@ultimat3/query 29.3.2 → 30.0.0

package/src/query.ts

@@ -15,13 +15,18 @@ import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryCacheScope } from './cache';
 import type { QueryClientMethodOf, QueryClientOptions } from './client';
-import { QueryCacheTtlInvalidError, QuerySingleInvalidError } from './errors';
+import type { QueryContractTest, QueryContractTestOptions } from './contract-test';
+import type { DownloadQuery, DownloadQueryDef, QueryDownload } from './download';
+import { assertDownloadDef, buildDownloadQuery } from './download';
+import { QuerySingleInvalidError } from './errors';
 import { facadeFor } from './facade';
+import { assertQueryHttp, type QueryHttp } from './http-pin';
 import { assertEncodableInput } from './input-shape';
 import type { LiveQuery, ToLiveOptions } from './live';
 import type { Page, PaginateArgs } from './pagination';
 import type { QueryPolicy, QuerySurface } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
+import { assertDownloadFreshness, assertFreshness } from './read-freshness';
 import type { SqlSource } from './source';
 import { assertSubscribes } from './subscribes';
 
@@ -34,6 +39,12 @@ export interface QueryCache {
    * every read of that query forever. Omitted takes `DEFAULT_READ_CACHE_TTL_MS`.
    */
   readonly ttlMs?: number;
+  /**
+   * Lifetime of a `null` answer, when it should be shorter than `ttlMs`: a `single: true` lookup
+   * that misses 40 ms before its row lands otherwise says "does not exist" for the whole `ttlMs`.
+   * Only `single: true` answers `null` — an empty list is a list. Positive and finite, as `ttlMs`.
+   */
+  readonly negativeTtlMs?: number;
   /**
    * Who a cached answer may be handed back to. **Defaults to `actor`**, and that default is the
    * mechanism: a read that declares nothing gets the narrowest key, which is always correct.
@@ -100,6 +111,20 @@ export interface QueryDef<
   readonly rows?: StandardSchemaV1<unknown, TRow>;
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
+  /**
+   * Answer `GET` with an `ETag` and `private, no-cache`, and a matching `If-None-Match` with a
+   * bodiless 304 — after the policy and the rate limit, since a 304 is still a read of the caller's
+   * rows. Opt-in because it moves the answer from `no-store` to the browser's disk. Refused on a
+   * `live` read (`X_QUERY_ETAG_INVALID`): its cursor is its validator.
+   */
+  readonly etag?: true;
+  /**
+   * This read's own statement bound, in ms, tighter than the role's `statement_timeout`. The source
+   * runs inside `withStatementTimeout`, a transaction — so **a bounded read never reaches a
+   * replica**. Above the role's bound is `X_DB_STATEMENT_BOUND_INVALID`; firing is
+   * `X_DB_STATEMENT_TIMEOUT`. Not a whole positive number: `X_QUERY_TIMEOUT_INVALID`.
+   */
+  readonly timeoutMs?: number;
   readonly mcp?: McpExposureDeclaration;
   /** Burst and refill for THIS read's route, in the limiter's own vocabulary. */
   readonly rateLimit?: QueryRateLimit;
@@ -118,6 +143,15 @@ export interface QueryDef<
    * `X_QUERY_AUDIT_SINK_MISSING` before the input is parsed.
    */
   readonly audit?: boolean;
+  /** The refusals `sql` may throw, closed — an action's `errors:`, same rule (`declared-errors.ts`). */
+  readonly errors?: readonly string[];
+  /** Pin the URL: `http: { path: '/orders/:id' }` (`http-pin.ts`). */
+  readonly http?: QueryHttp;
+  /**
+   * Absent on a rows read, by type: a declaration holding `sql` AND `download` — a variable, where
+   * no excess-property check reaches — must match neither `query()` overload. `download.ts`.
+   */
+  readonly download?: never;
 }
 
 export interface QueryOptions {
@@ -190,6 +224,9 @@ export interface QueryDescriptor {
   readonly ttlMs: number | null;
   readonly rateLimit: QueryRateLimit | null;
   readonly deprecated: Deprecation | null;
+  /** Declared `download:` — the read answers a file at a signed URL, never rows. */
+  readonly download: boolean;
+  readonly errors: readonly string[] | null;
 }
 
 /**
@@ -206,10 +243,15 @@ export interface AnyQueryDef {
   readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
+  readonly etag?: true;
+  readonly timeoutMs?: number;
   readonly mcp?: McpExposureDeclaration;
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
   readonly audit?: boolean;
+  readonly http?: QueryHttp;
+  /** A download's handler. Private like `sql`: `download.ts` reaches it through `defOf`. */
+  readonly download?: QueryDownload<StandardSchemaV1>;
 }
 
 export interface AnyQuery {
@@ -231,6 +273,9 @@ export interface AnyQuery {
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
+  /** `true` on a `query({ download })` — the route mints a URL or serves a file. Absent otherwise. */
+  readonly download?: true;
+  readonly errors?: readonly string[];
   describe(): QueryDescriptor;
   /** A twin under another name. Registration names through `named`. */
   named(name: string): AnyQuery;
@@ -264,6 +309,8 @@ export interface Query<
    * so it lives here and not on the schema-erased `AnyQuery` view.
    */
   client(options: QueryClientOptions): QueryClientMethodOf<TInput, TRow, TSingle>;
+  /** The generated contract suite the `contract` step runs (`contract-test.ts`). */
+  contract(options?: QueryContractTestOptions): readonly QueryContractTest[];
 }
 
 /** The fluent half of a query: lifted declaration plus one method per projection. */
@@ -282,22 +329,44 @@ export type QueryFacade<
   | 'mcp'
   | 'rateLimit'
   | 'deprecated'
+  | 'errors'
   | 'as'
   | 'page'
   | 'live'
   | 'client'
+  | 'contract'
 >;
 
+/**
+ * A read whose answer is a FILE at a short-lived signed URL — `download.ts`. Same primitive: one
+ * policy, one name, one route; `sql` and every rows option are refused beside it.
+ */
+export function query<TInput extends StandardSchemaV1>(
+  def: DownloadQueryDef<TInput>,
+): DownloadQuery<TInput>;
+export function query<
+  TInput extends StandardSchemaV1,
+  TRow extends object,
+  TSingle extends boolean = false,
+>(def: QueryDef<TInput, TRow, TSingle>): Query<TInput, TRow, TSingle>;
 export function query<
   TInput extends StandardSchemaV1,
   TRow extends object,
   TSingle extends boolean = false,
->(def: QueryDef<TInput, TRow, TSingle>): Query<TInput, TRow, TSingle> {
+>(
+  def: QueryDef<TInput, TRow, TSingle> | DownloadQueryDef<TInput>,
+): Query<TInput, TRow, TSingle> | DownloadQuery<TInput> {
   // 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);
+  if (!isDownloadDef(def)) assertQueryHttp(def.http, def.input);
+  if (isDownloadDef(def)) {
+    assertDownloadFreshness(def);
+    assertDownloadDef(def);
+    return buildDownloadQuery(def, '', describeQuery);
+  }
+  assertFreshness(def);
   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.
@@ -312,16 +381,10 @@ export function query<
   return build(subscribes === undefined ? def : { ...def, subscribes }, '');
 }
 
-/**
- * The same rule, for the same reason: a lease every `CacheTier` refuses is wrong for every read of
- * this query, so it fails on the line that wrote it rather than on the first request. Positive and
- * finite is `assertTtl`'s bar in `@ultimat3/cache`, restated as a refusal and never as a second
- * resolution — there is no "never expires" to fall back to.
- */
-function assertCacheTtl(cache: QueryCache | undefined): void {
-  const ttlMs = cache?.ttlMs;
-  if (ttlMs === undefined) return;
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new QueryCacheTtlInvalidError(ttlMs);
+function isDownloadDef<TInput extends StandardSchemaV1>(
+  def: QueryDef<TInput, object, boolean> | DownloadQueryDef<TInput>,
+): def is DownloadQueryDef<TInput> {
+  return 'download' in def && def.download !== undefined;
 }
 
 /**
@@ -384,6 +447,8 @@ export function describeQuery(target: AnyQuery): QueryDescriptor {
     ttlMs: target.cache?.ttlMs ?? null,
     rateLimit: target.rateLimit ?? null,
     deprecated: target.deprecated ?? null,
+    download: target.download === true,
+    errors: target.errors ?? null,
   };
 }
 

package/src/read-freshness.ts

@@ -0,0 +1,63 @@
+// Single responsibility: the declaration-time screen for a read's freshness options — `etag`, the
+// time bound and the null's lease. Refused on the line that wrote them, never on the first request:
+// a value wrong for one call of a query is wrong for every call of it.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import { QueryCacheTtlInvalidError } from './errors';
+
+export class QueryEtagInvalidError extends UltimateError {
+  constructor(why: 'download' | 'live') {
+    super({
+      code: 'X_QUERY_ETAG_INVALID',
+      cause:
+        why === 'download'
+          ? 'query({ download, etag: true }) — a download answers its own ETag on the file it serves'
+          : 'query({ live: true, etag: true }) — a live read is revalidated by its cursor, not a validator',
+      fix: "query({ input, policy, sql })  # the declaration the cause names, with etag: true removed; a live read's cursor is its validator",
+      meta: { why },
+    });
+  }
+}
+
+export class QueryTimeoutInvalidError extends UltimateError {
+  constructor(value: unknown, why: string) {
+    super({
+      code: 'X_QUERY_TIMEOUT_INVALID',
+      cause: `query({ timeoutMs: ${renderCauseValue(value)} }) — ${why}`,
+      fix: 'query({ timeoutMs: 500 })  # a whole number of ms under the role bound, read with: psql "$DATABASE_URL" -c "show statement_timeout" — or drop timeoutMs',
+    });
+  }
+}
+
+export interface FreshnessDecl {
+  readonly etag?: unknown;
+  readonly live?: boolean | undefined;
+  readonly timeoutMs?: unknown;
+  readonly cache?: { readonly ttlMs?: number; readonly negativeTtlMs?: number } | undefined;
+}
+
+/** A lease every tier refuses, refused here with the field that wrote it. */
+function assertLease(value: number | undefined, field: 'ttlMs' | 'negativeTtlMs'): void {
+  if (value === undefined) return;
+  if (!Number.isFinite(value) || value <= 0) throw new QueryCacheTtlInvalidError(value, field);
+}
+
+/** Rows reads. `download` reads go through `assertDownloadFreshness` instead. */
+export function assertFreshness(def: FreshnessDecl): void {
+  assertLease(def.cache?.ttlMs, 'ttlMs');
+  assertLease(def.cache?.negativeTtlMs, 'negativeTtlMs');
+  if (def.etag === true && def.live === true) throw new QueryEtagInvalidError('live');
+  const timeoutMs = def.timeoutMs;
+  if (timeoutMs === undefined) return;
+  if (typeof timeoutMs !== 'number' || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new QueryTimeoutInvalidError(timeoutMs, 'a bound is a whole number of ms above 0');
+  }
+}
+
+/** A download has its own validators and no `sql` to bound: both options are refused beside it. */
+export function assertDownloadFreshness(def: object): void {
+  if ('etag' in def && def.etag !== undefined) throw new QueryEtagInvalidError('download');
+  if ('timeoutMs' in def && def.timeoutMs !== undefined) {
+    throw new QueryTimeoutInvalidError(def.timeoutMs, 'a download read runs no sql to bound');
+  }
+}

package/src/read.ts

@@ -5,22 +5,29 @@
  * payload, and none of them can become a second read path or a second authz path.
  */
 
+import type { CacheTag } from '@ultimat3/cache';
 import type { Ctx } from '@ultimat3/core';
 import {
   actorOf,
   anonymousActor,
   assert,
   ctxOf,
+  failureCaptureActive,
   finiteOption,
   logger,
+  REDACTED,
+  recordFailureInput,
   runWithContext,
   tryUseContext,
   useContext,
   withChildContext,
+  withFailureCapture,
   withSpan,
 } from '@ultimat3/core';
+import { withStatementTimeout } from '@ultimat3/db';
+import { statusFor } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { formatPath, validateAsync } from '@ultimat3/schema';
+import { formatPath, maskSensitive, validateAsync } from '@ultimat3/schema';
 import type { ReadAudit, ReadTrace } from './audit-gate';
 import { audited, auditedBuild, readAuditFor } from './audit-gate';
 import {
@@ -31,6 +38,7 @@ import {
   readOnce,
   readThrough,
 } from './cache';
+import { judgedRead, judgedSql } from './declared-errors';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
 import { guardQuery, guardQueryBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
@@ -88,12 +96,15 @@ export function runQuery(
   raw: unknown,
   options: QueryOptions = {},
 ): Promise<readonly object[]> {
-  return asActor(options, (ctx) => {
-    const audit = auditFor(target, ctx, options);
-    return audit === null
-      ? readRows(target, raw, ctx, options, null)
-      : audited(audit, () => readRows(target, raw, ctx, options, audit.trace));
-  });
+  // A 5xx keeps a replayable bundle when `failureCapture` is on (`x repro`); off, it reads bare.
+  return asActor(options, (ctx) =>
+    withFailureCapture('query', queryName(target), statusFor, () => {
+      const audit = auditFor(target, ctx, options);
+      return audit === null
+        ? readRows(target, raw, ctx, options, null)
+        : audited(audit, () => readRows(target, raw, ctx, options, audit.trace));
+    }),
+  );
 }
 
 /**
@@ -217,9 +228,16 @@ async function readRowsIn(
   // Whether THIS call executed, for the audit record: a memo or tier hit never calls `read`, and
   // its record says so (`replayed: true`) rather than being skipped.
   if (trace !== null) trace.replayed = true;
+  // `timeoutMs` runs the source inside its own bounded read transaction — on the primary, since a
+  // transaction is pinned there. Inside `judgedRead`, so a fired bound is judged like any refusal.
+  const bound = def.timeoutMs;
+  const execute =
+    bound === undefined
+      ? () => source.execute()
+      : () => withStatementTimeout(bound, () => source.execute());
   const read = (): Promise<readonly object[]> => {
     if (trace !== null) trace.replayed = false;
-    return source.execute();
+    return judgedRead(target, name, execute);
   };
   // The source came from this query's own `sql()`, so its rows are TRow throughout —
   // which is what the typed overload above states, and this body never has to assert.
@@ -242,13 +260,41 @@ async function readRowsIn(
   // the process — a paginated feed over 10k tenants is 10k immortal entries.
   return def.cache === undefined
     ? await readOnce(ctx, key, read)
-    : await readThrough(
-        ctx,
-        key,
-        finiteOption('the read cache', 'ttlMs', def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS),
-        read,
-        tags,
-      );
+    : await readThroughLeased(ctx, key, def, read, tags);
+}
+
+/**
+ * The tier read with both leases. Only a `single: true` read can answer "none": its miss is stored
+ * as `null`, so the stack gives it `negativeTtlMs` — and an empty LIST stays a list with `ttlMs`.
+ */
+async function readThroughLeased(
+  ctx: Ctx,
+  key: string,
+  def: AnyQueryDef,
+  read: () => Promise<readonly object[]>,
+  tags: readonly CacheTag[],
+): Promise<readonly object[]> {
+  const ttlMs = finiteOption(
+    'the read cache',
+    'ttlMs',
+    def.cache?.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS,
+  );
+  const negativeTtlMs = def.cache?.negativeTtlMs;
+  if (def.single !== true || negativeTtlMs === undefined) {
+    return readThrough(ctx, key, ttlMs, read, tags);
+  }
+  const held = await readThrough(
+    ctx,
+    key,
+    ttlMs,
+    async (): Promise<readonly object[] | null> => {
+      const rows = await read();
+      return rows.length === 0 ? null : rows;
+    },
+    tags,
+    negativeTtlMs,
+  );
+  return held ?? [];
 }
 
 async function buildSource(
@@ -258,6 +304,46 @@ async function buildSource(
   options: SourceOptions,
   trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
+  const input = await admit(target, raw, ctx, options, trace);
+  // `sql` and the source's `execute` are where `errors:` judges a throw (`declared-errors.ts`).
+  const source = judgedSql(target, queryName(target), () => defOf(target).sql(input, ctx));
+  // A live window is served in the order its patches are placed in. The matcher breaks a tie on
+  // the declared keys with `id` (`totalOrder`) and so does the keyset re-read a reconnect resumes
+  // with, so an initial window served in the declared keys alone puts tied rows where neither of
+  // them would: the client renders one order and the next read answers another. A source that
+  // cannot say (`total` absent) already serves one order it can be resumed in.
+  return options.surface === 'live' && source.total !== undefined ? source.total() : source;
+}
+
+/**
+ * One whole call for a read that is ANSWERED by something other than `sql` — a download's file,
+ * or the URL minted for it. The same front half every surface shares (actor, audit, the declared
+ * limit, the parse, the policy), so a download is not a second read path: only what is done with
+ * the admitted input differs. `options.unenforced` is honoured exactly as `sourceFor` honours it.
+ */
+export function admittedCall<T>(
+  target: AnyQuery,
+  raw: unknown,
+  options: SourceOptions,
+  use: (input: unknown, ctx: Ctx) => Promise<T>,
+): Promise<T> {
+  return asActor(options, async (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    if (audit === null) return use(await admit(target, raw, ctx, options, null), ctx);
+    return audited(audit, async () =>
+      use(await admit(target, raw, ctx, options, audit.trace), ctx),
+    );
+  });
+}
+
+/** Everything before `sql()`: the actor half, the declared limit, the parse, the policy. */
+async function admit(
+  target: AnyQuery,
+  raw: unknown,
+  ctx: Ctx,
+  options: SourceOptions,
+  trace: ReadTrace | null,
+): Promise<unknown> {
   const def = defOf(target);
   const name = queryName(target);
   const unenforced = options.unenforced;
@@ -273,7 +359,9 @@ async function buildSource(
     } catch (denial) {
       // The record still names what was attempted, as an action's does: the denial is already
       // decided, so parsing now tells the CALLER nothing, and an unparseable payload is no input.
-      if (trace !== null) trace.input = await parsedOrNothing(def.input, raw);
+      if (trace !== null) {
+        trace.input = maskSensitive(def.input, await parsedOrNothing(def.input, raw), REDACTED);
+      }
       throw denial;
     }
   }
@@ -291,7 +379,9 @@ async function buildSource(
     });
   }
   const input = await validate(def.input, raw, name);
-  if (trace !== null) trace.input = input;
+  if (failureCaptureActive()) recordFailureInput(maskSensitive(def.input, input, REDACTED));
+  // The audit record's copy, masked by THIS read's own schema — never a key table (`action`'s rule).
+  if (trace !== null) trace.input = maskSensitive(def.input, input, REDACTED);
   if (unenforced === undefined) {
     guardQuery(
       def.policy,
@@ -312,13 +402,7 @@ async function buildSource(
     // comparison when nothing is listening.
     logger.debug('query.policy.unenforced', { query: name, reason: unenforced });
   }
-  const source = def.sql(input, ctx);
-  // A live window is served in the order its patches are placed in. The matcher breaks a tie on
-  // the declared keys with `id` (`totalOrder`) and so does the keyset re-read a reconnect resumes
-  // with, so an initial window served in the declared keys alone puts tied rows where neither of
-  // them would: the client renders one order and the next read answers another. A source that
-  // cannot say (`total` absent) already serves one order it can be resumed in.
-  return options.surface === 'live' && source.total !== undefined ? source.total() : source;
+  return input;
 }
 
 /** The parse without the refusal — only for the record of a read already refused on other grounds. */

package/src/record-answer.ts

@@ -25,8 +25,8 @@ export type RecordAnswer = (answer: readonly object[] | Page<object>) => Respons
 export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswer {
   if (!answersRecords(rows)) return (answer) => jsonResponse(answer, datesOf(answer));
   return (answer) => {
-    const records = collect(rows, isPage(answer) ? answer.rows : answer);
-    return jsonResponse(encodeRecordEnvelope(answer, records), {
+    const { records, order } = collect(rows, isPage(answer) ? answer.rows : answer);
+    return jsonResponse(encodeRecordEnvelope(answer, records, undefined, order), {
       headers: { [RECORDS_HEADER]: '1', ...datesOf(answer).headers },
     });
   };
@@ -49,10 +49,12 @@ function datesOf(data: unknown): { readonly headers: Record<string, string> } {
  */
 export function recordRowAnswerFor(rows: StandardSchemaV1 | undefined): (row: object) => Response {
   if (!answersRecords(rows)) return (row) => jsonResponse(row, datesOf(row));
-  return (row) =>
-    jsonResponse(encodeRecordEnvelope(row, collect(rows, [row])), {
+  return (row) => {
+    const { records, order } = collect(rows, [row]);
+    return jsonResponse(encodeRecordEnvelope(row, records, undefined, order), {
       headers: { [RECORDS_HEADER]: '1', ...datesOf(row).headers },
     });
+  };
 }
 
 /** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */
@@ -69,11 +71,18 @@ function isPage(answer: readonly object[] | Page<object>): answer is Page<object
  * 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.
+ *
+ * `order` is each type's keys as the answer met them. An integer-like key is an array index to
+ * every object, so the records object re-sorts it; `encodeRecordEnvelope` sends the order only for
+ * a type whose object lost it, so a uuid-keyed answer's body is what it always was.
  */
 function collect(
   schema: StandardSchemaV1,
   list: readonly object[],
-): Readonly<Record<string, RecordRows>> {
+): {
+  readonly records: Readonly<Record<string, RecordRows>>;
+  readonly order: Readonly<Record<string, readonly string[]>>;
+} {
   const out = new Map<string, Map<string, Row>>();
   for (const row of list) {
     for (const [type, byKey] of Object.entries(rowsOf(schema, row))) {
@@ -83,7 +92,10 @@ function collect(
         if (!bucket.has(key)) bucket.set(key, found);
     }
   }
-  return nullProto([...out].map(([type, bucket]) => [type, nullProto(bucket)] as const));
+  return {
+    records: nullProto([...out].map(([type, bucket]) => [type, nullProto(bucket)] as const)),
+    order: nullProto([...out].map(([type, bucket]) => [type, [...bucket.keys()]] as const)),
+  };
 }
 
 function nullProto<V>(entries: Iterable<readonly [string, V]>): Readonly<Record<string, V>> {

package/src/registry.ts

@@ -4,6 +4,7 @@
  * identifier the source file uses.
  */
 import { registerPrimitiveRegistrar } from '@ultimat3/core';
+import { assertNoSensitiveOutput } from '@ultimat3/schema';
 import { QueryDuplicateError, QueryPolicyMissingError } from './errors';
 import type { AnyQuery, QueryDescriptor } from './query';
 import { isQuery, nameQuery } from './query';
@@ -28,6 +29,9 @@ export function registerQuery<Q extends AnyQuery>(name: string, target: Q): Q {
   if (target.policy === undefined || target.policy === null) {
     throw new QueryPolicyMissingError(name);
   }
+  // Rows are sent back, which `.sensitive()` (`writeOnly`) forbids. PII read back and only hidden
+  // in logs is `redactKeys`, not this flag.
+  if (target.rows !== undefined) assertNoSensitiveOutput(`query "${name}" rows`, target.rows);
   const named = nameQuery(target, name);
   registry.set(name, named);
   return named;

package/src/search-string.ts

@@ -0,0 +1,47 @@
+// The read's input as a search string — the ONE encoding the typed client sends and a download's
+// minted URL carries, so the route's `coerceQuery` reads both back the same way. A leaf: the
+// browser client imports it, and it imports nothing that registers a code table.
+
+import { isJsonObject } from '@ultimat3/core/page';
+import type { PageControls } from './page-controls';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
+
+/**
+ * Input as a query string. Keys are sorted so the same input always produces the
+ * same URL — a GET is a cache key, and an unstable one caches nothing.
+ *
+ * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
+ * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
+ * split at `_first=` to recover the read underneath.
+ *
+ * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
+ * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
+ */
+export function searchOf(input: unknown, page?: PageControls): string {
+  const params = new URLSearchParams();
+  if (isJsonObject(input)) {
+    for (const key of Object.keys(input).sort()) {
+      const value = input[key];
+      if (value === undefined || value === null) continue;
+      for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
+        params.append(key, wireText(item));
+      }
+    }
+  }
+  if (page !== undefined) {
+    params.append(PAGE_FIRST_KEY, String(page.first));
+    if (page.after !== undefined) params.append(PAGE_AFTER_KEY, page.after);
+  }
+  return params.toString();
+}
+
+/**
+ * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
+ * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
+ * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
+ * as the text it prints and the read's own schema says what is wrong with it.
+ */
+function wireText(item: unknown): string {
+  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
+  return typeof item === 'object' ? JSON.stringify(item) : String(item);
+}

package/src/sql.ts

@@ -62,7 +62,8 @@ export async function describeSql(
     // `Object.hasOwn`, because `samples` is a caller's object literal and a name it never carried
     // — `constructor`, `toString` — would otherwise resolve to a FUNCTION and be parsed as input.
     const sample = Object.hasOwn(samples, name) ? samples[name] : undefined;
-    if (sample === undefined) {
+    // A download has no statement to render, sample or not: it answers a file.
+    if (sample === undefined || target.download === true) {
       entries.push({ query: name, live: target.isLive, sql: null });
       continue;
     }

package/src/type-pins.ts

@@ -5,6 +5,13 @@
 
 import type { McpExposureDeclaration } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { QueryClient } from './client';
+import type {
+  DownloadClientMethod,
+  DownloadQuery,
+  DownloadQueryDef,
+  QueryDownload,
+} from './download';
 import type { AnyQuery, Query, QueryDef } from './query';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
@@ -60,3 +67,41 @@ export type _NoQueryMcpTwin = import('./index').QueryMcp;
 export type _NoQueryMcpAnnotationsTwin = import('./index').QueryMcpAnnotations;
 // @ts-expect-error — `QueryListParams` is core's `McpListParams`.
 export type _NoQueryListParamsTwin = import('./index').QueryListParams;
+
+/**
+ * A download query's client is `url()` and nothing else: no rows call, no `page` — the route
+ * answers a minted URL or a file, never rows, so a method that promised rows would be a lie.
+ */
+type DownloadInput = StandardSchemaV1<{ runId: string }, { runId: string }>;
+export type _DownloadClientIsUrlOnly = Assert<
+  Identical<
+    QueryClient<{ rec: DownloadQuery<DownloadInput> }>['rec'],
+    DownloadClientMethod<DownloadInput>
+  >
+>;
+/** And a download declares no rows option: `sql` beside `download` does not compile. */
+export type _DownloadDeclaresNoSql = Assert<
+  Equals<NonNullable<DownloadQueryDef<DownloadInput>['sql']>, never>
+>;
+
+/**
+ * And the other way: a rows declaration names `download?: never`, so a VARIABLE holding both `sql`
+ * and `download` (no excess-property check reaches one) matches neither overload — a compile
+ * error where it is written, never `X_QUERY_DOWNLOAD_INVALID` on the first call.
+ */
+type RowsDownload =
+  QueryDef<DownloadInput, object> extends { readonly download?: infer D } ? D : 'absent';
+export type _RowsDeclareNoDownload = Assert<Equals<NonNullable<RowsDownload>, never>>;
+export type _BothDoNotCompile = Assert<
+  Equals<
+    {
+      input: DownloadInput;
+      policy: QueryDef<DownloadInput, object>['policy'];
+      sql: () => never;
+      download: QueryDownload<DownloadInput>;
+    } extends QueryDef<DownloadInput, object> | DownloadQueryDef<DownloadInput>
+      ? true
+      : false,
+    false
+  >
+>;