[spec] `FieldReferenceSchema` is declared in the `$between` endpoints but NO backend resolves a `$field` inside a list

[os-zhuang]

Measured while implementing #5222 (cross-field push-down). Filing unassigned — recording, not claiming.

The fact

packages/spec/src/data/filter.zod.ts declares FieldReferenceSchema in both $between endpoints, in the documentation copy and in the ENFORCED copy:

$between: z.tuple([
  z.union([z.number(), z.date(), z.string(), FieldReferenceSchema]),
  z.union([z.number(), z.date(), z.string(), FieldReferenceSchema])
]).optional(),

$in / $nin are z.array(z.any()), so a reference is admitted there too.

No backend resolves it. The in-memory evaluator — the one implementation the repo has for $field — does not, and this is structural rather than an oversight. matches-filter.ts resolveValue returns early for an array:

function resolveValue(raw: unknown, record) {
  if (raw && typeof raw === 'object' && !Array.isArray(raw) && '$field' in raw) { … }
  return raw;   // ← an ARRAY comes back unchanged, members unresolved
}

evalOp resolves the whole comparand, never the members. So for $in/$nin the raw reference OBJECT is compared with looseEq against a stored value (never equal), and for $between the raw object becomes an ordering bound.

Why it matters

This is the ADR-0049 enforce-or-remove shape at a declared position: the spec promises a comparand form that nothing implements, and the failure is SILENT on the memory path — { amount: { $in: [{ $field: 'budget' }] } } matches nothing and reports nothing. On an RLS check that is a denied write with no diagnostic; the $nin direction loses an exclusion the author wrote.

driver-sql / driver-sqlite-wasm refuse these positions loudly (INVALID_FILTER / 400) — #5041 installed that and #5222 deliberately kept it, precisely because there is no correct in-memory semantics for SQL to be equivalent to. So today the declaration is honoured by nobody and refused by two backends.

The decision this needs

Either:

• Remove FieldReferenceSchema from the $between endpoint unions (and rule $in/$nin members out explicitly), making declared = enforced; or
• Implement member resolution in matches-filter.ts and then decide whether the SQL faces can compile it conformance-equivalently (per-member OR-expansion, whose NULL and type-affinity behaviour is the open question [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 declined to guess at).

Not decided here — it is a contract-face call, same class as the #5222 rulings.

Refs

• [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 (cross-field push-down; refuses these positions, with the reasoning recorded in cross-field-conformance-cases.ts)
• [spec] $field 跨字段比较:spec 声明 + cel-to-filter 产出,但无任何 SQL 执行层实现 —— enforce-or-remove 裁决位 #5041 (the original refusal + probe evidence)
• ADR-0049 (enforce-or-remove)

[os-zhuang]

Triage: needs-user-decision appended; domain:spec (filer-applied) confirmed correct.

• Classification: the card itself frames the fork — remove FieldReferenceSchema from the $between endpoints (declared = enforced) vs implement member resolution — and states "Not decided here — it is a contract-face call". Either branch changes the acceptance surface of packages/spec, which is exactly the domain:spec criterion (standing instruction ③ reverse red line), and the choice is a maintainer contract ruling, same class as the [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 rulings.
• Premise verified on origin/main @ 744b8f5: packages/spec/src/data/filter.zod.ts:319-320 still declares FieldReferenceSchema in both $between endpoints, and packages/formula/src/matches-filter.ts:342 still early-returns arrays unresolved (!Array.isArray(raw) guard). Both anchors hold.
• Dedup: [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 (in flight, pm:dispatched) deliberately kept the SQL-side refusal and did not touch these positions; [spec] $field 跨字段比较:spec 声明 + cel-to-filter 产出,但无任何 SQL 执行层实现 —— enforce-or-remove 裁决位 #5041 is closed history. Sibling cards [spec] parseFilterAST lowers ['a', '=', { $field: 'b' }] to a bare field spec no backend reads as equality #7597/[spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 filed in the same batch cover the lowering sink and the analytics faces respectively — three distinct faces, no overlap in fix site. No convergence needed.
• Release read: the $field capability itself is still landing via [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 (its corpus is not yet on main — zero CROSS_FIELD_CASES hits @ 744b8f5), and the SQL faces refuse these positions loudly, so this does not block the current RC on its own; the ruling can also fold into [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222's follow-up scope.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded 2026-08-11 (PM session, executing the maintainer's direct instruction in chat — verbatim: 「接受你的全部建议，请更新 issue 的状态和标签」, accepting the four-lens decision-inbox review in full).

Ruling: Remove. Take FieldReferenceSchema out of both $between endpoint unions, and rule $in/$nin members out explicitly — declared = enforced via removal (ADR-0049). ⛔ No member-resolution implementation without measured demand (startup-focus): zero consumers today, and two backends already refuse these positions loudly.

State: needs-user-decision → pm:queue (domain:spec seat).

---

Generated by Claude Code

[os-zhuang]

Round-1 selection note (spec lane, session session_01JY2Q5Xto1u8YHADgrZDTnk): serialized BEHIND #7597 — same file (packages/spec/src/data/filter.zod.ts), strict cross-round serialization, and #7597's ruled silent-zero-rows fix goes first.

Facts recorded for the dispatching round (re-verified 09:18Z on origin/main):

• FieldReferenceSchema still sits in both $between endpoint unions at :319-320 (documentation copy) and :819-820 (enforced copy) — the removal targets the LIST positions only; the $gt/$gte/$lt/$lte references (:197-209, :801-804) STAY, they are the [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 capability.
• Dispatch only after [spec] parseFilterAST lowers ['a', '=', { $field: 'b' }] to a bare field spec no backend reads as equality #7597's PR merges; re-verify these anchors on the post-merge ref, and re-price this card with [spec] parseFilterAST lowers ['a', '=', { $field: 'b' }] to a bare field spec no backend reads as equality #7597's dev's answer on whether the lowering change moves the removal scope.

---

Generated by Claude Code