statewire 0.11.0 → 0.12.2

package/src/client/session.ts

@@ -1,6 +1,7 @@
 import { useContext, useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
+import { TERMINAL } from "./connection";
 import type { StatewireCmd, StatewireSyn } from "./connection";
 import {
   encodeParams,
@@ -70,6 +71,7 @@ type AttachState = "detached" | "attached" | "finished";
 
 export type StatewireSessionOptions = {
   sessionStore?: StatewireClient.SessionStorage | undefined;
+  onSessionLost?: StatewireClient.OnSessionLost | undefined;
   onDone?: (() => void) | undefined;
 };
 
@@ -92,6 +94,7 @@ type Session = {
   durableSeq: number;
   resumeAt: number;
   idle: boolean;
+  onSessionLost: StatewireClient.OnSessionLost | undefined;
   onDone: (() => void) | undefined;
   ctxOps: unknown[] | undefined;
   ctxPending: CtxPending[];
@@ -252,14 +255,9 @@ const settleEntry = (
   }
 };
 
-const settleAll = (s: Session, detach: "unmount" | "gone" | "superseded") => {
-  const cause = (
-    {
-      unmount: "unmount",
-      gone: "stream-gone",
-      superseded: "superseded",
-    } as const
-  )[detach];
+const settleAll = (s: Session, detach: "unmount" | "gone") => {
+  const cause =
+    detach === "unmount" ? ("unmount" as const) : ("stream-gone" as const);
   const batch = s.pending;
   const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
     if (!entry.attempted) {
@@ -286,26 +284,30 @@ const restateContext = (s: Session) => {
   s.ctxPending.push({ seq, ops: s.ctxOps, posted: false });
 };
 
+const settleLost = (s: Session, entries: Pending[]) => {
+  for (const entry of entries) {
+    s.lifecycle?.onCovered?.(entry.inv);
+    settleEntry(s, entry, {
+      ok: false,
+      failure: { fate: "lost", cause: "session-lost" },
+    });
+  }
+};
+
 // 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);
-    }
-  }
+// on the adopted lane clocks.
+const rebaseRecord = (s: Session, adopt: () => void) => {
+  const held = [...s.pending];
+  const survivors = held.filter((p) => !p.attempted && !p.applied);
+  settleLost(
+    s,
+    held.filter((p) => p.attempted || p.applied),
+  );
   s.pending = [];
   s.durableSeq = 0;
-  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
+  adopt();
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
     enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
@@ -316,33 +318,17 @@ const resetRecord = (s: Session, clientId: string) => {
   void pump(s);
 };
 
+const resetRecord = (s: Session, clientId: string) =>
+  rebaseRecord(s, () =>
+    setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] }),
+  );
+
 // Another sharer replaced the record's identity: their reset settles our
 // attempted history and our survivors re-stamp on the stored clocks.
-const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) => {
-  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;
-  s.record = stored;
-  for (const old of survivors) {
-    s.lifecycle?.onCovered?.(old.inv);
-    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
-  }
-  restateContext(s);
-  publish(s);
-  wake(s);
-  void pump(s);
-};
+const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) =>
+  rebaseRecord(s, () => {
+    s.record = stored;
+  });
 
 // The record died with the attach: mint a fresh id for the next one.
 const ephemeralDetach = (s: Session) => {
@@ -365,42 +351,31 @@ const outcomeOf = (
   cmd: StatewireCmd,
 ):
   | { ok: true; payload: unknown }
-  | { ok: false; failure: StatewireClient.SendFailure } =>
-  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,
-                },
-              }
-            : protocolError(`unknown cmd type: ${String(cmd.type)}`);
-
-const TERMINAL_CMD_TYPES = new Set([
-  "result",
-  "rejected",
-  "failed",
-  "crashed",
-  "expired",
-]);
+  | { ok: false; failure: StatewireClient.SendFailure } => {
+  switch (cmd.type) {
+    case "result":
+      return { ok: true, payload: reviveResponse(cmd).payload };
+    case "rejected":
+      return { ok: false, failure: rejectedFailure(reviveResponse(cmd)) };
+    case "failed":
+      return {
+        ok: false,
+        failure: {
+          fate: "failed",
+          cause: "server",
+          ...(cmd.message !== undefined && { message: cmd.message }),
+        },
+      };
+    case "crashed":
+      return { ok: false, failure: { fate: "crashed", cause: "server" } };
+    case "expired":
+      return { ok: false, failure: { fate: "expired", cause: "server" } };
+    default:
+      return protocolError(`unknown cmd type: ${String(cmd.type)}`);
+  }
+};
+
+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;
@@ -473,24 +448,10 @@ const publishIngested = (s: Session) => {
   wake(s);
 };
 
-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);
-      enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
-    }
-  }
+// A hello's cmd watermark may understate a durable record (cold host, tray
+// unloaded): held seqs resend as-is and the frame's answer arbitrates —
+// absorption where the record survived, a gap refusal where it did not.
+const snapCtxClock = (s: Session, ctxWm: number) => {
   const ctxAligned =
     s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) &&
     s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1;
@@ -500,39 +461,69 @@ const snapClocks = (s: Session, seqWm: number, ctxWm: number) => {
   }
 };
 
+// The refusal's watermarks are exact: every held statement above them 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 lane clocks restart at the watermarks.
+const sessionLostInner = (s: Session, seqWm: number, ctxWm: number) => {
+  const held = [...s.pending];
+  settleLost(s, held);
+  s.pending = [];
+  s.durableSeq = seqWm;
+  setRecord(s, {
+    clientId: s.record.clientId,
+    nextSeq: seqWm + 1,
+    ctxNextSeq: ctxWm + 1,
+    commands: [],
+  });
+  restateContext(s);
+  if (
+    held.length > 0 &&
+    s.onSessionLost?.(held.map((p) => p.inv)) === "requeue"
+  ) {
+    for (const old of held) {
+      enqueueInner(
+        s,
+        old.command,
+        old.inv.params,
+        () => {},
+        () => {},
+      );
+    }
+  }
+  publish(s);
+  wake(s);
+};
+
 const handleHello = (
   s: Session,
   { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
 ) => {
-  const record = syn.record ?? "fresh";
-  if (!RECORDS.includes(record)) {
-    protocolError(`unknown record: ${String(record)}`);
+  if (syn.record !== undefined && syn.record !== "ephemeral") {
+    protocolError(`unknown record: ${String(syn.record)}`);
   }
   ingestOps(s, ops);
   s.attach = "attached";
   s.attachEpoch += 1;
   s.frameFailures = 0;
   s.resumeAt = 0;
-  s.ephemeral = record === "ephemeral";
+  s.ephemeral = syn.record === "ephemeral";
   if (s.ephemeral) s.deactivated = true;
   const [attachCmd, attachCtx] = s.attachLaneSeqs;
   s.attachLaneSeqs = [new Set(), new Set()];
   const reconcile = () => {
-    if (record === "resumed") {
-      if (s.shared) adoptStored(s);
-      // 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);
-      syncBacklogInner(s);
-    } else {
-      resetRecord(s, s.record.clientId);
+    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);
     }
+    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);
+    snapCtxClock(s, ctxWatermark);
+    syncBacklogInner(s);
     s.sessionKnown = true;
   };
   if (!s.shared || s.deactivated) {
@@ -557,8 +548,9 @@ const handleOps = (
   publishIngested(s);
 };
 
-// A {syn} refusal never settles: reconcile the resend queues against the
-// stated watermarks; retry present means wait, absent means resend now.
+// 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.
 const handleRefusal = (s: Session, syn: StatewireSyn) => {
   const { seq, ctxSeq } = syn;
   if (typeof seq === "number") {
@@ -571,19 +563,30 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
   }
   if (typeof syn.retry === "number") {
     s.resumeAt = Date.now() + syn.retry;
+    wake(s);
+    void pump(s);
+    return;
   }
   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();
+  const cmdGap =
+    typeof seq === "number" &&
+    firstCmd !== undefined &&
+    firstCmd.seq > Math.max(seq, s.durableSeq) + 1;
+  const ctxGap =
+    typeof ctxSeq === "number" &&
+    firstCtx !== undefined &&
+    firstCtx.seq > ctxSeq + 1;
+  if (cmdGap || ctxGap) {
+    void transact(s, () => {
+      if (cmdGap) sessionLostInner(s, seq!, ctxSeq ?? 0);
+      else snapCtxClock(s, ctxSeq!);
+    }).then(() => {
+      wake(s);
+      void pump(s);
+    });
+    return;
+  }
   wake(s);
   void pump(s);
 };
@@ -597,11 +600,7 @@ const handleDetach = (s: Session) => {
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
   if (reason === "evicted" || reason === "error") return;
   s.attach = "finished";
-  // Superseded over shared storage: the superseder resends our backlog and
-  // parks the verdicts; our promises settle from the observed record.
-  if (!(s.shared && reason === "superseded")) {
-    settleAll(s, reason === "superseded" ? "superseded" : "gone");
-  }
+  settleAll(s, "gone");
   publish(s);
   wake(s);
 };
@@ -819,8 +818,8 @@ const enqueue = (
   ).then(() => void pump(s));
 };
 
-// A stored command cannot be told from one that reached the server: attempted
-// keeps a fresh record settling it lost instead of replaying it blind.
+// 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));
@@ -965,6 +964,7 @@ export const useStatewireSession = (
       durableSeq: 0,
       resumeAt: 0,
       idle: false,
+      onSessionLost: undefined,
       onDone: undefined,
       ctxOps: undefined,
       ctxPending: [],
@@ -1005,7 +1005,13 @@ export const useStatewireSession = (
     });
     return session;
   });
+  if ((store.lock !== undefined) !== (s.shared !== false)) {
+    throw new Error(
+      "statewire: session storage changed sharedness across renders — lock/subscribe must be present from the first render or never",
+    );
+  }
   s.store = store;
+  s.onSessionLost = options.onSessionLost;
   s.onDone = options.onDone;
   useEffect(() => {
     start(s);

package/src/host/draft.ts

@@ -30,6 +30,16 @@ const invalid = (path: StatewirePath, message: string) =>
 
 type Container = Record<string | number, unknown>;
 
+// Text-insert offsets are Unicode code points on the wire, not UTF-16 units.
+const codePointLength = (text: string): number => {
+  let count = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text.codePointAt(index)! > 0xffff) index += 1;
+    count += 1;
+  }
+  return count;
+};
+
 type Node = {
   parent: Node | null;
   key: string | number;
@@ -96,7 +106,11 @@ export const createStateDraft = <T>(host: DraftHost): StateDraft<T> => {
     if (suffix === "") return;
     prepareForWrite(node)[key] = existing + suffix;
     host.record(
-      { op: "add", path: [...node.path, key, existing.length], value: suffix },
+      {
+        op: "add",
+        path: [...node.path, key, codePointLength(existing)],
+        value: suffix,
+      },
       changedPathFor(node, key),
     );
   };

package/src/host/http.ts

@@ -166,7 +166,7 @@ const getStream = async (
   const attachment = attachSse(h, client.clientId);
   const lease = attachment.registration === null ? null : mintLease();
   if (attachment.registration !== null)
-    attachment.registration.rec.lease = lease;
+    attachment.registration.conn.lease = lease;
   return streamResponse(attachment, lease);
 };
 
@@ -202,7 +202,7 @@ const postStream = async (
   const attachment = attachSse(h, client.clientId);
   if (attachment.registration === null) return streamResponse(attachment, null);
   const lease = mintLease();
-  attachment.registration.rec.lease = lease;
+  attachment.registration.conn.lease = lease;
   admitAttachFrame(h, attachment.registration, frame);
   return streamResponse(attachment, lease);
 };
@@ -254,13 +254,14 @@ export const frames = async (
   if ("response" in client) return client.response;
   const rec = h.clients.get(client.clientId);
   const lease = request.headers.get(LEASE_HEADER);
-  if (
-    h.disposed ||
-    h.finished !== null ||
-    rec === undefined ||
-    lease === null ||
-    lease !== rec.lease
-  ) {
+  // A lease lives and dies with its attach: any live attach of the id accepts.
+  const live =
+    lease !== null &&
+    [...h.conns].some(
+      (conn) =>
+        conn.open && conn.clientId === client.clientId && conn.lease === lease,
+    );
+  if (h.disposed || h.finished !== null || rec === undefined || !live) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
   let frame: ParsedFrame;

package/src/host/socket.ts

@@ -38,7 +38,6 @@ export type ClientRec = {
   id: string;
   lastSeq: number;
   ctxSeq: number;
-  lease: string | null;
   touched: number;
   context: Record<string, unknown> | null;
   results: Map<number, { ts: number; cmd: StatewireCmd }>;
@@ -51,6 +50,7 @@ export type Conn = {
   open: boolean;
   sawFrame: boolean;
   lastSentAt: number;
+  lease: string | null;
 };
 
 // ─── frame parsing ──────────────────────────────────────
@@ -115,7 +115,7 @@ const contextValue = (ops: unknown): Record<string, unknown> => {
   }
   const value =
     op["meta"] !== undefined
-      ? reviveValue(op["value"], op["meta"])
+      ? reviveValue(op["value"], op["meta"], { rejectUnknown: true })
       : op["value"];
   if (!isPlainObject(value)) {
     throw new Error("context value must be an object");
@@ -128,13 +128,13 @@ export const parseFrameValue = (
   first: boolean,
 ): ParsedFrame => {
   if (!isPlainObject(frame)) return violation("malformed frame");
-  if (
-    frame["headers"] === undefined &&
-    frame["ctx"] === undefined &&
-    frame["cmd"] === undefined
-  ) {
-    return violation("malformed frame");
-  }
+  const keys = Object.keys(frame);
+  if (keys.length === 0) return violation("malformed frame");
+  const unknown = keys
+    .filter((key) => key !== "headers" && key !== "ctx" && key !== "cmd")
+    .sort();
+  if (unknown.length > 0)
+    return violation(`unknown frame key: '${unknown[0]}'`);
   let headers: Record<string, string> | null = null;
   if (frame["headers"] !== undefined) {
     if (!first) return violation("mid-session headers");
@@ -267,7 +267,7 @@ export type SocketHostState = {
   connect: (
     clientId: string,
     socket: StatewireHostInternal.Socket,
-  ) => StatewireHostInternal.SocketConnection;
+  ) => StatewireHostInternal.SocketConnection | null;
   finish: (fin: StatewireHost.Fin) => void;
   stream: (request: Request) => Promise<Response>;
   frames: (request: Request) => Promise<Response>;
@@ -563,7 +563,9 @@ const admitCmd = (
   let params = statement.params;
   if (statement.meta !== undefined) {
     try {
-      params = reviveValue(params, statement.meta) as unknown[];
+      params = reviveValue(params, statement.meta, {
+        rejectUnknown: true,
+      }) as unknown[];
     } catch (error) {
       rejectStatement(
         h,
@@ -717,7 +719,6 @@ export const register = (
           id: clientId,
           lastSeq: 0,
           ctxSeq: 0,
-          lease: null,
           touched: Date.now(),
           context: null,
           results: new Map(),
@@ -727,18 +728,13 @@ export const register = (
         return created;
       })();
   rec.touched = Date.now();
-  rec.lease = null;
-  for (const other of [...h.conns]) {
-    if (other.clientId !== clientId) continue;
-    sendTo(h, other, JSON.stringify({ fin: { reason: "superseded" } }));
-    closeConn(h, other);
-  }
   const conn: Conn = {
     clientId,
     socket,
     open: true,
     sawFrame: false,
     lastSentAt: 0,
+    lease: null,
   };
   h.conns.add(conn);
   gcClients(h);
@@ -756,7 +752,6 @@ export const register = (
     syn: {
       seq: admittedThrough(rec),
       ctxSeq: rec.ctxSeq,
-      record: known ? "resumed" : "fresh",
       ...(h.idleWire && { idle: true }),
     },
   };
@@ -773,15 +768,9 @@ const connect = (
   h: SocketHostState,
   clientId: string,
   socket: StatewireHostInternal.Socket,
-): StatewireHostInternal.SocketConnection => {
+): StatewireHostInternal.SocketConnection | null => {
   const registration = register(h, clientId, socket);
-  return (
-    registration?.connection ?? {
-      clientId,
-      message: () => {},
-      close: () => {},
-    }
-  );
+  return registration?.connection ?? null;
 };
 
 const finish = (h: SocketHostState, fin: StatewireHost.Fin) => {
@@ -862,7 +851,8 @@ const useSocketHost = (
  * feed it sockets (anything with `send`/`close`) and raw text frames, and it
  * speaks the Statewire packet protocol — snapshot-first hello with `syn`,
  * statement-lane client frames under one admission law, `{cmd}` answer
- * arrays, per-client-id supersede, idle edges, and `fin` on finish.
+ * arrays fanned out to every attach of a client id, idle edges, and `fin` on
+ * finish.
  */
 export const StatewireSocketHost = (
   transport: ResourceElement<Statewire>,

package/src/host-internal.ts

@@ -15,7 +15,8 @@ export namespace StatewireHostInternal {
   };
 
   export type SocketHost = {
-    connect: (clientId: string, socket: Socket) => SocketConnection;
+    /** Null means refused: the socket was told (fin and/or close) and is dead. */
+    connect: (clientId: string, socket: Socket) => SocketConnection | null;
     stream: (request: Request) => Promise<Response>;
     frames: (request: Request) => Promise<Response>;
     finish: (fin: StatewireHost.Fin) => void;

package/src/host.ts

@@ -58,7 +58,6 @@ export namespace StatewireHost {
       | "error"
       | "unauthorized"
       | "gone"
-      | "superseded"
       | "idle"
       | (string & {});
     message?: string;