iterate 0.3.0 → 0.4.0

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

@@ -1,205 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,28 +0,0 @@
-//#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

@@ -1 +0,0 @@
-{"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.d.mts

@@ -1,5 +0,0 @@
-//#region src/index.d.ts
-declare function runCli(): Promise;
-//#endregion
-export { runCli };
-//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

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

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export async function runCli() {\n  const cli = await import(\"./cli.ts\");\n  await cli.runCli();\n}\n"],"mappings":";AAAA,eAAsB,SAAS;CAE7B,OAAM,MADY,OAAO,sBAAA,CACf,OAAO;AACnB"}

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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-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

@@ -1,215 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-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;