@ttt-productions/chat-react 0.13.16 → 0.13.18

package/dist/realtime/diagnostics.js

@@ -1,144 +1,59 @@
-// OPT-IN structured client diagnostics for the realtime chat transport.
-//
-// The E2E/browser harness can already capture the raw WebSocket frames; what it
-// cannot see is what the CLIENT DECIDED about them — which frame it applied,
-// which it dropped and why, what resume cursor it sent, and whether a send was
-// reconciled or failed. This module is that missing half: a bounded, structured,
-// opt-in decision log.
-//
-// The connection-time, resume, presence, and socket-timing instruments are the
-// baseline-campaign metric families — they stay. Only the attachment-serving
-// instruments were retired with the chat-attachment architecture.
-//
-// Rules this module exists to enforce:
-//   - OFF BY DEFAULT and zero behavior change. When the option is absent the
-//     factory returns `null`, every call site is `this.diag?.(...)`, and JS
-//     optional-call short-circuiting means the payload object is never even
-//     constructed. The cost when off is one nullish check.
-//   - NEVER user content. Ids, seqs, states, counts, codes, booleans only —
-//     never message text, captions, filenames, URLs, tokens, or previews. The
-//     INBOX events go one step further and log SIZES only: a `channelRef` names
-//     one specific conversation, so registry/unread lines carry counts and
-//     deltas, never the refs themselves.
-//   - STABLE event names (`chat_client_*`) suitable for log queries and later
-//     alert metrics; one line per DECISION, never per render or per heartbeat.
-//   - A diagnostics sink can never break the client: every emit is wrapped, so a
-//     throwing sink is swallowed rather than turned into a transport failure.
-/**
- * Stable event names. These are a QUERY CONTRACT — Cloud Logging filters, E2E
- * console greps, and any later alert metric key on them, so a name is added or
- * retired deliberately, never renamed in place.
- */
+// Log queries key on these names: add or retire one, never rename it in place.
 export const CHAT_CLIENT_DIAGNOSTIC_EVENTS = {
-    /** A socket open is being attempted (per attempt, with the reconnect cause). */
     CONNECT_ATTEMPT: 'chat_client_connect_attempt',
-    /** The grant mint failed before a socket existed (terminal vs. retryable). */
     GRANT_FAILED: 'chat_client_grant_failed',
-    /** The socket reached OPEN (the point the resume cursor is sent from). */
     SOCKET_OPEN: 'chat_client_socket_open',
-    /** The socket closed, with the code and what the client decided to do next. */
     SOCKET_CLOSE: 'chat_client_socket_close',
-    /**
-     * CHANNEL ONLY. The dead-socket watchdog closed a socket that had gone silent
-     * past the client's inbound-silence threshold (the channel DO auto-acks every
-     * heartbeat, so silence there is provable death). One line per detection —
-     * never per heartbeat — followed by the ordinary socket_close/reconnect lines.
-     */
     SOCKET_LIVENESS_TIMEOUT: 'chat_client_socket_liveness_timeout',
-    /** A reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */
     RECONNECT_SCHEDULED: 'chat_client_reconnect_scheduled',
-    /** The resume cursor sent to the DO. */
     RESUME_REQUEST: 'chat_client_resume_request',
-    /** The DO's snapshot answer + how the cursor moved because of it. */
     RESUME_RESULT: 'chat_client_resume_result',
-    /** A `resync: true` snapshot dropped the local tail (removal, not upsert). */
     RESYNC_DROPPED_TAIL: 'chat_client_resync_dropped_tail',
-    /** A frame was applied to UI state (insert / replace-by-seq / optimistic reconcile). */
     FRAME_APPLIED: 'chat_client_frame_applied',
-    /** A frame was NOT applied, with the reason. */
     FRAME_DROPPED: 'chat_client_frame_dropped',
-    /** A moderation revision overlay was recorded (and whether a loaded row re-rendered). */
     REVISION_APPLIED: 'chat_client_revision_applied',
-    /** A history page was requested (cursor + limit). */
     HISTORY_REQUEST: 'chat_client_history_request',
-    /** A history page was applied: size, seq range, cursor advance. */
     HISTORY_PAGE: 'chat_client_history_page',
-    /** An optimistic send was rendered and its frame written. */
     SEND_OPTIMISTIC: 'chat_client_send_optimistic',
-    /** A send was acked by the server (seq assigned). */
     SEND_ACK: 'chat_client_send_ack',
-    /** A correlated `send-rejected` (or its legacy uncorrelated form) was handled. */
     SEND_REJECTED: 'chat_client_send_rejected',
-    /** A send was re-emitted (reconnect resume / scheduled hint / manual retry). */
     SEND_RETRY: 'chat_client_send_retry',
-    /** A send reached its visible failed state, with the reason. */
     SEND_FAILED: 'chat_client_send_failed',
-    /** An uncorrelated server `error` frame code. */
     ERROR_FRAME: 'chat_client_error_frame',
-    // ---- inbox socket (one per USER, separate from the per-thread channel socket) ----
-    /** An inbox socket open is being attempted (per attempt, with the reconnect cause). */
     INBOX_CONNECT_ATTEMPT: 'chat_client_inbox_connect_attempt',
-    /** The inbox grant mint failed before a socket existed (terminal vs. retryable). */
     INBOX_GRANT_FAILED: 'chat_client_inbox_grant_failed',
-    /** The inbox socket reached OPEN (the point `resume` is sent from). */
     INBOX_SOCKET_OPEN: 'chat_client_inbox_socket_open',
-    /** The inbox socket closed, with the code and what the client decided to do next. */
     INBOX_SOCKET_CLOSE: 'chat_client_inbox_socket_close',
-    /** An inbox reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */
     INBOX_RECONNECT_SCHEDULED: 'chat_client_inbox_reconnect_scheduled',
-    /** The cursorless inbox `resume` was sent (the DO answers with a full snapshot). */
     INBOX_RESUME_REQUEST: 'chat_client_inbox_resume_request',
-    /** An authoritative inbox snapshot was applied — registry SIZES only, never refs. */
     INBOX_SNAPSHOT_APPLIED: 'chat_client_inbox_snapshot_applied',
-    /** The unread projection actually CHANGED (dock dot and/or per-row dot count). */
     INBOX_UNREAD_UPDATED: 'chat_client_inbox_unread_updated',
-    /** An inbox frame was NOT applied, with the reason. */
     INBOX_FRAME_DROPPED: 'chat_client_inbox_frame_dropped',
-    /** A mark-read was written to the socket (no optimistic local clear). */
     INBOX_MARK_READ: 'chat_client_inbox_mark_read',
 };
-/** Max length of a server-supplied label (frame type, error code) we echo into a log line. */
 const MAX_LABEL_LEN = 48;
-/**
- * Clamp a server-supplied label before it enters a log line. Frame types and
- * error codes are protocol tokens, not user content, but they arrive from the
- * wire — bound them so a hostile/buggy peer cannot emit an unbounded line.
- */
 export function safeDiagnosticLabel(raw) {
     if (typeof raw !== 'string')
         return 'unknown';
     const trimmed = raw.slice(0, MAX_LABEL_LEN);
     return trimmed.length > 0 ? trimmed : 'unknown';
 }
-/**
- * The default sink: ONE `console.debug` line per decision, shaped
- * `chat_client_<event> {"compact":"json"}` so a browser console capture or a log
- * query can filter on the stable prefix and parse the payload without a
- * multi-line join.
- */
 const consoleDebugSink = (event, data) => {
     if (typeof console === 'undefined' || typeof console.debug !== 'function')
         return;
     console.debug(`${event} ${JSON.stringify(data)}`);
 };
-/**
- * Build the emitter for a `diagnostics` config value. Returns `null` when
- * diagnostics are off so call sites can use `this.diag?.(...)` — with optional
- * call syntax the argument object is not constructed at all on the off path.
- */
 export function createDiagnosticsEmitter(option) {
     if (option == null || option === false)
         return null;
     const sink = option === true ? consoleDebugSink : option;
     return (event, data) => {
-        // Diagnostics observe; they must never alter transport behavior — a sink that
-        // throws (or a payload that cannot be serialized) is swallowed here.
+        // RULE-STD-ENG-009 exception: diagnostics must never fail the client, so a throwing sink is
+        // swallowed.
         try {
             sink(event, data);
         }
-        catch {
-            /* diagnostics are never allowed to fail the client */
-        }
+        catch { }
     };
 }
 //# sourceMappingURL=diagnostics.js.map

package/dist/realtime/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/realtime/diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["// OPT-IN structured client diagnostics for the realtime chat transport.\n//\n// The E2E/browser harness can already capture the raw WebSocket frames; what it\n// cannot see is what the CLIENT DECIDED about them — which frame it applied,\n// which it dropped and why, what resume cursor it sent, and whether a send was\n// reconciled or failed. This module is that missing half: a bounded, structured,\n// opt-in decision log.\n//\n// The connection-time, resume, presence, and socket-timing instruments are the\n// baseline-campaign metric families — they stay. Only the attachment-serving\n// instruments were retired with the chat-attachment architecture.\n//\n// Rules this module exists to enforce:\n//   - OFF BY DEFAULT and zero behavior change. When the option is absent the\n//     factory returns `null`, every call site is `this.diag?.(...)`, and JS\n//     optional-call short-circuiting means the payload object is never even\n//     constructed. The cost when off is one nullish check.\n//   - NEVER user content. Ids, seqs, states, counts, codes, booleans only —\n//     never message text, captions, filenames, URLs, tokens, or previews. The\n//     INBOX events go one step further and log SIZES only: a `channelRef` names\n//     one specific conversation, so registry/unread lines carry counts and\n//     deltas, never the refs themselves.\n//   - STABLE event names (`chat_client_*`) suitable for log queries and later\n//     alert metrics; one line per DECISION, never per render or per heartbeat.\n//   - A diagnostics sink can never break the client: every emit is wrapped, so a\n//     throwing sink is swallowed rather than turned into a transport failure.\n\n/**\n * A structured diagnostic sink. `event` is one of the stable\n * {@link CHAT_CLIENT_DIAGNOSTIC_EVENTS} names; `data` is a compact, content-free\n * payload (ids/seqs/states/counts/codes only). Supplying a sink lets the app\n * route entries into its own logger; `true` uses the console.debug default.\n */\nexport type ChatClientDiagnosticsSink = (event: string, data: Record<string, unknown>) => void;\n\n/**\n * The additive `diagnostics` config value: `false`/absent = off (the default and\n * the only production posture), `true` = the single-line `console.debug` sink,\n * or a custom {@link ChatClientDiagnosticsSink}.\n */\nexport type ChatClientDiagnosticsOption = boolean | ChatClientDiagnosticsSink;\n\n/** The bound emitter, or `null` when diagnostics are off (the zero-overhead path). */\nexport type ChatClientDiagnosticsEmitter = ChatClientDiagnosticsSink | null;\n\n/**\n * Stable event names. These are a QUERY CONTRACT — Cloud Logging filters, E2E\n * console greps, and any later alert metric key on them, so a name is added or\n * retired deliberately, never renamed in place.\n */\nexport const CHAT_CLIENT_DIAGNOSTIC_EVENTS = {\n  /** A socket open is being attempted (per attempt, with the reconnect cause). */\n  CONNECT_ATTEMPT: 'chat_client_connect_attempt',\n  /** The grant mint failed before a socket existed (terminal vs. retryable). */\n  GRANT_FAILED: 'chat_client_grant_failed',\n  /** The socket reached OPEN (the point the resume cursor is sent from). */\n  SOCKET_OPEN: 'chat_client_socket_open',\n  /** The socket closed, with the code and what the client decided to do next. */\n  SOCKET_CLOSE: 'chat_client_socket_close',\n  /**\n   * CHANNEL ONLY. The dead-socket watchdog closed a socket that had gone silent\n   * past the client's inbound-silence threshold (the channel DO auto-acks every\n   * heartbeat, so silence there is provable death). One line per detection —\n   * never per heartbeat — followed by the ordinary socket_close/reconnect lines.\n   */\n  SOCKET_LIVENESS_TIMEOUT: 'chat_client_socket_liveness_timeout',\n  /** A reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */\n  RECONNECT_SCHEDULED: 'chat_client_reconnect_scheduled',\n  /** The resume cursor sent to the DO. */\n  RESUME_REQUEST: 'chat_client_resume_request',\n  /** The DO's snapshot answer + how the cursor moved because of it. */\n  RESUME_RESULT: 'chat_client_resume_result',\n  /** A `resync: true` snapshot dropped the local tail (removal, not upsert). */\n  RESYNC_DROPPED_TAIL: 'chat_client_resync_dropped_tail',\n  /** A frame was applied to UI state (insert / replace-by-seq / optimistic reconcile). */\n  FRAME_APPLIED: 'chat_client_frame_applied',\n  /** A frame was NOT applied, with the reason. */\n  FRAME_DROPPED: 'chat_client_frame_dropped',\n  /** A moderation revision overlay was recorded (and whether a loaded row re-rendered). */\n  REVISION_APPLIED: 'chat_client_revision_applied',\n  /** A history page was requested (cursor + limit). */\n  HISTORY_REQUEST: 'chat_client_history_request',\n  /** A history page was applied: size, seq range, cursor advance. */\n  HISTORY_PAGE: 'chat_client_history_page',\n  /** An optimistic send was rendered and its frame written. */\n  SEND_OPTIMISTIC: 'chat_client_send_optimistic',\n  /** A send was acked by the server (seq assigned). */\n  SEND_ACK: 'chat_client_send_ack',\n  /** A correlated `send-rejected` (or its legacy uncorrelated form) was handled. */\n  SEND_REJECTED: 'chat_client_send_rejected',\n  /** A send was re-emitted (reconnect resume / scheduled hint / manual retry). */\n  SEND_RETRY: 'chat_client_send_retry',\n  /** A send reached its visible failed state, with the reason. */\n  SEND_FAILED: 'chat_client_send_failed',\n  /** An uncorrelated server `error` frame code. */\n  ERROR_FRAME: 'chat_client_error_frame',\n\n  // ---- inbox socket (one per USER, separate from the per-thread channel socket) ----\n\n  /** An inbox socket open is being attempted (per attempt, with the reconnect cause). */\n  INBOX_CONNECT_ATTEMPT: 'chat_client_inbox_connect_attempt',\n  /** The inbox grant mint failed before a socket existed (terminal vs. retryable). */\n  INBOX_GRANT_FAILED: 'chat_client_inbox_grant_failed',\n  /** The inbox socket reached OPEN (the point `resume` is sent from). */\n  INBOX_SOCKET_OPEN: 'chat_client_inbox_socket_open',\n  /** The inbox socket closed, with the code and what the client decided to do next. */\n  INBOX_SOCKET_CLOSE: 'chat_client_inbox_socket_close',\n  /** An inbox reconnect was scheduled (`delayMs`) or given up on (`delayMs: null`). */\n  INBOX_RECONNECT_SCHEDULED: 'chat_client_inbox_reconnect_scheduled',\n  /** The cursorless inbox `resume` was sent (the DO answers with a full snapshot). */\n  INBOX_RESUME_REQUEST: 'chat_client_inbox_resume_request',\n  /** An authoritative inbox snapshot was applied — registry SIZES only, never refs. */\n  INBOX_SNAPSHOT_APPLIED: 'chat_client_inbox_snapshot_applied',\n  /** The unread projection actually CHANGED (dock dot and/or per-row dot count). */\n  INBOX_UNREAD_UPDATED: 'chat_client_inbox_unread_updated',\n  /** An inbox frame was NOT applied, with the reason. */\n  INBOX_FRAME_DROPPED: 'chat_client_inbox_frame_dropped',\n  /** A mark-read was written to the socket (no optimistic local clear). */\n  INBOX_MARK_READ: 'chat_client_inbox_mark_read',\n} as const;\n\nexport type ChatClientDiagnosticEventName =\n  (typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS)[keyof typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS];\n\n/** Max length of a server-supplied label (frame type, error code) we echo into a log line. */\nconst MAX_LABEL_LEN = 48;\n\n/**\n * Clamp a server-supplied label before it enters a log line. Frame types and\n * error codes are protocol tokens, not user content, but they arrive from the\n * wire — bound them so a hostile/buggy peer cannot emit an unbounded line.\n */\nexport function safeDiagnosticLabel(raw: unknown): string {\n  if (typeof raw !== 'string') return 'unknown';\n  const trimmed = raw.slice(0, MAX_LABEL_LEN);\n  return trimmed.length > 0 ? trimmed : 'unknown';\n}\n\n/**\n * The default sink: ONE `console.debug` line per decision, shaped\n * `chat_client_<event> {\"compact\":\"json\"}` so a browser console capture or a log\n * query can filter on the stable prefix and parse the payload without a\n * multi-line join.\n */\nconst consoleDebugSink: ChatClientDiagnosticsSink = (event, data) => {\n  if (typeof console === 'undefined' || typeof console.debug !== 'function') return;\n  console.debug(`${event} ${JSON.stringify(data)}`);\n};\n\n/**\n * Build the emitter for a `diagnostics` config value. Returns `null` when\n * diagnostics are off so call sites can use `this.diag?.(...)` — with optional\n * call syntax the argument object is not constructed at all on the off path.\n */\nexport function createDiagnosticsEmitter(\n  option: ChatClientDiagnosticsOption | undefined,\n): ChatClientDiagnosticsEmitter {\n  if (option == null || option === false) return null;\n  const sink = option === true ? consoleDebugSink : option;\n  return (event, data) => {\n    // Diagnostics observe; they must never alter transport behavior — a sink that\n    // throws (or a payload that cannot be serialized) is swallowed here.\n    try {\n      sink(event, data);\n    } catch {\n      /* diagnostics are never allowed to fail the client */\n    }\n  };\n}\n"]}
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/realtime/diagnostics.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe,EAAE,6BAA6B;IAC9C,YAAY,EAAE,0BAA0B;IACxC,WAAW,EAAE,yBAAyB;IACtC,YAAY,EAAE,0BAA0B;IACxC,uBAAuB,EAAE,qCAAqC;IAC9D,mBAAmB,EAAE,iCAAiC;IACtD,cAAc,EAAE,4BAA4B;IAC5C,aAAa,EAAE,2BAA2B;IAC1C,mBAAmB,EAAE,iCAAiC;IACtD,aAAa,EAAE,2BAA2B;IAC1C,aAAa,EAAE,2BAA2B;IAC1C,gBAAgB,EAAE,8BAA8B;IAChD,eAAe,EAAE,6BAA6B;IAC9C,YAAY,EAAE,0BAA0B;IACxC,eAAe,EAAE,6BAA6B;IAC9C,QAAQ,EAAE,sBAAsB;IAChC,aAAa,EAAE,2BAA2B;IAC1C,UAAU,EAAE,wBAAwB;IACpC,WAAW,EAAE,yBAAyB;IACtC,WAAW,EAAE,yBAAyB;IAEtC,qBAAqB,EAAE,mCAAmC;IAC1D,kBAAkB,EAAE,gCAAgC;IACpD,iBAAiB,EAAE,+BAA+B;IAClD,kBAAkB,EAAE,gCAAgC;IACpD,yBAAyB,EAAE,uCAAuC;IAClE,oBAAoB,EAAE,kCAAkC;IACxD,sBAAsB,EAAE,oCAAoC;IAC5D,oBAAoB,EAAE,kCAAkC;IACxD,mBAAmB,EAAE,iCAAiC;IACtD,eAAe,EAAE,6BAA6B;CACtC,CAAC;AAKX,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,MAAM,gBAAgB,GAA8B,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;IAClE,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU;QAAE,OAAO;IAClF,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpD,CAAC,CAAC;AAEF,MAAM,UAAU,wBAAwB,CACtC,MAA+C;IAE/C,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC;IACzD,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,4FAA4F;QAC5F,aAAa;QACb,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC","sourcesContent":["export type ChatClientDiagnosticsSink = (event: string, data: Record<string, unknown>) => void;\n\nexport type ChatClientDiagnosticsOption = boolean | ChatClientDiagnosticsSink;\n\nexport type ChatClientDiagnosticsEmitter = ChatClientDiagnosticsSink | null;\n\n// Log queries key on these names: add or retire one, never rename it in place.\nexport const CHAT_CLIENT_DIAGNOSTIC_EVENTS = {\n  CONNECT_ATTEMPT: 'chat_client_connect_attempt',\n  GRANT_FAILED: 'chat_client_grant_failed',\n  SOCKET_OPEN: 'chat_client_socket_open',\n  SOCKET_CLOSE: 'chat_client_socket_close',\n  SOCKET_LIVENESS_TIMEOUT: 'chat_client_socket_liveness_timeout',\n  RECONNECT_SCHEDULED: 'chat_client_reconnect_scheduled',\n  RESUME_REQUEST: 'chat_client_resume_request',\n  RESUME_RESULT: 'chat_client_resume_result',\n  RESYNC_DROPPED_TAIL: 'chat_client_resync_dropped_tail',\n  FRAME_APPLIED: 'chat_client_frame_applied',\n  FRAME_DROPPED: 'chat_client_frame_dropped',\n  REVISION_APPLIED: 'chat_client_revision_applied',\n  HISTORY_REQUEST: 'chat_client_history_request',\n  HISTORY_PAGE: 'chat_client_history_page',\n  SEND_OPTIMISTIC: 'chat_client_send_optimistic',\n  SEND_ACK: 'chat_client_send_ack',\n  SEND_REJECTED: 'chat_client_send_rejected',\n  SEND_RETRY: 'chat_client_send_retry',\n  SEND_FAILED: 'chat_client_send_failed',\n  ERROR_FRAME: 'chat_client_error_frame',\n\n  INBOX_CONNECT_ATTEMPT: 'chat_client_inbox_connect_attempt',\n  INBOX_GRANT_FAILED: 'chat_client_inbox_grant_failed',\n  INBOX_SOCKET_OPEN: 'chat_client_inbox_socket_open',\n  INBOX_SOCKET_CLOSE: 'chat_client_inbox_socket_close',\n  INBOX_RECONNECT_SCHEDULED: 'chat_client_inbox_reconnect_scheduled',\n  INBOX_RESUME_REQUEST: 'chat_client_inbox_resume_request',\n  INBOX_SNAPSHOT_APPLIED: 'chat_client_inbox_snapshot_applied',\n  INBOX_UNREAD_UPDATED: 'chat_client_inbox_unread_updated',\n  INBOX_FRAME_DROPPED: 'chat_client_inbox_frame_dropped',\n  INBOX_MARK_READ: 'chat_client_inbox_mark_read',\n} as const;\n\nexport type ChatClientDiagnosticEventName =\n  (typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS)[keyof typeof CHAT_CLIENT_DIAGNOSTIC_EVENTS];\n\nconst MAX_LABEL_LEN = 48;\n\nexport function safeDiagnosticLabel(raw: unknown): string {\n  if (typeof raw !== 'string') return 'unknown';\n  const trimmed = raw.slice(0, MAX_LABEL_LEN);\n  return trimmed.length > 0 ? trimmed : 'unknown';\n}\n\nconst consoleDebugSink: ChatClientDiagnosticsSink = (event, data) => {\n  if (typeof console === 'undefined' || typeof console.debug !== 'function') return;\n  console.debug(`${event} ${JSON.stringify(data)}`);\n};\n\nexport function createDiagnosticsEmitter(\n  option: ChatClientDiagnosticsOption | undefined,\n): ChatClientDiagnosticsEmitter {\n  if (option == null || option === false) return null;\n  const sink = option === true ? consoleDebugSink : option;\n  return (event, data) => {\n    // RULE-STD-ENG-009 exception: diagnostics must never fail the client, so a throwing sink is\n    // swallowed.\n    try {\n      sink(event, data);\n    } catch {}\n  };\n}\n"]}

package/dist/realtime/inbox-client.d.ts

@@ -5,39 +5,13 @@ import type { GrantProvider, TransportTimers, RealtimeStatus } from './shared.js
 import { type ChatClientDiagnosticsOption } from './diagnostics.js';
 export interface InboxClientState {
     status: RealtimeStatus;
-    /** Active (non-tombstoned) channel/invite registry entries — inbox-view visibility. */
     registry: WireRegistryEntry[];
-    /** True if ANY active channel/invite has unread (drives the dock dot). */
     hasUnread: boolean;
-    /** The set of channelRefs that currently carry an unread dot (per-row dots). */
     unreadChannelRefs: string[];
-    /**
-     * The last TERMINAL error code (mirrors `ChannelClientState.lastErrorCode`):
-     * `'access-denied'` when the inbox grant provider throws `ChatAccessDeniedError`
-     * (a genuine, terminal policy "no" — e.g. a banned/suspended account), and
-     * `'revoked'` on a 4403 REVOKED close. Null while healthy and across transient
-     * reconnects. The app subscribes to inbox state directly (there is no inbox React
-     * hook in this package), so this stable code is the surface — it invents no new UI.
-     */
     lastErrorCode: string | null;
-    /**
-     * True once the first authoritative snapshot has been applied — the registry and dots
-     * are then the inbox runtime's answer, so an empty registry means "nothing here"
-     * rather than "not loaded yet". Once true it stays true.
-     */
     hasLoadedInitialData: boolean;
-    /**
-     * True once the first open has failed for long enough to say so — the same rule as
-     * `ChannelClientState.initialLoadFailed`. Cleared by the first snapshot or `retryNow()`.
-     */
     initialLoadFailed: boolean;
 }
-/**
- * How one `markRead` ended: `ok` — the inbox runtime advanced the read cursor (its
- * fresh snapshot clears the dot); otherwise `code` says why not — the runtime's own
- * reason, `not-sent` (no open socket, nothing was sent), or `connection-lost` (the
- * socket closed before the answer arrived, so the outcome is unknown and the dot stays).
- */
 export type ChatMarkReadOutcome = {
     ok: true;
 } | {
@@ -46,9 +20,7 @@ export type ChatMarkReadOutcome = {
 };
 export interface InboxClientConfig {
     endpoint: string;
-    /** The authenticated uid (the inbox owner; the DO serves no one else's data). */
     currentUserId: string;
-    /** Mints/refreshes an INBOX-scope grant (scope `{ kind:'inbox', uid }`). */
     grantProvider: GrantProvider;
     socketFactory: SocketFactory;
     timers?: TransportTimers;
@@ -58,15 +30,6 @@ export interface InboxClientConfig {
         maxAttempts?: number | null;
         random?: () => number;
     };
-    /**
-     * OPT-IN structured client diagnostics — the SAME option type and emitter the
-     * channel client uses (one owner, `./diagnostics.ts`). Default OFF: absent or
-     * `false` changes nothing and costs one nullish check. `true` emits one
-     * single-line `console.debug` entry per decision under the stable
-     * `chat_client_inbox_*` names; a function routes them to the app's logger.
-     * Inbox payloads are SIZES ONLY — registry/unread counts and deltas, never a
-     * `channelRef` (which names one specific conversation).
-     */
     diagnostics?: ChatClientDiagnosticsOption;
 }
 export declare class InboxClient {
@@ -79,67 +42,33 @@ export declare class InboxClient {
     private reauthAttempted;
     private reconnectTimer;
     private closedByUs;
-    /**
-     * The current lifecycle's number, advanced by every `connect()` and `close()`; a grant,
-     * timer, or socket callback of an older lifecycle is ignored (FRONTEND-108).
-     */
     private lifecycle;
     private readonly initialLoad;
-    /** Mark-reads sent on the current socket, awaiting their correlated result, by requestId. */
     private readonly pendingMarkReads;
-    /** Structured diagnostics emitter, or null when off (the default, zero-overhead). */
     private readonly diag;
-    /** Monotonic socket-open attempt counter (diagnostics correlation only). */
     private connectAttempt;
-    /** Why the CURRENT connect attempt is happening (diagnostics only). */
     private reconnectCause;
-    /** The last close code observed, carried into the next attempt's cause line. */
     private lastCloseCode;
     constructor(config: InboxClientConfig);
     getState(): InboxClientState;
     subscribe(fn: (s: InboxClientState) => void): () => void;
     private setState;
     connect(): Promise<void>;
-    /**
-     * Retry now (the first-open failure's Retry) — the same rule as `ChannelClient.retryNow`:
-     * a reconnect waiting out its backoff opens at once; a stopped lifecycle starts again; an
-     * attempt in flight is left to finish; the first-open failure clears either way.
-     */
     retryNow(): void;
     private startLifecycle;
     private reportInitialLoadFailed;
     private openSocket;
     private onOpen;
     private onClose;
-    /**
-     * Terminal access denial surfaced by the inbox grant provider
-     * (`ChatAccessDeniedError`). Same terminal posture as the 4403 REVOKED close: mark
-     * closed-by-us, close the reconnect controller, and surface the stable
-     * `access-denied` code. The inbox client tracks NO optimistic/pending sends
-     * (mark-read is fire-and-forget with no local pending state), so — unlike
-     * ChannelClient — there is nothing to fail here; only the lifecycle stops.
-     */
     private denyAccessTerminally;
     private scheduleReconnect;
     private onMessage;
     private applySnapshot;
     private sendFrame;
-    /** True if a specific channel/invite currently carries an unread dot. */
     channelHasUnread(channelRef: string): boolean;
-    /**
-     * Clear a channel/invite's unread WITHOUT opening it (the inbox-view mark-read
-     * controls). Sends `mark-read` with a fresh `requestId`; the inbox runtime advances the
-     * member's read cursor, pushes a fresh authoritative snapshot (which is what removes
-     * the dot — there is NO optimistic local clear), and answers with a
-     * `mark-read-result` naming the same request. The promise settles on that answer —
-     * never on a timer — or with `not-sent` when no socket is open, or `connection-lost`
-     * when the socket closes first.
-     */
     markRead(channelRef: string): Promise<ChatMarkReadOutcome>;
-    /** Settle the mark-read the result names; a result naming no pending request is ignored. */
     private applyMarkReadResult;
     private settlePendingMarkReads;
-    /** Permanently close (auth-user switch / unmount). Idempotent. */
     close(): void;
 }
 //# sourceMappingURL=inbox-client.d.ts.map

package/dist/realtime/inbox-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox-client.d.ts","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inbox-client.d.ts","sourceRoot":"","sources":["../../src/realtime/inbox-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,uBAAuB,EAG7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAkB,aAAa,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlF,OAAO,EAKL,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,SAAS,CAAC,EAAE;QACV,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;KACvB,CAAC;IACF,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAYD,qBAAa,WAAW;IAkBV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAjBnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6D;IAC9F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CACwE;IAC9F,OAAO,CAAC,aAAa,CAAuB;gBAEf,MAAM,EAAE,iBAAiB;IAOtD,QAAQ,IAAI,gBAAgB;IAI5B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxD,OAAO,CAAC,QAAQ;IAKV,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,QAAQ,IAAI,IAAI;YAmBF,cAAc;IAa5B,OAAO,CAAC,uBAAuB;YAKjB,UAAU;IA4CxB,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,OAAO;IA+Bf,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,iBAAiB;IAqBzB,OAAO,CAAC,SAAS;IA2CjB,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,SAAS;IAMjB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI7C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ1D,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,sBAAsB;IAM9B,KAAK,IAAI,IAAI;CAiBd"}

package/dist/realtime/inbox-client.js

@@ -1,12 +1,3 @@
-// The Inbox realtime client: a SEPARATE WebSocket (scope `inbox`) to the user's
-// inbox DO. It maintains the channel/invite registry + unread projection that
-// drives the inbox view — DOTS ONLY, no counts (Contract C / "Unread + inbox").
-//
-// The inbox DO pushes a full `snapshot` ({ registry, hasUnread }) on connect, on
-// `resume`, and on every live delta (a projection apply). This client just
-// mirrors the latest snapshot into an observable store + a per-channel unread set.
-// Same connection lifecycle as the channel client (subprotocol auth, reconnect,
-// 4401 re-grant once, 4403 stop, auth-switch teardown).
 import { createReconnectController, } from '@ttt-productions/realtime-core';
 import { ChatMarkReadResultPayloadSchema, SERVER_KINDS, CLIENT_KINDS, CHAT_CLOSE_CODES, } from '@ttt-productions/chat-schemas';
 import { buildFrame, parseFrame, isInboxSnapshot, } from './wire.js';
@@ -32,21 +23,12 @@ export class InboxClient {
     reauthAttempted = false;
     reconnectTimer = null;
     closedByUs = false;
-    /**
-     * The current lifecycle's number, advanced by every `connect()` and `close()`; a grant,
-     * timer, or socket callback of an older lifecycle is ignored (FRONTEND-108).
-     */
     lifecycle = 0;
     initialLoad;
-    /** Mark-reads sent on the current socket, awaiting their correlated result, by requestId. */
     pendingMarkReads = new Map();
-    /** Structured diagnostics emitter, or null when off (the default, zero-overhead). */
     diag;
-    /** Monotonic socket-open attempt counter (diagnostics correlation only). */
     connectAttempt = 0;
-    /** Why the CURRENT connect attempt is happening (diagnostics only). */
     reconnectCause = 'initial';
-    /** The last close code observed, carried into the next attempt's cause line. */
     lastCloseCode = null;
     constructor(config) {
         this.config = config;
@@ -70,11 +52,6 @@ export class InboxClient {
     async connect() {
         return this.startLifecycle(true);
     }
-    /**
-     * Retry now (the first-open failure's Retry) — the same rule as `ChannelClient.retryNow`:
-     * a reconnect waiting out its backoff opens at once; a stopped lifecycle starts again; an
-     * attempt in flight is left to finish; the first-open failure clears either way.
-     */
     retryNow() {
         if (!this.state.hasLoadedInitialData)
             this.initialLoad.manualRetry();
@@ -96,25 +73,9 @@ export class InboxClient {
         void this.openSocket();
     }
     async startLifecycle(freshBudget) {
-        // Idempotency guard (mirrors ChannelClient): connect() only starts a lifecycle
-        // from a fresh (idle) or fully torn-down (closed) state. A second connect()
-        // while one is already connecting / open / reconnecting is a no-op, so a
-        // double-mounted dock cannot open a SECOND inbox socket against the per-uid
-        // cap. The reconnect path uses openSocket() / scheduleReconnect() directly
-        // (never connect()), so this never blocks a legitimate reconnect.
         if (this.state.status !== 'idle' && this.state.status !== 'closed')
             return;
-        // REVIVE the controller. `controller.close()` is PERMANENT: while it is in
-        // state `closed`, `start()` and `onOpen()` no-op and every later `onClose()`
-        // returns null — so without this reset a close() → connect() client opens a
-        // socket and works normally until its FIRST transient close, then parks
-        // terminally in `closed` with reconnect disabled and no surfaced error code.
         this.controller.reset();
-        // A terminal verdict (4403 REVOKED / ChatAccessDeniedError) is terminal WITHIN
-        // its lifecycle; an explicit connect() is a fresh attempt the authority may
-        // legitimately re-deny, so the previous lifecycle's code must not persist.
-        // The registry/unread projection is deliberately KEPT — the DO's next snapshot
-        // is authoritative, and blanking the dock on every restart is pure UI churn.
         if (isTerminalErrorCode(this.state.lastErrorCode))
             this.setState({ lastErrorCode: null });
         this.closedByUs = false;
@@ -147,11 +108,6 @@ export class InboxClient {
         catch (err) {
             if (lifecycle !== this.lifecycle)
                 return;
-            // A TERMINAL access denial (the app translated an authoritative policy "no"
-            // — e.g. Firebase `permission-denied` for a banned/suspended account — into the
-            // package-owned ChatAccessDeniedError) must NOT reconnect: the next mint would
-            // just re-deny, reconnect-looping forever and warning every cycle. Every other
-            // mint failure (network/transient) stays retryable and backs off as before.
             const terminal = isChatAccessDeniedError(err);
             this.diag?.(DIAG.INBOX_GRANT_FAILED, { attempt: this.connectAttempt, terminal });
             if (terminal)
@@ -161,12 +117,9 @@ export class InboxClient {
                 this.initialLoad.noteFailedAttempt();
             return this.scheduleReconnect();
         }
-        // A grant minted for an earlier lifecycle must never open a socket in this one.
         if (lifecycle !== this.lifecycle || this.closedByUs)
             return;
         const url = `${this.config.endpoint.replace(/\/$/, '')}/inbox`;
-        // Every callback is fenced to THIS socket: once it has been replaced or torn down, its
-        // late open, frames, and close are ignored.
         let socket = null;
         const isCurrent = () => socket !== null && this.socket === socket;
         socket = this.config.socketFactory({
@@ -200,10 +153,7 @@ export class InboxClient {
             registryCount: this.state.registry.length,
             hasUnread: this.state.hasUnread,
         });
-        // The DO sends a snapshot on accept; a `resume` re-requests it after a reconnect gap.
         const sent = this.sendFrame(CLIENT_KINDS.RESUME, {});
-        // The inbox resume is CURSORLESS by contract (the DO always answers with a full
-        // authoritative snapshot) — there is no `afterSeq` half to record here.
         this.diag?.(DIAG.INBOX_RESUME_REQUEST, {
             attempt: this.connectAttempt,
             cursorless: true,
@@ -213,7 +163,6 @@ export class InboxClient {
     onClose(code, _reason) {
         this.socket = null;
         this.lastCloseCode = code;
-        // A mark-read sent on this socket can no longer be answered.
         this.settlePendingMarkReads({ ok: false, code: 'connection-lost' });
         if (this.closedByUs) {
             this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: true, outcome: 'closed' });
@@ -242,14 +191,6 @@ export class InboxClient {
         this.diag?.(DIAG.INBOX_SOCKET_CLOSE, { code, closedByUs: false, outcome: 'reconnect' });
         this.scheduleReconnect();
     }
-    /**
-     * Terminal access denial surfaced by the inbox grant provider
-     * (`ChatAccessDeniedError`). Same terminal posture as the 4403 REVOKED close: mark
-     * closed-by-us, close the reconnect controller, and surface the stable
-     * `access-denied` code. The inbox client tracks NO optimistic/pending sends
-     * (mark-read is fire-and-forget with no local pending state), so — unlike
-     * ChannelClient — there is nothing to fail here; only the lifecycle stops.
-     */
     denyAccessTerminally() {
         this.closedByUs = true;
         this.controller.close();
@@ -285,9 +226,6 @@ export class InboxClient {
         }
         if (frame.type === SERVER_KINDS.MARK_READ_RESULT)
             return this.applyMarkReadResult(frame.payload);
-        // The inbox DO pushes a full `snapshot`; a future lightweight `unread` push
-        // carries either a full snapshot or a `{ hasUnread }` dock-dot patch. Route both
-        // instead of silently dropping the `unread` type (C-M2).
         if (frame.type !== 'snapshot' && frame.type !== 'unread') {
             this.diag?.(DIAG.INBOX_FRAME_DROPPED, {
                 kind: safeDiagnosticLabel(frame.type),
@@ -316,8 +254,6 @@ export class InboxClient {
             }
         }
         else {
-            // A stray CHANNEL snapshot ({ lastMessageSeq, readSeq }) on the inbox socket —
-            // deliberately inert, but never silently invisible under diagnostics.
             this.diag?.(DIAG.INBOX_FRAME_DROPPED, {
                 kind: safeDiagnosticLabel(frame.type),
                 reason: 'not-an-inbox-payload',
@@ -325,13 +261,7 @@ export class InboxClient {
         }
     }
     applySnapshot(snap, source) {
-        // Keep every non-tombstoned entry — including ARCHIVED rows — so the inbox view can
-        // render both the active list and the Archived toggle. `archived` is a distinct
-        // dimension from `tombstoned`; archived rows are still `state: 'active'`.
         const registry = snap.registry.filter((e) => e.state === 'active');
-        // The DO's `hasUnread` is the authoritative dock dot. Per-row dots are derived from
-        // the same projection but exclude ARCHIVED rows (archive = done — an archived row
-        // never shows a dot). The DO clears unread on archive, so this is belt-and-braces.
         const unreadChannelRefs = deriveUnreadRefs(snap);
         const hasUnread = Boolean(snap.hasUnread);
         const before = this.state;
@@ -346,12 +276,9 @@ export class InboxClient {
         });
         if (!this.diag)
             return;
-        // SIZES ONLY — a channelRef names one specific conversation and never enters a
-        // diagnostic line.
         this.diag(DIAG.INBOX_SNAPSHOT_APPLIED, {
             source: safeDiagnosticLabel(source),
             received: snap.registry.length,
-            // `received - active` is the tombstoned count the client filtered out.
             active: registry.length,
             archived: registry.filter((e) => e.archived === true).length,
             hasUnread,
@@ -377,30 +304,17 @@ export class InboxClient {
         this.socket.send(buildFrame(type, payload));
         return true;
     }
-    /** True if a specific channel/invite currently carries an unread dot. */
     channelHasUnread(channelRef) {
         return this.state.unreadChannelRefs.includes(channelRef);
     }
-    /**
-     * Clear a channel/invite's unread WITHOUT opening it (the inbox-view mark-read
-     * controls). Sends `mark-read` with a fresh `requestId`; the inbox runtime advances the
-     * member's read cursor, pushes a fresh authoritative snapshot (which is what removes
-     * the dot — there is NO optimistic local clear), and answers with a
-     * `mark-read-result` naming the same request. The promise settles on that answer —
-     * never on a timer — or with `not-sent` when no socket is open, or `connection-lost`
-     * when the socket closes first.
-     */
     markRead(channelRef) {
         const requestId = newCorrelationId();
         const sent = this.sendFrame(CLIENT_KINDS.MARK_READ, { channelRef, requestId });
-        // The ref itself is never logged — only that a mark-read was written and what the
-        // unread projection looked like at that moment (the DO's snapshot is what clears it).
         this.diag?.(DIAG.INBOX_MARK_READ, { sent, unreadCount: this.state.unreadChannelRefs.length });
         if (!sent)
             return Promise.resolve({ ok: false, code: 'not-sent' });
         return new Promise((resolve) => this.pendingMarkReads.set(requestId, resolve));
     }
-    /** Settle the mark-read the result names; a result naming no pending request is ignored. */
     applyMarkReadResult(payload) {
         const parsed = ChatMarkReadResultPayloadSchema.safeParse(payload);
         if (!parsed.success) {
@@ -422,7 +336,6 @@ export class InboxClient {
         for (const resolve of pending)
             resolve(outcome);
     }
-    /** Permanently close (auth-user switch / unmount). Idempotent. */
     close() {
         this.closedByUs = true;
         this.lifecycle += 1;
@@ -433,7 +346,6 @@ export class InboxClient {
             this.reconnectTimer = null;
         }
         if (this.socket) {
-            // Detach first: the socket's own late close is not this lifecycle's event.
             const socket = this.socket;
             this.socket = null;
             socket.close(1000, 'client teardown');
@@ -442,16 +354,6 @@ export class InboxClient {
         this.setState({ status: 'closed' });
     }
 }
-/**
- * Derive the per-channel unread set from a snapshot. The inbox DO's snapshot
- * carries a per-entry `unread` boolean on every active registry entry alongside
- * the global `hasUnread` roll-up that drives the dock dot. An entry without the
- * field (a legacy/pre-per-entry row) simply carries no per-row dot — the dock dot
- * still lights off `hasUnread`.
- *
- * ARCHIVED rows are excluded from the unread roll-up (archive = done — the DO clears
- * unread on archive; the client also never counts them).
- */
 function deriveUnreadRefs(snap) {
     const refs = [];
     for (const e of snap.registry) {