@executablemd/durable-streams 0.2.0

package/types/context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DurableContext — the scope-local state for durable execution.
+ *
+ * Stored on each Effection scope via createContext(). Child scopes
+ * inherit the shared replayIndex and stream, but get their own
+ * coroutineId and childCounter.
+ */
+import { type Context } from "effection";
+import type { ReplayIndex } from "./replay-index.js";
+import type { DurableStream } from "./stream.js";
+import type { CoroutineId } from "./types.js";
+export interface DurableContext {
+    /** Shared replay index (built from stream on startup). */
+    replayIndex: ReplayIndex;
+    /** Shared durable stream for appending events. */
+    stream: DurableStream;
+    /** This coroutine's hierarchical ID. */
+    coroutineId: CoroutineId;
+    /** Counter for assigning child IDs. */
+    childCounter: number;
+}
+/**
+ * Effection Context for durable execution state.
+ * Set on the root scope by durableRun(); inherited by child scopes.
+ */
+export declare const DurableCtx: Context<DurableContext>;

package/types/divergence.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Divergence API — pluggable policy for handling replay mismatches.
+ *
+ * When a durable effect's description doesn't match the replay index
+ * during replay, or when a generator continues to yield effects past
+ * a recorded Close event, a divergence is detected.
+ *
+ * By default, divergence is fatal (throws DivergenceError). Users can
+ * override this behavior per-scope via Effection's around() middleware
+ * to implement custom policies (e.g., switching to live execution).
+ *
+ * Uses createApi() from effection/experimental (not @effectionx/context-api)
+ * because it requires synchronous Api.invoke() dispatch, which the
+ * vendored context-api does not yet support. Will migrate once invoke()
+ * lands in @effectionx/context-api.
+ *
+ * The core decide() function is synchronous (not a generator) because
+ * it is called from inside Effect.enter(), which is a synchronous
+ * callback. createApi().invoke() dispatches synchronously, so this
+ * is safe. See DEC-031.
+ */
+import type { Api } from "effection";
+import type { CoroutineId, EffectDescription } from "./types.js";
+/** The two kinds of divergence detected during replay. */
+export type DivergenceKind = "description-mismatch" | "continue-past-close";
+/**
+ * Information about a detected divergence.
+ *
+ * Discriminated union on `kind` so that TypeScript enforces correct
+ * field access per variant.
+ */
+export type DivergenceInfo = {
+    kind: "description-mismatch";
+    coroutineId: CoroutineId;
+    /** Cursor position (yield index) where divergence was detected. */
+    cursor: number;
+    /** The description from the journal (what was expected). */
+    expected: EffectDescription;
+    /** The description from the generator (what was actually yielded). */
+    actual: EffectDescription;
+} | {
+    kind: "continue-past-close";
+    coroutineId: CoroutineId;
+    /** Number of yield entries recorded for this coroutine. */
+    yieldCount: number;
+};
+/**
+ * The policy decision returned by the Divergence API.
+ *
+ * - "throw": Fail the workflow with the provided error (default behavior).
+ * - "run-live": Disable replay for this coroutine and execute live from
+ *   this point forward. Previous replay entries are ignored.
+ */
+export type DivergenceDecision = {
+    type: "throw";
+    error: Error;
+} | {
+    type: "run-live";
+};
+/**
+ * The core shape of the Divergence API.
+ *
+ * decide() is synchronous because it is called from Effect.enter(),
+ * which cannot yield. Middleware installed via Api.around() also
+ * runs synchronously in the chain.
+ *
+ * Usage from Effect.enter() (synchronous):
+ *   Divergence.invoke(scope, "decide", [info])
+ *
+ * Middleware installation (from a generator):
+ *   yield* Divergence.around({ decide: ([info], next) => next(info) })
+ */
+interface DivergenceApi {
+    decide(info: DivergenceInfo): DivergenceDecision;
+}
+/**
+ * The Divergence API.
+ *
+ * Created via Effection's createApi() which provides proper middleware
+ * dispatch with WeakMap-based handle caching, automatic cache
+ * invalidation on Api.around(), and a fast-path that skips
+ * middleware dispatch entirely when no middleware is installed.
+ *
+ * Default behavior is strict: all divergences produce a throw decision
+ * with the appropriate error type.
+ */
+export declare const Divergence: Api<DivergenceApi>;
+export {};

package/types/each.d.ts

@@ -0,0 +1,62 @@
+/**
+ * durableEach — durable iteration primitive for Effection workflows.
+ *
+ * Mirrors Effection's `each()` / `each.next()` pattern but journals
+ * every fetch as a DurableEffect, so iteration survives crashes and
+ * replays from the journal.
+ *
+ * Usage:
+ *   for (let msg of yield* durableEach("queue", source)) {
+ *     yield* durableCall("process", () => process(msg));
+ *     yield* durableEach.next();
+ *   }
+ *
+ * See effection-integration.md §12.6 for the full design.
+ */
+import type { Operation } from "effection";
+import type { Json, Workflow } from "./types.js";
+/**
+ * Source of items for durable iteration.
+ *
+ * Each call to `next()` blocks until the next item is available.
+ * Returns `{ value: T }` for an item, `{ done: true }` for exhaustion.
+ *
+ * The `{ done: true }` wrapper (rather than `T | null`) avoids ambiguity
+ * when `null` is a legitimate JSON value from the source.
+ */
+export interface DurableSource<T extends Json> {
+    /** Read the next item, blocking until available. */
+    next(): Operation<{
+        value: T;
+    } | {
+        done: true;
+    }>;
+    /**
+     * Teardown — called on cancellation or completion.
+     *
+     * Must be idempotent: may be called more than once (once from effect
+     * teardown during an in-flight fetch, once from scope cleanup via
+     * ensure()). Subsequent calls after the first should be no-ops.
+     */
+    close?(): void;
+}
+/**
+ * Durable iteration over a DurableSource.
+ *
+ * Returns a Workflow that fetches the first item and yields a
+ * synchronous iterable. Use with `for...of` inside a Workflow:
+ *
+ * ```typescript
+ * for (let msg of yield* durableEach("queue", source)) {
+ *   yield* durableCall("process", () => process(msg));
+ *   yield* durableEach.next();
+ * }
+ * ```
+ *
+ * @param name Stable name for the iteration
+ * @param source Operation-native source of items
+ */
+export declare const durableEach: {
+    <T extends Json>(name: string, source: DurableSource<T>): Workflow<Iterable<T>>;
+    next<T extends Json>(): Workflow<void>;
+};

package/types/effect.d.ts

@@ -0,0 +1,60 @@
+/**
+ * createDurableEffect / createDurableOperation — core factories for durable effects.
+ *
+ * Each DurableEffect handles its own replay/live dispatch inside enter().
+ * It reads DurableContext from the scope, checks the replay index, and
+ * either feeds the stored result (replay) or executes live with
+ * persist-before-resume semantics.
+ *
+ * Two factories are provided:
+ * - createDurableEffect: callback-based executor (resolve/reject/teardown)
+ *   for timer-like and callback-based APIs (durableSleep, durableAction).
+ * - createDurableOperation: Operation-based executor for structured
+ *   concurrency. The live path runs entirely as a generator — execute,
+ *   capture result, persist, resolve. No callbacks, no .then().
+ *
+ * Divergence policy is delegated to the Divergence API (DEC-031).
+ * By default, mismatches are fatal. Users can install middleware via
+ * yield* Divergence.around(...) to override behavior per-scope.
+ *
+ * See integration doc §5.1, protocol spec §4.2, §5, §6.
+ */
+import type { Operation } from "effection";
+import type { DurableEffect, EffectDescription, Json, Result } from "./types.js";
+/**
+ * Executor function signature for live execution (callback-based).
+ *
+ * The executor receives:
+ * - resolve: call with a protocol Result when the effect completes
+ * - reject: call with an Error for unexpected failures
+ *
+ * Returns a teardown function called during scope destruction/cancellation.
+ */
+export type Executor = (resolve: (result: Result) => void, reject: (error: Error) => void) => () => void;
+/**
+ * Creates a DurableEffect using a callback-based executor.
+ *
+ * Use this for timer-like and callback-based APIs (durableSleep, durableAction)
+ * where the resolve/reject/teardown pattern is natural.
+ *
+ * For Operation-based effects, prefer createDurableOperation.
+ *
+ * @param desc Structured description for the journal and divergence detection
+ * @param execute Called only during live execution (skipped during replay)
+ */
+export declare function createDurableEffect<T>(desc: EffectDescription, execute: Executor): DurableEffect<T>;
+/**
+ * Creates a DurableEffect from an Operation-returning function.
+ *
+ * The live path runs entirely as a generator inside scope.run():
+ * execute the Operation, capture the result, persist the Yield event,
+ * then resolve the generator. No callbacks, no .then(), full structured
+ * concurrency — if the scope tears down, the operation is cancelled.
+ *
+ * Use this for durableCall and any effect where the work is expressed
+ * as an Operation (or can be wrapped as one via Effection's call()).
+ *
+ * @param desc Structured description for the journal and divergence detection
+ * @param execute Returns an Operation to run during live execution
+ */
+export declare function createDurableOperation<T extends Json>(desc: EffectDescription, execute: () => Operation<T>): DurableEffect<T>;

package/types/ephemeral.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ephemeral — explicit escape hatch for non-durable Operations inside Workflows.
+ *
+ * Wraps an Operation<T> so it satisfies the Workflow<T> type contract.
+ * The wrapped operation is **transparent to the journal** — no Yield event
+ * is written, no replay index entry is consumed. On replay, the operation
+ * simply re-runs.
+ *
+ * This is analogous to Rust's `unsafe {}` — it marks the boundary where
+ * the user is opting out of durable guarantees. Every non-durable
+ * Operation that needs to participate in a Workflow must go through
+ * ephemeral() to make the escape explicit and auditable.
+ *
+ * Usage:
+ *   yield* durableAll([
+ *     () => myDurableWorkflow(),              // Workflow<T> — journaled
+ *     function*() {                            // Workflow<T> with ephemeral child
+ *       return yield* ephemeral(someOperation());
+ *     },
+ *   ]);
+ *
+ * See DEC-034 for the design rationale.
+ */
+import type { Operation } from "effection";
+import type { Workflow } from "./types.js";
+/**
+ * Wrap a non-durable Operation so it can be used inside a Workflow.
+ *
+ * The operation is transparent to the durable execution protocol:
+ * - No Yield event is written to the journal
+ * - On replay, the operation re-runs (it is not cached)
+ * - Cancellation flows through normally via structured concurrency
+ *
+ * Use this when you need to run infrastructure Operations (or intentionally
+ * non-durable work) inside a Workflow where only DurableEffects are allowed.
+ *
+ * @param operation The Operation to wrap
+ * @returns A Workflow that yields the operation's result
+ */
+export declare function ephemeral<T>(operation: Operation<T>): Workflow<T>;

package/types/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Error types for the durable execution protocol.
+ */
+import type { CoroutineId, EffectDescription } from "./types.js";
+/**
+ * Raised when the replay index entry at the current cursor position
+ * does not match the effect yielded by the generator. See spec §6.2.
+ *
+ * A DivergenceError is NOT recoverable. The workflow cannot continue
+ * because the generator's execution path has diverged from the recorded
+ * history.
+ */
+export declare class DivergenceError extends Error {
+    name: string;
+    coroutineId: CoroutineId;
+    /** Cursor position within the coroutine where divergence was detected. */
+    position: number;
+    /** The description from the journal (what was expected). */
+    expected: EffectDescription;
+    /** The description from the generator (what was actually yielded). */
+    actual: EffectDescription;
+    constructor(coroutineId: CoroutineId, position: number, expected: EffectDescription, actual: EffectDescription, message?: string);
+}
+/**
+ * Raised when the generator finishes (returns) while the replay index
+ * still has unconsumed entries for this coroutine. See spec §6.3.
+ */
+export declare class EarlyReturnDivergenceError extends Error {
+    name: string;
+    coroutineId: CoroutineId;
+    consumedCount: number;
+    totalCount: number;
+    constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number);
+}
+/**
+ * Raised when the journal has a Close event for a coroutine but the
+ * generator has not finished after consuming all recorded yields.
+ * See spec §6.3.
+ */
+export declare class ContinuePastCloseDivergenceError extends Error {
+    name: string;
+    coroutineId: CoroutineId;
+    yieldCount: number;
+    constructor(coroutineId: CoroutineId, yieldCount: number);
+}
+/**
+ * Raised by a replay guard when a journal entry's recorded result is
+ * stale (e.g., the source file has changed since the effect was
+ * originally executed).
+ *
+ * Guards detect staleness by comparing current state against data stored
+ * in the effect description (input fields like file path) and result
+ * value (output fields like content hash).
+ *
+ * StaleInputError is NOT a divergence — the effect identity matches,
+ * but the external world has changed. The correct response depends on
+ * application policy: re-run from scratch, accept stale results, or
+ * (in future versions) re-execute the effect and continue.
+ *
+ * See replay-guard-spec.md §4.4.
+ */
+export declare class StaleInputError extends Error {
+    name: string;
+    /** The Yield event that was detected as stale. */
+    event?: {
+        coroutineId: string;
+        description: {
+            type: string;
+            name: string;
+        };
+    };
+    constructor(
+    /** Human-readable description of what changed. */
+    message: string, 
+    /** The Yield event that was detected as stale. */
+    event?: {
+        coroutineId: string;
+        description: {
+            type: string;
+            name: string;
+        };
+    });
+}

package/types/http-stream.d.ts

@@ -0,0 +1,42 @@
+import type { Operation } from "effection";
+import type { DurableStream } from "./stream.js";
+/**
+ * Configuration for useHttpDurableStream.
+ */
+export interface HttpDurableStreamOptions {
+    /** Base URL of the Durable Streams server (e.g. "http://localhost:4437"). */
+    baseUrl: string;
+    /** Stream identifier. Will be used as the URL path segment. */
+    streamId: string;
+    /** Unique producer identifier for idempotent append tracking. */
+    producerId: string;
+    /** Producer epoch — monotonically increasing. Stale epochs are fenced. */
+    epoch: number;
+    /** Optional custom fetch implementation (for testing). */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Extended DurableStream with HTTP-specific observable state.
+ */
+export interface HttpDurableStreamHandle extends DurableStream {
+    /**
+     * Last Stream-Next-Offset received from the server.
+     * Tracked from both reads and writes (DEC-029).
+     * This is the resumption point for future tail() calls.
+     */
+    lastOffset: string | undefined;
+}
+/**
+ * Create an HTTP-backed DurableStream as an Effection resource.
+ *
+ * The resource:
+ * 1. Creates the stream on the server (idempotent PUT)
+ * 2. Spawns a serial worker that processes appends in FIFO order
+ * 3. Returns a DurableStream handle with Operation-native readAll/append
+ *
+ * The worker is cancelled when the resource scope is torn down.
+ *
+ * Usage:
+ *   yield* useHttpDurableStream({ baseUrl, streamId, producerId, epoch })
+ */
+export declare function useHttpDurableStream(opts: HttpDurableStreamOptions): Operation<HttpDurableStreamHandle>;

package/types/mod.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * Durable execution for Effection.
+ *
+ * Implements the two-event durable execution protocol for generator-based
+ * structured concurrency, with Durable Streams as the persistence backend.
+ */
+export type { Close, CoroutineId, CoroutineView, DurableEffect, DurableEvent, EffectDescription, EffectionResult, Json, Resolve, Result, SerializedError, Workflow, Yield, } from "./types.js";
+export { ReplayIndex } from "./replay-index.js";
+export type { YieldEntry } from "./replay-index.js";
+export type { DurableStream } from "./stream.js";
+export { InMemoryStream } from "./stream.js";
+export { useHttpDurableStream } from "./http-stream.js";
+export type { HttpDurableStreamHandle, HttpDurableStreamOptions } from "./http-stream.js";
+export { ContinuePastCloseDivergenceError, DivergenceError, EarlyReturnDivergenceError, StaleInputError, } from "./errors.js";
+export { Divergence } from "./divergence.js";
+export type { DivergenceDecision, DivergenceInfo, DivergenceKind } from "./divergence.js";
+export { ReplayGuard } from "./replay-guard.js";
+export type { ReplayOutcome } from "./replay-guard.js";
+export { DurableCtx } from "./context.js";
+export type { DurableContext } from "./context.js";
+export { deserializeError, effectionToProtocol, protocolToEffection, serializeError, } from "./serialize.js";
+export { createDurableEffect, createDurableOperation } from "./effect.js";
+export type { Executor } from "./effect.js";
+export { durableAction, durableCall, durableSleep, versionCheck } from "./operations.js";
+export { durableAll, durableRace, durableSpawn } from "./combinators.js";
+export { durableEach } from "./each.js";
+export type { DurableSource } from "./each.js";
+export { ephemeral } from "./ephemeral.js";
+export { durableRun } from "./run.js";
+export type { DurableRunOptions } from "./run.js";

package/types/operations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Workflow-enabled effects — durable equivalents of Effection's built-in
+ * operations.
+ *
+ * Each returns a Workflow<T> (a generator that yields a single DurableEffect).
+ * These are the building blocks for durable workflows.
+ *
+ * See integration doc §6.
+ */
+import type { Operation } from "effection";
+import type { Json, Workflow } from "./types.js";
+/**
+ * Durable sleep — pauses the workflow for `ms` milliseconds.
+ *
+ * During replay, resolves synchronously with the stored result.
+ * During live execution, uses setTimeout and persists the Yield event.
+ *
+ * Description: { type: "sleep", name: "sleep" }
+ */
+export declare function durableSleep(ms: number): Workflow<void>;
+/**
+ * Durable call — wraps a function for durable execution.
+ *
+ * Accepts functions returning either a Promise or an Operation.
+ * Effection's call() handles the dispatch at runtime: Promises are
+ * bridged, Operations run with full structured concurrency.
+ *
+ * The function is called during live execution; its resolved value is
+ * serialized and persisted. During replay, the stored value is returned
+ * without calling the function.
+ *
+ * Description: { type: "call", name }
+ *
+ * IMPORTANT: The function's return value must be JSON-serializable.
+ *
+ * @param name Stable identifier for the effect (used for divergence detection)
+ * @param fn Function returning a Promise or Operation (only called during live execution)
+ */
+export declare function durableCall<T extends Json>(name: string, fn: () => Promise<T> | Operation<T>): Workflow<T>;
+/**
+ * Durable action — generic effect with a custom executor.
+ *
+ * Like Effection's action(), but durable. The executor receives resolve/reject
+ * callbacks and returns a teardown function.
+ *
+ * Description: { type: "action", name }
+ */
+export declare function durableAction<T extends Json>(name: string, executor: (resolve: (value: T) => void, reject: (error: Error) => void) => () => void): Workflow<T>;
+/**
+ * Version gate — enables safe code evolution for durable workflows.
+ *
+ * During live execution, resolves with `maxVersion`. During replay, the
+ * stored version determines which code path the workflow takes.
+ *
+ * Description: { type: "version_gate", name }
+ *
+ * See spec §9.
+ */
+export declare function versionCheck(name: string, opts: {
+    minVersion: number;
+    maxVersion: number;
+}): Workflow<number>;

package/types/replay-guard.d.ts

@@ -0,0 +1,102 @@
+/**
+ * ReplayGuard API — pluggable validation for replay staleness detection.
+ *
+ * The durable execution protocol's default behavior is "logs are authoritative"
+ * — the journal is unconditionally trusted during replay. ReplayGuard extends
+ * this with opt-in validation: guards can examine effect descriptions and
+ * result values to validate that recorded results are still valid against
+ * current state before allowing replay to proceed.
+ *
+ * Guards access `event.description.*` for effect input fields (e.g., file
+ * path, URL, encoding) and `event.result.value.*` for effect output fields
+ * (e.g., content hash, status code). There is no separate metadata field —
+ * inputs belong in the effect description, outputs belong in the result.
+ *
+ * The API has two phases:
+ *
+ * 1. **check** (before replay begins): Runs in generator context inside
+ *    `durableRun`, after the journal is loaded but before the workflow starts.
+ *    I/O is allowed — this is where file hashing, network checks, and other
+ *    observation-gathering happens. Results are cached in middleware closures.
+ *
+ * 2. **decide** (during replay): Runs synchronously inside
+ *    `DurableEffect.enter()`, after identity matching succeeds but before
+ *    the stored result is fed to the generator. Must be pure and side-effect-
+ *    free. Reads from the cache populated during the check phase.
+ *
+ * Multiple guards compose via Effection's `Api.around()`. A guard that has
+ * an opinion returns an outcome directly; one that doesn't calls `next(event)`
+ * to delegate. The first `error` outcome wins — the chain short-circuits.
+ *
+ * See replay-guard-spec.md for the full design.
+ */
+import type { Api, Operation } from "effection";
+import type { Yield } from "./types.js";
+/**
+ * The outcome of a replay guard's decision.
+ *
+ * - "replay": Proceed with replay — use the stored journal result.
+ * - "error": Halt replay with an error — the journal entry is stale.
+ *
+ * Future versions may add:
+ * - "reexecute": Re-execute the effect and replace the journal entry.
+ * - "fork": Create a new execution branch from this point.
+ */
+export type ReplayOutcome = {
+    outcome: "replay";
+} | {
+    outcome: "error";
+    error?: Error;
+};
+/**
+ * The core shape of the ReplayGuard API.
+ *
+ * - `check`: Called once per Yield event, before replay begins. Runs in
+ *   generator context — I/O is allowed. Use to gather current state (hash
+ *   files, check timestamps) and cache results for the decide phase.
+ *
+ * - `decide`: Called during replay, after identity matching succeeds.
+ *   Must be pure and synchronous — no I/O, no side effects. Returns the
+ *   replay outcome based on cached observations.
+ */
+interface ReplayGuardApi {
+    /** Phase 1: Check — gather observations before replay (I/O allowed). */
+    check(event: Yield): Operation<void>;
+    /** Phase 2: Decide — return replay outcome (synchronous, pure). */
+    decide(event: Yield): ReplayOutcome;
+}
+/**
+ * The ReplayGuard API.
+ *
+ * Default behavior is pass-through: `check` does nothing, `decide` returns
+ * `{ outcome: "replay" }`. This preserves "logs are authoritative" unless
+ * middleware says otherwise.
+ *
+ * Install guards via `yield* ReplayGuard.around({ ... })` before calling
+ * `durableRun`. Guards are inherited by child scopes through Effection's
+ * context inheritance.
+ *
+ * Example:
+ * ```ts
+ * function* myWorkflow(): Operation<void> {
+ *   const scope = yield* useScope();
+ *   yield* ReplayGuard.around({
+ *     *check([event], next) {
+ *       // Gather observations (I/O allowed here)
+ *       return yield* next(event);
+ *     },
+ *     decide([event], next) {
+ *       // Make decision (pure, synchronous)
+ *       if (isStale(event)) {
+ *         return { outcome: "error", error: new StaleInputError(...) };
+ *       }
+ *       return next(event);
+ *     },
+ *   });
+ *
+ *   yield* durableRun(workflow, { stream });
+ * }
+ * ```
+ */
+export declare const ReplayGuard: Api<ReplayGuardApi>;
+export {};

package/types/replay-index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ReplayIndex — derived, in-memory structure built from the stream on startup.
+ *
+ * Provides per-coroutine cursored access to Yield events and keyed access
+ * to Close events. See spec §4.1.
+ */
+import type { Close, CoroutineId, DurableEvent, EffectDescription, Result } from "./types.js";
+export interface YieldEntry {
+    description: EffectDescription;
+    result: Result;
+}
+export declare class ReplayIndex {
+    private yields;
+    private cursors;
+    private closes;
+    /** Coroutines where replay has been disabled (run-live mode). */
+    private disabled;
+    constructor(events: DurableEvent[]);
+    /**
+     * Disable replay for a coroutine (run-live mode).
+     *
+     * Once disabled, peekYield() returns undefined and hasClose() returns
+     * false for this coroutine, so all subsequent effects execute live
+     * and no further divergence checks are triggered.
+     */
+    disableReplay(coroutineId: CoroutineId): void;
+    /** Returns true if replay has been disabled for this coroutine. */
+    isReplayDisabled(coroutineId: CoroutineId): boolean;
+    /**
+     * Returns the next unconsumed yield for this coroutine,
+     * or undefined if the cursor is past the end or replay is disabled.
+     */
+    peekYield(coroutineId: CoroutineId): YieldEntry | undefined;
+    /** Advances the cursor for this coroutine by one position. */
+    consumeYield(coroutineId: CoroutineId): void;
+    /** Returns the current cursor position for this coroutine. */
+    getCursor(coroutineId: CoroutineId): number;
+    /** Returns true if a Close event exists for this coroutine (and replay is not disabled). */
+    hasClose(coroutineId: CoroutineId): boolean;
+    /** Returns the Close event for this coroutine, or undefined. */
+    getClose(coroutineId: CoroutineId): Close | undefined;
+    /**
+     * Returns true if any non-disabled coroutine still has unconsumed yields.
+     *
+     * This is used by durableRun to detect early-return divergence even when
+     * unconsumed entries belong to child coroutines rather than the root.
+     */
+    hasAnyUnconsumedYields(): boolean;
+    /**
+     * Return the first non-disabled coroutine with unconsumed yields.
+     *
+     * NOTE: Closed coroutines are skipped because their yields were consumed
+     * by the child's own replay path (via runDurableChild). This means
+     * orphaned children (recorded in the journal but never spawned in the
+     * current run) are not detected here. Orphan detection requires tracking
+     * which coroutine IDs were visited during the current run, which is a
+     * future enhancement.
+     */
+    firstUnconsumed(): {
+        coroutineId: CoroutineId;
+        cursor: number;
+        totalYields: number;
+    } | undefined;
+    /**
+     * Returns true if the cursor for this coroutine has been fully consumed
+     * AND a Close event exists. This means the coroutine completed in a
+     * previous run and can be treated as fully replayed.
+     *
+     * Returns false if replay is disabled (run-live mode).
+     */
+    isFullyReplayed(coroutineId: CoroutineId): boolean;
+    /** Returns the total number of yield entries for this coroutine. */
+    yieldCount(coroutineId: CoroutineId): number;
+}