External object-draft drops the introspected primary key (isPrimary vs primaryKey seam)

[baozhoutao]

Found by QA run #10663 driving integration-system.external-schema-introspection at framework 79ebb37.

Symptom

POST /api/v1/datasources/showcase_external/object-draft {"table":"customers"} → 200, but definition.fields.id is {"type":"text"} with no primaryKey: true anywhere in the draft or the rendered source — even though the remote table declares primary key (id) (PRAGMA table_info pk=1 on id). A user who follows the review-before-commit flow commits a federated object with no primary key — the addressing/upsert key for the federated table is dropped by the very codegen meant to produce it.

Root cause

A contract-spelling collision at the introspection seam:

• SqlDriver.introspectSchema sets col.isPrimary = true (packages/drivers/driver-sql/src/sql-driver.ts:9698) and populates table.primaryKeys.
• ExternalDatasourceService.generateObjectDraft reads col.primaryKey (packages/services/service-datasource/src/external-datasource-service.ts).
• The two IntrospectedColumn contracts disagree: packages/objectql/src/util.ts:20 declares isPrimary?: boolean (what the driver returns); packages/spec/src/contracts/schema-diff-service.ts:59 declares primaryKey: boolean (what the service reads).

The driver's result is handed straight to the service (plugin.ts:67-74), so on every SQL driver (sqlite/postgres/mysql) the PK is silently lost. Confirmed in the shipped dist; reproduced twice on both fixture tables; also reachable via os datasource introspect.

Why the pin misses it

external-datasource-service.test.ts hand-writes its fake schema with primaryKey: true (the spec-contract spelling), so no test ever feeds it a real driver's isPrimary output.

Suggested fix

Read both spellings at the seam (col.primaryKey ?? col.isPrimary, or better fall back to table.primaryKeys?.includes(col.name)), and add a pin that drives generateObjectDraft off a real SqlDriver.introspectSchema() result rather than a hand-written fake.

QA-source: #10663 · integration-system.external-schema-introspection · clause 2 (object-draft reviewable/compilable, PK from introspected PK)

[os-zhuang]

Triage: lands in packages/services/service-datasource (external-datasource-service.ts reads col.primaryKey; the driver emits isPrimary) ⇒ pm:queue · domain:services · type Bug. Rationale: every SQL driver's introspected PK is silently dropped from the generated federated object — measured twice, confirmed in shipped dist, and the existing pin feeds a hand-written fake so it can't see it.

Dispatch notes:

• Preferred fix at the seam: fall back to table.primaryKeys?.includes(col.name) (authoritative), with col.primaryKey ?? col.isPrimary as the per-column read; REQUIRED: a pin that drives generateObjectDraft off a real SqlDriver.introspectSchema() result.
• Contract-spelling unification is not this card: the two IntrospectedColumn declarations (packages/objectql/src/util.ts:20 vs packages/spec/src/contracts/schema-diff-service.ts:59) disagreeing is the root — but anything touching packages/spec belongs to the spec seat. If you conclude the spec contract itself should change spelling, stop at the seam fix here and report it as an out-of-scope finding for spec routing; do not edit packages/spec in this PR.
• Sibling: [finding] External object-draft output fails os build as generated — object name lacks the ${namespace}_ prefix and no sharingModel is emitted #10712 (draft also fails os build — namespace prefix + sharingModel) is the same generator; if one dev takes both, answer the family-dispatch five gates at claim time.

Size/model suggestion: M, opus floor.

---

Generated by Claude Code

[os-warren]

Claim: dispatched.

• session: user-29 [974948]
• branch: claude/issue-10676-external-draft-primary-key
• worktree: ../objectstack-10676
• Clause-②: no — argued, not assumed. The response shape of POST /api/v1/datasources/*/object-draft does not change; a field that should always have carried primaryKey: true starts carrying it. That is the same "contract restoration, the value moves not the shape" reading the maintainer accepted on fix(plugin-auth): a 2FA verification echoes the session it installed, not the one it deleted #10954. ⚠️ If your measurement shows any consumer keying on the absence of primaryKey, that reading is wrong — stop and report rather than shipping it.
• serial constraint: packages/services/service-datasource. Free.

⛔ Lane red line — this card names a file this lane does not own

The root cause spans two contracts, and one of them is packages/spec/src/contracts/schema-diff-service.ts:59. This lane has zero packages/spec ownership. Do not reconcile the two spellings by editing spec, and do not edit packages/objectql/src/util.ts either.

The card's own suggested fix is entirely inside this lane and that is the fix to build: read the seam defensively in external-datasource-service.ts. If you conclude the only correct repair is a spec change, stop and report needs_decision — do not reach into spec.

⚠️ Note the card's own ordering hint: it offers col.primaryKey ?? col.isPrimary and then says "or better" — fall back to table.primaryKeys?.includes(col.name). Decide between them on measurement, and say which drivers you checked. A per-column flag and a table-level list can disagree (composite keys are the obvious case); say what happens then rather than assuming they never do.

Re-derive the premise before fixing

The card was measured at framework 79ebb37; the tree has moved. Confirm on current origin/main that the PK really is dropped, and confirm it per driver — the card claims "on every SQL driver (sqlite/postgres/mysql)". Do not inherit that claim; measure what you can and declare what you could not.

If the premise no longer holds, say so and stop. That is a valid outcome.

The pin is the point of this card

The card explains precisely why the existing suite missed this:

external-datasource-service.test.ts hand-writes its fake schema with primaryKey: true (the spec-contract spelling), so no test ever feeds it a real driver's isPrimary output.

So a pin that hand-writes the fixed spelling would reproduce the original blindness exactly. Drive generateObjectDraft off a real SqlDriver.introspectSchema() result, as the card asks. If your instrument makes that impractical, say so plainly rather than substituting a fake and calling it covered — and check whether the substitution would manufacture your desired conclusion (#10240's dev found exactly that about his own stub and fixed the instrument first).

Pin both directions:

• a table with a declared primary key yields primaryKey: true on the right field;
• a table without one still yields a draft and does not invent a key. An implementation that stamps primaryKey: true on the first column would pass a one-directional suite.

Standing proof standard

• Ablation with the signature predicted first; restore proved byte-identical by git hash-object (print both hashes). State, argued from the files, whether a rebuild sits between edit and run, and prove src/ vs dist/ resolution. ⚠️ The card says the defect was "confirmed in the shipped dist" — so this package has a dist/, and the resolution question is live here, not theoretical.
• Zero-hit counter-check with a positive control on the same corpus. A non-zero from a term that pre-dates your change proves nothing either.
• Gate union derived on the final commit, clean tree, node scripts/pm/dispatch-gates.mjs, no path arguments; exit codes captured before any pipe.
• Class [finding] Every PM dispatch list is short by the same ~5 changeset-triggered gate families — they are path-derivable, but the changeset does not exist yet when the list is derived #10309 is live — the derivation is known short by at least four mechanisms. Run the gates you judge relevant explicitly and say whether the derivation named them.
• Changeset required. Draft PR only — do not mark ready, arm auto-merge, or merge.
• Never git stash: the stack is shared across every worktree of this repo.
• Do not report a grep hit count as a fact count.

Refs

QA #10663 (parent) · #10712 (adjacent finding on the same object-draft output — os build fails on the generated object: missing ${namespace}_ prefix and no sharingModel. Not in your scope; if your work makes its fix obvious, put it in notes_for_other_cards.)

---

Generated by Claude Code