@ultimat3/cache 1.2.0 → 3.0.0

package/src/errors.ts

@@ -5,9 +5,11 @@ import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 /** Codes this package declares and owns. */
 export const CACHE_OWNED_ERROR_CODES = [
   'X_CACHE_DRIVER_UNAVAILABLE',
+  'X_CACHE_JITTER_INVALID',
   'X_CACHE_PURGE_FAILED',
   'X_CACHE_TAG_UNKNOWN',
   'X_CACHE_TOO_LARGE',
+  'X_CACHE_TTL_INVALID',
 ] as const;
 
 /** Every code cache can throw. It borrows none: every remote driver here is implemented. */
@@ -18,9 +20,11 @@ export type CacheErrorCode = (typeof CACHE_ERROR_CODES)[number];
 
 export const CACHE_ERROR_TITLES: Readonly<Record<CacheOwnedErrorCode, string>> = {
   X_CACHE_DRIVER_UNAVAILABLE: "a tier's backing store is missing",
+  X_CACHE_JITTER_INVALID: 'a TTL jitter fraction outside [0, 1)',
   X_CACHE_PURGE_FAILED: 'the CDN refused a purge',
   X_CACHE_TAG_UNKNOWN: 'a tag no entity declared',
   X_CACHE_TOO_LARGE: "one entry exceeds the tier's byte budget",
+  X_CACHE_TTL_INVALID: 'a cache TTL that is not a positive number of milliseconds',
 };
 
 // One unconditional call, so a second package claiming one of cache's codes throws
@@ -72,6 +76,52 @@ export class CacheTooLargeError extends UltimateError {
   }
 }
 
+/**
+ * A `ttlMs` that is not a positive, finite number of milliseconds.
+ *
+ * `0` used to mean two things: "never expires" in the LRU tier and `EX 1` — one second — in the
+ * Redis tier, so a stack holding both answered differently depending on which one hit. Neither is
+ * what a caller writing `0` intends, and the third reading ("do not cache") has its own spelling:
+ * do not call the cache. Refused rather than resolved, so the miswiring is a failure and not a
+ * behaviour that varies by deployment.
+ */
+export class CacheTtlInvalidError extends UltimateError {
+  constructor(input: { key: string; ttlMs: number; tier: string }) {
+    super({
+      code: 'X_CACHE_TTL_INVALID',
+      cause: `entry "${input.key}" was written to the ${input.tier} tier with ttlMs=${String(
+        input.ttlMs,
+      )}; a TTL is a positive, finite number of milliseconds`,
+      fix: `cache.write('${input.key}', value, { ttlMs: 60_000 })   # or drop the option for the tier default; a value you do not want held is one you do not write`,
+      docs: docsFor('X_CACHE_TTL_INVALID'),
+      meta: { key: input.key, ttlMs: input.ttlMs, tier: input.tier },
+    });
+  }
+}
+
+/**
+ * A jitter fraction a tier cannot spread a TTL with.
+ *
+ * Jitter exists because 40,000 keys warmed by one rolling restart share one TTL and therefore one
+ * expiry instant; spreading them is the only thing that stops the herd. A fraction of `1` or more
+ * would shave a whole lease away and a negative one would EXTEND it past what the caller asked
+ * for, so both are miswiring rather than a preference — refused where the TTL rule already lives,
+ * for the same reason `0` is not silently reinterpreted as "never expires".
+ */
+export class CacheJitterInvalidError extends UltimateError {
+  constructor(input: { tier: string; jitterFraction: number }) {
+    super({
+      code: 'X_CACHE_JITTER_INVALID',
+      cause: `the ${input.tier} tier was configured with jitterFraction=${String(
+        input.jitterFraction,
+      )}; a jitter fraction is a finite number in [0, 1)`,
+      fix: `set cache.${input.tier}.jitterFraction in app.config.ts to a value in [0, 1) — 0.05 is the default, 0 disables jitter`,
+      docs: docsFor('X_CACHE_JITTER_INVALID'),
+      meta: { tier: input.tier, jitterFraction: input.jitterFraction },
+    });
+  }
+}
+
 /**
  * A remote purge did not happen. Never fatal on its own — `invalidateTags` collects it into
  * `report.errors` so a dead CDN cannot fail the write that triggered the bust — which is exactly

package/src/fence.ts

@@ -0,0 +1,110 @@
+// A read-through fill writes what `load()` read, and `load()` read it in the past. An
+// invalidation that lands in between finds nothing to clear and the fill then republishes the
+// pre-write rows for a full TTL — invisibly, with `errors: []`. The fence is the identity check
+// `single-flight.ts` does on a promise, done on time: sample before the load, ask before the write.
+
+import type { CacheTag } from './tags';
+import { tagMatches } from './tags';
+
+/**
+ * What a fill is about to publish, in invalidation terms. Both halves are optional and both are
+ * checked: `key` catches a `drop`/`write` of that exact key, `tags` catch a tag bust.
+ */
+export interface FenceScope {
+  readonly key?: string;
+  readonly tags?: readonly CacheTag[];
+}
+
+export interface CacheFence {
+  /** `false` once anything this fence covers was invalidated after the sample. Never throws. */
+  isValid(): boolean;
+  /**
+   * Widen what this fence covers — retroactively, back to the sample. A joiner arriving mid-load
+   * declares tags the leader never sampled, and those tags are unfenced for exactly the window
+   * they were absent unless covering reaches back.
+   */
+  cover(scope: FenceScope): void;
+}
+
+/**
+ * How many recent invalidations stay inspectable. A fill window is milliseconds and this is
+ * process-wide, so the ring is only ever short of an answer under a bust storm — where the
+ * conservative answer costs one refetch and the optimistic one serves a stale row until TTL.
+ */
+export const FENCE_MEMORY = 1024;
+
+interface Mark {
+  /** The generation this mark was recorded at; marks are pushed in generation order. */
+  readonly at: number;
+  readonly key?: string;
+  readonly tag?: CacheTag;
+}
+
+const marks: Mark[] = [];
+let generation = 0;
+/** The highest generation the ring has forgotten. A fence older than this cannot be proven. */
+let forgottenThrough = 0;
+
+/**
+ * Record an invalidation. `invalidateTags` already calls this for every fan-out, inbound
+ * broadcasts included, and `CacheStack` calls it for `drop`/`write` — a caller only needs it when
+ * it clears a cache key by some path of its own.
+ *
+ * Unlike every other process-global registry in this package this one needs no `isolate*()` seam
+ * and has no reset: a fence samples the CURRENT generation, which is always at or above
+ * `forgottenThrough`, so marks left behind by another test file can never invalidate a fence
+ * sampled after them.
+ */
+export function markInvalidated(scope: FenceScope): void {
+  const key = scope.key;
+  const tags = scope.tags ?? [];
+  if (key === undefined && tags.length === 0) return;
+
+  generation += 1;
+  if (key !== undefined) marks.push({ at: generation, key });
+  for (const owned of tags) marks.push({ at: generation, tag: owned });
+
+  while (marks.length > FENCE_MEMORY) {
+    const dropped = marks.shift();
+    if (dropped !== undefined) forgottenThrough = dropped.at;
+  }
+}
+
+function hits(mark: Mark, scope: FenceScope): boolean {
+  if (mark.key !== undefined) return scope.key !== undefined && mark.key === scope.key;
+  const owned = mark.tag;
+  if (owned === undefined) return false;
+  // `tagMatches` is symmetric on the wildcard: a collection bust hits a row fence and a row bust
+  // hits a collection fence, which is the same asymmetry-tolerance every tier invalidates with.
+  return (scope.tags ?? []).some((wanted) => tagMatches(wanted, owned));
+}
+
+/**
+ * Take a fence before `load()`; ask it before the write:
+ *
+ *   const fence = sampleFence({ key, tags });
+ *   const value = await load();
+ *   if (fence.isValid()) await tier.set(key, value, { tags });
+ */
+export function sampleFence(scope: FenceScope): CacheFence {
+  const sampledAt = generation;
+  const covered: FenceScope[] = [scope];
+
+  return {
+    cover(next: FenceScope): void {
+      covered.push(next);
+    },
+
+    isValid(): boolean {
+      // Older than the ring remembers: unprovable, so refused. One refetch, not a stale TTL.
+      if (sampledAt < forgottenThrough) return false;
+      for (let i = marks.length - 1; i >= 0; i -= 1) {
+        const mark = marks[i];
+        // Marks are pushed in generation order, so the first one at or below the sample ends it.
+        if (mark === undefined || mark.at <= sampledAt) break;
+        if (covered.some((scoped) => hits(mark, scoped))) return false;
+      }
+      return true;
+    },
+  };
+}

package/src/index.ts

@@ -7,26 +7,39 @@ export {
   CACHE_ERROR_CODES,
   CACHE_ERROR_TITLES,
   CacheDriverUnavailableError,
+  CacheJitterInvalidError,
   CachePurgeFailedError,
   CacheTagUnknownError,
   CacheTooLargeError,
+  CacheTtlInvalidError,
 } from './errors';
+export type { CacheFence, FenceScope } from './fence';
+export { FENCE_MEMORY, markInvalidated, sampleFence } from './fence';
 export type { CacheDependent, DependentKind } from './graph';
 export {
   dependentsOf,
   dependentsOfKind,
   graphSize,
   graphSnapshot,
+  isolateGraph,
   registerDependent,
   resetGraph,
   unregisterDependent,
 } from './graph';
-export type { InvalidationEvent, InvalidationReport, Revalidator } from './invalidate';
+export type {
+  InvalidationBroadcast,
+  InvalidationEvent,
+  InvalidationReport,
+  Revalidator,
+} from './invalidate';
 export {
   invalidateTags,
   invalidateWireTags,
+  isolateTiers,
+  receiveInvalidationBroadcast,
   recentInvalidations,
   registeredTiers,
+  registerInvalidationBroadcast,
   registerRevalidator,
   registerTier,
   resetTiers,
@@ -48,7 +61,12 @@ export { FASTLY_API_URL, FASTLY_MAX_KEYS_PER_REQUEST, fastlyPurgeDriver } from '
 export type { PurgeFetch } from './purge-http';
 export { DEFAULT_PURGE_TIMEOUT_MS } from './purge-http';
 export type { RedisLike, RedisTierOptions } from './redis';
-export { createRedisTier, REDIS_INVALIDATE_SCRIPT } from './redis';
+export {
+  createRedisTier,
+  namespaceFor,
+  REDIS_INVALIDATE_SCRIPT,
+  REDIS_TAG_MEMBER_SCRIPT,
+} from './redis';
 export type {
   Embedding,
   SemanticCache,
@@ -57,26 +75,45 @@ export type {
   SemanticRememberOptions,
 } from './semantic';
 export { cosineSimilarity, createMemorySemanticCache } from './semantic';
+export type { FlightJoin, SingleFlight } from './single-flight';
+export { createSingleFlight } from './single-flight';
 export type { CacheTag, CacheTagRegistry, TagFactory } from './tags';
 export {
   assertKnownTags,
   declareTags,
+  isolateDeclaredTags,
   knownTags,
   parseTag,
   resetDeclaredTags,
   serializeTag,
   serializeTags,
   tag,
+  tagKeys,
   tagMatches,
   tagsFor,
   tagsIntersect,
 } from './tags';
+export type { TierFailure, TierOperation } from './tier-failures';
+export { bestEffort, recentTierFailures } from './tier-failures';
 export type {
   CacheEntry,
   CacheSetOptions,
   CacheStack,
+  CacheStackOptions,
   CacheTier,
+  Rng,
   TierInvalidation,
+  TierLabel,
   TierName,
+  TtlJitter,
+  TtlScope,
+} from './tiers';
+export {
+  assertTtl,
+  createCacheStack,
+  DEFAULT_TTL_JITTER_FRACTION,
+  isExpired,
+  nowMs,
+  sortTiers,
+  TIER_ORDER,
 } from './tiers';
-export { createCacheStack, isExpired, nowMs, sortTiers, TIER_ORDER } from './tiers';

package/src/invalidate.ts

@@ -4,21 +4,39 @@
 // 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';
-import { assertKnownTags, parseTag, serializeTags } from './tags';
+import { assertKnownTags, knownTags, parseTag, serializeTags } from './tags';
+import { isolateTierFailures, resetTierFailures } from './tier-failures';
 import type { CacheTier, TierInvalidation } from './tiers';
-import { sortTiers } from './tiers';
+import { sortTiers, TIER_ORDER } from './tiers';
 
 /** Revalidates one ISR route path. Provided by `@ultimat3/render`; absent on a worker. */
 export type Revalidator = (path: string) => Promise<void> | void;
 
+/**
+ * Carries wire tags to every OTHER process. The seam, never the transport: `cache` is tier 1 and
+ * may not reach `realtime` (tier 3) or NATS, so `@ultimat3/cli` registers the sender at boot the
+ * same way `@ultimat3/render` registers the `Revalidator`.
+ *
+ * Without one, `invalidateTags` clears the LRU of exactly one process: a user edits their profile
+ * on pod 3, their next request lands on pod 7, and pod 7's in-process copy serves the pre-edit
+ * value for up to `defaultTtlMs`. The user watches their edit vanish and re-submits.
+ */
+export type InvalidationBroadcast = (wireTags: readonly string[]) => Promise<void> | void;
+
 export interface InvalidationReport {
   readonly tags: readonly string[];
   readonly tiers: readonly TierInvalidation[];
   /** ISR route paths queued for regeneration. */
   readonly isr: readonly string[];
+  /**
+   * CDN paths the graph hangs off these tags — what *depends* on them, not what cleared. The
+   * `cdn` tier is what purges them (as surrogate keys, with the tags), so what actually cleared
+   * is that tier's row in `tiers`. With no `cdn` tier registered this list purges nowhere.
+   */
   readonly cdn: readonly string[];
   readonly liveQueries: readonly string[];
   readonly durationMs: number;
@@ -32,8 +50,13 @@ export interface InvalidationEvent {
   /** Wire-form tags, exactly `report.tags`. */
   readonly tags: readonly string[];
   /**
-   * Everything the fan-out actually cleared: every tier key, plus the ISR paths, CDN paths
-   * and live queries.
+   * Everything the fan-out actually cleared: every tier key — the `cdn` tier's accepted purge
+   * keys included — plus the ISR paths and the live queries.
+   *
+   * Deliberately NOT `report.cdn`: that is the dependency graph's answer to "what depends on
+   * these tags", and folding it in here reported a path as busted when no `cdn` tier was
+   * registered to purge it. A partial bust that reads as a clean one is the failure this log
+   * exists to catch.
    */
   readonly busted: readonly string[];
   /**
@@ -64,6 +87,7 @@ export function recentInvalidations(): readonly InvalidationEvent[] {
 
 const registry: CacheTier[] = [];
 let revalidator: Revalidator | undefined;
+let broadcast: InvalidationBroadcast | undefined;
 
 /** Tiers register at boot from `app.config.ts`; order is normalised, not trusted. */
 export function registerTier(tier: CacheTier): void {
@@ -76,17 +100,59 @@ export function registeredTiers(): readonly CacheTier[] {
   return sortTiers(registry);
 }
 
-/** Test seam: drops every registered tier, the revalidator, and the invalidation log. */
+/**
+ * Test seam: drops every registered tier, the revalidator, the invalidation log and the
+ * swallowed-failure log. One reset, so a suite cannot clear half the recorded state.
+ */
 export function resetTiers(): void {
   registry.length = 0;
   revalidator = undefined;
+  broadcast = undefined;
   invalidationLog.length = 0;
+  resetTierFailures();
+}
+
+/**
+ * `isolateDeclaredTags()`'s contract over everything `resetTiers()` drops — `tags.ts` carries the
+ * why. It must live here because three of the four pieces are unreachable from a test file: the
+ * revalidator has no reader, and neither log has a writer, so a suite that reset them could put
+ * back only the tier registry:
+ *
+ *   const restoreTiers = isolateTiers();
+ *   afterAll(restoreTiers);
+ *
+ * Registration order is kept, not `sortTiers()`'s: `registeredTiers()` normalises on read, so
+ * restoring the sorted list would hand the process back a registry it never had.
+ */
+export function isolateTiers(): () => void {
+  const capturedTiers = [...registry];
+  const capturedRevalidator = revalidator;
+  const capturedBroadcast = broadcast;
+  const capturedLog = [...invalidationLog];
+  const restoreFailures = isolateTierFailures();
+
+  return () => {
+    resetTiers();
+    registry.push(...capturedTiers);
+    revalidator = capturedRevalidator;
+    broadcast = capturedBroadcast;
+    invalidationLog.push(...capturedLog);
+    restoreFailures();
+  };
 }
 
 export function registerRevalidator(next: Revalidator): void {
   revalidator = next;
 }
 
+/**
+ * Registers the outbound half of cross-instance invalidation. Called once at boot by whatever
+ * owns the transport — `@ultimat3/cli`, not this package.
+ */
+export function registerInvalidationBroadcast(next: InvalidationBroadcast): void {
+  broadcast = next;
+}
+
 /**
  * Fan out `tags` across every registered tier plus the dependency graph. Never throws for a
  * tier failure: a dead Redis must not fail the write that triggered the bust — the failure
@@ -96,24 +162,76 @@ export function invalidateTags(tags: readonly CacheTag[]): Promise<InvalidationR
   // Captured before `withSpan` opens `cache.invalidate` below: inside that callback the active
   // span is already this call's own, which would make every event's source the same string.
   const source = currentSpan()?.name ?? 'invalidateTags';
+  return fanOut(tags, { source, emit: true, validate: true, errors: [] });
+}
+
+/**
+ * The inbound half: another instance's fan-out, applied here.
+ *
+ * It cannot re-emit, and that is structural rather than a flag a caller could set wrong — `emit`
+ * lives on `fanOut`'s private options and this is the only entry point that passes `false`. A
+ * broadcast that re-broadcast would be a storm bounded by nothing.
+ *
+ * A tag this process has not declared is DROPPED and reported, never thrown: mid-deploy the new
+ * pods know an entity the old ones do not, and a throw here kills the subscriber loop that
+ * delivered it — which would silently end cross-instance invalidation for the whole process.
+ */
+export function receiveInvalidationBroadcast(wire: readonly string[]): Promise<InvalidationReport> {
+  const declared = new Set(knownTags());
+  const errors: { tier: string; message: string }[] = [];
+  const accepted: CacheTag[] = [];
+  for (const value of wire) {
+    const parsed = parseTag(value);
+    // An empty registry is `assertKnownTags`'s "validation is off" state; honour the same rule.
+    if (declared.size === 0 || declared.has(parsed.entity)) accepted.push(parsed);
+    else errors.push({ tier: 'broadcast', message: `ignored undeclared tag "${value}"` });
+  }
+  return fanOut(accepted, { source: 'cache.broadcast', emit: false, validate: false, errors });
+}
+
+interface FanOutOptions {
+  readonly source: string;
+  /** Never widened to a public parameter: see `receiveInvalidationBroadcast`. */
+  readonly emit: boolean;
+  /** The local path throws on a typo; the inbound one has already filtered instead. */
+  readonly validate: boolean;
+  readonly errors: { tier: string; message: string }[];
+}
+
+function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<InvalidationReport> {
+  const { source, emit } = options;
 
   return withSpan('cache.invalidate', async (): Promise<InvalidationReport> => {
     const startedAt = performance.now();
-    assertKnownTags(tags);
+    // Inside the span, so a typo is a REJECTED promise and not a synchronous throw past every
+    // caller that only ever awaited this function.
+    if (options.validate) assertKnownTags(tags);
+
+    // Before the first tier is touched, so a read-through fill whose `load()` started earlier
+    // cannot republish what this call is about to clear — the bust would otherwise land on a key
+    // that is not there yet, report `errors: []`, and be overwritten milliseconds later.
+    markInvalidated({ tags });
 
     const tiers: TierInvalidation[] = [];
-    const errors: { tier: string; message: string }[] = [];
+    const errors = options.errors;
 
-    for (const tier of sortTiers(registry)) {
+    // FARTHEST tier first. Near-to-far leaves the far tier holding the old value after the near
+    // ones are clear, and a read racing the bust promotes it straight back up into them — the
+    // report says every tier cleared, and the LRU is stale again before the call returns.
+    for (const tier of [...sortTiers(registry)].reverse()) {
       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
+    // printed upside down is a second thing for a reader to learn.
+    tiers.sort((a, b) => TIER_ORDER.indexOf(a.tier) - TIER_ORDER.indexOf(b.tier));
 
     const isr = dependentsOfKind(tags, 'isr-route');
     const cdn = dependentsOfKind(tags, 'cdn-path');
@@ -123,15 +241,24 @@ export function invalidateTags(tags: readonly CacheTag[]): Promise<InvalidationR
       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) });
+      }
+    }
+
+    const wire = serializeTags(tags);
+
+    // Last, and best-effort: every LOCAL tier has already cleared, so a dead transport degrades
+    // to "the other pods clear on TTL" rather than failing the write that triggered the bust.
+    if (emit && wire.length > 0 && broadcast !== undefined) {
+      try {
+        await broadcast(wire);
+      } catch (error) {
+        errors.push({ tier: 'broadcast', message: renderThrowable(error) });
       }
     }
 
     const report: InvalidationReport = {
-      tags: serializeTags(tags),
+      tags: wire,
       tiers,
       isr,
       cdn,
@@ -146,7 +273,6 @@ export function invalidateTags(tags: readonly CacheTag[]): Promise<InvalidationR
       busted: dedupe([
         ...report.tiers.flatMap((entry) => entry.keys),
         ...report.isr,
-        ...report.cdn,
         ...report.liveQueries,
       ]),
       source,

package/src/lru.ts

@@ -8,8 +8,15 @@ import { systemClock } from '@ultimat3/core';
 import { CacheTooLargeError } from './errors';
 import type { CacheTag } from './tags';
 import { serializeTag } from './tags';
-import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
-import { nowMs } from './tiers';
+import type {
+  CacheEntry,
+  CacheSetOptions,
+  CacheTier,
+  Rng,
+  TierInvalidation,
+  TtlJitter,
+} from './tiers';
+import { assertTtl, nowMs } from './tiers';
 
 export interface LruOptions {
   /** Byte budget for the whole tier. Default 64 MiB. */
@@ -17,13 +24,17 @@ export interface LruOptions {
   /** Applied when a `set` omits `ttlMs`. Default 60s — stale-by-default is safer here. */
   readonly defaultTtlMs?: number;
   readonly clock?: Clock;
+  /** TTL spread, in `[0, 1)`. Default `DEFAULT_TTL_JITTER_FRACTION`; `0` disables it. */
+  readonly jitterFraction?: number;
+  /** Injected so a jittered expiry is deterministic; `() => 0` is the full lease. */
+  readonly rng?: Rng;
 }
 
 interface LruNode {
   key: string;
   value: unknown;
   bytes: number;
-  /** Epoch ms, or `Number.POSITIVE_INFINITY` for no expiry. */
+  /** Epoch ms. Always finite: `assertTtl` refuses the `0` that used to mean "never expires". */
   expiresAt: number;
   tags: readonly CacheTag[];
   prev: LruNode | undefined;
@@ -77,6 +88,7 @@ export class LruCache {
   private readonly maxBytes: number;
   private readonly defaultTtlMs: number;
   private readonly clock: Clock;
+  private readonly jitter: TtlJitter;
   private head: LruNode | undefined;
   private tail: LruNode | undefined;
   private bytes = 0;
@@ -88,6 +100,10 @@ export class LruCache {
     this.maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
     this.defaultTtlMs = options.defaultTtlMs ?? 60_000;
     this.clock = options.clock ?? systemClock;
+    this.jitter = {
+      ...(options.jitterFraction === undefined ? {} : { jitterFraction: options.jitterFraction }),
+      ...(options.rng === undefined ? {} : { rng: options.rng }),
+    };
   }
 
   get<T>(key: string): CacheEntry<T> | undefined {
@@ -103,11 +119,7 @@ export class LruCache {
     }
     this.touch(node);
     this.hits += 1;
-    return {
-      value: node.value as T,
-      tags: node.tags,
-      ...(node.expiresAt === Number.POSITIVE_INFINITY ? {} : { expiresAt: node.expiresAt }),
-    };
+    return { value: node.value as T, tags: node.tags, expiresAt: node.expiresAt };
   }
 
   set<T>(key: string, value: T, options: CacheSetOptions = {}): void {
@@ -116,15 +128,17 @@ export class LruCache {
       throw new CacheTooLargeError({ key, bytes, maxBytes: this.maxBytes, tier: 'lru' });
     }
 
+    // Validate BEFORE evicting the entry being replaced: a rejected write must leave the cache
+    // exactly as it found it, or `X_CACHE_TTL_INVALID` also silently drops a live, valid value.
+    const ttl = assertTtl(key, options.ttlMs ?? this.defaultTtlMs, 'lru', this.jitter);
     const existing = this.map.get(key);
     if (existing !== undefined) this.unlink(existing);
 
-    const ttl = options.ttlMs ?? this.defaultTtlMs;
     const node: LruNode = {
       key,
       value,
       bytes,
-      expiresAt: ttl <= 0 ? Number.POSITIVE_INFINITY : nowMs(this.clock) + ttl,
+      expiresAt: nowMs(this.clock) + ttl,
       tags: options.tags ?? [],
       prev: undefined,
       next: undefined,
@@ -185,6 +199,11 @@ export class LruCache {
     this.head = undefined;
     this.tail = undefined;
     this.bytes = 0;
+    // Stats describe THIS cache's lifetime, not the process's — a cleared cache is a fresh one,
+    // so `stats()` after `clear()` must not still show hits/evictions from what is now gone.
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
   }
 
   stats(): LruStats {
@@ -240,9 +259,12 @@ export function createLruTier(options: LruOptions = {}): CacheTier & { readonly
     get<T>(key: string) {
       return Promise.resolve(cache.get<T>(key));
     },
-    set<T>(key: string, value: T, setOptions?: CacheSetOptions) {
+    // `async`, so a refusal is a REJECTION and not a synchronous throw out of a function typed
+    // `Promise<void>`. `LruCache.set` stays synchronous — it is a sync API — but a `CacheTier` is
+    // one interface with two implementations, and `tier.set(...).catch(...)` has to mean the same
+    // thing on the in-process rung as on the shared one, where the throw is already a rejection.
+    async set<T>(key: string, value: T, setOptions?: CacheSetOptions) {
       cache.set(key, value, setOptions ?? {});
-      return Promise.resolve();
     },
     del(key: string) {
       cache.del(key);