fix(driver-sql): $not 取反前先把操作数编译成全域谓词,NULL 行不再被静默排除 (#5146)

[os-zhuang]

Fixes #5146

按维护者在 #5146 上的拍板落地 engine 半边:$not 在 driver-sql 上改为 NULL-safe,
与 driver-memory / formula(2:1 的多数派)给出同一个答案。

开工前的事实核对(issue 写于今晨,sql-driver.ts 当天被 PR #5243 大改)

worktree 基于 origin/main@88b9b2d5c(含 #5243)。逐条实测,issue 正文引用的三处实现
与实测 SQL 仍然成立:

issue 的说法	现场实测(#5243 之后)	结论
$not → 裸 not (…),NULL 行被排除	select id from deal where not (stage = 'won') → 只返回 stage='lost' 的行	成立
driver-memory / formula 返回 NULL 行	两者对 { $not: { stage: 'won' } } 都返回 stage 为 null / 缺失的行	成立
分叉二 $not: {} → TRUE	已修:where 1 = 0 → 零行	已由 #5243 落地,本单一行不动

归约与 NULL-safe 改写没有互相够不到的问题。 #5243 的 reduceFilterNode 只对
空组合子做三值归约($not of TRUE → FALSE、$not of FALSE → TRUE),判定是结构性
的、与 NULL 无关;带真实谓词的 $not 一律归约成 'clause' 并进入编译分支,正是本次
改写生效的地方。改写发生在归约之后,且保证不改变任何节点的归约结论(每个加了守卫的
合取项仍带字段键,'clause' 还是 'clause'),所以 #5243 钉住的行为全部原样保留 ——
测试里对 { $not: {} }、$not of {$or: []}、非 filter 节点操作数的 ADR-0112 拒收
都各留了一条 pin。

实现

改动只有一处编译分支:applyFilterCondition 的 $not 在取反之前,先用新的纯函数
nullSafeNegationOperand 把操作数改写成全域(total)谓词 —— 永远 TRUE 或 FALSE,
不会是 UNKNOWN。

-- 之前
not (`stage` = 'won')
-- 现在
not ((`stage` is not null) and (`stage` = 'won'))

对 issue 给出的扁平形状,这与正文要求的 NOT (…) OR col IS NULL 完全等价。两点是刻意
的、也是我唯一在 issue 文字之外做的判断:

1. 守卫下推到每个叶子,而不是挂在 NOT 旁边。 二者只在扁平形状上等价。$not 内含
$or 时,顶层的 OR col IS NULL 会把 JS 家族排除的行重新放进来 —— 某列为 NULL、
但 $or 的另一个分支成立的行。下推之后 De Morgan 在两值叶子上成立,$and / $or /
嵌套 $not 全部无需特例(嵌套 $not 由它自己的分支负责,NOT 全域 本身即全域)。
测试里 $not: { $or: [{stage:'won'},{owner:'u1'}] } 就是这一条的 pin。

2. 守卫方向按算子逐个判定,不是一刀切。 { $not: { a: { $ne: 5 } } } 的语义是
「a 就是 5」,两个 JS 后端都把 NULL 行排除;无条件加 OR a IS NULL 会把这些行交回去 ——
正是 #2704 / #5134 那一族的静默放松。所以:

算子	缺值时 JS 家族的答案	编译形状
$eq / 隐式 = / $in / $gt $gte $lt $lte / $between / $contains / $startsWith / $endsWith / $regex	false	col IS NOT NULL AND (…)
$ne / $nin / $notContains	true	col IS NULL OR (…)
$null / $exists / $eq: null / $ne: null	本就是全域谓词	不加任何守卫

所有取值都是实测得到的(对 driver-memory 与 formula 跑了同一张表),不是推断。

行为变化(必读:这是可见集合的变化)

{ $not: { col: v } } 现在返回 col IS NULL 的行,以前不返回。

对 RLS 的意义:权限规则里的 CEL !expr 经 packages/formula/src/cel-to-filter.ts 降解
成 { $not: {…} },所以同一条 read scope 在 SQL 数据源上的可见集合会变大 ——
变大的部分正好是「被否定的那一列没有值」的行。举例:read scope 写
!(stage == 'won'),一条 stage 为空的记录以前在 SQL 后端上看不见、在内存后端 /
写侧 check 上看得见;现在三者一致地看得见。

需要留意的部署形态:如果某条 scope 事实上依赖了旧的「NULL 行被顺带排除」来隐藏数据,
本次之后它不再隐藏 —— 那种依赖本来就是不可移植的(换个驱动就失效),正确的写法是把
col IS NOT NULL 的意图显式写出来({ $and: [ { col: { $null: false } }, { $not: {…} } ] })。
changeset 里同样按「可观察行为变更」写明,不是内部重构。

$ne / $nin 反向的一侧没有被放松:{ $not: { a: { $ne: 5 } } } 仍然只返回
a = 5 的行。普通(非否定)比较的 SQL 逐字符不变,测试里有直接的 SQL 文本断言;
所以本次不会让任何非否定谓词失去索引利用,$not 路径上新增的 IS NOT NULL 守卫处在
一个原本就不可 sargable 的 NOT (…) 里面。

测试

三包各一组 pin(覆盖:NULL/缺失行在 $not 下的去留、嵌套 $and/$or/双重否定、
逐算子极性、以及非空行的既有行为不回归)。SQL 侧同时断言生成的 SQL 文本(沿用该目录
既有的 knex toString() 断言先例)。

• packages/plugins/driver-sql/src/sql-driver-not-null-safe.test.ts(新增,25 条)
• packages/plugins/driver-memory/src/memory-matcher-not-null-safe.test.ts(新增,17 条)
• packages/formula/src/matches-filter-not-null-safe.test.ts(新增,17 条)
• packages/plugins/driver-sql/src/sql-driver-null-operators.test.ts:唯一一条需要
  改期望的既有用例 —— 它原本把三值逻辑的结果(['3'])当成正确答案钉住,现在按新裁定
  改为 ['2','3','4'],并在注释里写明这就是行为变更本身。

两个 JS 后端彼此不一致的角落($notContains 对 null 值、$exists 对「键存在但值为
null」、driver-memory 对缺键 $nin)按实测分别钉住,没有假装一致 —— 这几处
不在 #5146 的裁定范围内,已另行记录(见下)。SQL 侧对 $notContains 跟随 formula,
理由:那正是本驱动今天已有的答案,不借这次改写顺手裁定一个没人裁定过的语义。

验证(均在共享锁下、NODE_OPTIONS=--max-old-space-size=4096):

• turbo test --filter=@objectstack/driver-sql --filter=@objectstack/driver-memory --filter=@objectstack/formula --filter=@objectstack/driver-sqlite-wasm → 全绿(driver-sql 754 passed / 44 skipped;driver-sqlite-wasm 继承 SqlDriver,用真实 sql.js 引擎跑同一张 FILTER_LOGIC_CASES)
• turbo typecheck(同三包)→ 全绿
• eslint(改动的 5 个文件)→ 零告警
• 连带面回归:objectql(1868)、plugin-security(731)、service-storage(283)、plugin-audit(108)→ 全绿

范围说明

• 分叉二($not: {} → FALSE)不在本单 —— 已随 SqlDriver.applyFilterCondition 丢弃编译成空的 $and/$or 子过滤器，而不是套用布尔单位元 —— 与同仓 matchesFilterCondition / driver-memory 相反 #5134 / PR fix(driver-sql): 空 $and/$or/$not 按布尔单位元编译，$or: [] 不再返回全表 (#5134) #5243 落地,本 PR 未改动
  相关代码,只补了 pin。
• spec 半边另计 —— FilterConditionSchema 的契约 TSDoc 与 FILTER_LOGIC_CASES 的
  跨驱动 conformance case 归 spec 车道(建议随 [spec] FILTER_LOGIC_CASES 补空组合子的布尔单位元四条 —— 需与 driver-mongodb 的单位元归约同时落地 #5239 与 driver-mongodb 同批落)。本 PR
  未触碰 packages/spec/。engine 半边先落不会造成 declared ≠ enforced:它让实现满足
  「同一算子同一答案」这条既有要求,spec 半边补的是把该答案写明。
• packages/plugins/driver-mongodb/ 未触碰([spec] FILTER_LOGIC_CASES 补空组合子的布尔单位元四条 —— 需与 driver-mongodb 的单位元归约同时落地 #5239 要求与 spec 那张表同时落地)。
• 下游连带(cloud 车道,不在本仓修):cloud#1076 的 RemoteTransport.buildWhereSQL
  当前跟随 SQL 家族发裸 NOT (…)。本 PR 合入后 framework 侧变为 NULL-safe,cloud remote
  会成为新的少数派,需要同向跟进。

---

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 4, 2026 4:06pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql.

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

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sql)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx (via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/driver-sql)
• content/docs/releases/implementation-status.mdx (via @objectstack/driver-sql)

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.

[os-zhuang]

范围外发现(已按 Prime Directive #10 单独立 issue,均未在本 PR 修)

实测过程中扫到三处邻接分叉,都不属于 #5146 的裁定范围,本 PR 一行未动:

• read-scope-sql 的 $not 有两处与 SQL 驱动分叉:非 NULL-safe(#5146 后的最后一个异类),且 { $not: {} } 编译成空 → RLS 整表放行 #5297 —— service-analytics 的 read-scope-sql.ts 有它自己的 $not 降解,同样
  发裸 NOT (…):本 PR 合入后,它是仓内最后一个按三值逻辑回答 $not 的 SQL 家族
  实现(同一条 read scope,普通查询与分析查询可见集合不同)。同一函数里
  { $not: {} } 还会编译成空字符串,而调用方 applyReadScope 有 if (!sql) return;
  —— 一条 RLS scope 因此完全不加 WHERE,即 SqlDriver.applyFilterCondition 丢弃编译成空的 $and/$or 子过滤器，而不是套用布尔单位元 —— 与同仓 matchesFilterCondition / driver-memory 相反 #5134 那条静默放松在这个编译器上尚未
  落地。该包是 dataset 跨 datasource JOIN 应在编译/发布期就被拒绝,而不是留到查询期才响亮失败(#5033 的后续) #5115 的在飞文件面,故只记录不动手;修的时候可直接照抄本 PR 的
  nullSafeNegationOperand。
• 非否定路径上的 $ne / $nin / $notContains:driver-sql 排除 NULL 行,driver-memory / formula 返回它们(#5146 只裁定了 $not) #5298 —— 非否定路径上的 $ne / $nin / $notContains:SQL 排除 NULL 行,
  两个 JS 后端返回它们(实测三条)。$not 的语义在 driver-sql 与 driver-memory / formula 之间分叉：NULL 行的去留相反，$not: {} 一个是 TRUE 一个是 FALSE #5146 只裁定了 $not,本 PR 刻意没有碰非否定路径
  (那会改变每一条普通查询的 SQL 形状与索引利用,是另一个量级的决定)。需要单独拍板。
• driver-memory 与 formula 对「字段没有值」给出三处不同答案:$notContains(null 值)、$exists(键在值为 null)、$nin(缺键) #5299 —— 两个 JS 后端彼此在三处不一致:$notContains(值为 null)、$exists
  (键在、值为 null)、$nin(缺键)。本 PR 对这三格一律不做决定:$notContains
  跟随 formula(那正是本驱动今天已有的答案),$exists 保持 IS NOT NULL。三家实测
  答案已按现状钉在新增的 pin 测试里,裁定之后改动会立刻被顶出来。

---

Generated by Claude Code