@ultimat3/cache 24.0.0 → 25.0.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,7 @@ Tier 1. Tagged caching + THE invalidation graph.
   collection bust and `t:{entity}:<id>` + `t:{entity}` for a row one. A row bust still `SREM`s what
   it deleted from the index (`sweepBucketsFor`). Pinned by `tier-parity.test.ts` and
   `redis.live.test.ts`.
-- **`CacheTier.set` REJECTS, never throws synchronously** — `createLruTier`/`createMemoTier` are
+- **`CacheTier.set` REJECTS, never throws synchronously** — `lruTier`/`memoTier` are
   `async` for that alone.
 - **`redis.ts`'s script deletes NOTHING — it reads.** It returns the members; the tier `DEL`s them
   client-side one key at a time (slot-local on Cluster/Dragonfly) and `SREM`s only what
@@ -148,7 +148,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 |
@@ -157,7 +157,6 @@ Tier 1. Tagged caching + THE invalidation graph.
 | `memo.ts` | request memo over the ALS ctx (WeakMap, no lifecycle) |
 | `lru.ts` | byte-budgeted LRU (linked list + map + tag index) |
 | `redis.ts` | `Bun.redis` tier, build-namespaced keys, hash-tagged buckets, one script call per tag |
-| `single-flight.ts` | the door onto `@ultimat3/core`'s `createSingleFlight` — one in-flight `load()` per key, shared by every concurrent miss. No implementation of its own since 2026-08-23 |
 | `cdn.ts` | `Cache-Control`/`Surrogate-Key` emission, `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(), {
@@ -58,9 +58,9 @@ called. 40,000 keys warmed by one rolling restart otherwise share one expiry ins
 inside the same 30-second window. The roll is injected, never `Math.random()` at a call site:
 
 ```ts
-createLruTier({ rng: () => 0 });          // the full lease — what a test asserting an exact expiry wants
-createRedisTier({ jitterFraction: 0 });   // off entirely
-createRedisTier({ jitterFraction: 0.2 }); // a wider spread; outside [0, 1) is X_CACHE_JITTER_INVALID
+lruTier({ rng: () => 0 });          // the full lease — what a test asserting an exact expiry wants
+redisTier({ jitterFraction: 0 });   // off entirely
+redisTier({ jitterFraction: 0.2 }); // a wider spread; outside [0, 1) is X_CACHE_JITTER_INVALID
 ```
 
 **N concurrent misses are ONE origin load.** `stack.read` shares an in-flight `load()` per key, so
@@ -68,13 +68,13 @@ a reader arriving while another's load is running joins it instead of issuing it
 ends as the load settles, rejection included, so one failure is never held as a permanent one. A
 feed cached for 60s and read 8,000×/s otherwise sends ~1,600 identical queries to Postgres at every
 TTL boundary, because the write only lands after `load()` resolves. The primitive is
-`createSingleFlight()` if you need it elsewhere — `@ultimat3/core`'s, re-exported here unchanged;
-the stack holds one per stack.
+`singleFlight()` from `@ultimat3/core` if you need it elsewhere (25.0.0 dropped this
+package's re-export); the stack holds one per stack.
 A `load()` that never settles does **not** hold its key for ever: past `loadDeadlineMs`
 (`DEFAULT_LOAD_DEADLINE_MS`, 30s — the point at which `http.requestTimeoutMs` already abandoned the
 request that was waiting for it) the key is freed and the next reader loads for itself. Eviction
 frees the key and never the work, so the readers already holding that load still get its answer,
-and the cost is one duplicate fill — `createCacheStack(tiers, { loadDeadlineMs: 5_000 })` for a
+and the cost is one duplicate fill — `cacheStack(tiers, { loadDeadlineMs: 5_000 })` for a
 tighter ceiling on a fast origin. A joiner shares the
 leader's **write** as well as its load, so it contributes to it: tags union, TTLs take the shortest.
 Without that the entry landed carrying only the leader's tags and the joiner's invalidation never
@@ -96,7 +96,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 +222,7 @@ Redis cannot read each other's payloads. Rename `PostView.author` to `PostView.a
 deploy: `JSON.parse` does not validate, so the old pod reads the new shape back and hands it to a
 renderer expecting the old one — an undefined author on every cached post, on half the fleet, for
 the length of the rolling deploy. The cost of the default is a **cold shared tier per deploy**,
-which is the cheaper of the two. Opt out with `createRedisTier({ buildId: null })` if you version
+which is the cheaper of the two. Opt out with `redisTier({ buildId: null })` if you version
 your own payloads.
 
 ## Invalidating
@@ -382,11 +382,11 @@ rather than failing the write that triggered it.
 ## Semantic cache
 
 For LLM calls, where "list my orders" and "show me my orders" must hit the same entry.
-`createMemorySemanticCache()` does cosine similarity at a 0.92 threshold (tight on
+`memorySemanticCache()` does cosine similarity at a 0.92 threshold (tight on
 purpose — a false hit answers the wrong question, which is worse than a miss) and is the
 only backing this package ships — it is O(n) and in-process. The interface (`SemanticCache`)
 is a driver seam for that reason; a Postgres/pgvector-backed implementation does not exist
-yet here (`@ultimat3/ai`'s `PgVectorStore` is a separate store, for RAG retrieval, not this
+yet here (`@ultimat3/ai`'s `postgresVectorStore()` is a separate store, for RAG retrieval, not this
 cache).
 
 ## Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.0.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

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

package/src/index.ts

@@ -3,7 +3,7 @@
 export type { CacheHeaderOptions, CdnTierOptions, PurgeDriver } from './cdn';
 export {
   cacheHeaders,
-  createCdnTier,
+  cdnTier,
   isNoopPurgeDriver,
   noopPurgeDriver,
   surrogateKeys,
@@ -53,8 +53,8 @@ export {
 } from './invalidate';
 export type { LruOptions, LruStats } from './lru';
 
-export { createLruTier, estimateBytes, LruCache } from './lru';
-export { clearMemo, createMemoTier, memoSize } from './memo';
+export { estimateBytes, LruCache, lruTier } from './lru';
+export { clearMemo, memoSize, memoTier } from './memo';
 export type { CloudflarePurgeOptions } from './purge-cloudflare';
 export {
   CLOUDFLARE_API_URL,
@@ -69,10 +69,10 @@ export type { PurgeFetch } from './purge-http';
 export { DEFAULT_PURGE_TIMEOUT_MS } from './purge-http';
 export type { RedisLike, RedisTierOptions } from './redis';
 export {
-  createRedisTier,
   namespaceFor,
   REDIS_INVALIDATE_SCRIPT,
   REDIS_TAG_MEMBER_SCRIPT,
+  redisTier,
 } from './redis';
 export type {
   Embedding,
@@ -81,9 +81,7 @@ export type {
   SemanticHit,
   SemanticRememberOptions,
 } from './semantic';
-export { cosineSimilarity, createMemorySemanticCache } from './semantic';
-export type { FlightJoin, SingleFlight } from './single-flight';
-export { createSingleFlight } from './single-flight';
+export { cosineSimilarity, memorySemanticCache } from './semantic';
 export type { CacheTag, CacheTagRegistry, TagFactory } from './tags';
 export {
   assertKnownTags,
@@ -121,11 +119,10 @@ export {
   assertFiniteDurationMs,
   assertFiniteSimilarityFloor,
   assertTtl,
-  createCacheStack,
+  cacheStack,
   DEFAULT_LOAD_DEADLINE_MS,
   DEFAULT_TTL_JITTER_FRACTION,
   isExpired,
   nowMs,
   sortTiers,
-  TIER_ORDER,
 } from './tiers';

package/src/invalidate.ts

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

package/src/lru.ts

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

package/src/memo.ts

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

package/src/purge-cloudflare.ts

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

package/src/purge-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

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

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