@ultimat3/cache 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -34,6 +34,17 @@ Tier 1. Tagged caching + THE invalidation graph.
 - One graph. `graph.ts` exports functions over module state and **no constructor** — do not
   add one, do not add a second registry anywhere else.
 - Tag order is `TIER_ORDER`, never registration order. `sortTiers()` enforces it.
+- **The rung NAMES are `@ultimat3/core`'s (`CACHE_TIERS`); the ladder is this package's.**
+  `TierName` is an alias of core's `CacheTierName` and `TIER_ORDER` IS `CACHE_TIERS` — the same
+  array object, which `tier-vocabulary.test.ts` asserts by identity. Tier 0 owns the spelling
+  because `app.config.ts`'s `cache.tiers` names the same rungs and core is the only place a tier-0
+  declaration and this package can both see. It was spelled twice until 2026-08-22 (issue #293):
+  config accepted `memo | lru | shared | isr | cdn`, so `cache: { tiers: ['isr'] }` typechecked and
+  selected nothing, and `sortTiers` would have placed either unknown name at `-1` — AHEAD of the
+  request memo. Adding a rung is an edit to `packages/core/src/cache-vocabulary.ts` plus a factory
+  here; `scripts/render-modes.ts` refuses a second declaration of the set anywhere in `packages/*/src`.
+  **`isr` is not and never was a tier** — it is a `RenderMode`; the `'isr'` in `invalidate.ts` is an
+  ISR ROUTE queued for regeneration (`DependentKind = 'isr-route'`), which is a different subject.
 - **`bestEffort()` is public, and it is the only sanctioned way to swallow a cache refusal.** A
   store outside this package that wraps its own `try/catch` degrades invisibly, and a second
   failure log nobody reads is what this bounded one exists to prevent. Its label is `TierLabel` —
@@ -241,6 +252,13 @@ Tier 1. Tagged caching + THE invalidation graph.
   and clears nothing, which is the one CDN failure no later read can catch.
 - `retryable` on `X_CACHE_PURGE_FAILED` is derived, never guessed: 408/409/425/429 and 5xx, plus
   any request that never got a status. That table lives in `purge-http.ts` and is edited there.
+  **It reaches `error.retry` too, `As of 2026-08-23`** — `CachePurgeFailedError` passes
+  `retry: input.retryable ? 'retryable' : 'terminal'`. Without it the constructor fell back to
+  `retryFor('X_CACHE_PURGE_FAILED')`, this package registers no retry class, and the default is
+  `terminal`: a 429 serialised as `{ "retry": "terminal", "meta": { "retryable": true } }` — one
+  error answering the retry question two ways, with `errorRetry()` (the one question a retry loop
+  asks) giving the wrong one. Per-INSTANCE, never `registerErrorRetry`: one code covers a 401 that
+  will never land and a 429 that will.
 - `X_CACHE_PURGE_FAILED` means a provider refused. A batch size that is not a positive integer is
   this package miswired, so `chunked()` raises `X_CACHE_DRIVER_UNAVAILABLE` instead — and it raises
   it *before* the loop, because a `0` spins forever and a `NaN` yields one empty batch, a purge that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "8.0.0"
+    "@ultimat3/core": "10.0.0"
   }
 }

package/src/errors.ts

@@ -33,8 +33,6 @@ 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 }) {
@@ -42,7 +40,6 @@ export class CacheDriverUnavailableError extends UltimateError {
       code: 'X_CACHE_DRIVER_UNAVAILABLE',
       cause: `cache tier "${input.driver}" is unavailable: ${input.cause}`,
       fix: input.fix,
-      docs: docsFor('X_CACHE_DRIVER_UNAVAILABLE'),
     });
   }
 }
@@ -59,7 +56,6 @@ export class CacheTagUnknownError extends UltimateError {
         input.known.length > 0 ? input.known.join(', ') : 'none'
       })`,
       fix: 'x manifest',
-      docs: docsFor('X_CACHE_TAG_UNKNOWN'),
     });
   }
 }
@@ -71,7 +67,6 @@ export class CacheTooLargeError extends UltimateError {
       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'),
     });
   }
 }
@@ -93,7 +88,6 @@ export class CacheTtlInvalidError extends UltimateError {
         input.ttlMs,
       )}; a TTL is a positive, finite number of milliseconds`,
       fix: `cache.write('${input.key}', value, { ttlMs: 60_000 })   # or drop the option for the tier default; a value you do not want held is one you do not write`,
-      docs: docsFor('X_CACHE_TTL_INVALID'),
       meta: { key: input.key, ttlMs: input.ttlMs, tier: input.tier },
     });
   }
@@ -116,7 +110,6 @@ export class CacheJitterInvalidError extends UltimateError {
         input.jitterFraction,
       )}; a jitter fraction is a finite number in [0, 1)`,
       fix: `set cache.${input.tier}.jitterFraction in app.config.ts to a value in [0, 1) — 0.05 is the default, 0 disables jitter`,
-      docs: docsFor('X_CACHE_JITTER_INVALID'),
       meta: { tier: input.tier, jitterFraction: input.jitterFraction },
     });
   }
@@ -141,7 +134,11 @@ export class CachePurgeFailedError extends UltimateError {
       code: 'X_CACHE_PURGE_FAILED',
       cause: `${input.driver} refused the purge${status}: ${input.detail}`,
       fix: input.fix,
-      docs: docsFor('X_CACHE_PURGE_FAILED'),
+      // Per-instance rather than `registerErrorRetry`, because one code covers both a 401 (never
+      // worth resending) and a 429 (worth resending unchanged). Without it every purge failure
+      // fell back to the registry's `terminal` while `meta.retryable` said otherwise — one error
+      // answering the retry question two ways.
+      retry: input.retryable ? 'retryable' : 'terminal',
       meta: {
         driver: input.driver,
         retryable: input.retryable,

package/src/purge-fastly.ts

@@ -61,7 +61,10 @@ const fixFor = (status: number): string => {
 function acceptedFrom(body: PurgeBody, batch: readonly string[]): string[] {
   const payload = body.json;
   if (!isRecord(payload)) return [...batch];
-  const named = batch.filter((key) => key in payload);
+  // `Object.hasOwn`, never `in`: a surrogate key named `constructor` or `toString` answered `true`
+  // out of a body that never mentioned it, so `InvalidationReport.tiers` listed keys nothing had
+  // purged — a partial bust reading as a clean one.
+  const named = batch.filter((key) => Object.hasOwn(payload, key));
   return named.length > 0 ? named : [...batch];
 }
 

package/src/tiers.ts

@@ -3,8 +3,8 @@
 // so a deployment can omit Redis (single node) or add the CDN tier without touching call
 // sites. Order is data, not control flow.
 
-import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import type { CacheTierName, Clock } from '@ultimat3/core';
+import { CACHE_TIERS, systemClock } from '@ultimat3/core';
 import { CacheJitterInvalidError, CacheTtlInvalidError } from './errors';
 import type { CacheFence } from './fence';
 import { markInvalidated, sampleFence } from './fence';
@@ -13,10 +13,17 @@ import { createSingleFlight } from './single-flight';
 import type { CacheTag } from './tags';
 import { bestEffort } from './tier-failures';
 
-export type TierName = 'request-memo' | 'lru' | 'redis' | 'cdn';
+/**
+ * The rungs, spelled in `@ultimat3/core` and nowhere else. Tier 0 owns the NAMES because
+ * `app.config.ts` names them too and core is the one place a tier-0 declaration and this package
+ * can both see; the ladder — order, promotion, fan-out — is still this file's. Aliased rather than
+ * re-exported under core's name so the ~30 call sites that already import `TierName` keep working:
+ * one declaration, two names, against one declaration each in two packages that disagreed.
+ */
+export type TierName = CacheTierName;
 
 /** Read order. Index in this array is the tier's distance from the request. */
-export const TIER_ORDER: readonly TierName[] = ['request-memo', 'lru', 'redis', 'cdn'];
+export const TIER_ORDER: readonly TierName[] = CACHE_TIERS;
 
 /**
  * Who a swallowed refusal is attributed to in `recentTierFailures()` and the `/_x` panel: every