actly 1.0.2 → 1.1.5

package/dist/policies/timeout.cjs

@@ -3,8 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TotalTimeoutError = exports.TimeoutError = void 0;
 exports.timeoutPolicy = timeoutPolicy;
 exports.totalTimeoutPolicy = totalTimeoutPolicy;
+const abort_js_1 = require("../utils/abort.js");
 // ─── Errors ───────────────────────────────────────────────────────────────────
+/**
+ * Thrown when a per-attempt `timeout` deadline fires.
+ *
+ * Carries the configured `ms` so callers can log/alert precisely:
+ *
+ * ```ts
+ * if (!result.ok && result.error instanceof TimeoutError) {
+ *   console.log(`attempt timed out after ${result.error.ms}ms`)
+ * }
+ * ```
+ */
 class TimeoutError extends Error {
+    ms;
     constructor(ms) {
         super(`ACT timed out after ${ms}ms`);
         this.name = 'TimeoutError';
@@ -13,11 +26,21 @@ class TimeoutError extends Error {
 }
 exports.TimeoutError = TimeoutError;
 /**
- * Thrown when the total budget across all attempts is exceeded.
- * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
- * which deadline fired.
+ * Thrown when the operation-wide `totalTimeout` budget fires.
+ *
+ * Distinct from `TimeoutError` (per-attempt) so callers can `instanceof`-check
+ * which deadline fired:
+ *
+ * ```ts
+ * if (result.error instanceof TotalTimeoutError) {
+ *   // whole operation budget exhausted
+ * } else if (result.error instanceof TimeoutError) {
+ *   // last attempt's per-attempt deadline fired
+ * }
+ * ```
  */
 class TotalTimeoutError extends Error {
+    ms;
     constructor(ms) {
         super(`ACT total timeout exceeded after ${ms}ms`);
         this.name = 'TotalTimeoutError';
@@ -25,29 +48,76 @@ class TotalTimeoutError extends Error {
     }
 }
 exports.TotalTimeoutError = TotalTimeoutError;
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-/** Shared race-against-a-timer logic. ErrorCtor lets callers pick the error type. */
+// ─── Policy ───────────────────────────────────────────────────────────────────
+/**
+ * Build a timeout policy that throws `ErrorCtor` on deadline.
+ *
+ * # Cancellation contract
+ *
+ * Each invocation:
+ *   1. Creates a fresh `AbortController` for this attempt.
+ *   2. Arms a `setTimeout` that aborts the controller with a fresh `ErrorCtor(ms)`.
+ *   3. Links the parent signal: if the parent aborts (e.g. `totalTimeout` or
+ *      caller cancellation), the child aborts with the parent's reason.
+ *   4. Races `fn(childSignal)` against the abort event.
+ *
+ * The race is critical: it ensures `act()` returns promptly even if `fn`
+ * ignores the signal. The underlying `fn` may keep running in the background
+ * (resource leak), but the caller is unblocked. This is the best JavaScript
+ * can do without cooperation from `fn`.
+ *
+ * If `fn` cooperates (passes `signal` to `fetch`, `AbortController`, etc.),
+ * the underlying work is cancelled properly — no leak.
+ *
+ * # Error attribution
+ *
+ * If the per-attempt timer fires, we throw `ErrorCtor(ms)` regardless of
+ * what `fn` does. If the parent signal fires first, we throw the parent's
+ * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
+ */
 function makeTimeoutPolicy(opts, ErrorCtor) {
-    return (fn, _ctx) => () => new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new ErrorCtor(opts.ms)), opts.ms);
-        fn()
-            .then((v) => { clearTimeout(timer); resolve(v); })
-            .catch((e) => { clearTimeout(timer); reject(e); });
-    });
+    return (fn, _ctx) => async (parentSignal) => {
+        const controller = new AbortController();
+        const timerError = new ErrorCtor(opts.ms);
+        // Arm the per-attempt timer. The error object is allocated once so the
+        // stack trace points here (the policy frame), not at setTimeout's
+        // internal callback.
+        const timer = setTimeout(() => controller.abort(timerError), opts.ms);
+        // Link parent -> child. If parent is already aborted, child aborts
+        // synchronously with parent's reason.
+        (0, abort_js_1.linkSignal)(parentSignal, controller);
+        try {
+            // Race fn against the abort event. If fn settles first, we get its
+            // result/error. If the signal aborts first, we reject with reason.
+            //
+            // We do NOT use AbortSignal.timeout() here because we need to throw
+            // our own ErrorCtor, not a DOMException named "TimeoutError".
+            return await new Promise((resolve, reject) => {
+                if (controller.signal.aborted) {
+                    reject(controller.signal.reason);
+                    return;
+                }
+                controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+                Promise.resolve(fn(controller.signal)).then((value) => resolve(value), (error) => reject(error));
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
 }
-// ─── Policies ─────────────────────────────────────────────────────────────────
 /**
- * Races fn against a hard deadline.
- * Rejects with TimeoutError if the deadline fires first.
+ * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *
- * Place this INSIDE retryPolicy (closer to fn) so each attempt has its own clock.
+ * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
+ * own clock.
  */
 function timeoutPolicy(opts) {
     return makeTimeoutPolicy(opts, TimeoutError);
 }
 /**
- * Races the ENTIRE operation (all retry attempts + delays) against a budget.
- * Rejects with TotalTimeoutError if the budget is exhausted.
+ * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
+ * delays) against a hard budget that does NOT reset.
  *
  * Place this as the OUTERMOST policy so the clock starts before any other
  * policy runs and stops regardless of what the inner chain is doing.

package/dist/policies/timeout.d.ts

@@ -1,27 +1,47 @@
 import type { PolicyApplier, TimeoutOptions } from '../types/index.js';
+/**
+ * Thrown when a per-attempt `timeout` deadline fires.
+ *
+ * Carries the configured `ms` so callers can log/alert precisely:
+ *
+ * ```ts
+ * if (!result.ok && result.error instanceof TimeoutError) {
+ *   console.log(`attempt timed out after ${result.error.ms}ms`)
+ * }
+ * ```
+ */
 export declare class TimeoutError extends Error {
     readonly ms: number;
     constructor(ms: number);
 }
 /**
- * Thrown when the total budget across all attempts is exceeded.
- * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
- * which deadline fired.
+ * Thrown when the operation-wide `totalTimeout` budget fires.
+ *
+ * Distinct from `TimeoutError` (per-attempt) so callers can `instanceof`-check
+ * which deadline fired:
+ *
+ * ```ts
+ * if (result.error instanceof TotalTimeoutError) {
+ *   // whole operation budget exhausted
+ * } else if (result.error instanceof TimeoutError) {
+ *   // last attempt's per-attempt deadline fired
+ * }
+ * ```
  */
 export declare class TotalTimeoutError extends Error {
     readonly ms: number;
     constructor(ms: number);
 }
 /**
- * Races fn against a hard deadline.
- * Rejects with TimeoutError if the deadline fires first.
+ * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *
- * Place this INSIDE retryPolicy (closer to fn) so each attempt has its own clock.
+ * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
+ * own clock.
  */
 export declare function timeoutPolicy<T>(opts: TimeoutOptions): PolicyApplier<T>;
 /**
- * Races the ENTIRE operation (all retry attempts + delays) against a budget.
- * Rejects with TotalTimeoutError if the budget is exhausted.
+ * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
+ * delays) against a hard budget that does NOT reset.
  *
  * Place this as the OUTERMOST policy so the clock starts before any other
  * policy runs and stops regardless of what the inner chain is doing.

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

@@ -1 +1 @@
-{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAI5F,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAyBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAK5F;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEP,EAAE,EAAE,MAAM;CAKvB;AAgFD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}

package/dist/policies/timeout.js

@@ -1,5 +1,18 @@
+import { linkSignal } from '../utils/abort.js';
 // ─── Errors ───────────────────────────────────────────────────────────────────
+/**
+ * Thrown when a per-attempt `timeout` deadline fires.
+ *
+ * Carries the configured `ms` so callers can log/alert precisely:
+ *
+ * ```ts
+ * if (!result.ok && result.error instanceof TimeoutError) {
+ *   console.log(`attempt timed out after ${result.error.ms}ms`)
+ * }
+ * ```
+ */
 export class TimeoutError extends Error {
+    ms;
     constructor(ms) {
         super(`ACT timed out after ${ms}ms`);
         this.name = 'TimeoutError';
@@ -7,40 +20,97 @@ export class TimeoutError extends Error {
     }
 }
 /**
- * Thrown when the total budget across all attempts is exceeded.
- * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
- * which deadline fired.
+ * Thrown when the operation-wide `totalTimeout` budget fires.
+ *
+ * Distinct from `TimeoutError` (per-attempt) so callers can `instanceof`-check
+ * which deadline fired:
+ *
+ * ```ts
+ * if (result.error instanceof TotalTimeoutError) {
+ *   // whole operation budget exhausted
+ * } else if (result.error instanceof TimeoutError) {
+ *   // last attempt's per-attempt deadline fired
+ * }
+ * ```
  */
 export class TotalTimeoutError extends Error {
+    ms;
     constructor(ms) {
         super(`ACT total timeout exceeded after ${ms}ms`);
         this.name = 'TotalTimeoutError';
         this.ms = ms;
     }
 }
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-/** Shared race-against-a-timer logic. ErrorCtor lets callers pick the error type. */
+// ─── Policy ───────────────────────────────────────────────────────────────────
+/**
+ * Build a timeout policy that throws `ErrorCtor` on deadline.
+ *
+ * # Cancellation contract
+ *
+ * Each invocation:
+ *   1. Creates a fresh `AbortController` for this attempt.
+ *   2. Arms a `setTimeout` that aborts the controller with a fresh `ErrorCtor(ms)`.
+ *   3. Links the parent signal: if the parent aborts (e.g. `totalTimeout` or
+ *      caller cancellation), the child aborts with the parent's reason.
+ *   4. Races `fn(childSignal)` against the abort event.
+ *
+ * The race is critical: it ensures `act()` returns promptly even if `fn`
+ * ignores the signal. The underlying `fn` may keep running in the background
+ * (resource leak), but the caller is unblocked. This is the best JavaScript
+ * can do without cooperation from `fn`.
+ *
+ * If `fn` cooperates (passes `signal` to `fetch`, `AbortController`, etc.),
+ * the underlying work is cancelled properly — no leak.
+ *
+ * # Error attribution
+ *
+ * If the per-attempt timer fires, we throw `ErrorCtor(ms)` regardless of
+ * what `fn` does. If the parent signal fires first, we throw the parent's
+ * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
+ */
 function makeTimeoutPolicy(opts, ErrorCtor) {
-    return (fn, _ctx) => () => new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new ErrorCtor(opts.ms)), opts.ms);
-        fn()
-            .then((v) => { clearTimeout(timer); resolve(v); })
-            .catch((e) => { clearTimeout(timer); reject(e); });
-    });
+    return (fn, _ctx) => async (parentSignal) => {
+        const controller = new AbortController();
+        const timerError = new ErrorCtor(opts.ms);
+        // Arm the per-attempt timer. The error object is allocated once so the
+        // stack trace points here (the policy frame), not at setTimeout's
+        // internal callback.
+        const timer = setTimeout(() => controller.abort(timerError), opts.ms);
+        // Link parent -> child. If parent is already aborted, child aborts
+        // synchronously with parent's reason.
+        linkSignal(parentSignal, controller);
+        try {
+            // Race fn against the abort event. If fn settles first, we get its
+            // result/error. If the signal aborts first, we reject with reason.
+            //
+            // We do NOT use AbortSignal.timeout() here because we need to throw
+            // our own ErrorCtor, not a DOMException named "TimeoutError".
+            return await new Promise((resolve, reject) => {
+                if (controller.signal.aborted) {
+                    reject(controller.signal.reason);
+                    return;
+                }
+                controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
+                Promise.resolve(fn(controller.signal)).then((value) => resolve(value), (error) => reject(error));
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
 }
-// ─── Policies ─────────────────────────────────────────────────────────────────
 /**
- * Races fn against a hard deadline.
- * Rejects with TimeoutError if the deadline fires first.
+ * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *
- * Place this INSIDE retryPolicy (closer to fn) so each attempt has its own clock.
+ * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
+ * own clock.
  */
 export function timeoutPolicy(opts) {
     return makeTimeoutPolicy(opts, TimeoutError);
 }
 /**
- * Races the ENTIRE operation (all retry attempts + delays) against a budget.
- * Rejects with TotalTimeoutError if the budget is exhausted.
+ * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
+ * delays) against a hard budget that does NOT reset.
  *
  * Place this as the OUTERMOST policy so the clock starts before any other
  * policy runs and stops regardless of what the inner chain is doing.

package/dist/policies/timeout.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAEA,iFAAiF;AAEjF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGrC,YAAY,EAAU;QACpB,KAAK,CAAC,uBAAuB,EAAE,IAAI,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAG1C,YAAY,EAAU;QACpB,KAAK,CAAC,oCAAoC,EAAE,IAAI,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED,iFAAiF;AAEjF,qFAAqF;AACrF,SAAS,iBAAiB,CACxB,IAAoB,EACpB,SAAoC;IAEpC,OAAO,CAAC,EAAY,EAAE,IAAmB,EAAY,EAAE,CACrD,GAAG,EAAE,CACH,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACjC,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EACpC,IAAI,CAAC,EAAE,CACR,CAAA;QAED,EAAE,EAAE;aACD,IAAI,CAAC,CAAC,CAAI,EAAS,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA,CAAC,CAAC,CAAC;aAC1D,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA,CAAE,CAAC,CAAC,CAAA;IAC/D,CAAC,CAAC,CAAA;AACR,CAAC;AAED,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,IAAoB;IACnD,OAAO,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAI,IAAoB;IACxD,OAAO,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;AACnD,CAAC"}
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,EAAE,CAAQ;IAEnB,YAAY,EAAU;QACpB,KAAK,CAAC,uBAAuB,EAAE,IAAI,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,EAAE,CAAQ;IAEnB,YAAY,EAAU;QACpB,KAAK,CAAC,oCAAoC,EAAE,IAAI,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAS,iBAAiB,CACxB,IAAoB,EACpB,SAAoC;IAEpC,OAAO,CAAC,EAAY,EAAE,IAAmB,EAAY,EAAE,CACrD,KAAK,EAAE,YAAyB,EAAE,EAAE;QAClC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,UAAU,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAEzC,uEAAuE;QACvE,kEAAkE;QAClE,qBAAqB;QACrB,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,EAClC,IAAI,CAAC,EAAE,CACR,CAAA;QAED,mEAAmE;QACnE,sCAAsC;QACtC,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;QAEpC,IAAI,CAAC;YACH,mEAAmE;YACnE,mEAAmE;YACnE,EAAE;YACF,oEAAoE;YACpE,8DAA8D;YAC9D,OAAO,MAAM,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC9C,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC9B,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;oBAChC,OAAM;gBACR,CAAC;gBAED,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAChC,OAAO,EACP,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,EACtC,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAA;gBAED,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CACzC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EACzB,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CACzB,CAAA;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;IACH,CAAC,CAAA;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,IAAoB;IACnD,OAAO,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAI,IAAoB;IACxD,OAAO,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;AACnD,CAAC"}

package/dist/state/store.cjs

@@ -1,41 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryStore = void 0;
-class InMemoryStore {
-    constructor() {
-        this.entries = new Map();
-    }
-    get(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
-            return undefined;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
-            return undefined;
-        }
-        return entry.value;
-    }
-    set(key, value, ttlMs) {
-        // ttlMs = 0 or undefined -> no expiry (sentinel null)
-        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
-        this.entries.set(key, { value, expiresAt });
-    }
-    delete(key) {
-        this.entries.delete(key);
-    }
-    has(key) {
-        // Reuse get() so expired entries are evicted on access
-        return this.get(key) !== undefined;
-    }
-    /** Drop everything. Handy in tests or for manual cache invalidation. */
-    clear() {
-        this.entries.clear();
-    }
-    /** Count of live (non-expired) entries. */
-    get size() {
-        for (const key of this.entries.keys())
-            this.has(key);
-        return this.entries.size;
-    }
-}
-exports.InMemoryStore = InMemoryStore;
+/**
+ * @deprecated since v1.1.5 — import from `'actly'` directly.
+ *
+ * This re-export shim exists for backwards compatibility with code that
+ * imported `InMemoryStore` from `'actly/state/store'`. It will be removed
+ * in v2.0.0.
+ *
+ * The implementation has moved to `src/stores/memory.ts`.
+ */
+var memory_js_1 = require("../stores/memory.js");
+Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return memory_js_1.InMemoryStore; } });

package/dist/state/store.d.ts

@@ -1,13 +1,11 @@
-import type { StateStore } from '../types/index.js';
-export declare class InMemoryStore implements StateStore {
-    private entries;
-    get<T>(key: string): T | undefined;
-    set<T>(key: string, value: T, ttlMs?: number): void;
-    delete(key: string): void;
-    has(key: string): boolean;
-    /** Drop everything. Handy in tests or for manual cache invalidation. */
-    clear(): void;
-    /** Count of live (non-expired) entries. */
-    get size(): number;
-}
+/**
+ * @deprecated since v1.1.5 — import from `'actly'` directly.
+ *
+ * This re-export shim exists for backwards compatibility with code that
+ * imported `InMemoryStore` from `'actly/state/store'`. It will be removed
+ * in v2.0.0.
+ *
+ * The implementation has moved to `src/stores/memory.ts`.
+ */
+export { InMemoryStore } from '../stores/memory.js';
 //# sourceMappingURL=store.d.ts.map

package/dist/state/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAQnD,qBAAa,aAAc,YAAW,UAAU;IAC9C,OAAO,CAAC,OAAO,CAAoC;IAEnD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAYlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAOnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAIb,2CAA2C;IAC3C,IAAI,IAAI,IAAI,MAAM,CAGjB;CACF"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/state/store.js

@@ -1,38 +1,11 @@
-export class InMemoryStore {
-    constructor() {
-        this.entries = new Map();
-    }
-    get(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
-            return undefined;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
-            return undefined;
-        }
-        return entry.value;
-    }
-    set(key, value, ttlMs) {
-        // ttlMs = 0 or undefined -> no expiry (sentinel null)
-        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
-        this.entries.set(key, { value, expiresAt });
-    }
-    delete(key) {
-        this.entries.delete(key);
-    }
-    has(key) {
-        // Reuse get() so expired entries are evicted on access
-        return this.get(key) !== undefined;
-    }
-    /** Drop everything. Handy in tests or for manual cache invalidation. */
-    clear() {
-        this.entries.clear();
-    }
-    /** Count of live (non-expired) entries. */
-    get size() {
-        for (const key of this.entries.keys())
-            this.has(key);
-        return this.entries.size;
-    }
-}
+/**
+ * @deprecated since v1.1.5 — import from `'actly'` directly.
+ *
+ * This re-export shim exists for backwards compatibility with code that
+ * imported `InMemoryStore` from `'actly/state/store'`. It will be removed
+ * in v2.0.0.
+ *
+ * The implementation has moved to `src/stores/memory.ts`.
+ */
+export { InMemoryStore } from '../stores/memory.js';
 //# sourceMappingURL=store.js.map

package/dist/state/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,aAAa;IAA1B;QACU,YAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IAwCrD,CAAC;IAtCC,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAA;QAE5B,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACxB,OAAO,SAAS,CAAA;QAClB,CAAC;QAED,OAAO,KAAK,CAAC,KAAU,CAAA;IACzB,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,KAAc;QAC1C,sDAAsD;QACtD,MAAM,SAAS,GACb,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;QACxD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;IAC7C,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,uDAAuD;QACvD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAA;IACpC,CAAC;IAED,wEAAwE;IACxE,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED,2CAA2C;IAC3C,IAAI,IAAI;QACN,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;CACF"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/state/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/stores/base.cjs

@@ -0,0 +1,20 @@
+"use strict";
+// ─── Store interfaces ─────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSyncStore = isSyncStore;
+exports.isAsyncStore = isAsyncStore;
+// ─── Type guards ──────────────────────────────────────────────────────────────
+/**
+ * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
+ * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
+ */
+function isSyncStore(store) {
+    return store._sync === true;
+}
+/**
+ * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
+ * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
+ */
+function isAsyncStore(store) {
+    return store._sync === false;
+}

package/dist/stores/base.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Synchronous key-value store. All operations complete in the same tick.
+ *
+ * # Why synchronous?
+ *
+ * `dedupePolicy` must read an in-flight Promise from the store and, if absent,
+ * write a new one — all within a single synchronous frame. If `get()` were
+ * async, two concurrent callers could both observe a miss before either
+ * write lands, defeating deduplication entirely. There is no lock primitive
+ * in JavaScript that can paper over this: the constraint is structural, not
+ * implementation-level.
+ *
+ * # The `_sync` discriminant
+ *
+ * `_sync: true` is a runtime tag that lets `execute()` enforce the dedupe
+ * constraint for plain-JS callers who bypass TypeScript. It is NOT part of
+ * the semantic contract and MUST NOT be used for anything beyond that guard.
+ * Implementations must set it as a `readonly` literal (`true as const`).
+ *
+ * # Lifecycle
+ *
+ * Implementations that hold background resources (timers, connections) should
+ * expose a `destroy()` method as a convention. See `InMemoryStore` for the
+ * reference pattern.
+ */
+export interface SyncStateStore {
+    /** Runtime discriminant. Must be `true as const`. */
+    readonly _sync: true;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+    /**
+     * Remove all entries synchronously.
+     * After `clear()` returns, `size()` returns 0.
+     */
+    clear(): void;
+    /**
+     * Return the count of live (non-expired) entries.
+     * Side-effect free: does not mutate the store. Implementations MAY evict
+     * expired entries opportunistically during this call, but MUST NOT have
+     * observable side effects beyond internal cleanup.
+     */
+    size(): number;
+}
+/**
+ * Asynchronous key-value store. All operations return Promises.
+ *
+ * # Policy compatibility
+ *
+ * Compatible with `cachePolicy` only. Passing an `AsyncStateStore` to a
+ * policy chain that includes `dedupePolicy` is a TypeScript error and a
+ * runtime error — `execute()` throws at chain-build time. See
+ * `SyncStateStore` for why dedupe requires synchronous access.
+ *
+ * # TTL semantics
+ *
+ * The store is responsible for honouring `ttlMs`. Actly passes it as a hint.
+ * Implementations may delegate to a native TTL mechanism (e.g. Redis EXPIRE).
+ *
+ * # The `_sync` discriminant
+ *
+ * `_sync: false` mirrors the discriminant on `SyncStateStore`. Must be set
+ * as a `readonly` literal (`false as const`).
+ */
+export interface AsyncStateStore {
+    /** Runtime discriminant. Must be `false as const`. */
+    readonly _sync: false;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    /** Remove all entries managed by this store. */
+    clear(): Promise<void>;
+    /** Return the count of live (non-expired) entries. */
+    size(): Promise<number>;
+}
+/**
+ * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
+ * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
+ */
+export declare function isSyncStore(store: SyncStateStore | AsyncStateStore): store is SyncStateStore;
+/**
+ * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
+ * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
+ */
+export declare function isAsyncStore(store: SyncStateStore | AsyncStateStore): store is AsyncStateStore;
+//# sourceMappingURL=base.d.ts.map

package/dist/stores/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;IAEpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAClC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAEzB;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;IAEb;;;;;OAKG;IACH,IAAI,IAAI,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IAErB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAElC,gDAAgD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB,sDAAsD;IACtD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,cAAc,CAEzB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,eAAe,CAE1B"}

package/dist/stores/base.js

@@ -0,0 +1,17 @@
+// ─── Store interfaces ─────────────────────────────────────────────────────────
+// ─── Type guards ──────────────────────────────────────────────────────────────
+/**
+ * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
+ * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
+ */
+export function isSyncStore(store) {
+    return store._sync === true;
+}
+/**
+ * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
+ * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
+ */
+export function isAsyncStore(store) {
+    return store._sync === false;
+}
+//# sourceMappingURL=base.js.map

package/dist/stores/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAuFjF,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,KAAuC;IAEvC,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAA;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAuC;IAEvC,OAAO,KAAK,CAAC,KAAK,KAAK,KAAK,CAAA;AAC9B,CAAC"}