@voltro/workflow 0.80.0 → 0.82.0

package/dist/cluster.d.ts

@@ -5,9 +5,16 @@ import { DataStore } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
+import { MalformedMessage } from '@effect/cluster/ClusterError';
 import { MessageStorage } from '@effect/cluster';
+import { MysqlCharset } from '@voltro/database/sql';
+import { PersistenceError } from '@effect/cluster/ClusterError';
+import { QueryDescriptor } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { Schema } from 'effect';
 import { Sharding } from '@effect/cluster';
 import { SqlClient } from '@effect/sql';
+import { SqlClient as SqlClient_2 } from '@effect/sql/SqlClient';
 import { SqlError } from '@effect/sql';
 import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Workflow } from '@effect/workflow';
@@ -22,6 +29,43 @@ import { WorkflowEngine } from '@effect/workflow';
  */
 export declare const activityPrimaryKey: (activityName: string, attempt: number) => string;
 
+/** The narrow slice of `DataStore` flow control needs. */
+declare interface AdmissionDataStore {
+    /** Native arbitration, preserved by every resident transaction adapter. */
+    readonly insertIgnoreWithOutcome: DataStore['insertIgnoreWithOutcome'];
+    /** Host schema codecs: queue rows carry encoded values, controls and the
+     * engine consume decoded payloads. Absent for a JSON-only low-level host. */
+    readonly encodeWorkflowPayload?: (workflowName: string, payload: unknown) => unknown;
+    readonly decodeWorkflowPayload?: (workflowName: string, payload: unknown) => unknown;
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    insert(table: string, row: Row): Promise<Row>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
+    delete(table: string, primaryKey: string): Promise<boolean>;
+    upsert(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+}
+
+/** The run currently holding a singleton key. */
+declare interface AdmissionIncumbent {
+    readonly executionId: string;
+    readonly runId: string;
+    /** Epoch ms, for the "how long has it held this" the ledger reports. */
+    readonly admittedAt: number;
+}
+
+/** Every flow-control key resolved against ONE concrete payload. */
+declare interface AdmissionKeys {
+    readonly debounceKey?: string;
+    readonly singletonKey?: string;
+    readonly concurrencyKey?: string;
+    readonly throttleKey?: string;
+    readonly rateLimitKey?: string;
+    readonly batchKey?: string;
+    readonly priority: number;
+}
+
 /** Database-only capture while holding the resident admission/entry lock.
  * observe reads the journal; it must never wake/reset the engine. Missing
  * journal evidence waits without inventing a binding. After commit, every
@@ -55,11 +99,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -68,7 +113,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "unknown";
@@ -94,11 +138,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -107,7 +152,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "superseded";
@@ -133,11 +177,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -146,7 +191,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "not-suspended";
@@ -172,11 +216,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -185,7 +230,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "bound";
@@ -211,11 +255,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -224,7 +269,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "waiting-journal";
@@ -250,11 +294,12 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -263,7 +308,6 @@ declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, ob
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 }>;
 
@@ -349,17 +393,50 @@ declare interface ClusterMessageState {
     readonly lastRead: Date | null;
 }
 
+/**
+ * A pass-through `SqlClient` layer that runs the cluster first-boot migration
+ * (serialized behind the reserved-connection migration lock) as a build
+ * side-effect, then re-exposes the SAME `SqlClient`. Provided in place of the raw
+ * dialect SqlClient layer so the cluster engine consumes THIS one — forcing the
+ * migration to complete before `SingleRunner` builds and hits its own (now no-op)
+ * DDL. Skipped entirely on the warm path, so a running cluster and single-runner
+ * restarts cost nothing.
+ */
+export declare const clusterMigrationGateLayer: (opts: {
+    readonly runnerStorage: RunnerStorage;
+    /** The declared store charset (mysql family) — the tables this gate creates are created in it. */
+    readonly charset?: MysqlCharset | undefined;
+}) => Layer.Layer<SqlClient.SqlClient, SqlError.SqlError, SqlClient.SqlClient>;
+
 declare interface ClusterRunner {
     readonly address: string;
     readonly lastHeartbeat: Date | null;
     readonly healthy: boolean;
 }
 
+declare type Command = Parameters<typeof readWorkflowRestartReservationInTransaction>[1];
+
 declare type ControlStore = Parameters<typeof bindWorkflowResumeJournalInTransaction>[0];
 
 /** Default port for the cluster's single-runner listener. Override per deploy. */
 export declare const DEFAULT_RUNNER_LISTEN_PORT: 34000;
 
+declare type DeferMode = DeferringControl | 'paused' | 'singleton';
+
+/**
+ * Controls that can DEFER a start rather than answer it immediately.
+ *
+ * The distinction matters at exactly one place: `ctx.workflows.run(...)` and
+ * `start(..., { wait: true })` block for the run's RESULT. There is no coherent
+ * result to return for a start that was collapsed into a future run, so those
+ * two callers reject a deferring control loudly instead of doing something
+ * surprising. Admission controls that have a synchronous answer — singleton,
+ * rate limit — still apply on every path.
+ */
+declare const DEFERRING_CONTROLS: readonly ["debounce", "batch", "throttle", "concurrency"];
+
+declare type DeferringControl = (typeof DEFERRING_CONTROLS)[number];
+
 /** Probe the live connection for an active wsrep (Galera / Percona XtraDB)
  *  cluster. `@@wsrep_on = 1` iff Galera replication is active; the variable is
  *  absent on stock MySQL (→ query errors → not a wsrep cluster) and `0` on a
@@ -368,6 +445,28 @@ export declare const DEFAULT_RUNNER_LISTEN_PORT: 34000;
  *  somehow can't be probed can still force `VOLTRO_WORKFLOW_SHARD_LOCK=row`. */
 export declare const detectWsrepCluster: Effect.Effect<boolean, never, SqlClient.SqlClient>;
 
+/** Internal dispatch only. A reset or poll is not evidence of body entry.
+ * The caller must reserve the resident generation and provide its capacity
+ * coordinator before dispatching. Inspect does not use this capability yet. */
+declare const dispatchWorkflowRestart: (options: Parameters<typeof resetReservedWorkflowJournal>[0]) => Effect.Effect<{
+    kind: "waiting-capacity";
+} | {
+    kind: "attempted";
+    journal: {
+        kind: "changed";
+        requestId: string;
+        count?: never;
+    } | {
+        kind: "already-reset";
+        count: number;
+        requestId?: never;
+    } | {
+        kind: "reset";
+        count: number;
+        requestId?: never;
+    };
+}, SqlError_2, SqlClient.SqlClient | Sharding.Sharding>;
+
 /** Internal cluster dispatch, not an acceptance or completion API. The host
  * supplies the resident admission transaction and the matching journal layer.
  * Only the recorder's next entry can confirm the persisted resume receipt. */
@@ -398,11 +497,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -411,7 +511,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "unknown";
@@ -437,11 +536,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -450,7 +550,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "superseded";
@@ -476,11 +575,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -489,7 +589,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "not-suspended";
@@ -515,11 +614,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -528,7 +628,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "waiting-journal";
@@ -554,11 +653,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -567,7 +667,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
 } | {
     kind: "already-terminal";
@@ -593,11 +692,12 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         readonly generation: string;
+        readonly runId: string;
         readonly requestedAt: number;
         readonly executionId: string;
-        readonly runId: string;
         readonly workflowName: string;
         readonly operation: "resume" | "cancel" | "terminate";
+        readonly dispatchAttempts: number;
         readonly owner: {
             readonly tenantId: string | null;
         } | null;
@@ -606,7 +706,6 @@ declare const dispatchWorkflowResume: (options: {
             readonly replyId: string;
             readonly restartToken: string | null;
         } | null;
-        readonly dispatchAttempts: number;
     };
     run: Readonly<Record<string, unknown>>;
 } | {
@@ -634,9 +733,9 @@ declare const dispatchWorkflowResume: (options: {
             readonly enteredAt: number;
         } | null;
         generation: string;
+        runId: string;
         requestedAt: number;
         executionId: string;
-        runId: string;
         workflowName: string;
         operation: "resume" | "cancel" | "terminate";
         owner: {
@@ -663,6 +762,12 @@ declare const dispatchWorkflowResume: (options: {
     };
 }, SqlError_2, SqlClient.SqlClient | Sharding.Sharding>;
 
+/** An immutable observation, not merely an execution/request identity. */
+declare interface ExpectedWorkflowReply {
+    readonly requestId: string;
+    readonly replyId: string;
+}
+
 /** A step attempt to reset so it re-executes on the next drive. */
 export declare interface FailedActivityRef {
     readonly name: string;
@@ -679,6 +784,43 @@ export declare const makeClusterCronLayer: (spec: ClusterCronSpec) => Layer.Laye
 
 export declare const makeClusterDiagnostics: (options: ClusterDiagnosticsOptions) => Effect.Effect<ClusterDiagnosticsOps, never, SqlClient.SqlClient>;
 
+declare type Observation = {
+    readonly kind: 'observed';
+    readonly replies: ReadonlyArray<ExpectedWorkflowReply>;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+
+/** Read-only capture of exact replies in the engine journal. The resident
+ * reservation must bind these observations to its failed generation; the
+ * subsequent reset compares every reply again before changing anything. */
+declare const observeWorkflowRestartReplies: (target: WorkflowRestartObservationTarget) => Effect.Effect<{
+    kind: "unavailable";
+    reason: "no-journal";
+    replies?: never;
+} | {
+    kind: "unavailable";
+    reason: "delivery-changed";
+    replies?: never;
+} | {
+    kind: "unavailable";
+    reason: "no-reply";
+    replies?: never;
+} | {
+    kind: "unavailable";
+    reason: "succeeded" | "suspended" | "unrecognized-reply";
+    replies?: never;
+} | {
+    kind: "unavailable";
+    reason: "activity-not-found";
+    replies?: never;
+} | {
+    kind: "observed";
+    replies: readonly ExpectedWorkflowReply[];
+    reason?: never;
+}, SqlError_2 | PersistenceError, SqlClient.SqlClient | Sharding.Sharding | MessageStorage.MessageStorage>;
+
 /** Parse `VOLTRO_WORKFLOW_SHARD_LOCK` (default `'auto'`). Throws on an
  *  unrecognized value so a typo fails boot loudly instead of silently keeping
  *  the advisory path that breaks cross-pod handoff on Galera. */
@@ -694,6 +836,240 @@ export declare const parseShardLockMode: (raw?: string | undefined) => ShardLock
  */
 export declare const pollWorkflowStorage: Effect.Effect<void, never, Sharding.Sharding>;
 
+/** Prepare against the resident owner, observe through the engine, then reserve
+ * against the same owner. No resident transaction spans journal I/O. Recovery
+ * reads the accepted command before looking at journal replies that a previous
+ * dispatch may already have reset. This does not dispatch or authorize entry. */
+declare const prepareWorkflowRestart: (options: {
+    readonly transaction: <T>(body: (tx: AdmissionDataStore) => Promise<T>) => Promise<T>;
+    readonly command: Command;
+    readonly workflow: Workflow.Any;
+    readonly readActivities: (tx: AdmissionDataStore) => Promise<ReadonlyArray<FailedActivityRef>>;
+    readonly control: ResolvedFlowControl;
+    readonly readPaused: (tx: AdmissionDataStore) => Promise<boolean>;
+    readonly now: number;
+    readonly createToken: () => string;
+    readonly observe: (target: WorkflowRestartObservationTarget) => Promise<Observation>;
+}) => Promise<{
+    kind: "reserved";
+    request: {
+        readonly id: string;
+        readonly tenantId: string | null;
+        readonly token: string;
+        readonly generation: string;
+        readonly runId: string;
+        readonly requestedAt: Date;
+        readonly executionId: string;
+        readonly workflowName: string;
+        readonly selection: {
+            readonly kind: "failed-steps";
+        } | {
+            readonly kind: "from-step";
+            readonly stepName: string;
+        };
+        readonly dispatchAttempts: number;
+        readonly enteredGeneration: string | null;
+        readonly ledgerId: string;
+        readonly eviction: {
+            readonly runId: string;
+            readonly executionId: string;
+        } | null;
+        readonly delivery: {
+            readonly requestId: string;
+            readonly restartToken: string | null;
+        };
+        readonly replies: readonly {
+            readonly requestId: string;
+            readonly replyId: string;
+        }[];
+    };
+    reused: boolean;
+    decision?: never;
+} | {
+    kind: "already-requested";
+    request?: never;
+    reused?: never;
+    decision?: never;
+} | {
+    kind: "not-admitted";
+    decision: {
+        readonly kind: "defer";
+        readonly mode: DeferMode;
+        readonly dueAt: number;
+        readonly deadlineAt?: number;
+        readonly collapse: "replace" | "append" | "hold";
+        readonly keys: AdmissionKeys;
+    } | {
+        readonly kind: "drop";
+        readonly reason: "rate-limit";
+        readonly retryAfterMs: number;
+        readonly keys: AdmissionKeys;
+    } | {
+        readonly kind: "skip";
+        readonly incumbent: AdmissionIncumbent;
+        readonly keys: AdmissionKeys;
+    };
+    request?: never;
+    reused?: never;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+}>;
+
+/** Host command boundary: recover an immutable receipt before reading the run's
+ * current generation. A lost response must not turn a retry into a new restart
+ * after the first restart has entered, completed, or failed again. The caller
+ * has already resolved the physical resident and trusted workflow/tenant. */
+declare const prepareWorkflowRestartCommand: (options: Omit<Parameters<typeof prepareWorkflowRestart>[0], "command"> & {
+    readonly command: Parameters<typeof readWorkflowRestartCommandInTransaction>[1];
+}) => Promise<{
+    kind: "reserved";
+    request: {
+        readonly id: string;
+        readonly tenantId: string | null;
+        readonly token: string;
+        readonly generation: string;
+        readonly runId: string;
+        readonly requestedAt: Date;
+        readonly executionId: string;
+        readonly workflowName: string;
+        readonly selection: {
+            readonly kind: "failed-steps";
+        } | {
+            readonly kind: "from-step";
+            readonly stepName: string;
+        };
+        readonly dispatchAttempts: number;
+        readonly enteredGeneration: string | null;
+        readonly ledgerId: string;
+        readonly eviction: {
+            readonly runId: string;
+            readonly executionId: string;
+        } | null;
+        readonly delivery: {
+            readonly requestId: string;
+            readonly restartToken: string | null;
+        };
+        readonly replies: readonly {
+            readonly requestId: string;
+            readonly replyId: string;
+        }[];
+    };
+    reused: boolean;
+    decision?: never;
+} | {
+    kind: "already-requested";
+    request?: never;
+    reused?: never;
+    decision?: never;
+} | {
+    kind: "not-admitted";
+    decision: {
+        readonly kind: "defer";
+        readonly mode: DeferMode;
+        readonly dueAt: number;
+        readonly deadlineAt?: number;
+        readonly collapse: "replace" | "append" | "hold";
+        readonly keys: AdmissionKeys;
+    } | {
+        readonly kind: "drop";
+        readonly reason: "rate-limit";
+        readonly retryAfterMs: number;
+        readonly keys: AdmissionKeys;
+    } | {
+        readonly kind: "skip";
+        readonly incumbent: AdmissionIncumbent;
+        readonly keys: AdmissionKeys;
+    };
+    request?: never;
+    reused?: never;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+}>;
+
+/** Read an accepted command before observing the journal again. Its captured
+ * replies remain authoritative after reset or body entry. This grants no new
+ * dispatch permission: dispatch must still recheck the resident generation. */
+declare const readWorkflowRestartCommandInTransaction: (tx: AdmissionDataStore, input: {
+    readonly id: string;
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly tenantId: string | null;
+    readonly selection: WorkflowRestartSelection;
+}) => Promise<{
+    readonly id: string;
+    readonly tenantId: string | null;
+    readonly token: string;
+    readonly generation: string;
+    readonly runId: string;
+    readonly requestedAt: Date;
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly selection: {
+        readonly kind: "failed-steps";
+    } | {
+        readonly kind: "from-step";
+        readonly stepName: string;
+    };
+    readonly dispatchAttempts: number;
+    readonly enteredGeneration: string | null;
+    readonly ledgerId: string;
+    readonly eviction: {
+        readonly runId: string;
+        readonly executionId: string;
+    } | null;
+    readonly delivery: {
+        readonly requestId: string;
+        readonly restartToken: string | null;
+    };
+    readonly replies: readonly {
+        readonly requestId: string;
+        readonly replyId: string;
+    }[];
+} | undefined>;
+
+/** Internal owner check after a generation has been captured. Command recovery
+ * deliberately does not derive that generation from the run's current state. */
+declare const readWorkflowRestartReservationInTransaction: (tx: AdmissionDataStore, input: Parameters<typeof readWorkflowRestartCommandInTransaction>[1] & {
+    readonly generation: string;
+}) => Promise<{
+    readonly id: string;
+    readonly tenantId: string | null;
+    readonly token: string;
+    readonly generation: string;
+    readonly runId: string;
+    readonly requestedAt: Date;
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly selection: {
+        readonly kind: "failed-steps";
+    } | {
+        readonly kind: "from-step";
+        readonly stepName: string;
+    };
+    readonly dispatchAttempts: number;
+    readonly enteredGeneration: string | null;
+    readonly ledgerId: string;
+    readonly eviction: {
+        readonly runId: string;
+        readonly executionId: string;
+    } | null;
+    readonly delivery: {
+        readonly requestId: string;
+        readonly restartToken: string | null;
+    };
+    readonly replies: readonly {
+        readonly requestId: string;
+        readonly replyId: string;
+    }[];
+} | undefined>;
+
+/** Observe the persisted run delivery without decoding it against a possibly
+ * changed workflow schema. Read failures remain errors, never `not-found`.
+ * This does not acknowledge replies, reset storage or dispatch an execution. */
+export declare const readWorkflowRunReply: (workflow: Workflow.Any, executionId: string) => Effect.Effect<WorkflowRunReplyObservation, PersistenceError | MalformedMessage, Sharding.Sharding | MessageStorage.MessageStorage>;
+
 /**
  * Re-drive a terminally-`failed` workflow run from the step it died on.
  *
@@ -751,6 +1127,130 @@ export declare interface RedriveTarget {
     readonly failedActivities: ReadonlyArray<FailedActivityRef>;
 }
 
+declare const Request_2: Schema.Struct<{
+    id: typeof Schema.NonEmptyString;
+    runId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+    executionId: typeof Schema.NonEmptyString;
+    generation: typeof Schema.NonEmptyString;
+    token: typeof Schema.NonEmptyString;
+    ledgerId: typeof Schema.NonEmptyString;
+    tenantId: Schema.NullOr<typeof Schema.NonEmptyString>;
+    delivery: Schema.Struct<{
+        requestId: typeof Schema.NonEmptyString;
+        restartToken: Schema.NullOr<typeof Schema.NonEmptyString>;
+    }>;
+    replies: Schema.Array$<Schema.Struct<{
+        requestId: typeof Schema.NonEmptyString;
+        replyId: typeof Schema.NonEmptyString;
+    }>>;
+    selection: Schema.Union<[Schema.Struct<{
+        kind: Schema.Literal<["failed-steps"]>;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["from-step"]>;
+        stepName: Schema.filter<typeof Schema.NonEmptyString>;
+    }>]>;
+    eviction: Schema.NullOr<Schema.Struct<{
+        executionId: typeof Schema.NonEmptyString;
+        runId: typeof Schema.String;
+    }>>;
+    requestedAt: typeof Schema.DateFromSelf;
+    dispatchAttempts: Schema.refine<number, typeof Schema.NonNegative>;
+    enteredGeneration: Schema.NullOr<typeof Schema.NonEmptyString>;
+}>;
+
+/** Private dispatch composition. Capacity is mandatory, outside the resident
+ * transaction; then revalidate the owner and commit its attempt before SQL I/O.
+ * Returns only journal evidence, never body acceptance. The host still owns
+ * engine polling and reconciliation after an ambiguous journal acknowledgement. */
+declare const resetReservedWorkflowJournal: (input: {
+    readonly requestId: string;
+    readonly transaction: <A>(work: (tx: AdmissionDataStore) => Promise<A>) => Promise<A>;
+    readonly acquireCapacity: (request: typeof Request_2.Type) => Promise<boolean>;
+}) => Effect.Effect<{
+    kind: "changed";
+    requestId: string;
+    count?: never;
+} | {
+    kind: "already-reset";
+    count: number;
+    requestId?: never;
+} | {
+    kind: "reset";
+    count: number;
+    requestId?: never;
+} | {
+    kind: "waiting-capacity";
+}, SqlError_2, SqlClient_2>;
+
+/** One resolved `cancelOn` entry. The schema is kept (not pre-compiled into a
+ *  decoder) so the sweeper can report a decode failure naming the event, which
+ *  is the difference between "the predicate said no" and "we could not read the
+ *  event at all". */
+declare interface ResolvedCancelOn {
+    readonly event: string;
+    readonly schema: Schema.Schema.Any;
+    readonly match: (event: unknown, payload: unknown) => boolean;
+    readonly withinMs?: number;
+    readonly reason: string;
+}
+
+/** The declaration with its durations resolved to milliseconds and its
+ *  defaults filled in — what the decision engine actually reads. Key functions
+ *  stay as functions; they are applied against a concrete payload at start. */
+declare interface ResolvedFlowControl {
+    readonly workflowName: string;
+    readonly debounce?: {
+        readonly key: (payload: unknown) => string;
+        readonly periodMs: number;
+        readonly timeoutMs?: number;
+    };
+    readonly singleton?: {
+        readonly key: (payload: unknown) => string;
+        readonly mode: 'skip' | 'cancel';
+    };
+    readonly concurrency?: {
+        readonly limit: number;
+        readonly key?: (payload: unknown) => string;
+        readonly pool?: string;
+    };
+    readonly throttle?: {
+        readonly limit: number;
+        readonly periodMs: number;
+        readonly key?: (payload: unknown) => string;
+    };
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly periodMs: number;
+        readonly key?: (payload: unknown) => string;
+    };
+    readonly batch?: {
+        readonly key?: (payload: unknown) => string;
+        readonly maxSize: number;
+        readonly timeoutMs: number;
+        /**
+         * Schema of ONE item — what a CALLER passes to `start()`, as opposed to the
+         * workflow's own `{ items: [...] }` payload.
+         *
+         * Carried through resolution because the facade validates an arriving start
+         * against it. It used to be declared, asserted at declaration time, and then
+         * dropped here — so every `start()` on a batching workflow was validated
+         * against the batch shape it is not, and threw `WorkflowPayloadError` before
+         * the gate ever saw it. A required option nothing reads is worse than an
+         * absent one: it reads as wired.
+         */
+        readonly item?: unknown;
+    };
+    readonly priority?: (payload: unknown) => number;
+    readonly timeouts?: {
+        readonly startMs?: number;
+        readonly finishMs?: number;
+    };
+    readonly onFailure?: string;
+    readonly encrypted?: boolean;
+    readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
+}
+
 /**
  * Read the failover-tuning knobs from the environment, for the boot paths to
  * spread into {@link workflowEngineLayer}. Operators set:
@@ -894,6 +1394,13 @@ export declare interface RunnerIdentity {
  */
 export declare type RunnerStorage = 'sql' | 'memory';
 
+declare const Selection: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["failed-steps"]>;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["from-step"]>;
+    stepName: Schema.filter<typeof Schema.NonEmptyString>;
+}>]>;
+
 declare interface ShardLockHolder {
     readonly shardId: string;
     readonly mode: 'advisory' | 'row';
@@ -949,7 +1456,7 @@ declare interface UnreadMessage extends ClusterMessageState {
     readonly unreadForMs: number;
 }
 
-export declare const workflowEngineLayer: (options: WorkflowEngineLayerOptions) => Layer.Layer<WorkflowEngine.WorkflowEngine | Sharding.Sharding | MessageStorage.MessageStorage | ClusterDiagnostics | WorkflowResumeDispatcher>;
+export declare const workflowEngineLayer: (options: WorkflowEngineLayerOptions) => Layer.Layer<WorkflowEngine.WorkflowEngine | Sharding.Sharding | MessageStorage.MessageStorage | ClusterDiagnostics | WorkflowResumeDispatcher | WorkflowRestartDispatcher>;
 
 export declare interface WorkflowEngineLayerOptions {
     /**
@@ -978,6 +1485,13 @@ export declare interface WorkflowEngineLayerOptions {
     readonly shardLockMode?: ShardLockMode;
     readonly runnerListenHost?: string;
     readonly runnerListenPort?: number;
+    /**
+     * The declared store charset (`store: { dialect, charset }`, mysql family).
+     * The engine's tables are created by the library with no character set named;
+     * the migration gate converts the ones it creates to this, so a workflow input
+     * with a 4-byte character is not refused on a `utf8mb3` server.
+     */
+    readonly charset?: MysqlCharset | undefined;
     /**
      * FAILOVER TUNING — the two knobs that govern how fast a SURVIVING replica
      * takes over a CRASHED replica's in-flight workflows. Reclaim is a
@@ -1027,6 +1541,27 @@ export declare interface WorkflowEngineLayerOptions {
     readonly extraShardingLayers?: ReadonlyArray<Layer.Layer<never, never, Sharding.Sharding>>;
 }
 
+export declare class WorkflowRestartDispatcher extends WorkflowRestartDispatcher_base {
+}
+
+declare const WorkflowRestartDispatcher_base: Context.TagClass<WorkflowRestartDispatcher, "@voltro/workflow/WorkflowRestartDispatcher", {
+    readonly prepare: (options: Omit<Parameters<typeof prepareWorkflowRestartCommand>[0], "observe">) => Effect.Effect<Awaited<ReturnType<typeof prepareWorkflowRestartCommand>>, unknown>;
+    readonly dispatch: (options: Parameters<typeof dispatchWorkflowRestart>[0]) => Effect.Effect<Effect.Effect.Success<ReturnType<typeof dispatchWorkflowRestart>>, Effect.Effect.Error<ReturnType<typeof dispatchWorkflowRestart>>>;
+    readonly observe: (target: WorkflowRestartObservationTarget) => Effect.Effect<Effect.Effect.Success<ReturnType<typeof observeWorkflowRestartReplies>>, Effect.Effect.Error<ReturnType<typeof observeWorkflowRestartReplies>>>;
+}>;
+
+declare interface WorkflowRestartObservationTarget {
+    readonly workflow: Workflow.Any;
+    readonly executionId: string;
+    readonly delivery: {
+        readonly requestId: string;
+        readonly restartToken: string | null;
+    };
+    readonly activities: ReadonlyArray<FailedActivityRef>;
+}
+
+declare type WorkflowRestartSelection = typeof Selection.Type;
+
 /** Engine-bound dispatch capability. Accepts resident transactions, not a
  * caller-selected SQL connection. Results acknowledge attempts, never entry. */
 export declare class WorkflowResumeDispatcher extends WorkflowResumeDispatcher_base {
@@ -1036,4 +1571,19 @@ declare const WorkflowResumeDispatcher_base: Context.TagClass<WorkflowResumeDisp
     readonly dispatch: (options: Parameters<typeof dispatchWorkflowResume>[0]) => Effect.Effect<Effect.Effect.Success<ReturnType<typeof dispatchWorkflowResume>>, Effect.Effect.Error<ReturnType<typeof dispatchWorkflowResume>>>;
 }>;
 
+/** Raw engine evidence, before workflow-result decoding. Server-only consumers
+ * must authorize access and project this reply before exposing it to a client.
+ * A reply does not by itself establish recorder entry or successful execution. */
+export declare type WorkflowRunReplyObservation = {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'pending';
+    readonly requestId: string;
+} | {
+    readonly kind: 'reply';
+    readonly requestId: string;
+    readonly replyId: string;
+    readonly exit: unknown;
+};
+
 export { }