@ultimat3/query 29.4.0 → 30.1.0

package/src/openapi.ts

@@ -18,18 +18,22 @@
 import { tagKeys } from '@ultimat3/cache';
 import {
   isMcpExposed,
-  queryPath,
   RECORDS_OPENAPI_HEADER,
   recordEnvelopeSchema,
+  templateParams,
+  toOpenApiPath,
 } from '@ultimat3/core';
 import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { policyCapability } from '@ultimat3/policy';
 import type { SchemaNode } from '@ultimat3/schema';
-import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
+import { nodeToJsonSchema, toWireOutputSchema, tryIntrospect } from '@ultimat3/schema';
 import { DOWNLOAD_GRANT_PARAM } from './download-token';
+import { servedQueryPath } from './http-pin';
+import { withDeclaredErrors } from './openapi-errors';
+import { withValidatorDoc } from './openapi-etag';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import type { AnyQuery } from './query';
-import { queryName } from './read';
+import { defOf, queryName } from './read';
 import { answersRecords } from './record-answer';
 import { listQueries } from './registry';
 
@@ -44,33 +48,53 @@ const QUERY_TAG = 'query';
 
 export type OpenApiPathItem = Record<string, unknown>;
 
+/** Today's answer for a read that publishes no row: any item, any object. */
+const UNTYPED_ITEM: Readonly<Record<string, unknown>> = {};
+const UNTYPED_ROW: Readonly<Record<string, unknown>> = { type: 'object' };
+
+/**
+ * The one row a read declares, or `undefined` when it declares none or none this package can read
+ * — the narrowing `@ultimat3/mcp` publishes as the same read's `outputSchema`, so the two surfaces
+ * cannot disagree. STRUCTURE only: a read's rows are never re-parsed, so a bound or a closed object
+ * is a promise nothing enforces on the way out. Inline, never a component: the CLI merges only
+ * `paths` from this package (`packages/cli/src/app-openapi.ts`).
+ */
+const rowOf = (target: AnyQuery): Readonly<Record<string, unknown>> | undefined => {
+  const row = toWireOutputSchema(target.rows);
+  return row === undefined ? undefined : { ...row };
+};
+
 /**
  * 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',
-    // The one page shape: the `endCursor`/`hasNextPage` alias pair left in 25.0.0 (O-12).
-    required: ['rows', 'nextCursor', 'hasMore'],
-    properties: {
-      rows: { type: 'array', items: {} },
-      nextCursor: {
-        type: ['string', 'null'],
-        description: `the signed cursor for the next page — send it as ${PAGE_AFTER_KEY}; null exactly when hasMore is false`,
+function listAnswers(
+  item: Readonly<Record<string, unknown>> = UNTYPED_ITEM,
+): readonly Record<string, unknown>[] {
+  return [
+    { type: 'array', items: item },
+    {
+      type: 'object',
+      // The one page shape: the `endCursor`/`hasNextPage` alias pair left in 25.0.0 (O-12).
+      required: ['rows', 'nextCursor', 'hasMore'],
+      properties: {
+        rows: { type: 'array', items: item },
+        nextCursor: {
+          type: ['string', 'null'],
+          description: `the signed cursor for the next page — send it as ${PAGE_AFTER_KEY}; null exactly when hasMore is false`,
+        },
+        hasMore: { type: 'boolean', description: 'whether another page follows' },
       },
-      hasMore: { type: 'boolean', description: 'whether another page follows' },
+      // `@ultimat3/core`'s `Page` is a union, and so is its wire shape: the two facts cannot
+      // disagree in a body this document validates (25.0.0 — the last page used to keep a cursor).
+      oneOf: [
+        { properties: { nextCursor: { type: 'string' }, hasMore: { const: true } } },
+        { properties: { nextCursor: { type: 'null' }, hasMore: { const: false } } },
+      ],
     },
-    // `@ultimat3/core`'s `Page` is a union, and so is its wire shape: the two facts cannot
-    // disagree in a body this document validates (25.0.0 — the last page used to keep a cursor).
-    oneOf: [
-      { properties: { nextCursor: { type: 'string' }, hasMore: { const: true } } },
-      { properties: { nextCursor: { type: 'null' }, hasMore: { const: false } } },
-    ],
-  },
-];
+  ];
+}
 
 /** `{ [path]: { get: operation } }` for every registered read, name-sorted like the actions. */
 export function queryOpenApiPaths(
@@ -78,11 +102,14 @@ export function queryOpenApiPaths(
 ): Record<string, OpenApiPathItem> {
   const paths: Record<string, OpenApiPathItem> = {};
   for (const target of [...queries].sort(compareByName)) {
-    paths[queryPath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
+    paths[toOpenApiPath(pathOf(target))] = { get: toQueryOpenApiOperation(target) };
   }
   return paths;
 }
 
+/** Where the read is served: its pin (a `:param` template), else `/_x/query/<kebab>`. */
+const pathOf = (target: AnyQuery): string => servedQueryPath(queryName(target), defOf(target).http);
+
 /**
  * The GET operation for one read. The input's members are `in: query` parameters — a read is
  * served from its search string (`input-shape.ts` is what guarantees every member fits one) — and
@@ -92,14 +119,20 @@ export function queryOpenApiPaths(
 export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknown> {
   const name = queryName(target);
   if (target.download === true) return downloadOperation(target, name);
+  const operation = rowsOperation(target, name);
+  return defOf(target).etag === true ? { ...withValidatorDoc(operation) } : operation;
+}
+
+function rowsOperation(target: AnyQuery, name: string): Record<string, unknown> {
   if (target.single === true) return singleOperation(target, name);
+  const answers = { oneOf: listAnswers(rowOf(target)) };
   return {
     operationId: name,
     tags: [QUERY_TAG],
     summary: target.mcp?.description ?? name,
     ...(target.deprecated === undefined ? {} : { deprecated: true }),
-    parameters: [...inputParameters(target.input), ...PAGE_PARAMETERS],
-    responses: {
+    parameters: [...inputParameters(target), ...PAGE_PARAMETERS],
+    responses: withDeclaredErrors(target, PROBLEM_SCHEMA_REF, {
       '200': {
         description: 'ok',
         content: {
@@ -109,9 +142,7 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
             // second operation — it is one route, one policy evaluation, one URL prefix.
             // 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 },
+            schema: answersRecords(target.rows) ? recordEnvelopeSchema(answers) : answers,
           },
         },
         ...(answersRecords(target.rows) ? { headers: RECORDS_OPENAPI_HEADER } : {}),
@@ -119,9 +150,9 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
       // `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
       // are the caller's to repair, which is what 400 says.
-      '400': problemResponse('X_INPUT_INVALID or X_CURSOR_INVALID'),
+      '400': problemResponse(`X_INPUT_INVALID or X_CURSOR_INVALID${conflictOf(target)}`),
       '403': problemResponse('policy denied'),
-    },
+    }),
     'x-ultimate': {
       capability: policyCapability(target.policy),
       live: target.isLive,
@@ -140,26 +171,27 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
  */
 function singleOperation(target: AnyQuery, name: string): Record<string, unknown> {
   const records = answersRecords(target.rows);
+  const answer = rowOf(target) ?? UNTYPED_ROW;
   return {
     operationId: name,
     tags: [QUERY_TAG],
     summary: target.mcp?.description ?? name,
     ...(target.deprecated === undefined ? {} : { deprecated: true }),
-    parameters: inputParameters(target.input),
-    responses: {
+    parameters: inputParameters(target),
+    responses: withDeclaredErrors(target, PROBLEM_SCHEMA_REF, {
       '200': {
         description: 'ok',
         content: {
           'application/json': {
-            schema: records ? recordEnvelopeSchema(SINGLE_ANSWER) : SINGLE_ANSWER,
+            schema: records ? recordEnvelopeSchema(answer) : answer,
           },
         },
         ...(records ? { headers: RECORDS_OPENAPI_HEADER } : {}),
       },
-      '400': problemResponse('X_INPUT_INVALID'),
+      '400': problemResponse(`X_INPUT_INVALID${conflictOf(target)}`),
       '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,
@@ -181,7 +213,7 @@ function downloadOperation(target: AnyQuery, name: string): Record<string, unkno
     summary: name,
     ...(target.deprecated === undefined ? {} : { deprecated: true }),
     parameters: [
-      ...inputParameters(target.input),
+      ...inputParameters(target),
       {
         name: DOWNLOAD_GRANT_PARAM,
         in: 'query',
@@ -232,9 +264,6 @@ const MINTED_URL: Readonly<Record<string, unknown>> = {
   },
 };
 
-/** 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>[] = [
   {
@@ -253,24 +282,44 @@ const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
   },
 ];
 
+/** A pinned read's 400 also names the path/search disagreement; an unpinned one's bytes stay. */
+const conflictOf = (target: AnyQuery): string =>
+  templateParams(pathOf(target)).length === 0 ? '' : ' or X_HTTP_PATH_INPUT_CONFLICT';
+
 /**
- * A member per declared property, name-sorted. A schema this package cannot introspect — a
- * foreign Standard Schema, the seam `configureSchemaProvider` exists for — publishes no
- * parameters rather than guessed ones, the same answer `assertEncodableInput` gives it.
+ * A member per declared property: the pin's `:param`s first, `in: path` and required, in template
+ * order; the rest `in: query`, name-sorted. A schema this package cannot introspect — a foreign
+ * Standard Schema, the seam `configureSchemaProvider` exists for — publishes no parameters rather
+ * than guessed ones, the same answer `assertEncodableInput` gives it.
  */
-function inputParameters(input: unknown): readonly Record<string, unknown>[] {
-  const node = tryIntrospect(input);
+function inputParameters(target: AnyQuery): readonly Record<string, unknown>[] {
+  const node = tryIntrospect(target.input);
   if (node?.properties === undefined) return [];
-  return Object.entries(node.properties)
-    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-    .map(([key, child]) => parameterOf(key, child));
+  const properties = node.properties;
+  const inPath = templateParams(pathOf(target));
+  const fromPath = inPath.flatMap((key) => {
+    const child = Object.hasOwn(properties, key) ? properties[key] : undefined;
+    return child === undefined ? [] : [parameterOf(key, child, 'path')];
+  });
+  return [
+    ...fromPath,
+    ...Object.entries(properties)
+      .filter(([key]) => !inPath.includes(key))
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, child]) => parameterOf(key, child, 'query')),
+  ];
 }
 
-function parameterOf(name: string, node: SchemaNode): Record<string, unknown> {
+function parameterOf(
+  name: string,
+  node: SchemaNode,
+  where: 'path' | 'query',
+): Record<string, unknown> {
   return {
     name,
-    in: 'query',
-    required: node.optional !== true && node.hasDefault !== true,
+    in: where,
+    // A path parameter is required by OpenAPI's rule, and by `assertQueryHttp`'s at `query()`.
+    required: where === 'path' || (node.optional !== true && node.hasDefault !== true),
     schema: nodeToJsonSchema(node),
   };
 }

package/src/query.ts

@@ -15,15 +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 type { QueryContractTest, QueryContractTestOptions } from './contract-test';
 import type { DownloadQuery, DownloadQueryDef, QueryDownload } from './download';
 import { assertDownloadDef, buildDownloadQuery } from './download';
-import { QueryCacheTtlInvalidError, QuerySingleInvalidError } from './errors';
+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';
 
@@ -36,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.
@@ -102,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;
@@ -120,6 +143,10 @@ 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`.
@@ -199,6 +226,7 @@ export interface QueryDescriptor {
   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;
 }
 
 /**
@@ -215,10 +243,13 @@ 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>;
 }
@@ -244,6 +275,7 @@ export interface AnyQuery {
   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;
@@ -277,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. */
@@ -295,10 +329,12 @@ export type QueryFacade<
   | 'mcp'
   | 'rateLimit'
   | 'deprecated'
+  | 'errors'
   | 'as'
   | 'page'
   | 'live'
   | 'client'
+  | 'contract'
 >;
 
 /**
@@ -324,11 +360,13 @@ export function query<
   // 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);
+  if (!isDownloadDef(def)) assertQueryHttp(def.http, def.input);
   if (isDownloadDef(def)) {
+    assertDownloadFreshness(def);
     assertDownloadDef(def);
     return buildDownloadQuery(def, '', describeQuery);
   }
-  assertCacheTtl(def.cache);
+  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.
@@ -349,18 +387,6 @@ function isDownloadDef<TInput extends StandardSchemaV1>(
   return 'download' in def && def.download !== undefined;
 }
 
-/**
- * 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);
-}
-
 /**
  * Structural, not nominal: an object only counts as a query if `query()` built it,
  * because only then does a declaration exist for `sourceFor` to read. A look-alike
@@ -422,6 +448,7 @@ export function describeQuery(target: AnyQuery): QueryDescriptor {
     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(
@@ -259,7 +305,8 @@ async function buildSource(
   trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
   const input = await admit(target, raw, ctx, options, trace);
-  const source = defOf(target).sql(input, ctx);
+  // `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
@@ -312,7 +359,9 @@ async function admit(
     } 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;
     }
   }
@@ -330,7 +379,9 @@ async function admit(
     });
   }
   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,