fix(driver-sql): bulkCreate and upsert re-seed a stale autonumber counter instead of burning the whole batch (#6943)

[claude]

Fixes #6943.

Two paths, two different shapes — measured, not inherited

The card said bulkCreate and upsert "still burn a number per collision, like create()". Only one of them does. Re-derived on main @ c8ff269, on a fresh DB with seeded rows above the counter (#5495's repro constraint: the storm is one-time per database, and on a DB already ground past the seeds everything passes and the defect is invisible).

upsert is create()'s pre-#5495 shape exactly. Single row, so a stale counter costs it one burned number per call — last_value walked 1 → 2 → 3 across two refused upserts. Worth stating because it is not obvious: ON CONFLICT (mergeKeys) DO UPDATE absorbs a conflict on the merge key only, and the tenanted autonumber lives under a different unique index, so its violation is still raised and still reaches the caller.

bulkCreate is a sharper shape. Each row reserves its number in its own committed transaction, then the whole batch goes in as one insert. So one colliding row does not burn one number — it burns every number the batch reserved and fails the entire request:

3-row bulkCreate, counter at 10, rows 11–39 already present	before	after
caller-visible failures	both calls threw	0
rows written	0	3
last_value	10 → 13, then 13 → 16	10 → 42, by one re-seed

And the exposure is the worst available: bulkCreate's own docstring records that framework#2678 made it the common case for seed/import — and seed/import is precisely what creates the staleness, since an isSystem replay or a preserveAudit import keeps its explicit numbers and never enters fillAutoNumberFields (#5495/#5503). The path most likely to meet a stale counter was the one with no recovery at all.

Batch semantics are unchanged, and that is a measurement

This card was split out of #5495 because per-row retry inside a batch was expected to force a decision about partial success, transaction boundaries, and whether a failed row rolls back its siblings.

There is no such decision to make. insert(rows[]) is a single statement (… select … union all select … on SQLite, multi-row VALUES elsewhere), so the batch is already all-or-nothing — the failed 3-row batch above left the table at exactly the 31 rows it started with. Re-issuing and retrying the whole batch therefore preserves the existing contract byte for byte: no partial success is introduced, no transaction is opened, and the sibling-rollback question never arises because siblings already fail together.

Rejected, with reasons, in bulkCreate's own comment:

• Per-row retry inside the batch (the shape the card sketched) — it requires splitting the one statement into N to learn which row failed, which invents partial success where none exists, costs N round-trips on the hot seed/import path, and is what the engine's own Engine fallback autonumber: counter seeds once and never resyncs; collisions burn numbers with no recheck (residual split from #5495) #6806 note warns about ("re-writing the batch could DUPLICATE the rows that did land"). Nothing lands here, so nothing can.
• Wrapping the batch in a driver-opened transaction — moves the very boundary the card was worried about for no gain (the statement is already atomic), defeats the reservation model (each getNextSequenceValue commits on purpose, which is what makes a forward-only re-seed meaningful), and on SQLite with pool max = 1 is the deadlock ensureSequencesTable already documents.
• Re-seed but do not re-issue — what the engine does at Engine fallback autonumber: counter seeds once and never resyncs; collisions burn numbers with no recheck (residual split from #5495) #6806, and correct there, because the engine cannot know whether an arbitrary driver applied the batch partially. Inside this driver that is measurably false, so the caller can be handed a successful batch instead of an error to retry itself.
• Blanket retry on any unique violation — rejected for 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's reason: it silently eats the caller's own 409.

The one thing the batch may not borrow from create()

create() keeps a reservation that did not collide, to avoid burning a second number. A batch cannot, and this is the non-obvious correctness point of the change.

A batch that straddles the seeded range — counter at 10, rows 11–39 present, batch reserves 11–70 — has its low rows collide and its high rows not. Re-issuing only the collided ones hands them numbers above the kept ones: an intra-batch duplicate the driver would have manufactured itself. So re-issue is per counter: every row drawn from a counter that went stale is re-issued, and counters that did not go stale keep their values, so a co-tenant's rows in the same batch are undisturbed. Both halves are pinned by tests.

Machinery reused, not rebuilt

collidingAutoNumberReservations (three-state routing), autoNumberValueExists (the data-based discriminator — the conflicting column is never determinable for a tenanted autonumber, so routing cannot rest on the error text), and the forward-only resyncSequenceToDataMax are all #6932's, unchanged. No fifth dialect word-list: the judgement is isUniqueViolationError / uniqueViolationColumn from @objectstack/types (Prime Directive #12).

One helper is new — autoNumberCounterKey, which reuses the existing sequenceKeyHash. create() never needed it because one row draws at most one reservation per field; a batch has many rows sharing one counter, and both of the batch's decisions (re-seed once, re-issue all) are per counter.

Retry stays confined to the no-caller-transaction case, as at #5495. Inside a caller's transaction the sequence UPDATE rolls back with the refused INSERT, so nothing is burned and there is nothing to repair — re-measured on both paths here — and on Postgres a constraint failure aborts the transaction outright. The caller owns that retry.

Three faces

face	conclusion	basis
SqlDriver	fixed	primary
SqliteWasmDriver	inherits, verified live	overrides neither method; own test
TursoDriver local/replica	inherits, verified live	overrides both and routes to super; own test
TursoDriver remote	neither defect nor fix	RemoteTransport.bulkCreate builds its own INSERT, never enters fillAutoNumberFields

Turso needed saying out loud more than at #5495: it overrides bulkCreate/upsert rather than merely inheriting, so "the base class was fixed" is not on its own an answer about that face. The remote face's absence is pinned as an assertion, not a comment, so wiring autonumber into that transport later (#6944) cannot silently inherit this file's green.

driver-memory / driver-mongodb are untouched and inside the #5499 freeze — neither declares supports.autonumber, so both use the engine fallback (#6806's surface). A real absence, not a skipped row.

Out of scope, recorded not fixed

upsert burns a number on every merge, and overwrites the record's autonumber. Independent of any stale counter: fillAutoNumberFields runs before the statement knows whether it will insert or merge, and the autonumber column is in mergeColumns. Measured on a correct counter — creating CASE-00001 then upserting the same row by id twice yielded CASE-00002 then CASE-00003, one row throughout, last_value 1 → 2 → 3. That is an unbounded burn on the success path, and it mutates a business identifier rather than merely leaving a gap. It is not this card's defect (no staleness involved), and fixing it is its own semantics decision — should an upsert that updates keep the old number, and should it reserve at all? — of exactly the kind that got this card split from #5495. Recorded for triage; deliberately not fixed here. Guarded only to the extent that the retry loop cannot turn a merge into an insert.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DZrSGPUVrFqYCKc3ELYRqR

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 9, 2026 8:21am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql.

9 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sql)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx (via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/driver-sql)
• content/docs/releases/implementation-status.mdx (via @objectstack/driver-sql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.