@nifrajs/cache 3.3.0 → 4.0.0

package/README.md

@@ -48,10 +48,36 @@ const cache = createCache({ store: new RedisCacheStore(redis) })
 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.
 
+## Observing operations and tracing
+
+`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
+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
+`cacheTracing()` from `@nifrajs/otel/cache` turns each operation into a child span of `c.trace`:
+
+```ts
+import { cacheTracing } from "@nifrajs/otel/cache"
+
+const cache = createCache({ observer: cacheTracing({ exporter }) })
+app.use(tracing({ exporter })).get("/orders/:user", (c) =>
+  cache.for(c).wrap(`orders:${c.params.user}`, () => loadOrders(c.params.user)), // span "cache wrap"
+)
+```
+
+The raw key goes to the in-process observer only. `cacheTracing` exports the key prefix (the token
+before the first `:`, when it is a short lowercase name) unless `keyAttribute` says otherwise
+(`"none"`, or a function that owns the redaction). A stale read's background refresh is its own trace,
+linked to the request span. `for(c)` needs a `beacon`, an `observer`, or both; the beacon is enforced
+whenever it is set.
+
 ## API
 
-- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError? }`.
+- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError?, 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.
 
 ## For AI agents

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAuC,MAAM,YAAY,CAAA;AAQ1F,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAgI7D"}
+{"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"}

package/dist/cache.js

@@ -16,6 +16,28 @@ function assertDuration(value, name) {
         throw new RangeError(`[nifra/cache] ${name} must be a finite non-negative number`);
     }
 }
+function notify(observer, event) {
+    try {
+        const result = observer(event);
+        if (result instanceof Promise)
+            result.catch(() => undefined);
+    }
+    catch {
+        // An observer can never change a cache result.
+    }
+}
+function report(observer, op, outcome, started, key, tag, tagCount, context) {
+    notify(observer, {
+        op,
+        outcome,
+        startedAt: performance.timeOrigin + started,
+        durationMs: performance.now() - started,
+        key,
+        tag,
+        tagCount,
+        context,
+    });
+}
 /** Create a cache over the given (or a fresh in-memory) store. */
 export function createCache(options = {}) {
     const defaultTtlMs = options.defaultTtlMs ?? 60_000;
@@ -25,6 +47,7 @@ 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 observer = options.observer;
     // Single-flight: concurrent loads for the same key share one promise (miss stampede + SWR dedup).
     const inflight = new Map();
     async function get(key) {
@@ -57,10 +80,16 @@ export function createCache(options = {}) {
         inflight.set(key, p);
         return p;
     }
-    function revalidate(key, loader, opts) {
+    function revalidate(key, loader, opts, context) {
         if (inflight.has(key))
             return; // a refresh is already running
-        void load(key, loader, opts).catch((error) => {
+        const started = observer === undefined ? 0 : performance.now();
+        const refresh = load(key, loader, opts);
+        if (observer !== undefined) {
+            const tagCount = opts.tags?.length ?? 0;
+            refresh.then(() => report(observer, "revalidate", "ok", started, key, undefined, tagCount, context), () => report(observer, "revalidate", "error", started, key, undefined, tagCount, context));
+        }
+        void refresh.catch((error) => {
             try {
                 onError(error, key);
             }
@@ -74,30 +103,96 @@ export function createCache(options = {}) {
         if (entry !== undefined) {
             if (now() < entry.staleAt)
                 return entry.value; // fresh hit
-            revalidate(key, loader, opts); // stale-but-live → serve stale, refresh in background
+            revalidate(key, loader, opts, undefined); // stale-but-live → serve stale, refresh in background
             return entry.value;
         }
         return (await load(key, loader, opts)); // miss → load (single-flight)
     }
+    const readOutcome = (entry) => entry === undefined ? "miss" : now() < entry.staleAt ? "hit" : "stale";
+    // A separate surface rather than branches in the plain one, so a cache without an observer runs
+    // exactly the code it ran before observers existed.
+    function observed(observer, context) {
+        const settle = async (op, key, tag, tagCount, run, success) => {
+            const started = performance.now();
+            let outcome = "error";
+            try {
+                const value = await run();
+                outcome = success;
+                return value;
+            }
+            finally {
+                report(observer, op, outcome, started, key, tag, tagCount, context);
+            }
+        };
+        const read = async (op, key, pick) => {
+            const started = performance.now();
+            let outcome = "error";
+            try {
+                const entry = await store.get(key);
+                outcome = readOutcome(entry);
+                return pick(entry);
+            }
+            finally {
+                report(observer, op, outcome, started, key, undefined, 0, context);
+            }
+        };
+        return {
+            get: (key) => read("get", key, (entry) => 
+            // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the store keeps values untyped; T is the caller's claim for this key, exactly as in the plain get().
+            entry === undefined ? undefined : entry.value),
+            has: (key) => read("has", key, (entry) => entry !== undefined),
+            set: (key, value, opts) => settle("set", key, undefined, opts?.tags?.length ?? 0, () => set(key, value, opts), "ok"),
+            async wrap(key, loader, opts = {}) {
+                const started = performance.now();
+                let outcome = "error";
+                try {
+                    const entry = await store.get(key);
+                    if (entry !== undefined) {
+                        outcome = readOutcome(entry);
+                        if (outcome === "stale")
+                            revalidate(key, loader, opts, context);
+                        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the store keeps values untyped; a wrap of this key stored what a loader of the caller's T returned.
+                        return entry.value;
+                    }
+                    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: load() resolves to what this loader returned, or what a concurrent wrap of the same key loaded for the same T.
+                    const value = (await load(key, loader, opts));
+                    outcome = "miss";
+                    return value;
+                }
+                finally {
+                    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"),
+            for: bind,
+        };
+    }
     const readToken = options.capabilities?.read ?? "cache.read";
     const writeToken = options.capabilities?.write ?? "cache.write";
-    const plain = {
-        get,
-        has,
-        set,
-        wrap,
-        delete: (key) => Promise.resolve(store.delete(key)),
-        invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
-        clear: () => Promise.resolve(store.clear()),
-        for: bind,
-    };
+    const plain = observer === undefined
+        ? {
+            get,
+            has,
+            set,
+            wrap,
+            delete: (key) => Promise.resolve(store.delete(key)),
+            invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
+            clear: () => Promise.resolve(store.clear()),
+            for: bind,
+        }
+        : observed(observer, undefined);
     // Built per call rather than cached per context: a cache keyed by context would hold every request's
     // context object for the process lifetime, which is a leak with a request body attached to it.
     function bind(context) {
         const beacon = options.beacon;
-        if (beacon === undefined) {
-            throw new Error("@nifrajs/cache: for(context) needs a beacon - pass `beacon: useCapability` (from @nifrajs/core/capabilities) to createCache");
+        if (beacon === undefined && observer === undefined) {
+            throw new Error("@nifrajs/cache: for(context) needs a beacon or an observer - pass `beacon: useCapability` (from @nifrajs/core/capabilities) or `observer` to createCache");
         }
+        const base = observer === undefined ? plain : observed(observer, context);
+        if (beacon === undefined)
+            return base;
         // A refused capability has to surface as a REJECTION, not a synchronous throw: every method here
         // returns a promise, and a caller who writes `.catch(…)` instead of `try` would otherwise miss it
         // entirely - turning a fail-closed gate into an unhandled crash.
@@ -114,14 +209,14 @@ export function createCache(options = {}) {
         const READ = [readToken];
         const WRITE = [writeToken];
         return {
-            get: (key) => guard(READ, () => plain.get(key)),
-            has: (key) => guard(READ, () => plain.has(key)),
-            set: (key, value, opts) => guard(WRITE, () => plain.set(key, value, opts)),
+            get: (key) => guard(READ, () => base.get(key)),
+            has: (key) => guard(READ, () => base.has(key)),
+            set: (key, value, opts) => guard(WRITE, () => base.set(key, value, opts)),
             // Both, because a miss writes and which one happens is not knowable before the call.
-            wrap: (key, loader, opts) => guard([readToken, writeToken], () => plain.wrap(key, loader, opts)),
-            delete: (key) => guard(WRITE, () => plain.delete(key)),
-            invalidateTag: (tag) => guard(WRITE, () => plain.invalidateTag(tag)),
-            clear: () => guard(WRITE, () => plain.clear()),
+            wrap: (key, loader, opts) => guard([readToken, writeToken], () => base.wrap(key, loader, opts)),
+            delete: (key) => guard(WRITE, () => base.delete(key)),
+            invalidateTag: (tag) => guard(WRITE, () => base.invalidateTag(tag)),
+            clear: () => guard(WRITE, () => base.clear()),
             for: bind,
         };
     }

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, CacheOptions, CacheStore, CapabilityBeacon, SetOptions, StoredEntry, WrapOptions, } from "./types.js";
+export type { Cache, CacheCapabilities, CacheEvent, CacheObserver, CacheOperation, CacheOptions, CacheOutcome, CacheStore, 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,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,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/types.d.ts

@@ -47,6 +47,41 @@ export interface CacheCapabilities {
     readonly read?: string;
     readonly write?: string;
 }
+/** A cache operation reported to a {@link CacheObserver}. `revalidate` is the background SWR refresh. */
+export type CacheOperation = "get" | "has" | "set" | "wrap" | "delete" | "invalidateTag" | "clear" | "revalidate";
+/**
+ * How an operation ended. Reads report `hit`, `stale` (served from the SWR window) or `miss`; writes and
+ * a completed revalidation report `ok`; `error` means the store or the loader threw.
+ */
+export type CacheOutcome = "hit" | "stale" | "miss" | "ok" | "error";
+/** One settled cache operation, as an observer sees it. */
+export interface CacheEvent {
+    readonly op: CacheOperation;
+    readonly outcome: CacheOutcome;
+    /** Epoch ms the operation started. */
+    readonly startedAt: number;
+    /** Monotonic duration in ms. */
+    readonly durationMs: number;
+    /**
+     * The raw key. Keys often hold ids or emails: this value is for in-process use, and an exporter
+     * decides what (if anything) of it leaves the process. Absent for `clear` and `invalidateTag`.
+     */
+    readonly key: string | undefined;
+    /** The tag passed to `invalidateTag`, with the same caution as `key`. */
+    readonly tag: string | undefined;
+    /** Tags written by `set`, `wrap` and `revalidate`; 1 for `invalidateTag`; otherwise 0. */
+    readonly tagCount: number;
+    /**
+     * The context bound with `for(context)`, or `undefined` for the unbound cache. For `revalidate` it is
+     * the context whose read found the stale entry.
+     */
+    readonly context: object | undefined;
+}
+/**
+ * Called once per operation after it settles, never before the caller sees the result. A throwing (or
+ * rejecting) observer is swallowed: it cannot change a cache result.
+ */
+export type CacheObserver = (event: CacheEvent) => void;
 export interface CacheOptions {
     /** Storage adapter. Default: a fresh {@link MemoryCache}. */
     readonly store?: CacheStore;
@@ -69,6 +104,11 @@ export interface CacheOptions {
     readonly now?: () => number;
     /** Called when a background SWR revalidation throws. Default: `console.error`. */
     readonly onError?: (error: unknown, key: string) => 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.
+     */
+    readonly observer?: CacheObserver;
 }
 export interface Cache {
     /** The cached value for `key`, or `undefined` if missing/expired. Pass `T` for the value type. */
@@ -88,15 +128,17 @@ export interface Cache {
      */
     wrap<T>(key: string, loader: () => T, options?: WrapOptions): Promise<Awaited<T>>;
     /**
-     * A view bound to a request context: every operation announces its capability first, and fails closed
-     * when the route did not declare it.
+     * A view bound to a request (or job) context. With a `beacon`, every operation announces its
+     * capability first and fails closed when the route did not declare it. With an `observer`, every
+     * event carries `context`, which is how a tracer parents the span to `context.trace`.
      *
      * `wrap` announces BOTH read and write, because a miss writes and which one happens is not known
      * before the call. A declaration describes what a route may do, so the conservative answer is the
      * correct one.
      *
-     * Requires `beacon`. Without one this throws rather than handing back a cache that quietly produces
-     * no evidence - a beacon nobody notices is missing is the exact failure the beacon exists to prevent.
+     * Requires `beacon` or `observer`. With neither this throws rather than handing back a view that
+     * quietly does nothing - a beacon nobody notices is missing is the exact failure the beacon exists
+     * to prevent.
      */
     for(context: object): Cache;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"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": "3.3.0",
+  "version": "4.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",
@@ -13,6 +13,9 @@
     "cache-tags"
   ],
   "type": "module",
+  "nifra": {
+    "environment": "library"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/cache.ts

@@ -11,7 +11,18 @@
  *   await cache.invalidateTag(`user:${id}`) // on write
  */
 import { MemoryCache } from "./memory-cache.ts"
-import type { Cache, CacheOptions, CacheStore, SetOptions, WrapOptions } from "./types.ts"
+import type {
+  Cache,
+  CacheEvent,
+  CacheObserver,
+  CacheOperation,
+  CacheOptions,
+  CacheOutcome,
+  CacheStore,
+  SetOptions,
+  StoredEntry,
+  WrapOptions,
+} from "./types.ts"
 
 function assertDuration(value: number, name: string): void {
   if (!Number.isFinite(value) || value < 0) {
@@ -19,6 +30,37 @@ function assertDuration(value: number, name: string): void {
   }
 }
 
+function notify(observer: CacheObserver, event: CacheEvent): void {
+  try {
+    const result: unknown = observer(event)
+    if (result instanceof Promise) result.catch(() => undefined)
+  } catch {
+    // An observer can never change a cache result.
+  }
+}
+
+function report(
+  observer: CacheObserver,
+  op: CacheOperation,
+  outcome: CacheOutcome,
+  started: number,
+  key: string | undefined,
+  tag: string | undefined,
+  tagCount: number,
+  context: object | undefined,
+): void {
+  notify(observer, {
+    op,
+    outcome,
+    startedAt: performance.timeOrigin + started,
+    durationMs: performance.now() - started,
+    key,
+    tag,
+    tagCount,
+    context,
+  })
+}
+
 /** Create a cache over the given (or a fresh in-memory) store. */
 export function createCache(options: CacheOptions = {}): Cache {
   const defaultTtlMs = options.defaultTtlMs ?? 60_000
@@ -31,6 +73,7 @@ export function createCache(options: CacheOptions = {}): Cache {
     ((error, key) =>
       console.error(`[nifra/cache] revalidate ${JSON.stringify(key)} failed:`, error))
 
+  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>>()
 
@@ -70,9 +113,23 @@ export function createCache(options: CacheOptions = {}): Cache {
     return p
   }
 
-  function revalidate(key: string, loader: () => unknown, opts: WrapOptions): void {
+  function revalidate(
+    key: string,
+    loader: () => unknown,
+    opts: WrapOptions,
+    context: object | undefined,
+  ): void {
     if (inflight.has(key)) return // a refresh is already running
-    void load(key, loader, opts).catch((error) => {
+    const started = observer === undefined ? 0 : performance.now()
+    const refresh = load(key, loader, opts)
+    if (observer !== undefined) {
+      const tagCount = opts.tags?.length ?? 0
+      refresh.then(
+        () => report(observer, "revalidate", "ok", started, key, undefined, tagCount, context),
+        () => report(observer, "revalidate", "error", started, key, undefined, tagCount, context),
+      )
+    }
+    void refresh.catch((error) => {
       try {
         onError(error, key)
       } catch {
@@ -89,35 +146,129 @@ export function createCache(options: CacheOptions = {}): Cache {
     const entry = await store.get(key)
     if (entry !== undefined) {
       if (now() < entry.staleAt) return entry.value as Awaited<T> // fresh hit
-      revalidate(key, loader as () => unknown, opts) // stale-but-live → serve stale, refresh in background
+      revalidate(key, loader as () => unknown, opts, undefined) // stale-but-live → serve stale, refresh in background
       return entry.value as Awaited<T>
     }
     return (await load(key, loader as () => unknown, opts)) as Awaited<T> // miss → load (single-flight)
   }
 
+  const readOutcome = (entry: StoredEntry | undefined): CacheOutcome =>
+    entry === undefined ? "miss" : now() < entry.staleAt ? "hit" : "stale"
+
+  // A separate surface rather than branches in the plain one, so a cache without an observer runs
+  // exactly the code it ran before observers existed.
+  function observed(observer: CacheObserver, context: object | undefined): Cache {
+    const settle = async <T>(
+      op: CacheOperation,
+      key: string | undefined,
+      tag: string | undefined,
+      tagCount: number,
+      run: () => Promise<T>,
+      success: CacheOutcome,
+    ): Promise<T> => {
+      const started = performance.now()
+      let outcome: CacheOutcome = "error"
+      try {
+        const value = await run()
+        outcome = success
+        return value
+      } finally {
+        report(observer, op, outcome, started, key, tag, tagCount, context)
+      }
+    }
+    const read = async <T>(op: "get" | "has", key: string, pick: (e?: StoredEntry) => T) => {
+      const started = performance.now()
+      let outcome: CacheOutcome = "error"
+      try {
+        const entry = await store.get(key)
+        outcome = readOutcome(entry)
+        return pick(entry)
+      } finally {
+        report(observer, op, outcome, started, key, undefined, 0, context)
+      }
+    }
+    return {
+      get: <T = unknown>(key: string): Promise<T | undefined> =>
+        read("get", key, (entry) =>
+          // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the store keeps values untyped; T is the caller's claim for this key, exactly as in the plain get().
+          entry === undefined ? undefined : (entry.value as T),
+        ),
+      has: (key) => read("has", key, (entry) => entry !== undefined),
+      set: (key, value, opts) =>
+        settle("set", key, undefined, opts?.tags?.length ?? 0, () => set(key, value, opts), "ok"),
+      async wrap<T>(key: string, loader: () => T, opts: WrapOptions = {}): Promise<Awaited<T>> {
+        const started = performance.now()
+        let outcome: CacheOutcome = "error"
+        try {
+          const entry = await store.get(key)
+          if (entry !== undefined) {
+            outcome = readOutcome(entry)
+            if (outcome === "stale") revalidate(key, loader, opts, context)
+            // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the store keeps values untyped; a wrap of this key stored what a loader of the caller's T returned.
+            return entry.value as Awaited<T>
+          }
+          // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: load() resolves to what this loader returned, or what a concurrent wrap of the same key loaded for the same T.
+          const value = (await load(key, loader, opts)) as Awaited<T>
+          outcome = "miss"
+          return value
+        } finally {
+          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"),
+      for: bind,
+    }
+  }
+
   const readToken = options.capabilities?.read ?? "cache.read"
   const writeToken = options.capabilities?.write ?? "cache.write"
 
-  const plain: Cache = {
-    get,
-    has,
-    set,
-    wrap,
-    delete: (key) => Promise.resolve(store.delete(key)),
-    invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
-    clear: () => Promise.resolve(store.clear()),
-    for: bind,
-  }
+  const plain: Cache =
+    observer === undefined
+      ? {
+          get,
+          has,
+          set,
+          wrap,
+          delete: (key) => Promise.resolve(store.delete(key)),
+          invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
+          clear: () => Promise.resolve(store.clear()),
+          for: bind,
+        }
+      : observed(observer, undefined)
 
   // Built per call rather than cached per context: a cache keyed by context would hold every request's
   // context object for the process lifetime, which is a leak with a request body attached to it.
   function bind(context: object): Cache {
     const beacon = options.beacon
-    if (beacon === undefined) {
+    if (beacon === undefined && observer === undefined) {
       throw new Error(
-        "@nifrajs/cache: for(context) needs a beacon - pass `beacon: useCapability` (from @nifrajs/core/capabilities) to createCache",
+        "@nifrajs/cache: for(context) needs a beacon or an observer - pass `beacon: useCapability` (from @nifrajs/core/capabilities) or `observer` to createCache",
       )
     }
+    const base = observer === undefined ? plain : observed(observer, context)
+    if (beacon === undefined) return base
     // A refused capability has to surface as a REJECTION, not a synchronous throw: every method here
     // returns a promise, and a caller who writes `.catch(…)` instead of `try` would otherwise miss it
     // entirely - turning a fail-closed gate into an unhandled crash.
@@ -133,16 +284,16 @@ export function createCache(options: CacheOptions = {}): Cache {
     const WRITE = [writeToken]
     return {
       get: <T = unknown>(key: string): Promise<T | undefined> =>
-        guard(READ, () => plain.get<T>(key)),
-      has: (key) => guard(READ, () => plain.has(key)),
+        guard(READ, () => base.get<T>(key)),
+      has: (key) => guard(READ, () => base.has(key)),
       set: <T>(key: string, value: T, opts?: SetOptions): Promise<void> =>
-        guard(WRITE, () => plain.set(key, value, opts)),
+        guard(WRITE, () => base.set(key, value, opts)),
       // Both, because a miss writes and which one happens is not knowable before the call.
       wrap: <T>(key: string, loader: () => T, opts?: WrapOptions): Promise<Awaited<T>> =>
-        guard([readToken, writeToken], () => plain.wrap(key, loader, opts)),
-      delete: (key) => guard(WRITE, () => plain.delete(key)),
-      invalidateTag: (tag) => guard(WRITE, () => plain.invalidateTag(tag)),
-      clear: () => guard(WRITE, () => plain.clear()),
+        guard([readToken, writeToken], () => base.wrap(key, loader, opts)),
+      delete: (key) => guard(WRITE, () => base.delete(key)),
+      invalidateTag: (tag) => guard(WRITE, () => base.invalidateTag(tag)),
+      clear: () => guard(WRITE, () => base.clear()),
       for: bind,
     }
   }

package/src/index.ts

@@ -13,7 +13,11 @@ export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.ts"
 export type {
   Cache,
   CacheCapabilities,
+  CacheEvent,
+  CacheObserver,
+  CacheOperation,
   CacheOptions,
+  CacheOutcome,
   CacheStore,
   CapabilityBeacon,
   SetOptions,

package/src/types.ts

@@ -54,6 +54,53 @@ export interface CacheCapabilities {
   readonly write?: string
 }
 
+/** A cache operation reported to a {@link CacheObserver}. `revalidate` is the background SWR refresh. */
+export type CacheOperation =
+  | "get"
+  | "has"
+  | "set"
+  | "wrap"
+  | "delete"
+  | "invalidateTag"
+  | "clear"
+  | "revalidate"
+
+/**
+ * How an operation ended. Reads report `hit`, `stale` (served from the SWR window) or `miss`; writes and
+ * a completed revalidation report `ok`; `error` means the store or the loader threw.
+ */
+export type CacheOutcome = "hit" | "stale" | "miss" | "ok" | "error"
+
+/** One settled cache operation, as an observer sees it. */
+export interface CacheEvent {
+  readonly op: CacheOperation
+  readonly outcome: CacheOutcome
+  /** Epoch ms the operation started. */
+  readonly startedAt: number
+  /** Monotonic duration in ms. */
+  readonly durationMs: number
+  /**
+   * The raw key. Keys often hold ids or emails: this value is for in-process use, and an exporter
+   * decides what (if anything) of it leaves the process. Absent for `clear` and `invalidateTag`.
+   */
+  readonly key: string | undefined
+  /** The tag passed to `invalidateTag`, with the same caution as `key`. */
+  readonly tag: string | undefined
+  /** Tags written by `set`, `wrap` and `revalidate`; 1 for `invalidateTag`; otherwise 0. */
+  readonly tagCount: number
+  /**
+   * The context bound with `for(context)`, or `undefined` for the unbound cache. For `revalidate` it is
+   * the context whose read found the stale entry.
+   */
+  readonly context: object | undefined
+}
+
+/**
+ * Called once per operation after it settles, never before the caller sees the result. A throwing (or
+ * rejecting) observer is swallowed: it cannot change a cache result.
+ */
+export type CacheObserver = (event: CacheEvent) => void
+
 export interface CacheOptions {
   /** Storage adapter. Default: a fresh {@link MemoryCache}. */
   readonly store?: CacheStore
@@ -76,6 +123,11 @@ export interface CacheOptions {
   readonly now?: () => number
   /** Called when a background SWR revalidation throws. Default: `console.error`. */
   readonly onError?: (error: unknown, key: string) => 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.
+   */
+  readonly observer?: CacheObserver
 }
 
 export interface Cache {
@@ -96,15 +148,17 @@ export interface Cache {
    */
   wrap<T>(key: string, loader: () => T, options?: WrapOptions): Promise<Awaited<T>>
   /**
-   * A view bound to a request context: every operation announces its capability first, and fails closed
-   * when the route did not declare it.
+   * A view bound to a request (or job) context. With a `beacon`, every operation announces its
+   * capability first and fails closed when the route did not declare it. With an `observer`, every
+   * event carries `context`, which is how a tracer parents the span to `context.trace`.
    *
    * `wrap` announces BOTH read and write, because a miss writes and which one happens is not known
    * before the call. A declaration describes what a route may do, so the conservative answer is the
    * correct one.
    *
-   * Requires `beacon`. Without one this throws rather than handing back a cache that quietly produces
-   * no evidence - a beacon nobody notices is missing is the exact failure the beacon exists to prevent.
+   * Requires `beacon` or `observer`. With neither this throws rather than handing back a view that
+   * quietly does nothing - a beacon nobody notices is missing is the exact failure the beacon exists
+   * to prevent.
    */
   for(context: object): Cache
 }