@voltro/protocol 0.69.0 → 0.70.0

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';
@@ -4099,6 +4209,48 @@ 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>>;
+    /**
+     * 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;
 }
 
 /**
@@ -4366,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
@@ -4393,6 +4553,263 @@ 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>;
+
+/**
+ * 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';
+
+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
+ *  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>>>;
+    /** A media type other than `application/json` (a JSON:API document). */
+    readonly contentType?: 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;
+    /** 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
+     *  `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;
+}
+
+/**
+ * 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;
 
@@ -4563,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;
 }
 
 /**
@@ -4959,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<{
@@ -4995,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>>;
 }>]>;
@@ -5034,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?: {
@@ -5404,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`.
@@ -5991,6 +6418,28 @@ 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;
+    /**
+     * 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;
 }
 
 /**