@ultimat3/query 29.3.2 → 30.0.0

package/src/http.ts

@@ -7,16 +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';
 
@@ -30,10 +40,22 @@ export function toQueryRoute(target: AnyQuery): Route {
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first read.
   const sunsetting = deprecationHeadersFor(name, target.deprecated);
+  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
@@ -66,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
@@ -120,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
@@ -133,11 +169,11 @@ 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. */
-function rateLimitedByHandler(name: string, limit: QueryRateLimit): 'handler' {
+export function rateLimitedByHandler(name: string, limit: QueryRateLimit): 'handler' {
   toBucket(name, limit);
   return 'handler';
 }

package/src/index.ts

@@ -47,6 +47,7 @@ export {
   requestMemo,
 } from './cache';
 export type {
+  DownloadUrl,
   FetchLike,
   QueryCallOptions,
   QueryClient,
@@ -58,7 +59,7 @@ export type {
   QuerySingleClientMethod,
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
-export { queryClient, queryClientMethodFor } from './client';
+export { downloadClientFor, queryClient, queryClientMethodFor } from './client';
 /**
  * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
  * `totalOrder` is the one definition of the order it must serve a page in. `compareRows`,
@@ -67,6 +68,33 @@ export { 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,
+  DownloadQueryDef,
+  QueryDownload,
+} from './download';
+export {
+  DEFAULT_DOWNLOAD_TTL_MS,
+  MAX_DOWNLOAD_TTL_MS,
+  MIN_DOWNLOAD_TTL_MS,
+} from './download';
+export type { DownloadTokenProblem } from './download-errors';
+export {
+  QueryDownloadInvalidError,
+  QueryDownloadOnlyError,
+  QueryDownloadTokenExpiredError,
+  QueryDownloadTokenInvalidError,
+} from './download-errors';
 export {
   CursorValueUnsupportedError,
   MatcherUnsupportedError,
@@ -85,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/input-shape.ts

@@ -16,6 +16,7 @@
 // input cannot be written.
 
 import { type SchemaNode, tryIntrospect } from '@ultimat3/schema';
+import { DOWNLOAD_GRANT_PARAM } from './download-token';
 import { QueryInputUnencodableError } from './errors';
 import { PAGE_CONTROL_KEYS } from './page-controls';
 
@@ -34,6 +35,9 @@ function unencodable(node: SchemaNode): string | undefined {
     if (PAGE_CONTROL_KEYS.includes(key)) {
       return `${key} is reserved — the route reads it as a page control (see query.page())`;
     }
+    if (key === DOWNLOAD_GRANT_PARAM) {
+      return `${key} is reserved — a download's route reads it as the signed token (see query.url())`;
+    }
     // Required AND nullable: `searchOf` sends nothing for a `null`, and absence is what the far
     // side then sees — so the value the caller explicitly chose fails validation on arrival.
     // Optional or defaulted, absence is already the schema's own answer and nothing is lost.

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' },
+    },
+  };
+}

package/src/openapi.ts

@@ -18,17 +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';
 
@@ -43,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(
@@ -77,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
@@ -90,14 +118,21 @@ 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: {
@@ -107,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 } : {}),
@@ -117,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,
@@ -138,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,
@@ -168,8 +202,67 @@ function singleOperation(target: AnyQuery, name: string): 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' };
+/**
+ * A download: one URL, two answers decided by `_token` — the mint (`{ url, expiresAt }`, JSON) and
+ * the file (bytes, a `Range:` window as 206). No page controls, no rows, no MCP tool.
+ */
+function downloadOperation(target: AnyQuery, name: string): Record<string, unknown> {
+  return {
+    operationId: name,
+    tags: [QUERY_TAG],
+    summary: name,
+    ...(target.deprecated === undefined ? {} : { deprecated: true }),
+    parameters: [
+      ...inputParameters(target),
+      {
+        name: DOWNLOAD_GRANT_PARAM,
+        in: 'query',
+        required: false,
+        description: 'absent: mint a signed URL for this input; present: the file that URL grants',
+        schema: { type: 'string' },
+      },
+    ],
+    responses: {
+      '200': {
+        description: `without ${DOWNLOAD_GRANT_PARAM}, the minted URL; with it, the file`,
+        content: {
+          'application/json': { schema: MINTED_URL },
+          // The file's own type — whatever `handle` answered — so any media type, as bytes.
+          '*/*': { schema: FILE_BYTES },
+        },
+      },
+      '206': {
+        description: 'the one byte range the Range header named, with content-range',
+        content: { '*/*': { schema: FILE_BYTES } },
+      },
+      '400': problemResponse('X_INPUT_INVALID'),
+      '401': problemResponse(
+        'X_UNAUTHENTICATED — a mint with no session, under a policy that needs one',
+      ),
+      '403': problemResponse('policy denied, or X_QUERY_DOWNLOAD_TOKEN_INVALID'),
+      '410': problemResponse('X_QUERY_DOWNLOAD_TOKEN_EXPIRED — mint again'),
+      '416': { description: 'the Range header starts past the end of the file' },
+    },
+    'x-ultimate': {
+      capability: policyCapability(target.policy),
+      live: false,
+      download: true,
+      cacheTags: [],
+      tool: null,
+    },
+  };
+}
+
+const FILE_BYTES: Readonly<Record<string, unknown>> = { type: 'string', format: 'binary' };
+
+const MINTED_URL: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  required: ['url', 'expiresAt'],
+  properties: {
+    url: { type: 'string', description: `this path, with the input and ${DOWNLOAD_GRANT_PARAM}` },
+    expiresAt: { type: 'string', format: 'date-time' },
+  },
+};
 
 /** The two controls, spelled from `page-controls.ts` so the document cannot drift from the route. */
 const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
@@ -189,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),
   };
 }