@nifrajs/cache 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @nifrajs/cache
 
-Typed KV cache for nifra — **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
+Typed KV cache for nifra - **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
 stampede protection** on a **pluggable store** (in-memory by default; bring CF KV / Redis for a shared
 cache). **Dependency-free**; runs on Bun/Node/Deno/Workers.
 
@@ -9,7 +9,7 @@ import { createCache } from "@nifrajs/cache"
 
 const cache = createCache({ defaultTtlMs: 30_000 })
 
-// Cache-aside in a loader — one DB hit per key per TTL, even under a stampede:
+// Cache-aside in a loader - one DB hit per key per TTL, even under a stampede:
 export async function loader({ params }) {
   const user = await cache.wrap(
     `user:${params.id}`,
@@ -25,7 +25,7 @@ await cache.invalidateTag(`user:${id}`)
 
 ## Semantics
 
-- **`wrap(key, loader, opts)`** — returns the cached value, or runs `loader`, stores, and returns it.
+- **`wrap(key, loader, opts)`** - returns the cached value, or runs `loader`, stores, and returns it.
   - **Fresh** (`now < staleAt`): the cached value, no loader call.
   - **Stale-but-live** (`staleAt ≤ now < expiresAt`, i.e. within `swrMs`): the stale value is returned
     **immediately** while a **background** refresh runs (deduped). Latency stays flat; data self-heals.
@@ -44,18 +44,18 @@ The default `MemoryCache` is in-process with lazy expiry, a tag index, and an op
 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
+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.
 
 ## API
 
-- `createCache(options?)` → `Cache` — `{ store?, defaultTtlMs?, now?, onError? }`.
+- `createCache(options?)` → `Cache` - `{ store?, defaultTtlMs?, now?, onError? }`.
 - `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
-- `MemoryCache({ maxEntries?, now? })` — the default store; implement `CacheStore` for your own.
+- `MemoryCache({ maxEntries?, now? })` - the default store; implement `CacheStore` for your own.
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

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

package/dist/cache.js

@@ -1,12 +1,12 @@
 /**
- * The cache facade — typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
+ * The cache facade - typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
  * single-flight stampede protection. Mirrors the other nifra primitives: a factory, an injectable clock,
  * and error isolation (a background revalidation that throws goes to `onError`, never rejects the caller).
  *
  *   import { createCache } from "@nifrajs/cache"
  *
  *   const cache = createCache({ defaultTtlMs: 30_000 })
- *   // Cache-aside in a loader — one DB hit per 30s per key, stampede-safe:
+ *   // Cache-aside in a loader - one DB hit per 30s per key, stampede-safe:
  *   const user = await cache.wrap(`user:${id}`, () => db.user(id), { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${id}`] })
  *   await cache.invalidateTag(`user:${id}`) // on write
  */
@@ -71,7 +71,9 @@ export function createCache(options = {}) {
         }
         return (await load(key, loader, opts)); // miss → load (single-flight)
     }
-    return {
+    const readToken = options.capabilities?.read ?? "cache.read";
+    const writeToken = options.capabilities?.write ?? "cache.write";
+    const plain = {
         get,
         has,
         set,
@@ -79,6 +81,42 @@ export function createCache(options = {}) {
         delete: (key) => Promise.resolve(store.delete(key)),
         invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
         clear: () => Promise.resolve(store.clear()),
+        for: bind,
     };
+    // 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");
+        }
+        // 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.
+        const guard = (capabilities, run) => {
+            try {
+                for (const capability of capabilities)
+                    beacon(context, capability);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            return run();
+        };
+        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)),
+            // 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()),
+            for: bind,
+        };
+    }
+    return plain;
 }
 //# sourceMappingURL=cache.js.map

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

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * @nifrajs/cache - a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
  * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
  * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
  *
@@ -9,5 +9,5 @@
  */
 export { createCache } from "./cache.js";
 export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.js";
-export type { Cache, CacheOptions, CacheStore, SetOptions, StoredEntry, WrapOptions, } from "./types.js";
+export type { Cache, CacheCapabilities, CacheOptions, 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,YAAY,EACZ,UAAU,EACV,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,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * @nifrajs/cache - a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
  * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
  * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
  *

package/dist/memory-cache.d.ts

@@ -1,5 +1,5 @@
 /**
- * In-process {@link CacheStore} — a Map with lazy expiry, a tag index for group invalidation, and an
+ * In-process {@link CacheStore} - a Map with lazy expiry, a tag index for group invalidation, and an
  * optional LRU cap. Correct for a single instance; for a cache shared across instances/workers, implement
  * `CacheStore` over CF KV / Redis. Not persisted (a restart empties it).
  */

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — types for the typed KV cache.
+ * @nifrajs/cache - types for the typed KV cache.
  *
  * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
  * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.
@@ -7,7 +7,7 @@
 /** A cached entry as the store holds it. */
 export interface StoredEntry {
     readonly value: unknown;
-    /** Epoch-ms after which the entry is gone — a miss. */
+    /** Epoch-ms after which the entry is gone - a miss. */
     readonly expiresAt: number;
     /** Epoch-ms after which the entry is stale: still served during the SWR window while a refresh runs.
      * Equal to `expiresAt` when there's no stale-while-revalidate window. */
@@ -15,7 +15,7 @@ export interface StoredEntry {
 }
 /**
  * Raw key→entry storage. The default {@link MemoryCache} is in-process; implement this over CF KV /
- * Redis / etc. for a cache shared across instances. All methods may be sync or async — the cache awaits them.
+ * Redis / etc. for a cache shared across instances. All methods may be sync or async - the cache awaits them.
  */
 export interface CacheStore {
     /** The live entry for `key`, or `undefined` if missing or hard-expired (`now >= expiresAt`). */
@@ -36,9 +36,33 @@ export interface SetOptions {
     readonly tags?: readonly string[];
 }
 export type WrapOptions = SetOptions;
+/**
+ * `useCapability` from `@nifrajs/core/capabilities`, taken as a parameter rather than imported so this
+ * package keeps its zero dependencies - a cache should not drag the server into a bundle that only
+ * wanted a cache. Wiring it is one line where the cache is created.
+ */
+export type CapabilityBeacon = (context: object, capability: string) => void;
+/** Capability tokens this cache announces. Defaults: `cache.read` and `cache.write`. */
+export interface CacheCapabilities {
+    readonly read?: string;
+    readonly write?: string;
+}
 export interface CacheOptions {
     /** Storage adapter. Default: a fresh {@link MemoryCache}. */
     readonly store?: CacheStore;
+    /**
+     * Make cache operations produce capability evidence:
+     *
+     *   import { useCapability } from "@nifrajs/core/capabilities"
+     *   const cache = createCache({ beacon: useCapability })
+     *
+     * Then `cache.for(context)` announces its capability before each operation. Evidence from the CALL is
+     * per-route and exact, where evidence from an import is per-module and therefore as broad as the
+     * module - which is why a beacon can say something a provenance rule cannot.
+     */
+    readonly beacon?: CapabilityBeacon;
+    /** Override the announced tokens when the app names its capabilities differently. */
+    readonly capabilities?: CacheCapabilities;
     /** Default TTL (ms) for `set`/`wrap` when none is given. Default 60_000. */
     readonly defaultTtlMs?: number;
     /** Injectable clock (tests). Default `() => Date.now()`. */
@@ -63,5 +87,17 @@ export interface Cache {
      * returned immediately while a deduped background refresh runs). A throwing `loader` is NOT cached.
      */
     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.
+     *
+     * `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.
+     */
+    for(context: object): Cache;
 }
 //# sourceMappingURL=types.d.ts.map

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,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;IAC3B,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;CACzD;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;CAClF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — types for the typed KV cache.
+ * @nifrajs/cache - types for the typed KV cache.
  *
  * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
  * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/cache",
-  "version": "2.1.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.",
+  "version": "2.3.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",
     "typescript",

package/src/cache.ts

@@ -1,12 +1,12 @@
 /**
- * The cache facade — typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
+ * The cache facade - typed get/set/wrap over a {@link CacheStore}, with TTL, stale-while-revalidate, and
  * single-flight stampede protection. Mirrors the other nifra primitives: a factory, an injectable clock,
  * and error isolation (a background revalidation that throws goes to `onError`, never rejects the caller).
  *
  *   import { createCache } from "@nifrajs/cache"
  *
  *   const cache = createCache({ defaultTtlMs: 30_000 })
- *   // Cache-aside in a loader — one DB hit per 30s per key, stampede-safe:
+ *   // Cache-aside in a loader - one DB hit per 30s per key, stampede-safe:
  *   const user = await cache.wrap(`user:${id}`, () => db.user(id), { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${id}`] })
  *   await cache.invalidateTag(`user:${id}`) // on write
  */
@@ -86,7 +86,10 @@ export function createCache(options: CacheOptions = {}): Cache {
     return (await load(key, loader as () => unknown, opts)) as Awaited<T> // miss → load (single-flight)
   }
 
-  return {
+  const readToken = options.capabilities?.read ?? "cache.read"
+  const writeToken = options.capabilities?.write ?? "cache.write"
+
+  const plain: Cache = {
     get,
     has,
     set,
@@ -94,5 +97,46 @@ export function createCache(options: CacheOptions = {}): Cache {
     delete: (key) => Promise.resolve(store.delete(key)),
     invalidateTag: (tag) => Promise.resolve(store.invalidateTag(tag)),
     clear: () => Promise.resolve(store.clear()),
+    for: bind,
   }
+
+  // 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) {
+      throw new Error(
+        "@nifrajs/cache: for(context) needs a beacon - pass `beacon: useCapability` (from @nifrajs/core/capabilities) to createCache",
+      )
+    }
+    // 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.
+    const guard = <T>(capabilities: readonly string[], run: () => Promise<T>): Promise<T> => {
+      try {
+        for (const capability of capabilities) beacon(context, capability)
+      } catch (error) {
+        return Promise.reject(error)
+      }
+      return run()
+    }
+    const READ = [readToken]
+    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)),
+      set: <T>(key: string, value: T, opts?: SetOptions): Promise<void> =>
+        guard(WRITE, () => plain.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()),
+      for: bind,
+    }
+  }
+
+  return plain
 }

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
+ * @nifrajs/cache - a typed KV cache for nifra: TTL, stale-while-revalidate, tag invalidation, and
  * single-flight stampede protection, on a pluggable store (in-memory by default; bring CF KV / Redis for
  * a shared cache). Dependency-free; runs on Bun/Node/Deno/Workers.
  *
@@ -12,8 +12,10 @@ export { createCache } from "./cache.ts"
 export { MemoryCache, type MemoryCacheOptions } from "./memory-cache.ts"
 export type {
   Cache,
+  CacheCapabilities,
   CacheOptions,
   CacheStore,
+  CapabilityBeacon,
   SetOptions,
   StoredEntry,
   WrapOptions,

package/src/memory-cache.ts

@@ -1,5 +1,5 @@
 /**
- * In-process {@link CacheStore} — a Map with lazy expiry, a tag index for group invalidation, and an
+ * In-process {@link CacheStore} - a Map with lazy expiry, a tag index for group invalidation, and an
  * optional LRU cap. Correct for a single instance; for a cache shared across instances/workers, implement
  * `CacheStore` over CF KV / Redis. Not persisted (a restart empties it).
  */

package/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/cache — types for the typed KV cache.
+ * @nifrajs/cache - types for the typed KV cache.
  *
  * The facade ({@link Cache}) is typed + owns TTL/SWR/stampede logic; the {@link CacheStore} is a raw
  * key→entry adapter (memory by default; bring CF KV / Redis for shared or durable caching). Dependency-free.
@@ -8,7 +8,7 @@
 /** A cached entry as the store holds it. */
 export interface StoredEntry {
   readonly value: unknown
-  /** Epoch-ms after which the entry is gone — a miss. */
+  /** Epoch-ms after which the entry is gone - a miss. */
   readonly expiresAt: number
   /** Epoch-ms after which the entry is stale: still served during the SWR window while a refresh runs.
    * Equal to `expiresAt` when there's no stale-while-revalidate window. */
@@ -17,7 +17,7 @@ export interface StoredEntry {
 
 /**
  * Raw key→entry storage. The default {@link MemoryCache} is in-process; implement this over CF KV /
- * Redis / etc. for a cache shared across instances. All methods may be sync or async — the cache awaits them.
+ * Redis / etc. for a cache shared across instances. All methods may be sync or async - the cache awaits them.
  */
 export interface CacheStore {
   /** The live entry for `key`, or `undefined` if missing or hard-expired (`now >= expiresAt`). */
@@ -41,9 +41,35 @@ export interface SetOptions {
 
 export type WrapOptions = SetOptions
 
+/**
+ * `useCapability` from `@nifrajs/core/capabilities`, taken as a parameter rather than imported so this
+ * package keeps its zero dependencies - a cache should not drag the server into a bundle that only
+ * wanted a cache. Wiring it is one line where the cache is created.
+ */
+export type CapabilityBeacon = (context: object, capability: string) => void
+
+/** Capability tokens this cache announces. Defaults: `cache.read` and `cache.write`. */
+export interface CacheCapabilities {
+  readonly read?: string
+  readonly write?: string
+}
+
 export interface CacheOptions {
   /** Storage adapter. Default: a fresh {@link MemoryCache}. */
   readonly store?: CacheStore
+  /**
+   * Make cache operations produce capability evidence:
+   *
+   *   import { useCapability } from "@nifrajs/core/capabilities"
+   *   const cache = createCache({ beacon: useCapability })
+   *
+   * Then `cache.for(context)` announces its capability before each operation. Evidence from the CALL is
+   * per-route and exact, where evidence from an import is per-module and therefore as broad as the
+   * module - which is why a beacon can say something a provenance rule cannot.
+   */
+  readonly beacon?: CapabilityBeacon
+  /** Override the announced tokens when the app names its capabilities differently. */
+  readonly capabilities?: CacheCapabilities
   /** Default TTL (ms) for `set`/`wrap` when none is given. Default 60_000. */
   readonly defaultTtlMs?: number
   /** Injectable clock (tests). Default `() => Date.now()`. */
@@ -69,4 +95,16 @@ export interface Cache {
    * returned immediately while a deduped background refresh runs). A throwing `loader` is NOT cached.
    */
   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.
+   *
+   * `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.
+   */
+  for(context: object): Cache
 }