@shipfox/api-workflows 2.0.0

package/src/core/step-transition/decide-step-transition.test.ts

@@ -0,0 +1,307 @@
+import type {Step} from '../entities/step.js';
+import {decideStepTransition, deriveCompletion, isTerminal} from './decide-step-transition.js';
+
+function step(overrides: Partial<Step> & {id: string; position: number}): Step {
+  return {
+    jobExecutionId: 'execution-1',
+    key: null,
+    name: 'step',
+    sourceLocation: null,
+    status: 'pending',
+    statusReason: null,
+    evaluationTrace: null,
+    type: 'run',
+    config: {},
+    condition: null,
+    configPlan: null,
+    authoredConfig: null,
+    error: null,
+    version: 1,
+    currentAttempt: 1,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('decideStepTransition', () => {
+  test('a succeeded step with pending siblings advances the step', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+    const steps = [target, step({id: 's1', position: 1, status: 'pending'})];
+
+    const decision = decideStepTransition({
+      steps,
+      target,
+      reportedAttempt: 1,
+      result: {status: 'succeeded'},
+    });
+
+    expect(decision).toEqual({kind: 'complete-step', stepId: 's0', attempt: 1});
+  });
+
+  test('a succeeded step completes the job when every other step is terminal', () => {
+    const target = step({id: 's1', position: 1, status: 'running'});
+    const steps = [step({id: 's0', position: 0, status: 'succeeded'}), target];
+
+    const decision = decideStepTransition({
+      steps,
+      target,
+      reportedAttempt: 1,
+      result: {status: 'succeeded'},
+    });
+
+    expect(decision).toEqual({kind: 'complete-job', stepId: 's1', attempt: 1});
+  });
+
+  test('a single succeeded step completes the job', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'succeeded'},
+    });
+
+    expect(decision).toEqual({kind: 'complete-job', stepId: 's0', attempt: 1});
+  });
+
+  test('a failed step marks the job as failed', () => {
+    const target = step({id: 's1', position: 1, status: 'running'});
+    const steps = [
+      step({id: 's0', position: 0, status: 'succeeded'}),
+      target,
+      step({id: 's2', position: 2, status: 'pending'}),
+    ];
+
+    const decision = decideStepTransition({
+      steps,
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', error: {message: 'boom'}},
+    });
+
+    expect(decision).toEqual({
+      kind: 'fail-job',
+      failedStepId: 's1',
+      attempt: 1,
+      failureError: {message: 'boom'},
+    });
+  });
+
+  test('a passing gate succeeds the step even when the raw status is failed', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+    const steps = [target, step({id: 's1', position: 1, status: 'pending'})];
+
+    const decision = decideStepTransition({
+      steps,
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1, error: {message: 'exit 1'}},
+      gateOutcome: {kind: 'passed', source: 'exit_code == 1'},
+    });
+
+    expect(decision).toEqual({kind: 'complete-step', stepId: 's0', attempt: 1});
+  });
+
+  test('a failing gate without on_failure fails the job with a gate_failed error', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 0'},
+    });
+
+    expect(decision).toMatchObject({
+      kind: 'fail-job',
+      failedStepId: 's0',
+      failureError: {kind: 'gate_failed', source: 'exit_code == 0'},
+    });
+  });
+
+  test('a failing gate with restart_from rewinds from the named earlier step', () => {
+    const restartTarget = step({id: 's0', key: 'producer', position: 0, status: 'succeeded'});
+    const target = step({id: 's1', position: 1, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [restartTarget, target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 0'},
+      gateOnFailure: {restartFrom: 'producer'},
+    });
+
+    expect(decision).toMatchObject({
+      kind: 'restart-job-from-step',
+      failedStepId: 's1',
+      restartFromStepId: 's0',
+      restartFromPosition: 0,
+      attempt: 1,
+    });
+  });
+
+  test('restart_from never resolves to the synthetic setup step (no workspace re-delete)', () => {
+    // A user step legitimately keyed "Set up job" shares its label with the synthetic
+    // setup step at position 0. Restart must resolve to the user step, not position 0.
+    const setup = step({
+      id: 'setup',
+      name: 'Set up job',
+      type: 'setup',
+      position: 0,
+      status: 'succeeded',
+    });
+    const userSetup = step({
+      id: 's1',
+      key: 'Set up job',
+      name: 'Set up job',
+      position: 1,
+      status: 'succeeded',
+    });
+    const target = step({id: 's2', position: 2, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [setup, userSetup, target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 0'},
+      gateOnFailure: {restartFrom: 'Set up job'},
+    });
+
+    expect(decision).toMatchObject({
+      kind: 'restart-job-from-step',
+      restartFromStepId: 's1',
+      restartFromPosition: 1,
+    });
+  });
+
+  test('restart is refused (exhausted) once the gating step hits the attempt cap', () => {
+    const restartTarget = step({id: 's0', key: 'producer', position: 0, status: 'succeeded'});
+    const target = step({id: 's1', position: 1, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [restartTarget, target],
+      target,
+      reportedAttempt: 3,
+      maxAttempts: 3,
+      result: {status: 'failed', exitCode: 1},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 0'},
+      gateOnFailure: {restartFrom: 'producer'},
+    });
+
+    expect(decision).toMatchObject({
+      kind: 'fail-job-restart-exhausted',
+      maxAttempts: 3,
+      failureError: {kind: 'restart_exhausted'},
+    });
+  });
+
+  test('restart_from that resolves to no earlier named step fails closed (unresolved)', () => {
+    const target = step({id: 's1', position: 1, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [step({id: 's0', position: 0, status: 'succeeded'}), target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 0'},
+      gateOnFailure: {restartFrom: 'does-not-exist'},
+    });
+
+    expect(decision).toMatchObject({
+      kind: 'fail-job',
+      failureError: {kind: 'restart_unresolved', restart_from: 'does-not-exist'},
+    });
+  });
+
+  test('an uncheckable gate (no exit code) is a plain command failure, not a restart', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: null, error: {message: 'killed'}},
+      gateOutcome: {kind: 'uncheckable', reason: 'no exit code'},
+      gateOnFailure: {restartFrom: 's0'},
+    });
+
+    expect(decision).toMatchObject({kind: 'fail-job', failureError: {message: 'killed'}});
+  });
+
+  test('echoes the reported attempt in the decision', () => {
+    const target = step({id: 's0', position: 0, status: 'running', currentAttempt: 2});
+    const steps = [target, step({id: 's1', position: 1, status: 'pending'})];
+
+    const decision = decideStepTransition({
+      steps,
+      target,
+      reportedAttempt: 2,
+      result: {status: 'succeeded'},
+    });
+
+    expect(decision).toMatchObject({kind: 'complete-step', attempt: 2});
+  });
+
+  test('a failing gate overrides a raw succeeded status (downward override)', () => {
+    const target = step({id: 's0', position: 0, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'succeeded', exitCode: 0},
+      gateOutcome: {kind: 'failed', source: 'exit_code == 1'},
+    });
+
+    expect(decision).toMatchObject({kind: 'fail-job', failureError: {kind: 'gate_failed'}});
+  });
+
+  test('a raw failure with on_failure but no success still restarts', () => {
+    const restartTarget = step({id: 's0', key: 'producer', position: 0, status: 'succeeded'});
+    const target = step({id: 's1', position: 1, status: 'running'});
+
+    const decision = decideStepTransition({
+      steps: [restartTarget, target],
+      target,
+      reportedAttempt: 1,
+      result: {status: 'failed', exitCode: 1},
+      // No gateOutcome (no success) but a restart policy is configured.
+      gateOnFailure: {restartFrom: 'producer'},
+    });
+
+    expect(decision).toMatchObject({kind: 'restart-job-from-step', restartFromStepId: 's0'});
+  });
+});
+
+describe('deriveCompletion / isTerminal', () => {
+  test('isTerminal covers the terminal states', () => {
+    expect(isTerminal('succeeded')).toBe(true);
+    expect(isTerminal('failed')).toBe(true);
+    expect(isTerminal('cancelled')).toBe(true);
+    expect(isTerminal('skipped')).toBe(true);
+    expect(isTerminal('running')).toBe(false);
+    expect(isTerminal('pending')).toBe(false);
+  });
+
+  test('deriveCompletion fails only when a step failed', () => {
+    expect(deriveCompletion([step({id: 'a', position: 0, status: 'succeeded'})])).toBe('succeeded');
+    expect(
+      deriveCompletion([
+        step({id: 'a', position: 0, status: 'succeeded'}),
+        step({id: 'b', position: 1, status: 'skipped'}),
+      ]),
+    ).toBe('succeeded');
+    expect(deriveCompletion([step({id: 'a', position: 0, status: 'skipped'})])).toBe('succeeded');
+    expect(
+      deriveCompletion([
+        step({id: 'a', position: 0, status: 'skipped'}),
+        step({id: 'b', position: 1, status: 'failed'}),
+      ]),
+    ).toBe('failed');
+  });
+});

package/src/core/step-transition/decide-step-transition.ts

@@ -0,0 +1,200 @@
+import type {PersistedEvaluationTraceEntry, Step, StepStatus} from '../entities/step.js';
+
+const TERMINAL_STATUSES: ReadonlySet<StepStatus> = new Set([
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+]);
+
+export function isTerminal(status: StepStatus): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
+export function deriveCompletion(steps: Step[]): 'succeeded' | 'failed' {
+  return steps.some((step) => step.status === 'failed') ? 'failed' : 'succeeded';
+}
+
+// The report the runner sent for the step being decided.
+export interface StepReport {
+  status: 'succeeded' | 'failed';
+  exitCode?: number | null;
+  error?: Record<string, unknown> | null;
+  output?: Record<string, unknown> | null;
+  response?: string | null;
+}
+
+// Precomputed gate evaluation (the CEL engine runs in evaluate-gate.ts, never
+// here). `passed`/`failed` are clean evaluations; `uncheckable` means the gate
+// could not be evaluated (no exit code, or an evaluation error) and is treated
+// as a plain command failure — never a restart.
+export type GateOutcome =
+  | {kind: 'no-gate'}
+  | {kind: 'passed'; source: string; trace?: readonly PersistedEvaluationTraceEntry[]}
+  | {kind: 'failed'; source: string; trace?: readonly PersistedEvaluationTraceEntry[]}
+  | {
+      kind: 'uncheckable';
+      reason: string;
+      source?: string;
+      trace?: readonly PersistedEvaluationTraceEntry[];
+    };
+
+export interface DecideStepTransitionInput {
+  // Full job projection, position-ordered (as returned by getStepsByJobIdForUpdate).
+  steps: Step[];
+  // The reporting step, already confirmed running at `reportedAttempt`.
+  target: Step;
+  reportedAttempt: number;
+  result: StepReport;
+  // Precomputed gate evaluation. Absent ⇒ no gate, so `result.status` is authoritative.
+  gateOutcome?: GateOutcome;
+  // The gate's on_failure policy, if any. Drives the restart branch.
+  gateOnFailure?: {restartFrom: string; feedback?: string};
+  restartFeedback?: string;
+  // Max total attempts for the gating step before restart is exhausted; defaults
+  // to DEFAULT_RESTART_ATTEMPT_CAP.
+  maxAttempts?: number;
+  // The gating step's own execution count (number of its attempts), used for the
+  // cap. Defaults to `reportedAttempt` — correct for a single-gate job, where the
+  // two are equal; the service passes the real count so a downstream gate in a
+  // multi-gate job isn't penalized for upstream-induced rewinds.
+  gatingAttemptCount?: number;
+}
+
+// Per-step restart cap: the gating step may run at most this many attempts before
+// a further restart is refused. Bounds runaway restart loops.
+export const DEFAULT_RESTART_ATTEMPT_CAP = 3;
+
+// The semantic outcome of a step report, independent of persistence.
+export type StepTransitionDecision =
+  | {kind: 'complete-step'; stepId: string; attempt: number}
+  // The step succeeds and is the last to finish; apply re-derives the job's
+  // terminal status from the projection (it may be `failed` if a sibling was
+  // cancelled), so the status is not carried on the decision.
+  | {kind: 'complete-job'; stepId: string; attempt: number}
+  | {
+      kind: 'fail-job';
+      failedStepId: string;
+      attempt: number;
+      // The error to record on the step/attempt (the reported error, or a
+      // structured gate error).
+      failureError: Record<string, unknown> | null;
+    }
+  | {
+      kind: 'restart-job-from-step';
+      failedStepId: string;
+      restartFromStepId: string;
+      restartFromPosition: number;
+      attempt: number;
+      feedback: string;
+      // Recorded on the failed attempt before the rewind clears the projection.
+      failureError: Record<string, unknown> | null;
+    }
+  | {
+      kind: 'fail-job-restart-exhausted';
+      failedStepId: string;
+      attempt: number;
+      maxAttempts: number;
+      failureError: Record<string, unknown> | null;
+    };
+
+function succeed(target: Step, attempt: number, steps: Step[]): StepTransitionDecision {
+  // Completes the job when every other step is already terminal, otherwise just
+  // advances this step.
+  const everyOtherTerminal = steps
+    .filter((step) => step.id !== target.id)
+    .every((step) => isTerminal(step.status));
+  return everyOtherTerminal
+    ? {kind: 'complete-job', stepId: target.id, attempt}
+    : {kind: 'complete-step', stepId: target.id, attempt};
+}
+
+function fail(
+  target: Step,
+  attempt: number,
+  failureError: Record<string, unknown> | null,
+): StepTransitionDecision {
+  return {
+    kind: 'fail-job',
+    failedStepId: target.id,
+    attempt,
+    failureError,
+  };
+}
+
+// Pure: maps a step report (and its precomputed gate outcome) to a transition
+// decision. No DB, no expression engine. A passing gate succeeds; a checkable
+// failure with a resolvable `restart_from` rewinds (until the per-step attempt cap
+// is hit); everything else fails the job. An `uncheckable` failure (no exit code /
+// eval error) is always a plain failure, never a restart.
+export function decideStepTransition(input: DecideStepTransitionInput): StepTransitionDecision {
+  const {steps, target, reportedAttempt, result, gateOnFailure} = input;
+  const gate = input.gateOutcome ?? {kind: 'no-gate'};
+  const maxAttempts = input.maxAttempts ?? DEFAULT_RESTART_ATTEMPT_CAP;
+
+  // 1. Did the step pass? The gate (when present and checkable) is authoritative
+  //    over the raw command status.
+  if (gate.kind === 'no-gate' ? result.status === 'succeeded' : gate.kind === 'passed') {
+    return succeed(target, reportedAttempt, steps);
+  }
+
+  // 2. It failed. Classify the failure error and whether it is restartable.
+  //    `uncheckable` (no exit code / eval error) is a plain command failure that
+  //    never restarts.
+  const uncheckable = gate.kind === 'uncheckable';
+  const failureError: Record<string, unknown> | null =
+    gate.kind === 'failed'
+      ? {kind: 'gate_failed', message: 'gate condition not met', source: gate.source}
+      : gate.kind === 'uncheckable'
+        ? (result.error ?? {kind: 'gate_uncheckable', message: gate.reason})
+        : (result.error ?? null);
+
+  // 3. Restart when a policy is configured and the failure is checkable.
+  if (gateOnFailure?.restartFrom && !uncheckable) {
+    // Exclude the synthetic setup step: a user step legitimately named "Set up job"
+    // would otherwise resolve to position 0 and rewind setup (deleting the workspace
+    // mid-job). Duplicate user-step names are already impossible (normalize rejects
+    // them with duplicate-step-id), so this is the only collision to guard.
+    const restartStep = steps.find(
+      (step) =>
+        step.type !== 'setup' &&
+        step.position < target.position &&
+        step.key === gateOnFailure.restartFrom,
+    );
+    if (!restartStep) {
+      // The model validates restart_from to an earlier named step, but fail closed
+      // if it can't be resolved at runtime rather than silently restarting wrong.
+      return fail(target, reportedAttempt, {
+        kind: 'restart_unresolved',
+        message: `could not resolve restart_from "${gateOnFailure.restartFrom}"`,
+        restart_from: gateOnFailure.restartFrom,
+      });
+    }
+    const gatingAttemptCount = input.gatingAttemptCount ?? reportedAttempt;
+    if (gatingAttemptCount >= maxAttempts) {
+      return {
+        kind: 'fail-job-restart-exhausted',
+        failedStepId: target.id,
+        attempt: reportedAttempt,
+        maxAttempts,
+        failureError: {
+          kind: 'restart_exhausted',
+          maxAttempts,
+          restart_from: gateOnFailure.restartFrom,
+        },
+      };
+    }
+    return {
+      kind: 'restart-job-from-step',
+      failedStepId: target.id,
+      restartFromStepId: restartStep.id,
+      restartFromPosition: restartStep.position,
+      attempt: reportedAttempt,
+      feedback: input.restartFeedback ?? gateOnFailure.feedback ?? 'gate condition not met',
+      failureError,
+    };
+  }
+
+  // 4. No restart → plain fail-and-cancel.
+  return fail(target, reportedAttempt, failureError);
+}