@shipfox/api-workflows 2.0.0

package/src/core/entities/job-listener-event.ts

@@ -0,0 +1,15 @@
+export type JobListenerEventDisposition = 'fire' | 'resolve';
+
+export interface JobListenerEvent {
+  id: string;
+  jobId: string;
+  disposition: JobListenerEventDisposition;
+  eventRef: string;
+  deliveryId: string;
+  source: string;
+  event: string;
+  payload: unknown;
+  receivedAt: Date;
+  consumedByExecutionId: string | null;
+  createdAt: Date;
+}

package/src/core/entities/job.ts

@@ -0,0 +1,91 @@
+import type {PersistedEvaluationTraceEntry} from './step.js';
+
+export type JobStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'skipped';
+
+export type JobMode = 'one_shot' | 'listening';
+
+export type ListenerStatus = 'inactive' | 'listening' | 'resolved';
+
+export type ResolutionReason = 'until' | 'timeout' | 'max_executions' | 'cancelled';
+
+export interface JobCheckout {
+  permissions: {
+    contents: 'read' | 'write';
+  };
+  persistCredentials: boolean;
+}
+
+export const JOB_STATUS_REASONS = [
+  'dependency_not_completed',
+  'condition_false',
+  'default_gate_rejected',
+  'condition_rejected',
+  'condition_errored',
+  'user_cancelled',
+  'run_cancelled',
+  'timed_out',
+  'runner_lost',
+  'step_failed',
+  'unknown',
+] as const;
+
+export type JobStatusReason = (typeof JOB_STATUS_REASONS)[number];
+
+const JOB_STATUS_REASON_SET = new Set<JobStatusReason>(JOB_STATUS_REASONS);
+
+export interface Job {
+  id: string;
+  workflowRunAttemptId: string;
+  key: string;
+  mode: JobMode;
+  name: string | null;
+  status: JobStatus;
+  statusReason: JobStatusReason | null;
+  carriedOver: boolean;
+  checkout: JobCheckout;
+  success?: string | null;
+  evaluationTrace?: readonly PersistedEvaluationTraceEntry[] | null;
+  executionTimeoutMs?: number | null;
+  listeningTimeoutMs: number | null;
+  maxExecutions: number | null;
+  onResolve: 'finish' | 'cancel' | null;
+  batchDebounceMs: number | null;
+  batchMaxSize: number | null;
+  batchMaxWaitMs: number | null;
+  listenerStatus: ListenerStatus;
+  resolutionReason: ResolutionReason | null;
+  listeningOn: JobListeningTrigger[] | null;
+  listeningUntil: JobListeningTrigger[] | null;
+  outputs: Record<string, unknown> | null;
+  dependencies: string[];
+  runner: string[] | null;
+  position: number;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface JobListeningTrigger {
+  readonly source: string;
+  readonly event: string;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+  readonly filter?: string;
+}
+
+export type TerminalJobStatus = Extract<
+  JobStatus,
+  'succeeded' | 'failed' | 'cancelled' | 'skipped'
+>;
+
+const TERMINAL_JOB_STATUSES = new Set<JobStatus>(['succeeded', 'failed', 'cancelled', 'skipped']);
+
+export function isJobTerminal(status: JobStatus): status is TerminalJobStatus {
+  return TERMINAL_JOB_STATUSES.has(status);
+}
+
+export function toJobStatusReason(value: string | null): JobStatusReason | null {
+  if (value === null) return null;
+  return JOB_STATUS_REASON_SET.has(value as JobStatusReason)
+    ? (value as JobStatusReason)
+    : 'unknown';
+}

package/src/core/entities/step.ts

@@ -0,0 +1,126 @@
+import type {
+  AgentIntegrationMcpServerConfigDto,
+  AgentThinking,
+  Harness,
+  MaterializedAgentIntegrationConfigDto,
+} from '@shipfox/api-agent-dto';
+import type {
+  EvaluationTraceEntry,
+  EvaluationTraceLimitEntry,
+  ResolvedField,
+  WorkflowExpression,
+} from '@shipfox/expression';
+import type {InterpolationUnresolvableField} from '../errors.js';
+
+export type StepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'skipped';
+
+export const STEP_STATUS_REASONS = [
+  'default_gate_rejected',
+  'condition_rejected',
+  'condition_errored',
+] as const;
+
+export type StepStatusReason = (typeof STEP_STATUS_REASONS)[number];
+
+const STEP_STATUS_REASON_SET = new Set<StepStatusReason>(STEP_STATUS_REASONS);
+
+export function toStepStatusReason(value: string | null): StepStatusReason | null {
+  if (value === null) return null;
+  return STEP_STATUS_REASON_SET.has(value as StepStatusReason) ? (value as StepStatusReason) : null;
+}
+
+export type StepAttemptLogOutcome = 'drained' | 'abandoned';
+
+// A step_attempts row exists only once an attempt is dispatched, so it is never
+// 'pending' or 'skipped'.
+export type StepAttemptStatus = Exclude<StepStatus, 'pending' | 'skipped'>;
+
+export interface StepSourceLocation {
+  startLine: number;
+  endLine: number;
+}
+
+/**
+ * Trace entry after a resolver-local expression trace is attached to workflow
+ * storage.
+ *
+ * Step config traces are stored on step attempts with the resolved attempt
+ * config; job-level traces are stored on the job or job-execution row whose
+ * value/status they explain. Keep `field` as the authored field path that
+ * produced the trace, not as a step-only enum.
+ */
+export type PersistedEvaluationTraceEntry =
+  | (EvaluationTraceEntry & {
+      readonly field: string;
+      readonly envKey?: string;
+    })
+  | EvaluationTraceLimitEntry;
+
+export interface StepConfigEvaluationTraceEntry extends EvaluationTraceEntry {
+  readonly field: InterpolationUnresolvableField;
+  readonly envKey?: string;
+}
+
+export interface StepConfigDispatchPlan {
+  run?: ResolvedField;
+  env?: Readonly<Record<string, ResolvedField>>;
+  agent?: {
+    prompt?: ResolvedField;
+    model?: ResolvedField;
+    provider?: ResolvedField;
+    harness?: Harness;
+    thinking?: AgentThinking;
+    tools?: readonly string[];
+    integrations?: readonly MaterializedAgentIntegrationConfigDto[];
+    mcpServers?: readonly AgentIntegrationMcpServerConfigDto[];
+  };
+  trace?: readonly (StepConfigEvaluationTraceEntry | EvaluationTraceLimitEntry)[];
+}
+
+export interface Step {
+  id: string;
+  jobExecutionId: string;
+  key: string | null;
+  name: string;
+  sourceLocation: StepSourceLocation | null;
+  status: StepStatus;
+  statusReason: StepStatusReason | null;
+  evaluationTrace: readonly PersistedEvaluationTraceEntry[] | null;
+  type: string;
+  config: Record<string, unknown>;
+  condition: WorkflowExpression | null;
+  configPlan: StepConfigDispatchPlan | null;
+  authoredConfig: Record<string, unknown> | null;
+  error: Record<string, unknown> | null;
+  position: number;
+  version: number;
+  // Execution-attempt identity for the current projection: which attempt the
+  // status/output/error above reflect. Distinct from `version` (the optimistic
+  // row counter). Starts at 1 and is bumped when a step is rewound.
+  currentAttempt: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// Append-only execution history: one row per dispatched attempt of a step. The
+// current projection lives on `Step`; this is the audit trail and the
+// idempotency anchor (unique on (stepId, attempt)).
+export interface StepAttempt {
+  id: string;
+  stepId: string;
+  attempt: number;
+  executionOrder: number;
+  status: StepAttemptStatus;
+  config: Record<string, unknown> | null;
+  evaluationTrace: readonly PersistedEvaluationTraceEntry[] | null;
+  output: Record<string, unknown> | null;
+  response: string | null;
+  error: Record<string, unknown> | null;
+  exitCode: number | null;
+  gateResult: Record<string, unknown> | null;
+  restartFeedback: string | null;
+  logOutcome: StepAttemptLogOutcome | null;
+  startedAt: Date;
+  finishedAt: Date | null;
+  createdAt: Date;
+}

package/src/core/entities/workflow-run-attempt.ts

@@ -0,0 +1,21 @@
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {AgentToolMaterializationSnapshot} from '#core/agent-tools.js';
+import type {WorkflowRunStatus} from './workflow-run.js';
+
+export type RerunMode = 'all' | 'failed';
+
+export interface WorkflowRunAttempt {
+  id: string;
+  workflowRunId: string;
+  attempt: number;
+  status: WorkflowRunStatus;
+  rerunMode: RerunMode | null;
+  rerunByUserId: string | null;
+  model: WorkflowModel | null;
+  agentToolMaterialization: AgentToolMaterializationSnapshot | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+}

package/src/core/entities/workflow-run.ts

@@ -0,0 +1,94 @@
+import type {Job} from './job.js';
+import type {JobExecution} from './job-execution.js';
+import type {Step, StepAttempt} from './step.js';
+import type {WorkflowRunAttempt} from './workflow-run-attempt.js';
+
+export type WorkflowRunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+
+export type TerminalWorkflowRunStatus = Extract<
+  WorkflowRunStatus,
+  'succeeded' | 'failed' | 'cancelled'
+>;
+
+const TERMINAL_WORKFLOW_RUN_STATUSES = new Set<WorkflowRunStatus>([
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
+export function isWorkflowRunTerminal(
+  status: WorkflowRunStatus,
+): status is TerminalWorkflowRunStatus {
+  return TERMINAL_WORKFLOW_RUN_STATUSES.has(status);
+}
+
+export interface WorkflowSourceSnapshot {
+  content: string;
+  format: 'yaml';
+}
+
+export type TriggerPayload =
+  | {
+      source: 'manual';
+      provider?: 'manual' | undefined;
+      event: 'fire';
+      subscriptionId: string;
+      userId: string;
+    }
+  | {
+      source: 'cron';
+      provider?: 'cron' | undefined;
+      event: 'tick';
+      scheduleId: string;
+    }
+  // Integration sources (github, gitlab, sentry, …) flow through opaquely: the
+  // run records what fired it and carries the raw event payload, without the
+  // triggers module having to know each source's shape.
+  | {
+      source: string;
+      provider?: string | undefined;
+      event: string;
+      deliveryId: string;
+      data: unknown;
+    };
+
+export interface WorkflowRun {
+  id: string;
+  workspaceId: string;
+  projectId: string;
+  definitionId: string;
+  name: string;
+  status: WorkflowRunStatus;
+  currentAttempt: number;
+  triggerProvider: string | null;
+  triggerSource: string;
+  triggerEvent: string;
+  triggerPayload: TriggerPayload;
+  inputs: Record<string, unknown> | null;
+  sourceSnapshot: WorkflowSourceSnapshot | null;
+  triggerIdempotencyKey: string | null;
+  timeoutMs: number;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+}
+
+export interface StepDetail extends Step {
+  attempts: StepAttempt[];
+}
+
+export interface JobExecutionDetail extends JobExecution {
+  steps: StepDetail[];
+}
+
+export interface WorkflowJobDetail extends Job {
+  jobExecutions: JobExecutionDetail[];
+}
+
+export interface WorkflowRunDetail extends WorkflowRun {
+  runAttempt: WorkflowRunAttempt;
+  latestAttempt: number;
+  jobs: WorkflowJobDetail[];
+}

package/src/core/errors.test.ts

@@ -0,0 +1,45 @@
+import {
+  AgentConfigUnresolvableError,
+  DefinitionNotFoundError,
+  InvalidJobRunnerLabelsError,
+  isPermanentRunWorkflowError,
+  ProjectMismatchError,
+} from './errors.js';
+
+describe('isPermanentRunWorkflowError', () => {
+  test('is true for a deleted definition', () => {
+    const result = isPermanentRunWorkflowError(new DefinitionNotFoundError('def-1'));
+
+    expect(result).toBe(true);
+  });
+
+  test('is true for a project mismatch', () => {
+    const result = isPermanentRunWorkflowError(new ProjectMismatchError('proj-a', 'proj-b'));
+
+    expect(result).toBe(true);
+  });
+
+  test('is true for unresolvable agent configuration', () => {
+    const result = isPermanentRunWorkflowError(new AgentConfigUnresolvableError('def-1'));
+
+    expect(result).toBe(true);
+  });
+
+  test('is true for invalid job runner labels', () => {
+    const result = isPermanentRunWorkflowError(new InvalidJobRunnerLabelsError(['has space']));
+
+    expect(result).toBe(true);
+  });
+
+  test('is false for a plain error treated as transient', () => {
+    const result = isPermanentRunWorkflowError(new Error('database unavailable'));
+
+    expect(result).toBe(false);
+  });
+
+  test('is false for a non-error thrown value', () => {
+    const result = isPermanentRunWorkflowError('boom');
+
+    expect(result).toBe(false);
+  });
+});

package/src/core/errors.ts

@@ -0,0 +1,209 @@
+import type {JobStatus} from './entities/job.js';
+import type {WorkflowRunStatus} from './entities/workflow-run.js';
+
+export class DefinitionNotFoundError extends Error {
+  constructor(definitionId: string) {
+    super(`Definition not found: ${definitionId}`);
+    this.name = 'DefinitionNotFoundError';
+  }
+}
+
+export class ProjectMismatchError extends Error {
+  constructor(definitionProjectId: string, requestProjectId: string) {
+    super(
+      `Definition belongs to project ${definitionProjectId}, but request targets project ${requestProjectId}`,
+    );
+    this.name = 'ProjectMismatchError';
+  }
+}
+
+export class AgentConfigUnresolvableError extends Error {
+  constructor(
+    readonly definitionId: string,
+    options?: ErrorOptions | undefined,
+  ) {
+    super(`Agent configuration cannot be resolved for definition ${definitionId}`, options);
+    this.name = 'AgentConfigUnresolvableError';
+  }
+}
+
+export class AgentIntegrationMaterializationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentIntegrationMaterializationError';
+  }
+}
+
+export type InterpolationUnresolvableField =
+  | 'run'
+  | 'env'
+  | 'agent.prompt'
+  | 'agent.model'
+  | 'agent.provider'
+  | 'job.runner'
+  | 'job.outputs'
+  | 'job.name'
+  | 'step.name'
+  | 'step.feedback';
+
+export class InterpolationUnresolvableError extends Error {
+  readonly field: InterpolationUnresolvableField;
+  readonly source: string;
+  readonly envKey?: string;
+
+  constructor(
+    readonly definitionId: string,
+    params: {
+      readonly field: InterpolationUnresolvableField;
+      readonly source: string;
+      readonly envKey?: string;
+      readonly cause?: unknown;
+    },
+  ) {
+    super(interpolationUnresolvableMessage(definitionId, params), {cause: params.cause});
+    this.name = 'InterpolationUnresolvableError';
+    this.field = params.field;
+    this.source = params.source;
+    if (params.envKey !== undefined) this.envKey = params.envKey;
+  }
+}
+
+function interpolationUnresolvableMessage(
+  definitionId: string,
+  params: {
+    readonly field: InterpolationUnresolvableField;
+    readonly source: string;
+    readonly envKey?: string;
+  },
+): string {
+  const envSuffix = params.envKey === undefined ? '' : ` (${params.envKey})`;
+  return `Workflow interpolation cannot be resolved for definition ${definitionId}: ${params.field}${envSuffix} uses \`${params.source}\`. Use has(x) ? x : '' for optional references.`;
+}
+
+/**
+ * True when a `runWorkflow` failure can never succeed on retry: the definition is gone or
+ * the subscription points at the wrong project. Callers (e.g. the trigger dispatcher) use this
+ * to skip a permanently-broken target instead of retrying it forever. Every other failure is
+ * treated as transient so at-least-once delivery can converge.
+ */
+export function isPermanentRunWorkflowError(error: unknown): boolean {
+  return (
+    error instanceof DefinitionNotFoundError ||
+    error instanceof ProjectMismatchError ||
+    error instanceof AgentConfigUnresolvableError ||
+    error instanceof AgentIntegrationMaterializationError ||
+    error instanceof InterpolationUnresolvableError ||
+    error instanceof InvalidJobRunnerLabelsError
+  );
+}
+
+export class JobNotFoundError extends Error {
+  constructor(jobId: string) {
+    super(`Job not found or has no steps: ${jobId}`);
+    this.name = 'JobNotFoundError';
+  }
+}
+
+export class JobLeaseNotActiveError extends Error {
+  constructor(readonly jobExecutionId: string) {
+    super(`Job lease is no longer active: ${jobExecutionId}`);
+    this.name = 'JobLeaseNotActiveError';
+  }
+}
+
+export class InvalidJobRunnerLabelsError extends Error {
+  constructor(readonly labels: readonly string[]) {
+    super(`Job runner labels are invalid: ${labels.join(', ')}`);
+    this.name = 'InvalidJobRunnerLabelsError';
+  }
+}
+
+// The job named by a lease is terminal, so it must not exchange its lease for
+// fresh checkout credentials. Server state is the final gate, not the token.
+export class JobNotActiveError extends Error {
+  constructor(
+    readonly jobId: string,
+    readonly status: JobStatus,
+  ) {
+    super(`Job ${jobId} is ${status} and cannot mint checkout credentials`);
+    this.name = 'JobNotActiveError';
+  }
+}
+
+export class WorkflowRunNotFoundError extends Error {
+  constructor(workflowRunId: string) {
+    super(`Workflow run not found: ${workflowRunId}`);
+    this.name = 'WorkflowRunNotFoundError';
+  }
+}
+
+export class WorkflowRunNotCancellableError extends Error {
+  constructor(
+    readonly workflowRunId: string,
+    readonly status: WorkflowRunStatus,
+  ) {
+    super(`Workflow run ${workflowRunId} is ${status} and cannot be cancelled`);
+    this.name = 'WorkflowRunNotCancellableError';
+  }
+}
+
+export class SourceRunNotFoundError extends Error {
+  constructor(workflowRunId: string) {
+    super(`Source workflow run not found: ${workflowRunId}`);
+    this.name = 'SourceRunNotFoundError';
+  }
+}
+
+export class RunNotTerminalError extends Error {
+  constructor(workflowRunId: string) {
+    super(`Workflow run is not terminal: ${workflowRunId}`);
+    this.name = 'RunNotTerminalError';
+  }
+}
+
+export class NoFailedJobsError extends Error {
+  constructor(workflowRunId: string) {
+    super(`Workflow run has no failed or cancelled jobs to re-run: ${workflowRunId}`);
+    this.name = 'NoFailedJobsError';
+  }
+}
+
+// The run's project (and therefore its source repository) cannot be resolved, so
+// there is nothing to check out.
+export class CheckoutIntentUnresolvedError extends Error {
+  constructor(projectId: string) {
+    super(`Checkout intent unresolved: project ${projectId} not found`);
+    this.name = 'CheckoutIntentUnresolvedError';
+  }
+}
+
+export class StepNotFoundError extends Error {
+  constructor(stepId: string, jobId: string) {
+    super(`Step ${stepId} not found in job ${jobId}`);
+    this.name = 'StepNotFoundError';
+  }
+}
+
+export class StepNotRunningError extends Error {
+  constructor(stepId: string, jobId: string) {
+    super(`Step ${stepId} in job ${jobId} is not running and cannot accept a result`);
+    this.name = 'StepNotRunningError';
+  }
+}
+
+// A report whose attempt is ahead of the step's current attempt. The host
+// allocates attempt numbers, so a runner can never report one it was not
+// dispatched — this is a protocol error, not an idempotent no-op.
+export class StepAttemptAheadError extends Error {
+  constructor(
+    readonly stepId: string,
+    readonly jobId: string,
+    readonly reportedAttempt: number,
+    readonly currentAttempt: number,
+  ) {
+    super(
+      `Step ${stepId} in job ${jobId} reported attempt ${reportedAttempt} ahead of current attempt ${currentAttempt}`,
+    );
+    this.name = 'StepAttemptAheadError';
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,54 @@
+export type {Job, JobStatus} from './entities/job.js';
+export type {
+  JobListenerEvent,
+  JobListenerEventDisposition,
+} from './entities/job-listener-event.js';
+export type {Step, StepStatus} from './entities/step.js';
+export type {
+  TriggerPayload,
+  WorkflowRun,
+  WorkflowRunStatus,
+  WorkflowSourceSnapshot,
+} from './entities/workflow-run.js';
+export {
+  AgentConfigUnresolvableError,
+  AgentIntegrationMaterializationError,
+  DefinitionNotFoundError,
+  InterpolationUnresolvableError,
+  isPermanentRunWorkflowError,
+  JobNotFoundError,
+  NoFailedJobsError,
+  ProjectMismatchError,
+  RunNotTerminalError,
+  SourceRunNotFoundError,
+  StepNotFoundError,
+  StepNotRunningError,
+  WorkflowRunNotCancellableError,
+} from './errors.js';
+export type {NextStep, RecordStepResultOutcome, RecordStepResultParams} from './job-execution.js';
+export {nextStepForJob, recordStepResult} from './job-execution.js';
+export {
+  type DecideJobActivationInput,
+  type DeriveJobSuccessResult,
+  decideJobActivation,
+  deriveJobExecutionOutputs,
+  deriveJobSuccess,
+  type JobActivationDecision,
+} from './job-transition/index.js';
+export type {RunWorkflowParams} from './run-workflow.js';
+export {runWorkflow} from './run-workflow.js';
+export {
+  type MaterializedWorkflowJob,
+  type MaterializedWorkflowStep,
+  materializeWorkflowModel,
+  modelHasAgentStep,
+} from './step-config/index.js';
+export {
+  deriveInitialJobExecutionPlan,
+  deriveJobExecutionRunner,
+  materializeWorkflowRunJobs,
+} from './workflow-run-creation.js';
+export {
+  type ScheduleRuntimeDagInput,
+  scheduleRuntimeDag,
+} from './workflow-scheduling/index.js';