@ultimat3/query 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -18,12 +18,14 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `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 |
 | `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 |
@@ -33,6 +35,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `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 |
 
@@ -61,8 +64,18 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   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`.**
+- **`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.
+- **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, `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.
 - **`deprecated:` is a compat WINDOW**: `Deprecation` / `Sunset` / `rel="successor-version"` on every
@@ -84,6 +97,15 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - 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.
+- **This package strips NO column, and must not start.** A query has no output parse; a
+  `.sealed()` column is absent from every projection because `@ultimat3/entity`'s repository row
+  does not ENUMERATE it (`serverOnly`, `packages/entity/src/sealed.ts`). So nothing on the read
+  path may rebuild a row property by property from a column list or `Object.getOwnPropertyNames`
+  — `JSON.stringify`, a spread and `Object.keys` are the only walks. `sealed-egress.test.ts` pins
+  HTTP (list, `Page`, single, envelope), MCP, live, the cache tier and a derived row.
+- **A live read keyed on a sealed column is refused at subscribe** (`assertNoSealedKey`, called by
+  `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 — the client
 
@@ -102,7 +124,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   import core from `@ultimat3/core/page`, the page keys live in the leaf `page-keys.ts`, and
   `client.ts` never imports `page-controls.ts` or `stable.ts`. `client-bundle.test.ts` fails on any
   titles table in the graph or past 11 kB; `client-subpath.test.ts` pins the specifier. Byte figures
-  (`As of 2026-09-22`, browser, minified): barrel `queryClient` 24,114 B; `./client` 10,210 B.
+  (`As of 2026-10-02`, browser, minified): barrel `queryClient` 25,237 B; `./client` 11,012 B.
 - **The record envelope is derived from `rows:`** — `answersRecords(rows)` (`hasEntityRows`,
   `@ultimat3/entity`), decided once at projection for `http.ts` and `openapi.ts`, sent on every
   answer. No `rows:` is byte-identical on the wire.
@@ -117,7 +139,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()`
@@ -132,6 +156,10 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - `paginate` has no `offset` and never grows one; it is reachable only as
   `query.page(input, { first, after })`. **A page is bounded**: `first` is 1…`MAX_PAGE_SIZE`
   (10,000, a twin of `@ultimat3/entity`'s).
+- **A 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
@@ -149,10 +177,14 @@ 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

package/README.md

@@ -53,6 +53,9 @@ const [post] = await queries.publicPost({ slug }); // typed input, typed rows
 
 Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
 
+`queryClient<Api['queries']>` typechecks at any app size: `client-scale-pins.ts` compiles it over
+100 reads in 50 modules — a list read, its `.page` and a `single: true` read — on every `typecheck`.
+
 Every read goes through `@ultimat3/core`'s **`clientTransport`** — the one browser HTTP function,
 `As of 2026-09-22` (21.0.0). There is no `fetch` call in this package: the `fetch` option is handed
 on as the transport's `fetchImpl`. The transport owns `Accept`, the trace/budget headers, the
@@ -65,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';
@@ -205,6 +211,8 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `sql.ts` | `explain()` — the generated SQL, verbatim |
 | `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
 
@@ -262,6 +270,22 @@ cursor cannot prove that rows sorting *before* it are unchanged, so any epoch ch
 new build, new policy, new schema — forces a full refetch instead of a resume. Bounded
 server memory bought with an occasional extra page fetch.
 
+## A sealed column never rides on a row
+
+A query has no output schema; nothing here strips a column. A `.sealed()` column is absent from
+every projection because `@ultimat3/entity` answers it as a server-only (non-enumerable) property —
+`row.password` on the server, nothing in `JSON.stringify(row)`.
+
+| Projection | Sealed column |
+|---|---|
+| HTTP — list, `Page`, `single: true`, the record envelope | absent |
+| MCP read, a `cache:` entry, a live snapshot | absent |
+| a derived row `({ ...row, extra })` | absent |
+| a derived row naming it `({ token: row.token })` | sent — the name is the statement |
+| `query(input)` on the server | `row.password` reads the plaintext |
+
+`sealed-egress.test.ts` holds one assertion per projection.
+
 ## Matcher support
 
 | Shape | Result |
@@ -270,6 +294,7 @@ server memory bought with an occasional extra page fetch.
 | `orderBy` (any number of keys) | insert position computed, moves become remove + add |
 | `limit` | tail eviction on insert, `refill` patch on removal |
 | joins, aggregates, `group by`, subqueries | `X_MATCHER_UNSUPPORTED` with a fix line |
+| a `.sealed()` column in a filter or an order | `X_MATCHER_UNSUPPORTED` — a change row carries no sealed column |
 
 An honest refusal beats a silently wrong result set, so unsupported shapes fail at
 **subscribe** time, not on the first change event.
@@ -320,7 +345,16 @@ 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()`.
+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
 
@@ -359,11 +393,14 @@ 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 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
@@ -432,9 +469,32 @@ 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
@@ -543,9 +603,9 @@ router feature here.
 | `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -36,11 +37,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/http": "22.15.0",
-    "@ultimat3/policy": "22.15.0",
-    "@ultimat3/schema": "22.15.0"
+    "@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"
   }
 }

package/src/client-scale-pins.ts

@@ -0,0 +1,78 @@
+// Compile-time pin: `queryClient<Api['queries']>` at 100 reads in 50 modules. Source, not a
+// `.test.ts` — `tsconfig.json` excludes those, so `tsc -b` would never read the claim. Types only:
+// nothing here is emitted, and a regression is a build error in the `typecheck` step.
+//
+// `QueryClient` is its own mapped type and regresses on its own. `defineApi` is `@ultimat3/action`'s
+// (sideways), so the map is spelled the way its `Merge` hands it over: one intersection of every
+// module's registered reads. `@ultimat3/action`'s `client-scale-pins.ts` holds the `Merge` half.
+
+import type { NumberSchema, ObjectSchema, StringSchema } from '@ultimat3/schema';
+import type { queryClient } from './client';
+import type { Page } from './pagination';
+import type { Query } from './query';
+
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/** Distinct per module, so no two modules collapse into one instantiation. */
+type ScaleInput<N extends number> = ObjectSchema<
+  { readonly orgId: StringSchema; readonly limit: NumberSchema } & {
+    readonly [K in `q${N}`]: StringSchema;
+  }
+>;
+
+type ScaleRow<N extends number> = { readonly id: string } & { readonly [K in `col${N}`]: number };
+
+/** One feature's reads: a list and a `single: true`, the two methods `QueryClient` projects. */
+type QueryModule<N extends number> = {
+  readonly [K in `listRows${N}`]: Query<ScaleInput<N>, ScaleRow<N>>;
+} & { readonly [K in `oneRow${N}`]: Query<ScaleInput<N>, ScaleRow<N>, true> };
+
+/** `Module<0> & … & Module<TCount - 1>`. A tail call, so the count costs no depth here. */
+type MergedQueries<
+  TCount extends number,
+  TSeen extends readonly unknown[] = [],
+  TMap = unknown,
+> = TSeen['length'] extends TCount
+  ? TMap
+  : MergedQueries<TCount, [...TSeen, unknown], TMap & QueryModule<TSeen['length']>>;
+
+type ScaleQueries = MergedQueries<50>;
+
+/** The idiom itself, through `queryClient`'s own `QueryMap` constraint. */
+type ScaleClient = ReturnType<typeof queryClient<ScaleQueries>>;
+
+export type _EveryModuleReachesTheClient = Assert<
+  'listRows0' | 'oneRow24' | 'listRows49' extends keyof ScaleClient ? true : false
+>;
+
+export type _TheClientHasExactlyTheMergedReads = Assert<
+  Equals<keyof ScaleClient, keyof ScaleQueries>
+>;
+
+type LastInput = { readonly orgId: string; readonly limit: number; readonly q49: string };
+
+/** One call of each shape, read off the LAST module's own declaration. */
+export type _AListReadAnswersRows = Assert<
+  Equals<
+    [Parameters<ScaleClient['listRows49']>[0], Awaited<ReturnType<ScaleClient['listRows49']>>],
+    [LastInput, readonly ScaleRow<49>[]]
+  >
+>;
+
+export type _AListReadPages = Assert<
+  Equals<Awaited<ReturnType<ScaleClient['listRows49']['page']>>, Page<ScaleRow<49>>>
+>;
+
+export type _ASingleReadAnswersTheRow = Assert<
+  Equals<
+    [Parameters<ScaleClient['oneRow49']>[0], Awaited<ReturnType<ScaleClient['oneRow49']>>],
+    [LastInput, ScaleRow<49>]
+  >
+>;
+
+/** A single read has no `page` — the route refuses the controls, so the method would be a 400. */
+export type _ASingleReadHasNoPage = Assert<
+  'page' extends keyof ScaleClient['oneRow49'] ? false : true
+>;

package/src/client.ts

@@ -203,6 +203,9 @@ function read(
  * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
  * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
  * split at `_first=` to recover the read underneath.
+ *
+ * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
+ * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
  */
 function searchOf(input: unknown, page?: PageControls): string {
   const params = new URLSearchParams();
@@ -211,7 +214,7 @@ function searchOf(input: unknown, page?: PageControls): string {
       const value = input[key];
       if (value === undefined || value === null) continue;
       for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
-        params.append(key, typeof item === 'object' ? JSON.stringify(item) : String(item));
+        params.append(key, wireText(item));
       }
     }
   }
@@ -221,3 +224,14 @@ function searchOf(input: unknown, page?: PageControls): string {
   }
   return params.toString();
 }
+
+/**
+ * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
+ * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
+ * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
+ * as the text it prints and the read's own schema says what is wrong with it.
+ */
+function wireText(item: unknown): string {
+  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
+  return typeof item === 'object' ? JSON.stringify(item) : String(item);
+}

package/src/column-kinds.ts

@@ -0,0 +1,28 @@
+// Single responsibility: the DECLARED kind of each column of the relation a read names. Postgres
+// compares two values by their column's type, so every comparison this package makes asks here
+// first and hands the answer to `@ultimat3/entity`'s comparator — never `typeof` the value.
+
+import type { ColumnKind } from '@ultimat3/entity';
+import { entityForTable } from '@ultimat3/entity';
+
+/** A column's declared kind, or `undefined` when nothing declares one. */
+export type KindOf = (column: string) => ColumnKind | undefined;
+
+const UNDECLARED: KindOf = () => undefined;
+
+/**
+ * The kinds of `QueryShape.entity`'s columns. Resolved once per read, sort or change event — the
+ * registry is a scan — and never per comparison.
+ *
+ * A relation no entity declares (`from('report', rows)` over a projection) has no kinds: its
+ * values compare as `@ultimat3/entity` compares an undeclared column, by what they are. `money` is
+ * two physical columns behind one property, so the property alone names no single value to order.
+ */
+export function kindsOf(relation: string): KindOf {
+  const columns = entityForTable(relation)?.$columns;
+  if (columns === undefined) return UNDECLARED;
+  return (column) => {
+    const kind = Object.hasOwn(columns, column) ? columns[column]?.$meta.kind : undefined;
+    return kind === 'money' ? undefined : kind;
+  };
+}

package/src/cursor-value.ts

@@ -1,11 +1,11 @@
 // Single responsibility: what a sort value becomes inside a cursor, and what it becomes again on
 // the way out. The codec is `@ultimat3/core`'s and it is JSON, so a `Date` went in and an ISO
-// STRING came back: `isAfterKey` then compared `"1769904000000"` against `"2026-02-01T…"` through
-// `compareValues`' string branch and page two came back empty. A `bigint` was worse — a bare
+// STRING came back: `isAfterKey` then compared `"1769904000000"` against `"2026-02-01T…"` as
+// text and page two came back empty. A `bigint` was worse — a bare
 // `TypeError` out of `JSON.stringify`, with no code and no fix.
 //
 // `@ultimat3/entity`'s `cursor.ts` solves the same problem by reading the column's declared kind.
-// A `query` has no column kinds — `QueryShape.orderBy` is a name and a direction — so the value
+// A read over a relation NO entity declares has no kinds to read (`column-kinds.ts`), so the value
 // carries its own tag instead. Self-describing, which is also what makes the revive total: nothing
 // here has to know which read minted the cursor.
 

package/src/facade.ts

@@ -45,7 +45,7 @@ export function facadeFor<
     // signed cursor is only reachable through the query that issued it.
     page: (input, args) => paginate(self(), input, args),
     live: (input, options) => toLiveQuery(self(), input, options),
-    tool: () => toQueryTool(self()),
+    tool: () => toQueryTool<TSingle>(self()),
     // One implementation for both wire shapes: the route decides the body, the transport parses
     // it, and only the TYPE differs — a single read's method answers the row, and has no `page`.
     client: (options) =>

package/src/http.ts

@@ -11,17 +11,15 @@ import { toBucket } from '@ultimat3/http';
 import { coerceQuery } from '@ultimat3/schema';
 import type { Deprecation } from './deprecation';
 import { recordDeprecatedCall, renderDeprecation } from './deprecation';
-import {
-  QueryDeprecationInvalidError,
-  QueryInputInvalidError,
-  QueryRowNotFoundError,
-} from './errors';
+import { QueryDeprecationInvalidError, QueryInputInvalidError } from './errors';
+import { absentArraysOf } from './input-shape';
 import { derivePath } from './naming';
 import { PAGE_FIRST_KEY, pageControlsOf } from './page-controls';
 import { admitsAnonymous, policyCapability } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, runQuery } from './read';
 import { recordAnswerFor, recordRowAnswerFor } from './record-answer';
+import { oneRowOf } from './single-answer';
 
 /**
  * `liveFeed` -> `GET /_x/query/live-feed`. Named for the primitive rather than spelled
@@ -63,7 +61,7 @@ export function toQueryRoute(target: AnyQuery): Route {
     // The two page controls come OUT first (`page-controls.ts`): they are the route's, not the
     // read's, and a schema that refused unknown keys would otherwise refuse every paged call.
     const { input: values, page } = pageControlsOf(name, request.queryRaw());
-    const input = coerceQuery(target.input, values);
+    const input = absentArraysOf(target.input, coerceQuery(target.input, values));
     if (target.single === true) {
       // Refused, not ignored: a caller paging a read of one object has the wrong read in mind, and
       // a silently dropped `_first` would answer a shape it did not ask for.
@@ -75,9 +73,7 @@ export function toQueryRoute(target: AnyQuery): Route {
       }
       // The first row — what every in-process `[0]` of the same read already takes. None is the
       // 404 a detail URL means, where a list read answers `200 []`.
-      const [row] = await runQuery(target, input, { surface: 'http' });
-      if (row === undefined) throw new QueryRowNotFoundError(name);
-      return answerRow(row);
+      return answerRow(oneRowOf(name, await runQuery(target, input, { surface: 'http' })));
     }
     // With a page control the answer is the `Page` envelope `query.page()` answers a server
     // caller with — `{ rows, nextCursor, hasMore, endCursor, hasNextPage }`, the same names (the

package/src/index.ts

@@ -65,6 +65,14 @@ export type {
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
 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`,
+ * `matchesFilter` and `isAfterKey` take the relation's declared kinds — `kindsOf(shape.entity)` —
+ * because how two values compare is `@ultimat3/entity`'s answer for the column's kind.
+ */
+export type { KindOf } from './column-kinds';
+export { kindsOf } from './column-kinds';
 /** The compat window a retirement gets. Versioning is two deployments, not a router feature. */
 export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
 export { recordDeprecatedCall, renderDeprecation } from './deprecation';
@@ -93,7 +101,7 @@ export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } fro
 export { planResume, seekOf, toLiveQuery } from './live';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
-export type { QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
+export type { QueryToolAnswer, QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
 export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
 /**
  * Path derivation only. There is no `toToolName`: an MCP tool is served under the export name
@@ -151,7 +159,6 @@ 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';
-
 export {
   describeQueries,
   getQuery,
@@ -164,18 +171,15 @@ export {
 export type { SearchChain, SearchDef, SearchInput, SearchPage } from './search';
 export { search } from './search';
 export type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-/**
- * `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.
- */
 export {
   compareRows,
-  compareValues,
   isNull,
   matchesFilter,
   seekKeyOf,
   totalOrder,
 } from './shape';
+/** What a `single: true` read answers — one rule, also `@ultimat3/mcp`'s served tool's. */
+export { readAnswer } from './single-answer';
 export type { RowProvider, SqlSource, SqlText } from './source';
 /** `isAfterKey` is the one definition of "after this position" — both seek paths use it. */
 export { Builder, from, isAfterKey } from './source';

package/src/input-shape.ts

@@ -79,3 +79,23 @@ export function assertEncodableInput(input: unknown): void {
   const offender = unencodable(node);
   if (offender !== undefined) throw new QueryInputUnencodableError(offender);
 }
+
+/**
+ * The route's half of an empty array. `searchOf` sends NOTHING for `[]` — a query string has no
+ * spelling for "this key, zero times" — so a REQUIRED array nobody sent can only be the empty one:
+ * left absent it fails validation, on a call the typed client accepted.
+ *
+ * Required only. An optional or defaulted array already has a meaning for absence, and it is the
+ * schema's: `[]` there would overwrite a declared default with a value the caller never wrote.
+ */
+export function absentArraysOf(
+  schema: unknown,
+  input: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...input };
+  for (const [key, child] of Object.entries(tryIntrospect(schema)?.properties ?? {})) {
+    if (child.kind !== 'array' || child.optional === true || child.hasDefault === true) continue;
+    if (!Object.hasOwn(input, key)) out[key] = [];
+  }
+  return out;
+}

package/src/live.ts

@@ -16,6 +16,7 @@ import { guard } from './policy-gate';
 import type { Query } from './query';
 import { queryHash } from './query';
 import { queryName, sourceFor } from './read';
+import { assertNoSealedKey } from './sealed-shape';
 import type { QueryShape, SeekKey } from './shape';
 import { seekKeyOf } from './shape';
 import { assertSubscribed } from './subscribes';
@@ -128,6 +129,8 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
   // outgrown means `x db gen` granted REPLICA IDENTITY FULL somewhere else, so every UPDATE on this
   // relation arrives without its old row and no patch is computable from it.
   assertSubscribed(name, target.subscribes, shape.entity);
+  // And once more for the same moment: a window keyed on a sealed column is read and never patched.
+  assertNoSealedKey(name, shape);
 
   const epoch = options.epoch ?? liveEpoch();
   const hash = queryHash(name, input);