@ultimat3/query 20.2.1 → 21.0.0

package/CLAUDE.md

@@ -17,9 +17,10 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `facade.ts` | the fluent surface — binds each projection to the query, re-implements none |
 | `http.ts` | route projection (`GET /_x/query/<kebab>`, `enforcedBy: 'handler'`) |
 | `mcp-tool.ts` | MCP read descriptor, same `sourceFor` |
-| `client.ts` | typed read client (browser-safe: no server imports) |
+| `client.ts` | typed read client (browser-safe: no server imports); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
+| `record-answer.ts` | a read's HTTP answer: bare rows, or the record envelope when `rows:` is an entity's branded row schema |
 | — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported from `src/index.ts`. There is no local copy and must not be one |
-| `naming.ts` | export name → `/_x/query/<kebab>`. Pure string math. **Paths only** — no tool name |
+| `naming.ts` | export name → `/_x/query/<kebab>` — `derivePath` IS `@ultimat3/core`'s `queryPath`, re-exported. **Paths only** — no tool name |
 | `registry.ts` | export-name registration, `describeQueries()`, and the `registerPrimitiveRegistrar('query', …)` announcement |
 | `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
 | `subscribes.ts` | the relations a live read declares, and the two assertions that keep them true |
@@ -193,14 +194,46 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   promises. It lives in `packages/core/src/client-flight.ts` now; the tests that pin it from this
   side still drive it through this package's own client.
 - **`ClientFlight` is a TYPE inside `client.ts` and never a value.** That erasure is the entire
-  tree-shaking story: `rpc` alone is 14,759 B minified for the browser and `queryClient` alone is
-  12,755 B, against 20,292 B / 17,912 B with `createClientFlight` imported beside them — ±376 B run
-  to run, which is `Bun.build` 1.4.0 dropping core's `schema-error-codes.ts` (issue #273). A caller
-  who wants a plain typed fetch must not pay for the fence, the dedup map or the retry loop —
-  `packages/cli/src/templates/resource-form-island.ts` and `examples/dummy`'s contact-sales island
-  both write a bare `fetch` today because that bill used to be unavoidable. Never import
-  `createClientFlight` for a VALUE from `client.ts` — `ClientFlight` and `ClientRetry` are
-  `import type` from `@ultimat3/core` and must stay that way.
+  tree-shaking story: a caller who wants a plain typed read must not pay for the fence, the dedup
+  map or the retry loop. Never import `createClientFlight` for a VALUE from `client.ts` —
+  `ClientFlight` and `ClientRetry` are `import type` from `@ultimat3/core` and must stay that way.
+- **Every read dispatches through `@ultimat3/core`'s `clientTransport`, and `client.ts` calls no
+  `fetch`** (`As of 2026-09-22`, 21.0.0, plan 101 slice 05). The `fetch` option is handed on as the
+  transport's injected `fetchImpl`. The transport owns `Accept`, the trace/budget headers, the
+  principal fence, the error decode and the record envelope — so a gateway's HTML is core's
+  `X_CLIENT_TRANSPORT_FAILED` now, and `QueryRequestFailedError` / `X_RPC_FAILED` are gone from this
+  package. The flight is handed to the transport, which is what dedups concurrent identical reads
+  (`client.test.ts`, one `fetchImpl` call); `fresh` and a per-call `retry` ride on the request
+  to it. The path is core's `queryPath` — `naming.ts` re-exports it as `derivePath`. `slice 15`'s `browser-transport` guard is what will make
+  a `fetch(` call here a build error; until then the check is
+  `rg -n 'fetch\(' packages/query/src --glob '!*.test.ts'` finding nothing.
+- **Bundle, `bun build --target=browser --minify`, `import { queryClient } from '@ultimat3/query'`**
+  (`As of 2026-09-22`): **19,026 B** at 20.2.1 (raw `fetch`), **24,114 B** on `clientTransport`;
+  the deep `src/client.ts` import 15,690 → 20,774 B. The +5.1 kB is entirely core's transport graph
+  (`client-transport.ts`, `client-dispatch.ts`, `client-problem.ts`, `record-envelope.ts`,
+  `client-scope.ts`, `record-sink.ts`, `client-paths.ts`); `client.ts` itself shrank. The 12,755 B this file
+  quoted was already false at 20.2.1. Shrinking it is a `packages/core` edit, never a raw `fetch`
+  here.
+- **`@ultimat3/query/client` is the read client without the barrel** (`As of 2026-09-22`). The
+  barrel anchors `errors.ts` and `registry.ts` (`sideEffects`) and exports the server projections;
+  an island that only reads needs neither. `import { queryClient } from '@ultimat3/query/client'`,
+  measured `bun build --target=browser --minify`: **16,458 B** against **23,611 B** through the
+  barrel. `@ultimat3/realtime`'s `useQuery` is the caller it exists for. `client-subpath.test.ts`
+  pins that the specifier resolves and carries no server export.
+- **…and reaches no titles table** (`As of 2026-09-22`, same method): **10,210 B**, from 16,640 B
+  that morning. `client.ts` and `naming.ts` import core from `@ultimat3/core/page`, and the two
+  page keys live in `page-keys.ts` — a leaf, because `page-controls.ts` refuses a bad value and so
+  imports `errors.ts`, which registers this package's whole code table at import. `client.ts` may
+  never import `page-controls.ts` or `stable.ts` again; `client-bundle.test.ts` fails on
+  `core-error-codes.ts`, `schema-error-codes.ts` or `errors.ts` in the graph, and past 11 kB.
+- **The record envelope is derived from `rows:`, never switched on** (`record-answer.ts`). A read's
+  `sql:` names its table as a STRING, so the query declaration carries no schema the envelope could
+  be derived from; `rows?: StandardSchemaV1<unknown, TRow>` is that carrier, typed against the row
+  `sql:` answers so a projection cannot claim a full entity's schema. `answersRecords(rows)`
+  (`hasEntityRows`, `@ultimat3/entity`) is decided ONCE at projection and read by both `http.ts`
+  and `openapi.ts`; the envelope is sent on EVERY answer (`records: {}` when none came back) — one body
+  shape per operation, action's rule, described once by core's `recordEnvelopeSchema`. No `rows:`,
+  or an unbranded one, is byte-identical on the wire and in `openapi.json`.
 - **The `sideEffects` array is what makes the barrel shakable, and it is load-bearing** (`As of
   2026-08-23`). Declaring nothing meant a bundler had to assume every module ran at import, so
   `import { rpc } from '@ultimat3/action'` was 43,104 B and `import { queryClient } from

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,12 @@ 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.
 
 ## 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": "21.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": "21.0.0",
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/entity": "21.0.0",
+    "@ultimat3/http": "21.0.0",
+    "@ultimat3/policy": "21.0.0",
+    "@ultimat3/schema": "21.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/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
@@ -29,11 +29,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.
@@ -305,46 +306,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

@@ -8,7 +8,7 @@
 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 { problem, toBucket } from '@ultimat3/http';
 import { coerceQuery } from '@ultimat3/schema';
 import type { Deprecation } from './deprecation';
 import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
@@ -18,6 +18,7 @@ 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,6 +31,7 @@ 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);
@@ -52,7 +54,7 @@ export function toQueryRoute(target: AnyQuery): Route {
       // 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(
+      const response = answer(
         page === undefined
           ? await runQuery(target, input, { surface: 'http' })
           : await target.page(input, { ...page, surface: 'http' }),

package/src/index.ts

@@ -66,7 +66,6 @@ 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,
@@ -79,7 +78,6 @@ export {
   QueryInputUnencodableError,
   QueryNotPageableError,
   QueryPolicyMissingError,
-  QueryRequestFailedError,
   QuerySubscribesDriftError,
   QuerySubscribesInvalidError,
   QueryUnregisteredError,

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;

package/src/openapi.ts

@@ -16,6 +16,7 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
+import { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from '@ultimat3/core';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
 import { isExposed } from './mcp-tool';
@@ -24,6 +25,7 @@ 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 { answersRecords } from './record-answer';
 import { listQueries } from './registry';
 
 /**
@@ -37,6 +39,24 @@ const QUERY_TAG = 'query';
 
 export type OpenApiPathItem = Record<string, unknown>;
 
+/**
+ * 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.
+ */
+const ANSWERS: readonly Record<string, unknown>[] = [
+  { type: 'array', items: {} },
+  {
+    type: 'object',
+    required: ['rows', 'endCursor', 'hasNextPage'],
+    properties: {
+      rows: { type: 'array', items: {} },
+      endCursor: { type: ['string', 'null'] },
+      hasNextPage: { type: 'boolean' },
+    },
+  },
+];
+
 /** `{ [path]: { get: operation } }` for every registered read, name-sorted like the actions. */
 export function queryOpenApiPaths(
   queries: readonly AnyQuery[] = listQueries(),
@@ -70,22 +90,14 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
             // 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' },
-                  },
-                },
-              ],
-            },
+            // A read declaring an entity's `rows:` ALWAYS answers the envelope, with the same two
+            // shapes under `data` — core's one description, shared with the action projection.
+            schema: answersRecords(target.rows)
+              ? recordEnvelopeSchema({ oneOf: ANSWERS })
+              : { oneOf: ANSWERS },
           },
         },
+        ...(answersRecords(target.rows) ? { headers: RECORDS_OPENAPI_HEADER } : {}),
       },
       // `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

package/src/page-controls.ts

@@ -12,11 +12,9 @@
 // `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
 
 import { QueryInputInvalidError } from './errors';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 
-/** `?_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 { PAGE_AFTER_KEY, PAGE_FIRST_KEY };
 export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_KEY];
 
 /**

package/src/page-keys.ts

@@ -0,0 +1,9 @@
+// The two search-string keys that turn `GET /_x/query/<name>` into a page — and nothing else. A
+// leaf apart from `page-controls.ts` because that module refuses a bad value, which means it imports
+// this package's `errors.ts`, which registers the whole code table at import: the browser client
+// that only SPELLS the keys must not carry it. `page-controls.ts` re-exports both names.
+
+/** `?_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';

package/src/query.ts

@@ -89,6 +89,15 @@ export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object>
    * is legal — a join reads relations the shape's single `entity` cannot name.
    */
   readonly subscribes?: readonly string[];
+  /**
+   * The row schema, when every row IS an entity's row — `rows: Post.$schema`. Typed against the
+   * row `sql:` answers, so a projection (`from<PostSummary>`) cannot claim a full entity's schema.
+   * It is what the route reads to answer the record envelope (`x-ultimate-records: 1`) so the
+   * page's one store adopts the rows; absent, or unbranded, the wire is the bare rows it has
+   * always been. `sql:` names a table as a STRING, so nothing else carries the schema to derive
+   * from — this key is that carrier, never a `records:` switch.
+   */
+  readonly rows?: StandardSchemaV1<unknown, TRow>;
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -179,6 +188,7 @@ export interface AnyQueryDef {
   readonly policy: QueryPolicy;
   readonly live?: boolean;
   readonly subscribes?: readonly string[];
+  readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -196,6 +206,8 @@ export interface AnyQuery {
   readonly policy: QueryPolicy;
   /** Lifted for the same reason `rateLimit` is: `toLiveQuery` cross-checks it without `defOf`. */
   readonly subscribes?: readonly string[];
+  /** Lifted for the route: whether an answer is a record envelope is decided at projection. */
+  readonly rows?: StandardSchemaV1;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
@@ -240,6 +252,7 @@ export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> =
   | 'input'
   | 'policy'
   | 'subscribes'
+  | 'rows'
   | 'cache'
   | 'mcp'
   | 'rateLimit'

package/src/record-answer.ts

@@ -0,0 +1,68 @@
+/**
+ * A read's HTTP answer. Decided ONCE per query, at projection, from its `rows:` schema — the rule
+ * `@ultimat3/action`'s `record-wire.ts` already follows: a query whose `rows:` is an entity row
+ * schema ALWAYS answers `{ data, records }` behind `x-ultimate-records: 1` (records may be `{}`),
+ * and every other query answers the bare rows (or `Page`) it always did. One body shape per
+ * operation — until 21.0.0 a read sent the envelope only when a row came back, so its OpenAPI was a
+ * `oneOf` over "sometimes" and a generated client had to branch on the data.
+ */
+
+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 type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Page } from './pagination';
+
+/** Turns one read's answer into its response. Built once per route, never per request. */
+export type RecordAnswer = (answer: readonly object[] | Page<object>) => Response;
+
+/**
+ * `undefined` or an unbranded schema answers the plain `json()` it always did. The rows are
+ * collected one at a time against the ROW schema, since the answer's own shape — an array or a
+ * `Page` — is the route's, not the declaration's.
+ */
+export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswer {
+  if (!answersRecords(rows)) return (answer) => json(answer);
+  return (answer) => {
+    const records = collect(rows, isPage(answer) ? answer.rows : answer);
+    return json(encodeRecordEnvelope(answer, records), { headers: { [RECORDS_HEADER]: '1' } });
+  };
+}
+
+/** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */
+export function answersRecords(rows: StandardSchemaV1 | undefined): rows is StandardSchemaV1 {
+  return rows !== undefined && hasEntityRows(rows);
+}
+
+/** `Array.isArray` does not narrow a `readonly` array out of a union, so this says it once. */
+function isPage(answer: readonly object[] | Page<object>): answer is Page<object> {
+  return !Array.isArray(answer);
+}
+
+/**
+ * Every entity row across the answer's rows: record type -> record key -> row. First sighting wins,
+ * `rowsOf`'s own rule — one record shown twice is one record. Built in `Map`s and handed out as
+ * null-prototype objects: a record type and a record key are data, and `__proto__` must stay a key.
+ */
+function collect(
+  schema: StandardSchemaV1,
+  list: readonly object[],
+): Readonly<Record<string, RecordRows>> {
+  const out = new Map<string, Map<string, Row>>();
+  for (const row of list) {
+    for (const [type, byKey] of Object.entries(rowsOf(schema, row))) {
+      const bucket = out.get(type) ?? new Map<string, Row>();
+      out.set(type, bucket);
+      for (const [key, found] of Object.entries(byKey))
+        if (!bucket.has(key)) bucket.set(key, found);
+    }
+  }
+  return nullProto([...out].map(([type, bucket]) => [type, nullProto(bucket)] as const));
+}
+
+function nullProto<V>(entries: Iterable<readonly [string, V]>): Readonly<Record<string, V>> {
+  const target = Object.create(null) as Record<string, V>;
+  for (const [key, value] of entries) target[key] = value;
+  return target;
+}