statewire 0.11.0 → 0.12.0

package/dist/transports/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":["ResourceElement","StatewireEnvelope","StatewireSSE","StatewireFrame","Statewire","openSSEStream","sseFrame","FakeStreamHandle","tick","Promise","r","setTimeout","applyOptimistic","MockTransport","transport","TState","commands","method","params","context","setState","state","applied","seq","settle","payload","sendEnvelope","envelope","finish","reason","message","clientId","attached","mockCount","createMockTransport","initialState","finished","clients","Map","ctxSeq","streams","Set","stream","send","admit","id","frame","rec","get","statement","ctx","Math","max","root","ops","value","push","cmd","fakeFetch","input","RequestInfo","URL","init","RequestInit","Response","TypeError","url","String","headers","Headers","endsWith","known","has","set","JSON","parse","body","handle","op","path","syn","record","signal","undefined","json","status","fetch","next","type","fin","close","size"],"sources":["../../src/transports/testing.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { StatewireEnvelope } from \"../client/connection\";\nimport { StatewireSSE } from \"./sse\";\nimport type { StatewireFrame } from \"./sse\";\nimport type { Statewire } from \"../types\";\nimport { openSSEStream, sseFrame } from \"./fake-sse\";\nimport type { FakeStreamHandle } from \"./fake-sse\";\n\nexport * from \"./fixtures\";\n\n/** Let queued microtasks and op batches drain through the statewire client. */\nexport const tick = () => new Promise<void>((r) => setTimeout(r, 0));\n\nexport { applyOptimistic } from \"../util/recordMutations\";\n\nexport type MockTransport<TState> = {\n  /** Pass as the `transport:` option of useStatewire / Harness. */\n  transport: ResourceElement<Statewire<TState | undefined, any>>;\n  /** Captured statements in arrival order: cmd as `{method, params}`, ctx as `{context}`. */\n  commands: { method?: string; params?: unknown[]; context?: unknown }[];\n  /** Replace the replicated state and broadcast it as a root snapshot op. */\n  setState: (state: TState) => Promise<void>;\n  /** Deliver a bare ack cmd packet on the stream. */\n  applied: (seq: number) => Promise<void>;\n  /** Deliver a terminal result cmd packet on the stream. */\n  settle: (seq: number, payload?: unknown) => Promise<void>;\n  /** Deliver an arbitrary envelope on the stream. */\n  sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>;\n  /** End the stream with a fin; further attaches fail like a dead server. */\n  finish: (reason: string, message?: string) => Promise<void>;\n  readonly clientId: string;\n  readonly attached: boolean;\n};\n\n/**\n * A mock statewire backend: serves `initialState` as the attach snapshot,\n * records submitted frames (receipt only — acks and results are delivered\n * from test code), and exposes the wire as a transport ResourceElement.\n */\nlet mockCount = 0;\n\nexport const createMockTransport = <TState>(\n  initialState: TState,\n): MockTransport<TState> => {\n  let state: unknown = initialState;\n  let clientId = \"\";\n  let finished = false;\n  const clients = new Map<string, { seq: number; ctxSeq: number }>();\n  const streams = new Set<FakeStreamHandle>();\n  const commands: MockTransport<unknown>[\"commands\"] = [];\n\n  const sendEnvelope = (envelope: StatewireEnvelope) => {\n    for (const stream of streams) stream.send(sseFrame(envelope));\n    return tick();\n  };\n\n  const admit = (id: string, frame: StatewireFrame) => {\n    const rec = clients.get(id)!;\n    for (const statement of frame.ctx ?? []) {\n      rec.ctxSeq = Math.max(rec.ctxSeq, statement.seq);\n      const root = statement.ops[0] as { value?: unknown } | undefined;\n      commands.push({ context: root?.value });\n    }\n    for (const statement of frame.cmd ?? []) {\n      rec.seq = Math.max(rec.seq, statement.seq);\n      commands.push({ method: statement.method, params: statement.params });\n    }\n  };\n\n  const fakeFetch = (async (\n    input: RequestInfo | URL,\n    init?: RequestInit,\n  ): Promise<Response> => {\n    if (finished) throw new TypeError(\"fetch failed (finished)\");\n    const url = String(input);\n    const headers = new Headers(init?.headers);\n    const id = headers.get(\"Statewire-Client-Id\") ?? \"\";\n    if (url.endsWith(\"/stream\")) {\n      clientId = id;\n      const known = clients.has(id);\n      if (!known) clients.set(id, { seq: 0, ctxSeq: 0 });\n      const rec = clients.get(id)!;\n      const frame = JSON.parse(String(init?.body)) as StatewireFrame;\n      admit(id, frame);\n      return openSSEStream(\n        streams,\n        id,\n        (handle) => {\n          handle.send(\n            sseFrame({\n              ops: [{ op: \"replace\", path: [], value: state }],\n              syn: {\n                seq: rec.seq,\n                ctxSeq: rec.ctxSeq,\n                record: known ? \"resumed\" : \"fresh\",\n              },\n            }),\n          );\n        },\n        init?.signal ?? undefined,\n        { \"Statewire-Lease\": \"mock-lease\" },\n      );\n    }\n    if (url.endsWith(\"/frames\")) {\n      admit(id, JSON.parse(String(init?.body)) as StatewireFrame);\n      return Response.json({});\n    }\n    return new Response(null, { status: 404 });\n  }) as typeof fetch;\n\n  return {\n    transport: StatewireSSE({\n      url: `http://mock-${++mockCount}/api`,\n      fetch: fakeFetch,\n    }),\n    commands,\n    setState: (next) => {\n      state = next;\n      return sendEnvelope({ ops: [{ op: \"replace\", path: [], value: next }] });\n    },\n    applied: (seq) => sendEnvelope({ cmd: [{ seq, type: \"applied\" }] }),\n    settle: (seq, payload) =>\n      sendEnvelope({\n        cmd: [\n          {\n            seq,\n            type: \"result\",\n            ...(payload !== undefined && { payload }),\n          },\n        ],\n      }),\n    sendEnvelope,\n    finish: async (reason, message) => {\n      await sendEnvelope({\n        fin: { reason, ...(message !== undefined && { message }) },\n      });\n      finished = true;\n      for (const stream of [...streams]) stream.close();\n      await tick();\n    },\n    get clientId() {\n      return clientId;\n    },\n    get attached() {\n      return streams.size > 0;\n    },\n  };\n};\n"],"mappings":"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"}
+{"version":3,"file":"testing.js","names":["ResourceElement","StatewireEnvelope","StatewireSSE","StatewireFrame","Statewire","openSSEStream","sseFrame","FakeStreamHandle","tick","Promise","r","setTimeout","applyOptimistic","MockTransport","transport","TState","commands","method","params","context","setState","state","applied","seq","settle","payload","sendEnvelope","envelope","finish","reason","message","clientId","attached","mockCount","createMockTransport","initialState","finished","clients","Map","ctxSeq","streams","Set","stream","send","admit","id","frame","rec","get","statement","ctx","Math","max","root","ops","value","push","cmd","fakeFetch","input","RequestInfo","URL","init","RequestInit","Response","TypeError","url","String","headers","Headers","endsWith","has","set","JSON","parse","body","handle","op","path","syn","signal","undefined","json","status","fetch","next","type","fin","close","size"],"sources":["../../src/transports/testing.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { StatewireEnvelope } from \"../client/connection\";\nimport { StatewireSSE } from \"./sse\";\nimport type { StatewireFrame } from \"./sse\";\nimport type { Statewire } from \"../types\";\nimport { openSSEStream, sseFrame } from \"./fake-sse\";\nimport type { FakeStreamHandle } from \"./fake-sse\";\n\nexport * from \"./fixtures\";\n\n/** Let queued microtasks and op batches drain through the statewire client. */\nexport const tick = () => new Promise<void>((r) => setTimeout(r, 0));\n\nexport { applyOptimistic } from \"../util/recordMutations\";\n\nexport type MockTransport<TState> = {\n  /** Pass as the `transport:` option of useStatewire / Harness. */\n  transport: ResourceElement<Statewire<TState | undefined, any>>;\n  /** Captured statements in arrival order: cmd as `{method, params}`, ctx as `{context}`. */\n  commands: { method?: string; params?: unknown[]; context?: unknown }[];\n  /** Replace the replicated state and broadcast it as a root snapshot op. */\n  setState: (state: TState) => Promise<void>;\n  /** Deliver a bare ack cmd packet on the stream. */\n  applied: (seq: number) => Promise<void>;\n  /** Deliver a terminal result cmd packet on the stream. */\n  settle: (seq: number, payload?: unknown) => Promise<void>;\n  /** Deliver an arbitrary envelope on the stream. */\n  sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>;\n  /** End the stream with a fin; further attaches fail like a dead server. */\n  finish: (reason: string, message?: string) => Promise<void>;\n  readonly clientId: string;\n  readonly attached: boolean;\n};\n\n/**\n * A mock statewire backend: serves `initialState` as the attach snapshot,\n * records submitted frames (receipt only — acks and results are delivered\n * from test code), and exposes the wire as a transport ResourceElement.\n */\nlet mockCount = 0;\n\nexport const createMockTransport = <TState>(\n  initialState: TState,\n): MockTransport<TState> => {\n  let state: unknown = initialState;\n  let clientId = \"\";\n  let finished = false;\n  const clients = new Map<string, { seq: number; ctxSeq: number }>();\n  const streams = new Set<FakeStreamHandle>();\n  const commands: MockTransport<unknown>[\"commands\"] = [];\n\n  const sendEnvelope = (envelope: StatewireEnvelope) => {\n    for (const stream of streams) stream.send(sseFrame(envelope));\n    return tick();\n  };\n\n  const admit = (id: string, frame: StatewireFrame) => {\n    const rec = clients.get(id)!;\n    for (const statement of frame.ctx ?? []) {\n      rec.ctxSeq = Math.max(rec.ctxSeq, statement.seq);\n      const root = statement.ops[0] as { value?: unknown } | undefined;\n      commands.push({ context: root?.value });\n    }\n    for (const statement of frame.cmd ?? []) {\n      rec.seq = Math.max(rec.seq, statement.seq);\n      commands.push({ method: statement.method, params: statement.params });\n    }\n  };\n\n  const fakeFetch = (async (\n    input: RequestInfo | URL,\n    init?: RequestInit,\n  ): Promise<Response> => {\n    if (finished) throw new TypeError(\"fetch failed (finished)\");\n    const url = String(input);\n    const headers = new Headers(init?.headers);\n    const id = headers.get(\"Statewire-Client-Id\") ?? \"\";\n    if (url.endsWith(\"/stream\")) {\n      clientId = id;\n      if (!clients.has(id)) clients.set(id, { seq: 0, ctxSeq: 0 });\n      const rec = clients.get(id)!;\n      const frame = JSON.parse(String(init?.body)) as StatewireFrame;\n      admit(id, frame);\n      return openSSEStream(\n        streams,\n        id,\n        (handle) => {\n          handle.send(\n            sseFrame({\n              ops: [{ op: \"replace\", path: [], value: state }],\n              syn: { seq: rec.seq, ctxSeq: rec.ctxSeq },\n            }),\n          );\n        },\n        init?.signal ?? undefined,\n        { \"Statewire-Lease\": \"mock-lease\" },\n      );\n    }\n    if (url.endsWith(\"/frames\")) {\n      admit(id, JSON.parse(String(init?.body)) as StatewireFrame);\n      return Response.json({});\n    }\n    return new Response(null, { status: 404 });\n  }) as typeof fetch;\n\n  return {\n    transport: StatewireSSE({\n      url: `http://mock-${++mockCount}/api`,\n      fetch: fakeFetch,\n    }),\n    commands,\n    setState: (next) => {\n      state = next;\n      return sendEnvelope({ ops: [{ op: \"replace\", path: [], value: next }] });\n    },\n    applied: (seq) => sendEnvelope({ cmd: [{ seq, type: \"applied\" }] }),\n    settle: (seq, payload) =>\n      sendEnvelope({\n        cmd: [\n          {\n            seq,\n            type: \"result\",\n            ...(payload !== undefined && { payload }),\n          },\n        ],\n      }),\n    sendEnvelope,\n    finish: async (reason, message) => {\n      await sendEnvelope({\n        fin: { reason, ...(message !== undefined && { message }) },\n      });\n      finished = true;\n      for (const stream of [...streams]) stream.close();\n      await tick();\n    },\n    get clientId() {\n      return clientId;\n    },\n    get attached() {\n      return streams.size > 0;\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/wire/meta.d.ts

@@ -3,9 +3,11 @@ type StatewireMetaEntry = {
   path: (string | number)[];
   type: string;
 };
-/** 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. */
-declare 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. */
+declare const reviveValue: (value: unknown, meta: unknown, { rejectUnknown }?: {
+  rejectUnknown?: boolean | undefined;
+}) => unknown;
 declare const reviveOps: (ops: unknown[]) => unknown[];
 declare const reviveResponse: <T extends {
   payload?: unknown;

package/dist/wire/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","names":[],"sources":["../../src/wire/meta.ts"],"mappings":";KAEY;EACV;EACA;;;;cAiBW,cAAe,gBAAgB;cAwB/B,YAAa;cAOb,iBAAkB;EAAY;EAAmB;GAC5D,UAAU,MACT;;;cA+BU,eACX;EACG;EAAmB,OAAO;;;cAOlB,cACX;EACG;EAAgB,OAAO"}
+{"version":3,"file":"meta.d.ts","names":[],"sources":["../../src/wire/meta.ts"],"mappings":";KAEY;EACV;EACA;;;;cAiBW,cACX,gBACA,iBACA;;;cA6BW,YAAa;cAOb,iBAAkB;EAAY;EAAmB;GAC5D,UAAU,MACT;;;cA+BU,eACX;EACG;EAAmB,OAAO;;;cAOlB,cACX;EACG;EAAgB,OAAO"}

package/dist/wire/meta.js

@@ -4,14 +4,17 @@ const fault = (message) => {
 	throw new Error(`statewire: protocol error: ${message}`);
 };
 const isPath = (path) => Array.isArray(path) && path.every((seg) => typeof seg === "string" || 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. */
-const reviveValue = (value, meta) => {
+/** Revive meta-typed locations inside a wire value (in place). Clients skip
+* unknown types; hosts pass `rejectUnknown` to fault on them instead. */
+const reviveValue = (value, meta, { rejectUnknown = false } = {}) => {
 	if (!Array.isArray(meta)) return fault("meta must be an array");
 	for (const entry of meta) {
 		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 === void 0) return fault(`meta path ${path.join(".")} does not resolve`);
 		if (typeof walked.leaf !== "string") return fault(`meta path ${path.join(".")} must name a string`);

package/dist/wire/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","names":["walkStatePath","StatewireMetaEntry","path","type","fault","message","Error","isPath","Array","isArray","every","seg","Number","isInteger","reviveValue","value","meta","entry","walked","undefined","join","leaf","date","Date","isNaN","getTime","parent","Record","key","reviveOps","ops","map","op","rest","reviveResponse","payload","response","T","walkDates","node","push","toISOString","item","i","Object","fromEntries","keys","encodeParams","params","encoded","param","length","encodeValue"],"sources":["../../src/wire/meta.ts"],"sourcesContent":["import { walkStatePath } from \"../util/statePath\";\n\nexport type StatewireMetaEntry = {\n  path: (string | number)[];\n  type: string;\n};\n\nconst fault = (message: string): never => {\n  throw new Error(`statewire: protocol error: ${message}`);\n};\n\nconst isPath = (path: unknown): path is (string | number)[] =>\n  Array.isArray(path) &&\n  path.every(\n    (seg) =>\n      typeof seg === \"string\" ||\n      (typeof seg === \"number\" && Number.isInteger(seg)),\n  );\n\n/** Revive meta-typed locations inside a wire value (in place). Unknown types\n * are skipped; a path that does not resolve to a valid target faults. */\nexport const reviveValue = (value: unknown, meta: unknown): unknown => {\n  if (!Array.isArray(meta)) return fault(\"meta must be an array\");\n  for (const entry of meta as { path?: unknown; type?: unknown }[]) {\n    const path =\n      typeof entry === \"object\" && entry !== null ? entry.path : null;\n    if (!isPath(path)) return fault(\"meta entry must carry a path array\");\n    if (entry.type !== \"date\") continue;\n    const walked = walkStatePath(value, path, \"resolve\");\n    if (walked === undefined) {\n      return fault(`meta path ${path.join(\".\")} does not resolve`);\n    }\n    if (typeof walked.leaf !== \"string\") {\n      return fault(`meta path ${path.join(\".\")} must name a string`);\n    }\n    const date = new Date(walked.leaf);\n    if (Number.isNaN(date.getTime())) {\n      return fault(`invalid date at meta path ${path.join(\".\")}`);\n    }\n    if (walked.parent === undefined) return date;\n    (walked.parent as Record<string | number, unknown>)[walked.key] = date;\n  }\n  return value;\n};\n\nexport const reviveOps = (ops: unknown[]): unknown[] =>\n  ops.map((op) => {\n    if (typeof op !== \"object\" || op === null || !(\"meta\" in op)) return op;\n    const { meta, ...rest } = op as { meta: unknown; value?: unknown };\n    return { ...rest, value: reviveValue(rest.value, meta) };\n  });\n\nexport const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(\n  response: T,\n): T => {\n  if (response.meta === undefined) return response;\n  const { meta, ...rest } = response;\n  return { ...rest, payload: reviveValue(rest.payload, meta) } as T;\n};\n\nconst walkDates = (\n  node: unknown,\n  path: (string | number)[],\n  meta: StatewireMetaEntry[],\n): unknown => {\n  if (node instanceof Date) {\n    meta.push({ path, type: \"date\" });\n    return node.toISOString();\n  }\n  if (Array.isArray(node)) {\n    return node.map((item, i) => walkDates(item, [...path, i], meta));\n  }\n  if (typeof node === \"object\" && node !== null) {\n    return Object.fromEntries(\n      Object.keys(node).map((key) => [\n        key,\n        walkDates((node as Record<string, unknown>)[key], [...path, key], meta),\n      ]),\n    );\n  }\n  return node;\n};\n\n/** Encode Date instances inside command params as canonical ISO strings,\n * recording their paths (starting at the param index) in meta. */\nexport const encodeParams = (\n  params: readonly unknown[],\n): { params: unknown[]; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = params.map((param, i) => walkDates(param, [i], meta));\n  return meta.length > 0 ? { params: encoded, meta } : { params: encoded };\n};\n\n/** Encode Date instances inside a wire value, recording their paths in meta. */\nexport const encodeValue = (\n  value: unknown,\n): { value: unknown; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = walkDates(value, [], meta);\n  return meta.length > 0 ? { value: encoded, meta } : { value: encoded };\n};\n"],"mappings":"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"}
+{"version":3,"file":"meta.js","names":["walkStatePath","StatewireMetaEntry","path","type","fault","message","Error","isPath","Array","isArray","every","seg","Number","isInteger","reviveValue","value","meta","rejectUnknown","entry","String","walked","undefined","join","leaf","date","Date","isNaN","getTime","parent","Record","key","reviveOps","ops","map","op","rest","reviveResponse","payload","response","T","walkDates","node","push","toISOString","item","i","Object","fromEntries","keys","encodeParams","params","encoded","param","length","encodeValue"],"sources":["../../src/wire/meta.ts"],"sourcesContent":["import { walkStatePath } from \"../util/statePath\";\n\nexport type StatewireMetaEntry = {\n  path: (string | number)[];\n  type: string;\n};\n\nconst fault = (message: string): never => {\n  throw new Error(`statewire: protocol error: ${message}`);\n};\n\nconst isPath = (path: unknown): path is (string | number)[] =>\n  Array.isArray(path) &&\n  path.every(\n    (seg) =>\n      typeof seg === \"string\" ||\n      (typeof seg === \"number\" && Number.isInteger(seg)),\n  );\n\n/** Revive meta-typed locations inside a wire value (in place). Clients skip\n * unknown types; hosts pass `rejectUnknown` to fault on them instead. */\nexport const reviveValue = (\n  value: unknown,\n  meta: unknown,\n  { rejectUnknown = false } = {},\n): unknown => {\n  if (!Array.isArray(meta)) return fault(\"meta must be an array\");\n  for (const entry of meta as { path?: unknown; type?: unknown }[]) {\n    const path =\n      typeof entry === \"object\" && entry !== null ? entry.path : null;\n    if (!isPath(path)) return fault(\"meta entry must carry a path array\");\n    if (entry.type !== \"date\") {\n      if (rejectUnknown)\n        return fault(`unknown meta type: ${String(entry.type)}`);\n      continue;\n    }\n    const walked = walkStatePath(value, path, \"resolve\");\n    if (walked === undefined) {\n      return fault(`meta path ${path.join(\".\")} does not resolve`);\n    }\n    if (typeof walked.leaf !== \"string\") {\n      return fault(`meta path ${path.join(\".\")} must name a string`);\n    }\n    const date = new Date(walked.leaf);\n    if (Number.isNaN(date.getTime())) {\n      return fault(`invalid date at meta path ${path.join(\".\")}`);\n    }\n    if (walked.parent === undefined) return date;\n    (walked.parent as Record<string | number, unknown>)[walked.key] = date;\n  }\n  return value;\n};\n\nexport const reviveOps = (ops: unknown[]): unknown[] =>\n  ops.map((op) => {\n    if (typeof op !== \"object\" || op === null || !(\"meta\" in op)) return op;\n    const { meta, ...rest } = op as { meta: unknown; value?: unknown };\n    return { ...rest, value: reviveValue(rest.value, meta) };\n  });\n\nexport const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(\n  response: T,\n): T => {\n  if (response.meta === undefined) return response;\n  const { meta, ...rest } = response;\n  return { ...rest, payload: reviveValue(rest.payload, meta) } as T;\n};\n\nconst walkDates = (\n  node: unknown,\n  path: (string | number)[],\n  meta: StatewireMetaEntry[],\n): unknown => {\n  if (node instanceof Date) {\n    meta.push({ path, type: \"date\" });\n    return node.toISOString();\n  }\n  if (Array.isArray(node)) {\n    return node.map((item, i) => walkDates(item, [...path, i], meta));\n  }\n  if (typeof node === \"object\" && node !== null) {\n    return Object.fromEntries(\n      Object.keys(node).map((key) => [\n        key,\n        walkDates((node as Record<string, unknown>)[key], [...path, key], meta),\n      ]),\n    );\n  }\n  return node;\n};\n\n/** Encode Date instances inside command params as canonical ISO strings,\n * recording their paths (starting at the param index) in meta. */\nexport const encodeParams = (\n  params: readonly unknown[],\n): { params: unknown[]; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = params.map((param, i) => walkDates(param, [i], meta));\n  return meta.length > 0 ? { params: encoded, meta } : { params: encoded };\n};\n\n/** Encode Date instances inside a wire value, recording their paths in meta. */\nexport const encodeValue = (\n  value: unknown,\n): { value: unknown; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = walkDates(value, [], meta);\n  return meta.length > 0 ? { value: encoded, meta } : { value: encoded };\n};\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statewire",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "State over the wire: snapshot-first delta streaming and command submission for any state and any command",
   "license": "MIT",
   "repository": {

package/src/client/connection.ts

@@ -11,9 +11,18 @@ export type Episode = {
   message?: string;
 };
 
+/** The terminal cmd verdict types; "applied" is the sole non-terminal type. */
+export const TERMINAL = [
+  "result",
+  "rejected",
+  "failed",
+  "crashed",
+  "expired",
+] as const;
+
 export type StatewireCmd = {
   seq: number;
-  type?: "applied" | "result" | "rejected" | "failed" | "crashed" | "expired";
+  type?: "applied" | (typeof TERMINAL)[number];
   code?: string;
   message?: string;
   payload?: unknown;
@@ -25,7 +34,7 @@ export type StatewireCmd = {
 export type StatewireSyn = {
   seq?: number;
   ctxSeq?: number;
-  record?: "fresh" | "resumed" | "ephemeral";
+  record?: "ephemeral";
   id?: string;
   idle?: boolean;
   retry?: number;
@@ -344,10 +353,7 @@ const settleFin = (c: Conn, fin: StatewireHost.Fin): AttemptOutcome => {
   }
   // An auth denial gets one immediate redial; a consecutive repeat parks as gone.
   const denial = finish.reason === "unauthorized";
-  const terminal =
-    finish.reason === "gone" ||
-    finish.reason === "superseded" ||
-    (denial && c.authDenials > 0);
+  const terminal = finish.reason === "gone" || (denial && c.authDenials > 0);
   if (denial) c.authDenials += 1;
   c.ctx.onFinish(terminal ? finish : { ...finish, reason: "error" });
   if (!terminal) {

package/src/client/session.ts

@@ -1,6 +1,7 @@
 import { useContext, useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
+import { TERMINAL } from "./connection";
 import type { StatewireCmd, StatewireSyn } from "./connection";
 import {
   encodeParams,
@@ -70,6 +71,7 @@ type AttachState = "detached" | "attached" | "finished";
 
 export type StatewireSessionOptions = {
   sessionStore?: StatewireClient.SessionStorage | undefined;
+  onSessionLost?: StatewireClient.OnSessionLost | undefined;
   onDone?: (() => void) | undefined;
 };
 
@@ -92,6 +94,7 @@ type Session = {
   durableSeq: number;
   resumeAt: number;
   idle: boolean;
+  onSessionLost: StatewireClient.OnSessionLost | undefined;
   onDone: (() => void) | undefined;
   ctxOps: unknown[] | undefined;
   ctxPending: CtxPending[];
@@ -252,14 +255,9 @@ const settleEntry = (
   }
 };
 
-const settleAll = (s: Session, detach: "unmount" | "gone" | "superseded") => {
-  const cause = (
-    {
-      unmount: "unmount",
-      gone: "stream-gone",
-      superseded: "superseded",
-    } as const
-  )[detach];
+const settleAll = (s: Session, detach: "unmount" | "gone") => {
+  const cause =
+    detach === "unmount" ? ("unmount" as const) : ("stream-gone" as const);
   const batch = s.pending;
   const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
     if (!entry.attempted) {
@@ -286,26 +284,30 @@ const restateContext = (s: Session) => {
   s.ctxPending.push({ seq, ops: s.ctxOps, posted: false });
 };
 
+const settleLost = (s: Session, entries: Pending[]) => {
+  for (const entry of entries) {
+    s.lifecycle?.onCovered?.(entry.inv);
+    settleEntry(s, entry, {
+      ok: false,
+      failure: { fate: "lost", cause: "session-lost" },
+    });
+  }
+};
+
 // The server-side record's dedup memory is gone: history that may have
 // reached a server settles lost — the new hello's snapshot is the only
 // truth about what survived — and never-attempted statements re-stamp
-// from 1 on the reset lane clocks.
-const resetRecord = (s: Session, clientId: string) => {
-  const survivors: Pending[] = [];
-  for (const entry of [...s.pending]) {
-    if (entry.attempted || entry.applied) {
-      s.lifecycle?.onCovered?.(entry.inv);
-      settleEntry(s, entry, {
-        ok: false,
-        failure: { fate: "lost", cause: "session-lost" },
-      });
-    } else {
-      survivors.push(entry);
-    }
-  }
+// on the adopted lane clocks.
+const rebaseRecord = (s: Session, adopt: () => void) => {
+  const held = [...s.pending];
+  const survivors = held.filter((p) => !p.attempted && !p.applied);
+  settleLost(
+    s,
+    held.filter((p) => p.attempted || p.applied),
+  );
   s.pending = [];
   s.durableSeq = 0;
-  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
+  adopt();
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
     enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
@@ -316,33 +318,17 @@ const resetRecord = (s: Session, clientId: string) => {
   void pump(s);
 };
 
+const resetRecord = (s: Session, clientId: string) =>
+  rebaseRecord(s, () =>
+    setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] }),
+  );
+
 // Another sharer replaced the record's identity: their reset settles our
 // attempted history and our survivors re-stamp on the stored clocks.
-const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) => {
-  const survivors: Pending[] = [];
-  for (const entry of [...s.pending]) {
-    if (entry.attempted || entry.applied) {
-      s.lifecycle?.onCovered?.(entry.inv);
-      settleEntry(s, entry, {
-        ok: false,
-        failure: { fate: "lost", cause: "session-lost" },
-      });
-    } else {
-      survivors.push(entry);
-    }
-  }
-  s.pending = [];
-  s.durableSeq = 0;
-  s.record = stored;
-  for (const old of survivors) {
-    s.lifecycle?.onCovered?.(old.inv);
-    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
-  }
-  restateContext(s);
-  publish(s);
-  wake(s);
-  void pump(s);
-};
+const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) =>
+  rebaseRecord(s, () => {
+    s.record = stored;
+  });
 
 // The record died with the attach: mint a fresh id for the next one.
 const ephemeralDetach = (s: Session) => {
@@ -365,42 +351,31 @@ const outcomeOf = (
   cmd: StatewireCmd,
 ):
   | { ok: true; payload: unknown }
-  | { ok: false; failure: StatewireClient.SendFailure } =>
-  cmd.type === "result"
-    ? { ok: true as const, payload: reviveResponse(cmd).payload }
-    : cmd.type === "rejected"
-      ? { ok: false as const, failure: rejectedFailure(reviveResponse(cmd)) }
-      : cmd.type === "failed"
-        ? {
-            ok: false as const,
-            failure: {
-              fate: "failed" as const,
-              cause: "server" as const,
-              ...(cmd.message !== undefined && { message: cmd.message }),
-            },
-          }
-        : cmd.type === "crashed"
-          ? {
-              ok: false as const,
-              failure: { fate: "crashed" as const, cause: "server" as const },
-            }
-          : cmd.type === "expired"
-            ? {
-                ok: false as const,
-                failure: {
-                  fate: "expired" as const,
-                  cause: "server" as const,
-                },
-              }
-            : protocolError(`unknown cmd type: ${String(cmd.type)}`);
-
-const TERMINAL_CMD_TYPES = new Set([
-  "result",
-  "rejected",
-  "failed",
-  "crashed",
-  "expired",
-]);
+  | { ok: false; failure: StatewireClient.SendFailure } => {
+  switch (cmd.type) {
+    case "result":
+      return { ok: true, payload: reviveResponse(cmd).payload };
+    case "rejected":
+      return { ok: false, failure: rejectedFailure(reviveResponse(cmd)) };
+    case "failed":
+      return {
+        ok: false,
+        failure: {
+          fate: "failed",
+          cause: "server",
+          ...(cmd.message !== undefined && { message: cmd.message }),
+        },
+      };
+    case "crashed":
+      return { ok: false, failure: { fate: "crashed", cause: "server" } };
+    case "expired":
+      return { ok: false, failure: { fate: "expired", cause: "server" } };
+    default:
+      return protocolError(`unknown cmd type: ${String(cmd.type)}`);
+  }
+};
+
+const TERMINAL_CMD_TYPES: ReadonlySet<string> = new Set(TERMINAL);
 
 const parkVerdict = (s: Session, cmd: StatewireCmd) => {
   if (!s.shared || !TERMINAL_CMD_TYPES.has(cmd.type!)) return;
@@ -473,24 +448,10 @@ const publishIngested = (s: Session) => {
   wake(s);
 };
 
-const RECORDS = ["fresh", "resumed", "ephemeral"];
-
-// Snap a resumed session's lane clocks onto the record: seqs above the stated
-// watermark were never admitted, so a stale restored clock re-stamps its
-// never-admitted statements consecutively after the watermark.
-const snapClocks = (s: Session, seqWm: number, ctxWm: number) => {
-  const tail = s.pending.filter((p) => p.seq > seqWm);
-  const cmdAligned =
-    tail.every((p, i) => p.seq === seqWm + 1 + i) &&
-    s.record.nextSeq === seqWm + tail.length + 1;
-  if (!cmdAligned) {
-    s.pending = s.pending.filter((p) => p.seq <= seqWm);
-    setRecord(s, { ...s.record, nextSeq: seqWm + 1 });
-    for (const old of tail) {
-      s.lifecycle?.onCovered?.(old.inv);
-      enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
-    }
-  }
+// A hello's cmd watermark may understate a durable record (cold host, tray
+// unloaded): held seqs resend as-is and the frame's answer arbitrates —
+// absorption where the record survived, a gap refusal where it did not.
+const snapCtxClock = (s: Session, ctxWm: number) => {
   const ctxAligned =
     s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) &&
     s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1;
@@ -500,39 +461,69 @@ const snapClocks = (s: Session, seqWm: number, ctxWm: number) => {
   }
 };
 
+// The refusal's watermarks are exact: every held statement above them was
+// never admitted by the live record, and the first unposted seq being beyond
+// watermark+1 proves the record that admitted the missing prefix is gone —
+// its history settles lost and the lane clocks restart at the watermarks.
+const sessionLostInner = (s: Session, seqWm: number, ctxWm: number) => {
+  const held = [...s.pending];
+  settleLost(s, held);
+  s.pending = [];
+  s.durableSeq = seqWm;
+  setRecord(s, {
+    clientId: s.record.clientId,
+    nextSeq: seqWm + 1,
+    ctxNextSeq: ctxWm + 1,
+    commands: [],
+  });
+  restateContext(s);
+  if (
+    held.length > 0 &&
+    s.onSessionLost?.(held.map((p) => p.inv)) === "requeue"
+  ) {
+    for (const old of held) {
+      enqueueInner(
+        s,
+        old.command,
+        old.inv.params,
+        () => {},
+        () => {},
+      );
+    }
+  }
+  publish(s);
+  wake(s);
+};
+
 const handleHello = (
   s: Session,
   { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
 ) => {
-  const record = syn.record ?? "fresh";
-  if (!RECORDS.includes(record)) {
-    protocolError(`unknown record: ${String(record)}`);
+  if (syn.record !== undefined && syn.record !== "ephemeral") {
+    protocolError(`unknown record: ${String(syn.record)}`);
   }
   ingestOps(s, ops);
   s.attach = "attached";
   s.attachEpoch += 1;
   s.frameFailures = 0;
   s.resumeAt = 0;
-  s.ephemeral = record === "ephemeral";
+  s.ephemeral = syn.record === "ephemeral";
   if (s.ephemeral) s.deactivated = true;
   const [attachCmd, attachCtx] = s.attachLaneSeqs;
   s.attachLaneSeqs = [new Set(), new Set()];
   const reconcile = () => {
-    if (record === "resumed") {
-      if (s.shared) adoptStored(s);
-      // Resending unsettled statements is exactly-once-safe: absorbed replays
-      // re-emit their stored verdicts (applied while still in flight).
-      for (const entry of s.pending) {
-        entry.posted = attachCmd.has(entry.seq);
-      }
-      const ctxWatermark = syn.ctxSeq ?? 0;
-      s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
-      for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
-      snapClocks(s, syn.seq ?? 0, ctxWatermark);
-      syncBacklogInner(s);
-    } else {
-      resetRecord(s, s.record.clientId);
+    if (s.shared) adoptStored(s);
+    // Resending unsettled statements is exactly-once-safe: absorbed replays
+    // re-emit their stored verdicts (applied while still in flight).
+    s.durableSeq = syn.seq ?? 0;
+    for (const entry of s.pending) {
+      entry.posted = attachCmd.has(entry.seq);
     }
+    const ctxWatermark = syn.ctxSeq ?? 0;
+    s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
+    for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
+    snapCtxClock(s, ctxWatermark);
+    syncBacklogInner(s);
     s.sessionKnown = true;
   };
   if (!s.shared || s.deactivated) {
@@ -557,8 +548,9 @@ const handleOps = (
   publishIngested(s);
 };
 
-// A {syn} refusal never settles: reconcile the resend queues against the
-// stated watermarks; retry present means wait, absent means resend now.
+// A retry-less {syn} refusal is the one session-loss verdict: a cmd gap
+// against its exact watermark settles the held history lost; a pushback
+// (retry present) or a gapless refusal only reconciles the resend queues.
 const handleRefusal = (s: Session, syn: StatewireSyn) => {
   const { seq, ctxSeq } = syn;
   if (typeof seq === "number") {
@@ -571,19 +563,30 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
   }
   if (typeof syn.retry === "number") {
     s.resumeAt = Date.now() + syn.retry;
+    wake(s);
+    void pump(s);
+    return;
   }
   const firstCmd = s.pending.find((p) => !p.posted);
   const firstCtx = s.ctxPending.find((c) => !c.posted);
-  const clocksAhead =
-    (typeof syn.seq === "number" &&
-      firstCmd !== undefined &&
-      firstCmd.seq > Math.max(syn.seq, s.durableSeq) + 1) ||
-    (typeof syn.ctxSeq === "number" &&
-      firstCtx !== undefined &&
-      firstCtx.seq > syn.ctxSeq + 1);
-  // Clocks ahead of a record that cannot admit them: reattach first and let
-  // the hello's record arbitrate.
-  if (clocksAhead) s.transport?.connection.reconnect();
+  const cmdGap =
+    typeof seq === "number" &&
+    firstCmd !== undefined &&
+    firstCmd.seq > Math.max(seq, s.durableSeq) + 1;
+  const ctxGap =
+    typeof ctxSeq === "number" &&
+    firstCtx !== undefined &&
+    firstCtx.seq > ctxSeq + 1;
+  if (cmdGap || ctxGap) {
+    void transact(s, () => {
+      if (cmdGap) sessionLostInner(s, seq!, ctxSeq ?? 0);
+      else snapCtxClock(s, ctxSeq!);
+    }).then(() => {
+      wake(s);
+      void pump(s);
+    });
+    return;
+  }
   wake(s);
   void pump(s);
 };
@@ -597,11 +600,7 @@ const handleDetach = (s: Session) => {
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
   if (reason === "evicted" || reason === "error") return;
   s.attach = "finished";
-  // Superseded over shared storage: the superseder resends our backlog and
-  // parks the verdicts; our promises settle from the observed record.
-  if (!(s.shared && reason === "superseded")) {
-    settleAll(s, reason === "superseded" ? "superseded" : "gone");
-  }
+  settleAll(s, "gone");
   publish(s);
   wake(s);
 };
@@ -819,8 +818,8 @@ const enqueue = (
   ).then(() => void pump(s));
 };
 
-// A stored command cannot be told from one that reached the server: attempted
-// keeps a fresh record settling it lost instead of replaying it blind.
+// A stored command may have reached a server: attempted settles it lost,
+// never aborted, when a channel death ends the session.
 const adoptStored = (s: Session) => {
   const known = new Set(s.pending.map((p) => p.seq));
   const stored = s.record.commands.filter((c) => !known.has(c.seq));
@@ -965,6 +964,7 @@ export const useStatewireSession = (
       durableSeq: 0,
       resumeAt: 0,
       idle: false,
+      onSessionLost: undefined,
       onDone: undefined,
       ctxOps: undefined,
       ctxPending: [],
@@ -1005,7 +1005,13 @@ export const useStatewireSession = (
     });
     return session;
   });
+  if ((store.lock !== undefined) !== (s.shared !== false)) {
+    throw new Error(
+      "statewire: session storage changed sharedness across renders — lock/subscribe must be present from the first render or never",
+    );
+  }
   s.store = store;
+  s.onSessionLost = options.onSessionLost;
   s.onDone = options.onDone;
   useEffect(() => {
     start(s);

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;