@warlock.js/cache 5.19.1 → 5.21.0

package/llms-full.txt

@@ -6,103 +6,104 @@
 
 ## apply-cache-patterns  `@warlock.js/cache/apply-cache-patterns/SKILL.md`
 
----
-name: apply-cache-patterns
-description: "Real-world caching patterns in @warlock.js/cache; use when you need to apply cache patterns."
----
-
-# Real-world caching patterns
-
-Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
-
-## Memoize an expensive function — `remember`
-
-```ts
-const user = await cache.remember(`user:${id}`, "1h", async () => {
-  return db.users.find(id);   // runs only on cache miss
-});
-```
-
-- The callback runs once per miss.
-- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
-- `null` is the universal miss sentinel. `remember` short-circuits on a **truthy** cached value (`if (cachedValue) return cachedValue;`), so a stored `null` reads back as a miss and the callback **re-runs on every call** — you get no caching at all, plus a wasted write each time. To actually cache a "not found," store a truthy sentinel instead (see negative caching below).
-
-## Cross-process stampede protection — distributed lock via `onConflict`
-
-`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
-
-```ts
-const lockKey = `lock:build-report:${reportId}`;
-const acquired = await cache.set(lockKey, process.pid, {
-  onConflict: "create",
-  ttl: "2m",
-});
-
-if (!acquired.wasSet) {
-  // another node is already building — wait or skip
-  return cache.get(`report:${reportId}`);
-}
-
-try {
-  const report = await buildExpensiveReport(reportId);
-  await cache.set(`report:${reportId}`, report, "1h");
-  return report;
-} finally {
-  await cache.remove(lockKey);
-}
-```
-
-This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
-
-## Negative caching
-
-Cache "not found" results with a shorter TTL to avoid hammering the origin:
-
-```ts
-const user = await cache.remember(`user:${id}`, "5m", async () => {
-  const found = await db.users.find(id);
-  return found ?? { __miss: true };
-});
-
-if (user?.__miss) {
-  return null;
-}
-```
-
-Don't return raw `null` inside `remember` to "cache the miss" — it won't. `remember`'s truthy guard treats a stored `null` as a miss, so the callback re-runs every time and the origin still gets hammered. The truthy `{ __miss: true }` sentinel is what actually skips the next call.
-
-## Per-tenant caching
-
-```ts
-// In cache config:
-options: {
-  redis: {
-    url: "...",
-    globalPrefix: () => `tenant-${currentContext.tenantId}`,
-  },
-}
-
-// At the call site — no tenancy awareness needed:
-await cache.set("user:1", user, "1h");
-// Actual key: "tenant-42.user.1"
-```
-
-Clear a tenant out:
-```ts
-await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
-// or
-await cache.tags([`tenant-${tenantId}`]).invalidate();
-```
-
-## See also
-
-- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
-- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
-- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
-- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
-- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
-- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
-- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization
+---
+name: apply-cache-patterns
+description: 'Compose cache primitives into real-world patterns — remember() memoization, cross-node stampede protection via a distributed lock (onConflict: ''create''), negative caching, and per-tenant scoping. Triggers: `cache.remember`, `cache.set` with `onConflict: "create"`, `globalPrefix`; "memoize this function", "prevent cache stampede across nodes", "cache not-found results", "per-tenant cache scoping"; typical import `import { cache } from "@warlock.js/cache"`. Skip: counters — `@warlock.js/cache/use-cache-atomic/SKILL.md`; bulk get/set — `@warlock.js/cache/use-cache-bulk/SKILL.md`; TTL constants/utilities — `@warlock.js/cache/use-cache-utils/SKILL.md`; named lock wrapper — `@warlock.js/cache/use-cache-lock/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`.'
+---
+
+# Real-world caching patterns
+
+Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
+
+## Memoize an expensive function — `remember`
+
+```ts
+const user = await cache.remember(`user:${id}`, "1h", async () => {
+  return db.users.find(id);   // runs only on cache miss
+});
+```
+
+- The callback runs once per miss.
+- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
+- `null` is the only miss. `0`, `false` and `""` are cached like any other value, so `remember` doesn't recompute them. A callback returning `null` is not cached, so the callback re-runs on the next call: to cache a "not found," store a sentinel (see negative caching below).
+- Stampede protection is per process, even on redis. To run something once across servers, wrap it in `cache.lock()` on `redis` or `pg`.
+
+## Cross-process stampede protection — distributed lock via `onConflict`
+
+`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
+
+```ts
+const lockKey = `lock:build-report:${reportId}`;
+const acquired = await cache.set(lockKey, process.pid, {
+  onConflict: "create",
+  ttl: "2m",
+});
+
+if (!acquired.wasSet) {
+  // another node is already building — wait or skip
+  return cache.get(`report:${reportId}`);
+}
+
+try {
+  const report = await buildExpensiveReport(reportId);
+  await cache.set(`report:${reportId}`, report, "1h");
+  return report;
+} finally {
+  await cache.remove(lockKey);
+}
+```
+
+This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
+
+## Negative caching
+
+Cache "not found" results with a shorter TTL to avoid hammering the origin:
+
+```ts
+const user = await cache.remember(`user:${id}`, "5m", async () => {
+  const found = await db.users.find(id);
+  return found ?? { __miss: true };
+});
+
+if (user?.__miss) {
+  return null;
+}
+```
+
+Don't return raw `null` inside `remember` to "cache the miss": `null` is the miss sentinel, so the callback re-runs every time and the origin still gets hammered. The `{ __miss: true }` sentinel is what skips the next call.
+
+## Per-tenant caching
+
+```ts
+// In cache config:
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+
+// At the call site — no tenancy awareness needed:
+await cache.set("user:1", user, "1h");
+// Actual key: "tenant-42.user.1"
+```
+
+Clear a tenant out:
+```ts
+await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
+// or
+await cache.tags([`tenant-${tenantId}`]).invalidate();
+```
+
+## See also
+
+- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
+- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
+- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
+- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
+- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
+- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
+- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization
 
 
 ## cache-basics  `@warlock.js/cache/cache-basics/SKILL.md`
@@ -236,7 +237,7 @@ const user = await cache.remember("user.1", "1h", async () => db.users.find(1));
 
 ---
 name: configure-pg-cache
-description: "pg cache driver — Postgres setup in @warlock.js/cache; use when you need to configure pg cache."
+description: 'Postgres cache driver setup — KV-only mode (default) or pgvector mode (opt in via options.pg.vector). Caller owns the pg.Pool, driver exposes driver.schema() for one-time DDL. Triggers: `PgCacheDriver`, `driver.schema`, `options.pg.vector`, `pg.Pool`, `hnsw`, `ivfflat`; "use Postgres as cache backend", "set up pgvector semantic cache", "DDL for warlock cache table"; typical import `import { cache, PgCacheDriver } from "@warlock.js/cache"`. Skip: cross-driver similarity API — `@warlock.js/cache/use-cache-similarity/SKILL.md`; driver picker — `@warlock.js/cache/pick-cache-driver/SKILL.md`; competing libs `pg-mem`; raw `pg` / `node-postgres`.'
 ---
 
 # `pg` cache driver — Postgres setup
@@ -249,14 +250,15 @@ Persistent cache backed by your existing Postgres pool. Two modes: **KV-only** (
 2. **`pg` is an optional peer dep.** Lazy-loaded; install only if you use this driver.
 3. **No auto-migration.** Driver exposes `driver.schema()` returning a DDL string — caller runs it via their own migration tool.
 4. **Table name is regex-validated** (`[A-Za-z_][A-Za-z0-9_]*`) before DDL interpolation. No SQL injection via misconfiguration.
-5. **TTL is lazy on read.** `SELECT ... WHERE expires_at IS NULL OR expires_at > now()`. Expired rows aren't auto-deleted unless you GC them yourself.
+5. **TTL is lazy on read.** `SELECT ... WHERE expires_at IS NULL OR expires_at > now()`. Expiry is computed on the DB clock. `driver.prune(limit = 1000)` deletes expired rows in batches and returns the count; `set()` also runs it on about 1 in 200 writes. Call it from a scheduled job for unique-key workloads.
 6. **`onConflict` is race-safe at the SQL layer:**
    - `create` → `INSERT ... ON CONFLICT DO UPDATE WHERE expires_at < now() RETURNING value` (reclaims expired rows; blocks live ones).
    - `update` → `UPDATE ... WHERE expires_at IS NULL OR expires_at > now() RETURNING value`.
    - `upsert` → unconditional `INSERT ... ON CONFLICT DO UPDATE`.
-7. **`stale_at TIMESTAMPTZ` column** powers [stale-while-revalidate](@warlock.js/cache/use-swr/SKILL.md) — `cache.swr(...)` populates it on writes, plain `set()` leaves it null (always-fresh). Provision via `driver.schema()` like any other column.
-8. **pgvector requires `CREATE EXTENSION vector;` once on the database.** Lazy probe on first vector op throws `CacheConfigurationError` if missing; result is cached.
-9. **Vectors are passed as text literals** (`'[1,2,3]'::vector`). No binary protocol dependency — works against any pg client.
+7. **Atomic ops are cross-server:** `increment` is one upsert that keeps `expires_at`, `pull` is `DELETE … RETURNING`, `update` is a compare-and-set with bounded retries (callback may run more than once). Tags use a one-statement JSON-array merge.
+8. **`stale_at TIMESTAMPTZ` column** powers [stale-while-revalidate](@warlock.js/cache/use-swr/SKILL.md) — `cache.swr(...)` populates it on writes, plain `set()` leaves it null (always-fresh). Provision via `driver.schema()` like any other column.
+9. **pgvector requires `CREATE EXTENSION vector;` once on the database.** Lazy probe on first vector op throws `CacheConfigurationError` if missing; result is cached.
+10. **Vectors are passed as text literals** (`'[1,2,3]'::vector`). No binary protocol dependency — works against any pg client.
 
 ## Configuration
 
@@ -353,305 +355,311 @@ See [`@warlock.js/cache/handle-cache-errors/SKILL.md`](@warlock.js/cache/handle-
 
 ## configure-set-options  `@warlock.js/cache/configure-set-options/SKILL.md`
 
----
-name: configure-set-options
-description: "The set options object in @warlock.js/cache; use when you need to configure set options."
----
-
-# The `set` options object
-
-`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
-
-## The three shapes
-
-```ts
-// 1. Number — seconds
-await cache.set("name", "Jane", 600);
-
-// 2. String — human-readable duration, parsed via `ms`
-await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
-
-// 3. Options object
-await cache.set("user:1", user, {
-  ttl: "1h",
-  expiresAt: new Date("2026-12-31"),
-  tags: ["users"],
-  onConflict: "create",
-  driver: "redis",
-});
-```
-
-## Option keys
-
-| Key | Type | Notes |
-| --- | --- | --- |
-| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
-| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
-| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
-| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
-| `driver` | `string` | Per-call driver override by registered name. |
-| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
-
-## `onConflict` policies
-
-Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
-
-```ts
-// create — set only if key is missing
-const result = await cache.set("lock:jobs:import", workerId, {
-  onConflict: "create",
-  ttl: "5m",
-});
-// result: { wasSet: true, existing: null } on acquire
-//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
-
-if (!result.wasSet) {
-  // another worker is already running; abort.
-}
-
-// update — set only if key exists (don't resurrect expired sessions)
-await cache.set("session:abc", session, { onConflict: "update" });
-```
-
-Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
-
-## Mutually-exclusive validations
-
-Both of these throw `CacheConfigurationError`:
-
-```ts
-await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
-await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
-```
-
-## Inline tags vs `cache.tags([...]).set(...)`
-
-Both work; inline is terser when you're writing one value under known tags:
-
-```ts
-// Inline
-await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
-
-// Fluent (useful when you already have a tagged instance)
-const users = cache.tags(["users"]);
-await users.set("user:1", user);
-await users.invalidate();   // drops every key tagged "users"
-```
-
-Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
-
-## Back-compat note
-
-Every call site using the old positional-TTL shape keeps working:
-
-```ts
-await cache.set("k", v);           // no TTL — driver default
-await cache.set("k", v, 3600);     // seconds
-await cache.set("k", v, undefined); // same as no TTL
-```
+---
+name: configure-set-options
+description: 'Configure cache.set''s third argument — ttl, expiresAt, tags, onConflict (create / update / upsert), driver, vector. Triggers: `cache.set`, `ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`, `CacheSetResult`, `wasSet`; "set a key only if missing", "set with absolute deadline", "attach tags inline", "route one cache call to redis"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag fluent API — `@warlock.js/cache/use-cache-tags/SKILL.md`; vector queries — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `keyv`, `ioredis`.'
+---
+
+# The `set` options object
+
+`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
+
+## The three shapes
+
+```ts
+// 1. Number — seconds
+await cache.set("name", "Jane", 600);
+
+// 2. String — human-readable duration, parsed via `ms`
+await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
+
+// 3. Options object
+await cache.set("user:1", user, {
+  ttl: "1h",
+  expiresAt: new Date("2026-12-31"),
+  tags: ["users"],
+  onConflict: "create",
+  driver: "redis",
+});
+```
+
+## Option keys
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
+| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
+| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
+| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
+| `driver` | `string` | Per-call driver override by registered name. |
+| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
+
+## TTL parsing
+
+- Number or bare numeric string (`"3600"`) = **seconds**. Fractions and sub-second values (`0.5`, `"500ms"`) round **up** to whole seconds, never 0.
+- `0` / `Infinity` = no expiry. `NaN`, negative and unparseable values throw `CacheConfigurationError`.
+- `cache.lock()` refuses any TTL that never expires.
+
+## `onConflict` policies
+
+Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
+
+```ts
+// create — set only if key is missing
+const result = await cache.set("lock:jobs:import", workerId, {
+  onConflict: "create",
+  ttl: "5m",
+});
+// result: { wasSet: true, existing: null } on acquire
+//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
+
+if (!result.wasSet) {
+  // another worker is already running; abort.
+}
+
+// update — set only if key exists (don't resurrect expired sessions)
+await cache.set("session:abc", session, { onConflict: "update" });
+```
+
+Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
+
+## Mutually-exclusive validations
+
+Both of these throw `CacheConfigurationError`:
+
+```ts
+await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
+await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
+```
+
+## Inline tags vs `cache.tags([...]).set(...)`
+
+Both work; inline is terser when you're writing one value under known tags:
+
+```ts
+// Inline
+await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
+
+// Fluent (useful when you already have a tagged instance)
+const users = cache.tags(["users"]);
+await users.set("user:1", user);
+await users.invalidate();   // drops every key tagged "users"
+```
+
+Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
+
+## Back-compat note
+
+Every call site using the old positional-TTL shape keeps working:
+
+```ts
+await cache.set("k", v);           // no TTL — driver default
+await cache.set("k", v, 3600);     // seconds
+await cache.set("k", v, undefined); // same as no TTL
+```
 
 
 ## handle-cache-errors  `@warlock.js/cache/handle-cache-errors/SKILL.md`
 
----
-name: handle-cache-errors
-description: "Error classes in @warlock.js/cache; use when you need to handle cache errors."
----
-
-# Error classes
-
-All cache errors extend `CacheError` which extends `Error`. Use `instanceof` to react selectively.
-
-```ts
-import {
-  CacheError,
-  CacheConfigurationError,
-  CacheConnectionError,
-  CacheDriverNotInitializedError,
-  CacheUnsupportedError,
-  CacheConcurrencyError,
-} from "@warlock.js/cache";
-```
-
-| Class | When it's thrown | How to react |
-| --- | --- | --- |
-| `CacheError` | Abstract base — don't throw directly, match against it to catch any cache error | `catch (e) { if (e instanceof CacheError) … }` |
-| `CacheConfigurationError` | Bad TTL string, `ttl` + `expiresAt` together, `expiresAt` in the past, missing required driver option (e.g. redis without url/host, file without directory), attempting to use an unregistered driver name | Fix the config / call site. Never catch at runtime — this is a programmer error, not a user-facing one. |
-| `CacheConnectionError` | Declared for driver connection failures. Not thrown by any built-in driver today (Redis currently logs the error and emits an `"error"` event instead of throwing on failed connect). | Reserved for future use. |
-| `CacheDriverNotInitializedError` | Any data op called before `cache.init()` / `cache.use()` | Call `cache.init()` at app startup. Tests often forget this — add a `beforeEach`. |
-| `CacheUnsupportedError` | Driver doesn't implement the requested op. Today: `update` / `merge` on the file driver; `set({ vector })` and `similar()` on file / redis / pg-without-`vector`-config. | Switch driver (memory family for dev similarity, `pg` with `vector` config for production), or queue the op. |
-| `CacheConcurrencyError` | Declared for future optimistic-concurrency exhaustion on Redis `update()` | Not thrown today. Reserved for the v2.1 `WATCH`/`MULTI` implementation. |
-| `CacheError` (file driver, path containment) | A key/namespace, after percent-encoding, still resolves outside the cache root — `"Cache key resolves outside the cache directory: ..."`. Last line of defense against path traversal on top of the encoding step; should not happen in normal use. | Treat as a programmer/attacker-input error — don't retry; investigate the key source. See [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the encoding contract. |
-
-## Special case — `setNX` unsupported
-
-Calling `cache.setNX(...)` on a driver that doesn't implement it throws a plain `Error`, not a `CacheUnsupportedError`:
-
-```ts
-// Error: "setNX is not supported by the current cache driver: memory"
-```
-
-This is legacy. The v2-preferred way is `cache.set(k, v, { onConflict: "create" })` which works on every driver (Redis native, others emulated). See [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md).
-
-## Patterns
-
-### Catch-all at the boundary
-
-```ts
-try {
-  await doCachedWork();
-} catch (error) {
-  if (error instanceof CacheError) {
-    logger.warn("cache unavailable, degrading", error);
-    await doWorkWithoutCache();
-    return;
-  }
-  throw error;
-}
-```
-
-### Selective — configuration vs runtime
-
-```ts
-try {
-  await cache.set("k", v, userSuppliedOptions);
-} catch (error) {
-  if (error instanceof CacheConfigurationError) {
-    return res.status(400).json({ error: "invalid TTL options" });
-  }
-  throw error;
-}
-```
-
-### Driver-missing fallback
-
-```ts
-try {
-  await cache.merge("user:1", { lastSeen: Date.now() });
-} catch (error) {
-  if (error instanceof CacheUnsupportedError) {
-    // File driver in dev — degrade gracefully
-    const current = await cache.get("user:1");
-    await cache.set("user:1", { ...current, lastSeen: Date.now() });
-    return;
-  }
-  throw error;
-}
-```
-
-## Things the driver does NOT throw
-
-- **Missing keys** — `get()` returns `null`, never throws. Tests checking "key not in cache" should assert `resolves.toBeNull()`, not `rejects.toThrow`.
-- **Expired entries** — `get()` returns `null` and emits `"miss"` + `"expired"` events. No throw.
-- **Flush on empty** — `flush()` succeeds silently when there's nothing to flush.
-- **Concurrent writes clobbering each other** — last-write-wins by default. Use `update()` or `onConflict: "create"` if you need protection.
+---
+name: handle-cache-errors
+description: 'Cache error classes — CacheError base, CacheConfigurationError, CacheConnectionError, CacheDriverNotInitializedError, CacheUnsupportedError, CacheConcurrencyError. Triggers: `CacheError`, `CacheConfigurationError`, `CacheConnectionError`, `CacheDriverNotInitializedError`, `CacheUnsupportedError`, `CacheConcurrencyError`; "catch cache errors at the boundary", "degrade when update or merge throws", "what does CacheUnsupportedError mean", "fall back when redis is down"; typical import `import { CacheError, CacheConfigurationError, CacheUnsupportedError } from "@warlock.js/cache"`. Skip: choosing a supported driver — `@warlock.js/cache/pick-cache-driver/SKILL.md`; observing errors via events — `@warlock.js/cache/observe-cache/SKILL.md`; competing libs ignore — generic `Error` patterns.'
+---
+
+# Error classes
+
+All cache errors extend `CacheError` which extends `Error`. Use `instanceof` to react selectively.
+
+```ts
+import {
+  CacheError,
+  CacheConfigurationError,
+  CacheConnectionError,
+  CacheDriverNotInitializedError,
+  CacheUnsupportedError,
+  CacheConcurrencyError,
+} from "@warlock.js/cache";
+```
+
+| Class | When it's thrown | How to react |
+| --- | --- | --- |
+| `CacheError` | Abstract base — don't throw directly, match against it to catch any cache error | `catch (e) { if (e instanceof CacheError) … }` |
+| `CacheConfigurationError` | Bad TTL string, `ttl` + `expiresAt` together, `expiresAt` in the past, missing required driver option (e.g. redis without url/host, file without directory), attempting to use an unregistered driver name | Fix the config / call site. Never catch at runtime — this is a programmer error, not a user-facing one. |
+| `CacheConnectionError` | Declared for driver connection failures. Not thrown by any built-in driver today (Redis currently logs the error and emits an `"error"` event instead of throwing on failed connect). | Reserved for future use. |
+| `CacheDriverNotInitializedError` | Any data op called before `cache.init()` / `cache.use()` | Call `cache.init()` at app startup. Tests often forget this — add a `beforeEach`. |
+| `CacheUnsupportedError` | Driver doesn't implement the requested op. Today: `update` / `merge` on the file driver; `set({ vector })` and `similar()` on file / redis / pg-without-`vector`-config. | Switch driver (memory family for dev similarity, `pg` with `vector` config for production), or queue the op. |
+| `CacheConcurrencyError` | Declared for future optimistic-concurrency exhaustion on Redis `update()` | Not thrown today. Reserved for the v2.1 `WATCH`/`MULTI` implementation. |
+| `CacheError` (file driver, path containment) | A key/namespace, after percent-encoding, still resolves outside the cache root — `"Cache key resolves outside the cache directory: ..."`. Last line of defense against path traversal on top of the encoding step; should not happen in normal use. | Treat as a programmer/attacker-input error — don't retry; investigate the key source. See [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the encoding contract. |
+
+## Special case — `setNX` unsupported
+
+Calling `cache.setNX(...)` on a driver that doesn't implement it throws a plain `Error`, not a `CacheUnsupportedError`:
+
+```ts
+// Error: "setNX is not supported by the current cache driver: memory"
+```
+
+This is legacy. The v2-preferred way is `cache.set(k, v, { onConflict: "create" })` which works on every driver (Redis native, others emulated). See [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md).
+
+## Patterns
+
+### Catch-all at the boundary
+
+```ts
+try {
+  await doCachedWork();
+} catch (error) {
+  if (error instanceof CacheError) {
+    logger.warn("cache unavailable, degrading", error);
+    await doWorkWithoutCache();
+    return;
+  }
+  throw error;
+}
+```
+
+### Selective — configuration vs runtime
+
+```ts
+try {
+  await cache.set("k", v, userSuppliedOptions);
+} catch (error) {
+  if (error instanceof CacheConfigurationError) {
+    return res.status(400).json({ error: "invalid TTL options" });
+  }
+  throw error;
+}
+```
+
+### Driver-missing fallback
+
+```ts
+try {
+  await cache.merge("user:1", { lastSeen: Date.now() });
+} catch (error) {
+  if (error instanceof CacheUnsupportedError) {
+    // File driver in dev — degrade gracefully
+    const current = await cache.get("user:1");
+    await cache.set("user:1", { ...current, lastSeen: Date.now() });
+    return;
+  }
+  throw error;
+}
+```
+
+## Things the driver does NOT throw
+
+- **Missing keys** — `get()` returns `null`, never throws. Tests checking "key not in cache" should assert `resolves.toBeNull()`, not `rejects.toThrow`.
+- **Expired entries** — `get()` returns `null` and emits `"miss"` + `"expired"` events. No throw.
+- **Flush on empty** — `flush()` succeeds silently when there's nothing to flush.
+- **Concurrent writes clobbering each other** — last-write-wins by default. Use `update()` or `onConflict: "create"` if you need protection.
 
 
 ## observe-cache  `@warlock.js/cache/observe-cache/SKILL.md`
 
----
-name: observe-cache
-description: "Cache observability — cache.metrics() and the event bus in @warlock.js/cache; use when you need to observe cache."
----
-
-# Cache observability — `cache.metrics()` and the event bus
-
-Two layers, different jobs.
-
-## Layer 1 — `cache.metrics()` for aggregate health
-
-Built-in collector subscribed to the manager's event bus. Returns a snapshot whenever you ask:
-
-```ts
-const m = cache.metrics();
-// {
-//   hits, misses, sets, removed, errors,
-//   hitRate,
-//   latencyMs: { p50, p95, p99, samples },
-//   byDriver: { memory: {...}, redis: {...} },
-//   startedAt,
-// }
-```
-
-**Lazy** — the collector attaches on the first `cache.metrics()` / `cache.resetMetrics()` call. Apps that never read metrics pay zero cost. Earlier events are not retroactively counted, so if you want metrics on every op including the first, call `cache.metrics()` once during startup right after `cache.init()`.
-
-**Survives `cache.use()` switches** — listens at the manager level, re-attaches to every loaded driver.
-
-**Latency** is sampled by the manager around `get` / `set` / `remove` into a circular buffer (default 1000 samples per driver). Percentiles are computed at snapshot time. Older samples age out, so percentiles reflect the recent ~1000 ops.
-
-`cache.resetMetrics()` zeroes counters + drops the buffer + bumps `startedAt`.
-
-## Layer 2 — Raw events for per-event reactions
-
-When you need to react to specific events (alerting, audit logs, debugging), subscribe to the event bus:
-
-```ts
-cache.on("error", ({ key, error }) => {
-  pagerDuty.trigger(`Cache error on ${key}`, error);
-});
-
-cache.on("miss", ({ key, driver }) => {
-  if (key.startsWith("hot.")) auditLog.miss(key, driver);
-});
-```
-
-Available events: `hit`, `miss`, `set`, `removed`, `flushed`, `expired`, `connected`, `disconnected`, `error`.
-
-Listeners attached via `cache.on(...)` survive driver switches the same way the metrics collector does.
-
-## Which one to reach for
-
-| Goal | Use |
-|---|---|
-| Show hit rate / latency in a dashboard | `cache.metrics()` |
-| Page on cache errors | `cache.on("error", ...)` |
-| Periodic export to Prometheus / StatsD | `cache.metrics()` + `setInterval` + `resetMetrics()` |
-| Audit log of every removal | `cache.on("removed", ...)` |
-| Detect a specific anti-pattern (e.g. always-miss key) | `cache.on("miss", ...)` |
-| Debug "is the cache being hit at all?" in dev | `cache.metrics()` once at the end of a flow |
-
-Both layers can coexist — events fire whether the metrics collector is attached or not.
-
-## Common shapes
-
-### Periodic export, then reset
-
-```ts
-setInterval(() => {
-  const snapshot = cache.metrics();
-  exporter.send(snapshot);
-  cache.resetMetrics();
-}, 60_000);
-```
-
-The snapshot now reflects the last minute of traffic, not the lifetime.
-
-### Boundary measurement
-
-```ts
-cache.resetMetrics();
-await runTrafficBurst();
-console.log(cache.metrics());
-```
-
-Useful for benchmarks, soak tests, "did the cache help?" before/after comparisons.
-
-### Per-driver isolation
-
-```ts
-const m = cache.metrics();
-console.log(`memory hit rate: ${m.byDriver.memory?.hitRate ?? 0}`);
-console.log(`redis p95: ${m.byDriver.redis?.latencyMs.p95 ?? 0}ms`);
-```
-
-Drivers that never fire events stay absent from `byDriver` — guard with `?.` and `?? 0`.
-
-## Things NOT to do
-
-- Don't subscribe to events to count things and ignore the built-in collector — that's exactly what it's built to do.
-- Don't call `cache.metrics()` on every request expecting per-request data — it returns a running aggregate. Use the event bus for per-call observability.
-- Don't expect lifetime percentiles. The buffer is bounded — for a 24h p95, sample-and-aggregate at your exporter, don't ask cache to remember every op forever.
-- Don't forget to attach early. If startup metrics matter, call `cache.metrics()` right after `cache.init()`.
+---
+name: observe-cache
+description: 'Cache observability — cache.metrics() for aggregate hit rate / latency p50/p95/p99 + event bus (cache.on(''hit'' / ''miss'' / ''set'' / ''removed'' / ''flushed'' / ''expired'' / ''error'', ...)). Triggers: `cache.metrics`, `cache.resetMetrics`, `cache.on`, `hit`, `miss`, `removed`, `flushed`, `error`, `hitRate`, `latencyMs`; "show cache hit rate", "page on cache errors", "is my cache being hit", "export metrics to prometheus"; typical import `import { cache } from "@warlock.js/cache"`. Skip: error classes — `@warlock.js/cache/handle-cache-errors/SKILL.md`; competing libs `prom-client`, `statsd-client`.'
+---
+
+# Cache observability — `cache.metrics()` and the event bus
+
+Two layers, different jobs.
+
+## Layer 1 — `cache.metrics()` for aggregate health
+
+Built-in collector subscribed to the manager's event bus. Returns a snapshot whenever you ask:
+
+```ts
+const m = cache.metrics();
+// {
+//   hits, misses, sets, removed, errors,
+//   hitRate,
+//   latencyMs: { p50, p95, p99, samples },
+//   byDriver: { memory: {...}, redis: {...} },
+//   startedAt,
+// }
+```
+
+**Lazy** — the collector attaches on the first `cache.metrics()` / `cache.resetMetrics()` call. Apps that never read metrics pay zero cost. Earlier events are not retroactively counted, so if you want metrics on every op including the first, call `cache.metrics()` once during startup right after `cache.init()`.
+
+**Survives `cache.use()` switches** — listens at the manager level, re-attaches to every loaded driver.
+
+**Latency** is sampled by the manager around `get` / `set` / `remove` into a circular buffer (default 1000 samples per driver). Percentiles are computed at snapshot time. Older samples age out, so percentiles reflect the recent ~1000 ops.
+
+`cache.resetMetrics()` zeroes counters + drops the buffer + bumps `startedAt`.
+
+## Layer 2 — Raw events for per-event reactions
+
+When you need to react to specific events (alerting, audit logs, debugging), subscribe to the event bus:
+
+```ts
+cache.on("error", ({ key, error }) => {
+  pagerDuty.trigger(`Cache error on ${key}`, error);
+});
+
+cache.on("miss", ({ key, driver }) => {
+  if (key.startsWith("hot.")) auditLog.miss(key, driver);
+});
+```
+
+Available events: `hit`, `miss`, `set`, `removed`, `flushed`, `expired`, `connected`, `disconnected`, `error`.
+
+Listeners attached via `cache.on(...)` survive driver switches the same way the metrics collector does.
+
+## Which one to reach for
+
+| Goal | Use |
+|---|---|
+| Show hit rate / latency in a dashboard | `cache.metrics()` |
+| Page on cache errors | `cache.on("error", ...)` |
+| Periodic export to Prometheus / StatsD | `cache.metrics()` + `setInterval` + `resetMetrics()` |
+| Audit log of every removal | `cache.on("removed", ...)` |
+| Detect a specific anti-pattern (e.g. always-miss key) | `cache.on("miss", ...)` |
+| Debug "is the cache being hit at all?" in dev | `cache.metrics()` once at the end of a flow |
+
+Both layers can coexist — events fire whether the metrics collector is attached or not.
+
+## Common shapes
+
+### Periodic export, then reset
+
+```ts
+setInterval(() => {
+  const snapshot = cache.metrics();
+  exporter.send(snapshot);
+  cache.resetMetrics();
+}, 60_000);
+```
+
+The snapshot now reflects the last minute of traffic, not the lifetime.
+
+### Boundary measurement
+
+```ts
+cache.resetMetrics();
+await runTrafficBurst();
+console.log(cache.metrics());
+```
+
+Useful for benchmarks, soak tests, "did the cache help?" before/after comparisons.
+
+### Per-driver isolation
+
+```ts
+const m = cache.metrics();
+console.log(`memory hit rate: ${m.byDriver.memory?.hitRate ?? 0}`);
+console.log(`redis p95: ${m.byDriver.redis?.latencyMs.p95 ?? 0}ms`);
+```
+
+Drivers that never fire events stay absent from `byDriver` — guard with `?.` and `?? 0`.
+
+## Things NOT to do
+
+- Don't subscribe to events to count things and ignore the built-in collector — that's exactly what it's built to do.
+- Don't call `cache.metrics()` on every request expecting per-request data — it returns a running aggregate. Use the event bus for per-call observability.
+- Don't expect lifetime percentiles. The buffer is bounded — for a 24h p95, sample-and-aggregate at your exporter, don't ask cache to remember every op forever.
+- Don't forget to attach early. If startup metrics matter, call `cache.metrics()` right after `cache.init()`.
 
 
 ## overview  `@warlock.js/cache/overview/SKILL.md`
@@ -729,1354 +737,1365 @@ Nineteen task skills. Most apps start with `cache-basics` + `pick-cache-driver`
 
 ## pick-cache-driver  `@warlock.js/cache/pick-cache-driver/SKILL.md`
 
----
-name: pick-cache-driver
-description: "Cache drivers — pick the right one in @warlock.js/cache; use when you need to choose cache driver."
----
-
-# Cache drivers — pick the right one
-
-Seven production drivers + a mock driver ship in-box. Pick by durability, scope, and workload.
-
-| Driver | Process scope | Persists on restart | Good for | Avoid when |
-| --- | --- | --- | --- | --- |
-| `null` | — | — | Disabling cache in tests; feature-flagging off | You actually want caching |
-| `memory` | Single process | No | Hot in-process data with default TTL; smallest latency | Multi-process / multi-node |
-| `memoryExtended` | Single process | No | Sliding-window TTL (TTL resets on every read) | Any multi-process deploy |
-| `lru` | Single process | No | Bounded in-memory caches (capacity-based eviction) | Need cross-process sharing |
-| `file` | Single host | Yes | Build artefacts, local dev persistence across restarts | Concurrency (no locks); multi-host |
-| `redis` | Shared | Yes (Redis-managed) | Anything shared across processes / nodes | Single-process-only workload — overkill |
-| `pg` | Shared | Yes (Postgres-managed) | You already run Postgres; semantic caching / RAG via pgvector | High-throughput hot reads (Redis is faster) |
-
-## Capability matrix
-
-| Capability | null | memory | memoryExt | lru | file | redis | pg |
-| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
-| `set` / `get` / `remove` / `flush` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| TTL (number or string) | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Sliding TTL on read | — | — | ✓ | — | — | — | — |
-| `removeNamespace` | noop | ✓ | ✓ | ✓ (prefix-scan) | ✓ | ✓ | ✓ (LIKE prefix) |
-| `onConflict: "create"` / `"update"` | noop | emulated | emulated | emulated | emulated | native `NX`/`XX` | native (INSERT ON CONFLICT) |
-| Native increment / decrement | — | ✓ | ✓ | ✓ | ✓ | atomic `INCRBY`/`DECRBY` | ✓ |
-| `update()` / `merge()` | ✓ | ✓ | ✓ | ✓ | ✗ throws | ✓ (single-process safety only today) | ✓ |
-| List sub-API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (O(n) JSON blob today; native LPUSH/LRANGE in v2.1) | ✓ |
-| Tagged invalidation | noop | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (native GIN(tags)) |
-| `similar()` / `set({ vector })` | returns `[]` / noop | ✓ brute force | ✓ brute force | ✓ brute force | ✗ throws | ✗ throws (Phase 2 backlog) | ✓ (with `vector` config — pgvector) |
-
-## Global config TTL — accepts number or string
-
-```ts
-options: {
-  redis:  { url: "...", ttl: "7d" },   // string OK
-  memory: { ttl: 3600 },                // number OK
-  lru:    { capacity: 10_000 },         // LRU has no TTL option today
-  file:   { directory: () => "/var/cache/myapp", ttl: "1h" },
-  pg:     { client: pool, ttl: "1h" },                           // KV-only
-  // pg with pgvector:
-  // pg:  { client: pool, vector: { dimensions: 1536, index: "hnsw" } },
-}
-```
-
-## Global prefix (multi-tenant scoping)
+---
+name: pick-cache-driver
+description: 'Pick a cache driver — null / memory / memoryExtended / lru / file / redis / pg / mock — and configure it. Triggers: `cache.setCacheConfigurations`, `BaseCacheDriver`, `cache.use`, `cache.load`, `cache.driver`, `globalPrefix`; "which cache driver should I use", "configure redis driver", "register custom cache driver", "multi-tenant scoping"; typical import `import { cache, BaseCacheDriver } from "@warlock.js/cache"`. Skip: cache CRUD — `@warlock.js/cache/cache-basics/SKILL.md`; pg setup — `@warlock.js/cache/configure-pg-cache/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`, `ioredis`; native `Map`.'
+---
+
+# Cache drivers — pick the right one
+
+Seven production drivers + a mock driver ship in-box. Pick by durability, scope, and workload.
+
+| Driver | Process scope | Persists on restart | Good for | Avoid when |
+| --- | --- | --- | --- | --- |
+| `null` | — | — | Disabling cache in tests; feature-flagging off | You actually want caching |
+| `memory` | Single process | No | Hot in-process data with default TTL; smallest latency | Multi-process / multi-node |
+| `memoryExtended` | Single process | No | Sliding-window TTL (TTL resets on every read) | Any multi-process deploy |
+| `lru` | Single process | No | Bounded in-memory caches (capacity-based eviction) | Need cross-process sharing |
+| `file` | Single host | Yes | Build artefacts, local dev persistence across restarts | Concurrency (no locks); multi-host |
+| `redis` | Shared | Yes (Redis-managed) | Anything shared across processes / nodes | Single-process-only workload — overkill |
+| `pg` | Shared | Yes (Postgres-managed) | You already run Postgres; semantic caching / RAG via pgvector | High-throughput hot reads (Redis is faster) |
+
+## Capability matrix
+
+| Capability | null | memory | memoryExt | lru | file | redis | pg |
+| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
+| `set` / `get` / `remove` / `flush` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| TTL (number or string; numeric strings = seconds) | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Sliding TTL on read | — | — | ✓ | — | — | — | — |
+| `removeNamespace` | noop | ✓ | ✓ | ✓ (prefix-scan) | ✓ | ✓ | ✓ (LIKE prefix) |
+| `onConflict: "create"` / `"update"` | noop | emulated | emulated | emulated | emulated | native `NX`/`XX` | native (INSERT ON CONFLICT) |
+| `increment` / `decrement` / `pull` | — | one process | one process | one process | one process | **cross-server** | **cross-server** |
+| `update()` / `merge()` | ✓ | one process | one process | one process | ✗ throws | **cross-server** (compare-and-set) | **cross-server** (compare-and-set) |
+| List sub-API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (O(n) JSON blob today; native LPUSH/LRANGE in v2.1) | ✓ |
+| Tagged invalidation | noop | ✓ | ✓ | ✓ | ✓ (serialized index) | ✓ (native SET) | ✓ (JSON-array merge) |
+| `similar()` / `set({ vector })` | returns `[]` / noop | ✓ brute force | ✓ brute force | ✓ brute force | ✗ throws | ✗ throws (Phase 2 backlog) | ✓ (with `vector` config — pgvector) |
+
+## Multi-server: use redis or pg
+
+Memory, memoryExtended, lru and file caches are **per-process** (file: per host). With more than one server, use `redis` or `pg` for counters, throttles, one-time tokens (`pull`), shared `update`, `lock()` and tag invalidation; on memory each server counts and invalidates alone. `remember()`/`swr()`/`cached()` stampede protection is per process even on redis. Redis Cluster is unsupported.
+
+Driver storage notes: `memory` stores flat keys (`get("users")` after `set("users.1")` is a miss) and `maxSize` counts entries in LRU order; redis `flush()` without a `globalPrefix` runs `FLUSHDB` (whole database), so set a prefix.
+
+## Global config TTL — accepts number or string
+
+```ts
+options: {
+  redis:  { url: "...", ttl: "7d" },   // string OK
+  memory: { ttl: 3600 },                // number OK
+  lru:    { capacity: 10_000 },         // LRU has no TTL option today
+  file:   { directory: () => "/var/cache/myapp", ttl: "1h" },
+  pg:     { client: pool, ttl: "1h" },                           // KV-only
+  // pg with pgvector:
+  // pg:  { client: pool, vector: { dimensions: 1536, index: "hnsw" } },
+}
+```
+
+## Global prefix (multi-tenant scoping)
+
+Every driver accepts `globalPrefix: string | (() => string)`. The function form runs per call — pair it with request-local async context to scope every cached key to the current tenant / user / client automatically:
+
+```ts
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+```
+
+## Key & namespace safety (file / redis)
+
+Cache keys can carry untrusted input (e.g. a `cached()` auto-key derived from a request param), so every built-in driver treats a key as data, never as a path or a query fragment:
+
+- **`file`** — a key/namespace maps to exactly one on-disk directory component: `%`, `/`, and `\` are percent-encoded before the path is built, so `../../etc` becomes an inert directory name instead of a traversal. The resolved path is also asserted to stay inside the configured cache root (throws `CacheError` otherwise) — a second, encoding-independent check. `removeNamespace` clears both the namespace's own directory and every dotted child (`ns`, `ns.*`), honoring `globalPrefix`.
+- **`redis`** — `removeNamespace` escapes glob metacharacters (`*`, `?`, `[`, `\`) in the namespace before building its match pattern, and walks matches with a `SCAN` cursor (`scanIterator`) instead of the blocking `KEYS` command, so clearing a namespace on a large keyspace doesn't stall the event loop for other tenants.
+- **Errors that echo a connection string** (Redis `connect()` failures, any driver's failed op) are logged through a `safeErrorInfo()` helper that redacts `scheme://user:pass@` credentials to `scheme://[REDACTED]@` and never prints the raw `Error` object — see [`@warlock.js/cache/handle-cache-errors/SKILL.md`](@warlock.js/cache/handle-cache-errors/SKILL.md).
+
+## Registering a custom driver
+
+```ts
+import { BaseCacheDriver, cache } from "@warlock.js/cache";
+
+class MemcachedCacheDriver extends BaseCacheDriver<MyClient, MyOptions> {
+  public name = "memcached";
+  // … implement set / get / remove / flush / removeNamespace / connect
+}
+
+cache.setCacheConfigurations({
+  default: "memcached",
+  drivers: { memcached: MemcachedCacheDriver },
+  options: { memcached: { host: "localhost" } },
+});
+```
+
+Extending `BaseCacheDriver` gives you free: TTL parsing, key parsing, event emission, stampede-safe `remember`, deep-clone-on-read, default `update` / `merge` / `list` implementations.
+
+## Runtime driver options — `cache.use(name, options)`
+
+Some driver options can only be built at runtime (`pg`'s `client: pg.Pool`, pre-wired clients). Pass them as the second arg to `cache.use` / `cache.load` / `cache.driver` — they merge over `setCacheConfigurations({ options })` per-key, runtime wins.
+
+```ts
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+cache.setCacheConfigurations({
+  default: "pg",
+  drivers: { pg: PgCacheDriver },
+  options: { pg: { table: "cache" } },        // static
+});
+
+await cache.use("pg", { client: pool });       // runtime — skip init() in this case
+```
+
+Constraints:
+- The driver name must be registered in `setCacheConfigurations({ drivers })` — runtime options don't bypass registration.
+- Once a driver is loaded, calling `use`/`load`/`driver` again with **non-empty** new options throws `CacheConfigurationError`. Register a second driver name if you need a different config.
+- Calling without options (or with `{}`) on an already-loaded driver returns the cached instance silently.
+
+## Per-call driver override
+
+When most writes go to the default driver but one call needs a different one:
+
+```ts
+await cache.set("audit:event", event, { driver: "redis" });
+```
+
+The manager loads (and connects) the override driver lazily on first use, then routes that single operation through it without mutating `currentDriver`.
+
+## See also
+
+- [`@warlock.js/cache/configure-pg-cache/SKILL.md`](@warlock.js/cache/configure-pg-cache/SKILL.md) — full pg setup (KV-only and pgvector mode)
+- [`@warlock.js/cache/test-cache-code/SKILL.md`](@warlock.js/cache/test-cache-code/SKILL.md) — `MockCacheDriver` and `NullCacheDriver` for tests
 
-Every driver accepts `globalPrefix: string | (() => string)`. The function form runs per call — pair it with request-local async context to scope every cached key to the current tenant / user / client automatically:
 
-```ts
-options: {
-  redis: {
-    url: "...",
-    globalPrefix: () => `tenant-${currentContext.tenantId}`,
-  },
-}
-```
+## test-cache-code  `@warlock.js/cache/test-cache-code/SKILL.md`
 
-## Key & namespace safety (file / redis)
+---
+name: test-cache-code
+description: 'Test code that touches cache — MockCacheDriver (behavioral assertions with wasCalled / callLog), MemoryCacheDriver (full-stack), NullCacheDriver (graceful-degradation). Triggers: `MockCacheDriver`, `MemoryCacheDriver`, `NullCacheDriver`, `wasCalled`, `callLog`, `getStored`, `reset`, `cache.on`; "assert cache was invalidated", "test code that uses cache.set", "mock cache in vitest", "test similarity without a real embedder", "stub the pg cache driver"; typical import `import { cache, MockCacheDriver, MemoryCacheDriver } from "@warlock.js/cache"`. Skip: real driver picks — `@warlock.js/cache/pick-cache-driver/SKILL.md`; competing libs `jest-mock`, `sinon`, `redis-mock`; native `vi.fn`.'
+---
+
+# Testing code that touches cache
+
+Three good strategies — pick based on what you're testing.
+
+## Strategy 1 — `MockCacheDriver` for behavioral assertions (preferred)
+
+When you want to assert "did my service actually invalidate the cache after the update?" or "was `set` called with the right TTL?", reach for `MockCacheDriver`. It implements the full driver contract on a `Map` and adds three introspection helpers:
+
+- `wasCalled(operation, key?)` — was a given op invoked? Optional key matched post-`parseKey`.
+- `getStored(key)` — raw stored value, bypassing TTL handling and clone protection.
+- `reset()` — wipe storage, tag index, and call log in one call.
+- `callLog: CacheCall[]` — ordered record of every op (operation, parsed key, raw args, timestamp).
+
+```ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { cache, MockCacheDriver } from "@warlock.js/cache";
+
+describe("UserService.update", () => {
+  let driver: MockCacheDriver;
+
+  beforeEach(async () => {
+    cache.setCacheConfigurations({
+      default: "mock",
+      logging: false,
+      drivers: { mock: MockCacheDriver },
+      options: { mock: {} },
+    });
+    await cache.init();
+
+    driver = cache.currentDriver as MockCacheDriver;
+  });
+
+  afterEach(async () => {
+    driver.reset();
+    await cache.disconnect();
+  });
+
+  it("invalidates the user cache after update", async () => {
+    await new UserService().update(42, { name: "Jane" });
+
+    expect(driver.wasCalled("remove", "users.42")).toBe(true);
+  });
+
+  it("caches with the right TTL on read-through", async () => {
+    await new UserService().getProfile(1);
+
+    const setCall = driver.callLog.find((call) => call.operation === "set");
+    expect(setCall?.args[1]).toBe("1h");
+  });
+});
+```
+
+`wasCalled` normalizes object keys, so `wasCalled("set", { id: 1 })` and `wasCalled("set", "id.1")` match the same call.
+
+## Strategy 2 — `MemoryCacheDriver` for full-stack integration tests
+
+When you want the real read/write semantics (eviction, TTL expiry, similarity scoring) without the introspection ceremony, `MemoryCacheDriver` is the right pick. Same setup pattern as the mock — swap `MockCacheDriver` for `MemoryCacheDriver`.
+
+`MockCacheDriver` does NOT implement `similar()` — vector writes are recorded into the call log but nearest-neighbor scoring is not available. Tests that call `cache.similar(...)` should use the memory driver.
+
+## Strategy 3 — `NullCacheDriver` when you need cache *off*
+
+Use `NullCacheDriver` to disable caching entirely for code paths that should still work without a cache (graceful-degradation tests):
+
+```ts
+cache.setCacheConfigurations({
+  default: "null",
+  drivers: { null: NullCacheDriver },
+  options: { null: {} },
+});
+await cache.init();
+
+// All cache ops no-op; get() always returns null; set() silently discards.
+```
+
+## Mocking Redis (for driver-level tests, not app code)
+
+For tests that specifically exercise `RedisCacheDriver`, use `vi.mock("redis")` with an in-memory fake. Example (condensed from `redis-cache-driver.spec.ts`):
+
+```ts
+import { vi } from "vitest";
+
+class FakeRedisClient {
+  public store = new Map<string, string>();
+  private expires = new Map<string, number>();
+  public on() { return this; }
+  public async connect() {}
+  public async quit() {}
+  public async set(key: string, value: string, opts?: { EX?: number; NX?: boolean; XX?: boolean }) {
+    if (opts?.NX && this.store.has(key)) return null;
+    if (opts?.XX && !this.store.has(key)) return null;
+    this.store.set(key, value);
+    if (opts?.EX) this.expires.set(key, Date.now() + opts.EX * 1000);
+    return "OK";
+  }
+  public async get(key: string) {
+    const ttl = this.expires.get(key);
+    if (ttl && ttl < Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return this.store.get(key) ?? null;
+  }
+  public async del(keys: string | string[]) {
+    const arr = Array.isArray(keys) ? keys : [keys];
+    let count = 0;
+    for (const k of arr) if (this.store.delete(k)) count++;
+    return count;
+  }
+  public async keys(pattern: string) {
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    return [...this.store.keys()].filter((k) => regex.test(k));
+  }
+  public async flushAll() { this.store.clear(); this.expires.clear(); }
+  public async incrBy(key: string, n: number) {
+    const next = Number(this.store.get(key) ?? 0) + n;
+    this.store.set(key, String(next));
+    return next;
+  }
+  public async decrBy(key: string, n: number) { return this.incrBy(key, -n); }
+}
+
+const fakeClient = new FakeRedisClient();
+vi.mock("redis", () => ({ createClient: vi.fn(() => fakeClient) }));
+```
+
+**One-time gotcha:** `RedisCacheDriver` kicks off an async `loadRedis()` at module import that resolves its internal "redis is available" flag. Before running any test that calls `connect()`, wait a short tick after the first dynamic import so the flag flips. The in-tree spec uses:
+
+```ts
+async function importDriver() {
+  const mod = await import("./redis-cache-driver");
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  return mod.RedisCacheDriver;
+}
+```
+
+## Silencing cache logs in tests
+
+The in-package vitest config runs `silent: true`, but if you're outside the package, explicitly disable logging:
+
+```ts
+cache.setCacheConfigurations({
+  default: "memory",
+  logging: false,             // <-- here
+  drivers: { memory: MemoryCacheDriver },
+  options: { memory: {} },
+});
+```
+
+Or per-driver: `driver.setLoggingState(false)`.
+
+## Spying on events
+
+Every driver emits `hit`, `miss`, `set`, `removed`, `flushed`, `expired`. Attach listeners to assert cache behavior without inspecting internal state:
+
+```ts
+const hits = vi.fn();
+cache.on("hit", hits);
+
+await service.getProfile("1");
+await service.getProfile("1");
+
+expect(hits).toHaveBeenCalledTimes(1);   // second call was a hit
+```
+
+Listeners registered via `cache.on(...)` automatically attach to any driver loaded later, so order of `on()` vs `init()` doesn't matter.
+
+## Tests for `update` / `merge` concurrency
+
+The chain-serialization guarantee is worth testing when your code fans out concurrent updates:
+
+```ts
+await cache.set("counter", 0);
+
+await Promise.all(
+  Array.from({ length: 10 }, () =>
+    cache.update<number>("counter", (c) => (c ?? 0) + 1),
+  ),
+);
+
+await expect(cache.get("counter")).resolves.toBe(10);
+```
+
+Runs in-process only — for cross-process safety see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
+
+## Testing similarity code paths
+
+`MemoryCacheDriver` runs `similar()` brute-force in-process — perfect for tests of code that calls `cache.similar(...)`. Use stable, hand-written vectors (don't call a real embedder in tests):
+
+```ts
+beforeEach(async () => {
+  cache.setCacheConfigurations({
+    default: "memory",
+    logging: false,
+    drivers: { memory: MemoryCacheDriver },
+    options: { memory: {} },
+  });
+  await cache.init();
+});
+
+it("returns the most similar doc above threshold", async () => {
+  await cache.set("a", { text: "alpha" }, { vector: [1, 0, 0] });
+  await cache.set("b", { text: "beta" },  { vector: [0, 1, 0] });
+
+  const hits = await cache.similar([1, 0, 0], { topK: 1, threshold: 0.5 });
+
+  expect(hits).toHaveLength(1);
+  expect(hits[0].key).toBe("a");
+});
+```
+
+## Testing the `pg` driver without a real Postgres
+
+The `pg` driver accepts any object satisfying `PgClientLike` (`{ query(text, values) }`). For unit tests, hand-roll a minimal Map-backed fake — see `src/drivers/pg-cache-driver.spec.ts` for a 60-line `FakePool` that recognizes the exact SQL shapes the driver issues. For integration coverage, gate a real-PG suite on a `POSTGRES_URL` env var and skip cleanly when unset.
 
-Cache keys can carry untrusted input (e.g. a `cached()` auto-key derived from a request param), so every built-in driver treats a key as data, never as a path or a query fragment:
 
-- **`file`** — a key/namespace maps to exactly one on-disk directory component: `%`, `/`, and `\` are percent-encoded before the path is built, so `../../etc` becomes an inert directory name instead of a traversal. The resolved path is also asserted to stay inside the configured cache root (throws `CacheError` otherwise) — a second, encoding-independent check. `removeNamespace` clears both the namespace's own directory and every dotted child (`ns`, `ns.*`), honoring `globalPrefix`.
-- **`redis`** — `removeNamespace` escapes glob metacharacters (`*`, `?`, `[`, `\`) in the namespace before building its match pattern, and walks matches with a `SCAN` cursor (`scanIterator`) instead of the blocking `KEYS` command, so clearing a namespace on a large keyspace doesn't stall the event loop for other tenants.
-- **Errors that echo a connection string** (Redis `connect()` failures, any driver's failed op) are logged through a `safeErrorInfo()` helper that redacts `scheme://user:pass@` credentials to `scheme://[REDACTED]@` and never prints the raw `Error` object — see [`@warlock.js/cache/handle-cache-errors/SKILL.md`](@warlock.js/cache/handle-cache-errors/SKILL.md).
+## use-cache-atomic  `@warlock.js/cache/use-cache-atomic/SKILL.md`
 
-## Registering a custom driver
+---
+name: use-cache-atomic
+description: 'Atomic counters via cache.increment(key, by=1) / cache.decrement(key, by=1) — returns the new number, throws on non-numeric values. Triggers: `cache.increment`, `cache.decrement`, "view counter", "page views", "atomic counter", "decrement stock", "rate-limit counter", "INCRBY"; typical import `import { cache } from "@warlock.js/cache"`. Skip: read-modify-write of objects — `@warlock.js/cache/use-cache-update-merge/SKILL.md`; named-lock coordination — `@warlock.js/cache/use-cache-lock/SKILL.md`; competing libs `ioredis` `INCR`, native counters in a `Map`.'
+---
+
+# Atomic counters — `cache.increment` / `cache.decrement`
+
+Numeric counters that go up and down without a read-then-write race in your own
+code. Both return the **new** value after the operation.
+
+```ts
+import { cache } from "@warlock.js/cache";
+
+const views = await cache.increment(`post.${id}.views`);     // +1 → 1, 2, 3…
+const bulk = await cache.increment(`post.${id}.views`, 10);  // +10
+const left = await cache.decrement(`stock.${sku}`, 3);       // -3
+```
+
+- A missing key is treated as `0`, so the first `increment` returns `by` (default `1`).
+- `decrement(key, n)` is exactly `increment(key, -n)`.
+- The stored value must be numeric — incrementing a string/object throws:
+  `Error: Cannot increment non-numeric value for key: <key>`.
+
+## Atomicity is per-driver
 
-```ts
-import { BaseCacheDriver, cache } from "@warlock.js/cache";
+`increment`, `decrement`, `pull` and `update` are atomic, but only some drivers are atomic **across servers**:
+
+| Driver | `increment` / `decrement` | `pull` | `update` / `merge` |
+|---|---|---|---|
+| `redis` | cross-server (`INCRBY`) | cross-server (`GETDEL`) | cross-server (Lua compare-and-set, retries) |
+| `pg` | cross-server (one upsert) | cross-server (`DELETE … RETURNING`) | cross-server (compare-and-set, retries) |
+| `memory` / `memoryExtended` / `lru` / `mock` | one process | one process | one process |
+| `file` | one process | one process | not supported (throws) |
+
+Use `redis` or `pg` for anything several servers touch (rate limits, login throttles, one-time tokens); memory is per-process. On redis/pg the `update` callback may run more than once under contention: keep it side-effect free.
+
+## TTL is kept
+
+Every driver keeps the key's **remaining TTL** across `increment`/`decrement`, so a fixed-window counter can't turn permanent. Set the TTL when you create the counter (`cache.set(key, 0, "1m")`, then `increment`). Use [`cache.update`](@warlock.js/cache/use-cache-update-merge/SKILL.md) for objects.
+
+## Common shapes
+
+```ts
+// View counter
+await cache.increment(`post.${id}.views`);
+
+// Decrement stock, guard against oversell
+const remaining = await cache.decrement(`stock.${sku}`, qty);
+if (remaining < 0) {
+  await cache.increment(`stock.${sku}`, qty); // roll back
+  throw new Error("Out of stock");
+}
+```
+
+## See also
+
+- [`@warlock.js/cache/use-cache-update-merge/SKILL.md`](@warlock.js/cache/use-cache-update-merge/SKILL.md) — atomic read-modify-write for objects, TTL-preserving
+- [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md) — coordinate multi-step critical sections
+- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — when you need cross-node atomicity
 
-class MemcachedCacheDriver extends BaseCacheDriver<MyClient, MyOptions> {
-  public name = "memcached";
-  // … implement set / get / remove / flush / removeNamespace / connect
-}
 
-cache.setCacheConfigurations({
-  default: "memcached",
-  drivers: { memcached: MemcachedCacheDriver },
-  options: { memcached: { host: "localhost" } },
-});
-```
+## use-cache-bulk  `@warlock.js/cache/use-cache-bulk/SKILL.md`
 
-Extending `BaseCacheDriver` gives you free: TTL parsing, key parsing, event emission, stampede-safe `remember`, deep-clone-on-read, default `update` / `merge` / `list` implementations.
+---
+name: use-cache-bulk
+description: 'Bulk reads/writes via cache.many(keys[]) → values[] (nulls for misses, order preserved) and cache.setMany(record, ttl?) → void. Triggers: `cache.many`, `cache.setMany`, "get multiple keys at once", "batch read cache", "warm the cache", "preload many keys", "mget", "mset"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag-based bulk invalidation — `@warlock.js/cache/use-cache-tags/SKILL.md`; single-key ops — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `ioredis` `MGET`/`MSET`.'
+---
+
+# Bulk operations — `cache.many` / `cache.setMany`
+
+Read or write a batch of keys in one call instead of awaiting them one at a time.
+
+## Read many — `many(keys)`
+
+```ts
+import { cache } from "@warlock.js/cache";
+
+const [alice, bob, carol] = await cache.many(["user.1", "user.2", "user.3"]);
+```
+
+- Returns an array **positionally aligned** with `keys`.
+- Missing keys come back as `null` (same as `get`), so the result length always
+  equals the input length — zip them back together by index.
+
+```ts
+const ids = [1, 2, 3];
+const users = await cache.many(ids.map((id) => `user.${id}`));
+
+const missingIds = ids.filter((_, index) => users[index] === null);
+// fetch only the misses from the origin…
+```
+
+## Write many — `setMany(items, ttl?)`
+
+```ts
+await cache.setMany({
+  "user.1": alice,
+  "user.2": bob,
+  "user.3": carol,
+}, 3600); // optional TTL (seconds) applied to every entry
+```
+
+- Keys are the object keys; values are the object values.
+- The optional second arg is a single TTL (seconds) applied to **all** entries —
+  there's no per-entry TTL or `tags` knob here. When you need tags or mixed TTLs,
+  loop with [`cache.set`](@warlock.js/cache/configure-set-options/SKILL.md) and
+  the rich options object instead.
+
+## Performance note
+
+On every driver these run their underlying `get`/`set` calls **concurrently**
+(`Promise.all`) on the shared connection; on the memory family it's effectively
+instant. There's no partial-failure handling — if one write rejects, the
+returned promise rejects.
+
+## See also
+
+- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — single-key `get` / `set` / `remember`
+- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — per-entry TTL, tags, conflict policy
+- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — invalidate a batch by tag
 
-## Runtime driver options — `cache.use(name, options)`
 
-Some driver options can only be built at runtime (`pg`'s `client: pg.Pool`, pre-wired clients). Pass them as the second arg to `cache.use` / `cache.load` / `cache.driver` — they merge over `setCacheConfigurations({ options })` per-key, runtime wins.
+## use-cache-list  `@warlock.js/cache/use-cache-list/SKILL.md`
 
-```ts
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+---
+name: use-cache-list
+description: 'Ordered collections via cache.list<T>(key) — push / unshift / pop / shift / slice / all / length / trim / clear. Triggers: `cache.list`, `push`, `unshift`, `pop`, `shift`, `slice`, `trim`, `clear`; "job queue in cache", "keep most recent N events", "audit log buffer", "FIFO queue"; typical import `import { cache } from "@warlock.js/cache"`. Skip: locking around list writes — `@warlock.js/cache/use-cache-lock/SKILL.md`; competing libs `bullmq`, `bee-queue`, `bull`, `ioredis` `LPUSH`; native `Array.push`.'
+---
+
+# Lists — the `cache.list<T>(key)` sub-API
+
+Dedicated accessor for ordered collections — queues, recent-N buffers, sliding windows. Keeps the flat `CacheDriver` contract lean while giving list-shaped data a typed, purpose-built surface.
+
+## Shape
+
+```ts
+const recent = cache.list<Event>("recent-events");
+
+await recent.push(event);                    // append to tail — returns new length
+await recent.unshift(priorityEvent);          // prepend to head — returns new length
+const tail = await recent.pop();              // remove + return tail
+const head = await recent.shift();            // remove + return head
+const first10 = await recent.slice(0, 10);    // view — does not mutate
+const all = await recent.all();
+const count = await recent.length();
+await recent.trim(0, 99);                     // keep only indices 0..99 inclusive
+await recent.clear();
+```
+
+## Type safety
+
+The generic flows through every method. Pass the element type at the accessor call, not on each method:
+
+```ts
+type Event = { type: string; at: number };
+const queue = cache.list<Event>("jobs:queue");
+
+await queue.push({ type: "import", at: Date.now() });   // ✓
+await queue.push("not an event" as never);              // ✗ at the caller
+```
+
+## Current performance characteristics
+
+The default implementation (used by memory, memoryExtended, LRU, file, **and redis today**) stores the entire list as a single cache entry and does read-mutate-write on every op. Correct for every driver, O(n) per op.
+
+Redis-native `LPUSH` / `RPUSH` / `LRANGE` / `LTRIM` is planned for v2.1 (see `domains/cache/backlog.md`). Until then, treat Redis list ops as O(n) and avoid very large lists on Redis.
+
+## Concurrency warning
+
+List writes on memory / file / LRU drivers **race** when two callers push simultaneously — the default read-mutate-write loop has no lock. If you need safe concurrent list writes today, wrap pushes in a distributed-lock pattern (see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md)) or use a single writer.
+
+Single-process memory with a single writer (typical test / script usage) is fine.
+
+## Empty-list cleanup
+
+When a list becomes empty (e.g. after successive `pop()` / `shift()` / `trim(0, -1)`), the backing cache entry is **removed** — `cache.get(key)` returns `null`, not `[]`. This keeps the store from accumulating empty list entries.
+
+```ts
+await recent.push("a");
+await recent.pop();
+await cache.get("recent-events");   // null, not []
+```
+
+## Typical recipes
+
+```ts
+// Recent-N audit log
+const audit = cache.list<AuditEntry>("audit:recent");
+await audit.unshift(entry);          // newest at head
+await audit.trim(0, 999);             // keep most-recent 1000
+
+// Lightweight job queue (single-node)
+const queue = cache.list<Job>("jobs:pending");
+await queue.push(job);
+const next = await queue.shift();     // FIFO
+
+// Stack
+const stack = cache.list<Frame>("stack");
+await stack.push(frame);
+const top = await stack.pop();        // LIFO
+```
+
+## What lists are NOT for
+
+- Unordered uniqueness — no native set today; use a plain object/Map in memory, or roll your own via `cache.get/set`.
+- Hash / field maps — same; use individual keys with a shared prefix.
+- Ordered top-N with scoring — no sorted-set analog today.
+
+These are tracked as candidates for v3.
 
-cache.setCacheConfigurations({
-  default: "pg",
-  drivers: { pg: PgCacheDriver },
-  options: { pg: { table: "cache" } },        // static
-});
 
-await cache.use("pg", { client: pool });       // runtime — skip init() in this case
-```
+## use-cache-lock  `@warlock.js/cache/use-cache-lock/SKILL.md`
 
-Constraints:
-- The driver name must be registered in `setCacheConfigurations({ drivers })` — runtime options don't bypass registration.
-- Once a driver is loaded, calling `use`/`load`/`driver` again with **non-empty** new options throws `CacheConfigurationError`. Register a second driver name if you need a different config.
-- Calling without options (or with `{}`) on an already-loaded driver returns the cached instance silently.
+---
+name: use-cache-lock
+description: 'Distributed lock via cache.lock(key, ttl, fn) — acquire, run fn, auto-release. Returns {acquired: true, value} or {acquired: false}. Triggers: `cache.lock`, `LockOutcome`, `acquired`, `owner`; "run cron on only one server", "idempotent webhook handler", "dedup payment processing", "lock a task across nodes"; typical import `import { cache } from "@warlock.js/cache"`. Skip: raw `onConflict: "create"` recipe — `@warlock.js/cache/apply-cache-patterns/SKILL.md`; memoization — `@warlock.js/cache/use-cached-hof/SKILL.md`; competing libs `redlock`, `async-mutex`, `proper-lockfile`.'
+---
+
+# `cache.lock()` — distributed locks with auto-release
+
+`cache.lock(key, ttl, fn)` acquires a distributed lock, runs `fn`, and auto-releases (even on throw). Built on `set({ onConflict: "create" })` — Redis-native where available, emulated elsewhere.
+
+## When to use
+
+- A task should run on only **one server at a time** (cron jobs, imports, migrations).
+- Idempotent webhook or payment processing — dedup across retries.
+- Any time you'd otherwise write `try { … } finally { cache.remove(lockKey); }`.
+
+**Not for memoization** — use [`cached()`](@warlock.js/cache/use-cached-hof/SKILL.md) or `cache.remember()`.
+
+## Shape
+
+```ts
+// Primary — positional TTL
+await cache.lock(key, ttl, fn);
+
+// With options — owner for debugging, per-call driver override
+await cache.lock(key, { ttl, owner?, driver? }, fn);
+```
+
+**TTL is required, finite and positive.** `0`, `Infinity`, negative, `NaN` and unparseable TTLs throw `CacheConfigurationError` before anything is written. A lock with no expiry blocks every server once its holder crashes.
+
+TTL rules: a number or a bare numeric string (`"90"`) is **seconds**; `"500ms"` and `0.5` round up to 1 s. There is no renewal or fencing, so the TTL must exceed the worst-case duration of `fn`.
+
+## Lock value and release
+
+- The stored value is `<owner>#<token>` (owner defaults to `pid.<pid>`; the token is random per acquisition). Match on the `<owner>#` prefix, never the bare owner.
+- Release is a compare-and-delete (atomic on memory, redis, pg): if your TTL expired and a successor acquired the key, your release leaves their lock alone.
+- A release error is logged and never replaces `fn`'s result or error.
+
+## Return shape — discriminated union
+
+```ts
+type LockOutcome<T> =
+  | { acquired: true; value: T }
+  | { acquired: false };
+```
+
+Unambiguous even when `fn` returns `undefined`. Narrow with TS:
+
+```ts
+const outcome = await cache.lock("lock.x", "1m", async () => compute());
+
+if (outcome.acquired) {
+  console.log(outcome.value);   // typed
+} else {
+  console.log("someone else is running");
+}
+```
+
+## Recipes
+
+### Cron on only one server
+
+```ts
+cron.daily("3am", () =>
+  cache.lock("lock.cleanup", "30m", () => db.cleanup()),
+);
+```
+
+### Idempotent webhook
+
+```ts
+app.post("/webhooks/stripe", async (req, res) => {
+  const outcome = await cache.lock(
+    `webhook.stripe.${req.body.id}`,
+    "24h",
+    () => processStripeEvent(req.body),
+  );
+
+  if (!outcome.acquired) {
+    return res.status(200).json({ status: "already-processed" });
+  }
+
+  res.status(200).json({ status: "processed" });
+});
+```
+
+### Batch job with debug-friendly owner
+
+```ts
+await cache.lock(
+  `lock.report.${date}`,
+  { ttl: "1h", owner: `worker.${process.env.HOSTNAME}` },
+  () => generateReport(date),
+);
+```
+
+`await cache.get("lock.report.2026-04-24")` reveals which worker holds the lock.
+
+## Driver behavior
+
+| Driver | Cross-process safe? |
+|--------|:-:|
+| `redis` | ✅ Native `SET … NX EX`, Lua release |
+| `pg` | ✅ `INSERT … ON CONFLICT`, one-statement release |
+| `memory` / `memoryExtended` / `lru` | ❌ In-process only (exclusive within the process) |
+| `file` | ⚠️ Single-host only (exclusive create) |
+| `null` | n/a — always "acquires" |
+
+## Gotchas
+
+- **Non-re-entrant in v1.** A recursive call for the same key gets `{ acquired: false }`.
+- **Don't release inside `fn`.** `lock()` handles release in `finally`. Manual `cache.remove(lockKey)` inside `fn` would let another process jump in mid-work.
+- **TTL shorter than `fn` runtime = race.** Pick a TTL with generous margin; there is no renewal.
+- **Cross-server requires `redis` or `pg`.** Memory / LRU / file drivers don't coordinate across servers.
 
-## Per-call driver override
 
-When most writes go to the default driver but one call needs a different one:
+## use-cache-namespace  `@warlock.js/cache/use-cache-namespace/SKILL.md`
 
-```ts
-await cache.set("audit:event", event, { driver: "redis" });
-```
+---
+name: use-cache-namespace
+description: 'Scope cache keys via cache.namespace(prefix, options?) — every key auto-prefixed, scope-level ttl / tags defaults, nested scopes, .clear() sugar. Triggers: `cache.namespace`, `cache.removeNamespace`, `clear`, `globalPrefix`; "scope cache keys under a prefix", "share TTL across a whole prefix", "drop every key under user.1", "nested cache scopes"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag-based bulk drop — `@warlock.js/cache/use-cache-tags/SKILL.md`; multi-tenant driver-level prefix — `@warlock.js/cache/pick-cache-driver/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `keyv` namespaces.'
+---
+
+# Scoped caches — `cache.namespace(prefix, options?)`
+
+When you'll touch the same prefix more than a couple of times, grab a scoped handle instead of repeating the prefix at every call site.
+
+## Shape
+
+```ts
+const chat = cache.namespace(`chats.${id}`, { ttl: "30d", tags: [`user.${userId}`] });
+
+await chat.set("messages.10", msg);          // chats.<id>.messages.10, 30d, user.<userId>
+await chat.set("draft", d, { ttl: "1h" });   // per-call ttl wins
+await chat.tags(["unread"]).set("ping", p);  // tags merge: user.<userId> + unread
+await chat.clear();                           // sugar for removeNamespace
+```
+
+Scopes are pure views — same connection, same driver, no extra state. Per-call options always win over scope defaults; tags merge additively.
+
+## Nested scopes
+
+```ts
+const chat = cache.namespace(`chats.${id}`, { ttl: "30d" });
+const typing = chat.namespace("typing", { ttl: "5s" });  // overrides parent ttl
+
+await typing.set("user.42", true);                       // chats.<id>.typing.user.42, 5s
+```
+
+Nested scopes inherit defaults and can override. Tags accumulate.
+
+## When to reach for it
+
+- The prefix repeats more than 2–3 times.
+- A whole prefix shares a TTL or tag policy.
+- You want `.clear()` to read like the intent ("clear this chat") instead of `removeNamespace(...)` boilerplate.
+
+Inline prefixes are still fine for one-off writes.
+
+## Plain `removeNamespace` when you already have the prefix
+
+When you *do* know the prefix string and don't need a scoped handle for repeated reads/writes:
+
+```ts
+await cache.set("user:1:profile", profile);
+await cache.set("user:1:prefs",   prefs);
+await cache.set("user:2:profile", otherProfile);
+
+await cache.removeNamespace("user.1");  // drops both user:1 entries, keeps user:2
+```
+
+Cheaper than tags (no reverse index to maintain). Every real driver supports it — memory family and `lru` by prefix-scan, `file` by directory (including dotted sibling keys like `ns.a`), `redis` by non-blocking `SCAN` (not `KEYS`), `pg` by key/`LIKE` prefix; `null` no-ops. Namespace strings are treated as data, not glob/path input — see [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the file-path-containment and redis-glob-escaping details.
+
+## Multi-tenant scoping at the driver level
+
+Instead of every call passing a tenant prefix, attach `globalPrefix` to the driver config — see [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md). Function form runs per call.
+
+```ts
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+```
+
+## SWR + namespace
+
+```ts
+const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
+
+await feed.swr(
+  "home",
+  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
+  () => buildHomeFeed(userId),
+);
+// stored at feed.<userId>.home, tagged [user.<userId>, computed]
+```
+
+Note: scope `ttl` defaults are NOT applied to SWR — `freshTtl` / `staleTtl` always come from the call site. See [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md).
+
+## Things NOT to do
+
+- Don't create a `cache.namespace(prefix)` for a single read/write — the boilerplate doesn't pay off until the prefix repeats. Inline `cache.set("prefix.foo", ...)` is fine.
+- Don't expect `cache.namespace(prefix).clear()` to do anything on the `null` driver — `removeNamespace` no-ops there (it caches nothing).
+- Don't mix prefix separators. The convention is `.` (dot) — pick one and stick with it across scopes so nested prefixes compose predictably.
 
-The manager loads (and connects) the override driver lazily on first use, then routes that single operation through it without mutating `currentDriver`.
 
-## See also
+## use-cache-similarity  `@warlock.js/cache/use-cache-similarity/SKILL.md`
 
-- [`@warlock.js/cache/configure-pg-cache/SKILL.md`](@warlock.js/cache/configure-pg-cache/SKILL.md) — full pg setup (KV-only and pgvector mode)
-- [`@warlock.js/cache/test-cache-code/SKILL.md`](@warlock.js/cache/test-cache-code/SKILL.md) — `MockCacheDriver` and `NullCacheDriver` for tests
+---
+name: use-cache-similarity
+description: 'Vector retrieval via cache.similar(vector, {topK, threshold?, tags?}) — index with set(k, v, {vector}), query nearest by cosine similarity. Triggers: `cache.similar`, `cache.set` with `vector`, `topK`, `threshold`, `tags`, `cosineSimilarity`; "build a semantic cache for an LLM", "RAG retrieval from cache", "nearest-neighbor over cached entries", "skip the LLM when a similar answer exists"; typical import `import { cache } from "@warlock.js/cache"`. Skip: pgvector setup specifics — `@warlock.js/cache/configure-pg-cache/SKILL.md`; competing libs `pinecone`, `weaviate`, `chromadb`, `lancedb`, `faiss-node`.'
+---
+
+# `cache.similar()` — vector-based retrieval
+
+`cache.similar(vector, { topK, threshold?, tags? })` returns stored entries closest to `vector` by cosine similarity, ordered descending by score. Same `set` / `get` model — different lookup function.
+
+## Shape
+
+```ts
+// Index on the way in.
+await cache.set(key, value, { vector: number[], tags?, ttl? });
+
+// Query.
+const hits = await cache.similar<T>(queryVec, {
+  topK: number,        // required
+  threshold?: number,  // [0, 1]; hits below are dropped
+  tags?: string[],     // narrow candidate pool by tag (union)
+});
+// hits: { key: string; value: T; score: number }[]   // score in [0, 1]
+```
+
+## Capability matrix
+
+| Driver | `similar()` |
+|---|---|
+| `memory` / `memoryExtended` / `lru` | ✅ Brute force (O(N)) — dev only past ~10k entries |
+| `pg` *with* `options.pg.vector` | ✅ pgvector + HNSW/IVFFlat index |
+| `pg` *without* `options.pg.vector` | ❌ Throws `CacheUnsupportedError` |
+| `redis` | ❌ Throws (RediSearch on backlog) |
+| `file` | ❌ Throws |
+| `null` | Returns `[]` |
+
+## Always-true facts
+
+1. **Cache is embedding-agnostic.** Caller computes vectors. The cache stores and ranks; it doesn't call out to an embedder.
+2. **Only entries written with `set({ vector })` show up.** A plain `set` adds the entry as KV — invisible to `similar()`.
+3. **Score = cosine similarity** in `[0, 1]` for typical embedding spaces. The `pg` driver computes `1 - (embedding <=> $1::vector)` so the score matches the memory drivers.
+4. **Tag filter narrows the candidate pool *before* ranking** — union semantics (entry must carry at least one of the listed tags).
+5. **Dimension mismatch throws `CacheConfigurationError`** at both `set({ vector })` and `similar()` time. Don't switch embedders without re-indexing.
+6. **TTL + LRU eviction also drop the vector** — expired or evicted entries are invisible to `similar()`.
+
+## Recipes
+
+### Semantic cache for an LLM
+
+```ts
+const queryVec = await embed(prompt);
+const hits = await cache.similar<Answer>(queryVec, { topK: 1, threshold: 0.92 });
+
+if (hits.length > 0) {
+  return hits[0].value;     // skip the LLM call
+}
+
+const answer = await llm.complete(prompt);
+await cache.set(`q.${hash(prompt)}`, answer, {
+  vector: queryVec,
+  ttl: "30d",
+  tags: ["llm-cache"],
+});
+return answer;
+```
+
+### Tag-narrowed RAG
+
+```ts
+const hits = await cache.similar<Doc>(await embed(question), {
+  topK: 5,
+  threshold: 0.7,
+  tags: ["docs", `tenant.${tenantId}`],
+});
+```
+
+### Production swap — same code, different driver
+
+```ts
+// Dev:
+options: { memory: { ttl: "1h" } }
+
+// Prod — same set/similar calls; index now lives in pgvector:
+options: { pg: { client: pool, vector: { dimensions: 1536 } } }
+```
+
+See [`@warlock.js/cache/configure-pg-cache/SKILL.md`](@warlock.js/cache/configure-pg-cache/SKILL.md).
+
+## Things NOT to do
+
+- Don't use `cache.similar()` on a memory driver with 100k+ vectorized entries — it scales O(N) per query. Switch to `pg` with `vector` config.
+- Don't pass an empty array as `vector` — `cosineSimilarity` throws `CacheConfigurationError`.
+- Don't mix vector dimensions in the same driver — re-embed when models change.
+- Don't expect `similar()` to surface a missing vector (`set` without the `vector` option). Plain KV entries stay out of the similarity index.
+- Don't use `topK: 0` or negative — `pg` rejects with `CacheConfigurationError`; memory drivers return `[]` but it's a code smell.
 
 
-## test-cache-code  `@warlock.js/cache/test-cache-code/SKILL.md`
+## use-cache-tags  `@warlock.js/cache/use-cache-tags/SKILL.md`
 
 ---
-name: test-cache-code
-description: "Testing code that touches cache in @warlock.js/cache; use when you need to test cache code."
+name: use-cache-tags
+description: 'Tag-based invalidation — attach tags on write, then cache.tags([...]).invalidate() drops every key bound to any of those tags. Triggers: `cache.tags`, `invalidate`, `cache.set` with `tags`; "invalidate every key tagged users", "drop everything for tenant 42", "bulk cache invalidation without knowing keys", "tag a cached value"; typical import `import { cache } from "@warlock.js/cache"`. Skip: prefix-based drop — `@warlock.js/cache/use-cache-namespace/SKILL.md`; HOF memoization with tags — `@warlock.js/cache/use-cached-hof/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `cache-manager` tags, Next.js `revalidateTag`.'
 ---
 
-# Testing code that touches cache
-
-Three good strategies — pick based on what you're testing.
-
-## Strategy 1 — `MockCacheDriver` for behavioral assertions (preferred)
+# Tag-based invalidation
 
-When you want to assert "did my service actually invalidate the cache after the update?" or "was `set` called with the right TTL?", reach for `MockCacheDriver`. It implements the full driver contract on a `Map` and adds three introspection helpers:
+Tags let you invalidate by a label rather than by enumerating every key. Use them when the set of keys to invalidate is not known ahead of time.
 
-- `wasCalled(operation, key?)` — was a given op invoked? Optional key matched post-`parseKey`.
-- `getStored(key)` — raw stored value, bypassing TTL handling and clone protection.
-- `reset()` — wipe storage, tag index, and call log in one call.
-- `callLog: CacheCall[]` — ordered record of every op (operation, parsed key, raw args, timestamp).
+## Attach tags on write
 
 ```ts
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { cache, MockCacheDriver } from "@warlock.js/cache";
+// Inline — terser when you know the tags up front
+await cache.set("user:1:profile", profile, { tags: ["users", "tenant-42"] });
+await cache.set("user:1:prefs",   prefs,   { tags: ["users", "tenant-42"] });
 
-describe("UserService.update", () => {
-  let driver: MockCacheDriver;
+// Fluent — useful when you already have a tagged handle
+const users = cache.tags(["users"]);
+await users.set("user:1", user);
+await users.set("user:2", otherUser);
+```
 
-  beforeEach(async () => {
-    cache.setCacheConfigurations({
-      default: "mock",
-      logging: false,
-      drivers: { mock: MockCacheDriver },
-      options: { mock: {} },
-    });
-    await cache.init();
+## Invalidate
 
-    driver = cache.currentDriver as MockCacheDriver;
-  });
+```ts
+// Drop everything tagged "users"
+await cache.tags(["users"]).invalidate();
 
-  afterEach(async () => {
-    driver.reset();
-    await cache.disconnect();
-  });
+// Multi-tag — matches either tag (union)
+await cache.tags(["tenant-42"]).invalidate();
+```
 
-  it("invalidates the user cache after update", async () => {
-    await new UserService().update(42, { name: "Jane" });
+Multi-tag is **union** semantics: an entry is invalidated if it carries **at least one** of the listed tags.
 
-    expect(driver.wasCalled("remove", "users.42")).toBe(true);
-  });
+## When to reach for tags vs namespaces
 
-  it("caches with the right TTL on read-through", async () => {
-    await new UserService().getProfile(1);
+| Use case | Reach for |
+| --- | --- |
+| The keys share a known prefix | `cache.removeNamespace("prefix")` ([`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md)) |
+| The keys are spread across prefixes, tied by entity | Tags |
+| Both apply | Tags — more flexible; cheap on most drivers |
 
-    const setCall = driver.callLog.find((call) => call.operation === "set");
-    expect(setCall?.args[1]).toBe("1h");
-  });
-});
-```
+Namespaces are cheaper (no reverse index). Tags are more powerful (any key can carry any tag).
 
-`wasCalled` normalizes object keys, so `wasCalled("set", { id: 1 })` and `wasCalled("set", "id.1")` match the same call.
+## Inline tag semantics
 
-## Strategy 2 — `MemoryCacheDriver` for full-stack integration tests
+Subsequent `set("user:1", ...)` with **no** `tags` leaves previous associations intact (the tag index still points to the key), but a `set(..., { tags: [...] })` adds to whatever index entries already exist rather than removing old tag bindings. Tag associations are additive at write-time.
 
-When you want the real read/write semantics (eviction, TTL expiry, similarity scoring) without the introspection ceremony, `MemoryCacheDriver` is the right pick. Same setup pattern as the mock — swap `MockCacheDriver` for `MemoryCacheDriver`.
+## Driver behavior
 
-`MockCacheDriver` does NOT implement `similar()` — vector writes are recorded into the call log but nearest-neighbor scoring is not available. Tests that call `cache.similar(...)` should use the memory driver.
+| Driver | Tag invalidation |
+| --- | :-: |
+| `null` | noop |
+| `memory` / `memoryExtended` / `lru` | ✓ (separate index store; eviction and expiry never touch it) |
+| `file` | ✓ (serialized index) |
+| `redis` | ✓ (native SET inside the prefix) |
+| `pg` | ✓ (JSON-array merge on the index row) |
 
-## Strategy 3 — `NullCacheDriver` when you need cache *off*
+The index uses driver primitives (`tagAdd` / `tagMembers` / `tagRemove`), so concurrent tagged writes never drop members. It stores un-prefixed keys, `invalidate()` deletes exactly the members it read, writes prune up to 20 dead members, and `remove()` / `pull()` detach the key. Tags are global across scopes. Across servers, use `redis` or `pg` so every server shares one index.
 
-Use `NullCacheDriver` to disable caching entirely for code paths that should still work without a cache (graceful-degradation tests):
+## SWR with tags
 
 ```ts
-cache.setCacheConfigurations({
-  default: "null",
-  drivers: { null: NullCacheDriver },
-  options: { null: {} },
-});
-await cache.init();
-
-// All cache ops no-op; get() always returns null; set() silently discards.
+await cache.swr(
+  `product.${id}`,
+  { freshTtl: "1m", staleTtl: "1h", tags: ["products", `tenant.${tenantId}`] },
+  () => db.products.find(id),
+);
 ```
 
-## Mocking Redis (for driver-level tests, not app code)
+Tags re-apply on every successful refresh — see [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md).
 
-For tests that specifically exercise `RedisCacheDriver`, use `vi.mock("redis")` with an in-memory fake. Example (condensed from `redis-cache-driver.spec.ts`):
+## `cached()` HOF with tags
 
 ```ts
-import { vi } from "vitest";
-
-class FakeRedisClient {
-  public store = new Map<string, string>();
-  private expires = new Map<string, number>();
-  public on() { return this; }
-  public async connect() {}
-  public async quit() {}
-  public async set(key: string, value: string, opts?: { EX?: number; NX?: boolean; XX?: boolean }) {
-    if (opts?.NX && this.store.has(key)) return null;
-    if (opts?.XX && !this.store.has(key)) return null;
-    this.store.set(key, value);
-    if (opts?.EX) this.expires.set(key, Date.now() + opts.EX * 1000);
-    return "OK";
-  }
-  public async get(key: string) {
-    const ttl = this.expires.get(key);
-    if (ttl && ttl < Date.now()) {
-      this.store.delete(key);
-      return null;
-    }
-    return this.store.get(key) ?? null;
-  }
-  public async del(keys: string | string[]) {
-    const arr = Array.isArray(keys) ? keys : [keys];
-    let count = 0;
-    for (const k of arr) if (this.store.delete(k)) count++;
-    return count;
-  }
-  public async keys(pattern: string) {
-    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
-    return [...this.store.keys()].filter((k) => regex.test(k));
-  }
-  public async flushAll() { this.store.clear(); this.expires.clear(); }
-  public async incrBy(key: string, n: number) {
-    const next = Number(this.store.get(key) ?? 0) + n;
-    this.store.set(key, String(next));
-    return next;
-  }
-  public async decrBy(key: string, n: number) { return this.incrBy(key, -n); }
-}
-
-const fakeClient = new FakeRedisClient();
-vi.mock("redis", () => ({ createClient: vi.fn(() => fakeClient) }));
-```
-
-**One-time gotcha:** `RedisCacheDriver` kicks off an async `loadRedis()` at module import that resolves its internal "redis is available" flag. Before running any test that calls `connect()`, wait a short tick after the first dynamic import so the flag flips. The in-tree spec uses:
+const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
+const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
 
-```ts
-async function importDriver() {
-  const mod = await import("./redis-cache-driver");
-  await new Promise((resolve) => setTimeout(resolve, 250));
-  return mod.RedisCacheDriver;
-}
+await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
 ```
 
-## Silencing cache logs in tests
+See [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md).
 
-The in-package vitest config runs `silent: true`, but if you're outside the package, explicitly disable logging:
+## Things NOT to do
 
-```ts
-cache.setCacheConfigurations({
-  default: "memory",
-  logging: false,             // <-- here
-  drivers: { memory: MemoryCacheDriver },
-  options: { memory: {} },
-});
-```
+- Don't tag aggressively. A reverse index per tag is cheap but not free — pick tags that actually correspond to invalidation events.
+- Don't expect tag invalidation to fire events for each affected key. It's a bulk op; the event bus emits one `flushed` or per-key `removed` per driver implementation. Test by reading back, not by counting events.
+- Don't use tags as a query mechanism. Tags drop keys; they don't list them. If you need "give me every user", store an index list separately.
 
-Or per-driver: `driver.setLoggingState(false)`.
 
-## Spying on events
+## use-cache-update-merge  `@warlock.js/cache/use-cache-update-merge/SKILL.md`
 
-Every driver emits `hit`, `miss`, `set`, `removed`, `flushed`, `expired`. Attach listeners to assert cache behavior without inspecting internal state:
-
-```ts
-const hits = vi.fn();
-cache.on("hit", hits);
-
-await service.getProfile("1");
-await service.getProfile("1");
-
-expect(hits).toHaveBeenCalledTimes(1);   // second call was a hit
-```
-
-Listeners registered via `cache.on(...)` automatically attach to any driver loaded later, so order of `on()` vs `init()` doesn't matter.
-
-## Tests for `update` / `merge` concurrency
-
-The chain-serialization guarantee is worth testing when your code fans out concurrent updates:
-
-```ts
-await cache.set("counter", 0);
-
-await Promise.all(
-  Array.from({ length: 10 }, () =>
-    cache.update<number>("counter", (c) => (c ?? 0) + 1),
-  ),
-);
-
-await expect(cache.get("counter")).resolves.toBe(10);
-```
-
-Runs in-process only — for cross-process safety see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
-
-## Testing similarity code paths
-
-`MemoryCacheDriver` runs `similar()` brute-force in-process — perfect for tests of code that calls `cache.similar(...)`. Use stable, hand-written vectors (don't call a real embedder in tests):
-
-```ts
-beforeEach(async () => {
-  cache.setCacheConfigurations({
-    default: "memory",
-    logging: false,
-    drivers: { memory: MemoryCacheDriver },
-    options: { memory: {} },
-  });
-  await cache.init();
-});
-
-it("returns the most similar doc above threshold", async () => {
-  await cache.set("a", { text: "alpha" }, { vector: [1, 0, 0] });
-  await cache.set("b", { text: "beta" },  { vector: [0, 1, 0] });
-
-  const hits = await cache.similar([1, 0, 0], { topK: 1, threshold: 0.5 });
-
-  expect(hits).toHaveLength(1);
-  expect(hits[0].key).toBe("a");
-});
-```
-
-## Testing the `pg` driver without a real Postgres
-
-The `pg` driver accepts any object satisfying `PgClientLike` (`{ query(text, values) }`). For unit tests, hand-roll a minimal Map-backed fake — see `src/drivers/pg-cache-driver.spec.ts` for a 60-line `FakePool` that recognizes the exact SQL shapes the driver issues. For integration coverage, gate a real-PG suite on a `POSTGRES_URL` env var and skip cleanly when unset.
-
-
-## use-cache-atomic  `@warlock.js/cache/use-cache-atomic/SKILL.md`
-
----
-name: use-cache-atomic
-description: "Atomic counters — cache.increment / cache.decrement in @warlock.js/cache; use when you need to use cache atomic."
----
-
-# Atomic counters — `cache.increment` / `cache.decrement`
-
-Numeric counters that go up and down without a read-then-write race in your own
-code. Both return the **new** value after the operation.
-
-```ts
-import { cache } from "@warlock.js/cache";
-
-const views = await cache.increment(`post.${id}.views`);     // +1 → 1, 2, 3…
-const bulk = await cache.increment(`post.${id}.views`, 10);  // +10
-const left = await cache.decrement(`stock.${sku}`, 3);       // -3
-```
-
-- A missing key is treated as `0`, so the first `increment` returns `by` (default `1`).
-- `decrement(key, n)` is exactly `increment(key, -n)`.
-- The stored value must be numeric — incrementing a string/object throws:
-  `Error: Cannot increment non-numeric value for key: <key>`.
-
-## Atomicity is per-driver
-
-| Driver | Guarantee |
-|---|---|
-| `redis` | Native `INCRBY` / `DECRBY` — atomic **across processes/nodes** |
-| memory family / `file` / `pg` | Read-modify-write — atomic **within one process** only |
-
-For a counter that multiple instances bump concurrently (a global rate limit, a
-shared tally), use the [`redis`](@warlock.js/cache/pick-cache-driver/SKILL.md)
-driver. In-memory counters are fine for single-node work.
-
-## TTL behavior differs too
-
-This is the gotcha to remember:
-
-- **Redis** `INCRBY` **preserves** the key's existing TTL.
-- **Memory-family / pg** write the new value through `set()` with the driver's
-  **default** TTL — they do **not** carry over the previous entry's remaining TTL.
-
-So if you need a counter that expires (a fixed window), set the TTL explicitly
-when you create it and don't rely on `increment` to keep a window alive on the
-in-memory drivers. For a value that should keep its TTL across edits, reach for
-[`cache.update`](@warlock.js/cache/use-cache-update-merge/SKILL.md), which
-preserves the remaining TTL.
-
-## Common shapes
-
-```ts
-// View counter
-await cache.increment(`post.${id}.views`);
-
-// Decrement stock, guard against oversell
-const remaining = await cache.decrement(`stock.${sku}`, qty);
-if (remaining < 0) {
-  await cache.increment(`stock.${sku}`, qty); // roll back
-  throw new Error("Out of stock");
-}
-```
-
-## See also
-
-- [`@warlock.js/cache/use-cache-update-merge/SKILL.md`](@warlock.js/cache/use-cache-update-merge/SKILL.md) — atomic read-modify-write for objects, TTL-preserving
-- [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md) — coordinate multi-step critical sections
-- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — when you need cross-node atomicity
-
-
-## use-cache-bulk  `@warlock.js/cache/use-cache-bulk/SKILL.md`
-
----
-name: use-cache-bulk
-description: "Bulk operations — cache.many / cache.setMany in @warlock.js/cache; use when you need to use cache bulk."
----
-
-# Bulk operations — `cache.many` / `cache.setMany`
-
-Read or write a batch of keys in one call instead of awaiting them one at a time.
-
-## Read many — `many(keys)`
-
-```ts
-import { cache } from "@warlock.js/cache";
-
-const [alice, bob, carol] = await cache.many(["user.1", "user.2", "user.3"]);
-```
-
-- Returns an array **positionally aligned** with `keys`.
-- Missing keys come back as `null` (same as `get`), so the result length always
-  equals the input length — zip them back together by index.
-
-```ts
-const ids = [1, 2, 3];
-const users = await cache.many(ids.map((id) => `user.${id}`));
-
-const missingIds = ids.filter((_, index) => users[index] === null);
-// fetch only the misses from the origin…
-```
-
-## Write many — `setMany(items, ttl?)`
-
-```ts
-await cache.setMany({
-  "user.1": alice,
-  "user.2": bob,
-  "user.3": carol,
-}, 3600); // optional TTL (seconds) applied to every entry
-```
-
-- Keys are the object keys; values are the object values.
-- The optional second arg is a single TTL (seconds) applied to **all** entries —
-  there's no per-entry TTL or `tags` knob here. When you need tags or mixed TTLs,
-  loop with [`cache.set`](@warlock.js/cache/configure-set-options/SKILL.md) and
-  the rich options object instead.
-
-## Performance note
-
-On every driver these run their underlying `get`/`set` calls **concurrently**
-(`Promise.all`) on the shared connection; on the memory family it's effectively
-instant. There's no partial-failure handling — if one write rejects, the
-returned promise rejects.
-
-## See also
-
-- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — single-key `get` / `set` / `remember`
-- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — per-entry TTL, tags, conflict policy
-- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — invalidate a batch by tag
-
-
-## use-cache-list  `@warlock.js/cache/use-cache-list/SKILL.md`
-
----
-name: use-cache-list
-description: "Lists — the cache.list<T>(key) sub-API in @warlock.js/cache; use when you need to use cache list."
----
-
-# Lists — the `cache.list<T>(key)` sub-API
-
-Dedicated accessor for ordered collections — queues, recent-N buffers, sliding windows. Keeps the flat `CacheDriver` contract lean while giving list-shaped data a typed, purpose-built surface.
-
-## Shape
-
-```ts
-const recent = cache.list<Event>("recent-events");
-
-await recent.push(event);                    // append to tail — returns new length
-await recent.unshift(priorityEvent);          // prepend to head — returns new length
-const tail = await recent.pop();              // remove + return tail
-const head = await recent.shift();            // remove + return head
-const first10 = await recent.slice(0, 10);    // view — does not mutate
-const all = await recent.all();
-const count = await recent.length();
-await recent.trim(0, 99);                     // keep only indices 0..99 inclusive
-await recent.clear();
-```
-
-## Type safety
-
-The generic flows through every method. Pass the element type at the accessor call, not on each method:
-
-```ts
-type Event = { type: string; at: number };
-const queue = cache.list<Event>("jobs:queue");
-
-await queue.push({ type: "import", at: Date.now() });   // ✓
-await queue.push("not an event" as never);              // ✗ at the caller
-```
-
-## Current performance characteristics
-
-The default implementation (used by memory, memoryExtended, LRU, file, **and redis today**) stores the entire list as a single cache entry and does read-mutate-write on every op. Correct for every driver, O(n) per op.
-
-Redis-native `LPUSH` / `RPUSH` / `LRANGE` / `LTRIM` is planned for v2.1 (see `domains/cache/backlog.md`). Until then, treat Redis list ops as O(n) and avoid very large lists on Redis.
-
-## Concurrency warning
-
-List writes on memory / file / LRU drivers **race** when two callers push simultaneously — the default read-mutate-write loop has no lock. If you need safe concurrent list writes today, wrap pushes in a distributed-lock pattern (see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md)) or use a single writer.
-
-Single-process memory with a single writer (typical test / script usage) is fine.
-
-## Empty-list cleanup
-
-When a list becomes empty (e.g. after successive `pop()` / `shift()` / `trim(0, -1)`), the backing cache entry is **removed** — `cache.get(key)` returns `null`, not `[]`. This keeps the store from accumulating empty list entries.
-
-```ts
-await recent.push("a");
-await recent.pop();
-await cache.get("recent-events");   // null, not []
-```
-
-## Typical recipes
-
-```ts
-// Recent-N audit log
-const audit = cache.list<AuditEntry>("audit:recent");
-await audit.unshift(entry);          // newest at head
-await audit.trim(0, 999);             // keep most-recent 1000
-
-// Lightweight job queue (single-node)
-const queue = cache.list<Job>("jobs:pending");
-await queue.push(job);
-const next = await queue.shift();     // FIFO
-
-// Stack
-const stack = cache.list<Frame>("stack");
-await stack.push(frame);
-const top = await stack.pop();        // LIFO
-```
-
-## What lists are NOT for
-
-- Unordered uniqueness — no native set today; use a plain object/Map in memory, or roll your own via `cache.get/set`.
-- Hash / field maps — same; use individual keys with a shared prefix.
-- Ordered top-N with scoring — no sorted-set analog today.
-
-These are tracked as candidates for v3.
-
-
-## use-cache-lock  `@warlock.js/cache/use-cache-lock/SKILL.md`
-
----
-name: use-cache-lock
-description: "cache.lock() — distributed locks with auto-release in @warlock.js/cache; use when you need to use cache lock."
----
-
-# `cache.lock()` — distributed locks with auto-release
-
-`cache.lock(key, ttl, fn)` acquires a distributed lock, runs `fn`, and auto-releases (even on throw). Built on `set({ onConflict: "create" })` — Redis-native where available, emulated elsewhere.
-
-## When to use
-
-- A task should run on only **one server at a time** (cron jobs, imports, migrations).
-- Idempotent webhook or payment processing — dedup across retries.
-- Any time you'd otherwise write `try { … } finally { cache.remove(lockKey); }`.
-
-**Not for memoization** — use [`cached()`](@warlock.js/cache/use-cached-hof/SKILL.md) or `cache.remember()`.
-
-## Shape
-
-```ts
-// Primary — positional TTL
-await cache.lock(key, ttl, fn);
-
-// With options — owner for debugging, per-call driver override
-await cache.lock(key, { ttl, owner?, driver? }, fn);
-```
-
-**TTL is required.** Forgotten locks stay forever if the process crashes; the TTL is your safety net.
-
-## Return shape — discriminated union
-
-```ts
-type LockOutcome<T> =
-  | { acquired: true; value: T }
-  | { acquired: false };
-```
-
-Unambiguous even when `fn` returns `undefined`. Narrow with TS:
-
-```ts
-const outcome = await cache.lock("lock.x", "1m", async () => compute());
-
-if (outcome.acquired) {
-  console.log(outcome.value);   // typed
-} else {
-  console.log("someone else is running");
-}
-```
-
-## Recipes
-
-### Cron on only one server
-
-```ts
-cron.daily("3am", () =>
-  cache.lock("lock.cleanup", "30m", () => db.cleanup()),
-);
-```
-
-### Idempotent webhook
-
-```ts
-app.post("/webhooks/stripe", async (req, res) => {
-  const outcome = await cache.lock(
-    `webhook.stripe.${req.body.id}`,
-    "24h",
-    () => processStripeEvent(req.body),
-  );
-
-  if (!outcome.acquired) {
-    return res.status(200).json({ status: "already-processed" });
-  }
-
-  res.status(200).json({ status: "processed" });
-});
-```
-
-### Batch job with debug-friendly owner
-
-```ts
-await cache.lock(
-  `lock.report.${date}`,
-  { ttl: "1h", owner: `worker.${process.env.HOSTNAME}` },
-  () => generateReport(date),
-);
-```
-
-`await cache.get("lock.report.2026-04-24")` reveals which worker holds the lock.
-
-## Driver behavior
-
-| Driver | Cross-process safe? |
-|--------|:-:|
-| `redis` | ✅ Native `SET … NX EX` |
-| `memory` / `memoryExtended` / `lru` | ❌ In-process only |
-| `file` | ⚠️ Single-host only (races across hosts) |
-| `null` | n/a — always "acquires" |
-
-## Gotchas
-
-- **Non-re-entrant in v1.** A recursive call for the same key gets `{ acquired: false }`.
-- **Don't release inside `fn`.** `lock()` handles release in `finally`. Manual `cache.remove(lockKey)` inside `fn` would let another process jump in mid-work.
-- **TTL shorter than `fn` runtime = race.** Pick a TTL with generous margin.
-- **Cross-server requires Redis.** Memory / LRU drivers don't coordinate across processes.
-
-
-## use-cache-namespace  `@warlock.js/cache/use-cache-namespace/SKILL.md`
-
----
-name: use-cache-namespace
-description: "Scoped caches — cache.namespace(prefix, options?) in @warlock.js/cache; use when you need to use cache namespace."
----
-
-# Scoped caches — `cache.namespace(prefix, options?)`
-
-When you'll touch the same prefix more than a couple of times, grab a scoped handle instead of repeating the prefix at every call site.
-
-## Shape
-
-```ts
-const chat = cache.namespace(`chats.${id}`, { ttl: "30d", tags: [`user.${userId}`] });
-
-await chat.set("messages.10", msg);          // chats.<id>.messages.10, 30d, user.<userId>
-await chat.set("draft", d, { ttl: "1h" });   // per-call ttl wins
-await chat.tags(["unread"]).set("ping", p);  // tags merge: user.<userId> + unread
-await chat.clear();                           // sugar for removeNamespace
-```
-
-Scopes are pure views — same connection, same driver, no extra state. Per-call options always win over scope defaults; tags merge additively.
-
-## Nested scopes
-
-```ts
-const chat = cache.namespace(`chats.${id}`, { ttl: "30d" });
-const typing = chat.namespace("typing", { ttl: "5s" });  // overrides parent ttl
-
-await typing.set("user.42", true);                       // chats.<id>.typing.user.42, 5s
-```
-
-Nested scopes inherit defaults and can override. Tags accumulate.
-
-## When to reach for it
-
-- The prefix repeats more than 2–3 times.
-- A whole prefix shares a TTL or tag policy.
-- You want `.clear()` to read like the intent ("clear this chat") instead of `removeNamespace(...)` boilerplate.
-
-Inline prefixes are still fine for one-off writes.
-
-## Plain `removeNamespace` when you already have the prefix
-
-When you *do* know the prefix string and don't need a scoped handle for repeated reads/writes:
-
-```ts
-await cache.set("user:1:profile", profile);
-await cache.set("user:1:prefs",   prefs);
-await cache.set("user:2:profile", otherProfile);
-
-await cache.removeNamespace("user.1");  // drops both user:1 entries, keeps user:2
-```
-
-Cheaper than tags (no reverse index to maintain). Every real driver supports it — memory family and `lru` by prefix-scan, `file` by directory (including dotted sibling keys like `ns.a`), `redis` by non-blocking `SCAN` (not `KEYS`), `pg` by key/`LIKE` prefix; `null` no-ops. Namespace strings are treated as data, not glob/path input — see [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) for the file-path-containment and redis-glob-escaping details.
-
-## Multi-tenant scoping at the driver level
-
-Instead of every call passing a tenant prefix, attach `globalPrefix` to the driver config — see [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md). Function form runs per call.
-
-```ts
-options: {
-  redis: {
-    url: "...",
-    globalPrefix: () => `tenant-${currentContext.tenantId}`,
-  },
-}
-```
-
-## SWR + namespace
-
-```ts
-const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
-
-await feed.swr(
-  "home",
-  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
-  () => buildHomeFeed(userId),
-);
-// stored at feed.<userId>.home, tagged [user.<userId>, computed]
-```
-
-Note: scope `ttl` defaults are NOT applied to SWR — `freshTtl` / `staleTtl` always come from the call site. See [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md).
-
-## Things NOT to do
-
-- Don't create a `cache.namespace(prefix)` for a single read/write — the boilerplate doesn't pay off until the prefix repeats. Inline `cache.set("prefix.foo", ...)` is fine.
-- Don't expect `cache.namespace(prefix).clear()` to do anything on the `null` driver — `removeNamespace` no-ops there (it caches nothing).
-- Don't mix prefix separators. The convention is `.` (dot) — pick one and stick with it across scopes so nested prefixes compose predictably.
-
-
-## use-cache-similarity  `@warlock.js/cache/use-cache-similarity/SKILL.md`
-
----
-name: use-cache-similarity
-description: "cache.similar() — vector-based retrieval in @warlock.js/cache; use when you need to use cache similarity."
----
-
-# `cache.similar()` — vector-based retrieval
-
-`cache.similar(vector, { topK, threshold?, tags? })` returns stored entries closest to `vector` by cosine similarity, ordered descending by score. Same `set` / `get` model — different lookup function.
-
-## Shape
-
-```ts
-// Index on the way in.
-await cache.set(key, value, { vector: number[], tags?, ttl? });
-
-// Query.
-const hits = await cache.similar<T>(queryVec, {
-  topK: number,        // required
-  threshold?: number,  // [0, 1]; hits below are dropped
-  tags?: string[],     // narrow candidate pool by tag (union)
-});
-// hits: { key: string; value: T; score: number }[]   // score in [0, 1]
-```
-
-## Capability matrix
-
-| Driver | `similar()` |
-|---|---|
-| `memory` / `memoryExtended` / `lru` | ✅ Brute force (O(N)) — dev only past ~10k entries |
-| `pg` *with* `options.pg.vector` | ✅ pgvector + HNSW/IVFFlat index |
-| `pg` *without* `options.pg.vector` | ❌ Throws `CacheUnsupportedError` |
-| `redis` | ❌ Throws (RediSearch on backlog) |
-| `file` | ❌ Throws |
-| `null` | Returns `[]` |
-
-## Always-true facts
-
-1. **Cache is embedding-agnostic.** Caller computes vectors. The cache stores and ranks; it doesn't call out to an embedder.
-2. **Only entries written with `set({ vector })` show up.** A plain `set` adds the entry as KV — invisible to `similar()`.
-3. **Score = cosine similarity** in `[0, 1]` for typical embedding spaces. The `pg` driver computes `1 - (embedding <=> $1::vector)` so the score matches the memory drivers.
-4. **Tag filter narrows the candidate pool *before* ranking** — union semantics (entry must carry at least one of the listed tags).
-5. **Dimension mismatch throws `CacheConfigurationError`** at both `set({ vector })` and `similar()` time. Don't switch embedders without re-indexing.
-6. **TTL + LRU eviction also drop the vector** — expired or evicted entries are invisible to `similar()`.
-
-## Recipes
-
-### Semantic cache for an LLM
-
-```ts
-const queryVec = await embed(prompt);
-const hits = await cache.similar<Answer>(queryVec, { topK: 1, threshold: 0.92 });
-
-if (hits.length > 0) {
-  return hits[0].value;     // skip the LLM call
-}
-
-const answer = await llm.complete(prompt);
-await cache.set(`q.${hash(prompt)}`, answer, {
-  vector: queryVec,
-  ttl: "30d",
-  tags: ["llm-cache"],
-});
-return answer;
-```
-
-### Tag-narrowed RAG
-
-```ts
-const hits = await cache.similar<Doc>(await embed(question), {
-  topK: 5,
-  threshold: 0.7,
-  tags: ["docs", `tenant.${tenantId}`],
-});
-```
-
-### Production swap — same code, different driver
-
-```ts
-// Dev:
-options: { memory: { ttl: "1h" } }
-
-// Prod — same set/similar calls; index now lives in pgvector:
-options: { pg: { client: pool, vector: { dimensions: 1536 } } }
-```
-
-See [`@warlock.js/cache/configure-pg-cache/SKILL.md`](@warlock.js/cache/configure-pg-cache/SKILL.md).
-
-## Things NOT to do
-
-- Don't use `cache.similar()` on a memory driver with 100k+ vectorized entries — it scales O(N) per query. Switch to `pg` with `vector` config.
-- Don't pass an empty array as `vector` — `cosineSimilarity` throws `CacheConfigurationError`.
-- Don't mix vector dimensions in the same driver — re-embed when models change.
-- Don't expect `similar()` to surface a missing vector (`set` without the `vector` option). Plain KV entries stay out of the similarity index.
-- Don't use `topK: 0` or negative — `pg` rejects with `CacheConfigurationError`; memory drivers return `[]` but it's a code smell.
-
-
-## use-cache-tags  `@warlock.js/cache/use-cache-tags/SKILL.md`
-
----
-name: use-cache-tags
-description: "Tag-based invalidation in @warlock.js/cache; use when you need to use cache tags."
----
-
-# Tag-based invalidation
-
-Tags let you invalidate by a label rather than by enumerating every key. Use them when the set of keys to invalidate is not known ahead of time.
-
-## Attach tags on write
-
-```ts
-// Inline — terser when you know the tags up front
-await cache.set("user:1:profile", profile, { tags: ["users", "tenant-42"] });
-await cache.set("user:1:prefs",   prefs,   { tags: ["users", "tenant-42"] });
-
-// Fluent — useful when you already have a tagged handle
-const users = cache.tags(["users"]);
-await users.set("user:1", user);
-await users.set("user:2", otherUser);
-```
-
-## Invalidate
-
-```ts
-// Drop everything tagged "users"
-await cache.tags(["users"]).invalidate();
-
-// Multi-tag — matches either tag (union)
-await cache.tags(["tenant-42"]).invalidate();
-```
-
-Multi-tag is **union** semantics: an entry is invalidated if it carries **at least one** of the listed tags.
-
-## When to reach for tags vs namespaces
-
-| Use case | Reach for |
-| --- | --- |
-| The keys share a known prefix | `cache.removeNamespace("prefix")` ([`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md)) |
-| The keys are spread across prefixes, tied by entity | Tags |
-| Both apply | Tags — more flexible; cheap on most drivers |
-
-Namespaces are cheaper (no reverse index). Tags are more powerful (any key can carry any tag).
-
-## Inline tag semantics
-
-Subsequent `set("user:1", ...)` with **no** `tags` leaves previous associations intact (the tag index still points to the key), but a `set(..., { tags: [...] })` adds to whatever index entries already exist rather than removing old tag bindings. Tag associations are additive at write-time.
-
-## Driver behavior
-
-| Driver | Tag invalidation |
-| --- | :-: |
-| `null` | noop |
-| `memory` / `memoryExtended` / `lru` / `file` | ✓ (reverse index in driver state) |
-| `redis` | ✓ |
-| `pg` | ✓ native via `GIN(tags)` index |
-
-## SWR with tags
-
-```ts
-await cache.swr(
-  `product.${id}`,
-  { freshTtl: "1m", staleTtl: "1h", tags: ["products", `tenant.${tenantId}`] },
-  () => db.products.find(id),
-);
-```
-
-Tags re-apply on every successful refresh — see [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md).
-
-## `cached()` HOF with tags
-
-```ts
-const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
-const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
-
-await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
-```
-
-See [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md).
-
-## Things NOT to do
-
-- Don't tag aggressively. A reverse index per tag is cheap but not free — pick tags that actually correspond to invalidation events.
-- Don't expect tag invalidation to fire events for each affected key. It's a bulk op; the event bus emits one `flushed` or per-key `removed` per driver implementation. Test by reading back, not by counting events.
-- Don't use tags as a query mechanism. Tags drop keys; they don't list them. If you need "give me every user", store an index list separately.
-
-
-## use-cache-update-merge  `@warlock.js/cache/use-cache-update-merge/SKILL.md`
-
----
-name: use-cache-update-merge
-description: "update and merge — atomic read-modify-write in @warlock.js/cache; use when you need to use cache update merge."
----
-
-# `update` and `merge` — atomic read-modify-write
-
-Prefer these over the ad-hoc `get → spread → set` pattern. Each call takes a per-key chain lock so concurrent callers in the same process are serialized end-to-end.
-
-## `update(key, fn, options?)`
-
-Read the current value, pass it to `fn`, write what `fn` returns.
-
-```ts
-// Counter increment
-await cache.update<number>("views", (current) => (current ?? 0) + 1);
-
-// Update nested state with defaults
-await cache.update<UserState>("user:1:state", (current) => ({
-  ...(current ?? defaultState),
-  lastSeenAt: Date.now(),
-}));
-
-// Conditional update — return null to remove
-await cache.update<Session>("session:abc", (current) => {
-  if (!current || current.expired) {
-    return null;          // removes the key
-  }
-  return { ...current, extendedAt: Date.now() };
-});
-```
-
-- `fn` receives `current: T | null`. Missing keys are `null`, not an exception.
-- Returning `null` **removes** the entry.
-- TTL is preserved by default. To reset, pass `{ ttl: "1h" }` as the 3rd arg.
-
-## `merge(key, partial, options?)`
-
-Shallow-merge sugar for the common "update one field" shape:
-
-```ts
-await cache.merge<User>("user:1", { name: "Jane" });
-await cache.merge<User>("user:1", { lastSeenAt: Date.now() }, { ttl: "1h" });
-```
-
-- **Shallow only.** Arrays are replaced wholesale. Nested objects overwrite.
-- Missing key → treats current as `{}`, creates with the partial.
-- Preserves existing TTL unless the options override is passed.
-
-Deep merge is not built in by design — too many edge cases with arrays and nullish values. If you need deep, write a custom `update(key, deepMerge(current, partial))`.
-
-## What you can't do
-
-- No JSONPath / dot-path partial updates (`update(key, "profile.name", "Jane")`). Use the callback form.
-- No file-driver support — both methods throw `CacheUnsupportedError` there. Use memory or redis.
-- No cross-process safety yet on Redis. The chain lock is in-process only. Cross-process safety requires `WATCH`/`MULTI` (tracked in `domains/cache/backlog.md` as a v2.1 follow-up). If two nodes run `update` on the same key simultaneously, last-write-wins.
-
-## Concurrent-in-process correctness
-
-```ts
-await cache.set("counter", 0);
-
-// 10 concurrent increments, all on the same key — all serialize
-await Promise.all(
-  Array.from({ length: 10 }, () =>
-    cache.update<number>("counter", (current) => (current ?? 0) + 1),
-  ),
-);
-
-await cache.get("counter");   // 10 — not a lost-update
-```
-
-The per-key lock map lives on the driver instance and is cleared after each chain link finishes. No leak.
-
-## When to reach for what
-
-| Task | Use |
-| --- | --- |
-| "Add 1 to this counter" | `increment()` (Redis-atomic via `INCRBY`; in-process elsewhere) |
-| "Change one field on a cached object" | `merge()` |
-| "Read-decide-maybe-write, possibly remove" | `update()` |
-| "Only set if missing" | `set(k, v, { onConflict: "create" })` |
-| "Only set if already exists" | `set(k, v, { onConflict: "update" })` |
-| "Read-then-delete atomically" | `pull()` |
+---
+name: use-cache-update-merge
+description: 'Atomic read-modify-write via cache.update(key, fn) (callback receives current) or cache.merge(key, partial) (shallow merge). Per-key chain lock serializes concurrent in-process callers. Triggers: `cache.update`, `cache.merge`, `cache.increment`, `cache.pull`; "atomically update a cached counter", "change one field on a cached object", "avoid get-spread-set race", "serialize concurrent cache writers"; typical import `import { cache } from "@warlock.js/cache"`. Skip: cross-process locking — `@warlock.js/cache/use-cache-lock/SKILL.md`; conditional create/update — `@warlock.js/cache/configure-set-options/SKILL.md`; competing libs `lodash.merge`, raw redis `WATCH`/`MULTI`.'
+---
+
+# `update` and `merge` — atomic read-modify-write
+
+Prefer these over the ad-hoc `get → spread → set` pattern. Each call takes a per-key chain lock so concurrent callers in the same process are serialized end-to-end.
+
+## `update(key, fn, options?)`
+
+Read the current value, pass it to `fn`, write what `fn` returns.
+
+```ts
+// Counter increment
+await cache.update<number>("views", (current) => (current ?? 0) + 1);
+
+// Update nested state with defaults
+await cache.update<UserState>("user:1:state", (current) => ({
+  ...(current ?? defaultState),
+  lastSeenAt: Date.now(),
+}));
+
+// Conditional update — return null to remove
+await cache.update<Session>("session:abc", (current) => {
+  if (!current || current.expired) {
+    return null;          // removes the key
+  }
+  return { ...current, extendedAt: Date.now() };
+});
+```
+
+- `fn` receives `current: T | null`. Missing keys are `null`, not an exception.
+- Returning `null` **removes** the entry.
+- TTL is preserved by default. To reset, pass `{ ttl: "1h" }` as the 3rd arg.
+
+## `merge(key, partial, options?)`
+
+Shallow-merge sugar for the common "update one field" shape:
+
+```ts
+await cache.merge<User>("user:1", { name: "Jane" });
+await cache.merge<User>("user:1", { lastSeenAt: Date.now() }, { ttl: "1h" });
+```
+
+- **Shallow only.** Arrays are replaced wholesale. Nested objects overwrite.
+- Missing key → treats current as `{}`, creates with the partial.
+- Preserves existing TTL unless the options override is passed.
+
+Deep merge is not built in by design — too many edge cases with arrays and nullish values. If you need deep, write a custom `update(key, deepMerge(current, partial))`.
+
+## What you can't do
+
+- No JSONPath / dot-path partial updates (`update(key, "profile.name", "Jane")`). Use the callback form.
+- No file-driver support — both methods throw `CacheUnsupportedError` there. Use memory or redis.
+- No cross-process safety yet on Redis. The chain lock is in-process only. Cross-process safety requires `WATCH`/`MULTI` (tracked in `domains/cache/backlog.md` as a v2.1 follow-up). If two nodes run `update` on the same key simultaneously, last-write-wins.
+
+## Concurrent-in-process correctness
+
+```ts
+await cache.set("counter", 0);
+
+// 10 concurrent increments, all on the same key — all serialize
+await Promise.all(
+  Array.from({ length: 10 }, () =>
+    cache.update<number>("counter", (current) => (current ?? 0) + 1),
+  ),
+);
+
+await cache.get("counter");   // 10 — not a lost-update
+```
+
+The per-key lock map lives on the driver instance and is cleared after each chain link finishes. No leak.
+
+## When to reach for what
+
+| Task | Use |
+| --- | --- |
+| "Add 1 to this counter" | `increment()` (Redis-atomic via `INCRBY`; in-process elsewhere) |
+| "Change one field on a cached object" | `merge()` |
+| "Read-decide-maybe-write, possibly remove" | `update()` |
+| "Only set if missing" | `set(k, v, { onConflict: "create" })` |
+| "Only set if already exists" | `set(k, v, { onConflict: "update" })` |
+| "Read-then-delete atomically" | `pull()` |
 
 
 ## use-cache-utils  `@warlock.js/cache/use-cache-utils/SKILL.md`
 
----
-name: use-cache-utils
-description: "Cache utilities in @warlock.js/cache; use when you need to use cache utils."
----
-
-# Cache utilities
-
-The helpers the drivers are built from, all re-exported from
-`@warlock.js/cache`. You rarely need them at the call site — `cache.set("k", v,
-"1h")` parses the duration for you. They earn their keep when you write a custom
-driver or do cache-adjacent work outside the manager.
-
-## TTL helpers
-
-```ts
-import { parseTtl, expiresAtToTtl, resolveTtl } from "@warlock.js/cache";
-
-parseTtl(3600);        // 3600
-parseTtl("1h");        // 3600  (duration string via `ms`)
-parseTtl(Infinity);    // Infinity (no expiry)
-parseTtl(-5);          // throws CacheConfigurationError
-
-expiresAtToTtl(new Date(Date.now() + 60_000)); // ~60 (absolute → relative seconds)
-expiresAtToTtl(Date.now() - 1000);             // throws — deadline in the past
-
-// caller ttl > expiresAt > fallback; ttl+expiresAt together throws
-resolveTtl("1h", undefined, Infinity);         // 3600
-resolveTtl(undefined, undefined, 1800);        // 1800 (fallback)
-```
-
-## Option normalizers
-
-Coerce the polymorphic 2nd/3rd argument of `set`/`remember` into a uniform shape
-— what `BaseCacheDriver` uses internally:
-
-```ts
-import { normalizeToOptions, normalizeToRememberOptions } from "@warlock.js/cache";
-
-normalizeToOptions(60);                 // { ttl: 60 }
-normalizeToOptions("1h");               // { ttl: "1h" }
-normalizeToOptions({ tags: ["x"] });    // returned as-is
-normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConflict)
-```
-
-## Key + tag helpers
-
-```ts
-import { parseCacheKey, mergeTagSets, injectTags } from "@warlock.js/cache";
-
-parseCacheKey("users:1");                       // "users.1"
-parseCacheKey({ page: 1, q: "John" });          // "page.1.q.John"
-parseCacheKey("user:1", { globalPrefix: "app" }); // "app.user.1"
-
-mergeTagSets(["a", "b"], ["b", "c"]);           // ["a","b","c"] (deduped union)
-mergeTagSets(undefined, undefined);             // undefined
-
-injectTags({ ttl: "1h" }, ["unread"]);          // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
-```
-
-## Vector scoring
-
-```ts
-import { cosineSimilarity } from "@warlock.js/cache";
-
-cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
-cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
-cosineSimilarity([1, 2, 3], [1, 2]);    // throws — dimension mismatch
-```
-
-Powers the brute-force `cache.similar()` on the memory drivers — reach for it
-directly only when scoring vectors outside the cache.
-
-## TTL constants — `CACHE_FOR`
-
-```ts
-import { cache, CACHE_FOR } from "@warlock.js/cache";
-
-await cache.set("report", data, CACHE_FOR.ONE_WEEK);
-```
-
-Members: `HALF_HOUR`, `ONE_HOUR`, `HALF_DAY`, `ONE_DAY`, `ONE_WEEK`,
-`HALF_MONTH`, `ONE_MONTH`, `TWO_MONTHS`, `SIX_MONTHS`, `ONE_YEAR` (all seconds).
-For most call sites the duration string (`"1h"`, `"7d"`) reads better.
-
-## See also
-
-- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — the high-level `set` options these normalize
-- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — `cache.similar()`, which uses `cosineSimilarity`
-- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — building a custom driver where these help
+---
+name: use-cache-utils
+description: 'Low-level cache utilities re-exported from @warlock.js/cache — parseTtl, expiresAtToTtl, resolveTtl, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, mergeTagSets, injectTags, cosineSimilarity, and the CACHE_FOR TTL enum. Triggers: `parseTtl`, `parseCacheKey`, `resolveTtl`, `expiresAtToTtl`, `cosineSimilarity`, `mergeTagSets`, `injectTags`, `CACHE_FOR`; "parse a duration to seconds", "build a cache key from an object", "score two vectors", "common TTL constant"; typical import `import { parseTtl, CACHE_FOR } from "@warlock.js/cache"`. Skip: building a whole custom driver — `@warlock.js/cache/pick-cache-driver/SKILL.md`; the high-level set API — `@warlock.js/cache/configure-set-options/SKILL.md`.'
+---
+
+# Cache utilities
+
+The helpers the drivers are built from, all re-exported from
+`@warlock.js/cache`. You rarely need them at the call site — `cache.set("k", v,
+"1h")` parses the duration for you. They earn their keep when you write a custom
+driver or do cache-adjacent work outside the manager.
+
+## TTL helpers
+
+```ts
+import { parseTtl, expiresAtToTtl, resolveTtl } from "@warlock.js/cache";
+
+parseTtl(3600);        // 3600
+parseTtl("1h");        // 3600  (duration string via `ms`)
+parseTtl(Infinity);    // Infinity (no expiry)
+parseTtl(-5);          // throws CacheConfigurationError
+
+expiresAtToTtl(new Date(Date.now() + 60_000)); // ~60 (absolute → relative seconds)
+expiresAtToTtl(Date.now() - 1000);             // throws — deadline in the past
+
+// caller ttl > expiresAt > fallback; ttl+expiresAt together throws
+resolveTtl("1h", undefined, Infinity);         // 3600
+resolveTtl(undefined, undefined, 1800);        // 1800 (fallback)
+```
+
+## Option normalizers
+
+Coerce the polymorphic 2nd/3rd argument of `set`/`remember` into a uniform shape
+— what `BaseCacheDriver` uses internally:
+
+```ts
+import { normalizeToOptions, normalizeToRememberOptions } from "@warlock.js/cache";
+
+normalizeToOptions(60);                 // { ttl: 60 }
+normalizeToOptions("1h");               // { ttl: "1h" }
+normalizeToOptions({ tags: ["x"] });    // returned as-is
+normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConflict)
+```
+
+## Key + tag helpers
+
+```ts
+import { parseCacheKey, mergeTagSets, injectTags } from "@warlock.js/cache";
+
+parseCacheKey("users:1");                       // "users.1"
+parseCacheKey({ page: 1, q: "John" });          // "page.1.q.John"
+parseCacheKey("user:1", { globalPrefix: "app" }); // "app.user.1"
+
+mergeTagSets(["a", "b"], ["b", "c"]);           // ["a","b","c"] (deduped union)
+mergeTagSets(undefined, undefined);             // undefined
+
+injectTags({ ttl: "1h" }, ["unread"]);          // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
+```
+
+## Vector scoring
+
+```ts
+import { cosineSimilarity } from "@warlock.js/cache";
+
+cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
+cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
+cosineSimilarity([1, 2, 3], [1, 2]);    // throws — dimension mismatch
+```
+
+Powers the brute-force `cache.similar()` on the memory drivers — reach for it
+directly only when scoring vectors outside the cache.
+
+## TTL constants — `CACHE_FOR`
+
+```ts
+import { cache, CACHE_FOR } from "@warlock.js/cache";
+
+await cache.set("report", data, CACHE_FOR.ONE_WEEK);
+```
+
+Members: `HALF_HOUR`, `ONE_HOUR`, `HALF_DAY`, `ONE_DAY`, `ONE_WEEK`,
+`HALF_MONTH`, `ONE_MONTH`, `TWO_MONTHS`, `SIX_MONTHS`, `ONE_YEAR` (all seconds).
+For most call sites the duration string (`"1h"`, `"7d"`) reads better.
+
+## See also
+
+- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — the high-level `set` options these normalize
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — `cache.similar()`, which uses `cosineSimilarity`
+- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — building a custom driver where these help
 
 
 ## use-cached-hof  `@warlock.js/cache/use-cached-hof/SKILL.md`
 
----
-name: use-cached-hof
-description: "cached() — function-memoization wrapper in @warlock.js/cache; use when you need to use cached hof."
----
-
-# `cached()` — function-memoization wrapper
-
-`cached()` turns any async function into a memoized version. One declaration, many call sites, with a bound `.invalidate()` helper.
-
-## When to use
-
-Reach for `cached()` instead of `cache.remember()` when:
-- You have a function you'll call from many places.
-- You want the caching strategy declared once, not repeated at every call site.
-- You want `.invalidate()` available without manually deriving keys.
-
-Stick with `cache.remember()` for one-shot "get-or-compute" calls.
-
-## The three shapes — `fn` always first
-
-```ts
-import { cached } from "@warlock.js/cache";
-
-// 1. Prefix shorthand — driver default TTL; key auto-derived from args
-cached(fn, "user");
-
-// 2. Prefix + TTL
-cached(fn, "user", "1h");
-
-// 3. Options form — custom key fn, tags, per-call driver
-cached(fn, {
-  key: (id: number) => `user.${id}`,
-  ttl: "1h",
-  tags: ["users"],
-  driver: "redis",
-});
-```
-
-## Auto-key rules (shorthand only)
-
+---
+name: use-cached-hof
+description: 'Wrap an async function with cached(fn, options) — declare the caching strategy once, call from many sites, get a bound .invalidate(...args) helper. Triggers: `cached`, `invalidate`, `key`, `ttl`, `tags`, `driver`; "wrap a DB lookup with caching", "memoize a function and invalidate by args", "one declaration many call sites", "auto-derive cache key from args"; typical import `import { cached } from "@warlock.js/cache"`. Skip: one-shot memoization — `@warlock.js/cache/apply-cache-patterns/SKILL.md` (`cache.remember`); tag bulk drop — `@warlock.js/cache/use-cache-tags/SKILL.md`; competing libs `p-memoize`, `mem`, `lodash.memoize`.'
+---
+
+# `cached()` — function-memoization wrapper
+
+`cached()` turns any async function into a memoized version. One declaration, many call sites, with a bound `.invalidate()` helper.
+
+## When to use
+
+Reach for `cached()` instead of `cache.remember()` when:
+- You have a function you'll call from many places.
+- You want the caching strategy declared once, not repeated at every call site.
+- You want `.invalidate()` available without manually deriving keys.
+
+Stick with `cache.remember()` for one-shot "get-or-compute" calls.
+
+## The three shapes — `fn` always first
+
+```ts
+import { cached } from "@warlock.js/cache";
+
+// 1. Prefix shorthand — driver default TTL; key auto-derived from args
+cached(fn, "user");
+
+// 2. Prefix + TTL
+cached(fn, "user", "1h");
+
+// 3. Options form — custom key fn, tags, per-call driver
+cached(fn, {
+  key: (id: number) => `user.${id}`,
+  ttl: "1h",
+  tags: ["users"],
+  driver: "redis",
+});
+```
+
+## Auto-key rules (shorthand only)
+
 | Args | Key |
 |------|-----|
 | None | `prefix` |
-| All primitives (incl. `null` / `undefined` / `bigint`) | `prefix.` + args joined with dots |
-| Any object / array arg | `prefix.` + `JSON.stringify(args)` |
-| Unserializable (circular / `BigInt` nested in object) | throws `CacheConfigurationError` |
-
-Footguns: order matters (`fn(1, 2)` and `fn(2, 1)` differ), `Date` → ISO string, `Map` / `Set` → `{}` (use the options form). When auto-key fails, use the options form with a custom `key` fn.
-
-## Return shape
-
-```ts
-type CachedFn<Args, R> = ((...args: Args) => Promise<R>) & {
-  invalidate(...args: Args): Promise<void>;
-};
-```
-
-`.refresh()` and `.peek()` are deferred to v2.1 — file demand in `backlog.md` if you need them.
-
-## Recipes
-
-### Cached DB lookup with write-side invalidation
-
-```ts
-const getUser = cached((id: number) => db.users.find(id), "user", "1h");
-
-// On update
-await db.users.update(42, patch);
-await getUser.invalidate(42);
-```
-
-### Tag-based bulk invalidation across wrappers
-
-```ts
-const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
-const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
-
-await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
-```
-
-See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md).
-
-### Project a subset of args into the key
-
-```ts
-const getCategoryMeta = cached(
-  (filters: Filters) => db.categories.meta(filters.category),
-  { key: (f) => `category.meta.${f.category}`, ttl: "1h" },   // ignores `sort`, `page`
-);
-```
-
-## Interaction with the rest of the API
-
-- Uses `cache.remember()` internally → inherits stampede protection within a single Node process.
-- Forwards `tags` and `driver` through the (extended) `RememberOptions` shape on `remember`.
-- `.invalidate()` calls `cache.remove()` — no side effects beyond the single entry.
-
-## Things NOT to do
-
-- Don't wrap a function that has non-JSON-serializable args with the shorthand form. Use the options form and project a stable subset into the key.
-- Don't rely on cross-process stampede safety. `cached` inherits `remember`'s in-process lock; cross-process needs a distributed lock via `onConflict: "create"`.
-- Don't include secrets in args — they'd land in cache keys. Project only the identifying fields into the key.
+| Any args | `prefix.<16 hex>` — sha1 of a stable JSON encoding of the args, truncated |
+| `Map` / `Set` / function / symbol / class instance / circular | throws `CacheConfigurationError` |
+
+The hash keeps distinct args on distinct keys (`("1.private", "")` ≠ `("1", "private")`). Object keys are sorted; `Date` → ISO string; order of args matters. Never build keys by hand: call `.invalidate(...args)`, which honours `config.driver`. When auto-key fails, use the options form with a custom `key` fn.
+
+**Upgrade (5.20):** the key format changed from dot-joined args, so old entries are never read and every call misses once.
+
+## Return shape
+
+```ts
+type CachedFn<Args, R> = ((...args: Args) => Promise<R>) & {
+  invalidate(...args: Args): Promise<void>;
+};
+```
+
+`.refresh()` and `.peek()` are deferred to v2.1 — file demand in `backlog.md` if you need them.
+
+## Recipes
+
+### Cached DB lookup with write-side invalidation
+
+```ts
+const getUser = cached((id: number) => db.users.find(id), "user", "1h");
+
+// On update
+await db.users.update(42, patch);
+await getUser.invalidate(42);
+```
+
+### Tag-based bulk invalidation across wrappers
+
+```ts
+const getUser = cached(fn, { key: (id) => `user.${id}`, ttl: "1h", tags: ["users"] });
+const getPosts = cached(fn, { key: (u) => `posts.by.${u}`, ttl: "30m", tags: ["users", "posts"] });
+
+await cache.tags(["users"]).invalidate();   // drops both wrappers' caches
+```
+
+See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md).
+
+### Project a subset of args into the key
+
+```ts
+const getCategoryMeta = cached(
+  (filters: Filters) => db.categories.meta(filters.category),
+  { key: (f) => `category.meta.${f.category}`, ttl: "1h" },   // ignores `sort`, `page`
+);
+```
+
+## Interaction with the rest of the API
+
+- Uses `cache.remember()` internally → inherits stampede protection within a single Node process.
+- Forwards `tags` and `driver` through the (extended) `RememberOptions` shape on `remember`.
+- `.invalidate()` calls `cache.remove()` — no side effects beyond the single entry.
+
+## Things NOT to do
+
+- Don't wrap a function whose args include `Map`, `Set` or class instances with the shorthand form (it throws). Use the options form and project a stable subset into the key.
+- Don't rely on cross-process stampede safety. `cached` inherits `remember`'s in-process lock; cross-process needs a distributed lock via `onConflict: "create"`.
+- Don't include secrets in args — they'd land in cache keys. Project only the identifying fields into the key.
 
 
 ## use-swr  `@warlock.js/cache/use-swr/SKILL.md`
 
----
-name: use-swr
-description: "Stale-while-revalidate — cache.swr(key, options, fn) in @warlock.js/cache; use when you need to use swr."
----
-
-# Stale-while-revalidate — `cache.swr(key, options, fn)`
-
-Returns the cached value immediately when it can; refreshes in the background when the value is getting old; only blocks when the entry is fully expired. The single biggest production-reliability win in the package — every cache miss past `freshTtl` becomes invisible to callers.
-
-## When to reach for it
-
-Use `cache.swr()` when **slightly-stale data is acceptable** and **the upstream is slow / occasionally fails**. That's most product-detail pages, dashboards, third-party API responses, expensive aggregations.
-
-Use `cache.remember()` when freshness is non-negotiable — auth, balances, billing, anything where the user must see the latest. Remember blocks every miss; SWR doesn't. See [`@warlock.js/cache/apply-cache-patterns/SKILL.md`](@warlock.js/cache/apply-cache-patterns/SKILL.md).
-
-## Three windows
-
-```
-   write              freshTtl              staleTtl
-     │                    │                    │
-     ▼                    ▼                    ▼
-─────┬──── fresh ─────────┬──── stale ─────────┬──── expired ──→
-     │  return cached     │  return cached +   │  block, refetch
-     │  no upstream call  │  bg refresh        │  like a miss
-```
-
-| Window | Behavior |
-|---|---|
-| `now < freshTtl` | Return cached. No upstream call. |
-| `freshTtl ≤ now < staleTtl` | Return cached immediately. Run `fn()` in background; next read sees the refreshed value. |
-| `now ≥ staleTtl` | Block on `fn()`. Same as `remember()`. |
-
-## API
-
-```ts
-await cache.swr(
-  "product.42",
-  {
-    freshTtl: "1m",          // CacheTtl — within this, no upstream call
-    staleTtl: "1h",          // CacheTtl — past this, block-and-refetch
-    tags?: string[],         // applied on first miss + every successful refresh
-    driver?: string,         // per-call driver override, like remember()
-  },
-  () => db.products.find(42),
-);
-```
-
-`staleTtl` MUST be greater than `freshTtl` — otherwise throws.
-
-## Key invariants
-
-1. **Concurrent stale-window callers share one refresh.** Per-key dedupe via the driver's existing locks map — no thundering herd on background refresh.
-2. **Failed background refreshes preserve the stale entry.** No retry storm; the next stale-window read tries again. Failures emit `error` events for observability.
-3. **The caller never sees a refresh failure.** If you returned the stale value, you got your data — failures only show up via `cache.on("error", ...)`. See [`@warlock.js/cache/observe-cache/SKILL.md`](@warlock.js/cache/observe-cache/SKILL.md).
-4. **Tags compose.** Per-call tags + scope tags (when via `cache.namespace().swr(...)`) merge additively.
-5. **Scope `ttl` defaults are NOT applied to SWR.** `freshTtl` / `staleTtl` always come from the call site.
-
-## Driver support
-
-| Driver | Background refresh |
-|---|---|
-| memory / memoryExtended / lru / file / mock | ✅ Full |
-| redis | ✅ Full (sidecar key for staleAt — backwards-compatible) |
-| pg | ✅ Full (`stale_at TIMESTAMPTZ` column — provision via `driver.schema()`) |
-| null | ❌ Always-fetch (null caches nothing) |
-
-## Common shapes
-
-```ts
-// Product detail — slightly stale OK, never want to block on DB
-await cache.swr(`product.${id}`, { freshTtl: "1m", staleTtl: "1h" }, () =>
-  db.products.findById(id),
-);
-
-// Dashboard — expensive aggregation, OK to be 5min stale
-await cache.swr(`dashboard.${tenantId}`, { freshTtl: "5m", staleTtl: "1h" }, () =>
-  computeKPIs(tenantId),
-);
-
-// Third-party API — degrade gracefully when upstream is down
-await cache.swr("exchange.rates", { freshTtl: "10m", staleTtl: "24h" }, () =>
-  fetchFromForexAPI(),
-);
-```
-
-## Through scoped caches
-
-```ts
-const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
-
-await feed.swr(
-  "home",
-  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
-  () => buildHomeFeed(userId),
-);
-// stored at feed.<userId>.home, tagged [user.<userId>, computed]
-```
-
-## Things NOT to do
-
-- Don't use SWR when the user must see the latest data (auth, billing). Use `remember()` instead — block-until-fresh is the right semantic there.
-- Don't pick `freshTtl` to be the *same* as `staleTtl` thinking it disables the stale window — that throws. Pick a tight `freshTtl` and wider `staleTtl` that reflects how stale your product can tolerate being.
-- Don't ignore `error` events. A persistent stream of refresh failures means upstream is broken and the cache is masking it.
-- Don't reach for SWR on the null driver — it caches nothing, so SWR always blocks.
+---
+name: use-swr
+description: 'Stale-while-revalidate via cache.swr(key, {freshTtl, staleTtl}, fn) — returns cached instantly when fresh, returns cached + background refresh when stale, blocks only when fully expired. Triggers: `cache.swr`, `freshTtl`, `staleTtl`, `tags`, `driver`, `stale_at`; "serve stale while refreshing", "degrade when upstream is down", "never block on cache miss"; typical import `import { cache } from "@warlock.js/cache"`. Skip: block-until-fresh memoization — `@warlock.js/cache/apply-cache-patterns/SKILL.md`; observing refresh failures — `@warlock.js/cache/observe-cache/SKILL.md`; competing libs `swr` (React, client-side).'
+---
+
+# Stale-while-revalidate — `cache.swr(key, options, fn)`
+
+Returns the cached value immediately when it can; refreshes in the background when the value is getting old; only blocks when the entry is fully expired. The single biggest production-reliability win in the package — every cache miss past `freshTtl` becomes invisible to callers.
+
+## When to reach for it
+
+Use `cache.swr()` when **slightly-stale data is acceptable** and **the upstream is slow / occasionally fails**. That's most product-detail pages, dashboards, third-party API responses, expensive aggregations.
+
+Use `cache.remember()` when freshness is non-negotiable — auth, balances, billing, anything where the user must see the latest. Remember blocks every miss; SWR doesn't. See [`@warlock.js/cache/apply-cache-patterns/SKILL.md`](@warlock.js/cache/apply-cache-patterns/SKILL.md).
+
+## Three windows
+
+```
+   write              freshTtl              staleTtl
+     │                    │                    │
+     ▼                    ▼                    ▼
+─────┬──── fresh ─────────┬──── stale ─────────┬──── expired ──→
+     │  return cached     │  return cached +   │  block, refetch
+     │  no upstream call  │  bg refresh        │  like a miss
+```
+
+| Window | Behavior |
+|---|---|
+| `now < freshTtl` | Return cached. No upstream call. |
+| `freshTtl ≤ now < staleTtl` | Return cached immediately. Run `fn()` in background; next read sees the refreshed value. |
+| `now ≥ staleTtl` | Block on `fn()`. Same as `remember()`. |
+
+## API
+
+```ts
+await cache.swr(
+  "product.42",
+  {
+    freshTtl: "1m",          // CacheTtl — within this, no upstream call
+    staleTtl: "1h",          // CacheTtl — past this, block-and-refetch
+    tags?: string[],         // applied on first miss + every successful refresh
+    driver?: string,         // per-call driver override, like remember()
+  },
+  () => db.products.find(42),
+);
+```
+
+`staleTtl` MUST be greater than `freshTtl` — otherwise throws.
+
+## Key invariants
+
+1. **Concurrent stale-window callers share one refresh.** Per-key dedupe via the driver's existing locks map — no thundering herd on background refresh.
+2. **Failed background refreshes preserve the stale entry.** No retry storm; the next stale-window read tries again. Failures emit `error` events for observability.
+3. **The caller never sees a refresh failure.** If you returned the stale value, you got your data — failures only show up via `cache.on("error", ...)`. See [`@warlock.js/cache/observe-cache/SKILL.md`](@warlock.js/cache/observe-cache/SKILL.md).
+4. **Tags compose.** Per-call tags + scope tags (when via `cache.namespace().swr(...)`) merge additively.
+5. **Scope `ttl` defaults are NOT applied to SWR.** `freshTtl` / `staleTtl` always come from the call site.
+
+## Driver support
+
+| Driver | Background refresh |
+|---|---|
+| memory / memoryExtended / lru / file / mock | ✅ Full |
+| redis | ✅ Full (sidecar key for staleAt — backwards-compatible) |
+| pg | ✅ Full (`stale_at TIMESTAMPTZ` column — provision via `driver.schema()`) |
+| null | ❌ Always-fetch (null caches nothing) |
+
+## Common shapes
+
+```ts
+// Product detail — slightly stale OK, never want to block on DB
+await cache.swr(`product.${id}`, { freshTtl: "1m", staleTtl: "1h" }, () =>
+  db.products.findById(id),
+);
+
+// Dashboard — expensive aggregation, OK to be 5min stale
+await cache.swr(`dashboard.${tenantId}`, { freshTtl: "5m", staleTtl: "1h" }, () =>
+  computeKPIs(tenantId),
+);
+
+// Third-party API — degrade gracefully when upstream is down
+await cache.swr("exchange.rates", { freshTtl: "10m", staleTtl: "24h" }, () =>
+  fetchFromForexAPI(),
+);
+```
+
+## Through scoped caches
+
+```ts
+const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
+
+await feed.swr(
+  "home",
+  { freshTtl: "30s", staleTtl: "10m", tags: ["computed"] },
+  () => buildHomeFeed(userId),
+);
+// stored at feed.<userId>.home, tagged [user.<userId>, computed]
+```
+
+## Things NOT to do
+
+- Don't use SWR when the user must see the latest data (auth, billing). Use `remember()` instead — block-until-fresh is the right semantic there.
+- Don't pick `freshTtl` to be the *same* as `staleTtl` thinking it disables the stale window — that throws. Pick a tight `freshTtl` and wider `staleTtl` that reflects how stale your product can tolerate being.
+- Don't ignore `error` events. A persistent stream of refresh failures means upstream is broken and the cache is masking it.
+- Don't reach for SWR on the null driver — it caches nothing, so SWR always blocks.