statewire 0.8.0 → 0.9.0

package/src/host/socket.ts

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
 import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { getCommandsHost, getEmitHost, getStateHost } from "./host";
+import { getCommandsHost, getStateHost } from "./host";
 import type { CommandsHost, CommandsOutcome } from "./host";
 import { StatewireSendError } from "../types";
 import type { Statewire } from "../types";
@@ -9,17 +9,14 @@ import type { StatewireHost } from "../host";
 import type { StatewireHostInternal } from "../host-internal";
 import { encodeValue, reviveValue } from "../wire/meta";
 import { createMacrotaskPoster } from "../util/macrotask";
-import { randomId } from "../util/randomId";
 import type { StatewireMetaEntry } from "../wire/meta";
 import type { StatewirePath } from "../wire/ops";
-import type {
-  StatewireEnvelope,
-  StatewireResponse,
-} from "../client/connection";
+import type { StatewireCmd, StatewireEnvelope } from "../client/connection";
 
 const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
 const RESULT_TTL_MS = 30_000;
 const RESULT_LIMIT = 256;
+const CLIENT_RECORD_LIMIT = 1024;
 
 type WireOp = {
   op: string;
@@ -31,17 +28,18 @@ type WireOp = {
 type Admission = {
   seq: number;
   method: string;
-  acked: boolean;
-  pendingSent: boolean;
+  applied: boolean;
+  appliedSent: boolean;
   settled: boolean;
-  release: () => void;
 };
 
 type ClientRec = {
   id: string;
   lastSeq: number;
+  ctxSeq: number;
+  touched: number;
   context: Record<string, unknown> | null;
-  results: Map<number, { ts: number; res: StatewireResponse }>;
+  results: Map<number, { ts: number; cmd: StatewireCmd }>;
   inflight: Map<number, Admission>;
 };
 
@@ -49,69 +47,140 @@ type Conn = {
   clientId: string;
   socket: StatewireHostInternal.Socket;
   open: boolean;
+  sawFrame: boolean;
   lastSentAt: number;
 };
 
-type Frame = {
-  method?: string;
+// ─── frame parsing ──────────────────────────────────────
+
+const violation = (reason: string): never => {
+  throw Object.assign(new Error(reason), { name: "StatewireViolation" });
+};
+
+const violationReason = (error: unknown): string | null =>
+  error instanceof Error && error.name === "StatewireViolation"
+    ? error.message
+    : null;
+
+type CtxStatement = { seq: number; value: Record<string, unknown> };
+type CmdStatement = {
   seq: number;
-  params: unknown[];
-  context?: unknown;
+  method: string;
+  params: unknown;
+  meta?: unknown;
 };
 
-const parseFrame = (raw: string): Frame | null => {
-  let frame: unknown;
-  try {
-    frame = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
-    return null;
-  }
-  const { method, seq, params, meta, context } = frame as Record<
-    string,
-    unknown
-  >;
-  if (method === undefined && context === undefined) return null;
-  if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1) return null;
-  if (method === undefined) {
-    return { seq, params: [], ...(context !== undefined && { context }) };
-  }
-  if (typeof method !== "string") return null;
-  if (!Array.isArray(params)) return null;
-  if (meta !== undefined) {
-    try {
-      reviveValue(params, meta);
-    } catch {
-      return null;
+type ParsedFrame = {
+  headers: Record<string, string> | null;
+  ctx: CtxStatement[];
+  cmd: CmdStatement[];
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const parseLane = (value: unknown): Record<string, unknown>[] => {
+  if (!Array.isArray(value)) return violation("malformed frame");
+  if (value.length === 0) return violation("empty lane");
+  const statements: Record<string, unknown>[] = [];
+  let prev: number | null = null;
+  for (const statement of value) {
+    if (!isPlainObject(statement)) return violation("malformed statement");
+    const seq = statement["seq"];
+    if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1) {
+      return violation("malformed statement");
     }
+    if (prev !== null && seq !== prev + 1) return violation("malformed frame");
+    prev = seq;
+    statements.push(statement);
   }
-  return { method, seq, params, ...(context !== undefined && { context }) };
+  return statements;
 };
 
-/** v1 context submissions are exactly one root replace with an object value. */
-const contextValue = (context: unknown): Record<string, unknown> => {
-  if (!Array.isArray(context) || context.length !== 1) {
+/** v1 ctx statements state the context whole: one root replace with an object value. */
+const contextValue = (ops: unknown): Record<string, unknown> => {
+  if (!Array.isArray(ops) || ops.length !== 1) {
     throw new Error("context must be a single-op array");
   }
-  const op = context[0] as Record<string, unknown> | null;
+  const op = ops[0] as Record<string, unknown> | null;
   if (
-    typeof op !== "object" ||
-    op === null ||
+    !isPlainObject(op) ||
     op["op"] !== "replace" ||
     !Array.isArray(op["path"]) ||
     op["path"].length !== 0
   ) {
     throw new Error("context op must be a root replace");
   }
-  const value = op["value"];
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+  const value =
+    op["meta"] !== undefined
+      ? reviveValue(op["value"], op["meta"])
+      : op["value"];
+  if (!isPlainObject(value)) {
     throw new Error("context value must be an object");
   }
-  return value as Record<string, unknown>;
+  return value;
+};
+
+const parseFrame = (raw: string, first: boolean): ParsedFrame => {
+  let frame: unknown;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    return violation("malformed frame");
+  }
+  if (!isPlainObject(frame)) return violation("malformed frame");
+  if (
+    frame["headers"] === undefined &&
+    frame["ctx"] === undefined &&
+    frame["cmd"] === undefined
+  ) {
+    return violation("malformed frame");
+  }
+  let headers: Record<string, string> | null = null;
+  if (frame["headers"] !== undefined) {
+    if (!first) return violation("mid-session headers");
+    const raw = frame["headers"];
+    if (
+      !isPlainObject(raw) ||
+      Object.values(raw).some((value) => typeof value !== "string")
+    ) {
+      return violation("malformed headers");
+    }
+    headers = raw as Record<string, string>;
+  }
+  const ctx: CtxStatement[] = [];
+  if (frame["ctx"] !== undefined) {
+    for (const statement of parseLane(frame["ctx"])) {
+      try {
+        ctx.push({
+          seq: statement["seq"] as number,
+          value: contextValue(statement["ops"]),
+        });
+      } catch {
+        return violation("invalid-context");
+      }
+    }
+  }
+  const cmd: CmdStatement[] = [];
+  if (frame["cmd"] !== undefined) {
+    for (const statement of parseLane(frame["cmd"])) {
+      const method = statement["method"];
+      if (typeof method !== "string" || !("params" in statement)) {
+        return violation("malformed statement");
+      }
+      cmd.push({
+        seq: statement["seq"] as number,
+        method,
+        params: statement["params"],
+        ...(statement["meta"] !== undefined && { meta: statement["meta"] }),
+      });
+    }
+  }
+  return { headers, ctx, cmd };
 };
 
+// ─── verdict encoding ───────────────────────────────────
+
 const encodePayload = (
   payload: unknown,
 ): { payload?: unknown; meta?: StatewireMetaEntry[] } => {
@@ -120,47 +189,43 @@ const encodePayload = (
   return { payload: value, ...(meta !== undefined && { meta }) };
 };
 
-const responseOf = (
-  adm: Admission,
-  outcome: CommandsOutcome,
-): StatewireResponse => {
+const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
   if (outcome.type === "accepted") {
-    return {
-      seq: adm.seq,
-      type: "accepted",
-      ...encodePayload(outcome.payload),
-    };
+    return { seq: adm.seq, type: "result", ...encodePayload(outcome.payload) };
   }
   const failure =
     outcome.error instanceof StatewireSendError ? outcome.error.failure : null;
   switch (failure?.fate) {
-    case "unknown-command":
+    case "failed":
       return {
         seq: adm.seq,
-        type: "rejected",
-        code: "unknown-command",
-        message: `unknown method: '${adm.method}'`,
+        type: "failed",
+        ...(failure.message !== undefined && { message: failure.message }),
       };
-    case "invalid-params":
-      return {
-        seq: adm.seq,
-        type: "rejected",
-        code: "invalid-params",
-        message: failure.message,
-      };
-    case "crashed":
-      return { seq: adm.seq, type: "crashed" };
-    case "rejected":
+    case "rejected": {
+      if (failure.code !== undefined) {
+        const message =
+          failure.code === "unknown-command"
+            ? `unknown method: '${adm.method}'`
+            : failure.message;
+        return {
+          seq: adm.seq,
+          type: "rejected",
+          code: failure.code,
+          ...(message !== undefined && { message }),
+        };
+      }
       return {
         seq: adm.seq,
         type: "rejected",
-        message: failure.message,
+        ...(failure.message !== undefined && { message: failure.message }),
         ...encodePayload(failure.payload),
       };
+    }
     default:
       return {
         seq: adm.seq,
-        type: "rejected",
+        type: "failed",
         message:
           outcome.error instanceof Error
             ? outcome.error.message
@@ -169,425 +234,564 @@ const responseOf = (
   }
 };
 
-const createSocketHost = (
-  options?: StatewireHostInternal.SocketHostOptions,
-) => {
-  const heartbeatMs = options?.heartbeatIntervalMs ?? 15_000;
-
-  const clients = new Map<string, ClientRec>();
-  const conns = new Set<Conn>();
-  let pendingOps: WireOp[] = [];
-  let dirtyAcks = new Set<string>();
-  let pendingRes = new Map<string, StatewireResponse[]>();
-  let inbox: Promise<void> = Promise.resolve();
-  let finished: StatewireHost.Fin | null = null;
-  let disposed = false;
-  let flushScheduled = false;
-  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
-
-  let stateHost: StatewireHost.StateHost | null = null;
-  let commandsHost: CommandsHost | null = null;
-  let emitHost: ReturnType<typeof getEmitHost> | null = null;
-  let current: Statewire<unknown> | null = null;
+// ─── host ───────────────────────────────────────────────
+
+type Host = {
+  heartbeatMs: number;
+  clientRecordLimit: number;
+  finOnIdle: boolean;
+  clients: Map<string, ClientRec>;
+  conns: Set<Conn>;
+  pendingOps: WireOp[];
+  pendingApplied: Map<string, number[]>;
+  pendingCmds: Map<string, StatewireCmd[]>;
+  idleWire: boolean;
+  finished: StatewireHost.Fin | null;
+  disposed: boolean;
+  flushScheduled: boolean;
+  heartbeatTimer: ReturnType<typeof setInterval> | null;
+  stateHost: StatewireHost.StateHost | null;
+  commandsHost: CommandsHost | null;
+  current: Statewire<unknown> | null;
+  post: () => void;
+  connect: (
+    clientId: string,
+    socket: StatewireHostInternal.Socket,
+  ) => StatewireHostInternal.SocketConnection;
+  finish: (fin: StatewireHost.Fin) => void;
+};
 
-  const post = createMacrotaskPoster(() => {
-    flushScheduled = false;
-    flush();
-  });
-  const scheduleFlush = () => {
-    if (flushScheduled || disposed) return;
-    flushScheduled = true;
-    post();
-  };
+const scheduleFlush = (h: Host) => {
+  if (h.flushScheduled || h.disposed) return;
+  h.flushScheduled = true;
+  h.post();
+};
 
-  const recordOp = (op: {
+const recordOp = (
+  h: Host,
+  op: {
     op: string;
     path?: StatewirePath;
     value?: unknown;
-  }) => {
-    if (op.op === "replace" || op.op === "add" || op.op === "event") {
-      const { value, meta } = encodeValue(op.value);
-      pendingOps.push({ ...op, value, ...(meta !== undefined && { meta }) });
-    } else {
-      pendingOps.push(op);
-    }
-    scheduleFlush();
-  };
+  },
+) => {
+  if (op.op === "replace" || op.op === "add") {
+    const { value, meta } = encodeValue(op.value);
+    h.pendingOps.push({ ...op, value, ...(meta !== undefined && { meta }) });
+  } else {
+    h.pendingOps.push(op);
+  }
+  scheduleFlush(h);
+};
 
-  const attach = (next: Statewire<unknown>) => {
-    if (next === current) return;
-    current = next;
-    const nextState =
-      typeof next.state === "object" && next.state !== null
-        ? getStateHost(next.state)
-        : undefined;
-    const nextCommands = getCommandsHost(next.commands);
-    const nextEmit = getEmitHost(next.emit);
-    if (!nextState || !nextCommands?.submit || !nextEmit) {
-      throw new Error(
-        "StatewireSocketHost requires a statewire/host transport (useStatewireState with object state, useStatewireCommands, useStatewireEmit)",
-      );
-    }
-    if (nextState !== stateHost) {
-      stateHost?.setOnOp(null);
-      stateHost = nextState;
-      stateHost.setOnOp(recordOp);
-    }
-    commandsHost = nextCommands;
-    if (nextEmit !== emitHost) {
-      emitHost?.setSink(null);
-      emitHost = nextEmit;
-      emitHost.setSink((event) => recordOp({ op: "event", value: event }));
-    }
-  };
+const attach = (h: Host, next: Statewire<unknown>) => {
+  if (next === h.current) return;
+  h.current = next;
+  const nextState =
+    typeof next.state === "object" && next.state !== null
+      ? getStateHost(next.state)
+      : undefined;
+  const nextCommands = getCommandsHost(next.commands);
+  if (!nextState || !nextCommands?.submit) {
+    throw new Error(
+      "StatewireSocketHost requires a statewire/host transport (useStatewireState with object state, useStatewireCommands)",
+    );
+  }
+  if (nextState !== h.stateHost) {
+    h.stateHost?.setOnOp(null);
+    h.stateHost = nextState;
+    h.stateHost.setOnOp((op) => recordOp(h, op));
+  }
+  h.commandsHost = nextCommands;
+};
 
-  const closeConn = (conn: Conn, code?: number, reason?: string) => {
-    if (!conn.open) return;
-    conn.open = false;
-    conns.delete(conn);
-    try {
-      conn.socket.close(code, reason);
-    } catch {
-      /* peer already gone */
-    }
-    if (conns.size === 0 && heartbeatTimer !== null) {
-      clearInterval(heartbeatTimer);
-      heartbeatTimer = null;
-    }
-  };
+const closeConn = (h: Host, conn: Conn, code?: number, reason?: string) => {
+  if (!conn.open) return;
+  conn.open = false;
+  h.conns.delete(conn);
+  try {
+    conn.socket.close(code, reason);
+  } catch {
+    /* peer already gone */
+  }
+  if (h.conns.size === 0 && h.heartbeatTimer !== null) {
+    clearInterval(h.heartbeatTimer);
+    h.heartbeatTimer = null;
+  }
+};
 
-  const sendTo = (conn: Conn, data: string) => {
-    if (!conn.open) return;
-    conn.lastSentAt = Date.now();
-    try {
-      conn.socket.send(data);
-    } catch {
-      closeConn(conn);
+const sendTo = (h: Host, conn: Conn, data: string) => {
+  if (!conn.open) return;
+  conn.lastSentAt = Date.now();
+  try {
+    conn.socket.send(data);
+  } catch {
+    closeConn(h, conn);
+  }
+};
+
+const ensureHeartbeat = (h: Host) => {
+  if (h.heartbeatTimer !== null || h.heartbeatMs <= 0) return;
+  h.heartbeatTimer = setInterval(() => {
+    const now = Date.now();
+    for (const conn of [...h.conns]) {
+      if (now - conn.lastSentAt >= h.heartbeatMs) sendTo(h, conn, "{}");
     }
-  };
+  }, h.heartbeatMs);
+  (h.heartbeatTimer as unknown as { unref?: () => void }).unref?.();
+};
 
-  const ensureHeartbeat = () => {
-    if (heartbeatTimer !== null || heartbeatMs <= 0) return;
-    heartbeatTimer = setInterval(() => {
-      const now = Date.now();
-      for (const conn of [...conns]) {
-        if (now - conn.lastSentAt >= heartbeatMs) sendTo(conn, "{}");
-      }
-    }, heartbeatMs);
-    (heartbeatTimer as unknown as { unref?: () => void }).unref?.();
-  };
+const setHeartbeatMs = (h: Host, ms: number) => {
+  if (ms === h.heartbeatMs) return;
+  h.heartbeatMs = ms;
+  if (h.heartbeatTimer !== null) {
+    clearInterval(h.heartbeatTimer);
+    h.heartbeatTimer = null;
+    ensureHeartbeat(h);
+  }
+};
 
-  const flush = (fin?: StatewireHost.Fin) => {
-    flushTapSync(() => {});
-    stateHost?.takeChanged();
-    for (const rec of clients.values()) {
-      for (const adm of rec.inflight.values()) {
-        if (adm.acked && !adm.settled && !adm.pendingSent) {
-          adm.pendingSent = true;
-          queueRes(rec.id, { seq: adm.seq, type: "pending" });
-        }
+const idleLevel = (h: Host): boolean => {
+  for (const rec of h.clients.values()) {
+    if (rec.inflight.size > 0) return false;
+  }
+  return true;
+};
+
+const flush = (h: Host, fin?: StatewireHost.Fin) => {
+  flushTapSync(() => {});
+  h.stateHost?.takeChanged();
+  for (const rec of h.clients.values()) {
+    for (const adm of rec.inflight.values()) {
+      if (adm.applied && !adm.settled && !adm.appliedSent) {
+        adm.appliedSent = true;
+        queueApplied(h, rec.id, adm.seq);
       }
     }
-    if (
-      pendingOps.length === 0 &&
-      dirtyAcks.size === 0 &&
-      pendingRes.size === 0 &&
-      fin === undefined
-    ) {
-      return;
+  }
+  const level = idleLevel(h);
+  const edge = level !== h.idleWire;
+  if (
+    h.pendingOps.length === 0 &&
+    h.pendingApplied.size === 0 &&
+    h.pendingCmds.size === 0 &&
+    fin === undefined &&
+    !edge
+  ) {
+    return;
+  }
+  h.idleWire = level;
+  if (fin === undefined && edge && level && h.finOnIdle) {
+    fin = { reason: "idle" };
+  }
+  const ops = h.pendingOps;
+  const applied = h.pendingApplied;
+  const cmds = h.pendingCmds;
+  h.pendingOps = [];
+  h.pendingApplied = new Map();
+  h.pendingCmds = new Map();
+  // Applied entries anchor to their effects: piggybacked on the ops packet
+  // when one is flushing, standalone otherwise. Terminal verdicts ride their
+  // own packet.
+  for (const conn of [...h.conns]) {
+    const appliedEntries: StatewireCmd[] = (
+      applied.get(conn.clientId) ?? []
+    ).map((seq) => ({ seq, type: "applied" }));
+    if (ops.length > 0) {
+      const packet: StatewireEnvelope = {
+        ops,
+        ...(appliedEntries.length > 0 && { cmd: appliedEntries }),
+        ...(edge && { idle: level }),
+      };
+      sendTo(h, conn, JSON.stringify(packet));
+    } else if (appliedEntries.length > 0) {
+      sendTo(h, conn, JSON.stringify({ cmd: appliedEntries }));
     }
-    const ops = pendingOps;
-    const acks = dirtyAcks;
-    const res = pendingRes;
-    pendingOps = [];
-    dirtyAcks = new Set();
-    pendingRes = new Map();
-    for (const conn of [...conns]) {
-      const envelope: StatewireEnvelope = {};
-      if (ops.length > 0) envelope.ops = ops;
-      const clientRes = res.get(conn.clientId);
-      if (clientRes !== undefined) envelope.res = clientRes;
-      if (acks.has(conn.clientId)) {
-        const rec = clients.get(conn.clientId);
-        if (rec !== undefined) envelope.ack = rec.lastSeq;
-      }
-      if (fin !== undefined) envelope.fin = fin;
-      if (Object.keys(envelope).length === 0) continue;
-      sendTo(conn, JSON.stringify(envelope));
-      if (fin !== undefined) closeConn(conn);
+    const verdicts = cmds.get(conn.clientId) ?? [];
+    if (verdicts.length > 0) {
+      sendTo(h, conn, JSON.stringify({ cmd: verdicts }));
     }
-  };
-
-  const queueRes = (clientId: string, response: StatewireResponse) => {
-    const list = pendingRes.get(clientId);
-    if (list) list.push(response);
-    else pendingRes.set(clientId, [response]);
-  };
-
-  const advance = (rec: ClientRec, seq: number) => {
-    rec.lastSeq = seq;
-    dirtyAcks.add(rec.id);
-  };
-
-  const retain = (rec: ClientRec, response: StatewireResponse) => {
-    const now = Date.now();
-    rec.results.set(response.seq, { ts: now, res: response });
-    const newest = Math.max(...rec.results.keys());
-    for (const [seq, entry] of rec.results) {
-      if (seq !== newest && now - entry.ts > RESULT_TTL_MS) {
-        rec.results.delete(seq);
-      }
+    if (edge && ops.length === 0) {
+      sendTo(h, conn, JSON.stringify({ idle: level }));
     }
-    while (rec.results.size > RESULT_LIMIT) {
-      rec.results.delete(Math.min(...rec.results.keys()));
+    if (fin !== undefined) {
+      sendTo(h, conn, JSON.stringify({ fin }));
+      closeConn(h, conn);
     }
-  };
+  }
+};
 
-  const duplicateAnswer = (rec: ClientRec, seq: number): StatewireResponse => {
-    const cached = rec.results.get(seq);
-    if (cached) {
-      const newest = Math.max(...rec.results.keys());
-      if (seq === newest || Date.now() - cached.ts <= RESULT_TTL_MS) {
-        return cached.res;
-      }
+const queueApplied = (h: Host, clientId: string, seq: number) => {
+  const list = h.pendingApplied.get(clientId);
+  if (list) list.push(seq);
+  else h.pendingApplied.set(clientId, [seq]);
+  scheduleFlush(h);
+};
+
+const queueCmd = (h: Host, clientId: string, cmd: StatewireCmd) => {
+  const list = h.pendingCmds.get(clientId);
+  if (list) list.push(cmd);
+  else h.pendingCmds.set(clientId, [cmd]);
+  scheduleFlush(h);
+};
+
+const retain = (rec: ClientRec, cmd: StatewireCmd) => {
+  const now = Date.now();
+  rec.results.set(cmd.seq, { ts: now, cmd });
+  const newest = Math.max(...rec.results.keys());
+  for (const [seq, entry] of rec.results) {
+    if (seq !== newest && now - entry.ts > RESULT_TTL_MS) {
       rec.results.delete(seq);
     }
-    if (rec.inflight.has(seq)) return { seq, type: "pending" };
-    return { seq, type: "result-unavailable" };
-  };
+  }
+  while (rec.results.size > RESULT_LIMIT) {
+    rec.results.delete(Math.min(...rec.results.keys()));
+  }
+};
 
-  const settleResponse = (
-    rec: ClientRec,
-    adm: Admission,
-    response: StatewireResponse,
-  ) => {
-    if (adm.settled) return;
-    adm.settled = true;
-    rec.inflight.delete(adm.seq);
-    retain(rec, response);
-    if (!adm.acked) {
-      adm.acked = true;
-      advance(rec, adm.seq);
-    }
-    if (
-      adm.pendingSent ||
-      response.type !== "accepted" ||
-      response.payload !== undefined
-    ) {
-      queueRes(rec.id, response);
+/** Cmd-lane watermark: the last statement admitted, settled or not. */
+const admittedThrough = (rec: ClientRec): number =>
+  Math.max(rec.lastSeq, ...rec.inflight.keys());
+
+// A re-asked seq never re-runs: the stored verdict re-emits, an applied
+// inflight run re-answers applied; one not yet applied answers nothing (its
+// answers ride the stream when ready), an evicted verdict answers expired.
+const reemit = (h: Host, rec: ClientRec, seq: number) => {
+  const cached = rec.results.get(seq);
+  if (cached) {
+    const newest = Math.max(...rec.results.keys());
+    if (seq === newest || Date.now() - cached.ts <= RESULT_TTL_MS) {
+      queueCmd(h, rec.id, cached.cmd);
+      return;
     }
-    scheduleFlush();
-    adm.release();
-  };
+    rec.results.delete(seq);
+  }
+  const adm = rec.inflight.get(seq);
+  if (adm) {
+    if (adm.applied) queueApplied(h, rec.id, seq);
+    return;
+  }
+  queueCmd(h, rec.id, { seq, type: "expired" });
+};
 
-  const settleWire = (
-    rec: ClientRec,
-    adm: Admission,
-    outcome: CommandsOutcome,
-  ) => settleResponse(rec, adm, responseOf(adm, outcome));
+const settleCmd = (
+  h: Host,
+  rec: ClientRec,
+  adm: Admission,
+  cmd: StatewireCmd,
+) => {
+  if (adm.settled) return;
+  adm.settled = true;
+  rec.inflight.delete(adm.seq);
+  retain(rec, cmd);
+  rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
+  adm.applied = true;
+  queueCmd(h, rec.id, cmd);
+};
 
-  const callerOf = (rec: ClientRec): StatewireHost.Caller => ({
-    clientId: rec.id,
-    get context() {
-      return rec.context;
-    },
-    get isConnected() {
-      if (clients.get(rec.id) !== rec) return false;
-      for (const conn of conns) {
-        if (conn.clientId === rec.id && conn.open) return true;
-      }
-      return false;
-    },
+const settleWire = (
+  h: Host,
+  rec: ClientRec,
+  adm: Admission,
+  outcome: CommandsOutcome,
+) => settleCmd(h, rec, adm, cmdOf(adm, outcome));
+
+const callerOf = (h: Host, rec: ClientRec): StatewireHost.Caller => ({
+  clientId: rec.id,
+  get context() {
+    return rec.context;
+  },
+  get isConnected() {
+    if (h.clients.get(rec.id) !== rec) return false;
+    for (const conn of h.conns) {
+      if (conn.clientId === rec.id && conn.open) return true;
+    }
+    return false;
+  },
+});
+
+const rejectStatement = (
+  h: Host,
+  rec: ClientRec,
+  adm: Admission,
+  message: string,
+) =>
+  settleCmd(h, rec, adm, {
+    seq: adm.seq,
+    type: "rejected",
+    code: "invalid-params",
+    message,
   });
 
-  const admit = (conn: Conn, frame: Frame): Promise<void> | void => {
-    if (!conn.open || disposed || finished !== null) return;
-    const rec = clients.get(conn.clientId)!;
-    if (frame.seq <= rec.lastSeq || rec.inflight.has(frame.seq)) {
-      queueRes(rec.id, duplicateAnswer(rec, frame.seq));
-      scheduleFlush();
-      return;
-    }
-    if (frame.seq > rec.lastSeq + 1) {
-      closeConn(
-        conn,
-        1008,
-        `seq gap: expected ${rec.lastSeq + 1}, got ${frame.seq}`,
+const admitCmd = (h: Host, rec: ClientRec, statement: CmdStatement) => {
+  const adm: Admission = {
+    seq: statement.seq,
+    method: statement.method,
+    applied: false,
+    appliedSent: false,
+    settled: false,
+  };
+  rec.inflight.set(statement.seq, adm);
+  if (!Array.isArray(statement.params)) {
+    rejectStatement(h, rec, adm, "params must be an array");
+    return;
+  }
+  let params = statement.params;
+  if (statement.meta !== undefined) {
+    try {
+      params = reviveValue(params, statement.meta) as unknown[];
+    } catch (error) {
+      rejectStatement(
+        h,
+        rec,
+        adm,
+        `invalid params: ${(error as Error).message}`,
       );
       return;
     }
-    const adm: Admission = {
-      seq: frame.seq,
-      method: frame.method ?? "",
-      acked: false,
-      pendingSent: false,
-      settled: false,
-      release: () => {},
-    };
-    if (frame.context !== undefined) {
-      let value: Record<string, unknown>;
-      try {
-        value = contextValue(frame.context);
-      } catch (error) {
-        rec.inflight.set(frame.seq, adm);
-        settleResponse(rec, adm, {
-          seq: frame.seq,
-          type: "rejected",
-          code: "invalid-context",
-          message: `invalid context: ${(error as Error).message}`,
-        });
-        return;
-      }
-      rec.context = value;
-      if (frame.method === undefined) {
-        rec.inflight.set(frame.seq, adm);
-        settleResponse(rec, adm, { seq: frame.seq, type: "accepted" });
-        return;
-      }
-    }
-    const released = new Promise<void>((resolve) => {
-      adm.release = resolve;
-    });
-    rec.inflight.set(frame.seq, adm);
-    commandsHost!.submit!({
-      method: frame.method!,
-      params: frame.params,
-      clientId: rec.id,
-      caller: callerOf(rec),
-      onAck: () => {
-        if (adm.settled || adm.acked) return;
-        adm.acked = true;
-        advance(rec, adm.seq);
-        scheduleFlush();
-        adm.release();
-      },
-      onSettle: (outcome) => settleWire(rec, adm, outcome),
-    }).catch((error: unknown) => {
-      if (!adm.settled) settleWire(rec, adm, { type: "rejected", error });
-    });
-    return released;
-  };
-
-  const message = (conn: Conn, data: string) => {
-    if (!conn.open || disposed || finished !== null) return;
-    const frame = parseFrame(data);
-    if (frame === null) {
-      closeConn(conn, 1008, "invalid frame");
+  }
+  if (statement.method === "statewire/commands") {
+    if (params.length > 0) {
+      rejectStatement(h, rec, adm, "statewire/commands takes no params");
       return;
     }
-    inbox = inbox.then(() => admit(conn, frame));
-  };
+    const names = [
+      ...(h.commandsHost?.methods?.() ?? []),
+      "statewire/commands",
+    ].sort();
+    settleCmd(h, rec, adm, { seq: adm.seq, type: "result", payload: names });
+    return;
+  }
+  h.commandsHost!.submit!({
+    method: statement.method,
+    params,
+    clientId: rec.id,
+    caller: callerOf(h, rec),
+    onApplied: () => {
+      if (adm.settled || adm.applied) return;
+      adm.applied = true;
+      rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
+      scheduleFlush(h);
+    },
+    onSettle: (outcome) => settleWire(h, rec, adm, outcome),
+  }).catch((error: unknown) => {
+    if (!adm.settled) settleWire(h, rec, adm, { type: "rejected", error });
+  });
+};
 
-  const connect = (
-    clientId: string,
-    socket: StatewireHostInternal.Socket,
-  ): StatewireHostInternal.SocketConnection => {
-    const dead: StatewireHostInternal.SocketConnection = {
-      clientId,
-      message: () => {},
-      close: () => {},
-    };
-    const refuse = (code: number, reason: string) => {
-      try {
-        socket.close(code, reason);
-      } catch {
-        /* peer already gone */
-      }
-      return dead;
-    };
-    if (disposed) return refuse(1001, "disposed");
-    if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
-    flush();
-    if (finished !== null) {
-      try {
-        socket.send(JSON.stringify({ fin: finished }));
-      } catch {
-        /* peer already gone */
-      }
-      return refuse(1000, "finished");
+// One admission law, both lanes: absorbed statements answer from the record,
+// then the new suffix is admitted whole or the frame is refused whole via a
+// {syn} stating both watermarks, nothing consumed. A gap is never a close.
+const admitFrame = (h: Host, conn: Conn, frame: ParsedFrame) => {
+  const rec = h.clients.get(conn.clientId)!;
+  rec.touched = Date.now();
+  const through = admittedThrough(rec);
+  for (const statement of frame.cmd) {
+    if (statement.seq <= through) reemit(h, rec, statement.seq);
+  }
+  const ctxNew = frame.ctx.filter((s) => s.seq > rec.ctxSeq);
+  const cmdNew = frame.cmd.filter((s) => s.seq > through);
+  if (
+    (ctxNew.length > 0 && ctxNew[0]!.seq !== rec.ctxSeq + 1) ||
+    (cmdNew.length > 0 && cmdNew[0]!.seq !== through + 1)
+  ) {
+    sendTo(
+      h,
+      conn,
+      JSON.stringify({ syn: { seq: through, ctxSeq: rec.ctxSeq } }),
+    );
+    return;
+  }
+  for (const statement of ctxNew) {
+    rec.context = statement.value;
+    rec.ctxSeq = statement.seq;
+  }
+  for (const statement of cmdNew) admitCmd(h, rec, statement);
+  if (cmdNew.length > 0) {
+    // Memory host: admitted means retained — dur rides the admitting flush.
+    queueCmd(h, rec.id, { seq: cmdNew.at(-1)!.seq, dur: true });
+  }
+  scheduleFlush(h);
+};
+
+const message = (h: Host, conn: Conn, data: string) => {
+  if (!conn.open || h.disposed || h.finished !== null) return;
+  const first = !conn.sawFrame;
+  conn.sawFrame = true;
+  let frame: ParsedFrame;
+  try {
+    frame = parseFrame(data, first);
+  } catch (error) {
+    const reason = violationReason(error);
+    if (reason === null) throw error;
+    closeConn(h, conn, 1008, reason);
+    return;
+  }
+  if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
+  admitFrame(h, conn, frame);
+};
+
+const gcClients = (h: Host) => {
+  let excess = h.clients.size - h.clientRecordLimit;
+  if (excess <= 0) return;
+  const live = new Set([...h.conns].map((conn) => conn.clientId));
+  const oldest = [...h.clients.values()].sort((a, b) => a.touched - b.touched);
+  for (const rec of oldest) {
+    if (excess <= 0) return;
+    if (live.has(rec.id) || rec.inflight.size > 0) continue;
+    h.clients.delete(rec.id);
+    excess -= 1;
+  }
+};
+
+const connect = (
+  h: Host,
+  clientId: string,
+  socket: StatewireHostInternal.Socket,
+): StatewireHostInternal.SocketConnection => {
+  const dead: StatewireHostInternal.SocketConnection = {
+    clientId,
+    message: () => {},
+    close: () => {},
+  };
+  const refuse = (code: number, reason: string) => {
+    try {
+      socket.close(code, reason);
+    } catch {
+      /* peer already gone */
     }
-    const known = clients.has(clientId);
-    const rec = known
-      ? clients.get(clientId)!
-      : (() => {
-          const created: ClientRec = {
-            id: clientId,
-            lastSeq: 0,
-            context: null,
-            results: new Map(),
-            inflight: new Map(),
-          };
-          clients.set(clientId, created);
-          return created;
-        })();
-    for (const other of [...conns]) {
-      if (other.clientId !== clientId) continue;
-      sendTo(other, JSON.stringify({ fin: { reason: "superseded" } }));
-      closeConn(other);
+    return dead;
+  };
+  if (h.disposed) return refuse(1001, "disposed");
+  if (!CLIENT_ID_RE.test(clientId)) return refuse(1008, "invalid client id");
+  flush(h);
+  if (h.finished !== null) {
+    try {
+      socket.send(JSON.stringify({ fin: h.finished }));
+    } catch {
+      /* peer already gone */
     }
-    const conn: Conn = { clientId, socket, open: true, lastSentAt: 0 };
-    conns.add(conn);
-    ensureHeartbeat();
-    const { value, meta } = encodeValue(stateHost!.snapshot());
-    const snapshot: StatewireEnvelope = {
-      ops: [
-        {
-          op: "replace",
-          path: [],
-          value,
-          ...(meta !== undefined && { meta }),
-        },
-      ],
-      syn: { lastSeq: known ? rec.lastSeq : -1, lease: randomId() },
-    };
-    sendTo(conn, JSON.stringify(snapshot));
-    return {
-      clientId,
-      message: (data) => message(conn, data),
-      close: () => closeConn(conn),
-    };
+    return refuse(1000, "finished");
+  }
+  const known = h.clients.has(clientId);
+  const rec = known
+    ? h.clients.get(clientId)!
+    : (() => {
+        const created: ClientRec = {
+          id: clientId,
+          lastSeq: 0,
+          ctxSeq: 0,
+          touched: Date.now(),
+          context: null,
+          results: new Map(),
+          inflight: new Map(),
+        };
+        h.clients.set(clientId, created);
+        return created;
+      })();
+  rec.touched = Date.now();
+  for (const other of [...h.conns]) {
+    if (other.clientId !== clientId) continue;
+    sendTo(h, other, JSON.stringify({ fin: { reason: "superseded" } }));
+    closeConn(h, other);
+  }
+  const conn: Conn = {
+    clientId,
+    socket,
+    open: true,
+    sawFrame: false,
+    lastSentAt: 0,
   };
-
-  const finish = (fin: StatewireHost.Fin) => {
-    if (finished !== null || disposed) return;
-    finished = fin;
-    flush(fin);
+  h.conns.add(conn);
+  gcClients(h);
+  ensureHeartbeat(h);
+  const { value, meta } = encodeValue(h.stateHost!.snapshot());
+  const hello: StatewireEnvelope = {
+    ops: [
+      {
+        op: "replace",
+        path: [],
+        value,
+        ...(meta !== undefined && { meta }),
+      },
+    ],
+    syn: {
+      seq: admittedThrough(rec),
+      ctxSeq: rec.ctxSeq,
+      record: known ? "resumed" : "fresh",
+      ...(h.idleWire && { idle: true }),
+    },
   };
-
+  sendTo(h, conn, JSON.stringify(hello));
   return {
-    connect,
-    finish,
-    attach,
-    resume: () => {
-      disposed = false;
-      stateHost?.setOnOp(recordOp);
-      emitHost?.setSink((event) => recordOp({ op: "event", value: event }));
-    },
-    suspend: () => {
-      disposed = true;
-      if (heartbeatTimer !== null) {
-        clearInterval(heartbeatTimer);
-        heartbeatTimer = null;
-      }
-      stateHost?.setOnOp(null);
-      emitHost?.setSink(null);
-    },
+    clientId,
+    message: (data) => message(h, conn, data),
+    close: () => closeConn(h, conn),
   };
 };
 
+const finish = (h: Host, fin: StatewireHost.Fin) => {
+  if (h.finished !== null || h.disposed) return;
+  h.finished = fin;
+  flush(h, fin);
+};
+
+const resume = (h: Host) => {
+  h.disposed = false;
+  h.stateHost?.setOnOp((op) => recordOp(h, op));
+};
+
+const suspend = (h: Host) => {
+  h.disposed = true;
+  if (h.heartbeatTimer !== null) {
+    clearInterval(h.heartbeatTimer);
+    h.heartbeatTimer = null;
+  }
+  h.stateHost?.setOnOp(null);
+};
+
 const useSocketHost = (
   transport: ResourceElement<Statewire>,
   options?: StatewireHostInternal.SocketHostOptions,
 ): Pick<StatewireHostInternal.SocketHost, "connect" | "finish"> => {
-  const [h] = useState(() => createSocketHost(options));
+  const [h] = useState((): Host => {
+    const host: Host = {
+      heartbeatMs: 15_000,
+      clientRecordLimit: CLIENT_RECORD_LIMIT,
+      finOnIdle: false,
+      clients: new Map(),
+      conns: new Set(),
+      pendingOps: [],
+      pendingApplied: new Map(),
+      pendingCmds: new Map(),
+      idleWire: true,
+      finished: null,
+      disposed: false,
+      flushScheduled: false,
+      heartbeatTimer: null,
+      stateHost: null,
+      commandsHost: null,
+      current: null,
+      post: createMacrotaskPoster(() => {
+        host.flushScheduled = false;
+        flush(host);
+      }),
+      connect: (clientId, socket) => connect(host, clientId, socket),
+      finish: (fin) => finish(host, fin),
+    };
+    return host;
+  });
+  setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  h.clientRecordLimit = options?.clientRecordLimit ?? CLIENT_RECORD_LIMIT;
+  h.finOnIdle = options?.finOnIdle ?? false;
   const value = useResource(transport) as Statewire<unknown>;
-  h.attach(value);
+  attach(h, value);
   useEffect(() => {
-    h.attach(value);
+    attach(h, value);
   });
   useEffect(() => {
-    h.resume();
-    return () => h.suspend();
+    resume(h);
+    return () => suspend(h);
   }, [h]);
   return h;
 };
@@ -595,8 +799,9 @@ const useSocketHost = (
 /**
  * Transport-agnostic WS binding over a statewire/host transport:
  * feed it sockets (anything with `send`/`close`) and raw text frames, and it
- * speaks the Statewire envelope protocol — snapshot-first attach with `syn`,
- * delta/ack/res envelopes, per-client-id supersede, and `fin` on finish.
+ * speaks the Statewire packet protocol — snapshot-first hello with `syn`,
+ * statement-lane client frames under one admission law, `{cmd}` answer
+ * arrays, per-client-id supersede, idle edges, and `fin` on finish.
  */
 export const StatewireSocketHost = (
   transport: ResourceElement<Statewire>,