@warlock.js/cache 4.0.171 → 4.1.1

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

@@ -0,0 +1,67 @@
+---
+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
+
+| 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

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

@@ -0,0 +1,57 @@
+---
+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

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

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

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

@@ -0,0 +1,104 @@
+---
+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.** 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.

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

@@ -0,0 +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, `redis`/`pg` by key/`LIKE` prefix; `null` no-ops. See [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md).
+
+## 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

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

@@ -0,0 +1,85 @@
+---
+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`.'
+---
+
+# 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.

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

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