layercache 1.2.6 → 1.2.8

package/dist/index.cjs

@@ -62,6 +62,127 @@ var import_node_events = require("events");
 
 // src/CacheNamespace.ts
 var import_async_mutex = require("async-mutex");
+
+// src/internal/CacheNamespaceMetrics.ts
+function createEmptyNamespaceMetrics(resetAt = Date.now()) {
+  return {
+    hits: 0,
+    misses: 0,
+    fetches: 0,
+    sets: 0,
+    deletes: 0,
+    backfills: 0,
+    invalidations: 0,
+    staleHits: 0,
+    refreshes: 0,
+    refreshErrors: 0,
+    writeFailures: 0,
+    singleFlightWaits: 0,
+    negativeCacheHits: 0,
+    circuitBreakerTrips: 0,
+    degradedOperations: 0,
+    hitsByLayer: {},
+    missesByLayer: {},
+    latencyByLayer: {},
+    resetAt
+  };
+}
+function cloneNamespaceMetrics(metrics) {
+  return {
+    ...metrics,
+    hitsByLayer: { ...metrics.hitsByLayer },
+    missesByLayer: { ...metrics.missesByLayer },
+    latencyByLayer: Object.fromEntries(
+      Object.entries(metrics.latencyByLayer).map(([key, value]) => [key, { ...value }])
+    )
+  };
+}
+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,
+    misses: base.misses + delta.misses,
+    fetches: base.fetches + delta.fetches,
+    sets: base.sets + delta.sets,
+    deletes: base.deletes + delta.deletes,
+    backfills: base.backfills + delta.backfills,
+    invalidations: base.invalidations + delta.invalidations,
+    staleHits: base.staleHits + delta.staleHits,
+    refreshes: base.refreshes + delta.refreshes,
+    refreshErrors: base.refreshErrors + delta.refreshErrors,
+    writeFailures: base.writeFailures + delta.writeFailures,
+    singleFlightWaits: base.singleFlightWaits + delta.singleFlightWaits,
+    negativeCacheHits: base.negativeCacheHits + delta.negativeCacheHits,
+    circuitBreakerTrips: base.circuitBreakerTrips + delta.circuitBreakerTrips,
+    degradedOperations: base.degradedOperations + delta.degradedOperations,
+    hitsByLayer: addMetricMap(base.hitsByLayer, delta.hitsByLayer),
+    missesByLayer: addMetricMap(base.missesByLayer, delta.missesByLayer),
+    latencyByLayer: cloneNamespaceMetrics(delta).latencyByLayer,
+    resetAt: base.resetAt
+  };
+}
+function computeNamespaceHitRate(metrics) {
+  const total = metrics.hits + metrics.misses;
+  const overall = total === 0 ? 0 : metrics.hits / total;
+  const byLayer = {};
+  const layers = /* @__PURE__ */ new Set([...Object.keys(metrics.hitsByLayer), ...Object.keys(metrics.missesByLayer)]);
+  for (const layer of layers) {
+    const hits = metrics.hitsByLayer[layer] ?? 0;
+    const misses = metrics.missesByLayer[layer] ?? 0;
+    byLayer[layer] = hits + misses === 0 ? 0 : hits / (hits + misses);
+  }
+  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 = {};
+  for (const key of keys) {
+    result[key] = (base[key] ?? 0) + (delta[key] ?? 0);
+  }
+  return result;
+}
+
+// src/CacheNamespace.ts
 var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
@@ -71,7 +192,7 @@ var CacheNamespace = class _CacheNamespace {
   cache;
   prefix;
   static metricsMutexes = /* @__PURE__ */ new WeakMap();
-  metrics = emptyMetrics();
+  metrics = createEmptyNamespaceMetrics();
   async get(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
@@ -168,19 +289,10 @@ var CacheNamespace = class _CacheNamespace {
     );
   }
   getMetrics() {
-    return cloneMetrics(this.metrics);
+    return cloneNamespaceMetrics(this.metrics);
   }
   getHitRate() {
-    const total = this.metrics.hits + this.metrics.misses;
-    const overall = total === 0 ? 0 : this.metrics.hits / total;
-    const byLayer = {};
-    const layers = /* @__PURE__ */ new Set([...Object.keys(this.metrics.hitsByLayer), ...Object.keys(this.metrics.missesByLayer)]);
-    for (const layer of layers) {
-      const hits = this.metrics.hitsByLayer[layer] ?? 0;
-      const misses = this.metrics.missesByLayer[layer] ?? 0;
-      byLayer[layer] = hits + misses === 0 ? 0 : hits / (hits + misses);
-    }
-    return { overall, byLayer };
+    return computeNamespaceHitRate(this.metrics);
   }
   /**
    * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
@@ -221,7 +333,7 @@ var CacheNamespace = class _CacheNamespace {
       const before = this.cache.getMetrics();
       const result = await operation();
       const after = this.cache.getMetrics();
-      this.metrics = addMetrics(this.metrics, diffMetrics(before, after));
+      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
       return result;
     });
   }
@@ -235,111 +347,6 @@ var CacheNamespace = class _CacheNamespace {
     return mutex;
   }
 };
-function emptyMetrics() {
-  return {
-    hits: 0,
-    misses: 0,
-    fetches: 0,
-    sets: 0,
-    deletes: 0,
-    backfills: 0,
-    invalidations: 0,
-    staleHits: 0,
-    refreshes: 0,
-    refreshErrors: 0,
-    writeFailures: 0,
-    singleFlightWaits: 0,
-    negativeCacheHits: 0,
-    circuitBreakerTrips: 0,
-    degradedOperations: 0,
-    hitsByLayer: {},
-    missesByLayer: {},
-    latencyByLayer: {},
-    resetAt: Date.now()
-  };
-}
-function cloneMetrics(metrics) {
-  return {
-    ...metrics,
-    hitsByLayer: { ...metrics.hitsByLayer },
-    missesByLayer: { ...metrics.missesByLayer },
-    latencyByLayer: Object.fromEntries(
-      Object.entries(metrics.latencyByLayer).map(([key, value]) => [key, { ...value }])
-    )
-  };
-}
-function diffMetrics(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: diffMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
-function addMetrics(base, delta) {
-  return {
-    hits: base.hits + delta.hits,
-    misses: base.misses + delta.misses,
-    fetches: base.fetches + delta.fetches,
-    sets: base.sets + delta.sets,
-    deletes: base.deletes + delta.deletes,
-    backfills: base.backfills + delta.backfills,
-    invalidations: base.invalidations + delta.invalidations,
-    staleHits: base.staleHits + delta.staleHits,
-    refreshes: base.refreshes + delta.refreshes,
-    refreshErrors: base.refreshErrors + delta.refreshErrors,
-    writeFailures: base.writeFailures + delta.writeFailures,
-    singleFlightWaits: base.singleFlightWaits + delta.singleFlightWaits,
-    negativeCacheHits: base.negativeCacheHits + delta.negativeCacheHits,
-    circuitBreakerTrips: base.circuitBreakerTrips + delta.circuitBreakerTrips,
-    degradedOperations: base.degradedOperations + delta.degradedOperations,
-    hitsByLayer: addMap(base.hitsByLayer, delta.hitsByLayer),
-    missesByLayer: addMap(base.missesByLayer, delta.missesByLayer),
-    latencyByLayer: cloneMetrics(delta).latencyByLayer,
-    resetAt: base.resetAt
-  };
-}
-function diffMap(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 addMap(base, delta) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (base[key] ?? 0) + (delta[key] ?? 0);
-  }
-  return result;
-}
 function validateNamespaceKey(key) {
   if (key.length === 0) {
     throw new Error("Namespace prefix must not be empty.");
@@ -549,101 +556,781 @@ function createInstanceId() {
   return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
 
-// src/internal/CacheSnapshotFile.ts
-function isWithinSnapshotBase(realBaseDir, candidatePath, pathSeparator, path) {
-  const relative = path.relative(realBaseDir, candidatePath);
-  return !(relative === ".." || relative.startsWith(`..${pathSeparator}`) || path.isAbsolute(relative));
+// src/internal/CacheStackGeneration.ts
+var DEFAULT_GENERATION_CLEANUP_BATCH_SIZE = 500;
+function generationPrefix(generation) {
+  return generation === void 0 ? "" : `v${generation}:`;
 }
-async function findExistingAncestor(directory, fs2, path) {
-  let current = directory;
-  while (true) {
-    try {
-      await fs2.lstat(current);
-      return current;
-    } catch (error) {
-      if (error.code !== "ENOENT") {
-        throw error;
-      }
-    }
-    const parent = path.dirname(current);
-    if (parent === current) {
-      return current;
-    }
-    current = parent;
+function qualifyGenerationKey(key, generation) {
+  const prefix = generationPrefix(generation);
+  return prefix ? `${prefix}${key}` : key;
+}
+function qualifyGenerationPattern(pattern, generation) {
+  return qualifyGenerationKey(pattern, generation);
+}
+function stripGenerationPrefix(key, generation) {
+  const prefix = generationPrefix(generation);
+  if (!prefix || !key.startsWith(prefix)) {
+    return key;
   }
+  return key.slice(prefix.length);
 }
-async function validateSnapshotFilePath(filePath, mode, snapshotBaseDir, cwd = process.cwd()) {
-  if (filePath.length === 0) {
-    throw new Error("filePath must not be empty.");
+function resolveGenerationCleanupTarget({
+  previousGeneration,
+  nextGeneration,
+  generationCleanup
+}) {
+  if (!generationCleanup || previousGeneration === void 0 || previousGeneration === nextGeneration) {
+    return null;
   }
-  if (filePath.includes("\0")) {
-    throw new Error("filePath must not contain null bytes.");
+  return previousGeneration;
+}
+function resolveGenerationCleanupBatchSize(generationCleanup) {
+  if (typeof generationCleanup !== "object" || generationCleanup === null) {
+    return DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
   }
-  const { promises: fs2 } = await import("fs");
-  const path = await import("path");
-  const resolved = path.resolve(filePath);
-  const baseDir = snapshotBaseDir === false ? false : path.resolve(snapshotBaseDir ?? cwd);
-  if (baseDir === false) {
-    return resolved;
+  return generationCleanup.batchSize ?? DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
+}
+function planGenerationCleanupBatches(keys, generationCleanup) {
+  if (keys.length === 0) {
+    return [];
   }
-  await fs2.mkdir(baseDir, { recursive: true });
-  const realBaseDir = await fs2.realpath(baseDir);
-  if (!isWithinSnapshotBase(realBaseDir, resolved, path.sep, path)) {
-    throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
+  const batchSize = resolveGenerationCleanupBatchSize(generationCleanup);
+  const batches = [];
+  for (let index = 0; index < keys.length; index += batchSize) {
+    batches.push(keys.slice(index, index + batchSize));
   }
-  if (mode === "read") {
-    const realTarget = await fs2.realpath(resolved);
-    if (!isWithinSnapshotBase(realBaseDir, realTarget, path.sep, path)) {
-      throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
-    }
-    return realTarget;
+  return batches;
+}
+
+// src/internal/CacheStackInvalidationSupport.ts
+var CacheStackInvalidationSupport = class {
+  constructor(options) {
+    this.options = options;
   }
-  const parentDir = path.dirname(resolved);
-  const existingAncestor = await findExistingAncestor(parentDir, fs2, path);
-  const realExistingAncestor = await fs2.realpath(existingAncestor);
-  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path.sep, path)) {
-    throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
+  options;
+  async collectKeysForTag(tag, maxKeys) {
+    const keys = /* @__PURE__ */ new Set();
+    if (this.options.tagIndex.forEachKeyForTag) {
+      await this.options.tagIndex.forEachKeyForTag(tag, async (key) => {
+        keys.add(key);
+        this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
+      });
+      return [...keys];
+    }
+    for (const key of await this.options.tagIndex.keysForTag(tag)) {
+      keys.add(key);
+      this.assertWithinInvalidationKeyLimit(keys.size, maxKeys);
+    }
+    return [...keys];
   }
-  await fs2.mkdir(parentDir, { recursive: true });
-  const realParentDir = await fs2.realpath(parentDir);
-  if (!isWithinSnapshotBase(realBaseDir, realParentDir, path.sep, path)) {
-    throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
+  intersectKeys(groups) {
+    if (groups.length === 0) {
+      return [];
+    }
+    const [firstGroup, ...rest] = groups;
+    const restSets = rest.map((group) => new Set(group));
+    return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
   }
-  const targetPath = path.join(realParentDir, path.basename(resolved));
-  try {
-    const existing = await fs2.lstat(targetPath);
-    if (existing.isSymbolicLink()) {
-      throw new Error("filePath must not point to a symbolic link.");
+  async deleteKeysFromLayers(layers, keys) {
+    await Promise.all(
+      layers.map(async (layer) => {
+        if (this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        if (layer.deleteMany) {
+          try {
+            await layer.deleteMany(keys);
+          } catch (error) {
+            await this.options.handleLayerFailure(layer, "delete", error);
+          }
+          return;
+        }
+        await Promise.all(
+          keys.map(async (key) => {
+            try {
+              await layer.delete(key);
+            } catch (error) {
+              await this.options.handleLayerFailure(layer, "delete", error);
+            }
+          })
+        );
+      })
+    );
+  }
+  assertWithinInvalidationKeyLimit(size, maxKeys) {
+    if (maxKeys !== false && size > maxKeys) {
+      throw new Error(`Invalidation matched too many keys (${size} > ${maxKeys}).`);
+    }
+  }
+};
+
+// src/internal/StoredValue.ts
+function isStoredValueEnvelope(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (v.__layercache !== 1) {
+    return false;
+  }
+  if (v.kind !== "value" && v.kind !== "empty") {
+    return false;
+  }
+  if (v.freshUntil !== null && (!Number.isFinite(v.freshUntil) || typeof v.freshUntil !== "number")) {
+    return false;
+  }
+  if (v.staleUntil !== null && (!Number.isFinite(v.staleUntil) || typeof v.staleUntil !== "number")) {
+    return false;
+  }
+  if (v.errorUntil !== null && (!Number.isFinite(v.errorUntil) || typeof v.errorUntil !== "number")) {
+    return false;
+  }
+  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
+    return false;
+  }
+  if (typeof v.staleUntil === "number" && v.staleUntil > maxTimestamp) {
+    return false;
+  }
+  if (typeof v.errorUntil === "number" && v.errorUntil > maxTimestamp) {
+    return false;
+  }
+  if (v.freshUntil === null && (v.staleUntil !== null || v.errorUntil !== null)) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.staleUntil === "number" && v.staleUntil < v.freshUntil) {
+    return false;
+  }
+  if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
+    return false;
+  }
+  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
+  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+    return false;
+  }
+  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+    return false;
+  }
+  return true;
+}
+function createStoredValueEnvelope(options) {
+  const now = options.now ?? Date.now();
+  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
+  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
+  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
+  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
+  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
+  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
+  return {
+    __layercache: 1,
+    kind: options.kind,
+    value: options.value,
+    freshUntil,
+    staleUntil,
+    errorUntil,
+    freshTtlSeconds: freshTtlSeconds ?? null,
+    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
+    staleIfErrorSeconds: staleIfErrorSeconds ?? null
+  };
+}
+function resolveStoredValue(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return { state: "fresh", value: stored, stored };
+  }
+  if (stored.freshUntil === null || stored.freshUntil > now) {
+    return { state: "fresh", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.staleUntil !== null && stored.staleUntil > now) {
+    return { state: "stale-while-revalidate", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  if (stored.errorUntil !== null && stored.errorUntil > now) {
+    return { state: "stale-if-error", value: unwrapStoredValue(stored), stored, envelope: stored };
+  }
+  return { state: "expired", value: null, stored, envelope: stored };
+}
+function unwrapStoredValue(stored) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  if (stored.kind === "empty") {
+    return null;
+  }
+  return stored.value ?? null;
+}
+function remainingStoredTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return void 0;
+  }
+  const expiry = maxExpiry(stored);
+  if (expiry === null) {
+    return void 0;
+  }
+  const remainingMs = expiry - now;
+  if (remainingMs <= 0) {
+    return 1;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function remainingFreshTtlSeconds(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
+    return void 0;
+  }
+  const remainingMs = stored.freshUntil - now;
+  if (remainingMs <= 0) {
+    return 0;
+  }
+  return Math.max(1, Math.ceil(remainingMs / 1e3));
+}
+function refreshStoredEnvelope(stored, now = Date.now()) {
+  if (!isStoredValueEnvelope(stored)) {
+    return stored;
+  }
+  return createStoredValueEnvelope({
+    kind: stored.kind,
+    value: stored.value,
+    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
+    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
+    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
+    now
+  });
+}
+function maxExpiry(stored) {
+  const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
+    (value) => value !== null
+  );
+  if (values.length === 0) {
+    return null;
+  }
+  return Math.max(...values);
+}
+function normalizePositiveSeconds(value) {
+  if (!value || value <= 0) {
+    return void 0;
+  }
+  return value;
+}
+function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+  if (value == null) {
+    return true;
+  }
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+}
+
+// src/internal/CacheStackLayerWriter.ts
+var CacheStackLayerWriter = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async writeAcrossLayers(key, kind, value, writeOptions) {
+    const now = Date.now();
+    const clearEpoch = this.options.maintenance.currentClearEpoch();
+    const keyEpoch = this.options.maintenance.currentKeyEpoch(key);
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const layer of this.options.layers) {
+      const operation = async () => {
+        if (this.options.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
+          return;
+        }
+        if (this.options.shouldSkipLayer(layer)) {
+          return;
+        }
+        const entry = this.buildLayerSetEntry(layer, key, kind, value, writeOptions, now);
+        try {
+          await layer.set(entry.key, entry.value, entry.ttl);
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.options.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
+      }
+    }
+    await this.executeLayerOperations(immediateOperations, { key, action: kind === "empty" ? "negative-set" : "set" });
+    await Promise.all(deferredOperations.map((operation) => this.options.enqueueWriteBehind(operation)));
+  }
+  async writeBatch(entries) {
+    const now = Date.now();
+    const clearEpoch = this.options.maintenance.currentClearEpoch();
+    const entryEpochs = new Map(
+      entries.map((entry) => [entry.key, this.options.maintenance.currentKeyEpoch(entry.key)])
+    );
+    const entriesByLayer = /* @__PURE__ */ new Map();
+    const immediateOperations = [];
+    const deferredOperations = [];
+    for (const entry of entries) {
+      for (const layer of this.options.layers) {
+        if (this.options.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const layerEntry = this.buildLayerSetEntry(layer, entry.key, "value", entry.value, entry.options, now);
+        const bucket = entriesByLayer.get(layer) ?? [];
+        bucket.push(layerEntry);
+        entriesByLayer.set(layer, bucket);
+      }
+    }
+    for (const [layer, layerEntries] of entriesByLayer.entries()) {
+      const operation = async () => {
+        if (clearEpoch !== this.options.maintenance.currentClearEpoch()) {
+          return;
+        }
+        const activeEntries = layerEntries.filter(
+          (entry) => (entryEpochs.get(entry.key) ?? 0) === this.options.maintenance.currentKeyEpoch(entry.key)
+        );
+        if (activeEntries.length === 0) {
+          return;
+        }
+        try {
+          if (layer.setMany) {
+            await layer.setMany(activeEntries);
+            return;
+          }
+          await Promise.all(activeEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
+        } catch (error) {
+          await this.options.handleLayerFailure(layer, "write", error);
+        }
+      };
+      if (this.options.shouldWriteBehind(layer)) {
+        deferredOperations.push(operation);
+      } else {
+        immediateOperations.push(operation);
+      }
+    }
+    await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
+    await Promise.all(deferredOperations.map((operation) => this.options.enqueueWriteBehind(operation)));
+    return { clearEpoch, entryEpochs };
+  }
+  async executeLayerOperations(operations, context) {
+    if (this.options.writePolicy !== "best-effort") {
+      await Promise.all(operations.map((operation) => operation()));
+      return;
+    }
+    const results = await Promise.allSettled(operations.map((operation) => operation()));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length === 0) {
+      return;
+    }
+    this.options.onWriteFailures(
+      context,
+      failures.map((failure) => failure.reason)
+    );
+    if (failures.length === operations.length) {
+      throw new AggregateError(
+        failures.map((failure) => failure.reason),
+        `${context.action} failed for every cache layer`
+      );
+    }
+  }
+  buildLayerSetEntry(layer, key, kind, value, writeOptions, now) {
+    const freshTtl = this.options.resolveFreshTtl(key, layer.name, kind, writeOptions, layer.defaultTtl, value);
+    const staleWhileRevalidate = this.options.resolveLayerSeconds(
+      layer.name,
+      writeOptions?.staleWhileRevalidate,
+      this.options.globalStaleWhileRevalidate
+    );
+    const staleIfError = this.options.resolveLayerSeconds(
+      layer.name,
+      writeOptions?.staleIfError,
+      this.options.globalStaleIfError
+    );
+    const payload = createStoredValueEnvelope({
+      kind,
+      value,
+      freshTtlSeconds: freshTtl,
+      staleWhileRevalidateSeconds: staleWhileRevalidate,
+      staleIfErrorSeconds: staleIfError,
+      now
+    });
+    const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
+    return {
+      key,
+      value: payload,
+      ttl
+    };
+  }
+};
+
+// src/internal/CacheStackMaintenance.ts
+var CacheStackMaintenance = class {
+  keyEpochs = /* @__PURE__ */ new Map();
+  writeBehindQueue = [];
+  writeBehindTimer;
+  writeBehindFlushPromise;
+  generationCleanupPromise;
+  clearEpoch = 0;
+  initializeWriteBehindTimer(writeStrategy, options, flush) {
+    if (writeStrategy !== "write-behind") {
+      return;
+    }
+    const flushIntervalMs = options?.flushIntervalMs;
+    if (!flushIntervalMs || flushIntervalMs <= 0) {
+      return;
+    }
+    this.disposeWriteBehindTimer();
+    this.writeBehindTimer = setInterval(() => {
+      void flush();
+    }, flushIntervalMs);
+    this.writeBehindTimer.unref?.();
+  }
+  disposeWriteBehindTimer() {
+    if (!this.writeBehindTimer) {
+      return;
+    }
+    clearInterval(this.writeBehindTimer);
+    this.writeBehindTimer = void 0;
+  }
+  beginClearEpoch() {
+    this.clearEpoch += 1;
+    this.keyEpochs.clear();
+    this.writeBehindQueue.length = 0;
+  }
+  currentClearEpoch() {
+    return this.clearEpoch;
+  }
+  currentKeyEpoch(key) {
+    return this.keyEpochs.get(key) ?? 0;
+  }
+  bumpKeyEpochs(keys) {
+    for (const key of keys) {
+      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
+    }
+  }
+  isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
+    if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
+      return true;
+    }
+    if (expectedKeyEpoch !== void 0 && expectedKeyEpoch !== this.currentKeyEpoch(key)) {
+      return true;
+    }
+    return false;
+  }
+  async enqueueWriteBehind(operation, options, flushBatch) {
+    this.writeBehindQueue.push(operation);
+    const batchSize = options?.batchSize ?? 100;
+    const maxQueueSize = options?.maxQueueSize ?? batchSize * 10;
+    if (this.writeBehindQueue.length >= batchSize) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+      return;
+    }
+    if (this.writeBehindQueue.length >= maxQueueSize) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+    }
+  }
+  async flushWriteBehindQueue(options, flushBatch) {
+    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
+      await this.writeBehindFlushPromise;
+      return;
+    }
+    const batchSize = options?.batchSize ?? 100;
+    const batch = this.writeBehindQueue.splice(0, batchSize);
+    this.writeBehindFlushPromise = flushBatch(batch);
+    try {
+      await this.writeBehindFlushPromise;
+    } finally {
+      this.writeBehindFlushPromise = void 0;
+    }
+    if (this.writeBehindQueue.length > 0) {
+      await this.flushWriteBehindQueue(options, flushBatch);
+    }
+  }
+  scheduleGenerationCleanup(generation, task, onError) {
+    const scheduledTask = (this.generationCleanupPromise ?? Promise.resolve()).then(() => task(generation)).catch((error) => {
+      onError(generation, error);
+    });
+    this.generationCleanupPromise = scheduledTask.finally(() => {
+      if (this.generationCleanupPromise === scheduledTask) {
+        this.generationCleanupPromise = void 0;
+      }
+    });
+  }
+  async waitForGenerationCleanup() {
+    await this.generationCleanupPromise;
+  }
+};
+
+// src/internal/CacheStackRuntimePolicy.ts
+function shouldSkipLayer(degradedUntil, now = Date.now()) {
+  return degradedUntil !== void 0 && degradedUntil > now;
+}
+function shouldStartBackgroundRefresh({
+  isDisconnecting,
+  hasRefreshInFlight
+}) {
+  return !isDisconnecting && !hasRefreshInFlight;
+}
+function resolveRecoverableLayerFailure(gracefulDegradation, now = Date.now()) {
+  if (!gracefulDegradation) {
+    return { degrade: false };
+  }
+  const retryAfterMs = typeof gracefulDegradation === "object" ? gracefulDegradation.retryAfterMs ?? 1e4 : 1e4;
+  return {
+    degrade: true,
+    degradedUntil: now + retryAfterMs
+  };
+}
+function planFreshReadPolicies({
+  stored,
+  hasFetcher,
+  slidingTtl,
+  refreshAheadSeconds
+}) {
+  const refreshedStored = slidingTtl && isStoredValueEnvelope(stored) ? refreshStoredEnvelope(stored) : void 0;
+  const refreshedStoredTtl = refreshedStored ? remainingStoredTtlSeconds(refreshedStored) ?? void 0 : void 0;
+  const remainingFreshTtl = remainingFreshTtlSeconds(stored) ?? 0;
+  return {
+    refreshedStored,
+    refreshedStoredTtl,
+    shouldScheduleBackgroundRefresh: hasFetcher && refreshAheadSeconds > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAheadSeconds
+  };
+}
+
+// src/internal/CacheStackSnapshotManager.ts
+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));
+}
+async function findExistingAncestor(directory, fs3, path2) {
+  let current = directory;
+  while (true) {
+    try {
+      await fs3.lstat(current);
+      return current;
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    const parent = path2.dirname(current);
+    if (parent === current) {
+      return current;
+    }
+    current = parent;
+  }
+}
+async function validateSnapshotFilePath(filePath, mode, snapshotBaseDir, cwd = process.cwd()) {
+  if (filePath.length === 0) {
+    throw new Error("filePath must not be empty.");
+  }
+  if (filePath.includes("\0")) {
+    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);
+  if (baseDir === false) {
+    return resolved;
+  }
+  await fs3.mkdir(baseDir, { recursive: true });
+  const realBaseDir = await fs3.realpath(baseDir);
+  if (!isWithinSnapshotBase(realBaseDir, resolved, path2.sep, path2)) {
+    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)) {
+      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 realExistingAncestor = await fs3.realpath(existingAncestor);
+  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path2.sep, path2)) {
+    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)) {
+    throw new Error(`filePath is outside the allowed snapshot directory: ${realBaseDir}`);
+  }
+  const targetPath = path2.join(realParentDir, path2.basename(resolved));
+  try {
+    const existing = await fs3.lstat(targetPath);
+    if (existing.isSymbolicLink()) {
+      throw new Error("filePath must not point to a symbolic link.");
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  return targetPath;
+}
+async function readUtf8HandleWithLimit(handle, byteLimit) {
+  if (byteLimit === false) {
+    return handle.readFile({ encoding: "utf8" });
+  }
+  const chunks = [];
+  let totalBytes = 0;
+  let position = 0;
+  while (true) {
+    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, byteLimit - totalBytes + 1));
+    const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
+    if (bytesRead === 0) {
+      break;
+    }
+    totalBytes += bytesRead;
+    if (totalBytes > byteLimit) {
+      throw new Error(`Snapshot file exceeds snapshotMaxBytes limit (${totalBytes} bytes > ${byteLimit} bytes).`);
+    }
+    chunks.push(buffer.subarray(0, bytesRead));
+    position += bytesRead;
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/internal/CacheStackSnapshotManager.ts
+var DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE = 50;
+var CacheStackSnapshotManager = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async exportState(maxEntries) {
+    const entries = [];
+    await this.visitExportEntries(maxEntries, async (entry) => {
+      entries.push(entry);
+    });
+    return entries;
+  }
+  async importState(entries) {
+    const normalizedEntries = entries.map((entry) => ({
+      key: this.options.qualifyKey(this.options.validateCacheKey(entry.key)),
+      value: entry.value,
+      ttl: entry.ttl
+    }));
+    for (let index = 0; index < normalizedEntries.length; index += DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE) {
+      const batch = normalizedEntries.slice(index, index + DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE);
+      await Promise.all(
+        batch.map(async (entry) => {
+          await Promise.all(this.options.layers.map((layer) => layer.set(entry.key, entry.value, entry.ttl)));
+          await this.options.tagIndex.touch(entry.key);
+        })
+      );
+    }
+  }
+  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()}-${Math.random().toString(36).slice(2)}.tmp`
+    );
+    let handle;
+    try {
+      handle = await import_node_fs.promises.open(tempPath, "wx");
+      const openedHandle = handle;
+      await openedHandle.writeFile("[", "utf8");
+      let wroteAny = false;
+      await this.visitExportEntries(maxEntries, async (entry) => {
+        await openedHandle.writeFile(wroteAny ? ",\n" : "\n", "utf8");
+        await openedHandle.writeFile(JSON.stringify(entry, null, 2), "utf8");
+        wroteAny = true;
+      });
+      await openedHandle.writeFile(wroteAny ? "\n]" : "]", "utf8");
+      await openedHandle.close();
+      handle = void 0;
+      await import_node_fs.promises.rename(tempPath, targetPath);
+    } catch (error) {
+      await handle?.close().catch(() => void 0);
+      await import_node_fs.promises.unlink(tempPath).catch(() => void 0);
+      throw error;
+    }
+  }
+  async restoreFromFile(filePath, snapshotBaseDir, maxBytes) {
+    const validatedPath = await validateSnapshotFilePath(filePath, "read", snapshotBaseDir);
+    const handle = await import_node_fs.promises.open(validatedPath, import_node_fs.constants.O_RDONLY | (import_node_fs.constants.O_NOFOLLOW ?? 0));
+    let raw;
+    try {
+      if (maxBytes !== false) {
+        const stat = await handle.stat();
+        if (stat.size > maxBytes) {
+          throw new Error(`Snapshot file exceeds snapshotMaxBytes limit (${stat.size} bytes > ${maxBytes} bytes).`);
+        }
+      }
+      raw = await readUtf8HandleWithLimit(handle, maxBytes);
+    } finally {
+      await handle.close();
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (cause) {
+      throw new Error(`Invalid snapshot file: could not parse JSON (${this.options.formatError(cause)})`);
     }
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
+    if (!this.isCacheSnapshotEntries(parsed)) {
+      throw new Error("Invalid snapshot file: expected an array of { key: string, value, ttl? } entries");
     }
+    await this.importState(
+      parsed.map((entry) => ({
+        key: entry.key,
+        value: this.sanitizeSnapshotValue(entry.value),
+        ttl: entry.ttl
+      }))
+    );
   }
-  return targetPath;
-}
-async function readUtf8HandleWithLimit(handle, byteLimit) {
-  if (byteLimit === false) {
-    return handle.readFile({ encoding: "utf8" });
-  }
-  const chunks = [];
-  let totalBytes = 0;
-  let position = 0;
-  while (true) {
-    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, byteLimit - totalBytes + 1));
-    const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
-    if (bytesRead === 0) {
-      break;
-    }
-    totalBytes += bytesRead;
-    if (totalBytes > byteLimit) {
-      throw new Error(`Snapshot file exceeds snapshotMaxBytes limit (${totalBytes} bytes > ${byteLimit} bytes).`);
+  async visitExportEntries(maxEntries, visitor) {
+    const exported = /* @__PURE__ */ new Set();
+    for (const layer of this.options.layers) {
+      if (!layer.keys && !layer.forEachKey) {
+        continue;
+      }
+      const visitKey = async (key) => {
+        const exportedKey = this.options.stripQualifiedKey(key);
+        if (exported.has(exportedKey)) {
+          return;
+        }
+        const stored = await this.options.readLayerEntry(layer, key);
+        if (stored === null) {
+          return;
+        }
+        exported.add(exportedKey);
+        if (maxEntries !== false && exported.size > maxEntries) {
+          throw new Error(`Snapshot export exceeds snapshotMaxEntries limit (${exported.size} > ${maxEntries}).`);
+        }
+        await visitor({
+          key: exportedKey,
+          value: stored,
+          ttl: remainingStoredTtlSeconds(stored)
+        });
+      };
+      if (layer.forEachKey) {
+        await layer.forEachKey(visitKey);
+        continue;
+      }
+      const keys = await layer.keys?.();
+      for (const key of keys ?? []) {
+        await visitKey(key);
+      }
     }
-    chunks.push(buffer.subarray(0, bytesRead));
-    position += bytesRead;
   }
-  return Buffer.concat(chunks).toString("utf8");
-}
+  isCacheSnapshotEntries(value) {
+    return Array.isArray(value) && value.every((entry) => {
+      if (!entry || typeof entry !== "object") {
+        return false;
+      }
+      const candidate = entry;
+      return typeof candidate.key === "string" && (candidate.ttl === void 0 || typeof candidate.ttl === "number" && Number.isFinite(candidate.ttl) && candidate.ttl >= 0);
+    });
+  }
+  sanitizeSnapshotValue(value) {
+    return this.options.snapshotSerializer.deserialize(this.options.snapshotSerializer.serialize(value));
+  }
+};
 
 // src/internal/CacheStackValidation.ts
 var MAX_CACHE_KEY_LENGTH = 1024;
@@ -798,7 +1485,6 @@ var CircuitBreakerManager = class {
     if (!options) {
       return;
     }
-    this.pruneIfNeeded();
     const failureThreshold = options.failureThreshold ?? 3;
     const cooldownMs = options.cooldownMs ?? 3e4;
     const state = this.breakers.get(key) ?? { failures: 0, openUntil: null, createdAt: Date.now() };
@@ -807,6 +1493,7 @@ var CircuitBreakerManager = class {
       state.openUntil = Date.now() + cooldownMs;
     }
     this.breakers.set(key, state);
+    this.pruneIfNeeded();
   }
   recordSuccess(key) {
     this.breakers.delete(key);
@@ -872,7 +1559,11 @@ var FetchRateLimiter = class {
   fetcherBuckets = /* @__PURE__ */ new WeakMap();
   nextFetcherBucketId = 0;
   drainTimer;
+  isDisposed = false;
   async schedule(options, context, task) {
+    if (this.isDisposed) {
+      throw new Error("FetchRateLimiter has been disposed.");
+    }
     if (!options) {
       return task();
     }
@@ -895,6 +1586,27 @@ var FetchRateLimiter = class {
       this.drain();
     });
   }
+  dispose() {
+    this.isDisposed = true;
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = void 0;
+    }
+    for (const bucket of this.buckets.values()) {
+      if (bucket.cleanupTimer) {
+        clearTimeout(bucket.cleanupTimer);
+        bucket.cleanupTimer = void 0;
+      }
+    }
+    for (const queue of this.queuesByBucket.values()) {
+      for (const item of queue) {
+        item.reject(new Error("FetchRateLimiter has been disposed."));
+      }
+    }
+    this.queuesByBucket.clear();
+    this.pendingBuckets.clear();
+    this.buckets.clear();
+  }
   normalize(options) {
     const maxConcurrent = options.maxConcurrent;
     const intervalMs = options.intervalMs;
@@ -930,6 +1642,9 @@ var FetchRateLimiter = class {
     return "global";
   }
   drain() {
+    if (this.isDisposed) {
+      return;
+    }
     if (this.drainTimer) {
       clearTimeout(this.drainTimer);
       this.drainTimer = void 0;
@@ -1026,6 +1741,9 @@ var FetchRateLimiter = class {
     }
   }
   bucketState(bucketKey) {
+    if (this.isDisposed) {
+      throw new Error("FetchRateLimiter has been disposed.");
+    }
     const existing = this.buckets.get(bucketKey);
     if (existing) {
       return existing;
@@ -1150,164 +1868,6 @@ var MetricsCollector = class {
   }
 };
 
-// src/internal/StoredValue.ts
-function isStoredValueEnvelope(value) {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const v = value;
-  if (v.__layercache !== 1) {
-    return false;
-  }
-  if (v.kind !== "value" && v.kind !== "empty") {
-    return false;
-  }
-  if (v.freshUntil !== null && (!Number.isFinite(v.freshUntil) || typeof v.freshUntil !== "number")) {
-    return false;
-  }
-  if (v.staleUntil !== null && (!Number.isFinite(v.staleUntil) || typeof v.staleUntil !== "number")) {
-    return false;
-  }
-  if (v.errorUntil !== null && (!Number.isFinite(v.errorUntil) || typeof v.errorUntil !== "number")) {
-    return false;
-  }
-  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
-  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
-    return false;
-  }
-  if (typeof v.staleUntil === "number" && v.staleUntil > maxTimestamp) {
-    return false;
-  }
-  if (typeof v.errorUntil === "number" && v.errorUntil > maxTimestamp) {
-    return false;
-  }
-  if (v.freshUntil === null && (v.staleUntil !== null || v.errorUntil !== null)) {
-    return false;
-  }
-  if (typeof v.freshUntil === "number" && typeof v.staleUntil === "number" && v.staleUntil < v.freshUntil) {
-    return false;
-  }
-  if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
-    return false;
-  }
-  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
-  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
-    return false;
-  }
-  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
-    return false;
-  }
-  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
-    return false;
-  }
-  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
-    return false;
-  }
-  return true;
-}
-function createStoredValueEnvelope(options) {
-  const now = options.now ?? Date.now();
-  const freshTtlSeconds = normalizePositiveSeconds(options.freshTtlSeconds);
-  const staleWhileRevalidateSeconds = normalizePositiveSeconds(options.staleWhileRevalidateSeconds);
-  const staleIfErrorSeconds = normalizePositiveSeconds(options.staleIfErrorSeconds);
-  const freshUntil = freshTtlSeconds ? now + freshTtlSeconds * 1e3 : null;
-  const staleUntil = freshUntil && staleWhileRevalidateSeconds ? freshUntil + staleWhileRevalidateSeconds * 1e3 : null;
-  const errorUntil = freshUntil && staleIfErrorSeconds ? freshUntil + staleIfErrorSeconds * 1e3 : null;
-  return {
-    __layercache: 1,
-    kind: options.kind,
-    value: options.value,
-    freshUntil,
-    staleUntil,
-    errorUntil,
-    freshTtlSeconds: freshTtlSeconds ?? null,
-    staleWhileRevalidateSeconds: staleWhileRevalidateSeconds ?? null,
-    staleIfErrorSeconds: staleIfErrorSeconds ?? null
-  };
-}
-function resolveStoredValue(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return { state: "fresh", value: stored, stored };
-  }
-  if (stored.freshUntil === null || stored.freshUntil > now) {
-    return { state: "fresh", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  if (stored.staleUntil !== null && stored.staleUntil > now) {
-    return { state: "stale-while-revalidate", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  if (stored.errorUntil !== null && stored.errorUntil > now) {
-    return { state: "stale-if-error", value: unwrapStoredValue(stored), stored, envelope: stored };
-  }
-  return { state: "expired", value: null, stored, envelope: stored };
-}
-function unwrapStoredValue(stored) {
-  if (!isStoredValueEnvelope(stored)) {
-    return stored;
-  }
-  if (stored.kind === "empty") {
-    return null;
-  }
-  return stored.value ?? null;
-}
-function remainingStoredTtlSeconds(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return void 0;
-  }
-  const expiry = maxExpiry(stored);
-  if (expiry === null) {
-    return void 0;
-  }
-  const remainingMs = expiry - now;
-  if (remainingMs <= 0) {
-    return 1;
-  }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
-}
-function remainingFreshTtlSeconds(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored) || stored.freshUntil === null) {
-    return void 0;
-  }
-  const remainingMs = stored.freshUntil - now;
-  if (remainingMs <= 0) {
-    return 0;
-  }
-  return Math.max(1, Math.ceil(remainingMs / 1e3));
-}
-function refreshStoredEnvelope(stored, now = Date.now()) {
-  if (!isStoredValueEnvelope(stored)) {
-    return stored;
-  }
-  return createStoredValueEnvelope({
-    kind: stored.kind,
-    value: stored.value,
-    freshTtlSeconds: stored.freshTtlSeconds ?? void 0,
-    staleWhileRevalidateSeconds: stored.staleWhileRevalidateSeconds ?? void 0,
-    staleIfErrorSeconds: stored.staleIfErrorSeconds ?? void 0,
-    now
-  });
-}
-function maxExpiry(stored) {
-  const values = [stored.freshUntil, stored.staleUntil, stored.errorUntil].filter(
-    (value) => value !== null
-  );
-  if (values.length === 0) {
-    return null;
-  }
-  return Math.max(...values);
-}
-function normalizePositiveSeconds(value) {
-  if (!value || value <= 0) {
-    return void 0;
-  }
-  return value;
-}
-function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
-  if (value == null) {
-    return true;
-  }
-  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
-}
-
 // src/internal/TtlResolver.ts
 var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
 var TtlResolver = class {
@@ -1642,19 +2202,19 @@ var TagIndex = class {
     if (!this.knownKeys.delete(key)) {
       return;
     }
-    const path = [];
+    const path2 = [];
     let node = this.root;
     for (const character of key) {
       const child = node.children.get(character);
       if (!child) {
         return;
       }
-      path.push([node, character]);
+      path2.push([node, character]);
       node = child;
     }
     node.terminal = false;
-    for (let index = path.length - 1; index >= 0; index -= 1) {
-      const entry = path[index];
+    for (let index = path2.length - 1; index >= 0; index -= 1) {
+      const entry = path2[index];
       if (!entry) {
         continue;
       }
@@ -1668,39 +2228,31 @@ var TagIndex = class {
   }
 };
 
-// src/serialization/JsonSerializer.ts
-var DANGEROUS_JSON_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-var MAX_SANITIZE_NODES = 1e4;
-var JsonSerializer = class {
-  serialize(value) {
-    return JSON.stringify(value);
-  }
-  deserialize(payload) {
-    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    return sanitizeJsonValue(JSON.parse(normalized), 0, { count: 0 });
-  }
-};
-var MAX_SANITIZE_DEPTH = 200;
-function sanitizeJsonValue(value, depth, state) {
+// src/internal/StructuredDataSanitizer.ts
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function sanitizeStructuredData(value, options) {
+  return sanitizeValue(value, 0, { count: 0 }, options);
+}
+function sanitizeValue(value, depth, state, options) {
   state.count += 1;
-  if (state.count > MAX_SANITIZE_NODES) {
-    throw new Error(`JSON payload exceeds max node count of ${MAX_SANITIZE_NODES}.`);
+  if (state.count > options.maxNodes) {
+    throw new Error(`${options.label} exceeds max node count of ${options.maxNodes}.`);
   }
-  if (depth > MAX_SANITIZE_DEPTH) {
-    throw new Error(`JSON payload exceeds max depth of ${MAX_SANITIZE_DEPTH}.`);
+  if (depth > options.maxDepth) {
+    throw new Error(`${options.label} exceeds max depth of ${options.maxDepth}.`);
   }
   if (Array.isArray(value)) {
-    return value.map((entry) => sanitizeJsonValue(entry, depth + 1, state));
+    return value.map((entry) => sanitizeValue(entry, depth + 1, state, options));
   }
   if (!isPlainObject(value)) {
     return value;
   }
-  const sanitized = {};
+  const sanitized = options.createObject?.() ?? {};
   for (const [key, entry] of Object.entries(value)) {
-    if (DANGEROUS_JSON_KEYS.has(key)) {
+    if (DANGEROUS_KEYS.has(key)) {
       continue;
     }
-    sanitized[key] = sanitizeJsonValue(entry, depth + 1, state);
+    sanitized[key] = sanitizeValue(entry, depth + 1, state, options);
   }
   return sanitized;
 }
@@ -1708,6 +2260,21 @@ function isPlainObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
+// src/serialization/JsonSerializer.ts
+var JsonSerializer = class {
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  deserialize(payload) {
+    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
+    return sanitizeStructuredData(JSON.parse(normalized), {
+      label: "JSON payload",
+      maxDepth: 200,
+      maxNodes: 1e4
+    });
+  }
+};
+
 // src/stampede/StampedeGuard.ts
 var import_async_mutex2 = require("async-mutex");
 var StampedeGuard = class {
@@ -1752,7 +2319,6 @@ 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_SNAPSHOT_IMPORT_BATCH_SIZE = 50;
 var DEFAULT_INVALIDATION_MAX_KEYS = 1e4;
 var DEFAULT_MAX_PROFILE_ENTRIES = 1e5;
 var DebugLogger = class {
@@ -1809,6 +2375,35 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.handleLayerFailure(layer, operation, error);
       }
     });
+    this.invalidation = new CacheStackInvalidationSupport({
+      tagIndex: this.tagIndex,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      }
+    });
+    this.layerWriter = new CacheStackLayerWriter({
+      layers: this.layers,
+      maintenance: this.maintenance,
+      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
+      shouldWriteBehind: (layer) => this.shouldWriteBehind(layer),
+      handleLayerFailure: async (layer, operation, error) => {
+        await this.handleLayerFailure(layer, operation, error);
+      },
+      enqueueWriteBehind: this.enqueueWriteBehind.bind(this),
+      resolveFreshTtl: this.resolveFreshTtl.bind(this),
+      resolveLayerSeconds: this.resolveLayerSeconds.bind(this),
+      globalStaleWhileRevalidate: this.options.staleWhileRevalidate,
+      globalStaleIfError: this.options.staleIfError,
+      writePolicy: this.options.writePolicy,
+      onWriteFailures: (context, failures) => {
+        this.metricsCollector.increment("writeFailures", failures.length);
+        this.logger.debug?.("write-failure", {
+          ...context,
+          failures: failures.map((failure) => this.formatError(failure))
+        });
+      }
+    });
     if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
       this.logger.warn?.(
         "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
@@ -1824,6 +2419,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
         "broadcastL1Invalidation defaults to false when an invalidation bus is configured; opt in explicitly if write-triggered L1 invalidation is desired."
       );
     }
+    this.snapshots = new CacheStackSnapshotManager({
+      layers: this.layers,
+      tagIndex: this.tagIndex,
+      snapshotSerializer: this.snapshotSerializer,
+      readLayerEntry: this.readLayerEntry.bind(this),
+      qualifyKey: this.qualifyKey.bind(this),
+      stripQualifiedKey: this.stripQualifiedKey.bind(this),
+      validateCacheKey,
+      formatError: this.formatError.bind(this)
+    });
     this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
   }
@@ -1839,17 +2444,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
   keyDiscovery;
   fetchRateLimiter = new FetchRateLimiter();
   snapshotSerializer = new JsonSerializer();
+  invalidation;
+  layerWriter;
+  snapshots;
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
-  keyEpochs = /* @__PURE__ */ new Map();
+  maintenance = new CacheStackMaintenance();
   ttlResolver;
   circuitBreakerManager;
+  nextOperationId = 0;
   currentGeneration;
-  writeBehindQueue = [];
-  writeBehindTimer;
-  writeBehindFlushPromise;
-  generationCleanupPromise;
-  clearEpoch = 0;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -1859,10 +2463,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * and no `fetcher` is provided.
    */
   async get(key, fetcher, options) {
-    const normalizedKey = this.qualifyKey(validateCacheKey(key));
-    this.validateWriteOptions(options);
-    await this.awaitStartup("get");
-    return this.getPrepared(normalizedKey, fetcher, options);
+    return this.observeOperation("layercache.get", { "layercache.key": String(key ?? "") }, async () => {
+      const normalizedKey = this.qualifyKey(validateCacheKey(key));
+      this.validateWriteOptions(options);
+      await this.awaitStartup("get");
+      return this.getPrepared(normalizedKey, fetcher, options);
+    });
   }
   async getPrepared(normalizedKey, fetcher, options) {
     const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
@@ -1984,28 +2590,32 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * Stores a value in all cache layers. Overwrites any existing value.
    */
   async set(key, value, options) {
-    const normalizedKey = this.qualifyKey(validateCacheKey(key));
-    this.validateWriteOptions(options);
-    await this.awaitStartup("set");
-    await this.storeEntry(normalizedKey, "value", value, options);
+    await this.observeOperation("layercache.set", { "layercache.key": String(key ?? "") }, async () => {
+      const normalizedKey = this.qualifyKey(validateCacheKey(key));
+      this.validateWriteOptions(options);
+      await this.awaitStartup("set");
+      await this.storeEntry(normalizedKey, "value", value, options);
+    });
   }
   /**
    * Deletes the key from all layers and publishes an invalidation message.
    */
   async delete(key) {
-    const normalizedKey = this.qualifyKey(validateCacheKey(key));
-    await this.awaitStartup("delete");
-    await this.deleteKeys([normalizedKey]);
-    await this.publishInvalidation({
-      scope: "key",
-      keys: [normalizedKey],
-      sourceId: this.instanceId,
-      operation: "delete"
+    await this.observeOperation("layercache.delete", { "layercache.key": String(key ?? "") }, async () => {
+      const normalizedKey = this.qualifyKey(validateCacheKey(key));
+      await this.awaitStartup("delete");
+      await this.deleteKeys([normalizedKey]);
+      await this.publishInvalidation({
+        scope: "key",
+        keys: [normalizedKey],
+        sourceId: this.instanceId,
+        operation: "delete"
+      });
     });
   }
   async clear() {
     await this.awaitStartup("clear");
-    this.beginClearEpoch();
+    this.maintenance.beginClearEpoch();
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
     this.ttlResolver.clearProfiles();
@@ -2033,95 +2643,99 @@ var CacheStack = class extends import_node_events.EventEmitter {
     });
   }
   async mget(entries) {
-    this.assertActive("mget");
-    if (entries.length === 0) {
-      return [];
-    }
-    const normalizedEntries = entries.map((entry) => ({
-      ...entry,
-      key: this.qualifyKey(validateCacheKey(entry.key))
-    }));
-    normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
-    const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
-    if (!canFastPath) {
+    return this.observeOperation("layercache.mget", void 0, async () => {
+      this.assertActive("mget");
+      if (entries.length === 0) {
+        return [];
+      }
+      const normalizedEntries = entries.map((entry) => ({
+        ...entry,
+        key: this.qualifyKey(validateCacheKey(entry.key))
+      }));
+      normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
+      const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
+      if (!canFastPath) {
+        await this.awaitStartup("mget");
+        const pendingReads = /* @__PURE__ */ new Map();
+        return Promise.all(
+          normalizedEntries.map((entry) => {
+            const optionsSignature = serializeOptions(entry.options);
+            const existing = pendingReads.get(entry.key);
+            if (!existing) {
+              const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
+              pendingReads.set(entry.key, {
+                promise,
+                fetch: entry.fetch,
+                optionsSignature
+              });
+              return promise;
+            }
+            if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
+              throw new Error(`mget received conflicting entries for key "${entry.key}".`);
+            }
+            return existing.promise;
+          })
+        );
+      }
       await this.awaitStartup("mget");
-      const pendingReads = /* @__PURE__ */ new Map();
-      return Promise.all(
-        normalizedEntries.map((entry) => {
-          const optionsSignature = serializeOptions(entry.options);
-          const existing = pendingReads.get(entry.key);
-          if (!existing) {
-            const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
-            pendingReads.set(entry.key, {
-              promise,
-              fetch: entry.fetch,
-              optionsSignature
-            });
-            return promise;
-          }
-          if (existing.fetch !== entry.fetch || existing.optionsSignature !== optionsSignature) {
-            throw new Error(`mget received conflicting entries for key "${entry.key}".`);
-          }
-          return existing.promise;
-        })
-      );
-    }
-    await this.awaitStartup("mget");
-    const pending = /* @__PURE__ */ new Set();
-    const indexesByKey = /* @__PURE__ */ new Map();
-    const resultsByKey = /* @__PURE__ */ new Map();
-    for (let index = 0; index < normalizedEntries.length; index += 1) {
-      const entry = normalizedEntries[index];
-      if (!entry) continue;
-      const key = entry.key;
-      const indexes = indexesByKey.get(key) ?? [];
-      indexes.push(index);
-      indexesByKey.set(key, indexes);
-      pending.add(key);
-    }
-    for (let layerIndex = 0; layerIndex < this.layers.length; layerIndex += 1) {
-      const layer = this.layers[layerIndex];
-      if (!layer) continue;
-      const keys = [...pending];
-      if (keys.length === 0) {
-        break;
+      const pending = /* @__PURE__ */ new Set();
+      const indexesByKey = /* @__PURE__ */ new Map();
+      const resultsByKey = /* @__PURE__ */ new Map();
+      for (let index = 0; index < normalizedEntries.length; index += 1) {
+        const entry = normalizedEntries[index];
+        if (!entry) continue;
+        const key = entry.key;
+        const indexes = indexesByKey.get(key) ?? [];
+        indexes.push(index);
+        indexesByKey.set(key, indexes);
+        pending.add(key);
       }
-      const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
-      for (let offset = 0; offset < values.length; offset += 1) {
-        const key = keys[offset];
-        const stored = values[offset];
-        if (!key || stored === null) {
-          continue;
+      for (let layerIndex = 0; layerIndex < this.layers.length; layerIndex += 1) {
+        const layer = this.layers[layerIndex];
+        if (!layer) continue;
+        const keys = [...pending];
+        if (keys.length === 0) {
+          break;
         }
-        const resolved = resolveStoredValue(stored);
-        if (resolved.state === "expired") {
-          await layer.delete(key);
-          continue;
+        const values = layer.getMany ? await layer.getMany(keys) : await Promise.all(keys.map((key) => this.readLayerEntry(layer, key)));
+        for (let offset = 0; offset < values.length; offset += 1) {
+          const key = keys[offset];
+          const stored = values[offset];
+          if (!key || stored === null) {
+            continue;
+          }
+          const resolved = resolveStoredValue(stored);
+          if (resolved.state === "expired") {
+            await layer.delete(key);
+            continue;
+          }
+          await this.tagIndex.touch(key);
+          await this.backfill(key, stored, layerIndex - 1);
+          resultsByKey.set(key, resolved.value);
+          pending.delete(key);
+          this.metricsCollector.increment("hits", indexesByKey.get(key)?.length ?? 1);
         }
-        await this.tagIndex.touch(key);
-        await this.backfill(key, stored, layerIndex - 1);
-        resultsByKey.set(key, resolved.value);
-        pending.delete(key);
-        this.metricsCollector.increment("hits", indexesByKey.get(key)?.length ?? 1);
       }
-    }
-    if (pending.size > 0) {
-      for (const key of pending) {
-        await this.tagIndex.remove(key);
-        this.metricsCollector.increment("misses", indexesByKey.get(key)?.length ?? 1);
+      if (pending.size > 0) {
+        for (const key of pending) {
+          await this.tagIndex.remove(key);
+          this.metricsCollector.increment("misses", indexesByKey.get(key)?.length ?? 1);
+        }
       }
-    }
-    return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
+      return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
+    });
   }
   async mset(entries) {
-    this.assertActive("mset");
-    const normalizedEntries = entries.map((entry) => ({
-      ...entry,
-      key: this.qualifyKey(validateCacheKey(entry.key))
-    }));
-    normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
-    await this.awaitStartup("mset");
-    await this.writeBatch(normalizedEntries);
+    await this.observeOperation("layercache.mset", void 0, async () => {
+      this.assertActive("mset");
+      const normalizedEntries = entries.map((entry) => ({
+        ...entry,
+        key: this.qualifyKey(validateCacheKey(entry.key))
+      }));
+      normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
+      await this.awaitStartup("mset");
+      await this.writeBatch(normalizedEntries);
+    });
   }
   async warm(entries, options = {}) {
     this.assertActive("warm");
@@ -2174,40 +2788,50 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
-    validateTag(tag);
-    await this.awaitStartup("invalidateByTag");
-    const keys = await this.collectKeysForTag(tag);
-    await this.deleteKeys(keys);
-    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    await this.observeOperation("layercache.invalidate_by_tag", void 0, async () => {
+      validateTag(tag);
+      await this.awaitStartup("invalidateByTag");
+      const keys = await this.invalidation.collectKeysForTag(tag, this.invalidationMaxKeys());
+      await this.deleteKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    });
   }
   async invalidateByTags(tags, mode = "any") {
-    if (tags.length === 0) {
-      return;
-    }
-    validateTags(tags);
-    await this.awaitStartup("invalidateByTags");
-    const keysByTag = await Promise.all(tags.map((tag) => this.collectKeysForTag(tag)));
-    const keys = mode === "all" ? this.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
-    this.assertWithinInvalidationKeyLimit(keys.length);
-    await this.deleteKeys(keys);
-    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    await this.observeOperation("layercache.invalidate_by_tags", void 0, async () => {
+      if (tags.length === 0) {
+        return;
+      }
+      validateTags(tags);
+      await this.awaitStartup("invalidateByTags");
+      const keysByTag = await Promise.all(
+        tags.map((tag) => this.invalidation.collectKeysForTag(tag, this.invalidationMaxKeys()))
+      );
+      const keys = mode === "all" ? this.invalidation.intersectKeys(keysByTag) : [...new Set(keysByTag.flat())];
+      this.invalidation.assertWithinInvalidationKeyLimit(keys.length, this.invalidationMaxKeys());
+      await this.deleteKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    });
   }
   async invalidateByPattern(pattern) {
-    validatePattern(pattern);
-    await this.awaitStartup("invalidateByPattern");
-    const keys = await this.keyDiscovery.collectKeysMatchingPattern(
-      this.qualifyPattern(pattern),
-      this.invalidationMaxKeys()
-    );
-    await this.deleteKeys(keys);
-    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    await this.observeOperation("layercache.invalidate_by_pattern", void 0, async () => {
+      validatePattern(pattern);
+      await this.awaitStartup("invalidateByPattern");
+      const keys = await this.keyDiscovery.collectKeysMatchingPattern(
+        this.qualifyPattern(pattern),
+        this.invalidationMaxKeys()
+      );
+      await this.deleteKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    });
   }
   async invalidateByPrefix(prefix) {
-    await this.awaitStartup("invalidateByPrefix");
-    const qualifiedPrefix = this.qualifyKey(validateCacheKey(prefix));
-    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix, this.invalidationMaxKeys());
-    await this.deleteKeys(keys);
-    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    await this.observeOperation("layercache.invalidate_by_prefix", void 0, async () => {
+      await this.awaitStartup("invalidateByPrefix");
+      const qualifiedPrefix = this.qualifyKey(validateCacheKey(prefix));
+      const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix, this.invalidationMaxKeys());
+      await this.deleteKeys(keys);
+      await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+    });
   }
   getMetrics() {
     return this.metricsCollector.snapshot;
@@ -2263,9 +2887,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
   bumpGeneration(nextGeneration) {
     const current = this.currentGeneration ?? 0;
     const previousGeneration = this.currentGeneration;
-    this.currentGeneration = nextGeneration ?? current + 1;
-    if (previousGeneration !== void 0 && previousGeneration !== this.currentGeneration && this.shouldCleanupGenerations()) {
-      this.scheduleGenerationCleanup(previousGeneration);
+    const updatedGeneration = nextGeneration ?? current + 1;
+    const generationToCleanup = resolveGenerationCleanupTarget({
+      previousGeneration,
+      nextGeneration: updatedGeneration,
+      generationCleanup: this.options.generationCleanup
+    });
+    this.currentGeneration = updatedGeneration;
+    if (generationToCleanup !== null) {
+      this.scheduleGenerationCleanup(generationToCleanup);
     }
     return this.currentGeneration;
   }
@@ -2312,95 +2942,19 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async exportState() {
     await this.awaitStartup("exportState");
-    const entries = [];
-    await this.visitExportEntries(this.snapshotMaxEntries(), async (entry) => {
-      entries.push(entry);
-    });
-    return entries;
+    return this.snapshots.exportState(this.snapshotMaxEntries());
   }
   async importState(entries) {
     await this.awaitStartup("importState");
-    const normalizedEntries = entries.map((entry) => ({
-      key: this.qualifyKey(validateCacheKey(entry.key)),
-      value: entry.value,
-      ttl: entry.ttl
-    }));
-    for (let index = 0; index < normalizedEntries.length; index += DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE) {
-      const batch = normalizedEntries.slice(index, index + DEFAULT_SNAPSHOT_IMPORT_BATCH_SIZE);
-      await Promise.all(
-        batch.map(async (entry) => {
-          await Promise.all(this.layers.map((layer) => layer.set(entry.key, entry.value, entry.ttl)));
-          await this.tagIndex.touch(entry.key);
-        })
-      );
-    }
+    await this.snapshots.importState(entries);
   }
   async persistToFile(filePath) {
     this.assertActive("persistToFile");
-    const { promises: fs2 } = await import("fs");
-    const path = await import("path");
-    const targetPath = await validateSnapshotFilePath(filePath, "write", this.options.snapshotBaseDir);
-    const tempPath = path.join(
-      path.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`
-    );
-    let handle;
-    try {
-      handle = await fs2.open(tempPath, "wx");
-      const openedHandle = handle;
-      await openedHandle.writeFile("[", "utf8");
-      let wroteAny = false;
-      await this.visitExportEntries(this.snapshotMaxEntries(), async (entry) => {
-        await openedHandle.writeFile(wroteAny ? ",\n" : "\n", "utf8");
-        await openedHandle.writeFile(JSON.stringify(entry, null, 2), "utf8");
-        wroteAny = true;
-      });
-      await openedHandle.writeFile(wroteAny ? "\n]" : "]", "utf8");
-      await openedHandle.close();
-      handle = void 0;
-      await fs2.rename(tempPath, targetPath);
-    } catch (error) {
-      await handle?.close().catch(() => void 0);
-      await fs2.unlink(tempPath).catch(() => void 0);
-      throw error;
-    }
+    await this.snapshots.persistToFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxEntries());
   }
   async restoreFromFile(filePath) {
     this.assertActive("restoreFromFile");
-    const { promises: fs2, constants } = await import("fs");
-    const validatedPath = await validateSnapshotFilePath(filePath, "read", this.options.snapshotBaseDir);
-    const handle = await fs2.open(validatedPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const snapshotMaxBytes = this.snapshotMaxBytes();
-    let raw;
-    try {
-      if (snapshotMaxBytes !== false) {
-        const stat = await handle.stat();
-        if (stat.size > snapshotMaxBytes) {
-          throw new Error(
-            `Snapshot file exceeds snapshotMaxBytes limit (${stat.size} bytes > ${snapshotMaxBytes} bytes).`
-          );
-        }
-      }
-      raw = await readUtf8HandleWithLimit(handle, snapshotMaxBytes);
-    } finally {
-      await handle.close();
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (cause) {
-      throw new Error(`Invalid snapshot file: could not parse JSON (${this.formatError(cause)})`);
-    }
-    if (!this.isCacheSnapshotEntries(parsed)) {
-      throw new Error("Invalid snapshot file: expected an array of { key: string, value, ttl? } entries");
-    }
-    await this.importState(
-      parsed.map((entry) => ({
-        key: entry.key,
-        value: this.sanitizeSnapshotValue(entry.value),
-        ttl: entry.ttl
-      }))
-    );
+    await this.snapshots.restoreFromFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxBytes());
   }
   async disconnect() {
     if (!this.disconnectPromise) {
@@ -2409,12 +2963,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.startup;
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
-        await this.generationCleanupPromise;
+        await this.maintenance.waitForGenerationCleanup();
         await Promise.allSettled([...this.backgroundRefreshes.values()]);
-        if (this.writeBehindTimer) {
-          clearInterval(this.writeBehindTimer);
-          this.writeBehindTimer = void 0;
-        }
+        this.maintenance.disposeWriteBehindTimer();
+        this.fetchRateLimiter.dispose();
         await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
       })();
     }
@@ -2490,13 +3042,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
-      if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+      if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
         this.logger.debug?.("skip-negative-store-after-invalidation", {
           key,
           expectedClearEpoch,
-          clearEpoch: this.clearEpoch,
+          clearEpoch: this.maintenance.currentClearEpoch(),
           expectedKeyEpoch,
-          keyEpoch: this.currentKeyEpoch(key)
+          keyEpoch: this.maintenance.currentKeyEpoch(key)
         });
         return null;
       }
@@ -2512,13 +3064,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
         this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
       }
     }
-    if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+    if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
       this.logger.debug?.("skip-store-after-invalidation", {
         key,
         expectedClearEpoch,
-        clearEpoch: this.clearEpoch,
+        clearEpoch: this.maintenance.currentClearEpoch(),
         expectedKeyEpoch,
-        keyEpoch: this.currentKeyEpoch(key)
+        keyEpoch: this.maintenance.currentKeyEpoch(key)
       });
       return fetched;
     }
@@ -2526,10 +3078,10 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return fetched;
   }
   async storeEntry(key, kind, value, options) {
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
-    await this.writeAcrossLayers(key, kind, value, options);
-    if (this.isWriteOutdated(key, clearEpoch, keyEpoch)) {
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const keyEpoch = this.maintenance.currentKeyEpoch(key);
+    await this.layerWriter.writeAcrossLayers(key, kind, value, options);
+    if (this.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
       return;
     }
     if (options?.tags) {
@@ -2545,57 +3097,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
   }
   async writeBatch(entries) {
-    const now = Date.now();
-    const clearEpoch = this.clearEpoch;
-    const entryEpochs = new Map(entries.map((entry) => [entry.key, this.currentKeyEpoch(entry.key)]));
-    const entriesByLayer = /* @__PURE__ */ new Map();
-    const immediateOperations = [];
-    const deferredOperations = [];
-    for (const entry of entries) {
-      for (const layer of this.layers) {
-        if (this.shouldSkipLayer(layer)) {
-          continue;
-        }
-        const layerEntry = this.buildLayerSetEntry(layer, entry.key, "value", entry.value, entry.options, now);
-        const bucket = entriesByLayer.get(layer) ?? [];
-        bucket.push(layerEntry);
-        entriesByLayer.set(layer, bucket);
-      }
-    }
-    for (const [layer, layerEntries] of entriesByLayer.entries()) {
-      const operation = async () => {
-        if (clearEpoch !== this.clearEpoch) {
-          return;
-        }
-        const activeEntries = layerEntries.filter(
-          (entry) => (entryEpochs.get(entry.key) ?? 0) === this.currentKeyEpoch(entry.key)
-        );
-        if (activeEntries.length === 0) {
-          return;
-        }
-        try {
-          if (layer.setMany) {
-            await layer.setMany(activeEntries);
-            return;
-          }
-          await Promise.all(activeEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
-        } catch (error) {
-          await this.handleLayerFailure(layer, "write", error);
-        }
-      };
-      if (this.shouldWriteBehind(layer)) {
-        deferredOperations.push(operation);
-      } else {
-        immediateOperations.push(operation);
-      }
-    }
-    await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
-    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
-    if (clearEpoch !== this.clearEpoch) {
+    const { clearEpoch, entryEpochs } = await this.layerWriter.writeBatch(entries);
+    if (clearEpoch !== this.maintenance.currentClearEpoch()) {
       return;
     }
     for (const entry of entries) {
-      if (this.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
+      if (this.maintenance.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
         continue;
       }
       if (entry.options?.tags) {
@@ -2670,83 +3177,31 @@ var CacheStack = class extends import_node_events.EventEmitter {
         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 });
-    }
-  }
-  async writeAcrossLayers(key, kind, value, options) {
-    const now = Date.now();
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
-    const immediateOperations = [];
-    const deferredOperations = [];
-    for (const layer of this.layers) {
-      const operation = async () => {
-        if (this.isWriteOutdated(key, clearEpoch, keyEpoch)) {
-          return;
-        }
-        if (this.shouldSkipLayer(layer)) {
-          return;
-        }
-        const entry = this.buildLayerSetEntry(layer, key, kind, value, options, now);
-        try {
-          await layer.set(entry.key, entry.value, entry.ttl);
-        } catch (error) {
-          await this.handleLayerFailure(layer, "write", error);
-        }
-      };
-      if (this.shouldWriteBehind(layer)) {
-        deferredOperations.push(operation);
-      } else {
-        immediateOperations.push(operation);
-      }
-    }
-    await this.executeLayerOperations(immediateOperations, { key, action: kind === "empty" ? "negative-set" : "set" });
-    await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
-  }
-  async executeLayerOperations(operations, context) {
-    if (this.options.writePolicy !== "best-effort") {
-      await Promise.all(operations.map((operation) => operation()));
-      return;
+    try {
+      return await layer.get(key);
+    } catch (error) {
+      return this.handleLayerFailure(layer, "read", error);
     }
-    const results = await Promise.allSettled(operations.map((operation) => operation()));
-    const failures = results.filter((result) => result.status === "rejected");
-    if (failures.length === 0) {
+  }
+  async backfill(key, stored, upToIndex, options) {
+    if (upToIndex < 0) {
       return;
     }
-    this.metricsCollector.increment("writeFailures", failures.length);
-    this.logger.debug?.("write-failure", {
-      ...context,
-      failures: failures.map((failure) => this.formatError(failure.reason))
-    });
-    if (failures.length === operations.length) {
-      throw new AggregateError(
-        failures.map((failure) => failure.reason),
-        `${context.action} failed for every cache layer`
-      );
+    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) {
@@ -2768,11 +3223,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
   scheduleBackgroundRefresh(key, fetcher, options) {
-    if (this.isDisconnecting || this.backgroundRefreshes.has(key)) {
+    if (!shouldStartBackgroundRefresh({
+      isDisconnecting: this.isDisconnecting,
+      hasRefreshInFlight: this.backgroundRefreshes.has(key)
+    })) {
       return;
     }
-    const clearEpoch = this.clearEpoch;
-    const keyEpoch = this.currentKeyEpoch(key);
+    const clearEpoch = this.maintenance.currentClearEpoch();
+    const keyEpoch = this.maintenance.currentKeyEpoch(key);
     const refresh = (async () => {
       this.metricsCollector.increment("refreshes");
       try {
@@ -2810,8 +3268,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (keys.length === 0) {
       return;
     }
-    this.bumpKeyEpochs(keys);
-    await this.deleteKeysFromLayers(this.layers, keys);
+    this.maintenance.bumpKeyEpochs(keys);
+    await this.invalidation.deleteKeysFromLayers(this.layers, keys);
     for (const key of keys) {
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
@@ -2834,7 +3292,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     const localLayers = this.layers.filter((layer) => layer.isLocal);
     if (message.scope === "clear") {
-      this.beginClearEpoch();
+      this.maintenance.beginClearEpoch();
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
       this.ttlResolver.clearProfiles();
@@ -2842,8 +3300,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return;
     }
     const keys = message.keys ?? [];
-    this.bumpKeyEpochs(keys);
-    await this.deleteKeysFromLayers(localLayers, keys);
+    this.maintenance.bumpKeyEpochs(keys);
+    await this.invalidation.deleteKeysFromLayers(localLayers, keys);
     if (message.operation !== "write") {
       for (const key of keys) {
         await this.tagIndex.remove(key);
@@ -2900,35 +3358,47 @@ var CacheStack = class extends import_node_events.EventEmitter {
   shouldBroadcastL1Invalidation() {
     return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
   }
-  shouldCleanupGenerations() {
-    return Boolean(this.options.generationCleanup);
-  }
-  generationCleanupBatchSize() {
-    const configured = typeof this.options.generationCleanup === "object" ? this.options.generationCleanup.batchSize : void 0;
-    return configured ?? 500;
+  async observeOperation(name, attributes, execute) {
+    const id = this.nextOperationId;
+    this.nextOperationId += 1;
+    this.emit("operation-start", { id, name, attributes });
+    try {
+      const result = await execute();
+      this.emit("operation-end", {
+        id,
+        name,
+        attributes,
+        success: true,
+        result: result === null ? "null" : void 0
+      });
+      return result;
+    } catch (error) {
+      this.emit("operation-end", {
+        id,
+        name,
+        attributes,
+        success: false,
+        error
+      });
+      throw error;
+    }
   }
   scheduleGenerationCleanup(generation) {
-    const task = (this.generationCleanupPromise ?? Promise.resolve()).then(() => this.cleanupGeneration(generation)).catch((error) => {
-      this.logger.warn?.("generation-cleanup-error", {
-        generation,
-        error: this.formatError(error)
-      });
-    });
-    this.generationCleanupPromise = task.finally(() => {
-      if (this.generationCleanupPromise === task) {
-        this.generationCleanupPromise = void 0;
+    this.maintenance.scheduleGenerationCleanup(
+      generation,
+      async (generationToClean) => this.cleanupGeneration(generationToClean),
+      (failedGeneration, error) => {
+        this.logger.warn?.("generation-cleanup-error", {
+          generation: failedGeneration,
+          error: this.formatError(error)
+        });
       }
-    });
+    );
   }
   async cleanupGeneration(generation) {
     const prefix = `v${generation}:`;
     const keys = await this.keyDiscovery.collectKeysWithPrefix(prefix);
-    if (keys.length === 0) {
-      return;
-    }
-    const batchSize = this.generationCleanupBatchSize();
-    for (let index = 0; index < keys.length; index += batchSize) {
-      const batch = keys.slice(index, index + batchSize);
+    for (const batch of planGenerationCleanupBatches(keys, this.options.generationCleanup)) {
       await this.deleteKeys(batch);
       await this.publishInvalidation({
         scope: "keys",
@@ -2939,161 +3409,43 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
   }
   initializeWriteBehind(options) {
-    if (this.options.writeStrategy !== "write-behind") {
-      return;
-    }
-    const flushIntervalMs = options?.flushIntervalMs;
-    if (!flushIntervalMs || flushIntervalMs <= 0) {
-      return;
-    }
-    this.writeBehindTimer = setInterval(() => {
-      void this.flushWriteBehindQueue();
-    }, flushIntervalMs);
-    this.writeBehindTimer.unref?.();
+    this.maintenance.initializeWriteBehindTimer(
+      this.options.writeStrategy,
+      options,
+      this.flushWriteBehindQueue.bind(this)
+    );
   }
   shouldWriteBehind(layer) {
     return this.options.writeStrategy === "write-behind" && !layer.isLocal;
   }
-  beginClearEpoch() {
-    this.clearEpoch += 1;
-    this.keyEpochs.clear();
-    this.writeBehindQueue.length = 0;
-  }
-  currentKeyEpoch(key) {
-    return this.keyEpochs.get(key) ?? 0;
-  }
-  bumpKeyEpochs(keys) {
-    for (const key of keys) {
-      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
-    }
-  }
-  isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch) {
-    if (expectedClearEpoch !== void 0 && expectedClearEpoch !== this.clearEpoch) {
-      return true;
-    }
-    if (expectedKeyEpoch !== void 0 && expectedKeyEpoch !== this.currentKeyEpoch(key)) {
-      return true;
-    }
-    return false;
-  }
   async enqueueWriteBehind(operation) {
-    this.writeBehindQueue.push(operation);
-    const batchSize = this.options.writeBehind?.batchSize ?? 100;
-    const maxQueueSize = this.options.writeBehind?.maxQueueSize ?? batchSize * 10;
-    if (this.writeBehindQueue.length >= batchSize) {
-      await this.flushWriteBehindQueue();
-      return;
-    }
-    if (this.writeBehindQueue.length >= maxQueueSize) {
-      await this.flushWriteBehindQueue();
-    }
+    await this.maintenance.enqueueWriteBehind(operation, this.options.writeBehind, this.runWriteBehindBatch.bind(this));
   }
   async flushWriteBehindQueue() {
-    if (this.writeBehindFlushPromise || this.writeBehindQueue.length === 0) {
-      await this.writeBehindFlushPromise;
+    await this.maintenance.flushWriteBehindQueue(this.options.writeBehind, this.runWriteBehindBatch.bind(this));
+  }
+  async runWriteBehindBatch(batch) {
+    const results = await Promise.allSettled(batch.map((operation) => operation()));
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length === 0) {
       return;
     }
-    const batchSize = this.options.writeBehind?.batchSize ?? 100;
-    const batch = this.writeBehindQueue.splice(0, batchSize);
-    this.writeBehindFlushPromise = (async () => {
-      const results = await Promise.allSettled(batch.map((operation) => operation()));
-      const failures = results.filter((result) => result.status === "rejected");
-      if (failures.length > 0) {
-        this.metricsCollector.increment("writeFailures", failures.length);
-        this.logger.error?.("write-behind-flush-failure", {
-          failed: failures.length,
-          total: batch.length,
-          errors: failures.map((failure) => this.formatError(failure.reason))
-        });
-        this.emitError("write-behind", { failed: failures.length, total: batch.length });
-      }
-    })();
-    await this.writeBehindFlushPromise;
-    this.writeBehindFlushPromise = void 0;
-    if (this.writeBehindQueue.length > 0) {
-      await this.flushWriteBehindQueue();
-    }
-  }
-  buildLayerSetEntry(layer, key, kind, value, options, now) {
-    const freshTtl = this.resolveFreshTtl(key, layer.name, kind, options, layer.defaultTtl, value);
-    const staleWhileRevalidate = this.resolveLayerSeconds(
-      layer.name,
-      options?.staleWhileRevalidate,
-      this.options.staleWhileRevalidate
-    );
-    const staleIfError = this.resolveLayerSeconds(layer.name, options?.staleIfError, this.options.staleIfError);
-    const payload = createStoredValueEnvelope({
-      kind,
-      value,
-      freshTtlSeconds: freshTtl,
-      staleWhileRevalidateSeconds: staleWhileRevalidate,
-      staleIfErrorSeconds: staleIfError,
-      now
+    this.metricsCollector.increment("writeFailures", failures.length);
+    this.logger.error?.("write-behind-flush-failure", {
+      failed: failures.length,
+      total: batch.length,
+      errors: failures.map((failure) => this.formatError(failure.reason))
     });
-    const ttl = remainingStoredTtlSeconds(payload, now) ?? freshTtl;
-    return {
-      key,
-      value: payload,
-      ttl
-    };
-  }
-  intersectKeys(groups) {
-    if (groups.length === 0) {
-      return [];
-    }
-    const [firstGroup, ...rest] = groups;
-    if (!firstGroup) {
-      return [];
-    }
-    const restSets = rest.map((group) => new Set(group));
-    return [...new Set(firstGroup)].filter((key) => restSets.every((group) => group.has(key)));
+    this.emitError("write-behind", { failed: failures.length, total: batch.length });
   }
   qualifyKey(key) {
-    const prefix = this.generationPrefix();
-    return prefix ? `${prefix}${key}` : key;
+    return qualifyGenerationKey(key, this.currentGeneration);
   }
   qualifyPattern(pattern) {
-    const prefix = this.generationPrefix();
-    return prefix ? `${prefix}${pattern}` : pattern;
+    return qualifyGenerationPattern(pattern, this.currentGeneration);
   }
   stripQualifiedKey(key) {
-    const prefix = this.generationPrefix();
-    if (!prefix || !key.startsWith(prefix)) {
-      return key;
-    }
-    return key.slice(prefix.length);
-  }
-  generationPrefix() {
-    if (this.currentGeneration === void 0) {
-      return "";
-    }
-    return `v${this.currentGeneration}:`;
-  }
-  async deleteKeysFromLayers(layers, keys) {
-    await Promise.all(
-      layers.map(async (layer) => {
-        if (this.shouldSkipLayer(layer)) {
-          return;
-        }
-        if (layer.deleteMany) {
-          try {
-            await layer.deleteMany(keys);
-          } catch (error) {
-            await this.handleLayerFailure(layer, "delete", error);
-          }
-          return;
-        }
-        await Promise.all(
-          keys.map(async (key) => {
-            try {
-              await layer.delete(key);
-            } catch (error) {
-              await this.handleLayerFailure(layer, "delete", error);
-            }
-          })
-        );
-      })
-    );
+    return stripGenerationPrefix(key, this.currentGeneration);
   }
   validateConfiguration() {
     if (this.options.broadcastL1Invalidation !== void 0 && this.options.publishSetInvalidation !== void 0 && this.options.broadcastL1Invalidation !== this.options.publishSetInvalidation) {
@@ -3158,37 +3510,38 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.assertActive(operation);
   }
   async applyFreshReadPolicies(key, hit, options, fetcher) {
-    const refreshAhead = this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0;
-    const remainingFreshTtl = remainingFreshTtlSeconds(hit.stored) ?? 0;
-    if ((options?.slidingTtl ?? false) && isStoredValueEnvelope(hit.stored)) {
-      const refreshed = refreshStoredEnvelope(hit.stored);
-      const ttl = remainingStoredTtlSeconds(refreshed);
+    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, refreshed, ttl);
+          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
         } catch (error) {
           await this.handleLayerFailure(layer, "sliding-ttl", error);
         }
       }
     }
-    if (fetcher && refreshAhead > 0 && remainingFreshTtl > 0 && remainingFreshTtl <= refreshAhead) {
+    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
       this.scheduleBackgroundRefresh(key, fetcher, options);
     }
   }
   shouldSkipLayer(layer) {
-    const degradedUntil = this.layerDegradedUntil.get(layer.name);
-    return degradedUntil !== void 0 && degradedUntil > Date.now();
+    return shouldSkipLayer(this.layerDegradedUntil.get(layer.name));
   }
   async handleLayerFailure(layer, operation, error) {
-    if (!this.isGracefulDegradationEnabled()) {
+    const recovery = resolveRecoverableLayerFailure(this.options.gracefulDegradation);
+    if (!recovery.degrade) {
       throw error;
     }
-    const retryAfterMs = typeof this.options.gracefulDegradation === "object" ? this.options.gracefulDegradation.retryAfterMs ?? 1e4 : 1e4;
-    this.layerDegradedUntil.set(layer.name, Date.now() + retryAfterMs);
+    this.layerDegradedUntil.set(layer.name, recovery.degradedUntil);
     this.metricsCollector.increment("degradedOperations");
     this.logger.warn?.("layer-degraded", { layer: layer.name, operation, error: this.formatError(error) });
     this.emitError(operation, { layer: layer.name, degraded: true, error: this.formatError(error) });
@@ -3224,18 +3577,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
       this.emit("error", { operation, ...context });
     }
   }
-  isCacheSnapshotEntries(value) {
-    return Array.isArray(value) && value.every((entry) => {
-      if (!entry || typeof entry !== "object") {
-        return false;
-      }
-      const candidate = entry;
-      return typeof candidate.key === "string" && (candidate.ttl === void 0 || typeof candidate.ttl === "number" && Number.isFinite(candidate.ttl) && candidate.ttl >= 0);
-    });
-  }
-  sanitizeSnapshotValue(value) {
-    return this.snapshotSerializer.deserialize(this.snapshotSerializer.serialize(value));
-  }
   snapshotMaxBytes() {
     return this.options.snapshotMaxBytes === false ? false : this.options.snapshotMaxBytes ?? DEFAULT_SNAPSHOT_MAX_BYTES;
   }
@@ -3245,62 +3586,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
   invalidationMaxKeys() {
     return this.options.invalidationMaxKeys === false ? false : this.options.invalidationMaxKeys ?? DEFAULT_INVALIDATION_MAX_KEYS;
   }
-  async collectKeysForTag(tag) {
-    const keys = /* @__PURE__ */ new Set();
-    if (this.tagIndex.forEachKeyForTag) {
-      await this.tagIndex.forEachKeyForTag(tag, async (key) => {
-        keys.add(key);
-        this.assertWithinInvalidationKeyLimit(keys.size);
-      });
-      return [...keys];
-    }
-    for (const key of await this.tagIndex.keysForTag(tag)) {
-      keys.add(key);
-      this.assertWithinInvalidationKeyLimit(keys.size);
-    }
-    return [...keys];
-  }
-  assertWithinInvalidationKeyLimit(size) {
-    const maxKeys = this.invalidationMaxKeys();
-    if (maxKeys !== false && size > maxKeys) {
-      throw new Error(`Invalidation matched too many keys (${size} > ${maxKeys}).`);
-    }
-  }
-  async visitExportEntries(maxEntries, visitor) {
-    const exported = /* @__PURE__ */ new Set();
-    for (const layer of this.layers) {
-      if (!layer.keys && !layer.forEachKey) {
-        continue;
-      }
-      const visitKey = async (key) => {
-        const exportedKey = this.stripQualifiedKey(key);
-        if (exported.has(exportedKey)) {
-          return;
-        }
-        const stored = await this.readLayerEntry(layer, key);
-        if (stored === null) {
-          return;
-        }
-        exported.add(exportedKey);
-        if (maxEntries !== false && exported.size > maxEntries) {
-          throw new Error(`Snapshot export exceeds snapshotMaxEntries limit (${exported.size} > ${maxEntries}).`);
-        }
-        await visitor({
-          key: exportedKey,
-          value: stored,
-          ttl: remainingStoredTtlSeconds(stored)
-        });
-      };
-      if (layer.forEachKey) {
-        await layer.forEachKey(visitKey);
-        continue;
-      }
-      const keys = await layer.keys?.();
-      for (const key of keys ?? []) {
-        await visitKey(key);
-      }
-    }
-  }
 };
 
 // src/invalidation/RedisInvalidationBus.ts
@@ -3342,7 +3627,12 @@ var RedisInvalidationBus = class {
   async dispatchToHandlers(payload) {
     let message;
     try {
-      const parsed = sanitizeJsonValue2(JSON.parse(payload));
+      const parsed = sanitizeStructuredData(JSON.parse(payload), {
+        label: "Invalidation payload",
+        maxDepth: 64,
+        maxNodes: 1e4,
+        createObject: () => /* @__PURE__ */ Object.create(null)
+      });
       if (!this.isInvalidationMessage(parsed)) {
         throw new Error("Invalid invalidation payload shape.");
       }
@@ -3379,31 +3669,6 @@ var RedisInvalidationBus = class {
     console.error(`[layercache] ${message}`, error);
   }
 };
-var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-var MAX_SANITIZE_DEPTH2 = 64;
-var MAX_SANITIZE_NODES2 = 1e4;
-function sanitizeJsonValue2(value, depth = 0, state = { count: 0 }) {
-  state.count += 1;
-  if (state.count > MAX_SANITIZE_NODES2) {
-    throw new Error(`Invalidation payload exceeds max node count of ${MAX_SANITIZE_NODES2}.`);
-  }
-  if (depth > MAX_SANITIZE_DEPTH2) {
-    throw new Error(`Invalidation payload exceeds max depth of ${MAX_SANITIZE_DEPTH2}.`);
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => sanitizeJsonValue2(entry, depth + 1, state));
-  }
-  if (value && typeof value === "object") {
-    const result = /* @__PURE__ */ Object.create(null);
-    for (const key of Object.keys(value)) {
-      if (!DANGEROUS_KEYS.has(key)) {
-        result[key] = sanitizeJsonValue2(value[key], depth + 1, state);
-      }
-    }
-    return result;
-  }
-  return value;
-}
 
 // src/invalidation/RedisTagIndex.ts
 var RedisTagIndex = class {
@@ -3773,64 +4038,37 @@ function normalizeUrl2(url) {
 
 // src/integrations/opentelemetry.ts
 function createOpenTelemetryPlugin(cache, tracer) {
-  const originals = {
-    get: cache.get.bind(cache),
-    set: cache.set.bind(cache),
-    delete: cache.delete.bind(cache),
-    mget: cache.mget.bind(cache),
-    mset: cache.mset.bind(cache),
-    invalidateByTag: cache.invalidateByTag.bind(cache),
-    invalidateByTags: cache.invalidateByTags.bind(cache),
-    invalidateByPattern: cache.invalidateByPattern.bind(cache),
-    invalidateByPrefix: cache.invalidateByPrefix.bind(cache)
+  const spans = /* @__PURE__ */ new Map();
+  const onStart = (event) => {
+    spans.set(event.id, tracer.startSpan(event.name, { attributes: event.attributes }));
   };
-  cache.get = instrument("layercache.get", tracer, originals.get, (args) => ({
-    "layercache.key": String(args[0] ?? "")
-  }));
-  cache.set = instrument("layercache.set", tracer, originals.set, (args) => ({
-    "layercache.key": String(args[0] ?? "")
-  }));
-  cache.delete = instrument("layercache.delete", tracer, originals.delete, (args) => ({
-    "layercache.key": String(args[0] ?? "")
-  }));
-  cache.mget = instrument("layercache.mget", tracer, originals.mget);
-  cache.mset = instrument("layercache.mset", tracer, originals.mset);
-  cache.invalidateByTag = instrument("layercache.invalidate_by_tag", tracer, originals.invalidateByTag);
-  cache.invalidateByTags = instrument("layercache.invalidate_by_tags", tracer, originals.invalidateByTags);
-  cache.invalidateByPattern = instrument("layercache.invalidate_by_pattern", tracer, originals.invalidateByPattern);
-  cache.invalidateByPrefix = instrument("layercache.invalidate_by_prefix", tracer, originals.invalidateByPrefix);
-  return {
-    uninstall() {
-      cache.get = originals.get;
-      cache.set = originals.set;
-      cache.delete = originals.delete;
-      cache.mget = originals.mget;
-      cache.mset = originals.mset;
-      cache.invalidateByTag = originals.invalidateByTag;
-      cache.invalidateByTags = originals.invalidateByTags;
-      cache.invalidateByPattern = originals.invalidateByPattern;
-      cache.invalidateByPrefix = originals.invalidateByPrefix;
+  const onEnd = (event) => {
+    const span = spans.get(event.id);
+    if (!span) {
+      return;
+    }
+    spans.delete(event.id);
+    span.setAttribute?.("layercache.success", event.success);
+    if (event.result) {
+      span.setAttribute?.("layercache.result", event.result);
     }
+    if (event.error !== void 0) {
+      span.recordException?.(event.error);
+    }
+    span.end();
   };
-}
-function instrument(name, tracer, method, attributes) {
-  return (async (...args) => {
-    const span = tracer.startSpan(name, { attributes: attributes?.(args) });
-    try {
-      const result = await method(...args);
-      span.setAttribute?.("layercache.success", true);
-      if (result === null) {
-        span.setAttribute?.("layercache.result", "null");
+  cache.on("operation-start", onStart);
+  cache.on("operation-end", onEnd);
+  return {
+    uninstall() {
+      cache.off("operation-start", onStart);
+      cache.off("operation-end", onEnd);
+      for (const span of spans.values()) {
+        span.end();
       }
-      return result;
-    } catch (error) {
-      span.setAttribute?.("layercache.success", false);
-      span.recordException?.(error);
-      throw error;
-    } finally {
-      span.end();
+      spans.clear();
     }
-  });
+  };
 }
 
 // src/integrations/trpc.ts
@@ -4382,8 +4620,8 @@ var RedisLayer = class {
 
 // src/layers/DiskLayer.ts
 var import_node_crypto = require("crypto");
-var import_node_fs = require("fs");
-var import_node_path = require("path");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
 var FILE_SCAN_CONCURRENCY = 32;
 var DiskLayer = class {
   name;
@@ -4426,7 +4664,7 @@ var DiskLayer = class {
   }
   async set(key, value, ttl = this.defaultTtl) {
     await this.enqueueWrite(async () => {
-      await import_node_fs.promises.mkdir(this.directory, { recursive: true });
+      await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
       const entry = {
         key,
         value,
@@ -4436,8 +4674,8 @@ var DiskLayer = class {
       const targetPath = this.keyToPath(key);
       const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
       try {
-        await import_node_fs.promises.writeFile(tempPath, payload);
-        await import_node_fs.promises.rename(tempPath, targetPath);
+        await import_node_fs2.promises.writeFile(tempPath, payload);
+        await import_node_fs2.promises.rename(tempPath, targetPath);
       } catch (error) {
         await this.safeDelete(tempPath);
         throw error;
@@ -4491,12 +4729,12 @@ var DiskLayer = class {
     await this.enqueueWrite(async () => {
       let entries;
       try {
-        entries = await import_node_fs.promises.readdir(this.directory);
+        entries = await import_node_fs2.promises.readdir(this.directory);
       } catch {
         return;
       }
       await this.deletePathsWithConcurrency(
-        entries.filter((name) => name.endsWith(".lc")).map((name) => (0, import_node_path.join)(this.directory, name))
+        entries.filter((name) => name.endsWith(".lc")).map((name) => (0, import_node_path2.join)(this.directory, name))
       );
     });
   }
@@ -4525,7 +4763,7 @@ var DiskLayer = class {
   }
   async ping() {
     try {
-      await import_node_fs.promises.mkdir(this.directory, { recursive: true });
+      await import_node_fs2.promises.mkdir(this.directory, { recursive: true });
       return true;
     } catch {
       return false;
@@ -4535,7 +4773,7 @@ var DiskLayer = class {
   }
   keyToPath(key) {
     const hash = (0, import_node_crypto.createHash)("sha256").update(key).digest("hex");
-    return (0, import_node_path.join)(this.directory, `${hash}.lc`);
+    return (0, import_node_path2.join)(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
     if (typeof directory !== "string" || directory.trim().length === 0) {
@@ -4544,7 +4782,7 @@ var DiskLayer = class {
     if (directory.includes("\0")) {
       throw new Error("DiskLayer.directory must not contain null bytes.");
     }
-    return (0, import_node_path.resolve)(directory);
+    return (0, import_node_path2.resolve)(directory);
   }
   normalizeMaxFiles(maxFiles) {
     if (maxFiles === void 0) {
@@ -4568,7 +4806,7 @@ var DiskLayer = class {
   async readEntryFile(filePath) {
     let handle;
     try {
-      handle = await import_node_fs.promises.open(filePath, "r");
+      handle = await import_node_fs2.promises.open(filePath, "r");
       return await this.readHandleWithLimit(handle);
     } catch {
       await this.safeDelete(filePath);
@@ -4608,7 +4846,7 @@ var DiskLayer = class {
   async scanEntries(visitor) {
     let entries;
     try {
-      entries = await import_node_fs.promises.readdir(this.directory);
+      entries = await import_node_fs2.promises.readdir(this.directory);
     } catch {
       return;
     }
@@ -4624,7 +4862,7 @@ var DiskLayer = class {
           if (name === void 0) {
             return;
           }
-          const filePath = (0, import_node_path.join)(this.directory, name);
+          const filePath = (0, import_node_path2.join)(this.directory, name);
           const raw = await this.readEntryFile(filePath);
           if (raw === null) {
             continue;
@@ -4671,7 +4909,7 @@ var DiskLayer = class {
   }
   async safeDelete(filePath) {
     try {
-      await import_node_fs.promises.unlink(filePath);
+      await import_node_fs2.promises.unlink(filePath);
     } catch {
     }
   }
@@ -4689,7 +4927,7 @@ var DiskLayer = class {
     }
     let entries;
     try {
-      entries = await import_node_fs.promises.readdir(this.directory);
+      entries = await import_node_fs2.promises.readdir(this.directory);
     } catch {
       return;
     }
@@ -4699,9 +4937,9 @@ var DiskLayer = class {
     }
     const withStats = await Promise.all(
       lcFiles.map(async (name) => {
-        const filePath = (0, import_node_path.join)(this.directory, name);
+        const filePath = (0, import_node_path2.join)(this.directory, name);
         try {
-          const stat = await import_node_fs.promises.stat(filePath);
+          const stat = await import_node_fs2.promises.stat(filePath);
           return { filePath, mtimeMs: stat.mtimeMs };
         } catch {
           return { filePath, mtimeMs: 0 };
@@ -4797,44 +5035,19 @@ var MemcachedLayer = class {
 
 // src/serialization/MsgpackSerializer.ts
 var import_msgpack = require("@msgpack/msgpack");
-var DANGEROUS_KEYS2 = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-var MAX_SANITIZE_DEPTH3 = 64;
-var MAX_SANITIZE_NODES3 = 1e4;
 var MsgpackSerializer = class {
   serialize(value) {
     return Buffer.from((0, import_msgpack.encode)(value));
   }
   deserialize(payload) {
-    const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
-    return sanitizeMsgpackValue((0, import_msgpack.decode)(normalized), 0, { count: 0 });
+    const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "latin1");
+    return sanitizeStructuredData((0, import_msgpack.decode)(normalized), {
+      label: "MessagePack payload",
+      maxDepth: 64,
+      maxNodes: 1e4
+    });
   }
 };
-function sanitizeMsgpackValue(value, depth, state) {
-  state.count += 1;
-  if (state.count > MAX_SANITIZE_NODES3) {
-    throw new Error(`MessagePack payload exceeds max node count of ${MAX_SANITIZE_NODES3}.`);
-  }
-  if (depth > MAX_SANITIZE_DEPTH3) {
-    throw new Error(`MessagePack payload exceeds max depth of ${MAX_SANITIZE_DEPTH3}.`);
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => sanitizeMsgpackValue(entry, depth + 1, state));
-  }
-  if (!isPlainObject2(value)) {
-    return value;
-  }
-  const sanitized = {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (DANGEROUS_KEYS2.has(key)) {
-      continue;
-    }
-    sanitized[key] = sanitizeMsgpackValue(entry, depth + 1, state);
-  }
-  return sanitized;
-}
-function isPlainObject2(value) {
-  return Object.prototype.toString.call(value) === "[object Object]";
-}
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
 var import_node_crypto2 = require("crypto");