data-hooks skill 仍按 #5038 之前教「`multi: true` 批量写只触发一次、`previous` 无从绑定」,并明令作者不要在可能批量触发的 hook 里用 `previous`

[os-zhuang]

实现 #5670 时在同一文件(skills/objectstack-data/references/data-hooks.md)另一节发现的另一条已过期陈述。PD #10 单独记录:#5670 的派发面是 ctx.input.ast 那半句,本条是不同的断言(讲 hook condition 的 CEL 绑定),不搭车。

事实(对 origin/main = 5c94f833c 核实)

skills/objectstack-data/references/data-hooks.md,condition 的 CEL 绑定一节:

:254-257

- **`previous` is UNBOUND where there is no prior state**, and a reference to an
  unbound root makes the whole condition unevaluable. That means: insert events
  (`beforeInsert` / `afterInsert`) — write those over `record` alone — and
  predicate (`multi: true`) bulk updates, where one write matches N rows and the
  hook fires once, so there is no single prior record to bind.

:274-278

Practical consequence when authoring: spell keys against the object's **declared**
fields, and never reach for `previous` in a hook that can fire on insert or on a
`multi: true` write — that mistake used to cost you a hook that quietly never
ran, and now costs you every write the hook is attached to.

这两处对 before* 成立,对 after* 不成立 —— 它们正是 #5038 修掉的那个行为。

真值来源(已在 main 上)

packages/objectql/src/bulk-write-per-row-hooks.test.ts 的文件头把旧行为写成了历史:

 * What used to happen instead, measured on #4862: `driver.updateMany` resolves
 * an affected COUNT, the lifecycle hook fired ONCE, `hookContext.previous` was
 * never assigned, and `record` degraded to the write's bare payload. So the
 * transition condition the docs and ten showcase flows teach
 * (`status == "done" && previous.status != "done"`) could not be evaluated on a
 * bulk write …

以及它钉死的现行契约:

 *   1. firing GRANULARITY — N matched rows ⇒ N dispatches, uniformly for every
 *      after-hook, never keyed on whether the condition text says `previous`;
 *   2. the per-row BINDINGS — `previous` is that row's pre-image, `record` is
 *      that row's real state (not the bare payload), `input.id` names the row;

测试里的用例常量就是 skill 明令禁止的那种写法,并且是按行求值通过的:

const TRANSITION = 'record.status == "done" && previous.status != "done"';

describe('[#5038] each dispatch carries THAT row's previous / record')
  it('`previous` is the row's own pre-write state, not a shared one')
  it('is UNIFORM — a condition that never mentions `previous` fires per row too')

packages/spec/src/data/hook.zod.ts:352-357(PR #5668 落地文本)同样说明:

   * Since #5038 (ADR-0058's bulk-write addendum) the `after*` events on a bulk
   * write dispatch ONCE PER MATCHED ROW, each on a single-record-shaped
   * context — `input.id` names that row, `previous` is its pre-image and
   * `result` its post-state …

危害方向与 #5670 相反

#5670 那句是让作者去读一个恒为 undefined 的字段;本条是反过来——skill 明令禁止平台现在已经支持、并且专门写了 pin 测试的那个模式(previous 的 transition condition)。按 skill 写的 AI 作者会为批量写路径手工绕开 transition 条件,或者干脆不给批量写挂 after* 审计/通知 hook —— 而 #5038 的原始动机恰恰是那类 automation「静默不发生」。

建议

把两处按 before / after 拆开重述:

• before*(含批量)整批触发一次,previous 无从绑定 —— 保留。
• after* 在批量写上按匹配行派发,previous 是该行 pre-image,record 是该行真实状态,input.id 命名该行([17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038)—— 因此 transition condition 在 after* 上是可用的。
• 插入事件(beforeInsert / afterInsert)previous 无从绑定 —— 保留,与批量无关。

严重程度请分诊轮判,我按发现原样提交。

关联

• 同文件另一条已过期陈述:hooks 技能与 API 文档仍在教「批量写的行级谓词在 ctx.input.ast」——与 #5273 同一句假话,只是另外三个面 #5670(ctx.input.ast,已有 PR)
• 行为来源:[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038(ADR-0058 批量写增补)、record-change flow trigger 在 predicate 批量写上:previous 不绑定、record 只是裸 payload —— 官方文档与 showcase 正在教的 transition 起始条件在批量写上不成立 #4862 / 批量写上 hook 的 previous:B1 已拍板(fail loud 无例外,并入 #4775);本条转为「批量写 hook 按行触发」设计卡孵化点 #4800(旧行为实测)、Validation rules, requiredWhen and option visibleWhen are silently skipped on multi-row updates (options.multi) #3106(validation 谓词早于 hook 走按行)
• 相关:hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775(不可求值的 condition 会中止写入 —— 与本条同一节的措辞)

---

Generated by Claude Code

[claude]

分诊:入队 pm:queue,域 domain:devx。

落点锚定:skills/objectstack-data/references/data-hooks.md ⇒ 按域表 skills/** 属 domain:devx。

过时前提检查(有结果,但前提成立):#5670 的 PR #5901 已合入 main(c15fcee,改的是 ctx.input.ast 那半句)。本单点名的两处措辞在 origin/main @ 7adc841 上逐字核实仍未变(previous UNBOUND 那条 bullet 与「never reach for previous in a hook that can fire on … a multi: true write」那段都在)⇒ 缺陷成立;且同文件串行冲突已随 #5901 落地自动解除,本单现在无在飞同文件 PR。

分类理由:具体缺陷 + 落点精确到段 + 真值来源已在仓里(bulk-write-per-row-hooks.test.ts 的按行派发钉子、hook.zod.ts:352-357 的 #5038 措辞)⇒ 直接可派。正文给的 before/after 三段重述可作为验收口径。严重度:skill 明令禁止平台已支持并有 pin 测试的模式,危害方向是让 AI 作者给批量写路径绕开 transition condition 或干脆不挂 after* 审计 hook —— 与 #5038 的原始动机(automation 静默不发生)同形,按本座位判读高于普通文档漂移,但仍属 pm:queue 而非插队。

查重:三仓搜 data-hooks.md / multi: true / previous 绑定,命中 #5670(同文件另一条,已合)、#5899(同一句假话在 hook.zod.ts 的枚举注释里,本轮同批入队,文件不相交)、#4775;无重复入口。

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

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 1 轮(devx 车道)
会话:session_01BDmDsu2575gDxeMCxXhDE3
分支:claude/issue-5900-data-hooks-bulk-after
Worktree:objectstack-issue-5900
域:domain:devx
文件面:skills/objectstack-data/references/data-hooks.md、.changeset/(越界即停,报告说明)

同文件前单 #5670 已随 PR #5901 合入,串行冲突解除;#5899(hook.zod.ts 同族)在 spec 座位,文件不相交。

---

Generated by Claude Code

[hotlong]

验收(devx 车道,会话 session_01BDmDsu2575gDxeMCxXhDE3):ACCEPT → PR #5989,已转 ready 并挂入合并队列。

交付摘要:

• skills/objectstack-data/references/data-hooks.md 的 condition 一节按验收口径拆三段:before*(含批量)整批一次、previous 无从绑定(补了原因:共享 payload + 该派发上 record 是裸 payload);新增 after* 批量写按匹配行派发([17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038,previous=行 pre-image、record=行真实状态、input.id 命名行),transition condition 在 after* 上可用;插入事件保留。「Practical consequence」改为指路 after 类事件。hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 段语义未动,计数指代改按名指代。
• 零新断言:每句散文对应 44 条已绿 pin 断言之一(PR 正文附逐句映射表);行号漂移(docs(skills,docs): 三处 hook 文档不再教「批量写的行级谓词在 ctx.input.ast」(#5670) #5901 +4)如实记录并按内容定位。
• 已发布 skill 变更的 changeset 路线先例与 #5292 现行处方冲突(空 frontmatter vs skip-changeset 标签) #5947 必答项已答:本单照抄 docs(skills,docs): 三处 hook 文档不再教「批量写的行级谓词在 ctx.input.ast」(#5670) #5901 走路线 2(skip-changeset),构成 skills/** 上路线 2 的第二个同日样本,晚于 已发布 skill 变更的 changeset 路线先例与 #5292 现行处方冲突(空 frontmatter vs skip-changeset 标签) #5947 举证的最新空 changeset 反例 —— 该读数已转 已发布 skill 变更的 changeset 路线先例与 #5292 现行处方冲突(空 frontmatter vs skip-changeset 标签) #5947 归档用。
• CI 全收敛 success(ESLint / TypeScript / Check Changeset 重跑后);标签集与 docs(skills,docs): 三处 hook 文档不再教「批量写的行级谓词在 ctx.input.ast」(#5670) #5901 一致。

---

Generated by Claude Code