@ultimat3/cache 2.0.0 → 3.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

package/package.json

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

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/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);