layercache 1.3.2 → 1.3.4

package/dist/index.cjs

@@ -961,6 +961,7 @@ var CacheStackLayerWriter = class {
 };
 
 // src/internal/CacheStackMaintenance.ts
+var MAX_KEY_EPOCHS = 5e4;
 var CacheStackMaintenance = class {
   keyEpochs = /* @__PURE__ */ new Map();
   writeBehindQueue = [];
@@ -1004,6 +1005,7 @@ var CacheStackMaintenance = class {
     for (const key of keys) {
       this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
     }
+    this.pruneKeyEpochsIfNeeded();
   }
   isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
     if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
@@ -1056,6 +1058,16 @@ var CacheStackMaintenance = class {
   async waitForGenerationCleanup() {
     await this.generationCleanupPromise;
   }
+  pruneKeyEpochsIfNeeded() {
+    if (this.keyEpochs.size <= MAX_KEY_EPOCHS) {
+      return;
+    }
+    const sorted = [...this.keyEpochs.entries()].sort((a, b) => a[1] - b[1]);
+    const toDelete = Math.ceil(sorted.length * 0.1);
+    for (let i = 0; i < toDelete; i++) {
+      this.keyEpochs.delete(sorted[i][0]);
+    }
+  }
 };
 
 // src/internal/CacheStackRuntimePolicy.ts
@@ -1094,17 +1106,377 @@ function planFreshReadPolicies({
   };
 }
 
+// src/internal/CacheStackReader.ts
+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 CacheStackReader = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  backgroundRefreshes = /* @__PURE__ */ new Map();
+  backgroundRefreshAbort = /* @__PURE__ */ new Map();
+  get activeRefreshCount() {
+    return this.backgroundRefreshes.size;
+  }
+  async getPrepared(normalizedKey, fetcher, options) {
+    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
+    if (hit.found) {
+      this.options.ttlResolver.recordAccess(normalizedKey);
+      if (this.isNegativeStoredValue(hit.stored)) {
+        this.options.metricsCollector.increment("negativeCacheHits");
+      }
+      if (hit.state === "fresh") {
+        this.options.metricsCollector.increment("hits");
+        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
+        return hit.value;
+      }
+      if (hit.state === "stale-while-revalidate") {
+        this.options.metricsCollector.increment("hits");
+        this.options.metricsCollector.increment("staleHits");
+        this.options.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        if (fetcher) {
+          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
+        }
+        return hit.value;
+      }
+      if (!fetcher) {
+        this.options.metricsCollector.increment("hits");
+        this.options.metricsCollector.increment("staleHits");
+        this.options.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
+        return hit.value;
+      }
+      try {
+        return await this.fetchWithGuards(normalizedKey, fetcher, options);
+      } catch (error) {
+        this.options.metricsCollector.increment("staleHits");
+        this.options.metricsCollector.increment("refreshErrors");
+        this.options.logger.debug?.("stale-if-error", {
+          key: normalizedKey,
+          error: this.options.formatError(error)
+        });
+        return hit.value;
+      }
+    }
+    this.options.metricsCollector.increment("misses");
+    if (!fetcher) {
+      return null;
+    }
+    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
+  }
+  async readLayerEntry(layer, key) {
+    if (this.options.shouldSkipLayer(layer)) {
+      return null;
+    }
+    if (layer.getEntry) {
+      try {
+        return await layer.getEntry(key);
+      } catch (error) {
+        return this.options.handleLayerFailure(layer, "read", error);
+      }
+    }
+    try {
+      return await layer.get(key);
+    } catch (error) {
+      return this.options.handleLayerFailure(layer, "read", error);
+    }
+  }
+  async backfill(key, stored, upToIndex, options) {
+    if (upToIndex < 0) {
+      return;
+    }
+    for (let index = 0; index <= upToIndex; index += 1) {
+      const layer = this.options.layers[index];
+      if (!layer || this.options.shouldSkipLayer(layer)) {
+        continue;
+      }
+      const ttl = remainingStoredTtlSeconds(stored) ?? this.options.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
+      try {
+        await layer.set(key, stored, ttl);
+      } catch (error) {
+        await this.options.handleLayerFailure(layer, "backfill", error);
+        continue;
+      }
+      this.options.metricsCollector.increment("backfills");
+      this.options.logger.debug?.("backfill", { key, layer: layer.name });
+      this.options.emit("backfill", { key, layer: layer.name });
+    }
+  }
+  abortAllRefreshes() {
+    for (const key of this.backgroundRefreshAbort.keys()) {
+      this.backgroundRefreshAbort.set(key, true);
+    }
+  }
+  getAllRefreshPromises() {
+    return [...this.backgroundRefreshes.values()];
+  }
+  async readFromLayers(key, options, mode) {
+    let sawRetainableValue = false;
+    for (let index = 0; index < this.options.layers.length; index += 1) {
+      const layer = this.options.layers[index];
+      if (!layer) continue;
+      const readStart = performance.now();
+      const stored = await this.readLayerEntry(layer, key);
+      const readDuration = performance.now() - readStart;
+      this.options.metricsCollector.recordLatency(layer.name, readDuration);
+      if (stored === null) {
+        this.options.metricsCollector.incrementLayer("missesByLayer", layer.name);
+        continue;
+      }
+      const resolved = resolveStoredValue(stored);
+      if (resolved.state === "expired") {
+        await layer.delete(key);
+        continue;
+      }
+      sawRetainableValue = true;
+      if (mode === "fresh-only" && resolved.state !== "fresh") {
+        continue;
+      }
+      await this.options.tagIndex.touch(key);
+      await this.backfill(key, stored, index - 1, options);
+      this.options.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+      this.options.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
+      this.options.emit("hit", {
+        key,
+        layer: layer.name,
+        state: resolved.state
+      });
+      return {
+        found: true,
+        value: resolved.value,
+        stored,
+        state: resolved.state,
+        layerIndex: index,
+        layerName: layer.name
+      };
+    }
+    if (!sawRetainableValue) {
+      await this.options.tagIndex.remove(key);
+    }
+    this.options.logger.debug?.("miss", { key, mode });
+    this.options.emit("miss", { key, mode });
+    return { found: false, value: null, stored: null, state: "miss" };
+  }
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
+    const fetchTask = async () => {
+      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
+      if (shouldRecheckFreshLayers) {
+        const secondHit = await this.readFromLayers(key, options, "fresh-only");
+        if (secondHit.found) {
+          this.options.metricsCollector.increment("hits");
+          return secondHit.value;
+        }
+      }
+      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
+    };
+    const singleFlightTask = async () => {
+      if (!this.options.singleFlightCoordinator) {
+        return fetchTask();
+      }
+      try {
+        return await this.options.singleFlightCoordinator.execute(
+          key,
+          this.resolveSingleFlightOptions(),
+          fetchTask,
+          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
+        );
+      } catch (error) {
+        if (!this.options.isGracefulDegradationEnabled()) {
+          throw error;
+        }
+        this.options.metricsCollector.increment("degradedOperations");
+        this.options.logger.warn?.("single-flight-coordinator-degraded", {
+          key,
+          error: this.options.formatError(error)
+        });
+        this.options.emitError("single-flight", {
+          key,
+          degraded: true,
+          error: this.options.formatError(error)
+        });
+        return fetchTask();
+      }
+    };
+    if (this.options.stampedePrevention === false) {
+      return singleFlightTask();
+    }
+    return this.options.stampedeGuard.execute(key, singleFlightTask);
+  }
+  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+    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;
+    this.options.metricsCollector.increment("singleFlightWaits");
+    this.options.emit("stampede-dedupe", { key });
+    while (Date.now() < deadline) {
+      const hit = await this.readFromLayers(key, options, "fresh-only");
+      if (hit.found) {
+        this.options.metricsCollector.increment("hits");
+        return hit.value;
+      }
+      await this.options.sleep(pollIntervalMs);
+    }
+    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
+  }
+  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    this.options.metricsCollector.increment("fetches");
+    const fetchStart = Date.now();
+    let fetched;
+    try {
+      fetched = await this.options.fetchRateLimiter.schedule(
+        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
+        { key, fetcher },
+        fetcher
+      );
+      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
+    } catch (error) {
+      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      throw error;
+    }
+    if (fetched === null || fetched === void 0) {
+      if (!this.shouldNegativeCache(options)) {
+        return null;
+      }
+      if (this.options.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+        this.options.logger.debug?.("skip-negative-store-after-invalidation", {
+          key,
+          expectedClearEpoch,
+          clearEpoch: this.options.maintenance.currentClearEpoch(),
+          expectedKeyEpoch,
+          keyEpoch: this.options.maintenance.currentKeyEpoch(key)
+        });
+        return null;
+      }
+      await this.options.storeEntry(key, "empty", null, options);
+      return null;
+    }
+    if (options?.shouldCache) {
+      try {
+        if (!options.shouldCache(fetched)) {
+          return fetched;
+        }
+      } catch (error) {
+        this.options.logger.warn?.("shouldCache-error", {
+          key,
+          error: this.options.formatError(error)
+        });
+      }
+    }
+    if (this.options.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+      this.options.logger.debug?.("skip-store-after-invalidation", {
+        key,
+        expectedClearEpoch,
+        clearEpoch: this.options.maintenance.currentClearEpoch(),
+        expectedKeyEpoch,
+        keyEpoch: this.options.maintenance.currentKeyEpoch(key)
+      });
+      return fetched;
+    }
+    await this.options.storeEntry(key, "value", fetched, options);
+    return fetched;
+  }
+  runScheduleBackgroundRefresh(key, fetcher, options) {
+    this.scheduleBackgroundRefresh(key, fetcher, options);
+  }
+  scheduleBackgroundRefresh(key, fetcher, options) {
+    if (!shouldStartBackgroundRefresh({
+      isDisconnecting: this.options.isDisconnecting(),
+      hasRefreshInFlight: this.backgroundRefreshes.has(key)
+    })) {
+      return;
+    }
+    const clearEpoch = this.options.maintenance.currentClearEpoch();
+    const keyEpoch = this.options.maintenance.currentKeyEpoch(key);
+    this.backgroundRefreshAbort.set(key, false);
+    const refresh = (async () => {
+      this.options.metricsCollector.increment("refreshes");
+      try {
+        if (this.backgroundRefreshAbort.get(key)) return;
+        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
+      } catch (error) {
+        if (this.backgroundRefreshAbort.get(key)) return;
+        this.options.metricsCollector.increment("refreshErrors");
+        this.options.logger.warn?.("background-refresh-error", {
+          key,
+          error: this.options.formatError(error)
+        });
+      } finally {
+        this.backgroundRefreshes.delete(key);
+        this.backgroundRefreshAbort.delete(key);
+      }
+    })();
+    this.backgroundRefreshes.set(key, refresh);
+  }
+  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
+    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
+    await this.fetchWithGuards(
+      key,
+      () => this.options.withTimeout(fetcher(), timeoutMs, () => {
+        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
+      }),
+      options,
+      expectedClearEpoch,
+      expectedKeyEpoch
+    );
+  }
+  async runApplyFreshReadPolicies(key, hit, options, fetcher) {
+    return this.applyFreshReadPolicies(key, hit, options, fetcher);
+  }
+  async applyFreshReadPolicies(key, hit, options, fetcher) {
+    const plan = planFreshReadPolicies({
+      stored: hit.stored,
+      hasFetcher: Boolean(fetcher),
+      slidingTtl: options?.slidingTtl ?? false,
+      refreshAheadSeconds: this.options.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0
+    });
+    if (plan.refreshedStored) {
+      for (let index = 0; index <= hit.layerIndex; index += 1) {
+        const layer = this.options.layers[index];
+        if (!layer || this.options.shouldSkipLayer(layer)) {
+          continue;
+        }
+        try {
+          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "sliding-ttl", error);
+        }
+      }
+    }
+    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
+      this.options.scheduleBackgroundRefreshDispatch(key, fetcher, options);
+    }
+  }
+  resolveSingleFlightOptions() {
+    return {
+      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
+      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
+      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
+      renewIntervalMs: this.options.singleFlightRenewIntervalMs
+    };
+  }
+  shouldNegativeCache(options) {
+    return options?.negativeCache ?? this.options.negativeCaching ?? false;
+  }
+  isNegativeStoredValue(stored) {
+    return isStoredValueEnvelope(stored) && stored.kind === "empty";
+  }
+};
+
 // src/internal/CacheStackSnapshotManager.ts
-var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
-var import_node_path = __toESM(require("path"), 1);
 
 // src/internal/CacheSnapshotFile.ts
-function isWithinSnapshotBase(realBaseDir, candidatePath, pathSeparator, path2) {
-  const relative = path2.relative(realBaseDir, candidatePath);
-  return !(relative === ".." || relative.startsWith(`..${pathSeparator}`) || path2.isAbsolute(relative));
+var import_node_crypto = require("crypto");
+var import_promises = require("fs/promises");
+function isWithinSnapshotBase(realBaseDir, candidatePath, pathSeparator, path) {
+  const relative = path.relative(realBaseDir, candidatePath);
+  return !(relative === ".." || relative.startsWith(`..${pathSeparator}`) || path.isAbsolute(relative));
 }
-async function findExistingAncestor(directory, fs3, path2) {
+async function findExistingAncestor(directory, fs3, path) {
   let current = directory;
   while (true) {
     try {
@@ -1115,7 +1487,7 @@ async function findExistingAncestor(directory, fs3, path2) {
         throw error;
       }
     }
-    const parent = path2.dirname(current);
+    const parent = path.dirname(current);
     if (parent === current) {
       return current;
     }
@@ -1130,36 +1502,36 @@ async function validateSnapshotFilePath(filePath, mode, snapshotBaseDir, cwd = p
     throw new Error("filePath must not contain null bytes.");
   }
   const { promises: fs3 } = await import("fs");
-  const path2 = await import("path");
-  const resolved = path2.resolve(filePath);
-  const baseDir = snapshotBaseDir === false ? false : path2.resolve(snapshotBaseDir ?? cwd);
+  const path = await import("path");
+  const resolved = path.resolve(filePath);
+  const baseDir = snapshotBaseDir === false ? false : path.resolve(snapshotBaseDir ?? cwd);
   if (baseDir === false) {
     return resolved;
   }
   await fs3.mkdir(baseDir, { recursive: true });
   const realBaseDir = await fs3.realpath(baseDir);
-  if (!isWithinSnapshotBase(realBaseDir, resolved, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, resolved, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
   if (mode === "read") {
     const realTarget = await fs3.realpath(resolved);
-    if (!isWithinSnapshotBase(realBaseDir, realTarget, path2.sep, path2)) {
+    if (!isWithinSnapshotBase(realBaseDir, realTarget, path.sep, path)) {
       throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
     }
     return realTarget;
   }
-  const parentDir = path2.dirname(resolved);
-  const existingAncestor = await findExistingAncestor(parentDir, fs3, path2);
+  const parentDir = path.dirname(resolved);
+  const existingAncestor = await findExistingAncestor(parentDir, fs3, path);
   const realExistingAncestor = await fs3.realpath(existingAncestor);
-  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
   await fs3.mkdir(parentDir, { recursive: true });
   const realParentDir = await fs3.realpath(parentDir);
-  if (!isWithinSnapshotBase(realBaseDir, realParentDir, path2.sep, path2)) {
+  if (!isWithinSnapshotBase(realBaseDir, realParentDir, path.sep, path)) {
     throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
   }
-  const targetPath = path2.join(realParentDir, path2.basename(resolved));
+  const targetPath = path.join(realParentDir, path.basename(resolved));
   try {
     const existing = await fs3.lstat(targetPath);
     if (existing.isSymbolicLink()) {
@@ -1194,6 +1566,17 @@ async function readUtf8HandleWithLimit(handle, byteLimit) {
   }
   return Buffer.concat(chunks).toString("utf8");
 }
+function atomicWriteTempPath(targetPath) {
+  return `${targetPath}.tmp-${(0, import_node_crypto.randomBytes)(8).toString("hex")}`;
+}
+async function commitAtomicWrite(tempPath, targetPath) {
+  try {
+    await (0, import_promises.rename)(tempPath, targetPath);
+  } catch (error) {
+    await (0, import_promises.unlink)(tempPath).catch(() => void 0);
+    throw error;
+  }
+}
 
 // src/internal/StructuredDataSanitizer.ts
 var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
@@ -1272,10 +1655,7 @@ var CacheStackSnapshotManager = class {
   }
   async persistToFile(filePath, snapshotBaseDir, maxEntries) {
     const targetPath = await validateSnapshotFilePath(filePath, "write", snapshotBaseDir);
-    const tempPath = import_node_path.default.join(
-      import_node_path.default.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${(0, import_node_crypto.randomBytes)(8).toString("hex")}.tmp`
-    );
+    const tempPath = atomicWriteTempPath(targetPath);
     let handle;
     try {
       handle = await import_node_fs.promises.open(tempPath, "wx");
@@ -1290,7 +1670,7 @@ var CacheStackSnapshotManager = class {
       await openedHandle.writeFile(wroteAny ? "\n]" : "]", "utf8");
       await openedHandle.close();
       handle = void 0;
-      await import_node_fs.promises.rename(tempPath, targetPath);
+      await commitAtomicWrite(tempPath, targetPath);
     } catch (error) {
       await handle?.close().catch(() => void 0);
       await import_node_fs.promises.unlink(tempPath).catch(() => void 0);
@@ -1605,6 +1985,7 @@ var CircuitBreakerManager = class {
 
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
+var MAX_QUEUE_PER_BUCKET = 1e4;
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -1613,6 +1994,7 @@ var FetchRateLimiter = class {
   nextFetcherBucketId = 0;
   drainTimer;
   isDisposed = false;
+  rateLimitBypasses = 0;
   async schedule(options, context, task) {
     if (this.isDisposed) {
       throw new Error("FetchRateLimiter has been disposed.");
@@ -1627,6 +2009,11 @@ var FetchRateLimiter = class {
     return new Promise((resolve2, reject) => {
       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);
+        return;
+      }
       queue.push({
         bucketKey,
         options: normalized,
@@ -1931,7 +2318,13 @@ var MetricsCollector = class {
 };
 
 // src/internal/TtlResolver.ts
+var import_node_crypto2 = require("crypto");
 var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
+var secureRandom = {
+  value() {
+    return (0, import_node_crypto2.randomBytes)(4).readUInt32BE(0) / 4294967296;
+  }
+};
 var TtlResolver = class {
   accessProfiles = /* @__PURE__ */ new Map();
   maxProfileEntries;
@@ -1994,7 +2387,7 @@ var TtlResolver = class {
     if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
       return ttl;
     }
-    const delta = (Math.random() * 2 - 1) * jitter;
+    const delta = (secureRandom.value() * 2 - 1) * jitter;
     return Math.max(1, Math.round(ttl + delta));
   }
   resolvePolicyTtl(key, value, policy) {
@@ -2046,7 +2439,7 @@ var MAX_PATTERN_RECURSION_DEPTH = 500;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
-  knownKeys = /* @__PURE__ */ new Set();
+  knownKeys = /* @__PURE__ */ new Map();
   maxKnownKeys;
   nextNodeId = 1;
   root = this.createTrieNode();
@@ -2134,10 +2527,11 @@ var TagIndex = class {
     };
   }
   insertKnownKey(key) {
-    if (this.knownKeys.has(key)) {
+    const isNew = !this.knownKeys.has(key);
+    this.knownKeys.set(key, Date.now());
+    if (!isNew) {
       return;
     }
-    this.knownKeys.add(key);
     let node = this.root;
     for (const character of key) {
       let child = node.children.get(character);
@@ -2232,14 +2626,13 @@ var TagIndex = class {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;
     }
+    const sorted = [...this.knownKeys.entries()].sort((a, b) => a[1] - b[1]);
     const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
-    let removed = 0;
-    for (const key of this.knownKeys) {
-      if (removed >= toRemove) {
-        break;
+    for (let i = 0; i < toRemove && i < sorted.length; i += 1) {
+      const entry = sorted[i];
+      if (entry) {
+        this.removeKey(entry[0]);
       }
-      this.removeKey(key);
-      removed += 1;
     }
   }
   removeKey(key) {
@@ -2264,19 +2657,19 @@ var TagIndex = class {
     if (!this.knownKeys.delete(key)) {
       return;
     }
-    const path2 = [];
+    const path = [];
     let node = this.root;
     for (const character of key) {
       const child = node.children.get(character);
       if (!child) {
         return;
       }
-      path2.push([node, character]);
+      path.push([node, character]);
       node = child;
     }
     node.terminal = false;
-    for (let index = path2.length - 1; index >= 0; index -= 1) {
-      const entry = path2[index];
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+      const entry = path[index];
       if (!entry) {
         continue;
       }
@@ -2390,10 +2783,6 @@ var CacheMissError = class extends Error {
 };
 
 // src/CacheStack.ts
-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 DEFAULT_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
 var DEFAULT_SNAPSHOT_MAX_ENTRIES = 1e4;
 var DEFAULT_INVALIDATION_MAX_KEYS = 1e4;
@@ -2503,14 +2892,49 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.snapshots = new CacheStackSnapshotManager({
       layers: this.layers,
       tagIndex: this.tagIndex,
-      snapshotSerializer: this.snapshotSerializer,
-      readLayerEntry: this.readLayerEntry.bind(this),
+      snapshotSerializer: this.snapshotSerializer,
+      readLayerEntry: (layer, key) => this.reader.readLayerEntry(layer, key),
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
+      qualifyKey: this.qualifyKey.bind(this),
+      stripQualifiedKey: this.stripQualifiedKey.bind(this),
+      validateCacheKey,
+      formatError: this.formatError.bind(this)
+    });
+    this.reader = new CacheStackReader({
+      layers: this.layers,
+      metricsCollector: this.metricsCollector,
+      maintenance: this.maintenance,
+      tagIndex: this.tagIndex,
+      circuitBreakerManager: this.circuitBreakerManager,
+      fetchRateLimiter: this.fetchRateLimiter,
+      stampedeGuard: this.stampedeGuard,
+      ttlResolver: this.ttlResolver,
+      logger: this.logger,
       shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
       handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
-      qualifyKey: this.qualifyKey.bind(this),
-      stripQualifiedKey: this.stripQualifiedKey.bind(this),
-      validateCacheKey,
-      formatError: this.formatError.bind(this)
+      emit: (event, data) => this.emit(event, data),
+      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),
+      resolveLayerSeconds: (layerName, override, globalDefault, fallback) => this.resolveLayerSeconds(layerName, override, globalDefault, fallback),
+      sleep: (ms) => this.sleep(ms),
+      withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
+      isDisconnecting: () => this.isDisconnecting,
+      isGracefulDegradationEnabled: () => this.isGracefulDegradationEnabled(),
+      scheduleBackgroundRefreshDispatch: (key, fetcher, options2) => this.scheduleBackgroundRefresh(key, fetcher, options2),
+      stampedePrevention: options.stampedePrevention,
+      singleFlightCoordinator: options.singleFlightCoordinator,
+      singleFlightLeaseMs: options.singleFlightLeaseMs,
+      singleFlightTimeoutMs: options.singleFlightTimeoutMs,
+      singleFlightPollMs: options.singleFlightPollMs,
+      singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
+      backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
+      negativeCaching: options.negativeCaching,
+      refreshAhead: options.refreshAhead,
+      circuitBreaker: options.circuitBreaker,
+      fetcherRateLimit: options.fetcherRateLimit
     });
     this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
@@ -2530,8 +2954,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   invalidation;
   layerWriter;
   snapshots;
-  backgroundRefreshes = /* @__PURE__ */ new Map();
-  backgroundRefreshAbort = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   maintenance = new CacheStackMaintenance();
   ttlResolver;
@@ -2539,6 +2961,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   nextOperationId = 0;
   currentGeneration;
   isDisconnecting = false;
+  reader;
   disconnectPromise;
   /**
    * Read-through cache get.
@@ -2551,51 +2974,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       const normalizedKey = this.qualifyKey(validateCacheKey(key));
       this.validateWriteOptions(options);
       await this.awaitStartup("get");
-      return this.getPrepared(normalizedKey, fetcher, options);
+      return this.reader.getPrepared(normalizedKey, fetcher, options);
     });
   }
-  async getPrepared(normalizedKey, fetcher, options) {
-    const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
-    if (hit.found) {
-      this.ttlResolver.recordAccess(normalizedKey);
-      if (this.isNegativeStoredValue(hit.stored)) {
-        this.metricsCollector.increment("negativeCacheHits");
-      }
-      if (hit.state === "fresh") {
-        this.metricsCollector.increment("hits");
-        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
-        return hit.value;
-      }
-      if (hit.state === "stale-while-revalidate") {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        if (fetcher) {
-          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
-        }
-        return hit.value;
-      }
-      if (!fetcher) {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        return hit.value;
-      }
-      try {
-        return await this.fetchWithGuards(normalizedKey, fetcher, options);
-      } catch (error) {
-        this.metricsCollector.increment("staleHits");
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("stale-if-error", { key: normalizedKey, error: this.formatError(error) });
-        return hit.value;
-      }
-    }
-    this.metricsCollector.increment("misses");
-    if (!fetcher) {
-      return null;
-    }
-    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
-  }
   /**
    * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
    * Fetches and caches the value if not already present.
@@ -2746,7 +3127,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
             const optionsSignature = serializeOptions(entry.options);
             const existing = pendingReads.get(entry.key);
             if (!existing) {
-              const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
+              const promise = this.reader.getPrepared(entry.key, entry.fetch, entry.options);
               pendingReads.set(entry.key, {
                 promise,
                 fetch: entry.fetch,
@@ -2782,7 +3163,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         if (keys.length === 0) {
           break;
         }
-        const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
+        const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.reader.readLayerEntry(layer, key)));
         for (let offset = 0; offset < values.length; offset += 1) {
           const key = keys[offset];
           const stored = values[offset];
@@ -2798,7 +3179,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
             this.metricsCollector.increment("staleHits", indexesByKey.get(key)?.length ?? 1);
           }
           await this.tagIndex.touch(key);
-          await this.backfill(key, stored, layerIndex - 1);
+          await this.reader.backfill(key, stored, layerIndex - 1);
           resultsByKey.set(key, resolved.value);
           pending.delete(key);
           this.metricsCollector.increment("hits", indexesByKey.get(key)?.length ?? 1);
@@ -2932,7 +3313,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         isLocal: Boolean(layer.isLocal),
         degradedUntil: this.layerDegradedUntil.get(layer.name) ?? null
       })),
-      backgroundRefreshes: this.backgroundRefreshes.size
+      backgroundRefreshes: this.reader.activeRefreshCount
     };
   }
   resetMetrics() {
@@ -3052,11 +3433,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
         await this.maintenance.waitForGenerationCleanup();
-        for (const key of this.backgroundRefreshAbort.keys()) {
-          this.backgroundRefreshAbort.set(key, true);
-        }
+        this.reader.abortAllRefreshes();
         await Promise.allSettled(
-          [...this.backgroundRefreshes.values()].map((promise) => {
+          this.reader.getAllRefreshPromises().map((promise) => {
             let timer;
             return Promise.race([
               promise,
@@ -3069,8 +3448,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
             });
           })
         );
-        this.backgroundRefreshes.clear();
-        this.backgroundRefreshAbort.clear();
         this.maintenance.disposeWriteBehindTimer();
         this.fetchRateLimiter.dispose();
         await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
@@ -3086,116 +3463,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
-    const fetchTask = async () => {
-      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
-      if (shouldRecheckFreshLayers) {
-        const secondHit = await this.readFromLayers(key, options, "fresh-only");
-        if (secondHit.found) {
-          this.metricsCollector.increment("hits");
-          return secondHit.value;
-        }
-      }
-      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-    };
-    const singleFlightTask = async () => {
-      if (!this.options.singleFlightCoordinator) {
-        return fetchTask();
-      }
-      try {
-        return await this.options.singleFlightCoordinator.execute(
-          key,
-          this.resolveSingleFlightOptions(),
-          fetchTask,
-          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-        );
-      } catch (error) {
-        if (!this.isGracefulDegradationEnabled()) {
-          throw error;
-        }
-        this.metricsCollector.increment("degradedOperations");
-        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
-        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
-        return fetchTask();
-      }
-    };
-    if (this.options.stampedePrevention === false) {
-      return singleFlightTask();
-    }
-    return this.stampedeGuard.execute(key, singleFlightTask);
-  }
-  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    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;
-    this.metricsCollector.increment("singleFlightWaits");
-    this.emit("stampede-dedupe", { key });
-    while (Date.now() < deadline) {
-      const hit = await this.readFromLayers(key, options, "fresh-only");
-      if (hit.found) {
-        this.metricsCollector.increment("hits");
-        return hit.value;
-      }
-      await this.sleep(pollIntervalMs);
-    }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-  }
-  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
-    this.metricsCollector.increment("fetches");
-    const fetchStart = Date.now();
-    let fetched;
-    try {
-      fetched = await this.fetchRateLimiter.schedule(
-        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
-        { key, fetcher },
-        fetcher
-      );
-      this.circuitBreakerManager.recordSuccess(key);
-      this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
-    } catch (error) {
-      this.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
-      throw error;
-    }
-    if (fetched === null || fetched === void 0) {
-      if (!this.shouldNegativeCache(options)) {
-        return null;
-      }
-      if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-        this.logger.debug?.("skip-negative-store-after-invalidation", {
-          key,
-          expectedClearEpoch,
-          clearEpoch: this.maintenance.currentClearEpoch(),
-          expectedKeyEpoch,
-          keyEpoch: this.maintenance.currentKeyEpoch(key)
-        });
-        return null;
-      }
-      await this.storeEntry(key, "empty", null, options);
-      return null;
-    }
-    if (options?.shouldCache) {
-      try {
-        if (!options.shouldCache(fetched)) {
-          return fetched;
-        }
-      } catch (error) {
-        this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
-      }
-    }
-    if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-      this.logger.debug?.("skip-store-after-invalidation", {
-        key,
-        expectedClearEpoch,
-        clearEpoch: this.maintenance.currentClearEpoch(),
-        expectedKeyEpoch,
-        keyEpoch: this.maintenance.currentKeyEpoch(key)
-      });
-      return fetched;
-    }
-    await this.storeEntry(key, "value", fetched, options);
-    return fetched;
-  }
   async storeEntry(key, kind, value, options) {
     const clearEpoch = this.maintenance.currentClearEpoch();
     const keyEpoch = this.maintenance.currentKeyEpoch(key);
@@ -3242,87 +3509,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
       });
     }
   }
-  async readFromLayers(key, options, mode) {
-    let sawRetainableValue = false;
-    for (let index = 0; index < this.layers.length; index += 1) {
-      const layer = this.layers[index];
-      if (!layer) continue;
-      const readStart = performance.now();
-      const stored = await this.readLayerEntry(layer, key);
-      const readDuration = performance.now() - readStart;
-      this.metricsCollector.recordLatency(layer.name, readDuration);
-      if (stored === null) {
-        this.metricsCollector.incrementLayer("missesByLayer", layer.name);
-        continue;
-      }
-      const resolved = resolveStoredValue(stored);
-      if (resolved.state === "expired") {
-        await layer.delete(key);
-        continue;
-      }
-      sawRetainableValue = true;
-      if (mode === "fresh-only" && resolved.state !== "fresh") {
-        continue;
-      }
-      await this.tagIndex.touch(key);
-      await this.backfill(key, stored, index - 1, options);
-      this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
-      this.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
-      this.emit("hit", { key, layer: layer.name, state: resolved.state });
-      return {
-        found: true,
-        value: resolved.value,
-        stored,
-        state: resolved.state,
-        layerIndex: index,
-        layerName: layer.name
-      };
-    }
-    if (!sawRetainableValue) {
-      await this.tagIndex.remove(key);
-    }
-    this.logger.debug?.("miss", { key, mode });
-    this.emit("miss", { key, mode });
-    return { found: false, value: null, stored: null, state: "miss" };
-  }
-  async readLayerEntry(layer, key) {
-    if (this.shouldSkipLayer(layer)) {
-      return null;
-    }
-    if (layer.getEntry) {
-      try {
-        return await layer.getEntry(key);
-      } catch (error) {
-        return this.handleLayerFailure(layer, "read", error);
-      }
-    }
-    try {
-      return await layer.get(key);
-    } catch (error) {
-      return this.handleLayerFailure(layer, "read", error);
-    }
-  }
-  async backfill(key, stored, upToIndex, options) {
-    if (upToIndex < 0) {
-      return;
-    }
-    for (let index = 0; index <= upToIndex; index += 1) {
-      const layer = this.layers[index];
-      if (!layer || this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      try {
-        await layer.set(key, stored, ttl);
-      } catch (error) {
-        await this.handleLayerFailure(layer, "backfill", error);
-        continue;
-      }
-      this.metricsCollector.increment("backfills");
-      this.logger.debug?.("backfill", { key, layer: layer.name });
-      this.emit("backfill", { key, layer: layer.name });
-    }
-  }
   resolveFreshTtl(key, layerName, kind, options, fallbackTtl, value) {
     return this.ttlResolver.resolveFreshTtl(
       key,
@@ -3338,55 +3524,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   resolveLayerSeconds(layerName, override, globalDefault, fallback) {
     return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
   }
-  shouldNegativeCache(options) {
-    return options?.negativeCache ?? this.options.negativeCaching ?? false;
-  }
-  scheduleBackgroundRefresh(key, fetcher, options) {
-    if (!shouldStartBackgroundRefresh({
-      isDisconnecting: this.isDisconnecting,
-      hasRefreshInFlight: this.backgroundRefreshes.has(key)
-    })) {
-      return;
-    }
-    const clearEpoch = this.maintenance.currentClearEpoch();
-    const keyEpoch = this.maintenance.currentKeyEpoch(key);
-    this.backgroundRefreshAbort.set(key, false);
-    const refresh = (async () => {
-      this.metricsCollector.increment("refreshes");
-      try {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
-      } catch (error) {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
-      } finally {
-        this.backgroundRefreshes.delete(key);
-        this.backgroundRefreshAbort.delete(key);
-      }
-    })();
-    this.backgroundRefreshes.set(key, refresh);
-  }
-  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
-    await this.fetchWithGuards(
-      key,
-      () => this.withTimeout(fetcher(), timeoutMs, () => {
-        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
-      }),
-      options,
-      expectedClearEpoch,
-      expectedKeyEpoch
-    );
-  }
-  resolveSingleFlightOptions() {
-    return {
-      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
-      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
-      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
-      renewIntervalMs: this.options.singleFlightRenewIntervalMs
-    };
-  }
   async deleteKeys(keys) {
     if (keys.length === 0) {
       return;
@@ -3632,32 +3769,22 @@ var CacheStack = class extends import_node_events.EventEmitter {
     await this.startup;
     this.assertActive(operation);
   }
+  async readLayerEntry(layer, key) {
+    return this.reader.readLayerEntry(layer, key);
+  }
+  scheduleBackgroundRefresh(key, fetcher, options) {
+    this.reader.runScheduleBackgroundRefresh(key, fetcher, options);
+  }
   async applyFreshReadPolicies(key, hit, options, fetcher) {
-    const plan = planFreshReadPolicies({
-      stored: hit.stored,
-      hasFetcher: Boolean(fetcher),
-      slidingTtl: options?.slidingTtl ?? false,
-      refreshAheadSeconds: this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0
-    });
-    if (plan.refreshedStored) {
-      for (let index = 0; index <= hit.layerIndex; index += 1) {
-        const layer = this.layers[index];
-        if (!layer || this.shouldSkipLayer(layer)) {
-          continue;
-        }
-        try {
-          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
-        } catch (error) {
-          await this.handleLayerFailure(layer, "sliding-ttl", error);
-        }
-      }
-    }
-    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
-      this.scheduleBackgroundRefresh(key, fetcher, options);
-    }
+    return this.reader.runApplyFreshReadPolicies(key, hit, options, fetcher);
   }
   shouldSkipLayer(layer) {
-    return shouldSkipLayer(this.layerDegradedUntil.get(layer.name));
+    const degradedUntil = this.layerDegradedUntil.get(layer.name);
+    const skip = shouldSkipLayer(degradedUntil);
+    if (!skip && degradedUntil !== void 0) {
+      this.layerDegradedUntil.delete(layer.name);
+    }
+    return skip;
   }
   async handleLayerFailure(layer, operation, error) {
     const recovery = resolveRecoverableLayerFailure(this.options.gracefulDegradation);
@@ -3691,9 +3818,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     this.emitError("fetch", { key, error: this.formatError(error) });
   }
-  isNegativeStoredValue(stored) {
-    return isStoredValueEnvelope(stored) && stored.kind === "empty";
-  }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
     if (this.listenerCount("error") > 0) {
@@ -4872,12 +4996,12 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_path = require("path");
 
 // src/internal/PayloadProtection.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
 var MAGIC_SIGNED = Buffer.from("LCS1:");
 var ALGORITHM = "aes-256-gcm";
@@ -4890,11 +5014,11 @@ var PayloadProtection = class {
   constructor(options) {
     if (options.encryptionKey) {
       const raw = Buffer.isBuffer(options.encryptionKey) ? options.encryptionKey : Buffer.from(options.encryptionKey, "utf8");
-      this.encryptionKey = (0, import_node_crypto2.createHash)("sha256").update(raw).digest();
+      this.encryptionKey = (0, import_node_crypto3.createHash)("sha256").update(raw).digest();
     }
     if (options.signingKey && !options.encryptionKey) {
       const raw = Buffer.isBuffer(options.signingKey) ? options.signingKey : Buffer.from(options.signingKey, "utf8");
-      this.signingKey = (0, import_node_crypto2.createHash)("sha256").update(raw).digest();
+      this.signingKey = (0, import_node_crypto3.createHash)("sha256").update(raw).digest();
     }
   }
   /** Returns `true` when any protection (encryption or signing) is configured. */
@@ -4941,8 +5065,8 @@ var PayloadProtection = class {
   }
   // ── Encryption (AES-256-GCM) ──────────────────────────────────────────
   encrypt(plaintext, key) {
-    const iv = (0, import_node_crypto2.randomBytes)(IV_LENGTH);
-    const cipher = (0, import_node_crypto2.createCipheriv)(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const iv = (0, import_node_crypto3.randomBytes)(IV_LENGTH);
+    const cipher = (0, import_node_crypto3.createCipheriv)(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
     const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return Buffer.concat([MAGIC_ENCRYPTED, iv, authTag, encrypted]);
@@ -4953,7 +5077,7 @@ var PayloadProtection = class {
     const authTag = payload.subarray(headerEnd + IV_LENGTH, headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
     const ciphertext = payload.subarray(headerEnd + IV_LENGTH + AUTH_TAG_LENGTH);
     try {
-      const decipher = (0, import_node_crypto2.createDecipheriv)(ALGORITHM, key, iv, {
+      const decipher = (0, import_node_crypto3.createDecipheriv)(ALGORITHM, key, iv, {
         authTagLength: AUTH_TAG_LENGTH
       });
       decipher.setAuthTag(authTag);
@@ -4966,15 +5090,15 @@ var PayloadProtection = class {
   }
   // ── Signing (HMAC-SHA256) ─────────────────────────────────────────────
   sign(payload, key) {
-    const hmac = (0, import_node_crypto2.createHmac)("sha256", key).update(payload).digest();
+    const hmac = (0, import_node_crypto3.createHmac)("sha256", key).update(payload).digest();
     return Buffer.concat([MAGIC_SIGNED, hmac, payload]);
   }
   verify(payload, key) {
     const headerEnd = MAGIC_SIGNED.length;
     const receivedHmac = payload.subarray(headerEnd, headerEnd + HMAC_LENGTH);
     const data = payload.subarray(headerEnd + HMAC_LENGTH);
-    const expectedHmac = (0, import_node_crypto2.createHmac)("sha256", key).update(data).digest();
-    if (receivedHmac.length !== HMAC_LENGTH || !(0, import_node_crypto2.timingSafeEqual)(receivedHmac, expectedHmac)) {
+    const expectedHmac = (0, import_node_crypto3.createHmac)("sha256", key).update(data).digest();
+    if (receivedHmac.length !== HMAC_LENGTH || !(0, import_node_crypto3.timingSafeEqual)(receivedHmac, expectedHmac)) {
       throw new PayloadProtectionError(
         "HMAC verification failed. The data may have been tampered with or the signingKey is incorrect."
       );
@@ -5054,7 +5178,7 @@ var DiskLayer = class {
       const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8");
       const protectedPayload = this.protection.protect(raw);
       const targetPath = this.keyToPath(key);
-      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${(0, import_node_crypto3.randomBytes)(8).toString("hex")}.tmp`;
+      const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${(0, import_node_crypto4.randomBytes)(8).toString("hex")}.tmp`;
       try {
         await import_node_fs2.promises.writeFile(tempPath, protectedPayload);
         await import_node_fs2.promises.rename(tempPath, targetPath);
@@ -5116,7 +5240,7 @@ var DiskLayer = class {
         return;
       }
       await this.deletePathsWithConcurrency(
-        entries.filter((name) => name.endsWith(".lc")).map((name) => (0, import_node_path2.join)(this.directory, name))
+        entries.filter((name) => name.endsWith(".lc")).map((name) => (0, import_node_path.join)(this.directory, name))
       );
     });
   }
@@ -5154,8 +5278,8 @@ var DiskLayer = class {
   async dispose() {
   }
   keyToPath(key) {
-    const hash = (0, import_node_crypto3.createHash)("sha256").update(key).digest("hex");
-    return (0, import_node_path2.join)(this.directory, `${hash}.lc`);
+    const hash = (0, import_node_crypto4.createHash)("sha256").update(key).digest("hex");
+    return (0, import_node_path.join)(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
     if (typeof directory !== "string" || directory.trim().length === 0) {
@@ -5164,7 +5288,7 @@ var DiskLayer = class {
     if (directory.includes("\0")) {
       throw new Error("DiskLayer.directory must not contain null bytes.");
     }
-    return (0, import_node_path2.resolve)(directory);
+    return (0, import_node_path.resolve)(directory);
   }
   normalizeMaxFiles(maxFiles) {
     if (maxFiles === void 0) {
@@ -5247,7 +5371,7 @@ var DiskLayer = class {
           if (name === void 0) {
             return;
           }
-          const filePath = (0, import_node_path2.join)(this.directory, name);
+          const filePath = (0, import_node_path.join)(this.directory, name);
           const raw = await this.readEntryFile(filePath);
           if (raw === null) {
             continue;
@@ -5323,7 +5447,7 @@ var DiskLayer = class {
     }
     const withStats = await Promise.all(
       lcFiles.map(async (name) => {
-        const filePath = (0, import_node_path2.join)(this.directory, name);
+        const filePath = (0, import_node_path.join)(this.directory, name);
         try {
           const stat = await import_node_fs2.promises.stat(filePath);
           return { filePath, mtimeMs: stat.mtimeMs };
@@ -5439,7 +5563,7 @@ var MsgpackSerializer = class {
 };
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
-var import_node_crypto4 = require("crypto");
+var import_node_crypto5 = require("crypto");
 var RELEASE_SCRIPT = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -5463,7 +5587,7 @@ var RedisSingleFlightCoordinator = class {
   }
   async execute(key, options, worker, waiter) {
     const lockKey = `${this.prefix}:${encodeURIComponent(key)}`;
-    const token = (0, import_node_crypto4.randomUUID)();
+    const token = (0, import_node_crypto5.randomUUID)();
     const acquired = await this.runCommand(
       `acquire("${key}")`,
       () => this.client.set(lockKey, token, "PX", options.leaseMs, "NX")