@ultimat3/cache 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -34,15 +34,27 @@ 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` —
   `TierName` plus `'query-read'` — closed, and deliberately NOT a widening of `TierName`: a name
   missing from `TIER_ORDER` sorts to `-1`, ahead of the request memo. A label is a log facet; a
   `TierName` is a position on the ladder.
-- **A refusal is rendered with `renderThrowable()`, never `error.message`** — the four sites that
-  absorb one (`bestEffort`'s log entry, and `fanOut`'s tier, ISR and broadcast catch blocks). A
-  tier, a revalidator and a broadcast are all app-supplied, so the value they reject with is too:
+- **A refusal is rendered with `renderThrowable()`, never `error.message`** — the five sites that
+  absorb one (`bestEffort`'s log entry, `fanOut`'s tier, ISR and broadcast catch blocks, and
+  `purgePost`'s transport catch). A tier, a revalidator, a broadcast and the `fetch` a purge driver
+  is given are all app-supplied, so the value they reject with is too:
   `instanceof` runs a `Proxy`'s `getPrototypeOf` trap and `String()` runs `Symbol.toPrimitive`, so
   building the log line used to raise INSTEAD of absorbing the refusal — on the business write that
   triggered the bust, which is the one caller both contracts promise to protect. The code field
@@ -131,7 +143,13 @@ Tier 1. Tagged caching + THE invalidation graph.
   carrying only the leader's tags: the joiner's tag reached nothing, so the invalidation it declared
   never fired. Tags union, TTLs take the SHORTEST — an entry held longer than a caller asked for is
   stale to that caller. `work` reads the merge through `shared()` **after** the load, or it sees
-  only what the leader brought.
+  only what the leader brought — and **once more after the fill**, because the flight stays open
+  for the whole ladder and a joiner merging a tag mid-fill hit the identical hole one rung later.
+  The second read re-fills EVERY tier rather than the rungs still to come: re-reading per tier
+  would land the near tier — the one every later read hits first — with the FEWEST tags, so an
+  invalidation would clear the far rungs and leave the near one serving. `tagsAddedSince` in
+  `set-options.ts` is what makes the second pass conditional; `tiers.test.ts`'s
+  `a single-flight joiner that arrives during the FILL` is what notices.
 - **`negativeTtlMs` is the stack's decision, not a tier's.** Only `createCacheStack` sees what
   `load()` answered, so the `null`/`undefined` branch lives in `ttlOptionsFor` there and reaches a
   tier as an ordinary `ttlMs`.

package/package.json

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

package/src/purge-http.ts

@@ -3,6 +3,7 @@
 // forces. Kept apart from the drivers because "which failure can succeed unchanged" is one
 // judgement, and two copies of it would drift into two answers for the same 429.
 
+import { renderThrowable } from '@ultimat3/core';
 import { CacheDriverUnavailableError, CachePurgeFailedError } from './errors';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
@@ -152,7 +153,11 @@ export async function purgePost(input: PurgePostInput): Promise<Response> {
       signal: AbortSignal.timeout(input.timeoutMs),
     });
   } catch (error) {
-    const reason = error instanceof Error ? error.message : 'the request failed before a response';
+    // `renderThrowable`, never `error.message` behind an `instanceof`: `fetch` is INJECTED here,
+    // so the rejection is whatever a driver or a test double threw — and `instanceof` itself
+    // throws on a `Proxy` whose `getPrototypeOf` does, which would replace the coded refusal this
+    // catch exists to raise with a bare `TypeError` from inside it. Same rule as `invalidate.ts`.
+    const reason = renderThrowable(error);
     throw new CachePurgeFailedError({
       driver: input.driver,
       detail: `${reason} — nothing left this host for ${input.url} (egress, DNS or TLS)`,

package/src/set-options.ts

@@ -63,3 +63,20 @@ export function mergeSetOptions(
     ...(negativeTtlMs === undefined ? {} : { negativeTtlMs }),
   };
 }
+
+/**
+ * Did `latest` gain a tag `written` does not carry?
+ *
+ * Compared on the wire form — the identity every tier indexes by and the one `mergeTags` above
+ * dedupes on — so "already written" means the same thing to both, and a re-fill is asked for
+ * exactly when a joiner brought something new.
+ */
+export function tagsAddedSince(
+  written: CacheSetOptions | undefined,
+  latest: CacheSetOptions | undefined,
+): boolean {
+  const added = latest?.tags;
+  if (added === undefined || added.length === 0) return false;
+  const seen = new Set((written?.tags ?? []).map(serializeTag));
+  return added.some((owned) => !seen.has(serializeTag(owned)));
+}

package/src/tiers.ts

@@ -3,20 +3,27 @@
 // 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';
-import { mergeSetOptions, ttlOptionsFor } from './set-options';
+import { mergeSetOptions, tagsAddedSince, ttlOptionsFor } from './set-options';
 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
@@ -255,6 +262,10 @@ export function createCacheStack(
     tiers: ordered,
 
     async read<T>(key: string, load: () => Promise<T>, setOptions?: CacheSetOptions): Promise<T> {
+      // Outside the flight on purpose, and the cost is known: N concurrent misses each walk the
+      // ladder before any of them joins, so a cold key pays N gets per rung. Moving it inside
+      // would serialise every HIT behind whichever caller happened to arrive first — the common
+      // case paying for the rare one. Carried as a Low; measure before changing it.
       const hit = await lookup<T>(key, setOptions);
       if (hit !== undefined) return hit.value;
 
@@ -273,9 +284,22 @@ export function createCacheStack(
           const value = await load();
           // Joiners merged their own tags into the load they shared; covering is retroactive, so
           // a tag that arrived mid-load is fenced back to the sample rather than from now.
+          const publish = async (options: CacheSetOptions | undefined): Promise<void> => {
+            if (options?.tags !== undefined) fence.cover({ tags: options.tags });
+            await fill(key, value, options, fence);
+          };
           const merged = shared() ?? setOptions;
-          if (merged?.tags !== undefined) fence.cover({ tags: merged.tags });
-          await fill(key, value, merged, fence);
+          await publish(merged);
+          // The flight stays open until this whole `work` settles, and `fill` is one await per
+          // rung — so a joiner can still merge a tag after the read above, and the entry that
+          // landed would carry the leader's tags alone, which `invalidateTags` can never reach.
+          // Re-read once and re-fill EVERY tier: re-reading per tier instead would land the near
+          // tier — the one every later read hits first — with the FEWEST tags, so an invalidation
+          // would clear the far rungs and leave the near one serving. A joiner arriving inside
+          // the second pass is left where a plain cache hit already leaves one: reading a value
+          // that was published without its tag.
+          const late = shared() ?? setOptions;
+          if (tagsAddedSince(merged, late)) await publish(late);
           return value;
         },
         { context: setOptions ?? {}, merge: mergeSetOptions },