@ultimat3/query 22.8.2 → 22.9.0

package/README.md

@@ -59,6 +59,34 @@ on as the transport's `fetchImpl`. The transport owns `Accept`, the trace/budget
 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.
 
+### One object — `single: true`
+
+A detail read declares `single: true`. The route answers the first row as the body and **404
+`X_NOT_FOUND`** when `sql` returns none (a list read answers `200 []`), refuses `_first`/`_after`
+(400), and `openapi.json` documents one object with a `404` and no page controls. `.client()` and
+`queryClient` type it `Promise<TRow>` with no `.page`. In process nothing moves: `postById({ id })`,
+`.as()`, `.page()`, `.live()` and the MCP tool still answer `readonly TRow[]`, so opting in breaks no
+`[0]` already written. `As of 2026-09-29`.
+
+```ts
+import { can } from '@ultimat3/policy';
+import { from, query, queryClient, t } from '@ultimat3/query';
+
+type Post = { readonly id: string; readonly title: string };
+declare const posts: readonly Post[];
+
+export const postById = query({
+  input: t.object({ id: t.uuid }),
+  policy: can('post:read'),
+  single: true,
+  sql: ({ id }) => from<Post>('posts', posts).where({ id }).limit(1),
+});
+
+const queries = queryClient<{ postById: typeof postById }>({ baseUrl: '' });
+const post: Post = await queries.postById({ id: '018f4a1c-1b2c-7d3e-8f90-abcdef012345' }); // or X_NOT_FOUND
+const rows: readonly Post[] = await postById({ id: post.id }); // in process: still the rows
+```
+
 ### Records — `rows:` puts a read's answer in the page's store
 
 ```ts
@@ -514,6 +542,8 @@ router feature here.
 | `X_QUERY_NOT_PAGEABLE` | a paged or live read returned a row with no `id` | select the primary key: `db.<rows>.select({ id: true, … })` |
 | `X_INPUT_INVALID` | input failed the Standard Schema | `x queries describe <name> --json` |
 | `X_QUERY_UNREGISTERED` | used before `registerQueries()` ran | register at boot |
+| `X_NOT_FOUND` | a `single: true` read matched no row — the HTTP route's 404 only (entity's code) | `x queries describe <name> --json` prints the SQL |
+| `X_QUERY_SINGLE_INVALID` | `single:` declared as something other than a boolean | `single: true`, or drop the key |
 | `X_QUERY_FOREIGN` | a look-alike was projected as a query | declare it with `query({ … })` |
 | `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` |
 
@@ -537,6 +567,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `QueryInputUnencodableError` | `X_QUERY_INPUT_UNENCODABLE` | `src/errors.ts` |
 | `QueryNotPageableError` | `X_QUERY_NOT_PAGEABLE` | `src/errors.ts` |
 | `QueryPolicyMissingError` | `X_QUERY_POLICY_MISSING` | `src/errors.ts` |
+| `QueryRowNotFoundError` | `X_NOT_FOUND` | `src/errors.ts` |
+| `QuerySingleInvalidError` | `X_QUERY_SINGLE_INVALID` | `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` |

package/package.json

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

package/src/client.ts

@@ -75,6 +75,26 @@ export interface QueryClientMethod<TInput extends StandardSchemaV1, TRow extends
   ): Promise<Page<TRow>>;
 }
 
+/**
+ * A `single: true` read's method: the route answers the row itself, or 404 `X_NOT_FOUND` — which
+ * the transport rejects with, as it does every problem document. No `page`: the route refuses the
+ * page controls on a single read, so the method a list read carries would be a guaranteed 400.
+ */
+export type QuerySingleClientMethod<TInput extends StandardSchemaV1, TRow extends object> = (
+  input: InferInput<TInput>,
+  options?: QueryCallOptions,
+) => Promise<TRow>;
+
+/**
+ * The method a read's declaration projects to. DISTRIBUTIVE on purpose: for `boolean` it is the
+ * union, so a `Query<I, R, true>` is still assignable where `Query<I, R, boolean>` is asked for.
+ */
+export type QueryClientMethodOf<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean,
+> = TSingle extends true ? QuerySingleClientMethod<TInput, TRow> : QueryClientMethod<TInput, TRow>;
+
 /**
  * Loose constraint on purpose: a map of concrete `Query<TInput, TRow>` values must be
  * assignable to it, while `QueryClient<T>` still recovers each read's own input schema and
@@ -89,8 +109,12 @@ export type QueryMap = Record<string, QueryLike>;
 
 /** `queries.publicPost({ slug })`, with the input schema and the row type both inferred. */
 export type QueryClient<TQueries extends QueryMap> = {
-  readonly [K in keyof TQueries]: TQueries[K] extends Query<infer TInput, infer TRow>
-    ? QueryClientMethod<TInput, TRow>
+  readonly [K in keyof TQueries]: TQueries[K] extends Query<
+    infer TInput,
+    infer TRow,
+    infer TSingle extends boolean
+  >
+    ? QueryClientMethodOf<TInput, TRow, TSingle>
     : never;
 };
 

package/src/errors.ts

@@ -27,15 +27,17 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_QUERY_SUBSCRIBES_DRIFT: 'a live query subscribes to a relation its own sql never reads',
   X_QUERY_SUBSCRIBES_INVALID: 'a query declares subscribed relations no live read can use',
   X_QUERY_UNREGISTERED: 'a query was used before it was registered',
+  X_QUERY_SINGLE_INVALID: 'a query declares single: as something other than a boolean',
 };
 
 /**
- * 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
+ * Codes another package owns that this one only throws. `X_INPUT_INVALID` describes an action's
+ * job — enforcing an input schema — and `X_NOT_FOUND` is `@ultimat3/entity`'s "no row for that
+ * id", which a `single: true` read answers over HTTP. The owner 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'] as const;
+export const QUERY_BORROWED_ERROR_CODES = ['X_INPUT_INVALID', 'X_NOT_FOUND'] 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.
@@ -324,3 +326,28 @@ export class QueryInputInvalidError extends UltimateError {
     });
   }
 }
+
+/**
+ * A `single: true` read matched no row. The HTTP route's answer only — every in-process caller of
+ * the same read gets `[]`, as it always has. `@ultimat3/entity`'s code, so the status (404) and the
+ * title are the ones a repo's `findById` miss already answers, not a second "not found".
+ */
+export class QueryRowNotFoundError extends UltimateError {
+  constructor(name: string) {
+    super({
+      code: 'X_NOT_FOUND',
+      cause: `query "${name}" is declared single: true and its sql matched no row for this input`,
+      fix: `x queries describe ${name} --json  # prints the SQL — a stale id, another tenant's row or a soft-deleted one matches nothing`,
+    });
+  }
+}
+
+export class QuerySingleInvalidError extends UltimateError {
+  constructor(value: unknown) {
+    super({
+      code: 'X_QUERY_SINGLE_INVALID',
+      cause: `a query declares single: as ${typeof value}, and only a boolean says whether it reads one object`,
+      fix: 'write single: true for a read of one object, or drop the key for a list read',
+    });
+  }
+}

package/src/facade.ts

@@ -7,6 +7,7 @@
  */
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { QueryClientMethodOf } from './client';
 import { queryClientMethodFor } from './client';
 import { toLiveQuery } from './live';
 import { toQueryTool } from './mcp-tool';
@@ -18,13 +19,19 @@ import { queryName, runQuery } from './read';
  * `self` is a thunk on purpose: the façade is attached while the query is still
  * being assembled, so every method resolves the query when it is called, not now.
  */
-export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
-  def: QueryDef<TInput, TRow>,
-  self: () => Query<TInput, TRow>,
-): QueryFacade<TInput, TRow> {
+export function facadeFor<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean,
+>(
+  def: QueryDef<TInput, TRow, TSingle>,
+  self: () => Query<TInput, TRow, TSingle>,
+): QueryFacade<TInput, TRow, TSingle> {
   return {
     input: def.input,
     policy: def.policy,
+    // Only when declared, like every lifted field: a list read's surface is unchanged.
+    ...(def.single === undefined ? {} : { single: def.single }),
     ...(def.subscribes === undefined ? {} : { subscribes: def.subscribes }),
     ...(def.rows === undefined ? {} : { rows: def.rows }),
     ...(def.cache === undefined ? {} : { cache: def.cache }),
@@ -39,6 +46,13 @@ export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
     page: (input, args) => paginate(self(), input, args),
     live: (input, options) => toLiveQuery(self(), input, options),
     tool: () => toQueryTool(self()),
-    client: (options) => queryClientMethodFor(queryName(self()), options),
+    // One implementation for both wire shapes: the route decides the body, the transport parses
+    // it, and only the TYPE differs — a single read's method answers the row, and has no `page`.
+    client: (options) =>
+      queryClientMethodFor<TInput, TRow>(queryName(self()), options) as QueryClientMethodOf<
+        TInput,
+        TRow,
+        TSingle
+      >,
   };
 }

package/src/http.ts

@@ -11,13 +11,17 @@ import { toBucket } from '@ultimat3/http';
 import { coerceQuery } from '@ultimat3/schema';
 import type { Deprecation } from './deprecation';
 import { recordDeprecatedCall, renderDeprecation } from './deprecation';
-import { QueryDeprecationInvalidError } from './errors';
+import {
+  QueryDeprecationInvalidError,
+  QueryInputInvalidError,
+  QueryRowNotFoundError,
+} from './errors';
 import { derivePath } from './naming';
-import { pageControlsOf } from './page-controls';
+import { PAGE_FIRST_KEY, 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';
+import { recordAnswerFor, recordRowAnswerFor } from './record-answer';
 
 /**
  * `liveFeed` -> `GET /_x/query/live-feed`. Named for the primitive rather than spelled
@@ -31,6 +35,7 @@ export function toQueryRoute(target: AnyQuery): Route {
   // not a surprise on the first read.
   const sunsetting = deprecationHeadersFor(name, target.deprecated);
   const answer = recordAnswerFor(target.rows);
+  const answerRow = recordRowAnswerFor(target.rows);
 
   const handler = async (request: UltimateRequest): Promise<Response> => {
     if (sunsetting !== undefined) {
@@ -59,6 +64,21 @@ export function toQueryRoute(target: AnyQuery): Route {
     // 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);
+    if (target.single === true) {
+      // Refused, not ignored: a caller paging a read of one object has the wrong read in mind, and
+      // a silently dropped `_first` would answer a shape it did not ask for.
+      if (page !== undefined) {
+        throw new QueryInputInvalidError(
+          name,
+          `${PAGE_FIRST_KEY} pages a list, and this read is declared single: true — it answers one row, or 404`,
+        );
+      }
+      // The first row — what every in-process `[0]` of the same read already takes. None is the
+      // 404 a detail URL means, where a list read answers `200 []`.
+      const [row] = await runQuery(target, input, { surface: 'http' });
+      if (row === undefined) throw new QueryRowNotFoundError(name);
+      return answerRow(row);
+    }
     // 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

package/src/index.ts

@@ -57,9 +57,11 @@ export type {
   QueryCallOptions,
   QueryClient,
   QueryClientMethod,
+  QueryClientMethodOf,
   QueryClientOptions,
   QueryLike,
   QueryMap,
+  QuerySingleClientMethod,
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
 export { queryClient, queryClientMethodFor } from './client';
@@ -79,6 +81,8 @@ export {
   QueryInputUnencodableError,
   QueryNotPageableError,
   QueryPolicyMissingError,
+  QueryRowNotFoundError,
+  QuerySingleInvalidError,
   QuerySubscribesDriftError,
   QuerySubscribesInvalidError,
   QueryUnregisteredError,

package/src/live.ts

@@ -108,7 +108,7 @@ export function liveEpoch(): string {
 }
 
 export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends object>(
-  target: Query<TInput, TRow>,
+  target: Query<TInput, TRow, boolean>,
   input: unknown,
   options: ToLiveOptions = {},
 ): Promise<LiveQuery> {

package/src/openapi.ts

@@ -76,6 +76,7 @@ export function queryOpenApiPaths(
  */
 export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknown> {
   const name = queryName(target);
+  if (target.single === true) return singleOperation(target, name);
   return {
     operationId: name,
     tags: [QUERY_TAG],
@@ -116,6 +117,46 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
   };
 }
 
+/**
+ * A `single: true` read: one object, a 404 when there is none, and no page controls — the route
+ * refuses them, so advertising them would document a guaranteed 400. Everything else — the input
+ * parameters, the record envelope, the `x-ultimate` block — is the list operation's, unchanged.
+ */
+function singleOperation(target: AnyQuery, name: string): Record<string, unknown> {
+  const records = answersRecords(target.rows);
+  return {
+    operationId: name,
+    tags: [QUERY_TAG],
+    summary: target.mcp?.description ?? name,
+    ...(target.deprecated === undefined ? {} : { deprecated: true }),
+    parameters: inputParameters(target.input),
+    responses: {
+      '200': {
+        description: 'ok',
+        content: {
+          'application/json': {
+            schema: records ? recordEnvelopeSchema(SINGLE_ANSWER) : SINGLE_ANSWER,
+          },
+        },
+        ...(records ? { headers: RECORDS_OPENAPI_HEADER } : {}),
+      },
+      '400': problemResponse('X_INPUT_INVALID'),
+      '403': problemResponse('policy denied'),
+      '404': problemResponse('X_NOT_FOUND — the read matched no row for this input'),
+    },
+    'x-ultimate': {
+      capability: policyCapability(target.policy),
+      live: target.isLive,
+      single: true,
+      cacheTags: tagKeys(target.cache?.tags ?? []),
+      tool: isExposed(target) ? name : null,
+    },
+  };
+}
+
+/** One row. Its members are not published — a query declares no output schema, as `ANSWERS` says. */
+const SINGLE_ANSWER: Readonly<Record<string, unknown>> = { type: 'object' };
+
 /** The two controls, spelled from `page-controls.ts` so the document cannot drift from the route. */
 const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
   {

package/src/pagination.ts

@@ -36,7 +36,7 @@ export interface PaginateArgs extends SourceOptions {
  * sliced after execution and the source is doing more work than it should.
  */
 export async function paginate<TInput extends StandardSchemaV1, TRow extends object>(
-  target: Query<TInput, TRow>,
+  target: Query<TInput, TRow, boolean>,
   input: unknown,
   args: PaginateArgs,
 ): Promise<Page<TRow>> {

package/src/query.ts

@@ -12,9 +12,9 @@ import type { Actor, Ctx } from '@ultimat3/core';
 import { fingerprint } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryCacheScope } from './cache';
-import type { QueryClientMethod, QueryClientOptions } from './client';
+import type { QueryClientMethodOf, QueryClientOptions } from './client';
 import type { Deprecation } from './deprecation';
-import { QueryCacheTtlInvalidError } from './errors';
+import { QueryCacheTtlInvalidError, QuerySingleInvalidError } from './errors';
 import { facadeFor } from './facade';
 import { assertEncodableInput } from './input-shape';
 import type { LiveQuery, ToLiveOptions } from './live';
@@ -86,11 +86,25 @@ export interface QueryRateLimit {
   readonly windowMs: number;
 }
 
-export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object> {
+export interface QueryDef<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean = boolean,
+> {
   readonly input: TInput;
   readonly policy: QueryPolicy;
   /** `true` makes the read subscribable — see `toLiveQuery`. */
   readonly live?: boolean;
+  /**
+   * `true` declares a read of ONE object — a detail page's row by id or slug. Only the WIRE
+   * changes: `GET /_x/query/<name>` answers that row itself (the first one `sql` returns), and
+   * **404 `X_NOT_FOUND`** when `sql` returns none, where a list read answers `200 []`; the OpenAPI
+   * operation documents one object and no `_first`/`_after`, which the route refuses (400). The
+   * typed client answers `Promise<TRow>`. Every in-process caller — `read(input)`, `.as()`,
+   * `.page()`, `.live()` and the MCP tool — keeps the rows it always had, so opting in breaks no
+   * `[0]` a server file already wrote. Omitted is `false`: a list.
+   */
+  readonly single?: TSingle;
   /**
    * The relations this live read is patched from — the tables `x db gen` grants
    * `REPLICA IDENTITY FULL`, without which logical replication carries no old row on an UPDATE
@@ -205,6 +219,7 @@ export interface AnyQueryDef {
   readonly input: StandardSchemaV1;
   readonly policy: QueryPolicy;
   readonly live?: boolean;
+  readonly single?: boolean;
   readonly subscribes?: readonly string[];
   readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
@@ -219,6 +234,8 @@ export interface AnyQuery {
   readonly name: string;
   /** Declared `live: true`. The subscription itself is `live()`. */
   readonly isLive: boolean;
+  /** Declared `single: true` — the route answers one object or 404. Absent is a list read. */
+  readonly single?: boolean;
   /** The declaration, minus `sql`: readable, and never a way to run it. */
   readonly input: StandardSchemaV1;
   readonly policy: QueryPolicy;
@@ -245,11 +262,14 @@ export interface AnyQuery {
 export interface Query<
   TInput extends StandardSchemaV1 = StandardSchemaV1,
   TRow extends object = Record<string, unknown>,
+  TSingle extends boolean = false,
 > extends AnyQuery {
   /** Callable server-side with the same types the client and the MCP tool see. */
   (input: InferInput<TInput>, options?: QueryOptions): Promise<readonly TRow[]>;
   readonly input: TInput;
-  named(name: string): Query<TInput, TRow>;
+  /** The declaration, as a type: what `.client()` and `queryClient` read the wire shape off. */
+  readonly single?: TSingle;
+  named(name: string): Query<TInput, TRow, TSingle>;
   as(
     actor: Actor | null,
     input: InferInput<TInput>,
@@ -261,14 +281,19 @@ export interface Query<
    * Typed against this query's input and row type, which is the whole point of it —
    * so it lives here and not on the schema-erased `AnyQuery` view.
    */
-  client(options: QueryClientOptions): QueryClientMethod<TInput, TRow>;
+  client(options: QueryClientOptions): QueryClientMethodOf<TInput, TRow, TSingle>;
 }
 
 /** The fluent half of a query: lifted declaration plus one method per projection. */
-export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> = Pick<
-  Query<TInput, TRow>,
+export type QueryFacade<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean = false,
+> = Pick<
+  Query<TInput, TRow, TSingle>,
   | 'input'
   | 'policy'
+  | 'single'
   | 'subscribes'
   | 'rows'
   | 'cache'
@@ -282,15 +307,22 @@ export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> =
   | 'client'
 >;
 
-export function query<TInput extends StandardSchemaV1, TRow extends object>(
-  def: QueryDef<TInput, TRow>,
-): Query<TInput, TRow> {
+export function query<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean = false,
+>(def: QueryDef<TInput, TRow, TSingle>): Query<TInput, TRow, TSingle> {
   // Here and not in `toQueryRoute`: a read is projected to `GET /_x/query/<kebab>` whether or not
   // anyone mounts it, and the typed client derives that same URL — so an input a query string
   // cannot carry is wrong for every call, and the file that declared it is where it is repaired.
   assertEncodableInput(def.input);
   assertCacheTtl(def.cache);
   assertSubscribes(def.subscribes, def.live);
+  // A JS caller or generated code can write `single: 'yes'`; truthiness would read it as `true`
+  // on the route and `false` in the type, so anything but a boolean is refused where it is written.
+  if (def.single !== undefined && typeof def.single !== 'boolean') {
+    throw new QuerySingleInvalidError(def.single);
+  }
   // Snapshot and freeze BEFORE registration. `build()` stores `def` and `facadeFor()` exposes the
   // same array, so a caller holding the literal it passed could mutate the list AFTER validation
   // — and that list is what the manifest publishes and what `x db gen` grants REPLICA IDENTITY
@@ -335,20 +367,20 @@ export function nameQuery<Q extends AnyQuery>(target: Q, name: string): Q {
   return target;
 }
 
-function build<TInput extends StandardSchemaV1, TRow extends object>(
-  def: QueryDef<TInput, TRow>,
+function build<TInput extends StandardSchemaV1, TRow extends object, TSingle extends boolean>(
+  def: QueryDef<TInput, TRow, TSingle>,
   name: string,
-): Query<TInput, TRow> {
+): Query<TInput, TRow, TSingle> {
   const callable = (
     input: InferInput<TInput>,
     options: QueryOptions = {},
   ): Promise<readonly TRow[]> => runQuery(self, input, options);
 
-  const self: Query<TInput, TRow> = Object.assign(callable, {
+  const self: Query<TInput, TRow, TSingle> = Object.assign(callable, {
     kind: 'query' as const,
     isLive: def.live === true,
     describe: (): QueryDescriptor => describeQuery(self),
-    named: (next: string): Query<TInput, TRow> => build(def, next),
+    named: (next: string): Query<TInput, TRow, TSingle> => build(def, next),
     ...facadeFor(def, () => self),
   });
   // `name` on a function is non-writable, so Object.assign cannot set it.

package/src/read.ts

@@ -65,7 +65,7 @@ export function queryName(target: AnyQuery): string {
 
 /** Validate, authorize, then read — the same three steps on every surface. */
 export function runQuery<TInput extends StandardSchemaV1, TRow extends object>(
-  target: Query<TInput, TRow>,
+  target: Query<TInput, TRow, boolean>,
   raw: unknown,
   options?: QueryOptions,
 ): Promise<readonly TRow[]>;

package/src/record-answer.ts

@@ -30,6 +30,17 @@ export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswe
   };
 }
 
+/**
+ * The same decision for a `single: true` read, whose answer is ONE row: the row itself, or the
+ * envelope with that row as `data` and its records beside it — the shape an action's record wire
+ * answers for a single output, so the transport unwraps both the same way.
+ */
+export function recordRowAnswerFor(rows: StandardSchemaV1 | undefined): (row: object) => Response {
+  if (!answersRecords(rows)) return (row) => json(row);
+  return (row) =>
+    json(encodeRecordEnvelope(row, collect(rows, [row])), { headers: { [RECORDS_HEADER]: '1' } });
+}
+
 /** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */
 export function answersRecords(rows: StandardSchemaV1 | undefined): rows is StandardSchemaV1 {
   return rows !== undefined && hasEntityRows(rows);

package/src/sql.ts

@@ -22,7 +22,7 @@ export interface ExplainResult extends SqlText {
  * surfaces that expose it (`/_x`, the CLI) are admin-gated in their own right.
  */
 export async function explain<TInput extends StandardSchemaV1, TRow extends object>(
-  target: Query<TInput, TRow>,
+  target: Query<TInput, TRow, boolean>,
   input: unknown,
   ctx?: Ctx,
 ): Promise<ExplainResult> {