feat!: update Order capability (Universal-Commerce-Protocol#254)

* fix(order): soften append-only and immutable language on adjustments and line items
* fix(order): remove quantity derivation language
* feat(order): model Order:Checkout as 1:N relationship
* feat(order): signed quantities/amounts, net exchange amounts, quantity.original
* fix(order): rename adjustment amount to totals for consistency

* fix(order): compose adjustment totals from total.json with signed_amount override
Align with the composition pattern in PR Universal-Commerce-Protocol#261 (totals contract):
allOf total.json base + signed_amount.json override, rather than
inlining the schema.

* fix(order): address review feedback on adjustments and status derivation
- SHOULD append-only adjustments, MAY update in-place
- Guard status derivation against quantity.total == 0 edge case

* fix(order): wrap long prose lines to match spec conventions

Author: richmolj

docs/index.md

@@ -367,8 +367,8 @@ image: assets/banner.png
         "type": "refund",
         "occurred_at": "2026-01-12T14:30:00Z",
         "status": "completed",
-        "line_items": [{ "id": "li_1", "quantity": 1 }],
-        "amount": 26550,
+        "line_items": [{ "id": "li_1", "quantity": -1 }],
+        "totals": [{ "type": "total", "amount": -26550 }],
         "description": "Defective item"
       }
     ],

docs/specification/order.md

@@ -31,17 +31,23 @@ Orders have three main components:
 **Line Items** — what was purchased at checkout:
 
 * Includes current quantity counts (total, fulfilled)
+* Can change post-order (e.g. order edits, exchanges); **MUST** include all
+  line items that ever existed on the order regardless of edits or alterations
 
 **Fulfillment** — how items get delivered:
 
 * **Expectations** — buyer-facing *promises* about when/how items will arrive
 * **Events** (append-only log) — what actually happened (e.g. 👕 was shipped)
 
-**Adjustments** (append-only log) — post-order events independent of fulfillment:
+**Adjustments** — post-order events independent of fulfillment:
 
 * Typically money movements (refunds, returns, credits, disputes, cancellations)
 * Can be any post-order change
 * Can happen before, during, or after fulfillment
+* Businesses SHOULD append new entries rather than mutating existing ones;
+  append-only ledger is preferred. Businesses that do not maintain adjustment
+  history MAY perform in-place updates of existing entries
+  (e.g. a single `return` adjustment can transition from `pending` to `completed`)
 
 ## Data Model
 
@@ -50,7 +56,7 @@ Orders have three main components:
 Line items reflect what was purchased at checkout and their current state:
 
 * Item details (product, price, quantity ordered)
-* Quantity counts and status are derived
+* Quantity counts and fulfillment status
 
 ### Fulfillment
 
@@ -83,15 +89,17 @@ Expectations can be split, merged, or adjusted post-order. For example:
 
 ### Adjustments
 
-**Adjustments** are an append-only log of events that exist independently of
+**Adjustments** are post-order events that exist independently of
 fulfillment:
 
 * Type is an open string field - businesses can use any values that make sense
   (typically money movements like `refund`, `return`, `credit`,
   `price_adjustment`, `dispute`, `cancellation`)
 * Can be any post-order change
 * Optionally link to line items (or order-level for things like shipping refunds)
-* Include amount when relevant
+* Quantities and amounts are signed—negative for reductions (returns, refunds),
+  positive for additions (exchanges)
+* Include totals breakdown when relevant
 * Can happen at any time regardless of fulfillment status
 
 ## Schema
@@ -103,23 +111,24 @@ fulfillment:
 ### Order Line Item
 
 Line items reflect what was purchased at checkout and their current state.
-Status and quantity counts should reflect the event logs.
 
 {{ schema_fields('order_line_item', 'order') }}
 
 **Quantity Structure:**
 
 ```json
 {
-  "total": 3,      // Current total quantity
+  "original": 3,   // Quantity from the original checkout
+  "total": 3,      // Current total (may differ after edits/exchanges)
   "fulfilled": 2   // What has been fulfilled
 }
 ```
 
 **Status Derivation:**
 
 ```text
-if (fulfilled == total) → "fulfilled"
+if (total == 0) → "removed"
+else if (fulfilled == total) → "fulfilled"
 else if (fulfilled > 0) → "partial"
 else → "processing"
 ```
@@ -171,7 +180,7 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
     {
       "id": "li_shoes",
       "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 },
-      "quantity": { "total": 3, "fulfilled": 3 },
+      "quantity": { "original": 3, "total": 3, "fulfilled": 3 },
       "totals": [
         {"type": "subtotal", "amount": 9000},
         {"type": "total", "amount": 9000}
@@ -181,7 +190,7 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
     {
       "id": "li_shirts",
       "item": { "id": "prod_shirts", "title": "Cotton T-Shirt", "price": 2000 },
-      "quantity": { "total": 2, "fulfilled": 0 },
+      "quantity": { "original": 2, "total": 2, "fulfilled": 0 },
       "totals": [
         {"type": "subtotal", "amount": 4000},
         {"type": "total", "amount": 4000}
@@ -238,8 +247,10 @@ Examples: `refund`, `return`, `credit`, `price_adjustment`, `dispute`,
       "type": "refund",
       "occurred_at": "2025-01-10T14:30:00Z",
       "status": "completed",
-      "line_items": [{ "id": "li_shoes", "quantity": 1 }],
-      "amount": 3000,
+      "line_items": [{ "id": "li_shoes", "quantity": -1 }],
+      "totals": [
+        { "type": "total", "amount": -3000 }
+      ],
       "description": "Defective item"
     }
   ],

source/schemas/shopping/order.json

@@ -3,7 +3,7 @@
   "$id": "https://ucp.dev/schemas/shopping/order.json",
   "name": "dev.ucp.shopping.order",
   "title": "Order",
-  "description": "Order schema with immutable line items, buyer-facing fulfillment expectations, and append-only event logs.",
+  "description": "Order schema with line items, buyer-facing fulfillment expectations, and event logs.",
   "$defs": {
     "platform_schema": {
       "title": "Platform Order Schema",
@@ -53,7 +53,7 @@
       "items": {
         "$ref": "types/order_line_item.json"
       },
-      "description": "Immutable line items — source of truth for what was ordered."
+      "description": "Line items representing what was purchased — can change post-order via edits or exchanges."
     },
     "fulfillment": {
       "type": "object",
@@ -80,7 +80,7 @@
       "items": {
         "$ref": "types/adjustment.json"
       },
-      "description": "Append-only event log of money movements (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment."
+      "description": "Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment."
     },
     "currency": {
       "type": "string",

source/schemas/shopping/types/adjustment.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://ucp.dev/schemas/shopping/types/adjustment.json",
   "title": "Adjustment",
-  "description": "Append-only event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.",
+  "description": "Post-order event that exists independently of fulfillment. Typically represents money movements but can be any post-order change. Polymorphic type that can optionally reference line items.",
   "type": "object",
   "required": [
     "id",
@@ -45,16 +45,18 @@
           },
           "quantity": {
             "type": "integer",
-            "minimum": 1,
-            "description": "Quantity affected by this adjustment."
+            "description": "Signed quantity affected by this adjustment. Negative values represent reductions (e.g. returns); positive values represent additions (e.g. exchanges)."
           }
         }
       },
       "description": "Which line items and quantities are affected (optional)."
     },
-    "amount": {
-      "$ref": "amount.json",
-      "description": "Amount in ISO 4217 minor units for refunds, credits, or price adjustments."
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "total.json"
+      },
+      "description": "Adjustment totals breakdown. Signed values - negative for money returned to buyer (refunds, credits), positive for additional charges (exchanges)."
     },
     "description": {
       "type": "string",

source/schemas/shopping/types/order_line_item.json

@@ -23,18 +23,23 @@
       "type": "object",
       "required": ["total", "fulfilled"],
       "properties": {
+        "original": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Quantity from the original checkout."
+        },
         "total": {
           "type": "integer",
           "minimum": 0,
-          "description": "Current total quantity."
+          "description": "Current total active quantity. May differ from original due to post-order modifications (e.g., returns or cancellations)."
         },
         "fulfilled": {
           "type": "integer",
           "minimum": 0,
-          "description": "Quantity fulfilled (sum from fulfillment events)."
+          "description": "Quantity fulfilled so far."
         }
       },
-      "description": "Quantity tracking. Both total and fulfilled are derived from events."
+      "description": "Quantity tracking for the line item."
     },
     "totals": {
       "type": "array",
@@ -48,9 +53,10 @@
       "enum": [
         "processing",
         "partial",
-        "fulfilled"
+        "fulfilled",
+        "removed"
       ],
-      "description": "Derived status: fulfilled if quantity.fulfilled == quantity.total, partial if quantity.fulfilled > 0, otherwise processing."
+      "description": "Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing."
     },
     "parent_id": {
       "type": "string",