@executablemd/testing 0.3.1 → 0.4.0

package/esm/durable-streams/operations.js

@@ -1,88 +0,0 @@
-/**
- * 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 { call } from "effection";
-import { createDurableEffect, createDurableOperation } from "./effect.ts";
-/**
- * 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 function* durableSleep(ms) {
-    yield createDurableEffect({ type: "sleep", name: "sleep" }, (resolve) => {
-        const id = setTimeout(() => resolve({ status: "ok" }), ms);
-        return () => clearTimeout(id);
-    });
-}
-/**
- * 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 function* durableCall(name, fn) {
-    // call() dispatches at runtime: if fn() returns a Promise, it bridges
-    // via action(); if it returns an Operation, it evaluates directly.
-    // The cast is safe because call() always resolves to T regardless of
-    // which branch fn() takes.
-    return (yield createDurableOperation({ type: "call", name }, () => call(fn)));
-}
-/**
- * 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 function* durableAction(name, executor) {
-    return (yield createDurableEffect({ type: "action", name }, (protocolResolve, reject) => {
-        return executor((value) => protocolResolve({ status: "ok", value: value }), reject);
-    }));
-}
-/**
- * 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 function* versionCheck(name, opts) {
-    if (opts.minVersion > opts.maxVersion) {
-        throw new Error(`versionCheck("${name}"): minVersion (${opts.minVersion}) ` +
-            `cannot exceed maxVersion (${opts.maxVersion})`);
-    }
-    const version = (yield createDurableEffect({ type: "version_gate", name }, (resolve) => {
-        resolve({ status: "ok", value: opts.maxVersion });
-        return () => { };
-    }));
-    if (version < opts.minVersion || version > opts.maxVersion) {
-        throw new Error(`versionCheck("${name}"): replayed version ${version} is outside ` +
-            `supported range [${opts.minVersion}, ${opts.maxVersion}]`);
-    }
-    return version;
-}

package/esm/durable-streams/replay-guard.js

@@ -1,87 +0,0 @@
-/**
- * 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 { createApi } from "effection/experimental";
-// ---------------------------------------------------------------------------
-// Default implementation (pass-through)
-// ---------------------------------------------------------------------------
-/**
- * Default check — no-op. Events pass through without observation.
- */
-function* defaultCheck(_event) {
-    // No observation — pass through to next middleware or default.
-}
-/**
- * Default decide — always replay. This preserves "logs are authoritative"
- * as the default behavior. Guards must be explicitly installed to add
- * validation.
- */
-function defaultDecide(_event) {
-    return { outcome: "replay" };
-}
-// ---------------------------------------------------------------------------
-// The ReplayGuard API instance
-// ---------------------------------------------------------------------------
-/**
- * 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 const ReplayGuard = createApi("DurableEffection.ReplayGuard", { check: defaultCheck, decide: defaultDecide });

package/esm/durable-streams/replay-index.js

@@ -1,132 +0,0 @@
-/**
- * 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.
- */
-export class ReplayIndex {
-    yields = new Map();
-    cursors = new Map();
-    closes = new Map();
-    /** Coroutines where replay has been disabled (run-live mode). */
-    disabled = new Set();
-    constructor(events) {
-        for (const event of events) {
-            if (event.type === "yield") {
-                let list = this.yields.get(event.coroutineId);
-                if (!list) {
-                    list = [];
-                    this.yields.set(event.coroutineId, list);
-                }
-                list.push({
-                    description: event.description,
-                    result: event.result,
-                });
-            }
-            if (event.type === "close") {
-                this.closes.set(event.coroutineId, event);
-            }
-        }
-    }
-    /**
-     * 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) {
-        this.disabled.add(coroutineId);
-    }
-    /** Returns true if replay has been disabled for this coroutine. */
-    isReplayDisabled(coroutineId) {
-        return this.disabled.has(coroutineId);
-    }
-    /**
-     * Returns the next unconsumed yield for this coroutine,
-     * or undefined if the cursor is past the end or replay is disabled.
-     */
-    peekYield(coroutineId) {
-        if (this.disabled.has(coroutineId))
-            return undefined;
-        const list = this.yields.get(coroutineId);
-        const cursor = this.cursors.get(coroutineId) ?? 0;
-        return list?.[cursor];
-    }
-    /** Advances the cursor for this coroutine by one position. */
-    consumeYield(coroutineId) {
-        const cursor = this.cursors.get(coroutineId) ?? 0;
-        this.cursors.set(coroutineId, cursor + 1);
-    }
-    /** Returns the current cursor position for this coroutine. */
-    getCursor(coroutineId) {
-        return this.cursors.get(coroutineId) ?? 0;
-    }
-    /** Returns true if a Close event exists for this coroutine (and replay is not disabled). */
-    hasClose(coroutineId) {
-        if (this.disabled.has(coroutineId))
-            return false;
-        return this.closes.has(coroutineId);
-    }
-    /** Returns the Close event for this coroutine, or undefined. */
-    getClose(coroutineId) {
-        if (this.disabled.has(coroutineId))
-            return undefined;
-        return this.closes.get(coroutineId);
-    }
-    /**
-     * 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() {
-        for (const [coroutineId, entries] of this.yields.entries()) {
-            if (this.disabled.has(coroutineId))
-                continue;
-            const cursor = this.cursors.get(coroutineId) ?? 0;
-            if (cursor < entries.length)
-                return true;
-        }
-        return false;
-    }
-    /**
-     * 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() {
-        for (const [coroutineId, entries] of this.yields.entries()) {
-            if (this.disabled.has(coroutineId))
-                continue;
-            if (this.closes.has(coroutineId))
-                continue;
-            const cursor = this.cursors.get(coroutineId) ?? 0;
-            if (cursor < entries.length) {
-                return { coroutineId, cursor, totalYields: entries.length };
-            }
-        }
-        return 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) {
-        if (this.disabled.has(coroutineId))
-            return false;
-        return this.peekYield(coroutineId) === undefined && this.hasClose(coroutineId);
-    }
-    /** Returns the total number of yield entries for this coroutine. */
-    yieldCount(coroutineId) {
-        return this.yields.get(coroutineId)?.length ?? 0;
-    }
-}

package/esm/durable-streams/run.js

@@ -1,137 +0,0 @@
-/**
- * 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 { useScope } from "effection";
-import { DurableCtx } from "./context.ts";
-import { EarlyReturnDivergenceError } from "./errors.ts";
-import { ReplayGuard } from "./replay-guard.ts";
-import { ReplayIndex } from "./replay-index.ts";
-import { deserializeError, serializeError } from "./serialize.ts";
-/**
- * Run the ReplayGuard check phase over all Yield events.
- *
- * This is Phase 1 of replay guard validation — it runs before the workflow
- * starts, in generator context where I/O is allowed. Middleware uses this
- * phase to gather observations (hash files, check timestamps) and cache
- * results for the decide phase.
- *
- * See replay-guard-spec.md §5.5.
- */
-function* runCheckPhase(events, scope) {
-    for (const event of events) {
-        if (event.type === "yield") {
-            yield* ReplayGuard.invoke(scope, "check", [event]);
-        }
-    }
-}
-/**
- * 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 function* durableRun(workflow, options) {
-    const { stream, coroutineId = "root" } = options;
-    // Read all events and build replay index
-    const events = yield* stream.readAll();
-    const replayIndex = new ReplayIndex(events);
-    // Inherit the caller's scope — middleware (e.g., Divergence, ReplayGuard)
-    // is already installed by the caller before yield*-ing into durableRun.
-    const scope = yield* useScope();
-    scope.set(DurableCtx, {
-        replayIndex,
-        stream,
-        coroutineId,
-        childCounter: 0,
-    });
-    // ── REPLAY GUARD: Check phase ──
-    // Run before the workflow starts. Middleware can yield* for I/O (hash
-    // files, make network requests) to gather observations for the decide
-    // phase. The check loop iterates all Yield events in journal order.
-    // See replay-guard-spec.md §5.5.
-    yield* runCheckPhase(events, scope);
-    // If the root coroutine already has a Close event in the journal,
-    // the workflow completed in a previous run. Return the stored result
-    // directly without re-running the workflow.
-    if (replayIndex.hasClose(coroutineId)) {
-        const closeEvent = replayIndex.getClose(coroutineId);
-        if (closeEvent.result.status === "ok") {
-            return closeEvent.result.value;
-        }
-        else if (closeEvent.result.status === "err") {
-            throw deserializeError(closeEvent.result.error);
-        }
-        else {
-            throw new Error("Workflow was cancelled");
-        }
-    }
-    try {
-        // Workflow<T> is structurally assignable to Operation<T>, so
-        // yield* accepts it directly — no cast needed.
-        const result = yield* workflow();
-        // §6.3: Check for early return divergence.
-        // If the generator returned but the replay index has unconsumed yields,
-        // the workflow has diverged. Skip this check when replay has been
-        // disabled (run-live mode) — the workflow intentionally diverged and
-        // the Divergence API already approved it.
-        if (!replayIndex.isReplayDisabled(coroutineId)) {
-            const unconsumed = replayIndex.firstUnconsumed();
-            if (unconsumed) {
-                throw new EarlyReturnDivergenceError(unconsumed.coroutineId, unconsumed.cursor, unconsumed.totalYields);
-            }
-        }
-        const closeEvent = {
-            type: "close",
-            coroutineId,
-            result: { status: "ok", value: result },
-        };
-        yield* stream.append(closeEvent);
-        return result;
-    }
-    catch (error) {
-        // Normalize the error once — use the same Error object for both the
-        // Close event and the rethrow so that live runs and replayed Close
-        // events carry identical error shapes.
-        const primary = error instanceof Error ? error : new Error(String(error));
-        const closeEvent = {
-            type: "close",
-            coroutineId,
-            result: {
-                status: "err",
-                error: serializeError(primary),
-            },
-        };
-        try {
-            yield* stream.append(closeEvent);
-        }
-        catch (appendError) {
-            const appendFailure = appendError instanceof Error ? appendError : new Error(String(appendError));
-            throw new AggregateError([primary, appendFailure], "Workflow failed and Close append also failed");
-        }
-        throw primary;
-    }
-}

package/esm/durable-streams/serialize.js

@@ -1,65 +0,0 @@
-/**
- * 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
- */
-// ---------------------------------------------------------------------------
-// Error serialization
-// ---------------------------------------------------------------------------
-/** Serialize an Error to a JSON-safe SerializedError. */
-export function serializeError(error) {
-    return {
-        message: error.message,
-        name: error.name,
-        stack: error.stack,
-    };
-}
-/** Deserialize a SerializedError back to an Error. */
-export function deserializeError(se) {
-    const error = new Error(se.message);
-    if (se.name)
-        error.name = se.name;
-    if (se.stack)
-        error.stack = se.stack;
-    return error;
-}
-// ---------------------------------------------------------------------------
-// Result conversion: Protocol ↔ Effection
-// ---------------------------------------------------------------------------
-/**
- * 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 function protocolToEffection(result) {
-    switch (result.status) {
-        case "ok":
-            return { ok: true, value: result.value };
-        case "err":
-            return { ok: false, error: deserializeError(result.error) };
-        case "cancelled":
-            return { ok: false, error: new Error("cancelled") };
-    }
-}
-/**
- * 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 function effectionToProtocol(result) {
-    if (result.ok) {
-        return { status: "ok", value: result.value };
-    }
-    else {
-        return { status: "err", error: serializeError(result.error) };
-    }
-}

package/esm/durable-streams/stream.js

@@ -1,56 +0,0 @@
-/**
- * DurableStream interface and in-memory implementation.
- *
- * The interface is intentionally abstract — protocol-specification.md §11
- * does not prescribe a physical encoding or transport.
- */
-function cloneEvent(event) {
-    return structuredClone(event);
-}
-function cloneEvents(events) {
-    return events.map(cloneEvent);
-}
-/**
- * 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 class InMemoryStream {
-    events = [];
-    /** Count of append calls, useful for verifying replay doesn't re-execute. */
-    appendCount = 0;
-    /** If set, append() will reject with this error. */
-    injectFailure = null;
-    /** Optional callback invoked on each append, before persistence. */
-    onAppend = null;
-    constructor(initialEvents = []) {
-        this.events = cloneEvents(initialEvents);
-    }
-    // deno-lint-ignore require-yield
-    *readAll() {
-        return cloneEvents(this.events);
-    }
-    // deno-lint-ignore require-yield
-    *append(event) {
-        if (this.injectFailure) {
-            throw this.injectFailure;
-        }
-        const cloned = cloneEvent(event);
-        this.onAppend?.(cloneEvent(cloned));
-        this.events.push(cloned);
-        this.appendCount++;
-    }
-    /** Get a snapshot of current events (for test assertions). */
-    snapshot() {
-        return cloneEvents(this.events);
-    }
-    /** Reset the stream (for test setup). */
-    reset(events = []) {
-        this.events = cloneEvents(events);
-        this.appendCount = 0;
-        this.injectFailure = null;
-        this.onAppend = null;
-    }
-}

package/esm/durable-streams/types.js

@@ -1,10 +0,0 @@
-/**
- * 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.
- */
-export {};