spec 契约:multi:true 批量更新上 beforeUpdate 的 per-row 载荷可变语义(#5574 裁决 B 的 contract-first 前置)

[baozhoutao]

#5574 的维护者裁决(2026-08-06 两级批复:裁决评论 + 全舰队决策箱「同意」)选定方案 B —— 把「批量写按行语义为平台契约」(#4800/#4862 既有裁决,after 侧已由 #5038 交付)延伸到 before 型 hook,并明确 contract-first 拆分:spec 契约子单先行,engine 实现随后。本单即该 spec 半边,由 engine-core 席按裁决的拆分指令代立;domain 标签交分诊落(预期 domain:spec)。

本单要定形的(裁决必答项映射)

1. per-row 载荷可改写语义:multi: true 批量更新逐行派发 beforeUpdate 时,每行 hook 拿到 per-row ctx.previous 与该行载荷 —— 需定:hook 改写载荷的合法面(哪些改写生效、作用域是否仅限本行)、N 行各自改写后与「一份谓词 payload」原形的关系(分叉合并规则)、ctx.result 形状、与单行路径的等价性声明。
2. 预算护栏的契约面:assertBulkPerRowHookBudget 先例的 spec 级表述(上限、超限行为);engine 侧复用已取的 priorRows、⛔ 不二次取数(裁决原文)。
3. pin 测试落 packages/spec,与 after 侧按行契约([17.x] 批量写按行语义实现:hook 按行触发 + record-change trigger 按行绑定 previous/record(#4800/#4862 拍板 A) #5038)同口径对表。
4. 与 ObjectQL.update 的 data.id 不做标量测试 —— 载荷里的算子对象被当成主键绑定,且盖过显式 options.multi: true #5748 同写 bulk-write ADR 附录(裁决指定)。

流程与下游

• 按裁决:PM 复核、维护者否决窗口。
• engine 实现半边(engine-core 席)Blocked-by 本单,spec 定形落地后由该席派发;届时与同接缝卡 单 id update 把同一行前置状态读了 3 次(engine 前置行门 + sys_fetch_previous_update + plugin-audit captureBefore),且后两次不受任何按对象需求门约束 #5846(单 id 三读前置行,其 (a) 方向 = 前置读移到 beforeUpdate 之前并绑定)统一编排,避免同一时序被改两次。
• 下游解锁:hotcrm#779(Blocked-by beforeUpdate hook 在 multi:true 批量更新上拿不到 ctx.previous —— sys_fetch_previous_update 依赖 input.id;引擎已为校验取 priorRows 却不喂 hook(17.0.0-rc.2) #5574)。

Refs:#5574(裁决与实测证据)、#4800 / #4862(after 侧既有裁决)、#5038(after 侧交付)、#5748(ADR 附录同伴)、#5846(同接缝编排)。

[claude]

Triage: pm:queue + domain:spec + target:v17. Not needs-user-decision — the decision is already made, twice.

Why the queue and not the maintainer's inbox. #5574 carries a two-level ruling: the 2026-08-06 08:29Z verdict selecting option B (extend the per-row bulk-write contract to before-type hooks), then the 10:36Z landing comment recording the maintainer's 「同意」 on the fleet decision-box report, with the implementation must-answer list attached. That ruling explicitly ordered this split: "contract-first 拆分——spec 契约子单先行 ... engine 实现随后". This card is that spec half. Sending an executed ruling back to the inbox is the #4829 failure mode (a made decision wearing a label that reads "still awaiting an answer"), so it goes to the queue.

Why domain:spec and not domain:spec-surface. The split criterion is the acceptance face, not the package and not the diff size: metadata legal before the change must be judged byte-identically after, or the card is domain:spec. This card defines per-row payload mutation semantics (which rewrites take effect, their scope, how N per-row rewrites reconcile against the single-predicate payload), the ctx.result shape, the assertBulkPerRowHookBudget contract face including over-limit behaviour, and new pin tests in packages/spec. That is behaviour, not describe/JSDoc prose — the reverse red line ("any card that changes accept/reject behaviour is domain:spec, however small") points the same way. Not domain:spec-tooling either: no gate, generator, lint rule or hand-written docs page is the subject.

Why target:v17. Its consumer #5574 is already on the release board, and correctly so — the measured harm is fail-open: on the multi: true path ctx.previous is permanently undefined, so all 15 hotcrm guard hooks written as previous?.x pass silently, and a batch write can set a readonly: true field to null where the single-row path would not. #5574 cannot be fixed without this contract landing first, so the blocking property propagates to the prerequisite. Board membership on a contract-first predecessor is not a second judgement; it is the same one.

Not blocked. This card is first in the chain — Blocked-by: belongs on the engine half, not here.

Duplicate check. Repo-scoped search over open issues for a spec-side card on before-hook per-row payload semantics returns nothing but #5574 itself and this card; #5748 (ADR appendix companion, named in the body) is closed, #5846 (same-seam single-id ordering) is open and distinct — it is the read-timing half, not the contract half. No convergence action needed.

One observation for the domain:engine-core seat (#6019) — flagged, not changed. #5574 currently reads pm:queue, unassigned, with no Blocked-by: line in its body, while its own 23:14Z comment states the engine half is Blocked-by this card. Batch selection reads labels and the body line, never the comment thread, so on the board #5574 looks dispatchable while its work is in fact gated on a contract that does not exist yet. The seat's stated intent ("本单保持 pm:queue 记账") is deliberate and is the lane's call on the lane's own card, so the triage seat has changed nothing there — but the accounting and the machine state currently disagree, and only the machine state is read at dispatch time.

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

---

Generated by Claude Code

[qq9340100]

认领:PM 循环轮 6(高并发常态化批次,第 4/5 单)
会话:session_011M7UwH25Unfi73UHim7ajY
分支:claude/issue-6462-bulk-before-update-contract
Worktree:objectstack-issue-6462
域:domain:spec
文件面:spec 数据 hook 契约面(beforeUpdate per-row 载荷可变语义定形 + assertBulkPerRowHookBudget 契约表述)、packages/spec pin 测试(与 #5038 after 侧同口径)、bulk-write ADR 附录、.changeset/。⛔ 不触 engine 实现(engine-core 席的后续半边)。越界即停,报告说明。

---

Generated by Claude Code