@nifrajs/core 2.0.0 → 2.2.0

package/dist/durable-execution.js

@@ -0,0 +1,1173 @@
+/**
+ * Durable capability execution primitives. This subpath is opt-in so the bare HTTP runtime stays
+ * lean. Approval and journal records are token-only. Saga input, results, and compensation arguments
+ * intentionally live only in the caller-supplied durable saga store — never in the effect ledger or
+ * telemetry — and production stores should encrypt them according to the application's data policy.
+ */
+import { emitEffectLifecycle } from "./effect-lifecycle.js";
+import { createEffectScope } from "./effect-scope.js";
+import { validCapabilityId } from "./internal/capability-runtime.js";
+import { safeEqual } from "./internal/safe-equal.js";
+const TOKEN = /^[!-~]+$/;
+const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function assertToken(value, label, maxLength = 255) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxLength ||
+        !TOKEN.test(value)) {
+        throw new TypeError(`${label} must be a bounded printable token`);
+    }
+}
+function assertPositiveMs(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`${label} must be a positive safe integer`);
+}
+function assertTimestamp(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError(`${label} must be a non-negative safe integer timestamp`);
+}
+function readClock(clock, label) {
+    const value = clock();
+    assertTimestamp(value, label);
+    return value;
+}
+function addDuration(timestamp, duration, label) {
+    const result = timestamp + duration;
+    assertTimestamp(result, label);
+    return result;
+}
+function bytesToBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function base64UrlToBytes(value) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value))
+        throw new ApprovalTokenInvalidError();
+    const padded = value
+        .replaceAll("-", "+")
+        .replaceAll("_", "/")
+        .padEnd(Math.ceil(value.length / 4) * 4, "=");
+    let binary;
+    try {
+        binary = atob(padded);
+    }
+    catch {
+        throw new ApprovalTokenInvalidError();
+    }
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+async function sha256(value) {
+    return bytesToBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value))));
+}
+function cloneValue(value) {
+    return structuredClone(value);
+}
+export class DurableEffectTransitionError extends Error {
+    effectId;
+    transition;
+    constructor(effectId, transition) {
+        super(`durable effect ${effectId}: ${transition} transition was rejected`);
+        this.effectId = effectId;
+        this.transition = transition;
+        this.name = "DurableEffectTransitionError";
+    }
+}
+export function createDurableEffectJournal(options) {
+    if (options.store.durability !== "durable" && options.allowMemoryStore !== true) {
+        throw new TypeError('durable effect journal requires store.durability === "durable"');
+    }
+    const clock = options.now ?? Date.now;
+    const now = () => readClock(clock, "durable effect clock");
+    const current = async (effectId) => {
+        assertToken(effectId, "durable effect id", 64);
+        const record = await options.store.get(effectId);
+        if (record === undefined)
+            throw new DurableEffectTransitionError(effectId, "missing");
+        if (record.effectId !== effectId ||
+            !validCapabilityId(record.capability) ||
+            !["admission", "executing", "committed", "failed", "unknown"].includes(record.state) ||
+            !Number.isSafeInteger(record.version) ||
+            record.version < 1) {
+            throw new TypeError(`durable effect ${effectId}: store returned an invalid record`);
+        }
+        assertTimestamp(record.createdAt, "durable effect createdAt");
+        assertTimestamp(record.updatedAt, "durable effect updatedAt");
+        if (record.createdAt > record.updatedAt)
+            throw new TypeError(`durable effect ${effectId}: updatedAt precedes createdAt`);
+        if (record.target !== undefined)
+            assertToken(record.target, "stored durable effect target", 128);
+        if (record.digest !== undefined && !/^[0-9a-f]{64}$/u.test(record.digest))
+            throw new TypeError(`durable effect ${effectId}: store returned an invalid digest`);
+        if (record.tenantId !== undefined)
+            assertToken(record.tenantId, "stored durable effect tenantId");
+        if (record.principalId !== undefined)
+            assertToken(record.principalId, "stored durable effect principalId");
+        if ((record.tenantId === undefined) !== (record.principalId === undefined))
+            throw new TypeError(`durable effect ${effectId}: store returned a partial identity`);
+        if (record.errorCode !== undefined && !ERROR_CODE.test(record.errorCode))
+            throw new TypeError(`durable effect ${effectId}: store returned an invalid error code`);
+        return record;
+    };
+    const transition = async (effectId, from, to, errorCode) => {
+        const record = await current(effectId);
+        if (record.state !== from)
+            throw new DurableEffectTransitionError(effectId, `${from}->${to}`);
+        const accepted = await options.store.transition({
+            effectId,
+            version: record.version,
+            from,
+            to,
+            updatedAt: now(),
+            ...(errorCode === undefined ? {} : { errorCode }),
+        });
+        if (!accepted)
+            throw new DurableEffectTransitionError(effectId, `${from}->${to}`);
+    };
+    const journal = {
+        async intent(input) {
+            assertToken(input.effectId, "durable effect id", 64);
+            if (!validCapabilityId(input.capability))
+                throw new TypeError("durable effect capability is invalid");
+            if (input.target !== undefined)
+                assertToken(input.target, "durable effect target", 128);
+            if (input.digest !== undefined && !/^[0-9a-f]{64}$/u.test(input.digest))
+                throw new TypeError("durable effect digest is invalid");
+            if (input.identity !== undefined) {
+                assertToken(input.identity.tenantId, "durable effect tenantId");
+                assertToken(input.identity.principalId, "durable effect principalId");
+            }
+            const at = now();
+            const accepted = await options.store.create(Object.freeze({
+                effectId: input.effectId,
+                capability: input.capability,
+                ...(input.target === undefined ? {} : { target: input.target }),
+                ...(input.digest === undefined ? {} : { digest: input.digest }),
+                ...(input.identity === undefined
+                    ? {}
+                    : { tenantId: input.identity.tenantId, principalId: input.identity.principalId }),
+                state: "admission",
+                createdAt: at,
+                updatedAt: at,
+                version: 1,
+            }));
+            if (!accepted)
+                throw new DurableEffectTransitionError(input.effectId, "create");
+        },
+        async executing(effectId) {
+            await transition(effectId, "admission", "executing");
+        },
+        async committed(effectId) {
+            await transition(effectId, "executing", "committed");
+        },
+        async failed(effectId, input) {
+            if (!ERROR_CODE.test(input.errorCode))
+                throw new TypeError("durable effect errorCode is invalid");
+            const record = await current(effectId);
+            const to = input.began ? "unknown" : "failed";
+            const accepted = await options.store.transition({
+                effectId,
+                version: record.version,
+                from: record.state,
+                to,
+                updatedAt: now(),
+                errorCode: input.errorCode,
+            });
+            if (!accepted)
+                throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`);
+        },
+    };
+    return Object.freeze(journal);
+}
+export class MemoryDurableEffectStore {
+    durability = "memory";
+    records = new Map();
+    // Secondary index: effectIds grouped by state, so reconciliation scans only the requested (few,
+    // non-terminal) states instead of walking every retained record. See {@link indexedScan}.
+    byState = new Map();
+    create(record) {
+        if (this.records.has(record.effectId))
+            return false;
+        this.records.set(record.effectId, Object.freeze(cloneValue(record)));
+        bucketAdd(this.byState, record.state, record.effectId);
+        return true;
+    }
+    get(effectId) {
+        const record = this.records.get(effectId);
+        return record === undefined ? undefined : Object.freeze(cloneValue(record));
+    }
+    transition(input) {
+        const current = this.records.get(input.effectId);
+        if (current === undefined || current.version !== input.version || current.state !== input.from)
+            return false;
+        this.records.set(input.effectId, Object.freeze({
+            ...current,
+            state: input.to,
+            updatedAt: input.updatedAt,
+            version: current.version + 1,
+            ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
+        }));
+        bucketMove(this.byState, current.state, input.to, input.effectId);
+        return true;
+    }
+    list() {
+        return Object.freeze([...this.records.values()].map((record) => Object.freeze(cloneValue(record))));
+    }
+    scan(input) {
+        return indexedScan(this.byState, (id) => this.records.get(id), input);
+    }
+}
+const DEFAULT_RECONCILIATION_LIMIT = 100;
+const MAX_RECONCILIATION_LIMIT = 1_000;
+function reconciliationLimit(value = DEFAULT_RECONCILIATION_LIMIT) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_RECONCILIATION_LIMIT) {
+        throw new RangeError(`reconciliation limit must be between 1 and ${MAX_RECONCILIATION_LIMIT}`);
+    }
+    return value;
+}
+function cursorOffset(cursor) {
+    if (cursor === undefined)
+        return 0;
+    if (!/^(?:0|[1-9][0-9]*)$/u.test(cursor))
+        throw new TypeError("invalid reconciliation cursor");
+    const offset = Number(cursor);
+    if (!Number.isSafeInteger(offset))
+        throw new TypeError("invalid reconciliation cursor");
+    return offset;
+}
+function memoryScan(source, input) {
+    const states = new Set(input.states);
+    const offset = cursorOffset(input.cursor);
+    const end = offset + input.limit;
+    const records = [];
+    // Stream the source: skip the first `offset` eligible records, collect up to `limit`, and stop as
+    // soon as one more eligible record proves a next page exists. Bounds allocation to the page and
+    // avoids materializing the whole store when the page fills early. (An unindexed in-memory store still
+    // walks its records to find sparse matches; a production store implements `scan()` as an indexed
+    // query - state + updatedAt predicate, keyset cursor - instead of relying on this reference scan.)
+    let seen = 0;
+    let more = false;
+    for (const record of source) {
+        if (!states.has(record.state))
+            continue;
+        if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore)
+            continue;
+        if (seen >= end) {
+            more = true;
+            break;
+        }
+        if (seen >= offset)
+            records.push(cloneValue(record));
+        seen++;
+    }
+    return Object.freeze({
+        records: Object.freeze(records),
+        ...(more ? { cursor: String(offset + records.length) } : {}),
+    });
+}
+function bucketAdd(byState, state, id) {
+    let bucket = byState.get(state);
+    if (bucket === undefined) {
+        bucket = new Set();
+        byState.set(state, bucket);
+    }
+    bucket.add(id);
+}
+function bucketMove(byState, from, to, id) {
+    if (from === to)
+        return;
+    byState.get(from)?.delete(id);
+    bucketAdd(byState, to, id);
+}
+/**
+ * Paginate a state-bucketed in-memory index: walk only the requested states' buckets (each a Set of
+ * ids in insertion order), resolve + `updatedBefore`-filter each record, and page by offset cursor.
+ * O(sum of the requested buckets) instead of O(total records) - the store still retains terminal
+ * records, but reconciliation never walks them. Matches {@link memoryScan}'s paging semantics.
+ */
+function indexedScan(byState, resolve, input) {
+    const offset = cursorOffset(input.cursor);
+    const end = offset + input.limit;
+    const records = [];
+    let seen = 0;
+    let more = false;
+    for (const state of new Set(input.states)) {
+        if (more)
+            break;
+        const bucket = byState.get(state);
+        if (bucket === undefined)
+            continue;
+        for (const id of bucket) {
+            const record = resolve(id);
+            if (record === undefined)
+                continue;
+            if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore)
+                continue;
+            if (seen >= end) {
+                more = true;
+                break;
+            }
+            if (seen >= offset)
+                records.push(cloneValue(record));
+            seen++;
+        }
+    }
+    return Object.freeze({
+        records: Object.freeze(records),
+        ...(more ? { cursor: String(offset + records.length) } : {}),
+    });
+}
+async function scanEffectRecords(store, input) {
+    if (store.scan !== undefined)
+        return await store.scan(input);
+    if (store.list === undefined)
+        throw new TypeError("effect store does not support reconciliation");
+    return memoryScan(await store.list(), input);
+}
+export async function reconcileEffectsPage(store, options) {
+    const findings = [];
+    const page = await scanEffectRecords(store, {
+        states: ["admission", "executing", "unknown"],
+        updatedBefore: options.staleBefore,
+        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+        limit: reconciliationLimit(options.limit),
+    });
+    for (const record of page.records) {
+        if (!validCapabilityId(record.capability) || !/^[!-~]{1,64}$/u.test(record.effectId))
+            continue;
+        if (record.updatedAt > options.staleBefore)
+            continue;
+        const state = record.state === "admission"
+            ? "incomplete"
+            : record.state === "executing" || record.state === "unknown"
+                ? "ambiguous"
+                : undefined;
+        if (state === undefined)
+            continue;
+        findings.push(Object.freeze({
+            effectId: record.effectId,
+            capability: record.capability,
+            state,
+            updatedAt: record.updatedAt,
+        }));
+        if (options.observer !== undefined) {
+            emitEffectLifecycle([options.observer], {
+                effectId: record.effectId,
+                capability: record.capability,
+                stage: "reconciliation",
+                phase: state === "ambiguous" ? "ambiguous" : "failed",
+                errorCode: state === "ambiguous" ? "effect_ambiguous" : "effect_incomplete",
+            });
+        }
+    }
+    return Object.freeze({
+        findings: Object.freeze(findings),
+        ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+    });
+}
+export async function reconcileEffects(store, options) {
+    const page = await reconcileEffectsPage(store, {
+        ...options,
+        limit: MAX_RECONCILIATION_LIMIT,
+    });
+    if (page.cursor !== undefined) {
+        throw new RangeError(`effect reconciliation exceeds ${MAX_RECONCILIATION_LIMIT} records; use reconcileEffectsPage()`);
+    }
+    return page.findings;
+}
+export class ApprovalRequiredError extends Error {
+    approvalId;
+    effectId;
+    resumeToken;
+    expiresAt;
+    constructor(approvalId, effectId, resumeToken, expiresAt) {
+        super("capability approval is required");
+        this.approvalId = approvalId;
+        this.effectId = effectId;
+        this.expiresAt = expiresAt;
+        Object.defineProperty(this, "resumeToken", {
+            value: resumeToken,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+        this.name = "ApprovalRequiredError";
+    }
+}
+export class ApprovalTokenInvalidError extends Error {
+    constructor() {
+        super("approval resume token is invalid");
+        this.name = "ApprovalTokenInvalidError";
+    }
+}
+export class ApprovalTokenExpiredError extends Error {
+    constructor() {
+        super("approval resume token has expired");
+        this.name = "ApprovalTokenExpiredError";
+    }
+}
+export class ApprovalTokenReplayError extends Error {
+    constructor() {
+        super("approval resume token has already been consumed");
+        this.name = "ApprovalTokenReplayError";
+    }
+}
+export class ApprovalBindingError extends Error {
+    constructor() {
+        super("approval resume token is bound to another tenant or principal");
+        this.name = "ApprovalBindingError";
+    }
+}
+export class ApprovalPendingError extends Error {
+    constructor() {
+        super("capability approval is still pending");
+        this.name = "ApprovalPendingError";
+    }
+}
+export class ApprovalDeniedError extends Error {
+    constructor() {
+        super("capability approval was denied");
+        this.name = "ApprovalDeniedError";
+    }
+}
+export function createApprovalCoordinator(options) {
+    if (options.store.durability !== "durable" && options.allowMemoryStore !== true) {
+        throw new TypeError('approval coordinator requires store.durability === "durable"');
+    }
+    if (!(options.secret instanceof Uint8Array) || options.secret.byteLength < 32) {
+        throw new TypeError("approval secret must contain at least 32 random bytes");
+    }
+    const secret = new Uint8Array(options.secret);
+    const ttlMs = options.ttlMs ?? 15 * 60_000;
+    assertPositiveMs(ttlMs, "approval ttlMs");
+    const clock = options.now ?? Date.now;
+    const now = () => readClock(clock, "approval clock");
+    const key = crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+        "verify",
+    ]);
+    const sign = async (claims) => {
+        const payload = bytesToBase64Url(encoder.encode(JSON.stringify(claims)));
+        const signature = new Uint8Array(await crypto.subtle.sign("HMAC", await key, encoder.encode(payload)));
+        return `v1.${payload}.${bytesToBase64Url(signature)}`;
+    };
+    const verify = async (token) => {
+        if (typeof token !== "string" || token.length > 2048)
+            throw new ApprovalTokenInvalidError();
+        const parts = token.split(".");
+        if (parts.length !== 3 || parts[0] !== "v1")
+            throw new ApprovalTokenInvalidError();
+        const payload = parts[1];
+        const valid = await crypto.subtle.verify("HMAC", await key, base64UrlToBytes(parts[2]).buffer, encoder.encode(payload));
+        if (!valid)
+            throw new ApprovalTokenInvalidError();
+        let claims;
+        try {
+            claims = JSON.parse(decoder.decode(base64UrlToBytes(payload)));
+        }
+        catch {
+            throw new ApprovalTokenInvalidError();
+        }
+        if (typeof claims !== "object" || claims === null)
+            throw new ApprovalTokenInvalidError();
+        const candidate = claims;
+        if (candidate.v !== 1 ||
+            typeof candidate.id !== "string" ||
+            typeof candidate.nonce !== "string" ||
+            !Number.isSafeInteger(candidate.exp)) {
+            throw new ApprovalTokenInvalidError();
+        }
+        assertToken(candidate.id, "approval id", 128);
+        assertToken(candidate.nonce, "approval nonce", 128);
+        if (candidate.exp <= now())
+            throw new ApprovalTokenExpiredError();
+        return candidate;
+    };
+    const coordinator = {
+        async authorize(input) {
+            if (input.signal.aborted)
+                throw input.signal.reason;
+            assertToken(input.identity.tenantId, "approval tenantId");
+            assertToken(input.identity.principalId, "approval principalId");
+            if (input.resumeToken === undefined) {
+                const approvalId = crypto.randomUUID();
+                const nonce = bytesToBase64Url(crypto.getRandomValues(new Uint8Array(18)));
+                const issuedAt = now();
+                const expiresAt = addDuration(issuedAt, ttlMs, "approval expiry");
+                const resumeToken = await sign({ v: 1, id: approvalId, nonce, exp: expiresAt });
+                const accepted = await options.store.create(Object.freeze({
+                    approvalId,
+                    effectId: input.effectId,
+                    capability: input.capability,
+                    ...(input.target === undefined ? {} : { target: input.target }),
+                    ...(input.digest === undefined ? {} : { digest: input.digest }),
+                    tenantId: input.identity.tenantId,
+                    principalId: input.identity.principalId,
+                    tokenHash: await sha256(resumeToken),
+                    state: "pending",
+                    createdAt: issuedAt,
+                    expiresAt,
+                    updatedAt: issuedAt,
+                    version: 1,
+                }));
+                if (!accepted)
+                    throw new Error("approval store rejected a unique approval id");
+                throw new ApprovalRequiredError(approvalId, input.effectId, resumeToken, expiresAt);
+            }
+            const claims = await verify(input.resumeToken);
+            const consumed = await options.store.consume({
+                approvalId: claims.id,
+                tenantId: input.identity.tenantId,
+                principalId: input.identity.principalId,
+                capability: input.capability,
+                ...(input.target === undefined ? {} : { target: input.target }),
+                ...(input.digest === undefined ? {} : { digest: input.digest }),
+                tokenHash: await sha256(input.resumeToken),
+                now: now(),
+            });
+            if (consumed.state === "consumed")
+                return;
+            if (consumed.state === "replay")
+                throw new ApprovalTokenReplayError();
+            if (consumed.state === "binding")
+                throw new ApprovalBindingError();
+            if (consumed.state === "expired")
+                throw new ApprovalTokenExpiredError();
+            if (consumed.state === "pending")
+                throw new ApprovalPendingError();
+            if (consumed.state === "denied")
+                throw new ApprovalDeniedError();
+            throw new ApprovalTokenInvalidError();
+        },
+        async decide(input) {
+            assertToken(input.approvalId, "approval id", 128);
+            assertToken(input.tenantId, "approval tenantId");
+            assertToken(input.decidedBy, "approval decidedBy");
+            const accepted = await options.store.decide({ ...input, now: now() });
+            if (!accepted)
+                throw new Error("approval decision rejected");
+        },
+        async get(approvalId) {
+            assertToken(approvalId, "approval id", 128);
+            return await options.store.get(approvalId);
+        },
+    };
+    return Object.freeze(coordinator);
+}
+export class MemoryApprovalStore {
+    durability = "memory";
+    records = new Map();
+    create(record) {
+        if (this.records.has(record.approvalId))
+            return false;
+        this.records.set(record.approvalId, Object.freeze(cloneValue(record)));
+        return true;
+    }
+    get(approvalId) {
+        const record = this.records.get(approvalId);
+        return record === undefined ? undefined : Object.freeze(cloneValue(record));
+    }
+    decide(input) {
+        const record = this.records.get(input.approvalId);
+        if (record === undefined ||
+            record.tenantId !== input.tenantId ||
+            record.state !== "pending" ||
+            record.expiresAt <= input.now)
+            return false;
+        this.records.set(input.approvalId, Object.freeze({
+            ...record,
+            state: input.decision,
+            decidedBy: input.decidedBy,
+            updatedAt: input.now,
+            version: record.version + 1,
+        }));
+        return true;
+    }
+    consume(input) {
+        const record = this.records.get(input.approvalId);
+        if (record === undefined)
+            return { state: "missing" };
+        if (record.tenantId !== input.tenantId ||
+            record.principalId !== input.principalId ||
+            record.capability !== input.capability ||
+            record.target !== input.target ||
+            !safeEqual(record.digest, input.digest))
+            return { state: "binding" };
+        if (!safeEqual(record.tokenHash, input.tokenHash))
+            return { state: "token" };
+        if (record.state === "consumed")
+            return { state: "replay" };
+        if (record.expiresAt <= input.now || record.state === "expired") {
+            if (record.state !== "expired")
+                this.records.set(input.approvalId, Object.freeze({
+                    ...record,
+                    state: "expired",
+                    updatedAt: input.now,
+                    version: record.version + 1,
+                }));
+            return { state: "expired" };
+        }
+        if (record.state === "pending")
+            return { state: "pending" };
+        if (record.state === "denied")
+            return { state: "denied" };
+        if (record.state !== "approved")
+            return { state: "token" };
+        this.records.set(input.approvalId, Object.freeze({
+            ...record,
+            state: "consumed",
+            updatedAt: input.now,
+            version: record.version + 1,
+        }));
+        return { state: "consumed" };
+    }
+    list() {
+        return Object.freeze([...this.records.values()].map((record) => Object.freeze(cloneValue(record))));
+    }
+}
+function assertSagaDefinition(definition) {
+    if (typeof definition !== "object" || definition === null)
+        throw new TypeError("saga definition must be an object");
+    assertToken(definition.name, "saga definition", 128);
+    if (definition.capability !== undefined && !validCapabilityId(definition.capability))
+        throw new TypeError("saga capability is invalid");
+    if (typeof definition.run !== "function")
+        throw new TypeError("saga run must be a function");
+    if (typeof definition.compensators !== "object" ||
+        definition.compensators === null ||
+        Array.isArray(definition.compensators)) {
+        throw new TypeError("saga compensators must be an object");
+    }
+    for (const [name, compensator] of Object.entries(definition.compensators)) {
+        assertToken(name, "saga compensator name", 128);
+        if (typeof compensator !== "function")
+            throw new TypeError(`saga compensator ${name} must be a function`);
+    }
+    if (definition.retry !== undefined) {
+        if (typeof definition.retry !== "object" || definition.retry === null)
+            throw new TypeError("saga retry must be an object");
+        if (definition.retry.maxAttempts !== undefined)
+            assertPositiveMs(definition.retry.maxAttempts, "saga maxAttempts");
+        if (definition.retry.backoffMs !== undefined &&
+            typeof definition.retry.backoffMs !== "function")
+            throw new TypeError("saga backoffMs must be a function");
+    }
+}
+export function defineSaga(definition) {
+    assertSagaDefinition(definition);
+    return Object.freeze({
+        ...definition,
+        compensators: Object.freeze({ ...definition.compensators }),
+        ...(definition.retry === undefined ? {} : { retry: Object.freeze({ ...definition.retry }) }),
+    });
+}
+export class SagaConcurrencyError extends Error {
+    sagaId;
+    constructor(sagaId) {
+        super(`saga ${sagaId}: concurrent transition rejected`);
+        this.sagaId = sagaId;
+        this.name = "SagaConcurrencyError";
+    }
+}
+export class SagaAmbiguousStepError extends Error {
+    sagaId;
+    step;
+    effectId;
+    constructor(sagaId, step, effectId) {
+        super(`saga ${sagaId}: step ${step} has an ambiguous effect`);
+        this.sagaId = sagaId;
+        this.step = step;
+        this.effectId = effectId;
+        this.name = "SagaAmbiguousStepError";
+    }
+}
+export class SagaResolutionError extends Error {
+    sagaId;
+    step;
+    constructor(sagaId, step, message) {
+        super(`saga ${sagaId}: step ${step} ${message}`);
+        this.sagaId = sagaId;
+        this.step = step;
+        this.name = "SagaResolutionError";
+    }
+}
+/** Throw this only when a provider conclusively proves that no effect committed. */
+export class SagaStepNotCommittedError extends Error {
+    code;
+    constructor(code = "not_committed") {
+        super("saga step conclusively did not commit");
+        this.code = code;
+        this.name = "SagaStepNotCommittedError";
+        if (!ERROR_CODE.test(code))
+            throw new TypeError("saga step error code is invalid");
+    }
+}
+let neverAbortSignal;
+function signalOrNever(signal) {
+    neverAbortSignal ??= new AbortController().signal;
+    return signal ?? neverAbortSignal;
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error("saga execution aborted");
+    }
+}
+export function createSagaEngine(options) {
+    if (options.store.durability !== "durable" && options.allowMemoryStore !== true)
+        throw new TypeError('saga engine requires store.durability === "durable"');
+    const clock = options.now ?? Date.now;
+    const now = () => readClock(clock, "saga clock");
+    const observer = options.observer;
+    const load = async (sagaId) => {
+        const record = await options.store.get(sagaId);
+        if (record === undefined)
+            throw new Error(`saga ${sagaId}: not found`);
+        if (record.sagaId !== sagaId ||
+            !["running", "compensating", "completed", "compensated", "manual-review"].includes(record.state) ||
+            !Array.isArray(record.steps) ||
+            !Number.isSafeInteger(record.version) ||
+            record.version < 1) {
+            throw new TypeError(`saga ${sagaId}: store returned an invalid record`);
+        }
+        assertToken(record.definition, "stored saga definition", 128);
+        assertTimestamp(record.createdAt, "stored saga createdAt");
+        assertTimestamp(record.updatedAt, "stored saga updatedAt");
+        if (record.createdAt > record.updatedAt)
+            throw new TypeError(`saga ${sagaId}: updatedAt precedes createdAt`);
+        const names = new Set();
+        const effectIds = new Set();
+        for (const step of record.steps) {
+            assertToken(step.name, "stored saga step", 128);
+            assertToken(step.effectId, "stored saga effect id", 64);
+            assertToken(step.compensationEffectId, "stored saga compensation effect id", 64);
+            if (![
+                "executing",
+                "committed",
+                "failed",
+                "ambiguous",
+                "compensating",
+                "compensation-failed",
+                "compensated",
+            ].includes(step.state) ||
+                !Number.isSafeInteger(step.attempts) ||
+                step.attempts < 0 ||
+                names.has(step.name) ||
+                effectIds.has(step.effectId) ||
+                effectIds.has(step.compensationEffectId)) {
+                throw new TypeError(`saga ${sagaId}: store returned an invalid step record`);
+            }
+            names.add(step.name);
+            effectIds.add(step.effectId);
+            effectIds.add(step.compensationEffectId);
+            if (step.nextAttemptAt !== undefined)
+                assertTimestamp(step.nextAttemptAt, "stored saga nextAttemptAt");
+            if (step.errorCode !== undefined && !ERROR_CODE.test(step.errorCode))
+                throw new TypeError(`saga ${sagaId}: store returned an invalid error code`);
+        }
+        return record;
+    };
+    const save = async (current, update) => {
+        const next = Object.freeze({ ...update, version: current.version + 1 });
+        if (!(await options.store.compareAndSet({
+            sagaId: current.sagaId,
+            version: current.version,
+            record: next,
+        })))
+            throw new SagaConcurrencyError(current.sagaId);
+        return next;
+    };
+    const withStep = (record, index, step, state = record.state) => ({
+        ...record,
+        state,
+        steps: Object.freeze(record.steps.map((candidate, candidateIndex) => candidateIndex === index ? Object.freeze(step) : candidate)),
+        updatedAt: now(),
+    });
+    const effectScope = createEffectScope({
+        ...(observer === undefined ? {} : { observers: [observer] }),
+    });
+    const compensate = async (definition, sagaId, runOptions = {}) => {
+        assertSagaDefinition(definition);
+        assertToken(sagaId, "saga id", 128);
+        const signal = signalOrNever(runOptions.signal);
+        throwIfAborted(signal);
+        let record = await load(sagaId);
+        if (record.definition !== definition.name)
+            throw new TypeError("saga definition mismatch");
+        if (record.state === "completed" || record.state === "compensated")
+            return record;
+        if (record.steps.some((step) => step.state === "ambiguous" || step.state === "executing" || step.state === "compensating")) {
+            if (record.state !== "manual-review")
+                record = await save(record, { ...record, state: "manual-review", updatedAt: now() });
+            const ambiguous = record.steps.find((step) => step.state === "ambiguous" || step.state === "executing" || step.state === "compensating");
+            throw new SagaAmbiguousStepError(sagaId, ambiguous.name, ambiguous.state === "compensating" ? ambiguous.compensationEffectId : ambiguous.effectId);
+        }
+        if (record.state !== "compensating")
+            record = await save(record, { ...record, state: "compensating", updatedAt: now() });
+        const maxAttempts = definition.retry?.maxAttempts ?? 3;
+        assertPositiveMs(maxAttempts, "saga maxAttempts");
+        const backoff = definition.retry?.backoffMs ??
+            ((attempt) => Math.min(60_000, 100 * 2 ** (attempt - 1)));
+        for (let index = record.steps.length - 1; index >= 0; index--) {
+            throwIfAborted(signal);
+            let step = record.steps[index];
+            if (step.state === "compensated" || step.state === "failed")
+                continue;
+            if (step.state !== "committed" && step.state !== "compensation-failed")
+                continue;
+            if (step.nextAttemptAt !== undefined && step.nextAttemptAt > now())
+                return record;
+            const compensator = definition.compensators[step.name];
+            if (typeof compensator !== "function") {
+                record = await save(record, { ...record, state: "manual-review", updatedAt: now() });
+                return record;
+            }
+            if (step.attempts >= maxAttempts) {
+                if (record.state !== "manual-review")
+                    record = await save(record, { ...record, state: "manual-review", updatedAt: now() });
+                return record;
+            }
+            const attempt = step.attempts + 1;
+            const { errorCode: _errorCode, nextAttemptAt: _nextAttemptAt, ...stepBase } = step;
+            step = { ...stepBase, state: "compensating", attempts: attempt };
+            let transitionError;
+            try {
+                await effectScope.run({
+                    effectId: step.compensationEffectId,
+                    capability: definition.capability ?? "saga.compensate",
+                    stage: "compensation",
+                    signal,
+                    attempt,
+                    failurePhase: () => "failed",
+                    errorCode: () => "compensation_failed",
+                    transitions: {
+                        async executing() {
+                            record = await save(record, withStep(record, index, step));
+                        },
+                        async committed() {
+                            step = { ...step, state: "compensated" };
+                            record = await save(record, withStep(record, index, step));
+                        },
+                        async failed() {
+                            const exhausted = attempt >= maxAttempts;
+                            try {
+                                const delay = exhausted ? undefined : backoff(attempt);
+                                if (delay !== undefined && (!Number.isSafeInteger(delay) || delay < 0))
+                                    throw new RangeError("saga backoff must return a non-negative safe integer");
+                                const failed = {
+                                    ...step,
+                                    state: "compensation-failed",
+                                    errorCode: "compensation_failed",
+                                    ...(delay === undefined
+                                        ? {}
+                                        : { nextAttemptAt: addDuration(now(), delay, "saga next retry") }),
+                                };
+                                record = await save(record, withStep(record, index, failed, exhausted ? "manual-review" : "compensating"));
+                            }
+                            catch (error) {
+                                transitionError = error;
+                                const failed = {
+                                    ...step,
+                                    state: "compensation-failed",
+                                    errorCode: "invalid_retry_policy",
+                                };
+                                record = await save(record, withStep(record, index, failed, "manual-review"));
+                            }
+                        },
+                    },
+                }, async (owned) => {
+                    await compensator(cloneValue(step.compensationArgs), {
+                        effectId: owned.effectId,
+                        sagaId,
+                        attempt,
+                        signal: owned.signal,
+                    });
+                });
+            }
+            catch {
+                if (transitionError !== undefined)
+                    throw transitionError;
+                return record;
+            }
+        }
+        return await save(record, { ...record, state: "compensated", updatedAt: now() });
+    };
+    const resume = async (definition, sagaId, runOptions = {}) => {
+        assertSagaDefinition(definition);
+        assertToken(sagaId, "saga id", 128);
+        const signal = signalOrNever(runOptions.signal);
+        throwIfAborted(signal);
+        let record = await load(sagaId);
+        if (record.definition !== definition.name)
+            throw new TypeError("saga definition mismatch");
+        if (record.state !== "running")
+            return record;
+        const context = {
+            async step(name, compensationArgs, execute) {
+                throwIfAborted(signal);
+                assertToken(name, "saga step", 128);
+                if (typeof execute !== "function")
+                    throw new TypeError("saga step execute must be a function");
+                if (typeof definition.compensators[name] !== "function")
+                    throw new TypeError(`saga step ${name} has no compensator`);
+                record = await load(sagaId);
+                const existingIndex = record.steps.findIndex((step) => step.name === name);
+                if (existingIndex >= 0) {
+                    const existing = record.steps[existingIndex];
+                    if (existing.state === "committed")
+                        return cloneValue(existing.result);
+                    if (existing.state === "executing" || existing.state === "ambiguous") {
+                        if (record.state !== "manual-review")
+                            record = await save(record, { ...record, state: "manual-review", updatedAt: now() });
+                        throw new SagaAmbiguousStepError(sagaId, name, existing.effectId);
+                    }
+                    throw new Error(`saga ${sagaId}: step ${name} cannot resume from ${existing.state}`);
+                }
+                const effectId = crypto.randomUUID();
+                const step = Object.freeze({
+                    name,
+                    effectId,
+                    compensationEffectId: crypto.randomUUID(),
+                    state: "executing",
+                    compensationArgs: cloneValue(compensationArgs),
+                    attempts: 0,
+                });
+                return await effectScope.run({
+                    effectId,
+                    capability: definition.capability ?? "saga.execute",
+                    stage: "execution",
+                    signal,
+                    failurePhase: (error) => error instanceof SagaStepNotCommittedError ? "failed" : "ambiguous",
+                    errorCode: (error, began) => error instanceof SagaStepNotCommittedError
+                        ? error.code
+                        : began
+                            ? "execution_unknown"
+                            : "aborted_before_execution",
+                    transitions: {
+                        async intent() {
+                            record = await save(record, {
+                                ...record,
+                                steps: Object.freeze([...record.steps, step]),
+                                updatedAt: now(),
+                            });
+                        },
+                        async committed(_owned, result) {
+                            record = await load(sagaId);
+                            const index = record.steps.findIndex((candidate) => candidate.effectId === effectId);
+                            const committed = {
+                                ...record.steps[index],
+                                state: "committed",
+                                result: cloneValue(result),
+                            };
+                            record = await save(record, withStep(record, index, committed));
+                        },
+                        async failed(_owned, failure) {
+                            record = await load(sagaId);
+                            const index = record.steps.findIndex((candidate) => candidate.effectId === effectId);
+                            const known = failure.error instanceof SagaStepNotCommittedError || !failure.began;
+                            const failed = {
+                                ...record.steps[index],
+                                state: known ? "failed" : "ambiguous",
+                                errorCode: failure.error instanceof SagaStepNotCommittedError
+                                    ? failure.error.code
+                                    : failure.began
+                                        ? "execution_unknown"
+                                        : "aborted_before_execution",
+                            };
+                            record = await save(record, withStep(record, index, failed, known ? "compensating" : "manual-review"));
+                        },
+                    },
+                }, (owned) => execute({ effectId: owned.effectId, signal: owned.signal }));
+            },
+        };
+        try {
+            throwIfAborted(signal);
+            await definition.run(context, cloneValue(record.input));
+            record = await load(sagaId);
+            if (record.state === "running")
+                record = await save(record, { ...record, state: "completed", updatedAt: now() });
+            return record;
+        }
+        catch (error) {
+            record = await load(sagaId);
+            if (record.state === "manual-review")
+                throw error;
+            await compensate(definition, sagaId, runOptions);
+            throw error;
+        }
+    };
+    const resolveAmbiguity = async (definition, sagaId, resolution) => {
+        assertSagaDefinition(definition);
+        assertToken(sagaId, "saga id", 128);
+        if (typeof resolution !== "object" || resolution === null)
+            throw new TypeError("saga resolution must be an object");
+        if ((resolution.kind === "execution" &&
+            resolution.outcome !== "committed" &&
+            resolution.outcome !== "not-committed") ||
+            (resolution.kind === "compensation" &&
+                resolution.outcome !== "compensated" &&
+                resolution.outcome !== "not-compensated") ||
+            (resolution.kind !== "execution" && resolution.kind !== "compensation")) {
+            throw new TypeError("saga resolution kind or outcome is invalid");
+        }
+        assertToken(resolution.step, "saga resolution step", 128);
+        assertToken(resolution.effectId, "saga resolution effect id", 64);
+        let record = await load(sagaId);
+        if (record.definition !== definition.name)
+            throw new TypeError("saga definition mismatch");
+        const index = record.steps.findIndex((step) => step.name === resolution.step);
+        if (index < 0)
+            throw new SagaResolutionError(sagaId, resolution.step, "does not exist");
+        const current = record.steps[index];
+        let step;
+        let state;
+        if (resolution.kind === "execution") {
+            if (current.effectId !== resolution.effectId)
+                throw new SagaResolutionError(sagaId, resolution.step, "execution effect id does not match");
+            if (current.state !== "executing" && current.state !== "ambiguous")
+                throw new SagaResolutionError(sagaId, resolution.step, `is not awaiting an execution resolution (${current.state})`);
+            const { errorCode: _errorCode, result: _result, ...base } = current;
+            if (resolution.outcome === "committed") {
+                step = { ...base, state: "committed", result: cloneValue(resolution.result) };
+                state = "running";
+            }
+            else {
+                const errorCode = resolution.errorCode ?? "not_committed";
+                if (!ERROR_CODE.test(errorCode))
+                    throw new TypeError("saga resolution errorCode is invalid");
+                step = { ...base, state: "failed", errorCode };
+                state = "compensating";
+            }
+        }
+        else {
+            if (current.compensationEffectId !== resolution.effectId)
+                throw new SagaResolutionError(sagaId, resolution.step, "compensation effect id does not match");
+            if (current.state !== "compensating")
+                throw new SagaResolutionError(sagaId, resolution.step, `is not awaiting a compensation resolution (${current.state})`);
+            const { errorCode: _errorCode, nextAttemptAt: _nextAttemptAt, ...base } = current;
+            step = {
+                ...base,
+                state: resolution.outcome === "compensated" ? "compensated" : "compensation-failed",
+            };
+            state =
+                resolution.outcome === "not-compensated" &&
+                    current.attempts >= (definition.retry?.maxAttempts ?? 3)
+                    ? "manual-review"
+                    : "compensating";
+        }
+        record = await save(record, withStep(record, index, Object.freeze(step), state));
+        return record;
+    };
+    const engine = {
+        async execute(definition, sagaId, input, runOptions = {}) {
+            assertSagaDefinition(definition);
+            assertToken(sagaId, "saga id", 128);
+            throwIfAborted(signalOrNever(runOptions.signal));
+            const at = now();
+            const accepted = await options.store.create(Object.freeze({
+                sagaId,
+                definition: definition.name,
+                state: "running",
+                input: cloneValue(input),
+                steps: Object.freeze([]),
+                createdAt: at,
+                updatedAt: at,
+                version: 1,
+            }));
+            if (!accepted)
+                throw new Error(`saga ${sagaId}: already exists`);
+            return await resume(definition, sagaId, runOptions);
+        },
+        resume,
+        compensate,
+        resolveAmbiguity,
+    };
+    return Object.freeze(engine);
+}
+export class MemorySagaStore {
+    durability = "memory";
+    records = new Map();
+    // Secondary index: sagaIds grouped by state, so reconciliation scans only the requested (few,
+    // non-terminal) states instead of walking every retained record. See {@link indexedScan}.
+    byState = new Map();
+    create(record) {
+        if (this.records.has(record.sagaId))
+            return false;
+        this.records.set(record.sagaId, Object.freeze(cloneValue(record)));
+        bucketAdd(this.byState, record.state, record.sagaId);
+        return true;
+    }
+    get(sagaId) {
+        const record = this.records.get(sagaId);
+        return record === undefined ? undefined : Object.freeze(cloneValue(record));
+    }
+    compareAndSet(input) {
+        const current = this.records.get(input.sagaId);
+        if (current === undefined ||
+            current.version !== input.version ||
+            input.record.version !== input.version + 1)
+            return false;
+        this.records.set(input.sagaId, Object.freeze(cloneValue(input.record)));
+        bucketMove(this.byState, current.state, input.record.state, input.sagaId);
+        return true;
+    }
+    list() {
+        return Object.freeze([...this.records.values()].map((record) => Object.freeze(cloneValue(record))));
+    }
+    scan(input) {
+        return indexedScan(this.byState, (id) => this.records.get(id), input);
+    }
+}
+async function scanSagaRecords(store, input) {
+    if (store.scan !== undefined)
+        return await store.scan(input);
+    if (store.list === undefined)
+        throw new TypeError("saga store does not support reconciliation");
+    return memoryScan(await store.list(), input);
+}
+export async function reconcileSagasPage(store, options) {
+    const findings = [];
+    const page = await scanSagaRecords(store, {
+        states: ["running", "compensating", "manual-review"],
+        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+        limit: reconciliationLimit(options.limit),
+    });
+    for (const record of page.records) {
+        const ambiguous = record.steps.find((step) => step.state === "executing" || step.state === "ambiguous" || step.state === "compensating");
+        if (ambiguous !== undefined) {
+            findings.push(Object.freeze({
+                sagaId: record.sagaId,
+                state: record.state,
+                step: ambiguous.name,
+                effectId: ambiguous.state === "compensating"
+                    ? ambiguous.compensationEffectId
+                    : ambiguous.effectId,
+                reason: ambiguous.state === "compensating" ? "ambiguous-compensation" : "ambiguous-execution",
+            }));
+        }
+        else if (record.state === "manual-review") {
+            findings.push(Object.freeze({ sagaId: record.sagaId, state: record.state, reason: "manual-review" }));
+        }
+        else if ((record.state === "running" || record.state === "compensating") &&
+            record.updatedAt <= options.staleBefore) {
+            findings.push(Object.freeze({ sagaId: record.sagaId, state: record.state, reason: "stale-running" }));
+        }
+    }
+    return Object.freeze({
+        findings: Object.freeze(findings),
+        ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+    });
+}
+export async function reconcileSagas(store, options) {
+    const page = await reconcileSagasPage(store, {
+        ...options,
+        limit: MAX_RECONCILIATION_LIMIT,
+    });
+    if (page.cursor !== undefined) {
+        throw new RangeError(`saga reconciliation exceeds ${MAX_RECONCILIATION_LIMIT} records; use reconcileSagasPage()`);
+    }
+    return page.findings;
+}
+//# sourceMappingURL=durable-execution.js.map