---
id: STATE-COM-FUL-011
title: Stock finding lifecycle
object: DOM-COM-FUL-005
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
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 inventory-update authority and an open finding.
    side_effects: []
    who: Administrator
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/persistence/inventory-exceptions.ts:acknowledgeInventoryException
  - from: open
    to: resolved
    trigger: Staff retain a closure result under the specific intervention authority.
    guard: Closure must supply its result and find a standing finding.
    side_effects: []
    who: Administrator
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/persistence/inventory-exceptions.ts:resolveInventoryException
  - from: acknowledged
    to: resolved
    trigger: Staff retain a closure result under the specific intervention authority.
    guard: Closure must supply its result and find a standing finding.
    side_effects: []
    who: Administrator
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/persistence/inventory-exceptions.ts:resolveInventoryException
  - from: open
    to: open
    trigger: >-
      The owning process records another allowed update without changing this
      state.
    guard: Recurrence must find the same standing kind and subject.
    side_effects:
      - Occurrences increased; latest details and detection retained.
    who: Nightly check or shipping workflows
    provenance: test
    source: >-
      services-commerce:modules/inventory/tests/integration/services/reconciliation/nightly-inventory.integration.spec.js#raises
      stale_allocation on the committed unit whose obligation is cancelled
invalid:
  - from: resolved
    to: open
    why: Resolved work remains closed; another occurrence needs its own record.
concurrency: >-
  Reserved concurrency one prevents overlapping nightly functions. Other
  warehouse requests still run, and each diagnosis writes in its subject’s
  workspace.
invariants:
  - INV-DOM-COM-FUL-005-11
evidence:
  - >-
    services-commerce at c8b66a98:
    modules/inventory/db/inventory-exceptions.table.ts;
    services/persistence/inventory-exceptions.ts;
    services/reconciliation/nightly-inventory.ts.
---

# Stock Finding Lifecycle

## The Lifecycle

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

## Transitions Explained

Warehouse and nightly checks open stock findings. Recurrence updates the standing record, staff acknowledgement records awareness, and resolution retains the investigation result. Only expired holds receive an automatic correction.

## What Cannot Happen

A resolved finding stays closed; later recurrence creates another record. Acknowledgement requires an open finding and cannot be repeated on an acknowledged one.

## Concurrency and Timing

The nightly function has reserved concurrency one and runs at 08:00 UTC. Shipping also raises findings during requests, and these records remain outside the Operations collection.