docs(skills,docs): 三处 hook 文档不再教「批量写的行级谓词在 ctx.input.ast」(#5670)

[os-zhuang]

Closes #5670

纯散文对齐:三处文档/技能面仍在教「批量写的行级谓词在 ctx.input.ast」,按 #5273 / PR #5668 已落地的措辞逐处改正。不动引擎、不动 spec、不动 releases。

前提核实(对 origin/main = 5c94f833c)

issue 的断言	结果
三处文件面仍在 main 上带这句	✅ 成立(行号有漂移,按内容定位:rules/hooks.md:115-116、references/data-hooks.md:61-62、data-flow.mdx:313)
写路径 input 是 { id, data, options } / { id, options }	✅ engine.ts:5243 / 5705
input: { ast } 只出现在两条读路径	✅ engine.ts:4776 / 4909,分别喂 driver.find / findOne(行号相对 issue 正文有漂移)
批量写谓词走 OperationContext.ast(#2982),不进 hookContext.input	✅ pin 测试三条断言,详见下
#5038 后批量写 after* 按行派发、input.id 绑定	✅ pin 测试两条断言
主句(批量写触发同名事件、没有 *Many 事件)仍成立	✅ 保留原样
content/docs/releases/v16.mdx:185 带同句但排除在外	✅ 未动
全仓 docs/skills 只有这三处	✅ grep -rn 'input\.ast' content/ skills/ docs/ examples/ apps/ 恰好四条命中,第四条是被排除的 releases 页

无断言被证伪。 唯一偏差是行号漂移,已按内容搜索定位。

改了什么

三处删掉「the row-scoping predicate is in ctx.input.ast」半句,替换为同一套措辞的两句实情:

1. 批量写不向 hook 暴露行级谓词 —— 它在引擎内部 OperationContext.ast(Security: bulk (multi) update/delete skips OWD owner scoping on private objects — members can modify others' rows #2982),composed 的 RLS / sharing 过滤器由此绑定 driver 调用本身,handler 无法放宽;要限定批量,就在调用方用 options.where。
2. after* 改为按匹配行派发,每行是单记录形状,input.id 在那里绑定([17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038)。

措辞取自 PR #5668 落在 packages/spec/src/data/hook.zod.ts:340-357 的那段(「NOT reachable from input at all … scope the batch through options.where at the CALLER … dispatch ONCE PER MATCHED ROW」),不自行发明。

两处刻意的局部差异

• issue 编号:skills/objectstack-data/ 两份文件本来就带编号引用(data-hooks.md 12 处、rules/hooks.md 2 处),故补 (#2982) / (#5038);content/docs/api/data-flow.mdx 全文零 issue 引用,那处按其本地惯例不引编号。
• 不写仓内测试路径:issue 建议「真值可直接引 hook-input-shape-contract.test.ts」。三份文件现有引用里没有任何一条指向仓内 packages/** 路径,且 skill 经 npx skills add 装到第三方项目后那种路径并不存在 —— 真值引用因此放在本 PR 正文,而不是写进发布给客户的文本。

验证 —— 反向验证方向说明(重要)

本单没有可 revert 的代码,所以模板里「恢复删掉的分支 → 新测试转红」那条对它不适用;照那个形状伪造一段证据比留空更糟。这里的真值验证是另一条:我写进文档的每一句,都对应 PR #5668 已在 main 上的 pin 测试的一条绿断言。全文实测:

✓ [#5273] a bulk write carries no `ast` on `input` > POSITIVE CONTROL — a read DOES carry `input.ast`
✓ [#5273] a bulk write carries no `ast` on `input` > `beforeUpdate` on a bulk write has no `ast` key
✓ [#5273] a bulk write carries no `ast` on `input` > `beforeDelete` on a bulk write has no `ast` key
✓ [#5273] `input.id` on a bulk write > `beforeUpdate` leaves `id` undefined (the key exists; nothing binds it)
✓ [#5273] `input.id` on a bulk write > `afterUpdate` fires per matched row, each naming its own `id`
✓ [#5273] `input.id` on a bulk write > `afterDelete` fires per matched row, each naming its own `id`
✓ [#5273] the single-record rows of the table > insert carries `data` — never `doc`
✓ [#5273] the single-record rows of the table > a batch insert builds ONE context per row (#2922)
✓ [#5273] the single-record rows of the table > a single-id update binds `id` and `data`
✓ [#5273] the single-record rows of the table > a single-id delete binds `id` and carries no `data`
✓ [#5273] a metadata-declared hook reads the same shape > `ctx.input.ast` is undefined on a bulk update through the flat-input proxy

Test Files  1 passed (1)
     Tests  11 passed (11)

句子 → 断言的映射:「不暴露谓词」← 第 2 / 3 / 11 条(含声明式作者那条路径,正是这句假话原本写给的读者);「after* 按行派发、input.id 绑定」← 第 5 / 6 条;第 1 条是 #4865 阳性对照(读路径确实带 ast),所以这是一次测量,不是对着一个到处都不发 ast 的引擎空过。

门禁

命令	结果
pnpm check:nul-bytes	OK(5699 文件,另对三个改动文件自扫 [\x00-\x08\x0b\x0c\x0e-\x1f\x7f],零命中)
pnpm check:doc-authoring	✅ 362 files clean
pnpm check:docs-audit-scope	✅ 178 hand-written doc(s) in sync;releases 9 页 review-only
pnpm check:role-word	OK(43 baselined,无新增)
pnpm check:skill-frame-sync	✅ 4 copies isomorphic(39 markdown 扫描)
pnpm check:adr-anchors	OK(30 anchored)
--filter @objectstack/spec check:skill-docs	✅ Skill docs in sync
--filter @objectstack/spec check:skill-refs	✅ 9 generated files in sync
--filter @objectstack/spec check:skill-examples	✅ 205 prose examples type-check
pnpm lint(eslint)	0
--filter @objectstack/objectql test	2084 passed (127 files)

changeset:无 → 已自行加 skip-changeset 标签

按实测先例,不靠猜:

• metadata.version 不 bump。 全仓历史里只有 77adf297f(已发布 skill objectstack-pm-dispatch 仍是两轴决策框架 —— 与 .claude/ 内部三轴(#5130)分叉,且「创业聚焦」轴是否该泛化给第三方项目未定 #5451 / PR docs(skills): 已发布 skill objectstack-pm-dispatch 的决策框架由两轴升为三轴(裁决 B:泛化内核后搬) #5799)bump 过 skill 版本,那是维护者裁决的「决策框架两轴改三轴」——改的是已安装 agent 遵循的判定程序。而 skills/objectstack-data/ 自身的内容修改先例是 72c3c8613、cbb6a5ca2、28ad90e9a 三次,都没有 bump;其中 cbb6a5ca2 改的正是本次这个 references/data-hooks.md,改的也正是同一类事情(把一个已不存在的字段从教学里去掉)。另外 skills/README.md 的 frontmatter 字段表根本没有收录 metadata.version,本单也未触碰任何 SKILL.md。
• 不写 changeset,走 skip-changeset 标签。 这是 changeset-check 自己的处方原文(Check Changeset 的失败文案把「空 changeset」推荐为出路 —— 而那正是 #4898 静默卡死发布的输入 #5292 / 空 changeset 会静默卡死已 version 的发布:Release run 全绿,但 npm 和 Docker 什么都没发(17.0.0-rc.2 现在就卡着) #4898 之后):路线 2「releases nothing(.github/、.claude/、docs/、content/、examples、tests-only 之类)→ 加 skip-changeset 标签 ← PREFERRED」;空 frontmatter changeset 是显式的 last resort(它是 changesets/action 的真实输入,全空集会静默绿着卡住 release)。本单零包源码改动,故取路线 2。

同口径先例:PR #5668(#5273 的 spec 侧修复)也是 skip-changeset,无 changeset。

顺带发现(PD #10,均未在本 PR 修)

• HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 —— 同一句假话在 packages/spec/src/data/hook.zod.ts:135-140 的 HookEvent 枚举注释里还剩一处(写作「carried in input」,无 .ast 后缀)。PR docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668 改的是同文件 200 行外的契约表,这段自 b49ccfdfe 起未被触及,于是同一个文件目前自相矛盾。本单派发面明确排除 packages/spec/**,不顺手改。
• data-hooks skill 仍按 #5038 之前教「multi: true 批量写只触发一次、previous 无从绑定」,并明令作者不要在可能批量触发的 hook 里用 previous #5900 —— references/data-hooks.md 的 condition CEL 绑定一节(:254-257、:274-278)仍按 [17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038 之前教:「multi: true 批量写 hook 只触发一次,previous 无从绑定」,并明令「never reach for previous in a hook that can fire on … a multi: true write」。这对 before* 成立,对 after* 不成立 —— bulk-write-per-row-hooks.test.ts 用的常量就是 record.status == "done" && previous.status != "done",按行求值通过。危害方向与本单相反:那处是禁止平台已支持并已 pin 的模式。虽在本单文件面内,但属不同断言,按 PD chore: version packages #10 单独立项。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 11:15am