statewire 0.24.0 → 0.24.2

package/src/client/session.ts

@@ -2,7 +2,8 @@ import { encodeContext } from "../wire/context";
 import { wrapStorageError } from "./storageError";
 import {
   DEFAULT_PROTOCOL,
-  WIRE_VERSION,
+  CLIENT_WIRE,
+  GAP_FILL_VERSION,
   protocolOffers,
   inRange,
 } from "../wire/protocol";
@@ -162,6 +163,8 @@ type Session = {
   /** Ephemeral lane clocks: restart at 1 on every attach. */
   ephemeralSeqs: Record<string, number>;
   resumeAt: number;
+  /** A refusal named sent durable stamps: a reattach's hello decides them, after `resumeAt`. */
+  reattach: boolean;
   idle: boolean;
   onSessionLost: StatewireClient.OnSessionLost | undefined;
   onDeprecatedPath: StatewireClient.OnDeprecatedPath | undefined;
@@ -182,6 +185,10 @@ type Session = {
   lanesOnAttach: boolean;
   attachEntries: ReadonlySet<Pending>;
   frameFailures: number;
+  /** A later hello decides stamps this one could not: another live sharer's stamp sat below them. */
+  recheck: ReturnType<typeof setTimeout> | undefined;
+  /** Hellos in a row that left stamps waiting at the same watermarks: the recheck backs off. */
+  rechecks: { watermarks: string; count: number };
   pending: Pending[];
   canonical: unknown;
   documentListeners: Set<() => void>;
@@ -1321,14 +1328,16 @@ const sessionLostInner = (s: Session, protocol: string, seqWm: number) => {
         },
       );
   } else {
-    // Default: the whole queue goes, each command a failure notice.
+    // Default: the queue goes, each command a failure notice. Held entries
+    // never went out: they stay held where they are.
     const stamps = mergeBacklog(s, protocol);
-    const queued = outboxOf(lane);
-    const { outbox: _outbox, ...rest } = lane;
+    const held = outboxOf(lane).filter((c) => c.held);
+    const queued = outboxOf(lane).filter((c) => !c.held);
+    const keep = new Set(held.map((c) => c.id));
     setRecord(
       s,
       withLane(s.record, protocol, {
-        ...withNotices(rest, [
+        ...withNotices(withOutbox(lane, held), [
           ...stamps.map((c) => lostNotice(c)),
           ...queued.map((c) => lostNotice(c)),
         ]),
@@ -1345,7 +1354,9 @@ const sessionLostInner = (s: Session, protocol: string, seqWm: number) => {
         ),
       }),
     );
-    for (const p of s.pending.filter((q) => q.command.protocol === protocol)) {
+    for (const p of s.pending.filter(
+      (q) => q.command.protocol === protocol && !keep.has(q.id),
+    )) {
       s.lifecycle?.onCovered?.(p.inv);
       settleEntry(s, p, { ok: false, failure }, "noticed");
     }
@@ -1355,14 +1366,17 @@ const sessionLostInner = (s: Session, protocol: string, seqWm: number) => {
   wake(s);
 };
 
-// Every stamp above the watermark, whichever sharer made it, returns to the
-// front of the outbox. A stamp past watermark+1, or one this client saw
-// admitted, proves the server record that admitted it is gone.
+// Every stamp above the watermark returns to the front of the outbox. A stamp
+// past watermark+1, or one this client saw admitted, proves the server record
+// that admitted it is gone. Another live sharer's stamp may still be on its
+// way on that sharer's attach: it and every stamp after it wait for a later
+// hello; the stamps before it never arrived and resend under their seqs.
 const demote = (
   s: Session,
   protocol: string,
   watermark: number,
   demoted: Set<string>,
+  waiting: Set<Pending>,
 ) => {
   const lane = laneOf(s.record, protocol);
   const local = laneEntries(s, protocol).filter((p) => p.seq > watermark);
@@ -1380,6 +1394,17 @@ const demote = (
     sessionLostInner(s, protocol, watermark);
     return;
   }
+  const me = s.store.owner?.id;
+  const foreign = moved.find(
+    (c) =>
+      c.owner !== undefined &&
+      c.owner !== me &&
+      !local.some((p) => p.id === c.id),
+  );
+  if (foreign !== undefined) {
+    for (const p of local) if (p.seq > foreign.seq) waiting.add(p);
+    return;
+  }
   setRecord(
     s,
     withLane(s.record, protocol, {
@@ -1399,6 +1424,24 @@ const demote = (
   sortPending(s);
 };
 
+const recheckLater = (s: Session, watermarks: string) => {
+  if (s.rechecks.watermarks !== watermarks)
+    s.rechecks = { watermarks, count: 0 };
+  s.rechecks.count += 1;
+  if (s.recheck !== undefined) return;
+  s.recheck = setTimeout(
+    () => {
+      s.recheck = undefined;
+      if (s.running && s.attach === "attached")
+        s.transport?.connection.reconnect();
+    },
+    backoff(s.rechecks.count + 1),
+  );
+};
+
+const gapFill = (s: Session) =>
+  s.selection !== undefined && s.selection.version >= GAP_FILL_VERSION;
+
 const selectionOf = (
   syn: StatewireSyn,
 ): StatewireProtocol.Selection | undefined => {
@@ -1414,6 +1457,21 @@ const selectionOf = (
   };
 };
 
+// The host admits an attach's durable statements right after its hello.
+const carriedThrough = (
+  lane: { name: string; seq?: number },
+  attached: ReadonlySet<Pending>,
+) => {
+  const carried = new Set(
+    [...attached]
+      .filter((p) => p.command.protocol === lane.name)
+      .map((p) => p.seq),
+  );
+  let seq = lane.seq ?? 0;
+  while (carried.has(seq + 1)) seq += 1;
+  return seq;
+};
+
 const handleHello = (
   s: Session,
   { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
@@ -1435,6 +1493,7 @@ const handleHello = (
   s.attachEpoch += 1;
   s.frameFailures = 0;
   s.resumeAt = 0;
+  s.reattach = false;
   const lanes = syn.protocols ?? [];
   s.ephemeral =
     lanes.length > 0 && lanes.every((lane) => lane.record === "ephemeral");
@@ -1446,6 +1505,7 @@ const handleHello = (
     // verdicts (the server never re-runs them); seqs above it never arrived
     // and go back to the outbox for fresh ones.
     const demoted = new Set<string>();
+    const waiting = new Set<Pending>();
     for (const lane of lanes) {
       if (lane.record === "ephemeral") {
         s.ephemeralSeqs[lane.name] = Math.max(
@@ -1456,17 +1516,24 @@ const handleHello = (
         );
         continue;
       }
-      demote(s, lane.name, lane.seq ?? 0, demoted);
+      demote(s, lane.name, carriedThrough(lane, attached), demoted, waiting);
       s.durableSeq[lane.name] = lane.seq ?? 0;
     }
     for (const entry of s.pending) {
       entry.posted =
         attached.has(entry) ||
+        waiting.has(entry) ||
         (isStamped(entry) &&
           entry.seq <= durableSeqOf(s, entry.command.protocol) &&
           !isEphemeral(s, entry.command.protocol));
       entry.stale = false;
     }
+    if (waiting.size > 0)
+      recheckLater(
+        s,
+        JSON.stringify(lanes.map((lane) => [lane.name, lane.seq])),
+      );
+    else s.rechecks = { watermarks: "", count: 0 };
     syncBacklogInner(s);
     s.sessionKnown = true;
     flushInner(s, demoted);
@@ -1498,10 +1565,26 @@ const handleOps = (
 // 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.
+// Under the gap-fill wire a refusal can predate frames sent since: durable
+// lanes never resend from it, a reattach's hello decides them.
 const handleRefusal = (s: Session, syn: StatewireSyn) => {
-  const lanes = (syn.protocols ?? []).filter(
+  const stated = (syn.protocols ?? []).filter(
     (lane): lane is { name: string; seq: number } => lane.seq !== undefined,
   );
+  const lanes = gapFill(s)
+    ? stated.filter(({ name }) => isEphemeral(s, name))
+    : stated;
+  if (
+    gapFill(s) &&
+    s.pending.some((p) => {
+      if (!isStamped(p) || !p.attempted) return false;
+      const protocol = p.command.protocol;
+      if (isEphemeral(s, protocol)) return false;
+      const seq = stated.find((lane) => lane.name === protocol)?.seq ?? 0;
+      return p.seq > Math.max(seq, durableSeqOf(s, protocol));
+    })
+  )
+    s.reattach = true;
   for (const { name, seq } of lanes) {
     const watermark = isEphemeral(s, name)
       ? seq
@@ -1683,21 +1766,47 @@ const pump = async (s: Session) => {
     while (s.running && !isFinished(s)) {
       if (!s.hydrated) await s.ready;
       const transport = s.transport;
+      if (s.reattach && s.attach === "attached" && transport) {
+        const delay = s.resumeAt - Date.now();
+        if (delay > 0) {
+          await sleepUntilWake(s, delay);
+          continue;
+        }
+        // Ephemeral answers ride only this attach: drain them first.
+        if (
+          s.pending.some(
+            (p) =>
+              isStamped(p) && p.attempted && isEphemeral(s, p.command.protocol),
+          )
+        ) {
+          await waitForWake(s);
+          continue;
+        }
+        s.reattach = false;
+        const epoch = s.attachEpoch;
+        transport.connection.reconnect();
+        while (s.running && !isFinished(s) && epoch === s.attachEpoch)
+          await waitForWake(s);
+        continue;
+      }
       const flushable = flushCandidates(s).length > 0;
-      const queued = s.pending.some((p) => isOutboxed(p) && !p.inv.held);
+      const queued =
+        s.pending.some((p) => isOutboxed(p) && !p.inv.held) ||
+        queuedInRecord(s);
       if (
         buildLanes(s) === null &&
         !flushable &&
         (!queued || s.attach === "attached")
       )
         return;
-      if (transport?.parked && s.pending.length === 0) return;
+      const waiting = s.pending.length > 0 || queued;
+      if (transport?.parked && !waiting) return;
       if (s.attach !== "attached" || !transport) {
-        if (s.pending.length === 0) return;
+        if (!waiting) return;
         if (
           (transport?.connection.status === "standby" &&
             transport.connection.reason === "idle") ||
-          (transport?.parked && s.pending.length > 0)
+          transport?.parked
         ) {
           transport.connection.reconnect();
         }
@@ -1743,6 +1852,18 @@ const pump = async (s: Session) => {
           : send(lanes));
       } catch {
         if (!s.running || isFinished(s)) return;
+        // The frame may have arrived. Under the gap-fill wire its seqs never
+        // go out again: the next hello answers what arrived and frees the rest.
+        if (lanes !== null && lanes.entries.length > 0 && gapFill(s)) {
+          if (epoch !== s.attachEpoch) continue;
+          for (const entry of lanes.entries)
+            if (s.pending.includes(entry)) entry.posted = true;
+          s.frameFailures += 1;
+          await sleepUntilWake(s, backoff(s.frameFailures));
+          if (s.running && epoch === s.attachEpoch && s.attach === "attached")
+            transport.connection.reconnect();
+          continue;
+        }
         if (lanes?.frame.ctx?.length) {
           s.lanesOnAttach = true;
           transport.connection.reconnect();
@@ -1852,6 +1973,8 @@ const start = (s: Session) => {
 
 const stop = (s: Session) => {
   s.running = false;
+  clearTimeout(s.recheck);
+  s.recheck = undefined;
   if (s.shared) {
     s.shared.unsubscribe?.();
     s.shared.unsubscribe = null;
@@ -2038,6 +2161,16 @@ const flushCandidates = (s: Session): Candidate[] =>
     return order.slice(0, free).map((stored) => ({ protocol, stored }));
   });
 
+// An entry the record holds that a flush would stamp once attached, whether
+// or not this page made the send: inserted, or kept from an earlier mount or
+// another sharer. It dials a parked or idle transport as a send does.
+const queuedInRecord = (s: Session) =>
+  Object.keys(s.record.lanes).some(
+    (protocol) =>
+      (s.selection ? negotiated(s, protocol) : offered(s, protocol)) &&
+      bubble(s, protocol, laneQueue(s, protocol)).free > 0,
+  );
+
 const reasonOf = (
   s: Session,
   stored: StatewireClient.OutboxCommand,
@@ -2372,7 +2505,7 @@ export const updateOutbox = (
 const producedOf = (
   s: Session,
 ): NonNullable<StatewireClient.SessionCommand["produced"]> => ({
-  wire: s.options.wireVersion ?? { version: WIRE_VERSION },
+  wire: s.options.wireVersion ?? CLIENT_WIRE,
   protocols:
     protocolOffers(s.options) === "*" && s.selection
       ? s.selection.protocols
@@ -2440,6 +2573,7 @@ export const insertOutbox = (
       return;
     }
     let base = s.record;
+    let entered = stored;
     if (entry.from !== undefined) {
       // Re-inserting a settled update consumes it in the same write: a
       // redelivery finds it gone.
@@ -2447,16 +2581,27 @@ export const insertOutbox = (
         l.inbox?.some((n) => n.id === entry.from),
       );
       if (source === undefined || locate(s, id) !== undefined) return;
+      const notice = source[1].inbox!.find((n) => n.id === entry.from)!;
+      entered = { ...stored, ts: notice.ts };
       base = withLane(base, source[0], withoutNotice(source[1], entry.from));
     }
     const lane = laneOf(base, protocol);
+    // A re-queued command keeps its place: ahead of what was queued after it.
+    const later = outboxOf(lane).find((c) => c.ts >= entered.ts);
+    const position =
+      entry.from !== undefined &&
+      entry.after === undefined &&
+      entry.before === undefined &&
+      later !== undefined
+        ? { before: later.id }
+        : entry;
     try {
       setRecord(
         s,
         withLane(
           base,
           protocol,
-          withOutbox(lane, placed(outboxOf(lane), stored, entry)),
+          withOutbox(lane, placed(outboxOf(lane), entered, position)),
         ),
       );
     } catch (error) {
@@ -2728,7 +2873,7 @@ const loadSessionRecord = (
   let stored = store.load();
   if (stored !== null) validateLanes(stored);
   const current = {
-    wire: options.wireVersion ?? { version: WIRE_VERSION },
+    wire: options.wireVersion ?? CLIENT_WIRE,
     protocols: protocolOffers(options),
   };
   const compatible = (record: StatewireClient.SessionRecord) =>
@@ -2861,6 +3006,7 @@ export const useStatewireSession = (
       durableSeq: {},
       ephemeralSeqs: {},
       resumeAt: 0,
+      reattach: false,
       idle: false,
       onSessionLost: undefined,
       onDeprecatedPath: undefined,
@@ -2878,6 +3024,8 @@ export const useStatewireSession = (
       lanesOnAttach: false,
       attachEntries: new Set(),
       frameFailures: 0,
+      recheck: undefined,
+      rechecks: { watermarks: "", count: 0 },
       pending: [],
       canonical: undefined,
       documentListeners: new Set(),

package/src/host/host.ts

@@ -182,6 +182,7 @@ export type CommandsSubmission = {
   clientId?: string;
   caller?: StatewireHost.Caller;
   context?: Statewire.Context;
+  version?: string;
   attach?: StatewireHost.Attach;
   onApplied?: () => void;
   onSettle?: (outcome: CommandsOutcome) => void;
@@ -206,6 +207,7 @@ export const bindCommandsHost = (commands: object, host: CommandsHost) => {
 
 type QueuedCall = {
   context?: Statewire.Context;
+  version?: string | undefined;
   method: string;
   params: readonly unknown[];
   ts: number;
@@ -223,6 +225,7 @@ type ActiveInvocation = CommandsInvocation & {
 
 type CommandsCell = {
   context: (() => Statewire.Context) | undefined;
+  version: string | undefined;
   handlers: Record<string, (...args: never[]) => unknown> | null;
   queue: QueuedCall[];
   active: Map<ActiveInvocation, QueuedCall>;
@@ -364,9 +367,16 @@ const dispatch = (cell: CommandsCell, call: QueuedCall) => {
   cell.listener?.onStart(inv);
   cell.listener?.onPosted?.(inv);
   const attach = call.origin?.attach;
+  const version =
+    call.origin !== undefined ? call.origin.version : call.version;
   const ctx: StatewireHost.Ctx = {
     caller: call.origin?.caller ?? LOCAL_CALLER,
     context: call.context ?? call.origin?.context ?? Object.freeze({}),
+    get version() {
+      if (version === undefined)
+        throw new Error("statewire: in-process dispatch has no version");
+      return version;
+    },
     get attach() {
       if (attach === undefined)
         throw new Error("statewire: in-process dispatch has no attach");
@@ -445,6 +455,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
   const [built] = useState(() => {
     const cell: CommandsCell = {
       context: undefined,
+      version: undefined,
       handlers: null,
       queue: [],
       active: new Map(),
@@ -465,6 +476,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
           }
           cell.queue.push({
             context: captureContext(cell.context?.() ?? {}),
+            version: cell.version,
             method,
             params,
             ts: Date.now(),
@@ -507,6 +519,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
   });
 
   built.cell.context = options?.context;
+  built.cell.version = options?.version;
   useEffect(() => {
     const { cell } = built;
     cell.unmounted = false;

package/src/host/socket.ts

@@ -3,7 +3,6 @@ import { MAX_CONTEXT_BYTES } from "../wire/limits";
 import { encodeDocument } from "../document";
 import {
   DEFAULT_PROTOCOL,
-  WIRE_VERSION,
   DEFAULT_PROTOCOL_VERSION,
   GAP_FILL_VERSION,
   MIN_SERVED_WIRE_VERSION,
@@ -183,8 +182,9 @@ export type ParsedFrame = {
   res?: { protocol: string; seq: number }[];
 };
 
+// This host serves through the gap-fill wire: it names no attach to retire.
 const SERVED_WIRE: StatewireProtocol.Range = {
-  version: WIRE_VERSION,
+  version: GAP_FILL_VERSION,
   minVersion: MIN_SERVED_WIRE_VERSION,
 };
 
@@ -1147,6 +1147,9 @@ const admitCmd = (
     caller: callerOf(h, rec, conn),
     attach: conn.attach,
     context: captureContext(conn.contexts.get(statement.protocol) ?? {}),
+    version: conn.selection.protocols.find(
+      (p) => p.name === statement.protocol,
+    )!.version,
     onApplied: () => {
       if (adm.settled || adm.applied) return;
       adm.applied = true;

package/src/host.ts

@@ -45,19 +45,27 @@ export namespace StatewireHost {
     setOnDocuments: (listener: (() => void) | null) => void;
   };
 
+  /** What `this.context` and `this.version` read for a call made on the proxy (in-process dispatch). */
+  export type CommandsOptions = {
+    context?: () => Statewire.Context;
+    version?: string;
+  };
+
   /**
    * Per-invocation handle bound as `this` of a command handler: `caller` is
    * the submitting client, `attach` the admitting attach's document view
-   * (in-process dispatch has none — reading it throws), `applied()` states the
-   * broadcast state now contains the command's effects — the client drops its
-   * optimistic overlay — before the handler settles (idempotent, a no-op after
-   * settle). The command settles when the handler's returned promise does.
+   * (in-process dispatch has none — reading it throws), `version` the
+   * command protocol's version that attach negotiated (in-process dispatch
+   * reads `CommandsOptions.version`; without one, reading it throws),
+   * `applied()` states the broadcast state now contains the command's effects
+   * — the client drops its optimistic overlay — before the handler settles
+   * (idempotent, a no-op after settle). The command settles when the
+   * handler's returned promise does.
    */
-  export type CommandsOptions = { context?: () => Statewire.Context };
-
   export type Ctx = {
     readonly caller: Caller;
     readonly context: Statewire.Context;
+    readonly version: string;
     readonly attach: Attach;
     readonly signal: AbortSignal;
     readonly applied: () => void;

package/src/transports/sse.ts

@@ -4,6 +4,7 @@ import type { ResourceElement } from "@assistant-ui/tap";
 import { createSseParser } from "./sse-parser";
 import { timing } from "../client/timing";
 import {
+  replacing,
   settleFin,
   classify,
   handleEnvelope,
@@ -149,6 +150,7 @@ const attemptStream = async (
     if (!headers.has(name)) headers.set(name, value);
   }
   c.negotiation = parseNegotiation(headers);
+  replacing(c, headers);
   c.authStale = false;
   const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
   const body = lanes === null ? undefined : JSON.stringify(lanes);

package/src/wire/protocol.ts

@@ -18,9 +18,17 @@ export namespace StatewireProtocol {
   };
 }
 
-export const WIRE_VERSION = "2026-11-01";
+export const WIRE_VERSION = "2026-11-02";
 /** Attach carries a results cursor and gets its verdicts gap-filled; a re-sent seq at or below the watermark is a protocol error. */
 export const GAP_FILL_VERSION = "2026-11-01";
+/** Every attach of a connection names its attacher; a host retires the attacher's earlier attaches before the hello. */
+export const FENCE_VERSION = "2026-11-02";
+/** The wire a client offers by default: the gap-fill contract and newer. */
+export const CLIENT_WIRE: StatewireProtocol.Range = {
+  version: WIRE_VERSION,
+  minVersion: GAP_FILL_VERSION,
+};
+export const ATTACHER_HEADER = "Statewire-Attacher";
 /** The oldest wire contract a host serves by default (re-sent seqs re-emit their verdicts). */
 export const MIN_SERVED_WIRE_VERSION = "2026-09-30";
 export const DEFAULT_PROTOCOL_VERSION = "2026-09-30";
@@ -81,7 +89,7 @@ export const negotiationHeaders = (
   if (offers !== "*" && !offers.length)
     invalid("protocol list must not be empty");
   return {
-    [VERSION_HEADER]: suffix(options.wireVersion ?? { version: WIRE_VERSION }),
+    [VERSION_HEADER]: suffix(options.wireVersion ?? CLIENT_WIRE),
     [PROTOCOL_HEADER]:
       offers === "*"
         ? "*"
@@ -201,7 +209,7 @@ export const validateSelection = (
     return invalid("missing negotiation selection");
   const syn = value as Record<string, unknown>;
   const version = validateVersion(syn.version);
-  if (!inRange(version, options.wireVersion ?? { version: WIRE_VERSION }))
+  if (!inRange(version, options.wireVersion ?? CLIENT_WIRE))
     invalid("selected wire version is outside offer");
   if (!Array.isArray(syn.protocols))
     return invalid("syn.protocols must be an array");