@voltro/protocol 0.50.1 → 0.52.0

package/CHANGELOG.md

@@ -39,6 +39,237 @@ _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
+
+- **@voltro/data-transfer, @voltro/cli** — The asset counts reported references as if they were blobs. `_voltro_storage_refs` holds one row per reference and several rows legitimately name one key, so a capture of 57 rows over 16 keys wrote `count: 57` into the stamp beside an `assets/` directory holding 16 files, and the restore reported "57 blob(s) restored" while 16 objects appeared. Nothing was lost; what was lost is the ability to check. Anyone answering "are all the blobs there?" after a restore compared the stamp's number against one they counted and found a 3.5x gap that was not one.
+
+  A key named by several references is now fetched once rather than downloaded, hashed and discarded once per row, and the three numbers are stated separately: `references` (rows enumerated), `count` (distinct keys), `objects` (distinct sha256 bodies), with `totalBytes` and `objectBytes` beside them. The stamp's existing fields keep their names and now mean what a reader always took them for; the new ones are optional, so a stamp written before them still parses.
+
+  **Breaking on one export.** `restoreAssetsFromCas` returns `{ count, objects }` instead of a bare `number` — one number could not answer both questions, which is the defect. `count` is what the old value was, so the migration that changes nothing is `.count`.
+
+  **`voltro update` carries you across this** — codemod `0.51.0/03_restore-assets-returns-counts`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.51.0).
+- **@voltro/i18n** — `<I18nProvider>` takes `timeZone` as its own prop, and `intlConfig` no longer accepts one.
+
+  `intlConfig` exists to forward props to react-intl UNMODIFIED, and for every other member of `IntlConfig` that is the right shape. `timeZone` is the one member this package's own formatters read — and they did not read it: `useFormatDate` built `Intl.DateTimeFormat` itself and took only the locale from the provider. So a zone passed through `intlConfig` configured `<T>`'s ICU dates and NOT the `useFormatDate()` beside them. Measured under one provider, one instant (`2026-08-24T23:30:00Z`), `locale: 'de'`, `intlConfig: { timeZone: 'Europe/Berlin' }`, process zone UTC: react-intl rendered `25.08.26, 01:30` and the hook rendered `24.08.26, 23:30`. A different hour, and a different day.
+
+  The zone has to be a prop this package can see. It is validated once at the provider (an unusable zone — a stale cookie, a typo, a runtime with a trimmed ICU — is dropped, because `Intl` THROWS on an unknown zone and `useFormatDate` catches, which would degrade every timestamp in the app to a raw `Date` string). It is what the new `useTimeZone()` reports. And it is what the framework fills per request.
+
+  **Migration:** `intlConfig={{ timeZone: 'Europe/Berlin' }}` → `timeZone="Europe/Berlin"`. The codemod does it, including the case where the zone was the bag's only member. An `intlConfig` naming a variable is reported by file and line rather than guessed at — the property would otherwise stop being read with nothing red anywhere.
+- **@voltro/cli** — A native restore whose bookkeeping store would not open ran anyway, with no in-progress marker and no word about it. `nativeBookkeeping` was `try { … } catch { return undefined }`, and that `undefined` guarded every branch below — including the refusal for a marker that could not be written. So the failure removed the precaution AND the sentence that would have reported it missing, and `markerState` was never computed, defaulting to "held".
+
+  What it produced was worse than silence: a failed restore printed "This database is now in an unknown state and the next boot will REFUSE, by design" over a database with zero marker rows. The next boot did not refuse, and `voltro data clear-replace-marker` had nothing to clear. The trigger is not exotic — wrong credentials, an unreachable database, a missing env var, no `app.config.ts` from here — and a restore is the operation you run against a target that is already unwell, so the guard fell away exactly when it was needed.
+
+  The reason now travels instead of being caught and dropped. A restore that cannot write the marker REFUSES and names which of the two reasons it was (the store would not open, or the table is not there); those were two separate refusals and are now one, because they are one decision for the operator. `--no-marker` is the deliberate way past it and warns every time. And the `recorded:` line no longer reports a local failure as a property of the target — it says where the failure was.
+
+  **This changes an exit code.** A restore that could not write the marker used to exit 0; it now exits 1. Two invocations are affected — the bookkeeping store will not open, or there is no `app.config.ts` from the working directory — and the second surprises people, because `restore` reads its target from the environment and so looks like it needs no project. It does not, for the dump; it needs one for the marker. `--no-marker` is the deliberate way through and warns every time. The note ships under `reach: 'beyond-source'` because the affected invocations live in cron entries, CI jobs and runbooks rather than in TypeScript.
+
+  **`voltro update` carries you across this** — codemod `0.51.0/02_restore-refuses-without-marker`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.51.0).
+
+### Added
+
+- **@voltro/i18n, @voltro/cli, @voltro/voltro** — `timeZone` in the web `app.config.ts` — the zone every date/time formatter renders in, resolved per request and published so the client agrees.
+
+  A formatter is deterministic given the value, the locale, the zone and the clock. The locale already came from the provider and was already agreed across the hydration boundary — the server publishes it as `<html lang>` and the client reads that attribute rather than `navigator.languages`, precisely because the browser's own answer can differ from what the server saw. The zone had no such source. `Intl` fell back to the zone of whichever runtime was formatting: the pod on the server (UTC on a container with no `TZ`), the viewer's machine in the browser. Every server-rendered timestamp was therefore a hydration mismatch waiting for a wide enough offset, and across midnight it was a different calendar day.
+
+  timeZone: 'Europe/Berlin' // one zone for every viewer timeZone: 'viewer' // per request, from the `voltro:tz` cookie defaultTimeZone: 'UTC' // before the viewer's zone is known
+
+  Whatever it resolves to is stamped on the document as `<html data-voltro-tz>`, and the generated client entry reads that attribute. Both sides then format against one value — which is the property that removes the mismatch, whether or not the value is the viewer's true zone: being wrong together is repairable after mount, being different is not.
+
+  Under `'viewer'` the framework injects a script that seeds `voltro:tz` from the browser when the cookie is absent, so the server renders in the viewer's zone from the second request with no login. It never overwrites an existing value — the APP is the authoritative writer, at login, from the zone it holds for the signed-in user (`TIMEZONE_COOKIE` and `isSupportedTimeZone` are exported for that). Unset, nothing changes: each runtime keeps using its own zone, and `useTimeZone()` returns `undefined` to say so.
+
+  This is the RENDER zone. The server-side compute zone — what `startOfDay` resolves against inside a handler — is still `@voltro/datetime/context`'s seam, unwired.
+
+  **`apiSurface: compatible`** covers the two golden lines that moved, and they are the same change twice: `makeSsgWrap`'s returned wrapper, and the `wraps` record on the SSG shell input, each gained an OPTIONAL second parameter (the per-request zone + render instant; the wrapper is built once per locale, so they cannot live in the factory). A function with an optional extra parameter is assignable wherever the one-parameter type was expected, so no call site that compiled stops compiling — and both are the framework's SSG bridge, documented as never imported by app code. Everything else this release adds to these packages is a pure addition; the one genuine break in `@voltro/i18n` is the `timeZone` prop, which has its own entry and its own codemod.
+
+### Changed
+
+- **@voltro/cli** — A `BREAKING` entry's changelog footer now tells a reader who pins versions by hand how to print the codemod's note without upgrading anything:
+
+  voltro update --codemods-only --from <your current version> --dry-run
+
+  The footer used to stop at the codemod's id, which is enough for anyone who runs `voltro update` and nothing at all for anyone who does not. A deployment said so plainly: they pin every `@voltro/*` version from their own container scripts, have never run the command, and `CHANGELOG.md` out of the tarball is the only channel anything reaches them through. So a note deliberately filed under an unreached version — our one mechanism for correcting guidance that can no longer be corrected in place — reached that population not at all, and the id told them a fix existed without telling them what it was.
+
+  No new surface: every flag in that invocation is already parsed, which is what lets `check-message-apis.mjs` verify the line rather than trust it.
+- **@voltro/cli** — Two fingerprint labels now say what they compare.
+
+  The restore's skew warning said the backup's schema "differs from what this code declares". It does not: the value it compares against is the TARGET database's live schema, read by introspection at restore time. Bringing a target to the backup's shape makes the warning disappear while the declared fingerprint is a third value entirely, which is how the mislabel was caught. The comparison is the useful one and is unchanged; the sentence sent readers looking for a code change where a database differed.
+
+  `voltro db plan` prints `fingerprint: live … · declared …` instead of `from … → to …`, plus a line saying the two are not meant to match. A hash of a live database never equals the hash of the declaration it came from — introspection cannot recover generated expressions, `maxLength` or sensitivity markers — which is why `db drift` keeps a separate live baseline. Printed as `from → to`, `0 operations` under two differing hashes read as a contradiction.
+
+### Fixed
+
+- **@voltro/cli** — `voltro check` reported a reactivity CHANNEL as a missing table, at `error` severity — so it set the exit code:
+
+  ✗ error reference/dangling-source query(presence.list) reads table 'channel:presence' which does not exist fix: declare a 'channel:presence.entity.ts' table or fix the query's source
+
+  A `source:` entry is a table name OR a channel's routing key (`channel:<name>`), and every rule resolved entries against the table set. The advice cannot be followed — a channel exists precisely because no table is meant — and because it is an error rather than a warning, `voltro check` could not be a CI gate for any app that uses a channel. That includes an app whose only channel comes from `@voltro/plugin-presence`, whose own `presence.list` declares one: a first-party feature meeting a rule that did not know about it, inside a first-party plugin.
+
+  Channels are filtered in the ONE helper every table rule reads, rather than at each rule, because a per-rule filter is how the next rule joins without one. The same cause was live one rule over: `observed/declared-but-unobserved` reported "declares source 'channel:presence' but never read it while running" for every exercised procedure that declares a channel. Both are covered, each with a negative control — a filter that dropped the whole source list would have silenced the rules instead of narrowing them.
+- **@voltro/data-transfer** — A native dump no longer carries `_voltro_data_transfers`, for the same reason it stopped carrying the in-progress marker one release ago. The restore opens its own run row there BEFORE the tool runs; the dump then dropped the table mid-flight, and the update recording the outcome wrote into a table that no longer held the row. Measured downstream: after a deliberately failed native restore, `voltro data transfers` showed no restore at all — only the `backup` row the dump had carried over from the SOURCE database. The command that answers "did the restore finish" could not see the run asking the question.
+
+  Exactly two tables are excluded and the line is deliberate: a native restore into the same deployment should bring the migration ledger, the stored plans, the CDC offsets and the schedule claims, because they describe the data being restored. These two describe the RESTORE, and a record of an operation must not be overwritten by the operation it records. Covered per dialect against real servers and real vendor tools, including a non-vacuity check that a table which SHOULD travel still does.
+- **@voltro/i18n, @voltro/cli** — `useRelativeTime` used `Date.now()` as its base, which under SSR is two different numbers. The server rendered at T and wrote "3 minutes ago" into the HTML; the browser hydrated at T+Δ and rendered "4 minutes ago" whenever a unit boundary fell in the gap. The gap is network latency, so it reproduced on a slow connection and never on the developer's machine, and it had nothing to do with timezones — a correctly zoned app hit it just the same.
+
+  The server states its render instant (`<html data-voltro-now>`, `renderedAt` on the provider), the first client render uses that same number, and the clock goes live once hydration commits. Server markup and hydration markup are therefore identical BY CONSTRUCTION — the property `await.tsx` and `deferred.ts` already hold, rather than `suppressHydrationWarning`, which would hide a real mismatch along with this one. An explicit `{ now }` still wins.
+
+  The mount state lives in the provider, not in the hook: a table of ten thousand rows would otherwise pay a state hook and a passive effect each to learn one fact that is true for the whole document. An app that never renders on the server publishes no stamp and takes no second render pass.
+- **@voltro/cli** — `closeNativeRun` writes the transfer row BACK when the restore's own artefact dropped the table it lives in, instead of issuing an `UPDATE` that matches nothing and returning happily. Excluding `_voltro_data_transfers` from our own dumps shortens that window; it does nothing for a dump taken before that change, for a hand-made one, or for mssql and sqlite, whose restores have no per-table exclusion at all. The write-back covers every dialect and every artefact, which is why it is the rule and the exclusion is the optimisation.
+
+  The row is read back rather than trusted — an update that matched nothing is indistinguishable from one that matched — and a read that itself fails writes nothing, because a duplicate row invented on a guess is its own defect in a history somebody reads under pressure.
+- **@voltro/cli** — A prerendered page shipped the shell's baked `lang="en"` whatever locale it was rendered in.
+
+  `voltro dev` and `voltro start` both set `<html lang>` per request; the prerender never did. So a `/de/...` artefact — rendered with the German catalog, handed `locale: 'de'` in its `meta` — served `<html lang="en">`. That attribute is what a screen reader pronounces in, what Chrome offers to translate FROM, and what hyphenation uses, so the failure was silent to whoever shipped it and loud only to the people it excluded. The same shape as the 0.30.0 cookie-name drift, one document path over.
+
+  It surfaced while giving the zone somewhere to travel: `<html lang>` was set by four hand-written copies of one `.replace(/<html…/)` and by nothing in the prerender, and adding a second attribute to that arrangement is how the next one reaches three paths out of five. There is one `applyDocumentAttrs` now, and the prerender is one of its callers — which fixes the locale as a side effect of having somewhere to put the zone.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — `voltro data backup --assets` / `restore --assets` are now driven against a REAL S3 API (MinIO in the test stack), over the network, with a real backup and a real restore into a second bucket and the bytes compared.
+
+  The asset half rests on one field: a provider must map "there is no object at that key" to `status === 404`, and nothing looser — a 403 from a rotated credential is also non-transient, and calling that "the object is gone" turns a recoverable outage into a backup that quietly contains nothing. That mapping was measured against memory, filesystem and database live, and against the s3/azure SDK error SHAPES constructed. A constructed shape is a claim about an SDK, not about a round trip: nothing in it exercises signing, path-style addressing, or what the SDK actually raises when a server answers `NoSuchKey`. Two deployments listed exactly this as the gap they could not close either.
+
+  Both directions are covered against the real server: a dangling reference is stepped over and reported, and a bad credential fails the capture rather than being read as a missing object.
+
+  The native dialect lane also stops being silent about mssql. It was absent from the array entirely — an absent lane and a covered one look identical from the outside — and it is now listed with a written reason for why it does not register here (`sqlpackage` is a separate Microsoft download on a .NET runtime, absent from `mcr.microsoft.com/mssql-tools`). It is registered rather than skipped-forever, because a skip present on every healthy run teaches readers to ignore skip lines; and an assertion fails if any lane drops out WITHOUT a written reason, or if a reason names a lane that is in fact running.
+- **@voltro/cli, @voltro/plugin-storage** — Coverage for the data commands, at the level the defects actually live.
+
+  `dataDirectFlags.e2e.test.ts` drives every DIRECT-target flag of `voltro data export` / `import` through the real binary against a real sqlite database, and carries the same `DATA_FLAGS`-driven self-check the native suite has: a new direct flag has to be driven there or the file goes red. The api-only flags are listed explicitly with the reason they are not here, and that list is asserted against `DATA_FLAGS` so it cannot become a place to hide an untested flag.
+
+  `missingObjectIs404.test.ts` pins the contract the dangling-reference skip rests on: every provider maps "no object at that key" to `status === 404`, and nothing looser. Five providers, three of them live, s3 and azure through their SDK's real error shapes — which read DIFFERENT fields (`$metadata.httpStatusCode` vs a bare `statusCode`), so a mapping copied from one to the other would turn dangling references back into hard capture failures on that backend alone.
+
+  `codegenFeatureTables.integration.test.ts` measures the count a report was about: `voltro codegen` must carry the tables a `*.cron.tsx` contributes, which the entity walk cannot see. The structural guards beside it were TRUE while that count was wrong. `frameworkSourceTypo.integration.test.ts` measures what catches a misspelled `_voltro_*` source given that the type deliberately does not — `voltro check` reports it as a dangling source and exits 1, with a negative control so the check is not merely flagging every framework name.
+
+---
+
 ## [0.50.1] — 2026-08-24
 
 ### Added

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.50.1",
+  "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.50.1",
-    "@voltro/logger": "0.50.1",
+    "@voltro/database": "0.52.0",
+    "@voltro/logger": "0.52.0",
     "jose": "^6.2.8"
   },
   "peerDependencies": {