fix(objectql): 单记录 delete 绑定 hookContext.previous —— 让引擎符合契约已声明的「for update/delete」 (#5272)

[os-zhuang]

Fixes #5272

按 issue 的 A 方向实施(PM 已拍板):delete() 复用 update() 同款的 demand-driven 前置行门,在单 id 路径取一次前置行并赋给 hookContext.previous,覆盖 beforeDelete / afterDelete 两个阶段。⛔ 未触碰 packages/spec/**、content/docs/releases/**、metadata-protocol/src/protocol.ts、core/src/kernel.ts,也未改 plugin-audit 的 __previous 兜底。

---

一、STALE-PREMISE 事实核对(基于合并 #5270 之后的现场)

worktree 基于 3905c0064(即 PR #5270 的合入点),逐条核对 issue 正文引用的行为:

issue 的说法	合并后现场	结论
hookContext.previous 的赋值只有一处,在 update() 单 id 分支	现在是两处:update() 单 id 分支(engine.ts 原 5300 行),以及 #5270 新增的 buildPerRowAfterContexts()(原 1225 行),后者为批量 update 和批量 delete 的每行 after 上下文赋 previous	⚠️ 已过时,但结论更强:单记录 delete 是合并后唯一一条完全不绑 previous 的写入路径
delete() 全程不给 hookContext.previous 赋值	成立(修复前 grep previous 在 delete() 体内零命中)	✅ 成立
summaryPrev 只喂 recomputeSummaries,不进上下文	成立(原 5551–5556 读,5611–5613 唯一消费点)	✅ 成立
报错走通用分支、读起来像作者拼错 key	已用真实引擎复现,原文如下	✅ 成立

复现原文(在 stash 掉本 PR 的 engine.ts 改动、只跑新测试时打印):

Hook 'audit_completed_task_deletion' could not evaluate its condition
(type: Unknown variable: previous) — operation aborted. The condition reads
'previous', which is not bound for this operation — the scope holds 'record',
plus 'previous' only when the record's prior state is in hand.

补充一条 issue 未提、实施中确认的事实:summaryPrev 走的是引擎级 this.findOne()(过中间件、RLS、formula 投影),而 update() 喂给 recomputeSummaries 的 priorRecord 是裸 driver 读。同一件事两条路两种语义 —— 合并成一次读时按 update() 的口径统一(见下)。

---

二、实现摘要(packages/objectql/src/engine.ts)

前置行读取放在 triggerHooks('beforeDelete') 之前:delete 的 before 阶段是唯一「除了 id 什么都没有」的阶段(input 无 data),而前像本来就必须在删除动作前取,一份数据两个阶段共用。

门(demand-driven):

hasHooksFor('beforeDelete', object) || hasHooksFor('afterDelete', object)
  || getSummaryDescriptors(object).length > 0

• 用 hasHooksFor(event, object)(按对象)而不是 update() 那条 this.hooks.get('afterUpdate')?.length > 0(全局),与 [17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038 批量 delete 侧同款,更省。
• 刻意没有把 needsPriorRecord(schema) 放进门,虽然 update() 的孪生门带着它:对象校验规则只在 insert/update 求值,delete() 一条都不跑 —— 带上它就是买一次没有读者的读。这是对 PM 指令中「同款条件」的一处有意收窄,理由记在代码注释里。

合并为一次读:原先 roll-up summary 的 summaryPrev 是另一次、更晚的读(在 beforeDelete 之后)。现已删除,recomputeSummaries 直接吃这一次前置行。口径按 update() 统一为裸 driver.findOne —— recomputeSummaries 只取 p?.[desc.fkField](存储列),裸读足够,且不会因调用方读权限被 RLS 收窄而静默跳过父行重算。

租户/事务安全:裸 driver 读经 buildDriverOptions(object, opCtx.context, hookContext.input.options) 取得 options —— 这正是把开启中的事务和 tenantId 带到裸读上的那一层,update() 的前置读同理。少了它会读到事务外、甚至跨租户。

不臆造:行不存在 → previous 保持 unbound(而非 {} / null),条件读它仍按 #4649/#4775 大声失败,而不是替一条没人读过的记录作答。

id 被改写/清空的收尾:beforeDelete hook 可以改写甚至清空 input.id(#4550 的 reject 判定就是为此再问一次)。hook 跑完后若 input.id !== id,则重读(改写)或丢弃(清空)绑定 —— 陈旧前像绝不进入 afterDelete 或 summary 重算;清空后落到 predicate 分支,而批量派发按契约本就不该带任何单行前像(hook-wrappers 正是靠这个「两者皆无」来诊断批量派发)。

未动:#5038 的批量 predicate delete 按行绑定路径逐字未改。

---

三、测试

改造既有「开绿灯」的 pin(本单硬性要求)

hook-condition-previous-scope.test.ts 的 a delete-shaped context evaluates 'previous' against the pre-image 手工构造 previous,断言的是 wrapper 读没读它 —— 而引擎从不产出这份数据,于是它替一个不存在的行为发了绿灯,真正的故障(每一次带 previous.* 条件的单记录 delete 都被 #4775 打回)就藏在它后面。已删除,原位留下说明注释,替换为走真实引擎的端到端用例。

新增 8 例(全部 insert → 真实 engine.delete() → 断言 hook 拿到什么)

用例	断言
hands 'beforeDelete' the stored pre-image	ctx.previous 等于数据库前像,不是 undefined、也不是 delete input 的裸 {id}
hands 'afterDelete' the same pre-image — by then the row is gone	同一份前像;并先断言此刻该行已读不到,坐实「必须提前取」
evaluates a 'previous.*' delete-side condition instead of rejecting the delete (#4775)	issue 原样的 previous.status == 'done':两次 delete 都不被拒,且条件有选择性(只对 done 的那条触发)
is TOTAL over declared fields on a delete too	从未写过的列在 delete 侧同样物化为 null,不中断表达式
does not leak materialised nulls into what the delete hook observes	引擎自己的 ctx.previous 不会多出该行从未有过的列
reads the pre-image ONCE for both phases	before+after 两个 hook 都在时,findOne 增量 = 1(合并读的成本护栏)
reads nothing at all when the object has no delete-side hook	增量 = 0(demand-driven 门)
leaves 'previous' UNBOUND when the row is not there	拿到 undefined,不臆造

反向验证(证明这些是真 pin,不是重言式):把 engine.ts 的改动 stash 掉单跑该文件 —— 6 failed | 17 passed,失败原因正是 issue 描述的两类(expected undefined to deeply equal {...}、HookConditionError ... Unknown variable: previous);另 2 例(无 hook 不读、行不存在不绑)修复前后都应成立,故不失败。恢复改动后 23 例全绿。

验证记录

命令	结果
pnpm --filter @objectstack/objectql test	Test Files 116 passed (116) / Tests 1875 passed (1875)
pnpm --filter @objectstack/objectql typecheck	tsc --noEmit,无输出(通过)
pnpm exec eslint packages/objectql/src/engine.ts packages/objectql/src/hook-condition-previous-scope.test.ts	无输出(通过)
turbo run test --filter @objectstack/plugin-audit --filter @objectstack/trigger-record-change	plugin-audit 108 passed;trigger-record-change 55 passed(两者都读 ctx.previous,是本改动的直接下游)

summary-rollup.test.ts(含 recomputes when a child is deleted)与 engine-summary-retry.test.ts 覆盖了被合并掉的那次读,均绿。

重的构建/测试全程持 flock /tmp/os-heavy-verify.lock 并带 NODE_OPTIONS=--max-old-space-size=4096,--maxWorkers=2 / --concurrency=2。

---

四、变更记录

.changeset/single-delete-binds-previous.md(@objectstack/objectql: patch),写明行为变化与升级影响:原本因 #4775 被打回的 delete 侧 previous.* 条件现在正常求值;delete 侧 handler 开始收到 ctx.previous;若有人靠 ctx.previous == null 来判别「这是一次 delete」,该判据失效,应改读 ctx.event。未改 content/docs/releases/**。

---

五、范围外(未在本 PR 修,留给 PM 分诊)

1. plugin-audit 的 (ctx as any).__previous 兜底可退役(PM 已记为后续 finding,本 PR 按指令不动)。audit-writers.ts 的 captureBefore 在 beforeDelete 里自己再读一次前像塞进 __previous;单记录 delete 的 previous 落地后,这次读在 delete 路径上已成重复(update 路径本来就重复)。退役它可省掉一次读,但属独立面。
2. update() 的前置行门仍是全局的(this.hooks.get('afterUpdate')?.length > 0),而 delete 侧用的是按对象的 hasHooksFor。全局门意味着任一对象注册了 afterUpdate,所有对象的单 id update 都多付一次读。属可收窄的性能面,非缺陷,未在本单扩面。

以上两条尚未开 issue —— 均为 PM 已知/已记项与纯优化面,按 #4949 的立项纪律先在此列明,若需要我可另开 finding 标签的观察类 issue。

---

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 4, 2026 3:45pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

13 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

范围外清单补记(正文第五节写这两条时尚未立项,现更新):

• 第 2 条已开 issue:update() 的前置行门是全局的(hooks.get('afterUpdate').length > 0),任一对象注册 afterUpdate 就让所有对象的单 id update 多付一次读 #5284 —— update() 的前置行门是全局的(this.hooks.get('afterUpdate')?.length > 0),任一对象注册 afterUpdate 就让所有对象的单 id update 多付一次读;而同文件的批量路径用的是按对象的 hasHooksFor。已按观察类挂 finding + domain:engine,不挂 pm:queue、不指派,交 PM 分诊定级。立项前已按关键词与文件面搜过 open issue,无重复。issue 里同时记下了收窄这条门的陷阱(bug(objectql/docs): hook condition 的 CEL 作用域只绑定 record —— 文档教的 previous.x / ctx.record 根本不存在,过渡型条件写不出来 #4784 的注释预告:按对象化后必须把 beforeUpdate 侧读 previous 的 condition 计入需求测试,否则会在 update 侧造出本 PR 刚在 delete 侧修掉的那类 hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 打回)。
• 第 1 条(plugin-audit 的 __previous 兜底可退役)未另开 issue —— PM 在 单记录 delete 从不绑定 hookContext.previous —— 契约声明「for update/delete」,引擎只在 update 分支赋值;#5038 之后批量 delete 反而比单记录 delete 更完整 #5272 的认领评论里已声明「修复落地后它是否退役另记 finding」,属已记项,避免开出双胞胎。若 PM 希望由我补一份独立 issue,告知即可。

---

Generated by Claude Code