@shipfox/api-workflows 2.0.0

package/src/core/job-transition/decide-job-activation.test.ts

@@ -0,0 +1,196 @@
+import {createWorkflowExpression} from '@shipfox/expression';
+import type {Job} from '../entities/job.js';
+import type {JobExecution} from '../entities/job-execution.js';
+import type {WorkflowRun} from '../entities/workflow-run.js';
+import {decideJobActivation} from './decide-job-activation.js';
+
+describe('decideJobActivation', () => {
+  test('starts a pending job without an activation condition', () => {
+    const run = workflowRun();
+    const job = workflowJob({key: 'build'});
+
+    const decision = decideJobActivation({run, job, dependencies: []});
+
+    expect(decision).toEqual({kind: 'start-job', jobId: job.id});
+  });
+
+  test('starts a failure-handling job when its dependency failed', () => {
+    const run = workflowRun();
+    const build = workflowJob({key: 'build', status: 'failed'});
+    const notify = workflowJob({key: 'notify', dependencies: ['build']});
+
+    const decision = decideJobActivation({
+      run,
+      job: notify,
+      condition: expression('jobs.build.status == "failed"'),
+      dependencies: [{job: build, executions: []}],
+    });
+
+    expect(decision).toEqual({kind: 'start-job', jobId: notify.id});
+  });
+
+  test('skips a conditional job when the predicate is false', () => {
+    const run = workflowRun();
+    const build = workflowJob({key: 'build', status: 'succeeded'});
+    const notify = workflowJob({key: 'notify', dependencies: ['build']});
+
+    const decision = decideJobActivation({
+      run,
+      job: notify,
+      condition: expression('jobs.build.status == "failed"'),
+      dependencies: [{job: build, executions: []}],
+    });
+
+    expect(decision).toEqual({
+      kind: 'skip-job',
+      jobId: notify.id,
+      status: 'skipped',
+      statusReason: 'condition_rejected',
+      evaluationTrace: [
+        expect.objectContaining({
+          expression: 'jobs.build.status == "failed"',
+          roots: ['jobs'],
+          value: 'false',
+          field: 'job.if',
+        }),
+      ],
+    });
+  });
+
+  test('marks skipped jobs as condition_errored when the predicate cannot evaluate', () => {
+    const run = workflowRun();
+    const build = workflowJob({key: 'build', status: 'succeeded'});
+    const notify = workflowJob({key: 'notify', dependencies: ['build']});
+
+    const decision = decideJobActivation({
+      run,
+      job: notify,
+      condition: expression('jobs.build.outputs.sha.missing == "abc123"'),
+      dependencies: [{job: build, executions: []}],
+    });
+
+    expect(decision).toEqual({
+      kind: 'skip-job',
+      jobId: notify.id,
+      status: 'skipped',
+      statusReason: 'condition_errored',
+      evaluationTrace: [
+        expect.objectContaining({
+          expression: 'jobs.build.outputs.sha.missing == "abc123"',
+          roots: ['jobs'],
+          value: 'false',
+          degraded: true,
+          field: 'job.if',
+        }),
+      ],
+    });
+  });
+
+  test('returns terminal jobs unchanged', () => {
+    const run = workflowRun();
+    const job = workflowJob({key: 'build', status: 'skipped', version: 4});
+
+    const decision = decideJobActivation({
+      run,
+      job,
+      condition: expression('false'),
+      dependencies: [],
+    });
+
+    expect(decision).toEqual({
+      kind: 'terminal-job',
+      jobId: job.id,
+      status: 'skipped',
+      jobVersion: 4,
+    });
+  });
+});
+
+function expression(source: string) {
+  return createWorkflowExpression({source, check: {mode: 'syntax'}});
+}
+
+function workflowRun(): WorkflowRun {
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    definitionId: crypto.randomUUID(),
+    name: 'Run',
+    status: 'pending',
+    currentAttempt: 1,
+    triggerProvider: null,
+    triggerSource: 'manual',
+    triggerEvent: 'fire',
+    triggerPayload: {
+      source: 'manual',
+      event: 'fire',
+      subscriptionId: crypto.randomUUID(),
+      userId: crypto.randomUUID(),
+    },
+    inputs: null,
+    sourceSnapshot: null,
+    triggerIdempotencyKey: null,
+    timeoutMs: 3_600_000,
+    version: 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+    startedAt: null,
+    finishedAt: null,
+  };
+}
+
+function workflowJob(params: Partial<Job> & Pick<Job, 'key'>): Job {
+  return {
+    id: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    key: params.key,
+    mode: 'one_shot',
+    name: null,
+    status: params.status ?? 'pending',
+    statusReason: null,
+    carriedOver: false,
+    checkout: {permissions: {contents: 'read'}, persistCredentials: true},
+    success: null,
+    evaluationTrace: null,
+    executionTimeoutMs: null,
+    listeningTimeoutMs: null,
+    maxExecutions: null,
+    onResolve: null,
+    batchDebounceMs: null,
+    batchMaxSize: null,
+    batchMaxWaitMs: null,
+    listenerStatus: 'inactive',
+    resolutionReason: null,
+    listeningOn: null,
+    listeningUntil: null,
+    outputs: params.outputs ?? null,
+    dependencies: params.dependencies ?? [],
+    runner: ['ubuntu-latest'],
+    position: params.position ?? 0,
+    version: params.version ?? 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+  };
+}
+
+export function jobExecution(params: Partial<JobExecution> = {}): JobExecution {
+  return {
+    id: crypto.randomUUID(),
+    jobId: params.jobId ?? crypto.randomUUID(),
+    sequence: params.sequence ?? 1,
+    name: params.name ?? 'build',
+    runner: null,
+    status: params.status ?? 'succeeded',
+    statusReason: params.statusReason ?? null,
+    outputs: params.outputs ?? null,
+    triggerEvents: [],
+    version: 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+    queuedAt: null,
+    startedAt: null,
+    finishedAt: null,
+    timedOutAt: null,
+  };
+}

package/src/core/job-transition/decide-job-activation.ts

@@ -0,0 +1,79 @@
+import type {WorkflowExpression} from '@shipfox/expression';
+import {evaluatePlannedPredicateAtSite} from '@shipfox/expression';
+import {explicitConditionTrace} from '../condition-trace.js';
+import {isJobTerminal, type Job, type JobStatusReason} from '../entities/job.js';
+import type {WorkflowRun} from '../entities/workflow-run.js';
+import {
+  assembleJobActivationContext,
+  type JobContextInput,
+} from '../step-config/assemble-run-context.js';
+import type {RuntimeCompletionStatus} from '../workflow-scheduling/runtime-dag.js';
+import {runtimeCompletionStatusForJob} from './runtime-completion-status-for-job.js';
+
+export type JobActivationDecision =
+  | {
+      kind: 'start-job';
+      jobId: string;
+    }
+  | {
+      kind: 'skip-job';
+      jobId: string;
+      status: 'skipped';
+      statusReason: JobStatusReason;
+      evaluationTrace: ReturnType<typeof explicitConditionTrace>;
+    }
+  | {
+      kind: 'terminal-job';
+      jobId: string;
+      status: RuntimeCompletionStatus;
+      jobVersion: number;
+    };
+
+export interface DecideJobActivationInput {
+  run: WorkflowRun;
+  job: Job;
+  condition?: WorkflowExpression | undefined;
+  dependencies: readonly JobContextInput[];
+}
+
+export function decideJobActivation(input: DecideJobActivationInput): JobActivationDecision {
+  if (isJobTerminal(input.job.status)) {
+    return {
+      kind: 'terminal-job',
+      jobId: input.job.id,
+      status: runtimeCompletionStatusForJob(input.job.status),
+      jobVersion: input.job.version,
+    };
+  }
+
+  if (input.condition === undefined) return {kind: 'start-job', jobId: input.job.id};
+
+  const context = assembleJobActivationContext({
+    run: input.run,
+    triggerPayload: input.run.triggerPayload,
+    inputs: input.run.inputs,
+    jobs: input.dependencies,
+  });
+  const outcome = evaluatePlannedPredicateAtSite({
+    expression: input.condition,
+    field: 'job.if',
+    site: context.site,
+    context: context.values,
+  });
+  if (outcome.value) return {kind: 'start-job', jobId: input.job.id};
+
+  return {
+    kind: 'skip-job',
+    jobId: input.job.id,
+    status: 'skipped',
+    statusReason: outcome.evaluationFailed ? 'condition_errored' : 'condition_rejected',
+    evaluationTrace: explicitConditionTrace({
+      expression: input.condition,
+      field: 'job.if',
+      route: outcome.route,
+      site: context.site,
+      value: outcome.value,
+      degraded: outcome.evaluationFailed,
+    }),
+  };
+}

package/src/core/job-transition/derive-job-execution-outputs.ts

@@ -0,0 +1,41 @@
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {Job} from '../entities/job.js';
+import type {JobExecution} from '../entities/job-execution.js';
+import type {Step, StepAttempt} from '../entities/step.js';
+import type {WorkflowRun} from '../entities/workflow-run.js';
+import {
+  assembleExecutionResolutionContext,
+  type JobContextInput,
+} from '../step-config/assemble-run-context.js';
+import {materializeJobOutputs} from '../step-config/materialize-workflow-model.js';
+
+export function deriveJobExecutionOutputs(params: {
+  run: WorkflowRun;
+  modelJob: WorkflowModel['jobs'][number];
+  job: Job;
+  jobExecution: JobExecution;
+  executions: readonly JobExecution[];
+  steps: readonly Step[];
+  attempts: readonly StepAttempt[];
+  jobs: readonly JobContextInput[];
+  vars?: Record<string, string> | undefined;
+}): Record<string, unknown> | null {
+  const context = assembleExecutionResolutionContext({
+    run: params.run,
+    triggerPayload: params.run.triggerPayload,
+    inputs: params.run.inputs,
+    vars: params.vars,
+    job: params.job,
+    jobExecution: params.jobExecution,
+    executions: params.executions,
+    steps: params.steps,
+    attempts: params.attempts,
+    jobs: params.jobs,
+  });
+
+  return materializeJobOutputs({
+    job: params.modelJob,
+    context,
+    definitionId: params.run.definitionId,
+  });
+}

package/src/core/job-transition/derive-job-success.test.ts

@@ -0,0 +1,133 @@
+import type {Job} from '../entities/job.js';
+import type {JobExecution} from '../entities/job-execution.js';
+import {deriveJobSuccess} from './derive-job-success.js';
+
+describe('deriveJobSuccess', () => {
+  test('treats zero or cancelled listener executions as successful by default', () => {
+    const empty = deriveJobSuccess({success: null, executions: [], jobs: []});
+    const cancelled = deriveJobSuccess({
+      success: null,
+      executions: [jobExecution({status: 'cancelled'})],
+      jobs: [],
+    });
+
+    expect(empty).toMatchObject({status: 'succeeded', statusReason: null});
+    expect(cancelled).toMatchObject({status: 'succeeded', statusReason: null});
+    expect(empty.trace).toEqual([
+      expect.objectContaining({
+        expression: "!executions.exists(e, e.status == 'failed')",
+        roots: ['executions'],
+        fillTarget: 'job-resolution',
+        evaluatedAt: 'job-resolution',
+        value: 'true',
+        field: 'job.success',
+      }),
+    ]);
+    expect(cancelled.trace).toEqual(empty.trace);
+  });
+
+  test('fails with the first execution status reason when the success expression is false', () => {
+    const result = deriveJobSuccess({
+      success: null,
+      executions: [jobExecution({status: 'failed', statusReason: 'timed_out'})],
+      jobs: [],
+    });
+
+    expect(result).toMatchObject({status: 'failed', statusReason: 'timed_out'});
+  });
+
+  test('resolves custom success expressions over direct dependency outputs', () => {
+    const build = workflowJob({
+      key: 'build',
+      status: 'succeeded',
+      outputs: {release: 'yes'},
+    });
+
+    const result = deriveJobSuccess({
+      success: 'jobs.build.status == "succeeded" && jobs.build.outputs.release == "yes"',
+      executions: [jobExecution({status: 'succeeded'})],
+      jobs: [{job: build, executions: []}],
+    });
+
+    expect(result).toMatchObject({status: 'succeeded', statusReason: null});
+  });
+
+  test('fails closed when the success expression throws at runtime', () => {
+    const result = deriveJobSuccess({
+      success: 'executions.all(e, 1 / 0 == 0)',
+      executions: [jobExecution({status: 'succeeded'})],
+      jobs: [],
+    });
+
+    expect(result).toMatchObject({
+      status: 'failed',
+      statusReason: 'unknown',
+      trace: [
+        expect.objectContaining({
+          expression: 'executions.all(e, 1 / 0 == 0)',
+          roots: ['executions'],
+          fillTarget: 'job-resolution',
+          evaluatedAt: 'job-resolution',
+          value: 'false',
+          degraded: true,
+          field: 'job.success',
+        }),
+      ],
+    });
+  });
+});
+
+function workflowJob(params: Partial<Job> & Pick<Job, 'key'>): Job {
+  return {
+    id: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    key: params.key,
+    mode: 'one_shot',
+    name: null,
+    status: params.status ?? 'pending',
+    statusReason: null,
+    carriedOver: false,
+    checkout: {permissions: {contents: 'read'}, persistCredentials: true},
+    success: null,
+    evaluationTrace: null,
+    executionTimeoutMs: null,
+    listeningTimeoutMs: null,
+    maxExecutions: null,
+    onResolve: null,
+    batchDebounceMs: null,
+    batchMaxSize: null,
+    batchMaxWaitMs: null,
+    listenerStatus: 'inactive',
+    resolutionReason: null,
+    listeningOn: null,
+    listeningUntil: null,
+    outputs: params.outputs ?? null,
+    dependencies: params.dependencies ?? [],
+    runner: ['ubuntu-latest'],
+    position: params.position ?? 0,
+    version: params.version ?? 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+  };
+}
+
+function jobExecution(params: Partial<JobExecution> = {}): JobExecution {
+  return {
+    id: crypto.randomUUID(),
+    jobId: params.jobId ?? crypto.randomUUID(),
+    sequence: params.sequence ?? 1,
+    name: params.name ?? 'build',
+    runner: null,
+    status: params.status ?? 'succeeded',
+    statusReason: params.statusReason ?? null,
+    outputs: params.outputs ?? null,
+    triggerEvents: [],
+    version: 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+    queuedAt: null,
+    startedAt: null,
+    finishedAt: null,
+    timedOutAt: null,
+  };
+}

package/src/core/job-transition/derive-job-success.ts

@@ -0,0 +1,67 @@
+import {DEFAULT_JOB_SUCCESS} from '@shipfox/api-definitions';
+import {
+  capTraceEntries,
+  createWorkflowExpression,
+  evaluatePlannedPredicateAtSite,
+  predicateTraceEntry,
+} from '@shipfox/expression';
+import type {JobStatusReason} from '../entities/job.js';
+import type {JobExecution} from '../entities/job-execution.js';
+import type {PersistedEvaluationTraceEntry} from '../entities/step.js';
+import {
+  assembleExecutionsContext,
+  assembleJobsContext,
+  type JobContextInput,
+} from '../step-config/assemble-run-context.js';
+import type {RuntimeCompletionStatus} from '../workflow-scheduling/runtime-dag.js';
+
+export interface DeriveJobSuccessResult {
+  status: RuntimeCompletionStatus;
+  statusReason: JobStatusReason | null;
+  trace: readonly PersistedEvaluationTraceEntry[];
+}
+
+export function deriveJobSuccess(params: {
+  success: string | null;
+  executions: readonly JobExecution[];
+  jobs: readonly JobContextInput[];
+}): DeriveJobSuccessResult {
+  const expression = createWorkflowExpression({
+    source: params.success ?? DEFAULT_JOB_SUCCESS,
+    check: {mode: 'syntax'},
+  });
+  const context = {
+    ...assembleExecutionsContext(params.executions),
+    ...assembleJobsContext(params.jobs),
+  };
+  const outcome = evaluatePlannedPredicateAtSite({
+    expression,
+    field: 'job.success',
+    site: 'job-resolution',
+    context,
+  });
+  const trace = capTraceEntries([
+    {
+      ...predicateTraceEntry({
+        expression: expression.source,
+        route: outcome.route,
+        site: 'job-resolution',
+        value: outcome.value,
+        degraded: outcome.evaluationFailed,
+      }),
+      field: 'job.success',
+    },
+  ]);
+  const passed = outcome.value;
+  const status: RuntimeCompletionStatus = passed ? 'succeeded' : 'failed';
+  if (status === 'succeeded') return {status, statusReason: null, trace};
+
+  return {
+    status,
+    statusReason: outcome.evaluationFailed
+      ? 'unknown'
+      : (params.executions.find((execution) => execution.statusReason)?.statusReason ??
+        'step_failed'),
+    trace,
+  };
+}

package/src/core/job-transition/index.ts

@@ -0,0 +1,11 @@
+export {
+  type DecideJobActivationInput,
+  decideJobActivation,
+  type JobActivationDecision,
+} from './decide-job-activation.js';
+export {deriveJobExecutionOutputs} from './derive-job-execution-outputs.js';
+export {
+  type DeriveJobSuccessResult,
+  deriveJobSuccess,
+} from './derive-job-success.js';
+export {runtimeCompletionStatusForJob} from './runtime-completion-status-for-job.js';

package/src/core/job-transition/runtime-completion-status-for-job.ts

@@ -0,0 +1,14 @@
+import type {JobStatus} from '../entities/job.js';
+import type {RuntimeCompletionStatus} from '../workflow-scheduling/runtime-dag.js';
+
+export function runtimeCompletionStatusForJob(status: JobStatus): RuntimeCompletionStatus {
+  if (
+    status === 'succeeded' ||
+    status === 'failed' ||
+    status === 'cancelled' ||
+    status === 'skipped'
+  ) {
+    return status;
+  }
+  throw new Error(`Job status is not terminal: ${status}`);
+}

package/src/core/listener-execution-materialization.test.ts

@@ -0,0 +1,49 @@
+import {workflowModel} from '#test/index.js';
+import {materializeListenerExecution} from './listener-execution-materialization.js';
+
+describe('materializeListenerExecution', () => {
+  it('fails cleanly when agent integration materialization is unresolvable', () => {
+    const model = workflowModel({
+      jobs: {
+        review: {
+          steps: [
+            {
+              prompt: 'Review the pull request.',
+              integrations: [{include: ['issue_read.get'], allowWrite: false}],
+            },
+          ],
+        },
+      },
+    });
+
+    const result = materializeListenerExecution({
+      model,
+      run: {
+        id: crypto.randomUUID(),
+        name: 'Review run',
+        definitionId: crypto.randomUUID(),
+        projectId: crypto.randomUUID(),
+        workspaceId: crypto.randomUUID(),
+        createdAt: new Date('2026-01-01T00:00:00.000Z'),
+        triggerPayload: {
+          source: 'github',
+          event: 'pull_request',
+          deliveryId: crypto.randomUUID(),
+          data: {action: 'opened'},
+        },
+        inputs: null,
+      },
+      job: {id: crypto.randomUUID(), key: 'review'},
+      sequence: 1,
+      triggerEvents: [],
+      priorExecutions: [],
+    });
+
+    expect(result).toMatchObject({
+      status: 'failed',
+      statusReason: 'unknown',
+      runner: [],
+      steps: [],
+    });
+  });
+});