@shipfox/api-workflows 11.0.0 → 12.0.0

package/src/db/schema/workflow-run-attempts.ts

@@ -23,6 +23,7 @@ export const workflowRunAttempts = pgTable(
     rerunMode: workflowRunRerunModeEnum('rerun_mode'),
     rerunByUserId: uuid('rerun_by_user_id'),
     model: jsonb('model').$type<WorkflowModel | WorkflowModelSnapshot>(),
+    vars: jsonb('vars').$type<Record<string, string>>(),
     agentToolMaterialization: jsonb(
       'agent_tool_materialization',
     ).$type<AgentToolMaterializationSnapshot>(),
@@ -53,6 +54,7 @@ export function toWorkflowRunAttempt(row: WorkflowRunAttemptDb): WorkflowRunAtte
     rerunMode: row.rerunMode ?? null,
     rerunByUserId: row.rerunByUserId,
     model: row.model === null ? null : readPersistedWorkflowModel(row.model),
+    vars: row.vars ?? null,
     agentToolMaterialization: row.agentToolMaterialization ?? null,
     version: row.version,
     createdAt: row.createdAt,

package/src/db/schema/workflow-run-counters.ts

@@ -0,0 +1,13 @@
+import {integer, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export const workflowRunCounters = pgTable(
+  'workflow_run_counters',
+  {
+    definitionId: uuid('definition_id').notNull(),
+    nextNumber: integer('next_number').notNull(),
+  },
+  (table) => [uniqueIndex('workflows_wrrc_definition_id_unique').on(table.definitionId)],
+);
+
+export type WorkflowRunCounterDb = typeof workflowRunCounters.$inferSelect;

package/src/db/schema/workflow-runs.ts

@@ -16,6 +16,7 @@ import {
 import type {
   TriggerPayload,
   WorkflowRun,
+  WorkflowRunTriggerReference,
   WorkflowSourceSnapshot,
 } from '#core/entities/workflow-run.js';
 import {pgTable} from './common.js';
@@ -37,13 +38,16 @@ export const workflowRuns = pgTable(
     workspaceId: uuid('workspace_id').notNull(),
     projectId: uuid('project_id').notNull(),
     definitionId: uuid('definition_id').notNull(),
-    name: text('name').notNull(),
+    number: integer('number').notNull(),
+    name: text('name'),
+    workflowName: text('workflow_name').notNull(),
     status: workflowRunStatusEnum('status').notNull().default('pending'),
     currentAttempt: integer('current_attempt').notNull().default(1),
     triggerProvider: text('trigger_provider'),
     triggerSource: text('trigger_source').notNull(),
     triggerEvent: text('trigger_event').notNull(),
     triggerPayload: jsonb('trigger_payload').notNull().$type<TriggerPayload>(),
+    triggerReference: jsonb('trigger_reference').$type<WorkflowRunTriggerReference>(),
     inputs: jsonb('inputs').$type<Record<string, unknown>>(),
     sourceSnapshot: jsonb('source_snapshot').$type<WorkflowSourceSnapshot>(),
     triggerIdempotencyKey: text('trigger_idempotency_key'),
@@ -56,6 +60,7 @@ export const workflowRuns = pgTable(
   },
   (table) => [
     uniqueIndex('workflows_wr_trigger_idempotency_key_unique').on(table.triggerIdempotencyKey),
+    uniqueIndex('workflows_wr_definition_number_unique').on(table.definitionId, table.number),
     index('workflows_wr_project_created_id_idx').on(table.projectId, table.createdAt, table.id),
     index('workflows_wr_project_status_created_id_idx').on(
       table.projectId,
@@ -92,13 +97,17 @@ export function toWorkflowRun(row: WorkflowRunDb): WorkflowRun {
     workspaceId: row.workspaceId,
     projectId: row.projectId,
     definitionId: row.definitionId,
-    name: row.name,
+    number: row.number,
+    name: row.name ?? row.workflowName,
+    workflowName: row.workflowName,
+    nameOverride: row.name,
     status: row.status,
     currentAttempt: row.currentAttempt,
     triggerProvider: row.triggerProvider,
     triggerSource: row.triggerSource,
     triggerEvent: row.triggerEvent,
     triggerPayload: row.triggerPayload as TriggerPayload,
+    triggerReference: row.triggerReference ?? null,
     inputs: row.inputs ?? null,
     sourceSnapshot: row.sourceSnapshot ?? null,
     triggerIdempotencyKey: row.triggerIdempotencyKey,

package/src/db/workflow-runs/job-executions.ts

@@ -32,35 +32,48 @@ import {
 } from './shared.js';
 import {bulkUpdateStepStatuses, getStepsByJobExecutionIdForUpdate} from './steps.js';
 
+async function getJobExecutionFallbackName(tx: Tx, jobExecutionId: string): Promise<string> {
+  const [row] = await tx
+    .select({job: jobs})
+    .from(jobExecutions)
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
+    .where(eq(jobExecutions.id, jobExecutionId))
+    .limit(1);
+  if (!row) throw new JobNotFoundError(jobExecutionId);
+  return row.job.name ?? row.job.key;
+}
+
 export async function getJobExecutionById(id: string, tx?: Tx): Promise<JobExecution | undefined> {
   const rows = await (tx ?? db())
-    .select()
+    .select({jobExecution: jobExecutions, job: jobs})
     .from(jobExecutions)
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
     .where(eq(jobExecutions.id, id))
     .limit(1);
   const row = rows[0];
-  return row ? toJobExecution(row) : undefined;
+  return row ? toJobExecution(row.jobExecution, row.job.name ?? row.job.key) : undefined;
 }
 
 export async function getJobExecutionsByWorkflowRunAttemptId(
   workflowRunAttemptId: string,
 ): Promise<JobExecution[]> {
   const rows = await db()
-    .select({jobExecution: jobExecutions})
+    .select({jobExecution: jobExecutions, job: jobs})
     .from(jobExecutions)
     .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
     .where(eq(jobs.workflowRunAttemptId, workflowRunAttemptId))
     .orderBy(asc(jobExecutions.sequence), asc(jobExecutions.id));
-  return rows.map((row) => toJobExecution(row.jobExecution));
+  return rows.map((row) => toJobExecution(row.jobExecution, row.job.name ?? row.job.key));
 }
 
 export async function getJobExecutionsByJobId(jobId: string): Promise<JobExecution[]> {
   const rows = await db()
-    .select()
+    .select({jobExecution: jobExecutions, job: jobs})
     .from(jobExecutions)
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
     .where(eq(jobExecutions.jobId, jobId))
     .orderBy(asc(jobExecutions.sequence), asc(jobExecutions.id));
-  return rows.map(toJobExecution);
+  return rows.map((row) => toJobExecution(row.jobExecution, row.job.name ?? row.job.key));
 }
 
 export async function getFirstJobExecutionByJobId(
@@ -68,13 +81,14 @@ export async function getFirstJobExecutionByJobId(
   tx?: Tx,
 ): Promise<JobExecution | undefined> {
   const rows = await (tx ?? db())
-    .select()
+    .select({jobExecution: jobExecutions, job: jobs})
     .from(jobExecutions)
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
     .where(eq(jobExecutions.jobId, jobId))
     .orderBy(asc(jobExecutions.sequence), asc(jobExecutions.id))
     .limit(1);
   const row = rows[0];
-  return row ? toJobExecution(row) : undefined;
+  return row ? toJobExecution(row.jobExecution, row.job.name ?? row.job.key) : undefined;
 }
 
 export async function getLatestJobExecutionByJobId(
@@ -82,13 +96,14 @@ export async function getLatestJobExecutionByJobId(
   tx?: Tx,
 ): Promise<JobExecution | undefined> {
   const rows = await (tx ?? db())
-    .select()
+    .select({jobExecution: jobExecutions, job: jobs})
     .from(jobExecutions)
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
     .where(eq(jobExecutions.jobId, jobId))
     .orderBy(desc(jobExecutions.sequence), desc(jobExecutions.id))
     .limit(1);
   const row = rows[0];
-  return row ? toJobExecution(row) : undefined;
+  return row ? toJobExecution(row.jobExecution, row.job.name ?? row.job.key) : undefined;
 }
 
 export interface UpdateJobExecutionStatusAtVersionParams {
@@ -129,10 +144,14 @@ async function resolveJobExecutionOutputs(
     .from(jobExecutions)
     .where(eq(jobExecutions.jobId, target.job.id))
     .orderBy(asc(jobExecutions.sequence), asc(jobExecutions.id));
+  const fallbackName = target.job.name ?? target.job.key;
   const executions = executionRows.map((row) =>
     row.id === target.execution.id
-      ? toJobExecution({...row, status: params.status, statusReason: params.statusReason})
-      : toJobExecution(row),
+      ? toJobExecution(
+          {...row, status: params.status, statusReason: params.statusReason},
+          fallbackName,
+        )
+      : toJobExecution(row, fallbackName),
   );
   const jobExecution = executions.find((execution) => execution.id === target.execution.id);
   if (!jobExecution) throw new JobNotFoundError(params.jobExecutionId);
@@ -217,7 +236,10 @@ async function updateJobExecutionStatusAtVersion(
 
   const row = rows[0];
   if (!row) return null;
-  return {execution: toJobExecution(row), changed: true};
+  return {
+    execution: toJobExecution(row, await getJobExecutionFallbackName(tx, row.id)),
+    changed: true,
+  };
 }
 
 export interface UpdateJobExecutionStatusParams {
@@ -250,7 +272,7 @@ export async function updateJobExecutionStatus(
             .where(eq(jobExecutions.id, params.jobExecutionId))
             .limit(1)
         )[0];
-        return row ? toJobExecution(row) : undefined;
+        return row ? toJobExecution(row, await getJobExecutionFallbackName(tx, row.id)) : undefined;
       },
       matchFn: (execution) =>
         (execution.status === params.status && execution.statusReason === statusReason) ||
@@ -317,7 +339,7 @@ export async function failJobExecutionAsTimedOut(params: {
             .where(eq(jobExecutions.id, params.jobExecutionId))
             .limit(1)
         )[0];
-        return row ? toJobExecution(row) : undefined;
+        return row ? toJobExecution(row, await getJobExecutionFallbackName(tx, row.id)) : undefined;
       },
       matchFn: (execution) => (execution.timedOutAt !== null ? {execution, changed: false} : null),
       failureMessage: `Optimistic lock failure: job execution ${params.jobExecutionId} version ${params.expectedVersion}`,

package/src/db/workflow-runs/jobs.ts

@@ -4,6 +4,7 @@ import {and, asc, desc, eq, inArray, notInArray, sql} from 'drizzle-orm';
 import {isJobTerminal, type Job, type JobStatus, type JobStatusReason} from '#core/entities/job.js';
 import type {JobExecution} from '#core/entities/job-execution.js';
 import type {PersistedEvaluationTraceEntry} from '#core/entities/step.js';
+import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
 import {JobNotFoundError} from '#core/errors.js';
 import {
   type DeriveJobSuccessResult,
@@ -58,11 +59,16 @@ export async function getJobById(id: string): Promise<Job | undefined> {
 export interface JobScope {
   workspaceId: string;
   projectId: string;
+  triggerReference: WorkflowRunTriggerReference | null;
 }
 
 export async function getJobScope(jobId: string): Promise<JobScope | undefined> {
   const rows = await db()
-    .select({workspaceId: workflowRuns.workspaceId, projectId: workflowRuns.projectId})
+    .select({
+      workspaceId: workflowRuns.workspaceId,
+      projectId: workflowRuns.projectId,
+      triggerReference: workflowRuns.triggerReference,
+    })
     .from(jobs)
     .innerJoin(workflowRunAttempts, eq(jobs.workflowRunAttemptId, workflowRunAttempts.id))
     .innerJoin(workflowRuns, eq(workflowRunAttempts.workflowRunId, workflowRuns.id))
@@ -98,7 +104,8 @@ export async function getDirectDependencyJobContexts(
       context = {job: toJob(row.job), executions: []};
       contextsByJobId.set(row.job.id, context);
     }
-    if (row.execution) context.executions.push(toJobExecution(row.execution));
+    if (row.execution)
+      context.executions.push(toJobExecution(row.execution, row.job.name ?? row.job.key));
   }
 
   return [...contextsByJobId.values()];
@@ -169,6 +176,7 @@ export async function evaluateJobActivations(
         run: toWorkflowRun(target.run),
         job,
         condition: modelJob?.if,
+        vars: target.attempt.vars ?? undefined,
         dependencies: job.dependencies.flatMap((key) => {
           const dependency = contextsByJobKey.get(key);
           return dependency === undefined ? [] : [dependency];
@@ -249,7 +257,8 @@ async function directDependencyContextsByJobKey(
       context = {job: toJob(row.job), executions: []};
       contextsByJobKey.set(row.job.key, context);
     }
-    if (row.execution) context.executions.push(toJobExecution(row.execution));
+    if (row.execution)
+      context.executions.push(toJobExecution(row.execution, row.job.name ?? row.job.key));
   }
 
   return contextsByJobKey;
@@ -383,6 +392,7 @@ export async function resolveJobStatusFromJobExecutions(params: {
       .from(jobExecutions)
       .where(eq(jobExecutions.jobId, params.jobId))
       .orderBy(asc(jobExecutions.sequence), asc(jobExecutions.id));
+    const workflowContext = await getWorkflowContextForJob(params.jobId, tx);
 
     if (jobExecutionRows.length === 0) {
       throw new Error(`Cannot resolve job ${params.jobId}: no job executions found`);
@@ -390,8 +400,11 @@ export async function resolveJobStatusFromJobExecutions(params: {
 
     const {status, statusReason, trace} = evaluateJobSuccess({
       success: jobRow.success,
-      executions: jobExecutionRows.map(toJobExecution),
+      executions: jobExecutionRows.map((execution) =>
+        toJobExecution(execution, jobRow.name ?? jobRow.key),
+      ),
       jobs: await getDirectDependencyJobContexts(params.jobId, tx),
+      vars: workflowContext.vars ?? undefined,
     });
 
     return optimisticLockRetry({

package/src/db/workflow-runs/queries.test.ts

@@ -1,3 +1,4 @@
+import {WORKFLOW_RUN_JOB_PREVIEW_LIMIT} from '@shipfox/api-workflows-dto';
 import {buildModel, createTestRun} from '#test/helpers/workflow-runs.js';
 import {
   createRerunWorkflowRun,
@@ -8,8 +9,10 @@ import {
   getWorkflowJobExecutionDepth,
   getWorkflowRunById,
   listRunAttempts,
+  listWorkflowRunJobSummaries,
   listWorkflowRunsByProject,
   updateJobExecutionStatus,
+  updateJobStatus,
   updateWorkflowRunStatus,
 } from '../workflow-runs.js';
 
@@ -136,6 +139,178 @@ describe('workflow run queries', () => {
     });
   });
 
+  describe('listWorkflowRunJobSummaries', () => {
+    test('returns jobs in graph order keyed by run, for many runs at once', async () => {
+      const model = buildModel({
+        jobs: {
+          build: {steps: [{run: 'echo build'}]},
+          test: {needs: 'build', steps: [{run: 'echo test'}]},
+        },
+      });
+      const first = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model,
+        triggerPayload: manualTrigger(),
+      });
+      const second = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model,
+        triggerPayload: manualTrigger(),
+      });
+
+      const summaries = await listWorkflowRunJobSummaries([
+        {id: first.id, currentAttempt: first.currentAttempt},
+        {id: second.id, currentAttempt: second.currentAttempt},
+      ]);
+
+      expect(summaries.get(first.id)?.preview.map((job) => job.key)).toEqual(['build', 'test']);
+      expect(summaries.get(second.id)?.preview.map((job) => job.key)).toEqual(['build', 'test']);
+    });
+
+    test('scopes jobs to the current attempt so a re-run does not stack both attempts', async () => {
+      const source = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({jobs: {build: {steps: [{run: 'echo build'}]}}}),
+        triggerPayload: manualTrigger(),
+      });
+      const [firstAttemptJob] = await getJobsByWorkflowRunId(source.id);
+      await updateWorkflowRunStatus({
+        workflowRunId: source.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+      const rerun = await createRerunWorkflowRun({
+        workflowRunId: source.id,
+        mode: 'all',
+        actorUserId: crypto.randomUUID(),
+      });
+
+      const summaries = await listWorkflowRunJobSummaries([
+        {id: source.id, currentAttempt: rerun.currentAttempt},
+      ]);
+
+      expect(rerun.currentAttempt).toBe(2);
+      expect(summaries.get(source.id)?.preview.map((job) => job.key)).toEqual(['build']);
+      expect(summaries.get(source.id)?.preview[0]?.id).not.toBe(firstAttemptJob?.id);
+    });
+
+    // The caller pins the attempt, so a re-run landing after its read still yields the jobs
+    // that belong to the metadata it is about to render, not whichever attempt is newest.
+    test('returns the caller requested attempt, not whichever is current now', async () => {
+      const source = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({jobs: {build: {steps: [{run: 'echo build'}]}}}),
+        triggerPayload: manualTrigger(),
+      });
+      const [firstAttemptJob] = await getJobsByWorkflowRunId(source.id);
+      await updateWorkflowRunStatus({
+        workflowRunId: source.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+      await createRerunWorkflowRun({
+        workflowRunId: source.id,
+        mode: 'all',
+        actorUserId: crypto.randomUUID(),
+      });
+
+      const summaries = await listWorkflowRunJobSummaries([{id: source.id, currentAttempt: 1}]);
+
+      expect(summaries.get(source.id)?.preview[0]?.id).toBe(firstAttemptJob?.id);
+    });
+
+    // The row draws a bounded strip, so the query must not hand back one row per job of a
+    // workflow that has no job limit; everything past the preview is described by counts.
+    test('caps the preview and still counts every job past it', async () => {
+      const jobCount = WORKFLOW_RUN_JOB_PREVIEW_LIMIT + 9;
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({
+          jobs: Object.fromEntries(
+            Array.from({length: jobCount}, (_, index) => [
+              `job-${String(index).padStart(2, '0')}`,
+              {steps: [{run: `echo ${index}`}]},
+            ]),
+          ),
+        }),
+        triggerPayload: manualTrigger(),
+      });
+
+      const summary = await listWorkflowRunJobSummaries([
+        {id: run.id, currentAttempt: run.currentAttempt},
+      ]);
+
+      expect(summary.get(run.id)?.preview).toHaveLength(WORKFLOW_RUN_JOB_PREVIEW_LIMIT);
+      expect(totalOf(summary.get(run.id))).toBe(jobCount);
+    });
+
+    test('counts each status the run holds, not only the previewed ones', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({
+          jobs: {build: {steps: [{run: 'echo build'}]}, test: {steps: [{run: 'echo test'}]}},
+        }),
+        triggerPayload: manualTrigger(),
+      });
+
+      const summary = await listWorkflowRunJobSummaries([
+        {id: run.id, currentAttempt: run.currentAttempt},
+      ]);
+
+      expect(summary.get(run.id)?.statusCounts).toEqual([{status: 'pending', count: 2}]);
+    });
+
+    // Checks the invariant the snapshot exists to protect: for a run inside the preview
+    // bound, the statuses drawn and the statuses counted describe the same jobs and must
+    // agree exactly. The read races a commit to give the anomaly a chance to appear, so this
+    // samples rather than proves; the guarantee itself comes from the isolation level, which
+    // no assertion here can force an interleaving against.
+    test('agrees between preview and counts while a job settles underneath', async () => {
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({
+          jobs: {build: {steps: [{run: 'echo build'}]}, test: {steps: [{run: 'echo test'}]}},
+        }),
+        triggerPayload: manualTrigger(),
+      });
+      const [firstJob] = await getJobsByWorkflowRunId(run.id);
+      if (!firstJob) throw new Error('expected the run to have jobs');
+
+      // Commits a status change while the read is in flight. A snapshot taken per statement
+      // would let one half of the answer see it and the other half miss it.
+      const settleMidRead = updateJobStatus({
+        jobId: firstJob.id,
+        status: 'failed',
+        expectedVersion: firstJob.version,
+      });
+      const [summaries] = await Promise.all([
+        listWorkflowRunJobSummaries([{id: run.id, currentAttempt: run.currentAttempt}]),
+        settleMidRead,
+      ]);
+
+      const summary = summaries.get(run.id);
+      expect(previewCounts(summary)).toEqual(statusCountMap(summary));
+    });
+
+    test('returns an empty map without querying for an empty page', async () => {
+      await expect(listWorkflowRunJobSummaries([])).resolves.toEqual(new Map());
+    });
+  });
+
   describe('listWorkflowRunsByProject', () => {
     test('returns runs ordered by creation descending', async () => {
       await createWorkflowRun({
@@ -254,3 +429,34 @@ describe('workflow run queries', () => {
     });
   });
 });
+
+function manualTrigger() {
+  return {
+    source: 'manual',
+    event: 'fire',
+    subscriptionId: crypto.randomUUID(),
+    userId: crypto.randomUUID(),
+  } as const;
+}
+
+function totalOf(summary: {statusCounts: Array<{count: number}>} | undefined): number {
+  return (summary?.statusCounts ?? []).reduce((total, entry) => total + entry.count, 0);
+}
+
+/** Statuses the preview actually drew, counted. */
+function previewCounts(
+  summary: {preview: Array<{status: string}>} | undefined,
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const job of summary?.preview ?? []) counts[job.status] = (counts[job.status] ?? 0) + 1;
+  return counts;
+}
+
+/** The same shape read off the totals, so the two halves can be compared directly. */
+function statusCountMap(
+  summary: {statusCounts: Array<{status: string; count: number}>} | undefined,
+): Record<string, number> {
+  return Object.fromEntries(
+    (summary?.statusCounts ?? []).map(({status, count}) => [status, count]),
+  );
+}