statewire 0.15.0 → 0.17.0

package/dist/client/session.js

@@ -1,19 +1,19 @@
+import { inRange, protocolOffers } from "../wire/protocol.js";
+import { encodeParams, encodeValue, reviveResponse, reviveValue } from "../wire/meta.js";
+import { applyDocumentOps, findDocument, mainDocument, resolveDocumentKey } from "../wire/documents.js";
 import { createMethodProxy } from "../util/methodProxy.js";
 import { StatewireSendError } from "../types.js";
 import { bindCommandsHost } from "../host/host.js";
-import { encodeParams, encodeValue, reviveResponse, reviveValue } from "../wire/meta.js";
 import "../wire/limits.js";
-import { SessionStorageContext, createMemorySessionStore } from "./sessionStore.js";
+import { DocumentStorageContext, SessionStorageContext, createMemorySessionStore } from "./sessionStore.js";
 import { backoff } from "./timing.js";
 import { TERMINAL } from "./connection.js";
-import { applyDocumentOps } from "../wire/documents.js";
 import { randomId } from "../util/randomId.js";
 import { useContext, useEffect, useState } from "@assistant-ui/tap/react-shim";
 //#region src/client/session.ts
 const protocolError = (message) => {
 	throw new Error(`statewire: protocol error: ${message}`);
 };
-const newClientId = () => `c-${randomId()}`;
 const rejectedSend = (failure) => {
 	const result = Promise.reject(new StatewireSendError(failure));
 	result.catch(() => {});
@@ -80,7 +80,21 @@ const transact = (s, fn) => {
 	const run = shared.txq.then(() => s.store.lock(async () => {
 		const stored = s.store.load();
 		if (stored !== null && stored.clientId !== s.record.clientId) adoptReset(s, stored);
-		else if (stored !== null) s.record = stored;
+		else if (stored !== null) {
+			s.record = stored;
+			if (stored.context !== void 0) {
+				const posted = new Set(s.ctxPending.filter((p) => p.posted).map((p) => p.seq));
+				s.ctxOps = stored.context.ops;
+				s.contextDocuments = applyDocumentOps({
+					mode: "mounted",
+					documents: /* @__PURE__ */ new Map()
+				}, stored.context.ops);
+				s.ctxPending = stored.context.pending.map((p) => ({
+					...p,
+					posted: posted.has(p.seq)
+				}));
+			}
+		}
 		fn();
 	}));
 	shared.txq = run.then(() => {}, () => {});
@@ -104,6 +118,8 @@ const retainFailedInner = (s, entry, failure) => {
 	setRecord(s, {
 		...s.record,
 		failed: [...s.record.failed ?? [], {
+			protocol: entry.command.protocol,
+			...entry.command.produced !== void 0 && { produced: entry.command.produced },
 			command: entry.command.method,
 			params: entry.command.params,
 			...entry.command.meta !== void 0 && { meta: entry.command.meta },
@@ -225,7 +241,7 @@ const adoptReset = (s, stored) => rebaseRecord(s, () => {
 const ephemeralDetach = (s) => {
 	s.ephemeral = false;
 	s.sessionKnown = false;
-	resetRecord(s, newClientId());
+	resetRecord(s, randomId());
 };
 const rejectedFailure = (cmd) => {
 	return {
@@ -295,8 +311,8 @@ const handleCmd = (s, cmd) => {
 		if (entry) cover(s, entry);
 		return;
 	}
-	parkVerdict(s, cmd);
 	if (!entry) return;
+	parkVerdict(s, cmd);
 	cover(s, entry);
 	settleEntry(s, entry, outcomeOf(cmd));
 };
@@ -325,17 +341,36 @@ const handleCmds = (s, cmds) => {
 	wake(s);
 };
 const ingestOps = (s, ops) => {
-	const applied = applyDocumentOps(s.documents, ops);
+	const applied = applyDocumentOps(s.documents, ops, s.selection?.protocols);
 	s.documents = applied;
-	s.canonical = applied.documents.get(0)?.value;
-	s.changed.push(...applied.changedPaths);
+	const next = s.selection === void 0 ? applied.documents.get(0)?.value : s.options.applicationProtocols === "*" ? Object.fromEntries([...applied.documents].map(([id, d]) => [`${d.protocol}:${d.key === null ? id : JSON.stringify(d.key)}`, d.value])) : mainDocument(applied, s.options.protocol ?? "default")?.value;
+	if (next !== s.canonical) s.changed.push(...applied.changedPaths.length ? applied.changedPaths : [[]]);
+	s.canonical = next;
+};
+const cacheDocuments = (s) => {
+	if (s.documentStore && s.selection) for (const document of s.documents.documents.values()) {
+		if (!document.protocol || !document.key) continue;
+		const key = resolveDocumentKey(document.key, s.options.keyPrefixes?.[document.protocol]);
+		const version = s.selection.protocols.find((p) => p.name === document.protocol)?.version;
+		if (key !== void 0 && version !== void 0) s.documentStore.save([
+			s.documentStore.namespace ?? "",
+			document.protocol,
+			...key
+		], {
+			version,
+			value: document.value
+		});
+	}
 };
 const publishIngested = (s) => {
 	publish(s);
+	cacheDocuments(s);
+	for (const listener of s.documentListeners) listener();
 	wake(s);
 };
 const snapCtxClock = (s, ctxWm) => {
 	if (!(s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) && s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1)) {
+		if (ctxWm > 0) throw new Error("statewire: context history is missing; use a new client id");
 		setRecord(s, {
 			...s.record,
 			ctxNextSeq: ctxWm + 1
@@ -351,17 +386,21 @@ const sessionLostInner = (s, seqWm, ctxWm) => {
 	setRecord(s, {
 		clientId: s.record.clientId,
 		nextSeq: seqWm + 1,
-		ctxNextSeq: ctxWm + 1,
+		ctxNextSeq: s.record.ctxNextSeq,
 		commands: [],
 		...s.record.failed !== void 0 && { failed: s.record.failed }
 	});
-	restateContext(s);
+	snapCtxClock(s, ctxWm);
 	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, { ops, syn }) => {
 	if (syn.record !== void 0 && syn.record !== "ephemeral") protocolError(`unknown record: ${String(syn.record)}`);
+	s.selection = syn.version === void 0 || syn.protocols === void 0 ? void 0 : {
+		version: syn.version,
+		protocols: syn.protocols
+	};
 	s.documents = {
 		mode: null,
 		documents: /* @__PURE__ */ new Map()
@@ -383,6 +422,7 @@ const handleHello = (s, { ops, syn }) => {
 		s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
 		for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
 		snapCtxClock(s, ctxWatermark);
+		if (s.ctxOps !== void 0) persistContext(s);
 		syncBacklogInner(s);
 		s.sessionKnown = true;
 	};
@@ -412,6 +452,7 @@ const handleRefusal = (s, syn) => {
 	if (typeof ctxSeq === "number") {
 		s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxSeq);
 		for (const c of s.ctxPending) c.posted = false;
+		if (s.ctxOps !== void 0) persistContext(s);
 	}
 	if (typeof syn.retry === "number") {
 		s.resumeAt = Date.now() + syn.retry;
@@ -471,10 +512,13 @@ const buildLanes = (s) => {
 				ops: c.ops,
 				seq: c.seq
 			})) },
-			...cmdEntries.length > 0 && { cmd: cmdEntries.map((p) => ({
-				...p.command,
-				seq: p.seq
-			})) }
+			...cmdEntries.length > 0 && { cmd: cmdEntries.map((p) => {
+				const { produced: _produced, ...command } = p.command;
+				return {
+					...command,
+					seq: p.seq
+				};
+			}) }
 		},
 		cmdEntries,
 		ctxEntries
@@ -593,6 +637,7 @@ const enqueueInner = (s, command, params, resolve, reject) => {
 		seq,
 		command,
 		inv: {
+			protocol: command.protocol,
 			method: command.method,
 			params,
 			ts: Date.now(),
@@ -646,11 +691,14 @@ const adoptStored = (s) => {
 	const stored = s.record.commands.filter((c) => !known.has(c.seq));
 	if (stored.length === 0) return;
 	for (const { seq, ...command } of stored) {
+		const offers = protocolOffers(s.options);
+		if (offers !== "*" && !offers.some((offer) => offer.name === command.protocol)) continue;
 		const params = command.meta === void 0 ? command.params : reviveValue([...command.params], command.meta);
 		const entry = {
 			seq,
 			command,
 			inv: {
+				protocol: command.protocol,
 				method: command.method,
 				params,
 				ts: Date.now(),
@@ -668,7 +716,7 @@ const adoptStored = (s) => {
 	}
 	s.pending.sort((a, b) => a.seq - b.seq);
 };
-const sendCommand = (s, method, params) => {
+const sendCommand = (s, method, params, protocol = s.options.protocol ?? "default") => {
 	if (!s.running) return rejectedSend({
 		fate: "aborted",
 		cause: "unmount"
@@ -680,6 +728,11 @@ const sendCommand = (s, method, params) => {
 	const result = new Promise((resolve, reject) => {
 		const { params: encoded, meta } = encodeParams(params);
 		enqueue(s, {
+			protocol,
+			produced: {
+				wire: s.options.wireVersion ?? { version: "2026-09-07" },
+				protocols: protocolOffers(s.options) === "*" && s.selection ? s.selection.protocols : protocolOffers(s.options)
+			},
 			method,
 			params: encoded,
 			...meta !== void 0 && { meta }
@@ -746,6 +799,8 @@ const retryFailed = (s, entry) => {
 			}
 			takeFailed(s, current);
 			enqueueInner(s, {
+				protocol: current.protocol,
+				...current.produced !== void 0 && { produced: current.produced },
 				method: current.command,
 				params: [...current.params],
 				...current.meta !== void 0 && { meta: current.meta }
@@ -765,59 +820,167 @@ const retryFailed = (s, entry) => {
 	result.catch(() => {});
 	return result;
 };
-const setContext = (s, value) => {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("statewire: context must be a plain object");
-	if (!s.running || isFinished(s)) return;
-	const { value: encoded, meta } = encodeValue(value);
-	const ops = [{
-		op: "replace",
-		path: [],
-		value: encoded,
-		...meta !== void 0 && { meta }
-	}];
+const contextSnapshot = (documents) => [...documents.documents].map(([doc, d]) => {
+	const encoded = encodeValue(d.value);
+	return {
+		op: "mount",
+		...doc === 0 ? {} : { doc },
+		protocol: d.protocol,
+		...d.main ? { main: true } : {},
+		...d.key === null ? {} : { key: d.key },
+		value: encoded.value,
+		...encoded.meta === void 0 ? {} : { meta: encoded.meta }
+	};
+});
+const persistContext = (s) => {
+	const ops = contextSnapshot(s.contextDocuments);
 	s.ctxOps = ops;
-	const mint = () => {
+	setRecord(s, {
+		...s.record,
+		context: {
+			ops,
+			pending: s.ctxPending.map(({ seq, ops }) => ({
+				seq,
+				ops
+			}))
+		}
+	});
+};
+const changeContext = (s, build) => {
+	if (!s.running || isFinished(s)) return;
+	const submit = () => {
+		if (!s.running || isFinished(s)) return;
+		const previous = s.record.context === void 0 ? s.contextDocuments : applyDocumentOps({
+			mode: "mounted",
+			documents: /* @__PURE__ */ new Map()
+		}, s.record.context.ops);
+		const operations = build(previous);
+		if (!operations.length) throw new Error("statewire: context operations must not be empty");
+		const offers = protocolOffers(s.options);
+		const protocols = s.selection?.protocols ?? (offers === "*" ? void 0 : offers);
+		s.contextDocuments = applyDocumentOps(previous, operations, protocols, true);
 		const seq = s.record.ctxNextSeq;
-		setRecord(s, {
-			...s.record,
-			ctxNextSeq: seq + 1
-		});
-		s.ctxPending.push({
+		s.ctxPending = [...s.ctxPending, {
 			seq,
-			ops,
+			ops: operations.map((op) => {
+				const value = op;
+				if (value["doc"] !== 0) return value;
+				const { doc: _doc, ...rest } = value;
+				return rest;
+			}),
 			posted: false
-		});
+		}];
+		s.record = {
+			...s.record,
+			ctxNextSeq: seq + 1
+		};
+		persistContext(s);
 	};
 	if (!s.shared) {
-		mint();
+		submit();
 		wake(s);
 		pump(s);
-		return;
-	}
-	transact(s, () => {
-		if (!s.running || isFinished(s)) return;
-		mint();
-	}).then(() => {
+	} else transact(s, submit).then(() => {
 		wake(s);
 		pump(s);
 	});
 };
+const updateContext = (s, operations) => changeContext(s, () => operations);
+const setContext = (s, value, protocol = s.options.protocol ?? "default") => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("statewire: context must be a plain object");
+	const encoded = encodeValue(value);
+	changeContext(s, (documents) => {
+		const found = [...documents.documents].find(([, d]) => d.protocol === protocol && d.main);
+		const doc = found?.[0] ?? Math.max(-1, ...documents.documents.keys()) + 1;
+		return [{
+			...found === void 0 ? {
+				op: "mount",
+				protocol,
+				main: true
+			} : {
+				op: "replace",
+				path: []
+			},
+			...doc === 0 ? {} : { doc },
+			value: encoded.value,
+			...encoded.meta === void 0 ? {} : { meta: encoded.meta }
+		}];
+	});
+};
+const documentSource = (s) => ({
+	get: (protocol, key, prefix = s.options.keyPrefixes?.[protocol]) => {
+		const mounted = findDocument(s.documents, protocol, key, prefix);
+		if (mounted !== void 0) return mounted.value;
+		if (!s.documentStore || key === void 0) return void 0;
+		const absolute = resolveDocumentKey(key, prefix);
+		if (absolute === void 0) return void 0;
+		const cached = s.documentStore.load([
+			s.documentStore.namespace ?? "",
+			protocol,
+			...absolute
+		]);
+		if (cached === void 0) return void 0;
+		const offers = protocolOffers(s.options);
+		const offer = offers === "*" ? s.selection?.protocols.find((p) => p.name === protocol) : offers.find((p) => p.name === protocol);
+		return offer !== void 0 && inRange(cached.version, offer) ? cached.value : void 0;
+	},
+	list: () => s.documents.documents,
+	subscribe: (listener) => {
+		s.documentListeners.add(listener);
+		return () => {
+			s.documentListeners.delete(listener);
+		};
+	}
+});
+const invokeProtocol = (s, protocol, method, params) => sendCommand(s, method, params, protocol);
+const storedCommandCompatible = (command, current) => {
+	if (!command.produced || !command.protocol || !inRange(command.produced.wire.version, current.wire)) return false;
+	const previous = command.produced.protocols;
+	if (current.protocols === "*") return true;
+	if (previous === "*") return false;
+	const produced = previous.find((p) => p.name === command.protocol);
+	const offer = current.protocols.find((p) => p.name === command.protocol);
+	return produced !== void 0 && offer !== void 0 && inRange(produced.version, offer);
+};
 const useStatewireSession = (options) => {
 	const [defaultStore] = useState(createMemorySessionStore);
 	const mounted = useContext(SessionStorageContext);
+	const documentStore = useContext(DocumentStorageContext);
 	if (options.sessionStore !== void 0 && mounted !== void 0) throw new Error("statewire: session storage is set twice — drop the transport's sessionStore or the client's storage.session");
 	const store = options.sessionStore ?? mounted ?? defaultStore;
 	if (store.lock === void 0 !== (store.subscribe === void 0)) throw new Error("statewire: session storage must provide lock and subscribe together");
 	const [s] = useState(() => {
-		const stored = store.load();
+		let stored = store.load();
+		if (stored !== null && !Array.isArray(stored.commands)) throw new Error("statewire: session storage loaded a record without a commands array");
+		const current = {
+			wire: options.wireVersion ?? { version: "2026-09-07" },
+			protocols: protocolOffers(options)
+		};
+		if (stored !== null && !stored.commands.every((command_0) => storedCommandCompatible(command_0, current))) {
+			if (!store.migrate) throw new Error("statewire: stored commands require a storage migration");
+			stored = store.migrate(stored, current);
+			if (stored !== null && !stored.commands.every((command) => storedCommandCompatible(command, current))) throw new Error("statewire: migrated commands are incompatible");
+			if (stored !== null) store.save(stored);
+		}
 		if (stored !== null && !Array.isArray(stored.commands)) throw new Error("statewire: session storage loaded a record without a commands array");
+		const record = stored ?? {
+			clientId: randomId(),
+			nextSeq: 1,
+			ctxNextSeq: 1,
+			commands: []
+		};
+		if (stored === null) store.save(record);
 		const session = {
-			record: stored ?? {
-				clientId: newClientId(),
-				nextSeq: 1,
-				ctxNextSeq: 1,
-				commands: []
-			},
+			options,
+			selection: void 0,
+			contextDocuments: stored?.context === void 0 ? {
+				mode: "mounted",
+				documents: /* @__PURE__ */ new Map()
+			} : applyDocumentOps({
+				mode: "mounted",
+				documents: /* @__PURE__ */ new Map()
+			}, stored.context.ops),
+			record,
 			ctx: {
 				get clientId() {
 					return session.record.clientId;
@@ -833,6 +996,7 @@ const useStatewireSession = (options) => {
 			},
 			recordPersisted: stored !== null,
 			store,
+			documentStore,
 			shared: store.lock !== void 0 ? {
 				txq: Promise.resolve(),
 				parked: [],
@@ -846,13 +1010,17 @@ const useStatewireSession = (options) => {
 			idle: false,
 			onSessionLost: void 0,
 			onDone: void 0,
-			ctxOps: void 0,
-			ctxPending: [],
+			ctxOps: stored?.context?.ops,
+			ctxPending: stored?.context?.pending.map((p) => ({
+				...p,
+				posted: false
+			})) ?? [],
 			lanesOnAttach: false,
 			attachLaneSeqs: [/* @__PURE__ */ new Set(), /* @__PURE__ */ new Set()],
 			frameFailures: 0,
 			pending: [],
 			canonical: void 0,
+			documentListeners: /* @__PURE__ */ new Set(),
 			documents: {
 				mode: null,
 				documents: /* @__PURE__ */ new Map()
@@ -886,9 +1054,22 @@ const useStatewireSession = (options) => {
 		return session;
 	});
 	if (store.lock !== void 0 !== (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.options = options;
 	s.store = store;
+	s.documentStore = documentStore;
 	s.onSessionLost = options.onSessionLost;
 	s.onDone = options.onDone;
+	const keyPrefixes = JSON.stringify(options.keyPrefixes);
+	useEffect(() => {
+		cacheDocuments(s);
+	}, [
+		s,
+		documentStore,
+		keyPrefixes
+	]);
+	useEffect(() => documentStore?.subscribe?.(() => {
+		for (const listener_1 of s.documentListeners) listener_1();
+	}), [s, documentStore]);
 	useEffect(() => {
 		start(s);
 		return () => stop(s);
@@ -896,6 +1077,6 @@ const useStatewireSession = (options) => {
 	return s;
 };
 //#endregion
-export { discardFailed, failedCommands, retryFailed, setContext, setTransport, useStatewireSession };
+export { discardFailed, documentSource, failedCommands, invokeProtocol, retryFailed, setContext, setTransport, updateContext, useStatewireSession };
 
 //# sourceMappingURL=session.js.map