@ultimat3/cache 8.0.0 → 9.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` —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "8.0.0",
+  "version": "9.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": "9.0.0"
   }
 }

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