statewire 0.18.2 → 0.19.0

package/src/host/synced.ts

@@ -0,0 +1,60 @@
+import { StatewireReject } from "./engine";
+import { applyDocumentOps } from "../wire/documents";
+import type { StatewireHost } from "../host";
+
+const PATCH_OPS = new Set(["add", "replace", "remove"]);
+
+const mount = (
+  attach: StatewireHost.Attach,
+  protocol: string,
+  value: unknown,
+) => {
+  try {
+    attach.mount(protocol, value, undefined, true);
+  } catch (error) {
+    throw new StatewireReject((error as Error).message, {
+      code: "oversized-document",
+    });
+  }
+};
+
+/** `set`/`patch` handlers for an ephemeral subprotocol's main document; spread into `useStatewireCommands`. */
+export const syncedDocument = (protocol: string) => ({
+  [`${protocol}/set`]: function (this: StatewireHost.Ctx, value: unknown) {
+    mount(this.attach, protocol, value);
+  },
+  [`${protocol}/patch`]: function (this: StatewireHost.Ctx, ops: unknown) {
+    const value = this.attach.document(protocol);
+    if (value === undefined)
+      throw new StatewireReject("no document is set", { code: "no-document" });
+    if (
+      !Array.isArray(ops) ||
+      !ops.every(
+        (op) =>
+          typeof op === "object" &&
+          op !== null &&
+          !Array.isArray(op) &&
+          PATCH_OPS.has((op as { op?: unknown }).op as string) &&
+          !("doc" in op),
+      )
+    )
+      throw new StatewireReject("invalid patch", { code: "invalid-patch" });
+    let next: unknown;
+    try {
+      next = applyDocumentOps(
+        {
+          mode: "mounted",
+          documents: new Map([[0, { key: null, protocol, main: true, value }]]),
+        },
+        ops,
+        undefined,
+        true,
+      ).documents.get(0)!.value;
+    } catch (error) {
+      throw new StatewireReject((error as Error).message, {
+        code: "invalid-patch",
+      });
+    }
+    mount(this.attach, protocol, next);
+  },
+});

package/src/host-internal.ts

@@ -1,6 +1,5 @@
 import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireHost } from "./host";
-import type { StatewireCmd } from "./client/connection";
 
 export { StatewireSocketHost } from "./host/socket";
 export { clientIdFromUrl, textFrameOrClose } from "./host/adapter";
@@ -45,11 +44,30 @@ export namespace StatewireHostInternal {
     dispose: () => void;
   };
 
+  export type Cmd = {
+    protocol: string;
+    seq: number;
+    type?: "applied" | "result" | "rejected" | "failed" | "crashed" | "expired";
+    code?: string;
+    message?: string;
+    payload?: unknown;
+    meta?: unknown;
+    /** Cumulative per lane: resending through this seq will never be needed. */
+    dur?: boolean;
+  };
+
   export type ClientRecord = {
     id: string;
-    lastSeq: number;
     touched: number;
-    results: readonly { seq: number; ts: number; cmd: StatewireCmd }[];
+    lanes: Readonly<
+      Record<
+        string,
+        {
+          lastSeq: number;
+          results: readonly { seq: number; ts: number; cmd: Cmd }[];
+        }
+      >
+    >;
     principal: unknown;
   };
 

package/src/host.ts

@@ -8,6 +8,7 @@ export {
   useStatewireState,
   useStatewireCommands,
 } from "./host/host";
+export { syncedDocument } from "./host/synced";
 
 export namespace StatewireHost {
   export type Work = {
@@ -23,20 +24,38 @@ export namespace StatewireHost {
     snapshot: () => TState;
   };
 
+  export type Document = {
+    protocol: string;
+    key: readonly string[] | null;
+    main: boolean;
+    value: unknown;
+  };
+
   export type StateHost = Statewire.StateSource & {
     /** Synchronous, per locally-recorded op; the host owns batching. */
     setOnOp: (listener: ((op: Statewire.Op) => void) | null) => void;
+    /** Mount or replace the shared document `(protocol, key)`; keyed documents reach an attach only once it `include`s them. */
+    mount: (
+      protocol: string,
+      value: unknown,
+      options?: { key?: readonly string[]; main?: boolean },
+    ) => void;
+    unmount: (protocol: string, key?: readonly string[]) => void;
+    documents: () => ReadonlyMap<string, Document>;
+    setOnDocuments: (listener: (() => void) | null) => void;
   };
 
   /**
    * Per-invocation handle bound as `this` of a command handler: `caller` is
-   * the submitting client, `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.
+   * 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.
    */
   export type Ctx = {
     readonly caller: Caller;
+    readonly attach: Attach;
     readonly signal: AbortSignal;
     readonly applied: () => void;
   };
@@ -46,17 +65,30 @@ export namespace StatewireHost {
    * across a long run: `clientId` is the client's `Statewire-Client-Id`
    * (in-process dispatch has none — reading it throws), `auth` is the value
    * `authorize` returned for the attach that admitted the command (undefined
-   * for a void `authorize` and for in-process dispatch), `context` reads the
-   * admitting attach's context live (null until that attach sends one),
-   * `isConnected` reports whether the client has an active stream attachment.
+   * for a void `authorize` and for in-process dispatch), `isConnected`
+   * reports whether the client has an active stream attachment.
    */
   export type Caller = {
     readonly clientId: string;
     readonly auth: unknown;
-    readonly context: Record<string, unknown> | null;
     readonly isConnected: boolean;
   };
 
+  /** The admitting attach's view: its ephemeral documents plus the shared documents included for it. */
+  export type Attach = {
+    document: (protocol: string, key?: readonly string[]) => unknown;
+    /** `protocol` must be ephemeral; the encoded value is bounded by `MAX_EPHEMERAL_DOCUMENT_BYTES`. */
+    mount: (
+      protocol: string,
+      value: unknown,
+      key?: readonly string[],
+      main?: boolean,
+    ) => void;
+    unmount: (protocol: string, key?: readonly string[]) => void;
+    include: (protocol: string, key: readonly string[]) => void;
+    exclude: (protocol: string, key: readonly string[]) => void;
+  };
+
   export type HandledCommands<THandlers extends Statewire.Commands> = {
     [K in keyof THandlers]: (
       ...args: Parameters<THandlers[K]>

package/src/index.ts

@@ -7,4 +7,5 @@ export { StatewireWebsocket } from "./transports/ws";
 export { StatewireSendError } from "./types";
 
 export type { StatewireProtocol } from "./wire/protocol";
+export { DEFAULT_PROTOCOL } from "./wire/protocol";
 export type { StatewireDocuments } from "./wire/documents";

package/src/statewire.ts

@@ -127,25 +127,10 @@ export const useStatewire = <
           );
         return value.invoke(protocol, method, params);
       },
-      updateContext: (ops: readonly unknown[]) => {
-        if (!value.updateContext)
-          throw new Error(
-            "statewire: transport does not support context documents",
-          );
-        value.updateContext(ops);
-      },
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
       isBusy,
-      setContext: (contextValue: Record<string, unknown>) => {
-        if (!value.setContext) {
-          throw new Error(
-            "statewire: this transport has no client context channel",
-          );
-        }
-        value.setContext(contextValue);
-      },
       failed,
       retryFailed: (entry: StatewireClient.FailedCommand) =>
         failures().retry(entry),
@@ -200,18 +185,10 @@ export class StatewireClient<
   ): Promise<unknown> {
     return this.root.getValue().invoke(protocol, method, params);
   }
-  updateContext(ops: readonly unknown[]): void {
-    this.root.getValue().updateContext(ops);
-  }
-
   get isBusy(): boolean {
     return this.root.getValue().isBusy;
   }
 
-  setContext(value: Record<string, unknown>): void {
-    this.root.getValue().setContext(value);
-  }
-
   get failed(): readonly StatewireClient.FailedCommand[] {
     return this.root.getValue().failed;
   }
@@ -286,15 +263,12 @@ export namespace StatewireClient {
       method: string,
       params: readonly unknown[],
     ) => Promise<unknown>;
-    updateContext: (ops: readonly unknown[]) => void;
     /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */
     getState: () => TState;
     connection: Connection;
     commands: Statewire.CommandsProxy<TCommands>;
     /** Negation of the server's broadcast idle level (a transport without idle is always busy). */
     isBusy: boolean;
-    /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
-    setContext: (value: Record<string, unknown>) => void;
     /** Non-accepted sends retained in the session record; reload with it. */
     failed: readonly FailedCommand[];
     /** Re-enqueues the entry's command on fresh clocks and removes the entry. */
@@ -422,7 +396,6 @@ export namespace StatewireClient {
   /** A command as persisted while un-durable: its lane seq plus the wire statement. */
   export type SessionCommand = {
     seq: number;
-    protocol: string;
     produced?: {
       wire: StatewireProtocol.Range;
       protocols: readonly StatewireProtocol.Offer[] | "*";
@@ -432,9 +405,8 @@ export namespace StatewireClient {
     meta?: unknown;
   };
 
-  /** The persisted session: the lane identity, the cmd clock, and the commands the server has not marked durable. */
-  export type SessionRecord = {
-    clientId: string;
+  /** A durable lane: its cmd clock and the commands the server has not marked durable. */
+  export type SessionLane = {
     nextSeq: number;
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
@@ -443,6 +415,12 @@ export namespace StatewireClient {
     failed?: readonly FailedCommand[];
   };
 
+  /** The persisted session: the client identity plus one lane per durable protocol. */
+  export type SessionRecord = {
+    clientId: string;
+    lanes: Readonly<Record<string, SessionLane>>;
+  };
+
   /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */
   export type SessionVerdict = {
     seq: number;

package/src/storage.ts

@@ -3,7 +3,11 @@ import { wrapStorageError } from "./client/storageError";
 import { resource } from "@assistant-ui/tap";
 import type { StatewireClient } from "./statewire";
 import type { StatewireProtocol } from "./wire/protocol";
-import { negotiationHeaders, protocolToken } from "./wire/protocol";
+import {
+  DEFAULT_PROTOCOL,
+  negotiationHeaders,
+  protocolToken,
+} from "./wire/protocol";
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -85,12 +89,8 @@ const isFailedCommand = (
   Number.isFinite(value["ts"]) &&
   isPositiveSafeInteger(value["seq"]);
 
-const isSessionRecord = (
-  value: unknown,
-): value is StatewireClient.SessionRecord =>
+const isSessionLane = (value: unknown): value is StatewireClient.SessionLane =>
   isRecord(value) &&
-  typeof value["clientId"] === "string" &&
-  value["clientId"].length > 0 &&
   isPositiveSafeInteger(value["nextSeq"]) &&
   Array.isArray(value["commands"]) &&
   value["commands"].every(isSessionCommand) &&
@@ -100,6 +100,18 @@ const isSessionRecord = (
   (value["failed"] === undefined ||
     (Array.isArray(value["failed"]) && value["failed"].every(isFailedCommand)));
 
+const isClientId = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+const isSessionRecord = (
+  value: unknown,
+): value is StatewireClient.SessionRecord =>
+  isRecord(value) &&
+  isClientId(value["clientId"]) &&
+  isRecord(value["lanes"]) &&
+  Object.keys(value["lanes"]).every(isProtocol) &&
+  Object.values(value["lanes"]).every(isSessionLane);
+
 const isProtocol = (value: unknown) =>
   value === undefined ||
   (typeof value === "string" && value !== "*" && protocolToken.test(value));
@@ -120,58 +132,79 @@ const isProducer = (value: unknown) => {
   }
 };
 
-const decode = (
-  raw: string | null,
-  legacyProtocol: KeyValueSessionStorage.Options["legacyProtocol"],
-): StatewireClient.SessionRecord | null => {
-  if (raw === null) return null;
-  const parsed: unknown = JSON.parse(raw);
-  if (!isSessionRecord(parsed))
-    throw new Error("statewire: invalid stored session record");
+const invalid = (): never => {
+  throw new Error("statewire: invalid stored session record");
+};
+
+// Formats 1 and 2 held one lane: it lifts under the primary protocol, failed
+// entries under their own.
+const liftLegacy = (
+  value: Record<string, unknown>,
+  protocol: string,
+): StatewireClient.SessionRecord => {
+  const { clientId, nextSeq, commands, verdicts, failed } = value;
+  const lane = {
+    nextSeq,
+    commands: [],
+    ...(verdicts !== undefined && { verdicts }),
+  };
+  if (!isClientId(clientId) || !isSessionLane(lane) || !Array.isArray(commands))
+    return invalid();
+  const legacyCommands = commands as (StatewireClient.SessionCommand & {
+    protocol?: string;
+  })[];
+  if (!legacyCommands.every(isSessionCommand)) return invalid();
+  if (
+    failed !== undefined &&
+    (!Array.isArray(failed) || !failed.every(isFailedCommand))
+  )
+    return invalid();
+  const lanes: Record<string, StatewireClient.SessionLane> = {
+    [protocol]: {
+      ...lane,
+      commands: legacyCommands
+        .filter((command) => (command.protocol ?? protocol) === protocol)
+        .map(({ protocol: _protocol, ...command }) => command),
+    },
+  };
+  for (const entry of failed ?? []) {
+    const target = lanes[entry.protocol] ?? { nextSeq: 1, commands: [] };
+    lanes[entry.protocol] = {
+      ...target,
+      failed: [...(target.failed ?? []), entry],
+    };
+  }
+  return { clientId, lanes };
+};
+
+const normalize = (
+  parsed: unknown,
+  protocol: string,
+): StatewireClient.SessionRecord => {
+  if (!isRecord(parsed)) return invalid();
   const {
     statewireStorageVersion: format,
     savedAt: _savedAt,
-    ctxNextSeq: _ctxNextSeq,
-    context: _context,
     ...value
-  } = parsed as StatewireClient.SessionRecord & {
-    statewireStorageVersion?: unknown;
-    savedAt?: unknown;
-    ctxNextSeq?: unknown;
-    context?: unknown;
-  };
-  if (!isSessionRecord(value))
-    throw new Error("statewire: invalid stored session record");
+  } = parsed;
+  if (format === 3) return isSessionRecord(value) ? value : invalid();
   if (format !== undefined && format !== 1 && format !== 2)
     throw new Error("statewire: unsupported session storage version");
-  if (legacyProtocol === undefined || format !== undefined) return value;
-  const produced = {
-    wire: { version: "2026-09-07" },
-    protocols: [legacyProtocol],
-  };
-  return {
-    ...value,
-    commands: value.commands.map((command) =>
-      command.produced === undefined
-        ? {
-            ...command,
-            protocol: command.protocol ?? legacyProtocol.name,
-            produced,
-          }
-        : command,
-    ),
-    ...(value.failed === undefined
-      ? {}
-      : {
-          failed: value.failed.map((entry) => ({
-            ...entry,
-            protocol: entry.protocol ?? legacyProtocol.name,
-            produced: entry.produced ?? produced,
-          })),
-        }),
-  };
+  const { ctxNextSeq: _ctxNextSeq, context: _context, ...legacy } = value;
+  return liftLegacy(legacy, protocol);
 };
 
+const decode = (
+  raw: string | null,
+  protocol: string,
+): StatewireClient.SessionRecord | null =>
+  raw === null ? null : normalize(JSON.parse(raw), protocol);
+
+const isEmpty = (record: StatewireClient.SessionRecord) =>
+  Object.values(record.lanes).every(
+    (lane) => lane.commands.length === 0 && !lane.failed?.length,
+  );
+
 const active = new WeakMap<
   KeyValueSessionStorage.Backend,
   Map<string, number>
@@ -193,16 +226,11 @@ const sweep = async (
     } catch {
       return undefined;
     }
-    const format = isRecord(value)
-      ? value["statewireStorageVersion"]
-      : undefined;
-    if (format !== undefined && format !== 1 && format !== 2) return undefined;
-    if (
-      !isSessionRecord(value) ||
-      value.commands.length ||
-      value.failed?.length
-    )
+    try {
+      if (!isEmpty(normalize(value, DEFAULT_PROTOCOL))) return undefined;
+    } catch {
       return undefined;
+    }
     const savedAt =
       (value as Record<string, unknown>)["savedAt"] ??
       (value as Record<string, unknown>)["updatedAt"];
@@ -254,7 +282,7 @@ const useKeyValueSessionStorage = (
     backend,
     key,
     namespace = "",
-    legacyProtocol: suppliedLegacyProtocol,
+    protocol = DEFAULT_PROTOCOL,
     migrate,
     retention: suppliedRetention,
     onError,
@@ -265,15 +293,6 @@ const useKeyValueSessionStorage = (
     () => (error: unknown) => latestErrorHandler.current?.(error),
     [],
   );
-  const legacyName = suppliedLegacyProtocol?.name;
-  const legacyVersion = suppliedLegacyProtocol?.version;
-  const legacyProtocol = useMemo(
-    () =>
-      legacyName === undefined
-        ? undefined
-        : { name: legacyName, version: legacyVersion! },
-    [legacyName, legacyVersion],
-  );
   const retain = suppliedRetention !== undefined;
   const maxAgeMs = suppliedRetention?.maxAgeMs;
   const maxEntries = suppliedRetention?.maxEntries;
@@ -297,8 +316,6 @@ const useKeyValueSessionStorage = (
     [backend, key, namespace, retention],
   );
   const storageKey = namespace + key;
-  if (legacyProtocol !== undefined)
-    negotiationHeaders({ applicationProtocols: [legacyProtocol] });
   if (retention !== undefined) {
     if (!namespace)
       throw new Error("statewire: session retention requires a namespace");
@@ -336,7 +353,7 @@ const useKeyValueSessionStorage = (
     if (state.asynchronous) {
       state.ready = Promise.resolve(raw)
         .then((value) => {
-          state.record = decode(value, legacyProtocol);
+          state.record = decode(value, protocol);
           state.hydrated = true;
         })
         .catch((cause: unknown) => {
@@ -348,7 +365,7 @@ const useKeyValueSessionStorage = (
       state.ready.catch(() => {});
     } else {
       try {
-        state.record = decode(raw as string | null, legacyProtocol);
+        state.record = decode(raw as string | null, protocol);
       } catch (cause) {
         const error = wrapStorageError(cause);
         reportError(error);
@@ -356,7 +373,7 @@ const useKeyValueSessionStorage = (
       }
     }
     return state;
-  }, [backend, storageKey, legacyProtocol, reportError]);
+  }, [backend, storageKey, protocol, reportError]);
 
   useEffect(() => {
     const entries = active.get(backend) ?? new Map<string, number>();
@@ -401,7 +418,7 @@ const useKeyValueSessionStorage = (
             "statewire: storage backend changed from synchronous to asynchronous",
           );
         try {
-          return decode(raw, legacyProtocol);
+          return decode(raw, protocol);
         } catch (cause) {
           const error = wrapStorageError(cause);
           reportError(error);
@@ -418,7 +435,7 @@ const useKeyValueSessionStorage = (
           throw new Error("statewire: invalid session record");
         const encoded = JSON.stringify({
           ...record,
-          statewireStorageVersion: 2,
+          statewireStorageVersion: 3,
           savedAt: Date.now(),
         });
         state.record = record;
@@ -483,7 +500,7 @@ const useKeyValueSessionStorage = (
       state,
       backend,
       storageKey,
-      legacyProtocol,
+      protocol,
       migrate,
       retention,
       configured,
@@ -508,8 +525,8 @@ export namespace KeyValueSessionStorage {
     backend: Backend;
     key: string;
     namespace?: string;
-    /** The application format used by sessions saved before version negotiation. */
-    legacyProtocol?: { name: string; version: string };
+    /** The lane that sessions saved in a single-lane format lift into; defaults to the client's default protocol. */
+    protocol?: string;
     migrate?: StatewireClient.SessionStorage["migrate"];
     retention?: { maxAgeMs?: number; maxEntries?: number };
     onError?: (error: unknown) => void;

package/src/transports/remote.ts

@@ -4,11 +4,9 @@ import type { Statewire } from "../types";
 import {
   documentSource,
   invokeProtocol,
-  updateContext,
   discardFailed,
   failedCommands,
   retryFailed,
-  setContext,
   setTransport,
   useStatewireSession,
 } from "../client/session";
@@ -40,17 +38,12 @@ export const useStatewireRemote = <
     },
     invoke: (protocol, method, params) =>
       invokeProtocol(s, protocol, method, params),
-    updateContext: (ops) => updateContext(s, ops),
     commands: s.commands,
     connection: conn.connection,
     source: s.source,
-    get durableSeq() {
-      return s.durableSeq;
-    },
     get isBusy() {
       return !s.idle;
     },
-    setContext: (value) => setContext(s, value),
     failures: {
       list: () => failedCommands(s),
       retry: (entry) => retryFailed(s, entry),

package/src/transports/sse.ts

@@ -25,14 +25,19 @@ import { negotiationHeaders, parseNegotiation } from "../wire/protocol";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
-  ctx?: { ops: unknown[]; seq: number }[];
-  cmd?: { method: string; params: unknown[]; meta?: unknown; seq: number }[];
+  cmd?: {
+    protocol: string;
+    method: string;
+    params: unknown[];
+    meta?: unknown;
+    seq: number;
+  }[];
 };
 
 export type StatewireRemoteProps = {
   beforeAttach?: () => void | Promise<void>;
   clientId: string;
-  /** Lanes to ride the attach frame: the context restatement, plus cmds on no-lease supersession; records the included seqs. */
+  /** Lanes to ride the attach frame: ephemeral-lane statements, plus durable cmds on no-lease supersession; records the included entries. */
   takeAttachLanes: () => StatewireFrame | null;
   onHello: (args: { ops: unknown[]; syn: StatewireSyn }) => void;
   onOps: (args: { ops: unknown[]; cmds: StatewireCmd[] }) => void;