layercache 1.3.1 → 1.3.2

package/packages/nestjs/dist/index.js

@@ -1,3915 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp(target, key, result);
-  return result;
-};
-
-// src/constants.ts
-var CACHE_STACK = /* @__PURE__ */ Symbol("CACHE_STACK");
-
-// ../../src/decorators/createCachedMethodDecorator.ts
-function createCachedMethodDecorator(options) {
-  const wrappedByInstance = /* @__PURE__ */ new WeakMap();
-  return ((_, propertyKey, descriptor) => {
-    const original = descriptor.value;
-    if (typeof original !== "function") {
-      throw new Error("createCachedMethodDecorator can only be applied to methods.");
-    }
-    descriptor.value = async function(...args) {
-      const instance = this;
-      let wrapped = wrappedByInstance.get(instance);
-      if (!wrapped) {
-        const cache = options.cache(instance);
-        wrapped = cache.wrap(
-          options.prefix ?? String(propertyKey),
-          (...methodArgs) => Promise.resolve(original.apply(instance, methodArgs)),
-          options
-        );
-        wrappedByInstance.set(instance, wrapped);
-      }
-      return wrapped(...args);
-    };
-  });
-}
-
-// src/decorators.ts
-function Cacheable(options) {
-  return createCachedMethodDecorator(options);
-}
-
-// src/module.ts
-import { Global, Inject, Module } from "@nestjs/common";
-
-// ../../src/CacheStack.ts
-import { EventEmitter } from "events";
-
-// ../../node_modules/async-mutex/index.mjs
-var E_TIMEOUT = new Error("timeout while waiting for mutex to become available");
-var E_ALREADY_LOCKED = new Error("mutex already locked");
-var E_CANCELED = new Error("request for lock canceled");
-var __awaiter$2 = function(thisArg, _arguments, P, generator) {
-  function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
-    });
-  }
-  return new (P || (P = Promise))(function(resolve, reject) {
-    function fulfilled(value) {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function rejected(value) {
-      try {
-        step(generator["throw"](value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
-    }
-    step((generator = generator.apply(thisArg, _arguments || [])).next());
-  });
-};
-var Semaphore = class {
-  constructor(_value, _cancelError = E_CANCELED) {
-    this._value = _value;
-    this._cancelError = _cancelError;
-    this._weightedQueues = [];
-    this._weightedWaiters = [];
-  }
-  acquire(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    return new Promise((resolve, reject) => {
-      if (!this._weightedQueues[weight - 1])
-        this._weightedQueues[weight - 1] = [];
-      this._weightedQueues[weight - 1].push({ resolve, reject });
-      this._dispatch();
-    });
-  }
-  runExclusive(callback, weight = 1) {
-    return __awaiter$2(this, void 0, void 0, function* () {
-      const [value, release] = yield this.acquire(weight);
-      try {
-        return yield callback(value);
-      } finally {
-        release();
-      }
-    });
-  }
-  waitForUnlock(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    return new Promise((resolve) => {
-      if (!this._weightedWaiters[weight - 1])
-        this._weightedWaiters[weight - 1] = [];
-      this._weightedWaiters[weight - 1].push(resolve);
-      this._dispatch();
-    });
-  }
-  isLocked() {
-    return this._value <= 0;
-  }
-  getValue() {
-    return this._value;
-  }
-  setValue(value) {
-    this._value = value;
-    this._dispatch();
-  }
-  release(weight = 1) {
-    if (weight <= 0)
-      throw new Error(`invalid weight ${weight}: must be positive`);
-    this._value += weight;
-    this._dispatch();
-  }
-  cancel() {
-    this._weightedQueues.forEach((queue) => queue.forEach((entry) => entry.reject(this._cancelError)));
-    this._weightedQueues = [];
-  }
-  _dispatch() {
-    var _a;
-    for (let weight = this._value; weight > 0; weight--) {
-      const queueEntry = (_a = this._weightedQueues[weight - 1]) === null || _a === void 0 ? void 0 : _a.shift();
-      if (!queueEntry)
-        continue;
-      const previousValue = this._value;
-      const previousWeight = weight;
-      this._value -= weight;
-      weight = this._value + 1;
-      queueEntry.resolve([previousValue, this._newReleaser(previousWeight)]);
-    }
-    this._drainUnlockWaiters();
-  }
-  _newReleaser(weight) {
-    let called = false;
-    return () => {
-      if (called)
-        return;
-      called = true;
-      this.release(weight);
-    };
-  }
-  _drainUnlockWaiters() {
-    for (let weight = this._value; weight > 0; weight--) {
-      if (!this._weightedWaiters[weight - 1])
-        continue;
-      this._weightedWaiters[weight - 1].forEach((waiter) => waiter());
-      this._weightedWaiters[weight - 1] = [];
-    }
-  }
-};
-var __awaiter$1 = function(thisArg, _arguments, P, generator) {
-  function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
-    });
-  }
-  return new (P || (P = Promise))(function(resolve, reject) {
-    function fulfilled(value) {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function rejected(value) {
-      try {
-        step(generator["throw"](value));
-      } catch (e) {
-        reject(e);
-      }
-    }
-    function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
-    }
-    step((generator = generator.apply(thisArg, _arguments || [])).next());
-  });
-};
-var Mutex = class {
-  constructor(cancelError) {
-    this._semaphore = new Semaphore(1, cancelError);
-  }
-  acquire() {
-    return __awaiter$1(this, void 0, void 0, function* () {
-      const [, releaser] = yield this._semaphore.acquire();
-      return releaser;
-    });
-  }
-  runExclusive(callback) {
-    return this._semaphore.runExclusive(() => callback());
-  }
-  isLocked() {
-    return this._semaphore.isLocked();
-  }
-  waitForUnlock() {
-    return this._semaphore.waitForUnlock();
-  }
-  release() {
-    if (this._semaphore.isLocked())
-      this._semaphore.release();
-  }
-  cancel() {
-    return this._semaphore.cancel();
-  }
-};
-
-// ../../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;
-    this.prefix = prefix;
-    validateNamespaceKey(prefix);
-  }
-  cache;
-  prefix;
-  static metricsMutexes = /* @__PURE__ */ new WeakMap();
-  metrics = createEmptyNamespaceMetrics();
-  async get(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, 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, this.qualifyGetOptions(options)));
-  }
-  async has(key) {
-    return this.trackMetrics(() => this.cache.has(this.qualify(key)));
-  }
-  async ttl(key) {
-    return this.trackMetrics(() => this.cache.ttl(this.qualify(key)));
-  }
-  async set(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)));
-  }
-  async mdelete(keys) {
-    await this.trackMetrics(() => this.cache.mdelete(keys.map((k) => this.qualify(k))));
-  }
-  async clear() {
-    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.prefix));
-  }
-  async mget(entries) {
-    return this.trackMetrics(
-      () => this.cache.mget(
-        entries.map((entry) => ({
-          ...entry,
-          key: this.qualify(entry.key),
-          options: this.qualifyGetOptions(entry.options)
-        }))
-      )
-    );
-  }
-  async mset(entries) {
-    await this.trackMetrics(
-      () => this.cache.mset(
-        entries.map((entry) => ({
-          ...entry,
-          key: this.qualify(entry.key),
-          options: this.qualifyWriteOptions(entry.options)
-        }))
-      )
-    );
-  }
-  async invalidateByTag(tag) {
-    await this.trackMetrics(() => this.cache.invalidateByTag(this.qualifyTag(tag)));
-  }
-  async invalidateByTags(tags, mode = "any") {
-    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)));
-  }
-  async invalidateByPrefix(prefix) {
-    await this.trackMetrics(() => this.cache.invalidateByPrefix(this.qualify(prefix)));
-  }
-  /**
-   * Returns detailed metadata about a single cache key within this namespace.
-   */
-  async inspect(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, this.qualifyWrapOptions(options));
-  }
-  warm(entries, options) {
-    return this.cache.warm(
-      entries.map((entry) => ({
-        ...entry,
-        key: this.qualify(entry.key),
-        options: this.qualifyGetOptions(entry.options)
-      })),
-      options
-    );
-  }
-  getMetrics() {
-    return cloneNamespaceMetrics(this.metrics);
-  }
-  getHitRate() {
-    return computeNamespaceHitRate(this.metrics);
-  }
-  /**
-   * Creates a nested namespace. Keys are prefixed with `parentPrefix:childPrefix:`.
-   *
-   * ```ts
-   * const tenant = cache.namespace('tenant:abc')
-   * const posts = tenant.namespace('posts')
-   * // keys become: "tenant:abc:posts:mykey"
-   * ```
-   */
-  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();
-      const result = await operation();
-      const after = this.cache.getMetrics();
-      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
-      return result;
-    });
-  }
-  getMetricsMutex() {
-    const existing = _CacheNamespace.metricsMutexes.get(this.cache);
-    if (existing) {
-      return existing;
-    }
-    const mutex = new Mutex();
-    _CacheNamespace.metricsMutexes.set(this.cache, mutex);
-    return mutex;
-  }
-};
-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 {
-  /**
-   * Tests whether a glob-style pattern matches a value.
-   * Supports `*` (any sequence of characters) and `?` (any single character).
-   * Uses a two-pointer algorithm to avoid ReDoS vulnerabilities and
-   * quadratic memory usage on long patterns/keys.
-   */
-  static matches(pattern, value) {
-    return _PatternMatcher.matchLinear(pattern, value);
-  }
-  /**
-   * Linear-time glob matching with O(1) extra memory.
-   */
-  static matchLinear(pattern, value) {
-    let patternIndex = 0;
-    let valueIndex = 0;
-    let starIndex = -1;
-    let backtrackValueIndex = 0;
-    while (valueIndex < value.length) {
-      const patternChar = pattern[patternIndex];
-      const valueChar = value[valueIndex];
-      if (patternChar === "*" && patternIndex < pattern.length) {
-        starIndex = patternIndex;
-        patternIndex += 1;
-        backtrackValueIndex = valueIndex;
-        continue;
-      }
-      if (patternChar === "?" || patternChar === valueChar) {
-        patternIndex += 1;
-        valueIndex += 1;
-        continue;
-      }
-      if (starIndex !== -1) {
-        patternIndex = starIndex + 1;
-        backtrackValueIndex += 1;
-        valueIndex = backtrackValueIndex;
-        continue;
-      }
-      return false;
-    }
-    while (patternIndex < pattern.length && pattern[patternIndex] === "*") {
-      patternIndex += 1;
-    }
-    return patternIndex === pattern.length;
-  }
-};
-
-// ../../src/internal/CacheKeyDiscovery.ts
-var CacheKeyDiscovery = class {
-  constructor(options) {
-    this.options = options;
-  }
-  options;
-  async collectKeysWithPrefix(prefix, maxMatches = false) {
-    const { tagIndex } = this.options;
-    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 && !layer.forEachKey || this.options.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          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) {
-          await this.options.handleLayerFailure(layer, "invalidate-prefix-scan", error);
-        }
-      })
-    );
-    return [...matches];
-  }
-  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 && !layer.forEachKey || this.options.shouldSkipLayer(layer)) {
-          return;
-        }
-        try {
-          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) {
-          await this.options.handleLayerFailure(layer, "invalidate-pattern-scan", error);
-        }
-      })
-    );
-    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.replace(/%/g, "%25").replace(/:/g, "%3A")}`;
-  }
-  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();
-  }
-  if (globalThis.crypto?.getRandomValues) {
-    const bytes = new Uint8Array(16);
-    globalThis.crypto.getRandomValues(bytes);
-    return `layercache-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-  }
-  throw new Error(
-    "layercache requires a cryptographic random source. Neither crypto.randomUUID nor crypto.getRandomValues is available in this runtime."
-  );
-}
-
-// ../../src/internal/CacheStackGeneration.ts
-var DEFAULT_GENERATION_CLEANUP_BATCH_SIZE = 500;
-function generationPrefix(generation) {
-  return generation === void 0 ? "" : `v${generation}:`;
-}
-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);
-}
-function resolveGenerationCleanupTarget({
-  previousGeneration,
-  nextGeneration,
-  generationCleanup
-}) {
-  if (!generationCleanup || previousGeneration === void 0 || previousGeneration === nextGeneration) {
-    return null;
-  }
-  return previousGeneration;
-}
-function resolveGenerationCleanupBatchSize(generationCleanup) {
-  if (typeof generationCleanup !== "object" || generationCleanup === null) {
-    return DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
-  }
-  return generationCleanup.batchSize ?? DEFAULT_GENERATION_CLEANUP_BATCH_SIZE;
-}
-function planGenerationCleanupBatches(keys, generationCleanup) {
-  if (keys.length === 0) {
-    return [];
-  }
-  const batchSize = resolveGenerationCleanupBatchSize(generationCleanup);
-  const batches = [];
-  for (let index = 0; index < keys.length; index += batchSize) {
-    batches.push(keys.slice(index, index + batchSize));
-  }
-  return batches;
-}
-
-// ../../src/internal/CacheStackInvalidationSupport.ts
-var CacheStackInvalidationSupport = class {
-  constructor(options) {
-    this.options = options;
-  }
-  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];
-  }
-  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)));
-  }
-  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");
-    const degraded = results.filter((result) => result.status === "fulfilled");
-    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
-import { randomBytes } from "crypto";
-import { constants, promises as fs } from "fs";
-import path from "path";
-
-// ../../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, fs2, path2) {
-  let current = directory;
-  while (true) {
-    try {
-      await fs2.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: fs2 } = 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 fs2.mkdir(baseDir, { recursive: true });
-  const realBaseDir = await fs2.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 fs2.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, fs2, path2);
-  const realExistingAncestor = await fs2.realpath(existingAncestor);
-  if (!isWithinSnapshotBase(realBaseDir, realExistingAncestor, path2.sep, path2)) {
-    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, 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 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/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 > options.maxNodes) {
-    throw new Error(`${options.label} exceeds max node count of ${options.maxNodes}.`);
-  }
-  if (depth > options.maxDepth) {
-    throw new Error(`${options.label} exceeds max depth of ${options.maxDepth}.`);
-  }
-  if (Array.isArray(value)) {
-    const sanitized2 = [];
-    for (const entry of value) {
-      sanitized2.push(sanitizeValue(entry, depth + 1, state, options));
-    }
-    return sanitized2;
-  }
-  if (!isPlainObject(value)) {
-    return value;
-  }
-  const sanitized = options.createObject?.() ?? {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (DANGEROUS_KEYS.has(key)) {
-      continue;
-    }
-    sanitized[key] = sanitizeValue(entry, depth + 1, state, options);
-  }
-  return sanitized;
-}
-function isPlainObject(value) {
-  return Object.prototype.toString.call(value) === "[object Object]";
-}
-
-// ../../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(async (layer) => {
-              if (this.options.shouldSkipLayer(layer)) return;
-              try {
-                await layer.set(entry.key, entry.value, entry.ttl);
-              } catch (error) {
-                await this.options.handleLayerFailure(layer, "write", error);
-              }
-            })
-          );
-          await this.options.tagIndex.touch(entry.key);
-        })
-      );
-    }
-  }
-  async persistToFile(filePath, snapshotBaseDir, maxEntries) {
-    const targetPath = await validateSnapshotFilePath(filePath, "write", snapshotBaseDir);
-    const tempPath = path.join(
-      path.dirname(targetPath),
-      `.layercache-${process.pid}-${Date.now()}-${randomBytes(8).toString("hex")}.tmp`
-    );
-    let handle;
-    try {
-      handle = await fs.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 fs.rename(tempPath, targetPath);
-    } catch (error) {
-      await handle?.close().catch(() => void 0);
-      await fs.unlink(tempPath).catch(() => void 0);
-      throw error;
-    }
-  }
-  async restoreFromFile(filePath, snapshotBaseDir, maxBytes) {
-    const validatedPath = await validateSnapshotFilePath(filePath, "read", snapshotBaseDir);
-    const handle = await fs.open(validatedPath, constants.O_RDONLY | (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)})`);
-    }
-    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
-      }))
-    );
-  }
-  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);
-      }
-    }
-  }
-  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) {
-    const roundTripped = this.options.snapshotSerializer.deserialize(this.options.snapshotSerializer.serialize(value));
-    return sanitizeStructuredData(roundTripped, {
-      label: "Snapshot value",
-      maxDepth: 64,
-      maxNodes: 1e4,
-      createObject: () => /* @__PURE__ */ Object.create(null)
-    });
-  }
-};
-
-// ../../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();
-  maxEntries;
-  constructor(options) {
-    this.maxEntries = options.maxEntries;
-  }
-  /**
-   * Throws if the circuit is open for the given key.
-   * Automatically resets if the cooldown has elapsed.
-   */
-  assertClosed(key, options) {
-    const state = this.breakers.get(key);
-    if (!state?.openUntil) {
-      return;
-    }
-    const now = Date.now();
-    if (state.openUntil <= now) {
-      this.breakers.delete(key);
-      return;
-    }
-    const remainingMs = state.openUntil - now;
-    const remainingSecs = Math.ceil(remainingMs / 1e3);
-    const displayKey = key.length > 64 ? `${key.slice(0, 64)}...` : key;
-    throw new Error(`Circuit breaker is open for key "${displayKey}" (resets in ${remainingSecs}s).`);
-  }
-  recordFailure(key, options) {
-    if (!options) {
-      return;
-    }
-    const failureThreshold = options.failureThreshold ?? 3;
-    const cooldownMs = options.cooldownMs ?? 3e4;
-    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);
-  }
-  isOpen(key) {
-    const state = this.breakers.get(key);
-    if (!state?.openUntil) {
-      return false;
-    }
-    if (state.openUntil <= Date.now()) {
-      this.breakers.delete(key);
-      return false;
-    }
-    return true;
-  }
-  delete(key) {
-    this.breakers.delete(key);
-  }
-  clear() {
-    this.breakers.clear();
-  }
-  tripCount() {
-    let count = 0;
-    for (const state of this.breakers.values()) {
-      if (state.openUntil !== null) {
-        count += 1;
-      }
-    }
-    return count;
-  }
-  pruneIfNeeded() {
-    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) {
-        return;
-      }
-      if (!state.openUntil || state.openUntil <= now) {
-        this.breakers.delete(key);
-      }
-    }
-    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;
-      }
-      this.breakers.delete(key);
-    }
-  }
-};
-
-// ../../src/internal/FetchRateLimiter.ts
-var MAX_BUCKETS = 1e4;
-var FetchRateLimiter = class {
-  buckets = /* @__PURE__ */ new Map();
-  queuesByBucket = /* @__PURE__ */ new Map();
-  pendingBuckets = /* @__PURE__ */ new Set();
-  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();
-    }
-    const normalized = this.normalize(options);
-    if (!normalized) {
-      return task();
-    }
-    return new Promise((resolve, reject) => {
-      const bucketKey = this.resolveBucketKey(normalized, context);
-      const queue = this.queuesByBucket.get(bucketKey) ?? [];
-      queue.push({
-        bucketKey,
-        options: normalized,
-        task,
-        resolve,
-        reject
-      });
-      this.queuesByBucket.set(bucketKey, queue);
-      this.pendingBuckets.add(bucketKey);
-      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;
-    const maxPerInterval = options.maxPerInterval;
-    if (!maxConcurrent && !(intervalMs && maxPerInterval)) {
-      return void 0;
-    }
-    return {
-      maxConcurrent,
-      intervalMs,
-      maxPerInterval,
-      scope: options.scope ?? "global",
-      bucketKey: options.bucketKey
-    };
-  }
-  resolveBucketKey(options, context) {
-    if (options.bucketKey) {
-      return `custom:${options.bucketKey}`;
-    }
-    if (options.scope === "key") {
-      return `key:${context.key}`;
-    }
-    if (options.scope === "fetcher") {
-      const existing = this.fetcherBuckets.get(context.fetcher);
-      if (existing) {
-        return existing;
-      }
-      const bucket = `fetcher:${this.nextFetcherBucketId}`;
-      this.nextFetcherBucketId += 1;
-      this.fetcherBuckets.set(context.fetcher, bucket);
-      return bucket;
-    }
-    return "global";
-  }
-  drain() {
-    if (this.isDisposed) {
-      return;
-    }
-    if (this.drainTimer) {
-      clearTimeout(this.drainTimer);
-      this.drainTimer = void 0;
-    }
-    while (this.pendingBuckets.size > 0) {
-      let nextBucketKey;
-      let nextWaitMs = Number.POSITIVE_INFINITY;
-      for (const bucketKey of this.pendingBuckets) {
-        const queue2 = this.queuesByBucket.get(bucketKey);
-        if (!queue2 || queue2.length === 0) {
-          this.pendingBuckets.delete(bucketKey);
-          this.queuesByBucket.delete(bucketKey);
-          continue;
-        }
-        const next2 = queue2[0];
-        if (!next2) {
-          this.pendingBuckets.delete(bucketKey);
-          this.queuesByBucket.delete(bucketKey);
-          continue;
-        }
-        const waitMs = this.waitTime(bucketKey, next2.options);
-        if (waitMs <= 0) {
-          nextBucketKey = bucketKey;
-          break;
-        }
-        nextWaitMs = Math.min(nextWaitMs, waitMs);
-      }
-      if (!nextBucketKey) {
-        if (Number.isFinite(nextWaitMs)) {
-          this.drainTimer = setTimeout(() => {
-            this.drainTimer = void 0;
-            this.drain();
-          }, nextWaitMs);
-          this.drainTimer.unref?.();
-        }
-        return;
-      }
-      const queue = this.queuesByBucket.get(nextBucketKey);
-      const next = queue?.shift();
-      if (!next) {
-        this.pendingBuckets.delete(nextBucketKey);
-        this.queuesByBucket.delete(nextBucketKey);
-        continue;
-      }
-      if (!queue || queue.length === 0) {
-        this.pendingBuckets.delete(nextBucketKey);
-        this.queuesByBucket.delete(nextBucketKey);
-      }
-      const bucket = this.bucketState(next.bucketKey);
-      if (bucket.cleanupTimer) {
-        clearTimeout(bucket.cleanupTimer);
-        bucket.cleanupTimer = void 0;
-      }
-      bucket.active += 1;
-      if (next.options.intervalMs && next.options.maxPerInterval) {
-        bucket.startedAt.push(Date.now());
-      }
-      void next.task().then(next.resolve, next.reject).finally(() => {
-        bucket.active -= 1;
-        if ((this.queuesByBucket.get(next.bucketKey)?.length ?? 0) > 0) {
-          this.pendingBuckets.add(next.bucketKey);
-        }
-        this.cleanupBucket(next.bucketKey, bucket, next.options.intervalMs);
-        if (!this.drainTimer) {
-          this.drainTimer = setTimeout(() => {
-            this.drainTimer = void 0;
-            this.drain();
-          }, 0);
-          this.drainTimer.unref?.();
-        }
-      });
-    }
-  }
-  waitTime(bucketKey, options) {
-    const bucket = this.bucketState(bucketKey);
-    const now = Date.now();
-    if (options.maxConcurrent && bucket.active >= options.maxConcurrent) {
-      return 1;
-    }
-    if (!options.intervalMs || !options.maxPerInterval) {
-      return 0;
-    }
-    this.prune(bucket, now, options.intervalMs);
-    if (bucket.startedAt.length < options.maxPerInterval) {
-      return 0;
-    }
-    const oldest = bucket.startedAt[0];
-    if (!oldest) {
-      return 0;
-    }
-    return Math.max(1, options.intervalMs - (now - oldest));
-  }
-  prune(bucket, now, intervalMs) {
-    while (bucket.startedAt.length > 0) {
-      const startedAt = bucket.startedAt[0];
-      if (startedAt === void 0 || now - startedAt < intervalMs) {
-        break;
-      }
-      bucket.startedAt.shift();
-    }
-  }
-  bucketState(bucketKey) {
-    if (this.isDisposed) {
-      throw new Error("FetchRateLimiter has been disposed.");
-    }
-    const existing = this.buckets.get(bucketKey);
-    if (existing) {
-      return existing;
-    }
-    if (this.buckets.size >= MAX_BUCKETS) {
-      this.evictIdleBuckets();
-      if (this.buckets.size >= MAX_BUCKETS) {
-        throw new Error(`FetchRateLimiter bucket limit (${MAX_BUCKETS}) exceeded.`);
-      }
-    }
-    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) {
-      this.buckets.delete(bucketKey);
-      this.queuesByBucket.delete(bucketKey);
-      this.pendingBuckets.delete(bucketKey);
-      return;
-    }
-    if (!intervalMs || bucket.active > 0 || queued > 0) {
-      return;
-    }
-    if (bucket.cleanupTimer) {
-      clearTimeout(bucket.cleanupTimer);
-    }
-    bucket.cleanupTimer = setTimeout(() => {
-      bucket.cleanupTimer = void 0;
-      this.prune(bucket, Date.now(), intervalMs);
-      if (bucket.active === 0 && bucket.startedAt.length === 0 && (this.queuesByBucket.get(bucketKey)?.length ?? 0) === 0) {
-        this.buckets.delete(bucketKey);
-        this.queuesByBucket.delete(bucketKey);
-        this.pendingBuckets.delete(bucketKey);
-      }
-    }, intervalMs);
-    bucket.cleanupTimer.unref?.();
-  }
-};
-
-// ../../src/internal/MetricsCollector.ts
-var MetricsCollector = class {
-  data = this.empty();
-  get snapshot() {
-    return {
-      ...this.data,
-      hitsByLayer: { ...this.data.hitsByLayer },
-      missesByLayer: { ...this.data.missesByLayer },
-      latencyByLayer: Object.fromEntries(Object.entries(this.data.latencyByLayer).map(([k, v]) => [k, { ...v }]))
-    };
-  }
-  increment(field, amount = 1) {
-    ;
-    this.data[field] += amount;
-  }
-  incrementLayer(map, layerName) {
-    this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
-  }
-  /**
-   * Records a read latency sample for the given layer.
-   * Maintains a rolling average and max using Welford's online algorithm.
-   */
-  recordLatency(layerName, durationMs) {
-    const existing = this.data.latencyByLayer[layerName];
-    if (!existing) {
-      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
-      return;
-    }
-    existing.count += 1;
-    existing.avgMs += (durationMs - existing.avgMs) / existing.count;
-    if (durationMs > existing.maxMs) {
-      existing.maxMs = durationMs;
-    }
-  }
-  reset() {
-    this.data = this.empty();
-  }
-  hitRate() {
-    const total = this.data.hits + this.data.misses;
-    const overall = total === 0 ? 0 : this.data.hits / total;
-    const byLayer = {};
-    const allLayers = /* @__PURE__ */ new Set([...Object.keys(this.data.hitsByLayer), ...Object.keys(this.data.missesByLayer)]);
-    for (const layer of allLayers) {
-      const h = this.data.hitsByLayer[layer] ?? 0;
-      const m = this.data.missesByLayer[layer] ?? 0;
-      byLayer[layer] = h + m === 0 ? 0 : h / (h + m);
-    }
-    return { overall, byLayer };
-  }
-  empty() {
-    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()
-    };
-  }
-};
-
-// ../../src/internal/TtlResolver.ts
-var DEFAULT_NEGATIVE_TTL_SECONDS = 60;
-var TtlResolver = class {
-  accessProfiles = /* @__PURE__ */ new Map();
-  maxProfileEntries;
-  constructor(options) {
-    this.maxProfileEntries = options.maxProfileEntries;
-  }
-  recordAccess(key) {
-    const profile = this.accessProfiles.get(key) ?? { hits: 0, lastAccessAt: Date.now() };
-    profile.hits += 1;
-    profile.lastAccessAt = Date.now();
-    this.accessProfiles.set(key, profile);
-    this.pruneIfNeeded();
-  }
-  deleteProfile(key) {
-    this.accessProfiles.delete(key);
-  }
-  clearProfiles() {
-    this.accessProfiles.clear();
-  }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, globalNegativeTtl, globalTtl, value) {
-    const policyTtl = kind === "value" ? this.resolvePolicyTtl(key, value, options?.ttlPolicy) : void 0;
-    const baseTtl = kind === "empty" ? this.resolveLayerSeconds(
-      layerName,
-      options?.negativeTtl,
-      globalNegativeTtl,
-      this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl) ?? DEFAULT_NEGATIVE_TTL_SECONDS
-    ) : this.resolveLayerSeconds(layerName, options?.ttl, globalTtl, policyTtl ?? fallbackTtl);
-    const adaptiveTtl = this.applyAdaptiveTtl(key, layerName, baseTtl, options?.adaptiveTtl);
-    const jitter = this.resolveLayerSeconds(layerName, options?.ttlJitter, void 0);
-    return this.applyJitter(adaptiveTtl, jitter);
-  }
-  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
-    if (override !== void 0) {
-      return this.readLayerNumber(layerName, override) ?? fallback;
-    }
-    if (globalDefault !== void 0) {
-      return this.readLayerNumber(layerName, globalDefault) ?? fallback;
-    }
-    return fallback;
-  }
-  applyAdaptiveTtl(key, layerName, ttl, adaptiveTtl) {
-    if (!ttl || !adaptiveTtl) {
-      return ttl;
-    }
-    const profile = this.accessProfiles.get(key);
-    if (!profile) {
-      return ttl;
-    }
-    const config = adaptiveTtl === true ? {} : adaptiveTtl;
-    const hotAfter = config.hotAfter ?? 3;
-    if (profile.hits < hotAfter) {
-      return ttl;
-    }
-    const step = this.resolveLayerSeconds(layerName, config.step, void 0, Math.max(1, Math.round(ttl / 2))) ?? 0;
-    const maxTtl = this.resolveLayerSeconds(layerName, config.maxTtl, void 0, ttl + step * 4) ?? ttl;
-    const multiplier = Math.floor(profile.hits / hotAfter);
-    return Math.min(maxTtl, ttl + step * multiplier);
-  }
-  applyJitter(ttl, jitter) {
-    if (!ttl || ttl <= 0 || !jitter || jitter <= 0) {
-      return ttl;
-    }
-    const delta = (Math.random() * 2 - 1) * jitter;
-    return Math.max(1, Math.round(ttl + delta));
-  }
-  resolvePolicyTtl(key, value, policy) {
-    if (!policy) {
-      return void 0;
-    }
-    if (typeof policy === "function") {
-      return policy({ key, value });
-    }
-    const now = /* @__PURE__ */ new Date();
-    if (policy === "until-midnight") {
-      const nextMidnight = new Date(now);
-      nextMidnight.setHours(24, 0, 0, 0);
-      return Math.max(1, Math.ceil((nextMidnight.getTime() - now.getTime()) / 1e3));
-    }
-    if (policy === "next-hour") {
-      const nextHour = new Date(now);
-      nextHour.setMinutes(60, 0, 0);
-      return Math.max(1, Math.ceil((nextHour.getTime() - now.getTime()) / 1e3));
-    }
-    const alignToSeconds = policy.alignTo;
-    const currentSeconds = Math.floor(Date.now() / 1e3);
-    const nextBoundary = Math.ceil((currentSeconds + 1) / alignToSeconds) * alignToSeconds;
-    return Math.max(1, nextBoundary - currentSeconds);
-  }
-  readLayerNumber(layerName, value) {
-    if (typeof value === "number") {
-      return value;
-    }
-    return value[layerName];
-  }
-  pruneIfNeeded() {
-    if (this.accessProfiles.size <= this.maxProfileEntries) {
-      return;
-    }
-    const toRemove = Math.ceil(this.maxProfileEntries * 0.1);
-    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]);
-      }
-    }
-  }
-};
-
-// ../../src/invalidation/TagIndex.ts
-var MAX_PATTERN_RECURSION_DEPTH = 500;
-var TagIndex = class {
-  tagToKeys = /* @__PURE__ */ new Map();
-  keyToTags = /* @__PURE__ */ new Map();
-  knownKeys = /* @__PURE__ */ new Set();
-  maxKnownKeys;
-  nextNodeId = 1;
-  root = this.createTrieNode();
-  constructor(options = {}) {
-    this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
-  }
-  async touch(key) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
-  }
-  async track(key, tags) {
-    this.insertKnownKey(key);
-    this.pruneKnownKeysIfNeeded();
-    if (tags.length === 0) {
-      return;
-    }
-    const existingTags = this.keyToTags.get(key);
-    if (existingTags) {
-      for (const tag of existingTags) {
-        this.tagToKeys.get(tag)?.delete(key);
-      }
-    }
-    const tagSet = new Set(tags);
-    this.keyToTags.set(key, tagSet);
-    for (const tag of tagSet) {
-      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
-      keys.add(key);
-      this.tagToKeys.set(tag, keys);
-    }
-  }
-  async remove(key) {
-    this.removeKey(key);
-  }
-  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) {
-      return [];
-    }
-    const matches = [];
-    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(), 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();
-    this.knownKeys.clear();
-    this.root.children.clear();
-    this.root.terminal = false;
-    this.nextNodeId = this.root.id + 1;
-  }
-  createTrieNode() {
-    return {
-      id: this.nextNodeId++,
-      terminal: false,
-      children: /* @__PURE__ */ new Map()
-    };
-  }
-  insertKnownKey(key) {
-    if (this.knownKeys.has(key)) {
-      return;
-    }
-    this.knownKeys.add(key);
-    let node = this.root;
-    for (const character of key) {
-      let child = node.children.get(character);
-      if (!child) {
-        child = this.createTrieNode();
-        node.children.set(character, child);
-      }
-      node = child;
-    }
-    node.terminal = true;
-  }
-  findNode(prefix) {
-    let node = this.root;
-    for (const character of prefix) {
-      node = node.children.get(character);
-      if (!node) {
-        return void 0;
-      }
-    }
-    return node;
-  }
-  collectFromNode(node, prefix, matches) {
-    if (node.terminal) {
-      matches.push(prefix);
-    }
-    for (const [character, child] of node.children) {
-      this.collectFromNode(child, `${prefix}${character}`, matches);
-    }
-  }
-  async visitFromNode(node, prefix, visitor) {
-    if (node.terminal) {
-      await visitor(prefix);
-    }
-    for (const [character, child] of node.children) {
-      await this.visitFromNode(child, `${prefix}${character}`, visitor);
-    }
-  }
-  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited, depth) {
-    if (depth > MAX_PATTERN_RECURSION_DEPTH) {
-      return;
-    }
-    const stateKey = `${node.id}:${patternIndex}`;
-    if (visited.has(stateKey)) {
-      return;
-    }
-    visited.add(stateKey);
-    if (patternIndex === pattern.length) {
-      if (node.terminal) {
-        matches.add(prefix);
-      }
-      return;
-    }
-    const patternChar = pattern[patternIndex];
-    if (patternChar === void 0) {
-      return;
-    }
-    if (patternChar === "*") {
-      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited, depth + 1);
-      for (const [character, child2] of node.children) {
-        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited, depth + 1);
-      }
-      return;
-    }
-    if (patternChar === "?") {
-      for (const [character, child2] of node.children) {
-        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,
-        depth + 1
-      );
-    }
-  }
-  pruneKnownKeysIfNeeded() {
-    if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
-      return;
-    }
-    const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
-    let removed = 0;
-    for (const key of this.knownKeys) {
-      if (removed >= toRemove) {
-        break;
-      }
-      this.removeKey(key);
-      removed += 1;
-    }
-  }
-  removeKey(key) {
-    this.removeKnownKey(key);
-    const tags = this.keyToTags.get(key);
-    if (!tags) {
-      return;
-    }
-    for (const tag of tags) {
-      const keys = this.tagToKeys.get(tag);
-      if (!keys) {
-        continue;
-      }
-      keys.delete(key);
-      if (keys.size === 0) {
-        this.tagToKeys.delete(tag);
-      }
-    }
-    this.keyToTags.delete(key);
-  }
-  removeKnownKey(key) {
-    if (!this.knownKeys.delete(key)) {
-      return;
-    }
-    const path2 = [];
-    let node = this.root;
-    for (const character of key) {
-      const child = node.children.get(character);
-      if (!child) {
-        return;
-      }
-      path2.push([node, character]);
-      node = child;
-    }
-    node.terminal = false;
-    for (let index = path2.length - 1; index >= 0; index -= 1) {
-      const entry = path2[index];
-      if (!entry) {
-        continue;
-      }
-      const [parent, character] = entry;
-      const child = parent.children.get(character);
-      if (!child || child.terminal || child.children.size > 0) {
-        break;
-      }
-      parent.children.delete(character);
-    }
-  }
-};
-
-// ../../src/serialization/JsonSerializer.ts
-var JsonSerializer = class {
-  serialize(value) {
-    return JSON.stringify(value);
-  }
-  deserialize(payload) {
-    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    let parsed;
-    try {
-      parsed = JSON.parse(normalized);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`JsonSerializer: failed to parse JSON payload: ${message}`);
-    }
-    return sanitizeStructuredData(parsed, {
-      label: "JSON payload",
-      maxDepth: 200,
-      maxNodes: 1e4
-    });
-  }
-};
-
-// ../../src/stampede/StampedeGuard.ts
-var StampedeGuard = class {
-  inFlight = /* @__PURE__ */ new Map();
-  maxInFlight;
-  entryTimeoutMs;
-  constructor(options = {}) {
-    this.maxInFlight = options.maxInFlight ?? 1e4;
-    this.entryTimeoutMs = options.entryTimeoutMs;
-  }
-  async execute(key, task) {
-    const existing = this.inFlight.get(key);
-    if (existing) {
-      existing.references += 1;
-      try {
-        return await existing.promise;
-      } finally {
-        this.releaseEntry(key, existing);
-      }
-    }
-    if (this.inFlight.size >= this.maxInFlight) {
-      throw new Error(
-        `StampedeGuard: in-flight limit of ${this.maxInFlight} exceeded. Rejecting new key to prevent memory exhaustion.`
-      );
-    }
-    const taskPromise = Promise.resolve().then(task);
-    const guardedPromise = this.entryTimeoutMs ? this.withTimeout(key, taskPromise, this.entryTimeoutMs) : taskPromise;
-    const entry = {
-      promise: guardedPromise,
-      references: 1
-    };
-    this.inFlight.set(key, entry);
-    try {
-      return await entry.promise;
-    } finally {
-      this.releaseEntry(key, entry);
-    }
-  }
-  withTimeout(key, promise, timeoutMs) {
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        reject(
-          new Error(
-            `StampedeGuard: task for key "${key.slice(0, 64)}${key.length > 64 ? "..." : ""}" timed out after ${timeoutMs}ms.`
-          )
-        );
-      }, timeoutMs);
-      promise.then(
-        (value) => {
-          clearTimeout(timer);
-          resolve(value);
-        },
-        (error) => {
-          clearTimeout(timer);
-          reject(error);
-        }
-      );
-    });
-  }
-  releaseEntry(key, entry) {
-    entry.references -= 1;
-    const current = this.inFlight.get(key);
-    if (current === entry && entry.references === 0) {
-      this.inFlight.delete(key);
-    }
-  }
-};
-
-// ../../src/types.ts
-var CacheMissError = class extends Error {
-  key;
-  constructor(key) {
-    super(`Cache miss for key "${key}".`);
-    this.name = "CacheMissError";
-    this.key = key;
-  }
-};
-
-// ../../src/CacheStack.ts
-var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
-var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
-var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
-var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
-var DEFAULT_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
-var DEFAULT_SNAPSHOT_MAX_ENTRIES = 1e4;
-var DEFAULT_INVALIDATION_MAX_KEYS = 1e4;
-var DEFAULT_MAX_PROFILE_ENTRIES = 1e5;
-var DebugLogger = class {
-  enabled;
-  constructor(enabled) {
-    this.enabled = enabled;
-  }
-  debug(message, context) {
-    this.write("debug", message, context);
-  }
-  info(message, context) {
-    this.write("info", message, context);
-  }
-  warn(message, context) {
-    this.write("warn", message, context);
-  }
-  error(message, context) {
-    this.write("error", message, context);
-  }
-  write(level, message, context) {
-    if (!this.enabled) {
-      return;
-    }
-    const suffix = context ? ` ${JSON.stringify(context)}` : "";
-    console[level](`[layercache] ${message}${suffix}`);
-  }
-};
-var CacheStack = class extends EventEmitter {
-  constructor(layers, options = {}) {
-    super();
-    this.layers = layers;
-    this.options = options;
-    if (layers.length === 0) {
-      throw new Error("CacheStack requires at least one cache layer.");
-    }
-    this.validateConfiguration();
-    const maxProfileEntries = options.maxProfileEntries ?? DEFAULT_MAX_PROFILE_ENTRIES;
-    this.ttlResolver = new TtlResolver({ maxProfileEntries });
-    this.circuitBreakerManager = new CircuitBreakerManager({ maxEntries: maxProfileEntries });
-    this.stampedeGuard = new StampedeGuard({
-      maxInFlight: options.stampedeMaxInFlight,
-      entryTimeoutMs: options.stampedeEntryTimeoutMs
-    });
-    this.currentGeneration = options.generation;
-    if (options.publishSetInvalidation !== void 0) {
-      console.warn(
-        "[layercache] CacheStackOptions.publishSetInvalidation is deprecated. Use broadcastL1Invalidation instead."
-      );
-    }
-    const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
-    this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
-    this.tagIndex = options.tagIndex ?? new TagIndex();
-    this.keyDiscovery = new CacheKeyDiscovery({
-      layers: this.layers,
-      tagIndex: this.tagIndex,
-      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
-      handleLayerFailure: async (layer, operation, error) => {
-        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."
-      );
-    }
-    if (!options.tagIndex && layers.some((layer) => layer.isLocal === false && !layer.keys)) {
-      this.logger.warn?.(
-        "Using the default in-memory TagIndex with a shared cache layer that does not implement keys() can leave invalidateByPattern() and invalidateByPrefix() incomplete after restarts. Use RedisTagIndex or implement keys() on the shared layer."
-      );
-    }
-    if (options.invalidationBus && options.broadcastL1Invalidation === void 0 && options.publishSetInvalidation === void 0) {
-      this.logger.warn?.(
-        "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),
-      shouldSkipLayer: (layer) => this.shouldSkipLayer(layer),
-      handleLayerFailure: async (layer, operation, error) => this.handleLayerFailure(layer, operation, error),
-      qualifyKey: this.qualifyKey.bind(this),
-      stripQualifiedKey: this.stripQualifiedKey.bind(this),
-      validateCacheKey,
-      formatError: this.formatError.bind(this)
-    });
-    this.initializeWriteBehind(options.writeBehind);
-    this.startup = this.initialize();
-  }
-  layers;
-  options;
-  stampedeGuard;
-  metricsCollector = new MetricsCollector();
-  instanceId = createInstanceId();
-  startup;
-  unsubscribeInvalidation;
-  logger;
-  tagIndex;
-  keyDiscovery;
-  fetchRateLimiter = new FetchRateLimiter();
-  snapshotSerializer = new JsonSerializer();
-  invalidation;
-  layerWriter;
-  snapshots;
-  backgroundRefreshes = /* @__PURE__ */ new Map();
-  backgroundRefreshAbort = /* @__PURE__ */ new Map();
-  layerDegradedUntil = /* @__PURE__ */ new Map();
-  maintenance = new CacheStackMaintenance();
-  ttlResolver;
-  circuitBreakerManager;
-  nextOperationId = 0;
-  currentGeneration;
-  isDisconnecting = false;
-  disconnectPromise;
-  /**
-   * Read-through cache get.
-   * Returns the cached value if present and fresh, or invokes `fetcher` on a miss
-   * and stores the result across all layers. Returns `null` if the key is not found
-   * and no `fetcher` is provided.
-   */
-  async get(key, 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");
-    if (hit.found) {
-      this.ttlResolver.recordAccess(normalizedKey);
-      if (this.isNegativeStoredValue(hit.stored)) {
-        this.metricsCollector.increment("negativeCacheHits");
-      }
-      if (hit.state === "fresh") {
-        this.metricsCollector.increment("hits");
-        await this.applyFreshReadPolicies(normalizedKey, hit, options, fetcher);
-        return hit.value;
-      }
-      if (hit.state === "stale-while-revalidate") {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        if (fetcher) {
-          this.scheduleBackgroundRefresh(normalizedKey, fetcher, options);
-        }
-        return hit.value;
-      }
-      if (!fetcher) {
-        this.metricsCollector.increment("hits");
-        this.metricsCollector.increment("staleHits");
-        this.emit("stale-serve", { key: normalizedKey, state: hit.state, layer: hit.layerName });
-        return hit.value;
-      }
-      try {
-        return await this.fetchWithGuards(normalizedKey, fetcher, options);
-      } catch (error) {
-        this.metricsCollector.increment("staleHits");
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("stale-if-error", { key: normalizedKey, error: this.formatError(error) });
-        return hit.value;
-      }
-    }
-    this.metricsCollector.increment("misses");
-    if (!fetcher) {
-      return null;
-    }
-    return this.fetchWithGuards(normalizedKey, fetcher, options, void 0, void 0, true);
-  }
-  /**
-   * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
-   * Fetches and caches the value if not already present.
-   */
-  async getOrSet(key, fetcher, options) {
-    return this.get(key, fetcher, options);
-  }
-  /**
-   * Like `get()`, but throws `CacheMissError` instead of returning `null`.
-   * Useful when the value is expected to exist or the fetcher is expected to
-   * return non-null.
-   */
-  async getOrThrow(key, fetcher, options) {
-    const value = await this.get(key, fetcher, options);
-    if (value === null) {
-      throw new CacheMissError(key);
-    }
-    return value;
-  }
-  /**
-   * Returns true if the given key exists and is not expired in any layer.
-   */
-  async has(key) {
-    const normalizedKey = this.qualifyKey(validateCacheKey(key));
-    await this.awaitStartup("has");
-    for (const layer of this.layers) {
-      if (this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      if (layer.has) {
-        try {
-          const exists = await layer.has(normalizedKey);
-          if (exists) {
-            return true;
-          }
-        } catch {
-          await this.reportRecoverableLayerFailure(layer, "has", new Error(`has() failed for layer "${layer.name}"`));
-        }
-      } else {
-        try {
-          const value = await layer.get(normalizedKey);
-          if (value !== null) {
-            return true;
-          }
-        } catch (error) {
-          await this.reportRecoverableLayerFailure(layer, "has", error);
-        }
-      }
-    }
-    return false;
-  }
-  /**
-   * Returns the remaining TTL in seconds for the key in the fastest layer
-   * that has it, or null if the key is not found / has no TTL.
-   */
-  async ttl(key) {
-    const normalizedKey = this.qualifyKey(validateCacheKey(key));
-    await this.awaitStartup("ttl");
-    for (const layer of this.layers) {
-      if (this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      if (layer.ttl) {
-        try {
-          const remaining = await layer.ttl(normalizedKey);
-          if (remaining !== null) {
-            return remaining;
-          }
-        } catch {
-        }
-      }
-    }
-    return null;
-  }
-  /**
-   * Stores a value in all cache layers. Overwrites any existing value.
-   */
-  async set(key, 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) {
-    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.maintenance.beginClearEpoch();
-    await Promise.all(this.layers.map((layer) => layer.clear()));
-    await this.tagIndex.clear();
-    this.ttlResolver.clearProfiles();
-    this.circuitBreakerManager.clear();
-    this.metricsCollector.increment("invalidations");
-    this.logger.debug?.("clear");
-    await this.publishInvalidation({ scope: "clear", sourceId: this.instanceId, operation: "clear" });
-  }
-  /**
-   * Deletes multiple keys at once. More efficient than calling `delete()` in a loop.
-   */
-  async mdelete(keys) {
-    if (keys.length === 0) {
-      return;
-    }
-    await this.awaitStartup("mdelete");
-    const normalizedKeys = keys.map((k) => validateCacheKey(k));
-    const cacheKeys = normalizedKeys.map((key) => this.qualifyKey(key));
-    await this.deleteKeys(cacheKeys);
-    await this.publishInvalidation({
-      scope: "keys",
-      keys: cacheKeys,
-      sourceId: this.instanceId,
-      operation: "delete"
-    });
-  }
-  async mget(entries) {
-    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) {
-              const displayKey = entry.key.length > 64 ? `${entry.key.slice(0, 64)}...` : entry.key;
-              throw new Error(`mget received conflicting entries for key "${displayKey}".`);
-            }
-            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 || this.shouldSkipLayer(layer)) continue;
-        const keys = [...pending];
-        if (keys.length === 0) {
-          break;
-        }
-        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;
-          }
-          if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
-            this.metricsCollector.increment("staleHits", 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);
-        }
-      }
-      return normalizedEntries.map((entry) => resultsByKey.get(entry.key) ?? null);
-    });
-  }
-  async mset(entries) {
-    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");
-    const concurrency = Math.max(1, options.concurrency ?? 4);
-    const total = entries.length;
-    let completed = 0;
-    const queue = [...entries].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0));
-    const workers = Array.from({ length: Math.min(concurrency, queue.length || 1) }, async () => {
-      while (queue.length > 0) {
-        const entry = queue.shift();
-        if (!entry) {
-          return;
-        }
-        let success = false;
-        try {
-          await this.get(entry.key, entry.fetcher, entry.options);
-          this.emit("warm", { key: entry.key });
-          success = true;
-        } catch (error) {
-          this.emitError("warm", { key: entry.key, error: this.formatError(error) });
-          if (!options.continueOnError) {
-            throw error;
-          }
-        } finally {
-          completed += 1;
-          const progress = { completed, total, key: entry.key, success };
-          options.onProgress?.(progress);
-        }
-      }
-    });
-    await Promise.all(workers);
-  }
-  /**
-   * Returns a cached version of `fetcher`. The cache key is derived from
-   * `prefix` plus the serialized arguments unless a `keyResolver` is provided.
-   */
-  wrap(prefix, fetcher, options = {}) {
-    return (...args) => {
-      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);
-    };
-  }
-  /**
-   * Creates a `CacheNamespace` that automatically prefixes all keys with
-   * `prefix:`. Useful for multi-tenant or module-level isolation.
-   */
-  namespace(prefix) {
-    validateNamespaceKey(prefix);
-    return new CacheNamespace(this, prefix);
-  }
-  async invalidateByTag(tag) {
-    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") {
-    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) {
-    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.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;
-  }
-  getStats() {
-    return {
-      metrics: this.getMetrics(),
-      layers: this.layers.map((layer) => ({
-        name: layer.name,
-        isLocal: Boolean(layer.isLocal),
-        degradedUntil: this.layerDegradedUntil.get(layer.name) ?? null
-      })),
-      backgroundRefreshes: this.backgroundRefreshes.size
-    };
-  }
-  resetMetrics() {
-    this.metricsCollector.reset();
-  }
-  /**
-   * Returns computed hit-rate statistics (overall and per-layer).
-   */
-  getHitRate() {
-    return this.metricsCollector.hitRate();
-  }
-  async healthCheck() {
-    await this.startup;
-    return Promise.all(
-      this.layers.map(async (layer) => {
-        const startedAt = performance.now();
-        try {
-          const healthy = layer.ping ? await layer.ping() : true;
-          return {
-            layer: layer.name,
-            healthy,
-            latencyMs: performance.now() - startedAt
-          };
-        } catch (error) {
-          return {
-            layer: layer.name,
-            healthy: false,
-            latencyMs: performance.now() - startedAt,
-            error: this.formatError(error)
-          };
-        }
-      })
-    );
-  }
-  /**
-   * Rotates the active generation prefix used for all future cache keys.
-   * Previous-generation keys remain in the underlying layers until they expire,
-   * unless `generationCleanup` is enabled to prune them in the background.
-   */
-  bumpGeneration(nextGeneration) {
-    const current = this.currentGeneration ?? 0;
-    const previousGeneration = this.currentGeneration;
-    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;
-  }
-  /**
-   * Returns detailed metadata about a single cache key: which layers contain it,
-   * remaining fresh/stale/error TTLs, and associated tags.
-   * Returns `null` if the key does not exist in any layer.
-   */
-  async inspect(key) {
-    const userKey = validateCacheKey(key);
-    const normalizedKey = this.qualifyKey(userKey);
-    await this.awaitStartup("inspect");
-    const foundInLayers = [];
-    let freshTtlSeconds = null;
-    let staleTtlSeconds = null;
-    let errorTtlSeconds = null;
-    let isStale = false;
-    for (const layer of this.layers) {
-      if (this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      const stored = await this.readLayerEntry(layer, normalizedKey);
-      if (stored === null) {
-        continue;
-      }
-      const resolved = resolveStoredValue(stored);
-      if (resolved.state === "expired") {
-        continue;
-      }
-      foundInLayers.push(layer.name);
-      if (foundInLayers.length === 1 && resolved.envelope) {
-        const now = Date.now();
-        freshTtlSeconds = resolved.envelope.freshUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.freshUntil - now) / 1e3)) : null;
-        staleTtlSeconds = resolved.envelope.staleUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.staleUntil - now) / 1e3)) : null;
-        errorTtlSeconds = resolved.envelope.errorUntil !== null ? Math.max(0, Math.ceil((resolved.envelope.errorUntil - now) / 1e3)) : null;
-        isStale = resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error";
-      }
-    }
-    if (foundInLayers.length === 0) {
-      return null;
-    }
-    const tags = await this.getTagsForKey(normalizedKey);
-    return { key: userKey, foundInLayers, freshTtlSeconds, staleTtlSeconds, errorTtlSeconds, isStale, tags };
-  }
-  async exportState() {
-    await this.awaitStartup("exportState");
-    return this.snapshots.exportState(this.snapshotMaxEntries());
-  }
-  async importState(entries) {
-    await this.awaitStartup("importState");
-    await this.snapshots.importState(entries);
-  }
-  async persistToFile(filePath) {
-    this.assertActive("persistToFile");
-    await this.snapshots.persistToFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxEntries());
-  }
-  async restoreFromFile(filePath) {
-    this.assertActive("restoreFromFile");
-    await this.snapshots.restoreFromFile(filePath, this.options.snapshotBaseDir, this.snapshotMaxBytes());
-  }
-  async disconnect() {
-    if (!this.disconnectPromise) {
-      this.isDisconnecting = true;
-      this.disconnectPromise = (async () => {
-        await this.startup;
-        await this.unsubscribeInvalidation?.();
-        await this.flushWriteBehindQueue();
-        await this.maintenance.waitForGenerationCleanup();
-        for (const key of this.backgroundRefreshAbort.keys()) {
-          this.backgroundRefreshAbort.set(key, true);
-        }
-        await Promise.allSettled(
-          [...this.backgroundRefreshes.values()].map((promise) => {
-            let timer;
-            return Promise.race([
-              promise,
-              new Promise((resolve) => {
-                timer = setTimeout(resolve, 5e3);
-                timer.unref?.();
-              })
-            ]).finally(() => {
-              if (timer) clearTimeout(timer);
-            });
-          })
-        );
-        this.backgroundRefreshes.clear();
-        this.backgroundRefreshAbort.clear();
-        this.maintenance.disposeWriteBehindTimer();
-        this.fetchRateLimiter.dispose();
-        await Promise.allSettled(this.layers.map((layer) => layer.dispose?.() ?? Promise.resolve()));
-      })();
-    }
-    await this.disconnectPromise;
-  }
-  async initialize() {
-    if (!this.options.invalidationBus) {
-      return;
-    }
-    this.unsubscribeInvalidation = await this.options.invalidationBus.subscribe(async (message) => {
-      await this.handleInvalidationMessage(message);
-    });
-  }
-  async fetchWithGuards(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, initialMissConfirmed = false) {
-    const fetchTask = async () => {
-      const shouldRecheckFreshLayers = !(initialMissConfirmed && this.options.singleFlightCoordinator);
-      if (shouldRecheckFreshLayers) {
-        const secondHit = await this.readFromLayers(key, options, "fresh-only");
-        if (secondHit.found) {
-          this.metricsCollector.increment("hits");
-          return secondHit.value;
-        }
-      }
-      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-    };
-    const singleFlightTask = async () => {
-      if (!this.options.singleFlightCoordinator) {
-        return fetchTask();
-      }
-      try {
-        return await this.options.singleFlightCoordinator.execute(
-          key,
-          this.resolveSingleFlightOptions(),
-          fetchTask,
-          () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch)
-        );
-      } catch (error) {
-        if (!this.isGracefulDegradationEnabled()) {
-          throw error;
-        }
-        this.metricsCollector.increment("degradedOperations");
-        this.logger.warn?.("single-flight-coordinator-degraded", { key, error: this.formatError(error) });
-        this.emitError("single-flight", { key, degraded: true, error: this.formatError(error) });
-        return fetchTask();
-      }
-    };
-    if (this.options.stampedePrevention === false) {
-      return singleFlightTask();
-    }
-    return this.stampedeGuard.execute(key, singleFlightTask);
-  }
-  async waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
-    const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
-    const deadline = Date.now() + timeoutMs;
-    this.metricsCollector.increment("singleFlightWaits");
-    this.emit("stampede-dedupe", { key });
-    while (Date.now() < deadline) {
-      const hit = await this.readFromLayers(key, options, "fresh-only");
-      if (hit.found) {
-        this.metricsCollector.increment("hits");
-        return hit.value;
-      }
-      await this.sleep(pollIntervalMs);
-    }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch);
-  }
-  async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    this.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
-    this.metricsCollector.increment("fetches");
-    const fetchStart = Date.now();
-    let fetched;
-    try {
-      fetched = await this.fetchRateLimiter.schedule(
-        options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
-        { key, fetcher },
-        fetcher
-      );
-      this.circuitBreakerManager.recordSuccess(key);
-      this.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
-    } catch (error) {
-      this.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
-      throw error;
-    }
-    if (fetched === null || fetched === void 0) {
-      if (!this.shouldNegativeCache(options)) {
-        return null;
-      }
-      if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-        this.logger.debug?.("skip-negative-store-after-invalidation", {
-          key,
-          expectedClearEpoch,
-          clearEpoch: this.maintenance.currentClearEpoch(),
-          expectedKeyEpoch,
-          keyEpoch: this.maintenance.currentKeyEpoch(key)
-        });
-        return null;
-      }
-      await this.storeEntry(key, "empty", null, options);
-      return null;
-    }
-    if (options?.shouldCache) {
-      try {
-        if (!options.shouldCache(fetched)) {
-          return fetched;
-        }
-      } catch (error) {
-        this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
-      }
-    }
-    if (this.maintenance.isWriteOutdated(key, expectedClearEpoch, expectedKeyEpoch)) {
-      this.logger.debug?.("skip-store-after-invalidation", {
-        key,
-        expectedClearEpoch,
-        clearEpoch: this.maintenance.currentClearEpoch(),
-        expectedKeyEpoch,
-        keyEpoch: this.maintenance.currentKeyEpoch(key)
-      });
-      return fetched;
-    }
-    await this.storeEntry(key, "value", fetched, options);
-    return fetched;
-  }
-  async storeEntry(key, kind, value, options) {
-    const clearEpoch = this.maintenance.currentClearEpoch();
-    const keyEpoch = this.maintenance.currentKeyEpoch(key);
-    await this.layerWriter.writeAcrossLayers(key, kind, value, options);
-    if (this.maintenance.isWriteOutdated(key, clearEpoch, keyEpoch)) {
-      return;
-    }
-    if (options?.tags) {
-      await this.tagIndex.track(key, options.tags);
-    } else {
-      await this.tagIndex.touch(key);
-    }
-    this.metricsCollector.increment("sets");
-    this.logger.debug?.("set", { key, kind, tags: options?.tags });
-    this.emit("set", { key, kind, tags: options?.tags });
-    if (this.shouldBroadcastL1Invalidation()) {
-      await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
-    }
-  }
-  async writeBatch(entries) {
-    const { clearEpoch, entryEpochs } = await this.layerWriter.writeBatch(entries);
-    if (clearEpoch !== this.maintenance.currentClearEpoch()) {
-      return;
-    }
-    for (const entry of entries) {
-      if (this.maintenance.isWriteOutdated(entry.key, clearEpoch, entryEpochs.get(entry.key))) {
-        continue;
-      }
-      if (entry.options?.tags) {
-        await this.tagIndex.track(entry.key, entry.options.tags);
-      } else {
-        await this.tagIndex.touch(entry.key);
-      }
-      this.metricsCollector.increment("sets");
-      this.logger.debug?.("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
-      this.emit("set", { key: entry.key, kind: "value", tags: entry.options?.tags });
-    }
-    if (this.shouldBroadcastL1Invalidation()) {
-      await this.publishInvalidation({
-        scope: "keys",
-        keys: entries.map((entry) => entry.key),
-        sourceId: this.instanceId,
-        operation: "write"
-      });
-    }
-  }
-  async readFromLayers(key, options, mode) {
-    let sawRetainableValue = false;
-    for (let index = 0; index < this.layers.length; index += 1) {
-      const layer = this.layers[index];
-      if (!layer) continue;
-      const readStart = performance.now();
-      const stored = await this.readLayerEntry(layer, key);
-      const readDuration = performance.now() - readStart;
-      this.metricsCollector.recordLatency(layer.name, readDuration);
-      if (stored === null) {
-        this.metricsCollector.incrementLayer("missesByLayer", layer.name);
-        continue;
-      }
-      const resolved = resolveStoredValue(stored);
-      if (resolved.state === "expired") {
-        await layer.delete(key);
-        continue;
-      }
-      sawRetainableValue = true;
-      if (mode === "fresh-only" && resolved.state !== "fresh") {
-        continue;
-      }
-      await this.tagIndex.touch(key);
-      await this.backfill(key, stored, index - 1, options);
-      this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
-      this.logger.debug?.("hit", { key, layer: layer.name, state: resolved.state });
-      this.emit("hit", { key, layer: layer.name, state: resolved.state });
-      return {
-        found: true,
-        value: resolved.value,
-        stored,
-        state: resolved.state,
-        layerIndex: index,
-        layerName: layer.name
-      };
-    }
-    if (!sawRetainableValue) {
-      await this.tagIndex.remove(key);
-    }
-    this.logger.debug?.("miss", { key, mode });
-    this.emit("miss", { key, mode });
-    return { found: false, value: null, stored: null, state: "miss" };
-  }
-  async readLayerEntry(layer, key) {
-    if (this.shouldSkipLayer(layer)) {
-      return null;
-    }
-    if (layer.getEntry) {
-      try {
-        return await layer.getEntry(key);
-      } catch (error) {
-        return this.handleLayerFailure(layer, "read", error);
-      }
-    }
-    try {
-      return await layer.get(key);
-    } catch (error) {
-      return this.handleLayerFailure(layer, "read", error);
-    }
-  }
-  async backfill(key, stored, upToIndex, options) {
-    if (upToIndex < 0) {
-      return;
-    }
-    for (let index = 0; index <= upToIndex; index += 1) {
-      const layer = this.layers[index];
-      if (!layer || this.shouldSkipLayer(layer)) {
-        continue;
-      }
-      const ttl = remainingStoredTtlSeconds(stored) ?? this.resolveLayerSeconds(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      try {
-        await layer.set(key, stored, ttl);
-      } catch (error) {
-        await this.handleLayerFailure(layer, "backfill", error);
-        continue;
-      }
-      this.metricsCollector.increment("backfills");
-      this.logger.debug?.("backfill", { key, layer: layer.name });
-      this.emit("backfill", { key, layer: layer.name });
-    }
-  }
-  resolveFreshTtl(key, layerName, kind, options, fallbackTtl, value) {
-    return this.ttlResolver.resolveFreshTtl(
-      key,
-      layerName,
-      kind,
-      options,
-      fallbackTtl,
-      this.options.negativeTtl,
-      void 0,
-      value
-    );
-  }
-  resolveLayerSeconds(layerName, override, globalDefault, fallback) {
-    return this.ttlResolver.resolveLayerSeconds(layerName, override, globalDefault, fallback);
-  }
-  shouldNegativeCache(options) {
-    return options?.negativeCache ?? this.options.negativeCaching ?? false;
-  }
-  scheduleBackgroundRefresh(key, fetcher, options) {
-    if (!shouldStartBackgroundRefresh({
-      isDisconnecting: this.isDisconnecting,
-      hasRefreshInFlight: this.backgroundRefreshes.has(key)
-    })) {
-      return;
-    }
-    const clearEpoch = this.maintenance.currentClearEpoch();
-    const keyEpoch = this.maintenance.currentKeyEpoch(key);
-    this.backgroundRefreshAbort.set(key, false);
-    const refresh = (async () => {
-      this.metricsCollector.increment("refreshes");
-      try {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        await this.runBackgroundRefresh(key, fetcher, options, clearEpoch, keyEpoch);
-      } catch (error) {
-        if (this.backgroundRefreshAbort.get(key)) return;
-        this.metricsCollector.increment("refreshErrors");
-        this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
-      } finally {
-        this.backgroundRefreshes.delete(key);
-        this.backgroundRefreshAbort.delete(key);
-      }
-    })();
-    this.backgroundRefreshes.set(key, refresh);
-  }
-  async runBackgroundRefresh(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch) {
-    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
-    await this.fetchWithGuards(
-      key,
-      () => this.withTimeout(fetcher(), timeoutMs, () => {
-        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
-      }),
-      options,
-      expectedClearEpoch,
-      expectedKeyEpoch
-    );
-  }
-  resolveSingleFlightOptions() {
-    return {
-      leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
-      waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
-      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
-      renewIntervalMs: this.options.singleFlightRenewIntervalMs
-    };
-  }
-  async deleteKeys(keys) {
-    if (keys.length === 0) {
-      return;
-    }
-    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);
-      this.circuitBreakerManager.delete(key);
-    }
-    this.metricsCollector.increment("deletes", keys.length);
-    this.metricsCollector.increment("invalidations");
-    this.logger.debug?.("delete", { keys });
-    this.emit("delete", { keys });
-  }
-  async publishInvalidation(message) {
-    if (!this.options.invalidationBus) {
-      return;
-    }
-    await this.options.invalidationBus.publish(message);
-  }
-  async handleInvalidationMessage(message) {
-    if (message.sourceId === this.instanceId) {
-      return;
-    }
-    const localLayers = this.layers.filter((layer) => layer.isLocal);
-    if (message.scope === "clear") {
-      this.maintenance.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.maintenance.bumpKeyEpochs(keys);
-    await this.invalidation.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);
-      }
-    }
-  }
-  async getTagsForKey(key) {
-    if (this.tagIndex.tagsForKey) {
-      return this.tagIndex.tagsForKey(key);
-    }
-    return [];
-  }
-  formatError(error) {
-    if (error instanceof Error) {
-      return error.message;
-    }
-    return String(error);
-  }
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-  async withTimeout(promise, timeoutMs, onTimeout) {
-    if (timeoutMs <= 0) {
-      return promise;
-    }
-    let timer;
-    const observedPromise = promise.then(
-      (value) => ({ kind: "value", value }),
-      (error) => ({ kind: "error", error })
-    );
-    try {
-      const result = await Promise.race([
-        observedPromise,
-        new Promise((_, reject) => {
-          timer = setTimeout(() => reject(onTimeout()), timeoutMs);
-          timer.unref?.();
-        })
-      ]);
-      if (result !== null && result !== void 0 && typeof result === "object" && "kind" in result) {
-        if (result.kind === "error") {
-          throw result.error;
-        }
-        return result.value;
-      }
-      return result;
-    } finally {
-      if (timer) {
-        clearTimeout(timer);
-      }
-    }
-  }
-  shouldBroadcastL1Invalidation() {
-    return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
-  }
-  async observeOperation(name, attributes, execute) {
-    const id = this.nextOperationId;
-    this.nextOperationId = (this.nextOperationId + 1) % Number.MAX_SAFE_INTEGER;
-    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) {
-    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);
-    for (const batch of planGenerationCleanupBatches(keys, this.options.generationCleanup)) {
-      await this.deleteKeys(batch);
-      await this.publishInvalidation({
-        scope: "keys",
-        keys: batch,
-        sourceId: this.instanceId,
-        operation: "invalidate"
-      });
-    }
-  }
-  initializeWriteBehind(options) {
-    this.maintenance.initializeWriteBehindTimer(
-      this.options.writeStrategy,
-      options,
-      this.flushWriteBehindQueue.bind(this)
-    );
-  }
-  shouldWriteBehind(layer) {
-    return this.options.writeStrategy === "write-behind" && !layer.isLocal;
-  }
-  async enqueueWriteBehind(operation) {
-    await this.maintenance.enqueueWriteBehind(operation, this.options.writeBehind, this.runWriteBehindBatch.bind(this));
-  }
-  async flushWriteBehindQueue() {
-    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;
-    }
-    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 });
-  }
-  qualifyKey(key) {
-    return qualifyGenerationKey(key, this.currentGeneration);
-  }
-  qualifyPattern(pattern) {
-    return qualifyGenerationPattern(pattern, this.currentGeneration);
-  }
-  stripQualifiedKey(key) {
-    return stripGenerationPrefix(key, this.currentGeneration);
-  }
-  validateConfiguration() {
-    if (this.options.broadcastL1Invalidation !== void 0 && this.options.publishSetInvalidation !== void 0 && this.options.broadcastL1Invalidation !== this.options.publishSetInvalidation) {
-      throw new Error("broadcastL1Invalidation and publishSetInvalidation cannot conflict.");
-    }
-    if (this.options.stampedePrevention === false && this.options.singleFlightCoordinator) {
-      throw new Error("singleFlightCoordinator requires stampedePrevention to remain enabled.");
-    }
-    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") {
-      validatePositiveNumber("generationCleanup.batchSize", this.options.generationCleanup.batchSize);
-    }
-    if (this.options.generation !== void 0) {
-      validateNonNegativeNumber("generation", this.options.generation);
-    }
-  }
-  validateWriteOptions(options) {
-    if (!options) {
-      return;
-    }
-    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) {
-      throw new Error(`CacheStack is disconnecting; cannot perform ${operation}.`);
-    }
-  }
-  async awaitStartup(operation) {
-    this.assertActive(operation);
-    await this.startup;
-    this.assertActive(operation);
-  }
-  async applyFreshReadPolicies(key, hit, options, fetcher) {
-    const plan = planFreshReadPolicies({
-      stored: hit.stored,
-      hasFetcher: Boolean(fetcher),
-      slidingTtl: options?.slidingTtl ?? false,
-      refreshAheadSeconds: this.resolveLayerSeconds(hit.layerName, options?.refreshAhead, this.options.refreshAhead, 0) ?? 0
-    });
-    if (plan.refreshedStored) {
-      for (let index = 0; index <= hit.layerIndex; index += 1) {
-        const layer = this.layers[index];
-        if (!layer || this.shouldSkipLayer(layer)) {
-          continue;
-        }
-        try {
-          await layer.set(key, plan.refreshedStored, plan.refreshedStoredTtl);
-        } catch (error) {
-          await this.handleLayerFailure(layer, "sliding-ttl", error);
-        }
-      }
-    }
-    if (fetcher && plan.shouldScheduleBackgroundRefresh) {
-      this.scheduleBackgroundRefresh(key, fetcher, options);
-    }
-  }
-  shouldSkipLayer(layer) {
-    return shouldSkipLayer(this.layerDegradedUntil.get(layer.name));
-  }
-  async handleLayerFailure(layer, operation, error) {
-    const recovery = resolveRecoverableLayerFailure(this.options.gracefulDegradation);
-    if (!recovery.degrade) {
-      throw error;
-    }
-    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) });
-    return null;
-  }
-  async reportRecoverableLayerFailure(layer, operation, error) {
-    if (this.isGracefulDegradationEnabled()) {
-      await this.handleLayerFailure(layer, operation, error);
-      return;
-    }
-    this.logger.warn?.("layer-operation-failed", { layer: layer.name, operation, error: this.formatError(error) });
-    this.emitError(operation, { layer: layer.name, degraded: false, error: this.formatError(error) });
-  }
-  isGracefulDegradationEnabled() {
-    return Boolean(this.options.gracefulDegradation);
-  }
-  recordCircuitFailure(key, options, error) {
-    if (!options) {
-      return;
-    }
-    this.circuitBreakerManager.recordFailure(key, options);
-    if (this.circuitBreakerManager.isOpen(key)) {
-      this.metricsCollector.increment("circuitBreakerTrips");
-    }
-    this.emitError("fetch", { key, error: this.formatError(error) });
-  }
-  isNegativeStoredValue(stored) {
-    return isStoredValueEnvelope(stored) && stored.kind === "empty";
-  }
-  emitError(operation, context) {
-    this.logger.error?.(operation, context);
-    if (this.listenerCount("error") > 0) {
-      this.emit("error", { operation, ...context });
-    }
-  }
-  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;
-  }
-};
-
-// src/module.ts
-var InjectCacheStack = () => Inject(CACHE_STACK);
-var CacheStackModule = class {
-  static forRoot(options) {
-    const provider = {
-      provide: CACHE_STACK,
-      useFactory: () => new CacheStack(options.layers, options.bridgeOptions)
-    };
-    return {
-      global: true,
-      module: CacheStackModule,
-      providers: [provider],
-      exports: [provider]
-    };
-  }
-  static forRootAsync(options) {
-    const provider = {
-      provide: CACHE_STACK,
-      inject: options.inject ?? [],
-      useFactory: async (...args) => {
-        const resolved = await options.useFactory(...args);
-        return new CacheStack(resolved.layers, resolved.bridgeOptions);
-      }
-    };
-    return {
-      global: true,
-      module: CacheStackModule,
-      providers: [provider],
-      exports: [provider]
-    };
-  }
-};
-CacheStackModule = __decorateClass([
-  Global(),
-  Module({})
-], CacheStackModule);
-export {
-  CACHE_STACK,
-  CacheStackModule,
-  Cacheable,
-  InjectCacheStack
-};