hooks 技能与 API 文档仍在教「批量写的行级谓词在 `ctx.input.ast`」——与 #5273 同一句假话,只是另外三个面

[os-zhuang]

在 #5273(PR #5668)修 packages/spec/src/data/hook.zod.ts 的契约注释时发现,PD #10 单独记录。同一条从未兑现的陈述还活在另外三个面上,#5273 的文件面不含它们,故未在那个 PR 里动。

事实(对 origin/main 核实)

packages/objectql/src/engine.ts 全仓只有 5 处 HookContext 生产点,input: { ast } 只出现在两条读路径(4640 / 4773,分别喂 driver.find / findOne)。写路径构造的是 { id, data, options }(5243)与 { id, options }(5705);批量写的行级谓词走引擎内部的 OperationContext.ast(#2982),从不进 hookContext.input。

以下三处仍照旧宣称它在 ctx.input.ast:

1. skills/objectstack-data/rules/hooks.md:116 —— 「the write events fire on bulk multi:true operations as well — the row-scoping predicate is in ctx.input.ast」
2. skills/objectstack-data/references/data-hooks.md:61-62 —— 「the write events fire on bulk multi:true operations (the row-scoping predicate is in ctx.input.ast)」
3. content/docs/api/data-flow.mdx:313 —— 「Bulk writes (multi: true) fire the same … events as single-id writes, with the row-scoping predicate in ctx.input.ast.」

三处都只是顺带提到 input.ast,主句(「批量写触发同名事件、没有 *Many 事件」)本身仍然成立——和 #5273 里那句的结构一模一样。

另外这三处也都没有描述 #5038 之后的按行形状:批量写的 after* 按匹配行派发,每行是单记录形状、input.id 是绑定的。

为什么单独提而不是搭 #5273 的车

#5273 经分诊确定的文件面就是 spec 那一个注释块;skills/** 与 content/docs/** 是另一条车道,同批可能有别的 agent 在改,不搭车以免撞面。

为什么不只是「文档小事」

skills/objectstack-data/ 是 AI 作者写 hook 时实际读的那份规格。照它写出来的 ctx.input.ast 在批量写上恒为 undefined,而这正是文档点名让人去读的字段——#5273 分诊轮的原话是「契约散文对 AI 作者就是规格,假散文即缺陷」。严重程度请分诊轮判,我按发现原样提交。

建议

按 #5273 已落地的措辞对齐三处:删掉 ctx.input.ast 那半句,补一句「批量写不向 hook 暴露谓词;after* 按行派发、input.id 在那里绑定」。真值可直接引 PR #5668 新增的 packages/objectql/src/hook-input-shape-contract.test.ts。

⚠️ content/docs/releases/v16.mdx:185 也带这句,但 releases 是发布态记录,按 CLAUDE.md 不在代码 PR 里改,这里不列为待办。

关联

• 同源:HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 / PR docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668(spec 侧那份已修)
• 相关:[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038(批量写按行语义)、Security: bulk (multi) update/delete skips OWD owner scoping on private objects — members can modify others' rows #2982(谓词走 opCtx.ast 的原因)

Blocked-by: #5273

[os-zhuang]

分诊:入队(pm:queue)+ domain:devx + 暂阻塞(pm:blocked,Blocked-by: #5273,已补正文)。

• 落点锚定:三处文件面已逐条核 origin/main 仍在——skills/objectstack-data/rules/hooks.md:116、skills/objectstack-data/references/data-hooks.md:62、content/docs/api/data-flow.mdx:313。skills/** 与 content/docs/** 归 devx 车道(域表)。
• 为什么阻塞:PR docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668(HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 的 spec 侧修复)仍是 open draft。本单的建议措辞要与其落地版对齐,且真值引用指向该 PR 新增的 hook-input-shape-contract.test.ts——上游未合前动手会对着一个还在变的文本对齐。HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 落地即解锁,届时是纯文档对齐的机械活。
• 查重:三仓仅 HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 同源(spec 侧那份,文件面不相交),无重复。releases 页面(v16.mdx:185)按 CLAUDE.md 纪律不入本单待办,issue 正文已自行排除,认可。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

Claim(PM devx 车道):本单由本 PM 会话派发实现。

• Session:session_01GX3sL71LFq8m2usg6VqTSE
• 分支:claude/issue-5670-bulk-ast-doc-align
• 解锁确认:Blocked-by HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 已 closed-completed(PR docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668 落地,真值测试 packages/objectql/src/hook-input-shape-contract.test.ts 在 main),阻塞解除。
• 派发面:仅 skills/objectstack-data/rules/hooks.md、skills/objectstack-data/references/data-hooks.md、content/docs/api/data-flow.mdx 三处;⛔ content/docs/releases/** 不动(issue 已自行排除,认可)。

---

Generated by Claude Code