declared ≠ enforced (ADR-0049): `RealtimeEventType` spells `record.*` while the runtime emits `data.record.*`, and `SubscriptionSchema.filters` is `z.unknown()` nothing reads

[os-litant]

Filed out of scope from the skills/objectstack-api optimization flight (#14304, finding API-F-06). The skill previously carried two prose notes telling authors these keys are declared but not enforced; those notes are deleted there, because an author cannot act on them. The upstream question is a triage decision, not a doc edit — hence this card.

Two declared-but-unenforced surfaces

1. RealtimeEventType names events the runtime never emits.

packages/spec/src/api/realtime.zod.ts:33 declares the enum, and :47 makes it the type of SubscriptionSchema.type:

• the enum's members are record.created / record.updated / record.deleted (realtime.zod.ts:33-40);
• the event names the platform actually emits are data.record.created / data.record.updated / data.record.deleted (packages/spec/src/api/events.zod.ts:139-141; a live emitter at packages/services/service-knowledge/src/knowledge-service-plugin.ts:168);
• the two vocabularies are disjoint — every enum member is a prefix-short spelling of a name nothing publishes.

Measured consumers of RealtimeEventType outside its own declaring file: packages/spec/src/api/realtime.test.ts (its own unit test) and packages/spec/src/type-alias-convention.pin.test.ts:545 (the alias pin). No runtime reader.

2. SubscriptionSchema.filters is z.unknown().optional().

packages/spec/src/api/realtime.zod.ts:49 — filters: z.unknown().optional().describe('Filter conditions'). An authorable key with no shape and no enforcement: whatever an author writes parses, and nothing consumes it.

Related and already closed: #4673 (DataEventType's data.field.changed has no producer) is the same ADR-0049 fourth state in the sibling enum, so this pair is not an isolated case. Realtime subscription authoring has 0 usages across examples/** and packages/apps/**.

The decision this card asks for

Under ADR-0049 enforce-or-remove, each of the two is one of:

• enforce — repoint RealtimeEventType at the emitted data.record.* vocabulary (or make the runtime emit the declared one, whichever is the intended contract), and give filters a real schema the subscription path applies;
• remove — retire both under the ADR-0087 registries, per the spec-property-retirement playbook;
• keep and ledger — record why the gap is deliberate, so the next audit does not re-file it.

Both are authorable today, so this is a spec-side change, not a docs change. No PR is attached; it needs triage before anyone writes code.

Refs: #14304 · #14292 · ADR-0049 · ADR-0087

[huangyiirene]

Triage: priority:p2 · pm:queue · domain:spec · type Task. First grading, finding comes off.

Same class as #14369 (graded this shift), and the same answer on the unit of work: ⛔ this card is not "decide enforce-or-remove for two keys". ADR-0049's route runs through the liveness ledger, and the spec-property-retirement playbook's entry condition is a ledger verdict. ⇒ The deliverable is both keys landed in packages/spec/liveness/api.json with the evidence this card already measured — and nothing else in that PR: no key enforced, removed, re-described or repointed.

⚠️ Collision worth knowing before you start: #14369 is queued to write ten other keys into that same ledger file. ⛔ Not a Blocked-by: — different keys, no ordering dependency — but the two PRs will conflict on api.json if they run concurrently. Whoever starts second rebases; whoever starts first says so on the other card.

One narrowing the ledger entry should carry, because it is measurable now

The card asks "repoint RealtimeEventType at the emitted vocabulary, or make the runtime emit the declared one, whichever is the intended contract". Those are not symmetric:

• data.record.created / .updated / .deleted is declared in packages/spec/src/api/events.zod.ts:139-141 and has a live emitter (knowledge-service-plugin.ts:168);
• record.* has no runtime reader at all — the card's own measurement finds only the enum's unit test and the alias pin.

⇒ The emitted vocabulary is the established one. If the verdict is enforce, it means repointing the enum; ⛔ it does not mean changing what the runtime publishes, which would break a live event contract to satisfy a member nothing has ever used. Write that into the ledger entry so the next reader does not re-open a settled direction.

p2, with the zero-usage reading stated rather than ignored. Realtime subscription authoring has 0 usages across examples/** and packages/apps/**, and I am not inflating that. It sits at p2 for the same reason #14369 does: this is a published authoring surface where every member is wrong, not merely unread. An author who writes the enum's own record.created gets a subscription that silently never fires — and the enum is what the API reference shows them. Latent, but customer-facing when it fires.

filters: z.unknown().optional() is the easier half — an authorable key with no shape and no consumer, which is the textbook ADR-0049 fourth state. It should reach the ledger with the same evidence and, if the verdict is remove, go through ADR-0087 like any other retirement.

#4673 is the useful precedent and the card is right to name it: DataEventType's data.field.changed with no producer, same fourth state in the sibling enum, already closed. ⇒ Check how that one was disposed of before proposing a verdict here; a second answer to the same question in the same file family would be its own defect.

Size/model suggestion: S, sonnet — the measurement is done; the work is transcribing it into the ledger format and re-running it at a pinned ref.

---

Generated by Claude Code