@voltro/protocol 0.69.1 → 0.71.0

package/dist/rest.d.ts

@@ -126,7 +126,7 @@ export declare const coerceQueryValue: (value: unknown, ast: AST.AST) => unknown
  * route, in stable (path) order. The boot layer feeds these straight into
  * `restRoutesToHttpRoutes` alongside any hand-authored `restRoutes`.
  */
-export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEntry>) => ReadonlyArray<RestRouteDescriptor<Record<string, unknown>, unknown>>;
+export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEntry>, options?: PublicApiProjectionOptions) => ReadonlyArray<RestRouteDescriptor<Record<string, unknown>, unknown>>;
 
 /**
  * What a descriptor CARRIES: the author's guards, or the erased form of their
@@ -159,11 +159,22 @@ declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input
 }
 
 /** query→GET, mutation/action→POST, unless the spec overrides. */
-export declare const derivePublicMethod: (kind: PublicApiDescriptor["kind"], spec: PublicApiSpec) => RestMethod;
+export declare const derivePublicMethod: (kind: PublicApiDescriptor["kind"], spec: PublicApiSpec, descriptor?: ResourceDescriptorFacts) => RestMethod;
 
 /** `/<version>/<tag-with-dots-as-slashes>` unless the spec gives an explicit
- *  path. `orders.create` @ v1 → `/v1/orders/create`. */
-export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => string;
+ *  path, or `resource` derives one. `orders.create` @ v1 → `/v1/orders/create`. */
+export declare const derivePublicPath: (tag: string, spec: PublicApiSpec, descriptor?: ResourceDescriptorFacts) => string;
+
+/**
+ * `publicApi.resource`: method and path from the resource, the descriptor's
+ * kind and target, and whether the input identifies one row — the convention
+ * `crud.*` already follows, so a surface of hundreds of projections is not
+ * hundreds of hand-written paths.
+ */
+export declare const deriveResource: (tag: string, spec: PublicApiSpec, descriptor: ResourceDescriptorFacts) => {
+    readonly method: RestMethod;
+    readonly path: string;
+};
 
 /**
  * Dispatch a request across REST routes that SHARE a path. Every REST route
@@ -182,6 +193,21 @@ export declare const derivePublicPath: (tag: string, spec: PublicApiSpec) => str
  */
 export declare const dispatchSharedPath: (group: ReadonlyArray<PluginHttpRoute>, req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
 
+/** 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;
+
+/** The member of an error union that declares `tag`, as a schema of its own —
+ *  for the spec's per-status responses. */
+export declare const errorMemberSchema: (error: Schema.Schema.All | undefined, tag: string) => Schema.Schema.All | undefined;
+
 /** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
  *  descriptor carries a top-level `description`; callers pass that in. */
 declare type ExposeAsTool = boolean | ExposeAsToolSpec;
@@ -306,6 +332,8 @@ export declare const isRestResponse: (value: unknown) => value is RestResponse<u
 
 export declare const isRestStreamResponse: (v: unknown) => v is RestStreamResponse;
 
+export declare const JSONAPI_MEDIA_TYPE = "application/vnd.api+json; charset=utf-8";
+
 /** Extract `:name` path params by aligning the route PATTERN with the request
  *  path segment-by-segment (`/projects/:project/deploy` + `/projects/acme/deploy`
  *  → `{ project: 'acme' }`). `PluginHttpRouteRequest` carries no matched params,
@@ -327,6 +355,8 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
      * 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
@@ -375,6 +405,14 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
     readonly internal: boolean | undefined;
 }
 
+/** Same-resource ordering for a mutation's calls on the client — see `defineMutation`'s `serialize`. */
+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;
+}
+
 declare interface NestedTargetFields<Input = unknown> {
     /** Dot-path to the nested array within the query VALUE to patch (e.g.
      *  `'snapshot.projects'`). Absent → patch the top-level row array (default). */
@@ -390,6 +428,15 @@ 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;
+
+/** `{teamId}` — the form every guideline writes first — is the same route as
+ *  `:teamId`; the desugar matches the colon form, so the path is normalised
+ *  once here. */
+export declare const normalizePathParams: (path: string) => string;
+
 /**
  * The runtime-erased form of a procedure's `openAccess:` — a DECLARED decision
  * that this procedure needs no authorization check, and the reason.
@@ -411,6 +458,50 @@ declare interface OpenAccessSpec {
     readonly open: string;
 }
 
+/** The rpc tag as an `operationId`: `teams.list` → `teamsList`. */
+export declare const operationIdOf: (tag: string) => string;
+
+/** The parameter names a route pattern binds, in order. */
+export declare const pathParamNames: (path: string) => ReadonlyArray<string>;
+
+/**
+ * A cross-cutting error schema a plugin merges into EVERY procedure's
+ * wire error union. Use when a plugin interceptor can fail with a typed
+ * error (e.g. a rate-limit `RateLimited`) that must decode TYPED on the
+ * client rather than crossing as an untyped defect.
+ *
+ * Two halves because the error must be applied in two places that can't
+ * share a value:
+ *   - `schema`: the live `effect/Schema` — used at runtime when the cli
+ *     assembles the SERVER rpc group.
+ *   - `import`: where to import the same schema from — used by codegen to
+ *     emit the import into the generated CLIENT rpc group, so both ends
+ *     agree on the wire shape. `name` must be the exported identifier.
+ *
+ * Requires the plugin to ship the schema as a NAMED export from `module`.
+ */
+declare interface PluginErrorSchema {
+    readonly schema: Schema.Schema.All;
+    readonly import: {
+        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. */
 declare interface PluginHttpRoute {
     /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
@@ -418,9 +509,22 @@ 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
@@ -593,6 +697,13 @@ 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
@@ -641,7 +752,7 @@ declare interface PluginHttpRouteStream {
  */
 declare interface PolicyGuardSpec<Input = unknown> {
     /** The action to authorize, as named in the resource policy's `actions`. */
-    readonly action: string;
+    readonly action: string | ((input: Input) => string);
     /** Which registered resource policy governs the check. */
     readonly resourceType: string;
     /** PURE `input → resource id`. Returning undefined DENIES — an unidentifiable
@@ -649,15 +760,47 @@ 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;
+
 /**
  * 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).
+ * OpenAPI projection already documents for a typed error); a plugin's
+ * cross-cutting error answers under the status the plugin names. Anything
+ * else is rethrown for the desugar's shared mapping (`ScopeError` → 403/401, a
+ * `status`-carrying error → itself, the rest → 500). The body is the tagged
+ * `{ error, …fields }` form; `projectedFailureFor` speaks the profile.
  */
-export declare const projectedFailure: (err: unknown, descriptor: PublicApiDescriptor, spec: PublicApiSpec) => unknown;
+export declare const projectedFailure: (err: unknown, descriptor: PublicApiDescriptor, spec: PublicApiSpec, pluginErrors?: ReadonlyArray<PluginErrorSchema>) => unknown;
+
+/** The generated TypeScript client, as the app declares it. */
+export declare interface PublicApiClientConfig {
+    /** The npm package name. Default `@app/api-client`. */
+    readonly package?: string;
+    /** Where the package is written, relative to the app root. Default `sdk/typescript`. */
+    readonly out?: string;
+    /** `'plain'` — the Promise client, no Effect anywhere; `'effect'` — the
+     *  Effect service; `'both'` — `.` plain and `./effect` Effect, with `effect`
+     *  an optional peer. Default `'both'`. */
+    readonly flavor?: 'plain' | 'effect' | 'both';
+    /** The package's `license` field (an SPDX id). */
+    readonly license?: string;
+    /** The package's version. Default `0.1.0`. */
+    readonly packageVersion?: string;
+    /** Generate for ONE API version (`'v2'`). */
+    readonly apiVersion?: string;
+    /** The client's default base URL. */
+    readonly baseUrl?: string;
+}
 
 /** 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>;
@@ -677,23 +820,87 @@ export declare interface PublicApiEntry {
  *  handler through the SAME AuthMiddleware/RBAC/tenant/audit as the rpc path. */
 export declare type PublicApiInvoke = (input: unknown, ctx: RestRouteContext) => Promise<unknown> | unknown;
 
+/** 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;
+    /** `'required'`: `voltro doctor` reports a projection without a
+     *  `description` and an input/output field without a `description`
+     *  annotation — so a new projection does not reach the surface without text.
+     *  Default `'optional'`. */
+    readonly docs?: 'required' | 'optional';
+    /**
+     * Files `voltro dev` writes beside `rpcGroup.generated.ts` on every boot, from
+     * the mounted surface: `'openapi'` (`openapi.generated.json`) and the
+     * collections — `'postman'`, `'bruno'`, `'insomnia'`, `'hoppscotch'` — as
+     * committed, generated files, so a review diff shows the surface change and
+     * a client imported once cannot drift; `'typescript'` keeps the generated
+     * client package (`client`) written the same way. Off by default.
+     */
+    readonly artifacts?: ReadonlyArray<'openapi' | 'postman' | 'bruno' | 'insomnia' | 'hoppscotch' | 'typescript'>;
+    /**
+     * The app's decision about its generated TypeScript client — what
+     * `voltro build api --target typescript` (and `voltro api-client build`)
+     * produces without flags, and what `voltro dev` keeps written when
+     * `artifacts` names `'typescript'`. `voltro api-client set …` writes this
+     * block; a flag on the command line overrides a field for one run.
+     */
+    readonly client?: PublicApiClientConfig;
+}
+
+export declare type PublicApiProfileName = 'rpc' | 'standard' | 'jsonapi';
+
+/** What a projection needs beyond its descriptor: the errors every mounted
+ *  plugin may fail a call with, and the app's `publicApi` profile. */
+export declare interface PublicApiProjectionOptions {
+    readonly pluginErrors?: ReadonlyArray<PluginErrorSchema>;
+    /** The `publicApi:` block of the api's `app.config.ts`. Absent → `'rpc'`. */
+    readonly profile?: PublicApiProfileConfig;
+}
+
 /**
- * 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 — 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.
+ * Synthesize the public REST route for ONE descriptor.
+ *
+ * The input arrives as `{ query, params, body }` from the desugar and is
+ * assembled into ONE object — the query (GET) or body (else), plus every
+ * path parameter bound to the input field of the same name — coerced toward
+ * the input's encoded shape (a query string and a path carry strings), then
+ * decoded by the input schema in the profile's wire form (`restViewSchema`).
+ * The handler receives the descriptor's typed input; its output is encoded to
+ * the wire form and enveloped by the profile. 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>;
+export declare const publicApiRoute: (descriptor: PublicApiDescriptor, invoke: PublicApiInvoke, subscribe?: PublicApiSubscribe, options?: PublicApiProjectionOptions) => RestRouteDescriptor<Record<string, unknown>, unknown>;
 
 declare interface PublicApiSpec {
     /** Derived by kind when omitted: query→GET, mutation/action→POST. */
     readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /** Derived from the tag + version when omitted: `/<version>/<tag-as-path>`. */
     readonly path?: string;
+    /**
+     * Derive method and path from the resource instead of writing them — the
+     * convention `crud.*` already follows, opt-in per descriptor. `'teams'` on a
+     * query whose input carries `teamId` or `id` → `GET /v1/teams/{teamId}`,
+     * without one → `GET /v1/teams`; on a mutation whose `target.op` is
+     * `insert` → `POST /v1/teams`, `update` → `PATCH /v1/teams/{teamId}`,
+     * `delete` → `DELETE /v1/teams/{teamId}`; an action, or a mutation without
+     * a target, → `POST /v1/teams/{teamId}/<verb>` (the tag's last segment) when
+     * the input carries the id, else `POST /v1/teams/<verb>`. An explicit
+     * `method` or `path` wins over the derivation.
+     */
+    readonly resource?: string;
     /** Path version segment; multiple versions coexist as separate descriptors. */
     readonly version?: string;
     /** Additional API-key scopes required ON TOP of the handler's RBAC. */
@@ -725,6 +932,37 @@ 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;
 }
 
 /**
@@ -739,6 +977,16 @@ export declare type PublicApiSubscribe = (input: unknown, ctx: RestRouteContext,
     readonly [k: string]: unknown;
 }) => void) => () => void;
 
+/**
+ * The digest of a public surface: every projection's facts (tag, method, path,
+ * parameters, version, security, the typed errors and their statuses) and the
+ * SHAPE of its wire schemas, in tag order. The OpenAPI document publishes it as
+ * `x-voltro-surface-digest`, a generated client carries the one it was built
+ * from, and `voltro check --public-api --against` compares the two — so one
+ * number says whether a consumer's client still describes the API it calls.
+ */
+export declare const publicSurfaceDigest: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => string;
+
 /**
  * Server-side snapshot caching for a query (see `defineQuery`). When set,
  * the dispatcher caches the initial snapshot result and auto-invalidates it
@@ -861,11 +1109,35 @@ export declare const requireAuthenticated: () => RestGuard;
  */
 export declare const requireScope: (scope: string) => RestGuard;
 
+/**
+ * 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;
+
+/** What `resource` derivation reads off a descriptor. */
+export declare interface ResourceDescriptorFacts {
+    readonly kind: 'query' | 'mutation' | 'action' | 'stream';
+    readonly input?: unknown;
+    readonly target?: {
+        readonly op?: string;
+    } | undefined;
+}
+
+/** The input field that identifies one row of `resource`: `<singular>Id`,
+ *  then `id`; `undefined` when the input names neither (a list, a create). */
+export declare const resourceIdField: (resource: string, input: unknown) => string | undefined;
+
 export declare const response: <O>(body: O, options?: {
     readonly status?: number;
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+    readonly contentType?: string;
 }) => RestResponse<O>;
 
+export declare const REST_PROFILE_NAMES: ReadonlyArray<PublicApiProfileName>;
+
 /** A BINARY streaming response (download/export). The serve layer pipes the
  *  ReadableStream without buffering — a body larger than the heap is fine.
  *  The LAZY thunk form defers opening the source until the response streams. */
@@ -881,8 +1153,85 @@ export declare interface RestByteResponse {
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
 }
 
+export declare type RestDates = 'iso' | 'epoch-ms';
+
+export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
+
 export declare const restError: (status: number, body: unknown, headers?: Readonly<Record<string, string | ReadonlyArray<string>>>) => RestRouteError;
 
+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;
+}
+
 export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -897,6 +1246,10 @@ export declare interface RestGuardRejection {
 
 export 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
@@ -906,6 +1259,8 @@ export 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;
 }
 
 /**
@@ -953,6 +1308,17 @@ export 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
@@ -1004,7 +1370,9 @@ export declare class RestRouteError extends Error {
     readonly status: number;
     readonly body: unknown;
     readonly headers: Readonly<Record<string, string | ReadonlyArray<string>>> | undefined;
-    constructor(status: number, body: unknown, headers?: Readonly<Record<string, string | ReadonlyArray<string>>>);
+    /** A media type other than `application/json` (`application/problem+json`). */
+    readonly contentType: string | undefined;
+    constructor(status: number, body: unknown, headers?: Readonly<Record<string, string | ReadonlyArray<string>>>, contentType?: string);
 }
 
 export declare interface RestRouteExample {
@@ -1012,6 +1380,39 @@ export 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.
+ */
+export declare interface RestRouteProjection {
+    readonly tag: string;
+    readonly kind: 'query' | 'mutation' | 'action';
+    readonly version: string;
+    readonly security: 'required' | 'optional' | 'none';
+    /** `publicApi.idempotent` — the route honours `Idempotency-Key` (under the
+     *  app's idempotency binding); a client sends one per attempt. */
+    readonly idempotent: boolean;
+    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;
+}
+
 /**
  * Desugar a list of REST descriptors into `PluginHttpRoute[]` ready to
  * spread into a plugin/app's `httpRoutes`. `bindings` is supplied by the
@@ -1059,6 +1460,33 @@ export declare interface RestStreamResponse {
     readonly stream: PluginHttpRouteStream;
 }
 
+/**
+ * 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;
+
+/**
+ * Whether `path` is one the route declared. The underlying router folds case
+ * and trailing slashes when selecting candidates; this dispatcher deliberately
+ * rejects those undeclared aliases. It checks byte for byte: a literal
+ * segment must be equal, a `:name` segment takes one non-empty segment, and
+ * beyond the declared segments a `'prefix'` route (the default) owns any
+ * sub-path while an `'exact'` route owns nothing. A trailing slash alone is
+ * not a sub-path — `/metrics/` is nobody's, whatever the mode. An explicit
+ * `/*` tail is a prefix by itself.
+ */
+export declare const routeAcceptsPath: (route: {
+    readonly path: string;
+    readonly match?: "prefix" | "exact" | undefined;
+}, path: string) => boolean;
+
 /**
  * Build a streaming (Server-Sent Events) handler result. `subscribe` gets an
  * `emit` for one already-framed SSE chunk and MUST return an unsubscribe, which
@@ -1093,6 +1521,11 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     type: Schema.Literal<["serviceAccount"]>;
     id: typeof Schema.String;
     tenantId: typeof Schema.String;
+    /** Application actor used for audit columns; null means machine work with
+     * no application actor. Identity only, never a permission grant. */
+    auditActorId: Schema.optionalWith<Schema.NullOr<typeof Schema.String>, {
+        exact: true;
+    }>;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
@@ -1177,6 +1610,8 @@ declare type TargetRelations = Readonly<Record<string, TargetRelation>>;
 
 declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 
+export declare const toSnakeCase: (key: string) => string;
+
 declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'update';
@@ -1194,4 +1629,12 @@ declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<str
     readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
+export declare const wireExample: (example: {
+    readonly request?: unknown;
+    readonly response?: unknown;
+}, wireInput: Schema.Schema.All, wireOutput: Schema.Schema.All) => {
+    readonly request?: unknown;
+    readonly response?: unknown;
+};
+
 export { }