[huangyiirene]

Fixes #18408

Clause-②: no

The domain:engine half of #17469's one-definition ruling, executed: packages/objectql and packages/drivers/driver-turso now ask @objectstack/spec's isMultiValueField the question they used to answer from a raw field.multiple. This NARROWS to a declared contract (the predicate FieldSchema already enforces at the authoring entrance) and widens nothing — hence Clause-②: no.

The population, and triage's 11 reconciled

The card said the counts are triage's and told a taker to re-derive them. Both halves of that are now answered.

What I counted (my population): every read of the field-level multiple flag in NON-TEST source of the two declared packages, located by content — .multiple, bracket access, destructuring, and a full word sweep of multiple over both src trees. 5 sites in 3 files.

Triage's table (5681445124) reproduces exactly — as SITES, not files. Its column header says "files"; the numbers are matching LINES. At triage's own ref 827cacbf4b, with triage's own declared predicate set (isMultiValueField / field.multiple / .multiple ??), counting matching lines over the WHOLE package (tests and CHANGELOG.md included):

package	lines at 827cacbf4b	triage's table	files at the same ref
packages/cli	18	18	6
packages/objectql	11	11	4
packages/runtime	1	1	1
packages/drivers/driver-turso	1	1	1

All four cells match on the line reading and none matches on the file reading, so the gap was a population difference exactly as the claim suspected: sites, tests included, labelled "files". ⛔ Nothing in triage's work is wrong; the label is.

Two consequences worth stating rather than burying:

• Triage's 11 for packages/objectql is dominated by sites that ALREADY ask the spec predicate — record-validator.ts imports it as specIsMultiValueField and wraps it — plus two CHANGELOG.md lines. Only one of those 11 is a raw read (engine.ts:4741, today :4759).
• Triage's predicate set MISSES two raw reads, because they are spelled fdef.multiple rather than field.multiple: engine.ts:13168 and engine.ts:13602. A taker who worked from the grep alone would have shipped half the card.

⭐ Every site below was located by CONTENT. The card's engine.ts:4741 is at :4759 today, as the claim already measured.

The per-site premise — the discriminating question, asked five times

If isMultiValueField and the raw flag ever disagreed, would this site's behaviour be WRONG, or merely worded differently?

#	site	reads the flag to decide	divergent input class	verdict
1	objectql/src/engine.ts resolveOptionDefault	the SHAPE of an option-derived insert default (array vs scalar)	multiselect/checkboxes/tags with no flag; any non-capable type WITH the flag	ALIGNED
2	objectql/src/engine.ts referenceProbeFilter	$contains vs bare equality against the FK column	master_detail + flag	ALIGNED
3	objectql/src/engine.ts cascade multiValued	the set_null write shape, the required-FK escalation, the probe narrowing	master_detail + flag	ALIGNED
4	objectql/src/validation/record-validator.ts:824	single-value vs multi-value validation branch for select/radio	none TODAY — see below	ALIGNED, with a reading
5	driver-turso/src/remote-transport.ts mapFieldTypeToSQL	the DDL column type	number/integer/boolean + flag	ALIGNED

Site 1 is a live defect in both directions: a multiselect with an option marked default: true was defaulted to a bare scalar, which validateRecord's own multi-value branch then refuses as invalid_type_array on the very insert the default was resolved for. Measured — that case throws VALIDATION_ERROR before this PR.

Site 5 is the same defect #17469 repaired on driver-sql, here inside ONE driver: TursoDriver is dual-transport, its local half extends the ALIGNED SqlDriver, and its remote half spelled its own types. So { type: 'number', multiple: true } was a float column on one transport and a TEXT column on the other, chosen by which URL the deployment holds.

⚠️ Site 4 is the one a reviewer may want to overturn, so here is the reading

if ((t === 'select' || t === 'radio') && def.multiple !== true) is dominated by its own type gate: select and radio are both in MULTI_CAPABLE_TYPES and in neither multi-option set, so on that domain isMultiValueField(def) reduces BY CONSTRUCTION to multiple === true. The two authorities cannot disagree there today, and the alignment therefore changes no behaviour on any input — it is not one of the divergences above.

It is aligned anyway, and the reason is the ruling's own: the line is the exact complement of the isMultiValueField(def) branch twelve lines below it, and the equality holds only while packages/spec keeps select/radio in the set they are in now. Spelling one dispatch's two halves from two authorities that happen to agree is the drift the #17469 ruling exists to end. ⛔ If the seat reads this as out of scope, it is a two-line revert and nothing else in the PR depends on it.

Exclusions, with a reason each

Within the population defined above the exclusion list is empty, and the card is right that an empty list needs its own evidence. It is empty because the population is defined by the READ, not by a grep for multiple — every candidate the wider grep surfaces was examined and is listed here as excluded:

1. objectql/src/validation/rule-validator.ts:2037 — CHOICE_FIELD_TYPES (select, multiselect, radio, checkboxes). A hand-listed type set that a MULTI_OPTION_TYPES grep matches. It asks "does this field draw its value(s) from options?" — select and radio are on it, lookup/file/user are not — and it never reads the flag. Different question: the driver-sql isJsonField and spec isMultiValueField disagree for master_detail / tree / text + multiple: true, so a consumer using the spec predicate to shape a query gets a 400 #17469 exclusion class, verbatim.
2. Three parameter-slice type annotations in engine.ts ({ multiple?: unknown }). Declarations of what a function reads, not reads. (Two gained type?: unknown so the seam can be asked.)
3. The FieldSchema citations in the cascade/set_null prose (engine.ts ×2). They name FieldSchema's multiple and required doc blocks as the authority for the RESIDUAL REPRESENTATION — that an emptied set is written [] and never null ([Decision] Multi-value lookup after set_null member removal: does the emptied array read back as [] or null? #9447). That is still FieldSchema's question and is untouched. Only the comments that named the flag as the authority for MULTI-VALUEDNESS were rewritten.
4. record-validator.ts's local isMultiValueField wrapper and normalizeMultiValueFields. Already delegating to the spec predicate — the seam the suggested route asks for already exists in that file.
5. turso-json-column-type-asymmetry.test.ts:215's "the multiple: true route" note. Its fixture is { type: 'lookup', multiple: true }, which IS multi-valued by the predicate, so the sentence stays true and the Converging driver-turso's two transports onto one physical column type for Field.json — and the measured reason VALUE_ROUNDTRIP cannot adjudicate it #12738 pin is unaffected.

Precedent check against #18199's own exclusion: nothing here CONSTRUCTS a descriptor the predicate is asked of one frame later (action-execution.ts:1279's shape), and nothing here interpolates the flag into a message (#17469's three).

The comment half

Copied from the domain:cli half: the three in-tree comments that declared the losing authority were rewritten rather than left standing — resolveOptionDefault's "multiple: true assembles an ARRAY … (FieldSchema.multiple)", referenceProbeFilter's "A field declaring multiple: true stores an ARRAY … (FieldSchema.multiple)", and cascadeDeleteRelations' "On a multiple: true field the FK is a SET". objectql gets one local seam, declaredMultiValued, for its three sites; driver-turso has exactly one site and calls the predicate directly rather than minting a second name for it.

Evidence

Reverse verification (mutation = the three source files restored to their pre-fix content, tests left as written; restore = git checkout HEAD -- path, proven byte-identical by git hash-object against the HEAD blob):

ANCHOR COUNTS, fixed   engine.ts declaredMultiValued=10   remote-transport.ts isMultiValueField=3
ANCHOR COUNTS, mutated engine.ts declaredMultiValued=0    remote-transport.ts isMultiValueField=0   -> MUTATION LANDED
RUN (mutated)  objectql      Tests  3 failed | 33 passed (36)
RUN (mutated)  driver-turso  Tests  2 failed |  1 passed (3)
RESTORE PROVEN BYTE-IDENTICAL (3/3 blobs == HEAD)

The five red assertions are the discriminating ones. The three that stay GREEN under the mutation are declared as such in the test bodies: two cascade guard legs ($contains is a substring test, so it still matches a scalar column, and the engine's own narrowing pass repairs the over-match) and the turso "ask the predicate directly" leg. Stating which halves cannot fail is the point of listing them.

Tests, on the final head:

• pnpm --filter @objectstack/objectql test — 298 files / 4995 passed
• pnpm --filter @objectstack/driver-turso test — 53 files / 1252 passed
• pnpm --filter ... typecheck (both) — Done, 0 errors
• Live PostgreSQL: pnpm --filter @objectstack/driver-sql test against a local PG 16 (initdb + pg_ctl, port 54318, timezone=Asia/Shanghai, TZ=America/New_York) — 186 passed | 3 skipped (189 files), 3315 passed | 85 skipped. Positive control that the live cells really ran: sql-driver-datetime-postgres-timezone.test.ts is 5 passed with OS_TEST_POSTGRES_URL set and 5 skipped without it, same tree. The 3 skipped files are the MySQL-gated cells — ⛔ no mysql-server was installed, OS_EXPECT_LIVE_DIALECT_MATRIX was deliberately left unset so those skip instead of becoming a named red that says nothing about this diff, and the MySQL half is left to CI.

New pins: turso-remote-multi-value-column-type.test.ts (the declared column type per predicate verdict, plus a cross-transport storage-class leg), two cases in engine-select-option-default.test.ts, three in engine-cascade-delete-multivalue-probe.test.ts.

Gates

Derived from the real changed paths and reconciled on the FINAL head 66de450f64 — one count, one reconciliation:

dispatch-gates --ran: 65 derived family(ies) accounted for — 63 run, 2 NOT-MEASURED
  (both NOT-MEASURED are a recorded exit 3 = PREREQUISITE NOT MET, ⛔ not a finding)
    - pnpm check:dual-build-cjs-loads   reads every package's built dist/; needs a full `pnpm build`
    - pnpm check:type-check-debt        re-measures against the built workspace closure; same prerequisite

All 63 measured families exit 0. Exit codes were captured to disk before anything was read.

⚠️ Two notes on gates that were red earlier in this round and are green here:

• check:cross-package-test-inputs failed at my first head with [finding] check:cross-package-test-inputs exits 0 or 1 on the same commit depending on whether a dist/ exists — and lint.yml runs it with no build ahead of it, so CI only ever sees the blind leg #18621 — @objectstack/cli descends a directory tree from packages/spec/dist/, triggered by the local spec build and nothing to do with this diff. It is GREEN after merging origin/main, which brought fix(gates): judge a cross-package walk root against the index, not the working tree #18641 ("judge a cross-package walk root against the index, not the working tree"). Named, not chased, and no twin filed.
• check:engine-split-ratio --days 90 exited 2 on the shallow clone — a refusal, not a ratio. Deepened with the remedy the script prints (git fetch --shallow-since=2026-06-12 origin) and re-run: exit 0, ratio 97.8% over 317 engine-core commits.

pnpm lint (the repo-wide scan CI owns) was run in full rather than narrowed; result in the report.

Acceptance notes — noted, not filed

• RemoteTransport.mapFieldTypeToSQL's case 'formula': return '' is unreachable from all three of its callers, each of which skips type === 'formula' before calling. Dead branch, not a defect, and untouched here. Carrier: whoever next edits that mapper.
• The remote transport resolves field.type || 'string' in the mapper while all three callers resolve the identical expression before calling it — two spellings of one default, one frame apart. This PR uses the mapper's own copy (one resolution now feeds both the predicate and the switch) and does not unify the two. Carrier: the same mapper edit as above.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-turso, @objectstack/objectql, touching 6 documentable anchor(s).

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

• content/docs/releases/v17/17-1.mdx (via cascadeDeleteRelations (symbol, a method of class ObjectQL))

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

• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 69 pages)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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.

Coarse fallback — 22 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 14d25441138aee0a52621f9369d564afa28df9d4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 384548d56a0bfb6ee1125e54980250a54d92ab5f — the merge of head 66de450f648e770f4b263394f28dc0b135e7eed4 into base 14d25441138aee0a52621f9369d564afa28df9d4, 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 384548d56a0bfb6ee1125e54980250a54d92ab5f && git checkout 384548d56a0bfb6ee1125e54980250a54d92ab5f
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 14d25441138aee0a52621f9369d564afa28df9d4 66de450f648e770f4b263394f28dc0b135e7eed4 && git checkout -B drift-repro 14d25441138aee0a52621f9369d564afa28df9d4 && git merge --no-ff 66de450f648e770f4b263394f28dc0b135e7eed4

node scripts/docs-audit/affected-docs.mjs --json 14d25441138aee0a52621f9369d564afa28df9d4

⚠️ 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 14d25441138aee0a52621f9369d564afa28df9d4 → pass the list as
args.docs, on the commit named under Which tree this was computed on.