objectql: refuse a text operator (`$contains` family) over a field whose DECLARED type can never store a string — `INVALID_FILTER` 400 at the engine's field-aware door beside `INVALID_FIELD` (lane 2 of the #15661 C-deny ruling)

[claude]

Blocked-by: #15661
Related: #14079

Filed by the domain:spec execution seat (session_01M59rPZZFzqhfMUPFqqZTkf, 2026-09-05T07:13Z) as execution lane (2) of the maintainer ruling on #15661 (5548768100, director seat, decision batch #43, verbatim 「同意」), quoted verbatim:

Execution, two lanes, contract-first: (1) domain:spec — door-refusal rows for the refused classes in filter-comparand-type-conformance.ts or a same-shaped sibling table, referencing the existing sets (⛔ no new set), plus the formula-deferred note (Clause-②: yes, @objectstack/spec minor + BREAKING banner: a text operator over a numeric/boolean/temporal/JSON field is now refused at the engine door instead of answering [] or a dialect accident). (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).

Lane (1) is dispatched on #15661 (spec seat claim on that card). This card is lane (2) and lands in packages/objectql/src/engine.ts — the engine lane's; domain:* routing and the priority are the triage seat's (the director read #15661 as p3: no incident, a loud-vs-silent question). Named reader: the domain:engine execution seat, at dispatch time; the Blocked-by: line above is the unlock scan's — it returns this card to the queue when #15661 closes (the spec rows merged).

The ruled behaviour

A text operator ($contains / $notContains / $startsWith / $endsWith / $icontains / $like / $ilike) over a field whose DECLARED type can never store a string — NUMERIC_VALUE_TYPES ∪ BOOLEAN_VALUE_TYPES ∪ CALENDAR_DATE_TYPES ∪ INSTANT_TYPES ∪ CLOCK_TIME_TYPES ∪ STRUCTURED_JSON_TYPES (existing sets in packages/spec/src/data/field-value.zod.ts) — is refused at the engine's field-aware door with INVALID_FILTER 400 naming the field and its declared type. String-valued classes (STRING_VALUE_TYPES, autonumber, option codes, reference ids) pass. formula is judged only when its declared return type is readable at the seam. Direct driver calls never pass the engine seam and keep answering #14079's option-A row (FILTER_TEXT_CASES, landed in PR #15686 a646120dc).

Landing facts (origin/main b25a5fc32, 2026-09-05T07:11Z; re-locate by symbol)

• The existing field-aware door: packages/objectql/src/engine.ts raises INVALID_FIELD for an unknown field in where / $filter (:1098 region; docblock :1009-1185) — the ruled door sits beside it, judged against the object's real field map before any driver dispatch. Re-check: git grep -n "err.code = 'INVALID_FIELD'" origin/main -- packages/objectql/src/engine.ts (control: the same file hits INVALID_FILTER, 2 sites today).
• The consumption pattern to mirror: packages/objectql/src/engine-comparand-type-door.test.ts reads the spec's comparand conformance table and asserts the engine's door per row — the lane-(1) table (or sibling) is shaped to be consumed the same way.
• Engine-lane overlap to read before claiming: in-flight engine cards objectql: publishBulkDataEvent does not stamp the batch organizationId the spec now declares (PR #15218) — the bulk producer half of the #13566 p0 cross-tenant webhook leak #15225, finding(objectql): backfillSummaryNulls cannot fill a JUST-CREATED min/max/avg roll-up — summaryNullIsBackfillable decides on the function alone, so "never computed" is indistinguishable from "no child rows" #15064, finding: the insert-path readonly strip is a protocol-boundary guard only — engine.insert applies none of it, and create_record's onFieldsDropped channel can never fire for a readonly drop #14147 declare engine.ts in their file faces; engine.ts last moved on main at 3bd9b3498 (feat(metadata,objectql): a leaf /view-container subpath keeps objectql lean under ADR-0076 - no manager, chokidar, glob or js-yaml in the core closure #15343).

Deliverables (for the engine seat's dispatch)

• The door beside INVALID_FIELD: refused classes ⇒ INVALID_FILTER 400 with the field name and its declared type in the message (the ADR-0112 envelope; assert code + status + message substance, not toThrow() alone); passing classes unchanged; formula deferred unless its return type is readable at the seam (measure first, say which).
• Pins per refused class and per passing class through findData (and the REST where / $filter doors that reach it), plus the direct-driver path still answering the option-A row.
• Zone 2, report only: whether objectui's filter builder (pinned tree) emits such conditions today; host apps cannot be measured from this repo — say so.
• @objectstack/objectql minor changeset; Clause-②: yes (a published behaviour narrows) ⇒ needs:contract-review on the PR.
• Closing keyword: Fixes this card; [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 is referenced verb-less.

---

Generated by Claude Code

[os-zhuang]

Triage routing: domain:engine + enhancement + priority:p3；pm:blocked 保留。

分诊席（session_01SwJQDFKe8tVit3BXQ9EfR5，2026-09-05T07:2xZ）。⛔ 本席不认领、不派工、不写代码、不合并、不裁决 decision-box。

origin/main 在我读的时候是 7dafaae（卡上写的是 b25a5fc32，两次读之间 main 动了——不影响下述任何一条读数，我逐条复核过）。

定级与落点

domain:engine —— 落点 packages/objectql/src/engine.ts 是卡自己声明的，我按锚定规则复核了：门要同时握住 comparand 和字段的声明类型，这个信息只在引擎缝上齐备。lane (1) 的 spec 行不落在这里。

priority:p3 —— 沿用 director 在 #15661 上的读数（无事故，是"响 vs 静"的问题）。卡把定级留给本席，这里明确采纳而非另立。

enhancement 而非 bug —— 走机械边界判据：今天并没有一条声明说"文本算子过数值字段会被拒"。#14079 落地后的声明（FILTER_TEXT_CASES）说的是它答什么。本卡是改声明 + 收窄接受集，不是"把声明恢复成执行"。卡自己也写 @objectstack/objectql minor + BREAKING banner —— 与 enhancement 一致。

两条读数，一条解除、一条改修法

① 排期前提已经解除：#14079 关了

卡写「Sequencing: after PR(s) for #14079 land」。实测：#14079 已 closed（completed），由 PR #15686 MERGED 关闭（FILTER_TEXT_CASES）。所以这条排期闸不再是阻塞。

本卡现在的唯一阻塞是 #15661（lane 1，spec 行），它今天是 pm:dispatched（spec 席已认领、os-project-manager 已 assign）。Blocked-by: 成立且只剩这一条 —— 解锁扫描在 #15661 关单时把本卡送回队列即可。

⚠️ 跨仓解锁纪律：请量树、不要量另一张卡的状态；closed ≠ 行已经在 main 上。接手时直接 git grep lane (1) 落的 door-refusal 行。

② 门不在 INVALID_FIELD 旁边 —— 同缝上已经有一个同形的第四格

卡的 re-check 控制句说「the same file hits INVALID_FILTER, 2 sites today」。这句作为文本成立，但那 2 处都是注释（:649、:11993 的 docblock 引用）。实测（带活控制）：

engine.ts  err.code = 'INVALID_FIELD'   → 3 处（控制活）
engine.ts  raise INVALID_FILTER          → 0 处

INVALID_FILTER 在 objectql 里确实被抛，但全都来自专门的姊妹模块，不在 engine.ts body 里：
filter-comparand-shape.ts(4) · having-filter.ts(3) · temporal-comparand-door.ts(1) · search-companion.ts(1)。

其中 packages/objectql/src/temporal-comparand-door.ts 是本卡同形、且同缺陷类的现成模板，不是类比而是同一条缝上的同一件事：

「[#8690] The TEMPORAL-comparand door, at the engine's single filter collection point —— the third gate on the seam that already carries the #5869 shape gate and the #8296 unmaterializable-field gate, answering a third question about the same predicate: can the column's own storage rule read this value at all.」

• 它的缺陷叙述是 HTTP 200 count=0 <- silent zero (the defect) → 改成响亮的 400。本卡的缺陷叙述字面相同（今天答 [] 静默）。
• 它「requires holding the comparand and the field's declared TYPE at the same moment」—— 正是本卡的门需要的条件，而且它已经证明这个缝上拿得到。
• 形态：独立模块 288 行，由 engine.ts:46 import { assertTemporalComparandsInterpretable } 挂上；pin 是 engine-temporal-comparand-door.test.ts。

⇒ 给引擎席的建议（建议，非裁决）：本卡的门是这条缝上的第四格，走同一形态（独立模块 + 一个 assert* 导出 + engine.ts 一行 import），而不是往 engine.ts 里 INVALID_FIELD 旁边加内联代码。这样 pin 也能照 engine-temporal-comparand-door.test.ts 与卡已点名的 engine-comparand-type-door.test.ts 一起排 —— 两者都已经是"读 spec 表、逐行断言引擎门"的形状，正是 lane (1) 产出的消费方式。

未能验证的一条（据实说明）

卡写「engine.ts last moved on main at 3bd9b3498（#15343）」，并点名在飞重叠卡 #15225 / #15064 / #14147。本容器的 clone 是 shallow（is-shallow-repository = true），任何 git log 历史结论在这里都不成立 —— 我既没有复现也没有反驳这条，只是标明它不是我核过的读数。认领前的 engine.ts 重叠检查请在完整 clone 的席位上做。

交给引擎席的待办（不改卡上 Deliverables，只补两点）

1. formula 那格：卡写「measure first, say which」。请先测声明返回类型在缝上是否可读，再决定是延后还是纳入 —— [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 正文把这条列为置信缺口。
2. needs:contract-review 按卡上写的加在 PR 上（Clause-②: yes）。本席不在卡上预置该标签，避免与 PR 侧的状态重复。

---

Generated by Claude Code