@shipfox/api-workflows 11.0.0 → 12.0.0

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

@@ -1,10 +1,18 @@
-import {createWorkflowModelSnapshot, type WorkflowModel} from '@shipfox/api-definitions-dto';
+import {
+  createWorkflowModelSnapshot,
+  WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS,
+  type WorkflowModel,
+} from '@shipfox/api-definitions-dto';
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
 import type {SecretsInterModuleClient} from '@shipfox/api-secrets-dto/inter-module';
-import {analyzeContextKeyAccess, type ResolvedFieldSegment} from '@shipfox/expression';
+import {
+  analyzeContextKeyAccess,
+  type ResolvedFieldSegment,
+  type WorkflowExpression,
+} from '@shipfox/expression';
 import {logger} from '@shipfox/node-opentelemetry';
-import {eq} from 'drizzle-orm';
+import {eq, sql} from 'drizzle-orm';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import {
   createAgentToolMaterializationSnapshot,
@@ -16,15 +24,22 @@ import type {
   WorkflowSourceSnapshot,
 } from '#core/entities/workflow-run.js';
 import {InterpolationUnresolvableError} from '#core/errors.js';
+import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-reference.js';
+import {assembleCreationContext} from '#core/step-config/assemble-run-context.js';
 import type {MaterializedWorkflowJob} from '#core/step-config/materialize-workflow-model.js';
 import type {WorkflowStepTemplateDiagnostic} from '#core/step-config/resolve-step-config.js';
+import {resolveWorkflowRunName} from '#core/step-config/resolve-workflow-run-name.js';
 import {
   deriveInitialJobExecutionPlan,
   materializeWorkflowRunJobs,
 } from '#core/workflow-run-creation.js';
-import {recordWorkflowRunCreated} from '#metrics/instance.js';
-import {db} from '../db.js';
+import {
+  recordWorkflowDisplayNameResolutionDegraded,
+  recordWorkflowRunCreated,
+} from '#metrics/instance.js';
+import {db, type Tx} from '../db.js';
 import {workflowRunAttempts} from '../schema/workflow-run-attempts.js';
+import {workflowRunCounters} from '../schema/workflow-run-counters.js';
 import {toWorkflowRun, workflowRuns} from '../schema/workflow-runs.js';
 import {type MaterializedRunGraphJob, persistMaterializedRunGraph} from './run-graph.js';
 
@@ -44,6 +59,7 @@ export interface CreateWorkflowRunParams {
   name?: string | undefined;
   model: WorkflowModel;
   triggerPayload: TriggerPayload;
+  triggerConnectionId?: string | undefined;
   inputs?: Record<string, unknown> | undefined;
   sourceSnapshot?: WorkflowSourceSnapshot | null | undefined;
   triggerIdempotencyKey?: string | undefined;
@@ -54,6 +70,14 @@ export interface CreateWorkflowRunParams {
 }
 
 export async function createWorkflowRun(params: CreateWorkflowRunParams): Promise<WorkflowRun> {
+  const triggerReference = await resolveWorkflowRunTriggerReference({
+    workspaceId: params.workspaceId,
+    triggerConnectionId: params.triggerConnectionId,
+    triggerPayload: params.triggerPayload,
+    integrations: params.integrations,
+    projects: params.projects,
+  });
+  const staticName = params.name ?? params.model.name;
   const agentToolContext =
     params.integrations === undefined
       ? undefined
@@ -69,19 +93,42 @@ export async function createWorkflowRun(params: CreateWorkflowRunParams): Promis
     context: agentToolContext,
   });
   const result = await db().transaction(async (tx) => {
+    // Serialize idempotent trigger resolution separately from per-definition number
+    // allocation so a replay never consumes a number, including when two deliveries
+    // race before either run is visible.
+    if (params.triggerIdempotencyKey) {
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtext(${params.triggerIdempotencyKey}))`,
+      );
+      const existing = await tx
+        .select()
+        .from(workflowRuns)
+        .where(eq(workflowRuns.triggerIdempotencyKey, params.triggerIdempotencyKey))
+        .limit(1);
+      const existingRow = existing[0];
+      if (existingRow) return {run: toWorkflowRun(existingRow), created: false};
+    }
+
+    // Keep allocation on the existing transaction so a trigger burst cannot pin
+    // every pool connection and then wait for a second connection per run.
+    const number = await allocateWorkflowRunNumber(tx, params.definitionId);
+
     const insertResult = await tx
       .insert(workflowRuns)
       .values({
         workspaceId: params.workspaceId,
         projectId: params.projectId,
         definitionId: params.definitionId,
-        name: params.name ?? params.model.name,
+        number,
+        name: null,
+        workflowName: staticName,
         status: 'pending',
         currentAttempt: 1,
         triggerProvider: params.triggerPayload.provider ?? null,
         triggerSource: params.triggerPayload.source,
         triggerEvent: params.triggerPayload.event,
         triggerPayload: params.triggerPayload,
+        triggerReference,
         inputs: params.inputs ?? null,
         sourceSnapshot: params.sourceSnapshot ?? null,
         triggerIdempotencyKey: params.triggerIdempotencyKey ?? null,
@@ -109,7 +156,38 @@ export async function createWorkflowRun(params: CreateWorkflowRunParams): Promis
       return {run: toWorkflowRun(existingRow), created: false};
     }
 
-    const run = toWorkflowRun(runRow);
+    // Resolving run-creation templates and predicates here gives them a stable variable snapshot
+    // and interpolation access to the inserted run id. Run-name resolution is display-only and
+    // persists only a resolved override. If resolution fails, the transaction rolls back the run,
+    // jobs, steps, and outbox event together. Listening steps are resolved later when a job
+    // execution is created.
+    const provisionalRun = toWorkflowRun(runRow);
+    const oneShotJobs = params.model.jobs.filter((job) => job.mode !== 'listening');
+    const vars = await loadReferencedVariables({
+      model: params.model,
+      jobs: oneShotJobs,
+      workspaceId: params.workspaceId,
+      projectId: params.projectId,
+      definitionId: params.definitionId,
+      secrets: params.secrets,
+    });
+    const runNameResolution = resolveWorkflowRunName({
+      runName: params.model.runName,
+      context: assembleCreationContext({
+        run: provisionalRun,
+        triggerPayload: params.triggerPayload,
+        inputs: params.inputs ?? null,
+        vars,
+      }).values,
+    });
+    const [resolvedRunRow] = await tx
+      .update(workflowRuns)
+      .set({name: runNameResolution.value, updatedAt: new Date()})
+      .where(eq(workflowRuns.id, provisionalRun.id))
+      .returning();
+    if (!resolvedRunRow)
+      throw new Error(`Workflow run missing after name resolution: ${runRow.id}`);
+    const run = toWorkflowRun(resolvedRunRow);
     const [attemptRow] = await tx
       .insert(workflowRunAttempts)
       .values({
@@ -117,23 +195,12 @@ export async function createWorkflowRun(params: CreateWorkflowRunParams): Promis
         attempt: 1,
         status: 'pending',
         model: createWorkflowModelSnapshot(params.model),
+        vars,
         agentToolMaterialization,
       })
       .returning();
     if (!attemptRow) throw new Error('Insert returned no rows');
 
-    // Resolving one-shot templates here gives interpolation access to the inserted run id.
-    // If resolution fails, the transaction rolls back the run, jobs, steps, and outbox event together.
-    // Listening steps are resolved later when a job execution is created.
-    const oneShotJobs = params.model.jobs.filter((job) => job.mode !== 'listening');
-    const vars = await loadReferencedVariables({
-      model: params.model,
-      jobs: oneShotJobs,
-      workspaceId: params.workspaceId,
-      projectId: params.projectId,
-      definitionId: params.definitionId,
-      secrets: params.secrets,
-    });
     const materializedJobs = await materializeWorkflowRunJobs({
       run,
       model: params.model,
@@ -171,15 +238,49 @@ export async function createWorkflowRun(params: CreateWorkflowRunParams): Promis
       ),
     });
 
-    return {run, created: true};
+    return {
+      run,
+      created: true,
+      nameDegradation: runNameResolution.degradation,
+    };
   });
 
-  if (result.created)
+  if (result.created && result.nameDegradation !== undefined) {
+    recordWorkflowDisplayNameResolutionDegraded('workflow.run_name', result.nameDegradation.cause);
+    logger().warn(
+      {
+        workflowRunId: result.run.id,
+        definitionId: result.run.definitionId,
+        field: 'workflow.run_name',
+        cause: result.nameDegradation.cause,
+        ...(result.nameDegradation.expression === undefined
+          ? {}
+          : {expression: result.nameDegradation.expression.slice(0, 256)}),
+      },
+      'Workflow run name resolution degraded to the static workflow name',
+    );
+  }
+
+  if (result.created) {
     recordWorkflowRunCreated(result.run.triggerPayload.provider ?? result.run.triggerSource);
+  }
 
   return result.run;
 }
 
+async function allocateWorkflowRunNumber(tx: Tx, definitionId: string): Promise<number> {
+  const [counterRow] = await tx
+    .insert(workflowRunCounters)
+    .values({definitionId, nextNumber: 2})
+    .onConflictDoUpdate({
+      target: workflowRunCounters.definitionId,
+      set: {nextNumber: sql`${workflowRunCounters.nextNumber} + 1`},
+    })
+    .returning({number: sql<number>`${workflowRunCounters.nextNumber} - 1`});
+  if (!counterRow) throw new Error('Run counter allocation returned no rows');
+  return counterRow.number;
+}
+
 export async function loadReferencedVariables(params: {
   readonly model: WorkflowModel;
   readonly jobs?: readonly WorkflowModelJob[] | undefined;
@@ -192,15 +293,22 @@ export async function loadReferencedVariables(params: {
   const keys = [...new Set(references.map((reference) => reference.key))].sort();
   if (keys.length === 0) return undefined;
 
-  if (!params.secrets) throw new Error('Secrets client is not configured.');
+  const requiresSecrets = (reference: ReferencedVariable) =>
+    reference.field !== 'job.execution_name' && reference.field !== 'workflow.run_name';
+  const requiredReferences = references.filter(requiresSecrets);
+  const requiredKeys = new Set(requiredReferences.map((reference) => reference.key));
+  if (!params.secrets) {
+    if (requiredKeys.size === 0) return undefined;
+    throw new Error('Secrets client is not configured.');
+  }
   const {values: vars} = await params.secrets.getVariablesByNamespace({
     workspaceId: params.workspaceId,
     projectId: params.projectId,
     namespace: '',
   });
-  const missingKey = keys.find((key) => !(key in vars));
+  const missingKey = [...requiredKeys].find((key) => !(key in vars));
   if (missingKey !== undefined) {
-    const reference = references.find((candidate) => candidate.key === missingKey);
+    const reference = requiredReferences.find((candidate) => candidate.key === missingKey);
     throw new InterpolationUnresolvableError(params.definitionId, {
       field: reference?.field ?? 'env',
       source: reference?.source ?? `vars.${missingKey}`,
@@ -208,7 +316,12 @@ export async function loadReferencedVariables(params: {
     });
   }
 
-  return vars;
+  const referencedVars: Record<string, string> = {};
+  for (const key of keys) {
+    const value = vars[key];
+    if (value !== undefined) referencedVars[key] = value;
+  }
+  return referencedVars;
 }
 
 function materializeRunGraphJobs(params: {
@@ -221,7 +334,7 @@ function materializeRunGraphJobs(params: {
     job: {
       key: job.key,
       mode: job.mode,
-      name: workflowTemplateSource(job.name),
+      name: job.name ?? null,
       status: 'pending' as const,
       checkoutPersistCredentials: job.checkout.persistCredentials,
       checkoutPermissionsContents: job.checkout.permissions.contents,
@@ -242,7 +355,7 @@ function materializeRunGraphJobs(params: {
     createExecution: (jobRow) => {
       if (jobRow.mode === 'listening') return undefined;
 
-      const fallbackName = `${jobRow.key} #1`;
+      const fallbackName = jobRow.name ?? jobRow.key;
       const modelJob = params.params.model.jobs[jobIndex];
       if (!modelJob) return undefined;
       const executionPlan = deriveInitialJobExecutionPlan({
@@ -259,7 +372,9 @@ function materializeRunGraphJobs(params: {
 
       return {
         sequence: 1,
-        name: executionPlan.name,
+        // Persist only the resolved override. The core entity supplies the
+        // static job name/key when this is null.
+        name: executionPlan.nameOverride,
         runner: [...executionPlan.runner],
         status: 'pending' as const,
         evaluationTrace:
@@ -288,12 +403,28 @@ function referencedVariables(
 ): readonly ReferencedVariable[] {
   const references: ReferencedVariable[] = [];
 
+  for (const job of model.jobs) {
+    collectPredicateVariableReferences(job.if, references);
+    collectPredicateVariableReferences(job.success, references);
+
+    for (const trigger of [...(job.listening?.on ?? []), ...(job.listening?.until ?? [])]) {
+      collectPredicateVariableReferences(trigger.filter, references);
+    }
+
+    for (const step of job.steps) {
+      collectPredicateVariableReferences(step.if, references);
+      collectPredicateVariableReferences(step.gate?.success, references);
+    }
+  }
+
+  collectFieldVariableReferences(model.runName, references, {field: 'workflow.run_name'});
+
   if (jobs.length > 0) {
     collectTemplateVariableReferences(model.templates?.env, references);
   }
 
   for (const job of jobs) {
-    collectFieldVariableReferences(job.name, references, {field: 'job.name'});
+    collectFieldVariableReferences(job.executionName, references, {field: 'job.execution_name'});
     for (const template of job.runnerTemplates ?? []) {
       collectFieldVariableReferences(template, references, {field: 'job.runner'});
     }
@@ -302,15 +433,22 @@ function referencedVariables(
 
     for (const step of job.steps) {
       collectFieldVariableReferences(step.templates?.name, references, {field: 'step.name'});
+      collectFieldVariableReferences(step.templates?.workingDirectory, references, {
+        field: 'step.working_directory',
+      });
       if (step.kind === 'run') {
         collectFieldVariableReferences(step.templates?.command, references, {field: 'run'});
         collectTemplateVariableReferences(step.templates?.env, references);
-      } else {
+      } else if (step.kind === 'agent') {
         collectFieldVariableReferences(step.templates?.prompt, references, {field: 'agent.prompt'});
         collectFieldVariableReferences(step.templates?.model, references, {field: 'agent.model'});
         collectFieldVariableReferences(step.templates?.provider, references, {
           field: 'agent.provider',
         });
+      } else if (step.kind === 'checkout') {
+        for (const [key, field] of WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS) {
+          collectFieldVariableReferences(step.checkout.templates?.[key], references, {field});
+        }
       }
     }
   }
@@ -318,6 +456,23 @@ function referencedVariables(
   return references;
 }
 
+function collectPredicateVariableReferences(
+  expression: WorkflowExpression | string | undefined,
+  references: ReferencedVariable[],
+): void {
+  if (expression === undefined) return;
+
+  const keyAccess = analyzeContextKeyAccess(expression);
+  for (const reference of keyAccess.references) {
+    if (reference.root !== 'vars') continue;
+    references.push({
+      key: reference.key,
+      field: 'env',
+      source: typeof expression === 'string' ? expression : expression.source,
+    });
+  }
+}
+
 function collectTemplateVariableReferences(
   templates: Readonly<Record<string, readonly ResolvedFieldSegment[]>> | undefined,
   references: ReferencedVariable[],
@@ -357,16 +512,6 @@ function collectFieldVariableReferences(
   }
 }
 
-function workflowTemplateSource(template: MaterializedWorkflowJob['name']): string | null {
-  if (template === undefined) return null;
-
-  return template
-    .map((segment) =>
-      segment.kind === 'literal' ? segment.value : `$${'{{'} ${segment.expression.source} ${'}}'}`,
-    )
-    .join('');
-}
-
 function logTemplateDiagnostics(params: {
   readonly workflowRunId: string;
   readonly diagnostics: readonly (WorkflowStepTemplateDiagnostic & {

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

@@ -42,6 +42,7 @@ describe('workflow run queries', () => {
   describe('createRerunWorkflowRun', () => {
     function rerunModel() {
       return buildModel({
+        runName: `Run ${template('inputs.env')}`,
         jobs: {
           build: {steps: [{run: 'echo build'}]},
           test: {needs: 'build', steps: [{run: 'echo test'}]},
@@ -112,6 +113,10 @@ describe('workflow run queries', () => {
 
       expect(rerun).toMatchObject({
         id: source.id,
+        number: source.number,
+        name: 'Run staging',
+        workflowName: 'Test Workflow',
+        nameOverride: 'Run staging',
         inputs: {env: 'staging'},
         sourceSnapshot: {content: 'name: Original\njobs: {}\n', format: 'yaml'},
       });
@@ -198,7 +203,7 @@ describe('workflow run queries', () => {
       expect(rerunAttempt?.agentToolMaterialization).toEqual(snapshot);
     });
 
-    test('reruns preserve each source job checkout policy', async () => {
+    test('reruns re-materialize each job checkout policy from the model', async () => {
       const source = await createWorkflowRun({
         workspaceId,
         projectId,
@@ -222,6 +227,12 @@ describe('workflow run queries', () => {
         },
       });
       const sourceJobs = await getJobsByWorkflowRunId(source.id);
+      const sourceJob = sourceJobs[0];
+      if (!sourceJob) throw new Error('Missing source job');
+      await db()
+        .update(jobs)
+        .set({checkoutPersistCredentials: true, checkoutPermissionsContents: 'read'})
+        .where(eq(jobs.id, sourceJob.id));
       await markJob(sourceJobs, 'build', 'failed');
       await updateWorkflowRunStatus({
         workflowRunId: source.id,
@@ -411,7 +422,7 @@ describe('workflow run queries', () => {
         model: buildModel({
           jobs: {
             deploy: {
-              name: `Deploy ${template('inputs.environment')}`,
+              executionName: `Deploy ${template('inputs.environment')}`,
               steps: [{run: 'echo deploy'}],
             },
           },
@@ -451,6 +462,54 @@ describe('workflow run queries', () => {
       expect(rerunExecution?.name).toBe('Deploy prod (attempt 1)');
     });
 
+    test('reruns preserve a null name override instead of copying the fallback', async () => {
+      const source = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel({
+          jobs: {
+            deploy: {name: 'Deploy', steps: [{run: 'echo deploy'}]},
+          },
+        }),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          subscriptionId: crypto.randomUUID(),
+          userId: crypto.randomUUID(),
+        },
+      });
+      const [sourceJob] = await getJobsByWorkflowRunId(source.id);
+      if (!sourceJob) throw new Error('Missing deploy job');
+      await markJob([sourceJob], 'deploy', 'failed');
+      const [sourceExecution] = await getJobExecutionsByJobId(sourceJob.id);
+      if (!sourceExecution) throw new Error('Missing deploy execution');
+      expect(sourceExecution.nameOverride).toBeNull();
+      expect(sourceExecution.name).toBe('Deploy');
+      await updateWorkflowRunStatus({
+        workflowRunId: source.id,
+        status: 'failed',
+        expectedVersion: 1,
+      });
+
+      const rerun = await createRerunWorkflowRun({
+        workflowRunId: source.id,
+        mode: 'all',
+        actorUserId: crypto.randomUUID(),
+      });
+
+      const [rerunJob] = await getJobsByWorkflowRunId(rerun.id);
+      if (!rerunJob) throw new Error('Missing rerun deploy job');
+      const [rerunExecution] = await getJobExecutionsByJobId(rerunJob.id);
+      expect(rerunExecution?.nameOverride).toBeNull();
+      expect(rerunExecution?.name).toBe('Deploy');
+      const [storedRerunExecution] = await db()
+        .select({name: jobExecutions.name})
+        .from(jobExecutions)
+        .where(eq(jobExecutions.jobId, rerunJob.id));
+      expect(storedRerunExecution?.name).toBeNull();
+    });
+
     test('writes one run-attempt-created outbox event for the rerun', async () => {
       const source = await createTerminalSourceRun();
 

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

@@ -77,6 +77,7 @@ export async function createRerunWorkflowRun(
         rerunMode: params.mode,
         rerunByUserId: params.actorUserId,
         model: sourceAttemptRow.model,
+        vars: sourceAttemptRow.vars,
         agentToolMaterialization: sourceAttemptRow.agentToolMaterialization,
       })
       .returning();
@@ -192,6 +193,9 @@ function materializeRerunGraphJobs(params: {
 
   return params.sourceJobs.map((sourceJob) => {
     const carriedOver = params.mode === 'failed' && sourceJob.status === 'succeeded';
+    const modelJob = sourceModelJobByKey.get(sourceJob.key);
+    const modelCheckout = modelJob?.checkout;
+    const resolvedModelCheckout = modelCheckout === false ? undefined : modelCheckout;
 
     return {
       job: {
@@ -201,8 +205,10 @@ function materializeRerunGraphJobs(params: {
         status: carriedOver ? ('succeeded' as const) : ('pending' as const),
         statusReason: null,
         carriedOver,
-        checkoutPersistCredentials: sourceJob.checkoutPersistCredentials,
-        checkoutPermissionsContents: sourceJob.checkoutPermissionsContents,
+        checkoutPersistCredentials:
+          resolvedModelCheckout?.persistCredentials ?? sourceJob.checkoutPersistCredentials,
+        checkoutPermissionsContents:
+          resolvedModelCheckout?.permissions?.contents ?? sourceJob.checkoutPermissionsContents,
         success: sourceJob.success,
         executionTimeoutMs: sourceJob.executionTimeoutMs,
         listeningTimeoutMs: sourceJob.listeningTimeoutMs,
@@ -224,8 +230,8 @@ function materializeRerunGraphJobs(params: {
         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 nameOverride = sourceExecution?.name ?? null;
+        const executionName = nameOverride ?? job.name ?? job.key;
         const runner =
           carriedOver || modelJob === undefined
             ? (sourceExecution?.runner ?? job.runner ?? null)
@@ -234,13 +240,17 @@ function materializeRerunGraphJobs(params: {
                 modelJob,
                 jobId: job.id,
                 sequence: 1,
+                nameOverride,
                 executionName,
+                jobName: job.name,
                 status: 'pending',
               });
 
         return {
           sequence: 1,
-          name: executionName,
+          // Reruns preserve the authored/resolved override, never the
+          // effective fallback exposed by the core entity.
+          name: nameOverride,
           runner: runner ? [...runner] : null,
           status: carriedOver ? ('succeeded' as const) : ('pending' as const),
           statusReason: null,

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

@@ -64,6 +64,7 @@ export async function getWorkflowContextForJob(
   workflowRunAttemptId: string;
   workspaceId: string;
   projectId: string;
+  vars: Record<string, string> | null;
 }> {
   const rows = await tx
     .select({
@@ -72,6 +73,7 @@ export async function getWorkflowContextForJob(
       workflowRunAttemptId: workflowRunAttempts.id,
       workspaceId: workflowRuns.workspaceId,
       projectId: workflowRuns.projectId,
+      vars: workflowRunAttempts.vars,
     })
     .from(jobs)
     .innerJoin(workflowRunAttempts, eq(jobs.workflowRunAttemptId, workflowRunAttempts.id))

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

@@ -379,8 +379,8 @@ export interface RewindStepsToPendingParams {
 // Restart-only: rewind every step at or after `fromPosition` back to pending,
 // clearing its result and bumping both `version` and `current_attempt` so the next
 // dispatch opens a fresh attempt. This DELIBERATELY bypasses the never-downgrade
-// guard used everywhere else — it is the one place that resurrects terminal steps
-// — so it must only be called from the durable-restart path, never the ordinary
+// guard used everywhere else. It is the one place that resurrects terminal steps,
+// so it must only be called from the durable-restart path, never the ordinary
 // report path. It must run in the same transaction as the failed-attempt write.
 export async function rewindStepsToPending(
   params: RewindStepsToPendingParams,
@@ -405,7 +405,7 @@ export async function rewindStepsToPending(
 }
 
 // Count a single step's own attempts. Used to bound the restart cap on the
-// gating step's actual executions — `steps.current_attempt` can't be used for
+// gating step's actual executions: `steps.current_attempt` can't be used for
 // the cap because a rewind also bumps it for downstream steps swept into the
 // rewind range (which would inflate a later gate's cap in a multi-gate job).
 export async function countStepAttempts(stepId: string, tx: Tx): Promise<number> {

package/src/db/workflow-runs.ts

@@ -47,6 +47,10 @@ export type {
   WorkflowRunAggregates,
   WorkflowRunCursor,
   WorkflowRunFilters,
+  WorkflowRunJobStatusCount,
+  WorkflowRunJobSummary,
+  WorkflowRunJobSummaryTarget,
+  WorkflowRunJobsSummary,
 } from './workflow-runs/queries.js';
 export {
   buildWorkflowRunListConditions,
@@ -59,6 +63,7 @@ export {
   getWorkflowRunById,
   getWorkflowRunDetail,
   listRunAttempts,
+  listWorkflowRunJobSummaries,
   listWorkflowRuns,
   listWorkflowRunsByProject,
 } from './workflow-runs/queries.js';
@@ -74,8 +79,10 @@ export {
   createRerunWorkflowRun,
   createWorkflowRun,
   failWorkflowRunAsTimedOut,
+  loadReferencedVariables,
   updateWorkflowRunStatus,
 } from './workflow-runs/runs.js';
+export {getWorkflowContextForJob} from './workflow-runs/shared.js';
 export type {
   ApplyStepResultParams,
   BulkUpdateStepStatusesParams,

package/src/metrics/instance.ts

@@ -10,6 +10,13 @@ const runCreatedCount = meter.createCounter<{provider: string}>('workflows_run_c
   description: 'Workflow runs created by bounded trigger provider',
 });
 
+const displayNameResolutionDegradedCount = meter.createCounter<{
+  field: 'workflow.run_name' | 'job.execution_name';
+  cause: 'missing_value' | 'evaluation_error' | 'empty_value' | 'sanitization';
+}>('workflows_display_name_resolution_degraded', {
+  description: 'Display-name resolution degradations by field and bounded cause',
+});
+
 const runStatusChangedCount = meter.createCounter<{status: WorkflowRunStatus}>(
   'workflows_run_status_changed',
   {description: 'Workflow run status transitions by resulting status'},
@@ -97,6 +104,13 @@ export function recordWorkflowRunCreated(provider: string): void {
   runCreatedCount.add(1, {provider});
 }
 
+export function recordWorkflowDisplayNameResolutionDegraded(
+  field: 'workflow.run_name' | 'job.execution_name',
+  cause: 'missing_value' | 'evaluation_error' | 'empty_value' | 'sanitization',
+): void {
+  displayNameResolutionDegradedCount.add(1, {field, cause});
+}
+
 export function recordWorkflowRunStatusChanged(status: WorkflowRunStatus): void {
   runStatusChangedCount.add(1, {status});
 }