@voltro/protocol 0.70.0 → 0.71.0

package/dist/apikey.d.ts

@@ -210,6 +210,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<{

package/dist/index.d.ts

@@ -3667,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;
@@ -4082,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;
 }
@@ -4127,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
@@ -4167,6 +4174,26 @@ 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 {
@@ -4180,6 +4207,28 @@ export declare interface PublicApiProfileConfig {
     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';
@@ -4189,6 +4238,18 @@ export declare interface PublicApiSpec {
     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. */
@@ -4518,6 +4579,11 @@ 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
@@ -4781,6 +4847,9 @@ declare interface RestRouteProjection {
     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>;
@@ -5350,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<{
@@ -5383,6 +5457,11 @@ 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<{
     type: Schema.Literal<["user"]>;
     id: typeof Schema.String;
@@ -5398,6 +5477,9 @@ export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
     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;
@@ -5482,6 +5564,7 @@ declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Sub
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
+    readonly auditActorId?: string | null;
 } | {
     readonly type: "anonymous";
     readonly id: null;
@@ -6644,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<{
@@ -6725,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>;
 
@@ -6761,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;
@@ -6781,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`
@@ -6793,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`. */
@@ -6869,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"]>>;
@@ -6979,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
@@ -7026,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;
@@ -7046,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`
@@ -7058,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`. */