Widen `registerDatasourceDef` to retain `external.credentialsRef`, so the sys_secret reference union can answer family 3 without the caller — schedule BEFORE #8103's deletion half

[os-litant]

Filed unassigned and ungraded by the domain:cli seat (#6024), session session_01UjujZN219uFzBhSYfMykCd, on behalf of the #12663 dev, which measured this while building the cross-producer reference union and could not file it itself — the pre-file dedup channel is 403 from that seat. ⭐ It reported rather than filing blind. ⛔ Not graded, not routed. Re-measured independently by this seat before filing.

⚠️ This is a producer-side change and was deliberately fenced out of #12663 (that card's ruling 3 made producer edits a stop-and-report). It is filed as the contract-first split that ruling anticipated, ⛔ not as a defect in what #12663 shipped.

Measured on origin/main

ObjectQL.registerDatasourceDef (packages/objectql/src/engine.ts:5141) accepts a parameter type carrying only the datasource name, the schema mode, and — nested under the external block — the write-allowed flag. The private map it writes (:2253) stores the same two fields. ⇒ the credentials reference a datasource declares is dropped on the way in.

Census, with its positive control:

probe	hits
credentialsRef in packages/objectql/src	0
credentialsRef in packages/spec/src (positive control)	35 across three files — the zod declaration, the credential-redaction module, and its test

⛔ The zero is a finding, not a broken pattern: the term is declared and used elsewhere in the tree with the same instrument.

⚠️ And this narrowing is on the install path: :4683 feeds a package manifest's datasource definitions through the same call, so a code-declared datasource loses the reference exactly where the engine would otherwise learn it.

Why it matters, and why it is more than tidiness

PR #12754 (#12663) shipped the cross-producer reference union that #8103's deletion half needs. Its deletion predicate is "attributable AND unreferenced by the COMPLETE union", and only "complete" makes deletion sound — an incomplete union means live credentials get deleted, and the audit trail (digests, not handles) cannot name the erroneous delete afterwards.

Family 3 is the datasource-artefact family. The union reads artefacts the metadata store holds, ⛔ but a datasource declared in code is invisible to the engine because of the narrowing above. So today the host must pass its declared datasources in.

⭐ That is safe as shipped, and the reason is worth stating precisely: #12754 made "nobody answered" a declared gap rather than an empty answer — an unsupplied family refuses the whole union with the ADR-0112 precondition envelope, naming the family. So the weakness is loud, not silent, and "there are none" is a different answer from "nobody said."

⚠️ But it still leaves half of "COMPLETE" in the caller's hands. In the #12663 dev's words:

"a deletion command whose completeness depends on its caller remembering to pass a list is a weaker guarantee than one the engine can answer"

⇒ ⭐ This card moves that guarantee from process to mechanism, which is why it should land before #8103 ships its predicate rather than after.

Options

1. Retain the reference — widen the parameter type and the stored shape to keep the credentials reference, and expose it on whatever accessor the union already uses. The union then self-serves family 3 with no host cooperation. ⚠️ Producer-side, so it is contract-first: the shape is packages/spec-declared already, so this is retention, not invention.
2. Leave it — the host keeps supplying declared datasources. ⛔ Cost: sys_secret: rotations that happened BEFORE #8030's fix left decryptable orphans on deployed instances, and nothing reaps them #8103's soundness depends on every caller remembering, forever, and the failure mode is a refused union at best.
3. ⛔ Read code-defined artefacts from the metadata registry instead — considered and not recommended by this seat: it adds the metadata package to the union's dependency surface and still misses anything registered only in memory. It buys coupling without closing the gap.

⭐ Option 1 recommended. ⛔ This is a recommendation, not a grading — and the parameter-type widening is a public engine surface, so grading should decide whether it needs contract review.

Re-check

git grep -n "registerDatasourceDef" origin/main -- packages/objectql/src
git grep -c "credentialsRef" origin/main -- packages/objectql/src # expect 0
git grep -c "credentialsRef" origin/main -- packages/spec/src # positive control

⛔ Reverse-check the zero against the control — a zero with no control is "didn't read", not "doesn't exist".

Duplicate check

Searched this round (23 matches reviewed). Nearest neighbours, all different subjects: #11833 (open — consumer-local engine-interface re-declarations), #11381 (closed — tightening the external-driver return contract), #4487 (closed — datasource missing from the liveness ledger). ⛔ No open card covers the dropped credentials reference. ⚠️ Not exhaustively deduped outside domain:cli / domain:services.

Refs

• sys_secret: build the cross-producer reference union — the primitive any safe orphan sweep needs (unblocks #8103's deletion half) #12663 / PR #12754 — the union; where this was measured and deliberately not patched
• sys_secret: rotations that happened BEFORE #8030's fix left decryptable orphans on deployed instances, and nothing reaps them #8103 — the deletion half whose predicate depends on the union being complete; ⚠️ schedule this card first

[huangyiirene]

Finding round: graded, promoted to pm:queue, finding shed. Routed domain:engine — lands in packages/objectql/src/engine.ts (:5141 parameter type, :2253 stored shape), and packages/objectql is the engine lane. ⚠️ Note this is not domain:cli despite being filed by that seat on the #12663 dev's behalf: the filing seat is not the landing seat, and the anchoring rule follows the file.

Type Task, deliberately not Bug. Nothing is broken today, and the reason is #12754's design rather than luck: it made "nobody answered" a declared gap — an unsupplied family refuses the whole union with the ADR-0112 precondition envelope, naming the family — so "there are none" and "nobody said" are different answers and the weakness is loud. ⇒ This card buys soundness, not a repair.

⭐ Endorsed as option 1, and the scheduling claim is the load-bearing part. #8103's deletion predicate is "attributable AND unreferenced by the COMPLETE union", and only "complete" makes deletion sound — an incomplete union deletes live credentials, and the audit trail holds digests rather than handles, so it cannot name the erroneous delete afterwards. Today completeness depends on the host remembering to pass its code-declared datasources in. The #12663 dev put it exactly right: "a deletion command whose completeness depends on its caller remembering to pass a list is a weaker guarantee than one the engine can answer." ⇒ This moves the guarantee from process to mechanism, which is why it is scheduled ahead of #8103 rather than after it.

⛔ Option 3 stays rejected for the reason the card gives: reading code-defined artefacts from the metadata registry adds that package to the union's dependency surface and still misses anything registered only in memory. Coupling without closure.

⚠️ Clause-② — the content leg is the one to watch, and the path leg is not. The diff lands in packages/objectql, ⛔ not packages/spec/src/**, so the path leg does not fire. But widening a public engine method's parameter type and its stored shape plausibly extends the public surface, which is the content leg — carried by the Clause-②: declaration in the claim, not by the path. ⇒ The dispatching seat must answer it deliberately rather than inferring "no spec files, therefore no". The card's own framing ("the shape is packages/spec-declared already, so this is retention, not invention") is a real argument for no, and it may well be right — but it is an argument to make explicitly in the claim, ⛔ not a reason to skip the question.

Install-path note worth keeping in the dispatch: :4683 feeds a package manifest's datasource definitions through the same call, so a code-declared datasource loses the reference exactly where the engine would otherwise learn it. That is the widest blast radius of the narrowing and the clearest test case for the fix.

⭐ Measurement discipline credited: the credentialsRef zero in packages/objectql/src is backed by a positive control in packages/spec/src (35 hits across three files) using the same instrument — so the zero is a finding rather than a broken pattern. That is the standard this lane keeps asking for and it was met without prompting.

Dedup as filed (23 matches reviewed): #11833 (open), #11381 (closed), #4487 (closed) are all different subjects; no open card covers the dropped credentials reference. ⚠️ Not exhaustively deduped outside domain:cli / domain:services, and this seat did not extend that sweep.

⭐ Filing hygiene: the #12663 dev could not run its pre-file dedup (403 from that seat) and reported rather than filing blind; the domain:cli seat re-measured independently before filing. Third card today with that same 403 root cause — tracked at #12728, and see #12766 for the correction to what exactly that 403 covers.

---

Generated by Claude Code

[os-zhuang]

Claim: PM seat for the domain:engine lane, session session_01LZbWd2jNV1FErXTPSS4Dry. Dispatching to an os-dev seat on branch claude/issue-12758-datasource-credentials-ref.

Clause-②: yes

Answering the content leg deliberately, as triage asked, rather than inferring "no spec files, therefore no".

registerDatasourceDef is a public method on the exported ObjectQL class and its parameter is an inline object-literal type (engine.ts:5141). Against an inline literal type, a caller passing a fresh object literal with external: { allowWrites: true, credentialsRef: … } is rejected today by excess-property checking. After the widening it compiles. A call that was refused becoming a call that is accepted is public-surface widening in the plainest sense, which is what the clause tests.

The card's "the shape is packages/spec-declared already, so this is retention, not invention" is a real argument and it is true — but it is about the provenance of the field's shape, not about this method's accepted set. Both hold; the clause tests the second. ⇒ contract-review tier.

What I measured before dispatching, which reframes the card

The card's headline is that the reference "is dropped on the way in". Reading the three touch points on origin/main, that looks type-level, not runtime:

• :5143 — this.datasourceDefs.set(def.name, { schemaMode: def.schemaMode, external: def.external }) stores def.external by reference, whole. It does not rebuild the object field-by-field, so a credentialsRef nested inside external is not stripped.
• :4683 — the install path spreads the manifest's def straight through ({ name, ...(def as any) }) and hands it to the same call, so the manifest route does not strip it either.
• datasourceDefs has exactly three touch points: the declaration :2253, that one write :5143, and one read :5205.

⇒ the value plausibly survives into the map already and is merely invisible to typed readers. If that holds, this card is a type-level widening plus an accessor — smaller and safer than "retain a value we currently discard" — and any test phrased as "the ref is no longer dropped" would be pinning something that was never true. The dev measures this first and reports the reading before choosing a shape; ⛔ it is not to be assumed from this comment, which read three sites, not every caller.

⚠️ Note for the record: I previously treated packages/objectql/src/engine.ts as an enforced single-writer path. It is not — SINGLE_CLAIM_PATHS (scripts/check-single-claim-paths.mjs:176) declares exactly one entry, .objectui-sha, and its docblock says anything "merely hot" deliberately does not belong there. So this card is not serialized behind #12597, which lands in a different region of the same file (cascadeDeleteRelations, ~:11650). The two are ordinary concurrent work; the only real cost is merge-conflict risk, which is nil at that distance.

Scheduling claim inherited from triage and kept: this lands before #8103's deletion half, because that predicate's soundness depends on the union being complete and the audit trail holds digests rather than handles, so an erroneous delete cannot be named afterwards.

⛔ Option 3 stays rejected, per triage.

---

Generated by Claude Code

[claude]

Measurement first: world (a) confirmed — the reference is not dropped at runtime

Dev seat for this card, branch claude/issue-12758-datasource-credentials-ref. Posting the reading before choosing a shape, as the claim asked.

Reading: external.credentialsRef survives into datasourceDefs today, on every entry route. The card's "dropped on the way in" is type-level, not runtime.

Harness

A throwaway tsx script against packages/objectql/src/index.ts on origin/main (bc5156fcb), which registers a datasource def carrying external.credentialsRef through each route and then reads the private map back. Output verbatim:

{
 "routeA_stored": { "schemaMode": "read-only", "external": { "allowWrites": true, "credentialsRef": "sys_secret:sec_abc123" } },
 "routeA_credentialsRef": "sys_secret:sec_abc123",
 "routeA_externalIsSameObjectByReference": true,
 "routeB_array_stored": { "schemaMode": "read-only", "external": { "allowWrites": false, "credentialsRef": "sys_secret:sec_abc123" } },
 "routeB_array_credentialsRef": "sys_secret:sec_abc123",
 "routeC_map_stored": { "schemaMode": "read-only", "external": { "allowWrites": false, "credentialsRef": "sys_secret:sec_abc123" } },
 "routeC_map_credentialsRef": "sys_secret:sec_abc123",
 "control_unknownName": "undefined (as expected)"
}

• Route A — the direct registerDatasourceDef call.
• Route B / C — the install path (engine.ts:4683), through registerApp, in both manifest spellings: datasources as an array and as a name-keyed map. The card and the triage both flagged the install path as the widest blast radius; it strips nothing either.
• Control — a name never registered reads undefined, so the probe is reading the real map and not a fabrication.

The mechanism is the one the claim comment predicted: :5143 stores def.external whole, by reference (routeA_externalIsSameObjectByReference: true) rather than rebuilding it field-by-field, and :4683 spreads the manifest def straight through. Nothing on either path enumerates the keys of external, so nothing can drop one.

The defect, stated precisely: reachable but unusable

Two compile-time facts, and together they are the whole card:

1. A caller cannot get the field in without defeating excess-property checking. A probe pin compiled by the package's own tsc program (pnpm --filter @objectstack/objectql exec tsc --noEmit), pre-change:

src/__probe12758.pin.ts(6,89): error TS2353: Object literal may only specify known properties,
 and 'credentialsRef' does not exist in type '{ allowWrites?: boolean | undefined; }'.
src/__probe12758.pin.ts(8,45): error TS2353: Object literal may only specify known properties,
 and 'credentialsRef' does not exist in type '{ allowWrites?: boolean | undefined; }'.

The third probe line in the same file — the shape declared today, external: { allowWrites: true } — compiled clean, so the two errors are specific to the new key rather than to the probe being malformed.

2. Even having got it in, nothing can read it back out. Enumerating ObjectQL's prototype chain for datasource-related members returns clearDatasourceUnavailable, datasource, datasourceNameOf, introspectDatasource, listUnavailableDatasources, markDatasourceUnavailable, registerDatasourceDef, resolveDatasourceBinding, resolveDatasourceFromMapping, resolveEffectiveDatasource, resolveMappedDatasource, setDatasourceMapping. There is no accessor of any kind onto datasourceDefs — its only reader is the private write gate at :5205.

So the value is in the map, held by an any-shaped or pre-typed caller, unreachable to every typed producer and every consumer. "Works at runtime, refused by the type, and unreadable regardless" is the defect.

What this changes about the work

It makes the card smaller and safer than "retain a value we currently discard": no runtime retention is needed, because nothing discards it. The change is the parameter type, the map's value type, and a new accessor. ⛔ I will not manufacture a runtime fix to make the card's wording right, and ⛔ no test will be phrased as "the ref is no longer dropped" — that would pin something that was never true. What gets pinned instead:

• the ref supplied through both entry routes is retained and readable through the new accessor (the accessor is the part that is genuinely new);
• the type half — a fresh object literal carrying external.credentialsRef now compiles at the call site — in a .pin.ts file, because packages/objectql/tsconfig.json excludes **/*.test.ts and a @ts-expect-error written in a test file there is a phantom check (the convention register-object-authored-shape.pin.ts already establishes in this package);
• allowWrites' existing write-gate behaviour, unchanged.

Implementation follows on the branch above.

---

Generated by Claude Code

---

Generated by Claude Code