---
id: WF-PFM-OPS-002
title: Run a job’s steps through to its outcome
product_area: platform
module: operations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
trigger: The first orchestration task begins a submitted job.
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
implements:
  - CAP-PFM-OPS-001
  - CAP-PFM-OPS-003
moves:
  - STATE-PFM-OPS-001
  - STATE-PFM-OPS-002
crosses:
  - SVC-PFM-OPS-jobs
idempotency: >-
  Tasks must tolerate repeat execution by their owner’s contract. Identical step reports add no event, and
  reports after final root settlement are discarded. Failure effects must be safe to repeat.
concurrency: >-
  The sequential workflow orders its tasks. Version checks arbitrate task and reconciler writes, but do not
  themselves make the owning task’s business effects idempotent.
hops:
  - 'n': 1
    actor_or_service: Standard publication task
    action: Publish the step definition into run history for monitor presentation.
    anchor: 'macroservice-libraries:packages/jobs/src/task/standard-job-operations.ts:publishStepDefinitionOperation'
    seam: state_machine
    on_failure: Use the publish task’s orchestration retry policy.
    left_inconsistent: The monitor may need its available catalogue fallback until publication succeeds.
    observer: Job page step list is the observation surface.
    provenance: test
    source: >-
      services-platform:modules/jobs/tests/integration/services/job-snapshot/job-snapshot.integration.spec.js#takes
      that catalog from the published event rather than the declaration, which the event itself carries
  - 'n': 2
    actor_or_service: Shared task handler
    action: >-
      Reconstruct execution context, report the step attempt, run the owner’s task and record completion or
      non-applicability.
    anchor: 'macroservice-libraries:packages/jobs/src/task/job-task-handler.ts:createJobTaskHandler'
    seam: state_machine
    on_failure: >-
      Route permanent refusals to failure handling; log other errors and retry while the configured budget
      remains.
    left_inconsistent: 'An unfinished attempt can remain running or retrying, with progress retained.'
    observer: Attempt history on job detail and task-function logs.
    provenance: test
    source: >-
      macroservice-libraries:packages/jobs/src/workflow/job-workflow.spec.ts#lets no detail of the transient
      error reach the job or the execution state
  - 'n': 3
    actor_or_service: Owning module task marked as settling
    action: >-
      Run the settling work and record successful root settlement; notifying kinds also invoke their success
      notice path.
    anchor: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:settleJob'
    seam: state_machine
    on_failure: Retry eligible task errors; the handler contains final-settlement refusal.
    left_inconsistent: Business work may have finished before its successful job account is recorded.
    observer: Monitors is the observation surface.
    provenance: observed
    source: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:settleJob'
  - 'n': 4
    actor_or_service: Standard failure task
    action: >-
      On permanent refusal or exhausted retries, apply the registered effect and then record failed step and
      root outcomes.
    anchor: 'macroservice-libraries:packages/jobs/src/task/standard-job-operations.ts:recordJobFailureOperation'
    seam: state_machine
    on_failure: 'If the effect throws before settlement, leave the job open for reconciliation.'
    left_inconsistent: Business recovery may have begun while the job remains open.
    observer: Detail failure panel and execution failure alarm is the observation surface.
    provenance: test
    source: >-
      macroservice-libraries:packages/jobs/src/reconciler/job-reconciler.spec.ts#applies it before the
      settlement, so a consequence that fails leaves the job for the next pass
  - 'n': 5
    actor_or_service: Notify requester
    action: Invoke shared requester delivery through the notifying kind’s success or failure path.
    anchor: 'services-platform:modules/jobs/services/notices/notify-job-requester.ts:notifyJobRequester'
    seam: sync
    on_failure: Contain delivery exceptions and record the notice attempt when possible.
    left_inconsistent: The job can finish without a delivered notice.
    observer: Notice outcome records and the delivery-failure metric.
    provenance: observed
    source: 'services-platform:modules/jobs/services/notices/notify-job-requester.ts:notifyJobRequester'
branches:
  - condition: A task answers that the step does not apply
    path: Execution continues without running that step.
  - condition: A repeating task has more work than one invocation
    path: >-
      The task persists its cursor and continues the same running step within its iteration limit. A longer
      run can record and start a continuation execution.
waits:
  - what: Task retries
    how_long: 'as each task declares, bounded by the execution timeout'
evidence:
  - >-
    macroservice-libraries at 54536a4: task/job-task-handler.ts, task/standard-job-operations.ts,
    workflow/job-workflow.ts, engine/job-engine.ts.
  - >-
    services-platform at ad3f6a6: docs/jobs.md §2 steps 3 to 6;
    modules/tenants/services/provisioning/provision-tenant-workflow.ts.
  - >-
    codex examination 2026-10-23: checked the pinned source anchors, planning references and enforcement
    boundaries; unresolved limits are recorded in module findings.
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Run a job’s steps through to its outcome

## What It Does

Orchestration runs declared tasks and the shared handler records their progress. The domain owner implements the business work, while the common engine supplies steps, attempts, history and settlement. Repeated tasks and continuation follow the declared workflow contract.

## The Flow

```mermaid
flowchart TD
  H0["Publish the step definition into run history for monitor presentation."]
  H1["Reconstruct execution context, report the step attempt, run the owner’s task and record completion or non-applicability."]
  H0 --> H1
  H2["Run the settling work and record successful root settlement; notifying kinds also invoke their success notice path."]
  H1 --> H2
  H3["On permanent refusal or exhausted retries, apply the registered effect and then record failed step and root outcomes."]
  H2 --> H3
  H4["Invoke shared requester delivery through the notifying kind’s success or failure path."]
  H3 --> H4
```

## When Something Fails

Retryable errors keep diagnostic detail in logs and use safe error names and references in reporting. Permanent refusal reaches the failure workflow. Failure effects ordinarily precede failed settlement, so an error there leaves an open candidate for reconciliation. Requester delivery errors are contained and do not determine the job outcome.

## Open Design Questions

Workspace provisioning is the only notifying Platform kind. Any broader audience or destination needs the existing product decision.