@shipfox/api-workflows 12.1.0 → 12.3.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

@@ -1,12 +1,26 @@
 import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
-import {canonicalizeLabels, findInvalidLabels, MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
+import {findInvalidLabels, MAX_RUNNER_LABELS, resolveRunnerLabels} from '@shipfox/runner-labels';
+import {runnerCatalog} from '#config.js';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 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,
@@ -99,10 +113,11 @@ export function materializeJobRunner(params: {
       definitionId: params.definitionId,
     }),
   );
-  const labels = canonicalizeLabels([...params.job.runner, ...resolvedLabels]);
+  const requestedLabels = [...params.job.runner, ...resolvedLabels];
+  const labels = resolveRunnerLabels(requestedLabels, runnerCatalog);
   const invalidLabels = findInvalidLabels(labels);
   if (labels.length === 0 || labels.length > MAX_RUNNER_LABELS || invalidLabels.length > 0) {
-    throw new InvalidJobRunnerLabelsError(labels);
+    throw new InvalidJobRunnerLabelsError(labels, requestedLabels);
   }
   return labels;
 }
@@ -111,22 +126,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/index.ts

@@ -34,6 +34,7 @@ export type {
   JobActivationDecision,
   ListWorkflowRunsParams,
   ListWorkflowRunsResult,
+  StepAttemptDetail,
   UpdateJobExecutionStatusParams,
   UpdateJobStatusParams,
   UpdateWorkflowRunStatusParams,
@@ -58,12 +59,15 @@ export {
   getJobById,
   getJobExecutionById,
   getJobExecutionDetail,
+  getJobExecutionFailureOrigin,
   getJobExecutionsByJobId,
   getJobExecutionsByWorkflowRunAttemptId,
   getJobScope,
   getJobsByWorkflowRunAttemptId,
   getJobsByWorkflowRunId,
   getLatestAttempt,
+  getLatestJobExecutionByJobId,
+  getStepAttemptDetail,
   getStepAttempts,
   getStepAttemptsByJobIds,
   getStepById,

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,
+                ),
         },
       });
     }