@voltro/protocol 0.69.0 → 0.69.1

package/CHANGELOG.md

@@ -39,6 +39,94 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.69.1] — 2026-09-11
+
+### Added
+
+- **@voltro/cli** — `voltro dev` and `voltro build` refuse a published artefact. A publish step writes `.framework/dist/.voltro-artifact.json` into a package that ships its build and no source; both commands look for it before loading the config or booting anything and exit 1 with the reason. An image built without the dev toolchain is a hindrance; this is the rule — a toolchain installed by hand into that image still cannot develop or rebuild the package. A developer's own tree never carries the marker, built or not, so nothing changes there.
+- **@voltro/database, @voltro/cli** — `voltro db plan` names the tables on which the live and the declared fingerprint part — in the JSON record, and on a TTY for an empty plan.
+
+  `fingerprintLive` hashes the whole live introspection, every table included; `fingerprintDeclared` hashes the declaration. A plan of zero operations says the schemas agree, and the two hashes can still differ — over a table the diff never compares (`cluster_*`, an undeclared `_voltro_*`, a soft-drop snapshot, a name in `VOLTRO_DB_IGNORE_TABLES`), or over a detail the diff calls equal that introspection reports differently from how it was declared. The TTY printed a caveat under the two; the JSON record a migrate job writes carried none, so `0 operations` under two different hashes read as a contradiction and raised the question whether the computation had changed.
+
+  The plan carries `fingerprintDivergence: { outsideDiff, diffEquivalent }` now, both lists of table names, and the record carries it with a one-line `fingerprintNote`. On a TTY the fingerprint line lists them, and an empty plan prints it only when the two part somewhere, so a clean schema stays a one-liner. The earlier wording — "a live hash never equals a declared one" — was wrong as a rule: a schema whose every detail introspects back as declared hashes the same on both sides, and does.
+
+  `voltro serve` is not part of this: its boot check compares the declared fingerprint against the one the last `voltro db apply` RECORDED, never the live hash.
+- **@voltro/client, @voltro/web** — The client diagnostics snapshot carries `runtime` — per api, what the runtime resolved to (`scheduler`, `generation`) — outside the event ring.
+
+  `runtime.resolved` is recorded when the runtime is built, which makes it one of the first events of a session, and the first events are exactly what a `clear()` before a measurement or the ring's eviction removes. An export taken after either carried every reconnect event and no statement about which scheduler produced them; a reader checking whether the yield channel was in use had to inspect the bundle by hand. The snapshot keeps the last resolved record per api in its own field now, and `clear()` leaves it in place — it describes the runtime, not the timeline.
+- **@voltro/plugin-openapi, @voltro/protocol, @voltro/cli** — `openapiPlugin` documents the app's own REST surface as the framework mounts it — every `restRoutes` descriptor and every `publicApi` projection — without the app listing them (`includeAppRoutes`, default `true`). A plugin can implement the new `onRestSurface(routes)` hook and is told the mounted routes on both boot paths once they exist. Importing descriptor modules into `app.config.ts` to build that list is no longer needed, which is the path on which a boot had hung.
+- **@voltro/workflow, @voltro/cli** — A `run-stalled` report on the durable engine carries the engine's view of the run — its journal messages, whether each was processed and last read, and who holds the lock on its shard — and the staleness tick warns about unprocessed messages no runner has read for the engine's own re-read window.
+
+  The engine's recovery for a run whose process died is real and silent: a runner that acquires a shard re-delivers the shard's unprocessed messages, and re-reads any whose `last_read` is older than ten minutes. The state with no symptom is the one where no runner acquires the shard — a postgres advisory lock held by a session that is not a live runner (a backend the server has not reaped, a pooled connection that outlived its client) — and the run then sits `running` with nothing moving while every process reports healthy. `ClusterDiagnostics` (provided by `workflowEngineLayer`) reads that state: `messagesFor(executionId)`, `unreadMessages()`, `shardLockHolders(shardIds)` (postgres advisory holders from `pg_locks` + `pg_stat_activity`, row leases from `cluster_locks`), `runners()`. Both boot paths attach it to the stall report as `cluster` and log `workflow.cluster: unprocessed messages no runner has read for the re-read window` with the holders, so the report names the pid to terminate — or the lease mode (`VOLTRO_WORKFLOW_SHARD_LOCK=row`) that bounds the wait.
+- **@voltro/runtime, @voltro/voltro** — `EffectStoreOps.upsertWithOutcome` — the Effect form of `upsertRowOutcome`, on `yield* EffectStore` and on the `tx` view `transactional` hands out.
+
+  `upsertRowOutcome` required `store.upsertWithOutcome`, which `ctx.store` provides and `EffectStoreOps` did not declare, so an Effect handler running its ingest inside `transactional` — the place the outcome was built for — kept a pre-read to report `created`. The operation answers `{ row, outcome: 'inserted' | 'updated' }` on the `StoreError` channel like every other op; a hand-written `DataStore` without it is refused with the same message the typed helper gives.
+
+### Changed
+
+- **@voltro/cli** — `voltro test` exits 1 when it executed no test, on every invocation — a bare `voltro test` included.
+
+  A filter that matched nothing and an explicitly named directory with no tests already failed. The bare command was the exception, kept as "a fresh app with no tests yet shouldn't fail its pipeline" — and that is the one exception a CI cannot see: a tree whose tests were all misnamed, moved or deleted printed green forever, with `if voltro test` seeing nothing. Every scaffold ships tests, so nothing needs the exception. The refusal for a stale `rpcGroup.generated.ts` already exited 1; this closes the remaining route to a green line over zero tests.
+
+  vitest's own `--passWithNoTests` is honoured verbatim when a green run over nothing is what you want; it used to be overridden.
+- **@voltro/runtime, @voltro/voltro, @voltro/cli** — `ApiKeyStore.ensureActor` receives the `issue()` input, and the built-in `apiKeys:` wiring takes an `ensureActor` of your own.
+
+  0.69.0 made issuing a key plant its `actors` row through a required `ensureActor({ id, displayName })`, and its note said the framework stores need nothing from you. Both were written for the BUILT-IN `actors`. An app may declare its own — it takes precedence over the built-in table — and that table need not carry `kind` or `displayName` at all and may require columns the hook never saw: which kind of key this is, whom it belongs to, which team it acts for. All of that is in the `issue()` input (`metadata`, `onBehalfOf`) and nowhere else, so the only complete row was one written AFTER `issue()` returned — and a hook that wrote a minimal row first collided with it on the table's own unique keys.
+
+  The hook receives `input` now — verbatim, and on a rotation the input the rotation rebuilt from the old row, so ownership survives rotation there too. The two framework stores read `id` and `displayName` and ignore the rest; a hand-written store can build the complete row before the key exists. Additive for an implementor: a function taking the narrower object is still assignable.
+
+  For an app that declares its own `actors` and uses the built-in wiring, the 0.69.0 write (`{ id, kind: 'apiKey', displayName }`) does not fit that table, and since 0.69.0 that meant `issue()` failed at the actor write. `apiKeys: { ensureActor }` in the config replaces exactly that write, on both boot paths.
+
+  A note under an already-crossed version is never seen again, so the corrected guidance is re-issued as codemod `0.69.1/01_ensure-actor-receives-the-issue-input`, gated on a hand-written `ApiKeyStore` OR an app-declared `actors` — the second group is affected without ever having written the first, and the 0.69.0 gate did not reach it.
+- **@voltro/protocol** — A `GET` projection coerces the query string toward the descriptor's input before decoding: `?limit=5` reaches a `Schema.Number` as `5`, `?archived=true` a `Schema.Boolean` as `true`, and a repeated parameter a `Schema.Array` as its elements; a value that does not read as the target is left for the schema's own `400`. A projection of a procedure without an `openAccess` decision now carries `requireAuthenticated()` — an anonymous caller answers `401` before the handler runs, where it used to reach the handler and surface that refusal as a `500`. A typed error the handler fails with, one of the descriptor's declared `error:` variants, answers with its tag and fields as the body under the status `publicApi.errorStatus` assigns it (`422` when unlisted); an undeclared error stays a `500`.
+- **@voltro/cli** — `voltro dashboard` has no dev fallback any more. A dashboard tree without a build used to be served by `voltro dev` — right for the monorepo source layout, and exactly the mode a deployed dashboard must never enter: a package that lacked its build would have booted a Vite dev server with a freshly minted inspect token on a public hostname, with a `mode: 'dev'` log line as the only sign. The command now refuses a tree without a build in every environment and says where a source tree is served from (`voltro dev <path>`, which the auto-launcher already picks on its own). Removed rather than gated: a gate is one environment variable away from open. The dashboard image is built to have no such door at all — installed without optional dependencies, so the build and dev toolchain is absent, and started through the bin's in-process start path.
+- **@voltro/database, @voltro/cli** — A declared snapshot and the live snapshot of a database the planner has converged on hash the SAME — the fingerprint canonicalises by the planner's own equivalence rules, and the declared snapshot carries the widths the emitter renders.
+
+  `fingerprint.ts` promised that two snapshots of identical observable shape produce identical fingerprints. Measured on a MariaDB: a plan of zero operations under two different hashes, and practically every table hashing apart from its own declaration. The planner decided "nothing to do" through helpers the fingerprint never saw — `restrict` folded into `noAction` on every foreign key (MySQL reports RESTRICT, SQL Server NO ACTION), `now` against `current_timestamp(6)` on every timestamp, a boolean default against the engine's `0`/`1`, `oneOf` compared as a set — and hashed the raw fields instead. And the emitter renders widths the declaration never spells out: `VARCHAR(255)` for a `oneOf` text, `VARCHAR(64)` for a typeid `id()`, a bounded key on mssql for indexed text; introspection reports them as `maxLength`, the declared snapshot carried nothing.
+
+  Those rules live in one module now (`columnEquivalence.ts`), imported by the planner and the fingerprint alike — a second copy is how the two disagreed. The fingerprint hashes the canonical column: references through `normRef`, defaults as the comparable token, `oneOf` sorted, a postgres BIGSERIAL's implicit sequence as the no-default it is to a numeric id, a soft-drop snapshot column left out as the planner leaves it out. `declaredSnapshot(tables, dialect)` materialises the width `sqlType` renders — the same function that renders CREATE TABLE, so the DDL is byte-for-byte what it was; an explicit `.maxLength(n)` is never touched, and a `text()` that renders unbounded stays unbounded. Verified against the database that showed it: the six remaining `diffEquivalent` tables after the first pass were all boolean defaults, and none remain.
+
+  **What this changes for a running deployment: the declared fingerprint of every schema with a foreign key, a default or a `oneOf` moves once.** A `voltro dev` boot runs the plan, finds nothing, and records the new value on its own. `voltro serve` compares the declared fingerprint against the last one `voltro db apply` recorded, so the pre-deploy `voltro db apply` your pipeline already runs is what records it — an apply that finds nothing to do records exactly for this case. `voltro db drift` reports the live side moved once too, until that apply re-baselines it.
+
+  `voltro db squash` now passes the dialect to the declared snapshot it fingerprints; it was the one caller that did not, and its hash disagreed with the boot's.
+- **@voltro/cli** — A production `voltro start` no longer reads `src/`. `voltro build` writes the route tree beside the SSR bundle (`dist/server/pagesTree.json`, the same walk the bundle's lazy page loaders were generated from), and `start` boots from it; the font head was already baked into the built shell. So a deployed web app is `.framework/` plus `app.config.ts` and its `node_modules` — the TypeScript source can stay out of the image and out of a published app package. Only an unbuilt tree (the Vite middleware fallback that is not a production path) still walks `src/pages`. A production start that finds an SSR bundle without the tree beside it refuses with the instruction to rebuild, rather than quietly falling back to the source.
+- **@voltro/cli** — `voltro start` drains on SIGTERM the way `voltro serve` does: readiness flips to `503`, the long-lived inspect streams are ended (their client reconnects), the listener closes and in-flight requests finish inside 60% of `VOLTRO_SHUTDOWN_GRACE_MS`, then the SSR loader, cache backend and registry entry close and the process exits `0` with a `drained in <ms>` line. Before this the web path closed its listener and exited: a render in flight when the signal landed was cut, and the docs described a drain with an env var (`SHUTDOWN_GRACE_MS`) that nothing read. The docs now name the real variable and the real order.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md` finds the project's `@voltro/cli` under the app it was run from, not only at the workspace root.
+
+  Its provenance line looked in `<root>/node_modules/@voltro/cli` alone, so a pnpm-strict install (`apps/<name>/node_modules/@voltro/cli`) reported `project has no resolvable @voltro/cli … installed: null` — from a command that was running that very cli. The candidates are now the directory the command started in and every directory up to the root, the root, then every discovered app, in that order.
+- **@voltro/cli** — `voltro update` prints the backfill for API keys issued before 0.69.0 to the apps that have them.
+
+  The 0.69.0 note `05_api-key-store-plants-its-actor` carried the instruction — one `actors` row per existing key — in its last paragraph, and gated the whole note on a hand-written `ApiKeyStore`. An app on the framework store, which is the app that holds such keys, saw `1 skipped (own check found nothing)`. A note under an already-crossed version is never printed again, so the paragraph is re-issued under `0.69.1/02_existing-api-keys-get-their-actors-row`, gated on using api keys at all (`apiKeys:` in the config, `apiKeyStrategy`, or an `ApiKeyStore`), with the loop that plants the rows idempotently through `insertIgnore`.
+- **@voltro/workflow, @voltro/cli** — `onFailure` fires for a run whose body failed — the route the documentation listed first and the one that was not wired.
+
+  The three flow-control routes into the failure signal (an expired `timeouts.start`, a `timeouts.finish` cancellation, a dead-lettered intent) reached the handler through the drainer's `onAbandoned`; the run recorder's terminal hook only released the admission lease. So a deployment saw its `onFailure` workflow run for a finish-timeout cancellation and stay silent for the runs that had actually failed. The recorder's `onTerminal` now carries the payload and the error on `failed`, and both boot paths build their hook with `makeWorkflowTerminalHook`: release the lease, then — for a workflow that declares `onFailure` — start it with the same `WorkflowFailureReport` the other routes send (`reason: 'the run failed with <errorTag>'`, `runId`, `executionId`, the payload). A workflow that declares nothing stays exactly as loud as before.
+- **@voltro/cli, @voltro/protocol** — A `publicApi` projection — and every hand-written `restRoutes` entry — now runs under the app's row filter. Both boot paths built the REST request's context from the subject alone, so for an app that registered `setRowFilter` the context builder's unfiltered-read guard refused every REST request before its handler ran: `500` on every route, in development and production alike. The shared REST surface now resolves the row filter for each request (`withRowFilter`, the same spine the rpc runners walk) before the context exists, and the context builder runs inside the route's failure mapping rather than escaping it as a transport defect.
+
+  Behind that refusal sat a second defect the refusal had been hiding: the one-shot read of a projected query went through the raw store, so once the request had a row filter it still returned every row of the table — the filter was resolved and never applied to the read. The one-shot runner now reads through the request-scoped store the context builder wraps (row filter and tenant scope applied), the store the handler itself would read from. The subscription and socket arms were already filtered.
+
+  The REST failure mapping is one function for every place a route can fail: `RestRouteError` and `{ status }` errors keep their status; the framework's `ScopeError` answers `403`, or `401` for an anonymous caller; `Unauthenticated` answers `401`; everything else is the reported `500`. A repeated query parameter (`?tag=a&tag=b`) reaches the input as an array of every value instead of the last one.
+- **@voltro/workflow, @voltro/cli** — `timeouts.finish` cancels at the deadline plus at most one drain tick — not at whatever start next happened to wake an idle drainer.
+
+  The bound is enforced by the admission drainer's tick, and the drainer disarms when nothing is pending. A run admitted straight through writes nothing to the queue, so with an empty queue the drainer slept while the run passed its bound and cancelled it only when an unrelated arrival woke it — measured as cancellations landing tens of minutes late by amounts that depended on traffic. Two changes: the finish sweep reports the earliest deadline among the running runs it saw, and `drainTick` folds it into `nextDueAt`, the instant the drainer arms for; and a run STARTING wakes the drainer in an app that declares a finish bound, so the tick that follows reads the new deadline. Both boot paths, through the shared wiring.
+- **@voltro/cli** — The `helm` baseline (`voltro baseline set helm`) probed `/healthz` on the api and `/` on the web — the first answers 404 on every Voltro boot path, so an api pod could never become ready; the second is answered by the SPA shell with 200 for anything, so a web pod could never become unready. Both deployments now probe what the framework answers before routing — `<path>/startup`, `<path>/readiness`, `<path>/liveness` — with a `probes` block per app (path, periods, thresholds) and a `shutdown` block that renders the `preStop` sleep, `terminationGracePeriodSeconds` and `VOLTRO_SHUTDOWN_GRACE_MS` together, since they are one budget. `PORT` is set from the chart's port so the Service and the listener agree.
+- **@voltro/cli** — `/_voltro/inspect/stream` under `voltro serve` no longer refuses a non-loopback `Host`. The DNS-rebinding host guard is a `voltro dev` measure — the dev api binds every interface and has no hostname of its own — and the JSON inspect door has only ever applied it there. The live stream's shared wiring applied it on every boot path, so behind a Kubernetes Service, a docker network name or an ingress host every JSON endpoint answered the dashboard's bearer with 200 while the stream answered the same bearer with `401 forbidden host` — a refusal that reads as a token problem and is not one. The stream now takes the guard from its door: on in dev, off in serve, where the surface is fail-closed on the token alone.
+- **@voltro/cli** — `voltro dev` stops, with exit code `3`, when the project's installed `@voltro/cli` is no longer the one it is running — instead of restarting on the old one and reporting it as complete.
+
+  The supervisor respawns the api child from its own entry, resolved once at boot. Swap `node_modules` under a running `voltro dev` (a `voltro update`, an install that bumps the cli, a volume replaced under a pod) and every restart after that booted the cli the supervisor started from, printing `restart complete — api ready` for an api composed by code the disk no longer had; nothing in the log said which cli built it. The supervisor cannot re-exec itself, so on the next file change it compares what the root installs with its own version and stops on a difference, naming both and the path — under a restart policy the process comes back on the installed version, in a terminal `voltro dev` is started again. The ready line now carries `cli=<version>`, and a first boot on a cli the project does not install is warned about rather than stopped, because a workspace binary against a checkout is legitimate.
+- **@voltro/cli** — `voltro update` puts every `package.json` it bumped back, byte for byte, when the install fails without ever fetching the target version.
+
+  The bump is written before the install runs — that is what the install resolves against — and an install can fail for a reason the tree had no part in. A lockstep release lands on the registry one package at a time, so the moment the FIRST `@voltro/*` package is there the latest version resolves to the new release; an update started in that minute bumped every manifest and then met `NO_MATCHING_VERSION` on a sibling that was seconds from landing. What it left behind was the worst of the three states: manifests saying the new version, lockfile and `node_modules` saying the old one, and `voltro update` itself reading the manifests as "already there".
+
+  Which state a failure leaves is now measured off the tree, not read off the exit code. A bumped package present in `node_modules` at the target version means the install fetched the release and failed after — a postinstall, a peer — so the bump stands and the message names the codemods as the missing half, as before. Nothing at the target version means the install never got that far, and the originals go back. The message says which of the two happened, and for the first names the publish window as the likely cause: wait a minute, re-run.
+
+  Nothing here reaches `--no-install`, which writes the bump on purpose and says what is left.
+- **@voltro/cli** — `voltro logs` and the dev log buffer keep the error a record was written with. `log.error(message, fields, err)` under `voltro serve` printed `cause` on stdout; the dev capture dropped it, so a route that threw showed `… threw path=/v1/x` and nothing else on any level. The record now carries the error's message and first stack frames, and the text renderer prints them under the line. `voltro dev` also warns when `VOLTRO_SESSION_SECRET` is shorter than the floor `voltro serve` refuses, instead of accepting in silence what production will reject.
+
+---
+
 ## [0.69.0] — 2026-09-10
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -4099,6 +4099,17 @@ export declare interface PublicApiSpec {
     /** Streaming queries over request/response: 'snapshot' (default — first
      *  snapshot, like POST /rpc) | 'sse' (Server-Sent Events of snapshot+deltas). */
     readonly stream?: 'snapshot' | 'sse';
+    /**
+     * HTTP status per DECLARED typed error tag, for the projection. A typed
+     * error the handler fails with — one of the descriptor's `error:` union —
+     * answers with its tag and fields as the body, and this status; a tag not
+     * listed here answers `422`, the status the OpenAPI projection documents
+     * for a typed error. The framework's own `ScopeError` is mapped
+     * before this (`403`, or `401` for an anonymous caller) and needs no entry.
+     *
+     *     publicApi: { errorStatus: { AccessDeniedError: 403, NotFoundError: 404 } }
+     */
+    readonly errorStatus?: Readonly<Record<string, number>>;
 }
 
 /**
@@ -4393,6 +4404,125 @@ export declare interface ResourceScopeRequest {
  */
 export declare type ResourceScopeResolver = (req: ResourceScopeRequest) => Effect.Effect<boolean, unknown>;
 
+declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
+
+/**
+ * A guard runs after input decode + ctx resolution, before the handler.
+ * Returning a `RestGuardRejection` short-circuits with that status; any
+ * other return (or `undefined`) lets the request proceed.
+ */
+declare interface RestGuardRejection {
+    readonly status: number;
+    readonly message: string;
+}
+
+declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+/** 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
+ *  the response intentionally has no representation. */
+declare interface RestResponse<O> {
+    readonly __voltroRestResponse: true;
+    readonly status: number;
+    readonly body: O;
+    readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+}
+
+/**
+ * Per-call context handed to a REST route handler. Resolved by the serve
+ * pipeline: `subject` from the framework's auth resolver, `headers`
+ * lowercased, `store` the framework `DataStore` injected the same way
+ * plugins receive it via `bindDataStore` (kept untyped here so protocol
+ * stays free of the database dep).
+ */
+declare interface RestRouteContext {
+    readonly subject: Subject;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Request metadata and the byte-exact body as received by the HTTP
+     *  transport. JSON routes normally use decoded `input.body`; `rawBody` is
+     *  for signature verification, multipart parsing, and other protocols where
+     *  parsing first would destroy information the handler must authenticate. */
+    readonly method: RestMethod;
+    readonly path: string;
+    readonly query: string;
+    readonly rawBody: Uint8Array;
+    /** Framework `DataStore`. Untyped in protocol (same discipline as
+     *  `PluginHttpRoute` / `bindDataStore`); cast to the concrete store at
+     *  the call site. `undefined` only in unit tests that don't inject one. */
+    readonly store: unknown;
+    /** Full framework context for this authenticated request. This keeps custom
+     *  REST handlers on the same capability surface as query/mutation/action
+     *  handlers without creating a protocol-to-runtime package dependency. */
+    readonly app?: unknown;
+}
+
+declare interface RestRouteDescriptor<I, O> {
+    readonly method: RestMethod;
+    /** Absolute path, e.g. `/v1/customers`. Matches that path exactly. */
+    readonly path: string;
+    /** Input schema. Shape is `{ query?, params?, body? }` — the desugar
+     *  parses the query string, path params, and JSON body into that shape
+     *  before decoding. Omit for routes that take no input. The schema's
+     *  decoded `Type` flows to the handler's `input`; its `Encoded` is left
+     *  open (`any`) so any `Schema.Struct(...)` is accepted. */
+    readonly input?: Schema.Schema<I, any, never>;
+    /** Output schema. The handler returns the decoded `Type`; the desugar
+     *  encodes it to JSON for the `200` response. */
+    readonly output: Schema.Schema<O, any, never>;
+    readonly handler: (input: I, ctx: RestRouteContext) => Promise<O | RestResponse<O>> | O | RestResponse<O>;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly example?: RestRouteExample;
+    /** Replacement hint. Sets a `Deprecation: true` response header. */
+    readonly deprecated?: string;
+    /** ISO date. Sets a `Sunset:` header; past the date the route returns
+     *  `410 Gone` with a replacement pointer. */
+    readonly sunset?: string;
+    /**
+     * Opt-in API version. `version: 'v2'` + `path: '/customers'` mounts the route
+     * at `/v2/customers` — the same `/vN/` convention the `publicApi:` projection
+     * has always used (`derivePublicPath`) and the built-in `/v1/api-keys`
+     * surface follows.
+     *
+     * OPT-IN on purpose: a route without `version` keeps its literal `path`
+     * untouched. An automatic prefix would silently move every deployed route —
+     * a second breaking change hiding inside a naming feature.
+     *
+     * Two versions of one resource are TWO descriptors: the old version is
+     * ordinary code — visible, testable, deletable — carrying `deprecated` (the
+     * replacement pointer) and `sunset` (the date it starts answering `410`,
+     * whose body then also names this `version`). There is no transformation
+     * DSL, and the rpc SOCKET is deliberately outside this: the generated client
+     * is versioned with the server it was generated from (a stale browser tab
+     * runs the previous client until reload — that skew window exists and is
+     * documented, it is not solved by URL versioning).
+     */
+    readonly version?: `v${number}`;
+    readonly guards?: ReadonlyArray<RestGuard>;
+    /**
+     * This route STREAMS (Server-Sent Events) rather than resolving one value — its
+     * handler returns `sse(...)`. Declared on the descriptor, not left implicit in
+     * the handler, so anything that INSPECTS routes without running them (the
+     * OpenAPI generator, the inspect manifest) can tell a stream from a buffered
+     * response. A spec that documents a stream as `application/json` is worse than
+     * no spec, because clients are generated from it.
+     */
+    readonly streaming?: boolean;
+    /** Per-route body cap override (bytes) — see PluginHttpRoute.maxBodyBytes. */
+    readonly maxBodyBytes?: number;
+    /** GET only: derive a weak ETag from the encoded response and answer a
+     *  matching `If-None-Match` with 304. The tag is content-derived (an md5
+     *  of the JSON), so it is correct across content-encodings — the
+     *  transport's compression varies the bytes, not the representation. */
+    readonly etag?: boolean;
+}
+
+declare interface RestRouteExample {
+    readonly request?: unknown;
+    readonly response?: unknown;
+}
+
 /** The id of a row, addressed in op paths as `/<id>`. */
 export declare type RowId = string | number;
 
@@ -5991,6 +6121,16 @@ export declare interface VoltroPlugin {
      * SDK here). Returns of `undefined`/empty are no-ops.
      */
     readonly contributeObservability?: (ctx: PluginLifecycleContext) => Promise<ObservabilityContribution | undefined> | ObservabilityContribution | undefined;
+    /**
+     * Told the app's mounted REST surface — hand-authored `restRoutes` AND the
+     * routes projected from `publicApi` annotations — once the boot has built it,
+     * on both boot paths. A documentation plugin reads its API from here instead
+     * of asking the app to import its own descriptors into `app.config.ts`,
+     * which is where an app importing hundreds of descriptor modules before
+     * discovery has hung its own boot. Synchronous: the surface is already
+     * mounted when this runs, so the hook only records.
+     */
+    readonly onRestSurface?: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => void;
 }
 
 /**

package/dist/rest.d.ts

@@ -1,3 +1,4 @@
+import * as AST from 'effect/SchemaAST';
 import { DataStore } from '@voltro/database';
 import { Schema } from 'effect';
 
@@ -104,6 +105,22 @@ export declare const bytes: (stream: ReadableStream<Uint8Array> | (() => Readabl
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
 }) => RestByteResponse;
 
+/**
+ * Coerce a decoded query-string object toward the ENCODED shape of `input`.
+ * Field by field for a struct; the object is returned unchanged for any other
+ * shape (the schema then decides). Unknown keys pass through untouched.
+ */
+export declare const coerceQueryObject: (query: unknown, input: Schema.Schema.All) => unknown;
+
+/**
+ * Coerce ONE query-string value toward what `ast` (an ENCODED shape) expects.
+ * Only a value that reads unambiguously as the target is converted; anything
+ * else is left for the schema to refuse with its own message. Refinements are
+ * looked through to their base; a union tries each arm and takes the first
+ * that changed the value.
+ */
+export declare const coerceQueryValue: (value: unknown, ast: AST.AST) => unknown;
+
 /**
  * Project every descriptor carrying a `publicApi` annotation into a REST
  * route, in stable (path) order. The boot layer feeds these straight into
@@ -123,6 +140,9 @@ export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEn
  */
 declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
 
+/** The `_tag` literals a descriptor's `error:` union declares (empty for none). */
+export declare const declaredErrorTags: (error: Schema.Schema.All | undefined) => ReadonlySet<string>;
+
 /**
  * Identity helper that fixes the descriptor's types (like `defineAction` /
  * `definePlugin`). Returns its argument unchanged at runtime; exists for
@@ -629,6 +649,16 @@ declare interface PolicyGuardSpec<Input = unknown> {
     readonly resource: (input: Input) => string | undefined;
 }
 
+/**
+ * Translate a handler's failure into the response the projection promised:
+ * a DECLARED typed error becomes a `RestRouteError` with the tag, the fields
+ * and the status `errorStatus` assigns (`422` by default, the status the
+ * OpenAPI projection already documents for a typed error). Anything else is
+ * rethrown for the desugar's shared mapping (`ScopeError` → 403/401, a
+ * `status`-carrying error → itself, the rest → 500).
+ */
+export declare const projectedFailure: (err: unknown, descriptor: PublicApiDescriptor, spec: PublicApiSpec) => unknown;
+
 /** A descriptor kind that can be projected to REST (streams are not, in v1). */
 export declare type PublicApiDescriptor = 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>;
 
@@ -650,11 +680,12 @@ export declare type PublicApiInvoke = (input: unknown, ctx: RestRouteContext) =>
 /**
  * Synthesize the public REST route for ONE descriptor. The descriptor's input
  * schema is wrapped into the REST `{ query }` (GET) / `{ body }` (other) shape
- * the desugar decodes, then handed UNWRAPPED to `invoke`. Output is the
- * descriptor's output schema verbatim (a query is drained to its first snapshot
- * by the serve layer — same as POST /rpc — unless `stream: 'sse'` streams it).
- * `scopes` become
- * `requireScope` guards on top of the handler's own RBAC.
+ * the desugar decodes — for GET behind a query-string coercion — then handed
+ * UNWRAPPED to `invoke`. Output is the descriptor's output schema verbatim (a
+ * query is drained to its first snapshot by the serve layer — same as POST
+ * /rpc — unless `stream: 'sse'` streams it). The guards are
+ * `requireAuthenticated()` unless the descriptor declares `openAccess`, then
+ * one `requireScope` per `scopes` entry, on top of the handler's own RBAC.
  */
 export declare const publicApiRoute: (descriptor: PublicApiDescriptor, invoke: PublicApiInvoke, subscribe?: PublicApiSubscribe) => RestRouteDescriptor<Record<string, unknown>, unknown>;
 
@@ -683,6 +714,17 @@ declare interface PublicApiSpec {
     /** Streaming queries over request/response: 'snapshot' (default — first
      *  snapshot, like POST /rpc) | 'sse' (Server-Sent Events of snapshot+deltas). */
     readonly stream?: 'snapshot' | 'sse';
+    /**
+     * HTTP status per DECLARED typed error tag, for the projection. A typed
+     * error the handler fails with — one of the descriptor's `error:` union —
+     * answers with its tag and fields as the body, and this status; a tag not
+     * listed here answers `422`, the status the OpenAPI projection documents
+     * for a typed error. The framework's own `ScopeError` is mapped
+     * before this (`403`, or `401` for an anonymous caller) and needs no entry.
+     *
+     *     publicApi: { errorStatus: { AccessDeniedError: 403, NotFoundError: 404 } }
+     */
+    readonly errorStatus?: Readonly<Record<string, number>>;
 }
 
 /**

package/dist/rest.js

@@ -1,56 +1,145 @@
 import { F as e, P as t } from "./scopes-DVtiKKsm.js";
 import { c as n, l as r, o as i, s as a, t as o } from "./serverErrorBus-BTnTpMqj.js";
 import { Effect as s, Schema as c } from "effect";
+import * as l from "effect/SchemaAST";
 //#region src/publicApi.ts
-var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, d = (e, t, n) => {
+var u = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), d = (e, t) => t.path ?? `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`, f = (e) => {
+	if (l.isUnion(e)) {
+		let t = e.types.filter((e) => !l.isUndefinedKeyword(e));
+		if (t.length === 1) return t[0];
+		if (t.length !== e.types.length) return l.Union.make(t);
+	}
+	return e;
+}, p = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i, m = (e, t) => {
+	let n = f(t);
+	if (l.isRefinement(n) || l.isTransformation(n)) return m(e, n.from);
+	if (l.isUnion(n)) {
+		for (let t of n.types) {
+			let n = m(e, t);
+			if (n !== e) return n;
+		}
+		return e;
+	}
+	if (l.isTupleType(n)) {
+		let t = Array.isArray(e) ? e : e === void 0 ? void 0 : [e];
+		if (t === void 0) return e;
+		let r = n.rest[0]?.type ?? n.elements[0]?.type;
+		return r === void 0 ? t : t.map((e) => m(e, r));
+	}
+	if (typeof e != "string") return e;
+	if (l.isNumberKeyword(n)) return p.test(e.trim()) ? Number(e) : e;
+	if (l.isBooleanKeyword(n)) return e === "true" || e !== "false" && e;
+	if (l.isLiteral(n)) {
+		let t = n.literal;
+		return typeof t == "number" && p.test(e.trim()) && Number(e) === t || typeof t == "boolean" && String(t) === e ? t : e;
+	}
+	return e;
+}, h = (e, t) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return e;
+	let n = f(l.encodedAST(t.ast));
+	if (!l.isTypeLiteral(n)) return e;
+	let r = { ...e };
+	for (let e of n.propertySignatures) {
+		let t = String(e.name);
+		t in r && (r[t] = m(r[t], e.type));
+	}
+	return r;
+}, g = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	if (e === void 0) return t;
+	let n = (e) => {
+		if (l.isUnion(e)) {
+			for (let t of e.types) n(t);
+			return;
+		}
+		if (l.isTransformation(e)) {
+			n(e.from), n(e.to);
+			return;
+		}
+		if (l.isRefinement(e)) {
+			n(e.from);
+			return;
+		}
+		if (l.isTypeLiteral(e)) {
+			let n = e.propertySignatures.find((e) => e.name === "_tag");
+			n !== void 0 && l.isLiteral(n.type) && typeof n.type.literal == "string" && t.add(n.type.literal);
+		}
+	};
+	return n(e.ast), t;
+}, _ = (e, t, n) => {
+	if (n !== void 0) try {
+		let r = c.encodeUnknownSync(n)(e);
+		if (typeof r == "object" && r) return {
+			error: t,
+			...r
+		};
+	} catch {}
+	let r = { error: t };
+	for (let [t, n] of Object.entries(e)) t !== "stack" && t !== "_tag" && (r[t] = n);
+	return r;
+}, v = (e, t, n) => {
+	if (typeof e != "object" || !e) return e;
+	let r = e._tag;
+	return typeof r != "string" || r === "ScopeError" || !g(t.error).has(r) ? e : new E(n.errorStatus?.[r] ?? 422, _(e, r, t.error));
+}, y = (e, t, n) => {
 	let r = e.publicApi;
 	if (r === void 0) throw Error(`publicApiRoute: descriptor '${e.name}' has no publicApi annotation`);
-	let i = l(e.kind, r), a = u(e.name, r), o = i === "GET" ? "query" : "body", s = c.Struct({ [o]: e.input }), d = (r.scopes ?? []).map((e) => m(e)), f = r.stream === "sse" && e.kind === "query" && n !== void 0, p = f ? (e, t) => x((r) => n(e[o], t, (e) => {
-		r(S(String(e._tag ?? "message"), e));
-	})) : (e, n) => t(e[o], n);
-	return b({
+	let i = u(e.kind, r), a = d(e.name, r), o = i === "GET" ? "query" : "body", s = c.Struct({ [o]: e.input }), l = i === "GET" ? c.transform(c.Struct({ query: c.Unknown }), s, {
+		strict: !1,
+		decode: (t) => ({ query: h(t.query, e.input) }),
+		encode: (e) => e
+	}) : s, f = [...e.openAccess === void 0 ? [x()] : [], ...(r.scopes ?? []).map((e) => S(e))], p = r.stream === "sse" && e.kind === "query" && n !== void 0, m = p ? (e, t) => k((r) => n(e[o], t, (e) => {
+		r(A(String(e._tag ?? "message"), e));
+	})) : async (n, i) => {
+		try {
+			return await t(n[o], i);
+		} catch (t) {
+			throw v(t, e, r);
+		}
+	};
+	return O({
 		method: i,
 		path: a,
-		input: s,
+		input: l,
 		output: e.output,
-		handler: p,
-		...f ? { streaming: !0 } : {},
-		...d.length > 0 ? { guards: d } : {},
+		handler: m,
+		...p ? { streaming: !0 } : {},
+		guards: f,
 		...r.summary === void 0 ? {} : { summary: r.summary },
 		...r.description === void 0 ? {} : { description: r.description },
 		...r.deprecated === void 0 ? {} : { deprecated: r.deprecated },
 		...r.sunset === void 0 ? {} : { sunset: r.sunset }
 	});
-}, f = (e) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => d(e.descriptor, e.invoke, e.subscribe)).sort((e, t) => e.path.localeCompare(t.path)), p = () => (e) => {
+}, b = (e) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => y(e.descriptor, e.invoke, e.subscribe)).sort((e, t) => e.path.localeCompare(t.path)), x = () => (e) => {
 	if (e.subject.type === "anonymous") return {
 		status: 401,
 		message: e.subject.credentialRejected ?? "Authentication required"
 	};
-}, m = (e) => (t) => {
+}, S = (e) => (t) => {
 	let n = t.subject.scopes;
 	if (!(n && (n.includes(e) || n.includes("admin:full")))) return {
 		status: 403,
 		message: `Missing required scope: ${e}`
 	};
-}, h = (e) => (t) => {
+}, C = (e) => (t) => {
 	let n = t.subject.scopes;
 	if (!(n && (n.includes("admin:full") || e.some((e) => n.includes(e))))) return {
 		status: 403,
 		message: `Missing required scope: one of ${e.join(", ")}`
 	};
-}, g = (e, t = {}) => ({
+}, w = (e, t = {}) => ({
 	__voltroRestResponse: !0,
 	status: t.status ?? 200,
 	body: e,
 	...t.headers === void 0 ? {} : { headers: t.headers }
-}), _ = (e) => typeof e == "object" && !!e && e.__voltroRestResponse === !0, v = class extends Error {
+}), T = (e) => typeof e == "object" && !!e && e.__voltroRestResponse === !0, E = class extends Error {
 	status;
 	body;
 	headers;
 	constructor(e, t, n) {
 		super(`REST ${e}`), this.name = "RestRouteError", this.status = e, this.body = t, this.headers = n;
 	}
-}, y = (e, t, n) => new v(e, t, n), b = (e) => {
+}, D = (e, t, n) => new E(e, t, n), O = (e) => {
 	if (e.version === void 0) return e;
 	if (!/^v\d+$/.test(e.version)) throw Error(`defineRestRoute(${e.method} ${e.path}): version "${e.version}" must be 'v' followed by digits — 'v1', 'v2', …`);
 	if ((/* @__PURE__ */ RegExp("^/v\\d+(/|$)")).test(e.path)) throw Error(`defineRestRoute(${e.method} ${e.path}): the path already starts with a version segment AND declares version: '${e.version}'. Pick one spelling — either bake the version into the path, or declare version: and keep the path bare ('/customers'). Both would mount '/${e.version}${e.path}', which is never what the author meant.`);
@@ -58,13 +147,13 @@ var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.
 		...e,
 		path: `/${e.version}${e.path}`
 	};
-}, x = (e, t = {}) => ({
+}, k = (e, t = {}) => ({
 	__voltroRestStream: !0,
 	stream: {
 		subscribe: e,
 		...t.keepAliveMs === void 0 ? {} : { keepAliveMs: t.keepAliveMs }
 	}
-}), S = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, C = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, w = (e, t = {}) => ({
+}), A = (e, t) => `event: ${e}\n${(typeof t == "string" ? t : JSON.stringify(t)).split("\n").map((e) => `data: ${e}`).join("\n")}\n\n`, j = (e) => typeof e == "object" && !!e && e.__voltroRestStream === !0, M = (e, t = {}) => ({
 	__voltroRestBytes: !0,
 	byteStream: {
 		stream: e,
@@ -74,23 +163,26 @@ var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.
 	...t.contentType === void 0 ? {} : { contentType: t.contentType },
 	...t.status === void 0 ? {} : { status: t.status },
 	...t.headers === void 0 ? {} : { headers: t.headers }
-}), T = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, E = async (e) => {
+}), N = (e) => typeof e == "object" && !!e && e.__voltroRestBytes === !0, P = async (e) => {
 	let t = await globalThis.crypto.subtle.digest("SHA-1", new TextEncoder().encode(e));
 	return [...new Uint8Array(t)].map((e) => e.toString(16).padStart(2, "0")).join("");
-}, D = (e, t, n) => ({
+}, F = (e, t, n) => ({
 	status: e,
 	contentType: "application/json; charset=utf-8",
 	body: JSON.stringify(t),
 	...n ? { headers: n } : {}
-}), O = (e) => {
+}), I = (e) => {
 	if (e.length === 0) return;
 	let t = new TextDecoder().decode(e);
 	if (t.trim() !== "") return JSON.parse(t);
-}, k = (e) => {
+}, L = (e) => {
 	let t = {};
-	for (let [n, r] of new URLSearchParams(e)) t[n] = r;
+	for (let [n, r] of new URLSearchParams(e)) {
+		let e = t[n];
+		e === void 0 ? t[n] = r : Array.isArray(e) ? e.push(r) : t[n] = [e, r];
+	}
 	return t;
-}, A = (e, t) => {
+}, R = (e, t) => {
 	let n = e.split("/").filter((e) => e.length > 0), r = t.split("/").filter((e) => e.length > 0), i = {};
 	for (let e = 0; e < n.length; e++) {
 		let t = n[e];
@@ -104,118 +196,141 @@ var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.
 		}
 	}
 	return i;
-}, j = (e, t) => ({
-	query: k(e.query),
+}, z = (e, t) => ({
+	query: L(e.query),
 	params: t,
-	body: O(e.rawBody)
-}), M = /* @__PURE__ */ new Set([
+	body: I(e.rawBody)
+}), B = /* @__PURE__ */ new Set([
 	"POST",
 	"PUT",
 	"PATCH",
 	"DELETE"
-]), N = (l, u) => {
-	let d = l.input ? c.decodeUnknown(l.input) : void 0, f = c.encode(l.output), p = {}, m = (e) => e.replace(/\/$/, "").split("/").length, h = m(l.path);
-	return l.deprecated !== void 0 && (p.Deprecation = "true"), l.sunset !== void 0 && (p.Sunset = l.sunset), {
+]), V = (e, n, r, i) => {
+	if (e instanceof E) return F(e.status, e.body, {
+		...i,
+		...e.headers
+	});
+	if (typeof e == "object" && e) {
+		let r = e;
+		if (typeof r.status == "number") return F(r.status, { error: typeof r.message == "string" ? r.message : "Error" }, i);
+		if (r._tag === "Unauthenticated" || e instanceof t) return F(401, { error: typeof r.reason == "string" ? r.reason : "Authentication required" }, i);
+		if (r._tag === "ScopeError") return F(n.type === "anonymous" ? 401 : 403, { error: typeof r.message == "string" ? r.message : "Forbidden" }, i);
+	}
+	return o({
+		error: e,
+		source: "rest",
+		name: `${r.method} ${r.path}`,
+		fields: { status: 500 }
+	}), F(500, { error: "Internal Server Error" }, i);
+}, H = (o, l) => {
+	let u = o.input ? c.decodeUnknown(o.input) : void 0, d = c.encode(o.output), f = {}, p = (e) => e.replace(/\/$/, "").split("/").length, m = p(o.path);
+	return o.deprecated !== void 0 && (f.Deprecation = "true"), o.sunset !== void 0 && (f.Sunset = o.sunset), {
 		method: "*",
-		path: l.path,
-		...l.maxBodyBytes === void 0 ? {} : { maxBodyBytes: l.maxBodyBytes },
+		path: o.path,
+		...o.maxBodyBytes === void 0 ? {} : { maxBodyBytes: o.maxBodyBytes },
 		handle: async (c) => {
-			if (!l.path.endsWith("/*") && m(c.path) !== h) return D(404, { error: "Not Found" }, p);
-			let y = c.method.toUpperCase();
-			if (!(y === l.method || y === "HEAD" && l.method === "GET")) return D(405, {
+			if (!o.path.endsWith("/*") && p(c.path) !== m) return F(404, { error: "Not Found" }, f);
+			let h = c.method.toUpperCase();
+			if (!(h === o.method || h === "HEAD" && o.method === "GET")) return F(405, {
 				error: "Method Not Allowed",
-				allow: l.method
+				allow: o.method
 			}, {
-				...p,
-				Allow: l.method
+				...f,
+				Allow: o.method
 			});
-			if (l.sunset !== void 0) {
-				let e = Date.parse(l.sunset);
-				if (!Number.isNaN(e) && Date.now() >= e) return D(410, {
+			if (o.sunset !== void 0) {
+				let e = Date.parse(o.sunset);
+				if (!Number.isNaN(e) && Date.now() >= e) return F(410, {
 					error: "Gone",
-					...l.version === void 0 ? {} : { version: l.version },
-					...l.deprecated === void 0 ? {} : { replacement: l.deprecated }
-				}, p);
+					...o.version === void 0 ? {} : { version: o.version },
+					...o.deprecated === void 0 ? {} : { replacement: o.deprecated }
+				}, f);
 			}
-			let b;
-			if (d) {
-				let e = j(c, A(l.path, c.path)), t = await s.runPromise(d(e).pipe(s.map((e) => ({
+			let g;
+			if (u) {
+				let e = z(c, R(o.path, c.path)), t = await s.runPromise(u(e).pipe(s.map((e) => ({
 					ok: !0,
 					value: e
 				})), s.catchAll((e) => s.succeed({
 					ok: !1,
 					cause: e
 				}))));
-				if (!t.ok) return D(400, {
+				if (!t.ok) return F(400, {
 					error: "Invalid request",
 					detail: String(t.cause)
-				}, p);
-				b = t.value;
+				}, f);
+				g = t.value;
 			}
-			let x;
+			let _;
 			try {
-				x = u.resolveSubject ? await u.resolveSubject(c.headers) : e(c.headers["x-tenant"] ?? null);
+				_ = l.resolveSubject ? await l.resolveSubject(c.headers) : e(c.headers["x-tenant"] ?? null);
 			} catch (e) {
 				if (e instanceof t || typeof e == "object" && e && e._tag === "Unauthenticated") {
 					let t = e.reason;
-					return D(401, { error: t ?? "Authentication required" }, p);
+					return F(401, { error: t ?? "Authentication required" }, f);
 				}
 				throw e;
 			}
-			let S = u.buildContext ? await u.buildContext(x, c.headers) : void 0, w = typeof S == "object" && S && "store" in S ? S.store : u.store, O = {
-				subject: x,
+			let v;
+			try {
+				v = l.buildContext ? await l.buildContext(_, c.headers) : void 0;
+			} catch (e) {
+				return V(e, _, o, f);
+			}
+			let y = typeof v == "object" && v && "store" in v ? v.store : l.store, b = {
+				subject: _,
 				headers: c.headers,
-				store: w,
-				method: y,
+				store: y,
+				method: h,
 				path: c.path,
 				query: c.query,
 				rawBody: c.rawBody,
-				...S === void 0 ? {} : { app: S }
+				...v === void 0 ? {} : { app: v }
 			};
-			if (l.guards) for (let e of l.guards) {
-				let t = await e(O);
-				if (t) return D(t.status, { error: t.message }, p);
+			if (o.guards) for (let e of o.guards) {
+				let t = await e(b);
+				if (t) return F(t.status, { error: t.message }, f);
 			}
-			let k = u.idempotency, N = k && M.has(l.method) ? c.headers[k.header.toLowerCase()] : void 0, P = k && N ? r(x.tenantId, l.method, l.path) : "";
-			if (k && N) {
-				let e = await i(k.store, P, N, k.ttlMs, Date.now());
-				if (e.kind === "replay") return D(e.response.status, e.response.body, {
-					...p,
+			let x = l.idempotency, S = x && B.has(o.method) ? c.headers[x.header.toLowerCase()] : void 0, C = x && S ? r(_.tenantId, o.method, o.path) : "";
+			if (x && S) {
+				let e = await i(x.store, C, S, x.ttlMs, Date.now());
+				if (e.kind === "replay") return F(e.response.status, e.response.body, {
+					...f,
 					"Idempotency-Replayed": "true"
 				});
-				if (e.kind === "conflict") return D(409, { error: "A request with this Idempotency-Key is already being processed" }, p);
+				if (e.kind === "conflict") return F(409, { error: "A request with this Idempotency-Key is already being processed" }, f);
 			}
 			try {
-				let e = await l.handler(b, O);
-				if (C(e) || T(e)) return k && N && await a(k.store, P, N), T(e) ? {
+				let e = await o.handler(g, b);
+				if (j(e) || N(e)) return x && S && await a(x.store, C, S), N(e) ? {
 					status: e.status ?? 200,
 					headers: {
-						...p,
+						...f,
 						...e.headers
 					},
 					byteStream: e.byteStream,
 					...e.contentType === void 0 ? {} : { contentType: e.contentType }
 				} : {
 					status: 200,
-					headers: p,
+					headers: f,
 					stream: e.stream
 				};
-				let t = _(e) ? e : g(e), r = await s.runPromise(f(t.body)), i = {
-					...p,
+				let t = T(e) ? e : w(e), r = await s.runPromise(d(t.body)), i = {
+					...f,
 					...t.headers
 				};
-				if (k && N && await n(k.store, P, N, {
+				if (x && S && await n(x.store, C, S, {
 					status: t.status,
 					body: r
-				}, Date.now()), l.etag === !0 && l.method === "GET") {
-					let e = `W/"${await E(JSON.stringify(r))}"`, n = c.headers["if-none-match"];
+				}, Date.now()), o.etag === !0 && o.method === "GET") {
+					let e = `W/"${await P(JSON.stringify(r))}"`, n = c.headers["if-none-match"];
 					return n !== void 0 && n.split(",").some((t) => t.trim() === e) ? {
 						status: 304,
 						headers: {
-							...p,
+							...f,
 							ETag: e
 						}
-					} : D(t.status, r, {
+					} : F(t.status, r, {
 						...i,
 						ETag: e
 					});
@@ -223,34 +338,21 @@ var l = (e, t) => t.method ?? (e === "query" ? "GET" : "POST"), u = (e, t) => t.
 				return t.status === 204 || t.status === 304 ? {
 					status: t.status,
 					headers: i
-				} : D(t.status, r, i);
+				} : F(t.status, r, i);
 			} catch (e) {
-				if (k && N && await a(k.store, P, N), e instanceof v) return D(e.status, e.body, {
-					...p,
-					...e.headers
-				});
-				if (typeof e == "object" && e && typeof e.status == "number") {
-					let t = e;
-					return D(t.status, { error: t.message ?? "Error" }, p);
-				}
-				return o({
-					error: e,
-					source: "rest",
-					name: `${l.method} ${l.path}`,
-					fields: { status: 500 }
-				}), D(500, { error: "Internal Server Error" }, p);
+				return x && S && await a(x.store, C, S), V(e, _, o, f);
 			}
 		}
 	};
-}, P = (e, t = {}) => {
+}, U = (e, t = {}) => {
 	if (t.idempotency !== void 0) {
-		for (let t of e) if (t.streaming === !0 && M.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...M].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
+		for (let t of e) if (t.streaming === !0 && B.has(t.method)) throw Error(`REST route ${t.method} ${t.path} declares \`streaming: true\` on a method the idempotency binding claims (${[...B].join("/")}). A stream cannot complete an idempotency claim — there is no replayable body to cache — so a retried request would 409 until the claim's TTL. Either serve the stream on GET, or scope the idempotency binding away from this app's streaming routes.`);
 	}
-	return e.map((e) => N(e, t));
-}, F = async (e, t) => {
+	return e.map((e) => H(e, t));
+}, W = async (e, t) => {
 	let n = await e[0].handle(t);
 	for (let r = 1; r < e.length && n.status === 405; r++) n = await e[r].handle(t);
 	return n;
 };
 //#endregion
-export { v as RestRouteError, w as bytes, f as collectPublicApiRoutes, b as defineRestRoute, l as derivePublicMethod, u as derivePublicPath, F as dispatchSharedPath, T as isRestByteResponse, _ as isRestResponse, C as isRestStreamResponse, A as matchPathParams, d as publicApiRoute, h as requireAnyScope, p as requireAuthenticated, m as requireScope, g as response, y as restError, P as restRoutesToHttpRoutes, x as sse, S as sseFrame };
+export { E as RestRouteError, M as bytes, h as coerceQueryObject, m as coerceQueryValue, b as collectPublicApiRoutes, g as declaredErrorTags, O as defineRestRoute, u as derivePublicMethod, d as derivePublicPath, W as dispatchSharedPath, N as isRestByteResponse, T as isRestResponse, j as isRestStreamResponse, R as matchPathParams, v as projectedFailure, y as publicApiRoute, C as requireAnyScope, x as requireAuthenticated, S as requireScope, w as response, D as restError, U as restRoutesToHttpRoutes, k as sse, A as sseFrame };

package/package.json

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