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

[qq9340100]

Fixes #8479

What

The autonumber contract ruled on #8283 (Option 1, maintainer ruling 2026-08-13: unique and monotonic per scope, NOT gapless — any rejected write may consume the number it reserved) landed as a driver TSDoc in PR #8488, but that half is claimed there and out of scope here. This card puts the same contract where an app author (human or AI) actually reads it: content/docs/data-modeling/**.

Premise re-verified on origin/main in this worktree before editing:

• grep -rniE 'gapless|monotonic' content/docs/data-modeling/*.mdx → zero on-topic hits (two unrelated "gap" matches about aggregation capability gaps).
• autonumber appears in 6 files: field-types.mdx, fields.mdx, field-type-decision-tree.mdx, schema-design.mdx, indexing.mdx, validation-rules.mdx — the ruled contract was genuinely absent from all of them.

Placement

One authoritative statement, one pointer — not all six pages, for the reason #8405/#8386/#8285 already established (a contract repeated N times is N things to keep in sync):

• field-types.mdx (### autonumber in the Field Type Gallery — the page schema-design.mdx itself calls "the complete per-type reference") gets the full contract as a <Callout type="warn">: unique + monotonic per scope, not gapless, names the cause (a unique violation on another field, a failed validation rule, a throwing beforeInsert all still consume the reserved number), and states the finance-facing corollary explicitly — an autonumber is not a legally gapless document number.
• schema-design.mdx's ### AutoNumber Field section gets a one-line pointer to the full contract. This page carries a complete worked account_number: Field.autonumber(...) example that a reader could copy straight into a business-identifier field without ever visiting the reference page — exactly the mis-promise path the ruling is trying to close — so it gets a reachable summary + link rather than silence.

fields.mdx, field-type-decision-tree.mdx, indexing.mdx, validation-rules.mdx were left untouched: each is a compact reference table/decision aid with no worked example a reader would act on directly, so a pointer there would be sync-debt without a matching reachability risk.

Testing

All from a fresh worktree, dependencies built first (pnpm --filter '@objectstack/lint^...' build):

• pnpm --filter @objectstack/lint run check:doc-formula-expressions → green (24 self-test cases + corpus scan clean)
• pnpm check:docs-audit-scope → green
• pnpm check:quick-reference-counts → green
• pnpm check:role-word → green
• pnpm check:nul-bytes → green
• pnpm check:doc-anchors → green (sanity-checked the new field-types#autonumber cross-reference link resolves)
• node scripts/pm/dispatch-gates.mjs content/docs/data-modeling/field-types.mdx content/docs/data-modeling/schema-design.mdx → surfaces exactly the four named families above, no additional family implicated by this diff.

Scope

Docs-only, content/docs/data-modeling/** only (declared file surface honored, no breach). Does not touch packages/drivers/driver-sql/src/sql-driver.ts (#8283's drivers half, different lane, already merged in #8488).

Generated by Claude Code

---

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 5:21pm