@warlock.js/cache 5.19.0 → 5.20.0

package/cjs/index.cjs

@@ -29,7 +29,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let _mongez_reinforcements = require("@mongez/reinforcements");
 let ms = require("ms");
 ms = __toESM(ms, 1);
+let node_crypto = require("node:crypto");
 let _warlock_js_logger = require("@warlock.js/logger");
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs, 1);
 let _warlock_js_fs = require("@warlock.js/fs");
 let path = require("path");
 path = __toESM(path, 1);
@@ -303,27 +306,37 @@ function parseCacheKey(key, options = {}) {
 * Parse a TTL value into seconds.
 *
 * Accepts:
-* - a number (already in seconds) — returned unchanged
+* - a number (seconds) — fractions are rounded UP to whole seconds
+*   (so Redis `EX` never receives a fraction); `0` means "no expiry"
 * - `Infinity` — no expiration, returned unchanged
-* - a human-readable duration string (e.g. `"1h"`, `"30m"`, `"7d"`) — parsed via `ms` then converted to seconds
+* - a bare numeric string (e.g. `"3600"`, from env vars) — treated as seconds
+* - a human-readable duration string (e.g. `"1h"`, `"30m"`, `"7d"`) — parsed via `ms`,
+*   then converted to seconds, rounding up
 *
-* Throws `CacheConfigurationError` on unparseable strings or negative numbers.
+* Throws `CacheConfigurationError` on NaN, negative numbers, or unparseable strings.
 *
 * @example
 * parseTtl(3600);      // 3600
+* parseTtl(0.5);       // 1
+* parseTtl("3600");    // 3600
+* parseTtl("500ms");   // 1
 * parseTtl("1h");      // 3600
 * parseTtl("7d");      // 604800
 * parseTtl(Infinity);  // Infinity
 */
 function parseTtl(input) {
 	if (typeof input === "number") {
+		if (Number.isNaN(input)) throw new CacheConfigurationError("Invalid TTL: NaN.");
 		if (input < 0) throw new CacheConfigurationError(`Invalid TTL: negative number (${input}).`);
-		return input;
+		return Math.ceil(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);
+	const trimmed = input.trim();
+	if (/^\d+(\.\d+)?$/.test(trimmed)) return Math.ceil(Number(trimmed));
+	const milliseconds = (0, ms.default)(trimmed);
 	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);
+	if (milliseconds < 0) throw new CacheConfigurationError(`Invalid TTL: negative duration ("${input}").`);
+	return Math.ceil(milliseconds / 1e3);
 }
 /**
 * Convert an absolute `expiresAt` (Date or epoch milliseconds) into a
@@ -595,17 +608,29 @@ var TaggedScopedCache = class {
 		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 the scoped key and take it out of every tag index this handle
+	* writes to (scope tags + handle tags).
 	*/
-	remove(key) {
-		return this.scope.remove(key);
+	async remove(key) {
+		await this.scope.remove(key);
+		await this.detachFromTags(key);
 	}
 	/**
-	* Read-and-remove the scoped key.
+	* Read-and-remove the scoped key, then take it out of this handle's tags.
 	*/
-	pull(key) {
-		return this.scope.pull(key);
+	async pull(key) {
+		const value = await this.scope.pull(key);
+		if (value !== null) await this.detachFromTags(key);
+		return value;
+	}
+	/**
+	* Remove the un-prefixed scoped key from every tag index of this handle.
+	*/
+	async detachFromTags(key) {
+		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
+		if (!allTags || allTags.length === 0) return;
+		const scopedKey = this.buildScopedKey(key);
+		await this.scope.source.tags(allTags).detachFromTags(parseCacheKey(scopedKey));
 	}
 	/**
 	* Permanent write with handle tags applied. Bypasses both the scope's and
@@ -846,19 +871,31 @@ var ScopedCache = class ScopedCache {
 		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.
+	* Atomic read-modify-write. An explicit `options.ttl` always wins. Otherwise
+	* the scope's default `ttl` is applied only when the key does not exist yet;
+	* for an existing key no ttl is passed so the source preserves the entry's
+	* remaining TTL.
 	*/
-	update(key, fn, options) {
-		return this.source.update(this.scopedKey(key), fn, { ttl: options?.ttl ?? this.defaults.ttl });
+	async update(key, fn, options) {
+		const scopedKey = this.scopedKey(key);
+		return this.source.update(scopedKey, fn, await this.writeOptions(scopedKey, options));
 	}
 	/**
 	* 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 });
+	async merge(key, partial, options) {
+		const scopedKey = this.scopedKey(key);
+		return this.source.merge(scopedKey, partial, await this.writeOptions(scopedKey, options));
+	}
+	/**
+	* Resolve the ttl options for update/merge: explicit ttl, else the scope
+	* default only for keys that don't exist yet, else nothing (keep remaining).
+	*/
+	async writeOptions(scopedKey, options) {
+		if (options?.ttl !== void 0) return { ttl: options.ttl };
+		if (this.defaults.ttl === void 0) return {};
+		return await this.source.has(scopedKey) ? {} : { ttl: this.defaults.ttl };
 	}
 	/**
 	* Return a list accessor bound to the scoped key. The accessor itself
@@ -946,6 +983,7 @@ var ScopedCache = class ScopedCache {
 var CacheManager = class {
 	constructor() {
 		this.loadedDrivers = {};
+		this.loadingDrivers = /* @__PURE__ */ new Map();
 		this.configurations = {
 			drivers: {},
 			options: {}
@@ -1177,6 +1215,11 @@ var CacheManager = class {
 			this.assertNoConflictingReload(driver, runtimeOptions);
 			return this.loadedDrivers[driver];
 		}
+		const inFlight = this.loadingDrivers.get(driver);
+		if (inFlight) {
+			this.assertNoConflictingReload(driver, runtimeOptions);
+			return inFlight;
+		}
 		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();
@@ -1185,10 +1228,18 @@ var CacheManager = class {
 			...configOptions,
 			...runtimeOptions ?? {}
 		});
-		await driverInstance.connect();
-		this.attachGlobalListeners(driverInstance);
-		this.loadedDrivers[driver] = driverInstance;
-		return driverInstance;
+		const promise = (async () => {
+			try {
+				await driverInstance.connect();
+				this.attachGlobalListeners(driverInstance);
+				this.loadedDrivers[driver] = driverInstance;
+				return driverInstance;
+			} finally {
+				this.loadingDrivers.delete(driver);
+			}
+		})();
+		this.loadingDrivers.set(driver, promise);
+		return promise;
 	}
 	/**
 	* Guard against silently dropping runtime options on a re-load. Once a
@@ -1212,7 +1263,11 @@ var CacheManager = class {
 	* Disconnect the cache manager
 	*/
 	async disconnect() {
-		if (this.currentDriver) await this.currentDriver.disconnect();
+		const drivers = new Set(Object.values(this.loadedDrivers));
+		if (this.currentDriver) drivers.add(this.currentDriver);
+		await Promise.allSettled([...drivers].map((driver) => driver.disconnect()));
+		for (const name of Object.keys(this.loadedDrivers)) delete this.loadedDrivers[name];
+		this.loadingDrivers.clear();
 	}
 	/**
 	* {@inheritdoc}
@@ -1426,50 +1481,65 @@ const cache = new CacheManager();
 /**
 * 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`.
+* The key is `<prefix>.<hash>` where `hash` is the first 16 hex chars of the
+* sha1 of a stable JSON encoding of the args. Hashing keeps the mapping
+* injective — raw punctuation-joined segments can be folded together by
+* `parseCacheKey` (e.g. `("1.private", "")` vs `("1", "private")`).
+*
+* Encoding rules: object keys are sorted, `Date` → ISO string, `undefined` →
+* `{"$u":1}`, `bigint` → decimal string with an `n` suffix.
+*
+* No args → the prefix alone.
+*
+* Map, Set, functions, symbols and class instances cannot be encoded stably
+* and throw `CacheConfigurationError`; supply a custom `key` function instead.
 *
 * @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"
+* deriveAutoKey("featured", []);        // "featured"
+* deriveAutoKey("user", [42]);          // "user.<16 hex chars>"
 */
 function deriveAutoKey(prefix, args) {
 	if (args.length === 0) return prefix;
-	if (args.every(isPrimitiveOrNullish)) return prefix + "." + args.map(serializePrimitive).join(".");
+	let encoded;
 	try {
-		return prefix + "." + JSON.stringify(args);
+		encoded = JSON.stringify(args.map((arg) => normalize(arg, prefix, /* @__PURE__ */ new Set())));
 	} 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}`);
+		if (error instanceof CacheConfigurationError) throw error;
+		throw new CacheConfigurationError(`cached(): could not derive an auto-key from args for prefix "${prefix}". The args are not serializable. Use the options form with a custom key function. Original error: ${error.message}`);
 	}
+	return `${prefix}.${(0, node_crypto.createHash)("sha1").update(encoded).digest("hex").slice(0, 16)}`;
 }
-/**
-* 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";
+function unsupported(prefix, what) {
+	throw new CacheConfigurationError(`cached(): cannot derive an auto-key for prefix "${prefix}" from ${what}. Use the options form with a custom key function.`);
 }
-/**
-* 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);
+function normalize(value, prefix, seen) {
+	if (value === void 0) return { $u: 1 };
+	if (value === null) return null;
+	switch (typeof value) {
+		case "string":
+		case "boolean": return value;
+		case "number": return Number.isFinite(value) ? value : { $n: String(value) };
+		case "bigint": return `${value.toString()}n`;
+		case "function": return unsupported(prefix, "a function argument");
+		case "symbol": return unsupported(prefix, "a symbol argument");
+	}
+	const obj = value;
+	if (obj instanceof Date) return Number.isNaN(obj.getTime()) ? { $d: "invalid" } : obj.toISOString();
+	if (obj instanceof Map) return unsupported(prefix, "a Map argument");
+	if (obj instanceof Set) return unsupported(prefix, "a Set argument");
+	if (seen.has(obj)) throw new CacheConfigurationError(`cached(): could not derive an auto-key for prefix "${prefix}": circular reference in args. Use the options form with a custom key function.`);
+	seen.add(obj);
+	let result;
+	if (Array.isArray(obj)) result = obj.map((item) => normalize(item, prefix, seen));
+	else {
+		const proto = Object.getPrototypeOf(obj);
+		if (proto !== Object.prototype && proto !== null) unsupported(prefix, "a class instance argument");
+		const out = {};
+		for (const key of Object.keys(obj).sort()) out[key] = normalize(obj[key], prefix, seen);
+		result = out;
+	}
+	seen.delete(obj);
+	return result;
 }
 
 //#endregion
@@ -1509,6 +1579,10 @@ function cached(fn, prefixOrOptions, maybeTtl) {
 	});
 	wrapper.invalidate = async (...args) => {
 		const key = config.key(...args);
+		if (config.driver) {
+			await (await cache.driver(config.driver)).remove(key);
+			return;
+		}
 		await cache.remove(key);
 	};
 	return wrapper;
@@ -1524,13 +1598,14 @@ function cached(fn, prefixOrOptions, maybeTtl) {
 * 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.
+* runs through `driver.update()`, so it is serialized in-process and keeps the
+* entry's remaining TTL.
 *
 * **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.
+* - Does NOT own: cross-process concurrency control (callers should wrap in a
+*   distributed lock when multi-process writers are possible), or tagging of
+*   list entries.
 *
 * @example
 * // Never constructed directly — obtained via driver.list():
@@ -1550,53 +1625,48 @@ var MemoryCacheList = class {
 		return Array.isArray(current) ? [...current] : [];
 	}
 	/**
-	* Persist the backing array. Removes the entry when empty to keep the
-	* store clean.
+	* Serialized read-modify-write through `driver.update()`. No ttl is passed,
+	* so the driver keeps the entry's remaining TTL. An empty list removes the
+	* entry 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);
+	async mutate(mutation) {
+		let result;
+		await this.driver.update(this.key, (current) => {
+			const items = Array.isArray(current) ? [...current] : [];
+			result = mutation(items);
+			return items.length === 0 ? null : items;
+		});
+		return result;
 	}
 	/**
 	* {@inheritdoc}
 	*/
-	async push(...items) {
-		const current = await this.read();
-		current.push(...items);
-		await this.write(current);
-		return current.length;
+	push(...items) {
+		return this.mutate((current) => {
+			current.push(...items);
+			return current.length;
+		});
 	}
 	/**
 	* {@inheritdoc}
 	*/
-	async unshift(...items) {
-		const current = await this.read();
-		current.unshift(...items);
-		await this.write(current);
-		return current.length;
+	unshift(...items) {
+		return this.mutate((current) => {
+			current.unshift(...items);
+			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;
+	pop() {
+		return this.mutate((current) => current.length === 0 ? null : current.pop());
 	}
 	/**
 	* {@inheritdoc}
 	*/
-	async shift() {
-		const current = await this.read();
-		if (current.length === 0) return null;
-		const value = current.shift();
-		await this.write(current);
-		return value;
+	shift() {
+		return this.mutate((current) => current.length === 0 ? null : current.shift());
 	}
 	/**
 	* {@inheritdoc}
@@ -1617,11 +1687,17 @@ var MemoryCacheList = class {
 		return (await this.read()).length;
 	}
 	/**
-	* {@inheritdoc}
+	* Keep the inclusive range `[start, end]` like Redis LTRIM; negative
+	* indexes count from the end.
 	*/
 	async trim(start, end) {
-		const trimmed = (await this.read()).slice(start, end + 1);
-		await this.write(trimmed);
+		await this.mutate((current) => {
+			const length = current.length;
+			const from = start < 0 ? Math.max(length + start, 0) : start;
+			const to = end < 0 ? length + end : end;
+			const kept = current.slice(from, to + 1);
+			current.splice(0, current.length, ...kept);
+		});
 	}
 	/**
 	* {@inheritdoc}
@@ -1637,7 +1713,7 @@ var MemoryCacheList = class {
 * Tagged Cache Wrapper
 * Wraps a cache driver to automatically manage tag relationships
 */
-var TaggedCache = class {
+var TaggedCache = class TaggedCache {
 	/**
 	* Constructor
 	*/
@@ -1670,13 +1746,52 @@ var TaggedCache = class {
 		const indexedKey = this.indexedKey(key);
 		for (const tag of this.cacheTags) {
 			const tagKey = this.tagKey(tag);
-			const keys = await this.driver.get(tagKey) || [];
-			if (!keys.includes(indexedKey)) {
-				keys.push(indexedKey);
-				await this.driver.set(tagKey, keys, Infinity);
-			}
+			await this.addToTag(tagKey, [indexedKey]);
+			await this.pruneTag(tagKey, indexedKey);
 		}
 	}
+	static {
+		this.PRUNE_CHECKS_PER_WRITE = 20;
+	}
+	/**
+	* Drop index members whose entry no longer exists (expired, evicted, or
+	* removed outside a tagged handle). Checks a random window of at most
+	* {@link PRUNE_CHECKS_PER_WRITE} members, so a long-lived index converges
+	* to its live members without any write paying for a full scan.
+	*/
+	async pruneTag(tagKey, justWritten) {
+		const members = (await this.membersOf(tagKey)).filter((member) => member !== justWritten);
+		if (members.length === 0) return;
+		const limit = TaggedCache.PRUNE_CHECKS_PER_WRITE;
+		const start = members.length > limit ? Math.floor(Math.random() * members.length) : 0;
+		const window = Array.from({ length: Math.min(limit, members.length) }, (_, index) => members[(start + index) % members.length]);
+		const missing = [];
+		for (const member of window) if (!await this.driver.has(member)) missing.push(member);
+		if (missing.length > 0) await this.removeFromTag(tagKey, missing);
+	}
+	async addToTag(tagKey, members) {
+		if (typeof this.driver.tagAdd === "function") return this.driver.tagAdd(tagKey, members);
+		const current = await this.legacyMembers(tagKey);
+		const merged = [...new Set([...current, ...members])];
+		if (merged.length !== current.length) await this.driver.set(tagKey, merged, Infinity);
+	}
+	async membersOf(tagKey) {
+		if (typeof this.driver.tagMembers === "function") return this.driver.tagMembers(tagKey);
+		return this.legacyMembers(tagKey);
+	}
+	async removeFromTag(tagKey, members) {
+		if (typeof this.driver.tagRemove === "function") return this.driver.tagRemove(tagKey, members);
+		const dropped = new Set(members);
+		const current = await this.legacyMembers(tagKey);
+		const kept = current.filter((member) => !dropped.has(member));
+		if (kept.length === current.length) return;
+		if (kept.length === 0) await this.driver.remove(tagKey);
+		else await this.driver.set(tagKey, kept, Infinity);
+	}
+	async legacyMembers(tagKey) {
+		const value = await this.driver.get(tagKey);
+		return Array.isArray(value) ? value.filter((member) => typeof member === "string") : [];
+	}
 	/**
 	* The form a key takes inside a tag index: normalized but un-prefixed.
 	*
@@ -1695,11 +1810,7 @@ var TaggedCache = class {
 	*/
 	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);
-		}
+		for (const tag of this.cacheTags) for (const key of await this.membersOf(this.tagKey(tag))) allKeys.add(key);
 		return allKeys;
 	}
 	/**
@@ -1722,19 +1833,24 @@ var TaggedCache = class {
 	async remove(key) {
 		const indexedKey = this.indexedKey(key);
 		await this.driver.remove(key);
+		await this.detachFromTags(indexedKey);
+	}
+	/**
+	* Invalidate (clear) all keys associated with the current tags
+	*/
+	async invalidate() {
 		for (const tag of this.cacheTags) {
 			const tagKey = this.tagKey(tag);
-			const updatedKeys = (await this.driver.get(tagKey) || []).filter((k) => k !== indexedKey);
-			await this.driver.set(tagKey, updatedKeys, Infinity);
+			const members = await this.membersOf(tagKey);
+			for (const member of members) await this.driver.remove(member);
+			await this.removeFromTag(tagKey, members);
 		}
 	}
 	/**
-	* Invalidate (clear) all keys associated with the current tags
+	* Remove `indexedKey` from every tag of this handle.
 	*/
-	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));
+	async detachFromTags(indexedKey) {
+		for (const tag of this.cacheTags) await this.removeFromTag(this.tagKey(tag), [indexedKey]);
 	}
 	/**
 	* Flush all keys associated with the current tags
@@ -1763,8 +1879,8 @@ var TaggedCache = class {
 	* {@inheritdoc}
 	*/
 	async pull(key) {
-		const value = await this.get(key);
-		if (value !== null) await this.remove(key);
+		const value = await this.driver.pull(key);
+		if (value !== null) await this.detachFromTags(this.indexedKey(key));
 		return value;
 	}
 	/**
@@ -1777,10 +1893,8 @@ var TaggedCache = class {
 	* {@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);
+		const newValue = await this.driver.increment(key, value);
+		await this.storeTaggedKey(key);
 		return newValue;
 	}
 	/**
@@ -1817,7 +1931,10 @@ var BaseCacheDriver = class {
 	constructor() {
 		this.shouldLog = true;
 		this.eventListeners = /* @__PURE__ */ new Map();
-		this.locks = /* @__PURE__ */ new Map();
+		this.rememberInFlight = /* @__PURE__ */ new Map();
+		this.swrFetchInFlight = /* @__PURE__ */ new Map();
+		this.swrRefreshes = /* @__PURE__ */ new Map();
+		this.updateChains = /* @__PURE__ */ new Map();
 	}
 	/**
 	* {@inheritdoc}
@@ -1926,13 +2043,67 @@ var BaseCacheDriver = class {
 		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) || [];
+			const keys = await this.tagMembers(`cache:tags:${tag}`);
 			for (const k of keys) allKeys.add(this.parseKey(k));
 		}
 		return allKeys;
 	}
 	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: the index is an ordinary entry holding a string
+	* array, read-modified-written under {@link runSerialized} — correct within
+	* THIS process only. Drivers with a native primitive override it (redis SET,
+	* pg atomic upsert, the in-process drivers' {@link InMemoryTagIndex}).
+	*/
+	async tagAdd(tagKey, members) {
+		if (members.length === 0) return;
+		await this.runSerialized(this.parseKey(tagKey), async () => {
+			const current = await this.readTagArray(tagKey);
+			const merged = new Set(current);
+			for (const member of members) merged.add(member);
+			if (merged.size !== current.length) await this.set(tagKey, [...merged], Infinity);
+		});
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		return this.readTagArray(tagKey);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Default implementation: serialized read-filter-write (process-local); an
+	* emptied index is removed.
+	*/
+	async tagRemove(tagKey, members) {
+		if (members.length === 0) return;
+		await this.runSerialized(this.parseKey(tagKey), async () => {
+			const current = await this.readTagArray(tagKey);
+			const dropped = new Set(members);
+			const kept = current.filter((member) => !dropped.has(member));
+			if (kept.length === current.length) return;
+			if (kept.length === 0) await this.remove(tagKey);
+			else await this.set(tagKey, kept, Infinity);
+		});
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		await this.runSerialized(this.parseKey(tagKey), () => this.remove(tagKey));
+	}
+	/**
+	* The index stored as a plain entry, or `[]`. Non-string members (a corrupted
+	* or foreign value) are ignored rather than trusted.
+	*/
+	async readTagArray(tagKey) {
+		const value = await this.get(tagKey);
+		if (!Array.isArray(value)) return [];
+		return value.filter((member) => typeof member === "string");
+	}
+	/**
 	* Apply tag relationships after a successful write. Called by drivers once
 	* the value is in storage.
 	*
@@ -1950,25 +2121,44 @@ var BaseCacheDriver = class {
 		return await this.get(key) !== null;
 	}
 	/**
+	* Run `task` once per key at a time: concurrent callers for the same
+	* `parsedKey` share the in-flight promise registered in `inFlight`.
+	*/
+	singleFlight(inFlight, parsedKey, task) {
+		const existing = inFlight.get(parsedKey);
+		if (existing) return existing;
+		const promise = task().finally(() => {
+			if (inFlight.get(parsedKey) === promise) inFlight.delete(parsedKey);
+		});
+		inFlight.set(parsedKey, promise);
+		return promise;
+	}
+	/**
+	* Chain `task` after every earlier serialized task for the same key, so
+	* read-modify-write callers in THIS process run one at a time. This is
+	* process-local: it does not coordinate with other servers.
+	*/
+	runSerialized(parsedKey, task) {
+		const next = (this.updateChains.get(parsedKey) ?? Promise.resolve()).catch(() => void 0).then(task);
+		this.updateChains.set(parsedKey, next);
+		next.finally(() => {
+			if (this.updateChains.get(parsedKey) === next) this.updateChains.delete(parsedKey);
+		}).catch(() => void 0);
+		return next;
+	}
+	/**
 	* {@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) => {
+		if (cachedValue !== null && cachedValue !== void 0) return cachedValue;
+		return this.singleFlight(this.rememberInFlight, parsedKey, async () => {
+			const result = await callback();
 			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
@@ -1986,8 +2176,9 @@ var BaseCacheDriver = class {
 	*
 	* 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}.
+	* `callback` on miss/expiry. Concurrent cold-miss callers share one fetch
+	* ({@link swrFetchInFlight}); concurrent stale-window callers share one
+	* background refresh ({@link swrRefreshes}).
 	*
 	* Drivers without a real {@link getEntry} override degrade gracefully —
 	* the synthetic entry has no `staleAt`, which the freshness check treats
@@ -2002,7 +2193,7 @@ var BaseCacheDriver = class {
 		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 || isExpired) return this.singleFlight(this.swrFetchInFlight, parsedKey, () => 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;
@@ -2061,7 +2252,7 @@ var BaseCacheDriver = class {
 	* `error` — the stale-returning caller never sees the failure.
 	*/
 	scheduleSwrRefresh(parsedKey, key, options, callback, freshSeconds, staleSeconds) {
-		if (this.locks.has(parsedKey)) return;
+		if (this.swrRefreshes.has(parsedKey)) return;
 		let refresh;
 		refresh = (async () => {
 			try {
@@ -2078,18 +2269,25 @@ var BaseCacheDriver = class {
 					error
 				});
 			} finally {
-				if (this.locks.get(parsedKey) === refresh) this.locks.delete(parsedKey);
+				if (this.swrRefreshes.get(parsedKey) === refresh) this.swrRefreshes.delete(parsedKey);
 			}
 		})();
-		this.locks.set(parsedKey, refresh);
+		this.swrRefreshes.set(parsedKey, refresh);
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* Default implementation: get-then-remove, serialized per key in THIS
+	* process. Drivers with a native primitive override it to be atomic across
+	* servers (redis `GETDEL`, pg `DELETE … RETURNING`) or process-atomic
+	* (memory, lru, mock).
 	*/
 	async pull(key) {
-		const value = await this.get(key);
-		if (value !== null) await this.remove(key);
-		return value;
+		return this.runSerialized(this.parseKey(key), async () => {
+			const value = await this.get(key);
+			if (value !== null) await this.remove(key);
+			return value;
+		});
 	}
 	/**
 	* {@inheritdoc}
@@ -2099,13 +2297,24 @@ var BaseCacheDriver = class {
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* Default implementation: read-add-write serialized per key in THIS process,
+	* keeping the entry's remaining TTL (a missing key starts from 0 with the
+	* driver default TTL). Not atomic across servers: drivers with a native
+	* primitive override it (redis `INCRBY`, pg single-statement upsert).
 	*/
 	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;
+		const parsedKey = this.parseKey(key);
+		return this.runSerialized(parsedKey, async () => {
+			const current = await this.get(key);
+			const base = current === null || current === void 0 ? 0 : current;
+			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+			const newValue = base + value;
+			const remainingTtl = current === null ? void 0 : await this.getRemainingTtl(key);
+			if (remainingTtl !== void 0) await this.set(key, newValue, { ttl: remainingTtl });
+			else await this.set(key, newValue);
+			return newValue;
+		});
 	}
 	/**
 	* {@inheritdoc}
@@ -2220,13 +2429,12 @@ var BaseCacheDriver = class {
 	/**
 	* {@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.
+	* Default implementation: read → transform → write, serialized per key in
+	* THIS process only. Drivers that can offer cross-server atomicity (redis,
+	* pg: compare-and-set with retries) override it.
 	*/
 	async update(key, fn, options = {}) {
-		const parsedKey = this.parseKey(key);
-		const next = (this.locks.get(parsedKey) ?? Promise.resolve()).catch(() => void 0).then(async () => {
+		return this.runSerialized(this.parseKey(key), async () => {
 			const result = await fn(await this.get(key));
 			if (result === null) {
 				await this.remove(key);
@@ -2241,11 +2449,6 @@ var BaseCacheDriver = class {
 			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}
@@ -2275,12 +2478,16 @@ var BaseCacheDriver = class {
 	* 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.
+	* propagates to the caller unchanged, and a failed release is logged rather
+	* than replacing `fn`'s result or error. The ttl must be finite and
+	* positive; there is no renewal, so it must exceed the worst-case duration.
 	*/
 	async lock(key, ttlOrOptions, fn) {
 		const { ttl, owner } = this.normalizeLockOptions(ttlOrOptions);
-		const lockOwner = owner ?? `pid.${process.pid}`;
-		const setResult = await this.set(key, lockOwner, {
+		const ttlSeconds = parseTtl(ttl);
+		if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) throw new CacheConfigurationError(`cache.lock() requires a finite, positive ttl (got ${String(ttl)}). The ttl must exceed the worst-case duration of the locked work.`);
+		const lockValue = `${owner ?? `pid.${process.pid}`}#${(0, node_crypto.randomUUID)()}`;
+		const setResult = await this.set(key, lockValue, {
 			onConflict: "create",
 			ttl
 		});
@@ -2291,10 +2498,26 @@ var BaseCacheDriver = class {
 				value: await fn()
 			};
 		} finally {
-			await this.remove(key);
+			try {
+				await this.deleteIfEquals(key, lockValue);
+			} catch (error) {
+				this.logError(`lock release failed for ${this.parseKey(key)}`, error);
+			}
 		}
 	}
 	/**
+	* Compare-and-delete: remove `key` only when its current value equals
+	* `expected`. Returns whether a delete happened.
+	*
+	* This default is get-then-remove and is NOT atomic across processes; drivers
+	* with a real primitive (memory, redis, pg) override it.
+	*/
+	async deleteIfEquals(key, expected) {
+		if (await this.get(key) !== expected) return false;
+		await this.remove(key);
+		return true;
+	}
+	/**
 	* {@inheritdoc}
 	*
 	* Default implementation throws {@link CacheUnsupportedError}. Drivers that
@@ -2357,6 +2580,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	* only ever produces a single filesystem component here.
 	*/
 	keyDirectory(parsedKey) {
+		if (parsedKey === "") throw new CacheConfigurationError("Cache key must not be empty.");
 		return this.containedPath(this.encodeKeySegment(parsedKey));
 	}
 	/**
@@ -2421,18 +2645,17 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* `onConflict: "create"` is exclusive (temp file + hard link, so `lock()`
+	* is safe across concurrent writers). `onConflict: "update"` is NOT atomic:
+	* the existence probe and the write are separate steps.
 	*/
 	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
-		};
+		const exists = (onConflict === "upsert" || onConflict === "create" ? null : await this.get(key)) !== null;
 		if (onConflict === "update" && !exists) return {
 			wasSet: false,
 			existing: null
@@ -2440,7 +2663,14 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		const data = this.prepareDataForStorage(value, ttl, staleAt);
 		const fileDirectory = this.keyDirectory(parsedKey);
 		await (0, _warlock_js_fs.ensureDirectoryAsync)(fileDirectory);
-		await (0, _warlock_js_fs.putJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName), data);
+		const filePath = path.default.resolve(fileDirectory, this.fileName);
+		if (onConflict === "create") {
+			const conflict = await this.writeExclusive(filePath, data);
+			if (conflict) return {
+				wasSet: false,
+				existing: conflict.existing
+			};
+		} else await (0, _warlock_js_fs.atomicWriteJsonAsync)(filePath, data);
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
@@ -2455,6 +2685,44 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		return this;
 	}
 	/**
+	* Create `filePath` only if it does not exist. Writes a temp file, then
+	* hard-links it to the target (EEXIST = already present). An existing but
+	* expired entry is removed (the file only, never the directory) and the
+	* link retried once.
+	*
+	* Returns `null` when written, or `{ existing }` on conflict.
+	*/
+	async writeExclusive(filePath, data) {
+		const tempPath = `${filePath}.${(0, node_crypto.randomBytes)(6).toString("hex")}.tmp`;
+		try {
+			await node_fs.default.promises.writeFile(tempPath, JSON.stringify(data, null, 2));
+			for (let attempt = 0; attempt < 2; attempt++) {
+				try {
+					await node_fs.default.promises.link(tempPath, filePath);
+					return null;
+				} catch (error) {
+					if (error?.code !== "EEXIST") throw error;
+				}
+				let current;
+				try {
+					current = await (0, _warlock_js_fs.getJsonFileAsync)(filePath);
+				} catch {
+					current = void 0;
+				}
+				const expired = current?.expiresAt !== void 0 && current.expiresAt !== null && current.expiresAt <= Date.now();
+				if (current && !expired) return { existing: current.data ?? null };
+				if (attempt === 0 && expired) {
+					await node_fs.default.promises.rm(filePath, { force: true });
+					continue;
+				}
+				return { existing: null };
+			}
+			return { existing: null };
+		} finally {
+			await node_fs.default.promises.unlink(tempPath).catch(() => void 0);
+		}
+	}
+	/**
 	* {@inheritdoc}
 	*
 	* File driver does not yet ship with a file-lock primitive, so concurrent
@@ -2495,21 +2763,24 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		const parsedKey = this.parseKey(key);
 		this.log("fetching", parsedKey);
 		const fileDirectory = this.keyDirectory(parsedKey);
+		let value;
 		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) {
+			value = await (0, _warlock_js_fs.getJsonFileAsync)(path.default.resolve(fileDirectory, this.fileName));
+		} catch {
+			value = void 0;
+		}
+		if (value === void 0 || value === null || typeof value !== "object") {
 			this.log("notFound", parsedKey);
 			await this.emit("miss", { key: parsedKey });
-			await this.remove(key);
 			return null;
 		}
+		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;
 	}
 	/**
 	* {@inheritdoc}
@@ -2545,6 +2816,77 @@ var FileCacheDriver = class extends BaseCacheDriver {
 	}
 };
 
+//#endregion
+//#region ../cache/src/drivers/in-memory-tag-index.ts
+/**
+* Tag index for the in-process drivers (memory, memoryExtended, lru, mock).
+*
+* Lives beside the driver's entry storage, never inside it: index sets are not
+* entries, so they are never subject to `maxSize` / LRU eviction or TTL
+* sweeps, and every operation is synchronous — concurrent tagged writes in one
+* process can never drop a member.
+*
+* Keys are the driver-parsed tag keys (`<prefix>.cache.tags.<tag>`); members
+* are the caller's normalized, un-prefixed cache keys.
+*/
+var InMemoryTagIndex = class {
+	constructor() {
+		this.sets = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Add members to a tag set, creating it on first use.
+	*/
+	add(tagKey, members) {
+		if (members.length === 0) return;
+		let set = this.sets.get(tagKey);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.sets.set(tagKey, set);
+		}
+		for (const member of members) set.add(member);
+	}
+	/**
+	* The members of a tag set (a copy; empty when the set does not exist).
+	*/
+	members(tagKey) {
+		return [...this.sets.get(tagKey) ?? []];
+	}
+	/**
+	* Remove members from a tag set; an emptied set is dropped.
+	*/
+	remove(tagKey, members) {
+		const set = this.sets.get(tagKey);
+		if (!set) return;
+		for (const member of members) set.delete(member);
+		if (set.size === 0) this.sets.delete(tagKey);
+	}
+	/**
+	* Drop a whole tag set.
+	*/
+	delete(tagKey) {
+		this.sets.delete(tagKey);
+	}
+	/**
+	* Drop every tag set whose key equals `namespace` or sits under
+	* `namespace.` — the same rule the drivers use for entries. An empty
+	* namespace clears everything.
+	*/
+	removeNamespace(namespace) {
+		if (namespace === "") {
+			this.sets.clear();
+			return;
+		}
+		const prefix = namespace + ".";
+		for (const key of [...this.sets.keys()]) if (key === namespace || key.startsWith(prefix)) this.sets.delete(key);
+	}
+	/**
+	* Drop every tag set.
+	*/
+	clear() {
+		this.sets.clear();
+	}
+};
+
 //#endregion
 //#region ../cache/src/drivers/lru-memory-cache-driver.ts
 var CacheNode = class {
@@ -2573,6 +2915,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		super();
 		this.name = "lru";
 		this.cache = /* @__PURE__ */ new Map();
+		this.tagIndex = new InMemoryTagIndex();
 		this.head = new CacheNode("", null);
 		this.tail = new CacheNode("", null);
 		this.init();
@@ -2618,6 +2961,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		const parsedNamespace = this.parseKey(namespace);
 		this.log("clearing", parsedNamespace || "(all)");
 		const removed = [];
+		this.tagIndex.removeNamespace(parsedNamespace);
 		if (parsedNamespace === "") for (const key of this.cache.keys()) removed.push(key);
 		else {
 			const prefix = parsedNamespace + ".";
@@ -2732,6 +3076,72 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		};
 	}
 	/**
+	* Live node for `parsedKey`, or `undefined` when missing / expired (an
+	* expired node is unlinked). Synchronous.
+	*/
+	liveNode(parsedKey) {
+		const node = this.cache.get(parsedKey);
+		if (!node) return;
+		if (node.isExpired) {
+			this.removeNode(node);
+			this.cache.delete(parsedKey);
+			return;
+		}
+		return node;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read, add and write run synchronously (no `await` in between), so
+	* concurrent increments in this process never lose an update. An existing
+	* node keeps its expiry; a missing key starts from 0 with the default TTL.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		const node = this.liveNode(parsedKey);
+		const current = node ? node.value : 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = current + value;
+		if (node) {
+			node.value = newValue;
+			this.moveHead(node);
+		} else {
+			const newNode = new CacheNode(parsedKey, newValue, this.ttl);
+			this.cache.set(parsedKey, newNode);
+			this.addNode(newNode);
+			if (this.cache.size > this.capacity) this.removeTail();
+		}
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read and unlink run synchronously, so a value is handed out exactly once
+	* even when concurrent callers pull the same key.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const node = this.liveNode(parsedKey);
+		if (!node) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.removeNode(node);
+		this.cache.delete(parsedKey);
+		const value = node.value !== null && typeof node.value === "object" ? structuredClone(node.value) : node.value;
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async get(key) {
@@ -2792,6 +3202,32 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 	/**
 	* {@inheritdoc}
 	*
+	* Synchronous in-process set, never evicted or expired with the entries.
+	*/
+	async tagAdd(tagKey, members) {
+		this.tagIndex.add(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		return this.tagIndex.members(this.parseKey(tagKey));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagRemove(tagKey, members) {
+		this.tagIndex.remove(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		this.tagIndex.delete(this.parseKey(tagKey));
+	}
+	/**
+	* {@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.
@@ -2801,6 +3237,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		if (this.options.globalPrefix) await this.removeNamespace("");
 		else {
 			this.cache.clear();
+			this.tagIndex.clear();
 			this.init();
 		}
 		this.log("flushed");
@@ -2859,29 +3296,50 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 
 //#endregion
 //#region ../cache/src/drivers/memory-cache-driver.ts
+/**
+* Clone non-primitive values so cached state can't be mutated through
+* references held by callers. Primitives are immutable and returned as-is.
+*/
+function cloneValue(value) {
+	if (value === null || value === void 0) return value;
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean") return value;
+	return structuredClone(value);
+}
 var MemoryCacheDriver = class extends BaseCacheDriver {
+	/**
+	* Read-only object view of the stored entries, keyed by parsed key.
+	* Kept for introspection; the values are the live stored wrappers.
+	*/
+	get data() {
+		return Object.fromEntries(this.entries);
+	}
 	/**
 	* {@inheritdoc}
 	*/
 	constructor() {
 		super();
 		this.name = "memory";
-		this.data = {};
-		this.temporaryData = {};
-		this.accessOrder = [];
+		this.entries = /* @__PURE__ */ new Map();
+		this.expiry = /* @__PURE__ */ new Map();
 		this.vectorIndex = /* @__PURE__ */ new Map();
+		this.tagIndex = new InMemoryTagIndex();
+		this.slidingExpiration = false;
 		this.startCleanup();
 	}
 	/**
-	* Start the cleanup process whenever a data that has a cache key is set
+	* Start the cleanup process for entries that carry a finite ttl
 	*/
 	startCleanup() {
 		if (this.cleanupInterval) clearInterval(this.cleanupInterval);
 		this.cleanupInterval = setInterval(async () => {
 			const now = Date.now();
-			for (const [key, entry] of Object.entries(this.temporaryData)) if (entry.expiresAt <= now) {
-				await this.remove(entry.key);
-				delete this.temporaryData[key];
+			const expiredKeys = [];
+			for (const [key, expiresAt] of this.expiry) if (expiresAt <= now) expiredKeys.push(key);
+			for (const key of expiredKeys) {
+				const expiresAt = this.expiry.get(key);
+				if (expiresAt === void 0 || expiresAt > now) continue;
+				this.dropEntry(key);
 				this.log("expired", key);
 				await this.emit("expired", { key });
 			}
@@ -2889,44 +3347,94 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		this.cleanupInterval.unref();
 	}
 	/**
-	* {@inheritdoc}
+	* Delete an entry and every side record (expiry, vector). Synchronous.
 	*/
-	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;
+	dropEntry(parsedKey) {
+		this.entries.delete(parsedKey);
+		this.expiry.delete(parsedKey);
+		this.vectorIndex.delete(parsedKey);
 	}
 	/**
-	* {@inheritdoc}
+	* Raw, synchronous read of a live entry. An expired entry is deleted and
+	* reported as missing. Never slides TTLs, never emits, never touches LRU order.
+	*/
+	readLive(parsedKey) {
+		const entry = this.entries.get(parsedKey);
+		if (!entry) return;
+		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+			this.dropEntry(parsedKey);
+			return;
+		}
+		return entry;
+	}
+	/**
+	* Mark an entry as most recently used (only tracked when `maxSize` is set).
+	*/
+	touch(parsedKey, entry) {
+		if (!this.options.maxSize) return;
+		this.entries.delete(parsedKey);
+		this.entries.set(parsedKey, entry);
+	}
+	/**
+	* Invoked on a live read hit, before the value is returned. Runs only from
+	* `get()` after the expiry check, so an expired entry is never resurrected,
+	* and never from the internal existence check used by `onConflict`.
+	*/
+	onRead(parsedKey, entry) {
+		if (!this.slidingExpiration) return;
+		const rawTtl = entry.ttl ?? this.options.ttl;
+		const ttl = rawTtl !== void 0 ? parseTtl(rawTtl) : void 0;
+		if (ttl && Number.isFinite(ttl)) {
+			entry.expiresAt = this.getExpiresAt(ttl);
+			this.expiry.set(parsedKey, entry.expiresAt);
+		}
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.log("clearing", namespace);
+		namespace = this.parseKey(namespace);
+		this.tagIndex.removeNamespace(namespace);
+		if (namespace === "") {
+			this.entries.clear();
+			this.expiry.clear();
+			this.vectorIndex.clear();
+		} else {
+			const prefix = namespace + ".";
+			for (const key of [...this.entries.keys()]) if (key === namespace || key.startsWith(prefix)) this.dropEntry(key);
+		}
+		this.log("cleared", namespace);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* The conditional check and the write run with no `await` in between, so
+	* `onConflict` decisions are atomic within the process.
 	*/
 	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 {
+		const existing = onConflict === "create" || onConflict === "update" ? this.readLive(parsedKey) : void 0;
+		if (onConflict === "create" && existing) return {
 			wasSet: false,
-			existing: existingValue
+			existing: cloneValue(existing.data)
 		};
-		if (onConflict === "update" && !exists) return {
+		if (onConflict === "update" && !existing) 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(key, tags);
+		const data = this.prepareDataForStorage(cloneValue(value), ttl, staleAt);
+		this.entries.delete(parsedKey);
+		this.entries.set(parsedKey, data);
+		if (data.expiresAt !== void 0 && Number.isFinite(data.expiresAt)) this.expiry.set(parsedKey, data.expiresAt);
+		else this.expiry.delete(parsedKey);
 		if (vector) this.vectorIndex.set(parsedKey, vector.slice());
+		else this.vectorIndex.delete(parsedKey);
+		this.enforceMaxSize(parsedKey);
+		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -2941,38 +3449,101 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* The check and the delete run synchronously (no `await` between them), so
+	* the compare-and-delete is atomic within the process.
+	*/
+	async deleteIfEquals(key, expected) {
+		const parsedKey = this.parseKey(key);
+		const entry = this.readLive(parsedKey);
+		if (!entry || entry.data !== expected) return false;
+		await this.remove(key);
+		return true;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read, add and write run synchronously (no `await` in between), so
+	* concurrent increments in this process never lose an update. An existing
+	* entry keeps its expiry; a missing key starts from 0 with the default TTL.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		const entry = this.readLive(parsedKey);
+		const current = entry ? entry.data : 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = current + value;
+		if (entry) {
+			entry.data = newValue;
+			this.touch(parsedKey, entry);
+		} else {
+			const data = this.prepareDataForStorage(newValue, this.ttl);
+			this.entries.set(parsedKey, data);
+			if (data.expiresAt !== void 0 && Number.isFinite(data.expiresAt)) this.expiry.set(parsedKey, data.expiresAt);
+			this.enforceMaxSize(parsedKey);
+		}
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: entry?.ttl ?? this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Read and delete run synchronously, so a value is handed out exactly once
+	* even when concurrent callers pull the same key.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const entry = this.readLive(parsedKey);
+		if (!entry) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.dropEntry(parsedKey);
+		const value = cloneValue(entry.data);
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
+	* {@inheritdoc}
 	*/
 	async get(key) {
 		const parsedKey = this.parseKey(key);
 		this.log("fetching", parsedKey);
-		const value = (0, _mongez_reinforcements.get)(this.data, parsedKey);
-		if (!value) {
+		const entry = this.readLive(parsedKey);
+		if (!entry) {
 			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
-			});
-		}
+		this.onRead(parsedKey, entry);
+		this.touch(parsedKey, entry);
+		const result = await this.parseCachedData(parsedKey, entry);
+		await this.emit("hit", {
+			key: parsedKey,
+			value: result
+		});
 		return result;
 	}
 	/**
-	* Read the raw {@link CacheData} wrapper, including `staleAt` metadata.
+	* Read the raw {@link CacheData} wrapper (cloned), 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);
+		const entry = this.readLive(this.parseKey(key));
 		if (!entry) return null;
-		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
-		return entry;
+		return {
+			...entry,
+			data: cloneValue(entry.data)
+		};
 	}
 	/**
 	* {@inheritdoc}
@@ -2980,76 +3551,65 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 	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.dropEntry(parsedKey);
 		this.log("removed", parsedKey);
 		await this.emit("removed", { key: parsedKey });
 	}
 	/**
 	* {@inheritdoc}
+	*
+	* Synchronous in-process set — concurrent tagged writes never drop members.
 	*/
-	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");
+	async tagAdd(tagKey, members) {
+		this.tagIndex.add(this.parseKey(tagKey), members);
 	}
 	/**
-	* Set the temporary data
+	* {@inheritdoc}
 	*/
-	setTemporaryData(key, parsedKey, ttl) {
-		this.temporaryData[parsedKey] = {
-			key: JSON.stringify(key),
-			expiresAt: Date.now() + ttl * 1e3
-		};
+	async tagMembers(tagKey) {
+		return this.tagIndex.members(this.parseKey(tagKey));
 	}
 	/**
-	* Track access for LRU eviction
+	* {@inheritdoc}
 	*/
-	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);
+	async tagRemove(tagKey, members) {
+		this.tagIndex.remove(this.parseKey(tagKey), members);
 	}
 	/**
-	* Remove key from access order tracking
+	* {@inheritdoc}
 	*/
-	removeFromAccessOrder(key) {
-		const index = this.accessOrder.indexOf(key);
-		if (index > -1) this.accessOrder.splice(index, 1);
+	async tagDelete(tagKey) {
+		this.tagIndex.delete(this.parseKey(tagKey));
 	}
 	/**
-	* 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).
+	* {@inheritdoc}
 	*/
-	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);
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) await this.removeNamespace("");
+		else {
+			this.entries.clear();
+			this.expiry.clear();
+			this.vectorIndex.clear();
+			this.tagIndex.clear();
 		}
+		this.log("flushed");
+		await this.emit("flushed");
 	}
 	/**
-	* Get current cache size (number of cached items)
+	* Evict least recently used entries (Map insertion order) until the size is
+	* within `maxSize`. Never evicts `protectedKey` (the key just written).
 	*/
-	getCacheSize() {
-		return Object.keys(this.data).length;
+	enforceMaxSize(protectedKey) {
+		const maxSize = this.options.maxSize;
+		if (!maxSize) return;
+		for (const lruKey of [...this.entries.keys()]) {
+			if (this.entries.size <= maxSize) break;
+			if (lruKey === protectedKey) continue;
+			this.log("removing", lruKey);
+			this.dropEntry(lruKey);
+			this.log("removed", lruKey);
+		}
 	}
 	/**
 	* {@inheritdoc}
@@ -3064,16 +3624,11 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 	async similar(vector, options) {
 		const tagFilter = await this.getKeysForTags(options.tags);
 		const hits = [];
-		for (const [parsedKey, stored] of this.vectorIndex) {
+		for (const [parsedKey, stored] of [...this.vectorIndex]) {
 			if (tagFilter && !tagFilter.has(parsedKey)) continue;
-			const entry = (0, _mongez_reinforcements.get)(this.data, parsedKey);
+			const entry = this.readLive(parsedKey);
 			if (!entry) continue;
-			if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) continue;
-			let value = entry.data;
-			if (value !== null && value !== void 0) {
-				const type = typeof value;
-				if (type !== "string" && type !== "number" && type !== "boolean") value = structuredClone(value);
-			}
+			const value = cloneValue(entry.data);
 			const score = cosineSimilarity(vector, stored);
 			if (options.threshold !== void 0 && score < options.threshold) continue;
 			hits.push({
@@ -3100,29 +3655,18 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 
 //#endregion
 //#region ../cache/src/drivers/memory-extended-cache-driver.ts
+/**
+* Memory driver with a sliding ttl: every live read pushes the entry's
+* expiration forward by its ttl. The sliding itself lives in
+* `MemoryCacheDriver.onRead`, which checks expiry first, so an expired entry
+* is never resurrected and the internal `onConflict` existence check never
+* slides a held lock.
+*/
 var MemoryExtendedCacheDriver = class extends MemoryCacheDriver {
-	constructor(..._args) {
-		super(..._args);
+	constructor() {
+		super();
 		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);
+		this.slidingExpiration = true;
 	}
 };
 
@@ -3175,6 +3719,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		this.name = "mock";
 		this.options = {};
 		this.storage = /* @__PURE__ */ new Map();
+		this.tagIndex = new InMemoryTagIndex();
 		this.callLog = [];
 	}
 	/**
@@ -3201,6 +3746,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		this.recordCall("removeNamespace", parsed, [namespace]);
 		this.log("clearing", parsed);
 		const prefix = parsed + ".";
+		this.tagIndex.removeNamespace(parsed);
 		for (const key of [...this.storage.keys()]) if (key === parsed || key.startsWith(prefix)) this.storage.delete(key);
 		this.log("cleared", parsed);
 	}
@@ -3213,17 +3759,20 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		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 {
+		let existing = onConflict === "create" || onConflict === "update" ? this.storage.get(parsedKey) : void 0;
+		if (existing && existing.expiresAt !== void 0 && existing.expiresAt <= Date.now()) {
+			this.storage.delete(parsedKey);
+			existing = void 0;
+		}
+		if (onConflict === "create" && existing) return {
 			wasSet: false,
-			existing
+			existing: this.cloneValue(existing.data)
 		};
-		if (onConflict === "update" && !exists) return {
+		if (onConflict === "update" && !existing) return {
 			wasSet: false,
 			existing: null
 		};
-		const data = this.prepareDataForStorage(value, ttl, staleAt);
+		const data = this.prepareDataForStorage(this.cloneValue(value), ttl, staleAt);
 		this.storage.set(parsedKey, data);
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
@@ -3236,7 +3785,14 @@ var MockCacheDriver = class extends BaseCacheDriver {
 			wasSet: true,
 			existing: null
 		};
-		return value;
+		return this;
+	}
+	/**
+	* Clone non-primitive values so stored state can't be mutated by callers.
+	*/
+	cloneValue(value) {
+		if (value === null || value === void 0 || typeof value !== "object") return value;
+		return structuredClone(value);
 	}
 	/**
 	* Standard `get` with TTL handling. Emits `hit` / `miss` events to keep
@@ -3265,6 +3821,59 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		return value;
 	}
 	/**
+	* Live entry for `parsedKey`, or `undefined` when missing / expired (an
+	* expired entry is deleted). Synchronous.
+	*/
+	liveEntry(parsedKey) {
+		const entry = this.storage.get(parsedKey);
+		if (!entry) return;
+		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+			this.storage.delete(parsedKey);
+			return;
+		}
+		return entry;
+	}
+	/**
+	* Synchronous read-add-write (atomic within the process). Keeps an existing
+	* entry's expiry; a missing key starts from 0 with the default TTL.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		this.recordCall("increment", parsedKey, [value]);
+		const entry = this.liveEntry(parsedKey);
+		const current = entry ? entry.data : 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = current + value;
+		if (entry) entry.data = newValue;
+		else this.storage.set(parsedKey, this.prepareDataForStorage(newValue, this.ttl));
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* Synchronous read-and-delete: a value is handed out exactly once.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		this.recordCall("pull", parsedKey);
+		const entry = this.liveEntry(parsedKey);
+		if (!entry) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		this.storage.delete(parsedKey);
+		const value = this.cloneValue(entry.data);
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		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.
@@ -3274,7 +3883,10 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		const entry = this.storage.get(parsedKey);
 		if (!entry) return null;
 		if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) return null;
-		return entry;
+		return {
+			...entry,
+			data: this.cloneValue(entry.data)
+		};
 	}
 	/**
 	* Standard `remove` — drops the entry and emits the `removed` event.
@@ -3288,6 +3900,32 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		await this.emit("removed", { key: parsedKey });
 	}
 	/**
+	* {@inheritdoc}
+	*
+	* Synchronous in-process set, never evicted or expired with the entries.
+	*/
+	async tagAdd(tagKey, members) {
+		this.tagIndex.add(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		return this.tagIndex.members(this.parseKey(tagKey));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagRemove(tagKey, members) {
+		this.tagIndex.remove(this.parseKey(tagKey), members);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		this.tagIndex.delete(this.parseKey(tagKey));
+	}
+	/**
 	* Standard `flush` — wipes the entire mock store + tag index. Does NOT
 	* touch the call log; use {@link reset} to clear that as well.
 	*/
@@ -3295,6 +3933,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		this.recordCall("flush", void 0);
 		this.log("flushing");
 		this.storage.clear();
+		this.tagIndex.clear();
 		this.log("flushed");
 		await this.emit("flushed");
 	}
@@ -3332,6 +3971,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 	*/
 	reset() {
 		this.storage.clear();
+		this.tagIndex.clear();
 		this.callLog.length = 0;
 	}
 	/**
@@ -3377,8 +4017,16 @@ var NullCacheDriver = class extends BaseCacheDriver {
 	/**
 	* {@inheritdoc}
 	*/
-	parseKey(_key) {
-		return "";
+	parseKey(key) {
+		return super.parseKey(key);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Nothing is stored, so always run the callback and return its own result.
+	*/
+	async remember(_key, _ttlOrOptions, callback) {
+		return callback();
 	}
 	/**
 	* {@inheritdoc}
@@ -3437,6 +4085,8 @@ var NullCacheDriver = class extends BaseCacheDriver {
 
 //#endregion
 //#region ../cache/src/drivers/pg-cache-driver.ts
+/** Compare-and-set attempts before `update()` gives up under contention. */
+const PG_UPDATE_MAX_ATTEMPTS = 10;
 /**
 * Allowed characters in a Postgres identifier (table name). We accept the
 * conservative ASCII subset and reject anything else — interpolating an
@@ -3532,12 +4182,94 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		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).
+	* {@inheritdoc}
+	*
+	* Single `DELETE … WHERE key AND value` — atomic in Postgres.
+	*/
+	async deleteIfEquals(key, expected) {
+		const parsedKey = this.parseKey(key);
+		if ((await this.pgClient.query(`DELETE FROM ${this.table}
+       WHERE key = $1 AND value = $2::jsonb AND (expires_at IS NULL OR expires_at > now())
+       RETURNING 1`, [parsedKey, JSON.stringify(expected)])).rows.length === 0) return false;
+		await this.emit("removed", { key: parsedKey });
+		return true;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One `INSERT … ON CONFLICT DO UPDATE` that unions the stored JSON array with
+	* `members`. Postgres row-locks the conflicting row, so concurrent adders on
+	* any number of servers serialize and none is lost.
+	*
+	* The index stays a row of the main table holding a JSON array — the same
+	* shape earlier versions wrote — so no schema change or migration is needed
+	* and existing indexes keep working. (The `tags` column only records tags
+	* passed inline to `set()`, not relationships added afterwards, so it can't
+	* serve as the invalidation index.)
+	*/
+	async tagAdd(tagKey, members) {
+		if (members.length === 0) return;
+		const t = this.table;
+		await this.pgClient.query(`/* cache:tag-add */ INSERT INTO ${t} (key, value)
+       VALUES ($1, to_jsonb($2::text[]))
+       ON CONFLICT (key) DO UPDATE
+         SET value = (
+           SELECT COALESCE(jsonb_agg(u.member), '[]'::jsonb)
+           FROM (
+             SELECT x.member FROM jsonb_array_elements_text(
+               CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END
+             ) AS x(member)
+             UNION
+             SELECT y.member FROM unnest($2::text[]) AS y(member)
+           ) AS u
+         ),
+         expires_at = NULL`, [this.parseKey(tagKey), members]);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One `UPDATE` that filters `members` out of the stored array (members added
+	* concurrently are kept), then a conditional `DELETE` of the row if it ended
+	* up empty.
 	*/
-	ttlToExpiresAt(ttl) {
+	async tagRemove(tagKey, members) {
+		if (members.length === 0) return;
+		const t = this.table;
+		const parsedKey = this.parseKey(tagKey);
+		await this.pgClient.query(`/* cache:tag-remove */ UPDATE ${t}
+       SET value = (
+         SELECT COALESCE(jsonb_agg(x.member), '[]'::jsonb)
+         FROM jsonb_array_elements_text(
+           CASE WHEN jsonb_typeof(${t}.value) = 'array' THEN ${t}.value ELSE '[]'::jsonb END
+         ) AS x(member)
+         WHERE x.member <> ALL($2::text[])
+       )
+       WHERE key = $1`, [parsedKey, members]);
+		await this.pgClient.query(`/* cache:tag-drop-empty */ DELETE FROM ${t} WHERE key = $1 AND value = '[]'::jsonb`, [parsedKey]);
+	}
+	/**
+	* TTL in seconds bound to `now() + make_interval(secs => $n)`, so expiry is
+	* computed on the DB clock (immune to app/DB clock skew). `null` — from
+	* `Infinity` / 0 / undefined — yields a NULL `expires_at` (never expires).
+	*/
+	ttlToSeconds(ttl) {
 		if (!ttl || ttl === Infinity) return null;
-		return new Date(Date.now() + ttl * 1e3);
+		return ttl;
+	}
+	/**
+	* Delete expired rows in batches of `limit`. Returns how many were removed.
+	* Also invoked opportunistically (~1 in 200 writes) by `set()`.
+	*/
+	async prune(limit = 1e3) {
+		const t = this.table;
+		return (await this.pgClient.query(`DELETE FROM ${t} WHERE ctid IN (SELECT ctid FROM ${t} WHERE expires_at < now() LIMIT $1)`, [limit])).rowCount ?? 0;
+	}
+	/**
+	* Fire-and-forget `prune()` on roughly 1 in 200 writes; errors are logged.
+	*/
+	maybePrune() {
+		if (Math.random() >= 1 / 200) return;
+		this.prune().catch((error) => this.logError("prune failed", error));
 	}
 	/**
 	* Return the SQL needed to provision the cache table + index. Run once via
@@ -3603,7 +4335,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			await this.ensureVectorReady();
 		}
 		this.log("caching", parsedKey);
-		const expiresAt = this.ttlToExpiresAt(ttl);
+		const expiresAt = this.ttlToSeconds(ttl);
 		const staleAtDate = staleAt !== void 0 ? new Date(staleAt) : null;
 		const tagsArr = tags ?? [];
 		const serialized = JSON.stringify(value);
@@ -3619,7 +4351,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		const placeholders = [
 			"$1",
 			"$2::jsonb",
-			"$3",
+			"now() + make_interval(secs => $3::double precision)",
 			"$4",
 			"$5"
 		];
@@ -3652,6 +4384,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			};
 			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
+			this.maybePrune();
 			await this.emit("set", {
 				key: parsedKey,
 				value,
@@ -3673,6 +4406,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			};
 			if (tags && tags.length > 0) await this.applyTags(key, tags);
 			this.log("cached", parsedKey);
+			this.maybePrune();
 			await this.emit("set", {
 				key: parsedKey,
 				value,
@@ -3689,6 +4423,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
          SET ${setClause}`, params);
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
 		this.log("cached", parsedKey);
+		this.maybePrune();
 		await this.emit("set", {
 			key: parsedKey,
 			value,
@@ -3765,6 +4500,140 @@ var PgCacheDriver = class extends BaseCacheDriver {
 		return entry;
 	}
 	/**
+	* Decode a JSONB column value (node-postgres usually parses it already;
+	* some pools hand back a string).
+	*/
+	decodeJson(value) {
+		if (typeof value === "string") try {
+			return JSON.parse(value);
+		} catch {
+			return value;
+		}
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One atomic `INSERT … ON CONFLICT DO UPDATE` statement, so concurrent
+	* increments from any number of servers never lose an update. A live row
+	* keeps its `expires_at`; a missing or expired row restarts from `value`
+	* with the driver default TTL. A non-numeric live value is rejected.
+	*/
+	async increment(key, value = 1) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const expired = `${t}.expires_at IS NOT NULL AND ${t}.expires_at <= now()`;
+		const { rows } = await this.pgClient.query(`/* cache:increment */ INSERT INTO ${t}(key, value, expires_at)
+       VALUES ($1, to_jsonb($2::numeric), now() + make_interval(secs => $3::double precision))
+       ON CONFLICT (key) DO UPDATE
+         SET value = CASE WHEN ${expired} THEN EXCLUDED.value
+                          ELSE to_jsonb((${t}.value #>> '{}')::numeric + $2::numeric) END,
+             expires_at = CASE WHEN ${expired} THEN EXCLUDED.expires_at ELSE ${t}.expires_at END,
+             stale_at = CASE WHEN ${expired} THEN NULL ELSE ${t}.stale_at END
+         WHERE (${expired}) OR jsonb_typeof(${t}.value) = 'number'
+       RETURNING value`, [
+			parsedKey,
+			value,
+			this.ttlToSeconds(this.ttl)
+		]);
+		if (rows.length === 0) throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		const newValue = Number(this.decodeJson(rows[0].value));
+		await this.emit("set", {
+			key: parsedKey,
+			value: newValue,
+			ttl: this.ttl
+		});
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* One atomic `DELETE … RETURNING`, so a value is handed out exactly once
+	* across servers. Expired rows count as missing.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const { rows } = await this.pgClient.query(`/* cache:pull */ DELETE FROM ${this.table}
+       WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())
+       RETURNING value`, [parsedKey]);
+		if (rows.length === 0) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		const value = this.decodeJson(rows[0].value);
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Atomic across servers via optimistic compare-and-set: read the live value,
+	* run `fn`, then write with `UPDATE … WHERE value = <what was read>` (or a
+	* create-only insert for a missing key), retrying when another writer got
+	* there first. `fn` may run more than once under contention; after
+	* {@link PG_UPDATE_MAX_ATTEMPTS} lost races it throws {@link CacheError}.
+	*
+	* Without an explicit `ttl` the row keeps its `expires_at`; a new key gets
+	* the driver default TTL. Returning `null` deletes the key (compare-and-delete).
+	*/
+	async update(key, fn, options = {}) {
+		const parsedKey = this.parseKey(key);
+		const t = this.table;
+		const live = `(expires_at IS NULL OR expires_at > now())`;
+		const explicitTtl = options.ttl !== void 0 ? parseTtl(options.ttl) : void 0;
+		for (let attempt = 0; attempt < PG_UPDATE_MAX_ATTEMPTS; attempt++) {
+			const read = await this.pgClient.query(`SELECT value FROM ${t}
+         WHERE key = $1 AND ${live}`, [parsedKey]);
+			const exists = read.rows.length > 0;
+			const current = exists ? this.decodeJson(read.rows[0].value) : null;
+			const expected = exists ? JSON.stringify(current) : null;
+			const result = await fn(current);
+			if (result === null) {
+				if (!exists) return null;
+				if ((await this.pgClient.query(`/* cache:cas-delete */ DELETE FROM ${t}
+           WHERE key = $1 AND value = $2::jsonb AND ${live}
+           RETURNING 1`, [parsedKey, expected])).rows.length > 0) {
+					await this.emit("removed", { key: parsedKey });
+					return null;
+				}
+				continue;
+			}
+			if (!exists) {
+				if ((await this.set(key, result, {
+					onConflict: "create",
+					...explicitTtl !== void 0 ? { ttl: explicitTtl } : {}
+				})).wasSet) return result;
+				continue;
+			}
+			const params = [
+				parsedKey,
+				JSON.stringify(result),
+				expected
+			];
+			let expirySql = "";
+			if (explicitTtl !== void 0) {
+				params.push(this.ttlToSeconds(explicitTtl));
+				expirySql = `, expires_at = now() + make_interval(secs => $4::double precision)`;
+			}
+			if ((await this.pgClient.query(`/* cache:cas-update */ UPDATE ${t}
+         SET value = $2::jsonb, stale_at = NULL${expirySql}
+         WHERE key = $1 AND value = $3::jsonb AND ${live}
+         RETURNING 1`, params)).rows.length > 0) {
+				await this.emit("set", {
+					key: parsedKey,
+					value: result,
+					ttl: explicitTtl
+				});
+				return result;
+			}
+		}
+		throw new CacheError(`cache.update(): '${parsedKey}' changed on every attempt (${PG_UPDATE_MAX_ATTEMPTS} tries) — too much write contention.`);
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async remove(key) {
@@ -3900,6 +4769,42 @@ async function loadRedis() {
 	}
 }
 loadRedis();
+/** KEYS[1]=key, ARGV[1]=expected raw value. 1 when deleted, 0 when not the owner. */
+const REDIS_COMPARE_DELETE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) return 1 else return 0 end`;
+/**
+* Compare-and-set used by `update()`.
+*
+* KEYS[1]=key; ARGV[1]=expected raw value (ignored when ARGV[3]=='1');
+* ARGV[2]=new raw value; ARGV[3]='1' when the key is expected to be missing;
+* ARGV[4]=ttl seconds to apply ('0' = no expiry); ARGV[5]='keep' to keep the
+* existing TTL instead (only when the key existed).
+*
+* Returns 1 when written, 0 when the current value no longer matches.
+* `KEEPTTL` requires Redis >= 6.
+*/
+const REDIS_CAS_SET_SCRIPT = `local cur = redis.call('GET', KEYS[1])
+if ARGV[3] == '1' then
+  if cur then return 0 end
+elseif cur ~= ARGV[1] then
+  return 0
+end
+local ttl = tonumber(ARGV[4])
+if ARGV[5] == 'keep' and ARGV[3] ~= '1' then
+  redis.call('SET', KEYS[1], ARGV[2], 'KEEPTTL')
+elseif ttl > 0 then
+  redis.call('SET', KEYS[1], ARGV[2], 'EX', ttl)
+else
+  redis.call('SET', KEYS[1], ARGV[2])
+end
+return 1`;
+/** KEYS[1]=key. Fallback for clients without `getDel`: returns the value and deletes it. */
+const REDIS_GET_DEL_SCRIPT = `local v = redis.call('GET', KEYS[1])
+if v then redis.call('DEL', KEYS[1]) end
+return v`;
+/** Compare-and-set attempts before `update()` gives up under contention. */
+const UPDATE_MAX_ATTEMPTS = 10;
+/** Keys deleted per UNLINK/DEL while draining a namespace. */
+const REMOVE_BATCH_SIZE = 500;
 var RedisCacheDriver = class extends BaseCacheDriver {
 	constructor(..._args) {
 		super(..._args);
@@ -3918,19 +4823,110 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 	async removeNamespace(namespace) {
 		namespace = this.parseKey(namespace);
 		this.log("clearing", namespace);
-		const pattern = namespace.replace(/[\\*?[\]]/g, "\\$&");
-		const keys = [];
-		if (this.client) for await (const key of this.client.scanIterator({
-			MATCH: `${pattern}*`,
-			COUNT: 100
-		})) keys.push(key);
-		if (keys.length === 0) {
+		const escaped = namespace.replace(/[\\*?[\]]/g, "\\$&");
+		const pattern = escaped === "" ? "*" : `${escaped}.*`;
+		const deleted = [];
+		if (this.client) {
+			if (escaped !== "") {
+				if (await this.deleteKeys([namespace]) > 0) deleted.push(namespace);
+			}
+			let batch = [];
+			for await (const scanned of this.client.scanIterator({
+				MATCH: pattern,
+				COUNT: 100
+			})) {
+				const keys = Array.isArray(scanned) ? scanned : [scanned];
+				for (const key of keys) {
+					batch.push(key);
+					if (batch.length >= REMOVE_BATCH_SIZE) {
+						await this.deleteKeys(batch);
+						deleted.push(...batch);
+						batch = [];
+					}
+				}
+			}
+			if (batch.length > 0) {
+				await this.deleteKeys(batch);
+				deleted.push(...batch);
+			}
+		}
+		if (deleted.length === 0) {
 			this.log("notFound", namespace);
 			return;
 		}
-		await this.client?.del(keys);
 		this.log("cleared", namespace);
-		return keys;
+		return deleted;
+	}
+	/**
+	* Delete keys with `UNLINK` (non-blocking free), falling back to `DEL` when
+	* the client lacks it. Returns the number of keys removed.
+	*/
+	async deleteKeys(keys) {
+		const client = this.client;
+		if (typeof client.unlink === "function") return Number(await client.unlink(keys)) || 0;
+		return Number(await client.del(keys)) || 0;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* `SADD` — atomic across servers, so concurrent tagged writes on any number
+	* of instances never drop a member. The set key lives inside the prefix
+	* namespace, so `flush()` / `removeNamespace()` sweep it too.
+	*/
+	async tagAdd(tagKey, members) {
+		if (members.length === 0) return;
+		const parsedKey = this.parseKey(tagKey);
+		await this.withTagSet(parsedKey, (client) => client.sAdd(parsedKey, members));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagMembers(tagKey) {
+		const parsedKey = this.parseKey(tagKey);
+		return this.withTagSet(parsedKey, async (client) => await client.sMembers(parsedKey) ?? []);
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* `SREM` — Redis drops the set once its last member is removed.
+	*/
+	async tagRemove(tagKey, members) {
+		if (members.length === 0) return;
+		const parsedKey = this.parseKey(tagKey);
+		await this.withTagSet(parsedKey, (client) => client.sRem(parsedKey, members));
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async tagDelete(tagKey) {
+		await this.client?.del(this.parseKey(tagKey));
+	}
+	/**
+	* Run a SET command against a tag key, upgrading a pre-5.20 index first.
+	*
+	* Earlier versions stored the index as a JSON-array STRING under the same
+	* key, which makes any SET command fail with `WRONGTYPE`. On that error the
+	* legacy array is read, the string deleted, its members re-added with
+	* `SADD`, and the command retried once.
+	*/
+	async withTagSet(parsedKey, run) {
+		const client = this.client;
+		try {
+			return await run(client);
+		} catch (error) {
+			if (!/WRONGTYPE/i.test(String(error?.message ?? error))) throw error;
+			const raw = await client.get(parsedKey);
+			let legacy = [];
+			try {
+				legacy = raw === null ? [] : JSON.parse(raw);
+			} catch {
+				legacy = [];
+			}
+			await client.del(parsedKey);
+			const members = Array.isArray(legacy) ? legacy.filter((member) => typeof member === "string") : [];
+			if (members.length > 0) await client.sAdd(parsedKey, members);
+			return run(client);
+		}
 	}
 	/**
 	* {@inheritDoc}
@@ -3958,7 +4954,8 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 			existing: onConflict === "create" ? await this.get(key) : null
 		};
 		if (tags && tags.length > 0) await this.applyTags(key, tags);
-		if (staleAt !== void 0) {
+		if (staleAt === void 0) await this.client?.del(this.swrMetaKey(parsedKey));
+		else {
 			const sidecarOptions = {};
 			if (hasExpiry) sidecarOptions.EX = ttl;
 			await this.client?.set(this.swrMetaKey(parsedKey), String(staleAt), sidecarOptions);
@@ -3976,11 +4973,28 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 		return value;
 	}
 	/**
+	* {@inheritdoc}
+	*
+	* Values are stored as `JSON.stringify(value)`, so the compare runs against
+	* the serialized form inside Lua.
+	*/
+	async deleteIfEquals(key, expected) {
+		const parsedKey = this.parseKey(key);
+		const deleted = await this.client.eval(REDIS_COMPARE_DELETE_SCRIPT, {
+			keys: [parsedKey],
+			arguments: [JSON.stringify(expected)]
+		});
+		if (Number(deleted) !== 1) return false;
+		await this.client?.del(this.swrMetaKey(parsedKey));
+		await this.emit("removed", { key: parsedKey });
+		return true;
+	}
+	/**
 	* Build the sidecar key Redis uses to track SWR freshness without
 	* wrapping the main value JSON.
 	*/
 	swrMetaKey(parsedKey) {
-		return `__swrmeta:${parsedKey}`;
+		return `${parsedKey}::swrmeta`;
 	}
 	/**
 	* Read the raw {@link CacheData} wrapper, fetching the value and the
@@ -4060,17 +5074,22 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 	async remove(key) {
 		key = this.parseKey(key);
 		this.log("removing", key);
-		await this.client?.del([key, this.swrMetaKey(key)]);
+		await this.client?.del(key);
+		await this.client?.del(this.swrMetaKey(key));
 		this.log("removed", key);
 		await this.emit("removed", { key });
 	}
 	/**
 	* {@inheritDoc}
+	*
+	* WARNING: without a `globalPrefix` this runs `FLUSHDB`, which clears the
+	* WHOLE selected Redis database (including keys not written by this driver).
+	* Configure a `globalPrefix` to only delete this driver's keys.
 	*/
 	async flush() {
 		this.log("flushing");
 		if (this.options.globalPrefix) await this.removeNamespace("");
-		else await this.client?.flushAll();
+		else await this.client?.flushDb();
 		this.log("flushed");
 		await this.emit("flushed");
 	}
@@ -4104,6 +5123,8 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 		} catch (error) {
 			_warlock_js_logger.log.fatal("cache", "redis", "Failed to connect", safeErrorInfo(error));
 			await this.emit("error", { error });
+			this.clientDriver = void 0;
+			throw error;
 		}
 	}
 	/**
@@ -4122,6 +5143,89 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 		await this.emit("disconnected");
 	}
 	/**
+	* {@inheritdoc}
+	*
+	* Atomic across servers: `GETDEL` (Redis >= 6.2), or an equivalent Lua
+	* script when the client has no `getDel`. A value is handed out once.
+	*/
+	async pull(key) {
+		const parsedKey = this.parseKey(key);
+		const client = this.client;
+		const raw = typeof client.getDel === "function" ? await client.getDel(parsedKey) : await client.eval(REDIS_GET_DEL_SCRIPT, {
+			keys: [parsedKey],
+			arguments: []
+		});
+		if (raw === null || raw === void 0) {
+			await this.emit("miss", { key: parsedKey });
+			return null;
+		}
+		await this.client?.del(this.swrMetaKey(parsedKey));
+		const value = JSON.parse(raw);
+		await this.emit("hit", {
+			key: parsedKey,
+			value
+		});
+		await this.emit("removed", { key: parsedKey });
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*
+	* Atomic across servers via optimistic compare-and-set: read the raw value,
+	* run `fn`, then write only if the value is still what was read (Lua), and
+	* retry otherwise. `fn` may therefore run more than once under contention;
+	* after {@link UPDATE_MAX_ATTEMPTS} lost races it throws {@link CacheError}.
+	*
+	* Without an explicit `ttl` the existing expiry is kept (`KEEPTTL`); a new
+	* key gets the driver default TTL. Returning `null` deletes the key
+	* (compare-and-delete).
+	*/
+	async update(key, fn, options = {}) {
+		const parsedKey = this.parseKey(key);
+		const client = this.client;
+		const explicitTtl = options.ttl !== void 0 ? parseTtl(options.ttl) : void 0;
+		for (let attempt = 0; attempt < UPDATE_MAX_ATTEMPTS; attempt++) {
+			const raw = await client.get(parsedKey) ?? null;
+			const result = await fn(raw === null ? null : JSON.parse(raw));
+			if (result === null) {
+				if (raw === null) return null;
+				const deleted = await client.eval(REDIS_COMPARE_DELETE_SCRIPT, {
+					keys: [parsedKey],
+					arguments: [raw]
+				});
+				if (Number(deleted) === 1) {
+					await this.client?.del(this.swrMetaKey(parsedKey));
+					await this.emit("removed", { key: parsedKey });
+					return null;
+				}
+				continue;
+			}
+			const isNew = raw === null;
+			const ttlSeconds = explicitTtl ?? (isNew ? this.ttl : 0);
+			const keep = explicitTtl === void 0 && !isNew;
+			const written = await client.eval(REDIS_CAS_SET_SCRIPT, {
+				keys: [parsedKey],
+				arguments: [
+					raw ?? "",
+					JSON.stringify(result),
+					isNew ? "1" : "0",
+					String(Number.isFinite(ttlSeconds) && ttlSeconds > 0 ? ttlSeconds : 0),
+					keep ? "keep" : ""
+				]
+			});
+			if (Number(written) === 1) {
+				await this.client?.del(this.swrMetaKey(parsedKey));
+				await this.emit("set", {
+					key: parsedKey,
+					value: result,
+					ttl: ttlSeconds
+				});
+				return result;
+			}
+		}
+		throw new CacheError(`cache.update(): '${parsedKey}' changed on every attempt (${UPDATE_MAX_ATTEMPTS} tries) — too much write contention.`);
+	}
+	/**
 	* Atomic increment using Redis native INCRBY command
 	* {@inheritdoc}
 	*/
@@ -4129,6 +5233,7 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 		const parsedKey = this.parseKey(key);
 		this.log("caching", parsedKey);
 		const result = await this.client?.incrBy(parsedKey, value);
+		if (this.ttl !== Infinity && this.ttl > 0) await this.client?.expire(parsedKey, this.ttl, "NX");
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -4199,6 +5304,9 @@ exports.MemoryExtendedCacheDriver = MemoryExtendedCacheDriver;
 exports.MockCacheDriver = MockCacheDriver;
 exports.NullCacheDriver = NullCacheDriver;
 exports.PgCacheDriver = PgCacheDriver;
+exports.REDIS_CAS_SET_SCRIPT = REDIS_CAS_SET_SCRIPT;
+exports.REDIS_COMPARE_DELETE_SCRIPT = REDIS_COMPARE_DELETE_SCRIPT;
+exports.REDIS_GET_DEL_SCRIPT = REDIS_GET_DEL_SCRIPT;
 exports.RedisCacheDriver = RedisCacheDriver;
 exports.ScopedCache = ScopedCache;
 exports.TaggedCache = TaggedCache;