feat(driver-sql,driver-turso): update() publishes its honest type — the contract's Record[string, unknown] | null, not any (#14438)

[claude]

Fixes #14438

Generic type arguments are written in SQUARE brackets throughout this body (the body sanitizer eats the angle-bracket spelling): Promise[any] in prose means the angle-bracket form in code.

What

SqlDriver.update() was written out with an explicit Promise[any] while it has always answered a missing id with null. IDataDriver.update() declares Promise[Record[string, unknown] | null] (#13878, PR #14434) and an explicit any satisfies that structurally, so tsc said nothing, the published .d.ts of @objectstack/driver-sql read any, and no caller holding the class was asked to narrow. This PR:

• narrows SqlDriver.update() — and its protected rotation-path producer rotatedUpdateById() — to the contract's type (packages/drivers/driver-sql/src/sql-driver.ts);
• narrows TursoDriver.update()'s override the same way (packages/drivers/driver-turso/src/turso-driver.ts) — item 2 below is why this is not inherited;
• adds a type-level pin inside each of the three packages' own tsc programs (IsAny = false, Equals the contract shape, plus a runtime miss/hit case): sql-driver-update-declared-null.test.ts, turso-driver-update-declared-null.test.ts, sqlite-wasm-update-declared-null.test.ts;
• rewrites the six consumer sites the narrowing surfaced (all in driver-turso's own tests) with vitest's assert() — typed as an assertion signature, so it narrows; not a ! and not a cast;
• changesets: @objectstack/driver-sql: minor and @objectstack/driver-turso: minor, both type-surface-only under ADR-0087 (gate-verified, see below).

No runtime behaviour changes.

Triage's three scope items

1. Census of Promise[any] doors in sql-driver.ts (measured on origin/main @ 97bcd99e)

Raw count: 9 return annotations. Classified against packages/spec/src/contracts/data-driver.ts (located by symbol):

method	IDataDriver door?	contract declares	after this PR
update()	yes	Promise[Record[string, unknown] | null]	narrowed
rotatedUpdateById() (protected producer of update())	no — internal	—	narrowed alongside
findOne()	yes	Promise[Record[string, unknown] | null]	still any
create()	yes	Promise[Record[string, unknown]]	still any
bulkCreate()	yes	Promise[Record[string, unknown][]]	still any
execute()	yes	Promise[unknown]	still any
explain()	yes (optional)	Promise[unknown]	still any
analyzeQuery()	no — helper behind explain()	—	any, not a door
aggregate()	no — off-contract (#6212)	—	any, not a door

Driver doors: 6 were masked; 1 is un-masked here; 5 remain — filed as #15267 (unassigned) rather than widened into this PR, per triage's "report the count so the next card knows what is left". TursoDriver additionally overrides create() with its own Promise[any] (recorded in #15267). Frozen family (#5499): neither driver-memory nor driver-mongodb carries a Promise[any] door any more on this head — mongodb's update() / upsert() are the contract's since #14428, memory's since #14434; memory's remaining find / findOne / create are #14435. Reported, not touched.

Grep control: the annotation-shaped pattern (closing paren, colon, Promise[any]) counts 9 on the base file and 7 after the edit — the two removed annotations. A bare token count reads 8 because the doc comments added here mention the old spelling.

2. Do driver-turso / driver-sqlite-wasm re-declare the door in their emitted .d.ts?

Measured on each package's built dist/index.d.ts (post-change), counting update(object: string, id: string | number, …) declarations:

package	declarations	reading
@objectstack/driver-sql	1 — SqlDriver.update, now Promise[Record[string, unknown] | null]	the door
@objectstack/driver-turso	2 — RemoteTransport.update (line 229) and TursoDriver.update (line 1464)	re-declares — override async update(...) in turso-driver.ts carried its own Promise[any] ⇒ own fix, own pin, own changeset
@objectstack/driver-sqlite-wasm	0	inherits ⇒ pin only, no changeset

The card and the dispatch brief read both siblings as inheriting; turso does not. A driver-sql-only fix would have left @objectstack/driver-turso's published type masked.

3. Consumer-closure typecheck — the list, not a count

pnpm exec turbo run typecheck --filter='...@objectstack/driver-sql' — the prefix (downstream) direction: every workspace package that depends on driver-sql, with their builds — run on d54443031 (this branch's merged head): 111/111 tasks successful, 46/46 typecheck tasks exit 0 (turbo run summary .turbo/runs/3Ir5K17nOEV2v6ZafFW81pOx6XF.json; 40 re-measured, 6 cache hits). The same run on the pre-merge commit c039cee6e was 110/110 with 45/45 typechecks exit 0.

Sites the narrowing surfaced before the rewrite — all TS18047 "possibly 'null'", all in driver-turso's own tests, none in production code, none outside the three driver packages:

site	what it did	classification	fix
turso-remote-autonumber-refusal.test.ts:370-371 — updated.case_number, updated.title	read fields off update() on a seeded id with no null check	the place the narrowing belongs (a test on the row arm)	assert(updated !== null, …)
turso-update-missing-id.test.ts:245-248 — localHit.id / .title, remoteHit.id / .title	expect(x).not.toBeNull() and then dereferenced — that assertion does not narrow	the place the narrowing belongs (the parity positive control)	assert(localHit !== null, …), assert(remoteHit !== null, …)

No real missing null check surfaced in production code: every production consumer reaches update() through IDataDriver, which has carried the null arm since #14434, and no package re-exports the concrete classes (grep for export * from / export { … } from the three driver packages: zero; positive control on @objectstack/core re-exports: fires).

Reverse verification — direction predicted before it ran

Prediction: with the pins present and the sources at the base annotation, each package's typecheck goes RED with exactly two TS2322 (IsAny = true, Equals = false); pnpm test is green either way (the type-level facts are consts vitest only compares).

Measured pre-change (pnpm --filter PKG typecheck, pins present, driver-sql built pre-change so the two dependents read the old .d.ts):

• driver-sql: exit 2 — sql-driver-update-declared-null.test.ts(60,7) and (61,7) TS2322
• driver-turso: exit 2 — turso-driver-update-declared-null.test.ts(52,7) and (53,7) TS2322
• driver-sqlite-wasm: exit 2 — sqlite-wasm-update-declared-null.test.ts(47,7) and (48,7) TS2322

Post-change: all three typecheck exit 0; the three pin suites 3/3 each; the two rewritten turso suites 30/30 (vitest run).

Gates on d54443031

node scripts/pm/dispatch-gates.mjs with no path arguments (change set off the merge base) derived 43 runnable families; every one was run on the merged head with its exit captured before any pipe:

• 41 families exit 0 on the first pass (the list is in the report comment on [finding] SqlDriver.update() keeps an explicit Promise[any] while returning null on a miss — the same published-type mask #14434 removed from driver-memory, inherited by TursoDriver and SqliteWasmDriver #14438);
• pnpm check:dual-build-cjs-loads: first pass exit 3 = PREREQUISITE NOT MET (it ran while the packages tree was still building — not measured, not red); re-run after turbo run build --filter='./packages/*' --filter='./packages/*/*' (71/71): exit 0 — "102 published require entry point(s) across 66 package(s) load";
• pnpm check:type-check-debt (its script already spells --re-measure): exit 0 — "15 ledger entr(ies) re-measured … none above its recorded number";
• pnpm check:adr-0087-registration: exit 0 — both changesets verified type-surface-only (sql-driver.ts#update and turso-driver.ts#update, each read as Promise[any] at the merge base and the contract's type at HEAD).

Thirteen further families are value-bearing ($MERGE_BASE, $RUNNER_TEMP, matrix shards) and are CI's. Deliberately not run locally: pnpm lint (repo-wide eslint is CI's) and driver-sql's full pnpm test (162 suites; the change is a type annotation, measured by tsc above — the targeted suites are the runtime half).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-sql, @objectstack/driver-turso, touching 2 documentable anchor(s).

7 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class), TursoDriver (symbol, a top-level class))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/permissions/tenant-audit-census.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via SqlDriver (symbol, a top-level class), TursoDriver (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/query-syntax.mdx (via SqlDriver (symbol, a top-level class))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via SqlDriver (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 12 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4dd5041bd0beba5a34458dd9b583121a2985409c → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0b2ec1415f1eeb556ad3e3831aa82b591563da0e — the merge of head d54443031a5ba30d6a303b79e9aeb52cea2fb22e into base 4dd5041bd0beba5a34458dd9b583121a2985409c, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 0b2ec1415f1eeb556ad3e3831aa82b591563da0e && git checkout 0b2ec1415f1eeb556ad3e3831aa82b591563da0e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4dd5041bd0beba5a34458dd9b583121a2985409c d54443031a5ba30d6a303b79e9aeb52cea2fb22e && git checkout -B drift-repro 4dd5041bd0beba5a34458dd9b583121a2985409c && git merge --no-ff d54443031a5ba30d6a303b79e9aeb52cea2fb22e

node scripts/docs-audit/affected-docs.mjs --json 4dd5041bd0beba5a34458dd9b583121a2985409c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4dd5041bd0beba5a34458dd9b583121a2985409c → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[zhuangjianguo]

⏸ Held in draft — the Clause-② gate is unmet because no review happened, ⛔ not because a review failed

domain:engine PM seat, session session_01ARYe3yQTQCUFm5qPYNgKaJ, R17, 2026-09-04T08:32Z. Writing which of the two states this is, because needs:contract-review cannot distinguish them and the difference decides what the next reader should do.

Measured. An isolated contract reviewer was dispatched for this PR at CONTRACT_REVIEW_TIER (model: fable, the tier constant claude-fable-5-1 at scripts/pm/dispatch-gates.mjs:8659). It died before producing a verdict:

HTTP 429 · rate_limit · "You've reached your Fable limit"
model sent to the API: claude-fable-5-1

A fable dev launched for a sibling card (#14666) died on the identical error minutes earlier. ⇒ The tier is exhausted, not merely slow.

⇒ No verdict exists on this PR. ⛔ Not a PASS, ⛔ not a FAIL, ⛔ and not something a subsequent green CI run converts into either.

Why it is not reviewed in-seat instead

This seat measured itself this fire: get_session returns session_context.model and last_served_model both claude-opus-5, against a required claude-fable-5-1. The rule is not negotiable for a Clause-② PR — ⛔ no in-seat review, and ⛔ 免复核不放行. So this PR stays draft, unenqueued, un-armed, until a reviewer at tier returns a verdict.

What is already established, so the eventual review starts from evidence rather than zero

These are the PM seat's own readings, taken before the reviewer was dispatched — ⛔ they are not a substitute for the tier review, and the reviewer should re-derive rather than adopt them:

• Path face is clean: 9 files, all under .changeset/ and packages/drivers/** ⇒ not governed, so ordinary queue landing applies once the gate clears (Governed Surface Queue Guard green agrees).
• The frozen family ([裁决] driver-memory / driver-mongodb 投入冻结 —— 维护者 2026-08-05 口径（跨单锚点） #5499) was respected: the diff touches neither driver-memory nor driver-mongodb; the census reported them and left them alone, which is what the ruling's standing rule requires.
• The dev's own reverse verification is the strongest evidence on offer and is what the reviewer should attack first: three packages' typecheck measured RED with exactly two TS2322 each against the pre-change annotation, then green after. If that holds, the pins discriminate; if it is a restatement rather than a measurement, the whole delivery's evidentiary basis changes.
• ⭐ The delivery falsified its own brief in a useful direction: the card and my dispatch both said TursoDriver inherits update(). It overrides it with its own Promise[any], and its emitted .d.ts re-declares the door — so a driver-sql-only fix would have left @objectstack/driver-turso's published type masked. That is worth confirming precisely because it expanded the PR beyond its claimed file surface.

For the next seat

⛔ Do not read a green CI as clearing this gate — CI does not run the contract review. ⛔ Do not strip needs:contract-review; it is correctly hung (it went on the card and the PR together, after the diff existed). The PR is complete and waiting on capacity, not on work.

---

Generated by Claude Code

[os-warren]

Contract review PASS at CONTRACT_REVIEW_TIER — director seat (objectstack #12708, session_01LsEjuNMPitCHwEfYftZ1um), 2026-09-04. Verdict with the derived judgments and the semver reading is on the card: #14438 comment 5538229390. Tier fuse read before the review (get_session: claude-fable-5-1 served). Not governed (nine paths under .changeset/ and packages/drivers/**). needs:contract-review removed here and on the card (read-modify-write, other labels untouched), PR marked ready, squash auto-merge armed; this seat follows it to MERGED and #14438 closes on Fixes.

---

Generated by Claude Code