---
id: STATE-COM-CAT-009
title: Code issuance batch
object: DOM-COM-CAT-005
product_area: commerce
module: catalog
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: requested
    meaning: The generation request is saved and its worker has been requested.
  - name: running
    meaning: Worker chunks are creating codes and progress reflects saved rows.
  - name: completed
    meaning: The requested number of codes exists and completion is recorded once.
  - name: failed
    meaning: Generation stopped with an explanation; successfully saved codes remain available.
transitions:
  - from: requested
    to: running
    trigger: The invoked worker begins generation.
    guard: The batch must remain requested or running.
    side_effects:
      - Progress is recalculated from saved code rows.
    who: Issuance worker
    provenance: documented
    source: 'services-commerce:modules/promotions/services/persistence/promotion-code-issuances.ts'
  - from: running
    to: completed
    trigger: The final required codes commit.
    guard: The saved code count must reach the requested quantity.
    side_effects:
      - The batch receives a completion instant and one history entry rather than an entry for every code.
    who: Issuance worker
    provenance: test
    source: >-
      services-commerce:modules/promotions/tests/unit/issuance/issuance-job.spec.js#continues from the codes
      that exist after a crash, making only the missing ones
  - from: running
    to: failed
    trigger: Generation encounters an error or reaches its conflict retry bound.
    guard: No additional condition applies.
    side_effects:
      - The batch displays a plain explanation while logs retain technical error detail.
    who: Issuance worker
    provenance: documented
    source: 'services-commerce:modules/promotions/services/issuance/issuance-job.ts'
  - from: requested
    to: failed
    trigger: Worker invocation fails.
    guard: No additional condition applies.
    side_effects:
      - The batch receives a failure explanation instead of remaining requested.
    who: Promotions API
    provenance: documented
    source: 'services-commerce:modules/promotions/services/issuance/issuance-workflow.ts'
  - from: running
    to: running
    trigger: 'A retry, repeated request or stale-batch read invokes generation again.'
    guard: The batch must remain requested or running.
    side_effects:
      - Generation resumes at the saved code count.
    who: 'Issuance worker, the promotions API on read'
    provenance: documented
    source: 'services-commerce:modules/promotions/services/issuance/issuance-workflow.ts:readCodeIssuance'
invalid:
  - from: completed
    to: running
    why: Completed generation returns saved progress without restarting.
  - from: failed
    to: running
    why: Failed generation remains final; further codes require another batch.
concurrency: >-
  Each chunk locks its batch, recounts saved codes and inserts no more than the remaining request quantity.
  Workspace code conflicts cause bounded regeneration attempts; different batches retain separate progress.
invariants:
  - INV-DOM-COM-CAT-005-14
evidence:
  - >-
    services-commerce at c8b66a98: modules/promotions/db/promotion-code-issuances.table.ts
    (ISSUANCE_STATUSES); services/persistence/promotion-code-issuances.ts; services/issuance/issuance-job.ts,
    issuance-workflow.ts, issuance-starter.ts; aws/lambda/ISSUANCE.ts.
  - 'services-commerce at c8b66a98: docs/milestones/COMM-M1b-promotions-and-codes.md (D-R2, scope item 1).'
---

# Code issuance batch

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> requested: request written
  requested --> running: worker starts
  requested --> failed: worker cannot be invoked
  running --> running: restarted, continues
  running --> completed: every code exists
  running --> failed: error or bounded retries spent
  completed --> [*]
  failed --> [*]
```

## Transitions Explained

Requested: The generation request is saved and its worker has been requested. Running: Worker chunks are creating codes and progress reflects saved rows. Completed: The requested number of codes exists and completion is recorded once. Failed: Generation stopped with an explanation; successfully saved codes remain available.

## What Cannot Happen

Completed generation returns saved progress without restarting. Failed generation remains final; further codes require another batch.

## Concurrency and Timing

Each chunk locks its batch, recounts saved codes and inserts no more than the remaining request quantity. Workspace code conflicts cause bounded regeneration attempts; different batches retain separate progress.