statewire 0.10.0 → 0.12.0

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;

package/src/statewire.ts

@@ -11,6 +11,7 @@ import {
 import type { ResourceElement } from "@assistant-ui/tap";
 import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
+import type { TERMINAL } from "./client/connection";
 import { SessionStorageContext } from "./client/sessionStore";
 
 const useSessionTransport = ({
@@ -218,7 +219,7 @@ export namespace StatewireClient {
    * fate: "aborted" = never sent, "rejected" = the server refused it
    * (`code` "unknown-command" | "invalid-params" for the static rejects,
    * code-less for handler rejects), "lost" = sent but no verdict will ever
-   * arrive — the record is gone (`record: "fresh"`) or the channel died: it
+   * arrive — the record is gone (a proven seq gap) or the channel died: it
    * may or may not have run, "failed" = the handler ran and threw,
    * "crashed" = the handler died involuntarily, "expired" = settled —
    * result, rejected, failed, or crashed — but the verdict outlived the
@@ -239,14 +240,25 @@ export namespace StatewireClient {
     | { fate: "expired"; cause: "server" }
     | {
         fate: "aborted";
-        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+        cause: "unmount" | "stream-gone" | "session-lost";
         predecessorLost?: true;
       }
     | {
         fate: "lost";
-        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+        cause: "unmount" | "stream-gone" | "session-lost";
       };
 
+  /** Held commands a proven record gap settled `{fate: "lost", cause: "session-lost"}`; return "requeue" to re-enqueue them on the reset clocks. */
+  export type OnSessionLost = (
+    pending: ReadonlyArray<{
+      method: string;
+      params: readonly unknown[];
+      ts: number;
+      seq: number;
+      clientId?: string;
+    }>,
+  ) => "requeue" | "drop";
+
   /** A command as persisted while un-durable: its lane seq plus the wire statement. */
   export type SessionCommand = {
     seq: number;
@@ -261,12 +273,28 @@ export namespace StatewireClient {
     nextSeq: number;
     ctxNextSeq: number;
     commands: readonly SessionCommand[];
+    /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
+    verdicts?: readonly SessionVerdict[];
+  };
+
+  /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */
+  export type SessionVerdict = {
+    seq: number;
+    type: (typeof TERMINAL)[number];
+    code?: string;
+    message?: string;
+    payload?: unknown;
+    meta?: unknown;
   };
 
   /** Session storage seam; `save` must persist synchronously in the caller's flow. */
   export type SessionStorage = {
     load: () => SessionRecord | null;
     save: (record: SessionRecord) => void;
+    /** Serializes record mutations across sharers; presence marks the storage shared. */
+    lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;
+    /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */
+    subscribe?: (listener: () => void) => () => void;
   };
 
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */
@@ -279,6 +307,7 @@ export namespace StatewireClient {
     url: string;
     headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
+    onSessionLost?: OnSessionLost;
     onChange?: (connection: Connection) => void;
     /** The broadcast idle flag's rising edge: the instance went quiet. */
     onDone?: () => void;
@@ -293,6 +322,7 @@ export namespace StatewireClient {
       | Record<string, string>
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
+    onSessionLost?: OnSessionLost;
     onChange?: (connection: Connection) => void;
     /** The broadcast idle flag's rising edge: the instance went quiet. */
     onDone?: () => void;

package/src/transports/fake-sse.ts

@@ -30,7 +30,11 @@ export const openSSEStream = (
           if (!open) return;
           open = false;
           streams.delete(handle);
-          controller.close();
+          try {
+            controller.close();
+          } catch {
+            // the reader already canceled
+          }
         },
       };
       streams.add(handle);
@@ -40,11 +44,7 @@ export const openSSEStream = (
       streams.delete(handle);
     },
   });
-  signal?.addEventListener("abort", () => {
-    for (const stream of [...streams]) {
-      if (stream.clientId === clientId) stream.close();
-    }
-  });
+  signal?.addEventListener("abort", () => handle.close());
   return new Response(body, {
     status: 200,
     headers: { "content-type": "text/event-stream", ...headers },

package/src/transports/remote.ts

@@ -21,6 +21,7 @@ export const useStatewireRemote = <
 ): Statewire<any, any> => {
   const s = useStatewireSession({
     sessionStore: options.sessionStore,
+    onSessionLost: options.onSessionLost,
     onDone: options.onDone,
   });
   const conn = useLink(options, s.ctx);

package/src/transports/testing.ts

@@ -77,8 +77,7 @@ export const createMockTransport = <TState>(
     const id = headers.get("Statewire-Client-Id") ?? "";
     if (url.endsWith("/stream")) {
       clientId = id;
-      const known = clients.has(id);
-      if (!known) clients.set(id, { seq: 0, ctxSeq: 0 });
+      if (!clients.has(id)) clients.set(id, { seq: 0, ctxSeq: 0 });
       const rec = clients.get(id)!;
       const frame = JSON.parse(String(init?.body)) as StatewireFrame;
       admit(id, frame);
@@ -89,11 +88,7 @@ export const createMockTransport = <TState>(
           handle.send(
             sseFrame({
               ops: [{ op: "replace", path: [], value: state }],
-              syn: {
-                seq: rec.seq,
-                ctxSeq: rec.ctxSeq,
-                record: known ? "resumed" : "fresh",
-              },
+              syn: { seq: rec.seq, ctxSeq: rec.ctxSeq },
             }),
           );
         },

package/src/wire/meta.ts

@@ -17,15 +17,23 @@ const isPath = (path: unknown): path is (string | number)[] =>
       (typeof seg === "number" && Number.isInteger(seg)),
   );
 
-/** Revive meta-typed locations inside a wire value (in place). Unknown types
- * are skipped; a path that does not resolve to a valid target faults. */
-export const reviveValue = (value: unknown, meta: unknown): unknown => {
+/** Revive meta-typed locations inside a wire value (in place). Clients skip
+ * unknown types; hosts pass `rejectUnknown` to fault on them instead. */
+export const reviveValue = (
+  value: unknown,
+  meta: unknown,
+  { rejectUnknown = false } = {},
+): unknown => {
   if (!Array.isArray(meta)) return fault("meta must be an array");
   for (const entry of meta as { path?: unknown; type?: unknown }[]) {
     const path =
       typeof entry === "object" && entry !== null ? entry.path : null;
     if (!isPath(path)) return fault("meta entry must carry a path array");
-    if (entry.type !== "date") continue;
+    if (entry.type !== "date") {
+      if (rejectUnknown)
+        return fault(`unknown meta type: ${String(entry.type)}`);
+      continue;
+    }
     const walked = walkStatePath(value, path, "resolve");
     if (walked === undefined) {
       return fault(`meta path ${path.join(".")} does not resolve`);