actly 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ACT contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/core/act.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.act = act;
+const executor_js_1 = require("./executor.js");
+const retry_js_1 = require("../policies/retry.js");
+const timeout_js_1 = require("../policies/timeout.js");
+const dedupe_js_1 = require("../policies/dedupe.js");
+const cache_js_1 = require("../policies/cache.js");
+const store_js_1 = require("../state/store.js");
+// Module-level default store so cache and dedupe persist across calls.
+// For SSR isolation or per-test control, construct an InMemoryStore and
+// call execute() directly — it accepts any StateStore implementation.
+const defaultStore = new store_js_1.InMemoryStore();
+/**
+ * Execute fn with the given reliability policies.
+ *
+ * @param key     Stable identifier for this action. Scopes dedupe + cache.
+ * @param fn      The async work to run.
+ * @param options Which policies to apply and how. All fields are optional.
+ *
+ * @returns       ActResult<T> — always resolves, never throws.
+ *                Check result.ok before reading result.value.
+ *
+ * @example
+ * const result = await act('user:42', () => fetchUser(42), {
+ *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout: { ms: 5_000 },
+ *   dedupe:  true,
+ *   cache:   { ttl: 60_000 },
+ * })
+ *
+ * if (result.ok) {
+ *   console.log(result.value, result.source, result.attempts)
+ * } else {
+ *   console.error(result.error)
+ * }
+ */
+async function act(key, fn, options = {}) {
+    const meta = { attempts: 1, source: 'fresh' };
+    // Normalise dedupe: true → { enabled: true } so the rest of the function
+    // always works with the object form.
+    const dedupe = typeof options.dedupe === 'boolean'
+        ? { enabled: options.dedupe }
+        : options.dedupe;
+    // Outermost -> innermost. See executor.ts for why this ordering matters.
+    const policies = [];
+    // totalTimeout sits before everything — it's a hard wall-clock budget over
+    // the entire operation. If it fires, no inner policy can extend the deadline.
+    if (options.totalTimeout && options.totalTimeout.ms > 0) {
+        policies.push((0, timeout_js_1.totalTimeoutPolicy)(options.totalTimeout)); // 0. hardest outer wall
+    }
+    if (options.cache && options.cache.ttl > 0) {
+        policies.push((0, cache_js_1.cachePolicy)(options.cache)); // 1. skip all on hit
+    }
+    if (dedupe?.enabled) {
+        policies.push((0, dedupe_js_1.dedupePolicy)()); // 2. collapse concurrent callers
+    }
+    if (options.retry && options.retry.attempts > 1) {
+        policies.push((0, retry_js_1.retryPolicy)(options.retry)); // 3. own the attempt loop
+    }
+    if (options.timeout && options.timeout.ms > 0) {
+        policies.push((0, timeout_js_1.timeoutPolicy)(options.timeout)); // 4. innermost — per-attempt clock
+    }
+    try {
+        const value = await (0, executor_js_1.execute)({ key, fn, policies, store: defaultStore, meta });
+        return { ok: true, value, source: meta.source, attempts: meta.attempts };
+    }
+    catch (error) {
+        return { ok: false, error, attempts: meta.attempts };
+    }
+}

package/dist/core/act.d.ts

@@ -0,0 +1,27 @@
+import type { ActFn, ActOptions, ActResult } from '../types/index.js';
+/**
+ * Execute fn with the given reliability policies.
+ *
+ * @param key     Stable identifier for this action. Scopes dedupe + cache.
+ * @param fn      The async work to run.
+ * @param options Which policies to apply and how. All fields are optional.
+ *
+ * @returns       ActResult<T> — always resolves, never throws.
+ *                Check result.ok before reading result.value.
+ *
+ * @example
+ * const result = await act('user:42', () => fetchUser(42), {
+ *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout: { ms: 5_000 },
+ *   dedupe:  true,
+ *   cache:   { ttl: 60_000 },
+ * })
+ *
+ * if (result.ok) {
+ *   console.log(result.value, result.source, result.attempts)
+ * } else {
+ *   console.error(result.error)
+ * }
+ */
+export declare function act<T>(key: string, fn: ActFn<T>, options?: ActOptions): Promise<ActResult<T>>;
+//# sourceMappingURL=act.d.ts.map

package/dist/core/act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAA0B,MAAM,mBAAmB,CAAA;AAa7F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,GAAG,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EACZ,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAwCvB"}

package/dist/core/act.js

@@ -0,0 +1,69 @@
+import { execute } from './executor.js';
+import { retryPolicy } from '../policies/retry.js';
+import { timeoutPolicy, totalTimeoutPolicy } from '../policies/timeout.js';
+import { dedupePolicy } from '../policies/dedupe.js';
+import { cachePolicy } from '../policies/cache.js';
+import { InMemoryStore } from '../state/store.js';
+// Module-level default store so cache and dedupe persist across calls.
+// For SSR isolation or per-test control, construct an InMemoryStore and
+// call execute() directly — it accepts any StateStore implementation.
+const defaultStore = new InMemoryStore();
+/**
+ * Execute fn with the given reliability policies.
+ *
+ * @param key     Stable identifier for this action. Scopes dedupe + cache.
+ * @param fn      The async work to run.
+ * @param options Which policies to apply and how. All fields are optional.
+ *
+ * @returns       ActResult<T> — always resolves, never throws.
+ *                Check result.ok before reading result.value.
+ *
+ * @example
+ * const result = await act('user:42', () => fetchUser(42), {
+ *   retry:   { attempts: 3, delayMs: 200, backoff: 'exponential' },
+ *   timeout: { ms: 5_000 },
+ *   dedupe:  true,
+ *   cache:   { ttl: 60_000 },
+ * })
+ *
+ * if (result.ok) {
+ *   console.log(result.value, result.source, result.attempts)
+ * } else {
+ *   console.error(result.error)
+ * }
+ */
+export async function act(key, fn, options = {}) {
+    const meta = { attempts: 1, source: 'fresh' };
+    // Normalise dedupe: true → { enabled: true } so the rest of the function
+    // always works with the object form.
+    const dedupe = typeof options.dedupe === 'boolean'
+        ? { enabled: options.dedupe }
+        : options.dedupe;
+    // Outermost -> innermost. See executor.ts for why this ordering matters.
+    const policies = [];
+    // totalTimeout sits before everything — it's a hard wall-clock budget over
+    // the entire operation. If it fires, no inner policy can extend the deadline.
+    if (options.totalTimeout && options.totalTimeout.ms > 0) {
+        policies.push(totalTimeoutPolicy(options.totalTimeout)); // 0. hardest outer wall
+    }
+    if (options.cache && options.cache.ttl > 0) {
+        policies.push(cachePolicy(options.cache)); // 1. skip all on hit
+    }
+    if (dedupe?.enabled) {
+        policies.push(dedupePolicy()); // 2. collapse concurrent callers
+    }
+    if (options.retry && options.retry.attempts > 1) {
+        policies.push(retryPolicy(options.retry)); // 3. own the attempt loop
+    }
+    if (options.timeout && options.timeout.ms > 0) {
+        policies.push(timeoutPolicy(options.timeout)); // 4. innermost — per-attempt clock
+    }
+    try {
+        const value = await execute({ key, fn, policies, store: defaultStore, meta });
+        return { ok: true, value, source: meta.source, attempts: meta.attempts };
+    }
+    catch (error) {
+        return { ok: false, error, attempts: meta.attempts };
+    }
+}
+//# sourceMappingURL=act.js.map

package/dist/core/act.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.js","sourceRoot":"","sources":["../../src/core/act.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAa,eAAe,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAS,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAQ,uBAAuB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAS,sBAAsB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAO,mBAAmB,CAAA;AAElD,uEAAuE;AACvE,wEAAwE;AACxE,sEAAsE;AACtE,MAAM,YAAY,GAAG,IAAI,aAAa,EAAE,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,GAAW,EACX,EAAY,EACZ,UAAsB,EAAE;IAExB,MAAM,IAAI,GAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAEtD,yEAAyE;IACzE,qCAAqC;IACrC,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,SAAS;QAChD,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE;QAC7B,CAAC,CAAC,OAAO,CAAC,MAAM,CAAA;IAElB,yEAAyE;IACzE,MAAM,QAAQ,GAA4B,EAAE,CAAA;IAE5C,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACxD,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA,CAAC,wBAAwB;IACrF,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;QAC3C,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA,CAAe,qBAAqB;IAClF,CAAC;IAED,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAK,CAAC,CAAA,CAA2B,iCAAiC;IAC9F,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA,CAAe,0BAA0B;IACvF,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA,CAAW,mCAAmC;IAChG,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;QAC7E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;IAC1E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;IACtD,CAAC;AACH,CAAC"}

package/dist/core/executor.cjs

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = execute;
+/**
+ * Pure execution engine.
+ *
+ * This file imports nothing from /policies.
+ * It operates on PolicyApplier<T> — a type alias defined in /types.
+ * Policy implementations live in /policies and are wired in core/act.ts.
+ */
+async function execute(input) {
+    const ctx = {
+        key: input.key,
+        store: input.store,
+        meta: input.meta,
+    };
+    // Build the call chain from inside out.
+    // reduceRight ensures policies[0] becomes the outermost wrapper (runs first).
+    const wrapped = input.policies.reduceRight((inner, applyPolicy) => applyPolicy(inner, ctx), input.fn);
+    return wrapped();
+}

package/dist/core/executor.d.ts

@@ -0,0 +1,27 @@
+import type { ActFn, PolicyApplier, StateStore, RunMeta } from '../types/index.js';
+export interface ExecutorInput<T> {
+    key: string;
+    fn: ActFn<T>;
+    /**
+     * Policies ordered outermost -> innermost.
+     * policies[0] intercepts first; policies[last] is closest to fn.
+     *
+     * Canonical order: [cache, dedupe, retry, timeout]
+     *   cache   -> a hit skips everything below it
+     *   dedupe  -> collapses concurrent callers before retry fires
+     *   retry   -> owns the attempt loop
+     *   timeout -> each individual attempt races against the clock
+     */
+    policies: ReadonlyArray<PolicyApplier<T>>;
+    store: StateStore;
+    meta: RunMeta;
+}
+/**
+ * Pure execution engine.
+ *
+ * This file imports nothing from /policies.
+ * It operates on PolicyApplier<T> — a type alias defined in /types.
+ * Policy implementations live in /policies and are wired in core/act.ts.
+ */
+export declare function execute<T>(input: ExecutorInput<T>): Promise<T>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/core/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EAEb,UAAU,EACV,OAAO,EACR,MAAM,mBAAmB,CAAA;AAE1B,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,GAAG,EAAO,MAAM,CAAA;IAChB,EAAE,EAAQ,KAAK,CAAC,CAAC,CAAC,CAAA;IAClB;;;;;;;;;OASG;IACH,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,KAAK,EAAK,UAAU,CAAA;IACpB,IAAI,EAAM,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAepE"}

package/dist/core/executor.js

@@ -0,0 +1,19 @@
+/**
+ * Pure execution engine.
+ *
+ * This file imports nothing from /policies.
+ * It operates on PolicyApplier<T> — a type alias defined in /types.
+ * Policy implementations live in /policies and are wired in core/act.ts.
+ */
+export async function execute(input) {
+    const ctx = {
+        key: input.key,
+        store: input.store,
+        meta: input.meta,
+    };
+    // Build the call chain from inside out.
+    // reduceRight ensures policies[0] becomes the outermost wrapper (runs first).
+    const wrapped = input.policies.reduceRight((inner, applyPolicy) => applyPolicy(inner, ctx), input.fn);
+    return wrapped();
+}
+//# sourceMappingURL=executor.js.map

package/dist/core/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,KAAuB;IACtD,MAAM,GAAG,GAAkB;QACzB,GAAG,EAAI,KAAK,CAAC,GAAG;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAG,KAAK,CAAC,IAAI;KAClB,CAAA;IAED,wCAAwC;IACxC,8EAA8E;IAC9E,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,WAAW,CACxC,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,EAC/C,KAAK,CAAC,EAAE,CACT,CAAA;IAED,OAAO,OAAO,EAAE,CAAA;AAClB,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TotalTimeoutError = exports.TimeoutError = exports.InMemoryStore = exports.act = void 0;
+var act_js_1 = require("./core/act.js");
+Object.defineProperty(exports, "act", { enumerable: true, get: function () { return act_js_1.act; } });
+// Exported so consumers can build isolated stores (e.g. per-request in SSR)
+var store_js_1 = require("./state/store.js");
+Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return store_js_1.InMemoryStore; } });
+// Exported so callers can instanceof-check against timeout failures
+var timeout_js_1 = require("./policies/timeout.js");
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return timeout_js_1.TimeoutError; } });
+Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return timeout_js_1.TotalTimeoutError; } });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { act } from './core/act.js';
+export type { ActFn, ActResult, ActSuccess, ActFailure, ActSource, ActOptions, RetryOptions, TimeoutOptions, DedupeOptions, CacheOptions, StateStore, } from './types/index.js';
+export { InMemoryStore } from './state/store.js';
+export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAEnC,YAAY,EACV,KAAK,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { act } from './core/act.js';
+// Exported so consumers can build isolated stores (e.g. per-request in SSR)
+export { InMemoryStore } from './state/store.js';
+// Exported so callers can instanceof-check against timeout failures
+export { TimeoutError, TotalTimeoutError } from './policies/timeout.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAgBnC,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEhD,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/policies/cache.cjs

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachePolicy = cachePolicy;
+const NS = 'cache:';
+/**
+ * Short-circuits the entire downstream chain on a cache hit.
+ * On a miss, runs fn and stores the result with TTL.
+ *
+ * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ */
+function cachePolicy(opts) {
+    return (fn, ctx) => async () => {
+        const key = NS + ctx.key;
+        const hit = ctx.store.get(key);
+        if (hit) {
+            ctx.meta.source = 'cache';
+            return hit.value;
+        }
+        const value = await fn();
+        ctx.store.set(key, { value }, opts.ttl);
+        return value;
+    };
+}

package/dist/policies/cache.d.ts

@@ -0,0 +1,9 @@
+import type { CacheOptions, PolicyApplier } from '../types/index.js';
+/**
+ * Short-circuits the entire downstream chain on a cache hit.
+ * On a miss, runs fn and stores the result with TTL.
+ *
+ * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ */
+export declare function cachePolicy<T>(opts: CacheOptions): PolicyApplier<T>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,YAAY,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAS1F;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAenE"}

package/dist/policies/cache.js

@@ -0,0 +1,21 @@
+const NS = 'cache:';
+/**
+ * Short-circuits the entire downstream chain on a cache hit.
+ * On a miss, runs fn and stores the result with TTL.
+ *
+ * Must be the OUTERMOST policy so a hit skips dedupe, timeout, and retry.
+ */
+export function cachePolicy(opts) {
+    return (fn, ctx) => async () => {
+        const key = NS + ctx.key;
+        const hit = ctx.store.get(key);
+        if (hit) {
+            ctx.meta.source = 'cache';
+            return hit.value;
+        }
+        const value = await fn();
+        ctx.store.set(key, { value }, opts.ttl);
+        return value;
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/policies/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AAEA,MAAM,EAAE,GAAG,QAAQ,CAAA;AAOnB;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,IAAkB;IAC/C,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,IAAI,EAAE;QACT,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAA;QAExB,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;QAC7C,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;YACzB,OAAO,GAAG,CAAC,KAAK,CAAA;QAClB,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;QACxB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACtD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;AACL,CAAC"}

package/dist/policies/dedupe.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dedupePolicy = dedupePolicy;
+// 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.
+ *
+ * The first caller starts the work. Every subsequent caller that arrives before
+ * the first resolves gets the same Promise back — no duplicate work.
+ *
+ * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
+ * the retry counter belongs to the originating call's meta object.
+ */
+function dedupePolicy() {
+    return (fn, ctx) => async () => {
+        const key = NS + ctx.key;
+        const inflight = ctx.store.get(key);
+        if (inflight)
+            return inflight;
+        // No TTL — .finally() cleans up regardless of outcome
+        const promise = fn().finally(() => ctx.store.delete(key));
+        ctx.store.set(key, promise);
+        return promise;
+    };
+}

package/dist/policies/dedupe.d.ts

@@ -0,0 +1,12 @@
+import type { PolicyApplier } from '../types/index.js';
+/**
+ * Collapses 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.
+ *
+ * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
+ * the retry counter belongs to the originating call's meta object.
+ */
+export declare function dedupePolicy<T>(): PolicyApplier<T>;
+//# sourceMappingURL=dedupe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,MAAM,mBAAmB,CAAA;AAK5E;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAalD"}

package/dist/policies/dedupe.js

@@ -0,0 +1,24 @@
+// 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.
+ *
+ * The first caller starts the work. Every subsequent caller that arrives before
+ * the first resolves gets the same Promise back — no duplicate work.
+ *
+ * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
+ * the retry counter belongs to the originating call's meta object.
+ */
+export function dedupePolicy() {
+    return (fn, ctx) => async () => {
+        const key = NS + ctx.key;
+        const inflight = ctx.store.get(key);
+        if (inflight)
+            return inflight;
+        // No TTL — .finally() cleans up regardless of outcome
+        const promise = fn().finally(() => ctx.store.delete(key));
+        ctx.store.set(key, promise);
+        return promise;
+    };
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/policies/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,MAAM,EAAE,GAAG,SAAS,CAAA;AAEpB;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,IAAI,EAAE;QACT,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,CAAC,GAAG,CAAA;QAExB,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,CAAC,CAAA;QAC/C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAA;QAE7B,sDAAsD;QACtD,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QACzD,GAAG,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,EAAE,OAAO,CAAC,CAAA;QACvC,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;AACL,CAAC"}

package/dist/policies/retry.cjs

@@ -0,0 +1,47 @@
+"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 sleep = (ms) => new Promise(r => setTimeout(r, ms));
+// ─── Policy ──────────────────────────────────────────────────────────────────
+/**
+ * Retries fn up to opts.attempts times on any thrown error.
+ * Writes the live attempt count into ctx.meta.attempts.
+ */
+function retryPolicy(opts) {
+    const max = Math.max(1, opts.attempts);
+    return (fn, ctx) => async () => {
+        let lastErr;
+        for (let attempt = 1; attempt <= max; attempt++) {
+            ctx.meta.attempts = attempt;
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < max) {
+                    // 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);
+                }
+            }
+        }
+        // Every attempt failed — surface the last error upstream
+        throw lastErr;
+    };
+}

package/dist/policies/retry.d.ts

@@ -0,0 +1,7 @@
+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.
+ */
+export declare function retryPolicy<T>(opts: RetryOptions): PolicyApplier<T>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +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"}

package/dist/policies/retry.js

@@ -0,0 +1,45 @@
+// ─── 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 sleep = (ms) => new Promise(r => setTimeout(r, ms));
+// ─── Policy ──────────────────────────────────────────────────────────────────
+/**
+ * Retries fn up to opts.attempts times on any thrown error.
+ * Writes the live attempt count into ctx.meta.attempts.
+ */
+export function retryPolicy(opts) {
+    const max = Math.max(1, opts.attempts);
+    return (fn, ctx) => async () => {
+        let lastErr;
+        for (let attempt = 1; attempt <= max; attempt++) {
+            ctx.meta.attempts = attempt;
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < max) {
+                    // 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);
+                }
+            }
+        }
+        // Every attempt failed — surface the last error upstream
+        throw lastErr;
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/policies/retry.js.map

@@ -0,0 +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"}

package/dist/policies/timeout.cjs

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TotalTimeoutError = exports.TimeoutError = void 0;
+exports.timeoutPolicy = timeoutPolicy;
+exports.totalTimeoutPolicy = totalTimeoutPolicy;
+// ─── Errors ───────────────────────────────────────────────────────────────────
+class TimeoutError extends Error {
+    constructor(ms) {
+        super(`ACT timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+        this.ms = ms;
+    }
+}
+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.
+ */
+class TotalTimeoutError extends Error {
+    constructor(ms) {
+        super(`ACT total timeout exceeded after ${ms}ms`);
+        this.name = 'TotalTimeoutError';
+        this.ms = ms;
+    }
+}
+exports.TotalTimeoutError = TotalTimeoutError;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Shared race-against-a-timer logic. ErrorCtor lets callers pick the error type. */
+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); });
+    });
+}
+// ─── Policies ─────────────────────────────────────────────────────────────────
+/**
+ * Races fn against a hard deadline.
+ * Rejects with TimeoutError if the deadline fires first.
+ *
+ * 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.
+ *
+ * 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.
+ */
+function totalTimeoutPolicy(opts) {
+    return makeTimeoutPolicy(opts, TotalTimeoutError);
+}

package/dist/policies/timeout.d.ts

@@ -0,0 +1,30 @@
+import type { PolicyApplier, TimeoutOptions } from '../types/index.js';
+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.
+ */
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function totalTimeoutPolicy<T>(opts: TimeoutOptions): PolicyApplier<T>;
+//# sourceMappingURL=timeout.d.ts.map

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

@@ -0,0 +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"}

package/dist/policies/timeout.js

@@ -0,0 +1,51 @@
+// ─── Errors ───────────────────────────────────────────────────────────────────
+export class TimeoutError extends Error {
+    constructor(ms) {
+        super(`ACT timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+        this.ms = ms;
+    }
+}
+/**
+ * Thrown when the total budget across all attempts is exceeded.
+ * Distinct from TimeoutError (per-attempt) so callers can instanceof-check
+ * which deadline fired.
+ */
+export class TotalTimeoutError extends Error {
+    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. */
+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); });
+    });
+}
+// ─── Policies ─────────────────────────────────────────────────────────────────
+/**
+ * Races fn against a hard deadline.
+ * Rejects with TimeoutError if the deadline fires first.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function totalTimeoutPolicy(opts) {
+    return makeTimeoutPolicy(opts, TotalTimeoutError);
+}
+//# sourceMappingURL=timeout.js.map

package/dist/policies/timeout.js.map

@@ -0,0 +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"}

package/dist/state/store.cjs

@@ -0,0 +1,41 @@
+"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;

package/dist/state/store.d.ts

@@ -0,0 +1,13 @@
+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;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +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"}

package/dist/state/store.js

@@ -0,0 +1,38 @@
+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;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/state/store.js.map

@@ -0,0 +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"}

package/dist/types/index.cjs

@@ -0,0 +1,3 @@
+"use strict";
+// ─── Public surface ────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -0,0 +1,116 @@
+/** The async function ACT wraps */
+export type ActFn<T> = () => Promise<T>;
+/** Where a successful result came from */
+export type ActSource = 'fresh' | 'cache';
+export interface ActSuccess<T> {
+    ok: true;
+    value: T;
+    source: ActSource;
+    /** Number of attempts made before success */
+    attempts: number;
+}
+export interface ActFailure {
+    ok: false;
+    error: unknown;
+    /** Number of attempts made before final failure */
+    attempts: number;
+}
+export type ActResult<T> = ActSuccess<T> | ActFailure;
+export interface RetryOptions {
+    /** Total number of attempts including the first call. Must be >= 1. */
+    attempts: number;
+    /** Base delay between attempts in ms. 0 = no delay. */
+    delayMs?: number;
+    /**
+     * How the base delay grows per attempt:
+     *  - 'none'        -> always delayMs
+     *  - 'linear'      -> delayMs * attempt
+     *  - 'exponential' -> delayMs * 2^(attempt-1)
+     */
+    backoff?: 'none' | 'linear' | 'exponential';
+    /**
+     * Predicate called after each failure, before the next attempt.
+     * Return false to stop retrying immediately and surface the error.
+     *
+     * Use this to skip retries for errors that are definitively non-recoverable
+     * (e.g. HTTP 4xx, AuthError, ValidationError).
+     *
+     * @param error   The error thrown by the most recent attempt.
+     * @param attempt The 1-based number of the attempt that just failed.
+     *
+     * @example
+     * shouldRetry: (err, attempt) =>
+     *   !(err instanceof HttpError && err.status < 500)
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+export interface TimeoutOptions {
+    /** Abort after this many ms */
+    ms: number;
+}
+export interface DedupeOptions {
+    /**
+     * Collapse concurrent calls sharing the same key into one in-flight Promise.
+     * Opt-in: be explicit when you want this behaviour.
+     */
+    enabled: boolean;
+}
+export interface CacheOptions {
+    /** Keep a successful result for this many ms */
+    ttl: number;
+}
+export interface ActOptions {
+    retry?: RetryOptions;
+    timeout?: TimeoutOptions;
+    /**
+     * Collapse concurrent calls with the same key into one in-flight Promise.
+     *
+     * Shorthand:  `dedupe: true`
+     * Full form:  `dedupe: { enabled: true }`
+     *
+     * Both are equivalent. The object form exists for forward compatibility.
+     */
+    dedupe?: boolean | DedupeOptions;
+    cache?: CacheOptions;
+    /**
+     * Hard budget over the ENTIRE operation — including all retry attempts,
+     * delays, and the timeout per attempt.
+     *
+     * Distinct from `timeout`, which resets the clock on every attempt.
+     * Use both together to express: "each attempt may take at most X ms,
+     * but the whole thing must finish within Y ms."
+     *
+     * Rejects with TotalTimeoutError if the deadline fires.
+     */
+    totalTimeout?: TimeoutOptions;
+}
+/**
+ * Mutable bag mutated in-place during execution.
+ * Policies annotate it; act() reads the final state to build ActResult.
+ */
+export interface RunMeta {
+    attempts: number;
+    source: ActSource;
+}
+/** Everything a policy receives about the current run */
+export interface PolicyContext {
+    key: string;
+    store: StateStore;
+    meta: RunMeta;
+}
+/**
+ * The ONLY shape the executor knows about policies.
+ *
+ * A policy wraps ActFn<T> and returns a new ActFn<T>.
+ * It may intercept before, after, or instead of the inner call.
+ * The executor never imports a concrete policy — only this type.
+ */
+export type PolicyApplier<T> = (fn: ActFn<T>, ctx: PolicyContext) => ActFn<T>;
+/** Minimal key-value contract used by dedupe and cache policies */
+export interface StateStore {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAEA,mCAAmC;AACnC,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;AAEvC,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzC,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,EAAE,EAAE,IAAI,CAAA;IACR,KAAK,EAAE,CAAC,CAAA;IACR,MAAM,EAAE,SAAS,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE,OAAO,CAAA;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAA;AAIrD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B,OAAO,CAAC,EAAO,cAAc,CAAA;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAQ,OAAO,GAAG,aAAa,CAAA;IACtC,KAAK,CAAC,EAAS,YAAY,CAAA;IAC3B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,cAAc,CAAA;CAC9B;AAID;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAI,SAAS,CAAA;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAI,MAAM,CAAA;IACb,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAG,OAAO,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;AAI7E,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,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;CAC1B"}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+// ─── Public surface ────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,kFAAkF"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "actly",
+  "version": "1.0.0",
+  "description": "A reliability primitive for executing async actions safely.",
+  "keywords": [
+    "reliability",
+    "retry",
+    "timeout",
+    "dedupe",
+    "cache",
+    "async"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "jest"
+  },
+  "jest": {
+    "preset": "ts-jest/presets/default-esm",
+    "testEnvironment": "node",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "useESM": true,
+          "tsconfig": {
+            "module": "ESNext",
+            "moduleResolution": "bundler"
+          }
+        }
+      ]
+    },
+    "testMatch": [
+      "**/src/__tests__/**/*.test.ts"
+    ],
+    "clearMocks": true,
+    "restoreMocks": true
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.0",
+    "typescript": "^5.4.0"
+  }
+}