layercache 3.0.0 → 3.1.1

package/dist/index.cjs

@@ -98,39 +98,6 @@ function cloneNamespaceMetrics(metrics) {
     )
   };
 }
-function diffNamespaceMetrics(before, after) {
-  const latencyByLayer = Object.fromEntries(
-    Object.entries(after.latencyByLayer).map(([layer, value]) => [
-      layer,
-      {
-        avgMs: value.avgMs,
-        maxMs: value.maxMs,
-        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
-      }
-    ])
-  );
-  return {
-    hits: after.hits - before.hits,
-    misses: after.misses - before.misses,
-    fetches: after.fetches - before.fetches,
-    sets: after.sets - before.sets,
-    deletes: after.deletes - before.deletes,
-    backfills: after.backfills - before.backfills,
-    invalidations: after.invalidations - before.invalidations,
-    staleHits: after.staleHits - before.staleHits,
-    refreshes: after.refreshes - before.refreshes,
-    refreshErrors: after.refreshErrors - before.refreshErrors,
-    writeFailures: after.writeFailures - before.writeFailures,
-    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
-    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
-    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
-    degradedOperations: after.degradedOperations - before.degradedOperations,
-    hitsByLayer: diffMetricMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMetricMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
 function addNamespaceMetrics(base, delta) {
   return {
     hits: base.hits + delta.hits,
@@ -166,14 +133,6 @@ function computeNamespaceHitRate(metrics) {
   }
   return { overall, byLayer };
 }
-function diffMetricMap(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
-  }
-  return result;
-}
 function addMetricMap(base, delta) {
   const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
   const result = {};
@@ -210,6 +169,20 @@ var CacheNamespace = class _CacheNamespace {
   async getOrSet(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Returns a namespaced cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    const entry = await this.trackMetrics(() => this.cache.getEntry(this.qualify(key)));
+    if (entry === null) {
+      return null;
+    }
+    return {
+      ...entry,
+      key
+    };
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    */
@@ -444,13 +417,24 @@ var CacheNamespace = class _CacheNamespace {
     };
   }
   async trackMetrics(operation) {
-    return this.getMetricsMutex().runExclusive(async () => {
-      const before = this.cache.getMetrics();
-      const result = await operation();
-      const after = this.cache.getMetrics();
-      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
-      return result;
+    let result;
+    let metrics;
+    try {
+      ;
+      ({ result, metrics } = await this.cache.captureMetrics(operation));
+    } catch (error) {
+      const capturedMetrics = error.metrics;
+      if (capturedMetrics) {
+        await this.getMetricsMutex().runExclusive(() => {
+          this.metrics = addNamespaceMetrics(this.metrics, capturedMetrics);
+        });
+      }
+      throw error;
+    }
+    await this.getMetricsMutex().runExclusive(() => {
+      this.metrics = addNamespaceMetrics(this.metrics, metrics);
     });
+    return result;
   }
   getMetricsMutex() {
     const existing = _CacheNamespace.metricsMutexes.get(this.cache);
@@ -1271,6 +1255,9 @@ var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
 var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
+var SINGLE_FLIGHT_BACKOFF_FACTOR = 2;
+var SINGLE_FLIGHT_BACKOFF_JITTER = 0.2;
+var SINGLE_FLIGHT_MAX_POLL_MS = 1e3;
 var CacheStackReader = class {
   constructor(options) {
     this.options = options;
@@ -1494,6 +1481,7 @@ var CacheStackReader = class {
     const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
     const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
     const deadline = Date.now() + timeoutMs;
+    let nextPollMs = pollIntervalMs;
     this.options.metricsCollector.increment("singleFlightWaits");
     this.options.emit("stampede-dedupe", { key });
     while (Date.now() < deadline) {
@@ -1502,7 +1490,13 @@ var CacheStackReader = class {
         this.options.metricsCollector.increment("hits");
         return hit.value;
       }
-      await this.options.sleep(pollIntervalMs);
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        break;
+      }
+      const delayMs = Math.min(this.jitterSingleFlightPoll(nextPollMs), remainingMs);
+      await this.options.sleep(delayMs);
+      nextPollMs = Math.min(nextPollMs * SINGLE_FLIGHT_BACKOFF_FACTOR, SINGLE_FLIGHT_MAX_POLL_MS, timeoutMs);
     }
     if (!this.options.singleFlightCoordinator) {
       return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
@@ -1514,12 +1508,18 @@ var CacheStackReader = class {
       () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext)
     );
   }
+  jitterSingleFlightPoll(delayMs) {
+    const jitterRange = delayMs * SINGLE_FLIGHT_BACKOFF_JITTER;
+    return Math.max(1, Math.round(delayMs - jitterRange + Math.random() * jitterRange * 2));
+  }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
     currentValue: void 0,
     state: "miss"
   }) {
-    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    const circuitBreakerOptions = options?.circuitBreaker ?? this.options.circuitBreaker;
+    const breakerKey = this.resolveCircuitBreakerKey(key, circuitBreakerOptions);
+    this.options.circuitBreakerManager.assertClosed(breakerKey, circuitBreakerOptions);
     this.options.metricsCollector.increment("fetches");
     const fetchStart = Date.now();
     let fetched;
@@ -1529,13 +1529,13 @@ var CacheStackReader = class {
         { key, fetcher },
         () => fetcher(fetcherContext)
       );
-      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.circuitBreakerManager.recordSuccess(breakerKey);
       this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
-      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      this.options.recordCircuitFailure(key, breakerKey, circuitBreakerOptions, error);
       throw error;
     }
-    if (fetched === null || fetched === void 0) {
+    if (fetched === void 0 || fetched === null && !this.shouldCacheNullValues(options)) {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
@@ -1577,6 +1577,18 @@ var CacheStackReader = class {
     await this.options.storeEntry(key, "value", fetched, options);
     return fetched;
   }
+  resolveCircuitBreakerKey(key, options) {
+    if (!options) {
+      return `key:${key}`;
+    }
+    if (options.breakerKey) {
+      return `custom:${options.breakerKey}`;
+    }
+    if (options.scope === "shared") {
+      return "scope:shared";
+    }
+    return `key:${key}`;
+  }
   runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
     this.scheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
   }
@@ -1677,6 +1689,9 @@ var CacheStackReader = class {
   shouldNegativeCache(options) {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
+  shouldCacheNullValues(options) {
+    return options?.cacheNullValues ?? this.options.cacheNullValues ?? false;
+  }
   isNegativeStoredValue(stored) {
     return isStoredValueEnvelope(stored) && stored.kind === "empty";
   }
@@ -2019,9 +2034,12 @@ function validateRateLimitOptions(name, options) {
   validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
   validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
   validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
-  if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+  if (options.scope !== void 0 && !["global", "key", "fetcher"].includes(options.scope)) {
     throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
   }
+  if (options.queueOverflow !== void 0 && !["reject", "bypass"].includes(options.queueOverflow)) {
+    throw new Error(`${name}.queueOverflow must be one of "reject" or "bypass".`);
+  }
   if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
     throw new Error(`${name}.bucketKey must not be empty.`);
   }
@@ -2102,6 +2120,12 @@ function validateCircuitBreakerOptions(options) {
   }
   validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
   validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+  if (options.scope !== void 0 && !["key", "shared"].includes(options.scope)) {
+    throw new Error('circuitBreaker.scope must be one of "key" or "shared".');
+  }
+  if (options.breakerKey !== void 0 && options.breakerKey.length === 0) {
+    throw new Error("circuitBreaker.breakerKey must not be empty.");
+  }
 }
 function validateContextEntryOptions(name, options) {
   if (!options) {
@@ -2215,6 +2239,7 @@ var CircuitBreakerManager = class {
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
 var MAX_QUEUE_PER_BUCKET = 1e4;
+var DEFAULT_QUEUE_OVERFLOW_POLICY = "reject";
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -2239,15 +2264,24 @@ var FetchRateLimiter = class {
       const bucketKey = this.resolveBucketKey(normalized, context);
       const queue = this.queuesByBucket.get(bucketKey) ?? [];
       if (queue.length >= MAX_QUEUE_PER_BUCKET) {
-        this.rateLimitBypasses += 1;
-        task().then(resolve2, reject);
+        if ((normalized.queueOverflow ?? DEFAULT_QUEUE_OVERFLOW_POLICY) === "bypass") {
+          this.rateLimitBypasses += 1;
+          task().then(resolve2, reject);
+          return;
+        }
+        reject(new Error(`FetchRateLimiter queue overflow for bucket "${bucketKey}".`));
         return;
       }
       queue.push({
         bucketKey,
         options: normalized,
-        task,
-        resolve: resolve2,
+        run: async () => {
+          try {
+            resolve2(await task());
+          } catch (error) {
+            reject(error);
+          }
+        },
         reject
       });
       this.queuesByBucket.set(bucketKey, queue);
@@ -2288,7 +2322,8 @@ var FetchRateLimiter = class {
       intervalMs,
       maxPerInterval,
       scope: options.scope ?? "global",
-      bucketKey: options.bucketKey
+      bucketKey: options.bucketKey,
+      queueOverflow: options.queueOverflow
     };
   }
   resolveBucketKey(options, context) {
@@ -2371,7 +2406,7 @@ var FetchRateLimiter = class {
       if (next.options.intervalMs && next.options.maxPerInterval) {
         bucket.startedAt.push(Date.now());
       }
-      void next.task().then(next.resolve, next.reject).finally(() => {
+      void next.run().finally(() => {
         bucket.active -= 1;
         if ((this.queuesByBucket.get(next.bucketKey)?.length ?? 0) > 0) {
           this.pendingBuckets.add(next.bucketKey);
@@ -2473,7 +2508,9 @@ var FetchRateLimiter = class {
 };
 
 // src/internal/MetricsCollector.ts
+var import_node_async_hooks = require("async_hooks");
 var MetricsCollector = class {
+  captures = new import_node_async_hooks.AsyncLocalStorage();
   data = this.empty();
   get snapshot() {
     return {
@@ -2486,18 +2523,46 @@ var MetricsCollector = class {
   increment(field, amount = 1) {
     ;
     this.data[field] += amount;
+    for (const capture of this.captures.getStore() ?? []) {
+      ;
+      capture[field] += amount;
+    }
   }
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
+    for (const capture of this.captures.getStore() ?? []) {
+      capture[map][layerName] = (capture[map][layerName] ?? 0) + 1;
+    }
   }
   /**
    * Records a read latency sample for the given layer.
    * Maintains a rolling average and max using Welford's online algorithm.
    */
   recordLatency(layerName, durationMs) {
-    const existing = this.data.latencyByLayer[layerName];
+    this.recordLatencySample(this.data, layerName, durationMs);
+    for (const capture of this.captures.getStore() ?? []) {
+      this.recordLatencySample(capture, layerName, durationMs);
+    }
+  }
+  async capture(operation) {
+    const metrics = this.empty();
+    const activeCaptures = this.captures.getStore();
+    const captures = activeCaptures ? [...activeCaptures, metrics] : [metrics];
+    try {
+      const result = await this.captures.run(captures, operation);
+      return { result, metrics };
+    } catch (error) {
+      if ((typeof error === "object" || typeof error === "function") && error !== null) {
+        ;
+        error.metrics = metrics;
+      }
+      throw error;
+    }
+  }
+  recordLatencySample(metrics, layerName, durationMs) {
+    const existing = metrics.latencyByLayer[layerName];
     if (!existing) {
-      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      metrics.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
       return;
     }
     existing.count += 1;
@@ -2665,30 +2730,34 @@ var TtlResolver = class {
 };
 
 // src/invalidation/TagIndex.ts
-var MAX_PATTERN_RECURSION_DEPTH = 500;
+var DEFAULT_TOUCH_REFRESH_INTERVAL_MS = 1e3;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Map();
   maxKnownKeys;
+  touchRefreshIntervalMs;
   nextNodeId = 1;
   root = this.createTrieNode();
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
+    this.touchRefreshIntervalMs = options.touchRefreshIntervalMs ?? DEFAULT_TOUCH_REFRESH_INTERVAL_MS;
   }
   /**
    * Records a key as known without changing tag assignments.
    */
   async touch(key) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
   }
   /**
    * Replaces the tags associated with a key and records the key as known.
    */
   async track(key, tags) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
+    if (this.insertKnownKey(key)) {
+      this.pruneKnownKeysIfNeeded();
+    }
     if (tags.length === 0) {
       return;
     }
@@ -2758,9 +2827,14 @@ var TagIndex = class {
    * Returns known keys matching a wildcard pattern.
    */
   async matchPattern(pattern) {
-    const matches = /* @__PURE__ */ new Set();
-    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
-    return [...matches];
+    const literalPrefix = this.literalPrefix(pattern);
+    const node = this.findNode(literalPrefix);
+    if (!node) {
+      return [];
+    }
+    const candidates = [];
+    this.collectFromNode(node, literalPrefix, candidates);
+    return candidates.filter((key) => PatternMatcher.matches(pattern, key));
   }
   /**
    * Visits known keys matching a wildcard pattern.
@@ -2790,13 +2864,18 @@ var TagIndex = class {
     };
   }
   insertKnownKey(key) {
-    const isNew = !this.knownKeys.has(key);
+    const previousTouch = this.knownKeys.get(key);
+    const isNew = previousTouch === void 0;
+    const now = Date.now();
+    if (!isNew && now - previousTouch < this.touchRefreshIntervalMs) {
+      return false;
+    }
     if (!isNew) {
       this.knownKeys.delete(key);
     }
-    this.knownKeys.set(key, Date.now());
+    this.knownKeys.set(key, now);
     if (!isNew) {
-      return;
+      return true;
     }
     let node = this.root;
     for (const character of key) {
@@ -2808,6 +2887,7 @@ var TagIndex = class {
       node = child;
     }
     node.terminal = true;
+    return true;
   }
   findNode(prefix) {
     let node = this.root;
@@ -2820,74 +2900,41 @@ var TagIndex = class {
     return node;
   }
   collectFromNode(node, prefix, matches) {
-    if (node.terminal) {
-      matches.push(prefix);
-    }
-    for (const [character, child] of node.children) {
-      this.collectFromNode(child, `${prefix}${character}`, matches);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
+      }
+      if (current.node.terminal) {
+        matches.push(current.prefix);
+      }
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
+      }
     }
   }
   async visitFromNode(node, prefix, visitor) {
-    if (node.terminal) {
-      await visitor(prefix);
-    }
-    for (const [character, child] of node.children) {
-      await this.visitFromNode(child, `${prefix}${character}`, visitor);
-    }
-  }
-  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited, depth) {
-    if (depth > MAX_PATTERN_RECURSION_DEPTH) {
-      return;
-    }
-    const stateKey = `${node.id}:${patternIndex}`;
-    if (visited.has(stateKey)) {
-      return;
-    }
-    visited.add(stateKey);
-    if (patternIndex === pattern.length) {
-      if (node.terminal) {
-        matches.add(prefix);
+    const stack = [{ node, prefix }];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current) {
+        continue;
       }
-      return;
-    }
-    const patternChar = pattern[patternIndex];
-    if (patternChar === void 0) {
-      return;
-    }
-    if (patternChar === "*") {
-      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited, depth + 1);
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited, depth + 1);
+      if (current.node.terminal) {
+        await visitor(current.prefix);
       }
-      return;
-    }
-    if (patternChar === "?") {
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(
-          child2,
-          `${prefix}${character}`,
-          pattern,
-          patternIndex + 1,
-          matches,
-          visited,
-          depth + 1
-        );
+      const children = [...current.node.children].reverse();
+      for (const [character, child] of children) {
+        stack.push({ node: child, prefix: `${current.prefix}${character}` });
       }
-      return;
-    }
-    const child = node.children.get(patternChar);
-    if (child) {
-      this.collectPatternMatches(
-        child,
-        `${prefix}${patternChar}`,
-        pattern,
-        patternIndex + 1,
-        matches,
-        visited,
-        depth + 1
-      );
     }
   }
+  literalPrefix(pattern) {
+    const wildcardIndex = pattern.search(/[*?]/);
+    return wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
+  }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;
@@ -3195,7 +3242,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       emitError: (operation, context) => this.emitError(operation, context),
       formatError: (error) => this.formatError(error),
       storeEntry: (key, kind, value, options2) => this.storeEntry(key, kind, value, options2),
-      recordCircuitFailure: (key, options2, error) => this.recordCircuitFailure(key, options2, error),
+      recordCircuitFailure: (key, breakerKey, options2, error) => this.recordCircuitFailure(key, breakerKey, options2, error),
       resolveLayerMs: (layerName, override, globalDefault, fallback) => this.resolveLayerMs(layerName, override, globalDefault, fallback),
       sleep: (ms) => this.sleep(ms),
       withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
@@ -3210,6 +3257,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
       backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
       negativeCaching: options.negativeCaching,
+      cacheNullValues: options.cacheNullValues,
       refreshAhead: options.refreshAhead,
       circuitBreaker: options.circuitBreaker,
       fetcherRateLimit: options.fetcherRateLimit
@@ -3262,6 +3310,64 @@ var CacheStack = class extends import_node_events.EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Returns a discriminated cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    return this.observeOperation("layercache.get_entry", { "layercache.key": String(key ?? "") }, async () => {
+      const userKey = validateCacheKey(key);
+      const normalizedKey = this.qualifyKey(userKey);
+      await this.awaitStartup("getEntry");
+      let sawRetainableValue = false;
+      for (let index = 0; index < this.layers.length; index += 1) {
+        const layer = this.layers[index];
+        if (!layer || this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const readStart = performance.now();
+        const stored = await this.readLayerEntry(layer, normalizedKey);
+        this.metricsCollector.recordLatency(layer.name, performance.now() - readStart);
+        if (stored === null) {
+          this.metricsCollector.incrementLayer("missesByLayer", layer.name);
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(normalizedKey);
+          continue;
+        }
+        sawRetainableValue = true;
+        await this.tagIndex.touch(normalizedKey);
+        await this.reader.backfill(normalizedKey, stored, index - 1);
+        this.metricsCollector.increment("hits");
+        if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
+          this.metricsCollector.increment("staleHits");
+        }
+        this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+        this.logger.debug?.("hit", { key: normalizedKey, layer: layer.name, state: resolved.state });
+        this.emit("hit", {
+          key: normalizedKey,
+          layer: layer.name,
+          state: resolved.state
+        });
+        return {
+          key: userKey,
+          value: resolved.value,
+          kind: resolved.envelope?.kind ?? "value",
+          state: resolved.state,
+          layer: layer.name
+        };
+      }
+      if (!sawRetainableValue) {
+        await this.tagIndex.remove(normalizedKey);
+      }
+      this.metricsCollector.increment("misses");
+      this.logger.debug?.("miss", { key: normalizedKey, mode: "getEntry" });
+      this.emit("miss", { key: normalizedKey, mode: "getEntry" });
+      return null;
+    });
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    * Useful when the value is expected to exist or the fetcher is expected to
@@ -3726,6 +3832,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
+  /**
+   * Runs an operation while collecting only the metrics emitted by its async context.
+   * Used by namespaces so metrics tracking does not serialize the operation itself.
+   */
+  async captureMetrics(operation) {
+    return this.metricsCollector.capture(operation);
+  }
   /**
    * Returns metrics plus layer degradation state and active background refresh count.
    */
@@ -4029,7 +4142,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     for (const key of keys) {
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("deletes", keys.length);
     this.metricsCollector.increment("invalidations");
@@ -4048,7 +4161,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("invalidations");
     this.logger.debug?.("expire", { keys });
@@ -4090,7 +4203,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       for (const key of keys) {
         await this.tagIndex.remove(key);
         this.ttlResolver.deleteProfile(key);
-        this.circuitBreakerManager.delete(key);
+        this.circuitBreakerManager.delete(`key:${key}`);
       }
     }
   }
@@ -4335,15 +4448,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
   isGracefulDegradationEnabled() {
     return Boolean(this.options.gracefulDegradation);
   }
-  recordCircuitFailure(key, options, error) {
+  recordCircuitFailure(key, breakerKey, options, error) {
     if (!options) {
       return;
     }
-    this.circuitBreakerManager.recordFailure(key, options);
-    if (this.circuitBreakerManager.isOpen(key)) {
+    this.circuitBreakerManager.recordFailure(breakerKey, options);
+    if (this.circuitBreakerManager.isOpen(breakerKey)) {
       this.metricsCollector.increment("circuitBreakerTrips");
     }
-    this.emitError("fetch", { key, error: this.formatError(error) });
+    this.emitError("fetch", { key, breakerKey, error: this.formatError(error) });
   }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
@@ -5989,6 +6102,7 @@ var PayloadProtectionError = class extends Error {
 
 // src/layers/DiskLayer.ts
 var FILE_SCAN_CONCURRENCY = 32;
+var DEFAULT_MAX_WRITE_QUEUE_DEPTH = 1e4;
 var DiskLayer = class {
   name;
   defaultTtl;
@@ -5997,8 +6111,10 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  maxWriteQueueDepth;
   protection;
   writeQueue = Promise.resolve();
+  writeQueueDepth = 0;
   /**
    * Creates a disk-backed cache layer.
    */
@@ -6009,6 +6125,7 @@ var DiskLayer = class {
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
     this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
+    this.maxWriteQueueDepth = this.normalizeMaxWriteQueueDepth(options.maxWriteQueueDepth);
     this.protection = new PayloadProtection({
       encryptionKey: options.encryptionKey,
       signingKey: options.signingKey
@@ -6224,6 +6341,16 @@ var DiskLayer = class {
     }
     return normalized;
   }
+  normalizeMaxWriteQueueDepth(maxWriteQueueDepth) {
+    if (maxWriteQueueDepth === false) {
+      return false;
+    }
+    const normalized = maxWriteQueueDepth ?? DEFAULT_MAX_WRITE_QUEUE_DEPTH;
+    if (!Number.isInteger(normalized) || normalized <= 0) {
+      throw new Error("DiskLayer.maxWriteQueueDepth must be a positive integer or false.");
+    }
+    return normalized;
+  }
   async readEntryFile(filePath) {
     let handle;
     try {
@@ -6336,7 +6463,13 @@ var DiskLayer = class {
     }
   }
   enqueueWrite(operation) {
-    const next = this.writeQueue.then(operation, operation);
+    if (this.maxWriteQueueDepth !== false && this.writeQueueDepth >= this.maxWriteQueueDepth) {
+      return Promise.reject(new Error(`DiskLayer write queue limit (${this.maxWriteQueueDepth}) exceeded.`));
+    }
+    this.writeQueueDepth += 1;
+    const next = this.writeQueue.then(operation, operation).finally(() => {
+      this.writeQueueDepth -= 1;
+    });
     this.writeQueue = next.catch(() => void 0);
     return next;
   }