actly 1.0.1 → 1.1.0

package/dist/policies/cache.js

@@ -1,21 +1,41 @@
+import { isSyncStore } from '../stores/base.js';
 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.
+ *
+ * Supports both SyncStateStore and AsyncStateStore. The async branch
+ * introduces two await points (get + set) but has no correctness
+ * requirement for same-tick execution — worst case is a cache stampede
+ * on a simultaneous miss, which is standard behaviour without locking.
  */
 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;
+        if (isSyncStore(ctx.store)) {
+            // Fast path — synchronous store, no await needed
+            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;
+        }
+        else {
+            // Async store path
+            const hit = await ctx.store.get(key);
+            if (hit) {
+                ctx.meta.source = 'cache';
+                return hit.value;
+            }
+            const value = await fn();
+            await ctx.store.set(key, { value }, opts.ttl);
+            return value;
         }
-        const value = await fn();
-        ctx.store.set(key, { value }, opts.ttl);
-        return value;
     };
 }
 //# sourceMappingURL=cache.js.map

package/dist/policies/cache.js.map

@@ -1 +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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/policies/cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,EAAE,GAAG,QAAQ,CAAA;AAOnB;;;;;;;;;;GAUG;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,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,iDAAiD;YACjD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;YAC7C,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;gBACzB,OAAO,GAAG,CAAC,KAAK,CAAA;YAClB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;YACxB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YACtD,OAAO,KAAK,CAAA;QACd,CAAC;aAAM,CAAC;YACN,mBAAmB;YACnB,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,CAAC,CAAA;YACnD,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAA;gBACzB,OAAO,GAAG,CAAC,KAAK,CAAA;YAClB,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,EAAE,EAAE,CAAA;YACxB,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,CAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC,CAAA;AACL,CAAC"}

package/dist/policies/dedupe.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dedupePolicy = dedupePolicy;
+const executor_js_1 = require("../core/executor.js");
 // Namespace so dedupe keys never collide with cache keys in the shared store
 const NS = 'dedupe:';
 /**
@@ -9,18 +10,32 @@ const NS = 'dedupe:';
  * The first caller starts the work. Every subsequent caller that arrives before
  * the first resolves gets the same Promise back — no duplicate work.
  *
+ * INVARIANT: requires a SyncStateStore — see stores/base.ts.
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an await between get() and
+ * set(), letting two concurrent callers both see a miss and both launch work.
+ * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
+ * enforce this at runtime for JS callers that bypass TypeScript.
+ *
  * 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;
+    const applier = (fn, ctx) => {
+        // Cast is safe: execute() verifies isSyncStore(ctx.store) before calling
+        // any policy tagged with REQUIRES_SYNC_STORE.
+        const syncCtx = ctx;
+        return async () => {
+            const key = NS + syncCtx.key;
+            const inflight = syncCtx.store.get(key);
+            if (inflight)
+                return inflight;
+            // No TTL — .finally() cleans up regardless of outcome
+            const promise = fn().finally(() => syncCtx.store.delete(key));
+            syncCtx.store.set(key, promise);
+            return promise;
+        };
     };
+    applier[executor_js_1.REQUIRES_SYNC_STORE] = true;
+    return applier;
 }

package/dist/policies/dedupe.d.ts

@@ -5,6 +5,13 @@ import type { PolicyApplier } from '../types/index.js';
  * The first caller starts the work. Every subsequent caller that arrives before
  * the first resolves gets the same Promise back — no duplicate work.
  *
+ * INVARIANT: requires a SyncStateStore — see stores/base.ts.
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an await between get() and
+ * set(), letting two concurrent callers both see a miss and both launch work.
+ * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
+ * enforce this at runtime for JS callers that bypass TypeScript.
+ *
  * Known tradeoff (v1): deduped callers see attempts=1 in their ActResult because
  * the retry counter belongs to the originating call's meta object.
  */

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

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

package/dist/policies/dedupe.js

@@ -1,3 +1,4 @@
+import { REQUIRES_SYNC_STORE } from '../core/executor.js';
 // Namespace so dedupe keys never collide with cache keys in the shared store
 const NS = 'dedupe:';
 /**
@@ -6,19 +7,33 @@ const NS = 'dedupe:';
  * The first caller starts the work. Every subsequent caller that arrives before
  * the first resolves gets the same Promise back — no duplicate work.
  *
+ * INVARIANT: requires a SyncStateStore — see stores/base.ts.
+ * The read-then-write that makes deduplication work must happen in a single
+ * synchronous frame. An async store would introduce an await between get() and
+ * set(), letting two concurrent callers both see a miss and both launch work.
+ * The REQUIRES_SYNC_STORE symbol on the returned PolicyApplier lets execute()
+ * enforce this at runtime for JS callers that bypass TypeScript.
+ *
  * 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;
+    const applier = (fn, ctx) => {
+        // Cast is safe: execute() verifies isSyncStore(ctx.store) before calling
+        // any policy tagged with REQUIRES_SYNC_STORE.
+        const syncCtx = ctx;
+        return async () => {
+            const key = NS + syncCtx.key;
+            const inflight = syncCtx.store.get(key);
+            if (inflight)
+                return inflight;
+            // No TTL — .finally() cleans up regardless of outcome
+            const promise = fn().finally(() => syncCtx.store.delete(key));
+            syncCtx.store.set(key, promise);
+            return promise;
+        };
     };
+    applier[REQUIRES_SYNC_STORE] = true;
+    return applier;
 }
 //# sourceMappingURL=dedupe.js.map

package/dist/policies/dedupe.js.map

@@ -1 +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"}
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/policies/dedupe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAEzD,6EAA6E;AAC7E,MAAM,EAAE,GAAG,SAAS,CAAA;AAOpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE;QAC7D,yEAAyE;QACzE,8CAA8C;QAC9C,MAAM,OAAO,GAAG,GAAoB,CAAA;QAEpC,OAAO,KAAK,IAAI,EAAE;YAChB,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAA;YAE5B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,CAAC,CAAA;YACnD,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAA;YAE7B,sDAAsD;YACtD,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;YAC7D,OAAO,CAAC,KAAK,CAAC,GAAG,CAAa,GAAG,EAAE,OAAO,CAAC,CAAA;YAC3C,OAAO,OAAO,CAAA;QAChB,CAAC,CAAA;IACH,CAAC,CAGA;IAAC,OAA+D,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAA;IAE7F,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/state/store.cjs

@@ -1,41 +1,7 @@
 "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;
+// 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.
+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,2 @@
-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;
-}
+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":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/state/store.js

@@ -1,38 +1,4 @@
-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;
-    }
-}
+// 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.
+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,yEAAyE;AACzE,0EAA0E;AAC1E,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,112 @@
+/**
+ * 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, 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.
+ */
+export interface SyncStateStore {
+    /**
+     * Runtime discriminant. Read by isSyncStore() in execute() to enforce the
+     * dedupe constraint without an instanceof check. 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.
+     * Must be deterministic: after clear() returns, size() must return 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().
+     */
+    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() will throw 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).
+ * There is no enforcement layer above the store boundary.
+ *
+ * # 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.
+ */
+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.
+     * For scoped adapters (e.g. a Redis key-prefix namespace), remove only the
+     * entries owned by this instance — not the entire backing 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.
+     */
+    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;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

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;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"}

package/dist/stores/memory.cjs

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryStore = void 0;
+function isUnrefable(t) {
+    return typeof t.unref === 'function';
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+class InMemoryStore {
+    constructor(options = {}) {
+        // Discriminant read by isSyncStore() in execute() to enforce the dedupe
+        // constraint at runtime for JS callers who bypass TypeScript.
+        this._sync = true;
+        this.entries = new Map();
+        const { autoCleanup = false, cleanupIntervalMs = 30000 } = options;
+        if (autoCleanup) {
+            const timer = setInterval(() => this._sweep(), cleanupIntervalMs);
+            // Prevent the interval from keeping the Node.js process alive when the
+            // application has otherwise finished its work. Safe no-op in browsers.
+            if (isUnrefable(timer))
+                timer.unref();
+            this.cleanupTimer = timer;
+        }
+    }
+    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) {
+        // Delegate to get() so expired entries are evicted on access.
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Remove all entries.
+     * After this call, size() returns 0.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Return the count of live (non-expired) entries.
+     *
+     * Expired entries are evicted during the scan, so repeated calls are
+     * slightly cheaper as the map self-prunes. O(n) in the number of entries.
+     */
+    size() {
+        // Evict expired entries as we scan — keeps the map tidy between sweeps
+        // and ensures the returned count reflects only observable entries.
+        for (const key of this.entries.keys())
+            this.has(key);
+        return this.entries.size;
+    }
+    /**
+     * Stop the background cleanup timer and release internal state.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     *
+     * Call destroy() when discarding a long-lived store instance to prevent
+     * timer leaks. Stores without autoCleanup enabled have nothing to release,
+     * but destroy() is safe to call on them regardless.
+     */
+    destroy() {
+        if (this.cleanupTimer !== undefined) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+    }
+    // Sweep all entries and remove those past their expiry time.
+    // Called by the autoCleanup interval — not part of the public contract.
+    _sweep() {
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt !== null && now > entry.expiresAt) {
+                this.entries.delete(key);
+            }
+        }
+    }
+}
+exports.InMemoryStore = InMemoryStore;

package/dist/stores/memory.d.ts

@@ -0,0 +1,58 @@
+import type { SyncStateStore } from './base.js';
+export interface InMemoryStoreOptions {
+    /**
+     * Periodically sweep and remove expired entries in the background.
+     *
+     * Disabled by default. The store evicts lazily on get()/has() access, which
+     * is sufficient for most use cases. Enable autoCleanup when the store is
+     * long-lived and accumulates many TTL'd entries that are never re-read — for
+     * example, a server-side cache that receives write-heavy traffic with low
+     * subsequent read rates.
+     *
+     * The sweep does not affect observable store semantics: expired entries are
+     * already invisible to get()/has()/size() before the sweep runs.
+     */
+    autoCleanup?: boolean;
+    /**
+     * Interval between background sweeps in milliseconds.
+     * Defaults to 30 000 (30 seconds). Ignored when autoCleanup is false.
+     *
+     * Choose a value appropriate to your TTL distribution — sweeping more often
+     * than your shortest TTL is wasteful; sweeping much less often than your
+     * longest TTL wastes memory.
+     */
+    cleanupIntervalMs?: number;
+}
+export declare class InMemoryStore implements SyncStateStore {
+    readonly _sync: true;
+    private readonly entries;
+    private cleanupTimer;
+    constructor(options?: InMemoryStoreOptions);
+    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.
+     * After this call, size() returns 0.
+     */
+    clear(): void;
+    /**
+     * Return the count of live (non-expired) entries.
+     *
+     * Expired entries are evicted during the scan, so repeated calls are
+     * slightly cheaper as the map self-prunes. O(n) in the number of entries.
+     */
+    size(): number;
+    /**
+     * Stop the background cleanup timer and release internal state.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     *
+     * Call destroy() when discarding a long-lived store instance to prevent
+     * timer leaks. Stores without autoCleanup enabled have nothing to release,
+     * but destroy() is safe to call on them regardless.
+     */
+    destroy(): void;
+    private _sweep;
+}
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAuB/C,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAID,qBAAa,aAAc,YAAW,cAAc;IAGlD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,YAAY,CAA4C;gBAEpD,OAAO,GAAE,oBAAyB;IAY9C,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;IAMnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,IAAI,IAAI,MAAM;IAOd;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,MAAM;CAQf"}