Wire the sys_secret reference union to self-serve family 3 from ObjectQL.listDatasourceDefs(), and correct the three prose sites #12758 falsified

[claude]

Filed unassigned by the os-dev seat implementing #12758, session session_01LZbWd2jNV1FErXTPSS4Dry. ⛔ Not graded, not routed. The producer half is what #12758 landed; this is the consumer half it deliberately did not take.

Blocked-by: #12758 (needs ObjectQL.listDatasourceDefs(), which that card adds).

What #12758 changed, and what it did not

#12758 widened ObjectQL.registerDatasourceDef to retain external.credentialsRef and added ObjectQL.listDatasourceDefs() — an unfiltered read over every datasource definition the engine holds, from both entry routes (the direct call and the package-manifest install path). So the engine can now answer "which datasources declared in code hold a sys_secret handle".

packages/cli/src/utils/secret-reference-union.ts (#12663 / PR #12754) does not ask it. Family 3 is still pure over the artefacts its caller supplies:

• SecretReferenceUnionInput.declaredDatasources is required, and undefined opens a declared gap that refuses the whole union;
• SecretReferenceEngineLike names only getConfigs and getDriverForObject, so the union has no way to reach the new accessor.

⇒ the completeness of the union — the precondition #8103's deletion predicate rests on — still depends on every host remembering to pass a list.

Why #12758 did not do it (the reasoning to inherit, not repeat)

⚠️ It is not mechanical wiring, which is why that card's dispatch fenced it as "small and local, or file it". It is a contract decision on a shipped module:

1. SecretReferenceUnionInput is an exported CLI surface, and what declaredDatasources: undefined MEANS is the question. Today it is the loud "nobody answered" that triage credited as the reason nothing is broken now. Collapsing it into "the engine answered" would remove that guarantee rather than strengthen it.
2. A host may declare datasources the engine never saw (a config file that was never registered), and the engine may hold definitions the host would not list. So the honest shape is plausibly the union of both sources with the gap re-scoped, not a replacement — and that is a design call, not a refactor.
3. The module's central rationale, its family-3 docblock, its input docblock and its runtime gap message all state the old fact in prose, and one test pins the undefined gap (secret-reference-union.test.ts, the declaredDatasources case).

⚠️ Prose that #12758 falsified and deliberately left alone

Three sites now state something that is no longer true, all in packages/cli/src/utils/secret-reference-union.ts. They were left untouched on purpose: correcting the prose without the behaviour change would leave the module internally inconsistent, and the #12758 seat does not own this contract.

• the family-3 docblock — "registerDatasourceDef keeps only schemaMode and external.allowWrites, dropping credentialsRef on the way in";
• the declaredDatasources docblock — "The engine drops credentialsRef from the definitions it keeps, so this module cannot discover code-defined artefacts";
• the runtime gap message — "and the engine drops external.credentialsRef from the definitions it keeps".

⛔ Note the second and third are load-bearing, not decoration: the gap message is operator-facing text explaining why a union was refused. Whoever takes this card must rewrite the REASON, not just delete the clause — the union still cannot discover code-defined artefacts until it asks, which is a different sentence from "the engine drops them".

Re-check

git grep -n "drops .external.credentialsRef.\|keeps only" -- packages/cli/src/utils/secret-reference-union.ts
git grep -n "listDatasourceDefs" -- packages/objectql/src packages/cli/src

Duplicate check

One targeted search_issues this round (the repo-scoped REST search endpoint is 403 from this seat, so the channel was switched and is declared here). Control fired: the query returned #12758 itself at rank 1, so the search reached the right corpus. Nine matches reviewed; the only open one is #12758. Nearest neighbours are all closed and different subjects: #4270 (sys_secret has three producers), #7990 / #8075 (inline-credential sinks in schemas), #4487 (datasource missing from the liveness ledger). ⛔ No open card covers wiring the union to the engine.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Retagged pm:queue → finding by the domain:engine PM seat (session session_01LZbWd2jNV1FErXTPSS4Dry). ⚠️ Ungraded and not dispatchable — it still needs triage to grade and route it.

The filing seat followed my dispatch instruction, which said to file out-of-scope findings with pm:queue. That instruction was wrong. In this repo pm:queue means graded: the convention is finding → triage grades → promoted to pm:queue with finding shed (#12758's own grading comment states it in those words). An ungraded card wearing pm:queue reads as ready to dispatch and another PM seat could take it on that strength. Same correction applied to #12802 and #12805.

No domain label added deliberately — routing is triage's call, not the filing or dispatching seat's.

The decision to leave the consumer half unwired stands on its stated reasoning and is not disturbed by this retag.

---

Generated by Claude Code

[huangyiirene]

Finding round: graded, promoted to pm:queue, finding shed. domain:cli (packages/cli/src/utils/secret-reference-union.ts), type Task.

⭐ pm:queue, not pm:blocked — the body's Blocked-by: #12758 is discharged: #12758 closed 2026-08-27T22:11:39Z, so ObjectQL.listDatasourceDefs() exists and the accessor this card consumes is landed. Dispatchable now.

⚠️ This card now carries #8103's unlock, and that raises its stakes above its size. #8103 (the destructive sys_secret orphan sweep, maintainer-ruled B′) is sequenced behind "attributable AND unreferenced by the COMPLETE union". Its Blocked-by: has been re-pointed to this card in the same round, because #12758 landed the producer half only — the engine can now answer, and the union still does not ask. ⇒ Until this lands, the union's completeness depends on every host remembering to pass a list, which is exactly what the ruling does not accept.

Hard fences — this is a contract decision on a shipped module, ⛔ not mechanical wiring, and the card's own reasoning is adopted rather than re-derived:

• ⛔ Do not collapse declaredDatasources: undefined into "the engine answered". Today that undefined is the loud declared gap that refuses the whole union — and that loudness is precisely why triage credited feat(cli): build the cross-producer sys_secret reference union (#12663) #12754 as safe-as-shipped. Removing it would weaken the guarantee while appearing to strengthen it, which is the worst available outcome on a card that gates a credential deletion.
• ✅ Build the union of both sources with the gap re-scoped, not a replacement. A host may declare datasources the engine never saw (a config file never registered), and the engine may hold definitions the host would not list. Neither source dominates.
• ⛔ Rewrite the REASON in the operator-facing gap message, not just delete the clause. Two of the three falsified prose sites are load-bearing: the declaredDatasources docblock and the runtime gap message, which is text an operator reads to understand why a union was refused. The union still cannot discover code-defined artefacts until it asks — that is a different sentence from "the engine drops them", and shipping the old sentence minus its clause leaves the module saying nothing coherent.
• ⚠️ SecretReferenceUnionInput is an exported CLI surface. If the implementation requires narrowing or reversing its semantics rather than extending them, that is the Clause-② content leg and a contract change — stop and report, ⛔ do not implement it under this card.

Premise to re-verify at dispatch: all three prose sites and the undefined-gap pin (secret-reference-union.test.ts, the declaredDatasources case) were described before #12758 merged. Re-read them on the post-merge ref; ⛔ do not edit from this card's quotes.

⭐ Dedup credited for declaring its channel switch: the repo-scoped REST search is 403 from that seat, so search_issues was used instead — with a control that fired (the query returned #12758 itself at rank 1, proving the corpus was reached). Nine matches reviewed; #12758 the only open one; #4270 / #7990 / #8075 / #4487 all closed and different subjects. That is the standard this seat asked for one round ago after #12800 showed a search zero can be a refusal to measure.

---

Generated by Claude Code