@shipfox/api-workflows 12.1.0 → 12.2.0

package/src/core/step-config/materialize-workflow-model.test.ts

@@ -7,10 +7,24 @@ import {
 import {parseWorkflowTemplate, planInterpolationField} from '@shipfox/expression';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
-import {AgentConfigUnresolvableError, InterpolationUnresolvableError} from '#core/errors.js';
+import {
+  AgentConfigUnresolvableError,
+  InterpolationUnresolvableError,
+  JobOutputNotJsonSafeError,
+  JobOutputTooLargeError,
+  JobOutputTooManyEntriesError,
+} from '#core/errors.js';
 import {resolveTestAgentDefaults} from '#test/fixtures/agent-inter-module.js';
 import {workflowModel} from '#test/index.js';
 import {
+  MAX_JOB_OUTPUT_ENTRIES,
+  MAX_JOB_OUTPUT_NESTING_DEPTH,
+  MAX_JOB_OUTPUT_VALUE_BYTES,
+  MAX_JOB_OUTPUTS_TOTAL_BYTES,
+  normalizeJobOutputValue,
+} from './job-output-limits.js';
+import {
+  materializeJobOutputs,
   materializeJobRunner,
   materializeWorkflowModel as materializeWorkflowModelImpl,
   modelHasAgentStep,
@@ -71,6 +85,38 @@ function creationContext(
   return {site: 'run-creation', values};
 }
 
+function outputJob(
+  outputs: Readonly<Record<string, string>>,
+  outputTypes?: WorkflowModel['jobs'][number]['outputTypes'],
+): WorkflowModel['jobs'][number] {
+  const model = workflowModel({
+    jobs: {
+      build: {
+        steps: [{key: 'collect', run: 'echo collect'}],
+        outputs,
+        ...(outputTypes === undefined ? {} : {outputTypes}),
+      },
+    },
+  });
+  const job = model.jobs[0];
+  if (!job) throw new Error('Test model created no jobs');
+  return job;
+}
+
+function outputContext(outputs: Record<string, unknown>): WorkflowEvaluationContext {
+  return {
+    site: 'execution-resolution',
+    values: {
+      steps: {
+        collect: {
+          status: 'succeeded',
+          outputs,
+        },
+      },
+    },
+  };
+}
+
 describe('materializeWorkflowModel', () => {
   it('keeps literal job names in runtime jobs', async () => {
     const model = workflowModel({
@@ -1429,3 +1475,262 @@ describe('materializeJobRunner', () => {
     expect(act).toThrow('Job runner labels are invalid: not valid');
   });
 });
+
+describe('materializeJobOutputs', () => {
+  it('preserves structured values from typed single-expression mappings', () => {
+    const value = [{severity: 'high'}, {severity: 'medium'}];
+    const job = outputJob(
+      {findings: template('steps.collect.outputs.findings')},
+      {
+        findings: {
+          kind: 'list',
+          element: {kind: 'object', fields: {severity: 'string'}},
+        },
+      },
+    );
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({findings: value}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({findings: value});
+  });
+
+  it('preserves number and boolean values from typed mappings', () => {
+    const job = outputJob(
+      {
+        count: template('steps.collect.outputs.count'),
+        ready: template('steps.collect.outputs.ready'),
+      },
+      {count: 'double', ready: 'bool'},
+    );
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({count: 42, ready: true}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({count: 42, ready: true});
+  });
+
+  it('normalizes typed integer values into JSON-safe values', () => {
+    const job = outputJob(
+      {
+        count: template('steps.collect.outputs.count'),
+        preciseCount: template('steps.collect.outputs.preciseCount'),
+      },
+      {count: 'int', preciseCount: 'int'},
+    );
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({count: 42n, preciseCount: 9007199254740993n}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({count: 42, preciseCount: '9007199254740993'});
+    expect(JSON.parse(JSON.stringify(result))).toEqual(result);
+  });
+
+  it('normalizes typed timestamps into JSON-safe ISO strings', () => {
+    const job = outputJob(
+      {createdAt: template('steps.collect.outputs.createdAt')},
+      {createdAt: 'timestamp'},
+    );
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({createdAt: new Date('2026-08-06T12:34:56.000Z')}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({createdAt: '2026-08-06T12:34:56.000Z'});
+    expect(JSON.parse(JSON.stringify(result))).toEqual(result);
+  });
+
+  it('stringifies mixed templates', () => {
+    const job = outputJob({value: `prefix-${template('steps.collect.outputs.value')}`});
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({value: 42}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({value: 'prefix-42'});
+  });
+
+  it('stringifies outputs whose inferred type is string', () => {
+    const job = outputJob({value: template('steps.collect.outputs.value')}, {value: 'string'});
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({value: 42}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({value: '42'});
+  });
+
+  it('stringifies exact mappings without an inferred type', () => {
+    const job = outputJob({value: template('steps.collect.outputs.value')});
+
+    const result = materializeJobOutputs({
+      job,
+      context: outputContext({value: {severity: 'high'}}),
+      definitionId: 'definition-1',
+    });
+
+    expect(result).toEqual({value: '{"severity":"high"}'});
+  });
+
+  it('keeps prototype-named untyped outputs as JSON strings', () => {
+    const outputs = Object.fromEntries([
+      ['toString', template('steps.collect.outputs.value')],
+      ['__proto__', template('steps.collect.outputs.value')],
+    ]);
+
+    const result = materializeJobOutputs({
+      job: outputJob(outputs),
+      context: outputContext({value: {value: 'structured'}}),
+      definitionId: 'definition-1',
+    });
+
+    expect(Object.keys(result ?? {})).toEqual(['toString', '__proto__']);
+    expect(Object.getOwnPropertyDescriptor(result ?? {}, 'toString')?.value).toBe(
+      '{"value":"structured"}',
+    );
+    expect(Object.getOwnPropertyDescriptor(result ?? {}, '__proto__')?.value).toBe(
+      '{"value":"structured"}',
+    );
+  });
+
+  it('measures structured values as JSON bytes for the per-value cap', () => {
+    const job = outputJob(
+      {payload: template('steps.collect.outputs.payload')},
+      {payload: {kind: 'list', element: 'string'}},
+    );
+    const payload = ['x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 1)];
+
+    const materialize = () =>
+      materializeJobOutputs({
+        job,
+        context: outputContext({payload}),
+        definitionId: 'definition-1',
+      });
+
+    expect(materialize).toThrow(JobOutputTooLargeError);
+    expect(materialize).toThrow(`Job output "payload" exceeds the ${MAX_JOB_OUTPUT_VALUE_BYTES}`);
+  });
+
+  it('measures string values as UTF-8 bytes for the per-value cap', () => {
+    const job = outputJob({payload: template('steps.collect.outputs.payload')});
+    const payload = 'é'.repeat(Math.ceil(MAX_JOB_OUTPUT_VALUE_BYTES / 2) + 1);
+
+    const materialize = () =>
+      materializeJobOutputs({
+        job,
+        context: outputContext({payload}),
+        definitionId: 'definition-1',
+      });
+
+    expect(materialize).toThrow(JobOutputTooLargeError);
+  });
+
+  it('rejects the total materialized job output cap', () => {
+    const keys = ['one', 'two', 'three', 'four', 'five'];
+    const outputs = Object.fromEntries(
+      keys.map((key) => [key, template(`steps.collect.outputs.${key}`)]),
+    );
+    const values = Object.fromEntries(
+      keys.map((key) => [key, 'x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES)]),
+    );
+    const job = outputJob(outputs);
+
+    const materialize = () =>
+      materializeJobOutputs({job, context: outputContext(values), definitionId: 'definition-1'});
+
+    expect(materialize).toThrow(JobOutputTooLargeError);
+    expect(materialize).toThrow(
+      `Job outputs exceed the ${MAX_JOB_OUTPUTS_TOTAL_BYTES}-byte total limit (at "four")`,
+    );
+  });
+
+  it('counts output keys and JSON encoding overhead against the total cap', () => {
+    const keys = ['a', 'b', 'c', 'd'].map((suffix) => `output${suffix}${'x'.repeat(256)}`);
+    const outputs = Object.fromEntries(
+      keys.map((key) => [key, template(`steps.collect.outputs.${key}`)]),
+    );
+    const values = Object.fromEntries(
+      keys.map((key) => [key, 'x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 16)]),
+    );
+    const job = outputJob(outputs);
+
+    const materialize = () =>
+      materializeJobOutputs({job, context: outputContext(values), definitionId: 'definition-1'});
+
+    expect(materialize).toThrow(JobOutputTooLargeError);
+    expect(materialize).toThrow(
+      `Job outputs exceed the ${MAX_JOB_OUTPUTS_TOTAL_BYTES}-byte total limit`,
+    );
+  });
+
+  it('rejects job output maps with too many entries', () => {
+    const outputs = Object.fromEntries(
+      Array.from({length: MAX_JOB_OUTPUT_ENTRIES + 1}, (_, index) => {
+        const key = `output${index}`;
+        return [key, template(`steps.collect.outputs.${key}`)];
+      }),
+    );
+    const job = outputJob(outputs);
+
+    const materialize = () =>
+      materializeJobOutputs({job, context: outputContext({}), definitionId: 'definition-1'});
+
+    expect(materialize).toThrow(JobOutputTooManyEntriesError);
+    expect(materialize).toThrow(
+      `Job outputs cannot define more than ${MAX_JOB_OUTPUT_ENTRIES} entries`,
+    );
+  });
+
+  it('rejects unsupported values with a JSON persistence error', () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    expect(() => normalizeJobOutputValue(circular, 'payload')).toThrow(JobOutputNotJsonSafeError);
+    expect(() => normalizeJobOutputValue(circular, 'payload')).toThrow(
+      'Job output "payload" cannot be persisted as JSON',
+    );
+  });
+
+  it('rejects deeply nested values with a JSON persistence error', () => {
+    let value: unknown = 'leaf';
+    for (let index = 0; index <= MAX_JOB_OUTPUT_NESTING_DEPTH; index += 1) {
+      value = {value};
+    }
+
+    expect(() => normalizeJobOutputValue(value, 'payload')).toThrow(JobOutputNotJsonSafeError);
+    expect(() => normalizeJobOutputValue(value, 'payload')).toThrow(
+      `values cannot be nested deeper than ${MAX_JOB_OUTPUT_NESTING_DEPTH} levels`,
+    );
+  });
+
+  it('fails when a typed output path is missing', () => {
+    const job = outputJob(
+      {findings: template('steps.collect.outputs.findings')},
+      {findings: {kind: 'list', element: 'string'}},
+    );
+
+    const materialize = () =>
+      materializeJobOutputs({
+        job,
+        context: outputContext({}),
+        definitionId: 'definition-1',
+      });
+
+    expect(materialize).toThrow(InterpolationUnresolvableError);
+  });
+});

package/src/core/step-config/materialize-workflow-model.ts

@@ -5,8 +5,21 @@ import type {
   AgentToolMaterializationContext,
   AgentToolMaterializationSnapshot,
 } from '#core/agent-tools.js';
-import {InvalidJobRunnerLabelsError} from '#core/errors.js';
-import {completeStepField} from './fields.js';
+import {
+  InvalidJobRunnerLabelsError,
+  JobOutputTooLargeError,
+  JobOutputTooManyEntriesError,
+} from '#core/errors.js';
+import {completeStepField, completeStepFieldWithType} from './fields.js';
+import {
+  type JsonSafeJobOutputValue,
+  jobOutputRecordEntryByteLength,
+  jobOutputValueByteLength,
+  MAX_JOB_OUTPUT_ENTRIES,
+  MAX_JOB_OUTPUT_VALUE_BYTES,
+  MAX_JOB_OUTPUTS_TOTAL_BYTES,
+  normalizeJobOutputValue,
+} from './job-output-limits.js';
 import {
   type MaterializedWorkflowStep,
   materializeJobExecutionSteps,
@@ -111,22 +124,54 @@ export function materializeJobOutputs(params: {
   readonly job: WorkflowModelJob;
   readonly context: WorkflowEvaluationContext;
   readonly definitionId: string;
-}): Record<string, string> | null {
+}): Record<string, unknown> | null {
   const outputs = params.job.outputs;
   if (outputs === undefined) return null;
 
-  return Object.fromEntries(
-    Object.entries(outputs).map(([key, template]) => [
-      key,
-      completeStepField({
-        field: 'job.outputs',
-        errorField: 'job.outputs',
-        template: {segments: template},
-        context: params.context,
-        definitionId: params.definitionId,
-      }),
-    ]),
-  );
+  const outputEntries = Object.entries(outputs);
+  if (outputEntries.length > MAX_JOB_OUTPUT_ENTRIES) {
+    throw new JobOutputTooManyEntriesError(outputEntries.length, MAX_JOB_OUTPUT_ENTRIES);
+  }
+
+  const materialized: Record<string, JsonSafeJobOutputValue> = {};
+  // This is exactly JSON.stringify(materialized): start with "{}", then add each
+  // key/value pair and its comma (except for the first entry).
+  let recordBytes = 2;
+
+  for (const [index, [key, template]] of outputEntries.entries()) {
+    const outputTypes = params.job.outputTypes;
+    const outputType =
+      outputTypes !== undefined && Object.hasOwn(outputTypes, key) ? outputTypes[key] : undefined;
+    const completionParams = {
+      field: 'job.outputs' as const,
+      errorField: 'job.outputs' as const,
+      template: {segments: template},
+      context: params.context,
+      definitionId: params.definitionId,
+    };
+    const value =
+      outputType === undefined || outputType === 'string'
+        ? completeStepField(completionParams)
+        : completeStepFieldWithType(completionParams);
+    const normalizedValue = normalizeJobOutputValue(value, key);
+    const valueBytes = jobOutputValueByteLength(normalizedValue);
+    if (valueBytes > MAX_JOB_OUTPUT_VALUE_BYTES) {
+      throw new JobOutputTooLargeError(key, MAX_JOB_OUTPUT_VALUE_BYTES, 'value');
+    }
+
+    recordBytes += (index === 0 ? 0 : 1) + jobOutputRecordEntryByteLength(key, normalizedValue);
+    Object.defineProperty(materialized, key, {
+      configurable: true,
+      enumerable: true,
+      value: normalizedValue,
+      writable: true,
+    });
+    if (recordBytes > MAX_JOB_OUTPUTS_TOTAL_BYTES) {
+      throw new JobOutputTooLargeError(key, MAX_JOB_OUTPUTS_TOTAL_BYTES, 'total');
+    }
+  }
+
+  return materialized;
 }
 
 export function modelHasAgentStep(model: WorkflowModel): boolean {

package/src/db/job-listeners.ts

@@ -27,6 +27,7 @@ import {
   applyListenerFilterSnapshots,
   assembleListenerSnapshotContext,
   type ListenerTriggerWithSnapshot,
+  listenerFilterOutputTypesForJobs,
   planListenerFilterSnapshots,
 } from '#core/step-config/assemble-run-context.js';
 import {
@@ -73,8 +74,9 @@ type JobActivatedListenerMatcher = Extract<
 function applyActivatedListenerFilterSnapshots(
   plans: Parameters<typeof applyListenerFilterSnapshots>[0],
   context: Parameters<typeof applyListenerFilterSnapshots>[1],
+  outputTypes: Parameters<typeof applyListenerFilterSnapshots>[2],
 ): JobActivatedListenerMatcher[] {
-  return applyListenerFilterSnapshots(plans, context);
+  return applyListenerFilterSnapshots(plans, context, outputTypes);
 }
 
 export async function activateJobListener(
@@ -150,6 +152,7 @@ export async function activateJobListener(
         plan: snapshotPlan,
         dependencyJobs,
       });
+      const listenerOutputTypes = listenerFilterOutputTypesForJobs(dependencyJobs);
 
       await writeWorkflowsOutboxEvent(tx, {
         type: WORKFLOWS_JOB_ACTIVATED,
@@ -158,11 +161,19 @@ export async function activateJobListener(
           workflowRunId: target.run.id,
           workspaceId: target.run.workspaceId,
           mode: 'listening',
-          on: applyActivatedListenerFilterSnapshots(snapshotPlan.on, snapshotContext),
+          on: applyActivatedListenerFilterSnapshots(
+            snapshotPlan.on,
+            snapshotContext,
+            listenerOutputTypes,
+          ),
           until:
             matchers.until === null
               ? null
-              : applyActivatedListenerFilterSnapshots(snapshotPlan.until, snapshotContext),
+              : applyActivatedListenerFilterSnapshots(
+                  snapshotPlan.until,
+                  snapshotContext,
+                  listenerOutputTypes,
+                ),
         },
       });
     }

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

@@ -1,14 +1,21 @@
 import {WORKFLOWS_JOB_EXECUTION_TIMED_OUT} from '@shipfox/api-workflows-dto';
 import {and, eq, sql} from 'drizzle-orm';
-import {buildModel, workflowRunAttemptId} from '#test/helpers/workflow-runs.js';
+import {
+  MAX_JOB_OUTPUT_ENTRIES,
+  MAX_JOB_OUTPUT_VALUE_BYTES,
+} from '#core/step-config/job-output-limits.js';
+import {buildModel, template, workflowRunAttemptId} from '#test/helpers/workflow-runs.js';
 import {db} from '../db.js';
 import {workflowsOutbox} from '../schema/outbox.js';
 import {
+  applyStepResult,
   createWorkflowRun,
   failJobExecutionAsTimedOut,
+  finishStepAttempt,
   getFirstJobExecutionByJobId,
   getJobsByWorkflowRunId,
   getStepsByJobId,
+  markStepRunning,
   resolveJobExecutionAfterLeaseExpiry,
   updateJobExecutionStatus,
 } from '../workflow-runs.js';
@@ -96,4 +103,203 @@ describe('workflow run job executions', () => {
     const jobSteps = await getStepsByJobId(job.id);
     expect(jobSteps.every((step) => step.status === 'pending')).toBe(true);
   });
+
+  test('persists a structured job output when execution succeeds', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs: {findings: template('steps.collect.outputs.findings')},
+            outputTypes: {
+              findings: {
+                kind: 'list',
+                element: {kind: 'object', fields: {severity: 'string'}},
+              },
+            },
+          },
+        },
+      }),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    if (!job) throw new Error('Expected workflow job');
+    const execution = await getFirstJobExecutionByJobId(job.id);
+    if (!execution) throw new Error('Expected job execution');
+    await finishCollectedStep(job.id, {findings: [{severity: 'high'}]});
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
+    });
+
+    expect(resolved.outputs).toEqual({findings: [{severity: 'high'}]});
+    expect(Array.isArray(resolved.outputs?.findings)).toBe(true);
+    const persisted = await getFirstJobExecutionByJobId(job.id);
+    expect(persisted?.outputs).toEqual({findings: [{severity: 'high'}]});
+  });
+
+  test('persists JSON-safe typed integer and timestamp outputs when execution succeeds', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs: {
+              count: template('steps.collect.outputs.count'),
+              createdAt: template('run.created_at'),
+            },
+            outputTypes: {count: 'int', createdAt: 'timestamp'},
+          },
+        },
+      }),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    if (!job) throw new Error('Expected workflow job');
+    const execution = await getFirstJobExecutionByJobId(job.id);
+    if (!execution) throw new Error('Expected job execution');
+    await finishCollectedStep(job.id, {count: 42});
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
+    });
+
+    expect(resolved.outputs).toEqual({count: 42, createdAt: run.createdAt.toISOString()});
+    const persisted = await getFirstJobExecutionByJobId(job.id);
+    expect(persisted?.outputs).toEqual({count: 42, createdAt: run.createdAt.toISOString()});
+  });
+
+  test('fails a successful execution when a materialized job output is too large', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs: {payload: template('steps.collect.outputs.payload')},
+            outputTypes: {payload: {kind: 'list', element: 'string'}},
+          },
+        },
+      }),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    if (!job) throw new Error('Expected workflow job');
+    const execution = await getFirstJobExecutionByJobId(job.id);
+    if (!execution) throw new Error('Expected job execution');
+    await finishCollectedStep(job.id, {
+      payload: ['x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 1)],
+    });
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
+    });
+
+    expect(resolved).toMatchObject({status: 'failed', statusReason: 'unknown', outputs: null});
+  });
+
+  test('fails a successful execution when the persisted model has too many job outputs', async () => {
+    const outputs = Object.fromEntries(
+      Array.from({length: MAX_JOB_OUTPUT_ENTRIES + 1}, (_, index) => {
+        const key = `output${index}`;
+        return [key, template(`steps.collect.outputs.${key}`)];
+      }),
+    );
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs,
+          },
+        },
+      }),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+    const [job] = await getJobsByWorkflowRunId(run.id);
+    if (!job) throw new Error('Expected workflow job');
+    const execution = await getFirstJobExecutionByJobId(job.id);
+    if (!execution) throw new Error('Expected job execution');
+    await finishCollectedStep(job.id, {});
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
+    });
+
+    expect(resolved).toMatchObject({status: 'failed', statusReason: 'unknown', outputs: null});
+  });
 });
+
+async function finishCollectedStep(jobId: string, output: Record<string, unknown>): Promise<void> {
+  const steps = await getStepsByJobId(jobId);
+  const step = steps.find((candidate) => candidate.key === 'collect');
+  if (!step) throw new Error('Expected collect step');
+
+  await db().transaction(async (tx) => {
+    const running = await markStepRunning(
+      {jobExecutionId: step.jobExecutionId, stepId: step.id},
+      tx,
+    );
+    if (!running) throw new Error('Expected pending collect step');
+    await finishStepAttempt(
+      {
+        stepId: step.id,
+        attempt: running.currentAttempt,
+        status: 'succeeded',
+        output,
+        response: null,
+        exitCode: 0,
+        logOutcome: 'drained',
+      },
+      tx,
+    );
+    await applyStepResult(
+      {
+        jobExecutionId: step.jobExecutionId,
+        stepId: step.id,
+        status: 'succeeded',
+        error: null,
+      },
+      tx,
+    );
+  });
+}