@ultimat3/cache 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -18,13 +18,13 @@ 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`,
@@ -36,11 +36,11 @@ Tier 1. Tagged caching + THE invalidation graph.
 - **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`.
@@ -49,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()`,
@@ -68,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
@@ -95,7 +95,11 @@ 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
+- **Every tier stores codec TEXT, never the caller's object** (`value-codec.ts`: JSON + tagged
+  `Date`/`bigint`/`Map`/`Set`, app `$x` keys escaped). One shape whichever tier hit, no shared
+  mutable reference; a cycle, depth > 512 or a bigint > 4096 chars is `X_CACHE_VALUE_UNENCODABLE`
+  at the write. Only `x1:`-marked text is revived; unmarked (pre-codec) is plain `JSON.parse`.
+- **`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
@@ -148,7 +152,7 @@ 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 |
@@ -156,8 +160,8 @@ Tier 1. Tagged caching + THE invalidation graph.
 | `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) |
+| `value-codec.ts` | the one value encoding every tier stores and decodes |
 | `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, `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` |

package/README.md

@@ -32,12 +32,12 @@ Reads walk down until a hit, then populate every tier they walked past. Writes p
 
 A tier is a `CacheTier` (`get`/`set`/`del`/`invalidateTags`, plus an optional `fence` for a tier
 other processes also write). Swap or omit any of them
-without touching a call site — order comes from `TIER_ORDER`, not registration order.
+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(), {
@@ -46,6 +46,22 @@ const feed = await stack.read('feed:org-1', () => db.posts.recent(), {
 });
 ```
 
+**Cached values: JSON + `Date` + `bigint` + `Map` + `Set` — the same shape from every tier.**
+Every tier (the memo and the LRU included) stores the value as text through one codec
+(`value-codec.ts`) and decodes a fresh copy on each hit, so:
+
+| You write | Every tier answers |
+|---|---|
+| a `Date`, a `bigint`, a `Map`, a `Set` (at any depth) | the same type back |
+| a plain object, array, string, number, boolean, `null` | JSON semantics: `NaN`/`Infinity` → `null`, `undefined` members dropped |
+| a class instance | a plain object — its prototype is not stored |
+| a cycle, a `toJSON` that throws, nesting past `MAX_CACHE_VALUE_DEPTH` (512), a `bigint` past `MAX_CACHE_BIGINT_DIGITS` (4096 chars) | `X_CACHE_VALUE_UNENCODABLE`, at the write — a value is stored and readable, or refused |
+
+A hit is never the object that was written, nor the one another reader got: mutating it changes
+nothing in the cache. An app key spelled `$x` (or `$$x`…) is escaped on the way in. The stored text
+is `x1:` + JSON; only marked text is revived, so a Redis entry written as plain JSON before the
+codec reads back exactly as stored — never revived, never renamed.
+
 **`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
@@ -58,9 +74,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
@@ -68,13 +84,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
@@ -96,7 +112,7 @@ if (fence.isValid()) await tier.set(key, value, { tags });
 **That fence is this process's; the Redis tier keeps a second one for the fleet.** A bust another
 replica ran reaches this process only when the broadcast does, and a lost broadcast means never —
 so the fill would publish the pre-write rows into the *shared* tier and every replica would promote
-them. `createRedisTier` implements `CacheTier.fence`: a bust writes a leased generation
+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`.
 
@@ -222,7 +238,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
@@ -382,11 +398,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
@@ -399,6 +415,7 @@ cache).
 | `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 |
+| `X_CACHE_VALUE_UNENCODABLE` | a value with a cycle, a throwing `toJSON`, nesting past 512 levels or a `bigint` past 4096 digits, written to any tier |
 
 ### Error classes
 
@@ -414,6 +431,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `CacheTagUnknownError` | `X_CACHE_TAG_UNKNOWN` | `src/errors.ts` |
 | `CacheTooLargeError` | `X_CACHE_TOO_LARGE` | `src/errors.ts` |
 | `CacheTtlInvalidError` | `X_CACHE_TTL_INVALID` | `src/errors.ts` |
+| `CacheValueUnencodableError` | `X_CACHE_VALUE_UNENCODABLE` | `src/errors.ts` |
 
 ## Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "24.0.0",
+  "version": "25.1.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": "24.0.0"
+    "@ultimat3/core": "25.1.0"
   }
 }

package/src/cdn.ts

@@ -125,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';
@@ -140,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 {

package/src/errors.ts

@@ -11,6 +11,7 @@ export const CACHE_OWNED_ERROR_CODES = [
   'X_CACHE_TAG_UNKNOWN',
   'X_CACHE_TOO_LARGE',
   'X_CACHE_TTL_INVALID',
+  'X_CACHE_VALUE_UNENCODABLE',
 ] as const;
 
 /** Every code cache can throw. It borrows none: every remote driver here is implemented. */
@@ -27,6 +28,7 @@ export const CACHE_ERROR_TITLES: Readonly<Record<CacheOwnedErrorCode, string>> =
   X_CACHE_TAG_UNKNOWN: 'a tag no entity declared',
   X_CACHE_TOO_LARGE: "one entry exceeds the tier's byte budget",
   X_CACHE_TTL_INVALID: 'a cache TTL that is not a positive number of milliseconds',
+  X_CACHE_VALUE_UNENCODABLE: 'a cached value the cache codec cannot encode',
 };
 
 // One unconditional call, so a second package claiming one of cache's codes throws
@@ -73,6 +75,23 @@ export class CacheTooLargeError extends UltimateError {
   }
 }
 
+/**
+ * A value the cache codec (`value-codec.ts`) cannot write: a cycle, a `toJSON` that throws, nesting
+ * past `MAX_CACHE_VALUE_DEPTH`, or a `bigint` past `MAX_CACHE_BIGINT_DIGITS`. Refused at the WRITE, in every tier alike — the LRU used to hold it by reference while Redis
+ * threw a bare `TypeError`, so the same `set` worked on one rung and failed on the next. `reason`
+ * is `renderThrowable` output, never the value: a cached value is application data.
+ */
+export class CacheValueUnencodableError extends UltimateError {
+  constructor(input: { key: string; tier: string; reason: string }) {
+    super({
+      code: 'X_CACHE_VALUE_UNENCODABLE',
+      cause: `entry "${input.key}" cannot be written to the ${input.tier} tier: ${input.reason}. A cache tier holds JSON plus Date, bigint, Map and Set, the same shape on every tier`,
+      fix: 'load: () => rows.map(({ parent, ...row }) => row) — cache a projection the codec reads back: plain objects, no back-references, nesting under 512 levels, a bigint past 4096 digits stored as a string',
+      meta: { key: input.key, tier: input.tier },
+    });
+  }
+}
+
 /**
  * A LIMIT this package runs on that is not one — a tier's byte budget, its entry ceiling, the
  * similarity floor the semantic tier decides "same question" with, or a purge driver's request
@@ -108,7 +127,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

@@ -3,7 +3,7 @@
 export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
 export {
   cacheHeaders,
-  createCdnTier,
+  cdnTier,
   isNoopPurgeDriver,
   noopPurgeDriver,
   surrogateKeys,
@@ -19,6 +19,7 @@ export {
   CacheTagUnknownError,
   CacheTooLargeError,
   CacheTtlInvalidError,
+  CacheValueUnencodableError,
 } from './errors';
 export type { CacheFence, FenceScope } from './fence';
 export { FENCE_MEMORY, markInvalidated, sampleFence } from './fence';
@@ -53,8 +54,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,
@@ -69,10 +70,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,
@@ -81,9 +82,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,
@@ -121,11 +120,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

@@ -17,6 +17,7 @@ import type {
   TtlJitter,
 } from './tiers';
 import { assertFiniteCapacity, assertFiniteDurationMs, assertTtl, nowMs } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
 export interface LruOptions {
   /** Byte budget for the whole tier. Default 64 MiB. */
@@ -32,7 +33,12 @@ export interface LruOptions {
 
 interface LruNode {
   key: string;
-  value: unknown;
+  /**
+   * `{ v }` as `value-codec.ts` text, never the caller's object: held by reference, a hit was the
+   * writer's live object — mutated by one reader for every later one — and a `Date` here was an
+   * ISO string on the pod that read the same entry back out of Redis.
+   */
+  text: string;
   bytes: number;
   /** Epoch ms. Always finite: `assertTtl` refuses the `0` that used to mean "never expires". */
   expiresAt: number;
@@ -141,11 +147,15 @@ export class LruCache {
     }
     this.touch(node);
     this.hits += 1;
-    return { value: node.value as T, tags: node.tags, expiresAt: node.expiresAt };
+    const { v } = decodeCacheValue(node.text) as { readonly v: T };
+    return { value: v, tags: node.tags, expiresAt: node.expiresAt };
   }
 
   set<T>(key: string, value: T, options: CacheSetOptions = {}): void {
-    const bytes = estimateBytes(value) + encoder.encode(key).byteLength;
+    // Encoded first: the budget is then the exact bytes held, and an unencodable value is refused
+    // before anything is evicted for it.
+    const text = encodeCacheValue({ v: value }, { key, tier: 'lru' });
+    const bytes = estimateBytes(text) + encoder.encode(key).byteLength;
     if (bytes > this.maxBytes) {
       throw new CacheTooLargeError({ key, bytes, maxBytes: this.maxBytes, tier: 'lru' });
     }
@@ -158,7 +168,7 @@ export class LruCache {
 
     const node: LruNode = {
       key,
-      value,
+      text,
       bytes,
       expiresAt: nowMs(this.clock) + ttl,
       tags: options.tags ?? [],
@@ -273,7 +283,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

@@ -10,8 +10,18 @@ import type { CacheTag } from './tags';
 import { tagsIntersect } from './tags';
 import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
 import { assertTtl } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
-type MemoStore = Map<string, CacheEntry<unknown>>;
+/**
+ * Codec text, as in every other tier: two callers in one request reading one key must not share
+ * one mutable object, and a hit here must be the shape the LRU or Redis would have answered.
+ */
+interface MemoEntry {
+  readonly text: string;
+  readonly tags: readonly CacheTag[];
+}
+
+type MemoStore = Map<string, MemoEntry>;
 
 const stores = new WeakMap<object, MemoStore>();
 
@@ -46,14 +56,16 @@ export function memoSize(): number {
   return storeFor(false)?.size ?? 0;
 }
 
-export function createMemoTier(): CacheTier {
+export function memoTier(): CacheTier {
   return {
     name: 'request-memo',
 
     get<T>(key: string): Promise<CacheEntry<T> | undefined> {
       const entry = storeFor(false)?.get(key);
       // No TTL check: a request is shorter than any meaningful TTL.
-      return Promise.resolve(entry as CacheEntry<T> | undefined);
+      if (entry === undefined) return Promise.resolve(undefined);
+      const { v } = decodeCacheValue(entry.text) as { readonly v: T };
+      return Promise.resolve({ value: v, tags: entry.tags });
     },
 
     /**
@@ -61,21 +73,22 @@ 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> {
       if (options?.ttlMs !== undefined) {
         assertTtl(key, options.ttlMs, 'request-memo', { jitterFraction: 0 });
       }
-      storeFor(true)?.set(key, { value, tags: options?.tags ?? [] });
+      const text = encodeCacheValue({ v: value }, { key, tier: 'request-memo' });
+      storeFor(true)?.set(key, { text, tags: options?.tags ?? [] });
     },
 
     del(key: string): 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-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.ts

@@ -19,6 +19,7 @@ import type {
   TtlJitter,
 } from './tiers';
 import { assertFiniteDurationMs, assertTtl, nowMs } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
 /** The slice of Bun's Redis client this tier uses. Narrow on purpose: easy to fake in tests. */
 export interface RedisLike {
@@ -191,7 +192,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',
@@ -285,7 +286,9 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       // death handed a fresh five minutes, one tier closer to the request.
       if ('kind' in lease && lease.kind === 'reaped') return undefined;
       try {
-        const parsed = JSON.parse(raw) as StoredEntry;
+        // `decodeCacheValue`, not `JSON.parse`: the LRU decodes with the same codec, so a `Date`
+        // promoted out of here is a `Date` there too. Plain JSON written before the codec reads as-is.
+        const parsed = decodeCacheValue(raw) as StoredEntry;
         return {
           value: parsed.v as T,
           tags: parsed.t.map(parseTag),
@@ -314,6 +317,8 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
       const tags = setOptions?.tags ?? [];
       const ttlMs = assertTtl(key, setOptions?.ttlMs ?? defaultTtlMs, 'redis', jitter);
       const payload: StoredEntry = { v: value, t: tags.map(serializeTag) };
+      // Before any bucket is joined: an unencodable value is refused with nothing left behind.
+      const text = encodeCacheValue(payload, { key, tier: 'redis' });
       const stored = valueKey(key);
       // `PX`, not `EX`: the value's lease is spent in the milliseconds it was validated and
       // jittered in. `Math.ceil(ttlMs / 1000)` honoured a 1,001ms lease as 2s — rounding toward
@@ -329,7 +334,7 @@ export function createRedisTier(options: RedisTierOptions = {}): CacheTier {
           conn().send('EVAL', [TAG_MEMBER_SCRIPT, '1', bucket, stored, bucketTtlSeconds]),
         ),
       );
-      await conn().send('SET', [stored, JSON.stringify(payload), 'PX', String(Math.ceil(ttlMs))]);
+      await conn().send('SET', [stored, text, 'PX', String(Math.ceil(ttlMs))]);
       if (buckets.length === 0) return;
       const membership = await Promise.all(
         buckets.map((bucket) => conn().send('SISMEMBER', [bucket, stored])),

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/tiers.ts

@@ -4,12 +4,11 @@
 // 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, 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';
@@ -24,14 +23,14 @@ import { sampleTierFences, verdictOf } from './tier-fence';
  */
 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.
  *
@@ -220,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));
 }
 
 /**
@@ -254,7 +253,7 @@ export interface CacheStackOptions {
   readonly schedule?: Scheduler;
 }
 
-export function createCacheStack(
+export function cacheStack(
   tiers: readonly CacheTier[],
   options: CacheStackOptions = {},
 ): CacheStack {
@@ -267,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,
   });

package/src/value-codec.ts

@@ -0,0 +1,167 @@
+// The ONE encoding every cache tier stores a value in: JSON, plus tagged `Date`, `bigint`, `Map`
+// and `Set`. One codec is what makes a hit the same shape whichever rung answered it — and since
+// every tier stores TEXT, no two readers ever share one mutable object. Lives here, not in
+// `@ultimat3/query`'s cursor codec: query is tier 3, and this package is tier 1.
+
+import { renderThrowable } from '@ultimat3/core';
+import { CacheValueUnencodableError } from './errors';
+
+/** The member that marks a tagged value. Only this codec writes it; an app's own is escaped. */
+const TAG = '$x';
+/** `$x`, `$$x`, `$$$x`…: an app key that could be read as a tag, written with one more `$`. */
+const ESCAPABLE = /^\$+x$/;
+/** What an escaped app key looks like on the way back: two or more `$`. */
+const ESCAPED = /^\$\$+x$/;
+const DIGITS = /^-?\d+$/;
+
+/**
+ * The deepest a cached value may nest. `JSON.parse` with a reviver recurses, and overflows the
+ * stack somewhere between 5k and 20k levels that `JSON.stringify` wrote without complaint — so a
+ * deeper value was stored and then unreadable on every hit until its TTL. Refused at the write.
+ */
+export const MAX_CACHE_VALUE_DEPTH = 512;
+
+/**
+ * The longest `bigint` a cached value may hold, in characters. `BigInt(text)` is super-linear: a
+ * million digits throws a `RangeError`, 300k take over a second. 4096 is far past any column type
+ * (`numeric` aside) and costs microseconds.
+ */
+export const MAX_CACHE_BIGINT_DIGITS = 4096;
+
+/**
+ * Prefixed to every text this codec writes. No JSON text starts with `x`, so an unmarked entry —
+ * a Redis value written by a pod from before the codec — is read with plain `JSON.parse`, and app
+ * data that happens to look like a tag (`{"$x":"bigint","v":"12"}`) or an escape (`$$x`) is
+ * handed back exactly as it was stored, never revived or renamed.
+ */
+export const CACHE_CODEC_MARK = 'x1:';
+
+type Tagged = { readonly [TAG]: 'date' | 'bigint' | 'map' | 'set'; readonly v: unknown };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** A copy with every tag-shaped key given one more `$`, or the object itself when it has none. */
+const escapeKeys = (value: Record<string, unknown>): Record<string, unknown> => {
+  const keys = Object.keys(value);
+  if (!keys.some((key) => ESCAPABLE.test(key))) return value;
+  return Object.fromEntries(keys.map((key) => [ESCAPABLE.test(key) ? `$${key}` : key, value[key]]));
+};
+
+const unescapeKeys = (value: Record<string, unknown>): Record<string, unknown> => {
+  const keys = Object.keys(value);
+  if (!keys.some((key) => ESCAPED.test(key))) return value;
+  return Object.fromEntries(
+    keys.map((key) => [ESCAPED.test(key) ? key.slice(1) : key, value[key]]),
+  );
+};
+
+/**
+ * `this[key]`, not `value`: `JSON.stringify` calls `Date#toJSON` BEFORE the replacer sees it, so
+ * the argument is already a string — the holder still has the `Date`.
+ */
+function transform(holder: unknown, key: string, value: unknown): unknown {
+  const raw =
+    isRecord(holder) || Array.isArray(holder) ? (holder as Record<string, unknown>)[key] : value;
+  if (raw instanceof Date) {
+    return { [TAG]: 'date', v: Number.isNaN(raw.getTime()) ? null : raw.toISOString() };
+  }
+  if (typeof raw === 'bigint') {
+    const digits = raw.toString();
+    if (digits.length > MAX_CACHE_BIGINT_DIGITS) {
+      throw new CacheCodecLimit(
+        `a bigint of ${digits.length} characters, over the ${MAX_CACHE_BIGINT_DIGITS} a cache holds`,
+      );
+    }
+    return { [TAG]: 'bigint', v: digits };
+  }
+  if (raw instanceof Map) return { [TAG]: 'map', v: [...raw.entries()] };
+  if (raw instanceof Set) return { [TAG]: 'set', v: [...raw] };
+  return isRecord(value) ? escapeKeys(value) : value;
+}
+
+/** A limit this codec refuses at, carried out of `JSON.stringify` to `encodeCacheValue`. */
+class CacheCodecLimit {
+  constructor(readonly reason: string) {}
+}
+
+/**
+ * A replacer that knows how deep it is: every container it hands back is filed under its depth,
+ * and `JSON.stringify` calls it with that container as `this` for each member — one map lookup
+ * per node, no second walk. A cycle never reaches the cap: `JSON.stringify` refuses it first.
+ */
+const replacerWithDepth = (): ((this: unknown, key: string, value: unknown) => unknown) => {
+  const depths = new WeakMap<object, number>();
+  return function replace(this: unknown, key: string, value: unknown): unknown {
+    const out = transform(this, key, value);
+    if (typeof out !== 'object' || out === null) return out;
+    const depth = (typeof this === 'object' && this !== null ? (depths.get(this) ?? 0) : 0) + 1;
+    if (depth > MAX_CACHE_VALUE_DEPTH) {
+      throw new CacheCodecLimit(
+        `nested deeper than the ${MAX_CACHE_VALUE_DEPTH} levels a cache reads back`,
+      );
+    }
+    depths.set(out, depth);
+    return out;
+  };
+};
+
+const isEntryList = (value: unknown): value is [unknown, unknown][] =>
+  Array.isArray(value) && value.every((entry) => Array.isArray(entry) && entry.length === 2);
+
+/** The tagged value back, or `undefined` when `value` is not one this codec wrote. */
+const untag = (value: Record<string, unknown>): { readonly revived: unknown } | undefined => {
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !Object.hasOwn(value, TAG) || !Object.hasOwn(value, 'v')) return;
+  const { v } = value as Tagged;
+  switch (value[TAG]) {
+    case 'date':
+      return v === null || typeof v === 'string'
+        ? { revived: new Date(v ?? Number.NaN) }
+        : undefined;
+    case 'bigint':
+      // Length first: text past the cap was not written by `encodeCacheValue`, and `BigInt` on it
+      // is the expensive call.
+      return typeof v === 'string' && v.length <= MAX_CACHE_BIGINT_DIGITS && DIGITS.test(v)
+        ? { revived: BigInt(v) }
+        : undefined;
+    case 'map':
+      return isEntryList(v) ? { revived: new Map(v) } : undefined;
+    case 'set':
+      return Array.isArray(v) ? { revived: new Set(v) } : undefined;
+    default:
+      return undefined;
+  }
+};
+
+/** Bottom-up, so a tagged value's members are already revived when the tag itself is read. */
+const revive = (_key: string, value: unknown): unknown => {
+  if (!isRecord(value)) return value;
+  const tagged = untag(value);
+  return tagged === undefined ? unescapeKeys(value) : tagged.revived;
+};
+
+/**
+ * `payload` as the text a tier stores, marked with `CACHE_CODEC_MARK`. A cycle, a throwing
+ * `toJSON`, nesting past `MAX_CACHE_VALUE_DEPTH` or a bigint past `MAX_CACHE_BIGINT_DIGITS` is
+ * `X_CACHE_VALUE_UNENCODABLE`, naming the key and the tier: what is written is always readable.
+ */
+export function encodeCacheValue(payload: unknown, at: { key: string; tier: string }): string {
+  try {
+    // `?? 'null'`: a top-level `undefined` or function is no JSON text at all.
+    return `${CACHE_CODEC_MARK}${JSON.stringify(payload, replacerWithDepth()) ?? 'null'}`;
+  } catch (error) {
+    const reason = error instanceof CacheCodecLimit ? error.reason : renderThrowable(error);
+    throw new CacheValueUnencodableError({ ...at, reason });
+  }
+}
+
+/**
+ * The inverse. Marked text is revived — only an object of exactly `{ $x, v }` with a tag this
+ * codec knows. Unmarked text predates the codec and is plain `JSON.parse`. Throws what
+ * `JSON.parse` throws; a tier reading text it did not write decides what a corrupt entry means.
+ */
+export function decodeCacheValue(text: string): unknown {
+  if (!text.startsWith(CACHE_CODEC_MARK)) return JSON.parse(text);
+  return JSON.parse(text.slice(CACHE_CODEC_MARK.length), revive);
+}

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';