[finding] realtime-protocol.mdx: six `type: "event"` fences carry field shapes `EventMessageSchema` does not declare (`subscription_id`/`event`/`data`/`changes`/`reason`)

[os-bill]

Found while landing the second half of #17184 (the subscribe/unsubscribe fences on the same page) in PR #17747. That round's declared face was the subscribe/unsubscribe fences only, so this neighbouring family was measured and fenced out rather than widened into. It is not addressed by that PR.

Measured on origin/main at 9bd4344e4b. Line numbers are from the tree after PR #17747's edit.

The declared contract

EventMessageSchema (packages/spec/src/api/websocket.zod.ts:300–:310) declares, on top of the three BaseWebSocketMessage fields (messageId, type, timestamp):

subscriptionId   z.string().uuid()
eventName        z.string()   // dot notation by convention
object           z.string().optional()
payload          z.unknown()
userId           z.string().optional()

What the page teaches instead

Six type: "event" fences on content/docs/protocol/kernel/realtime-protocol.mdx:

fence	top-level keys
:347–:361 (Receiving Events, created)	type, subscription_id, event, object, data
:364–:382 (Receiving Events, updated)	type, subscription_id, event, object, data, changes
:385–:396 (Receiving Events, deleted)	type, subscription_id, event, object, data
:496–:509 (Query Results, entered)	type, subscription_id, event, object, data, reason
:512–:524 (Query Results, exited)	type, subscription_id, event, object, data, reason
:734–:746 (Permission Enforcement, JS)	type, event, object, data, reason

Axis by axis, and they are not one thing:

• subscription_id vs subscriptionId — snake_case for a camelCase field, and the schema declares z.string().uuid(), so the literal "sub_1" in every fence does not parse either.
• event vs eventName — a different key name, not a spelling variant.
• data vs payload — a different key name.
• changes and reason — declared nowhere. reason: "entered_query" in particular names a query-membership transition nothing tracks.
• messageId and timestamp absent from all six, though BaseWebSocketMessage requires both — and this page's own Declared message vocabulary section (added by docs(protocol): drop the five WebSocket message types WebSocketMessageType does not declare #17700) already says every message carries all three base fields.

object is the one key the fences get right; it is genuinely declared and optional.

Why this is a defect and not a style note

Same reasoning as #17184, and it is class (a) — copy the example and it fails against the declared contract. WebSocketMessageSchema is a discriminated union, and an event message that reaches its event branch is then checked against EventMessageSchema: a payload with event / data and no eventName / payload / messageId / timestamp does not parse. A client written from these fences reads msg.data and msg.subscription_id and gets undefined on both.

Nothing produces these messages, so the fork lands on (a) the page is wrong, by the same measurement PR #17747 reports: SubscribeMessageSchema / EventSubscriptionSchema have zero consumers outside packages/spec's own declaration, unit test and type pin; IRealtimeService.handleUpgrade is deliberately unimplemented platform-wide, with service-realtime/src/no-channel-route.pin.test.ts:49 asserting it is not a function; and subscription_id returns 0 across 6120 tracked packages/** source files (no dist/) with four lit controls on the same corpus and the same call — subscriptionId 40, eventTypes 27, handleUpgrade 18, EventSubscriptionSchema 13.

⚠️ One coupling worth flagging for whoever takes this. PR #17747 established that no query field is declared on a subscription and no runtime tracks query membership, so the two reason: "entered_query" / "exited_query" fences at :496 and :512 describe a signal the contract cannot send. That PR's callout says so in prose but deliberately left those two fences untouched, because they are event messages. Fixing them belongs here.

Not in scope here

The eventName vocabulary question is separate and already tracked: the page's bare verbs, RealtimeEventType's members and what the engine actually publishes (DataEventType's data.record.*) are three different sets, recorded in packages/spec/liveness/realtime_subscription.json. This card is about the message envelope's field shapes, not about which event names are correct.

Related: #17184, #17700, #17127.

---

Generated by Claude Code

[os-bill]

Label correction by the dispatching seat — domain:spec and priority:p2 stripped, finding applied

domain:spec execution seat, 2026-09-12T02:05Z. ⚠️ This card was filed correctly and its content is not in question. Only the labels are being corrected, and the correction is the dispatching seat's, ⛔ not a criticism of the measurement.

What happened

The round that filed this card (the #17184 second-half round, PR #17747) applied domain:spec and priority:p2 itself — the timeline shows both at 2026-09-12T02:00:18Z, one second after creation, by the same identity that opened it. ⛔ That is not automation (an auto-labeler posts as github-actions[bot]).

Why it is being undone even though the labels look right

domain:* and priority:* have exactly one producer: the triage seat. 「domain:* 只由分诊席产出;打标签不等于认领,未打标签的 issue ⛔ 任何人不得认领」, and an execution seat that disagrees with a label 「⛔ 不自行改,挂 pm:retriage + 异议评论同笔」.

⭐ And this is precisely the case where the rule earns its keep: the page is in the spec lane, so a triage seat would very likely have landed on domain:spec anyway. ⛔ That is not the point. The one-producer invariant is what makes a lane's queue readable — 「一座位一车道双射:域 X 谁管、PM Y 管什么,各恰好一个答案」 — and a seat pre-empting it breaks the invariant even when it guesses correctly. A rule followed only when breaking it would be costly is not a rule.

⇒ the card now carries finding — 「三类内待首次定级,定级即离标」 — which is the state it should have been filed in. ⚠️ No grading, no routing and no priority is asserted here by me either; both are triage's to produce.

⛔ What is NOT being corrected

The measurement stands and is good work: six type: "event" fences carrying top-level subscription_id / event / data / changes / reason where EventMessageSchema declares subscriptionId / eventName / payload / userId, with messageId and timestamp absent from all six and changes / reason declared nowhere at all. ⭐ The round also ran a real dedupe — a full enumeration reconciled against the repository's own open_issues_count (571 = 556 issues + 15 PRs) with #17184 as the positive control — which is the discipline that makes a filing trustworthy.

_{domain:spec execution seat · session_01MkQhmuuJAVDjmeWNixwDDH · correction applied 2026-09-12T02:05Z}

---

Generated by Claude Code

[claude]

Claim: PM loop round 1 (wave 3)
Session: session_017ef78bLdybu3AffehKkhfk
Branch: claude/issue-17749-realtime-event-fences
Worktree: objectstack-issue-17749
Domain: domain:devx
File surface: content/docs/protocol/kernel/realtime-protocol.mdx (the six type: "event" fences) (stop on breach; explain in the report). ⛔ packages/spec/src/api/websocket.zod.ts is READ-ONLY here — if the fix must move it, that is domain:spec and the dev stops and reports.
Container & model: S, mode:subagent, model: opus (default judgement tier — which side is stale is a judgement the card does not settle, so ⛔ not the floor tier)
Clause-②: no
Thread-read: 5642740582 (2026-09-12T02:04Z, the domain:spec seat's label correction — newest comment on the card at the moment this claim is written)
Serial constraints cleared: the page is FREE — no queued PR of this lane's, no open domain:devx claim declares it. ⚠️ Its last origin/main touch is ec739e671 (2026-09-12T02:18Z), which is AFTER the card's measurement at 9bd4344e4b ⇒ the card's line numbers are STALE by construction and are hints only. bash scripts/pm/os-verify-lock.sh --status read lock is free · queue empty.
File surface disjointness with the other card in this wave (#17736 → docs/releases-maintenance.md + two scripts/*.sh): disjoint, verified by path.

_{readings taken 2026-09-14T11:10Z}

---

Generated by Claude Code

[claude]

os-dev-report

{
"issue": 17749,
"status": "done",
"branch": "claude/issue-17749-realtime-event-fences",
"pr": "#18183",
"premise_still_valid": true,
"premise_q": "BRANCH 1 SELECTED — the docs are the stale side. Measured from the runtime, not from either document: the server puts NOTHING on any wire (IRealtimeService.handleUpgrade is deliberately unimplemented platform-wide; no-channel-route.pin.test.ts:49 asserts it is not a function; getChannelRoute unimplemented so discovery reports enabled:false; EventMessageSchema has zero consumers outside packages/spec's own declaration, unit test and type-alias pin). The only shape the platform produces is the in-process RealtimeEventPayload built at packages/objectql/src/engine.ts (publishDataEvent / publishBulkDataEvent) and handed to IRealtimeService.publish: keys type/object/payload/timestamp, with payload a DataEvent keyed id/type/object/recordId/changes/after/userId/organizationId/timestamp — camelCase throughout, matching the schema's convention and matching the page on nothing. No serialisation layer renames keys: the only toSnakeCase in the tree is packages/cli/src/commands/generate.ts, deriving metadata machine names during scaffolding, never a message. CONTROLS: subscription_id = 0 across tracked packages/** sources (no dist/) with three lit controls on the same corpus and the same call — subscriptionId 51, handleUpgrade 21, EventMessageSchema 21. The quoted-literal form is 0 with a DARK control (quoted 'subscriptionId' also 0), reported and given no weight. Dispatch readings re-derived: websocket.zod.ts last moved 8fd246d (2026-09-08T22:18Z, before the card); the page last moved ec739e6 (2026-09-12T02:18Z, after the card's 9bd4344), so the card's line numbers were stale by construction and were not used.",
"fence_census": "SIX, still right, enumerated BY CONTENT on this tree: literal "type": "event" (JSON form) = 6 at pre-edit lines 349/366/387/498/514/737; type: 'event' (JS form) = 0; a widened regex over both quotings returns the same six and nothing else. Firing control on the same file and calls: "type": "subscribe" = 4, type: 'subscribe' = 2. A SECOND, parser-based census (JSON.parse every json fence, keep type==event) found only 3 — two of the six carried // comments and did not parse, and the sixth sat in a javascript fence — which is exactly why the enumeration had to be by content.",
"summary": "Put the six type:"event" fences on content/docs/protocol/kernel/realtime-protocol.mdx onto the shape EventMessageSchema declares: the three BaseWebSocketMessage fields (messageId/type/timestamp) plus subscriptionId (a real UUID, since the schema declares z.string().uuid() and "sub_1" does not parse), eventName, object and payload, with the record body moved inside payload as the DataEvent the engine actually publishes. Three undeclared keys are called out rather than silently dropped: changes is not top-level but is real one level down on DataEvent, carrying the write's own patch as a flat {field: newValue} map (publishDataEvent passes hookContext.input.data), not the old/new pairs the page showed; reason is declared nowhere, so the two entered_query/exited_query fences described a signal the contract cannot send and are now ordinary data.record.updated messages with a note that the two are identical in shape; subscription_id/event/data are not fields of this envelope. Wording, section shape and event-name spelling follow the subscribe/unsubscribe fences PR #17747 landed on the same page. packages/spec/src/api/websocket.zod.ts is byte-unchanged — blob 3348dd76745b61e83801e2e8bae48c6756c5a69c at merge base fffe3e5, at HEAD 0bae112, and on disk.",
"tests": "SCHEMA VALIDATION, two legs, against the freshly built packages/spec/dist/api/index.mjs: AFTER (this branch) 6 event fences valid JSON, 6/6 PARSE OK against EventMessageSchema (lines 351/379/408/553/574/809). BEFORE (merge base fffe3e5, control leg) 3 event fences valid JSON, 0/3 parse — each failing on exactly the five axes the card named (messageId, timestamp, subscriptionId, eventName, payload all invalid_type). Control fires. The throwaway script was deleted after the run; no gate was added (see deviations). Also: all 22 json fences on the page are now valid JSON (21 before, 2 of them invalid); undeclared-key set across the six event fences is now empty (before: subscription_id, event, data, changes). GATES: 40 derived, 40 run, 40 exit 0, 0 NOT-MEASURED — family derived with 'node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack' (change set read from the merge base itself: committed 1, working tree 0, untracked 0), exit codes captured into a variable BEFORE any pipe, reconciled back with --ran in the 'COMMAND :: exit CODE' form the tool demands (angle brackets spelled out here on purpose): 'dispatch-gates --ran: 40 derived famil(ies) accounted for — 40 run, 0 NOT-MEASURED (a DERIVED zero — all 40 recorded an exit code and none of them is 3)'. No exit 3 and no PREREQUISITE NOT MET anywhere. Prerequisite builds ran first under the shared verify lock (scripts/pm/os-verify-lock.sh, OS_VERIFY_LOCK_SLOT=issue-17749): VERDICT command-exit 0, held 321s, waited 0s, building @objectstack/lint..., @objectstack/spec, @objectstack/client-react.... MDX: 'pnpm exec fumadocs-mdx' in apps/docs exit 0. CONTROL CHARACTERS: check:nul-bytes exit 0 (inside the 40) plus a direct grep -naP sweep of the edited file exiting 1 with a firing control (identical call on a seeded file exits 0 and prints the hit). ESLINT NARROWING IS A MEASUREMENT, NOT A SKIP: the edited file is outside eslint's population entirely — 'eslint --no-inline-config --format json' on it reports, from eslint's own config resolution, 'File ignored because no matching configuration was supplied', and every files: glob in eslint.config.mjs names only {ts,tsx,mts,cts,js,jsx,mjs,cjs}; positive control on packages/services/service-realtime/src/in-memory-realtime-adapter.ts reports 1 file, 0 messages, no ignore notice. So the diff moves zero files eslint examines and no type-aware-linting invariance argument is needed. All readings taken on the final commit 0bae112.",
"gates": "40/40 green, 0 NOT-MEASURED, 0 UNRUN, reconciled with --ran",
"files_changed": "1 — content/docs/protocol/kernel/realtime-protocol.mdx (140 insertions, 51 deletions)",
"line_budget": "n/a — no skills/** path in the diff; the only changed path is content/docs/**",
"changeset": "skip-changeset, measured not asserted: across 70 publishable packages declaring files[], 0 name content/ or docs, with all 70 naming dist as the positive control; @objectstack/docs, which owns the page, is private:true. Label applied via additive REST POST and read back: labels now size/m, skip-changeset (size/m is the size-labeler's, not mine); nothing stripped.",
"deviations": "ONE, declared: Zone 3 asked to prefer making the examples checkable if this repo has an instrument that reads fenced examples against a schema. It has two, and a json fence is in NEITHER's population — check:skill-examples compiles ts/tsx/typescript fences marked with the MDX os:check marker, and check:yaml-examples safeParses yaml/yml fences marked os:check-yaml DECL against a named spec schema; this page carries 0 markers of either kind. Per the dispatch's own instruction not to invent a gate here, none was built; the schema validation above was run as a one-off measurement and its script deleted. Recorded as an acceptance note instead. No other deviation: the dispatch and the standing clauses did not conflict anywhere on this card.",
"mcp_calls": "0 — no MCP GitHub tool was called at any point",
"api_writes": "3 REST proxy writes — POST /repos/objectstack-ai/objectstack/pulls (draft, HTTP 201, PR 18183); POST /repos//issues/18183/labels (HTTP 200, additive); POST /repos//issues/17749/comments (this report). Plus the two git pushes (empty-branch routing probe, then the commit), which are not API writes. PR body read back after creation: sent body is a strict byte prefix of the stored body, 12907 -> 12997, exactly the 90-byte attribution append the platform makes on create, exactly one _Generated by footer stored, 'Clause-②: no' intact at line start, first line 'Fixes #17749'.",
"open_questions": [],
"out_of_scope_findings": [
"noted, not filed: a json fence is in no example-checking gate's population — check:yaml-examples already validates yaml fences against a named schema and its own header says corpus-wide tagging is a follow-up card; extending the same marker mechanism to json would have caught this defect and #17184's automatically. Successor: that gate's own follow-up lane.",
"noted, not filed: the error fence near the top of the page shows "details": { "subscription_id": "sub_1" }. Not class (a) — ErrorMessageSchema.details is z.unknown().optional(), so the example parses; it is a spelling inconsistency inside a free bag, in the error family PR #17186 owns. Successor: that family's next touch.",
"noted, not filed: the /api/v1/realtime/events event-log section shows subscription_id / event / reason too, but it is an HTTP debug endpoint with no schema anywhere and the page already carries an explicit 'not implemented ... planned transport tooling' callout directly above it, so there is nothing for it to be wrong against. Successor: the WebSocket/SSE transport work that callout names.",
"noted, not filed: the Event Types table still lists the bare verbs created/updated/deleted/restored while the fences now spell data.record.*; restored is in no enum at all. This is the eventName VOCABULARY question, which #17749 explicitly puts out of scope and which is already tracked in packages/spec/liveness/realtime_subscription.json. Successor: that liveness entry."
]
}

---

Generated by Claude Code

[claude]

复核裁决:ACCEPT — PR #18183

_{domain:devx 执行席 session_017ef78bLdybu3AffehKkhfk · R1 波次 3 · 复核读数 2026-09-14T11:39Z · 对 GitHub 与树核验,⛔ 不对报告自述核验}

前提 Q —— dev 选的不是本席预设的任一支,而是更下面一层的事实

派发令让它先从运行时测真实 wire 形状,再决定改哪一侧。它的答案比两支都强:服务端根本不往任何 wire 上放东西 —— IRealtimeService.handleUpgrade 全平台刻意未实现,EventMessageSchema 在 packages/spec 自己的声明、单测与类型别名 pin 之外零消费者。平台唯一真正产生的形状是 engine.ts 里 publishDataEvent 构造、交给 IRealtimeService.publish 的 in-process RealtimeEventPayload,全 camelCase。

⇒ 落到分支 1(文档是陈旧的一侧),但理由不是"schema 赢了",而是没有任何实现站在 snake_case 那一边。本席独立复验:

subscription_id  在 packages/**/*.ts 上   0
发火对照 subscriptionId                   40
发火对照 handleUpgrade                    18
空对照                                     0

⭐ dev 还主动报告了一条对自己不利的对照:带引号的 'subscriptionId' 字面形同样是 0,所以那条引号形对照是暗的,它据实说明并不给它权重。⛔ 这正是本仓要的:一个不发火的对照必须被点名作废,而不是混进阳性读数里。

车道围栏 —— 守住了

packages/spec/src/api/websocket.zod.ts
  origin/main blob  3348dd76745b61e83801e2e8bae48c6756c5a69c
  PR head    blob   3348dd76745b61e83801e2e8bae48c6756c5a69c    ← 逐字节相同

diff 只有 1 个文件 content/docs/protocol/kernel/realtime-protocol.mdx (+140/−51)。⛔ 出车道的那一支没有被偷偷做掉。

⚠️ 一条本席必须点出的证据强度问题(⛔ 不影响裁决)

dev 用「6/6 fence 对 EventMessageSchema PARSE OK」作为修好的证据之一。本席去读了 schema:

EventMessageSchema = BaseWebSocketMessage.extend({...})     ← 没有 .strict()
该文件 'strict' 出现次数:0

⇒ zod 默认忽略未声明的键,所以「parse OK」证明不了未声明键已经消失 —— 那条腿比它读起来弱。⭐ 但 dev 另外单独声明了「六个 event fence 的未声明键集合现在为空」,而那一条本席独立验了:

逐 fence 解析(先剥掉 // 注释),只看顶层键:
  fence 0..5  顶层未声明键 = NONE ×6
  发火对照:6 个 fence 全部含已声明键 subscriptionId

⚠️ 本席自己先用了错的量具:裸 grep "changes": 报出 4 个 fence 仍带它,差点写成缺陷。实际上 changes 是被移进 payload 里的(它在 DataEvent 上确实存在,只是不在顶层),grep 分不出嵌套。⇒ 顶层键集才是判据,裸 grep 不是。结论不变,但得用对工具才看得出来。

清单结论

draft ✅ · base main ✅ · 首行 Fixes #17749 ✅ · 正文带 Clause-②: no ✅(本轮派发令明令要求,#18176 正因漏它红过一次)· skip-changeset 判在发布面上(70 个可发布包的 files[] 无一指向 content/ 或 docs,阳性对照全部指向 dist;拥有该页的 @objectstack/docs 是 private:true)✅ · 治理面命中 0 ✅

CI:2026-09-14T11:39Z 去重后 30 个 distinct check,RED 0,3 个仍 in_progress ⇒ ⛔ 本裁决不含放行。

⭐ 两处方法论值得留档

1. fence 普查必须按内容做。 dev 的第二次普查用 JSON.parse 只找到 3 个 —— 六个里有两个带 // 注释解析失败、第六个在 javascript fence 里。⇒ 解析器普查会静默漏掉一半,按内容的正则普查才得到正确的 6,且有发火对照("type": "subscribe" = 4)。
2. eslint 的"收窄"在这里是测量不是跳过。 该文件根本不在 eslint 的语料里(eslint.config.mjs 的 files: 只列 {ts,tsx,mts,cts,js,jsx,mjs,cjs}),dev 用 eslint 自己的 --format json 输出证明「File ignored because no matching configuration was supplied」,并给了阳性对照。⇒ 这是有读数的范围声明,⛔ 不是省事。

偏差

1 条,已申报且正确:Zone 3 让它在存在"读 fence 对 schema"的仪器时优先把例子变成可检查的。它查了 —— 仓里有两台(check:skill-examples 读带 os:check 标记的 ts fence,check:yaml-examples 读带 os:check-yaml 的 yaml fence),而 json fence 不在任何一台的语料里,该页 0 个标记。⇒ 按派发令「⛔ 不要为这张卡造门禁」的明令,它没造,只把 schema 校验作为一次性测量跑完并删掉脚本,并记成验收备注。处置完全正确。

out_of_scope_findings 4 条,本席逐条判均不属三类(错误 fence 落在 z.unknown() 的自由袋里、HTTP 调试端点上方已有"未实现"提示、eventName 词表已由 liveness 台账承接)⇒ ⛔ 不立卡。

⇒ ACCEPT。 放行前置:去重后全部 check 全绿且 RED 0,才转 ready + 挂 auto-merge。

---

Generated by Claude Code

[claude]

✅ 已落地 —— 139fca3ef on origin/main

_{domain:devx 执行席 session_017ef78bLdybu3AffehKkhfk · 落地读数 2026-09-14T12:22Z}

PR #18183 已合入。落地判据按内容读(⛔ 不按 merged 布尔),重新 fetch 后带发火对照:

git show origin/main:content/docs/protocol/kernel/realtime-protocol.mdx
  subscriptionId      20    ← 已声明的 camelCase 键,落地前为 0
  "type": "event"      6    ← 发火对照:恰是本卡点名的六个 fence,一个不多一个不少
main tip  139fca3ef  docs(protocol): put the realtime event fences on the shape EventMessageSchema declares (#18183)

⇒ 六个 fence 现在都落在 EventMessageSchema 声明的形状上,顶层未声明键集合为空。

本卡的答案比它自己问的问题更深,记在这里

卡面把它写成「文档带了 schema 没声明的键」。dev 按派发令先从运行时测,得到的是:服务端根本不往任何 wire 上放东西 —— IRealtimeService.handleUpgrade 全平台刻意未实现,EventMessageSchema 在 spec 自己的声明、单测与类型别名 pin 之外零消费者。⇒ 文档陈旧的理由不是「schema 赢了」,而是没有任何实现站在 snake_case 那一边。

⚠️ 两条方法论留给下一个碰这页的人:

• fence 普查必须按内容做。 用 JSON.parse 的普查只找到 3 个(两个带 // 注释解析失败、一个在 javascript fence 里),按内容的正则才得到正确的 6。
• EventMessageSchema 没有 .strict()(该文件 strict 计数 0)⇒ zod 默认忽略未声明键,「parse OK」证明不了键卫生;判据是顶层键集。本席复核时先用裸 grep "changes": 得到 4 个命中、差点报成缺陷 —— 实际上 changes 被移进了 payload(它在 DataEvent 上确实存在),裸 grep 分不出嵌套。

承接:out_of_scope_findings 4 条本席已逐条判均不属三类,⛔ 未立卡,理由记在 ACCEPT 评论 5663330800。

---

Generated by Claude Code