statewire 0.8.1 → 0.9.0

package/src/client/session.ts

@@ -1,7 +1,8 @@
 import { useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
-import type { StatewireResponse } from "./connection";
+import type { StatewireCmd, StatewireSyn } from "./connection";
+import { encodeParams, encodeValue, reviveResponse } from "../wire/meta";
 import { bindCommandsHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
 import type { Statewire } from "../types";
@@ -12,128 +13,45 @@ import type {
   StatewireSessionStore,
   StatewireSessionStoreOptions,
 } from "./sessionStore";
-import { retryDelay } from "./timing";
+import { backoff } from "./timing";
 import { createMethodProxy } from "../util/methodProxy";
 import { randomId } from "../util/randomId";
 import { StatewireSendError } from "../types";
 import type {
   RemoteLink,
+  StatewireFrame,
   StatewireRemoteProps,
-  StatewireSubmitResult,
-  StatewireWireCommand,
 } from "../transports/sse";
 
-/**
- * queued/trying/posted: overlay live, result pending. awaiting-result: acked
- * (overlay gone) but the result rides a late res; `posted: false` re-sends.
- * settled-live: result settled but the overlay stays until the covering ack.
- * done: removed from the queue.
- */
-type PendingState =
-  | { at: "queued"; pendingMarked: boolean }
-  | { at: "trying"; pendingMarked: boolean; failedAttempts: number }
-  | { at: "posted"; pendingMarked: boolean; failedAttempts: number }
-  | { at: "awaiting-result"; posted: boolean; failedAttempts: number }
-  | { at: "settled-live"; posted: boolean; failedAttempts: number }
-  | { at: "done" };
+type WireCommand = {
+  method: string;
+  params: unknown[];
+  meta?: unknown;
+};
 
 type Pending = {
   readonly seq: number;
-  readonly command: StatewireWireCommand;
-  /** null for context submissions — they carry no command lifecycle. */
-  readonly inv: CommandsInvocation | null;
-  state: PendingState;
+  readonly command: WireCommand;
+  readonly inv: CommandsInvocation;
+  /** A send carrying this statement may have reached the server. */
+  attempted: boolean;
+  /** In the resend queue when false. */
+  posted: boolean;
+  /** The server acknowledged admission; the terminal verdict is still due. */
+  applied: boolean;
   resolve: (payload: unknown) => void;
   reject: (error: StatewireSendError) => void;
 };
 
-type Outcome =
-  | { ok: true; payload: unknown }
-  | { ok: false; failure: StatewireClient.SendFailure };
-
-const isResolved = (state: PendingState) =>
-  state.at === "settled-live" || state.at === "done";
-
-const isStateSettled = (state: PendingState) =>
-  state.at === "awaiting-result" || state.at === "done";
-
-// The pump admits an entry as trying before sending; only the pump itself
-// requeues, and a done entry is never still pending.
-const inFlight = (state: PendingState) => {
-  if (state.at === "queued" || state.at === "done") {
-    throw new Error(`statewire: ${state.at} entry observed after a send`);
-  }
-  return state;
-};
-
-const legalTransitions: Record<PendingState["at"], PendingState["at"][]> = {
-  queued: ["queued", "trying", "awaiting-result", "settled-live", "done"],
-  // trying -> queued: an answered unknown-client proves the seq was never admitted.
-  trying: [
-    "queued",
-    "trying",
-    "posted",
-    "awaiting-result",
-    "settled-live",
-    "done",
-  ],
-  posted: ["posted", "trying", "awaiting-result", "settled-live", "done"],
-  "awaiting-result": ["awaiting-result", "done"],
-  "settled-live": ["settled-live", "done"],
-  done: [],
-};
-
-const transition = (
-  s: Session,
-  entry: Pending,
-  next: PendingState,
-  outcome?: Outcome,
-) => {
-  const prev = entry.state;
-  if (!legalTransitions[prev.at].includes(next.at)) {
-    throw new Error(
-      `statewire: illegal pending transition ${prev.at} -> ${next.at}`,
-    );
-  }
-  const settles = !isResolved(prev) && isResolved(next);
-  if (settles && outcome === undefined) {
-    throw new Error(
-      `statewire: settling transition ${prev.at} -> ${next.at} without an outcome`,
-    );
-  }
-  const covers = !isStateSettled(prev) && isStateSettled(next);
-  entry.state = next;
-  if (covers && entry.inv) s.lifecycle?.onCovered?.(entry.inv);
-  if (settles && outcome !== undefined) {
-    if (outcome.ok) {
-      entry.resolve(outcome.payload);
-      if (entry.inv)
-        s.lifecycle?.onSettle(entry.inv, {
-          type: "accepted",
-          payload: outcome.payload,
-        });
-    } else {
-      entry.reject(new StatewireSendError(outcome.failure));
-      if (entry.inv)
-        s.lifecycle?.onSettle(entry.inv, {
-          type: "rejected",
-          error: new StatewireSendError(outcome.failure),
-        });
-    }
-  }
-  if (next.at === "done") {
-    s.pending = s.pending.filter((p) => p !== entry);
-  }
+type CtxPending = {
+  readonly seq: number;
+  readonly ops: unknown[];
+  posted: boolean;
 };
 
-const carried = (
-  state: Exclude<PendingState, { at: "done" }>,
-): { posted: boolean; failedAttempts: number } =>
-  state.at === "queued"
-    ? { posted: false, failedAttempts: 0 }
-    : state.at === "trying" || state.at === "posted"
-      ? { posted: state.at === "posted", failedAttempts: state.failedAttempts }
-      : { posted: state.posted, failedAttempts: state.failedAttempts };
+const protocolError = (message: string): never => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
 
 const newClientId = () => `c-${randomId()}`;
 
@@ -147,15 +65,26 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
-export type StatewireSessionOptions = StatewireSessionStoreOptions;
+export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+  onDone?: (() => void) | undefined;
+};
 
 type Session = {
   record: StatewireSessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
   store: StatewireSessionStore;
-  lastAck: number;
-  context: Record<string, unknown> | undefined;
+  ephemeral: boolean;
+  sessionKnown: boolean;
+  durableSeq: number;
+  resumeAt: number;
+  idle: boolean;
+  onDone: (() => void) | undefined;
+  ctxOps: unknown[] | undefined;
+  ctxPending: CtxPending[];
+  lanesOnAttach: boolean;
+  attachLaneSeqs: readonly [ReadonlySet<number>, ReadonlySet<number>];
+  frameFailures: number;
   pending: Pending[];
   canonical: unknown;
   lastPublished: unknown;
@@ -169,64 +98,9 @@ type Session = {
   waiters: (() => void)[];
   lifecycle: CommandsListener | null;
   notify: () => void;
-  emitEvent: (event: unknown) => void;
-  send: (command: StatewireWireCommand) => Promise<unknown>;
   commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
 };
 
-const createSession = (options: StatewireSessionOptions): Session => {
-  const store = options.sessionStore ?? createMemorySessionStore();
-  const stored = store.load();
-  const record = stored ?? { clientId: newClientId(), nextSeq: 1 };
-  const s: Session = {
-    record,
-    ctx: {
-      get clientId() {
-        return s.record.clientId;
-      },
-      onSnapshot: (args) => handleSnapshot(s, args),
-      onOps: (args) => handleOps(s, args),
-      onFinish: (args) => handleFinish(s, args),
-    },
-    recordPersisted: stored !== null,
-    store,
-    lastAck: -1,
-    context: undefined,
-    pending: [],
-    canonical: undefined,
-    lastPublished: undefined,
-    changed: [],
-    source: {
-      snapshot: () => s.canonical,
-      takeChanged: () => {
-        const changed = s.changed;
-        s.changed = [];
-        return changed;
-      },
-      setOnChange: (listener) => {
-        s.notify = listener ?? (() => {});
-      },
-    },
-    attach: "detached",
-    attachEpoch: 0,
-    running: false,
-    pumping: false,
-    transport: null,
-    waiters: [],
-    lifecycle: null,
-    notify: () => {},
-    emitEvent: () => {},
-    send: (command) => sendCommand(s, command),
-    commands: createMethodProxy((method, params) => s.send({ method, params })),
-  };
-  bindCommandsHost(s.commands, {
-    setListener: (listener) => {
-      s.lifecycle = listener;
-    },
-  });
-  return s;
-};
-
 const publish = (s: Session) => {
   if (s.canonical === s.lastPublished) return;
   s.lastPublished = s.canonical;
@@ -254,17 +128,51 @@ const sleepUntilWake = (s: Session, delayMs: number) =>
     s.waiters.push(waiter);
   });
 
-const settleAll = (
+const setRecord = (s: Session, record: StatewireSessionRecord) => {
+  s.record = record;
+  if (!s.ephemeral) s.store.save(record);
+};
+
+const setIdle = (s: Session, level: boolean) => {
+  if (level === s.idle) return;
+  s.idle = level;
+  s.notify();
+  if (level) s.onDone?.();
+};
+
+const cover = (s: Session, entry: Pending) => {
+  if (entry.applied) return;
+  entry.applied = true;
+  s.lifecycle?.onApplied(entry.inv);
+  s.lifecycle?.onCovered?.(entry.inv);
+};
+
+const settleEntry = (
   s: Session,
-  detach: "evicted" | "unmount" | "gone" | "superseded",
-  verdict?: {
-    entry: Pending;
-    failure: StatewireClient.SendFailure;
-  },
+  entry: Pending,
+  outcome:
+    | { ok: true; payload: unknown }
+    | { ok: false; failure: StatewireClient.SendFailure },
 ) => {
+  s.pending = s.pending.filter((p) => p !== entry);
+  if (outcome.ok) {
+    entry.resolve(outcome.payload);
+    s.lifecycle?.onSettle(entry.inv, {
+      type: "accepted",
+      payload: outcome.payload,
+    });
+  } else {
+    entry.reject(new StatewireSendError(outcome.failure));
+    s.lifecycle?.onSettle(entry.inv, {
+      type: "rejected",
+      error: new StatewireSendError(outcome.failure),
+    });
+  }
+};
+
+const settleAll = (s: Session, detach: "unmount" | "gone" | "superseded") => {
   const cause = (
     {
-      evicted: "session-lost",
       unmount: "unmount",
       gone: "stream-gone",
       superseded: "superseded",
@@ -272,12 +180,9 @@ const settleAll = (
   )[detach];
   const batch = s.pending;
   const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
-    const state = entry.state;
-    if (state.at === "awaiting-result")
-      return { fate: "result-unavailable", cause };
-    if (state.at === "queued") {
+    if (!entry.attempted) {
       const predecessorLost = batch.some(
-        (p) => p.seq < entry.seq && p.state.at !== "queued",
+        (p) => p.seq < entry.seq && p.attempted,
       );
       return predecessorLost
         ? { fate: "aborted", cause, predecessorLost }
@@ -286,221 +191,239 @@ const settleAll = (
     return { fate: "lost", cause };
   };
   for (const entry of [...batch]) {
-    const failure =
-      entry === verdict?.entry ? verdict.failure : detachFailure(entry);
-    transition(s, entry, { at: "done" }, { ok: false, failure });
+    s.lifecycle?.onCovered?.(entry.inv);
+    settleEntry(s, entry, { ok: false, failure: detachFailure(entry) });
   }
 };
 
-// Claims every unsettled real command for replay under the rotated client id,
-// in seq order; context submissions settle and the context re-sends whole.
-const claimReplays = (s: Session): Pending[] => {
-  const claimed = s.pending.filter(
-    (entry) => entry.inv !== null && !isResolved(entry.state),
-  );
-  if (claimed.length === 0) return [];
-  s.pending = s.pending.filter((p) => !claimed.includes(p));
-  return claimed;
+const restateContext = (s: Session) => {
+  s.ctxPending = [];
+  if (s.ctxOps === undefined) return;
+  const seq = s.record.ctxNextSeq;
+  setRecord(s, { ...s.record, ctxNextSeq: seq + 1 });
+  s.ctxPending.push({ seq, ops: s.ctxOps, posted: false });
 };
 
-const evict = (
-  s: Session,
-  verdict?: {
-    entry: Pending;
-    failure: StatewireClient.SendFailure;
-  },
-) => {
-  const replays = claimReplays(s);
-  settleAll(s, "evicted", verdict);
-  s.record = { clientId: newClientId(), nextSeq: 1 };
-  s.store.save(s.record);
-  s.attach = "detached";
-  // The server dropped this client's record and its stored context with it:
-  // the new session opens with a fresh full root replace.
-  if (s.context !== undefined) void s.send({ context: s.context });
-  for (const old of replays) {
-    if (old.inv) s.lifecycle?.onCovered?.(old.inv);
-    enqueue(s, old.command, 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
+// from 1 on the reset lane clocks.
+const resetRecord = (s: Session, clientId: string) => {
+  const survivors: Pending[] = [];
+  for (const entry of [...s.pending]) {
+    if (entry.attempted || entry.applied) {
+      s.lifecycle?.onCovered?.(entry.inv);
+      settleEntry(s, entry, {
+        ok: false,
+        failure: { fate: "lost", cause: "session-lost" },
+      });
+    } else {
+      survivors.push(entry);
+    }
+  }
+  s.pending = [];
+  s.durableSeq = 0;
+  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1 });
+  for (const old of survivors) {
+    s.lifecycle?.onCovered?.(old.inv);
+    enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
   }
+  restateContext(s);
   publish(s);
   wake(s);
 };
 
-const noteAcked = (s: Session, seq: number) => {
-  for (const entry of s.pending) {
-    if (entry.seq > seq || isStateSettled(entry.state)) continue;
-    if (entry.inv) s.lifecycle?.onAck(entry.inv);
-  }
-};
-
-const spliceAcked = (s: Session, seq: number, settleVoid: boolean) => {
-  for (const entry of [...s.pending]) {
-    const state = entry.state;
-    if (entry.seq > seq || isStateSettled(state)) continue;
-    if (state.at === "settled-live") {
-      transition(s, entry, { at: "done" });
-    } else if (settleVoid && !state.pendingMarked) {
-      transition(s, entry, { at: "done" }, { ok: true, payload: undefined });
-    } else {
-      transition(s, entry, { at: "awaiting-result", ...carried(state) });
-    }
-  }
+// The record died with the attach: mint a fresh id for the next one.
+const ephemeralDetach = (s: Session) => {
+  s.ephemeral = false;
+  s.sessionKnown = false;
+  resetRecord(s, newClientId());
 };
 
-const protocolError = (message: string): never => {
-  throw new Error(`statewire: protocol error: ${message}`);
+const rejectedFailure = (cmd: StatewireCmd): StatewireClient.SendFailure => {
+  const code =
+    cmd.code === undefined ||
+    cmd.code === "unknown-command" ||
+    cmd.code === "invalid-params"
+      ? cmd.code
+      : protocolError(`unknown rejected code: ${cmd.code}`);
+  return {
+    fate: "rejected",
+    cause: "server",
+    ...(code !== undefined && { code }),
+    ...(cmd.message !== undefined && { message: cmd.message }),
+    ...(cmd.payload !== undefined && { payload: cmd.payload }),
+  };
 };
 
-const applyResponse = (s: Session, response: StatewireResponse) => {
-  const entry = s.pending.find((p) => p.seq === response.seq);
+const handleCmd = (s: Session, cmd: StatewireCmd) => {
+  if (typeof cmd.seq !== "number") protocolError("cmd entry missing seq");
+  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.type === undefined) return;
+  const entry = s.pending.find((p) => p.seq === cmd.seq);
+  if (cmd.type === "applied") {
+    if (entry) cover(s, entry);
+    return;
+  }
   if (!entry) return;
-  const state = entry.state;
-  if (state.at === "done") return;
-  switch (response.type) {
-    case "pending":
-      if (
-        state.at === "queued" ||
-        state.at === "trying" ||
-        state.at === "posted"
-      ) {
-        transition(s, entry, { ...state, pendingMarked: true });
-      }
-      break;
-    case "accepted":
-      if (state.at === "settled-live") break;
-      transition(
-        s,
-        entry,
-        state.at === "awaiting-result"
-          ? { at: "done" }
-          : { at: "settled-live", ...carried(state) },
-        { ok: true, payload: response.payload },
-      );
-      break;
-    case "rejected":
-      transition(
-        s,
-        entry,
-        { at: "done" },
-        {
-          ok: false,
-          failure:
-            response.code === "unknown-command"
-              ? { fate: "unknown-command", cause: "server" }
-              : response.code === "invalid-params"
-                ? {
-                    fate: "invalid-params",
-                    cause: "server",
-                    message:
-                      response.message ??
-                      protocolError("rejected response missing message"),
-                  }
-                : {
-                    fate: "rejected",
-                    cause: "server",
-                    message:
-                      response.message ??
-                      protocolError("rejected response missing message"),
-                    ...(response.payload !== undefined && {
-                      payload: response.payload,
-                    }),
+  cover(s, entry);
+  const outcome =
+    cmd.type === "result"
+      ? { ok: true as const, payload: reviveResponse(cmd).payload }
+      : cmd.type === "rejected"
+        ? { ok: false as const, failure: rejectedFailure(reviveResponse(cmd)) }
+        : cmd.type === "failed"
+          ? {
+              ok: false as const,
+              failure: {
+                fate: "failed" as const,
+                cause: "server" as const,
+                ...(cmd.message !== undefined && { message: cmd.message }),
+              },
+            }
+          : cmd.type === "crashed"
+            ? {
+                ok: false as const,
+                failure: { fate: "crashed" as const, cause: "server" as const },
+              }
+            : cmd.type === "expired"
+              ? {
+                  ok: false as const,
+                  failure: {
+                    fate: "expired" as const,
+                    cause: "server" as const,
                   },
-        },
-      );
-      break;
-    case "crashed":
-    case "result-unavailable":
-      if (state.at === "settled-live") break;
-      transition(
-        s,
-        entry,
-        state.at === "awaiting-result"
-          ? { at: "done" }
-          : { at: "settled-live", ...carried(state) },
-        { ok: false, failure: { fate: response.type, cause: "server" } },
-      );
-      break;
-  }
+                }
+              : protocolError(`unknown cmd type: ${String(cmd.type)}`);
+  settleEntry(s, entry, outcome);
+};
+
+const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
+  for (const cmd of cmds) handleCmd(s, cmd);
+  wake(s);
 };
 
 const ingestOps = (s: Session, ops: unknown[]) => {
   const applied = applyOps(s.canonical, ops);
   s.canonical = applied.state;
   s.changed.push(...applied.changedPaths);
-  return applied.events;
 };
 
-const publishIngested = (s: Session, events: unknown[]) => {
+const publishIngested = (s: Session) => {
   publish(s);
-  for (const event of events) s.emitEvent(event);
   wake(s);
 };
 
-const handleSnapshot = (
+const RECORDS = ["fresh", "resumed", "ephemeral"];
+
+// Snap a resumed session's lane clocks onto the record: seqs above the stated
+// watermark were never admitted, so a stale restored clock re-stamps its
+// never-admitted statements consecutively after the watermark.
+const snapClocks = (s: Session, seqWm: number, ctxWm: number) => {
+  const tail = s.pending.filter((p) => p.seq > seqWm);
+  const cmdAligned =
+    tail.every((p, i) => p.seq === seqWm + 1 + i) &&
+    s.record.nextSeq === seqWm + tail.length + 1;
+  if (!cmdAligned) {
+    s.pending = s.pending.filter((p) => p.seq <= seqWm);
+    setRecord(s, { ...s.record, nextSeq: seqWm + 1 });
+    for (const old of tail) {
+      s.lifecycle?.onCovered?.(old.inv);
+      enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
+    }
+  }
+  const ctxAligned =
+    s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) &&
+    s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1;
+  if (!ctxAligned) {
+    setRecord(s, { ...s.record, ctxNextSeq: ctxWm + 1 });
+    restateContext(s);
+  }
+};
+
+const handleHello = (
   s: Session,
-  { ops, lastSeq }: { ops: unknown[]; lastSeq: number },
+  { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
 ) => {
-  if (lastSeq === -1 && s.attach !== "detached") {
-    evict(s);
-    s.transport?.connection.reconnect();
-    publishIngested(s, ingestOps(s, ops));
-    return;
+  const record = syn.record ?? "fresh";
+  if (!RECORDS.includes(record)) {
+    protocolError(`unknown record: ${String(record)}`);
   }
-  const events = ingestOps(s, ops);
+  ingestOps(s, ops);
   s.attach = "attached";
   s.attachEpoch += 1;
-  // The attach snapshot is not the true covering envelope: acked entries
-  // stay awaiting their result and re-send under seq dedup.
-  noteAcked(s, lastSeq);
-  spliceAcked(s, lastSeq, false);
-  s.lastAck = lastSeq;
-  for (const entry of s.pending) {
-    const state = entry.state;
-    if (entry.seq <= lastSeq) {
-      if (state.at === "awaiting-result" && state.posted) {
-        transition(s, entry, { ...state, posted: false });
-      }
-      if (state.at === "awaiting-result") void pump(s);
-    } else if (state.at === "posted") {
-      // Above the ack watermark a prior receipt no longer counts.
-      transition(s, entry, {
-        at: "trying",
-        pendingMarked: state.pendingMarked,
-        failedAttempts: state.failedAttempts,
-      });
-      void pump(s);
-    } else if (state.at === "settled-live" && state.posted) {
-      transition(s, entry, { ...state, posted: false });
-      void pump(s);
+  s.frameFailures = 0;
+  s.resumeAt = 0;
+  s.ephemeral = record === "ephemeral";
+  const [attachCmd, attachCtx] = s.attachLaneSeqs;
+  s.attachLaneSeqs = [new Set(), new Set()];
+  if (record === "resumed") {
+    // Resending unsettled statements is exactly-once-safe: absorbed replays
+    // re-emit their stored verdicts (applied while still in flight).
+    for (const entry of s.pending) {
+      entry.posted = attachCmd.has(entry.seq);
     }
+    const ctxWatermark = syn.ctxSeq ?? 0;
+    s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
+    for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
+    snapClocks(s, syn.seq ?? 0, ctxWatermark);
+  } else {
+    resetRecord(s, s.record.clientId);
   }
-  publishIngested(s, events);
+  s.sessionKnown = true;
+  publishIngested(s);
+  void pump(s);
 };
 
 const handleOps = (
   s: Session,
-  {
-    ops,
-    res,
-    ack,
-  }: { ops: unknown[]; res?: StatewireResponse[]; ack?: number },
+  { ops, cmds }: { ops: unknown[]; cmds: StatewireCmd[] },
 ) => {
-  const horizon = ack === undefined ? s.lastAck : Math.max(s.lastAck, ack);
-  if (res !== undefined) {
-    for (const response of res) {
-      if (response.seq > horizon) {
-        protocolError("response seq beyond the ack");
-      }
-    }
+  ingestOps(s, ops);
+  for (const cmd of cmds) handleCmd(s, cmd);
+  publishIngested(s);
+};
+
+// A {syn} refusal never settles: reconcile the resend queues against the
+// stated watermarks; retry present means wait, absent means resend now.
+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;
   }
-  const events = ingestOps(s, ops);
-  if (ack !== undefined) noteAcked(s, ack);
-  if (res !== undefined) for (const response of res) applyResponse(s, response);
-  if (ack !== undefined) {
-    spliceAcked(s, ack, true);
-    s.lastAck = Math.max(s.lastAck, ack);
+  if (typeof ctxSeq === "number") {
+    s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxSeq);
+    for (const c of s.ctxPending) c.posted = false;
   }
-  publishIngested(s, events);
+  if (typeof syn.retry === "number") {
+    s.resumeAt = Date.now() + Math.max(0, syn.retry);
+  }
+  const firstCmd = s.pending.find((p) => !p.posted);
+  const firstCtx = s.ctxPending.find((c) => !c.posted);
+  const clocksAhead =
+    (typeof syn.seq === "number" &&
+      firstCmd !== undefined &&
+      firstCmd.seq > Math.max(syn.seq, s.durableSeq) + 1) ||
+    (typeof syn.ctxSeq === "number" &&
+      firstCtx !== undefined &&
+      firstCtx.seq > syn.ctxSeq + 1);
+  // Clocks ahead of a record that cannot admit them: reattach first and let
+  // the hello's record arbitrate.
+  if (clocksAhead) s.transport?.connection.reconnect();
+  wake(s);
+  void pump(s);
+};
+
+const handleDetach = (s: Session) => {
+  if (s.attach === "attached") s.attach = "detached";
+  if (s.ephemeral) ephemeralDetach(s);
+  wake(s);
 };
 
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
@@ -513,130 +436,120 @@ const handleFinish = (s: Session, { reason }: { reason: string }) => {
 
 const isFinished = (s: Session) => s.attach === "finished";
 
-const sendable = (p: Pending) =>
-  p.state.at === "queued" ||
-  p.state.at === "trying" ||
-  ((p.state.at === "awaiting-result" || p.state.at === "settled-live") &&
-    !p.state.posted);
+type Lanes = {
+  frame: StatewireFrame;
+  cmdEntries: Pending[];
+  ctxEntries: CtxPending[];
+};
+
+// A lane must be strictly consecutive within a frame: the first unposted run
+// per lane rides now, later runs ride follow-up frames.
+const buildLanes = (s: Session): Lanes | null => {
+  const ctxEntries: CtxPending[] = [];
+  for (const entry of s.ctxPending) {
+    if (entry.posted) continue;
+    if (ctxEntries.length > 0 && entry.seq !== ctxEntries.at(-1)!.seq + 1)
+      break;
+    ctxEntries.push(entry);
+  }
+  const cmdEntries: Pending[] = [];
+  for (const entry of s.pending) {
+    if (entry.posted) continue;
+    if (cmdEntries.length > 0 && entry.seq !== cmdEntries.at(-1)!.seq + 1)
+      break;
+    cmdEntries.push(entry);
+  }
+  if (ctxEntries.length === 0 && cmdEntries.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) => ({ ...p.command, seq: p.seq })),
+      }),
+    },
+    cmdEntries,
+    ctxEntries,
+  };
+};
+
+const takeAttachLanes = (s: Session): StatewireFrame | null => {
+  s.attachLaneSeqs = [new Set(), new Set()];
+  const wanted = s.lanesOnAttach;
+  s.lanesOnAttach = false;
+  if (!wanted || !s.sessionKnown) return null;
+  const lanes = buildLanes(s);
+  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;
+  return lanes.frame;
+};
 
 const pump = async (s: Session) => {
   if (s.pumping) return;
   s.pumping = true;
   try {
     while (s.running && !isFinished(s)) {
-      const entry = s.pending.find(sendable);
-      if (!entry) return;
       const transport = s.transport;
+      if (buildLanes(s) === null) return;
       if (s.attach !== "attached" || !transport) {
+        if (transport?.connection.status === "idle") {
+          transport.connection.reconnect();
+        }
         await waitForWake(s);
         continue;
       }
-      const clientId = s.record.clientId;
-      const epoch = s.attachEpoch;
-      if (entry.state.at === "queued") {
-        transition(s, entry, {
-          at: "trying",
-          pendingMarked: entry.state.pendingMarked,
-          failedAttempts: 0,
-        });
+      const resumeDelay = s.resumeAt - Date.now();
+      if (resumeDelay > 0) {
+        await sleepUntilWake(s, resumeDelay);
+        continue;
       }
-      let result: StatewireSubmitResult;
+      const lanes = buildLanes(s);
+      if (!lanes) continue;
+      const epoch = s.attachEpoch;
+      for (const entry of lanes.cmdEntries) entry.attempted = true;
+      let result;
       try {
-        result = await transport.send({
-          seq: entry.seq,
-          command: entry.command,
-        });
-      } catch (error) {
+        result = await transport.send(lanes.frame);
+      } catch {
         if (!s.running || isFinished(s)) return;
-        if (!s.pending.includes(entry)) continue;
-        const state = inFlight(entry.state);
-        transition(s, entry, {
-          ...state,
-          failedAttempts: state.failedAttempts + 1,
-        });
-        await sleepUntilWake(s, retryDelay(error, state.failedAttempts + 1));
+        s.frameFailures += 1;
+        await sleepUntilWake(s, backoff(s.frameFailures));
         continue;
       }
       if (!s.running) return;
-      if (!s.pending.includes(entry)) continue;
-      if (result.type === "receipt") {
-        const response = result.response;
-        const state = entry.state;
-        if (state.at === "trying" || state.at === "posted") {
-          transition(s, entry, {
-            at: "posted",
-            pendingMarked: state.pendingMarked,
-            failedAttempts: state.failedAttempts,
-          });
-        } else if (
-          state.at === "awaiting-result" ||
-          state.at === "settled-live"
-        ) {
-          transition(s, entry, { ...state, posted: true });
-        }
-        if (entry.inv) s.lifecycle?.onPosted?.(entry.inv);
-        if (response !== undefined) {
-          applyResponse(s, response);
-          publish(s);
+      s.frameFailures = 0;
+      if (result.type === "ok") {
+        if (epoch === s.attachEpoch) {
+          for (const entry of lanes.cmdEntries) {
+            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 === "rejected") {
-        transition(
-          s,
-          entry,
-          { at: "done" },
-          {
-            ok: false,
-            failure: {
-              fate: "rejected",
-              cause: "server",
-              message: result.message,
-            },
-          },
-        );
-        publish(s);
+      } else if (result.type === "refusal") {
+        if (epoch === s.attachEpoch) handleRefusal(s, result.syn);
       } else if (result.type === "stale-lease") {
-        if (epoch === s.attachEpoch) await waitForWake(s);
-      } else if (result.type === "unknown-client") {
-        // Eviction is never decided on the POST leg: re-attach first and let
-        // the snapshot's lastSeq deliver the verdict. An answered attempt
-        // proves the server never admitted this seq, so a clean entry requeues.
+        // A POST outlived its attach: reattach first, the hello arbitrates.
         if (epoch === s.attachEpoch) {
-          const state = entry.state;
-          if (state.at === "trying" && state.failedAttempts === 0) {
-            transition(s, entry, {
-              at: "queued",
-              pendingMarked: state.pendingMarked,
-            });
-          }
-          s.transport?.connection.reconnect();
-          while (
-            s.running &&
-            !isFinished(s) &&
-            epoch === s.attachEpoch &&
-            clientId === s.record.clientId
-          ) {
+          transport.connection.reconnect();
+          await waitForWake(s);
+        }
+      } else if (result.type === "no-lease") {
+        // No out-of-band write channel: the frame rides a fresh attach.
+        if (epoch === s.attachEpoch) {
+          s.lanesOnAttach = true;
+          transport.connection.reconnect();
+          while (s.running && !isFinished(s) && epoch === s.attachEpoch) {
             await waitForWake(s);
           }
         }
-      } else if (result.type === "seq-gap") {
-        if (clientId === s.record.clientId) {
-          console.error(
-            `statewire: server reports a seq gap for seq ${entry.seq}; ` +
-              "treating the session as corrupt and rotating the client id",
-          );
-          // Every attempt answered means the server never saw it; a thrown
-          // attempt may have left the machine unanswered, so the verdict is "lost".
-          const state = inFlight(entry.state);
-          const failure: StatewireClient.SendFailure =
-            state.at === "awaiting-result"
-              ? { fate: "result-unavailable", cause: "session-lost" }
-              : {
-                  fate: state.failedAttempts > 0 ? "lost" : "aborted",
-                  cause: "session-lost",
-                };
-          evict(s, { entry, failure });
-          s.transport?.connection.reconnect();
-        }
       }
     }
   } finally {
@@ -667,38 +580,38 @@ const setTransport = (s: Session, transport: RemoteLink) => {
 
 const enqueue = (
   s: Session,
-  command: StatewireWireCommand,
+  command: WireCommand,
+  params: readonly unknown[],
   resolve: (payload: unknown) => void,
   reject: (error: StatewireSendError) => void,
 ) => {
   const seq = s.record.nextSeq;
-  s.record = { ...s.record, nextSeq: seq + 1 };
-  s.store.save(s.record);
+  setRecord(s, { ...s.record, nextSeq: seq + 1 });
   const entry: Pending = {
     seq,
     command,
-    inv:
-      command.method === undefined
-        ? null
-        : {
-            method: command.method,
-            params: command.params,
-            ts: Date.now(),
-            seq,
-            clientId: s.record.clientId,
-          },
-    state: { at: "queued", pendingMarked: false },
+    inv: {
+      method: command.method,
+      params,
+      ts: Date.now(),
+      seq,
+      clientId: s.record.clientId,
+    },
+    attempted: false,
+    posted: false,
+    applied: false,
     resolve,
     reject,
   };
   s.pending.push(entry);
-  if (entry.inv) s.lifecycle?.onStart(entry.inv);
+  s.lifecycle?.onStart(entry.inv);
   void pump(s);
 };
 
 const sendCommand = (
   s: Session,
-  command: StatewireWireCommand,
+  method: string,
+  params: readonly unknown[],
 ): Promise<unknown> => {
   if (!s.running) {
     return rejectedSend({ fate: "aborted", cause: "unmount" });
@@ -707,34 +620,115 @@ const sendCommand = (
     return rejectedSend({ fate: "aborted", cause: "stream-gone" });
   }
   const result = new Promise<unknown>((resolve, reject) => {
-    enqueue(s, command, resolve, reject);
+    const { params: encoded, meta } = encodeParams(params);
+    enqueue(
+      s,
+      { method, params: encoded, ...(meta !== undefined && { meta }) },
+      params,
+      resolve,
+      reject,
+    );
   });
   result.catch(() => {});
   return result;
 };
 
-const setContext = (
-  s: Session,
-  value: Record<string, unknown>,
-): Promise<unknown> => {
+const setContext = (s: Session, value: Record<string, unknown>): void => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error("statewire: context must be a plain object");
   }
-  s.context = value;
-  return s.send({ context: value });
+  const { value: encoded, meta } = encodeValue(value);
+  s.ctxOps = [
+    {
+      op: "replace",
+      path: [],
+      value: encoded,
+      ...(meta !== undefined && { meta }),
+    },
+  ];
+  const seq = s.record.ctxNextSeq;
+  setRecord(s, { ...s.record, ctxNextSeq: seq + 1 });
+  s.ctxPending.push({ seq, ops: s.ctxOps, posted: false });
+  wake(s);
+  void pump(s);
 };
 
 export const useStatewireSession = (
   options: StatewireSessionOptions,
-  emit: (event: unknown) => void,
 ): Session => {
-  const [s] = useState(() => createSession(options));
-  useEffect(() => {
-    s.emitEvent = emit;
-    return () => {
-      s.emitEvent = () => {};
+  const [defaultStore] = useState(createMemorySessionStore);
+  const store = options.sessionStore ?? defaultStore;
+  const [s] = useState((): Session => {
+    const stored = store.load();
+    const record = stored ?? {
+      clientId: newClientId(),
+      nextSeq: 1,
+      ctxNextSeq: 1,
     };
-  }, [s, emit]);
+    const session: Session = {
+      record,
+      ctx: {
+        get clientId() {
+          return session.record.clientId;
+        },
+        takeAttachLanes: () => takeAttachLanes(session),
+        onHello: (args) => handleHello(session, args),
+        onOps: (args) => handleOps(session, args),
+        onCmds: (cmds) => handleCmds(session, cmds),
+        onRefusal: (syn) => handleRefusal(session, syn),
+        onIdle: (level) => setIdle(session, level),
+        onDetach: () => handleDetach(session),
+        onFinish: (args) => handleFinish(session, args),
+      },
+      recordPersisted: stored !== null,
+      store,
+      ephemeral: false,
+      sessionKnown: false,
+      durableSeq: 0,
+      resumeAt: 0,
+      idle: false,
+      onDone: undefined,
+      ctxOps: undefined,
+      ctxPending: [],
+      lanesOnAttach: false,
+      attachLaneSeqs: [new Set(), new Set()],
+      frameFailures: 0,
+      pending: [],
+      canonical: undefined,
+      lastPublished: undefined,
+      changed: [],
+      source: {
+        snapshot: () => session.canonical,
+        takeChanged: () => {
+          const changed = session.changed;
+          session.changed = [];
+          return changed;
+        },
+        setOnChange: (listener) => {
+          session.notify = listener ?? (() => {});
+        },
+      },
+      attach: "detached",
+      attachEpoch: 0,
+      running: false,
+      pumping: false,
+      transport: null,
+      waiters: [],
+      lifecycle: null,
+      notify: () => {},
+      commands: createMethodProxy((method, params) =>
+        sendCommand(session, method, params),
+      ),
+    };
+    bindCommandsHost(session.commands, {
+      setListener: (listener) => {
+        session.lifecycle = listener;
+      },
+    });
+    return session;
+  });
+  s.store = store;
+  s.onDone = options.onDone;
   useEffect(() => {
     start(s);
     return () => stop(s);