@warlock.js/cache 5.24.0 → 5.26.0

package/skills/observe-cache/SKILL.md

@@ -1,103 +1,104 @@
----
-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()`.
+---
+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`, `invalidated`, `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", ...)` |
+| See which tag invalidations ran, what they removed and how long they took | `cache.on("invalidated", ({ tags, keys, durationMs }) => ...)` — once per `tags([...]).invalidate()` |
+| 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()`.

package/skills/pick-cache-driver/SKILL.md

@@ -1,129 +1,129 @@
----
-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) |
+---
+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) |
-
+| 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
+## 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