@voltro/workflow 0.69.1 → 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;
@@ -54,6 +301,25 @@ declare interface ClusterDiagnosticsOps {
     readonly shardLockHolders: (shardIds: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<ShardLockHolder>>;
     /** The runner table — every address that registered, with its heartbeat. */
     readonly runners: () => Effect.Effect<ReadonlyArray<ClusterRunner>>;
+    /**
+     * Delete the unprocessed messages addressed to one entity — the ONE write on
+     * this service. A run that ended outside the engine (cancelled by a sweep or
+     * an operator, parked as failed) leaves its unanswered requests behind: the
+     * `activity` a killed executor never replied to, the `run` itself if it was
+     * never processed. Every runner that acquires the shard re-reads them for the
+     * re-read window, forever, and an `activity` request for a run that does not
+     * execute waits on a latch that never opens. Nothing consumes them; deleting
+     * is what the engine's own reset does for one request. Returns how many.
+     *
+     * `unreadForMs`: only messages a runner last read at least this long ago —
+     * the guard for the sweep, which must not take a request an operator's
+     * redrive cleared a moment ago and a runner has just re-read.
+     */
+    readonly discardMessages: (input: {
+        readonly entityType: string;
+        readonly entityId: string;
+        readonly unreadForMs?: number;
+    }) => Effect.Effect<number>;
 }
 
 export declare interface ClusterDiagnosticsOptions {
@@ -63,6 +329,14 @@ export declare interface ClusterDiagnosticsOptions {
     readonly dialectId?: string | undefined;
     /** Shard groups in configured order — the advisory lock base per group. */
     readonly shardGroups?: ReadonlyArray<string>;
+    /**
+     * Does THIS runner hold the shard — `Sharding.hasShardId`, the engine's own
+     * account. This is what `own` on a holder means; without it every holder is
+     * a stranger. Not read from the database on purpose: the lock session's pid
+     * is not the pid of any query this service can make, and behind a pooler
+     * every session shares one client address and one application name.
+     */
+    readonly hasShard?: (shardId: string) => boolean;
 }
 
 declare interface ClusterMessageState {
@@ -81,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;
 
@@ -92,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;
@@ -144,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'
@@ -162,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). */
@@ -327,7 +900,14 @@ declare interface ShardLockHolder {
     /** Who holds it: `pid <n> from <client>` for a postgres advisory lock, the
      *  runner address for a row lease. */
     readonly holder: string;
-    /** `true` when the holder is THIS runner's own lock session/address. */
+    /**
+     * `true` when THIS runner holds the shard — the engine's own answer
+     * (`Sharding.hasShardId`), never a guess from a connection. The first
+     * version compared the holder's pid with `pg_backend_pid()` of the query
+     * that asked, and the pool hands every query a different backend than the
+     * lock session, so a runner's own 300 locks read as a stranger's — and the
+     * report's lever, ending the holder's session, would have ended the runner.
+     */
     readonly own: boolean;
     readonly since: Date | null;
     readonly detail?: Record<string, unknown>;
@@ -362,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 {
     /**
@@ -445,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 { }