statewire 0.18.2 → 0.19.0

package/src/transports/testing.ts

@@ -5,6 +5,7 @@ import type { StatewireFrame } from "./sse";
 import type { Statewire } from "../types";
 import { openSSEStream, sseFrame } from "./fake-sse";
 import type { FakeStreamHandle } from "./fake-sse";
+import { WIRE_VERSION } from "../wire/protocol";
 
 export * from "./fixtures";
 
@@ -16,8 +17,8 @@ export { applyOptimistic } from "../util/recordMutations";
 export type MockTransport<TState> = {
   /** Pass as the `transport:` option of useStatewire / Harness. */
   transport: ResourceElement<Statewire<TState | undefined, any>>;
-  /** Captured statements in arrival order: cmd as `{method, params}`, ctx as `{context}`. */
-  commands: { method?: string; params?: unknown[]; context?: unknown }[];
+  /** Captured statements in arrival order. */
+  commands: { protocol: string; method: string; params: unknown[] }[];
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver a bare ack cmd packet on the stream. */
@@ -42,11 +43,15 @@ let mockCount = 0;
 export const createMockTransport = <TState>(
   initialState: TState,
   protocol = "default",
+  options: { ephemeral?: readonly string[] } = {},
 ): MockTransport<TState> => {
+  const ephemeral = (options.ephemeral ?? []).map(
+    (child) => `${protocol}/${child}`,
+  );
   let state: unknown = initialState;
   let clientId = "";
   let finished = false;
-  const clients = new Map<string, { seq: number; ctxSeq: number }>();
+  const clients = new Map<string, Record<string, number>>();
   const streams = new Set<FakeStreamHandle>();
   const commands: MockTransport<unknown>["commands"] = [];
 
@@ -57,16 +62,14 @@ 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 });
+      if (statement.seq <= (rec[statement.protocol] ?? 0)) continue;
+      rec[statement.protocol] = statement.seq;
+      commands.push({
+        protocol: statement.protocol,
+        method: statement.method,
+        params: statement.params,
+      });
     }
   };
 
@@ -80,9 +83,9 @@ export const createMockTransport = <TState>(
     const id = headers.get("Statewire-Client-Id") ?? "";
     if (url.endsWith("/stream")) {
       clientId = id;
-      if (!clients.has(id)) clients.set(id, { seq: 0, ctxSeq: 0 });
+      if (!clients.has(id)) clients.set(id, {});
       const rec = clients.get(id)!;
-      rec.ctxSeq = 0;
+      for (const lane of ephemeral) delete rec[lane];
       const frame = JSON.parse(String(init?.body ?? "{}")) as StatewireFrame;
       admit(id, frame);
       return openSSEStream(
@@ -93,10 +96,20 @@ export const createMockTransport = <TState>(
             sseFrame({
               ops: [{ op: "mount", protocol, main: true, value: state }],
               syn: {
-                seq: rec.seq,
-                ctxSeq: 0,
-                version: "2026-09-07",
-                protocols: [{ name: protocol, version: "2026-09-07" }],
+                version: WIRE_VERSION,
+                protocols: [
+                  {
+                    name: protocol,
+                    version: WIRE_VERSION,
+                    seq: rec[protocol] ?? 0,
+                  },
+                  ...ephemeral.map((name) => ({
+                    name,
+                    version: WIRE_VERSION,
+                    record: "ephemeral" as const,
+                    seq: 0,
+                  })),
+                ],
               },
             }),
           );
@@ -122,11 +135,13 @@ export const createMockTransport = <TState>(
       state = next;
       return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });
     },
-    applied: (seq) => sendEnvelope({ cmd: [{ seq, type: "applied" }] }),
+    applied: (seq) =>
+      sendEnvelope({ cmd: [{ protocol, seq, type: "applied" }] }),
     settle: (seq, payload) =>
       sendEnvelope({
         cmd: [
           {
+            protocol,
             seq,
             type: "result",
             ...(payload !== undefined && { payload }),

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { StatewireDocuments } from "./wire/documents";
+import type { StatewireHost } from "./host";
 import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
@@ -60,17 +61,14 @@ export interface Statewire<
     method: string,
     params: readonly unknown[],
   ) => Promise<unknown>;
-  updateContext?: (ops: readonly unknown[]) => void;
   commands: Statewire.CommandsProxy<TCommands>;
   connection?: StatewireClient.Connection;
   source?: Statewire.StateSource;
-  /** Highest command seq the server's dur flag states durably admitted — never lost, never run again — and released from the resend queue. */
-  durableSeq?: number;
   /** Negation of the server's broadcast idle level; absent means always busy. */
   isBusy?: boolean;
   work?: { readonly isIdle: boolean };
-  /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
-  setContext?: (value: Record<string, unknown>) => void;
+  /** Called by the serving host when an attach ends; its ephemeral documents and includes are gone. */
+  detached?: (attach: StatewireHost.Attach) => void;
   /** The retained failed-send lane; present on transports with a durable session. */
   failures?: {
     list: () => readonly StatewireClient.FailedCommand[];

package/src/wire/limits.ts

@@ -1,6 +1,6 @@
 export const MAX_COMMANDS_PER_FRAME = 256;
 export const MAX_INFLIGHT_COMMANDS_PER_CLIENT = 256;
 export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
-export const MAX_CONTEXT_VALUE_BYTES = 64 * 1024;
+export const MAX_EPHEMERAL_DOCUMENT_BYTES = 64 * 1024;
 export const MAX_INFLIGHT_COMMANDS_PER_HOST = 1024;
 export const COMMAND_CAPACITY_RETRY_MS = 1_000;

package/src/wire/protocol.ts

@@ -3,7 +3,7 @@ export namespace StatewireProtocol {
   export type Offer = Range & { name: string; optional?: boolean };
   export type Selection = {
     version: string;
-    protocols: { name: string; version: string }[];
+    protocols: { name: string; version: string; record?: "ephemeral" }[];
   };
   export type Options = {
     wireVersion?: Range;
@@ -14,10 +14,11 @@ export namespace StatewireProtocol {
   export type Definition = Range & {
     name: string;
     requires?: Readonly<Record<string, Range>>;
+    subprotocols?: readonly { name: string; record?: "ephemeral" }[];
   };
 }
 
-export const WIRE_VERSION = "2026-09-07";
+export const WIRE_VERSION = "2026-09-13";
 export const DEFAULT_PROTOCOL = "default";
 export const PROTOCOL_HEADER = "Statewire-Protocol";
 export const VERSION_HEADER = "Statewire-Version";
@@ -197,7 +198,7 @@ export const validateSelection = (
   if (!Array.isArray(syn.protocols))
     return invalid("syn.protocols must be an array");
   const offers = protocolOffers(options);
-  const seen = new Set<string>();
+  const seen = new Map<string, string>();
   const protocols = syn.protocols.map((entry: unknown) => {
     if (typeof entry !== "object" || entry === null)
       return invalid("invalid selected protocol");
@@ -211,13 +212,21 @@ export const validateSelection = (
     )
       return invalid("invalid selected protocol name");
     const version = validateVersion(item.version);
-    seen.add(name);
-    if (offers !== "*") {
+    if (item.record !== undefined && item.record !== "ephemeral")
+      invalid("invalid selected protocol record");
+    const record = item.record as "ephemeral" | undefined;
+    const parent = name.slice(0, name.lastIndexOf("/"));
+    const child = parent !== "" && seen.has(parent);
+    if (child) {
+      if (seen.get(parent) !== version)
+        invalid("subprotocol version differs from its parent");
+    } else if (offers !== "*") {
       const offer = offers.find((o) => o.name === name);
       if (!offer || !inRange(version, offer))
         invalid("selected protocol is outside offer");
     }
-    return { name, version };
+    seen.set(name, version);
+    return { name, version, ...(record !== undefined && { record }) };
   });
   if (offers !== "*" && offers.some((o) => !o.optional && !seen.has(o.name)))
     invalid("required protocol missing from selection");
@@ -275,6 +284,19 @@ export const negotiateProtocols = (
   const registry = new Map(definitions.map((d) => [d.name, d]));
   if (registry.size !== definitions.length)
     throw new Error("statewire: duplicate registered protocol");
+  for (const definition of definitions) {
+    const children = new Set<string>();
+    for (const child of definition.subprotocols ?? []) {
+      if (
+        !protocolToken.test(child.name) ||
+        child.name.includes("/") ||
+        children.has(child.name) ||
+        (child.record !== undefined && child.record !== "ephemeral")
+      )
+        throw new Error("statewire: invalid subprotocol registration");
+      children.add(child.name);
+    }
+  }
   const offered = new Map(offers.map((o) => [o.name, o]));
   const solve = (names: Set<string>) => {
     const active = new Set(names);
@@ -318,10 +340,17 @@ export const negotiateProtocols = (
   }
   return {
     version,
-    protocols: offers.flatMap((o) =>
-      selected!.has(o.name)
-        ? [{ name: o.name, version: selected!.get(o.name)! }]
-        : [],
-    ),
+    protocols: offers.flatMap((o) => {
+      const version = selected!.get(o.name);
+      if (version === undefined) return [];
+      return [
+        { name: o.name, version },
+        ...(registry.get(o.name)!.subprotocols ?? []).map((child) => ({
+          name: `${o.name}/${child.name}`,
+          version,
+          ...(child.record !== undefined && { record: child.record }),
+        })),
+      ];
+    }),
   };
 };