@ultimat3/query 29.3.2 → 30.0.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` |
@@ -38,6 +44,12 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
 | `audit-gate.ts` | `audit: true` — **the only** file that calls an `AuditSink` (core's): one record per call, an audited source per `execute()` |
 | `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 (`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
 
@@ -65,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`.
@@ -112,6 +124,22 @@ 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
+
+- **A download is a `query`, never a ninth primitive** (`docs/history/primitive-factories.md`):
+  `download:` replaces `sql:` and every rows option is refused beside it (`X_QUERY_DOWNLOAD_INVALID`).
+- **Its stored `sql` throws `X_QUERY_DOWNLOAD_ONLY`** — the ONE refusal every rows projection meets.
+  Never add a per-projection `download` check.
+- **Mint and in-process call go through `admittedCall`** (`read.ts`, the front half `buildSource`
+  shares). The serve re-parses through it as `unenforced` with a written reason: the token IS the
+  policy's decision. Never re-run the policy at serve — the token carries no `facts`.
+- **The token is SEALED, never signed**: it carries the actor. Seal before expiry before input —
+  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
 
@@ -143,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 |
@@ -216,6 +236,11 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `source.ts` | the `SqlSource` contract + `from()`, the in-memory reference |
 | `column-kinds.ts` | `kindsOf(relation)` — the declared kind of each column, which every comparison is decided by |
 | `sealed-shape.ts` | a live read may not filter or order on a `.sealed()` column — refused at subscribe |
+| `download.ts` | `query({ download })` — the declaration, the in-process file, the mint and the serve |
+| `download-token.ts` | the `_token`: claims sealed with core's `seal()`, opened against one query, one input, the clock |
+| `download-http.ts` | the route's two answers — mint JSON or the file: `content-disposition`, one `Range:` window, `no-store` |
+| `download-errors.ts` | `X_QUERY_DOWNLOAD_INVALID` / `_ONLY` / `_TOKEN_INVALID` / `_TOKEN_EXPIRED` |
+| `search-string.ts` | the input as a search string — what the client sends and a minted URL carries |
 
 ## Live queries
 
@@ -551,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.
@@ -598,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
@@ -665,12 +705,70 @@ before the parse; a sink refusing a **denied/failed** record is logged (`audit.s
 original error still reaches the caller; a sink refusing an **allowed** record withholds the rows,
 `X_QUERY_AUDIT_SINK_FAILED` — a read commits nothing, so a retry is safe.
 
+## `download:` — a file at a short-lived signed URL
+
+A read whose answer is BYTES — a recording, an export, an attachment — is still a `query`: one
+input, one policy, one name, one route. `download:` replaces `sql:`; every rows option (`sql`,
+`live`, `single`, `rows`, `subscribes`, `cache`, `mcp`) beside it is a type error and
+`X_QUERY_DOWNLOAD_INVALID`.
+
+```ts
+import { open } from '@ultimat3/core';
+import { can } from '@ultimat3/policy';
+import { query, t } from '@ultimat3/query';
+import { disk } from '@ultimat3/storage';
+
+export const runRecording = query({
+  input: t.object({ runId: t.uuid, index: t.number.int().min(0) }),
+  policy: can('recording:watch'),
+  download: {
+    expiresInMs: 600_000, // 1 000 … 3 600 000; default 300 000
+    async handle({ input }) {
+      const key = `runs/${input.runId}/recordings/${input.index}`;
+      const { bytes } = await disk('debug').get(key);
+      // A SEALED object opens whole (one AES-GCM envelope), then is served as plain bytes.
+      const plain = await open(new TextDecoder().decode(bytes), { purpose: `run-debug:${key}` });
+      return { body: plain, contentType: 'video/mp4', filename: `run-${input.runId}.mp4` };
+    },
+  },
+});
+```
+
+| Call | Answers |
+|---|---|
+| `client.runRecording.url(input)` (browser, `queryClient`/`.client()`) | `{ url, expiresAt }` — `url` absolute on the client's `baseUrl` |
+| `await runRecording.url(input, { ctx })` (server) | the same, `url` a path: `/_x/query/run-recording?runId=…&index=0&_token=…` |
+| `GET <url>` | the file — to ANY requester holding the URL until `expiresAt`; no session needed |
+| `await runRecording(input, { ctx })` | the `DownloadFile` in-process, as the caller |
+
+| Rule | |
+|---|---|
+| The route | `GET /_x/query/<kebab>` — the read's own. No `_token`: MINT (`application/json`). `_token`: SERVE (the bytes). `auth: 'public'`, `enforcedBy: 'handler'`, `cache: no-store` |
+| 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? }`, 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; 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` |
+
+**A sealed object is buffered.** WebCrypto's AES-GCM opens a whole envelope or nothing, so a
+sealed recording is read with `get()` (bounded by the disk's `maxGetBytes`) and opened before a
+byte is served; ranges are then sliced from the plaintext. A PLAIN object can be a `Bun.file`
+or a stream with `size`, served without buffering.
+
 ## Errors
 
 | Code | When | Fix |
 |---|---|---|
 | `X_QUERY_AUDIT_SINK_MISSING` | `audit: true` and no audit sink installed — refused before the parse | `setAuditSink(sink)` from `@ultimat3/core` at boot |
 | `X_QUERY_AUDIT_SINK_FAILED` | the sink refused the record of an allowed read; the rows were withheld | fix the sink, then retry the read |
+| `X_QUERY_DOWNLOAD_INVALID` | `download:` beside a rows option, a `handle` that is not a function, `expiresInMs` outside 1 000 … 3 600 000 | declare `download: { handle }` alone |
+| `X_QUERY_DOWNLOAD_ONLY` | rows asked of a download (`.live()`, `.page()`, `.as()`, `sourceFor`) | `await q.url(input)`, or `await q(input)` for the file |
+| `X_QUERY_DOWNLOAD_TOKEN_INVALID` | a `_token` forged, truncated, another query's, under a retired key, or bound to other input — 403 | mint again: `client.<name>.url(input)` |
+| `X_QUERY_DOWNLOAD_TOKEN_EXPIRED` | a genuine `_token` past `expiresAt` — 410 | mint again right before the request |
 | `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
 | `X_QUERY_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
@@ -700,6 +798,10 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `QueryAuditSinkMissingError` | `X_QUERY_AUDIT_SINK_MISSING` | `src/audit-errors.ts` |
 | `QueryDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
 | `QueryDeprecationInvalidError` | `X_QUERY_DEPRECATION_INVALID` | `src/errors.ts` |
+| `QueryDownloadInvalidError` | `X_QUERY_DOWNLOAD_INVALID` | `src/download-errors.ts` |
+| `QueryDownloadOnlyError` | `X_QUERY_DOWNLOAD_ONLY` | `src/download-errors.ts` |
+| `QueryDownloadTokenExpiredError` | `X_QUERY_DOWNLOAD_TOKEN_EXPIRED` | `src/download-errors.ts` |
+| `QueryDownloadTokenInvalidError` | `X_QUERY_DOWNLOAD_TOKEN_INVALID` | `src/download-errors.ts` |
 | `QueryDuplicateError` | `X_QUERY_DUPLICATE` | `src/errors.ts` |
 | `QueryForeignError` | `X_QUERY_FOREIGN` | `src/errors.ts` |
 | `QueryInputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/query",
-  "version": "29.3.2",
+  "version": "30.0.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.3.2",
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/entity": "29.3.2",
-    "@ultimat3/http": "29.3.2",
-    "@ultimat3/policy": "29.3.2",
-    "@ultimat3/schema": "29.3.2"
+    "@ultimat3/cache": "30.0.0",
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/db": "30.0.0",
+    "@ultimat3/entity": "30.0.0",
+    "@ultimat3/http": "30.0.0",
+    "@ultimat3/policy": "30.0.0",
+    "@ultimat3/schema": "30.0.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,12 +18,14 @@
 
 import type { ClientFlight, ClientRetry } from '@ultimat3/core';
 import type { FetchLike, RecordEnvelope } from '@ultimat3/core/page';
-import { clientTransport, isJsonObject, 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 { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 import type { Page } from './pagination';
 import type { Query } from './query';
+import { searchOf } from './search-string';
 
 /** Core's, re-exported under the name this package always exported it by — one declaration. */
 export type { FetchLike } from '@ultimat3/core/page';
@@ -78,6 +80,15 @@ export interface QueryClientMethod<TInput extends StandardSchemaV1, TRow extends
   ): Promise<Page<TRow>>;
 }
 
+/**
+ * A download query's signed URL, as `url()` answers it. `url` is a PATH on the server and absolute
+ * from a client with a `baseUrl`; `expiresAt` is an ISO instant — mint again past it.
+ */
+export interface DownloadUrl {
+  readonly url: string;
+  readonly expiresAt: string;
+}
+
 /**
  * A `single: true` read's method: the route answers the row itself, or 404 `X_NOT_FOUND` — which
  * the transport rejects with, as it does every problem document. No `page`: the route refuses the
@@ -112,13 +123,11 @@ export type QueryMap = Record<string, QueryLike>;
 
 /** `queries.publicPost({ slug })`, with the input schema and the row type both inferred. */
 export type QueryClient<TQueries extends QueryMap> = {
-  readonly [K in keyof TQueries]: TQueries[K] extends Query<
-    infer TInput,
-    infer TRow,
-    infer TSingle extends boolean
-  >
-    ? QueryClientMethodOf<TInput, TRow, TSingle>
-    : never;
+  readonly [K in keyof TQueries]: TQueries[K] extends DownloadQuery<infer TInput>
+    ? DownloadClientMethod<TInput>
+    : TQueries[K] extends Query<infer TInput, infer TRow, infer TSingle extends boolean>
+      ? QueryClientMethodOf<TInput, TRow, TSingle>
+      : never;
 };
 
 /**
@@ -152,21 +161,63 @@ export function queryClient<TQueries extends QueryMap>(
   return proxy as QueryClient<TQueries>;
 }
 
-/** One query's method — what `query.client()` returns, and what `queryClient` proxies to. */
+/**
+ * One query's method — what `query.client()` returns, and what `queryClient` proxies to. It
+ * carries `url` too, the download half; the declaration's TYPE decides which half a caller sees.
+ */
 export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
+  pinnedPath?: string,
 ): QueryClientMethod<TInput, TRow> {
+  return methodsOf<TInput, TRow>(name, options, pinnedPath);
+}
+
+/**
+ * A download query's client half: `url(input)` asks the server to mint. A GET with no `_token` IS
+ * the mint, so the request is the plain read's and only the answer — `{ url, expiresAt }` — differs.
+ */
+export function downloadClientFor<TInput extends StandardSchemaV1>(
+  name: string,
+  options: QueryClientOptions,
+): DownloadClientMethod<TInput> {
+  return { url: methodsOf<TInput, object>(name, options).url };
+}
+
+/** The rows call, `page` and `url` over one base — `url` typed only on a download's method. */
+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>>;
-  return Object.assign(rows, { page });
+  ) => 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,
+      undefined,
+      path,
+    )) as DownloadUrl;
+    return { ...minted, url: base + minted.url };
+  };
+  return Object.assign(rows, { page, url });
 }
 
 /**
@@ -181,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 }),
@@ -199,43 +260,3 @@ function read(
     ...(options.fetch === undefined ? {} : { fetchImpl: options.fetch }),
   });
 }
-
-/**
- * Input as a query string. Keys are sorted so the same input always produces the
- * same URL — a GET is a cache key, and an unstable one caches nothing.
- *
- * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
- * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
- * split at `_first=` to recover the read underneath.
- *
- * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
- * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
- */
-function searchOf(input: unknown, page?: PageControls): string {
-  const params = new URLSearchParams();
-  if (isJsonObject(input)) {
-    for (const key of Object.keys(input).sort()) {
-      const value = input[key];
-      if (value === undefined || value === null) continue;
-      for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
-        params.append(key, wireText(item));
-      }
-    }
-  }
-  if (page !== undefined) {
-    params.append(PAGE_FIRST_KEY, String(page.first));
-    if (page.after !== undefined) params.append(PAGE_AFTER_KEY, page.after);
-  }
-  return params.toString();
-}
-
-/**
- * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
- * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
- * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
- * as the text it prints and the read's own schema says what is wrong with it.
- */
-function wireText(item: unknown): string {
-  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
-  return typeof item === 'object' ? JSON.stringify(item) : String(item);
-}

package/src/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);
+}