{
  "feature": "cart-checkout",
  "version": "1.0.0",
  "description": "Shopping cart and checkout flow with stock reservation, guest cart merge, multi-step checkout, tax, promo codes, and order placement.",
  "category": "payment",
  "tags": [
    "cart",
    "checkout",
    "e-commerce",
    "orders",
    "stock-reservation",
    "promo-codes"
  ],
  "fields": [
    {
      "name": "cart_id",
      "type": "text",
      "label": "Cart ID",
      "required": true,
      "validation": [
        {
          "type": "pattern",
          "value": "^cart_[a-zA-Z0-9]+$",
          "message": "Cart ID must match the required format"
        }
      ]
    },
    {
      "name": "customer_id",
      "type": "text",
      "label": "Customer ID",
      "required": false
    },
    {
      "name": "items",
      "type": "json",
      "label": "Cart Items",
      "required": true
    },
    {
      "name": "subtotal",
      "type": "number",
      "label": "Subtotal",
      "required": true,
      "validation": [
        {
          "type": "min",
          "value": 0,
          "message": "Subtotal must be zero or greater"
        }
      ]
    },
    {
      "name": "tax",
      "type": "number",
      "label": "Tax Amount",
      "required": true,
      "validation": [
        {
          "type": "min",
          "value": 0,
          "message": "Tax amount must be zero or greater"
        }
      ]
    },
    {
      "name": "shipping_cost",
      "type": "number",
      "label": "Shipping Cost",
      "required": true,
      "validation": [
        {
          "type": "min",
          "value": 0,
          "message": "Shipping cost must be zero or greater"
        }
      ]
    },
    {
      "name": "discount",
      "type": "number",
      "label": "Discount Amount",
      "required": false,
      "validation": [
        {
          "type": "min",
          "value": 0,
          "message": "Discount amount must be zero or greater"
        }
      ]
    },
    {
      "name": "total",
      "type": "number",
      "label": "Order Total",
      "required": true,
      "validation": [
        {
          "type": "min",
          "value": 0,
          "message": "Order total must be zero or greater"
        }
      ]
    },
    {
      "name": "promo_code",
      "type": "text",
      "label": "Promo Code",
      "required": false
    },
    {
      "name": "checkout_step",
      "type": "select",
      "label": "Checkout Step",
      "required": true,
      "options": [
        {
          "value": "cart",
          "label": "Cart"
        },
        {
          "value": "address",
          "label": "Address"
        },
        {
          "value": "shipping",
          "label": "Shipping"
        },
        {
          "value": "payment",
          "label": "Payment"
        },
        {
          "value": "review",
          "label": "Review"
        },
        {
          "value": "confirmed",
          "label": "Confirmed"
        }
      ]
    },
    {
      "name": "shipping_address",
      "type": "json",
      "label": "Shipping Address",
      "required": false
    },
    {
      "name": "billing_address",
      "type": "json",
      "label": "Billing Address",
      "required": false
    },
    {
      "name": "shipping_method",
      "type": "text",
      "label": "Shipping Method",
      "required": false
    },
    {
      "name": "payment_method_id",
      "type": "text",
      "label": "Payment Method",
      "required": false
    },
    {
      "name": "order_id",
      "type": "text",
      "label": "Order ID",
      "required": false
    }
  ],
  "states": {
    "field": "checkout_step",
    "values": [
      {
        "name": "cart",
        "description": "Customer is browsing and adding items to cart",
        "initial": true
      },
      {
        "name": "address",
        "description": "Customer entering shipping and billing addresses"
      },
      {
        "name": "shipping",
        "description": "Customer selecting shipping method"
      },
      {
        "name": "payment",
        "description": "Customer selecting payment method"
      },
      {
        "name": "review",
        "description": "Customer reviewing order summary before placing"
      },
      {
        "name": "confirmed",
        "description": "Order placed successfully",
        "terminal": true
      }
    ],
    "transitions": [
      {
        "from": "cart",
        "to": "address",
        "actor": "customer",
        "description": "Customer proceeds to checkout with items in cart",
        "condition": "Cart has at least one item and all items are in stock"
      },
      {
        "from": "address",
        "to": "shipping",
        "actor": "customer",
        "description": "Customer submits valid shipping address",
        "condition": "All required address fields populated"
      },
      {
        "from": "shipping",
        "to": "payment",
        "actor": "customer",
        "description": "Customer selects a shipping method",
        "condition": "Valid shipping method selected for destination"
      },
      {
        "from": "payment",
        "to": "review",
        "actor": "customer",
        "description": "Customer selects a payment method",
        "condition": "Valid payment method provided"
      },
      {
        "from": "review",
        "to": "confirmed",
        "actor": "customer",
        "description": "Customer places the order",
        "condition": "Payment authorized, stock confirmed"
      },
      {
        "from": [
          "address",
          "shipping",
          "payment",
          "review"
        ],
        "to": "cart",
        "actor": "customer",
        "description": "Customer returns to cart to modify items"
      }
    ]
  },
  "rules": {
    "stock_reservation": {
      "description": "When an item is added to cart, inventory is soft-reserved for 15 minutes. Reservation refreshes on cart activity. If the cart is inactive for 15 minutes, reservations are released.\n"
    },
    "cart_expiry": {
      "description": "Abandoned carts expire after 30 days. Guest carts expire after 7 days. Expiry releases all stock reservations.\n"
    },
    "guest_cart_merge": {
      "description": "When a guest user logs in, their guest cart merges into their account cart. Duplicate items have quantities summed. Conflicts (e.g., stock limits) are resolved in favor of the newest item.\n"
    },
    "quantity_validation": {
      "description": "Item quantity must be at least 1 and cannot exceed available stock. Attempting to add more than available stock shows the maximum available quantity.\n"
    },
    "total_calculation": {
      "description": "Order total = subtotal + tax + shipping_cost - discount. Recalculated on every cart or checkout modification.\n"
    },
    "promo_code_validation": {
      "description": "Promo codes are validated against active promotions. A code may be percentage-based or fixed-amount. Only one promo code per order. Invalid or expired codes return an error.\n"
    },
    "tax_calculation": {
      "description": "Tax calculated based on shipping destination, product tax category, and applicable tax rules. Recalculated when address or items change.\n"
    }
  },
  "outcomes": {
    "item_added_to_cart": {
      "priority": 1,
      "given": [
        "customer adds a product to cart",
        "product is in stock",
        "requested quantity is available"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "items",
          "description": "Product added to items array or quantity incremented"
        },
        {
          "action": "set_field",
          "target": "subtotal",
          "description": "Recalculated from item line totals"
        },
        {
          "action": "emit_event",
          "event": "cart.item_added",
          "payload": [
            "cart_id",
            "product_id",
            "quantity",
            "unit_price"
          ]
        }
      ],
      "result": "Item added to cart, subtotal updated, stock reserved for 15 minutes",
      "error": "CART_STOCK_RESERVATION_EXPIRED"
    },
    "item_removed_from_cart": {
      "priority": 2,
      "given": [
        "customer removes an item from cart",
        "item exists in cart"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "items",
          "description": "Item removed from items array"
        },
        {
          "action": "set_field",
          "target": "subtotal",
          "description": "Recalculated from remaining items"
        },
        {
          "action": "emit_event",
          "event": "cart.item_removed",
          "payload": [
            "cart_id",
            "product_id",
            "quantity_released"
          ]
        }
      ],
      "result": "Item removed from cart, stock reservation released, totals recalculated"
    },
    "item_quantity_updated": {
      "priority": 3,
      "given": [
        "customer updates item quantity in cart",
        "new quantity is between 1 and available stock"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "items",
          "description": "Quantity updated for the specified item"
        },
        {
          "action": "set_field",
          "target": "subtotal",
          "description": "Recalculated with new quantity"
        }
      ],
      "result": "Cart item quantity updated, totals recalculated"
    },
    "promo_code_applied": {
      "priority": 4,
      "given": [
        "customer enters a promo code",
        "promo code is valid and active",
        "cart meets minimum requirements for the promotion"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "promo_code",
          "description": "Promo code stored on cart"
        },
        {
          "action": "set_field",
          "target": "discount",
          "description": "Discount calculated from promo rules"
        },
        {
          "action": "set_field",
          "target": "total",
          "description": "Recalculated with discount applied"
        }
      ],
      "result": "Promo code applied, discount reflected in order total"
    },
    "checkout_started": {
      "priority": 5,
      "given": [
        "customer proceeds from cart to checkout",
        "cart has at least one item"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "checkout_step",
          "from": "cart",
          "to": "address"
        },
        {
          "action": "emit_event",
          "event": "checkout.started",
          "payload": [
            "cart_id",
            "customer_id",
            "item_count",
            "subtotal"
          ]
        }
      ],
      "result": "Checkout flow initiated, customer enters address step"
    },
    "order_placed": {
      "priority": 6,
      "given": [
        {
          "field": "checkout_step",
          "operator": "eq",
          "value": "review"
        },
        "payment is authorized",
        "all items are in stock"
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "checkout_step",
          "from": "review",
          "to": "confirmed"
        },
        {
          "action": "create_record",
          "type": "order",
          "target": "order",
          "description": "Order record created from cart data"
        },
        {
          "action": "set_field",
          "target": "order_id",
          "description": "Generated order ID assigned"
        },
        {
          "action": "emit_event",
          "event": "checkout.completed",
          "payload": [
            "cart_id",
            "order_id",
            "total"
          ]
        },
        {
          "action": "emit_event",
          "event": "order.placed",
          "payload": [
            "order_id",
            "customer_id",
            "items",
            "total",
            "shipping_method"
          ]
        }
      ],
      "result": "Order placed, payment captured, stock committed, confirmation sent",
      "transaction": true
    },
    "guest_cart_merged": {
      "priority": 7,
      "given": [
        "guest user logs in",
        "guest cart has items",
        "user has an existing account cart"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "items",
          "description": "Guest items merged into account cart"
        },
        {
          "action": "set_field",
          "target": "subtotal",
          "description": "Recalculated from merged items"
        }
      ],
      "result": "Guest cart merged into account cart, duplicates consolidated"
    },
    "cart_empty": {
      "priority": 1,
      "error": "CART_EMPTY",
      "given": [
        "customer attempts to checkout",
        {
          "field": "items",
          "operator": "not_exists"
        }
      ],
      "then": [
        {
          "action": "notify",
          "channel": "ui",
          "description": "Inform customer that cart is empty"
        }
      ],
      "result": "Cannot proceed to checkout with an empty cart"
    },
    "item_out_of_stock": {
      "priority": 2,
      "error": "CART_ITEM_OUT_OF_STOCK",
      "given": [
        "customer adds an item to cart",
        "requested quantity exceeds available stock"
      ],
      "then": [
        {
          "action": "notify",
          "channel": "ui",
          "description": "Show available stock quantity"
        }
      ],
      "result": "Item cannot be added, insufficient stock"
    },
    "promo_code_invalid": {
      "priority": 3,
      "error": "CART_PROMO_INVALID",
      "given": [
        "customer enters a promo code",
        "code is invalid, expired, or already used"
      ],
      "then": [
        {
          "action": "notify",
          "channel": "ui",
          "description": "Inform customer the promo code is not valid"
        }
      ],
      "result": "Promo code rejected"
    }
  },
  "errors": [
    {
      "code": "CART_EMPTY",
      "message": "Your cart is empty. Add items before proceeding to checkout.",
      "status": 400
    },
    {
      "code": "CART_ITEM_OUT_OF_STOCK",
      "message": "The requested quantity is not available. Please reduce the quantity or choose a different item.",
      "status": 409
    },
    {
      "code": "CART_PROMO_INVALID",
      "message": "The promo code is invalid, expired, or has already been used.",
      "status": 400
    },
    {
      "code": "CART_STOCK_RESERVATION_EXPIRED",
      "message": "Stock reservation has expired. Please verify item availability.",
      "status": 409
    },
    {
      "code": "CHECKOUT_PAYMENT_FAILED",
      "message": "Payment could not be authorized. Please try a different payment method.",
      "status": 422
    },
    {
      "code": "CHECKOUT_ADDRESS_INVALID",
      "message": "The shipping address is incomplete or invalid.",
      "status": 400
    }
  ],
  "events": [
    {
      "name": "cart.item_added",
      "description": "Item added to shopping cart",
      "payload": [
        "cart_id",
        "product_id",
        "quantity",
        "unit_price"
      ]
    },
    {
      "name": "cart.item_removed",
      "description": "Item removed from shopping cart",
      "payload": [
        "cart_id",
        "product_id",
        "quantity_released"
      ]
    },
    {
      "name": "checkout.started",
      "description": "Customer initiated checkout flow",
      "payload": [
        "cart_id",
        "customer_id",
        "item_count",
        "subtotal"
      ]
    },
    {
      "name": "checkout.completed",
      "description": "Checkout completed and order placed",
      "payload": [
        "cart_id",
        "order_id",
        "total"
      ]
    },
    {
      "name": "order.placed",
      "description": "New order created from cart",
      "payload": [
        "order_id",
        "customer_id",
        "items",
        "total",
        "shipping_method"
      ]
    }
  ],
  "related": [
    {
      "feature": "payment-methods",
      "type": "required",
      "reason": "Checkout requires a payment method for order placement"
    },
    {
      "feature": "shipping-calculation",
      "type": "required",
      "reason": "Shipping rates calculated during checkout"
    },
    {
      "feature": "currency-conversion",
      "type": "optional",
      "reason": "Multi-currency cart display and checkout"
    },
    {
      "feature": "refunds-returns",
      "type": "optional",
      "reason": "Post-purchase returns and refunds for placed orders"
    },
    {
      "feature": "subscription-billing",
      "type": "optional",
      "reason": "Cart may include subscription products"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_cart_checkout",
        "description": "Shopping cart and checkout flow with stock reservation, guest cart merge, multi-step checkout, tax, promo codes, and order placement.",
        "success_metrics": [
          {
            "metric": "policy_violation_rate",
            "target": "0%",
            "measurement": "Operations that violate defined policies"
          },
          {
            "metric": "audit_completeness",
            "target": "100%",
            "measurement": "All decisions have complete audit trails"
          }
        ],
        "constraints": [
          {
            "type": "regulatory",
            "description": "All operations must be auditable and traceable",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before transitioning to a terminal state",
        "before permanently deleting records"
      ],
      "escalation_triggers": [
        "error_rate > 5",
        "consecutive_failures > 3"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "item_added_to_cart",
          "permission": "autonomous"
        },
        {
          "action": "item_removed_from_cart",
          "permission": "human_required"
        },
        {
          "action": "item_quantity_updated",
          "permission": "supervised"
        },
        {
          "action": "promo_code_applied",
          "permission": "autonomous"
        },
        {
          "action": "checkout_started",
          "permission": "autonomous"
        },
        {
          "action": "order_placed",
          "permission": "autonomous"
        },
        {
          "action": "guest_cart_merged",
          "permission": "autonomous"
        },
        {
          "action": "cart_empty",
          "permission": "autonomous"
        },
        {
          "action": "item_out_of_stock",
          "permission": "autonomous"
        },
        {
          "action": "promo_code_invalid",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accuracy",
        "over": "speed",
        "reason": "financial transactions must be precise and auditable"
      }
    ],
    "verification": {
      "invariants": [
        "error messages never expose internal system details",
        "state transitions follow the defined state machine — no illegal transitions"
      ]
    },
    "coordination": {
      "protocol": "request_response",
      "consumes": [
        {
          "capability": "payment_methods",
          "from": "payment-methods",
          "fallback": "fail"
        },
        {
          "capability": "shipping_calculation",
          "from": "shipping-calculation",
          "fallback": "fail"
        }
      ]
    }
  }
}