@ultimat3/cache 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -27,6 +27,14 @@ Tier 1. Tagged caching + THE invalidation graph.
   second mechanism. `cover()` widens a fence for joiners' tags (`createCacheStack.read` only). A
   fence never fails a read — it declines to publish. The one process-global here with no `isolate*()`
   seam, structurally: a fence samples the current generation.
+- **The Redis tier keeps a second fence, for the FLEET** (`CacheTier.fence`, `tier-fence.ts`,
+  `redis-fence.ts`): a bust `SET`s a leased generation BEFORE it reads its buckets; `stack.read`
+  samples before `load()` and asks AFTER the tier's `set`. `busted` withdraws the whole fill,
+  `unprovable` (Redis unreachable, past `FENCE_PROOF_WINDOW_MS`, an unsampled joiner tag) skips
+  that tier only. Plain `SET`/`GET`, never a script — so `redis-fence.test.ts` proves it on the
+  fake. Tags only; `drop`/`write` by key still fence one process.
+- **A refused `set` in `fill` is followed by a `del` in that tier.** `LruCache.set` called
+  directly still leaves the entry it refused to replace.
 - One graph. `graph.ts` exports functions over module state and **no constructor**; no second registry.
 - Tag order is `TIER_ORDER`, never registration order. `sortTiers()` enforces it.
 - **The rung NAMES are `@ultimat3/core`'s (`CACHE_TIERS`); the ladder is this package's.** `TierName`
@@ -111,7 +119,16 @@ Tier 1. Tagged caching + THE invalidation graph.
   from `tiers` + `isr` + `liveQueries`, never `cdn`.
 - A purge driver is selected by `selectPurgeDriver` from the environment, never `app.config.ts`. Two
   CDN credentials, or half a pair, is refused. The token never reaches a printed string.
-- `assertPurgeableKeys` refuses whitespace or a comma in a key **before** the request.
+- `assertPurgeableKeys` refuses whitespace or a comma in a key **before** the request — and at
+  EMISSION (`surrogateKeys`, `cacheHeaders`), where an unpurgeable key would otherwise be tagged.
+- **The edge speaks `tagMatches` through two key lists in `cdn.ts`**: a response carries each wire
+  tag plus `e:<entity>`; a row bust purges `<entity>:<id>` + `<entity>`, a collection bust
+  `e:<entity>` + `<entity>`. Never purge `e:` for a row. `tag-parity.test.ts` runs one fixture
+  table through memo, LRU, Redis and CDN.
+- **The one shipped emitter of surrogate keys is `toResult` in `packages/render/src/render-isr.ts`**
+  (`surrogateKeys(tags, 'isr')`, `As of 2026-10-02`; http strips them on a rewrite to private). `cacheHeaders` has no production caller, and
+  `@ultimat3/http`'s `applyCacheHeaders` joins `CacheHint.tags` verbatim — a caller hands it
+  `surrogateKeys` output. Render screens `revalidate.tags` at registration with this function.
 - `retryable` on `X_CACHE_PURGE_FAILED` is core's `isRetryableStatus` (re-exported by
   `purge-http.ts`), plus any request with no status, and `CachePurgeFailedError` passes it through
   as a per-instance `retry` — never `registerErrorRetry`, one code covers a 401 and a 429.
@@ -133,13 +150,15 @@ Tier 1. Tagged caching + THE invalidation graph.
 | `graph.ts` | tag → dependents (cache keys, ISR routes, CDN paths, live queries) |
 | `tiers.ts` | `CacheTier`, `TIER_ORDER`, `TierLabel`, `assertTtl`, read-through stack |
 | `fence.ts` | the invalidation fence a fill (here or in `query`) checks before it publishes |
+| `tier-fence.ts` | `TierFence`/`FenceVerdict`, and how a fill samples and asks a shared tier's fence |
+| `redis-fence.ts` | the leased generation keys a bust writes and a fill watches |
 | `set-options.ts` | how two callers' `CacheSetOptions` combine, and the `null`-load TTL |
 | `tier-failures.ts` | `bestEffort()`, and the bounded log of refusals it absorbs |
 | `memo.ts` | request memo over the ALS ctx (WeakMap, no lifecycle) |
 | `lru.ts` | byte-budgeted LRU (linked list + map + tag index) |
 | `redis.ts` | `Bun.redis` tier, build-namespaced keys, hash-tagged buckets, one script call per tag |
 | `single-flight.ts` | the door onto `@ultimat3/core`'s `createSingleFlight` — one in-flight `load()` per key, shared by every concurrent miss. No implementation of its own since 2026-08-23 |
-| `cdn.ts` | `Cache-Control`/`Surrogate-Key` emission, the `PurgeDriver` seam, `noopPurgeDriver` |
+| `cdn.ts` | `Cache-Control`/`Surrogate-Key` emission, `surrogateKeys`, the purge key list, the `PurgeDriver` seam |
 | `purge-http.ts` | the HTTP half both remote drivers share: one POST, batching, key guard, and core's retryable table re-exported |
 | `purge-fastly.ts` | `fastlyPurgeDriver`: surrogate-key batch purge, `purge_all` |
 | `purge-cloudflare.ts` | `cloudflarePurgeDriver`: cache-tag purge, `purge_everything` |

package/README.md

@@ -30,7 +30,8 @@ Reads walk down until a hit, then populate every tier they walked past. Writes p
 | 2 | `redis` | `Bun.redis` | tag→keys set, one `EVAL` **per tag** + slot-local `DEL`s | single node |
 | 3 | `cdn` | headers + purge driver | surrogate keys | no CDN |
 
-A tier is a `CacheTier` (`get`/`set`/`del`/`invalidateTags`). Swap or omit any of them
+A tier is a `CacheTier` (`get`/`set`/`del`/`invalidateTags`, plus an optional `fence` for a tier
+other processes also write). Swap or omit any of them
 without touching a call site — order comes from `TIER_ORDER`, not registration order.
 
 ```ts
@@ -92,6 +93,27 @@ const value = await run();
 if (fence.isValid()) await tier.set(key, value, { tags });
 ```
 
+**That fence is this process's; the Redis tier keeps a second one for the fleet.** A bust another
+replica ran reaches this process only when the broadcast does, and a lost broadcast means never —
+so the fill would publish the pre-write rows into the *shared* tier and every replica would promote
+them. `createRedisTier` implements `CacheTier.fence`: a bust writes a leased generation
+(`<ns>:g:{entity}:r:<id>`, `:c`, `:a`) **before** it reads its buckets, `stack.read` samples the
+generations its tags watch before `load()`, and re-reads them after the tier's `SET`.
+
+| Verdict | Means | The fill |
+|---|---|---|
+| `valid` | nothing the tags match moved | stands |
+| `busted` | a generation moved — proof the value is stale | withdrawn from every tier written so far |
+| `unprovable` | Redis could not be asked, the load outlived the 60s proof window, or a joiner brought a tag nobody sampled | that tier alone is left unwritten; nearer tiers keep the value |
+
+Cost, `As of 2026-10`: one pipelined round trip before each `load()` and one after the `SET` (one
+`GET` for a collection tag, two for a row tag), two `SET`s per busted tag. Plain commands, no
+script. Tag busts only — `stack.drop(key)` and `stack.write(key)` still fence this process alone.
+
+**A tier that refuses a `set` during a fill has the key deleted in that tier.** The refusal is
+absorbed (below), so without the `del` the tier keeps answering with the value the fill was
+replacing — an entry that outgrew the LRU's budget served its previous version for a whole lease.
+
 **A `null` can carry its own TTL.** `negativeTtlMs` is used when the loaded value is `null` or
 `undefined`, so a lookup for a row that has not replicated yet is not held for the positive lease:
 
@@ -131,7 +153,7 @@ tagsFor(Post, row) // both, for a repo write
 ```
 
 Wire form is `post` / `post:<id>`, identical in Redis keys, CDN surrogate keys and
-`--json` reports. Invalidation is asymmetric-tolerant on purpose: busting a collection
+`--json` reports — the edge adds one `e:<entity>` index key per entity ([CDN](#cdn)). Invalidation is asymmetric-tolerant on purpose: busting a collection
 kills its rows, busting a row kills the collections that held it.
 
 `tag.post` is typed via a registry that `x manifest` generates, so `tag.pots` is a build
@@ -306,11 +328,26 @@ covers — so a suite outside `packages/cache` isolates the tiers and gets the f
 ```ts
 cacheHeaders({ sMaxAge: 300, staleWhileRevalidate: 86_400, tags: [tag('post', id)] });
 // => { 'Cache-Control': 'public, max-age=0, s-maxage=300, stale-while-revalidate=86400',
-//      'Surrogate-Key': 'post:1' }
+//      'Surrogate-Key': 'post:1 e:post', 'Cache-Tag': 'post:1,e:post' }
 ```
 
-The surrogate keys **are** the tags, byte for byte, so an edge purge and an app-level
-invalidation can never mean different things. A `cdn-path` dependent registered against a tag goes
+An edge purges by exact key, so `tagMatches` is built from what a response **carries** and what a
+bust **purges** — both from `cdn.ts`, so they cannot drift:
+
+| | Row tag `post:1` | Collection tag `post` |
+|---|---|---|
+| a response carries (`surrogateKeys(tags)`) | `post:1` `e:post` | `post` `e:post` |
+| a bust purges | `post:1` `post` | `e:post` `post` |
+
+So a row bust clears that row's pages and the lists keyed `post`, never `post:2`'s; a collection
+bust clears everything of the entity. `e:<entity>` is the edge twin of the Redis tier's entity
+index. Carrying the wire tags alone left a detail page unreachable by a collection bust, and a
+list unreachable by a row bust, with `errors: []`. Header growth, measured: `len(entity) + 3`
+bytes per distinct entity in each of the two headers — 7 bytes each for `post`, 14 per response.
+
+`surrogateKeys()` is exported for any emitter that does not go through `cacheHeaders()`. Both
+refuse a key carrying whitespace or a comma **at emission** (`X_CACHE_PURGE_FAILED`): the CDN
+would split it into keys no purge ever names. A `cdn-path` dependent registered against a tag goes
 out in the same purge — as a surrogate key, the one currency `PurgeDriver` has — so a host
 registering one must tag that response with its own path. Three `PurgeDriver`s ship:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0"
+    "@ultimat3/core": "24.0.0"
   }
 }

package/src/cdn.ts

@@ -1,11 +1,12 @@
 // Tier 3: the CDN. Ultimate does not read from the CDN (it sits in front of us), so this
 // tier's job is the other two thirds of caching: emitting the headers that let the CDN hold
-// the response, and purging by surrogate key when a tag changes. Surrogate keys ARE the
-// tags — same strings, so a CDN purge cannot drift from an app-level invalidation.
+// the response, and purging by surrogate key when a tag changes. Surrogate keys are built from
+// the tags in this one file, so what a purge sends cannot drift from what a response carries.
 
 import { dependentsOfKind } from './graph';
+import { assertPurgeableKeys } from './purge-http';
 import type { CacheTag } from './tags';
-import { serializeTags } from './tags';
+import { serializeTag } from './tags';
 import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
 
 export interface CacheHeaderOptions {
@@ -22,6 +23,56 @@ export interface CacheHeaderOptions {
   readonly tags?: readonly CacheTag[];
 }
 
+/**
+ * The edge's entity index: every response tagged with ANY tag of `entity` carries it. The CDN twin
+ * of `redis.ts`'s `e:{entity}` bucket, and a separate key for the same reason — one key serving as
+ * both "the collection tag" and "everything of this entity" is what makes a row bust over-reach.
+ */
+const entityIndexKey = (entity: string): string => `e:${entity}`;
+
+const screened = (emitter: string, keys: readonly string[]): readonly string[] => {
+  const unique = [...new Set(keys)];
+  assertPurgeableKeys(emitter, unique);
+  return unique;
+};
+
+/**
+ * What a response CARRIES: each tag's wire form, plus its entity's index key.
+ *
+ * A CDN cannot ask "does this key match?" — it purges by exact key — so `tagMatches`, the two-way
+ * rule every other tier keeps, has to be built out of what is carried and what is purged. Carrying
+ * the wire tags alone meant a collection bust (`post`) never reached a detail page keyed `post:1`,
+ * with `errors: []`. `purgeKeysFor` below is the other half; they live together so they cannot drift.
+ *
+ * Screened HERE, at emission: a key carrying whitespace or a comma is split by the CDN into keys
+ * nothing ever purges, so the response would be tagged and could never be cleared.
+ */
+export function surrogateKeys(
+  tags: readonly CacheTag[],
+  emitter = 'surrogateKeys',
+): readonly string[] {
+  return screened(
+    emitter,
+    tags.flatMap((owned) => [serializeTag(owned), entityIndexKey(owned.entity)]),
+  );
+}
+
+/**
+ * What a bust PURGES. A COLLECTION bust matches every tag of the entity, so it purges the index —
+ * and the bare collection key too, which responses cached before the index existed still carry.
+ * A ROW bust matches its own tag and the bare collection tag only: `post:2` survives `post:1`.
+ */
+function purgeKeysFor(tags: readonly CacheTag[]): readonly string[] {
+  return screened(
+    'cdn',
+    tags.flatMap((requested) =>
+      requested.id === undefined
+        ? [entityIndexKey(requested.entity), requested.entity]
+        : [serializeTag(requested), requested.entity],
+    ),
+  );
+}
+
 /** `Cache-Control` + `Surrogate-Key` + `Cache-Tag`, ready to spread into a `Headers` init. */
 export function cacheHeaders(options: CacheHeaderOptions = {}): Record<string, string> {
   const visibility = options.visibility ?? 'public';
@@ -41,7 +92,7 @@ export function cacheHeaders(options: CacheHeaderOptions = {}): Record<string, s
   if (options.immutable === true) parts.push('immutable');
 
   const headers: Record<string, string> = { 'Cache-Control': parts.join(', ') };
-  const keys = serializeTags(options.tags ?? []);
+  const keys = surrogateKeys(options.tags ?? [], 'cacheHeaders');
   if (keys.length > 0) {
     headers['Surrogate-Key'] = keys.join(' ');
     // Cloudflare's spelling of the same list; `@ultimat3/http`'s `applyCacheHeaders` writes both.
@@ -111,7 +162,7 @@ export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
     },
 
     /**
-     * The tags themselves plus every `cdn-path` the graph hangs off them — one purge, one list.
+     * `purgeKeysFor(tags)` plus every `cdn-path` the graph hangs off them — one purge, one list.
      *
      * Those paths were computed by `invalidate.ts` and reported as busted while nothing ever
      * purged them, so `x cache bust --json` named a path the edge still held for its whole
@@ -128,7 +179,7 @@ export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
       if (isNoopPurgeDriver(driver)) {
         return { tier: 'cdn', keys: [], skipped: 'no purge driver configured' };
       }
-      const keys = [...new Set([...serializeTags(tags), ...dependentsOfKind(tags, 'cdn-path')])];
+      const keys = [...new Set([...purgeKeysFor(tags), ...dependentsOfKind(tags, 'cdn-path')])];
       if (keys.length === 0) return { tier: 'cdn', keys: [] };
       const accepted = await driver.purge(keys);
       return { tier: 'cdn', keys: accepted };

package/src/index.ts

@@ -1,7 +1,13 @@
 // Public API of @ultimat3/cache. Explicit, no `export *`.
 
 export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
-export { cacheHeaders, createCdnTier, isNoopPurgeDriver, noopPurgeDriver } from './cdn';
+export {
+  cacheHeaders,
+  createCdnTier,
+  isNoopPurgeDriver,
+  noopPurgeDriver,
+  surrogateKeys,
+} from './cdn';
 export type { CacheErrorCode } from './errors';
 export {
   CACHE_ERROR_CODES,
@@ -96,6 +102,7 @@ export {
 } from './tags';
 export type { TierFailure, TierOperation } from './tier-failures';
 export { bestEffort, recentTierFailures } from './tier-failures';
+export type { FenceVerdict, TierFence } from './tier-fence';
 export type {
   CacheEntry,
   CacheSetOptions,

package/src/lru.ts

@@ -43,6 +43,17 @@ interface LruNode {
 
 const encoder = new TextEncoder();
 
+/**
+ * `JSON.stringify` renders a `Map` or a `Set` as `{}` — two bytes for a collection of any size, so
+ * a tier budgeted at 64 MiB held gigabytes of them without evicting once. Walked as their entries
+ * instead; a replacer is applied to what it returns, so a nested one is walked too.
+ */
+const widenCollections = (_key: string, value: unknown): unknown => {
+  if (value instanceof Map) return [...value.entries()];
+  if (value instanceof Set) return [...value];
+  return value;
+};
+
 /** Cheap, deterministic size estimate. Exact heap cost is unknowable; consistency matters. */
 export function estimateBytes(value: unknown): number {
   if (value === undefined) return 0;
@@ -50,7 +61,7 @@ export function estimateBytes(value: unknown): number {
   if (value instanceof ArrayBuffer) return value.byteLength;
   if (ArrayBuffer.isView(value)) return value.byteLength;
   try {
-    return encoder.encode(JSON.stringify(value) ?? '').byteLength;
+    return encoder.encode(JSON.stringify(value, widenCollections) ?? '').byteLength;
   } catch {
     return 1024;
   }

package/src/purge-env.ts

@@ -1,7 +1,7 @@
 // Single responsibility: environment → purge driver. The one place that decides which CDN a boot
 // purges against, so `x dev`, a worker container and any custom host resolve it identically. Keyed
-// on env rather than an `app.config.ts` field because nothing loads that file's contents at
-// runtime — a `cache.cdn` block would be a setting no boot could read.
+// on env, never an `app.config.ts` field the boot's one loader would read: the edge is a credential
+// and a deployment's, and one image is purged against a different edge per environment.
 
 import { ConfigInvalidError } from '@ultimat3/core';
 import type { PurgeDriver } from './cdn';

package/src/redis-fence.ts

@@ -0,0 +1,109 @@
+// The fence, held in Redis. `fence.ts` is module state: it cannot see a bust another replica ran
+// until the broadcast arrives, and a lost broadcast means never. A per-tag generation in the
+// shared store is the one thing both replicas read. Plain `SET`/`GET` — no script — so the fake
+// that cannot run Lua still proves every interleaving (`redis-fence.test.ts`).
+
+import type { Clock } from '@ultimat3/core';
+import type { FenceScope } from './fence';
+import type { CacheTag } from './tags';
+import type { FenceVerdict, TierFence } from './tier-fence';
+import { nowMs } from './tiers';
+
+/** The slice of the client a generation needs. `RedisLike` satisfies it. */
+export interface GenerationClient {
+  get(key: string): Promise<string | null>;
+  send(command: string, args: string[]): Promise<unknown>;
+}
+
+/** How long a generation outlives the bust that wrote it. Bounds the keys a write-heavy app holds. */
+export const GENERATION_LEASE_MS = 120_000;
+
+/**
+ * How long a fence can vouch for its sample — half the lease. A generation EXPIRES: sampled
+ * absent, written by a bust, expired again reads as "nothing happened". A bust after the sample
+ * is still on the server for the whole window, so inside it an unchanged reading is a proof; past
+ * it nothing is, and the fence says so instead of guessing.
+ */
+export const FENCE_PROOF_WINDOW_MS = GENERATION_LEASE_MS / 2;
+
+/**
+ * `tagMatches` in keys, the way `redis.ts`'s buckets are. Three generations per entity:
+ * `r:<id>` moves on a bust of that row, `c` on a collection bust, `a` on ANY bust of the entity.
+ * A row fill is hit by its own row and by the collection; a collection fill by anything. One
+ * counter per entity would decline every row fill while any OTHER row was being written.
+ * `{entity}` is the Cluster hash tag the buckets already carry.
+ */
+function generationKeys(ns: string) {
+  const row = (owned: CacheTag): string => `${ns}:g:{${owned.entity}}:r:${owned.id ?? ''}`;
+  const collection = (entity: string): string => `${ns}:g:{${entity}}:c`;
+  const any = (entity: string): string => `${ns}:g:{${entity}}:a`;
+  return {
+    bumpedBy: (bust: CacheTag): string[] =>
+      bust.id === undefined
+        ? [collection(bust.entity), any(bust.entity)]
+        : [row(bust), any(bust.entity)],
+    watchedBy: (owned: CacheTag): string[] =>
+      owned.id === undefined ? [any(owned.entity)] : [row(owned), collection(owned.entity)],
+  };
+}
+
+const unique = (keys: readonly string[]): string[] => [...new Set(keys)];
+
+/**
+ * The write half, run by a bust BEFORE it reads its buckets. That order is the whole argument: a
+ * fill re-checks after its own `SET`, so either it sees this generation and withdraws, or it
+ * wrote early enough that the bucket read that follows finds its key and deletes it.
+ *
+ * A fresh token rather than `INCR`: a counter that expired restarts at 1 and can repeat a value
+ * a fence already sampled.
+ */
+export async function bumpGenerations(
+  client: GenerationClient,
+  ns: string,
+  tags: readonly CacheTag[],
+): Promise<void> {
+  const keys = unique(tags.flatMap(generationKeys(ns).bumpedBy));
+  if (keys.length === 0) return;
+  const token = crypto.randomUUID();
+  const lease = String(GENERATION_LEASE_MS);
+  // One key per command, so each is slot-local; issued together, so the bust pays one round trip.
+  await Promise.all(keys.map((key) => client.send('SET', [key, token, 'PX', lease])));
+}
+
+/** The read half: sample now, and answer later whether anything covered moved in between. */
+export async function sampleGenerations(
+  client: GenerationClient,
+  ns: string,
+  clock: Clock,
+  scope: FenceScope,
+): Promise<TierFence> {
+  const keysFor = (tags: readonly CacheTag[] | undefined): string[] =>
+    unique((tags ?? []).flatMap(generationKeys(ns).watchedBy));
+  const sampledAt = nowMs(clock);
+  const sampled = new Map<string, string | null>();
+  await Promise.all(
+    keysFor(scope.tags).map(async (key) => {
+      sampled.set(key, await client.get(key));
+    }),
+  );
+  let coveredUnsampled = false;
+
+  return {
+    cover(next: FenceScope): void {
+      // Unlike the in-process ring there is no history to reach back into: a tag that arrives
+      // after the sample was never read, so nothing can be said about it.
+      if (keysFor(next.tags).some((key) => !sampled.has(key))) coveredUnsampled = true;
+    },
+
+    async verdict(): Promise<FenceVerdict> {
+      if (coveredUnsampled) return 'unprovable';
+      const elapsed = nowMs(clock) - sampledAt;
+      // A clock that ran backwards measured nothing; that is not a proof either.
+      if (!(elapsed >= 0 && elapsed < FENCE_PROOF_WINDOW_MS)) return 'unprovable';
+      const current = await Promise.all(
+        [...sampled].map(async ([key, before]) => (await client.get(key)) === before),
+      );
+      return current.every(Boolean) ? 'valid' : 'busted';
+    },
+  };
+}

package/src/redis.ts

@@ -6,6 +6,8 @@
 import type { Clock } from '@ultimat3/core';
 import { appVersion, logger, systemClock } from '@ultimat3/core';
 import { CacheDriverUnavailableError } from './errors';
+import type { FenceScope } from './fence';
+import { bumpGenerations, sampleGenerations } from './redis-fence';
 import type { CacheTag } from './tags';
 import { parseTag, serializeTag } from './tags';
 import type {
@@ -339,6 +341,9 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       await conn().send('DEL', [valueKey(key)]);
     },
 
+    /** The fleet-wide half of the fill fence: generations other replicas' busts move. */
+    fence: (scope: FenceScope) => sampleGenerations(conn(), ns, clock, scope),
+
     /**
      * ONE script call per tag, never one for the batch. Every key a call is handed comes from a
      * single tag and therefore carries the same `{entity}` hash tag, so it is one slot on Redis
@@ -356,6 +361,10 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
         if (read.length > 0) perTag.push({ read, sweep: [...read, ...sweepBucketsFor(owned)] });
       }
       if (perTag.length === 0) return { tier: 'redis', keys: [] };
+      // Before the buckets are read, and awaited: see `bumpGenerations` for why the order is the
+      // guarantee. A refusal here rejects the bust into `report.errors` with nothing deleted, so
+      // the retry it asks for repeats the whole thing.
+      await bumpGenerations(conn(), ns, tags);
       const replies = await Promise.all(
         perTag.map(({ read }) =>
           conn().send('EVAL', [INVALIDATE_SCRIPT, String(read.length), ...read]),

package/src/tier-fence.ts

@@ -0,0 +1,57 @@
+// The fence a SHARED tier keeps in its own store, and how a fill consults it. `fence.ts` answers
+// for this process; a tier that other processes also write (`redis.ts`) answers for the fleet.
+// Optional on `CacheTier`: an in-process tier has no second writer to be fenced against.
+
+import type { FenceScope } from './fence';
+import { bestEffort } from './tier-failures';
+import type { CacheTier } from './tiers';
+
+/**
+ * `busted` is a PROOF the value is stale, so the whole fill is withdrawn — the near tiers too.
+ * `unprovable` is the absence of one: that tier alone is left unwritten, because a shared store
+ * that cannot vouch for a value must not take a process-local cache down with it.
+ */
+export type FenceVerdict = 'valid' | 'busted' | 'unprovable';
+
+export interface TierFence {
+  /** Asked AFTER the tier's own `set`, never before: see `bumpGenerations` for why. */
+  verdict(): Promise<FenceVerdict>;
+  /** Widen what the fence covers. A tag it never sampled makes it `unprovable`, not valid. */
+  cover(scope: FenceScope): void;
+}
+
+const UNPROVABLE: TierFence = {
+  verdict: () => Promise.resolve('unprovable'),
+  cover: () => undefined,
+};
+
+export type TierFences = ReadonlyMap<CacheTier, TierFence>;
+
+/** One sample per fenced tier, taken before `load()`. A tier that could not answer is unprovable. */
+export async function sampleTierFences(
+  tiers: readonly CacheTier[],
+  key: string,
+  scope: FenceScope,
+): Promise<TierFences> {
+  const fences = new Map<CacheTier, TierFence>();
+  await Promise.all(
+    tiers.map(async (tier) => {
+      if (tier.fence === undefined) return;
+      const sample = tier.fence.bind(tier);
+      const fence = await bestEffort(tier.name, 'get', key, () => sample(scope));
+      fences.set(tier, fence ?? UNPROVABLE);
+    }),
+  );
+  return fences;
+}
+
+/** `unprovable` when the tier could not be asked — a refusal is never read as a clean bill. */
+export async function verdictOf(
+  tier: CacheTier,
+  key: string,
+  fences: TierFences | undefined,
+): Promise<FenceVerdict> {
+  const fence = fences?.get(tier);
+  if (fence === undefined) return 'valid';
+  return (await bestEffort(tier.name, 'get', key, () => fence.verdict())) ?? 'unprovable';
+}

package/src/tiers.ts

@@ -6,12 +6,14 @@
 import type { CacheTierName, Clock, Scheduler } from '@ultimat3/core';
 import { CACHE_TIERS, systemClock } from '@ultimat3/core';
 import { CacheJitterInvalidError, CacheLimitInvalidError, CacheTtlInvalidError } from './errors';
-import type { CacheFence } from './fence';
+import type { CacheFence, FenceScope } from './fence';
 import { markInvalidated, sampleFence } from './fence';
 import { mergeSetOptions, tagsAddedSince, ttlOptionsFor } from './set-options';
 import { createSingleFlight } from './single-flight';
 import type { CacheTag } from './tags';
 import { bestEffort } from './tier-failures';
+import type { TierFence, TierFences } from './tier-fence';
+import { sampleTierFences, verdictOf } from './tier-fence';
 
 /**
  * The rungs, spelled in `@ultimat3/core` and nowhere else. Tier 0 owns the NAMES because
@@ -188,6 +190,12 @@ export interface CacheTier {
   set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
   del(key: string): Promise<void>;
   invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation>;
+  /**
+   * A fence held in the tier's OWN store, for a tier other processes write too. Sampled before
+   * `load()` and asked after this tier's `set`, so a bust another replica ran — one this process
+   * may never be told about — still stops the fill (`tier-fence.ts`). Omitted by in-process tiers.
+   */
+  fence?(scope: FenceScope): Promise<TierFence>;
 }
 
 export interface CacheStack {
@@ -289,6 +297,7 @@ export function createCacheStack(
     value: T,
     setOptions?: CacheSetOptions,
     fence?: CacheFence,
+    shared?: TierFences,
   ): Promise<void> => {
     const resolved = ttlOptionsFor(value, setOptions);
     const written: CacheTier[] = [];
@@ -297,8 +306,28 @@ export function createCacheStack(
         await rollback(written, key);
         return;
       }
-      await bestEffort(tier.name, 'set', key, () => tier.set(key, value, resolved));
+      // A refused `set` leaves whatever the tier held before — the value this fill supersedes —
+      // and `bestEffort` swallows the refusal, so that tier would go on answering with it for its
+      // whole lease. The refusal is still the one recorded failure; the `del` is the repair.
+      let refused = false;
+      await bestEffort(tier.name, 'set', key, async () => {
+        try {
+          await tier.set(key, value, resolved);
+        } catch (error) {
+          refused = true;
+          throw error;
+        }
+      });
+      if (refused) await bestEffort(tier.name, 'del', key, () => tier.del(key));
       written.push(tier);
+      // Asked AFTER the set: the other replica's bust either moved the generation by now, or
+      // read its buckets late enough to find what was just written.
+      const verdict = await verdictOf(tier, key, shared);
+      if (verdict === 'busted') {
+        await rollback(written, key);
+        return;
+      }
+      if (verdict === 'unprovable') await bestEffort(tier.name, 'del', key, () => tier.del(key));
     }
   };
 
@@ -372,12 +401,21 @@ export function createCacheStack(
             key,
             ...(setOptions?.tags === undefined ? {} : { tags: setOptions.tags }),
           });
+          // The same sample, taken in each tier other replicas also write. One round trip, and
+          // only when such a tier is on the ladder.
+          const fleet = await sampleTierFences(ordered, key, {
+            key,
+            ...(setOptions?.tags === undefined ? {} : { tags: setOptions.tags }),
+          });
           const value = await load();
           // Joiners merged their own tags into the load they shared; covering is retroactive, so
           // a tag that arrived mid-load is fenced back to the sample rather than from now.
           const publish = async (options: CacheSetOptions | undefined): Promise<void> => {
-            if (options?.tags !== undefined) fence.cover({ tags: options.tags });
-            await fill(key, value, options, fence);
+            if (options?.tags !== undefined) {
+              fence.cover({ tags: options.tags });
+              for (const tierFence of fleet.values()) tierFence.cover({ tags: options.tags });
+            }
+            await fill(key, value, options, fence, fleet);
           };
           const merged = shared() ?? setOptions;
           await publish(merged);