@blogmcp/content-cache 0.2.1

package/README.md

@@ -0,0 +1,82 @@
+# @blogmcp/content-cache
+
+Server-only durable content cache for blogmcp presentation layers.
+
+A consuming SSR app (the drhoubicka storefront, the reference blogs) sources
+KB-owned page MDX + navigation through a two-tier read-through: a per-process
+in-memory hot tier over a pluggable **durable** store. The durable copy is
+written through on every successful KB fetch, so it is always the last content
+the KB actually served — a resilient offline floor with **no hand-maintained
+second source of truth to drift**.
+
+> Server-only: `FsCacheStore` imports `node:fs`. Import from `*.server.ts`
+> modules only — never a browser bundle.
+
+## API
+
+```ts
+import { SwrCache, FsCacheStore } from '@blogmcp/content-cache';
+
+// Public (durable) tier — survives restarts, is the outage floor.
+const articles = new SwrCache<{ mdx: string }>({
+  store: new FsCacheStore({ dir: process.env.CACHE_DIR! }),
+  freshMs: 60_000,      // serve memory without revalidating
+  staleMs: 600_000,     // serve stale + revalidate in the background
+  negTtlMs: 30_000,     // suppress refetch of a known-failing key
+  keyPrefix: 'article:',
+});
+
+// Gated/member tier — NEVER persisted to disk (omit `store`).
+const memberArticles = new SwrCache({ freshMs: 60_000, staleMs: 600_000, negTtlMs: 30_000 });
+
+const { value, source } = await articles.get(key, async () => {
+  const a = await kb.fetch(key);          // fetcher MUST throw on miss/failure
+  if (!a) throw new Error('no content');
+  return { mdx: a.content };
+});
+// source ∈ fresh | stale | cold | lkg-memory | lkg-durable | negative | error
+```
+
+Degradation ladder on a KB failure: prior in-memory value → durable store copy →
+`null` (negative-cached). Successful fetches write through to both tiers; the
+durable write is fire-and-forget (never blocks or fails the request path).
+
+### Purge
+
+```ts
+await articles.purge(key);        // evict one key (memory + durable)
+await articles.purgeAll('article:'); // evict a prefix
+await articles.purgeAll();        // evict everything
+```
+
+## Storage adapters
+
+`CacheStore` separates the caching pattern from where the last-known-good copy
+lives:
+
+- **`FsCacheStore`** — ships today. One atomic JSON file per entry under a dir.
+- **`S3CacheStore`** — designed-for (shared floor across pods). Not yet implemented.
+- **`PgCacheStore`** — designed-for (transactional/queryable). Not yet implemented.
+
+All satisfy the same interface, so adopting one is a constructor swap.
+
+`T` must be JSON-serializable — cache the raw nav-tree array, not a built `Map`.
+
+## Bounds
+
+The in-memory tier has no size cap or idle eviction — expired negative entries are
+reclaimed opportunistically on access, but distinct keys accumulate. Use it with a
+**bounded key space** (the storefront keys by tier + immutable id/filename + locale,
+and by nav scope + locale — dozens of entries). Don't key by unbounded/attacker-
+controlled input; a `maxEntries` LRU is a future add if a consumer needs one.
+
+## Build / publish
+
+Dual package.json (like `@blogmcp/sdk`): in-repo `exports` point at `./src`;
+`prepack` rewrites them to `./dist` for the npm tarball. Version-locked with the
+`@blogmcp/sdk` fixed changeset group.
+
+```bash
+npm run build   # vite → dist/*.js + tsc → dist/*.d.ts
+npm test        # vitest
+```

package/dist/fs-store.d.ts

@@ -0,0 +1,28 @@
+import type { CacheEntry, CacheStore } from './types';
+export interface FsCacheStoreOptions {
+    /** Directory that holds one JSON file per cache entry. Created on demand. */
+    dir: string;
+}
+/**
+ * Filesystem {@link CacheStore}: one JSON file per entry, named by a truncated
+ * sha256 of the key (keys contain `|`/`:`/`/`, unsafe as filenames). Writes are
+ * atomic (write a unique temp file in the same dir, then `rename`), so a crash
+ * mid-write never leaves a torn entry — a reader sees either the old file or the
+ * new one. A corrupt/partial file reads as a miss and self-heals on the next set.
+ *
+ * Server-only (imports `node:fs`/`node:crypto`/`node:path`) — never import from a
+ * browser bundle. Per-process on disk: on Kubernetes each pod keeps its own copy
+ * (fine for a last-known-good floor); a shared `S3CacheStore` would centralize it.
+ */
+export declare class FsCacheStore implements CacheStore {
+    readonly dir: string;
+    constructor(opts: FsCacheStoreOptions);
+    private fileFor;
+    private ensureDir;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    private readAllRecords;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+}

package/dist/fs-store.js

@@ -0,0 +1,83 @@
+import { promises as a } from "node:fs";
+import { createHash as c, randomUUID as o } from "node:crypto";
+import { resolve as l, join as n } from "node:path";
+class w {
+  dir;
+  constructor(t) {
+    if (!t || !t.dir) throw new Error("FsCacheStore requires a `dir`");
+    this.dir = l(t.dir);
+  }
+  fileFor(t) {
+    const e = c("sha256").update(t).digest("hex").slice(0, 40);
+    return n(this.dir, `${e}.json`);
+  }
+  async ensureDir() {
+    await a.mkdir(this.dir, { recursive: !0 });
+  }
+  async get(t) {
+    try {
+      const e = await a.readFile(this.fileFor(t), "utf8"), r = JSON.parse(e);
+      return !r || r.key !== t || !r.entry ? null : r.entry;
+    } catch {
+      return null;
+    }
+  }
+  async set(t, e) {
+    await this.ensureDir();
+    const r = this.fileFor(t), i = `${r}.${o()}.tmp`, s = { key: t, entry: e };
+    await a.writeFile(i, JSON.stringify(s), "utf8"), await a.rename(i, r);
+  }
+  async delete(t) {
+    try {
+      await a.unlink(this.fileFor(t));
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+  async readAllRecords() {
+    let t;
+    try {
+      t = await a.readdir(this.dir);
+    } catch (r) {
+      if (r.code === "ENOENT") return [];
+      throw r;
+    }
+    const e = [];
+    return await Promise.all(
+      t.filter((r) => r.endsWith(".json")).map(async (r) => {
+        try {
+          const i = await a.readFile(n(this.dir, r), "utf8"), s = JSON.parse(i);
+          s && typeof s.key == "string" && s.entry && e.push(s);
+        } catch {
+        }
+      })
+    ), e;
+  }
+  async keys(t) {
+    const e = (await this.readAllRecords()).map((r) => r.key);
+    return t ? e.filter((r) => r.startsWith(t)) : e;
+  }
+  async clear(t) {
+    if (!t) {
+      let r;
+      try {
+        r = await a.readdir(this.dir);
+      } catch (i) {
+        if (i.code === "ENOENT") return;
+        throw i;
+      }
+      await Promise.all(
+        r.filter((i) => i.endsWith(".json") || i.endsWith(".tmp")).map((i) => a.unlink(n(this.dir, i)).catch(() => {
+        }))
+      );
+      return;
+    }
+    const e = await this.readAllRecords();
+    await Promise.all(
+      e.filter((r) => r.key.startsWith(t)).map((r) => this.delete(r.key))
+    );
+  }
+}
+export {
+  w as FsCacheStore
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @blogmcp/content-cache — server-only durable content cache for blogmcp
+ * presentation layers.
+ *
+ * A consuming SSR app (the drhoubicka storefront, the reference blogs) sources
+ * KB-owned page MDX + navigation through {@link SwrCache}: a per-process hot tier
+ * over a pluggable durable {@link CacheStore}. The durable copy is written through
+ * on every successful origin fetch, so it is always the last content the KB
+ * actually served — the resilient offline floor with NO hand-maintained second
+ * source of truth to drift. Storage is separated from the caching pattern:
+ * {@link FsCacheStore} ships today; S3/Postgres adapters slot in behind the same
+ * interface later.
+ *
+ * Server-only: {@link FsCacheStore} imports `node:fs`. Import from `*.server.ts`
+ * modules only — never a browser bundle.
+ */
+export type { CacheEntry, CacheStore } from './types';
+export { FsCacheStore, type FsCacheStoreOptions } from './fs-store';
+export { SwrCache, type SwrCacheOptions, type SwrResult, type SwrSource, } from './swr-cache';

package/dist/index.js

@@ -0,0 +1,6 @@
+import { FsCacheStore as o } from "./fs-store.js";
+import { SwrCache as a } from "./swr-cache.js";
+export {
+  o as FsCacheStore,
+  a as SwrCache
+};

package/dist/swr-cache.d.ts

@@ -0,0 +1,95 @@
+import type { CacheStore } from './types';
+/**
+ * Which tier served a {@link SwrCache.get} result — for observability/logging.
+ *  - `fresh`       — in-memory hit within `freshMs` (no revalidation)
+ *  - `stale`       — in-memory hit within `staleMs` (revalidating in background)
+ *  - `cold`        — fetched live from the origin
+ *  - `lkg-memory`  — origin failed; served the prior in-memory value
+ *  - `lkg-durable` — origin failed + memory cold; served the durable store's copy
+ *  - `negative`    — recently-failed key with nothing cached (short-circuited)
+ *  - `error`       — origin failed and no value anywhere; caller gets `null`
+ */
+export type SwrSource = 'fresh' | 'stale' | 'cold' | 'lkg-memory' | 'lkg-durable' | 'negative' | 'error';
+export interface SwrResult<T> {
+    value: T | null;
+    source: SwrSource;
+}
+export interface SwrCacheOptions {
+    /**
+     * Durable backing tier — the last-known-good floor that survives a process
+     * restart. OMIT for an in-memory-only cache (e.g. gated/member content that
+     * must never be persisted to disk).
+     */
+    store?: CacheStore;
+    /** Serve from memory without revalidating for this long after a success. */
+    freshMs: number;
+    /** Serve stale from memory + revalidate in the background up to this age. */
+    staleMs: number;
+    /** Suppress refetch of a known-failing key (with no cached value) for this long. */
+    negTtlMs: number;
+    /** Namespace applied to DURABLE keys so several caches can share one store. */
+    keyPrefix?: string;
+    /** Clock injection point (defaults to `Date.now`) — for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Two-tier read-through cache: a per-process in-memory hot tier for latency, over
+ * an optional durable {@link CacheStore} for last-known-good survival across
+ * restarts. Generalizes the storefront's hand-rolled `swrGet`/`getNavMap` state
+ * machines (fresh → stale-while-revalidate → last-known-good → negative cache →
+ * single-flight) and adds the durable tier + a purge surface.
+ *
+ * On a successful fetch the value is written through to BOTH tiers (the durable
+ * write is fire-and-forget — it never blocks or fails the request). On an origin
+ * failure the cache degrades gracefully: prior memory value → durable value →
+ * `null` (negative-cached). The durable copy is therefore always the last content
+ * the origin actually served — there is no hand-maintained second source of truth
+ * to drift.
+ *
+ * `T` MUST be JSON-serializable (see {@link CacheEntry}).
+ */
+export declare class SwrCache<T = unknown> {
+    private readonly store?;
+    private readonly freshMs;
+    private readonly staleMs;
+    private readonly negTtlMs;
+    private readonly keyPrefix;
+    private readonly now;
+    private readonly mem;
+    private readonly neg;
+    private readonly inflight;
+    /**
+     * Bumped by every `purge`/`purgeAll`. A cache-population step (write-back after
+     * a fetch, durable-LKG hydration, negative-cache set) captures the generation
+     * when it STARTS and only applies its write if the generation is unchanged — so
+     * a purge that lands mid-flight is never silently re-populated by an in-flight
+     * (possibly stale, possibly coalesced) fetch. Fences the "lost purge" race.
+     */
+    private generation;
+    constructor(opts: SwrCacheOptions);
+    private durableKey;
+    /**
+     * Coalesce concurrent fetches for the same key onto one in-flight promise, and
+     * populate BOTH tiers on success — exactly once per real fetch, so a later
+     * request that rides an in-flight fetch (started before a purge) can't smuggle a
+     * stale value past that purge. The write-back is gated by the generation at
+     * FETCH-START: if a purge bumped it while the fetch was outstanding, the result
+     * is returned to callers but NOT cached.
+     */
+    private runFetch;
+    /** Persist to the durable tier without ever blocking/failing the request path. */
+    private writeThrough;
+    /**
+     * Read `key`, fetching via `fetcher` on a miss. `fetcher` MUST throw to signal a
+     * failure/absent value (mirrors the storefront's throwing fetchers); its resolved
+     * value is cached. Returns `{ value: null }` only when the origin fails and there
+     * is nothing cached in either tier.
+     */
+    get(key: string, fetcher: () => Promise<T>): Promise<SwrResult<T>>;
+    /** Immediately evict one key from memory AND the durable store. */
+    purge(key: string): Promise<void>;
+    /** Evict every key (or those starting with `prefix`) from memory AND durable. */
+    purgeAll(prefix?: string): Promise<void>;
+    /** Test-only: clear the in-memory tiers (leaves the durable store intact). */
+    resetMemory(): void;
+}

package/dist/swr-cache.js

@@ -0,0 +1,106 @@
+class o {
+  store;
+  freshMs;
+  staleMs;
+  negTtlMs;
+  keyPrefix;
+  now;
+  mem = /* @__PURE__ */ new Map();
+  neg = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  /**
+   * Bumped by every `purge`/`purgeAll`. A cache-population step (write-back after
+   * a fetch, durable-LKG hydration, negative-cache set) captures the generation
+   * when it STARTS and only applies its write if the generation is unchanged — so
+   * a purge that lands mid-flight is never silently re-populated by an in-flight
+   * (possibly stale, possibly coalesced) fetch. Fences the "lost purge" race.
+   */
+  generation = 0;
+  constructor(t) {
+    this.store = t.store, this.freshMs = t.freshMs, this.staleMs = t.staleMs, this.negTtlMs = t.negTtlMs, this.keyPrefix = t.keyPrefix ?? "", this.now = t.now ?? (() => Date.now());
+  }
+  durableKey(t) {
+    return this.keyPrefix ? `${this.keyPrefix}${t}` : t;
+  }
+  /**
+   * Coalesce concurrent fetches for the same key onto one in-flight promise, and
+   * populate BOTH tiers on success — exactly once per real fetch, so a later
+   * request that rides an in-flight fetch (started before a purge) can't smuggle a
+   * stale value past that purge. The write-back is gated by the generation at
+   * FETCH-START: if a purge bumped it while the fetch was outstanding, the result
+   * is returned to callers but NOT cached.
+   */
+  runFetch(t, e) {
+    const i = this.inflight.get(t);
+    if (i) return i;
+    const n = this.generation, s = (async () => {
+      try {
+        const r = await e();
+        return this.generation === n && (this.mem.set(t, { value: r, at: this.now() }), this.writeThrough(t, r), this.neg.delete(t)), r;
+      } finally {
+        this.inflight.delete(t);
+      }
+    })();
+    return this.inflight.set(t, s), s;
+  }
+  /** Persist to the durable tier without ever blocking/failing the request path. */
+  writeThrough(t, e) {
+    if (!this.store) return;
+    const i = { value: e, storedAt: this.now() };
+    this.store.set(this.durableKey(t), i).catch(() => {
+    });
+  }
+  /**
+   * Read `key`, fetching via `fetcher` on a miss. `fetcher` MUST throw to signal a
+   * failure/absent value (mirrors the storefront's throwing fetchers); its resolved
+   * value is cached. Returns `{ value: null }` only when the origin fails and there
+   * is nothing cached in either tier.
+   */
+  async get(t, e) {
+    const i = this.generation, n = this.now(), s = this.mem.get(t);
+    if (s && n - s.at < this.freshMs)
+      return { value: s.value, source: "fresh" };
+    const r = this.neg.get(t);
+    if (!s && r !== void 0) {
+      if (n - r < this.negTtlMs) return { value: null, source: "negative" };
+      this.neg.delete(t);
+    }
+    if (s && n - s.at < this.staleMs)
+      return this.runFetch(t, e).catch(() => {
+      }), { value: s.value, source: "stale" };
+    try {
+      return { value: await this.runFetch(t, e), source: "cold" };
+    } catch {
+      if (s)
+        return { value: s.value, source: "lkg-memory" };
+      if (this.store) {
+        const h = await this.store.get(this.durableKey(t)).catch(() => null);
+        if (h) {
+          const a = h.value;
+          return this.generation === i && this.mem.set(t, { value: a, at: h.storedAt }), { value: a, source: "lkg-durable" };
+        }
+      }
+      return this.generation === i && this.neg.set(t, this.now()), { value: null, source: "error" };
+    }
+  }
+  /** Immediately evict one key from memory AND the durable store. */
+  async purge(t) {
+    this.generation++, this.mem.delete(t), this.neg.delete(t), this.store && await this.store.delete(this.durableKey(t));
+  }
+  /** Evict every key (or those starting with `prefix`) from memory AND durable. */
+  async purgeAll(t) {
+    if (this.generation++, t) {
+      for (const e of [...this.mem.keys()]) e.startsWith(t) && this.mem.delete(e);
+      for (const e of [...this.neg.keys()]) e.startsWith(t) && this.neg.delete(e);
+      this.store && await this.store.clear(this.durableKey(t));
+    } else
+      this.mem.clear(), this.neg.clear(), this.store && await this.store.clear();
+  }
+  /** Test-only: clear the in-memory tiers (leaves the durable store intact). */
+  resetMemory() {
+    this.mem.clear(), this.neg.clear(), this.inflight.clear();
+  }
+}
+export {
+  o as SwrCache
+};

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A single cached value plus the freshness basis a read-through layer needs.
+ * `value` MUST be JSON-serializable — the filesystem (and future S3/Postgres)
+ * adapters persist it as JSON, so a Map/Set/class instance must be reduced to a
+ * plain object/array before caching (e.g. cache the raw nav-tree array, not a
+ * built `Map`).
+ */
+export interface CacheEntry<T = unknown> {
+    /** The cached value (JSON-serializable). */
+    value: T;
+    /** Epoch-ms when this entry was stored — the age basis for SWR freshness. */
+    storedAt: number;
+    /** Optional caller metadata (e.g. source tier, etag) — persisted verbatim. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Pluggable durable storage for cache entries. The read-through logic
+ * (`SwrCache`) is storage-agnostic — swap the adapter to change where the
+ * last-known-good copy lives.
+ *
+ * Ships today: {@link FsCacheStore} (local filesystem). Designed-for, not yet
+ * implemented: an `S3CacheStore` (shared last-known-good across pods) and a
+ * `PgCacheStore` (transactional, queryable) — both satisfy this exact interface,
+ * so adopting one is a constructor swap with no change to callers.
+ *
+ * Implementations must be TOTAL: a missing key, a missing backing store, or a
+ * corrupt/partial entry resolves to `null` (a cache miss), never a throw — a
+ * cache is a best-effort accelerator and must never take down the request path.
+ */
+export interface CacheStore {
+    /** Return the entry for `key`, or `null` on miss/corruption. Never throws for a miss. */
+    get(key: string): Promise<CacheEntry | null>;
+    /** Persist `entry` under `key`, replacing any existing value atomically. */
+    set(key: string, entry: CacheEntry): Promise<void>;
+    /** Remove `key`. A missing key is a no-op, not an error. */
+    delete(key: string): Promise<void>;
+    /** Remove every entry, or only those whose key starts with `prefix`. */
+    clear(prefix?: string): Promise<void>;
+    /** List stored keys, optionally filtered to those starting with `prefix`. */
+    keys(prefix?: string): Promise<string[]>;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@blogmcp/content-cache",
+  "version": "0.2.1",
+  "description": "Server-only durable content cache for blogmcp presentation layers: pluggable storage adapters (filesystem now; S3/Postgres later) behind an SWR + last-known-good read-through.",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepack": "node scripts/prepack.mjs",
+    "postpack": "node scripts/postpack.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vite": "^7.3.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "cache",
+    "swr",
+    "last-known-good",
+    "blogmcp",
+    "storage-adapter",
+    "server"
+  ],
+  "license": "MIT"
+}

package/src/__tests__/fs-store.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { FsCacheStore } from '../fs-store';
+import type { CacheEntry } from '../types';
+
+let dir: string;
+let store: FsCacheStore;
+
+beforeEach(() => {
+  dir = join(tmpdir(), `cc-fs-${randomUUID()}`);
+  store = new FsCacheStore({ dir });
+});
+afterEach(async () => {
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+const entry = (value: unknown): CacheEntry => ({ value, storedAt: 1_000 });
+
+describe('FsCacheStore', () => {
+  it('requires a dir', () => {
+    // @ts-expect-error — exercising the guard
+    expect(() => new FsCacheStore({})).toThrow(/requires a `dir`/);
+  });
+
+  it('returns null for a missing key (and lists nothing) when the dir is absent', async () => {
+    expect(await store.get('nope')).toBeNull();
+    expect(await store.keys()).toEqual([]);
+  });
+
+  it('round-trips set → get', async () => {
+    await store.set('a|b', entry({ mdx: 'hello' }));
+    const got = await store.get('a|b');
+    expect(got?.value).toEqual({ mdx: 'hello' });
+    expect(got?.storedAt).toBe(1_000);
+  });
+
+  it('overwrites atomically, leaving exactly one .json file (no temp files)', async () => {
+    await store.set('k', entry(1));
+    await store.set('k', entry(2));
+    expect((await store.get('k'))?.value).toBe(2);
+    const names = await fs.readdir(dir);
+    expect(names).toHaveLength(1);
+    expect(names.every((n) => n.endsWith('.json'))).toBe(true);
+  });
+
+  it('lists and prefix-filters keys by the ORIGINAL key (not the hashed filename)', async () => {
+    await store.set('p|x', entry(1));
+    await store.set('p|y', entry(2));
+    await store.set('q|z', entry(3));
+    expect((await store.keys()).sort()).toEqual(['p|x', 'p|y', 'q|z']);
+    expect((await store.keys('p|')).sort()).toEqual(['p|x', 'p|y']);
+  });
+
+  it('deletes a key; a missing delete is a no-op', async () => {
+    await store.set('k', entry(1));
+    await store.delete('k');
+    expect(await store.get('k')).toBeNull();
+    await expect(store.delete('k')).resolves.toBeUndefined();
+  });
+
+  it('clears by prefix, then clears all', async () => {
+    await store.set('p|x', entry(1));
+    await store.set('p|y', entry(2));
+    await store.set('q|z', entry(3));
+    await store.clear('p|');
+    expect((await store.keys()).sort()).toEqual(['q|z']);
+    await store.clear();
+    expect(await store.keys()).toEqual([]);
+  });
+
+  it('treats a corrupt entry file as a miss', async () => {
+    await store.set('k', entry(1));
+    const [name] = await fs.readdir(dir);
+    await fs.writeFile(join(dir, name), '{ not json', 'utf8');
+    expect(await store.get('k')).toBeNull();
+  });
+});

package/src/__tests__/swr-cache.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, it, vi } from 'vitest';
+import { SwrCache } from '../swr-cache';
+import type { CacheEntry, CacheStore } from '../types';
+
+/** Minimal in-memory {@link CacheStore} double for the durable-tier tests. */
+class MemoryStore implements CacheStore {
+  map = new Map<string, CacheEntry>();
+  async get(k: string) {
+    return this.map.get(k) ?? null;
+  }
+  async set(k: string, e: CacheEntry) {
+    this.map.set(k, e);
+  }
+  async delete(k: string) {
+    this.map.delete(k);
+  }
+  async clear(prefix?: string) {
+    if (!prefix) {
+      this.map.clear();
+      return;
+    }
+    for (const k of [...this.map.keys()]) if (k.startsWith(prefix)) this.map.delete(k);
+  }
+  async keys(prefix?: string) {
+    const ks = [...this.map.keys()];
+    return prefix ? ks.filter((k) => k.startsWith(prefix)) : ks;
+  }
+}
+
+const TTL = { freshMs: 100, staleMs: 1_000, negTtlMs: 50 };
+
+function makeClock(start = 0) {
+  let t = start;
+  return { now: () => t, advance: (ms: number) => (t += ms) };
+}
+/** Let queued microtasks + fire-and-forget promises settle. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe('SwrCache', () => {
+  it('serves fresh from memory without re-fetching', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<number>({ ...TTL, now: clock.now });
+    const fetcher = vi.fn(async () => 1);
+    expect(await cache.get('k', fetcher)).toEqual({ value: 1, source: 'cold' });
+    clock.advance(50);
+    expect(await cache.get('k', fetcher)).toEqual({ value: 1, source: 'fresh' });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it('serves stale immediately and revalidates in the background', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<number>({ ...TTL, now: clock.now });
+    let n = 1;
+    const fetcher = vi.fn(async () => n);
+    await cache.get('k', fetcher); // cold → 1
+    n = 2;
+    clock.advance(200); // > freshMs, < staleMs
+    expect(await cache.get('k', fetcher)).toEqual({ value: 1, source: 'stale' });
+    await flush(); // background revalidation lands
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(await cache.get('k', fetcher)).toEqual({ value: 2, source: 'fresh' });
+  });
+
+  it('serves last-known-good from memory when a cold refetch fails', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<number>({ ...TTL, now: clock.now });
+    let fail = false;
+    const fetcher = vi.fn(async () => {
+      if (fail) throw new Error('down');
+      return 7;
+    });
+    await cache.get('k', fetcher); // cold → 7
+    fail = true;
+    clock.advance(2_000); // > staleMs → cold path, which now fails
+    expect(await cache.get('k', fetcher)).toEqual({ value: 7, source: 'lkg-memory' });
+  });
+
+  it('serves lkg-memory during an outage without masking recovery (not labeled fresh)', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<string>({ ...TTL, now: clock.now });
+    let value = 'V0';
+    let down = false;
+    const fetcher = () =>
+      down ? Promise.reject(new Error('down')) : Promise.resolve(value);
+    await cache.get('k', fetcher); // cold → V0
+    down = true;
+    clock.advance(2_000); // past staleMs → cold retry, which fails
+    expect(await cache.get('k', fetcher)).toEqual({ value: 'V0', source: 'lkg-memory' });
+    // Origin recovers with new content — the very next request must pick it up
+    // (regression guard: the old fresh-window re-arm would return {V0, fresh} here).
+    down = false;
+    value = 'V1';
+    expect(await cache.get('k', fetcher)).toEqual({ value: 'V1', source: 'cold' });
+  });
+
+  it('re-fetches after the negative-cache window expires', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<string>({ ...TTL, now: clock.now });
+    let down = true;
+    const fetcher = vi.fn(() =>
+      down ? Promise.reject(new Error('x')) : Promise.resolve('OK'),
+    );
+    expect((await cache.get('k', fetcher)).source).toBe('error');
+    expect((await cache.get('k', fetcher)).source).toBe('negative'); // within negTtl
+    clock.advance(60); // > negTtlMs (50)
+    down = false;
+    expect(await cache.get('k', fetcher)).toEqual({ value: 'OK', source: 'cold' });
+  });
+
+  it('an in-memory-only cache (no store) persists nothing across a restart', async () => {
+    // The hard rule: a member/internal tier constructed WITHOUT a store must leave
+    // no durable residue — after a restart + origin down there is nothing to serve.
+    const cache = new SwrCache<string>({ ...TTL });
+    await cache.get('k', async () => 'M'); // cold success, no durable tier
+    cache.resetMemory(); // simulate a process restart
+    const r = await cache.get('k', async () => {
+      throw new Error('down');
+    });
+    expect(r).toEqual({ value: null, source: 'error' });
+  });
+
+  it('purge fences an in-flight fetch from re-populating memory + durable', async () => {
+    const store = new MemoryStore();
+    const clock = makeClock();
+    const cache = new SwrCache<string>({ ...TTL, store, keyPrefix: 'a:', now: clock.now });
+
+    await cache.get('k', async () => 'A'); // cold → A, write-through
+    await flush();
+    expect((await store.get('a:k'))?.value).toBe('A');
+
+    // Enter the stale window; kick off a SLOW background revalidation.
+    clock.advance(200);
+    let release!: () => void;
+    const gate = new Promise<void>((r) => (release = r));
+    expect(await cache.get('k', () => gate.then(() => 'OLD'))).toEqual({
+      value: 'A',
+      source: 'stale',
+    });
+
+    // Operator purges while that revalidation is still in flight.
+    await cache.purge('k');
+    expect(await store.get('a:k')).toBeNull();
+
+    // Let the in-flight revalidation resolve — it must NOT re-populate either tier.
+    release();
+    await flush();
+    expect(await store.get('a:k')).toBeNull(); // durable stays purged
+    // Memory was not re-populated: the next read is a cold miss, not a stale 'OLD' hit.
+    expect(await cache.get('k', async () => 'NEW')).toEqual({ value: 'NEW', source: 'cold' });
+  });
+
+  it('negative-caches a cold failure with no prior value', async () => {
+    const clock = makeClock();
+    const cache = new SwrCache<number>({ ...TTL, now: clock.now });
+    const fetcher = vi.fn(async () => {
+      throw new Error('down');
+    });
+    expect(await cache.get('k', fetcher)).toEqual({ value: null, source: 'error' });
+    expect(await cache.get('k', fetcher)).toEqual({ value: null, source: 'negative' });
+    expect(fetcher).toHaveBeenCalledTimes(1); // 2nd short-circuited
+  });
+
+  it('write-throughs to the durable store on a successful fetch', async () => {
+    const store = new MemoryStore();
+    const cache = new SwrCache<number>({ ...TTL, store, keyPrefix: 'a:' });
+    await cache.get('k', async () => 42);
+    await flush(); // fire-and-forget durable write
+    expect((await store.get('a:k'))?.value).toBe(42);
+  });
+
+  it('falls back to the durable store after a restart (cold memory + origin down)', async () => {
+    const store = new MemoryStore();
+    // A prior process persisted the value; this process starts with empty memory.
+    await store.set('a:k', { value: 99, storedAt: 1 });
+    const cache = new SwrCache<number>({ ...TTL, store, keyPrefix: 'a:' });
+    const r = await cache.get('k', async () => {
+      throw new Error('down');
+    });
+    expect(r).toEqual({ value: 99, source: 'lkg-durable' });
+  });
+
+  it('returns error when origin fails and both tiers are empty', async () => {
+    const store = new MemoryStore();
+    const cache = new SwrCache<number>({ ...TTL, store });
+    expect(
+      await cache.get('k', async () => {
+        throw new Error('down');
+      }),
+    ).toEqual({ value: null, source: 'error' });
+  });
+
+  it('reads the live Date.now when no clock is injected (fake-timer friendly)', async () => {
+    vi.useFakeTimers();
+    try {
+      const cache = new SwrCache<number>({ ...TTL }); // no `now` injected → default clock
+      let fail = false;
+      const fetcher = vi.fn(async () => {
+        if (fail) throw new Error('down');
+        return 5;
+      });
+      await cache.get('k', fetcher); // cold → 5, cached at the current fake time
+      fail = true;
+      vi.setSystemTime(Date.now() + TTL.staleMs + 1); // age past stale → cold retry, which fails
+      expect(await cache.get('k', fetcher)).toEqual({ value: 5, source: 'lkg-memory' });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('coalesces concurrent cold fetches (single-flight)', async () => {
+    const cache = new SwrCache<number>({ ...TTL });
+    let calls = 0;
+    const fetcher = () =>
+      new Promise<number>((res) => {
+        calls++;
+        setTimeout(() => res(5), 10);
+      });
+    const [a, b] = await Promise.all([cache.get('k', fetcher), cache.get('k', fetcher)]);
+    expect(a.value).toBe(5);
+    expect(b.value).toBe(5);
+    expect(calls).toBe(1);
+  });
+
+  it('purge evicts memory + durable; purgeAll clears everything', async () => {
+    const store = new MemoryStore();
+    const cache = new SwrCache<number>({ ...TTL, store, keyPrefix: 'a:' });
+    await cache.get('x', async () => 1);
+    await cache.get('y', async () => 2);
+    await flush();
+
+    await cache.purge('x');
+    expect(await store.get('a:x')).toBeNull();
+    const fetcher = vi.fn(async () => 11);
+    expect((await cache.get('x', fetcher)).source).toBe('cold'); // memory was evicted too
+    await flush();
+
+    await cache.purgeAll();
+    expect(await store.keys()).toEqual([]);
+  });
+});

package/src/fs-store.ts

@@ -0,0 +1,131 @@
+import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import type { CacheEntry, CacheStore } from './types';
+
+/**
+ * On-disk shape: the original key is stored ALONGSIDE the entry so we can (a)
+ * list/prefix-filter keys the caller actually wrote (the filename is a hash, not
+ * the key), and (b) reject a sha-prefix collision on read.
+ */
+interface StoredRecord {
+  key: string;
+  entry: CacheEntry;
+}
+
+export interface FsCacheStoreOptions {
+  /** Directory that holds one JSON file per cache entry. Created on demand. */
+  dir: string;
+}
+
+/**
+ * Filesystem {@link CacheStore}: one JSON file per entry, named by a truncated
+ * sha256 of the key (keys contain `|`/`:`/`/`, unsafe as filenames). Writes are
+ * atomic (write a unique temp file in the same dir, then `rename`), so a crash
+ * mid-write never leaves a torn entry — a reader sees either the old file or the
+ * new one. A corrupt/partial file reads as a miss and self-heals on the next set.
+ *
+ * Server-only (imports `node:fs`/`node:crypto`/`node:path`) — never import from a
+ * browser bundle. Per-process on disk: on Kubernetes each pod keeps its own copy
+ * (fine for a last-known-good floor); a shared `S3CacheStore` would centralize it.
+ */
+export class FsCacheStore implements CacheStore {
+  readonly dir: string;
+
+  constructor(opts: FsCacheStoreOptions) {
+    if (!opts || !opts.dir) throw new Error('FsCacheStore requires a `dir`');
+    this.dir = resolve(opts.dir);
+  }
+
+  private fileFor(key: string): string {
+    const h = createHash('sha256').update(key).digest('hex').slice(0, 40);
+    return join(this.dir, `${h}.json`);
+  }
+
+  private async ensureDir(): Promise<void> {
+    await fs.mkdir(this.dir, { recursive: true });
+  }
+
+  async get(key: string): Promise<CacheEntry | null> {
+    try {
+      const raw = await fs.readFile(this.fileFor(key), 'utf8');
+      const rec = JSON.parse(raw) as StoredRecord;
+      // Reject a hash-prefix collision, and guard against a malformed record.
+      if (!rec || rec.key !== key || !rec.entry) return null;
+      return rec.entry;
+    } catch {
+      // Missing file, partial write, or invalid JSON → a cache miss, never a throw.
+      return null;
+    }
+  }
+
+  async set(key: string, entry: CacheEntry): Promise<void> {
+    await this.ensureDir();
+    const dest = this.fileFor(key);
+    const tmp = `${dest}.${randomUUID()}.tmp`;
+    const rec: StoredRecord = { key, entry };
+    await fs.writeFile(tmp, JSON.stringify(rec), 'utf8');
+    await fs.rename(tmp, dest); // atomic within the same directory
+  }
+
+  async delete(key: string): Promise<void> {
+    try {
+      await fs.unlink(this.fileFor(key));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+  }
+
+  private async readAllRecords(): Promise<StoredRecord[]> {
+    let names: string[];
+    try {
+      names = await fs.readdir(this.dir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw err;
+    }
+    const out: StoredRecord[] = [];
+    await Promise.all(
+      names
+        .filter((n) => n.endsWith('.json')) // skip in-flight *.tmp temp files
+        .map(async (n) => {
+          try {
+            const raw = await fs.readFile(join(this.dir, n), 'utf8');
+            const rec = JSON.parse(raw) as StoredRecord;
+            if (rec && typeof rec.key === 'string' && rec.entry) out.push(rec);
+          } catch {
+            /* skip corrupt/partial file */
+          }
+        }),
+    );
+    return out;
+  }
+
+  async keys(prefix?: string): Promise<string[]> {
+    const ks = (await this.readAllRecords()).map((r) => r.key);
+    return prefix ? ks.filter((k) => k.startsWith(prefix)) : ks;
+  }
+
+  async clear(prefix?: string): Promise<void> {
+    if (!prefix) {
+      let names: string[];
+      try {
+        names = await fs.readdir(this.dir);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+        throw err;
+      }
+      await Promise.all(
+        names
+          // Also reclaim any `*.tmp` orphaned by a crash between write and rename.
+          .filter((n) => n.endsWith('.json') || n.endsWith('.tmp'))
+          .map((n) => fs.unlink(join(this.dir, n)).catch(() => {})),
+      );
+      return;
+    }
+    const recs = await this.readAllRecords();
+    await Promise.all(
+      recs.filter((r) => r.key.startsWith(prefix)).map((r) => this.delete(r.key)),
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @blogmcp/content-cache — server-only durable content cache for blogmcp
+ * presentation layers.
+ *
+ * A consuming SSR app (the drhoubicka storefront, the reference blogs) sources
+ * KB-owned page MDX + navigation through {@link SwrCache}: a per-process hot tier
+ * over a pluggable durable {@link CacheStore}. The durable copy is written through
+ * on every successful origin fetch, so it is always the last content the KB
+ * actually served — the resilient offline floor with NO hand-maintained second
+ * source of truth to drift. Storage is separated from the caching pattern:
+ * {@link FsCacheStore} ships today; S3/Postgres adapters slot in behind the same
+ * interface later.
+ *
+ * Server-only: {@link FsCacheStore} imports `node:fs`. Import from `*.server.ts`
+ * modules only — never a browser bundle.
+ */
+export type { CacheEntry, CacheStore } from './types';
+export { FsCacheStore, type FsCacheStoreOptions } from './fs-store';
+export {
+  SwrCache,
+  type SwrCacheOptions,
+  type SwrResult,
+  type SwrSource,
+} from './swr-cache';

package/src/swr-cache.ts

@@ -0,0 +1,221 @@
+import type { CacheEntry, CacheStore } from './types';
+
+/**
+ * Which tier served a {@link SwrCache.get} result — for observability/logging.
+ *  - `fresh`       — in-memory hit within `freshMs` (no revalidation)
+ *  - `stale`       — in-memory hit within `staleMs` (revalidating in background)
+ *  - `cold`        — fetched live from the origin
+ *  - `lkg-memory`  — origin failed; served the prior in-memory value
+ *  - `lkg-durable` — origin failed + memory cold; served the durable store's copy
+ *  - `negative`    — recently-failed key with nothing cached (short-circuited)
+ *  - `error`       — origin failed and no value anywhere; caller gets `null`
+ */
+export type SwrSource =
+  | 'fresh'
+  | 'stale'
+  | 'cold'
+  | 'lkg-memory'
+  | 'lkg-durable'
+  | 'negative'
+  | 'error';
+
+export interface SwrResult<T> {
+  value: T | null;
+  source: SwrSource;
+}
+
+export interface SwrCacheOptions {
+  /**
+   * Durable backing tier — the last-known-good floor that survives a process
+   * restart. OMIT for an in-memory-only cache (e.g. gated/member content that
+   * must never be persisted to disk).
+   */
+  store?: CacheStore;
+  /** Serve from memory without revalidating for this long after a success. */
+  freshMs: number;
+  /** Serve stale from memory + revalidate in the background up to this age. */
+  staleMs: number;
+  /** Suppress refetch of a known-failing key (with no cached value) for this long. */
+  negTtlMs: number;
+  /** Namespace applied to DURABLE keys so several caches can share one store. */
+  keyPrefix?: string;
+  /** Clock injection point (defaults to `Date.now`) — for deterministic tests. */
+  now?: () => number;
+}
+
+interface MemEntry<T> {
+  value: T;
+  at: number;
+}
+
+/**
+ * Two-tier read-through cache: a per-process in-memory hot tier for latency, over
+ * an optional durable {@link CacheStore} for last-known-good survival across
+ * restarts. Generalizes the storefront's hand-rolled `swrGet`/`getNavMap` state
+ * machines (fresh → stale-while-revalidate → last-known-good → negative cache →
+ * single-flight) and adds the durable tier + a purge surface.
+ *
+ * On a successful fetch the value is written through to BOTH tiers (the durable
+ * write is fire-and-forget — it never blocks or fails the request). On an origin
+ * failure the cache degrades gracefully: prior memory value → durable value →
+ * `null` (negative-cached). The durable copy is therefore always the last content
+ * the origin actually served — there is no hand-maintained second source of truth
+ * to drift.
+ *
+ * `T` MUST be JSON-serializable (see {@link CacheEntry}).
+ */
+export class SwrCache<T = unknown> {
+  private readonly store?: CacheStore;
+  private readonly freshMs: number;
+  private readonly staleMs: number;
+  private readonly negTtlMs: number;
+  private readonly keyPrefix: string;
+  private readonly now: () => number;
+  private readonly mem = new Map<string, MemEntry<T>>();
+  private readonly neg = new Map<string, number>();
+  private readonly inflight = new Map<string, Promise<T>>();
+  /**
+   * Bumped by every `purge`/`purgeAll`. A cache-population step (write-back after
+   * a fetch, durable-LKG hydration, negative-cache set) captures the generation
+   * when it STARTS and only applies its write if the generation is unchanged — so
+   * a purge that lands mid-flight is never silently re-populated by an in-flight
+   * (possibly stale, possibly coalesced) fetch. Fences the "lost purge" race.
+   */
+  private generation = 0;
+
+  constructor(opts: SwrCacheOptions) {
+    this.store = opts.store;
+    this.freshMs = opts.freshMs;
+    this.staleMs = opts.staleMs;
+    this.negTtlMs = opts.negTtlMs;
+    this.keyPrefix = opts.keyPrefix ?? '';
+    // Call `Date.now()` at read time (not a captured reference) so a test that installs
+    // fake timers AFTER construction still controls this cache's clock.
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  private durableKey(key: string): string {
+    return this.keyPrefix ? `${this.keyPrefix}${key}` : key;
+  }
+
+  /**
+   * Coalesce concurrent fetches for the same key onto one in-flight promise, and
+   * populate BOTH tiers on success — exactly once per real fetch, so a later
+   * request that rides an in-flight fetch (started before a purge) can't smuggle a
+   * stale value past that purge. The write-back is gated by the generation at
+   * FETCH-START: if a purge bumped it while the fetch was outstanding, the result
+   * is returned to callers but NOT cached.
+   */
+  private runFetch(key: string, fetcher: () => Promise<T>): Promise<T> {
+    const existing = this.inflight.get(key);
+    if (existing) return existing;
+    const gen = this.generation;
+    const p = (async () => {
+      try {
+        const value = await fetcher();
+        if (this.generation === gen) {
+          this.mem.set(key, { value, at: this.now() });
+          this.writeThrough(key, value);
+          this.neg.delete(key);
+        }
+        return value;
+      } finally {
+        this.inflight.delete(key);
+      }
+    })();
+    this.inflight.set(key, p);
+    return p;
+  }
+
+  /** Persist to the durable tier without ever blocking/failing the request path. */
+  private writeThrough(key: string, value: T): void {
+    if (!this.store) return;
+    const entry: CacheEntry<T> = { value, storedAt: this.now() };
+    void this.store.set(this.durableKey(key), entry as CacheEntry).catch(() => {});
+  }
+
+  /**
+   * Read `key`, fetching via `fetcher` on a miss. `fetcher` MUST throw to signal a
+   * failure/absent value (mirrors the storefront's throwing fetchers); its resolved
+   * value is cached. Returns `{ value: null }` only when the origin fails and there
+   * is nothing cached in either tier.
+   */
+  async get(key: string, fetcher: () => Promise<T>): Promise<SwrResult<T>> {
+    const gen = this.generation; // snapshot for purge-fencing the failure-path writes
+    const now = this.now();
+    const entry = this.mem.get(key);
+
+    if (entry && now - entry.at < this.freshMs) {
+      return { value: entry.value, source: 'fresh' };
+    }
+
+    // Negative cache: a recently-failed key with no positive memory entry
+    // short-circuits, so a broken key under load doesn't issue one call per request.
+    const failedAt = this.neg.get(key);
+    if (!entry && failedAt !== undefined) {
+      if (now - failedAt < this.negTtlMs) return { value: null, source: 'negative' };
+      this.neg.delete(key); // opportunistically reclaim the expired negative entry
+    }
+
+    if (entry && now - entry.at < this.staleMs) {
+      // Serve stale immediately; revalidate in the background (populates via runFetch).
+      void this.runFetch(key, fetcher).catch(() => {});
+      return { value: entry.value, source: 'stale' };
+    }
+
+    try {
+      const value = await this.runFetch(key, fetcher);
+      return { value, source: 'cold' };
+    } catch {
+      // Origin failed. Degrade: in-memory LKG → durable LKG → null (negative-cached).
+      // We deliberately DON'T advance `entry.at` here — serving last-known-good must
+      // not masquerade as `fresh` nor delay recovery; the very next request retries
+      // the origin and picks up a recovered KB immediately (parity with the origin
+      // storefront swrGet).
+      if (entry) {
+        return { value: entry.value, source: 'lkg-memory' };
+      }
+      if (this.store) {
+        const durable = await this.store.get(this.durableKey(key)).catch(() => null);
+        if (durable) {
+          const value = durable.value as T;
+          // Hydrate memory with the durable entry's OWN timestamp (not `now`), so it
+          // isn't served as `fresh`, and skip the write if a purge intervened.
+          if (this.generation === gen) this.mem.set(key, { value, at: durable.storedAt });
+          return { value, source: 'lkg-durable' };
+        }
+      }
+      if (this.generation === gen) this.neg.set(key, this.now());
+      return { value: null, source: 'error' };
+    }
+  }
+
+  /** Immediately evict one key from memory AND the durable store. */
+  async purge(key: string): Promise<void> {
+    this.generation++; // fence any in-flight fetch from re-populating what we evict
+    this.mem.delete(key);
+    this.neg.delete(key);
+    if (this.store) await this.store.delete(this.durableKey(key));
+  }
+
+  /** Evict every key (or those starting with `prefix`) from memory AND durable. */
+  async purgeAll(prefix?: string): Promise<void> {
+    this.generation++; // fence in-flight fetches (see `generation`)
+    if (prefix) {
+      for (const k of [...this.mem.keys()]) if (k.startsWith(prefix)) this.mem.delete(k);
+      for (const k of [...this.neg.keys()]) if (k.startsWith(prefix)) this.neg.delete(k);
+      if (this.store) await this.store.clear(this.durableKey(prefix));
+    } else {
+      this.mem.clear();
+      this.neg.clear();
+      if (this.store) await this.store.clear();
+    }
+  }
+
+  /** Test-only: clear the in-memory tiers (leaves the durable store intact). */
+  resetMemory(): void {
+    this.mem.clear();
+    this.neg.clear();
+    this.inflight.clear();
+  }
+}

package/src/types.ts

@@ -0,0 +1,42 @@
+/**
+ * A single cached value plus the freshness basis a read-through layer needs.
+ * `value` MUST be JSON-serializable — the filesystem (and future S3/Postgres)
+ * adapters persist it as JSON, so a Map/Set/class instance must be reduced to a
+ * plain object/array before caching (e.g. cache the raw nav-tree array, not a
+ * built `Map`).
+ */
+export interface CacheEntry<T = unknown> {
+  /** The cached value (JSON-serializable). */
+  value: T;
+  /** Epoch-ms when this entry was stored — the age basis for SWR freshness. */
+  storedAt: number;
+  /** Optional caller metadata (e.g. source tier, etag) — persisted verbatim. */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Pluggable durable storage for cache entries. The read-through logic
+ * (`SwrCache`) is storage-agnostic — swap the adapter to change where the
+ * last-known-good copy lives.
+ *
+ * Ships today: {@link FsCacheStore} (local filesystem). Designed-for, not yet
+ * implemented: an `S3CacheStore` (shared last-known-good across pods) and a
+ * `PgCacheStore` (transactional, queryable) — both satisfy this exact interface,
+ * so adopting one is a constructor swap with no change to callers.
+ *
+ * Implementations must be TOTAL: a missing key, a missing backing store, or a
+ * corrupt/partial entry resolves to `null` (a cache miss), never a throw — a
+ * cache is a best-effort accelerator and must never take down the request path.
+ */
+export interface CacheStore {
+  /** Return the entry for `key`, or `null` on miss/corruption. Never throws for a miss. */
+  get(key: string): Promise<CacheEntry | null>;
+  /** Persist `entry` under `key`, replacing any existing value atomically. */
+  set(key: string, entry: CacheEntry): Promise<void>;
+  /** Remove `key`. A missing key is a no-op, not an error. */
+  delete(key: string): Promise<void>;
+  /** Remove every entry, or only those whose key starts with `prefix`. */
+  clear(prefix?: string): Promise<void>;
+  /** List stored keys, optionally filtered to those starting with `prefix`. */
+  keys(prefix?: string): Promise<string[]>;
+}