feat(spec): the number-comparand declared-type door's contract and the platform's numeric grammar

[objectstack-fleet]

Fixes #20336
Clause-②: yes

What this adds

This is lane (1) of the split triage routed on #15661's precedent: the contract for the number-comparand declared-type door, plus the platform's one numeric grammar for a string. It adds one module to @objectstack/spec/data, filter-number-comparand-declared-type.ts, beside filter-text-operator-declared-type.ts, together with its test, the barrel line, the regenerated api-surface/data.json and export-origins/data.json, and a minor changeset. No door is written here, and no evaluator changes. The engine door and its three-driver, REST and per-aggregation filter pins are #20351's, which stays open and is Blocked-by: this card. The write side's string half adopts the same grammar under #20309, which also stays open.

The new exports (27, all additive; api-surface/data.json +27 / -0):

• The grammar
  • NUMERIC_STRING_PATTERN.
  • parseNumericString(s) returns the number, or undefined.
  • readNumericString(s) returns the number, or one of eight named forms (NON_NUMERIC_STRING_FORMS).
  • NUMERIC_STRING_GRAMMAR_CASES is the table of forms: 41 rows, each with its reason.
• The verdict
  • numberComparandFieldVerdict(field) returns judged / not-judged / deferred.
  • numberComparandDoorVerdict(field, comparand) returns one of:
    • door-refusal (INVALID_FILTER / 400, with a form);
    • narrows (with the number);
    • passes;
    • deferred.
  • NUMBER_COMPARAND_DOOR_JUDGED_TYPES is NUMERIC_VALUE_TYPES itself, by identity.
  • NUMBER_COMPARAND_DOOR_SCALAR_OPERATORS / NUMBER_COMPARAND_DOOR_LIST_OPERATORS.
• The words: numberComparandRefusalMessage(site, context?). It names the field, the declared type, the bounded comparand, its position and what is wrong with the string, all ahead of the remedy.
• For the engine suite
  • NUMBER_COMPARAND_DOOR_FIXTURE has one field per FieldType, plus the formula variants.
  • NUMBER_COMPARAND_DOOR_CASES has 136 derived cases: 52 refusals, 23 narrowings, 60 passes, 1 deferred.

Decisions this contract takes (each argued in the module header; the four-axis reasons are below)

1. The grammar is a JSON number literal that names a finite double. Its forms were checked one by one against the card's A2 list (NUMERIC_STRING_GRAMMAR_CASES is the record):

   • Admitted: "12", "-3", "12.5", "0.10", "1e3", "2.5E+3", "1e-7", "1e+21".
     • Every String(n) for a finite n is admitted and parses back to n. This is pinned as a round-trip property over 418 numbers.
     • So a URL query is never refused: ?amount=5 is lowered to an implicit { amount: "5" } in metadata-protocol's findData.
     • Neither is URLSearchParams, nor a plain CSV cell.
     • Exponents are admitted because String(1e-7) is "1e-7".
   • Refused, and Number() would have read them: "", " ", " 12 ", "0x10", "0o17", "0b101", "+5", ".5", "5.", "007".
     • Hex and whitespace-padded strings are refused by name in record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's triage direction.
     • The rest are refused for their spelling alone.
     • The test pins exactly this list, so that the narrowing against Number() stays deliberate.
   • Refused: "Infinity", "NaN", "1e400", "1,000", "1.000,5", "1_000", "1 000", full-width digits, U+2212, and every {placeholder}.

2. The door narrows a numeric string to its number, copy-on-write.

   • This is the pattern the comparand-type door already uses for an exact-range bigint, and the write side's "store the parsed number".
   • Left as a string, "12" is read three ways:
     • JS loose equality and relational comparison coerce it (driver-memory's matcher, read at source).
     • SQLite applies numeric affinity.
     • driver-mongodb compares by BSON type: its filter compiler coerces temporal comparands only (read at source).

3. summary is judged. Its column is numeric on every SQL dialect: numericColumnFor is defined for every judged type, and that is pinned. The write door exempts summary through COMPUTED_VALUE_TYPES, but that set answers who writes, not what may be compared. This answers A1.

4. formula is judged by its returnType, through the text door's own FORMULA_RETURN_TYPE_AS_FIELD_TYPE:

   • number is judged;
   • text, boolean and date are not number fields;
   • an absent returnType is deferred.

   As with the text door, no formula filter reaches the engine seam, because the unmaterializable-field door refuses every one of them first with INVALID_FIELD. The case table says the engine suite must partition those rows out. This also answers A1.

5. Judged positions: implicit equality; $eq / $ne / $gt / $gte / $lt / $lte; and each member of $in / $nin / $between.

   • Pinned: these, the seven text operators, and $null / $exists partition FieldOperatorsSchema's keys exactly.
   • Only string comparands are judged. A number, null, a Date, a boolean or a bigint passes.

6. A {placeholder} against a number field is refused, not stepped around.

   • Every filter token resolves to a user or organization id, a YYYY-MM-DD day or an ISO instant (resolveFilterToken in @objectstack/core). None of these is numeric, so a resolved token reaches PostgreSQL as the same 500.
   • The field-aware doors run before the token resolver.

7. A blank string is refused.

   • On the write side, a blank becomes null before the number arm (record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308).
   • On the read side, is_empty lowers to $null, and [Decision] what 「is empty」 means on a text column and on a multi-value column: null only (the spec's lowering today), or null OR '' / [] — three objectui builders disagree, and a stored sharing rule's rows depend on the answer #20311's ruling B keeps a number field on null alone.
   • objectui drops rows whose value is empty before they reach the server: viewFilterFold.ts and ListView.convertFilterGroupToAST, read at objectui 9f0c84a. So the console sends no { amount: "" }.

8. The words and the envelope (A4): no new error code. INVALID_FILTER / 400 is spelled as a literal, as filter-comparand-type.ts does, and pinned to StandardErrorCode. Each form's clause states only what holds for that form, so "+5" is not claimed to diverge between backends. Every refusal in the case table fits inside the 500-character client bound, and that is pinned.

Four-axis reasons (for the grammar and the narrowing)

• Real business need: the measured producers of numeric strings.
  • Read side: REST query parameters, lowered to implicit filters (metadata-protocol findData).
  • Write side: objectui's CSV-import legacy fallback (census 5863923799 on record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309).
  • Both carry what String(n) or a spreadsheet writes for a plain number. Every such form is admitted.
  • No measured producer writes +5, .5, 5. or 007. The objectui filter builder sends JS numbers (convertScalarToFamily).
• Long-term soundness: one grammar in one place, read by both doors. It is externally specified (RFC 8259 §6), so it is one sentence. Narrowing on the read side mirrors the write side's "store the parsed number", so there is one reading per string.
• Keeping AI from writing wrong metadata or code: the contract is tightened, never loosened.
  • Every form the backends read differently is refused loudly, with a named form and a remedy: blank, padded, hex, Infinity/NaN, locale separators, placeholders.
  • Nothing is silently coerced beyond the one declared conversion.
• No scope creep at the startup stage: one module, no new error code, no gate, no door. The engine door stays objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351's.

Premise check (rule 6)

• normalizeFilterComparandTypes takes no schema. This was confirmed at ab6fb027, which is why this is a new module (the triage retriage route).
• The precedent's shape matches A1: sets referenced by identity, a pure verdict, a fixture, and a derived case table.
• A3 holds: the verdict needs no spec change beyond the new module. @objectstack/objectql imports @objectstack/spec/data already. Its build closure builds against this spec (turbo, 14/14 tasks at b49a49b0), and check:lean-entry-closure holds its admitted set (15 packages).
• No package imports the new module yet. git grep -l "filter-number-comparand-declared-type" -- packages finds only the barrel, the module's own test and the generated export-origins/data.json shard.

Tests (at b49a49b0 unless noted)

• pnpm --filter @objectstack/spec typecheck: exit 0. check:test-typecheck OK, with the new test file compiled and no debt added.
• vitest run --project local (spec test): 562 files, 16551 tests passed (1 todo).
• vitest run --project repo (spec test:repo): 35 files, 634 tests passed. It also passed at a5680789, before the main merge.
• The new test file: 34 tests. It pins these, in both directions:
  • the grammar table;
  • the round-trip property;
  • the stricter-than-Number() list;
  • the FieldType census;
  • summary's numeric column;
  • the operator partition;
  • the envelope literal;
  • that every form's words differ and carry no tracker number;
  • the 500-character bound and front-loading;
  • fixture legality (FieldSchema / ObjectSchema);
  • the case-table agreement with the verdict;
  • parseFilterAST accepting every case.
• pnpm --filter @objectstack/spec check:generated at b49a49b0, after rebuilding from the merged tree: all 15 artifacts are up to date.

Gates (dispatch-gates --commands --repo objectstack-ai/objectstack at b49a49b0: 85 derived)

• 83 exited 0, and 2 are NOT MEASURED (exit 3, PREREQUISITE NOT MET):

  • check:dual-build-cjs-loads: needs every package built.
  • check:type-check-debt: needs the full build closure.

  CI runs both.

• dispatch-gates --ran: 85 derived families are accounted for (83 run, 2 NOT-MEASURED, derived from the recorded exit 3), 0 UNRUN.

• For comparison, the dispatch list derived at ab6fb027 had 72 lines. The diff and changeset added 13 families, all of them run above:

  • check-empty-changeset ×2
  • release-rehearsal-clone --self-test
  • spec check:generated
  • check:engine-double-contract
  • check:objectql-double-limit
  • check:objectui-changeset
  • check:pm-changeset-deadline-census
  • check:pm-widening-tells
  • check:query-options-erasure
  • check:type-check-coverage
  • check:type-check-debt
  • check:where-matcher

• On the first pass these gates needed a prerequisite and were rerun green:

  • check-plugin-teardown-shape --self-test needed its pinned fixture commit fetched at depth 1 on this shallow clone.
  • check:doc-formula-expressions and check:lean-entry-closure needed the @objectstack/objectql closure built.

Acceptance notes

• The door and its pins are objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351's. The case table's census comparands are chosen so that no other door on the seam refuses them: "2026-01-01" / "12:00" for the temporal fields, "abc" otherwise. That choice is a design claim for objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351 to measure, not something measured here.
• Not measured live in this change:
  • PostgreSQL's reading of the admitted and refused forms (documented numeric input only);
  • driver-mongodb's numeric-string answer (read at source);
  • SQLite's affinity on read comparands (the write-side cells were measured on record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309).
• Out of this card's scope, noted and not filed: a boolean or a Date compared against a number field is not judged here. The card and its direction are about strings. PostgreSQL's answer for those is not measured.
• Line budget: n/a (no skills/** path in the diff).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 55 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/export-origins/data.json, packages/spec/src/data/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

10 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/data-api.mdx (via INVALID_FILTER (literal, a string literal in NumberComparandDoorRefusalCase; a string literal in NumberComparandDoorVerdict; a string literal in numberComparandDoorVerdict))
• content/docs/api/error-catalog.mdx (via INVALID_FILTER (literal, a string literal in NumberComparandDoorRefusalCase; a string literal in NumberComparandDoorVerdict; a string literal in numberComparandDoorVerdict))
• content/docs/data-modeling/field-types.mdx (via returnType (symbol, a field of const object NUMBER_COMPARAND_DOOR_FIXTURE_FIELDS; a field of interface NumberComparandDoorCaseBase; a field of interface NumberComparandDoorFieldMeta; a field of interface NumberComparandDoorFixtureField; a field of interface NumberComparandRefusalSite), summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/data-modeling/fields.mdx (via summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/data-modeling/formulas.mdx (via returnType (symbol, a field of const object NUMBER_COMPARAND_DOOR_FIXTURE_FIELDS; a field of interface NumberComparandDoorCaseBase; a field of interface NumberComparandDoorFieldMeta; a field of interface NumberComparandDoorFixtureField; a field of interface NumberComparandRefusalSite))
• content/docs/data-modeling/validation-rules.mdx (via returnType (symbol, a field of const object NUMBER_COMPARAND_DOOR_FIXTURE_FIELDS; a field of interface NumberComparandDoorCaseBase; a field of interface NumberComparandDoorFieldMeta; a field of interface NumberComparandDoorFixtureField; a field of interface NumberComparandRefusalSite), summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/getting-started/common-patterns.mdx (via returnType (symbol, a field of const object NUMBER_COMPARAND_DOOR_FIXTURE_FIELDS; a field of interface NumberComparandDoorCaseBase; a field of interface NumberComparandDoorFieldMeta; a field of interface NumberComparandDoorFixtureField; a field of interface NumberComparandRefusalSite), summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/protocol/objectql/query-syntax.mdx (via INVALID_FILTER (literal, a string literal in NumberComparandDoorRefusalCase; a string literal in NumberComparandDoorVerdict; a string literal in numberComparandDoorVerdict))
• content/docs/protocol/objectql/schema.mdx (via summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/protocol/objectql/types.mdx (via summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/releases/v17/17-0.mdx (via summaryOperations (symbol, a field of interface NumberComparandDoorFixtureField))
• content/docs/releases/v17/17-1.mdx (via INVALID_FILTER (literal, a string literal in NumberComparandDoorRefusalCase; a string literal in NumberComparandDoorVerdict; a string literal in numberComparandDoorVerdict))
• content/docs/releases/v17/17-4.mdx (via INVALID_FILTER (literal, a string literal in NumberComparandDoorRefusalCase; a string literal in NumberComparandDoorVerdict; a string literal in numberComparandDoorVerdict))

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.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/export-origins/data.json, packages/spec/src/data/index.ts) — pages documenting those are invisible to this run
• 12 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 136 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 40b315b03345e334069dd454aecaf7016adbea4f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from da7fe006f4d4aa651b83f54754b779e33b3f139a — the merge of head 93ec07654bed8f640cde61920756fb0f74d10d85 into base 40b315b03345e334069dd454aecaf7016adbea4f, 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 da7fe006f4d4aa651b83f54754b779e33b3f139a && git checkout da7fe006f4d4aa651b83f54754b779e33b3f139a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 40b315b03345e334069dd454aecaf7016adbea4f 93ec07654bed8f640cde61920756fb0f74d10d85 && git checkout -B drift-repro 40b315b03345e334069dd454aecaf7016adbea4f && git merge --no-ff 93ec07654bed8f640cde61920756fb0f74d10d85

node scripts/docs-audit/affected-docs.mjs --json 40b315b03345e334069dd454aecaf7016adbea4f

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 40b315b03345e334069dd454aecaf7016adbea4f → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 93ec07654bed8f640cde61920756fb0f74d10d85
Local-runs: none

Read for this record: card #20336 (body and all eight comments, the seat's ACCEPT 5868030228 included, treated as a claim to test), PR #20414 (body, the 6-file list, the net diff against main at the head), the head's check-runs, the linked cards #20309 and #20351 with their threads, and origin/main for the precedent (filter-text-operator-declared-type.ts), the sets and schemas the diff references. Nothing was built, run or re-run; the check-runs on the head are the gate verdicts.

① Derived judgments

Public surface and accept sets.

1. Twenty-seven exports are added to @objectstack/spec/data, all additive: api-surface/data.json +27/-0 and export-origins/data.json +27/-0, each row resolving to src/data/filter-number-comparand-declared-type.ts. The module has exactly 27 export declarations, so the generated files are a projection of the module, not a hand edit. Main's [finding] An RLS predicate comparing two fields of different comparison classes (text vs number, text vs image) passes os validate; on driver-sql the using read answers 400 while the check insert is admitted and stored #20347 rows are retained. RIGHT.
2. No accept set moves in this release: no door, evaluator, validator or driver reads the module; parseFilterAST, normalizeFilterComparandTypes and record-validator.ts are untouched, and no package imports the new file but its own test and the barrel. The changeset says so in its own words. RIGHT, and section ② rests on it.

The contract the module declares, decision by decision.

3. The grammar: a string is numeric when its whole content is a JSON number literal (RFC 8259 §6) naming a finite double; parseNumericString answers Number(s), which equals JSON.parse(s) for every admitted string (pinned). The String(n) round-trip is pinned over 418 values, so no caller that stringifies a legal number is refused. NUMERIC_STRING_PATTERN is linear (each digit run is closed by a literal or the anchor). RIGHT.
4. Exponent forms (1e3, 2.5E+3, 1e-7, 1e+21) are admitted. RIGHT; the "plain decimal" wording is answered under ③.
5. Refused, each with a named form and a remedy: blank and whitespace-only (empty), surrounding whitespace (padded), 0x/0o/0b (radix-prefix), Infinity/NaN/1e400 (non-finite), locale grouping and decimal commas (digit-separator), +5/.5/5./007 (non-json-spelling), and everything else (not-a-number). The exact list of strings Number() reads as finite that this grammar refuses is pinned by membership, so a later loosening goes red on purpose. Hex and padded strings are refused by name in record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's direction 1; the class value contract is z.number().finite(). RIGHT.
6. A {placeholder} is refused, not stepped around. classifyFilterToken names any brace-wrapped token; resolveFilterToken in packages/core/src/utils/filter-tokens.ts answers a user id, an organization id, a calendar day or an instant, or throws for a record-context token. No token names a number, so a resolved token is the same PostgreSQL bind failure as "abc". The temporal door records that it runs before resolveWhereTokens, so the sibling door meets the token unresolved; were objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351 to seat it after resolution, the resolved id would fall to not-a-number and still be refused. Either order refuses. RIGHT.
7. A numeric string is narrowed to its number, copy-on-write. The comparand-type door already narrows an exact-range bigint this way (kind: 'narrow' in filter-comparand-type.ts), and record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's census answer 5863923799 chose "store the parsed number" for the write side, so one string has one reading at both doors. Left a string, "12" is read by JS coercion on memory, by affinity on SQLite and by BSON type on MongoDB. RIGHT. Consequence for objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351: the door must hand the driver c.expectedFilter() and its pins must assert the rewritten filter, not only the 400s.
8. The judged fields are NUMERIC_VALUE_TYPES by identity (pinned by reference equality), summary included. Read at origin/main, NUMERIC_COLUMN_REPRESENTATION.summary is EXACT, so the column is numeric on every SQL face and a non-numeric bind fails the same way; the text door refuses text operators on summary through the same set; COMPUTED_VALUE_TYPES is the write door's who-writes axis. autonumber is outside the set and passes: its stored value is a formatted string. RIGHT.
9. formula is judged as the FieldType its returnType names, through the text door's own FORMULA_RETURN_TYPE_AS_FIELD_TYPE; an absent or unreadable returnType is deferred. Precedent-identical, unreachable at the seam because The FILTER axis has no unmaterializable verdict: a where on a virtual formula field returns 0 rows silently, while sort and search refuse the same field with a 400 #8296 refuses every formula filter first, and the module, the case table and the barrel comment all say so. RIGHT.
10. Judged positions: the implicit comparand, $eq / $ne / $gt / $gte / $lt / $lte, and each member of $in / $nin / $between; not judged: $null / $exists (boolean flags), the seven text operators (refused one door earlier over a numeric field, [Decision] refuse a text operator ($contains family) over a field whose DECLARED type is not textual — INVALID_FILTER 400 at the engine's field-aware door (option C of #14079); the textual-type vocabulary is the question #15661), a { $field } reference and a dotted key. FieldOperatorsSchema at origin/main has exactly those 18 keys (6 + 3 + 7 + 2), so the partition pin is exact and a later operator fails it loudly. RIGHT.
11. Only string comparands are judged; a number, null, a Date, a boolean or a bigint passes. RIGHT for the card, whose title and direction are about strings. The boolean and Date gap is carried under ③.
12. The envelope is the existing INVALID_FILTER / 400, spelled as a literal (the api/ imports data/ reason filter-comparand-type.ts records) and pinned to StandardErrorCode.enum.INVALID_FILTER; no code is minted. RIGHT (ADR-0112 class 1).
13. The refusal words name the field, its declared type (and a formula's return type), the bounded comparand via shapePreview, the path, the form's clause and then the remedy; the 500-character REST bound is pinned over every refusal in the table and the front-loading is pinned at 40-character names; every form's words differ and carry no tracker number. Each form's clause claims only what holds for that form. RIGHT.
14. The fixture holds one field per FieldType member plus four typed formulas and one untyped, each a legal FieldSchema input and the object a legal ObjectSchema input (pinned); the 136 cases are derived by calling the verdict. Because caseFor calls numberComparandDoorVerdict, the "every verdict agrees" pin is tautological; what carries the weight is the hand-kept 41-row NUMERIC_STRING_GRAMMAR_CASES with its expected values and forms, the census-shape pins (refusals are exactly the numeric class plus f_formula_number, one deferred row, no narrowing), the three-way coverage of every judged position, the narrowed filters being the original with one comparand replaced, and parseFilterAST accepting every filter. That is the precedent's shape and it is sufficient. RIGHT.
15. The census comparands for the temporal fields ("2026-01-01", "12:00") are chosen so no other door on the seam refuses them. That is a design claim for objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351 to measure, and the module says so. RIGHT to leave it there.
16. The barrel: nine lines, one comment block and one export *, placed after filter-cross-field-comparison-class by the hand-resolved merge; the diff against main on that file is exactly those lines. RIGHT.
17. The escape-materialisation deviation: the net diff spells U+00A0, U+202F, U+FF11, U+FF12 and U+2212 as backslash-u escapes and carries no raw code point of any of them (checked byte-wise over the whole diff). RIGHT.
18. readNumericString's order (pattern, empty, padded, placeholder, radix, non-finite word, separator, JS spelling, none): a padded non-numeric string names its inner form and 0bad names radix-prefix. Form naming only; every such string is refused. RIGHT.

Wrong: none found.

Not verified here, and not load-bearing: the reading of the sibling repository that viewFilterFold.ts and ListView.convertFilterGroupToAST drop blank rows before they reach the server. A blank that does reach the door is refused loudly, which is the direction's answer, and today it is PostgreSQL's 500.

② Semver level

.changeset/20336-number-comparand-declared-type-contract.md: @objectstack/spec minor, body carrying Clause-②: yes with no arm, not BREAKING, no ADR-0087 marker. That matches what the diff publishes: 27 additive exports are a public-surface change, so yes, which takes at least minor (AGENTS.md, changeset rule 3); no accept set narrows in this release, so (narrowing), which would make the changeset BREAKING, is rightly absent. The narrowings land with #20351 and #20309's string half, whose changesets carry Clause-②: yes (narrowing) as BREAKING minor (triage note 3 on #20351, direction 4 on #20309). A changeset that declares no breaking change needs no ADR-0087 disposition (check-adr-0087-registration keys off the declaration). Check Changeset and Lint & Repo Gates are success on the head. The card's first grade (5861215026) said yes (narrowing) for the whole card; after the split (5861636857) the claim (5864659116), the PR body and the changeset all say yes for the contract half, which is the right value for it.

Clause-②: yes

③ Boundary flags

Dev open_questions[0] (three readings) and the seat's ACCEPT flags 1 and 2, which are the same two.

• (1) Exponent forms admitted although record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's direction 2 (5860329599) reads "the plain decimal grammar": ANSWERED, option A stands. That phrase is triage direction on a domain:engine card; the same triage seat, routing this card (5861636857), sent the grammar to record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's producer census rather than to that phrase, and record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's execution seat wrote (5863923799) that hex, padded and exponent forms "are refused or accepted by that grammar's own case table. This card does not pre-decide them." So no ruling fixes the form, and on the merits String(1e-7) is "1e-7" and String(1e21) is "1e+21", read alike by Number(), SQLite affinity and PostgreSQL numeric input; a grammar without the form refuses the platform's own stringification of a legal value. A contract reading inside the direction, not a new ruling, and now the pinned table record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309 adopts.
• (2) +5 / .5 / 5. / 007 refused: ANSWERED, right (judgment 5). Pointer for record validator's number arm accepts any value whose Number() is finite, so POST /api/v1/data with a number field [500] answers 201 and driver-sql stores the text '[500]' #20309's string half: 007 and a padded cell are forms the CSV import legacy fallback could deliver that Number() accepted and this grammar refuses; that card's changeset carries the narrowing as BREAKING minor naming the producer, per its direction 4.
• (3) Narrowing rather than pass-through: ANSWERED, right (judgment 7), with the consequence for objectql: refuse a non-numeric string compared against a number field at the engine's field-aware filter door (400, every driver and position) — the door half of #20336 #20351 named there.

Dev out_of_scope_findings[0]: a boolean or a Date compared against a number field is not judged, and PostgreSQL's answer is not measured. ESCALATED as a follow-up for the engine lane, not blocking this card: by reading, { amount: { $gt: true } } and a Date bound against a numeric column are the same bind-failure class on PostgreSQL. #20351's pins should carry a boolean and a Date comparand as measured cells beside the numeric control, and a card is filed only if they answer 500. Nothing is filed here; this record is the reviewer's one write.

Observation, no action asked. The platform now has three numeric-string readers: this grammar (the filter door and the record write arm), @objectstack/formula's NUMERIC_STRING_RE (a JS spelling, trimmed, for expression operands at evaluation) and rest's parseNumberCell (currency symbols, %, thousands separators, for import cells). The module names the import tolerance as deliberate, and the formula hydration is a different seam; the "one grammar" claim is scoped to the read door and the write arm and holds there.

Deviations reported. Main merged twice through os-regen-merge.sh, the barrel conflict resolved by keeping both blocks, and the generated files rebuilt from the merged tree (the barrel diff is this card's nine lines; the JSON deltas are +27/-0 each with main's rows retained): accepted. Escape spellings restored: verified in judgment 17. The test:repo timeouts, the shallow-clone fixture fetch, the attribution form (a session footer, model-free trailers) and zero labels written by the dev: process notes with no bearing on the diff, accepted.

Gates and shape. At my first read mergeable_state was unstable while a Check Changeset re-run, started at 10:22Z by the label write, was in progress; on re-read the head has 39 check-runs, 33 success, 6 skipped (the opt-in and path-gated jobs), 0 failures, none in progress. Six files, +1228/-0, all inside the claim's surface: no packages/objectql, no record-validator.ts. Fixes #20336 is the only closing keyword; #20351 and #20309 are named in prose only and stay open. The head branch is the one the claim names, and the PR assignee is the card's.

Implemented-by: claude/issue-20336-numeric-comparand-verdict
Reviewed-by: session_01B3TqpoQbTAfG7G74GMDWNW

VERDICT: PASS

---

Generated by Claude Code