---
id: STATE-COM-FUL-007
title: Pick list lifecycle
object: DOM-COM-FUL-004
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: claimed
    meaning: A picker has taken responsibility for the list.
  - name: completed
    meaning: The owning process has retained the required completed outcome.
  - name: cancelled
    meaning: >-
      The owning process withdrew the work under its permitted cancellation
      checks.
transitions:
  - from: open
    to: claimed
    trigger: A picker claims the open list.
    guard: Claim must find an open list.
    side_effects:
      - Picker and time stored.
    who: Picker (pick list update)
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/fulfillment/picking.ts:claimPickList
  - from: claimed
    to: completed
    trigger: The owning workflow retains its required final successful result.
    guard: Every list line must have a full or short result.
    side_effects: []
    who: Picker
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/fulfillment/picking.ts:completePickList
  - from: open
    to: completed
    trigger: The owning workflow retains its required final successful result.
    guard: Every line must be decided even if the list was not claimed.
    side_effects: []
    who: Picker
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/persistence/pick-lists.ts:completePickList
      (open or claimed)
  - from: open
    to: cancelled
    trigger: The owning process withdraws work before departure or delivery permits it.
    guard: Cancellation must find an open or claimed list.
    side_effects:
      - Return shipment lines for unfinished picking to warehouse release.
    who: Warehouse staff
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/fulfillment/picking.ts:cancelPickList
  - from: claimed
    to: cancelled
    trigger: The owning process withdraws work before departure or delivery permits it.
    guard: Cancellation must find an open or claimed list.
    side_effects:
      - Return unfinished picking lines to the available work queue.
    who: Warehouse staff
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/fulfillment/picking.ts:cancelPickList
invalid:
  - from: completed
    to: cancelled
    why: >-
      Completion remains final for this action; use the owning replacement or
      correction process.
  - from: cancelled
    to: claimed
    why: Cancelled work cannot be restarted through this lifecycle.
concurrency: >-
  Candidate selection precedes creation writes. Pick-list exclusion is read
  before insertion, and database membership uniqueness is per list, so competing
  list creation can duplicate a shipment line.
invariants:
  - INV-DOM-COM-FUL-004-01
evidence:
  - >-
    services-commerce at c8b66a98: modules/shipping/db/pick-lists.table.ts,
    pick-list-lines.table.ts; services/fulfillment/picking.ts;
    services/persistence/pick-lists.ts; docs/migrations/shipping/README.md
    (D-P8S-13).
---

# Pick List Lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> open: gathered from released lines
  open --> claimed
  claimed --> completed
  open --> completed
  open --> cancelled
  claimed --> cancelled
  completed --> [*]
  cancelled --> [*]
```

## Transitions Explained

A pick list gathers released lines and can be claimed by a picker. Each line receives a full or short result. Completion requires all lines decided, while cancellation returns undecided work to release.

## What Cannot Happen

Workflow checks retain completed and cancelled lists as terminal. The current membership check does not establish that concurrent list creation cannot duplicate a shipment line.

## Concurrency and Timing

Membership selection precedes insertion and uniqueness applies only within one list. A warehouse pick records physical work; allocation picking already occurred under delivery authorization.