@warlock.js/cache 5.28.0 → 5.30.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@warlock.js/cache` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.30.0 - 2026-10-16
+
+### Changed
+
+- Email addresses inside logged cache keys are masked (`user.member@example.com` logs as `u***@example.com`), in the base driver's operation log, in error lines (written even with logging off: SWR refresh failures, lock release, clone failures), in the "Cannot increment non-numeric value" error, and in the null driver (FW-04).
+
+### Fixed
+
+- **`redis` driver `increment()` works on Redis 6.** With a default `ttl` configured it ran `EXPIRE … NX`, which only Redis 7+ accepts: on Redis 6 the call threw after the count had already gone up, which silently disabled login throttles and the cache-backed rate limiter. The increment and the default TTL are now applied together by one Lua script, and a TTL the counter already has is never shortened.
+- The default `increment()` (file and null drivers) reads a counter's value and deadline in one read. A counter that expired between two separate reads used to be rewritten from its stale value with no expiry at all, and every increment rounded the remaining TTL up, pushing the deadline up to a second later each time.
+- `file` driver: an entry stored without a TTL (its `expiresAt` is written to JSON as `null`) was read back by the internal entry reader as already expired, so `swr()` freshness checks and TTL-preserving writes treated it as missing.
+
+## 5.29.0 - 2026-10-01
+
+### Changed
+
+- Lockstep release; package APIs are unchanged. Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
+
 ## 5.28.0 - 2026-10-01
 
 ### Changed

package/cjs/index.cjs

@@ -37,7 +37,7 @@ let _warlock_js_fs = require("@warlock.js/fs");
 let path = require("path");
 path = __toESM(path, 1);
 
-//#region ../cache/src/metrics.ts
+//#region ../../packages/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
@@ -232,7 +232,7 @@ var CacheMetricsCollector = class {
 };
 
 //#endregion
-//#region ../cache/src/types.ts
+//#region ../../packages/cache/src/types.ts
 /**
 * Base error class for cache-related errors
 */
@@ -292,7 +292,7 @@ var CacheConcurrencyError = class extends CacheError {
 };
 
 //#endregion
-//#region ../cache/src/utils.ts
+//#region ../../packages/cache/src/utils.ts
 /**
 * Make a proper key for the cache
 */
@@ -549,7 +549,7 @@ let CACHE_FOR = /* @__PURE__ */ function(CACHE_FOR) {
 }({});
 
 //#endregion
-//#region ../cache/src/tagged-scoped-cache.ts
+//#region ../../packages/cache/src/tagged-scoped-cache.ts
 /**
 * One-shot tagged write handle on top of a {@link ScopedCache}.
 *
@@ -698,7 +698,7 @@ var TaggedScopedCache = class {
 };
 
 //#endregion
-//#region ../cache/src/scoped-cache.ts
+//#region ../../packages/cache/src/scoped-cache.ts
 /**
 * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.
 *
@@ -979,7 +979,7 @@ var ScopedCache = class ScopedCache {
 };
 
 //#endregion
-//#region ../cache/src/cache-manager.ts
+//#region ../../packages/cache/src/cache-manager.ts
 var CacheManager = class {
 	constructor() {
 		this.loadedDrivers = {};
@@ -1477,7 +1477,7 @@ var CacheManager = class {
 const cache = new CacheManager();
 
 //#endregion
-//#region ../cache/src/cached/auto-key.ts
+//#region ../../packages/cache/src/cached/auto-key.ts
 /**
 * Derive a cache key from a prefix and a set of function arguments.
 *
@@ -1543,7 +1543,7 @@ function normalize(value, prefix, seen) {
 }
 
 //#endregion
-//#region ../cache/src/cached/normalize-args.ts
+//#region ../../packages/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.
@@ -1565,7 +1565,7 @@ function normalizeCachedArgs(prefixOrOptions, maybeTtl) {
 }
 
 //#endregion
-//#region ../cache/src/cached/cached.ts
+//#region ../../packages/cache/src/cached/cached.ts
 function cached(fn, prefixOrOptions, maybeTtl) {
 	const config = normalizeCachedArgs(prefixOrOptions, maybeTtl);
 	const buildRememberOptions = () => ({
@@ -1589,7 +1589,7 @@ function cached(fn, prefixOrOptions, maybeTtl) {
 }
 
 //#endregion
-//#region ../cache/src/list/memory-cache-list.ts
+//#region ../../packages/cache/src/list/memory-cache-list.ts
 /**
 * Generic array-backed {@link CacheListAccessor}.
 *
@@ -1708,7 +1708,7 @@ var MemoryCacheList = class {
 };
 
 //#endregion
-//#region ../cache/src/tagged-cache.ts
+//#region ../../packages/cache/src/tagged-cache.ts
 /**
 * Tagged Cache Wrapper
 * Wraps a cache driver to automatically manage tag relationships
@@ -1916,7 +1916,7 @@ var TaggedCache = class TaggedCache {
 };
 
 //#endregion
-//#region ../cache/src/drivers/base-cache-driver.ts
+//#region ../../packages/cache/src/drivers/base-cache-driver.ts
 const messages = {
 	clearing: "Clearing namespace",
 	cleared: "Namespace cleared",
@@ -2309,20 +2309,30 @@ 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).
+	* keeping the entry's deadline (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).
+	*
+	* The value and its deadline come from ONE read. Reading them separately
+	* let a counter that expired in between be rewritten from its stale value
+	* with no expiry at all (a login-throttle counter that then never resets).
+	* The remaining TTL is rounded down, so repeated increments can never push
+	* a window's deadline later.
 	*/
 	async increment(key, value = 1) {
 		const parsedKey = this.parseKey(key);
 		return this.runSerialized(parsedKey, async () => {
-			const current = await this.get(key);
+			const entry = await this.getEntry(key);
+			const now = Date.now();
+			const expiresAt = entry?.expiresAt;
+			const live = entry ? expiresAt == null || expiresAt > now : false;
+			const current = entry && live ? entry.data : null;
 			const base = current === null || current === void 0 ? 0 : current;
-			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+			if (typeof base !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(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);
+			if (!live) await this.set(key, newValue);
+			else if (expiresAt == null || expiresAt === Infinity) await this.set(key, newValue, { ttl: Infinity });
+			else await this.set(key, newValue, { ttl: Math.max(1, Math.floor((expiresAt - now) / 1e3)) });
 			return newValue;
 		});
 	}
@@ -2349,7 +2359,7 @@ var BaseCacheDriver = class {
 	*/
 	log(operation, key) {
 		if (!this.shouldLog) return;
-		if (typeof key === "string") key = key.replace(/\//g, ".");
+		if (typeof key === "string") key = (0, _warlock_js_logger.maskEmailsInText)(key.replace(/\//g, "."));
 		if (operation === "connectionFailed") _warlock_js_logger.log.fatal(`cache.${this.name}`, operation, key);
 		if (operation == "notFound" || operation == "expired") return _warlock_js_logger.log.info("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]);
@@ -2364,8 +2374,14 @@ var BaseCacheDriver = class {
 	* passed to the structured logger.
 	*/
 	logError(message, error) {
-		if (error) _warlock_js_logger.log.error("cache." + this.name, "error", message, safeErrorInfo(error));
-		else _warlock_js_logger.log.error("cache." + this.name, "error", message);
+		const maskedMessage = (0, _warlock_js_logger.maskEmailsInText)(message);
+		if (error) {
+			const info = safeErrorInfo(error);
+			_warlock_js_logger.log.error("cache." + this.name, "error", maskedMessage, {
+				...info,
+				message: (0, _warlock_js_logger.maskEmailsInText)(info.message)
+			});
+		} else _warlock_js_logger.log.error("cache." + this.name, "error", maskedMessage);
 	}
 	/**
 	* Get the default TTL in seconds. Parses human-readable strings (`"1h"`, `"30m"`)
@@ -2560,7 +2576,7 @@ var BaseCacheDriver = class {
 };
 
 //#endregion
-//#region ../cache/src/drivers/file-cache-driver.ts
+//#region ../../packages/cache/src/drivers/file-cache-driver.ts
 var FileCacheDriver = class extends BaseCacheDriver {
 	constructor(..._args) {
 		super(..._args);
@@ -2770,7 +2786,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 		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;
+			if (typeof entry.expiresAt === "number" && entry.expiresAt <= Date.now()) return null;
 			return entry;
 		} catch {
 			return null;
@@ -2837,7 +2853,7 @@ var FileCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/in-memory-tag-index.ts
+//#region ../../packages/cache/src/drivers/in-memory-tag-index.ts
 /**
 * Tag index for the in-process drivers (memory, memoryExtended, lru, mock).
 *
@@ -2908,7 +2924,7 @@ var InMemoryTagIndex = class {
 };
 
 //#endregion
-//#region ../cache/src/drivers/lru-memory-cache-driver.ts
+//#region ../../packages/cache/src/drivers/lru-memory-cache-driver.ts
 var CacheNode = class {
 	constructor(key, value, ttl) {
 		this.key = key;
@@ -3120,7 +3136,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 		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}`);
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = current + value;
 		if (node) {
 			node.value = newValue;
@@ -3315,7 +3331,7 @@ var LRUMemoryCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/memory-cache-driver.ts
+//#region ../../packages/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.
@@ -3491,7 +3507,7 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 		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}`);
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = current + value;
 		if (entry) {
 			entry.data = newValue;
@@ -3674,7 +3690,7 @@ var MemoryCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/memory-extended-cache-driver.ts
+//#region ../../packages/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
@@ -3691,7 +3707,7 @@ var MemoryExtendedCacheDriver = class extends MemoryCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/mock-cache-driver.ts
+//#region ../../packages/cache/src/drivers/mock-cache-driver.ts
 /**
 * In-memory cache driver with introspection helpers, intended for use as a
 * test double in downstream packages.
@@ -3862,7 +3878,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 		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}`);
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = current + value;
 		if (entry) entry.data = newValue;
 		else this.storage.set(parsedKey, this.prepareDataForStorage(newValue, this.ttl));
@@ -4009,7 +4025,7 @@ var MockCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/null-cache-driver.ts
+//#region ../../packages/cache/src/drivers/null-cache-driver.ts
 var NullCacheDriver = class extends BaseCacheDriver {
 	/**
 	* {@inheritdoc}
@@ -4052,32 +4068,39 @@ var NullCacheDriver = class extends BaseCacheDriver {
 	* {@inheritdoc}
 	*/
 	async removeNamespace(namespace) {
-		_warlock_js_logger.log.info("cache", "clearing namespace", namespace);
-		_warlock_js_logger.log.success("cache", "namespace cleared", namespace);
+		const loggableNamespace = (0, _warlock_js_logger.maskEmailsInText)(namespace);
+		_warlock_js_logger.log.info("cache", "clearing namespace", loggableNamespace);
+		_warlock_js_logger.log.success("cache", "namespace cleared", loggableNamespace);
 		return this;
 	}
 	/**
+	* The key as it may appear in a log line: parsed, with email addresses masked
+	*/
+	loggableKey(key) {
+		return (0, _warlock_js_logger.maskEmailsInText)(this.parseKey(key));
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async set(key, _value, _ttlOrOptions) {
-		_warlock_js_logger.log.info("cache", "setting key", key);
-		_warlock_js_logger.log.success("cache", "key set", key);
+		_warlock_js_logger.log.info("cache", "setting key", this.loggableKey(key));
+		_warlock_js_logger.log.success("cache", "key set", this.loggableKey(key));
 		return this;
 	}
 	/**
 	* {@inheritdoc}
 	*/
 	async get(key) {
-		_warlock_js_logger.log.info("cache", "fetching", key);
-		_warlock_js_logger.log.success("cache", "fetched", key);
+		_warlock_js_logger.log.info("cache", "fetching", this.loggableKey(key));
+		_warlock_js_logger.log.success("cache", "fetched", this.loggableKey(key));
 		return null;
 	}
 	/**
 	* {@inheritdoc}
 	*/
 	async remove(key) {
-		_warlock_js_logger.log.info("cache", "removing", key);
-		_warlock_js_logger.log.success("cache", "removed", key);
+		_warlock_js_logger.log.info("cache", "removing", this.loggableKey(key));
+		_warlock_js_logger.log.success("cache", "removed", this.loggableKey(key));
 	}
 	/**
 	* {@inheritdoc}
@@ -4104,7 +4127,7 @@ var NullCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/pg-cache-driver.ts
+//#region ../../packages/cache/src/drivers/pg-cache-driver.ts
 /** Compare-and-set attempts before `update()` gives up under contention. */
 const PG_UPDATE_MAX_ATTEMPTS = 10;
 /**
@@ -4556,7 +4579,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 			value,
 			this.ttlToSeconds(this.ttl)
 		]);
-		if (rows.length === 0) throw new Error(`Cannot increment non-numeric value for key: ${parsedKey}`);
+		if (rows.length === 0) throw new Error(`Cannot increment non-numeric value for key: ${(0, _warlock_js_logger.maskEmailsInText)(parsedKey)}`);
 		const newValue = Number(this.decodeJson(rows[0].value));
 		await this.emit("set", {
 			key: parsedKey,
@@ -4757,7 +4780,7 @@ var PgCacheDriver = class extends BaseCacheDriver {
 };
 
 //#endregion
-//#region ../cache/src/drivers/redis-cache-driver.ts
+//#region ../../packages/cache/src/drivers/redis-cache-driver.ts
 /**
 * Cached Redis module (loaded once, reused)
 */
@@ -4821,6 +4844,23 @@ return 1`;
 const REDIS_GET_DEL_SCRIPT = `local v = redis.call('GET', KEYS[1])
 if v then redis.call('DEL', KEYS[1]) end
 return v`;
+/**
+* Increment that gives a counter without an expiry the driver's default TTL,
+* in one round trip.
+*
+* KEYS[1]=key; ARGV[1]=amount; ARGV[2]=ttl seconds ('0' = none).
+*
+* Replaces `INCRBY` + `EXPIRE … NX`: the `NX` flag needs Redis >= 7.0, and on
+* Redis 6 the second command failed after the count had already gone up.
+* `TTL == -1` means "exists without an expiry", so a TTL set earlier (by
+* `set(..., { ttl })`) is never shortened or reset.
+*/
+const REDIS_INCREMENT_SCRIPT = `local v = redis.call('INCRBY', KEYS[1], ARGV[1])
+local ttl = tonumber(ARGV[2])
+if ttl > 0 and redis.call('TTL', KEYS[1]) == -1 then
+  redis.call('EXPIRE', KEYS[1], ttl)
+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. */
@@ -5252,8 +5292,11 @@ var RedisCacheDriver = class extends BaseCacheDriver {
 	async increment(key, value = 1) {
 		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");
+		const defaultTtl = Number.isFinite(this.ttl) && this.ttl > 0 ? Math.ceil(this.ttl) : 0;
+		const result = defaultTtl > 0 ? Number(await this.client?.eval(REDIS_INCREMENT_SCRIPT, {
+			keys: [parsedKey],
+			arguments: [String(value), String(defaultTtl)]
+		})) : await this.client?.incrBy(parsedKey, value);
 		this.log("cached", parsedKey);
 		await this.emit("set", {
 			key: parsedKey,
@@ -5327,6 +5370,7 @@ 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.REDIS_INCREMENT_SCRIPT = REDIS_INCREMENT_SCRIPT;
 exports.RedisCacheDriver = RedisCacheDriver;
 exports.ScopedCache = ScopedCache;
 exports.TaggedCache = TaggedCache;