@ultimat3/query 30.8.0 → 31.0.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 |---|---|
 | `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 |
+| `rows-override.ts`, `adapter.ts` | `@ultimat3/query/adapter`'s `overrideRows(query, rows \| fn \| undefined)`: canned rows where `sql()` is, answered in `buildSource` AFTER the parse and the policy, never cached (`rows-override.test.ts`). Never on the barrel — `@ultimat3/testing`'s `stub()` is its one caller |
 | `contract-test.ts` | `.contract()`, the generated suite. The three `X_CONTRACT_*` codes and `X_CONTRACT_DRIFT` are borrowed (`QUERY_BORROWED_ERROR_CODES`) |
 | `exercise.ts` | the exercise twin. "Reached" means `sql()` built a source, read off the refusal (`beforeSql`), because `read.ts` keeps no counter. No transaction: a read writes nothing |
 | `exercise-declarations.ts` | action's twin: `.contract({ exercise })` takes the app's `defineExercise()` value and reads the entry by the query's name (`apps/web/exercise.ts`, the one home) |
@@ -37,6 +38,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `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` | `explainQuery()` / `describeSql()` |
+| `validate.ts` | the input parse — `X_INPUT_INVALID` with `issues` + `issuesTruncated` on `meta`, as action's twin |
 | `cache.ts` | the read path: the request memo, and the fill through `@ultimat3/cache`'s registered tiers |
 | `search.ts` | `search()` — the query FACTORY over an entity's `.searchable()` columns |
 | `source.ts` | `SqlSource` contract + `from()` in-memory reference |
@@ -91,7 +93,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **A `single: true` read answers the row or `X_NOT_FOUND` by ONE rule** (`single-answer.ts`:
   `oneRowOf`, `readAnswer`) — the route and `@ultimat3/mcp`'s served tool both call it.
 - **`rateLimit:` is spent ONCE, in `buildSource`** (`rate-limit-gate.ts`'s `spendReadLimit`), for
-  every enforced build — route, `page()`, the MCP tool (`surface: 'mcp'`, judged as `'server'`).
+  every enforced build — route, `page()`, the MCP tool (`surface: 'mcp'`, judged as `'mcp'`, as an MCP action is).
   `'server'` and an `unenforced` build spend nothing. A live subscribe spends via `live.ts`'s
   `spendQueryLimit`, called by realtime per subscriber. `toQueryRoute` sets `rateLimitedBy:
   'handler'` and no stage bucket. Counted in `@ultimat3/http`'s installed store; key
@@ -113,6 +115,9 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   re-export; `index.test.ts` pins the absence.
 - `registry.ts` announces `registerQueries` in core's registrar table at import; `defineApi` in
   `@ultimat3/action` depends on it (`X_REGISTRAR_MISSING` otherwise).
+- `registerQuery`/`registerQueries` are on `@ultimat3/query/loader` (`loader.ts`), never the barrel:
+  `defineApi` is an app's one path; `x`'s loader and framework fixtures import the subpath
+  (`loader.test.ts` pins both).
 - 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.
@@ -146,7 +151,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 
 - **`audit: true` observes the read path, never forks it**: `buildSource` fills the trace (`input`,
   parsed-or-nothing on a pre-parse denial); `readRowsIn` sets `replayed`. The record shape and the
-  sink are `@ultimat3/core`'s (`AuditRecord`, `setAuditSink`) — shared with `@ultimat3/action`, and
+  sink are `@ultimat3/core`'s (`AuditRecord`, `installAuditSink` on `./adapter`) — shared with `@ultimat3/action`, and
   `AUDIT_RECORD_FIELDS` is the parity pin both packages' tests assert (`audit.test.ts`).
 - **A memo or cache hit is recorded** (`replayed: true`): an audit of a read is who saw what.
 - **One record per CALL**: `runQuery` and `readCall` (`.page()`) record the whole call;
@@ -205,7 +210,9 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - The matcher patches from `QueryShape`, never from SQL text.
 - `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 — `@ultimat3/entity`'s, imported; this package never re-publishes it).
+  (10,000 — `@ultimat3/entity`'s, imported; this package never re-publishes it). **The wire's
+  bound is `MAX_WIRE_PAGE_SIZE` (500)**, raised per read by `maxPage` (`assertMaxPage` at
+  `query()`, `X_QUERY_MAX_PAGE_INVALID`); the route and `openapi.ts` both read `target.maxPage`.
 - **A declared `.limit()` bounds the LISTING, on every page**: the window is
   `min(rowsLeft, first + 1)`, and a limited read's cursor carries the rows served so far at the
   tail of its key (after the typed id). A cursor without it is `X_CURSOR_INVALID` on a limited
@@ -256,6 +263,8 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **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.
+  **`'actor'` carries the grant set** (sorted roles, scopes, permissions, `onBehalfOf`): one id is
+  not one grant set (`cache-authority.test.ts`).
 - **`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.
@@ -273,7 +282,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 ## Commands
 
 ```
-bun test packages/query
+bun test ./packages/query/
 bun run typecheck
 ```
 

package/README.md

@@ -18,8 +18,9 @@ export const liveFeed = query({
 const rows = await liveFeed({ orgId });        // typed rows, policy enforced
 ```
 
-Register once at boot: `registerQueries(await import('./live'))`. Export names become
-query names, which the manifest, the live protocol and `/_x` all address.
+Register once at boot: `defineApi({ queries: [liveQueries] })` in `apps/web/api/index.ts`. Export
+names become query names, which the manifest, the live protocol and `/_x` all address.
+`registerQuery`/`registerQueries` are `x`'s loader's (`@ultimat3/query/loader`), never the barrel's.
 
 ## One declaration, five projections
 
@@ -220,8 +221,11 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `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) |
+| `loader.ts` | `@ultimat3/query/loader` — `registerQuery`/`registerQueries`, for `x`'s loader and framework fixtures; never the barrel |
+| `adapter.ts` | `@ultimat3/query/adapter` — `overrideRows`, the test seam `@ultimat3/testing`'s `stub()` drives, and `QueryClient` / `QueryClientOptions`, the client's own shape |
 | `http.ts` | the route projection — `GET /_x/query/<kebab>`, the URL the client derives |
-| `page-controls.ts` | `_first` / `_after` — the two search-string keys that page the route, split out and judged at the wire against `@ultimat3/entity`'s `MAX_PAGE_SIZE` |
+| `page-controls.ts` | `_first` / `_after` — the two search-string keys that page the route, split out and judged at the wire against `MAX_WIRE_PAGE_SIZE` (500) or the read's `maxPage`; `assertMaxPage` |
+| `validate.ts` | the input parse: `X_INPUT_INVALID` carrying `issues` (by path) and `issuesTruncated` — action's `validate.ts` twin |
 | `openapi.ts` | the read half of `openapi.json` — one `GET` path item per registered query, publishing a declared `rows:` |
 | `openapi-errors.ts` | a read operation's `responses` with its declared `errors:` in them |
 | `declared-errors.ts` / `declared-errors-contract.ts` | `errors:` judged around `sql` and `execute`; `.contract()`'s scan of `sql`'s source |
@@ -420,7 +424,8 @@ GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (uncha
 |---|---|
 | the keys are `_first` and `_after`, not `first` and `after` | the search string is ALSO the input, and an input member named `first` was legal on every release before this one — a listing's page-size field is the natural name for it. Reserving the bare names would have refused every such declaration at `query()`, in a minor. The underscore is the framework's own mark, as `/_x/` is |
 | a declaration naming either is refused at `query()` | `X_QUERY_INPUT_UNENCODABLE`, in the declaring file: the route strips the key before the schema runs, so the field could never be filled |
-| `_first` outside 1–10,000, not a whole number, or `_after` without `_first` | **400** `X_INPUT_INVALID` with the read's own fix line — judged at the wire (`page-controls.ts`), because `paginate` asserts the same bound as `X_INVARIANT`, which is a 500 blaming the server for a number the caller typed |
+| `_first` outside 1–500 (`MAX_WIRE_PAGE_SIZE`), not a whole number, or `_after` without `_first` | **400** `X_INPUT_INVALID` with the read's own fix line — judged at the wire (`page-controls.ts`), because `paginate` asserts the same bound as `X_INVARIANT`, which is a 500 blaming the server for a number the caller typed |
+| `query({ maxPage: 2000 })` | raises THIS read's wire bound, up to `MAX_PAGE_SIZE` (10,000); `openapi.json`'s `maximum` follows it. `As of 31.0.0`: the wire took 10,000 for every read, and 10,000 rows × a per-address budget (the demo's 120/s) is a table dump per second from one caller. A server `read.page()` keeps `MAX_PAGE_SIZE`. Not a whole number from 1 to 10,000: `X_QUERY_MAX_PAGE_INVALID` at `query()` |
 | a cursor that is not this read's | **400** `X_CURSOR_INVALID` — `decodeCursor` is the one judge of a cursor; the route checks only that `_after` is one non-empty string |
 | a control sent twice | refused, never resolved to the last one as a declared scalar is: two page sizes is two pages asked for in one request |
 | a declared `.limit()` is the size of the LISTING | `first` is the size of a page and never widens it: the window is `min(what the limit has left, first + 1)`, a limited read's cursor carries how many rows are already served, and the last page inside it answers `hasMore: false` with `nextCursor: null`. `As of 2026-10`; until then `first` REPLACED the limit, so `?_first=10000` walked a "top 3" to the end of the table. A read paged past its limit on purpose drops the `.limit()` |
@@ -541,7 +546,7 @@ 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 |
+| `actor` (default) | the actor's kind, id, org and GRANT SET (roles, scopes, permissions, `onBehalfOf`, order-free) — one id under two grant sets is two entries, so a role revoked inside `ttlMs` is never served the wider grant's rows (`As of 31.0.0`) | 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 |
 
@@ -555,8 +560,8 @@ required positional argument of `cacheKeyFor`, because an optional one is one a
 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
+failed business read and is published as a `cache.tier_failure` event under the name of the tier
+that refused — `subscribe('cache.tier_failure', handler)`. 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
@@ -673,9 +678,9 @@ export const patientChart = query({
 
 Every **call** is one record in the installed `AuditSink` — allowed, denied (before or after the
 input parse) and failed. The sink, the record and the installed slot are `@ultimat3/core`'s, the
-same ones an action's `audit: true` writes to: `setAuditSink(sink)` from `@ultimat3/core` (or
-`@ultimat3/action` — the same function) installs one sink for both, and `record.primitive` tells a
-read from a write.
+same ones an action's `audit: true` writes to: `auditSink` in `apps/web/runtime.ts` (the boot
+installs it through core's `installAuditSink`, `@ultimat3/core/adapter`) is one sink for both, and
+`record.primitive` tells a read from a write.
 
 **A memo or cache hit is recorded too**, with `replayed: true`. An audit of a read is about who saw
 what, not what was computed: a reader handed rows by the request memo saw them exactly as much as
@@ -746,6 +751,7 @@ export const runRecording = query({
 | The route | `GET /_x/query/<kebab>` — the read's own. No `_token`: MINT (`application/json`). `_token`: SERVE (the bytes). `auth: 'public'`, `enforcedBy: 'handler'`, `cache: no-store` |
 | Policy | evaluated at MINT, exactly as for a rows read: actor half, the declared `rateLimit:`, the parse, the predicate. A refusal is the policy's own 401/403 |
 | The token | `seal()`ed (`@ultimat3/core`, AES-256-GCM under the app master key, purpose `ultimate.query.download:<name>`) claims: the query, `fingerprint()` of the PARSED input, the expiry on `ctx.now()`, the minting actor minus `facts`. The ACTOR is ciphertext — no id, role or grant readable; the query's path and its input are plain in the URL, as on any read |
+| Revocation | **the token IS the grant for its TTL** (`DEFAULT_DOWNLOAD_TTL_MS`, 5 min; `expiresInMs` up to 1 h): a logout, a revoked session or a lost role does not void a URL already minted — the serve checks no session. Keep `expiresInMs` as short as the player or tab needs |
 | The serve | the seal first (forged, truncated, another query's, a retired key → `X_QUERY_DOWNLOAD_TOKEN_INVALID`, 403), then the expiry (`X_QUERY_DOWNLOAD_TOKEN_EXPIRED`, 410), then the URL's input re-parsed against the bound fingerprint (edited → 403). `handle` runs as the MINTING actor; the policy is not re-run — it decided at mint, with `facts` the token cannot carry |
 | `handle`'s answer | `{ body: Uint8Array \| Blob \| ReadableStream, contentType, filename, disposition?: 'attachment' \| 'inline', size? }`, or `body: (range?) => BodyInit` (`DownloadBodyOpener`) with `size` required — bytes, never base64. Anything else is a 500 (`X_INVARIANT`) naming the fix |
 | Headers | `content-type`, `content-disposition` (`attachment` default; ASCII `filename` + exact `filename*=UTF-8''…`), `x-content-type-options: nosniff`, `content-security-policy: default-src 'none'; img-src 'self'; media-src 'self'; sandbox`, `referrer-policy: no-referrer`, `cache-control: no-store`; `content-length` only when the size is known — a `Uint8Array`, a `Blob`, or a stream with `size` |
@@ -763,7 +769,7 @@ or a stream with `size`, served without buffering.
 
 | Code | When | Fix |
 |---|---|---|
-| `X_QUERY_AUDIT_SINK_MISSING` | `audit: true` and no audit sink installed — refused before the parse | `setAuditSink(sink)` from `@ultimat3/core` at boot |
+| `X_QUERY_AUDIT_SINK_MISSING` | `audit: true` and no audit sink installed — refused before the parse | `auditSink: postgresAuditSink({ executor })` in `apps/web/runtime.ts` |
 | `X_QUERY_AUDIT_SINK_FAILED` | the sink refused the record of an allowed read; the rows were withheld | fix the sink, then retry the read |
 | `X_QUERY_DOWNLOAD_INVALID` | `download:` beside a rows option, a `handle` that is not a function, `expiresInMs` outside 1 000 … 3 600 000 | declare `download: { handle }` alone |
 | `X_QUERY_DOWNLOAD_ONLY` | rows asked of a download (`.live()`, `.page()`, `.as()`, `sourceFor`) | `await q.url(input)`, or `await q(input)` for the file |
@@ -775,10 +781,11 @@ or a stream with `size`, served without buffering.
 | `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 |
 | `X_QUERY_NOT_PAGEABLE` | a paged or live read returned a row with no `id` | select the primary key: `db.<rows>.select({ id: true, … })` |
-| `X_INPUT_INVALID` | input failed the Standard Schema; a page control the wire refuses; a `search()` handed a blank term, a cursor, or a window that would cut rows | `x queries show <name> --json` |
-| `X_QUERY_UNREGISTERED` | used before `registerQueries()` ran | register at boot |
+| `X_INPUT_INVALID` | input failed the Standard Schema (`meta.issues` by path, at most `MAX_ISSUES`, `meta.issuesTruncated` when cut); a page control the wire refuses; a `search()` handed a blank term, a cursor, or a window that would cut rows | `x queries show <name> --json` |
+| `X_QUERY_UNREGISTERED` | used before `defineApi()` named it | hand its module to `defineApi` at boot |
 | `X_NOT_FOUND` | a `single: true` read matched no row — the HTTP route's 404, and the MCP tool's refusal (entity's code) | `x queries show <name> --json` prints the SQL |
 | `X_QUERY_SINGLE_INVALID` | `single:` declared as something other than a boolean | `single: true`, or drop the key |
+| `X_QUERY_MAX_PAGE_INVALID` | `maxPage:` not a whole number of rows from 1 to 10,000 | `query({ maxPage: 2000 })`, or drop the key for the 500-row wire cap |
 | `X_QUERY_FOREIGN` | a look-alike was projected as a query | declare it with `query({ … })` |
 | `X_CLIENT_TRANSPORT_FAILED` | `.client()` got no response, or a non-`problem+json` failure (core's code, since 21.0.0; was `X_RPC_FAILED`) | check the gateway in front of the app: `x doctor --json` |
 
@@ -792,27 +799,19 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
-| `CursorValueUnsupportedError` | `X_CURSOR_VALUE_UNSUPPORTED` | `src/errors.ts` |
-| `MatcherUnsupportedError` | `X_MATCHER_UNSUPPORTED` | `src/errors.ts` |
-| `QueryAuditSinkFailedError` | `X_QUERY_AUDIT_SINK_FAILED` | `src/audit-errors.ts` |
-| `QueryAuditSinkMissingError` | `X_QUERY_AUDIT_SINK_MISSING` | `src/audit-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` |
-| `QueryDownloadInvalidError` | `X_QUERY_DOWNLOAD_INVALID` | `src/download-errors.ts` |
-| `QueryDownloadOnlyError` | `X_QUERY_DOWNLOAD_ONLY` | `src/download-errors.ts` |
-| `QueryDownloadTokenExpiredError` | `X_QUERY_DOWNLOAD_TOKEN_EXPIRED` | `src/download-errors.ts` |
-| `QueryDownloadTokenInvalidError` | `X_QUERY_DOWNLOAD_TOKEN_INVALID` | `src/download-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` |
 | `QueryRowNotFoundError` | `X_NOT_FOUND` | `src/errors.ts` |
 | `QuerySingleInvalidError` | `X_QUERY_SINGLE_INVALID` | `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` |
+
+## `@ultimat3/query/adapter` — canned rows for a test
+
+`overrideRows(target, rows | (({ input, ctx }) => rows) | undefined)` answers a read with canned
+rows where its `sql()` is. The actor half, the declared rate limit, the input parse and the policy
+still run first, so a stubbed read still refuses whoever its policy refuses; every surface (route,
+MCP, live, pages) gets the same rows, and none is cached, so nothing outlives `undefined`, which
+restores the declared read. Not on the `.` barrel: an app module cannot answer a read with rows its
+`sql()` did not produce. Reach it through `@ultimat3/testing`'s `stub()`.
 
 ## Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "30.8.0",
+  "version": "31.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "keywords": [
     "ultimate",
@@ -29,7 +29,9 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./client": "./src/client.ts"
+    "./adapter": "./src/adapter.ts",
+    "./client": "./src/client.ts",
+    "./loader": "./src/loader.ts"
   },
   "files": [
     "src",
@@ -47,12 +49,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "30.8.0",
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/db": "30.8.0",
-    "@ultimat3/entity": "30.8.0",
-    "@ultimat3/http": "30.8.0",
-    "@ultimat3/policy": "30.8.0",
-    "@ultimat3/schema": "30.8.0"
+    "@ultimat3/cache": "31.0.0",
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/db": "31.0.0",
+    "@ultimat3/entity": "31.0.0",
+    "@ultimat3/http": "31.0.0",
+    "@ultimat3/policy": "31.0.0",
+    "@ultimat3/schema": "31.0.0"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,7 @@
+// `@ultimat3/query/adapter` — what a test harness reaches beside the barrel: the rows-override seam
+// `@ultimat3/testing`'s `stub(query)` installs. Never the `.` barrel: an app module cannot answer a
+// read with rows its `sql()` did not produce.
+
+export type { QueryClient, QueryClientOptions } from './client';
+export { overrideRows } from './read';
+export type { RowsOverride } from './rows-override';

package/src/audit-errors.ts

@@ -18,7 +18,7 @@ export class QueryAuditSinkMissingError extends UltimateError {
       code: 'X_QUERY_AUDIT_SINK_MISSING',
       cause: `query "${query}" declares \`audit: true\` and no audit sink is installed`,
       // The registered fix, verbatim: code first, so the line can be pasted (`wiki/Error-Codes.md`).
-      fix: 'setAuditSink(sink)   # from @ultimat3/core, at boot before defineApi()',
+      fix: 'auditSink: postgresAuditSink({ executor })   # in export const runtime = { … }, apps/<app>/runtime.ts',
     });
   }
 }
@@ -35,7 +35,7 @@ export class QueryAuditSinkFailedError extends UltimateError {
       code: 'X_QUERY_AUDIT_SINK_FAILED',
       cause: `"${query}" was read and its audit sink refused the record, so the rows were withheld — a read commits nothing, so nothing is left to reconcile`,
       // The sink's own error is `sourceError`; a read commits nothing, so the retry is safe.
-      fix: 'setAuditSink(sink)   # install a sink that accepts the record, then retry the read',
+      fix: 'auditSink: postgresAuditSink({ executor })   # apps/<app>/runtime.ts — a sink that accepts the record; then retry the read',
       meta: { query },
       sourceError,
     });

package/src/audit-gate.ts

@@ -5,7 +5,13 @@
  */
 
 import type { AuditOutcome, AuditRecord, AuditSink, Ctx } from '@ultimat3/core';
-import { getAuditSink, isUltimateError, logger } from '@ultimat3/core';
+import {
+  AUDIT_SINK_FAILED_EVENT,
+  auditFailureOf,
+  auditOutcomeOf,
+  getAuditSink,
+  logger,
+} from '@ultimat3/core';
 import { QueryAuditSinkFailedError, QueryAuditSinkMissingError } from './audit-errors';
 import { QueryDeniedError } from './errors';
 import type { QuerySurface } from './policy-gate';
@@ -126,11 +132,7 @@ export function auditedSource<TRow>(source: SqlSource<TRow>, audit: ReadAudit):
  * this `catch` would replace the caller's error with its own.
  */
 export function readOutcomeFor(error: unknown): AuditOutcome {
-  try {
-    return error instanceof QueryDeniedError ? 'denied' : 'failed';
-  } catch {
-    return 'failed';
-  }
+  return auditOutcomeOf(error, (thrown) => thrown instanceof QueryDeniedError);
 }
 
 function recordOf(audit: ReadAudit, at: Date, outcome: AuditOutcome, error: unknown): AuditRecord {
@@ -148,8 +150,7 @@ function recordOf(audit: ReadAudit, at: Date, outcome: AuditOutcome, error: unkn
     idempotencyKey: null,
     replayed: audit.trace.replayed,
     outcome,
-    failure:
-      outcome === 'allowed' ? null : { code: isUltimateError(error) ? error.code : null, error },
+    failure: outcome === 'allowed' ? null : auditFailureOf(error),
   };
 }
 
@@ -168,7 +169,7 @@ async function recordThrew(sink: AuditSink, record: AuditRecord): Promise<void>
     // The same line `@ultimat3/action` writes, so `audit.sink.failed` is one alert rule over every
     // audited primitive. Never the record: rendering an input the sink just choked on is the
     // second throw this branch exists to prevent.
-    logger.error('audit.sink.failed', {
+    logger.error(AUDIT_SINK_FAILED_EVENT, {
       query: record.name,
       outcome: record.outcome,
       error,

package/src/cache.ts

@@ -94,8 +94,24 @@ export function readAuthority(actor: Actor, scope: QueryCacheScope): string {
   }
 }
 
+/**
+ * The actor AND its grant set. One id is not one grant set — a role revoked inside a `ttlMs`, or a
+ * shared dev identity holding two role sets — and `sql(input, ctx)` may read `ctx.actor.roles`, so
+ * keying on the id alone served the narrower grant the wider grant's rows. Sorted copies: a set,
+ * so two orderings of one grant are one entry.
+ */
 const actorAuthority = (actor: Actor): string =>
-  JSON.stringify([actor.kind, actor.id, actor.orgId ?? null]);
+  JSON.stringify([
+    actor.kind,
+    actor.id,
+    actor.orgId ?? null,
+    grantSet(actor.roles),
+    grantSet(actor.scopes),
+    grantSet(actor.permissions),
+    actor.onBehalfOf === undefined ? null : [actor.onBehalfOf.actorKind, actor.onBehalfOf.actorId],
+  ]);
+
+const grantSet = (values: readonly string[]): readonly string[] => [...new Set(values)].sort();
 
 /**
  * Deterministic: same query + same input + same tags + same authority => same key.

package/src/errors.ts

@@ -1,6 +1,7 @@
 /** Every failure @ultimat3/query can produce, one subclass per stable code. */
-import { assertNever, deniedCallerFix, registerErrorCodes, UltimateError } from '@ultimat3/core';
-import type { SurfaceDenial } from '@ultimat3/policy';
+import { deniedCallerFix, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import type { PrimitiveDenial, SurfaceDenial } from '@ultimat3/policy';
+import type { ValidationIssue } from '@ultimat3/schema';
 
 // No `docs:` on the classes below.
 // `UltimateError` fills it from `describeErrorCode(code).docs`, which is `@ultimat3/core`'s
@@ -38,6 +39,7 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_QUERY_HTTP_PATH_INVALID: "a query's pinned http.path is not a valid path template",
   X_QUERY_ETAG_INVALID: 'etag: true on a read that has its own validator',
   X_QUERY_TIMEOUT_INVALID: 'a read declares a timeoutMs that is not a whole positive number of ms',
+  X_QUERY_MAX_PAGE_INVALID: 'a query declares a maxPage no page bound can hold',
 };
 
 /**
@@ -63,34 +65,6 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(OWNED_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-function denialCode(denial: SurfaceDenial): string {
-  switch (denial.surface) {
-    case 'http':
-      return denial.problem.code;
-    case 'live':
-    case 'job':
-      return denial.code;
-    case 'mcp':
-      return denial.content[0]?.text.split(':')[0] ?? 'X_FORBIDDEN';
-    default:
-      return assertNever(denial);
-  }
-}
-
-function denialReason(denial: SurfaceDenial): string {
-  switch (denial.surface) {
-    case 'http':
-      return denial.problem.detail;
-    case 'live':
-    case 'job':
-      return denial.reason;
-    case 'mcp':
-      return denial.content[0]?.text ?? 'denied';
-    default:
-      return assertNever(denial);
-  }
-}
-
 /**
  * An authz denial from `guardQuery()`. The code and reason come from the policy
  * decision — this package never invents an authz code — and the surface-shaped
@@ -99,25 +73,28 @@ function denialReason(denial: SurfaceDenial): string {
 export class QueryDeniedError extends UltimateError {
   readonly denial: SurfaceDenial;
 
-  constructor(query: string, denial: SurfaceDenial) {
-    const code = denialCode(denial);
+  /**
+   * Built from `guardPrimitive`'s answer, which already read the code and the reason out of the
+   * surface shape — a type-only import, so the browser-reachable error module pulls in no policy.
+   */
+  constructor(refused: PrimitiveDenial<'query'>) {
     super({
-      code,
-      cause: `${query} denied: ${denialReason(denial)}`,
-      fix: `x policy explain ${query} --json   # shows which clause decided and why`,
+      code: refused.code,
+      cause: `${refused.name} denied: ${refused.reason}`,
+      fix: `x policy explain ${refused.name} --json   # shows which clause decided and why`,
       callerFix: deniedCallerFix(),
     });
-    this.denial = denial;
+    this.denial = refused.denial;
   }
 }
 
-/** Thrown when a read is used before `registerQueries()` gave it a name. */
+/** Thrown when a read is used before `defineApi()` gave it a name. */
 export class QueryUnregisteredError extends UltimateError {
   constructor() {
     super({
       code: 'X_QUERY_UNREGISTERED',
       cause: 'a query was used before it was registered, so it has no name',
-      fix: "call registerQueries(await import('./live')) at boot, before serving reads",
+      fix: "list the query's module in defineApi({ queries }) in apps/<app>/api/index.ts — the boot names it before serving reads",
     });
   }
 }
@@ -337,12 +314,29 @@ export class QuerySubscribesDriftError extends UltimateError {
 }
 
 export class QueryInputInvalidError extends UltimateError {
-  constructor(name: string, detail: string) {
+  /** The rejections, addressed by path — `undefined` for a refusal judged before the schema ran. */
+  readonly issues: readonly ValidationIssue[] | undefined;
+  /** `true` when validation stopped at `MAX_ISSUES`: `issues` is a prefix. Also on `meta`. */
+  readonly issuesTruncated: boolean;
+
+  /** `detail` is `formatIssues(issues).join('; ')` when both are passed (`validate.ts`). */
+  constructor(
+    name: string,
+    detail: string,
+    issues?: readonly ValidationIssue[],
+    issuesTruncated = false,
+  ) {
     super({
       code: 'X_INPUT_INVALID',
       cause: `input for query "${name}" failed validation: ${detail}`,
       fix: `x queries show ${name} --json  # prints the expected input schema`,
+      // Action's shape (`InputInvalidError`): http lifts `meta.issues` to the problem's `issues`.
+      ...(issues === undefined
+        ? {}
+        : { meta: issuesTruncated ? { issues, issuesTruncated: true } : { issues } }),
     });
+    this.issues = issues;
+    this.issuesTruncated = issuesTruncated;
   }
 }
 

package/src/exercise.ts

@@ -19,7 +19,8 @@ import {
   UltimateError,
 } from '@ultimat3/core';
 import type { ExerciseRequestOption } from '@ultimat3/http';
-import { statusFor, withRequestAs, withScratchRateLimitStore } from '@ultimat3/http';
+import { statusFor, withRequestAs } from '@ultimat3/http';
+import { withScratchRateLimitStore } from '@ultimat3/http/adapter';
 import { admitsAnonymous } from '@ultimat3/policy';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { validateAsync } from '@ultimat3/schema';

package/src/facade.ts

@@ -38,6 +38,7 @@ export function facadeFor<
     ...(def.subscribes === undefined ? {} : { subscribes: def.subscribes }),
     ...(def.rows === undefined ? {} : { rows: def.rows }),
     ...(def.cache === undefined ? {} : { cache: def.cache }),
+    ...(def.maxPage === undefined ? {} : { maxPage: def.maxPage }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),

package/src/http.ts

@@ -100,6 +100,7 @@ export function toQueryRoute(target: AnyQuery): Route {
             raw: search,
           }) as typeof search)
         : search,
+      target.maxPage,
     );
     const input = absentArraysOf(target.input, coerceQuery(target.input, values));
     if (target.single === true) {

package/src/index.ts

@@ -33,9 +33,8 @@ export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 /**
  * The two refusals `query({ audit: true })` adds. The record and the sink are `@ultimat3/core`'s
- * (`setAuditSink`) — one sink for every audited primitive, so this package re-exports neither.
+ * (`runtime.ts`'s `auditSink`) — one sink for every audited primitive, so this package re-exports neither.
  */
-export { QueryAuditSinkFailedError, QueryAuditSinkMissingError } from './audit-errors';
 export type { QueryCacheScope } from './cache';
 /** `readAuthority` is the ONLY producer of `cacheKeyFor`'s authority — never spell one by hand. */
 export {
@@ -50,16 +49,14 @@ export type {
   DownloadUrl,
   FetchLike,
   QueryCallOptions,
-  QueryClient,
   QueryClientMethod,
   QueryClientMethodOf,
-  QueryClientOptions,
   QueryLike,
   QueryMap,
   QuerySingleClientMethod,
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
-export { downloadClientFor, queryClient, queryClientMethodFor } from './client';
+export { queryClient, queryClientMethodFor } from './client';
 /**
  * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
  * `totalOrder` is the one definition of the order it must serve a page in. `compareRows`,
@@ -84,34 +81,11 @@ export type {
   QueryDownload,
 } from './download';
 export {
-  DEFAULT_DOWNLOAD_TTL_MS,
-  MAX_DOWNLOAD_TTL_MS,
-  MIN_DOWNLOAD_TTL_MS,
-} from './download';
-export type { DownloadTokenProblem } from './download-errors';
-export {
-  QueryDownloadInvalidError,
-  QueryDownloadOnlyError,
-  QueryDownloadTokenExpiredError,
-  QueryDownloadTokenInvalidError,
-} from './download-errors';
-export {
-  CursorValueUnsupportedError,
-  MatcherUnsupportedError,
   QueryColumnUnselectedError,
   QueryDeniedError,
-  QueryDeprecationInvalidError,
-  QueryDuplicateError,
-  QueryForeignError,
   QueryInputInvalidError,
-  QueryInputUnencodableError,
-  QueryNotPageableError,
-  QueryPolicyMissingError,
   QueryRowNotFoundError,
   QuerySingleInvalidError,
-  QuerySubscribesDriftError,
-  QuerySubscribesInvalidError,
-  QueryUnregisteredError,
 } from './errors';
 export type {
   QueryExerciseActorOptions,
@@ -141,10 +115,12 @@ export { assertMatchable, match, positionFor } from './matcher';
  */
 export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
 /**
- * The shape the typed client's `.page()` takes. The bound both ends check is `@ultimat3/entity`'s
- * `MAX_PAGE_SIZE` — imported from there, never re-published here.
+ * The shape the typed client's `.page()` takes. A server page is bounded by `@ultimat3/entity`'s
+ * `MAX_PAGE_SIZE` — imported from there, never re-published here; the route's `_first` by
+ * `MAX_WIRE_PAGE_SIZE`, or the read's declared `maxPage`.
  */
 export type { PageControls } from './page-controls';
+export { MAX_WIRE_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
@@ -166,7 +142,6 @@ export type {
   QueryCache,
   QueryDef,
   QueryDescriptor,
-  QueryFacade,
   QueryOptions,
   QueryRateLimit,
   SourceOptions,
@@ -174,12 +149,12 @@ export type {
 export { describeQuery, isQuery, query, queryHash } from './query';
 /** The one read path. `defOf` stays unexported — that is the enforcement. */
 export { queryName, runQuery, sourceFor } from './read';
+// `registerQuery`/`registerQueries` are deliberately absent: `defineApi({ queries })` is an app's
+// one registration path, and `x`'s loader reaches them through `@ultimat3/query/loader`.
 export {
   describeQueries,
   getQuery,
   listQueries,
-  registerQueries,
-  registerQuery,
   resetQueries,
 } from './registry';
 /** The query FACTORY over an entity's searchable columns — a `query`, never a ninth primitive. */

package/src/loader.ts

@@ -0,0 +1,5 @@
+// `@ultimat3/query/loader` — where an export is NAMED as a query: `x`'s module scan and the
+// framework's own fixtures. Never the `.` barrel: an app hands its modules to `defineApi`, the one
+// registration path (axiom 1), and that reaches these through core's registrar table.
+
+export { registerQueries, registerQuery } from './registry';

package/src/openapi.ts

@@ -23,7 +23,6 @@ import {
   templateParams,
   toOpenApiPath,
 } from '@ultimat3/core';
-import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { policyCapability } from '@ultimat3/policy';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, toWireOutputSchema, tryIntrospect } from '@ultimat3/schema';
@@ -31,7 +30,7 @@ import { DOWNLOAD_GRANT_PARAM } from './download-token';
 import { servedQueryPath } from './http-pin';
 import { withDeclaredErrors } from './openapi-errors';
 import { withValidatorDoc } from './openapi-etag';
-import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
+import { MAX_WIRE_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import type { AnyQuery } from './query';
 import { defOf, queryName } from './read';
 import { answersRecords } from './record-answer';
@@ -131,7 +130,7 @@ function rowsOperation(target: AnyQuery, name: string): Record<string, unknown>
     tags: [QUERY_TAG],
     summary: target.mcp?.description ?? name,
     ...(target.deprecated === undefined ? {} : { deprecated: true }),
-    parameters: [...inputParameters(target), ...PAGE_PARAMETERS],
+    parameters: [...inputParameters(target), ...pageParameters(target.maxPage)],
     responses: withDeclaredErrors(target, PROBLEM_SCHEMA_REF, {
       '200': {
         description: 'ok',
@@ -264,14 +263,19 @@ const MINTED_URL: Readonly<Record<string, unknown>> = {
   },
 };
 
-/** The two controls, spelled from `page-controls.ts` so the document cannot drift from the route. */
-const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
+/**
+ * The two controls, spelled from `page-controls.ts` so the document cannot drift from the route —
+ * the bound included: the read's declared `maxPage`, else the wire's `MAX_WIRE_PAGE_SIZE`.
+ */
+const pageParameters = (
+  maxPage: number = MAX_WIRE_PAGE_SIZE,
+): readonly Record<string, unknown>[] => [
   {
     name: PAGE_FIRST_KEY,
     in: 'query',
     required: false,
-    description: `page size; present, the response is the page envelope rather than the bare rows (1 to ${MAX_PAGE_SIZE})`,
-    schema: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE },
+    description: `page size; present, the response is the page envelope rather than the bare rows (1 to ${maxPage})`,
+    schema: { type: 'integer', minimum: 1, maximum: maxPage },
   },
   {
     name: PAGE_AFTER_KEY,

package/src/page-controls.ts

@@ -11,6 +11,7 @@
 // the framework's own namespace mark — the route lives under `/_x/` for the same reason — and
 // `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
 
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
 import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { QueryInputInvalidError } from './errors';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
@@ -20,8 +21,35 @@ export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_
 
 // The largest page a read will serve is `@ultimat3/entity`'s `MAX_PAGE_SIZE`, imported — a batch
 // and a page are one memory bound, and this package already depends on entity. `first` reaches
-// `paginate` straight from a route parameter, so the route judges it against that bound BEFORE
-// `paginate` runs (`pageControlsOf`), and one request can never ask for five million rows.
+// `paginate` straight from a route parameter, so the route judges it BEFORE `paginate` runs
+// (`pageControlsOf`), and one request can never ask for five million rows.
+//
+// The WIRE's bound is tighter: `MAX_WIRE_PAGE_SIZE`. 10,000 rows per request times a per-address
+// budget (the demo's: 120/s) is a table dump a second from one caller, so a remote page stops at
+// 500 unless the read declares `maxPage` — a written statement, in the file that owns the rows.
+// A server call (`read.page()`) keeps `MAX_PAGE_SIZE`: the caller is the app's own code.
+
+/** The largest `_first` the route serves for a read that declares no `maxPage`. */
+export const MAX_WIRE_PAGE_SIZE = 500;
+
+export class QueryMaxPageInvalidError extends UltimateError {
+  constructor(value: unknown) {
+    super({
+      code: 'X_QUERY_MAX_PAGE_INVALID',
+      cause: `query({ maxPage: ${renderCauseValue(value)} }) — not a whole number of rows from 1 to ${MAX_PAGE_SIZE}`,
+      fix: `query({ maxPage: 2000 })  # a whole number from 1 to ${MAX_PAGE_SIZE} — or drop maxPage for the ${MAX_WIRE_PAGE_SIZE}-row wire cap`,
+    });
+  }
+}
+
+/** Judged at `query()`, where the file that wrote it fails — never on every read forever. */
+export function assertMaxPage(value: unknown): void {
+  if (value === undefined) return;
+  if (typeof value === 'number' && Number.isInteger(value) && value >= 1) {
+    if (value <= MAX_PAGE_SIZE) return;
+  }
+  throw new QueryMaxPageInvalidError(value);
+}
 
 /** What the route hands `query.page()` — `PaginateArgs` minus the server-side options. */
 export interface PageControls {
@@ -55,7 +83,11 @@ const WHOLE_NUMBER = /^\d+$/;
  * 400 — and a second reader of the codec's envelope would be a second opinion about what a cursor
  * is. Only its shape as a search value is checked: one string, non-empty.
  */
-export function pageControlsOf(name: string, values: SearchValues): SplitSearch {
+export function pageControlsOf(
+  name: string,
+  values: SearchValues,
+  maxPage: number = MAX_WIRE_PAGE_SIZE,
+): SplitSearch {
   // `Object.create(null)`, never `{}`, and the same rule `@ultimat3/http`'s `collectFields`
   // follows: a repeated `?__proto__=a&__proto__=b` arrives as an ARRAY, which is exactly what
   // `Object.prototype.__proto__`'s setter accepts — one assignment and this object's prototype IS
@@ -75,10 +107,10 @@ export function pageControlsOf(name: string, values: SearchValues): SplitSearch
     );
   }
   const size = single(name, PAGE_FIRST_KEY, first);
-  if (!WHOLE_NUMBER.test(size) || Number(size) < 1 || Number(size) > MAX_PAGE_SIZE) {
+  if (!WHOLE_NUMBER.test(size) || Number(size) < 1 || Number(size) > maxPage) {
     throw new QueryInputInvalidError(
       name,
-      `${PAGE_FIRST_KEY} must be a whole number of rows between 1 and ${MAX_PAGE_SIZE}, got "${size}"`,
+      `${PAGE_FIRST_KEY} must be a whole number of rows between 1 and ${maxPage}, got "${size}"`,
     );
   }
   if (after === undefined) return { input, page: { first: Number(size) } };

package/src/policy-gate.ts

@@ -1,33 +1,27 @@
 /**
- * The single point of contact with @ultimat3/policy. A live query evaluates its
- * policy **per subscriber**, never once at subscribe time for everyone — so this
- * gate is called on every fanout decision and its result is never cached.
+ * The single point of contact with @ultimat3/policy, through `guardPrimitive` — the one gate
+ * `@ultimat3/action` runs too. A live query evaluates its policy **per subscriber**: this gate is
+ * called on every fanout decision and its result is never cached.
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assertNever } from '@ultimat3/core';
-import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce, enforceBeforeInput } from '@ultimat3/policy';
+import type { GuardSubject, Policy, PrimitiveSurface } from '@ultimat3/policy';
+import { guardPrimitive } from '@ultimat3/policy';
 import { QueryDeniedError } from './errors';
 
 /** Policies are opaque here: we evaluate them, we never introspect their rules. */
 export type QueryPolicy = Policy<unknown>;
 
 /**
- * Where a read came from. `'mcp'` is an agent's tool call — named so a declared `rateLimit:`
- * spends for it (`'server'`, in-process app code, does not) — and is judged by the policy exactly
- * as `'server'` always judged it, so no MCP read's authz answer moved.
+ * Where a read came from. `'mcp'` is an agent's tool call: it spends a declared `rateLimit:` and,
+ * since v31, is judged on policy's `mcp` surface exactly as an MCP action is.
  */
-export type QuerySurface = 'server' | 'http' | 'live' | 'mcp';
+export type QuerySurface = PrimitiveSurface<'query'>;
 
 export interface QuerySubject {
   readonly actor: Actor | null;
   readonly input: unknown;
-  /**
-   * The already-loaded row a row-level rule decides about — the live row gate supplies it
-   * per subscriber per row. Omitted for a subscribe-time or whole-query decision. It is a
-   * field of its own and never folded into `input`: the predicate reads `args.row`.
-   */
+  /** The loaded row a row-level rule decides about — never folded into `input`. */
   readonly row?: unknown;
   readonly ctx: Ctx;
   readonly query: string;
@@ -38,43 +32,24 @@ export function guardQuery(
   subject: QuerySubject,
   surface: QuerySurface,
 ): void {
-  const denial = enforce(policySurface(surface), policy, {
-    input: subject.input,
-    actor: subject.actor,
-    row: subject.row,
-    ctx: subject.ctx,
-  });
-  if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
+  const { query: name, ...rest } = subject;
+  guard(policy, { stage: 'input', name, ...rest }, surface);
 }
 
-/**
- * The actor-only half of `guardQuery`, run BEFORE the input is parsed — the twin of
- * `@ultimat3/action`'s. A reader the policy refuses whatever they send is answered 403 (or 401),
- * never `X_INPUT_INVALID` with the read's input schema in it. Undecided passes to `guardQuery`.
- */
+/** The actor-only half, BEFORE the input parse: refused is 403/401, never `X_INPUT_INVALID`. */
 export function guardQueryBeforeInput(
   policy: QueryPolicy,
   subject: Omit<QuerySubject, 'input' | 'row'>,
   surface: QuerySurface,
 ): void {
-  const denial = enforceBeforeInput(policySurface(surface), policy, {
-    actor: subject.actor,
-    ctx: subject.ctx,
-  });
-  if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
+  guard(
+    policy,
+    { stage: 'actor', name: subject.query, actor: subject.actor, ctx: subject.ctx },
+    surface,
+  );
 }
 
-/** A direct server read is the job surface: no request, no socket to close. */
-function policySurface(surface: QuerySurface): PolicySurface {
-  switch (surface) {
-    case 'http':
-      return 'http';
-    case 'live':
-      return 'live';
-    case 'server':
-    case 'mcp':
-      return 'job';
-    default:
-      return assertNever(surface);
-  }
+function guard(policy: QueryPolicy, subject: GuardSubject, surface: QuerySurface): void {
+  const refused = guardPrimitive('query', policy, subject, surface);
+  if (refused !== undefined) throw new QueryDeniedError(refused);
 }

package/src/query.ts

@@ -23,6 +23,7 @@ import { facadeFor } from './facade';
 import { assertQueryHttp, type QueryHttp } from './http-pin';
 import { assertEncodableInput } from './input-shape';
 import type { LiveQuery, ToLiveOptions } from './live';
+import { assertMaxPage } from './page-controls';
 import type { Page, PaginateArgs } from './pagination';
 import type { QueryPolicy, QuerySurface } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
@@ -111,6 +112,12 @@ export interface QueryDef<
   readonly rows?: StandardSchemaV1<unknown, TRow>;
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
+  /**
+   * The largest `_first` the route serves this read, raising the wire's `MAX_WIRE_PAGE_SIZE` (500)
+   * up to `MAX_PAGE_SIZE` (10,000). A server `read.page()` is bounded by `MAX_PAGE_SIZE` either
+   * way. Not a whole number in that range: `X_QUERY_MAX_PAGE_INVALID` at `query()`.
+   */
+  readonly maxPage?: number;
   /**
    * Answer `GET` with an `ETag` and `private, no-cache`, and a matching `If-None-Match` with a
    * bodiless 304 — after the policy and the rate limit, since a 304 is still a read of the caller's
@@ -243,6 +250,7 @@ export interface AnyQueryDef {
   readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
+  readonly maxPage?: number;
   readonly etag?: true;
   readonly timeoutMs?: number;
   readonly mcp?: McpExposureDeclaration;
@@ -269,6 +277,8 @@ export interface AnyQuery {
   /** Lifted for the route: whether an answer is a record envelope is decided at projection. */
   readonly rows?: StandardSchemaV1;
   readonly cache?: QueryCache;
+  /** Declared `maxPage` — the route's `_first` bound. Absent is `MAX_WIRE_PAGE_SIZE`. */
+  readonly maxPage?: number;
   readonly mcp?: McpExposureDeclaration;
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
   readonly rateLimit?: QueryRateLimit;
@@ -326,6 +336,7 @@ export type QueryFacade<
   | 'subscribes'
   | 'rows'
   | 'cache'
+  | 'maxPage'
   | 'mcp'
   | 'rateLimit'
   | 'deprecated'
@@ -368,6 +379,7 @@ export function query<
   }
   assertFreshness(def);
   assertSubscribes(def.subscribes, def.live);
+  assertMaxPage(def.maxPage);
   // A JS caller or generated code can write `single: 'yes'`; truthiness would read it as `true`
   // on the route and `false` in the type, so anything but a boolean is refused where it is written.
   if (def.single !== undefined && typeof def.single !== 'boolean') {

package/src/rate-limit-gate.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Actor } from '@ultimat3/core';
-import { isAnonymous, systemClock } from '@ultimat3/core';
+import { liveClock, rateLimitScopeOf, rateLimitSpendsOn, rateLimitSubjectOf } from '@ultimat3/core';
 import type { RateLimitDecision } from '@ultimat3/http';
 // The bucket maths, the subject precedence and the refusal are `@ultimat3/http`'s (tier 2): a copy
 // here would be a second answer to "what does this limit mean" and "whose bucket is it".
@@ -13,12 +13,6 @@ import { installedRateLimitStore, rateLimited, rateLimitSpends, toBucket } from
 import type { QuerySurface } from './policy-gate';
 import type { QueryRateLimit } from './query';
 
-/**
- * Namespaced, never the bare query name: the HTTP stage still spends its own buckets under
- * `<route name>|<subject>`, and one key taken against two bucket shapes corrupts both counters.
- */
-const QUERY_SCOPE = 'query';
-
 export interface QueryLimitCaller {
   /** Who is reading — `ctx.actor` on a read, the socket's actor on a live subscribe. */
   readonly actor: Actor;
@@ -45,19 +39,18 @@ export async function spendReadLimit(
   limit: QueryRateLimit | undefined,
   caller: QueryLimitCaller,
 ): Promise<void> {
-  if (limit === undefined || caller.surface === 'server') return;
-  const actor = isAnonymous(caller.actor) ? null : caller.actor;
+  if (limit === undefined || !rateLimitSpendsOn(caller.surface)) return;
   const spends = rateLimitSpends(
     {
-      actorId: actor?.id ?? null,
-      orgId: actor?.orgId ?? null,
-      ip: caller.clientAddress ?? null,
-      routeName: `${QUERY_SCOPE}:${name}`,
+      // Core's one subject rule, `@ultimat3/action`'s too: an anonymous actor's org is still read.
+      ...rateLimitSubjectOf(caller.actor, caller.clientAddress ?? null),
+      // Namespaced, never the bare name: the HTTP stage spends `<route name>|<subject>`.
+      routeName: rateLimitScopeOf('query', name),
     },
     // The tenant allowance is the HTTP pipeline's; counting it here too would charge twice.
     { route: name, tenant: null },
   );
-  const nowMs = caller.nowMs ?? systemClock.now().getTime();
+  const nowMs = caller.nowMs ?? liveClock.now().getTime();
   for (const spend of spends) {
     const decision = await installedRateLimitStore().take(
       spend.key,

package/src/read.ts

@@ -14,10 +14,12 @@ import {
   ctxOf,
   failureCaptureActive,
   finiteOption,
+  instrument,
   logger,
   REDACTED,
   recordFailureInput,
   runWithContext,
+  subscribed,
   tryUseContext,
   useContext,
   withChildContext,
@@ -27,7 +29,7 @@ import {
 import { withStatementTimeout } from '@ultimat3/db';
 import { statusFor } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { formatPath, maskSensitive, validateAsync } from '@ultimat3/schema';
+import { maskSensitive } from '@ultimat3/schema';
 import type { ReadAudit, ReadTrace } from './audit-gate';
 import { audited, auditedBuild, readAuditFor } from './audit-gate';
 import {
@@ -39,11 +41,15 @@ import {
   readThrough,
 } from './cache';
 import { judgedRead, judgedSql } from './declared-errors';
-import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
+import { QueryForeignError, QueryUnregisteredError } from './errors';
 import { guardQuery, guardQueryBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
 import { spendReadLimit } from './rate-limit-gate';
+import type { RowsOverride } from './rows-override';
+import { rowsOverrideOf, setRowsOverride } from './rows-override';
 import type { SqlSource } from './source';
+import { from } from './source';
+import { parsedOrNothing, parseQueryInput } from './validate';
 
 /**
  * Private on purpose. `@ultimat3/query` exports no way to read this back, which is
@@ -69,6 +75,15 @@ export function defOf(target: AnyQuery): AnyQueryDef {
   return def;
 }
 
+/**
+ * Canned rows where `target`'s `sql()` is, on every read surface — the actor half, the declared
+ * limit, the parse and the policy still run first. `undefined` restores. On
+ * `@ultimat3/query/adapter` only: `@ultimat3/testing`'s `stub()` is its caller.
+ */
+export function overrideRows(target: AnyQuery, rows: RowsOverride | undefined): void {
+  setRowsOverride(defOf(target), rows);
+}
+
 /** Projections need a stable name; an unregistered query has none yet. */
 export function queryName(target: AnyQuery): string {
   if (target.name.length === 0) throw new QueryUnregisteredError();
@@ -209,7 +224,20 @@ function readRows(
       // read is filled — and which of the two a slow read took is the first thing to ask.
       'ultimate.cached': defOf(target).cache !== undefined,
     });
-    const rows = await readRowsIn(target, raw, ctx, options, trace);
+    const startedAt = performance.now();
+    let rows: readonly object[];
+    try {
+      rows = await readRowsIn(target, raw, ctx, options, trace);
+    } catch (error) {
+      // A refused or failed read is still a read; the bus hears it sampled or not.
+      if (subscribed('query.read')) {
+        instrument('query.read', { query: name, durationMs: performance.now() - startedAt, error });
+      }
+      throw error;
+    }
+    if (subscribed('query.read')) {
+      instrument('query.read', { query: name, durationMs: performance.now() - startedAt });
+    }
     span.setAttribute('ultimate.rows', rows.length);
     return rows;
   });
@@ -252,6 +280,9 @@ async function readRowsIn(
   // a cache whose lifetime is the request. It still *publishes* into the memo: this read is the
   // newest answer the request has, so the next plain read of the key joins it rather than the
   // entry a write earlier in the request already moved past.
+  // Canned rows are never stored — not in the tier, not in the request memo (a `fresh` read
+  // publishes into it): an entry filled from a stub would outlive its undo.
+  if (rowsOverrideOf(def) !== undefined) return await read();
   if (options.fresh === true) return await readFresh(ctx, key, read);
   // `cache:` buys the tier, never the memo: a read asked twice in one request is one execution
   // whether or not its author opted into caching.
@@ -305,6 +336,13 @@ async function buildSource(
   trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
   const input = await admit(target, raw, ctx, options, trace);
+  const canned = rowsOverrideOf(defOf(target));
+  if (canned !== undefined) {
+    const rows = canned;
+    return from(queryName(target), () =>
+      typeof rows === 'function' ? rows({ input, ctx }) : rows,
+    );
+  }
   // `sql` and the source's `execute` are where `errors:` judges a throw (`declared-errors.ts`).
   const source = judgedSql(target, queryName(target), () => defOf(target).sql(input, ctx));
   // A live window is served in the order its patches are placed in. The matcher breaks a tie on
@@ -378,7 +416,7 @@ async function admit(
       nowMs: ctx.now().getTime(),
     });
   }
-  const input = await validate(def.input, raw, name);
+  const input = await parseQueryInput(def.input, raw, name);
   if (failureCaptureActive()) recordFailureInput(maskSensitive(def.input, input, REDACTED));
   // The audit record's copy, masked by THIS read's own schema — never a key table (`action`'s rule).
   if (trace !== null) trace.input = maskSensitive(def.input, input, REDACTED);
@@ -404,23 +442,3 @@ async function admit(
   }
   return input;
 }
-
-/** The parse without the refusal — only for the record of a read already refused on other grounds. */
-async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
-  const result = await validateAsync(schema, raw);
-  return result.issues === undefined ? result.value : undefined;
-}
-
-async function validate(schema: StandardSchemaV1, raw: unknown, name: string): Promise<unknown> {
-  const result = await validateAsync(schema, raw);
-  if (result.issues !== undefined) {
-    const detail = result.issues
-      .map((issue) => {
-        const path = formatPath(issue.path);
-        return path === '' ? issue.message : `${path}: ${issue.message}`;
-      })
-      .join('; ');
-    throw new QueryInputInvalidError(name, detail);
-  }
-  return result.value;
-}

package/src/rows-override.ts

@@ -0,0 +1,23 @@
+// The rows-override slot: canned rows where a stored declaration's `sql()` is, for a test. Keyed by
+// the declaration `read.ts` builds from, read per call after the parse and the policy — so a stub
+// answers on every read surface and never decides who may read.
+
+import type { Ctx } from '@ultimat3/core';
+
+/** Rows, or a function of the parsed input and the caller that answers them. */
+export type RowsOverride =
+  | readonly object[]
+  | ((args: {
+      readonly input: unknown;
+      readonly ctx: Ctx;
+    }) => readonly object[] | Promise<readonly object[]>);
+
+const OVERRIDES = new WeakMap<object, RowsOverride>();
+
+/** `undefined` puts the declared `sql()` back. */
+export function setRowsOverride(def: object, rows: RowsOverride | undefined): void {
+  if (rows === undefined) OVERRIDES.delete(def);
+  else OVERRIDES.set(def, rows);
+}
+
+export const rowsOverrideOf = (def: object): RowsOverride | undefined => OVERRIDES.get(def);

package/src/validate.ts

@@ -0,0 +1,35 @@
+/**
+ * A read's input parse — `@ultimat3/action`'s `validate.ts` twin. Bounded by `@ultimat3/schema`'s
+ * `MAX_ISSUES` (`validateAsync` stops collecting there), and the refusal carries the list a form
+ * binds to plus `issuesTruncated`, so a hostile 10k-item input costs a hundred rejections.
+ */
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, toValidationIssues, validateAsync } from '@ultimat3/schema';
+import { QueryInputInvalidError } from './errors';
+
+/**
+ * `toValidationIssues`, never the raw `result.issues`: a conforming library's issue may carry the
+ * rejected VALUE, and this list reaches the HTTP problem document.
+ */
+export async function parseQueryInput(
+  schema: StandardSchemaV1,
+  raw: unknown,
+  name: string,
+): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  if (result.issues === undefined) return result.value;
+  const issues = toValidationIssues(result.issues);
+  throw new QueryInputInvalidError(
+    name,
+    formatIssues(issues).join('; '),
+    issues,
+    result.issuesTruncated === true,
+  );
+}
+
+/** The parse without the refusal — only for the record of a read already refused on other grounds. */
+export async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  return result.issues === undefined ? result.value : undefined;
+}