@executablemd/durable-streams 0.6.0 → 0.8.0

package/types/effect.d.ts

@@ -20,6 +20,7 @@
  * See integration doc §5.1, protocol spec §4.2, §5, §6.
  */
 import type { Operation } from "effection";
+import { type LiveDurableOperationCoordinator } from "./live-coordinator.js";
 import type { DurableEffect, EffectDescription, Json, Result } from "./types.js";
 /**
  * Executor function signature for live execution (callback-based).
@@ -56,5 +57,9 @@ export declare function createDurableEffect<T>(desc: EffectDescription, execute:
  *
  * @param desc Structured description for the journal and divergence detection
  * @param execute Returns an Operation to run during live execution
+ * @param options.coordinator Selects the live execution/publication boundary;
+ * replay never invokes it
  */
-export declare function createDurableOperation<T extends Json>(desc: EffectDescription, execute: () => Operation<T>): DurableEffect<T>;
+export declare function createDurableOperation<T extends Json>(desc: EffectDescription, execute: () => Operation<T>, options?: {
+    coordinator?: LiveDurableOperationCoordinator;
+}): DurableEffect<T>;

package/types/errors.d.ts

@@ -2,6 +2,33 @@
  * Error types for the durable execution protocol.
  */
 import type { CoroutineId, EffectDescription } from "./types.js";
+/**
+ * Raised when a durable event cannot be persisted.
+ *
+ * Persistence failures are protocol failures, not workflow outcomes. The
+ * adapter error remains available as the cause, and no compensating Close is
+ * written over the unpersisted event.
+ */
+export declare class DurablePersistenceError extends Error {
+    name: string;
+    constructor(eventType: "yield" | "close", cause: unknown);
+}
+/**
+ * Raised when a persisted record does not describe a `DurableEvent`.
+ *
+ * `path` locates the offending member within the record, such as
+ * `$.result.error.message`. Members the protocol does not name appear as `*`,
+ * because a record's own member names are as much retained content as its
+ * values. Neither the path nor the message repeats anything from the record: a
+ * journal is retained, filtered history, and a parse failure is not a reason to
+ * copy its contents into an error that travels to logs and terminals.
+ */
+export declare class MalformedDurableEventError extends Error {
+    name: string;
+    /** Location of the offending member within the record. */
+    path: string;
+    constructor(reason: string, path: string);
+}
 /**
  * Raised when the replay index entry at the current cursor position
  * does not match the effect yielded by the generator. See spec §6.2.
@@ -22,14 +49,26 @@ export declare class DivergenceError extends Error {
     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.
+ * Raised when a workflow terminates while replay still has unconsumed entries.
+ * The retained journal describes effects that the current execution did not
+ * reach, so no terminal Close may be appended over that history.
  */
-export declare class EarlyReturnDivergenceError extends Error {
+export declare class TerminalDivergenceError extends Error {
     name: string;
     coroutineId: CoroutineId;
     consumedCount: number;
     totalCount: number;
+    constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number, options?: {
+        cause?: unknown;
+        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 TerminalDivergenceError {
+    name: string;
     constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number);
 }
 /**

package/types/guard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * guardDurableStream — a host-side pre-persistence boundary.
+ *
+ * A gate runs once per live append, before the event reaches the backend.
+ * It receives a copy and returns nothing, so it can inspect or reject but
+ * never rewrite. When the gate completes, the original event is handed to
+ * the underlying stream exactly once. When the gate fails or is cancelled,
+ * the backend is never invoked and the failure propagates to the durable
+ * effect that produced the event.
+ *
+ * The backend append is a statement after the gate rather than a
+ * continuation passed to it. A gate therefore has nothing it can invoke
+ * twice, which preserves the protocol invariant that one durable yield
+ * produces at most one journal event.
+ */
+import { type Operation } from "effection";
+import type { DurableStream } from "./stream.js";
+import type { DurableEvent } from "./types.js";
+declare class JournalProvenance {
+    #private;
+}
+/**
+ * A non-operational, equality-only witness that a stream descends from the
+ * exact journal backend a provider selected.
+ *
+ * It grants no append, read, execution, publication or reconciliation
+ * capability. It is meaningful only because the provider retains the witness
+ * it established and later requires exact equality.
+ */
+export type { JournalProvenance };
+/** Establish the provenance a provider retains for one exact journal backend. */
+export declare function establishJournalProvenance(stream: DurableStream): JournalProvenance;
+/**
+ * Carry an exact source stream's provenance onto a trusted wrapper of it.
+ *
+ * Preservation is visible composition rather than new authority: it transfers
+ * only the witness already associated with that exact source, so an unproven
+ * source leaves the target unproven. The target is returned so the wrapping
+ * site reads as one expression.
+ */
+export declare function preserveJournalProvenance(source: DurableStream, target: DurableStream): DurableStream;
+/** @internal The live durable path reads provenance without receiving stream authority. */
+export declare function getJournalProvenance(stream: DurableStream): JournalProvenance | undefined;
+export interface DurableEventRejectionOccurrence {
+    rejected: boolean;
+    error?: unknown;
+}
+export declare function withDurableEventRejectionOccurrence(occurrence: DurableEventRejectionOccurrence, operation: () => Operation<void>): Operation<void>;
+/**
+ * A check that runs before a durable event is persisted.
+ *
+ * Completing successfully admits the event. Failing or being cancelled
+ * rejects it. A gate inspects or rejects, and nothing else: it returns no
+ * value, and the event it receives is a copy, so writing to that copy
+ * changes nothing about what gets journaled.
+ */
+export type DurableEventGate = (event: DurableEvent) => Operation<void>;
+/**
+ * Wrap a durable stream so every live append passes through `gate` first.
+ *
+ * `readAll()` delegates straight to the underlying stream, so replaying a
+ * journal restores existing entries without gating them.
+ *
+ * Wrap the stream before execution begins to cover the complete live
+ * journal — root component imports, yields, child closes, and the root
+ * close.
+ *
+ * Rejection is per event. The rejected event never reaches the backend, but
+ * the resulting failure may lead the workflow to append a later `Close`
+ * event with an `err` result, and that close crosses the gate on its own.
+ *
+ * The guard is policy-neutral, so the wrapper it returns is unproven. An
+ * authorized wrapping site preserves journal provenance explicitly through
+ * {@link preserveJournalProvenance}.
+ */
+export declare function guardDurableStream(stream: DurableStream, gate: DurableEventGate): DurableStream;

package/types/live-coordinator.d.ts

@@ -0,0 +1,11 @@
+import type { Operation } from "effection";
+import type { JournalProvenance } from "./guard.js";
+import type { Json, Result } from "./types.js";
+/** Activates the first infrastructure failure for the enclosing durable run. */
+export type ActivateDurabilityFailure = (failure: unknown) => Error;
+/** Coordinates one live structured durable operation with its publication. */
+export interface LiveDurableOperationCoordinator {
+    run<T extends Json>(execute: () => Operation<T>, publish: (result: Result) => Operation<void>, activateFailure: ActivateDurabilityFailure, journalProvenance: JournalProvenance | undefined): Operation<Result>;
+}
+/** The ordinary live path: execute once, publish once, then return the same result. */
+export declare const defaultLiveDurableOperationCoordinator: LiveDurableOperationCoordinator;

package/types/mod.d.ts

@@ -5,23 +5,30 @@
  * Implements the two-event durable execution protocol for generator-based
  * structured concurrency, with Durable Streams as the persistence backend.
  */
+import "./_dnt.polyfills.js";
 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 { retainEvents } from "./retained.js";
 export type { YieldEntry } from "./replay-index.js";
 export type { DurableStream } from "./stream.js";
 export { InMemoryStream } from "./stream.js";
+export { guardDurableStream } from "./guard.js";
+export { establishJournalProvenance, preserveJournalProvenance } from "./guard.js";
+export type { DurableEventGate, JournalProvenance } from "./guard.js";
 export { useHttpDurableStream } from "./http-stream.js";
 export type { HttpDurableStreamHandle, HttpDurableStreamOptions } from "./http-stream.js";
-export { ContinuePastCloseDivergenceError, DivergenceError, EarlyReturnDivergenceError, StaleInputError, } from "./errors.js";
+export { ContinuePastCloseDivergenceError, DivergenceError, DurablePersistenceError, EarlyReturnDivergenceError, MalformedDurableEventError, StaleInputError, TerminalDivergenceError, } 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 type { ReplayOutcome, RetainedHistory } from "./replay-guard.js";
+export { DurableContext } from "./context.js";
+export { deserializeError, effectionToProtocol, protocolToEffection, serializeDurableEvent, serializeError, } from "./serialize.js";
+export { parseDurableEvent } from "./parse.js";
 export { createDurableEffect, createDurableOperation } from "./effect.js";
 export type { Executor } from "./effect.js";
+export { defaultLiveDurableOperationCoordinator } from "./live-coordinator.js";
+export type { ActivateDurabilityFailure, LiveDurableOperationCoordinator, } from "./live-coordinator.js";
 export { durableAction, durableCall, durableSleep, versionCheck } from "./operations.js";
 export { durableAll, durableRace, durableSpawn } from "./combinators.js";
 export { durableEach } from "./each.js";

package/types/parse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `parseDurableEvent` is the typed inverse of `serializeDurableEvent`.
+ *
+ * A backend that retains the NDJSON record — a journal file, a SQLite
+ * column — reads it back through this function. The record is parsed,
+ * never trusted: every member is checked against the protocol types and
+ * the returned event is rebuilt from the checked members, so nothing
+ * reaches replay because it merely looked plausible.
+ *
+ * The closed shapes — the event envelope, a protocol `Result`, a
+ * `SerializedError` — reject members they do not declare. An
+ * `EffectDescription` declares an index signature, so its extra members
+ * are admitted as `Json`; those are the input fields replay guards read.
+ */
+import type { DurableEvent, EffectionResult } from "./types.js";
+/**
+ * Parse one NDJSON record produced by `serializeDurableEvent`.
+ *
+ * The record's terminating newline is optional — `JSON.parse` ignores
+ * trailing whitespace — so a stored record and a line split out of a
+ * journal file both parse.
+ */
+export declare function parseDurableEvent(record: string): EffectionResult<DurableEvent>;

package/types/replay-guard.d.ts

@@ -12,14 +12,26 @@
  * (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:
+ * A guard is **composable policy, not authority**. Guards compose through
+ * `Api.around`, and a handler installed further out may decline to call `next`.
+ * That is what composition is for, and it is why an invariant that must not be
+ * negotiable — durable identity above all — belongs somewhere a caller cannot
+ * replace, such as inside the `DurableStream` a consumer hands to `durableRun`.
+ *
+ * The API has three stages:
  *
  * 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
+ * 2. **admit** (after every check, before terminal reuse): Runs once with the
+ *    retained history as a whole. A guard that requires something of the
+ *    history rather than of one event — that an event it validates is present,
+ *    and present once — refuses here, because a per-event check has nothing to
+ *    object to in a journal that omits the event. Default is a no-op.
+ *
+ * 3. **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.
@@ -31,7 +43,24 @@
  * See replay-guard-spec.md for the full design.
  */
 import type { Api, Operation } from "effection";
-import type { Yield } from "./types.js";
+import type { CoroutineId, Yield } from "./types.js";
+/**
+ * The retained history a run is about to replay, offered once.
+ *
+ * A guard's per-event check can only speak about events a journal contains. A
+ * journal missing something a guard requires offers it nothing to object to,
+ * and the recorded terminal result is then reused on the strength of history
+ * that was never validated. This is where a guard says whether the history as a
+ * whole may be replayed at all.
+ */
+export interface RetainedHistory {
+    /** The coroutine whose recorded terminal result is about to be reused. */
+    readonly coroutineId: CoroutineId;
+    /** Every retained Yield, each owning the one cell for what it settled to. */
+    readonly yields: readonly Yield[];
+    /** Whether a recorded terminal result exists for that coroutine. */
+    readonly terminal: boolean;
+}
 /**
  * The outcome of a replay guard's decision.
  *
@@ -62,6 +91,13 @@ export type ReplayOutcome = {
 interface ReplayGuardApi {
     /** Phase 1: Check — gather observations before replay (I/O allowed). */
     check(event: Yield): Operation<void>;
+    /**
+     * Phase 1b: Admit — the retained history has been offered in full, and a
+     * recorded terminal result has not been reused yet. A guard that requires
+     * something of the history as a whole — that an event it validates is
+     * present at all, and present once — refuses here by throwing.
+     */
+    admit(history: RetainedHistory): Operation<void>;
     /** Phase 2: Decide — return replay outcome (synchronous, pure). */
     decide(event: Yield): ReplayOutcome;
 }

package/types/replay-index.d.ts

@@ -4,18 +4,37 @@
  * 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";
+import type { Close, CoroutineId, DurableEvent, EffectDescription, Result, Yield } from "./types.js";
 export interface YieldEntry {
     description: EffectDescription;
     result: Result;
 }
 export declare class ReplayIndex {
     private yields;
+    /** Every retained Yield in stream order, each owning its own settled cells. */
+    private retained;
     private cursors;
     private closes;
     /** Coroutines where replay has been disabled (run-live mode). */
     private disabled;
+    /** Retained coroutine identities reached by the current definition. */
+    private claimed;
+    /**
+     * Index a journal's events by identity, without reading what they settled to.
+     *
+     * The events are retained first — idempotently, so a caller that already
+     * produced the stable history hands the same objects on rather than a second
+     * wrapping of them, and every phase then observes one identity and one
+     * settlement per event.
+     */
     constructor(events: DurableEvent[]);
+    /**
+     * Every retained Yield in stream order, as the events a check phase sees.
+     *
+     * The same objects the replay path consumes, so a guard and a later consumer
+     * observe one settled result rather than two reads of the stream.
+     */
+    retainedYields(): Yield[];
     /**
      * Disable replay for a coroutine (run-live mode).
      *
@@ -26,6 +45,8 @@ export declare class ReplayIndex {
     disableReplay(coroutineId: CoroutineId): void;
     /** Returns true if replay has been disabled for this coroutine. */
     isReplayDisabled(coroutineId: CoroutineId): boolean;
+    /** Mark a retained coroutine identity as reached by the current run. */
+    claim(coroutineId: CoroutineId): void;
     /**
      * Returns the next unconsumed yield for this coroutine,
      * or undefined if the cursor is past the end or replay is disabled.
@@ -46,17 +67,8 @@ export declare class ReplayIndex {
      * 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(): {
+    /** Return the first retained coroutine not aligned with the current subtree. */
+    firstUnaligned(subtreeId: CoroutineId): {
         coroutineId: CoroutineId;
         cursor: number;
         totalYields: number;

package/types/retained.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Retained events — what a run reads a journal as.
+ *
+ * A journal is data supplied by a backend, and every phase of a replay reads
+ * the same events: a private authority gate, the replay index, public guard
+ * policy, and the replay path itself. If those are separate reads of the
+ * backend's own objects, a source that answers differently between them decides
+ * one thing for validation and another for execution, and nothing downstream
+ * can detect the substitution.
+ *
+ * A retained event is therefore read once and detached. **Every** event that
+ * participates in admission, indexing, or terminal reuse is retained, Close as
+ * well as Yield: a Close decides whether a coroutine has a terminal result to
+ * reuse, so leaving it as the backend's own object lets it belong to a child
+ * coroutine while one phase asks and to the root while the next does.
+ *
+ * The discriminator is settled once, by the classification that chooses a
+ * retained event's kind, and never read from the source again. Identity — the
+ * coroutine an event belongs to, and a Yield's complete effect description — is
+ * settled once too, so no phase can be shown a different event than the phase
+ * before it.
+ *
+ * A Yield's *settlement* stays lazy and separate: the index is built before
+ * guards run, and a guard that would refuse an event has to get that chance
+ * before the stream is asked to produce its result. A Close keeps its own cell,
+ * memoized the same way, so every later read receives the same detached answer.
+ */
+import type { DurableEvent, Json, Result } from "./types.js";
+/**
+ * A detached copy of one retained JSON value.
+ *
+ * Every property is read once and rebuilt, so nothing the stream still owns
+ * remains reachable: a nested accessor cannot answer one thing to one phase and
+ * another to the next, and no later mutation of the source changes what replay
+ * used.
+ *
+ * The copy is ordinary JSON. Detaching is the claim against the *stream*;
+ * making the copy immutable would be a claim against the *consumer*, and
+ * replayed values are legitimately mutable — an eval binding restored from a
+ * journal is pushed to by the iteration that resumes on it. Members are
+ * therefore writable and configurable like any other JSON.
+ *
+ * Keys are defined rather than assigned all the same, because `__proto__`
+ * reaches an inherited setter on some runtimes and would rewrite the copy's
+ * prototype instead of becoming a member of it.
+ *
+ * A cycle is refused. `Json` has none, and a value that does is not something
+ * this can detach — refusing is remembered like any other refusal.
+ */
+export declare function detachJson(value: Json, seen?: Set<object>): Json;
+/**
+ * The retained form of a journal's events.
+ *
+ * Idempotent: retaining an already-retained event returns it, so a caller that
+ * has produced the stable history hands the same objects onward rather than a
+ * second wrapping of them. That is what lets one snapshot serve every phase.
+ *
+ * Only the event type is read here, which is the least a caller can read and
+ * still tell a Yield from a Close. Everything else is the retained event's own.
+ */
+export declare function retainEvents(events: readonly DurableEvent[]): DurableEvent[];
+/**
+ * An isolated observation of a retained event, for public policy to read.
+ *
+ * A replay guard is composable policy, and composition means handlers read,
+ * annotate, and pass along. What it must never mean is that a handler edits the
+ * history the execution already validated: the authoritative graph is what
+ * admission accepted and what replay consumes, and a guard that could rewrite a
+ * root selection or an effect description after admission would hold exactly
+ * the authority the private gate exists to keep out of public hands.
+ *
+ * So policy reads a copy. It is deep and mutable, so middleware may compose over
+ * it as freely as it likes, and nothing it does reaches replay.
+ */
+export declare function observeEvent(event: DurableEvent): DurableEvent;
+/**
+ * A retained result as a consumer may hold it: ordinary mutable JSON.
+ *
+ * The authoritative copy is frozen so policy cannot rewrite it. A document
+ * that resumes on a restored binding writes to it, so what a workflow receives
+ * is a fresh copy taken from that authority rather than the authority itself.
+ */
+export declare function consumable(result: Result): Result;

package/types/run.d.ts

@@ -32,7 +32,8 @@ export interface DurableRunOptions {
  * 3. Runs the workflow — replayed effects resolve synchronously from
  *    the index; live effects execute and persist before resuming.
  * 4. On completion, appends a Close event to the stream.
- * 5. On error, appends a Close(err) event.
+ * 5. Before any Close, rejects durability failures and retained coroutine
+ *    history the current definition did not align with.
  *
  * Returns the workflow's result value.
  *

package/types/serialize.d.ts

@@ -5,8 +5,29 @@
  * - Protocol Result ({ status: "ok" | "err" | "cancelled" })
  * - Effection Result ({ ok: true, value } | { ok: false, error })
  * - Error ↔ SerializedError
+ *
+ * `serializeDurableEvent` is the shared NDJSON representation: file
+ * persistence writes it, and gates that inspect the persisted form derive
+ * it from the same function.
+ */
+import type { DurableEvent, EffectionResult, Result, SerializedError } from "./types.js";
+/**
+ * Render one durable event as its NDJSON record, terminating newline
+ * included.
+ *
+ * This is ordinary `JSON.stringify(event) + "\n"`. Field order follows the
+ * event object's own insertion order; nothing is sorted, normalized, or
+ * otherwise canonicalized. The value of sharing it is that file persistence
+ * and anything inspecting the persisted form cannot drift apart, not that
+ * the output is a canonical form of the event.
+ *
+ * Serialization fails when `JSON.stringify` throws — a circular structure or
+ * a `BigInt` — or when it does not return a string. Values that
+ * `JSON.stringify` silently coerces or drops are left alone: `undefined`,
+ * function and symbol members are omitted, non-finite numbers become `null`,
+ * and non-plain objects serialize through `toJSON`.
  */
-import type { EffectionResult, Result, SerializedError } from "./types.js";
+export declare function serializeDurableEvent(event: DurableEvent): string;
 /** Serialize an Error to a JSON-safe SerializedError. */
 export declare function serializeError(error: Error): SerializedError;
 /** Deserialize a SerializedError back to an Error. */