docs(spec,objectql,driver-sql): declare the unanchored readback boundary (#7287) (#7405)

Maintainer ruling on #7287 (2026-08-10, treatment (2) 「宣告边界」): on an
UNANCHORED autonumber format (neither prefix nor suffix), a stored value
carrying non-digit content is OUT OF CONTRACT for counter readback, and
`readAutonumberCounter`'s `undefined` for that slot is the contract rather
than a gap.

Zero behavior movement. The two consumers keep their divergent legacy
readings — the engine's `readStoredAutonumberCounter` takes the last digit
run, driver-sql's `scanMaxNumericTail` concatenates every digit — each now
labelled implementation detail outside the declared boundary, pointing at
spec's TSDoc. Hoisting either reading was rejected: it would move live
behavior on the other side over record numbers already issued (the reason
#7247 refused the hoist as a rider).

The boundary is drawn by CONTENT and deliberately wider than the observed
divergence: pure-digit values (what `renderAutonumber` emits for an
unanchored format) are in contract and read the same on both sides, while
every mixed-content value is outside — including ones the two readings
happen to agree on, since divergence needs two digit runs. Narrowing it to
"values the sides actually disagree on" would make membership undecidable
from the value alone.

Reachability: #6555's Route-3 ruling (PR #7265) made `{0000}` the declared
default for format-less autonumber fields, so the default authoring shape
now lands in this unanchored slot.

New pins in `autonumber-unanchored-boundary.test.ts` assert the `undefined`
for eight mixed-content shapes, show the two readings diverging on the
inputs the boundary excludes and agreeing on the ones it admits, and pin
that `{0000}` really renders an unanchored pair. No existing test is edited.

Diff is comments and one new test file only — no executable line is added,
removed or moved outside tests.

Closes #7287


Claude-Session: https://claude.ai/code/session_0184Hrx9PcaQ2KMMt88DRZ2c

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

packages/drivers/driver-sql/src/sql-driver.ts

@@ -3629,6 +3629,28 @@ export class SqlDriver implements IDataDriver {
    *     the last digit run), so there is nothing shared to hoist — spec answers
    *     `undefined` for an unanchored slot rather than pick one of the two.
    *
+   * ## The unanchored arm is IMPLEMENTATION DETAIL, outside the declared contract (#7287)
+   *
+   * That refusal is now a DECLARED boundary, not merely an absent agreement: the
+   * #7287 ruling (2026-08-10, 「宣告边界」) states that a stored value carrying
+   * non-digit content on an unanchored format is out of contract for counter
+   * readback, and that `readAutonumberCounter`'s `undefined` for that slot is the
+   * contract rather than a gap. The boundary and its rationale live in that
+   * function's TSDoc in `packages/spec/src/data/autonumber-format.ts`; the pins
+   * are `packages/spec/src/data/autonumber-unanchored-boundary.test.ts`.
+   *
+   * So the concatenate-every-digit reading below is THIS DRIVER'S behavior, not a
+   * promise the platform makes. On the inputs the contract admits — pure-digit
+   * values, which is what `renderAutonumber` emits for an unanchored format — it
+   * answers the same number the engine does. On mixed-content values it may
+   * answer differently (`'SO-2024-0007'` → `20240007` here, `7` in the engine's
+   * `readStoredAutonumberCounter`), and that difference is out of contract on
+   * both sides, not a defect on either.
+   *
+   * Consequently the ruling moves nothing here: neither this reading nor the
+   * engine's was hoisted into the shared helper, precisely because doing so would
+   * move live behavior on the other side over record numbers already issued.
+   *
    * ## Why the suffix is NOT pushed into the LIKE
    *
    * `like 'prefix%suffix'` looks tempting and is wrong: the counter scope is the

packages/objectql/src/engine.ts

@@ -372,6 +372,27 @@ interface IssuedAutonumber {
  *     concatenates every digit), which is exactly why spec refuses to answer for
  *     an unanchored slot instead of picking one of the two.
  *
+ * # The unanchored arm is IMPLEMENTATION DETAIL, outside the declared contract (#7287)
+ *
+ * Spec's refusal above is no longer just an absence of agreement: the #7287
+ * ruling (2026-08-10, 「宣告边界」) DECLARES that a stored value carrying
+ * non-digit content on an unanchored format is out of contract for counter
+ * readback, and that `readAutonumberCounter`'s `undefined` for that slot is the
+ * contract rather than a gap. The boundary and its rationale live in that
+ * function's TSDoc in `packages/spec/src/data/autonumber-format.ts`; the pins
+ * are `packages/spec/src/data/autonumber-unanchored-boundary.test.ts`.
+ *
+ * So the last-digit-run reading below is THIS ENGINE'S behavior, not a promise
+ * the platform makes. On the inputs the contract admits — pure-digit values,
+ * which is what `renderAutonumber` emits for an unanchored format — it answers
+ * the same number the SQL driver does. On mixed-content values it may answer
+ * differently (`'SO-2024-0007'` → `7` here, `20240007` there), and that
+ * difference is out of contract on both sides, not a defect on either.
+ *
+ * Consequently the ruling moves nothing here: neither this reading nor the
+ * driver's was hoisted into the shared helper, precisely because doing so would
+ * move live behavior on the other side over record numbers already issued.
+ *
  * The unanchored branch uses the linear `/\d+/g` — a backtracking lookahead here
  * is a polynomial-ReDoS sink on stored values full of zeros (CodeQL
  * js/polynomial-redos).

packages/spec/src/data/autonumber-format.ts

@@ -336,6 +336,57 @@ export function renderAutonumber(input: RenderAutonumberInput): RenderedAutonumb
  * Hoisting either one here would make this contract claim an agreement that does
  * not exist. Each side documents its own fallback at its own call site.
  *
+ * # The declared boundary: mixed-content unanchored values are OUT OF CONTRACT (#7287)
+ *
+ * That refusal is not a gap waiting to be filled — as of the maintainer's ruling
+ * on #7287 (2026-08-10, 「宣告边界」, treatment (2)) it IS the contract:
+ *
+ * > **On an UNANCHORED format (`prefix === '' && suffix === ''`), a stored value
+ * > carrying any non-digit content is out of contract for counter readback.**
+ * > `undefined` is this function's answer for that slot, permanently.
+ *
+ * Why declare it rather than pick a reading. The two consumers have read such a
+ * value differently since before this helper existed, and both readings are
+ * pinned by their own tests:
+ *
+ *   - the engine's `readStoredAutonumberCounter`
+ *     (`packages/objectql/src/engine.ts`) takes the **last digit run** —
+ *     `'SO-2024-0007'` → `7`;
+ *   - the SQL driver's `scanMaxNumericTail`
+ *     (`packages/drivers/driver-sql/src/sql-driver.ts`) **concatenates every
+ *     digit** — the same value → `20240007`.
+ *
+ * Ruling either one to be the contract would move live behavior on the other
+ * side, over stored business identifiers that are not reclaimable once issued —
+ * which is why #7247 refused the hoist as a rider, and why #7287 rejects it
+ * outright rather than picking a side. Declaring the input out of contract costs
+ * nothing that was ever promised: no reading was ever specified for it.
+ *
+ * The boundary is drawn by CONTENT, and deliberately wider than the observed
+ * divergence. A **pure-digit** value — which is exactly what `renderAutonumber`
+ * emits for an unanchored format — is inside the contract, and both sides answer
+ * the same number for it: `'0007'` reads as `7` either way. Everything else is
+ * outside, including mixed-content values the two readings happen to agree on
+ * (`'CASE-12'` is `12` both ways: divergence needs TWO digit runs, and that one
+ * has one). Narrowing the boundary to "values the sides actually disagree on"
+ * would make it undecidable from the value alone — a caller would have to know
+ * which consumer is running to know whether its input is in contract, which is
+ * the very "same metadata, different driver, different number" property this
+ * boundary exists to bound. So the out-of-contract face is simply
+ * legacy/migrated data: a dash-separated string in a column later declared
+ * autonumber.
+ *
+ * Reachability, and why the boundary is worth stating now: #6555's Route-3
+ * ruling (PR #7265) made `{0000}` the declared default for format-less
+ * autonumber fields, and `{0000}` renders neither prefix nor suffix — so the
+ * DEFAULT authoring shape resolves to this unanchored slot on both sides.
+ *
+ * Consequence for the consumers, also recorded by the ruling: neither moves.
+ * Each keeps its current unanchored reading as **implementation detail outside
+ * this boundary**, not as a contract this file underwrites. See the pins in
+ * `autonumber-unanchored-boundary.test.ts`, and the ruling itself at
+ * https://github.com/objectstack-ai/objectstack/issues/7287#issuecomment-5238560707.
+ *
  * The digit match is the linear `/^\d+/` — a backtracking lookahead here is a
  * polynomial-ReDoS sink on stored values full of zeros (CodeQL
  * js/polynomial-redos).

packages/spec/src/data/autonumber-unanchored-boundary.test.ts

@@ -0,0 +1,147 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pins for the contract boundary declared on #7287 (maintainer ruling
+ * 2026-08-10, 「宣告边界」, treatment (2)):
+ *
+ *   On an UNANCHORED format (`prefix === '' && suffix === ''`), a stored value
+ *   carrying non-digit content is OUT OF CONTRACT for counter readback.
+ *   `readAutonumberCounter`'s `undefined` for that slot is the contract, not a
+ *   gap — permanently.
+ *
+ * These cases exist to make that boundary fail loudly if a later change tries to
+ * fill the slot in: hoisting the engine's reading (last digit run) or the SQL
+ * driver's (concatenate every digit) into the shared helper would move live
+ * behavior on the other side, over record numbers that are not reclaimable once
+ * issued. #7247 refused that hoist as a rider; #7287 rejects it outright.
+ *
+ * The tests below assert only `readAutonumberCounter` — spec's declared surface.
+ * The two consumers' readings are modelled here ONLY to show WHY the slot is out
+ * of contract (they disagree on exactly the inputs the boundary excludes, and
+ * agree on the ones it admits); neither model is a contract, and the real
+ * implementations live at their own call sites.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseAutonumberFormat, renderAutonumber, readAutonumberCounter } from './autonumber-format';
+
+const NOW = new Date('2026-06-17T21:30:00.000Z');
+
+/**
+ * The engine's unanchored reading, mirrored from `readStoredAutonumberCounter`
+ * in `packages/objectql/src/engine.ts` — the LAST digit run of the value.
+ * Illustration only: this file pins nothing about the engine.
+ */
+function engineUnanchoredReading(value: string): number | undefined {
+  const runs = value.match(/\d+/g);
+  const digits = runs ? runs[runs.length - 1] : undefined;
+  return digits ? parseInt(digits, 10) : undefined;
+}
+
+/**
+ * The SQL driver's unanchored reading, mirrored from `scanMaxNumericTail` in
+ * `packages/drivers/driver-sql/src/sql-driver.ts` — EVERY digit, concatenated.
+ * Illustration only: this file pins nothing about the driver.
+ */
+function driverSqlUnanchoredReading(value: string): number | undefined {
+  const n = parseInt(value.replace(/[^0-9]/g, ''), 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+describe('the unanchored readback boundary (#7287 ruling: mixed content is out of contract)', () => {
+  it('the declared default format {0000} (#6555, PR #7265) really does render an UNANCHORED pair', () => {
+    // The premise the boundary hangs on: the default authoring shape is the one
+    // that lands in this slot, which is why the boundary is worth declaring.
+    const r = renderAutonumber({ tokens: parseAutonumberFormat('{0000}'), seq: 7, now: NOW });
+    expect(r.prefix).toBe('');
+    expect(r.suffix).toBe('');
+    expect(r.value).toBe('0007');
+  });
+
+  describe('OUT OF CONTRACT — non-digit content on an unanchored format reads as undefined', () => {
+    it.each([
+      ['A1B2', 'digits split by letters — the shape the two readings disagree on most sharply'],
+      ['CASE-12', 'a dash-separated legacy value against a bare {0000}'],
+      ['SO-2024-0007', 'the issue-body example: engine reads 7, driver-sql reads 20240007'],
+      ['2026-06-17', 'a date-looking value in a column later declared autonumber'],
+      ['INV/0042', 'a separator other than a dash — the boundary is content, not punctuation'],
+      ['0007 (void)', 'digits first, non-digit content trailing'],
+      ['v2.1', 'digits inside an unrelated version-shaped identifier'],
+      ['DRAFT', 'no digits at all — still out of contract, and still undefined'],
+    ])(
+      'out of contract: %s reads as undefined — the declared boundary, not a gap (#7287)',
+      (value) => {
+        expect(readAutonumberCounter(value, '', '')).toBeUndefined();
+      },
+    );
+
+    it.each([
+      ['A1B2'],
+      ['SO-2024-0007'],
+      ['2026-06-17'],
+      ['v2.1'],
+    ])(
+      'why %s is out of contract: the two consumers read it as DIFFERENT numbers',
+      (value) => {
+        expect(engineUnanchoredReading(value)).not.toBe(driverSqlUnanchoredReading(value));
+        // And spec declines to break the tie — that refusal IS the contract.
+        expect(readAutonumberCounter(value, '', '')).toBeUndefined();
+      },
+    );
+
+    it.each([['CASE-12', 12], ['INV/0042', 42], ['DRAFT-7', 7]])(
+      'out of contract even though the two consumers happen to agree on %s (%i)',
+      (value, agreed) => {
+        // The boundary is drawn by CONTENT, deliberately wider than the observed
+        // divergence: divergence needs TWO digit runs, so a mixed-content value
+        // carrying only one reads the same number either way. Narrowing the
+        // boundary to "values the two sides actually disagree on" would make it
+        // undecidable from the value alone — a caller would have to know which
+        // consumer is running to know whether it is in contract, which is the
+        // very "same metadata, different driver, different number" property
+        // #7287 exists to bound. So: still out of contract, still undefined.
+        expect(engineUnanchoredReading(value)).toBe(agreed);
+        expect(driverSqlUnanchoredReading(value)).toBe(agreed);
+        expect(readAutonumberCounter(value, '', '')).toBeUndefined();
+      },
+    );
+  });
+
+  describe('INSIDE the contract — pure-digit unanchored values, where both sides agree', () => {
+    it.each([['0007', 7], ['10', 10], ['0000', 0], ['123456', 123456]])(
+      'in contract: %s carries no non-digit content, so both consumers read %i',
+      (value, expected) => {
+        expect(engineUnanchoredReading(value)).toBe(expected);
+        expect(driverSqlUnanchoredReading(value)).toBe(expected);
+      },
+    );
+
+    it('what renderAutonumber itself emits for {0000} stays inside the boundary', () => {
+      // The in-contract face is the one the platform generates: an unanchored
+      // format renders pure digits, so a store the platform filled reads the
+      // same number on either side. The out-of-contract face is legacy/migrated
+      // data that arrived by some other path.
+      const tokens = parseAutonumberFormat('{0000}');
+      for (const seq of [0, 7, 42, 9999, 123456]) {
+        const { value } = renderAutonumber({ tokens, seq, now: NOW });
+        expect(engineUnanchoredReading(value)).toBe(seq);
+        expect(driverSqlUnanchoredReading(value)).toBe(seq);
+      }
+    });
+
+    it('agreement on the digits does NOT make the shared helper answer for the slot', () => {
+      // The boundary is about which INPUTS are in contract; the shared helper's
+      // declared job stays the ANCHORED inverse of renderAutonumber. Even where
+      // the two consumers agree, spec does not underwrite an unanchored reading
+      // — each side answers from its own implementation detail.
+      expect(readAutonumberCounter('0007', '', '')).toBeUndefined();
+    });
+  });
+
+  it('an anchored format is untouched by this boundary — non-digit content still reads normally there', () => {
+    // Guard against the boundary being read too widely: it is scoped to the
+    // unanchored slot. `CASE-0007` against the pair `{prefix: 'CASE-'}` is in
+    // contract and answers 7, mixed content and all.
+    expect(readAutonumberCounter('CASE-0007', 'CASE-', '')).toBe(7);
+  });
+});