@ultimat3/cache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @ultimat3/cache 🗂️
+
+Four tiers. **One invalidation graph, not three.**
+
+```ts
+cache: { invalidates: [tag.post, tag.feed] }
+```
+
+That declaration on an `action` reaches the request memo, the in-process LRU, Redis, every
+ISR route that rendered a post, and the CDN surrogate keys — in one hop, through one
+function. Manual cache invalidation is the single worst thing you can ask an agent to do,
+so the framework removes the decision: tag your writes, never your reads.
+
+## Why one graph
+
+Every framework that ships "cache tags", "revalidate paths", and "CDN purge" as three
+separate mechanisms produces the same bug — two of the three fire, the third serves last
+week. `graph.ts` is a module singleton with **no exported constructor**. Cache keys, ISR
+routes, CDN paths and live queries all register as `CacheDependent`s against tags in that
+one graph, and `invalidateTags()` is the only reader. There is nowhere to put a second one.
+
+## Tiers
+
+Reads walk down until a hit, then populate every tier they walked past. Writes populate all.
+
+| Order | Tier | Backing | Invalidation | Omit when |
+|---|---|---|---|---|
+| 0 | `request-memo` | ALS context (`WeakMap`) | dies with the request | never |
+| 1 | `lru` | in-process, byte-budgeted | tag index | never |
+| 2 | `redis` | `Bun.redis` | tag→keys set, one `EVAL` | single node |
+| 3 | `cdn` | headers + purge driver | surrogate keys | no CDN |
+
+A tier is a `CacheTier` (`get`/`set`/`del`/`invalidateTags`). Swap or omit any of them
+without touching a call site — order comes from `TIER_ORDER`, not registration order.
+
+```ts
+import { createCacheStack, createLruTier, createMemoTier, registerTier } from '@ultimat3/cache';
+
+const stack = createCacheStack([createMemoTier(), createLruTier({ maxBytes: 64 * 1024 * 1024 })]);
+for (const tier of stack.tiers) registerTier(tier);
+
+const feed = await stack.read('feed:org-1', () => db.posts.recent(), {
+  ttlMs: 30_000,
+  tags: [tag('post')],
+});
+```
+
+## Tags
+
+```ts
+tag.post          // the collection — busts lists
+tag('post', id)   // one row — also busts the lists that contained it
+tagsFor(Post, row) // both, for a repo write
+```
+
+Wire form is `post` / `post:<id>`, identical in Redis keys, CDN surrogate keys and
+`--json` reports. Invalidation is asymmetric-tolerant on purpose: busting a collection
+kills its rows, busting a row kills the collections that held it.
+
+`tag.post` is typed via a registry that `x manifest` generates, so `tag.pots` is a build
+error:
+
+```ts
+declare module '@ultimat3/cache' {
+  interface CacheTagRegistry { post: true; feed: true }
+}
+```
+
+## Invalidating
+
+```ts
+const report = await invalidateTags([tag('post', postId)]);
+```
+
+One function. Returns the report the `/_x` cache panel and `x cache bust --json` render:
+
+```json
+{
+  "tags": ["post:1"],
+  "tiers": [{ "tier": "lru", "keys": ["feed"] }, { "tier": "redis", "keys": ["feed"] }],
+  "isr": ["/blog", "/blog/hello"],
+  "cdn": ["post:1"],
+  "liveQueries": [],
+  "durationMs": 1.4,
+  "errors": []
+}
+```
+
+A dead tier lands in `errors` and never throws — a Redis outage must not fail the write
+that triggered the bust. Entries there expire by TTL instead.
+
+Every report is also kept: `recentInvalidations()` hands back the last 100, newest first, each
+one naming the span that triggered it. That is the log the `/_x` cache panel renders — "did it
+actually clear?" is answerable without a log dive because the one fan-out path retained the
+answer, not because a second recorder was wired next to it.
+
+## CDN
+
+```ts
+cacheHeaders({ sMaxAge: 300, staleWhileRevalidate: 86_400, tags: [tag('post', id)] });
+// => { 'Cache-Control': 'public, max-age=0, s-maxage=300, stale-while-revalidate=86400',
+//      'Surrogate-Key': 'post:1' }
+```
+
+The surrogate keys **are** the tags, byte for byte, so an edge purge and an app-level
+invalidation can never mean different things. Three `PurgeDriver`s ship:
+
+| Driver | Purge | Purge all | Batch |
+|---|---|---|---|
+| `noopPurgeDriver()` | echoes the keys back | resolves | — |
+| `fastlyPurgeDriver({ apiToken, serviceId })` | `POST /service/<id>/purge` with `surrogate_keys` | `POST /service/<id>/purge_all` | 256 keys |
+| `cloudflarePurgeDriver({ apiToken, zoneId })` | `POST /zones/<id>/purge_cache` with `tags` | same call, `purge_everything` | 30 tags |
+
+Which one a process installs comes from the environment, never from `app.config.ts` —
+nothing loads that file's contents at runtime:
+
+| Set | Selects |
+|---|---|
+| `FASTLY_API_TOKEN` + `FASTLY_SERVICE_ID` | Fastly |
+| `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ZONE_ID` | Cloudflare |
+| neither | nothing is purged, and `x dev` prints `cdn=none` |
+
+Both pairs at once is `X_CONFIG_INVALID`: one process purges exactly one edge. Half a pair
+is refused the same way — treating it as "no CDN" is how a deployment ships believing it
+purges. Either refusal names the keys that are actually set, in `cause` and in
+`meta.configured`, so the diagnostic can never point at a variable nobody set. A refused
+purge is `X_CACHE_PURGE_FAILED` carrying `meta.retryable`, and it lands in `report.errors`
+rather than failing the write that triggered it.
+
+## Semantic cache
+
+For LLM calls, where "list my orders" and "show me my orders" must hit the same entry.
+`createMemorySemanticCache()` does cosine similarity at a 0.92 threshold (tight on
+purpose — a false hit answers the wrong question, which is worse than a miss) and is the
+only backing this package ships — it is O(n) and in-process. The interface (`SemanticCache`)
+is a driver seam for that reason; a Postgres/pgvector-backed implementation does not exist
+yet here (`@ultimat3/ai`'s `PgVectorStore` is a separate store, for RAG retrieval, not this
+cache).
+
+## Errors
+
+| Code | Cause |
+|---|---|
+| `X_CACHE_DRIVER_UNAVAILABLE` | `Bun.redis` missing, a purge driver built without its token, or a batch size that is not a positive integer |
+| `X_CACHE_PURGE_FAILED` | the CDN refused a purge, or a key it would split on whitespace |
+| `X_CACHE_TAG_UNKNOWN` | a tag no entity declared — usually a typo |
+| `X_CACHE_TOO_LARGE` | one entry exceeds a tier's whole byte budget |
+
+## Boundary
+
+Tier 1. Imports `@ultimat3/core` and `@ultimat3/schema` only. Knows nothing about
+entities, HTTP or jobs — `tagsFor()` takes structural `{ name }` / `{ id }` arguments so
+`@ultimat3/entity` can depend on cache and never the reverse.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/cache",
+  "version": "1.0.0",
+  "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/cache"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/cdn.ts

@@ -0,0 +1,106 @@
+// Tier 3: the CDN. Ultimate does not read from the CDN (it sits in front of us), so this
+// tier's job is the other two thirds of caching: emitting the headers that let the CDN hold
+// the response, and purging by surrogate key when a tag changes. Surrogate keys ARE the
+// tags — same strings, so a CDN purge cannot drift from an app-level invalidation.
+
+import type { CacheTag } from './tags';
+import { serializeTags } from './tags';
+import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
+
+export interface CacheHeaderOptions {
+  /** Browser freshness, seconds. */
+  readonly maxAge?: number;
+  /** Shared (CDN) freshness, seconds. */
+  readonly sMaxAge?: number;
+  /** Serve stale for N seconds while revalidating behind the request. */
+  readonly staleWhileRevalidate?: number;
+  readonly staleIfError?: number;
+  /** Per-user responses: never shared, no surrogate keys. */
+  readonly visibility?: 'public' | 'private';
+  readonly immutable?: boolean;
+  readonly tags?: readonly CacheTag[];
+}
+
+/** `Cache-Control` + `Surrogate-Key`, ready to spread into a `Headers` init. */
+export function cacheHeaders(options: CacheHeaderOptions = {}): Record<string, string> {
+  const visibility = options.visibility ?? 'public';
+  const parts: string[] = [visibility];
+
+  if (visibility === 'private') {
+    parts.push('no-store');
+    return { 'Cache-Control': parts.join(', ') };
+  }
+
+  parts.push(`max-age=${options.maxAge ?? 0}`);
+  if (options.sMaxAge !== undefined) parts.push(`s-maxage=${options.sMaxAge}`);
+  if (options.staleWhileRevalidate !== undefined) {
+    parts.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+  }
+  if (options.staleIfError !== undefined) parts.push(`stale-if-error=${options.staleIfError}`);
+  if (options.immutable === true) parts.push('immutable');
+
+  const headers: Record<string, string> = { 'Cache-Control': parts.join(', ') };
+  const keys = serializeTags(options.tags ?? []);
+  if (keys.length > 0) headers['Surrogate-Key'] = keys.join(' ');
+  return headers;
+}
+
+export interface PurgeDriver {
+  readonly name: string;
+  /** Purge by surrogate key. Returns the keys the provider accepted. */
+  purge(keys: readonly string[]): Promise<readonly string[]>;
+  purgeAll(): Promise<void>;
+}
+
+/** Default: the CDN is optional infrastructure, so its absence must not fail a write. */
+export function noopPurgeDriver(): PurgeDriver {
+  return {
+    name: 'noop',
+    purge(keys) {
+      return Promise.resolve(keys);
+    },
+    purgeAll() {
+      return Promise.resolve();
+    },
+  };
+}
+
+export interface CdnTierOptions {
+  readonly purge?: PurgeDriver;
+  /**
+   * Maps a cache key to the CDN path(s) it renders, for key-level purges. Those paths are
+   * purged **as surrogate keys** — `PurgeDriver.purge` has one currency and this is it — so a
+   * host using this must tag those responses with their own path.
+   */
+  readonly pathsForKey?: (key: string) => readonly string[];
+}
+
+export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
+  const driver = options.purge ?? noopPurgeDriver();
+
+  return {
+    name: 'cdn',
+
+    get<T>(): Promise<CacheEntry<T> | undefined> {
+      // The CDN is upstream of the origin; a read here would be a round trip to ourselves.
+      return Promise.resolve(undefined);
+    },
+
+    set<T>(_key: string, _value: T, _options?: CacheSetOptions): Promise<void> {
+      // Population happens by responding with `cacheHeaders()`, never by pushing.
+      return Promise.resolve();
+    },
+
+    async del(key: string): Promise<void> {
+      const paths = options.pathsForKey?.(key) ?? [];
+      if (paths.length > 0) await driver.purge(paths);
+    },
+
+    async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      const keys = serializeTags(tags);
+      if (keys.length === 0) return { tier: 'cdn', keys: [] };
+      const accepted = await driver.purge(keys);
+      return { tier: 'cdn', keys: accepted };
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,102 @@
+// The X_* codes owned by @ultimat3/cache. Each one names the exact config change or
+// command that resolves it, so an agent reading the failure can act without a doc lookup.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const CACHE_OWNED_ERROR_CODES = [
+  'X_CACHE_DRIVER_UNAVAILABLE',
+  'X_CACHE_PURGE_FAILED',
+  'X_CACHE_TAG_UNKNOWN',
+  'X_CACHE_TOO_LARGE',
+] as const;
+
+/** Every code cache can throw. It borrows none: every remote driver here is implemented. */
+export const CACHE_ERROR_CODES = [...CACHE_OWNED_ERROR_CODES] as const;
+
+export type CacheOwnedErrorCode = (typeof CACHE_OWNED_ERROR_CODES)[number];
+export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[number];
+
+export const CACHE_ERROR_TITLES: Readonly<Record<CacheOwnedErrorCode, string>> = {
+  X_CACHE_DRIVER_UNAVAILABLE: "a tier's backing store is missing",
+  X_CACHE_PURGE_FAILED: 'the CDN refused a purge',
+  X_CACHE_TAG_UNKNOWN: 'a tag no entity declared',
+  X_CACHE_TOO_LARGE: "one entry exceeds the tier's byte budget",
+};
+
+// One unconditional call, so a second package claiming one of cache's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(CACHE_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+const docsFor = (code: CacheErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/** A tier's backing store is missing at runtime (no Redis binding, no CDN token). */
+export class CacheDriverUnavailableError extends UltimateError {
+  constructor(input: { driver: string; cause: string; fix: string }) {
+    super({
+      code: 'X_CACHE_DRIVER_UNAVAILABLE',
+      cause: `cache tier "${input.driver}" is unavailable: ${input.cause}`,
+      fix: input.fix,
+      docs: docsFor('X_CACHE_DRIVER_UNAVAILABLE'),
+    });
+  }
+}
+
+/**
+ * A tag was used that no entity declared. Caught here rather than at read time because a
+ * typo in `invalidates: [tag.pots]` is otherwise a silent stale-forever bug.
+ */
+export class CacheTagUnknownError extends UltimateError {
+  constructor(input: { tag: string; known: readonly string[] }) {
+    super({
+      code: 'X_CACHE_TAG_UNKNOWN',
+      cause: `tag "${input.tag}" is not declared by any entity (declared: ${
+        input.known.length > 0 ? input.known.join(', ') : 'none'
+      })`,
+      fix: 'x manifest',
+      docs: docsFor('X_CACHE_TAG_UNKNOWN'),
+    });
+  }
+}
+
+/** A single entry cannot fit the tier's byte budget, so caching it would evict everything. */
+export class CacheTooLargeError extends UltimateError {
+  constructor(input: { key: string; bytes: number; maxBytes: number; tier: string }) {
+    super({
+      code: 'X_CACHE_TOO_LARGE',
+      cause: `entry "${input.key}" is ${input.bytes}B, over the ${input.tier} budget of ${input.maxBytes}B`,
+      fix: `raise cache.${input.tier}.maxBytes in app.config.ts, or cache a projection instead of the row`,
+      docs: docsFor('X_CACHE_TOO_LARGE'),
+    });
+  }
+}
+
+/**
+ * A remote purge did not happen. Never fatal on its own — `invalidateTags` collects it into
+ * `report.errors` so a dead CDN cannot fail the write that triggered the bust — which is exactly
+ * why `retryable` is carried rather than guessed: the caller decides whether the same purge,
+ * unchanged, is worth sending again, and a stale edge until TTL is the cost of getting it wrong.
+ */
+export class CachePurgeFailedError extends UltimateError {
+  constructor(input: {
+    driver: string;
+    detail: string;
+    status?: number | undefined;
+    retryable: boolean;
+    fix: string;
+  }) {
+    const status = input.status === undefined ? '' : ` (HTTP ${input.status})`;
+    super({
+      code: 'X_CACHE_PURGE_FAILED',
+      cause: `${input.driver} refused the purge${status}: ${input.detail}`,
+      fix: input.fix,
+      docs: docsFor('X_CACHE_PURGE_FAILED'),
+      meta: {
+        driver: input.driver,
+        retryable: input.retryable,
+        ...(input.status === undefined ? {} : { status: input.status }),
+      },
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+// Public API of @ultimat3/cache. Explicit, no `export *`.
+
+export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
+export { cacheHeaders, createCdnTier, noopPurgeDriver } from './cdn';
+export type { CacheErrorCode } from './errors';
+export {
+  CACHE_ERROR_CODES,
+  CACHE_ERROR_TITLES,
+  CacheDriverUnavailableError,
+  CachePurgeFailedError,
+  CacheTagUnknownError,
+  CacheTooLargeError,
+} from './errors';
+export type { CacheDependent, DependentKind } from './graph';
+export {
+  dependentsOf,
+  dependentsOfKind,
+  graphSize,
+  graphSnapshot,
+  registerDependent,
+  resetGraph,
+  unregisterDependent,
+} from './graph';
+export type { InvalidationEvent, InvalidationReport, Revalidator } from './invalidate';
+export {
+  invalidateTags,
+  invalidateWireTags,
+  recentInvalidations,
+  registeredTiers,
+  registerRevalidator,
+  registerTier,
+  resetTiers,
+} from './invalidate';
+export type { LruOptions, LruStats } from './lru';
+
+export { createLruTier, estimateBytes, LruCache } from './lru';
+export { clearMemo, createMemoTier, memoSize } from './memo';
+export type { CloudflarePurgeOptions } from './purge-cloudflare';
+export {
+  CLOUDFLARE_API_URL,
+  CLOUDFLARE_MAX_TAGS_PER_REQUEST,
+  cloudflarePurgeDriver,
+} from './purge-cloudflare';
+export type { PurgeEnvironment, PurgeSelection } from './purge-env';
+export { CDN_PURGE_ENV_KEYS, isNoopPurgeDriver, selectPurgeDriver } from './purge-env';
+export type { FastlyPurgeOptions } from './purge-fastly';
+export { FASTLY_API_URL, FASTLY_MAX_KEYS_PER_REQUEST, fastlyPurgeDriver } from './purge-fastly';
+export type { PurgeFetch } from './purge-http';
+export { DEFAULT_PURGE_TIMEOUT_MS } from './purge-http';
+export type { RedisLike, RedisTierOptions } from './redis';
+export { createRedisTier, REDIS_INVALIDATE_SCRIPT } from './redis';
+export type {
+  Embedding,
+  SemanticCache,
+  SemanticCacheOptions,
+  SemanticHit,
+  SemanticRememberOptions,
+} from './semantic';
+export { cosineSimilarity, createMemorySemanticCache } from './semantic';
+export type { CacheTag, CacheTagRegistry, TagFactory } from './tags';
+export {
+  assertKnownTags,
+  declareTags,
+  knownTags,
+  parseTag,
+  resetDeclaredTags,
+  serializeTag,
+  serializeTags,
+  tag,
+  tagMatches,
+  tagsFor,
+  tagsIntersect,
+} from './tags';
+export type {
+  CacheEntry,
+  CacheSetOptions,
+  CacheStack,
+  CacheTier,
+  TierInvalidation,
+  TierName,
+} from './tiers';
+export { createCacheStack, isExpired, nowMs, sortTiers, TIER_ORDER } from './tiers';

package/src/invalidate.ts

@@ -0,0 +1,170 @@
+// THE single invalidation entry point. `action.cache.invalidates`, `x cache bust`, the MCP
+// tool and the admin panel all call this one function — nothing else may talk to a tier's
+// `invalidateTags` directly. One hop reaches memo, LRU, Redis, ISR routes and the CDN, and
+// the returned report is what the `/_x` cache panel renders, so "did it actually clear?" is
+// answerable without a log dive.
+
+import { currentSpan, logger, systemClock, withSpan } from '@ultimat3/core';
+import { dependentsOfKind } from './graph';
+import type { CacheTag } from './tags';
+import { assertKnownTags, parseTag, serializeTags } from './tags';
+import type { CacheTier, TierInvalidation } from './tiers';
+import { sortTiers } from './tiers';
+
+/** Revalidates one ISR route path. Provided by `@ultimat3/render`; absent on a worker. */
+export type Revalidator = (path: string) => Promise<void> | void;
+
+export interface InvalidationReport {
+  readonly tags: readonly string[];
+  readonly tiers: readonly TierInvalidation[];
+  /** ISR route paths queued for regeneration. */
+  readonly isr: readonly string[];
+  readonly cdn: readonly string[];
+  readonly liveQueries: readonly string[];
+  readonly durationMs: number;
+  readonly errors: readonly { tier: string; message: string }[];
+}
+
+/** One completed `invalidateTags` call, kept for the `/_x` cache panel. */
+export interface InvalidationEvent {
+  /** ISO-8601, from core's `systemClock` — never `new Date()`. */
+  readonly at: string;
+  /** Wire-form tags, exactly `report.tags`. */
+  readonly tags: readonly string[];
+  /**
+   * Everything the fan-out actually cleared: every tier key, plus the ISR paths, CDN paths
+   * and live queries.
+   */
+  readonly busted: readonly string[];
+  /**
+   * What triggered it: the name of the span active when `invalidateTags` was called, or
+   * `'invalidateTags'`.
+   */
+  readonly source: string;
+  readonly durationMs: number;
+  /** Tier failures, verbatim from the report — a partial bust must not read as a clean one. */
+  readonly errors: readonly { readonly tier: string; readonly message: string }[];
+}
+
+// A dev log, not an audit trail — capped so a long-lived `x dev` process cannot grow it forever.
+const MAX_INVALIDATION_LOG = 100;
+
+/** Newest first. Module-private; read it through `recentInvalidations()`. */
+const invalidationLog: InvalidationEvent[] = [];
+
+function recordInvalidation(event: InvalidationEvent): void {
+  invalidationLog.unshift(event);
+  invalidationLog.length = Math.min(invalidationLog.length, MAX_INVALIDATION_LOG);
+}
+
+/** What the `/_x` cache panel renders: newest first, capped, a copy of the live log. */
+export function recentInvalidations(): readonly InvalidationEvent[] {
+  return [...invalidationLog];
+}
+
+const registry: CacheTier[] = [];
+let revalidator: Revalidator | undefined;
+
+/** Tiers register at boot from `app.config.ts`; order is normalised, not trusted. */
+export function registerTier(tier: CacheTier): void {
+  const existing = registry.findIndex((known) => known.name === tier.name);
+  if (existing === -1) registry.push(tier);
+  else registry[existing] = tier;
+}
+
+export function registeredTiers(): readonly CacheTier[] {
+  return sortTiers(registry);
+}
+
+/** Test seam: drops every registered tier, the revalidator, and the invalidation log. */
+export function resetTiers(): void {
+  registry.length = 0;
+  revalidator = undefined;
+  invalidationLog.length = 0;
+}
+
+export function registerRevalidator(next: Revalidator): void {
+  revalidator = next;
+}
+
+/**
+ * Fan out `tags` across every registered tier plus the dependency graph. Never throws for a
+ * tier failure: a dead Redis must not fail the write that triggered the bust — the failure
+ * lands in `report.errors` and the entry expires by TTL.
+ */
+export function invalidateTags(tags: readonly CacheTag[]): Promise<InvalidationReport> {
+  // Captured before `withSpan` opens `cache.invalidate` below: inside that callback the active
+  // span is already this call's own, which would make every event's source the same string.
+  const source = currentSpan()?.name ?? 'invalidateTags';
+
+  return withSpan('cache.invalidate', async (): Promise<InvalidationReport> => {
+    const startedAt = performance.now();
+    assertKnownTags(tags);
+
+    const tiers: TierInvalidation[] = [];
+    const errors: { tier: string; message: string }[] = [];
+
+    for (const tier of sortTiers(registry)) {
+      try {
+        tiers.push(await tier.invalidateTags(tags));
+      } catch (error) {
+        errors.push({
+          tier: tier.name,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    const isr = dependentsOfKind(tags, 'isr-route');
+    const cdn = dependentsOfKind(tags, 'cdn-path');
+    const liveQueries = dependentsOfKind(tags, 'live-query');
+
+    for (const path of isr) {
+      try {
+        await revalidator?.(path);
+      } catch (error) {
+        errors.push({
+          tier: 'isr',
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    const report: InvalidationReport = {
+      tags: serializeTags(tags),
+      tiers,
+      isr,
+      cdn,
+      liveQueries,
+      durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+      errors,
+    };
+
+    recordInvalidation({
+      at: systemClock.now().toISOString(),
+      tags: report.tags,
+      busted: dedupe([
+        ...report.tiers.flatMap((entry) => entry.keys),
+        ...report.isr,
+        ...report.cdn,
+        ...report.liveQueries,
+      ]),
+      source,
+      durationMs: report.durationMs,
+      errors: report.errors,
+    });
+
+    if (errors.length > 0) logger.warn('cache.invalidate.partial', { ...report });
+    return report;
+  });
+}
+
+/** First-seen order kept — a union of what actually changed, not a sorted report. */
+function dedupe(values: readonly string[]): readonly string[] {
+  return [...new Set(values)];
+}
+
+/** Convenience for `x cache bust post:1` — accepts the wire form agents see in reports. */
+export function invalidateWireTags(wire: readonly string[]): Promise<InvalidationReport> {
+  return invalidateTags(wire.map(parseTag));
+}