@warlock.js/cache 5.24.0 → 5.25.0

package/skills/use-cache-list/SKILL.md

@@ -1,85 +1,85 @@
----
-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.
+---
+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.

package/skills/use-cache-lock/SKILL.md

@@ -1,30 +1,30 @@
----
-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);
-```
-
+---
+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`.
@@ -33,81 +33,81 @@ TTL rules: a number or a bare numeric string (`"90"`) is **seconds**; `"500ms"`
 
 - 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? |
-|--------|:-:|
+- 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.
+| `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.

package/skills/use-cache-namespace/SKILL.md

@@ -1,88 +1,88 @@
----
-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.
+---
+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.