fix(objectql)!: an option field stores the option code string a number or boolean was judged by, and refuses any object (#29562) - #29638

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

Contract-review-claim: session_01ADHkmQjPiXgNoSaEpqeGvY · head 6f16472 · 2026-11-02T23:15Z

📓 Docs Drift Check

6 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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 243c01d2eb83963aa74ad56a7b637874831bde0e && git checkout 243c01d2eb83963aa74ad56a7b637874831bde0e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 322cf9068f143f39cbfbc7527294db24f01cd649 6f164722dffdba3aa22c417e1349f2294625ee52 && git checkout -B drift-repro 322cf9068f143f39cbfbc7527294db24f01cd649 && git merge --no-ff 6f164722dffdba3aa22c417e1349f2294625ee52

node scripts/docs-audit/affected-docs.mjs --json 322cf9068f143f39cbfbc7527294db24f01cd649

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6f164722dffdba3aa22c417e1349f2294625ee52
Local-runs: none
Scope: packages/objectql/src/validation/record-validator.ts, packages/objectql/src/validation/record-validator.option-scalar-value.test.ts, packages/objectql/src/validation/record-validator.select-shape.test.ts, packages/rest/src/rest-data-option-scalar-value.test.ts + packages/spec/src/data/field-value.zod.ts (SINGLE_OPTION_TYPES, MULTI_OPTION_TYPES, MULTI_CAPABLE_TYPES, isMultiValueField, optionCodes, valueSchemaFor), packages/spec/src/data/field.zod.ts (SelectOptionSchema.value), packages/objectql/src/engine.ts (write-door ordering: insert 15531–15532, update 16968–16969, normalizeMultiValueFields 16495 / 18007 / 18257), packages/objectql/src/engine-validate.ts (the dry run's door, 158–160), and on main the record validator's normalizeNumericStringRow, isStringReadScalar, isPlainObjectValue, isInReadonlyScope, optionValues, isValueShapeJudgedType, isScannableValueShapeField and the two option arms of validateOne. Not reviewed: .changeset/29562-option-field-scalar-stored-string.md (prose face, read for ②).

Inputs: card #29562 (body, triage 6585729182, seat ruling 6587559938, claims 6587575551 / 6587628285, dev report 6590908827), PR #29638 (body, file list, net diff at the head), the precedents read on origin/main (#29241's .changeset/29241-text-field-scalar-stored-string.md and record-validator.text-scalar-value.test.ts; #29244's changeset and review 6585290571; #29133's changeset; card #29486 and its triage 6585221625), and the head's check-runs. The published spec and the cited code were read, never reviewed.

① Derived judgments

Every accept-set and public-surface change the diff implies, read against the cited code on main:

1. A number or a boolean on a single-value select / radio is written as String(value) at the door. RIGHT. The spec's stored element for the type is z.enum(codes) or z.string() (valueSchemaFor), never a number; on main the arm already judges membership by String(value) (record-validator.ts 1684) while the write carried the raw scalar, so "judged ≠ stored" was the defect. The door's new branch (BOUNDED_STRING_FIELD_TYPES.has(def.type) || isOptionType(def.type)) is the exact String(value) the arm reads, at the same point of the same function records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241 landed, so what is judged is what is stored. The spec's own optionCodes reads a declared option by String(o.value) and the validator's optionValues does the same, so a declared code "3" admits 3 and stores "3", which is the code the spec names; SelectOptionSchema.value is a SystemIdentifierSchema string, so an authored code is a string already.
2. A number or boolean ELEMENT of a multi-value option field (multiselect, checkboxes, tags, multiple: true select / radio) is written as its string; a lone scalar is written as its string and then wrapped. RIGHT. valueSchemaFor derives z.array(element) with the same string element; the multi-value branch on main (1740) judges each element by String(v). tags is free-form z.string(), so "7" is a legal tag exactly as 7 was judged to be. The door runs before normalizeMultiValueFields on every door (engine.ts: insert 15532 vs 16495; update 16969 vs 18007 / 18257), so a lone 3 on tags becomes '3' and is then wrapped to ['3']; had the wrap run first, the new array branch would have read [3] to ['3'] — either order lands the same value. optionElementsAsStrings keeps the same-reference contract (toBe(row) is pinned for untouched rows).
3. The array branch is gated on isOptionType(def.type) && isMultiValueField(def). RIGHT. A multi-valued lookup / user / file / image array is left as sent and still parses under the ADR-0104 arm (isValueShapeJudgedType), so no second shape rule for those types (finding: a multi-valued reference field (lookup/user with multiple: true) admits an element of the wrong shape: REST stores an embedded record [{ id }] with 201, where the single-valued field refuses it invalid_type (ADR-0104 D1) #22908 holds, pinned by an array on a multi-value lookup … left as sent). An array on a single-value select is left as sent, and the arm refuses it as before.
4. Readonly scope. The door runs under 'include' (isInReadonlyScope), so a readonly option field's scalar is rewritten, while system non-readonly and lifecycle columns are skipped — identical to the records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241 half and to A system-context write skips value-shape validation for readonly fields: a seed's malformed readonly datetime ('yesterday', an unresolved cel envelope) is stored verbatim, while the same value on a non-readonly field is refused #21663's rule that a readonly value's SHAPE is judged on every write. RIGHT.
5. Any object on a single-value select / radio is refused invalid_type with the records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244 sentence (expected one option value, received an object). RIGHT. isObjectValue is typeof value === 'object' && value !== null, so a Date, Map, Set, class instance, typed array or plain object all refuse, arrays keep the an array word via receivedObjectShape. On main isPlainObjectValue is prototype-strict, so a Date on a free select fell to membership and was stored as sent (SQLite its epoch TEXT), and on a declared select was refused invalid_option by the accident of String(date) failing membership — the 写入载荷里的算子对象:text 型字段不做类型校验,{ title: { $in: [...] } } 原样写进库(number 型会响亮拒绝) #5922 header's own "accident, not a rule". The spec's element has no object member, and no object has a string reading a caller meant as a code. The shape test still runs ahead of shapeOnly and of membership; the invalid_option → invalid_type move for a non-plain object on a declared select is named in the changeset. The plain-object / array rule of records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244 is unchanged in verdict, code and sentence.
6. Any object as an ELEMENT of a multi-value option field is refused the same way. RIGHT. value.find(isObjectValue) sits inside if (!isValueShapeJudgedType(t)), so the reference / media types are not touched. A null element is not an object: it is left to the branch as before (admitted on a free field, invalid_option as "null" on a declared one) — unchanged.
7. The blank arms are untouched. null and undefined on a single select return at isMissing before any arm, and the door skips them (neither string, array nor scalar); '' is normalizeBlankTypedValues' null (objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 / [Decision] records: a cleared single select or lookup is stored as '' by API / import / flow writers. Should the platform store it as "no value" (null), when that changes which existing records an "is empty" filter matches? #29346) one line earlier and a string is never rewritten on an option type (isJudgedNumberType is false, so the string path continues). RIGHT: a cleared select still stores null.
8. The edge scalars. String(-0) is "0", String(NaN) "NaN", String(Infinity) "Infinity", String(1e21) "1e+21", String(1.50) "1.5". Each is exactly the string the arm already judged membership by on main, so on a declared select only a declared code admits it (none of these is a SystemIdentifierSchema code), and on a free select or tags the stored value is now the judged string where before it was the driver's reading of the raw scalar (memory NaN, SQLite's REAL-to-TEXT). None is a NEW admission, and JSON cannot carry NaN or Infinity, so REST never sends them; the posture is records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241's (its SCALARS pins String(value) with no numeric grammar). RIGHT, with the observation that -0 and 0 were one code before and still are.
9. unique. Unique is enforced at the driver on the stored value, so 3 then "3" (and true then "true") now answer 201 then 409 on both drivers where both landed before; on SQLite true then 1 (both "1.0" before) and false then 0 (both "0.0") now land as two strings. The narrowing half and the true / 1 widening half are pinned against SQLite and stated in the changeset; the false / 0 half is implied and not stated (should-fix S1).
10. Public surface. No export, type or signature moves; normalizeNumericStringValues keeps its shape and has no consumer outside packages/objectql/src on main. No packages/spec change, no new error code or catalog sentence (fail('invalid_type', { type, detail }, 'invalid_value_shape') is the existing call), no filter-door change, no protocol.ts. The narrowed face is a data write's answer, served by every door that runs the record validator: engine insert / insertMany / update by id / update by predicate, validate() (engine-validate.ts 158–160 calls the same door), REST POST / PATCH, flow record nodes, screen-flow resume.
11. Header realignment (S3 of 6585290571). The new "Rules applied" list follows validateOne's arms on main in order: required (1151), operator (1162), string types with their bounds / domain / format nested (1211), number types with min / max / scale / precision nested (1315), boolean (1529), date / datetime (1536), time (1614), select / radio (1645), multi-value (1697), value shape (1756). RIGHT.
12. The forced test edit. select-shape.test.ts' { free: 3 } control is the pin review 6585290571 S1 asked to be moved by this card; it is restated as the rule (admitted, written as "3"), and the records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244 pins around it are untouched. RIGHT.

Correctly left alone: a value a before* hook writes AFTER the door is not rewritten (the arm still judges its string, the driver stores it as sent) — the latitude #20309 and #29241 documented; a bigint or symbol is neither a scalar the door reads nor an object the arm refuses, so it keeps its pre-existing path (unreachable through JSON). Observations, carrier none.

② Semver level

.changeset/29562-option-field-scalar-stored-string.md: '@objectstack/objectql': patch, title fix(objectql)!: …, line-initial Clause-②: yes (narrowing) and Metadata-protocol: none, one adr-0087: not-required (no-migration-prescription) marker, a BREAKING banner with FROM → TO for both narrowed cases and the one-line caller fix, the invalid_option → invalid_type move named, and the filter and stored-row notes. The PR body carries the same two lines. Per AGENTS.md § Post-Task Checklist 3 a non-protocol narrowing ships patch and keeps its BREAKING banner and ADR-0087 disposition; this is the shape of the landed twin .changeset/29241-text-field-scalar-stored-string.md line for line. Metadata-protocol: none is right: no key, value or metadata type an author writes moves. The Check Changeset and Governed Surface Queue Guard check-runs on the head are success.

Clause-②: yes (narrowing) — RIGHT, and the yes arm is the correct one: the stored form moves and the unique answer moves in BOTH directions (the SQLite true / 1 pair now lands), which a bare no (narrowing) could not carry; #29241 declared the same pair the same way, #29133 and #29244 (pure refusals) declared no (narrowing). The changeset states the widening half (true / 1); it omits the false / 0 pair #29241 named — S1, prose.

③ Boundary flags

OQ1 — filter face: { field: 3 } now matches no row written 3; should a number comparand on an option field be read by its string? Dev recommends A, decide in #29486 with the text family. ANSWERED: A. Measured posture, from the dev's table and the cited code: on base, SQLite stored 3 as the TEXT "3.0" (better-sqlite3 binds a JS number as REAL; TEXT affinity renders it "3.0") and a number comparand bound the same way matched that row and NOT a row written "3"; memory matched 3 === 3 only. So the filter face was already split by write spelling on both drivers. On head { f: "3" } matches every new row and { f: 3 } none. The one caller made worse is the one that writes numbers AND filters with numbers into an option field, whose census is 0 product writers (the dev's log-only probe over objectql, rest, runtime, service-automation, plugins and the dogfood battery; not re-run here). The spec's option value is a string, the #7872 comparand door admits a number on any field and has no field-aware arm for option fields, and the seat ruled the filter face out of this card (6587559938). The same silent miss #29486 names for text now exists for the option family; its body names text-family only, so the decision box must name both (S2). Not a must-fix: the REST pin records today's answer under #29486's name, so a change there is seen here.

OQ2 — stored rows: old raw 3 (memory with persistence) or SQLite "3.0" keep reading as they are and do not collide with a new "3"; should os migrate value-shapes carry option fields? Dev recommends A, its own card. ANSWERED: A, its own card, not this PR. Read in the tree: isScannableValueShapeField covers the reference and structured-JSON classes only, so the scan cannot see an option field today; an old SQLite "3.0" is decidable only against declared codes ("3.0" means "3" when "3" is a code, and nothing can be said on a free select), while a memory-persisted raw 3 is decidable by type. That is a migration rule, not a write-door one. Until it lands the inconsistency is the one #29241 accepted for text and the changeset states: a read hands back the old form, { f: "3" } misses old rows, and a new "3" does not collide with an old "3.0" on a unique field. The ADR-0087 marker's "no stored-row migration is prescribed" is right for this PR. S3 names the card.

Dev deviation — no driver-memory test consumer (closed census, check:driver-memory-census). ANSWERED: accepted; the recording-driver pin shows the payload every driver receives, the memory column was measured in the Step 0 table, and the unique collision on memory follows from its keying on the stored value (6585290571 ① 11).

Dev deviation — a non-plain object cannot reach REST; its pins are engine-level. ANSWERED: right, a JSON body carries no Date, Map or class instance; flows, hooks and server code reach the engine doors, where the pins sit.

Dev deviations — PR assignee / reviewer not set; subscribed to PR activity. ANSWERED: the standard order's posture; not findings.

Out-of-scope finding (carrier none) — the text arm still admits a non-plain object (new Date(0) on a text field passes as its string reading and the driver stores it as sent). ANSWERED: escalated as S4, a card; it is sibling (3)'s text-family twin through the same isPlainObjectValue helper, and this card's ruling is option-family only.

No flag is escalated beyond a card.

④ Design judgment

What the spec declares. ADR-0104 D1's value contract (field-value.zod.ts): the module header says select ⇒ option code; SINGLE_OPTION_TYPES "value is one declared option code"; MULTI_OPTION_TYPES "value is an array of option codes (tags: free-form)"; valueSchemaFor derives z.enum(codes) or z.string() per element and z.array(element) when isMultiValueField; optionCodes reads a declared value by String(o.value); SelectOptionSchema.value is a SystemIdentifierSchema string. No published spec declares a number, a boolean or any object as an option field's stored value. The narrowing makes the spec's own stored shape real at the write door and takes no declared capability away at the consumer: every payload admitted before is admitted now, with the same verdict and code (the one code move is a non-plain object on a declared select, from an accidental invalid_option to the shape sentence), and the value stored is the one the arm already judged. It is the option-family instance of #29241 (same function, same String(value), same door points) and of #29133 / #29244 (same shape refusal), widened from "plain" to "any" object because an option code is a string and no object has a string reading a caller meant.

Attempts to break it:

1. Is a free select or tags a declared "anything" capability that a number exercises? No: valueSchemaFor gives z.string(), not z.unknown(); the module reserves openness for json and the computed types. The number was admitted by its string reading, and now that reading is stored.
2. Can String(value) mint a code the arm did not judge? No: the door runs before the validator on every door with the same expression on the same scalar, and validate() (engine-validate.ts) runs it too. The only value the arm judges without the door is one a before* hook writes afterwards — the documented latitude of 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 and records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241, not this PR's.
3. Could a declared option be a number such that "3" and the code disagree? No: the spec's optionCodes and the validator's optionValues both String() the declared value, and SelectOptionSchema.value is a string identifier.
4. The edge scalars (-0, NaN, Infinity, 1e21, 1.50). Each stores the string the arm judged ("0", "NaN", "Infinity", "1e+21", "1.5"); on a declared select none passes membership unless declared, on a free field each was already admitted and the driver stored its own reading of the raw scalar. Nothing new is admitted; JSON cannot carry two of them. records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241 has the same posture.
5. Does the array branch of the door reach a non-option array? No: isOptionType && isMultiValueField; a multi-valued lookup / user / file / image and a json array are left as sent (pinned), and a single select's array is left for the arm to refuse (pinned).
6. Does the lone-scalar order matter? No (① 2): the door precedes normalizeMultiValueFields on insert and both update paths, and the array branch covers the other order.
7. Does isObjectValue catch null, and does the blank arm survive? null is excluded explicitly; isMissing returns before the arms; '' is null by objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 one line earlier; strings are never rewritten on option types. A cleared select stores null as before.
8. Does the object refusal leak into the reference / media classes or create a second element rule? No: both arms sit where records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244 put them, inside the !isValueShapeJudgedType(t) branch and the single-value select gate !isMultiValueField(def) (engine: the one-definition-of-multi-valued invariant reaches packages/objectql and driver-turso — the domain:engine half of #18199's ruling #18408).
9. Readonly and picklist. The shape test runs ahead of shapeOnly (pinned under 'include'); picklistUnresolved and keptOptionValues are untouched and still read String(value).
10. The operator rule. Still first and still its own sentence (valueMayBeAnObject is false for a single select).
11. Does the unique move take a capability away? It removes the ability to store 3 and "3" as two rows of one option on a unique field — the split the card is about, and the same move records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241 made with the same declaration. The SQLite widening half returns a legal pair ("true" and "1" are two codes).
12. The filter face. Not touched; the read door still refuses an object or array comparand on a select and still admits a number one, which now silently misses — filter: a number or boolean comparand on a text-family field never matches, now that a text field stores the number 42 as "42" (#29241), and no error is raised #29486's question, named for both families (S2).
13. Performance. The array branch allocates only when an element changes; a row with no change returns the same reference (pinned).

Findings.

Must-fix: none.

Should-fix (none blocks):

• S1. Changeset (and the REST test's table): state the false / 0 half of the SQLite widening beside true / 1 — both were stored "0.0" and now land as "false" and "0" — as records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241's changeset did; prose completeness of the BREAKING banner.
• S2. filter: a number or boolean comparand on a text-family field never matches, now that a text field stores the number 42 as "42" (#29241), and no error is raised #29486's decision box names the text family only; the seat adds the option family to it (OQ1 A), so one ruling covers both string-stored families and the REST pin here moves with it.
• S3. File the stored-row card (OQ2 A): a scan of option fields for a memory-persisted raw number / boolean and a SQLite "N.0" / "1.0" / "0.0" row, rewriting to the declared code where one matches; isScannableValueShapeField does not reach option fields today.
• S4. File the text-family twin of sibling (3): the BOUNDED_STRING_FIELD_TYPES arm admits a non-plain object through isPlainObjectValue and the door leaves it, so a Date on a text field is stored as sent.

Verdict grounds. Every accept-set change the diff implies is the spec's stored shape made real at the write door (①); the changeset level and declarations match the diff and the #29241 precedent (②); every flag and open question is answered, two escalated to cards (③); the narrowing takes no declared capability away and survives each probe above (④). The head's check-runs: the line below.

Check-runs on 6f164722: all 48 check-runs completed (35 success, 13 skipped), read at 2026-11-02T23:34Z; none concluded failure, cancelled or timed_out. The gate families this diff derives are success: Build Core, Test Core (8 shards), TypeScript Type Check and Type Check (workspace, source gates, consumer gates, debt ledger), Lint & Repo Gates with Lint · ESLint and every scoped lint gate, Check Changeset, PR-body guards, Governed Surface Queue Guard, Dogfood Regression Gate, Test UI and Live E2E UI. The UI build / lint / type-check matrix, Temporal Conformance and the opt-in harnesses are skipped by the path filter (no ui/ or driver path in the diff). Their conclusions are the gate verdicts this record adopts.

Implemented-by: claude/project-thread-fp1844
Reviewed-by: session_01ADHkmQjPiXgNoSaEpqeGvY

VERDICT: PASS

Stamped 2026-11-02T23:35Z.

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

席位核对 · ACCEPT · domain:server seat 1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY · 2026-11-02T23:38Z

Head 6f164722df, dev report 6590908827 (on #29562), seat ruling 6587559938 (A). Clause-②: yes (narrowing), so the record is owed at CONTRACT_REVIEW_TIER on the narrowing face. Record 6591249009 on this head at CONTRACT_REVIEW_TIER: PASS, no must-fix.

domain:server#1 · os-steve · session_01ADHkmQjPiXgNoSaEpqeGvY

Hand-off · seat 1 off duty · 2026-11-02T23:59Z

Seat 1 has gone off duty on Steve's order. This PR passes to the next domain:server seat. It is ACCEPTed (6591295533 on review PASS 6591249009) and sits in the merge queue with auto-merge on. The next seat follows it to MERGED and posts the landing note on #29562. The steps are in the hand-off on the card, 6591615821.