service-datasource: the `primaryKeyReader` docblock now describes a producer that no longer exists, and the union read's `isPrimary` arm has no in-tree producer left

[os-zhuang]

Recorded by the engine lane while landing #10676 / #10998, and deliberately not repaired there: the file is the services lane's, and the three-signal union read that PR #11001 shipped is on that lane's own one-release clock. The engine change makes two statements in it false; carving the read is the services seat's decision, not the driver change's.

What moved

SqlDriver.introspectSchema() now emits the packages/spec spelling (primaryKey on every column, plus dialect and introspectedAt) and no longer emits isPrimary at all. Maintainer ruling, 2026-08-22 (live session, 「同意所有」 item 9 = 驱动侧对齐 spec 契约).

What is now stale in external-datasource-service.ts

The primaryKeyReader docblock, which is the one place this seam's reasoning is written down:

1. Its producer table is wrong. It reads:

   producer	per-column	table-level
   SqlDriver (+ SqliteWasmDriver, which extends it)	isPrimary	primaryKeys

   SqlDriver now spells the per-column signal primaryKey, so the table records the collision the union read exists to bridge as if it were still live.

2. Its #10997 note is out of date. It says the SQLite composite-key truncation "is upstream of this seam and is not repaired here". driver-sql: SQLite introspection reports only the FIRST column of a composite primary key (pk === 1 vs SQLite's 1,2,3… numbering) #10997 merged (PR fix(driver-sql): report every member of a SQLite composite primary key, in key order #11104): introspectPrimaryKeys now reports every member of a composite key in declared key order. The engine seat flagged this exact sentence as going stale when that PR merged.

3. The isPrimary arm of the union now has no in-tree producer. The read still takes col.primaryKey || col.isPrimary || table.primaryKeys.includes(col.name). Nothing in the tree writes isPrimary any more except two deliberately hand-built fixtures in external-introspection-seam.test.ts that stage a disagreement no live database can produce. That is the belt's clock coming due — collapsing it to the spec spelling is a decision for this lane.

What the engine PR did and did not touch in this package

Touched, minimally, and only because leaving it red blocks the merge (authorised at dispatch):

• src/__tests__/external-introspection-seam.test.ts — the producer-spelling case, which was written to redden on exactly this change. Its title, its two producer assertions (now primaryKey === true / isPrimary === undefined), and the docblock's tense. The staged-disagreement cases and the file's second describe are untouched.

Added (new file, no existing behaviour touched):

• src/__tests__/external-object-draft-real-introspection.test.ts — the pin the ruling requires: generateObjectDraft driven off a real SqlDriver.introspectSchema() result.

⛔ Not touched: primaryKeyReader itself, its docblock, and every consumer of it.

Filed unassigned as an observation. No behaviour is broken by any of the above — the union read keeps working; what is wrong is what a reader is told.

[os-zhuang]

Blocked-by: #10676

PM note from the domain:engine seat (session_01RfyXxZ2WPjcjhuXpiQQc3y), verifying this out_of_scope_findings entry and porting two things from #11125, which I filed in parallel by mistake and have now closed as a duplicate of this card.

① The Blocked-by: line above is the point of this comment. Everything described here becomes true only once the driver actually lands — PR #11124 is in review, not merged. That line is machine-readable in a comment exactly as in a body, so the unlock scan fires it when #10676 closes, i.e. the moment the driver change merges. Without it this card is a true observation about a future that has not happened yet, and a taker picking it up today would find the isPrimary arm still has a producer.

② ⛔ Do not collapse table.primaryKeys along with the dead arm. The union is three signals and only one of them is dying. table.primaryKeys remains live and independent — the driver still emits it, and after #10997 (PR #11104, merged) it is the carrier of composite keys in declared key order, which the per-column boolean cannot express. Collapsing the union to col.primaryKey alone would silently drop composite-key handling at this seam. Whatever this lane decides about the isPrimary arm, that is a separate signal with a separate reason to exist.

Also confirming from the engine side, since this card records it: the engine PR touched only the producer-spelling case in external-introspection-seam.test.ts plus that file's docblock tense, and added one new file. primaryKeyReader, its docblock, its union read, the two staged-disagreement cases and the second describe block were left untouched — deliberately, and it was an explicit boundary in the dispatch rather than an oversight.

---

Generated by Claude Code

[os-zhuang]

Triage: pm:queue, domain:services, Task. primaryKeyReader docblock describes a producer that no longer exists and the union's isPrimary arm has no in-tree producer left — establish-first: re-verify both claims on the merged ref before editing; if the arm truly has no producer, the removal follows the dead-code discipline (reference-surface check at review).

---

Generated by Claude Code