statewire 0.11.0 → 0.12.0

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;
@@ -268,7 +280,7 @@ export namespace StatewireClient {
   /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */
   export type SessionVerdict = {
     seq: number;
-    type: "result" | "rejected" | "failed" | "crashed" | "expired";
+    type: (typeof TERMINAL)[number];
     code?: string;
     message?: string;
     payload?: unknown;
@@ -295,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;
@@ -309,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`);