fix(service-analytics): the read-scope compiler refuses a list under $eq instead of binding it

[objectstack-fleet]

Fixes #19975

Clause-②: no (narrowing)

What this changes

compileScopedFilterToSql (packages/services/service-analytics/src/read-scope-sql.ts) lowers a row-level read scope into the SQL that the analytics NativeSQL path executes and the /analytics/sql echo prints. It already refused a list in the implicit equality slot ({ f: [...] }) with READ_SCOPE_COMPILE_FAILED / 500. The explicit spelling, { f: { $eq: [...] } }, compiled to an equality with the whole list bound as one parameter, which left the meaning of the predicate to the executing database.

A new gate, assertNoListInEqualitySlot, refuses that spelling in compileField, at any depth under $and / $or / $not, in this module's own envelope. It runs before the member gates, so a list is reported as a list and not by one of its members. This applies ruling 乙 (#19757, record 5793368540: 「an array in the implicit-equality slot is refused at the shared face, for every driver at once」) to a compiler that never reaches the shared face.

Declaration

BREAKING: this narrows what compileScopedFilterToSql, exported from @objectstack/service-analytics, accepts. A read scope carrying { f: { $eq: [...] } } compiled before this change and is refused after it. The remedy is { f: { $in: [...] } }. The changeset ships the narrowing as minor under the launch-window convention for accept-set narrowings, with a ! on its headline, the Clause-②: no (narrowing) line and an ADR-0087 not-required (no-migration-prescription) disposition: no authorable key, spelling or stored shape moves, and an authored policy never emits this spelling.

Measured first

The measurement was recorded on this branch as c647adb6cc, before any source change. This is an abstract summary; the tests are the pins.

• Authoring door. The published RLS policy schema and the RLS authoring lint's decision procedure both admit an equality predicate whose comparand is a list, whether a list literal or a membership variable.
• Lowering. That predicate lowers to the implicit spelling. The CEL lowering emits $eq only around a { $field } reference, so no authored policy produces a list under $eq. The tenant layer, the sharing read filter and the controlled-by-parent filter do not emit $eq at all.
• This compiler. The implicit spelling reaches it through the security service's read filter and is refused (500). A list under $eq reaches it only from a host-supplied getReadScope or from a direct caller of the export, and it compiled.
• Engines. On the NativeSQL execute path the bound list got four different answers depending on the engine: a driver error, zero rows, rows the scope never named, and every row when negated. Measured on better-sqlite3 and sql.js through the drivers, and on a local PostgreSQL 16 through driver-sql and through a plain pg pool. MySQL is NOT MEASURED: there is no server in the container.

Deliberate choices

• 500, not the shared face's 400. The analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 ruling, re-affirmed as [spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 Q2 = A and recorded in this module's header, keeps every refusal of this compiler at READ_SCOPE_COMPILE_FAILED / 500 with the message withheld. The scope is a policy the caller cannot author, and a 4xx would echo it back to them. The card's 400 belongs at the policy's authoring door, which is not this file.
• The module's own wording, not a call into the shared face. assertListComparandShapes throws INVALID_FILTER / 400. It also judges more than the equality slot: list-operator shapes, null members, null ordering comparands and $between bounds. Calling it here would change other refusals of this compiler, and each of those has its own ruling on this door. The new sentence follows this module's bare-array refusal, so both spellings of the one condition read the same way in the operator's log.
• $ne with a list is not judged. Ruling 乙 names equality only. $ne falls under ruling A of [finding] $ne with an array comparand splits across backends: driver-sql and driver-memory refuse (400), driver-mongodb answers, formula matches every row — and both shared faces pass it #19886 and is handled on that card.

Compile surfaces (a list in the equality slot)

surface	verdict
compileScopedFilterToSql (service-analytics read scope)	changed. A list under $eq is refused. The implicit list was already refused and is now pinned at every depth.
assertListComparandShapes (spec shared face)	already compliant. This is ruling 乙's own face (#19882, landed). Measured: INVALID_FILTER / 400 for the implicit list, for $eq, and under $not.
matchesFilterCondition (formula)	already compliant. Measured: INVALID_FILTER / 400 for the same three shapes (#19886 stage 2a).
applyFilterCondition (driver-sql)	already compliant. It refuses with 400 at the driver and behind the engine's shared-face seam (table in the #19882 changeset; not re-measured here).
buildWhereSQL (driver-turso RemoteTransport)	already compliant. 400 according to the compile-face table in the #19886 stage-2a report; not re-measured here.
checkCondition (driver-memory)	already compliant. 400 at every depth (table in the #19882 changeset).
translateFieldOperators (driver-mongodb)	out of scope. The driver answers with MongoDB array equality. Platform doors reach it only through the shared face, which refuses (the declared scope of #19882).
lowerAnalyticsWhere (analytics caller where)	out of scope. This is the caller-authored filter door (the INVALID_FILTER / 400 family), not a read scope. Its object-form $eq list cell still reads accept in the frozen comparand matrix. The claim records #19888 against this file.
applyHaving / matchesHaving (objectql HAVING)	out of scope. A caller-authored filter applied after aggregation, not a read scope. Its answers are recorded in the #19886 stage-2a report.

The analytics ObjectQL execute route never calls this compiler. It hands the scope to engine.aggregate, and the engine's shared-face seam refuses the list with INVALID_FILTER / 400 (measured). See the acceptance notes.

Tests and evidence (head feb810c3d4, after merging origin/main at 276d96dd23)

• New src/__tests__/read-scope-eq-array-refusal.test.ts, 29 tests:
  • $eq lists at every depth, including negation, and beside another operator in either key order;
  • list-before-member precedence ([undefined], [{ $field }]);
  • the implicit list at every depth;
  • seven neighbouring shapes that must compile unchanged;
  • the NativeSQL execute face and the echo face over a real sql.js engine. Both refuse, and no statement reaches the engine. The prescribed $in serves exactly the rows it names.
• read-scope-refusal-envelope.test.ts: inventory row ⑯ added, and the ratchet moves to 16 rows over 14 sites.
• comparand-door-single-source.test.ts: the frozen matrix's read-scope $eq array cell changes from accept to the refusal, with a note. It pinned exactly the bind this PR removes.
• pnpm --filter @objectstack/service-analytics test: 116 files and 2484 tests passed. typecheck exited 0, and tsc --listFiles includes all three touched test files.
• Ablations. Each was run from the committed fix. The mutation went through scripts/ablation-replace.mjs, and each restore was proven by the blob hash matching HEAD.
  • A: removing the gate call turned 18 tests red. These include every $eq pin, both real-engine faces (zero rows served, and every row served under the negation), and inventory ⑯.
  • B: making the bare-array arm bind turned 11 tests red.
• Gates. dispatch-gates derives the same 61 at feb810c3d4 as at 11c11c7dc3, and all 61 were re-run on feb810c3d4: 59 exited 0. Two are NOT MEASURED because their prerequisite was not met (check:dual-build-cjs-loads and check:type-check-debt need the whole workspace built, and CI builds it). Among the 59: check-adr-0087-registration --base origin/main (1 declared-breaking changeset, carrying its disposition), check-changeset-no-major --base origin/main, check:changeset-gate-self-tests and check-issue-citations in its board-probing mode, all exit 0.
• Lint, narrowed to the change. eslint --no-inline-config --format json over the four touched TypeScript files: 4 files, 0 errors, 0 warnings. eslint --print-config resolves a config for each of them. eslint.config.mjs never enables type-aware linting (its own note, near line 326), so this diff cannot change the verdict on any untouched file.

Acceptance notes

• Authoring door, implicit spelling. The authoring-door half of the card for the implicit spelling is work in the [finding] $ne with an array comparand splits across backends: driver-sql and driver-memory refuse (400), driver-mongodb answers, formula matches every row — and both shared faces pass it #19886 lane: draft PR fix(formula, driver-mongodb): refuse == / != against a list literal at the CEL lowering and $ne arrays at the mongodb face #19947 refuses == against a list at the CEL lowering and in the lint. read-scope-sql compiles $eq: [...] in a policy scope as col = ? with the array bound (read-scope-sql.ts:1273) — outside ruling 乙's shared face; a bare array fails closed as 500, not 400 #19975 needs nothing more from it.
• Adjacent finding, filed by the seat, not addressed here. The analytics ObjectQL execute route answers a read-scope list with the engine's INVALID_FILTER / 400, not this compiler's 500.
• Premise correction. PR fix(spec)!: refuse an array in the equality slot at the shared comparand-shape face #19882, ruling 乙's shared face, merged at 2026-09-24T14:44Z, before this branch was cut from ae7a35a63b. The dispatch described it as in flight; it was not.

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 9 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 a666e949c92a43eef9c6b9af413f43127e5ee12c → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json a666e949c92a43eef9c6b9af413f43127e5ee12c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.