@qitqode/qitqore 0.1.0 → 0.2.0

package/dist/recovery-lease.js

@@ -0,0 +1,257 @@
+/**
+ * Qortex's recovery lease wire contract: the control envelope a host sends to
+ * bound additional work, and the usage projection Qortex returns for it.
+ * QitQore parses and encodes these values only. Hosts allocate token budgets,
+ * persist leases, authorize replay, and settle outcomes.
+ */
+/** Request header that carries a base64url-encoded control envelope to Qortex. */
+export const QORTEX_RECOVERY_CONTROL_HEADER = "x-qitqode-recovery-control";
+/** Maximum additional-work tokens in one lease, matching Qortex's public limit. */
+export const MAX_RECOVERY_ADDITIONAL_WORK = 12;
+/** Longest root-operation window Qortex will honor for one dispatch. */
+export const MAX_RECOVERY_ROOT_REMAINING_MS = 15 * 60 * 1_000;
+const MAX_RECOVERY_CONTROL_HEADER_LENGTH = 16_384;
+const MAX_IDENTIFIER_LENGTH = 256;
+const MAX_STAGE_LENGTH = 128;
+const HEADER_VALUE = /^[A-Za-z0-9_-]+$/;
+const RECOVERY_ACTIONS = new Set([
+    "initial_dispatch",
+    "retry_same_work",
+    "changed_approach",
+    "continuation",
+    "compaction",
+    "worker",
+    "reconciliation",
+]);
+const CONSUMED_WORK_ACTIONS = new Set([
+    "retry_same_work",
+    "changed_approach",
+    "continuation",
+    "compaction",
+    "worker",
+    "reconciliation",
+]);
+const USAGE_FIELDS = new Set([
+    "contractVersion",
+    "leaseID",
+    "publicOperationID",
+    "operationGeneration",
+    "workID",
+    "attemptID",
+    "requestID",
+    "routeID",
+    "consumed",
+    "unusedTokenIDs",
+]);
+const CONSUMED_FIELDS = new Set(["tokenID", "action", "stage"]);
+const ENVELOPE_FIELDS = new Set(["contractVersion", "operation", "lease"]);
+const OPERATION_FIELDS = new Set([
+    "contractVersion",
+    "publicOperationID",
+    "operationGeneration",
+    "workID",
+    "attemptID",
+    "parentWorkID",
+    "action",
+    "rootDeadlineAt",
+    "rootRemainingMsAtDispatch",
+    "claimID",
+    "leaseID",
+    "policyVersion",
+]);
+const LEASE_FIELDS = new Set(["leaseID", "tokenIDs"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertKnownFields(value, allowed, label) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new TypeError(`Qortex ${label} contains an unsupported field`);
+    }
+}
+function boundedString(value, label, maxLength) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+        throw new TypeError(`Qortex ${label} has an invalid identifier`);
+    }
+    return value;
+}
+function nonnegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`Qortex ${label} must be a non-negative integer`);
+    }
+    return value;
+}
+function uniqueTokenIDs(tokenIDs, label) {
+    if (tokenIDs.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError(`Qortex ${label} exceeds the additional-work limit`);
+    }
+    if (new Set(tokenIDs).size !== tokenIDs.length) {
+        throw new TypeError(`Qortex ${label} token IDs must be unique`);
+    }
+    return tokenIDs;
+}
+function tokenIDList(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError(`Qortex ${label} has an invalid token list`);
+    }
+    return value.map((item) => boundedString(item, label, MAX_IDENTIFIER_LENGTH));
+}
+/**
+ * Parse Qortex's lease usage projection. Every identity and token is bounded,
+ * token IDs must be unique across consumed and unused work, and unknown fields
+ * are rejected rather than forwarded.
+ */
+export function parseRecoveryLeaseUsage(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery lease usage must be an object");
+    assertKnownFields(value, USAGE_FIELDS, "recovery lease usage");
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery lease usage uses an unsupported contract version");
+    }
+    if (!Array.isArray(value.consumed) || value.consumed.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError("Qortex recovery lease usage has an invalid consumed list");
+    }
+    const consumed = value.consumed.map((item) => {
+        if (!isRecord(item))
+            throw new TypeError("Qortex recovery lease usage has an invalid consumed entry");
+        assertKnownFields(item, CONSUMED_FIELDS, "recovery lease usage consumed entry");
+        if (typeof item.action !== "string" || !CONSUMED_WORK_ACTIONS.has(item.action)) {
+            throw new TypeError("Qortex recovery lease usage has an invalid consumed action");
+        }
+        return {
+            tokenID: boundedString(item.tokenID, "recovery lease usage tokenID", MAX_IDENTIFIER_LENGTH),
+            action: item.action,
+            stage: boundedString(item.stage, "recovery lease usage stage", MAX_STAGE_LENGTH),
+        };
+    });
+    const unusedTokenIDs = tokenIDList(value.unusedTokenIDs, "recovery lease usage unusedTokenIDs");
+    uniqueTokenIDs([...consumed.map((item) => item.tokenID), ...unusedTokenIDs], "recovery lease usage");
+    return {
+        contractVersion: 1,
+        leaseID: boundedString(value.leaseID, "recovery lease usage leaseID", MAX_IDENTIFIER_LENGTH),
+        publicOperationID: boundedString(value.publicOperationID, "recovery lease usage publicOperationID", MAX_IDENTIFIER_LENGTH),
+        operationGeneration: nonnegativeInteger(value.operationGeneration, "recovery lease usage operationGeneration"),
+        workID: boundedString(value.workID, "recovery lease usage workID", MAX_IDENTIFIER_LENGTH),
+        attemptID: boundedString(value.attemptID, "recovery lease usage attemptID", MAX_IDENTIFIER_LENGTH),
+        requestID: boundedString(value.requestID, "recovery lease usage requestID", MAX_IDENTIFIER_LENGTH),
+        routeID: boundedString(value.routeID, "recovery lease usage routeID", MAX_IDENTIFIER_LENGTH),
+        consumed,
+        unusedTokenIDs,
+    };
+}
+/**
+ * Validate a control envelope before it is sent. The operation's lease ID must
+ * name the same lease as the token list, and the list stays within Qortex's
+ * additional-work limit.
+ */
+export function parseRecoveryControlEnvelope(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery control must be an object");
+    assertKnownFields(value, ENVELOPE_FIELDS, "recovery control");
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery control uses an unsupported contract version");
+    }
+    if (!isRecord(value.operation))
+        throw new TypeError("Qortex recovery control operation must be an object");
+    const operation = value.operation;
+    assertKnownFields(operation, OPERATION_FIELDS, "recovery control operation");
+    if (operation.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery control operation uses an unsupported contract version");
+    }
+    if (typeof operation.action !== "string" || !RECOVERY_ACTIONS.has(operation.action)) {
+        throw new TypeError("Qortex recovery control operation has an invalid action");
+    }
+    if (typeof operation.rootDeadlineAt !== "number" ||
+        !Number.isFinite(operation.rootDeadlineAt) ||
+        operation.rootDeadlineAt <= 0) {
+        throw new TypeError("Qortex recovery control operation has an invalid rootDeadlineAt");
+    }
+    if (typeof operation.rootRemainingMsAtDispatch !== "number" ||
+        !Number.isFinite(operation.rootRemainingMsAtDispatch) ||
+        operation.rootRemainingMsAtDispatch < 0 ||
+        operation.rootRemainingMsAtDispatch > MAX_RECOVERY_ROOT_REMAINING_MS) {
+        throw new TypeError("Qortex recovery control operation has an invalid rootRemainingMsAtDispatch");
+    }
+    if (!isRecord(value.lease))
+        throw new TypeError("Qortex recovery control lease must be an object");
+    assertKnownFields(value.lease, LEASE_FIELDS, "recovery control lease");
+    const leaseID = boundedString(value.lease.leaseID, "recovery control leaseID", MAX_IDENTIFIER_LENGTH);
+    const operationLeaseID = boundedString(operation.leaseID, "recovery control operation leaseID", MAX_IDENTIFIER_LENGTH);
+    if (operationLeaseID !== leaseID) {
+        throw new TypeError("Qortex recovery control lease ID must match the operation");
+    }
+    const tokenIDs = uniqueTokenIDs(tokenIDList(value.lease.tokenIDs, "recovery control tokenIDs"), "recovery control");
+    return {
+        contractVersion: 1,
+        operation: {
+            contractVersion: 1,
+            publicOperationID: boundedString(operation.publicOperationID, "recovery control publicOperationID", MAX_IDENTIFIER_LENGTH),
+            operationGeneration: nonnegativeInteger(operation.operationGeneration, "recovery control operationGeneration"),
+            workID: boundedString(operation.workID, "recovery control workID", MAX_IDENTIFIER_LENGTH),
+            attemptID: boundedString(operation.attemptID, "recovery control attemptID", MAX_IDENTIFIER_LENGTH),
+            ...(operation.parentWorkID === undefined
+                ? {}
+                : { parentWorkID: boundedString(operation.parentWorkID, "recovery control parentWorkID", MAX_IDENTIFIER_LENGTH) }),
+            action: operation.action,
+            rootDeadlineAt: operation.rootDeadlineAt,
+            rootRemainingMsAtDispatch: operation.rootRemainingMsAtDispatch,
+            ...(operation.claimID === undefined
+                ? {}
+                : { claimID: boundedString(operation.claimID, "recovery control claimID", MAX_IDENTIFIER_LENGTH) }),
+            leaseID,
+            ...(operation.policyVersion === undefined
+                ? {}
+                : { policyVersion: boundedString(operation.policyVersion, "recovery control policyVersion", MAX_IDENTIFIER_LENGTH) }),
+        },
+        lease: { leaseID, tokenIDs },
+    };
+}
+function base64UrlEncode(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/**
+ * Encode a validated control envelope as the base64url header value Qortex
+ * expects. Parser bounds keep every valid envelope under the header size limit.
+ */
+export function encodeRecoveryControlEnvelope(value) {
+    return base64UrlEncode(JSON.stringify(parseRecoveryControlEnvelope(value)));
+}
+/**
+ * Decode a recovery-control header value. The encoding must be canonical base64url
+ * so that a value cannot be accepted by one parser and rewritten by another.
+ */
+export function decodeRecoveryControlHeader(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_RECOVERY_CONTROL_HEADER_LENGTH ||
+        !HEADER_VALUE.test(value)) {
+        throw new TypeError("Qortex recovery control header is invalid");
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(base64UrlDecode(value));
+    }
+    catch {
+        throw new TypeError("Qortex recovery control header is invalid");
+    }
+    const envelope = parseRecoveryControlEnvelope(decoded);
+    if (base64UrlEncode(JSON.stringify(envelope)) !== value) {
+        throw new TypeError("Qortex recovery control header is not canonically encoded");
+    }
+    return envelope;
+}
+/** Return a copy of request headers that carries a validated recovery-control envelope. */
+export function withRecoveryControlHeader(headers, control) {
+    return { ...headers, [QORTEX_RECOVERY_CONTROL_HEADER]: encodeRecoveryControlEnvelope(control) };
+}
+//# sourceMappingURL=recovery-lease.js.map

package/dist/recovery-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-lease.js","sourceRoot":"","sources":["../src/recovery-lease.ts"],"names":[],"mappings":"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"}

package/dist/recovery-status.d.ts

@@ -0,0 +1,22 @@
+import { type QortexRecoveryLeaseUsage } from "./recovery-lease.js";
+export type QortexExecutionState = "not_started" | "running" | "succeeded" | "failed" | "unknown";
+export type QortexResultRecovery = "replayable" | "pending" | "expired" | "unsupported";
+export interface QortexRecoveryStatus {
+    contractVersion: 1;
+    requestID: string;
+    scope: "qortex_route";
+    executionState: QortexExecutionState;
+    resultRecovery: QortexResultRecovery;
+    replayUntil?: number;
+    routeID?: string;
+    /** Qortex's usage report for a lease it issued; it must name this request and route. */
+    recoveryLeaseUsage?: QortexRecoveryLeaseUsage;
+    lastUpdatedAt: number;
+}
+/**
+ * Parse Qortex's owner-scoped recovery projection. The parser accepts either
+ * the route's top-level success envelope or the standard `{ success, data }`
+ * wrapper, but it never forwards unrecognized fields to callers.
+ */
+export declare function parseRecoveryStatus(value: unknown, expectedRequestID?: string): QortexRecoveryStatus;
+//# sourceMappingURL=recovery-status.d.ts.map

package/dist/recovery-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-status.d.ts","sourceRoot":"","sources":["../src/recovery-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,SAAS,GACT,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,SAAS,GACT,SAAS,GACT,aAAa,CAAC;AAElB,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,CAAC,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,cAAc,EAAE,oBAAoB,CAAC;IACrC,cAAc,EAAE,oBAAoB,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB;AA8CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,iBAAiB,CAAC,EAAE,MAAM,GACzB,oBAAoB,CAyEtB"}

package/dist/recovery-status.js

@@ -0,0 +1,113 @@
+import { parseRecoveryLeaseUsage } from "./recovery-lease.js";
+const EXECUTION_STATES = new Set([
+    "not_started",
+    "running",
+    "succeeded",
+    "failed",
+    "unknown",
+]);
+const RESULT_RECOVERY_STATES = new Set([
+    "replayable",
+    "pending",
+    "expired",
+    "unsupported",
+]);
+const ALLOWED_FIELDS = new Set([
+    "contractVersion",
+    "requestID",
+    "scope",
+    "executionState",
+    "resultRecovery",
+    "replayUntil",
+    "routeID",
+    "recoveryLeaseUsage",
+    "lastUpdatedAt",
+    "success",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boundedString(value, field, maxLength) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+        throw new TypeError(`Qortex recovery status has an invalid ${field}`);
+    }
+    return value;
+}
+function epoch(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`Qortex recovery status has an invalid ${field}`);
+    }
+    return value;
+}
+/**
+ * Parse Qortex's owner-scoped recovery projection. The parser accepts either
+ * the route's top-level success envelope or the standard `{ success, data }`
+ * wrapper, but it never forwards unrecognized fields to callers.
+ */
+export function parseRecoveryStatus(value, expectedRequestID) {
+    if (!isRecord(value)) {
+        throw new TypeError("Qortex recovery status must be an object");
+    }
+    let candidate = value;
+    if (value.success === true && Object.hasOwn(value, "data")) {
+        candidate = value.data;
+    }
+    if (!isRecord(candidate)) {
+        throw new TypeError("Qortex recovery status data must be an object");
+    }
+    for (const key of Object.keys(candidate)) {
+        if (!ALLOWED_FIELDS.has(key)) {
+            throw new TypeError("Qortex recovery status contains an unsupported field");
+        }
+    }
+    if (candidate.success !== undefined && candidate.success !== true) {
+        throw new TypeError("Qortex recovery status has an invalid success marker");
+    }
+    if (candidate.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery status uses an unsupported contract version");
+    }
+    const requestID = boundedString(candidate.requestID, "requestID", 256);
+    if (expectedRequestID !== undefined && requestID !== expectedRequestID) {
+        throw new TypeError("Qortex recovery status requestID does not match the lookup");
+    }
+    if (candidate.scope !== "qortex_route") {
+        throw new TypeError("Qortex recovery status has an unsupported scope");
+    }
+    if (typeof candidate.executionState !== "string" || !EXECUTION_STATES.has(candidate.executionState)) {
+        throw new TypeError("Qortex recovery status has an invalid executionState");
+    }
+    if (typeof candidate.resultRecovery !== "string" || !RESULT_RECOVERY_STATES.has(candidate.resultRecovery)) {
+        throw new TypeError("Qortex recovery status has an invalid resultRecovery");
+    }
+    const replayUntil = candidate.replayUntil === undefined
+        ? undefined
+        : epoch(candidate.replayUntil, "replayUntil");
+    const routeID = candidate.routeID === undefined
+        ? undefined
+        : boundedString(candidate.routeID, "routeID", 256);
+    const recoveryLeaseUsage = candidate.recoveryLeaseUsage === undefined
+        ? undefined
+        : parseRecoveryLeaseUsage(candidate.recoveryLeaseUsage);
+    if (recoveryLeaseUsage !== undefined) {
+        // The request must always agree. Qortex's public schema lets the status omit its
+        // route, so the route is compared only when the status names one.
+        if (recoveryLeaseUsage.requestID !== requestID) {
+            throw new TypeError("Qortex recovery status lease usage does not match the request");
+        }
+        if (routeID !== undefined && recoveryLeaseUsage.routeID !== routeID) {
+            throw new TypeError("Qortex recovery status lease usage does not match the route");
+        }
+    }
+    return {
+        contractVersion: 1,
+        requestID,
+        scope: "qortex_route",
+        executionState: candidate.executionState,
+        resultRecovery: candidate.resultRecovery,
+        ...(replayUntil === undefined ? {} : { replayUntil }),
+        ...(routeID === undefined ? {} : { routeID }),
+        ...(recoveryLeaseUsage === undefined ? {} : { recoveryLeaseUsage }),
+        lastUpdatedAt: epoch(candidate.lastUpdatedAt, "lastUpdatedAt"),
+    };
+}
+//# sourceMappingURL=recovery-status.js.map

package/dist/recovery-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-status.js","sourceRoot":"","sources":["../src/recovery-status.ts"],"names":[],"mappings":"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"}

package/dist/recovery.d.ts

@@ -21,13 +21,26 @@ export interface ReplayAuthorizationContext {
     readonly outcome: Readonly<AttemptOutcome>;
     readonly signal?: AbortSignal;
 }
+export interface RecoveryAttemptOutcomeContext {
+    readonly operationId: string;
+    readonly attempt: number;
+    readonly outcome: Readonly<AttemptOutcome>;
+    readonly signal?: AbortSignal;
+    readonly error?: unknown;
+}
 export interface RecoveryOptions<T> {
     operationId: string;
     maxAttempts: number;
     signal?: AbortSignal;
+    /** Absolute epoch deadline for the whole logical operation. */
+    deadlineAt?: number;
     execute(context: QortexAttemptContext): Promise<T>;
     shouldRetry(error: unknown, context: ReplayAuthorizationContext): boolean;
     authorizeReplay(context: ReplayAuthorizationContext): boolean | Promise<boolean>;
+    /** Called immediately before an attempt is dispatched. */
+    onAttemptStart?: (context: QortexAttemptContext) => void | Promise<void>;
+    /** Called after an attempt settles, including failed and partially observed attempts. */
+    onAttemptOutcome?: (context: RecoveryAttemptOutcomeContext) => void | Promise<void>;
     backoffMs?: number | ((nextAttempt: number, error: unknown) => number);
 }
 export declare function abortableDelay(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,eAAe,IAAI,IAAI,CAAC;IACxB,YAAY,IAAI,IAAI,CAAC;IACrB,iBAAiB,IAAI,IAAI,CAAC;IAC1B,qBAAqB,IAAI,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnD,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC;IAC1E,eAAe,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;CACxE;AAMD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB9E;AAMD,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAyEhF"}
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,eAAe,IAAI,IAAI,CAAC;IACxB,YAAY,IAAI,IAAI,CAAC;IACrB,iBAAiB,IAAI,IAAI,CAAC;IAC1B,qBAAqB,IAAI,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnD,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC;IAC1E,eAAe,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,0DAA0D;IAC1D,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;CACxE;AAMD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB9E;AAMD,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAiHhF"}

package/dist/recovery.js

@@ -41,66 +41,105 @@ export async function runWithRecovery(options) {
     if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1 || options.maxAttempts > 5) {
         throw new RangeError("maxAttempts must be an integer between 1 and 5");
     }
-    for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
-        if (options.signal?.aborted)
-            throw abortReason(options.signal);
-        const outcome = {
-            acceptance: "unknown",
-            partialOutput: false,
-            sideEffectStarted: false,
-        };
-        const context = {
-            operationId: options.operationId,
-            attempt,
-            ...(options.signal ? { signal: options.signal } : {}),
-            markNotAccepted() {
-                if (outcome.acceptance !== "accepted")
-                    outcome.acceptance = "not-accepted";
-            },
-            markAccepted() {
-                outcome.acceptance = "accepted";
-            },
-            markPartialOutput() {
-                outcome.partialOutput = true;
-            },
-            markSideEffectStarted() {
-                outcome.sideEffectStarted = true;
-            },
-        };
-        try {
-            return await options.execute(context);
-        }
-        catch (error) {
-            if (options.signal?.aborted)
-                throw abortReason(options.signal);
-            if (attempt >= options.maxAttempts)
-                throw error;
-            const replayContext = Object.freeze({
+    if (options.deadlineAt !== undefined && (!Number.isFinite(options.deadlineAt) || options.deadlineAt <= 0)) {
+        throw new RangeError("deadlineAt must be a positive finite epoch timestamp");
+    }
+    if (options.deadlineAt !== undefined && options.deadlineAt <= Date.now()) {
+        throw new Error("The recovery operation deadline expired");
+    }
+    const deadlineController = options.deadlineAt === undefined ? undefined : new AbortController();
+    const deadlineTimer = deadlineController
+        ? setTimeout(() => deadlineController.abort(new Error("The recovery operation deadline expired")), Math.max(0, options.deadlineAt - Date.now()))
+        : undefined;
+    const signal = deadlineController
+        ? AbortSignal.any([...(options.signal ? [options.signal] : []), deadlineController.signal])
+        : options.signal;
+    try {
+        for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+            if (signal?.aborted)
+                throw abortReason(signal);
+            const outcome = {
+                acceptance: "unknown",
+                partialOutput: false,
+                sideEffectStarted: false,
+            };
+            const context = {
                 operationId: options.operationId,
                 attempt,
-                nextAttempt: attempt + 1,
-                error,
-                outcome: snapshot(outcome),
-                ...(options.signal ? { signal: options.signal } : {}),
-            });
-            if (options.shouldRetry(error, replayContext) !== true)
-                throw error;
-            if (outcome.acceptance === "accepted" ||
-                outcome.partialOutput ||
-                outcome.sideEffectStarted) {
-                throw error;
+                ...(signal ? { signal } : {}),
+                markNotAccepted() {
+                    if (outcome.acceptance !== "accepted")
+                        outcome.acceptance = "not-accepted";
+                },
+                markAccepted() {
+                    outcome.acceptance = "accepted";
+                },
+                markPartialOutput() {
+                    outcome.partialOutput = true;
+                },
+                markSideEffectStarted() {
+                    outcome.sideEffectStarted = true;
+                },
+            };
+            try {
+                if (options.onAttemptStart)
+                    await options.onAttemptStart(context);
+                const result = await options.execute(context);
+                if (options.onAttemptOutcome) {
+                    await options.onAttemptOutcome(Object.freeze({
+                        operationId: options.operationId,
+                        attempt,
+                        outcome: snapshot(outcome),
+                        ...(signal ? { signal } : {}),
+                    }));
+                }
+                return result;
+            }
+            catch (error) {
+                if (options.onAttemptOutcome) {
+                    await options.onAttemptOutcome(Object.freeze({
+                        operationId: options.operationId,
+                        attempt,
+                        outcome: snapshot(outcome),
+                        ...(signal ? { signal } : {}),
+                        error,
+                    }));
+                }
+                if (signal?.aborted)
+                    throw abortReason(signal);
+                if (attempt >= options.maxAttempts)
+                    throw error;
+                const replayContext = Object.freeze({
+                    operationId: options.operationId,
+                    attempt,
+                    nextAttempt: attempt + 1,
+                    error,
+                    outcome: snapshot(outcome),
+                    ...(signal ? { signal } : {}),
+                });
+                if (options.shouldRetry(error, replayContext) !== true)
+                    throw error;
+                if (outcome.acceptance === "accepted" ||
+                    outcome.partialOutput ||
+                    outcome.sideEffectStarted) {
+                    throw error;
+                }
+                if ((await options.authorizeReplay(replayContext)) !== true)
+                    throw error;
+                if (signal?.aborted)
+                    throw abortReason(signal);
+                const configuredDelay = typeof options.backoffMs === "function"
+                    ? options.backoffMs(attempt + 1, error)
+                    : options.backoffMs ?? 0;
+                const delay = Math.min(30_000, Math.max(0, configuredDelay));
+                await abortableDelay(delay, signal);
             }
-            if ((await options.authorizeReplay(replayContext)) !== true)
-                throw error;
-            if (options.signal?.aborted)
-                throw abortReason(options.signal);
-            const configuredDelay = typeof options.backoffMs === "function"
-                ? options.backoffMs(attempt + 1, error)
-                : options.backoffMs ?? 0;
-            const delay = Math.min(30_000, Math.max(0, configuredDelay));
-            await abortableDelay(delay, options.signal);
         }
     }
+    finally {
+        if (deadlineTimer !== undefined)
+            clearTimeout(deadlineTimer);
+    }
     throw new Error("Unreachable recovery state");
 }
 //# sourceMappingURL=recovery.js.map