@ultimat3/query 29.4.0 → 30.1.0

package/src/errors.ts

@@ -35,6 +35,9 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   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',
 };
 
 /**
@@ -44,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.
@@ -158,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' };
+}

package/src/http.ts

@@ -7,17 +7,26 @@
 
 import { tagKeys } from '@ultimat3/cache';
 import type { Deprecation } from '@ultimat3/core';
-import { queryPath, recordDeprecatedCall, renderDeprecation, useContext } from '@ultimat3/core';
+import {
+  mergePathParams,
+  queryPath,
+  recordDeprecatedCall,
+  renderDeprecation,
+  templateParams,
+  useContext,
+} from '@ultimat3/core';
 import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
 import { publishRateLimit, toBucket } from '@ultimat3/http';
 import { admitsAnonymous, policyCapability } from '@ultimat3/policy';
 import { coerceQuery } from '@ultimat3/schema';
 import { toDownloadRoute } from './download-http';
 import { QueryDeprecationInvalidError, QueryInputInvalidError } from './errors';
+import { withValidator } from './http-etag';
+import { servedQueryPath } from './http-pin';
 import { absentArraysOf } from './input-shape';
 import { PAGE_FIRST_KEY, pageControlsOf } from './page-controls';
 import type { AnyQuery, QueryRateLimit } from './query';
-import { queryName, runQuery } from './read';
+import { defOf, queryName, runQuery } from './read';
 import { recordAnswerFor, recordRowAnswerFor } from './record-answer';
 import { oneRowOf } from './single-answer';
 
@@ -34,8 +43,19 @@ export function toQueryRoute(target: AnyQuery): Route {
   if (target.download === true) return toDownloadRoute(target, name, sunsetting);
   const answer = recordAnswerFor(target.rows);
   const answerRow = recordRowAnswerFor(target.rows);
+  // A pinned `http.path` replaces `/_x/query/<kebab>`; its `:param`s join the search string as
+  // the one input, and a search string naming one differently is `X_HTTP_PATH_INPUT_CONFLICT`.
+  const path = servedQueryPath(name, defOf(target).http);
+  const pinned = templateParams(path).length > 0;
+  const owner = `query "${name}"`;
+  const etagged = defOf(target).etag === true;
 
   const handler = async (request: UltimateRequest): Promise<Response> => {
+    const answered = await answerRead(request);
+    return etagged ? withValidator(request, answered) : answered;
+  };
+
+  const answerRead = async (request: UltimateRequest): Promise<Response> => {
     if (sunsetting !== undefined) {
       recordDeprecatedCall('query', name);
       // On the CONTEXT, before anything can fail: the pipeline's `response` stage merges
@@ -68,7 +88,19 @@ export function toQueryRoute(target: AnyQuery): Route {
       onRateLimit: (decision: RateLimitDecision) =>
         publishRateLimit(request.ctx, decision, useContext().now().getTime()),
     } as const;
-    const { input: values, page } = pageControlsOf(name, request.queryRaw());
+    const search = request.queryRaw();
+    const { input: values, page } = pageControlsOf(
+      name,
+      pinned
+        ? // The search values plus string params: still `SearchValues` by construction.
+          (mergePathParams({
+            owner,
+            template: path,
+            params: request.params,
+            raw: search,
+          }) as typeof search)
+        : search,
+    );
     const input = absentArraysOf(target.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
@@ -122,6 +154,8 @@ export function toQueryRoute(target: AnyQuery): Route {
     // one actor's rows to the next caller of that URL, so a read is `no-store` and a
     // shared cache is something a CDN in front of the app configures knowingly. The tags
     // ride along so a purge can still name the read the tier keys by.
+    // `etag: true` is the declared exception: its handler writes `private, no-cache` itself
+    // (`http-etag.ts`), which the stage leaves alone, and this hint is never reached.
     cache: { mode: 'no-store', tags: tagKeys(target.cache?.tags ?? []) },
     tags: ['query'],
     // The read spends its own declared bucket on every surface (`read.ts`), so the stage spends
@@ -135,7 +169,7 @@ export function toQueryRoute(target: AnyQuery): Route {
     ...(target.mcp?.description === undefined ? {} : { description: target.mcp.description }),
   };
 
-  return { method: 'GET', path: queryPath(name), handler, meta };
+  return { method: 'GET', path, handler, meta };
 }
 
 /** Validates the declaration through the limiter's own conversion, then hands the route its flag. */

package/src/index.ts

@@ -68,12 +68,15 @@ export { downloadClientFor, queryClient, queryClientMethodFor } from './client';
  */
 export type { KindOf } from './column-kinds';
 export { kindsOf } from './column-kinds';
+export type { QueryContractTest, QueryContractTestOptions } from './contract-test';
+export { queryContractTestsFor } from './contract-test';
 /**
  * `query({ download })` — a read answered by a FILE at a short-lived signed URL. Still a `query`:
  * one policy, one name, one route (`GET /_x/query/<kebab>`: mint without `_token`, serve with it).
  */
 export type {
   DownloadArgs,
+  DownloadBodyOpener,
   DownloadClientMethod,
   DownloadFile,
   DownloadQuery,
@@ -110,10 +113,22 @@ export {
   QuerySubscribesInvalidError,
   QueryUnregisteredError,
 } from './errors';
+export type {
+  QueryExerciseActorOptions,
+  QueryExerciseOffOptions,
+  QueryExerciseOptions,
+  QueryExerciseReport,
+} from './exercise';
+export { exerciseQuery } from './exercise';
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
 export { toQueryRoute } from './http';
+export type { QueryHttp } from './http-pin';
+export { queryHttpPinOf } from './http-pin';
+export { QueryHttpPathInvalidError } from './http-pin-error';
 export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } from './live';
 export { planResume, seekOf, spendQueryLimit, toLiveQuery } from './live';
+export type { LiveReadPhase } from './live-trace';
+export { traceLiveRead } from './live-trace';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
 /**

package/src/live-trace.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the span a LIVE read runs in, continued from the subscriber's own
+// `traceparent`. The snapshot answers the subscribe, so it is that trace's child; a re-run answers
+// a change, not a request, so it LINKS to the subscriber and parents on whatever caused it.
+
+import { parseTraceparent, withSpan } from '@ultimat3/core';
+
+/** Which read: the one a subscribe asked for, or one a change fanned out. */
+export type LiveReadPhase = 'snapshot' | 'rerun';
+
+/**
+ * Runs `read` inside `live.<phase> <query>`. `traceparent` is the value the client put on its
+ * `subscribe` frame; an invalid or absent one is IGNORED, as an unknown time zone is: a garbage
+ * header must cost the subscriber its trace, never its subscription.
+ */
+export function traceLiveRead<T>(
+  query: string,
+  phase: LiveReadPhase,
+  traceparent: string | null | undefined,
+  read: () => Promise<T>,
+): Promise<T> {
+  const subscriber = parseTraceparent(traceparent);
+  const name = `live.${phase} ${query}`;
+  const attributes = { 'ultimate.primitive': 'query', 'ultimate.query': query };
+  if (phase === 'snapshot') {
+    return withSpan(name, read, {
+      kind: 'server',
+      attributes,
+      ...(subscriber === undefined ? {} : { parent: subscriber }),
+    });
+  }
+  return withSpan(name, read, {
+    kind: 'internal',
+    attributes,
+    links: subscriber === undefined ? [] : [subscriber],
+  });
+}

package/src/live.ts

@@ -8,6 +8,7 @@
  */
 import { tagKeys } from '@ultimat3/cache';
 import type { Ctx } from '@ultimat3/core';
+import { appVersion } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Patch } from './matcher';
 import { assertMatchable } from './matcher';
@@ -119,9 +120,9 @@ export function spendQueryLimit(
   return spendReadLimit(queryName(target), target.rateLimit, { ...caller, surface: 'live' });
 }
 
-/** Changing the build changes the epoch, which forces reconnects to refetch. */
+/** Changing the build changes the epoch, which forces reconnects to refetch: core's `APP_VERSION`. */
 export function liveEpoch(): string {
-  return Bun.env['X_BUILD_ID'] ?? 'dev';
+  return appVersion();
 }
 
 export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends object>(

package/src/openapi-errors.ts

@@ -0,0 +1,19 @@
+// Single responsibility: a read operation's `responses` with its declared `errors:` in them —
+// core's builder, bound to `@ultimat3/http`'s status table and Problem `type`; the `Problem` ref is
+// `openapi.ts`'s own, handed in. Undeclared, the members are today's.
+
+import { withDeclaredResponses } from '@ultimat3/core';
+import { declaredStatusFor, problemTypeFor } from '@ultimat3/http';
+import type { AnyQuery } from './query';
+
+export function withDeclaredErrors(
+  target: AnyQuery,
+  problemRef: string,
+  responses: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  return withDeclaredResponses(responses, target.errors, {
+    statusOf: declaredStatusFor,
+    typeFor: problemTypeFor,
+    problemRef,
+  });
+}

package/src/openapi-etag.ts

@@ -0,0 +1,43 @@
+// Single responsibility: what `etag: true` adds to a read's OpenAPI operation — the `If-None-Match`
+// header parameter, the `ETag` on the 200, and the bodiless 304. Applied after the operation is
+// built, so the list and single operations stay one description each.
+
+const IF_NONE_MATCH = {
+  name: 'If-None-Match',
+  in: 'header',
+  required: false,
+  description: 'The ETag of an answer this caller already holds; a match is 304 with no body.',
+  schema: { type: 'string' },
+} as const;
+
+const ETAG_HEADER = {
+  ETag: {
+    description: 'A strong validator of this answer, for this caller. Send it as If-None-Match.',
+    schema: { type: 'string' },
+  },
+} as const;
+
+type Operation = Readonly<Record<string, unknown>>;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** `operation` documenting its validator. An operation with no 200 is returned unchanged. */
+export function withValidatorDoc(operation: Operation): Operation {
+  const responses = operation['responses'];
+  const parameters = operation['parameters'];
+  if (!isRecord(responses) || !Array.isArray(parameters)) return operation;
+  const ok = responses['200'];
+  if (!isRecord(ok)) return operation;
+  const headers = isRecord(ok['headers']) ? ok['headers'] : {};
+  return {
+    ...operation,
+    // Last, after the page controls: a header is not one of the read's input members.
+    parameters: [...parameters, IF_NONE_MATCH],
+    responses: {
+      ...responses,
+      '200': { ...ok, headers: { ...headers, ...ETAG_HEADER } },
+      '304': { description: 'not modified — the If-None-Match validator still names this answer' },
+    },
+  };
+}