@voltro/protocol 0.79.0 → 0.80.0

package/CHANGELOG.md

@@ -39,6 +39,140 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.80.0] — 2026-09-24
+
+### ⚠ BREAKING
+
+- **The inspect stream's replica selection is decided before the response** — `@voltro/runtime`, `@voltro/voltro`
+
+  `InspectStream.select` returns `Effect<InspectStreamSelection | undefined>` instead of a `Stream`, where `InspectStreamSelection` is either `{ kind: 'stream', stream }` or `{ kind: 'refused', status, body }`. A stream response is committed as `200` from its first byte, so a refusal can only be expressed before it starts. The option is wired by `voltro dev`, `voltro serve` and `voltro start`; code that passes its own `inspectStream` to `startRpcServer` wraps its stream in `Effect.succeed({ kind: 'stream', stream })`. `voltro update` lists every line that sets `inspectStream`.
+- **`JiraService.listBoards` finds boards by project, name and type** — `@voltro/plugin-atlassian`
+
+  Every board method of `JiraService` took a board id, so a board picker had nothing to list and people looked ids up in Jira by hand. `listBoards({ projectKeyOrId?, name?, type? })` calls `GET /rest/agile/1.0/board`, follows the pages itself, and returns each board as `{ id, name, type, location? }`, where `location` names the project the board is located in. `name` is a contains match on Jira's side. It runs on the caller's own credentials like every other method, so a board the caller may not see is not listed. The break is for code that provides the service itself: a test stub written against the full `JiraServiceShape` needs the new method.
+
+  **`voltro update` carries you across this** — codemod `0.80.0/03_jira-service-lists-boards`. 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.80.0).
+- **A loader has `ctx.query` in the browser, so a clicked-to page keeps its title** — `@voltro/web`, `@voltro/client`, `@voltro/protocol`, `@voltro/cli`
+
+  `ctx.query` was `undefined` when a loader ran in the browser. A page whose loader resolved an entity's name for `meta` therefore showed it in the title on a fresh load and dropped it after a click inside the app: the same URL, two titles. The browser loader now gets `ctx.query` too. It reads through the page's own api client, so it carries the visitor's session. A query resolves to its first snapshot, as on the server, and an in-band error rejects with the typed error on `voltroError`. A newer navigation that replaces the one in flight now aborts the loader's `signal`, as `LoaderContext.signal` always promised, and that closes the read. What changes for existing code is a check on `query`'s presence: `if (query)`, `query ? … : …` and `query?.(…)` now take the resolving branch in the browser too. Branch on `ctx.isServer` where the check meant "this is the server". `voltro update` lists every such line in your pages and layouts.
+
+  Bundle size: the browser read path adds 1.6 KB gz to a web app's first load (194.6 → 196.2 KB gz on the framework's zero-procedure fixture). Because the router now imports the api client, the shared chunk that carries the Effect runtime is emitted as `router-*.js` instead of `index-*.js`; the bytes moved between the two files, they did not grow.
+- **No framework loading spinner; useNavigation() exposes navigation state** — `@voltro/web`
+
+  `FrameworkBoot` mounted a corner `NavigationIndicator` in every web app, in development and production, so a spinner appeared at the bottom right of pages whose design never included one — also in apps that had switched the devtools off. It is no longer mounted, and `NavigationIndicator` is removed from `@voltro/web`. In development the devtools button shows navigation progress as before. To build your own cue, read the new `useNavigation()` hook: `state` is `'loading'` while the router keeps the current page on screen for a target whose page module or loaders are not ready, and `pendingPathname` names that target; a server render is always `'idle'`. For a reconnecting api use `useConnectionStatus(apiName)` from `@voltro/client`. `voltro update` lists every file that still imports `NavigationIndicator`.
+- **DB_MAX_CONNECTIONS is what the whole process holds, not the size of each pool** — `@voltro/cli`, `@voltro/workflow`, `@voltro/database`
+
+  Every framework user of the database opened its own pool: the store, the plugin bind context, the workflow runtime, aggregates, analytics, and the boot steps that migrate or check the schema. Each was sized by `DB_MAX_CONNECTIONS`, so one process could hold several times the number its boot line printed. Measured on postgres at `DB_MAX_CONNECTIONS=3`: the line promised 4 and the database saw 8 connections from `voltro dev` and from `voltro serve`. Two pods budgeted at 5 against a pooler of 15 both failed to acquire in the same second.
+
+  The pools were built by dialect-independent code, and the repair is measured the same way on every dialect: under boot and a burst of concurrent requests, postgres, mariadb, mysql and mssql each hold exactly what the line prints.
+
+  In `voltro dev` and `voltro serve` they now share one pool per database target, so the boot line's number is what the process holds. Short-lived commands such as `voltro data restore` keep their own pool, because they close it to get fresh sessions. A value tuned per pool buys fewer connections in total. Read replicas, a separate migration URL (`DB_DIRECT_URL` / `DB_MIGRATE_URL`), a provisioned tenant's database and pools your own code builds stay separate.
+
+  The workflow runtime needs 3 connections at once (2 with `VOLTRO_WORKFLOW_RUNNER_STORAGE=memory`). Below that the boot now refuses and names the number; it used to wait out the acquire timeout and exit on `Failed to acquire connection`. `sqlPoolCapacity` is exported from `@voltro/database/sql` beside `registerSqlPoolCapacity`, an addition.
+
+  **`voltro update` carries you across this** — codemod `0.80.0/01_db-max-connections-is-the-process-budget`. 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.80.0).
+
+### Added
+
+- **security.clientAddressHeader reads a proxy's single-address header** — `@voltro/runtime`, `@voltro/cli`
+
+  `security.clientAddressHeader` (env `VOLTRO_CLIENT_ADDRESS_HEADER`) names a header a trusted proxy sets to the client's address, such as `cf-connecting-ip` or `x-real-ip`. It is believed only from a peer covered by `security.trustedProxies` and only when it holds one valid IP; otherwise `x-forwarded-for` applies as before. Naming a header without declaring a trusted proxy refuses the boot.
+- **Rate-limit rules can key on the caller's address** — `@voltro/plugin-ratelimit`, `@voltro/protocol`, `@voltro/runtime`, `@voltro/cli`
+
+  A rule can now use `by: 'ip'`, one bucket per client address. Before sign-in every caller is the same anonymous subject, so `'subject'` put them all in one bucket and one client could use up a sign-in or invite endpoint for everyone. The address is the one the listener resolves through `security.trustedProxies`, and plugin interceptors receive it as `RpcInterceptorContext.remoteAddr` on WebSocket, `POST /rpc` and `publicApi` REST calls; REST handlers get it as `RestRouteContext.remoteAddr`. A client cannot set it. Calls that do not arrive over the network share one `unknown` bucket. `KeyBy` gains the `'ip'` member: every value that type-checked before still does; only code that exhaustively switches over `KeyBy` needs the new case.
+
+### Changed
+
+- **Server-side rpc calls carry the visitor's address** — `@voltro/cli`
+
+  A loader's `ctx.query`, a page's `preload`, and the no-JavaScript form post now send `x-forwarded-for` to the api: the chain the request arrived with plus the address that delivered it to the web server. An api whose `security.trustedProxies` covers the web tier therefore rate-limits and audits these calls per visitor instead of counting every visitor against the web server. An api that trusts no proxy ignores the header, so its behaviour is unchanged. A visitor-written `x-forwarded-for` is never forwarded on its own.
+
+### Fixed
+
+- **The boot's database connection line names the dialect in use** — `@voltro/cli`
+
+  A database configured with `DB_HOST` and friends was logged as `db connection: postgres://…` whatever the dialect, so a SQL Server or MySQL connection read as a postgres one. The line now starts with the dialect's name.
+- **The dashboard's live streams share one browser connection** — `@voltro/cli`
+
+  The DevTools dashboard opened one event-stream connection per app. Over HTTP/1.1 a browser holds at most six connections per origin across all tabs, so with six apps — or three in two tabs — the logs and overview pages held every connection the dashboard had, and each later request waited indefinitely: a click on another page changed the URL, kept the old page on screen and left the navigation indicator spinning. Every stream a page holds now travels on one connection: the page posts its targets, each with its own app bearer, to `/api/dashboard/proxy/streams`, and `voltro dev` and `voltro start` fan the apps in behind it, each reconnecting on its own backoff. `/api/dashboard/proxy/stream` is removed; `@voltro/dashboard` of the same release uses the new route.
+- **`meta` keeps the rendered language after hydration without a locale cookie** — `@voltro/web`, `@voltro/cli`
+
+  In the browser, `meta` received the `voltro:locale` cookie's locale and otherwise a fixed `'en'`. A first visit carries no cookie, so the server rendered the title in the language it negotiated (`Accept-Language`, else `defaultLocale`), and after hydration the tab switched to English. `meta` now falls back to the locale the server rendered the document with, which it stamps on `<html lang>`, and the cookie still wins when a language switch has written one. A page `voltro serve` answers with the unrendered shell (a page the prerender did not produce) declared `lang="en"` in every app, and the client took that for the server's choice. The shell now declares the app's `defaultLocale`, or its first declared locale.
+- **The first `voltro dev` on a fresh SQL Server database boots with CDC on** — `@voltro/sql-mssql`
+
+  With `changeStrategy: 'cdc'`, the default, the Change Tracking reader started before auto-migrate created the schema and enabled tracking on tables that did not exist yet. The boot died on `Failed to execute statement`, so every new project on SQL Server failed its first `voltro dev`. The same database booted once with `CDC=0` worked afterwards.
+
+  The reader now enables tracking on the tables that exist and picks up the rest on the poll that first finds them, reading each from its own tracking floor. A table the migration creates during the boot is tracked from then on. `ensureChangeTracking` resolves to the tables it could not enable yet.
+- **Replica observations of ended processes are deleted after a day** — `@voltro/cli`, `@voltro/runtime`, `@voltro/database`
+
+  `_voltro_replica_observations` had no retention. A replica deletes its own rows on a graceful shutdown, but a process that crashed or was killed left them behind, and a replica ID that does not survive a restart — `dev-<pid>` under `voltro dev`, a pod replaced under a new name — never overwrites them. Every such row stayed listed as `departed` in each fleet read indefinitely. The retention sweep now deletes rows not rewritten for 24 hours on both boot paths and every dialect; live replicas rewrite theirs every 30 seconds. `VOLTRO_REPLICA_OBSERVATIONS_TTL_HOURS` changes the window, with a floor of one hour, and the boot line lists the policy with the others.
+- **A live stream for an ended replica is refused instead of reconnecting forever** — `@voltro/cli`, `@voltro/devtools-ui`
+
+  `/_voltro/inspect/stream?replica=<id>` now resolves the named replica and verifies its handshake before it answers, with the same refusals as a read: `404` for an unknown ID or one without a reachable address (no request leaves the process), `504` for a peer that does not accept the connection, `502` for a peer that answers with another process's feed. Previously the API answered `200 text/event-stream` first and found the missing peer inside the body, so a dashboard still naming a process from before a restart received a stream that closed at once, reconnected on backoff indefinitely, and left a `Fiber terminated with an unhandled error` in the target's log on every attempt. The replica selector in the local and Cloud dashboards now also removes a selected replica once the fleet no longer lists it — the process ended and its ID never answers again — names the removed IDs, and returns an emptied selection to All replicas. A replica that is only unavailable (stale, without a reachable address, or expected by the fleet without an answer) stays selected.
+- **A controlled workflow start without an acknowledgement returns its receipt** — `@voltro/runtime`, `@voltro/voltro`, `@voltro/workflow`, `@voltro/cli`, `@voltro/protocol`
+
+  When the engine dispatch of a start with flow controls failed without a definite answer, such as an exhausted database pool or an acknowledgement lost after the engine took the run, `start()` threw `Submission … remains unacknowledged`. The submission stayed durable and recovery retried it, so a caller that reported the failure could see the run happen anyway.
+
+  `start()` now returns `status: 'queued'` with `deferral.mode: 'unacknowledged'`, and `handle.id` is the receipt recovery binds to the resulting run. `start(…, { wait: true })` and `run(…)` follow it. A definite rejection still throws.
+
+  `WorkflowAdmissionOutcome`'s `accept` may now resolve to a `WorkflowQueuedAdmission` as well as an execution ID. Custom admission adapters only produce that outcome; the framework's facade is what calls `accept`, so adapter code keeps compiling. `isUnacknowledgedSubmission` is exported from `@voltro/workflow`.
+
+---
+
+## [0.79.1] — 2026-09-24
+
+### Changed
+
+- **A charset conversion blocked by a soft-drop snapshot names the reclaim** — `@voltro/database`
+
+  A declared `store.charset` refuses to convert a table that a foreign key ties to a table the plan does not convert. When that other table is a soft-drop snapshot (`<name>__dropped_<stamp>`), the fix line offered three remedies that do not fit one: declaring it, converting it by hand, or leaving the charset undeclared. It now names `voltro db gc-snapshots --before <date>` with the date that covers the newest blocking snapshot, says that the date also removes every older snapshot, and names `voltro db restore-snapshot` for data that is still wanted.
+- **The devtools capsule morphs into a status and back** — `@voltro/devtools`
+
+  When `voltro dev` reported a status such as "Compiling…", the closed capsule swapped its chips for the status in one frame and jumped to the new width. The swap is now a morph: the incoming content fades up while the capsule glides from its old width to the new one, and a status that changes mid-glide continues from the width reached. Under `prefers-reduced-motion` the swap stays immediate.
+- **The devtools console animates out the way it came in** — `@voltro/devtools`
+
+  Opening the console slid it in from its dock edge (or scaled a floating window up), but closing removed it in one frame. Closing now plays the entrance backwards: the console slides out towards its edge, or the window scales down and fades, and the capsule returns once it has gone. The console ignores input while it leaves, a page pushed aside by it reflows only after it is gone, and under `prefers-reduced-motion` it still closes at once.
+
+### Fixed
+
+- **Probes are answered while a large app's modules load at boot** — `@voltro/cli`
+
+  The app port answers the health probes from the start of the boot, but the process that answers them is the one booting. Loading the app's modules runs on Node's synchronous loader, so the whole run was one turn of the event loop and a probe waited for all of it: over 800 ms on a generated 1798-module app booting `voltro serve` from the production bundle, and over a second on a loaded machine. Loading now hands the thread back every 25 ms; on the same app, at load 14 on 12 cores, the slowest liveness answer during boot was 89 ms. `voltro dev` loads its modules through the same path.
+- **`voltro update` notes are not silenced by a comment naming the option** — `@voltro/cli`
+
+  A `manual` codemod decides whether your project is affected by searching its files. In code that search counted comments: an api config that set neither anonymous-tenant option and explained why in a comment read as one that had chosen, and the note meant for it was skipped as "none matched your project". Commented-out code did the same. In `.ts`, `.js` and `.json` files (and their variants) comments no longer count; prose files — runbooks, CI definitions, shell scripts — are still read whole. This applies to every codemod a later `voltro update` runs, including the ones of versions you have not crossed yet.
+- **`voltro update` notes search the whole workspace, not only the app** — `@voltro/cli`
+
+  `voltro update` runs from an app directory, and the search behind every manual note read only that app. A compose file at the workspace root still setting `VOLTRO_DEV_HEALTH_PORT`, or a tsconfig in another workspace member with a removed TypeScript 7 option, got "nothing in this repository matched" — though the TypeScript 7 note says it checks every tsconfig in the workspace. The search now covers the workspace the app sits in. The TypeScript 7 note also names each tsconfig line it found, and its hand-check `git grep` line matches `"moduleResolution": "node"` and the lower-case spellings (`amd`, `classic`, `es5`); it required `node10` before.
+- **Correction: a compose baseline from before 0.79.0 needs `voltro baseline sync`** — `@voltro/cli`
+
+  The 0.79.0 note on probes said a compose baseline needs nothing because it regenerates on the next `voltro dev`. It does not: only `voltro baseline sync` rewrites those files, and a baseline synced before 0.79.0 sets `VOLTRO_DEV_HEALTH_PORT` and points its healthchecks at a port nothing listens on any more. `voltro update` now prints a correcting note for every project whose workspace still sets that variable, naming the lines.
+- **`db apply` undo converts tables back and says exactly what still differs** — `@voltro/cli`, `@voltro/database`
+
+  On MySQL, MariaDB, SQLite and Turso a failed `voltro db apply` is undone rather than rolled back. When the run had converted tables to a declared `store.charset`, the undo planned the way back with that same charset, so no conversion could be planned in reverse — and the check behind "the database is as it was" asked the same charset-blind question, so the line printed over tables that stayed converted. The undo now converts each table back to the character set its string columns had before the run, and verifies it by reading every column back. A column the undo redefines also keeps its default: a string default read from MariaDB was quoted a second time. When an undo does not read as it was, the report now lists each remaining difference instead of asking you to compare by hand.
+- **The compose dev image starts pnpm 11 and later as the non-root user** — `@voltro/cli`
+
+  The `compose` and `compose-mariadb` baselines' `docker/dev.Dockerfile` activated pnpm as root but never ran it. pnpm 11 and later download a native binary on their first run, into a directory the non-root user compose starts every service as cannot write, so `docker compose … up` stopped at the first service with `EACCES … pnpm-native….tgz`. The image now runs pnpm once while it is built. Run `voltro baseline sync` and rebuild the image to take it.
+- **The closed devtools capsule glows again** — `@voltro/devtools`
+
+  When the overlay became a docking console, the closed state turned into a status capsule and lost the launcher's animated halo: a bright slice of brand violet circling the rim while a soft glow breathes around it. The capsule carries it again, traced along its pill outline. It steps aside while `voltro dev` reports a status, where the capsule's own pulse in the status colour takes over, and it stands still under `prefers-reduced-motion`.
+- **`db gc-snapshots` drops snapshots that reference each other, and works on MySQL** — `@voltro/cli`
+
+  `voltro db gc-snapshots` dropped snapshots in catalog order. Two tables one plan soft-dropped keep the foreign key between them, so dropping the parent first failed with `1451` on MySQL and MariaDB (and on Postgres whenever the parent came first), every run, after the snapshots before it were already gone; a soft-dropped reference column failed with `1553`. The keys the snapshots hold are now dropped first, then the columns, then the tables, a child before its parent. A snapshot that a table outside the set still references is refused before anything is dropped, with each constraint named. On MySQL 8 the command, and `voltro db restore-snapshot`, found no snapshot at all, because the catalog answers in upper case there; both read it now.
+- **`voltro update` lists the lines a manual note is about** — `@voltro/cli`
+
+  A `manual` codemod decides between "found" and "nothing in this repository matched" with its own check, and that check could be narrower than the search its note tells you to run. The note for probes on the app port told readers to grep for `internal/(liveness|readiness|startup)` but looked only for `VOLTRO_DEV_HEALTH_PORT`, so a project whose Helm values, compose healthcheck and smoke script probed app port + 1 directly got "nothing in this repository matched" while every one of them needed moving. A manual note can now list the lines it is about, and `voltro update` prints them under it (`── found in this repository (N lines) — check each:`, `file:line text`). The probe note lists every probe path and variable it finds, with the port beside each probe; the anonymous-tenant note names each api config that sets neither option. A note that lists a line is reported as found.
+- **MariaDB: a charset, type or nullability change keeps the column's CHECK** — `@voltro/database`
+
+  On MariaDB a CHECK written on the column itself — how a table with `text().oneOf([...])` is created — is part of the column definition, and `MODIFY COLUMN` without it removes it. Every operation that redefines a column did exactly that: a `convert-charset` rewrite, a nullability, type or default change. The re-plan then proposed `add-check` for each, and the apply refused with "the migration did not converge", after every statement had run. Declaring `store.charset` over an existing schema hit it once per converted enum column. The rewrite now restates each column's CHECK, so it stays where it was; an explicit `drop-check` still removes one the declaration no longer has. MySQL keeps such a CHECK on its own and is unchanged. `emitConvertCharsetMysql` takes the CHECKs to keep as an optional last argument, so every existing call compiles as before.
+- **`voltro serve` checks pending file migrations from its bundle, not from source** — `@voltro/cli`, `@voltro/database`
+
+  Before it boots, `voltro serve` refuses when a `migrations/<timestamp>_<slug>.ts` file has never run. `voltro build` did not bundle those files, so serve imported each from source — and, through it, a second copy of the framework's migration code. Measured on an app with two file migrations: about 290 ms during which the process answered nothing, after the port was already taking health probes. The build now bundles every file migration, and serve reads them from the bundle. `pendingFileMigrationIds` takes an optional module importer as its last argument, and `walkMigrationFiles` is exported; every existing call compiles as before.
+- **`voltro update --wait` says what the registry answered, per package** — `@voltro/cli`
+
+  `--wait` reported every package it could not confirm as "not on the registry", whether the registry had answered 404 or the request had failed. It now names the answer with each package — `404: not published yet`, or `no answer: <status or error>` — while it waits, at the ceiling, and after a failed install, so a network error is never reported as a missing release. In `pnpm-workspace.yaml`, a `minimumReleaseAgeExclude` entry that pnpm 12.5 and later widened in place to a version union (`'@voltro/ai@0.78.0 || 0.79.0'`) was skipped without a word; a union holding the version being left now moves to the target like any other entry.
+
+---
+
 ## [0.79.0] — 2026-09-23
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -2302,6 +2302,27 @@ export declare const findAdvisoryResourceGuards: (procedures: ReadonlyArray<{
 /** Record a completed response for replay. */
 export declare const finishIdempotent: (store: IdempotencyStore, scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
 
+/**
+ * The value a ONE-SHOT read of an rpc resolves to, given the first value it
+ * delivered.
+ *
+ * A query's success type is the three-member union above, and a one-shot read
+ * takes only its first event: a `snapshot` resolves to its `data`; an `error`
+ * REJECTS — with the typed error on `cause` and `voltroError`, so a caller can
+ * still branch on its `_tag` — exactly as a failed exit would; a `delta` cannot
+ * be first and says so. Anything else is a mutation or action's own result and
+ * passes through, which may legitimately be a tagged object of the app's.
+ *
+ * Shared because there are two such reads — the server loader's `ctx.query`
+ * over `POST /rpc` and the browser loader's over the page's socket — and an
+ * unwrap written twice is how an authorization answer once reached a loader as
+ * its return value on one transport and as a rejection on the other.
+ *
+ * `label` prefixes every message (`[loader.query]`), naming the surface that
+ * made the read.
+ */
+export declare const firstEventValue: (tag: string, value: unknown, label: string) => unknown;
+
 /** A route rendered for humans — logs, the inspect surface, the dashboard. */
 export declare const formatEventRoute: (route: string) => string;
 
@@ -4847,6 +4868,9 @@ declare interface RestRouteContext {
      *  REST handlers on the same capability surface as query/mutation/action
      *  handlers without creating a protocol-to-runtime package dependency. */
     readonly app?: unknown;
+    /** The caller's address, resolved through `security.trustedProxies` — the
+     *  value the listener's per-IP shield counts. Absent when unknown. */
+    readonly remoteAddr?: string;
 }
 
 declare interface RestRouteDescriptor<I, O> {
@@ -5149,6 +5173,16 @@ export declare interface RpcInterceptorContext {
     readonly surface?: 'rest';
     /** The descriptor's `publicApi` spec, on a projected call. */
     readonly publicApi?: PublicApiSpec;
+    /**
+     * The caller's address — the same value the pre-auth IP shield counts, resolved
+     * by the listener through `security.trustedProxies` (and
+     * `security.clientAddressHeader`). A client cannot set it: the listener
+     * writes it, and any copy the client sends is discarded.
+     *
+     * Absent when the call did not arrive over the network (a workflow step, a
+     * schedule, an in-process invocation) or the socket address is unknown.
+     */
+    readonly remoteAddr?: string;
 }
 
 /**
@@ -7506,7 +7540,12 @@ export declare const WorkflowRunHandleSchema: Schema.Struct<{
     status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-         *  `rateLimit` | `singleton`. */
+         *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+         *
+         *  `unacknowledged` — the start was dispatched and no acknowledgement came
+         *  back. The engine may have it; recovery retries the dispatch and binds the
+         *  receipt (`id`) to whatever run results. It is not a failure: do not
+         *  report one to a user, follow the receipt. */
         mode: typeof Schema.String;
         /** Epoch ms this may first be admitted. Null for a drop or a skip. */
         dueAt: Schema.NullOr<typeof Schema.Number>;
@@ -7694,7 +7733,12 @@ export declare type WorkflowStartDeferral = Schema.Schema.Type<typeof WorkflowSt
  */
 export declare const WorkflowStartDeferralSchema: Schema.Struct<{
     /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-     *  `rateLimit` | `singleton`. */
+     *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+     *
+     *  `unacknowledged` — the start was dispatched and no acknowledgement came
+     *  back. The engine may have it; recovery retries the dispatch and binds the
+     *  receipt (`id`) to whatever run results. It is not a failure: do not
+     *  report one to a user, follow the receipt. */
     mode: typeof Schema.String;
     /** Epoch ms this may first be admitted. Null for a drop or a skip. */
     dueAt: Schema.NullOr<typeof Schema.Number>;
@@ -7812,7 +7856,12 @@ export declare const workflowToRpc: <const Name extends string, Payload extends
     status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-         *  `rateLimit` | `singleton`. */
+         *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+         *
+         *  `unacknowledged` — the start was dispatched and no acknowledgement came
+         *  back. The engine may have it; recovery retries the dispatch and binds the
+         *  receipt (`id`) to whatever run results. It is not a failure: do not
+         *  report one to a user, follow the receipt. */
         mode: typeof Schema.String;
         /** Epoch ms this may first be admitted. Null for a drop or a skip. */
         dueAt: Schema.NullOr<typeof Schema.Number>;

package/dist/index.js

@@ -136,10 +136,22 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	_tag: p.Literal("error"),
 	error: p.Unknown,
 	revision: p.optional(p.Number)
-})), b = (e, t) => {
+})), wt = (e, t, n) => {
+	if (!t || typeof t != "object" || !("_tag" in t)) return t;
+	let r = t;
+	switch (r._tag) {
+		case "snapshot": return r.data;
+		case "error": {
+			let t = r.error;
+			throw Object.assign(Error(`${n} ${e}: ${t?._tag ?? "error"}${t?.message ? ` — ${t.message}` : ""}`, { cause: r.error }), { voltroError: r.error });
+		}
+		case "delta": throw Error(`${n} ${e}: received a 'delta' as the first event, which should be impossible — a subscription always opens with a snapshot. This is a framework bug.`);
+		default: return t;
+	}
+}, b = (e, t) => {
 	let n = `${e ?? "this procedure"} input`;
 	return t === !0 ? `${n} (guarded — the guard did NOT run: the payload failed to decode first, so this says nothing about access)` : n;
-}, wt = (e) => {
+}, Tt = (e) => {
 	let t = e.ast;
 	return t._tag === "TypeLiteral" && (t.propertySignatures?.length ?? 0) === 0 && (t.indexSignatures?.length ?? 0) === 0;
 }, x = (e, t, n) => {
@@ -147,8 +159,8 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		parseOptions: { onExcessProperty: "error" },
 		parseIssueTitle: () => r
 	});
-	return wt(e) ? p.filter((e) => typeof e == "object" && e && Object.keys(e).length > 0 ? `this procedure declares no input; received: ${Object.keys(e).join(", ")}` : void 0)(i).annotations({ identifier: r }) : i;
-}, Tt = class extends p.TaggedError()("BusinessRuleViolation", {
+	return Tt(e) ? p.filter((e) => typeof e == "object" && e && Object.keys(e).length > 0 ? `this procedure declares no input; received: ${Object.keys(e).join(", ")}` : void 0)(i).annotations({ identifier: r }) : i;
+}, Et = class extends p.TaggedError()("BusinessRuleViolation", {
 	rule: p.String,
 	params: p.optional(p.Record({
 		key: p.String,
@@ -157,21 +169,21 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	field: p.optional(p.String),
 	message: p.optional(p.String),
 	severity: p.Literal("error", "warning")
-}) {}, Et = p.Struct({
+}) {}, Dt = p.Struct({
 	field: p.String,
 	message: p.String,
 	params: p.optional(p.Record({
 		key: p.String,
 		value: p.Unknown
 	}))
-}), Dt = class extends p.TaggedError()("ValidationError", {
+}), Ot = class extends p.TaggedError()("ValidationError", {
 	field: p.String,
 	message: p.String,
 	params: p.optional(p.Record({
 		key: p.String,
 		value: p.Unknown
 	}))
-}) {}, Ot = class extends p.TaggedError()("ValidationErrors", { issues: p.Array(Et).pipe(p.minItems(1)) }) {}, kt = (e) => {
+}) {}, kt = class extends p.TaggedError()("ValidationErrors", { issues: p.Array(Dt).pipe(p.minItems(1)) }) {}, At = (e) => {
 	if (typeof e != "object" || !e) return [];
 	let t = e._tag;
 	if (t === "ValidationError") {
@@ -197,34 +209,34 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		}];
 	}
 	return [];
-}, At = class extends p.TaggedError()("ApprovalRequired", {
+}, jt = class extends p.TaggedError()("ApprovalRequired", {
 	approvalId: p.String,
 	procedure: p.String,
 	expiresAt: p.String,
 	requiredScopes: p.Array(p.String),
 	reason: p.NullOr(p.String),
 	created: p.Boolean
-}) {}, jt = class extends p.TaggedError()("ApprovalNotFound", { approvalId: p.String }) {}, Mt = class extends p.TaggedError()("ApprovalSelfApproval", {
+}) {}, Mt = class extends p.TaggedError()("ApprovalNotFound", { approvalId: p.String }) {}, Nt = class extends p.TaggedError()("ApprovalSelfApproval", {
 	approvalId: p.String,
 	subjectId: p.NullOr(p.String)
-}) {}, Nt = class extends p.TaggedError()("ApprovalRejected", {
+}) {}, Pt = class extends p.TaggedError()("ApprovalRejected", {
 	approvalId: p.String,
 	decidedBy: p.NullOr(p.String),
 	note: p.NullOr(p.String)
 }) {}, S = class extends p.TaggedError()("ApprovalExpired", {
 	approvalId: p.String,
 	expiredAt: p.String
-}) {}, Pt = class extends p.TaggedError()("ApprovalNotPending", {
+}) {}, Ft = class extends p.TaggedError()("ApprovalNotPending", {
 	approvalId: p.String,
 	status: p.String
-}) {}, Ft = class extends p.TaggedError()("ApprovalForbidden", {
+}) {}, It = class extends p.TaggedError()("ApprovalForbidden", {
 	approvalId: p.String,
 	required: p.NullOr(p.String),
 	message: p.String
 }) {}, C = class extends p.TaggedError()("ApprovalUnavailable", {
 	procedure: p.String,
 	message: p.String
-}) {}, It = p.Union(At, Nt, S, C), Lt = p.Union(jt, Mt, S, Pt, Ft, C), Rt = p.Struct({
+}) {}, Lt = p.Union(jt, Pt, S, C), Rt = p.Union(Mt, Nt, S, Ft, It, C), zt = p.Struct({
 	id: p.String,
 	procedure: p.String,
 	kind: p.Literal("mutation", "action"),
@@ -238,8 +250,8 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	decidedAt: p.NullOr(p.String),
 	note: p.NullOr(p.String),
 	relation: p.Literal("to-decide", "requested")
-}), w = "channel:", zt = Symbol.for("@voltro/protocol/reactivityChannels"), Bt = globalThis, T = Bt[zt] ?? (Bt[zt] = /* @__PURE__ */ new Map()), Vt = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/, Ht = (e) => {
-	if (!Vt.test(e)) throw Error(`reactivityChannel('${e}'): invalid channel name.\n  Use lowercase kebab segments separated by dots — \`presence\`, \`job-queue\`,
+}), w = "channel:", Bt = Symbol.for("@voltro/protocol/reactivityChannels"), Vt = globalThis, T = Vt[Bt] ?? (Vt[Bt] = /* @__PURE__ */ new Map()), Ht = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/, Ut = (e) => {
+	if (!Ht.test(e)) throw Error(`reactivityChannel('${e}'): invalid channel name.\n  Use lowercase kebab segments separated by dots — \`presence\`, \`job-queue\`,
   \`billing.usage\`. A \`:\` is refused because it is the namespace separator in
   the routing key (\`${w}<name>\`), and an uppercase letter is\n  refused because a key that differs only by case reads as one channel and
   routes as two.`);
@@ -252,14 +264,14 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		toString: () => n
 	});
 	return T.set(e, r), r;
-}, Ut = (e) => typeof e == "object" && !!e && e.kind === "reactivity-channel", Wt = (e) => e.startsWith(w), Gt = () => new Set([...T.values()].map((e) => e.key)), E = (e) => Ut(e) ? e.key : e, Kt = (e) => e === void 0 ? [] : Array.isArray(e) ? e.map(E) : [E(e)], qt = (e) => e === void 0 ? void 0 : Array.isArray(e) ? e.map(E) : E(e), Jt = (e) => {
-	let t = Gt(), n = [];
-	for (let r of e) for (let e of Kt(r.source)) Wt(e) && !t.has(e) && n.push({
+}, Wt = (e) => typeof e == "object" && !!e && e.kind === "reactivity-channel", Gt = (e) => e.startsWith(w), Kt = () => new Set([...T.values()].map((e) => e.key)), E = (e) => Wt(e) ? e.key : e, qt = (e) => e === void 0 ? [] : Array.isArray(e) ? e.map(E) : [E(e)], Jt = (e) => e === void 0 ? void 0 : Array.isArray(e) ? e.map(E) : E(e), Yt = (e) => {
+	let t = Kt(), n = [];
+	for (let r of e) for (let e of qt(r.source)) Gt(e) && !t.has(e) && n.push({
 		procedure: r.name,
 		key: e
 	});
 	return n;
-}, Yt = (e, t) => {
+}, Xt = (e, t) => {
 	let n = e?.injectExternalChange;
 	return n !== void 0 && (n.call(e, {
 		table: t.key,
@@ -268,8 +280,8 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		old: {},
 		origin: "inline"
 	}), !0);
-}, Xt = (e) => e.internal !== !0, D = (e) => {
-	if (Zt(e), e.idempotencyScope !== void 0 && e.idempotencyScope !== "subject" && e.idempotencyScope !== "connection") throw Error(`${e.name}: idempotencyScope must be 'subject' or 'connection'`);
+}, Zt = (e) => e.internal !== !0, D = (e) => {
+	if (Qt(e), e.idempotencyScope !== void 0 && e.idempotencyScope !== "subject" && e.idempotencyScope !== "connection") throw Error(`${e.name}: idempotencyScope must be 'subject' or 'connection'`);
 	let t = e.serialize;
 	if (t !== void 0) {
 		if (typeof t.key != "function") throw Error(`${e.name}: serialize.key must be a function of the input`);
@@ -293,7 +305,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	let r = [e.publicApi === void 0 ? void 0 : "publicApi", e.exposeAsTool === void 0 ? void 0 : "exposeAsTool"].filter((e) => e !== void 0);
 	if (r.length === 0) return e;
 	throw Error(`${e.name}: \`internal: true\` cannot be combined with ${r.map((e) => `\`${e}\``).join(" or ")}. \`internal\` takes the procedure OFF the wire; those put it back ON a different one (${r.includes("publicApi") ? "a REST route" : "an agent tool"}), and that surface is projected without consulting the flag — so the procedure would be unreachable from your client and reachable from the internet. Drop \`internal: true\` if the wider surface is intended, or remove the ${r.join(" / ")} annotation if it is not.`);
-}, Zt = (e) => {
+}, Qt = (e) => {
 	let t = e.requiresApproval;
 	if (t !== void 0) {
 		if (!Array.isArray(t.approvers) || t.approvers.length === 0) throw Error(`${e.name}: \`requiresApproval.approvers\` is empty, so NOBODY can approve this\n  procedure and every call would park forever. Name the scope(s) an approver must hold
@@ -303,7 +315,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
   human from every other, and the second-pair-of-eyes control would enforce nothing.
   Give the procedure a \`guards:\` decision, or drop \`requiresApproval\`.`);
 	}
-}, Qt = (e) => e.action !== void 0 && e.resourceType !== void 0, $t = (e) => e.authenticated === !0, en = (e) => e.openAccess !== void 0 || e.guards !== void 0 && e.guards.length > 0, O = (e, t, n) => {
+}, $t = (e) => e.action !== void 0 && e.resourceType !== void 0, en = (e) => e.authenticated === !0, tn = (e) => e.openAccess !== void 0 || e.guards !== void 0 && e.guards.length > 0, O = (e, t, n) => {
 	if (n === void 0) return t;
 	if (n.trim() === "") throw Error(`${e}: \`openAccess\` needs a REASON, not an empty string. It is the sentence a\n  reviewer reads to decide whether this procedure should really be callable
   without an authorization check — e.g. \`openAccess: 'public pricing, no caller data'\`.`);
@@ -316,7 +328,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	input: e.input,
 	output: e.output,
 	error: e.error ?? p.Never,
-	source: qt(e.source),
+	source: Jt(e.source),
 	cache: e.cache,
 	guards: O(e.name, e.guards, e.openAccess),
 	openAccess: e.openAccess,
@@ -355,7 +367,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	requiresApproval: e.requiresApproval,
 	internal: e.internal,
 	overridesPlugin: e.overridesPlugin
-}), tn = (e) => D({
+}), nn = (e) => D({
 	kind: "stream",
 	name: e.name,
 	input: e.input,
@@ -365,44 +377,44 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	overridesPlugin: e.overridesPlugin,
 	guards: O(e.name, e.guards, e.openAccess),
 	openAccess: e.openAccess
-}), M = (e, t) => t && t.length > 0 ? p.Union(e, ...t) : e, N = (e) => e !== void 0 && e.some((e) => !u(e)), nn = (e) => p.Union(e, f, l), rn = (e) => p.Union(e, Tt), an = (e) => p.Union(e, Dt, Ot), on = (e, t) => t === void 0 ? e : p.Union(e, It), P = (e, t) => {
-	let n = nn(e.error);
+}), M = (e, t) => t && t.length > 0 ? p.Union(e, ...t) : e, N = (e) => e !== void 0 && e.some((e) => !u(e)), rn = (e) => p.Union(e, f, l), an = (e) => p.Union(e, Et), on = (e) => p.Union(e, Ot, kt), sn = (e, t) => t === void 0 ? e : p.Union(e, Lt), P = (e, t) => {
+	let n = rn(e.error);
 	if (t === "stream" || t === "query") return n;
-	let r = t === "mutation" ? p.Union(rn(n), dt, ht) : n;
-	return on(an(t === "mutation" && e.idempotencyScope === "connection" ? p.Union(r, qe) : r), e.requiresApproval);
-}, sn = (e, t) => M(nn(e.errorSchema), t), cn = (e, t) => ({
+	let r = t === "mutation" ? p.Union(an(n), dt, ht) : n;
+	return sn(on(t === "mutation" && e.idempotencyScope === "connection" ? p.Union(r, qe) : r), e.requiresApproval);
+}, cn = (e, t) => M(rn(e.errorSchema), t), ln = (e, t) => ({
 	...e,
 	name: t
-}), ln = (e, t) => m.make(e.name, {
+}), un = (e, t) => m.make(e.name, {
 	payload: x(e.input, e.name, N(e.guards)),
 	success: y(e.output),
 	error: M(P(e, "query"), t),
 	stream: !0
-}), un = (e, t) => m.make(e.name, {
+}), dn = (e, t) => m.make(e.name, {
 	payload: x(e.input, e.name, N(e.guards)),
 	success: e.output,
 	error: M(P(e, "mutation"), t)
-}), dn = (e, t) => m.make(e.name, {
+}), fn = (e, t) => m.make(e.name, {
 	payload: x(e.input, e.name, N(e.guards)),
 	success: e.output,
 	error: M(P(e, "action"), t)
-}), fn = (e, t) => m.make(e.name, {
+}), pn = (e, t) => m.make(e.name, {
 	payload: x(e.input, e.name, N(e.guards)),
 	success: e.element,
 	error: M(e.error, t),
 	stream: !0
-}), pn = (e) => {
+}), mn = (e) => {
 	if (typeof e != "object" || !e) return;
 	let t = e._tag;
 	return typeof t == "string" ? t : void 0;
-}, mn = (e) => {
+}, hn = (e) => {
 	switch (e.kind) {
-		case "query": return ln(e);
-		case "mutation": return un(e);
-		case "action": return dn(e);
-		case "stream": return fn(e);
+		case "query": return un(e);
+		case "mutation": return dn(e);
+		case "action": return fn(e);
+		case "stream": return pn(e);
 	}
-}, hn = (e) => {
+}, gn = (e) => {
 	let t = e.input, n = t === void 0 ? {} : { input: t }, r = e.output, i = r === void 0 ? {} : { output: r };
 	if (e.kind === "query") return {
 		kind: "query",
@@ -448,7 +460,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 			..."relations" in e && e.relations !== void 0 ? { relations: e.relations } : {}
 		}))
 	};
-}, gn = 7500, _n = (e) => typeof e == "object" && !!e && e.kind === "event", vn = (e) => {
+}, _n = 7500, vn = (e) => typeof e == "object" && !!e && e.kind === "event", yn = (e) => {
 	if (e.name.length === 0) throw Error("defineEvent: `name` must not be empty");
 	if (/\s/.test(e.name)) throw Error(`defineEvent("${e.name}"): \`name\` must not contain whitespace.\n  The name is used as a broker subject segment. NATS refuses a subject with
   whitespace and delivers nothing — silently, and only on that broker, so an
@@ -483,62 +495,62 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		webhook: e.webhook,
 		delivery: e.delivery
 	};
-}, yn = (e) => p.Struct({
+}, bn = (e) => p.Struct({
 	_tag: p.Literal("event"),
 	origin: p.String,
 	n: p.Number,
 	emittedAt: p.Number,
 	payload: e
-}), bn = p.Struct({
+}), xn = p.Struct({
 	_tag: p.Literal("gap"),
 	missed: p.Number,
 	reason: p.Literal("buffer", "resume")
-}), xn = p.Struct({ _tag: p.Literal("attached") }), Sn = (e) => p.Union(xn, yn(e), bn), Cn = p.Struct({
+}), Sn = p.Struct({ _tag: p.Literal("attached") }), Cn = (e) => p.Union(Sn, bn(e), xn), wn = p.Struct({
 	origin: p.String,
 	n: p.Number
-}), wn = (e) => p.Struct({
+}), Tn = (e) => p.Struct({
 	key: e,
-	resume: p.optional(p.Array(Cn))
-}), Tn = (e, t) => {
+	resume: p.optional(p.Array(wn))
+}), En = (e, t) => {
 	let n = e.guards !== void 0 && e.guards.some((e) => !u(e)) ? p.Union(f, l) : l, r = t && t.length > 0 ? p.Union(n, ...t) : n;
 	return m.make(e.name, {
-		payload: x(wn(e.key), e.name, N(e.guards)),
-		success: Sn(e.payload),
+		payload: x(Tn(e.key), e.name, N(e.guards)),
+		success: Cn(e.payload),
 		error: r,
 		stream: !0
 	});
-}, En = class extends p.TaggedError()("EventPayloadInvalid", {
+}, Dn = class extends p.TaggedError()("EventPayloadInvalid", {
 	event: p.String,
 	message: p.String
-}) {}, Dn = class extends p.TaggedError()("EventKeyInvalid", {
+}) {}, On = class extends p.TaggedError()("EventKeyInvalid", {
 	event: p.String,
 	message: p.String
-}) {}, On = class extends p.TaggedError()("EventPayloadTooLarge", {
+}) {}, kn = class extends p.TaggedError()("EventPayloadTooLarge", {
 	event: p.String,
 	bytes: p.Number,
 	limit: p.Number
-}) {}, kn = (e) => {
+}) {}, An = (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);
-}, An = "\0", jn = (e, t, n) => [
+}, jn = "\0", Mn = (e, t, n) => [
 	e ?? "~",
 	t,
-	kn(n)
-].join("\0"), Mn = (e) => {
+	An(n)
+].join("\0"), Nn = (e) => {
 	let [t = "~", n = "", r = ""] = e.split("\0");
 	return {
 		tenantId: t === "~" ? null : t,
 		event: n,
 		key: r
 	};
-}, Nn = (e) => e.split("\0").join(" · "), F = Symbol.for("@voltro/protocol/workflow-access"), Pn = {
+}, Pn = (e) => e.split("\0").join(" · "), F = Symbol.for("@voltro/protocol/workflow-access"), Fn = {
 	guards: void 0,
 	openAccess: void 0,
 	internal: !1,
 	controls: void 0,
 	controlsOpenAccess: void 0
-}, Fn = (e, t) => {
+}, In = (e, t) => {
 	let n = t.guards;
 	if (n !== void 0 && n.length === 0) throw Error(`workflow("${e}"): \`guards: []\` is empty, so it enforces nothing —\n  but it reads at the call site as if the start were protected. Omit the field
   and decide with \`openAccess\` or \`internal\`, or list the scopes that may start it.`);
@@ -570,16 +582,16 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		controls: i === void 0 ? r : [d(i.trim())],
 		controlsOpenAccess: i?.trim()
 	};
-}, In = (e, t) => {
+}, Ln = (e, t) => {
 	Object.defineProperty(e, F, {
 		value: t,
 		enumerable: !1
 	});
 }, I = (e) => {
-	if (typeof e != "object" || !e) return Pn;
+	if (typeof e != "object" || !e) return Fn;
 	let t = e[F];
-	return t === void 0 ? Pn : t;
-}, Ln = (e) => {
+	return t === void 0 ? Fn : t;
+}, Rn = (e) => {
 	let t = I(e);
 	return {
 		name: e.name,
@@ -588,18 +600,18 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		openAccess: t.openAccess,
 		controls: t.controls
 	};
-}, Rn = (e) => e, zn = (e) => e, Bn = (e) => {
+}, zn = (e) => e, Bn = (e) => e, Vn = (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;
-}, Vn = (e) => {
+}, Hn = (e) => {
 	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
-}, Hn = (e, t) => {
+}, Un = (e, t) => {
 	let n = pt.GenericTag(e);
 	return {
 		Tag: n,
 		Live: mt.succeed(n, t)
 	};
-}, Un = (e, t, n) => {
+}, Wn = (e, t, n) => {
 	if (!t) return { ok: !0 };
 	let r = n === void 0 ? null : L(n);
 	if (!r) return {
@@ -609,7 +621,7 @@ var gt = p.Union(p.String, p.Number), h = p.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 (!Wn(i, r)) return {
+	for (let i of a) if (!Gn(i, r)) return {
 		ok: !1,
 		reason: `plugin "${e}" requires framework ${t}, running ${n}`
 	};
@@ -622,7 +634,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		patch: Number(t[3]),
 		pre: t[4] ?? ""
 	} : null;
-}, R = (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, Wn = (e, t) => {
+}, R = (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, Gn = (e, t) => {
 	if (e === "*") return !0;
 	if (e.startsWith("^")) {
 		let n = L(e.slice(1));
@@ -644,29 +656,29 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	}
 	let r = L(e);
 	return r ? R(t, r) === 0 : !1;
-}, Gn = (e) => {
+}, Kn = (e) => {
 	let t = e.startsWith("@") ? e.replace(/^@[^/]+\//, "") : e;
 	return (t.startsWith("plugin-") ? t.slice(7) : t).replace(/-([a-zA-Z0-9])/g, (e, t) => t.toUpperCase());
-}, Kn = (e) => {
+}, qn = (e) => {
 	let t = e.startsWith("@") ? e.replace(/^@[^/]+\//, "") : e;
 	return (t.startsWith("plugin-") ? t.slice(7) : t).replace(/#/g, "--").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}, qn = Symbol.for("@voltro/protocol/pluginAliases"), z = () => {
-	let e = globalThis, t = e[qn];
+}, Jn = Symbol.for("@voltro/protocol/pluginAliases"), z = () => {
+	let e = globalThis, t = e[Jn];
 	if (t instanceof Map) return t;
 	let n = /* @__PURE__ */ new Map();
-	return e[qn] = n, n;
-}, Jn = (e) => {
+	return e[Jn] = n, n;
+}, Yn = (e) => {
 	let t = z();
 	for (let [n, r] of Object.entries(e)) {
 		if (r === "") continue;
 		let e = t.get(n);
 		e === void 0 ? t.set(n, /* @__PURE__ */ new Set([r])) : e.add(r);
 	}
-}, Yn = () => {
+}, Xn = () => {
 	z().clear();
-}, Xn = (e, t) => {
+}, Zn = (e, t) => {
 	let n = z().get(e);
-	if (n === void 0 || n.size === 0) return `${Gn(e)}.${t}`;
+	if (n === void 0 || n.size === 0) return `${Kn(e)}.${t}`;
 	if (n.size === 1) return `${[...n][0]}.${t}`;
 	let r = [...n].filter((e) => !e.includes("#"));
 	if (r.length === 1) return `${r[0]}.${t}`;
@@ -732,23 +744,23 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	if (t.kind === "admission") return e.kind === (t.outcome.kind === "cancelled" ? "confirmed" : "already-terminal");
 	let n = t.snapshot;
 	return n.workflowName !== e.workflowName || n.id.length === 0 || n.executionId.length === 0 ? !1 : e.kind === "accepted" ? n.status === "running" || n.status === "suspended" : e.kind === "confirmed" ? n.status === "cancelled" : e.kind === "already-terminal" && (n.status === "succeeded" || n.status === "failed" || n.status === "cancelled");
-}, { message: () => "Queued cancellation acknowledgement contradicts its receipt or observation" })), Zn = p.Literal("cancel", "terminate", "abandon"), Qn = p.Struct({
+}, { message: () => "Queued cancellation acknowledgement contradicts its receipt or observation" })), Qn = p.Literal("cancel", "terminate", "abandon"), $n = p.Struct({
 	mode: p.String,
 	dueAt: p.NullOr(p.Number),
 	retryAfterMs: p.NullOr(p.Number),
 	intentId: p.NullOr(p.String)
-}), $n = p.Struct({
+}), er = p.Struct({
 	id: p.String,
 	workflowName: p.String,
 	executionId: p.NullOr(p.String),
 	status: p.Literal("running", "succeeded", "queued", "dropped", "skipped", "replayed"),
-	deferral: p.optional(Qn)
-}), er = (e, t) => {
+	deferral: p.optional($n)
+}), tr = (e, t) => {
 	let n = I(e);
 	return m.make(e.name, {
 		payload: x(e.payloadSchema, e.name, N(n.guards)),
-		success: $n,
-		error: sn({
+		success: er,
+		error: cn({
 			errorSchema: e.errorSchema,
 			guards: n.guards
 		}, t)
@@ -772,12 +784,12 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	durationMs: p.NullOr(p.Number),
 	traceId: p.NullOr(p.String),
 	parentExecutionId: p.NullOr(p.String),
-	parentClosePolicy: p.NullOr(Zn)
-}), tr = p.Struct({
+	parentClosePolicy: p.NullOr(Qn)
+}), nr = p.Struct({
 	tag: p.optional(p.String),
 	status: p.optional(V),
 	limit: p.optional(p.Number)
-}), nr = p.Struct({
+}), rr = p.Struct({
 	id: p.String,
 	runId: p.String,
 	stepName: p.String,
@@ -792,7 +804,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	startedAt: p.Date,
 	completedAt: p.NullOr(p.Date),
 	durationMs: p.NullOr(p.Number)
-}), rr = p.Struct({
+}), ir = p.Struct({
 	id: p.String,
 	runId: p.String,
 	eventType: p.String,
@@ -800,7 +812,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	occurredAt: p.Date,
 	stepName: p.NullOr(p.String),
 	attempt: p.NullOr(p.Number)
-}), ir = p.Struct({
+}), ar = p.Struct({
 	id: p.String,
 	name: p.String,
 	payload: p.Unknown,
@@ -808,7 +820,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	subject: p.NullOr(p.Unknown),
 	traceId: p.NullOr(p.String),
 	occurredAt: p.Date
-}), ar = p.Struct({
+}), or = p.Struct({
 	id: p.String,
 	eventId: p.String,
 	eventName: p.String,
@@ -821,10 +833,10 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	errorMessage: p.NullOr(p.String),
 	createdAt: p.Date,
 	completedAt: p.NullOr(p.Date)
-}), or = p.Struct({ id: p.String }), K = p.Struct({ runId: p.String }), sr = p.Struct({
+}), sr = p.Struct({ id: p.String }), K = p.Struct({ runId: p.String }), cr = p.Struct({
 	name: p.optional(p.String),
 	limit: p.optional(p.Number)
-}), cr = p.Struct({ eventId: p.String }), q = p.Struct({
+}), lr = p.Struct({ eventId: p.String }), q = p.Struct({
 	requestId: p.NonEmptyString,
 	cause: p.optionalWith(p.Struct({
 		reason: p.NonEmptyString,
@@ -837,7 +849,7 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	workflowName: p.String,
 	executionId: p.String,
 	control: p.optional(q)
-}), lr = p.Struct({
+}), ur = p.Struct({
 	workflowName: p.NonEmptyString,
 	executionId: p.NonEmptyString,
 	operation: p.Literal("cancel", "resume"),
@@ -846,106 +858,106 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	workflowName: p.NonEmptyString,
 	receiptId: p.NonEmptyString,
 	requestId: p.NonEmptyString
-}), ur = p.Struct({
+}), dr = p.Struct({
 	...Y.fields,
 	cause: q.fields.cause
-}), dr = j({
+}), fr = j({
 	name: "__voltro.workflow.queued.cancel",
-	input: ur,
+	input: dr,
 	output: W,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), fr = k({
+}), pr = k({
 	name: "__voltro.workflow.queued.control",
 	input: Y,
 	output: W,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), pr = k({
+}), mr = k({
 	name: "__voltro.workflow.control",
-	input: lr,
+	input: ur,
 	output: U,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), mr = p.Struct({
+}), hr = p.Struct({
 	id: p.String,
 	signalName: p.String,
 	payload: p.optional(p.Unknown)
-}), hr = p.Struct({
+}), gr = p.Struct({
 	id: p.String,
 	updateName: p.String,
 	payload: p.optional(p.Unknown),
 	timeoutMs: p.optional(p.Number)
-}), gr = p.Struct({
+}), _r = p.Struct({
 	eventId: p.String,
 	updateId: p.String,
 	completedEventId: p.String,
 	result: p.Unknown
-}), _r = k({
+}), vr = k({
 	name: "__voltro.workflow.run",
 	source: "_voltro_workflow_runs",
-	input: or,
+	input: sr,
 	output: p.Array(G),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), vr = k({
+}), yr = k({
 	name: "__voltro.workflow.runs",
 	source: "_voltro_workflow_runs",
-	input: tr,
+	input: nr,
 	output: p.Array(G),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), yr = k({
+}), br = k({
 	name: "__voltro.workflow.run.steps",
 	source: "_voltro_workflow_run_steps",
 	input: K,
-	output: p.Array(nr),
+	output: p.Array(rr),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), br = k({
+}), xr = k({
 	name: "__voltro.workflow.run.events",
 	source: "_voltro_workflow_run_events",
 	input: K,
-	output: p.Array(rr),
+	output: p.Array(ir),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), xr = k({
+}), Sr = k({
 	name: "__voltro.workflow.domainEvents",
 	source: "_voltro_workflow_events",
-	input: sr,
-	output: p.Array(ir),
+	input: cr,
+	output: p.Array(ar),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), Sr = k({
+}), Cr = k({
 	name: "__voltro.workflow.event.deliveries",
 	source: "_voltro_workflow_event_deliveries",
-	input: cr,
-	output: p.Array(ar),
+	input: lr,
+	output: p.Array(or),
 	openAccess: "the answer is scoped to the caller in the executor — a system or admin:full subject sees every row, an authenticated subject the rows of its own tenant, an anonymous caller none"
-}), Cr = j({
+}), wr = j({
 	name: "__voltro.workflow.cancel",
 	input: J,
 	output: U,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), wr = j({
+}), Tr = j({
 	name: "__voltro.workflow.resume",
 	input: J,
 	output: U,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), Tr = j({
+}), Er = j({
 	name: "__voltro.workflow.signal",
-	input: mr,
+	input: hr,
 	output: p.Struct({ eventId: p.String }),
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), Er = j({
+}), Dr = j({
 	name: "__voltro.workflow.update",
-	input: hr,
-	output: gr,
+	input: gr,
+	output: _r,
 	openAccess: "authorization happens in the executor against the target run — the caller must be authenticated and belong to the run's tenant, and a missing run answers exactly like a foreign one"
-}), Dr = p.NonEmptyString.pipe(p.filter((e) => e.trim().length > 0, { message: () => "A workflow retry identity must not be blank" })), Or = p.Struct({
-	runId: Dr,
-	requestId: Dr
-}), kr = p.Struct({
-	...Or.fields,
+}), Or = p.NonEmptyString.pipe(p.filter((e) => e.trim().length > 0, { message: () => "A workflow retry identity must not be blank" })), kr = p.Struct({
+	runId: Or,
+	requestId: Or
+}), Ar = p.Struct({
+	...kr.fields,
 	payloadOverride: p.optional(p.Unknown)
 }), X = {
 	requestId: p.NonEmptyString,
 	originalRunId: p.NonEmptyString,
 	originalExecutionId: p.NonEmptyString,
 	workflowName: p.NonEmptyString
-}, Ar = p.Union(p.Struct({
+}, jr = p.Union(p.Struct({
 	...X,
 	kind: p.Literal("queued"),
 	nextAttemptAt: p.NullOr(p.Number)
@@ -966,38 +978,38 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	...X,
 	kind: p.Literal("rejected"),
 	failureId: p.NonEmptyString
-})), jr = "__voltro.undo.log", Mr = "__voltro.undo.apply", Nr = "__voltro.undo.redo", Pr = p.Struct({
+})), Mr = "__voltro.undo.log", Nr = "__voltro.undo.apply", Pr = "__voltro.undo.redo", Fr = p.Struct({
 	id: p.String,
 	tag: p.String,
 	label: p.NullOr(p.String),
 	undone: p.Boolean,
 	crossesAction: p.Boolean,
 	createdAt: p.String
-}), Fr = class extends p.TaggedError()("UndoNotFound", { invocationId: p.String }) {}, Ir = class extends p.TaggedError()("UndoForbidden", { invocationId: p.String }) {}, Lr = class extends p.TaggedError()("UndoConflict", {
+}), Ir = class extends p.TaggedError()("UndoNotFound", { invocationId: p.String }) {}, Lr = class extends p.TaggedError()("UndoForbidden", { invocationId: p.String }) {}, Rr = class extends p.TaggedError()("UndoConflict", {
 	invocationId: p.String,
 	reason: p.Literal("conflict", "action")
-}) {}, Rr = p.Union(Fr, Ir, Lr), zr = k({
-	name: jr,
+}) {}, zr = p.Union(Ir, Lr, Rr), Br = k({
+	name: Mr,
 	source: "_voltro_undo_log",
 	input: p.Struct({ limit: p.optional(p.Number) }),
-	output: p.Array(Pr),
+	output: p.Array(Fr),
 	openAccess: "subject-scoped by construction: lists only the calling subject's own undoable actions"
-}), Br = A({
-	name: Mr,
+}), Vr = A({
+	name: Nr,
 	input: p.Struct({ invocationId: p.String }),
 	output: p.Struct({ ok: p.Boolean }),
-	error: Rr,
+	error: zr,
 	openAccess: "subject-scoped by construction: undo is per-actor — another subject's invocation fails typed with UndoForbidden"
-}), Vr = A({
-	name: Nr,
+}), Hr = A({
+	name: Pr,
 	input: p.Struct({ invocationId: p.String }),
 	output: p.Struct({ ok: p.Boolean }),
-	error: Rr,
+	error: zr,
 	openAccess: "subject-scoped by construction: redo is per-actor — another subject's invocation fails typed with UndoForbidden"
-}), Hr = class extends p.TaggedError()("TenantScopeViolation", {
+}), Ur = class extends p.TaggedError()("TenantScopeViolation", {
 	table: p.String,
 	reason: p.String
-}) {}, Ur = class extends p.TaggedError()("StoreOperationFailed", {
+}) {}, Wr = class extends p.TaggedError()("StoreOperationFailed", {
 	operation: p.String,
 	table: p.String,
 	cause: p.String
@@ -1005,28 +1017,28 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	get message() {
 		return `${this.operation} on '${this.table}' failed: ${this.cause}`;
 	}
-}, Wr = class extends p.TaggedError()("NoRowFound", {
+}, Gr = class extends p.TaggedError()("NoRowFound", {
 	table: p.String,
 	found: p.Number
 }) {
 	get message() {
 		return this.found === 0 ? `expected exactly one row in '${this.table}', found none` : `expected exactly one row in '${this.table}', found more than one`;
 	}
-}, Gr = class extends p.TaggedError()("TableValidationFailed", {
+}, Kr = class extends p.TaggedError()("TableValidationFailed", {
 	table: p.String,
 	summary: p.String,
 	issues: p.Array(p.Struct({
 		path: p.String,
 		message: p.String
 	}))
-}) {}, Kr = class extends p.TaggedError()("TenantRowNotFound", {
+}) {}, qr = class extends p.TaggedError()("TenantRowNotFound", {
 	table: p.String,
 	id: p.String,
 	reason: p.String
-}) {}, qr = class extends p.TaggedError()("ServerOnlyColumnWrite", {
+}) {}, Jr = class extends p.TaggedError()("ServerOnlyColumnWrite", {
 	table: p.String,
 	columns: p.Array(p.String)
-}) {}, Jr = class extends p.TaggedError()("ConstraintViolation", {
+}) {}, Yr = class extends p.TaggedError()("ConstraintViolation", {
 	kind: p.Literal("foreignKey", "foreignKeyInUse", "unique", "notNull", "check"),
 	table: p.String,
 	operation: p.String,
@@ -1045,14 +1057,14 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 			case "check": return `check constraint ${t}: the row does not satisfy it`;
 		}
 	}
-}, Yr = "__voltro.approvals.pending", Xr = "__voltro.approvals.decide", Zr = k({
-	name: Yr,
+}, Xr = "__voltro.approvals.pending", Zr = "__voltro.approvals.decide", Qr = k({
+	name: Xr,
 	source: "_voltro_approvals",
 	input: p.Struct({ limit: p.optional(p.Number) }),
-	output: p.Array(Rt),
+	output: p.Array(zt),
 	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"
-}), Qr = A({
-	name: Xr,
+}), $r = A({
+	name: Zr,
 	input: p.Struct({
 		approvalId: p.String,
 		decision: p.Literal("approve", "reject"),
@@ -1062,35 +1074,35 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 		approvalId: p.String,
 		status: p.Literal("approved", "rejected")
 	}),
-	error: Lt,
+	error: Rt,
 	openAccess: "the approver authority is the PENDING ROW's own recorded scopes (plus an unconditional self-approval refusal), checked in-handler — a descriptor-level scope would have to be the union of every approval-requiring procedure in the app"
-}), Z = "__voltro.connections.list", $r = "__voltro.connections.start", ei = "__voltro.connections.submitToken", ti = "__voltro.connections.disconnect", Q = p.Literal("oauth2", "pat"), ni = p.Literal("disconnected", "connected", "expired", "revoked", "error"), ri = p.Struct({
+}), Z = "__voltro.connections.list", ei = "__voltro.connections.start", ti = "__voltro.connections.submitToken", ni = "__voltro.connections.disconnect", Q = p.Literal("oauth2", "pat"), ri = p.Literal("disconnected", "connected", "expired", "revoked", "error"), ii = p.Struct({
 	connectionId: p.String,
 	kind: Q,
 	label: p.String,
-	status: ni,
+	status: ri,
 	accountId: p.NullOr(p.String),
 	accountLabel: p.NullOr(p.String),
 	scopes: p.Array(p.String),
 	expiresAt: p.NullOr(p.String),
 	lastError: p.NullOr(p.String),
 	connectedAt: p.NullOr(p.String)
-}), ii = class extends p.TaggedError()("ConnectionNotDeclared", { connectionId: p.String }) {}, ai = class extends p.TaggedError()("ConnectionSubjectRequired", { connectionId: p.String }) {}, oi = class extends p.TaggedError()("ConnectionKindMismatch", {
+}), ai = class extends p.TaggedError()("ConnectionNotDeclared", { connectionId: p.String }) {}, oi = class extends p.TaggedError()("ConnectionSubjectRequired", { connectionId: p.String }) {}, si = class extends p.TaggedError()("ConnectionKindMismatch", {
 	connectionId: p.String,
 	expected: Q,
 	actual: Q
-}) {}, si = class extends p.TaggedError()("ConnectionHandshakeFailed", {
+}) {}, ci = class extends p.TaggedError()("ConnectionHandshakeFailed", {
 	connectionId: p.String,
 	reason: p.String,
 	transient: p.Boolean
-}) {}, $ = p.Union(ii, ai, oi, si), ci = k({
+}) {}, $ = p.Union(ai, oi, si, ci), li = k({
 	name: Z,
 	source: "_voltro_connections",
 	input: p.Struct({}),
-	output: p.Array(ri),
+	output: p.Array(ii),
 	openAccess: "self-scoped read: projects the declared connections for the calling subject only (its own connect/disconnect state)"
-}), li = j({
-	name: $r,
+}), ui = j({
+	name: ei,
 	input: p.Struct({
 		connectionId: p.String,
 		redirectTo: p.optional(p.String)
@@ -1101,8 +1113,8 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	}),
 	error: $,
 	openAccess: "self-service: begins an oauth handshake that stores a credential for the calling subject only; anonymous callers fail typed with ConnectionSubjectRequired"
-}), ui = A({
-	name: ei,
+}), di = A({
+	name: ti,
 	input: p.Struct({
 		connectionId: p.String,
 		token: p.String
@@ -1110,21 +1122,21 @@ var gt = p.Union(p.String, p.Number), h = p.Record({
 	output: p.Struct({ ok: p.Boolean }),
 	error: $,
 	openAccess: "self-service: stores a pasted token as the calling subject's own credential; anonymous callers fail typed with ConnectionSubjectRequired"
-}), di = A({
-	name: ti,
+}), fi = A({
+	name: ni,
 	input: p.Struct({ connectionId: p.String }),
 	output: p.Struct({ ok: p.Boolean }),
 	error: $,
 	openAccess: "self-service: deletes only the calling subject's own credential row for this connection"
-}), fi = (e) => {
+}), pi = (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;
-}, pi = 4001, mi = /* @__PURE__ */ new Set(["/rpc", "/ws"]), hi = (e) => {
+}, mi = 4001, hi = /* @__PURE__ */ new Set(["/rpc", "/ws"]), gi = (e) => {
 	for (let [t, n] of Object.entries(e.limits ?? {})) if (n !== void 0 && (!Number.isSafeInteger(n) || n <= 0)) throw Error(`defineWebSocket: limits.${t} must be a positive safe integer`);
 	if (!e.path.startsWith("/")) throw Error(`defineWebSocket: path must be absolute, got '${e.path}'`);
-	if (mi.has(e.path)) throw Error(`defineWebSocket: '${e.path}' is the framework's own socket surface — mount the gateway elsewhere`);
+	if (hi.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;
-}, gi = 1;
+}, _i = 1;
 //#endregion
-export { Ne as ADMIN_SCOPE, Oe as APIKEY_ISSUE_ORG_SCOPE, je as APIKEY_ISSUE_OTHER_SCOPE, Ce as APIKEY_ISSUE_SELF_SCOPE, Xr as APPROVALS_DECIDE_TAG, Yr as APPROVALS_PENDING_TAG, Lt as ApprovalDecisionErrors, It as ApprovalErrors, S as ApprovalExpired, Ft as ApprovalForbidden, jt as ApprovalNotFound, Pt as ApprovalNotPending, Nt as ApprovalRejected, At as ApprovalRequired, Mt as ApprovalSelfApproval, C as ApprovalUnavailable, i as AuthMiddleware, Tt as BusinessRuleViolation, Z as CONNECTIONS_LIST_TAG, ti as CONNECTION_DISCONNECT_TAG, $r as CONNECTION_START_TAG, ei as CONNECTION_SUBMIT_TOKEN_TAG, si as ConnectionHandshakeFailed, ae as ConnectionInfo, Te as ConnectionInfoMiddleware, Q as ConnectionKind, oi as ConnectionKindMismatch, ii as ConnectionNotDeclared, ri as ConnectionState, ni as ConnectionStatus, ai as ConnectionSubjectRequired, Jr as ConstraintViolation, t as DEFAULT_SCOPE_CACHE_MAX_ENTRIES, we as DEFAULT_SCOPE_CACHE_TTL_MS, _e as DEVICES_MANAGE_SCOPE, An as EVENT_ROUTE_SEP, Dn as EventKeyInvalid, En as EventPayloadInvalid, On as EventPayloadTooLarge, pi as GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE, re as IMPERSONATION_METADATA_KEY, st as JSONAPI_MEDIA_TYPE, gn as MAX_EVENT_ENVELOPE_BYTES, ft as MUTATION_IN_FLIGHT_RETRY_AFTER_MS, qe as MutationConnectionRequired, dt as MutationInFlight, Wr as NoRowFound, nt as PROBLEM_JSON, gi as PROTOCOL_VERSION, Rt as PendingApproval, w as REACTIVITY_CHANNEL_PREFIX, at as REST_PROFILE_NAMES, f as ScopeError, qr as ServerOnlyColumnWrite, Ur as StoreOperationFailed, ie as Subject, oe as SubjectIdentity, o as SubjectService, Gr as TableValidationFailed, Kr as TenantRowNotFound, Hr as TenantScopeViolation, ge as TenantSelectionRefused, Mr as UNDO_APPLY_TAG, jr as UNDO_LOG_TAG, Nr as UNDO_REDO_TAG, l as Unauthenticated, Lr as UndoConflict, Ir as UndoForbidden, Pr as UndoLogEntry, Fr as UndoNotFound, Dt as ValidationError, Ot as ValidationErrors, Et as ValidationIssue, F as WorkflowAccessProperty, J as WorkflowControlInputSchema, q as WorkflowControlIntentSchema, lr as WorkflowControlReadInputSchema, U as WorkflowControlResultSchema, ir as WorkflowDomainEventRowSchema, sr as WorkflowDomainEventsInputSchema, cr as WorkflowEventDeliveriesInputSchema, ar as WorkflowEventDeliveryRowSchema, Zn as WorkflowParentClosePolicySchema, ur as WorkflowQueuedCancelInputSchema, W as WorkflowQueuedCancellationResultSchema, Y as WorkflowQueuedControlTargetSchema, kr as WorkflowRetryCommandSchema, Ar as WorkflowRetryObservationSchema, Or as WorkflowRetryTargetSchema, rr as WorkflowRunEventRowSchema, $n as WorkflowRunHandleSchema, or as WorkflowRunRefSchema, G as WorkflowRunRowSchema, H as WorkflowRunSnapshotSchema, V as WorkflowRunStatusSchema, nr as WorkflowRunStepRowSchema, K as WorkflowRunTableRefSchema, tr as WorkflowRunsInputSchema, mr as WorkflowSignalInputSchema, Qn as WorkflowStartDeferralSchema, B as WorkflowStartTerminalOutcomeSchema, hr as WorkflowUpdateInputSchema, gr as WorkflowUpdateResultSchema, dn as actionToRpc, Me as advisoryResourceGuardWarning, ne as anonymousSubject, Ct as applyRowPatch, ce as applyScopeDecision, Qr as approvalsDecideDescriptor, Zr as approvalsPendingQueryDescriptor, ze as assertAuthenticated, In as attachWorkflowAccess, Ue as beginIdempotent, Un as checkFrameworkCompat, ve as checkGuards, Ee as checkGuardsEffect, tt as compareSurfaces, n as composeAuthStrategies, Vn as composeRpcInterceptors, di as connectionDisconnectDescriptor, li as connectionStartDescriptor, ui as connectionSubmitTokenDescriptor, ci as connectionsListQueryDescriptor, Gt as declaredReactivityChannelKeys, j as defineAction, vn as defineEvent, A as defineMutation, Rn as definePlugin, zn as definePluginRoute, Hn as definePluginService, k as defineQuery, tn as defineStream, hi as defineWebSocket, xt as diffRows, Pe as effectiveScopes, kn as encodeEventKey, $e as encodeRestError, Ke as encodeRestSuccess, pn as errorTag, xn as eventAttached, yn as eventEnvelope, bn as eventGap, Cn as eventResumePoint, jn as eventRoute, Sn as eventStreamEvent, wn as eventSubscribeInput, Tn as eventToRpc, Be as failIdempotent, kt as fieldIssuesOf, ye as findAdvisoryResourceGuards, ut as finishIdempotent, Nn as formatEventRoute, be as getPolicyGuardResolver, ke as getResourceScopeResolver, I as getWorkflowAccess, Qe as groupShapeDigests, en as hasAccessDecision, fe as hasCallbackRoutes, De as hasEffectiveScope, N as hasEnforcedGuard, Se as hasScope, g as idToPath, We as idempotencyScope, b as inputLabel, xe as isAuthenticatedCheck, $t as isAuthenticatedGuard, _n as isEventDescriptor, St as isIdKeyed, u as isOpenAccess, Fe as isPolicyCheck, Qt as isPolicyGuard, Ut as isReactivityChannel, Wt as isReactivityChannelKey, c as isSystemSubject, se as isTenantSelectable, Xt as isWireReachable, de as makeScopeCache, He as memoryIdempotencyStore, Re as missingAccessDecision, un as mutationToRpc, rt as nextLink, hn as normalizeDescriptor, qt as normalizeSource, d as openAccessSpec, pe as orderByBearerPrefix, Mn as parseEventRoute, yt as pathToId, Gn as pluginAlias, Bn as pluginInstanceName, Kn as pluginSlug, Xn as pluginTag, ot as problemDetails, Je as problemTypeOf, Ze as procedureShapeDigest, Yt as publishReactivity, Xe as publishServerError, ln as queryToRpc, s as rawImpersonationMark, Ht as reactivityChannel, Jn as registerPluginAliases, Le as requireScope, Yn as resetPluginAliases, le as resolvePolicyAction, et as resolveRestFormat, Fn as resolveWorkflowAccess, ct as restViewSchema, _t as rowPatchOpSchema, vt as rowPatchSchema, Ge as schemaShape, te as scopeCacheKey, e as selectSubjectTenant, r as setEffectiveScopes, Ie as setPolicyGuardResolver, ue as setResourceScopeResolver, lt as shapeDigest, Kt as sourceKeys, fn as streamToRpc, x as strictInput, Ae as subjectAuditActorId, ee as subjectIdentity, a as subjectScopes, it as subscribeServerErrors, y as subscriptionEvent, he as systemSubject, me as tenantScopedSubject, mn as toRpc, Ye as toSnakeCase, fi as tsMs, Jt as undeclaredChannelKeys, Br as undoApplyDescriptor, zr as undoLogQueryDescriptor, Vr as undoRedoDescriptor, P as wireErrorUnion, cn as withRpcTag, Ln as workflowAccessDescriptor, Cr as workflowCancelDescriptor, pr as workflowControlQueryDescriptor, xr as workflowDomainEventsQueryDescriptor, Sr as workflowEventDeliveriesQueryDescriptor, dr as workflowQueuedCancelDescriptor, fr as workflowQueuedControlQueryDescriptor, wr as workflowResumeDescriptor, br as workflowRunEventsQueryDescriptor, _r as workflowRunQueryDescriptor, yr as workflowRunStepsQueryDescriptor, vr as workflowRunsQueryDescriptor, Tr as workflowSignalDescriptor, er as workflowToRpc, Er as workflowUpdateDescriptor, sn as workflowWireErrorUnion, Ve as wsMutationIdempotencyScope };
+export { Ne as ADMIN_SCOPE, Oe as APIKEY_ISSUE_ORG_SCOPE, je as APIKEY_ISSUE_OTHER_SCOPE, Ce as APIKEY_ISSUE_SELF_SCOPE, Zr as APPROVALS_DECIDE_TAG, Xr as APPROVALS_PENDING_TAG, Rt as ApprovalDecisionErrors, Lt as ApprovalErrors, S as ApprovalExpired, It as ApprovalForbidden, Mt as ApprovalNotFound, Ft as ApprovalNotPending, Pt as ApprovalRejected, jt as ApprovalRequired, Nt as ApprovalSelfApproval, C as ApprovalUnavailable, i as AuthMiddleware, Et as BusinessRuleViolation, Z as CONNECTIONS_LIST_TAG, ni as CONNECTION_DISCONNECT_TAG, ei as CONNECTION_START_TAG, ti as CONNECTION_SUBMIT_TOKEN_TAG, ci as ConnectionHandshakeFailed, ae as ConnectionInfo, Te as ConnectionInfoMiddleware, Q as ConnectionKind, si as ConnectionKindMismatch, ai as ConnectionNotDeclared, ii as ConnectionState, ri as ConnectionStatus, oi as ConnectionSubjectRequired, Yr as ConstraintViolation, t as DEFAULT_SCOPE_CACHE_MAX_ENTRIES, we as DEFAULT_SCOPE_CACHE_TTL_MS, _e as DEVICES_MANAGE_SCOPE, jn as EVENT_ROUTE_SEP, On as EventKeyInvalid, Dn as EventPayloadInvalid, kn as EventPayloadTooLarge, mi as GATEWAY_CREDENTIAL_EXPIRED_CLOSE_CODE, re as IMPERSONATION_METADATA_KEY, st as JSONAPI_MEDIA_TYPE, _n as MAX_EVENT_ENVELOPE_BYTES, ft as MUTATION_IN_FLIGHT_RETRY_AFTER_MS, qe as MutationConnectionRequired, dt as MutationInFlight, Gr as NoRowFound, nt as PROBLEM_JSON, _i as PROTOCOL_VERSION, zt as PendingApproval, w as REACTIVITY_CHANNEL_PREFIX, at as REST_PROFILE_NAMES, f as ScopeError, Jr as ServerOnlyColumnWrite, Wr as StoreOperationFailed, ie as Subject, oe as SubjectIdentity, o as SubjectService, Kr as TableValidationFailed, qr as TenantRowNotFound, Ur as TenantScopeViolation, ge as TenantSelectionRefused, Nr as UNDO_APPLY_TAG, Mr as UNDO_LOG_TAG, Pr as UNDO_REDO_TAG, l as Unauthenticated, Rr as UndoConflict, Lr as UndoForbidden, Fr as UndoLogEntry, Ir as UndoNotFound, Ot as ValidationError, kt as ValidationErrors, Dt as ValidationIssue, F as WorkflowAccessProperty, J as WorkflowControlInputSchema, q as WorkflowControlIntentSchema, ur as WorkflowControlReadInputSchema, U as WorkflowControlResultSchema, ar as WorkflowDomainEventRowSchema, cr as WorkflowDomainEventsInputSchema, lr as WorkflowEventDeliveriesInputSchema, or as WorkflowEventDeliveryRowSchema, Qn as WorkflowParentClosePolicySchema, dr as WorkflowQueuedCancelInputSchema, W as WorkflowQueuedCancellationResultSchema, Y as WorkflowQueuedControlTargetSchema, Ar as WorkflowRetryCommandSchema, jr as WorkflowRetryObservationSchema, kr as WorkflowRetryTargetSchema, ir as WorkflowRunEventRowSchema, er as WorkflowRunHandleSchema, sr as WorkflowRunRefSchema, G as WorkflowRunRowSchema, H as WorkflowRunSnapshotSchema, V as WorkflowRunStatusSchema, rr as WorkflowRunStepRowSchema, K as WorkflowRunTableRefSchema, nr as WorkflowRunsInputSchema, hr as WorkflowSignalInputSchema, $n as WorkflowStartDeferralSchema, B as WorkflowStartTerminalOutcomeSchema, gr as WorkflowUpdateInputSchema, _r as WorkflowUpdateResultSchema, fn as actionToRpc, Me as advisoryResourceGuardWarning, ne as anonymousSubject, Ct as applyRowPatch, ce as applyScopeDecision, $r as approvalsDecideDescriptor, Qr as approvalsPendingQueryDescriptor, ze as assertAuthenticated, Ln as attachWorkflowAccess, Ue as beginIdempotent, Wn as checkFrameworkCompat, ve as checkGuards, Ee as checkGuardsEffect, tt as compareSurfaces, n as composeAuthStrategies, Hn as composeRpcInterceptors, fi as connectionDisconnectDescriptor, ui as connectionStartDescriptor, di as connectionSubmitTokenDescriptor, li as connectionsListQueryDescriptor, Kt as declaredReactivityChannelKeys, j as defineAction, yn as defineEvent, A as defineMutation, zn as definePlugin, Bn as definePluginRoute, Un as definePluginService, k as defineQuery, nn as defineStream, gi as defineWebSocket, xt as diffRows, Pe as effectiveScopes, An as encodeEventKey, $e as encodeRestError, Ke as encodeRestSuccess, mn as errorTag, Sn as eventAttached, bn as eventEnvelope, xn as eventGap, wn as eventResumePoint, Mn as eventRoute, Cn as eventStreamEvent, Tn as eventSubscribeInput, En as eventToRpc, Be as failIdempotent, At as fieldIssuesOf, ye as findAdvisoryResourceGuards, ut as finishIdempotent, wt as firstEventValue, Pn as formatEventRoute, be as getPolicyGuardResolver, ke as getResourceScopeResolver, I as getWorkflowAccess, Qe as groupShapeDigests, tn as hasAccessDecision, fe as hasCallbackRoutes, De as hasEffectiveScope, N as hasEnforcedGuard, Se as hasScope, g as idToPath, We as idempotencyScope, b as inputLabel, xe as isAuthenticatedCheck, en as isAuthenticatedGuard, vn as isEventDescriptor, St as isIdKeyed, u as isOpenAccess, Fe as isPolicyCheck, $t as isPolicyGuard, Wt as isReactivityChannel, Gt as isReactivityChannelKey, c as isSystemSubject, se as isTenantSelectable, Zt as isWireReachable, de as makeScopeCache, He as memoryIdempotencyStore, Re as missingAccessDecision, dn as mutationToRpc, rt as nextLink, gn as normalizeDescriptor, Jt as normalizeSource, d as openAccessSpec, pe as orderByBearerPrefix, Nn as parseEventRoute, yt as pathToId, Kn as pluginAlias, Vn as pluginInstanceName, qn as pluginSlug, Zn as pluginTag, ot as problemDetails, Je as problemTypeOf, Ze as procedureShapeDigest, Xt as publishReactivity, Xe as publishServerError, un as queryToRpc, s as rawImpersonationMark, Ut as reactivityChannel, Yn as registerPluginAliases, Le as requireScope, Xn as resetPluginAliases, le as resolvePolicyAction, et as resolveRestFormat, In as resolveWorkflowAccess, ct as restViewSchema, _t as rowPatchOpSchema, vt as rowPatchSchema, Ge as schemaShape, te as scopeCacheKey, e as selectSubjectTenant, r as setEffectiveScopes, Ie as setPolicyGuardResolver, ue as setResourceScopeResolver, lt as shapeDigest, qt as sourceKeys, pn as streamToRpc, x as strictInput, Ae as subjectAuditActorId, ee as subjectIdentity, a as subjectScopes, it as subscribeServerErrors, y as subscriptionEvent, he as systemSubject, me as tenantScopedSubject, hn as toRpc, Ye as toSnakeCase, pi as tsMs, Yt as undeclaredChannelKeys, Vr as undoApplyDescriptor, Br as undoLogQueryDescriptor, Hr as undoRedoDescriptor, P as wireErrorUnion, ln as withRpcTag, Rn as workflowAccessDescriptor, wr as workflowCancelDescriptor, mr as workflowControlQueryDescriptor, Sr as workflowDomainEventsQueryDescriptor, Cr as workflowEventDeliveriesQueryDescriptor, fr as workflowQueuedCancelDescriptor, pr as workflowQueuedControlQueryDescriptor, Tr as workflowResumeDescriptor, xr as workflowRunEventsQueryDescriptor, vr as workflowRunQueryDescriptor, br as workflowRunStepsQueryDescriptor, yr as workflowRunsQueryDescriptor, Er as workflowSignalDescriptor, tr as workflowToRpc, Dr as workflowUpdateDescriptor, cn as workflowWireErrorUnion, Ve as wsMutationIdempotencyScope };

package/dist/rest.d.ts

@@ -1289,6 +1289,9 @@ export declare interface RestRouteContext {
      *  REST handlers on the same capability surface as query/mutation/action
      *  handlers without creating a protocol-to-runtime package dependency. */
     readonly app?: unknown;
+    /** The caller's address, resolved through `security.trustedProxies` — the
+     *  value the listener's per-IP shield counts. Absent when unknown. */
+    readonly remoteAddr?: string;
 }
 
 export declare interface RestRouteDescriptor<I, O> {

package/dist/rest.js

@@ -519,7 +519,8 @@ var w = (e, t, n) => t.method ?? (t.resource !== void 0 && n !== void 0 ? D("",
 				path: l.path,
 				query: l.query,
 				rawBody: l.rawBody,
-				..._ === void 0 ? {} : { app: _ }
+				..._ === void 0 ? {} : { app: _ },
+				...l.remoteAddr === void 0 ? {} : { remoteAddr: l.remoteAddr }
 			};
 			if (a.guards) for (let e of a.guards) {
 				let t = await e(x);

package/package.json

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