declared ≠ enforced:引擎 multi:true 谓词写入没有 data.record.* 事件,webhook / 知识同步对其静默(REST 批量端点不受影响)

[os-zhuang]

#4626(subscribeData/DataEvent 生产者履约)的范围外发现,按第十条军规立案,unassigned。

现象

DataEvent(@objectstack/spec/api)是逐记录契约:recordId 必填。但 ObjectQL 引擎的批量写路径拿不到记录标识:

• IDataDriver.updateMany / deleteMany 的契约返回值是 Promise<number>(受影响行数,见 packages/spec/src/contracts/data-driver.ts),没有行、也没有 id;
• 引擎 update() / delete() 的 options.multi = true 分支就走这两个方法。

#4626 之前,这两条路径各发一条伪造事件:payload: { recordId: '', changes, after: <受影响条数> }。它同时骗了两个仓内消费者——webhook auto-enqueuer 收到 recordId: '' 的一次投递,知识同步则把 {recordId, after} 这个信封当成记录写进索引。#4626 按契约优先(不在消费端容错、也不在生产端伪造)改成:批量写不发事件,并 warn 出声。

于是留下这个真实的能力缺口:

• multi: true 的更新/删除不再触发 webhook(此前触发一次,但内容不可用);
• 知识库 object source 对批量写不同步;
• subscribeData 订阅者看不到批量写。

处置方向(需裁决)

1. 逐记录扇出:批量写前/后按 AST 取一次匹配行(或让驱动 updateMany/deleteMany 返回受影响 id),对每行发一条合规 DataEvent。语义最正,但热路径多一次查询(或改驱动契约,涉及全部驱动)。
2. 新增批量事件类型:在 DataEventType 里声明 data.records.updated / data.records.deleted(带 object + matched 计数 + 可选的 where),让批量写有自己的诚实契约,而不是冒充逐记录事件。消费者(auto-enqueuer / 知识同步 / client SDK)按新类型分别处理。
3. 维持现状:批量写没有实时事件,文档写清楚(client realtime declared ≠ enforced:subscribeData 回调把 RealtimeEventPayload 硬铸成 DataEvent,顶层 recordId/changes/id 运行时是 undefined #4626 已在 content/docs/automation/webhooks.mdx 写明)。

三条都要顺带回答:批量事件是否应进入 webhook 触发器词汇表(create/update/delete 目前是逐记录语义)。

参考

• client realtime declared ≠ enforced:subscribeData 回调把 RealtimeEventPayload 硬铸成 DataEvent,顶层 recordId/changes/id 运行时是 undefined #4626 / PR(生产者履约,把伪造事件换成"发不出就出声")
• packages/objectql/src/engine.ts — publishDataEvent() 的 "no record identity → no event" 闸门
• packages/spec/src/api/events.zod.ts — DataEventType / DataEventSchema

[os-zhuang]

PM 提级:转入维护者收件箱,且与 v17 发布直接相关。

#4626 的 PR(#4655)已按契约优先落地"批量写发不出合规事件就不发、并 warn 出声",取代了此前 recordId: '' / after: <条数> 的伪造事件。方向是对的——旧事件任何遵守 schema 的消费者都必须拒绝,而 webhook enqueuer 里那条 ?? 'unknown' 兜底会把一条指代不明的记录变成一次真实投递。

但它留下的是一个用户可感知的能力缺口,且会随 v17 一起发出去:

• multi: true 的 updateMany / deleteMany 不再触发 webhook;
• 知识库 object source 对批量写不再同步;
• subscribeData 订阅者看不到批量写。

这不是纯正确性修复,是一次取舍:诚实但缺失 vs 有但在说谎。集成方若依赖批量写触发 webhook,升级到 v17 后会静默失去这条通路(内容此前本就不可用,但"有一次投递"和"零投递"对下游是不同的事)。

因此需要维护者定两件事:

1. v17 是否接受这个缺口发布——若接受,它应当进 v17 release notes 的 breaking 段落,而不是只躺在 changeset 里;
2. 三条出路选哪条(正文已列):逐记录扇出 / 新增诚实的批量事件类型 data.records.* / 维持缺口只写文档。

倾向 2:两轴同向——长远上批量写本来就不是逐记录语义,硬扇出要么加热路径查询、要么改动全部驱动的 updateMany 契约;防 AI 犯错这条上,给批量写一个自己的事件类型,比让它冒充逐记录事件更难被误用(消费者拿到 data.records.updated 就知道没有 recordId 可用,而不是拿到一个 recordId 为空串的"逐记录"事件)。

定了我立即安排;若选 1 或 3,也请一并确认 v17 release notes 的措辞由发布流程统一编写(按仓库规矩,代码 PR 不碰 content/docs/releases/)。

---

Generated by Claude Code

[os-zhuang]

状态更新:PR #4655 已合并(14:43:30),本 issue 描述的缺口现在在 main 上。

我曾撤下该 PR 的自动合并并转回 draft 以等待此处的裁决,但它已排在合并队列前端,队列照常完成合并——扣留未生效。因此裁决顺序被颠倒了:代码先落地,决策还没做。

这不改变需要裁决的内容,只改变了各选项的成本:

• 出路 3(维持缺口 + 写文档):现在是零改动的默认路径,但需要确认它进 v17 release notes 的 breaking 段落——否则集成方会在升级后静默失去批量写的 webhook 通路;
• 出路 2(新增诚实的 data.records.updated/deleted):仍是我的推荐,但现在是追加一个事件类型而非替换伪造事件,改动面比裁决前更小、更安全;
• 出路 1(逐记录扇出):成本不变(热路径多一次查询,或改全部驱动的 updateMany/deleteMany 契约返回受影响 id)。

另外附带一条与本 issue 相邻的债:#4655 正文声称做了写路径热路径开销实测,但那条数据从未贴出(agent 被容器重启杀掉)。也就是说每事件新增的 uuid + DataEventSchema.parse 开销目前无实测支撑,已记在 PR 上。

---

Generated by Claude Code

[os-zhuang]

维护者裁决

先更正一处范围误述——本 issue 标题与正文说的"批量写完全静默"不成立，会让集成方高估影响一个量级：

• POST /data/:object/createMany / updateMany / deleteMany / batch 这些 REST 批量端点照常逐记录发事件。它们在 packages/metadata-protocol/src/protocol.ts:5498-5729 早已被改写成逐记录循环调引擎单条路径(deleteManyData 把请求体的 options 展开在 where 之后 —— body 可覆盖 id 谓词,把"删这几条"放大成"删调用者可见的全部" #3897 / data: PATCH/DELETE of a nonexistent record answer 200 success instead of RECORD_NOT_FOUND #4435,即 ADR-0118 "诚实批量" 的先例),webhook 与知识同步对它们不受任何影响。
• 真正静默的只有引擎级 multi: true 谓词写入(engine.ts:4419 / :4739 → driver.updateMany/deleteMany)。它的实际可达面是:沙箱脚本 (quickjs-runner.ts:518 把 updateMany/deleteMany 暴露给用户代码)、保留期回收 (lifecycle-service.ts:723 按谓词 reap)、sharing 批量撤销、settings 复合键回退、messaging outbox 内部表。

另外需要记在裁决里的一条事实:audit 与 record-change 触发器走的是 ObjectQL hooks,hooks 明确覆盖 bulk(engine.ts:91-105,#3195)。所以今天批量写有 audit 行、有触发器,只是事件通道(webhook / KB / subscribeData)看不见。这条不对称此前是"碰巧如此",裁决把它转为显式分层:hooks = 进程内全保真;events = 逐记录契约 + 批量摘要。

裁决

采纳出路 2(新增诚实的批量事件类型),并附三项配套。

1. v17 按现状发布,缺口进 release notes 的 breaking 段落。
措辞必须写准范围:仅引擎 multi:true 谓词写入(沙箱脚本、内部后台任务)不发事件;REST 批量端点不受影响,逐记录事件照发。按仓库规矩,该段由发布流程统一编写,代码 PR 不碰 content/docs/releases/。

2. 主干落出路 2。
DataEventType 追加 data.records.updated / data.records.deleted,配独立 schema(不复用 DataEventSchema——recordId 必填的逐记录契约保持纯净),载荷 { id, type, object, matched, where?, userId?, timestamp }。引擎在两个 multi 分支发出。

webhook 触发器词汇表新增 opt-in 的 bulk_update / bulk_delete,不把批量事件并入现有 create/update/delete——让现有逐记录订阅者收到一个 count-only 的 body,是 recordId: '' 那种说谎的另一种形式,不能重蹈。

3. 知识同步单独配套——出路 2 救不了它。
一条只带 matched 计数的事件,KB 索引拿不到记录 id 也拿不到记录体,无法 upsert / 删除条目。而这里藏着比"webhook 少一次投递"更像真 bug 的东西:保留期回收按谓词删记录 → 零事件 → 知识库留下陈旧文档。处置:lifecycle-service.ts:723 直接学同文件 :782 已有的 per-id 先例做扇出(后台任务,无热路径顾虑)。KB 的周期性对账兜底另案讨论——事件管新鲜度,对账管正确性,比追求"每条事件都完美"稳健。

4. data.field.changed 另案退役,不做本 issue 的 rider。
declared-never-emitted,全仓只有 spec、其自身测试和文档三处出现,教科书式 ADR-0049 第四态(#3197 族),走 spec-property-retirement 流程三选一。

未采纳的理由

• 出路 1(逐记录扇出):两条实现路都贵——热路径前置查询等于消灭 multi:true 这个 fast path 的存在意义;改 IDataDriver.updateMany/deleteMany 返回受影响 id 是全驱动的破坏性契约变更(还要过 ADR-0087)。且 REST 层已事实上做了扇出,全量做出路 1 约等于主张"引擎不该有谓词批量写",那是另一个更大的裁决。
• 出路 3(维持缺口):已是零成本默认(warn + 文档 + pin 测试俱在),作为 v17 的发布姿态可接受,但作为长期状态不行——retention reap 导致的 KB 陈旧会持续累积,沙箱脚本用户的批量写永远静默。

附带的债

#4655 正文声称的写路径热路径开销实测(uuid + DataEventSchema.parse)数据从未贴出。不阻塞本裁决,但出路 2 的实施 PR 应把它补上。

---

Generated by Claude Code

[os-zhuang]

认领并开工(裁决第 2 条 + 第 3 条)。

• session: session_01LYnZrTwXbrctB8E8HpJAPT
• branch: claude/bulk-write-missing-events-sm1i4b

本 PR 范围:spec 新增 data.records.updated / data.records.deleted 与独立 schema、引擎两个 multi 分支发出、webhook 词汇表新增 opt-in bulk_update / bulk_delete、消费端(auto-enqueuer / 知识同步 / client)分别处理、lifecycle-service.ts:723 retention reap 改 per-id 扇出,附热路径实测。

不在本 PR:release notes(发布流程统一编写)、data.field.changed 退役(另案)、KB 周期性对账(另案)。

---

Generated by Claude Code

[os-zhuang]

裁决更正:实施中发现两处必须偏离原文

实施到代码里之后,原裁决有两条站不住,记在这里,免得后来人按裁决正文去改。

1. 事件不带 where(原裁决写了 where?)

原裁决的载荷写的是 { id, type, object, matched, where?, userId?, timestamp }。where? 必须拿掉——发布时手上唯一的谓词是中间件合成后的 AST:

engine.ts 的两个 multi 分支消费的是 opCtx.ast,而按 #2982,这个 AST 里已经注入了安全层的行级作用域(RLS 写过滤器、sharing 的 editable-rows 过滤器)。把它放进事件,就等于把租户作用域内部结构发到 webhook 指向的任意外部 URL 上。

退一步用调用方合成前的 options.where 也不行:那是对"这次写入影响了什么"的第二个、且与实际执行不一致的答案——正是 PD #12 说的第二套事实。

所以事件只说它能如实说的那件事:object + matched。理由写进了 BulkDataEventSchema 的 TSDoc 和一条 pin 测试(does NOT carry the query predicate),免得以后有人"顺手补全"。

2. 没有改 retention reap 的 per-id 扇出(原裁决第 3 条),它撞 ADR-0057

原裁决让 lifecycle-service.ts:723 学同文件 :782 的 per-id 先例。读了 ADR-0057 才发现这条不能做——§3.3 有硬规则:

the LifecycleService's own deletes/rotations are not audited or activity-logged (otherwise cleanup re-feeds the tables it is draining — the same self-audit trap ADR-0052 already guards). Aggregate one summary row at most.

逐记录扇出正是该规则禁止的形态。而且 :782 的 per-id 并不是"先例"——它在 guardedReap 里,理由是级联删除(filter-delete 会绕过 cascadeDeleteRelations),不是为了发事件。我把两者混为一谈了。

按 PD #13,推翻已记录的决定需要新 ADR,不是一个 changeset 悄悄反着来。所以没做。

好消息是聚合事件恰好合规:一次谓词删除发一条 data.records.deleted,正是 §3.3 说的 "aggregate one summary row at most"。

知识库的陈旧问题因此改由对账解决,已立 #4672(事件管新鲜度,对账管正确性)。本 PR 里知识同步收到 data.records.* 会打 warn 指明索引可能陈旧且无法从事件流自愈——出声不是修复,但比静默强。

3. 顺带定的一条:matched === 0 不发事件

谓词没匹配到行 = 没有数据变更 = 不是数据事件(逐记录路径同理:没写入就没事件)。否则每小时的 lifecycle sweep 会给每个对象发一条 "0 records" 的 webhook。

---

另外:本 issue 标题的"完全静默"确实夸大了,已更正

补一条实测的范围佐证:今天真正静默的 multi:true 可达面是沙箱脚本(quickjs-runner.ts:518)、保留期回收、sharing 批量撤销、settings 复合键回退、messaging outbox 内部表。REST 的 createMany/updateMany/deleteMany/batch 全部逐记录发事件,不受影响。

#4655 的实测债已还

packages/objectql/src/engine-data-events.bench.ts。内存驱动下每条事件约 7–9µs(insert 0.021ms vs 0.012ms;单 id update 0.013ms vs 0.007ms)。批量写每次写入只付一次,与匹配行数无关(100 行匹配集:0.040ms vs 0.034ms),所以匹配集越大相对开销越小。

第一版 benchmark 是错的,记一下免得重犯:三组用例共享同一对引擎,而 vitest 按墙钟跑而非固定迭代数,快的那侧多跑了近一倍迭代、往表里插了近两倍的行;结果谓词写那组报出"开事件反而更快"(其实是关事件的引擎要扫 84k 行 vs 47k 行)。改成每组用例独立引擎对、且谓词过滤的列不被自己写入,数字才自洽。

---

Generated by Claude Code