@voltro/runtime 0.63.0 → 0.64.0

package/dist/index.d.ts

@@ -33,10 +33,12 @@ import { EventResumePoint } from '@voltro/protocol';
 import { EventStreamEvent } from '@voltro/protocol';
 import { extractDbCause } from '@voltro/database';
 import { Fiber } from 'effect';
+import { FieldBinding } from '@voltro/database';
 import { FieldCipher } from '@voltro/database';
 import * as http from 'node:http';
 import { HttpClient } from '@effect/platform';
 import { HttpRequestInterceptor } from '@voltro/protocol';
+import { HttpRouteObserver } from '@voltro/protocol';
 import { IdempotencyStore } from '@voltro/protocol';
 import { IdScheme } from '@voltro/database';
 import { InMemoryMetricExporter } from '@opentelemetry/sdk-metrics';
@@ -102,6 +104,7 @@ import { Tracer } from 'effect';
 import { Unauthenticated } from '@voltro/protocol';
 import { ValidationError } from '@voltro/protocol';
 import { ValidationErrors } from '@voltro/protocol';
+import { VersionConflict } from '@voltro/database';
 import { WebSocketGatewayRoute } from '@voltro/protocol';
 import { WorkflowParentClosePolicy } from '@voltro/protocol';
 import { WorkflowRunHandle } from '@voltro/protocol';
@@ -1568,6 +1571,15 @@ export declare interface BeginOAuthResult {
     readonly state: string;
 }
 
+/** Exported for the backpressure suite — the production caller is `bindSubscription`. */
+export declare const bindComputedUntyped: (computed: ComputedQuery, dispatcher: Dispatcher, context: RuntimeContext, label: string, 
+/** Tunables override (tests); production reads the process-wide slot. */
+backpressure?: {
+    readonly maxBufferedBytes: number;
+    readonly overrunAfterMs: number;
+    readonly oversizedEventBytes: number;
+}) => Stream.Stream<SubscriptionEvent<unknown>, never, never>;
+
 /**
  * Present a new credential on an ALREADY-OPEN connection.
  *
@@ -2070,6 +2082,27 @@ export declare const collectPluginRefRules: (tables: ReadonlyArray<{
     }>;
 }>, registered: ReadonlySet<string>) => ReadonlyArray<PluginRefRule>;
 
+/**
+ * The soft-delete rules an app's OWN `reference(…, { onSoftDelete })` columns
+ * declare — app→app, where the hard delete is a real foreign key and only the
+ * soft delete needs the runtime.
+ *
+ * Refuses at boot, naming the column, when `'cascade'` points from a table
+ * that cannot be soft-deleted: the engine would `store.delete` the child, the
+ * middleware would HARD-delete it (no `softDelete()` to turn it into an
+ * update), and a restore of the parent would bring back a parent whose
+ * children are gone for good.
+ */
+export declare const collectReferenceSoftDeleteRules: (tables: ReadonlyArray<{
+    readonly name: string;
+    readonly softDeletable?: boolean;
+    readonly fields?: Readonly<Record<string, {
+        readonly type?: string;
+        readonly references?: () => unknown;
+        readonly refOnSoftDelete?: "cascade" | "setNull";
+    }>>;
+}>) => ReadonlyArray<PluginRefRule>;
+
 /** Parse + return the compiled `Cron` for a definition. Throws the
  *  same way `defineSchedule` validated — callers that already hold a
  *  branded definition can trust this won't throw. */
@@ -2916,7 +2949,7 @@ export declare const decideApprovalInvocation: (input: {
  * the old form is already on production disks, and a fix that needs the data
  * rewritten before the app works is an outage with a migration attached.
  */
-export declare const decryptField: (value: string) => string;
+export declare const decryptField: (value: string, binding?: FieldBinding) => string;
 
 export declare const DEFAULT_ANALYTICS_MIRROR_TUNABLES: AnalyticsMirrorTunables;
 
@@ -2977,6 +3010,9 @@ export declare const DEFAULT_MAX_RPC_BODY_BYTES: number;
  *  definition nothing keeps in step. */
 export declare const DEFAULT_MAX_RUNTIME_MS: number;
 
+/** Default replay bound — `mutations.replayAttempts` in `app.config.ts` moves it. */
+export declare const DEFAULT_MUTATION_REPLAY_ATTEMPTS = 3;
+
 /** See {@link DrainDeps.claimLeaseMs}. */
 export declare const DEFAULT_OUTBOX_CLAIM_LEASE_MS: number;
 
@@ -3035,6 +3071,8 @@ export declare const DEFAULT_SOCKET_OVERRUN_AFTER_MS = 10000;
 
 export declare const DEFAULT_SOCKET_OVERSIZED_EVENT_BYTES = 262144;
 
+export declare const DEFAULT_SOCKET_STALL_WARN_AFTER_MS = 5000;
+
 /**
  * How old a row may be before a reader should stop trusting it as current.
  *
@@ -3650,7 +3688,7 @@ export declare const enableGraphObservation: () => void;
  * not: their session rows written here were unreadable through the store, and
  * the error blamed the key.
  */
-export declare const encryptField: (plaintext: string) => string;
+export declare const encryptField: (plaintext: string, binding?: FieldBinding) => string;
 
 /**
  * The dispatch-spine entry point. A no-op for a descriptor with no policy; a
@@ -3721,7 +3759,11 @@ export declare const evaluateTouchedRules: (params: {
     readonly subject: unknown;
 }) => Promise<void>;
 
-declare type Event_2 = SubscriptionEvent<ReadonlyArray<Row>>;
+/** The outbox is generic in the payload: a descriptor subscription carries an
+ *  id-keyed row set (and deltas against it), a computed one carries whatever
+ *  its handler returned (snapshots only). Coalescing differs only in whether a
+ *  patch can be diffed — everything else is the same policy. */
+declare type Event_2<T> = SubscriptionEvent<T>;
 
 /**
  * How many deliveries one client may fall behind before the oldest are dropped.
@@ -4744,8 +4786,14 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
      * Scoping is identical to `query()` (tenant + soft-delete apply), because it
      * IS `query()` underneath — the probe just asks for one row more than it
      * needs so "the first of several" cannot masquerade as "the one you meant".
+     *
+     * `onMissing` turns the refusal into YOUR typed error: it receives the same
+     * `{ table, found }` `NoRowFound` carries and whatever it returns is thrown
+     * instead — `ctx.store.one(q, () => new NotFoundError({ resource: 'user', id }))`.
+     * A contract that already declares its not-found error keeps it, without a
+     * `maybeOne` + `if (row === null)` hop at every call site.
      */
-    one<R = Row_7>(query: QueryLike<R>): Promise<R>;
+    one<R = Row_7>(query: QueryLike<R>, onMissing?: OnMissingRow): Promise<R>;
     /** Terminal: the first matching row or `null`, TYPED. Use when "any match" is
      *  genuinely what you mean. */
     first<R = Row_7>(query: QueryLike<R>): Promise<R | null>;
@@ -5375,6 +5423,8 @@ export declare interface IssueInput {
     readonly metadata?: Readonly<Record<string, unknown>> | null;
 }
 
+export declare const isTransactionReadConflict: (err: unknown) => err is TransactionReadConflict;
+
 /** Is `address` one of the peers we are willing to take a forwarded chain from? */
 export declare const isTrustedProxy: (address: string | undefined, config: TrustedProxyConfig) => boolean;
 
@@ -5629,12 +5679,17 @@ export declare const makeAdvisoryLockCoordinator: (store: DataStore, replicaId:
 log?: SchedulerLogger) => Coordinator;
 
 /**
- * Build an AES-256-GCM cipher. Ciphertext format:
- * `enc:v1:<ivB64>:<tagB64>:<ctB64>` — a random 12-byte IV per call (so
- * the same plaintext encrypts differently each time), plus the GCM auth
- * tag for tamper detection. `decrypt` throws on a tampered/wrong-key
- * value (GCM auth failure) — that surfaces as a read error, never
- * silent corruption.
+ * Build an AES-256-GCM cipher. Two envelopes, one key:
+ *
+ *   `enc:v1:<ivB64>:<tagB64>:<ctB64>`        unbound — no binding given
+ *   `enc:v2:<r|c>:<ivB64>:<tagB64>:<ctB64>`  bound — the GCM tag also covers
+ *                                             `binding.row` (`r`) or
+ *                                             `binding.column` (`c`)
+ *
+ * A random 12-byte IV per call (the same plaintext encrypts differently each
+ * time), plus the GCM auth tag for tamper detection. `decrypt` throws on a
+ * tampered / wrong-key value AND on a bound value read at another address —
+ * both surface as a read error, never silent corruption.
  */
 export declare const makeAesCipher: (key: Buffer) => FieldCipher;
 
@@ -5983,7 +6038,7 @@ export declare const makeSubmitTokenExecutor: (deps: ConnectionBuiltinDeps) => (
     readonly ok: boolean;
 }>;
 
-export declare const makeSubscriptionOutbox: (options: SubscriptionBackpressureOptions) => SubscriptionOutbox;
+export declare const makeSubscriptionOutbox: <T = ReadonlyArray<Row>>(options: SubscriptionBackpressureOptions) => SubscriptionOutbox<T>;
 
 /**
  * The factory the serve entrypoints inject into `makeMutationRunner`'s
@@ -6024,6 +6079,34 @@ export declare const makeWorkflowLayers: <Context>(workflows: ReadonlyArray<Disc
 
 export declare const makeWorkflowRunHandle: (workflowName: string, executionId: string) => WorkflowRunHandle;
 
+/**
+ * Build the shared WORKFLOW START runner — the third member of the family,
+ * beside `makeMutationRunner` and `makeActionRunner`, for the unary rpc a
+ * `*.workflow.tsx` becomes on the wire.
+ *
+ * It existed on neither boot path. Both bound the start handler straight to
+ * the workflow facade, outside every plugin interceptor and with no guard
+ * check — measured with an anonymous socket: a query declaring
+ * `guards: [{ scope }]` answered `ScopeError`, the workflow beside it answered
+ * a run handle. So the three things this runner does are the three things a
+ * start never had:
+ *
+ *   1. `enforceGuards` — the workflow's `guards:` / `openAccess:` decision,
+ *      BEFORE the run row is written or the engine is asked for anything.
+ *      Under `defaultDeny` an undecided workflow is refused per request, the
+ *      defense-in-depth behind the boot gate exactly as for a mutation.
+ *   2. the plugin `interceptWorkflow` chain — audit records the start, rate
+ *      limiting counts it, rbac publishes the caller's role scopes so (1) can
+ *      see them. Without the chain, a role-derived scope guard could never pass.
+ *   3. a metric sample under `workflow.<name>`, so the rpc panel shows starts
+ *      beside mutations instead of a surface that does not exist there.
+ *
+ * `start` is injected rather than the facade: the two boot paths build their
+ * caller-context facade differently, and this runner owns the composition,
+ * not the engine.
+ */
+export declare const makeWorkflowStartRunner: (deps: WorkflowStartRunnerDeps) => (workflow: WorkflowStartLike, input: unknown, requestContext: ServeRequestContext, start: () => Promise<unknown>) => Promise<unknown>;
+
 /**
  * Mark a wakeup as handled. The row is kept (not deleted) so a crash
  * between firing and the producer re-registering the next occurrence is
@@ -6286,6 +6369,9 @@ export declare type MetricsMode = 'off' | 'console' | 'otlp' | 'memory';
  */
 export declare type MirrorVersion = number;
 
+/** The error `.one()` throws: the factory's, or the framework's `NoRowFound`. */
+export declare const missingRowError: (info: NoRowFoundInfo, onMissing: OnMissingRow | undefined) => unknown;
+
 export declare interface MutationLifecycle {
     readonly afterCommit: (work: () => Promise<unknown>) => void;
 }
@@ -6325,6 +6411,13 @@ export declare interface MutationOutputCodec<Output> {
 
 export declare interface MutationRunnerDeps {
     readonly store: TransactionalStore;
+    /**
+     * How many times a mutation's transaction runs before a replayable failure
+     * (contention, a transaction-read conflict) surfaces. Resolved by the CLI
+     * from `app.config.ts` `mutations.replayAttempts` (env
+     * `VOLTRO_MUTATION_REPLAY_ATTEMPTS` wins); absent → the default.
+     */
+    readonly replayAttempts?: number;
     /**
      * `security.defaultDeny`, threaded to the dispatch spine: `true` refuses a
      * descriptor with NO access decision per-request (typed `ScopeError`, the
@@ -6509,6 +6602,13 @@ declare const NoRowFound_base: Schema.TaggedErrorClass<NoRowFound, "NoRowFound",
     found: typeof Schema.Number;
 }>;
 
+/** What `.one()` hands an `onMissing` factory — the two facts `NoRowFound` carries. */
+export declare interface NoRowFoundInfo {
+    readonly table: string;
+    /** `0` — no row; `2` — at least two, the filter is not unique. */
+    readonly found: number;
+}
+
 /** Note one read against the in-flight procedure. No scope → nothing happens. */
 export declare const noteRead: (descriptor: QueryDescriptor) => void;
 
@@ -6621,6 +6721,14 @@ export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D>
     readonly queryRows: (descriptor: D, context: ServeRequestContext) => Promise<ReadonlyArray<unknown>>;
 }
 
+/**
+ * Turn `.one()`'s refusal into the caller's own typed error. Whatever it
+ * returns is THROWN — so a contract that declares `NotFoundError({ resource,
+ * id })` keeps declaring it, and the call site is `one(q, () => new
+ * NotFoundError(...))` instead of `maybeOne` + a null branch at every read.
+ */
+export declare type OnMissingRow = (info: NoRowFoundInfo) => unknown;
+
 /**
  * Register teardown to run on SIGINT/SIGTERM, before the launches are drained
  * and the process exits. Returns a de-register function.
@@ -6814,6 +6922,12 @@ export declare interface OutboxHandlerDefinition {
     readonly maxAttempts?: number;
 }
 
+/** What the pump hands events to — the `emit` of a `Stream.asyncScoped`. */
+export declare interface OutboxSink<T> {
+    readonly single: (event: Event_2<T>) => Promise<unknown>;
+    readonly end: () => unknown;
+}
+
 export declare type OutboxStatus = 'pending' | 'delivering' | 'delivered' | 'dead';
 
 export declare const outboxTable: TableLike;
@@ -6924,6 +7038,13 @@ export declare interface PluginRefRule {
     readonly targetTable: string;
     readonly policy: PluginRefOrphanPolicy;
     readonly onSoftDelete: boolean;
+    /**
+     * Fire on a HARD delete of the target. Default `true` — a `pluginRef` has no
+     * foreign key, so the runtime is the only thing that can clean up. `false`
+     * for a `reference(…, { onSoftDelete })` rule: its hard delete IS a foreign
+     * key, and the database already did whatever `onDelete` says.
+     */
+    readonly onHardDelete?: boolean;
 }
 
 /** The store surface the enforcement needs. */
@@ -7074,6 +7195,36 @@ export declare const publishEvent: <Name extends string, Key extends Schema.Sche
  */
 export declare const publishServerTracerLayer: Layer.Layer<never, never, never>;
 
+export declare interface PumpOptions {
+    /** Override the process-wide tunable (tests). */
+    readonly stallWarnAfterMs?: number;
+    readonly warn?: (message: string, fields: Record<string, unknown>) => void;
+}
+
+/**
+ * The pump between an outbox and its stream: hand events over ONE at a time,
+ * awaiting each acceptance — that await is the backpressure signal the outbox
+ * coalesces behind. `take()` resolves null once the outbox closes (scope
+ * teardown, or the terminal overrun error has drained).
+ *
+ * ONE definition for every subscription binder (descriptor, adopted-on-resume,
+ * computed). The three used to carry the same loop inline; a diagnostic added
+ * to one of them would have been absent from the other two.
+ *
+ * **The stall diagnostic.** `@effect/rpc` delivers a stream as `Chunk`
+ * messages and waits for the client's `Ack` of each before writing the next.
+ * The typed client acknowledges by itself; a hand-rolled socket client that
+ * only listens receives exactly one Chunk per subscription — the snapshot — and
+ * every later delivery parks behind the missing Ack. From the outside that is
+ * indistinguishable from "the server never produced an update", and it was
+ * reported as exactly that: the producer, the matcher and the registry all
+ * looked healthy because they were. The stream's buffer is ONE event deep, so
+ * the second delivery a stalled consumer does not accept blocks HERE — and a
+ * delivery the transport has not accepted within `stallWarnAfterMs` is said out
+ * loud, with the cause named, and counted in `voltro_subscription_stalled_total`.
+ */
+export declare const pumpOutbox: <T>(outbox: SubscriptionOutbox<T>, sink: OutboxSink<T>, label: string, options?: PumpOptions) => Promise<void>;
+
 /**
  * The two scopes, composed once, for every path that finalises a descriptor.
  *
@@ -7346,7 +7497,8 @@ export declare interface ReactiveConfigInput {
      * threshold is closed with a typed `SubscriptionOverrun` (it re-subscribes
      * for a fresh snapshot). Resolved by the CLI's `reactiveTunables.ts`; env
      * overrides win: `VOLTRO_REACTIVE_MAX_BUFFERED_BYTES` /
-     * `VOLTRO_REACTIVE_OVERRUN_AFTER_MS` / `VOLTRO_REACTIVE_OVERSIZED_EVENT_BYTES`.
+     * `VOLTRO_REACTIVE_OVERRUN_AFTER_MS` / `VOLTRO_REACTIVE_OVERSIZED_EVENT_BYTES` /
+     * `VOLTRO_REACTIVE_STALL_WARN_AFTER_MS`.
      */
     readonly socket?: {
         /** Estimated pending bytes per subscription above which a persistently
@@ -7357,6 +7509,11 @@ export declare interface ReactiveConfigInput {
         readonly overrunAfterMs?: number;
         /** Per-event WARN threshold (telemetry, NOT a cap). Default 256 KiB. */
         readonly oversizedEventBytes?: number;
+        /** How long a delivery may sit unaccepted by the transport before the
+         *  server says so — a WARN naming the subscription and the missing
+         *  `@effect/rpc` `Ack`, plus `voltro_subscription_stalled_total`.
+         *  Default 5_000 ms. */
+        readonly stallWarnAfterMs?: number;
     };
 }
 
@@ -7377,6 +7534,9 @@ export declare interface ReactiveSocketTunables {
     readonly maxBufferedBytes: number;
     readonly overrunAfterMs: number;
     readonly oversizedEventBytes: number;
+    /** How long a delivery may sit unaccepted by the transport before the pump
+     *  says so (WARN + `voltro_subscription_stalled_total`). See `pumpOutbox`. */
+    readonly stallWarnAfterMs: number;
 }
 
 /** The resolved tunables, or the defaults when no boot path has set any
@@ -7574,6 +7734,10 @@ export declare const recordSample: (s: RecordedSample) => void;
  */
 export declare const recordScheduleRun: (r: ScheduleRunRecord) => void;
 
+/** A delivery the pump handed to the stream that the transport did not accept
+ *  within the stall threshold — the consumer is not acknowledging chunks. */
+export declare const recordStalled: (label: string) => void;
+
 /** Move the live-subscriptions gauge for `label`'s tag by `delta` (+1 open, -1 close). */
 export declare const recordSubscriptionActive: (label: string, delta: number) => void;
 
@@ -8833,6 +8997,9 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
     /** Public raw-HTTP routes contributed by plugins (e.g. storage
      *  byte-serving). Mounted on the same listener as rpc + inspect. */
     readonly httpRoutes?: ReadonlyArray< PluginHttpRoute>;
+    /** Called after every plugin HTTP route answers — the composed plugins'
+     *  `onHttpRoute` hooks. Fire-and-forget; a throw never reaches the client. */
+    readonly onHttpRoute?: HttpRouteObserver;
     /** The app's DataStore, for `PluginHttpRouteRequest.store`. A getter rather
      *  than a value: routes mount before the store is built, and the two boot
      *  paths build it on opposite sides of that point. */
@@ -9070,6 +9237,10 @@ export declare const runWakeLoop: (deps: WakeOrchestratorDeps, intervalMs?: numb
  */
 export declare const runWithDeadlockRetry: <T>(work: () => Promise<T>, options?: {
     readonly delay?: (attempt: number) => Promise<void>;
+    /** How many times the transaction runs in total before the failure
+     *  surfaces. Default {@link DEFAULT_MUTATION_REPLAY_ATTEMPTS}; a hot row
+     *  with many simultaneous writers may need more — or a row lock. */
+    readonly attempts?: number;
 }) => Promise<T>;
 
 /**
@@ -9671,6 +9842,8 @@ export declare class SelectBuilder {
     where(...args: ReadonlyArray<unknown>): SelectBuilder;
     orderBy(column: string, direction?: 'asc' | 'desc'): SelectBuilder;
     limit(n: number): SelectBuilder;
+    /** Lock the matched rows for the rest of the transaction — see `Query.forUpdate`. */
+    forUpdate(): SelectBuilder;
     offset(n: number): SelectBuilder;
     select(...columns: ReadonlyArray<string>): SelectBuilder;
     using(indexName: string): SelectBuilder;
@@ -9698,8 +9871,10 @@ export declare class SelectBuilder {
      * the bug would surface far away from its cause. One extra row on the
      * wire buys a loud failure at the point the assumption breaks. Use
      * `.first()` / `.maybeOne()` when you genuinely want "any match".
+     *
+     * `onMissing` swaps the thrown error for yours — see `OnMissingRow`.
      */
-    one(): Promise<Row>;
+    one(onMissing?: OnMissingRow): Promise<Row>;
     /** Terminal: COUNT(*) of matching rows (real aggregate, not a fetch). */
     count(): Promise<number>;
     /** Terminal: does any row match? Uses a `LIMIT 1` probe. */
@@ -9775,7 +9950,7 @@ export declare const serverOnlyLeaks: (query: AuditableQuery, serverOnlyByTable:
 /** A plugin interceptor — wraps the base run Effect (Effect-native chain). */
 export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown, never>, meta: {
     readonly tag: string;
-    readonly kind: 'mutation' | 'action' | 'query';
+    readonly kind: 'mutation' | 'action' | 'query' | 'workflow';
     readonly input: unknown;
     readonly subject: unknown;
     readonly traceId: string;
@@ -10328,13 +10503,13 @@ export declare interface SubscriptionDeliveryRecord {
     readonly rowCount: number;
 }
 
-export declare interface SubscriptionOutbox {
+export declare interface SubscriptionOutbox<T = ReadonlyArray<Row>> {
     /** SYNC push from the dispatcher's emit callback. */
-    readonly push: (event: Event_2) => void;
+    readonly push: (event: Event_2<T>) => void;
     /** Pump side: resolves with the next event to hand into the stream —
      *  coalesced when more than one push landed since the last take — or null
      *  once the outbox is closed and drained. */
-    readonly take: () => Promise<Event_2 | null>;
+    readonly take: () => Promise<Event_2<T> | null>;
     /** True once the overrun policy fired (the error event has been queued;
      *  the stream ends after it drains). */
     readonly overrun: () => boolean;
@@ -10436,6 +10611,10 @@ export declare interface SubscriptionSocketMetricsSnapshot {
         readonly total: number;
         readonly byLabel: Readonly<Record<string, number>>;
     };
+    readonly stalledTotal: {
+        readonly total: number;
+        readonly byLabel: Readonly<Record<string, number>>;
+    };
 }
 
 export declare const subscriptionSocketMetricsSnapshot: () => SubscriptionSocketMetricsSnapshot;
@@ -10722,11 +10901,19 @@ export declare interface TracingOptions {
     readonly sampler?: Sampler;
 }
 
+export declare const TRANSACTION_READ_CONFLICT_NAME = "VoltroTransactionReadConflict";
+
 /** The store surface the runner needs — just the transactional wrap. */
 export declare interface TransactionalStore {
     transactional<T>(work: (tx: unknown) => Promise<T>): Promise<T>;
 }
 
+export declare class TransactionReadConflict extends Error {
+    readonly conflict: VersionConflict;
+    readonly name = "VoltroTransactionReadConflict";
+    constructor(conflict: VersionConflict);
+}
+
 /**
  * Transport-level security policy for the api listener.
  *
@@ -10872,6 +11059,10 @@ export declare type TupleSource = (req: {
     readonly load: DataLoader | undefined;
 }) => Promise<ReadonlyArray<RelationTuple>> | ReadonlyArray<RelationTuple>;
 
+/** The mutation runner's key for opening the read-version map on a transaction
+ *  view it obtained from the dialect store directly. */
+export declare const TX_READ_VERSIONS_KEY: unique symbol;
+
 /**
  * Drop everything this connection accumulated. Called by the WS-close finalizer
  * and by explicit sign-out flows. Idempotent.
@@ -11786,6 +11977,13 @@ export declare class WorkflowSingletonHeldError extends Error {
     constructor(workflowName: string, executionId: string);
 }
 
+/** The slice of a `workflow()` definition the start runner reads — its name
+ *  and its resolved access decision (`workflowAccessDescriptor` produces it). */
+export declare interface WorkflowStartLike {
+    readonly name: string;
+    readonly guards?: ReadonlyArray<AnyCheckSpec> | undefined;
+}
+
 export declare interface WorkflowStartOptions {
     readonly wait?: boolean;
     /**
@@ -11816,18 +12014,13 @@ export declare interface WorkflowStartOptions {
     /* Excluded from this release type: admitted */
 }
 
-export declare const workflowToRpc: (workflow: WorkflowDefinitionLike) => Rpc.Rpc<string, Schema.Schema.Any, Schema.Struct<{
-    id: typeof Schema.String;
-    workflowName: typeof Schema.String;
-    executionId: Schema.NullOr<typeof Schema.String>;
-    status: Schema.Literal<["running", "queued", "dropped", "skipped"]>;
-    deferral: Schema.optional<Schema.Struct<{
-        mode: typeof Schema.String;
-        dueAt: Schema.NullOr<typeof Schema.Number>;
-        retryAfterMs: Schema.NullOr<typeof Schema.Number>;
-        intentId: Schema.NullOr<typeof Schema.String>;
-    }>>;
-}>, Schema.Schema.All, never>;
+export declare interface WorkflowStartRunnerDeps {
+    /** Composed plugin workflow-interceptor (`interceptWorkflow`). */
+    readonly interceptor?: ServeRpcInterceptor;
+    readonly recordMetric?: MutationRunnerDeps['recordMetric'];
+    /** See {@link MutationRunnerDeps.defaultDeny} — same flag, same refusal. */
+    readonly defaultDeny?: boolean;
+}
 
 export declare interface WorkflowUpdateOptions {
     readonly timeoutMs?: number;