@shipfox/api-workflows 12.4.0 → 12.6.0

package/drizzle/meta/_journal.json

@@ -15,6 +15,20 @@
       "when": 1785771111717,
       "tag": "0001_windy_sunfire",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1786203875223,
+      "tag": "0002_output_failure_details",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1786266649202,
+      "tag": "0003_output_invalid_reason",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "12.4.0",
+  "version": "12.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -32,7 +32,7 @@
     "@shipfox/api-integration-core-dto": "12.2.0",
     "@shipfox/api-runners-dto": "12.4.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.3.0",
+    "@shipfox/api-workflows-dto": "12.6.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",

package/src/core/entities/job-execution.ts

@@ -43,6 +43,7 @@ export interface JobExecution {
   runner: string[] | null;
   status: JobExecutionStatus;
   statusReason: JobStatusReason | null;
+  statusReasonMessage?: string | null;
   triggerEvents: WorkflowExecutionEvent[];
   outputs: Record<string, unknown> | null;
   evaluationTrace?: readonly PersistedEvaluationTraceEntry[] | null;

package/src/core/entities/job.ts

@@ -25,8 +25,10 @@ export const JOB_STATUS_REASONS = [
   'run_cancelled',
   'timed_out',
   'runner_lost',
+  'output_too_large',
   'step_failed',
   'unknown',
+  'output_invalid',
 ] as const;
 
 export type JobStatusReason = (typeof JOB_STATUS_REASONS)[number];

package/src/core/errors.test.ts

@@ -3,6 +3,7 @@ import {
   DefinitionNotFoundError,
   InvalidJobRunnerLabelsError,
   isPermanentRunWorkflowError,
+  JobOutputTooLargeError,
   ProjectMismatchError,
 } from './errors.js';
 
@@ -43,3 +44,20 @@ describe('isPermanentRunWorkflowError', () => {
     expect(result).toBe(false);
   });
 });
+
+describe('JobOutputTooLargeError', () => {
+  test('reports per-value measurements and overshoot', () => {
+    const error = new JobOutputTooLargeError('payload', 100, 150, 'value');
+
+    expect(error.name).toBe('JobOutputTooLargeError');
+    expect(error.overshootBytes).toBe(50);
+    expect(error.message).toContain('measured 150 bytes; overshoot 50 bytes');
+  });
+
+  test('reports total measurements and overshoot', () => {
+    const error = new JobOutputTooLargeError('payload', 100, 175, 'total');
+
+    expect(error.overshootBytes).toBe(75);
+    expect(error.message).toContain('measured 175 bytes; overshoot 75 bytes');
+  });
+});

package/src/core/errors.ts

@@ -148,17 +148,24 @@ export class InvalidJobRunnerLabelsError extends Error {
 }
 
 export class JobOutputTooLargeError extends Error {
+  readonly overshootBytes: number;
+
   constructor(
     readonly outputKey: string,
     readonly limitBytes: number,
+    readonly measuredBytes: number,
     readonly scope: 'value' | 'total',
   ) {
+    const overshootBytes = measuredBytes - limitBytes;
     super(
       scope === 'total'
-        ? `Job outputs exceed the ${limitBytes}-byte total limit (at "${outputKey}")`
-        : `Job output "${outputKey}" exceeds the ${limitBytes}-byte size limit`,
+        ? `Job outputs exceed the total size limit of ${limitBytes} bytes at "${outputKey}" ` +
+            `(measured ${measuredBytes} bytes; overshoot ${overshootBytes} bytes).`
+        : `Job output "${outputKey}" exceeds the per-value size limit of ${limitBytes} bytes ` +
+            `(measured ${measuredBytes} bytes; overshoot ${overshootBytes} bytes).`,
     );
     this.name = 'JobOutputTooLargeError';
+    this.overshootBytes = overshootBytes;
   }
 }
 

package/src/core/step-config/job-output-limits.ts

@@ -6,8 +6,8 @@ import {JobOutputNotJsonSafeError} from '#core/errors.js';
 
 export const MAX_JOB_OUTPUT_ENTRIES = WORKFLOW_DOCUMENT_JOB_OUTPUTS_MAX_ENTRIES;
 export const MAX_JOB_OUTPUT_NESTING_DEPTH = WORKFLOW_DOCUMENT_STEP_OUTPUT_SCHEMA_MAX_DEPTH;
-export const MAX_JOB_OUTPUTS_TOTAL_BYTES = 64 * 1024;
-export const MAX_JOB_OUTPUT_VALUE_BYTES = 16 * 1024;
+export const MAX_JOB_OUTPUTS_TOTAL_BYTES = 256 * 1024;
+export const MAX_JOB_OUTPUT_VALUE_BYTES = 64 * 1024;
 
 const textEncoder = new TextEncoder();
 

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

@@ -1614,6 +1614,7 @@ describe('materializeJobOutputs', () => {
       {payload: {kind: 'list', element: 'string'}},
     );
     const payload = ['x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 1)];
+    const measuredBytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
 
     const materialize = () =>
       materializeJobOutputs({
@@ -1623,12 +1624,16 @@ describe('materializeJobOutputs', () => {
       });
 
     expect(materialize).toThrow(JobOutputTooLargeError);
-    expect(materialize).toThrow(`Job output "payload" exceeds the ${MAX_JOB_OUTPUT_VALUE_BYTES}`);
+    expect(materialize).toThrow(
+      `Job output "payload" exceeds the per-value size limit of ${MAX_JOB_OUTPUT_VALUE_BYTES} bytes ` +
+        `(measured ${measuredBytes} bytes; overshoot ${measuredBytes - MAX_JOB_OUTPUT_VALUE_BYTES} 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 measuredBytes = Buffer.byteLength(payload, 'utf8');
 
     const materialize = () =>
       materializeJobOutputs({
@@ -1638,6 +1643,58 @@ describe('materializeJobOutputs', () => {
       });
 
     expect(materialize).toThrow(JobOutputTooLargeError);
+    expect(materialize).toThrow(
+      `Job output "payload" exceeds the per-value size limit of ${MAX_JOB_OUTPUT_VALUE_BYTES} bytes ` +
+        `(measured ${measuredBytes} bytes; overshoot ${measuredBytes - MAX_JOB_OUTPUT_VALUE_BYTES} bytes).`,
+    );
+  });
+
+  it('accepts a 64 KiB value and rejects one byte over', () => {
+    const maxValueBytes = MAX_JOB_OUTPUT_VALUE_BYTES;
+    expect(maxValueBytes).toBe(64 * 1024);
+    const job = outputJob({payload: template('steps.collect.outputs.payload')});
+    const materialize = (payload: string) =>
+      materializeJobOutputs({
+        job,
+        context: outputContext({payload}),
+        definitionId: 'definition-1',
+      });
+
+    const payload = 'x'.repeat(maxValueBytes);
+
+    expect(materialize(payload)).toEqual({payload});
+    expect(() => materialize(`${payload}x`)).toThrow(JobOutputTooLargeError);
+  });
+
+  it('accepts a serialized total at 256 KiB and rejects one byte over', () => {
+    const maxValueBytes = MAX_JOB_OUTPUT_VALUE_BYTES;
+    const maxTotalBytes = MAX_JOB_OUTPUTS_TOTAL_BYTES;
+    expect(maxValueBytes).toBe(64 * 1024);
+    expect(maxTotalBytes).toBe(256 * 1024);
+    const keys = ['one', 'two', 'three', 'four'];
+    const outputs = Object.fromEntries(
+      keys.map((key) => [key, template(`steps.collect.outputs.${key}`)]),
+    );
+    const values = {
+      one: 'x'.repeat(maxValueBytes),
+      two: 'x'.repeat(maxValueBytes),
+      three: 'x'.repeat(maxValueBytes),
+      four: 'x'.repeat(maxValueBytes - 40),
+    };
+    const job = outputJob(outputs);
+    const materialize = (contextValues: Record<string, unknown>) =>
+      materializeJobOutputs({
+        job,
+        context: outputContext(contextValues),
+        definitionId: 'definition-1',
+      });
+
+    expect(Buffer.byteLength(JSON.stringify(values), 'utf8')).toBe(maxTotalBytes);
+    expect(materialize(values)).toEqual(values);
+
+    const overLimitValues = {...values, four: `${values.four}x`};
+    expect(Buffer.byteLength(JSON.stringify(overLimitValues), 'utf8')).toBe(maxTotalBytes + 1);
+    expect(() => materialize(overLimitValues)).toThrow(JobOutputTooLargeError);
   });
 
   it('rejects the total materialized job output cap', () => {
@@ -1648,6 +1705,10 @@ describe('materializeJobOutputs', () => {
     const values = Object.fromEntries(
       keys.map((key) => [key, 'x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES)]),
     );
+    const measuredBytes = Buffer.byteLength(
+      JSON.stringify(Object.fromEntries(keys.slice(0, 4).map((key) => [key, values[key]]))),
+      'utf8',
+    );
     const job = outputJob(outputs);
 
     const materialize = () =>
@@ -1655,7 +1716,8 @@ describe('materializeJobOutputs', () => {
 
     expect(materialize).toThrow(JobOutputTooLargeError);
     expect(materialize).toThrow(
-      `Job outputs exceed the ${MAX_JOB_OUTPUTS_TOTAL_BYTES}-byte total limit (at "four")`,
+      `Job outputs exceed the total size limit of ${MAX_JOB_OUTPUTS_TOTAL_BYTES} bytes at "four" ` +
+        `(measured ${measuredBytes} bytes; overshoot ${measuredBytes - MAX_JOB_OUTPUTS_TOTAL_BYTES} bytes).`,
     );
   });
 
@@ -1667,6 +1729,7 @@ describe('materializeJobOutputs', () => {
     const values = Object.fromEntries(
       keys.map((key) => [key, 'x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 16)]),
     );
+    const measuredBytes = Buffer.byteLength(JSON.stringify(values), 'utf8');
     const job = outputJob(outputs);
 
     const materialize = () =>
@@ -1674,7 +1737,8 @@ describe('materializeJobOutputs', () => {
 
     expect(materialize).toThrow(JobOutputTooLargeError);
     expect(materialize).toThrow(
-      `Job outputs exceed the ${MAX_JOB_OUTPUTS_TOTAL_BYTES}-byte total limit`,
+      `Job outputs exceed the total size limit of ${MAX_JOB_OUTPUTS_TOTAL_BYTES} bytes at "${keys[3]}" ` +
+        `(measured ${measuredBytes} bytes; overshoot ${measuredBytes - MAX_JOB_OUTPUTS_TOTAL_BYTES} bytes).`,
     );
   });
 

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

@@ -158,7 +158,7 @@ export function materializeJobOutputs(params: {
     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');
+      throw new JobOutputTooLargeError(key, MAX_JOB_OUTPUT_VALUE_BYTES, valueBytes, 'value');
     }
 
     recordBytes += (index === 0 ? 0 : 1) + jobOutputRecordEntryByteLength(key, normalizedValue);
@@ -169,7 +169,7 @@ export function materializeJobOutputs(params: {
       writable: true,
     });
     if (recordBytes > MAX_JOB_OUTPUTS_TOTAL_BYTES) {
-      throw new JobOutputTooLargeError(key, MAX_JOB_OUTPUTS_TOTAL_BYTES, 'total');
+      throw new JobOutputTooLargeError(key, MAX_JOB_OUTPUTS_TOTAL_BYTES, recordBytes, 'total');
     }
   }
 

package/src/db/index.ts

@@ -42,6 +42,7 @@ export type {
   WorkflowJobExecutionDepthParams,
   WorkflowRunAggregates,
   WorkflowRunFilters,
+  WorkflowRunJobRawStatusCount,
   WorkflowRunJobStatusCount,
   WorkflowRunJobSummary,
   WorkflowRunJobSummaryTarget,

package/src/db/schema/job-executions.ts

@@ -42,6 +42,7 @@ export const jobExecutions = pgTable(
     runner: jsonb('runner').$type<string[]>(),
     status: jobExecutionStatusEnum('status').notNull().default('pending'),
     statusReason: jobStatusReasonEnum('status_reason'),
+    statusReasonMessage: text('status_reason_message'),
     triggerEvents: jsonb('trigger_events').notNull().default([]).$type<WorkflowExecutionEvent[]>(),
     outputs: jsonb('outputs').$type<Record<string, unknown> | null>(),
     evaluationTrace: jsonb('evaluation_trace').$type<readonly PersistedEvaluationTraceEntry[]>(),
@@ -78,6 +79,7 @@ export function toJobExecution(row: JobExecutionDb, fallbackName: string): JobEx
     runner: row.runner as string[] | null,
     status: row.status,
     statusReason: toJobStatusReason(row.statusReason),
+    statusReasonMessage: row.statusReasonMessage,
     triggerEvents: row.triggerEvents.map(normalizeWorkflowExecutionEvent),
     outputs: row.outputs,
     evaluationTrace: row.evaluationTrace ?? null,

package/src/db/schema/jobs.ts

@@ -61,6 +61,9 @@ export const jobs = pgTable(
     key: text('key').notNull(),
     mode: jobModeEnum('mode').notNull().default('one_shot'),
     name: text('name'),
+    // This is the job's execution verdict, not its runtime lifecycle. Active execution state
+    // lives on job_executions and must be read there when a surface needs to distinguish
+    // waiting from executing.
     status: jobStatusEnum('status').notNull().default('pending'),
     statusReason: jobStatusReasonEnum('status_reason'),
     carriedOver: boolean('carried_over').notNull().default(false),

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

@@ -1,5 +1,11 @@
 import {WORKFLOWS_JOB_EXECUTION_TIMED_OUT} from '@shipfox/api-workflows-dto';
 import {and, eq, sql} from 'drizzle-orm';
+import {
+  InterpolationUnresolvableError,
+  JobOutputNotJsonSafeError,
+  JobOutputTooLargeError,
+  JobOutputTooManyEntriesError,
+} from '#core/errors.js';
 import {
   MAX_JOB_OUTPUT_ENTRIES,
   MAX_JOB_OUTPUT_VALUE_BYTES,
@@ -19,6 +25,7 @@ import {
   resolveJobExecutionAfterLeaseExpiry,
   updateJobExecutionStatus,
 } from '../workflow-runs.js';
+import {classifyJobOutputFailure} from './job-executions.js';
 
 describe('workflow run job executions', () => {
   let workspaceId: string;
@@ -148,6 +155,50 @@ describe('workflow run job executions', () => {
     expect(persisted?.outputs).toEqual({findings: [{severity: 'high'}]});
   });
 
+  test('persists job outputs in the raised size band when execution succeeds', async () => {
+    const outputKeys = ['one', 'two', 'three'];
+    const outputValues = Object.fromEntries(
+      outputKeys.map((key) => [key, 'x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES)]),
+    );
+    const outputTemplates = Object.fromEntries(
+      outputKeys.map((key) => [key, template(`steps.collect.outputs.${key}`)]),
+    );
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs: outputTemplates,
+          },
+        },
+      }),
+      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, outputValues);
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
+    });
+
+    expect(resolved).toMatchObject({status: 'succeeded', outputs: outputValues});
+    const persisted = await getFirstJobExecutionByJobId(job.id);
+    expect(persisted?.outputs).toEqual(outputValues);
+  });
+
   test('persists JSON-safe typed integer and timestamp outputs when execution succeeds', async () => {
     const run = await createWorkflowRun({
       workspaceId,
@@ -214,17 +265,66 @@ describe('workflow run job executions', () => {
     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 payload = ['x'.repeat(MAX_JOB_OUTPUT_VALUE_BYTES - 1)];
+    const measuredBytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
+    await finishCollectedStep(job.id, {payload});
+
+    const resolved = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'succeeded',
+      expectedVersion: execution.version,
     });
 
+    expect(resolved).toMatchObject({
+      status: 'failed',
+      statusReason: 'output_too_large',
+      statusReasonMessage:
+        `Job output "payload" exceeds the per-value size limit of ${MAX_JOB_OUTPUT_VALUE_BYTES} bytes ` +
+        `(measured ${measuredBytes} bytes; overshoot ${measuredBytes - MAX_JOB_OUTPUT_VALUE_BYTES} bytes).`,
+      outputs: null,
+    });
+  });
+
+  test('fails a successful execution when a materialized job output cannot be resolved', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({
+        jobs: {
+          build: {
+            steps: [{key: 'collect', run: 'echo build'}],
+            outputs: {payload: template('steps.collect.outputs.missing')},
+          },
+        },
+      }),
+      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});
+    expect(resolved).toMatchObject({
+      status: 'failed',
+      statusReason: 'output_invalid',
+      statusReasonMessage: expect.stringContaining(
+        'job.outputs uses `steps.collect.outputs.missing`',
+      ),
+      outputs: null,
+    });
   });
 
   test('fails a successful execution when the persisted model has too many job outputs', async () => {
@@ -265,7 +365,52 @@ describe('workflow run job executions', () => {
       expectedVersion: execution.version,
     });
 
-    expect(resolved).toMatchObject({status: 'failed', statusReason: 'unknown', outputs: null});
+    expect(resolved).toMatchObject({
+      status: 'failed',
+      statusReason: 'output_invalid',
+      statusReasonMessage: `Job outputs cannot define more than ${MAX_JOB_OUTPUT_ENTRIES} entries (found ${MAX_JOB_OUTPUT_ENTRIES + 1})`,
+      outputs: null,
+    });
+  });
+});
+
+describe('classifyJobOutputFailure', () => {
+  test.each([
+    [
+      new InterpolationUnresolvableError('definition-1', {
+        field: 'job.outputs',
+        source: 'steps.collect.outputs.payload',
+      }),
+      'output_invalid',
+    ],
+    [new JobOutputNotJsonSafeError('payload', 'undefined is not a JSON value'), 'output_invalid'],
+    [new JobOutputTooManyEntriesError(11, 10), 'output_invalid'],
+    [new JobOutputTooLargeError('payload', 16 * 1024, 16 * 1024 + 1, 'value'), 'output_too_large'],
+  ] as const)('classifies %s with the persisted reason', (error, statusReason) => {
+    expect(classifyJobOutputFailure(error)).toMatchObject({statusReason});
+  });
+
+  test('does not classify interpolation failures outside job outputs', () => {
+    const error = new InterpolationUnresolvableError('definition-1', {
+      field: 'env',
+      source: 'event.ref',
+      envKey: 'REF',
+    });
+
+    expect(classifyJobOutputFailure(error)).toBeNull();
+  });
+
+  test('does not classify unexpected failures', () => {
+    expect(classifyJobOutputFailure(new Error('database unavailable'))).toBeNull();
+  });
+
+  test('bounds the persisted message', () => {
+    const failure = classifyJobOutputFailure(
+      new JobOutputNotJsonSafeError('payload', 'x'.repeat(4096)),
+    );
+
+    expect(failure?.statusReasonMessage).toHaveLength(2048);
+    expect(failure?.statusReasonMessage.endsWith('…')).toBe(true);
   });
 });
 

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

@@ -117,10 +117,46 @@ export interface UpdateJobExecutionStatusAtVersionParams {
   status: JobExecutionStatus;
   expectedVersion: number;
   statusReason?: JobStatusReason | null | undefined;
+  statusReasonMessage?: string | null | undefined;
   markTimedOut?: boolean;
   secrets?: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'> | undefined;
 }
 
+const MAX_STATUS_REASON_MESSAGE_LENGTH = 2048;
+
+export type JobOutputFailure = {
+  statusReason: Extract<JobStatusReason, 'output_invalid' | 'output_too_large'>;
+  statusReasonMessage: string;
+};
+
+export function classifyJobOutputFailure(error: unknown): JobOutputFailure | null {
+  if (error instanceof JobOutputTooLargeError) {
+    return {
+      statusReason: 'output_too_large',
+      statusReasonMessage: boundedStatusReasonMessage(error.message),
+    };
+  }
+
+  if (
+    (error instanceof InterpolationUnresolvableError && error.field === 'job.outputs') ||
+    error instanceof JobOutputNotJsonSafeError ||
+    error instanceof JobOutputTooManyEntriesError
+  ) {
+    return {
+      statusReason: 'output_invalid',
+      statusReasonMessage: boundedStatusReasonMessage(error.message),
+    };
+  }
+
+  return null;
+}
+
+function boundedStatusReasonMessage(message: string): string {
+  return message.length <= MAX_STATUS_REASON_MESSAGE_LENGTH
+    ? message
+    : `${message.slice(0, MAX_STATUS_REASON_MESSAGE_LENGTH - 1)}…`;
+}
+
 async function resolveJobExecutionOutputs(
   tx: Tx,
   params: {
@@ -200,6 +236,7 @@ async function updateJobExecutionStatusAtVersion(
 ): Promise<{execution: JobExecution; changed: boolean} | null> {
   let status = params.status;
   let statusReason = params.statusReason ?? null;
+  let statusReasonMessage = params.statusReasonMessage ?? null;
   let outputs: Record<string, unknown> | null | undefined;
   if (TERMINAL_EXECUTION_STATUSES.includes(status)) {
     outputs = null;
@@ -213,16 +250,11 @@ async function updateJobExecutionStatusAtVersion(
         secrets: params.secrets,
       });
     } catch (error) {
-      if (
-        !(error instanceof InterpolationUnresolvableError) &&
-        !(error instanceof JobOutputNotJsonSafeError) &&
-        !(error instanceof JobOutputTooLargeError) &&
-        !(error instanceof JobOutputTooManyEntriesError)
-      ) {
-        throw error;
-      }
+      const outputFailure = classifyJobOutputFailure(error);
+      if (outputFailure === null) throw error;
       status = 'failed';
-      statusReason = 'unknown';
+      statusReason = outputFailure.statusReason;
+      statusReasonMessage = outputFailure.statusReasonMessage;
       outputs = null;
     }
   }
@@ -232,6 +264,7 @@ async function updateJobExecutionStatusAtVersion(
     .set({
       status,
       statusReason,
+      statusReasonMessage,
       ...(outputs === undefined ? {} : {outputs}),
       version: sql`${jobExecutions.version} + 1`,
       updatedAt: new Date(),
@@ -260,6 +293,7 @@ export interface UpdateJobExecutionStatusParams {
   status: JobExecutionStatus;
   expectedVersion: number;
   statusReason?: JobStatusReason | null | undefined;
+  statusReasonMessage?: string | null | undefined;
   secrets?: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'> | undefined;
 }
 
@@ -275,6 +309,7 @@ export async function updateJobExecutionStatus(
           status: params.status,
           expectedVersion: params.expectedVersion,
           statusReason,
+          statusReasonMessage: params.statusReasonMessage,
           secrets: params.secrets,
         }),
       fetchFn: async () => {

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

@@ -518,6 +518,36 @@ describe('workflow run queries', () => {
       });
     });
 
+    test('writes execution failure details on the terminated event', async () => {
+      const {run, jobId, jobExecutionId} = await seedPendingJob();
+      const statusReasonMessage =
+        'Job output "payload" exceeds the per-value size limit of 65536 bytes (measured 65537 bytes; overshoot 1 bytes).';
+
+      await updateJobExecutionStatus({
+        jobExecutionId: jobExecutionId as string,
+        status: 'failed',
+        expectedVersion: 1,
+        statusReason: 'output_too_large',
+        statusReasonMessage,
+      });
+      await updateJobStatus({
+        jobId,
+        status: 'failed',
+        expectedVersion: 1,
+        statusReason: 'output_too_large',
+      });
+
+      const events = await jobTerminatedEvents(jobId);
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatchObject({
+        jobId,
+        workflowRunId: run.id,
+        status: 'failed',
+        statusReason: 'output_too_large',
+        statusReasonMessage,
+      });
+    });
+
     test('writes no terminated event for a non-terminal transition', async () => {
       const {jobId} = await seedPendingJob();
 

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

@@ -348,7 +348,10 @@ export async function updateJobStatusAtVersion(
   // makes the terminal fact fire exactly once across all paths.
   if (isJobTerminal(job.status)) {
     const [currentExecution] = await tx
-      .select({id: jobExecutions.id})
+      .select({
+        id: jobExecutions.id,
+        statusReasonMessage: jobExecutions.statusReasonMessage,
+      })
       .from(jobExecutions)
       .where(eq(jobExecutions.jobId, job.id))
       .orderBy(desc(jobExecutions.sequence), desc(jobExecutions.id))
@@ -363,6 +366,7 @@ export async function updateJobStatusAtVersion(
         workflowRunAttemptId: identity.workflowRunAttemptId,
         status: job.status,
         statusReason: job.statusReason,
+        statusReasonMessage: currentExecution?.statusReasonMessage ?? null,
       },
     });
   }