actly 1.1.0 → 1.1.5

package/dist/policies/dedupe.cjs

@@ -2,37 +2,85 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dedupePolicy = dedupePolicy;
 const executor_js_1 = require("../core/executor.js");
-// Namespace so dedupe keys never collide with cache keys in the shared store
+const abort_js_1 = require("../utils/abort.js");
+// Namespace so dedupe keys never collide with cache keys in the shared store.
 const NS = 'dedupe:';
 /**
- * Collapses concurrent calls that share the same key into one in-flight Promise.
+ * Collapse concurrent calls that share the same key into one in-flight Promise.
  *
- * The first caller starts the work. Every subsequent caller that arrives before
- * the first resolves gets the same Promise back — no duplicate work.
+ * # How it works
  *
- * INVARIANT: requires a SyncStateStore — see stores/base.ts.
- * The read-then-write that makes deduplication work must happen in a single
- * synchronous frame. An async store would introduce an await between get() and
- * set(), letting two concurrent callers both see a miss and both launch work.
- * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
- * enforce this at runtime for JS callers that bypass TypeScript.
+ * The first caller (originator) starts the work and stores
+ * `{ promise, meta }` in the store under `dedupe:<key>`. Every subsequent
+ * caller that arrives before the promise settles receives the SAME promise
+ * — no duplicate work.
+ *
+ * # Shared `meta` (fixes v1.0 trade-off)
+ *
+ * The originator's `ctx.meta` reference is stored alongside the promise.
+ * Inner policies (e.g. `retryPolicy`) mutate it as they run. After the
+ * promise settles, joiners copy `attempts` and `source` from the shared
+ * meta into their own `ctx.meta`. This means a joiner's `ActResult.attempts`
+ * reflects the real effort (e.g. `3` if the originator retried twice), not
+ * the misleading default of `1`.
+ *
+ * # Abort safety (fixes hung-fn block)
  *
- * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
- * the retry counter belongs to the originating call's meta object.
+ * Joiners race the in-flight promise against their own AbortSignal via
+ * `raceAbort`. If a joiner's signal aborts (e.g. their `totalTimeout`
+ * fires), they reject immediately — they don't have to wait for the
+ * originator to finish. The originator's promise continues in the
+ * background for any other joiners that haven't aborted.
+ *
+ * If `inflightTtl` is set, the store entry is also TTL'd: if the
+ * originator never settles, new callers can start fresh after the TTL
+ * expires (the original promise still leaks unless an outer timeout
+ * fires, but new callers aren't blocked).
+ *
+ * # INVARIANT: requires SyncStateStore
+ *
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an `await` between
+ * `get()` and `set()`, letting two concurrent callers both see a miss and
+ * both launch work. The `REQUIRES_SYNC_STORE` symbol on the returned
+ * `PolicyApplier` lets `execute()` enforce this at runtime for JS callers
+ * that bypass TypeScript.
  */
-function dedupePolicy() {
+function dedupePolicy(opts = { enabled: true }) {
+    const inflightTtl = opts.inflightTtl;
     const applier = (fn, ctx) => {
         // Cast is safe: execute() verifies isSyncStore(ctx.store) before calling
         // any policy tagged with REQUIRES_SYNC_STORE.
         const syncCtx = ctx;
-        return async () => {
+        return async (signal) => {
             const key = NS + syncCtx.key;
-            const inflight = syncCtx.store.get(key);
-            if (inflight)
-                return inflight;
-            // No TTL — .finally() cleans up regardless of outcome
-            const promise = fn().finally(() => syncCtx.store.delete(key));
-            syncCtx.store.set(key, promise);
+            // Fast path: an in-flight promise already exists. Join it.
+            // raceAbort ensures we don't block on a hung originator if our own
+            // signal aborts.
+            const existing = syncCtx.store.get(key);
+            if (existing) {
+                try {
+                    const value = await (0, abort_js_1.raceAbort)(existing.promise, signal);
+                    return value;
+                }
+                finally {
+                    // Copy the originator's final meta into our own, regardless of
+                    // success or failure. By the time `existing.promise` has settled
+                    // (or our signal aborted), the originator's retry loop has set
+                    // the final attempt count.
+                    syncCtx.meta.attempts = existing.meta.attempts;
+                    syncCtx.meta.source = existing.meta.source;
+                }
+            }
+            // Originator path: start the work and publish the promise.
+            //
+            // We race fn against `signal` so that if our own signal aborts while
+            // fn is pending, we reject (and the .finally cleans up the store).
+            // The stored promise is the RACED one — joiners see the same
+            // rejection if they join before cleanup.
+            const promise = (0, abort_js_1.raceAbort)(Promise.resolve(fn(signal)), signal).finally(() => syncCtx.store.delete(key));
+            const entry = { promise, meta: syncCtx.meta };
+            syncCtx.store.set(key, entry, inflightTtl);
             return promise;
         };
     };

package/dist/policies/dedupe.d.ts

@@ -1,19 +1,44 @@
-import type { PolicyApplier } from '../types/index.js';
+import type { PolicyApplier, DedupeOptions } from '../types/index.js';
 /**
- * Collapses concurrent calls that share the same key into one in-flight Promise.
+ * Collapse concurrent calls that share the same key into one in-flight Promise.
  *
- * The first caller starts the work. Every subsequent caller that arrives before
- * the first resolves gets the same Promise back — no duplicate work.
+ * # How it works
  *
- * INVARIANT: requires a SyncStateStore — see stores/base.ts.
- * The read-then-write that makes deduplication work must happen in a single
- * synchronous frame. An async store would introduce an await between get() and
- * set(), letting two concurrent callers both see a miss and both launch work.
- * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
- * enforce this at runtime for JS callers that bypass TypeScript.
+ * The first caller (originator) starts the work and stores
+ * `{ promise, meta }` in the store under `dedupe:<key>`. Every subsequent
+ * caller that arrives before the promise settles receives the SAME promise
+ * — no duplicate work.
+ *
+ * # Shared `meta` (fixes v1.0 trade-off)
+ *
+ * The originator's `ctx.meta` reference is stored alongside the promise.
+ * Inner policies (e.g. `retryPolicy`) mutate it as they run. After the
+ * promise settles, joiners copy `attempts` and `source` from the shared
+ * meta into their own `ctx.meta`. This means a joiner's `ActResult.attempts`
+ * reflects the real effort (e.g. `3` if the originator retried twice), not
+ * the misleading default of `1`.
+ *
+ * # Abort safety (fixes hung-fn block)
  *
- * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
- * the retry counter belongs to the originating call's meta object.
+ * Joiners race the in-flight promise against their own AbortSignal via
+ * `raceAbort`. If a joiner's signal aborts (e.g. their `totalTimeout`
+ * fires), they reject immediately — they don't have to wait for the
+ * originator to finish. The originator's promise continues in the
+ * background for any other joiners that haven't aborted.
+ *
+ * If `inflightTtl` is set, the store entry is also TTL'd: if the
+ * originator never settles, new callers can start fresh after the TTL
+ * expires (the original promise still leaks unless an outer timeout
+ * fires, but new callers aren't blocked).
+ *
+ * # INVARIANT: requires SyncStateStore
+ *
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an `await` between
+ * `get()` and `set()`, letting two concurrent callers both see a miss and
+ * both launch work. The `REQUIRES_SYNC_STORE` symbol on the returned
+ * `PolicyApplier` lets `execute()` enforce this at runtime for JS callers
+ * that bypass TypeScript.
  */
-export declare function dedupePolicy<T>(): PolicyApplier<T>;
+export declare function dedupePolicy<T>(opts?: DedupeOptions): PolicyApplier<T>;
 //# sourceMappingURL=dedupe.d.ts.map

package/dist/policies/dedupe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAY5E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAuBlD"}
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAqB3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,GAAE,aAAiC,GAAG,aAAa,CAAC,CAAC,CAAC,CAkDzF"}

package/dist/policies/dedupe.js

@@ -1,35 +1,83 @@
 import { REQUIRES_SYNC_STORE } from '../core/executor.js';
-// Namespace so dedupe keys never collide with cache keys in the shared store
+import { raceAbort } from '../utils/abort.js';
+// Namespace so dedupe keys never collide with cache keys in the shared store.
 const NS = 'dedupe:';
 /**
- * Collapses concurrent calls that share the same key into one in-flight Promise.
+ * Collapse concurrent calls that share the same key into one in-flight Promise.
  *
- * The first caller starts the work. Every subsequent caller that arrives before
- * the first resolves gets the same Promise back — no duplicate work.
+ * # How it works
  *
- * INVARIANT: requires a SyncStateStore — see stores/base.ts.
- * The read-then-write that makes deduplication work must happen in a single
- * synchronous frame. An async store would introduce an await between get() and
- * set(), letting two concurrent callers both see a miss and both launch work.
- * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
- * enforce this at runtime for JS callers that bypass TypeScript.
+ * The first caller (originator) starts the work and stores
+ * `{ promise, meta }` in the store under `dedupe:<key>`. Every subsequent
+ * caller that arrives before the promise settles receives the SAME promise
+ * — no duplicate work.
+ *
+ * # Shared `meta` (fixes v1.0 trade-off)
+ *
+ * The originator's `ctx.meta` reference is stored alongside the promise.
+ * Inner policies (e.g. `retryPolicy`) mutate it as they run. After the
+ * promise settles, joiners copy `attempts` and `source` from the shared
+ * meta into their own `ctx.meta`. This means a joiner's `ActResult.attempts`
+ * reflects the real effort (e.g. `3` if the originator retried twice), not
+ * the misleading default of `1`.
+ *
+ * # Abort safety (fixes hung-fn block)
  *
- * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
- * the retry counter belongs to the originating call's meta object.
+ * Joiners race the in-flight promise against their own AbortSignal via
+ * `raceAbort`. If a joiner's signal aborts (e.g. their `totalTimeout`
+ * fires), they reject immediately — they don't have to wait for the
+ * originator to finish. The originator's promise continues in the
+ * background for any other joiners that haven't aborted.
+ *
+ * If `inflightTtl` is set, the store entry is also TTL'd: if the
+ * originator never settles, new callers can start fresh after the TTL
+ * expires (the original promise still leaks unless an outer timeout
+ * fires, but new callers aren't blocked).
+ *
+ * # INVARIANT: requires SyncStateStore
+ *
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an `await` between
+ * `get()` and `set()`, letting two concurrent callers both see a miss and
+ * both launch work. The `REQUIRES_SYNC_STORE` symbol on the returned
+ * `PolicyApplier` lets `execute()` enforce this at runtime for JS callers
+ * that bypass TypeScript.
  */
-export function dedupePolicy() {
+export function dedupePolicy(opts = { enabled: true }) {
+    const inflightTtl = opts.inflightTtl;
     const applier = (fn, ctx) => {
         // Cast is safe: execute() verifies isSyncStore(ctx.store) before calling
         // any policy tagged with REQUIRES_SYNC_STORE.
         const syncCtx = ctx;
-        return async () => {
+        return async (signal) => {
             const key = NS + syncCtx.key;
-            const inflight = syncCtx.store.get(key);
-            if (inflight)
-                return inflight;
-            // No TTL — .finally() cleans up regardless of outcome
-            const promise = fn().finally(() => syncCtx.store.delete(key));
-            syncCtx.store.set(key, promise);
+            // Fast path: an in-flight promise already exists. Join it.
+            // raceAbort ensures we don't block on a hung originator if our own
+            // signal aborts.
+            const existing = syncCtx.store.get(key);
+            if (existing) {
+                try {
+                    const value = await raceAbort(existing.promise, signal);
+                    return value;
+                }
+                finally {
+                    // Copy the originator's final meta into our own, regardless of
+                    // success or failure. By the time `existing.promise` has settled
+                    // (or our signal aborted), the originator's retry loop has set
+                    // the final attempt count.
+                    syncCtx.meta.attempts = existing.meta.attempts;
+                    syncCtx.meta.source = existing.meta.source;
+                }
+            }
+            // Originator path: start the work and publish the promise.
+            //
+            // We race fn against `signal` so that if our own signal aborts while
+            // fn is pending, we reject (and the .finally cleans up the store).
+            // The stored promise is the RACED one — joiners see the same
+            // rejection if they join before cleanup.
+            const promise = raceAbort(Promise.resolve(fn(signal)), signal).finally(() => syncCtx.store.delete(key));
+            const entry = { promise, meta: syncCtx.meta };
+            syncCtx.store.set(key, entry, inflightTtl);
             return promise;
         };
     };

package/dist/policies/dedupe.js.map

@@ -1 +1 @@
-{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAEzD,6EAA6E;AAC7E,MAAM,EAAE,GAAG,SAAS,CAAA;AAOpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE;QAC7D,yEAAyE;QACzE,8CAA8C;QAC9C,MAAM,OAAO,GAAG,GAAoB,CAAA;QAEpC,OAAO,KAAK,IAAI,EAAE;YAChB,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAA;YAE5B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,CAAC,CAAA;YACnD,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAA;YAE7B,sDAAsD;YACtD,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;YAC7D,OAAO,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,EAAE,OAAO,CAAC,CAAA;YAC3C,OAAO,OAAO,CAAA;QAChB,CAAC,CAAA;IACH,CAAC,CAGA;IAAC,OAA+D,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAA;IAE7F,OAAO,OAAO,CAAA;AAChB,CAAC"}
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE7C,8EAA8E;AAC9E,MAAM,EAAE,GAAG,SAAS,CAAA;AAepB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,YAAY,CAAI,OAAsB,EAAE,OAAO,EAAE,IAAI,EAAE;IACrE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;IAEpC,MAAM,OAAO,GAAG,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE;QAC7D,yEAAyE;QACzE,8CAA8C;QAC9C,MAAM,OAAO,GAAG,GAAoB,CAAA;QAEpC,OAAO,KAAK,EAAE,MAAmB,EAAE,EAAE;YACnC,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAA;YAE5B,2DAA2D;YAC3D,mEAAmE;YACnE,iBAAiB;YACjB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAiB,GAAG,CAAC,CAAA;YACvD,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;oBACvD,OAAO,KAAK,CAAA;gBACd,CAAC;wBAAS,CAAC;oBACT,+DAA+D;oBAC/D,iEAAiE;oBACjE,+DAA+D;oBAC/D,2BAA2B;oBAC3B,OAAO,CAAC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAA;oBAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,GAAK,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAA;gBAC9C,CAAC;YACH,CAAC;YAED,2DAA2D;YAC3D,EAAE;YACF,qEAAqE;YACrE,mEAAmE;YACnE,6DAA6D;YAC7D,yCAAyC;YACzC,MAAM,OAAO,GAAG,SAAS,CACvB,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAC3B,MAAM,CACP,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;YAE1C,MAAM,KAAK,GAAmB,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;YAC7D,OAAO,CAAC,KAAK,CAAC,GAAG,CAAiB,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,CAAA;YAC1D,OAAO,OAAO,CAAA;QAChB,CAAC,CAAA;IACH,CAAC,CAGA;IAAC,OAA+D,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAA;IAE7F,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/policies/retry.cjs

@@ -1,47 +1,87 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryPolicy = retryPolicy;
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function computeDelay(attempt, opts) {
-    const base = opts.delayMs ?? 0;
-    if (base === 0)
-        return 0;
-    switch (opts.backoff ?? 'none') {
-        case 'linear': return base * attempt;
-        case 'exponential': return base * 2 ** (attempt - 1);
-        default: return base;
-    }
+const backoff_js_1 = require("../utils/backoff.js");
+const abort_js_1 = require("../utils/abort.js");
+// ─── Default predicate ────────────────────────────────────────────────────────
+/**
+ * Default `shouldRetry`: retry on any error EXCEPT abort errors.
+ *
+ * Abort errors indicate the caller or a timeout cancelled the operation —
+ * retrying would just abort again on the next attempt, wasting delay budget.
+ *
+ * User-supplied `shouldRetry` overrides this entirely.
+ */
+function defaultShouldRetry(error, _attempt) {
+    return !(0, abort_js_1.isAbortError)(error);
 }
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-// ─── Policy ──────────────────────────────────────────────────────────────────
+// ─── Policy ───────────────────────────────────────────────────────────────────
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 function retryPolicy(opts) {
-    const max = Math.max(1, opts.attempts);
-    return (fn, ctx) => async () => {
+    const max = Math.max(1, Math.floor(opts.attempts));
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    return (fn, ctx) => async (parentSignal) => {
         let lastErr;
         for (let attempt = 1; attempt <= max; attempt++) {
+            // Parent (totalTimeout or caller signal) already aborted — bail.
+            if (parentSignal.aborted)
+                throw parentSignal.reason;
             ctx.meta.attempts = attempt;
             try {
-                return await fn();
+                return await fn(parentSignal);
             }
             catch (err) {
                 lastErr = err;
-                if (attempt < max) {
+                // Always invoke shouldRetry so observers see every failure.
+                // The return value only matters when there are attempts left.
+                const retryable = shouldRetry(err, attempt);
+                if (attempt >= max) {
+                    // Last attempt — surface the error regardless of retryable.
+                    throw err;
+                }
+                if (!retryable) {
                     // Non-retryable error — bail immediately without consuming
                     // remaining attempts. The error surfaces exactly as-is.
-                    if (opts.shouldRetry && !opts.shouldRetry(err, attempt)) {
-                        throw err;
-                    }
-                    const delay = computeDelay(attempt, opts);
-                    if (delay > 0)
-                        await sleep(delay);
+                    throw err;
+                }
+                // Parent aborted mid-attempt — don't sleep, bail.
+                if (parentSignal.aborted)
+                    throw parentSignal.reason;
+                const delay = (0, backoff_js_1.computeDelay)(attempt, opts);
+                if (delay > 0) {
+                    // Sleep is signal-aware: rejects immediately if parent aborts.
+                    await (0, abort_js_1.sleep)(delay, parentSignal);
                 }
             }
         }
-        // Every attempt failed — surface the last error upstream
+        // Unreachable: the loop either returns or throws on every iteration.
+        // The cast satisfies the type checker without a `throw` after the loop.
         throw lastErr;
     };
 }

package/dist/policies/retry.d.ts

@@ -1,7 +1,30 @@
 import type { PolicyApplier, RetryOptions } from '../types/index.js';
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 export declare function retryPolicy<T>(opts: RetryOptions): PolicyApplier<T>;
 //# sourceMappingURL=retry.d.ts.map

package/dist/policies/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAmB1F;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CA8BnE"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAoB1F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAiDnE"}

package/dist/policies/retry.js

@@ -1,44 +1,84 @@
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function computeDelay(attempt, opts) {
-    const base = opts.delayMs ?? 0;
-    if (base === 0)
-        return 0;
-    switch (opts.backoff ?? 'none') {
-        case 'linear': return base * attempt;
-        case 'exponential': return base * 2 ** (attempt - 1);
-        default: return base;
-    }
+import { computeDelay } from '../utils/backoff.js';
+import { isAbortError, sleep } from '../utils/abort.js';
+// ─── Default predicate ────────────────────────────────────────────────────────
+/**
+ * Default `shouldRetry`: retry on any error EXCEPT abort errors.
+ *
+ * Abort errors indicate the caller or a timeout cancelled the operation —
+ * retrying would just abort again on the next attempt, wasting delay budget.
+ *
+ * User-supplied `shouldRetry` overrides this entirely.
+ */
+function defaultShouldRetry(error, _attempt) {
+    return !isAbortError(error);
 }
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-// ─── Policy ──────────────────────────────────────────────────────────────────
+// ─── Policy ───────────────────────────────────────────────────────────────────
 /**
- * Retries fn up to opts.attempts times on any thrown error.
- * Writes the live attempt count into ctx.meta.attempts.
+ * Retry `fn` up to `opts.attempts` times on retryable errors.
+ *
+ * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
+ * report it in the final `ActResult`.
+ *
+ * # Signal awareness
+ *
+ * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
+ *   `totalTimeout` or caller) has aborted, throws the parent's reason
+ *   immediately — no more attempts.
+ * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
+ *   aborts mid-delay, the sleep rejects immediately instead of blocking
+ *   the loop until the timer would have elapsed.
+ *
+ * # `shouldRetry` invocation
+ *
+ * Called after EVERY failure, including the last attempt. This preserves the
+ * predicate's contract for observers / metrics that rely on it being called
+ * per-attempt. The return value is only consulted when `attempt < max`.
+ *
+ * # Default predicate
+ *
+ * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
+ * every error EXCEPT abort errors (so timeouts and caller cancellations
+ * don't waste retry budget).
  */
 export function retryPolicy(opts) {
-    const max = Math.max(1, opts.attempts);
-    return (fn, ctx) => async () => {
+    const max = Math.max(1, Math.floor(opts.attempts));
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    return (fn, ctx) => async (parentSignal) => {
         let lastErr;
         for (let attempt = 1; attempt <= max; attempt++) {
+            // Parent (totalTimeout or caller signal) already aborted — bail.
+            if (parentSignal.aborted)
+                throw parentSignal.reason;
             ctx.meta.attempts = attempt;
             try {
-                return await fn();
+                return await fn(parentSignal);
             }
             catch (err) {
                 lastErr = err;
-                if (attempt < max) {
+                // Always invoke shouldRetry so observers see every failure.
+                // The return value only matters when there are attempts left.
+                const retryable = shouldRetry(err, attempt);
+                if (attempt >= max) {
+                    // Last attempt — surface the error regardless of retryable.
+                    throw err;
+                }
+                if (!retryable) {
                     // Non-retryable error — bail immediately without consuming
                     // remaining attempts. The error surfaces exactly as-is.
-                    if (opts.shouldRetry && !opts.shouldRetry(err, attempt)) {
-                        throw err;
-                    }
-                    const delay = computeDelay(attempt, opts);
-                    if (delay > 0)
-                        await sleep(delay);
+                    throw err;
+                }
+                // Parent aborted mid-attempt — don't sleep, bail.
+                if (parentSignal.aborted)
+                    throw parentSignal.reason;
+                const delay = computeDelay(attempt, opts);
+                if (delay > 0) {
+                    // Sleep is signal-aware: rejects immediately if parent aborts.
+                    await sleep(delay, parentSignal);
                 }
             }
         }
-        // Every attempt failed — surface the last error upstream
+        // Unreachable: the loop either returns or throws on every iteration.
+        // The cast satisfies the type checker without a `throw` after the loop.
         throw lastErr;
     };
 }

package/dist/policies/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAEhF,SAAS,YAAY,CAAC,OAAe,EAAE,IAAkB;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAExB,QAAQ,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC;QAC/B,KAAK,QAAQ,CAAC,CAAM,OAAO,IAAI,GAAG,OAAO,CAAA;QACzC,KAAK,aAAa,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;QACpD,OAAO,CAAC,CAAY,OAAO,IAAI,CAAA;IACjC,CAAC;AACH,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AAEvE,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAI,IAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IAEtC,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,IAAI,EAAE;QACT,IAAI,OAAgB,CAAA;QAEpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAA;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,GAAG,CAAA;gBAEb,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;oBAClB,2DAA2D;oBAC3D,wDAAwD;oBACxD,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC;wBACxD,MAAM,GAAG,CAAA;oBACX,CAAC;oBAED,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;oBACzC,IAAI,KAAK,GAAG,CAAC;wBAAE,MAAM,KAAK,CAAC,KAAK,CAAC,CAAA;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,MAAM,OAAO,CAAA;IACf,CAAC,CAAA;AACL,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/policies/retry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEvD,iFAAiF;AAEjF;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAAC,KAAc,EAAE,QAAgB;IAC1D,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,WAAW,CAAI,IAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,kBAAkB,CAAA;IAE1D,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,EAAE,YAAyB,EAAE,EAAE;QAClC,IAAI,OAAgB,CAAA;QAEpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;YAChD,iEAAiE;YACjE,IAAI,YAAY,CAAC,OAAO;gBAAE,MAAM,YAAY,CAAC,MAAM,CAAA;YAEnD,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;YAE3B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAC,YAAY,CAAC,CAAA;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,GAAG,CAAA;gBAEb,4DAA4D;gBAC5D,8DAA8D;gBAC9D,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;gBAE3C,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;oBACnB,4DAA4D;oBAC5D,MAAM,GAAG,CAAA;gBACX,CAAC;gBAED,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,2DAA2D;oBAC3D,wDAAwD;oBACxD,MAAM,GAAG,CAAA;gBACX,CAAC;gBAED,kDAAkD;gBAClD,IAAI,YAAY,CAAC,OAAO;oBAAE,MAAM,YAAY,CAAC,MAAM,CAAA;gBAEnD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;gBACzC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;oBACd,+DAA+D;oBAC/D,MAAM,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;gBAClC,CAAC;YACH,CAAC;QACH,CAAC;QAED,qEAAqE;QACrE,wEAAwE;QACxE,MAAM,OAAO,CAAA;IACf,CAAC,CAAA;AACL,CAAC"}