@shipfox/api-workflows 2.0.0

package/src/core/step-transition/evaluate-gate.test.ts

@@ -0,0 +1,317 @@
+import {parseWorkflowTemplate, planInterpolationField} from '@shipfox/expression';
+import {
+  evaluateGate,
+  evaluateGateFeedback,
+  gateResultPayload,
+  readStepGate,
+} from './evaluate-gate.js';
+
+function gateConfig(source: string, restartFrom?: string): Record<string, unknown> {
+  return {
+    run: 'echo hi',
+    gate: {
+      success: {language: 'cel', check: 'syntax', source},
+      ...(restartFrom ? {on_failure: {restart_from: restartFrom}} : {}),
+    },
+  };
+}
+
+function feedbackTemplate(source: string) {
+  const plan = planInterpolationField({
+    field: 'step.feedback',
+    segments: parseWorkflowTemplate(source),
+  });
+  if (!plan.ok) throw new Error('Expected test feedback template to plan');
+  return plan.plan.field;
+}
+
+function gateTrace(source: string, value: boolean) {
+  return [
+    {
+      expression: source,
+      roots: ['step'],
+      fillTarget: 'step-report',
+      evaluatedAt: 'step-report',
+      value: String(value),
+      field: 'step.success',
+    },
+  ];
+}
+
+function degradedGateTrace(source: string, roots: readonly string[]) {
+  return [
+    {
+      expression: source,
+      roots,
+      fillTarget: 'step-report' as const,
+      evaluatedAt: 'step-report' as const,
+      value: 'false',
+      degraded: true,
+      field: 'step.success' as const,
+    },
+  ];
+}
+
+describe('readStepGate', () => {
+  test('returns undefined when the config has no gate', () => {
+    expect(readStepGate({run: 'echo hi'})).toBeUndefined();
+  });
+
+  test('parses success and on_failure', () => {
+    const gate = readStepGate(gateConfig('step.exit_code == 0', 'producer'));
+    expect(gate?.success?.source).toBe('step.exit_code == 0');
+    expect(gate?.onFailure).toEqual({restartFrom: 'producer'});
+  });
+
+  test('parses feedback templates from on_failure', () => {
+    const gate = readStepGate({
+      ...gateConfig('step.exit_code == 0'),
+      gate: {
+        success: {language: 'cel', check: 'syntax', source: 'step.exit_code == 0'},
+        on_failure: {
+          restart_from: 'producer',
+          feedback: 'failed',
+          feedback_template: feedbackTemplate(`failed: \${{ step.outputs.summary }}`),
+        },
+      },
+    });
+
+    expect(gate?.onFailure?.feedbackTemplate).toEqual(
+      feedbackTemplate(`failed: \${{ step.outputs.summary }}`),
+    );
+  });
+});
+
+describe('evaluateGate', () => {
+  test('no gate → no-gate', () => {
+    expect(
+      evaluateGate(readStepGate({run: 'echo hi'}), {status: 'succeeded', exitCode: 0}),
+    ).toEqual({
+      kind: 'no-gate',
+    });
+  });
+
+  test('step.exit_code == 0 passes for exit 0', () => {
+    const gate = readStepGate(gateConfig('step.exit_code == 0'));
+    expect(evaluateGate(gate, {status: 'succeeded', exitCode: 0})).toEqual({
+      kind: 'passed',
+      source: 'step.exit_code == 0',
+      trace: gateTrace('step.exit_code == 0', true),
+    });
+  });
+
+  test('step.exit_code == 0 fails for a non-zero exit', () => {
+    const gate = readStepGate(gateConfig('step.exit_code == 0'));
+    expect(evaluateGate(gate, {status: 'failed', exitCode: 1})).toEqual({
+      kind: 'failed',
+      source: 'step.exit_code == 0',
+      trace: gateTrace('step.exit_code == 0', false),
+    });
+  });
+
+  test('a passing gate can succeed a non-zero exit (success: step.exit_code == 1)', () => {
+    const gate = readStepGate(gateConfig('step.exit_code == 1'));
+    expect(evaluateGate(gate, {status: 'failed', exitCode: 1})).toMatchObject({kind: 'passed'});
+  });
+
+  test('exit_code arithmetic can pass using CEL int values at runtime', () => {
+    const gate = readStepGate(gateConfig('step.exit_code % 2 == 0'));
+
+    const result = evaluateGate(gate, {status: 'succeeded', exitCode: 2});
+
+    expect(result).toEqual({
+      kind: 'passed',
+      source: 'step.exit_code % 2 == 0',
+      trace: gateTrace('step.exit_code % 2 == 0', true),
+    });
+  });
+
+  test('exit_code arithmetic can fail using CEL int values at runtime', () => {
+    const gate = readStepGate(gateConfig('step.exit_code % 2 == 0'));
+
+    const result = evaluateGate(gate, {status: 'failed', exitCode: 3});
+
+    expect(result).toEqual({
+      kind: 'failed',
+      source: 'step.exit_code % 2 == 0',
+      trace: gateTrace('step.exit_code % 2 == 0', false),
+    });
+  });
+
+  test('step.status gates on the reported step status', () => {
+    const gate = readStepGate(gateConfig('step.status == "succeeded"'));
+    expect(evaluateGate(gate, {status: 'succeeded', exitCode: 0})).toMatchObject({kind: 'passed'});
+    expect(evaluateGate(gate, {status: 'failed', exitCode: 0})).toMatchObject({kind: 'failed'});
+  });
+
+  test('step.outputs gates on reported output values', () => {
+    const gate = readStepGate(gateConfig('step.outputs.pass == true'));
+
+    const passed = evaluateGate(gate, {
+      status: 'succeeded',
+      exitCode: 0,
+      output: {pass: true},
+    });
+    const failed = evaluateGate(gate, {
+      status: 'succeeded',
+      exitCode: 0,
+      output: {pass: false},
+    });
+
+    expect(passed).toEqual({
+      kind: 'passed',
+      source: 'step.outputs.pass == true',
+      trace: gateTrace('step.outputs.pass == true', true),
+    });
+    expect(failed).toEqual({
+      kind: 'failed',
+      source: 'step.outputs.pass == true',
+      trace: gateTrace('step.outputs.pass == true', false),
+    });
+  });
+
+  test('unguarded missing step output keys fail closed as uncheckable', () => {
+    const gate = readStepGate(gateConfig('step.outputs.pass == true'));
+
+    const result = evaluateGate(gate, {status: 'succeeded', exitCode: 0, output: {}});
+
+    expect(result).toEqual({
+      kind: 'uncheckable',
+      reason: 'gate expression evaluation failed',
+      source: 'step.outputs.pass == true',
+      trace: [
+        {
+          expression: 'step.outputs.pass == true',
+          roots: ['step'],
+          fillTarget: 'step-report',
+          evaluatedAt: 'step-report',
+          value: 'false',
+          degraded: true,
+          field: 'step.success',
+        },
+      ],
+    });
+  });
+
+  test('has-guarded missing step output keys evaluate as a checkable failure', () => {
+    const source = 'has(step.outputs.pass) && step.outputs.pass == true';
+    const gate = readStepGate(gateConfig(source));
+
+    const result = evaluateGate(gate, {status: 'succeeded', exitCode: 0, output: {}});
+
+    expect(result).toEqual({kind: 'failed', source, trace: gateTrace(source, false)});
+  });
+
+  test('a missing exit code is uncheckable (never evaluated)', () => {
+    const gate = readStepGate(gateConfig('step.exit_code == 0'));
+    expect(evaluateGate(gate, {status: 'failed', exitCode: null})).toMatchObject({
+      kind: 'uncheckable',
+    });
+  });
+
+  test('an evaluation error is uncheckable, not a gate failure', () => {
+    const gate = readStepGate(gateConfig('missing_var == 0'));
+    expect(evaluateGate(gate, {status: 'succeeded', exitCode: 0})).toEqual({
+      kind: 'uncheckable',
+      reason: 'gate expression evaluation failed',
+      source: 'missing_var == 0',
+      trace: degradedGateTrace('missing_var == 0', ['missing_var']),
+    });
+  });
+});
+
+describe('evaluateGateFeedback', () => {
+  test('returns literal feedback when no template was planned', () => {
+    const gate = readStepGate({
+      ...gateConfig('step.exit_code == 0'),
+      gate: {
+        success: {language: 'cel', check: 'syntax', source: 'step.exit_code == 0'},
+        on_failure: {restart_from: 'producer', feedback: 'try again'},
+      },
+    });
+    if (!gate) throw new Error('Expected gate');
+
+    const result = evaluateGateFeedback({
+      gate,
+      result: {status: 'failed', exitCode: 1, output: {summary: 'unit failed'}},
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toBe('try again');
+  });
+
+  test('evaluates feedback templates against the reported step self-root', () => {
+    const gate = readStepGate({
+      ...gateConfig('step.exit_code == 0'),
+      gate: {
+        success: {language: 'cel', check: 'syntax', source: 'step.exit_code == 0'},
+        on_failure: {
+          restart_from: 'producer',
+          feedback: 'try again',
+          feedback_template: feedbackTemplate(`failed: \${{ step.outputs.summary }}`),
+        },
+      },
+    });
+    if (!gate) throw new Error('Expected gate');
+
+    const result = evaluateGateFeedback({
+      gate,
+      result: {status: 'failed', exitCode: 1, output: {summary: 'unit failed'}},
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toBe('failed: unit failed');
+  });
+});
+
+describe('gateResultPayload', () => {
+  test('no-gate → null', () => {
+    expect(gateResultPayload({kind: 'no-gate'}, 0)).toBeNull();
+  });
+
+  test('passed records the source and evaluated exit code', () => {
+    expect(gateResultPayload({kind: 'passed', source: 'step.exit_code == 0'}, 0)).toEqual({
+      passed: true,
+      source: 'step.exit_code == 0',
+      exit_code: 0,
+    });
+  });
+
+  test('failed records the source and evaluated exit code', () => {
+    expect(gateResultPayload({kind: 'failed', source: 'step.exit_code == 0'}, 1)).toEqual({
+      passed: false,
+      source: 'step.exit_code == 0',
+      exit_code: 1,
+    });
+  });
+
+  test('uncheckable records the reason and a null exit code', () => {
+    expect(gateResultPayload({kind: 'uncheckable', reason: 'no exit code'}, null)).toEqual({
+      passed: false,
+      uncheckable: true,
+      reason: 'no exit code',
+      exit_code: null,
+    });
+  });
+
+  test('uncheckable preserves an evaluation trace when the predicate ran', () => {
+    expect(
+      gateResultPayload(
+        {
+          kind: 'uncheckable',
+          reason: 'gate expression evaluation failed',
+          source: 'missing_var == 0',
+          trace: degradedGateTrace('missing_var == 0', ['missing_var']),
+        },
+        0,
+      ),
+    ).toEqual({
+      passed: false,
+      uncheckable: true,
+      reason: 'gate expression evaluation failed',
+      source: 'missing_var == 0',
+      exit_code: 0,
+      trace: degradedGateTrace('missing_var == 0', ['missing_var']),
+    });
+  });
+});

package/src/core/step-transition/evaluate-gate.ts

@@ -0,0 +1,168 @@
+import {
+  capTraceEntries,
+  evaluatePlannedPredicateAtSite,
+  predicateTraceEntry,
+  type ResolvedField,
+  type WorkflowExpression,
+} from '@shipfox/expression';
+import {assembleGateContext} from '../step-config/assemble-run-context.js';
+import {completeStepField} from '../step-config/fields.js';
+import type {GateOutcome, StepReport} from './decide-step-transition.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';
+
+// The gate as parsed from a step's materialized `config.gate` (snake_case JSON).
+export interface StepGate {
+  success?: WorkflowExpression;
+  onFailure?: {restartFrom: string; feedback?: string; feedbackTemplate?: ResolvedField};
+}
+
+// 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: Record<string, unknown>): StepGate | undefined {
+  const gate = config.gate;
+  if (!gate || typeof gate !== 'object') return undefined;
+  const raw = gate as Record<string, unknown>;
+
+  const successRaw = raw.success as Record<string, unknown> | undefined;
+  const success =
+    successRaw && typeof successRaw.source === 'string'
+      ? // The model validated this expression before materialization; the stored
+        // JSON is structurally a WorkflowExpression.
+        (successRaw as unknown as WorkflowExpression)
+      : undefined;
+
+  const onFailureRaw = raw.on_failure as Record<string, unknown> | undefined;
+  const feedbackTemplateRaw = onFailureRaw?.feedback_template as
+    | Record<string, unknown>
+    | undefined;
+  const feedbackTemplate =
+    Array.isArray(feedbackTemplateRaw?.segments) &&
+    feedbackTemplateRaw.segments.every((segment) => typeof segment === 'object' && segment !== null)
+      ? (feedbackTemplateRaw as unknown as ResolvedField)
+      : 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: StepGate | undefined, result: StepReport): GateOutcome {
+  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: {
+  readonly gate: StepGate;
+  readonly result: StepReport;
+  readonly definitionId: string;
+}): string {
+  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: GateOutcome,
+  exitCode: number | null | undefined,
+): Record<string, unknown> | null {
+  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}),
+      };
+  }
+}

package/src/core/step-transition/read-step-outputs.ts

@@ -0,0 +1,27 @@
+import {type OutputDeclarations, outputTypes} from '@shipfox/expression';
+
+const outputTypeSet = new Set<string>(outputTypes);
+
+export function readStepOutputs(config: Record<string, unknown>): OutputDeclarations | undefined {
+  const outputs = config.outputs;
+  if (!isRecord(outputs)) return undefined;
+
+  const declarations: Record<string, {type: (typeof outputTypes)[number]; schema?: unknown}> =
+    Object.create(null) as Record<string, {type: (typeof outputTypes)[number]; schema?: unknown}>;
+
+  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 as (typeof outputTypes)[number],
+      ...(!Object.hasOwn(declaration, 'schema') ? {} : {schema: declaration.schema}),
+    };
+  }
+
+  return declarations;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/core/workflow-run-creation.test.ts

@@ -0,0 +1,155 @@
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import {buildModel, template} from '#test/helpers/workflow-runs.js';
+import type {TriggerPayload, WorkflowRun} from './entities/workflow-run.js';
+import {
+  deriveInitialJobExecutionPlan,
+  materializeWorkflowRunJobs,
+} from './workflow-run-creation.js';
+
+const triggerPayload: TriggerPayload = {
+  source: 'manual',
+  event: 'fire',
+  subscriptionId: 'subscription-1',
+  userId: 'user-1',
+};
+
+describe('deriveInitialJobExecutionPlan', () => {
+  it('resolves initial execution name and runner templates from creation context', () => {
+    const model = buildModel({
+      jobs: {
+        deploy: {
+          name: `Deploy ${template('inputs.environment')}`,
+          runner: ['linux'],
+          runnerTemplates: [template('inputs.runner')],
+          steps: [{run: 'echo deploy'}],
+        },
+      },
+    });
+    const run = workflowRun({inputs: {environment: 'prod', runner: 'GPU'}});
+    const {modelJob, job} = materializedJob(model, run, {inputs: run.inputs});
+
+    const plan = deriveInitialJobExecutionPlan({
+      run,
+      modelJob,
+      job,
+      jobId: 'job-1',
+      sequence: 1,
+      fallbackName: 'deploy #1',
+      triggerPayload,
+      inputs: run.inputs,
+    });
+
+    expect(plan).toMatchObject({
+      name: 'Deploy prod',
+      runner: ['gpu', 'linux'],
+      evaluationTrace: [
+        {
+          expression: 'inputs.environment',
+          roots: ['inputs'],
+          fillTarget: 'run-creation',
+          evaluatedAt: 'execution-creation',
+          value: 'prod',
+          field: 'job.name',
+        },
+      ],
+    });
+  });
+
+  it('resolves variables referenced only by job runner templates', () => {
+    const model = buildModel({
+      jobs: {
+        build: {
+          runnerTemplates: [template('vars.RUNNER')],
+          steps: [{run: 'echo build'}],
+        },
+      },
+    });
+    const run = workflowRun();
+    const {modelJob, job} = materializedJob(model, run, {vars: {RUNNER: 'GPU'}});
+
+    const plan = deriveInitialJobExecutionPlan({
+      run,
+      modelJob,
+      job,
+      jobId: 'job-1',
+      sequence: 1,
+      fallbackName: 'build #1',
+      triggerPayload,
+      vars: {RUNNER: 'GPU'},
+    });
+
+    expect(plan.runner).toEqual(['gpu', 'ubuntu-latest']);
+  });
+
+  it('uses the fallback name for execution-name self references', () => {
+    const model = buildModel({
+      jobs: {
+        deploy: {
+          name: `Current ${template('execution.name')}`,
+          steps: [{run: 'echo deploy'}],
+        },
+      },
+    });
+    const run = workflowRun();
+    const {modelJob, job} = materializedJob(model, run);
+
+    const plan = deriveInitialJobExecutionPlan({
+      run,
+      modelJob,
+      job,
+      jobId: 'job-1',
+      sequence: 1,
+      fallbackName: 'deploy #1',
+      triggerPayload,
+    });
+
+    expect(plan.name).toBe('Current deploy #1');
+  });
+});
+
+function materializedJob(
+  model: WorkflowModel,
+  run: WorkflowRun,
+  context: {
+    inputs?: Record<string, unknown> | null | undefined;
+    vars?: Record<string, string> | undefined;
+  } = {},
+) {
+  const [job] = materializeWorkflowRunJobs({
+    run,
+    model,
+    triggerPayload,
+    inputs: context.inputs,
+    vars: context.vars,
+    definitionId: run.definitionId,
+  });
+  const [modelJob] = model.jobs;
+  if (!job || !modelJob) throw new Error('Expected materialized job');
+  return {job, modelJob};
+}
+
+function workflowRun(params: {inputs?: Record<string, unknown> | null} = {}): WorkflowRun {
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  return {
+    id: 'run-1',
+    workspaceId: 'workspace-1',
+    projectId: 'project-1',
+    definitionId: 'definition-1',
+    name: 'Test workflow',
+    status: 'pending',
+    currentAttempt: 1,
+    triggerProvider: null,
+    triggerSource: triggerPayload.source,
+    triggerEvent: triggerPayload.event,
+    triggerPayload,
+    inputs: params.inputs ?? null,
+    sourceSnapshot: null,
+    triggerIdempotencyKey: null,
+    timeoutMs: 60_000,
+    version: 1,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: null,
+    finishedAt: null,
+  };
+}