declared ≠ enforced:DataEventType 的 data.field.changed 全仓没有生产者(ADR-0049 第四态)

[os-zhuang]

从 #4639 的裁决中拆出(明确不做 #4639 的 rider),unassigned。

现象

packages/spec/src/api/events.zod.ts 的 DataEventType 声明四个值:

export const DataEventType = z.enum([
  'data.record.created',
  'data.record.updated',
  'data.record.deleted',
  'data.field.changed',   // ← 无生产者
]);

全仓 grep data.field.changed 只有三处出现:上面这行、packages/spec/src/api/events.test.ts、以及文档 content/docs/references/api/events.mdx。没有任何代码发出它——ObjectQL engine 的 publishDataEvent / publishBulkDataEvent 只发 data.record.{created,updated,deleted} 与(#4639 起)data.records.{updated,deleted}。

content/docs/references/api/realtime.mdx 自己已经承认了这件事:

not yet enforced — the runtime emits data.record.* event names instead, and field.changed is never emitted; see #3197

这是教科书式的 ADR-0049 第四态(parsed / unmarked / unenforced),同族 #3197。

处置方向(ADR-0049 enforce-or-remove 三选一)

1. 实现:在 engine 的 update 路径按 changes 逐字段发 data.field.changed。要先回答值不值:逐字段事件在宽表上是一次写入 N 条事件,且现有 DataEvent 的 schema 没有 field / oldValue / newValue 字段可承载它——真要做需要自己的 schema(参照 declared ≠ enforced:引擎 multi:true 谓词写入没有 data.record.* 事件,webhook / 知识同步对其静默(REST 批量端点不受影响) #4639 给批量写单独立契约的做法)。
2. 标 experimental:仅当确实打算近期实现。
3. 移除:从 DataEventType 删掉。按 .claude/skills/spec-property-retirement 走完整套件(ADR-0087 转换层、liveness ledger、生成基线、文档、pin 测试),别手工重建。

倾向 3:没有需求方,DataEvent 的形状也不适合承载逐字段语义;真需要时按 #4639 的先例新立一个诚实的契约,比让一个空 enum 值占着位置强。

参考

• ADR-0049 docs/adr/0049-no-unenforced-security-properties.md — 三态与被禁的第四态
• Audit: several event/subscription/connector enums are schema-only (declared, no runtime consumer) #3197 — 同族(realtime 声明与运行时不符)
• declared ≠ enforced:引擎 multi:true 谓词写入没有 data.record.* 事件,webhook / 知识同步对其静默(REST 批量端点不受影响) #4639 — 相邻裁决,把"批量写没有合规事件"从伪造/静默改成独立契约

[os-zhuang]

认领 (claim)

• session id: session_01LYnZrTwXbrctB8E8HpJAPT
• branch: claude/issue-4673-retire-data-field-changed
• 处置方向: 按维护者裁决走路线 3 — 移除(ADR-0049 enforce-or-remove)。

开始前已复读本 issue 的全部评论,未发现来自其它 session 的在先认领。

预期改动范围:从 packages/spec/src/api/events.zod.ts 的 DataEventType 删除 data.field.changed,更新 packages/spec/src/api/events.test.ts,重新生成 packages/spec 的生成物与 content/docs/references/ 下的自动生成文档,清理手写文档中的残留提及,并补一个说明 FROM → TO 的 changeset。

注意与在途 PR #4677(claude/bulk-write-missing-events-sm1i4b)同文件相邻改动,本分支从 origin/main 切出,diff 仅限本次移除。

---

Generated by Claude Code