actly 1.1.0 → 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,7 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryStore = void 0;
-// Re-export shim — implementation moved to src/stores/memory.ts in v1.1.
-// Kept for one version to preserve git blame and ease internal refactors.
+/**
+ * @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,2 +1,11 @@
+/**
+ * @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":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"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,4 +1,11 @@
-// Re-export shim — implementation moved to src/stores/memory.ts in v1.1.
-// Kept for one version to preserve git blame and ease internal refactors.
+/**
+ * @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":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"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

@@ -5,15 +5,15 @@ 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.
+ * 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.
+ * 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

@@ -3,34 +3,28 @@
  *
  * # 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.
+ * `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
+ * # 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.
+ * `_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, though it is not part of this
- * interface — the async counterpart cannot enforce it symmetrically without
- * requiring Promise returns. See InMemoryStore for the reference pattern.
- *
- * InMemoryStore is the canonical implementation of this interface.
+ * expose a `destroy()` method as a convention. See `InMemoryStore` for the
+ * reference pattern.
  */
 export interface SyncStateStore {
-    /**
-     * Runtime discriminant. Read by isSyncStore() in execute() to enforce the
-     * dedupe constraint without an instanceof check. Must be `true as const`.
-     */
+    /** 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;
@@ -38,13 +32,14 @@ export interface SyncStateStore {
     has(key: string): boolean;
     /**
      * Remove all entries synchronously.
-     * Must be deterministic: after clear() returns, size() must return 0.
+     * After `clear()` returns, `size()` returns 0.
      */
     clear(): void;
     /**
      * Return the count of live (non-expired) entries.
-     * Expired entries must not be counted, but implementations are free to
-     * evict lazily — the count must reflect only entries observable via get().
+     * 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;
 }
@@ -53,60 +48,41 @@ export interface SyncStateStore {
  *
  * # 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() will throw at chain-build time. See SyncStateStore for why dedupe
- * requires synchronous access.
+ * 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.
+ * 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).
- * There is no enforcement layer above the store boundary.
  *
- * # The _sync discriminant
+ * # The `_sync` discriminant
  *
- * `_sync: false` mirrors the discriminant on SyncStateStore. The executor uses
- * this at runtime to reject async stores in contexts that require synchronous
- * access. Must be set as a `readonly` literal (`false as const`).
- *
- * # Contract parity
- *
- * clear() and size() mirror the SyncStateStore contract so callers building
- * against AnyStateStore can rely on both operations regardless of which variant
- * they receive. Async implementations that do not have a native equivalent
- * (e.g. a bounded Redis namespace) must still satisfy the signature.
+ * `_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`.
-     */
+    /** 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.
-     * For scoped adapters (e.g. a Redis key-prefix namespace), remove only the
-     * entries owned by this instance — not the entire backing store.
-     */
+    /** Remove all entries managed by this store. */
     clear(): Promise<void>;
-    /**
-     * Return the count of live (non-expired) entries.
-     * Expired entries must not be counted. For eventually-consistent backends,
-     * the count is a best-effort snapshot at the time of the call.
-     */
+    /** 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.
+ * 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.
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,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;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,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;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,GAAG,KAAK,IAAI,cAAc,CAE5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,GAAG,KAAK,IAAI,eAAe,CAE9F"}
+{"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

@@ -1,15 +1,15 @@
 // ─── Store interfaces ─────────────────────────────────────────────────────────
 // ─── Type guards ──────────────────────────────────────────────────────────────
 /**
- * Narrows AnyStateStore to SyncStateStore via the _sync discriminant.
- * Used by execute() and cachePolicy to branch between sync and async paths.
+ * 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.
+ * 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;

package/dist/stores/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAAA,iFAAiF;AA+GjF,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuC;IACjE,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAA;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAuC;IAClE,OAAO,KAAK,CAAC,KAAK,KAAK,KAAK,CAAA;AAC9B,CAAC"}
+{"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"}