@ultimat3/query 23.0.0 → 25.0.0

package/src/read.ts

@@ -7,9 +7,10 @@
 
 import type { Ctx } from '@ultimat3/core';
 import {
+  actorOf,
   anonymousActor,
   assert,
-  createContext,
+  ctxOf,
   finiteOption,
   logger,
   runWithContext,
@@ -20,6 +21,8 @@ import {
 } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { formatPath, validateAsync } from '@ultimat3/schema';
+import type { ReadAudit, ReadTrace } from './audit-gate';
+import { audited, auditedBuild, readAuditFor } from './audit-gate';
 import {
   cacheKeyFor,
   DEFAULT_READ_CACHE_TTL_MS,
@@ -29,8 +32,9 @@ import {
   readThrough,
 } from './cache';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
-import { actorOf, guard, guardBeforeInput } from './policy-gate';
+import { guardQuery, guardQueryBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
+import { spendReadLimit } from './rate-limit-gate';
 import type { SqlSource } from './source';
 
 /**
@@ -84,7 +88,12 @@ export function runQuery(
   raw: unknown,
   options: QueryOptions = {},
 ): Promise<readonly object[]> {
-  return asActor(options, (ctx) => readRows(target, raw, ctx, options));
+  return asActor(options, (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    return audit === null
+      ? readRows(target, raw, ctx, options, null)
+      : audited(audit, () => readRows(target, raw, ctx, options, audit.trace));
+  });
 }
 
 /**
@@ -97,7 +106,45 @@ export function sourceFor(
   raw: unknown,
   options: SourceOptions = {},
 ): Promise<SqlSource<object>> {
-  return asActor(options, (ctx) => buildSource(target, raw, ctx, options));
+  return asActor(options, (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    // A source handed out is executed by its caller — `@ultimat3/mcp`'s served tool among them —
+    // so an audited read records per `execute()`, and a build that refuses records here.
+    return audit === null
+      ? buildSource(target, raw, ctx, options, null)
+      : auditedBuild(audit, () => buildSource(target, raw, ctx, options, audit.trace));
+  });
+}
+
+/**
+ * One whole call over a built source, for a projection inside this package whose call is more
+ * than one `execute()` — `paginate`, which may answer a spent limit without executing at all. The
+ * record covers the build and `use` together, so the call is recorded exactly once either way.
+ */
+export function readCall<T>(
+  target: AnyQuery,
+  raw: unknown,
+  options: SourceOptions,
+  use: (source: SqlSource<object>) => Promise<T>,
+): Promise<T> {
+  return asActor(options, async (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    if (audit === null) return use(await buildSource(target, raw, ctx, options, null));
+    return audited(audit, async () =>
+      use(await buildSource(target, raw, ctx, options, audit.trace)),
+    );
+  });
+}
+
+/** Resolved before the parse, so an audited read with no sink refuses while it has read nothing. */
+function auditFor(target: AnyQuery, ctx: Ctx, options: SourceOptions): ReadAudit | null {
+  return readAuditFor(
+    defOf(target).audit,
+    options.unenforced,
+    queryName(target),
+    ctx,
+    options.surface ?? 'server',
+  );
 }
 
 /**
@@ -118,7 +165,7 @@ function asActor<T>(options: QueryOptions, run: (ctx: Ctx) => Promise<T>): Promi
   const inChild = (): Promise<T> => run(useContext());
   const base = options.ctx ?? tryUseContext();
   return base === undefined
-    ? runWithContext(createContext(patch), inChild)
+    ? runWithContext(ctxOf(patch), inChild)
     : runWithContext(base, () => withChildContext(patch, inChild));
 }
 
@@ -136,6 +183,7 @@ function readRows(
   raw: unknown,
   ctx: Ctx,
   options: QueryOptions,
+  trace: ReadTrace | null,
 ): Promise<readonly object[]> {
   const name = queryName(target);
   return withSpan(`query.${name}`, async (span) => {
@@ -150,7 +198,7 @@ function readRows(
       // read is filled — and which of the two a slow read took is the first thing to ask.
       'ultimate.cached': defOf(target).cache !== undefined,
     });
-    const rows = await readRowsIn(target, raw, ctx, options);
+    const rows = await readRowsIn(target, raw, ctx, options, trace);
     span.setAttribute('ultimate.rows', rows.length);
     return rows;
   });
@@ -161,11 +209,18 @@ async function readRowsIn(
   raw: unknown,
   ctx: Ctx,
   options: QueryOptions,
+  trace: ReadTrace | null,
 ): Promise<readonly object[]> {
   const def = defOf(target);
   const name = queryName(target);
-  const source = await buildSource(target, raw, ctx, options);
-  const read = (): Promise<readonly object[]> => source.execute();
+  const source = await buildSource(target, raw, ctx, options, trace);
+  // Whether THIS call executed, for the audit record: a memo or tier hit never calls `read`, and
+  // its record says so (`replayed: true`) rather than being skipped.
+  if (trace !== null) trace.replayed = true;
+  const read = (): Promise<readonly object[]> => {
+    if (trace !== null) trace.replayed = false;
+    return source.execute();
+  };
   // The source came from this query's own `sql()`, so its rows are TRow throughout —
   // which is what the typed overload above states, and this body never has to assert.
   const tags = def.cache?.tags ?? [];
@@ -201,6 +256,7 @@ async function buildSource(
   raw: unknown,
   ctx: Ctx,
   options: SourceOptions,
+  trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
   const def = defOf(target);
   const name = queryName(target);
@@ -208,15 +264,36 @@ async function buildSource(
   // The actor half of the policy first, exactly as `invoke` does it: a reader refused whatever
   // they send learns nothing about this read's input schema from an `X_INPUT_INVALID`.
   if (unenforced === undefined) {
-    guardBeforeInput(
-      def.policy,
-      { actor: actorOf(ctx), ctx, query: name },
-      options.surface ?? 'server',
-    );
+    try {
+      guardQueryBeforeInput(
+        def.policy,
+        { actor: actorOf(ctx), ctx, query: name },
+        options.surface ?? 'server',
+      );
+    } catch (denial) {
+      // The record still names what was attempted, as an action's does: the denial is already
+      // decided, so parsing now tells the CALLER nothing, and an unparseable payload is no input.
+      if (trace !== null) trace.input = await parsedOrNothing(def.input, raw);
+      throw denial;
+    }
+  }
+  // The ONE place a read's declared `rateLimit:` is spent for every surface it runs on — the
+  // route, a paged read, the MCP tool. After the actor half (a refused reader learns that, not a
+  // 429), before the parse and `sql()`, which are the work being limited. An unenforced build has
+  // no caller to charge: the shared live window spends per subscriber (`spendQueryLimit`).
+  if (unenforced === undefined) {
+    await spendReadLimit(name, def.rateLimit, {
+      actor: ctx.actor,
+      surface: options.surface ?? 'server',
+      clientAddress: options.clientAddress,
+      onRateLimit: options.onRateLimit,
+      nowMs: ctx.now().getTime(),
+    });
   }
   const input = await validate(def.input, raw, name);
+  if (trace !== null) trace.input = input;
   if (unenforced === undefined) {
-    guard(
+    guardQuery(
       def.policy,
       { actor: actorOf(ctx), input, ctx, query: name },
       options.surface ?? 'server',
@@ -244,6 +321,12 @@ async function buildSource(
   return options.surface === 'live' && source.total !== undefined ? source.total() : source;
 }
 
+/** The parse without the refusal — only for the record of a read already refused on other grounds. */
+async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  return result.issues === undefined ? result.value : undefined;
+}
+
 async function validate(schema: StandardSchemaV1, raw: unknown, name: string): Promise<unknown> {
   const result = await validateAsync(schema, raw);
   if (result.issues !== undefined) {

package/src/record-answer.ts

@@ -10,7 +10,7 @@
 import type { RecordRows, Row } from '@ultimat3/core';
 import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
 import { hasEntityRows, rowsOf } from '@ultimat3/entity';
-import { json } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Page } from './pagination';
 
@@ -23,10 +23,12 @@ export type RecordAnswer = (answer: readonly object[] | Page<object>) => Respons
  * `Page` — is the route's, not the declaration's.
  */
 export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswer {
-  if (!answersRecords(rows)) return (answer) => json(answer);
+  if (!answersRecords(rows)) return (answer) => jsonResponse(answer);
   return (answer) => {
     const records = collect(rows, isPage(answer) ? answer.rows : answer);
-    return json(encodeRecordEnvelope(answer, records), { headers: { [RECORDS_HEADER]: '1' } });
+    return jsonResponse(encodeRecordEnvelope(answer, records), {
+      headers: { [RECORDS_HEADER]: '1' },
+    });
   };
 }
 
@@ -36,9 +38,11 @@ export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswe
  * answers for a single output, so the transport unwraps both the same way.
  */
 export function recordRowAnswerFor(rows: StandardSchemaV1 | undefined): (row: object) => Response {
-  if (!answersRecords(rows)) return (row) => json(row);
+  if (!answersRecords(rows)) return (row) => jsonResponse(row);
   return (row) =>
-    json(encodeRecordEnvelope(row, collect(rows, [row])), { headers: { [RECORDS_HEADER]: '1' } });
+    jsonResponse(encodeRecordEnvelope(row, collect(rows, [row])), {
+      headers: { [RECORDS_HEADER]: '1' },
+    });
 }
 
 /** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */

package/src/registry.ts

@@ -64,6 +64,6 @@ export function describeQueries(): readonly QueryDescriptor[] {
 }
 
 /** Test-only. Production registers once at boot. */
-export function resetRegistry(): void {
+export function resetQueries(): void {
   registry.clear();
 }

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, type McpExposureDeclaration } 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 type { QueryCache, QueryRateLimit } 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. */
@@ -60,7 +60,7 @@ export interface SearchDef<S extends Shape, Row extends object> {
   readonly termMax?: number;
   readonly page?: SearchPage;
   readonly cache?: QueryCache;
-  readonly mcp?: QueryMcp;
+  readonly mcp?: McpExposureDeclaration;
   readonly rateLimit?: QueryRateLimit;
 }
 
@@ -84,12 +84,16 @@ const limitSchema = (max: number, fallback: number) =>
  * `SqlSource` is handed a `SeekKey` (the previous page's sort VALUES) and the chain wants its own
  * 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`.
+ * `hasMore: 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 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
+ * used to serve `first` rows, mint an `nextCursor` and report `hasMore: true` — a connection
  * protocol saying "call me again with this" for a call the cursor assert is guaranteed to throw on.
  * A first repair demanded `first >= limit` and refused the window itself, which refuses the
  * framework's OWN default pair: `limit` defaults to 20 and `first` arrives from a client
@@ -99,7 +103,7 @@ const limitSchema = (max: number, fallback: number) =>
  *
  * So the condition is the one thing that is actually wrong: the read answered MORE rows than the
  * window carries, and this seam has no second page to put the rest on. Below that, the page is
- * whole and `hasNextPage` is false by construction — the true stop signal, and no cursor is ever
+ * whole and `hasMore` is false by construction — the true stop signal, and no cursor is ever
  * handed back that a second call is guaranteed to refuse.
  *
  * **`seek` narrows the WINDOW and never the ORDER, and that is the whole reason this wrapper takes a
@@ -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`,
-    );
-    // `paginate` asks for `first + 1` — the extra row IS `hasNextPage` — so the window it names is
+    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 `hasMore` — 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,14 +149,15 @@ 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`. */
+  /** Rows `paginate` will serve. It fetched one more, to decide `hasMore`. */
   first: number,
 ): SqlSource<Row> => {
   const windowed = base.limit(first + 1);
@@ -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;
+}