@shipfox/api-workflows 2.0.0

package/dist/core/step-transition/apply-step-transition.js

@@ -0,0 +1,141 @@
+import { applyStepResult, finishStepAttempt, getStepsByJobExecutionIdForUpdate, rewindStepsToPending, settleJobFailed, writeJobStepsSettledOutbox, writeStepRestartEnqueuedOutbox } from '#db/workflow-runs.js';
+import { deriveCompletion, isTerminal } from './decide-step-transition.js';
+// Durable side of the decision: writes the attempt + projection for a transition,
+// then derives job completion from the post-apply projection and enqueues the
+// completion event in the same transaction. Only called for a running target, so
+// every path here is an actual state change (idempotent no-ops are handled by the
+// caller before deciding).
+export async function applyStepTransition(decision, ctx, tx) {
+    switch(decision.kind){
+        case 'complete-step':
+        case 'complete-job':
+            {
+                // A passing gate makes a step succeed even if the raw command status was
+                // 'failed', so the projection error is cleared regardless of the report.
+                await finishStepAttempt({
+                    stepId: decision.stepId,
+                    attempt: decision.attempt,
+                    status: 'succeeded',
+                    output: ctx.result.output ?? null,
+                    response: ctx.result.response ?? null,
+                    exitCode: ctx.result.exitCode ?? null,
+                    logOutcome: ctx.logOutcome,
+                    gateResult: ctx.gateResult ?? null
+                }, tx);
+                await applyStepResult({
+                    jobExecutionId: ctx.jobExecutionId,
+                    stepId: decision.stepId,
+                    status: 'succeeded',
+                    error: null
+                }, tx);
+                break;
+            }
+        case 'fail-job':
+        case 'fail-job-restart-exhausted':
+            {
+                await finishStepAttempt({
+                    stepId: decision.failedStepId,
+                    attempt: decision.attempt,
+                    status: 'failed',
+                    output: ctx.result.output ?? null,
+                    response: ctx.result.response ?? null,
+                    error: decision.failureError,
+                    exitCode: ctx.result.exitCode ?? null,
+                    logOutcome: ctx.logOutcome,
+                    gateResult: ctx.gateResult ?? null
+                }, tx);
+                const status = await settleJobFailed(tx, {
+                    jobId: ctx.jobId,
+                    jobExecutionId: ctx.jobExecutionId,
+                    failedStepId: decision.failedStepId,
+                    error: decision.failureError ?? {
+                        message: 'Step failed'
+                    }
+                });
+                if (status !== null) {
+                    return {
+                        outcome: {
+                            jobFinished: true,
+                            status
+                        },
+                        metrics: {
+                            jobStepsSettledStatus: status
+                        }
+                    };
+                }
+                return {
+                    outcome: {
+                        jobFinished: false
+                    },
+                    metrics: {}
+                };
+            }
+        case 'restart-job-from-step':
+            {
+                // Record the failed attempt FIRST (audit, with the restart feedback), then
+                // rewind the projection from restart_from so the prior result is preserved
+                // only in the attempt history. All in one transaction with the report.
+                await finishStepAttempt({
+                    stepId: decision.failedStepId,
+                    attempt: decision.attempt,
+                    status: 'failed',
+                    output: ctx.result.output ?? null,
+                    response: ctx.result.response ?? null,
+                    error: decision.failureError,
+                    exitCode: ctx.result.exitCode ?? null,
+                    logOutcome: ctx.logOutcome,
+                    gateResult: ctx.gateResult ?? null,
+                    restartFeedback: decision.feedback
+                }, tx);
+                await rewindStepsToPending({
+                    jobExecutionId: ctx.jobExecutionId,
+                    fromPosition: decision.restartFromPosition
+                }, tx);
+                await writeStepRestartEnqueuedOutbox(tx, {
+                    jobId: ctx.jobId,
+                    failedStepId: decision.failedStepId,
+                    failedStepAttempt: decision.attempt,
+                    restartFromStepId: decision.restartFromStepId,
+                    feedback: decision.feedback
+                });
+                // The job stays running; the next pull re-dispatches restart_from. Do not
+                // derive completion or emit a completion event.
+                return {
+                    outcome: {
+                        jobFinished: false
+                    },
+                    metrics: {
+                        stepRestartEnqueued: true
+                    }
+                };
+            }
+    }
+    // Re-derive completion from the post-apply projection and emit the
+    // steps-settled signal exactly once, here on the applied path.
+    const after = await getStepsByJobExecutionIdForUpdate(ctx.jobExecutionId, tx);
+    if (after.every((step)=>isTerminal(step.status))) {
+        const status = deriveCompletion(after);
+        await writeJobStepsSettledOutbox(tx, {
+            jobId: ctx.jobId,
+            jobExecutionId: ctx.jobExecutionId,
+            status
+        });
+        return {
+            outcome: {
+                jobFinished: true,
+                status
+            },
+            metrics: {
+                jobStepsSettledStatus: status
+            }
+        };
+    }
+    return {
+        outcome: {
+            jobFinished: false
+        },
+        metrics: {}
+    };
+}
+
+//# sourceMappingURL=apply-step-transition.js.map

package/dist/core/step-transition/apply-step-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/step-transition/apply-step-transition.ts"],"sourcesContent":["import type {LogOutcomeDto} from '@shipfox/api-workflows-dto';\nimport type {Tx} from '#db/db.js';\nimport {\n  applyStepResult,\n  finishStepAttempt,\n  getStepsByJobExecutionIdForUpdate,\n  rewindStepsToPending,\n  settleJobFailed,\n  writeJobStepsSettledOutbox,\n  writeStepRestartEnqueuedOutbox,\n} from '#db/workflow-runs.js';\nimport {\n  deriveCompletion,\n  isTerminal,\n  type StepReport,\n  type StepTransitionDecision,\n} from './decide-step-transition.js';\n\nexport type StepProgressionOutcome =\n  | {jobFinished: false}\n  | {jobFinished: true; status: 'succeeded' | 'failed'};\n\nexport interface StepProgressionMetrics {\n  jobStepsSettledStatus?: 'succeeded' | 'failed';\n  stepRestartEnqueued?: boolean;\n}\n\nexport interface StepProgressionResult {\n  outcome: StepProgressionOutcome;\n  metrics: StepProgressionMetrics;\n}\n\nexport interface ApplyStepTransitionContext {\n  jobId: string;\n  jobExecutionId: string;\n  result: StepReport;\n  logOutcome: LogOutcomeDto;\n  // Gate evaluation audit payload to record on the attempt, when a gate ran.\n  gateResult?: Record<string, unknown> | null;\n}\n\n// Durable side of the decision: writes the attempt + projection for a transition,\n// then derives job completion from the post-apply projection and enqueues the\n// completion event in the same transaction. Only called for a running target, so\n// every path here is an actual state change (idempotent no-ops are handled by the\n// caller before deciding).\nexport async function applyStepTransition(\n  decision: StepTransitionDecision,\n  ctx: ApplyStepTransitionContext,\n  tx: Tx,\n): Promise<StepProgressionResult> {\n  switch (decision.kind) {\n    case 'complete-step':\n    case 'complete-job': {\n      // A passing gate makes a step succeed even if the raw command status was\n      // 'failed', so the projection error is cleared regardless of the report.\n      await finishStepAttempt(\n        {\n          stepId: decision.stepId,\n          attempt: decision.attempt,\n          status: 'succeeded',\n          output: ctx.result.output ?? null,\n          response: ctx.result.response ?? null,\n          exitCode: ctx.result.exitCode ?? null,\n          logOutcome: ctx.logOutcome,\n          gateResult: ctx.gateResult ?? null,\n        },\n        tx,\n      );\n      await applyStepResult(\n        {\n          jobExecutionId: ctx.jobExecutionId,\n          stepId: decision.stepId,\n          status: 'succeeded',\n          error: null,\n        },\n        tx,\n      );\n      break;\n    }\n    case 'fail-job':\n    case 'fail-job-restart-exhausted': {\n      await finishStepAttempt(\n        {\n          stepId: decision.failedStepId,\n          attempt: decision.attempt,\n          status: 'failed',\n          output: ctx.result.output ?? null,\n          response: ctx.result.response ?? null,\n          error: decision.failureError,\n          exitCode: ctx.result.exitCode ?? null,\n          logOutcome: ctx.logOutcome,\n          gateResult: ctx.gateResult ?? null,\n        },\n        tx,\n      );\n      const status = await settleJobFailed(tx, {\n        jobId: ctx.jobId,\n        jobExecutionId: ctx.jobExecutionId,\n        failedStepId: decision.failedStepId,\n        error: decision.failureError ?? {message: 'Step failed'},\n      });\n      if (status !== null) {\n        return {\n          outcome: {jobFinished: true, status},\n          metrics: {jobStepsSettledStatus: status},\n        };\n      }\n      return {outcome: {jobFinished: false}, metrics: {}};\n    }\n    case 'restart-job-from-step': {\n      // Record the failed attempt FIRST (audit, with the restart feedback), then\n      // rewind the projection from restart_from so the prior result is preserved\n      // only in the attempt history. All in one transaction with the report.\n      await finishStepAttempt(\n        {\n          stepId: decision.failedStepId,\n          attempt: decision.attempt,\n          status: 'failed',\n          output: ctx.result.output ?? null,\n          response: ctx.result.response ?? null,\n          error: decision.failureError,\n          exitCode: ctx.result.exitCode ?? null,\n          logOutcome: ctx.logOutcome,\n          gateResult: ctx.gateResult ?? null,\n          restartFeedback: decision.feedback,\n        },\n        tx,\n      );\n      await rewindStepsToPending(\n        {jobExecutionId: ctx.jobExecutionId, fromPosition: decision.restartFromPosition},\n        tx,\n      );\n      await writeStepRestartEnqueuedOutbox(tx, {\n        jobId: ctx.jobId,\n        failedStepId: decision.failedStepId,\n        failedStepAttempt: decision.attempt,\n        restartFromStepId: decision.restartFromStepId,\n        feedback: decision.feedback,\n      });\n      // The job stays running; the next pull re-dispatches restart_from. Do not\n      // derive completion or emit a completion event.\n      return {outcome: {jobFinished: false}, metrics: {stepRestartEnqueued: true}};\n    }\n  }\n\n  // Re-derive completion from the post-apply projection and emit the\n  // steps-settled signal exactly once, here on the applied path.\n  const after = await getStepsByJobExecutionIdForUpdate(ctx.jobExecutionId, tx);\n  if (after.every((step) => isTerminal(step.status))) {\n    const status = deriveCompletion(after);\n    await writeJobStepsSettledOutbox(tx, {\n      jobId: ctx.jobId,\n      jobExecutionId: ctx.jobExecutionId,\n      status,\n    });\n    return {\n      outcome: {jobFinished: true, status},\n      metrics: {jobStepsSettledStatus: status},\n    };\n  }\n  return {outcome: {jobFinished: false}, metrics: {}};\n}\n"],"names":["applyStepResult","finishStepAttempt","getStepsByJobExecutionIdForUpdate","rewindStepsToPending","settleJobFailed","writeJobStepsSettledOutbox","writeStepRestartEnqueuedOutbox","deriveCompletion","isTerminal","applyStepTransition","decision","ctx","tx","kind","stepId","attempt","status","output","result","response","exitCode","logOutcome","gateResult","jobExecutionId","error","failedStepId","failureError","jobId","message","outcome","jobFinished","metrics","jobStepsSettledStatus","restartFeedback","feedback","fromPosition","restartFromPosition","failedStepAttempt","restartFromStepId","stepRestartEnqueued","after","every","step"],"mappings":"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"}

package/dist/core/step-transition/decide-step-transition.d.ts

@@ -0,0 +1,71 @@
+import type { PersistedEvaluationTraceEntry, Step, StepStatus } from '../entities/step.js';
+export declare function isTerminal(status: StepStatus): boolean;
+export declare function deriveCompletion(steps: Step[]): 'succeeded' | 'failed';
+export interface StepReport {
+    status: 'succeeded' | 'failed';
+    exitCode?: number | null;
+    error?: Record<string, unknown> | null;
+    output?: Record<string, unknown> | null;
+    response?: string | null;
+}
+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 {
+    steps: Step[];
+    target: Step;
+    reportedAttempt: number;
+    result: StepReport;
+    gateOutcome?: GateOutcome;
+    gateOnFailure?: {
+        restartFrom: string;
+        feedback?: string;
+    };
+    restartFeedback?: string;
+    maxAttempts?: number;
+    gatingAttemptCount?: number;
+}
+export declare const DEFAULT_RESTART_ATTEMPT_CAP = 3;
+export type StepTransitionDecision = {
+    kind: 'complete-step';
+    stepId: string;
+    attempt: number;
+} | {
+    kind: 'complete-job';
+    stepId: string;
+    attempt: number;
+} | {
+    kind: 'fail-job';
+    failedStepId: string;
+    attempt: number;
+    failureError: Record<string, unknown> | null;
+} | {
+    kind: 'restart-job-from-step';
+    failedStepId: string;
+    restartFromStepId: string;
+    restartFromPosition: number;
+    attempt: number;
+    feedback: string;
+    failureError: Record<string, unknown> | null;
+} | {
+    kind: 'fail-job-restart-exhausted';
+    failedStepId: string;
+    attempt: number;
+    maxAttempts: number;
+    failureError: Record<string, unknown> | null;
+};
+export declare function decideStepTransition(input: DecideStepTransitionInput): StepTransitionDecision;
+//# sourceMappingURL=decide-step-transition.d.ts.map

package/dist/core/step-transition/decide-step-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide-step-transition.d.ts","sourceRoot":"","sources":["../../../src/core/step-transition/decide-step-transition.ts"],"names":[],"mappings":"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"}

package/dist/core/step-transition/decide-step-transition.js

@@ -0,0 +1,110 @@
+const TERMINAL_STATUSES = new Set([
+    'succeeded',
+    'failed',
+    'cancelled',
+    'skipped'
+]);
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+export function deriveCompletion(steps) {
+    return steps.some((step)=>step.status === 'failed') ? 'failed' : 'succeeded';
+}
+// 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;
+function succeed(target, attempt, steps) {
+    // 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, attempt, failureError) {
+    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) {
+    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 = 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);
+}
+
+//# sourceMappingURL=decide-step-transition.js.map

package/dist/core/step-transition/decide-step-transition.js.map

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

package/dist/core/step-transition/evaluate-gate.d.ts

@@ -0,0 +1,28 @@
+import { type ResolvedField, type WorkflowExpression } from '@shipfox/expression';
+import type { GateOutcome, StepReport } from './decide-step-transition.js';
+export declare const GATE_EVALUATION_ERROR_REASON = "gate expression evaluation failed";
+export interface StepGate {
+    success?: WorkflowExpression;
+    onFailure?: {
+        restartFrom: string;
+        feedback?: string;
+        feedbackTemplate?: ResolvedField;
+    };
+}
+export declare function readStepGate(config: Record<string, unknown>): StepGate | undefined;
+/**
+ * Gate evaluation fails closed: a missing exit code or CEL evaluation error is
+ * `uncheckable` (a plain command failure), never a gate failure that can restart.
+ *
+ * Callers hold step-row locks while this runs. Keep the CEL context bounded
+ * unless evaluation gets a budget outside the lock. The materializer only
+ * persists CEL expressions, and this evaluator only needs the validated source.
+ */
+export declare function evaluateGate(gate: StepGate | undefined, result: StepReport): GateOutcome;
+export declare function evaluateGateFeedback(params: {
+    readonly gate: StepGate;
+    readonly result: StepReport;
+    readonly definitionId: string;
+}): string;
+export declare function gateResultPayload(outcome: GateOutcome, exitCode: number | null | undefined): Record<string, unknown> | null;
+//# sourceMappingURL=evaluate-gate.d.ts.map

package/dist/core/step-transition/evaluate-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-gate.d.ts","sourceRoot":"","sources":["../../../src/core/step-transition/evaluate-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAC,WAAW,EAAE,UAAU,EAAC,MAAM,6BAA6B,CAAC;AAMzE,eAAO,MAAM,4BAA4B,sCAAsC,CAAC;AAGhF,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,SAAS,CAAC,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,aAAa,CAAA;KAAC,CAAC;CACxF;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,GAAG,SAAS,CAoClF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,CAmCxF;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GAAG,MAAM,CAkBT;AAKD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CA6BhC"}

package/dist/core/step-transition/evaluate-gate.js

@@ -0,0 +1,159 @@
+import { capTraceEntries, evaluatePlannedPredicateAtSite, predicateTraceEntry } from '@shipfox/expression';
+import { assembleGateContext } from '../step-config/assemble-run-context.js';
+import { completeStepField } from '../step-config/fields.js';
+// The exact `uncheckable` reason recorded when the gate's CEL expression itself
+// throws (as opposed to a missing exit code). The DTO mapper keys on this string to
+// surface a distinct `evaluation_error` gate result, so the producer and the mapper
+// must share this constant rather than duplicating the literal.
+export const GATE_EVALUATION_ERROR_REASON = 'gate expression evaluation failed';
+// Read the gate persisted on a step's config by the materializer. Returns
+// undefined when the step has no gate of interest.
+export function readStepGate(config) {
+    const gate = config.gate;
+    if (!gate || typeof gate !== 'object') return undefined;
+    const raw = gate;
+    const successRaw = raw.success;
+    const success = successRaw && typeof successRaw.source === 'string' ? // JSON is structurally a WorkflowExpression.
+    successRaw : undefined;
+    const onFailureRaw = raw.on_failure;
+    const feedbackTemplateRaw = onFailureRaw?.feedback_template;
+    const feedbackTemplate = Array.isArray(feedbackTemplateRaw?.segments) && feedbackTemplateRaw.segments.every((segment)=>typeof segment === 'object' && segment !== null) ? feedbackTemplateRaw : undefined;
+    const onFailure = onFailureRaw && typeof onFailureRaw.restart_from === 'string' ? {
+        restartFrom: onFailureRaw.restart_from,
+        ...typeof onFailureRaw.feedback === 'string' ? {
+            feedback: onFailureRaw.feedback
+        } : {},
+        ...feedbackTemplate === undefined ? {} : {
+            feedbackTemplate
+        }
+    } : undefined;
+    if (!success && !onFailure) return undefined;
+    return {
+        ...success ? {
+            success
+        } : {},
+        ...onFailure ? {
+            onFailure
+        } : {}
+    };
+}
+/**
+ * Gate evaluation fails closed: a missing exit code or CEL evaluation error is
+ * `uncheckable` (a plain command failure), never a gate failure that can restart.
+ *
+ * Callers hold step-row locks while this runs. Keep the CEL context bounded
+ * unless evaluation gets a budget outside the lock. The materializer only
+ * persists CEL expressions, and this evaluator only needs the validated source.
+ */ export function evaluateGate(gate, result) {
+    if (!gate?.success) return {
+        kind: 'no-gate'
+    };
+    const source = gate.success.source;
+    if (result.exitCode === null || result.exitCode === undefined) {
+        return {
+            kind: 'uncheckable',
+            reason: 'step produced no exit code'
+        };
+    }
+    const context = assembleGateContext({
+        status: result.status,
+        exitCode: result.exitCode,
+        output: result.output
+    });
+    const outcome = evaluatePlannedPredicateAtSite({
+        expression: gate.success,
+        field: 'step.success',
+        site: context.site,
+        context: context.values
+    });
+    const trace = capTraceEntries([
+        {
+            ...predicateTraceEntry({
+                expression: source,
+                route: outcome.route,
+                site: context.site,
+                value: outcome.value,
+                degraded: outcome.evaluationFailed
+            }),
+            field: 'step.success'
+        }
+    ]);
+    if (outcome.evaluationFailed) {
+        return {
+            kind: 'uncheckable',
+            reason: GATE_EVALUATION_ERROR_REASON,
+            source,
+            trace
+        };
+    }
+    return outcome.value ? {
+        kind: 'passed',
+        source,
+        trace
+    } : {
+        kind: 'failed',
+        source,
+        trace
+    };
+}
+export function evaluateGateFeedback(params) {
+    const feedbackTemplate = params.gate.onFailure?.feedbackTemplate;
+    if (feedbackTemplate === undefined) {
+        return params.gate.onFailure?.feedback ?? 'gate condition not met';
+    }
+    const context = assembleGateContext({
+        status: params.result.status,
+        exitCode: params.result.exitCode ?? null,
+        output: params.result.output
+    });
+    return completeStepField({
+        field: 'step.feedback',
+        errorField: 'step.feedback',
+        template: feedbackTemplate,
+        context,
+        definitionId: params.definitionId
+    });
+}
+// Build the audit payload recorded on the step attempt for a gate evaluation.
+// Includes the evaluated `exit_code` so the gate decision is reconstructable from
+// the attempt row alone, independent of the column shape.
+export function gateResultPayload(outcome, exitCode) {
+    const exit_code = exitCode ?? null;
+    switch(outcome.kind){
+        case 'no-gate':
+            return null;
+        case 'passed':
+            return {
+                passed: true,
+                source: outcome.source,
+                exit_code,
+                ...outcome.trace === undefined ? {} : {
+                    trace: outcome.trace
+                }
+            };
+        case 'failed':
+            return {
+                passed: false,
+                source: outcome.source,
+                exit_code,
+                ...outcome.trace === undefined ? {} : {
+                    trace: outcome.trace
+                }
+            };
+        case 'uncheckable':
+            return {
+                passed: false,
+                uncheckable: true,
+                reason: outcome.reason,
+                exit_code,
+                ...outcome.source === undefined ? {} : {
+                    source: outcome.source
+                },
+                ...outcome.trace === undefined ? {} : {
+                    trace: outcome.trace
+                }
+            };
+    }
+}
+
+//# sourceMappingURL=evaluate-gate.js.map

package/dist/core/step-transition/evaluate-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/step-transition/evaluate-gate.ts"],"sourcesContent":["import {\n  capTraceEntries,\n  evaluatePlannedPredicateAtSite,\n  predicateTraceEntry,\n  type ResolvedField,\n  type WorkflowExpression,\n} from '@shipfox/expression';\nimport {assembleGateContext} from '../step-config/assemble-run-context.js';\nimport {completeStepField} from '../step-config/fields.js';\nimport type {GateOutcome, StepReport} from './decide-step-transition.js';\n\n// The exact `uncheckable` reason recorded when the gate's CEL expression itself\n// throws (as opposed to a missing exit code). The DTO mapper keys on this string to\n// surface a distinct `evaluation_error` gate result, so the producer and the mapper\n// must share this constant rather than duplicating the literal.\nexport const GATE_EVALUATION_ERROR_REASON = 'gate expression evaluation failed';\n\n// The gate as parsed from a step's materialized `config.gate` (snake_case JSON).\nexport interface StepGate {\n  success?: WorkflowExpression;\n  onFailure?: {restartFrom: string; feedback?: string; feedbackTemplate?: ResolvedField};\n}\n\n// Read the gate persisted on a step's config by the materializer. Returns\n// undefined when the step has no gate of interest.\nexport function readStepGate(config: Record<string, unknown>): StepGate | undefined {\n  const gate = config.gate;\n  if (!gate || typeof gate !== 'object') return undefined;\n  const raw = gate as Record<string, unknown>;\n\n  const successRaw = raw.success as Record<string, unknown> | undefined;\n  const success =\n    successRaw && typeof successRaw.source === 'string'\n      ? // The model validated this expression before materialization; the stored\n        // JSON is structurally a WorkflowExpression.\n        (successRaw as unknown as WorkflowExpression)\n      : undefined;\n\n  const onFailureRaw = raw.on_failure as Record<string, unknown> | undefined;\n  const feedbackTemplateRaw = onFailureRaw?.feedback_template as\n    | Record<string, unknown>\n    | undefined;\n  const feedbackTemplate =\n    Array.isArray(feedbackTemplateRaw?.segments) &&\n    feedbackTemplateRaw.segments.every((segment) => typeof segment === 'object' && segment !== null)\n      ? (feedbackTemplateRaw as unknown as ResolvedField)\n      : undefined;\n  const onFailure =\n    onFailureRaw && typeof onFailureRaw.restart_from === 'string'\n      ? {\n          restartFrom: onFailureRaw.restart_from,\n          ...(typeof onFailureRaw.feedback === 'string' ? {feedback: onFailureRaw.feedback} : {}),\n          ...(feedbackTemplate === undefined ? {} : {feedbackTemplate}),\n        }\n      : undefined;\n\n  if (!success && !onFailure) return undefined;\n  return {\n    ...(success ? {success} : {}),\n    ...(onFailure ? {onFailure} : {}),\n  };\n}\n\n/**\n * Gate evaluation fails closed: a missing exit code or CEL evaluation error is\n * `uncheckable` (a plain command failure), never a gate failure that can restart.\n *\n * Callers hold step-row locks while this runs. Keep the CEL context bounded\n * unless evaluation gets a budget outside the lock. The materializer only\n * persists CEL expressions, and this evaluator only needs the validated source.\n */\nexport function evaluateGate(gate: StepGate | undefined, result: StepReport): GateOutcome {\n  if (!gate?.success) return {kind: 'no-gate'};\n  const source = gate.success.source;\n\n  if (result.exitCode === null || result.exitCode === undefined) {\n    return {kind: 'uncheckable', reason: 'step produced no exit code'};\n  }\n\n  const context = assembleGateContext({\n    status: result.status,\n    exitCode: result.exitCode,\n    output: result.output,\n  });\n  const outcome = evaluatePlannedPredicateAtSite({\n    expression: gate.success,\n    field: 'step.success',\n    site: context.site,\n    context: context.values,\n  });\n  const trace = capTraceEntries([\n    {\n      ...predicateTraceEntry({\n        expression: source,\n        route: outcome.route,\n        site: context.site,\n        value: outcome.value,\n        degraded: outcome.evaluationFailed,\n      }),\n      field: 'step.success',\n    },\n  ]);\n  if (outcome.evaluationFailed) {\n    return {kind: 'uncheckable', reason: GATE_EVALUATION_ERROR_REASON, source, trace};\n  }\n  return outcome.value ? {kind: 'passed', source, trace} : {kind: 'failed', source, trace};\n}\n\nexport function evaluateGateFeedback(params: {\n  readonly gate: StepGate;\n  readonly result: StepReport;\n  readonly definitionId: string;\n}): string {\n  const feedbackTemplate = params.gate.onFailure?.feedbackTemplate;\n  if (feedbackTemplate === undefined) {\n    return params.gate.onFailure?.feedback ?? 'gate condition not met';\n  }\n\n  const context = assembleGateContext({\n    status: params.result.status,\n    exitCode: params.result.exitCode ?? null,\n    output: params.result.output,\n  });\n  return completeStepField({\n    field: 'step.feedback',\n    errorField: 'step.feedback',\n    template: feedbackTemplate,\n    context,\n    definitionId: params.definitionId,\n  });\n}\n\n// Build the audit payload recorded on the step attempt for a gate evaluation.\n// Includes the evaluated `exit_code` so the gate decision is reconstructable from\n// the attempt row alone, independent of the column shape.\nexport function gateResultPayload(\n  outcome: GateOutcome,\n  exitCode: number | null | undefined,\n): Record<string, unknown> | null {\n  const exit_code = exitCode ?? null;\n  switch (outcome.kind) {\n    case 'no-gate':\n      return null;\n    case 'passed':\n      return {\n        passed: true,\n        source: outcome.source,\n        exit_code,\n        ...(outcome.trace === undefined ? {} : {trace: outcome.trace}),\n      };\n    case 'failed':\n      return {\n        passed: false,\n        source: outcome.source,\n        exit_code,\n        ...(outcome.trace === undefined ? {} : {trace: outcome.trace}),\n      };\n    case 'uncheckable':\n      return {\n        passed: false,\n        uncheckable: true,\n        reason: outcome.reason,\n        exit_code,\n        ...(outcome.source === undefined ? {} : {source: outcome.source}),\n        ...(outcome.trace === undefined ? {} : {trace: outcome.trace}),\n      };\n  }\n}\n"],"names":["capTraceEntries","evaluatePlannedPredicateAtSite","predicateTraceEntry","assembleGateContext","completeStepField","GATE_EVALUATION_ERROR_REASON","readStepGate","config","gate","undefined","raw","successRaw","success","source","onFailureRaw","on_failure","feedbackTemplateRaw","feedback_template","feedbackTemplate","Array","isArray","segments","every","segment","onFailure","restart_from","restartFrom","feedback","evaluateGate","result","kind","exitCode","reason","context","status","output","outcome","expression","field","site","values","trace","route","value","degraded","evaluationFailed","evaluateGateFeedback","params","errorField","template","definitionId","gateResultPayload","exit_code","passed","uncheckable"],"mappings":"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"}

package/dist/core/step-transition/read-step-outputs.d.ts

@@ -0,0 +1,3 @@
+import { type OutputDeclarations } from '@shipfox/expression';
+export declare function readStepOutputs(config: Record<string, unknown>): OutputDeclarations | undefined;
+//# sourceMappingURL=read-step-outputs.d.ts.map

package/dist/core/step-transition/read-step-outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-step-outputs.d.ts","sourceRoot":"","sources":["../../../src/core/step-transition/read-step-outputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,kBAAkB,EAAc,MAAM,qBAAqB,CAAC;AAIzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,GAAG,SAAS,CAkB/F"}

package/dist/core/step-transition/read-step-outputs.js

@@ -0,0 +1,24 @@
+import { outputTypes } from '@shipfox/expression';
+const outputTypeSet = new Set(outputTypes);
+export function readStepOutputs(config) {
+    const outputs = config.outputs;
+    if (!isRecord(outputs)) return undefined;
+    const declarations = Object.create(null);
+    for (const [key, declaration] of Object.entries(outputs)){
+        if (!isRecord(declaration)) return undefined;
+        const type = declaration.type;
+        if (typeof type !== 'string' || !outputTypeSet.has(type)) return undefined;
+        declarations[key] = {
+            type: type,
+            ...!Object.hasOwn(declaration, 'schema') ? {} : {
+                schema: declaration.schema
+            }
+        };
+    }
+    return declarations;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+//# sourceMappingURL=read-step-outputs.js.map

package/dist/core/step-transition/read-step-outputs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/step-transition/read-step-outputs.ts"],"sourcesContent":["import {type OutputDeclarations, outputTypes} from '@shipfox/expression';\n\nconst outputTypeSet = new Set<string>(outputTypes);\n\nexport function readStepOutputs(config: Record<string, unknown>): OutputDeclarations | undefined {\n  const outputs = config.outputs;\n  if (!isRecord(outputs)) return undefined;\n\n  const declarations: Record<string, {type: (typeof outputTypes)[number]; schema?: unknown}> =\n    Object.create(null) as Record<string, {type: (typeof outputTypes)[number]; schema?: unknown}>;\n\n  for (const [key, declaration] of Object.entries(outputs)) {\n    if (!isRecord(declaration)) return undefined;\n    const type = declaration.type;\n    if (typeof type !== 'string' || !outputTypeSet.has(type)) return undefined;\n    declarations[key] = {\n      type: type as (typeof outputTypes)[number],\n      ...(!Object.hasOwn(declaration, 'schema') ? {} : {schema: declaration.schema}),\n    };\n  }\n\n  return declarations;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n"],"names":["outputTypes","outputTypeSet","Set","readStepOutputs","config","outputs","isRecord","undefined","declarations","Object","create","key","declaration","entries","type","has","hasOwn","schema","value","Array","isArray"],"mappings":"AAAA,SAAiCA,WAAW,QAAO,sBAAsB;AAEzE,MAAMC,gBAAgB,IAAIC,IAAYF;AAEtC,OAAO,SAASG,gBAAgBC,MAA+B;IAC7D,MAAMC,UAAUD,OAAOC,OAAO;IAC9B,IAAI,CAACC,SAASD,UAAU,OAAOE;IAE/B,MAAMC,eACJC,OAAOC,MAAM,CAAC;IAEhB,KAAK,MAAM,CAACC,KAAKC,YAAY,IAAIH,OAAOI,OAAO,CAACR,SAAU;QACxD,IAAI,CAACC,SAASM,cAAc,OAAOL;QACnC,MAAMO,OAAOF,YAAYE,IAAI;QAC7B,IAAI,OAAOA,SAAS,YAAY,CAACb,cAAcc,GAAG,CAACD,OAAO,OAAOP;QACjEC,YAAY,CAACG,IAAI,GAAG;YAClBG,MAAMA;YACN,GAAI,CAACL,OAAOO,MAAM,CAACJ,aAAa,YAAY,CAAC,IAAI;gBAACK,QAAQL,YAAYK,MAAM;YAAA,CAAC;QAC/E;IACF;IAEA,OAAOT;AACT;AAEA,SAASF,SAASY,KAAc;IAC9B,OAAO,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACC,MAAMC,OAAO,CAACF;AACvE"}