---
id: STATE-COM-FUL-004
title: Operational exception lifecycle
object: DOM-COM-FUL-003
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: open
    meaning: The record is active and available for its next staff or workflow action.
  - name: acknowledged
    meaning: Staff have recorded awareness while the finding remains outstanding.
  - name: resolved
    meaning: Staff retained closure and the result rather than executing further work.
transitions:
  - from: open
    to: acknowledged
    trigger: Staff record awareness of the open finding.
    guard: The caller needs acknowledgement authority and an unresolved exception.
    side_effects:
      - Intervention stored and the order's history line retained.
      - Send the staff audit event after the local transaction commits.
    who: Administrator
    provenance: observed
    source: >-
      services-commerce:modules/operations/services/interventions/operations-interventions.ts:acknowledgeExceptionByStaff
  - from: open
    to: resolved
    trigger: Staff retain a closure result under the specific intervention authority.
    guard: The caller needs resolution authority and a retained closure result.
    side_effects:
      - Intervention stored; audit event after commit.
    who: >-
      Administrator, or the register when a failed obligation or review is
      resolved
    provenance: test
    source: >-
      services-commerce:modules/fulfillment/tests/e2e/obligation-register.e2e.spec.js#re-authorizes
      the failed obligation at sequence two, which the participant fails again,
      then resolves it with its exceptions
  - from: acknowledged
    to: resolved
    trigger: Staff retain a closure result under the specific intervention authority.
    guard: Resolution must find a standing exception and the required authority.
    side_effects:
      - Intervention stored; audit event after commit.
    who: Administrator or the register
    provenance: observed
    source: >-
      services-commerce:modules/operations/services/interventions/operations-interventions.ts:resolveExceptionByStaff
  - from: open
    to: open
    trigger: >-
      The owning process records another allowed update without changing this
      state.
    guard: A standing exception of the same kind and subject must already exist.
    side_effects:
      - Increase the recurrence count and replace the diagnostic details.
    who: 'Register worker, register sweep or reconciler'
    provenance: documented
    source: 'services-commerce:docs/migrations/operations/README.md#D-P5-08'
  - from: acknowledged
    to: acknowledged
    trigger: >-
      The owning process records another allowed update without changing this
      state.
    guard: Requires standing row exists.
    side_effects:
      - Increase the recurrence count for the standing finding.
    who: Register or reconciler
    provenance: observed
    source: >-
      services-commerce:modules/fulfillment/services/persistence/operational-exceptions.ts
invalid:
  - from: resolved
    to: open
    why: Resolved work remains closed; another occurrence needs its own record.
  - from: resolved
    to: acknowledged
    why: Resolved work remains closed; another occurrence needs its own record.
concurrency: >-
  Standing-key uniqueness controls recurrence, and local staff changes lock
  their subject. Detection and browser refresh remain separate from the
  intervention commit.
invariants:
  - INV-DOM-COM-FUL-003-01
  - INV-DOM-COM-FUL-003-02
  - INV-DOM-COM-FUL-003-03
evidence:
  - >-
    services-commerce at c8b66a98:
    modules/fulfillment/db/operational-exceptions.table.ts;
    services/persistence/operational-exceptions.ts;
    modules/operations/services/interventions/operations-interventions.ts.
  - >-
    react-console at baf6dae3: lib/commerce/operations/live.ts (intervene reads
    the finding again after acting).
---

# Operational Exception Lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> open: detected
  open --> open: recurs
  open --> acknowledged
  acknowledged --> acknowledged: recurs
  open --> resolved
  acknowledged --> resolved
  resolved --> [*]
```

## Transitions Explained

Detection opens a finding. Repeated detection refreshes the standing diagnosis and occurrence count. Acknowledgement records awareness; resolution records closure and can also follow resolution of the affected record.

## What Cannot Happen

Resolved findings stay closed. A later recurrence can create another standing record, except an informational finding tied to a deduplicated event.

## Concurrency and Timing

Workers and scheduled checks detect independently. The screen reloads after staff action so a finding that changed elsewhere can leave the current view.