@nifrajs/cache 4.0.0 → 5.0.0

package/README.md

@@ -31,7 +31,12 @@ await cache.invalidateTag(`user:${id}`)
     **immediately** while a **background** refresh runs (deduped). Latency stays flat; data self-heals.
   - **Miss/expired**: awaits `loader`. Concurrent misses for the same key share **one** call (no stampede).
   - A throwing `loader` is **not** cached (and in the background path goes to `onError`, never rejects the caller).
-- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**.
+  - **Store outage**: a store `get` that throws or rejects is a miss, so the loader answers; a `set` that
+    fails still returns the loaded value, and a `fence` that fails leaves that load uncached. Each
+    failure goes to `onStoreError(error, { op })`, which by default logs one line per operation per
+    minute without the key. The explicit `get`, `set`, `delete`, `invalidateTag` and `clear` still
+    reject, so a failed invalidation is never silent.
+- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**. A `delete`, `invalidateTag`, `clear` or newer `set` also stops a `wrap` load or background refresh already running for that key or tag from storing its result, and the next `wrap` loads afresh. A `delete`, `invalidateTag` or `clear` runs after this cache's own async store writes it covers, so a store that applies requests out of order cannot land one after it.
 - TTL: `ttlMs` (→ stale) + optional `swrMs` (→ served-stale window) + optional `tags`.
 
 ## Stores
@@ -45,6 +50,14 @@ opt-in. For a cache shared across instances, implement `CacheStore`
 const cache = createCache({ store: new RedisCacheStore(redis) })
 ```
 
+A store several caches or processes share should also implement the optional `fence(key, tags)` and
+`setIfFence(key, entry, tags, token)`. A `wrap` load takes a fence before it runs and stores its result
+through `setIfFence`, which must refuse, in one atomic step, when a `set` or `delete` of the key, an
+`invalidateTag` of one of its tags, or a `clear` ran since that fence, from any cache. Without them, a
+load running in one process can store a value another process invalidated meanwhile. `MemoryCache`
+implements both, and `cacheStoreCertificationProfile({ fencing: true })` from
+`@nifrajs/testing/certification` checks a store's implementation.
+
 On **Cloudflare Workers** the in-memory cache is per-isolate and short-lived - back it with **CF KV** (or
 the Cache API) via a `CacheStore` for anything that should survive across requests/instances.
 
@@ -52,7 +65,8 @@ the Cache API) via a `CacheStore` for anything that should survive across reques
 
 `observer` receives one event per operation after it settles: `{ op, outcome, startedAt, durationMs,
 key, tag, tagCount, context }`. `outcome` is `hit`, `stale` or `miss` for reads, `ok` for writes and a
-finished background refresh (`op: "revalidate"`), `error` when the store or loader threw. An observer
+finished background refresh (`op: "revalidate"`), `error` when the store or loader threw. A `wrap`
+that loaded through a store outage reports `miss`. An observer
 that throws is swallowed; it never changes a result. Without an observer the cache reads no extra clock.
 
 `cache.for(c)` binds a request (or job) context, and every event carries it. That is how
@@ -75,7 +89,7 @@ whenever it is set.
 
 ## API
 
-- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError?, observer?, beacon?, capabilities? }`.
+- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError?, onStoreError?, observer?, beacon?, capabilities? }`.
 - `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
 - `cache.for(context)` → the same surface bound to a request or job context.
 - `MemoryCache({ maxEntries?, now? })` - the default store; implement `CacheStore` for your own.

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,KAAK,EAIL,YAAY,EAMb,MAAM,YAAY,CAAA;AAuCnB,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CA6O7D"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,KAAK,EAIL,YAAY,EAOb,MAAM,YAAY,CAAA;AAmDnB,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAyW7D"}

package/dist/cache.js

@@ -16,6 +16,16 @@ function assertDuration(value, name) {
         throw new RangeError(`[nifra/cache] ${name} must be a finite non-negative number`);
     }
 }
+const STORE_REPORT_INTERVAL_MS = 60_000;
+const STORE_REPORT_DETAIL_CHARS = 200;
+/** The error's own words with the key cut out, since a store may name the key it failed on. */
+function storeErrorDetail(error, key) {
+    const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    const redacted = key === "" ? text : text.split(key).join("<key>");
+    return redacted.length > STORE_REPORT_DETAIL_CHARS
+        ? `${redacted.slice(0, STORE_REPORT_DETAIL_CHARS)}...`
+        : redacted;
+}
 function notify(observer, event) {
     try {
         const result = observer(event);
@@ -47,9 +57,62 @@ export function createCache(options = {}) {
     const store = options.store ?? new MemoryCache({ now });
     const onError = options.onError ??
         ((error, key) => console.error(`[nifra/cache] revalidate ${JSON.stringify(key)} failed:`, error));
+    const lastStoreReport = new Map();
+    const reportStoreError = (op, key, error) => {
+        try {
+            if (options.onStoreError !== undefined) {
+                options.onStoreError(error, { op });
+                return;
+            }
+            const last = lastStoreReport.get(op);
+            const at = now();
+            if (last !== undefined && at - last < STORE_REPORT_INTERVAL_MS)
+                return;
+            lastStoreReport.set(op, at);
+            console.error(`[nifra/cache] store ${op} failed; loading without the cache (${storeErrorDetail(error, key)})`);
+        }
+        catch {
+            // A failing reporter must not turn a loaded value into an error.
+        }
+    };
+    /** `wrap`'s read: a store that throws or rejects is a miss, so the loader answers. */
+    const readEntry = async (key) => {
+        try {
+            return await store.get(key);
+        }
+        catch (error) {
+            reportStoreError("get", key, error);
+            return undefined;
+        }
+    };
     const observer = options.observer;
     // Single-flight: concurrent loads for the same key share one promise (miss stampede + SWR dedup).
+    // A delete, tag invalidation, clear or newer set withdraws a load's right to store its result, so
+    // a refresh that started before the invalidation cannot write the old value back. A store with
+    // `fence`/`setIfFence` also refuses a load's write after such a change from another cache sharing
+    // it, and a delete, invalidation or clear waits for this cache's async writes it covers, so a store
+    // that applies requests out of order cannot land one of them after it.
     const inflight = new Map();
+    const withdraw = (matches) => {
+        for (const [key, flight] of inflight) {
+            if (!matches(key, flight.tags))
+                continue;
+            flight.withdraw();
+            inflight.delete(key);
+        }
+    };
+    const fencing = typeof store.fence === "function" && typeof store.setIfFence === "function";
+    const writing = new Set();
+    // Run a delete, invalidation or clear after every async write it covers has settled.
+    const after = (matches, change) => {
+        const covered = [];
+        for (const write of writing)
+            if (matches(write.key, write.tags))
+                covered.push(write.done);
+        if (covered.length === 0)
+            return Promise.resolve(change());
+        return Promise.allSettled(covered).then(change);
+    };
     async function get(key) {
         const entry = await store.get(key);
         return entry === undefined ? undefined : entry.value;
@@ -57,27 +120,94 @@ export function createCache(options = {}) {
     async function has(key) {
         return (await store.get(key)) !== undefined;
     }
-    async function set(key, value, opts = {}) {
+    function entryOf(value, opts) {
         const ttlMs = opts.ttlMs ?? defaultTtlMs;
         const swrMs = opts.swrMs ?? 0;
         assertDuration(ttlMs, "ttlMs");
         assertDuration(swrMs, "swrMs");
         const t = now();
-        await store.set(key, { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs }, opts.tags ?? []);
+        return { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs };
+    }
+    async function put(key, entry, tags, fenced) {
+        const pending = fenced !== undefined && store.setIfFence !== undefined
+            ? store.setIfFence(key, entry, tags, fenced.token)
+            : store.set(key, entry, tags);
+        if (!(pending instanceof Promise))
+            return;
+        const record = { key, tags, done: pending };
+        writing.add(record);
+        try {
+            await pending;
+        }
+        finally {
+            writing.delete(record);
+        }
+    }
+    async function write(key, value, opts) {
+        await put(key, entryOf(value, opts), opts.tags ?? []);
+    }
+    function set(key, value, opts = {}) {
+        withdraw((flightKey) => flightKey === key);
+        return write(key, value, opts);
+    }
+    function remove(key) {
+        const matches = (writeKey) => writeKey === key;
+        withdraw(matches);
+        return after(matches, () => store.delete(key));
+    }
+    function invalidateTag(tag) {
+        const matches = (_key, tags) => tags.includes(tag);
+        withdraw(matches);
+        return after(matches, () => store.invalidateTag(tag));
+    }
+    function clear() {
+        withdraw(() => true);
+        return after(() => true, () => store.clear());
     }
     function load(key, loader, opts) {
         const existing = inflight.get(key);
         if (existing !== undefined)
-            return existing;
+            return existing.promise;
+        let withdrawn = false;
         const p = (async () => {
+            // Taken before the loader runs, so a change from another cache during the load refuses its
+            // write. Awaited only when async: a sync store keeps the loader starting synchronously.
+            let fenced;
+            let storable = true;
+            if (fencing) {
+                try {
+                    const token = store.fence?.(key, opts.tags ?? []);
+                    fenced = { token: token instanceof Promise ? await token : token };
+                }
+                catch (error) {
+                    // Without a token the write could land after another cache's invalidation: load uncached.
+                    reportStoreError("fence", key, error);
+                    storable = false;
+                }
+            }
             const value = await loader();
-            await set(key, value, opts);
+            if (!withdrawn && storable) {
+                // Built outside the try: a bad ttlMs is the caller's error, not a store outage.
+                const entry = entryOf(value, opts);
+                try {
+                    await put(key, entry, opts.tags ?? [], fenced);
+                }
+                catch (error) {
+                    reportStoreError("set", key, error);
+                }
+            }
             return value;
         })().finally(() => {
-            if (inflight.get(key) === p)
+            if (inflight.get(key)?.promise === p)
                 inflight.delete(key);
         });
-        inflight.set(key, p);
+        inflight.set(key, {
+            promise: p,
+            tags: opts.tags ?? [],
+            withdraw: () => {
+                withdrawn = true;
+            },
+        });
         return p;
     }
     function revalidate(key, loader, opts, context) {
@@ -99,7 +229,7 @@ export function createCache(options = {}) {
         });
     }
     async function wrap(key, loader, opts = {}) {
-        const entry = await store.get(key);
+        const entry = await readEntry(key);
         if (entry !== undefined) {
             if (now() < entry.staleAt)
                 return entry.value; // fresh hit
@@ -146,7 +276,7 @@ export function createCache(options = {}) {
                 const started = performance.now();
                 let outcome = "error";
                 try {
-                    const entry = await store.get(key);
+                    const entry = await readEntry(key);
                     if (entry !== undefined) {
                         outcome = readOutcome(entry);
                         if (outcome === "stale")
@@ -163,9 +293,9 @@ export function createCache(options = {}) {
                     report(observer, "wrap", outcome, started, key, undefined, opts.tags?.length ?? 0, context);
                 }
             },
-            delete: (key) => settle("delete", key, undefined, 0, () => Promise.resolve(store.delete(key)), "ok"),
-            invalidateTag: (tag) => settle("invalidateTag", undefined, tag, 1, () => Promise.resolve(store.invalidateTag(tag)), "ok"),
-            clear: () => settle("clear", undefined, undefined, 0, () => Promise.resolve(store.clear()), "ok"),
+            delete: (key) => settle("delete", key, undefined, 0, () => remove(key), "ok"),
+            invalidateTag: (tag) => settle("invalidateTag", undefined, tag, 1, () => invalidateTag(tag), "ok"),
+            clear: () => settle("clear", undefined, undefined, 0, clear, "ok"),
             for: bind,
         };
     }
@@ -177,9 +307,9 @@ export function createCache(options = {}) {
             has,
             set,
             wrap,
-            delete: (key) => Promise.resolve(store.delete(key)),
-            invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
-            clear: () => Promise.resolve(store.clear()),
+            delete: remove,
+            invalidateTag,
+            clear,
             for: bind,
         }
         : observed(observer, undefined);

package/dist/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,5 +9,5 @@
  */
 export { createCache } from "./cache.js";
 export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.js";
-export type { Cache, CacheCapabilities, CacheEvent, CacheObserver, CacheOperation, CacheOptions, CacheOutcome, CacheStore, CapabilityBeacon, SetOptions, StoredEntry, WrapOptions, } from "./types.js";
+export type { Cache, CacheCapabilities, CacheEvent, CacheObserver, CacheOperation, CacheOptions, CacheOutcome, CacheStore, CacheStoreOp, CapabilityBeacon, SetOptions, StoredEntry, WrapOptions, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EACV,KAAK,EACL,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EACV,KAAK,EACL,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/memory-cache.d.ts

@@ -17,14 +17,23 @@ export declare class MemoryCache implements CacheStore {
     private expirySweep;
     private readonly maxEntries;
     private readonly now;
+    private readonly keyChanges;
+    private readonly tagChanges;
+    private clearedAt;
+    private forgottenAt;
+    private epoch;
     constructor(options?: MemoryCacheOptions);
     get(key: string): StoredEntry | undefined;
     set(key: string, entry: StoredEntry, tags: readonly string[]): void;
     delete(key: string): void;
     invalidateTag(tag: string): void;
     clear(): void;
+    /** The current epoch: {@link MemoryCache.setIfFence} compares what changed after it. */
+    fence(): number;
+    setIfFence(key: string, entry: StoredEntry, tags: readonly string[], token: unknown): boolean;
     /** Live entry count (for observability/tests). */
     size(): number;
+    private record;
     /** Remove a key and unlink it from every tag set it belonged to. */
     private evict;
     private sweepExpired;

package/dist/memory-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AASzD,MAAM,WAAW,kBAAkB;IACjC;uCACmC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,WAAY,YAAW,UAAU;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,OAAO,GAAE,kBAAuB;IAQ5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAazC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAyBnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMhC,KAAK,IAAI,IAAI;IAMb,kDAAkD;IAClD,IAAI,IAAI,MAAM;IAId,oEAAoE;IACpE,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,YAAY;CAkBrB"}
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAazD,MAAM,WAAW,kBAAkB;IACjC;uCACmC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,WAAY,YAAW,UAAU;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAIlC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,KAAK,CAAI;gBAEL,OAAO,GAAE,kBAAuB;IAQ5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAazC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IA0BnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOhC,KAAK,IAAI,IAAI;IAUb,wFAAwF;IACxF,KAAK,IAAI,MAAM;IAIf,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;IAU7F,kDAAkD;IAClD,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,MAAM;IAWd,oEAAoE;IACpE,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,YAAY;CAkBrB"}

package/dist/memory-cache.js

@@ -1,3 +1,6 @@
+// How many distinct keys (and, separately, tags) the fence remembers changing. A load that outlives
+// this many distinct changes is refused its write, which costs one cache miss, never a stale value.
+const MAX_TRACKED_CHANGES = 65_536;
 export class MemoryCache {
     // Map iteration is insertion-ordered, so the first key is the LRU victim; `get`/`set` re-insert to touch.
     rows = new Map();
@@ -5,6 +8,14 @@ export class MemoryCache {
     expirySweep = this.rows.entries();
     maxEntries;
     now;
+    // The epoch of each key's and tag's latest change, oldest first. Only the change that matters to a
+    // load is compared, so unrelated writes never age its fence out. Bounded: a fence older than a
+    // forgotten change is refused.
+    keyChanges = new Map();
+    tagChanges = new Map();
+    clearedAt = 0;
+    forgottenAt = 0;
+    epoch = 0;
     constructor(options = {}) {
         this.maxEntries = options.maxEntries ?? 10_000;
         if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 0) {
@@ -26,6 +37,7 @@ export class MemoryCache {
         return { value: row.value, expiresAt: row.expiresAt, staleAt: row.staleAt };
     }
     set(key, entry, tags) {
+        this.record(this.keyChanges, key);
         // Incremental expiry keeps cold, high-cardinality keys from occupying the entire bound until
         // their exact key is read. A fixed batch avoids an O(n) latency spike on a write.
         this.sweepExpired(8);
@@ -51,9 +63,11 @@ export class MemoryCache {
         }
     }
     delete(key) {
+        this.record(this.keyChanges, key);
         this.evict(key);
     }
     invalidateTag(tag) {
+        this.record(this.tagChanges, tag);
         const keys = this.tagIndex.get(tag);
         if (keys === undefined)
             return;
@@ -61,14 +75,47 @@ export class MemoryCache {
             this.evict(key);
     }
     clear() {
+        // Every older fence is refused from here on, so the earlier changes need no remembering.
+        this.clearedAt = ++this.epoch;
+        this.keyChanges.clear();
+        this.tagChanges.clear();
         this.rows.clear();
         this.tagIndex.clear();
         this.expirySweep = this.rows.entries();
     }
+    /** The current epoch: {@link MemoryCache.setIfFence} compares what changed after it. */
+    fence() {
+        return this.epoch;
+    }
+    setIfFence(key, entry, tags, token) {
+        if (typeof token !== "number" || !Number.isSafeInteger(token) || token > this.epoch)
+            return false;
+        if (token < this.clearedAt || token < this.forgottenAt)
+            return false;
+        if ((this.keyChanges.get(key) ?? 0) > token)
+            return false;
+        for (const tag of tags)
+            if ((this.tagChanges.get(tag) ?? 0) > token)
+                return false;
+        this.set(key, entry, tags);
+        return true;
+    }
     /** Live entry count (for observability/tests). */
     size() {
         return this.rows.size;
     }
+    record(changes, name) {
+        changes.delete(name);
+        changes.set(name, ++this.epoch);
+        if (changes.size <= MAX_TRACKED_CHANGES)
+            return;
+        const first = changes.entries().next();
+        if (first.done)
+            return;
+        const [oldest, at] = first.value;
+        changes.delete(oldest);
+        this.forgottenAt = Math.max(this.forgottenAt, at);
+    }
     /** Remove a key and unlink it from every tag set it belonged to. */
     evict(key) {
         const row = this.rows.get(key);

package/dist/memory-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-cache.js","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory-cache.js","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -26,7 +26,22 @@ export interface CacheStore {
     /** Drop every entry carrying `tag`. */
     invalidateTag(tag: string): void | Promise<void>;
     clear(): void | Promise<void>;
+    /**
+     * Optional, with {@link CacheStore.setIfFence}, for a store several caches or processes share. An
+     * opaque token naming this moment for `key` and `tags`. A `wrap` load takes one before it starts.
+     */
+    fence?(key: string, tags: readonly string[]): unknown | Promise<unknown>;
+    /**
+     * Optional, with {@link CacheStore.fence}. Store `entry` only when nothing has run since `fence`
+     * returned `token` that a load must not overwrite: a `set` or `delete` of `key`, an `invalidateTag`
+     * of one of `tags`, or a `clear`, from any cache sharing the store. The check and the write are one
+     * atomic step. Resolves `true` when it wrote. A store that cannot tell may refuse; the load's value
+     * still reaches its caller, it is just not cached.
+     */
+    setIfFence?(key: string, entry: StoredEntry, tags: readonly string[], token: unknown): boolean | Promise<boolean>;
 }
+/** The store call a {@link CacheOptions.onStoreError} report is about. */
+export type CacheStoreOp = "get" | "set" | "fence";
 export interface SetOptions {
     /** Time-to-live (ms) before the value goes stale. Default: the cache's `defaultTtlMs`. */
     readonly ttlMs?: number;
@@ -104,6 +119,14 @@ export interface CacheOptions {
     readonly now?: () => number;
     /** Called when a background SWR revalidation throws. Default: `console.error`. */
     readonly onError?: (error: unknown, key: string) => void;
+    /**
+     * Called when `wrap` meets a store failure: a `get` that throws or rejects is answered as a miss, so
+     * the loader runs, and a `set` that fails still returns the loaded value. A `fence` that fails
+     * leaves that load uncached. Other operations reject as before. Default: one `console.error` line per operation per minute, never naming the key.
+     */
+    readonly onStoreError?: (error: unknown, info: {
+        readonly op: CacheStoreOp;
+    }) => void;
     /**
      * Receives one {@link CacheEvent} per operation - the seam `cacheTracing()` from `@nifrajs/otel/cache`
      * plugs into. Without one the cache reads no extra clock and allocates no event.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gGAAgG;IAChG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;IAC5E,yFAAyF;IACzF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,uCAAuC;IACvC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,2GAA2G;IAC3G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;AAE5E,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,yGAAyG;AACzG,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,KAAK,GACL,KAAK,GACL,MAAM,GACN,QAAQ,GACR,eAAe,GACf,OAAO,GACP,YAAY,CAAA;AAEhB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAA;AAEpE,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;AAEvD,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAA;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IACxD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAClC;AAED,MAAM,WAAW,KAAK;IACpB,kGAAkG;IAClG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACrD,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,iCAAiC;IACjC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,qCAAqC;IACrC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IACjF;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAA;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cache",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Typed KV cache for nifra - TTL, stale-while-revalidate, tag invalidation, and single-flight stampede protection on a pluggable store (in-memory default; bring CF KV / Redis). Dependency-free, runs on Bun/Node/Deno/Workers.",
   "keywords": [
     "bun",

package/src/cache.ts

@@ -19,6 +19,7 @@ import type {
   CacheOptions,
   CacheOutcome,
   CacheStore,
+  CacheStoreOp,
   SetOptions,
   StoredEntry,
   WrapOptions,
@@ -30,6 +31,18 @@ function assertDuration(value: number, name: string): void {
   }
 }
 
+const STORE_REPORT_INTERVAL_MS = 60_000
+const STORE_REPORT_DETAIL_CHARS = 200
+
+/** The error's own words with the key cut out, since a store may name the key it failed on. */
+function storeErrorDetail(error: unknown, key: string): string {
+  const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+  const redacted = key === "" ? text : text.split(key).join("<key>")
+  return redacted.length > STORE_REPORT_DETAIL_CHARS
+    ? `${redacted.slice(0, STORE_REPORT_DETAIL_CHARS)}...`
+    : redacted
+}
+
 function notify(observer: CacheObserver, event: CacheEvent): void {
   try {
     const result: unknown = observer(event)
@@ -73,9 +86,68 @@ export function createCache(options: CacheOptions = {}): Cache {
     ((error, key) =>
       console.error(`[nifra/cache] revalidate ${JSON.stringify(key)} failed:`, error))
 
+  const lastStoreReport = new Map<CacheStoreOp, number>()
+  const reportStoreError = (op: CacheStoreOp, key: string, error: unknown): void => {
+    try {
+      if (options.onStoreError !== undefined) {
+        options.onStoreError(error, { op })
+        return
+      }
+      const last = lastStoreReport.get(op)
+      const at = now()
+      if (last !== undefined && at - last < STORE_REPORT_INTERVAL_MS) return
+      lastStoreReport.set(op, at)
+      console.error(
+        `[nifra/cache] store ${op} failed; loading without the cache (${storeErrorDetail(error, key)})`,
+      )
+    } catch {
+      // A failing reporter must not turn a loaded value into an error.
+    }
+  }
+  /** `wrap`'s read: a store that throws or rejects is a miss, so the loader answers. */
+  const readEntry = async (key: string): Promise<StoredEntry | undefined> => {
+    try {
+      return await store.get(key)
+    } catch (error) {
+      reportStoreError("get", key, error)
+      return undefined
+    }
+  }
+
   const observer = options.observer
   // Single-flight: concurrent loads for the same key share one promise (miss stampede + SWR dedup).
-  const inflight = new Map<string, Promise<unknown>>()
+  // A delete, tag invalidation, clear or newer set withdraws a load's right to store its result, so
+  // a refresh that started before the invalidation cannot write the old value back. A store with
+  // `fence`/`setIfFence` also refuses a load's write after such a change from another cache sharing
+  // it, and a delete, invalidation or clear waits for this cache's async writes it covers, so a store
+  // that applies requests out of order cannot land one of them after it.
+  const inflight = new Map<
+    string,
+    { readonly promise: Promise<unknown>; readonly tags: readonly string[]; withdraw(): void }
+  >()
+  const withdraw = (matches: (key: string, tags: readonly string[]) => boolean): void => {
+    for (const [key, flight] of inflight) {
+      if (!matches(key, flight.tags)) continue
+      flight.withdraw()
+      inflight.delete(key)
+    }
+  }
+  const fencing = typeof store.fence === "function" && typeof store.setIfFence === "function"
+  const writing = new Set<{
+    readonly key: string
+    readonly tags: readonly string[]
+    readonly done: Promise<unknown>
+  }>()
+  // Run a delete, invalidation or clear after every async write it covers has settled.
+  const after = (
+    matches: (key: string, tags: readonly string[]) => boolean,
+    change: () => void | Promise<void>,
+  ): Promise<void> => {
+    const covered: Promise<unknown>[] = []
+    for (const write of writing) if (matches(write.key, write.tags)) covered.push(write.done)
+    if (covered.length === 0) return Promise.resolve(change())
+    return Promise.allSettled(covered).then(change)
+  }
 
   async function get<T = unknown>(key: string): Promise<T | undefined> {
     const entry = await store.get(key)
@@ -86,30 +158,104 @@ export function createCache(options: CacheOptions = {}): Cache {
     return (await store.get(key)) !== undefined
   }
 
-  async function set<T>(key: string, value: T, opts: SetOptions = {}): Promise<void> {
+  function entryOf(value: unknown, opts: SetOptions): StoredEntry {
     const ttlMs = opts.ttlMs ?? defaultTtlMs
     const swrMs = opts.swrMs ?? 0
     assertDuration(ttlMs, "ttlMs")
     assertDuration(swrMs, "swrMs")
     const t = now()
-    await store.set(
-      key,
-      { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs },
-      opts.tags ?? [],
+    return { value, staleAt: t + ttlMs, expiresAt: t + ttlMs + swrMs }
+  }
+
+  async function put(
+    key: string,
+    entry: StoredEntry,
+    tags: readonly string[],
+    fenced?: { readonly token: unknown },
+  ): Promise<void> {
+    const pending =
+      fenced !== undefined && store.setIfFence !== undefined
+        ? store.setIfFence(key, entry, tags, fenced.token)
+        : store.set(key, entry, tags)
+    if (!(pending instanceof Promise)) return
+    const record = { key, tags, done: pending }
+    writing.add(record)
+    try {
+      await pending
+    } finally {
+      writing.delete(record)
+    }
+  }
+
+  async function write<T>(key: string, value: T, opts: SetOptions): Promise<void> {
+    await put(key, entryOf(value, opts), opts.tags ?? [])
+  }
+
+  function set<T>(key: string, value: T, opts: SetOptions = {}): Promise<void> {
+    withdraw((flightKey) => flightKey === key)
+    return write(key, value, opts)
+  }
+
+  function remove(key: string): Promise<void> {
+    const matches = (writeKey: string): boolean => writeKey === key
+    withdraw(matches)
+    return after(matches, () => store.delete(key))
+  }
+
+  function invalidateTag(tag: string): Promise<void> {
+    const matches = (_key: string, tags: readonly string[]): boolean => tags.includes(tag)
+    withdraw(matches)
+    return after(matches, () => store.invalidateTag(tag))
+  }
+
+  function clear(): Promise<void> {
+    withdraw(() => true)
+    return after(
+      () => true,
+      () => store.clear(),
     )
   }
 
   function load(key: string, loader: () => unknown, opts: WrapOptions): Promise<unknown> {
     const existing = inflight.get(key)
-    if (existing !== undefined) return existing
+    if (existing !== undefined) return existing.promise
+    let withdrawn = false
     const p = (async () => {
+      // Taken before the loader runs, so a change from another cache during the load refuses its
+      // write. Awaited only when async: a sync store keeps the loader starting synchronously.
+      let fenced: { readonly token: unknown } | undefined
+      let storable = true
+      if (fencing) {
+        try {
+          const token = store.fence?.(key, opts.tags ?? [])
+          fenced = { token: token instanceof Promise ? await token : token }
+        } catch (error) {
+          // Without a token the write could land after another cache's invalidation: load uncached.
+          reportStoreError("fence", key, error)
+          storable = false
+        }
+      }
       const value = await loader()
-      await set(key, value, opts)
+      if (!withdrawn && storable) {
+        // Built outside the try: a bad ttlMs is the caller's error, not a store outage.
+        const entry = entryOf(value, opts)
+        try {
+          await put(key, entry, opts.tags ?? [], fenced)
+        } catch (error) {
+          reportStoreError("set", key, error)
+        }
+      }
       return value
     })().finally(() => {
-      if (inflight.get(key) === p) inflight.delete(key)
+      if (inflight.get(key)?.promise === p) inflight.delete(key)
+    })
+    inflight.set(key, {
+      promise: p,
+      tags: opts.tags ?? [],
+      withdraw: () => {
+        withdrawn = true
+      },
     })
-    inflight.set(key, p)
     return p
   }
 
@@ -143,7 +289,7 @@ export function createCache(options: CacheOptions = {}): Cache {
     loader: () => T,
     opts: WrapOptions = {},
   ): Promise<Awaited<T>> {
-    const entry = await store.get(key)
+    const entry = await readEntry(key)
     if (entry !== undefined) {
       if (now() < entry.staleAt) return entry.value as Awaited<T> // fresh hit
       revalidate(key, loader as () => unknown, opts, undefined) // stale-but-live → serve stale, refresh in background
@@ -200,7 +346,7 @@ export function createCache(options: CacheOptions = {}): Cache {
         const started = performance.now()
         let outcome: CacheOutcome = "error"
         try {
-          const entry = await store.get(key)
+          const entry = await readEntry(key)
           if (entry !== undefined) {
             outcome = readOutcome(entry)
             if (outcome === "stale") revalidate(key, loader, opts, context)
@@ -224,19 +370,10 @@ export function createCache(options: CacheOptions = {}): Cache {
           )
         }
       },
-      delete: (key) =>
-        settle("delete", key, undefined, 0, () => Promise.resolve(store.delete(key)), "ok"),
+      delete: (key) => settle("delete", key, undefined, 0, () => remove(key), "ok"),
       invalidateTag: (tag) =>
-        settle(
-          "invalidateTag",
-          undefined,
-          tag,
-          1,
-          () => Promise.resolve(store.invalidateTag(tag)),
-          "ok",
-        ),
-      clear: () =>
-        settle("clear", undefined, undefined, 0, () => Promise.resolve(store.clear()), "ok"),
+        settle("invalidateTag", undefined, tag, 1, () => invalidateTag(tag), "ok"),
+      clear: () => settle("clear", undefined, undefined, 0, clear, "ok"),
       for: bind,
     }
   }
@@ -251,9 +388,9 @@ export function createCache(options: CacheOptions = {}): Cache {
           has,
           set,
           wrap,
-          delete: (key) => Promise.resolve(store.delete(key)),
-          invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
-          clear: () => Promise.resolve(store.clear()),
+          delete: remove,
+          invalidateTag,
+          clear,
           for: bind,
         }
       : observed(observer, undefined)

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   CacheOptions,
   CacheOutcome,
   CacheStore,
+  CacheStoreOp,
   CapabilityBeacon,
   SetOptions,
   StoredEntry,

package/src/memory-cache.ts

@@ -12,6 +12,10 @@ interface Row {
   tags: readonly string[]
 }
 
+// How many distinct keys (and, separately, tags) the fence remembers changing. A load that outlives
+// this many distinct changes is refused its write, which costs one cache miss, never a stale value.
+const MAX_TRACKED_CHANGES = 65_536
+
 export interface MemoryCacheOptions {
   /** Evict the least-recently-used entry once the count exceeds this. Default 10,000; `0` explicitly
    * opts into an unbounded cache. */
@@ -27,6 +31,14 @@ export class MemoryCache implements CacheStore {
   private expirySweep = this.rows.entries()
   private readonly maxEntries: number
   private readonly now: () => number
+  // The epoch of each key's and tag's latest change, oldest first. Only the change that matters to a
+  // load is compared, so unrelated writes never age its fence out. Bounded: a fence older than a
+  // forgotten change is refused.
+  private readonly keyChanges = new Map<string, number>()
+  private readonly tagChanges = new Map<string, number>()
+  private clearedAt = 0
+  private forgottenAt = 0
+  private epoch = 0
 
   constructor(options: MemoryCacheOptions = {}) {
     this.maxEntries = options.maxEntries ?? 10_000
@@ -50,6 +62,7 @@ export class MemoryCache implements CacheStore {
   }
 
   set(key: string, entry: StoredEntry, tags: readonly string[]): void {
+    this.record(this.keyChanges, key)
     // Incremental expiry keeps cold, high-cardinality keys from occupying the entire bound until
     // their exact key is read. A fixed batch avoids an O(n) latency spike on a write.
     this.sweepExpired(8)
@@ -75,26 +88,58 @@ export class MemoryCache implements CacheStore {
   }
 
   delete(key: string): void {
+    this.record(this.keyChanges, key)
     this.evict(key)
   }
 
   invalidateTag(tag: string): void {
+    this.record(this.tagChanges, tag)
     const keys = this.tagIndex.get(tag)
     if (keys === undefined) return
     for (const key of [...keys]) this.evict(key)
   }
 
   clear(): void {
+    // Every older fence is refused from here on, so the earlier changes need no remembering.
+    this.clearedAt = ++this.epoch
+    this.keyChanges.clear()
+    this.tagChanges.clear()
     this.rows.clear()
     this.tagIndex.clear()
     this.expirySweep = this.rows.entries()
   }
 
+  /** The current epoch: {@link MemoryCache.setIfFence} compares what changed after it. */
+  fence(): number {
+    return this.epoch
+  }
+
+  setIfFence(key: string, entry: StoredEntry, tags: readonly string[], token: unknown): boolean {
+    if (typeof token !== "number" || !Number.isSafeInteger(token) || token > this.epoch)
+      return false
+    if (token < this.clearedAt || token < this.forgottenAt) return false
+    if ((this.keyChanges.get(key) ?? 0) > token) return false
+    for (const tag of tags) if ((this.tagChanges.get(tag) ?? 0) > token) return false
+    this.set(key, entry, tags)
+    return true
+  }
+
   /** Live entry count (for observability/tests). */
   size(): number {
     return this.rows.size
   }
 
+  private record(changes: Map<string, number>, name: string): void {
+    changes.delete(name)
+    changes.set(name, ++this.epoch)
+    if (changes.size <= MAX_TRACKED_CHANGES) return
+    const first = changes.entries().next()
+    if (first.done) return
+    const [oldest, at] = first.value
+    changes.delete(oldest)
+    this.forgottenAt = Math.max(this.forgottenAt, at)
+  }
+
   /** Remove a key and unlink it from every tag set it belonged to. */
   private evict(key: string): void {
     const row = this.rows.get(key)

package/src/types.ts

@@ -28,8 +28,29 @@ export interface CacheStore {
   /** Drop every entry carrying `tag`. */
   invalidateTag(tag: string): void | Promise<void>
   clear(): void | Promise<void>
+  /**
+   * Optional, with {@link CacheStore.setIfFence}, for a store several caches or processes share. An
+   * opaque token naming this moment for `key` and `tags`. A `wrap` load takes one before it starts.
+   */
+  fence?(key: string, tags: readonly string[]): unknown | Promise<unknown>
+  /**
+   * Optional, with {@link CacheStore.fence}. Store `entry` only when nothing has run since `fence`
+   * returned `token` that a load must not overwrite: a `set` or `delete` of `key`, an `invalidateTag`
+   * of one of `tags`, or a `clear`, from any cache sharing the store. The check and the write are one
+   * atomic step. Resolves `true` when it wrote. A store that cannot tell may refuse; the load's value
+   * still reaches its caller, it is just not cached.
+   */
+  setIfFence?(
+    key: string,
+    entry: StoredEntry,
+    tags: readonly string[],
+    token: unknown,
+  ): boolean | Promise<boolean>
 }
 
+/** The store call a {@link CacheOptions.onStoreError} report is about. */
+export type CacheStoreOp = "get" | "set" | "fence"
+
 export interface SetOptions {
   /** Time-to-live (ms) before the value goes stale. Default: the cache's `defaultTtlMs`. */
   readonly ttlMs?: number
@@ -123,6 +144,12 @@ export interface CacheOptions {
   readonly now?: () => number
   /** Called when a background SWR revalidation throws. Default: `console.error`. */
   readonly onError?: (error: unknown, key: string) => void
+  /**
+   * Called when `wrap` meets a store failure: a `get` that throws or rejects is answered as a miss, so
+   * the loader runs, and a `set` that fails still returns the loaded value. A `fence` that fails
+   * leaves that load uncached. Other operations reject as before. Default: one `console.error` line per operation per minute, never naming the key.
+   */
+  readonly onStoreError?: (error: unknown, info: { readonly op: CacheStoreOp }) => void
   /**
    * Receives one {@link CacheEvent} per operation - the seam `cacheTracing()` from `@nifrajs/otel/cache`
    * plugs into. Without one the cache reads no extra clock and allocates no event.