@ultimat3/query 29.3.2 → 30.0.0

package/src/download.ts

@@ -0,0 +1,261 @@
+/**
+ * `query({ input, policy, download })` — a read whose answer is a FILE, served at a short-lived
+ * signed URL. Still a `query`: the same input parse, the same policy, the same declared limit, the
+ * same audit, one name in the registry and the manifest. Only the answer differs, so the rows
+ * projections (`live`, `page`, `as`, MCP, `explain`) are refused by the `sql` this file stores.
+ *
+ * Two calls make a download. `url(input)` runs the read's front half as the caller and seals a
+ * token naming the caller, the input and an expiry. `GET <url>` opens the token, re-parses the
+ * input from the URL and runs `handle` as the minting actor — the policy decided at mint, and the
+ * token is what it decided. That is what lets a `<video src>` or a link handed to someone without
+ * the session's headers fetch the bytes, and what keeps a URL from outliving `expiresInMs`.
+ */
+
+import type { Ctx, Deprecation } from '@ultimat3/core';
+import { queryPath, useContext } from '@ultimat3/core';
+import type { RequestedRange } from '@ultimat3/http';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { DownloadUrl, QueryCallOptions, QueryClientOptions } from './client';
+import { downloadClientFor } from './client';
+import { QueryDownloadInvalidError, QueryDownloadOnlyError } from './download-errors';
+import {
+  assertGrantedInput,
+  DOWNLOAD_GRANT_PARAM,
+  mintDownloadToken,
+  openDownloadToken,
+} from './download-token';
+import type { QueryPolicy } from './policy-gate';
+import type { AnyQuery, AnyQueryDef, QueryDescriptor, QueryOptions, QueryRateLimit } from './query';
+import { admittedCall, defOf, queryName, stashDef } from './read';
+import { searchOf } from './search-string';
+
+export type { DownloadUrl } from './client';
+
+/** How long a minted URL works when the declaration names nothing: long enough to start a player. */
+export const DEFAULT_DOWNLOAD_TTL_MS = 300_000;
+/** The floor and ceiling of `expiresInMs`. A URL is a bearer capability; an hour is the most. */
+export const MIN_DOWNLOAD_TTL_MS = 1_000;
+export const MAX_DOWNLOAD_TTL_MS = 3_600_000;
+
+/** The written reason the token's serve skips the policy — `admit`'s escape, never a boolean. */
+const TOKEN_IS_THE_GRANT =
+  'a download token is sealed only by url(), after this query admitted the minting actor; the token is that decision';
+
+interface DownloadFileHead {
+  readonly contentType: string;
+  /** The name a browser saves it under — `content-disposition`'s `filename` and `filename*`. */
+  readonly filename: string;
+  /** `attachment` (default) saves it; `inline` lets a tab render it. `<video>` ignores both. */
+  readonly disposition?: 'attachment' | 'inline' | undefined;
+}
+
+/**
+ * Opens the bytes asked for: the window with a `Range:`, the whole file with none, and not at all
+ * for a 304 or a 416. So a stored object's seek reads only its window, with no `storage` edge here:
+ * `(range) => range === undefined ? disk.stream(key) : disk.streamRange(key, [range.start, range.end])`.
+ */
+export type DownloadBodyOpener = (range?: RequestedRange) => BodyInit | Promise<BodyInit>;
+
+/** What `handle` answers. Bytes, never a base64 string — that is the +33 % this exists to remove. */
+export type DownloadFile =
+  | (DownloadFileHead & {
+      /**
+       * A `Uint8Array` or a `Blob` (a `Bun.file`, a slice) is range-served from its own length; a
+       * `ReadableStream` is range-served only with `size`, else whole with `accept-ranges: none`,
+       * and a window of one has read and dropped everything before it.
+       */
+      readonly body: Uint8Array | Blob | ReadableStream<Uint8Array>;
+      /** The stream's length in bytes. Ignored for a `Uint8Array` or a `Blob`, which know theirs. */
+      readonly size?: number | undefined;
+    })
+  | (DownloadFileHead & {
+      /** The disk's own window. A sealed object cannot take it: an AES-GCM envelope opens whole. */
+      readonly body: DownloadBodyOpener;
+      /** Required: it is what a `Range:` is judged against before anything is opened. */
+      readonly size: number;
+    });
+
+export interface DownloadArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface QueryDownload<TInput extends StandardSchemaV1> {
+  /** How long a minted URL works: 1 000 … 3 600 000 ms. Default `DEFAULT_DOWNLOAD_TTL_MS` (5 min). */
+  readonly expiresInMs?: number | undefined;
+  /**
+   * The file, for an input the policy already admitted. Runs as the actor that MINTED the URL;
+   * decrypt a sealed object here (`open()` from `@ultimat3/core`) — an AES-GCM envelope opens whole,
+   * so a sealed object is buffered, bounded by its disk's `maxGetBytes`.
+   */
+  handle(args: DownloadArgs<TInput>): Promise<DownloadFile>;
+}
+
+type RowsOnly = 'sql' | 'live' | 'single' | 'subscribes' | 'rows' | 'cache' | 'mcp';
+
+/** A download declares no rows option: each is a type error here and `X_QUERY_DOWNLOAD_INVALID` at runtime. */
+export type DownloadQueryDef<TInput extends StandardSchemaV1> = {
+  readonly input: TInput;
+  readonly policy: QueryPolicy;
+  readonly download: QueryDownload<TInput>;
+  /** Spent at MINT — one URL is one admitted read, however many `Range:` requests a player makes. */
+  readonly rateLimit?: QueryRateLimit;
+  readonly deprecated?: Deprecation;
+  /** Records the MINT: the decision of who may read what. A ranged GET is not a second read. */
+  readonly audit?: boolean;
+} & { readonly [K in RowsOnly]?: never };
+
+/** `client.recording.url(input)` — the browser half: the server mints, this prefixes the base. */
+export interface DownloadClientMethod<TInput extends StandardSchemaV1> {
+  url(input: InferInput<TInput>, options?: QueryCallOptions): Promise<DownloadUrl>;
+}
+
+export interface DownloadQuery<TInput extends StandardSchemaV1 = StandardSchemaV1>
+  extends AnyQuery {
+  /** The file, in-process: the same parse and policy as `url()`, then `handle` as this caller. */
+  (input: InferInput<TInput>, options?: QueryOptions): Promise<DownloadFile>;
+  readonly input: TInput;
+  readonly download: true;
+  /** Mint a signed URL — a PATH, `/_x/query/<kebab>?…&_token=…` — for this caller and this input. */
+  url(input: InferInput<TInput>, options?: QueryOptions): Promise<DownloadUrl>;
+  client(options: QueryClientOptions): DownloadClientMethod<TInput>;
+  named(name: string): DownloadQuery<TInput>;
+}
+
+const isFunction = (value: unknown): value is (...args: never[]) => unknown =>
+  typeof value === 'function';
+
+/** The declaration, judged where it is written: an untyped caller can still pass `sql` beside it. */
+export function assertDownloadDef(def: Readonly<Record<string, unknown>>): void {
+  const download = def['download'];
+  if (typeof download !== 'object' || download === null) {
+    throw new QueryDownloadInvalidError('download is not an object with a handle');
+  }
+  const rows = (['sql', 'live', 'single', 'subscribes', 'rows', 'cache', 'mcp'] as const).filter(
+    (key) => def[key] !== undefined,
+  );
+  if (rows.length > 0) {
+    throw new QueryDownloadInvalidError(`it also declares ${rows.join(', ')}, which answer rows`);
+  }
+  if (!isFunction(Reflect.get(download, 'handle'))) {
+    throw new QueryDownloadInvalidError('download.handle is not a function');
+  }
+  const ttl: unknown = Reflect.get(download, 'expiresInMs');
+  const whole = typeof ttl === 'number' && Number.isSafeInteger(ttl);
+  if (ttl !== undefined && !(whole && ttl >= MIN_DOWNLOAD_TTL_MS && ttl <= MAX_DOWNLOAD_TTL_MS)) {
+    throw new QueryDownloadInvalidError(
+      `download.expiresInMs is ${String(ttl)}, not a whole number of ms from ${MIN_DOWNLOAD_TTL_MS} to ${MAX_DOWNLOAD_TTL_MS}`,
+    );
+  }
+}
+
+/** `describe` is handed in, so this file never value-imports `query.ts` (which imports it). */
+export function buildDownloadQuery<TInput extends StandardSchemaV1>(
+  def: DownloadQueryDef<TInput>,
+  name: string,
+  describe: (target: AnyQuery) => QueryDescriptor,
+): DownloadQuery<TInput> {
+  const refuse = (): Promise<never> => Promise.reject(new QueryDownloadOnlyError(queryName(self)));
+  const callable = (input: InferInput<TInput>, options: QueryOptions = {}): Promise<DownloadFile> =>
+    readDownloadFile(self, input, options);
+  const self: DownloadQuery<TInput> = Object.assign(callable, {
+    kind: 'query' as const,
+    isLive: false,
+    download: true as const,
+    input: def.input,
+    policy: def.policy,
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    describe: (): QueryDescriptor => describe(self),
+    named: (next: string): DownloadQuery<TInput> => buildDownloadQuery(def, next, describe),
+    as: refuse,
+    page: refuse,
+    live: refuse,
+    url: (input: InferInput<TInput>, options: QueryOptions = {}) =>
+      mintDownloadUrl(self, input, options),
+    client: (options: QueryClientOptions): DownloadClientMethod<TInput> => ({
+      url: downloadClientFor<TInput>(queryName(self), options).url,
+    }),
+  });
+  Object.defineProperty(self, 'name', { value: name, configurable: true });
+  const stored: AnyQueryDef = {
+    input: def.input,
+    policy: def.policy,
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    ...(def.audit === undefined ? {} : { audit: def.audit }),
+    download: def.download,
+    // Every rows projection ends here — one refusal, wherever the rows were asked from.
+    sql: () => {
+      throw new QueryDownloadOnlyError(queryName(self));
+    },
+  };
+  stashDef(self, stored);
+  return self;
+}
+
+function handlerOf(target: AnyQuery): QueryDownload<StandardSchemaV1> {
+  const download = defOf(target).download;
+  if (download === undefined) throw new QueryDownloadOnlyError(queryName(target));
+  return download;
+}
+
+/** The in-process read: admitted as the caller, answered by `handle`. */
+export function readDownloadFile(
+  target: AnyQuery,
+  raw: unknown,
+  options: QueryOptions,
+): Promise<DownloadFile> {
+  const download = handlerOf(target);
+  return admittedCall(target, raw, options, (input, ctx) => download.handle({ input, ctx }));
+}
+
+/**
+ * Admit the caller exactly as a read would, then seal the decision. The URL carries the input as
+ * it was HANDED in (the route re-parses it to the same value) and the token binds the PARSED one.
+ */
+export function mintDownloadUrl(
+  target: AnyQuery,
+  raw: unknown,
+  options: QueryOptions,
+): Promise<DownloadUrl> {
+  const name = queryName(target);
+  const ttl = handlerOf(target).expiresInMs ?? DEFAULT_DOWNLOAD_TTL_MS;
+  return admittedCall(target, raw, options, async (input, ctx) => {
+    const expiresAtMs = ctx.now().getTime() + ttl;
+    const token = await mintDownloadToken(name, input, ctx.actor, expiresAtMs);
+    const search = searchOf(raw);
+    const tokenParam = `${DOWNLOAD_GRANT_PARAM}=${encodeURIComponent(token)}`;
+    return {
+      url: `${queryPath(name)}?${search === '' ? '' : `${search}&`}${tokenParam}`,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    };
+  });
+}
+
+/**
+ * The file a token grants: the token opened against THIS query and THIS input on the context's
+ * clock, then `handle` as the minting actor. The input is still parsed — `handle` is owed the
+ * schema's output — and the policy is not re-run: it ran at mint, with facts this token cannot
+ * carry, and the written reason above is what `admit` logs for the skip.
+ */
+export async function serveDownloadFile(
+  target: AnyQuery,
+  raw: unknown,
+  token: string,
+  options: QueryOptions,
+): Promise<DownloadFile> {
+  const name = queryName(target);
+  const download = handlerOf(target);
+  const now = (options.ctx ?? useContext()).now().getTime();
+  const grant = await openDownloadToken(name, token, now);
+  return admittedCall(
+    target,
+    raw,
+    { ...options, actor: grant.actor, unenforced: TOKEN_IS_THE_GRANT },
+    (input, ctx) => {
+      assertGrantedInput(name, grant, input);
+      return download.handle({ input, ctx });
+    },
+  );
+}

package/src/errors.ts

@@ -31,6 +31,13 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_QUERY_AUDIT_SINK_MISSING: 'a query declares audit: true and no audit sink is installed',
   X_QUERY_AUDIT_SINK_FAILED:
     'an audited read was refused because the audit sink rejected its record',
+  X_QUERY_DOWNLOAD_INVALID: 'a query declares a download it cannot serve',
+  X_QUERY_DOWNLOAD_ONLY: 'rows were asked of a query that answers a file',
+  X_QUERY_DOWNLOAD_TOKEN_INVALID: 'a download URL carries a token this app did not mint for it',
+  X_QUERY_DOWNLOAD_TOKEN_EXPIRED: 'a download URL is past its expiry',
+  X_QUERY_HTTP_PATH_INVALID: "a query's pinned http.path is not a valid path template",
+  X_QUERY_ETAG_INVALID: 'etag: true on a read that has its own validator',
+  X_QUERY_TIMEOUT_INVALID: 'a read declares a timeoutMs that is not a whole positive number of ms',
 };
 
 /**
@@ -40,7 +47,15 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
  * 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_NOT_FOUND'] as const;
+// `X_CONTRACT_*`: the exercise assertion `contract-test.ts` runs, a twin of action's (`exercise.ts`).
+export const QUERY_BORROWED_ERROR_CODES = [
+  'X_INPUT_INVALID',
+  'X_NOT_FOUND',
+  'X_CONTRACT_DRIFT',
+  'X_CONTRACT_DEFECT',
+  'X_CONTRACT_EXERCISE_UNREACHED',
+  'X_CONTRACT_EXERCISE_UNDECLARED',
+] 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.
@@ -154,12 +169,12 @@ export class QueryInputUnencodableError extends UltimateError {
  * the cause describes the declaration, exactly as `X_QUERY_INPUT_UNENCODABLE` does.
  */
 export class QueryCacheTtlInvalidError extends UltimateError {
-  constructor(ttlMs: number) {
+  constructor(ttlMs: number, field: 'ttlMs' | 'negativeTtlMs' = 'ttlMs') {
     super({
       code: 'X_QUERY_CACHE_TTL_INVALID',
-      cause: `a query declares cache.ttlMs as ${ttlMs}, and every cache tier refuses a lease that is not positive and finite`,
-      fix: 'set `cache: { ttlMs: 60_000 }` to a positive whole number of milliseconds, or drop ttlMs to take the read cache default',
-      meta: { ttlMs },
+      cause: `a query declares cache.${field} as ${ttlMs}, and every cache tier refuses a lease that is not positive and finite`,
+      fix: `set \`cache: { ${field}: ${field === 'ttlMs' ? '60_000' : '1_000'} }\` to a positive whole number of milliseconds, or drop ${field} to take the default`,
+      meta: { ttlMs, field },
     });
   }
 }

package/src/exercise.ts

@@ -0,0 +1,156 @@
+/**
+ * A read's adapter over `@ultimat3/core`'s exercise loop (`runExercise`, shared with `action`):
+ * run the read with inputs its own schema accepts, seeded by its name, and see whether `sql()` and
+ * its execution survive. A read writes nothing, so no transaction wraps it. The codes are action's.
+ */
+
+import type { Actor, Ctx, DrawnInput, ExerciseReport } from '@ultimat3/core';
+import {
+  bindDrawn,
+  ctxOf,
+  exerciseReplay,
+  isUltimateError,
+  renderFixShellArg,
+  runExercise,
+  tryUseContext,
+  UltimateError,
+} from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { validateAsync } from '@ultimat3/schema';
+import { arbitrary } from '@ultimat3/schema/sample';
+import { QueryAuditSinkMissingError } from './audit-errors';
+import { QueryDeniedError } from './errors';
+import type { AnyQuery } from './query';
+import { queryName, sourceFor } from './read';
+
+/** Who reads, and what binds the parts a generated value cannot. Same shape as an action's. */
+export interface QueryExerciseActorOptions {
+  readonly actor: Actor | null;
+  readonly input?: (drawn: DrawnInput) => unknown;
+  readonly runs?: number;
+}
+
+export interface QueryExerciseOffOptions {
+  readonly off: string;
+}
+
+export type QueryExerciseOptions = QueryExerciseActorOptions | QueryExerciseOffOptions;
+
+export type QueryExerciseReport = ExerciseReport;
+
+export const queryExerciseTestName = (name: string): string =>
+  `${name}: read survives generated input`;
+
+/**
+ * Whether a refusal came from the front half every surface shares — the policy, the parse, the
+ * declared limit, a missing audit sink — rather than from `sql()` or its execution. Read off the
+ * refusal itself because `read.ts` keeps no counter: anything else was thrown past the front half.
+ */
+function beforeSql(error: unknown): boolean {
+  if (error instanceof QueryDeniedError || error instanceof QueryAuditSinkMissingError) return true;
+  return isUltimateError(error) && FRONT_HALF_CODES.has(error.code);
+}
+
+const FRONT_HALF_CODES: ReadonlySet<string> = new Set(['X_INPUT_INVALID', 'X_RATE_LIMITED']);
+
+const accepts = async (schema: StandardSchemaV1, input: unknown): Promise<boolean> =>
+  (await validateAsync(schema, input)).issues === undefined;
+
+/**
+ * Exercise `target`. "Reached" is `sql()` having built a source: everything before it — the
+ * policy, the declared limit, the parse — is the front half every surface shares.
+ *
+ * A test-time call: refused in `staging`/`production` (`X_CONTRACT_EXERCISE_ENVIRONMENT`). Nothing
+ * is rolled back, because a read writes nothing; what it touches anyway (a rate-limit counter, an
+ * audit record, an outbound fetch — sealed under the test preload) is kept.
+ */
+export async function exerciseQuery(
+  target: AnyQuery,
+  options: QueryExerciseActorOptions,
+  ctx?: Ctx,
+): Promise<QueryExerciseReport> {
+  const name = queryName(target);
+  const base = ctx ?? tryUseContext() ?? ctxOf({});
+  const verdict = await runExercise({
+    name,
+    runs: options.runs,
+    stoppedLabel: 'stopped before sql()',
+    draw: (seed, run) => arbitrary(target.input, { seed, run }),
+    bind: bindDrawn(options.input),
+    accepts: (input) => accepts(target.input, input),
+    attempt: async (input) => {
+      try {
+        const source = await sourceFor(target, input, {
+          ctx: base,
+          actor: options.actor,
+          surface: 'http',
+        });
+        await source.execute();
+        return { ok: true, reached: true };
+      } catch (error) {
+        return { ok: false, reached: !beforeSql(error), error };
+      }
+    },
+    statusOf: statusFor,
+  });
+  switch (verdict.kind) {
+    case 'pass':
+      return verdict.report;
+    case 'drift':
+      throw queryDrawsRefused(name);
+    case 'unreached':
+      throw queryUnreached(name, verdict.outcomes);
+    case 'defect':
+      throw queryDefect(name, verdict.run, verdict.input, verdict.defect, verdict.error);
+  }
+}
+
+function queryDefect(
+  name: string,
+  run: number,
+  input: unknown,
+  defect: string,
+  error: unknown,
+): UltimateError {
+  return new UltimateError({
+    code: 'X_CONTRACT_DEFECT',
+    cause: `query ${name} ${defect} on generated run ${run}, for input its own schema accepts (meta.input, meta.failure)`,
+    fix: `${exerciseReplay(name, queryExerciseTestName(name))}   # replays the run; fix the ${name} read or tighten its input: first`,
+    meta: {
+      run,
+      input,
+      ...(isUltimateError(error) ? { failure: { code: error.code, cause: error.cause } } : {}),
+    },
+    sourceError: error,
+  });
+}
+
+function queryUnreached(name: string, outcomes: readonly string[]): UltimateError {
+  return new UltimateError({
+    code: 'X_CONTRACT_EXERCISE_UNREACHED',
+    cause: `none of ${outcomes.length} generated runs of query ${name} reached its sql() (meta.outcomes lists what each one hit)`,
+    fix: `${renderFixShellArg(name, '<name>')}.contract({ exercise: { actor } }) with an actor the policy permits`,
+    meta: { outcomes },
+  });
+}
+
+function queryDrawsRefused(name: string): UltimateError {
+  return new UltimateError({
+    code: 'X_CONTRACT_DRIFT',
+    cause: `query ${name}: its input schema refused every generated value, so the read was never exercised`,
+    fix: `${renderFixShellArg(name, '<name>')}.contract({ exercise: { actor, input: (drawn) => ({ ...drawn, field: '<a value the refinement accepts>' }) } })`,
+  });
+}
+
+/** A guarded read with no exercise said, or an opt-out with a blank reason. */
+export function queryExerciseUndeclared(name: string, blankReason: boolean): UltimateError {
+  const call = renderFixShellArg(name, '<name>');
+  return new UltimateError({
+    code: 'X_CONTRACT_EXERCISE_UNDECLARED',
+    cause: blankReason
+      ? `${name}.contract({ exercise: { off } }) gives a blank reason, so the skip is silent`
+      : `query ${name} refuses an anonymous reader and its .contract() names no actor to read as`,
+    fix: `${call}.contract({ exercise: { actor } }) — or ${call}.contract({ exercise: { off: '<why this read cannot run in a test>' } })`,
+  });
+}

package/src/facade.ts

@@ -7,9 +7,12 @@
  * (`toolFrom(orgFeed)`), a tier this package cannot import.
  */
 
+import { checkDeclaredErrors } from '@ultimat3/core';
+import { declaredStatusFor } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryClientMethodOf } from './client';
 import { queryClientMethodFor } from './client';
+import { queryContractTestsFor } from './contract-test';
 import { toLiveQuery } from './live';
 import { paginate } from './pagination';
 import type { Query, QueryDef, QueryFacade } from './query';
@@ -38,6 +41,10 @@ export function facadeFor<
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    // Checked here, the one place a declaration is lifted: frozen and sorted, or refused.
+    ...(def.errors === undefined
+      ? {}
+      : { errors: checkDeclaredErrors(def.errors, declaredStatusFor, 'this query') }),
     // `.as()` is impersonation on the one read path: `runQuery` keeps the
     // surrounding context whole and swaps only the actor.
     as: (actor, input, options) => runQuery(self(), input, { ...options, actor }),
@@ -45,13 +52,14 @@ export function facadeFor<
     // signed cursor is only reachable through the query that issued it.
     page: (input, args) => paginate(self(), input, args),
     live: (input, options) => toLiveQuery(self(), input, options),
+    contract: (options) => queryContractTestsFor(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
-      >,
+      queryClientMethodFor<TInput, TRow>(
+        queryName(self()),
+        options,
+        def.http?.path,
+      ) as QueryClientMethodOf<TInput, TRow, TSingle>,
   };
 }

package/src/http-etag.ts

@@ -0,0 +1,44 @@
+// Single responsibility: a declared read's validator. The ETag is a strong hash of the bytes the
+// policy already judged, keyed to the actor who was judged, and the 304 is `@ultimat3/http`'s
+// `notModified` — the one `If-None-Match` reader, so this file never compares a header itself.
+
+import { notModified, PRIVATE_REVALIDATE, type UltimateRequest } from '@ultimat3/http';
+import { readAuthority } from './cache';
+
+/**
+ * `"<sha-256, base64url>"` over the actor's authority and the body. The authority is in the hash so
+ * one actor's validator never confirms that another's rows are unchanged: two callers seeing the
+ * same bytes still hold two validators.
+ */
+function etagOf(authority: string, body: ArrayBuffer): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(authority);
+  hasher.update('\0');
+  hasher.update(body);
+  return `"${hasher.digest('base64url')}"`;
+}
+
+/**
+ * The answer with its validator, or the bodiless 304 when the caller already holds it. Called with
+ * the response `runQuery` produced, so the policy and the rate limit have already run: a 304 is
+ * still a read of that person's rows. Only a 200 carries one — a refusal is never revalidated.
+ */
+export async function withValidator(
+  request: UltimateRequest,
+  response: Response,
+): Promise<Response> {
+  if (response.status !== 200) return response;
+  const body = await response.arrayBuffer();
+  const etag = etagOf(readAuthority(request.ctx.actor, 'actor'), body);
+  const headers = new Headers(response.headers);
+  headers.set('cache-control', PRIVATE_REVALIDATE);
+  headers.set('etag', etag);
+  const unchanged = notModified(request, etag, headers);
+  if (unchanged !== undefined) {
+    // A 304 carries no body, and no header describing one.
+    unchanged.headers.delete('content-length');
+    unchanged.headers.delete('content-type');
+    return unchanged;
+  }
+  return new Response(body, { status: 200, headers });
+}

package/src/http-pin-error.ts

@@ -0,0 +1,17 @@
+// Single responsibility: `X_QUERY_HTTP_PATH_INVALID`, the refusal of a read's pinned `http.path`.
+// Its own leaf over `@ultimat3/core/page`, so the browser read client can refuse a URL it cannot
+// fill without loading `errors.ts`'s titles table (`client-bundle.test.ts`); the title is there.
+
+import { UltimateError } from '@ultimat3/core/page';
+
+export class QueryHttpPathInvalidError extends UltimateError {
+  constructor(input: { readonly name: string; readonly path: string; readonly reason: string }) {
+    super({
+      code: 'X_QUERY_HTTP_PATH_INVALID',
+      cause: `query${input.name === '' ? '' : ` "${input.name}"`} pins http.path ${input.path}, which ${input.reason}`,
+      // Short on purpose: this class rides the browser read client (`client-bundle.test.ts`).
+      fix: "query({ input: t.object({ id: t.string }), http: { path: '/orders/:id' }, ... }) — every :param a required t.string key of input:, and passed to client()",
+      meta: { query: input.name },
+    });
+  }
+}

package/src/http-pin.ts

@@ -0,0 +1,67 @@
+// Single responsibility: where a read is served — its pinned `http.path` (`/orders/:id`) when it
+// declares one, else core's `queryPath(name)` — and the check of that pin at `query()`. The
+// template rule is core's, shared with `@ultimat3/action`'s pins; only the code is this package's.
+
+import {
+  pathTemplateProblem,
+  queryPath,
+  renderCauseValue,
+  templateKeyProblem,
+  templateParams,
+} from '@ultimat3/core';
+import { tryIntrospect } from '@ultimat3/schema';
+import { QueryHttpPathInvalidError } from './http-pin-error';
+import type { AnyQuery } from './query';
+import { defOf } from './read';
+
+/** What a read may say about its own HTTP projection. */
+export interface QueryHttp {
+  /**
+   * Pin the URL instead of `/_x/query/<kebab>`: lowercase static segments and `:param`s, each a
+   * REQUIRED string key of `input:`. The URL's value joins the search string as the one input the
+   * schema parses; a search string naming the key differently is `X_HTTP_PATH_INPUT_CONFLICT`.
+   */
+  readonly path?: string;
+  /** A read is a `GET`; stated only for symmetry with an action's pin. */
+  readonly method?: 'GET';
+}
+
+/** Refuses at `query()` a pin no route could serve or no input could fill. */
+export function assertQueryHttp(http: QueryHttp | undefined, input: unknown): void {
+  if (http === undefined) return;
+  const method: unknown = http.method;
+  const path: unknown = http.path;
+  const shown = renderCauseValue(path);
+  if (method !== undefined && method !== 'GET') {
+    throw new QueryHttpPathInvalidError({
+      name: '',
+      path: shown,
+      reason: `is declared with http.method ${renderCauseValue(method)}, and a read is a GET`,
+    });
+  }
+  if (path === undefined) {
+    if (method === undefined) return;
+    throw new QueryHttpPathInvalidError({
+      name: '',
+      path: shown,
+      reason: 'is absent, and http.method has no pinned path to answer on',
+    });
+  }
+  const reason =
+    pathTemplateProblem(path) ??
+    templateKeyProblem(templateParams(path as string), tryIntrospect(input)?.properties);
+  if (reason !== undefined) throw new QueryHttpPathInvalidError({ name: '', path: shown, reason });
+}
+
+/** The path `name` is served at: the pin, else the derived `/_x/query/<kebab>`. */
+export function servedQueryPath(name: string, http: QueryHttp | undefined): string {
+  return http?.path ?? queryPath(name);
+}
+
+/** `{ path, method: 'GET' }` exactly when `target` pins its URL — the manifest's fact. */
+export function queryHttpPinOf(
+  target: AnyQuery,
+): { readonly path: string; readonly method: 'GET' } | undefined {
+  const path = defOf(target).http?.path;
+  return path === undefined ? undefined : { path, method: 'GET' };
+}