refactor(spec,objectql,driver-sql): share the autonumber counter readback as spec's inverse of renderAutonumber (#6560) - #7247
Merged
Conversation
…back as spec's inverse of renderAutonumber (#6560) `packages/spec` gains `readAutonumberCounter(value, prefix, suffix)`, the declared inverse of `renderAutonumber`, and the two hand-written copies of that readback — one in the ObjectQL engine, one in the SQL driver — are replaced by calls to it. Pure refactor: zero behaviour change. PR #6553 (#6468) taught both seeding paths to locate a counter by the format's declared prefix/suffix pair, but landed that reading as two independent copies of the same four lines. That is the exact shape of the defect they were fixing: two hand-written readings of one composition rule had already drifted into two different wrong answers over one dataset, so the record-number band depended on which driver ran. Only the ANCHORED rule — the one both sides must apply identically — moved. The unanchored case stays per-side because the two sides deliberately differ there (engine: last digit run; driver: every digit concatenated), and #6553 preserved both byte-for-byte; spec returns undefined rather than claim an agreement that does not exist. The packages/runtime cross-side parity suite is unmodified and passes as-is, which is the evidence the semantics moved without changing. Per the maintainer's ruling on #6560 (2026-08-08 ×2, re-confirmed 2026-08-10): non-authorable export, no Zod, no new vocabulary — api-surface bookkeeping plus two call-site swaps. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DqCMGGYsvFxMJSU4PMSPo3
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 3 package(s): 111 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
August 10, 2026 04:57
This was referenced Aug 10, 2026
This was referenced Aug 10, 2026
Merged
akarma-synetal
pushed a commit
to akarma-synetal/framework
that referenced
this pull request
Aug 17, 2026
…ary (objectstack-ai#7287) (objectstack-ai#7405) Maintainer ruling on objectstack-ai#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 objectstack-ai#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: objectstack-ai#6555's Route-3 ruling (PR objectstack-ai#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 objectstack-ai#7287 Claude-Session: https://claude.ai/code/session_0184Hrx9PcaQ2KMMt88DRZ2c Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
packages/specgainsreadAutonumberCounter(value, prefix, suffix)— the declared inverse ofrenderAutonumber— and the two hand-written copies of that readback (ObjectQL engine, SQL driver) are replaced by calls to it. Pure refactor: zero behaviour change, no authorable surface, no Zod, no new vocabulary.Closes #6560The rulings this executes
Three consistent maintainer rulings on #6560, quoted verbatim (Chinese lines untranslated):
packages/specgains the pure-function export (e.g.readAutonumberCounter(value, prefix, suffix)) as the inverse ofrenderAutonumber, and both the engine and driver-sql sides call it, retiring the two hand-written ~4-line readbacks. Non-authorable, no Zod, no new vocabulary; api-surface bookkeeping only. The runtime cross-side parity test stays as the behavioral guard."packages/specdeliberately carries contract-semantics pure functions when a rule must be bit-identical across independent implementations (renderAutonumberitself, thefoldAsciiCasefamily JS 求值面全体拒收$icontains(driver-memory 两面 / driver-mongodb / objectqlhaving/ formula）—— SQL 族已实现,同一 filter 在内存 double 上抛错 #6520 → PR feat(spec,drivers,objectql,analytics,formula): $icontains reaches every JS evaluation face (#6520) #7123,valueSchemaForADR-0104 D1,isActionParamValuePresentPR fix(spec): validate action param defaultValue against the param's own value contract (#6970) #7126).Nothing was left to decide; this PR is execution only.
Premise re-measurement (on fresh
origin/main@2e4274d)The card's premise was two hand-written ~4-line readback copies, one per side, as PR #6553 left them. Re-measured before writing code — it has partly moved, and the finding strengthens the card rather than voiding it:
maintodaypackages/objectqlreadAutonumberCounter(engine.ts) by #6806, which added a second engine consumer (adoptExplicitAutonumber, the adopt-on-exempt-write resync) alongside the seeding scanpackages/drivers/driver-sqlscanMaxNumericTail, byte-for-byte as PR #6553 left itSo the cross-package duplication — the thing #6560 is about — still stood in full, and had meanwhile grown a third caller behind objectql's copy. Nobody had unified them:
packages/speccarried no such export (confirmed againstapi-surface/data.jsonbefore the change). Proceeding was correct; the STOP condition ("someone already unified them") did not fire.A repo-wide sweep for other copies of the rule (
endsWith(suffix),scanMaxNumericTail) returned only these two sites plus unrelated string-suffix matching inregistry.ts,type-compat.ts,analytics-service.ts,memory-analytics.ts.Changes
packages/spec/src/data/autonumber-format.tsreadAutonumberCounter(value, prefix, suffix): number | undefined, placed directly afterrenderAutonumber. TSDoc cites #6560's ruling and PR #6553, states it is the inverse companion ofrenderAutonumberand that both sides MUST call it rather than re-derivepackages/spec/src/data/autonumber-format.test.tspackages/objectql/src/engine.tsreadAutonumberCounter→readStoredAutonumberCounter, now a thin wrapper: anchored ⇒ delegate to spec, unanchored ⇒ this engine's own legacy reading. Both call sites (seeding scan, #6806 resync) follow the rename; TSDoc updatedpackages/drivers/driver-sql/src/sql-driver.tsscanMaxNumericTail(6 lines) → one call to spec's export; TSDoc updatedpackages/objectql/src/engine-autonumber-resync.test.tspackages/spec/api-surface/data.json,packages/spec/export-origins/data.json.changeset/autonumber-counter-readback-shared.md@objectstack/spec,@objectstack/objectql,@objectstack/driver-sqlCall sites replaced
packages/drivers/driver-sql/src/sql-driver.ts→scanMaxNumericTail— the copy PR fix(objectql,driver-sql): 播种解析按声明的 suffix 定位计数器,两侧收敛 (#6468) #6553 wrote, replaced directly.packages/objectql/src/engine.ts→readStoredAutonumberCounter, behind which sit two engine consumers:seedAutonumber's scan andadoptExplicitAutonumber(Engine fallback autonumber: counter seeds once and never resyncs; collisions burn numbers with no recheck (residual split from #5495) #6806).One deliberate design call: only the ANCHORED rule moved
The shared rule — the one both sides must apply identically — is the anchored one: the counter is the digit run at the start of what follows the rendered
prefix, after stripping the renderedsuffixwhen the value carries it (stripped when it matches, never required to match, since one counter spans the years a dynamic suffix renders). Out-of-scope values read asundefined, which also preserves the SQL driver's JS-side re-check of aLIKEthat matched looser thanstartsWithunder a case-insensitive collation.The unanchored case (neither affix declared) deliberately stays per-side, because the two sides genuinely differ there and PR #6553 preserved both byte-for-byte on purpose:
'SO-2024-0007'→ 7)'SO-2024-0007'→ 20240007)Both readings are pinned by existing tests on their own sides. Spec therefore returns
undefinedfor an unanchored slot rather than picking one of the two — hoisting either would make the shared contract claim an agreement that does not exist, which is a subtler instance of the very mirror-drift #6560 retires. Each side documents its own fallback at its own call site.Zero-behaviour-change proof
Every call site keeps its existing guards and its existing result for every input. The
packages/runtimecross-side parity suite (autonumber-seed-cross-side-parity.integration.test.ts) — the behavioural guard the ruling names — is unmodified in this PR and passes as-is. That is the evidence: the semantics moved packages without changing.Reverse-verification framing, stated honestly up front: this is a refactor, not a fix, so there is no red-then-green to show. The prediction was that every pin stays green on both sides before and after, and that is what the runs report — no fabricated failing baseline.
Gates
All run in this worktree on the rebuilt
dist(heavy runs serialised onflock /tmp/os-heavy-verify.lock; no lock contention observed — this session was the only holder).@objectstack/runtimetest — the parity suite, unchanged@objectstack/objectqltest@objectstack/driver-sqltest@objectstack/spectestcheck:generated(all 11 artifacts)check:api-surface(re-run on rebuiltdist)check:export-origins(self-test + check)check:exported-anyanycheck:dual-source-exportstypecheck— spec (incl. test layer), objectql, driver-sql, runtimeBuild discipline (#7122 stale-dist trap):
pnpm --filter @objectstack/spec buildwith real.d.tsran beforegen:api-surface/gen:export-origins, and both snapshots were then re-verified a second time against a full--filter @objectstack/runtime...rebuild.OS_SKIP_DTSwas not used for any build whose output a gate reads.Dual-snapshot rule (new public export ⇒ both):
api-surface/data.jsonandexport-origins/data.json, one added line each, zero removals, one shard each.api-surface/data.json:+ "readAutonumberCounter (function)"export-origins/data.json:+ "readAutonumberCounter": "src/data/autonumber-format.ts#readAutonumberCounter (function)"New unit tests (spec, 15 cases)
Round-trip against
renderAutonumberover 5 formats + a counter grown past the pad width; the #6468 defect inputs directly (003-2026→ 3, not 2026;001-2026→ 1, not 12026); suffix stripped-when-matching (007-2025→ 7) including a digit-leading suffix; leading zeros; and theundefinedcases the card called for — unanchored slot, foreign scope, value shorter than the affixes, non-numeric tail, value that is entirely the suffix, prefix-exactness, and a counter too long to parse finitely.Special inspection items for the PM
undefinedfor('', ''). If the preference is instead that spec carry the engine's unanchored reading too, that is a one-line change here plus a driver-side behaviour change — which would no longer be a zero-behaviour-change refactor, hence not taken.readAutonumberCounter; objectql's now-narrower local wrapper isreadStoredAutonumberCounterto avoid shadowing the import.content/docs/releases/and nodocs/adr/**touched.No auto-merge — the PM lands serially.
Generated by Claude Code