@voltro/protocol 0.69.1 → 0.71.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
@@ -3584,6 +3667,13 @@ export declare interface PluginInspectRequest {
 }
 
 export declare type PluginInspectResponse = {
+    readonly kind: 'bytes';
+    readonly status?: number;
+    readonly contentType: string;
+    readonly byteStream: PluginHttpRouteByteStream;
+    /** Download metadata; transport-owned auth/CORS headers cannot be overridden. */
+    readonly headers?: Readonly<Record<string, string>>;
+} | {
     readonly kind: 'json';
     readonly status?: number;
     readonly data: unknown;
@@ -3999,7 +4089,7 @@ export declare type PluginUninstallHook = (ctx: PluginLifecycleContext) => Effec
 
 /** The runtime-erased form of `PolicyGuardSpec` — a relationship check. */
 export declare interface PolicyCheckSpec {
-    readonly action: string;
+    readonly action: string | ((input: unknown) => string);
     readonly resourceType: string;
     readonly resource: (input: unknown) => string | undefined;
 }
@@ -4044,7 +4134,7 @@ export declare type PolicyGuardResolver = (req: PolicyGuardRequest) => Effect.Ef
  */
 export 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
@@ -4052,6 +4142,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,11 +4174,82 @@ export declare const PROTOCOL_VERSION: 1;
 
 export declare type ProtocolVersion = typeof PROTOCOL_VERSION;
 
+/** 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;
+}
+
+/** 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';
+
 export 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. */
@@ -4110,6 +4281,37 @@ export declare interface PublicApiSpec {
      *     publicApi: { errorStatus: { AccessDeniedError: 403, NotFoundError: 404 } }
      */
     readonly errorStatus?: Readonly<Record<string, number>>;
+    /**
+     * The spec's tag group(s) for this operation. Default: the rpc tag's prefix
+     * (`teams.list` → `teams`) — the first path segment, what a consumer looks
+     * for, and what an SDK generator turns into a client class.
+     */
+    readonly tags?: ReadonlyArray<string>;
+    /**
+     * The spec's `operationId`. Default: the rpc tag in camelCase (`teams.list`
+     * → `teamsList`) — the stable identifier a generator names methods from.
+     */
+    readonly operationId?: string;
+    /**
+     * Whether the operation documents a bearer requirement. Default: `'required'`
+     * unless the descriptor declares `openAccess` — then `'optional'` (the key
+     * strategy authenticates a bearer when one is sent, and an anonymous caller
+     * is allowed through), which Swagger UI and generated clients read as
+     * "send the token when you have one". `false` documents no scheme at all.
+     */
+    readonly security?: 'required' | 'optional' | false;
+    /** A request/response example for the spec — the same semantics as a
+     *  `defineRestRoute` example. */
+    readonly example?: {
+        readonly request?: unknown;
+        readonly response?: unknown;
+    };
+    /**
+     * This projection's wire format, overriding the app's `publicApi` profile
+     * (`app.config.ts`) for the one endpoint that must differ — every field
+     * optional, the rest inherited. See `PublicApiProfileConfig`.
+     */
+    readonly format?: PublicApiProfileConfig;
 }
 
 /**
@@ -4377,6 +4579,19 @@ 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;
 
+/** Resolve the input-selected action once. Invalid selectors deny rather than
+ * widening to any action the subject happens to hold. Also used when an
+ * approval persists the resolved guard for its later recheck. */
+export declare const resolvePolicyAction: (guard: PolicyCheckSpec, input: unknown) => string;
+
+/**
+ * The format one projection speaks: the app profile, then its building-block
+ * overrides, then the descriptor's own `format`. A named profile is a
+ * `RestFormat` with a name; an object is taken as-is and its fields overridden
+ * the same way.
+ */
+export declare const resolveRestFormat: (config: PublicApiProfileConfig | undefined, override?: Partial<PublicApiProfileConfig> | undefined) => RestFormat;
+
 /**
  * Validate an author's access options and normalise them into the array every
  * enforcement path reads. Throws at DEFINITION time — module load, which is
@@ -4404,6 +4619,85 @@ export declare interface ResourceScopeRequest {
  */
 export declare type ResourceScopeResolver = (req: ResourceScopeRequest) => Effect.Effect<boolean, unknown>;
 
+export declare const REST_PROFILE_NAMES: ReadonlyArray<PublicApiProfileName>;
+
+export declare type RestDates = 'iso' | 'epoch-ms';
+
+export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
+
+export declare type RestErrors = 'problem-details' | 'tagged';
+
+/**
+ * The wire format of one `publicApi` surface. `'standard'` and `'jsonapi'` are
+ * named instances of this; an app's own object is the custom case.
+ */
+export declare interface RestFormat {
+    readonly name: string;
+    /** `timestampMs` fields: RFC 3339 strings, or the epoch milliseconds the rpc wire carries. */
+    readonly dates: RestDates;
+    /** Failures: RFC 9457 `application/problem+json`, or the tagged object rpc carries. */
+    readonly errors: RestErrors;
+    /** Success bodies: the bare value, `{ data }`, or the JSON:API document. */
+    readonly envelope: RestEnvelope;
+    /** A cursor the handler returns in `cursorField`: as a `Link: <…>; rel="next"`
+     *  header (and `next` beside `data`), or left where the handler put it. */
+    readonly pagination: RestPagination;
+    /** The cursor field a paginated output carries. Default `nextCursor`. */
+    readonly cursorField: string;
+    /** The query parameter a cursor travels back in. Default `cursor`. */
+    readonly cursorParam: string;
+    /** Property names on the wire. */
+    readonly naming: RestNaming;
+    /** Weak `ETag` on GET answers, `If-None-Match` → 304. */
+    readonly etag: boolean;
+    /** Custom success encoding — receives the value already in wire form (dates,
+     *  naming applied). Replaces the envelope/pagination steps. */
+    readonly encodeSuccess?: (value: unknown, ctx: RestFormatContext) => RestFormatResponse;
+    /** Custom error encoding. Replaces `errors`. */
+    readonly encodeError?: (error: RestFormatError, ctx: RestFormatContext) => RestFormatResponse;
+    /** A hook over the OpenAPI operation the plugin emits for a projection. */
+    readonly describe?: (operation: Record<string, unknown>, ctx: {
+        readonly tag: string;
+        readonly method: string;
+        readonly path: string;
+    }) => Record<string, unknown>;
+}
+
+/** What a format sees when it encodes one response. */
+export declare interface RestFormatContext {
+    /** The rpc tag, e.g. `teams.list`. */
+    readonly tag: string;
+    readonly method: string;
+    /** The request path, for `Link` headers. */
+    readonly path: string;
+    /** The request's query string (without `?`). */
+    readonly query: string;
+    /** The first `source` table of the procedure, when it declares one — the
+     *  JSON:API resource `type`. */
+    readonly source: string | undefined;
+    readonly status: number;
+}
+
+/** A failure the desugar or the projection is about to answer with. */
+export declare interface RestFormatError {
+    readonly status: number;
+    /** The typed error's `_tag` (`AccessDeniedError`), or a stable name for a
+     *  transport failure (`InvalidRequest`, `Unauthorized`, `Forbidden`, …). */
+    readonly tag: string;
+    /** A human-readable line. */
+    readonly message: string;
+    /** The error's own fields (a typed error), without `_tag`. */
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+
+/** A response a format produced: body (already wire-shaped), headers, and the
+ *  media type when it is not `application/json`. */
+export declare interface RestFormatResponse {
+    readonly body: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly contentType?: string;
+}
+
 declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
@@ -4418,6 +4712,10 @@ declare interface RestGuardRejection {
 
 declare type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
+export declare type RestNaming = 'camelCase' | 'snake_case';
+
+export declare type RestPagination = 'link-header' | 'body-cursor';
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -4427,6 +4725,8 @@ declare interface RestResponse<O> {
     readonly status: number;
     readonly body: O;
     readonly headers?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+    /** A media type other than `application/json` (a JSON:API document). */
+    readonly contentType?: string;
 }
 
 /**
@@ -4474,6 +4774,17 @@ declare interface RestRouteDescriptor<I, O> {
     readonly summary?: string;
     readonly description?: string;
     readonly example?: RestRouteExample;
+    /** The spec's `operationId` — set by a `publicApi` projection from its tag. */
+    readonly operationId?: string;
+    /** The spec's tag group(s) — set by a projection from its tag prefix. */
+    readonly tags?: ReadonlyArray<string>;
+    /**
+     * Present on a `publicApi` projection: what the route projects, in the wire
+     * form its profile speaks. The OpenAPI generator documents parameters,
+     * bodies, responses and security from it; the desugar answers every refusal
+     * through its format.
+     */
+    readonly projection?: RestRouteProjection;
     /** Replacement hint. Sets a `Deprecation: true` response header. */
     readonly deprecated?: string;
     /** ISO date. Sets a `Sunset:` header; past the date the route returns
@@ -4523,6 +4834,51 @@ declare interface RestRouteExample {
     readonly response?: unknown;
 }
 
+/**
+ * What a `publicApi` projection is, for the two readers that need more than
+ * the route: the OpenAPI generator and the desugar's refusals. `input` and
+ * `output` are the WIRE schemas — the descriptor's, rewritten by the profile
+ * (`restViewSchema`): a `timestampMs` is a `date-time` string under
+ * `dates: 'iso'`, keys are snake_case under that naming. `input` carries the
+ * path parameters as fields; `pathParams` says which.
+ */
+declare interface RestRouteProjection {
+    readonly tag: string;
+    readonly kind: 'query' | 'mutation' | 'action';
+    readonly version: string;
+    readonly security: 'required' | 'optional' | 'none';
+    /** `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;
+}
+
+/**
+ * Rewrite a descriptor's schema into the shape the profile puts on the wire:
+ * `timestampMs` (`DateFromNumber`) becomes an RFC 3339 string under
+ * `dates: 'iso'`, and every struct's property names become `snake_case` under
+ * `naming: 'snake_case'` — as a transformation, so decoding a wire value yields
+ * the descriptor's own typed value and encoding the typed value yields the
+ * wire form. `JSONSchema.make` of the result documents the wire (a
+ * `format: date-time` string, the snake keys). Classes and other opaque
+ * transformations pass through unchanged; a struct inside one keeps its keys.
+ */
+export declare const restViewSchema: (schema: Schema.Schema.All, format: RestFormat) => Schema.Schema.All;
+
 /** The id of a row, addressed in op paths as `/<id>`. */
 export declare type RowId = string | number;
 
@@ -4693,6 +5049,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;
 }
 
 /**
@@ -5055,6 +5419,11 @@ export 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<{
@@ -5088,21 +5457,29 @@ export declare const Subject: Schema.Union<[Schema.Struct<{
 
 export declare type Subject = typeof Subject.Type;
 
+/** Resolve an application audit actor from server-established identity.
+ * Explicit null on a scoped machine identity survives persistence; it grants
+ * no authority and must not be inferred from user-provided metadata. */
+export declare const subjectAuditActorId: (subject: Subject) => string | null;
+
 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>>;
+    auditActorId: Schema.optionalWith<Schema.NullOr<typeof Schema.String>, {
+        exact: true;
+    }>;
 }>, Schema.Struct<{
     type: Schema.Literal<["anonymous"]>;
     id: typeof Schema.Null;
@@ -5125,8 +5502,8 @@ export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
      */
     credentialRejected: Schema.optional<typeof Schema.String>;
 }>, Schema.Struct<{
-    id: typeof Schema.String;
     type: Schema.Literal<["system"]>;
+    id: typeof Schema.String;
     tenantId: typeof Schema.Null;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
@@ -5164,37 +5541,38 @@ 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 auditActorId?: string | null;
 } | {
-    readonly id: null;
     readonly type: "anonymous";
+    readonly id: null;
     readonly tenantId: string | null;
     readonly credentialRejected?: string | undefined;
 } | {
-    readonly id: string;
     readonly type: "system";
+    readonly id: string;
     readonly tenantId: null;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
@@ -5534,6 +5912,8 @@ export declare const toRpc: <Name extends string, Input extends Schema.Schema.An
     revision: Schema.optional<typeof Schema.Number>;
 }>]>, Schema.Schema.All>, typeof Schema.Never, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Output, Schema.Schema.All>, typeof Schema.Never, never>;
 
+export declare const toSnakeCase: (key: string) => string;
+
 /**
  * Coerce a timestamp read (`Date` / epoch-ms number / ISO string) to
  * epoch milliseconds. Unrecognised inputs collapse to `0`.
@@ -6131,6 +6511,18 @@ export declare interface VoltroPlugin {
      * mounted when this runs, so the hook only records.
      */
     readonly onRestSurface?: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => void;
+    /**
+     * Told the app's wire-reachable rpc procedures — every query, mutation,
+     * action and stream discovery found, minus `internal` ones — once discovery
+     * has run, on both boot paths. The procedure counterpart of
+     * `onRestSurface`, for the same reason: a documentation plugin that wants
+     * the descriptors otherwise asks the app to import them into
+     * `app.config.ts`, which evaluates every descriptor module before discovery
+     * on every load of the config — and `voltro serve` loads no TypeScript at
+     * runtime, so a plugin cannot read them later either. Synchronous: records
+     * only.
+     */
+    readonly onProcedureSurface?: (procedures: ReadonlyArray<ProcedureDescriptor>) => void;
 }
 
 /**
@@ -6335,15 +6727,110 @@ export declare const WorkflowAccessProperty: unique symbol;
 export declare const workflowCancelDescriptor: ActionProcedureDescriptor<"__voltro.workflow.cancel", Schema.Struct<{
     workflowName: typeof Schema.String;
     executionId: typeof Schema.String;
-}>, Schema.Struct<{
-    ok: typeof Schema.Boolean;
-}>, typeof Schema.Never>;
+    control: Schema.optional<Schema.Struct<{
+        requestId: typeof Schema.NonEmptyString;
+        cause: Schema.optionalWith<Schema.Struct<{
+            reason: typeof Schema.NonEmptyString;
+            detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        }>, {
+            exact: true;
+        }>;
+    }>>;
+}>, Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel", "resume"]>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    snapshot: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: typeof Schema.String;
+        status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<Schema.Struct<{
+            tag: Schema.NullOr<typeof Schema.String>;
+            message: typeof Schema.String;
+        }>>;
+    }>;
+}>>, typeof Schema.Never>;
 
 export declare const WorkflowControlInputSchema: Schema.Struct<{
     workflowName: typeof Schema.String;
     executionId: typeof Schema.String;
+    control: Schema.optional<Schema.Struct<{
+        requestId: typeof Schema.NonEmptyString;
+        cause: Schema.optionalWith<Schema.Struct<{
+            reason: typeof Schema.NonEmptyString;
+            detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        }>, {
+            exact: true;
+        }>;
+    }>>;
+}>;
+
+export declare type WorkflowControlIntent = Schema.Schema.Type<typeof WorkflowControlIntentSchema>;
+
+/** Stable caller-owned intent for retry after an uncertain transport result. */
+export declare const WorkflowControlIntentSchema: Schema.Struct<{
+    requestId: typeof Schema.NonEmptyString;
+    cause: Schema.optionalWith<Schema.Struct<{
+        reason: typeof Schema.NonEmptyString;
+        detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>, {
+        exact: true;
+    }>;
+}>;
+
+export declare const workflowControlQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.control", Schema.Struct<{
+    workflowName: typeof Schema.NonEmptyString;
+    executionId: typeof Schema.NonEmptyString;
+    operation: Schema.Literal<["cancel", "resume"]>;
+    requestId: typeof Schema.NonEmptyString;
+}>, Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel", "resume"]>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    snapshot: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: typeof Schema.String;
+        status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<Schema.Struct<{
+            tag: Schema.NullOr<typeof Schema.String>;
+            message: typeof Schema.String;
+        }>>;
+    }>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowControlReadInput = Schema.Schema.Type<typeof WorkflowControlReadInputSchema>;
+
+export declare const WorkflowControlReadInputSchema: Schema.Struct<{
+    workflowName: typeof Schema.NonEmptyString;
+    executionId: typeof Schema.NonEmptyString;
+    operation: Schema.Literal<["cancel", "resume"]>;
+    requestId: typeof Schema.NonEmptyString;
 }>;
 
+export declare type WorkflowControlResult = Schema.Schema.Type<typeof WorkflowControlResultSchema>;
+
+/** Acceptance is not execution completion; null means no resident receipt. */
+export declare const WorkflowControlResultSchema: Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel", "resume"]>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    snapshot: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: typeof Schema.String;
+        status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<Schema.Struct<{
+            tag: Schema.NullOr<typeof Schema.String>;
+            message: typeof Schema.String;
+        }>>;
+    }>;
+}>>;
+
 export declare type WorkflowDomainEventRow = Schema.Schema.Type<typeof WorkflowDomainEventRowSchema>;
 
 export declare const WorkflowDomainEventRowSchema: Schema.Struct<{
@@ -6416,12 +6903,230 @@ export declare type WorkflowParentClosePolicy = Schema.Schema.Type<typeof Workfl
 
 export declare const WorkflowParentClosePolicySchema: Schema.Literal<["cancel", "terminate", "abandon"]>;
 
+export declare const workflowQueuedCancelDescriptor: ActionProcedureDescriptor<"__voltro.workflow.queued.cancel", Schema.Struct<{
+    cause: Schema.optionalWith<Schema.Struct<{
+        reason: typeof Schema.NonEmptyString;
+        detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>, {
+        exact: true;
+    }>;
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+}>, Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel"]>;
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    observation: Schema.Union<[Schema.Struct<{
+        kind: Schema.Literal<["pending"]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["admission"]>;
+        outcome: Schema.Union<[Schema.Union<[Schema.Struct<{
+            kind: Schema.Literal<["dropped"]>;
+            at: typeof Schema.Number;
+            retryAfterMs: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["skipped"]>;
+            at: typeof Schema.Number;
+            executionId: typeof Schema.String;
+            runId: typeof Schema.String;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["superseded"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["cancelled"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["abandoned"]>;
+            at: typeof Schema.Number;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>, Schema.Struct<{
+            kind: Schema.Literal<["rejected"]>;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["execution"]>;
+        snapshot: Schema.Struct<{
+            id: typeof Schema.String;
+            workflowName: typeof Schema.String;
+            executionId: typeof Schema.String;
+            status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+            output: Schema.optional<typeof Schema.Unknown>;
+            error: Schema.optional<Schema.Struct<{
+                tag: Schema.NullOr<typeof Schema.String>;
+                message: typeof Schema.String;
+            }>>;
+        }>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["unavailable"]>;
+        reason: Schema.Literal<["missing-request", "missing-run", "unconfirmed-generation", "unbound-submission"]>;
+    }>]>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowQueuedCancelInput = typeof WorkflowQueuedCancelInputSchema.Type;
+
+export declare const WorkflowQueuedCancelInputSchema: Schema.Struct<{
+    cause: Schema.optionalWith<Schema.Struct<{
+        reason: typeof Schema.NonEmptyString;
+        detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>, {
+        exact: true;
+    }>;
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+}>;
+
+export declare type WorkflowQueuedCancellationResult = typeof WorkflowQueuedCancellationResultSchema.Type;
+
+/** A queued caller has a receipt before any execution exists. Keep admission
+ * evidence separate from an observed execution rather than fabricating IDs. */
+export declare const WorkflowQueuedCancellationResultSchema: Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel"]>;
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    observation: Schema.Union<[Schema.Struct<{
+        kind: Schema.Literal<["pending"]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["admission"]>;
+        outcome: Schema.Union<[Schema.Union<[Schema.Struct<{
+            kind: Schema.Literal<["dropped"]>;
+            at: typeof Schema.Number;
+            retryAfterMs: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["skipped"]>;
+            at: typeof Schema.Number;
+            executionId: typeof Schema.String;
+            runId: typeof Schema.String;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["superseded"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["cancelled"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["abandoned"]>;
+            at: typeof Schema.Number;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>, Schema.Struct<{
+            kind: Schema.Literal<["rejected"]>;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["execution"]>;
+        snapshot: Schema.Struct<{
+            id: typeof Schema.String;
+            workflowName: typeof Schema.String;
+            executionId: typeof Schema.String;
+            status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+            output: Schema.optional<typeof Schema.Unknown>;
+            error: Schema.optional<Schema.Struct<{
+                tag: Schema.NullOr<typeof Schema.String>;
+                message: typeof Schema.String;
+            }>>;
+        }>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["unavailable"]>;
+        reason: Schema.Literal<["missing-request", "missing-run", "unconfirmed-generation", "unbound-submission"]>;
+    }>]>;
+}>>;
+
+export declare const workflowQueuedControlQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.queued.control", Schema.Struct<{
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+}>, Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel"]>;
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    observation: Schema.Union<[Schema.Struct<{
+        kind: Schema.Literal<["pending"]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["admission"]>;
+        outcome: Schema.Union<[Schema.Union<[Schema.Struct<{
+            kind: Schema.Literal<["dropped"]>;
+            at: typeof Schema.Number;
+            retryAfterMs: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["skipped"]>;
+            at: typeof Schema.Number;
+            executionId: typeof Schema.String;
+            runId: typeof Schema.String;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["superseded"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["cancelled"]>;
+            at: typeof Schema.Number;
+        }>, Schema.Struct<{
+            kind: Schema.Literal<["abandoned"]>;
+            at: typeof Schema.Number;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>, Schema.Struct<{
+            kind: Schema.Literal<["rejected"]>;
+            failureId: typeof Schema.NonEmptyString;
+        }>]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["execution"]>;
+        snapshot: Schema.Struct<{
+            id: typeof Schema.String;
+            workflowName: typeof Schema.String;
+            executionId: typeof Schema.String;
+            status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+            output: Schema.optional<typeof Schema.Unknown>;
+            error: Schema.optional<Schema.Struct<{
+                tag: Schema.NullOr<typeof Schema.String>;
+                message: typeof Schema.String;
+            }>>;
+        }>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["unavailable"]>;
+        reason: Schema.Literal<["missing-request", "missing-run", "unconfirmed-generation", "unbound-submission"]>;
+    }>]>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowQueuedControlTarget = typeof WorkflowQueuedControlTargetSchema.Type;
+
+export declare const WorkflowQueuedControlTargetSchema: Schema.Struct<{
+    workflowName: typeof Schema.NonEmptyString;
+    receiptId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+}>;
+
 export declare const workflowResumeDescriptor: ActionProcedureDescriptor<"__voltro.workflow.resume", Schema.Struct<{
     workflowName: typeof Schema.String;
     executionId: typeof Schema.String;
-}>, Schema.Struct<{
-    ok: typeof Schema.Boolean;
-}>, typeof Schema.Never>;
+    control: Schema.optional<Schema.Struct<{
+        requestId: typeof Schema.NonEmptyString;
+        cause: Schema.optionalWith<Schema.Struct<{
+            reason: typeof Schema.NonEmptyString;
+            detail: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        }>, {
+            exact: true;
+        }>;
+    }>>;
+}>, Schema.filter<Schema.Struct<{
+    operation: Schema.Literal<["cancel", "resume"]>;
+    kind: Schema.Literal<["accepted", "confirmed", "unknown", "already-terminal"]>;
+    requestId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    snapshot: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: typeof Schema.String;
+        status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<Schema.Struct<{
+            tag: Schema.NullOr<typeof Schema.String>;
+            message: typeof Schema.String;
+        }>>;
+    }>;
+}>>, typeof Schema.Never>;
 
 export declare type WorkflowRunEventRow = Schema.Schema.Type<typeof WorkflowRunEventRowSchema>;
 
@@ -6452,7 +7157,7 @@ export declare type WorkflowRunHandle = Schema.Schema.Type<typeof WorkflowRunHan
 
 export declare const WorkflowRunHandleSchema: Schema.Struct<{
     /** Stable handle callers pass to `useWorkflowRun(...)`. The durable execution
-     *  id for a started run; the pending-intent id for a queued one. */
+     *  id for a started run; the durable caller-receipt id for a queued one. */
     id: typeof Schema.String;
     /** Workflow tag, e.g. `notes.summarise`. */
     workflowName: typeof Schema.String;
@@ -6472,6 +7177,7 @@ export declare const WorkflowRunHandleSchema: Schema.Struct<{
     executionId: Schema.NullOr<typeof Schema.String>;
     /**
      * `running`  — the engine has it; starting is fire-and-return.
+     * `succeeded` — a blocking start observed successful completion.
      * `queued`   — flow control deferred it; see `deferral.dueAt`.
      * `dropped`  — over a `rateLimit` cap. It will NOT run.
      * `skipped`  — a `singleton: { mode: 'skip' }` key was held; `executionId`
@@ -6484,7 +7190,7 @@ export declare const WorkflowRunHandleSchema: Schema.Struct<{
      * a fresh start; a schedule keyed per day ran once and reported forty-seven
      * "starts" that were replays. See `workflow()`'s `idempotencyKey` doc.
      */
-    status: Schema.Literal<["running", "queued", "dropped", "skipped", "replayed"]>;
+    status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
          *  `rateLimit` | `singleton`. */
@@ -6560,6 +7266,21 @@ export declare const WorkflowRunsInputSchema: Schema.Struct<{
     limit: Schema.optional<typeof Schema.Number>;
 }>;
 
+export declare type WorkflowRunSnapshot = Schema.Schema.Type<typeof WorkflowRunSnapshotSchema>;
+
+/** Observed execution state, distinct from admission/start handles. */
+export declare const WorkflowRunSnapshotSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    workflowName: typeof Schema.String;
+    executionId: typeof Schema.String;
+    status: Schema.Union<[Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>, Schema.Literal<["unknown"]>]>;
+    output: Schema.optional<typeof Schema.Unknown>;
+    error: Schema.optional<Schema.Struct<{
+        tag: Schema.NullOr<typeof Schema.String>;
+        message: typeof Schema.String;
+    }>>;
+}>;
+
 export declare const workflowRunsQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.runs", Schema.Struct<{
     tag: Schema.optional<typeof Schema.String>;
     status: Schema.optional<Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>>;
@@ -6670,6 +7391,31 @@ export declare const WorkflowStartDeferralSchema: Schema.Struct<{
     intentId: Schema.NullOr<typeof Schema.String>;
 }>;
 
+export declare type WorkflowStartTerminalOutcome = typeof WorkflowStartTerminalOutcomeSchema.Type;
+
+/** A settled admission outcome is not a terminal execution snapshot. In the
+ * skipped case the identities belong to the incumbent, not to a new run. */
+export declare const WorkflowStartTerminalOutcomeSchema: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["dropped"]>;
+    at: typeof Schema.Number;
+    retryAfterMs: typeof Schema.Number;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["skipped"]>;
+    at: typeof Schema.Number;
+    executionId: typeof Schema.String;
+    runId: typeof Schema.String;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["superseded"]>;
+    at: typeof Schema.Number;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["cancelled"]>;
+    at: typeof Schema.Number;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["abandoned"]>;
+    at: typeof Schema.Number;
+    failureId: typeof Schema.NonEmptyString;
+}>]>;
+
 /**
  * Per-step plugin interceptor. Wraps every `step()` (==
  * `Activity.make`) invocation inside a workflow body. Composed
@@ -6717,7 +7463,7 @@ export declare const workflowToRpc: <const Name extends string, Payload extends
     readonly errorSchema: Schema.Schema.All;
 }, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Schema.Struct<{
     /** Stable handle callers pass to `useWorkflowRun(...)`. The durable execution
-     *  id for a started run; the pending-intent id for a queued one. */
+     *  id for a started run; the durable caller-receipt id for a queued one. */
     id: typeof Schema.String;
     /** Workflow tag, e.g. `notes.summarise`. */
     workflowName: typeof Schema.String;
@@ -6737,6 +7483,7 @@ export declare const workflowToRpc: <const Name extends string, Payload extends
     executionId: Schema.NullOr<typeof Schema.String>;
     /**
      * `running`  — the engine has it; starting is fire-and-return.
+     * `succeeded` — a blocking start observed successful completion.
      * `queued`   — flow control deferred it; see `deferral.dueAt`.
      * `dropped`  — over a `rateLimit` cap. It will NOT run.
      * `skipped`  — a `singleton: { mode: 'skip' }` key was held; `executionId`
@@ -6749,7 +7496,7 @@ export declare const workflowToRpc: <const Name extends string, Payload extends
      * a fresh start; a schedule keyed per day ran once and reported forty-seven
      * "starts" that were replays. See `workflow()`'s `idempotencyKey` doc.
      */
-    status: Schema.Literal<["running", "queued", "dropped", "skipped", "replayed"]>;
+    status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
          *  `rateLimit` | `singleton`. */