iterate 0.2.6 → 0.3.0

package/dist/stream-processor-keepalive-DAQTP6m3.mjs

@@ -0,0 +1,2082 @@
+import { z } from "zod";
+import { RpcTarget } from "@iterate-com/capnweb";
+//#region src/processors/rpc-types.ts
+/** Maximum serialized durable-event bytes one Stream read may return. */
+const MAX_STREAM_EVENT_READ_BYTE_LIMIT = 8 * 1024 * 1024;
+/**
+* A durable receiver's declaration that it cannot accept ANY batch right now —
+* part of the delivery contract, not an implementation detail. The subscription's cursor row
+* treats a rejection carrying this name as "the receiver is down/not ready"
+* and backs off or halts even under `onFailingEvent: "skip"`,
+* because failing-event confirmation is a verdict about ONE event and an unavailable
+* receiver fails every event: confirming skips during an outage window steps
+* over healthy events forever (the bootstrap incarnation: the project-worker
+* feed called its receiver before the config repo seeded, and permanently skipped the
+* events that raced the seed).
+*
+* Matched by NAME, not instanceof: the rejection crosses Workers RPC hops
+* (loopback itx roots, DO bindings), which preserve `error.name` but not
+* class identity.
+*/
+var StreamReceiverUnavailableError = class StreamReceiverUnavailableError extends Error {
+	static NAME = "StreamReceiverUnavailableError";
+	name = StreamReceiverUnavailableError.NAME;
+};
+/** A compare-and-append assertion lost to another committed stream event. */
+var StreamOffsetConflictError = class StreamOffsetConflictError extends Error {
+	static NAME = "StreamOffsetConflictError";
+	name = StreamOffsetConflictError.NAME;
+};
+/** An operation was bound to a stream lifetime that this path no longer names. */
+var StreamIdMismatchError = class StreamIdMismatchError extends Error {
+	static NAME = "StreamIdMismatchError";
+	name = StreamIdMismatchError.NAME;
+};
+/** Canonical guarded-append rejection text, including across RPC hops that
+* normalize the custom error name to `Error`. */
+function streamIdMismatchMessage(expectedStreamId, actualStreamId) {
+	return `stream ID changed (${expectedStreamId} -> ${String(actualStreamId)}); append rejected`;
+}
+const STREAM_ID_MISMATCH_MESSAGE = /^stream ID changed \(.+ -> .+\); append rejected$/;
+/**
+* Match a guarded append rejected because its source stream was recreated.
+* Durable Object RPC preserves the custom name; CapnWeb can reduce it to a
+* plain Error, so the exact canonical message remains a narrow fallback.
+*/
+function isStreamIdMismatchError(error) {
+	const candidate = error;
+	return candidate?.name === StreamIdMismatchError.NAME || candidate?.name === "Error" && typeof candidate.message === "string" && STREAM_ID_MISMATCH_MESSAGE.test(candidate.message);
+}
+/** Canonical compare-and-append conflict text, including across RPC hops that
+* normalize the custom error name to `Error`. */
+function streamOffsetConflictMessage(expectedOffset, actualOffset) {
+	return `expected next offset ${expectedOffset}, found ${actualOffset}`;
+}
+const STREAM_OFFSET_CONFLICT_MESSAGE = /^expected next offset \d+, found \d+$/;
+/**
+* Match by name because Durable Object RPC preserves names, not prototypes.
+* CapnWeb's public itx boundary currently normalizes custom error names to
+* `Error`, so retain an exact message fallback for that hop. Keep this
+* deliberately narrow: callers use the result to retry a compare-and-append.
+*/
+function isStreamOffsetConflictError(error) {
+	const candidate = error;
+	return candidate?.name === StreamOffsetConflictError.NAME || candidate?.name === "Error" && typeof candidate.message === "string" && STREAM_OFFSET_CONFLICT_MESSAGE.test(candidate.message);
+}
+function isStreamReceiverUnavailableError(error) {
+	return error?.name === StreamReceiverUnavailableError.NAME;
+}
+//#endregion
+//#region src/processors/stream-handle.ts
+/**
+* Resolve the path accepted by `stream.at(path)`. Absolute paths start at the
+* stream root; relative paths start at `basePath`; `..` may climb only as far
+* as the root. Keeping this next to {@link ProcessorStream} lets processor
+* appends decide whether a resolved destination is their own stream without
+* relying on RPC-target object identity.
+*/
+function resolveStreamPath(basePath, streamPath) {
+	const segments = streamPath.startsWith("/") ? [] : basePath.split("/").filter(Boolean);
+	for (const segment of streamPath.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length === 0) throw new Error(`stream path "${streamPath}" escapes the stream root (resolved from "${basePath}")`);
+			segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+//#endregion
+//#region src/processors/stream-runtime-metrics.ts
+/**
+* Fixed-capacity ring of latency samples. `stats()` is `null` until the first
+* sample — surfaces render "—" instead of a made-up number.
+*/
+var LatencyRing = class {
+	#capacity;
+	#samples = [];
+	#next = 0;
+	#last = 0;
+	#lastAt = 0;
+	constructor(capacity = 32) {
+		if (!Number.isInteger(capacity) || capacity <= 0) throw new Error("LatencyRing capacity must be a positive integer");
+		this.#capacity = capacity;
+	}
+	record(ms, atMs) {
+		if (!Number.isFinite(ms)) return;
+		const sample = Math.max(0, Math.round(ms));
+		if (this.#samples.length < this.#capacity) this.#samples.push(sample);
+		else this.#samples[this.#next] = sample;
+		this.#next = (this.#next + 1) % this.#capacity;
+		this.#last = sample;
+		this.#lastAt = atMs;
+	}
+	stats() {
+		if (this.#samples.length === 0) return null;
+		const sorted = [...this.#samples].sort((a, b) => a - b);
+		const rank = (q) => sorted[Math.max(0, Math.ceil(q * sorted.length) - 1)];
+		return {
+			last: this.#last,
+			p50: rank(.5),
+			p95: rank(.95),
+			samples: sorted.length,
+			lastAt: this.#lastAt
+		};
+	}
+};
+/**
+* 60 one-second buckets of {count, bytes}. Stale slots (lapped by the ring)
+* are ignored at read time, so a burst followed by silence decays to zero
+* without a sweeper.
+*/
+var MinuteBuckets = class {
+	#seconds = new Array(60).fill(-1);
+	#counts = new Array(60).fill(0);
+	#bytes = new Array(60).fill(0);
+	bump(atMs, count, bytes) {
+		const second = Math.floor(atMs / 1e3);
+		const slot = (second % 60 + 60) % 60;
+		if (this.#seconds[slot] !== second) {
+			this.#seconds[slot] = second;
+			this.#counts[slot] = 0;
+			this.#bytes[slot] = 0;
+		}
+		this.#counts[slot] += count;
+		this.#bytes[slot] += bytes;
+	}
+	lastMinute(nowMs) {
+		const { count, bytes } = this.window(nowMs, 60);
+		return {
+			count,
+			bytes,
+			perSecond: count / 60
+		};
+	}
+	/** Totals over the trailing `seconds` (≤60) — short windows make responsive rates. */
+	window(nowMs, seconds) {
+		const nowSecond = Math.floor(nowMs / 1e3);
+		let count = 0;
+		let bytes = 0;
+		for (let slot = 0; slot < 60; slot += 1) {
+			const second = this.#seconds[slot];
+			if (second < 0 || second > nowSecond || second <= nowSecond - seconds) continue;
+			count += this.#counts[slot];
+			bytes += this.#bytes[slot];
+		}
+		return {
+			count,
+			bytes
+		};
+	}
+	/**
+	* The raw per-second buckets, oldest→newest, always exactly 60 entries
+	* (silent seconds are zero) — what a UI graphs directly, so the graph is
+	* the measurement rather than a client-side reconstruction of it.
+	*/
+	series(nowMs) {
+		const nowSecond = Math.floor(nowMs / 1e3);
+		const counts = new Array(60).fill(0);
+		const bytes = new Array(60).fill(0);
+		for (let slot = 0; slot < 60; slot += 1) {
+			const second = this.#seconds[slot];
+			if (second < 0 || second > nowSecond || second <= nowSecond - 60) continue;
+			const index = 59 - (nowSecond - second);
+			counts[index] = this.#counts[slot];
+			bytes[index] = this.#bytes[slot];
+		}
+		return {
+			counts,
+			bytes
+		};
+	}
+};
+/** The stream Durable Object's in-memory throughput accounting. */
+var StreamRuntimeMetrics = class {
+	#measuredSinceMs;
+	ingress = new MinuteBuckets();
+	egress = new MinuteBuckets();
+	constructor(nowMs) {
+		this.#measuredSinceMs = nowMs;
+	}
+	report(nowMs) {
+		const direction = (buckets) => {
+			const trailing5s = buckets.window(nowMs, 5);
+			return {
+				perSecond5s: trailing5s.count / 5,
+				bytesPerSecond5s: trailing5s.bytes / 5,
+				lastMinute: buckets.lastMinute(nowMs),
+				series: buckets.series(nowMs)
+			};
+		};
+		return {
+			measuredSince: new Date(this.#measuredSinceMs).toISOString(),
+			reportedAt: new Date(nowMs).toISOString(),
+			ingress: direction(this.ingress),
+			egress: direction(this.egress)
+		};
+	}
+};
+/**
+* Age an event-driven throughput snapshot against the local wall clock. This
+* keeps trailing windows truthful during silence without polling the stream.
+*/
+function ageStreamThroughputMetrics(metrics, nowMs) {
+	const reportedAtMs = Date.parse(metrics.reportedAt);
+	if (!Number.isFinite(reportedAtMs)) return metrics;
+	const elapsedSeconds = Math.max(0, Math.floor(nowMs / 1e3) - Math.floor(reportedAtMs / 1e3));
+	if (elapsedSeconds === 0) return metrics;
+	const age = (report) => {
+		const shift = (values) => {
+			const seconds = Math.min(values.length, elapsedSeconds);
+			return [...values.slice(seconds), ...new Array(seconds).fill(0)];
+		};
+		const counts = shift(report.series.counts);
+		const bytes = shift(report.series.bytes);
+		const sum = (values) => values.reduce((total, value) => total + value, 0);
+		const count = sum(counts);
+		const byteCount = sum(bytes);
+		return {
+			perSecond5s: sum(counts.slice(-5)) / 5,
+			bytesPerSecond5s: sum(bytes.slice(-5)) / 5,
+			lastMinute: {
+				count,
+				bytes: byteCount,
+				perSecond: count / 60
+			},
+			series: {
+				counts,
+				bytes
+			}
+		};
+	};
+	return {
+		...metrics,
+		ingress: age(metrics.ingress),
+		egress: age(metrics.egress)
+	};
+}
+/**
+* The mutual ping's NTP-style math, shared by both requesters (a stream
+* pinging a callback owner; anything pinging the stream). The requester stamps
+* `t0` and observes `t3`; the responder reports receive/reply-send times on
+* ITS clock. RTT excludes responder processing time; `clockOffsetMs`
+* estimates `responderClock - requesterClock`.
+*/
+function pingRoundTrip(reply, t3) {
+	return {
+		rttMs: Math.max(0, t3 - reply.t0 - (reply.t2 - reply.t1)),
+		clockOffsetMs: (reply.t1 - reply.t0 + (reply.t2 - t3)) / 2
+	};
+}
+//#endregion
+//#region src/processors/event-consumption-metrics.ts
+/** In-flight own-append correlation entries beyond this are dropped oldest-first. */
+const MAX_PENDING_OWN_APPENDS = 16;
+var EventConsumptionMetrics = class {
+	#measuredSinceMs;
+	#consumeOwnAppend = new LatencyRing();
+	#appendRoundTrip = new LatencyRing();
+	#deliveryAge = new LatencyRing();
+	#ingest = new LatencyRing();
+	#batchesIngested = 0;
+	#eventsIngested = 0;
+	#clockOffsetMs = null;
+	/** Highest offset this host has ingested through (see noteBatchIngested). */
+	#ingestedThroughOffset = 0;
+	/** Own appends awaiting their loop-back delivery: committed offset + call-start time. */
+	#pendingOwnAppends = [];
+	constructor(nowMs) {
+		this.#measuredSinceMs = nowMs;
+	}
+	/**
+	* An `append()` this host issued resolved: `t0` is when the host called it,
+	* `atMs` is when the commit came back, and `maxCommittedOffset` is the
+	* highest committed offset that CAN come back to this host — the caller's
+	* judgement, because only the caller knows what it consumes. `null` means
+	* the append carried nothing this host will ever be delivered, and is timed
+	* for its round trip alone.
+	*/
+	noteAppendCommitted(args) {
+		this.#appendRoundTrip.record(args.atMs - args.t0, args.atMs);
+		if (args.maxCommittedOffset === null) return;
+		if (args.maxCommittedOffset <= this.#ingestedThroughOffset) {
+			this.#consumeOwnAppend.record(args.atMs - args.t0, args.atMs);
+			return;
+		}
+		this.#pendingOwnAppends.push({
+			offset: args.maxCommittedOffset,
+			t0: args.t0
+		});
+		if (this.#pendingOwnAppends.length > MAX_PENDING_OWN_APPENDS) this.#pendingOwnAppends.splice(0, this.#pendingOwnAppends.length - MAX_PENDING_OWN_APPENDS);
+	}
+	/** One delivered batch fully ingested (fold applied / SQLite write done). */
+	noteBatchIngested(args) {
+		this.#batchesIngested += 1;
+		this.#eventsIngested += args.ingestedOffsets.length;
+		this.#ingestedThroughOffset = Math.max(this.#ingestedThroughOffset, args.ingestedThroughOffset);
+		this.#ingest.record(args.atMs - args.ingestStartedAtMs, args.atMs);
+		if (args.newestEventCreatedAtMs !== void 0 && Number.isFinite(args.newestEventCreatedAtMs)) {
+			const hostNowOnStreamClock = args.atMs - (this.#clockOffsetMs ?? 0);
+			this.#deliveryAge.record(hostNowOnStreamClock - args.newestEventCreatedAtMs, args.atMs);
+		}
+		if (this.#pendingOwnAppends.length > 0) {
+			const stillPending = [];
+			for (const pending of this.#pendingOwnAppends) {
+				if (pending.offset > args.ingestedThroughOffset) {
+					stillPending.push(pending);
+					continue;
+				}
+				if (args.ingestedOffsets.includes(pending.offset)) this.#consumeOwnAppend.record(args.atMs - pending.t0, args.atMs);
+			}
+			this.#pendingOwnAppends = stillPending;
+		}
+	}
+	/**
+	* The stream pinged this host: `t0` is the stream's send time (stream
+	* clock), `t1` the host's receive time (host clock). With a one-way-delay
+	* estimate (half the host's measured transport RTT, when it has one) this
+	* yields the host−stream clock offset used to correct delivery ages.
+	*/
+	notePingObserved(args) {
+		this.#clockOffsetMs = args.t1 - args.t0 - (args.oneWayEstimateMs ?? 0);
+	}
+	/** The host's event connection reopened: in-flight own-append correlations are void. */
+	clearPendingAppends() {
+		this.#pendingOwnAppends = [];
+	}
+	report() {
+		return {
+			measuredSince: new Date(this.#measuredSinceMs).toISOString(),
+			consumeOwnAppendMs: this.#consumeOwnAppend.stats(),
+			appendRoundTripMs: this.#appendRoundTrip.stats(),
+			deliveryAgeMs: this.#deliveryAge.stats(),
+			ingestMs: this.#ingest.stats(),
+			batchesIngested: this.#batchesIngested,
+			eventsIngested: this.#eventsIngested,
+			clockOffsetMs: this.#clockOffsetMs
+		};
+	}
+};
+//#endregion
+//#region src/processors/schemas.ts
+/**
+* Maximum number of stream-to-stream copies retained in one event's provenance.
+* Cycles normally stop a chain earlier; this bounds acyclic graphs and the
+* serialized event growth they can produce.
+*/
+const MAX_COPIED_FROM_HOPS = 32;
+/** Append input before the stream assigns offset and timestamp. */
+const StreamEventInput = z.strictObject({
+	type: z.string(),
+	payload: z.record(z.string(), z.unknown()).optional(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	source: z.strictObject({
+		processor: z.strictObject({
+			slug: z.string(),
+			version: z.string(),
+			stream: z.strictObject({
+				path: z.string().trim().min(1),
+				projectId: z.string().trim().min(1).nullable(),
+				/** Exact lifetime of the processor's home stream. */
+				streamId: z.uuid()
+			}),
+			whileProcessing: z.strictObject({
+				offset: z.number().int().nonnegative(),
+				type: z.string().trim().min(1)
+			}).optional()
+		}).optional(),
+		copiedFrom: z.array(z.strictObject({
+			/** Name of the source stream's subscription that copied this event. */
+			name: z.string().trim().min(1),
+			/** Random identity assigned when that source stream's storage was created. */
+			streamId: z.uuid(),
+			/** Creation time of that source stream, used to order destructive recreations. */
+			streamCreatedAt: z.string().trim().min(1),
+			/** Configure or cursor-set event that started this delivered copy. */
+			cursorChangedAtSourceOffset: z.number().int().positive(),
+			createdAt: z.string(),
+			offset: z.number().int().nonnegative(),
+			path: z.string().trim().min(1),
+			projectId: z.string().trim().min(1).nullable(),
+			type: z.string().trim().min(1)
+		})).min(1).max(32).optional()
+	}).optional(),
+	idempotencyKey: z.string().trim().min(1).optional(),
+	/**
+	* Ephemeral events receive real stream offsets but their bodies are NEVER
+	* written to the Stream Durable Object's SQLite. The current Durable Object
+	* incarnation keeps up to 10 MiB of serialized ephemeral events in memory,
+	* evicting the oldest first. A restart forgets all of them.
+	*
+	* Range reads exclude ephemeral events unless `includeEphemeral: true`;
+	* point reads by offset return one only while it remains in memory. Session
+	* connections replay currently buffered ephemeral events after their replay
+	* cursor and receive new ones live. Durable subscriptions never deliver
+	* them. An ephemeral event cannot have an idempotency key.
+	*
+	* Nothing durable may depend on an ephemeral event. Use it for streaming
+	* signals whose durable truth lands separately — for example, LLM response
+	* chunks followed by a durable assistant context item.
+	* `z.literal(true)`, not boolean: absent = durable, so committed rows stay
+	* self-describing and `ephemeral: false` is a loud input error, not a
+	* silent synonym for omitting the flag.
+	*/
+	ephemeral: z.literal(true).optional()
+}).superRefine((event, context) => {
+	if (event.ephemeral === true && event.idempotencyKey !== void 0) context.addIssue({
+		code: "custom",
+		message: "ephemeral events cannot have an idempotencyKey",
+		path: ["idempotencyKey"]
+	});
+});
+/** Offset-assigned stream event after commit. */
+const StreamEvent = StreamEventInput.safeExtend({
+	offset: z.number().int().nonnegative(),
+	createdAt: z.string(),
+	path: z.string().trim().min(1)
+});
+/**
+* One known stream in a project's reduced state — what the project processor
+* records per agent/repo/secret/stream and what the collection `list()`
+* methods return.
+*/
+const StreamListItem = z.object({
+	createdAt: z.string(),
+	path: z.string()
+});
+//#endregion
+//#region src/processors/processor-contracts.ts
+/**
+* Merge one processor configuration patch into its current configuration.
+*
+* Configuration patches recurse only through plain JSON objects. Arrays,
+* scalars, and `null` replace the previous value wholesale; omitted keys are
+* retained. Processors validate the merged result with their own complete
+* configuration schema before storing it in reduced state.
+*/
+function mergeProcessorConfig(base, patch) {
+	if (!isPlainObject(base) || !isPlainObject(patch)) return patch;
+	const merged = { ...base };
+	for (const [key, patchValue] of Object.entries(patch)) {
+		const baseValue = merged[key];
+		merged[key] = isPlainObject(baseValue) && isPlainObject(patchValue) ? mergeProcessorConfig(baseValue, patchValue) : patchValue;
+	}
+	return merged;
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/**
+* Rebuild the concrete Zod envelope for one committed event from its catalog
+* key plus `payloadSchema`. Contracts author event definitions as plain
+* `{ description, payloadSchema }` values keyed by the event type string, so
+* replay and live delivery share one validation path.
+*/
+function getEventSchema(args) {
+	return z.looseObject({
+		type: z.literal(args.type),
+		payload: args.payloadSchema,
+		metadata: StreamEvent.shape.metadata,
+		source: StreamEvent.shape.source,
+		idempotencyKey: StreamEvent.shape.idempotencyKey,
+		ephemeral: StreamEvent.shape.ephemeral,
+		offset: StreamEvent.shape.offset,
+		createdAt: StreamEvent.shape.createdAt,
+		path: StreamEvent.shape.path
+	}).superRefine(rejectEphemeralIdempotency);
+}
+/** The envelope `ephemeral` slot: for a definition marked `ephemeral: true`,
+* absent defaults to `true` and an explicit `false` FAILS the parse — the
+* contract, not the append site, decides that the event never becomes a
+* durable stream fact. */
+function ephemeralEnvelopeSchema(forced, standard) {
+	return forced === true ? z.literal(true).default(true) : standard;
+}
+function rejectEphemeralIdempotency(event, context) {
+	if (event.ephemeral === true && event.idempotencyKey !== void 0) context.addIssue({
+		code: "custom",
+		message: "ephemeral events cannot have an idempotencyKey",
+		path: ["idempotencyKey"]
+	});
+}
+/**
+* `getEventSchema` without offset/createdAt (and strict, so an accidental
+* `offset` key on an append input fails loudly). Gives pre-append policy code
+* the same payload validation as reducers, without fabricating a committed
+* event just to get at the typed payload.
+*/
+function getEventInputSchema(args) {
+	return z.strictObject({
+		type: z.literal(args.type),
+		payload: args.payloadSchema,
+		metadata: StreamEventInput.shape.metadata,
+		source: StreamEventInput.shape.source,
+		idempotencyKey: StreamEventInput.shape.idempotencyKey,
+		ephemeral: ephemeralEnvelopeSchema(args.ephemeral, StreamEventInput.shape.ephemeral)
+	}).superRefine(rejectEphemeralIdempotency);
+}
+/**
+* Memoized twins of {@link getEventSchema} / {@link getEventInputSchema} for
+* hot paths. Constructing the zod wrapper per call costs ~20µs (~50x the
+* parse itself), and the reduce/append paths run once per event. Keyed by
+* payload-schema identity, then event type: catalog entries are module
+* constants, so the WeakMap never grows past the contract surface.
+*/
+const eventSchemaCache = /* @__PURE__ */ new WeakMap();
+function cachedSchema(cache, build, args) {
+	let byType = cache.get(args.payloadSchema);
+	if (byType === void 0) {
+		byType = /* @__PURE__ */ new Map();
+		cache.set(args.payloadSchema, byType);
+	}
+	let schema = byType.get(args.type);
+	if (schema === void 0) {
+		schema = build(args);
+		byType.set(args.type, schema);
+	}
+	return schema;
+}
+/** Memoized {@link getEventSchema} (see {@link eventSchemaCache}). */
+function cachedEventSchema(args) {
+	return cachedSchema(eventSchemaCache, getEventSchema, args);
+}
+/**
+* Validate an append input with the payload schema resolved from a processor
+* contract. Prefer the contract-bound `contract.buildEvent(event)` API, which
+* carries the same types without repeating the contract in the argument.
+*
+* @deprecated Use `contract.buildEvent(event)`.
+*/
+function buildEvent(args) {
+	return parseResolvedEventInput(args.contract, args.event);
+}
+function parseResolvedEventInput(contract, event) {
+	const eventDefinition = getResolvedEventDefinition({
+		contract,
+		eventType: event.type
+	});
+	if (eventDefinition === void 0) {
+		const owner = contract.slug == null ? "contract" : `processor "${contract.slug}"`;
+		throw new Error(`${owner} cannot build unresolved event "${event.type}".`);
+	}
+	return getEventInputSchema({
+		type: event.type,
+		payloadSchema: eventDefinition.payloadSchema,
+		ephemeral: eventDefinition.ephemeral
+	}).parse(event);
+}
+function defineProcessorContract(contract) {
+	assertNoLocalProcessorDepEventConflicts(contract);
+	assertDefaultStateSchema(contract);
+	if (typeof contract !== "object" || contract === null) throw new Error("Processor contract must be an object.");
+	for (const method of [
+		"buildEvent",
+		"parseEvent",
+		"parseEventInput",
+		"parseConsumedInput"
+	]) if (method in contract) throw new Error(`Processor "${getProcessorSlug(contract)}" must not define ${method}.`);
+	const typedContract = contract;
+	return Object.assign(typedContract, {
+		buildEvent(event) {
+			return parseResolvedEventInput(typedContract, event);
+		},
+		parseEvent: makeContractEventParser(typedContract, getEventSchema),
+		parseEventInput: makeContractEventParser(typedContract, getEventInputSchema),
+		parseConsumedInput: makeContractConsumedInputParser(typedContract)
+	});
+}
+/**
+* Runtime twin of {@link ConsumedInput}. Unlike `parseEventInput`, this parser
+* rejects a resolved event that the processor does not actually consume. A
+* domain object's typed `append` door uses both so its remote runtime boundary
+* cannot drift from the processor contract after TypeScript has been erased.
+*/
+function makeContractConsumedInputParser(contract) {
+	const parserCache = /* @__PURE__ */ new Map();
+	return (event) => {
+		if (event.ephemeral === true) throw new Error(`Processor "${getProcessorSlug(contract)}" cannot consume ephemeral event "${event.type}".`);
+		const eventDefinition = getConsumedEventDefinition({
+			contract,
+			eventType: event.type
+		});
+		if (eventDefinition === void 0) throw new Error(`Processor "${getProcessorSlug(contract)}" does not consume event "${event.type}".`);
+		let schema = parserCache.get(event.type);
+		if (schema === void 0) {
+			schema = getEventInputSchema({
+				type: event.type,
+				payloadSchema: eventDefinition.payloadSchema,
+				ephemeral: eventDefinition.ephemeral
+			});
+			parserCache.set(event.type, schema);
+		}
+		return schema.parse(event);
+	};
+}
+/**
+* Shared runtime body of `contract.parseEvent(...)` and
+* `contract.parseEventInput(...)`: both resolve the payload schema from the
+* contract catalog, so an edit to a core event schema automatically affects
+* committed-event reduction and pre-commit validation together.
+*/
+function makeContractEventParser(contract, schemaFor) {
+	const parserCache = /* @__PURE__ */ new Map();
+	return (event) => {
+		const eventType = event.type;
+		const eventDefinition = getResolvedEventDefinition({
+			contract,
+			eventType
+		});
+		if (eventDefinition == null) throw new Error(`Processor "${getProcessorSlug(contract)}" cannot parse unresolved event "${eventType}".`);
+		let schema = parserCache.get(eventType);
+		if (schema === void 0) {
+			schema = schemaFor({
+				type: eventType,
+				payloadSchema: eventDefinition.payloadSchema,
+				ephemeral: eventDefinition.ephemeral
+			});
+			parserCache.set(eventType, schema);
+		}
+		return schema.parse(event);
+	};
+}
+/**
+* Enforces the invariant that reduced processor state is object-shaped (so
+* state slices can evolve safely and hooks never branch on primitive state).
+*/
+function assertObjectProcessorState(args) {
+	if (typeof args.value === "object" && args.value !== null && !Array.isArray(args.value)) return;
+	throw new Error(`Processor "${args.processorSlug}" state must be an object.`);
+}
+function assertDefaultStateSchema(contract) {
+	if (typeof contract !== "object" || contract === null) throw new Error("Processor contract must be an object.");
+	const processorSlug = getProcessorSlug(contract);
+	if (!("stateSchema" in contract) || !isZodSchema(contract.stateSchema)) throw new Error(`Processor "${processorSlug}" must define stateSchema.`);
+	let defaultState;
+	try {
+		defaultState = contract.stateSchema.parse({});
+	} catch (error) {
+		throw new Error(`Processor "${processorSlug}" stateSchema must parse {}.`, { cause: error });
+	}
+	assertObjectProcessorState({
+		processorSlug,
+		value: defaultState
+	});
+}
+/**
+* Resolve the payload schema a processor should use for an incoming event:
+* the named definition when the type is listed in `consumes`, a permissive
+* `z.unknown()` definition when the contract consumes `"*"`, and `undefined`
+* when the event is not consumed at all. Runtime counterpart of
+* `ConsumedEvent<Contract>`.
+*
+* `"*"` NEVER MATCHES AN EPHEMERAL EVENT, and that one rule is what lets
+* ephemeral types live in `consumes` beside durable ones instead of in a
+* parallel list. Naming a type explicitly is the opt-in: you cannot be handed
+* a microphone firehose by a wildcard you wrote for durable facts, and a
+* processor that wants live events says so by type. Ephemeral bodies live
+* only in the Stream DO's bounded buffer, so a processor receiving one must
+* have decided it can cope with never seeing it again — a decision nobody
+* makes by writing `"*"`.
+*/
+function getConsumedEventDefinition(args) {
+	if (!args.contract.consumes.includes(args.eventType)) {
+		if (args.ephemeral === true) return void 0;
+		if (args.contract.consumes.includes("*")) return { payloadSchema: z.unknown() };
+		return;
+	}
+	const eventDefinition = getResolvedEventDefinition(args);
+	if (eventDefinition == null) throw new Error(`Unresolved stream processor consumes event type "${args.eventType}".`);
+	if (args.ephemeral === true && eventDefinition.ephemeral !== true) return void 0;
+	return eventDefinition;
+}
+function getResolvedEventDefinition(args) {
+	const localEventDefinition = args.contract.events[args.eventType];
+	if (localEventDefinition != null) return localEventDefinition;
+	for (const dependency of args.contract.processorDeps ?? []) {
+		const dependencyEventDefinition = getDependencyEvents(dependency)?.[args.eventType];
+		if (dependencyEventDefinition != null) return dependencyEventDefinition;
+	}
+}
+function getDependencyEvents(dependency) {
+	if (isEventCatalog(dependency)) return dependency;
+	if (typeof dependency === "object" && dependency !== null && "events" in dependency && isEventCatalog(dependency.events)) return dependency.events;
+}
+function assertNoLocalProcessorDepEventConflicts(contract) {
+	if (typeof contract !== "object" || contract === null || !("events" in contract)) return;
+	if (!isEventCatalog(contract.events)) return;
+	const processorDeps = "processorDeps" in contract && Array.isArray(contract.processorDeps) ? contract.processorDeps : [];
+	for (const dependency of processorDeps) {
+		const dependencyEvents = getDependencyEvents(dependency);
+		if (dependencyEvents === void 0) continue;
+		for (const type of Object.keys(contract.events)) {
+			if (!Object.prototype.hasOwnProperty.call(dependencyEvents, type)) continue;
+			throw new Error(`Processor "${getProcessorSlug(contract)}" defines event "${type}" that is already owned by processor dependency "${getProcessorSlug(dependency)}".`);
+		}
+	}
+}
+function isEventCatalog(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return Object.values(value).every(isEventDefinition);
+}
+function isEventDefinition(value) {
+	return typeof value === "object" && value !== null && "payloadSchema" in value && typeof value.payloadSchema === "object" && value.payloadSchema !== null;
+}
+function isZodSchema(value) {
+	return typeof value === "object" && value !== null && "parse" in value && typeof value.parse === "function";
+}
+function getProcessorSlug(contract) {
+	if (typeof contract === "object" && contract !== null && "slug" in contract && typeof contract.slug === "string") return contract.slug;
+	return "unknown";
+}
+/**
+* The ONE platform revival fact for every recovery-wired stream processor.
+* Appended by the platform keepalive (`durableObjectRecovery` in
+* durable-object-processor-durability.ts) when a processor is revived after
+* its incarnation died owing background work — never emitted by a processor.
+* Per-processor identity rides the payload's `processorSlug` and the
+* `processor-revived:<slug>@...` idempotency key, not the type string.
+* Consuming it is OPTIONAL: a processor should do so only when it reacts to
+* the fact itself. Its append still wakes delivery when it is unconsumed, and
+* a head-reaching frame receives the runner's eventless
+* `processEvent(event: null, caughtUp: true)` pass so open obligations are not
+* stranded. The event DEFINITION (payload schema) lives with the platform's
+* core stream contract; this constant is here so contracts and the recovery
+* adapter agree on the type string without importing that contract.
+*/
+const STREAM_PROCESSOR_REVIVED_EVENT_TYPE = "events.iterate.com/stream/processor-revived";
+/**
+* A processor contract announcement carried on `connection-opened` when the
+* callback owner is a hosted stream processor. UIs and tooling read it from
+* that event and from `runtime.connections[..].openedBy`.
+*/
+const ProcessorContractAnnouncement = z.object({
+	slug: z.string().trim().min(1),
+	version: z.string().trim().min(1),
+	description: z.string(),
+	consumes: z.array(z.string()),
+	emits: z.array(z.string()),
+	ownedEvents: z.array(z.object({
+		type: z.string().trim().min(1),
+		description: z.string().optional()
+	}))
+});
+/**
+* Platform stream events a processor contract may CONSUME without owning —
+* pass as a `processorDeps` entry. Currently just the keepalive revival fact.
+* Consumption is optional and belongs only in processors that react to the
+* fact itself; an unconsumed revival tail receives the runner's eventless
+* at-head turn. The event's authoritative definition lives with the
+* platform's core stream contract, and this catalog is deliberately
+* payload-loose.
+*/
+const PLATFORM_STREAM_EVENTS = { [STREAM_PROCESSOR_REVIVED_EVENT_TYPE]: {
+	description: "Platform keepalive revival fact: appended when a processor's incarnation died owing background work; consumed when the processor reacts to the fact itself, otherwise followed by an eventless at-head processEvent turn.",
+	payloadSchema: z.looseObject({})
+} };
+//#endregion
+//#region src/processors/stream-processor.ts
+async function awaitKeepAliveBacked(keepAliveWhile, work) {
+	if (keepAliveWhile === void 0) return await work();
+	return await new Promise((resolve, reject) => {
+		keepAliveWhile(async () => {
+			try {
+				const result = await work();
+				resolve(result);
+				return result;
+			} catch (error) {
+				reject(error);
+				throw error;
+			}
+		});
+	});
+}
+/**
+* Class-based stream processor.
+*
+* The model in one sentence: the StreamProcessorRunner
+* (stream-processor-runner.ts) delivers ordered events, folds each consumed
+* event into state through `reduce`, hands each reduction to the side-effect
+* hooks, and owns cursors, checkpoints, retry, and recovery — the processor
+* itself is only the hooks.
+*
+* Subclasses override up to two hooks:
+*
+* - `reduce` — pure projection of one consumed event into the next state
+* - `processEvent` — synchronous per-event side effects; what most processors
+*   implement. Side effects derived from the whole fold (rather than the
+*   delivered event) belong here too, guarded by `args.delivery.caughtUp`.
+*   `args.event` is `null` only when a caught-up scan contained no
+*   consumed event; authors skip their per-event switch but can still act on
+*   the fold.
+*
+* Every hook runs inside the runner's serialized delivery chain: a later
+* batch never starts until the previous one has completed or failed, and the
+* cursor is only committed after the hooks (plus any `blockProcessorWhile`
+* work) succeed.
+*/
+var StreamProcessor = class extends RpcTarget {
+	stream;
+	/** Path of the home stream — the one `this.stream` points at. */
+	path;
+	/** Owning project, or null on a global (deployment-root) stream. */
+	projectId;
+	deps;
+	/**
+	* Self-measured consumption metrics (see event-consumption-metrics.ts): every
+	* home-stream append and every committed event batch feeds it (the
+	* latter through the driver's `noteBatchIngested`), closing the
+	* consume-your-own-appends loop on the processor's own clock. HOSTS merge
+	* `eventConsumptionMetrics.report()` into the `getRuntimeState` answer they give
+	* the stream (`runtime.metrics`) — merged host-side so a subclass
+	* overriding `getRuntimeState` with its own `runtime` bag cannot
+	* accidentally drop it. In-memory; resets with the isolate.
+	*/
+	eventConsumptionMetrics = new EventConsumptionMetrics(Date.now());
+	#keepAliveWhile;
+	constructor(args) {
+		super();
+		const { stream, path, projectId, keepAliveWhile, ...deps } = args;
+		this.stream = stream;
+		this.path = path;
+		this.projectId = projectId;
+		this.deps = deps;
+		this.#keepAliveWhile = keepAliveWhile;
+	}
+	/**
+	* @internal Hands the StreamProcessorRunner its {@link StreamProcessorRunnerHooks}.
+	* A STATIC accessor on purpose: statics may reach protected/private members
+	* of instances of their own class, so the runner gets the hooks without any
+	* new public instance member (nothing for subclasses to see, shadow, or
+	* call). Authors never touch this; the runner is its only caller.
+	*/
+	static runnerHooks(processor) {
+		return {
+			contract: processor.contract,
+			initialState: () => processor.contract.stateSchema.parse({}),
+			parseState: (value) => {
+				const parsed = processor.contract.stateSchema.safeParse(value);
+				return parsed.success ? {
+					success: true,
+					state: parsed.data
+				} : {
+					success: false,
+					error: parsed.error
+				};
+			},
+			reduceRawEvent: (args) => processor.#reduceRawEvent(args),
+			isDeliverable: (event) => processor.#isDeliverable(event),
+			processEvent: (args) => processor.processEvent(args),
+			noteBatchIngested: (args) => processor.eventConsumptionMetrics.noteBatchIngested(args),
+			idempotencyKey: (key, whileProcessing) => processor.idempotencyKey(key, whileProcessing),
+			processorStamp: (streamId, whileProcessing) => processor.#processorStamp(streamId, whileProcessing),
+			append: (opts, input) => processor.#appendStamped({
+				target: processor.stream,
+				targetPath: processor.path,
+				sourceStreamId: opts.streamId,
+				whileProcessing: opts.whileProcessing
+			}, input),
+			appendTo: (path, opts, input) => processor.#appendStamped({
+				...processor.#appendTarget(path),
+				sourceStreamId: opts.streamId,
+				whileProcessing: opts.whileProcessing
+			}, input)
+		};
+	}
+	/**
+	* The processor-contributed slice of the published runtime state: the
+	* operational `runtime` bag only (see {@link ProcessorRuntimeContribution}).
+	* Subclasses override to expose debug data; the base contributes nothing.
+	* The snapshot half comes from the runner, and event-consumption metrics are
+	* merged in host-side — never read cursor state here.
+	*/
+	async getRuntimeState() {
+		return {};
+	}
+	/** Build and validate an append input for an event listed in `contract.emits`. */
+	#buildEmittedEvent(event) {
+		if (!this.contract.emits.includes(event.type)) throw new Error(`Processor "${this.contract.slug}" cannot build emitted event "${event.type}".`);
+		const eventDefinition = getResolvedEventDefinition({
+			contract: this.contract,
+			eventType: event.type
+		});
+		if (eventDefinition === void 0) throw new Error(`Unresolved stream processor emits event type "${event.type}".`);
+		return getEventInputSchema({
+			type: event.type,
+			payloadSchema: eventDefinition.payloadSchema,
+			ephemeral: eventDefinition.ephemeral
+		}).parse(event);
+	}
+	/**
+	* Pure projection of one consumed event into the next state. Defaults to
+	* identity; returning `null`/`undefined` also keeps the current state.
+	*/
+	reduce(args) {
+		return args.state;
+	}
+	/**
+	* Synchronous side-effect hook, called by the runner once per consumed event
+	* and, when necessary, once more with `event: null` for a caught-up scan
+	* that consumed nothing. It is ALSO the caught-up processing: when
+	* `args.delivery.caughtUp` is true (`args.state` is the whole observed fold),
+	* an obligation processor
+	* drives its undriven obligations and settles dead ones — scheduling that
+	* async work via `args.blockProcessorWhile`, keyed by STABLE obligation keys
+	* (`this.idempotencyKey(<obligation>)` with the deciding state folded into
+	* the key and NO event bound, so a redelivery/revival does not rotate the
+	* key and re-run the effect).
+	* The runner never sets `caughtUp` below its highest observed offset — no override
+	* needs its own mid-catch-up gate. Simple processors ignore the flag.
+	*/
+	processEvent(_args) {}
+	/** Parse a raw event against the contract: `undefined` (type not consumed),
+	* a Zod error (consumed type, bad shape), or the typed consumed event.
+	* Stateless — shared by {@link #reduceRawEvent} and {@link #isDeliverable}. */
+	#parseConsumedEvent(event) {
+		const eventDefinition = getConsumedEventDefinition({
+			contract: this.contract,
+			eventType: event.type,
+			ephemeral: event.ephemeral
+		});
+		if (eventDefinition === void 0) return { ok: false };
+		const parsed = cachedEventSchema({
+			type: event.type,
+			payloadSchema: eventDefinition.payloadSchema,
+			ephemeral: eventDefinition.ephemeral
+		}).safeParse(event);
+		if (!parsed.success) return {
+			ok: false,
+			error: parsed.error
+		};
+		return {
+			ok: true,
+			event: parsed.data
+		};
+	}
+	/** True when this event will reach `processEvent`: a consumed type that
+	* parses. A malformed consumed event is deliberately NOT deliverable. */
+	#isDeliverable(event) {
+		return this.#parseConsumedEvent(event).ok;
+	}
+	/**
+	* Reduce one raw stream event against explicit state, without touching any
+	* processor-internal state. Returns `undefined` for events this processor
+	* does not consume, and a {@link ConsumedEventParseFailure} for events of a
+	* consumed TYPE whose shape fails the contract parse — streams accept raw
+	* appends by design, so a malformed event is a fact of the log, not an
+	* exception: throwing here would wedge the cursor on it forever.
+	*/
+	#reduceRawEvent(args) {
+		const parsed = this.#parseConsumedEvent(args.event);
+		if (!parsed.ok) return parsed.error === void 0 ? void 0 : { parseError: parsed.error };
+		const event = parsed.event;
+		const state = this.reduce({
+			event,
+			state: args.state
+		}) ?? args.state;
+		assertObjectProcessorState({
+			processorSlug: this.contract.slug,
+			value: state
+		});
+		return {
+			event,
+			previousState: args.state,
+			state
+		};
+	}
+	/**
+	* Fire-and-forget async work backed by the injected keep-alive, with
+	* failures logged. For work launched OUTSIDE a delivery hook (DO verbs,
+	* alarm handlers); inside `processEvent`, use the `runInBackground` helper
+	* from the hook args — that one rides the runner's recovery keepalive.
+	*/
+	runInBackground(work) {
+		awaitKeepAliveBacked(this.#keepAliveWhile, work).catch((error) => {
+			console.error("stream processor background work failed", error);
+		});
+	}
+	/**
+	* Append events listed in `contract.emits` to this processor's own stream,
+	* stamped with `source.processor` provenance (no `whileProcessing`: this
+	* overload is for appends outside any event batch — alarm handlers, DO methods —
+	* and for decisions derived from the whole fold). Inside `processEvent`,
+	* prefer the event-bound `args.append`.
+	*/
+	append(...input) {
+		return this.#appendStamped({
+			target: this.stream,
+			targetPath: this.path
+		}, input);
+	}
+	/** Like {@link append}, onto a sibling stream (resolved via `stream.at(path)`). */
+	appendTo(path, ...input) {
+		return this.#appendStamped(this.#appendTarget(path), input);
+	}
+	#appendTarget(path) {
+		const targetPath = resolveStreamPath(this.path, path);
+		return {
+			target: targetPath === this.path ? this.stream : this.stream.at(path),
+			targetPath
+		};
+	}
+	/**
+	* Processor-scoped idempotency key: `<slug>/<key>`, plus `@<path>:<offset>`
+	* when the append is a deterministic consequence of processing one event —
+	* a resent event batch then dedupes instead of double-appending. The path
+	* makes fan-in safe: two same-slug processors on different streams
+	* forwarding into one target can never collide. Omit `whileProcessing` for
+	* state-derived appends and fold the deciding state into `key` instead
+	* (e.g. a generation counter).
+	*/
+	idempotencyKey(key, whileProcessing) {
+		const base = `${this.contract.slug}/${key}`;
+		if (whileProcessing === void 0) return base;
+		return `${base}@${whileProcessing.path}:${whileProcessing.offset}`;
+	}
+	/**
+	* The provenance stamp for one append. Always overwrites any
+	* caller-supplied `source.processor`: the stamp describes THIS append, and
+	* ancestry stays walkable through `whileProcessing` (and `copiedFrom`
+	* for subscription copies, which preserve the original stamp).
+	*/
+	#processorStamp(streamId, whileProcessing) {
+		return {
+			slug: this.contract.slug,
+			version: this.contract.version,
+			stream: {
+				path: this.path,
+				projectId: this.projectId,
+				streamId
+			},
+			...whileProcessing === void 0 ? {} : { whileProcessing: {
+				offset: whileProcessing.offset,
+				type: whileProcessing.type
+			} }
+		};
+	}
+	#appendStamped(args, input) {
+		const builtEvents = input.map((event) => this.#buildEmittedEvent(event));
+		return this.#appendBuiltEvents(args, builtEvents);
+	}
+	async #appendBuiltEvents(args, builtEvents) {
+		const sourceStreamId = args.sourceStreamId ?? (await this.stream.getEventPage({
+			afterOffset: Number.MAX_SAFE_INTEGER,
+			limit: 1
+		})).streamId;
+		const processor = this.#processorStamp(sourceStreamId, args.whileProcessing);
+		let events = builtEvents.map((built) => ({
+			...built,
+			source: {
+				...built.source,
+				processor
+			}
+		}));
+		if (args.targetPath !== this.path) {
+			events = events.map((event) => event.idempotencyKey === void 0 ? event : {
+				...event,
+				idempotencyKey: `${event.idempotencyKey}@source-stream:${sourceStreamId}`
+			});
+			return args.target.append(...events);
+		}
+		const t0 = Date.now();
+		return this.stream.appendIfStreamId({
+			streamId: sourceStreamId,
+			events
+		}).then((committed) => {
+			if (committed.length === 0) return committed;
+			let maxCommittedOffset = null;
+			for (const event of committed) {
+				if (!this.#isDeliverable(event)) continue;
+				maxCommittedOffset = Math.max(maxCommittedOffset ?? 0, event.offset);
+			}
+			this.eventConsumptionMetrics.noteAppendCommitted({
+				maxCommittedOffset,
+				t0,
+				atMs: Date.now()
+			});
+			return committed;
+		});
+	}
+};
+//#endregion
+//#region src/processors/stream-processor-runner.ts
+/**
+* Processes event batches for one processor on one stream. Runtime-neutral:
+* the browser, the Durable Object registry, and the in-memory
+* test harness all instantiate exactly this class and differ only in the
+* `durability` / `keepAlive` adapters they pass. One runner per processor —
+* the "host" of old survives only as a thin registry that builds adapters and
+* routes wakes/alarms to the right runner.
+*
+* Serialization: batches and self-pulls share ONE in-memory chain, so a
+* catch-up never interleaves with a half-processed batch. Cross-incarnation
+* races (a stale runner outliving progress made elsewhere) are fenced durably
+* instead, by the progress store's `cursorRevision` CAS + monotonic fence.
+*/
+var StreamProcessorRunner = class {
+	processor;
+	hooks;
+	stream;
+	durability;
+	keepAlive;
+	now;
+	readPageSize;
+	/** Memoized load for one stream lifetime; cleared on failure or recreation. */
+	#loaded;
+	#loadingStreamId;
+	/** True once progress reflects a real load (fresh default over an empty
+	* store counts; a pending/failed load does not) — the gate that keeps
+	* default or partially-refolded state from ever escaping (the legacy
+	* `isLoaded` invariant). `snapshot()` additionally
+	* awaits the load, so partial state cannot escape through it either. */
+	#hasLoaded = false;
+	/** The COMMITTED, loaded progress — what snapshots and direct callbacks publish.
+	* A hosted wake may publish only the separately-read processing cursor before this
+	* reduction cache loads. Batch folds accumulate in locals and land here only after
+	* the durable commit. */
+	#progress;
+	/** Highest stream offset observed across all batches this incarnation. */
+	#highestObservedOffset = 0;
+	/** Serializes batches + self-pulls; failures are contained per entry. */
+	#chain = Promise.resolve();
+	#disposed = false;
+	#eventWaiters = /* @__PURE__ */ new Set();
+	#stateChangeObservers = /* @__PURE__ */ new Set();
+	/** Memoized schema default, for pre-load `currentState` reads. */
+	#defaultState;
+	constructor(args) {
+		this.processor = args.processor;
+		this.hooks = StreamProcessor.runnerHooks(args.processor);
+		this.stream = args.stream;
+		this.durability = args.durability;
+		this.keepAlive = args.keepAlive;
+		this.now = args.now ?? (() => Date.now());
+		this.readPageSize = args.readPageSize ?? 500;
+	}
+	/**
+	* Opens the processor's event-batch callback and returns its committed
+	* processing offset. A hosted processor wake returns this pair to a source
+	* stream; the browser database writer calls the same method directly.
+	*
+	* `checkpointOffset` is the PROCESSING cursor (`acknowledgedThroughOffset`),
+	* never the reduction offset: the caller resumes after this value, and
+	* resuming from a reduction-pinned snapshot
+	* offset could skip events whose effects were never acknowledged.
+	*
+	* `processEventBatch` is the only place transport batching enters the
+	* runner; inside it the runner reduces and processes one event at a time. A
+	* hosting transport may adapt how the promise is observed, but must not
+	* duplicate these semantics.
+	*/
+	async openEventBatchCallback(expectedStreamId) {
+		this.#assertNotDisposed();
+		const opened = await this.#enqueue(async () => {
+			const streamId = await this.#readCurrentStreamId(expectedStreamId);
+			await this.#load(streamId);
+			return {
+				streamId,
+				checkpointOffset: this.#requireProgress().processing.acknowledgedThroughOffset
+			};
+		});
+		return this.#eventBatchCallback({
+			...opened,
+			deferredLoad: false,
+			sourceScansAllEvents: false
+		});
+	}
+	/**
+	* Open the callback used by a trusted hosted source Stream.
+	*
+	* The request already carries that source's authoritative stream ID. Reading
+	* it back before returning would deadlock a colocated Processor Facet: the
+	* source alarm owns the wake RPC while the facet's identity/refold read waits
+	* for that same source turn. Return the durable processing cursor without a
+	* source read, then finish any reduction-cache load when the source invokes
+	* the independent one-way batch callback.
+	*/
+	async openHostedEventBatchCallback(streamId) {
+		this.#assertNotDisposed();
+		const checkpointOffset = await this.#enqueue(() => this.#prepareHostedCheckpoint(streamId));
+		return this.#eventBatchCallback({
+			streamId,
+			checkpointOffset,
+			deferredLoad: true,
+			sourceScansAllEvents: true
+		});
+	}
+	#eventBatchCallback(args) {
+		return {
+			checkpointOffset: args.checkpointOffset,
+			processEventBatch: (batch) => {
+				const attempt = this.#enqueue(async () => {
+					if (args.deferredLoad) await this.#loadPreparedStream(args.streamId);
+					await this.#processBatch(batch);
+				});
+				this.durability?.recovery?.keepAliveWhile(() => attempt);
+				if (!args.sourceScansAllEvents) this.#runInBackground(() => attempt.then(() => this.#enqueue(async () => {
+					const { processing } = this.#requireProgress();
+					if (processing.acknowledgedThroughOffset < batch.streamMaxOffset) await this.#selfCatchUp();
+				}), () => void 0));
+				return attempt;
+			}
+		};
+	}
+	/** Handle a durable recovery alarm routed here by the hosting registry. */
+	async handleAlarm(info) {
+		const recovery = this.durability?.recovery;
+		if (recovery === void 0) return;
+		await recovery.handleAlarm(info);
+	}
+	/** One consistent read of the fold, pinned to `reducedThroughOffset`. */
+	async snapshot() {
+		return this.#enqueue(async () => {
+			const streamId = await this.#readCurrentStreamId();
+			await this.#load(streamId);
+			const progress = this.#requireProgress();
+			return {
+				offset: progress.reduction.reducedThroughOffset,
+				state: progress.reduction.state
+			};
+		});
+	}
+	/**
+	* Whether published state IS a real fold rather than the schema default —
+	* the legacy `isLoaded` gate. With the runner, the load itself performs any
+	* pending refold, so this is true whenever a load has completed and false
+	* only before the first successful load.
+	*/
+	get isLoaded() {
+		return this.#hasLoaded;
+	}
+	/** Highest offset whose processing and blocking consequences have committed. */
+	get currentAcknowledgedThroughOffset() {
+		return this.#progress?.processing.acknowledgedThroughOffset ?? 0;
+	}
+	/** Source lifetime paired atomically with the current committed state and cursor. */
+	get currentStreamId() {
+		return this.#progress?.streamId;
+	}
+	/**
+	* The current committed fold, synchronously (the schema default until the
+	* first load) — the legacy `StreamProcessor.currentState`,
+	* kept so a hosting registry can assemble its
+	* live state without an async hop. Gate on {@link isLoaded} first: a cold
+	* runner reports the default, and publishing that anywhere live would wipe
+	* real facts for state observers.
+	*/
+	get currentState() {
+		if (this.#progress !== void 0) return this.#progress.reduction.state;
+		this.#defaultState ??= this.hooks.initialState();
+		return this.#defaultState;
+	}
+	/**
+	* Observe committed reduced-state changes IN-PROCESS: the observer is a
+	* local function (the hosting registry wires it to reassemble its
+	* live-state engine), never a retained RPC stub. It fires after a batch
+	* commit lands durably AND the committed state changed identity — the
+	* runner's home for the legacy `StreamProcessor.observeStateChanges` +
+	* post-persist notify. Returns a function that stops observing.
+	*/
+	observeStateChanges(observer) {
+		this.#stateChangeObservers.add(observer);
+		return () => void this.#stateChangeObservers.delete(observer);
+	}
+	/**
+	* Read journal pages after the acknowledged cursor and process them until
+	* caught up — the public method for read-your-writes and a
+	* hosting registry's cold-load healing (the legacy host's `catchUpInternal`
+	* shape). One page of lookahead, so every non-final batch carries a
+	* `streamMaxOffset` past its own last event and only the genuinely final page is
+	* marked caught up. Serialized with delivered batches on the runner's chain; failures
+	* RETHROW — the caller owns any swallow-and-log policy.
+	*/
+	catchUp() {
+		return this.#enqueue(async () => {
+			const streamId = await this.#readCurrentStreamId();
+			await this.#load(streamId);
+			await this.#selfCatchUp();
+		});
+	}
+	async waitUntilEvent(args) {
+		if (args.signal?.aborted === true) throw abortReason(args.signal);
+		if ("offset" in args) {
+			if (!Number.isSafeInteger(args.offset) || args.offset < 0) throw new Error("waitUntilEvent offset must be a non-negative safe integer");
+			const streamId = await this.#readCurrentStreamId();
+			await this.#load(streamId);
+			if (this.#requireProgress().processing.acknowledgedThroughOffset >= args.offset) return;
+			const { offset, signal, timeoutMs } = args;
+			const reached = this.#registerEventWaiter({
+				kind: "offset",
+				offset
+			}, {
+				signal,
+				timeoutMs
+			});
+			this.catchUp().catch((error) => {
+				reached.reject(error);
+			});
+			return await reached.promise;
+		}
+		const { predicate, signal, timeoutMs } = args;
+		await this.#registerEventWaiter({
+			kind: "predicate",
+			predicate
+		}, {
+			signal,
+			timeoutMs
+		}).promise;
+	}
+	/** Release processor resources. Idempotent; a disposed runner rejects new work. */
+	dispose() {
+		this.#disposed = true;
+		for (const waiter of this.#eventWaiters) this.#settleEventWaiter(waiter, { error: /* @__PURE__ */ new Error("StreamProcessorRunner disposed") });
+		this.#stateChangeObservers.clear();
+	}
+	async #processBatch(batch) {
+		const ingestStartedAtMs = this.now();
+		assertProcessorEventBatch(batch);
+		const committed = this.#requireProgress();
+		if (batch.streamId !== committed.streamId) throw new Error(`stream processor "${this.hooks.contract.slug}" received batch for stream ID ${batch.streamId}; current progress belongs to ${committed.streamId}`);
+		const committedThroughOffset = committed.processing.acknowledgedThroughOffset;
+		if (batch.scannedAfterOffset > committedThroughOffset) throw new Error(`delivery batch starts after the committed scan cursor: ${batch.scannedAfterOffset} > ${committedThroughOffset}`);
+		const batchScannedThroughOffset = Math.max(committedThroughOffset, batch.scannedThroughOffset);
+		const pending = [];
+		let scan = committedThroughOffset;
+		for (const event of batch.events) {
+			if (event.offset <= scan) continue;
+			scan = event.offset;
+			pending.push(event);
+		}
+		this.#highestObservedOffset = Math.max(this.#highestObservedOffset, batch.streamMaxOffset, batchScannedThroughOffset);
+		if (pending.length === 0 && batchScannedThroughOffset === committedThroughOffset) return;
+		const batchCaughtUp = batchScannedThroughOffset >= this.#highestObservedOffset;
+		let lastDeliveredOffset = null;
+		for (const event of pending) if (this.hooks.isDeliverable(event)) lastDeliveredOffset = event.offset;
+		let firedCaughtUp = false;
+		const ctx = {
+			revision: committed.processing.cursorRevision,
+			ingestStartedAtMs,
+			state: committed.reduction.state,
+			reducedThroughOffset: committed.reduction.reducedThroughOffset,
+			completedThroughOffset: committed.processing.acknowledgedThroughOffset,
+			eventsSinceCommit: 0,
+			uncommittedEvents: [],
+			uncommittedParseFailures: []
+		};
+		/** Every blocker started anywhere in this batch, for failure settlement. */
+		const startedBlockers = [];
+		try {
+			for (const event of pending) {
+				const reduction = this.hooks.reduceRawEvent({
+					event,
+					state: ctx.state
+				});
+				if (reduction !== void 0 && "parseError" in reduction) ctx.uncommittedParseFailures.push({
+					event,
+					error: reduction.parseError
+				});
+				else if (reduction !== void 0) {
+					const caughtUp = batchCaughtUp && event.offset === lastDeliveredOffset;
+					if (caughtUp) firedCaughtUp = true;
+					const delivery = {
+						caughtUp,
+						streamId: batch.streamId
+					};
+					let eventChain = Promise.resolve();
+					const whileProcessing = reduction.event;
+					this.hooks.processEvent({
+						event: reduction.event,
+						previousState: reduction.previousState,
+						state: reduction.state,
+						delivery,
+						blockProcessorWhile: (work) => {
+							const attempt = eventChain.then(() => this.#keepAliveBackedWork(work).catch((error) => {
+								console.error(`stream processor blocked work failed (${this.hooks.contract.slug})`, error);
+								throw error;
+							}));
+							eventChain = attempt;
+							startedBlockers.push(attempt);
+						},
+						runInBackground: (work) => this.#runInBackground(work),
+						append: (...input) => this.hooks.append({
+							streamId: batch.streamId,
+							whileProcessing
+						}, input),
+						appendTo: (path, ...input) => this.hooks.appendTo(path, {
+							streamId: batch.streamId,
+							whileProcessing
+						}, input)
+					});
+					await eventChain;
+					ctx.state = reduction.state;
+				}
+				ctx.reducedThroughOffset = event.offset;
+				ctx.completedThroughOffset = event.offset;
+				ctx.eventsSinceCommit += 1;
+				ctx.uncommittedEvents.push(event);
+			}
+			if (batchCaughtUp && !firedCaughtUp) {
+				const delivery = {
+					caughtUp: true,
+					streamId: batch.streamId
+				};
+				let caughtUpChain = Promise.resolve();
+				this.hooks.processEvent({
+					event: null,
+					previousState: ctx.state,
+					state: ctx.state,
+					delivery,
+					blockProcessorWhile: (work) => {
+						const attempt = caughtUpChain.then(() => this.#keepAliveBackedWork(work).catch((error) => {
+							console.error(`stream processor blocked work failed (${this.hooks.contract.slug})`, error);
+							throw error;
+						}));
+						caughtUpChain = attempt;
+						startedBlockers.push(attempt);
+					},
+					runInBackground: (work) => this.#runInBackground(work),
+					append: (...input) => this.hooks.append({ streamId: batch.streamId }, input),
+					appendTo: (path, ...input) => this.hooks.appendTo(path, { streamId: batch.streamId }, input)
+				});
+				await caughtUpChain;
+			}
+			ctx.reducedThroughOffset = batchScannedThroughOffset;
+			ctx.completedThroughOffset = batchScannedThroughOffset;
+		} catch (error) {
+			await Promise.allSettled(startedBlockers);
+			throw error;
+		}
+		if (ctx.eventsSinceCommit > 0 || batchScannedThroughOffset > committedThroughOffset) await this.#commitBatchContext(ctx);
+	}
+	/**
+	* Persist the batch context, THEN advance the published cursor, resolve
+	* waiters, and flush parse-failure diagnostics for the covered events.
+	*
+	* Persist-before-advance is load-bearing (the legacy #ingest's ordering):
+	* if the durable write fails, the batch must stay retryable — the redelivered
+	* batch re-reduces from the OLD published state and retries the write.
+	* Advancing in-memory first would make the retry a silent no-op (every
+	* event filtered out, nothing re-saved), losing the batch durably.
+	*/
+	async #commitBatchContext(ctx) {
+		const streamId = this.#requireProgress().streamId;
+		const next = {
+			streamId,
+			reduction: {
+				reducerVersion: this.hooks.contract.version,
+				reducedThroughOffset: ctx.reducedThroughOffset,
+				state: ctx.state
+			},
+			processing: {
+				acknowledgedThroughOffset: ctx.completedThroughOffset,
+				cursorRevision: ctx.revision
+			}
+		};
+		const previousCommittedState = this.#progress?.reduction.state;
+		await this.#commit(next, {
+			expectedCursorRevision: ctx.revision,
+			expectedStreamId: streamId
+		});
+		this.#progress = next;
+		ctx.eventsSinceCommit = 0;
+		const committedEvents = ctx.uncommittedEvents.splice(0);
+		const committedFailures = ctx.uncommittedParseFailures.splice(0);
+		if (committedEvents.length > 0) {
+			const newestEventCreatedAtMs = Date.parse(committedEvents.at(-1).createdAt);
+			this.hooks.noteBatchIngested({
+				ingestedThroughOffset: next.processing.acknowledgedThroughOffset,
+				ingestedOffsets: committedEvents.map((event) => event.offset),
+				...Number.isFinite(newestEventCreatedAtMs) && { newestEventCreatedAtMs },
+				ingestStartedAtMs: ctx.ingestStartedAtMs,
+				atMs: this.now()
+			});
+		}
+		if (!Object.is(previousCommittedState, next.reduction.state)) this.#notifyStateChange({
+			offset: next.reduction.reducedThroughOffset,
+			state: next.reduction.state
+		});
+		this.#resolveEventWaiters(committedEvents, next.processing.acknowledgedThroughOffset);
+		for (const { event, error } of committedFailures) {
+			const message = `stream processor "${this.hooks.contract.slug}" skipped event at offset ${event.offset} ("${event.type}"): it fails the contract's schema`;
+			console.error(message, error);
+			this.#runInBackground(() => this.stream.appendIfStreamId({
+				streamId,
+				events: [{
+					type: "events.iterate.com/stream/error-occurred",
+					idempotencyKey: this.hooks.idempotencyKey("event-parse-failed", event),
+					source: { processor: this.hooks.processorStamp(streamId, event) },
+					payload: {
+						message,
+						error: {
+							name: error.name,
+							message: error.message
+						}
+					}
+				}]
+			}));
+		}
+	}
+	/**
+	* Return the hosted source's authoritative effect cursor without reading
+	* that source. Fresh/recreated lifetimes still land their durable fence
+	* before the checkpoint escapes; an existing lifetime leaves its disposable
+	* reduction cache unloaded until the one-way delivery callback.
+	*/
+	async #prepareHostedCheckpoint(streamId) {
+		if (this.#hasLoaded && this.#progress?.streamId === streamId) return this.#progress.processing.acknowledgedThroughOffset;
+		if (this.#hasLoaded) {
+			this.#hasLoaded = false;
+			this.#loaded = void 0;
+			this.#loadingStreamId = void 0;
+		}
+		const persisted = await this.durability?.progress.read();
+		if (persisted === void 0) {
+			const fresh = this.#freshProgress(streamId, 0);
+			await this.#commit(fresh, {
+				expectedCursorRevision: 0,
+				expectedStreamId: void 0
+			});
+			this.#progress = fresh;
+			this.#hasLoaded = true;
+			return 0;
+		}
+		if (persisted.streamId === streamId) return persisted.processing.acknowledgedThroughOffset;
+		const replaceForStream = this.durability?.progress.replaceForStream;
+		if (replaceForStream === void 0) throw new Error(`stream processor "${this.hooks.contract.slug}" progress belongs to stream ID ${persisted.streamId}, but the current stream ID is ${streamId}; this durability backend must reset its related projections before reopening`);
+		const fresh = this.#freshProgress(streamId, persisted.processing.cursorRevision + 1);
+		await replaceForStream(fresh, {
+			expectedCursorRevision: persisted.processing.cursorRevision,
+			expectedStreamId: persisted.streamId
+		});
+		this.#progress = fresh;
+		this.#hasLoaded = true;
+		this.#notifyStateChange({
+			offset: 0,
+			state: fresh.reduction.state
+		});
+		return 0;
+	}
+	#load(streamId) {
+		return this.#loadWithStreamReplacement(streamId, true);
+	}
+	#loadPreparedStream(streamId) {
+		if (this.#hasLoaded) return Promise.resolve();
+		return this.#loadWithStreamReplacement(streamId, false);
+	}
+	#loadWithStreamReplacement(streamId, replaceMismatchedStream) {
+		if (this.#hasLoaded && this.#progress?.streamId === streamId) return Promise.resolve();
+		if (this.#hasLoaded) {
+			this.#hasLoaded = false;
+			this.#loaded = void 0;
+			this.#loadingStreamId = void 0;
+		}
+		if (this.#loaded !== void 0) {
+			if (this.#loadingStreamId === streamId) return this.#loaded;
+			return this.#loaded.then(() => this.#loadWithStreamReplacement(streamId, replaceMismatchedStream));
+		}
+		this.#loadingStreamId = streamId;
+		this.#loaded = this.#loadOnce(streamId, replaceMismatchedStream).catch((error) => {
+			this.#loaded = void 0;
+			this.#loadingStreamId = void 0;
+			throw error;
+		});
+		return this.#loaded;
+	}
+	#freshProgress(streamId, cursorRevision) {
+		return {
+			streamId,
+			reduction: {
+				reducerVersion: this.hooks.contract.version,
+				reducedThroughOffset: 0,
+				state: this.hooks.initialState()
+			},
+			processing: {
+				acknowledgedThroughOffset: 0,
+				cursorRevision
+			}
+		};
+	}
+	async #loadOnce(streamId, replaceMismatchedStream) {
+		const persisted = await this.durability?.progress.read();
+		if (persisted === void 0) {
+			const fresh = this.#freshProgress(streamId, 0);
+			await this.#commit(fresh, {
+				expectedCursorRevision: 0,
+				expectedStreamId: void 0
+			});
+			this.#progress = fresh;
+			this.#hasLoaded = true;
+			return;
+		}
+		if (persisted.streamId !== streamId) {
+			if (!replaceMismatchedStream) throw new Error(`hosted callback for stream ID ${streamId} is stale; processor progress belongs to ${persisted.streamId}`);
+			const replaceForStream = this.durability?.progress.replaceForStream;
+			if (replaceForStream === void 0) throw new Error(`stream processor "${this.hooks.contract.slug}" progress belongs to stream ID ${persisted.streamId}, but the current stream ID is ${streamId}; this durability backend must reset its related projections before reopening`);
+			const fresh = this.#freshProgress(streamId, persisted.processing.cursorRevision + 1);
+			await replaceForStream(fresh, {
+				expectedCursorRevision: persisted.processing.cursorRevision,
+				expectedStreamId: persisted.streamId
+			});
+			this.#progress = fresh;
+			this.#hasLoaded = true;
+			this.#notifyStateChange({
+				offset: 0,
+				state: fresh.reduction.state
+			});
+			return;
+		}
+		const acknowledged = persisted.processing.acknowledgedThroughOffset;
+		const parsed = this.hooks.parseState(persisted.reduction.state);
+		const reducedAheadOfAck = persisted.reduction.reducedThroughOffset > acknowledged;
+		if (persisted.reduction.reducerVersion === this.hooks.contract.version && parsed.success && !reducedAheadOfAck) {
+			let reduction = {
+				...persisted.reduction,
+				state: parsed.state
+			};
+			if (reduction.reducedThroughOffset < acknowledged) {
+				reduction = await this.#rebuildReduction(streamId, acknowledged, {
+					state: reduction.state,
+					reducedThroughOffset: reduction.reducedThroughOffset
+				});
+				const progress = {
+					streamId,
+					reduction,
+					processing: persisted.processing
+				};
+				await this.#commit(progress, {
+					expectedCursorRevision: persisted.processing.cursorRevision,
+					expectedStreamId: streamId
+				});
+				this.#progress = progress;
+				this.#hasLoaded = true;
+				return;
+			}
+			this.#progress = {
+				streamId,
+				reduction,
+				processing: persisted.processing
+			};
+			this.#hasLoaded = true;
+			return;
+		}
+		console.warn(reducedAheadOfAck ? `stream processor "${this.hooks.contract.slug}" persisted reduction cursor (${persisted.reduction.reducedThroughOffset}) is AHEAD of the acknowledged cursor (${acknowledged}) — an invalid record; discarding the fold and refolding reduce-only through the acknowledgement` : `stream processor "${this.hooks.contract.slug}" reduction cache is stale (persisted reducerVersion "${persisted.reduction.reducerVersion}", current "${this.hooks.contract.version}", state ${parsed.success ? "valid" : "invalid"}); refolding reduce-only through acknowledged offset ${acknowledged}`);
+		const progress = {
+			streamId,
+			reduction: await this.#rebuildReduction(streamId, acknowledged),
+			processing: persisted.processing
+		};
+		await this.#commit(progress, {
+			expectedCursorRevision: persisted.processing.cursorRevision,
+			expectedStreamId: streamId
+		});
+		this.#progress = progress;
+		this.#hasLoaded = true;
+	}
+	/** Rebuild the fold through `throughOffset`, reduce ONLY, paged — from
+	* offset 0 by default, or extending `from` (a valid persisted fold that
+	* LAGS the target, so only the gap's events are read). */
+	async #rebuildReduction(streamId, throughOffset, from) {
+		let state = from?.state ?? this.hooks.initialState();
+		let afterOffset = from?.reducedThroughOffset ?? 0;
+		if (throughOffset > afterOffset) for (;;) {
+			const page = await this.stream.getEventPage({
+				afterOffset,
+				beforeOffset: throughOffset + 1,
+				byteLimit: MAX_STREAM_EVENT_READ_BYTE_LIMIT,
+				limit: this.readPageSize
+			});
+			this.#assertReadStreamId(page.streamId, streamId);
+			if (page.events.length === 0) break;
+			for (const event of page.events) {
+				if (event.offset > throughOffset) continue;
+				const reduction = this.hooks.reduceRawEvent({
+					event,
+					state
+				});
+				if (reduction !== void 0 && !("parseError" in reduction)) state = reduction.state;
+			}
+			afterOffset = page.events.at(-1).offset;
+		}
+		return {
+			reducerVersion: this.hooks.contract.version,
+			reducedThroughOffset: throughOffset,
+			state
+		};
+	}
+	async #commit(progress, opts) {
+		if (this.durability === void 0) return;
+		await this.durability.progress.commit(progress, opts);
+	}
+	/**
+	* Re-run `reduce` + `processEvent` from the acknowledged cursor by
+	* reading the journal itself — catch-up cannot rely on a callback whose
+	* starting offset was fixed when it opened. One page of lookahead means
+	* every non-final batch carries a streamMaxOffset past its own last event (the
+	* `caughtUp` flag appears only on the genuinely final page), matching the
+	* host's catch-up.
+	*/
+	async #selfCatchUp() {
+		const streamId = this.#requireProgress().streamId;
+		let scannedAfterOffset = this.#requireProgress().processing.acknowledgedThroughOffset;
+		let targetOffset;
+		for (;;) {
+			const page = await this.stream.getEventPage({
+				afterOffset: scannedAfterOffset,
+				...targetOffset === void 0 ? {} : { beforeOffset: targetOffset + 1 },
+				byteLimit: MAX_STREAM_EVENT_READ_BYTE_LIMIT,
+				limit: this.readPageSize
+			});
+			this.#assertReadStreamId(page.streamId, streamId);
+			targetOffset ??= page.streamMaxOffset;
+			const lastEventOffset = page.events.at(-1)?.offset;
+			const isFinalPage = lastEventOffset === void 0 || lastEventOffset >= targetOffset;
+			const scannedThroughOffset = isFinalPage ? targetOffset : lastEventOffset;
+			if (scannedThroughOffset <= scannedAfterOffset) return;
+			await this.#processBatch({
+				streamId,
+				events: page.events,
+				scannedAfterOffset,
+				scannedThroughOffset,
+				streamMaxOffset: targetOffset
+			});
+			scannedAfterOffset = scannedThroughOffset;
+			if (isFinalPage) return;
+		}
+	}
+	async #readCurrentStreamId(expectedStreamId) {
+		const page = await this.stream.getEventPage({
+			afterOffset: Number.MAX_SAFE_INTEGER,
+			limit: 1
+		});
+		if (expectedStreamId !== void 0 && page.streamId !== expectedStreamId) throw new Error(`stream processor "${this.hooks.contract.slug}" was opened for stream ID ${expectedStreamId}, but the stream at this path is ${page.streamId}`);
+		return page.streamId;
+	}
+	#assertReadStreamId(actualStreamId, expectedStreamId) {
+		if (actualStreamId === expectedStreamId) return;
+		throw new Error(`stream processor "${this.hooks.contract.slug}" stream ID changed during a read (${expectedStreamId} -> ${actualStreamId})`);
+	}
+	/** Fire-and-forget async work backed by the keepalive, with failures logged. */
+	#runInBackground(work) {
+		this.#keepAliveBackedWork(work).catch((error) => {
+			console.error("stream processor runner background work failed", error);
+		});
+	}
+	/**
+	* Route registered work through the recovery adapter's keepalive when
+	* present (both `blockProcessorWhile` and `runInBackground` ride it — "the
+	* DO died owing work" must equal "the alarm was armed"), else through the
+	* plain `keepAlive` hook, else run directly.
+	*/
+	async #keepAliveBackedWork(work) {
+		return await awaitKeepAliveBacked(this.durability?.recovery?.keepAliveWhile ?? this.keepAlive, work);
+	}
+	/** Serialize batches + self-pulls; the chain swallows each entry's
+	* failure so one failed batch never wedges the entries behind it. */
+	#enqueue(work) {
+		const next = this.#chain.then(() => {
+			this.#assertNotDisposed();
+			return work();
+		});
+		this.#chain = next.then(() => void 0, () => void 0);
+		return next;
+	}
+	#assertNotDisposed() {
+		if (this.#disposed) throw new Error(`StreamProcessorRunner for "${this.hooks.contract.slug}" is disposed; it accepts no new work`);
+	}
+	#requireProgress() {
+		if (this.#progress === void 0) throw new Error("StreamProcessorRunner progress read before load — this is a runner bug");
+		return this.#progress;
+	}
+	#notifyStateChange(snapshot) {
+		for (const observer of [...this.#stateChangeObservers]) try {
+			observer(snapshot);
+		} catch (error) {
+			console.error("stream processor runner state-change observer failed", error);
+		}
+	}
+	#registerEventWaiter(match, opts) {
+		let waiter;
+		return {
+			promise: new Promise((resolve, reject) => {
+				waiter = {
+					...match,
+					reject,
+					resolve,
+					signal: opts.signal
+				};
+				this.#eventWaiters.add(waiter);
+				if (opts.timeoutMs !== void 0) waiter.timer = setTimeout(() => {
+					this.#settleEventWaiter(waiter, { error: /* @__PURE__ */ new Error(`waitUntilEvent timed out after ${opts.timeoutMs}ms`) });
+				}, opts.timeoutMs);
+				if (opts.signal !== void 0) {
+					waiter.abortListener = () => {
+						this.#settleEventWaiter(waiter, { error: abortReason(opts.signal) });
+					};
+					opts.signal.addEventListener("abort", waiter.abortListener, { once: true });
+					if (opts.signal.aborted) waiter.abortListener();
+				}
+			}),
+			reject: (error) => this.#settleEventWaiter(waiter, { error })
+		};
+	}
+	#settleEventWaiter(waiter, outcome) {
+		if (!this.#eventWaiters.delete(waiter)) return;
+		if (waiter.timer !== void 0) clearTimeout(waiter.timer);
+		if (waiter.signal !== void 0 && waiter.abortListener !== void 0) waiter.signal.removeEventListener("abort", waiter.abortListener);
+		if ("error" in outcome) waiter.reject(outcome.error);
+		else waiter.resolve();
+	}
+	#resolveEventWaiters(events, acknowledgedThroughOffset) {
+		for (const waiter of this.#eventWaiters) {
+			let matched = false;
+			try {
+				matched = waiter.kind === "offset" ? acknowledgedThroughOffset >= waiter.offset : events.some(waiter.predicate);
+			} catch (error) {
+				this.#settleEventWaiter(waiter, { error });
+				continue;
+			}
+			if (matched) this.#settleEventWaiter(waiter, { value: void 0 });
+		}
+	}
+};
+function assertProcessorEventBatch(batch) {
+	const coordinates = [
+		["scannedAfterOffset", batch.scannedAfterOffset],
+		["scannedThroughOffset", batch.scannedThroughOffset],
+		["streamMaxOffset", batch.streamMaxOffset]
+	];
+	for (const [name, value] of coordinates) if (!Number.isSafeInteger(value) || value < 0) throw new Error(`stream processor event batch ${name} must be a non-negative safe integer`);
+	if (batch.scannedThroughOffset < batch.scannedAfterOffset) throw new Error(`stream processor event batch scan regressed: ${batch.scannedAfterOffset} -> ${batch.scannedThroughOffset}`);
+	if (batch.streamMaxOffset < batch.scannedThroughOffset) throw new Error(`stream processor event batch scan ${batch.scannedThroughOffset} is ahead of stream maximum offset ${batch.streamMaxOffset}`);
+	let previousOffset = batch.scannedAfterOffset;
+	for (const event of batch.events) {
+		if (!Number.isSafeInteger(event.offset) || event.offset <= previousOffset) throw new Error(`stream processor event batch events must increase strictly after scan cursor ${previousOffset}; found ${event.offset}`);
+		if (event.offset > batch.scannedThroughOffset) throw new Error(`stream processor event batch event ${event.offset} is beyond scanned-through offset ${batch.scannedThroughOffset}`);
+		previousOffset = event.offset;
+	}
+}
+function abortReason(signal) {
+	return signal.reason ?? /* @__PURE__ */ new Error("waitUntilEvent aborted");
+}
+//#endregion
+//#region src/processors/stream-processor-keepalive.ts
+/** How far ahead of in-flight work the alarm is scheduled. Bounds post-eviction
+* revival latency; a deploy mid-agent-turn recovers within roughly this. */
+const KEEPALIVE_ALARM_LEAD_MS = 1e4;
+/**
+* Floor between redundant re-assertions of an already-sufficient alarm.
+* See #ensureArmedForWork: the re-assert exists to heal a lost platform
+* write, and healing within a fraction of the lead is as good as instantly.
+*/
+const KEEPALIVE_REASSERT_MIN_INTERVAL_MS = 2500;
+/** Revival backoff by attempt number (1-based); past the table, the plateau. */
+const REVIVAL_BACKOFF_MS = [
+	1e4,
+	6e4,
+	5 * 6e4,
+	30 * 6e4
+];
+const REVIVAL_BACKOFF_PLATEAU_MS = 360 * 6e4;
+/** Attempts before the crash-loop evidence fact is appended (once per version). */
+const CRASH_LOOP_EVIDENCE_THRESHOLD = 3;
+/**
+* Consecutive busy fires with NO settlement in between before the window is
+* treated as wedged (a hung promise nothing will ever settle — e.g. a socket
+* with no deadline). 90 fires ≈ 15 minutes at the lead, comfortably past the
+* longest legitimate tracked work (the providers' 10-minute deadlines), so
+* legit work never trips it while a wedge decays into the revival backoff
+* instead of re-arming every lead interval forever.
+*/
+const MAX_CONSECUTIVE_BUSY_REFIRES = 90;
+function revivalBackoffMs(revivals) {
+	return REVIVAL_BACKOFF_MS[revivals - 1] ?? 216e5;
+}
+const FRESH_RECORD = {
+	revivals: 0,
+	lastRevivalAt: 0,
+	armedAtMs: null
+};
+var ProcessorKeepalive = class {
+	#hooks;
+	#inFlight = 0;
+	/** Any tracked work settled successfully since the alarm was armed. A
+	* successful revival pass also sets this — the pass IS settled work. */
+	#sawCleanSettle = false;
+	/** Any tracked work failed since the alarm was armed. Failures mean an
+	* obligation may be unsettled (a debounce append that lost its stream), so
+	* the next fire revives instead of disarming. */
+	#sawFailure = false;
+	/** Suppresses arm-earlier while the revival pass runs (see module doc). */
+	#reviving = false;
+	/** Consecutive busy fires without any settlement (wedged-work detector). */
+	#busyRefires = 0;
+	constructor(hooks) {
+		this.#hooks = hooks;
+	}
+	/**
+	* The keepalive's current alarm desire, for the host's slice merge. Read
+	* straight from the durable record (synchronous DO KV) — a separate
+	* in-memory copy would be one more thing to drift after an eviction, and
+	* stale copied state is exactly the failure class this module hunts.
+	*/
+	/** When an already-armed desire was last re-asserted; in-memory on purpose
+	* (a fresh incarnation should re-assert on its first tracked work). */
+	#lastReassertAtMs = 0;
+	get armedAtMs() {
+		return this.#hooks.readRecord()?.armedAtMs ?? null;
+	}
+	/**
+	* Register one unit of in-flight work. Every registered work closure —
+	* blocking and background alike — rides through here, so "the DO died owing
+	* work" is exactly "the DO died with the alarm armed".
+	*/
+	track(work) {
+		this.#inFlight += 1;
+		this.#ensureArmedForWork();
+		this.#hooks.keepAlive(work.then(() => {
+			this.#inFlight -= 1;
+			this.#sawCleanSettle = true;
+			this.#busyRefires = 0;
+		}, () => {
+			this.#inFlight -= 1;
+			this.#sawFailure = true;
+			this.#busyRefires = 0;
+		}));
+	}
+	/**
+	* The DO alarm handler body. The shared alarm may fire for another
+	* subsystem's slice (the scheduler's), so this self-gates on the persisted
+	* armed time and does nothing when the fire is not the keepalive's.
+	*/
+	async onAlarm() {
+		const now = this.#hooks.now();
+		const armedAt = this.armedAtMs;
+		if (armedAt === null || now < armedAt) return "not_due";
+		if (this.#inFlight > 0 || this.#reviving) {
+			this.#busyRefires += 1;
+			if (this.#busyRefires < 90) {
+				this.#arm(now + KEEPALIVE_ALARM_LEAD_MS);
+				return "busy_rearmed";
+			}
+			if (this.#reviving) {
+				this.#arm(now + REVIVAL_BACKOFF_PLATEAU_MS);
+				return "revival_hung_backoff";
+			}
+		}
+		if (this.#inFlight === 0 && this.#sawCleanSettle && !this.#sawFailure) {
+			this.#sawCleanSettle = false;
+			this.#disarmAndReset();
+			return "clean_disarmed";
+		}
+		return await this.#revive(now);
+	}
+	async #revive(now) {
+		const previous = this.#hooks.readRecord();
+		const priorRevivals = previous === void 0 || previous.version !== this.#hooks.version ? 0 : previous.revivals;
+		const record = {
+			revivals: priorRevivals + 1,
+			lastRevivalAt: now,
+			version: this.#hooks.version,
+			armedAtMs: now + revivalBackoffMs(priorRevivals + 1)
+		};
+		this.#hooks.writeRecord(record);
+		this.#hooks.armAlarm(record.armedAtMs);
+		if (record.revivals === CRASH_LOOP_EVIDENCE_THRESHOLD) this.#hooks.appendFact({
+			type: "events.iterate.com/stream/error-occurred",
+			idempotencyKey: `processor-host-crash-loop:${record.version}`,
+			payload: { message: `processor host revival has failed ${record.revivals} consecutive times on version ${record.version}; backing off (plateau ${REVIVAL_BACKOFF_PLATEAU_MS / 6e4}m). A deploy resets the budget.` }
+		});
+		this.#sawFailure = false;
+		this.#sawCleanSettle = false;
+		this.#reviving = true;
+		try {
+			await this.#hooks.revive(record);
+			this.#sawCleanSettle = true;
+			if (!(this.#inFlight > 0 && this.#busyRefires >= 90)) this.#arm(this.#hooks.now() + KEEPALIVE_ALARM_LEAD_MS);
+			return "revived";
+		} catch (error) {
+			if (this.#hooks.discardFailedRevival?.(error, record) === true) {
+				this.#sawFailure = false;
+				this.#sawCleanSettle = false;
+				return "revival_discarded";
+			}
+			console.error("stream processor host revival failed; backing off", {
+				revivals: record.revivals,
+				nextAttemptAt: record.armedAtMs,
+				error
+			});
+			this.#sawFailure = true;
+			return "revival_failed";
+		} finally {
+			this.#reviving = false;
+		}
+	}
+	/**
+	* The operator's no-deploy antidote: clear the crash-loop budget and, when
+	* a retry is owed (the record is armed), pull it in to the confirmation
+	* lead so the next fire revives promptly on the fresh budget. Without this
+	* the mark resets only on a quiet-clean confirmation or a version change —
+	* a 3-strikes plateau otherwise mutes a wedged processor for six hours at
+	* a time with a deploy as the only cure (the 2026-08-11 prod incident).
+	*/
+	resetBackoff() {
+		const record = this.#hooks.readRecord();
+		if (record === void 0) return;
+		if (record.armedAtMs === null) {
+			this.#hooks.writeRecord({
+				...FRESH_RECORD,
+				version: this.#hooks.version
+			});
+			return;
+		}
+		const atMs = this.#hooks.now() + KEEPALIVE_ALARM_LEAD_MS;
+		this.#hooks.writeRecord({
+			...FRESH_RECORD,
+			version: this.#hooks.version,
+			armedAtMs: atMs
+		});
+		this.#hooks.armAlarm(atMs);
+	}
+	/** Arm for in-flight work: move the alarm earlier, never later, and never
+	* during a revival pass (its backoff safety net must govern). */
+	#ensureArmedForWork() {
+		if (this.#reviving) return;
+		const nowMs = this.#hooks.now();
+		const atMs = nowMs + KEEPALIVE_ALARM_LEAD_MS;
+		const armedAt = this.armedAtMs;
+		if (armedAt !== null && armedAt <= atMs) {
+			if (nowMs - this.#lastReassertAtMs < KEEPALIVE_REASSERT_MIN_INTERVAL_MS) return;
+			this.#lastReassertAtMs = nowMs;
+			this.#hooks.armAlarm(armedAt);
+			return;
+		}
+		this.#lastReassertAtMs = nowMs;
+		this.#arm(atMs);
+	}
+	#arm(atMs) {
+		const record = this.#hooks.readRecord();
+		this.#hooks.writeRecord({
+			...record?.version === this.#hooks.version ? record : {
+				...FRESH_RECORD,
+				version: this.#hooks.version
+			},
+			armedAtMs: atMs
+		});
+		this.#hooks.armAlarm(atMs);
+	}
+	#disarmAndReset() {
+		const record = this.#hooks.readRecord();
+		if (record !== void 0 && (record.revivals !== 0 || record.armedAtMs !== null)) this.#hooks.writeRecord({
+			...FRESH_RECORD,
+			version: this.#hooks.version
+		});
+		this.#hooks.armAlarm(null);
+	}
+};
+//#endregion
+export { resolveStreamPath as A, StreamListItem as C, StreamRuntimeMetrics as D, MinuteBuckets as E, isStreamIdMismatchError as F, isStreamOffsetConflictError as I, isStreamReceiverUnavailableError as L, StreamIdMismatchError as M, StreamOffsetConflictError as N, ageStreamThroughputMetrics as O, StreamReceiverUnavailableError as P, streamIdMismatchMessage as R, StreamEventInput as S, LatencyRing as T, getEventInputSchema as _, revivalBackoffMs as a, MAX_COPIED_FROM_HOPS as b, awaitKeepAliveBacked as c, STREAM_PROCESSOR_REVIVED_EVENT_TYPE as d, assertObjectProcessorState as f, getConsumedEventDefinition as g, defineProcessorContract as h, REVIVAL_BACKOFF_PLATEAU_MS as i, MAX_STREAM_EVENT_READ_BYTE_LIMIT as j, pingRoundTrip as k, PLATFORM_STREAM_EVENTS as l, cachedEventSchema as m, MAX_CONSECUTIVE_BUSY_REFIRES as n, StreamProcessorRunner as o, buildEvent as p, ProcessorKeepalive as r, StreamProcessor as s, KEEPALIVE_ALARM_LEAD_MS as t, ProcessorContractAnnouncement as u, getResolvedEventDefinition as v, EventConsumptionMetrics as w, StreamEvent as x, mergeProcessorConfig as y, streamOffsetConflictMessage as z };
+
+//# sourceMappingURL=stream-processor-keepalive-DAQTP6m3.mjs.map