Skip to content

ADR-020 — Object Lifecycle Model

Status

Accepted

Context

UC-BoK models Business Objects (ADR-007) and Domain Events (ADR-009), but does not formally specify the valid states a Business Object can occupy, or the allowed transitions between those states. This creates three problems:

  1. Integration ambiguity — system integrators must infer valid state sequences from process diagrams or vendor documentation, leading to inconsistent implementations.
  2. Event orphaning — domain events such as order-confirmed or return-approved are defined but not anchored to a source state or target state in the canonical model.
  3. Assessment gaps — the UCMI maturity model cannot assess whether a platform handles the complete lifecycle of a business object (e.g. does it support partial fulfilment? split orders? post-delivery returns?).

A formal lifecycle model resolves all three by making state machines a first-class citizen of the UC-BoK knowledge graph.

Decision

UC-BoK introduces an Object Lifecycle Model as a new catalog layer under catalogs/lifecycles/.

Lifecycle definition

Each lifecycle YAML defines:

Field Required Description
id ✓ Stable kebab-case identifier (e.g. order-lifecycle)
name ✓ Display name
object ✓ Reference to the Business Object id it models
description ✓ Purpose and scope
states ✓ Ordered list of valid states
transitions ✓ Allowed state transitions

State definition

states:
  - id: draft          # kebab-case
    label: Draft       # display
    description: ...
    initial: true      # exactly one state per lifecycle
    terminal: false    # true for end states

Transition definition

transitions:
  - id: confirm-order
    from: draft
    to: confirmed
    trigger: order-confirmed     # domain event id (from events.yaml)
    guards:                      # pre-conditions (plain language)
      - Payment authorization obtained
      - All lines have available stock
    notes: ...                   # optional

Invariants

  1. Every lifecycle has exactly one initial: true state.
  2. Terminal states have no outbound transitions.
  3. Every trigger must resolve to an event id in catalogs/events.yaml.
  4. Every from and to must reference a valid state id in the same lifecycle.
  5. A state may have multiple inbound transitions (fan-in is allowed).
  6. A state may have multiple outbound transitions (fan-out is allowed, guards distinguish them).

Scope

The initial set covers the five Aggregate Root objects with the highest process coverage in UC-BoK:

Object Lifecycle id
order order-lifecycle
basket basket-lifecycle
return return-lifecycle
fulfillment-order fulfillment-order-lifecycle
payment payment-lifecycle

Future work: reservation, shipment, loyalty-account.

Consequences

  • catalogs/lifecycles/*.yaml is the canonical source of truth for object lifecycles.
  • Domain events classified as transitioned in events.yaml must be reachable from at least one lifecycle transition trigger.
  • scripts/generate_lifecycle_docs.py generates Mermaid stateDiagram-v2 diagrams and transition tables for each lifecycle.
  • Two new MCP tools expose lifecycle data to AI agents: list_lifecycles and get_lifecycle.
  • The UCMI assessment engine may reference lifecycle completeness in future scoring.
  • Lifecycle state ids are intentionally lowercase kebab-case (not SCREAMING_SNAKE) to stay consistent with UC-BoK identifier conventions.
  • ADR-007 Business Object Ontology
  • ADR-009 Event Ontology
  • ADR-012 Semantic Constraints