feat(driver-turso): the remote transport issues auto_number values from the shared persistent sequence (#21113)

[objectstack-fleet]

Fixes #21113
Clause-②: yes (widening)

Patch round 1 (review 5930100091)

The one blocking item was @objectstack/driver-sql at patch beside a root type re-export (AutoNumberReservation). Branch taken: the re-export is dropped and the two re-seed overrides in turso-driver.ts are typed Parameters indexed over SqlDriver's autoNumberValueExists (its second parameter) and resyncSequenceToDataMax (its first) — the premise (the protected member's parameter type is reachable from the subclass without the export) measured true: driver-sql typecheck exit 0, driver-turso typecheck exit 0, no structural copy. driver-sql's export list is byte-identical to main, so patch stands; the changeset sentence that named the export now reads "No export is added". origin/main merged again (fde553c50, which also lands the agentGuidance: false opt-out of #21151); re-run on the merged tree: closure build exit 0, both typechecks exit 0, driver-turso 82 passed (82) files / 2218 passed | 33 skipped (83 files / 2219 with the throwaway probe present), driver-sql autonumber suites 66 passed | 2 skipped, and the changeset, ADR-0087, nul-bytes and published-files gates all exit 0. Finding (b) was measured on the remote face as the review asked and reproduces; it is in the round-1 report on #21113 for the seat to file.

What this does

Disposition A of the remote-autonumber question, executed: a create, bulkCreate or upsert on the Turso REMOTE transport that leaves an auto_number slot empty now gets a generated value, issued atomically in the database from the same persistent _objectstack_sequences counter the local and embedded-replica faces draw from. supports.autonumber stays true on the remote face and is now honoured. The NOT_IMPLEMENTED / 501 refusal is gone; its suite is converted into the generation suite.

Why now: the appetite door the refusal left shut (「for want of measured demand」) was met by objectstack-ai/cloud#2531 — POST /api/v1/data/crm_account answers 501 on a hosted tenant, whose database is on this transport, so no object declaring an auto_number field could get a new record on the hosted product. That card carries the cloud half, Blocked-by: this one.

How, and what is shared rather than copied

Where the slots are filled. On the driver, one layer above the statement builder, exactly where the refusal was raised: RemoteTransport.create(object, data) takes no schema and caches none (pinned), while TursoDriver holds autoNumberFields from remote schema sync. The remote create / upsert / bulkCreate call the inherited SqlDriver.fillAutoNumberFields on a copy of the caller's row, then hand the filled row to the transport, which builds the same INSERT it built for a caller-supplied number.

One semantics (H3). The rules that decide WHICH counter a value is drawn from and WHERE a cold counter starts are SqlDriver's and are called, never copied. Lifted into protected members in the sequence region of sql-driver.ts (:7532–:8190 on this head; nothing else in that file): resolveSequenceTenantId (replaces three inline copies), defineSequencesTable (the table's one definition — the remote face compiles it to text with the connection-less Knex it already holds and sends that), maxAutonumberCounter + escapeLikePrefix (the bootstrap reading, suffix included, split from the Knex statement that fetches the values), sequencesTableName, autoNumberCollisionRetries. The two re-seed overrides take their parameter types through Parameters indexed over SqlDriver's protected members, so driver-sql's export list is unchanged. The format rendering and precedence were already shared (resolveAutonumberFormat at registration, renderAutonumber / missingFieldValues in fillAutoNumberFields), and are reached by calling that method.

What is this face's own: how the counter moves (H2). TursoDriver.getNextSequenceValue routes by transport. Local and replica keep the inherited Knex transaction. Remote moves the counter in ONE statement:

warm:  UPDATE _objectstack_sequences SET last_value = last_value + 1 WHERE key_hash = ? RETURNING last_value
cold:  scan the data table's MAX in JS by the shared reading, then
       INSERT … VALUES (…, max + 1) ON CONFLICT (key_hash) DO UPDATE SET last_value = last_value + 1 RETURNING last_value

Each is a single SQLite statement serialised by the database's write lock across connections and processes; no in-process state takes part (remoteSequencesTableEnsured remembers only that the TABLE exists). Two cold writers both scan and both INSERT; one wins the row, the other's ON CONFLICT arm increments it.

H2 falsified on one point, reported rather than followed: the PM expected the seed folded into the statement as a SQL MAX(…). It is not, because the bootstrap reading strips a declared suffix and reads the digit run after the prefix (readAutonumberCounter, #6468), which a dialect expression would be a second copy of — the exact collision H3 forbids. A Hrana batch was not needed either: the JS reading has to sit between the scan and the insert, and both insert arms are atomic on their own.

The legs (H4). create, bulkCreate and upsert all generate. bulkCreate on the remote face now runs through the driver's own create per row, which is what RemoteTransport.bulkCreate always did underneath (it loops the transport's create: one INSERT and one read-back per row, never one statement — so the old comment's 「all-or-nothing on this transport too」 was not true, and the statements sent and the mid-batch failure state are unchanged). upsert reserves before the statement, as SqlDriver.upsert does, and names the autonumber columns to the transport as insert-only (RemoteTransport.upsert gains an optional fifth argument, schema-free: WHICH columns, not WHY), so a merge keeps the number already in the row (#7011) and the insert leg — the one #7099 recorded as writing NULL — gets its number. The reservation a merge does not use is a gap, never a renumbering, the local face's rule byte for byte (pinned: seeded 42, merge, next create is 44). #7099's post-write warning is removed with the leg it reported.

Legacy shape and collision re-seed (H5), decided from the code. The pre-key_hash table: SqlDriver.ensureSequencesKeyHashShape rebuilds it through a live Knex connection, which this face has none of, and a raw-SQL rewrite would be a second copy of a migration; keying by the legacy (object, tenant_id, field) rule would be a second keying rule beside the shared one. So it is refused, DATABASE_ERROR / 500 with the remedy in the message (open the database once through the local or replica face), not cached as a verdict, caller-supplied numbers still written. It cannot arise on a database this face created. The #5495 re-seed is needed on this face — the bypass paths that create a stale counter (isSystem seed replay, preserveAudit import) are exactly the seed/import paths, and bulkCreate is their common door — and it is carried: autoNumberValueExists and resyncSequenceToDataMax are overridden for the remote face (the forward-only move is one atomic UPDATE guarded by last_value being below the observed MAX), and collidingAutoNumberReservations is the inherited discriminator, so a duplicate on a value the caller typed stays the caller's 409 (pinned).

H6. Clause-②: yes (widening) holds as measured: a create refused 501 today is accepted; no spec key moves; no export is added (the six lifted members are protected, and the overrides are typed through indexed types rather than a root re-export); RemoteTransport.upsert gains an optional parameter. Changeset: @objectstack/driver-turso minor, @objectstack/driver-sql patch.

Tests

Head for every number below: 52ab7ad76 (the merge of origin/main 1bd14c984), unless stated.

• Converted, not deleted: turso-remote-autonumber-refusal.test.ts → turso-remote-autonumber-generation.test.ts (git mv then rewritten; git's rename detection does not fire at this similarity, so the diff reads D+A — the three-face structure, the controls, the update() / plain-object / caller-supplied cases and the layer pins are the refusal suite's own). 27 cases: generation on every leg incl. the Turso remote:带 id/conflictKeys 但没匹配上的 upsert 仍会静默写入 NULL 自增号(#6944 拒绝闸门覆盖不到的那条腿) #7099 leg; caller-supplied numbers, merge, update, plain object untouched; the two-face block (local Knex face and remote native-libsql face on ONE file: numbers interleave 1,2,3,4 on one key_hash row equal to the local face's sequenceKeyHash; per-tenant buckets; the 自增号格式带「序号槽之后的后缀」时,播种解析读错数字段:引擎读成年份(2026),driver-sql 读成拼接串(12026),两侧还互不一致 #6468 suffix seed read as 5 not 52026; the {field} refusal is the same sentence on both faces and writes nothing); the Autonumber counter neither syncs to MAX(existing) per tenant nor re-checks on collision — warm-DB creates 409 in bursts, each failure burning a number (25 retries observed) #5495 re-seed on create and bulkCreate; the caller's own 409; the legacy-shape refusal with code + status; local and replica still issue; RemoteTransport.prototype still has no autonumber member and create.length === 2; supports.autonumber === true.
• The two boundary pins rewritten, not deleted (turso-autonumber-resync.test.ts, turso-autonumber-batch-resync.test.ts): the transport-surface probe verbatim, and the refusal half replaced by generation + re-seed on the remote face.
• Cross-process pin turso-remote-autonumber-concurrency.test.ts: two child processes (tsx over the package source, as packages/spec's process-boundary pins do; tsx added as a devDependency of driver-turso), each with its own @libsql/client native file: connection to one database file and its own remote-mode TursoDriver, released together by a file barrier; 2 × 200 creates per round → 400 distinct, exactly 1..400, strictly increasing per writer, no failed write, the table and the counter row agreeing. Those are the hard pins, asserted on every round. The overlap EVIDENCE (the writer changes at least twice in the global order) ends the loop on the first round that shows it; after three rounds without one the test is skipped with a note that says NOT MEASURED — because whether two processes overlap is the scheduler's decision, measured here once as a strictly serial run (1 change) under another seat's full-package run on this shared box. Final-head runs: 3/3 green standalone, measuring 400 writes · 400 distinct with 31, 21 and 23 writer changes; inside the full package run, 9. Said plainly: no sqld runs in this container; what is measured is two processes on libSQL's engine under its write lock, not an HTTP server.
• Driver-conformance ledger (lane commitment): identical before and after — 50 covered cell(s), 0 in the DEBT ledger, 0 exempt; the matrix has no autonumber cell for any driver, so none moved.

Runs, all under scripts/pm/os-verify-lock.sh after the merge: pnpm --filter '@objectstack/driver-turso^...' build exit 0 · driver-sql typecheck exit 0 · driver-turso typecheck exit 0 · driver-turso vitest run: 82 passed (82) files, 2218 passed | 33 skipped (2251) · driver-sql vitest run in two halves of 108 files: 103 passed | 5 skipped, 1389 passed | 100 skipped; 102 passed | 6 skipped, 1914 passed | 88 skipped (every file; the autonumber-named nine also run on their own: 66 passed | 2 skipped).

Reverse verification (predicted before each run; mutation and restore proven on disk by scripts/ablation-replace.mjs, blob == HEAD and git diff HEAD empty after each leg)

1. Merge-set exclusion dropped (RemoteTransport.upsert ignores insertOnlyColumns). Predicted: exactly the two [#7011] merge pins red. Measured: 2 failed | 25 passed, both merge pins, expected 'CASE-00043' to be 'CASE-00042' and expected 'CASE-00099' to be 'CASE-00042' — the renumbering the exclusion exists to prevent.
2. Warm path made non-atomic (SELECT last_value, then UPDATE to +1). Predicted: the distinct count in the concurrency pin drops below N; the stub-backed generation suite stays green. Measured — direction reversed, kept rather than tidied: the generation suite stayed green (27 passed) as predicted, but the concurrency pin went red on its 「no write failed」 assertion, not on the distinct count: the fixture's tenant-scoped unique index refused the second row carrying a duplicated number, and the forward-only re-seed could not outrun a writer that kept reading the same stale value, so writes failed with SQLITE_CONSTRAINT: UNIQUE constraint failed: index 'uniq_crm_case_organization_id_case_number' — 2 of 3 runs with no gap between the two statements, 3 of 3 with a 1 ms gap (the order of one HTTP round trip). On a declared-unique column a counter that hands out a number twice surfaces as refused writes before duplicate rows; recorded in the pin's docblock.
3. Shared bootstrap reading zeroed in driver-sql (maxAutonumberCounter, reached through dist/: rebuilt, ablation-dist-preflight present in 2 built files, exit 0). Predicted: the bootstrap and re-seed pins red on BOTH faces. Measured: 10 failed | 25 passed across the three suites — generation: explicit-then-continues-above, merge-then-44, 自增号格式带「序号槽之后的后缀」时,播种解析读错数字段:引擎读成年份(2026),driver-sql 读成拼接串(12026),两侧还互不一致 #6468 suffix, re-seed create, re-seed bulkCreate; resync: LOCAL and REMOTE re-seed; batch-resync: LOCAL bulkCreate, LOCAL upsert, REMOTE batch. Restore: rebuilt, preflight --absent exit 0. A first attempt of this ablation was a null operation (the tool refused because the replacement restated the anchor; the preflight correctly reported the marker absent and that green run is void) and was redone with a different anchor.

Gates

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on 52ab7ad76 (no paths; 73 commands). Run on the final tree (2c9d2985a, every file identical to the commit): the 73 derived commands — 72 exited 0, incl. check:driver-conformance, check:query-options-erasure (holds: 67 unswept non-test sites, none new — my first head had added one as any on a find() query in the new concurrency pin, retyped as DriverQuery), check:test-source-alias, check:undeclared-dep-imports, check:doc-authoring, check:nul-bytes, check:lean-entry-closure (measured after building @objectstack/objectql: 15 packages, 201/199 modules, admitted set held), check:type-check-debt (399.5 s re-measure, none above record), check:pm-skill-ratchet (0 with AGENTS.md at the merge-base blob — the turbo 2.11.5 agent-rules block, #21146, had rewritten it once in this worktree and is restored). check:dts-closure exited 1 on its first final-tree run naming plugin-email and plugin-security (neither in this diff nor in its closure) with dist/index.d.ts absent at that moment; a forced rebuild of the two and a rerun exits 0 (71 packages, 167/167 declarations) — concurrent turbo activity in the same tree, not this change. NOT MEASURED (1): check:dual-build-cjs-loads exits 3 PREREQUISITE NOT MET locally (78 packages without dist/ in this worktree) — CI's. dispatch-gates --ran: 73 derived, 72 run, 1 NOT-MEASURED declared, 0 UNRUN (exit 0). Seven further families (agent-test-spelling, docs-audit-scope, pm-governed-merges, pm-governed-prose, pm-skill-id-lint, pm-skill-ratchet, required-contexts) were derived only while the turbo block sat in AGENTS.md; they were run anyway and all exit 0. The derivation itself still lists what no local run covers: the 53 artifact-roster families, 11 wide-population families, 6 path-scheduled CI jobs and the type-check lanes.

pnpm lint narrowed, as a measurement: ① population = the lint script's own eslint . --no-inline-config, under one eslint.config.mjs; ② --format json on the changed source files: 9 files, 0 errors, 0 warnings; ③ invariance: the config enables no type-aware linting for any file (eslint.config.mjs states it, no parserOptions.project), so this diff moves no untouched file's verdict.

Acceptance notes

• Both faces: SQLite's LIKE has no escape character unless ESCAPE is declared, and the shared escapeLikePrefix writes backslashes. The remote statement declares ESCAPE '\'; the local Knex builder in scanMaxNumericTail does not (knex emits like ? with the escaped binding and no ESCAPE, measured on the sqlite and pg dialects), so on the local SQLite faces a format whose prefix contains _ or % seeds from 0 (measured: SO\_% matches nothing on SQLite without ESCAPE). Pre-existing, outside this card's class; filed in the report as a finding, not fixed here.
• RemoteTransport.upsert with caller conflictKeys leaves id in the merge set ("id" = excluded."id") — the drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 shape the local face closed. Not touched; noted for the lane.
• The README's remote refusal table loses its 「Record numbers」 row; content/docs/** carries no statement of the remote refusal (grepped).

维护者速读(草稿)

• 改了什么: Turso 远程传输面上,create / bulkCreate / upsert 留空的 auto_number 字段现在会生成编号,编号来自与本地面相同的持久计数表,在数据库里原子递增;原先的 501 拒绝改为生成。
• 为什么改: 托管产品的租户库全部走远程传输,任何声明了 auto_number 字段的对象都无法新建记录(cloud#2531 实测:HotCRM 建客户答 501)。这正是 TursoDriver remote 面根本不生成自增号:RemoteTransport.create 自建 INSERT,auto_number 只是个 TEXT 列 #6944 当初留下的「等实测需求」的门,现在门开了。
• 风险与代价(含回滚): 多进程并发只靠数据库写锁串行,无进程内计数;两个面共用一张计数表、一套键规则,已在同一数据库文件上对拍。遗留形状的计数表在远程面上明确拒绝、不迁移。回滚即还原本 PR;已生成的编号留在数据里,计数表形状与本地面一致。
• 席位意见: (留空)
• 你要做的: 批准后 cloud#2531 推进 pin 并在托管环境复验建客户。

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-sql, @objectstack/driver-turso, touching 38 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

21 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 14 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 fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 036addac90cebbce841dcd1c32c9e531c3be3620 — the merge of head 5d09309a65a19d50631d0a349e0e002b1129d6b8 into base fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a, 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 036addac90cebbce841dcd1c32c9e531c3be3620 && git checkout 036addac90cebbce841dcd1c32c9e531c3be3620
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a 5d09309a65a19d50631d0a349e0e002b1129d6b8 && git checkout -B drift-repro fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a && git merge --no-ff 5d09309a65a19d50631d0a349e0e002b1129d6b8

node scripts/docs-audit/affected-docs.mjs --json fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a

⚠️ 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 fde553c5091f9b7ac70b18c624ed7cd5df7c5f3a → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 2c9d2985a067984cfb97997d73757e9f38835315
Local-runs: none

Inputs: card #21113 (body, the claim comment, the dev report 5929937746), PR #21160 (body, the 14-file list, the net diff against the merge-base e952cff57), and the 32 check-runs on the head. Nothing built, run or re-run.

① Derived judgments

Accept-set, driver-turso remote face. A create / bulkCreate / upsert that leaves an autonumber slot empty (undefined, null, '') was refused NOT_IMPLEMENTED/501 and is now accepted with a generated value: the widening the PR declares. Right. It is #6944's disposition A behind its appetite door, opened by the measured demand the card records (cloud#2531). supports.autonumber on this face was already true, so the engine never ran its in-memory fallback here and none is introduced (pinned: supports.autonumber === true, and RemoteTransport.prototype still carries no autonumber member).

Atomicity (Acceptance 2). Warm path: UPDATE "_objectstack_sequences" SET last_value = last_value + 1 ... WHERE key_hash = ? RETURNING last_value, one statement, no read-then-write window. Cold path: a SELECT of the partition's stored values (read in JS by the shared maxAutonumberCounter), then INSERT ... ON CONFLICT (key_hash) DO UPDATE SET last_value = last_value + 1 RETURNING last_value: the counter move is again one statement. Two cold writers both scan, both INSERT; one wins the row and the other's CONFLICT arm increments it, so the values are distinct and no seed is lost. The window between the scan and the INSERT can only leave the seed stale (a bypass row landing meanwhile); SqlDriver.getNextSequenceValue has the same window (its scan at :7940 precedes its insert inside one transaction, and forUpdate is a no-op on SQLite), and both faces close it the same way: the #5495 re-seed, which on this face is UPDATE ... SET last_value = ? WHERE key_hash = ? guarded by last_value being below the observed MAX, forward-only and one statement, run when collidingAutoNumberReservations proves a unique violation to be this counter's. remoteSequencesTableEnsured holds only that the table exists and is reset on any failure; no in-process counter exists anywhere in the diff. Right.

What the concurrency pin proves, and what it does not. Two tsx child processes, each with its own @libsql/client native file: connection and its own remote-mode TursoDriver, released together by a file barrier, 2 x 200 creates per round: 400 distinct, exactly 1..400, strictly increasing per writer, no failed write, table and counter row agreeing, asserted every round. It proves the two statements are atomic under libSQL's write lock across OS processes, on the engine a Turso endpoint runs, which is the property the hosted runtime (several containers, one tenant database) needs. It does not exercise Hrana/HTTP: a statement retried after a lost response advances the counter twice, a gap the acceptance tolerates (gap-tolerant-monotonic), never a duplicate. And the overlap evidence is a skip, not a pass, when the scheduler serialises three rounds, so a green run of this file in CI is not by itself proof that the writers overlapped on that run; the skipped count is where it shows. The dev says both plainly. Judged adequate for Acceptance 2, with those two limits on record.

One semantics, shared not copied. Format and precedence: the inherited fillAutoNumberFields is called on every remote write (writeRemoteRowWithAutoNumbers), so resolveAutonumberFormat, renderAutonumber, the {field} refusal, the empty-slot predicate and the reservation report are one code path (pinned: the same refusal sentence on both faces, nothing written). Key: sequenceKeyHash(table, resolveSequenceTenantId(tenantField, tenantId), field, scope), pinned equal to the local face's sequenceKeyHash on one database file, with 1, 2, 3, 4 interleaving on one row whose last_value reads 4. Tenant: the same resolveSequenceTenantId, and the cold scan's tenant filter (resolvedTenantId === GLOBAL_TENANT ? null : resolvedTenantId) is the spelling SqlDriver.getNextSequenceValue uses at :7946. Bootstrap: maxAutonumberCounter with the suffix, pinned for #6468 (005-YYYY read as 5 on both faces, both continuing at 6 and 7). Table: defineSequencesTable compiled to text by the connection-less Knex, so both faces create one shape. What this face spells itself is the three statements and quoteSequenceName (identifier quoting that mirrors the transport's private tableSql), not a semantics copy. The ESCAPE '\' declared on the remote LIKE is right, and it is what exposed finding (a) in ③. Right.

The converted test (Acceptance 3). The refusal suite's 22 cases map onto the generation suite's 27. Every refusal became its generation counterpart (create, bulkCreate, the mixed batch, the no-id upsert, the '' and null slots). Every control is carried (caller-supplied number, batch with its own numbers, id-bearing upsert merges and keeps its number, update untouched, no-autonumber object untouched). The three face pins (LOCAL, LOCAL bulkCreate+upsert, REPLICA) and the two layer pins (RemoteTransport.create.length === 2, no autonumber member on the transport) are carried verbatim. The #7099 leg (an id-bearing upsert that INSERTS) is converted from "writes NULL and warns" to "gets its number, and no warning is logged". The other three #7099 pins asserted the warning's silence on legs that never warned; the warning is removed together with the leg it reported, so those pins have no subject left, and the behaviours behind them (merge keeps the number, no-autonumber object, caller-supplied) are pinned by the carried cases. Added: caller object not mutated, an explicit payload number does not renumber a merge, the two-face block (4 cases), the #5495 re-seed on create and bulkCreate plus the caller's own 409 (3), the legacy shape (1). The two resync pins keep their surface probe verbatim and replace the refusal half with generation and re-seed. Converted, not deleted. Right.

upsert and bulkCreate. RemoteTransport.upsert gains an optional fifth parameter, insertOnlyColumns (schema-free, default []); the driver passes remoteAutoNumberColumns(object, table), the object-then-table lookup fillAutoNumberFields makes, so a merge keeps its number and the unused reservation is a gap (pinned: seeded 42, merge, next create is 44; an explicit payload number does not renumber a merged row). SqlDriver.insertOnlyUpsertColumns also names id and created_at; the remote face names only the autonumber columns, so with caller conflictKeys the transport's merge set still carries id, which is pre-existing (#8622's shape) and is finding (b) in ③. bulkCreate on the remote face now loops this.create; RemoteTransport.bulkCreate was already a per-row loop of its own create (one INSERT and one read-back per row), so the statements sent and the mid-batch failure state are unchanged, and the old "all-or-nothing on this transport too" comment was false and is corrected. Right.

Legacy pre-key_hash table on the remote face. Refused DATABASE_ERROR/500 with the remedy in the message, not cached as a verdict (pinned: refused twice, nothing written, the table left exactly as found, a caller-supplied number still written through). Against ADR-0112: DATABASE_ERROR is a StandardErrorCode member (errors.zod.ts:111), 500 is the server band, and the same pair is what the spec's migration ledger records for "the object's table is absent", a correctly spelled request blocked by the backend's own state, which is this case. One consequence to know, not a defect of this PR: declaresServerFault (status at or above 500 with a string code, packages/types/src/error-leak.ts) means the REST doors put the code on the wire and withhold the prose, so the remedy reaches the operator's log rather than the tenant's body, which is where an operator action (open the database once through the local or replica face) belongs. Right.

Public surface. @objectstack/driver-sql's root gains one type re-export, AutoNumberReservation (the interface was exported from the module before, but the package exposes only ., so it was not reachable). Six new protected members on the exported SqlDriver (sequencesTableName, autoNumberCollisionRetries, resolveSequenceTenantId, defineSequencesTable, escapeLikePrefix, maxAutonumberCounter): subclass API in dist/index.d.ts, no runtime behaviour change on any dialect, every hunk a sequence member (:7532 to :8190 on the head, the region the claim bounded by content; its line numbers were read at an older base). RemoteTransport.upsert's optional fifth parameter. GLOBAL_TENANT was already exported. All right to make; the level of the root export is ② below.

AGENTS.md. Absent from the net diff: 14 paths, none is AGENTS.md, and the blob is e9e211fc9 at both the merge-base and the head (committed in 20a25d847, restored in 78fea1334). Confirmed.

tsx. devDependencies only. The lockfile gains only the importer entry (tsx: ^4.23.12, resolved 4.23.12); tsx@4.23.12 already resolves in the packages section for 12 other importers. Consistent, and Validate Package Dependencies is success on the head.

Check-runs on the head (32). Success: Build Core, Build Docs, Type Check source gates, Type Check debt ledger, Temporal Conformance (live PG + MySQL), Dogfood Regression Gate 2/3 and 3/3, Dogfood Verify CLI, Check Changeset, Validate Package Dependencies, Governed Surface Queue Guard, Check PR Size, Check Documentation Links, Flag docs affected by code changes, the four claim and path guards, Auto Label, filter. Skipped: Console Pin Gate, Packed-tarball smoke (opt-in). Still in_progress, so not verdicts: Test Core 1/6, 2/6, 3/6, 4/6, 5/6, 6/6, Dogfood Regression Gate 1/3, Lint and Repo Gates, Type Check consumer gates, Type Check workspace. Eleven, each named; none is read as green here, and the driver-turso pins (generation, concurrency, resync) run under Test Core. Check Changeset is check-changeset-no-major.mjs: presence and no-major, not the level, so its success does not answer ②.

② Semver level

Clause-②: yes (widening) is on the PR body and in the changeset body. The arm is right: a refused input is accepted, nothing narrows, nothing authorable moves, so no ADR-0087 marker is owed. @objectstack/driver-turso: minor. Right; yes takes at least minor (AGENTS.md Post-Task §3).

@objectstack/driver-sql: patch. Wrong. The diff adds a root export (AutoNumberReservation in src/index.ts's export-type block), and the changeset itself names it ("the AutoNumberReservation type is exported"). This package's own CHANGELOG levels exactly this shape: 17.5.0, "operatorFacingErrorText is a new export, present in dist/index.d.ts and in the export list. A purely additive widening takes at least minor", and "@objectstack/driver-memory is minor for the two new public-entry exports"; and the patch-side rule in 17.3.0, "Why patch and not minor: no export is added (the collector is protected)". The six protected members alone would be patch by that rule; the root type export is not. The dispatch premise "no spec key or export moves" was falsified by the implementation and reported in the PR body, but the level did not move with it. Either of two fixes closes this: bump @objectstack/driver-sql to minor in .changeset/21113-turso-remote-autonumber.md; or drop the root re-export and type the two overrides through the Parameters indexed type over SqlDriver that the autoNumberValueExists override already uses for its first parameter, leaving the export list unchanged and patch right. Nothing else in the changeset body is wrong.

③ Boundary flags

• open_questions: []. None to answer.
• H2 falsified on one point (the seed is not a SQL MAX folded into the statement): answered right. The bootstrap reading strips a declared suffix (自增号格式带「序号槽之后的后缀」时,播种解析读错数字段:引擎读成年份(2026),driver-sql 读成拼接串(12026),两侧还互不一致 #6468), a dialect expression would be the second copy the claim forbids, and both INSERT arms are atomic without it.
• "No sqld in this container": judged in ①; adequate for Acceptance 2 with the HTTP-retry gap and the skip-on-no-overlap limits on record.
• NOT MEASURED check:dual-build-cjs-loads (no local dist): CI's; Build Core is success on the head.
• Finding (a), scanMaxNumericTail on the local SQLite faces: Knex emits like ? with the backslash-escaped binding and no ESCAPE, so a format whose rendered prefix contains _ or % bootstraps from 0 on driver-sql over better-sqlite3 and on turso local and replica (PG and MySQL default to backslash escaping; measured probe in the report). Class a, public door, pre-existing, outside this card's file surface, and no carrier named. Escalated: needs its own card for the drivers lane. This PR's remote statement declares ESCAPE '\' and is the control.
• Finding (b), RemoteTransport.upsert with caller conflictKeys keeps id in the merge set ("id" = excluded."id"), the drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 re-keying the local face closed: pre-existing, read from the code, no carrier. Escalated: needs its own card.
• Finding (c), remote bulkCreate never all-or-nothing: answered. The false comment is corrected in this PR, and no contract text promises batch atomicity on this transport.
• (d) turbo 2.11.5 rewriting AGENTS.md: tracked as tooling: turbo 2.11.5 writes a managed block into AGENTS.md in every agent worktree; opt out with "agentGuidance": false in turbo.json #21146 / PR chore(turbo): opt out of the agent-guidance block in the root turbo.json #21151; AGENTS.md confirmed absent from this diff. (e) A transient check:dts-closure miss during a concurrent rebuild: noted, the [finding] @objectstack/service-cluster's dist/*.d.ts vanished AFTER its own build reported 3/3 declared declaration file(s) present — a downstream typecheck then failed TS7016 against a package that had built green #15042 shape, not this change's.
• Write surface: the dev reports 0 MCP calls and three relay writes (PR create, assignee, report), no label writes; the dispatch named none.

Implemented-by: claude/issue-21113-turso-remote-autonumber
Reviewed-by: session_01Ujdtvqs7ree7WyQmEDwEnG

VERDICT: FAIL

One blocking item, ②: @objectstack/driver-sql is levelled patch while the diff adds a root export; one line in the changeset, or dropping the re-export, closes it. Every ① judgment and every ③ flag holds on this head, so the re-review after that fix is bounded to the changeset and to the eleven check-runs still in progress.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5d09309a65a19d50631d0a349e0e002b1129d6b8
Local-runs: none

Round-1 delta review of FAIL 5930100091 @ 2c9d2985a. Inputs: card #21113 (body; the claim 5927179360, the round-0 report 5929937746, the seat's decision 5930121675, the round-1 report 5930264607), PR #21160 (body as rewritten for round 1, the 13-file list, the net diff against the merge-base fde553c50, which is the main commit merged in 605a1d2b5), the 39 check-runs on the head read once at 2026-10-01T11:22:44Z, and the previous at-tier record. Nothing built, run or re-run; the shared checkout was only fetched into a review ref and read.

What moved since 2c9d2985a. Two first-parent commits: the merge 605a1d2b5 (of main fde553c50, 10 commits) and the fix 5d09309a6. The PR's own hunks are patch-id identical before and after the merge (849a28b3c for both e952cff57..2c9d2985a and fde553c50..605a1d2b5, identical file lists), and main's one change to a PR file in that range (sql-driver.ts via #21117, hunks at :144, :3669 and :16232) is outside the sequence region (:7347 to :7950 at this head), so the merge carried nothing of its own and the net diff is the PR's hunks plus the fix. The fix is 3 files, +6/-11: driver-sql/src/index.ts drops the six-line AutoNumberReservation re-export; turso-driver.ts drops the type AutoNumberReservation import and retypes two override parameters; the changeset's last sentence changes. Nothing else.

① Derived judgments

The four questions of this round.

• packages/drivers/driver-sql/src/index.ts is byte-identical to main: blob cb0a71d25 at the head, at origin/main and at the merge-base; git diff origin/main..head on it is empty. No new export reaches a consumer: @objectstack/driver-sql's package.json is unchanged (exports has only ., to dist/index.d.ts / .mjs / .js), the only driver-sql source in the diff is sql-driver.ts, and every addition there is protected (six members). Right.
• The two re-seed overrides take their parameter types through Parameters indexed over SqlDriver's protected members: autoNumberValueExists takes Parameters of SqlDriver['autoNumberValueExists'] at index 0 and index 1; resyncSequenceToDataMax takes Parameters of SqlDriver['resyncSequenceToDataMax'] at index 0; getNextSequenceValue's parentTrx the same way (unchanged from round 0). No structural copy: a grep for AutoNumberReservation across driver-turso at this head hits only four prose mentions of collidingAutoNumberReservations; no interface or type named *Reservation and no object type spelling its fields exists in the package. The premise the seat required measuring (the type is reachable from the subclass without the export) is sound by construction, since an indexed access type on a protected member is legal inside the subclass body, and the same spelling already compiled at 2c9d2985a for the first parameter and for parentTrx (Type Check source gates success there and here). Right.
• driver-sql at patch: right now, judged in ②.
• AGENTS.md: absent from the net diff (13 paths, none is AGENTS.md), blob e9e211fc9 at both main and the head, and fde553c50 carries chore(turbo): opt out of the agent-guidance block in the root turbo.json #21151's agentGuidance: false opt-out, so the cause of the round-0 incident is gone from this branch's tree as well. Confirmed.

Every ① judgment of 5930100091, re-confirmed on this head. The hunks they were made on are unchanged by patch-id, so each holds unless the fix touched it:

• Accept-set, driver-turso remote face: a create / bulkCreate / upsert leaving an autonumber slot empty (undefined, null, '') was refused NOT_IMPLEMENTED/501 and is now accepted with a generated value; supports.autonumber stays true and no in-memory fallback is introduced (pinned). Holds.
• Atomicity (Acceptance 2): warm UPDATE ... RETURNING last_value, cold scan-then-INSERT ... ON CONFLICT (key_hash) DO UPDATE ... RETURNING, one statement each; the scan-to-insert window leaves only a stale seed, closed by the Autonumber counter neither syncs to MAX(existing) per tenant nor re-checks on collision — warm-DB creates 409 in bursts, each failure burning a number (25 retries observed) #5495 forward-only re-seed exactly as on the local face; remoteSequencesTableEnsured remembers only that the table exists and is reset on failure. Holds.
• The concurrency pin and its two limits (no Hrana/HTTP; a skip, not a pass, when three rounds serialise): holds. The round-1 report adds one measurement on the merged tree, 400 writes / 400 distinct / 5 writer changes inside the full-package run.
• One semantics, shared not copied: fillAutoNumberFields called on every remote write; sequenceKeyHash(table, resolveSequenceTenantId(...), field, scope) pinned equal to the local face's on one database file; maxAutonumberCounter with the suffix (自增号格式带「序号槽之后的后缀」时,播种解析读错数字段:引擎读成年份(2026),driver-sql 读成拼接串(12026),两侧还互不一致 #6468); defineSequencesTable compiled to text; the ESCAPE '\' on the remote LIKE. Holds, and the fix strengthens it: the reservation type is no longer even named in driver-turso.
• The converted test (Acceptance 3): refusal suite D (537 lines) to generation suite A (602 lines, 27 cases), controls and the three face pins and two layer pins carried, the Turso remote:带 id/conflictKeys 但没匹配上的 upsert 仍会静默写入 NULL 自增号(#6944 拒绝闸门覆盖不到的那条腿) #7099 leg converted, the two resync pins rewritten with the surface probe verbatim. Holds.
• upsert and bulkCreate: RemoteTransport.upsert gains an optional fifth parameter insertOnlyColumns (default []), the driver names the autonumber columns, a merge keeps its number and the unused reservation is a gap (pinned 42, merge, 44); remote bulkCreate loops this.create and the transport was already a per-row loop, so statements and mid-batch state are unchanged. Holds.
• Legacy pre-key_hash table on the remote face: refused DATABASE_ERROR/500 with the remedy, not cached, caller-supplied numbers still written (pinned). Holds.
• Public surface, REVISED by the fix: @objectstack/driver-sql's root gains nothing; six protected members on SqlDriver (sequencesTableName, autoNumberCollisionRetries, resolveSequenceTenantId, defineSequencesTable, escapeLikePrefix, maxAutonumberCounter) are subclass API in dist/index.d.ts only. GLOBAL_TENANT, newly imported by turso-driver, was already exported (index.ts:107 on main). On @objectstack/driver-turso, RemoteTransport IS a root export (src/index.ts:38, unchanged), so upsert's optional fifth parameter is public surface of that package, additive, covered by its minor. All right to make.
• tsx as a devDependency of driver-turso with only the importer entry in the lockfile (tsx@4.23.12 already resolved): holds; Validate Package Dependencies is success on this head.
• Cosmetic, not a defect: the PR body's ":7532 to :8190 on this head" for the sequence region predates the merge; at 5d09309a6 the members sit at :7362 to :7999.

Check-runs on the head (39 entries, read once at 11:22:44Z). Success (19): Type Check source gates, Build Docs, Check Changeset (both runs), Validate Package Dependencies, Governed Surface Queue Guard, Check PR Size, Check Documentation Links, Flag docs affected by code changes, The card this PR closes must claim this branch (both), No other open PR may claim the same issue (both), No other open PR may claim the same single-writer path (both), Part-of PR must not also close its card (both), Auto Label, filter. Skipped (4): Console Pin Gate, Packed-tarball smoke (opt-in), and one Auto Label and one Check PR Size duplicate. Still in_progress, so not verdicts, each named: Build Core (success on 2c9d2985a, re-running here), Test Core 1/6, 2/6, 3/6, 4/6, 5/6, 6/6 (these carry the driver-turso generation, concurrency and resync pins), Lint and Repo Gates, Type Check consumer gates, Type Check debt ledger, Type Check workspace, Dogfood Regression Gate 1/3, 2/3, 3/3, Dogfood Verify CLI, Temporal Conformance (live PG + MySQL). Sixteen; none is read as green here, and none was polled. No check is failure or cancelled. Check Changeset is presence and no-major, not the level, so ② is judged from the diff.

② Semver level

Clause-②: yes (widening) is on the PR body and in the changeset body. The arm is right: a refused input is accepted, nothing narrows, no spec key or authorable surface moves, so no ADR-0087 marker is owed. @objectstack/driver-turso: minor. Right; yes takes at least minor, and the package also gains an optional parameter on an exported class.

@objectstack/driver-sql: patch. Right now. The root export that made it wrong at 2c9d2985a is gone (index.ts byte-identical to main); the six new members are protected; and every sql-driver.ts hunk is an extraction with identical logic: defineSequencesTable is the former inline createTable body, escapeLikePrefix the former regex, maxAutonumberCounter the former loop over the same values, resolveSequenceTenantId the former ternary at its three sites, and the two getters return the module constants and are not called by SqlDriver itself. No statement SqlDriver sends changes on any dialect. This is the 17.3.0 shape in the package's own CHANGELOG ("no export is added, the collector is protected"). The changeset sentence matches the diff: "No export is added and no behaviour changes on any dialect", and that sentence is the only changeset delta since 2c9d2985a. The blocking item of 5930100091 is closed on branch 1 of the seat's decision 5930121675, with the premise measured as that decision required; branch 2 was not taken and is not needed.

③ Boundary flags

• open_questions: [] in the round-0 and round-1 reports. None to answer.
• Seat decision 5930121675, branch taken: 1 (drop the export). Named by the dev, measured (driver-sql and driver-turso typecheck exit 0 locally) and sound by construction as read above. Answered.
• Finding (b), measured as the seat asked: RemoteTransport.upsert with caller conflictKeys keeps id in its merge set, and it REPRODUCES on the remote face (stub harness: a payload id replaces the stored row's primary key; with no payload id a freshly minted nanoid re-keys the row; the LOCAL control keeps row-a). Pre-existing, outside this diff's hunks (the driver names only the autonumber columns insert-only; the transport's merge set is pre-existing code). Named here for the seat to file per 5930121675. Not judged as this PR's.
• Finding (b-prime), new from the same probe's LOCAL control: SqlDriver.upsert keyed on ['email'] with payload id: 'row-NEW' keeps the stored id (correct) but RETURNS a row carrying id: 'row-NEW', an id no stored row has. Read off one better-sqlite3 run, not PG/MySQL. The dev names the seat's (b) card as carrier. Escalated with (b): a contract fact of the local face, outside this diff.
• Finding (a), scanMaxNumericTail on the local SQLite faces compiles like ? without ESCAPE: filed by the seat as [finding] SQLite: an autonumber format whose prefix contains _ or % seeds its counter from 0 — scanMaxNumericTail escapes the prefix but Knex emits no ESCAPE clause, so the bootstrap and #5495 re-seed scans match nothing #21163. Answered; this PR's remote statement declares ESCAPE '\' and is the control.
• Finding (c), remote bulkCreate never all-or-nothing: answered, the false comment is corrected in this PR and no contract text promises batch atomicity on this transport.
• (d) turbo 2.11.5 rewriting AGENTS.md: tooling: turbo 2.11.5 writes a managed block into AGENTS.md in every agent worktree; opt out with "agentGuidance": false in turbo.json #21146 / chore(turbo): opt out of the agent-guidance block in the root turbo.json #21151, and the opt-out is in the main merged here; AGENTS.md absent from the diff. Answered. (e) The transient check:dts-closure miss during a concurrent rebuild: the [finding] @objectstack/service-cluster's dist/*.d.ts vanished AFTER its own build reported 3/3 declared declaration file(s) present — a downstream typecheck then failed TS7016 against a package that had built green #15042 shape, not this change's. Noted.
• H2 falsified on one point (the seed is not folded into the statement as a SQL MAX): answered as in round 0, the bootstrap reading strips a declared suffix and a dialect expression would be the second copy the claim forbids.
• "No sqld in this container": unchanged, adequate for Acceptance 2 with the HTTP-retry gap and the skip-on-no-overlap limits on record.
• NOT MEASURED check:dual-build-cjs-loads (no local dist): CI's; Build Core was in_progress on this head at the read, so it is not a verdict here, unlike on 2c9d2985a.
• The throwaway drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 probe: deleted before the commit, as reported; the 13-path file list holds no probe, and the 83/2219 versus 82/2218 counts reconcile with that.
• Write surface this round: 0 MCP; two relay writes (the PR body PATCH with --ack-through=5930100091, the round-1 report); no label, assignee or state writes; one fast-forward push.

Implemented-by: claude/issue-21113-turso-remote-autonumber
Reviewed-by: session_01Ujdtvqs7ree7WyQmEDwEnG

VERDICT: PASS

The one blocking item of 5930100091 is closed by dropping the root export and typing the two overrides through the indexed Parameters of the protected members; driver-sql patch and the changeset text are right on this head, every ① judgment of the previous record holds on hunks that are patch-id identical, and ③ carries nothing open for this PR. Sixteen check-runs were still in progress at the read and are not verdicts of this record; the merge gates read them on their own.

---

Generated by Claude Code