iterate 0.2.6 → 0.3.0

package/dist/durable-object-processor-durability-CNsTjAJS.mjs

@@ -0,0 +1,205 @@
+import { F as isStreamIdMismatchError, M as StreamIdMismatchError, d as STREAM_PROCESSOR_REVIVED_EVENT_TYPE, r as ProcessorKeepalive } from "./stream-processor-keepalive-DAQTP6m3.mjs";
+//#region src/processors/durable-object-processor-durability.ts
+/** The two-cursor progress record ({@link ProcessorProgress}). */
+const processorProgressKey = (name) => `stream-processor:${name}:progress`;
+/** The per-runner keepalive record ({@link KeepaliveRecord}). */
+const processorKeepaliveKey = (name) => `stream-processor:${name}:keepalive`;
+function isStreamKeepaliveRecord(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return Number.isInteger(candidate.revivals) && (candidate.revivals ?? -1) >= 0 && typeof candidate.lastRevivalAt === "number" && Number.isFinite(candidate.lastRevivalAt) && typeof candidate.version === "string" && candidate.version.trim().length > 0 && (candidate.armedAtMs === null || typeof candidate.armedAtMs === "number" && Number.isFinite(candidate.armedAtMs)) && typeof candidate.streamId === "string" && candidate.streamId.trim().length > 0;
+}
+function sameKeepaliveAttempt(stored, streamId, attempt) {
+	return stored.streamId === streamId && stored.revivals === attempt.revivals && stored.lastRevivalAt === attempt.lastRevivalAt && stored.version === attempt.version && stored.armedAtMs === attempt.armedAtMs;
+}
+/**
+* The runner's durable progress store over DO KV (`storage.kv` — synchronous,
+* single-threaded isolate, so read-check-write is atomic without awaits).
+*/
+function durableObjectProgressStore(args) {
+	const { storage, name } = args;
+	const progressKey = processorProgressKey(name);
+	const cachedProgress = (progress) => {
+		const reductionCache = args.reductionCache;
+		if (!reductionCache || reductionCache.shouldCacheReduction(progress.reduction.state)) return progress;
+		return {
+			...progress,
+			reduction: {
+				...progress.reduction,
+				reducedThroughOffset: 0,
+				state: reductionCache.initialState()
+			}
+		};
+	};
+	return {
+		read: () => storage.kv.get(progressKey),
+		commit: (progress, opts) => {
+			const persisted = storage.kv.get(progressKey);
+			if (persisted?.streamId !== opts.expectedStreamId) throw new Error(`stream processor "${name}" progress commit fenced: expected stream ID ${String(opts.expectedStreamId)}, persisted ${String(persisted?.streamId)} — the stream lifetime changed after this continuation began`);
+			const persistedRevision = persisted?.processing.cursorRevision ?? 0;
+			if (opts.expectedCursorRevision !== persistedRevision) throw new Error(`stream processor "${name}" progress commit fenced: expected cursorRevision ${opts.expectedCursorRevision}, persisted ${persistedRevision} — a cursor rewind landed after this continuation began`);
+			if (persisted !== void 0 && progress.processing.acknowledgedThroughOffset < persisted.processing.acknowledgedThroughOffset && progress.processing.cursorRevision <= persistedRevision) throw new Error(`stream processor "${name}" progress commit fenced: acknowledgedThroughOffset would move backward (${persisted.processing.acknowledgedThroughOffset} -> ${progress.processing.acknowledgedThroughOffset}) without a cursorRevision bump — a stale incarnation is rolling the cursor back`);
+			storage.kv.put(progressKey, cachedProgress(progress));
+		},
+		replaceForStream: (progress, opts) => {
+			const persisted = storage.kv.get(progressKey);
+			if (persisted?.streamId !== opts.expectedStreamId || persisted.processing.cursorRevision !== opts.expectedCursorRevision) throw new Error(`stream processor "${name}" stream replacement fenced: expected ${opts.expectedStreamId}@${opts.expectedCursorRevision}, persisted ${String(persisted?.streamId)}@${persisted?.processing.cursorRevision ?? 0}`);
+			args.resetForStream?.();
+			storage.kv.delete(processorKeepaliveKey(name));
+			storage.kv.put(progressKey, cachedProgress(progress));
+		}
+	};
+}
+/**
+* The runner's recovery adapter for a Durable Object: wraps ONE
+* {@link ProcessorKeepalive} for THIS runner (per-runner recovery identity, so
+* a revival names exactly which processor owed work). The keepalive machinery
+* — mark-before-work, bounded backoff, quiet-clean reset,
+* deploy-version reset, wedged-work detection — is reused wholesale, never
+* reimplemented.
+*
+* DO-shaped seams are INJECTED, not reached for:
+*   - `armAlarm` — the hosting registry's alarm slice for this runner. A DO
+*     has ONE alarm; the registry merges every runner's desire (plus its own)
+*     and arms the earliest, exactly like the host's `setAlarmSlice`. This
+*     adapter never touches `storage.setAlarm`.
+*   - `waitUntil` — calls the hosting DO's `ctx.waitUntil`, keeping the
+*     incarnation alive while tracked work runs.
+*
+* Revival appends the core `stream/processor-revived` fact (ONE type for
+* every processor — {@link STREAM_PROCESSOR_REVIVED_EVENT_TYPE}; the payload's
+* `processorSlug` and the idempotency key carry the per-processor identity)
+* to the stream and STOPS: the append wakes the source stream's event sender (its
+* `woken` handlers cold-boot the stream DO if the deploy evicted it too), and
+* wake-mode delivery reaches head and guarantees a turn: either the contract
+* consumes the fact and receives it, or the runner supplies its eventless
+* `processEvent(event: null, caughtUp: true)` pass. No self-driven catch-up
+* here, unlike the host's `catchUpInternal` loop: delivery has ONE entrypoint.
+*
+* Construction re-issues a persisted armed desire through `armAlarm` (the
+* host's boot-time reconcile): a platform `setAlarm` that failed after the KV
+* record committed — or an eviction in the fire→re-arm window — would
+* otherwise leave the only thing that revives this DO permanently lost.
+*/
+function durableObjectRecovery(args) {
+	const now = args.now ?? (() => Date.now());
+	const recordKey = processorKeepaliveKey(args.name);
+	const progressKey = processorProgressKey(args.name);
+	const readProgress = () => args.storage.kv.get(progressKey);
+	const discardStoredRecord = (reason) => {
+		args.storage.kv.delete(recordKey);
+		args.armAlarm(null);
+		console.warn(`stream processor "${args.name}" discarded its recovery record: ${reason}`);
+	};
+	const readStoredRecord = (context) => {
+		const value = args.storage.kv.get(recordKey);
+		if (value === void 0) return void 0;
+		if (!isStreamKeepaliveRecord(value)) {
+			discardStoredRecord(`invalid record found while ${context}`);
+			return;
+		}
+		return value;
+	};
+	const requireProgressStreamId = () => {
+		const streamId = readProgress()?.streamId;
+		if (streamId === void 0 || streamId.trim().length === 0) throw new Error(`stream processor "${args.name}" cannot arm recovery before its stream lifetime is bound`);
+		return streamId;
+	};
+	const assertProgressStreamId = (expectedStreamId) => {
+		const currentStreamId = readProgress()?.streamId;
+		if (currentStreamId !== expectedStreamId) throw new StreamIdMismatchError(`stream processor "${args.name}" recovery belongs to stream ID ${expectedStreamId}, but current progress belongs to ${String(currentStreamId)}`);
+	};
+	const readCurrentStoredRecord = (context) => {
+		const record = readStoredRecord(context);
+		if (record === void 0) return void 0;
+		const progressStreamId = readProgress()?.streamId;
+		if (progressStreamId !== record.streamId) {
+			discardStoredRecord(`record belongs to stream ID ${record.streamId}, current progress belongs to ${String(progressStreamId)}`);
+			return;
+		}
+		return record;
+	};
+	const appendRevived = async (streamId, record) => {
+		assertProgressStreamId(streamId);
+		await args.stream.appendIfStreamId({
+			streamId,
+			events: [{
+				type: STREAM_PROCESSOR_REVIVED_EVENT_TYPE,
+				idempotencyKey: `processor-revived:${args.name}@${record.version}:${record.revivals}:${record.lastRevivalAt}`,
+				payload: {
+					processorSlug: args.name,
+					revivals: record.revivals,
+					version: record.version
+				}
+			}]
+		});
+	};
+	let activeKeepalive;
+	const keepaliveFor = (streamId) => {
+		if (activeKeepalive?.streamId === streamId) return activeKeepalive.keepalive;
+		const readRecord = () => {
+			const record = readCurrentStoredRecord("reading it");
+			return record?.streamId === streamId ? record : void 0;
+		};
+		const keepalive = new ProcessorKeepalive({
+			now,
+			readRecord,
+			writeRecord: (record) => {
+				assertProgressStreamId(streamId);
+				const persisted = readStoredRecord("arming recovery");
+				if (persisted !== void 0 && persisted.streamId !== streamId) throw new StreamIdMismatchError(`stream processor "${args.name}" cannot arm recovery for stream ID ${streamId} over the record for ${persisted.streamId}`);
+				args.storage.kv.put(recordKey, {
+					...record,
+					streamId
+				});
+			},
+			armAlarm: (atMs) => args.armAlarm(atMs),
+			keepAlive: (work) => args.waitUntil(work),
+			revive: (record) => appendRevived(streamId, record),
+			discardFailedRevival: (error, record) => {
+				if (!isStreamIdMismatchError(error)) return false;
+				const stored = readStoredRecord("discarding a stale revival");
+				if (stored === void 0) args.armAlarm(null);
+				else if (sameKeepaliveAttempt(stored, streamId, record)) discardStoredRecord(`stream ID ${streamId} was replaced`);
+				return true;
+			},
+			appendFact: (event) => {
+				Promise.resolve().then(() => {
+					assertProgressStreamId(streamId);
+					return args.stream.appendIfStreamId({
+						streamId,
+						events: [event]
+					});
+				}).catch((error) => {
+					console.error(`stream processor "${args.name}" keepalive evidence append failed`, error);
+				});
+			},
+			version: args.version
+		});
+		activeKeepalive = {
+			streamId,
+			keepalive
+		};
+		return keepalive;
+	};
+	const recovery = {
+		keepAliveWhile: (work) => keepaliveFor(requireProgressStreamId()).track(work()),
+		handleAlarm: async () => {
+			const record = readCurrentStoredRecord("handling an alarm");
+			if (record === void 0) return;
+			await keepaliveFor(record.streamId).onAlarm();
+		},
+		resetBackoff: () => {
+			const record = readCurrentStoredRecord("resetting the backoff");
+			if (record === void 0) return;
+			keepaliveFor(record.streamId).resetBackoff();
+		}
+	};
+	const persisted = readCurrentStoredRecord("booting");
+	if (persisted !== void 0 && persisted.armedAtMs !== null) args.armAlarm(persisted.armedAtMs);
+	return recovery;
+}
+//#endregion
+export { processorProgressKey as i, durableObjectRecovery as n, processorKeepaliveKey as r, durableObjectProgressStore as t };
+
+//# sourceMappingURL=durable-object-processor-durability-CNsTjAJS.mjs.map

package/dist/durable-object-processor-durability-CNsTjAJS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-object-processor-durability-CNsTjAJS.mjs","names":[],"sources":["../src/processors/durable-object-processor-durability.ts"],"sourcesContent":["// The Cloudflare Durable Object implementations of the StreamProcessorRunner's\n// two durability adapters (stream-processor-runner.ts):\n//\n//   - `durableObjectProgressStore` — the CAS-fenced two-cursor\n//     {@link ProcessorProgressStore} over the DO's synchronous KV facade.\n//   - `durableObjectRecovery` — the {@link ProcessorRecovery} adapter for a\n//     durable processor that owns background work: ONE ProcessorKeepalive per\n//     runner, storage-backed per registered NAME, with the DO-shaped seams\n//     (alarm slice, waitUntil) INJECTED so nothing here touches\n//     `storage.setAlarm` or a Cloudflare ctx directly.\n//\n// This file is deliberately runtime-light so its tests run in plain-node\n// vitest over an in-memory `storage.kv` fake\n// (durable-object-processor-durability.test.ts).\n\nimport type { ProcessorStream } from \"./stream-handle.ts\";\nimport { STREAM_PROCESSOR_REVIVED_EVENT_TYPE } from \"./processor-contracts.ts\";\nimport { isStreamIdMismatchError, StreamIdMismatchError } from \"./rpc-types.ts\";\nimport { ProcessorKeepalive, type KeepaliveRecord } from \"./stream-processor-keepalive.ts\";\nimport type {\n  ProcessorProgress,\n  ProcessorProgressStore,\n  ProcessorRecovery,\n} from \"./stream-processor-runner.ts\";\n\n// -----------------------------------------------------------------------------\n// Key layout. Per registered NAME (the subscription name, which equals the\n// contract slug — one identity), all under the `stream-processor:` prefix.\n// -----------------------------------------------------------------------------\n\n/** The two-cursor progress record ({@link ProcessorProgress}). */\nexport const processorProgressKey = (name: string) => `stream-processor:${name}:progress`;\n\n/** The per-runner keepalive record ({@link KeepaliveRecord}). */\nexport const processorKeepaliveKey = (name: string) => `stream-processor:${name}:keepalive`;\n\n/** A recovery alarm belongs to one stream lifetime, not merely one path. */\ntype StreamKeepaliveRecord = KeepaliveRecord & { streamId: string };\n\nfunction isStreamKeepaliveRecord(value: unknown): value is StreamKeepaliveRecord {\n  if (typeof value !== \"object\" || value === null) return false;\n  const candidate = value as Partial<StreamKeepaliveRecord>;\n  return (\n    Number.isInteger(candidate.revivals) &&\n    (candidate.revivals ?? -1) >= 0 &&\n    typeof candidate.lastRevivalAt === \"number\" &&\n    Number.isFinite(candidate.lastRevivalAt) &&\n    typeof candidate.version === \"string\" &&\n    candidate.version.trim().length > 0 &&\n    (candidate.armedAtMs === null ||\n      (typeof candidate.armedAtMs === \"number\" && Number.isFinite(candidate.armedAtMs))) &&\n    typeof candidate.streamId === \"string\" &&\n    candidate.streamId.trim().length > 0\n  );\n}\n\nfunction sameKeepaliveAttempt(\n  stored: StreamKeepaliveRecord,\n  streamId: string,\n  attempt: KeepaliveRecord,\n): boolean {\n  return (\n    stored.streamId === streamId &&\n    stored.revivals === attempt.revivals &&\n    stored.lastRevivalAt === attempt.lastRevivalAt &&\n    stored.version === attempt.version &&\n    stored.armedAtMs === attempt.armedAtMs\n  );\n}\n\n/**\n * The runner's durable progress store over DO KV (`storage.kv` — synchronous,\n * single-threaded isolate, so read-check-write is atomic without awaits).\n */\nexport function durableObjectProgressStore<State>(args: {\n  storage: DurableObjectStorage;\n  /** The registered processor name (subscription name = contract slug) —\n   * keys the progress record. */\n  name: string;\n  /** Synchronously clear related projections when the source stream is replaced. */\n  resetForStream?: () => void;\n  /**\n   * An optional bounded reduction cache. Processing cursors always remain\n   * durable; a cold runner refolds reduce-only from initialState when the\n   * predicate declines a large cache.\n   */\n  reductionCache?: {\n    shouldCacheReduction(state: State): boolean;\n    initialState(): State;\n  };\n}): ProcessorProgressStore<State> {\n  const { storage, name } = args;\n  const progressKey = processorProgressKey(name);\n  const cachedProgress = (progress: ProcessorProgress<State>): ProcessorProgress<State> => {\n    const reductionCache = args.reductionCache;\n    if (!reductionCache || reductionCache.shouldCacheReduction(progress.reduction.state))\n      return progress;\n    return {\n      ...progress,\n      reduction: {\n        ...progress.reduction,\n        reducedThroughOffset: 0,\n        state: reductionCache.initialState(),\n      },\n    };\n  };\n\n  return {\n    read: () => storage.kv.get<ProcessorProgress<State>>(progressKey),\n    commit: (progress, opts) => {\n      // CAS fence: read-check-write with NO intervening awaits — DO storage is\n      // synchronous and the isolate single-threaded, so this whole block is\n      // atomic. An absent record reads as revision 0.\n      const persisted = storage.kv.get<ProcessorProgress<State>>(progressKey);\n      if (persisted?.streamId !== opts.expectedStreamId) {\n        throw new Error(\n          `stream processor \"${name}\" progress commit fenced: expected stream ID ` +\n            `${String(opts.expectedStreamId)}, persisted ${String(persisted?.streamId)} — ` +\n            `the stream lifetime changed after this continuation began`,\n        );\n      }\n      const persistedRevision = persisted?.processing.cursorRevision ?? 0;\n      if (opts.expectedCursorRevision !== persistedRevision) {\n        throw new Error(\n          `stream processor \"${name}\" progress commit fenced: expected cursorRevision ` +\n            `${opts.expectedCursorRevision}, persisted ${persistedRevision} — ` +\n            `a cursor rewind landed after this continuation began`,\n        );\n      }\n      // MONOTONIC fence: the revision CAS alone cannot stop a stale\n      // incarnation at the SAME revision from rolling acknowledgement (and\n      // state) backward past progress a newer incarnation already committed —\n      // re-running effects that were durably acknowledged. Only an explicit\n      // revision-bumping cursor rewind may move acked backward.\n      if (\n        persisted !== undefined &&\n        progress.processing.acknowledgedThroughOffset <\n          persisted.processing.acknowledgedThroughOffset &&\n        progress.processing.cursorRevision <= persistedRevision\n      ) {\n        throw new Error(\n          `stream processor \"${name}\" progress commit fenced: acknowledgedThroughOffset would ` +\n            `move backward (${persisted.processing.acknowledgedThroughOffset} -> ` +\n            `${progress.processing.acknowledgedThroughOffset}) without a cursorRevision bump — ` +\n            `a stale incarnation is rolling the cursor back`,\n        );\n      }\n      storage.kv.put(progressKey, cachedProgress(progress));\n    },\n    replaceForStream: (progress, opts) => {\n      const persisted = storage.kv.get<ProcessorProgress<State>>(progressKey);\n      if (\n        persisted?.streamId !== opts.expectedStreamId ||\n        persisted.processing.cursorRevision !== opts.expectedCursorRevision\n      ) {\n        throw new Error(\n          `stream processor \"${name}\" stream replacement fenced: expected ` +\n            `${opts.expectedStreamId}@${opts.expectedCursorRevision}, persisted ` +\n            `${String(persisted?.streamId)}@${persisted?.processing.cursorRevision ?? 0}`,\n        );\n      }\n      // Old-lifetime recovery desires must not append revival facts into the\n      // recreated stream. A new obligation will arm a fresh record.\n      args.resetForStream?.();\n      storage.kv.delete(processorKeepaliveKey(name));\n      storage.kv.put(progressKey, cachedProgress(progress));\n    },\n  };\n}\n\n/**\n * The runner's recovery adapter for a Durable Object: wraps ONE\n * {@link ProcessorKeepalive} for THIS runner (per-runner recovery identity, so\n * a revival names exactly which processor owed work). The keepalive machinery\n * — mark-before-work, bounded backoff, quiet-clean reset,\n * deploy-version reset, wedged-work detection — is reused wholesale, never\n * reimplemented.\n *\n * DO-shaped seams are INJECTED, not reached for:\n *   - `armAlarm` — the hosting registry's alarm slice for this runner. A DO\n *     has ONE alarm; the registry merges every runner's desire (plus its own)\n *     and arms the earliest, exactly like the host's `setAlarmSlice`. This\n *     adapter never touches `storage.setAlarm`.\n *   - `waitUntil` — calls the hosting DO's `ctx.waitUntil`, keeping the\n *     incarnation alive while tracked work runs.\n *\n * Revival appends the core `stream/processor-revived` fact (ONE type for\n * every processor — {@link STREAM_PROCESSOR_REVIVED_EVENT_TYPE}; the payload's\n * `processorSlug` and the idempotency key carry the per-processor identity)\n * to the stream and STOPS: the append wakes the source stream's event sender (its\n * `woken` handlers cold-boot the stream DO if the deploy evicted it too), and\n * wake-mode delivery reaches head and guarantees a turn: either the contract\n * consumes the fact and receives it, or the runner supplies its eventless\n * `processEvent(event: null, caughtUp: true)` pass. No self-driven catch-up\n * here, unlike the host's `catchUpInternal` loop: delivery has ONE entrypoint.\n *\n * Construction re-issues a persisted armed desire through `armAlarm` (the\n * host's boot-time reconcile): a platform `setAlarm` that failed after the KV\n * record committed — or an eviction in the fire→re-arm window — would\n * otherwise leave the only thing that revives this DO permanently lost.\n */\nexport function durableObjectRecovery(args: {\n  storage: DurableObjectStorage;\n  /** The registered processor name (subscription name = contract slug) —\n   * keys the per-runner keepalive record and the revival fact's idempotency\n   * key, and fills the revival payload's `processorSlug`. */\n  name: string;\n  /** The processor's home stream: revived facts and crash-loop evidence land here. */\n  stream: ProcessorStream;\n  /** Worker deploy version; a change resets the keepalive's crash-loop budget\n   * (the antidote deploy). Pass `workerVersion(env)`. REQUIRED for the same\n   * reason the host requires it: a silent default could never take the\n   * version-reset code path. */\n  version: string;\n  /** The registry's alarm-slice seam for this runner (null = disarm). */\n  armAlarm: (atMs: number | null) => void;\n  /** The hosting DO's `ctx.waitUntil` — keeps the incarnation alive while\n   * tracked work runs. */\n  waitUntil: (work: Promise<unknown>) => void;\n  /** Injected clock for the test harness; production uses Date.now. */\n  now?: () => number;\n}): ProcessorRecovery {\n  const now = args.now ?? (() => Date.now());\n  const recordKey = processorKeepaliveKey(args.name);\n  const progressKey = processorProgressKey(args.name);\n  const readProgress = () => args.storage.kv.get<ProcessorProgress<unknown>>(progressKey);\n\n  const discardStoredRecord = (reason: string): void => {\n    args.storage.kv.delete(recordKey);\n    args.armAlarm(null);\n    console.warn(`stream processor \"${args.name}\" discarded its recovery record: ${reason}`);\n  };\n\n  const readStoredRecord = (context: string): StreamKeepaliveRecord | undefined => {\n    const value = args.storage.kv.get<unknown>(recordKey);\n    if (value === undefined) return undefined;\n    if (!isStreamKeepaliveRecord(value)) {\n      discardStoredRecord(`invalid record found while ${context}`);\n      return undefined;\n    }\n    return value;\n  };\n\n  const requireProgressStreamId = (): string => {\n    const streamId = readProgress()?.streamId;\n    if (streamId === undefined || streamId.trim().length === 0) {\n      throw new Error(\n        `stream processor \"${args.name}\" cannot arm recovery before its stream lifetime is bound`,\n      );\n    }\n    return streamId;\n  };\n\n  const assertProgressStreamId = (expectedStreamId: string): void => {\n    const currentStreamId = readProgress()?.streamId;\n    if (currentStreamId !== expectedStreamId) {\n      throw new StreamIdMismatchError(\n        `stream processor \"${args.name}\" recovery belongs to stream ID ${expectedStreamId}, ` +\n          `but current progress belongs to ${String(currentStreamId)}`,\n      );\n    }\n  };\n\n  const readCurrentStoredRecord = (context: string): StreamKeepaliveRecord | undefined => {\n    const record = readStoredRecord(context);\n    if (record === undefined) return undefined;\n    const progressStreamId = readProgress()?.streamId;\n    if (progressStreamId !== record.streamId) {\n      discardStoredRecord(\n        `record belongs to stream ID ${record.streamId}, current progress belongs to ${String(\n          progressStreamId,\n        )}`,\n      );\n      return undefined;\n    }\n    return record;\n  };\n\n  const appendRevived = async (streamId: string, record: KeepaliveRecord): Promise<void> => {\n    // Check both sides of the RPC boundary. The progress check stops an old\n    // local continuation immediately; appendIfStreamId closes the remaining\n    // race if the path is deleted and recreated while the RPC is in flight.\n    assertProgressStreamId(streamId);\n    await args.stream.appendIfStreamId({\n      streamId,\n      events: [\n        {\n          type: STREAM_PROCESSOR_REVIVED_EVENT_TYPE,\n          idempotencyKey:\n            `processor-revived:${args.name}` +\n            `@${record.version}:${record.revivals}:${record.lastRevivalAt}`,\n          payload: {\n            // The registered name IS the contract slug (one identity).\n            processorSlug: args.name,\n            revivals: record.revivals,\n            version: record.version,\n          },\n        },\n      ],\n    });\n  };\n\n  let activeKeepalive: { streamId: string; keepalive: ProcessorKeepalive } | undefined;\n\n  const keepaliveFor = (streamId: string): ProcessorKeepalive => {\n    if (activeKeepalive?.streamId === streamId) return activeKeepalive.keepalive;\n\n    const readRecord = (): KeepaliveRecord | undefined => {\n      const record = readCurrentStoredRecord(\"reading it\");\n      return record?.streamId === streamId ? record : undefined;\n    };\n    const keepalive = new ProcessorKeepalive({\n      now,\n      readRecord,\n      writeRecord: (record) => {\n        assertProgressStreamId(streamId);\n        const persisted = readStoredRecord(\"arming recovery\");\n        if (persisted !== undefined && persisted.streamId !== streamId) {\n          throw new StreamIdMismatchError(\n            `stream processor \"${args.name}\" cannot arm recovery for stream ID ${streamId} ` +\n              `over the record for ${persisted.streamId}`,\n          );\n        }\n        args.storage.kv.put(recordKey, { ...record, streamId } satisfies StreamKeepaliveRecord);\n      },\n      armAlarm: (atMs) => args.armAlarm(atMs),\n      keepAlive: (work) => args.waitUntil(work),\n      // Append the journaled fact and stop — the wake delivery of that fact is\n      // the recovery turn. Failures throw: the keepalive's breaker owns retries.\n      revive: (record) => appendRevived(streamId, record),\n      // A stream ID never becomes current again. Retrying its revival would\n      // wake forever, so discard exactly this attempt. If a newer lifetime or\n      // attempt already replaced the record, leave its alarm desire untouched.\n      discardFailedRevival: (error, record) => {\n        if (!isStreamIdMismatchError(error)) return false;\n        const stored = readStoredRecord(\"discarding a stale revival\");\n        if (stored === undefined) {\n          args.armAlarm(null);\n        } else if (sameKeepaliveAttempt(stored, streamId, record)) {\n          discardStoredRecord(`stream ID ${streamId} was replaced`);\n        }\n        return true;\n      },\n      // Best-effort journal evidence (crash-loop warnings). The stream-ID\n      // guard prevents an old lifetime's evidence from landing in its replacement.\n      appendFact: (event) => {\n        void Promise.resolve()\n          .then(() => {\n            assertProgressStreamId(streamId);\n            return args.stream.appendIfStreamId({ streamId, events: [event] });\n          })\n          .catch((error: unknown) => {\n            console.error(\n              `stream processor \"${args.name}\" keepalive evidence append failed`,\n              error,\n            );\n          });\n      },\n      version: args.version,\n    });\n    activeKeepalive = { streamId, keepalive };\n    return keepalive;\n  };\n\n  const recovery: ProcessorRecovery = {\n    // The host's wiring verbatim (stream-processor-host.ts:445): every\n    // registered closure — blocking, background, and the runner's whole-batch\n    // attempt — rides the keepalive, so \"the DO died owing work\" is exactly\n    // \"the DO died with the alarm armed\".\n    keepAliveWhile: (work) => keepaliveFor(requireProgressStreamId()).track(work()),\n    handleAlarm: async () => {\n      // Delegation IS the whole handler: every alarm action drives the\n      // injected seams from inside onAlarm before it returns — busy_rearmed\n      // re-arms at the lead, clean_disarmed disarms via armAlarm(null), the\n      // revival outcomes record + arm the backoff and run the revive hook (which\n      // appends the revived fact). The keepalive self-gates on its persisted\n      // armed time, so a fire belonging to another slice of the shared DO\n      // alarm is a no-op here — route every fire to every runner.\n      const record = readCurrentStoredRecord(\"handling an alarm\");\n      if (record === undefined) return;\n      await keepaliveFor(record.streamId).onAlarm();\n    },\n    // The operator's no-deploy antidote for a 3-strikes plateau: clear the\n    // crash-loop budget and pull the owed retry to the lead. Delegates\n    // wholesale to the keepalive (the budget's one owner).\n    resetBackoff: () => {\n      const record = readCurrentStoredRecord(\"resetting the backoff\");\n      if (record === undefined) return;\n      keepaliveFor(record.streamId).resetBackoff();\n    },\n  };\n\n  // Boot-time reconcile (the host's post-construction block verbatim): a\n  // fresh incarnation restores — and RE-ISSUES — the persisted alarm desire,\n  // so a lost platform alarm heals when the host next opens instead of never.\n  const persisted = readCurrentStoredRecord(\"booting\");\n  if (persisted !== undefined && persisted.armedAtMs !== null) {\n    args.armAlarm(persisted.armedAtMs);\n  }\n\n  return recovery;\n}\n"],"mappings":"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"}

package/dist/idempotency-DleloJNt.mjs

@@ -0,0 +1,28 @@
+//#region src/processors/idempotency.ts
+const IDEMPOTENCY_CONFLICT_FRAGMENT = " already names a different event at offset ";
+function idempotencyConflictMessage(idempotencyKey, existingOffset) {
+	return `idempotency key "${idempotencyKey}"${IDEMPOTENCY_CONFLICT_FRAGMENT}${existingOffset}`;
+}
+function isIdempotencyConflict(error) {
+	return (error instanceof Error ? error.message : String(error)).includes(IDEMPOTENCY_CONFLICT_FRAGMENT);
+}
+/** Whether a requested append names the SAME event an idempotency key already committed. */
+function sameIdempotentEvent(existing, requested) {
+	return existing.type === requested.type && jsonValuesEqual(existing.payload, requested.payload) && jsonValuesEqual(existing.metadata, requested.metadata) && existing.ephemeral === requested.ephemeral;
+}
+/** Structural JSON equality (key-order-insensitive). */
+function jsonValuesEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) || Array.isArray(right)) return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => jsonValuesEqual(value, right[index]));
+	if (typeof left === "object" && typeof right === "object" && left !== null && right !== null) {
+		const leftKeys = Object.keys(left).sort();
+		const rightKeys = Object.keys(right).sort();
+		if (leftKeys.length !== rightKeys.length) return false;
+		return leftKeys.every((key, index) => key === rightKeys[index] && jsonValuesEqual(left[key], right[key]));
+	}
+	return false;
+}
+//#endregion
+export { sameIdempotentEvent as i, isIdempotencyConflict as n, jsonValuesEqual as r, idempotencyConflictMessage as t };
+
+//# sourceMappingURL=idempotency-DleloJNt.mjs.map

package/dist/idempotency-DleloJNt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-DleloJNt.mjs","names":[],"sources":["../src/processors/idempotency.ts"],"sourcesContent":["// The Stream DO's idempotency semantics, importable: a same-key append is a\n// dedup ONLY when its body is structurally identical — otherwise it must be\n// rejected. Lives here so the production Stream Durable Object and the\n// MemoryStream test double share ONE predicate and cannot drift.\n\ntype EventBody = {\n  type: string;\n  payload?: unknown;\n  metadata?: unknown;\n  ephemeral?: boolean | undefined;\n};\n\n// The wording is a live wire contract: the rejection crosses Workers RPC,\n// which preserves the message but not class identity, so deployed processors\n// classify the conflict by this text. Mint with the builder, match with the\n// predicate — never spell the wording anywhere else.\nconst IDEMPOTENCY_CONFLICT_FRAGMENT = \" already names a different event at offset \";\n\nexport function idempotencyConflictMessage(idempotencyKey: string, existingOffset: number) {\n  return `idempotency key \"${idempotencyKey}\"${IDEMPOTENCY_CONFLICT_FRAGMENT}${existingOffset}`;\n}\n\nexport function isIdempotencyConflict(error: unknown) {\n  const message = error instanceof Error ? error.message : String(error);\n  return message.includes(IDEMPOTENCY_CONFLICT_FRAGMENT);\n}\n\n/** Whether a requested append names the SAME event an idempotency key already committed. */\nexport function sameIdempotentEvent(existing: EventBody, requested: EventBody): boolean {\n  return (\n    existing.type === requested.type &&\n    jsonValuesEqual(existing.payload, requested.payload) &&\n    jsonValuesEqual(existing.metadata, requested.metadata) &&\n    existing.ephemeral === requested.ephemeral\n  );\n}\n\n/** Structural JSON equality (key-order-insensitive). */\nexport function jsonValuesEqual(left: unknown, right: unknown): boolean {\n  if (Object.is(left, right)) return true;\n  if (Array.isArray(left) || Array.isArray(right)) {\n    return (\n      Array.isArray(left) &&\n      Array.isArray(right) &&\n      left.length === right.length &&\n      left.every((value, index) => jsonValuesEqual(value, right[index]))\n    );\n  }\n  if (typeof left === \"object\" && typeof right === \"object\" && left !== null && right !== null) {\n    const leftKeys = Object.keys(left).sort();\n    const rightKeys = Object.keys(right).sort();\n    if (leftKeys.length !== rightKeys.length) return false;\n    return leftKeys.every(\n      (key, index) =>\n        key === rightKeys[index] &&\n        jsonValuesEqual(\n          (left as Record<string, unknown>)[key],\n          (right as Record<string, unknown>)[key],\n        ),\n    );\n  }\n  return false;\n}\n"],"mappings":";AAgBA,MAAM,gCAAgC;AAEtC,SAAgB,2BAA2B,gBAAwB,gBAAwB;CACzF,OAAO,oBAAoB,eAAe,GAAG,gCAAgC;AAC/E;AAEA,SAAgB,sBAAsB,OAAgB;CAEpD,QADgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAA,CACtD,SAAS,6BAA6B;AACvD;;AAGA,SAAgB,oBAAoB,UAAqB,WAA+B;CACtF,OACE,SAAS,SAAS,UAAU,QAC5B,gBAAgB,SAAS,SAAS,UAAU,OAAO,KACnD,gBAAgB,SAAS,UAAU,UAAU,QAAQ,KACrD,SAAS,cAAc,UAAU;AAErC;;AAGA,SAAgB,gBAAgB,MAAe,OAAyB;CACtE,IAAI,OAAO,GAAG,MAAM,KAAK,GAAG,OAAO;CACnC,IAAI,MAAM,QAAQ,IAAI,KAAK,MAAM,QAAQ,KAAK,GAC5C,OACE,MAAM,QAAQ,IAAI,KAClB,MAAM,QAAQ,KAAK,KACnB,KAAK,WAAW,MAAM,UACtB,KAAK,OAAO,OAAO,UAAU,gBAAgB,OAAO,MAAM,MAAM,CAAC;CAGrE,IAAI,OAAO,SAAS,YAAY,OAAO,UAAU,YAAY,SAAS,QAAQ,UAAU,MAAM;EAC5F,MAAM,WAAW,OAAO,KAAK,IAAI,CAAC,CAAC,KAAK;EACxC,MAAM,YAAY,OAAO,KAAK,KAAK,CAAC,CAAC,KAAK;EAC1C,IAAI,SAAS,WAAW,UAAU,QAAQ,OAAO;EACjD,OAAO,SAAS,OACb,KAAK,UACJ,QAAQ,UAAU,UAClB,gBACG,KAAiC,MACjC,MAAkC,IACrC,CACJ;CACF;CACA,OAAO;AACT"}

package/dist/index.mjs

@@ -1,6 +1,6 @@
 //#region src/index.ts
 async function runCli() {
-	await (await import("./cli-DMS4kJph.mjs")).runCli();
+	await (await import("./cli-D0c-pDL_.mjs")).runCli();
 }
 //#endregion
 export { runCli };

package/dist/itx/api-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An OS deployment's `/api` WebSocket URL from its http(s) base — the ONE
+ * place that knows the path and the ws/wss protocol swap, shared by the
+ * shared session and the one-shot Node client.
+ */
+export declare function apiWebSocketUrl(baseUrl: string): URL;

package/dist/itx/itx-node-client.d.ts

@@ -0,0 +1,65 @@
+import { type RpcStub as CapnRpcStub } from "@iterate-com/capnweb";
+import type { Agent, ItxAuthCredentials, Project, Session, UnauthenticatedOs } from "../itx-api.generated.ts";
+export type ItxWebSocketMessage = [timestamp: number, direction: "in" | "out", data: unknown];
+type ConnectItxBaseInput = {
+    /** OS deployment base URL, e.g. the config's APP_CONFIG_BASE_URL. */
+    baseUrl: string;
+    /** Node WebSocket handshake headers, used by CLI/server callers with cookies. */
+    headers?: Record<string, string>;
+    /** Observe every decoded ws frame (e.g. the e2e suite's frame recorder). */
+    onWebSocketMessage?: (message: ItxWebSocketMessage) => void;
+    /**
+     * Observe the returned connection closing. Failed pre-ready dials use onRetry.
+     *
+     * A client whose job is to stay connected (a device, a long-lived agent)
+     * reconnects from HERE — the moment the transport dies — not lazily when
+     * its next call fails. The hook is a passive observer: this client stays
+     * vanilla capnweb and never reconnects, pings, or retries by itself; the
+     * consumer owns that loop.
+     */
+    onWebSocketClose?: (close: {
+        code: number;
+        reason: string;
+    }) => void;
+};
+type ConnectItxAuthenticatedInput = ConnectItxBaseInput & {
+    auth: ItxAuthCredentials;
+};
+type ConnectProjectItxInput = ConnectItxAuthenticatedInput & {
+    projectId: string;
+};
+type ConnectAgentItxInput = ConnectItxAuthenticatedInput & {
+    agentPath: string;
+    projectId: string;
+};
+export type ItxInitialConnectionRetry = {
+    attemptDurationMs: number;
+    delayMs: number;
+    error: Error;
+    failedAttempt: 1;
+    nextAttempt: 2;
+    startedAt: string;
+};
+export type ConnectItxReadyOptions = {
+    /**
+     * Permit exactly one fresh dial while establishing the initial WebSocket.
+     *
+     * The retry boundary ends before the RPC session exists, so it can never
+     * replay authentication or a caller operation.
+     */
+    retryInitialConnection?: {
+        /** Delay before the one retry. Defaults to 250ms; maximum 5s. */
+        delayMs?: number;
+        /** Observe the failed first dial before the retry begins. */
+        onRetry?: (retry: ItxInitialConnectionRetry) => Promise<void> | void;
+    };
+};
+export declare function connectItx(input: ConnectAgentItxInput): CapnRpcStub<Agent>;
+export declare function connectItx(input: ConnectProjectItxInput): CapnRpcStub<Project>;
+export declare function connectItx(input: ConnectItxAuthenticatedInput): CapnRpcStub<Session>;
+export declare function connectItx(input: ConnectItxBaseInput): CapnRpcStub<UnauthenticatedOs>;
+export declare function connectItxReady(input: ConnectAgentItxInput, options?: ConnectItxReadyOptions): Promise<CapnRpcStub<Agent>>;
+export declare function connectItxReady(input: ConnectProjectItxInput, options?: ConnectItxReadyOptions): Promise<CapnRpcStub<Project>>;
+export declare function connectItxReady(input: ConnectItxAuthenticatedInput, options?: ConnectItxReadyOptions): Promise<CapnRpcStub<Session>>;
+export declare function connectItxReady(input: ConnectItxBaseInput, options?: ConnectItxReadyOptions): Promise<CapnRpcStub<UnauthenticatedOs>>;
+export {};

package/dist/itx/itx-session.d.ts

@@ -0,0 +1,215 @@
+/**
+ * itx-session — the framework-free half of the itx client: ONE WebSocket per
+ * process (browser tab, TUI, phone), connected to an OS deployment's `/api`,
+ * `authenticate()`d into a **Session** (the catalog that vends project itxs via
+ * `session.projects.get(slug)`), and kept alive through transport gaps.
+ *
+ * React never appears in this module. The hooks in ../sdk/itx/react.ts are a thin
+ * binding over the exact surface exported here (`subscribeSession` +
+ * `currentSnapshot` feed `useSyncExternalStore`; everything else is shared
+ * verbatim), so a non-React consumer — a node script, a future runtime —
+ * gets the same one-socket semantics by importing `iterate/client`.
+ *
+ * WHERE THE CONNECTION TARGET COMES FROM
+ *   • In a browser, nothing to configure: the keeper connects
+ *     `window.location`'s `/api` and authenticates with the session cookie
+ *     riding the WebSocket handshake.
+ *   • Anywhere else (the chat TUI, tests, scripts that want the KEEPER rather
+ *     than the one-shot node dial), call {@link configureIterateSession} with a
+ *     base URL and credentials. Calling it again for the same deployment
+ *     refreshes the credential source without disturbing the socket; changing
+ *     deployments deliberately replaces the socket. The runtime's global
+ *     WebSocket carries the dial — node ≥ 22, bun, and React Native all satisfy
+ *     capnweb's WebSocket needs.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * THE SESSION MODEL — one socket, generations, invisible reconnect
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *  • ONE WebSocket for the whole process, kept in module state (so in a
+ *    browser it persists across client-side navigation). One connection attempt is a
+ *    GENERATION ({@link Generation}): its WebSocket and its connecting
+ *    promise. The session is the AWAITED `authenticate()` result — one settled
+ *    stub identity shared by the snapshot, imperative awaiters, and the
+ *    project-stub cache (resolving with the raw pipelined RpcPromise would
+ *    fork identities: native promises assimilate thenables). The connection timeout
+ *    spans the whole handshake (TCP/TLS/upgrade AND authenticate), and a REAL
+ *    auth rejection over a working socket is terminal — it surfaces from the
+ *    connecting promise instead of looping.
+ *
+ *  • RECONNECT IS INVISIBLE. Readers see an immutable {@link Snapshot};
+ *    `snapshot.session` holds the LAST live session and is kept across a
+ *    transport gap. Before the FIRST session, awaiters share the STABLE
+ *    {@link firstConnect} promise, which survives failed connection attempts (paced
+ *    reconnects happen behind it; an individual attempt's rejection never reaches a suspended
+ *    React tree) and rejects only on a TERMINAL failure. Kept-across-the-gap
+ *    applies to TRANSPORT gaps only: a terminal auth rejection on a reconnect is
+ *    an AUTHORITY loss — the halted snapshot drops the (already dead) session
+ *    so the real error surfaces instead of zombie stubs.
+ *
+ *  • PROJECT STUBS ARE SESSION-OWNED. `session.projects.get` allocates a
+ *    capnweb import-table entry, so deriving stubs ad hoc (or inside React
+ *    renders that may be discarded) would leak them. The module
+ *    {@link projectStubCaches} WeakMap keyed by the session stub caches one
+ *    real stub per (session, slug); a retired generation disposes them. The
+ *    stub stays the REAL capnweb stub (a lazy wrapper that awaited the session
+ *    per call would break pipelining — capnweb fork v0.8.0), and its identity
+ *    changes exactly once per successful reconnect.
+ *
+ *  • TRANSPORT HEALTH IS SOCKET-OWNED and GENERATION-GUARDED. A half-open
+ *    socket (laptop sleep, network switch — no `close` event) is detected by
+ *    one verifier per generation ({@link verifyTransport}: periodic +
+ *    visibility/online probes, two-strike). Consumers REPORT suspicion
+ *    ({@link reportTransportSuspicion}); they never close the shared socket
+ *    themselves. Only two failed probes against the SAME generation retire it,
+ *    and {@link reconnectIfCurrent} is a compare-and-swap on generation OBJECT
+ *    IDENTITY — a late verdict against a superseded generation can never close
+ *    its healthy successor. {@link reconnectIterateSession} is the separate,
+ *    deliberate *semantic* reset (new claims after create/unlock).
+ */
+import { type RpcStub } from "@iterate-com/capnweb";
+import type { ItxAuthCredentials, Project, Session } from "../itx-api.generated.ts";
+/** The Session catalog (what `authenticate()` returns): vends project itxs. */
+export type SessionStub = RpcStub<Session>;
+/** A project capability handle — `session.projects.get(slug)`. */
+export type ProjectStub = RpcStub<Project>;
+export type { ProjectStub as Itx };
+export type IterateSessionConfig = {
+    /** OS deployment base URL, e.g. `https://os.iterate.com`; `/api` is appended. */
+    baseUrl: string;
+    /**
+     * How `authenticate()` identifies the caller. A provider is resolved for
+     * every dial, so rotating credentials stay fresh across transport reconnects.
+     * If authentication rejects with an auth-shaped error, providers get one
+     * forced-refresh attempt before the failure becomes terminal. Default: the
+     * browser session cookie.
+     */
+    credentials?: ItxAuthCredentials | ((options: {
+        forceRefresh: boolean;
+    }) => ItxAuthCredentials | Promise<ItxAuthCredentials>);
+};
+/**
+ * Point the keeper at a deployment explicitly — the non-browser entry into the
+ * one-socket model (the chat TUI, React Native, keeper-based scripts). Repeating
+ * the same target updates its credential source without disturbing the live
+ * socket. A different target retires the old deployment immediately and connects
+ * the new one, so authority can never cross deployments. In a browser this is
+ * optional (the default is `window.location`'s `/api` with cookie auth).
+ */
+export declare function configureIterateSession(config: IterateSessionConfig): void;
+/**
+ * The immutable value readers see (React reads it via `useSyncExternalStore` +
+ * `use()`). Replaced wholesale on every transition, always BEFORE listeners are
+ * notified, so a concurrent render can never tear. `session` is the last live
+ * session and survives transport gaps — that is what makes reconnect
+ * invisible. `generation` is a monotonic number whose only job is being the
+ * reconnect dep for the React layer's reconnect-aware effect (the CAS is
+ * generation object identity, not this number). `connecting` is what
+ * first-load callers await/suspend on: before the FIRST session it is the
+ * stable {@link firstConnect} promise (survives closed-before-open retries
+ * without rejecting a suspended tree); afterwards `session` is always defined.
+ */
+type Snapshot = {
+    generation: number;
+    session: SessionStub | undefined;
+    connecting: Promise<SessionStub>;
+};
+export declare const subscribeSession: (onChange: () => void) => () => undefined;
+export declare function projectStubFor(session: SessionStub, slug: string): ProjectStub;
+/** getSnapshot for useSyncExternalStore: stable between transitions; connects when idle. */
+export declare function currentSnapshot(): Snapshot;
+export declare const serverSnapshot: () => never;
+/**
+ * Ensure a live-or-connecting session and return its connecting promise. The
+ * imperative sibling of the React `useIterateSession()`: for handlers,
+ * `mutationFn`s, scripts, and lazy closures. Same one socket the hooks use.
+ * After a TERMINAL auth rejection this keeps returning that failure (the
+ * halted generation — see Generation.failed) until {@link reconnectIterateSession}.
+ */
+export declare function connectIterateSession(): Promise<SessionStub>;
+/**
+ * The project itx for a slug (or `prj_…` id), imperatively. Pipelines through
+ * the returned promise — `(await connectItx(slug)).streams.get(path)`. Returns
+ * the session-owned cached stub, re-derived automatically after a reconnect.
+ */
+export declare function connectItx(slug: string): Promise<ProjectStub>;
+/**
+ * Report that the shared transport may be half-open (a call hung). Consumers —
+ * the subscription watchdog, any long-lived reader — call this instead of
+ * closing the socket themselves — {@link verifyTransport} probes and, only on
+ * two strikes against the SAME generation, retires it. A stale report is a
+ * no-op.
+ */
+export declare function reportTransportSuspicion(): void;
+/**
+ * The SEMANTIC reset (not a transport reconnect): drop the live socket and connection attempt
+ * a fresh one so the next reads run under the caller's CURRENT claims. Call
+ * after creating a project or unlocking admin — the live socket carries the
+ * connect-time principal. React callers that need already-cached data refreshed
+ * should also `invalidateQueries({ queryKey: ["itx"] })`.
+ */
+export declare function reconnectIterateSession(): void;
+/**
+ * Revive only a generation parked by a terminal authentication failure. This
+ * is the imperative retry boundary for query/mutation clients: calling it
+ * before a repeated operation lets refreshed credentials dial again without
+ * disturbing a healthy or merely reconnecting session.
+ */
+export declare function retryFailedIterateSession(): void;
+/**
+ * Release the current transport and authority without reconnecting. Intended
+ * for process-local lifecycle boundaries such as signing out of a native app;
+ * mounted consumers should be removed in the same transition. The explicit
+ * deployment configuration remains, so a later connect can dial it again.
+ */
+export declare function disconnectIterateSession(): void;
+/**
+ * The four — and only four — transport-close rejections a caller may treat as
+ * "the socket died, retry on a fresh one": our own connection-closed rejection, capnweb's
+ * two WebSocket aborts (`Peer closed WebSocket: <code> <reason>` and
+ * `WebSocket connection failed.`), and capnweb's exact local-shutdown error
+ * from our forced bootstrap disposal. Deliberately NARROW: an
+ * application/auth/validation error that merely mentions "WebSocket" must never
+ * be mistaken for a transport failure and retried. This is the one discriminant
+ * shared by the query retry, the subscribe retry, and the liveness verifier.
+ */
+export declare function isItxTransportError(error: unknown): boolean;
+/**
+ * The common lifecycle used by reconnecting stream and live-state clients.
+ * Concrete APIs adapt their own handle (`StreamConnectionHandle.close()` or
+ * `LiveStateSubscriptionHandle.unsubscribe()`) to `close()`. Real handles are
+ * capnweb stubs and therefore Disposable: `close()` closes the server-side
+ * resource, while `[Symbol.dispose]` releases the caller-owned stub —
+ * on the process-long shared socket, skipping the dispose leaks one
+ * import-table entry per subscribe cycle, so holders always do both.
+ */
+export type ItxRecoverableConnectionHandle = {
+    ping(): boolean | Promise<boolean>;
+    close(): unknown;
+    [Symbol.dispose]?(): void;
+};
+/**
+ * Release a push connection completely: `close()` closes the server side
+ * (already-dead is fine — the rejection is swallowed), then
+ * `[Symbol.dispose]` frees the caller-owned stub. One helper because
+ * forgetting either half leaks (see {@link ItxRecoverableConnectionHandle}).
+ */
+export declare function releaseItxConnection(handle: ItxRecoverableConnectionHandle): void;
+/**
+ * Poll a push connection's `ping()` until it stops answering `true`, then
+ * recover. Server pushes fail SILENTLY: a dead Durable Object or half-open TCP
+ * stops delivering with no client-visible signal, so a consumer can show
+ * "live" forever while stale. The watchdog checks on an interval and — because
+ * those are exactly when sockets die — when a browser tab becomes visible or
+ * comes online (in runtimes without those signals, the interval carries it).
+ *
+ *   `dead`      → ping answered `false` or REJECTED: the socket works but the
+ *                 server-side connection is gone (DO restart / dropped
+ *                 callback). Recovery opens it again on the same socket.
+ *   `timed-out` → ping never answered: the shared WebSocket is half-open. The
+ *                 watchdog REPORTS the suspicion to the socket-owned verifier
+ *                 ({@link reportTransportSuspicion}) — it never closes the socket
+ *                 itself — and the holder opens again once the generation
+ *                 reconnects.
+ */
+export declare function watchItxConnection(ping: () => boolean | Promise<boolean>, onDead: () => void): () => void;

package/dist/itx/owned-rpc-session.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Groups an authenticated child stub with the parent stubs that keep it alive.
+ *
+ * Cap'n Web callers often want `using project = connectItx({ projectId })`, but
+ * that project stub is reached through a root session and authentication stub.
+ * This proxy makes disposal and `dup()` preserve the whole ownership chain, so
+ * disposing the child also tells the server it can release the parent stubs.
+ */
+type DisposableLike = {
+    [Symbol.dispose]?(): void;
+    dup?(): DisposableLike;
+};
+export declare function withOwnedRpcSession<T extends object>(stub: T, ...owned: DisposableLike[]): T;
+export {};

package/dist/itx/query-client.d.ts

@@ -0,0 +1,10 @@
+import { QueryClient } from "@tanstack/react-query";
+/**
+ * One Query client policy for every Iterate React renderer.
+ *
+ * The browser dashboard and the OpenTUI client intentionally share these
+ * defaults. Renderer-specific entrypoints own only where the provider mounts;
+ * cache lifetime, refetch behavior, and mutation retries must not drift by
+ * surface.
+ */
+export declare function createIterateQueryClient(): QueryClient;