order.status = "CAMUNDA_JOB_RETRY_2"
order.status = "HTTP_503_FROM_PROVISIONING"
order.status = "DHL_PENDING_PICKUP"

order_line.state = FULFILLING
order_line.last_external_status = DHL_PENDING_PICKUP
order_line.last_error_code = null
camunda_job.retry_count = 2

public Order transition(OrderTransitionCommand command) {
    Order order = orderRepository.findForUpdate(command.orderId());

    OrderTransition transition = transitionRegistry.resolve(
        order.status(),
        command.action()
    );

    if (transition == null) {
        throw new InvalidOrderTransitionException(order.status(), command.action());
    }

    TransitionDecision decision = transition.evaluate(order, command);

    if (!decision.allowed()) {
        throw new TransitionGuardViolationException(decision.reasonCode(), decision.message());
    }

    Order changed = order.apply(decision.nextStatus(), command);
    orderRepository.saveTransition(changed, command, decision);
    outboxRepository.insert(OrderLifecycleEvent.from(changed, command, decision));

    return changed;
}

create table order_line_dependency (
    order_id uuid not null,
    dependent_line_id uuid not null,
    prerequisite_line_id uuid not null,
    dependency_type varchar(40) not null,
    required_state varchar(40) not null,
    created_at timestamptz not null default now(),
    primary key (dependent_line_id, prerequisite_line_id),
    foreign key (order_id, dependent_line_id) references order_line(order_id, order_line_id),
    foreign key (order_id, prerequisite_line_id) references order_line(order_id, order_line_id),
    check (dependent_line_id <> prerequisite_line_id)
);

public void assertAcyclic(List<OrderLine> lines, List<OrderLineDependency> dependencies) {
    DirectedGraph<UUID> graph = DirectedGraph.from(dependencies);
    if (graph.hasCycle()) {
        throw new InvalidOrderGraphException("ORDER_LINE_DEPENDENCY_CYCLE");
    }
}

if all mandatory lines are successful_terminal:
    root = COMPLETED
else if any line is in failure_terminal and no repair plan exists:
    root = FAILED
else if any line is active_or_pending and at least one line is fulfilled:
    root = PARTIALLY_COMPLETED
else if any line is active_or_pending:
    root = IN_PROGRESS

create table customer_order (
    order_id uuid primary key,
    tenant_id uuid not null,
    customer_id uuid not null,
    source_quote_id uuid not null,
    source_quote_version int not null,
    status varchar(40) not null,
    status_reason_code varchar(80),
    lifecycle_version bigint not null default 0,
    submitted_at timestamptz not null,
    started_at timestamptz,
    completed_at timestamptz,
    cancelled_at timestamptz,
    failed_at timestamptz,
    created_at timestamptz not null default now(),
    updated_at timestamptz not null default now(),
    check (status in (
        'CAPTURED',
        'VALIDATING',
        'READY_FOR_FULFILLMENT',
        'IN_PROGRESS',
        'SUSPENDED',
        'PARTIALLY_COMPLETED',
        'COMPLETED',
        'CANCELLING',
        'CANCELLED',
        'FAILED'
    ))
);

create index idx_customer_order_tenant_status
    on customer_order (tenant_id, status, updated_at desc);

create index idx_customer_order_source_quote
    on customer_order (tenant_id, source_quote_id, source_quote_version);

create table order_line (
    order_id uuid not null,
    order_line_id uuid not null,
    tenant_id uuid not null,
    source_quote_line_id uuid not null,
    line_type varchar(60) not null,
    fulfillment_type varchar(60) not null,
    status varchar(40) not null,
    status_reason_code varchar(80),
    mandatory boolean not null default true,
    sequence_no int not null,
    lifecycle_version bigint not null default 0,
    external_system varchar(80),
    external_reference varchar(160),
    last_external_status varchar(120),
    last_error_code varchar(120),
    last_error_message text,
    ready_at timestamptz,
    started_at timestamptz,
    fulfilled_at timestamptz,
    cancelled_at timestamptz,
    failed_at timestamptz,
    created_at timestamptz not null default now(),
    updated_at timestamptz not null default now(),
    primary key (order_id, order_line_id),
    check (status in (
        'CREATED',
        'WAITING_DEPENDENCY',
        'READY',
        'RESERVED',
        'FULFILLING',
        'FULFILLED',
        'BLOCKED',
        'FAILED_RETRYABLE',
        'FAILED_TERMINAL',
        'CANCELLING',
        'CANCELLED',
        'COMPENSATED',
        'SKIPPED'
    ))
);

create index idx_order_line_status
    on order_line (tenant_id, status, updated_at desc);

create index idx_order_line_external_ref
    on order_line (tenant_id, external_system, external_reference)
    where external_reference is not null;

create table order_transition_history (
    transition_id uuid primary key,
    tenant_id uuid not null,
    order_id uuid not null,
    order_line_id uuid,
    entity_type varchar(20) not null,
    from_status varchar(40),
    to_status varchar(40) not null,
    action varchar(80) not null,
    reason_code varchar(120),
    reason_message text,
    actor_type varchar(40) not null,
    actor_id varchar(160) not null,
    command_id uuid not null,
    correlation_id varchar(120),
    causation_id varchar(120),
    metadata jsonb not null default '{}'::jsonb,
    occurred_at timestamptz not null default now(),
    check (entity_type in ('ORDER', 'ORDER_LINE'))
);

create index idx_order_transition_history_order
    on order_transition_history (tenant_id, order_id, occurred_at asc);

create unique index uq_order_transition_command
    on order_transition_history (tenant_id, command_id, entity_type, coalesce(order_line_id, '00000000-0000-0000-0000-000000000000'::uuid));

public record OrderTransitionCommand(
    UUID commandId,
    UUID tenantId,
    UUID orderId,
    OrderAction action,
    String reasonCode,
    String reasonMessage,
    Actor actor,
    String correlationId,
    String causationId,
    Map<String, Object> metadata,
    Long expectedLifecycleVersion
) {}

public record OrderLineTransitionCommand(
    UUID commandId,
    UUID tenantId,
    UUID orderId,
    UUID orderLineId,
    OrderLineAction action,
    String externalSystem,
    String externalReference,
    String externalStatus,
    String errorCode,
    String errorMessage,
    Actor actor,
    String correlationId,
    String causationId,
    Long expectedLifecycleVersion
) {}

<update id="transitionOrderStatus">
  update customer_order
  set status = #{toStatus},
      status_reason_code = #{reasonCode},
      lifecycle_version = lifecycle_version + 1,
      updated_at = now(),
      started_at = case
          when #{toStatus} = 'IN_PROGRESS' and started_at is null then now()
          else started_at
      end,
      completed_at = case
          when #{toStatus} = 'COMPLETED' then now()
          else completed_at
      end,
      cancelled_at = case
          when #{toStatus} = 'CANCELLED' then now()
          else cancelled_at
      end,
      failed_at = case
          when #{toStatus} = 'FAILED' then now()
          else failed_at
      end
  where tenant_id = #{tenantId}
    and order_id = #{orderId}
    and status = #{fromStatus}
    and lifecycle_version = #{expectedLifecycleVersion}
</update>

<insert id="insertTransitionHistory">
  insert into order_transition_history (
      transition_id,
      tenant_id,
      order_id,
      order_line_id,
      entity_type,
      from_status,
      to_status,
      action,
      reason_code,
      reason_message,
      actor_type,
      actor_id,
      command_id,
      correlation_id,
      causation_id,
      metadata
  ) values (
      #{transitionId},
      #{tenantId},
      #{orderId},
      #{orderLineId},
      #{entityType},
      #{fromStatus},
      #{toStatus},
      #{action},
      #{reasonCode},
      #{reasonMessage},
      #{actorType},
      #{actorId},
      #{commandId},
      #{correlationId},
      #{causationId},
      #{metadata,typeHandler=com.acme.platform.mybatis.JsonbTypeHandler}
  )
</insert>

int changed = mapper.transitionOrderStatus(params);
if (changed == 0) {
    throw new OptimisticLifecycleConflictException(command.orderId(), command.expectedLifecycleVersion());
}

public final class OrderTransitionRegistry {

    private final Map<OrderStatus, Map<OrderAction, OrderTransition>> transitions;

    public OrderTransitionRegistry() {
        this.transitions = Map.of(
            OrderStatus.CAPTURED, Map.of(
                OrderAction.START_VALIDATION, transitionTo(OrderStatus.VALIDATING, this::canStartValidation),
                OrderAction.REQUEST_CANCEL, transitionTo(OrderStatus.CANCELLING, this::canCancelBeforeStart)
            ),
            OrderStatus.VALIDATING, Map.of(
                OrderAction.MARK_VALIDATED, transitionTo(OrderStatus.READY_FOR_FULFILLMENT, this::validationPassed),
                OrderAction.MARK_VALIDATION_FAILED, transitionTo(OrderStatus.FAILED, this::validationTerminalFailed),
                OrderAction.REQUEST_CANCEL, transitionTo(OrderStatus.CANCELLING, this::canCancelDuringValidation)
            ),
            OrderStatus.READY_FOR_FULFILLMENT, Map.of(
                OrderAction.START_FULFILLMENT, transitionTo(OrderStatus.IN_PROGRESS, this::hasStartableLines),
                OrderAction.REQUEST_CANCEL, transitionTo(OrderStatus.CANCELLING, this::canCancelBeforeFulfillment)
            ),
            OrderStatus.IN_PROGRESS, Map.of(
                OrderAction.SUSPEND, transitionTo(OrderStatus.SUSPENDED, this::hasValidHoldReason),
                OrderAction.MARK_COMPLETED, transitionTo(OrderStatus.COMPLETED, this::allRequiredLinesDone),
                OrderAction.REQUEST_CANCEL, transitionTo(OrderStatus.CANCELLING, this::canCancelInProgress)
            ),
            OrderStatus.SUSPENDED, Map.of(
                OrderAction.RESUME, transitionTo(OrderStatus.IN_PROGRESS, this::holdResolved),
                OrderAction.REQUEST_CANCEL, transitionTo(OrderStatus.CANCELLING, this::canCancelSuspended)
            )
        );
    }
}

{
  "eventId": "0191fb7e-3e61-7db8-81a4-cf0bd521d7a2",
  "eventType": "OrderStatusChanged",
  "eventVersion": 1,
  "occurredAt": "2026-07-02T10:15:30Z",
  "tenantId": "6b98f40b-6c4e-4ce2-8932-9e39e2eab981",
  "aggregateType": "ORDER",
  "aggregateId": "4d3c6a3b-0d9f-4c2b-94fb-390d7bcb2b3a",
  "aggregateVersion": 8,
  "correlationId": "req-8d318",
  "causationId": "cmd-fd912",
  "payload": {
    "fromStatus": "READY_FOR_FULFILLMENT",
    "toStatus": "IN_PROGRESS",
    "action": "START_FULFILLMENT",
    "reasonCode": "FULFILLMENT_STARTED",
    "actor": {
      "type": "SYSTEM",
      "id": "order-orchestrator"
    }
  }
}

IN_PROGRESS -> CANCELLING -> CANCELLED

FULFILLED -> COMPENSATED
FULFILLING -> CANCELLING -> CANCELLED
READY -> CANCELLED
FAILED_TERMINAL -> COMPENSATED or FAILED remains

{
  "action": "REQUEST_CANCEL",
  "reasonCode": "CUSTOMER_REQUEST",
  "requestedBy": "user:agent-123",
  "scope": "ORDER",
  "requestedAt": "2026-07-02T10:00:00Z"
}

TRANSIENT_TECHNICAL -> FAILED_RETRYABLE
EXTERNAL_BUSINESS_BLOCKER -> BLOCKED
INVALID_ORDER_DATA -> FAILED_TERMINAL
DEPENDENCY_FAILURE -> BLOCKED or FAILED_TERMINAL
POLICY_FAILURE -> SUSPENDED or FAILED
UNKNOWN -> FAILED_RETRYABLE + incident

@Path("/v1/orders/{orderId}/lifecycle")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class OrderLifecycleResource {

    @POST
    @Path("transitions")
    public Response transitionOrder(
        @PathParam("orderId") UUID orderId,
        @HeaderParam("Idempotency-Key") String idempotencyKey,
        OrderTransitionRequest request
    ) {
        OrderTransitionResult result = lifecycleService.transitionOrder(
            mapper.toCommand(orderId, idempotencyKey, request)
        );
        return Response.ok(mapper.toResponse(result)).build();
    }

    @POST
    @Path("lines/{lineId}/transitions")
    public Response transitionLine(
        @PathParam("orderId") UUID orderId,
        @PathParam("lineId") UUID lineId,
        @HeaderParam("Idempotency-Key") String idempotencyKey,
        OrderLineTransitionRequest request
    ) {
        OrderLineTransitionResult result = lifecycleService.transitionLine(
            mapper.toCommand(orderId, lineId, idempotencyKey, request)
        );
        return Response.ok(mapper.toResponse(result)).build();
    }
}

select o.order_id
from customer_order o
where o.status = 'IN_PROGRESS'
  and not exists (
      select 1
      from order_line l
      where l.order_id = o.order_id
        and l.mandatory = true
        and l.status not in ('FULFILLED', 'COMPENSATED', 'SKIPPED')
  );

@ParameterizedTest
@MethodSource("validTransitions")
void validTransitionsAreAllowed(OrderStatus from, OrderAction action, OrderStatus to) {
    OrderTransition transition = registry.resolve(from, action);
    assertThat(transition).isNotNull();
    assertThat(transition.nextStatus()).isEqualTo(to);
}