statewire 0.16.0 → 0.17.0

package/src/statewire.ts

@@ -1,3 +1,5 @@
+import type { StatewireDocuments } from "./wire/documents";
+import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireHost } from "./host";
 import { useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
@@ -13,18 +15,32 @@ import type { ResourceElement } from "@assistant-ui/tap";
 import { CONNECTED_CONNECTION, useStatewireCore } from "./client/core";
 import type { Statewire } from "./types";
 import type { TERMINAL } from "./client/connection";
-import { SessionStorageContext } from "./client/sessionStore";
+import {
+  DocumentStorageContext,
+  ProtocolContext,
+  SessionStorageContext,
+} from "./client/sessionStore";
 
 const useSessionTransport = ({
   transport,
   session,
+  documents,
+  protocol,
 }: {
   transport: ResourceElement<Statewire<any, any>>;
   session: StatewireClient.SessionStorage | undefined;
+  documents: StatewireDocuments.Storage | undefined;
+  protocol: StatewireProtocol.Options;
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
     // oxlint-disable-next-line react-hooks/rules-of-hooks
-    useResource(transport),
+    useContextProvider(DocumentStorageContext, documents, () =>
+      // oxlint-disable-next-line react-hooks/rules-of-hooks
+      useContextProvider(ProtocolContext, protocol, () =>
+        // oxlint-disable-next-line react-hooks/rules-of-hooks
+        useResource(transport),
+      ),
+    ),
   );
 
 // The transport owns the session; it reads the storage off the context this
@@ -45,8 +61,30 @@ export const useStatewire = <
       ? [withKey("session", options.storage.session)]
       : [],
   )[0];
+  const documents = useResources(
+    options.storage?.documents === undefined
+      ? []
+      : [withKey("documents", options.storage.documents)],
+  )[0];
+  const protocol: StatewireProtocol.Options = {
+    ...(options.protocol !== undefined && { protocol: options.protocol }),
+    ...(options.wireVersion !== undefined && {
+      wireVersion: options.wireVersion,
+    }),
+    ...(options.applicationProtocols !== undefined && {
+      applicationProtocols: options.applicationProtocols,
+    }),
+    ...(options.keyPrefixes !== undefined && {
+      keyPrefixes: options.keyPrefixes,
+    }),
+  };
   const value = useResource(
-    SessionTransport({ transport: options.transport, session }),
+    SessionTransport({
+      transport: options.transport,
+      session,
+      documents,
+      protocol,
+    }),
   );
   const core = useStatewireCore(() => latest.current, value);
   const [subscribe] = useState(
@@ -76,6 +114,26 @@ export const useStatewire = <
     };
     return {
       state,
+      documents: value.documents,
+      selection: value.selection,
+      invoke: (
+        protocol: string,
+        method: string,
+        params: readonly unknown[],
+      ) => {
+        if (!value.invoke)
+          throw new Error(
+            "statewire: transport does not support protocol commands",
+          );
+        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>,
@@ -129,6 +187,23 @@ export class StatewireClient<
     return this.root.getValue().commands;
   }
 
+  get documents(): StatewireDocuments.Source | undefined {
+    return this.root.getValue().documents;
+  }
+  get selection(): StatewireProtocol.Selection | undefined {
+    return this.root.getValue().selection;
+  }
+  invoke(
+    protocol: string,
+    method: string,
+    params: readonly unknown[],
+  ): 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;
   }
@@ -165,10 +240,17 @@ export namespace StatewireClient {
     TState,
     TCommands extends Statewire.Commands = Statewire.Commands,
   > = {
+    protocol?: string;
+    keyPrefixes?: Readonly<Record<string, readonly string[]>>;
+    wireVersion?: StatewireProtocol.Range;
+    applicationProtocols?: readonly StatewireProtocol.Offer[] | "*";
     transport: ResourceElement<Statewire<TState, TCommands>>;
     /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */
     storage?:
-      | { session?: ResourceElement<SessionStorage> | undefined }
+      | {
+          session?: ResourceElement<SessionStorage> | undefined;
+          documents?: ResourceElement<StatewireDocuments.Storage> | undefined;
+        }
       | undefined;
     /** Served as the canonical state until the attach snapshot; own commands fold over it. */
     initialState?: TState;
@@ -197,6 +279,14 @@ export namespace StatewireClient {
   > = {
     /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */
     state: TState;
+    documents: StatewireDocuments.Source | undefined;
+    selection: StatewireProtocol.Selection | undefined;
+    invoke: (
+      protocol: string,
+      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;
@@ -318,6 +408,8 @@ export namespace StatewireClient {
 
   /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */
   export type FailedCommand = {
+    readonly protocol: string;
+    readonly produced?: SessionCommand["produced"];
     readonly command: string;
     readonly params: readonly unknown[];
     readonly meta?: unknown;
@@ -329,6 +421,11 @@ 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[] | "*";
+    };
     method: string;
     params: unknown[];
     meta?: unknown;
@@ -339,6 +436,7 @@ export namespace StatewireClient {
     clientId: string;
     nextSeq: number;
     ctxNextSeq: number;
+    context?: { ops: unknown[]; pending: { seq: number; ops: unknown[] }[] };
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
@@ -360,6 +458,11 @@ export namespace StatewireClient {
   export type SessionStorage = {
     load: () => SessionRecord | null;
     save: (record: SessionRecord) => void;
+    /** Upgrade incompatible stored commands; null discards the old record and starts a new client identity. */
+    migrate?: (
+      record: SessionRecord,
+      current: NonNullable<SessionCommand["produced"]>,
+    ) => SessionRecord | null;
     /** 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`. */
@@ -373,7 +476,7 @@ export namespace StatewireClient {
     | HeadersInit
     | ((ctx: { staleAuth: boolean }) => HeadersInit | Promise<HeadersInit>);
 
-  export type HttpOptions = {
+  export type HttpOptions = StatewireProtocol.Options & {
     sessionStore?: SessionStorage | undefined;
     url: string;
     /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */
@@ -387,7 +490,7 @@ export namespace StatewireClient {
     onDone?: () => void;
   };
 
-  export type WebsocketOptions = {
+  export type WebsocketOptions = StatewireProtocol.Options & {
     sessionStore?: SessionStorage | undefined;
     url: string;
     /** The session does not exist on the server yet: the first attach waits for the first command send (or an explicit `reconnect()`). */

package/src/transports/fixtures.ts

@@ -24,7 +24,7 @@ export const commandFrame = (
   method: string,
   seq: number,
   params: unknown[] = [],
-) => JSON.stringify({ cmd: [{ method, params, seq }] });
+) => JSON.stringify({ cmd: [{ protocol: "default", method, params, seq }] });
 
 export type SocketRecorder = {
   sent: string[];

package/src/transports/remote.ts

@@ -1,6 +1,10 @@
-import { useEffect } from "react";
+import { useContext, useEffect } from "react";
+import { ProtocolContext } from "../client/sessionStore";
 import type { Statewire } from "../types";
 import {
+  documentSource,
+  invokeProtocol,
+  updateContext,
   discardFailed,
   failedCommands,
   retryFailed,
@@ -22,16 +26,21 @@ export const useStatewireRemote = <
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any> => {
-  const s = useStatewireSession({
-    sessionStore: options.sessionStore,
-    onSessionLost: options.onSessionLost,
-    onDone: options.onDone,
-  });
-  const conn = useLink(options, s.ctx);
+  const inherited = useContext(ProtocolContext);
+  const configured = { ...inherited, ...options };
+  const s = useStatewireSession(configured);
+  const conn = useLink(configured, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 
   return {
     state: s.canonical,
+    documents: documentSource(s),
+    get selection() {
+      return s.selection;
+    },
+    invoke: (protocol, method, params) =>
+      invokeProtocol(s, protocol, method, params),
+    updateContext: (ops) => updateContext(s, ops),
     commands: s.commands,
     connection: conn.connection,
     source: s.source,

package/src/transports/sse.ts

@@ -7,7 +7,6 @@ import {
   classify,
   handleEnvelope,
   resolveHeaders,
-  unsupportedVersion,
   useLink,
   validateRefusalSyn,
 } from "../client/connection";
@@ -22,7 +21,7 @@ import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import type { StatewireHost } from "../host";
 import { useStatewireRemote } from "./remote";
-import { PROTOCOL_VERSION, VERSION_HEADER } from "../wire/version";
+import { negotiationHeaders, parseNegotiation } from "../wire/protocol";
 
 /** A client frame's lanes: stamped statements, strictly consecutive per lane. */
 export type StatewireFrame = {
@@ -121,6 +120,10 @@ const attemptStream = async (
 ): Promise<AttemptOutcome> => {
   c.lease = null;
   const headers = await resolveHeaders(options.headers, c.authStale);
+  for (const [name, value] of Object.entries(negotiationHeaders(options))) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
+  c.negotiation = parseNegotiation(headers);
   c.authStale = false;
   const lanes = flushTapSync(() => c.ctx.takeAttachLanes());
   const body = lanes === null ? undefined : JSON.stringify(lanes);
@@ -150,14 +153,21 @@ const attemptStream = async (
   } finally {
     clearTimeout(headerTimer);
   }
-  if (!res.ok) return flushTapSync(() => settleFin(c, httpFin(res)));
+  if (!res.ok) {
+    const body = await res
+      .clone()
+      .json()
+      .catch(() => null);
+    return (
+      flushTapSync(() =>
+        body?.fin === undefined
+          ? settleFin(c, httpFin(res))
+          : handleEnvelope(c, body),
+      ) ?? "stop"
+    );
+  }
   if (!res.body)
     throw new Error("statewire: protocol error: stream response has no body");
-  const version = res.headers.get(VERSION_HEADER)?.trim();
-  if (version !== undefined && version !== PROTOCOL_VERSION) {
-    res.body.cancel().catch(() => {});
-    return unsupportedVersion(c, version);
-  }
   c.lease = res.headers.get(LEASE_HEADER);
   const reader = res.body.getReader();
   try {

package/src/transports/testing.ts

@@ -41,6 +41,7 @@ let mockCount = 0;
 
 export const createMockTransport = <TState>(
   initialState: TState,
+  protocol = "default",
 ): MockTransport<TState> => {
   let state: unknown = initialState;
   let clientId = "";
@@ -57,11 +58,13 @@ export const createMockTransport = <TState>(
   const admit = (id: string, frame: StatewireFrame) => {
     const rec = clients.get(id)!;
     for (const statement of frame.ctx ?? []) {
+      if (statement.seq <= rec.ctxSeq) continue;
       rec.ctxSeq = Math.max(rec.ctxSeq, statement.seq);
       const root = statement.ops[0] as { value?: unknown } | undefined;
       commands.push({ context: root?.value });
     }
     for (const statement of frame.cmd ?? []) {
+      if (statement.seq <= rec.seq) continue;
       rec.seq = Math.max(rec.seq, statement.seq);
       commands.push({ method: statement.method, params: statement.params });
     }
@@ -87,8 +90,13 @@ export const createMockTransport = <TState>(
         (handle) => {
           handle.send(
             sseFrame({
-              ops: [{ op: "replace", path: [], value: state }],
-              syn: { seq: rec.seq, ctxSeq: rec.ctxSeq },
+              ops: [{ op: "mount", protocol, main: true, value: state }],
+              syn: {
+                seq: rec.seq,
+                ctxSeq: rec.ctxSeq,
+                version: "2026-09-07",
+                protocols: [{ name: protocol, version: "2026-09-07" }],
+              },
             }),
           );
         },

package/src/transports/ws.ts

@@ -72,7 +72,7 @@ const runSocket = (
     ws.onerror = () => {};
     ws.onopen = () => {
       const negotiated = ws.protocol.trim();
-      if (negotiated !== "" && negotiated !== WS_SUBPROTOCOL) {
+      if (negotiated !== WS_SUBPROTOCOL) {
         outcome = unsupportedVersion(c, negotiated);
         ws.close();
         return;

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { StatewireDocuments } from "./wire/documents";
+import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
 
@@ -16,6 +18,7 @@ export namespace Statewire {
 
   export type CommandUpdate<TCommands extends Commands = Commands> = {
     [K in keyof TCommands]: {
+      readonly protocol?: string;
       method: K;
       params: Parameters<TCommands[K]>;
       seq: number;
@@ -50,6 +53,14 @@ export interface Statewire<
   TCommands extends Statewire.Commands = Statewire.Commands,
 > {
   state: TState;
+  documents?: StatewireDocuments.Source;
+  selection?: StatewireProtocol.Selection | undefined;
+  invoke?: (
+    protocol: string,
+    method: string,
+    params: readonly unknown[],
+  ) => Promise<unknown>;
+  updateContext?: (ops: readonly unknown[]) => void;
   commands: Statewire.CommandsProxy<TCommands>;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;

package/src/wire/documents.ts

@@ -1,9 +1,31 @@
 import { applyOps } from "./ops";
 import { reviveValue } from "./meta";
+import { protocolToken } from "./protocol";
 import type { StatewirePath } from "./ops";
 
 export namespace StatewireDocuments {
-  export type Document = { key: readonly string[] | null; value: unknown };
+  export type CacheEntry = { version: string; value: unknown };
+  export type Storage = {
+    namespace?: string;
+    load: (identity: readonly string[]) => CacheEntry | undefined;
+    save: (identity: readonly string[], entry: CacheEntry) => void;
+    subscribe?: (listener: () => void) => () => void;
+  };
+  export type Source = {
+    get: (
+      protocol: string,
+      key?: readonly string[],
+      prefix?: readonly string[],
+    ) => unknown;
+    list: () => ReadonlyMap<number, Document>;
+    subscribe: (listener: () => void) => () => void;
+  };
+  export type Document = {
+    key: readonly string[] | null;
+    protocol?: string;
+    main?: boolean;
+    value: unknown;
+  };
   export type State = {
     mode: "mounted" | "keyless" | null;
     documents: ReadonlyMap<number, Document>;
@@ -17,8 +39,12 @@ const invalid: (message: string) => never = (message) => {
 export const applyDocumentOps = (
   previous: StatewireDocuments.State,
   ops: readonly unknown[],
+  protocols?: readonly { name: string; version: string }[],
+  strict = false,
 ) => {
-  let mode = previous.mode;
+  let mode =
+    previous.mode ??
+    (protocols !== undefined && ops.length === 0 ? "mounted" : null);
   const documents = new Map(previous.documents);
   const changedPaths: StatewirePath[] = [];
   for (const raw of ops) {
@@ -35,10 +61,13 @@ export const applyDocumentOps = (
         op.op as string,
       )
     ) {
+      if (strict) invalid("unknown context operation");
       const { doc: _doc, ...unknown } = op;
       applyOps(undefined, [unknown]);
       continue;
     }
+    if (protocols !== undefined && mode === null && op.op !== "mount")
+      invalid("negotiated state must start with mounts");
     if (mode === null) {
       if (op.op === "mount") mode = "mounted";
       else if (
@@ -64,23 +93,73 @@ export const applyDocumentOps = (
     if (op.op === "mount") {
       if (documents.has(doc)) invalid("document is already mounted");
       if (
-        !Array.isArray(op.key) ||
-        !op.key.every((key) => typeof key === "string") ||
+        (op.key !== undefined &&
+          (!Array.isArray(op.key) ||
+            !op.key.every((key) => typeof key === "string"))) ||
         !("value" in op)
       ) {
-        invalid("mount requires a key array and value");
+        invalid("mount requires value and an optional key array");
       }
+      if (
+        op.protocol !== undefined &&
+        (typeof op.protocol !== "string" ||
+          !protocolToken.test(op.protocol) ||
+          op.protocol === "*")
+      )
+        invalid("invalid mount protocol");
+      if (
+        protocols !== undefined &&
+        !protocols.some((p) => p.name === op.protocol)
+      )
+        invalid("mount protocol was not negotiated");
+      if (op.main !== undefined && typeof op.main !== "boolean")
+        invalid("main must be boolean");
+      if (
+        op.main === true &&
+        [...documents.values()].some(
+          (d) => d.protocol === op.protocol && d.main,
+        )
+      )
+        invalid("protocol already has a main document");
+      if (
+        op.key !== undefined &&
+        [...documents.values()].some(
+          (d) =>
+            d.protocol === op.protocol &&
+            JSON.stringify(d.key) === JSON.stringify(op.key),
+        )
+      )
+        invalid("protocol document key is already mounted");
       documents.set(doc, {
-        key: op.key,
+        key: op.key === undefined ? null : (op.key as string[]),
+        ...(op.protocol === undefined
+          ? {}
+          : { protocol: op.protocol as string }),
+        ...(op.main === undefined ? {} : { main: op.main as boolean }),
         value:
-          op.meta === undefined ? op.value : reviveValue(op.value, op.meta),
+          op.meta === undefined
+            ? op.value
+            : reviveValue(op.value, op.meta, { rejectUnknown: strict }),
       });
       if (doc === 0) changedPaths.push([]);
     } else if (op.op === "unmount") {
+      const document = documents.get(doc);
+      if (
+        protocols !== undefined &&
+        document !== undefined &&
+        !protocols.some((p) => p.name === document.protocol)
+      )
+        invalid("document protocol was not negotiated");
       if (!documents.delete(doc)) invalid("document is not mounted");
       if (doc === 0) changedPaths.push([]);
     } else if (op.op === "add" || op.op === "replace" || op.op === "remove") {
       const document = documents.get(doc);
+      if (
+        protocols !== undefined &&
+        document !== undefined &&
+        !protocols.some((p) => p.name === document.protocol)
+      )
+        invalid("document protocol was not negotiated");
       if (!document) invalid("document is not mounted");
       if (
         !Array.isArray(op.path) ||
@@ -98,7 +177,9 @@ export const applyDocumentOps = (
         invalid("operation requires a value");
       const { doc: _doc, meta, ...mutation } = op;
       if (meta !== undefined)
-        mutation.value = reviveValue(mutation.value, meta);
+        mutation.value = reviveValue(mutation.value, meta, {
+          rejectUnknown: strict,
+        });
       const applied = applyOps(document.value, [mutation]);
       documents.set(doc, { ...document, value: applied.state });
       if (doc === 0) changedPaths.push(...applied.changedPaths);
@@ -107,3 +188,40 @@ export const applyDocumentOps = (
   if (mode === null) invalid("hello missing snapshot");
   return { mode, documents, changedPaths };
 };
+
+export const mainDocument = (
+  state: StatewireDocuments.State,
+  protocol: string,
+) =>
+  [...state.documents.values()].find(
+    (document) => document.protocol === protocol && document.main,
+  );
+
+export const resolveDocumentKey = (
+  key: readonly string[],
+  prefix?: readonly string[],
+) =>
+  key[0] === "."
+    ? prefix === undefined
+      ? undefined
+      : [...prefix, ...key.slice(1)]
+    : key;
+
+export const findDocument = (
+  state: StatewireDocuments.State,
+  protocol: string,
+  key?: readonly string[],
+  prefix?: readonly string[],
+) => {
+  if (key === undefined) return mainDocument(state, protocol);
+  const resolved = resolveDocumentKey(key, prefix);
+  return [...state.documents.values()].find(
+    (document) =>
+      document.protocol === protocol &&
+      document.key !== null &&
+      (JSON.stringify(document.key) === JSON.stringify(key) ||
+        (resolved !== undefined &&
+          JSON.stringify(resolveDocumentKey(document.key, prefix)) ===
+            JSON.stringify(resolved))),
+  );
+};