@ultimat3/cache 1.1.0 → 2.0.0

package/src/single-flight.ts

@@ -0,0 +1,78 @@
+// N concurrent misses on one key are ONE origin load. Without this a cache is an outage
+// amplifier: the write only lands after `load()` resolves, so every request that arrives inside
+// that window misses too and every one of them queries the origin. The share is per load and
+// never a second cache — the entry clears as it settles, rejection included.
+
+/**
+ * What a joiner contributes to the load it joined. Without one a joiner is a free rider: it takes
+ * the leader's value AND the leader's write, so anything it declared about that write is dropped.
+ */
+export interface FlightJoin<C> {
+  readonly context: C;
+  /** Folds a joiner in. Called synchronously as it arrives, so the leader sees it before it writes. */
+  readonly merge: (current: C, joining: C) => C;
+}
+
+/** Shares one in-flight `work()` per key. `@ultimat3/realtime`'s `entry.reading`, one tier down. */
+export interface SingleFlight {
+  /**
+   * `work` receives a reader for the merged context — read it LATE (after the load settles), or
+   * it answers with only what the leader brought.
+   */
+  run<T, C = undefined>(
+    key: string,
+    work: (shared: () => C | undefined) => Promise<T>,
+    join?: FlightJoin<C>,
+  ): Promise<T>;
+  /** In-flight loads right now. A number that does not fall back to `0` is a leak. */
+  readonly size: number;
+}
+
+/** The leader's promise, plus the box its merged context lives in — one identity for both. */
+interface Flight {
+  readonly running: Promise<unknown>;
+  readonly shared: { context: unknown };
+}
+
+export function createSingleFlight(): SingleFlight {
+  const inflight = new Map<string, Flight>();
+
+  return {
+    get size(): number {
+      return inflight.size;
+    },
+
+    run<T, C = undefined>(
+      key: string,
+      work: (shared: () => C | undefined) => Promise<T>,
+      join?: FlightJoin<C>,
+    ): Promise<T> {
+      const joined = inflight.get(key);
+      // Two readers of one key asking for two different `T` is an app bug the cache cannot see;
+      // the value they share is the same object either way, so the cast is the honest one.
+      if (joined !== undefined) {
+        if (join !== undefined) {
+          joined.shared.context = join.merge(joined.shared.context as C, join.context);
+        }
+        return joined.running as Promise<T>;
+      }
+
+      const shared: { context: unknown } = { context: join?.context };
+      // Wrapped so a `work()` that throws SYNCHRONOUSLY still rejects the joiners rather than
+      // escaping past the map and leaving no entry to clear.
+      const running: Promise<T> = (async () => await work(() => shared.context as C | undefined))();
+      const entry: Flight = { running, shared };
+      inflight.set(key, entry);
+
+      const settled = (): void => {
+        // Only the leader clears its own entry: a load started after this one settled must not be
+        // dropped by a late callback from the load it replaced.
+        if (inflight.get(key) === entry) inflight.delete(key);
+      };
+      // A rejected load MUST clear too, or one failure is cached as a permanent rejection.
+      void running.then(settled, settled);
+
+      return running;
+    },
+  };
+}

package/src/tags.ts

@@ -54,6 +54,26 @@ export function serializeTags(tags: readonly CacheTag[]): string[] {
   return tags.map(serializeTag);
 }
 
+/**
+ * The wire forms as an IDENTITY: sorted and de-duplicated, so two declaration orders of one tag
+ * set are one string. `@ultimat3/action`'s descriptor and OpenAPI `invalidates`, and
+ * `@ultimat3/query`'s `cacheKeyFor`, are built from it — a key that varied with declaration order
+ * would fill two entries for one read, and an action's `invalidates` would drop whichever of them
+ * it happened to name.
+ *
+ * It lives here rather than in either of those packages, which held byte-identical copies of it:
+ * both are tier 3, so neither can import the other and a copy in either is a second answer for the
+ * other. The same move `toBucket` made into `@ultimat3/http`.
+ *
+ * NOT the same function as `@ultimat3/render`'s same-named `tagKeys`, which is `serializeTags`
+ * over an optional list and deliberately preserves declaration order for a route descriptor
+ * (`dsl.test.ts` pins it). Two behaviours under one name, in two packages an app imports together:
+ * naming it here is where a reader can see both.
+ */
+export function tagKeys(tags: readonly CacheTag[]): readonly string[] {
+  return [...new Set(serializeTags(tags))].sort();
+}
+
 /**
  * Every tag a row participates in: its collection and its own identity. A row write
  * therefore busts list caches and detail caches with one call.
@@ -95,6 +115,31 @@ export function resetDeclaredTags(): void {
   declared.clear();
 }
 
+/**
+ * Test seam, and the one `resetDeclaredTags()` cannot be: `declareTags` is additive and
+ * process-wide, so a suite that declares a fixture entity flips `assertKnownTags` on for every
+ * LATER file in the same `bun test` process — and those files fail with X_CACHE_TAG_UNKNOWN for a
+ * reason nothing in them explains. Resetting instead would drop what a neighbour declared, so this
+ * puts back exactly what it found:
+ *
+ *   const restoreTags = isolateDeclaredTags();
+ *   afterAll(restoreTags);
+ *
+ * This is the shape every process-global registry in this package is undone with — `isolateGraph()`
+ * in `graph.ts`, `isolateTiers()` in `invalidate.ts`, `isolateTierFailures()` in
+ * `tier-failures.ts` — and one reason covers all four: `@ultimat3/testing`'s leak guard compares
+ * its before/after samples for ADDITIONS only, so a file that DELETES what a neighbour registered
+ * is invisible to it and surfaces instead as a failure in an innocent file with nothing in it to
+ * explain the missing state. A reset in a test file is the one leak no mechanism catches for you.
+ */
+export function isolateDeclaredTags(): () => void {
+  const captured = knownTags();
+  return () => {
+    declared.clear();
+    for (const name of captured) declared.add(name);
+  };
+}
+
 /**
  * Validation is skipped while nothing is declared — `x dev` boots before the manifest
  * exists, and a hard failure there would be worse than a late one. Once any entity has

package/src/tier-failures.ts

@@ -0,0 +1,92 @@
+// A cache tier is best-effort infrastructure: a refusal must never reach the caller of a
+// business read or write, the same rule `invalidateTags` already keeps. `read()` has no report
+// 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 type { TierLabel } from './tiers';
+
+/** The three tier calls a stack makes on the value path. `invalidateTags` reports its own. */
+export type TierOperation = 'get' | 'set' | 'del';
+
+export interface TierFailure {
+  /** ISO-8601, from core's `systemClock` — never `new Date()`. */
+  readonly at: string;
+  readonly tier: TierLabel;
+  readonly op: TierOperation;
+  readonly key: string;
+  /** The `X_*` code when the tier threw an `UltimateError`; absent for anything else. */
+  readonly code?: string;
+  readonly message: string;
+}
+
+// A dev log, not an audit trail — capped so a long-lived process cannot grow it forever.
+const MAX_TIER_FAILURES = 100;
+
+/** Newest first. Module-private; read it through `recentTierFailures()`. */
+const failureLog: TierFailure[] = [];
+
+/** What a "is the cache degraded?" question reads: newest first, capped, a copy of the log. */
+export function recentTierFailures(): readonly TierFailure[] {
+  return [...failureLog];
+}
+
+/** Test seam, and `resetTiers()`'s: drops every recorded failure. */
+export function resetTierFailures(): void {
+  failureLog.length = 0;
+}
+
+/**
+ * `isolateDeclaredTags()`'s contract over this log — `tags.ts` carries the why. It lives here
+ * rather than in a test file because the log has a reader and no writer: from outside this module
+ * the entries `resetTierFailures()` drops cannot be put back at all.
+ *
+ *   const restoreFailures = isolateTierFailures();
+ *   afterAll(restoreFailures);
+ */
+export function isolateTierFailures(): () => void {
+  const captured = [...failureLog];
+  return () => {
+    failureLog.length = 0;
+    failureLog.push(...captured);
+  };
+}
+
+/**
+ * Runs one tier call and absorbs its refusal. `undefined` back means the tier declined, which a
+ * `get` already reads as a miss and a `set`/`del` as "that tier is unchanged" — so the caller
+ * needs no branch. The entry a tier refused to hold expires by TTL, exactly as one an
+ * `invalidateTags` failure left behind does.
+ *
+ * Public, and the only sanctioned way to swallow a cache refusal: a store outside this package
+ * (`@ultimat3/query`'s read cache) that wrapped its own `try/catch` would degrade invisibly, and
+ * a second failure log nobody reads is what this one exists to prevent. Pass the store's
+ * `TierLabel` — it is closed for that reason.
+ */
+export async function bestEffort<T>(
+  tier: TierLabel,
+  op: TierOperation,
+  key: string,
+  run: () => Promise<T>,
+): Promise<T | undefined> {
+  try {
+    return await run();
+  } catch (error) {
+    record(tier, op, key, error);
+    return undefined;
+  }
+}
+
+function record(tier: TierLabel, op: TierOperation, key: string, error: unknown): void {
+  const failure: TierFailure = {
+    at: systemClock.now().toISOString(),
+    tier,
+    op,
+    key,
+    ...(error instanceof UltimateError ? { code: error.code } : {}),
+    message: error instanceof Error ? error.message : String(error),
+  };
+  failureLog.unshift(failure);
+  failureLog.length = Math.min(failureLog.length, MAX_TIER_FAILURES);
+  logger.warn('cache.tier.failed', { ...failure });
+}

package/src/tiers.ts

@@ -4,13 +4,54 @@
 // sites. Order is data, not control flow.
 
 import type { Clock } from '@ultimat3/core';
+import { 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 { createSingleFlight } from './single-flight';
 import type { CacheTag } from './tags';
+import { bestEffort } from './tier-failures';
 
 export type TierName = 'request-memo' | 'lru' | 'redis' | 'cdn';
 
 /** 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'];
 
+/**
+ * Who a swallowed refusal is attributed to in `recentTierFailures()` and the `/_x` panel: every
+ * rung of the ladder, plus a store that degrades the same way without being on it.
+ *
+ * Closed rather than a free-form string, and NOT a widening of `TierName`: `TIER_ORDER` is the
+ * ladder and a name missing from it sorts to `-1`, ahead of the request memo. A label is a log
+ * facet; a `TierName` is a position. Two spellings of one store is a panel nobody can group.
+ *
+ * **`'query-read'` emits nothing as of 2026-08** and is kept only because narrowing a shipped
+ * exported union breaks any caller that passes it to `bestEffort`. It named `@ultimat3/query`'s
+ * private read cache, which was a store in no registry — so `invalidateTags` could not reach it,
+ * which is exactly why that store is gone and a `cache:` read now fills these tiers. A refusal on
+ * that path is attributed to the tier that actually refused. Do not add a second such member: a
+ * cache worth a label is a cache worth registering.
+ */
+export type TierLabel = TierName | 'query-read';
+
+/** Injected so a jittered TTL is deterministic in a test. Never `Math.random()` at a call site. */
+export type Rng = () => number;
+
+/**
+ * 5%: enough to smear a warm-up herd across the tail of its lease, small enough that a 60s cache
+ * is never mistaken for a 54s one. Higher is a correctness question for the app, not the tier.
+ */
+export const DEFAULT_TTL_JITTER_FRACTION = 0.05;
+
+/** How a tier spreads its TTLs. Every tier takes it; `assertTtl` is the one place it is applied. */
+export interface TtlJitter {
+  /** Fraction of the lease that may be shaved off, in `[0, 1)`. `0` disables it. */
+  readonly jitterFraction?: number;
+  /** `() => 0` is "the full lease, this write" — the deterministic setting a test wants. */
+  readonly rng?: Rng;
+}
+
 export interface CacheEntry<T> {
   readonly value: T;
   /** Epoch ms; `undefined` means no expiry. */
@@ -19,10 +60,58 @@ export interface CacheEntry<T> {
 }
 
 export interface CacheSetOptions {
+  /**
+   * Lifetime in milliseconds. **Positive and finite, always** — omit it for the tier's default.
+   * There is no "never expires" and no "do not cache": both used to be spellings of `0` that the
+   * LRU and Redis tiers read differently, so every tier now refuses it (`X_CACHE_TTL_INVALID`).
+   */
   readonly ttlMs?: number;
+  /**
+   * Lifetime for a `null`/`undefined` load, when it should differ from `ttlMs`. A lookup for a
+   * row that has not replicated yet answers `null` 40ms before it lands; holding that for the
+   * positive TTL serves "does not exist" for five minutes. Omitted means "same as `ttlMs`",
+   * which is the accident this field makes a decision.
+   */
+  readonly negativeTtlMs?: number;
   readonly tags?: readonly CacheTag[];
 }
 
+/**
+ * The one TTL rule, applied by every tier before it writes: validate, then spread. It lives here
+ * rather than in each tier because two tiers disagreeing about what `0` means is exactly the bug
+ * this replaced — and jitter belongs at the same choke point for the same reason.
+ *
+ * Jitter is not a nicety. A rolling restart warms 40,000 keys inside 30 seconds and hands every
+ * one of them the same 300s lease; five minutes later all 40,000 expire inside the same 30-second
+ * window, and with single-flight sharing only the loads that overlap that is still 40,000 origin
+ * reads. Shaving a random slice off each lease is what turns one cliff into a ramp.
+ */
+/**
+ * Where a lease is being spent. Every tier — plus `'semantic'`, which is not a tier and still may
+ * not invent its own reading of `ttlMs: 0`.
+ */
+export type TtlScope = TierName | 'semantic';
+
+export function assertTtl(
+  key: string,
+  ttlMs: number,
+  tier: TtlScope,
+  jitter: TtlJitter = {},
+): number {
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    throw new CacheTtlInvalidError({ key, ttlMs, tier });
+  }
+  const fraction = jitter.jitterFraction ?? DEFAULT_TTL_JITTER_FRACTION;
+  if (!Number.isFinite(fraction) || fraction < 0 || fraction >= 1) {
+    throw new CacheJitterInvalidError({ tier, jitterFraction: fraction });
+  }
+  if (fraction === 0) return ttlMs;
+  // Clamped rather than trusted: an `rng` outside [0, 1) would EXTEND the lease past what the
+  // caller asked for, which is a stale read no reader can explain.
+  const roll = Math.min(1, Math.max(0, (jitter.rng ?? Math.random)()));
+  return Math.max(1, Math.round(ttlMs * (1 - fraction * roll)));
+}
+
 /** Per-tier result of an invalidation, surfaced verbatim in the `/_x` cache panel. */
 export interface TierInvalidation {
   readonly tier: TierName;
@@ -65,36 +154,149 @@ export function sortTiers(tiers: readonly CacheTier[]): readonly CacheTier[] {
   return [...tiers].sort((a, b) => TIER_ORDER.indexOf(a.name) - TIER_ORDER.indexOf(b.name));
 }
 
-export function createCacheStack(tiers: readonly CacheTier[]): CacheStack {
+/**
+ * Every tier call here goes through `bestEffort`: a tier that refuses is a tier that did not
+ * answer, never a failed business read. `load()` is the one call left unguarded — it *is* the
+ * business read, and swallowing it would return `undefined` as if it were the value.
+ */
+export interface CacheStackOptions {
+  /** Read through `nowMs()`; the same clock a tier takes. Defaults to `systemClock`. */
+  readonly clock?: Clock;
+}
+
+export function createCacheStack(
+  tiers: readonly CacheTier[],
+  options: CacheStackOptions = {},
+): CacheStack {
   const ordered = sortTiers(tiers);
+  const clock = options.clock ?? systemClock;
+  // Per stack, not per module: two stacks are two ladders and must not join each other's loads.
+  const flight = createSingleFlight();
 
-  return {
-    tiers: ordered,
+  /** Take back what a fence refused mid-ladder: half a stale ladder is still a stale read. */
+  const rollback = async (written: readonly CacheTier[], key: string): Promise<void> => {
+    for (const tier of [...written].reverse()) {
+      await bestEffort(tier.name, 'del', key, () => tier.del(key));
+    }
+  };
+
+  /**
+   * `fence` is what stops a fill from republishing what an invalidation just cleared: the value
+   * was read by a `load()` that started before the bust, so writing it now hides that write from
+   * every reader for the whole TTL — and the invalidation reported `errors: []` while doing it.
+   * Re-checked per tier rather than once, because the ladder is several awaits long.
+   */
+  const fill = async <T>(
+    key: string,
+    value: T,
+    setOptions?: CacheSetOptions,
+    fence?: CacheFence,
+  ): Promise<void> => {
+    const resolved = ttlOptionsFor(value, setOptions);
+    const written: CacheTier[] = [];
+    for (const tier of ordered) {
+      if (fence !== undefined && !fence.isValid()) {
+        await rollback(written, key);
+        return;
+      }
+      await bestEffort(tier.name, 'set', key, () => tier.set(key, value, resolved));
+      written.push(tier);
+    }
+  };
 
-    async read<T>(key: string, load: () => Promise<T>, options?: CacheSetOptions): Promise<T> {
-      for (let i = 0; i < ordered.length; i += 1) {
-        const tier = ordered[i];
-        if (tier === undefined) continue;
-        const hit = await tier.get<T>(key);
-        if (hit === undefined) continue;
-        // Populate every tier we walked past, closest-first on the next read.
-        for (let up = 0; up < i; up += 1) {
-          await ordered[up]?.set(key, hit.value, { ...options, tags: hit.tags });
+  /** Walks down, promoting into every tier it passed. `undefined` means every tier missed. */
+  const lookup = async <T>(
+    key: string,
+    setOptions?: CacheSetOptions,
+  ): Promise<CacheEntry<T> | undefined> => {
+    // A promotion is a write too. The ladder is one await per rung, so a bust can finish between
+    // the far `get` and the near `set` — which promotes a value out of a tier nothing has cleared
+    // yet into one that was cleared a millisecond ago. Fan-out order makes that window small; the
+    // fence is what makes crossing it not matter.
+    const fence = sampleFence({ key });
+    for (let i = 0; i < ordered.length; i += 1) {
+      const tier = ordered[i];
+      if (tier === undefined) continue;
+      const hit = await bestEffort(tier.name, 'get', key, () => tier.get<T>(key));
+      if (hit === undefined) continue;
+      const now = nowMs(clock);
+      // A tier may answer with an entry it has not reaped yet; expiry is decided here, once,
+      // by the predicate this module already exported and nothing had ever called.
+      if (isExpired(hit, now)) continue;
+      // Populate every tier we walked past, closest-first on the next read — carrying the
+      // entry's REMAINING life, never the caller's original ttlMs. Re-leasing a value one
+      // second from expiry for a fresh five minutes on every read is a hot key that never
+      // goes stale enough to be refetched.
+      const promoted: CacheSetOptions = {
+        ...setOptions,
+        tags: hit.tags,
+        ...(hit.expiresAt === undefined ? {} : { ttlMs: hit.expiresAt - now }),
+      };
+      fence.cover({ tags: hit.tags });
+      const promotedInto: CacheTier[] = [];
+      for (let up = 0; up < i; up += 1) {
+        const closer = ordered[up];
+        if (closer === undefined) continue;
+        if (!fence.isValid()) {
+          await rollback(promotedInto, key);
+          break;
         }
-        return hit.value;
+        await bestEffort(closer.name, 'set', key, () => closer.set(key, hit.value, promoted));
+        promotedInto.push(closer);
       }
+      // Returned either way: this IS what a tier held when it was asked, and a fence never fails
+      // a business read — it only declines to publish.
+      return hit;
+    }
+    return undefined;
+  };
+
+  return {
+    tiers: ordered,
 
-      const value = await load();
-      for (const tier of ordered) await tier.set(key, value, options);
-      return value;
+    async read<T>(key: string, load: () => Promise<T>, setOptions?: CacheSetOptions): Promise<T> {
+      const hit = await lookup<T>(key, setOptions);
+      if (hit !== undefined) return hit.value;
+
+      // The stampede guard. The homepage feed read 8,000x/s with a 60s lease misses for the whole
+      // ~200ms `load()` takes, so ~1,600 identical queries reach Postgres at every TTL boundary
+      // unless the arrivals inside that window join the read already running.
+      return await flight.run<T, CacheSetOptions>(
+        key,
+        async (shared) => {
+          // Sampled BEFORE `load()` — everything after this instant is a write this value has
+          // not seen, and a fill that ignored it would hide that write for the whole TTL.
+          const fence = sampleFence({
+            key,
+            ...(setOptions?.tags === undefined ? {} : { tags: setOptions.tags }),
+          });
+          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 merged = shared() ?? setOptions;
+          if (merged?.tags !== undefined) fence.cover({ tags: merged.tags });
+          await fill(key, value, merged, fence);
+          return value;
+        },
+        { context: setOptions ?? {}, merge: mergeSetOptions },
+      );
     },
 
-    async write<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {
-      for (const tier of ordered) await tier.set(key, value, options);
+    write<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {
+      // An explicit write is newer truth than any load already in flight for this key, so it
+      // fences those fills off before it starts rather than losing a race with one.
+      markInvalidated({ key });
+      return fill(key, value, options);
     },
 
     async drop(key: string): Promise<void> {
-      for (const tier of ordered) await tier.del(key);
+      markInvalidated({ key });
+      // Farthest tier first, for the reason `invalidateTags` fans out that way: clearing the near
+      // tiers first leaves a window where a racing read finds the far tier still holding the old
+      // value and promotes it back up, into tiers this call has already cleared.
+      for (const tier of [...ordered].reverse()) {
+        await bestEffort(tier.name, 'del', key, () => tier.del(key));
+      }
     },
   };
 }