feat(objectql)!: refuse a text operator over a field whose DECLARED type can never store a string (#15773)

[claude]

Fixes #15773

Execution lane (2) of the maintainer ruling on #15661 (5548768100, decision batch #43, option C-deny). Lane (1) — the contract this consumes — landed in 6f1ce7d267 (#15804); this PR is its only consumer.

The ruling, verbatim (lane 2)

(2) domain:engine — the door in packages/objectql/src/engine.ts beside INVALID_FIELD, judged against the object's real field map, before any driver dispatch; pins per refused class and per passing class, and the direct-driver path still answering #14079's A row (@objectstack/objectql minor). Sequencing: after PR(s) for #14079 land. Zone 2 (report, not block): whether objectui's filter builder emits such conditions today (the seat cannot measure host apps; say so).

What was wrong, measured before the door

origin/main 59db8a02cb, a real ObjectQL, lane (1)'s fixture object registered, a recording driver beneath:

filter	before	after
{ f_number: { $contains: '5' } }	driver read, filter passed through	400 INVALID_FILTER
{ f_summary: { $contains: '5' } }	driver read, filter passed through	400 INVALID_FILTER
{ f_json: { $contains: 'a' } }	driver read, filter passed through	400 INVALID_FILTER
{ f_date: { $startsWith: '2026' } }	400 INVALID_FILTER — the #8690 TEMPORAL door, about the COMPARAND	400 INVALID_FILTER, naming the declared type
{ f_text: { $contains: 'a' } }	driver read	unchanged

Beneath the door the driver answered #14079's option-A row: no row for a positive operator, EVERY row for $notContains. That is the declared answer and it is not wrong — it simply carries no signal that the field can never hold a string.

What this adds

• One door, packages/objectql/src/text-operator-declared-type-door.ts, bound at the engine's single filter collection point (lowerWhereFilterArray, both branches) and at aggregate's per-aggregation filter slot. Ladder position 3 of 4: comparand shape (数据 API:集合算子 not_in/in 的比较值是标量(非数组)时答 500 DATABASE_ERROR,而不是带信封的 400 —— 而这个形状是 spec 合法的 ViewFilterRule #5869) → materializable field (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 / [finding] The FILTER axis has no DOTTED-path verdict — where: { project_id.name: 'x' } rides its head segment past both doors, where SORT refuses the same spelling (#4256) #8371) → declared type → temporal comparand (An unparseable date comparand on a datetime filter is passed through and compares false — HTTP 200, zero rows, no diagnostic — while an unknown {placeholder} is correctly rejected 400 (17.0.0 GA) #8690).
• Derived, never re-listed. The verdict is @objectstack/spec/data's textOperatorDoorVerdict; the refused set is the union of the six published value classes. A type added to NUMERIC_VALUE_TYPES tomorrow is refused with no edit in this package. ⛔ No new set, no new error code, no new export.
• INVALID_FILTER / 400 / httpStatus 400 through this package's existing invalidFilterError — the message names the field, its declared type and the operator, per the ruling.

Why it runs BEFORE the temporal gate

A text operator over a date field was already refused — by #8690, with the same wire envelope but a message reporting that the comparand is not a date value. True, and beside the point: no comparand would have made the filter runnable, and an author who "fixes" it to $startsWith: '2026-01-01' gets the silent cell back. Same envelope, the ruling's message. No pin in the tree asserted the old wording for that cell (checked by grep over packages/objectql/src/*.test.ts).

⚠️ One named divergence from lane (1)'s case table: formula

assertFilterIsMaterializable (#8296) refuses EVERY filter over a formula field one door above this one, with INVALID_FIELD / 400, for the broader reason that no driver materialises a column for it. Measured on the same tree, for all three return-type shapes:

find(o, { where: { f_formula_number:  { $contains: '5' } } })  -> INVALID_FIELD 400 (#8296)
find(o, { where: { f_formula_text:    { $contains: '5' } } })  -> INVALID_FIELD 400 (#8296)
find(o, { where: { f_formula_untyped: { $contains: '5' } } })  -> INVALID_FIELD 400 (#8296)

So lane (1)'s formula rows — returnType: number ⇒ door-refusal with INVALID_FILTER, text ⇒ passes with a driver read — cannot be consumed as written at this seam. The ladder was not reordered around them: doing so would answer ONE condition ("a formula field cannot be filtered") with TWO wire codes chosen by returnType, which is the split every door on this seam records its reasoning against, and #8296's own note argues that code assignment. The rows are pinned in the direction they actually answer, under a test named NAMED DIVERGENCE, so the day formula fields become filterable this file goes red and the question is re-judged rather than silently inherited. The door's own verdict function is still exercised through its formula branch.

Zone 2 — reported, not blocked

Whether objectui's filter builder emits such conditions today cannot be measured from this repo. objectui is a sibling repository and the host apps that consume it are not in this checkout; this seat has no reading of them. What can be said from here: the refusal is INVALID_FILTER / 400 with a message naming the field and its declared type, so a builder that does emit one gets a diagnostic rather than an empty list — and the string-valued classes a filter builder most often targets (select / radio codes, multiselect / checkboxes / tags, lookup and user ids, autonumber, the file classes) all pass unchanged, which is what C-allow was refused for. A follow-up measurement on the objectui tree belongs to a seat that can read it.

Verification

Head cc83d5c741. Local scope per the repo's rule: the objectql dependency closure build, the affected packages' own tests and typechecks, and the gate families derived from the diff. Repo-wide scans are CI's. Exit codes captured by redirect-then-$?, never across a pipe.

run	result
pnpm --filter '@objectstack/objectql^...' build --concurrency=2	VERDICT command-exit 0 (shared verify lock)
pnpm --filter @objectstack/objectql test at cc83d5c741	295 files / 4947 tests passed, exit 0
pnpm --filter @objectstack/objectql typecheck	exit 0 — check:test-typecheck: OK … 44 file(s) / 242 error(s) / 69 pinned signature(s), the ledger's own numbers, unchanged
pnpm --filter @objectstack/spec test	471 files / 13266 tests passed, exit 0
pnpm --filter @objectstack/spec typecheck	exit 0
check:migration-registry · check:spec-changes · check:upgrade-guide	exit 0, exit 0, exit 0
node scripts/pm/dispatch-gates.mjs --ran	110 derived, 109 run green, 0 UNRUN, 1 NOT-MEASURED
node scripts/pm/check-clause2-carriers.mjs --pair 17381	exit 0 — both carriers agree

The one NOT-MEASURED family is pnpm check:dual-build-cjs-loads, exit 3 — PREREQUISITE NOT MET: it reads built output and 33 packages have no dist/ in this worktree ("Run pnpm build first. ⛔ This is NOT a pass: nothing was measured"). A repo-wide build is CI's, not a local scope. ⛔ Not recorded as a pass.

Two gates were red on the way and are fixed in their own commits, both proved red-before / green-after by exit code: pnpm --filter @objectstack/objectql typecheck (three TS2339s — the REFUSALS partition filtered on the discriminant with a plain boolean predicate, which does not narrow the union; fixed with a c is TextOperatorDoorRefusalCase type guard, no @ts-expect-error, no any, no debt-ledger edit) and pnpm check:doc-authoring (one site: the refusal message carried (#14079); the id moved to an adjacent // comment, baseline untouched). check:type-check-debt first exited 3 under --max-old-space-size=4096 (the re-measure tsc OOMed); re-run at 8192 it is exit 0 — 5 ledger entries re-measured, 55 raw errors, none above its recorded number.

Red before green, in the real direction

Ablation on the committed tree: the three assertTextOperatorTargetsAreStringCapable(...) call sites deleted from engine.ts (proved on disk — 4 occurrences before, 1 after, git hash-object moved from d14c0561… to 996ca53f…), suite re-run, then restored from HEAD under a trap.

RED   : 9 failed | 13 passed (22)   exit 1
        × refuses every door-refusal case … × pins EVERY class of the verdict matrix
        × covers every engine verb … × FilterArray sugar … × $and / $or / $not
        × the per-aggregation filter … × where object / $filter string / filter AST
        AssertionError: $contains over f_number (number) — door-refusal: expected a refusal
GREEN : 22 passed (22)               exit 0

The 13 that stay green under ablation are the guards and the beneath-the-door pins — exactly the ones that must NOT depend on the door. Restore verified by blob hash (d14c0561… again) and an empty git diff HEAD.

Two zero-hit readings, each with a control that fires

• The door did not exist on main: git grep -c -E "textOperatorDoorVerdict|TEXT_OPERATOR_DOOR" 59db8a02cb -- packages/objectql packages/rest packages/core → 0 files; control assertFilterIsMaterializable on the same three trees → 5 files.
• No pin asserted the An unparseable date comparand on a datetime filter is passed through and compares false — HTTP 200, zero rows, no diagnostic — while an unknown {placeholder} is correctly rejected 400 (17.0.0 GA) #8690 wording for a text operator over a temporal field (the cell whose message this PR changes): the text-operator grep over packages/objectql/src/*.test.ts at 59db8a02cb, filtered to temporal field names → 0 lines; control, $gte / $lt in engine-temporal-comparand-door.test.ts → 26 hits.

Acceptance notes

• Clause-②: yes — a published filter surface narrows (a call that answered [], every row, or a dialect accident now answers 400), the same criterion the maintainer used on text operator over a temporal column: SQLite matches the stored ISO text, live Postgres refuses with SQLSTATE 42883, and the JS faces answer by stored representation — no face declares the cell #15683. needs:contract-review is on this PR; @objectstack/objectql minor with a BREAKING banner in the changeset, per the ruling's grade.
• No new error code: INVALID_FILTER already exists at packages/spec/src/api/errors.zod.ts. No export added or removed from either package entry (index.ts / core.ts re-export neither this module nor its two sibling door modules). No member added to any published closed set.
• packages/spec/src/data/field-value.zod.ts is read-only in this PR, per the round's serial-queue fence (driver-sql: store the file family (file / image / avatar / video / audio) as the bare sys_file id in a string column — drop FILE_REFERENCE_TYPES from JSON_COLUMN_TYPES, per-deployment switch on the adr-0104-file-references flag (ruling on #15041, step 2) #15989 holds it). This PR reads its sets through lane (1)'s module and edits nothing there.
• The per-aggregation filter slot (engine.aggregate: add per-aggregation filter to the contract — ruled half of #10413 (measure-level filters on the ObjectQL analytics path) #10576) is covered as well as where. That position is not named in the ruling; it is the same door, the same seam and the same verb, and covering where alone would answer one mistake two ways inside aggregate. Called out here for the reviewer rather than left implicit.
• The ADR-0087 disposition is registered, and the question that decided it was measured rather than asserted. not-required (no-migration-prescription) would have been wrong twice over: this body carries a FROM → TO prescription, and — the half that actually decides it — a filter body CAN be persisted as metadata. Measured on the tree: sys_saved_report.query_json.filter is executed verbatim (report-service.ts → engine.find(object, { where: q.filter })), FieldSchema.summaryOperations[].filter is ANDed with the parent-FK match and handed to engine.aggregate (summary-aggregate.ts), ViewFilterRuleSchema takes field: z.string() with contains / not_contains / icontains / starts_with / ends_with in its operator enum and AST_OPERATOR_MAP lowers 'contains' to '$contains', and FilterConditionSchema is embedded by dashboards, datasets, reports and relatedListFilter. No schema changed, so those stored bodies still parse and still load — the first sign is a 400 on the read. Hence one new semantic entry, filter-text-operator-declared-type-refused (protocol 18), carrying the repair procedure and its acceptance criteria; no mechanical rewrite exists, which is what a semantic entry is for. sys_sharing_rule was checked and is deliberately NOT on that list: its authored surface is CEL, and RLS / sharing predicates are composed onto the AST AFTER this door, so the door never judges one.
• A hand-written doc sentence this PR falsified is scoped, not deleted. content/docs/protocol/objectql/query-syntax.mdx stated text operator over a temporal column: SQLite matches the stored ISO text, live Postgres refuses with SQLSTATE 42883, and the JS faces answer by stored representation — no face declares the cell #15683's compile-time no-match as what a caller sees; after this door that holds only BENEATH it. The callout now says which caller gets which answer — through the engine, 400 INVALID_FILTER before dispatch; beneath it, the driver's own answer — and keeps the driver-memory divergence (driver-memory answers a text operator over a DECLARED temporal column by matching its canonical ISO text — the opposite of #15683's declared-type answer, and the existing pin passes for the wrong reason (a millisecond mismatch) #17348) and the FILTER_TEXT_CASES sentence intact. The case-axis half is untouched. ⛔ Nothing under content/docs/releases/** was touched.
• Out of scope, noted, not filed: the neighbouring assertTemporalComparandsInterpretable is not wired into the per-aggregation filter slot (only 数据 API:集合算子 not_in/in 的比较值是标量(非数组)时答 500 DATABASE_ERROR,而不是带信封的 400 —— 而这个形状是 spec 合法的 ViewFilterRule #5869 and 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 are, plus this door now), so an uninterpretable temporal comparand inside one aggregation's filter is still unjudged. Untouched here — it is An unparseable date comparand on a datetime filter is passed through and compares false — HTTP 200, zero rows, no diagnostic — while an unknown {placeholder} is correctly rejected 400 (17.0.0 GA) #8690's card, not this one — and the carrier that would trip over it is a dashboard measure filter. Successor: none identified; recorded so the next seat on that slot sees it.

---

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/spec, touching 10 documentable anchor(s).

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

• content/docs/data-modeling/field-types.mdx (via returnType (symbol, a field of interface TextOperatorOverNonTextField))
• content/docs/data-modeling/formulas.mdx (via returnType (symbol, a field of interface TextOperatorOverNonTextField))
• content/docs/data-modeling/validation-rules.mdx (via returnType (symbol, a field of interface TextOperatorOverNonTextField))
• content/docs/getting-started/common-patterns.mdx (via returnType (symbol, a field of interface TextOperatorOverNonTextField))

What this run could not see

• 6 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 135 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 2bafbfdca92fa0bf9a08e6f306be435c97ce6505 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 2bafbfdca92fa0bf9a08e6f306be435c97ce6505

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