@ultimat3/query 19.1.3 → 19.3.1

package/README.md

@@ -30,7 +30,7 @@ Every projection is a method on the query itself. A query has no `.def`.
 | `liveFeed.page({ orgId }, { first: 20, after })` | one bounded page plus the signed cursor that continues it. There is no `offset` |
 | `liveFeed.live({ orgId })` | the `LiveQuery` `@ultimat3/realtime` subscribes to, carrying the same policy object |
 | `liveFeed.tool()` | the MCP read tool, named `liveFeed`. `tool().policy === liveFeed.policy`, and it reads fresh |
-| `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways |
+| `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways. `.page(input, { first, after })` on the same method reads one page over the wire |
 | `liveFeed.describe()` | the manifest row |
 
 The route on the other end of that client is `toQueryRoute(liveFeed)`, and — `As of 2026-08` —
@@ -132,6 +132,8 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `mcp-tool.ts` | the MCP read descriptor |
 | `client.ts` | the typed read client (browser-safe) |
 | `http.ts` | the route projection — `GET /_x/query/<kebab>`, the URL the client derives |
+| `page-controls.ts` | `_first` / `_after` — the two search-string keys that page the route, split out and judged at the wire; `MAX_PAGE_SIZE` |
+| `openapi.ts` | the read half of `openapi.json` — one `GET` path item per registered query |
 | `naming.ts` | export name → wire path. The MCP tool name is the export name verbatim |
 | `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
 | `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
@@ -267,6 +269,35 @@ HMAC-signed, and bound to one query + arguments — a cursor from another query
 `query.page(input, { first, after })` is the only way to ask for one — `paginate` backs it and is
 not exported, because a page is the read's own answer rather than an imported helper.
 
+### The same page over HTTP — `?_first=` and `?_after=`
+
+The route reads two controls off the search string BEFORE the schema sees it, and with either
+present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, endCursor,
+hasNextPage }`, the same names, so a cursor read off the wire and one read off a direct call are
+one string in one field. Without a control the answer is the bare array it has always been, so a
+client written before the controls existed keeps reading rows. `As of 2026-09`; until then the
+route had no envelope, and a query over a paged external source carried its page marker on a row
+(an `olderCursor` column on the oldest message), which is a cursor on the wrong side of the shape.
+
+```
+GET /_x/query/live-feed?orgId=…&_first=20             → { rows, endCursor, hasNextPage }
+GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page
+GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (unchanged)
+```
+
+| Rule | Why it is that way |
+|---|---|
+| the keys are `_first` and `_after`, not `first` and `after` | the search string is ALSO the input, and an input member named `first` was legal on every release before this one — a listing's page-size field is the natural name for it. Reserving the bare names would have refused every such declaration at `query()`, in a minor. The underscore is the framework's own mark, as `/_x/` is |
+| a declaration naming either is refused at `query()` | `X_QUERY_INPUT_UNENCODABLE`, in the declaring file: the route strips the key before the schema runs, so the field could never be filled |
+| `_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 |
+| 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.
+
 The codec lives in `@ultimat3/core`, not here: `encodeCursor`, `decodeCursor`,
 `configureCursorSigning` (set the signing secret once at boot; rotating it invalidates every
 open cursor) and `usesDevCursorSecret` are all imported from there. `As of 2026-08`, `x doctor`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "19.1.3",
+  "version": "19.3.1",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -35,10 +35,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "19.1.3",
-    "@ultimat3/core": "19.1.3",
-    "@ultimat3/http": "19.1.3",
-    "@ultimat3/policy": "19.1.3",
-    "@ultimat3/schema": "19.1.3"
+    "@ultimat3/cache": "19.3.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/http": "19.3.1",
+    "@ultimat3/policy": "19.3.1",
+    "@ultimat3/schema": "19.3.1"
   }
 }

package/src/client.ts

@@ -21,6 +21,9 @@ import { problemOf, traceHeaders } from '@ultimat3/core';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
 import { QueryRequestFailedError } from './errors';
 import { derivePath } from './naming';
+import type { PageControls } from './page-controls';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
+import type { Page } from './pagination';
 import type { Query } from './query';
 import { isJsonObject } from './stable';
 
@@ -50,11 +53,23 @@ export interface QueryCallOptions {
   readonly retry?: ClientRetry;
 }
 
-/** `feed({ orgId })` with the input schema and the row type both inferred. */
-export type QueryClientMethod<TInput extends StandardSchemaV1, TRow extends object> = (
-  input: InferInput<TInput>,
-  options?: QueryCallOptions,
-) => Promise<readonly TRow[]>;
+/**
+ * `feed({ orgId })` with the input schema and the row type both inferred — and `feed.page(...)`,
+ * the same read as one bounded page.
+ *
+ * `page` rides ON the method rather than beside it because the method is what a `queryClient` map
+ * hands out per name: `queries.feed.page({ orgId }, { first: 20 })` needs no second map and no
+ * second derivation of the URL. Its args are `PaginateArgs` with the server-side options gone —
+ * the browser has no `ctx` and no `actor` to hand over; the route decides both.
+ */
+export interface QueryClientMethod<TInput extends StandardSchemaV1, TRow extends object> {
+  (input: InferInput<TInput>, options?: QueryCallOptions): Promise<readonly TRow[]>;
+  page(
+    input: InferInput<TInput>,
+    args: PageControls,
+    options?: QueryCallOptions,
+  ): Promise<Page<TRow>>;
+}
 
 /**
  * Loose constraint on purpose: a map of concrete `Query<TInput, TRow>` values must be
@@ -114,8 +129,14 @@ export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow exten
   const doFetch: FetchLike = options.fetch ?? ((input, init) => fetch(input, init));
   const base = options.baseUrl.replace(/\/+$/, '');
   // Erased at the wire seam; the row type is this query's by construction.
-  return (input, callOptions = {}) =>
+  const rows = (input: InferInput<TInput>, callOptions: QueryCallOptions = {}) =>
     read(doFetch, base, options, name, input, callOptions) as Promise<readonly TRow[]>;
+  const page = (
+    input: InferInput<TInput>,
+    args: PageControls,
+    callOptions: QueryCallOptions = {},
+  ) => read(doFetch, base, options, name, input, callOptions, args) as Promise<Page<TRow>>;
+  return Object.assign(rows, { page });
 }
 
 async function read(
@@ -125,8 +146,9 @@ async function read(
   name: string,
   input: unknown,
   callOptions: QueryCallOptions,
+  page?: PageControls,
 ): Promise<unknown> {
-  const search = searchOf(input);
+  const search = searchOf(input, page);
   const url = `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`;
   const dispatch = (signal: AbortSignal | undefined): Promise<WireAnswer> =>
     fetchOnce(doFetch, url, options, name, signal ?? callOptions.signal);
@@ -177,16 +199,25 @@ async function fetchOnce(
 /**
  * Input as a query string. Keys are sorted so the same input always produces the
  * same URL — a GET is a cache key, and an unstable one caches nothing.
+ *
+ * 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.
  */
-function searchOf(input: unknown): string {
-  if (!isJsonObject(input)) return '';
+function searchOf(input: unknown, page?: PageControls): string {
   const params = new URLSearchParams();
-  for (const key of Object.keys(input).sort()) {
-    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));
+  if (isJsonObject(input)) {
+    for (const key of Object.keys(input).sort()) {
+      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));
+      }
     }
   }
+  if (page !== undefined) {
+    params.append(PAGE_FIRST_KEY, String(page.first));
+    if (page.after !== undefined) params.append(PAGE_AFTER_KEY, page.after);
+  }
   return params.toString();
 }

package/src/http.ts

@@ -14,6 +14,7 @@ import type { Deprecation } from './deprecation';
 import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { QueryDeprecationInvalidError } from './errors';
 import { derivePath } from './naming';
+import { pageControlsOf } from './page-controls';
 import { admitsAnonymous, policyCapability } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, runQuery } from './read';
@@ -40,8 +41,22 @@ export function toQueryRoute(target: AnyQuery): Route {
       // second parser: the same read would answer `X_BODY_INVALID` where every other
       // surface answers `X_INPUT_INVALID` with the line that prints its schema. `runQuery`
       // is the one that decides, exactly as it does for a direct server call.
-      const input = coerceQuery(target.input, request.queryRaw());
-      const response = json(await runQuery(target, input, { surface: 'http' }));
+      //
+      // 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);
+      // With a page control the answer is the `Page` envelope `query.page()` answers a server
+      // caller with — `{ rows, endCursor, hasNextPage }`, the same names, so a cursor read off the
+      // wire and one read off a direct call are the same string in the same field. Without one the
+      // answer is the bare array it has always been: every client written before the controls
+      // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker
+      // has no business being.
+      const response = json(
+        page === undefined
+          ? await runQuery(target, input, { surface: 'http' })
+          : await target.page(input, { ...page, surface: 'http' }),
+      );
       // On the failure path too, below: a client polling a deprecated read that is currently
       // 403ing still has to learn the read is going away.
       if (sunsetting !== undefined) applyHeaders(response, sunsetting);

package/src/index.ts

@@ -97,6 +97,17 @@ export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
  * verbatim, and an exported derivation would be a second way to spell one tool.
  */
 export { derivePath, toKebabCase } from './naming';
+/**
+ * The read half of `openapi.json`. `@ultimat3/cli` merges these paths into `@ultimat3/action`'s
+ * `buildOpenApi` document — the two packages are one tier and cannot compose each other.
+ */
+export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
+/**
+ * The two search-string keys that page `GET /_x/query/<name>` — `_first` and `_after` — and the
+ * shape the typed client's `.page()` takes. `MAX_PAGE_SIZE` is the bound both ends check.
+ */
+export type { PageControls } from './page-controls';
+export { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 /**
  * The shapes `query.page(input, { first, after })` takes and answers with. `paginate` itself is
  * deliberately unexported: a page is the read's own answer, and a second, importable way to ask

package/src/input-shape.ts

@@ -17,6 +17,7 @@
 
 import { type SchemaNode, tryIntrospect } from '@ultimat3/schema';
 import { QueryInputUnencodableError } from './errors';
+import { PAGE_CONTROL_KEYS } from './page-controls';
 
 /** Node kinds whose value is a structure, not characters. `money` is `{ minor, currency }`. */
 const STRUCTURAL = new Set(['object', 'record', 'money']);
@@ -27,6 +28,12 @@ const STRUCTURAL = new Set(['object', 'record', 'money']);
  */
 function unencodable(node: SchemaNode): string | undefined {
   for (const [key, child] of Object.entries(node.properties ?? {})) {
+    // The route reads `_first` and `_after` OFF the search string before the schema sees it, so a
+    // declaration naming either is a field no request can ever fill — refused where it is written,
+    // exactly like a nested object, and for the same reason: the wire cannot carry it.
+    if (PAGE_CONTROL_KEYS.includes(key)) {
+      return `${key} is reserved — the route reads it as a page control (see query.page())`;
+    }
     // Required AND nullable: `searchOf` sends nothing for a `null`, and absence is what the far
     // side then sees — so the value the caller explicitly chose fails validation on arrival.
     // Optional or defaulted, absence is already the schema's own answer and nothing is lost.

package/src/openapi.ts

@@ -0,0 +1,156 @@
+/**
+ * Projection: a query's route as an OpenAPI 3.1 path item, so `openapi.json` — the file `x verify`
+ * diffs and the typed client is generated from — documents the READ half of the API. It documented
+ * only the write half until 2026-09: `buildOpenApi` in `@ultimat3/action` walks the action
+ * registry, and every `GET /_x/query/<name>` was served by `api-routes.ts` and published nowhere,
+ * which is why the page controls this route now reads had no document to be written into.
+ *
+ * Ported beside `@ultimat3/action`'s rather than composed with it: both packages are tier 3 and
+ * tiers never go sideways, so the CLI — the one caller that writes the file — merges the two
+ * `paths` maps (`packages/cli/src/app-openapi.ts`). The component names this file references are
+ * restated, and pinned in `openapi.test.ts` against what the action side emits.
+ *
+ * DETERMINISM IS A HARD REQUIREMENT, as it is one package over: `serializeOpenApi` sorts keys at
+ * every depth, so only the ARRAYS here need an order — parameters by name, then the two page
+ * controls — and nothing reads the clock, the environment or a random source.
+ */
+
+import { tagKeys } from '@ultimat3/cache';
+import type { SchemaNode } from '@ultimat3/schema';
+import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
+import { isExposed } from './mcp-tool';
+import { derivePath } from './naming';
+import { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
+import { policyCapability } from './policy-gate';
+import type { AnyQuery } from './query';
+import { queryName } from './read';
+import { listQueries } from './registry';
+
+/**
+ * `@ultimat3/action`'s `PROBLEM_SCHEMA_NAME`, restated: the CLI merges this file's paths into that
+ * package's document, which is what puts the component the `$ref` names into `components`.
+ */
+const PROBLEM_SCHEMA_REF = '#/components/schemas/Problem';
+
+/** One tag for every read: an action is tagged by its resource, a read by what it is. */
+const QUERY_TAG = 'query';
+
+export type OpenApiPathItem = Record<string, unknown>;
+
+/** `{ [path]: { get: operation } }` for every registered read, name-sorted like the actions. */
+export function queryOpenApiPaths(
+  queries: readonly AnyQuery[] = listQueries(),
+): Record<string, OpenApiPathItem> {
+  const paths: Record<string, OpenApiPathItem> = {};
+  for (const target of [...queries].sort(compareByName)) {
+    paths[derivePath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
+  }
+  return paths;
+}
+
+/**
+ * The GET operation for one read. The input's members are `in: query` parameters — a read is
+ * served from its search string (`input-shape.ts` is what guarantees every member fits one) — and
+ * the two page controls follow them, on every read, because every read pages through the same
+ * route code. `required` follows the schema: optional or defaulted is not required.
+ */
+export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknown> {
+  const name = queryName(target);
+  return {
+    operationId: name,
+    tags: [QUERY_TAG],
+    summary: target.mcp?.description ?? name,
+    ...(target.deprecated === undefined ? {} : { deprecated: true }),
+    parameters: [...inputParameters(target.input), ...PAGE_PARAMETERS],
+    responses: {
+      '200': {
+        description: 'ok',
+        content: {
+          'application/json': {
+            // Two shapes, decided by the request: the bare rows every client read before the
+            // controls existed, and the page envelope when `_first` is sent. `oneOf` and not a
+            // second operation — it is one route, one policy evaluation, one URL prefix.
+            schema: {
+              oneOf: [
+                { type: 'array', items: {} },
+                {
+                  type: 'object',
+                  required: ['rows', 'endCursor', 'hasNextPage'],
+                  properties: {
+                    rows: { type: 'array', items: {} },
+                    endCursor: { type: ['string', 'null'] },
+                    hasNextPage: { type: 'boolean' },
+                  },
+                },
+              ],
+            },
+          },
+        },
+      },
+      // `X_INPUT_INVALID` is the search string failing the read's own schema, or a page control
+      // outside its bound; `X_CURSOR_INVALID` is an `_after` that is not one of this read's. Both
+      // are the caller's to repair, which is what 400 says.
+      '400': problemResponse('X_INPUT_INVALID or X_CURSOR_INVALID'),
+      '403': problemResponse('policy denied'),
+    },
+    'x-ultimate': {
+      capability: policyCapability(target.policy),
+      live: target.isLive,
+      cacheTags: tagKeys(target.cache?.tags ?? []),
+      // The same rule `toMcpTool` and the action side apply: a tool is advertised only where the
+      // MCP catalog lists one, under the export name verbatim (`mcp-tool.ts`).
+      tool: isExposed(target) ? name : null,
+    },
+  };
+}
+
+/** The two controls, spelled from `page-controls.ts` so the document cannot drift from the route. */
+const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
+  {
+    name: PAGE_FIRST_KEY,
+    in: 'query',
+    required: false,
+    description: `page size; present, the response is the page envelope rather than the bare rows (1 to ${MAX_PAGE_SIZE})`,
+    schema: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE },
+  },
+  {
+    name: PAGE_AFTER_KEY,
+    in: 'query',
+    required: false,
+    description: `the endCursor a previous page answered; needs ${PAGE_FIRST_KEY}`,
+    schema: { type: 'string' },
+  },
+];
+
+/**
+ * A member per declared property, name-sorted. A schema this package cannot introspect — a
+ * foreign Standard Schema, the seam `configureSchemaProvider` exists for — publishes no
+ * parameters rather than guessed ones, the same answer `assertEncodableInput` gives it.
+ */
+function inputParameters(input: unknown): readonly Record<string, unknown>[] {
+  const node = tryIntrospect(input);
+  if (node?.properties === undefined) return [];
+  return Object.entries(node.properties)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([key, child]) => parameterOf(key, child));
+}
+
+function parameterOf(name: string, node: SchemaNode): Record<string, unknown> {
+  return {
+    name,
+    in: 'query',
+    required: node.optional !== true && node.hasDefault !== true,
+    schema: nodeToJsonSchema(node),
+  };
+}
+
+function problemResponse(description: string): Record<string, unknown> {
+  return {
+    description,
+    content: { 'application/problem+json': { schema: { $ref: PROBLEM_SCHEMA_REF } } },
+  };
+}
+
+function compareByName(a: AnyQuery, b: AnyQuery): number {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}

package/src/page-controls.ts

@@ -0,0 +1,112 @@
+// Single responsibility: the two search-string keys that turn `GET /_x/query/<name>` into a page,
+// and what a value under either has to look like. A LEAF on purpose: `client.ts` is browser-safe
+// and `openapi.ts` is a projection, and both spell these names — one file, or the client encodes a
+// key the route does not read.
+//
+// The keys are `_first` and `_after`, not `first` and `after`. `PaginateArgs` spells them bare,
+// and the route could have too — except a search string is ALSO the query's input, and an input
+// field named `first` was legal on every release before this one (`http.test.ts` declares one,
+// and a listing's page-size field is the most natural name for it). Reserving the bare names would
+// have turned every such declaration into a refusal at `query()`, in a minor. The underscore is
+// the framework's own namespace mark — the route lives under `/_x/` for the same reason — and
+// `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
+
+import { QueryInputInvalidError } from './errors';
+
+/** `?_first=20` — the page size. Present is what makes the route answer a `Page`. */
+export const PAGE_FIRST_KEY = '_first';
+/** `?_after=<cursor>` — the signed cursor the previous page's `endCursor` carried. */
+export const PAGE_AFTER_KEY = '_after';
+export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_KEY];
+
+/**
+ * The largest page a read will serve. A TWIN of `@ultimat3/entity`'s `MAX_PAGE_SIZE` — this
+ * package holds no dependency on that one, the same compromise `naming.ts` and `deprecation.ts`
+ * are ported under — and it exists for the same reason: `first` reaches `paginate` straight from
+ * an action's input or a route parameter, so `args.first + 1` bound whatever a client sent and one
+ * request could ask for five million rows. Lives here rather than in `pagination.ts` because the
+ * route validates against it BEFORE `paginate` runs — see `pageControlsOf`.
+ */
+export const MAX_PAGE_SIZE = 10_000;
+
+/** What the route hands `query.page()` — `PaginateArgs` minus the server-side options. */
+export interface PageControls {
+  readonly first: number;
+  readonly after?: string;
+}
+
+/** The values a search string decodes to: `@ultimat3/http`'s `QueryValues`, restated as a leaf. */
+export type SearchValues = Readonly<Record<string, string | readonly string[] | undefined>>;
+
+export interface SplitSearch {
+  /** The search string with both controls removed — what the query's own schema sees. */
+  readonly input: Record<string, string | readonly string[] | undefined>;
+  /** `undefined` when neither control was sent, so the route answers a bare array as it always has. */
+  readonly page: PageControls | undefined;
+}
+
+/**
+ * Whole digits only — `Number('1e3')` is 1000 and `Number(' 2')` is 2, and a page size that
+ * needs a lenient parse is a page size nobody meant.
+ */
+const WHOLE_NUMBER = /^\d+$/;
+
+/**
+ * Splits the two controls out of a search string, judged at the WIRE and never left to `paginate`:
+ * that function `assert`s its bound, which is `X_INVARIANT` — a 500, blaming the server for a
+ * number the caller typed. Here every refusal is the query's own `X_INPUT_INVALID`, a 400 whose
+ * fix line prints the schema, exactly what a bad `orgId` on the same URL already answers.
+ *
+ * The cursor's VALIDITY is not judged here. `decodeCursor` owns that — `X_CURSOR_INVALID`, also a
+ * 400 — and a second reader of the codec's envelope would be a second opinion about what a cursor
+ * is. Only its shape as a search value is checked: one string, non-empty.
+ */
+export function pageControlsOf(name: string, values: SearchValues): SplitSearch {
+  // `Object.create(null)`, never `{}`, and the same rule `@ultimat3/http`'s `collectFields`
+  // follows: a repeated `?__proto__=a&__proto__=b` arrives as an ARRAY, which is exactly what
+  // `Object.prototype.__proto__`'s setter accepts — one assignment and this object's prototype IS
+  // that array, so `'length' in input` answers true about a field nobody sent. A null prototype
+  // has no such accessor, so the key is ordinary data on the way to the schema.
+  const input: Record<string, string | readonly string[] | undefined> = Object.create(null);
+  for (const [key, value] of Object.entries(values)) {
+    if (!PAGE_CONTROL_KEYS.includes(key)) input[key] = value;
+  }
+  const first = values[PAGE_FIRST_KEY];
+  const after = values[PAGE_AFTER_KEY];
+  if (first === undefined && after === undefined) return { input, page: undefined };
+  if (first === undefined) {
+    throw new QueryInputInvalidError(
+      name,
+      `${PAGE_AFTER_KEY} was sent without ${PAGE_FIRST_KEY} — a cursor continues a page, so the page size is what names one`,
+    );
+  }
+  const size = single(name, PAGE_FIRST_KEY, first);
+  if (!WHOLE_NUMBER.test(size) || Number(size) < 1 || Number(size) > MAX_PAGE_SIZE) {
+    throw new QueryInputInvalidError(
+      name,
+      `${PAGE_FIRST_KEY} must be a whole number of rows between 1 and ${MAX_PAGE_SIZE}, got "${size}"`,
+    );
+  }
+  if (after === undefined) return { input, page: { first: Number(size) } };
+  const cursor = single(name, PAGE_AFTER_KEY, after);
+  if (cursor.length === 0) {
+    throw new QueryInputInvalidError(
+      name,
+      `${PAGE_AFTER_KEY} is empty — omit it for the first page, or send the endCursor the previous page answered`,
+    );
+  }
+  return { input, page: { first: Number(size), after: cursor } };
+}
+
+/**
+ * A control sent twice is refused rather than resolved. `coerceQuery` takes the LAST repeat of a
+ * declared scalar, but a page size is not a filter: two of them is two different pages asked for
+ * in one request, and answering either one silently is the wrong half of a guess.
+ */
+function single(name: string, key: string, value: string | readonly string[]): string {
+  if (typeof value === 'string') return value;
+  throw new QueryInputInvalidError(
+    name,
+    `${key} was sent ${value.length} times — a page has one size and one cursor`,
+  );
+}

package/src/pagination.ts

@@ -12,6 +12,7 @@
 import { assert, decodeCursor, encodeCursor } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { reviveSortKey, serializeSortValue } from './cursor-value';
+import { MAX_PAGE_SIZE } from './page-controls';
 import type { Query, SourceOptions } from './query';
 import { queryHash, queryName, sourceFor } from './query';
 import type { QueryShape, SeekKey } from './shape';
@@ -30,15 +31,6 @@ export interface PaginateArgs extends SourceOptions {
   readonly after?: string;
 }
 
-/**
- * The largest page a read will serve. A TWIN of `@ultimat3/entity`'s `MAX_PAGE_SIZE` — this
- * package holds no dependency on that one, the same compromise `naming.ts` and `deprecation.ts`
- * are ported under — and it exists for the same reason: `first` reaches here straight from an
- * action's input or a route parameter, so `args.first + 1` bound whatever a client sent and one
- * request could ask for five million rows.
- */
-const MAX_PAGE_SIZE = 10_000;
-
 /**
  * One page. Push-down when the source implements `seek()`; otherwise the rows are
  * sliced after execution and the source is doing more work than it should.
@@ -66,6 +58,8 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   const base = await sourceFor(target, input, args);
   const shape = base.shape();
 
+  // `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;
   const source: SqlSource<object> = base.seek === undefined ? base : base.seek(after, window);