iterate 0.2.6 → 0.3.0

package/dist/processors/stream-processor-keepalive.d.ts

@@ -0,0 +1,95 @@
+import type { StreamEventInput } from "./schemas.ts";
+/**
+ * The durable mark, stored in DO KV BELOW the journal/fold: the crash-loop
+ * breaker must live beneath the state reduction it protects (a failing fold
+ * cannot be asked to fold its own pause fact). KV is authoritative here;
+ * journal facts about revivals are evidence, not enforcement — the deliberate
+ * inversion of the usual rule.
+ */
+export type KeepaliveRecord = {
+    /** Consecutive revival attempts without a quiet-clean confirmation. */
+    revivals: number;
+    /** Epoch ms of the most recent revival attempt (drives the backoff). */
+    lastRevivalAt: number;
+    /** Worker version at the last write; a different live version resets the budget. */
+    version: string;
+    /**
+     * The keepalive's own armed alarm time, or null when disarmed. Persisted so
+     * a fresh incarnation can tell "this fire is mine" from "another subsystem's
+     * slice of the shared DO alarm is due" (e.g. the scheduler's) — in-memory
+     * state does not survive the eviction that makes revival necessary.
+     */
+    armedAtMs: number | null;
+};
+type ProcessorKeepaliveHooks = {
+    /** Injected clock (epoch ms). */
+    now(): number;
+    /** Read the durable record. Synchronous DO KV in production. */
+    readRecord(): KeepaliveRecord | undefined;
+    /** Write the durable record. */
+    writeRecord(record: KeepaliveRecord): void;
+    /** Repoint (or clear) the keepalive's slice of the DO alarm. */
+    armAlarm(atMs: number | null): void;
+    /** Keep the DO alive while tracked work runs (ctx.waitUntil). */
+    keepAlive(work: Promise<unknown>): void;
+    /**
+     * The revival pass: append the journaled revival fact, then pull every
+     * hosted processor through its pending events so end-of-batch
+     * reconciliations run. Must throw on failure — the breaker owns the retry.
+     */
+    revive(record: KeepaliveRecord): Promise<void>;
+    /**
+     * Classify and dispose a revival that can never become valid on retry.
+     * Return true only after synchronously removing this attempt's durable
+     * desire (or proving a newer desire replaced it). The keepalive then stops
+     * without arming another retry.
+     */
+    discardFailedRevival?(error: unknown, record: KeepaliveRecord): boolean;
+    /** Best-effort journal evidence (crash-loop warnings). Must not throw. */
+    appendFact(event: StreamEventInput): void;
+    /** Current worker deploy version (antidote-deploy budget reset). */
+    version: string;
+};
+/** 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. */
+export declare const KEEPALIVE_ALARM_LEAD_MS = 10000;
+export declare const REVIVAL_BACKOFF_PLATEAU_MS: number;
+/**
+ * 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.
+ */
+export declare const MAX_CONSECUTIVE_BUSY_REFIRES = 90;
+/** The semantic outcome of one platform alarm reaching the keepalive. */
+type ProcessorKeepaliveAlarmAction = "not_due" | "busy_rearmed" | "revival_hung_backoff" | "clean_disarmed" | "revived" | "revival_discarded" | "revival_failed";
+export declare function revivalBackoffMs(revivals: number): number;
+export declare class ProcessorKeepalive {
+    #private;
+    constructor(hooks: ProcessorKeepaliveHooks);
+    get armedAtMs(): number | 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: Promise<unknown>): void;
+    /**
+     * 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.
+     */
+    onAlarm(): Promise<ProcessorKeepaliveAlarmAction>;
+    /**
+     * 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(): void;
+}
+export {};

package/dist/processors/stream-processor-registry.d.ts

@@ -0,0 +1,233 @@
+import { LiveState } from "../sdk/capnweb/live-state/engine.ts";
+import type { ProcessorStream } from "./stream-handle.ts";
+import type { StreamEvent } from "./schemas.ts";
+import type { StreamProcessorWakeRequest, StreamProcessorWakeResponse } from "./rpc-types.ts";
+import type { ProcessorState } from "./processor-contracts.ts";
+import type { ProcessorReads } from "./stream-processor.ts";
+import { type AnyHostedProcessor } from "./processor-host-capabilities.ts";
+/**
+ * What `register` accepts: a real {@link StreamProcessor} subclass instance
+ * that also carries the hosted-capability surface — contract description,
+ * runtime state, event-consumption metrics — the wake call shares with the
+ * browser host. The bound is STRUCTURAL ({@link AnyHostedProcessor})
+ * because the class itself cannot appear here: it is
+ * invariant in its contract parameter (private state storage holds `State` in
+ * both positions), so no single instantiation is a supertype of all
+ * processors. The "must be a real StreamProcessor" half is enforced at
+ * construction instead — the runner's `StreamProcessor.runnerHooks` reaches
+ * the class's own private hooks and throws on a structural impostor.
+ */
+export type RegisterableProcessor = AnyHostedProcessor;
+/**
+ * The folded-state type of a registered processor, derived from its
+ * contract's `stateSchema` — the class's contract parameter is invariant and
+ * cannot be named through {@link RegisterableProcessor}'s structural bound,
+ * but every concrete subclass's `contract` property already carries the
+ * schema whose output IS the state type.
+ */
+export type RegisteredProcessorState<P extends RegisterableProcessor> = ProcessorState<P["contract"]>;
+/**
+ * What {@link StreamProcessorRegistry.reads} returns: the RPC-facing
+ * {@link ProcessorReads} plus the two synchronous reads a DO's `getLiveState`
+ * closure needs (live-state assembly runs synchronously; see `refreshLive`),
+ * with `waitUntilEvent` widened to the runner's full waiter — the offset
+ * barrier {@link ProcessorReads} publishes over RPC PLUS the in-process-only
+ * predicate form (a function cannot cross the RPC facade; a DO wires it into
+ * processor deps that wait for a specific future event, e.g. the capability
+ * host's script-completion wait).
+ */
+export type RegisteredProcessorReads<State> = Omit<ProcessorReads<State>, "waitUntilEvent"> & {
+    waitUntilEvent(input: {
+        offset: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    } | {
+        predicate: (event: StreamEvent) => boolean;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** The runner's committed fold, synchronously (schema default until loaded). */
+    readonly currentState: State;
+    /** Committed processing cursor, read atomically with currentState in live assembly. */
+    readonly currentAcknowledgedThroughOffset: number;
+    /** Source lifetime paired atomically with currentState and its cursor. */
+    readonly currentStreamId: string | undefined;
+    /** Whether `currentState` is a real fold — gate live publishing on it. */
+    readonly isLoaded: boolean;
+    /**
+     * Fold through the durable stream tail or throw. The registry and this
+     * processor-specific door have the same strict contract.
+     */
+    catchUp(): Promise<void>;
+};
+/**
+ * Options for {@link StreamProcessorRegistry.register}. A processor registers
+ * under its contract slug by default — which IS the subscription name under the
+ * identity doctrine (docs/stream-subscription-model-redesign.md): the same
+ * string as the stream's catalog key, the facet name under facet placement,
+ * and the progress-key component. Pass an explicit `name` to register a second
+ * instance of one contract under a distinct name; reads, wake routing, and
+ * progress storage all already key by that name (see `reads`, `resolveProcessorName`,
+ * and `durableObjectProgressStore`), so the instances stay independent.
+ */
+export type RegisterProcessorOptions<State = unknown> = {
+    /** Clear this processor's related projections synchronously with source-lifetime replacement. */
+    resetForStream?: () => void;
+    /** Post-eviction keepalive recovery — REQUIRED for consequential
+     * `runInBackground` work (see the module doc). */
+    recovery?: boolean;
+    /** Registered/progress name for this instance. Defaults to the contract slug
+     * (name === slug, the identity-doctrine default). Supply a distinct name to
+     * host two instances of one contract on one registry without colliding. */
+    name?: string;
+    /** Persist a bounded reduction cache; a cold runner refolds when it is omitted. */
+    reductionCache?: {
+        shouldCacheReduction(state: State): boolean;
+        initialState(): State;
+    };
+};
+export type StreamProcessorRegistry<Live extends object = Record<string, unknown>> = {
+    readonly stream: ProcessorStream;
+    /** The node's live-state engine; a `.liveState` RpcTarget exposes getState()/subscribe() over it. */
+    readonly live: LiveState<Live>;
+    /**
+     * Reassemble the live state from current inputs — the ONE writer for the
+     * engine. Call it after mutating any non-runner live-state input (the
+     * streams index, the demo counter); a runner's own committed-state change
+     * calls it automatically via `observeStateChanges`. On a cold DO (a
+     * runner's progress not yet loaded) it does nothing instead of publishing
+     * the schema default over real facts; `loadAndRefreshLive` is the explicit
+     * asynchronous loading door.
+     */
+    refreshLive(): void;
+    /**
+     * `refreshLive`'s cold-start sibling: LOAD every runner's progress, THEN
+     * reassemble — so the first read or connection reflects committed writes
+     * even on a cold DO. (Distinct names because the difference — one awaits
+     * storage, one must not — is exactly what a call site gets wrong.)
+     */
+    loadAndRefreshLive(): Promise<void>;
+    /** Registered processor names, in registration order. */
+    readonly names: readonly string[];
+    /**
+     * Register a processor (constructed by the DO — the processor is the star,
+     * the registry is plumbing) under its contract slug (= subscription name —
+     * see {@link RegisterProcessorOptions}) and build its runner: durable
+     * two-cursor progress in DO KV keyed by the name, plus — WHEN THE
+     * DO PASSES `{ recovery: true }` — the per-runner recovery adapter
+     * (keepalive + the core `stream/processor-revived` fact). See the module
+     * doc: recovery is REQUIRED for any processor whose `runInBackground` work
+     * is consequential; the registry cannot infer that.
+     * Duplicate names (and re-registering the same instance) throw. Returns the
+     * processor, so DOs keep their `field = registry.register(new XProcessor(...))` shape.
+     */
+    register<P extends RegisterableProcessor>(processor: P, opts?: RegisterProcessorOptions<RegisteredProcessorState<P>>): P;
+    /**
+     * The runner-backed READ surface for one registered processor. The runner
+     * owns both cursors and the fold — the processor instance holds no
+     * readable state at all — so every read goes through here. Hand THIS to
+     * `new StreamProcessorRpcTarget(...)` and to every DO verb that reads its
+     * own fold: `snapshot`/`waitUntilEvent` come from the runner's committed
+     * progress; `getRuntimeState` assembles the processor's contributed
+     * runtime bag under the runner's snapshot; `currentState` / `isLoaded`
+     * serve `getLiveState` closures without an async hop. Takes the registered
+     * instance so the state type flows through, or a registered NAME for hosts
+     * that route doors by subscription name (the facet) — the name form cannot
+     * carry the state type, so its reads publish `unknown` state.
+     */
+    reads<P extends RegisterableProcessor>(processor: P): RegisteredProcessorReads<RegisteredProcessorState<P>>;
+    reads(name: string): RegisteredProcessorReads<unknown>;
+    /** Observe committed fold changes for one registered processor. */
+    observeStateChanges<P extends RegisterableProcessor>(processor: P, observer: (snapshot: {
+        offset: number;
+        state: RegisteredProcessorState<P>;
+    }) => void): () => void;
+    /**
+     * Wire this to the host DO's wakeStreamProcessor RPC method. Resolves the
+     * woken runner by the request's `name` (= contract slug) and answers with
+     * its acknowledged cursor and a fresh processEventBatch.
+     */
+    wakeStreamProcessor(args: StreamProcessorWakeRequest): Promise<StreamProcessorWakeResponse>;
+    /**
+     * Pull any events stream delivery has not (yet) brought this runner and
+     * drive them now. Call before serving a read that must reflect a write the
+     * caller just made (read-your-writes): push delivery is asynchronous. The
+     * pull is serialized with live frames on the runner's chain, so racing a
+     * sink is safe. A direct Durable Object lifecycle loss gets one replay on
+     * the runner's durable cursor; all application failures and a second
+     * availability failure throw. Stale state is never presented as success.
+     */
+    catchUp(name: string): Promise<void>;
+    /**
+     * Operator seam: clear one runner's revival crash-loop budget and pull its
+     * owed retry in to the confirmation lead — the no-deploy antidote for a
+     * 3-strikes plateau ("backing off (plateau 360m). A deploy resets the
+     * budget."). No-op for a recovery-less runner.
+     */
+    resetRecoveryBackoff(name: string): void;
+    /**
+     * Wire this to the host DO's `alarm()` handler — REQUIRED on every hosting
+     * class. The fire routes to EVERY runner (each keepalive self-gates on its
+     * own persisted armed time), so a DO sharing the alarm with its own
+     * scheduling (see {@link setAlarmSlice}) calls this unconditionally and
+     * then runs its own due work.
+     */
+    handleAlarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;
+    /**
+     * Share the single DO alarm: each named slice states its own desired fire
+     * time (or null for none) and the registry arms the earliest across all
+     * slices (each runner's keepalive rides its own `keepalive:<slug>` slice).
+     * A slice owner must tolerate early fires (another slice's) and re-arm
+     * itself during its handler — in-memory desires do not survive eviction;
+     * the durable alarm plus each subsystem's re-derivation do. The returned
+     * promise settles when the platform alarm durably reflects the change;
+     * await it (and rethrow) where durability is load-bearing (error-path
+     * fallbacks), ignore it everywhere else.
+     */
+    setAlarmSlice(name: string, atMs: number | null): Promise<void>;
+    /** The slice's own current desire (NOT the merged alarm time). */
+    getAlarmSlice(name: string): number | null;
+};
+export declare function createStreamProcessorRegistry<Live extends object = Record<string, unknown>>(ctx: DurableObjectState, options: {
+    stream: ProcessorStream;
+    /** Path of the hosted stream. The registry fences every
+     * `wakeStreamProcessor` against this exact `(projectId, path)`: a wake
+     * carrying a matching processor slug but a DIFFERENT coordinate is
+     * rejected, so a stale or miswired subscription can never fold a foreign
+     * stream into this processor. (Provenance stamping still lives in the
+     * processors; this is the delivery-side isolation check.) */
+    path: string;
+    /** Owning project, or null on a global (deployment-root) stream. The other
+     * half of the wake coordinate fence (see `path`). */
+    projectId: string | null;
+    /** Worker deploy version; a change resets each keepalive's crash-loop
+     * budget (the antidote deploy). Pass `workerVersion(env)`. REQUIRED: a
+     * registry that silently defaulted this could never take the
+     * version-reset path, so a deterministic crash loop would wait out the
+     * full plateau even after the fixing deploy shipped. */
+    version: string;
+    /** Injected clock for the node test harness; production uses Date.now. */
+    now?: () => number;
+    /**
+     * Assemble this node's live state (see `LiveState`) — this is what TYPES
+     * the registry's `Live` parameter. Called on every registered runner's
+     * committed-state change and on `loadAndRefreshLive`. Omit and the live
+     * state is the primary (first-registered) runner's reduced state
+     * (untyped: `Live` stays the default record); provide it to project a
+     * redacted view or fold in extras (e.g. a streams index).
+     */
+    getLiveState?: () => Live;
+    /**
+     * Fires after every `assembleLive` pass — with `skippedUnloadedRunners:
+     * false` when the live state was actually reassembled, `true` when the
+     * pass no-oped on the unloaded-runner wall (a fresh incarnation woken by
+     * one runner's delivery while other runners are still cold). A host that
+     * pushes live state to external watchers (the liveState socket lane)
+     * needs the skipped signal: without it, a change committed behind the
+     * wall would never reach them. A dumb callback — policy lives with the
+     * caller.
+     */
+    onLiveAssembled?: (assembly: {
+        skippedUnloadedRunners: boolean;
+    }) => void;
+}): StreamProcessorRegistry<Live>;

package/dist/processors/stream-processor-runner.d.ts

@@ -0,0 +1,289 @@
+import type { ProcessorStream } from "./stream-handle.ts";
+import type { ProcessorState } from "./processor-contracts.ts";
+import type { StreamEvent } from "./schemas.ts";
+import { type StreamEventBatch } from "./rpc-types.ts";
+import { StreamProcessor, type MaybePromise, type StreamProcessorContract } from "./stream-processor.ts";
+/**
+ * The reduction half of a processor's durable progress: a disposable CACHE of
+ * the fold (the journal is the authority). `reducerVersion` is the cache key —
+ * a deploy that changes it invalidates the cache and triggers an automatic
+ * reduce-only refold at load, which re-runs `reduce` ONLY. That is the whole point of splitting
+ * this from {@link ProcessingProgress}: today's single `{offset, state}` cursor
+ * makes a routine state-schema deploy refold history AND re-run `processEvent`
+ * across it, re-driving real vendor calls.
+ */
+export type ReductionProgress<State> = {
+    /** Cache key for the fold; a mismatch discards `state` and refolds. */
+    reducerVersion: string;
+    /** The highest offset folded into `state`. */
+    reducedThroughOffset: number;
+    /** The fold through `reducedThroughOffset`, under `reducerVersion`. */
+    state: State;
+};
+/**
+ * The processing half of a processor's durable progress: the AUTHORITATIVE
+ * effect-acknowledgement cursor. Unlike the reduction cache it is never
+ * discarded — rewinding it re-runs side effects. `cursorRevision` is the CAS
+ * fence for exactly those rewinds: every commit asserts it, and a bump makes
+ * every in-flight continuation of the old cursor position stale.
+ */
+export type ProcessingProgress = {
+    /** Every effect at or below this offset is acknowledged (durably settled). */
+    acknowledgedThroughOffset: number;
+    /** Monotonic fencing token; a bump is the only sanctioned way to move
+     * `acknowledgedThroughOffset` backward. */
+    cursorRevision: number;
+};
+/**
+ * A processor's two durable positions, persisted as one record. Invariant
+ * (when persisted): `reduction.reducedThroughOffset <=
+ * processing.acknowledgedThroughOffset` — the fold cache may lag the effect
+ * cursor (it is rebuildable), but a fold AHEAD of acknowledged effects would
+ * let `snapshot()` show state derived from events whose effects a cursor
+ * rewind is about to re-run. Core (Phase 2) is the graceful degradation:
+ * reduction only, no processing cursor — same structure, same reduce-only refold.
+ */
+export type ProcessorProgress<State> = {
+    /** Random identity of the stream lifetime whose offsets and fold this record describes. */
+    streamId: string;
+    reduction: ReductionProgress<State>;
+    processing: ProcessingProgress;
+};
+/**
+ * Durable progress store, CAS-fenced by `cursorRevision`. The runner reads
+ * once at open, then commits once per delivered batch; `commit` rejects
+ * (throws) if `expectedCursorRevision` no longer matches the persisted
+ * revision — the fence that stops a stale incarnation (or a continuation
+ * outliving a cursor rewind) from clobbering the rewound cursor.
+ * An absent record reads as revision 0. Backends use DO KV or an in-memory
+ * store in tests. Related projections share the same commit boundary.
+ */
+export type ProcessorProgressStore<State> = {
+    read(): MaybePromise<ProcessorProgress<State> | undefined>;
+    commit(progress: ProcessorProgress<State>, opts: {
+        expectedCursorRevision: number;
+        expectedStreamId: string | undefined;
+    }): MaybePromise<void>;
+    /**
+     * Atomically replace progress after the stream at this path is recreated.
+     * Backends with related durable projections must reset those in the same
+     * transaction; omitting this method makes recreation fail closed.
+     */
+    replaceForStream?(progress: ProcessorProgress<State>, opts: {
+        expectedCursorRevision: number;
+        expectedStreamId: string;
+    }): MaybePromise<void>;
+};
+/**
+ * Optional recovery capability. Present only for durable processors that own
+ * background obligations (`runInBackground` work whose OUTCOME matters).
+ *
+ * - `keepAliveWhile` schedules a durable alarm ahead of in-flight work, so an
+ *   incarnation that dies owing work is revived by the alarm's fire. The
+ *   production adapter is `(work) => keepalive.track(work())` over ONE
+ *   ProcessorKeepalive (stream-processor-keepalive.ts) — the runner REUSES
+ *   that machinery wholesale, it never reinvents mark/backoff/quiet-clean.
+ * - The adapter's private revival pass appends the core
+ *   `stream/processor-revived` fact (the payload's `processorSlug` names the
+ *   revived processor), guaranteeing at least one delivery turn even at zero
+ *   lag. Consuming the fact is OPTIONAL: an unconsumed head-reaching frame
+ *   still gets the runner's eventless
+ *   `processEvent({ event: null, delivery: { caughtUp: true } })` pass.
+ * - `handleAlarm` services the durable timer (`ProcessorKeepalive.onAlarm`);
+ *   the host DO multiplexes its single alarm across runners and routes fires
+ *   to {@link StreamProcessorRunner.handleAlarm}, which delegates here.
+ */
+export type ProcessorRecovery = {
+    keepAliveWhile(work: () => Promise<unknown>): void;
+    handleAlarm(info?: unknown): MaybePromise<void>;
+    /**
+     * Operator seam: clear the keepalive's crash-loop budget and pull an owed
+     * retry in to the confirmation lead — the no-deploy antidote for a
+     * 3-strikes revival plateau. Optional: in-memory/test recoveries without a
+     * durable budget have nothing to reset.
+     */
+    resetBackoff?(): void;
+};
+/**
+ * The ONE optional durability adapter a hosting runtime hands the runner:
+ * `progress` is required whenever the processor is durable at all (without the
+ * adapter the runner keeps progress in memory — tests, ephemeral
+ * views); `recovery` is orthogonal and present only when the processor owns
+ * background work that must survive eviction. This is deliberately where
+ * every runtime-specific concern lives — no Cloudflare `ctx` in the runner.
+ */
+type ProcessorDurability<State> = {
+    progress: ProcessorProgressStore<State>;
+    recovery?: ProcessorRecovery;
+};
+/** Honest delivery information handed to `processEvent`. */
+export type DeliveryContext = {
+    /** Random identity of the stream lifetime that delivered this turn. */
+    streamId: string;
+    /**
+     * The at-head signal: the scan has reached the highest raw stream offset
+     * the runner has observed, so `state` is the complete reduction of
+     * everything it has seen. It is true on the last consumed event of a
+     * head-reaching frame. If that frame contains no consumed event, the runner
+     * makes one eventless `processEvent` call (`event: null`) with this flag
+     * instead; an unconsumed tail must not strand obligations on an otherwise
+     * quiet stream.
+     */
+    caughtUp: boolean;
+};
+/**
+ * One transport scan as delivered to the runner. The scan coordinates are
+ * first-class rather than inferred from `events`: a delivery may deliberately
+ * omit ephemeral or selector-filtered rows, including an entirely empty
+ * interval, while still proving that every raw offset in the interval was
+ * examined. Advancing through that proof is what prevents filtered rows from
+ * leaving a processor cursor below the scanned-through offset.
+ */
+export type StreamProcessorEventBatch = Pick<StreamEventBatch, "events" | "scannedAfterOffset" | "scannedThroughOffset" | "streamId" | "streamMaxOffset">;
+/**
+ * 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.
+ */
+export declare class StreamProcessorRunner<Contract extends StreamProcessorContract, Deps extends object = object> {
+    #private;
+    private readonly processor;
+    private readonly hooks;
+    private readonly stream;
+    private readonly durability;
+    private readonly keepAlive;
+    private readonly now;
+    private readonly readPageSize;
+    constructor(args: {
+        /** The processor to run — passed in; the runner never constructs one. */
+        processor: StreamProcessor<Contract, Deps>;
+        /** The processor's home stream (replay reads, revival appends). */
+        stream: ProcessorStream;
+        /** Durable progress + optional recovery; omit for in-memory (tests, ephemeral views). */
+        durability?: ProcessorDurability<ProcessorState<Contract>>;
+        /** Keeps in-flight work alive with the hosting DO's `waitUntil`. */
+        keepAlive?: (work: () => Promise<unknown>) => void;
+        /** Injected clock for the test harness; production uses Date.now. */
+        now?: () => number;
+        /** Journal read page size (refold/catch-up paging); tests shrink it. */
+        readPageSize?: number;
+    });
+    /**
+     * 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.
+     */
+    openEventBatchCallback(expectedStreamId?: string): Promise<{
+        checkpointOffset: number;
+        processEventBatch: (batch: StreamProcessorEventBatch) => Promise<void>;
+    }>;
+    /**
+     * 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.
+     */
+    openHostedEventBatchCallback(streamId: string): Promise<{
+        checkpointOffset: number;
+        processEventBatch: (batch: StreamProcessorEventBatch) => Promise<void>;
+    }>;
+    /** Handle a durable recovery alarm routed here by the hosting registry. */
+    handleAlarm(info?: unknown): Promise<void>;
+    /** One consistent read of the fold, pinned to `reducedThroughOffset`. */
+    snapshot(): Promise<{
+        offset: number;
+        state: ProcessorState<Contract>;
+    }>;
+    /**
+     * 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(): boolean;
+    /** Highest offset whose processing and blocking consequences have committed. */
+    get currentAcknowledgedThroughOffset(): number;
+    /** Source lifetime paired atomically with the current committed state and cursor. */
+    get currentStreamId(): string | undefined;
+    /**
+     * 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(): ProcessorState<Contract>;
+    /**
+     * 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: (snapshot: {
+        offset: number;
+        state: ProcessorState<Contract>;
+    }) => void): () => void;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Resolve once the ACKNOWLEDGED cursor reaches `offset` — the single
+     * wait-for-progress door (read-your-writes: append, then wait on the offset
+     * the append returned). The offset form never depends on stream delivery to
+     * reach an event that ALREADY EXISTS on the stream: when the cursor is
+     * behind, it starts a chain-serialized journal read ({@link catchUp}); the
+     * waiting promise covers only a genuinely
+     * FUTURE offset the pull cannot reach yet. The predicate form observes
+     * FUTURE deliveries only — an event not yet appended (e.g. runScript's
+     * completion, appended later by `runInBackground` work; that work runs OFF
+     * the runner chain and outside the awaiting handler, so the halted waiter
+     * never gates the append or the delivery that resolves it) — and resolves
+     * after the batch that delivered the matching event has durably committed,
+     * so state already reflects it.
+     */
+    waitUntilEvent(args: {
+        predicate: (event: StreamEvent) => boolean;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    waitUntilEvent(args: {
+        offset: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Release processor resources. Idempotent; a disposed runner rejects new work. */
+    dispose(): void;
+}
+export {};