---
id: STATE-COM-CAT-011
title: Recommendation rule lifecycle
object: DOM-COM-CAT-006
product_area: commerce
module: catalog
revision: 1
status: draft
design_intent: open
implementation_evidence: observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
states:
  - name: draft
    meaning: The rule is available for preparation and produces no offers.
  - name: active
    meaning: Evaluation may use the rule at its bound placements during its permitted dates and store scope.
  - name: paused
    meaning: Evaluation skips the rule while preserving its settings.
  - name: ended
    meaning: 'Evaluation cannot resume the rule, but existing presentations and performance remain.'
  - name: archived
    meaning: The rule has reached its final lifecycle status.
  - name: locked
    meaning: First presentation adds a protected-fields condition; the rule’s lifecycle status remains separate.
transitions:
  - from: draft
    to: active
    trigger: Staff request rule activation.
    guard: >-
      Activation requires valid parameters and action, compatible active placement bindings within limits, and
      fewer than twenty-five active rules at each placement.
    side_effects: []
    who: Selling configuration administrator (commerce.recommendation-rules.activate)
    provenance: test
    source: >-
      services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses
      the twenty-sixth active rule of one placement, too_many_active_rules, naming the placement
  - from: active
    to: paused
    trigger: Staff request a temporary pause.
    guard: The caller must hold rule update authority.
    side_effects: []
    who: Selling configuration administrator
    provenance: observed
    source: 'services-commerce:modules/recommendations/services/rules/rule-workflow.ts:RULE_OPERATIONS'
  - from: paused
    to: active
    trigger: Staff request resumption.
    guard: Activation authority and all placement and rule checks must pass.
    side_effects: []
    who: Selling configuration administrator (commerce.recommendation-rules.activate)
    provenance: test
    source: >-
      services-commerce:modules/recommendations/tests/e2e/recommendations-security.e2e.spec.js#lists the rules
      and the placements, and is refused a create and an activation 403 permission_missing
  - from: active
    to: ended
    trigger: Staff request permanent ending.
    guard: The caller must hold rule update authority.
    side_effects: []
    who: Selling configuration administrator
    provenance: observed
    source: 'services-commerce:modules/recommendations/services/persistence/recommendation-rules.ts'
  - from: paused
    to: ended
    trigger: Staff request permanent ending.
    guard: The caller must hold rule update authority.
    side_effects: []
    who: Selling configuration administrator
    provenance: observed
    source: 'services-commerce:modules/recommendations/services/persistence/recommendation-rules.ts'
  - from: draft
    to: archived
    trigger: Staff archive a prepared rule.
    guard: The caller must hold rule update authority.
    side_effects: []
    who: Selling configuration administrator
    provenance: observed
    source: 'services-commerce:modules/recommendations/services/persistence/recommendation-rules.ts'
  - from: ended
    to: archived
    trigger: Staff archive an ended rule.
    guard: The caller must hold rule update authority.
    side_effects: []
    who: Selling configuration administrator
    provenance: observed
    source: 'services-commerce:modules/recommendations/services/persistence/recommendation-rules.ts'
  - from: active
    to: locked
    trigger: Live evaluation commits the first presentation.
    guard: The transaction containing the presentation must commit.
    side_effects:
      - Presentation insertion also stamps the first protected-fields lock.
    who: Offer evaluation
    provenance: test
    source: >-
      services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses
      the substance of a locked rule, rule_locked, naming the columns, while the message stays editable
invalid:
  - from: archived
    to: active
    why: The final archive status has no activation path.
  - from: ended
    to: active
    why: An ended rule needs a new configuration to run again.
  - from: draft
    to: paused
    why: A rule must be active before pausing.
concurrency: >-
  Rule writes compare versions and presentation commits stamp protected fields. Activation counts the
  placement’s active rules, but concurrent ceiling enforcement lacks established serialization.
invariants:
  - INV-DOM-COM-CAT-006-03
  - INV-DOM-COM-CAT-006-04
evidence:
  - >-
    services-commerce at c8b66a98: modules/recommendations/services/persistence/recommendation-rules.ts
    (RULE_TRANSITIONS, lockRecommendationRules); services/rules/rule-workflow.ts (RULE_OPERATIONS, moveRule);
    db/recommendation-rules.table.ts.
---

# Recommendation rule lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> draft
  draft --> active: activate
  active --> paused: pause
  paused --> active: resume
  active --> ended: end
  paused --> ended: end
  draft --> archived: archive
  ended --> archived: archive
  note right of active: first presentation locks the substance
```

## Transitions Explained

Draft: The rule is available for preparation and produces no offers. Active: Evaluation may use the rule at its bound placements during its permitted dates and store scope. Paused: Evaluation skips the rule while preserving its settings. Ended: Evaluation cannot resume the rule, but existing presentations and performance remain. Archived: The rule has reached its final lifecycle status. Protection is an independent condition and does not replace lifecycle status.

## What Cannot Happen

The final archive status has no activation path. An ended rule needs a new configuration to run again. A rule must be active before pausing.

## Concurrency and Timing

Rule writes compare versions and presentation commits stamp protected fields. Activation counts the placement’s active rules, but concurrent ceiling enforcement lacks established serialization.