@ultimat3/query 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -16,54 +16,56 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `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); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
 | `client-scale-pins.ts` | compile-time pin: `queryClient<Api['queries']>` over 100 reads in 50 modules — list, `.page` and `single: true` |
 | `record-answer.ts` | a read's HTTP answer: bare rows, or the record envelope when `rows:` is an entity's branded row schema |
 | — | 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 |
+| `live.ts` | `LiveQuery` descriptor + cursor arithmetic + `spendQueryLimit` (a live subscribe's spend) |
+| `rate-limit-gate.ts` | **the one place** a read's declared `rateLimit:` is spent |
 | `subscribes.ts` | the relations a live read declares, and the two assertions that keep them true |
 | `sealed-shape.ts` | a live read keyed on a `.sealed()` column is refused at subscribe (`X_MATCHER_UNSUPPORTED`) |
 | `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 back |
 | `input-shape.ts` | what a read's `input:` may be, given that its route is a query STRING |
-| `sql.ts` | `explain()` / `describeSql()` |
+| `sql.ts` | `explainQuery()` / `describeSql()` |
 | `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 |
 | `shape.ts` | shared read vocabulary (filters, ordering, seek keys) |
 | `column-kinds.ts` | `kindsOf(relation)`: a column's DECLARED kind, from `QueryShape.entity` |
 | `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
-| `deprecation.ts` | `Deprecation` + RFC 9745/8594 render + `deprecated_calls_total` — TWINNED with `@ultimat3/action`'s |
+| `audit-gate.ts` | `audit: true` — **the only** file that calls an `AuditSink` (core's): one record per call, an audited source per `execute()` |
+| `audit-errors.ts` | `X_QUERY_AUDIT_SINK_MISSING` / `X_QUERY_AUDIT_SINK_FAILED` (titles in `errors.ts`) |
 
 ## Invariants — the read path
 
-- Every surface goes through `sourceFor`: the policy's actor half (`guardBeforeInput`), parse input,
+- Every surface goes through `sourceFor`: the policy's actor half (`guardQueryBeforeInput`), 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.
+  `@ultimat3/entity`'s tenant guard reads) must be the identity `guardQuery()` 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`.
+  query (`liveFeed.live()`); new methods are bound in `facade.ts`. **No MCP tool is projected
+  here** (O-tool, 25.0.0): `@ultimat3/mcp`'s `toolFrom` is the one projection, reading through
+  `sourceFor(…, { surface: 'mcp' })`. `.tool()`/`toQueryTool` coming back is red in `index.test.ts`,
+  `dsl.test.ts` and `type-pins.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`.
+- `mcp` is opt-in; `openapi.ts` asks core's `isMcpExposed` directly — the `isExposed` wrapper is gone.
 - **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`.
+  `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`.**
+  `queryClientMethodFor`. **`toQueryRoute` and `client()` derive the same URL from core's `queryPath`.**
 - **`QueryClient` typechecks at any app size, and a `.test.ts` cannot say so** (`tsconfig.json`
   excludes them): `client-scale-pins.ts` is source, so a regression is a `typecheck` error. The map
   it pins is the intersection `@ultimat3/action`'s `Merge` hands over; that package pins `Merge`.
@@ -74,24 +76,28 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   sent as `[]`. Never for an optional or defaulted one — absence there is the schema's answer.
   `http-round-trip.test.ts` pins both ends against each other.
 - **A `single: true` read answers the row or `X_NOT_FOUND` by ONE rule** (`single-answer.ts`:
-  `oneRowOf`, `readAnswer`) — the route, `tool().read()` and `@ultimat3/mcp`'s served tool all call
-  it. `QueryToolDescriptor<TSingle>` types the answer: rows for a list read, the row for a single.
-- **`rateLimit:` is declarable; `toQueryRoute` sets both `meta.rateLimit` and
-  `meta.rateLimitBucket`**, via `@ultimat3/http`'s `toBucket` — never a local copy.
+  `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'`).
+  `'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
+  `query:<name>|<subject>`. `toBucket` is http's — never a local copy. `rate-limit-surfaces.test.ts`.
 - **`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.**
+- **`policyCapability` is a display label; `policyPermissions` (`QueryDescriptor.permissions`) is
+  what a report matches on.** Both are `@ultimat3/policy`'s, imported from there.
 - **`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.
+- **`meta.auth` comes from `@ultimat3/policy`'s `admitsAnonymous`** (a walk of the tree, imported
+  from `@ultimat3/policy` by `http.ts`), never the root combinator. 25.0.0 dropped this package's
+  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).
 - Authz goes through `enforce(surface, policy, { input, actor, ctx })`; a live denial keeps its 4403
@@ -107,11 +113,25 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `toLiveQuery`): a change row carries none, so the window would be read once and never patched.
   The refusal names the column, never the filter's value.
 
+## Invariants — audit
+
+- **`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
+  `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;
+  `sourceFor` hands out an audited source (one record per `execute()`, `@ultimat3/mcp`'s served
+  tool included) and records a refused build at once. An `unenforced` build records nothing.
+- **Never the rows.** The sink is resolved before the parse (`X_QUERY_AUDIT_SINK_MISSING`); a
+  refused allowed record withholds the rows (`X_QUERY_AUDIT_SINK_FAILED`); a refused denied/failed
+  record is logged and the original error wins. `audit-surfaces.test.ts`.
+
 ## 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
+- **Flight control is `@ultimat3/core`'s, and NOT re-exported** (`clientFlight`,
+  `DEFAULT_CLIENT_RETRY`, `isTransientFailure`, `isSuperseded` — `X_HELPER_COPY` refuses a value
+  re-export; only the types `ClientFlight`/`ClientRetry` the options name). 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.
@@ -120,11 +140,12 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   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
+- **`@ultimat3/query/client` is the read client without the barrel** — `client.ts`
+  imports 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-10-02`, browser, minified): barrel `queryClient` 25,237 B; `./client` 11,012 B.
+  titles table in the graph or past 12 kB; `client-subpath.test.ts` pins the specifier. Byte figures
+  (browser, minified): barrel `queryClient` 25,237 B (`As of 2026-10-02`); `./client` 11,983 B
+  (`As of 2026-10-05`, +971 B: core reads a refusal's `Retry-After` and body title).
 - **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.
@@ -155,7 +176,7 @@ 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, a twin of `@ultimat3/entity`'s).
+  (10,000 — `@ultimat3/entity`'s, imported; this package never re-publishes it).
 - **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
@@ -190,13 +211,12 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **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.
+- **`tagKeys` is `@ultimat3/cache`'s** — the only public one; never restore a local copy.
 - **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`.
+  `columnOf`; core's `isJsonObject` is imported from core (`X_HELPER_COPY` refuses a re-export).
 - 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).
+  input)`). An unverified cursor is `X_CURSOR_INVALID` (`CursorInvalidError`, core's — imported from `@ultimat3/core`, never re-exported).
 
 ## Invariants — caching
 
@@ -210,10 +230,10 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **`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
+- **A fill is FENCED, by `@ultimat3/cache`'s fence inside `cacheStack.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
+  `cacheStack(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.

package/README.md

@@ -29,7 +29,7 @@ Every projection is a method on the query itself. A query has no `.def`.
 | `liveFeed.as(actor, { orgId })` | the same read as another actor — the surrounding context is untouched, `null` is signed out |
 | `liveFeed.page({ orgId }, { first: 20, after })` | one bounded page plus the signed cursor that continues it. There is no `offset` |
 | `liveFeed.live({ orgId })` | the `LiveQuery` `@ultimat3/realtime` subscribes to, carrying the same policy object |
-| `liveFeed.tool()` | the MCP read tool, named `liveFeed`. `tool().policy === liveFeed.policy`, and it reads fresh |
+| `toolFrom(liveFeed)` | the MCP read tool, from `@ultimat3/mcp` — named `liveFeed`, exactly what `tools/list` serves, reading fresh through `sourceFor` with the same policy object. There is no `liveFeed.tool()` (`As of 25.0.0`): it was a second projection a tier below the served one |
 | `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways. `.page(input, { first, after })` on the same method reads one page over the wire |
 | `liveFeed.describe()` | the manifest row |
 
@@ -122,20 +122,21 @@ or with a schema no `entity()` branded (a `t.object` look-alike, a `.pick()`ed p
 is the bare rows, byte-identical to before. `rows:` exists because a read's `sql:` names its table
 as a STRING, so nothing else carries a schema the envelope could be derived from.
 
-### Flight control — `createClientFlight`, opt-in
+### Flight control — `clientFlight`, opt-in
 
 A typed read is one dispatch and nothing else until a `flight` is installed. With one, N concurrent
 identical reads become ONE dispatch, a fence can retire everything issued before now, and a failure
 worth sending again is sent again on `@ultimat3/core`'s one backoff curve.
 
 ```ts
-import { createClientFlight, isSuperseded, queryClient } from '@ultimat3/query';
+import { clientFlight, isSuperseded } from '@ultimat3/core';
+import { queryClient } from '@ultimat3/query';
 
 declare const session: () => { userId: string };
 declare const baseUrl: string;
 type Api = { queries: Record<string, never> };
 
-const flight = createClientFlight({
+const flight = clientFlight({
   principal: () => session().userId,   // dedup is OFF without this — see below
   retry: { attempts: 3 },              // default is `attempts: 1`, i.e. no retry
   deadlineMs: 10_000,
@@ -159,10 +160,11 @@ flight.bump();
 | an **unclassified** throw is not retried | core's `retryDecision` retries anything nobody classified — a caller's own `AbortError` included. A client retries a declared `retryable`/`retry-after`, plus a dispatch that produced no response at all |
 | a deadline is `X_TIMEOUT` | core's code, already classified `retryable`, so a caller's own loop needs no table |
 
-`createClientFlight` is **`@ultimat3/core`'s**, re-exported here: it is the same object
-`@ultimat3/action` re-exports, because both packages are tier 3 and neither may import the other.
-It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
-this package exactly as before.
+`clientFlight` is **`@ultimat3/core`'s**, and imported from there, `isSuperseded` with it.
+It shipped as a byte-identical copy here and in `@ultimat3/action` (both tier 3, neither may import
+the other); the copies are gone, and since 25.0.0 so are the re-exports: one value, one import
+path (`X_HELPER_COPY`, `bun run flight-copies`). The types `ClientFlight` and `ClientRetry` stay
+re-exported, because `queryClient`'s options name them.
 
 Bundle cost is why `ClientFlight` is a TYPE inside `client.ts` and never a value. Importing
 `queryClient` alone through this package's barrel, `bun build --target=browser --minify`,
@@ -179,7 +181,7 @@ merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`
 ### Skipping the policy costs a written reason
 
 Two reads have no subscriber to decide about: developer tooling that returns the statement and no
-rows (`explain`, `describeSql`), and the shared, subject-less window a sync node builds once per
+rows (`explainQuery`, `describeSql`), and the shared, subject-less window a sync node builds once per
 `(query, input)`. Both say so, in words:
 
 ```ts
@@ -202,13 +204,14 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `mcp-tool.ts` | the MCP read descriptor |
 | `client.ts` | the typed read client (browser-safe) |
 | `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; `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 `@ultimat3/entity`'s `MAX_PAGE_SIZE` |
 | `openapi.ts` | the read half of `openapi.json` — one `GET` path item per registered query |
-| `naming.ts` | export name → wire path. The MCP tool name is the export name verbatim |
 | `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
 | `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
 | `pagination.ts` | `paginate()` — keyset pages over core's cursor codec |
-| `sql.ts` | `explain()` — the generated SQL, verbatim |
+| `sql.ts` | `explainQuery()` — the generated SQL, verbatim |
+| `audit-gate.ts` | `audit: true` — the only file that calls an `AuditSink`; one record per call, an audited source per `execute()` |
+| `audit-errors.ts` | `X_QUERY_AUDIT_SINK_MISSING` / `X_QUERY_AUDIT_SINK_FAILED` |
 | `cache.ts` | request memo + tag-keyed tier, one invalidation graph |
 | `source.ts` | the `SqlSource` contract + `from()`, the in-memory reference |
 | `column-kinds.ts` | `kindsOf(relation)` — the declared kind of each column, which every comparison is decided by |
@@ -344,7 +347,7 @@ empty box is not an empty result set.
 
 **It serves one page.** The rows come from the entity chain, which pages by its own signed cursor;
 that cursor cannot cross the `SqlSource` seam, and slicing in memory instead would cut inside the
-page the provider fetched and report `hasNextPage: false` at its edge. So a second page is
+page the provider fetched and report `hasMore: false` at its edge. So a second page is
 refused, and the cause names the chain — `db.posts.search(term).after(cursor).page()`.
 
 | A request `search()` refuses | Answer |
@@ -371,17 +374,19 @@ not exported, because a page is the read's own answer rather than an imported he
 
 The route reads two controls off the search string BEFORE the schema sees it, and with either
 present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, nextCursor,
-hasMore, endCursor, hasNextPage }`, the same names, so a cursor read off the wire and one read off a
-direct call are one string in one field. **`nextCursor` and `hasMore` are the preferred names**
-(`As of 22.12`); `endCursor` and `hasNextPage` carry the same two values, always, as aliases — not
-deprecated, so a client reading them keeps working. `openapi.json` lists all five as required, the
-aliases described as such. Without a control the answer is the bare array it has always been, so a
+hasMore }`, the same names, so a cursor read off the wire and one read off a direct call are one
+string in one field. The `endCursor`/`hasNextPage` alias pair is gone (`As of 25.0.0`): `Page` is
+the framework's one page type — `@ultimat3/core`'s, re-exported here, the same an entity `findMany`
+answers — and `openapi.json` lists exactly those three as required. **`nextCursor` is `null` exactly
+when `hasMore` is false** (`As of 25.0.0`; the last page used to keep a cursor, so a
+`while (page.nextCursor)` loop fetched an empty page past the end): `openapi.json` says so as a
+`oneOf`, and the type is a union that narrows `nextCursor` to `string` under `if (page.hasMore)`. Without a control the answer is the bare array it has always been, so a
 client written before the controls existed keeps reading rows. `As of 2026-09`; until then the
 route had no envelope, and a query over a paged external source carried its page marker on a row
 (an `olderCursor` column on the oldest message), which is a cursor on the wrong side of the shape.
 
 ```
-GET /_x/query/live-feed?orgId=…&_first=20             → { rows, nextCursor, hasMore, endCursor, hasNextPage }
+GET /_x/query/live-feed?orgId=…&_first=20             → { rows, nextCursor, hasMore }
 GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page (<c> = nextCursor)
 GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (unchanged)
 ```
@@ -393,7 +398,7 @@ GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (uncha
 | `_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 |
 | 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 page after the last is empty 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()` |
+| 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()` |
 | a cursor a limited read minted before that | **400** `X_CURSOR_INVALID` — it does not say how much of the limit is spent, and honouring it would start a second "top N" below the first |
 | the typed client | `feed.client({ baseUrl }).page(input, { first, after })` and `queries.feed.page(…)` append the two controls after the sorted input, so a paged URL is the plain URL plus a suffix |
 | `openapi.json` | every read is a `GET` path item with its input as `in: query` parameters, the two controls after them, and a `200` that is `oneOf` the bare rows and the envelope — `queryOpenApiPaths`, merged into `@ultimat3/action`'s document by the CLI |
@@ -407,8 +412,8 @@ The codec lives in `@ultimat3/core`, not here: `encodeCursor`, `decodeCursor`,
 open cursor) and `usesDevCursorSecret` are all imported from there. `As of 2026-08`, `x doctor`
 reports `X_CURSOR_SECRET_DEV` when a production process is still signing with the key shipped in
 the package, and rotating the secret is what invalidates every open cursor. This package supplies
-the only thing that is its business — the scope, `queryHash(name, input)` — and re-exports
-`CursorInvalidError` so the failure keeps its name on this surface.
+the only thing that is its business — the scope, `queryHash(name, input)`. `CursorInvalidError`
+is core's too, imported from `@ultimat3/core` (25.0.0 dropped this package's re-export).
 
 The scope's hash is **SHA-256, first 16 hex** — `fingerprint` from `@ultimat3/core`, the primitive
 and width `@ultimat3/entity`'s `planScope` already uses, and the same function
@@ -498,7 +503,7 @@ no kind is the defect.
 ## Caching
 
 Request memo (same read twice in one render ⇒ one round trip), then the tier ladder
-`@ultimat3/cache` has registered — `createCacheStack(registeredTiers())`, read down and promoted
+`@ultimat3/cache` has registered — `cacheStack(registeredTiers())`, read down and promoted
 up. Keys are `query:<name>:<authority>:<input fingerprint>:<tags>`. An action's `cache.invalidates`
 and a query's `cache.tags` meet in the one graph owned by `@ultimat3/cache`, because there is one
 registry and this package holds no store of its own.
@@ -521,7 +526,7 @@ skipped policy. `readAuthority(actor, scope)` is the only producer of the compon
 required positional argument of `cacheKeyFor`, because an optional one is one a call site forgets.
 
 **The fill is fenced, best-effort and single-flighted, and none of that is written here.**
-`createCacheStack` samples `@ultimat3/cache`'s fence immediately before it runs the source and
+`cacheStack` samples `@ultimat3/cache`'s fence immediately before it runs the source and
 re-asks it per rung before each write, so a bust that lands mid-read cannot be republished for the
 whole TTL — the caller still gets the rows it read, because those are its answer; only publishing is
 refused. Every tier call goes through `bestEffort`, so a Redis refusal is a miss rather than a
@@ -574,8 +579,21 @@ rateLimit: { limit: 3, windowMs: 600_000 },   // 3 held, one back every three an
 Symmetric with an action's, and for a reason: without it **every** `GET /_x/query/*` fell to the
 `default` bucket — 120 burst, 2/s per actor — so one authenticated caller could hold 120
 cross-tenant aggregates in flight and then 2/s indefinitely, from a single account, with no
-declaration able to say otherwise. `toQueryRoute` sets the bucket NAME and the NUMBERS, and
-`@ultimat3/http`'s `withRouteBuckets` registers them: a name alone falls through to `default`.
+declaration able to say otherwise.
+
+**One bucket, every surface.** The read path's front half (`buildSource`) spends it, so the HTTP
+route, a paged read and the MCP tool (`surface: 'mcp'`) all draw on the same bucket. A live
+SUBSCRIBE is realtime's — the sync node builds one shared window per `(query, input)` with no
+subscriber, which spends nothing — and spends per subscriber through `spendQueryLimit(target,
+{ actor })`. An in-process read (`surface: 'server'`, a page's render, a service) spends nothing.
+
+| Fact | Answer |
+|---|---|
+| whose bucket | the reader's: actor → org → connection address (`@ultimat3/http`'s `rateLimitSpends`) |
+| where it is counted | `@ultimat3/http`'s installed store (`installRateLimitStore`) — the one `@ultimat3/action` spends from, and the instance the boot hands `httpServer` |
+| what HTTP answers | `RateLimit-*` from the bucket closest to refusing; `429` + `Retry-After` on a refusal |
+| `default` | not spent for this route: it is `rateLimitedBy: 'handler'`, so a read declaring more than `default` is not capped at it. The tenant allowance still applies |
+
 The conversion is `toBucket` from `@ultimat3/http` — the same one the action route uses, because
 http owns `Bucket` and `action` is the same tier as this package. A pair the limiter cannot run
 on is `X_RATE_LIMIT_INVALID`, at projection.
@@ -593,10 +611,66 @@ before the read is deleted. A date that cannot be rendered is `X_QUERY_DEPRECATI
 projection, not on the first read. Versioning is two deployments behind one ingress, never a
 router feature here.
 
+`Deprecation`, `renderDeprecation` and `recordDeprecatedCall` are `@ultimat3/core`'s and are
+imported from there — this package does not re-export them (`As of 25.0.0`).
+
+## `audit: true` — who saw what
+
+```ts
+import { can } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+
+type Chart = { readonly id: string; readonly patientId: string };
+declare const charts: readonly Chart[];
+
+export const patientChart = query({
+  input: t.object({ patientId: t.uuid }),
+  policy: can('chart:read'),
+  audit: true,
+  sql: ({ patientId }) => from<Chart>('charts', charts).where({ patientId }),
+});
+```
+
+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.
+
+**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
+the reader whose call executed the SQL.
+
+| Field | On a read |
+|---|---|
+| `name` | the export name — required, and the record's only name (the `action` alias left in 25.0.0) |
+| `primitive` / `mutator` | `'query'` / `false` |
+| `surface` | `server` (a direct call, `.as()`, `.page()`), `http` (the route), `mcp` (`@ultimat3/mcp`'s served tool: `sourceFor(…, { surface: 'mcp' })`) |
+| `input` | the **parsed** input, as an action's record carries it; `undefined` when the parse failed. Unredacted in the record — a persisting sink redacts through `auditableInput` (core's credential-key table and `Secret`), as `postgresAuditSink` does |
+| `replayed` | `true` when the request memo or a cache tier answered |
+| `idempotencyKey` | always `null` |
+| `outcome` / `failure` | `allowed` \| `denied` \| `failed`, and the `X_*` code with the thrown value |
+
+**The rows are never on the record** — an action's record carries no result for the same reason:
+a copy of every row seen is a second table to protect as carefully as the first.
+
+| Path | Records |
+|---|---|
+| `read(input)`, `.as()`, the route, `.page()` | once per call — `.page()` once even when a spent `.limit()` answers without executing |
+| `sourceFor(target, input, …)` then `execute()` | once per `execute()`; a build that is refused (denied, unparsed, rate-limited) once, at the build |
+| `explainQuery()`, `describeSql()`, the shared live window | never — they are built `unenforced`, with no caller to attribute a sighting to |
+
+Failure policies are the action seam's: no sink installed is `X_QUERY_AUDIT_SINK_MISSING`, refused
+before the parse; a sink refusing a **denied/failed** record is logged (`audit.sink.failed`) and the
+original error still reaches the caller; a sink refusing an **allowed** record withholds the rows,
+`X_QUERY_AUDIT_SINK_FAILED` — a read commits nothing, so a retry is safe.
+
 ## Errors
 
 | 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_FAILED` | the sink refused the record of an allowed read; the rows were withheld | fix the sink, then retry the read |
 | `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
 | `X_QUERY_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
@@ -622,6 +696,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 |---|---|---|
 | `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` |
 | `QueryDuplicateError` | `X_QUERY_DUPLICATE` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -30,18 +30,18 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "24.0.0",
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/http": "24.0.0",
-    "@ultimat3/policy": "24.0.0",
-    "@ultimat3/schema": "24.0.0"
+    "@ultimat3/cache": "25.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/entity": "25.0.0",
+    "@ultimat3/http": "25.0.0",
+    "@ultimat3/policy": "25.0.0",
+    "@ultimat3/schema": "25.0.0"
   }
 }

package/src/audit-errors.ts

@@ -0,0 +1,43 @@
+/**
+ * The two ways an audited read fails because of its audit, and nothing else. Their own module so
+ * `errors.ts` keeps one job — the codes' TITLES are registered there, with every other code this
+ * package owns — and so a read that declares no audit never constructs either.
+ */
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * `audit: true` with no sink installed. Raised before the input is parsed and before anything is
+ * read — the twin of `@ultimat3/action`'s `X_AUDIT_SINK_MISSING`, and for the same reason there is
+ * no logger-backed default to fall back on: a line nobody stores would satisfy the declaration
+ * while recording nothing, which for a read is "who saw what" silently answered "nobody".
+ */
+export class QueryAuditSinkMissingError extends UltimateError {
+  constructor(query: string) {
+    super({
+      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()',
+    });
+  }
+}
+
+/**
+ * The sink refused the record of a read that SUCCEEDED, so the rows are withheld. The opposite of
+ * the action twin's position on one point: an action's handler had already committed and only the
+ * record is missing, while a read has changed nothing — so refusing the answer costs one retry,
+ * and handing back rows nobody recorded is exactly the gap an audited read exists to close.
+ */
+export class QueryAuditSinkFailedError extends UltimateError {
+  constructor(query: string, sourceError: unknown) {
+    super({
+      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',
+      meta: { query },
+      sourceError,
+    });
+  }
+}