@executablemd/durable-streams 0.2.0

package/types/run.d.ts

@@ -0,0 +1,46 @@
+/**
+ * durableRun — entry point for durable workflow execution.
+ *
+ * An Operation<T> that reads the event stream, builds the ReplayIndex,
+ * sets DurableContext on the current scope, runs the workflow, and emits
+ * a Close event when the workflow terminates.
+ *
+ * Because durableRun is an Operation, it inherits the caller's Effection
+ * scope — including any middleware installed via Api.around(). This is
+ * how divergence policy overrides work: the caller installs middleware
+ * before yield*-ing into durableRun. See DEC-032.
+ *
+ * See integration doc §10, protocol spec §4.
+ */
+import type { Operation } from "effection";
+import type { DurableStream } from "./stream.js";
+import type { Workflow, WorkflowValue } from "./types.js";
+/**
+ * Options for durableRun.
+ */
+export interface DurableRunOptions {
+    /** The durable stream to read from and append to. */
+    stream: DurableStream;
+    /** Coroutine ID for the root workflow. Defaults to "root". */
+    coroutineId?: string;
+}
+/**
+ * Execute a durable workflow.
+ *
+ * 1. Reads all events from the stream and builds a ReplayIndex.
+ * 2. Sets DurableContext on the current scope (inherited from caller).
+ * 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.
+ *
+ * Returns the workflow's result value.
+ *
+ * Usage:
+ *   // From async code (standalone):
+ *   await run(() => durableRun(workflow, { stream }));
+ *
+ *   // From inside an Effection generator (inherits scope):
+ *   const result = yield* durableRun(workflow, { stream });
+ */
+export declare function durableRun<T extends WorkflowValue>(workflow: () => Workflow<T> | Operation<T>, options: DurableRunOptions): Operation<T>;

package/types/serialize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Serialization utilities for the durable execution protocol.
+ *
+ * Converts between:
+ * - Protocol Result ({ status: "ok" | "err" | "cancelled" })
+ * - Effection Result ({ ok: true, value } | { ok: false, error })
+ * - Error ↔ SerializedError
+ */
+import type { EffectionResult, Result, SerializedError } from "./types.js";
+/** Serialize an Error to a JSON-safe SerializedError. */
+export declare function serializeError(error: Error): SerializedError;
+/** Deserialize a SerializedError back to an Error. */
+export declare function deserializeError(se: SerializedError): Error;
+/**
+ * Convert a protocol Result to an Effection Result.
+ *
+ * - ok → { ok: true, value }
+ * - err → { ok: false, error } (deserialized)
+ * - cancelled → { ok: false, error } with a CancelledError
+ *
+ * The value is returned as-is (Json). The caller is responsible for any
+ * narrowing to a specific type T.
+ */
+export declare function protocolToEffection<T>(result: Result): EffectionResult<T>;
+/**
+ * Convert an Effection Result to a protocol Result.
+ *
+ * The value must be JSON-serializable. This function does NOT validate
+ * serializability — that is the caller's responsibility.
+ */
+export declare function effectionToProtocol<T>(result: EffectionResult<T>): Result;

package/types/stream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DurableStream interface and in-memory implementation.
+ *
+ * The interface is intentionally abstract — protocol-specification.md §11
+ * does not prescribe a physical encoding or transport.
+ */
+import type { Operation } from "effection";
+import type { DurableEvent } from "./types.js";
+/**
+ * Abstract interface for the append-only durable event stream.
+ *
+ * Implementations must guarantee:
+ * - Append-only (events are never updated or deleted)
+ * - Prefix-closed (no gaps)
+ * - Monotonic append order (backend-specific offsets may be opaque)
+ * - Durability (once append resolves, the event persists)
+ */
+export interface DurableStream {
+    /** Read all events in the stream, in append order. */
+    readAll(): Operation<DurableEvent[]>;
+    /**
+     * Append an event to the stream.
+     * The returned operation completes only after the event is durably persisted.
+     */
+    append(event: DurableEvent): Operation<void>;
+}
+/**
+ * In-memory DurableStream implementation for testing.
+ *
+ * Provides optional hooks for:
+ * - Tracking append calls (to verify no re-execution during replay)
+ * - Injecting failures (for persist-before-resume testing)
+ */
+export declare class InMemoryStream implements DurableStream {
+    private events;
+    /** Count of append calls, useful for verifying replay doesn't re-execute. */
+    appendCount: number;
+    /** If set, append() will reject with this error. */
+    injectFailure: Error | null;
+    /** Optional callback invoked on each append, before persistence. */
+    onAppend: ((event: DurableEvent) => void) | null;
+    constructor(initialEvents?: DurableEvent[]);
+    readAll(): Operation<DurableEvent[]>;
+    append(event: DurableEvent): Operation<void>;
+    /** Get a snapshot of current events (for test assertions). */
+    snapshot(): DurableEvent[];
+    /** Reset the stream (for test setup). */
+    reset(events?: DurableEvent[]): void;
+}

package/types/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Protocol types for the two-event durable execution protocol.
+ *
+ * Protocol types (Json, Result, DurableEvent, etc.) are the fixed contract
+ * defined by protocol-specification.md and do not depend on Effection.
+ *
+ * Effection integration types (CoroutineView, DurableEffect, Workflow) are
+ * in the second section and bridge the protocol with Effection's runtime.
+ */
+import type { Result as EffectionResult, Resolve, Scope } from "effection";
+/** Any JSON-serializable value. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export type WorkflowValue = Json | void;
+/** Serialized error for durable storage. */
+export interface SerializedError {
+    message: string;
+    name?: string;
+    stack?: string;
+}
+/** Result of an effect or coroutine. */
+export type Result = {
+    status: "ok";
+    value?: Json;
+} | {
+    status: "err";
+    error: SerializedError;
+} | {
+    status: "cancelled";
+};
+/** Dot-delimited hierarchical coroutine path. See spec §3. */
+export type CoroutineId = string;
+/**
+ * Structured effect identity for divergence detection.
+ * See spec §6 for matching rules.
+ *
+ * Only `type` and `name` are compared during divergence detection.
+ * Extra fields beyond `type` and `name` are stored verbatim in the
+ * journal but never compared. They exist for runtime use (e.g.,
+ * replay guards reading input parameters like file paths).
+ */
+export interface EffectDescription {
+    /** Effect category. E.g., "call", "sleep", "action", "spawn", "resource". */
+    type: string;
+    /** Stable name within the category. E.g., function name, resource label. */
+    name: string;
+    /** Extra fields stored verbatim, never compared during divergence detection. */
+    [key: string]: Json;
+}
+/**
+ * A Yield event — an effect was executed and resolved.
+ * Written after an effect resolves. Records both what was requested
+ * (description) and what the outcome was (result). See spec §2.1.
+ *
+ * Replay guards access `description.*` for input fields (e.g., file path)
+ * and `result.value.*` for output fields (e.g., content hash). There is
+ * no separate metadata field — inputs belong in the effect description,
+ * outputs belong in the result.
+ */
+export interface Yield {
+    type: "yield";
+    coroutineId: CoroutineId;
+    description: EffectDescription;
+    result: Result;
+}
+/**
+ * A Close event — a coroutine reached a terminal state.
+ * Written when a coroutine terminates (completed, failed, or cancelled).
+ * See spec §2.2.
+ */
+export interface Close {
+    type: "close";
+    coroutineId: CoroutineId;
+    result: Result;
+}
+/** The two event types that make up the durable stream. */
+export type DurableEvent = Yield | Close;
+/**
+ * Effection's internal Result type, re-exported under a distinct name to
+ * avoid collision with the protocol's Result type.
+ *
+ * Effection uses { ok: true, value: T } | { ok: false, error: Error }.
+ * The protocol uses { status: "ok" | "err" | "cancelled" }.
+ */
+export type { EffectionResult, Resolve };
+/**
+ * View of Effection's Coroutine — the fields we need from enter().
+ *
+ * The full Coroutine type is internal to Effection (@ignore), but
+ * enter() receives it. We need `scope` to read DurableContext and
+ * to invoke the Divergence API via Api.invoke(scope, ...).
+ */
+export interface CoroutineView {
+    scope: Scope;
+}
+/**
+ * A DurableEffect extends Effection's Effect interface with a structured
+ * `effectDescription` for divergence detection and replay.
+ *
+ * The `enter()` signature matches Effection's Effect<T> exactly:
+ *   enter(resolve: Resolve<Result<T>>, routine: Coroutine):
+ *     (resolve: Resolve<Result<void>>) => void
+ *
+ * DurableEffect<T> is structurally assignable to Effect<T> because it has
+ * the same shape plus the extra `effectDescription` field. We use
+ * CoroutineView (a narrower type than Coroutine) so that contravariance
+ * keeps the assignment valid while documenting our minimal dependency.
+ */
+export interface DurableEffect<T> {
+    /** Human-readable description (for Effection's Effect interface). */
+    description: string;
+    /** Structured description for divergence detection (spec §6). */
+    effectDescription: EffectDescription;
+    /** Enter the effect — handles replay/live dispatch internally. */
+    enter(resolve: Resolve<EffectionResult<T>>, routine: CoroutineView): (resolve: Resolve<EffectionResult<void>>) => void;
+}
+/**
+ * A Workflow is a generator that only yields DurableEffect values.
+ *
+ * Every Workflow is structurally compatible with Operation<T> because
+ * DurableEffect<unknown> extends Effect<unknown> (it has all required fields).
+ * TypeScript's covariant yield type means Generator<DurableEffect, T, unknown>
+ * is assignable to Iterator<Effect, T, unknown>.
+ *
+ * Uses Generator (not Iterable) so TypeScript enforces the yield type
+ * at compile time — yielding a plain Effect inside a Workflow generator
+ * is a type error.
+ */
+export type Workflow<T> = Generator<DurableEffect<unknown>, T, unknown>;