@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/cache/json-lossy-check.ts

@@ -0,0 +1,69 @@
+import { logLossyCacheValue } from '../server/logger.ts';
+
+const LOSSY_TYPES = ['Date', 'Map', 'Set', 'BigInt'] as const;
+
+let hasWarned = false;
+
+/**
+ * Dev-mode warning when a cache value contains types that lose fidelity
+ * through JSON round-trip. Only runs in development — no-op in production.
+ *
+ * Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).
+ * Emits once per process to avoid log spam.
+ */
+export function warnLossyJsonValue(value: unknown, cacheKey: string): void {
+  if (hasWarned) return;
+  if (process.env.NODE_ENV === 'production') return;
+
+  const lossy = findLossyTypes(value, new Set(), 0);
+  if (lossy.size === 0) return;
+
+  hasWarned = true;
+  logLossyCacheValue({ cacheKey, types: [...lossy].join(', ') });
+}
+
+function findLossyTypes(value: unknown, seen: Set<unknown>, depth: number): Set<string> {
+  const lossy = new Set<string>();
+  if (depth > 8 || value === null || value === undefined) return lossy;
+  if (typeof value === 'bigint') {
+    lossy.add('BigInt');
+    return lossy;
+  }
+  if (typeof value !== 'object' && typeof value !== 'function') return lossy;
+  if (seen.has(value)) return lossy;
+  seen.add(value);
+
+  if (value instanceof Date) {
+    lossy.add('Date');
+    return lossy;
+  }
+  if (value instanceof Map) {
+    lossy.add('Map');
+    return lossy;
+  }
+  if (value instanceof Set) {
+    lossy.add('Set');
+    return lossy;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      for (const t of findLossyTypes(item, seen, depth + 1)) lossy.add(t);
+      if (lossy.size === LOSSY_TYPES.length) return lossy;
+    }
+    return lossy;
+  }
+
+  for (const k of Object.keys(value as Record<string, unknown>)) {
+    for (const t of findLossyTypes((value as Record<string, unknown>)[k], seen, depth + 1)) {
+      lossy.add(t);
+    }
+    if (lossy.size === LOSSY_TYPES.length) return lossy;
+  }
+  return lossy;
+}
+
+/** Reset warning state — for tests only. */
+export function _resetLossyWarning(): void {
+  hasWarned = false;
+}

package/src/cache/redis-handler.ts

@@ -1,16 +1,132 @@
-import type { CacheHandler } from './index';
+import type { CacheHandler } from './index.ts';
+import { warnLossyJsonValue } from './json-lossy-check.ts';
 
 /**
- * Minimal Redis client interface — compatible with ioredis, node-redis, and
- * Cloudflare Workers Redis bindings. We depend on the interface, not the
- * implementation, so users bring their own Redis client.
+ * Minimal Redis client contract for `RedisCacheHandler`.
+ *
+ * This is deliberately NOT the native shape of any client library. ioredis,
+ * node-redis v4, and @upstash/redis all disagree on TTL argument shapes
+ * (positional `'EX'` vs `{ EX }` vs `{ ex }`), method casing (`sadd` vs
+ * `sAdd`), and array handling in `del` — a contract that pattern-matches one
+ * client lets another silently drop the expiry (TIM-1030: node-redis ignored
+ * the positional `'EX'` and wrote keys with no TTL). Instead, TTL semantics
+ * are explicit in the signature and you adapt your client with a thin
+ * wrapper, so a mismatch is a type error rather than silent unbounded
+ * keyspace growth.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   srem: (k, ...m) => redis.srem(k, ...m),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ *   execMulti: async (ops) => {
+ *     const p = redis.multi();
+ *     for (const op of ops) {
+ *       switch (op.op) {
+ *         case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+ *         case 'sadd': p.sadd(op.key, ...op.members); break;
+ *         case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+ *         case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+ *         case 'del': p.del(op.key); break;
+ *       }
+ *     }
+ *     await p.exec();
+ *   },
+ * };
+ * ```
+ *
+ * @example node-redis v4
+ * ```ts
+ * import { createClient } from 'redis';
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   srem: (k, ...m) => redis.sRem(k, m),
+ *   smembers: (k) => redis.sMembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * // automaticDeserialization must be off: the handler stores JSON strings
+ * // and parses them itself — auto-parsing would hand back objects.
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
  */
+export type RedisWriteOp =
+  | { op: 'set'; key: string; value: string; ttlSeconds: number }
+  | { op: 'sadd'; key: string; members: string[] }
+  | { op: 'expireNX'; key: string; seconds: number }
+  | { op: 'expireGT'; key: string; seconds: number }
+  | { op: 'del'; key: string };
+
 export interface RedisClient {
+  /** `GET key` — the stored string, or null when absent. */
   get(key: string): Promise<string | null>;
-  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
-  del(key: string | string[]): Promise<number>;
-  sadd(key: string, ...members: string[]): Promise<number>;
+  /**
+   * `SET key value EX ttlSeconds` — store with an expiry. The TTL is a
+   * required positional argument so no adapter can forget it.
+   */
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds NX` — set the TTL only if the key has no existing
+   * expiry (Redis 7.0+). Used to set the initial TTL on new tag sets.
+   */
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds GT` — update the TTL only if the new value is greater
+   * than the current one (Redis 7.0+). Used to extend tag set TTLs without
+   * allowing a short-TTL writer to shrink them.
+   */
+  expireGT(key: string, seconds: number): Promise<unknown>;
+  /** `DEL key` — delete a single key. Multi-key deletes loop per key. */
+  del(key: string): Promise<unknown>;
+  /** `SADD key member [member ...]` — add members to a set. */
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  /** `SREM key member [member ...]` — remove members from a set. */
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  /** `SMEMBERS key` — all members of a set. */
   smembers(key: string): Promise<string[]>;
+  /**
+   * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does
+   * not exist, -1 if the key exists but has no expiry.
+   */
+  ttl(key: string): Promise<number>;
+  /**
+   * Execute a batch of write operations atomically via `MULTI/EXEC`.
+   * When provided, `set()` uses this to make tag-index writes and the data
+   * write atomic — no `invalidate({tag})` can interleave. Optional: when
+   * absent, operations run sequentially (correct but not race-free).
+   */
+  execMulti?(ops: RedisWriteOp[]): Promise<void>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -23,8 +139,9 @@ const TAG_PREFIX = 'timber:tag:';
  * invalidations. Tag-based invalidation uses Redis Sets to track which keys
  * belong to which tags.
  *
- * Bring your own Redis client — any client implementing the RedisClient
- * interface works (ioredis, node-redis, @upstash/redis, etc.).
+ * Bring your own Redis client wrapped to the {@link RedisClient} contract —
+ * see the adapter examples on the interface for ioredis, node-redis v4, and
+ * @upstash/redis.
  */
 export class RedisCacheHandler implements CacheHandler {
   private client: RedisClient;
@@ -52,26 +169,71 @@ export class RedisCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
+    warnLossyJsonValue(value, key);
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
-    const payload = JSON.stringify({ value, expiresAt });
+
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
+    const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
     // on stale entries. The logical staleness is determined by expiresAt.
     // We use 2x TTL + 60s as the Redis expiry so stale entries remain
     // available for SWR background refetches.
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-    await this.client.set(ck, payload, 'EX', redisTtlSeconds);
 
-    // Track key membership in each tag set
+    const writeOps: RedisWriteOp[] = [];
     for (const tag of opts.tags) {
-      await this.client.sadd(this.tagKey(tag), key);
+      writeOps.push({ op: 'sadd', key: this.tagKey(tag), members: [key] });
+      writeOps.push({ op: 'expireNX', key: this.tagKey(tag), seconds: redisTtlSeconds });
+      writeOps.push({ op: 'expireGT', key: this.tagKey(tag), seconds: redisTtlSeconds });
+    }
+    writeOps.push({ op: 'set', key: ck, value: payload, ttlSeconds: redisTtlSeconds });
+
+    if (this.client.execMulti) {
+      await this.client.execMulti(writeOps);
+    } else {
+      for (const op of writeOps) {
+        await this.execOp(op);
+      }
+    }
+  }
+
+  private async execOp(op: RedisWriteOp): Promise<void> {
+    switch (op.op) {
+      case 'set':
+        await this.client.set(op.key, op.value, op.ttlSeconds);
+        break;
+      case 'sadd':
+        await this.client.sadd(op.key, ...op.members);
+        break;
+      case 'expireNX':
+        await this.client.expireNX(op.key, op.seconds);
+        break;
+      case 'expireGT':
+        await this.client.expireGT(op.key, op.seconds);
+        break;
+      case 'del':
+        await this.client.del(op.key);
+        break;
     }
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
     if (opts.key) {
+      const raw = await this.client.get(this.cacheKey(opts.key));
+      if (raw !== null) {
+        const entry = JSON.parse(raw) as { tags?: string[] };
+        if (entry.tags) {
+          await Promise.all(entry.tags.map((tag) => this.client.srem(this.tagKey(tag), opts.key!)));
+        }
+      }
       await this.client.del(this.cacheKey(opts.key));
     }
 
@@ -79,13 +241,29 @@ export class RedisCacheHandler implements CacheHandler {
       const tk = this.tagKey(opts.tag);
       const keys = await this.client.smembers(tk);
 
-      if (keys.length > 0) {
-        const cacheKeys = keys.map((k) => this.cacheKey(k));
-        await this.client.del(cacheKeys);
-      }
+      // Re-check each member before deleting — the tag set can contain stale
+      // memberships from entries whose tags changed since they were added.
+      // Mirrors TagAwareCacheHandler's eager strategy (tag-aware-handler.ts:183-198).
+      await Promise.all(
+        keys.map(async (k) => {
+          const raw = await this.client.get(this.cacheKey(k));
+          if (raw === null) {
+            await this.client.srem(tk, k);
+            return;
+          }
+          const entry = JSON.parse(raw) as { tags?: string[] };
+          if (entry.tags?.includes(opts.tag!)) {
+            await this.client.del(this.cacheKey(k));
+          }
+          await this.client.srem(tk, k);
+        })
+      );
 
-      // Clean up the tag set itself
-      await this.client.del(tk);
+      // Clean up the now-empty tag set so it doesn't consume memory
+      const remaining = await this.client.smembers(tk);
+      if (remaining.length === 0) {
+        await this.client.del(tk);
+      }
     }
   }
 }

package/src/cache/singleflight.ts

@@ -3,24 +3,90 @@
  * execution. All callers receive the same result (or error).
  *
  * Per-process, in-memory. Each process coalesces independently.
+ *
+ * An optional `timeoutMs` prevents hung `fn()` calls from permanently
+ * blocking all future callers for that key. When set, `fn()` is raced
+ * against a timeout — if the timeout fires first, the promise rejects
+ * with `SingleflightTimeoutError`, `finally` cleans up the key, and
+ * subsequent callers can retry. See TIM-518.
  */
+
+export interface SingleflightOptions {
+  /** Maximum time (ms) a coalesced call may run before being rejected. */
+  timeoutMs?: number;
+}
+
 export interface Singleflight {
-  do<T>(key: string, fn: () => Promise<T>): Promise<T>;
+  do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+  /** Return the in-flight promise for a key, or undefined if none. */
+  get(key: string): Promise<unknown> | undefined;
+}
+
+/**
+ * Error thrown when a singleflight call exceeds `timeoutMs`.
+ * Exported so callers can distinguish timeout from other errors.
+ */
+export class SingleflightTimeoutError extends Error {
+  constructor(key: string, timeoutMs: number) {
+    super(`Singleflight timeout: key "${key}" exceeded ${timeoutMs}ms`);
+    this.name = 'SingleflightTimeoutError';
+  }
 }
 
-export function createSingleflight(): Singleflight {
+export function createSingleflight(opts?: SingleflightOptions): Singleflight {
   const inflight = new Map<string, Promise<unknown>>();
+  const timeoutMs = opts?.timeoutMs;
 
   return {
-    do<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T> {
       const existing = inflight.get(key);
       if (existing) return existing as Promise<T>;
 
-      const promise = fn().finally(() => {
+      const ac = new AbortController();
+      let promise: Promise<T>;
+
+      if (timeoutMs != null && timeoutMs > 0) {
+        // Race fn() against a timeout to prevent hung calls from
+        // permanently blocking the key. See TIM-518.
+        // Abort the signal on timeout so the callback can skip
+        // side effects (e.g. cache writes). See TIM-1092.
+        promise = new Promise<T>((resolve, reject) => {
+          const timer = setTimeout(() => {
+            // The timeout error is also the signal's reason, so the body
+            // can tell why it was aborted (runBackgroundFlight reports it).
+            const timeout = new SingleflightTimeoutError(key, timeoutMs);
+            ac.abort(timeout);
+            reject(timeout);
+          }, timeoutMs);
+          try {
+            fn(ac.signal).then(
+              (value) => {
+                clearTimeout(timer);
+                resolve(value);
+              },
+              (err) => {
+                clearTimeout(timer);
+                reject(err);
+              }
+            );
+          } catch (err) {
+            clearTimeout(timer);
+            reject(err);
+          }
+        });
+      } else {
+        promise = fn(ac.signal);
+      }
+
+      const tracked = promise.finally(() => {
         inflight.delete(key);
       });
-      inflight.set(key, promise);
-      return promise;
+
+      inflight.set(key, tracked);
+      return tracked as Promise<T>;
+    },
+    get(key: string): Promise<unknown> | undefined {
+      return inflight.get(key);
     },
   };
 }

package/src/cache/sizeof.ts

@@ -0,0 +1,35 @@
+/**
+ * Lightweight byte-size estimation for cache entries.
+ *
+ * Estimates the in-memory byte cost of a JavaScript value using
+ * JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+ * approximation — it doesn't account for V8 object overhead, Map
+ * metadata, or non-serializable values — but it's fast and good
+ * enough for cache budget enforcement.
+ *
+ * Values that fail JSON serialization (circular references, BigInt,
+ * etc.) return 0, allowing the entry to be cached without counting
+ * toward the byte budget. This is a conservative choice: it's better
+ * to cache and undercount than to reject the entry.
+ */
+
+import { swallow } from '../server/logger.ts';
+
+/**
+ * Estimate the byte size of a value.
+ *
+ * Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+ * in-memory size. Returns 0 if the value is not serializable.
+ */
+export function estimateByteSize(value: unknown): number {
+  try {
+    const json = JSON.stringify(value);
+    if (json === undefined) return 0;
+    // Each JS string character is 2 bytes (UTF-16)
+    return json.length * 2;
+  } catch (e) {
+    // Circular reference or non-serializable value
+    swallow(e, 'sizeof estimation failed', { level: 'debug' });
+    return 0;
+  }
+}

package/src/cache/stable-stringify.ts

@@ -2,20 +2,83 @@
  * Deterministic JSON serialization with sorted object keys.
  * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
  * produce the same string.
+ *
+ * Matches JSON.stringify semantics for toJSON: Date serializes to its ISO
+ * string, URL to its href, and class instances with a custom toJSON use it.
+ * Map and Set serialize their entries explicitly (insertion-order
+ * independent). Values that would serialize lossily — functions, symbols,
+ * and non-plain objects with no enumerable own state (RegExp, class
+ * instances holding data behind getters or internal slots) — throw instead:
+ * every such value would collapse to the same cache key, silently returning
+ * one argument's cached data for another (TIM-1020).
  */
 export function stableStringify(value: unknown): string {
-  if (value === null || value === undefined) return JSON.stringify(value);
-  if (typeof value !== 'object') return JSON.stringify(value);
+  if (value === null || value === undefined) return String(value);
+
+  const type = typeof value;
+  if (type === 'function' || type === 'symbol') {
+    throw new TypeError(
+      `stableStringify: cannot serialize a ${type} into a stable cache key — ` +
+        'all such values would collide. Provide an explicit `key` option to cache().'
+    );
+  }
+  if (type !== 'object') return JSON.stringify(value);
+
   if (Array.isArray(value)) {
     return '[' + value.map((item) => stableStringify(item)).join(',') + ']';
   }
 
+  // Honor toJSON like JSON.stringify does (Date → ISO string, URL → href,
+  // custom class serialization). JSON.stringify does not re-invoke toJSON
+  // on the value it returns, so a toJSON that returns `this` falls through
+  // to plain own-property serialization instead of recursing forever.
+  const withToJSON = value as { toJSON?: () => unknown };
+  if (typeof withToJSON.toJSON === 'function') {
+    const json = withToJSON.toJSON();
+    if (json !== value) return stableStringify(json);
+  }
+
+  // Map/Set have no enumerable own properties — serialize entries explicitly.
+  // Entries are sorted after serialization so insertion order doesn't change
+  // the key. The Map(/Set( prefixes can't collide with object ('{'), array
+  // ('['), or string ('"') output.
+  if (value instanceof Map) {
+    const entries = [...value.entries()].map(
+      ([k, v]) => stableStringify(k) + '=>' + stableStringify(v)
+    );
+    return 'Map(' + entries.sort().join(',') + ')';
+  }
+  if (value instanceof Set) {
+    const members = [...value].map((member) => stableStringify(member));
+    return 'Set(' + members.sort().join(',') + ')';
+  }
+
   const obj = value as Record<string, unknown>;
   const keys = Object.keys(obj).sort();
   const pairs: string[] = [];
   for (const key of keys) {
     if (obj[key] === undefined) continue;
+    // A callable own toJSON only reaches this loop via the returns-`this`
+    // fall-through above. It's the serialization protocol, not data —
+    // JSON.stringify omits it too.
+    if (key === 'toJSON' && typeof obj[key] === 'function') continue;
     pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));
   }
+
+  // A non-plain object that serializes to '{}' carries its state behind
+  // getters or internal slots (RegExp, sessions, ORM entities). Serializing
+  // it would give every instance the same cache key.
+  if (pairs.length === 0) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      const name = (value as object).constructor?.name || 'Object';
+      throw new TypeError(
+        `stableStringify: ${name} instance has no serializable own state — ` +
+          'all instances would share one cache key. Provide an explicit `key` ' +
+          'option to cache(), or add a toJSON() method.'
+      );
+    }
+  }
+
   return '{' + pairs.join(',') + '}';
 }

package/src/cache/store.ts

@@ -0,0 +1,71 @@
+/**
+ * CacheStore — the contract cache backends implement.
+ *
+ * Three tiers of tag capability, auto-detected by TagAwareCacheHandler:
+ *
+ * 1. **Native tags** (store implements setWithTags + invalidateTag): The store
+ *    handles tag indexing and invalidation internally. The handler delegates
+ *    directly. Examples: Vercel Runtime Cache, Durable Object–backed stores.
+ *
+ * 2. **Set primitives** (store implements sadd/smembers/srem/sdel): The handler
+ *    maintains an inverted index using the store's atomic set operations.
+ *    Eager invalidation — enumerate and delete. Example: Redis.
+ *
+ * 3. **Bare KV** (only get/set/del): The handler uses version-stamping. Entries
+ *    record tag versions at write time; reads validate against current versions.
+ *    Invalidation bumps a counter — O(1), race-free. Example: Cloudflare KV.
+ *
+ * Implementors pick their tier by which methods they provide. The handler
+ * selects the best available strategy automatically.
+ */
+
+export interface CacheStore {
+  // --- Required: every store must implement these ---
+
+  /** Read a key. Returns null if absent or physically expired. */
+  get(key: string): Promise<string | null>;
+
+  /** Write a key with a physical TTL in seconds. Overwrites if exists. */
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+
+  /** Delete a key. No-op if absent. */
+  del(key: string): Promise<void>;
+
+  // --- Tier 1: Native tag support ---
+  // If implemented, the handler delegates tag operations entirely to the store.
+
+  /**
+   * Write a value with associated tags. The store handles tag indexing
+   * internally. If provided, the handler will call this instead of plain
+   * set() for tagged entries.
+   */
+  setWithTags?(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void>;
+
+  /**
+   * Invalidate all entries associated with a tag. The store handles
+   * the lookup and deletion/marking internally.
+   */
+  invalidateTag?(tag: string): Promise<void>;
+
+  // --- Tier 2: Set primitives (enables eager inverted-index strategy) ---
+
+  /**
+   * Atomically add members to a named set and ensure the set has at least
+   * the given TTL.
+   */
+  sadd?(key: string, members: string[], ttlSeconds: number): Promise<void>;
+
+  /** Remove members from a named set. */
+  srem?(key: string, members: string[]): Promise<void>;
+
+  /** Return all members of a named set. */
+  smembers?(key: string): Promise<string[]>;
+
+  /** Delete a named set entirely. */
+  sdel?(key: string): Promise<void>;
+
+  // --- Metadata ---
+
+  /** Consistency model — used for framework build diagnostics. */
+  readonly consistency: 'strong' | 'eventual' | 'local';
+}

package/src/cache/stores/cloudflare-kv.ts

@@ -0,0 +1,52 @@
+/**
+ * Cloudflare Workers KV CacheStore — eventually-consistent, no set operations.
+ *
+ * The TagAwareCacheHandler uses the lazy (version-stamp) strategy for this
+ * store: tag invalidation bumps a version counter (O(1) write), and reads
+ * validate stored tag versions against current. No enumeration, no
+ * read-modify-write races, correct under eventual consistency.
+ *
+ * Consistency: KV propagates writes in ~60s. A tag version bump propagates
+ * like any other write — during the window, some reads may still validate
+ * against the old version and serve stale data. This is acceptable for KV's
+ * consistency model (use short TTLs for security-critical invalidation).
+ */
+
+import type { CacheStore } from '../store.ts';
+
+export interface CloudflareKVNamespace {
+  get(key: string, options?: { type?: string }): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export class CloudflareKVStore implements CacheStore {
+  private kv: CloudflareKVNamespace | (() => CloudflareKVNamespace);
+  readonly consistency = 'eventual' as const;
+
+  /**
+   * @param kv - Either a KVNamespace instance or a factory function that
+   * resolves it from the current request context (for Workers where bindings
+   * are per-request).
+   */
+  constructor(kv: CloudflareKVNamespace | (() => CloudflareKVNamespace)) {
+    this.kv = kv;
+  }
+
+  private getKV(): CloudflareKVNamespace {
+    return typeof this.kv === 'function' ? this.kv() : this.kv;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.getKV().get(key);
+  }
+
+  async set(key: string, value: string, ttlSeconds: number): Promise<void> {
+    // KV expirationTtl minimum is 60s
+    await this.getKV().put(key, value, { expirationTtl: Math.max(ttlSeconds, 60) });
+  }
+
+  async del(key: string): Promise<void> {
+    await this.getKV().delete(key);
+  }
+}