HookContext 契约表把 `before*` 的 `input.options` 记成 DriverOptions —— 实测那里仍是调用方的 engine options(含 where),两个 break-glass 守卫正读它

[baozhoutao]

观察类发现(finding),来自 #5941(break-glass delete 守卫)的实测。今天没有用户会撞上:代码行为正确且被两个守卫依赖,问题在于同一段散文对它的描述不精确,而这段散文就是下一个作者能读到的唯一规格。

两条陈述

packages/spec/src/data/hook.zod.ts 的 HookContextSchema.input 契约表(#5273 / PR #5668 落地,#5964 刚把枚举注释对齐到它):

   * - delete (bulk, multi:true) — before: { id: undefined, options: DriverOptions }
   * - update (bulk, multi:true) — before: { id: undefined, data: Record, options: DriverOptions }
   ...
   * The row-scoping predicate is NOT reachable from `input` at all. …
   * scope the batch through `options.where` at the CALLER, or work per row on
   * the `after*` events below.

实测(对 origin/main = ffd51fd7a)

packages/objectql/src/engine.ts:

行	事实
5516 → 5517	await this.triggerHooks('beforeUpdate', …) 之后才 hookContext.input.options = this.buildDriverOptions(…)
6137 → 6152	await this.triggerHooks('beforeDelete', …) 之后才做同一件事

也就是说 before* 期间 input.options 仍是调用方那只 engine options 包(EngineUpdateOptions / EngineDeleteOptions),where 与 multi 都在;它变成 DriverOptions 是在钩子返回之后、驱动调用之前。真engine + better-sqlite3 上探针实测到的 beforeDelete 载荷:

by-id      : { inputId: 'u1', inputOptionsWhere: { id: 'u1' }, previous: [...] }
multi      : { inputId: undefined, inputOptionsWhere: { id: { $in: ['u2','u3'] } }, inputOptionsMulti: true }

所以契约表里两处 before 行的 options: DriverOptions 与实测不符,而「NOT reachable from input at all」+「scope … at the CALLER」这组措辞,读起来像是「钩子看不到谓词」——钉子测试并没有钉这一句:hook-input-shape-contract.test.ts 断言的是 'ast' in input === false(以及读路径的阳性对照),没有任何一条断言 input.options 上没有 where。

为什么值得记

这不是措辞洁癖:packages/plugins/plugin-auth 的两个 break-glass 守卫(#5892 的 ban 半边、#5941 的 delete 半边)正是靠 before* 期间的 input.options.where 解析谓词/multi 写的目标行集 —— 没有它,批量写这条能一次扫掉全部管理员的路径就是盲区。按现在的散文,下一个安全钩子作者会得到「谓词拿不到,放弃」的结论,或者反过来读到守卫的代码后认为它违反契约。

两句都可以同时为真,只是要把区别写明:钩子拿不到的是 composed ast(生效谓词,filters 中间件可能往上叠 RLS / sharing 的收窄);拿得到的是调用方原始 options.where。因为中间件只会收窄不会放宽,把调用方谓词当作行集是上界近似 —— 对 fail-closed 的守卫恰好是安全方向。

建议

契约表两处 before 行改成实测形状(调用方 engine options,DriverOptions 是 after* / 驱动调用起才成立),并在那段说明里补一句区分 composed ast 与调用方 options.where;顺手给 hook-input-shape-contract.test.ts 加一条正向断言(before* 的 input.options.where 就是调用方传入的谓词),这样这条被两个安全守卫依赖的性质从散文变成钉子。

参考

• HookContext.input 的契约注释声明批量写携带 input.ast,引擎从不设置它(AST 只在 opCtx 上);同一张表也未描述 #5038 后 after 事件的按行形状 #5273 / PR docs(spec): HookContext.input 契约表改成引擎真正构造的形状 (#5273) #5668(契约表)、HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 / PR docs(spec): HookEvent 枚举注释不再声称批量写把行级谓词放在 input (#5899) #5964(枚举注释对齐)
• Security: bulk (multi) update/delete skips OWD owner scoping on private objects — members can modify others' rows #2982(谓词走 opCtx.ast 的原因)、单记录 delete 从不绑定 hookContext.previous —— 契约声明「for update/delete」,引擎只在 update 分支赋值;#5038 之后批量 delete 反而比单记录 delete 更完整 #5272(delete 预取)、[17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038(bulk after* 逐行派发)
• plugin-auth: break-glass 守卫 —— SCIM/ban 不得停用最后一个管理员(ADR-0024 D5.2,cloud#621 转入) #5892 / PR feat(plugin-auth): break-glass 守卫 —— ban 不得停用最后一个管理员(ADR-0024 D5.2) #5939、最后一个管理员的「删除」路径无守卫:目标不持本地密码时,SCIM/admin remove 可删掉环境最后一个管理员 #5941(两个消费者)

[claude]

发现分诊:晋级 —— 摘 finding,改 pm:queue + domain:spec

判级 — 晋级入队,且建议在 spec 车道里排靠前。立单人自评「今天没有用户会撞上」成立(代码行为正确),但观察类的判据不是「代码对不对」,而是「散文错了会不会咬人」——这里会:packages/plugins/plugin-auth 的两个 break-glass 守卫(#5892 的 ban 半边、#5941 的 delete 半边)正是靠 before* 期间的 input.options.where 解析批量写的目标行集,而契约表现在写着 options: DriverOptions + 「The row-scoping predicate is NOT reachable from input at all」。下一个安全钩子作者按这段散文只会得出两个结论之一:「谓词拿不到,放弃」(于是批量写扫掉全部管理员那条路成为盲区),或「守卫违反契约」(于是去删守卫)。两个结论都指向拆掉一道安全防线,这就是它不该留在观察档的原因。

域 — 落点 packages/spec/src/data/hook.zod.ts(契约表)+ hook-input-shape-contract.test.ts(补正向钉子)⇒ domain:spec(「shared contract surfaces have one owner」)。

过时前提检查(origin/main 44106d9;正文引用 ffd51fd7a,已前移):

• 实测的顺序逐条仍成立,但行号已漂,派发时按新行号:engine.ts:5529 triggerHooks('beforeUpdate') → :5530 才 input.options = buildDriverOptions(...);:6150 triggerHooks('beforeDelete') → :6165 才同一动作(正文记的是 5516/5517 与 6137/6152)。结论不变:before* 期间 input.options 仍是调用方的 engine options,where / multi 都在。
• 契约表与那段措辞仍在 hook.zod.ts;HookEvent 的枚举注释仍在说批量写把行级谓词「carried in input」—— 与 #5273 同一句假话,在同文件 40 行之外 #5899 / PR docs(spec): HookEvent 枚举注释不再声称批量写把行级谓词放在 input (#5899) #5964 只对齐了枚举注释,未触及本段。

同文件并发提示(给 spec 座位) — hook.zod.ts 上本轮共有两单:本单与 #6001(positions JSDoc 仍举 services.sharing.canEdit(…) 为正例,同轮入队)。⚠️ 两单改的是同一文件的不同段落,建议同批或明确串行;另 #5899 已 MERGED(2381c19),座位表该行仍记其为在飞,文件锁实际已释放。

范围提示 — 正文的两句区分是本单的核心产出,建议原样进 PR 措辞:钩子拿不到的是 composed ast(filters 中间件可能叠 RLS / sharing 的收窄);拿得到的是调用方原始 options.where;因中间件只收窄不放宽,把调用方谓词当行集是上界近似,对 fail-closed 守卫恰是安全方向。⛔ 不要为了「让散文变简单」把守卫依赖的这条性质写没了。

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

---

Generated by Claude Code

[hotlong]

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — criterion ②: the published HookContext contract table says before* input.options is DriverOptions and "predicate NOT reachable", while the runtime passes the caller's engine options including where — the very shape two break-glass guards rely on. Declared ≠ enforced on a public contract. Triage seat may veto.

---

Generated by Claude Code

[hotlong]

Triage: domain:spec → domain:spec-surface (seat #6298; existing-stock migration pass, maintainer-instructed 2026-08-07). Direction decided before routing, since it is what picks the seat: the runtime shape here (caller engine options carrying where) is what two break-glass guards depend on, so the contract table is the wrong artifact, not the runtime — a doc-side correction with the acceptance surface untouched. ⚠️ If anyone later rules that the runtime should be narrowed to match the table instead, that is an acceptance change and the card returns to domain:spec.

---

Generated by Claude Code

[hotlong]

pm:blocked applied + Blocked-by: #6001 body line (spec-surface seat #6298, session session_01JTSZAjgtL3oR6YcpNDhW3T). Reason: #6001 is in flight (claimed by the spec lane's wave, pm:dispatched) on the same file this card's fix lands in — packages/spec/src/data/hook.zod.ts. Same-file claims serialize strictly across rounds, no exception.

Recorded for the dispatch that picks this up after unlock (deferring is not shelving):

1. Triage's stale-premise pass already re-anchored the engine line numbers: engine.ts:5529→5530 (beforeUpdate) and :6150→:6165 (beforeDelete) at 44106d9; re-verify at dispatch time.
2. The core sentence pair to preserve (from triage, do not simplify away): hooks cannot see the composed ast (middleware may narrow it with RLS/sharing), hooks CAN see the caller's raw options.where; middleware only narrows, so treating the caller predicate as the row set is an upper-bound approximation — the safe direction for fail-closed guards.
3. The positive pin goes in hook-input-shape-contract.test.ts (NOT hook.test.ts, which the in-flight sweep sweep(spec-surface): 5-item description-surface truth sweep — one claim, one PR, per-item checklist review (#6085 #6081 #6137 #6065 #5676) #6243 touches at :422).
4. This card is target:v17; it outranks non-board cards the moment it unlocks.

---

Generated by Claude Code