@shipfox/api-workflows 12.7.0 → 13.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "12.7.0",
+  "version": "13.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -25,14 +25,14 @@
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-agent-dto": "12.2.0",
+    "@shipfox/api-agent-dto": "13.1.0",
     "@shipfox/annotations-dto": "12.3.0",
     "@shipfox/api-definitions-dto": "12.3.0",
     "@shipfox/api-projects-dto": "12.2.0",
     "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-runners-dto": "12.4.0",
+    "@shipfox/api-runners-dto": "13.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.7.0",
+    "@shipfox/api-workflows-dto": "13.1.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",

package/src/core/errors.ts

@@ -38,13 +38,28 @@ export class WorkspaceNotFoundError extends Error {
   }
 }
 
+export interface AgentConfigUnresolvableErrorOptions {
+  readonly cause?: unknown;
+  readonly message?: string;
+  readonly code?: string;
+  readonly managedProviderId?: string;
+}
+
 export class AgentConfigUnresolvableError extends Error {
+  readonly code?: string | undefined;
+  readonly managedProviderId?: string | undefined;
+
   constructor(
     readonly definitionId: string,
-    options?: ErrorOptions | undefined,
+    options?: AgentConfigUnresolvableErrorOptions | undefined,
   ) {
-    super(`Agent configuration cannot be resolved for definition ${definitionId}`, options);
+    super(
+      options?.message ?? `Agent configuration cannot be resolved for definition ${definitionId}`,
+      options?.cause === undefined ? undefined : {cause: options.cause},
+    );
     this.name = 'AgentConfigUnresolvableError';
+    this.code = options?.code;
+    this.managedProviderId = options?.managedProviderId;
   }
 }
 

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

@@ -1,3 +1,7 @@
+import {
+  type AgentInterModuleClient,
+  agentInterModuleContract,
+} from '@shipfox/api-agent-dto/inter-module';
 import {
   WORKFLOWS_JOB_STEPS_SETTLED,
   WORKFLOWS_STEP_ATTEMPT_TERMINATED,
@@ -10,6 +14,7 @@ import {
   parseWorkflowTemplate,
   planInterpolationField,
 } from '@shipfox/expression';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
 import {and, eq, sql} from 'drizzle-orm';
 import {db} from '#db/db.js';
 import {workflowsOutbox} from '#db/schema/outbox.js';
@@ -322,6 +327,55 @@ describe('nextStepForJob', () => {
     });
   });
 
+  test('reports managed provider policy failures as agent config errors', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(1);
+    const pending = steps[0];
+    if (!pending) throw new Error('Expected pending step');
+    await db()
+      .update(stepsTable)
+      .set({
+        config: {},
+        configPlan: {
+          agent: {
+            prompt: {segments: [{kind: 'literal', value: 'Review the change.'}]},
+          },
+        },
+      })
+      .where(eq(stepsTable.id, pending.id));
+
+    const agent = {
+      getValidationCatalog: vi.fn(),
+      resolveAgentConfig: vi.fn().mockRejectedValue(
+        createInterModuleKnownError(
+          agentInterModuleContract.methods.resolveAgentConfig,
+          'agent-config-invalid',
+          {
+            message: 'This instance only supports provider `shipfox`.',
+            managed_provider_id: 'shipfox',
+          },
+        ),
+      ),
+      resolveRuntimeCredentials: vi.fn(),
+    } as unknown as AgentInterModuleClient;
+
+    const next = await nextStepForJob(jobId, agent);
+
+    expect(next).toEqual({kind: 'done', status: 'failed'});
+    const after = await getStepsByJobId(jobId);
+    expect(after[0]).toMatchObject({
+      status: 'failed',
+      error: {
+        message: 'This instance only supports provider `shipfox`.',
+        reason: 'agent_config_invalid',
+        field: 'agent',
+        source: 'agent',
+        code: 'workspace-providers-disabled',
+        managedProviderId: 'shipfox',
+        agentConfigIssue: 'provider_unsupported',
+      },
+    });
+  });
+
   test('all steps succeeded → {done, succeeded}', async () => {
     const {jobId, steps} = await arrangeJobWithSteps(2);
     for (const step of steps) {

package/src/core/job-execution.ts

@@ -339,11 +339,16 @@ function dispatchConfigError(error: DispatchConfigError): Record<string, unknown
     };
   }
 
+  const isManagedProviderPolicyFailure =
+    error.code === 'workspace-providers-disabled' && error.managedProviderId !== undefined;
   return {
     message: error.message,
-    reason: 'config_unresolvable',
+    reason: isManagedProviderPolicyFailure ? 'agent_config_invalid' : 'config_unresolvable',
     field: 'agent',
     source: 'agent',
+    ...(error.code === undefined ? {} : {code: error.code}),
+    ...(error.managedProviderId === undefined ? {} : {managedProviderId: error.managedProviderId}),
+    ...(isManagedProviderPolicyFailure ? {agentConfigIssue: 'provider_unsupported'} : {}),
   };
 }
 

package/src/core/step-config/agent.ts

@@ -185,7 +185,14 @@ export async function completeAgentDefaults(params: {
       isInterModuleKnownError(agentInterModuleContract.methods.resolveAgentConfig, error) &&
       error.code === 'agent-config-invalid'
     ) {
-      throw new AgentConfigUnresolvableError(params.definitionId, {cause: error});
+      const managedProviderId = error.details.managed_provider_id;
+      throw new AgentConfigUnresolvableError(params.definitionId, {
+        cause: error,
+        ...(error.details.message === undefined ? {} : {message: error.details.message}),
+        ...(managedProviderId === undefined
+          ? {}
+          : {code: 'workspace-providers-disabled', managedProviderId}),
+      });
     }
     throw error;
   }

package/src/core/step-config/complete-step-dispatch-config.test.ts

@@ -453,6 +453,43 @@ describe('completeStepDispatchConfig', () => {
     await expect(act()).rejects.toThrow(AgentConfigUnresolvableError);
   });
 
+  it('preserves managed provider policy details in unresolvable agent config errors', async () => {
+    const pending = step({
+      type: 'agent',
+      config: {},
+      configPlan: {
+        agent: {
+          prompt: plannedField('Review the change.'),
+        },
+      },
+    });
+    const failingResolver: AgentDefaultsResolver = () => {
+      throw createInterModuleKnownError(
+        agentInterModuleContract.methods.resolveAgentConfig,
+        'agent-config-invalid',
+        {
+          message: 'This instance only supports provider `shipfox`.',
+          managed_provider_id: 'shipfox',
+        },
+      );
+    };
+
+    const act = () =>
+      completeStepDispatchConfig({
+        step: pending,
+        context,
+        resolveAgentDefaults: failingResolver,
+        definitionId: 'def-1',
+      });
+
+    await expect(act()).rejects.toMatchObject({
+      name: 'AgentConfigUnresolvableError',
+      message: 'This instance only supports provider `shipfox`.',
+      code: 'workspace-providers-disabled',
+      managedProviderId: 'shipfox',
+    });
+  });
+
   it('throws when a server-side segment still survives dispatch', async () => {
     const pending = step({
       config: {},

package/src/db/index.ts

@@ -85,7 +85,7 @@ export {
   listWorkflowRunJobSummaries,
   listWorkflowRuns,
   listWorkflowRunsByProject,
-  recordJobExecutionQueuedAt,
+  queueJobExecution,
   recordJobExecutionStartedAt,
   resolveJobExecutionAfterLeaseExpiry,
   resolveJobStatusFromJobExecutions,

package/src/db/job-listeners.test.ts

@@ -15,6 +15,7 @@ import {
   drainListenerEventsIntoExecution,
   peekListenerBuffer,
   resolveJobListener,
+  settleListenerJobExecution,
 } from '#db/job-listeners.js';
 import {jobExecutions} from '#db/schema/job-executions.js';
 import {jobListenerEvents} from '#db/schema/job-listener-events.js';
@@ -22,6 +23,7 @@ import {jobs} from '#db/schema/jobs.js';
 import {workflowsOutbox} from '#db/schema/outbox.js';
 import {steps} from '#db/schema/steps.js';
 import {workflowRunAttempts} from '#db/schema/workflow-run-attempts.js';
+import {jobExecutionTerminatedEvents} from '#test/helpers/workflow-runs.js';
 import {jobFactory, workflowModel, workflowRunFactory} from '#test/index.js';
 import {getJobsByWorkflowRunId, updateJobExecutionStatus} from './workflow-runs.js';
 
@@ -127,6 +129,25 @@ function expectListeningPayload(
   expect(payload.mode).toBe('listening');
 }
 
+describe('settleListenerJobExecution', () => {
+  it('writes a terminal job-execution fact for a cancelled listener firing', async () => {
+    const job = await createListeningJob();
+    const execution = await insertExecution(job.id, 1, 'running');
+
+    await settleListenerJobExecution({jobExecutionId: execution.id, status: 'cancelled'});
+    await settleListenerJobExecution({jobExecutionId: execution.id, status: 'cancelled'});
+
+    expect(await jobExecutionTerminatedEvents(execution.id)).toEqual([
+      expect.objectContaining({
+        jobId: job.id,
+        jobExecutionId: execution.id,
+        status: 'cancelled',
+        statusReason: 'run_cancelled',
+      }),
+    ]);
+  });
+});
+
 async function createInactiveListeningJobWithMatchers(params: {
   readonly on: readonly JobListeningTrigger[];
   readonly until?: readonly JobListeningTrigger[] | null;

package/src/db/job-listeners.ts

@@ -48,6 +48,7 @@ import {
   getDirectDependencyJobContexts,
   loadReferencedVariables,
   updateJobStatusAtVersion,
+  writeJobExecutionTerminatedOutbox,
 } from './workflow-runs.js';
 
 const TERMINAL_EXECUTION_STATUSES: JobExecutionStatus[] = ['succeeded', 'failed', 'cancelled'];
@@ -481,6 +482,13 @@ export async function settleListenerJobExecution(params: {
       )
       .returning();
     if (!execution) return false;
+    await writeJobExecutionTerminatedOutbox(tx, {
+      jobId: execution.jobId,
+      jobExecutionId: execution.id,
+      status: execution.status,
+      statusReason: execution.statusReason,
+      statusReasonMessage: execution.statusReasonMessage,
+    });
     await bulkUpdateStepStatuses(
       {jobExecutionId: params.jobExecutionId, status: params.status},
       tx,
@@ -615,6 +623,16 @@ async function persistMaterializedListenerExecution(
     .returning();
   if (!execution) throw new Error('Insert returned no rows');
 
+  if (execution.status === 'failed') {
+    await writeJobExecutionTerminatedOutbox(tx, {
+      jobId: execution.jobId,
+      jobExecutionId: execution.id,
+      status: execution.status,
+      statusReason: execution.statusReason,
+      statusReasonMessage: execution.statusReasonMessage,
+    });
+  }
+
   await tx
     .update(jobListenerEvents)
     .set({consumedByExecutionId: execution.id})

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

@@ -1,4 +1,4 @@
-import {WORKFLOWS_JOB_EXECUTION_TIMED_OUT} from '@shipfox/api-workflows-dto';
+import {WORKFLOWS_JOB_EXECUTION_QUEUED} from '@shipfox/api-workflows-dto';
 import {and, eq, sql} from 'drizzle-orm';
 import {
   InterpolationUnresolvableError,
@@ -10,18 +10,23 @@ 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 {
+  buildModel,
+  jobExecutionTerminatedEvents,
+  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,
+  queueJobExecution,
   resolveJobExecutionAfterLeaseExpiry,
   updateJobExecutionStatus,
 } from '../workflow-runs.js';
@@ -38,7 +43,7 @@ describe('workflow run job executions', () => {
     definitionId = crypto.randomUUID();
   });
 
-  test('derives timeout outbox attempt identity from the job execution', async () => {
+  test('records and publishes the queue fact once', async () => {
     const run = await createWorkflowRun({
       workspaceId,
       projectId,
@@ -57,26 +62,119 @@ describe('workflow run job executions', () => {
     if (!execution) throw new Error('Expected job execution');
     const actualAttemptId = await workflowRunAttemptId(run.id);
 
-    await failJobExecutionAsTimedOut({
-      jobExecutionId: execution.id,
-      workflowRunAttemptId: crypto.randomUUID(),
-      expectedVersion: execution.version,
-    });
+    const queued = await queueJobExecution({jobExecutionId: execution.id});
+    await queueJobExecution({jobExecutionId: execution.id});
 
-    const [event] = await db()
+    const events = await db()
       .select({payload: workflowsOutbox.payload})
       .from(workflowsOutbox)
       .where(
         and(
-          eq(workflowsOutbox.eventType, WORKFLOWS_JOB_EXECUTION_TIMED_OUT),
+          eq(workflowsOutbox.eventType, WORKFLOWS_JOB_EXECUTION_QUEUED),
           sql`${workflowsOutbox.payload}->>'jobExecutionId' = ${execution.id}`,
         ),
       );
-    expect(event?.payload).toMatchObject({
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toMatchObject({
       jobId: job.id,
       jobExecutionId: execution.id,
+      workflowRunId: run.id,
       workflowRunAttemptId: actualAttemptId,
+      workspaceId,
+      projectId,
+      requiredLabels: ['ubuntu-latest'],
+      queuedAt: queued.queuedAt?.toISOString(),
+    });
+  });
+
+  test('writes one terminal fact when a job execution becomes terminal', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({jobs: {build: {steps: [{run: 'echo build'}]}}}),
+      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');
+
+    const running = await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'running',
+      expectedVersion: execution.version,
     });
+    expect(await jobExecutionTerminatedEvents(execution.id)).toHaveLength(0);
+
+    await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'cancelled',
+      expectedVersion: running.version,
+      statusReason: 'run_cancelled',
+    });
+    await updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'failed',
+      expectedVersion: running.version + 1,
+      statusReason: 'unknown',
+    });
+
+    expect(await jobExecutionTerminatedEvents(execution.id)).toEqual([
+      expect.objectContaining({
+        jobId: job.id,
+        jobExecutionId: execution.id,
+        workflowRunId: run.id,
+        status: 'cancelled',
+        statusReason: 'run_cancelled',
+      }),
+    ]);
+  });
+
+  test('does not publish a queue fact after the execution is terminal', async () => {
+    const run = await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId,
+      model: buildModel({jobs: {build: {steps: [{run: 'echo build'}]}}}),
+      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 updateJobExecutionStatus({
+      jobExecutionId: execution.id,
+      status: 'cancelled',
+      expectedVersion: execution.version,
+      statusReason: 'run_cancelled',
+    });
+    const after = await queueJobExecution({jobExecutionId: execution.id});
+
+    expect(after.status).toBe('cancelled');
+    expect(after.queuedAt).toBeNull();
+    expect(
+      await db()
+        .select()
+        .from(workflowsOutbox)
+        .where(
+          and(
+            eq(workflowsOutbox.eventType, WORKFLOWS_JOB_EXECUTION_QUEUED),
+            sql`${workflowsOutbox.payload}->>'jobExecutionId' = ${execution.id}`,
+          ),
+        ),
+    ).toHaveLength(0);
   });
 
   test('does not cancel steps when lease expiry loses the execution version race', async () => {

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

@@ -1,6 +1,6 @@
 import {readPersistedWorkflowModel} from '@shipfox/api-definitions-dto';
 import type {SecretsInterModuleClient} from '@shipfox/api-secrets-dto/inter-module';
-import {WORKFLOWS_JOB_EXECUTION_TIMED_OUT} from '@shipfox/api-workflows-dto';
+import {canonicalizeLabels} from '@shipfox/runner-labels';
 import {and, asc, desc, eq, isNull, notInArray, sql} from 'drizzle-orm';
 import type {JobStatusReason} from '#core/entities/job.js';
 import type {JobExecution, JobExecutionStatus} from '#core/entities/job-execution.js';
@@ -22,7 +22,6 @@ import {
   recordWorkflowJobExecutionTimedOut,
 } from '#metrics/instance.js';
 import {db, type Tx} from '../db.js';
-import {writeWorkflowsOutboxEvent} from '../outbox-writes.js';
 import {jobExecutions, toJobExecution} from '../schema/job-executions.js';
 import {jobs, toJob} from '../schema/jobs.js';
 import {stepAttempts, toStepAttempt} from '../schema/step-attempts.js';
@@ -30,12 +29,9 @@ import {steps, toStep} from '../schema/steps.js';
 import {workflowRunAttempts} from '../schema/workflow-run-attempts.js';
 import {toWorkflowRun, workflowRuns} from '../schema/workflow-runs.js';
 import {getDirectDependencyJobContexts} from './jobs.js';
+import {writeJobExecutionQueuedOutbox, writeJobExecutionTerminatedOutbox} from './outbox.js';
 import {loadReferencedVariables} from './runs.js';
-import {
-  getWorkflowContextForJob,
-  optimisticLockRetry,
-  TERMINAL_EXECUTION_STATUSES,
-} from './shared.js';
+import {optimisticLockRetry, TERMINAL_EXECUTION_STATUSES} from './shared.js';
 import {bulkUpdateStepStatuses, getStepsByJobExecutionIdForUpdate} from './steps.js';
 
 async function getJobExecutionFallbackName(tx: Tx, jobExecutionId: string): Promise<string> {
@@ -282,6 +278,15 @@ async function updateJobExecutionStatusAtVersion(
 
   const row = rows[0];
   if (!row) return null;
+  if (TERMINAL_EXECUTION_STATUSES.includes(row.status)) {
+    await writeJobExecutionTerminatedOutbox(tx, {
+      jobId: row.jobId,
+      jobExecutionId: row.id,
+      status: row.status,
+      statusReason: row.statusReason,
+      statusReasonMessage: row.statusReasonMessage,
+    });
+  }
   return {
     execution: toJobExecution(row, await getJobExecutionFallbackName(tx, row.id)),
     changed: true,
@@ -336,17 +341,49 @@ export async function updateJobExecutionStatus(
   return result.execution;
 }
 
-export async function recordJobExecutionQueuedAt(params: {
-  jobExecutionId: string;
-  queuedAt: Date;
-}): Promise<void> {
-  const updated = await db()
-    .update(jobExecutions)
-    .set({queuedAt: params.queuedAt})
-    .where(and(eq(jobExecutions.id, params.jobExecutionId), isNull(jobExecutions.queuedAt)))
-    .returning({id: jobExecutions.id});
+export async function queueJobExecution(params: {jobExecutionId: string}): Promise<JobExecution> {
+  const result = await db().transaction(async (tx) => {
+    const [row] = await tx
+      .select({jobExecution: jobExecutions, job: jobs})
+      .from(jobExecutions)
+      .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
+      .where(eq(jobExecutions.id, params.jobExecutionId))
+      .limit(1)
+      .for('update');
+    if (!row) throw new JobNotFoundError(params.jobExecutionId);
+
+    const existing = toJobExecution(row.jobExecution, row.job.name ?? row.job.key);
+    if (existing.queuedAt !== null || TERMINAL_EXECUTION_STATUSES.includes(existing.status)) {
+      return {execution: existing, changed: false};
+    }
+
+    const requiredLabels = [...canonicalizeLabels(existing.runner ?? row.job.runner ?? [])];
+    if (requiredLabels.length === 0) {
+      throw new Error(`Job execution ${params.jobExecutionId} has no required runner labels`);
+    }
 
-  if (updated.length > 0) recordWorkflowJobExecutionQueued();
+    const [queued] = await tx
+      .update(jobExecutions)
+      .set({queuedAt: sql`now()`})
+      .where(eq(jobExecutions.id, params.jobExecutionId))
+      .returning();
+    if (!queued?.queuedAt) throw new Error(`Cannot queue job execution ${params.jobExecutionId}`);
+
+    await writeJobExecutionQueuedOutbox(tx, {
+      jobId: queued.jobId,
+      jobExecutionId: queued.id,
+      requiredLabels,
+      queuedAt: queued.queuedAt,
+    });
+
+    return {
+      execution: toJobExecution(queued, row.job.name ?? row.job.key),
+      changed: true,
+    };
+  });
+
+  if (result.changed) recordWorkflowJobExecutionQueued();
+  return result.execution;
 }
 
 export async function recordJobExecutionStartedAt(params: {
@@ -393,18 +430,6 @@ export async function failJobExecutionAsTimedOut(params: {
       failureMessage: `Optimistic lock failure: job execution ${params.jobExecutionId} version ${params.expectedVersion}`,
     });
 
-    if (updated.changed) {
-      const identity = await getWorkflowContextForJob(updated.execution.jobId, tx);
-      await writeWorkflowsOutboxEvent(tx, {
-        type: WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
-        payload: {
-          jobId: identity.jobId,
-          jobExecutionId: params.jobExecutionId,
-          workflowRunAttemptId: identity.workflowRunAttemptId,
-        },
-      });
-    }
-
     return updated;
   });
 

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

@@ -1,16 +1,79 @@
 import {
   type LogOutcomeDto,
+  WORKFLOWS_JOB_EXECUTION_QUEUED,
+  WORKFLOWS_JOB_EXECUTION_TERMINATED,
   WORKFLOWS_JOB_STEPS_SETTLED,
   WORKFLOWS_STEP_ATTEMPT_TERMINATED,
   WORKFLOWS_STEP_RESTART_ENQUEUED,
 } from '@shipfox/api-workflows-dto';
 import {eq} from 'drizzle-orm';
+import type {JobStatusReason} from '#core/entities/job.js';
+import type {JobExecutionStatus} from '#core/entities/job-execution.js';
 import type {Tx} from '../db.js';
 import {writeWorkflowsOutboxEvent} from '../outbox-writes.js';
 import {jobExecutions} from '../schema/job-executions.js';
 import {steps} from '../schema/steps.js';
 import {getWorkflowContextForJob} from './shared.js';
 
+export async function writeJobExecutionQueuedOutbox(
+  tx: Tx,
+  params: {
+    jobId: string;
+    jobExecutionId: string;
+    requiredLabels: string[];
+    queuedAt: Date;
+  },
+): Promise<void> {
+  const identity = await getWorkflowContextForJob(params.jobId, tx);
+
+  await writeWorkflowsOutboxEvent(tx, {
+    type: WORKFLOWS_JOB_EXECUTION_QUEUED,
+    payload: {
+      jobId: params.jobId,
+      jobExecutionId: params.jobExecutionId,
+      workflowRunId: identity.workflowRunId,
+      workflowRunAttemptId: identity.workflowRunAttemptId,
+      workspaceId: identity.workspaceId,
+      projectId: identity.projectId,
+      requiredLabels: params.requiredLabels,
+      queuedAt: params.queuedAt.toISOString(),
+    },
+  });
+}
+
+export async function writeJobExecutionTerminatedOutbox(
+  tx: Tx,
+  params: {
+    jobId: string;
+    jobExecutionId: string;
+    status: JobExecutionStatus;
+    statusReason: JobStatusReason | null;
+    statusReasonMessage?: string | null | undefined;
+  },
+): Promise<void> {
+  if (
+    params.status !== 'succeeded' &&
+    params.status !== 'failed' &&
+    params.status !== 'cancelled'
+  ) {
+    throw new Error(`Cannot enqueue terminal job execution event for status ${params.status}`);
+  }
+  const identity = await getWorkflowContextForJob(params.jobId, tx);
+
+  await writeWorkflowsOutboxEvent(tx, {
+    type: WORKFLOWS_JOB_EXECUTION_TERMINATED,
+    payload: {
+      jobId: params.jobId,
+      jobExecutionId: params.jobExecutionId,
+      workflowRunId: identity.workflowRunId,
+      workflowRunAttemptId: identity.workflowRunAttemptId,
+      status: params.status,
+      statusReason: params.statusReason,
+      statusReasonMessage: params.statusReasonMessage ?? null,
+    },
+  });
+}
+
 // Enqueue the steps-settled signal in the same transaction as the final per-step
 // result, so per-step execution observes it exactly once (the outbox is at-least-once;
 // the job workflow dedupes the signal). Drives the Temporal JOB_FINISHED_SIGNAL; the