layercache 1.2.4 → 1.2.6

package/dist/index.cjs

@@ -66,22 +66,23 @@ var CacheNamespace = class _CacheNamespace {
   constructor(cache, prefix) {
     this.cache = cache;
     this.prefix = prefix;
+    validateNamespaceKey(prefix);
   }
   cache;
   prefix;
   static metricsMutexes = /* @__PURE__ */ new WeakMap();
   metrics = emptyMetrics();
   async get(key, fetcher, options) {
-    return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, options));
+    return this.trackMetrics(() => this.cache.get(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
   async getOrSet(key, fetcher, options) {
-    return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, options));
+    return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    */
   async getOrThrow(key, fetcher, options) {
-    return this.trackMetrics(() => this.cache.getOrThrow(this.qualify(key), fetcher, options));
+    return this.trackMetrics(() => this.cache.getOrThrow(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
   async has(key) {
     return this.trackMetrics(() => this.cache.has(this.qualify(key)));
@@ -90,7 +91,7 @@ var CacheNamespace = class _CacheNamespace {
     return this.trackMetrics(() => this.cache.ttl(this.qualify(key)));
   }
   async set(key, value, options) {
-    await this.trackMetrics(() => this.cache.set(this.qualify(key), value, options));
+    await this.trackMetrics(() => this.cache.set(this.qualify(key), value, this.qualifyWriteOptions(options)));
   }
   async delete(key) {
     await this.trackMetrics(() => this.cache.delete(this.qualify(key)));
@@ -106,7 +107,8 @@ var CacheNamespace = class _CacheNamespace {
       () => this.cache.mget(
         entries.map((entry) => ({
           ...entry,
-          key: this.qualify(entry.key)
+          key: this.qualify(entry.key),
+          options: this.qualifyGetOptions(entry.options)
         }))
       )
     );
@@ -116,16 +118,22 @@ var CacheNamespace = class _CacheNamespace {
       () => this.cache.mset(
         entries.map((entry) => ({
           ...entry,
-          key: this.qualify(entry.key)
+          key: this.qualify(entry.key),
+          options: this.qualifyWriteOptions(entry.options)
         }))
       )
     );
   }
   async invalidateByTag(tag) {
-    await this.trackMetrics(() => this.cache.invalidateByTag(tag));
+    await this.trackMetrics(() => this.cache.invalidateByTag(this.qualifyTag(tag)));
   }
   async invalidateByTags(tags, mode = "any") {
-    await this.trackMetrics(() => this.cache.invalidateByTags(tags, mode));
+    await this.trackMetrics(
+      () => this.cache.invalidateByTags(
+        tags.map((tag) => this.qualifyTag(tag)),
+        mode
+      )
+    );
   }
   async invalidateByPattern(pattern) {
     await this.trackMetrics(() => this.cache.invalidateByPattern(this.qualify(pattern)));
@@ -137,16 +145,24 @@ var CacheNamespace = class _CacheNamespace {
    * Returns detailed metadata about a single cache key within this namespace.
    */
   async inspect(key) {
-    return this.cache.inspect(this.qualify(key));
+    const result = await this.cache.inspect(this.qualify(key));
+    if (result === null) {
+      return null;
+    }
+    return {
+      ...result,
+      tags: result.tags.filter((tag) => tag.startsWith(`${this.prefix}:`)).map((tag) => tag.slice(this.prefix.length + 1))
+    };
   }
   wrap(keyPrefix, fetcher, options) {
-    return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, options);
+    return this.cache.wrap(`${this.prefix}:${keyPrefix}`, fetcher, this.qualifyWrapOptions(options));
   }
   warm(entries, options) {
     return this.cache.warm(
       entries.map((entry) => ({
         ...entry,
-        key: this.qualify(entry.key)
+        key: this.qualify(entry.key),
+        options: this.qualifyGetOptions(entry.options)
       })),
       options
     );
@@ -176,11 +192,30 @@ var CacheNamespace = class _CacheNamespace {
    * ```
    */
   namespace(childPrefix) {
+    validateNamespaceKey(childPrefix);
     return new _CacheNamespace(this.cache, `${this.prefix}:${childPrefix}`);
   }
   qualify(key) {
     return `${this.prefix}:${key}`;
   }
+  qualifyTag(tag) {
+    return `${this.prefix}:${tag}`;
+  }
+  qualifyGetOptions(options) {
+    return this.qualifyWriteOptions(options);
+  }
+  qualifyWrapOptions(options) {
+    return this.qualifyWriteOptions(options);
+  }
+  qualifyWriteOptions(options) {
+    if (!options?.tags || options.tags.length === 0) {
+      return options;
+    }
+    return {
+      ...options,
+      tags: options.tags.map((tag) => this.qualifyTag(tag))
+    };
+  }
   async trackMetrics(operation) {
     return this.getMetricsMutex().runExclusive(async () => {
       const before = this.cache.getMetrics();
@@ -305,6 +340,20 @@ function addMap(base, delta) {
   }
   return result;
 }
+function validateNamespaceKey(key) {
+  if (key.length === 0) {
+    throw new Error("Namespace prefix must not be empty.");
+  }
+  if (key.length > 256) {
+    throw new Error("Namespace prefix must be at most 256 characters.");
+  }
+  if (/[\u0000-\u001F\u007F]/.test(key)) {
+    throw new Error("Namespace prefix contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(key)) {
+    throw new Error("Namespace prefix contains unsupported surrogate code points.");
+  }
+}
 
 // src/invalidation/PatternMatcher.ts
 var PatternMatcher = class _PatternMatcher {
@@ -360,21 +409,41 @@ var CacheKeyDiscovery = class {
     this.options = options;
   }
   options;
-  async collectKeysWithPrefix(prefix) {
+  async collectKeysWithPrefix(prefix, maxMatches = false) {
     const { tagIndex } = this.options;
-    const matches = new Set(
-      tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`)
-    );
+    const matches = /* @__PURE__ */ new Set();
+    if (tagIndex.forEachKeyForPrefix) {
+      await tagIndex.forEachKeyForPrefix(prefix, async (key) => {
+        matches.add(key);
+        this.assertWithinMatchLimit(matches, maxMatches);
+      });
+    } else {
+      const initialMatches = tagIndex.keysForPrefix ? await tagIndex.keysForPrefix(prefix) : await tagIndex.matchPattern(`${prefix}*`);
+      for (const key of initialMatches) {
+        matches.add(key);
+        this.assertWithinMatchLimit(matches, maxMatches);
+      }
+    }
     await Promise.all(
       this.options.layers.map(async (layer) => {
-        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+        if (!layer.keys && !layer.forEachKey || this.options.shouldSkipLayer(layer)) {
           return;
         }
         try {
-          const keys = await layer.keys();
-          for (const key of keys) {
+          if (layer.forEachKey) {
+            await layer.forEachKey(async (key) => {
+              if (key.startsWith(prefix)) {
+                matches.add(key);
+                this.assertWithinMatchLimit(matches, maxMatches);
+              }
+            });
+            return;
+          }
+          const keys = await layer.keys?.();
+          for (const key of keys ?? []) {
             if (key.startsWith(prefix)) {
               matches.add(key);
+              this.assertWithinMatchLimit(matches, maxMatches);
             }
           }
         } catch (error) {
@@ -384,18 +453,39 @@ var CacheKeyDiscovery = class {
     );
     return [...matches];
   }
-  async collectKeysMatchingPattern(pattern) {
-    const matches = new Set(await this.options.tagIndex.matchPattern(pattern));
+  async collectKeysMatchingPattern(pattern, maxMatches = false) {
+    const matches = /* @__PURE__ */ new Set();
+    if (this.options.tagIndex.forEachKeyMatchingPattern) {
+      await this.options.tagIndex.forEachKeyMatchingPattern(pattern, async (key) => {
+        matches.add(key);
+        this.assertWithinMatchLimit(matches, maxMatches);
+      });
+    } else {
+      for (const key of await this.options.tagIndex.matchPattern(pattern)) {
+        matches.add(key);
+        this.assertWithinMatchLimit(matches, maxMatches);
+      }
+    }
     await Promise.all(
       this.options.layers.map(async (layer) => {
-        if (!layer.keys || this.options.shouldSkipLayer(layer)) {
+        if (!layer.keys && !layer.forEachKey || this.options.shouldSkipLayer(layer)) {
           return;
         }
         try {
-          const keys = await layer.keys();
-          for (const key of keys) {
+          if (layer.forEachKey) {
+            await layer.forEachKey(async (key) => {
+              if (PatternMatcher.matches(pattern, key)) {
+                matches.add(key);
+                this.assertWithinMatchLimit(matches, maxMatches);
+              }
+            });
+            return;
+          }
+          const keys = await layer.keys?.();
+          for (const key of keys ?? []) {
             if (PatternMatcher.matches(pattern, key)) {
               matches.add(key);
+              this.assertWithinMatchLimit(matches, maxMatches);
             }
           }
         } catch (error) {
@@ -405,8 +495,280 @@ var CacheKeyDiscovery = class {
     );
     return [...matches];
   }
+  assertWithinMatchLimit(matches, maxMatches) {
+    if (maxMatches !== false && matches.size > maxMatches) {
+      throw new Error(`Invalidation matched too many keys (${matches.size} > ${maxMatches}).`);
+    }
+  }
 };
 
+// src/internal/CacheKeySerialization.ts
+var DANGEROUS_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function normalizeForSerialization(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeForSerialization(entry));
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value).sort().reduce((normalized, key) => {
+      if (DANGEROUS_OBJECT_KEYS.has(key)) {
+        return normalized;
+      }
+      normalized[key] = normalizeForSerialization(value[key]);
+      return normalized;
+    }, {});
+  }
+  return value;
+}
+function serializeKeyPart(value) {
+  if (typeof value === "string") {
+    return `s:${value}`;
+  }
+  if (typeof value === "number") {
+    return `n:${value}`;
+  }
+  if (typeof value === "boolean") {
+    return `b:${value}`;
+  }
+  return `j:${JSON.stringify(normalizeForSerialization(value))}`;
+}
+function serializeOptions(options) {
+  return JSON.stringify(normalizeForSerialization(options) ?? null);
+}
+function createInstanceId() {
+  if (globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  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));
+}
+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;
+  }
+}
+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: 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;
+  }
+  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}`);
+  }
+  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;
+  }
+  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}`);
+  }
+  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}`);
+  }
+  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.");
+    }
+  } 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/CacheStackValidation.ts
+var MAX_CACHE_KEY_LENGTH = 1024;
+var MAX_PATTERN_LENGTH = 1024;
+var MAX_TAGS_PER_OPERATION = 128;
+function validatePositiveNumber(name, value) {
+  if (value === void 0) {
+    return;
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive finite number.`);
+  }
+}
+function validateNonNegativeNumber(name, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative finite number.`);
+  }
+}
+function validateLayerNumberOption(name, value) {
+  if (value === void 0) {
+    return;
+  }
+  if (typeof value === "number") {
+    validateNonNegativeNumber(name, value);
+    return;
+  }
+  for (const [layerName, layerValue] of Object.entries(value)) {
+    if (layerValue === void 0) {
+      continue;
+    }
+    validateNonNegativeNumber(`${name}.${layerName}`, layerValue);
+  }
+}
+function validateRateLimitOptions(name, options) {
+  if (!options) {
+    return;
+  }
+  validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
+  validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
+  validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
+  if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+    throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
+  }
+  if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
+    throw new Error(`${name}.bucketKey must not be empty.`);
+  }
+}
+function validateCacheKey(key) {
+  if (key.length === 0) {
+    throw new Error("Cache key must not be empty.");
+  }
+  if (key.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache key length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(key)) {
+    throw new Error("Cache key contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(key)) {
+    throw new Error("Cache key contains unsupported surrogate code points.");
+  }
+  return key;
+}
+function validateTag(tag) {
+  if (tag.length === 0) {
+    throw new Error("Cache tag must not be empty.");
+  }
+  if (tag.length > MAX_CACHE_KEY_LENGTH) {
+    throw new Error(`Cache tag length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported control characters.");
+  }
+  if (/[\uD800-\uDFFF]/.test(tag)) {
+    throw new Error("Cache tag contains unsupported surrogate code points.");
+  }
+  return tag;
+}
+function validateTags(tags) {
+  if (!tags) {
+    return;
+  }
+  if (tags.length > MAX_TAGS_PER_OPERATION) {
+    throw new Error(`options.tags must contain at most ${MAX_TAGS_PER_OPERATION} tags.`);
+  }
+  for (const tag of tags) {
+    validateTag(tag);
+  }
+}
+function validatePattern(pattern) {
+  if (pattern.length === 0) {
+    throw new Error("Pattern must not be empty.");
+  }
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Pattern length must be at most ${MAX_PATTERN_LENGTH} characters.`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(pattern)) {
+    throw new Error("Pattern contains unsupported control characters.");
+  }
+}
+function validateTtlPolicy(name, policy) {
+  if (!policy || typeof policy === "function" || policy === "until-midnight" || policy === "next-hour") {
+    return;
+  }
+  if ("alignTo" in policy) {
+    validatePositiveNumber(`${name}.alignTo`, policy.alignTo);
+    return;
+  }
+  throw new Error(`${name} is invalid.`);
+}
+function validateAdaptiveTtlOptions(options) {
+  if (!options || options === true) {
+    return;
+  }
+  validatePositiveNumber("adaptiveTtl.hotAfter", options.hotAfter);
+  validateLayerNumberOption("adaptiveTtl.step", options.step);
+  validateLayerNumberOption("adaptiveTtl.maxTtl", options.maxTtl);
+}
+function validateCircuitBreakerOptions(options) {
+  if (!options) {
+    return;
+  }
+  validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
+  validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
+}
+
 // src/internal/CircuitBreakerManager.ts
 var CircuitBreakerManager = class {
   breakers = /* @__PURE__ */ new Map();
@@ -425,9 +787,7 @@ var CircuitBreakerManager = class {
     }
     const now = Date.now();
     if (state.openUntil <= now) {
-      state.openUntil = null;
-      state.failures = 0;
-      this.breakers.set(key, state);
+      this.breakers.delete(key);
       return;
     }
     const remainingMs = state.openUntil - now;
@@ -438,15 +798,15 @@ 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 };
+    const state = this.breakers.get(key) ?? { failures: 0, openUntil: null, createdAt: Date.now() };
     state.failures += 1;
     if (state.failures >= failureThreshold) {
       state.openUntil = Date.now() + cooldownMs;
     }
     this.breakers.set(key, state);
-    this.pruneIfNeeded();
   }
   recordSuccess(key) {
     this.breakers.delete(key);
@@ -457,8 +817,7 @@ var CircuitBreakerManager = class {
       return false;
     }
     if (state.openUntil <= Date.now()) {
-      state.openUntil = null;
-      state.failures = 0;
+      this.breakers.delete(key);
       return false;
     }
     return true;
@@ -482,15 +841,20 @@ var CircuitBreakerManager = class {
     if (this.breakers.size <= this.maxEntries) {
       return;
     }
+    const now = Date.now();
     for (const [key, state] of this.breakers.entries()) {
       if (this.breakers.size <= this.maxEntries) {
-        break;
+        return;
       }
-      if (!state.openUntil || state.openUntil <= Date.now()) {
+      if (!state.openUntil || state.openUntil <= now) {
         this.breakers.delete(key);
       }
     }
-    for (const key of this.breakers.keys()) {
+    if (this.breakers.size <= this.maxEntries) {
+      return;
+    }
+    const sorted = [...this.breakers.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    for (const [key] of sorted) {
       if (this.breakers.size <= this.maxEntries) {
         break;
       }
@@ -500,6 +864,7 @@ var CircuitBreakerManager = class {
 };
 
 // src/internal/FetchRateLimiter.ts
+var MAX_BUCKETS = 1e4;
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -665,10 +1030,25 @@ var FetchRateLimiter = class {
     if (existing) {
       return existing;
     }
+    if (this.buckets.size >= MAX_BUCKETS) {
+      this.evictIdleBuckets();
+    }
     const bucket = { active: 0, startedAt: [] };
     this.buckets.set(bucketKey, bucket);
     return bucket;
   }
+  evictIdleBuckets() {
+    for (const [key, bucket] of this.buckets.entries()) {
+      if (this.buckets.size <= MAX_BUCKETS * 0.9) {
+        break;
+      }
+      if (bucket.active === 0 && bucket.startedAt.length === 0 && !this.queuesByBucket.has(key)) {
+        this.buckets.delete(key);
+        this.queuesByBucket.delete(key);
+        this.pendingBuckets.delete(key);
+      }
+    }
+  }
   cleanupBucket(bucketKey, bucket, intervalMs) {
     const queued = this.queuesByBucket.get(bucketKey)?.length ?? 0;
     if (queued === 0 && bucket.active === 0 && bucket.startedAt.length === 0) {
@@ -782,19 +1162,47 @@ function isStoredValueEnvelope(value) {
   if (v.kind !== "value" && v.kind !== "empty") {
     return false;
   }
-  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+  if (v.freshUntil !== null && (!Number.isFinite(v.freshUntil) || typeof v.freshUntil !== "number")) {
     return false;
   }
-  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+  if (v.staleUntil !== null && (!Number.isFinite(v.staleUntil) || typeof v.staleUntil !== "number")) {
     return false;
   }
-  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+  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) {
@@ -893,6 +1301,12 @@ function normalizePositiveSeconds(value) {
   }
   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;
@@ -995,18 +1409,18 @@ var TtlResolver = class {
       return;
     }
     const toRemove = Math.ceil(this.maxProfileEntries * 0.1);
-    let removed = 0;
-    for (const key of this.accessProfiles.keys()) {
-      if (removed >= toRemove) {
-        break;
+    const sorted = [...this.accessProfiles.entries()].sort((a, b) => a[1].lastAccessAt - b[1].lastAccessAt);
+    for (let i = 0; i < toRemove && i < sorted.length; i++) {
+      const entry = sorted[i];
+      if (entry) {
+        this.accessProfiles.delete(entry[0]);
       }
-      this.accessProfiles.delete(key);
-      removed += 1;
     }
   }
 };
 
 // src/invalidation/TagIndex.ts
+var MAX_PATTERN_RECURSION_DEPTH = 500;
 var TagIndex = class {
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
@@ -1047,6 +1461,11 @@ var TagIndex = class {
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  async forEachKeyForTag(tag, visitor) {
+    for (const key of this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()) {
+      await visitor(key);
+    }
+  }
   async keysForPrefix(prefix) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -1056,14 +1475,27 @@ var TagIndex = class {
     this.collectFromNode(node, prefix, matches);
     return matches;
   }
+  async forEachKeyForPrefix(prefix, visitor) {
+    const node = this.findNode(prefix);
+    if (!node) {
+      return;
+    }
+    await this.visitFromNode(node, prefix, visitor);
+  }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
   async matchPattern(pattern) {
     const matches = /* @__PURE__ */ new Set();
-    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set());
+    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
     return [...matches];
   }
+  async forEachKeyMatchingPattern(pattern, visitor) {
+    const matches = await this.matchPattern(pattern);
+    for (const key of matches) {
+      await visitor(key);
+    }
+  }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
@@ -1113,7 +1545,18 @@ var TagIndex = class {
       this.collectFromNode(child, `${prefix}${character}`, matches);
     }
   }
-  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited) {
+  async visitFromNode(node, prefix, visitor) {
+    if (node.terminal) {
+      await visitor(prefix);
+    }
+    for (const [character, child] of node.children) {
+      await this.visitFromNode(child, `${prefix}${character}`, visitor);
+    }
+  }
+  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited, depth) {
+    if (depth > MAX_PATTERN_RECURSION_DEPTH) {
+      return;
+    }
     const stateKey = `${node.id}:${patternIndex}`;
     if (visited.has(stateKey)) {
       return;
@@ -1130,21 +1573,37 @@ var TagIndex = class {
       return;
     }
     if (patternChar === "*") {
-      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited);
+      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited, depth + 1);
       for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited);
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited, depth + 1);
       }
       return;
     }
     if (patternChar === "?") {
       for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex + 1, matches, visited);
+        this.collectPatternMatches(
+          child2,
+          `${prefix}${character}`,
+          pattern,
+          patternIndex + 1,
+          matches,
+          visited,
+          depth + 1
+        );
       }
       return;
     }
     const child = node.children.get(patternChar);
     if (child) {
-      this.collectPatternMatches(child, `${prefix}${patternChar}`, pattern, patternIndex + 1, matches, visited);
+      this.collectPatternMatches(
+        child,
+        `${prefix}${patternChar}`,
+        pattern,
+        patternIndex + 1,
+        matches,
+        visited,
+        depth + 1
+      );
     }
   }
   pruneKnownKeysIfNeeded() {
@@ -1211,22 +1670,27 @@ 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);
+    return sanitizeJsonValue(JSON.parse(normalized), 0, { count: 0 });
   }
 };
 var MAX_SANITIZE_DEPTH = 200;
-function sanitizeJsonValue(value, depth) {
+function sanitizeJsonValue(value, depth, state) {
+  state.count += 1;
+  if (state.count > MAX_SANITIZE_NODES) {
+    throw new Error(`JSON payload exceeds max node count of ${MAX_SANITIZE_NODES}.`);
+  }
   if (depth > MAX_SANITIZE_DEPTH) {
-    return value;
+    throw new Error(`JSON payload exceeds max depth of ${MAX_SANITIZE_DEPTH}.`);
   }
   if (Array.isArray(value)) {
-    return value.map((entry) => sanitizeJsonValue(entry, depth + 1));
+    return value.map((entry) => sanitizeJsonValue(entry, depth + 1, state));
   }
   if (!isPlainObject(value)) {
     return value;
@@ -1236,7 +1700,7 @@ function sanitizeJsonValue(value, depth) {
     if (DANGEROUS_JSON_KEYS.has(key)) {
       continue;
     }
-    sanitized[key] = sanitizeJsonValue(entry, depth + 1);
+    sanitized[key] = sanitizeJsonValue(entry, depth + 1, state);
   }
   return sanitized;
 }
@@ -1286,9 +1750,11 @@ var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
 var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
-var MAX_CACHE_KEY_LENGTH = 1024;
+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 DANGEROUS_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 var DebugLogger = class {
   enabled;
   constructor(enabled) {
@@ -1375,6 +1841,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
+  keyEpochs = /* @__PURE__ */ new Map();
   ttlResolver;
   circuitBreakerManager;
   currentGeneration;
@@ -1382,6 +1849,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   writeBehindTimer;
   writeBehindFlushPromise;
   generationCleanupPromise;
+  clearEpoch = 0;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -1391,7 +1859,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * and no `fetcher` is provided.
    */
   async get(key, fetcher, options) {
-    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    const normalizedKey = this.qualifyKey(validateCacheKey(key));
     this.validateWriteOptions(options);
     await this.awaitStartup("get");
     return this.getPrepared(normalizedKey, fetcher, options);
@@ -1461,7 +1929,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * Returns true if the given key exists and is not expired in any layer.
    */
   async has(key) {
-    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    const normalizedKey = this.qualifyKey(validateCacheKey(key));
     await this.awaitStartup("has");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
@@ -1494,7 +1962,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * that has it, or null if the key is not found / has no TTL.
    */
   async ttl(key) {
-    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    const normalizedKey = this.qualifyKey(validateCacheKey(key));
     await this.awaitStartup("ttl");
     for (const layer of this.layers) {
       if (this.shouldSkipLayer(layer)) {
@@ -1516,7 +1984,7 @@ 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(this.validateCacheKey(key));
+    const normalizedKey = this.qualifyKey(validateCacheKey(key));
     this.validateWriteOptions(options);
     await this.awaitStartup("set");
     await this.storeEntry(normalizedKey, "value", value, options);
@@ -1525,7 +1993,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * Deletes the key from all layers and publishes an invalidation message.
    */
   async delete(key) {
-    const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
+    const normalizedKey = this.qualifyKey(validateCacheKey(key));
     await this.awaitStartup("delete");
     await this.deleteKeys([normalizedKey]);
     await this.publishInvalidation({
@@ -1537,6 +2005,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async clear() {
     await this.awaitStartup("clear");
+    this.beginClearEpoch();
     await Promise.all(this.layers.map((layer) => layer.clear()));
     await this.tagIndex.clear();
     this.ttlResolver.clearProfiles();
@@ -1553,7 +2022,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return;
     }
     await this.awaitStartup("mdelete");
-    const normalizedKeys = keys.map((k) => this.validateCacheKey(k));
+    const normalizedKeys = keys.map((k) => validateCacheKey(k));
     const cacheKeys = normalizedKeys.map((key) => this.qualifyKey(key));
     await this.deleteKeys(cacheKeys);
     await this.publishInvalidation({
@@ -1570,7 +2039,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.qualifyKey(this.validateCacheKey(entry.key))
+      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);
@@ -1579,7 +2048,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
       const pendingReads = /* @__PURE__ */ new Map();
       return Promise.all(
         normalizedEntries.map((entry) => {
-          const optionsSignature = this.serializeOptions(entry.options);
+          const optionsSignature = serializeOptions(entry.options);
           const existing = pendingReads.get(entry.key);
           if (!existing) {
             const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
@@ -1648,7 +2117,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.assertActive("mset");
     const normalizedEntries = entries.map((entry) => ({
       ...entry,
-      key: this.qualifyKey(this.validateCacheKey(entry.key))
+      key: this.qualifyKey(validateCacheKey(entry.key))
     }));
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
     await this.awaitStartup("mset");
@@ -1691,7 +2160,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    */
   wrap(prefix, fetcher, options = {}) {
     return (...args) => {
-      const suffix = options.keyResolver ? options.keyResolver(...args) : args.map((argument) => this.serializeKeyPart(argument)).join(":");
+      const suffix = options.keyResolver ? options.keyResolver(...args) : args.map((argument) => serializeKeyPart(argument)).join(":");
       const key = suffix.length > 0 ? `${prefix}:${suffix}` : prefix;
       return this.get(key, () => fetcher(...args), options);
     };
@@ -1701,11 +2170,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * `prefix:`. Useful for multi-tenant or module-level isolation.
    */
   namespace(prefix) {
+    validateNamespaceKey(prefix);
     return new CacheNamespace(this, prefix);
   }
   async invalidateByTag(tag) {
+    validateTag(tag);
     await this.awaitStartup("invalidateByTag");
-    const keys = await this.tagIndex.keysForTag(tag);
+    const keys = await this.collectKeysForTag(tag);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -1713,22 +2184,28 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (tags.length === 0) {
       return;
     }
+    validateTags(tags);
     await this.awaitStartup("invalidateByTags");
-    const keysByTag = await Promise.all(tags.map((tag) => this.tagIndex.keysForTag(tag)));
+    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" });
   }
   async invalidateByPattern(pattern) {
+    validatePattern(pattern);
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.keyDiscovery.collectKeysMatchingPattern(this.qualifyPattern(pattern));
+    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(this.validateCacheKey(prefix));
-    const keys = await this.keyDiscovery.collectKeysWithPrefix(qualifiedPrefix);
+    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" });
   }
@@ -1798,7 +2275,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
    * Returns `null` if the key does not exist in any layer.
    */
   async inspect(key) {
-    const userKey = this.validateCacheKey(key);
+    const userKey = validateCacheKey(key);
     const normalizedKey = this.qualifyKey(userKey);
     await this.awaitStartup("inspect");
     const foundInLayers = [];
@@ -1835,50 +2312,79 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async exportState() {
     await this.awaitStartup("exportState");
-    const exported = /* @__PURE__ */ new Map();
-    for (const layer of this.layers) {
-      if (!layer.keys) {
-        continue;
-      }
-      const keys = await layer.keys();
-      for (const key of keys) {
-        const exportedKey = this.stripQualifiedKey(key);
-        if (exported.has(exportedKey)) {
-          continue;
-        }
-        const stored = await this.readLayerEntry(layer, key);
-        if (stored === null) {
-          continue;
-        }
-        exported.set(exportedKey, {
-          key: exportedKey,
-          value: stored,
-          ttl: remainingStoredTtlSeconds(stored)
-        });
-      }
-    }
-    return [...exported.values()];
+    const entries = [];
+    await this.visitExportEntries(this.snapshotMaxEntries(), async (entry) => {
+      entries.push(entry);
+    });
+    return entries;
   }
   async importState(entries) {
     await this.awaitStartup("importState");
-    await Promise.all(
-      entries.map(async (entry) => {
-        const qualifiedKey = this.qualifyKey(entry.key);
-        await Promise.all(this.layers.map((layer) => layer.set(qualifiedKey, entry.value, entry.ttl)));
-        await this.tagIndex.touch(qualifiedKey);
-      })
-    );
+    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);
+        })
+      );
+    }
   }
   async persistToFile(filePath) {
     this.assertActive("persistToFile");
-    const snapshot = await this.exportState();
     const { promises: fs2 } = await import("fs");
-    await fs2.writeFile(await this.validateSnapshotFilePath(filePath), JSON.stringify(snapshot, null, 2), "utf8");
+    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;
+    }
   }
   async restoreFromFile(filePath) {
     this.assertActive("restoreFromFile");
-    const { promises: fs2 } = await import("fs");
-    const raw = await fs2.readFile(await this.validateSnapshotFilePath(filePath), "utf8");
+    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);
@@ -1922,14 +2428,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.handleInvalidationMessage(message);
     });
   }
-  async fetchWithGuards(key, fetcher, options) {
+  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
     const fetchTask = async () => {
       const secondHit = await this.readFromLayers(key, options, "fresh-only");
       if (secondHit.found) {
         this.metricsCollector.increment("hits");
         return secondHit.value;
       }
-      return this.fetchAndPopulate(key, fetcher, options);
+      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
     };
     const singleFlightTask = async () => {
       if (!this.options.singleFlightCoordinator) {
@@ -1939,7 +2445,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         key,
         this.resolveSingleFlightOptions(),
         fetchTask,
-        () => this.waitForFreshValue(key, fetcher, options)
+        () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
       );
     };
     if (this.options.stampedePrevention === false) {
@@ -1947,7 +2453,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     return this.stampedeGuard.execute(key, singleFlightTask);
   }
-  async waitForFreshValue(key, fetcher, options) {
+  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
     const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
     const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
     const deadline = Date.now() + timeoutMs;
@@ -1961,9 +2467,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
       }
       await this.sleep(pollIntervalMs);
     }
-    return this.fetchAndPopulate(key, fetcher, options);
+    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
   }
-  async fetchAndPopulate(key, fetcher, options) {
+  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
     this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
     this.metricsCollector.increment("fetches");
     const fetchStart = Date.now();
@@ -1984,6 +2490,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
+      if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+        this.logger.debug?.("skip-negative-store-after-invalidation", {
+          key,
+          expectedClearEpoch,
+          clearEpoch: this.clearEpoch,
+          expectedKeyEpoch,
+          keyEpoch: this.currentKeyEpoch(key)
+        });
+        return null;
+      }
       await this.storeEntry(key, "empty", null, options);
       return null;
     }
@@ -1996,11 +2512,26 @@ var CacheStack = class extends import_node_events.EventEmitter {
         this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
       }
     }
+    if (this.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
+      this.logger.debug?.("skip-store-after-invalidation", {
+        key,
+        expectedClearEpoch,
+        clearEpoch: this.clearEpoch,
+        expectedKeyEpoch,
+        keyEpoch: this.currentKeyEpoch(key)
+      });
+      return fetched;
+    }
     await this.storeEntry(key, "value", fetched, options);
     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)) {
+      return;
+    }
     if (options?.tags) {
       await this.tagIndex.track(key, options.tags);
     } else {
@@ -2015,6 +2546,8 @@ 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 = [];
@@ -2031,12 +2564,21 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     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(layerEntries);
+            await layer.setMany(activeEntries);
             return;
           }
-          await Promise.all(layerEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
+          await Promise.all(activeEntries.map((entry) => layer.set(entry.key, entry.value, entry.ttl)));
         } catch (error) {
           await this.handleLayerFailure(layer, "write", error);
         }
@@ -2049,7 +2591,13 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
     await this.executeLayerOperations(immediateOperations, { key: "batch", action: "mset" });
     await Promise.all(deferredOperations.map((operation) => this.enqueueWriteBehind(operation)));
+    if (clearEpoch !== this.clearEpoch) {
+      return;
+    }
     for (const entry of entries) {
+      if (this.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
+        continue;
+      }
       if (entry.options?.tags) {
         await this.tagIndex.track(entry.key, entry.options.tags);
       } else {
@@ -2151,10 +2699,15 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   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;
         }
@@ -2218,10 +2771,12 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (this.isDisconnecting || this.backgroundRefreshes.has(key)) {
       return;
     }
+    const clearEpoch = this.clearEpoch;
+    const keyEpoch = this.currentKeyEpoch(key);
     const refresh = (async () => {
       this.metricsCollector.increment("refreshes");
       try {
-        await this.runBackgroundRefresh(key, fetcher, options);
+        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
       } catch (error) {
         this.metricsCollector.increment("refreshErrors");
         this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
@@ -2231,14 +2786,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
     })();
     this.backgroundRefreshes.set(key, refresh);
   }
-  async runBackgroundRefresh(key, fetcher, options) {
+  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
     const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
     await this.fetchWithGuards(
       key,
       () => this.withTimeout(fetcher(), timeoutMs, () => {
         return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
       }),
-      options
+      options,
+      expectedClearEpoch,
+      expectedKeyEpoch
     );
   }
   resolveSingleFlightOptions() {
@@ -2253,6 +2810,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (keys.length === 0) {
       return;
     }
+    this.bumpKeyEpochs(keys);
     await this.deleteKeysFromLayers(this.layers, keys);
     for (const key of keys) {
       await this.tagIndex.remove(key);
@@ -2275,21 +2833,22 @@ var CacheStack = class extends import_node_events.EventEmitter {
       return;
     }
     const localLayers = this.layers.filter((layer) => layer.isLocal);
-    if (localLayers.length === 0) {
-      return;
-    }
     if (message.scope === "clear") {
+      this.beginClearEpoch();
       await Promise.all(localLayers.map((layer) => layer.clear()));
       await this.tagIndex.clear();
       this.ttlResolver.clearProfiles();
+      this.circuitBreakerManager.clear();
       return;
     }
     const keys = message.keys ?? [];
+    this.bumpKeyEpochs(keys);
     await this.deleteKeysFromLayers(localLayers, keys);
     if (message.operation !== "write") {
       for (const key of keys) {
         await this.tagIndex.remove(key);
         this.ttlResolver.deleteProfile(key);
+        this.circuitBreakerManager.delete(key);
       }
     }
   }
@@ -2395,6 +2954,28 @@ var CacheStack = class extends import_node_events.EventEmitter {
   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;
@@ -2521,107 +3102,50 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (this.options.stampedePrevention === false && this.options.singleFlightCoordinator) {
       throw new Error("singleFlightCoordinator requires stampedePrevention to remain enabled.");
     }
-    this.validateLayerNumberOption("negativeTtl", this.options.negativeTtl);
-    this.validateLayerNumberOption("staleWhileRevalidate", this.options.staleWhileRevalidate);
-    this.validateLayerNumberOption("staleIfError", this.options.staleIfError);
-    this.validateLayerNumberOption("ttlJitter", this.options.ttlJitter);
-    this.validateLayerNumberOption("refreshAhead", this.options.refreshAhead);
-    this.validatePositiveNumber("singleFlightLeaseMs", this.options.singleFlightLeaseMs);
-    this.validatePositiveNumber("singleFlightTimeoutMs", this.options.singleFlightTimeoutMs);
-    this.validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
-    this.validatePositiveNumber("singleFlightRenewIntervalMs", this.options.singleFlightRenewIntervalMs);
-    this.validatePositiveNumber("backgroundRefreshTimeoutMs", this.options.backgroundRefreshTimeoutMs);
-    this.validateRateLimitOptions("fetcherRateLimit", this.options.fetcherRateLimit);
-    this.validateAdaptiveTtlOptions(this.options.adaptiveTtl);
-    this.validateCircuitBreakerOptions(this.options.circuitBreaker);
+    validateLayerNumberOption("negativeTtl", this.options.negativeTtl);
+    validateLayerNumberOption("staleWhileRevalidate", this.options.staleWhileRevalidate);
+    validateLayerNumberOption("staleIfError", this.options.staleIfError);
+    validateLayerNumberOption("ttlJitter", this.options.ttlJitter);
+    validateLayerNumberOption("refreshAhead", this.options.refreshAhead);
+    validatePositiveNumber("singleFlightLeaseMs", this.options.singleFlightLeaseMs);
+    validatePositiveNumber("singleFlightTimeoutMs", this.options.singleFlightTimeoutMs);
+    validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
+    validatePositiveNumber("singleFlightRenewIntervalMs", this.options.singleFlightRenewIntervalMs);
+    validatePositiveNumber("backgroundRefreshTimeoutMs", this.options.backgroundRefreshTimeoutMs);
+    if (this.options.snapshotMaxBytes !== false) {
+      validatePositiveNumber("snapshotMaxBytes", this.options.snapshotMaxBytes);
+    }
+    if (this.options.snapshotMaxEntries !== false) {
+      validatePositiveNumber("snapshotMaxEntries", this.options.snapshotMaxEntries);
+    }
+    if (this.options.invalidationMaxKeys !== false) {
+      validatePositiveNumber("invalidationMaxKeys", this.options.invalidationMaxKeys);
+    }
+    validateRateLimitOptions("fetcherRateLimit", this.options.fetcherRateLimit);
+    validateAdaptiveTtlOptions(this.options.adaptiveTtl);
+    validateCircuitBreakerOptions(this.options.circuitBreaker);
     if (typeof this.options.generationCleanup === "object") {
-      this.validatePositiveNumber("generationCleanup.batchSize", this.options.generationCleanup.batchSize);
+      validatePositiveNumber("generationCleanup.batchSize", this.options.generationCleanup.batchSize);
     }
     if (this.options.generation !== void 0) {
-      this.validateNonNegativeNumber("generation", this.options.generation);
+      validateNonNegativeNumber("generation", this.options.generation);
     }
   }
   validateWriteOptions(options) {
     if (!options) {
       return;
     }
-    this.validateLayerNumberOption("options.ttl", options.ttl);
-    this.validateLayerNumberOption("options.negativeTtl", options.negativeTtl);
-    this.validateLayerNumberOption("options.staleWhileRevalidate", options.staleWhileRevalidate);
-    this.validateLayerNumberOption("options.staleIfError", options.staleIfError);
-    this.validateLayerNumberOption("options.ttlJitter", options.ttlJitter);
-    this.validateLayerNumberOption("options.refreshAhead", options.refreshAhead);
-    this.validateTtlPolicy("options.ttlPolicy", options.ttlPolicy);
-    this.validateAdaptiveTtlOptions(options.adaptiveTtl);
-    this.validateCircuitBreakerOptions(options.circuitBreaker);
-    this.validateRateLimitOptions("options.fetcherRateLimit", options.fetcherRateLimit);
-  }
-  validateLayerNumberOption(name, value) {
-    if (value === void 0) {
-      return;
-    }
-    if (typeof value === "number") {
-      this.validateNonNegativeNumber(name, value);
-      return;
-    }
-    for (const [layerName, layerValue] of Object.entries(value)) {
-      if (layerValue === void 0) {
-        continue;
-      }
-      this.validateNonNegativeNumber(`${name}.${layerName}`, layerValue);
-    }
-  }
-  validatePositiveNumber(name, value) {
-    if (value === void 0) {
-      return;
-    }
-    if (!Number.isFinite(value) || value <= 0) {
-      throw new Error(`${name} must be a positive finite number.`);
-    }
-  }
-  validateRateLimitOptions(name, options) {
-    if (!options) {
-      return;
-    }
-    this.validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
-    this.validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
-    this.validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
-    if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
-      throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
-    }
-    if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
-      throw new Error(`${name}.bucketKey must not be empty.`);
-    }
-  }
-  validateNonNegativeNumber(name, value) {
-    if (!Number.isFinite(value) || value < 0) {
-      throw new Error(`${name} must be a non-negative finite number.`);
-    }
-  }
-  validateCacheKey(key) {
-    if (key.length === 0) {
-      throw new Error("Cache key must not be empty.");
-    }
-    if (key.length > MAX_CACHE_KEY_LENGTH) {
-      throw new Error(`Cache key length must be at most ${MAX_CACHE_KEY_LENGTH} characters.`);
-    }
-    if (/[\u0000-\u001F\u007F]/.test(key)) {
-      throw new Error("Cache key contains unsupported control characters.");
-    }
-    if (/[\uD800-\uDFFF]/.test(key)) {
-      throw new Error("Cache key contains unsupported surrogate code points.");
-    }
-    return key;
-  }
-  validateTtlPolicy(name, policy) {
-    if (!policy || typeof policy === "function" || policy === "until-midnight" || policy === "next-hour") {
-      return;
-    }
-    if ("alignTo" in policy) {
-      this.validatePositiveNumber(`${name}.alignTo`, policy.alignTo);
-      return;
-    }
-    throw new Error(`${name} is invalid.`);
+    validateLayerNumberOption("options.ttl", options.ttl);
+    validateLayerNumberOption("options.negativeTtl", options.negativeTtl);
+    validateLayerNumberOption("options.staleWhileRevalidate", options.staleWhileRevalidate);
+    validateLayerNumberOption("options.staleIfError", options.staleIfError);
+    validateLayerNumberOption("options.ttlJitter", options.ttlJitter);
+    validateLayerNumberOption("options.refreshAhead", options.refreshAhead);
+    validateTtlPolicy("options.ttlPolicy", options.ttlPolicy);
+    validateAdaptiveTtlOptions(options.adaptiveTtl);
+    validateCircuitBreakerOptions(options.circuitBreaker);
+    validateRateLimitOptions("options.fetcherRateLimit", options.fetcherRateLimit);
+    validateTags(options.tags);
   }
   assertActive(operation) {
     if (this.isDisconnecting) {
@@ -2633,24 +3157,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
     await this.startup;
     this.assertActive(operation);
   }
-  serializeOptions(options) {
-    return JSON.stringify(this.normalizeForSerialization(options) ?? null);
-  }
-  validateAdaptiveTtlOptions(options) {
-    if (!options || options === true) {
-      return;
-    }
-    this.validatePositiveNumber("adaptiveTtl.hotAfter", options.hotAfter);
-    this.validateLayerNumberOption("adaptiveTtl.step", options.step);
-    this.validateLayerNumberOption("adaptiveTtl.maxTtl", options.maxTtl);
-  }
-  validateCircuitBreakerOptions(options) {
-    if (!options) {
-      return;
-    }
-    this.validatePositiveNumber("circuitBreaker.failureThreshold", options.failureThreshold);
-    this.validatePositiveNumber("circuitBreaker.cooldownMs", options.cooldownMs);
-  }
   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;
@@ -2718,18 +3224,6 @@ var CacheStack = class extends import_node_events.EventEmitter {
       this.emit("error", { operation, ...context });
     }
   }
-  serializeKeyPart(value) {
-    if (typeof value === "string") {
-      return `s:${value}`;
-    }
-    if (typeof value === "number") {
-      return `n:${value}`;
-    }
-    if (typeof value === "boolean") {
-      return `b:${value}`;
-    }
-    return `j:${JSON.stringify(this.normalizeForSerialization(value))}`;
-  }
   isCacheSnapshotEntries(value) {
     return Array.isArray(value) && value.every((entry) => {
       if (!entry || typeof entry !== "object") {
@@ -2742,43 +3236,72 @@ var CacheStack = class extends import_node_events.EventEmitter {
   sanitizeSnapshotValue(value) {
     return this.snapshotSerializer.deserialize(this.snapshotSerializer.serialize(value));
   }
-  async validateSnapshotFilePath(filePath) {
-    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.");
+  snapshotMaxBytes() {
+    return this.options.snapshotMaxBytes === false ? false : this.options.snapshotMaxBytes ?? DEFAULT_SNAPSHOT_MAX_BYTES;
+  }
+  snapshotMaxEntries() {
+    return this.options.snapshotMaxEntries === false ? false : this.options.snapshotMaxEntries ?? DEFAULT_SNAPSHOT_MAX_ENTRIES;
+  }
+  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];
     }
-    const path = await import("path");
-    const resolved = path.resolve(filePath);
-    const baseDir = this.options.snapshotBaseDir === false ? false : path.resolve(this.options.snapshotBaseDir ?? process.cwd());
-    if (baseDir !== false) {
-      const relative = path.relative(baseDir, resolved);
-      if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-        throw new Error(`filePath is outside the allowed snapshot directory: ${baseDir}`);
-      }
+    for (const key of await this.tagIndex.keysForTag(tag)) {
+      keys.add(key);
+      this.assertWithinInvalidationKeyLimit(keys.size);
     }
-    return resolved;
+    return [...keys];
   }
-  normalizeForSerialization(value) {
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.normalizeForSerialization(entry));
+  assertWithinInvalidationKeyLimit(size) {
+    const maxKeys = this.invalidationMaxKeys();
+    if (maxKeys !== false && size > maxKeys) {
+      throw new Error(`Invalidation matched too many keys (${size} > ${maxKeys}).`);
     }
-    if (value && typeof value === "object") {
-      return Object.keys(value).sort().reduce((normalized, key) => {
-        if (DANGEROUS_OBJECT_KEYS.has(key)) {
-          return normalized;
+  }
+  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;
         }
-        normalized[key] = this.normalizeForSerialization(value[key]);
-        return normalized;
-      }, {});
+        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);
+      }
     }
-    return value;
   }
 };
-function createInstanceId() {
-  return globalThis.crypto?.randomUUID?.() ?? `layercache-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-}
 
 // src/invalidation/RedisInvalidationBus.ts
 var RedisInvalidationBus = class {
@@ -2819,7 +3342,7 @@ var RedisInvalidationBus = class {
   async dispatchToHandlers(payload) {
     let message;
     try {
-      const parsed = JSON.parse(payload);
+      const parsed = sanitizeJsonValue2(JSON.parse(payload));
       if (!this.isInvalidationMessage(parsed)) {
         throw new Error("Invalid invalidation payload shape.");
       }
@@ -2856,6 +3379,31 @@ 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 {
@@ -2903,6 +3451,17 @@ var RedisTagIndex = class {
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  async forEachKeyForTag(tag, visitor) {
+    let cursor = "0";
+    const tagKey = this.tagKeysKey(tag);
+    do {
+      const [nextCursor, keys] = await this.client.sscan(tagKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      for (const key of keys) {
+        await visitor(key);
+      }
+    } while (cursor !== "0");
+  }
   async keysForPrefix(prefix) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -2915,6 +3474,20 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyForPrefix(prefix, visitor) {
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
@@ -2937,6 +3510,27 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  async forEachKeyMatchingPattern(pattern, visitor) {
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            await visitor(key);
+          }
+        }
+      } while (cursor !== "0");
+    }
+  }
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {
@@ -2992,10 +3586,18 @@ function simpleHash(value) {
 }
 
 // src/http/createCacheStatsHandler.ts
-function createCacheStatsHandler(cache) {
-  return async (_request, response) => {
-    response.statusCode = 200;
+function createCacheStatsHandler(cache, options = {}) {
+  return async (request, response) => {
     response.setHeader?.("content-type", "application/json; charset=utf-8");
+    response.setHeader?.("cache-control", "no-store");
+    response.setHeader?.("x-content-type-options", "nosniff");
+    const isAuthorized = options.allowPublicAccess === true || (options.authorize ? await options.authorize(request) : false);
+    if (!isAuthorized) {
+      response.statusCode = options.unauthorizedStatusCode ?? 403;
+      response.end(JSON.stringify({ error: "Forbidden" }));
+      return;
+    }
+    response.statusCode = 200;
     response.end(JSON.stringify(cache.getStats(), null, 2));
   };
 }
@@ -3030,7 +3632,26 @@ function createFastifyLayercachePlugin(cache, options = {}) {
   return async (fastify) => {
     fastify.decorate("cache", cache);
     if (options.exposeStatsRoute === true && fastify.get) {
-      fastify.get(options.statsPath ?? "/cache/stats", async () => cache.getStats());
+      fastify.get(options.statsPath ?? "/cache/stats", async (request, reply) => {
+        const isAuthorized = options.allowPublicStatsRoute === true || (options.authorizeStatsRoute ? await options.authorizeStatsRoute(request) : false);
+        reply.header?.("cache-control", "no-store");
+        reply.header?.("x-content-type-options", "nosniff");
+        if (!isAuthorized) {
+          reply.statusCode = options.unauthorizedStatusCode ?? 403;
+          const body2 = { error: "Forbidden" };
+          if (reply.send) {
+            reply.send(body2);
+            return;
+          }
+          return body2;
+        }
+        const body = cache.getStats();
+        if (reply.send) {
+          reply.send(body);
+          return;
+        }
+        return body;
+      });
     }
   };
 }
@@ -3045,6 +3666,10 @@ function createExpressCacheMiddleware(cache, options = {}) {
         next();
         return;
       }
+      if (!options.keyResolver && options.allowPrivateCaching !== true) {
+        next();
+        return;
+      }
       const rawUrl = req.originalUrl ?? req.url ?? "/";
       const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeUrl(rawUrl)}`;
       const cached = await cache.get(key, void 0, options);
@@ -3081,7 +3706,7 @@ function normalizeUrl(url) {
   try {
     const parsed = new URL(url, "http://localhost");
     parsed.searchParams.sort();
-    return decodeURIComponent(parsed.pathname) + parsed.search;
+    return parsed.pathname + parsed.search;
   } catch {
     return url;
   }
@@ -3089,6 +3714,11 @@ function normalizeUrl(url) {
 
 // src/integrations/graphql.ts
 function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
+  if (!options.keyResolver && options.allowImplicitContextCaching !== true) {
+    throw new Error(
+      "cacheGraphqlResolver requires a keyResolver or allowImplicitContextCaching=true because resolver output may depend on request context."
+    );
+  }
   const wrapped = cache.wrap(prefix, resolver, {
     ...options,
     keyResolver: options.keyResolver
@@ -3105,14 +3735,17 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
+    if (!options.keyResolver && options.allowPrivateCaching !== true) {
+      await next();
+      return;
+    }
     const rawPath = context.req.path ?? context.req.url ?? "/";
     const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl2(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
       context.header?.("content-type", "application/json; charset=utf-8");
-      context.json(cached);
-      return;
+      return context.json(cached);
     }
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
@@ -3132,7 +3765,7 @@ function normalizeUrl2(url) {
   try {
     const parsed = new URL(url, "http://localhost");
     parsed.searchParams.sort();
-    return decodeURIComponent(parsed.pathname) + parsed.search;
+    return parsed.pathname + parsed.search;
   } catch {
     return url;
   }
@@ -3202,6 +3835,11 @@ function instrument(name, tracer, method, attributes) {
 
 // src/integrations/trpc.ts
 function createTrpcCacheMiddleware(cache, prefix, options = {}) {
+  if (!options.keyResolver && options.allowImplicitContextCaching !== true) {
+    throw new Error(
+      "createTrpcCacheMiddleware requires a keyResolver or allowImplicitContextCaching=true because procedure output may depend on request context."
+    );
+  }
   return async (context) => {
     const key = options.keyResolver ? `${prefix}:${options.keyResolver(context.rawInput, context.path, context.type)}` : `${prefix}:${context.path ?? "procedure"}:${JSON.stringify(context.rawInput ?? null)}`;
     let didFetch = false;
@@ -3341,6 +3979,12 @@ var MemoryLayer = class {
     this.pruneExpired();
     return [...this.entries.keys()];
   }
+  async forEachKey(visitor) {
+    this.pruneExpired();
+    for (const key of this.entries.keys()) {
+      await visitor(key);
+    }
+  }
   exportState() {
     this.pruneExpired();
     return [...this.entries.entries()].map(([key, entry]) => ({
@@ -3408,13 +4052,12 @@ var MemoryLayer = class {
 };
 
 // src/layers/RedisLayer.ts
+var import_node_stream = require("stream");
 var import_node_util = require("util");
 var import_node_zlib = require("zlib");
 var BATCH_DELETE_SIZE = 500;
 var gzipAsync = (0, import_node_util.promisify)(import_node_zlib.gzip);
-var gunzipAsync = (0, import_node_util.promisify)(import_node_zlib.gunzip);
 var brotliCompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliCompress);
-var brotliDecompressAsync = (0, import_node_util.promisify)(import_node_zlib.brotliDecompress);
 var RedisLayer = class {
   name;
   defaultTtl;
@@ -3522,8 +4165,18 @@ var RedisLayer = class {
     return remaining;
   }
   async size() {
-    const keys = await this.keys();
-    return keys.length;
+    if (!this.prefix) {
+      return this.client.dbsize();
+    }
+    const pattern = `${this.prefix}*`;
+    let cursor = "0";
+    let count = 0;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      count += keys.length;
+    } while (cursor !== "0");
+    return count;
   }
   async ping() {
     try {
@@ -3569,6 +4222,17 @@ var RedisLayer = class {
     }
     return keys.map((key) => key.slice(this.prefix.length));
   }
+  async forEachKey(visitor) {
+    const pattern = `${this.prefix}*`;
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      for (const key of keys) {
+        await visitor(this.prefix ? key.slice(this.prefix.length) : key);
+      }
+    } while (cursor !== "0");
+  }
   async scanKeys(pattern) {
     const matches = [];
     let cursor = "0";
@@ -3583,7 +4247,13 @@ var RedisLayer = class {
     return `${this.prefix}${key}`;
   }
   async deserializeOrDelete(key, payload) {
-    const decodedPayload = await this.decodePayload(payload);
+    let decodedPayload;
+    try {
+      decodedPayload = await this.decodePayload(payload);
+    } catch {
+      await this.deleteCorruptedKey(key);
+      return null;
+    }
     for (const serializer of this.serializers) {
       try {
         const value = serializer.deserialize(decodedPayload);
@@ -3594,11 +4264,15 @@ var RedisLayer = class {
       } catch {
       }
     }
+    await this.deleteCorruptedKey(key);
+    return null;
+  }
+  async deleteCorruptedKey(key) {
     try {
-      await this.client.del(this.withPrefix(key)).catch(() => void 0);
-    } catch {
+      await this.client.del(this.withPrefix(key));
+    } catch (deleteError) {
+      console.warn(`[layercache] RedisLayer: failed to delete corrupted key "${key}"`, deleteError);
     }
-    return null;
   }
   async rewriteWithPrimarySerializer(key, value) {
     const serialized = this.primarySerializer().serialize(value);
@@ -3645,31 +4319,72 @@ var RedisLayer = class {
       return payload;
     }
     if (payload.subarray(0, 10).toString() === "LCZ1:gzip:") {
-      const decompressed = await gunzipAsync(payload.subarray(10));
-      if (decompressed.byteLength > this.decompressionMaxBytes) {
-        throw new Error(
-          `Decompressed payload (${decompressed.byteLength} bytes) exceeds decompressionMaxBytes limit (${this.decompressionMaxBytes} bytes).`
-        );
-      }
-      return decompressed;
+      return this.decompressWithLimit((0, import_node_zlib.createGunzip)(), payload.subarray(10));
     }
     if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
-      const decompressed = await brotliDecompressAsync(payload.subarray(12));
-      if (decompressed.byteLength > this.decompressionMaxBytes) {
-        throw new Error(
-          `Decompressed payload (${decompressed.byteLength} bytes) exceeds decompressionMaxBytes limit (${this.decompressionMaxBytes} bytes).`
-        );
-      }
-      return decompressed;
+      return this.decompressWithLimit((0, import_node_zlib.createBrotliDecompress)(), payload.subarray(12));
     }
     return payload;
   }
+  async decompressWithLimit(decompressor, payload) {
+    return new Promise((resolve2, reject) => {
+      const source = import_node_stream.Readable.from(payload);
+      const chunks = [];
+      let totalBytes = 0;
+      let settled = false;
+      const cleanup = () => {
+        decompressor.removeAllListeners();
+      };
+      const fail = (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        source.unpipe(decompressor);
+        source.destroy();
+        decompressor.destroy();
+        reject(error);
+      };
+      decompressor.on("data", (chunk) => {
+        const normalized = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += normalized.byteLength;
+        if (totalBytes > this.decompressionMaxBytes) {
+          fail(
+            new Error(
+              `Decompressed payload (${totalBytes} bytes) exceeds decompressionMaxBytes limit (${this.decompressionMaxBytes} bytes).`
+            )
+          );
+          return;
+        }
+        chunks.push(normalized);
+      });
+      decompressor.once("error", (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        reject(error);
+      });
+      decompressor.once("end", () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve2(Buffer.concat(chunks));
+      });
+      source.pipe(decompressor);
+    });
+  }
 };
 
 // src/layers/DiskLayer.ts
 var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var FILE_SCAN_CONCURRENCY = 32;
 var DiskLayer = class {
   name;
   defaultTtl;
@@ -3677,6 +4392,7 @@ var DiskLayer = class {
   directory;
   serializer;
   maxFiles;
+  maxEntryBytes;
   writeQueue = Promise.resolve();
   constructor(options) {
     this.directory = this.resolveDirectory(options.directory);
@@ -3684,16 +4400,15 @@ var DiskLayer = class {
     this.name = options.name ?? "disk";
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
+    this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
   }
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
   }
   async getEntry(key) {
     const filePath = this.keyToPath(key);
-    let raw;
-    try {
-      raw = await import_node_fs.promises.readFile(filePath);
-    } catch {
+    const raw = await this.readEntryFile(filePath);
+    if (raw === null) {
       return null;
     }
     let entry;
@@ -3744,10 +4459,8 @@ var DiskLayer = class {
   }
   async ttl(key) {
     const filePath = this.keyToPath(key);
-    let raw;
-    try {
-      raw = await import_node_fs.promises.readFile(filePath);
-    } catch {
+    const raw = await this.readEntryFile(filePath);
+    if (raw === null) {
       return null;
     }
     let entry;
@@ -3771,7 +4484,7 @@ var DiskLayer = class {
   }
   async deleteMany(keys) {
     await this.enqueueWrite(async () => {
-      await Promise.all(keys.map((key) => this.safeDelete(this.keyToPath(key))));
+      await this.deletePathsWithConcurrency(keys.map((key) => this.keyToPath(key)));
     });
   }
   async clear() {
@@ -3782,8 +4495,8 @@ var DiskLayer = class {
       } catch {
         return;
       }
-      await Promise.all(
-        entries.filter((name) => name.endsWith(".lc")).map((name) => this.safeDelete((0, import_node_path.join)(this.directory, name)))
+      await this.deletePathsWithConcurrency(
+        entries.filter((name) => name.endsWith(".lc")).map((name) => (0, import_node_path.join)(this.directory, name))
       );
     });
   }
@@ -3792,42 +4505,23 @@ var DiskLayer = class {
    * Expired entries are skipped and cleaned up during the scan.
    */
   async keys() {
-    let entries;
-    try {
-      entries = await import_node_fs.promises.readdir(this.directory);
-    } catch {
-      return [];
-    }
-    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
     const keys = [];
-    await Promise.all(
-      lcFiles.map(async (name) => {
-        const filePath = (0, import_node_path.join)(this.directory, name);
-        let raw;
-        try {
-          raw = await import_node_fs.promises.readFile(filePath);
-        } catch {
-          return;
-        }
-        let entry;
-        try {
-          entry = this.deserializeEntry(raw);
-        } catch {
-          await this.safeDelete(filePath);
-          return;
-        }
-        if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
-          await this.safeDelete(filePath);
-          return;
-        }
-        keys.push(entry.key);
-      })
-    );
+    await this.scanEntries(async (entry) => {
+      keys.push(entry.key);
+    });
     return keys;
   }
+  async forEachKey(visitor) {
+    await this.scanEntries(async (entry) => {
+      await visitor(entry.key);
+    });
+  }
   async size() {
-    const keys = await this.keys();
-    return keys.length;
+    let count = 0;
+    await this.scanEntries(async () => {
+      count += 1;
+    });
+    return count;
   }
   async ping() {
     try {
@@ -3861,6 +4555,113 @@ var DiskLayer = class {
     }
     return maxFiles;
   }
+  normalizeMaxEntryBytes(maxEntryBytes) {
+    if (maxEntryBytes === false) {
+      return false;
+    }
+    const normalized = maxEntryBytes ?? 16 * 1024 * 1024;
+    if (!Number.isFinite(normalized) || normalized <= 0) {
+      throw new Error("DiskLayer.maxEntryBytes must be a positive number or false.");
+    }
+    return normalized;
+  }
+  async readEntryFile(filePath) {
+    let handle;
+    try {
+      handle = await import_node_fs.promises.open(filePath, "r");
+      return await this.readHandleWithLimit(handle);
+    } catch {
+      await this.safeDelete(filePath);
+      return null;
+    } finally {
+      await handle?.close().catch(() => void 0);
+    }
+  }
+  async readHandleWithLimit(handle) {
+    if (this.maxEntryBytes === false) {
+      return handle.readFile();
+    }
+    const stat = await handle.stat();
+    if (stat.size > this.maxEntryBytes) {
+      throw new Error(`DiskLayer entry exceeds maxEntryBytes limit (${stat.size} bytes > ${this.maxEntryBytes} bytes).`);
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    let position = 0;
+    while (true) {
+      const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, this.maxEntryBytes - totalBytes + 1));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
+      if (bytesRead === 0) {
+        break;
+      }
+      totalBytes += bytesRead;
+      if (totalBytes > this.maxEntryBytes) {
+        throw new Error(
+          `DiskLayer entry exceeds maxEntryBytes limit (${totalBytes} bytes > ${this.maxEntryBytes} bytes).`
+        );
+      }
+      chunks.push(buffer.subarray(0, bytesRead));
+      position += bytesRead;
+    }
+    return Buffer.concat(chunks);
+  }
+  async scanEntries(visitor) {
+    let entries;
+    try {
+      entries = await import_node_fs.promises.readdir(this.directory);
+    } catch {
+      return;
+    }
+    const lcFiles = entries.filter((name) => name.endsWith(".lc"));
+    let nextIndex = 0;
+    const workerCount = Math.min(FILE_SCAN_CONCURRENCY, lcFiles.length);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        while (true) {
+          const currentIndex = nextIndex;
+          nextIndex += 1;
+          const name = lcFiles[currentIndex];
+          if (name === void 0) {
+            return;
+          }
+          const filePath = (0, import_node_path.join)(this.directory, name);
+          const raw = await this.readEntryFile(filePath);
+          if (raw === null) {
+            continue;
+          }
+          let entry;
+          try {
+            entry = this.deserializeEntry(raw);
+          } catch {
+            await this.safeDelete(filePath);
+            continue;
+          }
+          if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+            await this.safeDelete(filePath);
+            continue;
+          }
+          await visitor(entry);
+        }
+      })
+    );
+  }
+  async deletePathsWithConcurrency(paths) {
+    let nextIndex = 0;
+    const workerCount = Math.min(FILE_SCAN_CONCURRENCY, paths.length);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        while (true) {
+          const currentIndex = nextIndex;
+          nextIndex += 1;
+          const filePath = paths[currentIndex];
+          if (filePath === void 0) {
+            return;
+          }
+          await this.safeDelete(filePath);
+        }
+      })
+    );
+  }
   deserializeEntry(raw) {
     const entry = this.serializer.deserialize(raw);
     if (!isDiskEntry(entry)) {
@@ -3996,29 +4797,38 @@ var MemcachedLayer = class {
 
 // src/serialization/MsgpackSerializer.ts
 var import_msgpack = require("@msgpack/msgpack");
-var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+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));
+    return sanitizeMsgpackValue((0, import_msgpack.decode)(normalized), 0, { count: 0 });
   }
 };
-function sanitizeMsgpackValue(value) {
+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));
+    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_KEYS.has(key)) {
+    if (DANGEROUS_KEYS2.has(key)) {
       continue;
     }
-    sanitized[key] = sanitizeMsgpackValue(entry);
+    sanitized[key] = sanitizeMsgpackValue(entry, depth + 1, state);
   }
   return sanitized;
 }