@executablemd/durable-streams 0.6.0 → 0.8.0

package/esm/_dnt.polyfills.js

@@ -0,0 +1 @@
+export {};

package/esm/combinators.js

@@ -18,8 +18,10 @@
  * See protocol spec §7 (structured concurrency), §10 (race semantics).
  */
 import { all as effectionAll, ensure, race as effectionRace, spawn, suspend, useScope, } from "effection";
-import { DurableCtx } from "./context.js";
+import { DurableContext } from "./context.js";
+import { activeDurabilityFailure, appendDurableEvent, rememberDurabilityFailure, } from "./durability.js";
 import { ephemeral } from "./ephemeral.js";
+import { EarlyReturnDivergenceError, TerminalDivergenceError } from "./errors.js";
 import { deserializeError, serializeError } from "./serialize.js";
 /**
  * Run a child workflow within a spawned scope, setting up its own
@@ -29,7 +31,7 @@ import { deserializeError, serializeError } from "./serialize.js";
  *
  * It:
  *  1. Checks if the child already completed (has Close event) — short-circuits
- *  2. Sets DurableCtx on the child's scope with the child's coroutineId
+ *  2. Sets DurableContext on the child's scope with the child's coroutineId
  *  3. Runs the child workflow (its DurableEffects use the child's coroutineId)
  *  4. Appends Close(ok|err) when the child terminates
  *
@@ -38,6 +40,7 @@ import { deserializeError, serializeError } from "./serialize.js";
  */
 function* runDurableChild(childWorkflow, childId, parentCtx) {
     const { replayIndex, stream } = parentCtx;
+    replayIndex.claim(childId);
     // Short-circuit: child already completed in a previous run.
     // NOTE: Replay guard validation is not bypassed here — the check phase
     // (runCheckPhase in durableRun) already iterated ALL Yield events
@@ -72,17 +75,32 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
     }
     // Set child's DurableContext on this scope
     const scope = yield* useScope();
-    scope.set(DurableCtx, {
+    parentCtx.durability ??= {};
+    const childCtx = {
         replayIndex,
         stream,
         coroutineId: childId,
         childCounter: 0,
-    });
+        durability: parentCtx.durability,
+    };
+    scope.set(DurableContext, childCtx);
     let closeEvent;
+    let suppressClose = false;
     yield* ensure(function* () {
+        if (suppressClose || activeDurabilityFailure(childCtx)) {
+            return;
+        }
         // closeEvent still undefined means the child was cancelled before the
         // normal-return or catch path ran.
         if (!closeEvent) {
+            const unaligned = replayIndex.firstUnaligned(childId);
+            if (unaligned) {
+                const failure = new TerminalDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, {
+                    message: `Divergence: coroutine ${childId} was cancelled before retained history was exhausted`,
+                });
+                rememberDurabilityFailure(childCtx, failure);
+                throw failure;
+            }
             closeEvent = {
                 type: "close",
                 coroutineId: childId,
@@ -92,13 +110,25 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
         // Don't re-emit a Close event if one already exists in the journal
         // (e.g., a cancelled child being replayed via suspend()).
         if (!replayIndex.hasClose(childId)) {
-            yield* stream.append(closeEvent);
+            yield* appendDurableEvent(childCtx, closeEvent);
         }
     });
     try {
         // Run the child workflow. DurableEffects inside the child read
-        // DurableCtx from the scope, so they'll use childId.
+        // DurableContext from the scope, so they'll use childId.
         const result = yield* childWorkflow();
+        const durabilityFailure = activeDurabilityFailure(childCtx);
+        if (durabilityFailure) {
+            suppressClose = true;
+            throw durabilityFailure;
+        }
+        const unaligned = replayIndex.firstUnaligned(childId);
+        if (unaligned) {
+            suppressClose = true;
+            const failure = new EarlyReturnDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields);
+            rememberDurabilityFailure(childCtx, failure);
+            throw failure;
+        }
         closeEvent = {
             type: "close",
             coroutineId: childId,
@@ -107,15 +137,28 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
         return result;
     }
     catch (error) {
+        const primary = error instanceof Error ? error : new Error(String(error));
+        const durabilityFailure = activeDurabilityFailure(childCtx, primary);
+        if (durabilityFailure) {
+            suppressClose = true;
+            throw durabilityFailure;
+        }
+        const unaligned = replayIndex.firstUnaligned(childId);
+        if (unaligned) {
+            suppressClose = true;
+            const failure = new TerminalDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, { cause: primary });
+            rememberDurabilityFailure(childCtx, failure);
+            throw failure;
+        }
         closeEvent = {
             type: "close",
             coroutineId: childId,
             result: {
                 status: "err",
-                error: serializeError(error instanceof Error ? error : new Error(String(error))),
+                error: serializeError(primary),
             },
         };
-        throw error;
+        throw primary;
     }
 }
 /**
@@ -133,7 +176,7 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
 export function durableSpawn(childWorkflow) {
     return ephemeral((function* () {
         const scope = yield* useScope();
-        const ctx = scope.expect(DurableCtx);
+        const ctx = scope.expect(DurableContext);
         // Assign deterministic child ID
         const childIndex = ctx.childCounter++;
         const childId = `${ctx.coroutineId}.${childIndex}`;
@@ -158,7 +201,7 @@ export function durableSpawn(childWorkflow) {
 export function durableAll(workflows) {
     return ephemeral((function* () {
         const scope = yield* useScope();
-        const ctx = scope.expect(DurableCtx);
+        const ctx = scope.expect(DurableContext);
         // Build child Operations, one per workflow. Each gets its own
         // deterministic coroutineId and Close event handling.
         const childOps = workflows.map((workflow) => {
@@ -197,7 +240,7 @@ export function durableAll(workflows) {
 export function durableRace(workflows) {
     return ephemeral((function* () {
         const scope = yield* useScope();
-        const ctx = scope.expect(DurableCtx);
+        const ctx = scope.expect(DurableContext);
         // Build Operations for each child — each gets its own coroutineId
         // and Close event handling via runDurableChild.
         const childOps = workflows.map((workflow) => {

package/esm/context.js

@@ -10,4 +10,4 @@ import { createContext } from "effection";
  * Effection Context for durable execution state.
  * Set on the root scope by durableRun(); inherited by child scopes.
  */
-export const DurableCtx = createContext("@effection/durable");
+export const DurableContext = createContext("@effection/durable");

package/esm/durability.js

@@ -0,0 +1,118 @@
+import { ensure, resource, withResolvers } from "effection";
+import { ContinuePastCloseDivergenceError, DivergenceError, DurablePersistenceError, StaleInputError, TerminalDivergenceError, } from "./errors.js";
+import { withDurableEventRejectionOccurrence, } from "./guard.js";
+function createAppendFence() {
+    let held = false;
+    const waiting = [];
+    function release() {
+        const next = waiting.shift();
+        if (next === undefined) {
+            held = false;
+            return;
+        }
+        next.granted = true;
+        next.gate.resolve();
+    }
+    return {
+        hold: () => resource(function* (provide) {
+            const turn = { gate: withResolvers(), granted: false };
+            yield* ensure(() => {
+                if (turn.granted) {
+                    release();
+                    return;
+                }
+                const index = waiting.indexOf(turn);
+                if (index >= 0) {
+                    waiting.splice(index, 1);
+                }
+            });
+            if (held) {
+                waiting.push(turn);
+                yield* turn.gate.operation;
+            }
+            else {
+                held = true;
+                turn.granted = true;
+            }
+            yield* provide();
+        }),
+    };
+}
+function durabilityState(ctx) {
+    ctx.durability ??= {};
+    return ctx.durability;
+}
+function appendFence(ctx) {
+    const state = durabilityState(ctx);
+    state.appendFence ??= createAppendFence();
+    return state.appendFence;
+}
+export function findDurabilityFailure(error) {
+    const visited = new Set();
+    const pending = [error];
+    while (pending.length > 0) {
+        const current = pending.shift();
+        if (visited.has(current)) {
+            continue;
+        }
+        visited.add(current);
+        if (current instanceof DurablePersistenceError ||
+            current instanceof StaleInputError ||
+            current instanceof DivergenceError ||
+            current instanceof TerminalDivergenceError ||
+            current instanceof ContinuePastCloseDivergenceError) {
+            return current;
+        }
+        if (current instanceof AggregateError) {
+            pending.push(...current.errors);
+        }
+        if (current instanceof Error && current.cause !== undefined) {
+            pending.push(current.cause);
+        }
+    }
+    return undefined;
+}
+export function rememberDurabilityFailure(ctx, error) {
+    const state = durabilityState(ctx);
+    state.failure ??= error;
+    return state.failure;
+}
+export function activeDurabilityFailure(ctx, error) {
+    if (ctx.durability?.failure) {
+        return ctx.durability.failure;
+    }
+    const failure = findDurabilityFailure(error);
+    if (failure) {
+        return rememberDurabilityFailure(ctx, failure);
+    }
+    return undefined;
+}
+export function* appendDurableEvent(ctx, event) {
+    const existing = activeDurabilityFailure(ctx);
+    if (existing) {
+        throw existing;
+    }
+    yield* appendFence(ctx).hold();
+    const admitted = activeDurabilityFailure(ctx);
+    if (admitted) {
+        throw admitted;
+    }
+    const occurrence = { rejected: false };
+    try {
+        yield* withDurableEventRejectionOccurrence(occurrence, () => ctx.stream.append(event));
+    }
+    catch (error) {
+        if (occurrence.rejected && Object.is(error, occurrence.error)) {
+            const failure = activeDurabilityFailure(ctx);
+            if (failure) {
+                throw failure;
+            }
+            throw error;
+        }
+        const active = activeDurabilityFailure(ctx);
+        if (active) {
+            throw active;
+        }
+        throw rememberDurabilityFailure(ctx, new DurablePersistenceError(event.type, error));
+    }
+}

package/esm/effect.js

@@ -19,10 +19,14 @@
  *
  * See integration doc §5.1, protocol spec §4.2, §5, §6.
  */
-import { DurableCtx } from "./context.js";
+import { DurableContext } from "./context.js";
 import { Divergence } from "./divergence.js";
+import { activeDurabilityFailure, appendDurableEvent, rememberDurabilityFailure, } from "./durability.js";
 import { StaleInputError } from "./errors.js";
+import { getJournalProvenance } from "./guard.js";
+import { defaultLiveDurableOperationCoordinator, } from "./live-coordinator.js";
 import { ReplayGuard } from "./replay-guard.js";
+import { consumable, observeEvent } from "./retained.js";
 import { protocolToEffection, serializeError } from "./serialize.js";
 /** Effection void-ok result, used for no-op teardowns. */
 const VOID_OK = {
@@ -64,6 +68,7 @@ function checkReplay(desc, resolve, routine, ctx) {
                     },
                 ]);
                 if (decision.type === "throw") {
+                    rememberDurabilityFailure(ctx, decision.error);
                     resolve({ ok: false, error: decision.error });
                     return { path: "replayed", teardown: (exit) => exit(VOID_OK) };
                 }
@@ -73,12 +78,23 @@ function checkReplay(desc, resolve, routine, ctx) {
             }
             // Description matches — now check replay guards before replaying.
             // ── REPLAY GUARD: Decide phase ──
-            const yieldEvent = {
+            // An isolated observation, like the check and admit phases: a decision is
+            // policy, and policy reads. Handing the retained description or result
+            // here would let a guard rewrite what replay is about to consume.
+            const observed = observeEvent({
                 type: "yield",
                 coroutineId: ctx.coroutineId,
                 description: entry.description,
                 result: entry.result,
-            };
+            });
+            const yieldEvent = observed.type === "yield"
+                ? observed
+                : {
+                    type: "yield",
+                    coroutineId: ctx.coroutineId,
+                    description: desc,
+                    result: entry.result,
+                };
             const outcome = ReplayGuard.invoke(routine.scope, "decide", [yieldEvent]);
             if (outcome.outcome === "error") {
                 ctx.replayIndex.consumeYield(ctx.coroutineId);
@@ -87,13 +103,17 @@ function checkReplay(desc, resolve, routine, ctx) {
                         coroutineId: ctx.coroutineId,
                         description: desc,
                     });
+                rememberDurabilityFailure(ctx, error);
                 resolve({ ok: false, error });
                 return { path: "replayed", teardown: (exit) => exit(VOID_OK) };
             }
             // All guards approved — consume the entry and advance cursor
             ctx.replayIndex.consumeYield(ctx.coroutineId);
-            // Feed stored result synchronously
-            resolve(protocolToEffection(entry.result));
+            // Feed stored result synchronously, as a fresh mutable copy: the
+            // authoritative result stays frozen so policy cannot rewrite it, while a
+            // document that resumes on a restored binding still writes to what it
+            // receives.
+            resolve(protocolToEffection(consumable(entry.result)));
             return { path: "replayed", teardown: (exit) => exit(VOID_OK) };
         }
         // No replay entry. Check for continue-past-close divergence (§6.3).
@@ -107,6 +127,7 @@ function checkReplay(desc, resolve, routine, ctx) {
                 },
             ]);
             if (decision.type === "throw") {
+                rememberDurabilityFailure(ctx, decision.error);
                 resolve({ ok: false, error: decision.error });
                 return { path: "replayed", teardown: (exit) => exit(VOID_OK) };
             }
@@ -133,7 +154,12 @@ export function createDurableEffect(desc, execute) {
         description: `${desc.type}(${desc.name})`,
         effectDescription: desc,
         enter(resolve, routine) {
-            const ctx = routine.scope.expect(DurableCtx);
+            const ctx = routine.scope.expect(DurableContext);
+            const durabilityFailure = activeDurabilityFailure(ctx);
+            if (durabilityFailure) {
+                resolve({ ok: false, error: durabilityFailure });
+                return (exit) => exit(VOID_OK);
+            }
             const replay = checkReplay(desc, resolve, routine, ctx);
             if (replay.path === "replayed") {
                 return replay.teardown;
@@ -160,7 +186,7 @@ export function createDurableEffect(desc, execute) {
                 // down, the append is cancelled.
                 routine.scope.run(function* () {
                     try {
-                        yield* ctx.stream.append(event);
+                        yield* appendDurableEvent(ctx, event);
                         resolve(protocolToEffection(result));
                     }
                     catch (err) {
@@ -221,13 +247,20 @@ export function createDurableEffect(desc, 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 function createDurableOperation(desc, execute) {
+export function createDurableOperation(desc, execute, options = {}) {
     return {
         description: `${desc.type}(${desc.name})`,
         effectDescription: desc,
         enter(resolve, routine) {
-            const ctx = routine.scope.expect(DurableCtx);
+            const ctx = routine.scope.expect(DurableContext);
+            const durabilityFailure = activeDurabilityFailure(ctx);
+            if (durabilityFailure) {
+                resolve({ ok: false, error: durabilityFailure });
+                return (exit) => exit(VOID_OK);
+            }
             const replay = checkReplay(desc, resolve, routine, ctx);
             if (replay.path === "replayed") {
                 return replay.teardown;
@@ -236,23 +269,30 @@ export function createDurableOperation(desc, execute) {
             // Run the entire execute → capture → persist → resolve sequence
             // as a structured operation in the routine's scope.
             routine.scope.run(function* () {
-                let result;
-                try {
-                    const value = yield* execute();
-                    result = { status: "ok", value: value };
-                }
-                catch (e) {
-                    const error = e instanceof Error ? e : new Error(String(e));
-                    result = { status: "err", error: serializeError(error) };
+                const active = activeDurabilityFailure(ctx);
+                if (active) {
+                    resolve({ ok: false, error: active });
+                    return;
                 }
-                const event = {
-                    type: "yield",
-                    coroutineId: ctx.coroutineId,
-                    description: desc,
-                    result,
-                };
                 try {
-                    yield* ctx.stream.append(event);
+                    const coordinator = options.coordinator ?? defaultLiveDurableOperationCoordinator;
+                    const activateFailure = (failure) => {
+                        const existing = activeDurabilityFailure(ctx);
+                        if (existing) {
+                            return existing;
+                        }
+                        const error = failure instanceof Error ? failure : new Error(String(failure));
+                        return rememberDurabilityFailure(ctx, error);
+                    };
+                    const result = yield* coordinator.run(execute, function* (published) {
+                        const event = {
+                            type: "yield",
+                            coroutineId: ctx.coroutineId,
+                            description: desc,
+                            result: published,
+                        };
+                        yield* appendDurableEvent(ctx, event);
+                    }, activateFailure, getJournalProvenance(ctx.stream));
                     resolve(protocolToEffection(result));
                 }
                 catch (err) {

package/esm/errors.js

@@ -1,6 +1,38 @@
 /**
  * Error types for the durable execution protocol.
  */
+/**
+ * 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 class DurablePersistenceError extends Error {
+    name = "DurablePersistenceError";
+    constructor(eventType, cause) {
+        super(`Failed to persist durable ${eventType} event`, { cause });
+    }
+}
+/**
+ * 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 class MalformedDurableEventError extends Error {
+    name = "MalformedDurableEventError";
+    /** Location of the offending member within the record. */
+    path;
+    constructor(reason, path) {
+        super(`${reason} at ${path}`);
+        this.path = path;
+    }
+}
 /**
  * Raised when the replay index entry at the current cursor position
  * does not match the effect yielded by the generator. See spec §6.2.
@@ -30,22 +62,37 @@ export class DivergenceError extends Error {
     }
 }
 /**
- * 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 class EarlyReturnDivergenceError extends Error {
-    name = "EarlyReturnDivergenceError";
+export class TerminalDivergenceError extends Error {
+    name = "TerminalDivergenceError";
     coroutineId;
     consumedCount;
     totalCount;
-    constructor(coroutineId, consumedCount, totalCount) {
-        super(`Divergence: generator ${coroutineId} returned after ${consumedCount} yields, ` +
-            `but journal has ${totalCount} yield entries`);
+    constructor(coroutineId, consumedCount, totalCount, options = {}) {
+        super(options.message ??
+            `Divergence: workflow ${coroutineId} terminated after ${consumedCount} yields, ` +
+                `but journal has ${totalCount} yield entries`, { cause: options.cause });
         this.coroutineId = coroutineId;
         this.consumedCount = consumedCount;
         this.totalCount = totalCount;
     }
 }
+/**
+ * Raised when the generator finishes (returns) while the replay index
+ * still has unconsumed entries for this coroutine. See spec §6.3.
+ */
+export class EarlyReturnDivergenceError extends TerminalDivergenceError {
+    name = "EarlyReturnDivergenceError";
+    constructor(coroutineId, consumedCount, totalCount) {
+        super(coroutineId, consumedCount, totalCount, {
+            message: `Divergence: generator ${coroutineId} returned after ${consumedCount} yields, ` +
+                `but journal has ${totalCount} yield entries`,
+        });
+    }
+}
 /**
  * Raised when the journal has a Close event for a coroutine but the
  * generator has not finished after consuming all recorded yields.

package/esm/guard.js

@@ -0,0 +1,107 @@
+/**
+ * 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 { createContext } from "effection";
+class JournalProvenance {
+    #opaque = undefined;
+}
+const journalProvenances = (() => {
+    // This security witness is deliberately canonical-module-local. A loaded
+    // copy cannot read this copy's association or enroll a stream into it.
+    const provenances = new WeakMap();
+    return {
+        establish(stream) {
+            if (provenances.has(stream)) {
+                throw new Error("this durable stream already has journal provenance");
+            }
+            const provenance = new JournalProvenance();
+            provenances.set(stream, provenance);
+            return provenance;
+        },
+        preserve(source, target) {
+            const provenance = provenances.get(source);
+            if (provenance !== undefined) {
+                provenances.set(target, provenance);
+            }
+        },
+        get(stream) {
+            return provenances.get(stream);
+        },
+    };
+})();
+/** Establish the provenance a provider retains for one exact journal backend. */
+export function establishJournalProvenance(stream) {
+    return journalProvenances.establish(stream);
+}
+/**
+ * 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 function preserveJournalProvenance(source, target) {
+    journalProvenances.preserve(source, target);
+    return target;
+}
+/** @internal The live durable path reads provenance without receiving stream authority. */
+export function getJournalProvenance(stream) {
+    return journalProvenances.get(stream);
+}
+const EventRejectionOccurrence = createContext("effectionx.durable-streams.event-rejection-occurrence", undefined);
+export function withDurableEventRejectionOccurrence(occurrence, operation) {
+    return EventRejectionOccurrence.with(occurrence, operation);
+}
+/**
+ * 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 function guardDurableStream(stream, gate) {
+    return {
+        readAll: () => stream.readAll(),
+        *append(event) {
+            // The gate sees a copy so "inspect or reject" is enforced rather than
+            // merely documented: the backend always receives the event the effect
+            // produced, whatever the gate did to the one it was handed.
+            try {
+                yield* gate(structuredClone(event));
+            }
+            catch (error) {
+                const occurrence = yield* EventRejectionOccurrence.get();
+                if (occurrence !== undefined) {
+                    occurrence.rejected = true;
+                    occurrence.error = error;
+                }
+                throw error;
+            }
+            yield* stream.append(event);
+        },
+    };
+}

package/esm/live-coordinator.js

@@ -0,0 +1,16 @@
+import { serializeError } from "./serialize.js";
+/** The ordinary live path: execute once, publish once, then return the same result. */
+export const defaultLiveDurableOperationCoordinator = {
+    *run(execute, publish, _activateFailure, _journalProvenance) {
+        let result;
+        try {
+            result = { status: "ok", value: yield* execute() };
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            result = { status: "err", error: serializeError(failure) };
+        }
+        yield* publish(result);
+        return result;
+    },
+};