fix(rest)!: /import reads a comma in a number cell only as a thousands group, refusing the rest (#20497)

[objectstack-fleet]

Fixes #20497
Clause-②: no

What changes

parseNumberCell in packages/rest/src/import-coerce.ts removed every comma before parsing, as if every comma grouped thousands. So POST /api/v1/data/:object/import stored a decimal-comma cell as a different number and reported success.

A comma is now accepted only in a well-formed thousands group: 1 to 3 leading digits, then groups of exactly three, and only before any . (1,000, 12,345.67). One anchored pattern, THOUSANDS_GROUPED_INTEGER, is tested before the strip, and the strip now runs only for that form. Every other comma makes the cell unparseable, so the row gets the importer's existing invalid_number error. That is the same code the plain write doors already answer for these cells. No locale is guessed, and there is no new error code and no decimal-separator option, as triage directed (5877481993). The rule is stated in the parseNumberCell docblock, where the reader's tolerances are listed.

Measured through the real route (JSON rows, writeMode: 'insert') on InMemoryDriver and on SqlDriver (better-sqlite3). Both drivers answered the same on every cell, at base 9449512a31 and at head c76a3c95f2:

cell	base: stored · import answer	head	plain POST (engine insert), both trees
'3,14'	314 · ok 1, errors 0	row refused, invalid_number, nothing stored	VALIDATION_FAILED / invalid_number
'1,5'	15 · ok 1, errors 0	row refused, invalid_number, nothing stored	same
'1.000,5'	1.0005 · ok 1, errors 0	row refused, invalid_number, nothing stored	same
'1,2,3'	123 · ok 1, errors 0	row refused, invalid_number, nothing stored	same
'1,000'	1000	1000 (unchanged)	refused (the import-only tolerance stays)
'12,345.67'	12345.67	12345.67 (unchanged)	refused
'(1,234)'	-1234	-1234 (unchanged)	refused

PM hypotheses, measured

• H0 holds. On current main (9449512a31), the four cells imported as 314, 15, 1.0005 and 123 with ok 1, errors 0, on InMemoryDriver and on SQLite. The table above has the readings.
• H1 holds. The one line s.replace(/,/g, '') is the whole cause. Before/after census through coerceRow: before is rest's built dist at the base, after is the head's src. It covers 79 rows: the spec grammar's 41 NUMERIC_STRING_GRAMMAR_CASES rows, 18 documented or control forms, and 20 comma probes.
  • Grammar rows. 1 of 41 changed: '1.000,5' went from 1.0005 to refused. The other 7 grammar-refused rows the reader admits keep their reading: ' 12 ', '12\n', '\t-3', '1,000', '+5', '.5' and '007'.
  • Documented and control forms. 0 of 18 changed: 1,234, $1,000, ¥2,500.75, €1,000, £1,000, ￥1,000, 25%, (1,234), (100), 1,234.5, 12,345.67, 1,000, -1,234, +1,234, 1,234,567.89, $ 1,000, 1,234% and 1,000e3.
  • Comma probes. 18 of 20 changed, each from a stripped number to a refusal: 3,14, 1,5, 1.000,5, 1,2,3, 0,5, 1,23, 1234,567, 1,0000, ,123, -,123, .5,000, 1,000,, 12,345.6,7, 12,34,567, 1,00,000, (3,14), $1,5 and 1,5%. The other 2 (1,000. and 1 ,000) were already refused.
  • Overall. 19 rows changed, every one from a stored number to a refusal. No row moved the other way, and no admitted value changed.
• H2 holds. A refused cell's row carries code: 'invalid_number', the code the importer already uses for abc, with the importer's existing sentence (Amount: "3,14" is not a number, from the catalog's import_invalid_number key). The plain create door answers 400 VALIDATION_FAILED with field code invalid_number for the same cells, and that is pinned beside the import pins. No new code.
• H3 holds, in the direction expected. The ablation removed the grouping guard, which restores the unconditional strip. It ran via scripts/ablation-replace.mjs in wrap mode, at head c76a3c95f2. The anchor went 1 to 0 and the blob went afaf602da192 to a06963b8c44c, so the mutation landed. Result: Tests 24 failed | 46 passed (70).
  • Red: every refused-cell assertion and nothing else. That is 18 parseNumberCell refusal cases, the 4 per-cell import pins, the CSV leg and the dry-run leg.
  • Green: every admitted control. That is 3 import pins, 8 parseNumberCell admitted cases, and the plain-door parity pin.
  • Restore proven. Blob after restore equals HEAD (afaf602da192), git diff HEAD is empty, and the marker count is 0. No build was needed: the pins reach import-coerce.ts through relative imports (./rest-server, ./import-coerce), never through a dist/.

Tests

• packages/rest/src/import-number-thousands-group.test.ts (new) goes through the real /import route over SqlDriver (better-sqlite3 :memory:). It has 10 cases:
  • each of the four cells is refused as its own row's invalid_number, with a sibling row still written;
  • each admitted control (1,000, 12,345.67, (1,234)) is stored as its number;
  • the same verdicts hold for quoted CSV cells;
  • the dry run predicts the refusals and persists nothing;
  • the plain create door answers the same code.
• packages/rest/src/import-coerce.test.ts gets the parseNumberCell case table: 8 admitted groupings and 18 refused comma forms.
• At c76a3c95f2, run as pnpm --filter @objectstack/rest test --maxWorkers=2: Test Files 220 passed (220) and Tests 4211 passed | 40 skipped (4251). test:repo passed 1 file with 8 tests.
• pnpm --filter @objectstack/rest typecheck exits 0: tsc --noEmit, then check:test-typecheck: OK, with 0 errors. Both test files are in the tsconfig.test.json program (--listFilesOnly).

Gates

• Build. turbo run build ran first for @objectstack/rest..., then for all of ./packages/* and ./packages/*/*, because two gates read the whole built tree. Result: 71/71 tasks.
• Derived gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 61 commands at c76a3c95f2. All 61 ran with exit 0. Reconciled with --ran: 61 derived, 61 run, 0 NOT-MEASURED, 0 UNRUN.
• Other gates, all exit 0. pnpm lint (the whole repository, 29 s, no narrowing) and node scripts/check-issue-citations.mjs --base origin/main (origin/main is still 9449512a31, the branch point, so there was nothing to merge).
• Changeset gates. check-adr-0087-registration names this PR's changeset as [BREAKING+clause-②-narrowing] not-required (no-migration-prescription). check-changeset-no-major reports no major.

Declared narrowing — verification ran UNLOCKED. scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the command below was run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for this
run, nor for any sibling agent in this container while it ran.

pnpm turbo run build --filter='@objectstack/rest...' --concurrency=2 --output-logs=errors-only
pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2 --output-logs=errors-only
pnpm --filter @objectstack/rest test --maxWorkers=2
pnpm --filter @objectstack/rest test:repo --maxWorkers=2
pnpm --filter @objectstack/rest typecheck
pnpm --filter @objectstack/rest exec vitest run --project local --maxWorkers=2 (the targeted pin files, and the ablation's wrapped run)

(The entry point printed this wording once for each command above. It is pasted once here, with every command it covered.)

Changeset

.changeset/20497-import-number-thousands-group.md: @objectstack/rest minor, with a line-initial Clause-②: no (narrowing), a BREAKING paragraph giving each refused cell shape FROM → TO, and the ADR-0087 disposition not-required (no-migration-prescription). The shape follows PR #20218 and PR #20231.

Acceptance notes

• The InMemoryDriver leg is measured, not pinned. This departs from triage's pin list. Triage asked for /import pins on memory and SQLite. @objectstack/driver-memory's test consumers are a ruled, ledgered set (scripts/driver-memory-census.ledger.json, gated by pnpm check:driver-memory-census), and the gate says a new consumer is a maintainer ruling. A first cut added the driver as a packages/rest devDependency with a source alias. The census gate refused it by name: x LEDGERED: packages/rest/src/import-number-thousands-group.test.ts:31 binds @objectstack/driver-memory (import) and the ledger does not cover it. That cut was withdrawn, so the diff is back to the claim's file surface. The cell is judged by the importer's reader before any driver is reached, so one verdict holds on every driver. The memory readings at base and head are recorded in the table above and in the pin's header. If a permanent memory arm is wanted, it goes through the census ruling first.
• Grouping by twos is now refused (12,34,567, 1,00,000). These used to import as the number they denote. The changeset names this as the one case where the narrowing refuses a cell that was read correctly before, because a two-digit group cannot be told apart from a decimal comma.
• The import template card feat(rest): 导出接口新增 ?template=true —— 输出只含「可填列」的 xlsx 导入模板 #18386 should follow this wording. Its value-domain row for number lists 1,234 among the tolerated forms. It should say that a comma is read only as a thousands group (1 to 3 leading digits, then groups of exactly three, only before any .), and that a decimal comma such as 3,14 is refused, never guessed. That card is assigned elsewhere and is not edited here.
• A spec comment now overstates the reader. The module header of packages/spec/src/data/filter-number-comparand-declared-type.ts says, in the parenthetical under its refused digit-separator forms, that the CSV import route's cell reader strips such punctuation before it parses. For 1.000,5 that is no longer true. It was already untrue for 1_000 and 1 000, which the reader refused before this change too. This is a comment in the spec seat's surface. There is no carrier, so it is noted here only.
• objectui's Import Wizard preview disagrees with the server on grouped numbers. The preview judges numeric cells with a bare Number() (packages/plugin-grid/src/ImportWizard.tsx in objectui, the number/currency/percent case). So it flags 1,000 as invalid while the server admits it. That disagreement predates this PR and is unchanged by it. For the four cells here, preview and server now agree: both refuse. I read this in objectui's source and did not measure it through the UI. There is no carrier, so it is noted here only.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

2 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 15 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9449512a31f61cfb85f6b6934f2bf0d556c8111f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0407d41f6ca81d3c5d27931689f30341fdcdcedc — the merge of head c76a3c95f27e053b6c9fe4f9066d7b06d5860325 into base 9449512a31f61cfb85f6b6934f2bf0d556c8111f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 0407d41f6ca81d3c5d27931689f30341fdcdcedc && git checkout 0407d41f6ca81d3c5d27931689f30341fdcdcedc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9449512a31f61cfb85f6b6934f2bf0d556c8111f c76a3c95f27e053b6c9fe4f9066d7b06d5860325 && git checkout -B drift-repro 9449512a31f61cfb85f6b6934f2bf0d556c8111f && git merge --no-ff c76a3c95f27e053b6c9fe4f9066d7b06d5860325

node scripts/docs-audit/affected-docs.mjs --json 9449512a31f61cfb85f6b6934f2bf0d556c8111f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c76a3c95f27e053b6c9fe4f9066d7b06d5860325
Local-runs: none

① Derived judgments

Inputs read: card #20497 (body; comments 5877481993 triage grade, 5878411415 claim, 5879111895 os-dev-report, 5879135639 seat answer A), PR #20517 (body, 4-file list, net diff against main at 9449512a31), and the check-runs on the head. The card carries no maintainer ruling; the binding direction is triage's grade 5877481993, and every judgment below is against it.

• The one code change is the comma guard in parseNumberCell (packages/rest/src/import-coerce.ts): if (s.includes(',')) { if (!THOUSANDS_GROUPED_INTEGER.test(s)) return undefined; s = s.replace(/,/g, ''); } replaces the unconditional s.replace(/,/g, ''). THOUSANDS_GROUPED_INTEGER = /^[+-]?\d{1,3}(?:,\d{3})+(?![\d,])[^,]*$/, a module-private const, tested after the parentheses, currency-symbol and % strips and before the existing numeric grammar. Right.
• (1) The accepted comma form is exactly triage's. Read off the pattern: an optional sign, 1 to 3 leading digits, one or more groups of exactly three digits, then no digit or comma directly after the last group and no comma anywhere later in the cell. So a group may be followed only by the end of the cell, a . fraction or an exponent, and a comma after any . is refused. Walked by hand: 1,000 12,345.67 1,234,567.89 -1,234 (1,234) $1,000 1,234% 1,000e3 admitted; 3,14 1,5 1.000,5 1,2,3 0,5 1,23 1,0000 1234,567 ,123 -,123 1,000, .5,000 12,345.6,7 12,34,567 1,00,000 (3,14) $1,5 1,5% refused. The lookahead is what refuses 1,0000 (four digits after a comma), which [^,]*$ alone would not. No locale is guessed and no decimal-separator option exists in the diff. Right.
• (2) No previously admitted non-comma form is refused, and no refused form is admitted. Structural, not only measured: the guard sits inside if (s.includes(',')), so a cell without a comma takes the identical path as at the base; and when the guard passes, the strip is byte-identical to the old one, so the head's accept set is a subset of the base's. The only cells whose reading changed are comma cells that fail the pattern, every one from a stored number to a refusal. The one class that was read to the number the author meant and is now refused, two-digit grouping (12,34,567, 1,00,000), is refused by the grade's own terms (groups of exactly 3, no locale guessing), and the changeset names it. Right.
• (3) The refused cell's row error is the existing shape, with no new code. parseNumberCell returning undefined reaches the untouched NUMBER_TYPES branch of the cell coercer, coerceError(meta, field, 'invalid_number', 'import_invalid_number', raw, ctx) (base line 444, outside every hunk). No error code, catalog key or sentence is added; the diff adds one private const and docblock text. Right.
• Surface. parseNumberCell is not exported from packages/rest/src/index.ts and has no caller outside its own module; the published carriers of the narrowed reader are the /import route and the exported coerceRow. A JSON number and a numeric xlsx cell keep the typeof raw === 'number' early return, untouched. No export is added, removed or renamed. Right.
• Docblock. The rule is written in the parseNumberCell docblock, where the reader's tolerances are listed, as the grade asked. Right.
• Pins against the grade's cells. Unit table in import-coerce.test.ts: 8 admitted groupings, 18 refused comma forms, the card's four included. Route pins in the new import-number-thousands-group.test.ts, through the real RestServer route over SqlDriver (better-sqlite3 :memory:): each of 3,14 1,5 1.000,5 1,2,3 refused as its own row's invalid_number with the sibling row written and nothing stored; 1,000 / 12,345.67 / (1,234) stored as 1000 / 12345.67 / -1234; the same verdicts for quoted CSV cells; the dry run refuses and persists nothing; the plain create door answers VALIDATION_FAILED / invalid_number for the same cells. Every refused and every admitted cell the grade names is pinned. The memory arm is the one departure from the pin list, judged under ③. Right.
• File surface equals the claim's (import-coerce.ts, its test, one new test under packages/rest/src/, one @objectstack/rest changeset). The withdrawn driver-memory cut (package.json, lockfile, vitest alias) is not in the net diff. Right.

Check-runs on the head, read at 21:39 UTC, newest run per name, 33 runs: 28 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke opt-in), 2 in progress (Lint & Repo Gates; Test Core (4/6)), 0 failure. Check Changeset success is the verdict of pr-automation's changeset-check job, which runs check-empty-changeset, check-adr-0087-registration and check-changeset-no-major against the merge base. No verdict is inferred for the two running checks.

② Semver level

• .changeset/20497-import-number-thousands-group.md: '@objectstack/rest': minor, the only touched package, and it publishes. The body carries a line-initial Clause-②: no (narrowing), a **BREAKING for callers of the import door.** paragraph with a per-shape FROM/TO remedy, a "What is not affected" paragraph, and exactly one adr-0087: not-required (no-migration-prescription) marker.
• (4) The level and the Clause-② narrowing line satisfy ADR-0087 and the lane's precedents. The diff narrows a published accept set (wire behaviour on /import, and coerceRow), which is no (narrowing) under scripts/pm/clause2-line.mjs (NOT a widening, but breaking) and BREAKING under AGENTS.md Post-Task Checklist step 3. ADR-0087's amended level half (2026-09-13, [Decision] 两条裁决援引同一个 launch-window convention，却给出相反的 changeset 等级（minor vs major）—— 退役一个可写键到底发哪一级？ #18003): pre-GA a break ships minor carrying the BREAKING banner and its disposition, and major is refused by check-changeset-no-major. PR fix(runtime): the package install door parses its whole body through PackageInstallBodySchema #20218 (@objectstack/runtime minor, Clause-②: no (narrowing), a BREAKING paragraph with an inline FROM/TO remedy per refused shape, not-required (no-migration-prescription)) and PR fix(cli): refuse a present non-array packages in the stack-collection and docs readers #20231 (@objectstack/cli minor, the same lines) are the same shape in every line that matters. The disposition is legal by the gate's own reading: nothing authorable is removed, renamed or reshaped, and the body carries no FROM → TO placeholder label, no arrow rewrite and no rewrite table (the only arrow-shaped bytes are the marker's own comment close), so the prescription detector finds nothing, exactly as on fix(runtime): the package install door parses its whole body through PackageInstallBodySchema #20218's inline prose. Check Changeset success on this head is the gate's verdict.
• The PR body's line is bare Clause-②: no, the claim's spelling; the arm rides on the changeset, which is the carrier check-adr-0087-registration reads. Both precedents also spelled no (narrowing) in the PR body; a bare no is a legal declaration (an absent arm declares no direction) and costs the level axis nothing during the window. A note, not a defect.
• Level: right. Not patch, because (narrowing) is breaking; not major, because the launch window forbids it.

③ Boundary flags

Dev flags (os-dev-report 5879111895), each answered or escalated:

1. The memory arm is measured, not pinned (deviation 1, and the one open question). Seat-answered A (5879135639): the driver-memory census is a maintainer-ruled gate and it refused the new consumer by name; the cell is judged in parseNumberCell before any driver is reached. Judged here on coverage only: the delivered pins cover every refused and every admitted cell of the grade at the real route (SQLite) plus the reader table, and the memory readings at base and head are recorded in the pin's header and the PR body. Answered.
2. PR opened with gh pr create (GraphQL) rather than REST. Process only; no effect on the diff or its contract. Noted.
3. One targeted vitest run outside os-verify-lock.sh, and 4. the UNLOCKED disclosure pasted once for six commands. Process only; the disclosure is in the PR body. Noted.
4. H3 red set is 24, not "exactly four". The extra reds are the 18 unit-table refusals and the CSV and dry-run legs, all refused-cell assertions; every admitted control stayed green. The substance holds. Noted.

Out-of-scope findings, escalated (none blocks this PR):

• feat(rest): 导出接口新增 ?template=true —— 输出只含「可填列」的 xlsx 导入模板 #18386 wording. Triage's grade said the import template card's 1,234 row should follow this rule; the dev did not write to a card assigned elsewhere. Escalated to the seat: one comment on feat(rest): 导出接口新增 ?template=true —— 输出只含「可填列」的 xlsx 导入模板 #18386 pointing at this changeset's rule.
• Spec module header of packages/spec/src/data/filter-number-comparand-declared-type.ts says the CSV import reader strips such punctuation before it parses; that is now false for 1.000,5 (and was already false for 1_000 and 1 000). packages/spec/** was read-only for this card and there is no carrier. Escalated to the seat for a spec-lane docs follow-up (the fix(runtime): the package install door parses its whole body through PackageInstallBodySchema #20218 → [finding] once PR #20218 lands, PackageInstallBodySchema's published docblock still says the install door answers 201 to residual classes 1b, 2, 3 and 4, which it then refuses 400 #20219 pattern).
• objectui ImportWizard.tsx preview judges numeric cells with a bare Number(), so it flags 1,000 the server admits. Pre-existing, unchanged by this PR, read from source only, no reach. Noted; no action from this PR.

Landing note: the PASS is on the contract. Two check-runs were still in progress at the read, and landing waits for them to complete green.

Implemented-by: claude/issue-20497-import-decimal-comma
Reviewed-by: local_1d2a197c-c20e-4e90-9be8-413d4d432289

VERDICT: PASS