@ultimat3/query 22.15.0 → 24.0.0

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/sealed-shape.ts

@@ -0,0 +1,27 @@
+/**
+ * A live read may not FILTER or ORDER on a sealed column, refused at subscribe. The matcher places
+ * a change from the row the change feed carries, and that row names no sealed column — the log
+ * holds the stored string, which `@ultimat3/realtime` drops rather than forwards. So a window keyed
+ * on one could be read once and never patched: every later change would miss the filter or land
+ * at no position, silently.
+ */
+
+import { entityForTable, sealedFields } from '@ultimat3/entity';
+import { MatcherUnsupportedError } from './errors';
+import type { QueryShape } from './shape';
+
+export function assertNoSealedKey(name: string, shape: QueryShape): void {
+  // A relation no entity declares has no sealed column to name: `from('report', rows)` over a
+  // projection is common, and it is not this rule's to refuse.
+  const entity = entityForTable(shape.entity);
+  if (entity === undefined) return;
+  const sealed = new Set(sealedFields(entity).map((field) => field.property));
+  if (sealed.size === 0) return;
+  const keyed = [...shape.filters, ...shape.orderBy].find((key) => sealed.has(key.column));
+  if (keyed === undefined) return;
+  // The column's NAME, never the filter's value: that value is the secret being matched on.
+  throw new MatcherUnsupportedError(
+    name,
+    `the sealed column "${keyed.column}" in a filter or an order — a change row carries no sealed column`,
+  );
+}

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;
 };