@ultimat3/query 1.2.0 → 3.0.0

package/README.md

@@ -29,15 +29,51 @@ Every projection is a method on the query itself. A query has no `.def`.
 | `liveFeed.as(actor, { orgId })` | the same read as another actor — the surrounding context is untouched, `null` is signed out |
 | `liveFeed.page({ orgId }, { first: 20, after })` | one bounded page plus the signed cursor that continues it. There is no `offset` |
 | `liveFeed.live({ orgId })` | the `LiveQuery` `@ultimat3/realtime` subscribes to, carrying the same policy object |
-| `liveFeed.tool()` | the MCP read tool. `tool().policy === liveFeed.policy`, and it reads fresh |
+| `liveFeed.tool()` | the MCP read tool, named `liveFeed`. `tool().policy === liveFeed.policy`, and it reads fresh |
 | `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways |
 | `liveFeed.describe()` | the manifest row |
 
+The route on the other end of that client is `toQueryRoute(liveFeed)`, and — `As of 2026-08` —
+`x dev` and a container both mount it for every registered read, the framework's job, not the
+app's. The search string is coerced at the wire and validated by the read's own schema, so a bad
+`orgId` is the query's `X_INPUT_INVALID` and a 400; the answer is `no-store`, because the URL
+names no actor while the rows are scoped to one.
+
+`queryClient` is the same method for **every** registered read at once — the read half of
+`@ultimat3/action`'s `rpc`, and the one spelling available to a surface that may not import a
+feature:
+
+```ts
+import { queryClient } from '@ultimat3/query';
+import type { Api } from '../api';                 // a TYPE, so no module-graph edge
+
+export const queries = queryClient<Api['queries']>({ baseUrl });
+const [post] = await queries.publicPost({ slug }); // typed input, typed rows
+```
+
+Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
+
 The declaration is lifted too: `.input`, `.policy`, `.cache`, `.mcp`, `.isLive`. `sql` is not
 among them — it lives in a private store inside `read.ts`, so `sourceFor` is the only thing
 that can build a source and there is nowhere for a second authz path to hide. Something that
 merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`.
 
+### Skipping the policy costs a written reason
+
+Two reads have no subscriber to decide about: developer tooling that returns the statement and no
+rows (`explain`, `describeSql`), and the shared, subject-less window a sync node builds once per
+`(query, input)`. Both say so, in words:
+
+```ts
+const source = await sourceFor(target, input, {
+  unenforced: 'a scaffolded test asserts the SQL text; the policy is asserted separately',
+});
+```
+
+A blank reason is refused before the source is built. It is a string and not a boolean for the
+reason `@ultimat3/entity`'s `crossTenant(reason, fn)` is: `enforce: false` reads exactly like
+forgetting the policy, and the reason is what tells the next reader which of the two it is.
+
 ## What each file owns
 
 | File | Job |
@@ -47,7 +83,8 @@ merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`
 | `facade.ts` | binds each projection to the query; re-implements none of them |
 | `mcp-tool.ts` | the MCP read descriptor |
 | `client.ts` | the typed read client (browser-safe) |
-| `naming.ts` | export name → wire path + tool name |
+| `http.ts` | the route projection — `GET /_x/query/<kebab>`, the URL the client derives |
+| `naming.ts` | export name → wire path. The MCP tool name is the export name verbatim |
 | `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
 | `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
 | `pagination.ts` | `paginate()` — keyset pages over core's cursor codec |
@@ -106,6 +143,14 @@ the package, and rotating the secret is what invalidates every open cursor. This
 the only thing that is its business — the scope, `queryHash(name, input)` — and re-exports
 `CursorInvalidError` so the failure keeps its name on this surface.
 
+The scope's hash is **SHA-256, first 16 hex** (`fingerprint` in `stable.ts`), the primitive and
+width `@ultimat3/realtime`'s `stableDigest` and `@ultimat3/entity`'s `planScope` already use. It
+was FNV-1a/32 until 2026-08 — 4×10⁹ values over input a client chooses, brute-forceable offline in
+seconds, and a fingerprint here is a *sharing* key: which read-cache entry two callers are served
+from, and which scope a cursor is bound to. The canonical serialization did not change, only the
+hash, so a cursor issued before it fails its scope check as `X_CURSOR_INVALID` with "request the
+first page again" as its fix, and a warm read cache is cold once.
+
 A cursor names a **position in the ordering**, never a row and never a count. Both seek paths
 answer "is this row after that position?" through the one predicate, `isAfterKey`: `Builder.seek()`
 compiles it to SQL — spelled out per key, so a mixed `createdAt desc, id asc` listing is a real
@@ -116,23 +161,147 @@ gone. A row with no `id` cannot name a position at all: that is `X_QUERY_NOT_PAG
 cursor signed over `"undefined"`.
 
 Because the predicate always carries that id, the ordering carries it too: a paged read is served
-`order by <declared keys>, "id" asc`, and the in-memory path sorts by the same list. Ordering by
-the declared keys alone leaves rows with equal sort values in whatever order the database chose,
-while the cursor reads them as if id had decided — so one of a tied pair comes back on both pages
-and the other on neither.
+`order by <declared keys>, "id" asc` — that list is `totalOrder(orderBy)`, exported for the reason
+`isAfterKey` is — and the in-memory sort and the live matcher's insertion position read the same
+one. Ordering by the declared keys alone leaves rows with equal sort values in whatever order the
+database chose, while the cursor reads them as if id had decided — so one of a tied pair comes back
+on both pages and the other on neither, and a row the matcher appends after a tie group is a
+position no re-read returns.
+
+A **live** read is served that way too, and `SqlSource.total()` is how it says so: the same read
+with no cursor and no window, ordered `<declared keys>, "id" asc`. `sourceFor` calls it for
+`surface: 'live'` and for nothing else, so the initial window, the patch positions the matcher
+computes and the keyset re-read a reconnect resumes with are one ordering. A source that does not
+implement `total()` is left alone — it already serves one order it can be resumed in.
+
+## NULL
+
+One rule, three readers: the SQL a source generates, the in-memory execution behind `from()`, and
+the live matcher. `null` and a column the row omits are the same absence — `isNull` is the one
+definition, exported for the same reason `isAfterKey` is.
+
+| Operator | NULL is | Emitted as |
+|---|---|---|
+| `=` `!=` `in` | a value — it matches itself and nothing else | `is null` · `is not null` · `is distinct from` · `in (…) or is null` |
+| `>` `>=` `<` `<=` | unknown — a NULL on either side matches nothing | `"col" > $n`, which already matches no NULL |
+| `order by`, the cursor | the largest value: last ascending, first descending | `asc nulls last` · `desc nulls first` |
+
+`where({ deletedAt: null })` compiles to `"deletedAt" is null` and binds no parameter: `= $1` with
+a NULL argument is unknown in Postgres and unknown is never true, so that filter used to match
+every row in memory and none in the database. The seek predicate had the same defect one page
+later — `"publishedAt" > $1` is unknown for every draft, so page two stopped at the first NULL and
+the rows after it were unreachable through a cursor. An ascending key now reaches them
+(`("col" > $1 or "col" is null)`); a NULL cursor value drops its own term, nothing sorting after a
+NULL under `nulls last`, and the page continues on the id tiebreak, which is never NULL.
+
+`nulls last` / `nulls first` are Postgres' own defaults, written down rather than inherited: it is
+the rule `compareValues` implements, so the in-memory sort and the seek predicate can only agree
+with it, and a driver whose default differs cannot re-open the divergence.
 
 ## Caching
 
-Request memo (same read twice in one render ⇒ one round trip), then the tier behind
-`ReadCache`. Keys are `query:<name>:<input fingerprint>:<tags>`. An action's
-`cache.invalidates` and a query's `cache.tags` meet in the one graph owned by
-`@ultimat3/cache`.
+Request memo (same read twice in one render ⇒ one round trip), then the tier ladder
+`@ultimat3/cache` has registered — `createCacheStack(registeredTiers())`, read down and promoted
+up. Keys are `query:<name>:<authority>:<input fingerprint>:<tags>`. An action's `cache.invalidates`
+and a query's `cache.tags` meet in the one graph owned by `@ultimat3/cache`, because there is one
+registry and this package holds no store of its own.
+
+**The authority is who the read was answered for, and it is not optional.** `sql(input, ctx)` is
+handed the context and `@ultimat3/entity` derives every tenant predicate from `ctx.actor.orgId`,
+never from the input — so a key made of the name, the input and the tags did not identify a read's
+answer, and the process-wide tier served one org's rows to the next org that asked. `cache.scope`
+declares who may be served one entry:
+
+| `scope` | Key holds | Use it when |
+|---|---|---|
+| `actor` (default) | the actor's kind, id and org | anything. Declaring nothing gets this, and this is always correct |
+| `tenant` | the actor's org — the actor itself when there is none | every member of one org sees the same rows |
+| `global` | nothing | the rows are the same for everyone, signed-in or not |
+
+The default is the mechanism: forgetting to declare a scope gives the narrowest key. Widening it
+is a written statement about the rows, one `grep` away — the same shape `unenforced:` uses for a
+skipped policy. `readAuthority(actor, scope)` is the only producer of the component, and it is a
+required positional argument of `cacheKeyFor`, because an optional one is one a call site forgets.
+
+**The fill is fenced, best-effort and single-flighted, and none of that is written here.**
+`createCacheStack` samples `@ultimat3/cache`'s fence immediately before it runs the source and
+re-asks it per rung before each write, so a bust that lands mid-read cannot be republished for the
+whole TTL — the caller still gets the rows it read, because those are its answer; only publishing is
+refused. Every tier call goes through `bestEffort`, so a Redis refusal is a miss rather than a
+failed business read and shows up in `recentTierFailures()` under the name of the tier that
+refused. Concurrent misses of one key share one `load()`. `@ultimat3/query` used to carry its own
+copy of the first two and none of the third.
+
+`cache.ttlMs` is refused at `query()` unless it is positive and finite
+(`X_QUERY_CACHE_TTL_INVALID`): every tier refuses such a lease, so `ttlMs: Infinity` used to make
+one read fail permanently at run time with a cause about a cache key.
+
+An entry is written with the read's `cache.tags`, so a row bust (`post:1`) drops the lists that
+held the row, exactly as `tagMatches` defines it — and `invalidateTags(tags)`, the call an action's
+`cache.invalidates` makes, is the whole of what drops it. There is nothing to install and nothing
+to wire: a `cache:` read fills the registered tiers, so a process that registered none reads
+uncached rather than filling a store no fan-out can see.
+
+A `cache:` block that omits `ttlMs` gets `DEFAULT_READ_CACHE_TTL_MS` (60s) rather than immortality.
+Tags are the primary eviction; the TTL is the backstop for the read whose tags never fire. The
+lease handed to the ladder is **relative** — the tier's own clock turns it into an expiry, so a
+tier registered with a frozen clock is drivable end to end — and omitting it is how a tier is asked
+for its own default. `@ultimat3/cache`'s tiers refuse a non-positive `ttlMs` and have no immortal
+entry to offer, so there is no "never" to spell.
+
+The memo entry is the read **in flight**, not its value, so "twice" covers reads that race as
+well as reads that follow: five holes rendering concurrently share one execution and one tier
+round trip. A rejection is evicted — a failed read is not the request's answer.
+
+| Layer | Applies to | Lifetime |
+|---|---|---|
+| request memo (`readOnce`) | **every** query, `cache:` or not | the request — a `Ctx`'s identity is the key |
+| tag-keyed tier (`readThrough`) | a query that declares `cache:` | `ttlMs`, or until an `invalidates` fan-out drops the tag |
+
+`cache:` buys the tier, never the memo: an uncached lookup called once per row of a list would
+otherwise cost one round trip per row. Parsing, the policy and `sql()` still run on every call —
+the memo holds the execution, not the decision — and `.as()` reads in a child context, so an
+impersonated read never joins one made as someone else.
+
+`fresh: true` skips both on the way in, and **publishes into the memo on the way out**: it is how
+a caller reads past a write made earlier in the same request, and the read it just made is the
+request's answer from then on, so a later plain read of the same key joins it rather than the entry
+the write moved past. Invalidation drops tier entries, not memo entries.
+
+## `rateLimit:` — the read half, and it is enforced
+
+```ts
+rateLimit: { limit: 3, windowMs: 600_000 },   // 3 held, one back every three and a bit minutes
+```
+
+Symmetric with an action's, and for a reason: without it **every** `GET /_x/query/*` fell to the
+`default` bucket — 120 burst, 2/s per actor — so one authenticated caller could hold 120
+cross-tenant aggregates in flight and then 2/s indefinitely, from a single account, with no
+declaration able to say otherwise. `toQueryRoute` sets the bucket NAME and the NUMBERS, and
+`@ultimat3/http`'s `withRouteBuckets` registers them: a name alone falls through to `default`.
+The conversion is `toBucket` from `@ultimat3/http` — the same one the action route uses, because
+http owns `Bucket` and `action` is the same tier as this package. A pair the limiter cannot run
+on is `X_RATE_LIMIT_INVALID`, at projection.
+
+## `deprecated:` — a compat window, not a version
+
+```ts
+deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2026-12-31T23:59:59Z', replacedBy: 'searchOrders' },
+```
+
+`Deprecation` (RFC 9745) and `Sunset` (RFC 8594) on every answer, a
+`link: </_x/query/search-orders>; rel="successor-version"`, the dates on the descriptor, and a
+`deprecated_calls_total{primitive,name}` counter so "is anyone still reading it?" has an answer
+before the read is deleted. A date that cannot be rendered is `X_QUERY_DEPRECATION_INVALID` at
+projection, not on the first read. Versioning is two deployments behind one ingress, never a
+router feature here.
 
 ## Errors
 
 | Code | When | Fix |
 |---|---|---|
 | `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
+| `X_QUERY_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
 | `X_MATCHER_UNSUPPORTED` | live query the matcher cannot patch | reshape it, or `live: false` |
 | `X_CURSOR_INVALID` | tampered / foreign / malformed cursor | request the first page again |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,9 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/policy": "1.2.0",
-    "@ultimat3/schema": "1.2.0"
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/http": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/schema": "3.0.0"
   }
 }

package/src/cache.ts

@@ -1,101 +1,210 @@
 /**
- * Read caching, two layers: a per-request memo (same query twice in one render
- * costs one round trip) and a tag-keyed tier behind the `ReadCache` interface.
- * Invalidation is never local — it goes through @ultimat3/cache so an action's
- * `invalidates` and a query's `tags` meet in one graph.
+ * The read path: a per-request memo (`readOnce` — same query twice in one render costs one
+ * execution, whether the second read follows the first or races it) and, for a query that
+ * declares `cache:`, the fill through `@ultimat3/cache`'s registered tiers (`readThrough`). Every
+ * read gets the memo; the ladder is the half a query opts into.
  */
 
-import type { CacheTag } from '@ultimat3/cache';
-import { invalidateTags } from '@ultimat3/cache';
-import type { Ctx } from '@ultimat3/core';
+import type { CacheStack, CacheTag, CacheTier } from '@ultimat3/cache';
+import { createCacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
+import type { Actor, Clock, Ctx } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
 import { fingerprint } from './stable';
-import { tagKeys } from './tags';
 
-export interface ReadCacheEntry {
-  readonly value: unknown;
-  readonly expiresAt: number | null;
-}
+/**
+ * A `cache:` block with no `ttlMs`. Tag invalidation is the primary eviction, so this is the
+ * backstop for the read whose tags never fire — one number, the same 60s `@ultimat3/cache`'s
+ * LRU tier defaults to.
+ */
+export const DEFAULT_READ_CACHE_TTL_MS = 60_000;
 
-export interface ReadCache {
-  get(key: string): Promise<ReadCacheEntry | undefined>;
-  set(key: string, entry: ReadCacheEntry): Promise<void>;
-  delete(key: string): Promise<void>;
-}
+/**
+ * Request-scoped memo. Keyed by ctx identity so it dies with the request.
+ *
+ * An entry is the read *in flight*, not its value: unsettled it is the answer a caller is
+ * already waiting for, settled it is the answer. That is what makes two concurrent identical
+ * reads one round trip — and it is why no sentinel is needed for a legitimately `undefined`
+ * value, which a value-keyed memo cannot tell apart from a miss. A promise is never `undefined`.
+ */
+const memos = new WeakMap<object, Map<string, Promise<unknown>>>();
 
-/** In-memory default. Production installs the tiered cache from @ultimat3/cache. */
-export class MemoryReadCache implements ReadCache {
-  readonly #entries = new Map<string, ReadCacheEntry>();
-
-  async get(key: string): Promise<ReadCacheEntry | undefined> {
-    const entry = this.#entries.get(key);
-    if (entry === undefined) return undefined;
-    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
-      return undefined;
-    }
-    return entry;
-  }
+export function requestMemo(ctx: Ctx): Map<string, Promise<unknown>> {
+  const key: object = ctx;
+  const existing = memos.get(key);
+  if (existing !== undefined) return existing;
+  const created = new Map<string, Promise<unknown>>();
+  memos.set(key, created);
+  return created;
+}
 
-  async set(key: string, entry: ReadCacheEntry): Promise<void> {
-    this.#entries.set(key, entry);
-  }
+/**
+ * Who a cached answer may be handed back to. Declared as `cache: { scope }`.
+ *
+ * `actor` is the default, and the default is the mechanism (axiom 3): a read that says nothing
+ * gets the NARROWEST key, which is always correct. Widening is a written statement about what the
+ * rows are — `tenant` says "every member of this org gets the same rows", `global` says "everyone
+ * does" — and a wrong one is visible in the declaration rather than in a support ticket.
+ */
+export type QueryCacheScope = 'actor' | 'tenant' | 'global';
 
-  async delete(key: string): Promise<void> {
-    this.#entries.delete(key);
+/**
+ * The authority a read was answered under, as a key component.
+ *
+ * `sql(input, ctx)` is handed the context, and `@ultimat3/entity` derives every tenant predicate
+ * from `ctx.actor.orgId` rather than from the input — so the name, the input and the tags do not
+ * identify a read's answer, and a tier keyed on those three served one org's rows to the next org
+ * that asked. Folding the authority in is what `@ultimat3/entity`'s `scopeKey` does for a batched
+ * point read, for exactly this reason.
+ *
+ * JSON, never a joined string: an actor id is app data and may carry the separator, and a value
+ * that can spell a boundary can spell someone else's.
+ */
+export function readAuthority(actor: Actor, scope: QueryCacheScope): string {
+  switch (scope) {
+    case 'global':
+      return '*';
+    case 'tenant':
+      // An actor inside no org is not a shared tenant. Nothing here can prove two org-less callers
+      // see the same rows, so the key narrows to the actor rather than widening to everyone —
+      // declining instead of guessing, which is the only safe direction for a sharing key.
+      return actor.orgId === undefined || actor.orgId === ''
+        ? actorAuthority(actor)
+        : JSON.stringify(['org', actor.orgId]);
+    case 'actor':
+      return actorAuthority(actor);
+    default:
+      // A fourth scope is a compile error here, not a value that silently keys as `undefined`.
+      return assertNever(scope);
   }
 }
 
-let tier: ReadCache = new MemoryReadCache();
+const actorAuthority = (actor: Actor): string =>
+  JSON.stringify([actor.kind, actor.id, actor.orgId ?? null]);
 
-export function setReadCache(cache: ReadCache): void {
-  tier = cache;
+/**
+ * Deterministic: same query + same input + same tags + same authority => same key.
+ *
+ * `authority` is REQUIRED and positional rather than optional, because an optional one is one a
+ * call site can forget — and a forgotten one is the cross-tenant read this argument exists to
+ * make impossible. `readAuthority` is the only thing that produces it.
+ */
+export function cacheKeyFor(
+  name: string,
+  input: unknown,
+  tags: readonly CacheTag[],
+  authority: string,
+): string {
+  return `query:${name}:${authority}:${fingerprint(input)}:${tagKeys(tags).join(',')}`;
 }
 
-export function getReadCache(): ReadCache {
-  return tier;
+/**
+ * One execution per key per request: the first caller runs it, every caller after joins it.
+ *
+ * This is the layer a query gets whether or not it declares `cache:` — an uncached read asked
+ * once per row of a list is the N+1 the memo exists to collapse.
+ */
+export async function readOnce<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
+  const memo = requestMemo(ctx);
+  const joined = memo.get(key);
+  // Already answered or already being answered: the second reader waits on the first read
+  // rather than starting a competing one. Awaiting a settled promise costs a microtask.
+  if (joined !== undefined) return (await joined) as T;
+  return publish(memo, key, run);
 }
 
-/** Request-scoped memo. Keyed by ctx identity so it dies with the request. */
-const memos = new WeakMap<object, Map<string, unknown>>();
+/**
+ * Runs no matter what the memo holds, and then *becomes* what it holds — what `fresh: true` asks
+ * for.
+ *
+ * Joining is the half `fresh` refuses; publishing is not. A fresh read that left the earlier entry
+ * in place would read past a write for its own caller and hand the next plain read of that key in
+ * the same request the answer this one just proved stale — so the guarantee would end at the one
+ * call that asked for it.
+ */
+export function readFresh<T>(ctx: Ctx, key: string, run: () => Promise<T>): Promise<T> {
+  return publish(requestMemo(ctx), key, run);
+}
 
-export function requestMemo(ctx: Ctx): Map<string, unknown> {
-  const key: object = ctx;
-  const existing = memos.get(key);
-  if (existing !== undefined) return existing;
-  const created = new Map<string, unknown>();
-  memos.set(key, created);
-  return created;
+/** The read in flight: published before its first await, evicted if it rejects. */
+async function publish<T>(
+  memo: Map<string, Promise<unknown>>,
+  key: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  // Published before the first await, so a reader arriving in the same tick finds this read.
+  const flight = run();
+  memo.set(key, flight);
+  try {
+    return await flight;
+  } catch (error) {
+    // A rejection is not an answer. Drop it so a later read in the same request retries
+    // instead of replaying one failure until the request ends. Only ours: a fresh read may have
+    // replaced this entry already, and evicting that one would discard a live answer.
+    if (memo.get(key) === flight) memo.delete(key);
+    throw error;
+  }
 }
 
-/** Deterministic: same query + same input + same tags => same key. */
-export function cacheKeyFor(name: string, input: unknown, tags: readonly CacheTag[]): string {
-  return `query:${name}:${fingerprint(input)}:${tagKeys(tags).join(',')}`;
+/**
+ * One stack per (registry, clock) — never one per read.
+ *
+ * `createCacheStack` owns a single-flight map, so a stack built per call joins nothing and the
+ * cross-request stampede guard would be a no-op. Keyed on the clock because the stack's expiry
+ * decision and the tiers' own have to agree: a tier registered with a frozen clock under a stack
+ * reading the wall clock calls every entry expired, which is the shape that made the old read
+ * tier undrivable by a test.
+ */
+const stacks = new WeakMap<Clock, { tiers: readonly CacheTier[]; stack: CacheStack }>();
+
+const sameTiers = (a: readonly CacheTier[], b: readonly CacheTier[]): boolean =>
+  a.length === b.length && a.every((tier, index) => tier === b[index]);
+
+function stackFor(clock: Clock): CacheStack {
+  const tiers = registeredTiers();
+  const held = stacks.get(clock);
+  // Rebuilt whenever the registry changes — a boot that registers the shared tier after the first
+  // read, and `resetTiers()` between suites. Compared element-wise by identity: a tier object is
+  // registered once and never mutated, so two equal lists are the same ladder.
+  if (held !== undefined && sameTiers(held.tiers, tiers)) return held.stack;
+  const stack = createCacheStack(tiers, { clock });
+  stacks.set(clock, { tiers, stack });
+  return stack;
 }
 
-/** Memo first, then the tier, then the source. */
-export async function readThrough<T>(
+/**
+ * Memo first, then the tier ladder, then the source — what a query with `cache:` reads through.
+ *
+ * `tags` is what the written entry is dropped by; an entry stored without them is reachable
+ * only by its key and can therefore only expire.
+ */
+export function readThrough<T>(
   ctx: Ctx,
   key: string,
   ttlMs: number | null,
   run: () => Promise<T>,
+  tags: readonly CacheTag[] = [],
 ): Promise<T> {
-  const memo = requestMemo(ctx);
-  const memoized = memo.get(key);
-  if (memoized !== undefined) return memoized as T;
-
-  const cached = await tier.get(key);
-  if (cached !== undefined) {
-    memo.set(key, cached.value);
-    return cached.value as T;
-  }
-
-  const value = await run();
-  memo.set(key, value);
-  await tier.set(key, { value, expiresAt: ttlMs === null ? null : Date.now() + ttlMs });
-  return value;
+  return readOnce(ctx, key, () => fill(ctx.clock, key, ttlMs, tags, run));
 }
 
-/** The one invalidation path. Actions call the same function via their `cache`. */
-export async function invalidateQueryTags(tags: readonly CacheTag[]): Promise<void> {
-  await invalidateTags(tags);
+/**
+ * The read itself, through the tiers `@ultimat3/cache` has registered and no store of this
+ * package's own. Runs once per key per request; the rest join it at the memo above.
+ *
+ * Everything this used to do by hand — the fence sampled before the load, `bestEffort` around
+ * every tier call, the expiry — is `createCacheStack`'s, which is the point: there was one read
+ * cache too many, and the one that lived here was in no registry, so `invalidateTags` could not
+ * reach it. A relative `ttlMs` and never an absolute expiry: the tier's own clock decides when
+ * the entry dies, so a tier registered with a frozen clock is drivable end to end.
+ */
+function fill<T>(
+  clock: Clock,
+  key: string,
+  ttlMs: number | null,
+  tags: readonly CacheTag[],
+  run: () => Promise<T>,
+): Promise<T> {
+  // `null` is "the caller named none", never "never": every tier refuses a non-positive `ttlMs`
+  // and none has an immortal entry to offer, so omitting it falls to the tier's own default.
+  return stackFor(clock).read(key, run, { ...(ttlMs === null ? {} : { ttlMs }), tags });
 }