@kb-labs/workflow-engine 2.118.2 → 2.119.0-canary.2077501f1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { WorkflowSpec, RunTrigger, IdempotencyKey, ConcurrencyGroup, WorkflowRun, JobRun, StepRun, RetryPolicy, ArtifactMergeConfig } from '@kb-labs/workflow-contracts';
 import { ILogger, ICache, IEventBus, IAnalytics, ISnapshotManager, Unsubscribe, IJobScheduler, JobDefinition, JobHandle, CronExpression, JobFilter } from '@kb-labs/core-platform';
-import { JobPriority, WorkflowEventName } from '@kb-labs/workflow-constants';
+import { AssertTransitionOptions, JobPriority, WorkflowEventName } from '@kb-labs/workflow-constants';
 import { ClassifiedFailure, IExecutionBackend } from '@kb-labs/core-contracts';
 import { ArtifactClient } from '@kb-labs/workflow-artifacts';
 import { IEntityRegistry } from '@kb-labs/core-registry';
@@ -51,9 +51,34 @@ declare class StateStore {
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
     getAllRunIds(): Promise<string[]>;
+    /**
+     * Holds an exclusive per-run lock (see `withLock`) for the whole
+     * read-modify-write, so `mutator` runs exactly once per call — no other
+     * writer can observe or clobber the run in between. This is what actually
+     * fixes the original bug class (a job marked `failed` while its step was
+     * mid-write to `waiting_approval`): the two writes can no longer interleave.
+     *
+     * `mutator` must still not `await` — it runs synchronously against a
+     * single in-memory draft while the lock is held; async work belongs after
+     * `updateRun` resolves (and holding the lock across an `await` would just
+     * make every other writer to this run block on it needlessly).
+     */
     updateRun(runId: string, mutator: (draft: WorkflowRun) => WorkflowRun | void): Promise<WorkflowRun | null>;
     updateJob(runId: string, jobId: string, mutator: (job: JobRun) => JobRun | void): Promise<JobRun | null>;
     updateStep(runId: string, jobId: string, stepId: string, mutator: (step: StepRun) => StepRun | void): Promise<StepRun | null>;
+    /**
+     * Like `updateRun`, but validates the status transition against the
+     * workflow state machine before applying it — throws
+     * `IllegalStateTransitionError` (from `@kb-labs/workflow-constants`) if
+     * `to` is not reachable from the run's current status. `mutate` sets any
+     * *other* fields; it must not itself assign `.status` (this method owns
+     * that assignment, after the check).
+     */
+    transitionRun(runId: string, to: WorkflowRun['status'], mutate?: (draft: WorkflowRun) => void, options?: AssertTransitionOptions): Promise<WorkflowRun | null>;
+    /** Job-level counterpart of `transitionRun` — see its docblock. */
+    transitionJob(runId: string, jobId: string, to: JobRun['status'], mutate?: (draft: JobRun) => void, options?: AssertTransitionOptions): Promise<JobRun | null>;
+    /** Step-level counterpart of `transitionRun` — see its docblock. */
+    transitionStep(runId: string, jobId: string, stepId: string, to: StepRun['status'], mutate?: (draft: StepRun) => void, options?: AssertTransitionOptions): Promise<StepRun | null>;
     releaseBlockedJobs(runId: string, completedJobName: string): Promise<JobRun[]>;
 }
 
@@ -111,6 +136,16 @@ declare class Scheduler {
     enqueueJob(runId: string, job: JobRun, priority?: JobPriority): Promise<void>;
     dequeueJob(): Promise<JobQueueEntry | null>;
     reschedule(entry: JobQueueEntry, delayMs: number): Promise<void>;
+    /**
+     * The read (`zrangebyscore`) and the remove (`zrem`) below are two
+     * separate cache round-trips, not one atomic op — without the lock, two
+     * daemon instances racing this method could both read the same top entry
+     * before either removes it, and both would go on to execute the same job
+     * (the daemon runs multiple instances in production, so this is a live
+     * bug, not a theoretical one). `withLock` serializes dequeues against this
+     * one priority queue across every process sharing the same cache backend,
+     * the same way `StateStore.updateRun` serializes writes to one run.
+     */
     private dequeueFromPriority;
     getDefaultPriority(): JobPriority;
 }
@@ -293,10 +328,26 @@ declare class WorkflowEngine {
     /**
      * Mark step as waiting for human approval.
      */
+    /**
+     * Park a step waiting for human approval — and park its parent job with
+     * it, in the SAME atomic write (one `transitionJob` call touching both the
+     * job's own status and its nested step). Two separate writes (step then
+     * job) would leave a window where a reader could observe step=waiting but
+     * job=running; going through one call closes that window entirely, not
+     * just narrows it.
+     *
+     * The job-level `waiting_approval` status is what makes the daemon-restart
+     * exemption in `cleanupStaleRuns` structural: that force-fail loop only
+     * ever touches `running`/`queued` jobs, so a parked job is never in its
+     * blast radius — no bespoke "is this job actually abandoned or just
+     * waiting on a human" check needed there.
+     */
     markStepWaitingApproval(runId: string, jobId: string, stepId: string): Promise<void>;
     /**
-     * Park a step while its child workflow runs. The worker returns after this
-     * transition, so parent workflows never consume the pool needed by children.
+     * Park a step (and its parent job — see `markStepWaitingApproval`'s
+     * docblock for why job+step move together in one write) while its child
+     * workflow runs. The worker returns after this transition, so parent
+     * workflows never consume the pool needed by children.
      */
     markStepWaitingChild(runId: string, jobId: string, stepId: string, childRunId: string): Promise<void>;
     /** Re-queue a parked parent job after its child workflow reaches a terminal state. */
@@ -305,6 +356,12 @@ declare class WorkflowEngine {
      * Resolve a pending approval — approve or reject.
      * On approve: marks step as success with approval outputs.
      * On reject: marks step as failed with rejection error.
+     *
+     * Resolves the step AND un-parks the job (`waiting_approval` → `queued`)
+     * in one atomic write — same reasoning as `markStepWaitingApproval` — then
+     * re-enqueues the job. This re-enqueue is what actually resumes execution:
+     * with approval no longer polled in-process (the worker parks and returns
+     * instead of waiting), nothing else will ever pick this job back up.
      */
     resolveApproval(runId: string, jobId: string, stepId: string, action: 'approve' | 'reject', data?: Record<string, unknown>, comment?: string): Promise<void>;
     /**
@@ -316,9 +373,12 @@ declare class WorkflowEngine {
      */
     getScheduler(): Scheduler;
     /**
-     * Mark stale running/queued runs as failed on daemon startup.
-     * Runs that were in-flight when the daemon crashed are unrecoverable —
-     * their executor process is gone, so we mark them failed immediately.
+     * Mark stale running/queued jobs as failed on daemon startup — their
+     * executor process is gone, so they're unrecoverable. The run itself is
+     * only finalized as 'failed' if nothing else could still complete it;
+     * a run with one abandoned job and one job legitimately parked on a human
+     * approval or a child workflow stays 'running' (only the abandoned job is
+     * failed) until the parked one resolves.
      */
     cleanupStaleRuns(): Promise<void>;
     /**