@voltro/protocol 0.63.0 → 0.64.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
+import { Option } from 'effect';
 import { Rpc } from '@effect/rpc';
 import { RpcMiddleware } from '@effect/rpc';
 import { Schema } from 'effect';
@@ -447,6 +448,10 @@ declare const ApprovalUnavailable_base: Schema.TaggedErrorClass<ApprovalUnavaila
  */
 export declare const assertAuthenticated: (subject: Subject, reason?: string) => void;
 
+/** Attach a resolved decision to a definition — non-enumerable, like the
+ *  definer's other metadata, so the engine never sees it as a field. */
+export declare const attachWorkflowAccess: (definition: object, access: WorkflowAccess) => void;
+
 /** Optional callback-route mount surface for strategies that handle
  *  OAuth callbacks. Apps wire these via the framework's HTTP router
  *  when the strategy declares `mountRoutes`. */
@@ -587,6 +592,55 @@ export declare interface AuthStrategyWithCallback extends AuthStrategy {
     readonly mountRoutes: (router: AuthCallbackRouter) => void;
 }
 
+export declare type AuthSubjectGuard = (subject: Subject, ctx: AuthSubjectGuardContext) => Promise<AuthSubjectGuardVerdict> | AuthSubjectGuardVerdict;
+
+export declare interface AuthSubjectGuardContext {
+    /** `'request'` for a live call, `'workflow'` for a durable run being executed. */
+    readonly origin: 'request' | 'workflow';
+    /** The request's headers. EMPTY for `origin: 'workflow'`. */
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    /** `undefined` for `origin: 'workflow'` and for transports with no connection. */
+    readonly clientId: number | undefined;
+    /** The app's boot store (see `AuthStrategyInput.store`), or `undefined` while
+     *  it is still being built — a guard that needs it then fails CLOSED. */
+    readonly store: DataStore | undefined;
+}
+
+/**
+ * A post-authentication VETO on a resolved subject — the framework-level form
+ * of `@voltro/plugin-auth`'s `subjectGuards`, and the reason it exists here too.
+ *
+ * The auth plugin runs its guards once, at LOGIN, before a session is issued —
+ * the right place when every session comes from its routes. It is the wrong
+ * place for an app whose subjects arrive through its own strategy chain (a JWKS
+ * IdP, an API-key table, a session it mints itself): those never pass through
+ * a login handler, so a `deactivationGuard()` wired onto the auth plugin vetoed
+ * nobody, and `users.deactivate` locked no one out. The guard has to sit where
+ * EVERY subject passes — after a strategy matches and authority is resolved,
+ * on the request path and on a durable workflow's resume alike.
+ *
+ * A guard receives the subject WITH its resolved scopes (so it may reason about
+ * them) and the same context `resolveScopes` gets: `origin` (a durable run has
+ * no request behind it), the headers, and the app's store for the row it needs
+ * to read. It returns a verdict; the first rejection wins and the request fails
+ * closed with `Unauthenticated` carrying the guard's `code` and `message`. It
+ * runs only for a MATCHED subject — an anonymous caller has no identity to veto.
+ *
+ * It is cached WITH the scope decision, under the same key and window: a veto
+ * is a fact about an identity, exactly like its roles, and a guard that reads a
+ * row per request would otherwise cost what `scopeCache` exists to avoid. The
+ * staleness is therefore the one number the docs already give (30s), and
+ * `invalidate(scopeCacheKey(subject))` from the mutation that deactivates makes
+ * it zero on that process — the same handle, the same call.
+ */
+export declare type AuthSubjectGuardVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+
 /**
  * Decide what to do for an incoming (scope, key) in ONE atomic store call. On
  * `fresh` the caller runs the handler then calls `finish`/`fail`; on
@@ -821,6 +875,13 @@ export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrat
         removed: ReadonlyArray<string>;
         granted: ReadonlyArray<string>;
     }) => void;
+    /**
+     * Post-authentication vetoes on a MATCHED subject — see `AuthSubjectGuard`.
+     * Run after `resolveScopes` (so a guard sees the applied scopes), inside the
+     * same cache entry, first rejection wins → `Unauthenticated` with the
+     * guard's `code` and `message`.
+     */
+    readonly subjectGuards?: ReadonlyArray<AuthSubjectGuard>;
     /**
      * Hands every strategy the app's store on `input.store`.
      *
@@ -2132,6 +2193,15 @@ export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefin
 /** The currently-registered resource-scope resolver, or `undefined`. */
 export declare const getResourceScopeResolver: () => ResourceScopeResolver | undefined;
 
+/**
+ * Read a definition's decision back. A value that never went through
+ * `workflow()` — a bare `Workflow.make`, a test double — reports UNDECIDED and
+ * not internal, so the boot gate judges it exactly like a definer call that
+ * declared nothing: that is the fail-closed reading, and the only one under
+ * which forgetting the definer cannot open a door.
+ */
+export declare const getWorkflowAccess: (definition: unknown) => WorkflowAccess;
+
 /** Ask for default-deny semantics on one `checkGuards` call. */
 export declare interface GuardCheckOptions {
     /** Refuse a procedure that declares no access decision at all. */
@@ -2295,6 +2365,9 @@ export declare interface HttpRequestContext {
  */
 export declare type HttpRequestInterceptor = (next: () => Promise<HttpInterceptResponse | null>, ctx: HttpRequestContext) => Promise<HttpInterceptResponse | null>;
 
+/** Fire-and-forget observer of plugin HTTP route calls — see {@link PluginHttpRouteEvent}. */
+export declare type HttpRouteObserver = (event: PluginHttpRouteEvent) => void;
+
 export declare type IdempotencyOutcome = {
     readonly kind: 'fresh';
 } | {
@@ -2503,6 +2576,24 @@ export declare const memoryIdempotencyStore: () => IdempotencyStore;
  *  and the call-time path cannot describe the same defect differently. */
 export declare const missingAccessDecision: (procedure?: string) => ScopeError;
 
+/** The wait a conflicting replay is told to take. Long enough that a handler
+ *  in its last second finishes; short enough that a 10-second replay window
+ *  fits several tries. */
+export declare const MUTATION_IN_FLIGHT_RETRY_AFTER_MS = 1000;
+
+export declare class MutationInFlight extends MutationInFlight_base {
+    get message(): string;
+}
+
+declare const MutationInFlight_base: Schema.TaggedErrorClass<MutationInFlight, "MutationInFlight", {
+    readonly _tag: Schema.tag<"MutationInFlight">;
+} & {
+    traceId: typeof Schema.String;
+    /** How long to wait before replaying the same key — the first call is still
+     *  running; a replay before it finishes conflicts again. */
+    retryAfterMs: typeof Schema.Number;
+}>;
+
 export declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
     readonly kind: 'mutation';
     readonly name: Name;
@@ -2704,20 +2795,6 @@ export declare type PluginActivateHook = (ctx: PluginLifecycleContext) => Effect
  */
 export declare const pluginAlias: (pluginName: string) => string;
 
-/**
- * Server-only context delivered to `bindDataStore`, ALONGSIDE the store,
- * AFTER the framework has opened its store + pool. Gives a plugin the
- * framework's ALREADY-OPEN handles so it never rebuilds a pg pool from
- * raw env (the anti-pattern `@voltro/plugin-ratelimit` used to hand-roll)
- * and never runs an un-coordinated per-replica `setInterval` sweep (what
- * presence + governance used to do).
- *
- * These fields are SERVER-only — they are TYPES only in this browser-safe
- * protocol package (the `DataStore` / `SqlClient` imports are erased), and
- * the live values exist only inside the serve pipeline that calls
- * `bindDataStore`. Nothing in the browser-loaded descriptor/schema graph
- * touches them.
- */
 export declare interface PluginBindContext {
     /**
      * This process's replica identity — the same value the event bus stamps as
@@ -2754,6 +2831,20 @@ export declare interface PluginBindContext {
         readonly publish: (channel: string, payload: string) => unknown;
         readonly subscribe: (channel: string, handler: (payload: string) => void) => unknown;
     };
+    /**
+     * The framework's cache — the SAME backend `ctx.cache` and query snapshots
+     * use (`CACHE_BACKEND`: in-process memory, or Redis shared across replicas).
+     * A plugin that memoises reference data (a board's configuration, a field
+     * catalogue) reads and writes it here instead of asking the app for a
+     * hand-built store object; the keys a plugin writes are its own to namespace.
+     *
+     * A handle rather than a value: `voltro dev` builds the cache after plugins
+     * are bound and `voltro serve` before, so the two boot paths hand over the
+     * same object whose methods resolve the live cache at call time. Before it
+     * exists a read misses and a write is dropped — best-effort, never a boot
+     * ordering a plugin has to know about.
+     */
+    readonly cache?: PluginCacheHandle;
     /**
      * The framework's already-open `SqlClient` (from `@effect/sql`) — the
      * SAME pool the app's store uses. A plugin runs raw SQL through this
@@ -2805,6 +2896,28 @@ export declare interface PluginBindContext {
     readonly claimChange: (scope: string, key: string) => Promise<boolean>;
 }
 
+/**
+ * Server-only context delivered to `bindDataStore`, ALONGSIDE the store,
+ * AFTER the framework has opened its store + pool. Gives a plugin the
+ * framework's ALREADY-OPEN handles so it never rebuilds a pg pool from
+ * raw env (the anti-pattern `@voltro/plugin-ratelimit` used to hand-roll)
+ * and never runs an un-coordinated per-replica `setInterval` sweep (what
+ * presence + governance used to do).
+ *
+ * These fields are SERVER-only — they are TYPES only in this browser-safe
+ * protocol package (the `DataStore` / `SqlClient` imports are erased), and
+ * the live values exist only inside the serve pipeline that calls
+ * `bindDataStore`. Nothing in the browser-loaded descriptor/schema graph
+ * touches them.
+ */
+/** The slice of the framework cache handed to a plugin at bind time. */
+export declare interface PluginCacheHandle {
+    readonly get: (key: string) => Effect.Effect<Option.Option<unknown>, unknown>;
+    readonly set: (key: string, value: unknown, options?: {
+        readonly ttlMs?: number;
+    }) => Effect.Effect<void, unknown>;
+}
+
 /**
  * Post-commit change event delivered to a plugin's `onChangeEvent` tap.
  * Minimal, browser-safe shape (protocol must not depend on the database
@@ -3113,6 +3226,25 @@ export declare interface PluginHttpRouteByteStream {
     readonly contentDisposition?: string;
 }
 
+/**
+ * One plugin HTTP route call, after it answered — what an audit trail records.
+ *
+ * `onHttpRequest` runs BEFORE auth and before routing and sees no status, so a
+ * login, a logout or an avatar fetch served by a plugin's `httpRoutes` left no
+ * trace in a trail that recorded every rpc. This is the other end of the same
+ * pipeline: the method, the path, the status and how long it took, once the
+ * route has answered. No subject — a plugin HTTP route is not part of the rpc
+ * pipeline and nothing upstream authenticated its caller; a route that resolves
+ * one itself is the only party that knows, and can put it in its own log.
+ */
+export declare interface PluginHttpRouteEvent {
+    readonly method: string;
+    /** Path WITHOUT query string. */
+    readonly path: string;
+    readonly status: number;
+    readonly durationMs: number;
+}
+
 export declare interface PluginHttpRouteRequest {
     readonly method: string;
     /** Path WITHOUT query string. */
@@ -3220,7 +3352,10 @@ export declare interface PluginHttpRouteResult {
     readonly status: number;
     readonly body?: string | Uint8Array;
     readonly contentType?: string;
-    readonly headers?: Record<string, string>;
+    /** Response headers. A header that repeats — two `Set-Cookie` lines, a
+     *  session and a CSRF cookie from one login — is an ARRAY; `set-cookie`
+     *  arrays become separate lines, every other array joins with `, `. */
+    readonly headers?: Record<string, string | ReadonlyArray<string>>;
     /** Stream the response (SSE) instead of sending `body`. See
      *  {@link PluginHttpRouteStream}. */
     readonly stream?: PluginHttpRouteStream;
@@ -3444,7 +3579,7 @@ export declare type PluginMigrationSqlClient = SqlClient.SqlClient;
  * boot log + `/_voltro/inspect/plugins` so operators audit what each
  * plugin asks for before installing.
  */
-export declare type PluginPermission = 'rpc:intercept:mutation' | 'rpc:intercept:query' | 'rpc:intercept:action' | 'schedule:fire' | 'schedule:read' | 'workflow:step' | 'http:intercept' | 'inspect:read' | 'inspect:write' | 'dashboard:mount' | 'store:write' | 'migration:run' | 'store:changes:read' | `secrets:read:${string}` | `network:outbound:${string}` | `plugin:hook:${string}`;
+export declare type PluginPermission = 'rpc:intercept:mutation' | 'rpc:intercept:query' | 'rpc:intercept:action' | 'rpc:intercept:workflow' | 'schedule:fire' | 'schedule:read' | 'workflow:step' | 'http:intercept' | 'inspect:read' | 'inspect:write' | 'dashboard:mount' | 'store:write' | 'migration:run' | 'store:changes:read' | `secrets:read:${string}` | `network:outbound:${string}` | `plugin:hook:${string}`;
 
 /**
  * Per-call context handed to a plugin-contributed rpc route's
@@ -3458,6 +3593,15 @@ export declare interface PluginRouteContext {
     };
 }
 
+/**
+ * The kinds a plugin can CONTRIBUTE a route as. A plugin declares procedures,
+ * never workflows (a workflow is a `*.workflow.tsx` pair the app authors and the
+ * engine runs), so this is the interceptor union minus `'workflow'` — kept as
+ * its own name so a route's `kind` cannot select a runtime path that does not
+ * exist for it.
+ */
+export declare type PluginRouteKind = 'mutation' | 'query' | 'action';
+
 /**
  * Client-facing declaration of a plugin RPC route's descriptor, so the codegen
  * can emit it into the generated client rpc group (`appGroup` + `appDescriptors`)
@@ -3474,7 +3618,7 @@ export declare interface PluginRouteContext {
  */
 export declare interface PluginRpcClientDescriptor {
     readonly tag: string;
-    readonly kind: RpcKind;
+    readonly kind: PluginRouteKind;
     readonly import: {
         readonly module: string;
         readonly name: string;
@@ -3497,7 +3641,7 @@ export declare interface PluginRpcClientDescriptor {
  */
 export declare interface PluginRpcRoute {
     /** 'mutation' | 'query' | 'action' — determines the runtime path. */
-    readonly kind: RpcKind;
+    readonly kind: PluginRouteKind;
     /** RPC tag relative to the plugin (e.g. `'list'`, `'admin.events'`). */
     readonly name: string;
     /** Optional human-readable description; surfaced in the dashboard. */
@@ -4042,6 +4186,14 @@ export declare const requireScope: (subject: Subject, scope: string) => Effect.E
 /** Drop every registration. Tests only — production registers once at module load. */
 export declare const resetPluginAliases: () => void;
 
+/**
+ * Validate an author's access options and normalise them into the array every
+ * enforcement path reads. Throws at DEFINITION time — module load, which is
+ * boot — with the same wording the event and procedure definers use, so the
+ * three refusals read as one rule.
+ */
+export declare const resolveWorkflowAccess: (name: string, options: WorkflowAccessOptions<never>) => WorkflowAccess;
+
 /** The question the runtime asks a registered resource-scope resolver. */
 export declare interface ResourceScopeRequest {
     /** The authenticated caller. */
@@ -4219,7 +4371,7 @@ export declare type RpcInterceptor = (next: Effect.Effect<unknown, unknown>, con
 export declare interface RpcInterceptorContext {
     /** Procedure tag, e.g. `todos.create`. */
     readonly tag: string;
-    /** Discriminator — `'mutation' | 'query' | 'action'`. */
+    /** Discriminator — `'mutation' | 'query' | 'action' | 'workflow'`. */
     readonly kind: RpcKind;
     /** The validated input the executor is about to (or already did) receive. */
     readonly input: unknown;
@@ -4236,10 +4388,11 @@ export declare interface RpcInterceptorContext {
 /**
  * Which kind of rpc the interceptor is wrapping. The runtime passes
  * `kind: 'mutation'` to interceptors registered as `interceptMutation`,
- * `kind: 'query'` to `interceptQuery`, and `kind: 'action'` to
- * `interceptAction` — one plugin can implement any combination.
+ * `kind: 'query'` to `interceptQuery`, `kind: 'action'` to
+ * `interceptAction`, and `kind: 'workflow'` to `interceptWorkflow` — one
+ * plugin can implement any combination.
  */
-export declare type RpcKind = 'mutation' | 'query' | 'action';
+export declare type RpcKind = 'mutation' | 'query' | 'action' | 'workflow';
 
 /**
  * Per-firing context passed to schedule-fire interceptors. Shape
@@ -4351,6 +4504,19 @@ export declare type ScopeDecision =
 | {
     readonly kind: 'unavailable';
     readonly reason: string;
+}
+/**
+* A subject guard REFUSED this identity (see `AuthSubjectGuard`). Not a
+* resolver's answer — a resolver returns one of the three above — but the
+* composer's, produced after the guards ran, and cached like a grant: a veto
+* is a durable fact about the identity until whatever changed it invalidates
+* the key. `applyScopeDecision` THROWS on it, so a caller that forgot the
+* explicit branch fails closed rather than applying "no scopes" and carrying on.
+*/
+| {
+    readonly kind: 'vetoed';
+    readonly code: string;
+    readonly message: string;
 };
 
 export declare class ScopeError extends ScopeError_base {
@@ -5380,6 +5546,22 @@ export declare interface VoltroPlugin {
      * tenant-scoped IO quotas).
      */
     readonly interceptAction?: RpcInterceptor;
+    /**
+     * Wraps every WORKFLOW START call — the unary rpc a `*.workflow.tsx`
+     * becomes on the wire. Same composition semantics as `interceptMutation`.
+     *
+     * A start is a write-class call: it records a run row, it may cost money
+     * (a workflow that calls a model or a paid API), and it runs as the caller's
+     * subject. So the plugins that wrap mutations — audit, rate limiting,
+     * entitlement, rbac's scope publication — want to wrap this too, and before
+     * this hook existed none of them did: the start handler was bound outside
+     * every interceptor chain, so an audit trail that covered every mutation
+     * recorded no workflow start, and a `guards:` on a workflow could not see
+     * the scopes rbac publishes inside the chain. Declaring `interceptAction`
+     * without this hook leaves that gap open for your plugin; the first-party
+     * plugins carry a parity test that fails when one does.
+     */
+    readonly interceptWorkflow?: RpcInterceptor;
     /**
      * Effect Layer that contributes services into the per-request
      * context. Anything declared here is yieldable from any handler in
@@ -5515,6 +5697,14 @@ export declare interface VoltroPlugin {
      * the hook is declared without the matching permission.
      */
     readonly onHttpRequest?: HttpRequestInterceptor;
+    /**
+     * Post-response observer of every plugin HTTP route call — method, path,
+     * status, duration. The audit plugin's way of recording a login or an avatar
+     * fetch, which no rpc interceptor ever sees. Fire-and-forget: it cannot
+     * change the response and a throw is swallowed. Same `'http:intercept'`
+     * permission as `onHttpRequest` — it is the same pipeline, the other end.
+     */
+    readonly onHttpRoute?: HttpRouteObserver;
     /**
      * Dashboard mount contributions — remote-loaded ESM modules the
      * dashboard host renders alongside framework pages. See
@@ -5735,6 +5925,61 @@ export declare const withRpcTag: <D extends {
     readonly name: T;
 };
 
+/** The resolved decision the runtime reads. */
+export declare interface WorkflowAccess {
+    /** The author's guards, or the erased `openAccess` entry — never both. */
+    readonly guards: DeclaredAccess<unknown> | undefined;
+    readonly openAccess: string | undefined;
+    readonly internal: boolean;
+}
+
+/**
+ * The definition as the boot gate, the codegen and the dispatch spine read it:
+ * the structural `{ name, internal, guards, openAccess }` every other kind
+ * presents, so `isWireReachable` and `hasAccessDecision` apply unchanged and a
+ * workflow rides the same walk as the five procedure kinds.
+ */
+export declare const workflowAccessDescriptor: (definition: {
+    readonly name: string;
+}) => {
+    readonly name: string;
+    readonly internal: boolean;
+    readonly guards: DeclaredAccess<unknown> | undefined;
+    readonly openAccess: string | undefined;
+};
+
+/** What an author writes on `workflow({ … })`. */
+export declare interface WorkflowAccessOptions<Payload = unknown> {
+    /**
+     * WHO MAY START this workflow over the wire — the same vocabulary as a
+     * mutation's `guards:`. A resource-scoped guard reads its id from the start
+     * payload: `{ action: 'export', resourceType: 'team', resource: (p) => p.teamId }`.
+     *
+     * Checked ONCE, at the start call, before the run row is written or the
+     * engine is asked for anything. The run itself then executes as the subject
+     * that started it (`ctx.subject` inside the workflow) — the guard decides
+     * whether it may begin, not what it may read; row filters do that.
+     */
+    readonly guards?: Guards<Payload>;
+    /**
+     * Anyone who can open the socket may start this workflow — and WHY. A
+     * reason, never a boolean; an empty string is refused at definition time.
+     * Read by the boot gate and printed by `voltro doctor` beside the tag.
+     */
+    readonly openAccess?: string;
+    /**
+     * No start rpc at all. The workflow is still discovered, registered with the
+     * engine and startable from server code — `ctx.workflows.start`, a
+     * `schedule:` block, an event trigger, a parent workflow — but the codegen
+     * emits no client entry and neither boot path binds a handler for it.
+     * Cannot be combined with `openAccess` (there is no wire to decide about).
+     */
+    readonly internal?: boolean;
+}
+
+/** The non-enumerable property a `workflow()` definition carries its decision under. */
+export declare const WorkflowAccessProperty: unique symbol;
+
 export declare const workflowCancelDescriptor: ActionProcedureDescriptor<"__voltro.workflow.cancel", Schema.Struct<{
     workflowName: typeof Schema.String;
     executionId: typeof Schema.String;
@@ -5880,7 +6125,14 @@ export declare const WorkflowRunHandleSchema: Schema.Struct<{
      * `skipped`  — a `singleton: { mode: 'skip' }` key was held; `executionId`
      *              names the run that holds it.
      */
-    status: Schema.Literal<["running", "queued", "dropped", "skipped"]>;
+    /**
+     * `replayed` — the idempotency key was already SPENT: a run under it had
+     * finished, so nothing started and the handle addresses that old run. It
+     * used to come back `running` with the old run's id, indistinguishable from
+     * 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"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
          *  `rateLimit` | `singleton`. */
@@ -6094,6 +6346,71 @@ export declare interface WorkflowStepContext {
 
 export declare type WorkflowStepInterceptor = <Success, ErrorE, R>(next: Effect.Effect<Success, ErrorE, R>, ctx: WorkflowStepContext) => Effect.Effect<Success, ErrorE, R>;
 
+/**
+ * The fifth lifter — a `workflow()` definition to the unary START rpc it
+ * answers to on the wire. Browser-safe, like the four procedure lifters, and
+ * for the same reason: the generated client group and both boot paths call
+ * THIS, so the three cannot disagree about the payload strictness or the error
+ * union. It used to be spelled three times (a runtime helper for serve, an
+ * inline `Rpc.make` in dev without `strictInput`, another inline one in the
+ * codegen without the guard errors), and the three had already drifted.
+ *
+ * Reads the access decision off the definition: an enforced guard widens the
+ * error union with `ScopeError` / `Unauthenticated`, exactly as it does for a
+ * mutation, and labels the strict-input refusal as a guarded procedure's.
+ */
+export declare const workflowToRpc: (workflow: {
+    readonly name: string;
+    readonly payloadSchema: Schema.Schema.Any;
+    readonly errorSchema: Schema.Schema.All;
+}, extraErrors?: ExtraErrors) => Rpc.Rpc<string, Schema.Schema.Any, 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: typeof Schema.String;
+    /** Workflow tag, e.g. `notes.summarise`. */
+    workflowName: typeof Schema.String;
+    /**
+     * Deterministic durable id derived from workflow name + idempotency key.
+     *
+     * NULL when flow control deferred, dropped, or skipped the start — because
+     * there is no execution yet, and there may never be one. It used to be a
+     * required string, and keeping it that way would have meant inventing a value:
+     * either an empty string or the id the run WOULD have had. Both are polls that
+     * return `status: 'unknown'` forever, which is the failure mode this whole
+     * feature set exists to remove.
+     *
+     * For a `skipped` singleton it is the INCUMBENT's execution id — a real,
+     * pollable run, which is the entire point of `mode: 'skip'`.
+     */
+    executionId: Schema.NullOr<typeof Schema.String>;
+    /**
+     * `running`  — the engine has it; starting is fire-and-return.
+     * `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`
+     *              names the run that holds it.
+     */
+    /**
+     * `replayed` — the idempotency key was already SPENT: a run under it had
+     * finished, so nothing started and the handle addresses that old run. It
+     * used to come back `running` with the old run's id, indistinguishable from
+     * 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"]>;
+    deferral: Schema.optional<Schema.Struct<{
+        /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
+         *  `rateLimit` | `singleton`. */
+        mode: typeof Schema.String;
+        /** Epoch ms this may first be admitted. Null for a drop or a skip. */
+        dueAt: Schema.NullOr<typeof Schema.Number>;
+        /** How long until the rate window reopens. Null unless dropped. */
+        retryAfterMs: Schema.NullOr<typeof Schema.Number>;
+        /** The `_voltro_workflow_pending` row holding this start. Null unless queued. */
+        intentId: Schema.NullOr<typeof Schema.String>;
+    }>>;
+}>, Schema.Schema.All, never>;
+
 export declare const workflowUpdateDescriptor: ActionProcedureDescriptor<"__voltro.workflow.update", Schema.Struct<{
     id: typeof Schema.String;
     updateName: typeof Schema.String;
@@ -6122,6 +6439,21 @@ export declare const WorkflowUpdateResultSchema: Schema.Struct<{
     result: typeof Schema.Unknown;
 }>;
 
+/**
+ * The error union a WORKFLOW START puts on the wire — the workflow's own
+ * `error:` plus what the framework can refuse the start with before the engine
+ * is asked: the guard refusals (when it declares an enforced guard) and any
+ * plugin error the `interceptWorkflow` chain may fail with. Read by the two
+ * boot paths (the rpc group AND `bindMutation`'s declared set) and by
+ * `workflowToRpc` for the generated client — one function, so a `ScopeError`
+ * on a start decodes as the typed failure it is rather than crossing as the
+ * `ExitEncoded` defect tree a mutation used to ship for the same reason.
+ */
+export declare const workflowWireErrorUnion: (workflow: {
+    readonly errorSchema: Schema.Schema.All;
+    readonly guards?: DeclaredAccess | undefined;
+}, extraErrors?: ExtraErrors) => Schema.Schema.All;
+
 /**
  * Scope for a WS-rpc MUTATION. Unlike the REST scope (tenant + method + path),
  * this includes the acting SUBJECT id: a WS app is often single-tenant with many