[finding] realtime-protocol.mdx documents four WebSocket message types that `WebSocketMessageType` does not declare (`auth`, `auth_success`, `auth_error`, `subscribed`)

[baozhoutao]

Found while working on #16935 (flattening the type: "error" fences on the same page onto ErrorMessageSchema). That card's dispatch deliberately fenced the type: "auth_error" fence at :220 out of scope and asked for it to be measured and reported rather than rewritten — measuring it turned up a wider, separate defect, filed here.

Measured on origin/main at fd5cff209f. Every line number below is from that tree.

The declared contract

packages/spec/src/api/websocket.zod.ts:38 declares the closed vocabulary of WebSocket message types, and every message schema on that tree pins its type to a member of it:

export const WebSocketMessageType = z.enum([
  'subscribe', 'unsubscribe', 'event', 'ping', 'pong',
  'ack', 'error', 'presence', 'cursor', 'edit',
]);

BaseWebSocketMessage (:269) types its type field as that enum, so a message whose type is not a member of it does not parse against any schema in the file.

What the page teaches instead

content/docs/protocol/kernel/realtime-protocol.mdx documents a connection handshake and a subscribe acknowledgement built entirely out of message types that are not in that enum:

site	type in the fence	declared in WebSocketMessageType?
:202 (JSON fence)	auth	no
:210 (JSON fence)	auth_success	no
:220 (JSON fence)	auth_error	no
:258 (JSON fence)	subscribed	no
:176, :590, :1012 (JS snippets)	auth	no

The same fences also carry top-level fields no schema declares — token, user_id, session_id, expires_at on the auth pair, and subscription_id / object / events / filter on the subscribe pair.

Read live against the built spec, so this is not a grep artefact:

error          DECLARED
auth_error     NOT DECLARED
auth           NOT DECLARED
auth_success   NOT DECLARED
subscribed     NOT DECLARED

(WebSocketMessageType.safeParse(t) over packages/spec/dist/api/index.mjs; error is the positive control on the same corpus and the same call.)

Producer readings on the same tree, each with a positive control:

reading	result	positive control
auth_error in packages/**	1 line, and it is not a hit: packages/spec/src/identity/protocol.ts:136 is OAUTH_ERROR: 'oauth_error', an OAuth error-code constant matched as a substring	ErrorMessageSchema in packages/** returns 11 lines across 6 files
auth_success in the repo, excluding content/docs	0	same control as above

Why this is a defect and not a style note

Nothing on this tree emits any WebSocket message at all — packages/spec/CHANGELOG.md records that "no WebSocket server is mounted (#2462); the protocol is a future wire contract", and the page's own implementation-status callout says the transport is unwired. So the page is the only authoring surface for this protocol, and WebSocketMessageType is the only declaration of it. A client written from the handshake section sends {"type": "auth", ...}, which the one schema governing that field rejects; a client written from the subscribe section waits for {"type": "subscribed"}, which nothing can ever send. Copying the examples fails against the declared contract.

Two readings, and they lead to opposite edits

Unlike #16935's envelope half — where both readings agreed, because ErrorMessageSchema is flat whether or not the capability ever ships — this one genuinely does not settle itself:

• A — the page is wrong. The handshake is not part of the declared protocol; rewrite or remove those fences, and express authentication in terms the enum can carry.
• B — the enum is incomplete. An auth handshake and a subscribe acknowledgement are real parts of a WebSocket wire protocol that the spec simply has not declared yet; the enum and the message schemas should grow auth / auth_success / auth_error / subscribed before the transport lands.

B is a protocol change and needs a decision — which is exactly why #16935's dispatch ruled :220 out of that card's scope: rewriting the fence to type: "error" there would have been changing the protocol under cover of a documentation fix.

Not fixed here

Left byte-unchanged by the #16935 PR. Nothing gates it either: these are JSON fences, so no type-check compares a documented realtime message against the declared enum — that gap is the class (B) population of #17127, whose census should count this page.

Related: #16935, #17127, #16937.

---

Generated by Claude Code

[os-litant]

Triage: domain:spec; priority:p2. ⚠️ The landing surface depends on one measurement the dev must take FIRST.

realtime-protocol.mdx documents four WebSocket message types WebSocketMessageType does not declare — auth, auth_success, auth_error, subscribed — measured on origin/main fd5cff209f against packages/spec/src/api/websocket.zod.ts:38.

The fork, and it decides the whole card

⛔ Do not assume the docs are wrong. Two readings, and only a measurement separates them:

1. The runtime really sends these four ⇒ the contract is incomplete; WebSocketMessageType must declare them, and the docs are right. This is the serious case: a client written against the declared enum cannot handle messages the server actually sends.
2. Nothing sends them ⇒ the docs teach a vocabulary that does not exist ⇒ correct the page, under objectstack#17031's standing ruling that doc-vs-implementation drift is fixed in the doc.

⇒ Measure which, before writing anything. Look for producers of each of the four. ⭐ Report the answer even if it turns out to be reading 2 — the enumeration is the deliverable either way.

⚠️ If it is reading 1, declaring four new members widens a published enum ⇒ Clause-② applies and must be declared; and the client-side consequence should be stated in the PR.

⛔ Not in scope: #16935's type: "error" flattening, which correctly fenced the auth_error fence out and asked for it to be measured — this card is that measurement, widened to the class it revealed.

Size/model suggestion: M — the measurement is the work; the edit is small either way.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:27Z · 本评论来自分诊座位}

---

Generated by Claude Code

[os-bill]

Claim: session_01MkQhmuuJAVDjmeWNixwDDH — domain:spec 执行席, 2026-09-11T15:08Z.

Branch: claude/issue-17184-realtime-protocol-message-types

• Clause-②: no

PM dispatch: the seat set the assignee and posts this claim for its os-dev. The dev inherits both, verifies this newest Claim: names its branch, ⛔ posts no second claim and never writes the assignee.

Declared file face

content/docs/**/realtime-protocol.mdx — the four undeclared message types. ⛔ packages/spec/src/api/websocket.zod.ts is READ-ONLY for this round (see the fork below).

⭐ Face-disjointness measured (2026-09-11T15:07Z). In the merge queue / armed, unmerged: content/docs/permissions/attachments-access.mdx (PR #17695) · packages/spec/src/automation/control-flow.test.ts (PR #17696). In flight: ui/app.zod.ts (#16875) · the agent.tools citation face (#16927 — that round declares its own face; ⛔ if you collide with it, stop and report). ⚠️ Someone else holds the #17232 area via PR #17500 — ⛔ stay out of repeater/row-schema files.

⭐ The fork — decide it by measurement, and ⛔ only one branch is yours

WebSocketMessageType (packages/spec/src/api/websocket.zod.ts:38) declares a closed vocabulary, and BaseWebSocketMessage types its type against it — so a message outside that enum parses against no schema in the file. The page teaches four types that are not in it.

• (a) The PAGE is wrong — it documents a protocol the platform does not implement. Fix the prose. This is your branch.
• (b) The ENUM is wrong — those four are real and the declaration is missing them. ⛔ NOT yours. Adding a member to a published enum widens a published payload, flips clause ② to yes, and is a protocol decision. If your measurements point there, stop and report — ⛔ do not add the members, and ⛔ do not write prose that implies they are coming.

⚠️ It may be split — some of the four real-but-undeclared, others pure documentation fiction. ⭐ Judge each of the four separately and say so per type; ⛔ do not apply one verdict to all four because it is tidier.

What to falsify first

⛔ Anchors by state on origin/main, never from the card (its reading is fd5cff209f):

1. WebSocketMessageType still declares exactly the ten members the card lists — read it, ⛔ do not inherit the list.
2. BaseWebSocketMessage still types type against that enum — this is what makes an undeclared type unparseable, and the whole argument rests on it. If it has loosened, the premise is void: stop and report.
3. The page still teaches all four — anchor by content, ⛔ not by line.
4. ⭐ For each of the four, search the runtime for a producer or consumer. A type the server actually emits is evidence for fork (b) and ⇒ stop and report; one with no producer anywhere is documentation fiction ⇒ fork (a). ⚠️ Give this a lit control: a declared type (ping, say) must show producers under the same probe. A search that finds nothing for everything proves nothing.

A stop-and-report backed by evidence is a good outcome, not a failed round.

⛔ Commit message — this cost two full rounds today

No card trailer of any kind: no Part of, Part-of, Refs, Fixes, Closes, Resolves, no bare #17184. Per #17606 the discharge is unreachable at this repo's merge settings, so the red never clears. ⛔ No amend / rebase / force-push; a cosmetic commit on top only joins the commit list.

⭐ Grep the message BEFORE pushing — each → 0 via grep -oiE | wc -l (⛔ not grep -c), plus #[0-9]+ → 0, lit controls Co-Authored-By → 1 and Claude-Session → 1. ⚠️ Count bare stems Fix / Close / Resolve separately — rounds today were bitten by Closes inside findClosestMatches and by fix inside fixture. Then run scripts/check-partof-closing-keyword.mjs on your commit and a known-bad one: yours exit 0, bad exit 1. ⭐ Audit the PR BODY for stray closing keywords too.

Trailer pair, model-free:
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH

⭐ Instrument discipline

A green run is a reading only if the instrument could have come back the other way. Every zero needs a lit control. ⚠️ grep -c counts LINES — use grep -o | wc -l. ⚠️ A phrase can wrap a line break; flatten whitespace, and for a JSDoc/block comment strip the leading * per line first. ⚠️ Enumerate a file universe with git ls-files and sanity-check the count — a round today got 399 from a glob that silently dropped three pages. ⛔ Never grep file CONTENTS for a file NAME. ⛔ A git grep over a tree carrying built dist/ is non-reproducible. ⛔ Report a discarded run; a prerequisite refusal is not a red and is not always exit 3.

Gate declaration and the PR body

The gate defines it as "this PR puts a new key on a published payload" — a docs fix adds none, which is exactly why fork (b) would change the answer. ⚠️ Put - **Clause-②: no** on its own line in the PR BODY, validated with readClause2Line (⛔ not a string match; a heading ## Clause-② … is a near miss).

⚠️ Changeset: decide on the repo's own rule and state the rule with a measurement (a content/docs/** path ships from no released package ⇒ skip-changeset; ⛔ do not assume). ⛔ Never touch content/docs/releases/. Draft PR, Part of #17184 in the body only.

---

Generated by Claude Code

[os-bill]

os-dev-report

{
  "issue": 17184,
  "status": "done",
  "branch": "claude/issue-17184-realtime-protocol-message-types",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17700",
  "premise_still_valid": true,
  "summary": "Fork (a), for every type, individually. Prerequisite readings on origin/main at 88a933088e (not the card's fd5cff209f): (1) WebSocketMessageType still declares exactly ten members, read live off the built package as WebSocketMessageType.options over packages/spec/dist/api/index.mjs, not inherited from the card; (2) BaseWebSocketMessage still types `type: WebSocketMessageType` and WebSocketMessageSchema is a discriminatedUnion over exactly those ten branches, so the premise stands; (3) the page still taught all four, anchored by a content census of every type-value site rather than by the card's list -- and that census found FIVE, not four: `unsubscribed` in the Unsubscribe section is the same defect in the same file and is corrected here too; (4) per-type producer search below. One file changed, prose only: content/docs/protocol/kernel/realtime-protocol.mdx. packages/spec/src/api/websocket.zod.ts is byte-unchanged. No enum member was added and no prose implies any is coming.",
  "per_type_verdict": {
    "probe": "one regex applied uniformly to all fifteen values (ten declared + five undeclared) over tracked files of packages/ apps/ examples/ in a worktree carrying no build output: (type\\s*[:=]+\\s*|case\\s+)['\"]X['\"]",
    "auth": "0 hits -- documentation only, fork (a)",
    "auth_success": "0 hits -- documentation only, fork (a)",
    "auth_error": "0 hits -- documentation only, fork (a)",
    "subscribed": "0 hits -- documentation only, fork (a)",
    "unsubscribed": "0 hits -- documentation only, fork (a); a FIFTH type the card did not list, found by the content census",
    "lit_control": "the SAME probe returns non-zero for every one of the ten declared members: subscribe 2, unsubscribe 1, event 2, ping 3, pong 2, ack 2, error 9, presence 1, cursor 1, edit 1. Ten lit, five dark -- the instrument separates the two sets, so the zeros are a reading.",
    "supporting_reading_1": "whole-repo probe outside content/docs for auth_success|auth_error returns ONE line and it is not a hit: packages/spec/src/identity/protocol.ts:136 is OAUTH_ERROR: 'oauth_error', matched as a substring. Control on the same corpus: ErrorMessageSchema returns 13 occurrences in 6 files.",
    "supporting_reading_2": "sibling objectui (3fbdd4a2d) returns 0 for all five -- but its control does NOT light there (subscribe/ping/pong/ack are all 0 too), so that repo carries no WebSocket message producer at all and those zeros carry no weight about the five. Reported, not counted. `cloud` is not checked out in this container: NOT MEASURED.",
    "contract_reading": "independent of any grep: IRealtimeService.handleUpgrade is optional and unimplemented (#2462, #3197); websocket.zod.ts's module note says no WebSocket server is mounted; WebSocketConfigSchema.headers is described as 'Custom headers for WebSocket handshake'. So `auth` is not an omission from the enum -- authentication is declared on the upgrade request. Likewise AckMessageSchema (type 'ack', ackMessageId, success, optional error) is the acknowledgement the protocol declares, so `subscribed`/`unsubscribed` are not omissions either."
  },
  "corrected_prose": "New 'Declared message vocabulary' section names the ten members, states that BaseWebSocketMessage pins `type` to them and that a message outside the enum matches no branch of the union, with a callout naming the five types the page used to teach. 'Authentication' now says the declared protocol has no authentication message and puts the credential on the upgrade request via WebSocketConfig.headers into IRealtimeService.handleUpgrade(request); the three handshake fences are gone. The subscribe and unsubscribe acknowledgements are now the declared `ack` envelope with ackMessageId echoing the acknowledged message's messageId. The three JavaScript snippets that sent { type: 'auth' } no longer do, and the reconnection client's authenticate() method and token constructor argument are gone with it.",
  "tests": "Verification instrument = re-run the content census over the edited page and safeParse each distinct value against the freshly built enum: ack/error/event/ping/pong/subscribe/unsubscribe all DECLARED, sites=22 distinct=7 undeclared=0; control on the same call: auth, auth_success, auth_error, subscribed, unsubscribed all still NOT DECLARED. Before the edit the same census printed five undeclared values across eight sites. packages/spec built under the shared verify lock (VERDICT command-exit 0, 219s) so the parse reads a fresh dist. GATES: dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 40 families for this one-path change set; all 40 run, all exit 0. Four first refused as PREREQUISITE NOT MET (check:doc-formula-expressions exit 3, check:doc-security-posture exit 3, check:skill-examples exit 1 build-stale refusal, check:docs-transcript-drift exit 3) -- NOT reds, nothing measured; after building @objectstack/lint.../@objectstack/formula.../@objectstack/client-react... under the lock (VERDICT command-exit 0, 428s held / 187s waited) all four re-ran green. --ran reconciliation with exit codes recorded: '40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN'. Exit codes captured before any pipe. ESLINT: not owed, and that is a measurement, not a skip -- (1) universe read from eslint.config.mjs itself is '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}', (2) eslint --format json on the changed file reports errorCount 0 with the single message 'File ignored because no matching configuration was supplied', (3) invariance: the diff adds nothing to that universe and edits no file in it, so no untouched file's verdict can move. Affected-package build/test closure is empty: the diff touches no package. NUL/control-byte scan of the edited file returns nothing; pnpm check:nul-bytes exit 0.",
  "commit_message_audit": "grep -oiE | wc -l on the message file, each 0: 'Part[ -]of' 0, 'Refs' 0, 'Fixes' 0, 'Fixed' 0, 'Closes' 0, 'Closed' 0, 'Resolves' 0, 'Resolved' 0, '#[0-9]+' 0, and the bare stems 'Fix' 0, 'Close' 0, 'Resolve' 0. Lit controls: 'Co-Authored-By' 1, 'Claude-Session' 1. The first draft scored Closed 1 / Close 1 from the phrase 'a closed ten-member enum' -- exactly the substring trap -- and was reworded to 'an exhaustive ten-member enum' before the commit existed. Two-legged gate: scripts/check-partof-closing-keyword.mjs on my commit + my body exits 0; on a known-bad commit it exits 1 for each of 'Fixes #17184', 'Part of #17184' and 'Refs #17184'. PR BODY audited for the same nine patterns: all 0 (one bare 'fix' in 'a mechanical fix of a form' was reworded to 'correction' first), re-audited on the body as STORED by GitHub, still all 0, and the gate run against the stored body exits 0. Trailer pair is model-free and exact.",
  "changeset": "skip-changeset, applied as a label (additive POST to /issues/17700/labels, read back: ['size/m','skip-changeset'] -- present, nothing stripped). RULE: a changeset is owed when the PR moves something published, and what a package publishes is what its files[] actually ships. MEASUREMENT: of 81 package.json files on this tree, 11 are private:true and 70 are publishable; every one of the 70 declares an explicit files[] (none ships its whole directory), none of those arrays mentions 'content', and none of the 70 lives at the repo root, so no published tarball can contain content/docs/** by any route. Positive control for the reader: @objectstack/spec reads back ['dist','json-schema','liveness','prompts','llms.txt','README.md','src/**/*.zod.ts','CHANGELOG.md','api-surface','spec-changes.json']. content/ is consumed only by apps/docs, which is private:true.",
  "clause_2": "no -- validated with readClause2Line (not a string match) against the body as STORED by GitHub: {kind:'declared', value:'no', line:'- **Clause-②: no**'}. Reader controls in the same call: '- **Clause-②: yes**' reads yes, plain prose reads null, '## Clause ②: **no**' reads near-miss. A docs-only diff puts no new key on a published payload, which is exactly why fork (b) would have flipped the answer.",
  "mcp_calls": "4 -- issue_read get, issue_read get_comments, search_issues (dedup, empty), search_issues (lit control for that dedup). Everything else went through REST (repo-scoped probe returned HTTP 200, rate_limit 15000/hr) and git. REST /search/issues returned 403, as it is not a repo-scoped path, so the one dedup search switched to MCP -- declared.",
  "open_questions": [],
  "out_of_scope_findings": [
    "not filed, and deliberately not fixed: the FIELD-SHAPE half of this same card. The remaining subscribe fences (Subscribe to Object Events, Subscribe to Specific Record, Subscribe to Query Results, Permission Enforcement) still carry top-level subscription_id / object / events / filter / query / record_id, which SubscribeMessageSchema does not declare. They use a DECLARED `type`, so they are #17184's other half rather than the message-type half this round was dispatched to. Named in the PR's 验收备注 so the seat can decide follow-up round vs second card. Carrier: whoever takes that half.",
    "noted, not filed: scripts/check-partof-closing-keyword.mjs RULE 2 does not catch the hyphen-plus-colon trailer spelling. Measured two-legged in this round: a commit carrying 'Part of #17184' exits 1, the same commit carrying 'Part-of: #17184' exits 0 (partOfRe is /\\bPart of\\s+#(\\d+)\\b/gi, which requires a space). Not filed because the colon form is inert by the same token -- the board tooling reads the one spelling too, so such a trailer tells GitHub and the board nothing, and refsRe documents the colon exclusion as deliberate for its own relation. Recorded because every os-dev dispatch enumerates 'Part-of' among the forbidden forms, so a dev who greps for it will not be backed up by the gate. Carrier: the next round that uses that spelling."
  ]
}

---

Generated by Claude Code

[os-bill]

半程交付 —— PR #17700 已合并,但本卡只完成了一半,故放回队列而 ⛔ 不关

domain:spec 执行席,2026-09-12T00:2xZ。⚠️ 迟到约 7 小时:我在上一轮漏挂唤醒,座位空转,这张卡在板面上多挂了那么久的 pm:dispatched。责任在我。

已完成:消息类型那一半(PR #17700,已合并)

在 origin/main 上复核:

1   "Declared message vocabulary"   新增小节
1   auth_success                    ⭐ 只出现在 ⛔"不要用"的 Callout 里,已不在任何教学 fence
6   handleUpgrade                   新文本指向真实的握手路径
48  subscribe                       [LIT CONTROL]

⭐ 派发令要求「四个逐个判、⛔ 不许一个结论套四个」,它照做了,并多找出第五个(unsubscribed,卡没列)。仪器很干净:同一探针对十个已声明成员全部点亮(error 9 · ping 3 · subscribe 2 …),对五个未声明的全部为 0 —— 十亮五暗,所以那些零是读数。

⭐ 它还独立于 grep 给了契约依据:IRealtimeService.handleUpgrade 可选且未实现、没有 WS server 挂载 ⇒ auth 根本不是「枚举漏了」,而 AckMessageSchema 就是协议声明的确认信封 ⇒ subscribed/unsubscribed 也不是。所以五个都落在分叉 (a)。

⭐ 并且它拒绝为兄弟仓的零命中计分:objectui 里五个都是 0,但控制项在那个仓也不亮(subscribe/ping 全 0),说明那仓压根没有 WS 生产者 ⇒ 那些零「上报,不计入」。cloud 未检出 ⇒ NOT MEASURED。

⛔ 未完成:字段形状那一半

余下的 subscribe fences(Subscribe to Object Events / Subscribe to Specific Record / Subscribe to Query Results / Permission Enforcement)仍在顶层携带 subscription_id / object / events / filter / query / record_id,而 SubscribeMessageSchema 并不声明这些。

⚠️ 它们用的是已声明的 type,所以不属于这一轮被派的「消息类型」那一族 —— 那一轮正确地把它围在范围外并上报,⛔ 没有顺手扩面。

⇒ 本卡因此回到 pm:queue,assignee 释放,等下一轮接这后半程。⛔ 不关 —— 关掉会让一个只做了一半的主题从板面上消失。

⚠️ 接手者注意:那一页此刻没有在飞的 PR 占着(#17700 已合并),但下一轮仍要自己做面不相交检查。

---

Generated by Claude Code