@ultimat3/cache 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -157,6 +157,10 @@ Tier 1. Tagged caching + THE invalidation graph.
   change: a cold shared tier, which the default build-id namespace already pays per deploy.
   Pinned by `tier-parity.test.ts` (all three rungs, one test each) and `redis.live.test.ts` (the
   same two busts against a real server, asserting the LRU's and Redis's survivors are EQUAL).
+  **A row bust does not read the index and still SREMs from it** (`sweepBucketsFor`) — reading it
+  over-reaches, removing a member cannot: only what the bust deleted leaves. Without that, a
+  deleted value key kept its membership in `e:{entity}` for ever while every write renewed that
+  index's lease — the unbounded `SMEMBERS` the lease was added to prevent, rebuilt out of corpses.
 - **`CacheTier.set` REJECTS, never throws synchronously.** `createLruTier` and `createMemoTier` are
   `async` for that reason alone — `LruCache.set` stays a sync API, but a `CacheTier` is one
   interface with three implementations and `tier.set(...).catch(...)` has to mean the same thing on
@@ -212,6 +216,11 @@ Tier 1. Tagged caching + THE invalidation graph.
   options and only `receiveInvalidationBroadcast` passes `false`. An inbound tag this process never
   declared is dropped into `report.errors`, never thrown: a throw kills the subscriber loop and
   silently ends cross-instance invalidation for the whole process.
+- **A `cdn` tier holding `noopPurgeDriver()` reports `skipped`, never keys.** That is the default
+  state of every deployment with no CDN credentials (`selectPurgeDriver`), and the noop ECHOES the
+  keys it is handed — so the tier reported every tag as CLEARED and `busted` listed keys nothing
+  had purged, with `errors: []`. `isNoopPurgeDriver` lives in `cdn.ts`, beside the `name: 'noop'`
+  it tests for, because `createCdnTier` cannot import `purge-env.ts` without a cycle.
 - **`report.cdn` is what depends on the tags; `report.tiers` is what cleared.** The `cdn` tier
   purges `cdn-path` dependents itself, alongside the tags, so `busted` is built from `tiers` +
   `isr` + `liveQueries` and never from `cdn` — folding in a list nothing purged is exactly the

package/README.md

@@ -170,9 +170,12 @@ partial bust while stale rows served until TTL. Value keys are still deleted cli
 each, which is slot-local under every topology.
 
 The script **deletes nothing at all** — not the value keys, and not the buckets either. The tier
-`SREM`s exactly the members whose `DEL` succeeded, so a refused delete keeps its membership and the
-retry the error asks for still finds it; dropping the bucket inside the script made that failure
-permanent. A `set` mirrors it: buckets are joined **before** the value is written and membership is
+`SREM`s exactly the members whose `DEL` succeeded, from every bucket that member joined —
+including, for a row bust, the entity index it deliberately never *reads*. Reading `e:{entity}` for
+a row bust would return every key of the entity; removing from it cannot over-reach, and a member
+left there is a corpse in a set every later write renews the lease on. A refused delete keeps its
+membership and the retry the error asks for still finds it; dropping the bucket inside the script
+made that failure permanent. A `set` mirrors it: buckets are joined **before** the value is written and membership is
 re-checked after, because a bust that landed in between would otherwise leave a row nothing can
 reach by tag, serving until its own lease ran out.
 
@@ -319,6 +322,12 @@ nothing loads that file's contents at runtime:
 | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ZONE_ID` | Cloudflare |
 | neither | nothing is purged, and `x dev` prints `cdn=none` |
 
+A `cdn` tier holding the noop driver answers an invalidation with
+`{ tier: 'cdn', keys: [], skipped: 'no purge driver configured' }` — never a list of keys. The noop
+echoes what it is handed, so reporting its reply as accepted made every tag read as CLEARED in
+`report.tiers` and in `recentInvalidations().busted`, with `errors: []`, in the default state of a
+deployment that has no CDN at all. `isNoopPurgeDriver(driver)` is the same probe, exported.
+
 Both pairs at once is `X_CONFIG_INVALID`: one process purges exactly one edge. Half a pair
 is refused the same way — treating it as "no CDN" is how a deployment ships believing it
 purges. Either refusal names the keys that are actually set, in `cause` and in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0"
+    "@ultimat3/core": "4.1.0"
   }
 }

package/src/cdn.ts

@@ -66,6 +66,15 @@ export function noopPurgeDriver(): PurgeDriver {
   };
 }
 
+/**
+ * A driver that reaches no CDN, so a caller can report "purges nothing" without a name match.
+ *
+ * Lives here rather than beside `selectPurgeDriver`, which is where it was until 2026-08: the
+ * `name: 'noop'` it tests for is declared one function up, and `createCdnTier` — the caller that
+ * most needs it — cannot import from `purge-env.ts` without making a cycle of the two files.
+ */
+export const isNoopPurgeDriver = (driver: PurgeDriver): boolean => driver.name === 'noop';
+
 export interface CdnTierOptions {
   readonly purge?: PurgeDriver;
   /**
@@ -108,6 +117,13 @@ export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
      * `cdn-path` dependent must tag that response with its own path.
      */
     async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
+      // The default state of any deployment with no CDN credentials, and it has to say so: the
+      // noop driver ECHOES its argument, so every tag came back as an accepted purge and
+      // `recentInvalidations().busted` listed keys nothing had cleared, `errors: []`. `skipped`
+      // is the field that already exists for this — a tier that did not run, named as one.
+      if (isNoopPurgeDriver(driver)) {
+        return { tier: 'cdn', keys: [], skipped: 'no purge driver configured' };
+      }
       const keys = [...new Set([...serializeTags(tags), ...dependentsOfKind(tags, 'cdn-path')])];
       if (keys.length === 0) return { tier: 'cdn', keys: [] };
       const accepted = await driver.purge(keys);

package/src/index.ts

@@ -1,7 +1,7 @@
 // Public API of @ultimat3/cache. Explicit, no `export *`.
 
 export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
-export { cacheHeaders, createCdnTier, noopPurgeDriver } from './cdn';
+export { cacheHeaders, createCdnTier, isNoopPurgeDriver, noopPurgeDriver } from './cdn';
 export type { CacheErrorCode } from './errors';
 export {
   CACHE_ERROR_CODES,
@@ -55,7 +55,7 @@ export {
   cloudflarePurgeDriver,
 } from './purge-cloudflare';
 export type { PurgeEnvironment, PurgeSelection } from './purge-env';
-export { CDN_PURGE_ENV_KEYS, isNoopPurgeDriver, selectPurgeDriver } from './purge-env';
+export { CDN_PURGE_ENV_KEYS, selectPurgeDriver } from './purge-env';
 export type { FastlyPurgeOptions } from './purge-fastly';
 export { FASTLY_API_URL, FASTLY_MAX_KEYS_PER_REQUEST, fastlyPurgeDriver } from './purge-fastly';
 export type { PurgeFetch } from './purge-http';

package/src/purge-env.ts

@@ -41,9 +41,6 @@ const nonEmpty = (value: string | undefined): string | undefined =>
 const configuredKeys = (env: PurgeEnvironment): readonly string[] =>
   CDN_PURGE_ENV_KEYS.filter((key) => nonEmpty(env[key]) !== undefined);
 
-/** A driver that reaches no CDN, so a caller can report "purges nothing" without a name match. */
-export const isNoopPurgeDriver = (driver: PurgeDriver): boolean => driver.name === 'noop';
-
 /**
  * Either key selects its provider, and the other is then required: a `FASTLY_SERVICE_ID` with no
  * token is a half-finished deploy, and treating it as "no CDN" is how an environment ships

package/src/redis.ts

@@ -239,6 +239,19 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       ? [entityKey(owned.entity), tagKey(owned)]
       : [tagKey(owned), tagKey({ entity: owned.entity })];
 
+  /**
+   * The buckets a bust CLEANS UP, which is not the set it reads — and the asymmetry is the point.
+   *
+   * A row bust must not READ the entity index: it holds every key of the entity, so the bust would
+   * delete them all. It must still SREM from it. `set` joins the index on every write, so a row
+   * bust that deletes a value key and leaves its membership there leaves a corpse no later bust
+   * can reach — while `TAG_MEMBER_SCRIPT` renews that index's lease on every write, which is the
+   * unbounded `SMEMBERS` the lease exists to prevent, rebuilt out of dead keys. Removing a member
+   * cannot over-reach the way reading one can: only what this bust actually deleted leaves.
+   */
+  const sweepBucketsFor = (owned: CacheTag): string[] =>
+    owned.id === undefined ? [] : [entityKey(owned.entity)];
+
   return {
     name: 'redis',
 
@@ -330,18 +343,18 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
      */
     async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
       const claimed = new Set<string>();
-      const perTag: string[][] = [];
+      const perTag: { read: string[]; sweep: string[] }[] = [];
       for (const owned of tags) {
         // A bucket already claimed by an earlier tag is dropped rather than re-sent: a collection
         // tag and one of its rows overlap, and the second call would read the same members.
-        const buckets = bustBucketsFor(owned).filter((bucket) => !claimed.has(bucket));
-        for (const bucket of buckets) claimed.add(bucket);
-        if (buckets.length > 0) perTag.push(buckets);
+        const read = bustBucketsFor(owned).filter((bucket) => !claimed.has(bucket));
+        for (const bucket of read) claimed.add(bucket);
+        if (read.length > 0) perTag.push({ read, sweep: [...read, ...sweepBucketsFor(owned)] });
       }
       if (perTag.length === 0) return { tier: 'redis', keys: [] };
       const replies = await Promise.all(
-        perTag.map((buckets) =>
-          conn().send('EVAL', [INVALIDATE_SCRIPT, String(buckets.length), ...buckets]),
+        perTag.map(({ read }) =>
+          conn().send('EVAL', [INVALIDATE_SCRIPT, String(read.length), ...read]),
         ),
       );
       // A member may sit in two tag sets; deleting it twice is harmless but reporting it twice
@@ -369,7 +382,7 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       // drops the bucket, which is what made that failure permanent.
       for (let i = 0; i < perTag.length; i += 1) {
         const gone = [...new Set(toStrings(replies[i]))].filter((member) => deleted.has(member));
-        for (const bucket of perTag[i] ?? []) {
+        for (const bucket of perTag[i]?.sweep ?? []) {
           for (let start = 0; start < gone.length; start += DELETE_BATCH) {
             await conn().send('SREM', [bucket, ...gone.slice(start, start + DELETE_BATCH)]);
           }