actly 1.1.5 → 1.2.0

package/dist/policies/timeout.d.ts

@@ -1,37 +1,6 @@
 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 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);
-}
+import { TimeoutError, TotalTimeoutError } from '../errors.js';
+export { TimeoutError, TotalTimeoutError };
 /**
  * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
  *

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;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"}
+{"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;AAE5F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAa9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAyF1C;;;;;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,46 +1,16 @@
 import { linkSignal } from '../utils/abort.js';
+import { TimeoutError, TotalTimeoutError } from '../errors.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';
-        this.ms = ms;
-    }
-}
-/**
- * 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;
-    }
-}
+//
+// TimeoutError and TotalTimeoutError live in `src/errors.ts` and
+// now extend `ActlyError` (which extends `Error`). Existing `instanceof
+// Error` and `instanceof TimeoutError` checks continue to work; new
+// `instanceof ActlyError` and `.code` field give consumers a stable
+// discriminator for telemetry.
+//
+// Re-exported here for backwards compatibility with code that imports
+// from `'actly/policies/timeout'` (the deep path).
+export { TimeoutError, TotalTimeoutError };
 // ─── Policy ───────────────────────────────────────────────────────────────────
 /**
  * Build a timeout policy that throws `ErrorCtor` on deadline.
@@ -69,16 +39,21 @@ export class TotalTimeoutError extends Error {
  * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
  */
 function makeTimeoutPolicy(opts, ErrorCtor) {
-    return (fn, _ctx) => async (parentSignal) => {
+    return (fn, ctx) => async (parentSignal) => {
         const controller = new AbortController();
-        const timerError = new ErrorCtor(opts.ms);
+        // Pass key to the error ctor for better debugging context.
+        const timerError = new ErrorCtor(opts.ms, { key: ctx.key });
         // 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);
+        // NOTE: do NOT `unref()` this timer. The timeout IS the operation
+        // the caller is awaiting. unref'ing would let Node exit the process
+        // while a timeout was pending — silently dropping the operation.
+        // The timer is cleared in the finally block below.
+        // Link parent → child. Capture the unlink function so we can clean
+        // up the listener on success path (contract).
+        const unlink = 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.
@@ -90,12 +65,20 @@ function makeTimeoutPolicy(opts, ErrorCtor) {
                     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));
+                const onAbort = () => reject(controller.signal.reason);
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                Promise.resolve(fn(controller.signal)).then((value) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                }, (error) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    reject(error);
+                });
             });
         }
         finally {
             clearTimeout(timer);
+            unlink();
         }
     };
 }

package/dist/policies/timeout.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAE9D,iFAAiF;AACjF,EAAE;AACF,iEAAiE;AACjE,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE;AACpE,+BAA+B;AAC/B,EAAE;AACF,sEAAsE;AACtE,mDAAmD;AAEnD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAE1C,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAS,iBAAiB,CACxB,IAAoB,EACpB,SAAgE;IAEhE,OAAO,CAAC,EAAY,EAAE,GAAkB,EAAY,EAAE,CACpD,KAAK,EAAE,YAAyB,EAAE,EAAE;QAClC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,2DAA2D;QAC3D,MAAM,UAAU,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;QAE3D,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;QACD,kEAAkE;QAClE,oEAAoE;QACpE,iEAAiE;QACjE,mDAAmD;QAEnD,mEAAmE;QACnE,8CAA8C;QAC9C,MAAM,MAAM,GAAG,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;QAEnD,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,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBACtD,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;gBAEpE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CACzC,CAAC,KAAK,EAAE,EAAE;oBACR,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;oBACvD,OAAO,CAAC,KAAK,CAAC,CAAA;gBAChB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;oBACR,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;oBACvD,MAAM,CAAC,KAAK,CAAC,CAAA;gBACf,CAAC,CACF,CAAA;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,EAAE,CAAA;QACV,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

@@ -2,13 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryStore = void 0;
 /**
- * @deprecated since v1.1.5 — import from `'actly'` directly.
+ * @deprecated 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.
+ * in a future major release.
  *
- * The implementation has moved to `src/stores/memory.ts`.
+ * The implementation lives in `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,11 +1,11 @@
 /**
- * @deprecated since v1.1.5 — import from `'actly'` directly.
+ * @deprecated 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.
+ * in a future major release.
  *
- * The implementation has moved to `src/stores/memory.ts`.
+ * The implementation lives in `src/stores/memory.ts`.
  */
 export { InMemoryStore } from '../stores/memory.js';
 //# sourceMappingURL=store.d.ts.map

package/dist/state/store.js

@@ -1,11 +1,11 @@
 /**
- * @deprecated since v1.1.5 — import from `'actly'` directly.
+ * @deprecated 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.
+ * in a future major release.
  *
- * The implementation has moved to `src/stores/memory.ts`.
+ * The implementation lives in `src/stores/memory.ts`.
  */
 export { InMemoryStore } from '../stores/memory.js';
 //# sourceMappingURL=store.js.map

package/dist/stores/memory.cjs

@@ -1,18 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryStore = void 0;
+exports.createDefaultStore = createDefaultStore;
+const limits_js_1 = require("../utils/limits.js");
 function isUnrefable(t) {
     return typeof t.unref === 'function';
 }
 // ─── Implementation ───────────────────────────────────────────────────────────
 /**
- * Reference `SyncStateStore` implementation backed by a `Map`.
+ * Reference `SyncStateStore` implementation backed by a `Map` + doubly-linked
+ * list for LRU.
  *
- * # LRU semantics
+ * # Properties
  *
- * `Map` iteration order is insertion order, so we implement LRU by
- * `delete` + `set` on every access — the most-recently-touched key ends up
- * at the end of the iteration, and the oldest is `entries.keys().next().value`.
+ *  - `size()` is O(1) — tracked via a counter instead of full scan.
+ *  - LRU reordering uses an explicit doubly-linked list, avoiding the
+ *    `delete + set` Map churn that was 2 Map operations per `get()`.
+ *  - Default `maxSize` is bounded (`LIMITS.DEFAULT_STORE_MAX_SIZE`) when
+ *    used as the module-level default — prevents unbounded memory growth
+ *    in long-running servers.
  *
  * # Expiry
  *
@@ -21,8 +27,10 @@ function isUnrefable(t) {
  */
 class InMemoryStore {
     _sync = true;
-    entries = new Map();
+    map = new Map();
     maxSize;
+    head; // least recently used
+    tail; // most recently used
     cleanupTimer;
     constructor(options = {}) {
         const { autoCleanup = false, cleanupIntervalMs = 30_000, maxSize = Number.POSITIVE_INFINITY, } = options;
@@ -42,74 +50,81 @@ class InMemoryStore {
         }
     }
     get(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
+        const node = this.map.get(key);
+        if (!node)
             return undefined;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
+        if (node.expiresAt !== null && Date.now() > node.expiresAt) {
+            this._removeNode(node);
+            this.map.delete(key);
             return undefined;
         }
-        // LRU refresh: move to most-recent position.
-        // delete + set is the canonical pattern for reordering a Map.
-        this.entries.delete(key);
-        this.entries.set(key, entry);
-        return entry.value;
+        // LRU refresh: move to tail (most-recent).
+        this._moveToTail(node);
+        return node.value;
     }
     set(key, value, ttlMs) {
-        // Evict if at capacity AND adding a new key (updates don't grow size).
-        if (!this.entries.has(key) && this.entries.size >= this.maxSize) {
-            const oldest = this.entries.keys().next().value;
-            if (oldest !== undefined)
-                this.entries.delete(oldest);
+        const existing = this.map.get(key);
+        const now = Date.now();
+        if (existing) {
+            // Update in place — don't grow size, don't evict.
+            existing.value = value;
+            existing.expiresAt = ttlMs != null && ttlMs > 0 ? now + ttlMs : null;
+            existing.insertedAt = now;
+            this._moveToTail(existing);
+            return;
+        }
+        // New key — evict if at capacity.
+        while (this.map.size >= this.maxSize && this.head) {
+            const evict = this.head;
+            this._removeNode(evict);
+            this.map.delete(evict.key);
         }
-        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
-        // delete + set ensures the key is moved to the most-recent position
-        // even on update, keeping LRU order consistent.
-        this.entries.delete(key);
-        this.entries.set(key, { value, expiresAt });
+        const node = {
+            key,
+            value,
+            expiresAt: ttlMs != null && ttlMs > 0 ? now + ttlMs : null,
+            insertedAt: now,
+        };
+        this.map.set(key, node);
+        this._appendTail(node);
     }
     delete(key) {
-        this.entries.delete(key);
+        const node = this.map.get(key);
+        if (!node)
+            return;
+        this._removeNode(node);
+        this.map.delete(key);
     }
     has(key) {
         // Inline the expiry check to avoid the LRU side-effect of get().
         // `has()` should be a pure query, not a touch.
-        const entry = this.entries.get(key);
-        if (!entry)
+        const node = this.map.get(key);
+        if (!node)
             return false;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
+        if (node.expiresAt !== null && Date.now() > node.expiresAt) {
+            this._removeNode(node);
+            this.map.delete(key);
             return false;
         }
         return true;
     }
     clear() {
-        this.entries.clear();
+        this.map.clear();
+        this.head = undefined;
+        this.tail = undefined;
     }
     /**
      * Return the count of live (non-expired) entries.
      *
-     * Pure query — does NOT touch LRU order. Expired entries discovered during
-     * the scan are evicted opportunistically (they were already invisible to
-     * `get()`, so eviction has no observable effect beyond memory reclamation).
+     * O(1) — returns the Map size directly. Expired-but-not-yet-
+     * evicted entries are counted; they're reclaimed lazily on next access
+     * or by the background sweep. This is intentional: a fully-accurate
+     * count would require an O(n) scan, defeating the purpose.
      *
-     * Two-pass to avoid mutating the Map during iteration (spec-safe).
+     * Pure query — does NOT touch LRU order.
      */
     size() {
-        const now = Date.now();
-        const expired = [];
-        let count = 0;
-        for (const [key, entry] of this.entries) {
-            if (entry.expiresAt !== null && entry.expiresAt <= now) {
-                expired.push(key);
-            }
-            else {
-                count++;
-            }
-        }
-        for (const key of expired)
-            this.entries.delete(key);
-        return count;
+        return this.map.size;
     }
     /**
      * Stop the background cleanup timer and release internal state.
@@ -121,20 +136,78 @@ class InMemoryStore {
             this.cleanupTimer = undefined;
         }
     }
+    // ─── LRU list operations ──────────────────────────────────────────────────
+    //
+    // All operations are O(1). The list runs head (LRU) → tail (MRU).
+    _appendTail(node) {
+        if (this.tail) {
+            this.tail.next = node;
+            node.prev = this.tail;
+            node.next = undefined;
+        }
+        else {
+            // Empty list — node is both head and tail.
+            this.head = node;
+        }
+        this.tail = node;
+    }
+    _removeNode(node) {
+        if (node.prev) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+        node.prev = undefined;
+        node.next = undefined;
+    }
+    _moveToTail(node) {
+        if (this.tail === node)
+            return; // already MRU
+        this._removeNode(node);
+        this._appendTail(node);
+    }
     /**
      * Sweep all entries and remove those past their expiry time.
      * Called by the autoCleanup interval; not part of the public contract.
+     *
+     * Two-pass to avoid mutating the Map during iteration (spec-safe).
      */
     _sweep() {
         const now = Date.now();
         const expired = [];
-        for (const [key, entry] of this.entries) {
-            if (entry.expiresAt !== null && now > entry.expiresAt) {
+        for (const [key, node] of this.map) {
+            if (node.expiresAt !== null && now > node.expiresAt) {
                 expired.push(key);
             }
         }
-        for (const key of expired)
-            this.entries.delete(key);
+        for (const key of expired) {
+            const node = this.map.get(key);
+            if (node) {
+                this._removeNode(node);
+                this.map.delete(key);
+            }
+        }
     }
 }
 exports.InMemoryStore = InMemoryStore;
+/**
+ * Factory for the default module-level store.
+ *
+ * Bounded by `LIMITS.DEFAULT_STORE_MAX_SIZE` with background sweep —
+ * prevents unbounded memory growth in long-running servers without
+ * requiring callers to opt in.
+ */
+function createDefaultStore() {
+    return new InMemoryStore({
+        maxSize: limits_js_1.LIMITS.DEFAULT_STORE_MAX_SIZE,
+        autoCleanup: true,
+        cleanupIntervalMs: limits_js_1.LIMITS.DEFAULT_STORE_CLEANUP_INTERVAL_MS,
+    });
+}

package/dist/stores/memory.d.ts

@@ -3,11 +3,9 @@ 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.
+     * Disabled by default for explicit-store users. The DEFAULT module-level
+     * store (used when you call `act()` without `withStore()`) enables this
+     * automatically — see `core/act.ts`.
      */
     autoCleanup?: boolean;
     /**
@@ -26,18 +24,23 @@ export interface InMemoryStoreOptions {
      * caches with high-cardinality keys to bound memory usage.
      *
      * The LRU order is updated on `get()` and `set()` — both move the accessed
-     * key to the most-recent position.
+     * key to the most-recent position. Implementation uses a doubly-linked
+     * list for O(1) reordering (no `delete + set` Map churn).
      */
     maxSize?: number;
 }
 /**
- * Reference `SyncStateStore` implementation backed by a `Map`.
+ * Reference `SyncStateStore` implementation backed by a `Map` + doubly-linked
+ * list for LRU.
  *
- * # LRU semantics
+ * # Properties
  *
- * `Map` iteration order is insertion order, so we implement LRU by
- * `delete` + `set` on every access — the most-recently-touched key ends up
- * at the end of the iteration, and the oldest is `entries.keys().next().value`.
+ *  - `size()` is O(1) — tracked via a counter instead of full scan.
+ *  - LRU reordering uses an explicit doubly-linked list, avoiding the
+ *    `delete + set` Map churn that was 2 Map operations per `get()`.
+ *  - Default `maxSize` is bounded (`LIMITS.DEFAULT_STORE_MAX_SIZE`) when
+ *    used as the module-level default — prevents unbounded memory growth
+ *    in long-running servers.
  *
  * # Expiry
  *
@@ -46,8 +49,10 @@ export interface InMemoryStoreOptions {
  */
 export declare class InMemoryStore implements SyncStateStore {
     readonly _sync: true;
-    private readonly entries;
+    private readonly map;
     private readonly maxSize;
+    private head?;
+    private tail?;
     private cleanupTimer;
     constructor(options?: InMemoryStoreOptions);
     get<T>(key: string): T | undefined;
@@ -58,11 +63,12 @@ export declare class InMemoryStore implements SyncStateStore {
     /**
      * Return the count of live (non-expired) entries.
      *
-     * Pure query — does NOT touch LRU order. Expired entries discovered during
-     * the scan are evicted opportunistically (they were already invisible to
-     * `get()`, so eviction has no observable effect beyond memory reclamation).
+     * O(1) — returns the Map size directly. Expired-but-not-yet-
+     * evicted entries are counted; they're reclaimed lazily on next access
+     * or by the background sweep. This is intentional: a fully-accurate
+     * count would require an O(n) scan, defeating the purpose.
      *
-     * Two-pass to avoid mutating the Map during iteration (spec-safe).
+     * Pure query — does NOT touch LRU order.
      */
     size(): number;
     /**
@@ -70,10 +76,23 @@ export declare class InMemoryStore implements SyncStateStore {
      * Safe to call multiple times — subsequent calls are no-ops.
      */
     destroy(): void;
+    private _appendTail;
+    private _removeNode;
+    private _moveToTail;
     /**
      * Sweep all entries and remove those past their expiry time.
      * Called by the autoCleanup interval; not part of the public contract.
+     *
+     * Two-pass to avoid mutating the Map during iteration (spec-safe).
      */
     private _sweep;
 }
+/**
+ * Factory for the default module-level store.
+ *
+ * Bounded by `LIMITS.DEFAULT_STORE_MAX_SIZE` with background sweep —
+ * prevents unbounded memory growth in long-running servers without
+ * requiring callers to opt in.
+ */
+export declare function createDefaultStore(): InMemoryStore;
 //# sourceMappingURL=memory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAwB/C,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,YAAY,CAA4C;gBAEpD,OAAO,GAAE,oBAAyB;IA0B9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAiBlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAcnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAIb;;;;;;;;OAQG;IACH,IAAI,IAAI,MAAM;IAiBd;;;OAGG;IACH,OAAO,IAAI,IAAI;IAOf;;;OAGG;IACH,OAAO,CAAC,MAAM;CAUf"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAkC/C,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,YAAY,CAA4C;gBAEpD,OAAO,GAAE,oBAAyB;IA0B9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAgBlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IA8BnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAazB,KAAK,IAAI,IAAI;IAMb;;;;;;;;;OASG;IACH,IAAI,IAAI,MAAM;IAId;;;OAGG;IACH,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACH,OAAO,CAAC,MAAM;CAgBf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAMlD"}