Every wizard-created datasource with a password is badged invalid today — the service writes external.credentialsRef onto rows whose schemaMode defaults to 'managed', which the schema refuses

Split out of #8081 scope item 5 by the domain:services PM seat. ⛔ Not graded by me; no domain:* label — the fix is in packages/spec (⇒ likely domain:spec + fable per the standing contract-change clause), but the routing is triage's call.

Promoted out of #8081's proposal surface because the measurement changed its nature: it was carried there as a theoretical inconsistency, and it is neither theoretical nor an edge case.

Measured — it is the default happy path

POST /api/v1/datasources {name:'good_pg', driver:'postgres',
                          config:{host,database,username}, secret:'hunter2'}   → 201
persisted:  {name:'good_pg', config:{…}, origin:'runtime',
             external:{credentialsRef:'sys_secret:bound'}}        // no schemaMode

computeMetadataDiagnostics('datasource', <that row>)
  → {valid:false, errors:[{path:'external',
      message:"'external' settings only apply when schemaMode != 'managed'."}]}

DatasourceSchema.schemaMode defaults to 'managed' (datasource.zod.ts:502), and createDatasource writes external.credentialsRef without consulting schemaMode. So every wizard-created datasource that has a password — the ordinary way an operator adds one — is badged _diagnostics.valid:false in the Studio metadata list right now, and PUT /meta on that row answers 422 for a shape the service itself wrote.

Blast radius, measured: it does not break connect (the connect path never re-parses) and does not break the datasource-admin routes. The damage is the invalid badge plus the PUT /meta 422. So this is a correctness-of-the-contract defect, not an outage — which is why it survived unnoticed.

⚠️ The obvious fix is wider than the problem

#8081 recorded the dev recommendation as "A — allow external.credentialsRef, or a top-level ref, on managed". The implementing dev then corrected that framing, and I think the correction is right:

"Allow external on managed" is wider than the problem. The refinement's intent is sound — federation settings genuinely do not apply to a managed datasource — and blanket-allowing external discards a real check to unblock one key.

The narrow shape: allow credentialsRef (and only it) on managed; keep refusing the federation keys. That preserves the refinement's meaning and matches what the service already writes. ⛔ "A as written" would trade a live check away for free.

The alternative direction — make createDatasource stop writing external.credentialsRef on managed rows and put the ref somewhere else — is not obviously worse, but it moves a shipped persisted shape and every reader of it. Whoever takes this should weigh both rather than inherit the first.

Sequencing — ⚠️ this blocks #8081's migration story

#8081 item 3's migration writes external.credentialsRef onto existing rows. Running it before this is settled would convert every affected managed datasource from "invalid because it holds cleartext" to "invalid because it holds a credentialsRef" — a migration whose entire output lands in the shape that fails re-parse. Settle this first.

Constraints

⛔ The packages/spec change is a contract change; it does not land from the services lane.
⛔ Do not "fix" it by removing the schemaMode != 'managed' refinement outright — the federation half of it is doing real work.
The connect path never re-parses, so a fix must not assume re-parse is the enforcement point.

Provenance: #8081 dev report (comment 5269923121, §⑤) and my ACCEPT receipt (#8081 comment 5270102954). Related: #7990, #8078, #8081.

Triage: escalated to needs-user-decision, routed domain:spec (the candidate fix changes DatasourceSchema's accept/reject behavior ⇒ semantic lane; if it queues after the ruling, dispatch is claude-fable-5 mandatory per the standing contract clause). Type Bug — the platform contradicts itself today: the service writes a shape the schema refuses, so every wizard-created datasource with a password is badged invalid and PUT /meta answers 422 on the service's own output.

This does not qualify for triage auto-adjudication: whichever way it resolves either widens a published schema's accept set (contract change ⇒ human floor) or moves a shipped persisted shape (migration-adjacent ⇒ human floor). The decision blocks #8155 (the credential migration story), so it carries an open downstream dependency.

The question: managed datasources need a home for credentialsRef. Two candidate shapes:

Option 1 (narrow spec allowance): allow external.credentialsRef — and only it — on schemaMode: 'managed'; keep refusing all federation keys. ~1 refinement change in datasource.zod.ts; matches what createDatasource already writes and what the connect path already honors.
Option 2 (service re-homes the ref): createDatasource stops writing external.credentialsRef on managed rows and stores the ref elsewhere. No accept-set change, but it moves a shipped persisted shape and every reader of it, and needs its own migration for existing rows.
⛔ Explicitly rejected upstream by the implementing dev (endorsed): "A as written" — blanket-allowing external on managed — trades a live federation check away for free.

Four-prong analysis:

Platform long-term coherence: Option 1 makes declared = enforced with the smallest possible widening and preserves the refinement's real intent (federation settings still refused on managed). Option 2 preserves the schema's purity at the cost of a shape migration plus reader churn — more moving parts, same end state.
Measured business pull: the default happy path is broken today — every wizard-created datasource with a password is badged valid:false (measured, POST → 201 → _diagnostics.valid:false). Not speculative.
AI-agent error-resistance: Option 1 keeps the loud refusal for federation keys (closed allowance of exactly one key), so an AI author still cannot smuggle federation config onto a managed row. Option 2 introduces a second, non-obvious home for the ref that every future reader/writer must know about — more opportunity for silent divergence.
Startup scope discipline: Option 1 is a one-line-order change that unblocks the migration story; Option 2 is a mini-programme. No new capability is declared either way.

Recommendation: Option 1 (narrow allowance, credentialsRef only), with an acceptance pin that a managed row carrying any other external.* key is still refused, plus a re-parse round-trip test on the exact shape createDatasource writes.

Re-check commands for premise freshness: git log --oneline -5 origin/main -- packages/spec/src/system/datasource.zod.ts (refinement unchanged?) · re-run the card's computeMetadataDiagnostics('datasource', …) measurement.

Blocked downstream: #8155 (Blocked-by: #8153).

Generated by Claude Code

Maintainer ruling — narrow allow

Ruled by the maintainer in a live PM session, 2026-08-13 (session session_015XyMgCSMGGn9oSwbQEeWYg), verbatim: 「其他全部接受你的建议。」 — accepting the narrow shape this card itself argued for.

Ruling: allow external.credentialsRef (and only it) on schemaMode: 'managed'; keep refusing every federation key on managed. ⛔ "A as written" (blanket-allow external on managed) is rejected — it trades a live check away for free. The alternative (move the ref out of external) is rejected as relocating a shipped persisted shape and all its readers for no semantic gain.

Implementation notes for dispatch:

packages/spec accept-set change ⇒ model: claude-fable-5 mandatory (standing contract-change clause), domain:spec lane.
Acceptance: the measured happy path (wizard-created datasource with a password) parses valid; a managed row with any federation key still refuses with the existing guidance; connect path unchanged (it never re-parses — do not make re-parse the enforcement point).
Sequencing: [services half of #7990] Close the datasource/connector credential write/read paths: scrub getDatasource().config, fix the false "credential-stripped" claim, and write the stored-cleartext-rows migration story #8081 item 3's migration stays parked until this lands — its output must land in a shape that re-parses valid.

Label swap: needs-user-decision → pm:queue.

Generated by Claude Code

feat(spec): allow external.credentialsRef (and only it) on schemaMode…

feat(objectql): retain and expose external.credentialsRef on datasour…

test(spec): the first data/ file group's test titles state each cited…

Navigation Menu

Repository navigation

Every wizard-created datasource with a password is badged invalid today — the service writes external.credentialsRef onto rows whose schemaMode defaults to 'managed', which the schema refuses #8153

Measured — it is the default happy path

⚠️ The obvious fix is wider than the problem

Sequencing — ⚠️ this blocks #8081's migration story

Constraints

Maintainer ruling — narrow allow

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Every wizard-created datasource with a password is badged invalid today — the service writes external.credentialsRef onto rows whose schemaMode defaults to 'managed', which the schema refuses #8153

Description

Measured — it is the default happy path

⚠️ The obvious fix is wider than the problem

Sequencing — ⚠️ this blocks #8081's migration story

Constraints

Activity

hotlong commented on Aug 12, 2026

hotlong commented on Aug 13, 2026

Maintainer ruling — narrow allow

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions