statewire 0.18.2 → 0.19.0

package/src/host/socket.ts

@@ -5,22 +5,21 @@ import {
   negotiateProtocols,
 } from "../wire/protocol";
 import type { StatewireProtocol } from "../wire/protocol";
-import { applyDocumentOps, mainDocument } from "../wire/documents";
-import type { StatewireDocuments } from "../wire/documents";
 import { useEffect, useState } from "react";
 import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { getCommandsHost, getStateHost } from "./host";
+import { documentIdentity, getCommandsHost, getStateHost } from "./host";
 import type { CommandsHost, CommandsOutcome } from "./host";
 import { StatewireSendError } from "../types";
 import type { Statewire } from "../types";
 import type { StatewireHost } from "../host";
 import type { StatewireHostInternal } from "../host-internal";
 import { reviveValue } from "../wire/meta";
+import { sanitizeValue } from "../wire/ops";
 import {
   COMMAND_CAPACITY_RETRY_MS,
   MAX_COMMANDS_PER_FRAME,
-  MAX_CONTEXT_VALUE_BYTES,
+  MAX_EPHEMERAL_DOCUMENT_BYTES,
   MAX_FRAME_BODY_BYTES,
   MAX_INFLIGHT_COMMANDS_PER_CLIENT,
   MAX_INFLIGHT_COMMANDS_PER_HOST,
@@ -28,7 +27,6 @@ import {
 import { createMacrotaskPoster } from "../util/macrotask";
 import type { StatewireDocument } from "../document";
 import type { StatewirePath } from "../wire/ops";
-import type { StatewireCmd, StatewireEnvelope } from "../client/connection";
 import { frames as serveFrames, stream as serveStream } from "./http";
 
 export const CLIENT_ID_RE = /^[A-Za-z0-9._~-]{1,256}$/;
@@ -76,14 +74,21 @@ const MAX_SUBSCRIBERS = 1024;
 export const SUBSCRIBER_LIMIT_MESSAGE = "stream subscriber limit reached";
 const STREAM_QUEUE_SIZE = 256;
 
+type Cmd = StatewireHostInternal.Cmd;
+
 type WireOp = {
   op: string;
+  doc?: number;
   path?: StatewirePath;
   value?: unknown;
   meta?: StatewireDocument.MetaEntry[];
+  protocol?: string;
+  key?: readonly string[];
+  main?: boolean;
 };
 
 type Admission = {
+  protocol: string;
   seq: number;
   method: string;
   applied: boolean;
@@ -91,31 +96,44 @@ type Admission = {
   settled: boolean;
 };
 
+/** One statement lane: durable lanes live on the client record, ephemeral lanes on the attach. */
+type Lane = {
+  protocol: string;
+  clientId: string;
+  conn: Conn | null;
+  lastSeq: number;
+  results: Map<number, { ts: number; cmd: Cmd }>;
+  inflight: Map<number, Admission>;
+};
+
 export type ClientRec = {
   id: string;
-  lastSeq: number;
   touched: number;
-  results: Map<number, { ts: number; cmd: StatewireCmd }>;
-  inflight: Map<number, Admission>;
+  lanes: Map<string, Lane>;
   /** The auth captured at the record's first attach; later attaches must match. */
   principal: unknown;
 };
 
-// The ctx lane is attach scoped: a Conn is born with an empty context table
-// and outlives its socket so an admitted command keeps reading its last value.
+// A Conn outlives its socket so an admitted command keeps its attach view.
 export type Conn = {
   selection: StatewireProtocol.Selection;
   clientId: string;
   socket: StatewireHostInternal.Socket;
   open: boolean;
+  ready: boolean;
   sawFrame: boolean;
   lastSentAt: number;
   lease: string | null;
   /** The awaited `authorize` return captured at this attach's authorization. */
   auth: unknown;
-  ctxSeq: number;
-  context: Record<string, unknown> | null;
-  contextDocuments: StatewireDocuments.State;
+  lanes: Map<string, Lane>;
+  documents: Map<string, StatewireHost.Document>;
+  included: Set<string>;
+  view: Map<string, { doc: number; value: unknown }>;
+  nextDoc: number;
+  pendingApplied: Cmd[];
+  pendingCmds: Cmd[];
+  attach: StatewireHost.Attach;
 };
 
 type PendingConn = {
@@ -138,7 +156,6 @@ const violationReason = (error: unknown): string | null =>
     ? error.message
     : null;
 
-type CtxStatement = { seq: number; ops: unknown[] };
 type CmdStatement = {
   protocol: string;
   seq: number;
@@ -147,84 +164,55 @@ type CmdStatement = {
   meta?: unknown;
 };
 
-export type ParsedFrame = {
-  ctx: CtxStatement[];
-  cmd: CmdStatement[];
-};
+export type ParsedFrame = { 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 statements;
-};
-
 const frameEncoder = new TextEncoder();
 
 export const parseFrameValue = (frame: unknown): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
   const keys = Object.keys(frame);
   if (keys.length === 0) return violation("malformed frame");
-  const unknown = keys.filter((key) => key !== "ctx" && key !== "cmd").sort();
+  const unknown = keys.filter((key) => key !== "cmd").sort();
   if (unknown.length > 0)
     return violation(`unknown frame key: '${unknown[0]}'`);
-  const ctx: CtxStatement[] = [];
-  if (frame["ctx"] !== undefined) {
-    const lane = frame["ctx"];
-    if (Array.isArray(lane) && lane.length > MAX_COMMANDS_PER_FRAME) {
-      return violation("too many context statements");
-    }
-    for (const statement of parseLane(lane)) {
-      const ops = statement["ops"];
-      if (!Array.isArray(ops) || !ops.length)
-        return violation("invalid-context");
-      if (
-        frameEncoder.encode(JSON.stringify(ops)).byteLength >
-        MAX_CONTEXT_VALUE_BYTES
-      )
-        return violation("oversized-context");
-      ctx.push({ seq: statement["seq"] as number, ops });
-    }
-  }
+  const lane = frame["cmd"];
+  if (!Array.isArray(lane)) return violation("malformed frame");
+  if (lane.length === 0) return violation("empty lane");
+  if (lane.length > MAX_COMMANDS_PER_FRAME)
+    return violation("too many commands");
+  const prev = new Map<string, number>();
   const cmd: CmdStatement[] = [];
-  if (frame["cmd"] !== undefined) {
-    const lane = frame["cmd"];
-    if (Array.isArray(lane) && lane.length > MAX_COMMANDS_PER_FRAME) {
-      return violation("too many commands");
-    }
-    for (const statement of parseLane(lane)) {
-      const method = statement["method"];
-      if (
-        typeof method !== "string" ||
-        typeof statement["protocol"] !== "string" ||
-        !("params" in statement)
-      ) {
-        return violation("malformed statement");
-      }
-      cmd.push({
-        protocol: statement["protocol"] as string,
-        seq: statement["seq"] as number,
-        method,
-        params: statement["params"],
-        ...(statement["meta"] !== undefined && { meta: statement["meta"] }),
-      });
+  for (const statement of lane) {
+    if (!isPlainObject(statement)) return violation("malformed statement");
+    const seq = statement["seq"];
+    const method = statement["method"];
+    const protocol = statement["protocol"];
+    if (
+      typeof seq !== "number" ||
+      !Number.isInteger(seq) ||
+      seq < 1 ||
+      typeof method !== "string" ||
+      typeof protocol !== "string" ||
+      !("params" in statement)
+    ) {
+      return violation("malformed statement");
     }
+    const last = prev.get(protocol);
+    if (last !== undefined && seq !== last + 1)
+      return violation("malformed frame");
+    prev.set(protocol, seq);
+    cmd.push({
+      protocol,
+      seq,
+      method,
+      params: statement["params"],
+      ...(statement["meta"] !== undefined && { meta: statement["meta"] }),
+    });
   }
-  return { ctx, cmd };
+  return { cmd };
 };
 
 export const parseFrame = (raw: string): ParsedFrame => {
@@ -251,18 +239,19 @@ const encodePayload = (
   return { payload: value, ...(meta !== undefined && { meta }) };
 };
 
-const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
+const cmdOf = (adm: Admission, outcome: CommandsOutcome): Cmd => {
+  const at = { protocol: adm.protocol, seq: adm.seq };
   if (outcome.type === "accepted") {
-    return { seq: adm.seq, type: "result", ...encodePayload(outcome.payload) };
+    return { ...at, type: "result", ...encodePayload(outcome.payload) };
   }
   const failure =
     outcome.error instanceof StatewireSendError ? outcome.error.failure : null;
   switch (failure?.fate) {
     case "crashed":
-      return { seq: adm.seq, type: "crashed" };
+      return { ...at, type: "crashed" };
     case "failed":
       return {
-        seq: adm.seq,
+        ...at,
         type: "failed",
         ...(failure.message !== undefined && { message: failure.message }),
       };
@@ -273,14 +262,14 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
             ? `unknown method: '${adm.method}'`
             : failure.message;
         return {
-          seq: adm.seq,
+          ...at,
           type: "rejected",
           code: failure.code,
           ...(message !== undefined && { message }),
         };
       }
       return {
-        seq: adm.seq,
+        ...at,
         type: "rejected",
         ...(failure.message !== undefined && { message: failure.message }),
         ...encodePayload(failure.payload),
@@ -288,7 +277,7 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): StatewireCmd => {
     }
     default:
       return {
-        seq: adm.seq,
+        ...at,
         type: "failed",
         message:
           outcome.error instanceof Error
@@ -316,9 +305,7 @@ const parseInitialFrame = (raw: string) => {
   }
   return {
     headers: headers as Record<string, string>,
-    frame: Object.keys(lanes).length
-      ? parseFrameValue(lanes)
-      : { ctx: [], cmd: [] },
+    frame: Object.keys(lanes).length ? parseFrameValue(lanes) : { cmd: [] },
   };
 };
 
@@ -340,8 +327,9 @@ export type SocketHostState = {
   conns: Set<Conn>;
   pendingConns: Set<PendingConn>;
   pendingOps: WireOp[];
-  pendingApplied: Map<string, number[]>;
-  pendingCmds: Map<string, StatewireCmd[]>;
+  pendingApplied: Map<string, Cmd[]>;
+  pendingCmds: Map<string, Cmd[]>;
+  viewsDirty: boolean;
   idleWire: boolean;
   finished: StatewireHost.Fin | null;
   disposed: boolean;
@@ -368,6 +356,11 @@ const scheduleFlush = (h: SocketHostState) => {
   h.post();
 };
 
+const markViews = (h: SocketHostState) => {
+  h.viewsDirty = true;
+  scheduleFlush(h);
+};
+
 const recordOp = (
   h: SocketHostState,
   op: {
@@ -400,8 +393,10 @@ const attach = (h: SocketHostState, next: Statewire<unknown>) => {
   }
   if (nextState !== h.stateHost) {
     h.stateHost?.setOnOp(null);
+    h.stateHost?.setOnDocuments(null);
     h.stateHost = nextState;
     h.stateHost.setOnOp((op) => recordOp(h, op));
+    h.stateHost.setOnDocuments(() => markViews(h));
   }
   h.commandsHost = nextCommands;
 };
@@ -420,6 +415,7 @@ export const closeConn = (
   } catch {
     /* peer already gone */
   }
+  h.current?.detached?.(conn.attach);
   if (h.conns.size === 0 && h.heartbeatTimer !== null) {
     clearInterval(h.heartbeatTimer);
     h.heartbeatTimer = null;
@@ -436,6 +432,15 @@ export const sendTo = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+const violate = (h: SocketHostState, conn: Conn, reason: string) => {
+  sendTo(
+    h,
+    conn,
+    JSON.stringify({ fin: { reason: "protocol-error", message: reason } }),
+  );
+  closeConn(h, conn, 1008, reason);
+};
+
 export const atSubscriberLimit = (h: SocketHostState): boolean =>
   h.conns.size +
     [...h.pendingConns].filter((conn) => conn.authorizing).length >=
@@ -462,22 +467,163 @@ const setHeartbeatMs = (h: SocketHostState, ms: number) => {
   }
 };
 
+const durableLanes = function* (h: SocketHostState) {
+  for (const rec of h.clients.values()) yield* rec.lanes.values();
+};
+
+const allLanes = function* (h: SocketHostState) {
+  yield* durableLanes(h);
+  for (const conn of h.conns) yield* conn.lanes.values();
+};
+
 const idleLevel = (h: SocketHostState): boolean => {
   if (h.current?.work?.isIdle === false) return false;
-  for (const rec of h.clients.values()) {
-    if (rec.inflight.size > 0) return false;
+  for (const lane of allLanes(h)) {
+    if (lane.inflight.size > 0) return false;
   }
   return true;
 };
 
+const selects = (conn: Conn, protocol: string) =>
+  conn.selection.protocols.some((p) => p.name === protocol);
+
+// ─── views ──────────────────────────────────────────────
+
+const viewOf = (
+  h: SocketHostState,
+  conn: Conn,
+): Map<string, StatewireHost.Document> => {
+  const view = new Map<string, StatewireHost.Document>();
+  const shared = h.stateHost!.documents();
+  const hostMain = documentIdentity(h.protocol.name);
+  for (const p of conn.selection.protocols) {
+    if (p.record === "ephemeral") {
+      for (const [id, doc] of conn.documents)
+        if (doc.protocol === p.name) view.set(id, doc);
+    } else {
+      for (const [id, doc] of shared) {
+        if (
+          doc.protocol === p.name &&
+          id !== hostMain &&
+          (doc.main || conn.included.has(id))
+        )
+          view.set(id, doc);
+      }
+    }
+  }
+  return view;
+};
+
+const diffView = (h: SocketHostState, conn: Conn): WireOp[] => {
+  const current = viewOf(h, conn);
+  const ops: WireOp[] = [];
+  for (const [id, entry] of conn.view) {
+    if (current.has(id)) continue;
+    conn.view.delete(id);
+    ops.push({ op: "unmount", doc: entry.doc });
+  }
+  for (const [id, doc] of current) {
+    const entry = conn.view.get(id);
+    if (entry !== undefined && entry.value === doc.value) continue;
+    const { value, meta } = encodeDocument(doc.value);
+    if (entry === undefined) {
+      const number = conn.nextDoc++;
+      conn.view.set(id, { doc: number, value: doc.value });
+      ops.push({
+        op: "mount",
+        doc: number,
+        protocol: doc.protocol,
+        ...(doc.key !== null && { key: doc.key }),
+        ...(doc.main && { main: true }),
+        value,
+        ...(meta !== undefined && { meta }),
+      });
+    } else {
+      entry.value = doc.value;
+      ops.push({
+        op: "replace",
+        doc: entry.doc,
+        path: [],
+        value,
+        ...(meta !== undefined && { meta }),
+      });
+    }
+  }
+  return ops;
+};
+
+const attachOf = (h: SocketHostState, conn: Conn): StatewireHost.Attach => {
+  const requireSelected = (protocol: string) => {
+    const entry = conn.selection.protocols.find((p) => p.name === protocol);
+    if (entry === undefined)
+      throw new Error(`statewire: protocol ${protocol} was not negotiated`);
+    return entry;
+  };
+  return {
+    document: (protocol, key) => {
+      if (key === undefined && protocol === h.protocol.name)
+        return h.stateHost!.snapshot();
+      const view = viewOf(h, conn);
+      if (key !== undefined)
+        return view.get(documentIdentity(protocol, key))?.value;
+      for (const doc of view.values())
+        if (doc.protocol === protocol && doc.main) return doc.value;
+      return undefined;
+    },
+    mount: (protocol, value, key, main = key === undefined) => {
+      if (requireSelected(protocol).record !== "ephemeral")
+        throw new Error(`statewire: protocol ${protocol} is not ephemeral`);
+      const encoded = encodeDocument(value);
+      if (
+        frameEncoder.encode(JSON.stringify(encoded)).byteLength >
+        MAX_EPHEMERAL_DOCUMENT_BYTES
+      )
+        throw new Error("statewire: oversized ephemeral document");
+      const id = documentIdentity(protocol, key);
+      if (main) {
+        for (const [other, doc] of conn.documents) {
+          if (doc.protocol === protocol && doc.main && other !== id)
+            throw new Error(
+              `statewire: ${protocol} already has a main document`,
+            );
+        }
+      }
+      conn.documents.set(id, {
+        protocol,
+        key: key === undefined ? null : [...key],
+        main,
+        value: sanitizeValue(value),
+      });
+      markViews(h);
+    },
+    unmount: (protocol, key) => {
+      if (!conn.documents.delete(documentIdentity(protocol, key)))
+        throw new Error("statewire: document is not mounted");
+      markViews(h);
+    },
+    include: (protocol, key) => {
+      if (requireSelected(protocol).record !== undefined)
+        throw new Error(`statewire: protocol ${protocol} is not durable`);
+      conn.included.add(documentIdentity(protocol, key));
+      markViews(h);
+    },
+    exclude: (protocol, key) => {
+      conn.included.delete(documentIdentity(protocol, key));
+      markViews(h);
+    },
+  };
+};
+
+// ─── flush ──────────────────────────────────────────────
+
 export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
   flushTapSync(() => {});
   h.stateHost?.takeChanged();
-  for (const rec of h.clients.values()) {
-    for (const adm of rec.inflight.values()) {
+  for (const lane of allLanes(h)) {
+    for (const adm of lane.inflight.values()) {
       if (adm.applied && !adm.settled && !adm.appliedSent) {
         adm.appliedSent = true;
-        queueApplied(h, rec.id, adm.seq);
+        queueApplied(h, lane, adm);
       }
     }
   }
@@ -487,16 +633,21 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
     h.pendingOps.length === 0 &&
     h.pendingApplied.size === 0 &&
     h.pendingCmds.size === 0 &&
+    !h.viewsDirty &&
     fin === undefined &&
-    !edge
+    !edge &&
+    ![...h.conns].some(
+      (conn) => conn.pendingApplied.length > 0 || conn.pendingCmds.length > 0,
+    )
   ) {
     return;
   }
   h.idleWire = level;
+  h.viewsDirty = false;
   if (fin === undefined && edge && level && h.finOnIdle) {
     fin = { reason: "idle" };
   }
-  const ops = h.pendingOps;
+  const mainOps = h.pendingOps;
   const applied = h.pendingApplied;
   const cmds = h.pendingCmds;
   h.pendingOps = [];
@@ -506,26 +657,34 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
   // 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 (!conn.ready) continue;
+    const forConn = (list: Cmd[] | undefined) =>
+      (list ?? []).filter((cmd) => selects(conn, cmd.protocol));
+    const ops = [
+      ...(selects(conn, h.protocol.name) ? mainOps : []),
+      ...diffView(h, conn),
+    ];
+    const appliedEntries = [
+      ...forConn(applied.get(conn.clientId)),
+      ...conn.pendingApplied.splice(0),
+    ];
     if (ops.length > 0) {
-      const packet: StatewireEnvelope = {
-        ops: conn.selection.protocols.some((p) => p.name === h.protocol.name)
-          ? ops
-          : [],
-        ...(appliedEntries.length > 0 && { cmd: appliedEntries }),
-        ...(edge && { idle: level }),
-      };
-      sendTo(h, conn, JSON.stringify(packet));
+      sendTo(
+        h,
+        conn,
+        JSON.stringify({
+          ops,
+          ...(appliedEntries.length > 0 && { cmd: appliedEntries }),
+          ...(edge && { idle: level }),
+        }),
+      );
     } else if (appliedEntries.length > 0) {
       sendTo(h, conn, JSON.stringify({ cmd: appliedEntries }));
     }
-    const verdicts = (cmds.get(conn.clientId) ?? []).map((cmd) =>
-      conn.selection.protocols.some((p) => p.name === h.protocol.name)
-        ? cmd
-        : { seq: cmd.seq, ...(cmd.dur === undefined ? {} : { dur: cmd.dur }) },
-    );
+    const verdicts = [
+      ...forConn(cmds.get(conn.clientId)),
+      ...conn.pendingCmds.splice(0),
+    ];
     if (verdicts.length > 0) {
       sendTo(h, conn, JSON.stringify({ cmd: verdicts }));
     }
@@ -539,17 +698,24 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
   }
 };
 
-const queueApplied = (h: SocketHostState, clientId: string, seq: number) => {
-  const list = h.pendingApplied.get(clientId);
-  if (list) list.push(seq);
-  else h.pendingApplied.set(clientId, [seq]);
+const queueApplied = (h: SocketHostState, lane: Lane, adm: Admission) => {
+  const cmd: Cmd = { protocol: adm.protocol, seq: adm.seq, type: "applied" };
+  if (lane.conn !== null) lane.conn.pendingApplied.push(cmd);
+  else {
+    const list = h.pendingApplied.get(lane.clientId);
+    if (list) list.push(cmd);
+    else h.pendingApplied.set(lane.clientId, [cmd]);
+  }
   scheduleFlush(h);
 };
 
-const queueCmd = (h: SocketHostState, clientId: string, cmd: StatewireCmd) => {
-  const list = h.pendingCmds.get(clientId);
-  if (list) list.push(cmd);
-  else h.pendingCmds.set(clientId, [cmd]);
+const queueCmd = (h: SocketHostState, lane: Lane, cmd: Cmd) => {
+  if (lane.conn !== null) lane.conn.pendingCmds.push(cmd);
+  else {
+    const list = h.pendingCmds.get(lane.clientId);
+    if (list) list.push(cmd);
+    else h.pendingCmds.set(lane.clientId, [cmd]);
+  }
   scheduleFlush(h);
 };
 
@@ -557,80 +723,116 @@ const notifyClientRecords = (h: SocketHostState) => {
   h.persistence?.onClientRecordsChange?.(
     [...h.clients.values()].map((rec) => ({
       id: rec.id,
-      lastSeq: admittedThrough(rec),
       touched: rec.touched,
-      results: [...rec.results].map(([seq, entry]) => ({
-        seq,
-        ts: entry.ts,
-        cmd: entry.cmd,
-      })),
+      lanes: Object.fromEntries(
+        [...rec.lanes.values()].map((lane) => [
+          lane.protocol,
+          {
+            lastSeq: admittedThrough(lane),
+            results: [...lane.results].map(([seq, entry]) => ({
+              seq,
+              ts: entry.ts,
+              cmd: entry.cmd,
+            })),
+          },
+        ]),
+      ),
       principal: rec.principal,
     })),
   );
 };
 
-const retain = (rec: ClientRec, cmd: StatewireCmd) => {
+const retain = (lane: Lane, cmd: Cmd) => {
   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) {
+  lane.results.set(cmd.seq, { ts: now, cmd });
+  const newest = Math.max(...lane.results.keys());
+  for (const [seq, entry] of lane.results) {
     if (seq !== newest && now - entry.ts > RESULT_TTL_MS) {
-      rec.results.delete(seq);
+      lane.results.delete(seq);
     }
   }
-  while (rec.results.size > RESULT_LIMIT) {
-    rec.results.delete(Math.min(...rec.results.keys()));
+  while (lane.results.size > RESULT_LIMIT) {
+    lane.results.delete(Math.min(...lane.results.keys()));
   }
 };
 
-/** Cmd-lane watermark: the last statement admitted, settled or not. */
-const admittedThrough = (rec: ClientRec): number =>
-  Math.max(rec.lastSeq, ...rec.inflight.keys());
+/** Lane watermark: the last statement admitted, settled or not. */
+const admittedThrough = (lane: Lane): number =>
+  Math.max(lane.lastSeq, ...lane.inflight.keys());
+
+const watermark = (h: SocketHostState, conn: Conn, protocol: string) => {
+  const entry = conn.selection.protocols.find((p) => p.name === protocol)!;
+  const lane =
+    entry.record === "ephemeral"
+      ? conn.lanes.get(protocol)
+      : h.clients.get(conn.clientId)?.lanes.get(protocol);
+  return lane === undefined ? 0 : admittedThrough(lane);
+};
+
+const laneOf = (h: SocketHostState, conn: Conn, protocol: string): Lane => {
+  const entry = conn.selection.protocols.find((p) => p.name === protocol);
+  if (entry === undefined) return violation("unsupported protocol");
+  const ephemeral = entry.record === "ephemeral";
+  const lanes = ephemeral ? conn.lanes : h.clients.get(conn.clientId)!.lanes;
+  let lane = lanes.get(protocol);
+  if (lane === undefined) {
+    lane = {
+      protocol,
+      clientId: conn.clientId,
+      conn: ephemeral ? conn : null,
+      lastSeq: 0,
+      results: new Map(),
+      inflight: new Map(),
+    };
+    lanes.set(protocol, lane);
+  }
+  return lane;
+};
 
 // 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: SocketHostState, rec: ClientRec, seq: number) => {
-  const cached = rec.results.get(seq);
+const reemit = (h: SocketHostState, lane: Lane, seq: number) => {
+  const cached = lane.results.get(seq);
   if (cached) {
-    const newest = Math.max(...rec.results.keys());
+    const newest = Math.max(...lane.results.keys());
     if (seq === newest || Date.now() - cached.ts <= RESULT_TTL_MS) {
-      queueCmd(h, rec.id, cached.cmd);
+      queueCmd(h, lane, cached.cmd);
       return;
     }
-    rec.results.delete(seq);
+    lane.results.delete(seq);
     notifyClientRecords(h);
   }
-  const adm = rec.inflight.get(seq);
+  const adm = lane.inflight.get(seq);
   if (adm) {
-    if (adm.applied) queueApplied(h, rec.id, seq);
+    if (adm.applied) queueApplied(h, lane, adm);
     return;
   }
-  queueCmd(h, rec.id, { seq, type: "expired" });
+  queueCmd(h, lane, { protocol: lane.protocol, seq, type: "expired" });
 };
 
 const settleCmd = (
   h: SocketHostState,
-  rec: ClientRec,
+  lane: Lane,
   adm: Admission,
-  cmd: StatewireCmd,
+  cmd: Cmd,
 ) => {
   if (adm.settled) return;
   adm.settled = true;
-  rec.inflight.delete(adm.seq);
-  retain(rec, cmd);
-  rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
+  lane.inflight.delete(adm.seq);
+  retain(lane, cmd);
+  lane.lastSeq = Math.max(lane.lastSeq, adm.seq);
   adm.applied = true;
-  queueCmd(h, rec.id, cmd);
-  notifyClientRecords(h);
+  queueCmd(h, lane, cmd);
+  if (lane.conn === null) notifyClientRecords(h);
 };
 
 const settleWire = (
   h: SocketHostState,
-  rec: ClientRec,
+  lane: Lane,
   adm: Admission,
   outcome: CommandsOutcome,
-) => settleCmd(h, rec, adm, cmdOf(adm, outcome));
+) => settleCmd(h, lane, adm, cmdOf(adm, outcome));
 
 const callerOf = (
   h: SocketHostState,
@@ -639,9 +841,6 @@ const callerOf = (
 ): StatewireHost.Caller => ({
   clientId: rec.id,
   auth: conn.auth,
-  get context() {
-    return conn.context;
-  },
   get isConnected() {
     if (h.clients.get(rec.id) !== rec) return false;
     for (const conn of h.conns) {
@@ -653,11 +852,12 @@ const callerOf = (
 
 const rejectStatement = (
   h: SocketHostState,
-  rec: ClientRec,
+  lane: Lane,
   adm: Admission,
   message: string,
 ) =>
-  settleCmd(h, rec, adm, {
+  settleCmd(h, lane, adm, {
+    protocol: adm.protocol,
     seq: adm.seq,
     type: "rejected",
     code: "invalid-params",
@@ -666,33 +866,23 @@ const rejectStatement = (
 
 const admitCmd = (
   h: SocketHostState,
-  rec: ClientRec,
+  lane: Lane,
   conn: Conn,
   statement: CmdStatement,
 ) => {
+  const rec = h.clients.get(conn.clientId)!;
   const adm: Admission = {
+    protocol: statement.protocol,
     seq: statement.seq,
     method: statement.method,
     applied: false,
     appliedSent: false,
     settled: false,
   };
-  rec.inflight.set(statement.seq, adm);
-  notifyClientRecords(h);
-  if (
-    statement.protocol !== h.protocol.name ||
-    !conn.selection.protocols.some((p) => p.name === statement.protocol)
-  ) {
-    settleCmd(h, rec, adm, {
-      seq: adm.seq,
-      type: "rejected",
-      code: "unsupported-protocol",
-      message: "command protocol was not negotiated",
-    });
-    return;
-  }
+  lane.inflight.set(statement.seq, adm);
+  if (lane.conn === null) notifyClientRecords(h);
   if (!Array.isArray(statement.params)) {
-    rejectStatement(h, rec, adm, "params must be an array");
+    rejectStatement(h, lane, adm, "params must be an array");
     return;
   }
   let params = statement.params;
@@ -704,7 +894,7 @@ const admitCmd = (
     } catch (error) {
       rejectStatement(
         h,
-        rec,
+        lane,
         adm,
         `invalid params: ${(error as Error).message}`,
       );
@@ -713,47 +903,75 @@ const admitCmd = (
   }
   if (statement.method === "statewire/commands") {
     if (params.length > 0) {
-      rejectStatement(h, rec, adm, "statewire/commands takes no params");
+      rejectStatement(h, lane, adm, "statewire/commands takes no params");
       return;
     }
     const names = [
       ...(h.commandsHost?.methods?.() ?? []),
       "statewire/commands",
     ].sort();
-    settleCmd(h, rec, adm, { seq: adm.seq, type: "result", payload: names });
+    settleCmd(h, lane, adm, {
+      protocol: adm.protocol,
+      seq: adm.seq,
+      type: "result",
+      payload: names,
+    });
     return;
   }
+  // Subprotocol methods are registered under their full wire name.
+  const method =
+    statement.protocol === h.protocol.name
+      ? statement.method
+      : `${statement.protocol}/${statement.method}`;
   h.commandsHost!.submit!({
-    method: statement.method,
+    method,
     params,
     clientId: rec.id,
     caller: callerOf(h, rec, conn),
+    attach: conn.attach,
     onApplied: () => {
       if (adm.settled || adm.applied) return;
       adm.applied = true;
-      rec.lastSeq = Math.max(rec.lastSeq, adm.seq);
-      notifyClientRecords(h);
+      lane.lastSeq = Math.max(lane.lastSeq, adm.seq);
+      if (lane.conn === null) notifyClientRecords(h);
       scheduleFlush(h);
     },
-    onSettle: (outcome) => settleWire(h, rec, adm, outcome),
+    onSettle: (outcome) => settleWire(h, lane, adm, outcome),
   }).catch((error: unknown) => {
-    if (!adm.settled) settleWire(h, rec, adm, { type: "rejected", error });
+    if (!adm.settled) settleWire(h, lane, adm, { type: "rejected", error });
   });
 };
 
-// One admission law, both lanes: absorbed statements answer from the record
-// (cmd) or the attach (ctx), 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.
+// One admission law, every lane: absorbed statements answer from their lane,
+// then the new suffix is admitted whole or the frame is refused whole via a
+// {syn} stating every lane's watermark, nothing consumed. A durable gap is
+// never a close; an ephemeral gap is a violation (the lane has no replay).
 export type FrameAdmission =
   | { type: "ok" }
   | {
       type: "refused";
       syn: {
-        syn: { seq: number; ctxSeq: number; retry?: number };
+        syn: { protocols: { name: string; seq: number }[]; retry?: number };
       };
     };
 
+const refusal = (
+  h: SocketHostState,
+  conn: Conn,
+  retry?: number,
+): FrameAdmission => ({
+  type: "refused",
+  syn: {
+    syn: {
+      protocols: conn.selection.protocols.map((p) => ({
+        name: p.name,
+        seq: watermark(h, conn, p.name),
+      })),
+      ...(retry !== undefined && { retry }),
+    },
+  },
+});
+
 export const admitFrame = (
   h: SocketHostState,
   conn: Conn,
@@ -761,81 +979,57 @@ export const admitFrame = (
 ): FrameAdmission => {
   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 > conn.ctxSeq);
-  const cmdNew = frame.cmd.filter((s) => s.seq > through);
-  if (
-    (ctxNew.length > 0 && ctxNew[0]!.seq !== conn.ctxSeq + 1) ||
-    (cmdNew.length > 0 && cmdNew[0]!.seq !== through + 1)
-  ) {
-    notifyClientRecords(h);
-    return {
-      type: "refused",
-      syn: { syn: { seq: through, ctxSeq: conn.ctxSeq } },
-    };
+  const lanes = new Map(
+    frame.cmd.map((s) => [s.protocol, laneOf(h, conn, s.protocol)]),
+  );
+  const through = new Map(
+    [...lanes].map(([protocol, lane]) => [protocol, admittedThrough(lane)]),
+  );
+  const fresh = frame.cmd.filter((s) => s.seq > through.get(s.protocol)!);
+  for (const s of frame.cmd) {
+    if (s.seq <= through.get(s.protocol)!)
+      reemit(h, lanes.get(s.protocol)!, s.seq);
   }
-  if (cmdNew.length > 0) {
-    let hostCommandLoad = 0;
-    for (const client of h.clients.values()) {
-      hostCommandLoad += client.inflight.size;
+  let durableNew = 0;
+  for (const [protocol, lane] of lanes) {
+    const first = fresh.find((s) => s.protocol === protocol);
+    if (first === undefined) continue;
+    if (first.seq !== through.get(protocol)! + 1) {
+      if (lane.conn !== null) return violation("ephemeral lane gap");
+      notifyClientRecords(h);
+      return refusal(h, conn);
     }
+    if (lane.conn === null)
+      durableNew += fresh.filter((s) => s.protocol === protocol).length;
+  }
+  if (durableNew > 0) {
+    let clientLoad = 0;
+    for (const lane of rec.lanes.values()) clientLoad += lane.inflight.size;
+    let hostLoad = 0;
+    for (const lane of durableLanes(h)) hostLoad += lane.inflight.size;
     if (
-      rec.inflight.size + cmdNew.length > MAX_INFLIGHT_COMMANDS_PER_CLIENT ||
-      hostCommandLoad + cmdNew.length > h.maxInflightCommands
+      clientLoad + durableNew > MAX_INFLIGHT_COMMANDS_PER_CLIENT ||
+      hostLoad + durableNew > h.maxInflightCommands
     ) {
-      return {
-        type: "refused",
-        syn: {
-          syn: {
-            seq: through,
-            ctxSeq: conn.ctxSeq,
-            retry: COMMAND_CAPACITY_RETRY_MS,
-          },
-        },
-      };
+      return refusal(h, conn, COMMAND_CAPACITY_RETRY_MS);
     }
   }
-  if ((ctxNew.length || cmdNew.length) && h.pushback) {
+  if (fresh.length > 0 && h.pushback) {
     const retry = h.pushback();
     if (retry !== null) {
       if (!Number.isSafeInteger(retry) || retry < 0)
         throw new TypeError(
           "pushback must return a nonnegative safe integer or null",
         );
-      return {
-        type: "refused",
-        syn: { syn: { seq: through, ctxSeq: conn.ctxSeq, retry } },
-      };
+      return refusal(h, conn, retry);
     }
   }
-  let contextDocuments = conn.contextDocuments;
-  try {
-    for (const statement of ctxNew)
-      contextDocuments = applyDocumentOps(
-        contextDocuments,
-        statement.ops,
-        conn.selection.protocols,
-        true,
-      );
-    if (
-      frameEncoder.encode(JSON.stringify([...contextDocuments.documents]))
-        .byteLength > MAX_CONTEXT_VALUE_BYTES
-    )
-      return violation("oversized-context");
-  } catch {
-    return violation("invalid-context");
-  }
-  conn.contextDocuments = contextDocuments;
-  conn.context = (mainDocument(contextDocuments, h.protocol.name)?.value ??
-    null) as Record<string, unknown> | null;
-  if (ctxNew.length) conn.ctxSeq = ctxNew.at(-1)!.seq;
-  for (const statement of cmdNew) admitCmd(h, rec, conn, statement);
-  if (cmdNew.length > 0) {
+  for (const s of fresh) admitCmd(h, lanes.get(s.protocol)!, conn, s);
+  for (const [protocol, lane] of lanes) {
+    const last = fresh.findLast((s) => s.protocol === protocol);
     // Memory host: admitted means retained — dur rides the admitting flush.
-    queueCmd(h, rec.id, { seq: cmdNew.at(-1)!.seq, dur: true });
+    if (last !== undefined && lane.conn === null)
+      queueCmd(h, lane, { protocol, seq: last.seq, dur: true });
   }
   notifyClientRecords(h);
   scheduleFlush(h);
@@ -860,38 +1054,15 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
   }
   const first = !conn.sawFrame;
   conn.sawFrame = true;
-  let frame: ParsedFrame;
-  try {
-    frame = first ? parseInitialFrame(data).frame : parseFrame(data);
-  } catch (error) {
-    const reason = violationReason(error);
-    if (reason === null) throw error;
-    sendTo(
-      h,
-      conn,
-      JSON.stringify({
-        fin: {
-          reason: "protocol-error",
-          message: reason,
-        },
-      }),
-    );
-    closeConn(h, conn, 1008, reason);
-    return;
-  }
-  if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
   let admission: ReturnType<typeof admitFrame>;
   try {
+    const frame = first ? parseInitialFrame(data).frame : parseFrame(data);
+    if (frame.cmd.length === 0) return;
     admission = admitFrame(h, conn, frame);
   } catch (error) {
     const reason = violationReason(error);
     if (reason === null) throw error;
-    sendTo(
-      h,
-      conn,
-      JSON.stringify({ fin: { reason: "protocol-error", message: reason } }),
-    );
-    closeConn(h, conn, 1008, reason);
+    violate(h, conn, reason);
     return;
   }
   if (admission.type === "refused") {
@@ -1146,26 +1317,23 @@ const connectAuthorized = (
           pending.open = false;
           h.pendingConns.delete(pending);
           if (pending.timer !== null) clearTimeout(pending.timer);
-          const registration = register(
-            h,
-            clientId,
-            socket,
-            true,
-            auth,
-            selection,
-          );
-          if (registration === null) return;
-          pending.connection = registration.connection;
-          if (frame.ctx.length || frame.cmd.length) {
-            message(
+          let registration: Registration | null;
+          try {
+            registration = register(
               h,
-              registration.conn,
-              JSON.stringify({
-                ...(frame.ctx.length ? { ctx: frame.ctx } : {}),
-                ...(frame.cmd.length ? { cmd: frame.cmd } : {}),
-              }),
+              clientId,
+              socket,
+              true,
+              auth,
+              selection,
+              frame,
             );
+          } catch (error) {
+            if (violationReason(error) === null) throw error;
+            return;
           }
+          if (registration === null) return;
+          pending.connection = registration.connection;
           for (const data of pending.queued.splice(0))
             registration.connection.message(data);
         })
@@ -1188,7 +1356,11 @@ const gcClients = (h: SocketHostState) => {
   const oldest = [...h.clients.values()].sort((a, b) => a.touched - b.touched);
   for (const rec of oldest) {
     if (excess <= 0) break;
-    if (live.has(rec.id) || rec.inflight.size > 0) continue;
+    if (
+      live.has(rec.id) ||
+      [...rec.lanes.values()].some((lane) => lane.inflight.size > 0)
+    )
+      continue;
     h.clients.delete(rec.id);
     changed = true;
     excess -= 1;
@@ -1201,6 +1373,11 @@ export type Registration = {
   connection: StatewireHostInternal.SocketConnection;
 };
 
+/**
+ * Attach a socket: ephemeral-lane statements of the attach frame are admitted
+ * before the snapshot (their documents and answers ride the hello), durable
+ * ones after it. A violation in the attach frame closes the attach and throws.
+ */
 export const register = (
   h: SocketHostState,
   clientId: string,
@@ -1211,6 +1388,7 @@ export const register = (
     version: h.wireVersion.version,
     protocols: [{ name: h.protocol.name, version: h.protocol.version }],
   },
+  frame: ParsedFrame = { cmd: [] },
 ): Registration | null => {
   const refuse = (code: number, reason: string) => {
     try {
@@ -1257,10 +1435,8 @@ export const register = (
     (() => {
       const created: ClientRec = {
         id: clientId,
-        lastSeq: 0,
         touched: Date.now(),
-        results: new Map(),
-        inflight: new Map(),
+        lanes: new Map(),
         principal: auth,
       };
       h.clients.set(clientId, created);
@@ -1272,39 +1448,78 @@ export const register = (
     clientId,
     socket,
     open: true,
+    ready: false,
     sawFrame,
     lastSentAt: 0,
     lease: null,
     auth,
-    ctxSeq: 0,
-    context: null,
-    contextDocuments: { mode: "mounted", documents: new Map() },
+    lanes: new Map(),
+    documents: new Map(),
+    included: new Set(),
+    view: new Map(),
+    nextDoc: 1,
+    pendingApplied: [],
+    pendingCmds: [],
+    attach: undefined!,
   };
+  conn.attach = attachOf(h, conn);
   h.conns.add(conn);
   gcClients(h);
-  notifyClientRecords(h);
   ensureHeartbeat(h);
-  const { value, meta } = encodeDocument(h.stateHost!.snapshot());
-  const hello: StatewireEnvelope = {
-    ops: [
-      {
-        op: "mount",
-        protocol: h.protocol.name,
-        main: true,
-        value,
-        ...(meta !== undefined && { meta }),
-      },
-    ],
+  const isEphemeral = (s: CmdStatement) =>
+    selection.protocols.find((p) => p.name === s.protocol)?.record ===
+    "ephemeral";
+  const early = frame.cmd.filter(isEphemeral);
+  const late = frame.cmd.filter((s) => !isEphemeral(s));
+  const admit = (statements: CmdStatement[]) => {
+    if (statements.length === 0) return null;
+    try {
+      return admitFrame(h, conn, { cmd: statements });
+    } catch (error) {
+      const reason = violationReason(error);
+      if (reason === null) throw error;
+      violate(h, conn, reason);
+      throw error;
+    }
+  };
+  const earlyAdmission = admit(early);
+  if (early.length > 0) flush(h);
+  notifyClientRecords(h);
+  const ops: WireOp[] = [];
+  if (selects(conn, h.protocol.name)) {
+    const { value, meta } = encodeDocument(h.stateHost!.snapshot());
+    ops.push({
+      op: "mount",
+      protocol: h.protocol.name,
+      main: true,
+      value,
+      ...(meta !== undefined && { meta }),
+    });
+  }
+  ops.push(...diffView(h, conn));
+  const answers = [
+    ...conn.pendingApplied.splice(0),
+    ...conn.pendingCmds.splice(0),
+  ];
+  const hello = {
+    ops,
     syn: {
-      ...selection,
-      seq: admittedThrough(rec),
-      ctxSeq: 0,
+      version: selection.version,
+      protocols: selection.protocols.map((p) => ({
+        ...p,
+        seq: p.record === "ephemeral" ? 0 : watermark(h, conn, p.name),
+      })),
       ...(h.idleWire && { idle: true }),
     },
+    ...(answers.length > 0 && { cmd: answers }),
   };
-  if (!selection.protocols.some((p) => p.name === h.protocol.name))
-    hello.ops = [];
+  conn.ready = true;
   sendTo(h, conn, JSON.stringify(hello));
+  if (earlyAdmission?.type === "refused")
+    sendTo(h, conn, JSON.stringify(earlyAdmission.syn));
+  const lateAdmission = admit(late);
+  if (lateAdmission?.type === "refused")
+    sendTo(h, conn, JSON.stringify(lateAdmission.syn));
   const connection: StatewireHostInternal.SocketConnection = {
     clientId,
     message: (data) => message(h, conn, data),
@@ -1342,6 +1557,7 @@ const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
 const resume = (h: SocketHostState) => {
   h.disposed = false;
   h.stateHost?.setOnOp((op) => recordOp(h, op));
+  h.stateHost?.setOnDocuments(() => markViews(h));
 };
 
 const suspend = (h: SocketHostState) => {
@@ -1351,6 +1567,7 @@ const suspend = (h: SocketHostState) => {
     h.heartbeatTimer = null;
   }
   h.stateHost?.setOnOp(null);
+  h.stateHost?.setOnDocuments(null);
 };
 
 const restoreClientRecords = (
@@ -1361,12 +1578,22 @@ const restoreClientRecords = (
       record.id,
       {
         id: record.id,
-        lastSeq: record.lastSeq,
         touched: record.touched,
-        results: new Map(
-          record.results.map(({ seq, ts, cmd }) => [seq, { ts, cmd }]),
+        lanes: new Map(
+          Object.entries(record.lanes).map(([protocol, lane]) => [
+            protocol,
+            {
+              protocol,
+              clientId: record.id,
+              conn: null,
+              lastSeq: lane.lastSeq,
+              results: new Map(
+                lane.results.map(({ seq, ts, cmd }) => [seq, { ts, cmd }]),
+              ),
+              inflight: new Map(),
+            },
+          ]),
         ),
-        inflight: new Map(),
         principal: record.principal,
       },
     ]),
@@ -1399,6 +1626,7 @@ const useSocketHost = (
       pendingOps: [],
       pendingApplied: new Map(),
       pendingCmds: new Map(),
+      viewsDirty: false,
       idleWire: true,
       finished: null,
       disposed: false,
@@ -1472,9 +1700,10 @@ 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 packet protocol — snapshot-first hello with `syn`,
- * statement-lane client frames under one admission law, `{cmd}` answer
- * arrays fanned out to every attach of a client id, idle edges, and `fin` on
- * finish.
+ * per-protocol statement lanes under one admission law, `{cmd}` answer
+ * arrays fanned out to every attach of a client id (durable lanes) or the
+ * admitting attach (ephemeral lanes), per-attach document views, idle edges,
+ * and `fin` on finish.
  */
 export const StatewireSocketHost = (
   transport: ResourceElement<Statewire>,