---
id: WF-PFM-DJE-013
title: Cancel a data run
trigger: 'Staff cancel a registered, running or paused migration run.'
product_area: platform
module: data-job-engine
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-DJE-016
moves:
  - STATE-PFM-DJE-004
  - STATE-PFM-DJE-005
  - STATE-PFM-DJE-001
crosses:
  - SVC-PFM-DJE-data-jobs
  - SVC-PFM-DJE-crm-data-jobs
hops:
  - 'n': 1
    actor_or_service: Run driver
    action: Authorize the caller for active child datasets.
    anchor: >-
      services-platform:modules/data-jobs/services/runs/run-driver.ts:cancelDataRun
    seam: sync
    on_failure: Return access denial before this authorization phase changes state.
    left_inconsistent: Existing child work remains active.
    observer: The request response exposes the result.
    provenance: observed
    source: >-
      services-platform:modules/data-jobs/services/runs/run-driver.ts:authorizeSteps
  - 'n': 2
    actor_or_service: Run driver and the owning services
    action: >-
      Request cancellation from each active child using current staff
      credentials.
    anchor: 'services-platform:modules/data-jobs/services/runs/run-driver.ts:cancelStep'
    seam: sync
    on_failure: Access denial stops the loop; other failures are logged and ignored.
    left_inconsistent: >-
      Previously cancelled children stay cancelled, while failed requests can
      leave others writing.
    observer: Warning logs expose ignored child-call failures.
    provenance: observed
    source: 'services-platform:modules/data-jobs/services/runs/run-driver.ts:cancelStep'
  - 'n': 3
    actor_or_service: Run persistence
    action: Set the parent cancelled and mark pending steps skipped.
    anchor: >-
      services-platform:modules/data-jobs/services/persistence/data-runs.ts:setDataRunState
    seam: sync
    on_failure: Refuse incompatible final state or return persistence failure.
    left_inconsistent: 'Committed records remain, and child settlement is not verified.'
    observer: The run read.
    provenance: test
    source: >-
      services-platform:modules/data-jobs/tests/integration/services/runs/run-driver.integration.spec.js#cancels
      the jobs a cancelled run had already submitted, in their own services
idempotency: >-
  Setting an already cancelled state returns unchanged, although the
  cancellation method can still call children whose step rows remain running.
  Other final parent transitions are refused.
concurrency: >-
  A concurrent execution pass can submit a child after cancellation read its
  active steps, leaving that child outside the cancel calls.
branches: []
waits: []
evidence:
  - >-
    services-platform at ad3f6a65: services/runs/run-driver.ts;
    services/persistence/data-runs.ts.
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-003, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, 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-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]
---

# Cancel A Data Run

## What It Does

Parent cancellation asks active child services to stop and skips work not submitted. It does not wait for every child to prove that processing ended.

## The Flow

```mermaid
flowchart TD
  H1["Run driver"] --> H2
  H2["Run driver and the owning services"] --> H3
  H3["Run persistence"]
```

## When Something Fails

A cancellation loop can partially cancel children before a later access refusal. Non-access failures are ignored, allowing a cancelled parent with an active child. Committed records remain until an explicit reset.

## Open Design Questions

The recorded findings identify the remaining limits; this examination does not authorize stronger behavior or change the planning rules.