@warlock.js/cache 5.19.1 → 5.21.0

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

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

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: use-cache-tags
-description: "Tag-based invalidation in @warlock.js/cache; use when you need to 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`.'
 ---
 
 # Tag-based invalidation
@@ -51,9 +51,12 @@ Subsequent `set("user:1", ...)` with **no** `tags` leaves previous associations
 | Driver | Tag invalidation |
 | --- | :-: |
 | `null` | noop |
-| `memory` / `memoryExtended` / `lru` / `file` | ✓ (reverse index in driver state) |
-| `redis` | ✓ |
-| `pg` | ✓ native via `GIN(tags)` index |
+| `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) |
+
+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.
 
 ## SWR with tags
 

package/skills/use-cache-update-merge/SKILL.md

@@ -1,84 +1,84 @@
----
-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()` |