@voltro/protocol 0.69.0 → 0.70.0

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,12 +105,28 @@ 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
  * `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
@@ -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
@@ -162,6 +182,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;
@@ -286,6 +321,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,
@@ -307,6 +344,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
@@ -355,6 +394,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). */
@@ -370,6 +417,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.
@@ -391,6 +447,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
@@ -398,9 +498,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
@@ -573,6 +686,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
@@ -629,6 +749,28 @@ 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); 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, pluginErrors?: ReadonlyArray<PluginErrorSchema>) => 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>;
 
@@ -647,16 +789,47 @@ 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;
+}
+
+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, 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.
+ * 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. */
@@ -683,6 +856,48 @@ 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;
 }
 
 /**
@@ -819,11 +1034,22 @@ 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;
+
 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. */
@@ -839,8 +1065,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>;
 
 /**
@@ -855,6 +1158,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
@@ -864,6 +1171,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;
 }
 
 /**
@@ -911,6 +1220,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
@@ -962,7 +1282,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 {
@@ -970,6 +1292,36 @@ 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';
+    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
@@ -1017,6 +1369,32 @@ 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 router matches case-folded and
+ * ignores a trailing slash; the dispatcher asks this, 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
@@ -1135,6 +1513,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';