@shipfox/api-workflows 2.0.0

package/src/db/workflow-runs/run-rerun.ts

@@ -0,0 +1,266 @@
+import {and, asc, eq, inArray, sql} from 'drizzle-orm';
+import {isWorkflowRunTerminal, type WorkflowRun} from '#core/entities/workflow-run.js';
+import {NoFailedJobsError, RunNotTerminalError, SourceRunNotFoundError} from '#core/errors.js';
+import {deriveJobExecutionRunner} from '#core/workflow-run-creation.js';
+import {recordWorkflowRunCreated} from '#metrics/instance.js';
+import {db, type Tx} from '../db.js';
+import {type JobExecutionDb, jobExecutions} from '../schema/job-executions.js';
+import {type JobDb, jobs} from '../schema/jobs.js';
+import {type StepDb, steps} from '../schema/steps.js';
+import {type WorkflowRunAttemptDb, workflowRunAttempts} from '../schema/workflow-run-attempts.js';
+import {toWorkflowRun, workflowRuns} from '../schema/workflow-runs.js';
+import {type MaterializedRunGraphJob, persistMaterializedRunGraph} from './run-graph.js';
+import {lockWorkflowRun} from './shared.js';
+
+export interface CreateRerunWorkflowRunParams {
+  workflowRunId: string;
+  mode: 'all' | 'failed';
+  actorUserId: string;
+}
+
+export async function createRerunWorkflowRun(
+  params: CreateRerunWorkflowRunParams,
+): Promise<WorkflowRun> {
+  const result = await db().transaction(async (tx) => {
+    const workflowRunId = params.workflowRunId;
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${workflowRunId}))`);
+
+    const sourceRow = await lockWorkflowRun(workflowRunId, tx);
+    if (!sourceRow) throw new SourceRunNotFoundError(workflowRunId);
+
+    const [sourceAttemptRow] = await tx
+      .select()
+      .from(workflowRunAttempts)
+      .where(
+        and(
+          eq(workflowRunAttempts.workflowRunId, sourceRow.id),
+          eq(workflowRunAttempts.attempt, sourceRow.currentAttempt),
+        ),
+      )
+      .limit(1)
+      .for('update');
+    if (!sourceAttemptRow) {
+      throw new Error(
+        `Current attempt ${sourceRow.currentAttempt} missing for run ${sourceRow.id}`,
+      );
+    }
+    if (!isWorkflowRunTerminal(sourceAttemptRow.status)) {
+      throw new RunNotTerminalError(sourceRow.id);
+    }
+
+    const sourceJobs = await tx
+      .select()
+      .from(jobs)
+      .where(eq(jobs.workflowRunAttemptId, sourceAttemptRow.id))
+      .orderBy(asc(jobs.position), asc(jobs.id));
+
+    if (
+      params.mode === 'failed' &&
+      !sourceJobs.some((job) => job.status === 'failed' || job.status === 'cancelled')
+    ) {
+      throw new NoFailedJobsError(sourceRow.id);
+    }
+
+    const [attemptRow] = await tx
+      .select({value: sql<number>`coalesce(max(${workflowRunAttempts.attempt}), 1)`})
+      .from(workflowRunAttempts)
+      .where(eq(workflowRunAttempts.workflowRunId, sourceRow.id));
+    const attempt = Number(attemptRow?.value ?? 1) + 1;
+
+    const [newAttemptRow] = await tx
+      .insert(workflowRunAttempts)
+      .values({
+        workflowRunId: sourceRow.id,
+        attempt,
+        status: 'pending',
+        rerunMode: params.mode,
+        rerunByUserId: params.actorUserId,
+        model: sourceAttemptRow.model,
+        agentToolMaterialization: sourceAttemptRow.agentToolMaterialization,
+      })
+      .returning();
+    if (!newAttemptRow) throw new Error('Insert returned no rows');
+
+    const sourceGraph = await loadRerunSourceGraph(tx, sourceJobs);
+
+    const sourceRun = toWorkflowRun(sourceRow);
+    const graphJobs = materializeRerunGraphJobs({
+      mode: params.mode,
+      sourceRun,
+      sourceAttempt: sourceAttemptRow,
+      sourceJobs,
+      ...sourceGraph,
+    });
+    await persistMaterializedRunGraph(tx, {
+      run: sourceRun,
+      workflowRunAttempt: newAttemptRow,
+      materializedJobs: graphJobs,
+    });
+
+    const [newRunRow] = await tx
+      .update(workflowRuns)
+      .set({
+        currentAttempt: attempt,
+        status: 'pending',
+        version: sql`${workflowRuns.version} + 1`,
+        updatedAt: new Date(),
+        startedAt: null,
+        finishedAt: null,
+      })
+      .where(eq(workflowRuns.id, sourceRow.id))
+      .returning();
+    if (!newRunRow) throw new Error(`Workflow run missing after rerun: ${sourceRow.id}`);
+
+    return toWorkflowRun(newRunRow);
+  });
+
+  recordWorkflowRunCreated(result.triggerPayload.provider ?? result.triggerSource);
+
+  return result;
+}
+
+async function loadRerunSourceGraph(
+  tx: Tx,
+  sourceJobs: readonly JobDb[],
+): Promise<{
+  readonly sourceJobExecutionByJobId: ReadonlyMap<string, JobExecutionDb>;
+  readonly sourceJobByJobExecutionId: ReadonlyMap<string, JobDb>;
+  readonly sourceSteps: readonly StepDb[];
+}> {
+  const sourceJobIds = sourceJobs.map((job) => job.id);
+  const sourceJobExecutionRows =
+    sourceJobIds.length === 0
+      ? []
+      : await tx
+          .select()
+          .from(jobExecutions)
+          .where(inArray(jobExecutions.jobId, sourceJobIds))
+          .orderBy(asc(jobExecutions.jobId), asc(jobExecutions.sequence), asc(jobExecutions.id));
+  const sourceJobExecutionByJobId = new Map<string, JobExecutionDb>();
+  for (const jobExecution of sourceJobExecutionRows) {
+    if (!sourceJobExecutionByJobId.has(jobExecution.jobId)) {
+      sourceJobExecutionByJobId.set(jobExecution.jobId, jobExecution);
+    }
+  }
+
+  const sourceJobExecutionIds = [...sourceJobExecutionByJobId.values()].map(
+    (jobExecution) => jobExecution.id,
+  );
+  const sourceSteps =
+    sourceJobExecutionIds.length === 0
+      ? []
+      : await tx
+          .select()
+          .from(steps)
+          .where(inArray(steps.jobExecutionId, sourceJobExecutionIds))
+          .orderBy(asc(steps.jobExecutionId), asc(steps.position), asc(steps.id));
+
+  const sourceJobById = new Map(sourceJobs.map((job) => [job.id, job]));
+  const sourceJobByJobExecutionId = new Map(
+    [...sourceJobExecutionByJobId.entries()].flatMap(([jobId, jobExecution]) => {
+      const job = sourceJobById.get(jobId);
+      return job ? [[jobExecution.id, job] as const] : [];
+    }),
+  );
+
+  return {sourceJobExecutionByJobId, sourceJobByJobExecutionId, sourceSteps};
+}
+
+function materializeRerunGraphJobs(params: {
+  readonly mode: CreateRerunWorkflowRunParams['mode'];
+  readonly sourceRun: WorkflowRun;
+  readonly sourceAttempt: WorkflowRunAttemptDb;
+  readonly sourceJobs: readonly JobDb[];
+  readonly sourceJobExecutionByJobId: ReadonlyMap<string, JobExecutionDb>;
+  readonly sourceJobByJobExecutionId: ReadonlyMap<string, JobDb>;
+  readonly sourceSteps: readonly StepDb[];
+}): readonly MaterializedRunGraphJob[] {
+  const sourceModelJobByKey = new Map(
+    (params.sourceAttempt.model?.jobs ?? []).map((job) => [job.key, job]),
+  );
+  const sourceStepsByJobId = new Map<string, StepDb[]>();
+  for (const step of params.sourceSteps) {
+    const sourceJob = params.sourceJobByJobExecutionId.get(step.jobExecutionId);
+    if (!sourceJob) continue;
+    const sourceJobSteps = sourceStepsByJobId.get(sourceJob.id) ?? [];
+    sourceJobSteps.push(step);
+    sourceStepsByJobId.set(sourceJob.id, sourceJobSteps);
+  }
+
+  return params.sourceJobs.map((sourceJob) => {
+    const carriedOver = params.mode === 'failed' && sourceJob.status === 'succeeded';
+
+    return {
+      job: {
+        key: sourceJob.key,
+        name: sourceJob.name,
+        mode: sourceJob.mode,
+        status: carriedOver ? ('succeeded' as const) : ('pending' as const),
+        statusReason: null,
+        carriedOver,
+        checkoutPersistCredentials: sourceJob.checkoutPersistCredentials,
+        checkoutPermissionsContents: sourceJob.checkoutPermissionsContents,
+        success: sourceJob.success,
+        executionTimeoutMs: sourceJob.executionTimeoutMs,
+        listeningTimeoutMs: sourceJob.listeningTimeoutMs,
+        maxExecutions: sourceJob.maxExecutions,
+        onResolve: sourceJob.onResolve,
+        batchDebounceMs: sourceJob.batchDebounceMs,
+        batchMaxSize: sourceJob.batchMaxSize,
+        batchMaxWaitMs: sourceJob.batchMaxWaitMs,
+        listenerStatus: 'inactive' as const,
+        resolutionReason: null,
+        listeningOn: sourceJob.listeningOn ? [...sourceJob.listeningOn] : null,
+        listeningUntil: sourceJob.listeningUntil ? [...sourceJob.listeningUntil] : null,
+        outputs: carriedOver && sourceJob.outputs ? {...sourceJob.outputs} : null,
+        dependencies: [...sourceJob.dependencies],
+        runner: sourceJob.runner ? [...sourceJob.runner] : null,
+        position: sourceJob.position,
+      },
+      createExecution: (job) => {
+        if (job.mode === 'listening') return undefined;
+
+        const sourceExecution = params.sourceJobExecutionByJobId.get(sourceJob.id);
+        const modelJob = sourceModelJobByKey.get(job.key);
+        const executionName = sourceExecution?.name ?? `${job.key} #1`;
+        const runner =
+          carriedOver || modelJob === undefined
+            ? (sourceExecution?.runner ?? job.runner ?? null)
+            : deriveJobExecutionRunner({
+                run: params.sourceRun,
+                modelJob,
+                jobId: job.id,
+                sequence: 1,
+                executionName,
+                status: 'pending',
+              });
+
+        return {
+          sequence: 1,
+          name: executionName,
+          runner: runner ? [...runner] : null,
+          status: carriedOver ? ('succeeded' as const) : ('pending' as const),
+          statusReason: null,
+          outputs: carriedOver && sourceExecution?.outputs ? {...sourceExecution.outputs} : null,
+          ...(carriedOver ? {finishedAt: sql`now()`} : {}),
+        };
+      },
+      createSteps: () =>
+        (sourceStepsByJobId.get(sourceJob.id) ?? []).map((step) => ({
+          key: step.key,
+          name: step.name,
+          sourceLocation: step.sourceLocation,
+          status: carriedOver ? step.status : ('pending' as const),
+          statusReason: carriedOver ? step.statusReason : null,
+          type: step.type,
+          config: step.config,
+          condition: step.condition ?? null,
+          configPlan: step.configPlan,
+          authoredConfig: step.authoredConfig,
+          error: null,
+          position: step.position,
+          currentAttempt: 1,
+        })),
+    };
+  });
+}

package/src/db/workflow-runs/run-status.test.ts

@@ -0,0 +1,425 @@
+import {eq} from 'drizzle-orm';
+import {WorkflowRunNotCancellableError} from '#core/errors.js';
+import {nextStepForJob} from '#core/job-execution.js';
+import {
+  buildModel,
+  createTestRun,
+  jobTerminatedEvents,
+  runCancelledEvents,
+  runTerminatedEvents,
+  stepAttemptTerminatedEvents,
+} from '#test/helpers/workflow-runs.js';
+import {db} from '../db.js';
+import {workflowRunAttempts} from '../schema/workflow-run-attempts.js';
+import {workflowRuns} from '../schema/workflow-runs.js';
+import {
+  cancelWorkflowRun,
+  createRerunWorkflowRun,
+  createWorkflowRun,
+  getJobsByWorkflowRunId,
+  getStepsByJobId,
+  getWorkflowRunById,
+  listRunAttempts,
+  updateJobStatus,
+  updateWorkflowRunStatus,
+} from '../workflow-runs.js';
+
+describe('workflow run queries', () => {
+  let workspaceId: string;
+  let projectId: string;
+  let definitionId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    definitionId = crypto.randomUUID();
+  });
+
+  describe('updateWorkflowRunStatus', () => {
+    test('updates status and increments version', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel(),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          subscriptionId: crypto.randomUUID(),
+          userId: crypto.randomUUID(),
+        },
+      });
+
+      const updated = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: 1,
+      });
+
+      expect(updated.status).toBe('running');
+      expect(updated.version).toBe(2);
+    });
+
+    test('preserves terminal status reason when a later transition is ignored', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel(),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          subscriptionId: crypto.randomUUID(),
+          userId: crypto.randomUUID(),
+        },
+      });
+      const job = (await getJobsByWorkflowRunId(run.id))[0];
+
+      const skipped = await updateJobStatus({
+        jobId: job?.id as string,
+        status: 'skipped',
+        expectedVersion: 1,
+        statusReason: 'dependency_not_completed',
+      });
+      const retry = await updateJobStatus({
+        jobId: job?.id as string,
+        status: 'running',
+        expectedVersion: 2,
+      });
+
+      expect(skipped.statusReason).toBe('dependency_not_completed');
+      expect(retry.status).toBe('skipped');
+      expect(retry.statusReason).toBe('dependency_not_completed');
+    });
+
+    test('throws on version mismatch', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel(),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          subscriptionId: crypto.randomUUID(),
+          userId: crypto.randomUUID(),
+        },
+      });
+
+      await expect(
+        updateWorkflowRunStatus({workflowRunId: run.id, status: 'running', expectedVersion: 99}),
+      ).rejects.toThrow('Optimistic lock failure');
+    });
+
+    test('throws when run not found', async () => {
+      await expect(
+        updateWorkflowRunStatus({
+          workflowRunId: crypto.randomUUID(),
+          status: 'running',
+          expectedVersion: 1,
+        }),
+      ).rejects.toThrow('Workflow run not found');
+    });
+
+    test.each([
+      'succeeded',
+      'failed',
+      'cancelled',
+    ] as const)('writes one run-terminated event when the status becomes %s', async (status) => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+
+      await updateWorkflowRunStatus({workflowRunId: run.id, status, expectedVersion: 1});
+
+      const events = await runTerminatedEvents(run.id);
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatchObject({workflowRunId: run.id, projectId: run.projectId, status});
+    });
+
+    test('writes no run-terminated event for a non-terminal transition', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+
+      await updateWorkflowRunStatus({workflowRunId: run.id, status: 'running', expectedVersion: 1});
+
+      expect(await runTerminatedEvents(run.id)).toHaveLength(0);
+    });
+
+    test('does not mirror a non-current attempt terminal update to the run', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      const attempts = await listRunAttempts({workflowRunId: run.id, projectId});
+      const firstAttempt = attempts[0];
+      if (!firstAttempt) throw new Error('Expected initial attempt');
+      await db().insert(workflowRunAttempts).values({
+        workflowRunId: run.id,
+        attempt: 2,
+        status: 'succeeded',
+      });
+      await db()
+        .update(workflowRuns)
+        .set({currentAttempt: 2, status: 'succeeded'})
+        .where(eq(workflowRuns.id, run.id));
+
+      const staleUpdate = await updateWorkflowRunStatus({
+        workflowRunAttemptId: firstAttempt.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+
+      expect(staleUpdate.status).toBe('succeeded');
+      expect(await getWorkflowRunById(run.id)).toMatchObject({
+        status: 'succeeded',
+        currentAttempt: 2,
+      });
+      expect(await runTerminatedEvents(run.id)).toHaveLength(0);
+    });
+
+    test('idempotent retry: a second terminal update at the stale version emits once', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+
+      const first = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+      const retry = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+
+      expect(retry.version).toBe(first.version);
+      expect(await runTerminatedEvents(run.id)).toHaveLength(1);
+    });
+
+    test('terminal-tolerant mismatch: existing terminal run returns without re-emitting', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      const cancelled = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'cancelled',
+        expectedVersion: 1,
+      });
+
+      const retry = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: 1,
+      });
+
+      expect(retry.status).toBe('cancelled');
+      expect(retry.version).toBe(cancelled.version);
+      expect(await runTerminatedEvents(run.id)).toHaveLength(1);
+    });
+
+    test('terminal-tolerant match: existing terminal run cannot be revived at the current version', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      const cancelled = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'cancelled',
+        expectedVersion: 1,
+      });
+
+      const retry = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: cancelled.version,
+      });
+
+      expect(retry.status).toBe('cancelled');
+      expect(retry.version).toBe(cancelled.version);
+      expect(await getWorkflowRunById(run.id)).toMatchObject({
+        status: 'cancelled',
+        version: cancelled.version,
+      });
+      expect(await runTerminatedEvents(run.id)).toHaveLength(1);
+    });
+  });
+
+  describe('cancelWorkflowRun', () => {
+    test('cancels the run, non-terminal jobs, and only their non-terminal steps', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({
+          jobs: {
+            running: {steps: [{run: 'a'}, {run: 'b'}]},
+            succeeded: {steps: [{run: 'ok'}]},
+            skipped: {steps: [{run: 'skip'}]},
+          },
+        }),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          subscriptionId: crypto.randomUUID(),
+          userId: crypto.randomUUID(),
+        },
+      });
+      await updateWorkflowRunStatus({workflowRunId: run.id, status: 'running', expectedVersion: 1});
+      const [runningJobExecution, succeededJob, skippedJob] = await getJobsByWorkflowRunId(run.id);
+      if (!runningJobExecution || !succeededJob || !skippedJob) throw new Error('Expected jobs');
+      await updateJobStatus({jobId: runningJobExecution.id, status: 'running', expectedVersion: 1});
+      await nextStepForJob(runningJobExecution.id);
+      await updateJobStatus({jobId: succeededJob.id, status: 'succeeded', expectedVersion: 1});
+      await updateJobStatus({
+        jobId: skippedJob.id,
+        status: 'skipped',
+        expectedVersion: 1,
+        statusReason: 'dependency_not_completed',
+      });
+
+      const cancelled = await cancelWorkflowRun({workflowRunId: run.id});
+
+      expect(cancelled.status).toBe('cancelled');
+      expect(cancelled.finishedAt).not.toBeNull();
+      const [finalRunning, finalSucceeded, finalSkipped] = await getJobsByWorkflowRunId(run.id);
+      expect(finalRunning).toMatchObject({status: 'cancelled', statusReason: 'run_cancelled'});
+      expect(finalSucceeded).toMatchObject({status: 'succeeded', statusReason: null});
+      expect(finalSkipped).toMatchObject({
+        status: 'skipped',
+        statusReason: 'dependency_not_completed',
+      });
+      expect((await getStepsByJobId(runningJobExecution.id)).map((step) => step.status)).toEqual([
+        'cancelled',
+        'cancelled',
+        'cancelled',
+      ]);
+      expect(
+        (await getStepsByJobId(skippedJob.id)).every((step) => step.status === 'pending'),
+      ).toBe(true);
+      expect(await runTerminatedEvents(run.id)).toEqual([
+        expect.objectContaining({workflowRunId: run.id, projectId, status: 'cancelled'}),
+      ]);
+      expect(await runCancelledEvents(run.id)).toEqual([
+        expect.objectContaining({workflowRunId: run.id, projectId}),
+      ]);
+      expect(await jobTerminatedEvents(runningJobExecution.id)).toEqual([
+        expect.objectContaining({
+          jobId: runningJobExecution.id,
+          workflowRunId: run.id,
+          status: 'cancelled',
+          statusReason: 'run_cancelled',
+        }),
+      ]);
+      expect(await stepAttemptTerminatedEvents(runningJobExecution.id)).toHaveLength(1);
+      expect(await jobTerminatedEvents(succeededJob.id)).toHaveLength(1);
+      expect(await jobTerminatedEvents(skippedJob.id)).toHaveLength(1);
+    });
+
+    test('cancels the current rerun attempt after current_attempt moves', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      await updateWorkflowRunStatus({workflowRunId: run.id, status: 'failed', expectedVersion: 1});
+      const firstAttempt = (await listRunAttempts({workflowRunId: run.id, projectId}))[0];
+      if (!firstAttempt) throw new Error('Expected initial attempt');
+      await createRerunWorkflowRun({
+        workflowRunId: run.id,
+        mode: 'all',
+        actorUserId: crypto.randomUUID(),
+      });
+      const secondAttempt = (await listRunAttempts({workflowRunId: run.id, projectId})).find(
+        (attempt) => attempt.attempt === 2,
+      );
+      if (!secondAttempt) throw new Error('Expected rerun attempt');
+      await updateWorkflowRunStatus({workflowRunId: run.id, status: 'running', expectedVersion: 1});
+
+      await cancelWorkflowRun({workflowRunId: run.id});
+
+      expect(await runCancelledEvents(run.id)).toEqual([
+        expect.objectContaining({
+          workflowRunId: run.id,
+          workflowRunAttemptId: secondAttempt.id,
+          projectId,
+        }),
+      ]);
+      const terminatedEvents = await runTerminatedEvents(run.id);
+      expect(terminatedEvents).toHaveLength(2);
+      expect(terminatedEvents).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            workflowRunId: run.id,
+            workflowRunAttemptId: firstAttempt.id,
+            projectId,
+            status: 'failed',
+          }),
+          expect.objectContaining({
+            workflowRunId: run.id,
+            workflowRunAttemptId: secondAttempt.id,
+            projectId,
+            status: 'cancelled',
+          }),
+        ]),
+      );
+    });
+
+    test('throws without changing an already-terminal run', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      const finished = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'succeeded',
+        expectedVersion: 1,
+      });
+
+      await expect(cancelWorkflowRun({workflowRunId: run.id})).rejects.toBeInstanceOf(
+        WorkflowRunNotCancellableError,
+      );
+
+      expect(await getWorkflowRunById(run.id)).toMatchObject({
+        status: 'succeeded',
+        version: finished.version,
+      });
+      expect(await runCancelledEvents(run.id)).toHaveLength(0);
+    });
+  });
+
+  describe('run lifecycle timing', () => {
+    test('run: stamps started_at on running and preserves it through the terminal transition', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+
+      const running = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: 1,
+      });
+
+      expect(running.startedAt).not.toBeNull();
+      expect(running.finishedAt).toBeNull();
+
+      const finished = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'succeeded',
+        expectedVersion: 2,
+      });
+
+      expect(finished.finishedAt).not.toBeNull();
+      expect(finished.startedAt?.getTime()).toBe(running.startedAt?.getTime());
+    });
+
+    test('run: cancelled straight from pending has no start but a finish', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+
+      const cancelled = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'cancelled',
+        expectedVersion: 1,
+      });
+
+      expect(cancelled.startedAt).toBeNull();
+      expect(cancelled.finishedAt).not.toBeNull();
+    });
+
+    test('run: re-entering running keeps the first started_at (coalesce, not a fresh clock)', async () => {
+      const run = await createTestRun({workspaceId, projectId, definitionId});
+      const firstRunning = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: 1,
+      });
+
+      const secondRunning = await updateWorkflowRunStatus({
+        workflowRunId: run.id,
+        status: 'running',
+        expectedVersion: 2,
+      });
+
+      expect(secondRunning.startedAt?.getTime()).toBe(firstRunning.startedAt?.getTime());
+    });
+  });
+});