[finding][drivers] `DriverQuery` 收窄之外：`aggregate` / `distinct` / `analyzeQuery` 等驱动自有查询方法仍要求把对象名写两遍

[os-zhuang]

在 #6075（PR #6210）把五个驱动的六个契约方法签名迁到 DriverQuery 时实测发现，记录备查。观察类，不挂 pm:queue，请分诊轮定级。

现状

#5181 只收窄了 IDataDriver 声明的六个方法（find / findOne / count / updateMany / deleteMany / explain），#6075 让五个驱动的实现跟上。但驱动上还有一批同样吃 query AST、却不在 IDataDriver 里的方法，它们的第一个实参同样已经是对象名，query 里却仍然要求（或放任）再写一遍 object：

位置	签名	形态
driver-memory/src/memory-driver.ts:653	aggregate(object, pipeline: Record< string, any >[] | QueryAST, …)	要求 object
driver-memory/src/memory-driver.ts:612	distinct(object, field, query?: QueryInput)	要求 object
driver-mongodb/src/mongodb-driver.ts:468	aggregate(object, query: QueryAST, …)	要求 object
driver-sql/src/sql-driver.ts:3249	aggregate(object, query: any, …)	any，全无检查
driver-sql/src/sql-driver.ts:3372	findWithWindowFunctions(object, query: any, …)	any
driver-sql/src/sql-driver.ts:3409	analyzeQuery(object, query: any, …)	any
driver-turso/src/turso-driver.ts:547	aggregate(object, query: any, …)	any

（行号取自 origin/main @ 80f7dc6，会漂。）

为什么单独记一笔

这正是 #5181 判定为「同一个事实要求写两遍，因此有了两处互相矛盾的余地」的那种冗余，只是它活在契约没有覆盖的方法上。两个后果：

1. 要求 object 的那几处：调用方手上只有 where / groupBy 时叫不出类型的名字，于是走 as any —— [spec] IDataDriver 的 query 参数要求 QueryAST.object 与第一实参重复 —— 下游被迫 as any(20 处实测),提议 Omit/optional 化 #5181 的 changeset 记过这笔账的代价（cloud#1053 实测 20 处，cloud#1030 的 $like 就是从这个口子活到运行时的）。
2. 写成 any 的那几处：连 where / orderBy / fields 的检查一起关掉，与 [finding][drivers] 五个驱动的 find/count/… 仍声明 query: QueryAST，而调用方已可省略 object —— 双变让它编译，但声明开始说谎 #6075 刚在 turso 上收回来的是同一批检查。

PR #6210 没有动它们：它们不是 #5181 收窄的那六个方法，顺手改属于超范围。

不是缺陷，别当缺陷派

今天没有人踩：git grep 'query\.object' -- 'packages/drivers/*/src' 在 main 上仍是零命中，这几个方法自己也不读 query.object。所以这是休眠的冗余 + 放弃的检查，不是活体缺陷，判级请按观察类走。

如果要做

给这批方法定一个 query 参数类型。要注意它们彼此并不同形，不是一刀切换成 DriverQuery 就完：

• memory.aggregate 的形参是 pipeline，联合了 mongo 风格管线数组与 AST 两种输入，收窄前得先确认两条分支各自的真实生产者；
• memory.distinct 用的是输入形 QueryInput（不是输出形 QueryAST），直接换成 DriverQuery 会连带收紧 groupBy 的元素类型 —— PR refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210 在 performAggregation 上就是因为这一点选了 Omit< QueryInput, 'object' > 而不是 DriverQuery；
• analyzeQuery / findWithWindowFunctions 是否还有生产者，值得先量一量再决定是收窄还是退役（explain 已经只是 analyzeQuery 的一层转发）。

⚠️ 另注：driver-memory / driver-mongodb 在 #5499 的冻结面内，跨面处置请按冻结令的口径框定范围。

会话：session_01WyvqvKMG6asi9aXjKE6xtx（#6075 实施期间发现，未认领）

[os-zhuang]

测量棒交付(只读调查,基线 d367f03d6,仓内零改动;PM 复核收下)。

对本单正文的三处更正(实测)

1. 清单漏了一个:sql-driver.ts:3481 distinct(object, field, filters?: any) 也是 any ⇒ 实为 8 个方法(算 turso 两层则 10 个);行号已漂(sql 三处 → 3384 / 3507 / 3544)。
2. performAggregation 选 Omit<QueryInput,'object'> 的归因错了:正文说是 groupBy 元素类型差异 —— 实测 QueryInput 与 QueryAST 在 groupBy 上逐字相同,差异只在 search/orderBy/expand;且直接换 DriverQuery 零报错。不影响 refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210 的正确性(它做的是最小改动),但影响本单:那不是被迫的选择,契约优先应选 DriverQuery。
3. explain 核实:它本身已经是 DriverQuery,只是 analyzeQuery 的一层转发。

生产者实测

aggregate 仅 3 个活体生产者;distinct / analyzeQuery / findWithWindowFunctions 非测试生产者为零;IDataDriver.explain 全仓唯一引用是一条只验存在性的幽灵断言。

三个门禁盲区(实施必须带上)

• erasure 棘轮是双向的:aggregate 在监视方法集内,全仓 49 处 .aggregate(… as any),收窄后删掉这些 as any 会让 267 下跌 ⇒ 同一 PR 内必须 --update 提交 baseline;⛔ 绝不能新增 as any 消红;
• mongodb 的 tsconfig 排除测试(TEST_DEBT 43)⇒ 必须全仓 check:type-check-debt re-measure(refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210 在 plugin-auth 上的同一课);
• driver-sqlite-wasm 读的是 driver-sql 的 dist/*.d.ts ⇒ 只改源码不重建 d.ts 是假绿,实测重建后立刻 12 条。派发必须点名把它进同批文件面。

PM 裁决(第三档,带否决窗口)

问题 1 —— findWithWindowFunctions 的类型:采纳 B(在 driver-sql 本地声明扁平形)。 它既不能退役(#4286 把它写成了已发布的迁移处方,指向它的有墓碑消息 + registry + 5 个 docs 页 + release notes + upgrade guide),也不能标 DriverQuery(windowFunctions 是 retiredKey 墓碑 ⇒ 两个候选类型上都是 undefined,该门自己文档里的载荷会编译不过)。B 把类型留在能力真正所属的那一层、契约面零扩张,与 #4286「spec 不描述驱动私有形状」同向,且可逆。⚠️ 选项 D(退役它并撤回 #4286 的迁移处方)仍然摆在桌上——那要改 6 处已发布文档,是维护者的取舍,不是我的;本裁决只是先把丢掉的检查拿回来,不预断 D。

问题 2 —— 批 C 的冻结面归属:适用已有先例,按冻结面外的类型维护处理。 这与我在 #6075 认领评论里裁的口径是同一条(纯类型注解、零 emit 差异、零行为 ⇒ 不属 #5499 冻的「缺陷修复与语义补齐的开发投入」),而 #6210 已按该口径在同一批驱动上做过一次并合并。硬约束不变:冻结面只许改签名类型,任何需要动逻辑才能收紧的一律停手报告。

批次派发

批	内容	处置
A+E	analyzeQuery → DriverQuery(实测零报错)+ findWithWindowFunctions 按裁决 B 本地类型	现在派(同文件相邻区,合一单)
C	memory + mongodb 纯类型注解	现在派(独立文件面)
B	aggregate(sql+turso)+ 别名退役前置	等 #6203(PR #6312)合并后派——同函数体撞面;顺序必须是 ①重拼 fixture ②删 aggregate/func 别名 ③再收窄
D	distinct 跨驱动语义分叉	另立单(是缺陷不是冗余,见下)
F	verify 的 BucketableDriver 替身	并入 A+E 的 PR 或另立,PM 选后者

本单作为清单锚点保持 open,各批落地后勾销。

---

Generated by Claude Code

[os-zhuang]

批 B 派发(前置 #6203/PR #6312 已 MERGED,同函数体撞面解除)

会话:session_01WyvqvKMG6asi9aXjKE6xtx
分支:claude/issue-6212-batch-b-aggregate-signatures
Worktree:objectstack-issue-6212-b
文件面:driver-sql/src/sql-driver.ts(:3384/:3439/:3442 区)+ driver-turso/src/turso-driver.ts(:548)+ driver-turso/src/remote-transport.ts(:820-837 区)+ 四个 fixture(sql-driver-advanced / sql-driver-queryast / sqlite-wasm-driver-advanced / sqlite-wasm-driver-queryast)+ driver-sqlite-wasm 必须进验证面(它读 driver-sql 的 dist/*.d.ts,只改源码是假绿)+ changeset

硬性顺序(倒过来会拿到一堆解释不清的红):① 重拼 fixture 到已声明拼写(aggregate:→aggregations:、func:→function:)→ ② 删 query.aggregate / agg.func 两个未声明别名分支(记账单 #6321,ADR-0049:重拼后生产者归零)→ ③ 才收窄签名。

已知的一处行为改动(测量棒实测,非纯类型):remote-transport.ts:826 的 const groupBy: string[] = … query.groupBy 假定 groupBy 只有字符串形,而 spec 的 GroupByNode 是联合;今天不炸是因为 turso remote 模式把 queryDateGranularity 声明为空表、引擎因此不下推结构化 groupBy。收窄会把这个「靠能力位守着的类型假设」摆上台面 ⇒ 必须显式处置(运行期收窄或显式拒收)并在 PR 说明,或把 turso 半边拆出单排,⛔ 不许用 as any 抹掉。

并行:批 A+E、批 C 在飞,文件面互不相交。

---

Generated by Claude Code

[os-zhuang]

批 A+E(+F)复核:ACCEPT → PR #6355(PM 实测复核):

• 变更面 5 文件;边界零触碰实测确认(aggregate / memory / mongodb / packages/spec 全部不在 diff);
• 裁决 B 执行到位,且比派发词更准:类型写成 Omit<DriverQuery,'windowFunctions'> & {…} 而非直接交集——理由是墓碑键 undefined 与数组求交会让属性变成不可写、载荷静默编译不过且报错点离声明十万八千里。并给这个坑本身加了 pin(谁把 Omit 「简化」掉,红在测试里而不是红在文档里)——这是把一次性判断固化成守卫,做法对;
• 验收标准做成了 pin 而非口头承诺:文档载荷逐字抄自 queries.mdx 编进类型断言;同时证明请求面墓碑没被重新打开(analyzeQuery 传 windowFunctions 仍是编译错误);
• 反向验证覆盖了那个门禁盲区本身:在 driver-sqlite-wasm 上做(而非 driver-sql),红出来即证明它读到的是重建后的 dist/*.d.ts、不是假绿——这比单纯「记得 build」强一档;
• 顺带发现的类型学事实值得留档:DropsObject<any> 解析为 never(因 'object' extends keyof any 为真)⇒ 一条 pin 同时挡住「把 object 加回来」和「把参数放宽回 any」两种回退;
• 批 F 判定合理(9 行、删逃逸口而非新增、verify 全绿),且明确声明不预断批 B(方法参数双变,驱动侧声明什么都满足该替身);
• 三道门禁:erasure 267 未动(合并前后各跑一次 + baseline key set 核对)、type-check-debt 34 条无超记录、driver-sqlite-wasm 点名进验证面;13 个依赖包 grep 三个符号零命中;
• changeset major 依据与 [spec] IDataDriver 的 query 参数要求 QueryAST.object 与第一实参重复 —— 下游被迫 as any(20 处实测),提议 Omit/optional 化 #5181/[finding][drivers] 五个驱动的 find/count/… 仍声明 query: QueryAST，而调用方已可省略 object —— 双变让它编译，但声明开始说谎 #6075 一致。

顺带新账 #6354(checkDateBucketParity 的每个调用点都写 driver as never,把结构替身的意义整个抹掉;实测该 cast 并不必要)——观察类,已另立。

CI 清零后 ready + auto-merge。批 A / E / F 就此勾销,#6212 余 B(在飞)、C(在飞)、D(已独立为 #6320)。

---

Generated by Claude Code

[os-zhuang]

✅ ACCEPT — 批 C（PR #6356）

memory / mongodb 的 aggregate / distinct 收进 DriverQuery。已逐项实证复核，接受。

复核结论

改动面：8 文件（changeset、memory×2、mongodb×2、新增 memory-driver-query-narrowing.test.ts、check-type-check-coverage.mjs、query-options-erasure-baseline.json）。逐行看过非测试源码改动，确为纯签名置换 + 无用 import 删除，无一处逻辑改动 —— #5499 冻结面口径成立（与 #6210 在同一批驱动上的既有口径一致）。刻意保留 'Aggregate operation (QueryAST)' 这条运行期日志文案是对的：改它就不再是零行为变化。

本 PR 最值得记下的一条：那个 ratchet 不是记账

把 mongodb 的 TEST_DEBT 从 43 降到 10，读起来像顺手清理旧漂移，实际是本 PR 唯一能钉住自己的东西：

• mongodb 的 tsconfig.json 排除 *.test.ts，而被收窄方法的唯一消费者就是它自己的测试 —— per-package typecheck 与全仓 tsc 都看不见这次收窄（PR 里如实预判为绿并实测为绿，exit 0 零输出）；
• 所以能看见它的只剩 ledger re-measure。而旧天花板 43 的余量会把它整个吞掉：实测把 aggregate 签名改回 QueryAST 得 12 条，12 < 43，门禁不会红；
• 降到 10 之后，同一反转实测报 records 10 … now reports 12 (+2) —— 门禁这才真的红。

归因也已坐实而非声称：在 d367f03d6^（#6210 前一刻）实测正好 43 = TS2345×33 + 现存 10，与旧 note 逐字吻合；那 33 条是 #6210 消掉的，与本 PR 无关（本分支与 pristine tree 在 2bc187641 上同报 10）。先证明归属，再动棘轮，顺序正确。

两处判断做对了

pin 挂在真实调用上，不挂类型字面量。 const x: DriverQuery = … 这种形状在签名回退后依旧是绿的（DriverQuery 本来就没有 object）—— 那正是 #5018 / #4984 付过学费的死 pin。该包 tsconfig 不排除测试层、无 TEST_DEBT 条目，所以这些 @ts-expect-error 是真检查。

mongodb 侧刻意不写同形 pin。 那里的测试不在任何 tsc program 里，写了就是 AGENTS.md PINS_CHECKED 点名的幽灵检查 —— 宁可承认它的钉子只有上面那条 ratchet，也不摆一个看着像证据的空壳。这个"不做"比多做一份更有价值。

门禁

• check:query-options-erasure：4 处 as any（memory 2 + mongodb 2）因收窄成为多余而删除，测试面 267 → 263，按规矩 --update 提交 baseline，diff 恰好一行。⛔ 全程零新增 as any —— 棘轮向下走，方向对。
• check:type-check-debt：全仓 34 entries re-measured, none above its recorded number。
• 冻结面回归：driver-memory 532 passed / driver-mongodb 206 passed。mongodb 那 137 条 skipped 需真实 mongod（driver-mongodb 测试:两个套件并发下载 MongoDB 二进制,mongodb-memory-server 的 rename 竞态让全绿测试 exit 1(队列 flaky) #5517 起 opt-in），PR 已如实标注"两处 as any 的删除是类型层证据、不是运行期证据" —— 该说的短板说了。

证伪本单正文一处归因（第二次独立确认）

本单正文称 performAggregation 当初取 Omit<QueryInput,'object'> 是被 groupBy 元素类型差异逼的。不成立：QueryInput 与 QueryAST 在 groupBy 上逐字相同，差异只在 search / orderBy / expand。这与我此前测量棒的结论一致，现由实现侧独立复现。本单正文的这条归因作废 —— 那不是被迫的选择，DriverQuery 一直可用。

CI 上那次红与本 PR 无关

TypeScript Type Check 曾红在 ui/BulkActionDef:requiredPermissions 上 —— 本 PR 一行 packages/spec 都没碰。已查明是 CI 配置缺陷：lint.yml 的 typecheck job 没有 fetch-depth: 0，authorable-surface 删除门走不到 merge base、退化到拿 main 的 tip 当锚点，于是把 main 新增的键（#6332，本日刚合入）误判成分支删除的键。已另立 #6359 记录（含一行修法），本 PR 已 update branch 重跑。

---

批 C 结清。剩余：批 B 在飞（aggregate sql+turso），#6320 / #6188 待分诊。

---

Generated by Claude Code