---
id: WF-COM-FUL-009
title: Record a staff intervention and tell the audit store
trigger: Staff submit an available intervention.
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-COM-FUL-005
  - CAP-COM-FUL-008
moves:
  - STATE-COM-FUL-001
  - STATE-COM-FUL-004
crosses:
  - SVC-COM-FUL-fulfillment
  - SVC-COM-FUL-operations
idempotency: >-
  Accepted interventions have no request key. State checks refuse repetitions
  that no longer apply, and failed local changes roll back their intervention
  record.
concurrency: >-
  Local changes lock their subject. Approval rechecks its condition before
  retaining the act, so competing approval requests retain one accepted
  intervention.
hops:
  - 'n': 1
    actor_or_service: Console (Operations or Order 360)
    action: >-
      Offer actions by subject state, kind and permission, collecting reason or
      the evidence used for closure.
    anchor: 'react-console:lib/commerce/operations/live.ts:interventionRoute'
    seam: sync
    on_failure: Explain unsupported actions without sending a request.
    left_inconsistent: No unsupported intervention is performed.
    observer: Screen explanation.
    provenance: observed
    source: 'react-console:lib/commerce/operations/rules.ts:interventionsFor'
  - 'n': 2
    actor_or_service: Fulfillment or operations API
    action: >-
      Validate the specific authority and retain intervention, history and
      subject change in the local transaction.
    anchor: >-
      services-commerce:modules/fulfillment/services/register/obligation-interventions.ts
    seam: sync
    on_failure: Rollback the local act when its change is refused.
    left_inconsistent: The refused local transaction retains no intervention.
    observer: Request refusal response.
    provenance: observed
    source: >-
      services-commerce:modules/operations/services/interventions/operations-interventions.ts
  - 'n': 3
    actor_or_service: Fulfillment or operations API
    action: >-
      Evaluate gate-affecting changes or nudge newly queued authorizations after
      the local commit.
    anchor: >-
      services-commerce:modules/fulfillment/services/register/gate-evaluation.ts:evaluateObligations
    seam: sync
    on_failure: Later recovery may revisit pending gates or retained dispatch entries.
    left_inconsistent: The committed staff act can precede delivery continuation.
    observer: Updated obligation verdict.
    provenance: observed
    source: >-
      services-commerce:modules/fulfillment/services/register/obligation-interventions.ts
  - 'n': 4
    actor_or_service: Intervention audit provider
    action: >-
      Attempt external audit publication with the action, actor, subject and
      local ledger reference.
    anchor: >-
      services-commerce:modules/fulfillment/services/register/intervention-audit.ts
    seam: event
    on_failure: >-
      Log publication failure without refusing the already committed
      intervention.
    left_inconsistent: Platform audit storage lacks the act while Commerce retains it.
    observer: Audit-provider error log.
    provenance: observed
    source: >-
      services-commerce:aws/cdk/commerce.function-environment.ts
      (COMMERCE_INTERVENTION_AUDIT=platform)
  - 'n': 5
    actor_or_service: Console
    action: Reload the subject or order and refresh the displayed attention state.
    anchor: 'react-console:lib/commerce/operations/live.ts:createLiveOperationsAdapter'
    seam: sync
    on_failure: Show a stale-subject response or read failure.
    left_inconsistent: The browser can temporarily retain an outdated view.
    observer: Reloaded screen state.
    provenance: observed
    source: 'react-console:lib/commerce/operations/live.ts'
branches:
  - >-
    Manual completion requires evidence and applies only to an in-flight
    obligation.
  - >-
    A hold applies only to a outstanding obligation; its release leaves it
    blocked for the evaluator.
waits: []
evidence:
  - >-
    services-commerce at c8b66a98:
    modules/fulfillment/services/register/obligation-interventions.ts,
    intervention-audit.ts;
    modules/operations/services/interventions/operations-interventions.ts;
    db/intervention-logs.table.ts; docs/migrations/operations/README.md
    (D-P5-10, D-P5-11, D-P5-12).
  - >-
    react-console at baf6dae3: lib/commerce/operations/*.ts;
    components/commerce/operations/intervention-dialog.tsx.
controls: [TC-IAM-006, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002]
---

# Record a Staff Intervention and Tell the Audit Store

## What It Does

A staff intervention validates its authority and records the actor, reason and change together. Gate-related actions can evaluate afterward, and queued work can nudge dispatch. The screen then reads the subject again.

## The Flow

```mermaid
sequenceDiagram
  participant P as Staff (console)
  participant A as Fulfillment or operations API
  participant L as Intervention ledger
  participant S as Subject record
  participant U as Audit provider
  P->>A: action, reason
  A->>L: record intervention
  A->>S: make the change (same transaction)
  A-->>A: commit
  A->>A: evaluate, nudge dispatcher
  A->>U: audit event (never thrown)
  A-->>P: result; console re-reads
```

## When Something Fails

The change survives later audit failure. The selected audit provider currently writes an error log rather than a Platform audit record. Unsupported console actions send nothing, and a stale subject can return a conflict or disappear on reload.