@ultimat3/query 21.0.0 → 22.0.0

package/CLAUDE.md

@@ -12,21 +12,21 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 
 | File | Job |
 |---|---|
-| `query.ts` | the primitive: `query()`, `describeQuery`, `queryHash`; the package's front door for the read path |
+| `query.ts` | the primitive: `query()`, `describeQuery`, `queryHash`; the front door for the read path |
 | `read.ts` | **the one read path** (`runQuery`, `sourceFor`) + the private declaration store `sql` lives in |
 | `facade.ts` | the fluent surface — binds each projection to the query, re-implements none |
 | `http.ts` | route projection (`GET /_x/query/<kebab>`, `enforcedBy: 'handler'`) |
 | `mcp-tool.ts` | MCP read descriptor, same `sourceFor` |
-| `client.ts` | typed read client (browser-safe: no server imports); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
+| `client.ts` | typed read client (browser-safe); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
 | `record-answer.ts` | a read's HTTP answer: bare rows, or the record envelope when `rows:` is an entity's branded row schema |
-| — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported from `src/index.ts`. There is no local copy and must not be one |
-| `naming.ts` | export name → `/_x/query/<kebab>` — `derivePath` IS `@ultimat3/core`'s `queryPath`, re-exported. **Paths only** — no tool name |
-| `registry.ts` | export-name registration, `describeQueries()`, and the `registerPrimitiveRegistrar('query', …)` announcement |
+| — | flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported. No local copy |
+| `naming.ts` | export name → `/_x/query/<kebab>` — `derivePath` IS core's `queryPath`. **Paths only** |
+| `registry.ts` | export-name registration, `describeQueries()`, the `registerPrimitiveRegistrar('query', …)` announcement |
 | `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
 | `subscribes.ts` | the relations a live read declares, and the two assertions that keep them true |
 | `matcher.ts` | change event → minimal patch, `refill` when the window cannot place the row, or `X_MATCHER_UNSUPPORTED` |
 | `pagination.ts` | `paginate()` over core's cursor codec — no offset, ever |
-| `cursor-value.ts` | what a sort value becomes inside a cursor, and what it becomes again |
+| `cursor-value.ts` | what a sort value becomes inside a cursor, and back |
 | `input-shape.ts` | what a read's `input:` may be, given that its route is a query STRING |
 | `sql.ts` | `explain()` / `describeSql()` |
 | `cache.ts` | the read path: the request memo, and the fill through `@ultimat3/cache`'s registered tiers |
@@ -34,561 +34,159 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `source.ts` | `SqlSource` contract + `from()` in-memory reference |
 | `shape.ts` | shared read vocabulary (filters, ordering, seek keys) |
 | `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
-| `deprecation.ts` | `Deprecation` + the RFC 9745/8594 render + the `deprecated_calls_total` counter — TWINNED with `@ultimat3/action`'s |
+| `deprecation.ts` | `Deprecation` + RFC 9745/8594 render + `deprecated_calls_total` — TWINNED with `@ultimat3/action`'s |
 
-## Invariants
+## Invariants — the read path
+
+- Every surface goes through `sourceFor`: parse input, evaluate policy, build the source. A second
+  read path is the one unforgivable change here.
+- **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
+  `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.
+  `read-context.test.ts` asserts ambient, `options.actor` and `options.ctx` are one caller.
+- **Skipping a read's policy costs a WRITTEN REASON** (`unenforced?: string`; blank refused).
+  `ToLiveOptions.enforce` stays a boolean, translated into `SHARED_WINDOW_REASON`.
+- The declaration never leaves `read.ts`. `defOf`/`stashDef`/`hasDef` are never re-exported from
+  `src/index.ts` — that omission is the enforcement. A query has no `.def`; outside the package read
+  `.input`/`.policy`/`.cache`/`.mcp`/`.isLive` or `describe()`. A projection is reached through the
+  query (`liveFeed.tool()`); new methods are bound in `facade.ts`.
+- `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim** (`index.test.ts` asserts identity).
+- **`LiveQuery` describes the read *and* runs it** (`execute()`, never memoised).
+  `@ultimat3/realtime`'s shared window reads through it.
+- `isLive` is the declared boolean, `live()` the subscription. `QueryDescriptor.live` keeps its name
+  (`manifest` and `admin` read it).
+- `mcp` is opt-in; `isExposed` delegates to core's `isMcpExposed`.
+- **A read has ONE tool name, the export name verbatim.** `toToolName` is deleted.
+  `mcp-tool.test.ts` asserts `toQueryTool(q).name === queryName(q)`; `index.test.ts` asserts the
+  barrel exports nothing matching `/tool_?name/i`.
+- **`queryClient` is the map-wide read client (mirror of `rpc`)**; both spellings run
+  `queryClientMethodFor`. **`toQueryRoute` and `client()` derive the same URL from `naming.ts`.**
+- **The route coerces (`coerceQuery`), `runQuery` validates.** No `request.query(schema)` and no
+  `meta.input` on the route.
+- **`rateLimit:` is declarable; `toQueryRoute` sets both `meta.rateLimit` and
+  `meta.rateLimitBucket`**, via `@ultimat3/http`'s `toBucket` — never a local copy.
+- **`deprecated:` is a compat WINDOW**: `Deprecation` / `Sunset` / `rel="successor-version"` on every
+  answer, rendered ONCE at projection (`X_QUERY_DEPRECATION_INVALID` at mount). Versioning is two
+  deployments behind one ingress.
+- **The span wraps the whole read** (`readRows` holds it, `readRowsIn` is the body); bounded
+  attributes only — never the input or an actor id. `telemetry.test.ts` asserts the extent through
+  `currentSpan()`.
+- **`policyCapability` is a display label; `policyPermissions` (`QueryDescriptor.permissions`) is what
+  a report matches on.**
+- **`client.ts` injects `traceparent`** before the caller's headers; an incomplete span context sends
+  nothing.
+- **A read is `no-store`, and its policy is `enforcedBy: 'handler'`** — `runQuery` is the one
+  evaluation (`http.test.ts` counts exactly one).
+- **`meta.auth` comes from `@ultimat3/policy`'s `admitsAnonymous`** (a walk of the tree, via
+  `policy-gate.ts`), never the root combinator.
+- `registry.ts` announces `registerQueries` in core's registrar table at import; `defineApi` in
+  `@ultimat3/action` depends on it (`X_REGISTRAR_MISSING` otherwise).
+- Authz goes through `enforce(surface, policy, { input, actor, ctx })`; a live denial keeps its 4403
+  close code on `QueryDeniedError.denial`. Policy runs per subscriber for live queries — never cache a
+  decision across actors.
+
+## Invariants — the client
+
+- **Flight control is `@ultimat3/core`'s, re-exported** (`createClientFlight`,
+  `DEFAULT_CLIENT_RETRY`, `isTransientFailure`, `isSuperseded`, the types) — the same objects
+  `@ultimat3/action` exports. Fix the pipeline in `packages/core/src/client-flight.ts`. No new error
+  code, curve, fence or retry loop here; `bun run flight-copies` says so.
+- **`isTransientFailure` INVERTS `retryDecision`'s unclassified default** — a caller's own
+  `AbortError` is terminal. Must survive.
+- **`ClientFlight` is a TYPE inside `client.ts`, never a value.**
+- **Every read dispatches through core's `clientTransport`; `client.ts` calls no `fetch`.** The
+  transport owns `Accept`, trace/budget headers, the principal fence, the error decode and the record
+  envelope; the flight handed to it dedups concurrent identical reads. `bun run browser-transport`
+  is the guard.
+- **`@ultimat3/query/client` is the read client without the barrel** — `client.ts` and `naming.ts`
+  import core from `@ultimat3/core/page`, the page keys live in the leaf `page-keys.ts`, and
+  `client.ts` never imports `page-controls.ts` or `stable.ts`. `client-bundle.test.ts` fails on any
+  titles table in the graph or past 11 kB; `client-subpath.test.ts` pins the specifier. Byte figures
+  (`As of 2026-09-22`, browser, minified): barrel `queryClient` 24,114 B; `./client` 10,210 B.
+- **The record envelope is derived from `rows:`** — `answersRecords(rows)` (`hasEntityRows`,
+  `@ultimat3/entity`), decided once at projection for `http.ts` and `openapi.ts`, sent on every
+  answer. No `rows:` is byte-identical on the wire.
+- **The `sideEffects` array is load-bearing**: `errors.ts` and `registry.ts` run at import. Never `false`.
+
+## Invariants — numbers, search, live declarations
+
+- **Every numeric option is refused when not FINITE** (`finiteOption()`: the read cache's `ttlMs`,
+  `search()`'s `page.max`, `page.default`, `termMax`). `finite-bounds` pins this package at zero.
+- **`search()` is a FACTORY over `query()`**: it owns the input schema (`q` + a bounded `limit`),
+  refuses a blank term and calls `.search(term)` on the chain the app hands it (structural
+  `SearchChain`). No `PRIMITIVE_FACTORIES` row (it returns a query from the query package). **It serves
+  ONE page**: `windowOf.execute` refuses only when rows would be CUT; `onePage.seek` narrows with
+  `Builder.limit()`, never `Builder.seek()`, so the chain's own ranking survives; no `total()`.
+  `search.test.ts`'s fixture must stay NOT id-ascending.
+- **`subscribes:` is DECLARED (nothing can derive it) and CROSS-CHECKED**: `toLiveQuery` asserts
+  `shape.entity` is among the declared names at first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`) —
+  membership, never equality. An empty list, or one on a non-live read, is refused at `query()`
+  (`X_QUERY_SUBSCRIBES_INVALID`).
+- **A read's `input:` must survive a query STRING** (`input-shape.ts`, `X_QUERY_INPUT_UNENCODABLE`):
+  refused are structural members (`object`, `record`, `money`, or an array/union of one), a REQUIRED
+  nullable member, and a non-object top level. An un-introspectable schema is left alone.
+
+## Invariants — ordering, cursors, the matcher
 
-- Every surface goes through `sourceFor`: parse input, evaluate policy, build the source.
-  Adding a second read path is the one unforgivable change here.
-- **An explicit `ctx` is INSTALLED, never merely passed** (`As of 2026-08`). `asActor` used to hand
-  `options.ctx` to `run(ctx)` and enter no `runWithContext` unless an `actor` was also given, so
-  `guard()` decided about that actor while everything reading the AMBIENT context — above all
-  `@ultimat3/entity`'s tenant guard, which derives from `tryUseContext()` and not from the ctx it is
-  handed — saw a different identity, or none. A read was authorised as one caller and scoped to
-  nobody. Absent a `ctx` it reinstalls the ambient one, which is a no-op on every path that already
-  worked. The twin fix is `@ultimat3/action`'s `invoke`, and `read-context.test.ts` is written as an
-  equality between the three spellings of one caller — ambient, `options.actor`, `options.ctx` —
-  because three independent expectations are exactly what let this ship.
-- **Skipping a read's policy costs a WRITTEN REASON, never a boolean** (`As of 2026-08`).
-  `SourceOptions.enforce?: boolean` is gone; it is `unenforced?: string`, and a blank one is
-  refused before the source is built. The bar is `@ultimat3/entity`'s `cross-tenant.ts`: a boolean
-  argument "reads exactly like forgetting the tenant", and a forgotten policy reads the same way —
-  so the reason IS the mechanism and every skipped policy is one `grep` away with its justification
-  attached. It is deliberately NOT capability-gated the way `crossTenant` is: `explain` runs from
-  the CLI with no actor to check a scope against, and gating it would close the one surface it
-  exists for. **`ToLiveOptions.enforce` stays a boolean**, because it is that one use with exactly
-  one reason — `toLiveQuery` translates it into the reason string spelled once as
-  `SHARED_WINDOW_REASON`, so a sync node and this file cannot disagree about why the shared window
-  has no subject. Two shipped callers, both reading no rows for a subscriber: `sql.ts` and that
-  window.
-- The declaration never leaves `read.ts`. `defOf`/`stashDef`/`hasDef` are internal and must
-  never be re-exported from `src/index.ts` — that omission is the enforcement.
-- A query has no `.def`. Inside the package read it with `defOf(target)`; outside, read the
-  lifted `.input`/`.policy`/`.cache`/`.mcp`/`.isLive` or `describe()`.
-- App code reaches a projection through the query (`liveFeed.tool()`), never through `.def`
-  and never by importing the projection function. `facade.ts` is where a new method is bound;
-  the projection itself keeps living in its own file.
-- `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a query file imports
-  one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on every
-  access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
-- **`LiveQuery` describes the read *and* runs it.** `execute()` is the source the shape, the reads
-  and `sqlText` were taken from — one build of one `(query, input)`. A caller that wanted rows and
-  called `sourceFor` itself was a second build: twice the parse, twice the `sql()`, and a matcher
-  describing a source the rows never came from. `@ultimat3/realtime`'s shared window is the one
-  consumer, and it reads through `execute()`. It never memoises — a subscriber joining an existing
-  subscription must see the rows as they are now, not the window someone else opened.
-- `isLive` is the declared boolean, `live()` is the subscription. Never name one after the other.
-  `QueryDescriptor.live` keeps its name — `@ultimat3/manifest` and `@ultimat3/admin` read it.
-- `mcp` is opt-in (`expose: true`), exactly as it is for an action: rows reach an agent only when
-  the author said so. `isExposed` here delegates to `isMcpExposed` in `@ultimat3/core` — the one
-  predicate every reader in the framework asks — rather than spelling `=== true` a second time.
-- **A read has ONE tool name, and it is the export name verbatim** (`As of 2026-08`). `toQueryTool`
-  snake_cased it (`liveFeed` → `live_feed`) while `@ultimat3/mcp` serves the read under
-  `queryName(target)` and answers `tools/call` for nothing else — so anything that read the name off
-  the descriptor rather than off `tools/list` called a tool the server had never heard of, and the
-  scope map in `defineAppMcp` is keyed on the verbatim name too. `toToolName` is **deleted**, not
-  merely unused: an exported derivation is a second way to spell one tool. Two pins, both in this
-  package because this is where the rule can be broken — `mcp-tool.test.ts` asserts
-  `toQueryTool(q).name === queryName(q)` (the presence), and `index.test.ts` asserts the barrel
-  exports no key matching `/tool_?name/i` (the absence, which nothing else catches: the only other
-  guard is `packages/mcp/src/cross-surface.test.ts`, tier 4 and unimportable from here).
-  `naming.ts` derives PATHS only.
-- `client.ts` stays free of server imports — it is bundled into the browser. `@ultimat3/action`
-  is the same tier, so its naming is ported here, never imported.
-- **`queryClient` is the map-wide read client and the mirror of `rpc`; both spellings run
-  `queryClientMethodFor`.** `queryClient<Api['queries']>({ baseUrl })` is how a surface that must
-  not import a feature reaches every registered read — `site/` in an app, whose one edge into
-  `app/` is a boundary violation, so `.client()` (which needs the query object) is unreachable
-  there. The map-wide client re-deriving a path from the property name would be the second URL
-  derivation this package spent a release removing; it proxies to the per-query method instead.
-- **`toQueryRoute` is the other half of `client()`, and the two derive the same URL from the same
-  `naming.ts`.** The client shipped fetching `/_x/query/<kebab>` while nothing built a route for
-  it, so every typed read compiled and 404'd; a projection whose only consumer is a URL string is
-  the failure this pairing exists to prevent. Named for the primitive rather than `toRoute`,
-  because a host mounts it beside `@ultimat3/action`'s — the same reason the tool projection here
-  is `toQueryTool`.
-- **The route coerces, `runQuery` validates, and only the first belongs to the wire.** A search
-  string is characters, so the boundary decodes it with `@ultimat3/schema`'s `coerceQuery` — the
-  one HTTP-boundary decoder, which never invents data and hands on what it cannot convert.
-  Validating there as well (`request.query(schema)`) would be the second parser: the same read
-  would answer `X_BODY_INVALID` where every other surface answers `X_INPUT_INVALID` and prints
-  its schema. For the same reason `meta.input` stays **absent** — the pipeline's body stage
-  validates it against a body, and a GET has none, so declaring it fails every read on nothing.
-- **`rateLimit:` is declarable on a read, and `toQueryRoute` sets the NAME and the NUMBERS.**
-  `QueryDef` had neither until 2026-08, so every `GET /_x/query/*` fell through `bucketFor` to
-  `default` — 120 burst, 2/s per actor — and 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. The conversion is `toBucket` from **`@ultimat3/http`**, never a copy here:
-  http owns `Bucket` and the maths, `@ultimat3/action` is the same tier as this package, and a
-  copy in either is a second answer for the other. The field is lifted onto the facade so
-  `toQueryRoute` reads it without `defOf`, exactly as `cache` and `mcp` are.
-- **`deprecated:` is a compat WINDOW; versioning is two deployments behind one ingress.** Headers
-  are rendered ONCE at projection, so an unparseable date is `X_QUERY_DEPRECATION_INVALID` at
-  mount and not on the first read. `deprecation.ts` is a TWIN of `@ultimat3/action`'s — both are
-  tier 3, so neither may import the other, and the shared home is `@ultimat3/http` if it grows
-  one. The same compromise `naming.ts` is ported under; keep the two files identical in behaviour.
-- **The span wraps the whole read, not `source.execute()`.** Parse, policy and `sql()`'s own
-  construction were outside every span, so a read whose cost was in building the source reported
-  milliseconds under a parent that reported seconds — a gap with no name. `readRows` holds the
-  span and `readRowsIn` is the body; attributes are bounded (surface, actor KIND, `live`,
-  `cached`, `fresh`) plus the row count, and never the input or an actor id — a read is keyed per
-  tenant and per cursor, so either would be unbounded. `telemetry.test.ts` asserts the extent
-  structurally through `currentSpan()`, because the test clock is frozen. `sourceFor` still has no
-  span of its own: adding one would double-span every read that goes through `readRows`.
-- **`policyCapability` is a display label and `policyPermissions` is what a report matches on.**
-  A composite renders as `or(feed:read, org:administer)`, which equals no permission string, so
-  `x policy list` matching on `capability` reported every non-trivially-guarded read's permissions
-  as unenforced. `QueryDescriptor.permissions` is the flattened list, published beside
-  `capability` and never instead of it.
-- **`client.ts` injects `traceparent`**, before the caller's own headers so an explicit one wins,
-  and sends nothing when the span context is incomplete — `00-<trace>--01` is a header every
-  collector drops. The twin of `@ultimat3/action`'s, ported for the same tier reason.
-- **A read is `no-store`, and its policy is `enforcedBy: 'handler'`.** The URL names no actor
-  while the answer is scoped to one, so `public` would hand one reader's rows to the next caller
-  of that URL; and `runQuery` is the read's one evaluation, deciding from the parsed input, so an
-  authz stage deciding first would be a second authz system holding raw strings — and would
-  demand an `authorize` hook to decide at all. `http.test.ts` drives both over the real pipeline
-  with no hook wired and counts the evaluations: exactly one.
-- **`meta.auth` is derived from a WALK of the policy tree**, never from the root combinator.
-  `target.policy.kind === 'allow'` answered `'required'` for `or(allow(), can('x:y'))`, so the
-  pipeline's `auth` stage 401'd an anonymous caller the policy itself ALLOWS — while the MCP tool
-  and a direct server read let that caller through the same object. One policy, a different answer
-  per surface. `'public'` here is `meta.auth` only: the read is still `cache: no-store` and
-  `runQuery` still evaluates the policy per caller.
-  **`admitsAnonymous` is `@ultimat3/policy`'s** (`policy.ts`, beside `policyPermissions`) and
-  reaches this package through `policy-gate.ts` like every other authz question — never a copy
-  here. It cannot be one: `@ultimat3/action` needs the identical answer and is the same tier, so a
-  copy in either is a second answer for the other. It is EXACT rather than heuristic — with
-  `actor === null`, `can()` short-circuits before its predicate and `allow()`/`deny()` ignore their
-  arguments, so the tree alone decides. `packages/policy/src/policy.test.ts` asserts it against
-  `policy.run({ actor: null })` itself, case for case; `http.test.ts` proves this projection reads
-  the answer, over the real pipeline.
-- `registry.ts` announces `registerQueries` in core's registrar table at import. That is how
-  `defineApi({ queries })` in `@ultimat3/action` registers a read without importing this package
-  sideways. Never remove the announcement: `defineApi` would then throw `X_REGISTRAR_MISSING`.
-- **Flight control is `@ultimat3/core`'s, and this package RE-EXPORTS it.** `client-flight.ts` and
-  `client-wire.ts` shipped here and in the other tier-3 client package as byte-identical copies —
-  288 and 85 lines — kept in step by a `client-twin.test.ts` in each. A test that makes drift LOUD
-  is not the same as a file that cannot drift, and this package's own thesis is that duplication is
-  the defect. Both files import nothing but tier 0, which was always the argument for where they
-  belong; the one blocker was `isJsonObject`, now `@ultimat3/core`'s `json-object.ts`, re-exported
-  from `./stable` here. `createClientFlight`, `DEFAULT_CLIENT_RETRY`, `isTransientFailure`,
-  `isSuperseded`, `ClientFlight`, `ClientFlightOptions`, `ClientRetry`, `FlightKeyOptions`,
-  `FlightPlan` and `WireAnswer` are all still importable from `@ultimat3/query` — the same names,
-  and now literally the same objects the other package exports. Never re-declare one here; the
-  fix for anything wrong with the pipeline is an edit in `packages/core/src/client-flight.ts`.
-- **Every mechanism underneath the flight is `@ultimat3/core`'s, the pipeline included.**
-  `createSingleFlight` for dedup, `createFence`/`isSuperseded` for supersession, `createFlightGate`
-  for the ceiling, `retry` + `backoffDelay` for the schedule, `isRetryableStatus` for the status
-  table, `X_TIMEOUT` for the deadline — and `createClientFlight`, which composes them. This package
-  declares NO new error code for any of it; never add a second curve, a second fence or a private
-  retry loop here, and `bun run flight-copies` is what says so.
-- **`isTransientFailure` INVERTS `retryDecision`'s unclassified default, and the inversion must
-  survive** (`As of 2026-08-23`). `retryDecision` sends a throw nobody classified again until the
-  attempts run out; `@ultimat3/ai` and `@ultimat3/db` each refused the executor outright over it.
-  The client keeps the executor and supplies a predicate instead: a declared
-  `retryable`/`retry-after`, plus a dispatch that produced no response at all (`fetch` rejecting
-  with a plain `TypeError`), and nothing else — a caller's own `AbortError` and a foreign value are
-  terminal. The loop is stopped by RESOLVING to a private sentinel rather than by throwing, so the
-  original value still reaches the caller unwrapped, which is the property `retry`'s own header
-  promises. It lives in `packages/core/src/client-flight.ts` now; the tests that pin it from this
-  side still drive it through this package's own client.
-- **`ClientFlight` is a TYPE inside `client.ts` and never a value.** That erasure is the entire
-  tree-shaking story: a caller who wants a plain typed read must not pay for the fence, the dedup
-  map or the retry loop. Never import `createClientFlight` for a VALUE from `client.ts` —
-  `ClientFlight` and `ClientRetry` are `import type` from `@ultimat3/core` and must stay that way.
-- **Every read dispatches through `@ultimat3/core`'s `clientTransport`, and `client.ts` calls no
-  `fetch`** (`As of 2026-09-22`, 21.0.0, plan 101 slice 05). The `fetch` option is handed on as the
-  transport's injected `fetchImpl`. The transport owns `Accept`, the trace/budget headers, the
-  principal fence, the error decode and the record envelope — so a gateway's HTML is core's
-  `X_CLIENT_TRANSPORT_FAILED` now, and `QueryRequestFailedError` / `X_RPC_FAILED` are gone from this
-  package. The flight is handed to the transport, which is what dedups concurrent identical reads
-  (`client.test.ts`, one `fetchImpl` call); `fresh` and a per-call `retry` ride on the request
-  to it. The path is core's `queryPath` — `naming.ts` re-exports it as `derivePath`. `slice 15`'s `browser-transport` guard is what will make
-  a `fetch(` call here a build error; until then the check is
-  `rg -n 'fetch\(' packages/query/src --glob '!*.test.ts'` finding nothing.
-- **Bundle, `bun build --target=browser --minify`, `import { queryClient } from '@ultimat3/query'`**
-  (`As of 2026-09-22`): **19,026 B** at 20.2.1 (raw `fetch`), **24,114 B** on `clientTransport`;
-  the deep `src/client.ts` import 15,690 → 20,774 B. The +5.1 kB is entirely core's transport graph
-  (`client-transport.ts`, `client-dispatch.ts`, `client-problem.ts`, `record-envelope.ts`,
-  `client-scope.ts`, `record-sink.ts`, `client-paths.ts`); `client.ts` itself shrank. The 12,755 B this file
-  quoted was already false at 20.2.1. Shrinking it is a `packages/core` edit, never a raw `fetch`
-  here.
-- **`@ultimat3/query/client` is the read client without the barrel** (`As of 2026-09-22`). The
-  barrel anchors `errors.ts` and `registry.ts` (`sideEffects`) and exports the server projections;
-  an island that only reads needs neither. `import { queryClient } from '@ultimat3/query/client'`,
-  measured `bun build --target=browser --minify`: **16,458 B** against **23,611 B** through the
-  barrel. `@ultimat3/realtime`'s `useQuery` is the caller it exists for. `client-subpath.test.ts`
-  pins that the specifier resolves and carries no server export.
-- **…and reaches no titles table** (`As of 2026-09-22`, same method): **10,210 B**, from 16,640 B
-  that morning. `client.ts` and `naming.ts` import core from `@ultimat3/core/page`, and the two
-  page keys live in `page-keys.ts` — a leaf, because `page-controls.ts` refuses a bad value and so
-  imports `errors.ts`, which registers this package's whole code table at import. `client.ts` may
-  never import `page-controls.ts` or `stable.ts` again; `client-bundle.test.ts` fails on
-  `core-error-codes.ts`, `schema-error-codes.ts` or `errors.ts` in the graph, and past 11 kB.
-- **The record envelope is derived from `rows:`, never switched on** (`record-answer.ts`). A read's
-  `sql:` names its table as a STRING, so the query declaration carries no schema the envelope could
-  be derived from; `rows?: StandardSchemaV1<unknown, TRow>` is that carrier, typed against the row
-  `sql:` answers so a projection cannot claim a full entity's schema. `answersRecords(rows)`
-  (`hasEntityRows`, `@ultimat3/entity`) is decided ONCE at projection and read by both `http.ts`
-  and `openapi.ts`; the envelope is sent on EVERY answer (`records: {}` when none came back) — one body
-  shape per operation, action's rule, described once by core's `recordEnvelopeSchema`. No `rows:`,
-  or an unbranded one, is byte-identical on the wire and in `openapi.json`.
-- **The `sideEffects` array is what makes the barrel shakable, and it is load-bearing** (`As of
-  2026-08-23`). Declaring nothing meant a bundler had to assume every module ran at import, so
-  `import { rpc } from '@ultimat3/action'` was 43,104 B and `import { queryClient } from
-  '@ultimat3/query'` was 40,859 B — three times the deep-import cost, through the ONLY specifier
-  the `exports` map offers. The arrays are the ones `bun run scripts/side-effects.ts --explain
-  --json` measures, and they must stay that: `errors.ts` runs `registerErrorCodes` at import in both
-  packages, and query's `registry.ts` runs `registerPrimitiveRegistrar('query', …)` — drop either
-  and a bundled app loses its error titles or throws `X_REGISTRAR_MISSING`. Never `false`.
-- **Every numeric option is refused when it is not a FINITE number, `As of 2026-08-26`.**
-  `@ultimat3/core`'s `finiteOption()` guards the read cache's `ttlMs` and `search()`'s `page.max`,
-  `page.default` and `termMax`; `bun run finite-bounds` is the ratchet and this package is pinned
-  at **zero**. `??` guards nullish and `NaN` is not, so an unchecked bound is a comparison that
-  reads false forever — and `Math.max`/`Math.floor` propagate `NaN` rather than validating it.
-- **`search()` is a FACTORY over `query()`, never a ninth primitive.** It owns the input schema
-  (`q` + a `limit` bounded in the schema, beside the read's own keys), trims and refuses a blank
-  term, and calls `.search(term)` on the chain the app hands it — which is what makes the term
-  unable to arrive any other way. The chain crosses **structurally** (`SearchChain`): this package
-  may import `@ultimat3/entity` and nothing here does, so four methods are not worth a new
-  `package.json` edge and a new `bun.lock` block — the trade `@ultimat3/db`'s `entity-shape.ts`
-  makes one tier down. It needs no row in `PRIMITIVE_FACTORIES`: that table is for a factory
-  returning an `action` or a `job` from OUTSIDE the primitive's own package, and this returns a
-  query from the query package. **It serves ONE page and refuses a second**, because a `SqlSource`
-  is handed a `SeekKey` and the entity chain wants its own signed, plan-scoped cursor — there is no
-  minting one from the other here, and falling through to `paginate`'s in-memory slice would cut
-  inside the one page the provider fetched and report `hasNextPage: false` at its edge. Rows served
-  on no page at all is the defect 12.0.0 spent a release removing from the timestamp seek; the
-  `fix:` names the entity chain, which pages this read correctly. **The refusal is on the rows that
-  would be CUT, never on the window**, `As of 2026-08-26`: a screen demanding `first >= limit`
-  refuses the framework's own default pair — `limit` defaults to 20 and `first` arrives from a
-  client — so every `pageSize` under 20 was a 500 at page ONE, including a search matching three
-  rows that fit the window twice over. `windowOf.execute` asserts on `rows.length` instead, so a
-  page that is whole is served with `hasNextPage: false` and no cursor is ever handed back that a
-  second call is guaranteed to refuse. **The one page it serves is the
-  chain's own ORDER**, `As of 2026-08-26`: `onePage.seek` narrows the window with `Builder.limit()`
-  and never with `Builder.seek()`, which sets `totalized` — `servedOrder()` is then `totalOrder([])`
-  = `id asc`, because the ranking lives inside the chain behind the row thunk and no `OrderKey` here
-  can name it, and `execute()` re-sorts the page the provider already ranked. Measured with a chain
-  serving `z, m, a`: `runQuery` answered `z, m, a` and `.page(input, { first: 2 })` answered `a, m`,
-  dropping the top-ranked row off page one. It exposes no `total()` for the same reason — an absent
-  `total` is how `SqlSource` says the source already serves one order it can be resumed in. The
-  fixture in `search.test.ts` must stay NOT id-ascending: `ROWS` is `a, b, c`, which is why the
-  shipped page test could not see this.
-- **`subscribes:` is DECLARED because nothing can derive it, and CROSS-CHECKED because a
-  declaration drifts** (`subscribes.ts`, `As of 2026-08-26`). `@ultimat3/realtime` refuses a
-  subscription to a table that is not `REPLICA IDENTITY FULL` — logical replication carries no old
-  row on an `UPDATE`, so no patch is computable — and nothing emitted the `alter`, so a scaffolded
-  app with a live query generated a schema its own preflight rejected (#357). It cannot be derived:
-  the relation name is a string inside `sql:`, a callback no generator can invoke without valid
-  input, so `QueryDescriptor` carried no table and `x db gen` had no live-query set to read. The
-  field is optional and a read that declares nothing is unchanged — the emitter sees no table.
-  The cross-check is what makes it worth shipping: `toLiveQuery` asserts `shape.entity` is among the
-  declared names at the first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`), one line under
-  `assertMatchable` and for its reason — a live read whose old row never arrives cannot be patched,
-  so a WARNING would preserve only a subscription that silently stops updating, and the stale
-  declaration has already granted the identity to the wrong table. `pg-preflight.ts`'s
-  `warnPartialIdentity` warns instead, and that precedent does NOT transfer: it fires for every app
-  on the postgres default, which nobody wrote, while this fires only on a declaration an author
-  wrote wrong. **Membership, never equality** — a `QueryShape` names one relation and a read may
-  join several, and `@ultimat3/db` keeps only the declared names an entity's table matches, so an
-  extra name costs nothing and the resolved one going missing is the whole failure. An empty list,
-  or one on a read that is not `live: true`, is refused at `query()`
-  (`X_QUERY_SUBSCRIBES_INVALID`) beside `assertCacheTtl`: a declaration nothing can act on is wrong
-  for every subscriber, and one on a non-live read would never reach the cross-check at all —
-  declared and never wired, which is the defect this field exists to close.
-- Policy runs per subscriber for live queries. Never cache a decision across actors.
 - The matcher patches from `QueryShape`, never from SQL text.
-- `paginate` has no `offset` parameter and must never grow one, and it is reachable **only** as
-  `query.page(input, { first, after })` — a page is the read's own answer, not an imported helper.
-  `src/index.ts` exports `Page` and `PaginateArgs` and not the function: re-exporting it would be
-  a second way to ask for the thing `.page()` already does.
-- **A `RowProvider` may be a list, a sync function or an async one** (`As of 2026-08-19`).
-  `execute()` awaits whatever the function returns, so all three were always accepted at runtime —
-  the type declared only `() => Promise<readonly TRow[]>`, which refused a repo method already
-  holding its page and every in-memory fixture. `source.test.ts` pins all three.
-- **A cursor is a position, not a row.** `isAfterKey` in `source.ts` is the one definition of
-  "after this position": `Builder.seek()` compiles it to SQL and `paginate()` applies it when a
-  source cannot push the seek down. The fallback used to find the cursor's row by id and slice
-  after it — which restarts the listing from the top the moment that row is deleted, the exact
-  failure keyset pagination exists to prevent. Never reintroduce a row lookup here.
-- The seek predicate is spelled out per key (`(a < $1) or (a = $2 and id > $3)`), the way
-  `@ultimat3/entity`'s `seekSql` spells it. A row-value comparison cannot express a mixed
-  `createdAt desc, id asc` ordering, and the id-tiebreak-only fallback it replaced returned rows
-  the ordering was already past — with `execute()` disagreeing with the SQL it printed.
-- **NULL has one meaning, and `isNull` is it.** `null` and a column the row omits are the same
-  absence, in the SQL and in memory alike. `=`/`!=`/`in` read NULL as a **value** — `is null`,
-  `is not null`, `is distinct from`, `in (…) or is null`, the pair `@ultimat3/entity`'s
-  `predicateSql` emits; `>`/`>=`/`<`/`<=` read it as **unknown**, matching nothing on either side,
-  which is why they need no special emission; `order by` reads it as the **largest value**, spelled
-  `asc nulls last` / `desc nulls first` rather than inherited from the driver. `= $n` with a NULL
-  argument is never true in Postgres, so `where({ deletedAt: null })` matched every row in memory
-  and none in the database, and `"col" > $n` blanked page two at the first NULL. Never emit a bound
-  parameter where NULL is the value being tested, and never let `compareValues` sort a NULL as the
-  string `"null"` again — `compareRows`, `isAfterKey` and the matcher's insertion position all
-  read it, so one string compare moves rows on three surfaces. `in` takes a list or nothing: an
-  empty one is `1 = 0`, and so is an operand that is not an array at all — `matchesFilter` answers
-  no rows for it, and `"col" in $n` is a syntax error the driver reports instead of that answer.
-- **The id is the tiebreak that makes the order total.** A row without one is
-  `X_QUERY_NOT_PAGEABLE` at `seekKeyOf` **and** at the matcher's `idOf`, never `String(undefined)`:
-  `"undefined"` is a position every row matches, signed and opaque, so page two would be page one
-  forever and one row's patch would land on another's index.
-- **`totalOrder` is the order a read is served in, and all three readers use it.** The declared
-  keys then `id asc`, unless the ordering already names `id` — `Builder.servedOrder()` compiles it,
-  the in-memory sort applies it, and `positionFor` places a row by it. The matcher comparing
-  `shape.orderBy` alone appended a tied row after its whole tie group, which is a position no
-  re-read returns and a cursor that skips every tie it was pushed past. `SeekKey` is the same list
-  decomposed — `key` for the declared part, `id` for the tiebreak — so never add `id` to
-  `QueryShape.orderBy` to get it: `seekKeyOf` would then sign the id twice. An unordered query
-  appends, because SQL promises no position there to get wrong.
-- **A live read asks for that order explicitly, and `sourceFor` is where it asks.** `total()` is
-  the `SqlSource` method for "the same read, served in `totalOrder`" — no cursor, no window — and
-  `buildSource` calls it when `surface === 'live'`, for nothing else, and only when the source
-  implements it. A live window served by the declared keys alone puts a tied row wherever the
-  database returned it, while `positionFor` places the patch by id and the resume re-read seeks by
-  id: the client then renders an order no re-read answers. Never reach for `seek(null, limit)`
-  instead — a live query need not carry a limit, and inventing one is a window nobody asked for.
-- **A sort value carries its own TYPE through the cursor** (`cursor-value.ts`, `As of 2026-08`).
-  The codec is JSON, so `paginate()` putting raw column values in meant a `Date` went out and an
-  ISO STRING came back: `isAfterKey` compared `"1769904000000"` against `"2026-02-01T…"` through
-  `compareValues`' string branch and **page two came back empty** — and a `bigint` sort key was a
-  bare `TypeError` out of `JSON.stringify`, with no code and no fix. `@ultimat3/entity`'s
-  `cursor.ts` solves the same problem by reading the column's declared kind; a `query` has no
-  column kinds — `QueryShape.orderBy` is a name and a direction — so the value is TAGGED instead
-  (`{ $x: 'date' | 'bigint', v }`) and `reviveSortKey` is total without knowing which read minted
-  it. `undefined` encodes as `null`, because SQL has one absence and dropping the key would shift
-  every later one a position left. Anything JSON cannot carry and this cannot tag — an object, an
-  array, `NaN`, `±Infinity` — is `X_CURSOR_VALUE_UNSUPPORTED` where the cursor is MINTED, never
-  `X_CURSOR_INVALID`: the mistake is the read's own `orderBy` and no retry repairs it.
-- **`compareValues` orders numbers and bigints in ONE order, because Postgres does.** The numeric
-  fast path was `typeof === 'number'` on both sides, so an `int8` fell to
-  `String(left) < String(right)`: `compareValues(9n, 10n)` answered `1` and a sort came out
-  `["10", "100", "9"]`. `bigint` is the physical type of every `<p>_minor` column and
-  `@ultimat3/entity`'s `count-by.ts` lists it as groupable, so the in-memory source, the live
-  matcher and the seek fallback ALL disagreed with the database on any bigint-ordered read.
-  `shape-order.test.ts` is the pin, and `As of 2026-08` it reads a REAL kind list: `COLUMN_KINDS`
-  is the runtime array `@ultimat3/entity`'s `ColumnKind` derives from, and entity is tier 2 so a
-  test here may import it as a VALUE — which is what a `satisfies Record<ColumnKind, …>` could not
-  be, since `tsconfig.json` excludes `*.test.ts` and `tsc` never reads one. It had a spelled-out
-  list and `const COUNT = 9` beside a union of THIRTEEN members: `9 === 9`, a test that could not
-  fail, with `numeric`, `date`, `bytea` and `array` carrying no case at all.
-- **`numeric` and the TEXT form of `bigint` are a DECLARED gap here, and closing it is a
-  declaration change** (`shape-order.test.ts`, `As of 2026-08`). `@ultimat3/entity`'s `bigint()`
-  and `decimal()` hand digits back as strings, so `["9","10","100","2"]` sorts to
-  `["10","100","2","9"]` here and `["2","9","10","100"]` in the database — and a cursor's revived
-  `bigint` against a stored decimal string (`compareValues(9n, "10")` → `1`) cuts page two where
-  the database does not. It is **not** fixed by calling `@ultimat3/core`'s `compareDecimalText`
-  from `compareValues`: that function answers only for a caller holding the column's declared kind
-  (`@ultimat3/entity`'s `compareByKind`), and `QueryShape.orderBy` is a name and a direction —
-  nothing here can tell a `numeric` holding `"10"` from a `text` holding `"10"`, which Postgres
-  orders lexically, so a comparator guessing would trade one disagreement with the SQL it prints
-  for another. The fix is an `OrderKey` that carries a kind, from `sourceFor` down. Until then the
-  `DECLARED_GAP` block asserts both halves, so the gap cannot be silently re-discovered or
-  silently widened.
-- **A read's `input:` must survive a query STRING, and `query()` refuses one that cannot**
-  (`input-shape.ts`, `X_QUERY_INPUT_UNENCODABLE`, `As of 2026-08`). `client.ts` encoded a nested
-  member as `JSON.stringify(item)` and skipped a `null`, while `coerceQuery` has no inverse for
-  either — `case 'object'` hands the raw value back untouched — so the typed client type-checked
-  calls the server's own route then rejected, which is the exact failure `client.ts`'s header
-  claims to prevent. **The declaration is the fix, not the encoder**: teaching `coerceQuery` to
-  `JSON.parse` a string would make the ONE HTTP-boundary decoder invent structure for every
-  surface that shares it — forms and route params included — against that file's own rule that it
-  never invents data, and a `null` sentinel would be a reserved string colliding with the value
-  `"null"`. Refused: a structural member (`object`, `record`, `money`, or an array/union of one),
-  a REQUIRED nullable member, and a top-level input that is not an object. A schema
-  `tryIntrospect` cannot read is left alone, or `configureSchemaProvider` would be unusable.
-- **A refill is owed by a FULL window and by nothing else** (`matcher.ts`, `As of 2026-08`).
-  `removeAt` pushed one whenever `shape.limit !== null`, with no reference to how many rows the
-  window holds: three rows under `limit: 50`, delete one, and the patch list was
-  `[{remove, position:1}, {refill, from:49}]` — a position no two-row result set has. It is not a
-  harmless extra: `@ultimat3/realtime`'s `matcher-bridge` folds any refill into
-  `BridgeResult.refill`, and `live-fanout` then sends **no patch frame at all** that round, marking
-  every subscriber desynced instead — so on a quiet feed the deleted row stays rendered until some
-  other change to the same query id arrives, and on a busy one it is a full DB re-read plus one
-  snapshot per subscriber per delete. A window under `limit` has no unknown tail: the source served
-  fewer rows than it was allowed to, so what the client holds IS the result set. `held >=
-  shape.limit` is the gate, and it is `wasFull` one branch away, already written.
-- **A move OUT of a full window is a `refill`, never an `add`** (`matcher.ts`). `insert()` places a
-  moved row among the `limit - 1` rows the client still holds, so its position can never reach
-  `shape.limit` and the `position >= shape.limit` bail is unreachable on that path — the row was
-  re-inserted INSIDE the window. Proven with `limit: 3`, window `[a:1, b:2, c:3]` and a server also
-  holding `d:4, e:5`: moving `a` to `99` rendered `[b, c, a:99]` where the true window is
-  `[b, c, d]`. Only the server can answer the tail, and whether the moved row is still in the
-  window is its answer too.
-- **A page is bounded whether or not the caller bounded it.** `paginate` asserts `first` is a whole
-  number of rows in `1…MAX_PAGE_SIZE` (10,000) before anything else — `args.first + 1` bound
-  whatever an action's input or a route parameter carried, so one request could ask for five
-  million rows. The constant is a TWIN of `@ultimat3/entity`'s, under the same tier compromise
-  `naming.ts` and `deprecation.ts` are ported under.
-- **`tagKeys` is `@ultimat3/cache`'s, not this package's — moved 2026-08.** `src/tags.ts` here and
-  `@ultimat3/action`'s were byte-identical, and both packages 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`. `tagKey` went with it: `serializeTag` under a second name, zero call sites.
-  `@ultimat3/render` exports a *different* function under the same name (declaration order kept);
-  never import that one here.
-- **A fingerprint is an identity, so two different inputs may not share one — and it is
-  `@ultimat3/core`'s, not this package's, `As of 2026-08`.** `canonicalJson` + `fingerprint` moved
-  down to tier 0 because `@ultimat3/action` and `@ultimat3/realtime` needed the identical function
-  and all three are tier 3, so a copy in any of them was a second answer for the other two — and
-  the copies had already diverged. This one had **no `Date` branch**: `Object.keys(date)` is `[]`,
-  so the object branch rendered every date as `{}` and `queryHash({from: 2020…, to: 2020…})`
-  equalled `queryHash({from: 2026…, to: 2026…})`. Reachable on the ordinary HTTP path — `http.ts`
-  decodes a query string through `coerceQuery`, which turns a `t.date` member into a real `Date`,
-  and `input-shape.ts` permits `date` members — so ONE read-cache entry answered every date window
-  of that read for the TTL, page two of range A was served from range B's cursor scope, and every
-  date window shared one live query id. The hash form tags a `Date`, a `Map` and a `Set`
-  (`Date(<epoch>)`, `Map(…)`, `Set(…)`) beside the bare `NaN` / `±Infinity` / `-0` tokens it
-  already emitted, all for the reason a bare token exists: `'null'` collided with JSON `null` and
-  `String(-0)` is `"0"`. `stable.ts` keeps `columnOf` and a re-export of core's `isJsonObject` —
-  that predicate went down to tier 0 the same way, when `client-wire.ts` did. Ordinary
-  inputs are byte-identical, so the durable-key cost is confined to reads whose input carries a
-  `Date`, a `Map` or a `Set`: those cursors answer `X_CURSOR_INVALID` once, and their cache entries
-  are cold once. `query-hash.test.ts` is the pin, at `queryHash` and at `cacheKeyFor`.
-- The cursor codec is `@ultimat3/core`'s (`encodeCursor` / `decodeCursor` / `configureCursorSigning`).
-  This package supplies only the scope a cursor is bound to — `queryHash(name, input)` — and never
-  signs, encodes or parses one itself. An unverified or foreign cursor is `X_CURSOR_INVALID`, thrown
-  by core's `CursorInvalidError`, which `errors.ts` re-exports so the name stays on this surface.
-- **The request memo holds the read, not the rows.** `readOnce` publishes the in-flight promise
-  before its first await, so two reads of one key in one request are one execution and one tier
-  round trip whether the second follows the first or races it. A value-keyed map could not express
-  that, and could not tell a memoized `undefined` from a miss either. A rejection is evicted — a
-  failed read is not the request's answer, and the next read retries. `requestMemo(ctx)` is
-  therefore `Map<string, Promise<unknown>>`; never put a settled value in it.
-- **Every read is memoized; only a `cache:` read goes through the tier.** `readThrough` is
-  `readOnce` plus the fill through the ladder, and `readRows` picks between them on `def.cache`
-  alone. The memo is not what `cache:` buys — a list that renders one uncached lookup per row pays for
-  every row otherwise, which is the N+1 this collapses. Never gate `readOnce` on `def.cache`
-  again, and never let a second key function grow beside `cacheKeyFor`.
-- **A cache key carries the read's AUTHORITY, and `cache.scope` is what widens it** (`As of
-  2026-08`). `cacheKeyFor` held the name, the input and the tags — nothing about who asked — while
-  `sql(input, ctx)` is handed the context and `@ultimat3/entity` derives every tenant predicate
-  from `ctx.actor.orgId`. The tier is process-wide, so the first actor to ask filled the entry and
-  the next was served it: a query filtering on `ctx.actor.orgId` returned `org-a`'s row to an
-  `org-b` actor. `readAuthority(actor, scope)` is the ONE producer of the component and
-  `cacheKeyFor`'s fourth argument is **required and positional**, because an optional one is one a
-  call site forgets and a forgotten one is that read. `scope` defaults to `'actor'` and the default
-  is the mechanism: declaring nothing gets the narrowest key. `'tenant'` and `'global'` are written
-  statements about the rows — the `unenforced:` shape one field over — and `'tenant'` with no
-  `orgId` narrows to the actor rather than widening to everyone, because nothing here can prove two
-  org-less callers share a tenant. **All THREE spellings of "no org" take that branch**, `As of
-  2026-08`: `undefined`, `''` and `null`. The last one missed it, so every org-less caller shared
-  the single key `["org",null]` and was served the rows of whoever asked first. `orgless()` widens
-  its parameter past core's `orgId?: string` because **`orgId` is a value off the wire** — an app's
-  adapter, a decoded session row, a JSON payload — not because a declared type permits a `null`.
-  `@ultimat3/policy`'s `PolicyActorFields` reads like the reason and is not it (corrected
-  2026-08-19): `Actor = CoreActor & PolicyActorFields`, and that intersection collapses its
-  `string | null | undefined` back to `string | undefined`, so the widening is **inert** at the type
-  level and `{ orgId: null }` is a type error. Its `testActor` mints `orgId: null` through the one
-  cast left in `packages/policy/src/test-kit.ts`, which is why `cache-authority.test.ts` can reach
-  this branch at all — the repo's only producer of that `null`, and a test seam rather than a proof.
-  The authority is JSON, never a joined string, for the reason
-  `@ultimat3/entity`'s `scopeKey` gives: an actor id is app data and may carry the separator.
-- **`cache.ttlMs` is judged at `query()`, not on the first read.** Every `CacheTier` refuses a
-  lease that is not positive and finite (`assertTtl`), and the read tier's one catch absorbs
-  `X_CACHE_TOO_LARGE` only — so `ttlMs: Infinity` turned a typo into a permanently failing business
-  read whose cause named a cache key. `X_QUERY_CACHE_TTL_INVALID`, on the line that wrote it. It
-  restates `assertTtl`'s bar as a refusal and never as a second resolution.
-- **`fingerprint` is SHA-256/16, never a 32-bit hash** (`@ultimat3/core`, `As of 2026-08`). It is a
-  SHARING key over client-chosen input — which read-cache entry two callers are served from, which
-  scope a cursor is bound to — so FNV-1a/32's 4×10⁹ values are a collision found offline in
-  seconds. `@ultimat3/realtime`'s `stableDigest` was the same primitive at the same width and is
-  gone with the rest of that copy: a `qid` is `queryHash(name, input)` now, imported across the
-  declared `realtime -> query` edge, so the two hashes cannot drift apart while `planResume`
-  compares one against a cursor's.
-- **A fill is FENCED, and the fence is `@ultimat3/cache`'s** (`As of 2026-08`). `run()` answers with
-  rows it read in the past: a mutator committing in between busts a key not yet in the tier, so the
-  drop is a no-op reporting `errors: []`, and the fill then publishes the pre-write rows for the
-  full TTL — invisible to every reader until it expires. The sample happens inside
-  `createCacheStack.read`, immediately before `load()`, and is re-asked per rung before each write.
-  This package no longer samples one of its own — that copy went with the private store. The caller
-  is answered either way: those rows ARE its answer, and only publishing is refused.
-  `cache-fence.test.ts` is the proof the property survived the move.
-- **This package owns NO cache store, and that is the enforcement** (`As of 2026-08`). A `cache:`
-  read fills `createCacheStack(registeredTiers(), { clock })` — the tiers `@ultimat3/cache` has
-  registered — and there is nothing here to install, swap or wire. There used to be: a private
-  `ReadCache` seam (`setReadCache`/`getReadCache`/`MemoryReadCache`) that `invalidateTags` could not
-  reach, because that fan-out walks the registered `CacheTier`s and nothing else. The gap was closed
-  by `packages/cli/src/dev-cache.ts` installing the read cache **over** an object it also
-  registered — a correctness property held by a wiring line in a CLI file, one edit from being
-  wrong, and carrying a second `ReadCache` implementation (`tierReadCache`) that dated entries with
-  `Date.now()`. And `invalidateQueryTags` was a second fan-out path, which
-  `packages/cache/CLAUDE.md` forbids in as many words. One registry, one fan-out, no seam. **Never
-  reintroduce a store here**, and never call `tier.invalidateTags()` from this package.
-- **A tier refusal degrades the cache, never the read** — and so does every other tier concern.
-  `bestEffort`, the fence, the single flight, the promotion and the TTL are all `createCacheStack`'s,
-  which is what "no store here" buys: a refused `get` reads as a miss, a refused `set` as "that tier
-  is unchanged", and the failure lands in `recentTierFailures()` under the name of the tier that
-  actually refused rather than under a `'query-read'` label for a rung in no registry. Never wrap a
-  tier call here in a private try/catch, and never sample a second fence.
-- **The read path reads NO clock, and that is what makes it drivable.** It hands the stack a
-  RELATIVE `ttlMs`; the tier's own clock turns it into an absolute expiry. `fill` used to compute
-  `nowMs(clock) + ttlMs` and `tierReadCache` used to compute `expiresAt - Date.now()`, so the two
-  `ReadCache` implementations disagreed about "now" and no frozen clock could drive the
-  Redis-backed one. `read-tier.test.ts` pins it: a `createLruTier({ clock, jitterFraction: 0 })` and
-  a `ctx.clock` frozen at the same instant produce an expiry a test can assert exactly.
-- **A `cache:` read always expires, and the bound is the tier's.**
-  `def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS` (60s) is what `readRows` passes — a query keyed on
-  `{ orgId, cursor }` has as many distinct keys as the deployment has tenants, and unbounded that is
-  one permanent entry per page per org. `null` is "the caller named none", never "never": it reaches
-  the stack as an OMITTED `ttlMs`, which is how a tier is asked for its own default. Every tier
-  refuses a non-positive lease outright, so there is no immortal entry to spell.
-- **A process that registered no tier reads uncached.** `createCacheStack([])` loads, answers and
-  writes nowhere — correct, and slower. That is the trade for deleting the module-default store: a
-  script, a worker boot or a test that wants caching calls `registerTier`, the same call every
-  other cached surface in the framework already uses.
-- **The memo holds an execution, never a decision.** `readRows` runs `buildSource` — parse, guard,
-  `sql()` — *before* it reaches the memo, on every call, and `.as()` reads in a child context whose
-  identity is its own memo. So a memoized answer is still one this actor was allowed to ask for,
-  and no impersonated read can join a read made as someone else. Moving the memo above
-  `buildSource` would turn it into an authz bypass.
-- **`fresh: true` skips the memo on the way in and publishes to it on the way out.** A memo is a
-  cache whose lifetime is the request, so `fresh` refuses to *join* an entry — `readFresh` is
-  `readOnce` minus the join, both sharing one `publish` — but it must still *become* one. Returning
-  the rows early instead left the pre-write entry standing, so "the one way to read past a write
-  made earlier in the same request" ended at the single call that asked for it and the next plain
-  read of that key got the stale answer back. Invalidation still drops tier entries only.
-- **A read can declare a `rateLimit:`, and `toQueryRoute` enforces it — added 2026-08.** `QueryDef`
-  had no such field and the route set no bucket, so **every** `GET /_x/query/*` fell through
-  `bucketFor` to `default` — 120 burst, 2/s per actor. One authenticated caller could hold 120
-  cross-tenant aggregates in flight and then 2/s indefinitely, from a single account, and the
-  declaration that would have throttled it did not exist in the type. `meta.rateLimit` (the name)
-  **and** `meta.rateLimitBucket` (the numbers) are both set, because a name nothing registers is
-  the same silent fall-through. The conversion is `toBucket` from **`@ultimat3/http`** — http owns
-  `Bucket` and the maths, and `@ultimat3/action` is this tier, so a copy here would be a second
-  answer for the write half. Never derive a bucket locally.
-- **`deprecated:` is a compat WINDOW; versioning is not here and will not be.** `Deprecation`
-  (RFC 9745, `@<unix seconds>`) and `Sunset` (RFC 8594, IMF-fixdate) on every answer including the
-  failures, a `rel="successor-version"` link built through `derivePath` — the same derivation
-  `client()` uses, never a second one — the dates on the descriptor, and
-  `deprecated_calls_total{primitive,name}`, which is the only way to answer "is anyone still
-  reading it?" before deleting the read. Rendered ONCE at projection, so a date that cannot become
-  a header is `X_QUERY_DEPRECATION_INVALID` at mount rather than on the first read. Running two
-  versions side by side is two deployments behind one ingress (axiom 7). `deprecation.ts` is a
-  twin of `@ultimat3/action`'s: both are tier 3, the shared home is `@ultimat3/http` if it ever
-  grows one, and this is the same compromise `naming.ts` is ported under.
-- **The span wraps the whole read, not `source.execute()`.** Wrapping the execution alone left the
-  input parse, the policy evaluation and `sql()`'s own construction outside every span, so a read
-  whose cost was in building the source reported milliseconds under a parent reporting seconds —
-  a gap with no name, which reads as framework overhead. Attributes are bounded: surface, actor
-  KIND, `live`, `cached`, `fresh`, and the row count. Never the input and never an actor id — a
-  read is keyed per tenant and per cursor, so either would be unbounded. `telemetry.test.ts`
-  asserts the EXTENT structurally, reading `currentSpan()` from inside the policy predicate and
-  `sql:`, because the test clock is frozen and a timing assertion would hang on it.
-- **`policyCapability` is a display label; `policyPermissions` is what a report matches on.** A
-  composite renders as `or(feed:read, org:administer)`, which equals no permission string, so
-  `x policy list` matching on `capability` reported every non-trivially-guarded read's permissions
-  as *unenforced*. `QueryDescriptor.permissions` is the flattened list from `@ultimat3/policy`,
-  published beside `capability` and never instead of it.
-- **`queryClient`/`client()` inject `traceparent`.** Core's `traceparent()` had no caller in the
-  repo, so a service-to-service read began a fresh root trace on the far side. Set BEFORE the
-  caller's own headers so an explicit one wins; an incomplete span context (`spanId: ''`) sends
-  nothing rather than a header every collector drops. In a browser there is no ambient context, so
-  a cross-origin read gains no CORS preflight it did not already have. The helper is twinned in
-  `@ultimat3/action`'s client for the same tier reason `naming.ts` is.
-- Authz goes through `enforce(surface, policy, { input, actor, ctx })` from
-  `@ultimat3/policy`; a live denial keeps its 4403 close code on `QueryDeniedError.denial`.
-  `policy-gate.ts` is the only file that imports the policy package.
+- `paginate` has no `offset` and never grows one; it is reachable only as
+  `query.page(input, { first, after })`. **A page is bounded**: `first` is 1…`MAX_PAGE_SIZE`
+  (10,000, a twin of `@ultimat3/entity`'s).
+- **A `RowProvider` may be a list, a sync function or an async one** (`source.test.ts`).
+- **A cursor is a position, not a row**: `isAfterKey` (`source.ts`) is the one definition of "after";
+  never reintroduce a row lookup. The seek predicate is spelled out per key
+  (`(a < $1) or (a = $2 and id > $3)`), never a row-value comparison.
+- **NULL has one meaning, `isNull`**: `=`/`!=`/`in` treat NULL as a value (`is null`,
+  `is distinct from`, `in (…) or is null`); range operators treat it as unknown; `order by` treats it
+  as the largest value (`asc nulls last` / `desc nulls first`). Never bind a parameter where NULL is
+  the tested value. `in` with an empty or non-array operand is `1 = 0`.
+- **The id is the tiebreak that makes the order total.** No id is `X_QUERY_NOT_PAGEABLE`, never
+  `String(undefined)`. **`totalOrder`** (declared keys, then `id asc`) is the served order for SQL,
+  memory and `positionFor`; never add `id` to `QueryShape.orderBy`. A live read asks for it via
+  `SqlSource.total()` (called by `buildSource` for `surface === 'live'`), never `seek(null, limit)`.
+- **The keyset tiebreak keeps the id's TYPE** (`SeekKey.id: unknown`), carried at the tail of `key`
+  through `serializeSortValue` (`pagination-id-type.test.ts`).
+- **A sort value carries its TYPE through the cursor** (`cursor-value.ts`: `{ $x: 'date' | 'bigint',
+  v }`; `undefined` → `null`). Untaggable values are `X_CURSOR_VALUE_UNSUPPORTED` where the cursor is
+  minted.
+- **`compareValues` orders numbers and bigints in one order**; equality treats `number` and `bigint`
+  as one family (`shape.ts` `same`). `shape-order.test.ts` reads `@ultimat3/entity`'s `COLUMN_KINDS`.
+- **`numeric` and the TEXT form of `bigint` are a DECLARED gap** (`DECLARED_GAP` in
+  `shape-order.test.ts`): closing it needs an `OrderKey` carrying a kind, never a guessing comparator.
+- **A refill is owed by a FULL window only** (`held >= shape.limit`). **A move OUT of a full window is
+  a `refill`, never an `add`.**
+- **A position is decided against the rows the WINDOW holds**: `unprojectedOrderKey` — a held row
+  missing an ordering column (`Object.hasOwn`, never a value check) gets a `refill` rather than a
+  guess. A delete is addressed by index and still patches.
+- **`tagKeys` is `@ultimat3/cache`'s.** `@ultimat3/render` exports a different `tagKeys`; never import
+  that one here.
+- **A fingerprint is `@ultimat3/core`'s** (`canonicalJson` + SHA-256/16 `fingerprint`), tagging `Date`,
+  `Map`, `Set`. `query-hash.test.ts` pins it at `queryHash` and `cacheKeyFor`. `stable.ts` keeps
+  `columnOf` and re-exports core's `isJsonObject`.
+- The cursor codec is `@ultimat3/core`'s; this package supplies only the scope (`queryHash(name,
+  input)`). An unverified cursor is `X_CURSOR_INVALID` (`CursorInvalidError`, re-exported).
+
+## Invariants — caching
+
+- **The request memo holds the read, not the rows**: `readOnce` publishes the in-flight promise
+  before its first await; a rejection is evicted. `requestMemo(ctx)` is `Map<string, Promise<unknown>>`.
+- **Every read is memoized; only a `cache:` read goes through the tier** (`readThrough`). One key
+  function, `cacheKeyFor`.
+- **A cache key carries the read's AUTHORITY**: `readAuthority(actor, scope)` is its one producer and
+  `cacheKeyFor`'s fourth argument is required. `scope` defaults to `'actor'`; `'tenant'` with no
+  `orgId` (`undefined`, `''` or `null` — `orgless()`) narrows to the actor. The authority is JSON.
+- **`cache.ttlMs` is judged at `query()`** (`X_QUERY_CACHE_TTL_INVALID`). A `cache:` read always
+  expires: `def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS` (60 s); an unset TTL is OMITTED so the tier
+  defaults.
+- **A fill is FENCED, by `@ultimat3/cache`'s fence inside `createCacheStack.read`** — never a second
+  one here (`cache-fence.test.ts`).
+- **This package owns NO cache store**: a `cache:` read fills
+  `createCacheStack(registeredTiers(), { clock })`. Never reintroduce a store, never call
+  `tier.invalidateTags()` here. A tier refusal degrades the cache, never the read.
+- **The read path reads NO clock** — it hands the stack a relative `ttlMs` (`read-tier.test.ts`).
+- **A process that registered no tier reads uncached** — correct, and slower.
+- **The memo holds an execution, never a decision**: `buildSource` (parse, guard, `sql()`) runs on
+  every call before the memo. Moving the memo above it would be an authz bypass.
+- **`fresh: true` skips the memo on the way in and publishes to it on the way out.**
 
 ## Commands
 
@@ -597,21 +195,4 @@ bun test packages/query
 bun run typecheck
 ```
 
-**A position is decided against the rows the WINDOW holds, so a window that cannot answer gets a
-`refill` rather than a guess** — `unprojectedOrderKey`, `As of 2026-08-20`. A result set is whatever
-the query's `sql` returned, and a PROJECTION that drops an ordering column left `compareRows`
-measuring the change row's real value against nothing: never equal on the update path, so every
-change read as a move, and arbitrary on the insert path, so a row created last landed wherever
-`undefined` sorted. `examples/dummy`'s feed ordered by `createdAt` and projected without it, and one
-publish became a `remove` + `insert` whose re-inserted row was the raw table row (#230).
-
-The discriminator is **`Object.hasOwn`, never a value check**: a nullable column that IS null still
-carries its key, and everywhere else in this package an absent key and a SQL NULL are one absence
-(`isNull` says so). Here they are different facts — "this row's value is nothing" versus "this shape
-cannot answer" — and only the key tells them apart. Asked of the row the window holds and never of
-the change row, which comes off the table and can always answer. A **delete** never reaches the rule:
-it is addressed by the index its id was found at, so a projected query still removes incrementally.
-
-The rule generalises what `assertSeekable` already applies to a cursor: **a sort key has to be
-readable on the row.** A live query whose rows omit one still works — it re-reads instead of
-patching — which is correct and slower, and the fix is to project the key.
+Why each rule above is shaped the way it is: [`docs/history/query.md`](../../docs/history/query.md).

package/README.md

@@ -520,6 +520,27 @@ router feature here.
 Denials re-throw the policy layer's own codes and keep the surface denial on
 `QueryDeniedError.denial`, so a live socket closes with 4403 instead of guessing.
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `CursorValueUnsupportedError` | `X_CURSOR_VALUE_UNSUPPORTED` | `src/errors.ts` |
+| `MatcherUnsupportedError` | `X_MATCHER_UNSUPPORTED` | `src/errors.ts` |
+| `QueryDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
+| `QueryDeprecationInvalidError` | `X_QUERY_DEPRECATION_INVALID` | `src/errors.ts` |
+| `QueryDuplicateError` | `X_QUERY_DUPLICATE` | `src/errors.ts` |
+| `QueryForeignError` | `X_QUERY_FOREIGN` | `src/errors.ts` |
+| `QueryInputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |
+| `QueryInputUnencodableError` | `X_QUERY_INPUT_UNENCODABLE` | `src/errors.ts` |
+| `QueryNotPageableError` | `X_QUERY_NOT_PAGEABLE` | `src/errors.ts` |
+| `QueryPolicyMissingError` | `X_QUERY_POLICY_MISSING` | `src/errors.ts` |
+| `QuerySubscribesDriftError` | `X_QUERY_SUBSCRIBES_DRIFT` | `src/errors.ts` |
+| `QuerySubscribesInvalidError` | `X_QUERY_SUBSCRIBES_INVALID` | `src/errors.ts` |
+| `QueryUnregisteredError` | `X_QUERY_UNREGISTERED` | `src/errors.ts` |
+
 ## Boundaries
 
 Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `entity`, `http`, `policy`. Never imports `action`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -36,11 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "21.0.0",
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/entity": "21.0.0",
-    "@ultimat3/http": "21.0.0",
-    "@ultimat3/policy": "21.0.0",
-    "@ultimat3/schema": "21.0.0"
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/http": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/schema": "22.0.0"
   }
 }

package/src/deprecation.ts

@@ -74,8 +74,3 @@ export function renderDeprecation(
   };
   return { ok: true, headers, meta };
 }
-
-/** Set on a response that already exists, so a problem document carries them too. */
-export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
-  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
-}

package/src/errors.ts

@@ -17,6 +17,7 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_CURSOR_VALUE_UNSUPPORTED: 'a sort value cannot be carried in a cursor',
   X_MATCHER_UNSUPPORTED: 'live query shape cannot be patched incrementally',
   X_QUERY_CACHE_TTL_INVALID: 'a query declares a cache ttlMs no tier can hold',
+  X_QUERY_COLUMN_UNSELECTED: 'a read filters or sorts on a column its rows do not carry',
   X_QUERY_DEPRECATION_INVALID: 'a query declares a deprecation whose dates cannot be rendered',
   X_QUERY_DUPLICATE: 'two queries are registered under one name',
   X_QUERY_FOREIGN: 'a value that is not a query was projected as one',
@@ -240,6 +241,23 @@ export class CursorValueUnsupportedError extends UltimateError {
   }
 }
 
+/**
+ * A `where()`, `compare()` or `orderBy()` on a column the provider's rows do not carry. Absent is
+ * not "not equal": every row failed the filter and the read answered `[]` — a loader that selected
+ * `slug` and `updatedAt` and filtered on `status` built a blog with no article in it, under a
+ * green gate. Refused by name, because the repair is one edit to the loader's `select`.
+ */
+export class QueryColumnUnselectedError extends UltimateError {
+  constructor(entity: string, column: string) {
+    super({
+      code: 'X_QUERY_COLUMN_UNSELECTED',
+      cause: `the rows of "${entity}" carry no "${column}" column, so filtering or sorting on it matches nothing`,
+      fix: 'select it in the loader: db.posts.select({ slug: true, status: true, publishedAt: true }) — or drop the filter the loader already applied',
+      meta: { entity, column },
+    });
+  }
+}
+
 /** The honest fallback: the matcher refuses to guess rather than patch wrongly. */
 export class MatcherUnsupportedError extends UltimateError {
   constructor(name: string, feature: string) {

package/src/http.ts

@@ -6,12 +6,11 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { isUltimateError } from '@ultimat3/core';
 import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
-import { problem, toBucket } from '@ultimat3/http';
+import { toBucket } from '@ultimat3/http';
 import { coerceQuery } from '@ultimat3/schema';
 import type { Deprecation } from './deprecation';
-import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
+import { recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { QueryDeprecationInvalidError } from './errors';
 import { derivePath } from './naming';
 import { pageControlsOf } from './page-controls';
@@ -34,43 +33,43 @@ export function toQueryRoute(target: AnyQuery): Route {
   const answer = recordAnswerFor(target.rows);
 
   const handler = async (request: UltimateRequest): Promise<Response> => {
-    if (sunsetting !== undefined) recordDeprecatedCall('query', name);
-    try {
-      // Coerced, then validated — two different jobs, and only the first one belongs to a
-      // wire. A search string is characters, so `t.number` and `t.boolean` need the HTTP
-      // boundary's decode (`coerceQuery` never invents data: what it cannot convert it
-      // hands on untouched). VALIDATING here — `request.query(schema)` — would be the
-      // second parser: the same read would answer `X_BODY_INVALID` where every other
-      // surface answers `X_INPUT_INVALID` with the line that prints its schema. `runQuery`
-      // is the one that decides, exactly as it does for a direct server call.
-      //
-      // The two page controls come OUT first (`page-controls.ts`): they are the route's, not the
-      // read's, and a schema that refused unknown keys would otherwise refuse every paged call.
-      const { input: values, page } = pageControlsOf(name, request.queryRaw());
-      const input = coerceQuery(target.input, values);
-      // With a page control the answer is the `Page` envelope `query.page()` answers a server
-      // caller with — `{ rows, endCursor, hasNextPage }`, the same names, so a cursor read off the
-      // wire and one read off a direct call are the same string in the same field. Without one the
-      // answer is the bare array it has always been: every client written before the controls
-      // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker
-      // has no business being.
-      const response = answer(
-        page === undefined
-          ? await runQuery(target, input, { surface: 'http' })
-          : await target.page(input, { ...page, surface: 'http' }),
-      );
-      // On the failure path too, below: a client polling a deprecated read that is currently
-      // 403ing still has to learn the read is going away.
-      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
-      return response;
-    } catch (error) {
-      // Framework errors carry their own code, status and fix line; anything else is
-      // a bug and belongs to the server's error boundary, not to this route.
-      if (!isUltimateError(error)) throw error;
-      const response = problem(error);
-      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
-      return response;
+    if (sunsetting !== undefined) {
+      recordDeprecatedCall('query', name);
+      // On the CONTEXT, before anything can fail: the pipeline's `response` stage merges
+      // `ctx.headers` into whatever answers — this handler's rows and the `error-map` stage's
+      // problem or error page alike. A client polling a deprecated read that is currently 403ing
+      // still has to learn the read is going away.
+      for (const [header, value] of Object.entries(sunsetting))
+        request.ctx.headers.set(header, value);
     }
+    // No `catch`: an error — framework or not — takes the path every route's error takes, the
+    // repair `@ultimat3/action`'s `toRoute` got. This answered `problem(error)` itself, so the
+    // `error-map` stage never saw it: no `onError`/`reportError` on a 5xx, no HTML error page or
+    // sign-in redirect for a browser, no `requestId`, no `Retry-After`.
+    //
+    // Coerced, then validated — two different jobs, and only the first one belongs to a
+    // wire. A search string is characters, so `t.number` and `t.boolean` need the HTTP
+    // boundary's decode (`coerceQuery` never invents data: what it cannot convert it
+    // hands on untouched). VALIDATING here — `request.query(schema)` — would be the
+    // second parser: the same read would answer `X_BODY_INVALID` where every other
+    // surface answers `X_INPUT_INVALID` with the line that prints its schema. `runQuery`
+    // is the one that decides, exactly as it does for a direct server call.
+    //
+    // The two page controls come OUT first (`page-controls.ts`): they are the route's, not the
+    // read's, and a schema that refused unknown keys would otherwise refuse every paged call.
+    const { input: values, page } = pageControlsOf(name, request.queryRaw());
+    const input = coerceQuery(target.input, values);
+    // With a page control the answer is the `Page` envelope `query.page()` answers a server
+    // caller with — `{ rows, endCursor, hasNextPage }`, the same names, so a cursor read off the
+    // wire and one read off a direct call are the same string in the same field. Without one the
+    // answer is the bare array it has always been: every client written before the controls
+    // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker
+    // has no business being.
+    return answer(
+      page === undefined
+        ? await runQuery(target, input, { surface: 'http' })
+        : await target.page(input, { ...page, surface: 'http' }),
+    );
   };
 
   const meta: RouteMeta = {

package/src/index.ts

@@ -70,6 +70,7 @@ export {
   CursorInvalidError,
   CursorValueUnsupportedError,
   MatcherUnsupportedError,
+  QueryColumnUnselectedError,
   QueryDeniedError,
   QueryDeprecationInvalidError,
   QueryDuplicateError,
@@ -85,7 +86,7 @@ export {
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
 export { toQueryRoute } from './http';
 export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } from './live';
-export { advanceCursor, liveEpoch, planResume, seekOf, toLiveQuery } from './live';
+export { planResume, seekOf, toLiveQuery } from './live';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
 export type { QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
@@ -94,7 +95,7 @@ export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
  * Path derivation only. There is no `toToolName`: an MCP tool is served under the export name
  * verbatim, and an exported derivation would be a second way to spell one tool.
  */
-export { derivePath, toKebabCase } from './naming';
+export { derivePath } from './naming';
 /**
  * The read half of `openapi.json`. `@ultimat3/cli` merges these paths into `@ultimat3/action`'s
  * `buildOpenApi` document — the two packages are one tier and cannot compose each other.
@@ -105,7 +106,7 @@ export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
  * shape the typed client's `.page()` takes. `MAX_PAGE_SIZE` is the bound both ends check.
  */
 export type { PageControls } from './page-controls';
-export { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
+export { MAX_PAGE_SIZE } from './page-controls';
 /**
  * The shapes `query.page(input, { first, after })` takes and answers with. `paginate` itself is
  * deliberately unexported: a page is the read's own answer, and a second, importable way to ask
@@ -139,7 +140,7 @@ export type {
   QueryRateLimit,
   SourceOptions,
 } from './query';
-export { describeQuery, isQuery, nameQuery, query, queryHash } from './query';
+export { describeQuery, isQuery, query, queryHash } from './query';
 /** The one read path. `defOf` stays unexported — that is the enforcement. */
 export { queryName, runQuery, sourceFor } from './read';
 
@@ -164,7 +165,6 @@ export {
   compareValues,
   isNull,
   matchesFilter,
-  matchesFilters,
   seekKeyOf,
   totalOrder,
 } from './shape';

package/src/pagination.ts

@@ -50,13 +50,13 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   // The scope is this read plus these arguments: a cursor from anywhere else is
   // already `X_CURSOR_INVALID` by the time it gets here.
   const decoded = args.after === undefined ? null : decodeCursor(args.after, hash);
+  const base = await sourceFor(target, input, args);
+  const shape = base.shape();
   // Revived to the types the columns hold, never left as the strings JSON handed back: a `Date`
   // key decoded as an ISO string reaches `compareValues` as text and is compared against the
   // row's own millisecond number, so page two matched nothing at all. See `cursor-value.ts`.
   const after: SeekKey | null =
-    decoded === null ? null : { key: reviveSortKey(decoded.key), id: decoded.id };
-  const base = await sourceFor(target, input, args);
-  const shape = base.shape();
+    decoded === null ? null : seekFromCursor(decoded, shape.orderBy.length);
 
   // `MAX_PAGE_SIZE` lives in `page-controls.ts`: the route checks the same bound at the wire, as
   // a 400, before this `assert` — which is a 500 — can see the number.
@@ -75,7 +75,13 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
     endCursor:
       seek === null
         ? null
-        : encodeCursor({ scope: hash, key: seek.key.map(serializeSortValue), id: seek.id }),
+        : encodeCursor({
+            scope: hash,
+            // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
+            // numeric or bigint tiebreak compares as a number on the next page, not lexically.
+            key: [...seek.key, seek.id].map(serializeSortValue),
+            id: String(seek.id),
+          }),
     hasNextPage: scoped.length > args.first,
   };
 }
@@ -109,3 +115,16 @@ function inTotalOrder(
   if (after === null) return ordered;
   return ordered.filter((row) => isAfterKey(row, after, shape.orderBy));
 }
+
+/**
+ * The seek a decoded cursor names. A cursor carrying one more key than the ordering has its typed
+ * id at the tail; an older cursor, minted before the id rode there, falls back to the string slot.
+ */
+function seekFromCursor(
+  decoded: { readonly key: readonly unknown[]; readonly id: string },
+  width: number,
+): SeekKey {
+  const key = reviveSortKey(decoded.key);
+  if (key.length !== width + 1) return { key, id: decoded.id };
+  return { key: key.slice(0, width), id: key[width] };
+}

package/src/shape.ts

@@ -31,10 +31,14 @@ export interface QueryShape {
   readonly unsupported: readonly string[];
 }
 
-/** Where a page resumes: the sort-key values of the last row plus its id tiebreak. */
+/**
+ * Where a page resumes: the sort-key values of the last row plus its id tiebreak. `id` keeps the
+ * row's own TYPE: a stringified numeric id compared lexically against the next page's rows, so
+ * `"10" < "7"` and a row tied on the sort key after id 7 was never served.
+ */
 export interface SeekKey {
   readonly key: readonly unknown[];
-  readonly id: string;
+  readonly id: unknown;
 }
 
 /**
@@ -53,7 +57,7 @@ export function seekKeyOf(
   if (id === undefined || id === null) throw new QueryNotPageableError(shape.entity);
   return {
     key: shape.orderBy.map((order) => columnOf(row, order.column)),
-    id: typeof id === 'string' ? id : String(id),
+    id,
   };
 }
 
@@ -193,11 +197,18 @@ function normalize(value: unknown): unknown {
   return value instanceof Date ? value.getTime() : value;
 }
 
+/**
+ * Equality as Postgres answers it. A number and a bigint are ONE family — an `int8` arrives as a
+ * `bigint` from one driver while a filter value is usually a `number` literal, and `5n = 5` is
+ * true there — so the type check that keeps `'5'` from equalling `5` treats them as one.
+ */
 function same(a: unknown, b: unknown): boolean {
   if (isNull(a) || isNull(b)) return isNull(a) && isNull(b);
-  return compareValues(a, b) === 0 && typeof normalize(a) === typeof normalize(b);
+  return compareValues(a, b) === 0 && family(normalize(a)) === family(normalize(b));
 }
 
+const family = (value: unknown): string => (isNumeric(value) ? 'numeric' : typeof value);
+
 /** Row ordering under an `orderBy` list. Stable, and total when an id key is last. */
 export function compareRows(a: object, b: object, orderBy: readonly OrderKey[]): number {
   for (const key of orderBy) {

package/src/source.ts

@@ -4,6 +4,7 @@
  * app's `sql:` returns `from()` over an `@ultimat3/entity` repo, and a source only has to
  * answer these four questions.
  */
+import { QueryColumnUnselectedError } from './errors';
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
 import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
@@ -132,6 +133,7 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
 
   async execute(): Promise<readonly TRow[]> {
     const source = typeof this.rows === 'function' ? await this.rows() : this.rows;
+    this.assertCarried(source);
     let result = source.filter((row) => matchesFilters(row, this.filters));
     const keys = this.servedOrder();
     if (keys.length > 0) {
@@ -144,6 +146,19 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     return this.rowLimit === null ? result : result.slice(0, this.rowLimit);
   }
 
+  /**
+   * Every column a filter or the declared ordering reads must be ON the rows. Only the declared
+   * keys: the `id` tiebreak `servedOrder()` adds is `seek()`'s concern, refused there by name.
+   */
+  private assertCarried(rows: readonly TRow[]): void {
+    const read = new Set([...this.filters, ...this.order].map((entry) => entry.column));
+    for (const row of rows) {
+      for (const column of read) {
+        if (!(column in row)) throw new QueryColumnUnselectedError(this.entity, column);
+      }
+    }
+  }
+
   /** True when the ordering already names `id`, so the tiebreak is neither added nor doubled. */
   private get ordersById(): boolean {
     return this.order.some((key) => key.column === 'id');