@ultimat3/query 20.2.1 → 22.0.0

package/README.md

@@ -53,9 +53,44 @@ const [post] = await queries.publicPost({ slug }); // typed input, typed rows
 
 Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
 
+Every read goes through `@ultimat3/core`'s **`clientTransport`** — the one browser HTTP function,
+`As of 2026-09-22` (21.0.0). There is no `fetch` call in this package: the `fetch` option is handed
+on as the transport's `fetchImpl`. The transport owns `Accept`, the trace/budget headers, the
+principal fence, and the error decode — a non-`problem+json` failure (a gateway's HTML) is core's
+`X_CLIENT_TRANSPORT_FAILED`, a `problem+json` one is the server's own code, verbatim.
+
+### Records — `rows:` puts a read's answer in the page's store
+
+```ts
+import { entity, text, uuid } from '@ultimat3/entity';
+import { allow } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+
+const Post = entity('post', {
+  columns: { id: uuid().primaryKey(), orgId: uuid(), title: text({ max: 120 }) },
+});
+type PostRow = { id: string; orgId: string; title: string };
+declare const list: (orgId: string) => Promise<readonly PostRow[]>;
+
+export const postList = query({
+  input: t.object({ orgId: t.uuid }),
+  policy: allow('public'),
+  rows: Post.$schema, // the entity's row schema — typed against what `sql:` answers
+  sql: ({ orgId }) => from<PostRow>('posts', () => list(orgId)).where({ orgId }).orderBy('id'),
+});
+```
+
+With `rows:` naming an **entity's** row schema, the route answers `x-ultimate-records: 1` and the
+record envelope `{ data, records }` on EVERY answer — `records` is `{}` when no row came back, so
+the operation has one body shape and one OpenAPI schema; the typed client adopts
+`records` into `pageClient().store` and returns `data` — the same rows, the same type. Without it,
+or with a schema no `entity()` branded (a `t.object` look-alike, a `.pick()`ed partial), the wire
+is the bare rows, byte-identical to before. `rows:` exists because a read's `sql:` names its table
+as a STRING, so nothing else carries a schema the envelope could be derived from.
+
 ### Flight control — `createClientFlight`, opt-in
 
-A typed read is one `fetch` and nothing else until a `flight` is installed. With one, N concurrent
+A typed read is one dispatch and nothing else until a `flight` is installed. With one, N concurrent
 identical reads become ONE dispatch, a fence can retire everything issued before now, and a failure
 worth sending again is sent again on `@ultimat3/core`'s one backoff curve.
 
@@ -95,11 +130,12 @@ flight.bump();
 It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
 this package exactly as before.
 
-Bundle cost is why `ClientFlight` is a TYPE inside `client.ts` and never a value: importing
-`queryClient` alone from this package is **12,755 B** minified for the browser, and adding
-`createClientFlight` is **17,912 B**. A caller who wants a plain typed fetch pays for none of it.
-Expect ±376 B run to run — `Bun.build` 1.4.0 drops `@ultimat3/core`'s `schema-error-codes.ts` from
-some builds even though `sideEffects` names it (issue #273).
+Bundle cost is why `ClientFlight` is a TYPE inside `client.ts` and never a value. Importing
+`queryClient` alone through this package's barrel, `bun build --target=browser --minify`,
+`As of 2026-09-22`: **19,026 B** before the move to `clientTransport` (20.2.1), **24,114 B** after.
+The growth is core's transport and its graph (`client-transport.ts`, `client-problem.ts`,
+`record-envelope.ts`, `client-scope.ts`, `record-sink.ts`); `client.ts` itself got smaller. The
+12,755 B this page quoted before was no longer true at 20.2.1 — re-measure, never quote.
 
 The declaration is lifted too: `.input`, `.policy`, `.cache`, `.mcp`, `.isLive`. `sql` is not
 among them — it lives in a private store inside `read.ts`, so `sourceFor` is the only thing
@@ -479,12 +515,33 @@ router feature here.
 | `X_INPUT_INVALID` | input failed the Standard Schema | `x queries describe <name> --json` |
 | `X_QUERY_UNREGISTERED` | used before `registerQueries()` ran | register at boot |
 | `X_QUERY_FOREIGN` | a look-alike was projected as a query | declare it with `query({ … })` |
-| `X_RPC_FAILED` | `.client()` got a non-`problem+json` failure | check the gateway in front of the app |
+| `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` |
 
 Denials re-throw the policy layer's own codes and keep the surface denial on
 `QueryDeniedError.denial`, so a live socket closes with 4403 instead of guessing.
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `CursorValueUnsupportedError` | `X_CURSOR_VALUE_UNSUPPORTED` | `src/errors.ts` |
+| `MatcherUnsupportedError` | `X_MATCHER_UNSUPPORTED` | `src/errors.ts` |
+| `QueryDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
+| `QueryDeprecationInvalidError` | `X_QUERY_DEPRECATION_INVALID` | `src/errors.ts` |
+| `QueryDuplicateError` | `X_QUERY_DUPLICATE` | `src/errors.ts` |
+| `QueryForeignError` | `X_QUERY_FOREIGN` | `src/errors.ts` |
+| `QueryInputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |
+| `QueryInputUnencodableError` | `X_QUERY_INPUT_UNENCODABLE` | `src/errors.ts` |
+| `QueryNotPageableError` | `X_QUERY_NOT_PAGEABLE` | `src/errors.ts` |
+| `QueryPolicyMissingError` | `X_QUERY_POLICY_MISSING` | `src/errors.ts` |
+| `QuerySubscribesDriftError` | `X_QUERY_SUBSCRIBES_DRIFT` | `src/errors.ts` |
+| `QuerySubscribesInvalidError` | `X_QUERY_SUBSCRIBES_INVALID` | `src/errors.ts` |
+| `QueryUnregisteredError` | `X_QUERY_UNREGISTERED` | `src/errors.ts` |
+
 ## Boundaries
 
-Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`. Never imports `action`,
+Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `entity`, `http`, `policy`. Never imports `action`,
 `jobs` or `realtime` (same tier) — `realtime` consumes `LiveQuery` from here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
   },
   "files": [
     "src",
@@ -35,10 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "20.2.1",
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/http": "20.2.1",
-    "@ultimat3/policy": "20.2.1",
-    "@ultimat3/schema": "20.2.1"
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/http": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/schema": "22.0.0"
   }
 }

package/src/client.ts

@@ -4,30 +4,29 @@
  * in a Solid component rather than a 404 at runtime. Browser-safe on purpose: no
  * server imports, nothing here touches a context, a policy or a database.
  *
- * Rows arrive as JSON and are handed back as parsed, exactly as `rpc` does: a query declares no
- * output schema — row types come from the `SqlSource` its `sql:` returns — so there is nothing
- * here to rehydrate a `Date` with, and an instant reaches a caller as the ISO string
- * `JSON.stringify` wrote. A surface that formats one converts at its own edge.
+ * Every read goes through `@ultimat3/core`'s `clientTransport`, the one browser HTTP function —
+ * there is no `fetch` call here, only the injected `fetch` option handed on as `fetchImpl`. Rows
+ * are handed back as parsed: an instant reaches a caller as the ISO string `JSON.stringify` wrote,
+ * and a surface that formats one converts at its own edge. A record envelope is unwrapped by the
+ * transport, its rows adopted into the page's store, so the return type is the rows either way.
  *
  * `ClientFlight` is a TYPE here and never a value: dedup, retry, the deadline and the fence are
  * `@ultimat3/core`'s `client-flight.ts`, and a caller that never calls `createClientFlight` does
  * not pay a byte for any of them — an `import type` is erased and the value import would not be.
- * That erasure is the whole reason two islands in this repo write a bare `fetch` instead of
- * importing a typed client.
  */
 
-import type { ClientFlight, ClientRetry, WireAnswer } from '@ultimat3/core';
-import { problemOf, traceHeaders } from '@ultimat3/core';
+import type { ClientFlight, ClientRetry } from '@ultimat3/core';
+import type { FetchLike, RecordEnvelope } from '@ultimat3/core/page';
+import { clientTransport, isJsonObject } from '@ultimat3/core/page';
 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 { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 import type { Page } from './pagination';
 import type { Query } from './query';
-import { isJsonObject } from './stable';
 
-export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Core's, re-exported under the name this package always exported it by — one declaration. */
+export type { FetchLike } from '@ultimat3/core/page';
 
 export interface QueryClientOptions {
   readonly baseUrl: string;
@@ -35,8 +34,8 @@ export interface QueryClientOptions {
   readonly headers?: Readonly<Record<string, string>>;
   /**
    * Opt-in flight control for every read this client makes — `createClientFlight({ principal })`.
-   * Absent, a read is one `fetch` and nothing else, which is what every caller written before this
-   * option existed already gets.
+   * Absent, a read is one dispatch and nothing else, which is what every caller written before
+   * this option existed already gets.
    */
   readonly flight?: ClientFlight;
 }
@@ -51,6 +50,11 @@ export interface QueryCallOptions {
   readonly fresh?: boolean;
   /** Overrides the flight's retry policy for this one read. Ignored with no `flight` installed. */
   readonly retry?: ClientRetry;
+  /**
+   * The decoded record envelope, after its rows were adopted — only for a read declaring an
+   * entity's `rows:`. The store is keyed and unordered; this is where a caller reads the ORDER.
+   */
+  readonly onEnvelope?: (envelope: RecordEnvelope) => void;
 }
 
 /**
@@ -126,21 +130,25 @@ export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow exten
   name: string,
   options: QueryClientOptions,
 ): QueryClientMethod<TInput, TRow> {
-  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.
   const rows = (input: InferInput<TInput>, callOptions: QueryCallOptions = {}) =>
-    read(doFetch, base, options, name, input, callOptions) as Promise<readonly TRow[]>;
+    read(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>>;
+  ) => read(base, options, name, input, callOptions, args) as Promise<Page<TRow>>;
   return Object.assign(rows, { page });
 }
 
-async function read(
-  doFetch: FetchLike,
+/**
+ * One read, through `@ultimat3/core`'s `clientTransport` — the one browser HTTP function. It owns
+ * the wire: `Accept`, the error decode, the principal fence, and the record envelope — whose rows it adopts
+ * into the page's store before handing back `data`, so the return type here never changed. The
+ * `fetch` option is the transport's injected `fetchImpl`, never a call made here.
+ */
+function read(
   base: string,
   options: QueryClientOptions,
   name: string,
@@ -149,51 +157,19 @@ async function read(
   page?: PageControls,
 ): Promise<unknown> {
   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);
-
-  const flight = options.flight;
-  const answer =
-    flight === undefined
-      ? await dispatch(undefined)
-      : await flight.run({
-          key: flight.keyFor(url, callOptions),
-          // A caller holding its own signal owns this read's lifecycle: it is neither shared nor
-          // aborted by a fence bump, and its signal is the only one that reaches the wire.
-          abortable: callOptions.signal === undefined,
-          ...(callOptions.retry === undefined ? {} : { retry: callOptions.retry }),
-          run: dispatch,
-        });
-  // Parsed per CALLER, never once per dispatch: N joiners of one deduped read may not be handed
-  // one mutable array between them, and the shared value is the immutable body TEXT for that
-  // reason alone.
-  return JSON.parse(answer.text) as unknown;
-}
-
-/** One dispatch. Everything above it decides how many times this happens; it decides none. */
-async function fetchOnce(
-  doFetch: FetchLike,
-  url: string,
-  options: QueryClientOptions,
-  name: string,
-  signal: AbortSignal | undefined,
-): Promise<WireAnswer> {
-  const init: RequestInit = {
-    // `traceHeaders()` before the caller's, so an explicit `traceparent` still wins. Without it a
-    // service-to-service read started a fresh root trace on the other side, and "which of my
-    // downstreams is slow" was unanswerable across every Ultimate-to-Ultimate hop.
-    headers: { accept: 'application/json', ...traceHeaders(), ...options.headers },
+  return clientTransport({
     method: 'GET',
-    ...(signal === undefined ? {} : { signal }),
-  };
-
-  const response = await doFetch(url, init);
-  // Read as TEXT once: a `Response` body is a single-use stream, so the failure path and the row
-  // path cannot both have it, and a shared answer has to be something a joiner can re-read.
-  const text = await response.text();
-  if (!response.ok) throw new QueryRequestFailedError(name, response.status, problemOf(text));
-  return { status: response.status, text };
+    url: `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`,
+    // The trace and budget are the transport's, from its server-side outbound slot, placed
+    // before these so an explicit `traceparent` still wins; a browser bundles none of it.
+    ...(options.headers === undefined ? {} : { headers: options.headers }),
+    ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
+    ...(options.flight === undefined ? {} : { flight: options.flight }),
+    ...(callOptions.fresh === undefined ? {} : { fresh: callOptions.fresh }),
+    ...(callOptions.retry === undefined ? {} : { retry: callOptions.retry }),
+    ...(callOptions.onEnvelope === undefined ? {} : { onEnvelope: callOptions.onEnvelope }),
+    ...(options.fetch === undefined ? {} : { fetchImpl: options.fetch }),
+  });
 }
 
 /**

package/src/deprecation.ts

@@ -74,8 +74,3 @@ export function renderDeprecation(
   };
   return { ok: true, headers, meta };
 }
-
-/** Set on a response that already exists, so a problem document carries them too. */
-export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
-  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
-}

package/src/errors.ts

@@ -1,8 +1,8 @@
 /** Every failure @ultimat3/query can produce, one subclass per stable code. */
-import { assertNever, registerErrorCodes, retryForStatus, UltimateError } from '@ultimat3/core';
+import { assertNever, registerErrorCodes, UltimateError } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
 
-// No `docs:` on the classes below, with one exception noted at `QueryRequestFailedError`.
+// No `docs:` on the classes below.
 // `UltimateError` fills it from `describeErrorCode(code).docs`, which is `@ultimat3/core`'s
 // `ERROR_DOCS_URL` — one page for every code, never one per code, because `wiki/` is the
 // framework's only public documentation surface and a code lives there in a TABLE ROW, which has
@@ -17,6 +17,7 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_CURSOR_VALUE_UNSUPPORTED: 'a sort value cannot be carried in a cursor',
   X_MATCHER_UNSUPPORTED: 'live query shape cannot be patched incrementally',
   X_QUERY_CACHE_TTL_INVALID: 'a query declares a cache ttlMs no tier can hold',
+  X_QUERY_COLUMN_UNSELECTED: 'a read filters or sorts on a column its rows do not carry',
   X_QUERY_DEPRECATION_INVALID: 'a query declares a deprecation whose dates cannot be rendered',
   X_QUERY_DUPLICATE: 'two queries are registered under one name',
   X_QUERY_FOREIGN: 'a value that is not a query was projected as one',
@@ -29,11 +30,12 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
 };
 
 /**
- * Codes `@ultimat3/action` owns that this package only throws. Both describe an action's job —
- * enforcing an input schema, and speaking the typed RPC wire — so action declares the title and
- * query never re-declares it: two copies of a title are two titles, one of which is stale.
+ * Codes `@ultimat3/action` owns that this package only throws. It describes an action's job —
+ * enforcing an input schema — so action declares the title and query never re-declares it: two
+ * copies of a title are two titles, one of which is stale. `X_RPC_FAILED` left this list in
+ * 21.0.0: the typed read client's wire failures are `@ultimat3/core`'s `clientTransport`'s now.
  */
-export const QUERY_BORROWED_ERROR_CODES = ['X_INPUT_INVALID', 'X_RPC_FAILED'] as const;
+export const QUERY_BORROWED_ERROR_CODES = ['X_INPUT_INVALID'] as const;
 
 // One unconditional call: a presence guard would turn "another package claims one of these codes"
 // from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
@@ -239,6 +241,23 @@ export class CursorValueUnsupportedError extends UltimateError {
   }
 }
 
+/**
+ * A `where()`, `compare()` or `orderBy()` on a column the provider's rows do not carry. Absent is
+ * not "not equal": every row failed the filter and the read answered `[]` — a loader that selected
+ * `slug` and `updatedAt` and filtered on `status` built a blog with no article in it, under a
+ * green gate. Refused by name, because the repair is one edit to the loader's `select`.
+ */
+export class QueryColumnUnselectedError extends UltimateError {
+  constructor(entity: string, column: string) {
+    super({
+      code: 'X_QUERY_COLUMN_UNSELECTED',
+      cause: `the rows of "${entity}" carry no "${column}" column, so filtering or sorting on it matches nothing`,
+      fix: 'select it in the loader: db.posts.select({ slug: true, status: true, publishedAt: true }) — or drop the filter the loader already applied',
+      meta: { entity, column },
+    });
+  }
+}
+
 /** The honest fallback: the matcher refuses to guess rather than patch wrongly. */
 export class MatcherUnsupportedError extends UltimateError {
   constructor(name: string, feature: string) {
@@ -305,46 +324,3 @@ export class QueryInputInvalidError extends UltimateError {
     });
   }
 }
-
-/** The `problem+json` fields a failing read can send back. All optional: a proxy sends none. */
-export interface QueryProblem {
-  readonly code?: unknown;
-  readonly cause?: unknown;
-  readonly detail?: unknown;
-  readonly fix?: unknown;
-  readonly docs?: unknown;
-}
-
-/**
- * The typed client's failure. A `problem+json` body is re-thrown verbatim — the
- * server already said what broke and how to fix it, and inventing a second story
- * here would bury it. Anything else answered instead of the app, so it is
- * `X_RPC_FAILED` and the fix line points at the gateway.
- */
-export class QueryRequestFailedError extends UltimateError {
-  constructor(name: string, status: number, problem: QueryProblem = {}) {
-    const code = text(problem.code) ?? 'X_RPC_FAILED';
-    const served = text(problem.docs);
-    super({
-      code,
-      // The status is what says "send it again", and only where nobody has classified the code:
-      // `UltimateError` otherwise fills `retry` from `retryFor(code)`, which fails closed, so a
-      // 502 out of a typed read announced itself as `terminal` on the one field the framework
-      // promises a client never has to infer.
-      retry: retryForStatus(code, status),
-      cause: text(problem.cause) ?? text(problem.detail) ?? `${name} returned HTTP ${status}`,
-      fix:
-        text(problem.fix) ??
-        `check the gateway in front of the app, then: x queries describe ${name} --json`,
-      // The one place a `docs` is passed: the SERVER's, re-thrown verbatim beside the cause and
-      // fix it came with. An app that documents its own codes somewhere else is entitled to say
-      // so, and overwriting it with this framework's page would bury the answer. Absent, the
-      // constructor resolves `ERROR_DOCS_URL` like every other error here.
-      ...(served === undefined ? {} : { docs: served }),
-    });
-  }
-}
-
-function text(value: unknown): string | undefined {
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}

package/src/facade.ts

@@ -26,6 +26,7 @@ export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
     input: def.input,
     policy: def.policy,
     ...(def.subscribes === undefined ? {} : { subscribes: def.subscribes }),
+    ...(def.rows === undefined ? {} : { rows: def.rows }),
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),

package/src/http.ts

@@ -6,18 +6,18 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { isUltimateError } from '@ultimat3/core';
 import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
-import { json, problem, toBucket } from '@ultimat3/http';
+import { toBucket } from '@ultimat3/http';
 import { coerceQuery } from '@ultimat3/schema';
 import type { Deprecation } from './deprecation';
-import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
+import { 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';
+import { recordAnswerFor } from './record-answer';
 
 /**
  * `liveFeed` -> `GET /_x/query/live-feed`. Named for the primitive rather than spelled
@@ -30,45 +30,46 @@ export function toQueryRoute(target: AnyQuery): Route {
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first read.
   const sunsetting = deprecationHeadersFor(name, target.deprecated);
+  const answer = recordAnswerFor(target.rows);
 
   const handler = async (request: UltimateRequest): Promise<Response> => {
-    if (sunsetting !== undefined) recordDeprecatedCall('query', name);
-    try {
-      // Coerced, then validated — two different jobs, and only the first one belongs to a
-      // wire. A search string is characters, so `t.number` and `t.boolean` need the HTTP
-      // boundary's decode (`coerceQuery` never invents data: what it cannot convert it
-      // hands on untouched). VALIDATING here — `request.query(schema)` — would be the
-      // 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.
-      //
-      // 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);
-      return response;
-    } catch (error) {
-      // Framework errors carry their own code, status and fix line; anything else is
-      // a bug and belongs to the server's error boundary, not to this route.
-      if (!isUltimateError(error)) throw error;
-      const response = problem(error);
-      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
-      return response;
+    if (sunsetting !== undefined) {
+      recordDeprecatedCall('query', name);
+      // On the CONTEXT, before anything can fail: the pipeline's `response` stage merges
+      // `ctx.headers` into whatever answers — this handler's rows and the `error-map` stage's
+      // problem or error page alike. A client polling a deprecated read that is currently 403ing
+      // still has to learn the read is going away.
+      for (const [header, value] of Object.entries(sunsetting))
+        request.ctx.headers.set(header, value);
     }
+    // No `catch`: an error — framework or not — takes the path every route's error takes, the
+    // repair `@ultimat3/action`'s `toRoute` got. This answered `problem(error)` itself, so the
+    // `error-map` stage never saw it: no `onError`/`reportError` on a 5xx, no HTML error page or
+    // sign-in redirect for a browser, no `requestId`, no `Retry-After`.
+    //
+    // Coerced, then validated — two different jobs, and only the first one belongs to a
+    // wire. A search string is characters, so `t.number` and `t.boolean` need the HTTP
+    // boundary's decode (`coerceQuery` never invents data: what it cannot convert it
+    // hands on untouched). VALIDATING here — `request.query(schema)` — would be the
+    // 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.
+    //
+    // 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.
+    return answer(
+      page === undefined
+        ? await runQuery(target, input, { surface: 'http' })
+        : await target.page(input, { ...page, surface: 'http' }),
+    );
   };
 
   const meta: RouteMeta = {

package/src/index.ts

@@ -66,11 +66,11 @@ export { queryClient, queryClientMethodFor } from './client';
 /** 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';
-export type { QueryProblem } from './errors';
 export {
   CursorInvalidError,
   CursorValueUnsupportedError,
   MatcherUnsupportedError,
+  QueryColumnUnselectedError,
   QueryDeniedError,
   QueryDeprecationInvalidError,
   QueryDuplicateError,
@@ -79,7 +79,6 @@ export {
   QueryInputUnencodableError,
   QueryNotPageableError,
   QueryPolicyMissingError,
-  QueryRequestFailedError,
   QuerySubscribesDriftError,
   QuerySubscribesInvalidError,
   QueryUnregisteredError,
@@ -87,7 +86,7 @@ export {
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
 export { toQueryRoute } from './http';
 export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } from './live';
-export { advanceCursor, liveEpoch, planResume, seekOf, toLiveQuery } from './live';
+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';
@@ -96,7 +95,7 @@ export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
  * Path derivation only. There is no `toToolName`: an MCP tool is served under the export name
  * verbatim, and an exported derivation would be a second way to spell one tool.
  */
-export { derivePath, toKebabCase } from './naming';
+export { derivePath } 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.
@@ -107,7 +106,7 @@ export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
  * 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';
+export { MAX_PAGE_SIZE } 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
@@ -141,7 +140,7 @@ export type {
   QueryRateLimit,
   SourceOptions,
 } from './query';
-export { describeQuery, isQuery, nameQuery, query, queryHash } from './query';
+export { describeQuery, isQuery, query, queryHash } from './query';
 /** The one read path. `defOf` stays unexported — that is the enforcement. */
 export { queryName, runQuery, sourceFor } from './read';
 
@@ -166,7 +165,6 @@ export {
   compareValues,
   isNull,
   matchesFilter,
-  matchesFilters,
   seekKeyOf,
   totalOrder,
 } from './shape';

package/src/naming.ts

@@ -1,23 +1,13 @@
 /**
- * The one naming rule for reads: a query's export name derives its HTTP path.
- * Pure string math, so the browser client derives the same URL without importing
- * a byte of server code. Ported rather than imported from @ultimat3/action: that
- * package is the same tier, and tiers never go sideways. The MCP tool name is NOT
- * derived — it is the export name verbatim, so there is one name to call.
+ * The naming rule for reads, as this package has always exported it: a query's export name
+ * derives its HTTP path. The rule itself is `@ultimat3/core`'s `client-paths.ts` — one tier-0 file
+ * that `action`, `query` and `realtime` all read, so the path cannot be derived two ways. The MCP
+ * tool name is NOT derived — it is the export name verbatim, so there is one name to call.
  */
 
-/** Every read is served under one prefix, so a router can claim it in one rule. */
-const QUERY_PREFIX = '/_x/query';
+import { queryPath, splitWords } from '@ultimat3/core/page';
 
-/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
-export function splitWords(name: string): string[] {
-  return name
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .split(/[\s_-]+/)
-    .filter((word) => word.length > 0)
-    .map((word) => word.toLowerCase());
-}
+export { splitWords };
 
 /** `liveFeed` -> `live-feed`. */
 export function toKebabCase(name: string): string {
@@ -25,10 +15,8 @@ export function toKebabCase(name: string): string {
 }
 
 /**
- * `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. A read is a GET
- * under its own prefix so a CDN, a browser cache and a log line can all tell it
- * apart from an action's `POST /api/...` without parsing a body.
+ * `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. A read is a GET under its own
+ * prefix so a CDN, a browser cache and a log line can all tell it apart from an action's
+ * `POST /api/...` without parsing a body.
  */
-export function derivePath(name: string): string {
-  return `${QUERY_PREFIX}/${toKebabCase(name)}`;
-}
+export const derivePath: (name: string) => string = queryPath;