@ultimat3/query 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -16,74 +16,88 @@ 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`.
 - **The route coerces (`coerceQuery`), `runQuery` validates.** No `request.query(schema)` and no
   `meta.input` on the route.
-- **`rateLimit:` is declarable; `toQueryRoute` sets both `meta.rateLimit` and
-  `meta.rateLimitBucket`**, via `@ultimat3/http`'s `toBucket` — never a local copy.
+- **The client and the route are two halves of one encoding.** `searchOf` sends a `Date` as its ISO
+  instant and nothing for `[]`; `absentArraysOf` (`input-shape.ts`) reads a REQUIRED array nobody
+  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 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
@@ -99,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.
@@ -112,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-01`, browser, minified): barrel `queryClient` 23,997 B; `./client` 10,899 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.
@@ -131,7 +160,9 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `SearchChain`). No `PRIMITIVE_FACTORIES` row (it returns a query from the query package). **It serves
   ONE page**: `windowOf.execute` refuses only when rows would be CUT; `onePage.seek` narrows with
   `Builder.limit()`, never `Builder.seek()`, so the chain's own ranking survives; no `total()`.
-  `search.test.ts`'s fixture must stay NOT id-ascending.
+  Its three refusals (blank term, a cursor, a window that cuts rows) are caller-reachable, so each
+  is `X_INPUT_INVALID` — never core's `assert`. `search.test.ts`'s fixture must stay NOT
+  id-ascending.
 - **`subscribes:` is DECLARED (nothing can derive it) and CROSS-CHECKED**: `toLiveQuery` asserts
   `shape.entity` is among the declared names at first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`) —
   membership, never equality. An empty list, or one on a non-live read, is refused at `query()`
@@ -145,7 +176,11 @@ 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
+  read. `Builder.seek()` takes the smaller limit too. `pagination-limit.test.ts`.
 - **A `RowProvider` may be a list, a sync function or an async one** (`source.test.ts`).
 - **A cursor is a position, not a row**: `isAfterKey` (`source.ts`) is the one definition of "after";
   never reintroduce a row lookup. The seek predicate is spelled out per key
@@ -163,22 +198,25 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **A sort value carries its TYPE through the cursor** (`cursor-value.ts`: `{ $x: 'date' | 'bigint',
   v }`; `undefined` → `null`). Untaggable values are `X_CURSOR_VALUE_UNSUPPORTED` where the cursor is
   minted.
-- **`compareValues` orders numbers and bigints in one order**; equality treats `number` and `bigint`
-  as one family (`shape.ts` `same`). `shape-order.test.ts` reads `@ultimat3/entity`'s `COLUMN_KINDS`.
-- **`numeric` and the TEXT form of `bigint` are a DECLARED gap** (`DECLARED_GAP` in
-  `shape-order.test.ts`): closing it needs an `OrderKey` carrying a kind, never a guessing comparator.
+- **This package has NO comparator.** How two values compare is `@ultimat3/entity`'s
+  `compareByKind` / `sameValueOfKind`, asked under the column's declared kind (`kindsOf(shape.entity)`,
+  `column-kinds.ts`). `compareRows`, `matchesFilter(s)` and `isAfterKey` REQUIRE the `KindOf`; never
+  add a `typeof` branch here — fix the rule in entity. `equalOrBothNull` adds only this package's
+  NULL rule. `compare-parity-fixture.ts` is the one table: `compare-parity.test.ts` (entity, matcher,
+  `from()`) and `compare-parity.live.test.ts` (Postgres). `grep compareValues src` stays empty.
+- **A relation no entity declares has no kinds** — digits there are text, as in a `text` column.
+  `shape-order.test.ts` reads `@ultimat3/entity`'s `COLUMN_KINDS`, one case per kind.
 - **A refill is owed by a FULL window only** (`held >= shape.limit`). **A move OUT of a full window is
   a `refill`, never an `add`.**
 - **A position is decided against the rows the WINDOW holds**: `unprojectedOrderKey` — a held row
   missing an ordering column (`Object.hasOwn`, never a value check) gets a `refill` rather than a
   guess. A delete is addressed by index and still patches.
-- **`tagKeys` is `@ultimat3/cache`'s.** `@ultimat3/render` exports a different `tagKeys`; never import
-  that one here.
+- **`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
 
@@ -192,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 |
 
@@ -68,8 +68,11 @@ A detail read declares `single: true`. The route answers the first row as the bo
 `X_NOT_FOUND`** when `sql` returns none (a list read answers `200 []`), refuses `_first`/`_after`
 (400), and `openapi.json` documents one object with a `404` and no page controls. `.client()` and
 `queryClient` type it `Promise<TRow>` with no `.page`. In process nothing moves: `postById({ id })`,
-`.as()`, `.page()`, `.live()` and the MCP tool still answer `readonly TRow[]`, so opting in breaks no
-`[0]` already written. `As of 2026-09-29`.
+`.as()`, `.page()` and `.live()` still answer `readonly TRow[]`, so opting in breaks no `[0]`
+already written. `As of 2026-09-29`. **`tool().read()` answers as the route does**
+(`As of 2026-10`): the row itself, and `X_NOT_FOUND` when `sql` returns none — an agent given `[]`
+for a missing id read "found, and empty" where HTTP said 404. The tool `@ultimat3/mcp` serves over
+`tools/call` answers the same two ways.
 
 ```ts
 import { can } from '@ultimat3/policy';
@@ -119,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,
@@ -156,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`,
@@ -176,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
@@ -199,15 +204,17 @@ 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 |
 | `sealed-shape.ts` | a live read may not filter or order on a `.sealed()` column — refused at subscribe |
 
 ## Live queries
@@ -340,8 +347,17 @@ 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
-refused, and the `fix:` names the chain — `db.posts.search(term).after(cursor).page()`.
+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 |
+|---|---|
+| `q` of only whitespace (`?q=%20%20` passes `t.string.min(1)`) | **400** `X_INPUT_INVALID` |
+| a cursor (`?_after=…`) | **400** `X_INPUT_INVALID` |
+| a window that would cut rows (`?_first=1` with two matches) | **400** `X_INPUT_INVALID`, naming both edits: widen `first` to the read's `limit`, or narrow `limit` |
+
+All three arrive on the request, so all three are the caller's. `As of 2026-10`; until then they
+were core `assert`s — `X_INVARIANT`, a 500 blaming the server.
 
 ## Pagination is cursor-only
 
@@ -358,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)
 ```
@@ -380,19 +398,22 @@ 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 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 |
 
 The MCP read tool does not page: `read()` answers the source's rows, bounded by the read's own
-`limit`, and an agent that wants more asks a narrower question.
+`limit` — or the one row of a `single: true` read — and an agent that wants more asks a narrower
+question.
 
 The codec lives in `@ultimat3/core`, not here: `encodeCursor`, `decodeCursor`,
 `configureCursorSigning` (set the signing secret once at boot; rotating it invalidates every
 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
@@ -453,13 +474,36 @@ the rows after it were unreachable through a cursor. An ascending key now reache
 NULL under `nulls last`, and the page continues on the id tiebreak, which is never NULL.
 
 `nulls last` / `nulls first` are Postgres' own defaults, written down rather than inherited: it is
-the rule `compareValues` implements, so the in-memory sort and the seek predicate can only agree
+the rule `compareRows` implements, so the in-memory sort and the seek predicate can only agree
 with it, and a driver whose default differs cannot re-open the divergence.
 
+## How two values compare
+
+**By the column's declared kind, and by `@ultimat3/entity`'s comparator — this package has none.**
+`kindsOf(shape.entity)` resolves each column's `ColumnKind` from the entity declared on that table,
+and `compareRows`, `matchesFilter`, `isAfterKey` and the matcher hand it to entity's
+`compareByKind` / `sameValueOfKind`: the one JS statement of how Postgres compares a column.
+`As of 2026-10`; until then a second comparator here decided by `typeof`.
+
+| Column | What its row holds | Decided as |
+|---|---|---|
+| `bigint()`, `decimal()` | decimal TEXT | digits, exactly: `'9'` before `'10'`, `'2.50'` equal to `'2.5'` and to `2.5` |
+| `uuid()` | text | a value: upper and lower case are one id |
+| `timestamp()` | `Date` | an instant: a `Date` equals the ISO text naming it |
+| `text()` | text | characters: `'10'` before `'9'`, as `order by` on a text column answers |
+| a relation no entity declares | whatever the row provider returned | no kind — numbers numerically (a `number` and a `bigint` in one order), `Date`s by instant, the rest as text |
+
+`compare-parity-fixture.ts` is the one `(kind, left, right)` table: `compare-parity.test.ts` runs it
+through entity's evaluator, the matcher and `from()`; `compare-parity.live.test.ts` runs it through
+Postgres, and walks a live window ordered on a `bigint()` and a `decimal()` column against the
+database's own `order by`. A custom `SqlSource` calling `compareRows`, `matchesFilter` or
+`isAfterKey` passes `kindsOf(shape.entity)` — the argument is required, because a comparison with
+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.
@@ -482,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
@@ -535,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.
@@ -554,19 +611,75 @@ 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('…')` |
 | `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 | `x queries describe <name> --json` |
+| `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 describe <name> --json` |
 | `X_QUERY_UNREGISTERED` | used before `registerQueries()` ran | register at boot |
-| `X_NOT_FOUND` | a `single: true` read matched no row — the HTTP route's 404 only (entity's code) | `x queries describe <name> --json` prints the SQL |
+| `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 describe <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_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` |
@@ -583,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": "23.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": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/http": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/schema": "23.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"
   }
 }