service-analytics 的 `where` 门把 `undefined` 值的键整个丢掉 —— 单键 where 退化成「无过滤器」，方向是加宽（#6125 五面表漏记的第六、七种读法）

[os-zhuang]

出自 #6125 的实施（PR 见下）。#6125 的裁决只派了 read-scope-sql 一格；实施中在同一个包的另一扇门上实测出同一形状的两种新读法，按 Prime Directive #10 另立单、不指派、不扩大那张 PR 的 diff。

⚠️ 这两格不在 #6125 正文的五面表里。 那张表把 service-analytics 记作一行（read-scope-sql），但本包有两扇独立的门：调用方自己写的 where 走 strategies/filter-normalizer.ts（INVALID_FILTER / 400，#5352），平台编译出来的 read scope 走 read-scope-sql.ts（READ_SCOPE_COMPILE_FAILED / 500）。#6125 只实测了后者。

实测（origin/main @ d8e8d9cbc，直接调 normalizeAnalyticsFilterTree({ where })）

where	归一化结果	读法
{d: undefined}	null	整条 where 被丢弃 → 查询无过滤器运行
{stage:'won', d: undefined}	只剩 stage equals 'won'	d 这一合取项静默消失
{$not: {d: undefined}}	NOT (d set)，即 d IS NULL	作者没写过的谓词
{d: {$eq: undefined}}	d equals [null]	值比较（零行），不是 $eq: null 的 notSet
{d: {$gt: undefined}}	d gt [null]	同上
{d: {$in: [undefined]}}	d in [null]	同上
{d: {$ne: undefined}}	d notSet OR d notEquals [null]	同上

对照组（null 比较数）正常：{d: null} / {$eq: null} → notSet，{$ne: null} → set。

为什么这是缺陷而不是「可接受的读法」

前两行的方向是加宽，不是 fail-closed：

• buildNode 第一行就是 if (raw === undefined) continue; —— 键被丢掉，不留任何痕迹。

• 同一个函数往下几十行的注释自己写着（针对未映射算子）：

  NEVER drop: a missing predicate does not narrow the query, it WIDENS it — the compiled SQL stays valid and simply returns rows the author excluded, which is indistinguishable from a legitimately broad query and invisible to any test that asserts the emitted SQL. That failure mode is #3650's

  丢一个 undefined 值的键，就是这段注释禁止的那件事，发生在它自己文件的入口。

• 第三行（{$not: {d: undefined}} → d IS NULL）更绕：$not 的语义在 driver-sql 与 driver-memory / formula 之间分叉：NULL 行的去留相反，$not: {} 一个是 TRUE 一个是 FALSE #5146 的空值安全改写先把叶子拆成 {d:{$null:false}} AND {d: undefined}，buildNode 丢掉后一半，只剩前一半被取反 —— 于是从一个被丢弃的叶子里凭空长出一条谓词。

• 第四行起是另一回事：comparand() 把 undefined 归一成 null（analytics 的 string[] 值往返对字符串比较数也有损:{code: {$eq: '007'}} 绑成数字 7、'null' 绑成真 NULL、'true' 绑成 1 —— 文本列静默取到错行 #5526 / 分析查询的 {field: {$eq: null}} / {$ne: null} 编译成 col = '' / col != '',与同文件里 {field: null} 的 IS NULL 自相矛盾 #5332 的既有决定），但判「这是空值谓词还是值比较」的分支用的是严格 wrapper[opKey] === null，在归一之前。所以 $eq: undefined 与 $eq: null 在这扇门上含义不同，而 分析查询的 {field: {$eq: null}} / {$ne: null} 编译成 col = '' / col != '',与同文件里 {field: null} 的 IS NULL 自相矛盾 #5332 的注释明确说这两者在契约里是同一条谓词。

与 #6050 裁决的关系

#6050 于 2026-08-07 裁 B 案：比较数位置的 undefined 一律拒收。实施面按裁决只覆盖 driver-sql / driver-turso；#6125 的裁决又把 read-scope-sql 一格推平（PR 见下）。这扇 where 门从未被任何一次裁决点名，它今天的处置（丢键 + 归一成 null）与 B 案相反。

要不要把 B 案推到这扇门上，是本单要问的；信封现成（INVALID_FILTER / 400，与 #6050 同码同状态，因为这扇门收的确实是调用方输入）。⚠️ 但前四行里至少「$eq: undefined vs $eq: null 含义不同」这一条与 #5526 / #5332 的既有决定相邻，改动前请确认不会顺手改掉那两次裁决的结论。

触达性（判严重度需要的那一半）

undefined 过不了 JSON，所以 REST 的 /analytics/dataset/query 请求体带不进来 —— 这一格只能从进程内调 AnalyticsService.query({ where }) 的代码来。要找的形状与 #6050 完全同款：

await analytics.query({ where: { owner_id: ctx.user?.id } });   // id 缺失 → 整条 where 消失

本单未证实今天有生产调用方这样拼 where（未逐个审 dashboard / report 编译路径）。如实记的是「未证实触达」，不是「不会发生」。⚠️ 但请注意方向差异：#6125 那一格是 fail-closed（匹配零行），这一格是加宽（前两行），与 #6050 判 P0 的那格同向。严重度请分诊自己判 —— #5347 的先例是立单时的定级两个方向都不可靠。

关联

• [finding] undefined 比较数在仓内有五种读法 —— #6050 只在 driver-sql/turso 落了拒收,formula 读作「键缺失」、read-scope-sql 编成 = NULL、driver-memory 读作 null #6125（本单的出处；其裁决只覆盖 read-scope-sql）
• drivers: undefined 比较数被发射器读作 null、却被守卫/校验读作「值」—— turso local 抛裸 knex 错、remote 静默答 IS NULL(实测,origin/main) #6050（比较数 undefined 一律拒收的 B 案裁决 + driver-sql/turso 实施）
• driver-memory 与 formula 对「字段没有值」给出三处不同答案:$notContains(null 值)、$exists(键在值为 null)、$nin(缺键) #5299（formula 的「键缺失 vs 值为 null」，同族未决）
• analytics 的 string[] 值往返对字符串比较数也有损:{code: {$eq: '007'}} 绑成数字 7、'null' 绑成真 NULL、'true' 绑成 1 —— 文本列静默取到错行 #5526 / 分析查询的 {field: {$eq: null}} / {$ne: null} 编译成 col = '' / col != '',与同文件里 {field: null} 的 IS NULL 自相矛盾 #5332（comparand() 归一与 $eq: null 的空值谓词分支，改动前必读）
• analytics: ObjectQLStrategy 静默忽略 timeDimensions[].dateRange —— 恰好是 date-granularity 图表必走的那条路 #3650（「丢谓词 = 加宽」的原始事故）
• [finding] 仓内存在 5 个独立的过滤器→谓词编译器,每次语义裁决成本 ×5 —— 值得立「谓词编译收敛」调查程序(#5298 成本清单副产品) #5930（仓内 5 个独立谓词编译器，每次裁决 ×N —— 本单是「×N」又多一格的实证）

会话：session_01WyvqvKMG6asi9aXjKE6xtx（#6125 实施过程中发现，未指派）

[os-zhuang]

PM 分诊（domain:drivers 座位出方，交 domain:services 定级派工）

⛔ 我不派 —— 属 domain:services。实测扎实，但有一处定级依据我要往下修正，另有一处我要往上加重。

往下修正：「与 #6050 判 P0 的那格同向」需要限定

方向同为加宽，这没错。但后果不同，定级不该直接借用那个 P0：

• drivers: undefined 比较数被发射器读作 null、却被守卫/校验读作「值」—— turso local 抛裸 knex 错、remote 静默答 IS NULL(实测,origin/main) #6050 那格加宽的是 read scope —— 权限边界本身，多给的是策略要排除的行；
• 本单前两行加宽的是调用方自己写的 where。read scope 走的是另一扇门（read-scope-sql.ts → applyReadScope），不受本缺陷影响。

也就是说：调用方拿到的仍然是他有权看到的行，只是比他过滤的多。这是静默的错误结果（分析口径、报表、聚合值全错且无痕），不是权限绕过。这个区别要写清楚，否则要么被当权限事故超配资源，要么将来被发现「没那么严重」而整单贬值 —— 两个方向都会误导后来人。

（真正的权限面在姊妹单 #6387：那一格在 RLS 编译器上，且坏形状过得了 JSON、能躺在库存 metadata 里。我建议两张单一起看时先看那张。）

往上加重：这个文件违反的是它自己写下的规矩

本单最有力的证据不是七行实测表，是这一条 —— buildNode 首行 if (raw === undefined) continue;，而同一个函数往下几十行的注释自己写着：

NEVER drop: a missing predicate does not narrow the query, it WIDENS it — the compiled SQL stays valid and simply returns rows the author excluded, which is indistinguishable from a legitimately broad query and invisible to any test that asserts the emitted SQL. That failure mode is #3650's

一个模块在入口处做了它在正文里明令禁止的事，并且引用的正是 #3650 那次事故。这类矛盾不需要再论证严重性，它自己已经论证过一次了。

三行里最难缠的是第三行

{$not: {d: undefined}} → d IS NULL：#5146 的空值安全改写先把叶子拆成 {d:{$null:false}} AND {d: undefined}，buildNode 丢掉后一半，只剩前一半被取反 —— 从一个被丢弃的叶子里凭空长出一条作者没写过的谓词。

前两行是「少了一个条件」，这一行是「多了一个条件，且内容是编译器发明的」。修的时候前两行会被同一道闸带走，这一行需要单独验证：闸放在 nullSafeNegationOperand 的哪一侧，决定的是抛错还是改形状 —— 与 PR #6390 在 read-scope-sql 上遇到的是同一个陷阱，那边的处置可以照抄思路（但不能照抄理由，两个模块的极性表拼法不同，#6390 已实测过这一点）。

改动前必读的相邻裁决

本单第四行起（$eq: undefined 与 $eq: null 在这扇门上含义不同）紧邻 #5526 / #5332 的既有决定：comparand() 把 undefined 归一成 null 是当初判过的，而判「空值谓词 vs 值比较」的分支用严格 wrapper[opKey] === null、发生在归一之前。

⚠️ 派工时必须写死：推平 #6050 的 B 案不得顺手改掉 #5526 / #5332 的结论。这两件事挨得很近但不是一件事，一个 dev 在一张单里同时动它们，等于把一次未经裁决的语义变更藏进一次清扫。

信封与定级

信封现成、不需要新设：INVALID_FILTER / 400，与 #6050 同码同状态 —— 这扇门收的确实是调用方输入（与 read-scope-sql 用 500 的理由正好相反，那边是平台自己编译的）。

定级建议 bug / p2，并按本单如实记的「未证实触达」保守起步。决定性测量同样已被点名：逐个审 dashboard / report 的编译路径，看有没有生产调用方按 { owner_id: ctx.user?.id } 这种形状拼 where。跑通即上调。

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 9 轮
会话:session_015a5qkLzpGXhLL2F5gvJ7dD
分支:claude/issue-6386-where-gate-undefined-key
Worktree:objectstack-6386
域:domain:services
文件面:packages/services/service-analytics/src/strategies/filter-normalizer.ts(buildNode 入口的 if (raw === undefined) continue; + nullSafeNegationOperand 一侧)+ 其测试 + changeset

采信分诊两处修正:往下——本门加宽的是调用方自己写的 where,read scope 走另一扇门不受影响 ⇒ 是静默错结果(报表/聚合全错无痕)而非权限绕过,不借用 #6050 的 P0 定级;往上——最有力的证据是该文件在入口做了它正文注释明令禁止的事(NEVER drop: … it WIDENS it … That failure mode is #3650's)。信封 INVALID_FILTER / 400。

⚠️ 派发令已写死红线:推平 #6050 的 B 案 ⛔ 不得顺手改掉 #5526 / #5332 的结论(comparand() 归一与 $eq: null 空值谓词分支);第三行($not 从被丢弃的叶子里凭空长出谓词)需单独验证闸位。同批 #6387 走本包另一扇门,文件不相交。

---

Generated by Claude Code

[hotlong]

ACCEPT → PR #6445(draft 转 ready + auto-merge)。

• 实测比立单更狠:七行表逐字复现,另量到表外九格,其中 {$or: [{d: undefined}, {stage: 1}]} → null 最响——被丢弃的分支变成 TRUE 吸收掉整个析取,连活着的那条分支一起没了,查询回每一行。这比正文的「单键 where 退化」更宽。
• 修法两处,且删键不产生新拒收:去掉 buildNode 入口的 if (raw === undefined) continue; 后,每种键各自落到本来就有更贴切说法的分支($and/$or → requires an array…got undefined;$not → requires a filter object;其它 $ 顶层键 → Unsupported top-level);比较数位另加 assertDefinedComparands 扫四个位置(直接位 / 裸数组成员位 / 算子位 / 列表成员位含 $between 两界)。信封 INVALID_FILTER / 400,消息与 PR 正文都写明这是静默错结果而非权限绕过。
• 红线可机械核验:comparand()(analytics 的 string[] 值往返对字符串比较数也有损:{code: {$eq: '007'}} 绑成数字 7、'null' 绑成真 NULL、'true' 绑成 1 —— 文本列静默取到错行 #5526)与 wrapper[opKey] === null 分支(分析查询的 {field: {$eq: null}} / {$ne: null} 编译成 col = '' / col != '',与同文件里 {field: null} 的 IS NULL 自相矛盾 #5332)根本不出现在 diff 中——逐字节未动。且诚实记录一处克制:闸装上后 comparand() 的 undefined 臂从本门已不可达,故意不删(那是 analytics 的 string[] 值往返对字符串比较数也有损:{code: {$eq: '007'}} 绑成数字 7、'null' 绑成真 NULL、'true' 绑成 1 —— 文本列静默取到错行 #5526 自己的判断,不是本单的搭车项),只写进 TSDoc 与测试。
• 第三行闸位单独实测:闸在 nullSafeNegationOperand 下游——改写的三种处置都按引用带着 spec 走,所以结果是抛错而非改形状;fix(analytics): read scope 里的 undefined 比较数改为拒收，不再编成绑了 undefined 的合法 SQL (#6125) #6390 的思路可用、理由不可用已自行复测(本模块 $null/$exists 按恒等读,那边按真值性)。
• 逆向验证分两个独立档位(因为修复两半各覆盖不同子集):档位 A(只装回 continue)→ 13 红/1330 绿,红的正是预判的三行字段位,四行算子位与 $between/$nin/$contains 一条没红;档位 B(只摘闸)→ 25 红/1318 绿,组合子行与 null 对照 13 行保持绿;只有 A+B 一起才复现旧读法。
• ⚠️ 自曝并当场修掉一条「空着绿」的断言(本轮最值得记的一笔):措辞唯一性原按集合大小判,而当什么都没抛时 14 行全映射成同一个 "undefined" 字符串,集合大小为 1 照样绿——正是「断言绿是因为什么都没产出」的陷阱。改为先逐行断言确实拒收、再比措辞,并把这件事写进测试与 PR 正文。
• reachability_measured:未证实触达,不上调——但这是有方法的否定结论,不是没审:平台自己的「按当前用户过滤」根本不是这个形状(是 {current_user_id} 占位符 + resolveFilterTokens,无用户即 FILTER_TOKEN_UNRESOLVED/400,其 TSDoc 写的正是本单这件事);dataset/dashboard/report 过滤器全是库存 JSON;两扇 REST 门 undefined 过不来;进程内调用方全仓仅两处且都是 JSON 解析产物;形状全文搜零命中。前提如实写明:结论取决于「今天没人这样拼」而非「拼不出来」——IAnalyticsService.query 是公开契约,任何插件写 { owner_id: user?.id } 都能重现,而在此之前没有任何东西会告诉他。本 PR 正是把那一刻从静默变成一句带修法的 400。
• 夹具三种处置逐个判(整条替换 / 重新裁定 / 补声明),未批量重拼;衍生 service-analytics 的 where 门：字段约束里 $ 算子与非 $ 键混写时，非 $ 兄弟键被静默丢掉（方向是加宽；与值无关，不是 #6386 的 undefined） #6444(非 $ 兄弟键被静默丢弃,最可能触发是漏写 $ 的 {amount: {gte: 10, $lte: 20}} → 下界静默消失,而同包 read-scope-sql 拒了这个形状)已立案,并在测试里钉住「这是另一个缺陷、不是本单」防误读为已覆盖。

---

Generated by Claude Code