---
id: WF-PFM-OPS-006
title: Stop a running job on request
product_area: platform
module: operations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference: []
trigger: >-
  An engine caller requests cancellation for a kind declaring support; Platform exposes no cancellation route
  or screen.
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
implements:
  - CAP-PFM-OPS-004
moves:
  - STATE-PFM-OPS-001
  - STATE-PFM-OPS-002
crosses:
  - SVC-PFM-OPS-jobs
idempotency: >-
  Repeated cancellation adds no second request event. It can repeat the stop call, allowing a caller to retry
  a failed stop submission.
concurrency: >-
  The recorded request uses a version-checked transaction. A competing final settlement prevents cancellation
  from reopening the root.
hops:
  - 'n': 1
    actor_or_service: Job engine
    action: >-
      Validate cancellation support, open status and a nonblank reason, then record requester, time and reason
      with history.
    anchor: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:cancelJob'
    seam: sync
    on_failure: Refuse the request without committing a cancellation change.
    left_inconsistent: No accepted stop request remains after validation refusal.
    observer: Caller’s error is the observation surface.
    provenance: test
    source: >-
      macroservice-libraries:packages/jobs/src/engine/job-cancellation.spec.ts#refuses a job whose type is not
      cancellable
  - 'n': 2
    actor_or_service: Job engine
    action: 'If no execution handle exists, commit immediate cancellation with the request.'
    anchor: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:writeCancellation'
    seam: sync
    on_failure: Roll back the cancellation transaction on write failure.
    left_inconsistent: No partially committed cancellation account remains.
    observer: Job history is the observation surface.
    provenance: test
    source: >-
      macroservice-libraries:packages/jobs/src/engine/job-cancellation.spec.ts#records the request on the root
      and in its history, then stops the execution with the cause
  - 'n': 3
    actor_or_service: Job engine
    action: 'After commit, send the orchestration stop request using the recorded reason.'
    anchor: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:cancelJob'
    seam: state_machine
    on_failure: Log and propagate a stop error; retain the accepted request.
    left_inconsistent: The execution can continue while the job carries a stop request.
    observer: Stop-failed log event is the observation surface.
    provenance: observed
    source: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:cancelJob'
  - 'n': 4
    actor_or_service: Reconciler or observing task
    action: >-
      When a task or reconciler observes the stop, settle cancelled and fail in-flight steps as stopped
      without a business failure effect.
    anchor: 'macroservice-libraries:packages/jobs/src/engine/job-engine.ts:settleCancelledJob'
    seam: schedule
    on_failure: Defer an unsuccessful reconciliation attempt.
    left_inconsistent: The job can remain open with cancellation already requested.
    observer: Job history is the observation surface.
    provenance: test
    source: >-
      macroservice-libraries:packages/jobs/src/engine/job-cancellation.spec.ts#settles an execution aborted on
      request as cancelled, applying no failure consequence
branches: []
waits:
  - what: Observation of the stop
    how_long: until a task observes the request or the reconciler’s next pass after fifteen minutes of silence
evidence:
  - >-
    macroservice-libraries at 54536a4: engine/job-engine.ts (cancelJob, settleCancelledJob,
    writeCancellation), engine/job-cancellation.spec.ts, CHANGELOG 0.5.0.
  - >-
    services-platform at ad3f6a6: modules/jobs/aws/api/jobs.routes.ts (read-only surface);
    modules/eligibility/services/population/population-workflow.ts (cancellable).
  - >-
    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-AZ-005, TC-DAT-001, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Stop a running job on request

## What It Does

Cancellation first records the intention to stop, then asks orchestration to stop execution. A job with no execution handle becomes cancelled immediately. Eligibility population declares support, but callers cannot reach a Platform cancellation operation or screen.

## The Flow

```mermaid
flowchart TD
  H0["Validate cancellation support, open status and a nonblank reason, then record requester, time and reason with history."]
  H1["If no execution handle exists, commit immediate cancellation with the request."]
  H0 --> H1
  H2["After commit, send the orchestration stop request using the recorded reason."]
  H1 --> H2
  H3["When a task or reconciler observes the stop, settle cancelled and fail in-flight steps as stopped without a business failure effect."]
  H2 --> H3
```

## When Something Fails

A failed stop call does not erase the request. The caller can repeat it, and an observing task can settle cancellation itself. An aborted execution is cancelled only when a recorded request explains it; an unrequested abort is failed work.

## Open Design Questions

Authority and management surfaces for stopping work remain the existing open product choice.