@warlock.js/cache 4.0.174 → 4.1.1

package/cjs/index.cjs

@@ -0,0 +1,4088 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let _mongez_reinforcements = require("@mongez/reinforcements");
+let ms = require("ms");
+ms = __toESM(ms, 1);
+let _warlock_js_logger = require("@warlock.js/logger");
+let _warlock_js_fs = require("@warlock.js/fs");
+let path = require("path");
+path = __toESM(path, 1);
+
+//#region ../../@warlock.js/cache/src/metrics.ts
+/**
+* Default size of the circular latency-sample buffer. 1000 samples covers
+* "tell me the current p95" for every realistic workload while keeping the
+* memory cost negligible (8KB at 8 bytes per number).
+*/
+const DEFAULT_LATENCY_BUFFER_SIZE = 1e3;
+/**
+* Listens to `CacheManager` events and accumulates running counters + a
+* circular latency buffer per driver. Returned to consumers via
+* `cache.metrics()` as a {@link CacheMetricsSnapshot}.
+*
+* **Role.** Single-instance observability layer attached to the manager.
+* Subscribes once at construction; survives `cache.use()` driver switches
+* because the global event registry on the manager re-attaches handlers to
+* every loaded driver.
+*
+* **Responsibility.**
+* - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,
+*   `removed`, `errors`), the latency circular buffer, and snapshot
+*   computation including hit-rate + percentile calculation.
+* - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),
+*   timing instrumentation (done at the manager level via `recordLatency`),
+*   or persistence — every metric resets on `resetMetrics()` and on process
+*   restart.
+*
+* @example
+* cache.metrics();
+* // {
+* //   hits: 9821, misses: 173, hitRate: 0.983,
+* //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },
+* //   byDriver: { memory: { ... }, redis: { ... } },
+* //   startedAt: 1714185600000,
+* // }
+*/
+var CacheMetricsCollector = class {
+	constructor(bufferSize = DEFAULT_LATENCY_BUFFER_SIZE) {
+		this.byDriver = /* @__PURE__ */ new Map();
+		this.startedAt = Date.now();
+		this.bufferSize = bufferSize;
+		this.aggregate = this.createCounters();
+	}
+	/**
+	* Increment the appropriate counters for a cache event. Called from the
+	* manager's global listeners (one per event type).
+	*/
+	recordEvent(event, data) {
+		const driverBucket = this.bucketFor(data.driver);
+		const aggregate = this.aggregate;
+		switch (event) {
+			case "hit":
+				aggregate.hits += 1;
+				driverBucket.hits += 1;
+				break;
+			case "miss":
+				aggregate.misses += 1;
+				driverBucket.misses += 1;
+				break;
+			case "set":
+				aggregate.sets += 1;
+				driverBucket.sets += 1;
+				break;
+			case "removed":
+				aggregate.removed += 1;
+				driverBucket.removed += 1;
+				break;
+			case "error":
+				aggregate.errors += 1;
+				driverBucket.errors += 1;
+				break;
+		}
+	}
+	/**
+	* Append a latency sample for `driver`. Called by the manager from its
+	* timed wrappers around `get` / `set` / `remove`. Uses circular-buffer
+	* semantics: oldest samples are overwritten once the buffer is full.
+	*/
+	recordLatency(driver, durationMs) {
+		this.appendLatency(this.aggregate, durationMs);
+		this.appendLatency(this.bucketFor(driver), durationMs);
+	}
+	/**
+	* Compute and return the current snapshot. Latency percentiles are
+	* derived from a sorted copy of the buffer at call time — O(N log N)
+	* on N=1000 is cheap enough that we don't bother caching.
+	*/
+	snapshot() {
+		const byDriver = {};
+		for (const [driverName, bucket] of this.byDriver) byDriver[driverName] = this.toRow(bucket);
+		return {
+			...this.toRow(this.aggregate),
+			byDriver,
+			startedAt: this.startedAt
+		};
+	}
+	/**
+	* Wipe every counter, drop every latency sample, and reset `startedAt`.
+	* The collector itself stays subscribed to events.
+	*/
+	reset() {
+		this.resetCounters(this.aggregate);
+		this.byDriver.clear();
+		this.startedAt = Date.now();
+	}
+	/**
+	* Locate the per-driver bucket, creating it on first reference. Driver
+	* names are taken verbatim from `CacheEventData.driver`.
+	*/
+	bucketFor(driverName) {
+		let bucket = this.byDriver.get(driverName);
+		if (!bucket) {
+			bucket = this.createCounters();
+			this.byDriver.set(driverName, bucket);
+		}
+		return bucket;
+	}
+	/**
+	* Convert raw counters into the public snapshot row shape. Computes
+	* `hitRate` and the latency percentiles on the fly.
+	*/
+	toRow(bucket) {
+		const totalReads = bucket.hits + bucket.misses;
+		const hitRate = totalReads === 0 ? 0 : bucket.hits / totalReads;
+		const latency = this.computeLatency(bucket.latencySamples);
+		return {
+			hits: bucket.hits,
+			misses: bucket.misses,
+			sets: bucket.sets,
+			removed: bucket.removed,
+			errors: bucket.errors,
+			hitRate,
+			latencyMs: latency,
+			startedAt: this.startedAt
+		};
+	}
+	/**
+	* Sort a copy of the buffer and pick the percentile entries directly.
+	* Empty buffers return zeroed percentiles so consumers can render
+	* dashboards without null-checking.
+	*/
+	computeLatency(samples) {
+		if (samples.length === 0) return {
+			p50: 0,
+			p95: 0,
+			p99: 0,
+			samples: 0
+		};
+		const sorted = [...samples].sort((a, b) => a - b);
+		const pick = (quantile) => {
+			return sorted[Math.min(sorted.length - 1, Math.floor(quantile * sorted.length))];
+		};
+		return {
+			p50: pick(.5),
+			p95: pick(.95),
+			p99: pick(.99),
+			samples: sorted.length
+		};
+	}
+	/**
+	* Append a latency sample using circular-buffer semantics — overwrite the
+	* oldest entry once the buffer is full instead of growing unbounded.
+	*/
+	appendLatency(bucket, durationMs) {
+		if (bucket.latencySamples.length < this.bufferSize) {
+			bucket.latencySamples.push(durationMs);
+			return;
+		}
+		bucket.latencySamples[bucket.latencyCursor] = durationMs;
+		bucket.latencyCursor = (bucket.latencyCursor + 1) % this.bufferSize;
+	}
+	/** Build a fresh counter row with zeroed totals and an empty buffer. */
+	createCounters() {
+		return {
+			hits: 0,
+			misses: 0,
+			sets: 0,
+			removed: 0,
+			errors: 0,
+			latencySamples: [],
+			latencyCursor: 0
+		};
+	}
+	/** Reset an existing counter row in place. Used by `reset()` for the aggregate. */
+	resetCounters(bucket) {
+		bucket.hits = 0;
+		bucket.misses = 0;
+		bucket.sets = 0;
+		bucket.removed = 0;
+		bucket.errors = 0;
+		bucket.latencySamples.length = 0;
+		bucket.latencyCursor = 0;
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/types.ts
+/**
+* Base error class for cache-related errors
+*/
+var CacheError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CacheError";
+	}
+};
+/**
+* Error thrown when cache connection fails
+*/
+var CacheConnectionError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConnectionError";
+	}
+};
+/**
+* Error thrown when cache driver configuration is invalid
+*/
+var CacheConfigurationError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConfigurationError";
+	}
+};
+/**
+* Error thrown when cache driver is not initialized
+*/
+var CacheDriverNotInitializedError = class extends CacheError {
+	constructor(message = "No cache driver initialized. Call cache.init() or cache.use() first.") {
+		super(message);
+		this.name = "CacheDriverNotInitializedError";
+	}
+};
+/**
+* Error thrown when a driver does not implement a requested operation.
+*
+* Raised when a caller invokes a method the driver cannot fulfill —
+* e.g. `update()` on the file driver before the file-lock primitive lands.
+*/
+var CacheUnsupportedError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheUnsupportedError";
+	}
+};
+/**
+* Error thrown when an optimistic-concurrency update exhausts its retry budget.
+*/
+var CacheConcurrencyError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConcurrencyError";
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/utils.ts
+/**
+* Make a proper key for the cache
+*/
+function parseCacheKey(key, options = {}) {
+	if (typeof key === "object") key = JSON.stringify(key);
+	key = key.replace(/[{}"[\]]/g, "").replaceAll(/[:,]/g, ".");
+	const cachePrefix = typeof options.globalPrefix === "function" ? options.globalPrefix() : options.globalPrefix;
+	return (0, _mongez_reinforcements.rtrim)(String(cachePrefix ? (0, _mongez_reinforcements.rtrim)(cachePrefix, ".") + "." + key : key), ".");
+}
+/**
+* Parse a TTL value into seconds.
+*
+* Accepts:
+* - a number (already in seconds) — returned unchanged
+* - `Infinity` — no expiration, returned unchanged
+* - a human-readable duration string (e.g. `"1h"`, `"30m"`, `"7d"`) — parsed via `ms` then converted to seconds
+*
+* Throws `CacheConfigurationError` on unparseable strings or negative numbers.
+*
+* @example
+* parseTtl(3600);      // 3600
+* parseTtl("1h");      // 3600
+* parseTtl("7d");      // 604800
+* parseTtl(Infinity);  // Infinity
+*/
+function parseTtl(input) {
+	if (typeof input === "number") {
+		if (input < 0) throw new CacheConfigurationError(`Invalid TTL: negative number (${input}).`);
+		return input;
+	}
+	if (typeof input !== "string" || input.trim() === "") throw new CacheConfigurationError(`Invalid TTL: expected number or duration string, got ${typeof input}.`);
+	const milliseconds = (0, ms.default)(input);
+	if (milliseconds === void 0 || Number.isNaN(milliseconds)) throw new CacheConfigurationError(`Invalid TTL duration string: "${input}". Expected forms like "1h", "30m", "7d".`);
+	return Math.floor(milliseconds / 1e3);
+}
+/**
+* Convert an absolute `expiresAt` (Date or epoch milliseconds) into a
+* relative TTL in seconds.
+*
+* Throws {@link CacheConfigurationError} when the deadline is in the past —
+* the caller almost certainly has a bug (stale timestamp, wrong unit, etc.)
+* and silently storing an already-expired entry would hide it.
+*
+* @example
+* expiresAtToTtl(new Date(Date.now() + 60_000));   // ~60
+* expiresAtToTtl(Date.now() + 30 * 60 * 1000);     // ~1800
+*/
+function expiresAtToTtl(expiresAt) {
+	const deadline = expiresAt instanceof Date ? expiresAt.getTime() : expiresAt;
+	const relativeMs = deadline - Date.now();
+	if (relativeMs <= 0) throw new CacheConfigurationError(`\`expiresAt\` must be in the future; got ${new Date(deadline).toISOString()}.`);
+	return Math.ceil(relativeMs / 1e3);
+}
+/**
+* Coerce the polymorphic 3rd `set` argument into a uniform `CacheSetOptions`
+* shape. Lets callers (and `BaseCacheDriver.resolveSetOptions`) skip per-shape
+* branching.
+*
+* - `undefined` / `null` → `{}` (resolves to driver-level defaults later)
+* - `number` / `string` (positional TTL) → `{ ttl }`
+* - already an options object → returned as-is
+*/
+function normalizeToOptions(input) {
+	if (input === void 0 || input === null) return {};
+	if (typeof input === "number" || typeof input === "string") return { ttl: input };
+	return input;
+}
+/**
+* Sibling of {@link normalizeToOptions} for the `remember()` call site, where
+* the polymorphic 2nd argument is `CacheTtl | RememberOptions` (no `expiresAt`,
+* no `onConflict`). Returns the same shape so callers can `{ ...opts, ... }`
+* without branching.
+*
+* @example
+* normalizeToRememberOptions(60);             // { ttl: 60 }
+* normalizeToRememberOptions("1h");           // { ttl: "1h" }
+* normalizeToRememberOptions({ ttl: "1h", tags: ["x"] }); // returned as-is
+*/
+function normalizeToRememberOptions(input) {
+	if (input === void 0 || input === null) return {};
+	if (typeof input === "number" || typeof input === "string") return { ttl: input };
+	return input;
+}
+/**
+* Resolve the final TTL in seconds for a `set` call. Precedence:
+*
+* 1. Caller's `ttl` (number or duration string) wins.
+* 2. Otherwise, caller's `expiresAt` is converted to relative seconds.
+* 3. Otherwise, `fallback` is used (driver-level default — typically
+*    `Infinity` when no default is configured, meaning "never expires").
+*
+* Throws {@link CacheConfigurationError} when `ttl` and `expiresAt` are
+* supplied together (mutually exclusive).
+*/
+function resolveTtl(ttl, expiresAt, fallback) {
+	if (ttl !== void 0 && expiresAt !== void 0) throw new CacheConfigurationError("Cache set options cannot specify both `ttl` and `expiresAt` — choose one.");
+	if (ttl !== void 0) return parseTtl(ttl);
+	if (expiresAt !== void 0) return expiresAtToTtl(expiresAt);
+	return fallback;
+}
+/**
+* Combine any number of tag lists into a single deduped array, dropping
+* `undefined`/empty entries. Returns `undefined` when no tags survive — lets
+* callers skip emitting empty `tags: []` into option payloads.
+*
+* Used by scoped-cache merging where scope tags + handle tags + per-call tags
+* must union additively without duplicates.
+*
+* @example
+* mergeTagSets(["a", "b"], ["b", "c"]);          // ["a", "b", "c"]
+* mergeTagSets(undefined, ["x"]);                // ["x"]
+* mergeTagSets(undefined, undefined);            // undefined
+* mergeTagSets([], []);                          // undefined
+*/
+function mergeTagSets(...lists) {
+	const flat = [];
+	for (const list of lists) {
+		if (!list || list.length === 0) continue;
+		flat.push(...list);
+	}
+	if (flat.length === 0) return;
+	return Array.from(new Set(flat));
+}
+/**
+* Add extra tags to any option-bag that already shapes `tags?: string[]`.
+* Pure — clones the input shape, never mutates. Tags are appended (caller
+* is responsible for de-duplication if needed; pair with {@link mergeTagSets}).
+*
+* @example
+* injectTags({ ttl: "1h" }, ["unread"]);         // { ttl: "1h", tags: ["unread"] }
+* injectTags({ tags: ["a"] }, ["b"]);            // { tags: ["a", "b"] }
+*/
+function injectTags(options, extraTags) {
+	if (extraTags.length === 0) return options;
+	return {
+		...options,
+		tags: [...options.tags ?? [], ...extraTags]
+	};
+}
+/**
+* Cosine similarity between two equal-length numeric vectors.
+*
+* Returns a value in `[-1, 1]` where `1` means perfectly aligned, `0` means
+* orthogonal, and `-1` means opposing. For typical embedding spaces (where
+* vectors live in the positive cone) the practical range is `[0, 1]`.
+*
+* Throws {@link CacheConfigurationError} on dimension mismatch — fail loud at
+* the call site rather than silently returning a misleading score. A zero-norm
+* vector on either side returns `0` (no defined direction to compare).
+*
+* @example
+* cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
+* cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
+*/
+function cosineSimilarity(a, b) {
+	if (a.length !== b.length) throw new CacheConfigurationError(`Vector dimension mismatch: got ${a.length} and ${b.length}.`);
+	if (a.length === 0) throw new CacheConfigurationError("Vector dimension mismatch: empty vector cannot be compared.");
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		const y = b[i];
+		dot += x * y;
+		normA += x * x;
+		normB += y * y;
+	}
+	if (normA === 0 || normB === 0) return 0;
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+let CACHE_FOR = /* @__PURE__ */ function(CACHE_FOR) {
+	/**
+	* Cache for 30 Minutes (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_HOUR"] = 1800] = "HALF_HOUR";
+	/**
+	* Cache for 1 Hour (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_HOUR"] = 3600] = "ONE_HOUR";
+	/**
+	* Cache for 12 Hours (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_DAY"] = 43200] = "HALF_DAY";
+	/**
+	* Cache for 24 Hours (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_DAY"] = 86400] = "ONE_DAY";
+	/**
+	* Cache for 7 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_WEEK"] = 604800] = "ONE_WEEK";
+	/**
+	* Cache for 15 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_MONTH"] = 1296e3] = "HALF_MONTH";
+	/**
+	* Cache for 30 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_MONTH"] = 2592e3] = "ONE_MONTH";
+	/**
+	* Cache for 60 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["TWO_MONTHS"] = 5184e3] = "TWO_MONTHS";
+	/**
+	* Cache for 180 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["SIX_MONTHS"] = 15768e3] = "SIX_MONTHS";
+	/**
+	* Cache for 365 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_YEAR"] = 31536e3] = "ONE_YEAR";
+	return CACHE_FOR;
+}({});
+
+//#endregion
+//#region ../../@warlock.js/cache/src/tagged-scoped-cache.ts
+/**
+* One-shot tagged write handle on top of a {@link ScopedCache}.
+*
+* **Role.** Returned by `scope.tags([...])`. Adds a fixed list of tags to
+* every write produced through this handle, on top of any tags the parent
+* scope already contributes. Stateless except for the captured tag list.
+*
+* **Responsibility.**
+* - Owns: appending the handle's tags to writes, delegating tag-index
+*   bookkeeping for `setNX` (which lacks an inline `tags` knob on the driver
+*   contract), and computing the union for `invalidate()` calls.
+* - Does NOT own: storage, prefix-prepending (delegated to the scope),
+*   default `ttl` (delegated to the scope), or any kind of long-lived state.
+*
+* Tags compose additively: scope tags + handle tags + per-call tags, all
+* unioned and deduped. The handle never replaces scope tags — `invalidate()`
+* always sees the full union.
+*
+* @example
+* // Inside application code — scope provides the per-user tag automatically:
+* const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
+*
+* await feed.tags(["unread"]).set("messages.1", message);
+* // → tagged with [user.<id>, unread]
+*
+* await feed.tags(["unread"]).invalidate();
+* // → wipes everything tagged with user.<id> OR unread.
+*/
+var TaggedScopedCache = class {
+	/**
+	* Build a tagged handle. Constructed via `scope.tags([...])` — users never
+	* call this directly.
+	*/
+	constructor(scope, handleTags) {
+		this.scope = scope;
+		this.handleTags = [...handleTags];
+	}
+	/**
+	* Write the scoped key with the handle's tags appended to whatever the
+	* caller passed. Scope-level tags are added on top by the scope itself.
+	*/
+	set(key, value, ttlOrOptions) {
+		const options = injectTags(normalizeToOptions(ttlOrOptions), this.handleTags);
+		return this.scope.set(key, value, options);
+	}
+	/**
+	* Read the scoped key. Tags don't affect reads — pass-through.
+	*/
+	get(key) {
+		return this.scope.get(key);
+	}
+	/**
+	* Check presence of the scoped key.
+	*/
+	has(key) {
+		return this.scope.has(key);
+	}
+	/**
+	* Remove the scoped key. The tag-index entry will eventually be cleaned up
+	* by `invalidate()`; we don't proactively rewrite it here for cost reasons.
+	*/
+	remove(key) {
+		return this.scope.remove(key);
+	}
+	/**
+	* Read-and-remove the scoped key.
+	*/
+	pull(key) {
+		return this.scope.pull(key);
+	}
+	/**
+	* Permanent write with handle tags applied. Bypasses both the scope's and
+	* the caller's TTL (forever means forever) — only tags get injected.
+	*/
+	forever(key, value) {
+		return this.scope.set(key, value, {
+			ttl: Infinity,
+			tags: this.handleTags
+		});
+	}
+	/**
+	* Atomic create-or-skip with the handle's tags applied on success. The
+	* driver contract has no inline `tags` knob on `setNX`, so we register the
+	* tag relationship manually after a successful write.
+	*/
+	async setNX(key, value, ttl) {
+		if (!await this.scope.setNX(key, value, ttl)) return false;
+		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
+		if (!allTags || allTags.length === 0) return true;
+		const scopedKey = this.buildScopedKey(key);
+		const parsedKey = this.scope.source.parseKey(scopedKey);
+		await this.scope.source.tags(allTags).storeTagRelationship(parsedKey);
+		return true;
+	}
+	/**
+	* Read-or-compute with handle tags appended on the cache-miss write.
+	*/
+	remember(key, ttlOrOptions, callback) {
+		const options = injectTags(normalizeToRememberOptions(ttlOrOptions), this.handleTags);
+		return this.scope.remember(key, options, callback);
+	}
+	/**
+	* Atomic counter increment on the scoped key. Tags aren't applied to
+	* subsequent increments — they're attached at first-write time.
+	*/
+	increment(key, value) {
+		return this.scope.increment(key, value);
+	}
+	/**
+	* Atomic counter decrement on the scoped key. See {@link increment}.
+	*/
+	decrement(key, value) {
+		return this.scope.decrement(key, value);
+	}
+	/**
+	* Wipe every entry tagged with the union of (scope tags + handle tags).
+	* Tags are global across the package, so this reaches outside the scope's
+	* prefix when scope tags are also used elsewhere.
+	*/
+	async invalidate() {
+		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
+		if (!allTags || allTags.length === 0) return;
+		await this.scope.source.tags(allTags).invalidate();
+	}
+	/**
+	* Compute the source-side key the same way `ScopedCache.scopedKey` does —
+	* needed for `setNX`, where we have to register the tag relationship by
+	* hand because the driver contract doesn't accept inline tags there.
+	*/
+	buildScopedKey(key) {
+		const keyString = typeof key === "string" ? key : parseCacheKey(key);
+		if (!keyString) return this.scope.prefix;
+		return `${this.scope.prefix}.${keyString}`;
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/scoped-cache.ts
+/**
+* Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.
+*
+* **Role.** A `ScopedCache` is a stateless wrapper that prepends a fixed
+* prefix to every key and applies optional default `ttl` / `tags` to every
+* write. Stores nothing itself — every call forwards to the underlying
+* `source` (typically the `CacheManager`, but any `CacheDriver` works).
+*
+* **Responsibility.**
+* - Owns: prefix-prepending of keys, normalization of nested-scope prefixes,
+*   merging scope defaults into write options (`ttl`, `tags`), filtering
+*   `similar()` hits to its own scope, and exposing `.clear()` as a sugar
+*   for `removeNamespace(prefix)`.
+* - Does NOT own: actual storage, connection lifecycle, event listeners,
+*   driver selection, or tag-index bookkeeping (delegated to the source's
+*   tagged-cache machinery).
+*
+* Per-call options always win over scope defaults; tags merge additively
+* across (scope defaults + per-call) layers. Nested scopes inherit and may
+* override the parent's defaults — see {@link ScopedCache.namespace}.
+*
+* @example
+* const chat = cache.namespace(`chats.${id}`, { ttl: "30d" });
+*
+* await chat.set("messages.10", msg);          // 30d default
+* await chat.set("draft", d, { ttl: "1h" });   // per-call override
+* await chat.namespace("typing", { ttl: "5s" }).set("user.42", true);
+* await chat.clear();
+*/
+var ScopedCache = class ScopedCache {
+	/**
+	* Build a scope. Constructed via `cache.namespace(prefix, options)` —
+	* users never call this directly.
+	*/
+	constructor(source, prefix, defaults = {}) {
+		this.source = source;
+		this.prefix = parseCacheKey(prefix);
+		this.defaults = {
+			ttl: defaults.ttl,
+			tags: defaults.tags && defaults.tags.length > 0 ? [...defaults.tags] : void 0
+		};
+	}
+	/**
+	* Build a nested scope. The child's prefix is `parent.child`; child options
+	* override the parent's `ttl` and union into `tags`.
+	*
+	* @example
+	* const chat = cache.namespace("chats.10", { ttl: "30d" });
+	* const typing = chat.namespace("typing", { ttl: "5s" });
+	* // typing.prefix === "chats.10.typing"
+	*/
+	namespace(prefix, options = {}) {
+		const childPrefix = `${this.prefix}.${parseCacheKey(prefix)}`;
+		return new ScopedCache(this.source, childPrefix, {
+			ttl: options.ttl ?? this.defaults.ttl,
+			tags: mergeTagSets(this.defaults.tags, options.tags)
+		});
+	}
+	/**
+	* Return a one-shot tagged write handle. The handle's tags merge additively
+	* with scope-level defaults — final tag list per write is the union of
+	* (scope tags + handle tags + per-call tags), deduped.
+	*/
+	tags(tags) {
+		return new TaggedScopedCache(this, tags);
+	}
+	/**
+	* Wipe every entry under this scope's prefix. Sugar over
+	* `source.removeNamespace(prefix)` — siblings outside the scope are
+	* untouched.
+	*/
+	clear() {
+		return this.source.removeNamespace(this.prefix);
+	}
+	/**
+	* Read the value at the scoped key. Forwards to the source after prefixing.
+	*/
+	get(key) {
+		return this.source.get(this.scopedKey(key));
+	}
+	/**
+	* Check presence of the scoped key without fetching the value.
+	*/
+	has(key) {
+		return this.source.has(this.scopedKey(key));
+	}
+	/**
+	* Batch-read scoped keys. Each input key is prefixed before forwarding.
+	*/
+	many(keys) {
+		return this.source.many(keys.map((key) => this.scopedKey(key)));
+	}
+	/**
+	* Read-and-remove. Returns the value or `null`; the entry is gone after.
+	*/
+	pull(key) {
+		return this.source.pull(this.scopedKey(key));
+	}
+	/**
+	* Write the scoped key. Per-call `ttl`/`tags` win over scope defaults;
+	* `expiresAt` is preserved as-is (absolute deadlines are never overridden
+	* by the scope's relative-ttl default).
+	*/
+	set(key, value, ttlOrOptions) {
+		return this.source.set(this.scopedKey(key), value, this.mergeSetOptions(ttlOrOptions));
+	}
+	/**
+	* Batch-write under the scope. Caller's positional `ttl` wins; otherwise
+	* the scope default is parsed to seconds (since `setMany` accepts only a
+	* numeric ttl).
+	*/
+	setMany(items, ttl) {
+		const scoped = {};
+		for (const [key, value] of Object.entries(items)) scoped[this.scopedKey(key)] = value;
+		return this.source.setMany(scoped, ttl ?? this.scopeTtlSeconds());
+	}
+	/**
+	* Atomic create-or-skip on the scoped key. Throws when the underlying
+	* source has no `setNX` (driver-specific — Redis-only today).
+	*/
+	setNX(key, value, ttl) {
+		if (!this.source.setNX) throw new Error(`setNX is not supported by the underlying cache source: ${this.source.name}`);
+		return this.source.setNX(this.scopedKey(key), value, ttl ?? this.scopeTtlSeconds());
+	}
+	/**
+	* Permanent write (no expiration). Bypasses the scope's `ttl` default —
+	* `forever` always means forever, regardless of scope policy.
+	*/
+	forever(key, value) {
+		return this.source.forever(this.scopedKey(key), value);
+	}
+	/**
+	* Remove a single scoped key.
+	*/
+	remove(key) {
+		return this.source.remove(this.scopedKey(key));
+	}
+	/**
+	* Read-or-compute. Cache-miss writes pick up the scope's default `ttl`
+	* and `tags` unless the caller passed an options object that overrides.
+	*/
+	remember(key, ttlOrOptions, callback) {
+		return this.source.remember(this.scopedKey(key), this.mergeRememberOptions(ttlOrOptions), callback);
+	}
+	/**
+	* Stale-while-revalidate on the scoped key. Scope-level `tags` merge
+	* additively with `options.tags`; `freshTtl`/`staleTtl` always come from
+	* the caller (no scope-default precedence — the SWR shape is too
+	* specific to the call site to inherit).
+	*/
+	swr(key, options, callback) {
+		const merged = {
+			...options,
+			tags: mergeTagSets(this.defaults.tags, options.tags)
+		};
+		return this.source.swr(this.scopedKey(key), merged, callback);
+	}
+	/**
+	* Atomic counter increment on the scoped key. TTL is preserved by the
+	* underlying driver — scope ttl is only applied on first write via `set`.
+	*/
+	increment(key, value) {
+		return this.source.increment(this.scopedKey(key), value);
+	}
+	/**
+	* Atomic counter decrement on the scoped key. See {@link increment} for
+	* TTL semantics.
+	*/
+	decrement(key, value) {
+		return this.source.decrement(this.scopedKey(key), value);
+	}
+	/**
+	* Atomic read-modify-write. Falls back to the scope's `ttl` when the caller
+	* doesn't provide one; the source still keeps the existing entry's TTL on
+	* an update unless `options.ttl` is explicitly set.
+	*/
+	update(key, fn, options) {
+		return this.source.update(this.scopedKey(key), fn, { ttl: options?.ttl ?? this.defaults.ttl });
+	}
+	/**
+	* Shallow-merge a partial object into the scoped entry. Same TTL semantics
+	* as {@link update}.
+	*/
+	merge(key, partial, options) {
+		return this.source.merge(this.scopedKey(key), partial, { ttl: options?.ttl ?? this.defaults.ttl });
+	}
+	/**
+	* Return a list accessor bound to the scoped key. The accessor itself
+	* does its own read-mutate-write under the prefixed entry.
+	*/
+	list(key) {
+		return this.source.list(this.scopedKey(key));
+	}
+	/**
+	* Acquire a distributed lock on the scoped key. Caller's TTL wins; when
+	* the options form omits `ttl`, the scope default fills in.
+	*/
+	lock(key, ttlOrOptions, fn) {
+		if (typeof ttlOrOptions === "object" && ttlOrOptions !== null) {
+			const merged = {
+				...ttlOrOptions,
+				ttl: ttlOrOptions.ttl ?? this.defaults.ttl ?? ttlOrOptions.ttl
+			};
+			return this.source.lock(this.scopedKey(key), merged, fn);
+		}
+		return this.source.lock(this.scopedKey(key), ttlOrOptions, fn);
+	}
+	/**
+	* Similarity retrieval, scope-isolated. Hits whose keys fall outside this
+	* scope are filtered out before the result is returned. `topK` applies to
+	* the underlying retrieval — when the scope contains fewer than `topK`
+	* matches but other scopes do, the caller will see fewer hits than `topK`.
+	*/
+	async similar(vector, options) {
+		const hits = await this.source.similar(vector, options);
+		const parsedPrefix = this.source.parseKey(this.prefix);
+		return hits.filter((hit) => hit.key === parsedPrefix || hit.key.startsWith(parsedPrefix + "."));
+	}
+	/**
+	* Build the source-side key by prepending the scope prefix. Object keys
+	* are normalized via {@link parseCacheKey} first so they compose with the
+	* prefix as plain dot-strings.
+	*/
+	scopedKey(key) {
+		const keyString = typeof key === "string" ? key : parseCacheKey(key);
+		if (!keyString) return this.prefix;
+		return `${this.prefix}.${keyString}`;
+	}
+	/**
+	* Coerce the polymorphic 3rd `set` argument into a {@link CacheSetOptions}
+	* with scope defaults filled in. Per-call values always win; tags merge
+	* additively. `expiresAt` is preserved without injecting the scope's `ttl`
+	* default (absolute deadlines override relative ones).
+	*/
+	mergeSetOptions(input) {
+		const options = normalizeToOptions(input);
+		const ttl = options.ttl ?? (options.expiresAt === void 0 ? this.defaults.ttl : void 0);
+		const tags = mergeTagSets(this.defaults.tags, options.tags);
+		const merged = { ...options };
+		if (ttl !== void 0) merged.ttl = ttl;
+		if (tags !== void 0) merged.tags = tags;
+		return merged;
+	}
+	/**
+	* Same merge as {@link mergeSetOptions} but for the `remember()` shape
+	* ({@link RememberOptions} — no `expiresAt`).
+	*/
+	mergeRememberOptions(input) {
+		const options = normalizeToRememberOptions(input);
+		const ttl = options.ttl ?? this.defaults.ttl;
+		const tags = mergeTagSets(this.defaults.tags, options.tags);
+		const merged = { ...options };
+		if (ttl !== void 0) merged.ttl = ttl;
+		if (tags !== void 0) merged.tags = tags;
+		return merged;
+	}
+	/**
+	* Convert the scope's default `ttl` (which may be a duration string) into
+	* seconds, for the few methods (`setMany`, `setNX`) that accept only a
+	* numeric ttl.
+	*/
+	scopeTtlSeconds() {
+		if (this.defaults.ttl === void 0) return;
+		return parseTtl(this.defaults.ttl);
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/cache-manager.ts
+var CacheManager = class {
+	constructor() {
+		this.loadedDrivers = {};
+		this.configurations = {
+			drivers: {},
+			options: {}
+		};
+		this.globalEventListeners = /* @__PURE__ */ new Map();
+		this.name = "cacheManager";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	get client() {
+		return this.currentDriver?.client;
+	}
+	/**
+	* Set the cache configurations
+	*/
+	setCacheConfigurations(configurations) {
+		this.configurations.default = configurations.default;
+		this.configurations.drivers = configurations.drivers;
+		this.configurations.options = configurations.options;
+		this.configurations.logging = configurations.logging;
+	}
+	/**
+	* Set logging state
+	*/
+	setLoggingState(loggingState) {
+		this.ensureDriverInitialized();
+		this.currentDriver.setLoggingState(loggingState);
+	}
+	/**
+	* Switch the manager to a registered driver, optionally injecting runtime
+	* options that merge over the static config.
+	*
+	* The string form looks the driver up in `setCacheConfigurations({ drivers })`,
+	* loads it (or returns the cached instance), and sets it as `currentDriver`.
+	* The instance form takes a pre-built driver and bypasses the registry; the
+	* `runtimeOptions` argument is silently ignored in that case because the
+	* instance was constructed externally.
+	*
+	* Runtime options merge over `config.options[name]` per-key — runtime wins.
+	* Use this for constructor-only knobs that can't live in static config
+	* (e.g. `pg`'s `client: pg.Pool`).
+	*
+	* @example
+	* const pool = new Pool({ connectionString });
+	* await cache.use("pg", { client: pool });
+	*/
+	async use(driver, runtimeOptions) {
+		if (typeof driver === "string") {
+			const driverInstance = await this.load(driver, runtimeOptions);
+			if (!driverInstance) throw new CacheConfigurationError(`Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`);
+			driver = driverInstance;
+		}
+		this.attachGlobalListeners(driver);
+		if (this.configurations.logging !== void 0) driver.setLoggingState(this.configurations.logging);
+		this.currentDriver = driver;
+		return this;
+	}
+	/**
+	* Ensure driver is initialized before operations
+	*/
+	ensureDriverInitialized() {
+		if (!this.currentDriver) throw new CacheDriverNotInitializedError();
+	}
+	/**
+	* Return the running metrics snapshot — counters, hit-rate, latency
+	* percentiles, per-driver breakdowns. Lazy-attaches the collector on
+	* first call so apps that never read metrics pay zero cost.
+	*
+	* @example
+	* const m = cache.metrics();
+	* console.log(`hit rate: ${(m.hitRate * 100).toFixed(1)}%`);
+	* console.log(`p95: ${m.latencyMs.p95.toFixed(2)}ms`);
+	*/
+	metrics() {
+		return this.ensureMetricsCollector().snapshot();
+	}
+	/**
+	* Wipe every counter + latency sample and reset `startedAt` to now.
+	* The collector itself stays subscribed to events.
+	*/
+	resetMetrics() {
+		this.ensureMetricsCollector().reset();
+	}
+	/**
+	* Lazy-construct the metrics collector and wire it to the global event
+	* bus. Subsequent calls return the same instance — survives `cache.use()`
+	* driver switches because handlers attach via `on()` and re-bind to every
+	* loaded driver.
+	*/
+	ensureMetricsCollector() {
+		if (this.metricsCollector) return this.metricsCollector;
+		const collector = new CacheMetricsCollector();
+		this.on("hit", (data) => collector.recordEvent("hit", data));
+		this.on("miss", (data) => collector.recordEvent("miss", data));
+		this.on("set", (data) => collector.recordEvent("set", data));
+		this.on("removed", (data) => collector.recordEvent("removed", data));
+		this.on("error", (data) => collector.recordEvent("error", data));
+		this.metricsCollector = collector;
+		return collector;
+	}
+	/**
+	* Time the body, record the elapsed milliseconds against the metrics
+	* collector for the given driver (defaults to the current driver's name).
+	* Pass-through if the collector hasn't been instantiated yet — apps that
+	* don't read metrics never pay for sample collection.
+	*/
+	async timed(body, driverName) {
+		if (!this.metricsCollector) return body();
+		const start = performance.now();
+		try {
+			return await body();
+		} finally {
+			const elapsed = performance.now() - start;
+			const name = driverName ?? this.currentDriver?.name ?? "unknown";
+			this.metricsCollector.recordLatency(name, elapsed);
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		this.ensureDriverInitialized();
+		return this.timed(() => this.currentDriver.get(key));
+	}
+	/**
+	* Set a value in the cache.
+	*
+	* Accepts a positional TTL (number of seconds or duration string like `"1h"`)
+	* or a rich {@link CacheSetOptions} object supporting `ttl`, `expiresAt`,
+	* `tags`, `onConflict`, `namespace`, and per-call `driver` overrides.
+	*/
+	async set(key, value, ttlOrOptions) {
+		this.ensureDriverInitialized();
+		const driverOverride = ttlOrOptions && typeof ttlOrOptions === "object" && "driver" in ttlOrOptions ? ttlOrOptions.driver : void 0;
+		if (driverOverride) {
+			const driver = await this.load(driverOverride);
+			return this.timed(() => driver.set(key, value, ttlOrOptions), driver.name);
+		}
+		return this.timed(() => this.currentDriver.set(key, value, ttlOrOptions));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		this.ensureDriverInitialized();
+		return this.timed(() => this.currentDriver.remove(key));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.removeNamespace(namespace);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		this.ensureDriverInitialized();
+		return this.currentDriver.flush();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.ensureDriverInitialized();
+		return this.currentDriver.connect();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	parseKey(key) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.parseKey(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	get options() {
+		this.ensureDriverInitialized();
+		return this.currentDriver.options;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.setOptions(options || {});
+	}
+	/**
+	* Return the loaded driver instance for `driverName`, loading it on first
+	* call. Optional `runtimeOptions` follow the same merge-over-config rules
+	* as {@link load}; passing options after the driver has already been
+	* loaded throws to avoid silent swallowing.
+	*/
+	async driver(driverName, runtimeOptions) {
+		if (this.loadedDrivers[driverName]) {
+			this.assertNoConflictingReload(driverName, runtimeOptions);
+			return this.loadedDrivers[driverName];
+		}
+		return this.load(driverName, runtimeOptions);
+	}
+	/**
+	* Initialize the cache manager and pick the default driver
+	*/
+	async init() {
+		const defaultCacheDriverName = this.configurations.default;
+		if (!defaultCacheDriverName) return;
+		const driver = await this.driver(defaultCacheDriverName);
+		await this.use(driver);
+	}
+	/**
+	* Load and connect the registered driver named `driver`. First-call wins —
+	* subsequent calls without `runtimeOptions` return the cached instance, and
+	* subsequent calls *with* `runtimeOptions` throw {@link CacheConfigurationError}
+	* to avoid silently dropping the new options.
+	*
+	* `runtimeOptions` merge over `config.options[driver]` per-key (runtime wins),
+	* letting consumers split static knobs (table, ttl, globalPrefix) from
+	* constructor-only ones (pg's `client`, custom adapters, etc.).
+	*
+	* @example
+	* const pool = new Pool({ connectionString });
+	* const pg = await cache.load("pg", { client: pool });
+	*/
+	async load(driver, runtimeOptions) {
+		if (this.loadedDrivers[driver]) {
+			this.assertNoConflictingReload(driver, runtimeOptions);
+			return this.loadedDrivers[driver];
+		}
+		const Driver = this.configurations.drivers[driver];
+		if (!Driver) throw new CacheConfigurationError(`Cache driver ${driver} is not found, please declare it in the cache drivers in the configurations list.`);
+		const driverInstance = new Driver();
+		const configOptions = this.configurations.options[driver] || {};
+		driverInstance.setOptions({
+			...configOptions,
+			...runtimeOptions ?? {}
+		});
+		await driverInstance.connect();
+		this.attachGlobalListeners(driverInstance);
+		this.loadedDrivers[driver] = driverInstance;
+		return driverInstance;
+	}
+	/**
+	* Guard against silently dropping runtime options on a re-load. Once a
+	* driver has been instantiated, its options are frozen — calling `load` /
+	* `driver` / `use` again with a non-empty `runtimeOptions` would otherwise
+	* appear to work but actually use the original options. We throw instead
+	* so the misuse surfaces at the call site.
+	*/
+	assertNoConflictingReload(driverName, runtimeOptions) {
+		if (runtimeOptions === void 0) return;
+		if (Object.keys(runtimeOptions).length === 0) return;
+		throw new CacheConfigurationError(`Cache driver '${driverName}' is already loaded; runtime options on subsequent calls are ignored — register a second driver name if you need a different configuration.`);
+	}
+	/**
+	* Register and bind a driver
+	*/
+	registerDriver(driverName, driverClass) {
+		this.configurations.drivers[driverName] = driverClass;
+	}
+	/**
+	* Disconnect the cache manager
+	*/
+	async disconnect() {
+		if (this.currentDriver) await this.currentDriver.disconnect();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async has(key) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.has(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remember(key, ttlOrOptions, callback) {
+		this.ensureDriverInitialized();
+		const driverOverride = ttlOrOptions && typeof ttlOrOptions === "object" && "driver" in ttlOrOptions ? ttlOrOptions.driver : void 0;
+		if (driverOverride) return (await this.load(driverOverride)).remember(key, ttlOrOptions, callback);
+		return this.currentDriver.remember(key, ttlOrOptions, callback);
+	}
+	/**
+	* Stale-while-revalidate. Returns cached when fresh, returns the stale
+	* value plus a background refresh when within `freshTtl..staleTtl`,
+	* blocks like a normal miss past `staleTtl`. Honors per-call `driver`
+	* override the same way `remember()` does.
+	*
+	* @example
+	* const product = await cache.swr(
+	*   "product.42",
+	*   { freshTtl: "1m", staleTtl: "1h" },
+	*   () => db.products.find(42),
+	* );
+	*/
+	async swr(key, options, callback) {
+		this.ensureDriverInitialized();
+		const driverOverride = options.driver;
+		if (driverOverride) return (await this.load(driverOverride)).swr(key, options, callback);
+		return this.currentDriver.swr(key, options, callback);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pull(key) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.pull(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async forever(key, value) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.forever(key, value);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async increment(key, value) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.increment(key, value);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async decrement(key, value) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.decrement(key, value);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async many(keys) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.many(keys);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async setMany(items, ttl) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.setMany(items, ttl);
+	}
+	/**
+	* Register a global event listener (applies to all drivers)
+	*/
+	on(event, handler) {
+		if (!this.globalEventListeners.has(event)) this.globalEventListeners.set(event, /* @__PURE__ */ new Set());
+		this.globalEventListeners.get(event).add(handler);
+		if (this.currentDriver) this.currentDriver.on(event, handler);
+		for (const driver of Object.values(this.loadedDrivers)) driver.on(event, handler);
+		return this;
+	}
+	/**
+	* Remove a global event listener
+	*/
+	off(event, handler) {
+		const handlers = this.globalEventListeners.get(event);
+		if (handlers) handlers.delete(handler);
+		if (this.currentDriver) this.currentDriver.off(event, handler);
+		for (const driver of Object.values(this.loadedDrivers)) driver.off(event, handler);
+		return this;
+	}
+	/**
+	* Register a one-time global event listener
+	*/
+	once(event, handler) {
+		const onceHandler = async (data) => {
+			await handler(data);
+			this.off(event, onceHandler);
+		};
+		return this.on(event, onceHandler);
+	}
+	/**
+	* Attach global listeners to a driver
+	*/
+	attachGlobalListeners(driver) {
+		for (const [event, handlers] of this.globalEventListeners) for (const handler of handlers) driver.on(event, handler);
+	}
+	/**
+	* Set if not exists (atomic operation)
+	* Returns true if key was set, false if key already existed
+	* Note: Only supported by drivers that implement setNX (e.g., Redis)
+	*/
+	async setNX(key, value, ttl) {
+		this.ensureDriverInitialized();
+		if (!this.currentDriver.setNX) throw new Error(`setNX is not supported by the current cache driver: ${this.currentDriver.name}`);
+		return this.currentDriver.setNX(key, value, ttl);
+	}
+	/**
+	* Create a tagged cache instance for the given tags
+	*/
+	tags(tags) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.tags(tags);
+	}
+	/**
+	* Atomically read, transform, and write a cached value. Delegates to the current driver.
+	*/
+	async update(key, fn, options) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.update(key, fn, options);
+	}
+	/**
+	* Shallow-merge a partial object into a cached value.
+	*/
+	async merge(key, partial, options) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.merge(key, partial, options);
+	}
+	/**
+	* Obtain a list accessor bound to the current driver.
+	*/
+	list(key) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.list(key);
+	}
+	/**
+	* Acquire a distributed lock, run `fn`, and auto-release. Returns a
+	* {@link LockOutcome} discriminated union so callers can distinguish
+	* "ran and got this value" from "skipped because someone else holds it".
+	*
+	* Honors the `driver` option for per-call driver override, same as `set`
+	* and `remember`.
+	*
+	* @example
+	* const outcome = await cache.lock("lock.import", "5m", async () => {
+	*   await runImport();
+	*   return "done";
+	* });
+	* if (!outcome.acquired) {
+	*   console.log("another worker is already importing");
+	* }
+	*/
+	async lock(key, ttlOrOptions, fn) {
+		this.ensureDriverInitialized();
+		const driverOverride = ttlOrOptions && typeof ttlOrOptions === "object" && "driver" in ttlOrOptions ? ttlOrOptions.driver : void 0;
+		return (driverOverride ? await this.load(driverOverride) : this.currentDriver).lock(key, ttlOrOptions, fn);
+	}
+	/**
+	* Similarity retrieval. Delegates to the current driver's `similar()` impl.
+	*
+	* Drivers that lack a similarity index throw {@link CacheUnsupportedError}.
+	*
+	* @example
+	* const hits = await cache.similar(await embed(query), { topK: 5, threshold: 0.7 });
+	*/
+	/**
+	* Create a scoped view over the cache. Every key written through the
+	* returned scope is automatically prefixed with `prefix`; optional defaults
+	* (`ttl`, `tags`) flow through every write inside the scope.
+	*
+	* Per-call options always win over scope defaults. Scope tags merge
+	* additively with per-call tags. Nested scopes inherit from the parent.
+	*
+	* @example
+	* const chat = cache.namespace("chats.10", { ttl: "30d" });
+	* await chat.set("messages.1", msg);          // → "chats.10.messages.1", 30d
+	* await chat.set("draft", d, { ttl: "1h" });  // per-call ttl wins
+	* await chat.namespace("typing", { ttl: "5s" }).set("user.42", true);
+	* await chat.clear();                          // wipe the whole scope
+	*/
+	namespace(prefix, options) {
+		this.ensureDriverInitialized();
+		return new ScopedCache(this, prefix, options);
+	}
+	async similar(vector, options) {
+		this.ensureDriverInitialized();
+		return this.currentDriver.similar(vector, options);
+	}
+};
+const cache = new CacheManager();
+
+//#endregion
+//#region ../../@warlock.js/cache/src/cached/auto-key.ts
+/**
+* Derive a cache key from a prefix and a set of function arguments.
+*
+* Rules (in order of precedence):
+* 1. No args → prefix alone.
+* 2. All primitives (`string`, `number`, `boolean`) or `null` / `undefined` /
+*    `bigint` → joined onto the prefix with dots.
+* 3. Any non-primitive arg present → the full args array is `JSON.stringify`-ed
+*    and appended to the prefix.
+* 4. Serialization throws (circular refs, `BigInt` nested in an object) → we
+*    re-throw as `CacheConfigurationError` so the caller sees a cache-scoped
+*    error rather than a cryptic `TypeError`.
+*
+* @example
+* deriveAutoKey("user", [42]);                         // "user.42"
+* deriveAutoKey("orders", [42, "abc"]);                // "orders.42.abc"
+* deriveAutoKey("featured", []);                       // "featured"
+* deriveAutoKey("search", [{ q: "hello" }]);           // "search.[{\"q\":\"hello\"}]"
+* deriveAutoKey("user", [null, undefined]);            // "user.null.undefined"
+*/
+function deriveAutoKey(prefix, args) {
+	if (args.length === 0) return prefix;
+	if (args.every(isPrimitiveOrNullish)) return prefix + "." + args.map(serializePrimitive).join(".");
+	try {
+		return prefix + "." + JSON.stringify(args);
+	} catch (error) {
+		throw new CacheConfigurationError(`cached(): could not derive an auto-key from args for prefix "${prefix}". The args include a value that is not JSON-serializable (circular reference, BigInt nested inside an object, or similar). Use the options form with a custom key function. Original error: ${error.message}`);
+	}
+}
+/**
+* Primitives and nullish values can be concatenated directly onto a key without
+* JSON serialization. Adding `bigint` here avoids the `JSON.stringify` throw on
+* top-level bigint args.
+*/
+function isPrimitiveOrNullish(value) {
+	if (value === null || value === void 0) return true;
+	const type = typeof value;
+	return type === "string" || type === "number" || type === "boolean" || type === "bigint";
+}
+/**
+* Serialize a single primitive or nullish value to its string key-segment form.
+*/
+function serializePrimitive(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "bigint") return value.toString();
+	return String(value);
+}
+
+//#endregion
+//#region ../../@warlock.js/cache/src/cached/normalize-args.ts
+/**
+* Resolve the positional-or-options arguments of `cached()` into a single
+* normalized config. Keeps the wrapper body free of shape-checks.
+*/
+function normalizeCachedArgs(prefixOrOptions, maybeTtl) {
+	if (typeof prefixOrOptions === "string") {
+		const prefix = prefixOrOptions;
+		return {
+			key: (...args) => deriveAutoKey(prefix, args),
+			ttl: maybeTtl
+		};
+	}
+	return {
+		key: prefixOrOptions.key,
+		ttl: prefixOrOptions.ttl,
+		tags: prefixOrOptions.tags,
+		driver: prefixOrOptions.driver
+	};
+}
+
+//#endregion
+//#region ../../@warlock.js/cache/src/cached/cached.ts
+function cached(fn, prefixOrOptions, maybeTtl) {
+	const config = normalizeCachedArgs(prefixOrOptions, maybeTtl);
+	const buildRememberOptions = () => ({
+		ttl: config.ttl,
+		tags: config.tags,
+		driver: config.driver
+	});
+	const wrapper = (async (...args) => {
+		const key = config.key(...args);
+		return cache.remember(key, buildRememberOptions(), () => fn(...args));
+	});
+	wrapper.invalidate = async (...args) => {
+		const key = config.key(...args);
+		await cache.remove(key);
+	};
+	return wrapper;
+}
+
+//#endregion
+//#region ../../@warlock.js/cache/src/list/memory-cache-list.ts
+/**
+* Generic array-backed {@link CacheListAccessor}.
+*
+* Stores the full list as a single cache entry and performs read-mutate-write
+* for every operation. Correct for any driver, but O(n) per op. The Redis
+* driver overrides `list()` to return a native-command accessor instead.
+*
+* **Role.** Fallback list accessor bound to a driver + key. Every mutation
+* fetches the array, transforms it in memory, and writes it back.
+*
+* **Responsibility.**
+* - Owns: translating list operations into array mutations + driver writes.
+* - Does NOT own: concurrency control (callers should wrap in a distributed
+*   lock when multi-process writers are possible), TTL preservation across
+*   ops (writes use driver defaults), or tagging of list entries.
+*
+* @example
+* // Never constructed directly — obtained via driver.list():
+* const list = cache.list<Event>("recent-events");
+* await list.push(event);
+*/
+var MemoryCacheList = class {
+	constructor(driver, key) {
+		this.driver = driver;
+		this.key = key;
+	}
+	/**
+	* Read the backing array from the driver. Returns an empty array on miss.
+	*/
+	async read() {
+		const current = await this.driver.get(this.key);
+		return Array.isArray(current) ? [...current] : [];
+	}
+	/**
+	* Persist the backing array. Removes the entry when empty to keep the
+	* store clean.
+	*/
+	async write(items) {
+		if (items.length === 0) {
+			await this.driver.remove(this.key);
+			return;
+		}
+		await this.driver.set(this.key, items);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async push(...items) {
+		const current = await this.read();
+		current.push(...items);
+		await this.write(current);
+		return current.length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async unshift(...items) {
+		const current = await this.read();
+		current.unshift(...items);
+		await this.write(current);
+		return current.length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pop() {
+		const current = await this.read();
+		if (current.length === 0) return null;
+		const value = current.pop();
+		await this.write(current);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async shift() {
+		const current = await this.read();
+		if (current.length === 0) return null;
+		const value = current.shift();
+		await this.write(current);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async slice(start, end) {
+		return (await this.read()).slice(start, end);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async all() {
+		return this.read();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async length() {
+		return (await this.read()).length;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async trim(start, end) {
+		const trimmed = (await this.read()).slice(start, end + 1);
+		await this.write(trimmed);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async clear() {
+		await this.driver.remove(this.key);
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/tagged-cache.ts
+/**
+* Tagged Cache Wrapper
+* Wraps a cache driver to automatically manage tag relationships
+*/
+var TaggedCache = class {
+	/**
+	* Constructor
+	*/
+	constructor(tags, driver) {
+		this.cacheTags = tags;
+		this.driver = driver;
+	}
+	/**
+	* Get the tag key prefix for storing tag-key relationships
+	*/
+	tagKey(tag) {
+		return `cache:tags:${tag}`;
+	}
+	/**
+	* Store tag-key relationship
+	*/
+	async storeTaggedKey(key) {
+		await this.storeTagRelationship(key);
+	}
+	/**
+	* Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`
+	* when tags are passed inline through `CacheSetOptions.tags`.
+	*
+	* @internal — public for cross-class use within this package; not part of the
+	* stable consumer API.
+	*/
+	async storeTagRelationship(parsedKey) {
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const keys = await this.driver.get(tagKey) || [];
+			if (!keys.includes(parsedKey)) {
+				keys.push(parsedKey);
+				await this.driver.set(tagKey, keys, Infinity);
+			}
+		}
+	}
+	/**
+	* Get all keys associated with tags
+	*/
+	async getTaggedKeys() {
+		const allKeys = /* @__PURE__ */ new Set();
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const keys = await this.driver.get(tagKey) || [];
+			for (const key of keys) allKeys.add(key);
+		}
+		return allKeys;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.driver.parseKey(key);
+		await this.driver.set(key, value, ttlOrOptions);
+		await this.storeTaggedKey(parsedKey);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		return this.driver.get(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.driver.parseKey(key);
+		await this.driver.remove(key);
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const updatedKeys = (await this.driver.get(tagKey) || []).filter((k) => k !== parsedKey);
+			await this.driver.set(tagKey, updatedKeys, Infinity);
+		}
+	}
+	/**
+	* Invalidate (clear) all keys associated with the current tags
+	*/
+	async invalidate() {
+		const keysToRemove = await this.getTaggedKeys();
+		for (const key of keysToRemove) await this.driver.remove(key);
+		for (const tag of this.cacheTags) await this.driver.remove(this.tagKey(tag));
+	}
+	/**
+	* Flush all keys associated with the current tags
+	* @deprecated Use invalidate() instead for better semantics
+	*/
+	async flush() {
+		return this.invalidate();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async has(key) {
+		return this.driver.has(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remember(key, ttl, callback) {
+		const value = await this.get(key);
+		if (value !== null) return value;
+		const result = await callback();
+		await this.set(key, result, ttl);
+		return result;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pull(key) {
+		const value = await this.get(key);
+		if (value !== null) await this.remove(key);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async forever(key, value) {
+		return this.set(key, value, Infinity);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async increment(key, value = 1) {
+		const current = await this.get(key) || 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${this.driver.parseKey(key)}`);
+		const newValue = current + value;
+		await this.set(key, newValue);
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/base-cache-driver.ts
+const messages = {
+	clearing: "Clearing namespace",
+	cleared: "Namespace cleared",
+	fetching: "Fetching key",
+	fetched: "Key fetched",
+	caching: "Caching key",
+	cached: "Key cached",
+	flushing: "Flushing cache",
+	flushed: "Cache flushed",
+	removing: "Removing key",
+	removed: "Key removed",
+	expired: "Key expired",
+	notFound: "Key not found",
+	connecting: "Connecting to the cache engine.",
+	connected: "Connected to the cache engine.",
+	disconnecting: "Disconnecting from the cache engine.",
+	disconnected: "Disconnected from the cache engine.",
+	error: "Error occurred"
+};
+var BaseCacheDriver = class {
+	constructor() {
+		this.shouldLog = true;
+		this.eventListeners = /* @__PURE__ */ new Map();
+		this.locks = /* @__PURE__ */ new Map();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	get client() {
+		return this.clientDriver || this;
+	}
+	/**
+	* Set logging state
+	*/
+	setLoggingState(shouldLog) {
+		this.shouldLog = shouldLog;
+		return this;
+	}
+	/**
+	* Set client driver
+	*/
+	set client(client) {
+		this.clientDriver = client;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	parseKey(key) {
+		return parseCacheKey(key, this.options);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		this.options = options || {};
+		return this;
+	}
+	/**
+	* Register an event listener
+	*/
+	on(event, handler) {
+		if (!this.eventListeners.has(event)) this.eventListeners.set(event, /* @__PURE__ */ new Set());
+		this.eventListeners.get(event).add(handler);
+		return this;
+	}
+	/**
+	* Remove an event listener
+	*/
+	off(event, handler) {
+		const handlers = this.eventListeners.get(event);
+		if (handlers) handlers.delete(handler);
+		return this;
+	}
+	/**
+	* Register a one-time event listener
+	*/
+	once(event, handler) {
+		const onceHandler = async (data) => {
+			await handler(data);
+			this.off(event, onceHandler);
+		};
+		return this.on(event, onceHandler);
+	}
+	/**
+	* Emit an event to all registered listeners
+	*/
+	async emit(event, data = {}) {
+		const handlers = this.eventListeners.get(event);
+		if (!handlers || handlers.size === 0) return;
+		const eventData = {
+			driver: this.name,
+			...data
+		};
+		const promises = [];
+		for (const handler of handlers) try {
+			const result = handler(eventData);
+			if (result instanceof Promise) promises.push(result);
+		} catch (error) {
+			this.logError(`Error in event handler for '${event}'`, error);
+		}
+		if (promises.length > 0) await Promise.allSettled(promises);
+	}
+	/**
+	* Normalize the 3rd argument of a `set` call into a single shape every driver
+	* can act on. Handles TTL parsing (number | string | Infinity), `expiresAt` →
+	* relative TTL conversion, and mutual-exclusion validation.
+	*
+	* @throws {CacheConfigurationError} when `ttl` and `expiresAt` are passed together
+	* or an unparseable duration string is supplied.
+	*/
+	resolveSetOptions(ttlOrOptions) {
+		const options = normalizeToOptions(ttlOrOptions);
+		return {
+			ttl: resolveTtl(options.ttl, options.expiresAt, this.ttl),
+			tags: options.tags,
+			onConflict: options.onConflict ?? "upsert",
+			vector: options.vector,
+			staleAt: options.staleAt
+		};
+	}
+	/**
+	* Resolve the union of cache keys associated with any of the given tags.
+	* Used by `similar()` to narrow the candidate pool before similarity ranking.
+	*
+	* Returns `null` when no tags are passed (callers should treat that as "no filter").
+	*/
+	async getKeysForTags(tags) {
+		if (!tags || tags.length === 0) return null;
+		const allKeys = /* @__PURE__ */ new Set();
+		for (const tag of tags) {
+			const tagKey = `cache:tags:${tag}`;
+			const keys = await this.get(tagKey) || [];
+			for (const k of keys) allKeys.add(k);
+		}
+		return allKeys;
+	}
+	/**
+	* Apply tag relationships after a successful write. Called by drivers once
+	* the value is in storage.
+	*/
+	async applyTags(parsedKey, tags) {
+		if (tags.length === 0) return;
+		await this.tags(tags).storeTagRelationship(parsedKey);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async has(key) {
+		return await this.get(key) !== null;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remember(key, ttlOrOptions, callback) {
+		const parsedKey = this.parseKey(key);
+		const setOptions = this.normalizeRememberOptions(ttlOrOptions);
+		const cachedValue = await this.get(key);
+		if (cachedValue) return cachedValue;
+		const existingLock = this.locks.get(parsedKey);
+		if (existingLock) return existingLock;
+		const promise = callback().then(async (result) => {
+			await this.set(key, result, setOptions);
+			this.locks.delete(parsedKey);
+			return result;
+		}).catch((err) => {
+			this.locks.delete(parsedKey);
+			throw err;
+		});
+		this.locks.set(parsedKey, promise);
+		return promise;
+	}
+	/**
+	* Resolve the TTL-or-options arg of `remember` into a `CacheSetOptions` object
+	* that can be passed straight to `set()`. Keeps the implementation unbranched.
+	*/
+	normalizeRememberOptions(ttlOrOptions) {
+		if (typeof ttlOrOptions === "number" || typeof ttlOrOptions === "string") return { ttl: ttlOrOptions };
+		return {
+			ttl: ttlOrOptions.ttl,
+			tags: ttlOrOptions.tags
+		};
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: read raw entry, branch on freshness/staleness,
+	* trigger background refresh in the stale window, fall through to
+	* `callback` on miss/expiry. Concurrent stale-window callers share a
+	* single in-flight refresh via {@link locks}.
+	*
+	* Drivers without a real {@link getEntry} override degrade gracefully —
+	* the synthetic entry has no `staleAt`, which the freshness check treats
+	* as "always fresh," so SWR behaves like a TTL-only cached read on those
+	* drivers (no background refresh, but no double-fetch either).
+	*/
+	async swr(key, options, callback) {
+		const parsedKey = this.parseKey(key);
+		const freshSeconds = parseTtl(options.freshTtl);
+		const staleSeconds = parseTtl(options.staleTtl);
+		if (staleSeconds <= freshSeconds) throw new Error(`cache.swr: 'staleTtl' (${staleSeconds}s) must be greater than 'freshTtl' (${freshSeconds}s).`);
+		const entry = await this.getEntry(key);
+		const now = Date.now();
+		const isExpired = entry?.expiresAt !== void 0 && entry.expiresAt <= now;
+		if (!entry || isExpired) return this.swrFetchAndStore(key, options, callback, freshSeconds, staleSeconds);
+		if (entry.staleAt === void 0 || entry.staleAt > now) return entry.data;
+		this.scheduleSwrRefresh(parsedKey, key, options, callback, freshSeconds, staleSeconds);
+		return entry.data;
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper for a key, including any
+	* `expiresAt` / `staleAt` metadata. Default implementation falls back to
+	* `get()` and synthesizes a metadata-less wrapper — drivers that store
+	* the wrapper directly (memory, lru, file, redis, pg, mock) override
+	* this to return real metadata so SWR can branch on freshness.
+	*/
+	async getEntry(key) {
+		const value = await this.get(key);
+		if (value === null) return null;
+		return { data: value };
+	}
+	/**
+	* Remaining lifetime of an existing entry, in seconds — used by TTL-preserving
+	* writes such as `update()` / `merge()` when the caller passes no explicit
+	* `ttl`.
+	*
+	* - `Infinity` — the entry exists with no expiry (preserve "never expires").
+	* - positive number — seconds left before the entry expires.
+	* - `undefined` — the key is missing or already past its deadline; the caller
+	*   should fall back to the driver default TTL.
+	*
+	* Default reads `expiresAt` from {@link getEntry}, which the metadata-aware
+	* drivers (memory, lru, mock, pg) populate. Drivers that track TTL natively
+	* and don't carry `expiresAt` in their payload (Redis) override this.
+	*/
+	async getRemainingTtl(key) {
+		const entry = await this.getEntry(key);
+		if (!entry) return;
+		if (!entry.expiresAt || entry.expiresAt === Infinity) return Infinity;
+		const remainingSeconds = Math.ceil((entry.expiresAt - Date.now()) / 1e3);
+		return remainingSeconds > 0 ? remainingSeconds : void 0;
+	}
+	/**
+	* Block-and-fetch path of `swr()`: invoked on miss or past-`staleTtl`
+	* expiry. Writes through `set()` with the SWR options translated into
+	* standard `CacheSetOptions` (ttl = staleTtl, staleAt = now + freshTtl).
+	*/
+	async swrFetchAndStore(key, options, callback, freshSeconds, staleSeconds) {
+		const result = await callback();
+		await this.set(key, result, {
+			ttl: staleSeconds,
+			staleAt: Date.now() + freshSeconds * 1e3,
+			tags: options.tags
+		});
+		return result;
+	}
+	/**
+	* Stale-window background refresh. Registers a single in-flight promise
+	* per parsed key so concurrent SWR callers share one refresh. Failed
+	* refreshes preserve the stale entry, log via `logError`, and emit on
+	* `error` — the stale-returning caller never sees the failure.
+	*/
+	scheduleSwrRefresh(parsedKey, key, options, callback, freshSeconds, staleSeconds) {
+		if (this.locks.has(parsedKey)) return;
+		let refresh;
+		refresh = (async () => {
+			try {
+				const result = await callback();
+				await this.set(key, result, {
+					ttl: staleSeconds,
+					staleAt: Date.now() + freshSeconds * 1e3,
+					tags: options.tags
+				});
+			} catch (error) {
+				this.logError(`SWR background refresh failed for ${parsedKey}`, error);
+				await this.emit("error", {
+					key: parsedKey,
+					error
+				});
+			} finally {
+				if (this.locks.get(parsedKey) === refresh) this.locks.delete(parsedKey);
+			}
+		})();
+		this.locks.set(parsedKey, refresh);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pull(key) {
+		const value = await this.get(key);
+		if (value !== null) await this.remove(key);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async forever(key, value) {
+		return this.set(key, value, Infinity);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async increment(key, value = 1) {
+		const current = await this.get(key) || 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${this.parseKey(key)}`);
+		const newValue = current + value;
+		await this.set(key, newValue);
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async many(keys) {
+		return Promise.all(keys.map((key) => this.get(key)));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async setMany(items, ttl) {
+		await Promise.all(Object.entries(items).map(([key, value]) => this.set(key, value, ttl)));
+	}
+	/**
+	* Log the operation
+	*/
+	log(operation, key) {
+		if (!this.shouldLog) return;
+		if (key) key = key.replaceAll("/", ".");
+		if (operation == "notFound" || operation == "expired") return _warlock_js_logger.log.warn("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
+		if (operation.endsWith("ed")) return _warlock_js_logger.log.success("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
+		_warlock_js_logger.log.info("cache." + this.name, operation, (key ? key + " " : "") + messages[operation]);
+	}
+	/**
+	* Log error message
+	*/
+	logError(message, error) {
+		_warlock_js_logger.log.error("cache." + this.name, "error", message);
+		if (error) console.log(error);
+	}
+	/**
+	* Get the default TTL in seconds. Parses human-readable strings (`"1h"`, `"30m"`)
+	* from driver options if present; falls back to `Infinity` when no default is set.
+	*/
+	get ttl() {
+		if (this.options.ttl === void 0) return Infinity;
+		return parseTtl(this.options.ttl);
+	}
+	/**
+	* Get time to live value in milliseconds
+	*/
+	getExpiresAt(ttl = this.ttl) {
+		if (ttl) return (/* @__PURE__ */ new Date()).getTime() + ttl * 1e3;
+	}
+	/**
+	* Wrap a value with TTL and optional freshness metadata for backend
+	* storage. `staleAt` persists alongside `expiresAt` when supplied — used
+	* by the SWR flow to mark when the entry stops being fresh.
+	*/
+	prepareDataForStorage(data, ttl, staleAt) {
+		const preparedData = { data };
+		if (ttl) {
+			preparedData.ttl = ttl;
+			preparedData.expiresAt = this.getExpiresAt(ttl);
+		}
+		if (staleAt !== void 0) preparedData.staleAt = staleAt;
+		return preparedData;
+	}
+	/**
+	* Parse fetched data from cache
+	*/
+	async parseCachedData(key, data) {
+		this.log("fetched", key);
+		if (data.expiresAt && data.expiresAt < Date.now()) {
+			this.remove(key);
+			return null;
+		}
+		const value = data.data;
+		if (value === null || value === void 0) return value;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") return value;
+		try {
+			return structuredClone(value);
+		} catch (error) {
+			console.log(value);
+			this.logError(`Failed to clone cached value for ${key}, typeof value: ${typeof value}`, error);
+			throw error;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.log("connecting");
+		this.log("connected");
+		await this.emit("connected");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async disconnect() {
+		this.log("disconnected");
+		await this.emit("disconnected");
+	}
+	/**
+	* Create a tagged cache instance for the given tags
+	*/
+	tags(tags) {
+		return new TaggedCache(tags, this);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: read → transform → write under a per-key in-process
+	* lock. Drivers that can offer stronger semantics (Redis via `WATCH`/`MULTI`)
+	* should override.
+	*/
+	async update(key, fn, options = {}) {
+		const parsedKey = this.parseKey(key);
+		const next = (this.locks.get(parsedKey) ?? Promise.resolve()).catch(() => void 0).then(async () => {
+			const result = await fn(await this.get(key));
+			if (result === null) {
+				await this.remove(key);
+				return null;
+			}
+			if (options.ttl !== void 0) {
+				await this.set(key, result, { ttl: options.ttl });
+				return result;
+			}
+			const remainingTtl = await this.getRemainingTtl(key);
+			if (remainingTtl !== void 0) await this.set(key, result, { ttl: remainingTtl });
+			else await this.set(key, result);
+			return result;
+		});
+		this.locks.set(parsedKey, next);
+		next.finally(() => {
+			if (this.locks.get(parsedKey) === next) this.locks.delete(parsedKey);
+		});
+		return next;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async merge(key, partial, options = {}) {
+		return await this.update(key, (current) => {
+			return {
+				...current ?? {},
+				...partial
+			};
+		}, options);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: read-mutate-write array backed by the underlying
+	* cache entry. Concrete drivers (e.g. Redis) override with native commands.
+	*/
+	list(key) {
+		return new MemoryCacheList(this, key);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Built on top of `set({ onConflict: "create" })` — Redis-native `SET … NX EX`
+	* under the hood on Redis, emulated via key-existence check on other drivers.
+	* The lock value is the resolved `owner` (defaults to `pid.<process.pid>`).
+	*
+	* Always releases in `finally`, even if `fn` throws — the thrown error
+	* propagates to the caller unchanged.
+	*/
+	async lock(key, ttlOrOptions, fn) {
+		const { ttl, owner } = this.normalizeLockOptions(ttlOrOptions);
+		const lockOwner = owner ?? `pid.${process.pid}`;
+		const setResult = await this.set(key, lockOwner, {
+			onConflict: "create",
+			ttl
+		});
+		if (!(typeof setResult === "object" && setResult !== null && "wasSet" in setResult ? setResult.wasSet : true)) return { acquired: false };
+		try {
+			return {
+				acquired: true,
+				value: await fn()
+			};
+		} finally {
+			await this.remove(key);
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation throws {@link CacheUnsupportedError}. Drivers that
+	* support similarity retrieval (memory family, `pg`, `redis` w/ RediSearch)
+	* override this with a real impl.
+	*/
+	async similar(_vector, _options) {
+		throw new CacheUnsupportedError(`'${this.name}' driver does not support similarity retrieval. Use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).`);
+	}
+	/**
+	* Resolve the TTL-or-options arg of `lock` into a uniform shape.
+	*/
+	normalizeLockOptions(ttlOrOptions) {
+		if (typeof ttlOrOptions === "number" || typeof ttlOrOptions === "string") return { ttl: ttlOrOptions };
+		return {
+			ttl: ttlOrOptions.ttl,
+			owner: ttlOrOptions.owner
+		};
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/file-cache-driver.ts
+var FileCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "file";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		if (!options.directory) throw new CacheConfigurationError("File driver requires 'directory' option to be configured.");
+		return super.setOptions(options);
+	}
+	/**
+	* Get the cache directory
+	*/
+	get directory() {
+		const directory = this.options.directory;
+		if (typeof directory === "function") return directory();
+		throw new CacheConfigurationError("Cache directory is not defined, please define it in the file driver options");
+	}
+	/**
+	* Get file name
+	*/
+	get fileName() {
+		const fileName = this.options.fileName;
+		if (typeof fileName === "function") return fileName();
+		return "cache.json";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.log("clearing", namespace);
+		try {
+			await (0, _warlock_js_fs.removeDirectoryAsync)(path.default.resolve(this.directory, namespace));
+			this.log("cleared", namespace);
+		} catch (error) {}
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		if (vector) throw new CacheUnsupportedError("'file' driver does not support similarity retrieval — use a memory driver, 'pg' (with pgvector), or 'redis' (with RediSearch).");
+		this.log("caching", parsedKey);
+		const existing = onConflict === "upsert" ? null : await this.get(key);
+		const exists = existing !== null;
+		if (onConflict === "create" && exists) return {
+			wasSet: false,
+			existing
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		const data = this.prepareDataForStorage(value, ttl, staleAt);
+		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		await (0, _warlock_js_fs.ensureDirectoryAsync)(fileDirectory);
+		await (0, _warlock_js_fs.putJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName), data);
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* File driver does not yet ship with a file-lock primitive, so concurrent
+	* writers could clobber each other. Rather than ship an unsafe default, we
+	* throw — consumers can fall back to memory/redis for `update` until a
+	* proper file lock lands (tracked in `domains/cache/backlog.md`).
+	*/
+	async update() {
+		throw new CacheUnsupportedError("`update()` is not supported on the file driver. Use the memory or redis driver, or wait for the file-lock primitive (see domains/cache/backlog.md).");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async merge() {
+		throw new CacheUnsupportedError("`merge()` is not supported on the file driver. Use the memory or redis driver.");
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper from disk, including `staleAt`
+	* metadata. Returns `null` for missing or expired files — `swr()`
+	* consumes this to branch on freshness.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		try {
+			const entry = await (0, _warlock_js_fs.getJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName));
+			if (!entry) return null;
+			if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
+			return entry;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		try {
+			const value = await (0, _warlock_js_fs.getJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName));
+			const result = await this.parseCachedData(parsedKey, value);
+			if (result === null) await this.emit("miss", { key: parsedKey });
+			else await this.emit("hit", {
+				key: parsedKey,
+				value: result
+			});
+			return result;
+		} catch (error) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			await this.remove(key);
+			return null;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const fileDirectory = path.default.resolve(this.directory, parsedKey);
+		try {
+			await (0, _warlock_js_fs.removeDirectoryAsync)(fileDirectory);
+			this.log("removed", parsedKey);
+			await this.emit("removed", { key: parsedKey });
+		} catch (error) {}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await (0, _warlock_js_fs.removeDirectoryAsync)(this.directory);
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.log("connecting");
+		await (0, _warlock_js_fs.ensureDirectoryAsync)(this.directory);
+		this.log("connected");
+		await this.emit("connected");
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/lru-memory-cache-driver.ts
+var CacheNode = class {
+	constructor(key, value, ttl) {
+		this.key = key;
+		this.value = value;
+		this.next = null;
+		this.prev = null;
+		if (ttl && ttl !== Infinity) this.expiresAt = Date.now() + ttl * 1e3;
+	}
+	get isExpired() {
+		return this.expiresAt !== void 0 && this.expiresAt < Date.now();
+	}
+};
+/**
+* LRU Memory Cache Driver
+* The concept of LRU is to remove the least recently used data
+* whenever the cache is full
+* The question that resides here is how to tell the cache is full?
+*/
+var LRUMemoryCacheDriver = class extends BaseCacheDriver {
+	/**
+	* {@inheritdoc}
+	*/
+	constructor() {
+		super();
+		this.name = "lru";
+		this.cache = /* @__PURE__ */ new Map();
+		this.head = new CacheNode("", null);
+		this.tail = new CacheNode("", null);
+		this.init();
+		this.startCleanup();
+	}
+	/**
+	* Initialize the cache
+	*/
+	init() {
+		this.head.next = this.tail;
+		this.tail.prev = this.head;
+	}
+	/**
+	* Start the cleanup process for expired items
+	*/
+	startCleanup() {
+		if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+		this.cleanupInterval = setInterval(async () => {
+			const now = Date.now();
+			const expiredKeys = [];
+			for (const [key, node] of this.cache) if (node.expiresAt && node.expiresAt <= now) expiredKeys.push(key);
+			for (const key of expiredKeys) {
+				const node = this.cache.get(key);
+				if (node) {
+					this.removeNode(node);
+					this.cache.delete(key);
+					this.log("expired", key);
+					await this.emit("expired", { key });
+				}
+			}
+		}, 1e3);
+		this.cleanupInterval.unref();
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Clears every entry whose key starts with the parsed namespace (followed
+	* by a dot) or equals it exactly. Called with an empty namespace while a
+	* `globalPrefix` is configured, clears everything under the prefix — which
+	* is how `flush()` scopes cleanup per tenant.
+	*/
+	async removeNamespace(namespace) {
+		const parsedNamespace = this.parseKey(namespace);
+		this.log("clearing", parsedNamespace || "(all)");
+		const removed = [];
+		if (parsedNamespace === "") for (const key of this.cache.keys()) removed.push(key);
+		else {
+			const prefix = parsedNamespace + ".";
+			for (const key of this.cache.keys()) if (key === parsedNamespace || key.startsWith(prefix)) removed.push(key);
+		}
+		for (const key of removed) {
+			const node = this.cache.get(key);
+			if (node) {
+				this.removeNode(node);
+				this.cache.delete(key);
+			}
+			await this.emit("removed", { key });
+		}
+		this.log("cleared", parsedNamespace || "(all)");
+		return removed;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		this.log("caching", parsedKey);
+		let existingNode = this.cache.get(parsedKey);
+		if (existingNode && existingNode.isExpired) {
+			this.removeNode(existingNode);
+			this.cache.delete(parsedKey);
+			existingNode = void 0;
+		}
+		const exists = Boolean(existingNode);
+		if (onConflict === "create" && exists) return {
+			wasSet: false,
+			existing: existingNode.value
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		if (existingNode) {
+			existingNode.value = value;
+			if (ttl && ttl !== Infinity) existingNode.expiresAt = Date.now() + ttl * 1e3;
+			else existingNode.expiresAt = void 0;
+			existingNode.staleAt = staleAt;
+			if (vector) existingNode.vector = vector.slice();
+			this.moveHead(existingNode);
+		} else {
+			const newNode = new CacheNode(parsedKey, value, ttl);
+			newNode.staleAt = staleAt;
+			if (vector) newNode.vector = vector.slice();
+			this.cache.set(parsedKey, newNode);
+			this.addNode(newNode);
+			if (this.cache.size > this.capacity) this.removeTail();
+		}
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return this;
+	}
+	/**
+	* Move the node to the head
+	*/
+	moveHead(node) {
+		this.removeNode(node);
+		this.addNode(node);
+	}
+	/**
+	* Remove the node from the cache
+	*/
+	removeNode(node) {
+		node.prev.next = node.next;
+		node.next.prev = node.prev;
+	}
+	/**
+	* Add the node to the head
+	*/
+	addNode(node) {
+		node.next = this.head.next;
+		node.prev = this.head;
+		this.head.next.prev = node;
+		this.head.next = node;
+	}
+	/**
+	* Remove the tail node
+	*/
+	removeTail() {
+		const node = this.tail.prev;
+		this.removeNode(node);
+		this.cache.delete(node.key);
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Returns `null` for missing or expired nodes — `swr()` consumes this
+	* to branch on freshness without going through `get()`'s clone-and-emit
+	* path.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const node = this.cache.get(parsedKey);
+		if (!node || node.isExpired) return null;
+		return {
+			data: node.value,
+			expiresAt: node.expiresAt,
+			staleAt: node.staleAt
+		};
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const node = this.cache.get(parsedKey);
+		if (!node) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		if (node.isExpired) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+			this.log("expired", parsedKey);
+			await this.emit("expired", { key: parsedKey });
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.moveHead(node);
+		this.log("fetched", parsedKey);
+		const value = node.value;
+		if (value === null || value === void 0) return value;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		try {
+			const clonedValue = structuredClone(value);
+			await this.emit("hit", {
+				key: parsedKey,
+				value: clonedValue
+			});
+			return clonedValue;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${parsedKey}`, error);
+			throw error;
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const node = this.cache.get(parsedKey);
+		if (node) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+		}
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* When a `globalPrefix` is configured, `flush` scopes itself to that prefix
+	* so multi-tenant caches don't accidentally wipe sibling tenants. Without
+	* a prefix, clears everything.
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else {
+			this.cache.clear();
+			this.init();
+		}
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Brute-force O(N) cosine similarity over every cached node that carries a
+	* vector. Suitable for development and small in-memory knowledge bases —
+	* not for production beyond ~10k entries.
+	*
+	* @warning Dev-only — O(N) per query.
+	*/
+	async similar(vector, options) {
+		const tagFilter = await this.getKeysForTags(options.tags);
+		const hits = [];
+		for (const [parsedKey, node] of this.cache) {
+			if (!node.vector) continue;
+			if (node.isExpired) continue;
+			if (tagFilter && !tagFilter.has(parsedKey)) continue;
+			const score = cosineSimilarity(vector, node.vector);
+			if (options.threshold !== void 0 && score < options.threshold) continue;
+			let value = node.value;
+			if (value !== null && value !== void 0) {
+				const t = typeof value;
+				if (t !== "string" && t !== "number" && t !== "boolean") value = structuredClone(value);
+			}
+			hits.push({
+				key: parsedKey,
+				value,
+				score
+			});
+		}
+		hits.sort((a, b) => b.score - a.score);
+		if (options.topK >= 0 && hits.length > options.topK) hits.length = options.topK;
+		return hits;
+	}
+	/**
+	* Get lru capacity
+	*/
+	get capacity() {
+		return this.options.capacity || 1e3;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async disconnect() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = void 0;
+		}
+		await super.disconnect();
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/memory-cache-driver.ts
+var MemoryCacheDriver = class extends BaseCacheDriver {
+	/**
+	* {@inheritdoc}
+	*/
+	constructor() {
+		super();
+		this.name = "memory";
+		this.data = {};
+		this.temporaryData = {};
+		this.accessOrder = [];
+		this.vectorIndex = /* @__PURE__ */ new Map();
+		this.startCleanup();
+	}
+	/**
+	* Start the cleanup process whenever a data that has a cache key is set
+	*/
+	startCleanup() {
+		if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+		this.cleanupInterval = setInterval(async () => {
+			const now = Date.now();
+			for (const key in this.temporaryData) if (this.temporaryData[key].expiresAt <= now) {
+				await this.remove(this.temporaryData[key].key);
+				delete this.temporaryData[key];
+				this.log("expired", key);
+				await this.emit("expired", { key });
+			}
+		}, 1e3);
+		this.cleanupInterval.unref();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.log("clearing", namespace);
+		namespace = this.parseKey(namespace);
+		(0, _mongez_reinforcements.unset)(this.data, [namespace]);
+		if (namespace === "") this.vectorIndex.clear();
+		else {
+			const prefix = namespace + ".";
+			for (const k of [...this.vectorIndex.keys()]) if (k === namespace || k.startsWith(prefix)) this.vectorIndex.delete(k);
+		}
+		this.log("cleared", namespace);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		this.log("caching", parsedKey);
+		const existingValue = onConflict === "upsert" ? null : await this.get(key);
+		const exists = existingValue !== null;
+		if (onConflict === "create" && exists) return {
+			wasSet: false,
+			existing: existingValue
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		const data = this.prepareDataForStorage(value, ttl, staleAt);
+		if (ttl) this.setTemporaryData(key, parsedKey, ttl);
+		(0, _mongez_reinforcements.set)(this.data, parsedKey, data);
+		this.trackAccess(parsedKey);
+		if (!exists && this.options.maxSize) await this.enforceMaxSize();
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (vector) this.vectorIndex.set(parsedKey, vector.slice());
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const value = (0, _mongez_reinforcements.get)(this.data, parsedKey);
+		if (!value) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		const result = await this.parseCachedData(parsedKey, value);
+		if (result === null) await this.emit("miss", { key: parsedKey });
+		else {
+			this.trackAccess(parsedKey);
+			await this.emit("hit", {
+				key: parsedKey,
+				value: result
+			});
+		}
+		return result;
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Returns `null` for missing or expired entries so the SWR flow can branch
+	* cleanly. Does not emit `hit`/`miss` events — that's `get()`'s job.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const entry = (0, _mongez_reinforcements.get)(this.data, parsedKey);
+		if (!entry) return null;
+		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
+		return entry;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		(0, _mongez_reinforcements.unset)(this.data, [parsedKey]);
+		delete this.temporaryData[parsedKey];
+		this.removeFromAccessOrder(parsedKey);
+		this.vectorIndex.delete(parsedKey);
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) this.removeNamespace("");
+		else {
+			this.data = {};
+			this.accessOrder = [];
+			this.vectorIndex.clear();
+		}
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* Set the temporary data
+	*/
+	setTemporaryData(key, parsedKey, ttl) {
+		this.temporaryData[parsedKey] = {
+			key: JSON.stringify(key),
+			expiresAt: Date.now() + ttl * 1e3
+		};
+	}
+	/**
+	* Track access for LRU eviction
+	*/
+	trackAccess(key) {
+		if (!this.options.maxSize) return;
+		const index = this.accessOrder.indexOf(key);
+		if (index > -1) this.accessOrder.splice(index, 1);
+		this.accessOrder.push(key);
+	}
+	/**
+	* Remove key from access order tracking
+	*/
+	removeFromAccessOrder(key) {
+		const index = this.accessOrder.indexOf(key);
+		if (index > -1) this.accessOrder.splice(index, 1);
+	}
+	/**
+	* Enforce max size by evicting least recently used items.
+	*
+	* Recomputes the live cache size on every iteration — a single snapshot at
+	* the top of the loop would go stale and cause this routine to evict every
+	* entry in `accessOrder` (including the just-inserted key).
+	*/
+	async enforceMaxSize() {
+		if (!this.options.maxSize) return;
+		while (this.getCacheSize() > this.options.maxSize && this.accessOrder.length > 0) {
+			const lruKey = this.accessOrder.shift();
+			if (!lruKey) break;
+			this.log("removing", lruKey);
+			(0, _mongez_reinforcements.unset)(this.data, [lruKey]);
+			delete this.temporaryData[lruKey];
+			this.vectorIndex.delete(lruKey);
+			this.log("removed", lruKey);
+		}
+	}
+	/**
+	* Get current cache size (number of cached items)
+	*/
+	getCacheSize() {
+		return Object.keys(this.data).length;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Brute-force O(N) cosine similarity over every entry that was written with
+	* `set({ vector })`. Suitable for development and small in-memory knowledge
+	* bases — not for production beyond ~10k entries. Use the `pg` driver
+	* (with pgvector) or `redis` (with RediSearch) at scale.
+	*
+	* @warning Dev-only — O(N) per query.
+	*/
+	async similar(vector, options) {
+		const tagFilter = await this.getKeysForTags(options.tags);
+		const hits = [];
+		for (const [parsedKey, stored] of this.vectorIndex) {
+			if (tagFilter && !tagFilter.has(parsedKey)) continue;
+			const value = await this.get(parsedKey);
+			if (value === null) continue;
+			const score = cosineSimilarity(vector, stored);
+			if (options.threshold !== void 0 && score < options.threshold) continue;
+			hits.push({
+				key: parsedKey,
+				value,
+				score
+			});
+		}
+		hits.sort((a, b) => b.score - a.score);
+		if (options.topK >= 0 && hits.length > options.topK) hits.length = options.topK;
+		return hits;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async disconnect() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = void 0;
+		}
+		await super.disconnect();
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/memory-extended-cache-driver.ts
+var MemoryExtendedCacheDriver = class extends MemoryCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "memoryExtended";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const value = (0, _mongez_reinforcements.get)(this.data, parsedKey);
+		if (!value) {
+			this.log("notFound", parsedKey);
+			return null;
+		}
+		const rawTtl = value.ttl ?? this.options.ttl;
+		const ttl = rawTtl !== void 0 ? parseTtl(rawTtl) : void 0;
+		if (ttl) {
+			this.setTemporaryData(key, parsedKey, ttl);
+			value.expiresAt = this.getExpiresAt(ttl);
+		}
+		return this.parseCachedData(parsedKey, value);
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/mock-cache-driver.ts
+/**
+* In-memory cache driver with introspection helpers, intended for use as a
+* test double in downstream packages.
+*
+* **Role.** Drop-in replacement for any real driver in test setups, with
+* extra surface that makes behavioral assertions easy: every public op gets
+* recorded into {@link MockCacheDriver.callLog}, and {@link wasCalled} /
+* {@link getStored} / {@link reset} let tests verify side effects without
+* pulling in a real Redis / Postgres / file system.
+*
+* **Responsibility.**
+* - Owns: in-memory storage backed by a `Map`, the `callLog`, TTL handling
+*   via `parseCachedData`, `onConflict` policies, and tag-index storage.
+* - Does NOT own: similarity retrieval (vectors are recorded into the
+*   `callLog` but `similar()` throws — use `MemoryCacheDriver` for tests
+*   that need real nearest-neighbor scoring), connection lifecycle
+*   (no-op `connect`/`disconnect`), or eviction (no `maxSize`).
+*
+* Register it like any other driver — sub-paths are not part of the
+* package's export convention; the same single barrel ships it next to
+* the production drivers.
+*
+* @example
+* import { cache, MockCacheDriver } from "@warlock.js/cache";
+*
+* beforeEach(async () => {
+*   cache.setCacheConfigurations({
+*     default: "mock",
+*     drivers: { mock: MockCacheDriver },
+*     options: { mock: {} },
+*   });
+*   await cache.init();
+* });
+*
+* it("invalidates the user cache after update", async () => {
+*   await userService.update(42, { name: "Jane" });
+*
+*   const driver = cache.currentDriver as MockCacheDriver;
+*   expect(driver.wasCalled("remove", "users.42")).toBe(true);
+* });
+*/
+var MockCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "mock";
+		this.options = {};
+		this.storage = /* @__PURE__ */ new Map();
+		this.callLog = [];
+	}
+	/**
+	* Standard driver setup. Mirrors the null driver — no connection, no
+	* resources to release.
+	*/
+	async connect() {
+		this.recordCall("connect", void 0);
+		await super.connect();
+	}
+	/**
+	* Standard driver teardown.
+	*/
+	async disconnect() {
+		this.recordCall("disconnect", void 0);
+		await super.disconnect();
+	}
+	/**
+	* Wipe everything under `namespace`. Matches `MemoryCacheDriver` semantics
+	* — the namespace itself and any key with the namespace prefix is removed.
+	*/
+	async removeNamespace(namespace) {
+		const parsed = this.parseKey(namespace);
+		this.recordCall("removeNamespace", parsed, [namespace]);
+		this.log("clearing", parsed);
+		const prefix = parsed + ".";
+		for (const key of [...this.storage.keys()]) if (key === parsed || key.startsWith(prefix)) this.storage.delete(key);
+		this.log("cleared", parsed);
+	}
+	/**
+	* Standard `set` with full `onConflict` support. Honors scope-default TTL
+	* via {@link BaseCacheDriver.resolveSetOptions}.
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		this.recordCall("set", parsedKey, [value, ttlOrOptions]);
+		this.log("caching", parsedKey);
+		const existing = onConflict === "upsert" ? null : await this.get(key);
+		const exists = existing !== null;
+		if (onConflict === "create" && exists) return {
+			wasSet: false,
+			existing
+		};
+		if (onConflict === "update" && !exists) return {
+			wasSet: false,
+			existing: null
+		};
+		const data = this.prepareDataForStorage(value, ttl, staleAt);
+		this.storage.set(parsedKey, data);
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return value;
+	}
+	/**
+	* Standard `get` with TTL handling. Emits `hit` / `miss` events to keep
+	* downstream metrics tests realistic.
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.recordCall("get", parsedKey);
+		this.log("fetching", parsedKey);
+		const data = this.storage.get(parsedKey);
+		if (!data) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		const value = await this.parseCachedData(parsedKey, data);
+		if (value === null) {
+			this.storage.delete(parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		return value;
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper from the in-memory `Map`,
+	* including `staleAt` metadata. Returns `null` for missing or expired
+	* entries — `swr()` consumes this to branch on freshness.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const entry = this.storage.get(parsedKey);
+		if (!entry) return null;
+		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
+		return entry;
+	}
+	/**
+	* Standard `remove` — drops the entry and emits the `removed` event.
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.recordCall("remove", parsedKey);
+		this.log("removing", parsedKey);
+		this.storage.delete(parsedKey);
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* Standard `flush` — wipes the entire mock store + tag index. Does NOT
+	* touch the call log; use {@link reset} to clear that as well.
+	*/
+	async flush() {
+		this.recordCall("flush", void 0);
+		this.log("flushing");
+		this.storage.clear();
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* Was a given operation invoked? When `key` is provided, the match is
+	* post-`parseKey` so callers pass the same key shape they used at the
+	* call site — strings or objects, both resolve to the same parsed key.
+	*
+	* @example
+	* driver.wasCalled("set");                  // any set
+	* driver.wasCalled("set", "users.42");      // set on this specific key
+	* driver.wasCalled("set", { id: 42 });      // same — object key normalized
+	*/
+	wasCalled(operation, key) {
+		if (key === void 0) return this.callLog.some((call) => call.operation === operation);
+		const parsedKey = this.parseKey(key);
+		return this.callLog.some((call) => call.operation === operation && call.key === parsedKey);
+	}
+	/**
+	* Return the raw stored value for `key`, bypassing TTL handling and clone
+	* protection. Useful when a test wants to assert on the persisted shape
+	* (or assert that an entry expired without going through `get`).
+	*
+	* Returns `undefined` when the key isn't present.
+	*/
+	getStored(key) {
+		const parsedKey = this.parseKey(key);
+		const entry = this.storage.get(parsedKey);
+		if (!entry) return;
+		return entry.data;
+	}
+	/**
+	* Wipe everything — storage, tag index, and the call log. Pair with
+	* Vitest's `beforeEach` to get clean isolation between tests.
+	*/
+	reset() {
+		this.storage.clear();
+		this.callLog.length = 0;
+	}
+	/**
+	* Append a row to {@link callLog}. Internal helper called by every
+	* recorded op before the actual work runs.
+	*/
+	recordCall(operation, key, args = []) {
+		this.callLog.push({
+			operation,
+			key,
+			args,
+			timestamp: Date.now()
+		});
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/null-cache-driver.ts
+var NullCacheDriver = class extends BaseCacheDriver {
+	/**
+	* {@inheritdoc}
+	*/
+	get client() {
+		return this;
+	}
+	/**
+	* Constructor
+	*/
+	constructor(options = {}) {
+		super();
+		this.options = {};
+		this.name = "null";
+		this.data = {};
+		this.setOptions(options);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		this.options = options;
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	parseKey(_key) {
+		return "";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		_warlock_js_logger.log.info("cache", "clearing namespace", namespace);
+		_warlock_js_logger.log.success("cache", "namespace cleared", namespace);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, _value, _ttlOrOptions) {
+		_warlock_js_logger.log.info("cache", "setting key", key);
+		_warlock_js_logger.log.success("cache", "key set", key);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		_warlock_js_logger.log.info("cache", "fetching", key);
+		_warlock_js_logger.log.success("cache", "fetched", key);
+		return null;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		_warlock_js_logger.log.info("cache", "removing", key);
+		_warlock_js_logger.log.success("cache", "removed", key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		_warlock_js_logger.log.info("cache", "flushing", "all");
+		_warlock_js_logger.log.success("cache", "flushed", "all");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* The null driver is a black-hole — `similar()` mirrors `get()` and returns
+	* an empty result set rather than throwing.
+	*/
+	async similar() {
+		return [];
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		_warlock_js_logger.log.success("cache", "connected", "Connected to null cache driver");
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/pg-cache-driver.ts
+/**
+* Allowed characters in a Postgres identifier (table name). We accept the
+* conservative ASCII subset and reject anything else — interpolating an
+* arbitrary string into DDL would be a SQL-injection footgun.
+*/
+const SAFE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Postgres cache driver with optional pgvector similarity support.
+*
+* Connection lifecycle is the caller's responsibility — pass an already-built
+* `pg.Pool` or `pg.Client` via the `client` option. The driver never closes it
+* on `cache.disconnect()`, so the same pool can serve queries elsewhere in
+* the app.
+*
+* Schema is not auto-migrated. Call `driver.schema()` to get the DDL string
+* and run it through whichever migration tool you use.
+*
+* @example
+* import { Pool } from "pg";
+* import { cache, PgCacheDriver } from "@warlock.js/cache";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+*
+* cache.setCacheConfigurations({
+*   default: "pg",
+*   drivers: { pg: PgCacheDriver },
+*   options: { pg: { client: pool, table: "warlock_cache", ttl: "1h" } },
+* });
+*
+* await cache.init();
+*
+* // Run once, via your own migration tooling:
+* // await pool.query(driver.schema());
+*/
+var PgCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "pg";
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Validates `client` presence and the table name before storing options.
+	*/
+	setOptions(options) {
+		if (!options || !options.client || typeof options.client.query !== "function") throw new CacheConfigurationError("Pg cache driver requires a 'client' option implementing { query(text, values) } — pass a pg.Pool or pg.Client.");
+		const table = options.table ?? "warlock_cache";
+		if (!SAFE_IDENT.test(table)) throw new CacheConfigurationError(`Pg cache driver: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		if (options.vector) {
+			const dim = options.vector.dimensions;
+			if (!Number.isInteger(dim) || dim <= 0) throw new CacheConfigurationError(`Pg cache driver: vector.dimensions must be a positive integer; got ${dim}.`);
+			const idx = options.vector.index ?? "hnsw";
+			if (idx !== "hnsw" && idx !== "ivfflat") throw new CacheConfigurationError(`Pg cache driver: vector.index must be 'hnsw' or 'ivfflat'; got '${idx}'.`);
+		}
+		return super.setOptions({
+			...options,
+			table
+		});
+	}
+	/**
+	* Lazy pgvector availability check. Runs once on the first vector op and
+	* caches the result — subsequent ops are zero-overhead. Throws
+	* {@link CacheConfigurationError} if the extension isn't installed; throws
+	* {@link CacheUnsupportedError} if `vector` config wasn't provided at all.
+	*/
+	async ensureVectorReady() {
+		if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.");
+		if (this.vectorReady === true) return;
+		const { rows } = await this.pgClient.query(`SELECT 1 FROM pg_extension WHERE extname = 'vector'`);
+		if (rows.length === 0) throw new CacheConfigurationError("'pg' driver: pgvector extension not installed. Run 'CREATE EXTENSION vector;' or remove the 'vector' config option.");
+		this.vectorReady = true;
+	}
+	/**
+	* Format a numeric vector for pgvector ingestion. The `vector` type accepts
+	* a string literal `'[1,2,3]'` cast via `::vector` — this avoids depending
+	* on the binary protocol and works against any pg client.
+	*/
+	formatVector(vector) {
+		return `[${vector.join(",")}]`;
+	}
+	/**
+	* Resolved table name. Always defined post-`setOptions` — the validator
+	* fills in the default.
+	*/
+	get table() {
+		return this.options.table ?? "warlock_cache";
+	}
+	/**
+	* The user-supplied `pg.Pool` / `pg.Client`. Use this rather than `this.client`
+	* (which has a generic fallback to `this`) for actual queries.
+	*/
+	get pgClient() {
+		return this.options.client;
+	}
+	/**
+	* Compute an absolute `expires_at` Date for the given relative TTL in seconds,
+	* or `null` when the entry should not expire (`Infinity` / 0 / undefined).
+	*/
+	ttlToExpiresAt(ttl) {
+		if (!ttl || ttl === Infinity) return null;
+		return new Date(Date.now() + ttl * 1e3);
+	}
+	/**
+	* Return the SQL needed to provision the cache table + index. Run once via
+	* the caller's migration tooling — the driver never auto-migrates.
+	*
+	* @example
+	* await pool.query(driver.schema());
+	*/
+	schema() {
+		const t = this.table;
+		const vec = this.options.vector;
+		const columns = [
+			`  key TEXT PRIMARY KEY,`,
+			`  value JSONB NOT NULL,`,
+			`  expires_at TIMESTAMPTZ,`,
+			`  stale_at TIMESTAMPTZ,`,
+			`  tags TEXT[] NOT NULL DEFAULT '{}'::TEXT[]`
+		];
+		if (vec) {
+			columns[columns.length - 1] = columns[columns.length - 1] + ",";
+			columns.push(`  embedding VECTOR(${vec.dimensions})`);
+		}
+		const lines = [
+			`CREATE TABLE IF NOT EXISTS ${t} (`,
+			...columns,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${t}_expires_at ON ${t} (expires_at);`,
+			`CREATE INDEX IF NOT EXISTS idx_${t}_tags ON ${t} USING GIN (tags);`
+		];
+		if (vec) {
+			const idx = vec.index ?? "hnsw";
+			lines.push(`CREATE INDEX IF NOT EXISTS idx_${t}_embedding ON ${t} USING ${idx} (embedding vector_cosine_ops);`);
+		}
+		return lines.join("\n");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async connect() {
+		this.log("connecting");
+		this.log("connected");
+		await this.emit("connected");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Does NOT close the user-supplied client — lifecycle stays with the caller.
+	*/
+	async disconnect() {
+		this.log("disconnected");
+		await this.emit("disconnected");
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		if (vector) {
+			if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: cannot index a vector without options.vector configuration — set { dimensions } and recreate the table via driver.schema().");
+			const expected = this.options.vector.dimensions;
+			if (vector.length !== expected) throw new CacheConfigurationError(`Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`);
+			await this.ensureVectorReady();
+		}
+		this.log("caching", parsedKey);
+		const expiresAt = this.ttlToExpiresAt(ttl);
+		const staleAtDate = staleAt !== void 0 ? new Date(staleAt) : null;
+		const tagsArr = tags ?? [];
+		const serialized = JSON.stringify(value);
+		const vecLiteral = vector ? this.formatVector(vector) : null;
+		const t = this.table;
+		const cols = [
+			"key",
+			"value",
+			"expires_at",
+			"stale_at",
+			"tags"
+		];
+		const placeholders = [
+			"$1",
+			"$2::jsonb",
+			"$3",
+			"$4",
+			"$5"
+		];
+		const params = [
+			parsedKey,
+			serialized,
+			expiresAt,
+			staleAtDate,
+			tagsArr
+		];
+		if (vecLiteral !== null) {
+			cols.push("embedding");
+			placeholders.push(`$${params.length + 1}::vector`);
+			params.push(vecLiteral);
+		}
+		const colList = cols.join(", ");
+		const valList = placeholders.join(", ");
+		const setClause = cols.slice(1).map((c) => `${c} = EXCLUDED.${c}`).join(", ");
+		const updateSetClause = cols.slice(1).map((c, i) => `${c} = ${placeholders[i + 1]}`).join(", ");
+		if (onConflict === "create") {
+			const { rows } = await this.pgClient.query(`INSERT INTO ${t}(${colList})
+         VALUES (${valList})
+         ON CONFLICT (key) DO UPDATE
+           SET ${setClause}
+           WHERE ${t}.expires_at IS NOT NULL AND ${t}.expires_at < now()
+         RETURNING value`, params);
+			if (rows.length === 0) return {
+				wasSet: false,
+				existing: await this.get(key)
+			};
+			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+			return {
+				wasSet: true,
+				existing: null
+			};
+		}
+		if (onConflict === "update") {
+			const { rows } = await this.pgClient.query(`UPDATE ${t}
+         SET ${updateSetClause}
+         WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())
+         RETURNING value`, params);
+			if (rows.length === 0) return {
+				wasSet: false,
+				existing: null
+			};
+			if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+			return {
+				wasSet: true,
+				existing: null
+			};
+		}
+		await this.pgClient.query(`INSERT INTO ${t}(${colList})
+       VALUES (${valList})
+       ON CONFLICT (key) DO UPDATE
+         SET ${setClause}`, params);
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const t = this.table;
+		const { rows } = await this.pgClient.query(`SELECT value FROM ${t}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [parsedKey]);
+		if (rows.length === 0) {
+			this.log("notFound", parsedKey);
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.log("fetched", parsedKey);
+		let value = rows[0].value;
+		if (typeof value === "string") try {
+			value = JSON.parse(value);
+		} catch {}
+		if (value === null || value === void 0) {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key: parsedKey,
+				value
+			});
+			return value;
+		}
+		try {
+			const cloned = structuredClone(value);
+			await this.emit("hit", {
+				key: parsedKey,
+				value: cloned
+			});
+			return cloned;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${parsedKey}`, error);
+			throw error;
+		}
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Returns `null` for missing or expired rows — `swr()` consumes this to
+	* branch on freshness without going through `get()`'s clone-and-emit path.
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const { rows } = await this.pgClient.query(`SELECT value, expires_at, stale_at FROM ${t}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [parsedKey]);
+		if (rows.length === 0) return null;
+		let data = rows[0].value;
+		if (typeof data === "string") try {
+			data = JSON.parse(data);
+		} catch {}
+		const entry = { data };
+		const expiresAtRaw = rows[0].expires_at;
+		if (expiresAtRaw) entry.expiresAt = (expiresAtRaw instanceof Date ? expiresAtRaw : new Date(expiresAtRaw)).getTime();
+		const staleAtRaw = rows[0].stale_at;
+		if (staleAtRaw) entry.staleAt = (staleAtRaw instanceof Date ? staleAtRaw : new Date(staleAtRaw)).getTime();
+		return entry;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		const t = this.table;
+		await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1`, [parsedKey]);
+		this.log("removed", parsedKey);
+		await this.emit("removed", { key: parsedKey });
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Deletes all rows whose key equals the namespace exactly or starts with
+	* `<namespace>.` — same boundary semantics as the other drivers.
+	*/
+	async removeNamespace(namespace) {
+		const parsed = this.parseKey(namespace);
+		this.log("clearing", parsed || "(all)");
+		const t = this.table;
+		if (parsed === "") await this.pgClient.query(`DELETE FROM ${t}`);
+		else {
+			const escaped = parsed.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+			await this.pgClient.query(`DELETE FROM ${t} WHERE key = $1 OR key LIKE $2 ESCAPE '\\'`, [parsed, `${escaped}.%`]);
+		}
+		this.log("cleared", parsed || "(all)");
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Honors `globalPrefix` — when configured, scopes the flush to entries
+	* under the prefix rather than truncating the entire table (which could
+	* wipe sibling tenants sharing the same Postgres database).
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await this.pgClient.query(`DELETE FROM ${this.table}`);
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* pgvector-backed similarity. Uses the `<=>` cosine-distance operator
+	* (lower distance = higher similarity) and converts to cosine similarity
+	* as `1 - distance` so the returned `score` matches the rest of the
+	* package (`[0, 1]`, higher is more similar).
+	*
+	* Honors `topK`, `threshold`, and an optional `tags` filter (native
+	* `tags && $tags` overlap query — much faster than the meta-key path).
+	*
+	* Throws {@link CacheUnsupportedError} when `options.vector` was not
+	* configured at driver setup; throws {@link CacheConfigurationError} when
+	* the pgvector extension is missing or the query vector's dimension count
+	* doesn't match the configured one.
+	*/
+	async similar(vector, options) {
+		if (!this.options.vector) throw new CacheUnsupportedError("'pg' driver: similarity retrieval requires the 'vector' config block. Set options.vector.dimensions and reconnect.");
+		const expected = this.options.vector.dimensions;
+		if (vector.length !== expected) throw new CacheConfigurationError(`Pg cache driver: vector dimension mismatch — expected ${expected}, got ${vector.length}.`);
+		if (!Number.isInteger(options.topK) || options.topK <= 0) throw new CacheConfigurationError(`Pg cache driver: similar.topK must be a positive integer; got ${options.topK}.`);
+		await this.ensureVectorReady();
+		const t = this.table;
+		const params = [this.formatVector(vector)];
+		let tagFilter = "";
+		if (options.tags && options.tags.length > 0) {
+			params.push(options.tags);
+			tagFilter = `AND tags && $${params.length}`;
+		}
+		params.push(options.topK);
+		const topKParam = `$${params.length}`;
+		const { rows } = await this.pgClient.query(`SELECT key, value, 1 - (embedding <=> $1::vector) AS score
+       FROM ${t}
+       WHERE embedding IS NOT NULL
+         AND (expires_at IS NULL OR expires_at > now())
+         ${tagFilter}
+       ORDER BY embedding <=> $1::vector
+       LIMIT ${topKParam}`, params);
+		const hits = [];
+		for (const row of rows) {
+			const score = Number(row.score);
+			if (options.threshold !== void 0 && score < options.threshold) continue;
+			let value = row.value;
+			if (typeof value === "string") try {
+				value = JSON.parse(value);
+			} catch {}
+			if (value !== null && value !== void 0) {
+				const ty = typeof value;
+				if (ty !== "string" && ty !== "number" && ty !== "boolean") value = structuredClone(value);
+			}
+			hits.push({
+				key: row.key,
+				value,
+				score
+			});
+		}
+		return hits;
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/cache/src/drivers/redis-cache-driver.ts
+/**
+* Cached Redis module (loaded once, reused)
+*/
+let RedisClient;
+let isModuleExists = null;
+/**
+* Installation instructions for Redis package
+*/
+const REDIS_INSTALL_INSTRUCTIONS = `
+Redis cache driver requires the redis package.
+Install it with:
+
+  npm install redis
+
+Or with your preferred package manager:
+
+  pnpm add redis
+  yarn add redis
+`.trim();
+/**
+* Load Redis module
+*/
+async function loadRedis() {
+	try {
+		RedisClient = await import("redis");
+		isModuleExists = true;
+	} catch {
+		isModuleExists = false;
+	}
+}
+loadRedis();
+var RedisCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "redis";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		if (!options.url && !options.host) throw new CacheConfigurationError("Redis driver requires either 'url' or 'host' option to be configured.");
+		return super.setOptions(options);
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async removeNamespace(namespace) {
+		namespace = this.parseKey(namespace);
+		this.log("clearing", namespace);
+		const keys = await this.client?.keys(`${namespace}*`);
+		if (!keys || keys.length === 0) {
+			this.log("notFound", namespace);
+			return;
+		}
+		await this.client?.del(keys);
+		this.log("cleared", namespace);
+		return keys;
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.parseKey(key);
+		const { ttl, tags, onConflict, vector, staleAt } = this.resolveSetOptions(ttlOrOptions);
+		if (vector) throw new CacheUnsupportedError("'redis' driver does not yet support similarity retrieval. Phase 2 (RediSearch) is on the backlog — use a memory driver or the 'pg' driver (with pgvector) for now.");
+		this.log("caching", parsedKey);
+		const serialized = JSON.stringify(value);
+		const hasExpiry = Boolean(ttl) && ttl !== Infinity;
+		let reply;
+		if (onConflict === "create") {
+			const options = { NX: true };
+			if (hasExpiry) options.EX = ttl;
+			reply = await this.client?.set(parsedKey, serialized, options);
+		} else if (onConflict === "update") {
+			const options = { XX: true };
+			if (hasExpiry) options.EX = ttl;
+			reply = await this.client?.set(parsedKey, serialized, options);
+		} else if (hasExpiry) reply = await this.client?.set(parsedKey, serialized, { EX: ttl });
+		else reply = await this.client?.set(parsedKey, serialized);
+		if ((onConflict === "create" || onConflict === "update") && !(reply === "OK")) return {
+			wasSet: false,
+			existing: onConflict === "create" ? await this.get(key) : null
+		};
+		if (tags && tags.length > 0) await this.applyTags(parsedKey, tags);
+		if (staleAt !== void 0) {
+			const sidecarOptions = {};
+			if (hasExpiry) sidecarOptions.EX = ttl;
+			await this.client?.set(this.swrMetaKey(parsedKey), String(staleAt), sidecarOptions);
+		}
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value,
+			ttl
+		});
+		if (onConflict === "create" || onConflict === "update") return {
+			wasSet: true,
+			existing: null
+		};
+		return value;
+	}
+	/**
+	* Build the sidecar key Redis uses to track SWR freshness without
+	* wrapping the main value JSON.
+	*/
+	swrMetaKey(parsedKey) {
+		return `__swrmeta:${parsedKey}`;
+	}
+	/**
+	* Read the raw {@link CacheData} wrapper, fetching the value and the
+	* SWR sidecar in parallel. Returns `null` when the main key is missing
+	* or expired (Redis handles expiry natively, so the absence of the
+	* value alone tells us).
+	*/
+	async getEntry(key) {
+		const parsedKey = this.parseKey(key);
+		const [valueRaw, staleAtRaw] = await Promise.all([this.client?.get(parsedKey), this.client?.get(this.swrMetaKey(parsedKey))]);
+		if (!valueRaw) return null;
+		const data = JSON.parse(valueRaw);
+		const staleAt = staleAtRaw ? Number(staleAtRaw) : void 0;
+		return staleAt !== void 0 ? {
+			data,
+			staleAt
+		} : { data };
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Redis tracks expiry natively (the payload carries no `expiresAt`), so read
+	* the remaining lifetime with the `TTL` command. Redis returns `-2` for a
+	* missing key and `-1` for a key with no expiry.
+	*/
+	async getRemainingTtl(key) {
+		const parsedKey = this.parseKey(key);
+		const ttl = await this.client?.ttl(parsedKey);
+		if (ttl === void 0 || ttl === -2) return;
+		if (ttl === -1) return Infinity;
+		return ttl;
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async get(key) {
+		key = this.parseKey(key);
+		this.log("fetching", key);
+		const value = await this.client?.get(key);
+		if (!value) {
+			this.log("notFound", key);
+			await this.emit("miss", { key });
+			return null;
+		}
+		this.log("fetched", key);
+		const parsedValue = JSON.parse(value);
+		if (parsedValue === null || parsedValue === void 0) {
+			await this.emit("hit", {
+				key,
+				value: parsedValue
+			});
+			return parsedValue;
+		}
+		const type = typeof parsedValue;
+		if (type === "string" || type === "number" || type === "boolean") {
+			await this.emit("hit", {
+				key,
+				value: parsedValue
+			});
+			return parsedValue;
+		}
+		try {
+			const clonedValue = structuredClone(parsedValue);
+			await this.emit("hit", {
+				key,
+				value: clonedValue
+			});
+			return clonedValue;
+		} catch (error) {
+			this.logError(`Failed to clone cached value for ${key}`, error);
+			throw error;
+		}
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async remove(key) {
+		key = this.parseKey(key);
+		this.log("removing", key);
+		await this.client?.del([key, this.swrMetaKey(key)]);
+		this.log("removed", key);
+		await this.emit("removed", { key });
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else await this.client?.flushAll();
+		this.log("flushed");
+		await this.emit("flushed");
+	}
+	/**
+	* {@inheritDoc}
+	*/
+	async connect() {
+		if (this.clientDriver) return;
+		if (!isModuleExists) throw new Error(REDIS_INSTALL_INSTRUCTIONS);
+		const options = this.options;
+		if (options && !options.url && options.host) {
+			const auth = options.password || options.username ? `${options.username}:${options.password}@` : "";
+			if (!options.url) options.url = `redis://${auth}${options.host || "localhost"}:${options.port || 6379}`;
+		}
+		const clientOptions = {
+			...options,
+			...this.options.clientOptions || {}
+		};
+		this.log("connecting");
+		const { createClient } = RedisClient;
+		this.client = createClient(clientOptions);
+		this.client.on("error", (error) => {
+			this.log("error", error.message);
+		});
+		try {
+			await this.client.connect();
+			this.log("connected");
+			await this.emit("connected");
+		} catch (error) {
+			_warlock_js_logger.log.error("cache", "redis", error);
+			await this.emit("error", { error });
+		}
+	}
+	/**
+	* {@inheritDoc}
+	*
+	* Guards against disconnecting when the client was never created. The base
+	* `client` getter falls back to `this` when no client is set, so we check
+	* the backing `clientDriver` directly — using `this.client` for this guard
+	* would always be truthy and crash with "this.quit is not a function".
+	*/
+	async disconnect() {
+		if (!this.clientDriver) return;
+		this.log("disconnecting");
+		await this.clientDriver.quit();
+		this.log("disconnected");
+		await this.emit("disconnected");
+	}
+	/**
+	* Atomic increment using Redis native INCRBY command
+	* {@inheritdoc}
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		const result = await this.client?.incrBy(parsedKey, value);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value: result,
+			ttl: void 0
+		});
+		return result || 0;
+	}
+	/**
+	* Atomic decrement using Redis native DECRBY command
+	* {@inheritdoc}
+	*/
+	async decrement(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		const result = await this.client?.decrBy(parsedKey, value);
+		this.log("cached", parsedKey);
+		await this.emit("set", {
+			key: parsedKey,
+			value: result,
+			ttl: void 0
+		});
+		return result || 0;
+	}
+	/**
+	* Set if not exists (atomic operation)
+	* Returns true if key was set, false if key already existed
+	*/
+	async setNX(key, value, ttl) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		if (ttl === void 0) ttl = this.ttl;
+		let result;
+		if (ttl && ttl !== Infinity) result = await this.client?.set(parsedKey, JSON.stringify(value), {
+			NX: true,
+			EX: ttl
+		});
+		else result = await this.client?.set(parsedKey, JSON.stringify(value), { NX: true });
+		const wasSet = result === "OK";
+		if (wasSet) {
+			this.log("cached", parsedKey);
+			await this.emit("set", {
+				key: parsedKey,
+				value,
+				ttl
+			});
+		} else this.log("notFound", parsedKey);
+		return wasSet;
+	}
+};
+
+//#endregion
+exports.BaseCacheDriver = BaseCacheDriver;
+exports.CACHE_FOR = CACHE_FOR;
+exports.CacheConcurrencyError = CacheConcurrencyError;
+exports.CacheConfigurationError = CacheConfigurationError;
+exports.CacheConnectionError = CacheConnectionError;
+exports.CacheDriverNotInitializedError = CacheDriverNotInitializedError;
+exports.CacheError = CacheError;
+exports.CacheManager = CacheManager;
+exports.CacheMetricsCollector = CacheMetricsCollector;
+exports.CacheUnsupportedError = CacheUnsupportedError;
+exports.FileCacheDriver = FileCacheDriver;
+exports.LRUMemoryCacheDriver = LRUMemoryCacheDriver;
+exports.MemoryCacheDriver = MemoryCacheDriver;
+exports.MemoryCacheList = MemoryCacheList;
+exports.MemoryExtendedCacheDriver = MemoryExtendedCacheDriver;
+exports.MockCacheDriver = MockCacheDriver;
+exports.NullCacheDriver = NullCacheDriver;
+exports.PgCacheDriver = PgCacheDriver;
+exports.RedisCacheDriver = RedisCacheDriver;
+exports.ScopedCache = ScopedCache;
+exports.TaggedCache = TaggedCache;
+exports.TaggedScopedCache = TaggedScopedCache;
+exports.cache = cache;
+exports.cached = cached;
+exports.cosineSimilarity = cosineSimilarity;
+exports.deriveAutoKey = deriveAutoKey;
+exports.expiresAtToTtl = expiresAtToTtl;
+exports.injectTags = injectTags;
+exports.mergeTagSets = mergeTagSets;
+exports.normalizeCachedArgs = normalizeCachedArgs;
+exports.normalizeToOptions = normalizeToOptions;
+exports.normalizeToRememberOptions = normalizeToRememberOptions;
+exports.parseCacheKey = parseCacheKey;
+exports.parseTtl = parseTtl;
+exports.resolveTtl = resolveTtl;
+//# sourceMappingURL=index.cjs.map