statewire 0.24.1 → 0.24.3

package/src/client/session.ts

@@ -2,8 +2,8 @@ import { encodeContext } from "../wire/context";
 import { wrapStorageError } from "./storageError";
 import {
   DEFAULT_PROTOCOL,
+  CLIENT_WIRE,
   GAP_FILL_VERSION,
-  WIRE_VERSION,
   protocolOffers,
   inRange,
 } from "../wire/protocol";
@@ -163,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;
@@ -1326,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)),
         ]),
@@ -1350,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");
     }
@@ -1451,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 },
@@ -1472,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");
@@ -1494,7 +1516,7 @@ const handleHello = (
         );
         continue;
       }
-      demote(s, lane.name, lane.seq ?? 0, demoted, waiting);
+      demote(s, lane.name, carriedThrough(lane, attached), demoted, waiting);
       s.durableSeq[lane.name] = lane.seq ?? 0;
     }
     for (const entry of s.pending) {
@@ -1543,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
@@ -1728,6 +1766,29 @@ 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) ||
@@ -2444,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
@@ -2512,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.
@@ -2519,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) {
@@ -2800,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) =>
@@ -2933,6 +3006,7 @@ export const useStatewireSession = (
       durableSeq: {},
       ephemeralSeqs: {},
       resumeAt: 0,
+      reattach: false,
       idle: false,
       onSessionLost: undefined,
       onDeprecatedPath: undefined,

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/transports/testing.ts

@@ -7,6 +7,7 @@ import { openSSEStream, sseFrame } from "./fake-sse";
 import type { FakeStreamHandle } from "./fake-sse";
 import {
   DEFAULT_PROTOCOL_VERSION,
+  GAP_FILL_VERSION,
   WIRE_VERSION,
   parseNegotiation,
 } from "../wire/protocol";
@@ -93,7 +94,19 @@ export const createMockTransport = <TState>(
       if (!clients.has(id)) clients.set(id, {});
       const rec = clients.get(id)!;
       const ephemeral = ephemeralLanes();
-      const offers = parseNegotiation(headers).applicationProtocols;
+      const negotiation = parseNegotiation(headers);
+      const offers = negotiation.applicationProtocols;
+      // The newest wire this mock speaks that the client offered. It speaks
+      // GAP_FILL_VERSION and newer: it skips a re-sent seq instead of
+      // re-emitting its verdict, as older wires require.
+      const offered = negotiation.wireVersion;
+      const wireVersion =
+        offered.version < WIRE_VERSION ? offered.version : WIRE_VERSION;
+      if (
+        wireVersion < GAP_FILL_VERSION ||
+        (offered.minVersion !== undefined && wireVersion < offered.minVersion)
+      )
+        throw new Error("mock wire version was not offered");
       const applicationVersion =
         offers === "*"
           ? DEFAULT_PROTOCOL_VERSION
@@ -111,7 +124,7 @@ export const createMockTransport = <TState>(
             sseFrame({
               ops: [{ op: "mount", protocol, main: true, value: state }],
               syn: {
-                version: WIRE_VERSION,
+                version: wireVersion,
                 protocols: [
                   {
                     name: protocol,

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");