finding(spec): EventNameSchema's only three binding schemas have no runtime consumer — the live event vocabulary is a closed enum that never touches it

[os-warren]

Observed while running the per-surface identifier census for #12245. Filed unassigned as a finding, not a defect claim.

What was observed

EventNameSchema (packages/spec/src/shared/identifiers.zod.ts) is bound by exactly
three schemas, and by nothing else in either repository:

Binding	Site	Runtime consumer?
EventTypeDefinitionSchema.name	kernel/events/core.zod.ts:94	none
EventSchema.name	kernel/events/core.zod.ts:122	none
EventMessageSchema.eventName	api/websocket.zod.ts:299	none

Reproduced on origin/main at e2debee6: outside kernel/events/core.zod.ts and
api/websocket.zod.ts themselves, every reference to those three names is a generated
baseline (api-surface/*.json), the file's own test, type-alias-convention.pin.test.ts,
CHANGELOG.md, or V3_MIGRATION_GUIDE.md. No plugin, service, driver, or app parses
through any of them.

What the platform actually validates event names with is a closed literal enum that
does not reference EventNameSchema at all — packages/spec/src/api/events.zod.ts:

export const DataEventType = z.enum([
  'data.record.created',
  'data.record.updated',
  'data.record.deleted',
]);

export const BulkDataEventType = z.enum([
  'data.records.updated',
  'data.records.deleted',
]);

grep -c EventNameSchema packages/spec/src/api/events.zod.ts returns 0.

The sibling free-text surface is unconstrained rather than schema-guarded:
WebSocketEventSchema.channel is a bare z.string() (api/websocket.zod.ts:468) whose
own describe() documents "record.account.123" and "user.456" as legitimate channel
spellings.

Why it may matter

EventNameSchema is presented as the platform's event-name grammar — the docblock on
SystemIdentifierSchema lists "Event keys" among the surfaces it governs, and
EventNameSchema carries its own worked examples. In practice it governs nothing that
runs: the real vocabulary is closed and enumerated, and the one open event-ish surface
(channel) opted out into z.string().

That makes it the ADR-0049 declared-but-unenforced shape, with the usual consequence for
AI-authored metadata: a generator that reads EventNameSchema and emits an event name
satisfying it has satisfied nothing the platform will check, while a generator that emits
anything outside the closed enum is refused by a rule the identifier file never mentions.

Two routes, neither obvious and neither recommended here:

1. Bind it — have the open event surfaces (starting with channel, and any future
   custom-event registration) run through EventNameSchema, making the declared grammar
   the enforced one.
2. Retire it under ADR-0049 enforce-or-remove, and let DataEventType /
   BulkDataEventType stand as the only event-name contract. This is a published-export
   removal, so it takes the ADR-0087 conversion.

Recording the measurement only; sizing and the route are a maintainer call.

Related: #12245 (the census that surfaced this) · #4673 (the same class, on
DataEventType's retired data.field.changed member) · ADR-0049.

[os-warren]

分诊定级 → domain:spec · needs-user-decision · p3 · tooling。摘 finding。

锚定。 packages/spec/src/shared/identifiers.zod.ts 及两条路线的落点(kernel/events/core.zod.ts · api/websocket.zod.ts · api/events.zod.ts)全在 packages/spec ⇒ domain:spec。

为什么交你裁。 ADR-0049 已经把原则定死(声明而不强制的必须强制或移除),所以要裁的是路线,而两条都动公共契约:路线 1(绑定 channel 等开放事件面)是 accept 集收窄;路线 2(退役)是已发布 export 的移除,须走 ADR-0087 conversion。⛔ 分诊不代裁。

定级 p3:无行为缺陷、无错误答案上线。危害在 ③ 轴且是真的 —— 一个读 EventNameSchema 并据以生成事件名的 generator 满足了一个平台根本不检查的东西;而它若生成闭合枚举之外的任何名字,会被一条 identifier 文件从未提及的规则拒收。两个方向都误导,这是比单纯「死代码」更贵的形状。

⭐ 与 #13612 是同族,建议同一次裁决一并给方向 —— 但不要合卡

三张卡出自同一次 #12245 普查,是同一种病的三个面:

卡	形状	本轮处置
本卡	EventNameSchema 有三个绑定 schema,但那三个零运行期消费者	needs-user-decision p3
#13612	六个 branded identifier 零绑定(+ 评论补的三个「绑定了但被绑定方无读者」)	needs-user-decision p3
#13621	SystemIdentifierSchema 散文声称覆盖 11 个面,实测只绑 1 个	已入队 pm:queue p3(纯散文更正,零 accept 集变更)

⇒ 裁 #13612 与本卡时,同一句「bind 还是 retire」可以覆盖两张,省你一次上下文切换。

⛔ 但两张不合并,因为 bind 路线的爆炸半径完全不同:#13612 的绑定会改 object name / field name 的 accept 集(内联正则允许前导下划线,SnakeCaseIdentifierSchema 不允许 ⇒ 存量元数据可能被拒);本卡的绑定动的是 WebSocketEventSchema.channel(今天是裸 z.string())⇒ 收窄一个从未被约束过的自由文本面,风险与代价都是另一回事。一句方向、两张各自评估半径。

⚠️ 若裁 #13612 或本卡走 bind,#13621 的散文更正要跟着改(它现在的任务是「把散文写成今天的真相」;绑定会改变那个真相)。⇒ #13621 应排在两张裁决之后,或明确写成「按裁决后的绑定状态落笔」。本卡与 #13612 的评论里都记了这一条。

派单/裁决时手上要有的三个读数(已复核口径,origin/main @ e2debee6)

1. 三个绑定站点 —— EventTypeDefinitionSchema.name(kernel/events/core.zod.ts:94)· EventSchema.name(:122)· EventMessageSchema.eventName(api/websocket.zod.ts:299),三者均无运行期消费者;
2. 平台实际校验事件名用的是闭合字面量枚举 —— DataEventType / BulkDataEventType(api/events.zod.ts),且 grep -c EventNameSchema packages/spec/src/api/events.zod.ts = 0;
3. 唯一开放的事件类面 WebSocketEventSchema.channel(api/websocket.zod.ts:468)是裸 z.string(),其 describe() 自己举的合法拼法是 "record.account.123" / "user.456" —— ⚠️ 这两个例子是否满足 EventNameSchema 的文法,是 bind 路线的第一道判据,裁决前值得实测一次,否则「绑定」可能当场拒掉平台自己文档里的示例。

Refs:#12245(普查)· #4673(同类,DataEventType 已退役成员 data.field.changed)· ADR-0049。

---

Generated by Claude Code

[os-sam]

⚖️ RULED — maintainer, 2026-09-01, director decision batch C, verbatim 「同意」: retire

EventNameSchema and its three bindings (EventTypeDefinitionSchema.name, EventSchema.name, EventMessageSchema.eventName) are retired under ADR-0049 enforce-or-remove (ADR-0087 conversion; launch-window changeset grade). The closed literal enums (DataEventType / BulkDataEventType) stand as the only event-name contract — they are what the platform actually checks, and the event surface is platform-defined, not author-extensible, so a grammar layer for a hypothetical extension surface is a trap, not a reserve. WebSocketEventSchema.channel stays a deliberate z.string() until real pull says otherwise — ⛔ this ruling adds no constraint there.

Family-dispatch note: pairs with #13612 (same class, same playbook, same lane) under the five-gate family rule.

State transition in this same pass: needs-user-decision → pm:queue. domain:spec lane; Clause-② path limb fires — contract-review tier at dispatch.

---

Generated by Claude Code