@voltro/protocol 0.69.1 → 0.70.0

package/CHANGELOG.md

@@ -39,6 +39,86 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.70.0] — 2026-09-11
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — The DevTools dashboard has a lock of its own: `VOLTRO_DASHBOARD_TOKEN`. A deployed dashboard that holds other apps' inspect tokens in `VOLTRO_DASHBOARD_APPS` refuses to boot in production without it, `/api/dashboard/config` no longer serves token values, and the proxy attaches a configured target's credentials itself.
+
+  Before this the dashboard had no door: whoever reached its URL got every configured app's inspect read AND write token from `/api/dashboard/config` in one request, and the proxy forwarded whatever bearer that browser then presented. The URL was the credential.
+
+  Three rules now, on both boot paths: the browser proves the dashboard token once (`POST /api/dashboard/login`) and gets an HttpOnly, SameSite=Strict session cookie derived from it by HMAC (12 h; a rotated lock invalidates every cookie); every other `/api/dashboard/*` route answers 401 without a session; the config route says where the targets are and whether the pod holds credentials (`hasToken`, `hasWriteToken`), never which. A dashboard with nothing to guard (no configured targets, a loopback dev registry) boots open as before — setting the token locks it anyway. `voltro secret generate dashboard` prints the variable paste-ready. `codemod: none`: no user code changes; the operator sets one variable, and the chart's `dashboardToken` renders it.
+
+  **No codemod** — this break touches no user-authored code.
+
+### Added
+
+- **@voltro/protocol, @voltro/plugin-openapi, @voltro/cli, @voltro/testing** — The `publicApi` surface speaks a REST profile, chosen once in the api's `app.config.ts` (`publicApi: { profile }`) and overridable per descriptor (`publicApi.format`): `'rpc'` — the default, today's wire — `'standard'`, `'jsonapi'`, or a `RestFormat` object of the app's own, with building blocks (`dates`, `errors`, `envelope`, `pagination`, `naming`, `etag`) that override the preset. `'standard'` is the Zalando / Google AIP / Microsoft intersection: `timestampMs` as RFC 3339 (accepted inbound too), every failure as RFC 9457 Problem Details — the transport's refusals included — no envelope, a `nextCursor` as a `Link: <…>; rel="next"` header, a weak `ETag` on GET with `If-None-Match` → 304. `'jsonapi'` answers `{ data, links }` as `application/vnd.api+json`. The spec follows the profile (`format: date-time`, the `ProblemDetails` component, `Link`/`ETag` headers, snake-case names). `makeTestApp({ publicApiProfile })` measures the same wire.
+
+  A path with `{teamId}` or `:teamId` binds that segment to the input field of the same name — always, under every profile — with the remaining fields from the query string (GET) or the body; the brace form used to be no route, the colon form a `400`, so `GET /v1/teams/{teamId}` was unreachable for a projection.
+- **@voltro/testing, @voltro/database** — `makeTestContext({ fieldEncryptionKey })` registers the field cipher for `.encrypted()` columns under test. Setting `VOLTRO_FIELD_ENCRYPTION_KEY` — in `process.env` or the context's `env` — did nothing here, because the harness runs no boot gate and the gate is what turns the variable into a cipher; the only working route was `setFieldCipher(makeFieldCipher(key))` from another package, which nothing pointed at. The refusal now names the option.
+- **@voltro/database, @voltro/runtime** — `insertIgnoreWithOutcome` on the framework store (and on `yield* EffectStore` plus the `tx` view), with the typed helper `insertIgnoreRowOutcome`: `{ row, outcome: 'inserted' | 'ignored' }`.
+
+  `insertIgnore` returns the existing row on the ignore path, and that row is indistinguishable from one it just wrote — so a loop that plants missing rows reported every row it visited as planted unless it read the destination first, per row. The answer is decided the way `upsertWithOutcome` decides it: the id the store minted before the statement is not the id the ignore path hands back; where the id cannot decide (caller-supplied, or database-assigned) the destination is read first and the answer stays exact. Plain `insertIgnore` never pays for that read.
+- **@voltro/protocol, @voltro/client, @voltro/web** — `defineMutation({ serialize: { key, maxPending? } })` — calls of one mutation to the SAME resource run in invocation order on the client, for every caller of the tag. A row lock serialises transactions, not the order a browser invoked them in: two quick saves of one snapshot could take the lock in reverse order and the older snapshot then overwrote the newer one; server-side idempotency does not see it, and `.version()` detects the conflict and replays the older write. `key` names the resource from the input; calls sharing it run one at a time, FIFO, per subject, the permit spanning connection setup, the request, replay and its acknowledgement — optimistic previews stay immediate, different keys run independently. An unknown outcome (a transport failure after the request started) blocks the key for that subject rather than let a later write pass it; a subject change drops the queue; admission beyond `maxPending` (default 32) rejects with `MutationSerialExecutionError`. `useMutation`'s `pending` now counts every concurrent call, not only the one that settled last.
+
+  Declared on the descriptor — where `concurrency` lives for workflows — rather than as a hook builder, because a hook-scoped queue orders one component's calls and lets a second component writing the same resource interleave. Not a durable outbox, a distributed lock or a cross-tab merge.
+- **@voltro/cli** — API `fonts:` declarations now package validated native-readable fonts and relocatable Fontconfig artifacts during build. Dev, serve and direct production entries activate them before startups and handlers; missing or corrupt artifacts refuse boot. Native renderers no longer depend on undeclared host fonts or original workspace font paths.
+- **@voltro/plugin-openapi** — Every mounted API version has an OpenAPI document of its own — `/openapi/v2.json` beside `/openapi.json`, or `?version=v2` — the same spec filtered to that version, every operation fact included; the unversioned URL keeps serving everything. With more than one version mounted the docs page shows Swagger UI's "Select a definition" dropdown: one entry per version, newest first and preselected, an expiring version named with its earliest `sunset` (`v1 — sunset 2027-03-01`), the whole document last.
+
+  Before this `v1` and `v2` shared one document and one viewer: a consumer integrating `v2` scrolled past every `v1` path, and a generator built both into one client.
+- **@voltro/protocol, @voltro/cli, @voltro/plugin-openapi** — `onProcedureSurface` — a plugin hook told the app's wire-reachable rpc procedures (every query, mutation, action and stream discovery found, minus `internal`) once discovery has run, on both boot paths; the procedure counterpart of `onRestSurface`. `openapiPlugin({ includeAppProcedures: true })` documents them as `POST /rpc/<name>` operations without the app listing them: opt-in, so the spec stays REST-only unless asked, and a procedure also passed in `procedures` is documented once.
+
+  Before this `procedures` was the only way in, and filling it meant importing every descriptor module into `app.config.ts` — evaluated before discovery on every load of the config, the pattern the `onRestSurface` docs name as a boot that hung — while `voltro serve` loads no TypeScript at runtime, so a plugin could not read them later either.
+- **@voltro/protocol, @voltro/plugin-openapi** — A `publicApi` projection documents itself completely: `tags` from the rpc tag's prefix (`teams.list` → `teams`; `publicApi.tags` overrides) with a top-level `tags[]` and `tagDescriptions` on the OpenAPI plugin; an `operationId` from the tag (`teamsList`; `publicApi.operationId` overrides); `security` on every operation — required, or optional under `openAccess` (`[{ bearerAuth: [] }, {}]`), `publicApi.security: false` for none — with `securitySchemes.bearerAuth` published once any projection exists; one response per `errorStatus` entry carrying the error's own schema, `422` for the union's other tags, `429` for a mounted rate limiter; `publicApi.example: { request?, response? }`; path parameters `in: path` and query parameters typed from the input.
+
+  Before this the plugin wrote `tags` only for an explicit `version`, `security` only for a `guards:` route — so after "Authorize" Swagger UI sent the token to those alone and "Try it out" on every other route ran without a key — no `operationId`, no `errorStatus` response, no example, and no query parameter at all for a GET projection.
+
+### Fixed
+
+- **@voltro/protocol** — A `publicApi.path` segment that names no input field refuses the boot, naming the descriptor and the segment (`descriptor 'bookings.get' — path '/v1/bookings/:uuid' binds ':uuid', and the input declares no field of that name (fields: bookingId)`). A field the path binds may repeat in the body or query string with the same value — a PATCH carrying the whole resource — but another value answers `400` naming the field.
+
+  Before this the segment was bound silently: the route mounted, the handler never saw the value, and a body that carried the same field with another value was overwritten by the path without a word.
+- **@voltro/protocol, @voltro/runtime, @voltro/plugin-openapi, @voltro/plugin-prometheus** — A plugin route answers the path it declared, byte for byte: the dispatcher refuses a request whose path is not the route's own — case-folded twins and a bare trailing slash included — with `404`, before the body is read. `PluginHttpRoute.match: 'exact'` narrows a route to its path alone, no sub-path; the default stays `'prefix'`, the contract every route that branches on its tail was written against. A REST descriptor is an exact route; the OpenAPI spec and docs routes and the Prometheus scrape route declare `'exact'`.
+
+  Before this the router matched without case and ignored a trailing slash, and every route owned its sub-paths: `/OPENAPI.JSON`, `/openapi.json/`, `/Docs` and `/Metrics` all answered, so a path guard at the ingress that named the one documented spelling covered none of the others. The docs of both plugins now say the guard can name the path as written.
+- **@voltro/workflow, @voltro/cli** — A run that ended outside the engine no longer leaves its unanswered requests in the cluster journal. Cancelling a run (`timeouts.finish`, `cancelOn`, the operator's button, the bulk action) discards its unprocessed messages at once, and the staleness tick discards those of every ended run (`succeeded`, `failed`, `cancelled`) that a runner last read more than a minute ago — logged as `workflow.cluster: discarded unprocessed messages of runs that have ended`.
+
+  Before this, the `activity` request a killed executor was inside stayed unprocessed after the run was cancelled: every runner that acquired the shard re-read it every ten minutes for the rest of time, its handler waited on a latch that never opens, and the `unprocessed messages` warning was printed again on every engine start. An unprocessed `run` request of a cancelled run would have gone further and executed it. The engine's own reset deletes one request; this deletes the ended run's, and `ClusterDiagnostics.discardMessages` is the one write on that service.
+- **@voltro/cli** — `voltro db encrypt-column <table>.<column> .` accepts the app directory every other `db` command takes as its last argument — accepted and not needed, the connection comes from env. It used to parse `.` as a column reference and refuse. A positional that is neither a `<table>.<column>` nor a directory is named in the refusal.
+- **@voltro/runtime, @voltro/cli, @voltro/database** — Every API key has its `actors` row after the first boot on this version. Both boot paths plant, after the schema is applied, one row per `_voltro_api_keys.id` that has none — through the same `ensureActor` a new key goes through (the built-in row, or the app's `apiKeys.ensureActor` handed the issue input rebuilt from the row). Idempotent; two queries when nothing is missing; `api keys: planted actors rows for keys that had none` with the count, and a key whose row cannot be written is named in a warning rather than failing the boot.
+
+  Two release notes had asked the operator to run a loop once. The first was printed to the wrong group; the second printed `store.select(...)` for a `*.startup.ts`, and `StartupContext.store` is a `DataStore` with no fluent builder — both API pods refused to boot on it. The 0.69.1 note now says what the boot does and which line to look for. The framework tables `@voltro/database` exports (`_voltroApiKeysTable` and the others) are typed `SchemaTable` instead of `TableLike`, so `queryFor(_voltroApiKeysTable)` compiles where a hand-written read is still wanted.
+- **@voltro/runtime** — Idempotent WebSocket mutations acquire and finalize their claims safely across request interruption. A closed socket cannot orphan a claim acquired by a still pending store Promise; synchronous executor failures release fresh claims too. Already-started Promise executors finish their actual write and record the result before interruption completes, preventing a replay from duplicating the write. Effect executors remain interruptible and release only after cleanup. A late interrupt never deletes the completion receipt of a successful write.
+
+  Codemod: none — no application source or configuration changes. Claim TTL, replay limits, transport guards and process-crash recovery guarantees are unchanged.
+- **@voltro/cli** — Docker deployments retain optional native platform bindings until runtime tracing, and the pruner traces both conditional import and require entries so relocated API and web images can still execute native image processing.
+- **@voltro/workflow, @voltro/cli** — `own` on a shard-lock holder in the stall report and the `workflow.cluster` warning is now the engine's own account (`Sharding.hasShardId`), and a holder that is this runner reads `this runner (pid N)`.
+
+  The first version compared the holder's pid with `pg_backend_pid()` of the query that asked. The advisory lock lives on the runner's reserved connection, and the pool hands every other query a different backend — so a runner's own 300 locks read as a stranger's, always, and behind a connection pooler nothing in `pg_stat_activity` could have told them apart either. The report's stated lever for a stranger, ending the holder's session, would have ended the runner. The hint now distinguishes the three cases (another runner, a session that outlived its runner, this runner re-reading a request nobody answers), and the docs say to read `own` before `pg_terminate_backend`.
+- **@voltro/cli** — Production HTTP proxies release upstream resources when the browser abandons an unfinished response, including SSE, and propagate truncated upstream responses as transport failures instead of hanging. Complete responses retain payloads and keep-alive; no application configuration change is needed.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/testing, @voltro/plugin-ratelimit** — `publicApi.rateLimit` on a descriptor is that endpoint's own rule for calls through the `/v1` projection — ahead of the plugin's `rules` and `default`, one bucket per caller per endpoint, under `enabled`. A REST call now carries `surface: 'rest'` and the descriptor's `publicApi` spec on the interceptor context, so a plugin can tell a projected call from an rpc one.
+
+  The field said "rides @voltro/plugin-ratelimit when mounted" and nothing read it: three calls at `limit: 1` answered `200 200 200`, no bucket, no `onLimited`. The plugin never learned which calls came through the projection, let alone what it declared. Without the plugin mounted the spec is inert, as the comment always implied.
+- **@voltro/cli** — The retention sweep arms its policies on the `_voltro_workflow_*` tables only where the workflow engine that creates those tables is composed. An api with no `*.workflow.tsx` has no engine and no such tables, and the five policies still armed on them were five failing `DELETE`s per tick, each an `ERROR` line in the database log, for the life of the deployment — not switchable off from the app. The boot line `retention: N policy(ies) armed` now lists exactly what is swept.
+- **@voltro/plugin-mail** — SMTP replies are classified by SMTP rules instead of HTTP rules: 4xx replies remain retryable, permanent 5xx rejections do not trigger automatic retries (RFC 5321 §4.2.1). HTTP providers keep their existing policy. Tests exercise actual loopback connections, envelope, MIME and attachment encoding without sending external mail.
+
+  Codemod: none — corrected SMTP reply semantics require no application source or configuration migration.
+- **@voltro/workflow** — The workflow engine's boot check for its cluster tables asks whether a table exists with a query that succeeds either way (`to_regclass` on postgres, `information_schema` on mysql, `OBJECT_ID` on mssql, `sqlite_master` on sqlite) instead of selecting from the table and reading the failure as "no" — which the database server logged as an `ERROR` on every first boot of a database. The probes `@effect/cluster` itself makes for its legacy tables are upstream and still fail-as-answer.
+- **@voltro/cli** — `voltro dev` acquires the workflow runtime as a boot step, as `voltro serve` always has — `workflow runtime ready — N entity type(s) registered` on both paths, through one shared helper with a parity test.
+
+  A `ManagedRuntime` builds its layer on first use, and `voltro dev` never used it at boot. A fleet of dev pods therefore had NO cluster runner after a restart — no runner row, no shard locks, no re-delivery — until something asked the runtime for a service. The first thing that asked, in a deployment, was the once-per-fleet staleness tick, five minutes after the boot, in the one pod that ran it: a run orphaned by the restart waited exactly that long and was then adopted by that pod alone.
+- **@voltro/cli** — `voltro baseline sync` writes its `docker/Caddyfile` with tabs, the way `caddy fmt` writes it. Caddy warned on every proxy start that the file "is not formatted", and a project that checks its generated files for drift could not fix it on its side — the next sync undid it.
+- **@voltro/plugin-ratelimit** — `redisStore({ url })` binds its client on the first `consume` when nobody activated it — from `url` or the env it reads at activation — so a limit holds in the test harness, where `makeTestContext` runs no lifecycle hooks. A store with neither stays fail-open (`failOpenReason: 'unbound'`), as at activation.
+
+  Before this a suite that "checked the redis store" ran every call through an unbound store: `200 200 200` at `limit: 2`, no key in Redis, no warning — and nothing a test could read told "the limit held" from "the store was never there".
+- **@voltro/cli, @voltro/i18n** — A `src/pages/[locale]/…` route renders in the locale it matched, on both web boot paths: `voltro start` and `voltro dev` hand the matched `[locale]` parameter to the same i18n resolver (also for the ISR key and for an app without catalogs), and `resolveLocale` takes it as `routeLocale` — ahead of the `voltro:locale` cookie, `Accept-Language` and the default, and only on an exact supported spelling. The build's static prerender already did this; the runtime render fell back to cookie or browser language, so `/en` answered with a German head and `html lang="de"`. In the same change `voltro dev`'s buffered SPA and ISR responses merge a page's `meta.title` into the shell the way production does — there was a second `<title>` before.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/testing, @voltro/plugin-ratelimit** — A rate-limited call on the `/v1` projection answers `429` with `Retry-After` and the `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers, the tag and fields as the body — on both boot paths and in `makeTestApp`. A `PluginErrorSchema` may declare `rest: { status, headers }`; the projection encodes a plugin's cross-cutting error under that status (`422` when it names none; the descriptor's own `errorStatus` entry wins), and the plugin declares `429` for `RateLimited`.
+
+  The plugin merged `RateLimited` into every rpc's wire union at boot and the client decoded it typed, but the REST projection encoded through the descriptor's own `error:` union only — the one surface with no typed channel to fall back on answered `500 Internal Server Error` with no `Retry-After`. The only way to a `429` was to import a plugin error into every descriptor file. A `500`'s cause now rides on the response value off the wire, so the `GET /v1/… → 500` log line names the reason on `voltro serve` too.
+
+---
+
 ## [0.69.1] — 2026-09-11
 
 ### Added

package/dist/index.d.ts

@@ -761,6 +761,8 @@ export declare interface ClientDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
     /** Mutation only: connection setup hooks require an explicit connection scope. */
     readonly idempotencyScope?: MutationIdempotencyScope | undefined;
+    /** Mutation only: same-key calls run in invocation order on the client. */
+    readonly serialize?: MutationSerialization | undefined;
     /** Query only: table(s) the cache should match this subscription against. */
     readonly source?: string | ReadonlyArray<string> | undefined;
     /** Mutation only: tables this mutation writes, with op. */
@@ -1549,6 +1551,26 @@ export declare const defineMutation: <const Name extends string, Input extends S
      * never ordinary business writes. Requires a live WebSocket even when dedup
      * is disabled; internal/public REST/agent-tool projections are refused. */
     readonly idempotencyScope?: MutationIdempotencyScope;
+    /**
+     * Run this mutation's calls to the SAME resource in invocation order, on the
+     * client — for every caller of the tag, not one hook.
+     *
+     * A row lock serialises transactions, not the order a browser invoked them
+     * in: two quick saves of one snapshot can take the lock in reverse order, and
+     * the older snapshot then overwrites the newer one; server-side idempotency
+     * does not see it, and `.version()` detects the conflict and replays the
+     * OLDER write. `key` names the resource from the input; calls sharing a key
+     * run one at a time, FIFO, per subject, the permit spanning connection
+     * setup, the request, replay and its acknowledgement — optimistic previews
+     * stay immediate. Different keys run independently. An unknown outcome (a
+     * transport failure after the request started) blocks the key for that
+     * subject rather than let a later write pass it; a subject change drops the
+     * queue. `maxPending` bounds active plus waiting calls per subject (default
+     * 32); admission beyond it rejects with `MutationSerialExecutionError`.
+     * Declared here, on the mutation, so every `useMutation` of it orders the
+     * same way. Not a durable outbox, a distributed lock or a cross-tab merge.
+     */
+    readonly serialize?: MutationSerialization<Schema.Schema.Type<Input>>;
     /** Optional declarative target(s) — drives auto-optimistic. */
     readonly target?: Target<Schema.Schema.Type<Input>, Schema.Schema.Type<Output>>;
     /** Declarative authorization guard(s) — the caller must hold the named
@@ -1858,6 +1880,17 @@ export declare const effectiveScopes: (subject: Subject) => ReadonlyArray<string
  */
 export declare const encodeEventKey: (key: unknown) => string;
 
+/** Encode a failure under `format`: the tagged body the desugar always wrote
+ *  (`{ error, …fields }`), Problem Details, or the format's own encoder. */
+export declare const encodeRestError: (format: RestFormat, error: RestFormatError, ctx: RestFormatContext) => RestFormatResponse;
+
+/**
+ * Encode a success value under `format`: the bare value, `{ data, next? }`, or
+ * a JSON:API document; a cursor becomes a `Link` header under `link-header`.
+ * `value` is already in wire form (dates, naming applied by `restViewSchema`).
+ */
+export declare const encodeRestSuccess: (format: RestFormat, value: unknown, ctx: RestFormatContext) => RestFormatResponse;
+
 /**
  * Read the `_tag` off a thrown error value, or `undefined` when it has none.
  *
@@ -2607,6 +2640,8 @@ export declare const isWireReachable: (descriptor: {
     readonly internal?: boolean | undefined;
 }) => boolean;
 
+export declare const JSONAPI_MEDIA_TYPE = "application/vnd.api+json; charset=utf-8";
+
 /**
  * Build a scope cache. Hand it to `composeAuthStrategies({ scopeCache })` and
  * keep the handle: `invalidate(scopeCacheKey(subject))` from the mutation that
@@ -2686,6 +2721,8 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
      * re-executes on a new server-owned WebSocket identity and rejects HTTP RPC.
      * This does not grant access or restore application membership by itself. */
     readonly idempotencyScope?: MutationIdempotencyScope | undefined;
+    /** Same-key calls run in invocation order on the client — see `defineMutation`. */
+    readonly serialize?: MutationSerialization<Schema.Schema.Type<Input>> | undefined;
     /** Declarative target(s) — drives auto-optimistic on the client AND
      *  surfaces which tables this mutation touches (debug, future
      *  query-invalidation analytics). Mutations without a target run
@@ -2734,6 +2771,14 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
     readonly internal: boolean | undefined;
 }
 
+/** Same-resource ordering for a mutation's calls on the client — see `defineMutation`'s `serialize`. */
+export declare interface MutationSerialization<Input = unknown> {
+    /** The resource a call writes, from its input; calls sharing it run in order. */
+    readonly key: (input: Input) => string;
+    /** Bound for active plus waiting calls per subject. Default 32. */
+    readonly maxPending?: number;
+}
+
 export declare const mutationToRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: MutationProcedureDescriptor<Name, Input, Output, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never>;
 
 export declare interface NestedTargetFields<Input = unknown> {
@@ -2751,6 +2796,10 @@ export declare interface NestedTargetFields<Input = unknown> {
     readonly match?: ((value: unknown, input: Input) => boolean) | undefined;
 }
 
+/** `Link: <path?cursor=…>; rel="next"` — the current query with the cursor
+ *  parameter replaced. */
+export declare const nextLink: (ctx: RestFormatContext, cursor: string, param: string) => string;
+
 /**
  * Project a runtime descriptor down to the subset the client needs.
  * Functions (`shape`, `identify`) are passed through by reference —
@@ -3310,6 +3359,20 @@ export declare interface PluginErrorSchema {
         readonly module: string;
         readonly name: string;
     };
+    /**
+     * How the `publicApi` REST projection answers this error. The projection
+     * encodes a plugin's cross-cutting error the way it encodes a descriptor's
+     * own declared error — tag and fields as the body — under this status
+     * (`422` when absent, the status an undeclared-status descriptor error
+     * gets), with these headers. A rate limiter names `429` and the
+     * `Retry-After` / `RateLimit-*` headers here; a descriptor's own
+     * `errorStatus` entry for the tag still wins. Without this the same
+     * rejection that decoded typed on the rpc wire was a `500` on `/v1`.
+     */
+    readonly rest?: {
+        readonly status: number;
+        readonly headers?: (error: unknown) => Readonly<Record<string, string>>;
+    };
 }
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
@@ -3319,9 +3382,22 @@ export declare interface PluginHttpRoute {
      *  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`). */
+    /** Absolute path, e.g. `/_voltro/storage`. Matched byte for byte: the
+     *  router folds case and a trailing slash to FIND the route, the dispatcher
+     *  then asks whether the request's path is one the route declared — so
+     *  `/Metrics` and `/metrics/` are not `/metrics`. A `:name` segment takes one
+     *  non-empty segment. Whether the route also owns its sub-paths is
+     *  `match`. */
     readonly path: string;
+    /**
+     * `'prefix'` (default): the route answers its path AND every sub-path
+     * (`/_voltro/storage/abc123`) — a plugin that branches on the tail mounts
+     * once. `'exact'`: the path alone — no sub-path, no trailing slash — which is
+     * what a single document or a scrape endpoint is (`/openapi.json`,
+     * `/metrics`), and what a path guard at the ingress can cover, because
+     * exactly one spelling answers. A path ending in `/*` is a prefix either way.
+     */
+    readonly match?: 'prefix' | 'exact';
     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
@@ -3518,6 +3594,13 @@ export declare interface PluginHttpRouteResult {
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
+    /**
+     * The error behind a `5xx` — for the server log line that names the
+     * status, never for the wire. A route that maps a throw into a response
+     * value has swallowed the reason by the time the transport logs the value;
+     * this carries it alongside.
+     */
+    readonly cause?: unknown;
     /** 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
@@ -4052,6 +4135,16 @@ export declare interface PolicyGuardSpec<Input = unknown> {
     readonly resource: (input: Input) => string | undefined;
 }
 
+export declare const PROBLEM_JSON = "application/problem+json; charset=utf-8";
+
+/** RFC 9457 Problem Details for one failure: `type` from the tag, `title` from
+ *  the tag's words, `status`, `detail` from the message, the error's own fields
+ *  as extension members. */
+export declare const problemDetails: (error: RestFormatError) => Record<string, unknown>;
+
+/** A stable, non-resolving URI for an error type: the tag as a URN. */
+export declare const problemTypeOf: (tag: string) => string;
+
 export declare type ProcedureDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | StreamProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 
 /** The shape of one procedure, as the pair of peers must agree on it. */
@@ -4074,6 +4167,23 @@ export declare const PROTOCOL_VERSION: 1;
 
 export declare type ProtocolVersion = typeof PROTOCOL_VERSION;
 
+/** The `publicApi:` block of an api `app.config.ts`, and the shape of a
+ *  descriptor's `publicApi.format` override (every field optional there). */
+export declare interface PublicApiProfileConfig {
+    /** The profile every projection speaks. Default `'rpc'` — today's wire. */
+    readonly profile?: PublicApiProfileName | RestFormat;
+    readonly dates?: RestDates;
+    readonly errors?: RestErrors;
+    readonly envelope?: RestEnvelope;
+    readonly pagination?: RestPagination;
+    readonly cursorField?: string;
+    readonly cursorParam?: string;
+    readonly naming?: RestNaming;
+    readonly etag?: boolean;
+}
+
+export declare type PublicApiProfileName = 'rpc' | 'standard' | 'jsonapi';
+
 export declare interface PublicApiSpec {
     /** Derived by kind when omitted: query→GET, mutation/action→POST. */
     readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -4110,6 +4220,37 @@ export declare interface PublicApiSpec {
      *     publicApi: { errorStatus: { AccessDeniedError: 403, NotFoundError: 404 } }
      */
     readonly errorStatus?: Readonly<Record<string, number>>;
+    /**
+     * The spec's tag group(s) for this operation. Default: the rpc tag's prefix
+     * (`teams.list` → `teams`) — the first path segment, what a consumer looks
+     * for, and what an SDK generator turns into a client class.
+     */
+    readonly tags?: ReadonlyArray<string>;
+    /**
+     * The spec's `operationId`. Default: the rpc tag in camelCase (`teams.list`
+     * → `teamsList`) — the stable identifier a generator names methods from.
+     */
+    readonly operationId?: string;
+    /**
+     * Whether the operation documents a bearer requirement. Default: `'required'`
+     * unless the descriptor declares `openAccess` — then `'optional'` (the key
+     * strategy authenticates a bearer when one is sent, and an anonymous caller
+     * is allowed through), which Swagger UI and generated clients read as
+     * "send the token when you have one". `false` documents no scheme at all.
+     */
+    readonly security?: 'required' | 'optional' | false;
+    /** A request/response example for the spec — the same semantics as a
+     *  `defineRestRoute` example. */
+    readonly example?: {
+        readonly request?: unknown;
+        readonly response?: unknown;
+    };
+    /**
+     * This projection's wire format, overriding the app's `publicApi` profile
+     * (`app.config.ts`) for the one endpoint that must differ — every field
+     * optional, the rest inherited. See `PublicApiProfileConfig`.
+     */
+    readonly format?: PublicApiProfileConfig;
 }
 
 /**
@@ -4377,6 +4518,14 @@ export declare const requireScope: (subject: Subject, scope: string) => Effect.E
 /** Drop every registration. Tests only — production registers once at module load. */
 export declare const resetPluginAliases: () => void;
 
+/**
+ * The format one projection speaks: the app profile, then its building-block
+ * overrides, then the descriptor's own `format`. A named profile is a
+ * `RestFormat` with a name; an object is taken as-is and its fields overridden
+ * the same way.
+ */
+export declare const resolveRestFormat: (config: PublicApiProfileConfig | undefined, override?: Partial<PublicApiProfileConfig> | undefined) => RestFormat;
+
 /**
  * Validate an author's access options and normalise them into the array every
  * enforcement path reads. Throws at DEFINITION time — module load, which is
@@ -4404,6 +4553,85 @@ export declare interface ResourceScopeRequest {
  */
 export declare type ResourceScopeResolver = (req: ResourceScopeRequest) => Effect.Effect<boolean, unknown>;
 
+export declare const REST_PROFILE_NAMES: ReadonlyArray<PublicApiProfileName>;
+
+export declare type RestDates = 'iso' | 'epoch-ms';
+
+export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
+
+export declare type RestErrors = 'problem-details' | 'tagged';
+
+/**
+ * The wire format of one `publicApi` surface. `'standard'` and `'jsonapi'` are
+ * named instances of this; an app's own object is the custom case.
+ */
+export declare interface RestFormat {
+    readonly name: string;
+    /** `timestampMs` fields: RFC 3339 strings, or the epoch milliseconds the rpc wire carries. */
+    readonly dates: RestDates;
+    /** Failures: RFC 9457 `application/problem+json`, or the tagged object rpc carries. */
+    readonly errors: RestErrors;
+    /** Success bodies: the bare value, `{ data }`, or the JSON:API document. */
+    readonly envelope: RestEnvelope;
+    /** A cursor the handler returns in `cursorField`: as a `Link: <…>; rel="next"`
+     *  header (and `next` beside `data`), or left where the handler put it. */
+    readonly pagination: RestPagination;
+    /** The cursor field a paginated output carries. Default `nextCursor`. */
+    readonly cursorField: string;
+    /** The query parameter a cursor travels back in. Default `cursor`. */
+    readonly cursorParam: string;
+    /** Property names on the wire. */
+    readonly naming: RestNaming;
+    /** Weak `ETag` on GET answers, `If-None-Match` → 304. */
+    readonly etag: boolean;
+    /** Custom success encoding — receives the value already in wire form (dates,
+     *  naming applied). Replaces the envelope/pagination steps. */
+    readonly encodeSuccess?: (value: unknown, ctx: RestFormatContext) => RestFormatResponse;
+    /** Custom error encoding. Replaces `errors`. */
+    readonly encodeError?: (error: RestFormatError, ctx: RestFormatContext) => RestFormatResponse;
+    /** A hook over the OpenAPI operation the plugin emits for a projection. */
+    readonly describe?: (operation: Record<string, unknown>, ctx: {
+        readonly tag: string;
+        readonly method: string;
+        readonly path: string;
+    }) => Record<string, unknown>;
+}
+
+/** What a format sees when it encodes one response. */
+export declare interface RestFormatContext {
+    /** The rpc tag, e.g. `teams.list`. */
+    readonly tag: string;
+    readonly method: string;
+    /** The request path, for `Link` headers. */
+    readonly path: string;
+    /** The request's query string (without `?`). */
+    readonly query: string;
+    /** The first `source` table of the procedure, when it declares one — the
+     *  JSON:API resource `type`. */
+    readonly source: string | undefined;
+    readonly status: number;
+}
+
+/** A failure the desugar or the projection is about to answer with. */
+export declare interface RestFormatError {
+    readonly status: number;
+    /** The typed error's `_tag` (`AccessDeniedError`), or a stable name for a
+     *  transport failure (`InvalidRequest`, `Unauthorized`, `Forbidden`, …). */
+    readonly tag: string;
+    /** A human-readable line. */
+    readonly message: string;
+    /** The error's own fields (a typed error), without `_tag`. */
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+
+/** A response a format produced: body (already wire-shaped), headers, and the
+ *  media type when it is not `application/json`. */
+export declare interface RestFormatResponse {
+    readonly body: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly contentType?: string;
+}
+
 declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -4418,6 +4646,10 @@ declare interface RestGuardRejection {
 
 declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
+export declare type RestNaming = 'camelCase' | 'snake_case';
+
+export declare type RestPagination = 'link-header' | 'body-cursor';
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -4427,6 +4659,8 @@ declare interface RestResponse<O> {
     readonly status: number;
     readonly body: O;
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+    /** A media type other than `application/json` (a JSON:API document). */
+    readonly contentType?: string;
 }
 
 /**
@@ -4474,6 +4708,17 @@ declare interface RestRouteDescriptor<I, O> {
     readonly summary?: string;
     readonly description?: string;
     readonly example?: RestRouteExample;
+    /** The spec's `operationId` — set by a `publicApi` projection from its tag. */
+    readonly operationId?: string;
+    /** The spec's tag group(s) — set by a projection from its tag prefix. */
+    readonly tags?: ReadonlyArray<string>;
+    /**
+     * Present on a `publicApi` projection: what the route projects, in the wire
+     * form its profile speaks. The OpenAPI generator documents parameters,
+     * bodies, responses and security from it; the desugar answers every refusal
+     * through its format.
+     */
+    readonly projection?: RestRouteProjection;
     /** Replacement hint. Sets a `Deprecation: true` response header. */
     readonly deprecated?: string;
     /** ISO date. Sets a `Sunset:` header; past the date the route returns
@@ -4523,6 +4768,48 @@ declare interface RestRouteExample {
     readonly response?: unknown;
 }
 
+/**
+ * What a `publicApi` projection is, for the two readers that need more than
+ * the route: the OpenAPI generator and the desugar's refusals. `input` and
+ * `output` are the WIRE schemas — the descriptor's, rewritten by the profile
+ * (`restViewSchema`): a `timestampMs` is a `date-time` string under
+ * `dates: 'iso'`, keys are snake_case under that naming. `input` carries the
+ * path parameters as fields; `pathParams` says which.
+ */
+declare interface RestRouteProjection {
+    readonly tag: string;
+    readonly kind: 'query' | 'mutation' | 'action';
+    readonly version: string;
+    readonly security: 'required' | 'optional' | 'none';
+    readonly input: Schema.Schema.All;
+    /** The wire names of the input fields bound from the path. */
+    readonly pathParams: ReadonlyArray<string>;
+    readonly output: Schema.Schema.All;
+    /** The first `source` table, when the procedure declares one. */
+    readonly source: string | undefined;
+    /** Every failure the operation answers with a typed body, and its status:
+     *  the descriptor's `errorStatus` entries, `422` for the union's other tags,
+     *  and each plugin error that names a REST status. */
+    readonly errorResponses: ReadonlyArray<{
+        readonly status: number;
+        readonly tag: string;
+        readonly schema: Schema.Schema.All;
+    }>;
+    readonly format: RestFormat;
+}
+
+/**
+ * Rewrite a descriptor's schema into the shape the profile puts on the wire:
+ * `timestampMs` (`DateFromNumber`) becomes an RFC 3339 string under
+ * `dates: 'iso'`, and every struct's property names become `snake_case` under
+ * `naming: 'snake_case'` — as a transformation, so decoding a wire value yields
+ * the descriptor's own typed value and encoding the typed value yields the
+ * wire form. `JSONSchema.make` of the result documents the wire (a
+ * `format: date-time` string, the snake keys). Classes and other opaque
+ * transformations pass through unchanged; a struct inside one keeps its keys.
+ */
+export declare const restViewSchema: (schema: Schema.Schema.All, format: RestFormat) => Schema.Schema.All;
+
 /** The id of a row, addressed in op paths as `/<id>`. */
 export declare type RowId = string | number;
 
@@ -4693,6 +4980,14 @@ export declare interface RpcInterceptorContext {
      *  plugins (Sentry/Datadog) attach an error to the exact span, not just
      *  the trace. Absent when no tracer is installed. */
     readonly spanId?: string;
+    /**
+     * `'rest'` when the call came through the `publicApi` projection (`/v1`);
+     * absent on the rpc wire. A per-endpoint policy on the projection — the
+     * descriptor's `publicApi.rateLimit` — applies to these calls only.
+     */
+    readonly surface?: 'rest';
+    /** The descriptor's `publicApi` spec, on a projected call. */
+    readonly publicApi?: PublicApiSpec;
 }
 
 /**
@@ -5089,18 +5384,18 @@ export declare const Subject: Schema.Union<[Schema.Struct<{
 export declare type Subject = typeof Subject.Type;
 
 export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
-    id: typeof Schema.String;
     type: Schema.Literal<["user"]>;
+    id: typeof Schema.String;
     tenantId: typeof Schema.String;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
-    id: typeof Schema.String;
     type: Schema.Literal<["apiKey"]>;
+    id: typeof Schema.String;
     tenantId: typeof Schema.String;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
-    id: typeof Schema.String;
     type: Schema.Literal<["serviceAccount"]>;
+    id: typeof Schema.String;
     tenantId: typeof Schema.String;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
@@ -5125,8 +5420,8 @@ export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
      */
     credentialRejected: Schema.optional<typeof Schema.String>;
 }>, Schema.Struct<{
-    id: typeof Schema.String;
     type: Schema.Literal<["system"]>;
+    id: typeof Schema.String;
     tenantId: typeof Schema.Null;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
@@ -5164,37 +5459,37 @@ export declare class SubjectService extends SubjectService_base {
 }
 
 declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Subject", {
-    readonly id: string;
     readonly type: "user";
+    readonly id: string;
     readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
-    readonly id: string;
     readonly type: "apiKey";
+    readonly id: string;
     readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
-    readonly id: string;
     readonly type: "serviceAccount";
+    readonly id: string;
     readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
-    readonly id: null;
     readonly type: "anonymous";
+    readonly id: null;
     readonly tenantId: string | null;
     readonly credentialRejected?: string | undefined;
 } | {
-    readonly id: string;
     readonly type: "system";
+    readonly id: string;
     readonly tenantId: null;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
@@ -5534,6 +5829,8 @@ export declare const toRpc: <Name extends string, Input extends Schema.Schema.An
     revision: Schema.optional<typeof Schema.Number>;
 }>]>, Schema.Schema.All>, typeof Schema.Never, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Output, Schema.Schema.All>, typeof Schema.Never, never>;
 
+export declare const toSnakeCase: (key: string) => string;
+
 /**
  * Coerce a timestamp read (`Date` / epoch-ms number / ISO string) to
  * epoch milliseconds. Unrecognised inputs collapse to `0`.
@@ -6131,6 +6428,18 @@ export declare interface VoltroPlugin {
      * mounted when this runs, so the hook only records.
      */
     readonly onRestSurface?: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => void;
+    /**
+     * Told the app's wire-reachable rpc procedures — every query, mutation,
+     * action and stream discovery found, minus `internal` ones — once discovery
+     * has run, on both boot paths. The procedure counterpart of
+     * `onRestSurface`, for the same reason: a documentation plugin that wants
+     * the descriptors otherwise asks the app to import them into
+     * `app.config.ts`, which evaluates every descriptor module before discovery
+     * on every load of the config — and `voltro serve` loads no TypeScript at
+     * runtime, so a plugin cannot read them later either. Synchronous: records
+     * only.
+     */
+    readonly onProcedureSurface?: (procedures: ReadonlyArray<ProcedureDescriptor>) => void;
 }
 
 /**