fix(analytics): refuse an undefined comparand in a read scope instead of binding it (#6125) (#6390)

`compileScopedFilterToSql` compiled a comparand-position `undefined` into legal
SQL with `undefined` in the bind list. The driver renders that as NULL, every
comparison against NULL is UNKNOWN, and the read scope matched ZERO rows with no
log line — indistinguishable from a scope that worked. Re-measured on d8e8d9c
with the refusal disabled, alias `t`:

  { d: undefined }            -> "t"."d" = ?                                  [undefined]
  { d: { $gt: undefined } }   -> "t"."d" > ?                                  [undefined]
  { d: { $in: [undefined] } } -> "t"."d" IN (?)                               [undefined]
  { $not: { d: undefined } }  -> NOT (("t"."d" IS NOT NULL AND "t"."d" = ?))  [undefined]

One gate at the top of `compileField` — after `quoteIdent`, before any `bind()`
— refuses all four positions with ONE wording that varies only by path (#5240).
The envelope is this module's existing `READ_SCOPE_COMPILE_FAILED` / 500, not
#6050's `INVALID_FILTER` / 400: a read scope is compiled by the platform from
CEL and stored metadata, so a 400 would bill the caller for something they
neither wrote nor can change.

`null` is untouched — SQL and binds byte for byte, pinned as its own control
group, because refusing it alongside `undefined` is the way this change could
do harm.

Per the #6125 ruling, `@objectstack/formula` (a third semantics, #5299),
`driver-memory` / `driver-mongodb` (#5499 freeze) and `driver-sql` /
`driver-turso` (#6050, already landed) are deliberately not touched.

Fixes #6125


Claude-Session: https://claude.ai/code/session_01WyvqvKMG6asi9aXjKE6xtx

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/read-scope-undefined-comparand-refusal.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): read scope 里的 `undefined` 比较数改为拒收，不再编成绑了 `undefined` 的合法 SQL (#6125)
+
+**⚠️ 行为变更。** `compileScopedFilterToSql` 遇到比较数位置上的 `undefined`，从「编出合法 SQL、绑一个 `undefined`、匹配零行、零日志」改为 `READ_SCOPE_COMPILE_FAILED` / **500** 拒收。
+
+## 实测到的毛病
+
+#6050 于 2026-08-07 裁定（B 案）：比较数位置的 `undefined` 一律拒收，并落在了**已证实可触达**的 `driver-sql` / `driver-turso` 两面。#6125 在同一轮把仓内其余求值面逐格实测，同一个形状拿到五种读法；本条改的是其中一格 —— `service-analytics` 的 `read-scope-sql.ts`。在 `d8e8d9cbc` 上把本次拒收关掉复测，alias `t`、字段 `d`，四格与 #6125 正文表一致：
+
+| read scope | 编译结果 | 绑定表 |
+|---|---|---|
+| `{ d: undefined }` | `"t"."d" = ?` | `[undefined]` |
+| `{ d: { $gt: undefined } }` | `"t"."d" > ?` | `[undefined]` |
+| `{ d: { $in: [undefined] } }` | `"t"."d" IN (?)` | `[undefined]` |
+| `{ $not: { d: undefined } }` | `NOT (("t"."d" IS NOT NULL AND "t"."d" = ?))` | `[undefined]` |
+
+绑定表里是 JS 的 `undefined` 本身，不是 `null`：`applyReadScope`（`native-sql-strategy.ts`）在把 `?` 改写成 `$N` 时原样 `push(scopeParams[i])`。所以 NULL 是**驱动**对一个 JS `undefined` 的读法 —— 同一格在不肯猜的驱动上则是一句裸 `Undefined binding(s)` 崩溃。一次绑定、两种败法，取决于数据源恰好挂的是哪个驱动，这正是它该在编译器处拒收、而不是在某一个消费者处修补的理由。
+
+方向与 #6050 不同，如实记：那边是**越权**（`{ owner_id: ctx.user?.id }` 在 Turso remote 上编成 `IS NULL`，匹配全环境行）；这边是 fail-**closed** —— 匹配零行，永远不会多给行。所以它不是潜伏的权限绕过，#6125 也没有按那个级别定级。之所以照样拒收：一个「答了没人问的问题、且一条日志都不报」的 read scope，与一个真的生效了的 read scope 在外部完全无法区分。本次改动的价值就是把沉默变成响亮。
+
+## 修法
+
+一道闸落在 `compileField` 的开头 —— 在 `quoteIdent` 之后（不安全标识符是注入向量，保留它自己的措辞与优先级），在任何 `bind()` 之前。
+
+拒收的**位置**逐个清点，因为「比较数」是位置而不是类型：直接比较数（`{ d: undefined }`）、单值算子的比较数（`$eq`/`$ne`/`$gt`/`$gte`/`$lt`/`$lte` 与 LIKE 族）、列表算子数组的**成员**（`$in`/`$nin`/`$between`）。四格共用**一条**措辞，只有 `path` 不同（#5240「一个条件，一种措辞」）。
+
+信封沿用本模块自述的那一个（`READ_SCOPE_COMPILE_FAILED` / 500），不是 #6050 的 `INVALID_FILTER` / 400：read scope 的 filter 由平台自己从 CEL 与库存 metadata 编译而来，不是调用方输入 —— 报 400 等于让调用方去修一个他既没写、也改不动的东西。消息里指名要修的是**生产者**（管理员写的共享规则 / 权限集、它的 CEL 下降、或进程内拼这条 FilterCondition 的代码），并按 #5367 只进日志、不进响应体。
+
+三个位置**故意不扫**，各自因为本模块已经用更贴切的诊断拒了它：`$null` / `$exists`（比较数是声明的布尔量，不是比较数位置）、直接位置上的裸数组（`compileField` 整体拒「用 `{ $in: [...] }`」）、以及约束对象里的非 `$` 键（那是嵌套关系，改写成 `null` 一样编不过 —— 这一条是与 `driver-sql` 孪生实现的唯一有意分歧，来自本模块拒收嵌套关系，而不是对 #6050 的另一种读法）。
+
+## ⛔ `null` 一字未动
+
+`{ d: null }` / `{ $eq: null }` → `IS NULL`；`{ $ne: null }` → `IS NOT NULL`；`$null` / `$exists`、`$in: [null]`、`$nin: [null]`、`$between: [null, 5]`、`$contains: null`（`%null%`，#5526）、以及 `$not` 下的各式 —— SQL 与绑定表逐字节不变。这是本次改动唯一可能造成伤害的方向（模块里每张极性表都只用一个 `===` 把 `null` 与 `undefined` 分开），所以它有自己的对照组回归 pin。
+
+## 刻意不动的邻居
+
+- ⛔ `@objectstack/formula` 把同一个 `undefined` 读作「这个键在记录里不存在」—— 那是**第三种语义**，不是第三个 bug 拼写，也正是 #5299 在争的问题。在这里顺手改掉等于替 #5299 拍板。
+- ⛔ `driver-memory` / `driver-mongodb` 维持 #5499 投入冻结，只 pin 不改。后果是本编译器与 `driver-memory` 在这一格上从此不一致 —— 这是裁决接受的代价，解冻时一并还，账记在 #6125。
+- ⛔ `driver-sql` / `driver-turso` 已由 #6050 落地，未触碰。

packages/services/service-analytics/src/__tests__/read-scope-refusal-envelope.test.ts

@@ -41,6 +41,18 @@
  * code and all ten fail with `code` / `status` `undefined`, while the block above
  * stays green.
  *
+ * ## [#6125] An eleventh site, and why it is registered HERE
+ *
+ * The `undefined` comparand refusal (row ⑥) was added on 2026-08-07 by #6125's
+ * ruling. It is in this table for the invariant at the bottom of the file rather
+ * than for its own sake: what #5352 cost was a module where SOME refusals
+ * carried the envelope, which is indistinguishable from none of them at the HTTP
+ * boundary. So the rule this table encodes is that the inventory grows whenever
+ * the module gains a refusing site — a new `throw` that is not listed here is
+ * the defect returning. Row ⑥'s own behaviour (four comparand positions, and the
+ * `null` control group that must NOT move) is pinned in
+ * `read-scope-undefined-comparand.test.ts`; only its ENVELOPE is asserted here.
+ *
  * The end-to-end consequence — that the REST face answers
  * `500 ANALYTICS_QUERY_FAILED` with the policy content WITHHELD from the body and
  * intact in `logError` — is `packages/rest`'s
@@ -69,7 +81,7 @@ function refusalFor(filter: unknown, alias = 'crm_opportunity'): Refusal | undef
 /**
  * Every refusing site in `read-scope-sql.ts`, in source order.
  *
- * ELEVEN rows over TEN throw sites: `quoteIdent` is one site reached with two
+ * TWELVE rows over ELEVEN throw sites: `quoteIdent` is one site reached with two
  * `kind` values, and both are listed on purpose. That alias-vs-field split was
  * option C on #5367's decision card — the one place where the two triggers are
  * genuinely different (a bad alias is OUR generator, a bad field is the admin's
@@ -129,42 +141,49 @@ const REFUSALS: Array<{
     sensitive: '$nor',
   },
   {
-    name: '⑥ bare array value',
+    name: '⑥ undefined in a comparand position',
+    site: 'compileField: undefined comparand',
+    filter: { owner_id: undefined },
+    message: /comparand at "owner_id" is undefined — refusing to build read scope \(fail-closed\)/,
+    sensitive: 'owner_id',
+  },
+  {
+    name: '⑦ bare array value',
     site: 'compileField: bare array value',
     filter: { region_code: ['emea', 'apac'] },
     message: /bare array value for "region_code" — use \{ \$in: \[\.\.\.\] \} \(fail-closed\)/,
     sensitive: 'region_code',
   },
   {
-    name: '⑦ nested / relation value',
+    name: '⑧ nested / relation value',
     site: 'compileField: nested/relation value',
     filter: { owner: { manager_id: 'u1' } },
     message: /"owner" has a nested\/relation value which is not supported in a read scope \(fail-closed\)/,
     sensitive: 'owner',
   },
   {
-    name: '⑧ $in without an array',
+    name: '⑨ $in without an array',
     site: 'compileOperator: $in needs an array',
     filter: { region_code: { $in: 'emea' } },
     message: /\$in for "region_code" needs an array \(fail-closed\)/,
     sensitive: 'region_code',
   },
   {
-    name: '⑨ $nin without an array',
+    name: '⑩ $nin without an array',
     site: 'compileOperator: $nin needs an array',
     filter: { region_code: { $nin: 'emea' } },
     message: /\$nin for "region_code" needs an array \(fail-closed\)/,
     sensitive: 'region_code',
   },
   {
-    name: '⑩ $between without [min, max]',
+    name: '⑪ $between without [min,max]',
     site: 'compileOperator: $between needs [min,max]',
     filter: { credit_limit: { $between: [10] } },
     message: /\$between for "credit_limit" needs \[min,max\] \(fail-closed\)/,
     sensitive: 'credit_limit',
   },
   {
-    name: '⑪ unsupported operator',
+    name: '⑫ unsupported operator',
     site: 'compileOperator: unsupported operator',
     filter: { owner_email: { $regex: 'admin@' } },
     message: /unsupported operator "\$regex" on "owner_email" \(fail-closed\)/,
@@ -255,10 +274,12 @@ describe('[#5367] every read-scope refusal carries the ADR-0112 envelope (READ_S
     // #5352's lesson, stated as a guard: seven of `filter-normalizer.ts`'s nine
     // sites carrying an envelope was indistinguishable from none of them at the
     // HTTP boundary, because the commonest input hit one of the two bare ones.
-    // Eleven inputs over the module's ten throw sites (see the table's note on
-    // `quoteIdent`), and every one of them enveloped.
-    expect(REFUSALS).toHaveLength(11);
-    expect(new Set(REFUSALS.map((c) => c.site)).size).toBe(10);
+    // Twelve inputs over the module's ELEVEN throw sites (see the table's note
+    // on `quoteIdent`), and every one of them enveloped. [#6125] added the
+    // eleventh site; these two numbers are the ratchet that makes a future
+    // unenveloped `throw` fail HERE instead of at an HTTP boundary.
+    expect(REFUSALS).toHaveLength(12);
+    expect(new Set(REFUSALS.map((c) => c.site)).size).toBe(11);
     for (const c of REFUSALS) {
       expect(refusalFor(c.filter, c.alias)?.code, `${c.site} is still bare`).toBe('READ_SCOPE_COMPILE_FAILED');
     }