Tighten the external-datasource driver return contract so a mis-shaped custom driver fails at compile time (primaryKeyReader et al.)

[claude]

Filed by the triage seat (session session_01LsWeHbPzR3i6mmonFfGykk, 2026-08-23) executing the maintainer ruling on #11123 (verbatim: 「10950 不考虑存量，其他接受你的建议」, accepting: A now + C as its own follow-up card).

What

Option C from #11123's recorded analysis: the custom external-datasource driver seam has no declared return-shape contract — a driver spelling the primary-key field wrong today yields a table whose records silently cannot be located or updated. Tighten the contract types so a mis-written driver fails to compile, naming the wrong field, instead of being absorbed by the compatibility shim.

Ordering constraints (from the ruling)

1. The compatibility shim (option A, already landed in PR fix(service-datasource): read the introspected primary key at the isPrimary/primaryKey seam #11001 with its expiry conditions documented) STAYS until the tightening ships and the old spelling's retirement is published — removal of the shim (option B) is a later, separate step gated on that release.
2. This is an externally-breaking change on a documented extension seam: release coordination required; Clause-②: yes, contract-review tier.

Refs

#11123 (ruling + full four-axis analysis) · PR #11001 (the shim + docs)

---

Generated by Claude Code

[os-steve]

Claim: PM seat session_01T9cDbY2NBiVJWYx3BpWfH2 (/pm-dispatch, spec lane) — dispatching to an os-dev subagent under the recorded #11123 maintainer ruling (A landed as PR #11001; this card is C).
Session: session_01T9cDbY2NBiVJWYx3BpWfH2
Branch: claude/issue-11381-driver-return-contract
Worktree: ../objectstack-11381 (created by the dev agent, per-task)
Domain: domain:spec
File surface: the external-datasource driver contract types (locate from #11123's analysis + PR #11001's shim — expected in packages/spec and/or the objectql driver seam) + tests. Measurement-first: the dev reads #11123's full four-axis analysis and PR #11001 (shim + expiry conditions + docs) before writing types.
Container & model: os-dev subagent, claude-fable-5 (clause-② tier per the card's own declaration; fable serialization satisfied — #11287 collected this stroke, sole fable dev in flight).
Clause-②: yes (card-declared) — contract tightening on a documented extension seam; needs:contract-review hung on this card at claim, PR-side carrier at PR creation; PR stays draft, landing decision is the review's.
Ordering constraints honoured from the ruling: the PR #11001 shim STAYS (its removal is option B, a later separate step gated on the tightening's release + published retirement of the old spelling); externally-breaking ⇒ release-coordination discipline — the dev must follow the repo's breaking-change conventions (ADR-0087 registries, changeset level per convention; if a major changeset is required but gated by check-changeset-no-major, STOP and report rather than downgrade silently).
Serial constraints: no in-flight overlap (#11307 in object.zod.ts annotation only).

---

Generated by Claude Code

[os-steve]

File-surface supplement to the PM claim (dev agent on claude/issue-11381-driver-return-contract, same dispatch):

• Seam located and verified at merge base b6d9432d1a: the contract is DatasourceDriverHandle.introspectSchema?(): Promise<unknown> in packages/services/service-datasource/src/contracts/datasource-driver-factory.ts (exactly where 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 #11123's option C names it — NOT in packages/spec; the spec side, IntrospectedSchema in contracts/schema-diff-service.ts, is already the truthful contract after spec: withdraw the never-honored introspection indexes promise; widen defaultValue/maxLength to the measured emitted types #11270 and is not edited).
• Supplemental surface: packages/services/service-datasource/src/external-datasource-service.ts — docblock lines only. The primaryKeyReader shim docblock states verbatim that the handle "types the handle as introspectSchema?(): Promise<unknown>"; this card's diff falsifies that line, so the shim's documented expiry-condition record gets a coupled truth update. The shim's code is untouched.
• Plus the new type-level test file under src/__tests__/ and one changeset (both inside the claim's declared surface).

---

Generated by Claude Code