@ultimat3/cache 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -40,6 +40,16 @@ Tier 1. Tagged caching + THE invalidation graph.
   `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:
+  `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
+  keeps its own total probe (`ultimateCode` in `tier-failures.ts`) rather than core's `stringField`:
+  a driver error's `code` is a SQLSTATE and must never be reported as an `X_*` one. Consequence to
+  know: a recorded `message` carries the throwable's NAME (`Error: nats is down`, `"just a string"`),
+  which is what `renderThrowable` renders and what the tests here now pin.
 - Tier failures go into `report.errors`. A cache tier may never fail a business read or write.
   `createCacheStack` routes every `get`/`set`/`del` through `bestEffort()` for that reason — a
   refusal becomes "that tier did not answer" and lands in `recentTierFailures()`, the read side's
@@ -147,6 +157,10 @@ Tier 1. Tagged caching + THE invalidation graph.
   change: a cold shared tier, which the default build-id namespace already pays per deploy.
   Pinned by `tier-parity.test.ts` (all three rungs, one test each) and `redis.live.test.ts` (the
   same two busts against a real server, asserting the LRU's and Redis's survivors are EQUAL).
+  **A row bust does not read the index and still SREMs from it** (`sweepBucketsFor`) — reading it
+  over-reaches, removing a member cannot: only what the bust deleted leaves. Without that, a
+  deleted value key kept its membership in `e:{entity}` for ever while every write renewed that
+  index's lease — the unbounded `SMEMBERS` the lease was added to prevent, rebuilt out of corpses.
 - **`CacheTier.set` REJECTS, never throws synchronously.** `createLruTier` and `createMemoTier` are
   `async` for that reason alone — `LruCache.set` stays a sync API, but a `CacheTier` is one
   interface with three implementations and `tier.set(...).catch(...)` has to mean the same thing on
@@ -202,6 +216,11 @@ Tier 1. Tagged caching + THE invalidation graph.
   options and only `receiveInvalidationBroadcast` passes `false`. An inbound tag this process never
   declared is dropped into `report.errors`, never thrown: a throw kills the subscriber loop and
   silently ends cross-instance invalidation for the whole process.
+- **A `cdn` tier holding `noopPurgeDriver()` reports `skipped`, never keys.** That is the default
+  state of every deployment with no CDN credentials (`selectPurgeDriver`), and the noop ECHOES the
+  keys it is handed — so the tier reported every tag as CLEARED and `busted` listed keys nothing
+  had purged, with `errors: []`. `isNoopPurgeDriver` lives in `cdn.ts`, beside the `name: 'noop'`
+  it tests for, because `createCdnTier` cannot import `purge-env.ts` without a cycle.
 - **`report.cdn` is what depends on the tags; `report.tiers` is what cleared.** The `cdn` tier
   purges `cdn-path` dependents itself, alongside the tags, so `busted` is built from `tiers` +
   `isr` + `liveQueries` and never from `cdn` — folding in a list nothing purged is exactly the

package/README.md

@@ -170,9 +170,12 @@ partial bust while stale rows served until TTL. Value keys are still deleted cli
 each, which is slot-local under every topology.
 
 The script **deletes nothing at all** — not the value keys, and not the buckets either. The tier
-`SREM`s exactly the members whose `DEL` succeeded, so a refused delete keeps its membership and the
-retry the error asks for still finds it; dropping the bucket inside the script made that failure
-permanent. A `set` mirrors it: buckets are joined **before** the value is written and membership is
+`SREM`s exactly the members whose `DEL` succeeded, from every bucket that member joined —
+including, for a row bust, the entity index it deliberately never *reads*. Reading `e:{entity}` for
+a row bust would return every key of the entity; removing from it cannot over-reach, and a member
+left there is a corpse in a set every later write renews the lease on. A refused delete keeps its
+membership and the retry the error asks for still finds it; dropping the bucket inside the script
+made that failure permanent. A `set` mirrors it: buckets are joined **before** the value is written and membership is
 re-checked after, because a bust that landed in between would otherwise leave a row nothing can
 reach by tag, serving until its own lease ran out.
 
@@ -319,6 +322,12 @@ nothing loads that file's contents at runtime:
 | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ZONE_ID` | Cloudflare |
 | neither | nothing is purged, and `x dev` prints `cdn=none` |
 
+A `cdn` tier holding the noop driver answers an invalidation with
+`{ tier: 'cdn', keys: [], skipped: 'no purge driver configured' }` — never a list of keys. The noop
+echoes what it is handed, so reporting its reply as accepted made every tag read as CLEARED in
+`report.tiers` and in `recentInvalidations().busted`, with `errors: []`, in the default state of a
+deployment that has no CDN at all. `isNoopPurgeDriver(driver)` is the same probe, exported.
+
 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

package/package.json

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

package/src/cdn.ts

@@ -66,6 +66,15 @@ export function noopPurgeDriver(): PurgeDriver {
   };
 }
 
+/**
+ * A driver that reaches no CDN, so a caller can report "purges nothing" without a name match.
+ *
+ * Lives here rather than beside `selectPurgeDriver`, which is where it was until 2026-08: the
+ * `name: 'noop'` it tests for is declared one function up, and `createCdnTier` — the caller that
+ * most needs it — cannot import from `purge-env.ts` without making a cycle of the two files.
+ */
+export const isNoopPurgeDriver = (driver: PurgeDriver): boolean => driver.name === 'noop';
+
 export interface CdnTierOptions {
   readonly purge?: PurgeDriver;
   /**
@@ -108,6 +117,13 @@ export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
      * `cdn-path` dependent must tag that response with its own path.
      */
     async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      // The default state of any deployment with no CDN credentials, and it has to say so: the
+      // noop driver ECHOES its argument, so every tag came back as an accepted purge and
+      // `recentInvalidations().busted` listed keys nothing had cleared, `errors: []`. `skipped`
+      // is the field that already exists for this — a tier that did not run, named as one.
+      if (isNoopPurgeDriver(driver)) {
+        return { tier: 'cdn', keys: [], skipped: 'no purge driver configured' };
+      }
       const keys = [...new Set([...serializeTags(tags), ...dependentsOfKind(tags, 'cdn-path')])];
       if (keys.length === 0) return { tier: 'cdn', keys: [] };
       const accepted = await driver.purge(keys);

package/src/index.ts

@@ -1,7 +1,7 @@
 // Public API of @ultimat3/cache. Explicit, no `export *`.
 
 export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
-export { cacheHeaders, createCdnTier, noopPurgeDriver } from './cdn';
+export { cacheHeaders, createCdnTier, isNoopPurgeDriver, noopPurgeDriver } from './cdn';
 export type { CacheErrorCode } from './errors';
 export {
   CACHE_ERROR_CODES,
@@ -55,7 +55,7 @@ export {
   cloudflarePurgeDriver,
 } from './purge-cloudflare';
 export type { PurgeEnvironment, PurgeSelection } from './purge-env';
-export { CDN_PURGE_ENV_KEYS, isNoopPurgeDriver, selectPurgeDriver } from './purge-env';
+export { CDN_PURGE_ENV_KEYS, 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';

package/src/invalidate.ts

@@ -4,7 +4,7 @@
 // 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 { currentSpan, logger, renderThrowable, systemClock, withSpan } from '@ultimat3/core';
 import { markInvalidated } from './fence';
 import { dependentsOfKind } from './graph';
 import type { CacheTag } from './tags';
@@ -222,10 +222,11 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva
       try {
         tiers.push(await tier.invalidateTags(tags));
       } catch (error) {
-        errors.push({
-          tier: tier.name,
-          message: error instanceof Error ? error.message : String(error),
-        });
+        // `renderThrowable`, never `error.message`: a tier is app-supplied, so the value it
+        // rejects with is too, and both `instanceof` and `String()` RUN app code on it. A render
+        // that throws here rejects the whole fan-out — the failure the line above promises not to
+        // let reach the write that triggered the bust.
+        errors.push({ tier: tier.name, message: renderThrowable(error) });
       }
     }
     // The report is read order, not clear order: it is what the `/_x` panel renders, and a ladder
@@ -240,10 +241,7 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva
       try {
         await revalidator?.(path);
       } catch (error) {
-        errors.push({
-          tier: 'isr',
-          message: error instanceof Error ? error.message : String(error),
-        });
+        errors.push({ tier: 'isr', message: renderThrowable(error) });
       }
     }
 
@@ -255,10 +253,7 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva
       try {
         await broadcast(wire);
       } catch (error) {
-        errors.push({
-          tier: 'broadcast',
-          message: error instanceof Error ? error.message : String(error),
-        });
+        errors.push({ tier: 'broadcast', message: renderThrowable(error) });
       }
     }
 

package/src/purge-env.ts

@@ -41,9 +41,6 @@ const nonEmpty = (value: string | undefined): string | undefined =>
 const configuredKeys = (env: PurgeEnvironment): readonly string[] =>
   CDN_PURGE_ENV_KEYS.filter((key) => nonEmpty(env[key]) !== undefined);
 
-/** A driver that reaches no CDN, so a caller can report "purges nothing" without a name match. */
-export const isNoopPurgeDriver = (driver: PurgeDriver): boolean => driver.name === 'noop';
-
 /**
  * Either key selects its provider, and the other is then required: a `FASTLY_SERVICE_ID` with no
  * token is a half-finished deploy, and treating it as "no CDN" is how an environment ships

package/src/redis.ts

@@ -239,6 +239,19 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       ? [entityKey(owned.entity), tagKey(owned)]
       : [tagKey(owned), tagKey({ entity: owned.entity })];
 
+  /**
+   * The buckets a bust CLEANS UP, which is not the set it reads — and the asymmetry is the point.
+   *
+   * A row bust must not READ the entity index: it holds every key of the entity, so the bust would
+   * delete them all. It must still SREM from it. `set` joins the index on every write, so a row
+   * bust that deletes a value key and leaves its membership there leaves a corpse no later bust
+   * can reach — while `TAG_MEMBER_SCRIPT` renews that index's lease on every write, which is the
+   * unbounded `SMEMBERS` the lease exists to prevent, rebuilt out of dead keys. Removing a member
+   * cannot over-reach the way reading one can: only what this bust actually deleted leaves.
+   */
+  const sweepBucketsFor = (owned: CacheTag): string[] =>
+    owned.id === undefined ? [] : [entityKey(owned.entity)];
+
   return {
     name: 'redis',
 
@@ -330,18 +343,18 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
      */
     async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
       const claimed = new Set<string>();
-      const perTag: string[][] = [];
+      const perTag: { read: string[]; sweep: string[] }[] = [];
       for (const owned of tags) {
         // A bucket already claimed by an earlier tag is dropped rather than re-sent: a collection
         // tag and one of its rows overlap, and the second call would read the same members.
-        const buckets = bustBucketsFor(owned).filter((bucket) => !claimed.has(bucket));
-        for (const bucket of buckets) claimed.add(bucket);
-        if (buckets.length > 0) perTag.push(buckets);
+        const read = bustBucketsFor(owned).filter((bucket) => !claimed.has(bucket));
+        for (const bucket of read) claimed.add(bucket);
+        if (read.length > 0) perTag.push({ read, sweep: [...read, ...sweepBucketsFor(owned)] });
       }
       if (perTag.length === 0) return { tier: 'redis', keys: [] };
       const replies = await Promise.all(
-        perTag.map((buckets) =>
-          conn().send('EVAL', [INVALIDATE_SCRIPT, String(buckets.length), ...buckets]),
+        perTag.map(({ read }) =>
+          conn().send('EVAL', [INVALIDATE_SCRIPT, String(read.length), ...read]),
         ),
       );
       // A member may sit in two tag sets; deleting it twice is harmless but reporting it twice
@@ -369,7 +382,7 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       // drops the bucket, which is what made that failure permanent.
       for (let i = 0; i < perTag.length; i += 1) {
         const gone = [...new Set(toStrings(replies[i]))].filter((member) => deleted.has(member));
-        for (const bucket of perTag[i] ?? []) {
+        for (const bucket of perTag[i]?.sweep ?? []) {
           for (let start = 0; start < gone.length; start += DELETE_BATCH) {
             await conn().send('SREM', [bucket, ...gone.slice(start, start + DELETE_BATCH)]);
           }

package/src/tier-failures.ts

@@ -3,7 +3,7 @@
 // to return, so every swallowed refusal lands in one bounded log plus one `warn` — a stack
 // running degraded stays answerable instead of merely looking slow.
 
-import { logger, systemClock, UltimateError } from '@ultimat3/core';
+import { logger, renderThrowable, systemClock, UltimateError } from '@ultimat3/core';
 import type { TierLabel } from './tiers';
 
 /** The three tier calls a stack makes on the value path. `invalidateTags` reports its own. */
@@ -77,14 +77,35 @@ export async function bestEffort<T>(
   }
 }
 
+/**
+ * The `X_*` code when the tier threw an `UltimateError`, and `undefined` for every other answer —
+ * "the probe itself threw" included. `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap and the
+ * read past it is a getter call, both on a value this package did not build; the one place the
+ * question is asked is the catch block absorbing a refusal, which has nothing left to answer with
+ * if asking it raises. Core's `isThrownError` is this guard for `Error` and `stringField` is it for
+ * a loose field — neither fits here, because a driver error's `code` is a SQLSTATE and must never
+ * be reported as an `X_*` one.
+ */
+function ultimateCode(error: unknown): string | undefined {
+  try {
+    if (!(error instanceof UltimateError)) return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function record(tier: TierLabel, op: TierOperation, key: string, error: unknown): void {
+  const code = ultimateCode(error);
   const failure: TierFailure = {
     at: systemClock.now().toISOString(),
     tier,
     op,
     key,
-    ...(error instanceof UltimateError ? { code: error.code } : {}),
-    message: error instanceof Error ? error.message : String(error),
+    ...(code === undefined ? {} : { code }),
+    // Never `error.message`: a rendering that throws replaces the absorbed refusal with a
+    // `TypeError` on the business read this function exists to keep alive.
+    message: renderThrowable(error),
   };
   failureLog.unshift(failure);
   failureLog.length = Math.min(failureLog.length, MAX_TIER_FAILURES);