@ultimat3/cache 1.2.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,267 @@
+# @ultimat3/cache — agent notes
+
+Tier 1. Tagged caching + THE invalidation graph.
+
+## Boundary
+
+- May import: `@ultimat3/core`, `@ultimat3/schema`. Nothing else, ever.
+- Must NOT know about entities, HTTP, jobs, render. `tagsFor()` takes structural args.
+- Consumers: `entity` (write hooks), `action` (`cache.invalidates`), `render` (ISR), `cli`.
+
+## Rules
+
+- `invalidateTags()` in `invalidate.ts` is the ONLY fan-out path. Never call
+  `tier.invalidateTags()` from outside it. It is also the only place the log is written:
+  `recentInvalidations()` is a read of what that one path already reported, never a second
+  recorder a caller has to remember to call.
+- **The fan-out clears FARTHEST tier first, and reports in read order.** Near-to-far leaves the far
+  tier holding the old value after the near ones are clear, and a read racing the bust promotes it
+  straight back up — `report.errors` empty, LRU stale again before the call returns. `CacheStack.drop`
+  reverses for the same reason. The report is re-sorted into `TIER_ORDER` because it is what the
+  `/_x` panel renders. Pinned in `invalidation-race.test.ts`.
+- **A fill is fenced: sample before `load()`, ask before the write** (`fence.ts`). A read-through
+  fill publishes rows `load()` read in the past, so a bust landing in between finds a key that is
+  not there yet, reports `errors: []`, and is overwritten milliseconds later — invisible for the
+  whole TTL. `sampleFence({ key, tags })` → `fence.isValid()` is the whole API, `markInvalidated`
+  is its write half (called by `fanOut`, `CacheStack.write` and `CacheStack.drop`; a caller only
+  needs it for a clearing path of its own). It is **exported** because a store outside this package
+  with the same hole must not grow a second mechanism. `cover()` widens a fence
+  RETROACTIVELY — needed only where joiners contribute tags the leader never sampled, which is
+  `createCacheStack.read` and nothing else. A fence never fails a read: it declines to publish.
+  This is the one process-global here with **no `isolate*()` seam and no reset**, and that is
+  structural: a fence samples the current generation, which is always at or above what the ring has
+  forgotten, so another file's marks cannot invalidate a fence sampled after them.
+- One graph. `graph.ts` exports functions over module state and **no constructor** — do not
+  add one, do not add a second registry anywhere else.
+- Tag order is `TIER_ORDER`, never registration order. `sortTiers()` enforces it.
+- **`bestEffort()` is public, and it is the only sanctioned way to swallow a cache refusal.** A
+  store outside this package that wraps its own `try/catch` degrades invisibly, and a second
+  failure log nobody reads is what this bounded one exists to prevent. Its label is `TierLabel` —
+  `TierName` plus `'query-read'` — closed, and deliberately NOT a widening of `TierName`: a name
+  missing from `TIER_ORDER` sorts to `-1`, ahead of the request memo. A label is a log facet; a
+  `TierName` is a position on the ladder.
+- **A refusal is rendered with `renderThrowable()`, never `error.message`** — the four sites that
+  absorb one (`bestEffort`'s log entry, and `fanOut`'s tier, ISR and broadcast catch blocks). A
+  tier, a revalidator and a broadcast are all app-supplied, so the value they reject with is too:
+  `instanceof` runs a `Proxy`'s `getPrototypeOf` trap and `String()` runs `Symbol.toPrimitive`, so
+  building the log line used to raise INSTEAD of absorbing the refusal — on the business write that
+  triggered the bust, which is the one caller both contracts promise to protect. The code field
+  keeps its own total probe (`ultimateCode` in `tier-failures.ts`) rather than core's `stringField`:
+  a driver error's `code` is a SQLSTATE and must never be reported as an `X_*` one. Consequence to
+  know: a recorded `message` carries the throwable's NAME (`Error: nats is down`, `"just a string"`),
+  which is what `renderThrowable` renders and what the tests here now pin.
+- 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()` for that reason — a
+  refusal becomes "that tier did not answer" and lands in `recentTierFailures()`, the read side's
+  equivalent of `report.errors`. `load()` is the one unguarded call: it is the business read, so
+  swallowing it would return `undefined` as if it were the value. `LruCache.set` still throws
+  `X_CACHE_TOO_LARGE` to a direct caller — the stack is the layer that degrades, not the tier.
+- **`serializeTags` is the wire form; `tagKeys` is the IDENTITY form, and the difference is the
+  point.** `tagKeys` sorts and de-duplicates, because its readers build a descriptor field and a
+  cache KEY out of it — `@ultimat3/query`'s `cacheKeyFor` above all, where a key that varied with
+  declaration order fills two entries for one read and an action's `invalidates` drops whichever
+  one it happens to name. It lives here, in the package that owns `serializeTag`, because
+  `@ultimat3/action` and `@ultimat3/query` held byte-identical copies of it and are the same
+  tier — 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`. **Known collision, not fixed here:**
+  `@ultimat3/render` exports its own `tagKeys` (`render/src/route.ts`) with different behaviour —
+  `serializeTags` over an optional list, declaration order preserved, pinned by its own
+  `dsl.test.ts`. Two behaviours under one name in two packages an app imports together; the
+  consolidation is render's to make, and this doc block is where a reader finds out.
+- **Two exports here have no production caller and both are KEPT — re-verified 2026-08.**
+  `invalidateWireTags` is the wire-form door (`x cache bust` is planned and exits
+  `X_NOT_IMPLEMENTED`); its sibling `receiveInvalidationBroadcast` takes the same wire form and DOES
+  have one (`packages/cli/src/dev-cache.ts`), so deleting the outbound door would leave one of a
+  matched pair. `recentTierFailures()` is the read-ladder half of `report.errors` and the `/_x`
+  cache panel is still **not** its reader — `packages/cli/src/dev-dashboard.ts` imports
+  `recentInvalidations` and nothing else — so it is read only by tests, `@ultimat3/query`'s
+  `cache-degraded.test.ts` included. Neither is dead in the sense that matters: a bounded log with
+  no panel is a log an operator can still reach, and removing it is removing the only evidence a
+  degraded tier leaves. Wire the panel or leave them; do not delete one and keep the other.
+- `tag.x` typing comes from the `CacheTagRegistry` augmentation, generated by `x manifest`.
+- **`declareTags()` is additive and process-wide, so a test undoes it with `isolateDeclaredTags()`,
+  never with `resetDeclaredTags()`.** The empty set is what switches `assertKnownTags` off, so one
+  suite declaring a fixture entity makes every later file in the same `bun test` process validate
+  against a registry it never saw — the cross-file X_CACHE_TAG_UNKNOWN `packages/query`'s read-cache
+  suite used to fail with. A reset would drop a neighbour's declarations instead of only your own;
+  `@ultimat3/testing`'s leak guard fails the file that leaks either the tag set or the tier registry.
+- **Every process-global registry here has that same seam, and a test file uses it: `isolateGraph()`
+  (`graph.ts`), `isolateTiers()` (`invalidate.ts`), `isolateTierFailures()` (`tier-failures.ts`).**
+  A per-test `resetGraph()` / `resetTierFailures()` stays where an empty registry is the subject —
+  pair it with the module-scope isolate and an `afterAll(restore)`. The leak guard reports
+  *additions* only, so a file that DELETES a neighbour's registrations is invisible to it and lands
+  as a failure in an innocent file: a reset in a test file is the one leak nothing catches for you.
+  The last two exist in the owning module because a test file cannot reach the state — the
+  revalidator has no reader and neither log has a writer, so `resetTiers()` is unrecoverable from
+  outside. `isolateTierFailures` is deliberately off `index.ts`, same as `resetTierFailures`:
+  nothing outside this package can clear that log except through `resetTiers()`, which
+  `isolateTiers()` already covers.
+- Clocks are injected (`LruOptions.clock`, `CacheStackOptions.clock`); read them through `nowMs()`.
+- **`ttlMs` is positive and finite, and `assertTtl` (in `tiers.ts`) is the one place that says so.**
+  Every tier calls it before it writes — **the request memo included, `As of 2026-08`**: it was the
+  last rung skipping it, so `ttlMs: 0` was stored by the memo and refused by the other three, and
+  `createCacheStack` swallows both refusals through `bestEffort`, so the read HIT out of the one
+  tier that should never have taken it. It validates a lease it then discards (it holds nothing past
+  the request), and only a lease the caller SUPPLIED — there is no memo default to fall back on.
+  So does `createMemorySemanticCache.remember` — which was
+  the one writer skipping it, so `ttlMs: 0` stored an entry already past its expiry and every lookup
+  missed with a completion bill as the only evidence. Its scope is `'semantic'` (`TtlScope`), with
+  `jitterFraction: 0`: spreading a lease is a herd defence for a SHARED store, and that one is per
+  process. `0` used to be "never expires" here and `EX 1` in `redis.ts`,
+  so one stack answered two ways; the rule lives beside `CacheSetOptions` precisely so a new tier
+  cannot invent a third reading. `X_CACHE_TTL_INVALID`, never a resolution.
+- **`assertTtl` also SPREADS the lease it validated** — validate, then jitter, one choke point. A
+  rolling restart warms 40,000 keys in 30s on one lease and they all expire in one 30s window; the
+  spread is what makes that a ramp. `rng` is injected (`LruOptions.rng`, `RedisTierOptions.rng`) —
+  **never `Math.random()` at a call site**, or nothing downstream is deterministic. `rng: () => 0`
+  is the full lease and is what a test asserting an exact `expiresAt` passes; `jitterFraction: 0`
+  turns it off. Outside `[0, 1)` is `X_CACHE_JITTER_INVALID`, refused rather than clamped.
+- **`createCacheStack` is the production read path, and `@ultimat3/query` is its caller** (`As of
+  2026-08`). It had none for two releases — read-down/promote-up, the fence, single flight and the
+  negative TTL were the package's whole design, reachable only from its own tests, while the one
+  cached read path in the framework kept a private store beside the registry. `readThrough` calls
+  `createCacheStack(registeredTiers(), { clock })` now, so deleting or bypassing this function
+  removes the only thing that makes an action's `cache.invalidates` reach a `cache:` query.
+- **`createCacheStack` shares one in-flight `load()` per key** (`single-flight.ts`, mirroring
+  `realtime`'s `entry.reading`). The share ends as the load settles — a REJECTED load must clear
+  its entry too, or one origin failure becomes a permanent cached rejection. One `SingleFlight` per
+  stack, never a module-level map: two stacks are two ladders.
+- **A joiner shares the leader's WRITE, so it contributes to it** (`FlightJoin`, merged by
+  `mergeSetOptions` in `set-options.ts`). Keyed on `key` alone and read late, the entry used to land
+  carrying only the leader's tags: the joiner's tag reached nothing, so the invalidation it declared
+  never fired. Tags union, TTLs take the SHORTEST — an entry held longer than a caller asked for is
+  stale to that caller. `work` reads the merge through `shared()` **after** the load, or it sees
+  only what the leader brought.
+- **`negativeTtlMs` is the stack's decision, not a tier's.** Only `createCacheStack` sees what
+  `load()` answered, so the `null`/`undefined` branch lives in `ttlOptionsFor` there and reaches a
+  tier as an ordinary `ttlMs`.
+- **A promotion carries the entry's remaining life, not `options.ttlMs`** — `createCacheStack.read`
+  writes the closer tiers with `hit.expiresAt - now`, and drops a hit that fails `isExpired`. A
+  fresh full lease per read is a hot key that never goes stale enough to refetch. `isExpired` was
+  exported and unit-tested and called by nothing; the stack is its one caller.
+- **Every tier's `get` therefore reports `expiresAt`, or the promotion above has nothing to carry.**
+  `redis.ts` reads it from `PTTL`, issued alongside the `GET` so Bun pipelines the pair — the server
+  owns the clock, so it survives skew between the node that wrote and the node that reads, and no
+  stored payload shape changes under a running deployment. `-1`/`-2` are sentinels, not durations:
+  they mean no expiry, never one millisecond ago.
+- **`t:` is the TAG's bucket and `e:` is the ENTITY index, and one key may not be both** (`As of
+  2026-08`). Three tiers implement `tagMatches` and the shared one was the outlier: a row-tagged
+  write joined the collection bucket, and a row bust read that bucket back, so
+  `invalidateTags([tag('post', '1')])` returned every post-tagged key in the store and deleted them
+  — one row write emptying the shared tier for that entity, while the LRU one rung closer kept
+  exactly the row that changed. `writeBucketsFor` joins the declared tag plus `e:{entity}`;
+  `bustBucketsFor` reads the index for a COLLECTION bust and `t:{entity}:<id>` + `t:{entity}` for a
+  ROW one. A collection bust also reads `t:{entity}` — a strict subset of the index today, kept so a
+  `buildId: null` deployment upgrading into this layout does not MISS its old two-role buckets;
+  over-reading a subset costs a round trip, under-reading is a stale read. It IS a wire-layout
+  change: a cold shared tier, which the default build-id namespace already pays per deploy.
+  Pinned by `tier-parity.test.ts` (all three rungs, one test each) and `redis.live.test.ts` (the
+  same two busts against a real server, asserting the LRU's and Redis's survivors are EQUAL).
+- **`CacheTier.set` REJECTS, never throws synchronously.** `createLruTier` and `createMemoTier` are
+  `async` for that reason alone — `LruCache.set` stays a sync API, but a `CacheTier` is one
+  interface with three implementations and `tier.set(...).catch(...)` has to mean the same thing on
+  every rung. `bestEffort` absorbs both shapes; a direct caller does not.
+- **`redis.ts`'s script deletes NOTHING — it reads.** The members of a tag set are value keys in
+  slots this node may not own, so `DEL`ing them from Lua is a cross-slot access that fails on Redis
+  Cluster and Dragonfly strict mode — into `report.errors`, so the bust reads as partial and stale
+  rows serve until TTL. The script returns the members; the tier deletes them client-side, one key
+  per `DEL`, which is slot-local under every topology.
+- **The bucket is not dropped in the script either, and the tier `SREM`s only what it deleted.**
+  Dropping it atomically with the `SMEMBERS` made one failure permanent: a refused `DEL` left its
+  member with no bucket to be found in, so the retry the error asks for answered `keys: []` and
+  those rows served until their own TTL. `Promise.allSettled` is what makes "what actually died"
+  knowable. A member a concurrent write added between the two halves keeps its membership instead
+  of being orphaned by a bust that never deleted it.
+- **A `set` joins its buckets BEFORE it writes the value, and re-checks membership after.** Value
+  first left a window where a bust's `SMEMBERS` saw an empty bucket and the value survived its own
+  invalidation for the full TTL. Joining first moves the window somewhere observable: membership
+  gone by the time the `SET` lands means this write was busted in the air, and the value goes with
+  it — a row nothing can reach by tag is one no later bust can clear. Only a literal `0` from
+  `SISMEMBER` counts as gone (`saysAbsent`); a reply the tier cannot read is not evidence, and
+  deleting on one is a cache that never caches.
+- **`GET` and `PTTL` are two commands and the key can die between them.** `PTTL: -2` for a value
+  the `GET` returned is a MISS, not an entry with no expiry — reported as a hit it is promoted into
+  the LRU on the CALLER's ttl, so a row one millisecond from death gets a fresh five minutes one
+  tier closer.
+- **That fixed half of it; `KEYS` itself was the other half.** Tag keys carry a `{entity}` hash tag
+  (`<ns>:t:{post}`, `<ns>:t:{post}:7`) and `invalidateTags` issues **one script call per tag**, so
+  every key a call is handed hashes to one slot. A single `EVAL` carrying two tags' buckets is
+  `CROSSSLOT`-rejected before the script runs. The invariant a test pins: no command's `KEYS` ever
+  spans two hash tags.
+- **Every tag set carries a lease, and the lease only grows.** `TAG_MEMBER_SCRIPT` does the `SADD`
+  and the `EXPIRE` in one call, one key in `KEYS`. A set with no TTL is unbounded memory and a
+  multi-million-member `SMEMBERS` on the next publish. `EXPIRE … GT` is NOT enough on its own — it
+  treats a key with no TTL as infinite, so a fresh bucket would stay immortal, which is the bug.
+  `SREM`-on-`del` is deliberately not done: `del(key)` does not know the key's tags without a read,
+  and a bounded bucket lease already bounds the growth.
+- **A fake cannot run Lua, so it must never pretend to.** Both fakes used to mirror
+  `INVALIDATE_SCRIPT` and `TAG_MEMBER_SCRIPT` in TypeScript and match on the exported constant's
+  identity — so gutting either script to `return 1` / `return {}` left all 517 tests in `cache` +
+  `query` green, with the entire shared-tier invalidation path proving nothing. The fakes are
+  recorders now: the wire traffic is what a unit test asserts, and a test whose path READS a
+  script's reply states it with `answerEval(script, reply)` — an unprogrammed `EVAL` throws rather
+  than answering `[]`, which is exactly what the gutted script returns. **Every claim about what a
+  script DOES belongs in `redis.live.test.ts`** (`describe.skipIf(!TEST_REDIS_URL)`), which is the
+  only place either one is executed.
+- **The Redis namespace carries the build id by default** (`namespaceFor`, `appVersion()`). Two
+  builds sharing one Redis otherwise read each other's payloads through a `JSON.parse` that does
+  not validate. `buildId: null` opts out. The layout is wire-visible: changing it is a cold cache.
+- **Cross-instance invalidation is a SEAM here, never a transport.** `registerInvalidationBroadcast`
+  (outbound) and `receiveInvalidationBroadcast` (inbound) mirror `registerRevalidator`; `cli` owns
+  the bus. The inbound half cannot re-emit and that is structural — `emit` is on `fanOut`'s private
+  options and only `receiveInvalidationBroadcast` passes `false`. An inbound tag this process never
+  declared is dropped into `report.errors`, never thrown: a throw kills the subscriber loop and
+  silently ends cross-instance invalidation for the whole process.
+- **`report.cdn` is what depends on the tags; `report.tiers` is what cleared.** The `cdn` tier
+  purges `cdn-path` dependents itself, alongside the tags, so `busted` is built from `tiers` +
+  `isr` + `liveQueries` and never from `cdn` — folding in a list nothing purged is exactly the
+  partial-bust-reading-as-clean this log exists to prevent.
+- A purge driver is selected by `selectPurgeDriver` from the environment, never from an
+  `app.config.ts` field — nothing loads that file's contents at runtime. Two CDN credentials at
+  once is refused, not resolved, and half a pair is refused too: "no CDN" is the one wrong answer,
+  because a deployment then ships believing it purges. The token never reaches a printed string.
+- A purge key is a wire tag unchanged. Every CDN splits a key list on whitespace and a comma, so
+  `assertPurgeableKeys` refuses either **before** the request — a split key is purged successfully
+  and clears nothing, which is the one CDN failure no later read can catch.
+- `retryable` on `X_CACHE_PURGE_FAILED` is derived, never guessed: 408/409/425/429 and 5xx, plus
+  any request that never got a status. That table lives in `purge-http.ts` and is edited there.
+- `X_CACHE_PURGE_FAILED` means a provider refused. A batch size that is not a positive integer is
+  this package miswired, so `chunked()` raises `X_CACHE_DRIVER_UNAVAILABLE` instead — and it raises
+  it *before* the loop, because a `0` spins forever and a `NaN` yields one empty batch, a purge that
+  reports success having cleared nothing.
+- Every `fixFor()` branch names a command, an env key or a call. The gate's `fix:` scanner reads
+  `fix:` properties, not the `return` literals in those functions, so the colocated
+  "every failure fix names a command" tests are the only thing enforcing it.
+- A refusal's diagnostic reads the environment, never a hardcoded pair: `meta.configured` and the
+  cause name the keys that are actually set. Names only — all four keys can hold a credential.
+- A remote driver takes an injected `fetch` so a test never unseals the network; the loopback
+  proof in `purge-fastly.test.ts` is the only place the default one runs.
+
+## Files
+
+| File | Owns |
+|---|---|
+| `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 |
+| `fence.ts` | the invalidation fence a fill (here or in `query`) checks before it publishes |
+| `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` | one in-flight `load()` per key, shared by every concurrent miss |
+| `cdn.ts` | `Cache-Control`/`Surrogate-Key` emission, the `PurgeDriver` seam, `noopPurgeDriver` |
+| `purge-http.ts` | the HTTP half both remote drivers share: one POST, retryable table, batching, key guard |
+| `purge-fastly.ts` | `fastlyPurgeDriver`: surrogate-key batch purge, `purge_all` |
+| `purge-cloudflare.ts` | `cloudflarePurgeDriver`: cache-tag purge, `purge_everything` |
+| `purge-env.ts` | `selectPurgeDriver`: which edge an environment purges, and nothing else |
+| `invalidate.ts` | the single entry point, `InvalidationReport`, and the bounded log `/_x` renders |
+| `semantic.ts` | embedding cache for LLM calls |
+
+## Commands
+
+```
+bun test packages/cache
+bun run --filter @ultimat3/cache typecheck
+```

package/README.md

@@ -27,7 +27,7 @@ Reads walk down until a hit, then populate every tier they walked past. Writes p
 |---|---|---|---|---|
 | 0 | `request-memo` | ALS context (`WeakMap`) | dies with the request | never |
 | 1 | `lru` | in-process, byte-budgeted | tag index | never |
-| 2 | `redis` | `Bun.redis` | tag→keys set, one `EVAL` | single node |
+| 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
@@ -45,6 +45,76 @@ const feed = await stack.read('feed:org-1', () => db.posts.recent(), {
 });
 ```
 
+**`ttlMs` is positive and finite, in every tier.** Omit it for the tier's default; anything else
+is `X_CACHE_TTL_INVALID`. There is no "never expires" and no "do not cache" — `0` used to mean the
+first in the LRU tier and one second in the Redis tier, so a stack holding both answered
+differently depending on which one hit, and neither reading was what the caller meant. A value you
+do not want held is a value you do not put in the cache.
+
+**Every lease is spread.** A tier shortens each `ttlMs` by a random slice of up to 5%
+(`DEFAULT_TTL_JITTER_FRACTION`) before it writes, in `assertTtl` — the one place every tier already
+called. 40,000 keys warmed by one rolling restart otherwise share one expiry instant and all miss
+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
+```
+
+**N concurrent misses are ONE origin load.** `stack.read` shares an in-flight `load()` per key, so
+a reader arriving while another's load is running joins it instead of issuing its own — the share
+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; the stack holds one per stack. 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
+fired.
+
+**A fill obeys an invalidation that raced it.** `load()` answers with rows it read in the past, so a
+bust landing in between finds a key that is not there yet — it reports `errors: []` and the fill
+republishes the pre-write rows for the full TTL, invisibly. `stack.read` samples a fence before the
+load and re-checks it before each tier write; a fill that lost the race is dropped, and anything it
+already wrote is taken back. The caller still gets what the origin answered: a fence declines to
+publish, it never fails a read. It is exported for any cache doing its own read-through:
+
+```ts
+const fence = sampleFence({ key, tags });
+const value = await run();
+if (fence.isValid()) await tier.set(key, value, { tags });
+```
+
+**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:
+
+```ts
+await stack.read(key, () => db.posts.byId(id), { ttlMs: 300_000, negativeTtlMs: 5_000 });
+```
+
+**A promoted hit carries its own remaining life.** When a read hits a far tier and populates the
+closer ones, it writes them with `expiresAt - now`, not with the `ttlMs` the caller passed — a
+fresh full lease on every read is a hot key that never gets stale enough to be refetched. An entry
+already past its expiry is dropped on the way through and the read falls to `load()`. Each tier
+supplies that expiry from its own store, so the number is real: the Redis tier reads `PTTL`
+alongside the value, in the same pipelined round trip.
+
+Every tier call the stack makes is best-effort: a tier that throws on `get`, `set` or `del` is a
+tier that did not answer, so `read`, `write` and `drop` carry on. A feed too big for the LRU
+(`X_CACHE_TOO_LARGE`) or a Redis with no socket costs the entry, never the read. The one call left
+to throw is `load()` — it *is* the business read, and absorbing it would hand back `undefined` as
+though it were the value.
+
+`recentTierFailures()` is where those refusals go: last 100, newest first, each naming the tier, the
+operation, the key and the `X_*` code, and each one also logged as `cache.tier.failed`. Same
+bargain as `report.errors` on the invalidation side — degraded is visible, not merely slow.
+
+`bestEffort(label, op, key, run)` is that guard, exported: a cache that is not a rung of this ladder
+degrades into the same log rather than into a private `try/catch` nobody can read. The label is
+closed (`TierLabel`) so the panel can group by it. `'query-read'` is in that union and emits nothing
+— it named `@ultimat3/query`'s own read cache, a store in no registry, and that store is gone: a
+`cache:` read fills these tiers, so its refusals carry the refusing tier's own name.
+
 ## Tags
 
 ```ts
@@ -66,20 +136,79 @@ declare module '@ultimat3/cache' {
 }
 ```
 
+`declareTags()` takes the manifest's entity names at boot and is **additive and process-wide** —
+once anything is declared, an undeclared tag is `X_CACHE_TAG_UNKNOWN`. A test that declares its own
+fixture entity therefore turns validation on for every later file in the same `bun test` process.
+`isolateDeclaredTags()` is the seam for that — see [Test seams](#test-seams).
+
+## The Redis tier's key layout
+
+| Key | Holds |
+|---|---|
+| `<prefix>:<buildId>:c:<key>` | the value, `SET … PX` |
+| `<prefix>:<buildId>:t:{<entity>}` | members carrying the **collection tag** — `tag('post')` |
+| `<prefix>:<buildId>:t:{<entity>}:<id>` | members carrying **that row's tag** — `tag('post', '1')` |
+| `<prefix>:<buildId>:e:{<entity>}` | members carrying **any** tag of the entity — the index |
+
+Four keys, three jobs, and the fourth is why: `t:` buckets are the tags a caller declared and `e:`
+is the entity index. A **collection bust** reads the index, so it clears the rows too; a **row
+bust** reads that row's bucket and the collection tag's, so `post:2` survives a bust of `post:1`.
+That is `tagMatches` — the same predicate the LRU answers through its two indexes and the request
+memo answers through `tagsIntersect` — and the shared tier is the rung that did not, because `t:`
+served as the index as well: `invalidateTags([tag('post', '1')])` came back with every post-tagged
+key in the store and deleted them, so one row write emptied the shared tier for that entity while
+the in-process tier one rung closer kept exactly the row that had changed.
+`tier-parity.test.ts` compares all three rungs and `redis.live.test.ts` runs the same two busts
+against a real server.
+
+`{<entity>}` is a **Redis Cluster hash tag**, not decoration: it is what makes a row's bucket, its
+collection's bucket and the index hash to one slot, so a script may take them in one `KEYS`.
+Invalidation issues
+**one script call per tag** for that reason — the batched form carried every tag's buckets in one
+`EVAL` and was rejected with `CROSSSLOT` before the script ran, landing in `report.errors` as a
+partial bust while stale rows served until TTL. Value keys are still deleted client-side, one `DEL`
+each, which is slot-local under every topology.
+
+The script **deletes nothing at all** — not the value keys, and not the buckets either. The tier
+`SREM`s exactly the members whose `DEL` succeeded, so a refused delete keeps its membership and the
+retry the error asks for still finds it; dropping the bucket inside the script made that failure
+permanent. A `set` mirrors it: buckets are joined **before** the value is written and membership is
+re-checked after, because a bust that landed in between would otherwise leave a row nothing can
+reach by tag, serving until its own lease ran out.
+
+**Every tag set carries a lease**, renewed on each write to the member's own TTL plus 60s, raised
+only when the new lease is longer — a 60s member must not shorten a bucket a 1h member is in.
+Without it a tag set grew forever: value keys died after five minutes, their membership never did,
+and after a month `SMEMBERS` on a multi-million-member set blocked the server for hundreds of
+milliseconds and answered with a list the client then `DEL`'d in batches. One publish became a
+Redis outage. The renewal is a script (`REDIS_TAG_MEMBER_SCRIPT`, one key in `KEYS`) rather than
+`EXPIRE … GT`, because `GT` treats a key with no TTL as infinite and would leave a **fresh** bucket
+immortal — which is the bug being fixed.
+
+**`buildId` defaults to `appVersion()`** (`APP_VERSION`, else `dev`), so two builds sharing one
+Redis cannot read each other's payloads. Rename `PostView.author` to `PostView.authorId` and
+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
+your own payloads.
+
 ## Invalidating
 
 ```ts
 const report = await invalidateTags([tag('post', postId)]);
 ```
 
-One function. Returns the report the `/_x` cache panel and `x cache bust --json` render:
+One function. It returns the report below, which is also what the `/_x` cache panel renders — and
+what `x cache bust --json` will print once it ships; that command is planned and exits
+`X_NOT_IMPLEMENTED` today.
 
 ```json
 {
   "tags": ["post:1"],
   "tiers": [{ "tier": "lru", "keys": ["feed"] }, { "tier": "redis", "keys": ["feed"] }],
   "isr": ["/blog", "/blog/hello"],
-  "cdn": ["post:1"],
+  "cdn": ["/feed.xml"],
   "liveQueries": [],
   "durationMs": 1.4,
   "errors": []
@@ -89,11 +218,79 @@ One function. Returns the report the `/_x` cache panel and `x cache bust --json`
 A dead tier lands in `errors` and never throws — a Redis outage must not fail the write
 that triggered the bust. Entries there expire by TTL instead.
 
+The fan-out walks the ladder **farthest tier first** — Redis before the LRU before the request memo
+— and reports in read order. Clearing near-to-far leaves the far tier holding the old value after
+the near ones are clear, and a read racing the bust promotes it straight back up into them: every
+tier reports cleared and the LRU is stale again before the call returns. `stack.drop(key)` reverses
+for the same reason.
+
+`cdn` is what the dependency graph hangs off these tags, not what cleared: the `cdn` tier purges
+those paths (as surrogate keys, alongside the tags), so what actually cleared is that tier's row
+in `tiers`. With no `cdn` tier registered the list purges nowhere, which is why
+`recentInvalidations()` reports `busted` from `tiers` and never from `cdn` — a partial bust that
+reads as a clean one is the failure that log exists to catch.
+
 Every report is also kept: `recentInvalidations()` hands back the last 100, newest first, each
 one naming the span that triggered it. That is the log the `/_x` cache panel renders — "did it
 actually clear?" is answerable without a log dive because the one fan-out path retained the
 answer, not because a second recorder was wired next to it.
 
+### Across instances
+
+`invalidateTags` clears the tiers of the process that called it. On a fleet that is one pod: a user
+edits their profile on pod 3, their next request lands on pod 7, and pod 7's LRU serves the pre-edit
+value for up to `defaultTtlMs`. Cache ships the **seam**, not the transport — it is tier 1 and may
+not reach `realtime` or a message bus — and whoever owns the transport (`@ultimat3/cli`) wires it at
+boot, exactly as `@ultimat3/render` wires the `Revalidator`:
+
+```ts
+registerInvalidationBroadcast(async (wireTags) => bus.publish('cache.invalidate', wireTags));
+bus.subscribe('cache.invalidate', (wireTags) => receiveInvalidationBroadcast(wireTags));
+```
+
+| Half | Function | Emits? |
+|---|---|---|
+| outbound | `registerInvalidationBroadcast(fn)` — `fn(wireTags: readonly string[])`, called last, best-effort | — |
+| inbound | `receiveInvalidationBroadcast(wireTags)` → `InvalidationReport` | **never** |
+
+The inbound half **cannot** re-emit, and that is structural rather than a flag: `emit` lives on the
+private fan-out options and `receiveInvalidationBroadcast` is the only caller that passes `false`.
+A receiver that re-broadcast would be a storm bounded by nothing. A failed send lands in
+`report.errors` under `tier: "broadcast"` — the other pods then clear on TTL, and the write that
+triggered the bust still succeeds. An inbound tag this process has not declared is dropped and
+reported rather than thrown, because mid-deploy the new pods know an entity the old ones do not and
+a throw would kill the subscriber loop that delivered it.
+
+## Test seams
+
+Every registry here is process-global and `bun test` is one process, so a suite undoes its own
+registrations with an `isolate*()` — **capture and restore, never a reset**:
+
+```ts
+const restoreTags = isolateDeclaredTags();
+declareTags(['fixture']);
+afterAll(restoreTags);
+```
+
+| Helper | Puts back |
+|---|---|
+| `isolateDeclaredTags()` | the declared-tag set |
+| `isolateGraph()` | every tag → dependent edge, across all three indexes |
+| `isolateTiers()` | everything `resetTiers()` drops: the tier registry in registration order, the revalidator, the invalidation broadcast, `recentInvalidations()` and `recentTierFailures()` |
+
+Each returns the function that puts back **exactly what it found**, so a per-test `resetGraph()` is
+still fine — pair it with the module-scope isolate and the process gets its baseline back. A reset
+alone is not a substitute: it drops what a neighbouring file registered, and
+`@ultimat3/testing`'s leak guard compares its samples for *additions*, so the loss is invisible to
+it and surfaces as a failure in an innocent file. That is the one leak no mechanism catches for you.
+The last two live in the modules that own the state because a test file cannot reach it: the
+revalidator has no reader, and neither log has a writer.
+
+**`resetTierFailures()` and `isolateTierFailures()` are deliberately off `index.ts`.** Nothing
+outside this package clears that log except through `resetTiers()`, which `isolateTiers()` already
+covers — so a suite outside `packages/cache` isolates the tiers and gets the failure log with them.
+`recentTierFailures()` is the only member of that module the public surface carries.
+
 ## CDN
 
 ```ts
@@ -103,7 +300,9 @@ cacheHeaders({ sMaxAge: 300, staleWhileRevalidate: 86_400, tags: [tag('post', id
 ```
 
 The surrogate keys **are** the tags, byte for byte, so an edge purge and an app-level
-invalidation can never mean different things. Three `PurgeDriver`s ship:
+invalidation can never mean different things. 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:
 
 | Driver | Purge | Purge all | Batch |
 |---|---|---|---|
@@ -142,9 +341,11 @@ cache).
 | Code | Cause |
 |---|---|
 | `X_CACHE_DRIVER_UNAVAILABLE` | `Bun.redis` missing, a purge driver built without its token, or a batch size that is not a positive integer |
+| `X_CACHE_JITTER_INVALID` | a tier's `jitterFraction` outside `[0, 1)` |
 | `X_CACHE_PURGE_FAILED` | the CDN refused a purge, or a key it would split on whitespace |
 | `X_CACHE_TAG_UNKNOWN` | a tag no entity declared — usually a typo |
 | `X_CACHE_TOO_LARGE` | one entry exceeds a tier's whole byte budget |
+| `X_CACHE_TTL_INVALID` | a `ttlMs` that is not a positive, finite number of milliseconds |
 
 ## Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "1.2.0",
+  "version": "3.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",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "3.0.0"
   }
 }

package/src/cdn.ts

@@ -3,6 +3,7 @@
 // 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.
 
+import { dependentsOfKind } from './graph';
 import type { CacheTag } from './tags';
 import { serializeTags } from './tags';
 import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
@@ -96,8 +97,18 @@ export function createCdnTier(options: CdnTierOptions = {}): CacheTier {
       if (paths.length > 0) await driver.purge(paths);
     },
 
+    /**
+     * The tags themselves 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
+     * `s-maxage`: a partial bust reading as a clean one, which is the one failure the report
+     * exists to prevent. They go out **as surrogate keys**, the single currency `PurgeDriver`
+     * has — the same convention `pathsForKey` already documents, so a host registering a
+     * `cdn-path` dependent must tag that response with its own path.
+     */
     async invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
-      const keys = serializeTags(tags);
+      const keys = [...new Set([...serializeTags(tags), ...dependentsOfKind(tags, 'cdn-path')])];
       if (keys.length === 0) return { tier: 'cdn', keys: [] };
       const accepted = await driver.purge(keys);
       return { tier: 'cdn', keys: accepted };