---
id: WF-COM-FUL-017
title: Count a shelf and correct the ledger
trigger: 'Staff open, record or complete a shelf count.'
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
implements:
  - CAP-COM-FUL-019
moves:
  - STATE-COM-FUL-010
crosses:
  - SVC-COM-FUL-inventory
idempotency: >-
  Correction keys identify count lines. A terminal count refuses another
  completion, while the retained movements prevent duplicate corrections.
concurrency: >-
  Completion locks the count and compares observations with current on-hand. The
  recorded expectation can be older than intervening stock movements.
hops:
  - 'n': 1
    actor_or_service: Inventory API (open and record)
    action: >-
      Open a scoped count and retain or replace each item observation with its
      current expectation.
    anchor: >-
      services-commerce:modules/inventory/services/persistence/inventory-counts.ts:recordCountLines
    seam: sync
    on_failure: Reject items outside the selected warehouse or location.
    left_inconsistent: Earlier valid observations remain recorded.
    observer: Count observations.
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/persistence/inventory-counts.ts
  - 'n': 2
    actor_or_service: Inventory API (complete)
    action: >-
      Write keyed correction movements against current on-hand, stamp counted
      items and complete the count.
    anchor: >-
      services-commerce:modules/inventory/services/persistence/inventory-counts.ts:completeCount
    seam: sync
    on_failure: Rollback completion if any correction is refused.
    left_inconsistent: The failed completion retains no partial correction.
    observer: Correction movement history.
    provenance: observed
    source: >-
      services-commerce:modules/inventory/services/persistence/inventory-counts.ts
branches:
  - Cancelling writes nothing.
  - >-
    A short pick raises a stock finding that asks for a count; nothing opens the
    count automatically.
waits:
  - The staff member's counting.
evidence:
  - >-
    services-commerce at c8b66a98:
    modules/inventory/services/persistence/inventory-counts.ts;
    db/inventory-counts.table.ts, inventory-count-lines.table.ts.
controls: [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-LOG-004, TC-PI-001, TC-PI-003, TC-PI-005]
---

# Count a Shelf and Correct the Ledger

## What It Does

Staff open a count and record or replace item observations within its warehouse scope. Completion compares each observation with current on-hand, writes keyed correction movements and stamps the counted items.

## The Flow

```mermaid
sequenceDiagram
  participant S as Staff
  participant I as Inventory API
  participant M as Movement ledger
  S->>I: open count
  S->>I: record lines (expected kept)
  S->>I: complete
  I->>M: count corrections for differences
```

## When Something Fails

Invalid scope or a balance refusal stops the act. Failed completion rolls back its corrections together. Terminal counts reject another completion or line edit.