@warlock.js/cache 5.24.0 → 5.26.0

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

@@ -1,94 +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.
+---
+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-update-merge/SKILL.md

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

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

@@ -1,89 +1,89 @@
----
-name: use-cache-utils
-description: 'Low-level cache utilities re-exported from @warlock.js/cache — parseTtl, expiresAtToTtl, resolveTtl, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, mergeTagSets, injectTags, cosineSimilarity, and the CACHE_FOR TTL enum. Triggers: `parseTtl`, `parseCacheKey`, `resolveTtl`, `expiresAtToTtl`, `cosineSimilarity`, `mergeTagSets`, `injectTags`, `CACHE_FOR`; "parse a duration to seconds", "build a cache key from an object", "score two vectors", "common TTL constant"; typical import `import { parseTtl, CACHE_FOR } from "@warlock.js/cache"`. Skip: building a whole custom driver — `@warlock.js/cache/pick-cache-driver/SKILL.md`; the high-level set API — `@warlock.js/cache/configure-set-options/SKILL.md`.'
----
-
-# Cache utilities
-
-The helpers the drivers are built from, all re-exported from
-`@warlock.js/cache`. You rarely need them at the call site — `cache.set("k", v,
-"1h")` parses the duration for you. They earn their keep when you write a custom
-driver or do cache-adjacent work outside the manager.
-
-## TTL helpers
-
-```ts
-import { parseTtl, expiresAtToTtl, resolveTtl } from "@warlock.js/cache";
-
-parseTtl(3600);        // 3600
-parseTtl("1h");        // 3600  (duration string via `ms`)
-parseTtl(Infinity);    // Infinity (no expiry)
-parseTtl(-5);          // throws CacheConfigurationError
-
-expiresAtToTtl(new Date(Date.now() + 60_000)); // ~60 (absolute → relative seconds)
-expiresAtToTtl(Date.now() - 1000);             // throws — deadline in the past
-
-// caller ttl > expiresAt > fallback; ttl+expiresAt together throws
-resolveTtl("1h", undefined, Infinity);         // 3600
-resolveTtl(undefined, undefined, 1800);        // 1800 (fallback)
-```
-
-## Option normalizers
-
-Coerce the polymorphic 2nd/3rd argument of `set`/`remember` into a uniform shape
-— what `BaseCacheDriver` uses internally:
-
-```ts
-import { normalizeToOptions, normalizeToRememberOptions } from "@warlock.js/cache";
-
-normalizeToOptions(60);                 // { ttl: 60 }
-normalizeToOptions("1h");               // { ttl: "1h" }
-normalizeToOptions({ tags: ["x"] });    // returned as-is
-normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConflict)
-```
-
-## Key + tag helpers
-
-```ts
-import { parseCacheKey, mergeTagSets, injectTags } from "@warlock.js/cache";
-
-parseCacheKey("users:1");                       // "users.1"
-parseCacheKey({ page: 1, q: "John" });          // "page.1.q.John"
-parseCacheKey("user:1", { globalPrefix: "app" }); // "app.user.1"
-
-mergeTagSets(["a", "b"], ["b", "c"]);           // ["a","b","c"] (deduped union)
-mergeTagSets(undefined, undefined);             // undefined
-
-injectTags({ ttl: "1h" }, ["unread"]);          // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
-```
-
-## Vector scoring
-
-```ts
-import { cosineSimilarity } from "@warlock.js/cache";
-
-cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
-cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
-cosineSimilarity([1, 2, 3], [1, 2]);    // throws — dimension mismatch
-```
-
-Powers the brute-force `cache.similar()` on the memory drivers — reach for it
-directly only when scoring vectors outside the cache.
-
-## TTL constants — `CACHE_FOR`
-
-```ts
-import { cache, CACHE_FOR } from "@warlock.js/cache";
-
-await cache.set("report", data, CACHE_FOR.ONE_WEEK);
-```
-
-Members: `HALF_HOUR`, `ONE_HOUR`, `HALF_DAY`, `ONE_DAY`, `ONE_WEEK`,
-`HALF_MONTH`, `ONE_MONTH`, `TWO_MONTHS`, `SIX_MONTHS`, `ONE_YEAR` (all seconds).
-For most call sites the duration string (`"1h"`, `"7d"`) reads better.
-
-## See also
-
-- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — the high-level `set` options these normalize
-- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — `cache.similar()`, which uses `cosineSimilarity`
-- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — building a custom driver where these help
+---
+name: use-cache-utils
+description: 'Low-level cache utilities re-exported from @warlock.js/cache — parseTtl, expiresAtToTtl, resolveTtl, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, mergeTagSets, injectTags, cosineSimilarity, and the CACHE_FOR TTL enum. Triggers: `parseTtl`, `parseCacheKey`, `resolveTtl`, `expiresAtToTtl`, `cosineSimilarity`, `mergeTagSets`, `injectTags`, `CACHE_FOR`; "parse a duration to seconds", "build a cache key from an object", "score two vectors", "common TTL constant"; typical import `import { parseTtl, CACHE_FOR } from "@warlock.js/cache"`. Skip: building a whole custom driver — `@warlock.js/cache/pick-cache-driver/SKILL.md`; the high-level set API — `@warlock.js/cache/configure-set-options/SKILL.md`.'
+---
+
+# Cache utilities
+
+The helpers the drivers are built from, all re-exported from
+`@warlock.js/cache`. You rarely need them at the call site — `cache.set("k", v,
+"1h")` parses the duration for you. They earn their keep when you write a custom
+driver or do cache-adjacent work outside the manager.
+
+## TTL helpers
+
+```ts
+import { parseTtl, expiresAtToTtl, resolveTtl } from "@warlock.js/cache";
+
+parseTtl(3600);        // 3600
+parseTtl("1h");        // 3600  (duration string via `ms`)
+parseTtl(Infinity);    // Infinity (no expiry)
+parseTtl(-5);          // throws CacheConfigurationError
+
+expiresAtToTtl(new Date(Date.now() + 60_000)); // ~60 (absolute → relative seconds)
+expiresAtToTtl(Date.now() - 1000);             // throws — deadline in the past
+
+// caller ttl > expiresAt > fallback; ttl+expiresAt together throws
+resolveTtl("1h", undefined, Infinity);         // 3600
+resolveTtl(undefined, undefined, 1800);        // 1800 (fallback)
+```
+
+## Option normalizers
+
+Coerce the polymorphic 2nd/3rd argument of `set`/`remember` into a uniform shape
+— what `BaseCacheDriver` uses internally:
+
+```ts
+import { normalizeToOptions, normalizeToRememberOptions } from "@warlock.js/cache";
+
+normalizeToOptions(60);                 // { ttl: 60 }
+normalizeToOptions("1h");               // { ttl: "1h" }
+normalizeToOptions({ tags: ["x"] });    // returned as-is
+normalizeToRememberOptions("1h");       // { ttl: "1h" }   (no expiresAt/onConflict)
+```
+
+## Key + tag helpers
+
+```ts
+import { parseCacheKey, mergeTagSets, injectTags } from "@warlock.js/cache";
+
+parseCacheKey("users:1");                       // "users.1"
+parseCacheKey({ page: 1, q: "John" });          // "page.1.q.John"
+parseCacheKey("user:1", { globalPrefix: "app" }); // "app.user.1"
+
+mergeTagSets(["a", "b"], ["b", "c"]);           // ["a","b","c"] (deduped union)
+mergeTagSets(undefined, undefined);             // undefined
+
+injectTags({ ttl: "1h" }, ["unread"]);          // { ttl: "1h", tags: ["unread"] } (pure, no mutation)
+```
+
+## Vector scoring
+
+```ts
+import { cosineSimilarity } from "@warlock.js/cache";
+
+cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
+cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
+cosineSimilarity([1, 2, 3], [1, 2]);    // throws — dimension mismatch
+```
+
+Powers the brute-force `cache.similar()` on the memory drivers — reach for it
+directly only when scoring vectors outside the cache.
+
+## TTL constants — `CACHE_FOR`
+
+```ts
+import { cache, CACHE_FOR } from "@warlock.js/cache";
+
+await cache.set("report", data, CACHE_FOR.ONE_WEEK);
+```
+
+Members: `HALF_HOUR`, `ONE_HOUR`, `HALF_DAY`, `ONE_DAY`, `ONE_WEEK`,
+`HALF_MONTH`, `ONE_MONTH`, `TWO_MONTHS`, `SIX_MONTHS`, `ONE_YEAR` (all seconds).
+For most call sites the duration string (`"1h"`, `"7d"`) reads better.
+
+## See also
+
+- [`@warlock.js/cache/configure-set-options/SKILL.md`](@warlock.js/cache/configure-set-options/SKILL.md) — the high-level `set` options these normalize
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — `cache.similar()`, which uses `cosineSimilarity`
+- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](@warlock.js/cache/pick-cache-driver/SKILL.md) — building a custom driver where these help