@ultimat3/query 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -14,6 +14,12 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 |---|---|
 | `query.ts` | the primitive: `query()`, `describeQuery`, `queryHash`; the front door for the read path |
 | `read.ts` | **the one read path** (`runQuery`, `sourceFor`) + the private declaration store `sql` lives in |
+| `contract-test.ts` | `.contract()`, the generated suite. The three `X_CONTRACT_*` codes and `X_CONTRACT_DRIFT` are borrowed (`QUERY_BORROWED_ERROR_CODES`) |
+| `exercise.ts` | the exercise twin. "Reached" means `sql()` built a source, read off the refusal (`beforeSql`), because `read.ts` keeps no counter. No transaction: a read writes nothing |
+| `declared-errors.ts` | `judgedSql` / `judgedRead`, around `sql` and the source's `execute` in `read.ts`. `errors:` is checked where it is lifted (`facade.ts`), not in `query.ts` |
+| `declared-errors-contract.ts`, `openapi-errors.ts` | `.contract()`'s source scan; core's builder bound to http's status |
+| `http-pin.ts` | a read's pinned `http.path`, its check at `query()`, `servedQueryPath`, `queryHttpPinOf` |
+| `http-pin-error.ts` | `X_QUERY_HTTP_PATH_INVALID`, a leaf over `@ultimat3/core/page` so the browser client can raise it without `errors.ts`'s titles table |
 | `facade.ts` | the fluent surface — binds each projection to the query, re-implements none |
 | `http.ts` | route projection (`GET /_x/query/<kebab>`, `enforcedBy: 'handler'`) |
 | `client.ts` | typed read client (browser-safe); dispatches through `@ultimat3/core`'s `clientTransport`, never `fetch` |
@@ -40,9 +46,10 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `audit-errors.ts` | `X_QUERY_AUDIT_SINK_MISSING` / `X_QUERY_AUDIT_SINK_FAILED` (titles in `errors.ts`) |
 | `download.ts` | `query({ download })`: the build, the in-process file, the mint, the serve — through `admittedCall` |
 | `download-token.ts` | the `_token`: claims `seal()`ed under the master key, opened against one query, one input, the clock |
-| `download-http.ts` | the download route: mint JSON without `_token`, the file with it (`Range:`, `content-disposition`) |
+| `download-http.ts` | the download route: mint JSON without `_token`, the file with it (`content-disposition`, and `Range:` by http's `objectResponse`; only `bodyOf` slices a body) |
 | `download-errors.ts` | the four `X_QUERY_DOWNLOAD_*` classes (titles in `errors.ts`) |
 | `search-string.ts` | `searchOf`: the input as a search string — the client's request and a minted URL, one encoding |
+| `openapi.ts` | the read half of `openapi.json`; a declared `rows:` is published inline through `toWireOutputSchema`, today's bytes otherwise |
 
 ## Invariants — the read path
 
@@ -70,7 +77,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **A read has ONE tool name, the export name verbatim.** `toToolName` is deleted.
   `index.test.ts` asserts the barrel exports nothing matching `/tool_?name/i`.
 - **`queryClient` is the map-wide read client (mirror of `rpc`)**; both spellings run
-  `queryClientMethodFor`. **`toQueryRoute` and `client()` derive the same URL from core's `queryPath`.**
+  `queryClientMethodFor`. **`toQueryRoute` and `client()` derive the same URL from core's `queryPath`, or from the read's pin, which both read from the declaration.**
 - **`QueryClient` typechecks at any app size, and a `.test.ts` cannot say so** (`tsconfig.json`
   excludes them): `client-scale-pins.ts` is source, so a regression is a `typecheck` error. The map
   it pins is the intersection `@ultimat3/action`'s `Merge` hands over; that package pins `Merge`.
@@ -117,6 +124,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **A live read keyed on a sealed column is refused at subscribe** (`assertNoSealedKey`, called by
   `toLiveQuery`): a change row carries none, so the window would be read once and never patched.
   The refusal names the column, never the filter's value.
+- **The document's row and the MCP tool's are one narrowing** (`toWireOutputSchema`, `As of 2026-11`). Inline, never a component: the CLI merges only `paths`. Structure only: rows are never re-parsed, so a bound or a closed object is a promise nothing enforces. `openapi.test.ts`, `sealed-egress.test.ts`.
 
 ## Invariants — download
 
@@ -131,6 +139,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   an expired forgery is a forgery. `X_SEAL_KEY_MISSING` stays a 500 (the server's fault).
 - **`audit: true` records the mint, `rateLimit:` spends at the mint** — a player's `Range:` GETs
   are one admitted read.
+- `download-http.ts`: a function `body` is handed the window by `objectResponse`, with `size` required by type and by `assertFile`.
 
 ## Invariants — audit
 
@@ -162,9 +171,9 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 - **`@ultimat3/query/client` is the read client without the barrel** — `client.ts`
   imports core from `@ultimat3/core/page`, the page keys live in the leaf `page-keys.ts`, and
   `client.ts` never imports `page-controls.ts` or `stable.ts`. `client-bundle.test.ts` fails on any
-  titles table in the graph or past 12 kB; `client-subpath.test.ts` pins the specifier. Byte figures
-  (browser, minified): barrel `queryClient` 25,237 B (`As of 2026-10-02`); `./client` 11,983 B
-  (`As of 2026-10-05`, +971 B: core reads a refusal's `Retry-After` and body title).
+  titles table in the graph or past 14.5 kB; `client-subpath.test.ts` pins the specifier. Byte figures
+  (browser, minified): barrel `queryClient` 25,237 B (`As of 2026-10-02`); `./client` 14,494 B
+  (`As of 2026-11-05`: +1,013 B a pinned read's URL fill, the rest wave 5a's core `./page` additions).
 - **The record envelope is derived from `rows:`** — `answersRecords(rows)` (`hasEntityRows`,
   `@ultimat3/entity`), decided once at projection for `http.ts` and `openapi.ts`, sent on every
   answer. No `rows:` is byte-identical on the wire.

package/README.md

@@ -2,6 +2,8 @@
 
 A read. Optionally live. Never a mutation — writes are `action`.
 
+`bun add @ultimat3/query` · guide: [Queries And Live Queries](https://github.com/developerz-ai/ultimate/wiki/Queries-And-Live-Queries)
+
 ```ts
 import { query, t } from '@ultimat3/query';
 
@@ -32,6 +34,7 @@ Every projection is a method on the query itself. A query has no `.def`.
 | `toolFrom(liveFeed)` | the MCP read tool, from `@ultimat3/mcp` — named `liveFeed`, exactly what `tools/list` serves, reading fresh through `sourceFor` with the same policy object. There is no `liveFeed.tool()` (`As of 25.0.0`): it was a second projection a tier below the served one |
 | `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways. `.page(input, { first, after })` on the same method reads one page over the wire |
 | `liveFeed.describe()` | the manifest row |
+| `liveFeed.contract({ exercise: { actor } })` | the generated contract suite: the read survives 16 generated legal inputs (`exerciseQuery`), seeded by its name. `exercise` is required unless the policy admits an anonymous reader; `{ off: '<reason>' }` skips it out loud |
 
 The route on the other end of that client is `toQueryRoute(liveFeed)`, and — `As of 2026-08` —
 `x dev` and a container both mount it for every registered read, the framework's job, not the
@@ -53,6 +56,13 @@ const [post] = await queries.publicPost({ slug }); // typed input, typed rows
 
 Both spellings run `queryClientMethodFor`, so a read has one URL however it is addressed.
 
+A read may pin its URL: `query({ …, http: { path: '/orders/:id' } })` is served at `GET /orders/:id`
+in place of `/_x/query/<kebab>`. Each `:param` is a required `t.string` key of `input:`
+(`X_QUERY_HTTP_PATH_INVALID` at `query()`); the URL's value joins the search string before the
+input is parsed, and a search string naming it differently is 400 `X_HTTP_PATH_INPUT_CONFLICT`.
+`read.client()` fills the URL; `queryClient` by name cannot see a pin. `queryHttpPinOf(read)` is
+the manifest's `{ path, method: 'GET' }`.
+
 `queryClient<Api['queries']>` typechecks at any app size: `client-scale-pins.ts` compiles it over
 100 reads in 50 modules — a list read, its `.page` and a `single: true` read — on every `typecheck`.
 
@@ -122,6 +132,13 @@ or with a schema no `entity()` branded (a `t.object` look-alike, a `.pick()`ed p
 is the bare rows, byte-identical to before. `rows:` exists because a read's `sql:` names its table
 as a STRING, so nothing else carries a schema the envelope could be derived from.
 
+**Any introspectable `rows:` is also the published row** (`As of 2026-11`), entity or not:
+`openapi.json` and a mount's document print its members inline in the list, the page envelope and
+the single answer, and `x.manifest.json` carries the same wire schema, so `x verify` refuses a
+member removed, retyped or made optional without a major. One narrowing, `toWireOutputSchema`, the
+one the MCP tool's `outputSchema` uses. No `rows:`, or one that cannot be introspected: the bytes
+it had (`items: {}`).
+
 ### Flight control — `clientFlight`, opt-in
 
 A typed read is one dispatch and nothing else until a `flight` is installed. With one, N concurrent
@@ -205,7 +222,10 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `client.ts` | the typed read client (browser-safe) |
 | `http.ts` | the route projection — `GET /_x/query/<kebab>`, the URL the client derives |
 | `page-controls.ts` | `_first` / `_after` — the two search-string keys that page the route, split out and judged at the wire against `@ultimat3/entity`'s `MAX_PAGE_SIZE` |
-| `openapi.ts` | the read half of `openapi.json` — one `GET` path item per registered query |
+| `openapi.ts` | the read half of `openapi.json` — one `GET` path item per registered query, publishing a declared `rows:` |
+| `openapi-errors.ts` | a read operation's `responses` with its declared `errors:` in them |
+| `declared-errors.ts` / `declared-errors-contract.ts` | `errors:` judged around `sql` and `execute`; `.contract()`'s scan of `sql`'s source |
+| `contract-test.ts` / `exercise.ts` | `.contract()`: the exercise assertion, a twin of `@ultimat3/action`'s; its three `X_CONTRACT_*` codes are borrowed |
 | `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
 | `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
 | `pagination.ts` | `paginate()` — keyset pages over core's cursor codec |
@@ -556,6 +576,13 @@ tier registered with a frozen clock is drivable end to end — and omitting it i
 for its own default. `@ultimat3/cache`'s tiers refuse a non-positive `ttlMs` and have no immortal
 entry to offer, so there is no "never" to spell.
 
+`cache: { negativeTtlMs }` is a `null`'s own lease: a `single: true` read that matched nothing is
+stored as `null` and the stack keeps it `negativeTtlMs`. An empty list is a list, and keeps `ttlMs`.
+
+`etag: true` answers `private, no-cache` with a strong `ETag` and a bodiless 304 for a held one —
+`@ultimat3/http`'s `notModified`, after the policy and the rate limit (`http-etag.ts`).
+`timeoutMs` runs the source inside `@ultimat3/db`'s `withStatementTimeout`: always the primary.
+
 The memo entry is the read **in flight**, not its value, so "twice" covers reads that race as
 well as reads that follow: five holes rendering concurrently share one execution and one tier
 round trip. A rejection is evicted — a failed read is not the request's answer.
@@ -603,6 +630,14 @@ The conversion is `toBucket` from `@ultimat3/http` — the same one the action r
 http owns `Bucket` and `action` is the same tier as this package. A pair the limiter cannot run
 on is `X_RATE_LIMIT_INVALID`, at projection.
 
+## `errors:` — the refusals a reader may branch on, closed
+
+An action's rule, read side: `query({ errors: [FeedGone.code], … })`, judged around `sql` and the
+source's `execute` (`declared-errors.ts`), scanned in `sql`'s own source by `.contract()`
+(`declared-errors-contract.ts`), named per status in the OpenAPI operation (`openapi-errors.ts`)
+and on the MCP tool's description. Checked where it is lifted (`facade.ts`): sorted, frozen, or
+`X_ACTION_ERRORS_INVALID`. `describe().errors` is the list, `null` when absent.
+
 ## `deprecated:` — a compat window, not a version
 
 ```ts
@@ -712,9 +747,9 @@ export const runRecording = query({
 | Policy | evaluated at MINT, exactly as for a rows read: actor half, the declared `rateLimit:`, the parse, the predicate. A refusal is the policy's own 401/403 |
 | The token | `seal()`ed (`@ultimat3/core`, AES-256-GCM under the app master key, purpose `ultimate.query.download:<name>`) claims: the query, `fingerprint()` of the PARSED input, the expiry on `ctx.now()`, the minting actor minus `facts`. The ACTOR is ciphertext — no id, role or grant readable; the query's path and its input are plain in the URL, as on any read |
 | The serve | the seal first (forged, truncated, another query's, a retired key → `X_QUERY_DOWNLOAD_TOKEN_INVALID`, 403), then the expiry (`X_QUERY_DOWNLOAD_TOKEN_EXPIRED`, 410), then the URL's input re-parsed against the bound fingerprint (edited → 403). `handle` runs as the MINTING actor; the policy is not re-run — it decided at mint, with `facts` the token cannot carry |
-| `handle`'s answer | `{ body: Uint8Array \| Blob \| ReadableStream, contentType, filename, disposition?: 'attachment' \| 'inline', size? }` — bytes, never base64. Anything else is a 500 (`X_INVARIANT`) naming the fix |
+| `handle`'s answer | `{ body: Uint8Array \| Blob \| ReadableStream, contentType, filename, disposition?: 'attachment' \| 'inline', size? }`, or `body: (range?) => BodyInit` (`DownloadBodyOpener`) with `size` required — bytes, never base64. Anything else is a 500 (`X_INVARIANT`) naming the fix |
 | Headers | `content-type`, `content-disposition` (`attachment` default; ASCII `filename` + exact `filename*=UTF-8''…`), `x-content-type-options: nosniff`, `content-security-policy: default-src 'none'; img-src 'self'; media-src 'self'; sandbox`, `referrer-policy: no-referrer`, `cache-control: no-store`; `content-length` only when the size is known — a `Uint8Array`, a `Blob`, or a stream with `size` |
-| `Range:` | one `bytes=` window, 206 + `content-range`; past the end 416. A `Uint8Array`/`Blob` always (a `Blob` slices lazily); a `ReadableStream` only with `size`, else `accept-ranges: none` and the whole body |
+| `Range:` | one `bytes=` window, 206 + `content-range`; past the end 416. A `Uint8Array`/`Blob` always (a `Blob` slices lazily); a `ReadableStream` only with `size`, else `accept-ranges: none` and the whole body; the function form is handed the window, so `(range) => disk.streamRange(key, [range.start, range.end])` reads nothing before it, and a 304 or a 416 opens nothing |
 | Rows | `.live()`, `.page()`, `.as()`, `sourceFor`, `explain`, an MCP tool: `X_QUERY_DOWNLOAD_ONLY`. `describeSql` lists it with `sql: null` |
 | Audit | `audit: true` records the MINT — the decision of who may read what. A serve, and every `Range:` a player sends, is not a second read |
 | Manifest / OpenAPI | `download: true` on the `QueryFact` (rows ↔ download is breaking); one GET with `_token`, `200` as JSON or `application/octet-stream`, `206`, `410`, `416` |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/query",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "query",
+    "live-query",
+    "pagination",
+    "realtime"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Queries-And-Live-Queries",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -37,11 +47,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "29.4.0",
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/entity": "29.4.0",
-    "@ultimat3/http": "29.4.0",
-    "@ultimat3/policy": "29.4.0",
-    "@ultimat3/schema": "29.4.0"
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/db": "30.1.0",
+    "@ultimat3/entity": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/policy": "30.1.0",
+    "@ultimat3/schema": "30.1.0"
   }
 }

package/src/cache.ts

@@ -199,8 +199,15 @@ export function readThrough<T>(
   ttlMs: number | null,
   run: () => Promise<T>,
   tags: readonly CacheTag[] = [],
+  negativeTtlMs: number | null = null,
 ): Promise<T> {
-  return readOnce(ctx, key, () => fill(ctx.clock, key, ttlMs, tags, run));
+  return readOnce(ctx, key, () => fill(ctx.clock, key, { ttlMs, negativeTtlMs }, tags, run));
+}
+
+/** The two leases a filled entry may take: a value's, and a `null`'s when it differs. */
+interface Leases {
+  readonly ttlMs: number | null;
+  readonly negativeTtlMs: number | null;
 }
 
 /**
@@ -216,11 +223,16 @@ export function readThrough<T>(
 function fill<T>(
   clock: Clock,
   key: string,
-  ttlMs: number | null,
+  { ttlMs, negativeTtlMs }: Leases,
   tags: readonly CacheTag[],
   run: () => Promise<T>,
 ): Promise<T> {
   // `null` is "the caller named none", never "never": every tier refuses a non-positive `ttlMs`
   // and none has an immortal entry to offer, so omitting it falls to the tier's own default.
-  return stackFor(clock).read(key, run, { ...(ttlMs === null ? {} : { ttlMs }), tags });
+  // `negativeTtlMs` is the stack's to apply (`ttlOptionsFor`): it alone knows the load was a null.
+  return stackFor(clock).read(key, run, {
+    ...(ttlMs === null ? {} : { ttlMs }),
+    ...(negativeTtlMs === null ? {} : { negativeTtlMs }),
+    tags,
+  });
 }

package/src/client.ts

@@ -18,9 +18,10 @@
 
 import type { ClientFlight, ClientRetry } from '@ultimat3/core';
 import type { FetchLike, RecordEnvelope } from '@ultimat3/core/page';
-import { clientTransport, queryPath } from '@ultimat3/core/page';
+import { clientTransport, fillWire, queryPath, renderedQueryPin } from '@ultimat3/core/page';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { DownloadClientMethod, DownloadQuery } from './download';
+import { QueryHttpPathInvalidError } from './http-pin-error';
 import type { PageControls } from './page-controls';
 import type { Page } from './pagination';
 import type { Query } from './query';
@@ -167,8 +168,9 @@ export function queryClient<TQueries extends QueryMap>(
 export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
+  pinnedPath?: string,
 ): QueryClientMethod<TInput, TRow> {
-  return methodsOf<TInput, TRow>(name, options);
+  return methodsOf<TInput, TRow>(name, options, pinnedPath);
 }
 
 /**
@@ -186,21 +188,33 @@ export function downloadClientFor<TInput extends StandardSchemaV1>(
 function methodsOf<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
+  pinnedPath?: string,
 ) {
   const base = options.baseUrl.replace(/\/+$/, '');
+  // A browser caller naming the read only by name — `queryClient`, `useQuery`, a channel's
+  // catch-up — goes where the server's document says it pinned it, never to a derived 404.
+  const path = pinnedPath ?? renderedQueryPin(name) ?? queryPath(name);
   // Erased at the wire seam; the row type is this query's by construction.
   const rows = (input: InferInput<TInput>, callOptions: QueryCallOptions = {}) =>
-    read(base, options, name, input, callOptions) as Promise<readonly TRow[]>;
+    read(base, options, name, input, callOptions, undefined, path) as Promise<readonly TRow[]>;
   const page = (
     input: InferInput<TInput>,
     args: PageControls,
     callOptions: QueryCallOptions = {},
-  ) => read(base, options, name, input, callOptions, args) as Promise<Page<TRow>>;
+  ) => read(base, options, name, input, callOptions, args, path) as Promise<Page<TRow>>;
   const url = async (
     input: InferInput<TInput>,
     callOptions: QueryCallOptions = {},
   ): Promise<DownloadUrl> => {
-    const minted = (await read(base, options, name, input, callOptions)) as DownloadUrl;
+    const minted = (await read(
+      base,
+      options,
+      name,
+      input,
+      callOptions,
+      undefined,
+      path,
+    )) as DownloadUrl;
     return { ...minted, url: base + minted.url };
   };
   return Object.assign(rows, { page, url });
@@ -218,12 +232,22 @@ function read(
   name: string,
   input: unknown,
   callOptions: QueryCallOptions,
-  page?: PageControls,
+  page: PageControls | undefined,
+  path: string,
 ): Promise<unknown> {
-  const search = searchOf(input, page);
+  // The URL carries a `:param` pin's values, each one encoded segment the router decodes back; the
+  // search string carries the rest. A missing value is refused before any request exists.
+  const filled = fillWire(path, input);
+  if (!filled.ok) {
+    return Promise.reject(
+      new QueryHttpPathInvalidError({ name, path, reason: `:${filled.missing} ${filled.reason}` }),
+    );
+  }
+  const at = filled.url;
+  const search = searchOf(filled.rest, page);
   return clientTransport({
     method: 'GET',
-    url: `${base}${queryPath(name)}${search === '' ? '' : `?${search}`}`,
+    url: `${base}${at}${search === '' ? '' : `?${search}`}`,
     // The trace and budget are the transport's, from its server-side outbound slot, placed
     // before these so an explicit `traceparent` still wins; a browser bundles none of it.
     ...(options.headers === undefined ? {} : { headers: options.headers }),

package/src/contract-test.ts

@@ -0,0 +1,59 @@
+/**
+ * A read's generated contract suite, `orgFeed.contract()`: what the `contract` step runs for a
+ * query. Today one assertion — the read survives generated legal input — beside which other
+ * claims a read owes (its declared refusals) are appended here, never in a second suite.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { admitsAnonymous } from '@ultimat3/policy';
+import { declaredErrorsContract } from './declared-errors-contract';
+import type { QueryExerciseOptions } from './exercise';
+import { exerciseQuery, queryExerciseTestName, queryExerciseUndeclared } from './exercise';
+import type { AnyQuery } from './query';
+import { queryName } from './read';
+
+/** One generated assertion: a name to register under `test()`, and its body. */
+export interface QueryContractTest {
+  readonly name: string;
+  run(): Promise<void>;
+}
+
+export interface QueryContractTestOptions {
+  /**
+   * Who the generated runs read as — required unless the policy admits an anonymous reader — or
+   * `{ off: '<reason>' }`, which skips the runs out loud: the reason is in the test's name.
+   */
+  readonly exercise?: QueryExerciseOptions;
+  /** The context each run starts from; the actor is swapped in, the rest kept. */
+  readonly ctx?: Ctx;
+}
+
+export function queryContractTestsFor(
+  target: AnyQuery,
+  options: QueryContractTestOptions = {},
+): readonly QueryContractTest[] {
+  return [exerciseContract(target, options), ...declaredErrorsContract(target)];
+}
+
+function exerciseContract(target: AnyQuery, options: QueryContractTestOptions): QueryContractTest {
+  const name = queryName(target);
+  const exercise = options.exercise;
+  if (exercise !== undefined && 'off' in exercise) {
+    const reason = exercise.off.trim();
+    if (reason.length > 0) {
+      return { name: `${name}: read exercise off: ${reason}`, run: () => Promise.resolve() };
+    }
+    return {
+      name: queryExerciseTestName(name),
+      run: () => Promise.reject(queryExerciseUndeclared(name, true)),
+    };
+  }
+  const chosen = exercise ?? (admitsAnonymous(target.policy) ? { actor: null } : undefined);
+  return {
+    name: queryExerciseTestName(name),
+    run: async () => {
+      if (chosen === undefined) throw queryExerciseUndeclared(name, false);
+      await exerciseQuery(target, chosen, options.ctx);
+    },
+  };
+}

package/src/declared-errors-contract.ts

@@ -0,0 +1,34 @@
+// Single responsibility: `.contract()`'s assertion for a query declaring `errors:` — the codes its
+// `sql` names in its own source, judged by core's rule (the action's twin, one tier over). First
+// hop only: what a repository helper throws is the read path's wrap to judge (`declared-errors.ts`).
+
+import {
+  definedErrorClassCodes,
+  ErrorUndeclaredError,
+  judgeThrown,
+  scanHandlerSource,
+} from '@ultimat3/core';
+import { declaredStatusFor } from '@ultimat3/http';
+import type { QueryContractTest } from './contract-test';
+import type { AnyQuery } from './query';
+import { defOf, queryName } from './read';
+
+/** One assertion for a read that declares `errors:`; none for an open contract or a download. */
+export function declaredErrorsContract(target: AnyQuery): readonly QueryContractTest[] {
+  const declared = target.errors;
+  if (declared === undefined || target.download === true) return [];
+  const name = queryName(target);
+  return [
+    {
+      name: `${name}: its read names only the errors it declares`,
+      run: async () => {
+        const stray = scanHandlerSource(
+          defOf(target).sql.toString(),
+          await definedErrorClassCodes(),
+        ).filter((code) => judgeThrown(declared, code, declaredStatusFor(code)) === 'undeclared');
+        if (stray.length === 0) return;
+        throw new ErrorUndeclaredError({ primitive: 'query', name }, stray.join("', '"));
+      },
+    },
+  ];
+}

package/src/declared-errors.ts

@@ -0,0 +1,26 @@
+// Single responsibility: the judgement the read path puts around `sql` and the source's `execute`
+// for a query declaring `errors:` — core's rule (`declared-errors.ts`, shared with
+// `@ultimat3/action`), `@ultimat3/http`'s status. Undeclared, each call is the read itself.
+
+import type { DeclaredErrorsOwner } from '@ultimat3/core';
+import { enforceDeclared, withDeclaredErrors } from '@ultimat3/core';
+import { declaredStatusFor } from '@ultimat3/http';
+import type { AnyQuery } from './query';
+
+const ownerOf = (name: string): DeclaredErrorsOwner => ({ primitive: 'query', name });
+
+/** `sql(input, ctx)`, which builds a source synchronously: a throw from it is judged here. */
+export function judgedSql<T>(target: AnyQuery, name: string, build: () => T): T {
+  if (target.errors === undefined) return build();
+  try {
+    return build();
+  } catch (error) {
+    throw enforceDeclared(error, target.errors, declaredStatusFor, ownerOf(name));
+  }
+}
+
+/** The source's `execute()`: the same promise when undeclared, a judged one otherwise. */
+export function judgedRead<T>(target: AnyQuery, name: string, run: () => Promise<T>): Promise<T> {
+  if (target.errors === undefined) return run();
+  return withDeclaredErrors(target.errors, declaredStatusFor, ownerOf(name), run);
+}

package/src/download-http.ts

@@ -9,11 +9,10 @@ import { assert, queryPath, useContext } from '@ultimat3/core';
 import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
 import {
   byteWindow,
-  contentRangeOf,
   jsonResponse,
-  parseByteRange,
+  type ObjectRequest,
+  objectResponse,
   publishRateLimit,
-  RANGE_UNSATISFIABLE,
   type RequestedRange,
 } from '@ultimat3/http';
 import { policyCapability } from '@ultimat3/policy';
@@ -56,7 +55,7 @@ export function toDownloadRoute(
       return jsonResponse(minted);
     }
     const file = await serveDownloadFile(target, input, token, { surface: 'http' });
-    return fileResponse(file, request.header('range'));
+    return fileResponse(request, file);
   };
 
   const meta: RouteMeta = {
@@ -120,10 +119,18 @@ const hasControl = (text: string): boolean =>
 function assertFile(file: DownloadFile): void {
   const { body, contentType, filename, disposition, size } = file;
   assert(
-    body instanceof Uint8Array || body instanceof Blob || body instanceof ReadableStream,
-    'a download handle() answered a body that is not a Uint8Array, a Blob or a ReadableStream',
+    body instanceof Uint8Array ||
+      body instanceof Blob ||
+      body instanceof ReadableStream ||
+      typeof body === 'function',
+    'a download handle() answered a body that is not a Uint8Array, a Blob, a ReadableStream or a function',
     "return { body: bytes, contentType: 'video/mp4', filename: 'run.mp4' }   // bytes, never a base64 string",
   );
+  assert(
+    typeof body !== 'function' || size !== undefined,
+    'a download handle() answered a function body with no size, so no Range: can be judged',
+    "return { body: (range) => open(range), size: object.size, contentType: 'video/mp4', filename: 'run.mp4' }",
+  );
   assert(
     typeof contentType === 'string' && contentType !== '' && !hasControl(contentType),
     'a download handle() answered a contentType that is empty, not a string, or carries a control character',
@@ -180,8 +187,9 @@ function bytesBody(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
     : bytes.slice();
 }
 
-function bodyOf(file: DownloadFile, range?: RequestedRange): BodyInit {
+function bodyOf(file: DownloadFile, range?: RequestedRange): BodyInit | Promise<BodyInit> {
   const { body } = file;
+  if (typeof body === 'function') return body(range);
   if (body instanceof Uint8Array) {
     const whole = bytesBody(body);
     return range === undefined ? whole : whole.subarray(range.start, range.end + 1);
@@ -192,35 +200,38 @@ function bodyOf(file: DownloadFile, range?: RequestedRange): BodyInit {
   return range === undefined ? body : byteWindow(body, range);
 }
 
-/** Status, headers and body for one file and the request's `Range:`, if it named one we serve. */
-export function fileResponse(file: DownloadFile, rangeHeader: string | null): Response {
+/**
+ * Status, headers and body for one file and the request's `Range:`, by `objectResponse`'s rules.
+ * The headers are the file's own and stand in for its sandbox rule. A file of unknown size has no
+ * window to serve, so it answers whole; there is no etag on a file either, so no 304.
+ */
+export async function fileResponse(request: ObjectRequest, file: DownloadFile): Promise<Response> {
   assertFile(file);
-  const headers = new Headers({
-    'content-type': file.contentType,
+  const own = {
     'content-disposition': contentDisposition(file),
     'x-content-type-options': 'nosniff',
     // Loads nothing but itself, in an opaque origin with no script — and names no URL on the way
     // out: the one this file is served at is a bearer grant until it expires.
     'content-security-policy': DOWNLOAD_CSP,
     'referrer-policy': 'no-referrer',
-  });
+  };
   const size = sizeOf(file);
   if (size === undefined) {
-    headers.set('accept-ranges', 'none');
-    return new Response(bodyOf(file), { headers });
-  }
-  headers.set('accept-ranges', 'bytes');
-  const range = parseByteRange(rangeHeader, size);
-  if (range === RANGE_UNSATISFIABLE) {
-    if (file.body instanceof ReadableStream) void file.body.cancel().catch(() => undefined);
-    headers.set('content-range', `bytes */${String(size)}`);
-    return new Response(null, { status: 416, headers });
+    return new Response(await bodyOf(file), {
+      headers: { 'content-type': file.contentType, 'accept-ranges': 'none', ...own },
+    });
   }
-  if (range === undefined) {
-    headers.set('content-length', String(size));
-    return new Response(bodyOf(file), { headers });
+  const response = await objectResponse(
+    request,
+    {
+      object: { contentType: file.contentType, size },
+      open: (range) => bodyOf(file, range),
+    },
+    { headers: own },
+  );
+  // Nothing opened it, and nothing else will read it: a stream the handler started is let go.
+  if (response.status === 416 && file.body instanceof ReadableStream) {
+    void file.body.cancel().catch(() => undefined);
   }
-  headers.set('content-range', contentRangeOf(range, size));
-  headers.set('content-length', String(range.end - range.start + 1));
-  return new Response(bodyOf(file, range), { status: 206, headers });
+  return response;
 }

package/src/download.ts

@@ -13,6 +13,7 @@
 
 import type { Ctx, Deprecation } from '@ultimat3/core';
 import { queryPath, useContext } from '@ultimat3/core';
+import type { RequestedRange } from '@ultimat3/http';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { DownloadUrl, QueryCallOptions, QueryClientOptions } from './client';
 import { downloadClientFor } from './client';
@@ -40,22 +41,40 @@ export const MAX_DOWNLOAD_TTL_MS = 3_600_000;
 const TOKEN_IS_THE_GRANT =
   'a download token is sealed only by url(), after this query admitted the minting actor; the token is that decision';
 
-/** What `handle` answers. Bytes, never a base64 string — that is the +33 % this exists to remove. */
-export interface DownloadFile {
-  /**
-   * A `Uint8Array` or a `Blob` (a `Bun.file`, a slice) is range-served from its own length; a
-   * `ReadableStream` is range-served only with `size`, else whole with `accept-ranges: none`.
-   */
-  readonly body: Uint8Array | Blob | ReadableStream<Uint8Array>;
+interface DownloadFileHead {
   readonly contentType: string;
   /** The name a browser saves it under — `content-disposition`'s `filename` and `filename*`. */
   readonly filename: string;
   /** `attachment` (default) saves it; `inline` lets a tab render it. `<video>` ignores both. */
   readonly disposition?: 'attachment' | 'inline' | undefined;
-  /** The stream's length in bytes. Ignored for a `Uint8Array` or a `Blob`, which know theirs. */
-  readonly size?: number | undefined;
 }
 
+/**
+ * Opens the bytes asked for: the window with a `Range:`, the whole file with none, and not at all
+ * for a 304 or a 416. So a stored object's seek reads only its window, with no `storage` edge here:
+ * `(range) => range === undefined ? disk.stream(key) : disk.streamRange(key, [range.start, range.end])`.
+ */
+export type DownloadBodyOpener = (range?: RequestedRange) => BodyInit | Promise<BodyInit>;
+
+/** What `handle` answers. Bytes, never a base64 string — that is the +33 % this exists to remove. */
+export type DownloadFile =
+  | (DownloadFileHead & {
+      /**
+       * A `Uint8Array` or a `Blob` (a `Bun.file`, a slice) is range-served from its own length; a
+       * `ReadableStream` is range-served only with `size`, else whole with `accept-ranges: none`,
+       * and a window of one has read and dropped everything before it.
+       */
+      readonly body: Uint8Array | Blob | ReadableStream<Uint8Array>;
+      /** The stream's length in bytes. Ignored for a `Uint8Array` or a `Blob`, which know theirs. */
+      readonly size?: number | undefined;
+    })
+  | (DownloadFileHead & {
+      /** The disk's own window. A sealed object cannot take it: an AES-GCM envelope opens whole. */
+      readonly body: DownloadBodyOpener;
+      /** Required: it is what a `Range:` is judged against before anything is opened. */
+      readonly size: number;
+    });
+
 export interface DownloadArgs<TInput extends StandardSchemaV1> {
   readonly input: InferOutput<TInput>;
   readonly ctx: Ctx;