fix(objectql,skills): hook condition 的 CEL 作用域补上 previous —— 过渡语义可写,与 validation 谓词对齐 (#4784) (#4799)

声明式 hook 的 `condition` 只绑定一个根 `record`,但两处已发布的 skill 文档
(`objectstack-formula` §5 与它的 `ISCHANGED(x)` → `previous.x != record.x`
迁移条目)一直教作者写 `previous.*`。照着写下去只会静默失效:
`No such key: previous` → 被 catch 成 `false` → hook 不触发,只留一条 warn。
declared ≠ delivered。

#4770 之后这条缺口变成了能力缺口:`record` 现在表示记录的**状态**,
`record.done == true` 对每一次已完成任务的 update 都为真。「刚刚变成 done」
只能靠比较 `previous` 表达,而 `showcase_audit_task_completion` 的 description
写的正是 "after a task transitions to done"。

- `hook-wrappers.ts`:条件求值绑定 `record` + `previous` 两个根。`previous`
  复用 `materializeDeclaredFields`(#4649/#4770 的同一个 helper)对**已声明字段**
  做成总全 —— driver 没返回的列读作 `null` 而不是让整条表达式 fault;未声明的
  key 仍然不可求值,拼写错误照旧报出来。**拷贝而非原地修改**:`ctx.previous`
  是引擎自己的 pre-image,after hook 观察的就是它,物化出的 null 不回灌。
- 取不到 prior 时 `previous` **不绑定**(CEL 里就是一个未声明标识符),与
  `validation/rule-validator.ts` 逐字一致:insert 事件没有前态;predicate
  (`multi: true`) 批量更新一次匹配 N 行、hook 只触发一次,没有单一前置记录可绑。
  绑 `{}`/`null` 等于替没人读过的行编造事实。
- **不新增按需取数机制**:`previous` 搭的是 `engine.update` 既有的那一次
  prior 取数(注册了 afterUpdate hook 就会取),即喂 `ctx.previous` 和
  record-change flow trigger 的同一行。不引用 `previous` 的条件零额外取数,
  已用测试钉死。engine.ts 那处 gate 留了注释:今后若收窄它,必须把 hook
  条件的 `previous` 需求算进新的判定。
- 文档:`objectstack-automation/SKILL.md` 速查表里的 `ctx.record` 是纯错
  (`HookContext` 声明的是 `input` / `result` / `previous` / `session` / `ql`),
  改为区分 handler 的 `ctx.*` 与 condition 的 CEL 根;`objectstack-formula`
  §5 保留 `previous` 示例并补上绑定范围/总全/`!= null` 而非 `has()`/成本说明;
  `objectstack-data/references/data-hooks.md` 的 condition 一节同步。
- showcase 的 `showcase_audit_task_completion` 改用过渡条件,让它的 description
  与实际行为一致。


Claude-Session: https://claude.ai/code/session_018iARDqtrhQgz6fVHDeDkbQ

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/hook-condition-previous-binding.md

@@ -0,0 +1,55 @@
+---
+'@objectstack/objectql': minor
+---
+
+**A declarative hook `condition` can now express a TRANSITION: the CEL scope binds `previous` alongside `record` (#4784).**
+
+The condition gate evaluated against a single root — `{ record }`. Both published skill
+docs, however, taught the `previous` form: `objectstack-formula` §5 ("Update hook
+condition — `previous` vs `record`") gives
+`P\`previous.status != 'escalated' && record.status == 'escalated'\``, and its legacy
+migration table maps `OLD.x` → `previous.x` and `ISCHANGED(x)` → `previous.x != record.x`.
+Written into a hook, any of those aborted the expression with `No such key: previous`,
+which the gate swallowed into `false` — the hook simply never ran, leaving one WARN line.
+Declared ≠ delivered.
+
+It became load-bearing with #4770. `record` now means the record's **state** (stored ⊕
+payload), so `record.done == true` is true on *every* update of an already-done row — not
+only the one that completed it. `showcase_audit_task_completion`'s own description says
+"after a task transitions to done", and there was no way to write that. Now there is:
+
+```ts
+condition: P`previous.done != true && record.done == true`
+```
+
+`previous` is built exactly as the validation side builds it (#4649), through the shared
+`materializeDeclaredFields` helper, so one CEL expression means one thing on both
+surfaces:
+
+- **the stored pre-write row**, made **total over the object's DECLARED fields** — a
+  column the driver never returned reads as `null` instead of aborting the expression;
+- **declared fields only** — `previous.dnoe` stays unevaluable, so a typo is still
+  reported rather than quietly answered;
+- **copied, never mutated in place.** `ctx.previous` is the engine's own pre-image object,
+  observed by every after-hook; the materialised `null`s do not leak into it.
+
+**Where `previous` is NOT bound** — verbatim the rule `validation/rule-validator.ts`
+already applies, so referencing it there makes the condition unevaluable:
+
+- **insert events** (`beforeInsert` / `afterInsert`) — there is no prior state. Write
+  insert conditions over `record` alone.
+- **predicate (`multi: true`) bulk updates** — one write matches N rows and the hook fires
+  once, so there is no single prior record. Binding `{}` or `null` would answer
+  `previous.x == null` with a fabricated fact about rows nobody read.
+
+**Cost: none.** No new demand-driven fetch was introduced. `previous` rides on the prior
+row `engine.update` already reads whenever an afterUpdate hook is registered — the same
+one that feeds `ctx.previous` and record-change flow triggers. A condition that never
+mentions `previous` reads nothing extra, pinned by test.
+
+**What you may see after upgrading:** hooks whose condition referenced `previous` never
+fired before and start firing now. That is the declaration finally being honoured — review
+any hook carrying a `previous.*` condition before you upgrade.
+
+**Unchanged, deliberately:** a condition that is *still* unevaluable is logged at WARN and
+treated as `false`. Whether that should fail loudly instead is tracked separately.

examples/app-showcase/src/data/hooks/index.ts

@@ -38,13 +38,20 @@ export const NormalizeTaskTitleHook = {
   description: 'Trims leading/trailing whitespace from the task title before every write.',
 };
 
-/** afterUpdate (gated) — log a line whenever a task flips to done. */
+/**
+ * afterUpdate (gated) — log a line on the update that flips a task to done.
+ *
+ * The condition compares against `previous` on purpose (#4784). Since #4770
+ * `record` means the record's STATE, so `record.done == true` alone would audit
+ * every later edit of an already-done task — while this hook's own description
+ * says "transitions to done". The transition is the two-root form.
+ */
 export const AuditTaskCompletionHook = {
   name: 'showcase_audit_task_completion',
   label: 'Audit Task Completion',
   object: 'showcase_task',
   events: ['afterUpdate'] as LifecycleEvent[],
-  condition: "record.done == true",
+  condition: "previous.done != true && record.done == true",
   body: {
     language: 'js' as const,
     source: "var r = ctx.result || ctx.input || {}; ctx.log.info('task completed: ' + (r.title || r.id || 'unknown'));",

packages/objectql/src/engine.ts

@@ -4736,6 +4736,18 @@ export class ObjectQL implements IObjectQLEngine {
            // record-change flow triggers work: their start-condition gate reads
            // `previous.*` (e.g. `status == "done" && previous.status != "done"`),
            // which silently fails when `previous` is absent.
+           //
+           // [#4784] It is ALSO what supplies the `previous` binding to a
+           // declarative hook `condition` (`hook-wrappers.ts`), which is how a
+           // TRANSITION is expressed there: `previous.done != true &&
+           // record.done == true`. Note this needs NO second demand-driven
+           // fetch — the existing gate already fetches whenever an afterUpdate
+           // hook exists, and afterUpdate is the event whose context carries
+           // `previous`. Deliberately: adding a "does the condition reference
+           // `previous`?" analysis on top would be dead code today. If this
+           // gate is ever NARROWED (e.g. scoped per object), hook conditions
+           // reading `previous` must be counted into the new demand test —
+           // pinned by `hook-condition-previous-scope.test.ts`.
            let priorRecord: Record<string, unknown> | null = null;
            const updateSchema = this._registry.getObject(object);
            const mediaValueShapeStrict = await this.mediaValueShapeStrictFor(updateSchema);