@voltro/protocol 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -39,6 +39,133 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.52.0] — 2026-08-25
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/web, @voltro/plugin-storage, @voltro/plugin-ratelimit** — The HTTP surface is complete — seven gaps closed, each proven against the real listener.
+
+  **Binary byte streams.** REST handlers return `bytes(stream, { contentType, contentLength?, contentDisposition? })` (lazy thunk form defers opening the source); plugin routes return `byteStream`. Piped, never buffered (a 256 MiB export streams with bounded heap), never compressed. Idempotency × stream is DECIDED: `streaming: true` on an idempotent method with an idempotency binding is a mount error (a stream cannot cache a replayable body — retries would 409 until the TTL); an undeclared stream releases its claim at return. Storage's full-object download rides the generic path now.
+
+  **Negotiated compression + conditional GET.** brotli/gzip negotiated with a compressible-type allowlist, 1 KiB threshold, `Vary: Accept-Encoding` always on compressible types — on the api's buffered responses AND `voltro start`'s HTML (`http.compression.{enabled,minBytes}`). The BREACH position is structural: `POST /rpc` responses are NEVER compressed. ISR keeps ONE uncompressed entry and compresses per hit. `voltro start` answers `If-None-Match` with 304 (weak md5 tags over the uncompressed body); REST routes can declare `etag: true` (GET, weak SHA-1 content tag).
+
+  **Raw WebSocket gateways.** `defineWebSocket({ path, auth, onConnection })` in a `*.ws.ts` file — for FOREIGN protocols (a Yjs provider, a device fleet); app realtime stays the subscription protocol. `auth` is required with no default: `'subject'` runs the same chain as rpc/SSR BEFORE the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code 4001); `'public'` is a written-down decision. Every gateway path joins the upgrade origin guard (cross-site WebSocket hijacking → 403). Teardown at construction; plain GET → 426; duplicate paths refuse the boot.
+
+  **Body caps everywhere.** The 8 MiB cap used to guard only `/rpc`; plugin routes read uncapped and webhooks read uncapped AND UTF-8-round-tripped (corrupting binary bodies — fixed, proven byte-for-byte). `http.maxBodyBytes` (env `VOLTRO_MAX_BODY_BYTES`), per-route overrides on `defineRestRoute` and webhook handlers; a shared path takes its group's widest override. 413 for both request shapes.
+
+  **Full method unions.** PATCH/HEAD/OPTIONS are first-class on plugin and REST routes; HEAD is admitted wherever GET is (RFC 9110) with the transport dropping the body.
+
+  **BREAKING — the interceptor chain is fail-closed.** A throwing `onHttpRequest` interceptor is a 500 + a log line now; it used to be swallowed, which let a crashed security gate silently stop guarding. The manual codemod tells interceptor authors where the decision lives: propagate (a gate) or catch-and-degrade-loudly (protection with a dependency) — plugin-ratelimit's httpShield now does the latter, so a Redis outage cannot become a self-inflicted API outage. No app-authored call sites change shape, hence `apiSurface: compatible` — the break is the error POLARITY of one plugin-author hook, carried by the manual note.
+
+  **Middleware response headers + CSP nonce.** `middleware.ts` can return `responseHeaders` (applied on every render response shape, both boot paths; prerendered static files are the documented proxy-side limit) and `cspNonce` — the framework stamps every script tag of that render (React's own included) while the policy header stays the middleware's. `isr` + `cspNonce` is refused loudly: a cached nonce is a lie the browser enforces.
+
+  Deliberate limits: no multipart parser on REST/webhook routes (the storage upload routes are the sanctioned file path); static-file response headers belong at the proxy.
+- **@voltro/plugin-row-history, @voltro/cli** — `@voltro/plugin-versioning` is renamed to `@voltro/plugin-row-history` — the name now says what it does.
+
+  The old name collided head-on with API versioning (versioned REST routes, `/v1` → `/v2`, sunset flow), which `defineRestRoute` now supports as a first-class `version:` field. What this plugin does is row history + time travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions` over `_voltro_row_history`); every comparison table that filed it under API versioning was reading the name, not the feature.
+
+  Renamed with it: the factory (`versioningPlugin` → `rowHistoryPlugin`), the options type (`VersioningPluginOptions` → `RowHistoryPluginOptions`), and the default instance alias (`versioning` → `row-history` — the inspect endpoint path and boot-log lines; an explicit `alias:` you passed is untouched). The table name (`_voltro_row_history`) and `VOLTRO_ROW_HISTORY_TTL_HOURS` already carried the new name: no data movement, no env change, no migration.
+
+  The codemod rewrites imports, the factory call sites and the options-type references, and prints the one step it cannot do — swapping the dependency in package.json.
+
+### Added
+
+- **@voltro/cli** — `voltro doctor` now reports every declared `@voltro/*` dependency with no import site — the residue a migration off a framework package leaves in `package.json`, where it keeps getting installed, walked by `voltro update`, and read as evidence the package is in use, its breaking-change notes included.
+
+  Scoped to `@voltro/*` deliberately (third-party packages have too many legitimate no-import shapes), and three states are distinguished and printed: exempt by name with a reason (`@voltro/cli` is the binary, `@voltro/devtools` is mounted by `voltro dev`, `@voltro/sql-*` drivers are loaded from config); not-measurable-yet for `@voltro/client`/`@voltro/web` on a tree where codegen has never run (a missing measurement, not a dead dependency); and unimported — advisory, never fatal. A mention in a comment or an error string does not count as an import, and a commented-out import counts least of all: it is the artefact the rule exists to see past. Also in `voltro doctor --json` under `unimportedDeps`, `null` when no `package.json` could be read.
+- **@voltro/web, @voltro/cli** — Islands now save real bytes — every `interactive: 'islands'` page gets its OWN browser entry.
+
+  Measured on the reference fixture (pinned in `bundle-budget.json`, 2026-08-25): an islands page's first load is **59.6 KB gz** against **181.9 KB gz** for a fully hydrated page — react + the island runtime + that page's islands, no router, no Effect runtime, no subscription cache. The bundle-budget gate pins a hard <70 KB bound AND the ratio (<50 % of a full page), so a regression that re-couples the entries fails loudly.
+
+  - **`@voltro/web/islands`** is the new react-only subpath — `island()` and the hydration runtime import only react + react-dom/client. Importing the `@voltro/web` BARREL (or `@voltro/i18n`) anywhere in an island's import graph is now a BUILD error naming file and specifier: an island hydrates provider-less, router hooks and `useT()` throw there anyway, and the barrel would pull the Effect runtime into the slim entry. - **The build finds each page's islands** through its relative import graph (transitively, through components in between) and emits one shell + entry per islands page. `interactive` must be a source LITERAL to select the slim entry — a computed value ships the full entry as before, and the build says so. - **All three paths**: `voltro build` (SSG renders into the per-page shell, main-shell stylesheets folded in), `voltro start` (ssr/isr islands routes serve their shell), `voltro dev` (same mechanism on demand — violations fire in dev, not first in CI). Fixed on the way: a STATIC islands page fell through dev's render gate to the SPA fallback and loaded the full app entry — dev now server-renders it like production. - **Framework islands**: an island importing `@voltro/client` (`useSubscription`, …) is detected — that page's entry boots the rpc client and wraps each island root in `VoltroRuntimeProvider`, so the island receives live data. Presentational pages never pay for the client core. - **`hydrate: 'only'`** (Astro's `client:only`): the server renders an empty placeholder — a browser-only lib touching `window` in render no longer crashes the SSR pass — and the client mounts fresh with `createRoot`. - **Island props are declared lossy where they are**: props cross an HTML attribute as JSON, so a `Date` arrives as an ISO string and `Map`/`Set`/ functions do not arrive at all — dev warns naming the island and prop. - The per-island `manualChunks` rule is gone: with per-page entries as additional rollup inputs it MERGED the shared react modules into the island group (a second-React-instance shape); per-island chunks were also redundant — the entry already scopes to the page's islands, and they were statically preloaded anyway.
+
+  Limits: an islands page reached via SPA navigation from a full page runs in the already-loaded app bundle (the saving applies to hard loads of the islands page); a page's islands share one entry (hydrate strategies control WHEN each hydrates, not when it downloads).
+
+  Why the golden churn is compatible: `hydrate: 'only'` widens a union, `hydrateIslandsOnPage` gains an optional options argument, and the subpath is a new export.
+- **@voltro/ui, @voltro/client, @voltro/web, @voltro/cli** — Forms without JavaScript — `<AutoForm>` on a server-rendered page now works with JS disabled, end to end.
+
+  The form always renders `action="/form/<mutationTag>"` + `method="post"`; with JS alive, `onSubmit` intercepts exactly as before (optimistic rpc path unchanged). The `/form/*` endpoint is mounted by the WEB listener on BOTH boot paths (`voltro dev` and `voltro start`, one shared builder):
+
+  - **Origin-checked at the door** with the same `classifyRequestOrigin` the api's rpc listener runs — a cross-origin form POST is a 403 before a byte of the body is parsed. (The server-side forward reaches the api as a no-browser-origin request, so the web listener's check is the one that guards this surface.) - **One validation path.** The urlencoded body maps through the schema-driven `formDataToInput` (checkbox present/absent → true/false, `''` on number/date omits the field — never a silent 0 —, repeated keys → arrays, non-numeric strings pass through RAW so the decode fails honestly instead of minting NaN, unknown keys dropped) and validates with the SAME `validateFields` the client-side submit runs — byte-identical field errors. - **PRG on success**: 303 back to the submitting page, or to `<AutoForm redirectTo>` (same-origin relative paths only — anything else is refused, a hidden field must not become an open redirect). Reloading the redirected-to page cannot resubmit. - **422 re-render on validation failure**: the referring page renders in the same response with field errors + submitted values in the SAME error UI (`role="alert"`, aria unchanged), `cache-control: no-store`, bypassing the ISR cache in both directions. An rpc refusal after valid input (guard, server error) renders as a form-level error. The flash also embeds as a JSON script, so a page whose bundle arrives late hydrates to the identical state. - **Valid submits forward server-side over `POST /rpc`** with the request's cookie — auth middleware, guards and the rpc interceptor chain run identically to every other mutation.
+
+  New `<AutoForm>` props: `formKey` (several forms per page — the 422 re-render re-fills only the submitted one), `redirectTo`, and `action={false}` for purely static deploys where `/form/*` does not exist. Headless: `useFormBinding` gains `flash` + `formError`, `@voltro/web` gains `useFormFlash(formKey)`.
+
+  Also fixed on the way: a required `Schema.Boolean` field with no default used to block the JS submit as "missing" while its checkbox rendered visibly unchecked — boolean fields now seed `false`, agreeing with what the user sees (and with the no-JS mapping).
+
+  Deliberate limits: the no-JS error re-render needs an `ssr`/`isr` page (a static page cannot be re-rendered with request state; a minimal error page is the fallback); a purely static deploy has no `/form/*` endpoint (use `action={false}`); file uploads stay JS-only (multipart → 415). On an ssr page pass `schema` explicitly — descriptor resolution is a client-runtime feature and the SSR render would otherwise show no fields.
+
+  Bundle note: the `serverContext` chunk group is renamed `serverRequest` by the context's move to @voltro/client — identical 190 B gz, re-pinned in `bundle-budget.json` (fresh full measurement 2026-08-25: firstLoad 185,494 B gz, was 185,309 — +185 B from the form-flash read in the request context).
+
+  Why the golden churn is compatible: every addition is a new export or an optional prop; `FormBinding.formError` is a new member of the hook's RETURN type (nothing in the public API accepts a caller-built `FormBinding`), and `ServerRequestContextValue.formFlash` is optional.
+- **@voltro/runtime, @voltro/cli, @voltro/cms, @voltro/plugin-broadcast** — On-demand ISR revalidation — the third invalidation axis next to time (`revalidate`) and CDC (`cacheInvalidatesOn`). Server code in the api process calls `revalidatePath('/blog/[slug]')` / `revalidateTable('posts')` / `revalidateTag('pricing')` (exported from `@voltro/runtime`; callable from mutations, actions, webhook receivers and REST routes) and the matching ISR cache entries fall on EVERY `voltro start` replica — including on dialects with no CDC at all, which is the case this exists for.
+
+  Transport is dialect-shaped, either or both: on postgres a `pg_notify` rides the SAME LISTEN connection the CDC invalidator already holds (no broker needed); everywhere else the broadcast broker carries it (`BROADCAST_URL` on both deployments; channel namespaced by `VOLTRO_BROADCAST_NAMESPACE` — deliberately env-derived, because this channel pairs an api with its WEB app and no shared name is derivable). A web process with isr routes and neither transport warns loudly at boot; under `voltro dev` the calls are documented debug-logged no-ops. Tags share ONE mechanism with tables — `cacheInvalidatesOn` accepts free strings, so `revalidateTag` is the same sink under another name.
+
+  Correctness edges built in: `revalidatePath` against a `static` route is a NAMED error on the web process (never a silent no-op); a purge landing while an SWR refresh or miss fill renders is guarded by a per-key generation counter on BOTH cache backends — the pre-purge page cannot be written back with a full TTL, and a refused write also suppresses the postgres backend's fire-and-forget upsert so no replica resurrects a deleted row. A content type declares `revalidate: { paths, tags }` and `publish()`/`unpublish()` fire them after commit.
+
+  Proven end-to-end (`scripts/revalidate-e2e.mjs`): 1 api + 2 `voltro start` replicas behind Redis (warm → purge → both fresh, with a negative control), the sqlite dialect leg, and a broker-less postgres leg where the NOTIFY line alone carries the purge to a LISTEN-only replica.
+
+  `apiSurface: compatible` — additive only: the new `@voltro/runtime` revalidation exports, an optional `revalidate` on `ContentTypeSpec`, the optional `onRevalidate`/`revalidateChannel` on the CDC invalidator options, a widened `BroadcastChannelKind`, and `IsrCache.set`'s new optional generation guard (plus `generation()`).
+- **@voltro/protocol, @voltro/plugin-openapi** — `defineRestRoute` takes an opt-in `version:` — versioned REST APIs with a sunset flow.
+
+  `version: 'v2'` + `path: '/customers'` mounts the route at `/v2/customers`, the same `/vN/` convention the `publicApi:` projection and the built-in `/v1/api-keys` surface already use. The path is normalised ONCE at definition time, so every consumer — the mount, path-param matching, the idempotency scope, tracing spans, the OpenAPI generator — sees the mounted path and none can disagree.
+
+  Deliberate edges:
+
+  - **Opt-in, no auto-prefix.** A route without `version:` keeps its literal path untouched — an automatic prefix would silently move every deployed route. A path that already starts with `/vN/` AND declares `version:` is refused loudly at definition (both spellings at once is never what the author meant). - **Two versions are two descriptors.** The old version is ordinary code — visible, testable, deletable — carrying `deprecated:` (the replacement pointer) and `sunset:` (the date it starts answering `410 Gone`; the 410 body now also names which `version` died). - **One OpenAPI document for every version.** The `/vN/` prefix already separates the paths; each versioned operation is grouped under a version tag and carries `x-voltro-api-version` for tooling. No `?version=` filtered spec — a second document shape for information the paths already state. - The rpc socket stays outside URL versioning on purpose: the generated client is versioned with the server it was generated from. A stale browser tab runs the previous client until reload — that skew window exists and is documented, not solved by URLs.
+- **@voltro/web, @voltro/cli** — Opt-in View Transitions for SPA navigations. `router.viewTransitions: true` in a web `app.config.ts` runs every route swap — `<Link>` clicks, `navigate(...)`, back/forward — through `document.startViewTransition`; individual navigations override the default in either direction with `navigate(to, { transition })` / `<Link transition>`.
+
+  The visual swap is the router's deferred-navigation commit, flushed synchronously inside the transition callback — by that point the target's lazy chunk and loaders have settled, so the flushed tree renders with data in hand. Three deliberate behaviors: `defer()` fields (and an explicit `Pending` skeleton's settled content) resolve AFTER the transition as ordinary updates, never a second animation; navigating while a transition is animating skips the running one (last navigation wins, nothing queues); overlay/dialog state changes never trigger one — a root snapshot would cross-fade the whole viewport for a one-layer change.
+
+  Fallback is exact: a browser without the API, and any user with `prefers-reduced-motion: reduce`, gets today's untransitioned swap — same timing, nothing to feature-detect. Styling is plain `::view-transition-*` CSS (no animation DSL); cross-document transitions for static/MPA pages are a one-line `@view-transition` CSS opt-in with no framework involvement.
+
+  Proven in a real chromium (`scripts/browser-view-transitions.mjs`): called on navigation, silent under reduced-motion, harmless with the API deleted, one transition across a `defer()` commit, rapid double-navigation lands on the last target — plus the jsdom wiring suite and the generated-entry flag check shared by all three web boot paths.
+
+  `apiSurface: compatible` — additive only: a new optional `viewTransitions` on `RouterProps`, optional `transition` on `NavigateOptions`/`LinkProps`, and the optional `router` block on the web app config.
+- **@voltro/web, @voltro/cli** — Schema-typed search params — the query-string half of the URL is now part of the type graph.
+
+  A page declares its contract once:
+
+  ```ts
+  export const searchParams = Schema.Struct({
+    q:    Schema.optionalWith(Schema.String, { default: () => '' }),
+    page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+  })
+  ```
+
+  and gets, end to end:
+
+  - **Typed reads** — `useSearchParams(searchParams)` returns the decoded, defaulted shape, SSR-aware; the zero-arg call keeps returning the raw `URLSearchParams`. Decoding is TOTAL: an invalid query falls back to the schema's defaults instead of crashing a render; only a schema that cannot even decode `{}` (a required field with no default) throws, naming the fix. - **Typed links** — the generated `routes` builder brands the route's URL with the schema's shape through a TYPE-ONLY page import (zero value edges: code-splitting is untouched, pinned by test), and `withQuery` type-checks against it — a misspelt key or wrong value type is a compile error. The link-side encode is canonical and schema-free (strings/numbers/booleans, arrays as repeated keys); a roundtrip test pins that it produces exactly what the schema's decode accepts. Deliberately ONE generic signature rather than overloads: with overloads, a wrong key would silently fall through to the permissive untyped form and the compile error would never fire. - **Typed writes** — `useSetSearchParams(searchParams)` returns the typed setter: its object form replaces the query (same semantics as the untyped form), and its updater form receives the CURRENT decoded params, so keeping `?filter` across a page flip is one explicit spread — `setParams((p) => ({ ...p, page: p.page + 1 }))` — instead of a hand-rolled merge. - **A fail-closed isr gate** — `renderMode: 'isr'` plus a `searchParams` export is refused at boot: the isr cache is keyed by path (+tenant+locale), not query, so the first variant would be cached for every query — and the gate catches the re-exported spelling (`export { searchParams } from …`, the mirror-route pattern) too, not only the local declaration. - **A doctor rule** — a page that exports the schema but keeps reading the query with zero-arg `useSearchParams()` is flagged with the typed spelling.
+
+  Deliberate limits: array fields decode a single occurrence as a one-element array (link shape stays stable); `siblingApps` routes stay untyped (their schemas live in a foreign compile graph); `static` pages see the defaults at build time and decode live on the client.
+
+  Why the golden churn is compatible: `VoltroRouteUrl` gains a type parameter with a DEFAULT (`<TSearch = unknown>`), so every existing bare `VoltroRouteUrl` spelling still compiles, and the new brand member is an OPTIONAL phantom property of type `unknown` — assignability in both directions is unchanged. `withQuery`'s parameter for the untyped case is strictly WIDER than before (adds `boolean` and array values); no call that compiled stops compiling.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md`'s copied `agent-docs/` mirror no longer keeps orphaned modules across a re-seed.
+
+  The copy fallback (projects where `@voltro/cli` isn't resolvable) merged into an existing `agent-docs/` directory: when a module was renamed upstream (`plugins/versioning.md` → `plugins/row-history.md`), a `--force` re-seed brought the new file and left the old one sitting beside it — a stale generated doc teaching a package name that no longer exists, which is exactly the claim≠code drift the guide exists to prevent. The mirror is wholly framework-owned, so a re-seed now replaces it (the generator prunes its own output dir the same way).
+- **@voltro/cli** — `voltro check`'s observed-diff footer now accounts for every declared procedure, and no result line states a verdict without the count it is a verdict about.
+
+  Two defects, both found by readers doing arithmetic on the output:
+
+  - The diff computes TWO kinds of blindness — a procedure that never ran, and one that ran with no table access recorded — and the printer named only the first. The printed counts came out short of the total, with no way to tell an unshown category from a defect in `check` itself. The buckets are now derived from the result type, so a third one cannot be added without the label map failing to compile, and a partition that does not close prints as such instead of quietly under-counting. - `no declared/observed mismatches` was a bare verdict sitting under its denominator, and was quotable — and quoted — without it, as a clean bill of health for a surface where almost nothing had been exercised. Every result line now carries its scope (`no declared/observed mismatch among the 12 that ran`), and at zero coverage the section reports the ABSENCE of a comparison (`nothing was compared — a declaration is only checked against a procedure that RAN`) rather than the absence of findings. The two are different facts and only one of them is evidence.
+- **@voltro/cli** — An `isr` render no longer sees the requesting visitor's credentials — in `voltro dev` and `voltro start` alike.
+
+  An isr page's HTML is cached under tenant+locale and served to every visitor inside the revalidate window, but the render itself ran with the FULL request: loaders received the session cookie, and `ctx.query` was bound to it. A loader that read subject-scoped data on an isr page therefore cached the first visitor's data and served it to everyone — cache poisoning by construction.
+
+  The render boundary is fail-closed now: before an isr render runs, the cookie jar (except `voltro:locale`), the `authorization` header and every `x-voltro-*` header are stripped, for the loaders, `ctx.query` AND the `useServerRequest()` snapshot. What survives is exactly what the cache key and locale resolution read: `x-tenant`, `accept-language`, and the locale cookie — so a `de` visitor's fill still lands under the `de` key. One shared helper (`isrCredentialStrip.ts`), called by both boot paths, so dev renders isr anonymously exactly as production does — a page can no longer look personalised in dev and silently serve shared HTML in production.
+
+  Behavioural consequence, on purpose: a subject-reading loader on an isr page now gets the anonymous answer. A page whose loader needs the signed-in subject belongs on `renderMode: 'ssr'`.
+- **@voltro/cli, @voltro/runtime** — **`voltro serve` registers plugin rpc routes again — every plugin-contributed procedure answered `Unknown request tag` in production while `voltro dev` registered all of them.** The serve path mirrored dev's plugin-route block by hand and mirrored exactly half of it: the collision check ran (so nothing warned) and the returned routes were discarded as a bare expression statement, never reaching the buckets the rpc registry is built from. Every plugin route was indistinguishable from a tag that never existed — `useUpload`'s storage tags, presence, every inspect-less plugin rpc — while the app's own procedures answered normally, so the registry looked alive.
+
+  Three changes, each aimed at the way this stayed invisible:
+
+  - Both boot paths now call ONE shared builder (`mergePluginRoutesInto`) whose buckets are required parameters — a returned list can be discarded by a statement that typechecks; a function you cannot call without handing it the sinks cannot have its effect dropped. A reachability test drives a real socket with a plugin tag and an invented-tag control, and a source pin keeps the helper pair from being reassembled by hand in either path. - The boot line `plugin routes registered` prints WHENEVER plugins are installed, count included — zero is a finding, and silence is how this shipped. `voltro check` against a running server now also diffs source-declared tags against the live registry (`declared vs live:`), and its offline manifest includes plugin routes, which it previously did not. - Every `Defect` frame the server sends is now also a server log line (`rpc defect sent to client`, ws and http rpc). The defect string used to exist only inside the WebSocket frame — visible in whoever's browser console, invisible to the operator whose server produced it.
+
+---
+
 ## [0.51.0] — 2026-08-24
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -1623,6 +1623,13 @@ export declare const defineStream: <const Name extends string, Input extends Sch
     readonly openAccess?: string;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
+/**
+ * Declare a raw WebSocket gateway (`*.ws.ts` default export). Validation at
+ * DEFINITION time — a bad path fails the boot that discovers it, not the
+ * first client.
+ */
+export declare const defineWebSocket: (route: WebSocketGatewayRoute) => WebSocketGatewayRoute;
+
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'delete';
@@ -2027,6 +2034,11 @@ export declare const finishIdempotent: (store: IdempotencyStore, scope: string,
 /** A route rendered for humans — logs, the inspect surface, the dashboard. */
 export declare const formatEventRoute: (route: string) => string;
 
+/** Close code a gateway connection receives when its credential expires —
+ *  the same session-expiry contract the rpc socket has (SEC-16), spelled as
+ *  an application close code so foreign clients can reauth + reconnect. */
+export declare const GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE = 4001;
+
 /** The currently-registered policy-guard resolver, or `undefined`. */
 export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefined;
 
@@ -2897,12 +2909,19 @@ export declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 export declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). */
-    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
+     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
+     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
+     *  for its other job: one dispatcher per shared path + a precise 405). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
     /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /** Per-route body cap override (bytes) — wins over the listener's shared
+     *  `maxBodyBytes`. NOTE: routes SHARING a path share one body read, so the
+     *  widest override on the path's group applies to the whole group. */
+    readonly maxBodyBytes?: number;
     /**
      * Opt this route's path OUT of the listener's cross-site origin check.
      *
@@ -2941,6 +2960,21 @@ export declare interface PluginHttpRoute {
     readonly originGuard?: 'exempt';
 }
 
+/**
+ * A binary streaming body — the download/export shape. The serve layer pipes
+ * the Web ReadableStream to the socket without buffering, so a response
+ * larger than the heap is fine; the LAZY thunk form defers opening the
+ * source (a provider connection, a file handle) until the response actually
+ * streams.
+ */
+export declare interface PluginHttpRouteByteStream {
+    readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+    /** Declared up front when known — lets the client render progress. */
+    readonly contentLength?: number;
+    /** e.g. `attachment; filename="export.zip"`. */
+    readonly contentDisposition?: string;
+}
+
 export declare interface PluginHttpRouteRequest {
     readonly method: string;
     /** Path WITHOUT query string. */
@@ -3052,6 +3086,12 @@ export declare interface PluginHttpRouteResult {
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
+    /** Stream a BINARY response (a download, an export) instead of sending
+     *  `body` — see {@link PluginHttpRouteByteStream}. Never buffered by the
+     *  serve layer; never compressed (flush timing + Content-Length are the
+     *  contract). Takes precedence over `body`; do not set both `stream` and
+     *  `byteStream`. */
+    readonly byteStream?: PluginHttpRouteByteStream;
 }
 
 /**
@@ -5216,6 +5256,48 @@ export declare interface VoltroPlugin {
 export declare interface VoltroTableNames {
 }
 
+/** What a gateway's connection handler receives. Transport-agnostic on
+ *  purpose — the runtime adapts the platform socket to this. */
+export declare interface WebSocketGatewayConnection {
+    /** Send a text or binary frame. */
+    readonly send: (data: string | Uint8Array) => void;
+    /** Close the connection (application close codes 4000-4999 are yours). */
+    readonly close: (code?: number, reason?: string) => void;
+    /** Register a message listener (binary-safe; text arrives as bytes). */
+    readonly onMessage: (listener: (data: Uint8Array) => void) => void;
+    /** The authenticated subject — `null` only on an `auth: 'public'` route. */
+    readonly subject: Subject | null;
+    /** Lowercased request headers of the upgrade. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The mounted path. */
+    readonly path: string;
+}
+
+export declare interface WebSocketGatewayRoute {
+    /** Absolute upgrade path (`/gateways/yjs`). Must not collide with the rpc
+     *  socket (`/ws` or the configured `transport.wsPath`) or `/rpc`. */
+    readonly path: `/${string}`;
+    /**
+     * REQUIRED, no default: who may connect.
+     * - `'subject'` — the upgrade resolves a Subject through the SAME auth
+     *   chain as rpc/SSR (cookie/bearer); an unauthenticated upgrade is a 401
+     *   BEFORE any socket exists, and the connection closes with
+     *   {@link GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE} when the credential
+     *   expires.
+     * - `'public'` — deliberately unauthenticated (a device fleet with its own
+     *   protocol-level auth). A decision somebody wrote down, not a default.
+     */
+    readonly auth: 'subject' | 'public';
+    /**
+     * Runs once per accepted connection. The returned function is the
+     * connection's TEARDOWN — taken at construction (the `startOutboxRunner`
+     * rule): it runs on client disconnect, on credential expiry, and on
+     * server shutdown, so whatever the handler opened cannot outlive the
+     * socket.
+     */
+    readonly onConnection: (connection: WebSocketGatewayConnection) => void | (() => void) | Promise<void | (() => void)>;
+}
+
 /**
  * The error union a procedure ACTUALLY puts on the wire — `descriptor.error`
  * plus everything the framework can produce for it before or around the

package/dist/index.js

@@ -378,56 +378,56 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 }), Dt = d.Struct({ _tag: d.Literal("attached") }), Ot = (e) => d.Union(Dt, Tt(e), Et), kt = d.Struct({
 	origin: d.String,
 	n: d.Number
-}), At = (e) => d.Struct({
+}), G = (e) => d.Struct({
 	key: e,
 	resume: d.optional(d.Array(kt))
-}), jt = (e, t) => {
+}), At = (e, t) => {
 	let n = e.guards !== void 0 && e.guards.some((e) => !l(e)) ? d.Union(c, s) : d.Never, r = t && t.length > 0 ? d.Union(n, ...t) : n;
 	return f.make(e.name, {
-		payload: b(At(e.key), e.name, U(e.guards)),
+		payload: b(G(e.key), e.name, U(e.guards)),
 		success: Ot(e.payload),
 		error: r,
 		stream: !0
 	});
-}, Mt = class extends d.TaggedError()("EventPayloadInvalid", {
+}, jt = class extends d.TaggedError()("EventPayloadInvalid", {
 	event: d.String,
 	message: d.String
-}) {}, Nt = class extends d.TaggedError()("EventKeyInvalid", {
+}) {}, Mt = class extends d.TaggedError()("EventKeyInvalid", {
 	event: d.String,
 	message: d.String
-}) {}, Pt = class extends d.TaggedError()("EventPayloadTooLarge", {
+}) {}, Nt = class extends d.TaggedError()("EventPayloadTooLarge", {
 	event: d.String,
 	bytes: d.Number,
 	limit: d.Number
-}) {}, Ft = (e) => {
+}) {}, Pt = (e) => {
 	if (typeof e != "object" || !e) return JSON.stringify(e) ?? "null";
 	let t = Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t));
 	return JSON.stringify(t);
-}, It = "\0", Lt = (e, t, n) => [
+}, Ft = "\0", It = (e, t, n) => [
 	e ?? "~",
 	t,
-	Ft(n)
-].join("\0"), Rt = (e) => {
+	Pt(n)
+].join("\0"), Lt = (e) => {
 	let [t = "~", n = "", r = ""] = e.split("\0");
 	return {
 		tenantId: t === "~" ? null : t,
 		event: n,
 		key: r
 	};
-}, zt = (e) => e.split("\0").join(" · "), Bt = (e) => e, Vt = (e) => e, Ht = (e) => {
+}, Rt = (e) => e.split("\0").join(" · "), zt = (e) => e, Bt = (e) => e, Vt = (e) => {
 	let t = e.alias?.trim(), n = e.instance?.trim(), r = t !== void 0 && t !== "" ? t : e.base;
 	return n !== void 0 && n !== "" ? `${r}#${n}` : r;
-}, Ut = (e) => {
+}, Ht = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, Wt = (e, t) => {
+}, Ut = (e, t) => {
 	let n = He.GenericTag(e);
 	return {
 		Tag: n,
 		Live: Ue.succeed(n, t)
 	};
-}, Gt = (e, t, n) => {
+}, Wt = (e, t, n) => {
 	if (!t) return { ok: !0 };
-	let r = G(n);
+	let r = K(n);
 	if (!r) return {
 		ok: !1,
 		reason: `cannot parse runningVersion "${n}"`
@@ -435,12 +435,12 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	let i = t.trim();
 	if (i === "*" || i === "") return { ok: !0 };
 	let a = i.split(/\s+/).filter((e) => e.length > 0);
-	for (let i of a) if (!Kt(i, r)) return {
+	for (let i of a) if (!Gt(i, r)) return {
 		ok: !1,
 		reason: `plugin "${e}" requires framework ${t}, running ${n}`
 	};
 	return { ok: !0 };
-}, G = (e) => {
+}, K = (e) => {
 	let t = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9a-zA-Z.-]+))?$/.exec(e.trim());
 	return t ? {
 		major: Number(t[1]),
@@ -448,44 +448,44 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 		patch: Number(t[3]),
 		pre: t[4] ?? ""
 	} : null;
-}, K = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, Kt = (e, t) => {
+}, q = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, Gt = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
-		let n = G(e.slice(1));
-		return !n || t.major !== n.major ? !1 : K(t, n) >= 0;
+		let n = K(e.slice(1));
+		return !n || t.major !== n.major ? !1 : q(t, n) >= 0;
 	}
 	if (e.startsWith("~")) {
-		let n = G(e.slice(1));
-		return !n || t.major !== n.major || t.minor !== n.minor ? !1 : K(t, n) >= 0;
+		let n = K(e.slice(1));
+		return !n || t.major !== n.major || t.minor !== n.minor ? !1 : q(t, n) >= 0;
 	}
 	let n = /^(>=|<=|>|<)(.+)$/.exec(e);
 	if (n) {
-		let e = n[1], r = G(n[2]);
+		let e = n[1], r = K(n[2]);
 		if (!r) return !1;
-		let i = K(t, r);
+		let i = q(t, r);
 		if (e === ">=") return i >= 0;
 		if (e === "<=") return i <= 0;
 		if (e === ">") return i > 0;
 		if (e === "<") return i < 0;
 	}
-	let r = G(e);
-	return r ? K(t, r) === 0 : !1;
-}, q = d.Literal("running", "succeeded", "failed", "cancelled", "suspended"), qt = d.Literal("cancel", "terminate", "abandon"), Jt = d.Struct({
+	let r = K(e);
+	return r ? q(t, r) === 0 : !1;
+}, J = d.Literal("running", "succeeded", "failed", "cancelled", "suspended"), Kt = d.Literal("cancel", "terminate", "abandon"), qt = d.Struct({
 	mode: d.String,
 	dueAt: d.NullOr(d.Number),
 	retryAfterMs: d.NullOr(d.Number),
 	intentId: d.NullOr(d.String)
-}), Yt = d.Struct({
+}), Jt = d.Struct({
 	id: d.String,
 	workflowName: d.String,
 	executionId: d.NullOr(d.String),
 	status: d.Literal("running", "queued", "dropped", "skipped"),
-	deferral: d.optional(Jt)
-}), J = d.Struct({
+	deferral: d.optional(qt)
+}), Y = d.Struct({
 	id: d.String,
 	tag: d.String,
 	executionId: d.String,
-	status: q,
+	status: J,
 	payload: d.Unknown,
 	workflowVersion: d.NullOr(d.String),
 	workflowPatches: d.NullOr(d.Unknown),
@@ -500,12 +500,12 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	durationMs: d.NullOr(d.Number),
 	traceId: d.NullOr(d.String),
 	parentExecutionId: d.NullOr(d.String),
-	parentClosePolicy: d.NullOr(qt)
-}), Xt = d.Struct({
+	parentClosePolicy: d.NullOr(Kt)
+}), Yt = d.Struct({
 	tag: d.optional(d.String),
-	status: d.optional(q),
+	status: d.optional(J),
 	limit: d.optional(d.Number)
-}), Zt = d.Struct({
+}), Xt = d.Struct({
 	id: d.String,
 	runId: d.String,
 	stepName: d.String,
@@ -520,7 +520,7 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	startedAt: d.Date,
 	completedAt: d.NullOr(d.Date),
 	durationMs: d.NullOr(d.Number)
-}), Qt = d.Struct({
+}), Zt = d.Struct({
 	id: d.String,
 	runId: d.String,
 	eventType: d.String,
@@ -528,7 +528,7 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	occurredAt: d.Date,
 	stepName: d.NullOr(d.String),
 	attempt: d.NullOr(d.Number)
-}), $t = d.Struct({
+}), Qt = d.Struct({
 	id: d.String,
 	name: d.String,
 	payload: d.Unknown,
@@ -536,7 +536,7 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	subject: d.NullOr(d.Unknown),
 	traceId: d.NullOr(d.String),
 	occurredAt: d.Date
-}), en = d.Struct({
+}), $t = d.Struct({
 	id: d.String,
 	eventId: d.String,
 	eventName: d.String,
@@ -549,122 +549,122 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 	errorMessage: d.NullOr(d.String),
 	createdAt: d.Date,
 	completedAt: d.NullOr(d.Date)
-}), tn = d.Struct({ id: d.String }), Y = d.Struct({ runId: d.String }), nn = d.Struct({
+}), en = d.Struct({ id: d.String }), X = d.Struct({ runId: d.String }), tn = d.Struct({
 	name: d.optional(d.String),
 	limit: d.optional(d.Number)
-}), rn = d.Struct({ eventId: d.String }), X = d.Struct({
+}), nn = d.Struct({ eventId: d.String }), Z = d.Struct({
 	workflowName: d.String,
 	executionId: d.String
-}), an = d.Struct({
+}), rn = d.Struct({
 	id: d.String,
 	signalName: d.String,
 	payload: d.optional(d.Unknown)
-}), on = d.Struct({
+}), an = d.Struct({
 	id: d.String,
 	updateName: d.String,
 	payload: d.optional(d.Unknown),
 	timeoutMs: d.optional(d.Number)
-}), sn = d.Struct({
+}), on = d.Struct({
 	eventId: d.String,
 	updateId: d.String,
 	completedEventId: d.String,
 	result: d.Unknown
-}), cn = z({
+}), sn = z({
 	name: "__voltro.workflow.run",
 	source: "_voltro_workflow_runs",
-	input: tn,
-	output: d.Array(J)
-}), ln = z({
+	input: en,
+	output: d.Array(Y)
+}), cn = z({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
-	input: Xt,
-	output: d.Array(J)
-}), un = z({
+	input: Yt,
+	output: d.Array(Y)
+}), ln = z({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
-	input: Y,
-	output: d.Array(Zt)
-}), dn = z({
+	input: X,
+	output: d.Array(Xt)
+}), un = z({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
-	input: Y,
-	output: d.Array(Qt)
-}), fn = z({
+	input: X,
+	output: d.Array(Zt)
+}), dn = z({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
-	input: nn,
-	output: d.Array($t)
-}), pn = z({
+	input: tn,
+	output: d.Array(Qt)
+}), fn = z({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
-	input: rn,
-	output: d.Array(en)
-}), mn = V({
+	input: nn,
+	output: d.Array($t)
+}), pn = V({
 	name: "__voltro.workflow.cancel",
-	input: X,
+	input: Z,
 	output: d.Struct({ ok: d.Boolean })
-}), hn = V({
+}), mn = V({
 	name: "__voltro.workflow.resume",
-	input: X,
+	input: Z,
 	output: d.Struct({ ok: d.Boolean })
-}), gn = V({
+}), hn = V({
 	name: "__voltro.workflow.signal",
-	input: an,
+	input: rn,
 	output: d.Struct({ eventId: d.String })
-}), _n = V({
+}), gn = V({
 	name: "__voltro.workflow.update",
-	input: on,
-	output: sn
-}), vn = "__voltro.undo.log", yn = "__voltro.undo.apply", bn = "__voltro.undo.redo", xn = d.Struct({
+	input: an,
+	output: on
+}), _n = "__voltro.undo.log", vn = "__voltro.undo.apply", yn = "__voltro.undo.redo", bn = d.Struct({
 	id: d.String,
 	tag: d.String,
 	label: d.NullOr(d.String),
 	undone: d.Boolean,
 	crossesAction: d.Boolean,
 	createdAt: d.String
-}), Sn = class extends d.TaggedError()("UndoNotFound", { invocationId: d.String }) {}, Cn = class extends d.TaggedError()("UndoForbidden", { invocationId: d.String }) {}, wn = class extends d.TaggedError()("UndoConflict", {
+}), xn = class extends d.TaggedError()("UndoNotFound", { invocationId: d.String }) {}, Sn = class extends d.TaggedError()("UndoForbidden", { invocationId: d.String }) {}, Cn = class extends d.TaggedError()("UndoConflict", {
 	invocationId: d.String,
 	reason: d.Literal("conflict", "action")
-}) {}, Tn = d.Union(Sn, Cn, wn), En = z({
-	name: vn,
+}) {}, wn = d.Union(xn, Sn, Cn), Tn = z({
+	name: _n,
 	source: "_voltro_undo_log",
 	input: d.Struct({ limit: d.optional(d.Number) }),
-	output: d.Array(xn),
+	output: d.Array(bn),
 	openAccess: "subject-scoped by construction: lists only the calling subject's own undoable actions"
-}), Dn = B({
-	name: yn,
+}), En = B({
+	name: vn,
 	input: d.Struct({ invocationId: d.String }),
 	output: d.Struct({ ok: d.Boolean }),
-	error: Tn,
+	error: wn,
 	openAccess: "subject-scoped by construction: undo is per-actor — another subject's invocation fails typed with UndoForbidden"
-}), On = B({
-	name: bn,
+}), Dn = B({
+	name: yn,
 	input: d.Struct({ invocationId: d.String }),
 	output: d.Struct({ ok: d.Boolean }),
-	error: Tn,
+	error: wn,
 	openAccess: "subject-scoped by construction: redo is per-actor — another subject's invocation fails typed with UndoForbidden"
-}), kn = class extends d.TaggedError()("TenantScopeViolation", {
+}), On = class extends d.TaggedError()("TenantScopeViolation", {
 	table: d.String,
 	reason: d.String
-}) {}, An = class extends d.TaggedError()("StoreOperationFailed", {
+}) {}, kn = class extends d.TaggedError()("StoreOperationFailed", {
 	operation: d.String,
 	table: d.String,
 	cause: d.String
-}) {}, jn = class extends d.TaggedError()("TableValidationFailed", {
+}) {}, An = class extends d.TaggedError()("TableValidationFailed", {
 	table: d.String,
 	summary: d.String,
 	issues: d.Array(d.Struct({
 		path: d.String,
 		message: d.String
 	}))
-}) {}, Mn = class extends d.TaggedError()("TenantRowNotFound", {
+}) {}, jn = class extends d.TaggedError()("TenantRowNotFound", {
 	table: d.String,
 	id: d.String,
 	reason: d.String
-}) {}, Nn = class extends d.TaggedError()("ServerOnlyColumnWrite", {
+}) {}, Mn = class extends d.TaggedError()("ServerOnlyColumnWrite", {
 	table: d.String,
 	columns: d.Array(d.String)
-}) {}, Pn = class extends d.TaggedError()("ConstraintViolation", {
+}) {}, Nn = class extends d.TaggedError()("ConstraintViolation", {
 	kind: d.Literal("foreignKey", "foreignKeyInUse", "unique", "notNull", "check"),
 	table: d.String,
 	operation: d.String,
@@ -681,14 +681,14 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 			case "check": return `check constraint ${t}: the row does not satisfy it`;
 		}
 	}
-}, Fn = "__voltro.approvals.pending", Z = "__voltro.approvals.decide", In = z({
-	name: Fn,
+}, Pn = "__voltro.approvals.pending", Fn = "__voltro.approvals.decide", In = z({
+	name: Pn,
 	source: "_voltro_approvals",
 	input: d.Struct({ limit: d.optional(d.Number) }),
 	output: d.Array(M),
 	openAccess: "the answer is scoped to the caller — a row appears only if they requested it or hold its recorded approver scopes, so an anonymous caller sees nothing"
 }), Ln = B({
-	name: Z,
+	name: Fn,
 	input: d.Struct({
 		approvalId: d.String,
 		decision: d.Literal("approve", "reject"),
@@ -755,6 +755,11 @@ var We = d.Union(d.String, d.Number), p = d.Record({
 }), Qn = (e) => {
 	let t = e instanceof Date ? e.getTime() : typeof e == "number" ? e : typeof e == "string" ? new Date(e).getTime() : 0;
 	return Number.isNaN(t) ? 0 : t;
-}, $n = 1;
+}, $n = 4001, er = /* @__PURE__ */ new Set(["/rpc", "/ws"]), tr = (e) => {
+	if (!e.path.startsWith("/")) throw Error(`defineWebSocket: path must be absolute, got '${e.path}'`);
+	if (er.has(e.path)) throw Error(`defineWebSocket: '${e.path}' is the framework's own socket surface — mount the gateway elsewhere`);
+	if (e.auth !== "subject" && e.auth !== "public") throw Error(`defineWebSocket: auth must be 'subject' or 'public' (explicitly — an unauthenticated socket has to be a decision somebody wrote down), got '${String(e.auth)}'`);
+	return e;
+}, nr = 1;
 //#endregion
-export { Oe as ADMIN_SCOPE, Ce as APIKEY_ISSUE_ORG_SCOPE, Ee as APIKEY_ISSUE_OTHER_SCOPE, ve as APIKEY_ISSUE_SELF_SCOPE, Z as APPROVALS_DECIDE_TAG, Fn as APPROVALS_PENDING_TAG, j as ApprovalDecisionErrors, A as ApprovalErrors, E as ApprovalExpired, O as ApprovalForbidden, C as ApprovalNotFound, D as ApprovalNotPending, T as ApprovalRejected, S as ApprovalRequired, w as ApprovalSelfApproval, k as ApprovalUnavailable, Ae as AuthMiddleware, x as BusinessRuleViolation, Rn as CONNECTIONS_LIST_TAG, Vn as CONNECTION_DISCONNECT_TAG, zn as CONNECTION_START_TAG, Bn as CONNECTION_SUBMIT_TOKEN_TAG, qn as ConnectionHandshakeFailed, ce as ConnectionInfo, i as ConnectionInfoMiddleware, Q as ConnectionKind, Kn as ConnectionKindMismatch, Wn as ConnectionNotDeclared, Un as ConnectionState, Hn as ConnectionStatus, Gn as ConnectionSubjectRequired, Pn as ConstraintViolation, r as DEFAULT_SCOPE_CACHE_MAX_ENTRIES, ie as DEFAULT_SCOPE_CACHE_TTL_MS, It as EVENT_ROUTE_SEP, Nt as EventKeyInvalid, Mt as EventPayloadInvalid, Pt as EventPayloadTooLarge, be as IMPERSONATION_METADATA_KEY, St as MAX_EVENT_ENVELOPE_BYTES, $n as PROTOCOL_VERSION, M as PendingApproval, N as REACTIVITY_CHANNEL_PREFIX, c as ScopeError, Nn as ServerOnlyColumnWrite, An as StoreOperationFailed, e as Subject, ye as SubjectIdentity, re as SubjectService, jn as TableValidationFailed, Mn as TenantRowNotFound, kn as TenantScopeViolation, yn as UNDO_APPLY_TAG, vn as UNDO_LOG_TAG, bn as UNDO_REDO_TAG, s as Unauthenticated, wn as UndoConflict, Cn as UndoForbidden, xn as UndoLogEntry, Sn as UndoNotFound, X as WorkflowControlInputSchema, $t as WorkflowDomainEventRowSchema, nn as WorkflowDomainEventsInputSchema, rn as WorkflowEventDeliveriesInputSchema, en as WorkflowEventDeliveryRowSchema, qt as WorkflowParentClosePolicySchema, Qt as WorkflowRunEventRowSchema, Yt as WorkflowRunHandleSchema, tn as WorkflowRunRefSchema, J as WorkflowRunRowSchema, q as WorkflowRunStatusSchema, Zt as WorkflowRunStepRowSchema, Y as WorkflowRunTableRefSchema, Xt as WorkflowRunsInputSchema, an as WorkflowSignalInputSchema, Jt as WorkflowStartDeferralSchema, on as WorkflowUpdateInputSchema, sn as WorkflowUpdateResultSchema, _t as actionToRpc, we as advisoryResourceGuardWarning, ae as anonymousSubject, Ye as applyRowPatch, a as applyScopeDecision, Ln as approvalsDecideDescriptor, In as approvalsPendingQueryDescriptor, te as assertAuthenticated, ze as beginIdempotent, Gt as checkFrameworkCompat, De as checkGuards, me as checkGuardsEffect, ne as composeAuthStrategies, Ut as composeRpcInterceptors, Zn as connectionDisconnectDescriptor, Yn as connectionStartDescriptor, Xn as connectionSubmitTokenDescriptor, Jn as connectionsListQueryDescriptor, nt as declaredReactivityChannelKeys, V as defineAction, wt as defineEvent, B as defineMutation, Bt as definePlugin, Vt as definePluginRoute, Wt as definePluginService, z as defineQuery, dt as defineStream, qe as diffRows, xe as effectiveScopes, Ft as encodeEventKey, yt as errorTag, Dt as eventAttached, Tt as eventEnvelope, Et as eventGap, kt as eventResumePoint, Lt as eventRoute, Ot as eventStreamEvent, At as eventSubscribeInput, jt as eventToRpc, Ie as failIdempotent, ke as findAdvisoryResourceGuards, Pe as finishIdempotent, zt as formatEventRoute, he as getPolicyGuardResolver, ge as getResourceScopeResolver, ut as hasAccessDecision, oe as hasCallbackRoutes, Te as hasEffectiveScope, U as hasEnforcedGuard, Se as hasScope, g as idToPath, Re as idempotencyScope, y as inputLabel, Ct as isEventDescriptor, Je as isIdKeyed, l as isOpenAccess, _e as isPolicyCheck, lt as isPolicyGuard, et as isReactivityChannel, tt as isReactivityChannelKey, Ne as isSystemSubject, st as isWireReachable, t as makeScopeCache, Be as memoryIdempotencyStore, fe as missingAccessDecision, gt as mutationToRpc, xt as normalizeDescriptor, it as normalizeSource, u as openAccessSpec, Rt as parseEventRoute, Ge as pathToId, Ht as pluginInstanceName, ot as publishReactivity, Ve as publishServerError, ht as queryToRpc, ue as rawImpersonationMark, $e as reactivityChannel, Me as requireScope, m as rowPatchOpSchema, h as rowPatchSchema, ee as scopeCacheKey, pe as setEffectiveScopes, je as setPolicyGuardResolver, se as setResourceScopeResolver, rt as sourceKeys, vt as streamToRpc, b as strictInput, le as subjectIdentity, n as subjectScopes, Le as subscribeServerErrors, v as subscriptionEvent, de as systemSubject, o as tenantScopedSubject, bt as toRpc, Qn as tsMs, at as undeclaredChannelKeys, Dn as undoApplyDescriptor, En as undoLogQueryDescriptor, On as undoRedoDescriptor, W as wireErrorUnion, mn as workflowCancelDescriptor, fn as workflowDomainEventsQueryDescriptor, pn as workflowEventDeliveriesQueryDescriptor, hn as workflowResumeDescriptor, dn as workflowRunEventsQueryDescriptor, cn as workflowRunQueryDescriptor, un as workflowRunStepsQueryDescriptor, ln as workflowRunsQueryDescriptor, gn as workflowSignalDescriptor, _n as workflowUpdateDescriptor, Fe as wsMutationIdempotencyScope };
+export { Oe as ADMIN_SCOPE, Ce as APIKEY_ISSUE_ORG_SCOPE, Ee as APIKEY_ISSUE_OTHER_SCOPE, ve as APIKEY_ISSUE_SELF_SCOPE, Fn as APPROVALS_DECIDE_TAG, Pn as APPROVALS_PENDING_TAG, j as ApprovalDecisionErrors, A as ApprovalErrors, E as ApprovalExpired, O as ApprovalForbidden, C as ApprovalNotFound, D as ApprovalNotPending, T as ApprovalRejected, S as ApprovalRequired, w as ApprovalSelfApproval, k as ApprovalUnavailable, Ae as AuthMiddleware, x as BusinessRuleViolation, Rn as CONNECTIONS_LIST_TAG, Vn as CONNECTION_DISCONNECT_TAG, zn as CONNECTION_START_TAG, Bn as CONNECTION_SUBMIT_TOKEN_TAG, qn as ConnectionHandshakeFailed, ce as ConnectionInfo, i as ConnectionInfoMiddleware, Q as ConnectionKind, Kn as ConnectionKindMismatch, Wn as ConnectionNotDeclared, Un as ConnectionState, Hn as ConnectionStatus, Gn as ConnectionSubjectRequired, Nn as ConstraintViolation, r as DEFAULT_SCOPE_CACHE_MAX_ENTRIES, ie as DEFAULT_SCOPE_CACHE_TTL_MS, Ft as EVENT_ROUTE_SEP, Mt as EventKeyInvalid, jt as EventPayloadInvalid, Nt as EventPayloadTooLarge, $n as GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE, be as IMPERSONATION_METADATA_KEY, St as MAX_EVENT_ENVELOPE_BYTES, nr as PROTOCOL_VERSION, M as PendingApproval, N as REACTIVITY_CHANNEL_PREFIX, c as ScopeError, Mn as ServerOnlyColumnWrite, kn as StoreOperationFailed, e as Subject, ye as SubjectIdentity, re as SubjectService, An as TableValidationFailed, jn as TenantRowNotFound, On as TenantScopeViolation, vn as UNDO_APPLY_TAG, _n as UNDO_LOG_TAG, yn as UNDO_REDO_TAG, s as Unauthenticated, Cn as UndoConflict, Sn as UndoForbidden, bn as UndoLogEntry, xn as UndoNotFound, Z as WorkflowControlInputSchema, Qt as WorkflowDomainEventRowSchema, tn as WorkflowDomainEventsInputSchema, nn as WorkflowEventDeliveriesInputSchema, $t as WorkflowEventDeliveryRowSchema, Kt as WorkflowParentClosePolicySchema, Zt as WorkflowRunEventRowSchema, Jt as WorkflowRunHandleSchema, en as WorkflowRunRefSchema, Y as WorkflowRunRowSchema, J as WorkflowRunStatusSchema, Xt as WorkflowRunStepRowSchema, X as WorkflowRunTableRefSchema, Yt as WorkflowRunsInputSchema, rn as WorkflowSignalInputSchema, qt as WorkflowStartDeferralSchema, an as WorkflowUpdateInputSchema, on as WorkflowUpdateResultSchema, _t as actionToRpc, we as advisoryResourceGuardWarning, ae as anonymousSubject, Ye as applyRowPatch, a as applyScopeDecision, Ln as approvalsDecideDescriptor, In as approvalsPendingQueryDescriptor, te as assertAuthenticated, ze as beginIdempotent, Wt as checkFrameworkCompat, De as checkGuards, me as checkGuardsEffect, ne as composeAuthStrategies, Ht as composeRpcInterceptors, Zn as connectionDisconnectDescriptor, Yn as connectionStartDescriptor, Xn as connectionSubmitTokenDescriptor, Jn as connectionsListQueryDescriptor, nt as declaredReactivityChannelKeys, V as defineAction, wt as defineEvent, B as defineMutation, zt as definePlugin, Bt as definePluginRoute, Ut as definePluginService, z as defineQuery, dt as defineStream, tr as defineWebSocket, qe as diffRows, xe as effectiveScopes, Pt as encodeEventKey, yt as errorTag, Dt as eventAttached, Tt as eventEnvelope, Et as eventGap, kt as eventResumePoint, It as eventRoute, Ot as eventStreamEvent, G as eventSubscribeInput, At as eventToRpc, Ie as failIdempotent, ke as findAdvisoryResourceGuards, Pe as finishIdempotent, Rt as formatEventRoute, he as getPolicyGuardResolver, ge as getResourceScopeResolver, ut as hasAccessDecision, oe as hasCallbackRoutes, Te as hasEffectiveScope, U as hasEnforcedGuard, Se as hasScope, g as idToPath, Re as idempotencyScope, y as inputLabel, Ct as isEventDescriptor, Je as isIdKeyed, l as isOpenAccess, _e as isPolicyCheck, lt as isPolicyGuard, et as isReactivityChannel, tt as isReactivityChannelKey, Ne as isSystemSubject, st as isWireReachable, t as makeScopeCache, Be as memoryIdempotencyStore, fe as missingAccessDecision, gt as mutationToRpc, xt as normalizeDescriptor, it as normalizeSource, u as openAccessSpec, Lt as parseEventRoute, Ge as pathToId, Vt as pluginInstanceName, ot as publishReactivity, Ve as publishServerError, ht as queryToRpc, ue as rawImpersonationMark, $e as reactivityChannel, Me as requireScope, m as rowPatchOpSchema, h as rowPatchSchema, ee as scopeCacheKey, pe as setEffectiveScopes, je as setPolicyGuardResolver, se as setResourceScopeResolver, rt as sourceKeys, vt as streamToRpc, b as strictInput, le as subjectIdentity, n as subjectScopes, Le as subscribeServerErrors, v as subscriptionEvent, de as systemSubject, o as tenantScopedSubject, bt as toRpc, Qn as tsMs, at as undeclaredChannelKeys, En as undoApplyDescriptor, Tn as undoLogQueryDescriptor, Dn as undoRedoDescriptor, W as wireErrorUnion, pn as workflowCancelDescriptor, dn as workflowDomainEventsQueryDescriptor, fn as workflowEventDeliveriesQueryDescriptor, mn as workflowResumeDescriptor, un as workflowRunEventsQueryDescriptor, sn as workflowRunQueryDescriptor, ln as workflowRunStepsQueryDescriptor, cn as workflowRunsQueryDescriptor, hn as workflowSignalDescriptor, gn as workflowUpdateDescriptor, Fe as wsMutationIdempotencyScope };

package/dist/rest.d.ts

@@ -74,6 +74,12 @@ declare interface AnyApprovalPolicy {
 /** A guard is either a scope check or a relationship check. */
 declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
 
+export declare const bytes: (stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>), options?: {
+    readonly contentType?: string;
+    readonly contentLength?: number;
+    readonly contentDisposition?: string;
+}) => RestByteResponse;
+
 /**
  * Project every descriptor carrying a `publicApi` annotation into a REST
  * route, in stable (path) order. The boot layer feeds these straight into
@@ -248,6 +254,8 @@ declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<str
     readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
+export declare const isRestByteResponse: (v: unknown) => v is RestByteResponse;
+
 export declare const isRestStreamResponse: (v: unknown) => v is RestStreamResponse;
 
 /** Extract `:name` path params by aligning the route PATTERN with the request
@@ -349,12 +357,19 @@ declare interface OpenAccessSpec {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). */
-    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
+     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
+     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
+     *  for its other job: one dispatcher per shared path + a precise 405). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
     /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
      *  any sub-path (`/_voltro/storage/abc123`). */
     readonly path: string;
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /** Per-route body cap override (bytes) — wins over the listener's shared
+     *  `maxBodyBytes`. NOTE: routes SHARING a path share one body read, so the
+     *  widest override on the path's group applies to the whole group. */
+    readonly maxBodyBytes?: number;
     /**
      * Opt this route's path OUT of the listener's cross-site origin check.
      *
@@ -393,6 +408,21 @@ declare interface PluginHttpRoute {
     readonly originGuard?: 'exempt';
 }
 
+/**
+ * A binary streaming body — the download/export shape. The serve layer pipes
+ * the Web ReadableStream to the socket without buffering, so a response
+ * larger than the heap is fine; the LAZY thunk form defers opening the
+ * source (a provider connection, a file handle) until the response actually
+ * streams.
+ */
+declare interface PluginHttpRouteByteStream {
+    readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+    /** Declared up front when known — lets the client render progress. */
+    readonly contentLength?: number;
+    /** e.g. `attachment; filename="export.zip"`. */
+    readonly contentDisposition?: string;
+}
+
 declare interface PluginHttpRouteRequest {
     readonly method: string;
     /** Path WITHOUT query string. */
@@ -504,6 +534,12 @@ declare interface PluginHttpRouteResult {
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
+    /** Stream a BINARY response (a download, an export) instead of sending
+     *  `body` — see {@link PluginHttpRouteByteStream}. Never buffered by the
+     *  serve layer; never compressed (flush timing + Content-Length are the
+     *  contract). Takes precedence over `body`; do not set both `stream` and
+     *  `byteStream`. */
+    readonly byteStream?: PluginHttpRouteByteStream;
 }
 
 /**
@@ -739,6 +775,19 @@ export declare const requireAnyScope: (scopes: ReadonlyArray<string>) => RestGua
  */
 export declare const requireScope: (scope: string) => RestGuard;
 
+/** A BINARY streaming response (download/export). The serve layer pipes the
+ *  ReadableStream without buffering — a body larger than the heap is fine.
+ *  The LAZY thunk form defers opening the source until the response streams. */
+export declare interface RestByteResponse {
+    readonly __voltroRestBytes: true;
+    readonly byteStream: {
+        readonly stream: ReadableStream<Uint8Array> | (() => ReadableStream<Uint8Array>);
+        readonly contentLength?: number;
+        readonly contentDisposition?: string;
+    };
+    readonly contentType?: string;
+}
+
 export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -751,7 +800,7 @@ export declare interface RestGuardRejection {
     readonly message: string;
 }
 
-export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
 /**
  * Per-call context handed to a REST route handler. Resolved by the serve
@@ -791,6 +840,26 @@ export declare interface RestRouteDescriptor<I, O> {
     /** ISO date. Sets a `Sunset:` header; past the date the route returns
      *  `410 Gone` with a replacement pointer. */
     readonly sunset?: string;
+    /**
+     * Opt-in API version. `version: 'v2'` + `path: '/customers'` mounts the route
+     * at `/v2/customers` — the same `/vN/` convention the `publicApi:` projection
+     * has always used (`derivePublicPath`) and the built-in `/v1/api-keys`
+     * surface follows.
+     *
+     * OPT-IN on purpose: a route without `version` keeps its literal `path`
+     * untouched. An automatic prefix would silently move every deployed route —
+     * a second breaking change hiding inside a naming feature.
+     *
+     * Two versions of one resource are TWO descriptors: the old version is
+     * ordinary code — visible, testable, deletable — carrying `deprecated` (the
+     * replacement pointer) and `sunset` (the date it starts answering `410`,
+     * whose body then also names this `version`). There is no transformation
+     * DSL, and the rpc SOCKET is deliberately outside this: the generated client
+     * is versioned with the server it was generated from (a stale browser tab
+     * runs the previous client until reload — that skew window exists and is
+     * documented, it is not solved by URL versioning).
+     */
+    readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
@@ -801,6 +870,13 @@ export declare interface RestRouteDescriptor<I, O> {
      * no spec, because clients are generated from it.
      */
     readonly streaming?: boolean;
+    /** Per-route body cap override (bytes) — see PluginHttpRoute.maxBodyBytes. */
+    readonly maxBodyBytes?: number;
+    /** GET only: derive a weak ETag from the encoded response and answer a
+     *  matching `If-None-Match` with 304. The tag is content-derived (an md5
+     *  of the JSON), so it is correct across content-encodings — the
+     *  transport's compression varies the bytes, not the representation. */
+    readonly etag?: boolean;
 }
 
 export declare interface RestRouteExample {

package/dist/rest.js

@@ -33,26 +33,45 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		status: 403,
 		message: `Missing required scope: one of ${e.join(", ")}`
 	};
-}, m = (e) => e, h = (e, t = {}) => ({
+}, m = (e) => {
+	if (e.version === void 0) return e;
+	if (!/^v\d+$/.test(e.version)) throw Error(`defineRestRoute(${e.method} ${e.path}): version "${e.version}" must be 'v' followed by digits — 'v1', 'v2', …`);
+	if ((/* @__PURE__ */ RegExp("^/v\\d+(/|$)")).test(e.path)) throw Error(`defineRestRoute(${e.method} ${e.path}): the path already starts with a version segment AND declares version: '${e.version}'. Pick one spelling — either bake the version into the path, or declare version: and keep the path bare ('/customers'). Both would mount '/${e.version}${e.path}', which is never what the author meant.`);
+	return {
+		...e,
+		path: `/${e.version}${e.path}`
+	};
+}, h = (e, t = {}) => ({
 	__voltroRestStream: !0,
 	stream: {
 		subscribe: e,
 		...t.keepAliveMs === void 0 ? {} : { keepAliveMs: t.keepAliveMs }
 	}
-}), g = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, _ = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, v = (e, t, n) => ({
+}), g = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, _ = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, v = (e, t = {}) => ({
+	__voltroRestBytes: !0,
+	byteStream: {
+		stream: e,
+		...t.contentLength === void 0 ? {} : { contentLength: t.contentLength },
+		...t.contentDisposition === void 0 ? {} : { contentDisposition: t.contentDisposition }
+	},
+	...t.contentType === void 0 ? {} : { contentType: t.contentType }
+}), y = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, b = async (e) => {
+	let t = await globalThis.crypto.subtle.digest("SHA-1", new TextEncoder().encode(e));
+	return [...new Uint8Array(t)].map((e) => e.toString(16).padStart(2, "0")).join("");
+}, x = (e, t, n) => ({
 	status: e,
 	contentType: "application/json; charset=utf-8",
 	body: JSON.stringify(t),
 	...n ? { headers: n } : {}
-}), y = (e) => {
+}), S = (e) => {
 	if (e.length === 0) return;
 	let t = new TextDecoder().decode(e);
 	if (t.trim() !== "") return JSON.parse(t);
-}, b = (e) => {
+}, C = (e) => {
 	let t = {};
 	for (let [n, r] of new URLSearchParams(e)) t[n] = r;
 	return t;
-}, x = (e, t) => {
+}, w = (e, t) => {
 	let n = e.split("/").filter((e) => e.length > 0), r = t.split("/").filter((e) => e.length > 0), i = {};
 	for (let e = 0; e < n.length; e++) {
 		let t = n[e];
@@ -66,22 +85,24 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 		}
 	}
 	return i;
-}, S = (e, t) => ({
-	query: b(e.query),
+}, T = (e, t) => ({
+	query: C(e.query),
 	params: t,
-	body: y(e.rawBody)
-}), C = /* @__PURE__ */ new Set([
+	body: S(e.rawBody)
+}), E = /* @__PURE__ */ new Set([
 	"POST",
 	"PUT",
 	"PATCH",
 	"DELETE"
-]), w = (c, l) => {
+]), D = (c, l) => {
 	let u = c.input ? s.decodeUnknown(c.input) : void 0, d = s.encode(c.output), f = {};
 	return c.deprecated !== void 0 && (f.Deprecation = "true"), c.sunset !== void 0 && (f.Sunset = c.sunset), {
 		method: "*",
 		path: c.path,
+		...c.maxBodyBytes === void 0 ? {} : { maxBodyBytes: c.maxBodyBytes },
 		handle: async (s) => {
-			if (s.method.toUpperCase() !== c.method) return v(405, {
+			let p = s.method.toUpperCase();
+			if (!(p === c.method || p === "HEAD" && c.method === "GET")) return x(405, {
 				error: "Method Not Allowed",
 				allow: c.method
 			}, {
@@ -90,74 +111,98 @@ var c = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), l = (e, t) => t.
 			});
 			if (c.sunset !== void 0) {
 				let e = Date.parse(c.sunset);
-				if (!Number.isNaN(e) && Date.now() >= e) return v(410, {
+				if (!Number.isNaN(e) && Date.now() >= e) return x(410, {
 					error: "Gone",
+					...c.version === void 0 ? {} : { version: c.version },
 					...c.deprecated === void 0 ? {} : { replacement: c.deprecated }
 				}, f);
 			}
-			let p;
+			let m;
 			if (u) {
-				let e = S(s, x(c.path, s.path)), t = await o.runPromise(u(e).pipe(o.map((e) => ({
+				let e = T(s, w(c.path, s.path)), t = await o.runPromise(u(e).pipe(o.map((e) => ({
 					ok: !0,
 					value: e
 				})), o.catchAll((e) => o.succeed({
 					ok: !1,
 					cause: e
 				}))));
-				if (!t.ok) return v(400, {
+				if (!t.ok) return x(400, {
 					error: "Invalid request",
 					detail: String(t.cause)
 				}, f);
-				p = t.value;
+				m = t.value;
 			}
-			let m = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), h = {
-				subject: m,
+			let h = l.resolveSubject ? await l.resolveSubject(s.headers) : e(s.headers["x-tenant"] ?? null), g = {
+				subject: h,
 				headers: s.headers,
 				store: l.store
 			};
 			if (c.guards) for (let e of c.guards) {
-				let t = await e(h);
-				if (t) return v(t.status, { error: t.message }, f);
+				let t = await e(g);
+				if (t) return x(t.status, { error: t.message }, f);
 			}
-			let g = l.idempotency, y = g && C.has(c.method) ? s.headers[g.header.toLowerCase()] : void 0, b = g && y ? r(m.tenantId, c.method, c.path) : "";
-			if (g && y) {
-				let e = await i(g.store, b, y, g.ttlMs, Date.now());
-				if (e.kind === "replay") return v(e.response.status, e.response.body, {
+			let v = l.idempotency, S = v && E.has(c.method) ? s.headers[v.header.toLowerCase()] : void 0, C = v && S ? r(h.tenantId, c.method, c.path) : "";
+			if (v && S) {
+				let e = await i(v.store, C, S, v.ttlMs, Date.now());
+				if (e.kind === "replay") return x(e.response.status, e.response.body, {
 					...f,
 					"Idempotency-Replayed": "true"
 				});
-				if (e.kind === "conflict") return v(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
+				if (e.kind === "conflict") return x(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
 			}
 			try {
-				let e = await c.handler(p, h);
-				if (_(e)) return {
+				let e = await c.handler(m, g);
+				if (_(e) || y(e)) return v && S && await n(v.store, C, S), y(e) ? {
+					status: 200,
+					headers: f,
+					byteStream: e.byteStream,
+					...e.contentType === void 0 ? {} : { contentType: e.contentType }
+				} : {
 					status: 200,
 					headers: f,
 					stream: e.stream
 				};
-				let n = await o.runPromise(d(e));
-				return g && y && await t(g.store, b, y, {
+				let r = await o.runPromise(d(e));
+				if (v && S && await t(v.store, C, S, {
 					status: 200,
-					body: n
-				}, Date.now()), v(200, n, f);
+					body: r
+				}, Date.now()), c.etag === !0 && c.method === "GET") {
+					let e = `W/"${await b(JSON.stringify(r))}"`, t = s.headers["if-none-match"];
+					return t !== void 0 && t.split(",").some((t) => t.trim() === e) ? {
+						status: 304,
+						headers: {
+							...f,
+							ETag: e
+						}
+					} : x(200, r, {
+						...f,
+						ETag: e
+					});
+				}
+				return x(200, r, f);
 			} catch (e) {
-				if (g && y && await n(g.store, b, y), typeof e == "object" && e && typeof e.status == "number") {
+				if (v && S && await n(v.store, C, S), typeof e == "object" && e && typeof e.status == "number") {
 					let t = e;
-					return v(t.status, { error: t.message ?? "Error" }, f);
+					return x(t.status, { error: t.message ?? "Error" }, f);
 				}
 				return a({
 					error: e,
 					source: "rest",
 					name: `${c.method} ${c.path}`,
 					fields: { status: 500 }
-				}), v(500, { error: "Internal Server Error" }, f);
+				}), x(500, { error: "Internal Server Error" }, f);
 			}
 		}
 	};
-}, T = (e, t = {}) => e.map((e) => w(e, t)), E = async (e, t) => {
+}, O = (e, t = {}) => {
+	if (t.idempotency !== void 0) {
+		for (let t of e) if (t.streaming === !0 && E.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...E].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
+	}
+	return e.map((e) => D(e, t));
+}, k = async (e, t) => {
 	let n = await e[0].handle(t);
 	for (let r = 1; r < e.length && n.status === 405; r++) n = await e[r].handle(t);
 	return n;
 };
 //#endregion
-export { d as collectPublicApiRoutes, m as defineRestRoute, c as derivePublicMethod, l as derivePublicPath, E as dispatchSharedPath, _ as isRestStreamResponse, x as matchPathParams, u as publicApiRoute, p as requireAnyScope, f as requireScope, T as restRoutesToHttpRoutes, h as sse, g as sseFrame };
+export { v as bytes, d as collectPublicApiRoutes, m as defineRestRoute, c as derivePublicMethod, l as derivePublicPath, k as dispatchSharedPath, y as isRestByteResponse, _ as isRestStreamResponse, w as matchPathParams, u as publicApiRoute, p as requireAnyScope, f as requireScope, O as restRoutesToHttpRoutes, h as sse, g as sseFrame };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.51.0",
-    "@voltro/logger": "0.51.0",
+    "@voltro/database": "0.52.0",
+    "@voltro/logger": "0.52.0",
     "jose": "^6.2.8"
   },
   "peerDependencies": {