@ultimat3/query 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -35,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 |
 
@@ -68,6 +69,13 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   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
@@ -116,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-10-01`, browser, minified): barrel `queryClient` 23,997 B; `./client` 10,899 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.
@@ -131,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()`
@@ -146,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
@@ -163,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

@@ -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';
@@ -208,6 +211,7 @@ 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
@@ -341,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
 
@@ -380,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
@@ -453,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
@@ -564,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": "23.0.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",
@@ -37,11 +37,11 @@
     "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": "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.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/matcher.ts

@@ -4,6 +4,8 @@
  * filters + orderBy + limit; anything else throws X_MATCHER_UNSUPPORTED, because
  * an honest refusal beats a silently wrong result set.
  */
+import type { KindOf } from './column-kinds';
+import { kindsOf } from './column-kinds';
 import { MatcherUnsupportedError, QueryNotPageableError } from './errors';
 import type { QueryShape } from './shape';
 import { compareRows, matchesFilters, totalOrder } from './shape';
@@ -58,7 +60,10 @@ export function match<TRow extends object>(
   const id = idOf(event.row, shape.entity);
   const index = rows.findIndex((row) => idOf(row, shape.entity) === id);
   const inSet = index >= 0;
-  const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
+  // The declared kinds of the relation's columns, resolved once for this event: every comparison
+  // below is `@ultimat3/entity`'s, asked under the kind Postgres would decide by.
+  const kindOf = kindsOf(shape.entity);
+  const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters, kindOf);
 
   if (event.op === 'delete' || (inSet && !belongs)) {
     return inSet ? removeAt(shape, index, id, true, rows.length) : [];
@@ -81,14 +86,14 @@ export function match<TRow extends object>(
     return [{ kind: 'refill', from: 0 }];
   }
 
-  if (!inSet) return insert(shape, rows, event.row);
+  if (!inSet) return insert(shape, rows, event.row, kindOf);
 
   // Present and still matching: a change to an ordering column is a move, not an update.
   const current = rows[index];
   const moved =
     shape.orderBy.length > 0 &&
     current !== undefined &&
-    compareRows(event.row, current, shape.orderBy) !== 0;
+    compareRows(event.row, current, shape.orderBy, kindOf) !== 0;
   if (!moved) return [{ kind: 'update', position: index, row: event.row }];
 
   const without = [...rows.slice(0, index), ...rows.slice(index + 1)];
@@ -100,12 +105,12 @@ export function match<TRow extends object>(
   // window is `[b, c, d]`. Whether the moved row is still in the window is the server's answer
   // too, so the refill covers both.
   const wasFull = shape.limit !== null && rows.length >= shape.limit;
-  if (wasFull && positionFor(shape, without, event.row) >= without.length) {
+  if (wasFull && positionFor(shape, without, event.row, kindOf) >= without.length) {
     return removeAt<TRow>(shape, index, id, true, rows.length);
   }
   return [
     ...removeAt<TRow>(shape, index, id, false, rows.length),
-    ...insert(shape, without, event.row),
+    ...insert(shape, without, event.row, kindOf),
   ];
 }
 
@@ -113,8 +118,9 @@ function insert<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
+  kindOf: KindOf,
 ): readonly Patch<TRow>[] {
-  const position = positionFor(shape, rows, row);
+  const position = positionFor(shape, rows, row, kindOf);
   // Sorted past the end of a full window: the row exists but nobody sees it.
   if (shape.limit !== null && position >= shape.limit) return [];
   const patches: Patch<TRow>[] = [{ kind: 'add', position, row }];
@@ -186,10 +192,11 @@ export function positionFor<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
+  kindOf: KindOf = kindsOf(shape.entity),
 ): number {
   if (shape.orderBy.length === 0) return rows.length;
   const order = totalOrder(shape.orderBy);
-  const found = rows.findIndex((current) => compareRows(row, current, order) < 0);
+  const found = rows.findIndex((current) => compareRows(row, current, order, kindOf) < 0);
   return found === -1 ? rows.length : found;
 }
 

package/src/mcp-tool.ts

@@ -6,12 +6,13 @@
 
 import type { Actor, Ctx } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
-import type { JsonSchema } from '@ultimat3/schema';
-import { toMcpInputSchema } from '@ultimat3/schema';
+import type { WireJsonSchema } from '@ultimat3/schema';
+import { toWireSchema } from '@ultimat3/schema';
 import type { QueryPolicy } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, sourceFor } from './read';
 import { listQueries } from './registry';
+import { readAnswer } from './single-answer';
 
 export interface QueryToolReadOptions {
   readonly ctx?: Ctx;
@@ -19,7 +20,18 @@ export interface QueryToolReadOptions {
   readonly actor?: Actor | null;
 }
 
-export interface QueryToolDescriptor {
+/**
+ * What `read()` resolves to, decided by the declaration: a list read's rows, a `single: true`
+ * read's one row. Only a schema-erased query (`AnyQuery`, a mixed registry) answers the union —
+ * a KNOWN list read typed as "rows or a row" made `.map` on its own answer a compile error.
+ */
+export type QueryToolAnswer<TSingle extends boolean> = [TSingle] extends [true]
+  ? object
+  : [TSingle] extends [false]
+    ? readonly object[]
+    : readonly object[] | object;
+
+export interface QueryToolDescriptor<TSingle extends boolean = boolean> {
   /**
    * The export name VERBATIM, and identical to `query` below. `@ultimat3/mcp` serves a read
    * under `queryName(target)` and answers `tools/call` for nothing else, so a snake_cased
@@ -34,20 +46,28 @@ export interface QueryToolDescriptor {
    * is what makes "an MCP call cannot reach a different authz path" checkable.
    */
   readonly policy: QueryPolicy;
-  readonly inputSchema: JsonSchema;
+  /** What `@ultimat3/mcp`'s `tools/list` serves for this read — `@ultimat3/schema`'s wire subset. */
+  readonly inputSchema: WireJsonSchema;
   /** Always false: a query reads. Drives the rate-limit bucket in @ultimat3/mcp. */
   readonly mutates: false;
-  read(input: unknown, options?: QueryToolReadOptions): Promise<readonly object[]>;
+  /**
+   * The rows — or, for a `single: true` read, the one row itself and `X_NOT_FOUND` when there is
+   * none. The route's answer on both counts: an agent handed `[]` for a missing id reads "found,
+   * and empty" where the same read over HTTP said 404.
+   */
+  read(input: unknown, options?: QueryToolReadOptions): Promise<QueryToolAnswer<TSingle>>;
 }
 
-export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
+export function toQueryTool<TSingle extends boolean = boolean>(
+  target: AnyQuery & { readonly single?: TSingle },
+): QueryToolDescriptor<TSingle> {
   const name = queryName(target);
   return {
     name,
     description: target.mcp?.description ?? name,
     query: name,
     policy: target.policy,
-    inputSchema: toMcpInputSchema(target.input),
+    inputSchema: toWireSchema(target.input),
     mutates: false,
     read: async (input, options = {}) => {
       // Executed without the cache tiers on purpose: an agent diffing two tool
@@ -56,7 +76,8 @@ export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
         ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
         ...(options.actor === undefined ? {} : { actor: options.actor }),
       });
-      return source.execute();
+      // The declaration decides the shape, and `TSingle` is that declaration as a type.
+      return readAnswer(target, await source.execute()) as QueryToolAnswer<TSingle>;
     },
   };
 }

package/src/pagination.ts

@@ -11,7 +11,9 @@
  */
 import { assert, decodeCursor, encodeCursor } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { kindsOf } from './column-kinds';
 import { reviveSortKey, serializeSortValue } from './cursor-value';
+import { CursorInvalidError } from './errors';
 import { MAX_PAGE_SIZE } from './page-controls';
 import type { Query, SourceOptions } from './query';
 import { queryHash, queryName, sourceFor } from './query';
@@ -73,18 +75,24 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   const base = await sourceFor(target, input, args);
   const shape = base.shape();
   // Revived to the types the columns hold, never left as the strings JSON handed back: a `Date`
-  // key decoded as an ISO string reaches `compareValues` as text and is compared against the
-  // row's own millisecond number, so page two matched nothing at all. See `cursor-value.ts`.
-  const after: SeekKey | null =
-    decoded === null ? null : seekFromCursor(decoded, shape.orderBy.length);
+  // key decoded as an ISO string was compared as text against the row's own instant, so page two
+  // matched nothing at all. See `cursor-value.ts`.
+  const resumed = decoded === null ? null : seekFromCursor(decoded, shape.orderBy.length);
+  const after = resumed?.seek ?? null;
+  const left = rowsLeft(shape.limit, resumed);
+  // The whole of a declared limit is already served: there is no row to ask the source for.
+  if (left === 0) return pageOf<TRow>([], null, false);
 
   // `MAX_PAGE_SIZE` lives in `page-controls.ts`: the route checks the same bound at the wire, as
   // a 400, before this `assert` — which is a 500 — can see the number.
-  // Fetch one extra row: its presence *is* `hasNextPage`, with no count query.
-  const window = args.first + 1;
+  // Fetch one extra row: its presence *is* `hasNextPage`, with no count query. Never past what a
+  // declared `.limit()` has left — `first` used to REPLACE that limit, so `?_first=10000` walked a
+  // "top 3" to the end of the table.
+  const window = Math.min(left, args.first + 1);
   const source: SqlSource<object> = base.seek === undefined ? base : base.seek(after, window);
   const executed = await source.execute();
-  const scoped = base.seek === undefined ? inTotalOrder(executed, after, shape) : executed;
+  const scoped =
+    base.seek === undefined ? inTotalOrder(executed, after, shape).slice(0, window) : executed;
   // The source came from this query's own `sql()`, so its rows are TRow.
   const rows = scoped.slice(0, args.first) as unknown as readonly TRow[];
   const last = rows[rows.length - 1];
@@ -97,12 +105,41 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
           scope: hash,
           // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
           // numeric or bigint tiebreak compares as a number on the next page, not lexically.
-          key: [...seek.key, seek.id].map(serializeSortValue),
+          // A limited read appends how much of its limit is now spent: a keyset cursor names a
+          // position and no count, and the count is the only thing that can end a "top N".
+          key: [
+            ...[...seek.key, seek.id].map(serializeSortValue),
+            ...(shape.limit === null ? [] : [(resumed?.served ?? 0) + rows.length]),
+          ],
           id: String(seek.id),
         });
   return pageOf(rows, nextCursor, scoped.length > args.first);
 }
 
+/** A decoded cursor: where the page resumes, and how many rows of a declared limit are spent. */
+interface Resumed {
+  readonly seek: SeekKey;
+  readonly served: number | undefined;
+}
+
+/**
+ * Rows a declared limit still allows, or no bound at all for a read that declares none.
+ *
+ * A cursor on a limited read MUST say how many rows came before it. One that does not was minted
+ * before the limit bounded the listing (or before the read declared one), and honouring it would
+ * start a fresh "top N" below the real one — so it is refused as any other cursor this read did
+ * not mint, with core's own instruction: request the first page again.
+ */
+function rowsLeft(limit: number | null, resumed: Resumed | null): number {
+  if (limit === null) return Number.POSITIVE_INFINITY;
+  if (resumed === null) return Math.max(0, limit);
+  const { served } = resumed;
+  if (served === undefined || !Number.isInteger(served) || served < 1) {
+    throw new CursorInvalidError('it does not say how much of this read’s limit is already served');
+  }
+  return Math.max(0, limit - served);
+}
+
 /**
  * The cursor names a POSITION in the ordering, so the fallback filters by that position — the
  * same comparison `Builder.seek()` pushes into SQL. Locating the cursor's row by id instead
@@ -128,20 +165,26 @@ function inTotalOrder(
   shape: QueryShape,
 ): readonly object[] {
   const keys = totalOrder(shape.orderBy);
-  const ordered = [...rows].sort((left, right) => compareRows(left, right, keys));
+  const kindOf = kindsOf(shape.entity);
+  const ordered = [...rows].sort((left, right) => compareRows(left, right, keys, kindOf));
   if (after === null) return ordered;
-  return ordered.filter((row) => isAfterKey(row, after, shape.orderBy));
+  return ordered.filter((row) => isAfterKey(row, after, shape.orderBy, kindOf));
 }
 
 /**
- * The seek a decoded cursor names. A cursor carrying one more key than the ordering has its typed
- * id at the tail; an older cursor, minted before the id rode there, falls back to the string slot.
+ * The seek a decoded cursor names. A cursor carrying more keys than the ordering has its typed id
+ * next, then — on a limited read — the count of rows served so far; an older cursor, minted before
+ * the id rode there, falls back to the string slot.
  */
 function seekFromCursor(
   decoded: { readonly key: readonly unknown[]; readonly id: string },
   width: number,
-): SeekKey {
+): Resumed {
   const key = reviveSortKey(decoded.key);
-  if (key.length !== width + 1) return { key, id: decoded.id };
-  return { key: key.slice(0, width), id: key[width] };
+  if (key.length <= width) return { seek: { key, id: decoded.id }, served: undefined };
+  const count = key[width + 1];
+  return {
+    seek: { key: key.slice(0, width), id: key[width] },
+    served: typeof count === 'number' ? count : undefined,
+  };
 }

package/src/query.ts

@@ -297,6 +297,8 @@ export interface Query<
    * so it lives here and not on the schema-erased `AnyQuery` view.
    */
   client(options: QueryClientOptions): QueryClientMethodOf<TInput, TRow, TSingle>;
+  /** Narrowed by the declaration: a list read's tool answers rows, a single read's one row. */
+  tool(): QueryToolDescriptor<TSingle>;
 }
 
 /** The fluent half of a query: lifted declaration plus one method per projection. */

package/src/search.ts

@@ -6,12 +6,13 @@
  * syntax, and the tenant predicate is never optional.
  */
 
-import { assert, type Ctx, finiteOption } from '@ultimat3/core';
+import { type Ctx, finiteOption } from '@ultimat3/core';
 import type { InferOutput, Shape, Simplify } from '@ultimat3/schema';
 import { t } from '@ultimat3/schema';
+import { QueryInputInvalidError } from './errors';
 import type { QueryPolicy } from './policy-gate';
 import type { QueryCache, QueryMcp, QueryRateLimit } from './query';
-import { query } from './query';
+import { query, queryName } from './query';
 import type { SeekKey } from './shape';
 import type { Builder, SqlSource, SqlText } from './source';
 import { from } from './source';
@@ -19,10 +20,9 @@ import { from } from './source';
 /**
  * What `@ultimat3/entity`'s `ReadBuilder` answers, crossed STRUCTURALLY.
  *
- * This package may import `@ultimat3/entity` (tier 2) and deliberately does not: nothing here does
- * today, so a real dependency would be a new edge in `package.json` and a new block in `bun.lock`
- * for four methods. Same trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down, and the same
- * discipline — the shape is the contract, and a chain that does not satisfy it does not compile.
+ * Four methods are all this file reads, so the chain is named by its shape rather than by
+ * `ReadBuilder`'s type: an app may hand over a wrapper of its own, and one that does not satisfy
+ * the shape does not compile.
  */
 export interface SearchChain<Row extends object> {
   /** Appends the full-text predicate. The TERM, never a tsquery. */
@@ -85,8 +85,12 @@ const limitSchema = (max: number, fallback: number) =>
  * signed, plan-scoped string, and there is no way to mint one from the other here. Falling through
  * to `paginate`'s in-memory slice would cut inside the one page the provider fetched and report
  * `hasNextPage: false` at its edge — rows served on no page at all, which is the defect 12.0.0 spent
- * a release removing from the timestamp seek. So it is a refusal with the alternative in the `fix`:
- * page with the entity chain's own `.search(term).after(cursor)`, or raise this read's `limit`.
+ * a release removing from the timestamp seek. So it is a refusal naming the alternative: page with
+ * the entity chain's own `.search(term).after(cursor)`, or raise this read's `limit`.
+ *
+ * **Every refusal here is the CALLER's, so each is `X_INPUT_INVALID`** — a 400. A cursor, a window
+ * and a blank term all arrive on the request (`?_after=`, `?_first=`, `?q=%20`); raised with core's
+ * `assert` they were `X_INVARIANT`, a 500 that blamed the server and paged whoever watches it.
  *
  * **The refusal is on the rows that would be CUT, never on the window** (`As of 2026-08-26`). It
  * used to serve `first` rows, mint an `endCursor` and report `hasNextPage: true` — a connection
@@ -112,6 +116,8 @@ const limitSchema = (max: number, fallback: number) =>
  */
 const onePage = <Row extends object>(
   base: Builder<Row>,
+  /** The read's registered name — what the refusal's `fix:` asks `x queries describe` about. */
+  read: string,
   entity: string,
   /** Rows the chain was capped at — this read's `limit` input, and its whole page. */
   served: number,
@@ -123,14 +129,15 @@ const onePage = <Row extends object>(
   // resumed in", which is exactly true of a relevance ranking — and `total()` would totalize the
   // Builder, re-sorting that ranking by id for the same reason `seek` must not.
   seek: (after: SeekKey | null, window: number): SqlSource<Row> => {
-    assert(
-      after === null,
-      `search of ${entity} serves one page: a relevance-filtered read has no cursor this layer can carry`,
-      `db.${entity}.search(term).orderBy('<key>').after(cursor).page()   # the entity chain pages this read — or raise its limit`,
-    );
+    if (after !== null) {
+      throw new QueryInputInvalidError(
+        read,
+        `search of ${entity} serves one page: a relevance-filtered read has no cursor this layer can carry — raise this read's limit, or page the entity chain itself with .search(term).after(cursor)`,
+      );
+    }
     // `paginate` asks for `first + 1` — the extra row IS `hasNextPage` — so the window it names is
     // one wider than the page it will serve.
-    return windowOf(base, entity, served, window - 1);
+    return windowOf(base, read, entity, served, window - 1);
   },
 });
 
@@ -142,11 +149,12 @@ const onePage = <Row extends object>(
  * rows or fewer, which is most searches. Refusing it on the declaration alone made the framework's
  * own defaults a 500.
  *
- * The `fix:` names `served` — the read's declared `limit` — and never the count that came back: a
+ * The refusal names `served` — the read's declared `limit` — and never the count that came back: a
  * window sized to today's result set breaks on the first row added to the corpus.
  */
 const windowOf = <Row extends object>(
   base: Builder<Row>,
+  read: string,
   entity: string,
   served: number,
   /** Rows `paginate` will serve. It fetched one more, to decide `hasNextPage`. */
@@ -161,11 +169,12 @@ const windowOf = <Row extends object>(
     // ranking, which `total()` would re-sort by id for the same reason `seek` must not.
     execute: async () => {
       const rows = await windowed.execute();
-      assert(
-        rows.length <= first,
-        `search of ${entity} answered more than the ${String(first)} rows .page() asked for, and this read has no second page: the rest would be on no page at all`,
-        `read.page(input, { first: ${String(served)} })   # widen the window to the read's whole page — or narrow the page: read({ q, limit: ${String(first)} })`,
-      );
+      if (rows.length > first) {
+        throw new QueryInputInvalidError(
+          read,
+          `search of ${entity} answered more than the ${String(first)} rows .page() asked for, and this read has no second page: the rest would be on no page at all — widen the window to the read's whole page with read.page(input, { first: ${String(served)} }), or narrow the read with read({ q, limit: ${String(first)} })`,
+        );
+      }
       return rows;
     },
   };
@@ -190,28 +199,37 @@ export const search = <Row extends object, S extends Shape = Record<string, neve
     ),
   } as SearchShape<S>;
 
-  return query({
+  const self = query({
     input: t.object(shape),
     policy: def.policy,
     live: false,
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
-    sql: (input, ctx) => {
+    // The return type is WRITTEN: the body names `self`, and an inferred one would make this
+    // declaration's type depend on itself.
+    sql: (input, ctx): SqlSource<Row> => {
       const parsed = input as SearchInput<S> & { readonly q: string; readonly limit: number };
       // Trimmed and refused HERE, before the chain exists: `websearch_to_tsquery('english', '  ')`
       // is a legal empty tsquery matching nothing, so a blank box would answer "no results" as if
       // it had searched. Saying so is the difference between an empty answer and an empty question.
       const term = parsed.q.trim();
-      assert(
-        term.length > 0,
-        'a search term of only whitespace is not a search',
-        'guard the input before calling: if (term.trim() === "") return [] — an empty box is not an empty result set',
-      );
+      if (term.length === 0) {
+        throw new QueryInputInvalidError(
+          queryName(self),
+          'q is only whitespace, which is not a search — guard the box before calling: an empty box is not an empty result set',
+        );
+      }
       const chain = def.in({ input: parsed, ctx });
       const name = chain.plan().entity;
       const rows = () => chain.search(term).limit(parsed.limit).all();
-      return onePage(from<Row>(name, rows).raw('full-text search'), name, parsed.limit);
+      return onePage(
+        from<Row>(name, rows).raw('full-text search'),
+        queryName(self),
+        name,
+        parsed.limit,
+      );
     },
   });
+  return self;
 };

package/src/shape.ts

@@ -1,7 +1,11 @@
 /**
  * The read vocabulary shared by the matcher, the SQL sources, pagination and the
- * live descriptor. Types only plus two pure predicates — no I/O lives here.
+ * live descriptor: the types, and the two predicates that read a row. How two VALUES compare is
+ * `@ultimat3/entity`'s answer (`compareByKind`, `sameValueOfKind`) — no comparator lives here.
  */
+import type { ColumnKind } from '@ultimat3/entity';
+import { compareByKind, sameValueOfKind } from '@ultimat3/entity';
+import type { KindOf } from './column-kinds';
 import { QueryNotPageableError } from './errors';
 import { columnOf } from './stable';
 
@@ -87,24 +91,33 @@ export function isNull(value: unknown): boolean {
   return value === null || value === undefined;
 }
 
-export function matchesFilters(row: object, filters: readonly Filter[]): boolean {
-  return filters.every((filter) => matchesFilter(row, filter));
+export function matchesFilters(row: object, filters: readonly Filter[], kindOf: KindOf): boolean {
+  return filters.every((filter) => matchesFilter(row, filter, kindOf));
 }
 
-export function matchesFilter(row: object, filter: Filter): boolean {
+/**
+ * One filter against one row, as Postgres answers it for that column. `kindOf` is required: a
+ * comparison with no declared kind to decide by is how `'10'` in a `bigint()` column sorted before
+ * `'9'`, and an optional argument is one a caller forgets.
+ */
+export function matchesFilter(row: object, filter: Filter, kindOf: KindOf): boolean {
   const actual = columnOf(row, filter.column);
+  const kind = kindOf(filter.column);
   switch (filter.op) {
     case '=':
-      return same(actual, filter.value);
+      return equalOrBothNull(kind, actual, filter.value);
     case '!=':
-      return !same(actual, filter.value);
+      return !equalOrBothNull(kind, actual, filter.value);
     case 'in':
-      return Array.isArray(filter.value) && filter.value.some((item) => same(actual, item));
+      return (
+        Array.isArray(filter.value) &&
+        filter.value.some((item) => equalOrBothNull(kind, actual, item))
+      );
     case '>':
     case '>=':
     case '<':
     case '<=':
-      return ordered(filter.op, actual, filter.value);
+      return ordered(filter.op, kind, actual, filter.value);
     default:
       return false;
   }
@@ -115,9 +128,14 @@ export function matchesFilter(row: object, filter: Filter): boolean {
  * ordering operator matches nothing here either. Only `=`, `!=` and `in` read NULL as a value —
  * and those are exactly the three `Builder.toSQL()` compiles to `is null` / `is distinct from`.
  */
-function ordered(op: '>' | '>=' | '<' | '<=', actual: unknown, value: unknown): boolean {
+function ordered(
+  op: '>' | '>=' | '<' | '<=',
+  kind: ColumnKind | undefined,
+  actual: unknown,
+  value: unknown,
+): boolean {
   if (isNull(actual) || isNull(value)) return false;
-  const result = compareValues(actual, value);
+  const result = compareByKind(kind, actual, value);
   switch (op) {
     case '>':
       return result > 0;
@@ -131,88 +149,37 @@ function ordered(op: '>' | '>=' | '<' | '<=', actual: unknown, value: unknown):
 }
 
 /**
- * Dates compare by instant, everything else by value. No coercion across types.
- *
- * NULL is greater than every value and equal to itself — Postgres' own sort rule, which is what
- * lets `Builder.toSQL()` write it down as `asc nulls last` / `desc nulls first` and mean this
- * function. Sorting only: a comparison *filter* against NULL matches nothing (`ordered`). Before
- * this, `null` sorted as the string `"null"`, so it landed between `"m"` and `"o"` in memory and
- * at the end in the database — the same page read two ways.
+ * This package's NULL rule around `@ultimat3/entity`'s equality: `=`, `!=` and `in` read NULL as a
+ * value, so two absences are equal and an absence equals nothing else. What two PRESENT values
+ * are to each other is not decided here — `sameValueOfKind` answers by the column's kind.
  */
-export function compareValues(a: unknown, b: unknown): number {
-  if (isNull(a) || isNull(b)) return isNull(a) ? (isNull(b) ? 0 : 1) : -1;
-  const left = normalize(a);
-  const right = normalize(b);
-  if (isNumeric(left) && isNumeric(right)) return compareNumeric(left, right);
-  const l = String(left);
-  const r = String(right);
-  return l < r ? -1 : l > r ? 1 : 0;
-}
-
-function isNumeric(value: unknown): value is number | bigint {
-  return typeof value === 'number' || typeof value === 'bigint';
+function equalOrBothNull(kind: ColumnKind | undefined, a: unknown, b: unknown): boolean {
+  if (isNull(a) || isNull(b)) return isNull(a) && isNull(b);
+  return sameValueOfKind(kind, a, b);
 }
 
 /**
- * Numbers and bigints, in one order, because **Postgres orders them in one order**.
+ * Row ordering under an `orderBy` list. Stable, and total when an id key is last.
  *
- * `bigint` is a first-class `ColumnKind` — the physical type of every `<p>_minor` column — and
- * `@ultimat3/entity`'s `count-by.ts` lists it as groupable, so these values do reach the
- * comparator. The old numeric fast path was `typeof left === 'number' && typeof right ===
- * 'number'` alone, so a bigint fell through to `String(left) < String(right)`:
- * `compareValues(9n, 10n)` answered `1` and a sort came out `["10", "100", "9"]`, which means the
- * in-memory source, the live matcher and the seek fallback all disagreed with the database on any
- * bigint-ordered read — including page two of one.
- *
- * A bigint pair never subtracts: the difference is exact but the return type is a `number`. A
- * mixed pair goes through `BigInt` when the number is whole, so a value past 2^53 keeps its exact
- * place; a fractional number cannot equal a bigint, so comparing it as a float is enough to place
- * it. `Number.isInteger` is false for `NaN` and `±Infinity`, which is what keeps them out of the
- * `BigInt()` call that would throw on them.
+ * Each key is ordered by `@ultimat3/entity`'s `compareByKind` under the column's declared kind —
+ * the one JS statement of how Postgres orders a column. NULL is the largest value there and equal
+ * to itself, which is what lets `Builder.toSQL()` write `asc nulls last` / `desc nulls first` and
+ * mean this function. This package used to keep a second comparator that decided by `typeof`: a
+ * `bigint()` or `decimal()` row is decimal TEXT, so `'10'` sorted before `'9'` in the in-memory
+ * source, the live matcher and the seek fallback while the database answered the other way.
  */
-function compareNumeric(left: number | bigint, right: number | bigint): number {
-  if (typeof left === 'number' && typeof right === 'number') return left - right;
-  if (typeof left === 'bigint' && typeof right === 'bigint') return sign(left, right);
-  // Widened rather than negated: `-sign(a, b)` answers `-0` for a tie, and `-0` is a different
-  // value from `0` to `Object.is` and to a caller writing `=== 0`.
-  return typeof left === 'bigint'
-    ? mixed(left, right as number)
-    : -mixed(right as bigint, left) || 0;
-}
-
-/** A bigint against a number, in that order. Whole numbers go through `BigInt` so a value past
- * 2^53 keeps its exact place; a fractional number can never equal a bigint, so comparing it as a
- * float is enough to place it. `Number.isInteger` is false for `NaN` and `±Infinity`, which is
- * what keeps them out of the `BigInt()` call that would throw on them. */
-function mixed(big: bigint, other: number): number {
-  return Number.isInteger(other) ? sign(big, BigInt(other)) : sign(Number(big), other);
-}
-
-function sign<T extends number | bigint>(left: T, right: T): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}
-
-/** A `Date` compares by instant, so two of them order by time and never by their ISO text. */
-function normalize(value: unknown): unknown {
-  return value instanceof Date ? value.getTime() : value;
-}
-
-/**
- * Equality as Postgres answers it. A number and a bigint are ONE family — an `int8` arrives as a
- * `bigint` from one driver while a filter value is usually a `number` literal, and `5n = 5` is
- * true there — so the type check that keeps `'5'` from equalling `5` treats them as one.
- */
-function same(a: unknown, b: unknown): boolean {
-  if (isNull(a) || isNull(b)) return isNull(a) && isNull(b);
-  return compareValues(a, b) === 0 && family(normalize(a)) === family(normalize(b));
-}
-
-const family = (value: unknown): string => (isNumeric(value) ? 'numeric' : typeof value);
-
-/** Row ordering under an `orderBy` list. Stable, and total when an id key is last. */
-export function compareRows(a: object, b: object, orderBy: readonly OrderKey[]): number {
+export function compareRows(
+  a: object,
+  b: object,
+  orderBy: readonly OrderKey[],
+  kindOf: KindOf,
+): number {
   for (const key of orderBy) {
-    const result = compareValues(columnOf(a, key.column), columnOf(b, key.column));
+    const result = compareByKind(
+      kindOf(key.column),
+      columnOf(a, key.column),
+      columnOf(b, key.column),
+    );
     if (result !== 0) return key.direction === 'asc' ? result : -result;
   }
   return 0;

package/src/single-answer.ts

@@ -0,0 +1,22 @@
+// Single responsibility: what a `single: true` read ANSWERS — its first row, or `X_NOT_FOUND`.
+// One rule for the route, the read's own tool and `@ultimat3/mcp`'s served tool: three copies of
+// "take the first row, refuse when there is none" are three places for one surface to drift.
+
+import { QueryRowNotFoundError } from './errors';
+import type { AnyQuery } from './query';
+import { queryName } from './read';
+
+/** The first row — what every in-process `[0]` of the same read takes — or `X_NOT_FOUND`. */
+export function oneRowOf<TRow extends object>(name: string, rows: readonly TRow[]): TRow {
+  const [row] = rows;
+  if (row === undefined) throw new QueryRowNotFoundError(name);
+  return row;
+}
+
+/**
+ * A read's answer on a surface that hands back one value: the rows of a list read, the one row of
+ * a `single: true` read. `rows` is what the read's own source executed to.
+ */
+export function readAnswer(target: AnyQuery, rows: readonly object[]): readonly object[] | object {
+  return target.single === true ? oneRowOf(queryName(target), rows) : rows;
+}

package/src/source.ts

@@ -4,9 +4,13 @@
  * app's `sql:` returns `from()` over an `@ultimat3/entity` repo, and a source only has to
  * answer these four questions.
  */
+
+import { compareByKind } from '@ultimat3/entity';
+import type { KindOf } from './column-kinds';
+import { kindsOf } from './column-kinds';
 import { QueryColumnUnselectedError } from './errors';
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
+import { compareRows, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
 /** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */
@@ -97,8 +101,13 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     return this.derive({ unsupported: [...this.unsupported, feature] });
   }
 
+  /**
+   * The window is the SMALLER of the two limits. It used to replace a declared `.limit()`, so a
+   * page wider than a "top N" served rows the read itself never would.
+   */
   seek(after: SeekKey | null, limit: number): Builder<TRow> {
-    return this.derive({ after, rowLimit: limit, totalized: true });
+    const rowLimit = this.rowLimit === null ? limit : Math.min(this.rowLimit, limit);
+    return this.derive({ after, rowLimit, totalized: true });
   }
 
   /**
@@ -134,14 +143,15 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   async execute(): Promise<readonly TRow[]> {
     const source = typeof this.rows === 'function' ? await this.rows() : this.rows;
     this.assertCarried(source);
-    let result = source.filter((row) => matchesFilters(row, this.filters));
+    const kindOf = kindsOf(this.entity);
+    let result = source.filter((row) => matchesFilters(row, this.filters, kindOf));
     const keys = this.servedOrder();
     if (keys.length > 0) {
-      result = [...result].sort((a, b) => compareRows(a, b, keys));
+      result = [...result].sort((a, b) => compareRows(a, b, keys, kindOf));
     }
     if (this.after !== null) {
       const cut = this.after;
-      result = result.filter((row) => isAfterKey(row, cut, this.order));
+      result = result.filter((row) => isAfterKey(row, cut, this.order, kindOf));
     }
     return this.rowLimit === null ? result : result.slice(0, this.rowLimit);
   }
@@ -264,7 +274,7 @@ function filterClause(filter: Filter, slot: Slot): string {
 
 /**
  * NULL's place in the ordering, written down rather than inherited. Postgres already defaults
- * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareValues`
+ * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareRows`
  * implements, so the in-memory sort, the live matcher and `seekClause` below can only agree
  * with it. Saying it out loud is what keeps a driver whose default differs from re-opening the
  * divergence, and it is what an agent reads when a nullable sort key surprises it.
@@ -312,11 +322,16 @@ interface BuilderState {
  * pagination needs the same answer when a source cannot push the seek down — a second definition
  * of "after" is how one path skips a row the other returns.
  */
-export function isAfterKey(row: object, cursor: SeekKey, order: readonly OrderKey[]): boolean {
+export function isAfterKey(
+  row: object,
+  cursor: SeekKey,
+  order: readonly OrderKey[],
+  kindOf: KindOf,
+): boolean {
   for (const [index, key] of order.entries()) {
-    const result = compareValues(columnOf(row, key.column), cursor.key[index]);
+    const result = compareByKind(kindOf(key.column), columnOf(row, key.column), cursor.key[index]);
     const signed = key.direction === 'asc' ? result : -result;
     if (signed !== 0) return signed > 0;
   }
-  return compareValues(columnOf(row, 'id'), cursor.id) > 0;
+  return compareByKind(kindOf('id'), columnOf(row, 'id'), cursor.id) > 0;
 }