statewire 0.18.2 → 0.19.0

package/src/client/session.ts

@@ -1,4 +1,3 @@
-import { encodeDocument } from "../document";
 import { wrapStorageError } from "./storageError";
 import {
   DEFAULT_PROTOCOL,
@@ -30,7 +29,7 @@ import {
   SessionStorageContext,
   createMemorySessionStore,
 } from "./sessionStore";
-import { backoff } from "./timing";
+import { backoff, retryHint } from "./timing";
 import { createMethodProxy } from "../util/methodProxy";
 import { randomId as newClientId } from "../util/randomId";
 import { StatewireSendError } from "../types";
@@ -62,12 +61,6 @@ type Pending = {
   reject: (error: unknown) => void;
 };
 
-type CtxPending = {
-  readonly seq: number;
-  readonly ops: unknown[];
-  posted: boolean;
-};
-
 const protocolError = (message: string): never => {
   throw new Error(`statewire: protocol error: ${message}`);
 };
@@ -90,14 +83,13 @@ export type StatewireSessionOptions = StatewireProtocol.Options & {
 
 type Shared = {
   txq: Promise<void>;
-  parked: StatewireClient.SessionVerdict[];
+  parked: { protocol: string; verdict: StatewireClient.SessionVerdict }[];
   unsubscribe: (() => void) | null;
 };
 
 type Session = {
   options: StatewireSessionOptions;
   selection: StatewireProtocol.Selection | undefined;
-  contextDocuments: StatewireDocuments.State;
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
@@ -108,21 +100,24 @@ type Session = {
   store: StatewireClient.SessionStorage;
   documentStore: StatewireDocuments.Storage | undefined;
   shared: Shared | false;
+  /** Every selected lane is ephemeral: the record dies with the attach. */
   ephemeral: boolean;
   /** An ephemeral record died with its attach: the storage is off for good. */
   deactivated: boolean;
   sessionKnown: boolean;
-  durableSeq: number;
+  durableSeq: Record<string, number>;
+  /** Ephemeral lane clocks: restart at 1 on every attach. */
+  ephemeralSeqs: Record<string, number>;
   resumeAt: number;
   idle: boolean;
   onSessionLost: StatewireClient.OnSessionLost | undefined;
   onDone: (() => void) | undefined;
-  ctxNextSeq: number;
-  ctxPending: CtxPending[];
   lanesOnAttach: boolean;
-  attachLaneSeqs: readonly [ReadonlySet<number>, ReadonlySet<number>];
+  attachEntries: ReadonlySet<Pending>;
   frameFailures: number;
   pending: Pending[];
+  failedList: readonly StatewireClient.FailedCommand[];
+  failedParts: readonly (readonly StatewireClient.FailedCommand[])[];
   canonical: unknown;
   documentListeners: Set<() => void>;
   documents: StatewireDocuments.State;
@@ -140,6 +135,33 @@ type Session = {
   commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
 };
 
+const EMPTY_LANE: StatewireClient.SessionLane = { nextSeq: 1, commands: [] };
+
+const laneOf = (
+  record: StatewireClient.SessionRecord,
+  protocol: string,
+): StatewireClient.SessionLane => record.lanes[protocol] ?? EMPTY_LANE;
+
+const withLane = (
+  record: StatewireClient.SessionRecord,
+  protocol: string,
+  lane: StatewireClient.SessionLane,
+): StatewireClient.SessionRecord => ({
+  ...record,
+  lanes: { ...record.lanes, [protocol]: lane },
+});
+
+const isEphemeral = (s: Session, protocol: string) =>
+  s.selection?.protocols.some(
+    (p) => p.name === protocol && p.record === "ephemeral",
+  ) ?? false;
+
+const durableSeqOf = (s: Session, protocol: string) =>
+  s.durableSeq[protocol] ?? 0;
+
+const laneEntries = (s: Session, protocol: string) =>
+  s.pending.filter((p) => p.command.protocol === protocol);
+
 const publish = (s: Session) => {
   if (s.canonical === s.lastPublished) return;
   s.lastPublished = s.canonical;
@@ -186,43 +208,76 @@ const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
   }
 };
 
-const backlog = (s: Session): StatewireClient.SessionCommand[] =>
-  s.pending
-    .filter((p) => p.seq > s.durableSeq)
-    .map((p) => ({ seq: p.seq, ...p.command }));
+const toStored = (p: Pending): StatewireClient.SessionCommand => {
+  const { protocol: _protocol, ...command } = p.command;
+  return { seq: p.seq, ...command };
+};
+
+const backlog = (
+  s: Session,
+  protocol: string,
+): StatewireClient.SessionCommand[] =>
+  laneEntries(s, protocol)
+    .filter((p) => p.seq > durableSeqOf(s, protocol))
+    .map(toStored);
 
-const mergeBacklog = (s: Session): StatewireClient.SessionCommand[] => {
-  const own = backlog(s);
+const mergeBacklog = (
+  s: Session,
+  protocol: string,
+): StatewireClient.SessionCommand[] => {
+  const own = backlog(s, protocol);
   if (!s.shared) return own;
-  const known = new Set(s.pending.map((p) => p.seq));
-  const foreign = s.record.commands.filter(
-    (c) => !known.has(c.seq) && c.seq > s.durableSeq,
+  const known = new Set(laneEntries(s, protocol).map((p) => p.seq));
+  const foreign = laneOf(s.record, protocol).commands.filter(
+    (c) => !known.has(c.seq) && c.seq > durableSeqOf(s, protocol),
   );
   return [...foreign, ...own].sort((a, b) => a.seq - b.seq);
 };
 
+const durableLanes = (s: Session): string[] => [
+  ...new Set([
+    ...Object.keys(s.record.lanes),
+    ...s.pending
+      .map((p) => p.command.protocol)
+      .filter((protocol) => !isEphemeral(s, protocol)),
+  ]),
+];
+
 const MAX_PARKED_VERDICTS = 64;
 
 // Storage holds what a reload must resend: a command leaves at its dur, at a
 // server verdict, or at a record reset — never at a local channel death.
 const syncBacklogInner = (s: Session) => {
   const parked = s.shared ? s.shared.parked.splice(0) : [];
-  const parkedSeqs = new Set(parked.map((v) => v.seq));
-  const commands = mergeBacklog(s).filter((c) => !parkedSeqs.has(c.seq));
-  const verdicts =
-    parked.length > 0
-      ? [...(s.record.verdicts ?? []), ...parked].slice(-MAX_PARKED_VERDICTS)
-      : s.record.verdicts;
-  const unchanged =
-    verdicts === s.record.verdicts &&
-    commands.length === s.record.commands.length &&
-    commands.every((c, i) => c.seq === s.record.commands[i]!.seq);
-  if (unchanged) return;
-  setRecord(s, {
-    ...s.record,
-    commands,
-    ...(verdicts !== undefined && { verdicts }),
-  });
+  let lanes = s.record.lanes;
+  for (const protocol of durableLanes(s)) {
+    const lane = laneOf(s.record, protocol);
+    const parkedHere = parked
+      .filter((v) => v.protocol === protocol)
+      .map((v) => v.verdict);
+    const parkedSeqs = new Set(parkedHere.map((v) => v.seq));
+    const commands = mergeBacklog(s, protocol).filter(
+      (c) => !parkedSeqs.has(c.seq),
+    );
+    const verdicts =
+      parkedHere.length > 0
+        ? [...(lane.verdicts ?? []), ...parkedHere].slice(-MAX_PARKED_VERDICTS)
+        : lane.verdicts;
+    const unchanged =
+      verdicts === lane.verdicts &&
+      commands.length === lane.commands.length &&
+      commands.every((c, i) => c.seq === lane.commands[i]!.seq);
+    if (unchanged) continue;
+    lanes = {
+      ...lanes,
+      [protocol]: {
+        ...lane,
+        commands,
+        ...(verdicts !== undefined && { verdicts }),
+      },
+    };
+  }
+  if (lanes !== s.record.lanes) setRecord(s, { ...s.record, lanes });
 };
 
 const syncBacklog = (s: Session) => {
@@ -279,35 +334,49 @@ const cover = (s: Session, entry: Pending) => {
   s.lifecycle?.onCovered?.(entry.inv);
 };
 
-const NO_FAILED: readonly StatewireClient.FailedCommand[] = [];
-
 export const failedCommands = (
   s: Session,
-): readonly StatewireClient.FailedCommand[] => s.record.failed ?? NO_FAILED;
+): readonly StatewireClient.FailedCommand[] => {
+  const parts = Object.values(s.record.lanes).flatMap((lane) =>
+    lane.failed === undefined ? [] : [lane.failed],
+  );
+  const same =
+    parts.length === s.failedParts.length &&
+    parts.every((part, i) => part === s.failedParts[i]);
+  if (!same) {
+    s.failedParts = parts;
+    s.failedList = parts.flat();
+  }
+  return s.failedList;
+};
 
 const retainFailedInner = (
   s: Session,
   entry: Pending,
   failure: StatewireClient.SendFailure,
 ) => {
-  setRecord(s, {
-    ...s.record,
-    failed: [
-      ...(s.record.failed ?? []),
-      {
-        protocol: entry.command.protocol,
-        ...(entry.command.produced !== undefined && {
-          produced: entry.command.produced,
-        }),
-        command: entry.command.method,
-        params: entry.command.params,
-        ...(entry.command.meta !== undefined && { meta: entry.command.meta }),
-        failure,
-        ts: entry.inv.ts,
-        seq: entry.seq,
-      },
-    ],
-  });
+  const lane = laneOf(s.record, entry.command.protocol);
+  setRecord(
+    s,
+    withLane(s.record, entry.command.protocol, {
+      ...lane,
+      failed: [
+        ...(lane.failed ?? []),
+        {
+          protocol: entry.command.protocol,
+          ...(entry.command.produced !== undefined && {
+            produced: entry.command.produced,
+          }),
+          command: entry.command.method,
+          params: entry.command.params,
+          ...(entry.command.meta !== undefined && { meta: entry.command.meta }),
+          failure,
+          ts: entry.inv.ts,
+          seq: entry.seq,
+        },
+      ],
+    }),
+  );
   s.notify();
 };
 
@@ -343,8 +412,9 @@ const settleEntry = (
     const rides =
       (outcome.failure.cause === "unmount" ||
         outcome.failure.cause === "stream-gone") &&
-      entry.seq > s.durableSeq;
-    if (!rides) retainFailed(s, entry, outcome.failure);
+      entry.seq > durableSeqOf(s, entry.command.protocol);
+    if (!rides && !isEphemeral(s, entry.command.protocol))
+      retainFailed(s, entry, outcome.failure);
     entry.reject(new StatewireSendError(outcome.failure));
     s.lifecycle?.onSettle(entry.inv, {
       type: "rejected",
@@ -360,7 +430,10 @@ const settleAll = (s: Session, detach: "unmount" | "gone") => {
   const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
     if (!entry.attempted) {
       const predecessorLost = batch.some(
-        (p) => p.seq < entry.seq && p.attempted,
+        (p) =>
+          p.command.protocol === entry.command.protocol &&
+          p.seq < entry.seq &&
+          p.attempted,
       );
       return predecessorLost
         ? { fate: "aborted", cause, predecessorLost }
@@ -384,6 +457,13 @@ const settleLost = (s: Session, entries: Pending[]) => {
   }
 };
 
+const requeue = (s: Session, survivors: Pending[]) => {
+  for (const old of survivors) {
+    s.lifecycle?.onCovered?.(old.inv);
+    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
+  }
+};
+
 // The server-side record's dedup memory is gone: history that may have
 // reached a server settles lost — the new hello's snapshot is the only
 // truth about what survived — and never-attempted statements re-stamp
@@ -396,27 +476,33 @@ const rebaseRecord = (s: Session, adopt: () => void) => {
     held.filter((p) => p.attempted || p.applied),
   );
   s.pending = [];
-  s.durableSeq = 0;
+  s.durableSeq = {};
   // Failed entries are user-owned history: they ride through every record replacement.
-  const failed = s.record.failed;
+  const previous = s.record.lanes;
   adopt();
-  if (failed !== undefined && s.record.failed !== failed) {
-    setRecord(s, {
-      ...s.record,
-      failed: [...(s.record.failed ?? []), ...failed],
-    });
-  }
-  for (const old of survivors) {
-    s.lifecycle?.onCovered?.(old.inv);
-    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
+  let lanes = s.record.lanes;
+  for (const [protocol, lane] of Object.entries(previous)) {
+    const failed = lane.failed;
+    if (failed === undefined || laneOf(s.record, protocol).failed === failed)
+      continue;
+    const current = laneOf(s.record, protocol);
+    lanes = {
+      ...lanes,
+      [protocol]: {
+        ...current,
+        failed: [...(current.failed ?? []), ...failed],
+      },
+    };
   }
+  if (lanes !== s.record.lanes) setRecord(s, { ...s.record, lanes });
+  requeue(s, survivors);
   publish(s);
   wake(s);
   void pump(s);
 };
 
 const resetRecord = (s: Session, clientId: string) =>
-  rebaseRecord(s, () => setRecord(s, { clientId, nextSeq: 1, commands: [] }));
+  rebaseRecord(s, () => setRecord(s, { clientId, lanes: {} }));
 
 // Another sharer replaced the record's identity: their reset settles our
 // attempted history and our survivors re-stamp on the stored clocks.
@@ -432,6 +518,23 @@ const ephemeralDetach = (s: Session) => {
   resetRecord(s, newClientId());
 };
 
+// An ephemeral lane dies with its attach: attempted statements can never be
+// answered, the rest re-stamp from 1 for the next attach.
+const detachEphemeralLanes = (s: Session) => {
+  const held = s.pending.filter((p) => isEphemeral(s, p.command.protocol));
+  if (held.length === 0) return;
+  s.pending = s.pending.filter((p) => !held.includes(p));
+  settleLost(
+    s,
+    held.filter((p) => p.attempted),
+  );
+  requeue(
+    s,
+    held.filter((p) => !p.attempted),
+  );
+  publish(s);
+};
+
 const rejectedFailure = (cmd: StatewireCmd): StatewireClient.SendFailure => {
   return {
     fate: "rejected",
@@ -470,58 +573,76 @@ const outcomeOf = (
   }
 };
 
+// Only a result verdict carries applied effects; the rest drop the overlay unapplied.
+const settleVerdict = (s: Session, entry: Pending, cmd: StatewireCmd) => {
+  const outcome = outcomeOf(cmd);
+  if (outcome.ok) cover(s, entry);
+  else s.lifecycle?.onCovered?.(entry.inv);
+  settleEntry(s, entry, outcome);
+};
+
 const TERMINAL_CMD_TYPES: ReadonlySet<string> = new Set(TERMINAL);
 
 const parkVerdict = (s: Session, cmd: StatewireCmd) => {
   if (!s.shared || !TERMINAL_CMD_TYPES.has(cmd.type!)) return;
+  if (isEphemeral(s, cmd.protocol)) return;
   s.shared.parked.push({
-    seq: cmd.seq,
-    type: cmd.type as StatewireClient.SessionVerdict["type"],
-    ...(cmd.code !== undefined && { code: cmd.code }),
-    ...(cmd.message !== undefined && { message: cmd.message }),
-    ...(cmd.payload !== undefined && { payload: cmd.payload }),
-    ...(cmd.meta !== undefined && { meta: cmd.meta }),
+    protocol: cmd.protocol,
+    verdict: {
+      seq: cmd.seq,
+      type: cmd.type as StatewireClient.SessionVerdict["type"],
+      ...(cmd.code !== undefined && { code: cmd.code }),
+      ...(cmd.message !== undefined && { message: cmd.message }),
+      ...(cmd.payload !== undefined && { payload: cmd.payload }),
+      ...(cmd.meta !== undefined && { meta: cmd.meta }),
+    },
   });
 };
 
 const handleCmd = (s: Session, cmd: StatewireCmd) => {
-  if (!Number.isSafeInteger(cmd.seq) || cmd.seq <= 0) {
-    protocolError("cmd.seq must be a positive safe integer");
-  }
-  if (cmd.dur === true) {
-    s.durableSeq = Math.max(s.durableSeq, cmd.seq);
-    for (const entry of s.pending) {
-      if (entry.seq <= s.durableSeq) entry.posted = true;
+  if (cmd.dur === true && !isEphemeral(s, cmd.protocol)) {
+    const watermark = Math.max(durableSeqOf(s, cmd.protocol), cmd.seq);
+    s.durableSeq[cmd.protocol] = watermark;
+    for (const entry of laneEntries(s, cmd.protocol)) {
+      if (entry.seq <= watermark) entry.posted = true;
     }
   }
   if (cmd.type === undefined) return;
-  const entry = s.pending.find((p) => p.seq === cmd.seq);
+  const entry = s.pending.find(
+    (p) => p.command.protocol === cmd.protocol && p.seq === cmd.seq,
+  );
   if (cmd.type === "applied") {
     if (entry) cover(s, entry);
     return;
   }
   if (!entry) return;
   parkVerdict(s, cmd);
-  cover(s, entry);
-  settleEntry(s, entry, outcomeOf(cmd));
+  settleVerdict(s, entry, cmd);
 };
 
 const consumeVerdicts = (s: Session) => {
-  const verdicts = s.record.verdicts ?? [];
-  const consumed = new Set<number>();
-  for (const verdict of verdicts) {
-    const entry = s.pending.find((p) => p.seq === verdict.seq);
-    if (!entry) continue;
-    consumed.add(verdict.seq);
-    cover(s, entry);
-    settleEntry(s, entry, outcomeOf(verdict as StatewireCmd));
+  let lanes = s.record.lanes;
+  for (const [protocol, lane] of Object.entries(s.record.lanes)) {
+    const verdicts = lane.verdicts ?? [];
+    const consumed = new Set<number>();
+    for (const verdict of verdicts) {
+      const entry = laneEntries(s, protocol).find((p) => p.seq === verdict.seq);
+      if (!entry) continue;
+      consumed.add(verdict.seq);
+      settleVerdict(s, entry, { ...verdict, protocol });
+    }
+    if (consumed.size === 0) continue;
+    lanes = {
+      ...lanes,
+      [protocol]: {
+        ...lane,
+        commands: lane.commands.filter((c) => !consumed.has(c.seq)),
+        verdicts: verdicts.filter((v) => !consumed.has(v.seq)),
+      },
+    };
   }
-  if (consumed.size === 0) return;
-  setRecord(s, {
-    ...s.record,
-    commands: s.record.commands.filter((c) => !consumed.has(c.seq)),
-    verdicts: verdicts.filter((v) => !consumed.has(v.seq)),
-  });
+  if (lanes === s.record.lanes) return;
+  setRecord(s, { ...s.record, lanes });
   publish(s);
   wake(s);
 };
@@ -583,18 +704,20 @@ const publishIngested = (s: Session) => {
 // The refusal's watermark is exact: every held statement above it was never
 // admitted by the live record, and the first unposted seq being beyond
 // watermark+1 proves the record that admitted the missing prefix is gone —
-// its history settles lost and the cmd clock restarts at the watermark.
-const sessionLostInner = (s: Session, seqWm: number) => {
-  const held = [...s.pending];
+// its history settles lost and the lane clock restarts at the watermark.
+const sessionLostInner = (s: Session, protocol: string, seqWm: number) => {
+  const held = laneEntries(s, protocol);
   settleLost(s, held);
-  s.pending = [];
-  s.durableSeq = seqWm;
-  setRecord(s, {
-    clientId: s.record.clientId,
-    nextSeq: seqWm + 1,
-    commands: [],
-    ...(s.record.failed !== undefined && { failed: s.record.failed }),
-  });
+  s.durableSeq[protocol] = seqWm;
+  const failed = laneOf(s.record, protocol).failed;
+  setRecord(
+    s,
+    withLane(s.record, protocol, {
+      nextSeq: seqWm + 1,
+      commands: [],
+      ...(failed !== undefined && { failed }),
+    }),
+  );
   if (
     held.length > 0 &&
     s.onSessionLost?.(held.map((p) => p.inv)) === "requeue"
@@ -613,39 +736,51 @@ const sessionLostInner = (s: Session, seqWm: number) => {
   wake(s);
 };
 
+const selectionOf = (
+  syn: StatewireSyn,
+): StatewireProtocol.Selection | undefined => {
+  if (syn.version === undefined || syn.protocols === undefined)
+    return undefined;
+  return {
+    version: syn.version,
+    protocols: syn.protocols.map(({ name, version, record }) => {
+      if (version === undefined)
+        return protocolError(`hello lane ${name} has no version`);
+      return { name, version, ...(record !== undefined && { record }) };
+    }),
+  };
+};
+
 const handleHello = (
   s: Session,
   { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
 ) => {
-  if (syn.record !== undefined && syn.record !== "ephemeral") {
-    protocolError(`unknown record: ${String(syn.record)}`);
-  }
-  if (syn.ctxSeq !== undefined && syn.ctxSeq !== 0) {
-    protocolError(`hello ctxSeq must be 0, got ${syn.ctxSeq}`);
-  }
-  s.selection =
-    syn.version === undefined || syn.protocols === undefined
-      ? undefined
-      : { version: syn.version, protocols: syn.protocols };
+  s.selection = selectionOf(syn);
   s.documents = { mode: null, documents: new Map() };
   ingestOps(s, ops);
   s.attach = "attached";
   s.attachEpoch += 1;
   s.frameFailures = 0;
   s.resumeAt = 0;
-  s.ephemeral = syn.record === "ephemeral";
+  const lanes = syn.protocols ?? [];
+  s.ephemeral =
+    lanes.length > 0 && lanes.every((lane) => lane.record === "ephemeral");
   if (s.ephemeral) s.deactivated = true;
-  const [attachCmd, attachCtx] = s.attachLaneSeqs;
-  s.attachLaneSeqs = [new Set(), new Set()];
+  const attached = s.attachEntries;
+  s.attachEntries = new Set();
   const reconcile = () => {
     if (s.shared) adoptStored(s);
     // Resending unsettled statements is exactly-once-safe: absorbed replays
     // re-emit their stored verdicts (applied while still in flight).
-    s.durableSeq = syn.seq ?? 0;
-    for (const entry of s.pending) {
-      entry.posted = attachCmd.has(entry.seq);
+    for (const lane of lanes) {
+      if (lane.record === "ephemeral") {
+        s.ephemeralSeqs[lane.name] = Math.max(
+          s.ephemeralSeqs[lane.name] ?? 0,
+          ...laneEntries(s, lane.name).map((p) => p.seq),
+        );
+      } else s.durableSeq[lane.name] = lane.seq ?? 0;
     }
-    for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
+    for (const entry of s.pending) entry.posted = attached.has(entry);
     syncBacklogInner(s);
     s.sessionKnown = true;
   };
@@ -671,40 +806,43 @@ const handleOps = (
   publishIngested(s);
 };
 
-// A retry-less {syn} refusal is the one session-loss verdict: a cmd gap
-// against its exact watermark settles the held history lost; a pushback
-// (retry present) or a gapless refusal only reconciles the resend queues.
+// A retry-less {syn} refusal is the one session-loss verdict: a gap against
+// a durable lane's exact watermark settles that lane's history lost; a
+// pushback (retry present) or a gapless refusal only reconciles the resend queues.
 const handleRefusal = (s: Session, syn: StatewireSyn) => {
-  const { seq, ctxSeq } = syn;
-  if (typeof seq === "number") {
-    const watermark = Math.max(seq, s.durableSeq);
-    for (const entry of s.pending) entry.posted = entry.seq <= watermark;
-  }
-  if (typeof ctxSeq === "number") {
-    s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxSeq);
-    for (const c of s.ctxPending) c.posted = false;
-    const firstCtx = s.ctxPending.find((c) => !c.posted);
-    if (firstCtx !== undefined && firstCtx.seq > ctxSeq + 1) {
-      protocolError(
-        `ctx gap on a live attach: seq ${firstCtx.seq} after watermark ${ctxSeq}`,
-      );
-    }
+  const lanes = (syn.protocols ?? []).filter(
+    (lane): lane is { name: string; seq: number } => lane.seq !== undefined,
+  );
+  for (const { name, seq } of lanes) {
+    const watermark = isEphemeral(s, name)
+      ? seq
+      : Math.max(seq, durableSeqOf(s, name));
+    for (const entry of laneEntries(s, name))
+      entry.posted = entry.seq <= watermark;
   }
   if (typeof syn.retry === "number") {
-    s.resumeAt = Date.now() + syn.retry;
+    s.resumeAt = Date.now() + retryHint(syn.retry);
     wake(s);
     void pump(s);
     return;
   }
-  const firstCmd = s.pending.find((p) => !p.posted);
-  const cmdGap =
-    typeof seq === "number" &&
-    firstCmd !== undefined &&
-    firstCmd.seq > Math.max(seq, s.durableSeq) + 1;
-  if (cmdGap) {
+  const gaps = lanes.filter(({ name, seq }) => {
+    const first = laneEntries(s, name).find((p) => !p.posted);
+    return (
+      first !== undefined &&
+      first.seq > Math.max(seq, durableSeqOf(s, name)) + 1
+    );
+  });
+  for (const { name, seq } of gaps) {
+    if (isEphemeral(s, name))
+      protocolError(`gap on ephemeral lane ${name} after watermark ${seq}`);
+  }
+  if (gaps.length > 0) {
     transactBackground(
       s,
-      () => sessionLostInner(s, seq),
+      () => {
+        for (const { name, seq } of gaps) sessionLostInner(s, name, seq);
+      },
       () => {
         wake(s);
         void pump(s);
@@ -718,7 +856,9 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
 
 const handleDetach = (s: Session) => {
   if (s.attach === "attached") s.attach = "detached";
+  s.ephemeralSeqs = {};
   if (s.ephemeral) ephemeralDetach(s);
+  else detachEphemeralLanes(s);
   wake(s);
 };
 
@@ -734,77 +874,56 @@ const isFinished = (s: Session) => s.attach === "finished";
 
 type Lanes = {
   frame: StatewireFrame;
-  cmdEntries: Pending[];
-  ctxEntries: CtxPending[];
+  entries: Pending[];
 };
 
 // A lane must be strictly consecutive within a frame: the first unposted run
-// per lane rides now, later runs ride follow-up frames.
+// per lane rides now, later runs ride follow-up frames. Ephemeral lanes ignore
+// the gate: they live on the attach and never wait for persistence.
 const buildLanes = (
   s: Session,
   cmdGate: "persisted" | "all" | "none" = "all",
 ): Lanes | null => {
-  const ctxEntries: CtxPending[] = [];
-  for (const entry of s.ctxPending) {
-    if (entry.posted) continue;
-    if (ctxEntries.length >= MAX_COMMANDS_PER_FRAME) break;
-    if (ctxEntries.length > 0 && entry.seq !== ctxEntries.at(-1)!.seq + 1)
-      break;
-    ctxEntries.push(entry);
-  }
-  const cmdEntries: Pending[] = [];
+  const entries: Pending[] = [];
+  const last: Record<string, number> = {};
+  const stopped = new Set<string>();
   for (const entry of s.pending) {
-    if (cmdGate === "none") break;
-    if (entry.posted) continue;
-    if (
-      cmdGate === "persisted" &&
-      (s.persistedRecord?.clientId !== s.record.clientId ||
-        entry.seq >= s.persistedRecord.nextSeq)
-    )
-      break;
-    if (cmdEntries.length >= MAX_COMMANDS_PER_FRAME) break;
-    if (cmdEntries.length > 0 && entry.seq !== cmdEntries.at(-1)!.seq + 1)
-      break;
-    cmdEntries.push(entry);
+    if (entries.length >= MAX_COMMANDS_PER_FRAME) break;
+    const protocol = entry.command.protocol;
+    if (entry.posted || stopped.has(protocol)) continue;
+    const gated =
+      !isEphemeral(s, protocol) &&
+      (cmdGate === "none" ||
+        (cmdGate === "persisted" &&
+          (s.persistedRecord?.clientId !== s.record.clientId ||
+            entry.seq >= laneOf(s.persistedRecord, protocol).nextSeq)));
+    if (gated || (protocol in last && entry.seq !== last[protocol]! + 1)) {
+      stopped.add(protocol);
+      continue;
+    }
+    last[protocol] = entry.seq;
+    entries.push(entry);
   }
-  if (ctxEntries.length === 0 && cmdEntries.length === 0) return null;
+  if (entries.length === 0) return null;
   return {
     frame: {
-      ...(ctxEntries.length > 0 && {
-        ctx: ctxEntries.map((c) => ({ ops: c.ops, seq: c.seq })),
-      }),
-      ...(cmdEntries.length > 0 && {
-        cmd: cmdEntries.map((p) => {
-          const { produced: _produced, ...command } = p.command;
-          return { ...command, seq: p.seq };
-        }),
+      cmd: entries.map((p) => {
+        const { produced: _produced, ...command } = p.command;
+        return { ...command, seq: p.seq };
       }),
     },
-    cmdEntries,
-    ctxEntries,
+    entries,
   };
 };
 
-// Context is attach scoped: every attach starts at ctx seq 0 with an empty
-// table, so the full context restates at seq 1 on the attach frame.
-const resetContextLane = (s: Session) => {
-  const ops = contextSnapshot(s.contextDocuments);
-  s.ctxPending = ops.length === 0 ? [] : [{ seq: 1, ops, posted: false }];
-  s.ctxNextSeq = s.ctxPending.length + 1;
-};
-
 const takeAttachLanes = (s: Session): StatewireFrame | null => {
-  s.attachLaneSeqs = [new Set(), new Set()];
-  resetContextLane(s);
+  s.attachEntries = new Set();
   const wanted = s.lanesOnAttach;
   s.lanesOnAttach = false;
   const lanes = buildLanes(s, wanted && s.sessionKnown ? "persisted" : "none");
   if (!lanes) return null;
-  s.attachLaneSeqs = [
-    new Set(lanes.cmdEntries.map((p) => p.seq)),
-    new Set(lanes.ctxEntries.map((c) => c.seq)),
-  ];
-  for (const entry of lanes.cmdEntries) entry.attempted = true;
+  s.attachEntries = new Set(lanes.entries);
+  for (const entry of lanes.entries) entry.attempted = true;
   return lanes.frame;
 };
 
@@ -860,7 +979,7 @@ const pump = async (s: Session) => {
       if (persistence) await persistence;
       if (!s.running || isFinished(s)) return;
       if (epoch !== s.attachEpoch || s.attach !== "attached") continue;
-      for (const entry of lanes.cmdEntries) entry.attempted = true;
+      for (const entry of lanes.entries) entry.attempted = true;
       let result;
       try {
         // Shared storage: the lock across the send keeps per-lane arrival
@@ -879,13 +998,12 @@ const pump = async (s: Session) => {
       s.frameFailures = 0;
       if (result.type === "ok") {
         if (epoch === s.attachEpoch) {
-          for (const entry of lanes.cmdEntries) {
+          for (const entry of lanes.entries) {
             if (s.pending.includes(entry)) {
               entry.posted = true;
               s.lifecycle?.onPosted?.(entry.inv);
             }
           }
-          for (const entry of lanes.ctxEntries) entry.posted = true;
         }
       } else if (result.type === "refusal") {
         if (epoch === s.attachEpoch) handleRefusal(s, result.syn);
@@ -973,12 +1091,19 @@ const enqueueInner = (
   resolve: (payload: unknown) => void,
   reject: (error: unknown) => void,
 ) => {
-  const seq = Math.max(s.record.nextSeq, s.durableSeq + 1);
+  const protocol = command.protocol;
+  const ephemeral = isEphemeral(s, protocol);
+  const seq = ephemeral
+    ? (s.ephemeralSeqs[protocol] ?? 0) + 1
+    : Math.max(
+        laneOf(s.record, protocol).nextSeq,
+        durableSeqOf(s, protocol) + 1,
+      );
   const entry: Pending = {
     seq,
     command,
     inv: {
-      protocol: command.protocol,
+      protocol,
       method: command.method,
       params,
       ts: Date.now(),
@@ -992,7 +1117,16 @@ const enqueueInner = (
     reject,
   };
   s.pending.push(entry);
-  setRecord(s, { ...s.record, nextSeq: seq + 1, commands: mergeBacklog(s) });
+  if (ephemeral) s.ephemeralSeqs[protocol] = seq;
+  else
+    setRecord(
+      s,
+      withLane(s.record, protocol, {
+        ...laneOf(s.record, protocol),
+        nextSeq: seq + 1,
+        commands: mergeBacklog(s, protocol),
+      }),
+    );
   s.lifecycle?.onStart(entry.inv);
 };
 
@@ -1025,44 +1159,47 @@ const enqueue = (
   }, reject);
 };
 
+const offered = (s: Session, protocol: string) => {
+  const offers = protocolOffers(s.options);
+  return offers === "*" || offers.some((offer) => offer.name === protocol);
+};
+
 // A stored command may have reached a server: attempted settles it lost,
 // never aborted, when a channel death ends the session.
 const adoptStored = (s: Session) => {
-  const known = new Set(s.pending.map((p) => p.seq));
-  const stored = s.record.commands.filter((c) => !known.has(c.seq));
-  if (stored.length === 0) return;
-  for (const { seq, ...command } of stored) {
-    const offers = protocolOffers(s.options);
-    if (
-      offers !== "*" &&
-      !offers.some((offer) => offer.name === command.protocol)
-    )
-      continue;
-    const params =
-      command.meta === undefined
-        ? command.params
-        : (reviveValue([...command.params], command.meta) as unknown[]);
-    const entry: Pending = {
-      seq,
-      command,
-      inv: {
-        protocol: command.protocol,
-        method: command.method,
-        params,
-        ts: Date.now(),
+  let adopted = false;
+  for (const [protocol, lane] of Object.entries(s.record.lanes)) {
+    if (!offered(s, protocol)) continue;
+    const known = new Set(laneEntries(s, protocol).map((p) => p.seq));
+    for (const { seq, ...command } of lane.commands) {
+      if (known.has(seq)) continue;
+      const params =
+        command.meta === undefined
+          ? command.params
+          : (reviveValue([...command.params], command.meta) as unknown[]);
+      const entry: Pending = {
         seq,
-        clientId: s.record.clientId,
-      },
-      attempted: true,
-      posted: false,
-      applied: false,
-      resolve: () => {},
-      reject: () => {},
-    };
-    s.pending.push(entry);
-    s.lifecycle?.onStart(entry.inv);
+        command: { protocol, ...command },
+        inv: {
+          protocol,
+          method: command.method,
+          params,
+          ts: Date.now(),
+          seq,
+          clientId: s.record.clientId,
+        },
+        attempted: true,
+        posted: false,
+        applied: false,
+        resolve: () => {},
+        reject: () => {},
+      };
+      s.pending.push(entry);
+      s.lifecycle?.onStart(entry.inv);
+      adopted = true;
+    }
   }
-  s.pending.sort((a, b) => a.seq - b.seq);
+  if (adopted) s.pending.sort((a, b) => a.seq - b.seq);
 };
 
 const sendCommand = (
@@ -1071,6 +1208,11 @@ const sendCommand = (
   params: readonly unknown[],
   protocol = s.options.protocol ?? DEFAULT_PROTOCOL,
 ): Promise<unknown> => {
+  const negotiated = s.selection
+    ? s.selection.protocols.some((p) => p.name === protocol)
+    : offered(s, protocol);
+  if (!negotiated)
+    throw new Error(`statewire: protocol "${protocol}" is not negotiated`);
   if (!s.hydrated) {
     const result = s.ready!.then(() =>
       sendCommand(s, method, params, protocol),
@@ -1119,7 +1261,7 @@ const findFailed = (
   s: Session,
   entry: StatewireClient.FailedCommand,
 ): StatewireClient.FailedCommand | undefined =>
-  (s.record.failed ?? []).find(
+  (laneOf(s.record, entry.protocol).failed ?? []).find(
     (f) =>
       f.seq === entry.seq && f.ts === entry.ts && f.command === entry.command,
   );
@@ -1131,10 +1273,16 @@ const takeFailed = (
   s: Session,
   entry: StatewireClient.FailedCommand,
 ): StatewireClient.FailedCommand => {
-  const failed = s.record.failed ?? [];
+  const lane = laneOf(s.record, entry.protocol);
   const found = findFailed(s, entry);
   if (found === undefined) throw unknownFailed(entry);
-  setRecord(s, { ...s.record, failed: failed.filter((f) => f !== found) });
+  setRecord(
+    s,
+    withLane(s.record, entry.protocol, {
+      ...lane,
+      failed: (lane.failed ?? []).filter((f) => f !== found),
+    }),
+  );
   s.notify();
   return found;
 };
@@ -1216,83 +1364,6 @@ export const retryFailed = (
   return result;
 };
 
-const contextSnapshot = (documents: StatewireDocuments.State) =>
-  [...documents.documents].map(([doc, d]) => {
-    const encoded = encodeDocument(d.value);
-    return {
-      op: "mount",
-      ...(doc === 0 ? {} : { doc }),
-      protocol: d.protocol,
-      ...(d.main ? { main: true } : {}),
-      ...(d.key === null ? {} : { key: d.key }),
-      value: encoded.value,
-      ...(encoded.meta === undefined ? {} : { meta: encoded.meta }),
-    };
-  });
-
-const changeContext = (
-  s: Session,
-  build: (documents: StatewireDocuments.State) => readonly unknown[],
-): void => {
-  if (!s.running || isFinished(s)) return;
-  const operations = build(s.contextDocuments);
-  if (!operations.length)
-    throw new Error("statewire: context operations must not be empty");
-  const offers = protocolOffers(s.options);
-  const protocols =
-    s.selection?.protocols ?? (offers === "*" ? undefined : offers);
-  s.contextDocuments = applyDocumentOps(
-    s.contextDocuments,
-    operations,
-    protocols,
-    true,
-  );
-  s.ctxPending = [
-    ...s.ctxPending,
-    {
-      seq: s.ctxNextSeq++,
-      ops: operations.map((op) => {
-        const value = op as Record<string, unknown>;
-        if (value["doc"] !== 0) return value;
-        const { doc: _doc, ...rest } = value;
-        return rest;
-      }),
-      posted: false,
-    },
-  ];
-  wake(s);
-  void pump(s);
-};
-
-export const updateContext = (s: Session, operations: readonly unknown[]) =>
-  changeContext(s, () => operations);
-
-const setContext = (
-  s: Session,
-  value: Record<string, unknown>,
-  protocol = s.options.protocol ?? DEFAULT_PROTOCOL,
-): void => {
-  if (typeof value !== "object" || value === null || Array.isArray(value))
-    throw new Error("statewire: context must be a plain object");
-  const encoded = encodeDocument(value);
-  changeContext(s, (documents) => {
-    const found = [...documents.documents].find(
-      ([, d]) => d.protocol === protocol && d.main,
-    );
-    const doc = found?.[0] ?? Math.max(-1, ...documents.documents.keys()) + 1;
-    return [
-      {
-        ...(found === undefined
-          ? { op: "mount", protocol, main: true }
-          : { op: "replace", path: [] }),
-        ...(doc === 0 ? {} : { doc }),
-        value: encoded.value,
-        ...(encoded.meta === undefined ? {} : { meta: encoded.meta }),
-      },
-    ];
-  });
-};
-
 export const documentSource = (s: Session): StatewireDocuments.Source => ({
   get: (protocol, key, prefix = s.options.keyPrefixes?.[protocol]) => {
     const mounted = findDocument(s.documents, protocol, key, prefix);
@@ -1332,20 +1403,20 @@ export const invokeProtocol = (
 ) => sendCommand(s, method, params, protocol);
 
 const storedCommandCompatible = (
+  protocol: string,
   command: StatewireClient.SessionCommand,
   current: NonNullable<StatewireClient.SessionCommand["produced"]>,
 ) => {
   if (
     !command.produced ||
-    !command.protocol ||
     !inRange(command.produced.wire.version, current.wire)
   )
     return false;
   const previous = command.produced.protocols;
   if (current.protocols === "*") return true;
   if (previous === "*") return false;
-  const produced = previous.find((p) => p.name === command.protocol);
-  const offer = current.protocols.find((p) => p.name === command.protocol);
+  const produced = previous.find((p) => p.name === protocol);
+  const offer = current.protocols.find((p) => p.name === protocol);
   return (
     produced !== undefined &&
     offer !== undefined &&
@@ -1353,47 +1424,45 @@ const storedCommandCompatible = (
   );
 };
 
+const validateLanes = (record: StatewireClient.SessionRecord) => {
+  if (
+    typeof record.lanes !== "object" ||
+    record.lanes === null ||
+    Object.values(record.lanes).some((lane) => !Array.isArray(lane.commands))
+  )
+    throw new Error(
+      "statewire: session storage loaded a record without command lanes",
+    );
+};
+
 const loadSessionRecord = (
   store: StatewireClient.SessionStorage,
   options: StatewireSessionOptions,
 ) => {
   let stored = store.load();
-  if (stored !== null && !Array.isArray(stored.commands))
-    throw new Error(
-      "statewire: session storage loaded a record without a commands array",
-    );
+  if (stored !== null) validateLanes(stored);
   const current = {
     wire: options.wireVersion ?? { version: WIRE_VERSION },
     protocols: protocolOffers(options),
   };
-  if (
-    stored !== null &&
-    !stored.commands.every((command) =>
-      storedCommandCompatible(command, current),
-    )
-  ) {
+  const compatible = (record: StatewireClient.SessionRecord) =>
+    Object.entries(record.lanes).every(([protocol, lane]) =>
+      lane.commands.every((command) =>
+        storedCommandCompatible(protocol, command, current),
+      ),
+    );
+  if (stored !== null && !compatible(stored)) {
     if (!store.migrate)
       throw new Error("statewire: stored commands require a storage migration");
     stored = store.migrate(stored, current);
-    if (
-      stored !== null &&
-      !stored.commands.every((command) =>
-        storedCommandCompatible(command, current),
-      )
-    )
-      throw new Error("statewire: migrated commands are incompatible");
-    if (stored !== null) store.save(stored);
-  }
-  if (stored !== null && !Array.isArray(stored.commands)) {
-    throw new Error(
-      "statewire: session storage loaded a record without a commands array",
-    );
+    if (stored !== null) {
+      validateLanes(stored);
+      if (!compatible(stored))
+        throw new Error("statewire: migrated commands are incompatible");
+      store.save(stored);
+    }
   }
-  const record = stored ?? {
-    clientId: newClientId(),
-    nextSeq: 1,
-    commands: [],
-  };
+  const record = stored ?? { clientId: newClientId(), lanes: {} };
   if (stored === null) store.save(record);
   return record;
 };
@@ -1419,11 +1488,10 @@ export const useStatewireSession = (
     const record =
       store.ready === undefined
         ? loadSessionRecord(store, options)
-        : { clientId: newClientId(), nextSeq: 1, commands: [] };
+        : { clientId: newClientId(), lanes: {} };
     const session: Session = {
       options,
       selection: undefined,
-      contextDocuments: { mode: "mounted", documents: new Map() },
       record,
       ctx: {
         beforeAttach: () => persistBeforeSend(session),
@@ -1453,17 +1521,18 @@ export const useStatewireSession = (
       ephemeral: false,
       deactivated: false,
       sessionKnown: false,
-      durableSeq: 0,
+      durableSeq: {},
+      ephemeralSeqs: {},
       resumeAt: 0,
       idle: false,
       onSessionLost: undefined,
       onDone: undefined,
-      ctxNextSeq: 1,
-      ctxPending: [],
       lanesOnAttach: false,
-      attachLaneSeqs: [new Set(), new Set()],
+      attachEntries: new Set(),
       frameFailures: 0,
       pending: [],
+      failedList: [],
+      failedParts: [],
       canonical: undefined,
       documentListeners: new Set(),
       documents: { mode: null, documents: new Map() },
@@ -1542,4 +1611,4 @@ export const useStatewireSession = (
   return s;
 };
 
-export { setContext, setTransport };
+export { setTransport };