bug(objectql/docs): hook `condition` 的 CEL 作用域只绑定 `record` —— 文档教的 `previous.x` / `ctx.record` 根本不存在,过渡型条件写不出来

[xuyushun441-sys]

TL;DR

声明式 hook 的 condition 求值时只绑定一个根 record:

// packages/objectql/src/hook-wrappers.ts
const r = ExpressionEngine.evaluate< boolean >(expr, { record: record ?? {} });

但两处已发布的 skill 文档教作者写 previous.*(以及一个不存在的 ctx.record)。写了就静默失效:previous.status → No such key: previous → 被 catch 成 false → hook 不触发,只留一条 warn。

现场

1. skills/objectstack-formula/SKILL.md §5「Update hook condition — previous vs record」直接给出:

   P`previous.status != 'escalated' && record.status == 'escalated'`

   这个例子对 validation rule 的 condition 是对的(rule-validator.ts 确实传 previous binding),对 hook 的 condition 是错的 —— 而小标题写的是 hook。同一页的转换表还把 ISCHANGED(x) 映射成 previous.x != record.x,作者会照着往 hook 里抄。

2. skills/objectstack-automation/SKILL.md 的 time-word 速查表:

   Surface	Event-time record	Pre-event record	Live record
   Object hook (ctx)	ctx.record (write payload)	ctx.previous	—

   HookContext 上没有 record 这个键(packages/spec/src/data/hook.zod.ts:input / result / previous / session / …)。ctx.previous 是真的,ctx.record 不是。

为什么现在值得单独立一条

#4770(hook 条件改为对 stored ⊕ payload 求值)刚把条件的语义从「本次 diff」变成「记录状态」:record.done == true 现在对每一次已完成任务的 update 都为真,而不只是那次把它置为 done 的 update。想表达「刚刚变成 done」这件事,唯一的写法就是比较 previous —— 而 hook 条件恰恰拿不到它。审计类 hook 的原意(showcase_audit_task_completion 的 description 写的是 "after a task transitions to done")因此仍然表达不出来。

两条路,需要定夺(所以本条不带实现)

• A. 给 hook condition 的作用域补上 previous(以及可能的 user),与 validation 谓词对齐。 好处:文档里已经这么教了,作者心智一致,过渡语义可写。代价:condition 的可写表达面变大,属于公开契约扩展 —— 而且 previous 只在引擎取到 prior row 时才有(bulk predicate update 没有),要先定「拿不到时 previous 是什么」。
• B. 不扩作用域,把两处文档改成只讲 record,并明确「hook 条件无法表达过渡,需要过渡语义请用 record-change flow trigger 的 start condition」。 好处:不动运行时。代价:skills/objectstack-formula 的 ISCHANGED 迁移路径在 hook 上就是断的。

无论选哪条,文档与运行时现在是对不上的,属于 declared ≠ delivered。

复现

一个 afterUpdate hook,condition: "previous.done != true && record.done == true",更新任一字段:

WARN [hook] condition evaluation failed; treating as false
  {"hook":"...","condition":"previous.done != true && record.done == true",
   "error":"No such key: previous..."}

---

发现于 #4770 的实现过程中(PR: hook 条件合并 record),按 AGENTS.md Prime Directive #10 记录,未在该 PR 内修复。

[xuyushun441-sys]

认领:PM 循环第 2 轮(分诊中,尚未派发)
会话:session_018iARDqtrhQgz6fVHDeDkbQ
分支:claude/issue-4784-hook-condition-previous-scope(待定夺后建立)

分诊:落地 objectstack(后端 packages/objectql + skills/),不涉及 objectui / cloud。

排队约束(两条,都不是我能绕开的):

1. 文件冲突 —— PR fix(objectql): hook 条件对完整 record 求值 —— stored ⊕ payload,与 #4649 同源 (#4770) #4786 正在合并队列里,它改的正是本 issue 点名的 skills/objectstack-automation/SKILL.md 与 skills/objectstack-data/references/data-hooks.md。同一批次派发必然产生合并竞争,按 batch 独立性规则串行:等 fix(objectql): hook 条件对完整 record 求值 —— stored ⊕ payload,与 #4649 同源 (#4770) #4786 落地再派发。
2. 语义依赖 —— hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 刚拍板方案 B(求不出值 → 抛错中断该次操作)。这直接改变了本 issue 的风险计算:今天 previous.status 写在 hook 条件里只是静默失效,hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 落地之后它会让那次写入失败。所以「文档教的写法运行时不支持」从「静默的坑」升级为「会打挂写入的坑」,本 issue 必须在 hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 之前或同批解决,不能落在它后面。

---

现状核对(读了代码,不是照抄 issue)

• hook 条件的 CEL 作用域确实只绑一个根:hook-wrappers.ts:84 —— ExpressionEngine.evaluate(expr, { record: record ?? {} })。没有 previous,没有 user。
• validation 谓词那边有 previous 绑定,且 Script validation rules are silently skipped when their predicate fails to evaluate — fail-open is the wrong direction for a validation #4649 把它也做成了总全(rule-validator.ts:673-677:「The previous CEL binding is made total too (Script validation rules are silently skipped when their predicate fails to evaluate — fail-open is the wrong direction for a validation #4649)」),并特意注明物化出的 null 不回灌 hookContext.previous。
• ctx.record 确实不存在。hook.zod.ts 声明的是 input / result / previous / session / ql 等 —— skills/objectstack-automation/SKILL.md 速查表里那格 ctx.record 是纯错,与 A/B 怎么选无关,两条路下都要改。

一个改变判断的发现:引擎已经有「按需取 prior row」的成例

issue 把 A 的代价写成「previous 只在引擎取到 prior row 时才有(bulk predicate update 没有),要先定拿不到时 previous 是什么」。读了代码之后,这个前提需要修正 —— 引擎不是"碰巧有就有",而是按需求驱动去取:

engine.ts:4597 的 rulesNeedRows 分支,配合 rule-validator.ts:477 的 ruleNeedsPrior(rule):哪条规则声明了它要读 prior,引擎就为 bulk update 逐行取 prior row 喂给它(previous: row);没有规则要,就走零取数的 previous: null 快路径。#4649 还特意把「conditional 只要声明了 when 就算需要 prior」补了进去。

也就是说 A 不需要发明新机制:hook 的 condition 是预编译的(hook-wrappers.ts:74 就编好了),编译期即可判定这条条件有没有引用 previous,然后沿用同一条按需取数的路。「拿不到时 previous 是什么」这个问题在 A 下大部分是不存在的 —— 需要就去取,不需要就不取。

两条路,沿两条固定轴

A. 给 hook condition 的作用域补上 previous(与 validation 谓词对齐)

• 项目长远合理性:好。 平台已经有两处「对着 record 求 CEL」的表面,bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 刚把它们的 record 统一到一个 helper。作用域再对不上,就是同一件事的第二次漂移 —— 作者要记「validation 里能写 previous,hook 里不能」,这条区别没有任何道理可讲,纯属实现史。而且过渡语义(「刚变成 done」)是审计类 hook 的核心用例,showcase_audit_task_completion 自己的 description 写的就是 "after a task transitions to done" —— 平台连自己示例的原意都表达不出来,这是能力缺口,不是作者写错。
• 防 AI 写错:好,且是 A 相对 B 的主要优势。 文档已经这么教、AI 也已经这么写(ISCHANGED(x) → previous.x != record.x 是迁移表里的正式条目)。B 是要求文档、skill、以及所有已经形成的写法习惯一起绕开一个本可以支持的能力;A 是让运行时兑现已声明的教学。契约收紧的方向在这里是「让声明成真」,不是「把声明删掉」。
• 代价(要说清): ① bulk predicate update 上,一条引用 previous 的 hook 条件会触发逐行取数 —— 这是 validation 已经在付的同一笔成本,但 hook 侧新增;② previous 绑定必须和 validation 一样做成总全(Script validation rules are silently skipped when their predicate fails to evaluate — fail-open is the wrong direction for a validation #4649 的 materializeDeclaredFields,bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 刚抽成共用 helper),否则在 hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 的 B 之下,一个读 previous.x 的条件会因为 driver 没返回该列而打挂写入;③ insert 上 previous 是什么要写死(validation 侧的答案是 null/不需要 prior,照抄即可)。

B. 不扩作用域,改文档并指向 record-change flow trigger

• 项目长远合理性:中。 不动运行时是真实的好处;但它把「hook 条件」永久定义成「只能描述状态、不能描述过渡」,而 bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 刚让条件从「本次 diff」变成「记录状态」—— 两件事叠加,结果是过渡语义在 hook 这条路上被彻底关死,作者要改用 flow trigger。如果 flow trigger 确实是我们希望承接过渡语义的唯一地方,那 B 是收敛而不是残缺;如果不是,B 就是用文档掩盖一个能力缺口。这一点是你的产品判断,我没有依据替你定。
• 防 AI 写错:取决于执行得多彻底。 光改文档不够 —— 必须让 previous.x 在 hook 条件里响亮地报错并指路(「hook 条件不支持 previous,过渡语义请用 record-change flow trigger」)。hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 的 B 恰好提供了这个报错通道,但默认错误文案会是 No such key: previous,对着已被文档教过 previous 的作者来说毫无指引。B 必须附带一条专门的诊断,否则它在防 AI 犯错这条轴上明显劣于 A。

我的建议

A,并且要求:previous 绑定复用 #4770 抽出的 materializeDeclaredFields 做成总全;是否取 prior 由条件的编译期分析驱动,沿用 rulesNeedRows / ruleNeedsPrior 的成例,不引入第二套按需取数机制;insert 上的 previous 语义与 validation 侧逐字一致。

理由沿两条轴:长远上它消除的是同一概念在两个表面上的第二次漂移(#4770 刚消除了第一次);防 AI 犯错上,文档与 AI 的既有写法已经站在 A 这边,而 B 要求的是让所有人绕开一个技术上可支持的能力 —— 在 #4775 选了 B(fail loud)之后,「绕开」的代价从静默失效变成了写入失败,门槛更高了。

如果你的产品意图本就是「过渡语义一律走 flow trigger,hook 条件只描述状态」,那 B 是对的收敛,请直说 —— 那我会把它连同一条专门的诊断文案一起派发,而不是只改文档。

ctx.record 那格是纯错,无论 A/B 都要修,不单独占一次决策。

---

Generated by Claude Code

[xuyushun441-sys]

维护者已拍板:方案 A —— 给 hook condition 的作用域补上 previous

决定:hook 的 condition 作用域扩为 record + previous,与 validation 谓词对齐。B(只改文档、把过渡语义收敛到 flow trigger)不采纳 —— 过渡语义在 hook 条件里是要支持的,不是要绕开的。

随决定确认的实现约束(派发时会原样写进 prompt):

1. previous 绑定必须做成总全,复用 bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 抽出的 packages/objectql/src/declared-fields.ts 的 materializeDeclaredFields —— 与 validation 侧 Script validation rules are silently skipped when their predicate fails to evaluate — fail-open is the wrong direction for a validation #4649 的做法逐字一致(rule-validator.ts:673-677)。在 hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 的 fail loud 之下这不是优化而是必需:否则一条读 previous.x 的条件会因为 driver 没返回该列而打挂写入。同样地,物化出的 null 不得回灌 hookContext.previous(after hook 观察的是同一批对象,Script validation rules are silently skipped when their predicate fails to evaluate — fail-open is the wrong direction for a validation #4649 已就此留过注释,bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 的测试也钉了这条)。
2. 是否取 prior row 由条件的编译期分析驱动,沿用 engine.ts:4597 的 rulesNeedRows / rule-validator.ts:477 的 ruleNeedsPrior 那条成例 —— hook 条件本来就是预编译的(hook-wrappers.ts:74),编译期即可判定有没有引用 previous。不要引入第二套按需取数机制;不引用 previous 的条件必须保持零额外取数。
3. insert 上的 previous 语义与 validation 侧逐字一致(不需要 prior / null),不要另立一套。
4. skills/objectstack-automation/SKILL.md 速查表里的 ctx.record 是纯错(HookContext 声明的是 input / result / previous / session / ql),一并改掉 —— 这一格与 A/B 无关,两条路下都要修。
5. skills/objectstack-formula/SKILL.md §5 的 previous.status != … && record.status == … 与 ISCHANGED(x) → previous.x != record.x 迁移条目,在 A 之下变成正确的,保留;需要补的是「bulk predicate update 上引用 previous 会触发逐行取数」这条成本提示。

排队(链条已定,不要乱序)

#4786(#4770 修法 1,合并队列中)
   └─▶ #4784(本 issue,方案 A:previous 进作用域)
          └─▶ #4775(方案 B:求不出值 → 抛错中断)

• 本 issue 等 fix(objectql): hook 条件对完整 record 求值 —— stored ⊕ payload,与 #4649 同源 (#4770) #4786:文件冲突(两处 skill 文档),且要用它抽出的 materializeDeclaredFields。
• hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 等本 issue:hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 的 fail loud 会把「条件里写了 previous」从静默失效变成写入失败。先把 previous 支持上,文档教的写法才是对的,fail loud 才不会当场打挂一批照文档写的 hook。顺序反了就是自造一次事故。

Blocked-by: objectstack-ai/objectstack#4770(PR #4786)。#4786 合入后本 issue 立即派发。

---

Generated by Claude Code

[xuyushun441-sys]

PM 复核:通过(ACCEPT),等 CI 全绿后进合并队列

PR:#4799(草稿,base main,body 首行 Fixes objectstack-ai/objectstack#4784,changeset @objectstack/objectql: minor,未触碰 content/docs/releases/)

我自己去代码里验证的三条(派发时说了不会只信报告)

1. 复用了共用 helper,没另写一个:pickPreviousPayload 调的是 declared-fields.ts 的 materializeDeclaredFields,与 record 走同一条。✅
2. 物化出的 null 没有回灌 hookContext.previous:{ ...(prior) } 先拷贝再物化。两处钉住 —— wrapper 层断言 ctx.previous 键集仍是 ['done','id','status','title'],真引擎层断言 after hook 观察到的 previous 没长出 archived。✅
3. 不引用 previous 的条件零额外取数:engine.ts 的改动是纯注释(12 行新增、0 删除) —— 根本没有新增取数机制。两条 pin 用 driver 计数器量:纯 record 的 before-hook 条件 findOne 增量为 0;引用与不引用 previous 的 afterUpdate 条件都是 1 vs 1。✅

我派发时写错的两条约束,dev 顶回来了,顶得对

• 约束 2 我要求「取不取 prior row 由条件的编译期分析驱动」 —— 实现没有这么做,理由成立:既有那道闸门只要注册了 afterUpdate hook 就已经取,再加一层「条件里有没有 previous」的分析今天就是死代码。它改为在 engine.ts 留注释说明「这道闸门若将来被收窄(例如按对象细分),必须把读 previous 的 hook 条件计入新的需求判定」,并用测试钉住。比我要求的那版对。
• 约束 5 我要求文档写「引用 previous 会让 bulk predicate update 逐行取数」 —— 这句话是错的,dev 没有照抄。引擎在批量分支上 hook 只触发一次、hookContext.previous 从不赋值,逐行取回来也没有东西可以绑。写下那句提示会是又一次 declared ≠ delivered。它改为如实写「批量上 previous 不绑定」,并把这一格拆成 批量写上 hook 的 previous:B1 已拍板(fail loud 无例外,并入 #4775);本条转为「批量写 hook 按行触发」设计卡孵化点 #4800。这是正确的处理。

其余验收项

ctx.record 已消失(速查表拆成 handler ctx.* 与 condition CEL 两行,并加了一段明写「没有 ctx.record」);formula SKILL §5 的 previous 示例与 OLD.x / ISCHANGED(x) 迁移条目按方案 A 保留,并补了绑定作用域表、总全性、!= null 而非 has()、以及成本说明;showcase 的审计 hook 改成 previous.done != true && record.done == true —— 它的 description 一直写的是 "after a task transitions to done",现在名实相符了。

衍生的新阻塞:#4800(重要)

#4799 之后,批量更新那条路成了会在 #4775 之后变成事故的一格:引用 previous 的条件在 predicate 批量更新上不可求值,今天只是 warn + 跳过,但 #4775 的 fail loud 落地后,该对象的每一次批量更新都会写入失败,失败还指向一个与这次写入无关的 hook。

排队因此再加一环:

#4786 ✅ → #4799(本 issue)→ #4800(批量上 previous 的语义,待拍板)→ #4775(fail loud)

已在 #4775 上补 Blocked-by: #4800。

---

Generated by Claude Code