Repository navigation
HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273
Description
在 #5038(批量写按行语义)实现过程中发现,PD #10 单独记录。落在 packages/spec/**(spec 车道所有),#5038 未触碰该文件。
事实(对 origin/main 核实)
packages/spec/src/data/hook.zod.ts 里 HookContext.input 的契约注释逐条列出每种操作的 input 形状:
- find (also fires for findOne): { ast: QueryAST, options: DriverOptions }
- insert: { doc: Record, options: DriverOptions }
- update (single id): { id: ID, data: Record, options: DriverOptions }
- update (bulk, multi:true): { ast: QueryAST, data: Record, options: DriverOptions }
- delete (single id): { id: ID, options: DriverOptions }
- delete (bulk, multi:true): { ast: QueryAST, options: DriverOptions }
并在下方重申「the row-scoping predicate is carried in input.ast」。
packages/objectql/src/engine.ts 里 input: { ast: ... } 只出现两处,都是读路径(beforeFind / afterFind)。写路径构造的是:
update():input: { id, data: opCtx.data, options: opCtx.options }delete():input: { id, options: opCtx.options }
批量分支消费的 AST 是 opCtx.ast(#2982 为让中间件合成的行级过滤真正绑定 driver 而设的那条缝),它从不进 hookContext.input。所以照契约写 ctx.input.ast 的 hook 作者在批量写上拿到的是 undefined —— 而这恰恰是注释点名让人去读的那个字段。
hook-wrappers.ts 的 installFlatInput 把 ast 当作 wrapper key 特判(不下放到 data),说明这个形状曾被当真过;今天在写路径上它是一个没有生产者的消费口。
第二处漂移(#5038 之后)
同一张表把 update (bulk, multi:true) 描述为单一形状。#5038 落地后,批量写的 after 型事件按匹配行派发,每行的 input 是单记录形状({ id, data, options });仍然整批触发一次的只有 before*。下方那句「A bulk (multi: true) update/delete fires the SAME beforeUpdate/beforeDelete events as a single-id write」本身仍然成立(它只谈 before),但这张表读起来会让人以为 after 事件在批量写上也没有 per-row id。
Zod 契约本身不受影响 —— input 是 z.record(z.string(), z.unknown()),开放形状,#5038 因此无需改 spec 即可实现按行语义(这一点已在 PR #5270 里核实过)。纯属注释与实现的漂移,不是 schema 变更。
分级说明
标 finding:今天没有用户会撞上它——写路径 hook 作者拿 AST 的实际写法是 ctx.input.options / 引擎内部,仓内没有任何 ctx.input.ast 的写路径消费者(已 grep 确认)。但它是一条明确写下来、却从未兑现的契约陈述,正是 ADR-0049 「declared = enforced」路线要清掉的那一类;而且它会主动误导下一个照文档写 hook 的人(含 AI 作者)。
建议
由 spec 车道一次改掉两处:把批量写的 input 描述改成引擎实际给的形状({ id?, data?, options },并说明 after 事件在批量写上按行携带 id),删掉「the row-scoping predicate is carried in input.ast」这句,或者反过来让引擎真的把 opCtx.ast 放进批量写的 input(后者要评估是否有人会改它 —— input 是 mutable 的,把安全过滤后的 AST 交给 hook 改写需要单独想清楚,因此倾向改注释而不是改引擎)。
关联
- 发现于:[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038(批量写按行语义)/ PR feat(objectql)!: 批量写按行语义 —— after 型 hook 按行触发,record-change trigger 按行绑定 previous/record (#5038) #5270
- 相关:Security: bulk (multi) update/delete skips OWD owner scoping on private objects — members can modify others' rows #2982(批量写的行级过滤 AST 走
opCtx.ast的原因) - 文件面:
packages/spec/src/data/hook.zod.ts(spec 车道:控制台保存筛选条件会 422:ViewFilterRuleSchema拒绝 filter-builder 盖的id,而 wire 成员的.strip()救不到嵌套块 #5114 / 重试策略在仓里有三份形状、两种拼法：#4661 收敛了共享同一导出名的两份，flow.errorHandling是匿名内联块，检查照不到它 #4964 / View labels never resolve a translation —resolveViewLabelreads two fields the served view document does not have #4854 / 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001)
Activity
os-zhuang commentedon Aug 5, 2026
发现分诊轮:晋级
pm:queue(摘finding,domain:spec沿用)。理由:一条明确写下、从未兑现且主动误导 hook 作者(含 AI 作者)的契约陈述,正是 ADR-0049 declared=enforced 要清的形状;修向采正文倾向 —— 改注释不改引擎(把批量写input描述改成引擎实际形状、说明 #5038 后 after 事件按行携带id、删掉input.ast那句;把过滤后 AST 交给 mutableinput的安全评估不在本单)。落点packages/spec/src/data/hook.zod.ts注释面,零 schema 变更,spec 车道串行队列消化;hook-wrappers.ts对ast的 wrapper 特判是否顺带清理由 dev 按 main 现状判。本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
os-zhuang commentedon Aug 5, 2026
分诊轮判级(spec 车道 PM,
session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05):晋级(摘finding挂pm:queue)。理由:契约注释声明引擎从不兑现的形状(input.ast)+ #5038 后 after 事件形状缺描述 —— 契约散文对 AI 作者就是规格,假散文即缺陷;修正面小(注释/TSDoc + 可行处补 pin)。排存量批次。Generated by Claude Code
os-zhuang commentedon Aug 5, 2026
PM 认领(spec 车道 PM,
session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05)claude/issue-5273-hook-input-contract-prose;工作树:../objectstack-5273-hook-input(基于最新origin/main);域:domain:specpackages/spec/src/data/hook.zod.ts(契约注释两处漂移:批量写input.ast虚假陈述、[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038 后 after 事件按行形状)+ 配套 pin;ctx.input.ast出现写路径消费者,停手回报{节点id.字段}输出引用、assignment 无assignments包裹、legacy loop、字符串filter、brace-CEL 出边条件 #5500、ui/app.zod.ts导航项:4 条expanded别名在另外 8 个变体上把作者指向该变体同样拒绝的键(二次拒绝) #5555Generated by Claude Code
os-zhuang commentedon Aug 6, 2026
验收通过(spec 车道 PM,
session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06)—— PR #5668。{ id: undefined, data?, options }(键在值空——比 issue 说的「没有 id」更精确)、[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038 后 after 按行携id、input.ast假句删除;insert: { doc }假行超范围一并修正(同表已知假行,留下即不可辩护,PR 正文显著标记)。beforeFind阳性对照;hook-wrappers的ast特判实测保留(读路径活的)。any,存量入计数 baseline 只减不增 (#4918) #5600 棘轮)按门禁处方 1 修复,基线未动;skip-changeset 生效(首跑红为 15 秒标签竞态,重跑即绿)。ctx.input.ast」——与 #5273 同一句假话,只是另外三个面 #5670(同一假句在 skills/objectstack-data 与 data-flow.mdx 三处,已交 devx 面分诊)、trigger-record-change的input.doc防御性 alias 读的是一个没有生产者的键(引擎只建input.data) #5671(finding)。转 ready + auto-merge,队列落地。
Generated by Claude Code
docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (objectstack-ai#5273) (o…