driver-memory 与 formula 对「字段没有值」给出三处不同答案:`$notContains`(null 值)、`$exists`(键在值为 null)、`$nin`(缺键)

[os-zhuang]

修 #5146 时,为了给 SQL 侧找一个「JS 家族的正确答案」而把两个 JS 后端逐算子跑了一遍,
顺带测出它们彼此在三处不一致。不在 #5146 范围内(那单裁定的是 $not 在 SQL 上
的 NULL 语义),按 Prime Directive #10 记录。

事实(实测)

两组 fixture,区分「键在、值为 null」与「键不存在」:

• NULLED:3: { stage: null }、4: { stage: null }
• MISSING:3: {}(无 stage 键)、4: {}

filter	driver-memory match(值为 null)	driver-memory(缺键)	formula(值为 null)	formula(缺键)
{ stage: { $notContains: 'w' } }	不匹配	不匹配	匹配	匹配
{ stage: { $exists: true } }	不算存在	不算存在	算存在	不算存在
{ stage: { $nin: ['won'] } }	匹配	不匹配	匹配	匹配

成因都在 packages/plugins/driver-memory/src/memory-matcher.ts 的 checkCondition:

1. 早退守卫 if (value === undefined && op !== '$exists' && op !== '$ne' && op !== '$null') return false;
   —— 豁免名单里没有 $nin,所以缺键的记录直接判 $nin 不通过,而同一记录若把字段
   写成 null 则通过。formula 的 evalOp 两种情况都判「不在集合里」→ 通过。
2. case '$notContains': if (typeof value !== 'string' || value.includes(target)) return false;
   —— 值不是字符串(null / undefined)一律判否;formula 的
   !(typeof actual === 'string' && actual.includes(v)) 判是。
3. $exists 两边读的是不同的东西:driver-memory 读「有没有值」
   (value !== undefined && value !== null),formula 读「键在不在」
   (actual !== undefined)。对「键在、值为 null」这一格必然相反。

为什么这不是学术问题

matchesFilterCondition 是 RLS 写侧 check 的求值器(insert/update 的后像),
driver-memory 的 match 是内存驱动的读过滤。同一条策略里写
{ notes: { $notContains: 'secret' } },一条 notes 为 null 的记录在写侧被判「满足」
而在内存读侧被判「不满足」 —— 而 SQL 侧又是第三个答案(NOT LIKE 对 NULL 是 UNKNOWN
→ 不返回)。#5146 只把 $not 这一格统一了,这三格没人裁定过。

顺带说明 PR #5296 在这三格上没有顺手做决定:driver-sql 的 $not 改写对
$notContains 跟随 formula(理由:那正是该驱动今天已有的答案,不借改写引入一个没人
裁定的语义),$exists 保持 IS NOT NULL(SQL 分不出「键不在」和「值为 null」)。
三个后端的实测答案都已按现状钉在测试里:

• packages/plugins/driver-memory/src/memory-matcher-not-null-safe.test.ts
  的 “known disagreements with formula.matchesFilterCondition” 一节
• packages/formula/src/matches-filter-not-null-safe.test.ts
  的 “known disagreement with driver-memory” 一节

所以裁定之后,要改的地方是明确的、且改动会立刻被这两组 pin 顶出来。

需要拍板的

1. $notContains 对「没有值」的字段是否成立?(SQL 侧天然是「不成立」,formula 说
   「成立」,driver-memory 说「不成立」。)
2. $exists 的语义是「键存在」还是「有值」?两者在 SQL 上不可区分,所以选「有值」能让
   三家统一,选「键存在」则 SQL 永远无法兑现 —— 按 declared = enforced,倾向前者。
3. $nin 对缺键记录:driver-memory 的早退守卫应把 $nin(以及同族的
   $notContains)一并豁免,还是维持?

建议与 #5146 的 spec 半边、#5239 的 FILTER_LOGIC_CASES 扩表一并裁定,并把这几格写进
那张跨后端表 —— 它今天刻意不含 null 处理,所以这三处分叉现在没有任何门禁能发现。

关联

#5146 / PR #5296($not 的 NULL 语义,已拍板并落地 engine 半边)、#5298(非否定路径上
$ne/$nin/$notContains 的 SQL vs JS 分叉)、#5240({ field: {} } 的三个答案)、
#5239(conformance 表)。

[os-zhuang]

补一条实测:这三个算子的分叉不止 memory ↔ formula,driver-memory 自己的两个过滤面之间就已经分叉

做 #5324 / #5328(normalizeFilterCondition 的形状门)时,把 FILTER_LOGIC_CASES 穿透到真驱动后,顺手对 memory-matcher-not-null-safe.test.ts 的整张表做了「实时 mingo 路径 vs 参考匹配器」的逐条比对。本 issue 记的同样三个算子,在同一个包的两个面之间也给出不同答案 —— 而实时路径正是用户真正跑到的那一面。

实测原文(worktree 基于 c7406b0ec + #5324 的修复;InMemoryDriver.find vs memory-matcher.match,同一份 fixture):

                          live(mingo)   ref(matcher)
NULLED   plain $exists    1,2,3,4       1,2          >>> 分叉
MISSING  plain $nin       2,3,4         2            >>> 分叉
NULLED   $not $notContains 1            1,3,4        >>> 分叉

注意前两条不带任何 $not —— 所以这不是 #5146 的否定语义问题,是算子本身在「字段没有值」时的读法不同:

算子	mingo(实时路径)	memory-matcher(参考匹配器)
$exists	键存在即为 true(值为 null 也算存在)	「有值」才为 true(value !== undefined && value !== null)
$nin	缺键的文档匹配(missing ≠ 'won')	checkCondition 开头的 value === undefined 守卫只豁免 $exists/$ne/$null,所以缺键直接 false
$notContains	正则不匹配 null → true	typeof value !== 'string' → false

也就是说本 issue 的表应该是三列而不是两列:driver-memory(实时) / driver-memory(匹配器) / formula。$exists 这一行上,实时路径的读法(键存在)与 formula 相同,反倒是参考匹配器是少数派 —— 这对「哪个读法是 canonical」的裁决是直接相关的证据。

为什么 #5324 没有一并修

那一单加的是形状门(词汇表、$between 元数、组合子操作数),对语义一律不碰:这三条是同一个算子在两个求值引擎里的不同读法,修它需要先裁决哪个读法是 canonical,那是本 issue(和 #5298 / #5239)的事,不是一个 shape gate 能顺手带走的。

现状已按实测钉在 packages/plugins/driver-memory/src/memory-driver-document-not.test.ts 的 known two-face divergences on a value-less field — pinned, see #5299 一节里,并在注释里指向本单 —— 好让分叉是可见的、而且本单落地时必须有意识地去改那三行,而不是让它悄悄变绿。

未验证:我没有测 driver-sql / driver-sqlite-wasm / driver-mongodb 在这三个输入上的答案,所以不知道五个后端的完整分布(#5298 覆盖了 $ne/$nin/$notContains 的 SQL 侧一半)。

---

Generated by Claude Code

[os-zhuang]

分诊（backlog sweep，主 backlog 代扫）：挂 finding + domain:engine。理由：跨执行面语义分歧（driver-memory 与 formula 对「字段没有值」三处答案不同）是实锤，但哪一面是对的需要一次语义裁决（先例：#5146 之于 $not、#5240 之于空对象）——裁决出来之前没有可写进派发词的验收判据，故按 finding 持有。晋级路径：engine 车道 PM 起 [决策] 单或并入下次发现分诊轮，与 #5298 宜同一次裁决处理。不构成认领。会话：session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code

[os-zhuang]

范围注记（2026-08-05，维护者裁决，锚点 #5499）：driver-memory 投入已冻结，本单三处分歧中涉 driver-memory 的部分随之冻结；formula 侧对「字段没有值」的语义是否自洽仍是活问题，故保留 finding 不转 on-hold。下次发现分诊轮请以 formula（及 driver-sql 对照）重新框定；若重框后 formula 侧无独立缺陷，可引用锚点关闭（not planned）。会话：session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code