statewire 0.10.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.10.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) {