@voltro/workflow 0.70.0 → 0.71.0

package/dist/cluster.d.ts

@@ -1,6 +1,7 @@
 import { ConfigError } from 'effect';
 import { Context } from 'effect';
 import { Cron } from 'effect';
+import { DataStore } from '@voltro/database';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
@@ -8,6 +9,7 @@ import { MessageStorage } from '@effect/cluster';
 import { Sharding } from '@effect/cluster';
 import { SqlClient } from '@effect/sql';
 import { SqlError } from '@effect/sql';
+import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Workflow } from '@effect/workflow';
 import { WorkflowEngine } from '@effect/workflow';
 
@@ -20,6 +22,251 @@ import { WorkflowEngine } from '@effect/workflow';
  */
 export declare const activityPrimaryKey: (activityName: string, attempt: number) => string;
 
+/** 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
+ * dispatch uses this immutable observation, including after a lost ACK. */
+declare const bindWorkflowResumeJournalInTransaction: (tx: Store, id: string, observe: (target: {
+    readonly workflowName: string;
+    readonly executionId: string;
+    readonly requestId: string;
+    readonly restartToken: string | null;
+}) => Promise<unknown>) => Promise<{
+    kind: "settled";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "unknown";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "superseded";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "not-suspended";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "bound";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "waiting-journal";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+}>;
+
 export declare interface ClusterCronSpec {
     /** Stable schedule name — used as the cluster cron's identity. */
     readonly name: string;
@@ -108,6 +355,8 @@ declare interface ClusterRunner {
     readonly healthy: boolean;
 }
 
+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;
 
@@ -119,6 +368,301 @@ 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 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. */
+declare const dispatchWorkflowResume: (options: {
+    readonly requestId: string;
+    readonly transaction: <A>(work: (tx: ControlStore) => Promise<A>) => Promise<A>;
+}) => Effect.Effect<{
+    kind: "settled";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "unknown";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "superseded";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "not-suspended";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "waiting-journal";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+} | {
+    kind: "already-terminal";
+    request: {
+        readonly id: string;
+        readonly cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        readonly result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        readonly requestedAt: number;
+        readonly executionId: string;
+        readonly runId: string;
+        readonly workflowName: string;
+        readonly operation: "resume" | "cancel" | "terminate";
+        readonly generation: string;
+        readonly owner: {
+            readonly tenantId: string | null;
+        } | null;
+        readonly resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+        readonly dispatchAttempts: number;
+    };
+    run: Readonly<Record<string, unknown>>;
+} | {
+    kind: "attempted";
+    request: {
+        dispatchAttempts: number;
+        id: string;
+        cause?: {
+            readonly detail?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+            readonly reason: string;
+        } | null | undefined;
+        result: {
+            readonly status: "failed" | "cancelled" | "succeeded";
+            readonly kind: "confirmed" | "already-terminal";
+            readonly errorMessage: string | null;
+            readonly output: unknown;
+            readonly errorTag: string | null;
+            readonly completedAt: number;
+        } | {
+            readonly status: "running";
+            readonly kind: "confirmed";
+            readonly generation: string;
+            readonly enteredAt: number;
+        } | null;
+        requestedAt: number;
+        executionId: string;
+        runId: string;
+        workflowName: string;
+        operation: "resume" | "cancel" | "terminate";
+        generation: string;
+        owner: {
+            readonly tenantId: string | null;
+        } | null;
+        resumeJournal: {
+            readonly requestId: string;
+            readonly replyId: string;
+            readonly restartToken: string | null;
+        } | null;
+    };
+    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>;
+
 /** A step attempt to reset so it re-executes on the next drive. */
 export declare interface FailedActivityRef {
     readonly name: string;
@@ -171,16 +715,18 @@ export declare const redriveFailedRun: (target: RedriveTarget) => Effect.Effect<
 export declare interface RedriveOutcome {
     /** True iff the `run` reply was cleared and storage re-polled. */
     readonly redriven: boolean;
-    /** True iff the terminal `run` reply was cleared. */
+    /** True when clearing the terminal run reply was confirmed. False does not
+     * prove no write occurred when reason is run-reset-unconfirmed. */
     readonly runReplyCleared: boolean;
     /** How many failed activity replies were cleared (so they re-execute). */
     readonly activitiesReset: number;
     /** Set when `redriven` is false. */
-    readonly reason: RedriveSkipReason | null;
+    readonly reason: RedriveReason | null;
 }
 
-/** Why a re-drive did nothing — surfaced so the caller reports honestly. */
-export declare type RedriveSkipReason = 
+/** Why a replay was not confirmed. Reset failures can follow partial changes;
+ * they are not proof that the journal was left untouched. */
+export declare type RedriveReason = 
 /** No `run` request found in the cluster journal — a memory engine, or
 *  a run that was never durably journaled. Nothing to re-drive. */
 'no-journal'
@@ -189,7 +735,7 @@ export declare type RedriveSkipReason =
 | 'no-reply'
 /** The stored reply is a SUCCESS — the run completed cleanly. Nothing
 *  to re-drive; refuse rather than resurrect a finished run. */
-| 'succeeded';
+| 'succeeded' | 'suspended' | 'unrecognized-reply' | 'activity-not-found' | 'activity-reset-unconfirmed' | 'run-reset-unconfirmed';
 
 export declare interface RedriveTarget {
     /** The workflow definition — for its `name` (entity type) + `annotations` (shard group). */
@@ -396,12 +942,14 @@ declare interface ShardLockHolder {
  */
 export declare type ShardLockMode = 'auto' | 'row' | 'advisory';
 
+declare type Store = Pick<DataStore, 'query' | 'insert' | 'update'>;
+
 declare interface UnreadMessage extends ClusterMessageState {
     /** How long ago the last runner read it. */
     readonly unreadForMs: number;
 }
 
-export declare const workflowEngineLayer: (options: WorkflowEngineLayerOptions) => Layer.Layer<WorkflowEngine.WorkflowEngine | Sharding.Sharding | MessageStorage.MessageStorage | ClusterDiagnostics>;
+export declare const workflowEngineLayer: (options: WorkflowEngineLayerOptions) => Layer.Layer<WorkflowEngine.WorkflowEngine | Sharding.Sharding | MessageStorage.MessageStorage | ClusterDiagnostics | WorkflowResumeDispatcher>;
 
 export declare interface WorkflowEngineLayerOptions {
     /**
@@ -479,4 +1027,13 @@ export declare interface WorkflowEngineLayerOptions {
     readonly extraShardingLayers?: ReadonlyArray<Layer.Layer<never, never, Sharding.Sharding>>;
 }
 
+/** 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 {
+}
+
+declare const WorkflowResumeDispatcher_base: Context.TagClass<WorkflowResumeDispatcher, "@voltro/workflow/WorkflowResumeDispatcher", {
+    readonly dispatch: (options: Parameters<typeof dispatchWorkflowResume>[0]) => Effect.Effect<Effect.Effect.Success<ReturnType<typeof dispatchWorkflowResume>>, Effect.Effect.Error<ReturnType<typeof dispatchWorkflowResume>>>;
+}>;
+
 export { }

package/dist/cluster.js

@@ -1,2 +1,2 @@
-import { a as e, c as t, d as n, f as r, i, l as a, m as o, n as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cluster-CSycI4sz.js";
-export { e as DEFAULT_RUNNER_LISTEN_PORT, f as activityPrimaryKey, c as detectWsrepCluster, i as makeClusterCronLayer, o as makeClusterDiagnostics, d as parseShardLockMode, t as pollWorkflowStorage, s as redriveFailedRun, a as resolveFailoverTuning, p as resolveRunnerIdentity, n as resolveRunnerStorage, r as resolveShardLockDisableAdvisory, u as resumeRunFromStep, l as workflowEngineLayer };
+import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, n as c, o as l, p as u, r as d, s as f, t as p, u as m } from "./cluster-BRSoL1tb.js";
+export { e as DEFAULT_RUNNER_LISTEN_PORT, i as WorkflowResumeDispatcher, p as activityPrimaryKey, l as detectWsrepCluster, a as makeClusterCronLayer, s as makeClusterDiagnostics, f as parseShardLockMode, t as pollWorkflowStorage, c as redriveFailedRun, o as resolveFailoverTuning, m as resolveRunnerIdentity, n as resolveRunnerStorage, r as resolveShardLockDisableAdvisory, d as resumeRunFromStep, u as workflowEngineLayer };