fix(analytics): refuse a { $field } comparand on both SQL-lowering doors instead of binding it (#7598)

[os-help]

Part of #7598

⛔ Part of, not Fixes: the card asks for the #5222 capability to be PORTED to these two compilers, and this PR does not port it — it closes the silent defect the port's premise-check uncovered and leaves the port itself in the decision box (see "What this does not do"). Merging it should not close the card.

⚠️ The premise was inverted, and the truth is worse

#7598 reads: "service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces."

Measured on origin/main @ 5823d593d, nothing 400s. For the six scalar comparison operators — exactly the ones #5222 taught driver-sql to compile into a same-table column-to-column comparison — both doors COMPILED, and put the reference object in the bind list:

face	{ amount: { $gt: { $field: 'budget' } } }
read-scope-sql	"person"."amount" > ? · bind list [{"$field":"budget"}]
where → NativeSQLStrategy	WHERE amount > $1 · bound to the JSON TEXT {"$field":"budget"}
where → /analytics/sql echo	WHERE amount > $1 · bound to the reference OBJECT
where → ObjectQL engine	{amount:{$gt:{$field:'budget'}}} reaches driver-sql, which compiles it correctly since #5222

So the defect was never a refusal — it was a silent wrong answer: a syntactically perfect predicate comparing a column against a value no row can hold. Three of the four faces disagreed, and the one answering wrongly on the read-scope door is an administrator's RLS predicate, which is why that half is graded above the where door's empty chart.

The gates assumed to be catching this (isBindableComparand / isRenderableTextComparand) had not drifted from driver-sql — they are simply never ASKED about that position. Both doors consult them for the LIKE family and for $in / $nin / $between MEMBERS only, so the whole comparand of a scalar comparison was unguarded on both.

Two corollaries worth stating, because the card predicted otherwise:

• The "stale convergence comment" is not stale. The pinned case in comparand-shape-refusal.test.ts is {name: {$contains: {$field: 'status'}}} — a LIKE-family operator, which [spec] SqlDriver 将 $field 编译为列对列比较(cross-field comparison push-down) #5222 left in its own refusal arm (a column-side LIKE pattern cannot be metacharacter-escaped portably). That pin still converges with driver-sql, verbatim, and is deliberately unchanged. Only its comment gains the re-measurement.
• $between on the where door was the one comparand position no shape gate had ever seen — its branch in fieldLeaves lowers to gte / lte leaves and returns before assertCompilableComparand runs.

What this PR does

Both doors refuse a { $field } comparand whose value is a string, in the positions that were BOUND — the six scalar comparison operators' whole comparand, plus the two $between endpoints — each in its existing envelope: INVALID_FILTER / 400 on the analytics where door, READ_SCOPE_COMPILE_FAILED / 500 on the read-scope lowering. comparand-shape.ts gains the third question (isFieldReference) and owns the shared sentence, exactly as it already owns the other two; each door keeps its own throw.

Positions that already refused keep their exact wording, because each of those refusals already converges with driver-sql's own #5222 refusal arm. read-scope-sql's header goes from twelve refusing sites to thirteen.

The reference shape is read exactly as driver-sql's fieldReferenceOf reads it: extra keys do not disqualify it (formula's resolveValue ignores them too), and a $field whose value is not a string is NOT a reference — it stays the ordinary object-comparand account #5234 deliberately left open.

⚠️ What this deliberately does NOT do, and the cost taken

It does not bring the capability to these compilers.#5222's four maintainer rulings (2026-08-06) — same-table only, declared-only enumeration, tenant-isolation column forbidden on both sides, same comparison class — all turn on metadata driver-sql reads from its own initObjects capture. StrategyContext (@objectstack/spec/contracts) exposes neither an object's declared field set nor its tenant-isolation column, so these compilers cannot enforce the rulings at all, and the dispatch's own instruction for that case is to stop rather than ship a weaker port. Implementing it here is a packages/spec contract question first, which is out of this card's declared surface.

Refusing at the where door narrows the ObjectQL engine path, which today passes the reference through to a driver that handles it properly. That cost is taken deliberately and is the part to re-open if the maintainer rules otherwise: the pass-through is an accident of convertFilter forwarding an unrecognised comparand (nothing here validates it, no test pinned it), and leaving it makes one authored where mean two things depending on the backend behind the cube — with the other two emitters unable to agree either way.

The mandated envelope correction is NOT made. The dispatch requires that an unsupported rule stop presenting as a server error on read-scope-sql (4xx + locating information). That conflicts head-on with the #5367 maintainer ruling of 2026-08-06, quoted verbatim and untranslated from the module header, which rejected a 4xx including a 422:

⚠️ Deliberately NOT a 4xx of any flavour, including a 422. Option A on the decision card was READ_SCOPE_INVALID / 422 ("not your fault, not a crash"); it was rejected because no consumer reads a code on this path (so a new vocabulary had no measured pull), because a 4xx cannot be fixed by the client and therefore misreports the condition, and because 422 would have left the disclosure question to be re-decided message by message.

Both of that ruling's arguments apply to this shape verbatim rather than by analogy: the producer is an admin-authored sharing rule and its CEL lowering (compileCelToFilter is exactly what emits { $field: path }), so a 4xx bills a caller who cannot author the document; and a 4xx echoes the message, which here names the POLICY's field names — the disclosure #5367 closed. Re-adjudicating a maintainer ruling is not this seat's to do, so it is raised as an open question instead.

Verification

• @objectstack/service-analytics: 72 files / 1551 tests passed (1444 before — the new file adds 107). ESLint clean on every changed file with --no-inline-config.
• Gates: check:nul-bytes OK (7091 files, self-test 75 assertions), check-changeset-fixed OK (69 public packages), check:docs-audit-scope OK, pnpm install --frozen-lockfile clean.
• The shared corpus is driven through both faces: CROSS_FIELD_CASES and CROSS_FIELD_REFUSALS are imported from @objectstack/driver-sql (new devDependency only — service-automation sets the precedent; no runtime edge added). Every case in both arms is refused on both doors, which is the asymmetry [spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 records, stated as an executable fact.
• Corpus messageIncludes are deliberately not asserted — those pin driver-sql's wordings, and a driver message naming initObjects declarations would be a lie on this side. The envelope is asserted for every case; the wordings are asserted separately, per door.

Reverse verification — direction predicted in writing before running

Both assertNoFieldReferenceComparand call sites disabled. Predicted: the scalar / $between cells go red by resolving (not by some other throw); the LIKE-family and list-member cells stay green; comparand-shape-refusal.test.ts stays fully green.

Measured: 87 failed / 47 passed, and every failure reads expected the compiler to refuse this filter, but it returned … — the predicted cells, failing in the predicted manner. On a targeted re-read: not one LIKE-family or $in / $nin case went red, proving the gate is narrow and those refusals come from the #5234 gates; the two $between-endpoint cases went red on the where door only, staying green on the read-scope door where assertCompilableMembers already refused them — which is precisely why $between had to be named on the where door; and comparand-shape-refusal.test.ts stayed green in full.

Restored by inverse edit inside this worktree (no git stash); grep confirms zero markers remain and the suite is green again.

Out of scope, filed

• [finding] $icontains is absent from analytics TEXT_PATTERN_OPERATORS, so the #5234 comparand fence never covered it on the where door — one operator, two answers inside one package #7693 — $icontains is absent from TEXT_PATTERN_OPERATORS, so the driver-sql:两类无意义比较对象仍编译成「静默空谓词」—— $in/$nin 的非 $field 对象成员,与 LIKE 族的对象比较值(String 成 [object Object]) #5234 comparand fence never covered it on the where door: {name: {$icontains: {foo: 1}}} still compiles to LIKE '%[object Object]%' there while read-scope-sql refuses it. Pinned as a RECORDED GAP block in the new suite so it shows in test output instead of being re-discovered. Same class as objectql having has no $icontains comparand-shape gate — an empty comparand matches EVERY row (2 of 5 FILTER_TEXT_CASES rejection rows unenrollable) #7158 at a third face.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 11, 2026 10:32am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics.

5 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/data-api.mdx(via @objectstack/service-analytics)
• content/docs/api/index.mdx(via @objectstack/service-analytics)
• content/docs/kernel/services-checklist.mdx(via @objectstack/service-analytics)
• content/docs/permissions/sharing-rules.mdx(via @objectstack/service-analytics)
• content/docs/plugins/packages.mdx(via @objectstack/service-analytics)

⛔ 3 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/service-analytics)
• content/docs/releases/v17.mdx(via @objectstack/service-analytics)
• content/docs/releases/v9.mdx(via @objectstack/service-analytics)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.