---
id: STATE-COM-CAT-006
title: Special-price handover realization
object: DOM-COM-CAT-004
product_area: commerce
module: catalog
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
states:
  - name: handed over
    meaning: >-
      Accounting retained a retired special-price handover whose price row references an audience awaiting
      creation.
  - name: audience prepared
    meaning: An inactive product-scoped audience exists while binding work remains.
  - name: realized
    meaning: 'The audience is bound and active, and Accounting’s handover has its completion stamp.'
  - name: unresolved
    meaning: A conflicting rank or refused criteria leave work pending with an explanation.
transitions:
  - from: handed over
    to: audience prepared
    trigger: Realization processes a pending handover.
    guard: The required rank must be available in the workspace.
    side_effects:
      - Preparation inserts an inactive audience scoped to the product.
      - An existing matching audience can instead be retained.
    who: The realization job (no caller exists)
    provenance: test
    source: >-
      services-commerce:modules/pricing/tests/integration/services/handovers/audience-handover-realization.integration.spec.js#leaves
      a handover whose rank another audience of the tenant holds, naming the rank
  - from: handed over
    to: unresolved
    trigger: Realization encounters an occupied audience rank.
    guard: A different audience must already occupy the desired rank.
    side_effects:
      - The report identifies the conflicting handover and rank.
    who: The realization job
    provenance: test
    source: >-
      services-commerce:modules/pricing/tests/integration/services/handovers/audience-handover-realization.integration.spec.js#leaves
      a handover whose rank another audience of the tenant holds, naming the rank
  - from: audience prepared
    to: realized
    trigger: The binding port returns the definition and binding.
    guard: The binding port must accept the retained criteria.
    side_effects:
      - The audience receives its binding reference.
      - The audience becomes active.
      - Accounting’s handover receives a realization timestamp.
    who: 'The realization job, through a fixture binding port'
    provenance: documented
    source: 'services-commerce:modules/pricing/services/handovers/audience-handover-realization.ts'
  - from: audience prepared
    to: unresolved
    trigger: Binding creation rejects the retained criteria.
    guard: No additional condition applies.
    side_effects:
      - The inactive audience remains and the report explains the pending handover.
    who: The realization job
    provenance: documented
    source: 'services-commerce:modules/pricing/services/handovers/audience-handover-realization.ts'
  - from: unresolved
    to: audience prepared
    trigger: A later realization run can prepare the audience.
    guard: The requested rank must be available.
    side_effects:
      - Realization reuses the prepared audience.
    who: The realization job
    provenance: documented
    source: 'services-commerce:modules/pricing/services/handovers/audience-handover-realization.ts'
invalid:
  - from: realized
    to: handed over
    why: No implementation clears the realization timestamp.
concurrency: >-
  Sequential reruns adopt prepared audiences and skip stamped work. No runtime caller exists, and overlapping
  realization has no established serialization beyond uniqueness checks.
invariants:
  - INV-DOM-COM-CAT-004-02
evidence:
  - >-
    services-commerce at c8b66a98: modules/pricing/services/handovers/audience-handover-realization.ts
    (realizePricingAudienceHandovers); services/persistence/pricing-audience-handovers.ts;
    tests/integration/services/handovers/audience-handover-realization.integration.spec.js.
---

# Special-price handover realization

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> handed_over: Accounting retires a special price
  handed_over --> audience_prepared: rank free
  handed_over --> unresolved: rank taken
  audience_prepared --> realized: binding made, audience active
  audience_prepared --> unresolved: criteria refused
  unresolved --> audience_prepared: later run
  realized --> [*]
```

## Transitions Explained

Handed over: Accounting retained a retired special-price handover whose price row references an audience awaiting creation. Audience prepared: An inactive product-scoped audience exists while binding work remains. Realized: The audience is bound and active, and Accounting’s handover has its completion stamp. Unresolved: A conflicting rank or refused criteria leave work pending with an explanation.

## What Cannot Happen

No implementation clears the realization timestamp.

## Concurrency and Timing

Sequential reruns adopt prepared audiences and skip stamped work. No runtime caller exists, and overlapping realization has no established serialization beyond uniqueness checks.