@warlock.js/cache 5.19.0 → 5.20.0

package/llms.txt

@@ -6,23 +6,23 @@
 
 ## Skills
 
-- [apply-cache-patterns](@warlock.js/cache/apply-cache-patterns/SKILL.md): Real-world caching patterns in @warlock.js/cache; use when you need to apply cache patterns.
+- [apply-cache-patterns](@warlock.js/cache/apply-cache-patterns/SKILL.md): (no description)
 - [cache-basics](@warlock.js/cache/cache-basics/SKILL.md): Start here for @warlock.js/cache drivers, key-value operations, and application cache configuration.
-- [configure-pg-cache](@warlock.js/cache/configure-pg-cache/SKILL.md): pg cache driver — Postgres setup in @warlock.js/cache; use when you need to configure pg cache.
-- [configure-set-options](@warlock.js/cache/configure-set-options/SKILL.md): The set options object in @warlock.js/cache; use when you need to configure set options.
-- [handle-cache-errors](@warlock.js/cache/handle-cache-errors/SKILL.md): Error classes in @warlock.js/cache; use when you need to handle cache errors.
-- [observe-cache](@warlock.js/cache/observe-cache/SKILL.md): Cache observability — cache.metrics() and the event bus in @warlock.js/cache; use when you need to observe cache.
+- [configure-pg-cache](@warlock.js/cache/configure-pg-cache/SKILL.md): Postgres cache driver setup — KV-only mode (default) or pgvector mode (opt in via options.pg.vector). Caller owns the pg.Pool, driver exposes driver.schema() for one-time DDL. Triggers: `PgCacheDriver`, `driver.schema`, `options.pg.vector`, `pg.Pool`, `hnsw`, `ivfflat`; "use Postgres as cache backend", "set up pgvector semantic cache", "DDL for warlock cache table"; typical import `import { cache, PgCacheDriver } from "@warlock.js/cache"`. Skip: cross-driver similarity API — `@warlock.js/cache/use-cache-similarity/SKILL.md`; driver picker — `@warlock.js/cache/pick-cache-driver/SKILL.md`; competing libs `pg-mem`; raw `pg` / `node-postgres`.
+- [configure-set-options](@warlock.js/cache/configure-set-options/SKILL.md): (no description)
+- [handle-cache-errors](@warlock.js/cache/handle-cache-errors/SKILL.md): (no description)
+- [observe-cache](@warlock.js/cache/observe-cache/SKILL.md): (no description)
 - [overview](@warlock.js/cache/overview/SKILL.md): @warlock.js/cache overview for orientation and choosing the focused skill for the task.
-- [pick-cache-driver](@warlock.js/cache/pick-cache-driver/SKILL.md): Cache drivers — pick the right one in @warlock.js/cache; use when you need to choose cache driver.
-- [test-cache-code](@warlock.js/cache/test-cache-code/SKILL.md): Testing code that touches cache in @warlock.js/cache; use when you need to test cache code.
-- [use-cache-atomic](@warlock.js/cache/use-cache-atomic/SKILL.md): Atomic counters — cache.increment / cache.decrement in @warlock.js/cache; use when you need to use cache atomic.
-- [use-cache-bulk](@warlock.js/cache/use-cache-bulk/SKILL.md): Bulk operations — cache.many / cache.setMany in @warlock.js/cache; use when you need to use cache bulk.
-- [use-cache-list](@warlock.js/cache/use-cache-list/SKILL.md): Lists — the cache.list<T>(key) sub-API in @warlock.js/cache; use when you need to use cache list.
-- [use-cache-lock](@warlock.js/cache/use-cache-lock/SKILL.md): cache.lock() — distributed locks with auto-release in @warlock.js/cache; use when you need to use cache lock.
-- [use-cache-namespace](@warlock.js/cache/use-cache-namespace/SKILL.md): Scoped caches — cache.namespace(prefix, options?) in @warlock.js/cache; use when you need to use cache namespace.
-- [use-cache-similarity](@warlock.js/cache/use-cache-similarity/SKILL.md): cache.similar() — vector-based retrieval in @warlock.js/cache; use when you need to use cache similarity.
-- [use-cache-tags](@warlock.js/cache/use-cache-tags/SKILL.md): Tag-based invalidation in @warlock.js/cache; use when you need to use cache tags.
-- [use-cache-update-merge](@warlock.js/cache/use-cache-update-merge/SKILL.md): update and merge — atomic read-modify-write in @warlock.js/cache; use when you need to use cache update merge.
-- [use-cache-utils](@warlock.js/cache/use-cache-utils/SKILL.md): Cache utilities in @warlock.js/cache; use when you need to use cache utils.
-- [use-cached-hof](@warlock.js/cache/use-cached-hof/SKILL.md): cached() — function-memoization wrapper in @warlock.js/cache; use when you need to use cached hof.
-- [use-swr](@warlock.js/cache/use-swr/SKILL.md): Stale-while-revalidate — cache.swr(key, options, fn) in @warlock.js/cache; use when you need to use swr.
+- [pick-cache-driver](@warlock.js/cache/pick-cache-driver/SKILL.md): (no description)
+- [test-cache-code](@warlock.js/cache/test-cache-code/SKILL.md): (no description)
+- [use-cache-atomic](@warlock.js/cache/use-cache-atomic/SKILL.md): (no description)
+- [use-cache-bulk](@warlock.js/cache/use-cache-bulk/SKILL.md): (no description)
+- [use-cache-list](@warlock.js/cache/use-cache-list/SKILL.md): (no description)
+- [use-cache-lock](@warlock.js/cache/use-cache-lock/SKILL.md): (no description)
+- [use-cache-namespace](@warlock.js/cache/use-cache-namespace/SKILL.md): (no description)
+- [use-cache-similarity](@warlock.js/cache/use-cache-similarity/SKILL.md): (no description)
+- [use-cache-tags](@warlock.js/cache/use-cache-tags/SKILL.md): 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`.
+- [use-cache-update-merge](@warlock.js/cache/use-cache-update-merge/SKILL.md): (no description)
+- [use-cache-utils](@warlock.js/cache/use-cache-utils/SKILL.md): (no description)
+- [use-cached-hof](@warlock.js/cache/use-cached-hof/SKILL.md): (no description)
+- [use-swr](@warlock.js/cache/use-swr/SKILL.md): (no description)

package/package.json

@@ -5,9 +5,9 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/fs": "5.19.0",
-    "@mongez/reinforcements": "^4.0.1",
-    "@warlock.js/logger": "5.19.0",
+    "@warlock.js/fs": "5.20.0",
+    "@mongez/reinforcements": "^4.0.2",
+    "@warlock.js/logger": "5.20.0",
     "ms": "^2.1.3"
   },
   "peerDependencies": {
@@ -46,7 +46,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.19.0",
+  "version": "5.20.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/apply-cache-patterns/SKILL.md

@@ -1,97 +1,98 @@
----
-name: apply-cache-patterns
-description: "Real-world caching patterns in @warlock.js/cache; use when you need to apply cache patterns."
----
-
-# Real-world caching patterns
-
-Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
-
-## Memoize an expensive function — `remember`
-
-```ts
-const user = await cache.remember(`user:${id}`, "1h", async () => {
-  return db.users.find(id);   // runs only on cache miss
-});
-```
-
-- The callback runs once per miss.
-- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
-- `null` is the universal miss sentinel. `remember` short-circuits on a **truthy** cached value (`if (cachedValue) return cachedValue;`), so a stored `null` reads back as a miss and the callback **re-runs on every call** — you get no caching at all, plus a wasted write each time. To actually cache a "not found," store a truthy sentinel instead (see negative caching below).
-
-## Cross-process stampede protection — distributed lock via `onConflict`
-
-`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
-
-```ts
-const lockKey = `lock:build-report:${reportId}`;
-const acquired = await cache.set(lockKey, process.pid, {
-  onConflict: "create",
-  ttl: "2m",
-});
-
-if (!acquired.wasSet) {
-  // another node is already building — wait or skip
-  return cache.get(`report:${reportId}`);
-}
-
-try {
-  const report = await buildExpensiveReport(reportId);
-  await cache.set(`report:${reportId}`, report, "1h");
-  return report;
-} finally {
-  await cache.remove(lockKey);
-}
-```
-
-This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
-
-## Negative caching
-
-Cache "not found" results with a shorter TTL to avoid hammering the origin:
-
-```ts
-const user = await cache.remember(`user:${id}`, "5m", async () => {
-  const found = await db.users.find(id);
-  return found ?? { __miss: true };
-});
-
-if (user?.__miss) {
-  return null;
-}
-```
-
-Don't return raw `null` inside `remember` to "cache the miss" — it won't. `remember`'s truthy guard treats a stored `null` as a miss, so the callback re-runs every time and the origin still gets hammered. The truthy `{ __miss: true }` sentinel is what actually skips the next call.
-
-## Per-tenant caching
-
-```ts
-// In cache config:
-options: {
-  redis: {
-    url: "...",
-    globalPrefix: () => `tenant-${currentContext.tenantId}`,
-  },
-}
-
-// At the call site — no tenancy awareness needed:
-await cache.set("user:1", user, "1h");
-// Actual key: "tenant-42.user.1"
-```
-
-Clear a tenant out:
-```ts
-await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
-// or
-await cache.tags([`tenant-${tenantId}`]).invalidate();
-```
-
-## See also
-
-- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
-- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
-- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
-- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
-- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
-- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
-- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization
+---
+name: apply-cache-patterns
+description: 'Compose cache primitives into real-world patterns — remember() memoization, cross-node stampede protection via a distributed lock (onConflict: ''create''), negative caching, and per-tenant scoping. Triggers: `cache.remember`, `cache.set` with `onConflict: "create"`, `globalPrefix`; "memoize this function", "prevent cache stampede across nodes", "cache not-found results", "per-tenant cache scoping"; typical import `import { cache } from "@warlock.js/cache"`. Skip: counters — `@warlock.js/cache/use-cache-atomic/SKILL.md`; bulk get/set — `@warlock.js/cache/use-cache-bulk/SKILL.md`; TTL constants/utilities — `@warlock.js/cache/use-cache-utils/SKILL.md`; named lock wrapper — `@warlock.js/cache/use-cache-lock/SKILL.md`; SWR — `@warlock.js/cache/use-swr/SKILL.md`; competing libs `lru-cache`, `node-cache`, `keyv`.'
+---
+
+# Real-world caching patterns
+
+Common shapes — the "general patterns" file. Specialized topics have dedicated skills: [`use-cache-tags`](@warlock.js/cache/use-cache-tags/SKILL.md), [`use-cache-namespace`](@warlock.js/cache/use-cache-namespace/SKILL.md), [`use-swr`](@warlock.js/cache/use-swr/SKILL.md), [`use-cache-lock`](@warlock.js/cache/use-cache-lock/SKILL.md), [`use-cache-list`](@warlock.js/cache/use-cache-list/SKILL.md).
+
+## Memoize an expensive function — `remember`
+
+```ts
+const user = await cache.remember(`user:${id}`, "1h", async () => {
+  return db.users.find(id);   // runs only on cache miss
+});
+```
+
+- The callback runs once per miss.
+- Concurrent callers for the same key share the in-flight promise (stampede protection) — within one Node process.
+- `null` is the only miss. `0`, `false` and `""` are cached like any other value, so `remember` doesn't recompute them. A callback returning `null` is not cached, so the callback re-runs on the next call: to cache a "not found," store a sentinel (see negative caching below).
+- Stampede protection is per process, even on redis. To run something once across servers, wrap it in `cache.lock()` on `redis` or `pg`.
+
+## Cross-process stampede protection — distributed lock via `onConflict`
+
+`remember`'s lock is per-process. For cross-node safety, acquire a short-lived distributed lock before doing expensive work:
+
+```ts
+const lockKey = `lock:build-report:${reportId}`;
+const acquired = await cache.set(lockKey, process.pid, {
+  onConflict: "create",
+  ttl: "2m",
+});
+
+if (!acquired.wasSet) {
+  // another node is already building — wait or skip
+  return cache.get(`report:${reportId}`);
+}
+
+try {
+  const report = await buildExpensiveReport(reportId);
+  await cache.set(`report:${reportId}`, report, "1h");
+  return report;
+} finally {
+  await cache.remove(lockKey);
+}
+```
+
+This requires a driver with atomic `SET NX` — Redis is native, memory/LRU/file emulate (single-process only). For a higher-level wrapper that does the lock-and-release for you, see [`@warlock.js/cache/use-cache-lock/SKILL.md`](@warlock.js/cache/use-cache-lock/SKILL.md).
+
+## Negative caching
+
+Cache "not found" results with a shorter TTL to avoid hammering the origin:
+
+```ts
+const user = await cache.remember(`user:${id}`, "5m", async () => {
+  const found = await db.users.find(id);
+  return found ?? { __miss: true };
+});
+
+if (user?.__miss) {
+  return null;
+}
+```
+
+Don't return raw `null` inside `remember` to "cache the miss": `null` is the miss sentinel, so the callback re-runs every time and the origin still gets hammered. The `{ __miss: true }` sentinel is what skips the next call.
+
+## Per-tenant caching
+
+```ts
+// In cache config:
+options: {
+  redis: {
+    url: "...",
+    globalPrefix: () => `tenant-${currentContext.tenantId}`,
+  },
+}
+
+// At the call site — no tenancy awareness needed:
+await cache.set("user:1", user, "1h");
+// Actual key: "tenant-42.user.1"
+```
+
+Clear a tenant out:
+```ts
+await cache.removeNamespace("");   // when globalPrefix is set, flush scopes to it
+// or
+await cache.tags([`tenant-${tenantId}`]).invalidate();
+```
+
+## See also
+
+- [`@warlock.js/cache/use-cache-atomic/SKILL.md`](@warlock.js/cache/use-cache-atomic/SKILL.md) — `increment` / `decrement` counters
+- [`@warlock.js/cache/use-cache-bulk/SKILL.md`](@warlock.js/cache/use-cache-bulk/SKILL.md) — `many` / `setMany`
+- [`@warlock.js/cache/use-cache-utils/SKILL.md`](@warlock.js/cache/use-cache-utils/SKILL.md) — `CACHE_FOR` constants and TTL/key helpers
+- [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md) — tag-based invalidation
+- [`@warlock.js/cache/use-cache-namespace/SKILL.md`](@warlock.js/cache/use-cache-namespace/SKILL.md) — scoped handles and `removeNamespace`
+- [`@warlock.js/cache/use-swr/SKILL.md`](@warlock.js/cache/use-swr/SKILL.md) — stale-while-revalidate for slow upstreams
+- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — `cached()` HOF for declarative memoization

package/skills/configure-pg-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configure-pg-cache
-description: "pg cache driver — Postgres setup in @warlock.js/cache; use when you need to configure pg cache."
+description: 'Postgres cache driver setup — KV-only mode (default) or pgvector mode (opt in via options.pg.vector). Caller owns the pg.Pool, driver exposes driver.schema() for one-time DDL. Triggers: `PgCacheDriver`, `driver.schema`, `options.pg.vector`, `pg.Pool`, `hnsw`, `ivfflat`; "use Postgres as cache backend", "set up pgvector semantic cache", "DDL for warlock cache table"; typical import `import { cache, PgCacheDriver } from "@warlock.js/cache"`. Skip: cross-driver similarity API — `@warlock.js/cache/use-cache-similarity/SKILL.md`; driver picker — `@warlock.js/cache/pick-cache-driver/SKILL.md`; competing libs `pg-mem`; raw `pg` / `node-postgres`.'
 ---
 
 # `pg` cache driver — Postgres setup
@@ -13,14 +13,15 @@ Persistent cache backed by your existing Postgres pool. Two modes: **KV-only** (
 2. **`pg` is an optional peer dep.** Lazy-loaded; install only if you use this driver.
 3. **No auto-migration.** Driver exposes `driver.schema()` returning a DDL string — caller runs it via their own migration tool.
 4. **Table name is regex-validated** (`[A-Za-z_][A-Za-z0-9_]*`) before DDL interpolation. No SQL injection via misconfiguration.
-5. **TTL is lazy on read.** `SELECT ... WHERE expires_at IS NULL OR expires_at > now()`. Expired rows aren't auto-deleted unless you GC them yourself.
+5. **TTL is lazy on read.** `SELECT ... WHERE expires_at IS NULL OR expires_at > now()`. Expiry is computed on the DB clock. `driver.prune(limit = 1000)` deletes expired rows in batches and returns the count; `set()` also runs it on about 1 in 200 writes. Call it from a scheduled job for unique-key workloads.
 6. **`onConflict` is race-safe at the SQL layer:**
    - `create` → `INSERT ... ON CONFLICT DO UPDATE WHERE expires_at < now() RETURNING value` (reclaims expired rows; blocks live ones).
    - `update` → `UPDATE ... WHERE expires_at IS NULL OR expires_at > now() RETURNING value`.
    - `upsert` → unconditional `INSERT ... ON CONFLICT DO UPDATE`.
-7. **`stale_at TIMESTAMPTZ` column** powers [stale-while-revalidate](@warlock.js/cache/use-swr/SKILL.md) — `cache.swr(...)` populates it on writes, plain `set()` leaves it null (always-fresh). Provision via `driver.schema()` like any other column.
-8. **pgvector requires `CREATE EXTENSION vector;` once on the database.** Lazy probe on first vector op throws `CacheConfigurationError` if missing; result is cached.
-9. **Vectors are passed as text literals** (`'[1,2,3]'::vector`). No binary protocol dependency — works against any pg client.
+7. **Atomic ops are cross-server:** `increment` is one upsert that keeps `expires_at`, `pull` is `DELETE … RETURNING`, `update` is a compare-and-set with bounded retries (callback may run more than once). Tags use a one-statement JSON-array merge.
+8. **`stale_at TIMESTAMPTZ` column** powers [stale-while-revalidate](@warlock.js/cache/use-swr/SKILL.md) — `cache.swr(...)` populates it on writes, plain `set()` leaves it null (always-fresh). Provision via `driver.schema()` like any other column.
+9. **pgvector requires `CREATE EXTENSION vector;` once on the database.** Lazy probe on first vector op throws `CacheConfigurationError` if missing; result is cached.
+10. **Vectors are passed as text literals** (`'[1,2,3]'::vector`). No binary protocol dependency — works against any pg client.
 
 ## Configuration
 

package/skills/configure-set-options/SKILL.md

@@ -1,96 +1,102 @@
----
-name: configure-set-options
-description: "The set options object in @warlock.js/cache; use when you need to configure set options."
----
-
-# The `set` options object
-
-`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
-
-## The three shapes
-
-```ts
-// 1. Number — seconds
-await cache.set("name", "Jane", 600);
-
-// 2. String — human-readable duration, parsed via `ms`
-await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
-
-// 3. Options object
-await cache.set("user:1", user, {
-  ttl: "1h",
-  expiresAt: new Date("2026-12-31"),
-  tags: ["users"],
-  onConflict: "create",
-  driver: "redis",
-});
-```
-
-## Option keys
-
-| Key | Type | Notes |
-| --- | --- | --- |
-| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
-| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
-| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
-| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
-| `driver` | `string` | Per-call driver override by registered name. |
-| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
-
-## `onConflict` policies
-
-Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
-
-```ts
-// create — set only if key is missing
-const result = await cache.set("lock:jobs:import", workerId, {
-  onConflict: "create",
-  ttl: "5m",
-});
-// result: { wasSet: true, existing: null } on acquire
-//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
-
-if (!result.wasSet) {
-  // another worker is already running; abort.
-}
-
-// update — set only if key exists (don't resurrect expired sessions)
-await cache.set("session:abc", session, { onConflict: "update" });
-```
-
-Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
-
-## Mutually-exclusive validations
-
-Both of these throw `CacheConfigurationError`:
-
-```ts
-await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
-await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
-```
-
-## Inline tags vs `cache.tags([...]).set(...)`
-
-Both work; inline is terser when you're writing one value under known tags:
-
-```ts
-// Inline
-await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
-
-// Fluent (useful when you already have a tagged instance)
-const users = cache.tags(["users"]);
-await users.set("user:1", user);
-await users.invalidate();   // drops every key tagged "users"
-```
-
-Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
-
-## Back-compat note
-
-Every call site using the old positional-TTL shape keeps working:
-
-```ts
-await cache.set("k", v);           // no TTL — driver default
-await cache.set("k", v, 3600);     // seconds
-await cache.set("k", v, undefined); // same as no TTL
-```
+---
+name: configure-set-options
+description: 'Configure cache.set''s third argument — ttl, expiresAt, tags, onConflict (create / update / upsert), driver, vector. Triggers: `cache.set`, `ttl`, `expiresAt`, `tags`, `onConflict`, `driver`, `vector`, `CacheSetResult`, `wasSet`; "set a key only if missing", "set with absolute deadline", "attach tags inline", "route one cache call to redis"; typical import `import { cache } from "@warlock.js/cache"`. Skip: tag fluent API — `@warlock.js/cache/use-cache-tags/SKILL.md`; vector queries — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `keyv`, `ioredis`.'
+---
+
+# The `set` options object
+
+`cache.set(key, value, ttlOrOptions?)` — the 3rd argument accepts three shapes.
+
+## The three shapes
+
+```ts
+// 1. Number — seconds
+await cache.set("name", "Jane", 600);
+
+// 2. String — human-readable duration, parsed via `ms`
+await cache.set("name", "Jane", "10m");   // "1s", "30m", "1h", "7d", "2 weeks"
+
+// 3. Options object
+await cache.set("user:1", user, {
+  ttl: "1h",
+  expiresAt: new Date("2026-12-31"),
+  tags: ["users"],
+  onConflict: "create",
+  driver: "redis",
+});
+```
+
+## Option keys
+
+| Key | Type | Notes |
+| --- | --- | --- |
+| `ttl` | `number \| string` | Relative expiry. Mutually exclusive with `expiresAt`. |
+| `expiresAt` | `number \| Date` | Absolute deadline (epoch ms or Date). Must be in the future. Mutually exclusive with `ttl`. |
+| `tags` | `string[]` | Inline equivalent of `cache.tags([...]).set(...)`. See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md). |
+| `onConflict` | `"create" \| "update" \| "upsert"` | See below. Default `"upsert"`. |
+| `driver` | `string` | Per-call driver override by registered name. |
+| `vector` | `number[]` | Embedding indexed alongside the entry for [`cache.similar()`](@warlock.js/cache/use-cache-similarity/SKILL.md). Drivers without similarity support throw `CacheUnsupportedError`. |
+
+## TTL parsing
+
+- Number or bare numeric string (`"3600"`) = **seconds**. Fractions and sub-second values (`0.5`, `"500ms"`) round **up** to whole seconds, never 0.
+- `0` / `Infinity` = no expiry. `NaN`, negative and unparseable values throw `CacheConfigurationError`.
+- `cache.lock()` refuses any TTL that never expires.
+
+## `onConflict` policies
+
+Self-documenting enum; Redis maps these to `NX` / `XX` natively, others emulate.
+
+```ts
+// create — set only if key is missing
+const result = await cache.set("lock:jobs:import", workerId, {
+  onConflict: "create",
+  ttl: "5m",
+});
+// result: { wasSet: true, existing: null } on acquire
+//         { wasSet: false, existing: <prior workerId> } on conflict — someone else holds the lock
+
+if (!result.wasSet) {
+  // another worker is already running; abort.
+}
+
+// update — set only if key exists (don't resurrect expired sessions)
+await cache.set("session:abc", session, { onConflict: "update" });
+```
+
+Conditional writes (`"create"` / `"update"`) return a `CacheSetResult`; unconditional `"upsert"` returns the value or driver instance as before.
+
+## Mutually-exclusive validations
+
+Both of these throw `CacheConfigurationError`:
+
+```ts
+await cache.set("k", v, { ttl: "1h", expiresAt: Date.now() + 1000 });  // both set
+await cache.set("k", v, { expiresAt: Date.now() - 1000 });              // past deadline
+```
+
+## Inline tags vs `cache.tags([...]).set(...)`
+
+Both work; inline is terser when you're writing one value under known tags:
+
+```ts
+// Inline
+await cache.set("user:1", user, { tags: ["users", "tenant-42"] });
+
+// Fluent (useful when you already have a tagged instance)
+const users = cache.tags(["users"]);
+await users.set("user:1", user);
+await users.invalidate();   // drops every key tagged "users"
+```
+
+Inline tag semantics are **additive**, never replace. A subsequent `set("user:1", ...)` with no `tags` leaves previous associations intact (the tag index still points to the key), and a `set(..., { tags: [...] })` only appends the key to those tags' index entries — it never removes the key from tags it was bound to earlier. To drop stale bindings, invalidate the old tag explicitly via `cache.tags([...]).invalidate()`.
+
+## Back-compat note
+
+Every call site using the old positional-TTL shape keeps working:
+
+```ts
+await cache.set("k", v);           // no TTL — driver default
+await cache.set("k", v, 3600);     // seconds
+await cache.set("k", v, undefined); // same as no TTL
+```