Saga Compensation Actions

Every step in a saga has a compensation action — the "undo" that runs if a later step fails.

How Compensation Works

Forward execution:
  Step 1 ✓ → Step 2 ✓ → Step 3 ✗ (fails)

Compensation (reverse order):
  Compensate 2 ✓ → Compensate 1 ✓

Result: System returned to original state

Defining Compensations

When adding a step, specify its compensation:

naos saga add-step order-saga charge-payment --compensate refund-payment

Example: E-Commerce Order

sagas:
  order-fulfillment:
    steps:
      - name: reserve-inventory
        agent: inventory-reserve
        compensate: inventory-release     # Undo: release the reserved items

      - name: charge-payment
        agent: payment-charge
        compensate: payment-refund        # Undo: refund the charge

      - name: ship-order
        agent: shipping-create
        compensate: shipping-cancel       # Undo: cancel shipment

Scenarios

All Steps Succeed

reserve ✓ → charge ✓ → ship ✓
Result: Order fulfilled, no compensation needed

Step 3 Fails

reserve ✓ → charge ✓ → ship ✗
Compensate: refund ✓ → release ✓
Result: Customer refunded, inventory released

Step 2 Fails

reserve ✓ → charge ✗
Compensate: release ✓
Result: Inventory released, no charge to refund

Compensation Best Practices

1. Make compensations idempotent — They might run more than once
2. Log everything — You need to trace what was undone
3. Test compensations — They're as important as the forward steps
4. Handle partial states — Compensations should work even if the forward step partially completed