@ultimat3/cache 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -18,21 +18,29 @@ Tier 1. Tagged caching + THE invalidation graph.
   repair by the call's shape.
 - `invalidateTags()` in `invalidate.ts` is the ONLY fan-out path, and the only writer of the log
   `recentInvalidations()` reads. Never call `tier.invalidateTags()` from outside it.
-- **The fan-out clears FARTHEST tier first, and reports in read order** (`TIER_ORDER`, what `/_x`
+- **The fan-out clears FARTHEST tier first, and reports in read order** (core's `CACHE_TIERS`, what `/_x`
   renders). Near-to-far lets a racing read promote the stale far value straight back up.
   `CacheStack.drop` reverses for the same reason. `invalidation-race.test.ts`.
 - **A fill is fenced: sample before `load()`, ask before the write** (`fence.ts`). `sampleFence({ key,
   tags })` → `fence.isValid()`; `markInvalidated` is the write half (`fanOut`, `CacheStack.write`,
   `CacheStack.drop`). Exported so a store outside this package reuses it rather than growing a
-  second mechanism. `cover()` widens a fence for joiners' tags (`createCacheStack.read` only). A
+  second mechanism. `cover()` widens a fence for joiners' tags (`cacheStack.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.
+- Tag order is core's `CACHE_TIERS`, never registration order. `sortTiers()` enforces it.
 - **The rung NAMES are `@ultimat3/core`'s (`CACHE_TIERS`); the ladder is this package's.** `TierName`
-  aliases core's `CacheTierName` and `TIER_ORDER` IS `CACHE_TIERS` (asserted by identity in
-  `tier-vocabulary.test.ts`). Adding a rung is an edit to `packages/core/src/cache-vocabulary.ts`
-  plus a factory here; `scripts/render-modes.ts` refuses a second declaration of the set. **`isr` is
+  aliases core's `CacheTierName`; the read order IS `CACHE_TIERS`, imported — 25.0.0 deleted the
+  `TIER_ORDER` alias (`X_HELPER_COPY` refuses a value of core's under a second name). Adding a
+  rung is an edit to `packages/core/src/cache-vocabulary.ts` plus a factory here; `scripts/render-modes.ts` refuses a second declaration of the set. **`isr` is
   not a tier** — the `'isr'` in `invalidate.ts` is an ISR route (`DependentKind = 'isr-route'`).
 - **`bestEffort()` is the only sanctioned way to swallow a cache refusal.** Its label is `TierLabel`
   (`TierName` plus `'query-read'`), deliberately not a widening of `TierName`.
@@ -41,15 +49,15 @@ Tier 1. Tagged caching + THE invalidation graph.
   values are too. The code field keeps its own total probe (`ultimateCode` in `tier-failures.ts`):
   a driver `code` is a SQLSTATE, never an `X_*`.
 - Tier failures go into `report.errors`; a cache tier may never fail a business read or write.
-  `createCacheStack` routes every `get`/`set`/`del` through `bestEffort()` into
+  `cacheStack` routes every `get`/`set`/`del` through `bestEffort()` into
   `recentTierFailures()`. `load()` is the one unguarded call (it IS the business read).
   `LruCache.set` still throws `X_CACHE_TOO_LARGE` to a direct caller.
 - **`serializeTags` is the wire form; `tagKeys` is the IDENTITY form** (sorted, de-duplicated —
   `@ultimat3/query`'s `cacheKeyFor` builds keys from it). It lives here because `action` and `query`
-  are one tier and cannot share a copy. **Known collision:** `@ultimat3/render` exports its own
-  `tagKeys` (`render/src/route.ts`) with different behaviour; consolidating is render's call.
+  are one tier and cannot share a copy. `@ultimat3/render`'s order-preserving route form is its
+  internal `routeTagKeys` (`render/src/route.ts`) — one public `tagKeys`, this one.
 - **Two exports have no production caller and both are KEPT**: `invalidateWireTags` (the outbound
-  twin of `receiveInvalidationBroadcast`, which `packages/cli/src/dev-cache.ts` calls) and
+  twin of `receiveInvalidationBroadcast`, which `packages/cli/src/runtime-cache.ts` calls) and
   `recentTierFailures()` (no `/_x` panel reads it yet). Wire the panel or leave them.
 - `tag.x` typing comes from the `CacheTagRegistry` augmentation, generated by `x manifest`.
 - **`declareTags()` is additive and process-wide: a test undoes it with `isolateDeclaredTags()`,
@@ -60,16 +68,16 @@ Tier 1. Tagged caching + THE invalidation graph.
   deletions. `isolateTierFailures`/`resetTierFailures` stay off `index.ts`.
 - Clocks are injected (`LruOptions.clock`, `CacheStackOptions.clock`); read them through `nowMs()`.
 - **`ttlMs` is positive and finite, and `assertTtl` (`tiers.ts`) is the one place that says so** —
-  every tier calls it before writing, the request memo and `createMemorySemanticCache.remember`
+  every tier calls it before writing, the request memo and `memorySemanticCache.remember`
   included (scope `'semantic'`, `jitterFraction: 0`). `X_CACHE_TTL_INVALID`, never a resolution.
 - **`assertTtl` also SPREADS the lease it validated.** `rng` is injected (`LruOptions.rng`,
   `RedisTierOptions.rng`) — never `Math.random()` at a call site; `rng: () => 0` is the full lease.
   `jitterFraction` outside `[0, 1)` is `X_CACHE_JITTER_INVALID`, refused, not clamped.
-- **`createCacheStack` is the production read path, and `@ultimat3/query`'s `readThrough` is its
+- **`cacheStack` is the production read path, and `@ultimat3/query`'s `readThrough` is its
   caller** — it is what makes an action's `cache.invalidates` reach a `cache:` query.
-- **`createCacheStack` shares one in-flight `load()` per key** through `single-flight.ts`, which is
-  the door onto `@ultimat3/core`'s `createSingleFlight` (pinned by identity in
-  `single-flight.test.ts`). A rejected load clears its entry. One `SingleFlight` per stack.
+- **`cacheStack` shares one in-flight `load()` per key** through `@ultimat3/core`'s
+  `singleFlight`, imported by `tiers.ts` (`single-flight.test.ts` exercises it through the
+  stack); 25.0.0 deleted the `single-flight.ts` door and its re-export. A rejected load clears its entry. One `SingleFlight` per stack.
 - **A wedged `load()` frees its key after `DEFAULT_LOAD_DEADLINE_MS` (30 s)** — http's
   `requestTimeoutMs` default, written as a literal because http is tier 2. `loadDeadlineMs`
   overrides it and `schedule` injects the timer. Eviction frees the KEY only; the load runs on. Not
@@ -87,7 +95,7 @@ Tier 1. Tagged caching + THE invalidation graph.
   collection bust and `t:{entity}:<id>` + `t:{entity}` for a row one. A row bust still `SREM`s what
   it deleted from the index (`sweepBucketsFor`). Pinned by `tier-parity.test.ts` and
   `redis.live.test.ts`.
-- **`CacheTier.set` REJECTS, never throws synchronously** — `createLruTier`/`createMemoTier` are
+- **`CacheTier.set` REJECTS, never throws synchronously** — `lruTier`/`memoTier` are
   `async` for that alone.
 - **`redis.ts`'s script deletes NOTHING — it reads.** It returns the members; the tier `DEL`s them
   client-side one key at a time (slot-local on Cluster/Dragonfly) and `SREM`s only what
@@ -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.
@@ -131,15 +148,16 @@ Tier 1. Tagged caching + THE invalidation graph.
 |---|---|
 | `tags.ts` | `tag` factory, wire form, match semantics, `tagKeys`, declared-tag registry |
 | `graph.ts` | tag → dependents (cache keys, ISR routes, CDN paths, live queries) |
-| `tiers.ts` | `CacheTier`, `TIER_ORDER`, `TierLabel`, `assertTtl`, read-through stack |
+| `tiers.ts` | `CacheTier`, `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,13 +30,14 @@ 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
-without touching a call site — order comes from `TIER_ORDER`, not registration order.
+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 `@ultimat3/core`'s `CACHE_TIERS`, not registration order.
 
 ```ts
-import { createCacheStack, createLruTier, createMemoTier, registerTier } from '@ultimat3/cache';
+import { cacheStack, lruTier, memoTier, registerTier } from '@ultimat3/cache';
 
-const stack = createCacheStack([createMemoTier(), createLruTier({ maxBytes: 64 * 1024 * 1024 })]);
+const stack = cacheStack([memoTier(), lruTier({ maxBytes: 64 * 1024 * 1024 })]);
 for (const tier of stack.tiers) registerTier(tier);
 
 const feed = await stack.read('feed:org-1', () => db.posts.recent(), {
@@ -57,9 +58,9 @@ called. 40,000 keys warmed by one rolling restart otherwise share one expiry ins
 inside the same 30-second window. The roll is injected, never `Math.random()` at a call site:
 
 ```ts
-createLruTier({ rng: () => 0 });          // the full lease — what a test asserting an exact expiry wants
-createRedisTier({ jitterFraction: 0 });   // off entirely
-createRedisTier({ jitterFraction: 0.2 }); // a wider spread; outside [0, 1) is X_CACHE_JITTER_INVALID
+lruTier({ rng: () => 0 });          // the full lease — what a test asserting an exact expiry wants
+redisTier({ jitterFraction: 0 });   // off entirely
+redisTier({ jitterFraction: 0.2 }); // a wider spread; outside [0, 1) is X_CACHE_JITTER_INVALID
 ```
 
 **N concurrent misses are ONE origin load.** `stack.read` shares an in-flight `load()` per key, so
@@ -67,13 +68,13 @@ a reader arriving while another's load is running joins it instead of issuing it
 ends as the load settles, rejection included, so one failure is never held as a permanent one. A
 feed cached for 60s and read 8,000×/s otherwise sends ~1,600 identical queries to Postgres at every
 TTL boundary, because the write only lands after `load()` resolves. The primitive is
-`createSingleFlight()` if you need it elsewhere — `@ultimat3/core`'s, re-exported here unchanged;
-the stack holds one per stack.
+`singleFlight()` from `@ultimat3/core` if you need it elsewhere (25.0.0 dropped this
+package's re-export); the stack holds one per stack.
 A `load()` that never settles does **not** hold its key for ever: past `loadDeadlineMs`
 (`DEFAULT_LOAD_DEADLINE_MS`, 30s — the point at which `http.requestTimeoutMs` already abandoned the
 request that was waiting for it) the key is freed and the next reader loads for itself. Eviction
 frees the key and never the work, so the readers already holding that load still get its answer,
-and the cost is one duplicate fill — `createCacheStack(tiers, { loadDeadlineMs: 5_000 })` for a
+and the cost is one duplicate fill — `cacheStack(tiers, { loadDeadlineMs: 5_000 })` for a
 tighter ceiling on a fast origin. A joiner shares the
 leader's **write** as well as its load, so it contributes to it: tags union, TTLs take the shortest.
 Without that the entry landed carrying only the leader's tags and the joiner's invalidation never
@@ -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. `redisTier` 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
@@ -200,7 +222,7 @@ Redis cannot read each other's payloads. Rename `PostView.author` to `PostView.a
 deploy: `JSON.parse` does not validate, so the old pod reads the new shape back and hands it to a
 renderer expecting the old one — an undefined author on every cached post, on half the fleet, for
 the length of the rolling deploy. The cost of the default is a **cold shared tier per deploy**,
-which is the cheaper of the two. Opt out with `createRedisTier({ buildId: null })` if you version
+which is the cheaper of the two. Opt out with `redisTier({ buildId: null })` if you version
 your own payloads.
 
 ## Invalidating
@@ -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:
 
@@ -345,11 +382,11 @@ rather than failing the write that triggered it.
 ## Semantic cache
 
 For LLM calls, where "list my orders" and "show me my orders" must hit the same entry.
-`createMemorySemanticCache()` does cosine similarity at a 0.92 threshold (tight on
+`memorySemanticCache()` does cosine similarity at a 0.92 threshold (tight on
 purpose — a false hit answers the wrong question, which is worse than a miss) and is the
 only backing this package ships — it is O(n) and in-process. The interface (`SemanticCache`)
 is a driver seam for that reason; a Postgres/pgvector-backed implementation does not exist
-yet here (`@ultimat3/ai`'s `PgVectorStore` is a separate store, for RAG retrieval, not this
+yet here (`@ultimat3/ai`'s `postgresVectorStore()` is a separate store, for RAG retrieval, not this
 cache).
 
 ## Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0"
+    "@ultimat3/core": "25.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.
@@ -74,7 +125,7 @@ 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
+ * `name: 'noop'` it tests for is declared one function up, and `cdnTier` — 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';
@@ -89,7 +140,7 @@ export interface CdnTierOptions {
   readonly pathsForKey?: (key: string) => readonly string[];
 }
 
-export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
+export function cdnTier(options: CdnTierOptions = {}): CacheTier {
   const driver = options.purge ?? noopPurgeDriver();
 
   return {
@@ -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/errors.ts

@@ -108,7 +108,7 @@ export class CacheLimitInvalidError extends UltimateError {
     expected: string;
     /**
      * Where the value came FROM, when that is not an `app.config.ts` key. `loadDeadlineMs` and the
-     * similarity override arrive as call arguments (`createCacheStack`, `lookup`), so telling their
+     * similarity override arrive as call arguments (`cacheStack`, `lookup`), so telling their
      * caller to edit `app.config.ts` names a key that does not exist.
      */
     source?: string | undefined;

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,
+  cdnTier,
+  isNoopPurgeDriver,
+  noopPurgeDriver,
+  surrogateKeys,
+} from './cdn';
 export type { CacheErrorCode } from './errors';
 export {
   CACHE_ERROR_CODES,
@@ -47,8 +53,8 @@ export {
 } from './invalidate';
 export type { LruOptions, LruStats } from './lru';
 
-export { createLruTier, estimateBytes, LruCache } from './lru';
-export { clearMemo, createMemoTier, memoSize } from './memo';
+export { estimateBytes, LruCache, lruTier } from './lru';
+export { clearMemo, memoSize, memoTier } from './memo';
 export type { CloudflarePurgeOptions } from './purge-cloudflare';
 export {
   CLOUDFLARE_API_URL,
@@ -63,10 +69,10 @@ export type { PurgeFetch } from './purge-http';
 export { DEFAULT_PURGE_TIMEOUT_MS } from './purge-http';
 export type { RedisLike, RedisTierOptions } from './redis';
 export {
-  createRedisTier,
   namespaceFor,
   REDIS_INVALIDATE_SCRIPT,
   REDIS_TAG_MEMBER_SCRIPT,
+  redisTier,
 } from './redis';
 export type {
   Embedding,
@@ -75,9 +81,7 @@ export type {
   SemanticHit,
   SemanticRememberOptions,
 } from './semantic';
-export { cosineSimilarity, createMemorySemanticCache } from './semantic';
-export type { FlightJoin, SingleFlight } from './single-flight';
-export { createSingleFlight } from './single-flight';
+export { cosineSimilarity, memorySemanticCache } from './semantic';
 export type { CacheTag, CacheTagRegistry, TagFactory } from './tags';
 export {
   assertKnownTags,
@@ -96,6 +100,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,
@@ -114,11 +119,10 @@ export {
   assertFiniteDurationMs,
   assertFiniteSimilarityFloor,
   assertTtl,
-  createCacheStack,
+  cacheStack,
   DEFAULT_LOAD_DEADLINE_MS,
   DEFAULT_TTL_JITTER_FRACTION,
   isExpired,
   nowMs,
   sortTiers,
-  TIER_ORDER,
 } from './tiers';

package/src/invalidate.ts

@@ -4,14 +4,21 @@
 // the returned report is what the `/_x` cache panel renders, so "did it actually clear?" is
 // answerable without a log dive.
 
-import { currentSpan, logger, renderThrowable, systemClock, withSpan } from '@ultimat3/core';
+import {
+  CACHE_TIERS,
+  currentSpan,
+  logger,
+  renderThrowable,
+  systemClock,
+  withSpan,
+} from '@ultimat3/core';
 import { markInvalidated } from './fence';
 import { dependentsOfKind } from './graph';
 import type { CacheTag } from './tags';
 import { assertKnownTags, knownTags, parseTag, serializeTags } from './tags';
 import { isolateTierFailures, resetTierFailures } from './tier-failures';
 import type { CacheTier, TierInvalidation } from './tiers';
-import { sortTiers, TIER_ORDER } from './tiers';
+import { sortTiers } from './tiers';
 
 /** Revalidates one ISR route path. Provided by `@ultimat3/render`; absent on a worker. */
 export type Revalidator = (path: string) => Promise<void> | void;
@@ -231,7 +238,7 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva
     }
     // The report is read order, not clear order: it is what the `/_x` panel renders, and a ladder
     // printed upside down is a second thing for a reader to learn.
-    tiers.sort((a, b) => TIER_ORDER.indexOf(a.tier) - TIER_ORDER.indexOf(b.tier));
+    tiers.sort((a, b) => CACHE_TIERS.indexOf(a.tier) - CACHE_TIERS.indexOf(b.tier));
 
     const isr = dependentsOfKind(tags, 'isr-route');
     const cdn = dependentsOfKind(tags, 'cdn-path');

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;
   }
@@ -262,7 +273,7 @@ export class LruCache {
   }
 }
 
-export function createLruTier(options: LruOptions = {}): CacheTier & { readonly cache: LruCache } {
+export function lruTier(options: LruOptions = {}): CacheTier & { readonly cache: LruCache } {
   const cache = new LruCache(options);
   return {
     name: 'lru',

package/src/memo.ts

@@ -46,7 +46,7 @@ export function memoSize(): number {
   return storeFor(false)?.size ?? 0;
 }
 
-export function createMemoTier(): CacheTier {
+export function memoTier(): CacheTier {
   return {
     name: 'request-memo',
 
@@ -61,14 +61,14 @@ export function createMemoTier(): CacheTier {
      *
      * This tier holds nothing past the request, so it stores no `expiresAt` — but it is still a
      * rung of one ladder, and `assertTtl` is the one place that says what `ttlMs` may be. Skipping
-     * it made `ttlMs: 0` a value the memo accepted and every other tier refused: `createCacheStack`
+     * it made `ttlMs: 0` a value the memo accepted and every other tier refused: `cacheStack`
      * routes each rung through `bestEffort`, so the miswiring was swallowed as two tier failures
      * and the read still hit — out of the one tier that never should have taken it. Exactly the
      * "two tiers, two readings of `0`" the rule exists to close.
      *
      * Only a lease the caller SUPPLIED is checked: there is no default to fall back to, because a
      * memo entry that outlives its request is not a thing that can happen. `jitterFraction: 0` for
-     * `createMemorySemanticCache`'s reason — spreading a lease is a herd defence for a SHARED
+     * `memorySemanticCache`'s reason — spreading a lease is a herd defence for a SHARED
      * store, and this one dies with the request that made it.
      */
     async set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {

package/src/purge-cloudflare.ts

@@ -3,6 +3,7 @@
 // tags ARE Ultimate's wire tags, so a `Cache-Tag` response header and an `invalidates: [tag.post]`
 // name the same string — the alternative, purging by URL, would need a route list nobody keeps.
 
+import { isRetryableStatus } from '@ultimat3/core';
 import type { PurgeDriver } from './cdn';
 import { CachePurgeFailedError } from './errors';
 import type { PurgeFetch } from './purge-http';
@@ -13,7 +14,6 @@ import {
   defaultPurgeFetch,
   detailFrom,
   isRecord,
-  isRetryableStatus,
   purgeBody,
   purgePost,
   requireCredential,

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/purge-fastly.ts

@@ -3,6 +3,7 @@
 // client. The keys are Ultimate's wire tags unchanged (`post`, `post:1`), which is the property
 // that keeps an edge purge and an app-level invalidation from ever meaning different things.
 
+import { isRetryableStatus } from '@ultimat3/core';
 import type { PurgeDriver } from './cdn';
 import { CachePurgeFailedError } from './errors';
 import type { PurgeFetch } from './purge-http';
@@ -13,7 +14,6 @@ import {
   defaultPurgeFetch,
   detailFrom,
   isRecord,
-  isRetryableStatus,
   type PurgeBody,
   purgeBody,
   purgePost,

package/src/purge-http.ts

@@ -18,9 +18,7 @@ const MAX_DETAIL_LENGTH = 200;
 // Every other 4xx is a credential or a plan, which no retry fixes. The table itself is
 // `@ultimat3/core`'s — this line and `packages/mail/src/driver-resend.ts`'s were byte-identical in
 // two packages that cannot import each other, so one of them was always going to be edited alone.
-// Re-exported rather than imported twice, so both purge drivers still read "what a failure means"
-// off the shared HTTP half — the same door `@ultimat3/auth`'s `tokens.ts` gives `timingSafeEqual`.
-export { isRetryableStatus } from '@ultimat3/core';
+// Both purge drivers import it from core; it is not re-exported here (`X_HELPER_COPY`).
 
 /**
  * A bare reference to `globalThis.fetch` risks "Illegal invocation" on some hosts; closing over

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 {
@@ -189,7 +191,7 @@ function raiseSweepFailure(failures: readonly unknown[], attempted: number): nev
   });
 }
 
-export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
+export function redisTier(options: RedisTierOptions = {}): CacheTier {
   const ns = namespaceFor(options.prefix ?? 'x', options.buildId);
   const defaultTtlMs = assertFiniteDurationMs(
     'redis',
@@ -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/semantic.ts

@@ -78,7 +78,7 @@ interface SemanticRecord {
   readonly tags: readonly CacheTag[];
 }
 
-export function createMemorySemanticCache(options: SemanticCacheOptions = {}): SemanticCache {
+export function memorySemanticCache(options: SemanticCacheOptions = {}): SemanticCache {
   // Screened at construction, both of them: this tier's two knobs are the ones whose failure is
   // silent — a floor of NaN matches everything, a ceiling of NaN evicts nothing.
   const threshold = assertFiniteSimilarityFloor('semantic', 'threshold', options.threshold ?? 0.92);

package/src/tags.ts

@@ -65,10 +65,9 @@ export function serializeTags(tags: readonly CacheTag[]): string[] {
  * both are tier 3, so neither can import the other and a copy in either is a second answer for the
  * other. The same move `toBucket` made into `@ultimat3/http`.
  *
- * NOT the same function as `@ultimat3/render`'s same-named `tagKeys`, which is `serializeTags`
- * over an optional list and deliberately preserves declaration order for a route descriptor
- * (`dsl.test.ts` pins it). Two behaviours under one name, in two packages an app imports together:
- * naming it here is where a reader can see both.
+ * NOT `@ultimat3/render`'s internal `routeTagKeys`, which is `serializeTags` over an optional list
+ * and deliberately preserves declaration order for a route descriptor (`dsl.test.ts` pins it). It
+ * was a second public `tagKeys` until 25.0.0: two behaviours under one name.
  */
 export function tagKeys(tags: readonly CacheTag[]): readonly string[] {
   return [...new Set(serializeTags(tags))].sort();

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

@@ -4,14 +4,15 @@
 // sites. Order is data, not control flow.
 
 import type { CacheTierName, Clock, Scheduler } from '@ultimat3/core';
-import { CACHE_TIERS, systemClock } from '@ultimat3/core';
+import { CACHE_TIERS, singleFlight, 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
@@ -22,14 +23,14 @@ import { bestEffort } from './tier-failures';
  */
 export type TierName = CacheTierName;
 
-/** Read order. Index in this array is the tier's distance from the request. */
-export const TIER_ORDER: readonly TierName[] = CACHE_TIERS;
+// Read order is core's `CACHE_TIERS`: index in that array is the tier's distance from the request.
+// Imported, never aliased under a second name here (`X_HELPER_COPY`).
 
 /**
  * Who a swallowed refusal is attributed to in `recentTierFailures()` and the `/_x` panel: every
  * rung of the ladder, plus a store that degrades the same way without being on it.
  *
- * Closed rather than a free-form string, and NOT a widening of `TierName`: `TIER_ORDER` is the
+ * Closed rather than a free-form string, and NOT a widening of `TierName`: `CACHE_TIERS` is the
  * ladder and a name missing from it sorts to `-1`, ahead of the request memo. A label is a log
  * facet; a `TierName` is a position. Two spellings of one store is a panel nobody can group.
  *
@@ -188,6 +189,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 {
@@ -212,9 +219,9 @@ export function isExpired<T>(entry: CacheEntry<T>, at: number): boolean {
   return entry.expiresAt !== undefined && entry.expiresAt <= at;
 }
 
-/** Sorts tiers into `TIER_ORDER` so registration order cannot change read semantics. */
+/** Sorts tiers into `CACHE_TIERS` order so registration order cannot change read semantics. */
 export function sortTiers(tiers: readonly CacheTier[]): readonly CacheTier[] {
-  return [...tiers].sort((a, b) => TIER_ORDER.indexOf(a.name) - TIER_ORDER.indexOf(b.name));
+  return [...tiers].sort((a, b) => CACHE_TIERS.indexOf(a.name) - CACHE_TIERS.indexOf(b.name));
 }
 
 /**
@@ -246,7 +253,7 @@ export interface CacheStackOptions {
   readonly schedule?: Scheduler;
 }
 
-export function createCacheStack(
+export function cacheStack(
   tiers: readonly CacheTier[],
   options: CacheStackOptions = {},
 ): CacheStack {
@@ -259,14 +266,14 @@ export function createCacheStack(
   // holding its promise still get whatever it eventually answers. What eviction buys is that the
   // NEXT reader is allowed to try. So the worst case is one duplicate fill, which the ladder's
   // last-write-wins `set` already tolerates, against a key pinned for the life of the process.
-  const flight = createSingleFlight({
+  const flight = singleFlight({
     deadlineMs: assertFiniteDurationMs(
       'ladder',
       'loadDeadlineMs',
       options.loadDeadlineMs ?? DEFAULT_LOAD_DEADLINE_MS,
-      // Caller-owned: it arrives as a `createCacheStack({ loadDeadlineMs })` argument, so there is
+      // Caller-owned: it arrives as a `cacheStack({ loadDeadlineMs })` argument, so there is
       // no `app.config.ts` key to send the reader to.
-      'the loadDeadlineMs argument to createCacheStack(...)',
+      'the loadDeadlineMs argument to cacheStack(...)',
     ),
     schedule: options.schedule,
   });
@@ -289,6 +296,7 @@ export function createCacheStack(
     value: T,
     setOptions?: CacheSetOptions,
     fence?: CacheFence,
+    shared?: TierFences,
   ): Promise<void> => {
     const resolved = ttlOptionsFor(value, setOptions);
     const written: CacheTier[] = [];
@@ -297,8 +305,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 +400,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);

package/src/redis-fake.ts

@@ -1,115 +0,0 @@
-// The fake `Bun.redis` both redis test files drive, and the two wire readers they assert with.
-// It is a RECORDER, never an interpreter: it cannot run Lua, so it never pretends to, and every
-// claim about what a script DOES lives in `redis.live.test.ts`. Not exported from `index.ts` —
-// it is a test double shaped around this package's own assertions, not public API.
-
-import type { RedisLike, RedisTierOptions } from './redis';
-import { createRedisTier, REDIS_TAG_MEMBER_SCRIPT } from './redis';
-import type { CacheTier } from './tiers';
-
-export interface FakeRedis extends RedisLike {
-  readonly sent: string[][];
-  /**
-   * What the server's script answers for one `EVAL`. A test driving a path that READS the reply
-   * has to say what came back; there is no default, because `[]` is exactly what a gutted
-   * `INVALIDATE_SCRIPT` returns and a silent one would make "the bust cleared nothing" the
-   * baseline of both files.
-   */
-  answerEval(script: string, reply: unknown): void;
-  /** Makes one value key's `DEL` refuse, which is the half of a bust that can fail alone. */
-  refuseDel(key: string): void;
-}
-
-export function fakeRedis(): FakeRedis {
-  const values = new Map<string, string>();
-  // The lease `EX` bought, in ms. A fake that answered no `PTTL` could not catch a tier that
-  // stopped asking for one — and a hit read back without its remaining life is promoted on the
-  // caller's ttl, which is how a value one second from expiry gets a fresh five minutes.
-  const expiries = new Map<string, number>();
-  const sent: string[][] = [];
-  // A fake cannot run Lua. This one used to mirror both script bodies in TypeScript, which is why
-  // gutting either to `return 1` / `return {}` left all 517 tests in `cache` + `query` green — the
-  // assertions ran against the mirror and the script itself was executed by nothing, ever. What is
-  // left is a recorder: the wire traffic is what those files assert, the script body is opaque to
-  // them, and every claim about what a script DOES lives behind TEST_REDIS_URL.
-  const evalReplies = new Map<string, unknown>([
-    // Nothing reads the tag-join's reply, so a constant here asserts nothing about the script.
-    [REDIS_TAG_MEMBER_SCRIPT, 1],
-  ]);
-  const refused = new Set<string>();
-  return {
-    sent,
-    answerEval(script, reply) {
-      evalReplies.set(script, reply);
-    },
-    refuseDel(key) {
-      refused.add(key);
-    },
-    get(key) {
-      return Promise.resolve(values.get(key) ?? null);
-    },
-    set(key, value) {
-      values.set(key, value);
-      return Promise.resolve('OK');
-    },
-    send(command, args) {
-      sent.push([command, ...args]);
-      if (command === 'SET') {
-        values.set(String(args[0]), String(args[1]));
-        if (args[2] === 'EX') expiries.set(String(args[0]), Number(args[3]) * 1_000);
-        if (args[2] === 'PX') expiries.set(String(args[0]), Number(args[3]));
-        return Promise.resolve('OK');
-      }
-      if (command === 'PTTL') {
-        const key = String(args[0]);
-        if (!values.has(key)) return Promise.resolve(-2);
-        return Promise.resolve(expiries.get(key) ?? -1);
-      }
-      if (command === 'DEL') {
-        if (refused.has(String(args[0]))) {
-          return Promise.reject(new Error(`redis refused DEL ${String(args[0])}`));
-        }
-        values.delete(String(args[0]));
-        expiries.delete(String(args[0]));
-        return Promise.resolve(1);
-      }
-      if (command === 'EVAL') {
-        const script = String(args[0]);
-        if (!evalReplies.has(script)) {
-          // Loud rather than `[]`: an empty member list is what the gutted script answers, so a
-          // default would report every bust in these files as clean and every one of them green.
-          throw new Error(
-            'fake redis cannot execute EVAL — call answerEval(script, reply) to state what the ' +
-              'server returned, or move the claim to redis.live.test.ts, which runs the script',
-          );
-        }
-        return Promise.resolve(evalReplies.get(script));
-      }
-      return Promise.resolve(null);
-    },
-  };
-}
-
-/**
- * `buildId: null` and `rng: () => 0` are the two things a wire assertion needs pinned: the
- * namespace carries the build id by default, and the lease is spread by default.
- */
-export function tierFor(client: RedisLike, extra: RedisTierOptions = {}): CacheTier {
-  return createRedisTier({ client, buildId: null, rng: () => 0, ...extra });
-}
-
-/** The `{...}` hash tag of a key, which is what Redis Cluster hashes to a slot. */
-export function slotTokenOf(key: string): string {
-  return /\{([^}]*)\}/.exec(key)?.[1] ?? key;
-}
-
-/**
- * Every key argument of one command — `EVAL script numkeys k1 .. kN`, `DEL key` and
- * `SREM key member..`, whose members are values rather than keys and so hash to nothing.
- */
-export function keysOf(command: readonly string[]): string[] {
-  if (command[0] === 'EVAL') return command.slice(3, 3 + Number(command[2]));
-  if (command[0] === 'DEL') return command.slice(1);
-  if (command[0] === 'SREM' || command[0] === 'SISMEMBER') return command.slice(1, 2);
-  return [];
-}

package/src/single-flight.ts

@@ -1,8 +0,0 @@
-// N concurrent misses on one key are ONE origin load. The mechanism is `@ultimat3/core`'s — this
-// file's shape verbatim, one tier down, plus identity-checked eviction and an optional injected
-// deadline — because four packages each grew their own deduper and only copies can drift. This
-// file stays as the door `@ultimat3/cache` has always published it through, so no caller moves.
-// `@ultimat3/realtime`'s `entry.reading` is the same shape one tier UP, adopting the same door.
-
-export type { FlightJoin, SingleFlight } from '@ultimat3/core';
-export { createSingleFlight } from '@ultimat3/core';