@executablemd/durable-streams 0.7.0 → 0.8.1

package/esm/parse.js

@@ -0,0 +1,206 @@
+/**
+ * `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 { Err, Ok } from "effection";
+import { MalformedDurableEventError } from "./errors.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 function parseDurableEvent(record) {
+    try {
+        return Ok(parseEvent(parseRecord(record)));
+    }
+    catch (error) {
+        if (error instanceof MalformedDurableEventError) {
+            return Err(error);
+        }
+        throw error;
+    }
+}
+function parseRecord(record) {
+    try {
+        return JSON.parse(record);
+    }
+    catch {
+        // The thrown SyntaxError quotes the offending text, which is the one
+        // thing a journal parse failure must not repeat.
+        throw new MalformedDurableEventError("expected a JSON record", "$");
+    }
+}
+function parseEvent(value) {
+    const members = parseMembers(value, "$");
+    const type = parseStringMember(members, "type", "$");
+    if (type === "yield") {
+        return parseYield(members);
+    }
+    if (type === "close") {
+        return parseClose(members);
+    }
+    throw new MalformedDurableEventError('expected "yield" or "close"', "$.type");
+}
+function parseYield(members) {
+    requireMemberNames(members, ["type", "coroutineId", "description", "result"], "$");
+    return {
+        type: "yield",
+        coroutineId: parseStringMember(members, "coroutineId", "$"),
+        description: parseEffectDescription(members.get("description"), "$.description"),
+        result: parseResult(members.get("result"), "$.result"),
+    };
+}
+function parseClose(members) {
+    requireMemberNames(members, ["type", "coroutineId", "result"], "$");
+    return {
+        type: "close",
+        coroutineId: parseStringMember(members, "coroutineId", "$"),
+        result: parseResult(members.get("result"), "$.result"),
+    };
+}
+function parseEffectDescription(value, path) {
+    const members = parseMembers(value, path);
+    const description = {
+        type: parseStringMember(members, "type", path),
+        name: parseStringMember(members, "name", path),
+    };
+    for (const [key, member] of members) {
+        if (key === "type" || key === "name") {
+            continue;
+        }
+        // `${path}.*`, not `${path}.${key}`: these member names come from the
+        // record, and a record's own names are as much retained content as its
+        // values. A path built from one would carry it into logs and terminals.
+        define(description, key, parseJsonValue(member, `${path}.*`));
+    }
+    return description;
+}
+function parseResult(value, path) {
+    const members = parseMembers(value, path);
+    const status = parseStringMember(members, "status", path);
+    switch (status) {
+        case "ok": {
+            requireMemberNames(members, ["status", "value"], path);
+            if (!members.has("value")) {
+                return { status: "ok" };
+            }
+            return { status: "ok", value: parseJsonValue(members.get("value"), `${path}.value`) };
+        }
+        case "err": {
+            requireMemberNames(members, ["status", "error"], path);
+            return { status: "err", error: parseSerializedError(members.get("error"), `${path}.error`) };
+        }
+        case "cancelled": {
+            requireMemberNames(members, ["status"], path);
+            return { status: "cancelled" };
+        }
+        default:
+            throw new MalformedDurableEventError('expected "ok", "err" or "cancelled"', `${path}.status`);
+    }
+}
+function parseSerializedError(value, path) {
+    const members = parseMembers(value, path);
+    requireMemberNames(members, ["message", "name", "stack"], path);
+    const error = { message: parseStringMember(members, "message", path) };
+    if (members.has("name")) {
+        error.name = parseStringMember(members, "name", path);
+    }
+    if (members.has("stack")) {
+        error.stack = parseStringMember(members, "stack", path);
+    }
+    return error;
+}
+function parseJsonValue(value, path) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        // JSON has no infinity literal, but an exponent large enough to
+        // overflow — `1e999` — parses to one.
+        if (!Number.isFinite(value)) {
+            throw new MalformedDurableEventError("expected a finite number", path);
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const items = [];
+        for (let index = 0; index < value.length; index++) {
+            items.push(parseJsonValue(value[index], `${path}[${index}]`));
+        }
+        return items;
+    }
+    if (typeof value === "object") {
+        const object = {};
+        for (const [key, member] of Object.entries(value)) {
+            define(object, key, parseJsonValue(member, `${path}.*`));
+        }
+        return object;
+    }
+    throw new MalformedDurableEventError(`expected a JSON value, found ${describe(value)}`, path);
+}
+function parseMembers(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new MalformedDurableEventError(`expected an object, found ${describe(value)}`, path);
+    }
+    return new Map(Object.entries(value));
+}
+function parseStringMember(members, key, path) {
+    const member = members.get(key);
+    if (typeof member !== "string") {
+        throw new MalformedDurableEventError(`expected a string, found ${describe(member)}`, `${path}.${key}`);
+    }
+    return member;
+}
+/**
+ * Refuse a member this shape does not declare, without naming it.
+ *
+ * The names it *does* declare are this module's own and safe to print; the one
+ * that turned up is content from the record, and a record's member names are
+ * as much retained history as its values.
+ */
+function requireMemberNames(members, names, path) {
+    for (const key of members.keys()) {
+        if (!names.includes(key)) {
+            throw new MalformedDurableEventError(`expected only the members ${names.join(", ")}`, path);
+        }
+    }
+}
+/**
+ * Add one member as a plain own data property.
+ *
+ * `object[key] = value` is not equivalent for the key `__proto__`: it
+ * reaches `Object.prototype`'s inherited setter, which under V8 and
+ * JavaScriptCore replaces the object's prototype and drops the key while
+ * Deno's parse keeps it. `JSON.parse` makes `__proto__` an own property,
+ * so any record can carry one, and the same record would otherwise parse
+ * to a different object on different runtimes.
+ */
+function define(object, key, value) {
+    Object.defineProperty(object, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+function describe(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "an array";
+    }
+    return typeof value;
+}

package/esm/replay-guard.js

@@ -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.
@@ -37,6 +49,12 @@ import { createApi } from "effection/experimental";
 function* defaultCheck(_event) {
     // No observation — pass through to next middleware or default.
 }
+/**
+ * Default admit — no-op. A history nobody objects to is replayed.
+ */
+function* defaultAdmit(_history) {
+    // No requirement — 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
@@ -78,4 +96,4 @@ function defaultDecide(_event) {
  * }
  * ```
  */
-export const ReplayGuard = createApi("DurableEffection.ReplayGuard", { check: defaultCheck, decide: defaultDecide });
+export const ReplayGuard = createApi("DurableEffection.ReplayGuard", { check: defaultCheck, admit: defaultAdmit, decide: defaultDecide });

package/esm/replay-index.js

@@ -4,30 +4,50 @@
  * Provides per-coroutine cursored access to Yield events and keyed access
  * to Close events. See spec §4.1.
  */
+import { retainEvents } from "./retained.js";
 export class ReplayIndex {
     yields = new Map();
+    /** Every retained Yield in stream order, each owning its own settled cells. */
+    retained = [];
     cursors = new Map();
     closes = new Map();
     /** Coroutines where replay has been disabled (run-live mode). */
     disabled = new Set();
+    /** Retained coroutine identities reached by the current definition. */
+    claimed = new Set();
+    /**
+     * 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) {
-        for (const event of events) {
+        for (const event of retainEvents(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,
-                });
+                this.retained.push(event);
+                list.push(event);
             }
             if (event.type === "close") {
                 this.closes.set(event.coroutineId, event);
             }
         }
     }
+    /**
+     * 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() {
+        return [...this.retained];
+    }
     /**
      * Disable replay for a coroutine (run-live mode).
      *
@@ -42,6 +62,19 @@ export class ReplayIndex {
     isReplayDisabled(coroutineId) {
         return this.disabled.has(coroutineId);
     }
+    /** Mark a retained coroutine identity as reached by the current run. */
+    claim(coroutineId) {
+        this.claimed.add(coroutineId);
+        if (!this.closes.has(coroutineId)) {
+            return;
+        }
+        const retainedIds = new Set([...this.yields.keys(), ...this.closes.keys()]);
+        for (const retainedId of retainedIds) {
+            if (retainedId.startsWith(`${coroutineId}.`)) {
+                this.claimed.add(retainedId);
+            }
+        }
+    }
     /**
      * Returns the next unconsumed yield for this coroutine,
      * or undefined if the cursor is past the end or replay is disabled.
@@ -95,24 +128,27 @@ export class ReplayIndex {
         }
         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()) {
+    /** Return the first retained coroutine not aligned with the current subtree. */
+    firstUnaligned(subtreeId) {
+        if (this.disabled.has(subtreeId)) {
+            return undefined;
+        }
+        const coroutineIds = new Set([...this.yields.keys(), ...this.closes.keys()]);
+        for (const coroutineId of coroutineIds) {
+            if (coroutineId !== subtreeId && !coroutineId.startsWith(`${subtreeId}.`)) {
+                continue;
+            }
             if (this.disabled.has(coroutineId)) {
                 continue;
             }
             if (this.closes.has(coroutineId)) {
+                if (!this.claimed.has(coroutineId)) {
+                    const entries = this.yields.get(coroutineId) ?? [];
+                    return { coroutineId, cursor: 0, totalYields: entries.length };
+                }
                 continue;
             }
+            const entries = this.yields.get(coroutineId) ?? [];
             const cursor = this.cursors.get(coroutineId) ?? 0;
             if (cursor < entries.length) {
                 return { coroutineId, cursor, totalYields: entries.length };