iterate 0.2.7 → 0.3.0

package/dist/cloudflare-BTm90gQ4.mjs

@@ -0,0 +1,951 @@
+import { o as StreamProcessorRunner } from "./stream-processor-keepalive-DAQTP6m3.mjs";
+import { n as durableObjectRecovery, t as durableObjectProgressStore } from "./durable-object-processor-durability-CNsTjAJS.mjs";
+import { n as hostRuntimeCapabilities, t as announceContract } from "./processor-host-capabilities-BMFH3KTM.mjs";
+import * as cloudflareWorkers from "cloudflare:workers";
+import { DurableObject } from "cloudflare:workers";
+import { z } from "zod";
+//#region src/sdk/capnweb/live-state/retain.ts
+/**
+* Retain a single-argument RPC callback so it survives past the call that
+* carried it. `dup()` duplicates the underlying remote stub (that dup is what
+* `[Symbol.dispose]` releases); `onRpcBroken` is forwarded defensively — Cap'n
+* Web stubs expose no own property descriptors and a Workers RPC property access
+* can fabricate a pipelined method that rejects at call time, so we wire whatever
+* the stub claims and swallow registration failures. `onRpcBroken` is only a
+* prompt hint; callers that need a terminal verdict must model one explicitly
+* (for example, the durable wake lane's independent settlement capability).
+*/
+function retainCallback(callback) {
+	const retainable = callback;
+	const retained = retainable.dup?.() ?? retainable;
+	const dispose = retained[Symbol.dispose]?.bind(retained);
+	let disposed = false;
+	const wrapped = Object.assign((arg) => retained(arg), { [Symbol.dispose]() {
+		if (disposed) return;
+		disposed = true;
+		dispose?.();
+	} });
+	const onRpcBroken = retained.onRpcBroken;
+	if (typeof onRpcBroken === "function") wrapped.onRpcBroken = (handler) => {
+		try {
+			const result = onRpcBroken.call(retained, handler);
+			if (isThenable(result)) Promise.resolve(result).catch(() => {});
+		} catch {}
+	};
+	return wrapped;
+}
+/** Thenable probe: RPC stubs and their call results are thenable-shaped. */
+function isThenable(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+/**
+* Dispose the result of an RPC call whose value the caller ignores. Reading a
+* Cap'n Web / Workers RPC method yields a disposable stub even when unused, and
+* dropping it without disposal leaks the remote reference.
+*/
+function disposeIgnoredRpcResult(result) {
+	if (result !== null && (typeof result === "object" || typeof result === "function") && Symbol.dispose in result) result[Symbol.dispose]();
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/diff.ts
+/**
+* Structural diff between two JSON values, producing the minimal `LiveStatePatch`
+* — or `undefined` when nothing changed.
+*
+* The diff is REFERENCE-FIRST: identical references short-circuit immediately
+* (`Object.is`), so the cost is O(changed), not O(size) — *as long as callers
+* update state immutably* (unchanged sub-objects keep their identity). That one
+* discipline is the whole performance story: a single touched row in a
+* thousand-entry index yields one tiny patch instead of a full rescan.
+*
+* PLAIN objects (prototype `Object.prototype` or `null`) are treated as keyed
+* maps and diffed per key. Dense arrays are diffed by position. Everything
+* else — primitives, `null`, sparse arrays, and
+* non-plain instances like `Date`/`Map`/`Set` — is a leaf, replaced wholesale.
+* Descending into an instance would diff its own enumerable keys, which for a
+* `Date` is NONE — two different Dates would read as "unchanged" and the
+* subscriber would stay stale forever. Keyed objects remain preferable for
+* collections whose entries frequently move; positional patches do not infer moves.
+*/
+function diff(prev, next, options = {}) {
+	if (Object.is(prev, next)) return void 0;
+	if (Array.isArray(prev) && Array.isArray(next) && options.arrays !== false) {
+		const items = [];
+		for (let index = 0; index < next.length; index++) {
+			if (!Object.hasOwn(next, index) || index < prev.length && !Object.hasOwn(prev, index)) return { set: next };
+			const patch = index < prev.length ? diff(prev[index], next[index], options) : { set: next[index] };
+			if (patch) items.push([index, patch]);
+		}
+		return items.length > 0 || prev.length !== next.length ? { array: {
+			length: next.length,
+			items
+		} } : void 0;
+	}
+	if (!isPlainObject(prev) || !isPlainObject(next)) return { set: next };
+	const fields = [];
+	const drop = [];
+	for (const key of Object.keys(next)) {
+		if (next[key] === void 0) {
+			if (Object.hasOwn(prev, key)) drop.push(key);
+			continue;
+		}
+		const childPatch = diff(Object.hasOwn(prev, key) ? prev[key] : void 0, next[key], options);
+		if (childPatch !== void 0) fields.push([key, childPatch]);
+	}
+	for (const key of Object.keys(prev)) if (!Object.hasOwn(next, key)) drop.push(key);
+	if (fields.length === 0 && drop.length === 0) return void 0;
+	const patch = {};
+	if (fields.length > 0) patch.fields = Object.fromEntries(fields);
+	if (drop.length > 0) patch.drop = drop;
+	return patch;
+}
+/**
+* Apply a `LiveStatePatch` to a previous value, returning the next value.
+*
+* Like `diff`, this preserves structural sharing: a fresh object is built only
+* along changed paths, so untouched branches keep their previous reference.
+* That's what lets a client selector (`s => s.streamsIndex`) skip re-rendering
+* when an unrelated slice changed — the slice it reads stays `Object.is`-equal
+* across applies.
+*/
+function applyPatch(prev, patch) {
+	if ("set" in patch) return patch.set;
+	if ("array" in patch) {
+		if (!Array.isArray(prev)) throw new Error("Live-state array patch requires an array baseline");
+		const next = prev.slice(0, patch.array.length);
+		next.length = patch.array.length;
+		for (const [index, child] of patch.array.items) {
+			if (!Number.isSafeInteger(index) || index < 0 || index >= next.length) throw new Error("Live-state array patch index is outside its resulting length");
+			next[index] = applyPatch(prev[index], child);
+		}
+		return next;
+	}
+	const base = isPlainObject(prev) ? prev : {};
+	const next = { ...base };
+	if (patch.fields) for (const [key, childPatch] of Object.entries(patch.fields)) Object.defineProperty(next, key, {
+		value: applyPatch(Object.hasOwn(base, key) ? base[key] : void 0, childPatch),
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	if (patch.drop) for (const key of patch.drop) delete next[key];
+	return next;
+}
+/**
+* A PLAIN object — prototype `Object.prototype` or `null` — the only thing
+* `diff` descends into and `applyPatch` merges over. Arrays and class instances
+* (`Date`, `Map`, `Set`, …) fail this on purpose: they carry state outside
+* their own enumerable keys, so per-key diffing would misread them (see the
+* `diff` docstring) — they are leaves, replaced wholesale.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/compact.ts
+const fieldAddresses = /* @__PURE__ */ new WeakMap();
+function addresses(value) {
+	let cached = fieldAddresses.get(value);
+	if (!cached) {
+		const keys = Object.keys(value).filter((key) => value[key] !== void 0).sort();
+		cached = {
+			keys,
+			indices: new Map(keys.map((key, index) => [key, index]))
+		};
+		fieldAddresses.set(value, cached);
+	}
+	return cached;
+}
+/** Encode only the changed paths of an existing structural diff. */
+function compactPatch(previous, patch) {
+	if ("set" in patch) {
+		const next = patch.set;
+		if (typeof previous === "string" && typeof next === "string" && previous.length >= 16 && previous.length <= 4096 && next.length > previous.length && next.startsWith(previous)) return [previous.length, next.slice(previous.length)];
+		if (next === null || typeof next === "string" || typeof next === "number" || typeof next === "boolean") return next;
+		return [next];
+	}
+	if ("array" in patch) {
+		if (!Array.isArray(previous)) throw new Error("Live-state array patch requires an array baseline");
+		const result = {};
+		if (patch.array.length !== previous.length) result["#"] = patch.array.length;
+		for (const [index, child] of patch.array.items) result[index] = compactPatch(previous[index], child);
+		return result;
+	}
+	if (!isPlainObject(previous)) throw new Error("Live-state object patch requires an object baseline");
+	const { indices } = addresses(previous);
+	const fields = [];
+	for (const [key, child] of Object.entries(patch.fields || {})) {
+		const index = indices.get(key);
+		fields.push([index === void 0 ? `+${key}` : String(index), compactPatch(index === void 0 ? void 0 : previous[key], child)]);
+	}
+	for (const key of patch.drop || []) {
+		const index = indices.get(key);
+		if (index !== void 0) fields.push([String(index), []]);
+	}
+	return Object.fromEntries(fields);
+}
+/** Apply a version 3 patch, retaining every untouched object's identity. */
+function applyCompactPatch(previous, patch) {
+	return applyCompactValue(previous, patch);
+}
+function applyCompactValue(previous, patch) {
+	if (patch === null || typeof patch !== "object") return patch;
+	if (Array.isArray(patch)) {
+		if (patch.length === 1) return patch[0];
+		if (patch.length !== 2 || typeof previous !== "string" || previous.length !== patch[0]) throw new Error("Live-state append does not match its string baseline");
+		return previous + patch[1];
+	}
+	if (Array.isArray(previous)) {
+		const length = Object.hasOwn(patch, "#") ? patch["#"] : previous.length;
+		if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0 || length > 4294967295) throw new Error("Live-state array patch has an invalid length");
+		const next = previous.slice(0, length);
+		next.length = length;
+		for (const [address, child] of Object.entries(patch)) {
+			if (address === "#") continue;
+			const index = position(address, length);
+			next[index] = applyCompactValue(previous[index], child);
+		}
+		return next;
+	}
+	if (!isPlainObject(previous)) throw new Error("Live-state object patch requires an object baseline");
+	const { keys } = addresses(previous);
+	const next = { ...previous };
+	for (const [address, child] of Object.entries(patch)) {
+		const added = address.startsWith("+");
+		const key = added ? address.slice(1) : keys[position(address, keys.length)];
+		if (added && Object.hasOwn(previous, key) && previous[key] !== void 0) throw new Error("Live-state new field already exists in its baseline");
+		if (Array.isArray(child) && child.length === 0) {
+			if (added) throw new Error("Live-state cannot delete a new field");
+			delete next[key];
+		} else Object.defineProperty(next, key, {
+			value: applyCompactValue(added ? void 0 : previous[key], child),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return next;
+}
+function position(address, length) {
+	const index = Number(address);
+	if (!Number.isSafeInteger(index) || index < 0 || index >= length || String(index) !== address) throw new Error("Live-state field address is outside its baseline");
+	return index;
+}
+//#endregion
+//#region src/sdk/capnweb/live-state/engine.ts
+const DEFAULT_DEBOUNCE_MS = 100;
+const ACK_TIMEOUT_MS = 1e4;
+/**
+* A source-agnostic live store: hold a state value, and when it changes push the
+* minimal diff to every subscriber. It does not know or care where the state
+* comes from — a Durable Object folds events into it, a stateless RpcTarget polls
+* a third-party API into it — so ANY RpcTarget can expose live state by holding
+* one and returning a read-only wrapper from a `.live` getter.
+*
+* Two rules make it cheap and correct:
+* - Updates are IMMUTABLE (`setState`/`assign` build a new value, never mutate),
+*   so the diff short-circuits unchanged branches by identity — O(changed), not
+*   O(size). See `diff.ts`.
+* - Push work runs only while a subscriber exists. Transient readers call
+*   `readSince` explicitly; a dormant engine schedules nothing.
+*
+* All subscribers share one revision line. Fast subscribers share a patch;
+* slow subscribers receive a coalesced patch from their acknowledged state.
+* A revision mismatch makes the client resync instead of applying stale data.
+*/
+var LiveState = class {
+	#current;
+	/** Latest flushed state — the shared diff baseline. */
+	#broadcast;
+	#revision = 0;
+	#epoch = crypto.randomUUID();
+	#lastUpdate;
+	#lastCompactUpdate;
+	#subscribers = /* @__PURE__ */ new Map();
+	#debounceMs;
+	#flushTimer;
+	constructor(initial, options = {}) {
+		this.#current = initial;
+		this.#broadcast = initial;
+		this.#debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+	}
+	/** The current state — reflects every `setState`/`assign`, even while dormant. */
+	getState() {
+		return this.#current;
+	}
+	/** One retained delta bounds history while a single parent can pull incrementally.
+	* A late reader or a new incarnation receives an explicit snapshot instead. */
+	readSince(cursor, options = {}) {
+		if (this.#flushTimer !== void 0) clearTimeout(this.#flushTimer);
+		this.#flushTimer = void 0;
+		this.#flush();
+		if (cursor?.epoch === this.#epoch) {
+			if (cursor.revision === this.#revision) return {
+				epoch: this.#epoch,
+				update: null
+			};
+			if (cursor.revision === this.#lastUpdate?.from) return {
+				epoch: this.#epoch,
+				update: options.patchVersion === 3 ? this.#lastCompactUpdate : this.#lastUpdate
+			};
+		}
+		return {
+			epoch: this.#epoch,
+			update: options.patchVersion === 3 ? { s: [this.#revision, this.#broadcast] } : {
+				type: "snapshot",
+				revision: this.#revision,
+				state: this.#broadcast
+			}
+		};
+	}
+	/** True while at least one live subscriber makes projection work observable. */
+	get observed() {
+		return this.#subscribers.size > 0;
+	}
+	/** Replace the state. Build a NEW value (don't mutate) so the diff stays cheap. */
+	setState(next) {
+		this.#current = typeof next === "function" ? next(this.#current) : next;
+		if (this.#subscribers.size > 0) this.#scheduleFlush();
+	}
+	/** Shallow-merge a partial into the state — sugar for `setState(p => ({ ...p, ...partial }))`. */
+	assign(partial) {
+		this.setState((prev) => ({
+			...prev,
+			...partial
+		}));
+	}
+	subscribe(sink, options = {}) {
+		if (this.#subscribers.size === 0) this.#flush();
+		const retained = retainCallback(sink);
+		this.#subscribers.set(retained, {
+			version: options.patchVersion ?? 1,
+			state: this.#broadcast,
+			revision: this.#revision,
+			busy: false
+		});
+		retained.onRpcBroken?.(() => this.#drop(retained));
+		this.#deliver(retained, options.patchVersion === 3 ? { s: [this.#revision, this.#broadcast] } : {
+			type: "snapshot",
+			revision: this.#revision,
+			state: this.#broadcast
+		});
+		return {
+			ping: () => this.#subscribers.has(retained),
+			unsubscribe: () => this.#drop(retained),
+			[Symbol.dispose]: () => this.#drop(retained)
+		};
+	}
+	#scheduleFlush() {
+		this.#flushTimer ??= setTimeout(() => {
+			this.#flushTimer = void 0;
+			this.#flush();
+		}, this.#debounceMs);
+	}
+	#flush() {
+		const previous = this.#broadcast;
+		const patch = diff(previous, this.#current);
+		if (patch === void 0) return;
+		const from = this.#revision;
+		const to = this.#revision += 1;
+		this.#broadcast = this.#current;
+		const update = {
+			type: "patch",
+			from,
+			to,
+			patch
+		};
+		this.#lastUpdate = update;
+		this.#lastCompactUpdate = { p: [
+			from,
+			to,
+			compactPatch(previous, patch)
+		] };
+		for (const subscriber of this.#subscribers.keys()) this.#sendLatest(subscriber);
+	}
+	/** Slow subscribers hold one call and one baseline, never a queue of token updates. */
+	#sendLatest(subscriber) {
+		const held = this.#subscribers.get(subscriber);
+		if (!held || held.busy || held.revision === this.#revision) return;
+		if (held.version === 3) {
+			if (held.revision === this.#lastUpdate?.from) this.#deliver(subscriber, this.#lastCompactUpdate);
+			else {
+				const patch = diff(held.state, this.#broadcast);
+				this.#deliver(subscriber, { p: [
+					held.revision,
+					this.#revision,
+					patch ? compactPatch(held.state, patch) : {}
+				] });
+			}
+			return;
+		}
+		const patch = held.version === 2 && held.revision === this.#lastUpdate?.from ? this.#lastUpdate.patch : diff(held.state, this.#broadcast, { arrays: held.version === 2 });
+		this.#deliver(subscriber, {
+			type: "patch",
+			from: held.revision,
+			to: this.#revision,
+			patch: patch ?? {}
+		});
+	}
+	/** Only acknowledgement releases the next coalesced update; a dead sink is dropped. */
+	#deliver(subscriber, update) {
+		const held = this.#subscribers.get(subscriber);
+		if (!held) return;
+		held.state = this.#broadcast;
+		held.revision = this.#revision;
+		held.busy = true;
+		let result;
+		try {
+			result = subscriber(update);
+		} catch {
+			this.#drop(subscriber);
+			return;
+		}
+		if (isThenable(result)) {
+			held.timeout = setTimeout(() => {
+				console.warn("Live-state subscriber dropped: acknowledgement timed out", {
+					revision: held.revision,
+					timeoutMs: ACK_TIMEOUT_MS
+				});
+				this.#drop(subscriber);
+			}, ACK_TIMEOUT_MS);
+			Promise.resolve(result).then(() => {
+				if (held.timeout !== void 0) clearTimeout(held.timeout);
+				held.busy = false;
+				this.#sendLatest(subscriber);
+			}, () => this.#drop(subscriber)).finally(() => disposeIgnoredRpcResult(result));
+			return;
+		}
+		held.busy = false;
+		disposeIgnoredRpcResult(result);
+	}
+	#drop(subscriber) {
+		const timeout = this.#subscribers.get(subscriber)?.timeout;
+		if (timeout !== void 0) clearTimeout(timeout);
+		if (!this.#subscribers.delete(subscriber)) return;
+		subscriber[Symbol.dispose]();
+		if (this.#subscribers.size === 0 && this.#flushTimer !== void 0) {
+			clearTimeout(this.#flushTimer);
+			this.#flushTimer = void 0;
+		}
+	}
+};
+//#endregion
+//#region src/processors/stream-processor-registry.ts
+const tracing = cloudflareWorkers.tracing ?? { enterSpan: (_name, fn) => fn({ setAttribute() {} }) };
+const WakeDeliveryThrowableFields = z.object({
+	durableObjectReset: z.unknown().optional(),
+	itxCallId: z.unknown().optional(),
+	message: z.unknown().optional(),
+	name: z.unknown().optional(),
+	overloaded: z.unknown().optional(),
+	retryable: z.unknown().optional()
+});
+function serializeWakeDeliveryError(error) {
+	const parsed = WakeDeliveryThrowableFields.safeParse(error);
+	const candidate = parsed.success ? parsed.data : void 0;
+	return {
+		name: typeof candidate?.name === "string" ? candidate.name : "Error",
+		message: typeof candidate?.message === "string" ? candidate.message : String(error) || "unknown delivery failure",
+		...typeof candidate?.itxCallId === "string" && candidate.itxCallId.length > 0 && candidate.itxCallId.length <= 200 && { itxCallId: candidate.itxCallId },
+		...candidate?.durableObjectReset === true && { durableObjectReset: true },
+		...candidate?.overloaded === true && { overloaded: true },
+		...candidate?.retryable === true && { retryable: true }
+	};
+}
+/**
+* Report one final wake-delivery result without awaiting the report call's
+* return value. Calling the callback sends the result; awaiting it would keep
+* the original cross-Durable-Object call chain open.
+*/
+function reportWakeDeliveryResult(reportDeliveryResult, deliveryResult) {
+	let result;
+	try {
+		result = reportDeliveryResult(deliveryResult);
+	} catch (error) {
+		console.warn("stream wake delivery result could not be reported", { error });
+		return;
+	}
+	try {
+		disposeIgnoredRpcResult(result);
+	} catch (error) {
+		console.warn("stream wake delivery report result disposal failed", { error });
+	}
+}
+function createStreamProcessorRegistry(ctx, options) {
+	const entries = /* @__PURE__ */ new Map();
+	const now = options.now ?? (() => Date.now());
+	const alarmSlices = /* @__PURE__ */ new Map();
+	/**
+	* A durable alarm armed by a PREVIOUS incarnation whose owning slice we
+	* cannot know (in-memory desires died with it). The first reconcile adopts
+	* it as a desire of its own so this incarnation's arming/disarming cannot
+	* clobber it; the next actual fire drops it — every subsystem re-derives
+	* its desire in that turn.
+	*/
+	const INHERITED_ALARM_SLICE = "@inherited";
+	/** What the platform alarm holds; null = cleared, undefined = unknown. */
+	let platformAlarmAtMs;
+	/** Serializes alarm storage ops so read-adopt and writes cannot interleave. */
+	let alarmChain = Promise.resolve();
+	/**
+	* Returns the settled write for callers whose correctness depends on the
+	* alarm being DURABLY armed (the alarm handler, the scheduler's error-path
+	* fallback) — a rejected step means the platform alarm may not exist, and
+	* such callers must rethrow so the platform retries them. Fire-and-forget
+	* callers may ignore the result: the chain observes the rejection either
+	* way, and the next reconcile re-reads and re-issues.
+	*/
+	function reconcileAlarm() {
+		const step = alarmChain.then(async () => {
+			if (platformAlarmAtMs === void 0) {
+				const existing = await ctx.storage.getAlarm();
+				platformAlarmAtMs = existing;
+				if (existing !== null) alarmSlices.set(INHERITED_ALARM_SLICE, existing);
+			}
+			let earliest = null;
+			for (const atMs of alarmSlices.values()) if (earliest === null || atMs < earliest) earliest = atMs;
+			if (earliest === platformAlarmAtMs) return;
+			platformAlarmAtMs = earliest;
+			if (earliest === null) await ctx.storage.deleteAlarm();
+			else await ctx.storage.setAlarm(earliest);
+		});
+		alarmChain = step.catch((error) => {
+			platformAlarmAtMs = void 0;
+			console.error("stream processor registry alarm arming failed", error);
+		});
+		ctx.waitUntil(alarmChain);
+		return step;
+	}
+	function setAlarmSlice(name, atMs) {
+		if (atMs === null) alarmSlices.delete(name);
+		else alarmSlices.set(name, atMs);
+		return reconcileAlarm();
+	}
+	function requireEntry(name) {
+		const entry = entries.get(name);
+		if (entry === void 0) throw new Error(`Unknown stream processor name "${name}" on this registry (registered: ${[...entries.keys()].join(", ") || "none"})`);
+		return entry;
+	}
+	function requireEntryForInstance(processor, verb) {
+		for (const entry of entries.values()) if (entry.processor === processor) return entry;
+		throw new Error(`stream processor "${processor.contract.slug}" instance passed to ${verb}() is not registered on this registry — pass the exact instance register() returned (registered names: ${[...entries.keys()].join(", ") || "none"})`);
+	}
+	/**
+	* Route a wake to a registered entry. The subscription NAME is the key —
+	* and equals the contract slug (enforced at configure time; under facet
+	* placement it is also the facet name). An unknown name is a loud error.
+	*/
+	function resolveProcessorName(args) {
+		if (entries.get(args.name) === void 0) throw new Error(`wakeStreamProcessor for unknown name "${args.name}" — subscribe by registered name (registered: ${[...entries.keys()].join(", ") || "none"})`);
+		return args.name;
+	}
+	const live = new LiveState({});
+	function assembleLive() {
+		if ([...entries.values()].some((entry) => !entry.runner.isLoaded)) {
+			options.onLiveAssembled?.({ skippedUnloadedRunners: true });
+			return;
+		}
+		const primary = [...entries.values()][0]?.runner.currentState;
+		live.setState(options.getLiveState?.() ?? primary ?? {});
+		options.onLiveAssembled?.({ skippedUnloadedRunners: false });
+	}
+	async function loadThenAssemble() {
+		await Promise.all([...entries.values()].map((entry) => entry.runner.snapshot()));
+		assembleLive();
+	}
+	return {
+		stream: options.stream,
+		live,
+		refreshLive: assembleLive,
+		loadAndRefreshLive: loadThenAssemble,
+		get names() {
+			return [...entries.keys()];
+		},
+		register(processor, opts) {
+			const name = opts?.name ?? processor.contract.slug;
+			if (entries.has(name)) throw new Error(`Stream processor name "${name}" is already registered on this registry`);
+			for (const [registeredName, entry] of entries) if (entry.processor === processor) throw new Error(`this exact processor instance is already registered as "${registeredName}" — construct one instance per registration`);
+			const recovery = opts?.recovery ? durableObjectRecovery({
+				storage: ctx.storage,
+				name,
+				stream: options.stream,
+				version: options.version,
+				armAlarm: (atMs) => void setAlarmSlice(`keepalive:${name}`, atMs),
+				waitUntil: (work) => ctx.waitUntil(work),
+				now
+			}) : void 0;
+			const runner = new StreamProcessorRunner({
+				processor,
+				stream: options.stream,
+				durability: {
+					progress: durableObjectProgressStore({
+						storage: ctx.storage,
+						name,
+						resetForStream: opts?.resetForStream,
+						reductionCache: opts?.reductionCache
+					}),
+					...recovery === void 0 ? {} : { recovery }
+				},
+				keepAlive: (work) => ctx.waitUntil(work()),
+				now
+			});
+			entries.set(name, {
+				processor,
+				runner,
+				...recovery === void 0 ? {} : { recovery }
+			});
+			runner.observeStateChanges(() => assembleLive());
+			return processor;
+		},
+		reads(processorOrName) {
+			const entry = typeof processorOrName === "string" ? requireEntry(processorOrName) : requireEntryForInstance(processorOrName, "reads");
+			const { runner } = entry;
+			return {
+				snapshot: () => runner.snapshot(),
+				getRuntimeState: async () => {
+					return {
+						...await entry.processor.getRuntimeState(),
+						snapshot: await runner.snapshot()
+					};
+				},
+				waitUntilEvent: (input) => "offset" in input ? runner.waitUntilEvent(input) : runner.waitUntilEvent(input),
+				catchUp: () => runner.catchUp(),
+				get currentAcknowledgedThroughOffset() {
+					return runner.currentAcknowledgedThroughOffset;
+				},
+				get currentStreamId() {
+					return runner.currentStreamId;
+				},
+				get currentState() {
+					return runner.currentState;
+				},
+				get isLoaded() {
+					return runner.isLoaded;
+				}
+			};
+		},
+		observeStateChanges(processor, observer) {
+			return requireEntryForInstance(processor, "observeStateChanges").runner.observeStateChanges(observer);
+		},
+		async catchUp(name) {
+			await requireEntry(name).runner.catchUp();
+		},
+		resetRecoveryBackoff(name) {
+			requireEntry(name).recovery?.resetBackoff?.();
+		},
+		handleAlarm(alarmInfo) {
+			return tracing.enterSpan("alarm processor keepalive", async (span) => {
+				platformAlarmAtMs = null;
+				const firedAt = now();
+				for (const [name, atMs] of alarmSlices) if (atMs <= firedAt) alarmSlices.delete(name);
+				span.setAttribute("iterate.alarm.kind", "processor_keepalive");
+				if (alarmInfo !== void 0) {
+					span.setAttribute("iterate.alarm.is_retry", alarmInfo.isRetry);
+					span.setAttribute("iterate.alarm.retry_count", alarmInfo.retryCount);
+				}
+				try {
+					const failures = [];
+					for (const [name, entry] of entries) try {
+						await entry.runner.handleAlarm(alarmInfo);
+					} catch (error) {
+						console.error(`stream processor "${name}" alarm handling failed`, error);
+						failures.push(error);
+					}
+					if (failures.length > 0) throw failures[0];
+				} finally {
+					await reconcileAlarm();
+				}
+			});
+		},
+		setAlarmSlice,
+		getAlarmSlice: (name) => alarmSlices.get(name) ?? null,
+		async wakeStreamProcessor(args) {
+			if (args.stream.projectId !== options.projectId || args.stream.path !== options.path) throw new Error(`wakeStreamProcessor coordinate mismatch: wake for ${args.stream.projectId ?? "null"}:${args.stream.path} does not match registry ${options.projectId ?? "null"}:${options.path}`);
+			const name = resolveProcessorName(args);
+			const entry = requireEntry(name);
+			if (!z.uuid().safeParse(args.stream.streamId).success) throw new Error(`wakeStreamProcessor streamId must be a UUID`);
+			const opened = await entry.runner.openHostedEventBatchCallback(args.stream.streamId);
+			const processEventBatch = (batch) => {
+				const { reportDeliveryResult, ...frame } = batch;
+				if (frame.projectId !== options.projectId || frame.path !== options.path || frame.streamId !== args.stream.streamId) throw new Error(`hosted processor "${name}" received batch for ${frame.projectId ?? "null"}:${frame.path}:${frame.streamId}; expected ${options.projectId ?? "null"}:${options.path}:${args.stream.streamId}`);
+				let retainedResultCallback;
+				try {
+					retainedResultCallback = retainCallback(reportDeliveryResult);
+				} catch (error) {
+					console.error("stream wake delivery result callback could not be retained", { error });
+					return;
+				}
+				let attempt;
+				try {
+					attempt = opened.processEventBatch(frame);
+				} catch (error) {
+					attempt = Promise.reject(error);
+				}
+				const report = attempt.then(() => reportWakeDeliveryResult(retainedResultCallback, { outcome: "ok" }), (error) => reportWakeDeliveryResult(retainedResultCallback, {
+					outcome: "error",
+					error: serializeWakeDeliveryError(error)
+				}));
+				ctx.waitUntil(report.finally(() => {
+					try {
+						retainedResultCallback[Symbol.dispose]();
+					} catch (error) {
+						console.warn("stream wake delivery result callback disposal failed", { error });
+					}
+				}));
+			};
+			const capabilities = hostRuntimeCapabilities(entry.processor, {
+				now,
+				snapshot: () => entry.runner.snapshot()
+			});
+			return {
+				streamId: args.stream.streamId,
+				checkpointOffset: opened.checkpointOffset,
+				processEventBatch,
+				openedBy: { processor: { announcement: announceContract(entry.processor.contract) } },
+				...capabilities
+			};
+		}
+	};
+}
+//#endregion
+//#region src/processors/processor-facet.ts
+/**
+* Where the configured identity lives in the facet's own kv. Exported so a
+* subclass's own doors can self-heal a fresh incarnation (re-run the
+* idempotent `configure` from the stash) before the base's boot microtask has
+* run — see apps/os `ProcessorFacet.#requireRegistry`.
+*/
+const FACET_IDENTITY_KEY = "iterate:processor-facet:identity";
+/**
+* A view of `target` with `overrides` in front and everything else passed
+* through. Proxies (not spreads or Object.create) because DurableObjectState
+* and DurableObjectStorage are host objects: their methods must be invoked
+* with the REAL receiver or workerd throws "Illegal invocation". (The same
+* overlay as sdk.ts's `selfAlarmState` facade — duplicated here because the
+* sdk entry drags its whole dependency graph along.)
+*/
+function overlay(target, overrides) {
+	return new Proxy(target, { get(object, prop) {
+		if (Object.hasOwn(overrides, prop)) return overrides[prop];
+		const value = Reflect.get(object, prop, object);
+		return typeof value === "function" ? value.bind(object) : value;
+	} });
+}
+/**
+* A facet's `DurableObjectState` facade for `createStreamProcessorRegistry`:
+* ONLY `storage.setAlarm` / `storage.deleteAlarm` / `storage.getAlarm` are
+* overridden to dial the parent's {@link ProcessorFacetAlarmProxy}; kv,
+* waitUntil, and everything else pass through untouched. `parentAlarms` is
+* invoked PER CALL — the parent stub must be resolved lazily from the stashed
+* identity, because the recovery adapter's boot reconcile issues alarm calls
+* at construction and a stub captured once would outlive its RPC session.
+*/
+function facetProcessorDurableObjectState(ctx, parentAlarms) {
+	return overlay(ctx, { storage: overlay(ctx.storage, {
+		setAlarm: async (scheduledTime) => {
+			disposeIgnoredRpcResult(await parentAlarms().proxySetAlarm(typeof scheduledTime === "number" ? scheduledTime : scheduledTime.getTime()));
+		},
+		deleteAlarm: async () => {
+			disposeIgnoredRpcResult(await parentAlarms().proxyDeleteAlarm());
+		},
+		getAlarm: async () => await parentAlarms().proxyGetAlarm()
+	}) });
+}
+/**
+* Plain-copy an `AlarmInvocationInfo` before a facet hop. The platform hands
+* the parent's `alarm()` a host object that does not serialize across RPC;
+* a parent replaying a fire into {@link ProcessorFacet.handleAlarm} must send
+* this copy instead.
+*/
+function plainAlarmInvocationInfo(info) {
+	if (info === void 0) return void 0;
+	const { scheduledTime } = info;
+	return {
+		...scheduledTime === void 0 ? {} : { scheduledTime },
+		isRetry: info.isRetry,
+		retryCount: info.retryCount
+	};
+}
+/**
+* Generic base for hosting stream processors in a Durable Object facet.
+* Subclasses are the per-host composition (the facets task's target shape) and
+* supply exactly two things: how to dial the parent's alarm proxy and what
+* this host runs —
+*
+* ```ts
+* export class AgentProcessors extends ProcessorFacet<Env> {
+*   protected parentAlarms({ parentName }: ProcessorFacetIdentity) {
+*     return this.env.STREAM.getByName(parentName);
+*   }
+*   protected createHost({ path, projectId }: ProcessorFacetIdentity): ProcessorFacetHost {
+*     const stream = ...; // dial the parent stream
+*     return {
+*       stream,
+*       version: workerVersion(this.env),
+*       registerProcessors: (registry) => {
+*         registry.register(
+*           new AgentProcessor({ stream, path, projectId, ... }),
+*           { recovery: true, name: "agent" },
+*         );
+*       },
+*     };
+*   }
+* }
+* ```
+*
+* The parent creates it with `ctx.facets.get(name, () => ({ class:
+* ctx.exports.AgentProcessors }))`, calls `configure()` once (idempotent), and
+* routes wakes/alarms/doors to the RPC surface below.
+*
+* THIS CLASS MUST NEVER DEFINE `alarm()` — and neither may a subclass. The
+* fire arrives as `handleAlarm` (an ordinary RPC verb) instead: workerd
+* reserves `alarm` for its native handler, and with one present a failed
+* native `setAlarm` poisons the facet's output gate (workerd#6810). The
+* constructor enforces this.
+*/
+var ProcessorFacet = class extends DurableObject {
+	#host;
+	constructor(ctx, env) {
+		super(ctx, env);
+		if ("alarm" in this && typeof this.alarm === "function") throw new Error(`${this.constructor.name} must not define alarm(): facets have no native alarms (workerd#6810 — a failed setAlarm would poison this facet's output gate). The parent's fire arrives as handleAlarm() instead.`);
+		Promise.resolve().then(() => {
+			try {
+				if (this.#readIdentity() !== void 0) this.#requireHost();
+			} catch (error) {
+				console.error("ProcessorFacet boot host construction failed", error);
+			}
+		});
+	}
+	/**
+	* First-contact identity stash, idempotent: re-configuring with the same
+	* identity is a no-op (and ensures the host is built); a DIFFERENT identity
+	* throws — a facet's coordinate never changes, so a mismatch is a miswire,
+	* not a migration.
+	*/
+	configure(identity) {
+		const stashed = this.#readIdentity();
+		if (stashed !== void 0) {
+			if (stashed.parentName !== identity.parentName || stashed.projectId !== identity.projectId || stashed.path !== identity.path) throw new Error(`ProcessorFacet is configured for ${stashed.projectId ?? "null"}:${stashed.path} (parent "${stashed.parentName}") and cannot be re-configured for ${identity.projectId ?? "null"}:${identity.path} (parent "${identity.parentName}")`);
+			this.#requireHost();
+			return;
+		}
+		this.ctx.storage.kv.put(FACET_IDENTITY_KEY, {
+			parentName: identity.parentName,
+			projectId: identity.projectId,
+			path: identity.path
+		});
+		this.#requireHost();
+	}
+	/** The wake door — the parent's colocated delivery dial. Routes to the
+	* registry: name-first resolution, coordinate fence, per-batch settlement
+	* through each batch's independent `reportDeliveryResult`. */
+	wakeStreamProcessor(request) {
+		return this.#requireHost().registry.wakeStreamProcessor(request);
+	}
+	/**
+	* The parent's alarm replay door — deliberately NOT named `alarm` (see the
+	* class doc). The parent plain-copies its `AlarmInvocationInfo`
+	* ({@link plainAlarmInvocationInfo}) and awaits this; a rejection propagates
+	* so the parent can rethrow and get the platform's alarm retry.
+	*/
+	async handleAlarm(info) {
+		if (this.#readIdentity() === void 0) {
+			console.warn("ProcessorFacet.handleAlarm before configure(); nothing to revive");
+			return;
+		}
+		await this.#requireHost().registry.handleAlarm(plainAlarmInvocationInfo(info));
+	}
+	/** One consistent read of a hosted processor's committed fold. `name` may be
+	* omitted on a single-processor host. */
+	async snapshot(args) {
+		return await this.#reads(args?.name).snapshot();
+	}
+	/** The hosted processor's runtime state (runner snapshot + contributed
+	* runtime bag). `name` may be omitted on a single-processor host. */
+	async getRuntimeState(args) {
+		return await this.#reads(args?.name).getRuntimeState();
+	}
+	/** Resolve once the named processor's acknowledged cursor reaches `offset` —
+	* the read-your-writes barrier. The subscription catalog's uniform
+	* `waitUntilProcessed` delegates its facet-placed processor rows here. */
+	async waitUntilProcessed(args) {
+		const { name, ...input } = args;
+		await this.#reads(name).waitUntilEvent(input);
+	}
+	/** Pull the named processor through the durable stream tail — the parent
+	* facade's catch-up-before-snapshot leg, dialed before every facet read.
+	* `name` may be omitted on a single-processor host. */
+	async catchUp(args) {
+		await this.#reads(args?.name).catchUp();
+	}
+	/** Read a transient snapshot or delta for the parent's current stream lifetime.
+	* Cold or replaced processors hydrate from durable progress. Warm reads use
+	* committed local state: polling must not call back into the parent stream
+	* for every processor while it is delivering events to this facet. */
+	async readLiveState(args) {
+		const { registry } = this.#requireHost();
+		if (registry.names.some((name) => {
+			const reads = registry.reads(name);
+			return !reads.isLoaded || reads.currentStreamId !== args.streamId;
+		})) await registry.loadAndRefreshLive();
+		else registry.refreshLive();
+		return registry.live.readSince(args.cursor, { patchVersion: args.patchVersion });
+	}
+	/** Direct subscriptions retain their callbacks across the Workers RPC hop. */
+	liveState() {
+		const { registry } = this.#requireHost();
+		return {
+			get: async () => {
+				await registry.loadAndRefreshLive();
+				return registry.live.getState();
+			},
+			subscribe: async (onUpdate, options) => {
+				await registry.loadAndRefreshLive();
+				const subscription = registry.live.subscribe(onUpdate, options);
+				return {
+					ping: () => subscription.ping(),
+					unsubscribe: () => subscription.unsubscribe(),
+					[Symbol.dispose]: () => subscription.unsubscribe()
+				};
+			}
+		};
+	}
+	#readIdentity() {
+		return this.ctx.storage.kv.get(FACET_IDENTITY_KEY);
+	}
+	#requireIdentity() {
+		const identity = this.#readIdentity();
+		if (identity === void 0) throw new Error("ProcessorFacet has no stashed identity yet — call configure() first");
+		return identity;
+	}
+	#requireHost() {
+		if (this.#host === void 0) {
+			const identity = this.#requireIdentity();
+			const host = this.createHost(identity);
+			const registry = createStreamProcessorRegistry(facetProcessorDurableObjectState(this.ctx, () => this.parentAlarms(this.#requireIdentity())), {
+				stream: host.stream,
+				path: identity.path,
+				projectId: identity.projectId,
+				version: host.version,
+				...host.now === void 0 ? {} : { now: host.now },
+				...host.getLiveState === void 0 ? {} : { getLiveState: host.getLiveState }
+			});
+			host.registerProcessors(registry);
+			this.#host = { registry };
+		}
+		return this.#host;
+	}
+	#reads(name) {
+		const { registry } = this.#requireHost();
+		if (name !== void 0) return registry.reads(name);
+		const names = registry.names;
+		if (names.length === 1) return registry.reads(names[0]);
+		throw new Error(`this facet hosts ${names.length} processors (${names.join(", ") || "none"}); pass a name`);
+	}
+};
+//#endregion
+export { createStreamProcessorRegistry as a, compactPatch as c, disposeIgnoredRpcResult as d, isThenable as f, plainAlarmInvocationInfo as i, applyPatch as l, ProcessorFacet as n, LiveState as o, retainCallback as p, facetProcessorDurableObjectState as r, applyCompactPatch as s, FACET_IDENTITY_KEY as t, diff as u };
+
+//# sourceMappingURL=cloudflare-BTm90gQ4.mjs.map