@lumencast/protocol 0.1.0

package/src/conformance/scenario.ts

@@ -0,0 +1,71 @@
+// Scenario YAML loader. Mirrors the Go reference at
+// lumencast-go/conformance/scenario.go and the contract in
+// lumencast-protocol/conformance/v1/SCENARIO-FORMAT.md.
+
+import { parse as parseYaml } from "yaml";
+
+export type Tag = "required" | "recommended" | "extended";
+export type Target = "any" | "server" | "runtime";
+
+export type StepKind =
+  | "client-sends"
+  | "server-sends"
+  | "server-emits"
+  | "expect-runtime-state"
+  | "expect-server-state"
+  | "expect-no-frame-for"
+  | "expect-client-action";
+
+export type ClientAction = "close-with-reason" | "reconnect";
+
+export interface Step {
+  kind: StepKind;
+  /** client-sends, server-sends */
+  frame?: Record<string, unknown>;
+  /** expect-runtime-state, expect-server-state */
+  state?: Record<string, unknown>;
+  /** expect-no-frame-for */
+  duration_ms?: number;
+  /** expect-client-action */
+  action?: ClientAction;
+  reason?: string;
+}
+
+export interface BundleDecl {
+  id: string;
+  inline: Record<string, unknown>;
+  /** sha256:<hex> — populated lazily by computeBundleHashes(). */
+  hash?: string;
+}
+
+export interface Scenario {
+  name: string;
+  description: string;
+  tag: Tag;
+  target: Target;
+  spec_refs?: string[];
+  bundles?: BundleDecl[];
+  steps: Step[];
+}
+
+export function parseScenario(raw: string): Scenario {
+  const obj = parseYaml(raw) as Partial<Scenario> | undefined;
+  if (!obj || typeof obj !== "object") {
+    throw new Error("scenario: not a YAML mapping");
+  }
+  if (!obj.name) throw new Error("scenario: missing name");
+  if (!Array.isArray(obj.steps)) throw new Error("scenario: missing steps[]");
+
+  const tag: Tag = (obj.tag as Tag | undefined) ?? "required";
+  const target: Target = (obj.target as Target | undefined) ?? "any";
+
+  return {
+    name: obj.name,
+    description: obj.description ?? "",
+    tag,
+    target,
+    ...(obj.spec_refs ? { spec_refs: obj.spec_refs } : {}),
+    ...(obj.bundles ? { bundles: obj.bundles as BundleDecl[] } : {}),
+    steps: obj.steps as Step[],
+  };
+}

package/src/envelope.ts

@@ -0,0 +1,180 @@
+// Envelope helpers — convenience constructors that stamp `v` automatically.
+// Useful when emitting frames from a server or test fixture.
+
+import {
+  PROTOCOL_VERSION,
+  type Cause,
+  type DeltaFrame,
+  type ErrorCode,
+  type ErrorFrame,
+  type InputFrame,
+  type LeafPath,
+  type LeafValue,
+  type Patch,
+  type PingFrame,
+  type PongFrame,
+  type SceneChangedFrame,
+  type SceneId,
+  type SceneTransition,
+  type SceneVersion,
+  type SessionId,
+  type SnapshotFrame,
+  type SubscribeFrame,
+  type UnsubscribeFrame,
+} from "./types.js";
+
+export interface SnapshotInit {
+  seq: number;
+  scene_id: SceneId;
+  scene_version: SceneVersion;
+  state: Record<LeafPath, LeafValue>;
+  ts?: string;
+}
+
+export function snapshot(init: SnapshotInit): SnapshotFrame {
+  const frame: SnapshotFrame = {
+    v: PROTOCOL_VERSION,
+    type: "snapshot",
+    seq: init.seq,
+    scene_id: init.scene_id,
+    scene_version: init.scene_version,
+    state: init.state,
+  };
+  if (init.ts !== undefined) frame.ts = init.ts;
+  return frame;
+}
+
+export interface DeltaInit {
+  seq: number;
+  patches: Patch[];
+  ts?: string;
+  /** LSDP/1.1 §3.2.3 — optional provenance metadata. */
+  cause?: Cause;
+}
+
+export function delta(init: DeltaInit): DeltaFrame {
+  if (init.patches.length === 0) {
+    throw new Error("delta.patches must be non-empty");
+  }
+  const frame: DeltaFrame = {
+    v: PROTOCOL_VERSION,
+    type: "delta",
+    seq: init.seq,
+    patches: init.patches,
+  };
+  if (init.ts !== undefined) frame.ts = init.ts;
+  if (init.cause !== undefined) frame.cause = init.cause;
+  return frame;
+}
+
+export interface SceneChangedInit {
+  seq: number;
+  scene_id: SceneId;
+  scene_version: SceneVersion;
+  ts?: string;
+  /** LSDP/1.1 §3.3.1 — previously active scene id. */
+  from_scene_id?: SceneId;
+  /** LSDP/1.1 §3.3.1 — show-level scene transition. */
+  transition?: SceneTransition;
+}
+
+export function sceneChanged(init: SceneChangedInit): SceneChangedFrame {
+  const frame: SceneChangedFrame = {
+    v: PROTOCOL_VERSION,
+    type: "scene_changed",
+    seq: init.seq,
+    scene_id: init.scene_id,
+    scene_version: init.scene_version,
+  };
+  if (init.ts !== undefined) frame.ts = init.ts;
+  if (init.from_scene_id !== undefined) frame.from_scene_id = init.from_scene_id;
+  if (init.transition !== undefined) frame.transition = init.transition;
+  return frame;
+}
+
+export interface ErrorInit {
+  seq: number;
+  code: ErrorCode;
+  message: string;
+  recoverable: boolean;
+  /**
+   * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+   * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1.
+   */
+  path?: LeafPath;
+  retry_after_ms?: number;
+  requested_version?: string;
+  supported_version?: string;
+  session?: string;
+  ts?: string;
+}
+
+export function errorFrame(init: ErrorInit): ErrorFrame {
+  const frame: ErrorFrame = {
+    v: PROTOCOL_VERSION,
+    type: "error",
+    seq: init.seq,
+    code: init.code,
+    message: init.message,
+    recoverable: init.recoverable,
+  };
+  if (init.path !== undefined) frame.path = init.path;
+  if (init.retry_after_ms !== undefined) frame.retry_after_ms = init.retry_after_ms;
+  if (init.requested_version !== undefined) frame.requested_version = init.requested_version;
+  if (init.supported_version !== undefined) frame.supported_version = init.supported_version;
+  if (init.session !== undefined) frame.session = init.session;
+  if (init.ts !== undefined) frame.ts = init.ts;
+  return frame;
+}
+
+export function pong(nonce?: string): PongFrame {
+  const frame: PongFrame = { v: PROTOCOL_VERSION, type: "pong" };
+  if (nonce !== undefined) frame.nonce = nonce;
+  return frame;
+}
+
+export interface SubscribeInit {
+  token: string;
+  scene?: SceneId;
+  session?: SessionId;
+  /** LSDP/1.1 §4.1 — incremental resume from a known last-seen seq. */
+  since_sequence?: number;
+}
+
+export function subscribe(init: SubscribeInit): SubscribeFrame {
+  const frame: SubscribeFrame = {
+    v: PROTOCOL_VERSION,
+    type: "subscribe",
+    token: init.token,
+  };
+  if (init.scene !== undefined) frame.scene = init.scene;
+  if (init.session !== undefined) frame.session = init.session;
+  if (init.since_sequence !== undefined) frame.since_sequence = init.since_sequence;
+  return frame;
+}
+
+export interface InputInit {
+  patches: Patch[];
+  /** LSDP/1.1 §4.2 — optimistic-UI correlation tag. */
+  client_msg_id?: string;
+}
+
+export function input(patches: Patch[], init?: { client_msg_id?: string }): InputFrame {
+  if (patches.length === 0) {
+    throw new Error("input.patches must be non-empty");
+  }
+  const frame: InputFrame = { v: PROTOCOL_VERSION, type: "input", patches };
+  if (init?.client_msg_id !== undefined) frame.client_msg_id = init.client_msg_id;
+  return frame;
+}
+
+export function ping(nonce?: string): PingFrame {
+  const frame: PingFrame = { v: PROTOCOL_VERSION, type: "ping" };
+  if (nonce !== undefined) frame.nonce = nonce;
+  return frame;
+}
+
+/** LSDP/1.1 §4.4 — clean teardown signal. */
+export function unsubscribe(): UnsubscribeFrame {
+  return { v: PROTOCOL_VERSION, type: "unsubscribe" };
+}

package/src/errors.ts

@@ -0,0 +1,55 @@
+// Error helpers — typed exception + code-set membership check.
+// Code semantics live in lumencast-protocol/spec/ERROR-CODES.md.
+
+import type { ErrorCode } from "./types.js";
+
+const ERROR_CODES = new Set<ErrorCode>([
+  "AUTH_DENIED",
+  "WRITE_FORBIDDEN",
+  "SCENE_NOT_FOUND",
+  "BUNDLE_FETCH_FAILED",
+  "BUNDLE_INCOMPATIBLE",
+  "VERSION_GAP",
+  "VERSION_MISMATCH",
+  "UNKNOWN_PATH",
+  "INVALID_VALUE",
+  "RATE_LIMIT",
+  "TEST_SESSION_EXPIRED",
+  "INTERNAL",
+]);
+
+export function isProtocolErrorCode(value: unknown): value is ErrorCode {
+  return typeof value === "string" && ERROR_CODES.has(value as ErrorCode);
+}
+
+export interface LumencastErrorInit {
+  code: ErrorCode;
+  message: string;
+  recoverable: boolean;
+  /**
+   * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+   * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1.
+   */
+  path?: string;
+  retry_after_ms?: number;
+}
+
+/**
+ * Typed runtime exception. Mirrors the shape of an LSDP `error` frame so that
+ * runtime hosts can match `error.code` against the closed taxonomy.
+ */
+export class LumencastError extends Error {
+  readonly code: ErrorCode;
+  readonly recoverable: boolean;
+  readonly path: string | undefined;
+  readonly retry_after_ms: number | undefined;
+
+  constructor(init: LumencastErrorInit) {
+    super(init.message);
+    this.name = "LumencastError";
+    this.code = init.code;
+    this.recoverable = init.recoverable;
+    this.path = init.path;
+    this.retry_after_ms = init.retry_after_ms;
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+// Public surface of @lumencast/protocol.
+
+export {
+  PROTOCOL_VERSION,
+  WS_SUBPROTOCOL,
+  WS_SUBPROTOCOL_V1_1,
+  WS_SUBPROTOCOLS,
+  type Cause,
+  type ClientFrame,
+  type DeltaFrame,
+  type ErrorCode,
+  type ErrorFrame,
+  type InputFrame,
+  type LeafPath,
+  type LeafValue,
+  type Patch,
+  type PingFrame,
+  type PongFrame,
+  type SceneChangedFrame,
+  type SceneId,
+  type SceneTransition,
+  type SceneVersion,
+  type ServerFrame,
+  type SessionId,
+  type SnapshotFrame,
+  type SubscribeFrame,
+  type TransitionSpec,
+  type UnsubscribeFrame,
+} from "./types.js";
+
+export { LumencastError, isProtocolErrorCode, type LumencastErrorInit } from "./errors.js";
+
+export { encodeFrame, decodeServerFrame, decodeClientFrame } from "./codec.js";
+
+export { SequenceTracker, type SequenceObservation } from "./sequence.js";
+
+export {
+  RESERVED_NAMESPACES,
+  type ReservedNamespace,
+  parseLeafPath,
+  formatLeafPath,
+  isReservedPath,
+  isUnknownReservedPath,
+  substituteScope,
+} from "./leaf-path.js";
+
+export {
+  snapshot,
+  delta,
+  sceneChanged,
+  errorFrame,
+  pong,
+  subscribe,
+  input,
+  ping,
+  unsubscribe,
+  type SnapshotInit,
+  type DeltaInit,
+  type SceneChangedInit,
+  type ErrorInit,
+  type SubscribeInit,
+  type InputInit,
+} from "./envelope.js";

package/src/leaf-path.ts

@@ -0,0 +1,58 @@
+// LeafPath canonical form + scope substitution.
+// Reference: LSDP/1 §10 (reserved namespaces) and LSML 1.0 §7 (repeat scope).
+
+import type { LeafPath } from "./types.js";
+
+/** A path segment is alphanumeric + underscore. Numeric indices are decimal. */
+const SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$|^[0-9]+$/;
+
+/** Reserved top-level namespaces per LSDP/1 §10. */
+export const RESERVED_NAMESPACES = ["__inputs", "__system", "__test", "__schema"] as const;
+export type ReservedNamespace = (typeof RESERVED_NAMESPACES)[number];
+
+/** Parse a `LeafPath` string into its segments. Throws on malformed input. */
+export function parseLeafPath(path: LeafPath): string[] {
+  if (path.length === 0) throw new Error("leaf-path is empty");
+  const segs = path.split(".");
+  for (const s of segs) {
+    if (!SEGMENT_RE.test(s)) {
+      throw new Error(`leaf-path segment is not valid: ${s}`);
+    }
+  }
+  return segs;
+}
+
+/** Format an array of segments back to a `LeafPath`. */
+export function formatLeafPath(segments: string[]): LeafPath {
+  return segments.join(".");
+}
+
+/** True if the path begins with a reserved namespace (`__inputs`, `__system`, ...). */
+export function isReservedPath(path: LeafPath): boolean {
+  const head = path.split(".", 1)[0];
+  return (RESERVED_NAMESPACES as readonly string[]).includes(head ?? "");
+}
+
+/** True if the path begins with `__` but is NOT one of the four declared namespaces. */
+export function isUnknownReservedPath(path: LeafPath): boolean {
+  if (!path.startsWith("__")) return false;
+  const head = path.split(".", 1)[0] ?? "";
+  return !(RESERVED_NAMESPACES as readonly string[]).includes(head);
+}
+
+/**
+ * Substitute `{scope}` placeholders inside a path template.
+ * Used by `repeat` primitives to bind per-item paths.
+ *
+ * Example: `substituteScope("{player}.score", { player: "players.0" })`
+ *   → "players.0.score"
+ */
+export function substituteScope(template: LeafPath, scopes: Record<string, string>): LeafPath {
+  return template.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name: string) => {
+    const replacement = scopes[name];
+    if (replacement === undefined) {
+      throw new Error(`unknown scope identifier in path template: ${name}`);
+    }
+    return replacement;
+  });
+}

package/src/sequence.ts

@@ -0,0 +1,60 @@
+// Monotonic sequence tracker with gap detection.
+// LSDP/1.1 §18.1.1: seq is per-scene, NOT per-subscription. The first
+// frame of a fresh subscription can carry any seq >= 1 (late-joining
+// subscribers see the current scene seq). The tracker rebases to the
+// snapshot value after scene_changed via observeSnapshot.
+//
+// Receiver rules:
+//   - first frame on a fresh tracker → establish baseline (any seq >= 1)
+//   - seq > last + 1                 → gap, runtime MUST close + reconnect
+//   - seq <= last                    → replay, runtime MUST drop silently
+//   - seq == last + 1                → in-order, accept
+
+export type SequenceObservation =
+  | { kind: "in-order"; seq: number }
+  | { kind: "duplicate"; seq: number; lastSeq: number }
+  | { kind: "gap"; seq: number; lastSeq: number };
+
+export class SequenceTracker {
+  private lastSeq = 0;
+
+  /** Observe an incoming server seq. Returns the classification. */
+  observe(seq: number): SequenceObservation {
+    if (!Number.isInteger(seq) || seq < 1) {
+      // Treat malformed seq as a gap so the runtime reconnects.
+      return { kind: "gap", seq, lastSeq: this.lastSeq };
+    }
+    if (this.lastSeq === 0) {
+      // Fresh tracker — any seq >= 1 establishes the baseline
+      // (LSDP/1.1 §18.1.1).
+      this.lastSeq = seq;
+      return { kind: "in-order", seq };
+    }
+    if (seq <= this.lastSeq) {
+      return { kind: "duplicate", seq, lastSeq: this.lastSeq };
+    }
+    if (seq > this.lastSeq + 1) {
+      return { kind: "gap", seq, lastSeq: this.lastSeq };
+    }
+    this.lastSeq = seq;
+    return { kind: "in-order", seq };
+  }
+
+  /** Rebase the tracker to a snapshot's seq. Called after scene_changed
+   * or back-pressure recovery — the tracker takes the snapshot value as
+   * the new baseline regardless of previous state. */
+  observeSnapshot(seq: number): void {
+    if (Number.isInteger(seq) && seq >= 1) {
+      this.lastSeq = seq;
+    }
+  }
+
+  /** Reset the tracker. Called on reconnect with no resume. */
+  reset(): void {
+    this.lastSeq = 0;
+  }
+
+  get last(): number {
+    return this.lastSeq;
+  }
+}

package/src/types.ts

@@ -0,0 +1,201 @@
+// LSDP/1 wire types and shared shapes.
+// Canonical reference: lumencast-protocol/spec/LSDP-1.md (and ERROR-CODES.md, RUNTIME-API.md).
+
+/** LSDP major version. Bumped only on breaking envelope/semantic changes. */
+export const PROTOCOL_VERSION = 1 as const;
+
+/** LSDP/1.0 WebSocket subprotocol — see LSDP/1 §1. Kept for 1.0 client compat. */
+export const WS_SUBPROTOCOL = "lsdp.v1" as const;
+
+/** LSDP/1.1 WebSocket subprotocol — opts into the additive 1.1 frame surface
+ * (since_sequence resume, unsubscribe, transition, cause, nonce, client_msg_id,
+ * from_scene_id + show transition). See LSDP/1.1 envelope/header section. */
+export const WS_SUBPROTOCOL_V1_1 = "lsdp.v1.1" as const;
+
+/** Canonical advertise/accept list, ordered by preference (1.1 first, 1.0 fallback). */
+export const WS_SUBPROTOCOLS = [WS_SUBPROTOCOL_V1_1, WS_SUBPROTOCOL] as const;
+
+/** A leaf path expressed as a dot-separated string. See LSDP/1 §10 for reserved namespaces. */
+export type LeafPath = string;
+
+/** A scene identifier — operator-chosen, not derived. */
+export type SceneId = string;
+
+/** A scene version — sha256 hash prefixed with `sha256:`. */
+export type SceneVersion = string;
+
+/** A test session identifier. */
+export type SessionId = string;
+
+/** Permitted JSON values inside a `delta.patches[].value`. Objects are forbidden — push leaf-grain. */
+export type LeafValue = string | number | boolean | null | LeafValue[];
+
+/** Closed taxonomy of LSDP/1 error codes. Match by exact string equality. */
+export type ErrorCode =
+  | "AUTH_DENIED"
+  | "WRITE_FORBIDDEN"
+  | "SCENE_NOT_FOUND"
+  | "BUNDLE_FETCH_FAILED"
+  | "BUNDLE_INCOMPATIBLE"
+  | "VERSION_GAP"
+  | "VERSION_MISMATCH"
+  | "UNKNOWN_PATH"
+  | "INVALID_VALUE"
+  | "RATE_LIMIT"
+  | "TEST_SESSION_EXPIRED"
+  | "INTERNAL";
+
+/** Per-leaf animation directive on a delta patch (LSDP/1.1 §3.2.2).
+ * Servers MAY emit ; runtimes interpret when applying the new value.
+ * 1.0 receivers ignore. */
+export interface TransitionSpec {
+  kind: "tween" | "spring" | "snap";
+  /** tween only */
+  duration_ms?: number;
+  /** tween only */
+  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+  /** spring only */
+  stiffness?: number;
+  /** spring only */
+  damping?: number;
+}
+
+/** Optional provenance metadata on a delta (LSDP/1.1 §3.2.3). Receivers
+ * MUST NOT use it for semantic decisions — debug/audit only. */
+export interface Cause {
+  /** e.g. "operator:user-abc", "adapter:http_poll", "service:ranker" */
+  source: string;
+  /** Echoes InputFrame.client_msg_id verbatim when the delta was caused
+   * by an operator input. */
+  input_id?: string;
+}
+
+/** Show-level scene-swap transition on a scene_changed frame
+ * (LSDP/1.1 §3.3.1). Runtimes that don't recognise `kind` fall back
+ * to crossfade. */
+export interface SceneTransition {
+  kind: "crossfade" | (string & {}); // open string for vendor kinds
+  duration_ms?: number;
+}
+
+/** A leaf-grain patch. */
+export interface Patch {
+  path: LeafPath;
+  value: LeafValue;
+  /** Optional 1.1 per-leaf transition directive. */
+  transition?: TransitionSpec;
+}
+
+// --- Server → client frames -------------------------------------------------
+
+interface BaseFrame {
+  v: typeof PROTOCOL_VERSION;
+  /** Monotonically increasing per subscription. Required on server frames except `pong`. */
+  seq?: number;
+  /** ISO 8601 timestamp. SHOULD be sent on snapshots and errors; MAY be omitted on deltas. */
+  ts?: string;
+}
+
+export interface SnapshotFrame extends BaseFrame {
+  type: "snapshot";
+  seq: number;
+  scene_id: SceneId;
+  scene_version: SceneVersion;
+  /** Flat dictionary of leaf paths to JSON values. */
+  state: Record<LeafPath, LeafValue>;
+}
+
+export interface DeltaFrame extends BaseFrame {
+  type: "delta";
+  seq: number;
+  /** Non-empty array of patches; applied left-to-right, atomic per frame. */
+  patches: Patch[];
+  /** Optional provenance (LSDP/1.1 §3.2.3). Debug/audit only. */
+  cause?: Cause;
+}
+
+export interface SceneChangedFrame extends BaseFrame {
+  type: "scene_changed";
+  seq: number;
+  scene_id: SceneId;
+  scene_version: SceneVersion;
+  /** Previously active scene id (LSDP/1.1 §3.3.1). 1.0 receivers ignore. */
+  from_scene_id?: SceneId;
+  /** Show-level transition between old and new scene (LSDP/1.1 §3.3.1). */
+  transition?: SceneTransition;
+}
+
+export interface ErrorFrame extends BaseFrame {
+  type: "error";
+  seq: number;
+  code: ErrorCode;
+  message: string;
+  recoverable: boolean;
+  /**
+   * REQUIRED for path-scoped codes (`WRITE_FORBIDDEN`, `UNKNOWN_PATH`,
+   * `INVALID_VALUE`) per LSDP/1.0.1 §3.4.1. Forbidden for codes that
+   * are not path-scoped.
+   */
+  path?: LeafPath;
+  /** Optional, for `RATE_LIMIT`. */
+  retry_after_ms?: number;
+  /** Optional, for `BUNDLE_INCOMPATIBLE`. */
+  requested_version?: string;
+  supported_version?: string;
+  /** Optional, for `TEST_SESSION_EXPIRED`. */
+  session?: string;
+}
+
+export interface PongFrame {
+  v: typeof PROTOCOL_VERSION;
+  type: "pong";
+  /** Echoes PingFrame.nonce verbatim (LSDP/1.1 §3.5). 1.0 servers omit. */
+  nonce?: string;
+}
+
+export type ServerFrame = SnapshotFrame | DeltaFrame | SceneChangedFrame | ErrorFrame | PongFrame;
+
+// --- Client → server frames -------------------------------------------------
+
+export interface SubscribeFrame {
+  v: typeof PROTOCOL_VERSION;
+  type: "subscribe";
+  /** Opaque authentication token. */
+  token: string;
+  /** Required for test mode (preview a specific scene); forbidden for live. */
+  scene?: SceneId;
+  /** Required for test mode with isolated session; forbidden otherwise. */
+  session?: SessionId;
+  /** Last seq the client successfully observed before disconnect
+   * (LSDP/1.1 §4.1, §18). Server resumes with deltas from
+   * since_sequence+1 if the replay buffer covers, else fresh snapshot.
+   * 1.0 servers MUST ignore this field. Omit (or 0) means no resume. */
+  since_sequence?: number;
+}
+
+export interface InputFrame {
+  v: typeof PROTOCOL_VERSION;
+  type: "input";
+  /** Non-empty. Server validates each path against active scene's `operator_inputs`. */
+  patches: Patch[];
+  /** Free-form correlation tag (LSDP/1.1 §4.2). Server MUST echo
+   * verbatim in the resulting Delta.cause.input_id. 1.0 servers ignore. */
+  client_msg_id?: string;
+}
+
+export interface PingFrame {
+  v: typeof PROTOCOL_VERSION;
+  type: "ping";
+  /** Free-form correlation identifier (LSDP/1.1 §4.3). Receiver MUST
+   * echo verbatim in the Pong reply. */
+  nonce?: string;
+}
+
+/** Clean teardown signal (LSDP/1.1 §4.4). Server MUST close the
+ * WebSocket within 1 second of receipt. No data flows after. */
+export interface UnsubscribeFrame {
+  v: typeof PROTOCOL_VERSION;
+  type: "unsubscribe";
+}
+
+export type ClientFrame = SubscribeFrame | InputFrame | PingFrame | UnsubscribeFrame;