docs(driver-sql): state the autonumber contract — unique and monotonic, not gapless

[os-zhuang]

Fixes#8283

Executes the maintainer ruling of 2026-08-13 (option 1): document the contract, change nothing.

What this is

A TSDoc addition and a changeset. Nothing else.

 .changeset/autonumber-not-gapless-contract.md | 40 ++++++++++++++++++++++++
packages/drivers/driver-sql/src/sql-driver.ts | 45 +++++++++++++++++++++++++++
2 files changed, 85 insertions(+)

All 45 added lines in sql-driver.ts are comment lines; there are zero deletions and zero non-comment additions in the whole diff. Verified mechanically rather than by eye:

$ git diff -U0 origin/main -- packages/drivers/driver-sql/src/sql-driver.ts \
| grep '^+' | grep -v '^+++' | sed 's/^+//' | grep -vE '^\s*\*'
(no output)

The contract, as stated

Placed next to the existing sentencean autonumber is an immutable business identifier (anchored by phrase — the neighbour is at sql-driver.ts:4827 on this base, and line numbers there have drifted repeatedly). The new section says:

• Unique and monotonic per counter — the (table, tenant, field, scope) key getNextSequenceValue issues from — and NOT gapless.
• A rejected write consumes the number it reserved: a unique violation on another field, a validation rule, a throwing beforeInsert. The number is issued to no row and never re-issued; the next write gets the one after it. TK-0001, a failed insert, then TK-0003 is the contract behaving correctly.
• Why it cannot be taken back — the mechanism, since this is the driver that owns it: getNextSequenceValue commits the reservation in its own transaction (runner.transaction over parentTrx ?? this.knex), deliberately independent of the caller's insert.
• This is ordinary sequence semantics, not a defect — with an explicit instruction not to add reclamation or reservation-reordering, and the reason that shape was rejected.
• A decided property, citing the ruling, so the next reader can tell it was chosen rather than defaulted.

Accuracy note on the mechanism

I verified the mechanism against the code it sits beside rather than restating the card. runner.transaction nests when a parentTrx is supplied, so the inside-a-caller-transaction path rolls back with the refused insert and burns nothing — which the upsert retry comment right below already records as measured. The TSDoc states the independent-commit case as the contract-relevant one and notes the nested case parenthetically, so the paragraph does not overstate what the code does.

Explicitly not done

• No behaviour change of any kind.
• No reservation-ordering work (rejected as option 2).
• The savepoint structure in getNextSequenceValue is untouched; I did not edit that function at all, and reference it outward via {@link getNextSequenceValue} instead.
• No opt-in gapless mode (option 3 — recorded as a restart condition, not work).
• No content/docs/**. The author-facing half of the ruling belongs to the devx lane and is tracked in docs: the autonumber contract ruled on #8283 (unique + monotonic, NOT gapless) is absent from the author-facing pages — a driver TSDoc cannot stop the mis-promise it exists to prevent #8479, which stays open and is not addressed here.

Changeset: patch on @objectstack/driver-sql, deliberately

Reasoned rather than copied, on repo evidence:

• The empty-frontmatter route is not available: check-empty-changeset.mjs rejects a PR that newly adds one (the 182 in the tree are grandfathered by a diff-computed exemption).
• That leaves patch or the skip-changeset label. The label is for a PR that "declares no release of its own" — the workflow's own textbook case is editing a CI-internal script.
• This PR's entire product is a consumer-facing contract statement, and it ships two ways: the package builds with declaration: true and no removeComments, and insertOnlyUpsertColumns is protected, so the text is emitted into the published .d.ts; and AGENTS.md frames the changeset body as the channel that reaches consumers as CHANGELOG.md — "what an upgrading agent greps".
• Routing a statement whose whole purpose is preventing a mis-promise into driver source only would reproduce, at the release-notes layer, exactly the gap that made this card necessary.

The honest counter-argument: AGENTS.md scopes changesets to feature work and functional improvement, and this is neither — that is the case for skip-changeset. I judged the delivery channel to be the deciding factor. Flipping to the label costs one deleted file if the reviewer disagrees.

Verification

Check	Result
pnpm --filter @objectstack/driver-sql typecheck	pass
pnpm --filter @objectstack/driver-sql test	1431 passed, 52 skipped, 93 files, 0 failed
autonumber + upsert-immutable specs, re-run by name	3 files, 18 tests, pass
check:nul-bytes	pass (7643 files, no raw control bytes)
check:driver-conformance	pass (45 cells, 0 debt)
check:changeset-gate-self-tests	pass
check-empty-changeset / check-changeset-no-major / check-adr-0087-registration	pass, diff-scoped against the merge base
check:objectui-changeset, check:test-source-alias, check:type-source-resolution	pass

Reverse verification does not apply here: there is no behaviour to revert and no diagnostic that could change colour. What I did instead was read the mechanism I describe — getNextSequenceValue's runner assignment and its runner.transaction body — and check the claim against the two independent places in the file that already record it as measured.

check:objectui-pin-fresh and check-dev-prereqs are red on inputs this diff does not touch (a stale .objectui-sha; a workspace needing pnpm build) — known-ambient, reported not chased.

---

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 13, 2026 3:38pm

[github-actions]

📓 Docs Drift Check

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

8 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)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/driver-sql)

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.

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.