@wowok/agent-mcp 3.1.6 → 3.2.0

package/dist/schemas/onchain_operations.schema.json

@@ -112,7 +112,7 @@
                             "type": "string",
                             "description": "Name of the product or service to purchase"
                           },
-                          "stock": {
+                          "quantity": {
                             "anyOf": [
                               {
                                 "type": "number"
@@ -121,16 +121,17 @@
                                 "type": "string"
                               }
                             ],
-                            "description": "Quantity of the product or service to purchase"
+                            "description": "⚠️ PURCHASE QUANTITY, NOT inventory. This is the number of units you are buying; the on-chain order total = sale.price x this value. Do NOT put the product's available stock here — inventory is the separate `stock` field on the Service's sales list. To buy one unit, set quantity: 1. (Legacy callers may still send this as `stock`; it is accepted and treated identically as the purchase quantity.)"
                           },
                           "wip_hash": {
-                            "type": "string",
-                            "description": "WIP file hash of the item. EMPTY string \"\" means only verify the WIP file integrity without comparing to a specific hash (the hash within the wip file will be used). For purchases, it is STRONGLY RECOMMENDED to fill in the hash you saw when viewing the product info (from the Service sale's wip_hash field) to prevent the merchant from replacing the WIP file before your order is placed (a legitimate update operation), which would cause inconsistency between what you saw and what you received."
+                            "default": "",
+                            "description": "WIP file hash of the item. OMIT this field (or pass empty string \"\") to AUTO-FILL it from the bound Service sale's wip_hash — the on-chain quote then verifies the WIP file matches that hash (E_WIP_HASH_NOT_MATCH on mismatch), so buyers do NOT need to copy any hash value. Only pass an explicit hash when pinning a value seen earlier: that protects against a legitimate merchant WIP update between viewing the product and placing the order.",
+                            "type": "string"
                           }
                         },
                         "required": [
                           "name",
-                          "stock",
+                          "quantity",
                           "wip_hash"
                         ],
                         "additionalProperties": false
@@ -165,7 +166,7 @@
                           "properties": {
                             "coin": {
                               "type": "string",
-                              "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                              "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                             }
                           },
                           "required": [
@@ -249,7 +250,7 @@
                   "additionalProperties": false
                 },
                 "namedNewOrder": {
-                  "description": "RECOMMENDED: Set a local name for the newly created Order object. Without this, the Order is only referenceable by its on-chain address. Example: {name: 'my_order_v1'} allows subsequent operations to use 'my_order_v1' instead of the address.",
+                  "description": "RECOMMENDED: Set a local name for the newly created Order object. Without this, the Order is only referenceable by its on-chain address. Example: {name: 'my_order_v1'} allows subsequent operations to use 'my_order_v1' instead of the address. PLACEMENT: this field MUST be inside data.order_new (it is an OrderNew field) — putting namedNewOrder at the data root fails schema validation with 'Unrecognized key'. MIGRATION TIP: for batch/migration order creation, always auto-generate readable names (e.g. '<source>_<service>_<seq>' like 'upwork_svc_v1_0001') — unnamed orders (head.name = null) are only address-referenceable, which breaks downstream queries, displays and audits (E-8).",
                   "type": "object",
                   "properties": {
                     "name": {
@@ -379,7 +380,7 @@
                                 "type": "string"
                               }
                             ],
-                            "description": "Current REMAINING stock of the product or service. Each order DECREMENTS it by the ordered quantity (a buy aborts when the remaining stock is lower than the ordered quantity). Writing this field SETS the remaining stock to the given value — it is NOT added to it. To top up one product's stock without resending the whole list, there is no per-item op in this tool; re-issue sales with op:\"set\" carrying the full list and the updated stock for that product."
+                            "description": "Current REMAINING stock of the product or service. Each order DECREMENTS it by the ordered quantity (a buy aborts when the remaining stock is lower than the ordered quantity). Writing this field SETS the remaining stock to the given value — it is NOT added to it. To change one product without resending the whole list, use the per-item sales ops on onchain_operations service: stock_add / stock_reduce (deltas), price_add / price_reduce (deltas), sale_suspension (suspend/resume one product)."
                           },
                           "suspension": {
                             "type": "boolean",
@@ -450,7 +451,7 @@
                                 "type": "string"
                               }
                             ],
-                            "description": "Current REMAINING stock of the product or service. Each order DECREMENTS it by the ordered quantity (a buy aborts when the remaining stock is lower than the ordered quantity). Writing this field SETS the remaining stock to the given value — it is NOT added to it. To top up one product's stock without resending the whole list, there is no per-item op in this tool; re-issue sales with op:\"set\" carrying the full list and the updated stock for that product."
+                            "description": "Current REMAINING stock of the product or service. Each order DECREMENTS it by the ordered quantity (a buy aborts when the remaining stock is lower than the ordered quantity). Writing this field SETS the remaining stock to the given value — it is NOT added to it. To change one product without resending the whole list, use the per-item sales ops on onchain_operations service: stock_add / stock_reduce (deltas), price_add / price_reduce (deltas), sale_suspension (suspend/resume one product)."
                           },
                           "suspension": {
                             "type": "boolean",
@@ -483,7 +484,7 @@
                     "sales"
                   ],
                   "additionalProperties": false,
-                  "description": "Replaces the ENTIRE sales list: every product NOT included is REMOVED from the Service (its stock and wip binding go with it — there is no per-item update via this op). To change one product (e.g. its price or stock), resend the FULL list including all unchanged products. Removal is immediate and cannot be undone."
+                  "description": "Replaces the ENTIRE sales list: every product NOT included is REMOVED from the Service (its stock and wip binding go with it). To change ONE product, prefer the per-item ops (price_add / price_reduce / stock_add / stock_reduce / sale_suspension) over re-sending the full list; with op:set you MUST resend ALL unchanged products too. Removal is immediate and cannot be undone."
                 },
                 {
                   "type": "object",
@@ -520,6 +521,154 @@
                   ],
                   "additionalProperties": false,
                   "description": "Clear all sales products or services."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "price_add"
+                    },
+                    "sale_name": {
+                      "type": "string",
+                      "description": "Name of the product to update"
+                    },
+                    "value": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "description": "Price INCREASE delta in the Service token's smallest units (e.g. 100000000 = +0.1 WOW). Added to the current price (on-chain saturating add). NOT the new absolute price."
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "sale_name",
+                    "value"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Raise one product's price by a delta. Only the named product is touched; an unknown sale_name is silently ignored on-chain (verify with query_toolkit afterwards)."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "price_reduce"
+                    },
+                    "sale_name": {
+                      "type": "string",
+                      "description": "Name of the product to update"
+                    },
+                    "value": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "description": "Price DECREASE delta in the Service token's smallest units (e.g. 100000000 = -0.1 WOW). If the delta exceeds the current price, the price clamps to 0. NOT the new absolute price."
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "sale_name",
+                    "value"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Lower one product's price by a delta. Only the named product is touched; an unknown sale_name is silently ignored on-chain (verify with query_toolkit afterwards)."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "stock_add"
+                    },
+                    "sale_name": {
+                      "type": "string",
+                      "description": "Name of the product to update"
+                    },
+                    "value": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "description": "Stock INCREASE delta (a unit COUNT, not money), e.g. 50 = +50 units."
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "sale_name",
+                    "value"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Restock one product by a delta. Only the named product is touched; an unknown sale_name is silently ignored on-chain (verify with query_toolkit afterwards)."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "stock_reduce"
+                    },
+                    "sale_name": {
+                      "type": "string",
+                      "description": "Name of the product to update"
+                    },
+                    "value": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "string"
+                        }
+                      ],
+                      "description": "Stock DECREASE delta (a unit COUNT, not money), e.g. 10 = -10 units. If the delta exceeds current stock, the stock clamps to 0 (product becomes unsellable)."
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "sale_name",
+                    "value"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Reduce one product's stock by a delta (e.g. write-off damaged units). Only the named product is touched; an unknown sale_name is silently ignored on-chain."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "op": {
+                      "type": "string",
+                      "const": "sale_suspension"
+                    },
+                    "sale_name": {
+                      "type": "string",
+                      "description": "Name of the product to suspend or resume"
+                    },
+                    "suspension": {
+                      "type": "boolean",
+                      "description": "true = suspend the product (buy/quote abort with E_SALE_SUSPENDED); false = resume selling."
+                    }
+                  },
+                  "required": [
+                    "op",
+                    "sale_name",
+                    "suspension"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Suspend or resume ONE product without removing it (keeps price/stock/WIP binding). The Amazon-style 'out of stock / listing inactive' state. Only the named product is touched; an unknown sale_name is silently ignored on-chain (verify with query_toolkit afterwards)."
                 }
               ]
             },
@@ -969,7 +1118,7 @@
                                       "type": "string"
                                     }
                                   ],
-                                  "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate': basis-points rate, 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
+                                  "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
                                 },
                                 "mode": {
                                   "anyOf": [
@@ -978,12 +1127,13 @@
                                       "enum": [
                                         "Amount",
                                         "Rate",
-                                        "Surplus"
+                                        "Surplus",
+                                        "RateGross"
                                       ]
                                     },
                                     {}
                                   ],
-                                  "description": "Allocation mode — determines how the `sharing` field is interpreted. Three modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set). Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate items (proportional to balance-fix) → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits (requires sum == 10000 unless Surplus present). Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2)."
+                                  "description": "Allocation mode — determines how the `sharing` field is interpreted. Four modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross', recommended) or number (0/1/2/3)."
                                 }
                               },
                               "required": [
@@ -992,12 +1142,12 @@
                                 "mode"
                               ],
                               "additionalProperties": false,
-                              "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last."
+                              "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate/RateGross items second, Surplus last."
                             },
-                            "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
+                            "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate/RateGross + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix; RateGross proportional to the full pool) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; NET Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); RateGross sum must <= 10000 (never mixed with NET Rate while a fixed total is present); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
                           },
                           "fix": {
-                            "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation.",
+                            "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for NET Rate allocation (RateGross ignores fix and uses the full pool/`max`).",
                             "anyOf": [
                               {
                                 "type": "number"
@@ -1008,7 +1158,7 @@
                             ]
                           },
                           "max": {
-                            "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: total_rates = max - fix (instead of balance - fix)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
+                            "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: NET Rate total_rates = max - fix; RateGross total_rates = max (fix NOT subtracted)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
                             "anyOf": [
                               {
                                 "anyOf": [
@@ -1032,7 +1182,7 @@
                           "sharing"
                         ],
                         "additionalProperties": false,
-                        "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus."
+                        "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/RateGross/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate/RateGross → Surplus."
                       },
                       "description": "Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."
                     }
@@ -1043,7 +1193,7 @@
                     "allocators"
                   ],
                   "additionalProperties": false,
-                  "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus)."
+                  "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate/RateGross → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's NET Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus); RateGross-mode sharing[] must sum to <= 10000."
                 },
                 {
                   "type": "null"
@@ -1091,7 +1241,7 @@
                   "properties": {
                     "coin": {
                       "type": "string",
-                      "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                      "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                     }
                   },
                   "required": [
@@ -1422,7 +1572,7 @@
               "type": "boolean"
             },
             "publish": {
-              "description": "Whether to publish the Service. After publishing, customers can place orders. VERIFIED against Move source + SDK (4-level immutability matrix):\n  L1 — PERMANENTLY LOCKED after publish (assert!(!bPublished), no pause+lock exception):\n    • machine          (workflow template)\n    • order_allocators (fund distribution rules)\n  L2 — TIME-LOCKED after publish (unpublished-state check — requires pause + setting_lock_duration elapsed):\n    • arbitrations remove/clear (dispute resolution objects)\n    • rewards remove/clear       (reward objects)\n    • compensation_fund_withdraw (withdraw ALL funds)\n  L3 — REMAIN MUTABLE after publish (no SDK check, no Move check):\n    • arbitrations add, rewards add (no assert — can add after publish)\n    • buy_guard, sales, discount, description, location, pause, repositories,\n    • compensation_fund_add, setting_lock_duration_add, customer_required, um (Contact)\nThese 2 L1-LOCKED fields (machine/order_allocators) MUST be set BEFORE publish=true.\narbitrations/rewards can be ADDED after publish but remove/clear requires pause+lock.\n\n⚠️ COMPENSATION_FUND + ARBITRATION LINKAGE:\n  At publish time, if compensation_fund > 0, Arbitration MUST be bound:\n    if (balance::value(&self.compensation_fund) > 0) {\n        assert!(arbitration_count > 0, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND);\n    }\n  The MCP handler enforces this as a HARD PRE-CHECK: if publish=true AND compensation_fund_add   is set in the same call AND arbitrations is empty, the call is REJECTED before submission.   If compensation_fund was deposited in a prior call, a SOFT WARNING is issued.\n\nSCHEMA-03 / P0-01 fix — DEPLOYMENT WORKFLOW (two-phase, avoids circular dependency):\n  Phase 1 — CREATE (no publish): object={name:'my-service', type_parameter, permission} + machine + order_allocators + arbitrations.\n    NOTE: buy_guard can use a LocalMark NAME (not address) to break the Guard→Service circular dependency.\n    The name is resolved to an address at transaction build time.\n  Phase 2 — PUBLISH: object='my-service' (string ref) + publish=true.\n    All L1-LOCKED fields must be set in Phase 1; Phase 2 only flips the publish flag.\n  Post-publish updates: buy_guard, sales, description, repositories (add), rewards (add), arbitrations (add), etc.",
+              "description": "Whether to publish the Service. After publishing, customers can place orders. ⚠️ PRE-PUBLISH EVALUATION (mandatory, stop-node fund-exit coverage): service.allocators MUST cover EVERY stop node of the bound Machine — every node where an order can rest (terminal nodes AND waiting states: review windows, handovers, open disputes) needs BOTH a withdrawal (release) AND a refund allocation rule, and each mapping guard must be satisfiable in BOTH directions. An uncovered stop node strands escrowed funds permanently (order_allocators is L1-immutable). Review-gated release is a TIME VARIANT inside ONE exit guard ('reviewed OR unreviewed after T'), never parallel outgoing edges (race deadlock). See pattern.fund_flow_stop_node_coverage + rules R-M5-03 / R-M5-09. VERIFIED against Move source + SDK (4-level immutability matrix):\n  L1 — PERMANENTLY LOCKED after publish (assert!(!bPublished), no pause+lock exception):\n    • machine          (workflow template)\n    • order_allocators (fund distribution rules)\n  L2 — TIME-LOCKED after publish (unpublished-state check — requires pause + setting_lock_duration elapsed):\n    • arbitrations remove/clear (dispute resolution objects)\n    • rewards remove/clear       (reward objects)\n    • compensation_fund_withdraw (withdraw ALL funds)\n  L3 — REMAIN MUTABLE after publish (no SDK check, no Move check):\n    • arbitrations add, rewards add (no assert — can add after publish)\n    • buy_guard, sales, discount, description, location, pause, repositories,\n    • compensation_fund_add, setting_lock_duration_add, customer_required, um (Contact)\nThese 2 L1-LOCKED fields (machine/order_allocators) MUST be set BEFORE publish=true.\narbitrations/rewards can be ADDED after publish but remove/clear requires pause+lock.\n\n⚠️ COMPENSATION_FUND + ARBITRATION LINKAGE:\n  At publish time, if compensation_fund > 0, Arbitration MUST be bound:\n    if (balance::value(&self.compensation_fund) > 0) {\n        assert!(arbitration_count > 0, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND);\n    }\n  The MCP handler enforces this as a HARD PRE-CHECK: if publish=true AND compensation_fund_add   is set in the same call AND arbitrations is empty, the call is REJECTED before submission.   If compensation_fund was deposited in a prior call, a SOFT WARNING is issued.\n\nSCHEMA-03 / P0-01 fix — DEPLOYMENT WORKFLOW (two-phase, avoids circular dependency):\n  Phase 1 — CREATE (no publish): object={name:'my-service', type_parameter, permission} + machine + order_allocators + arbitrations.\n    NOTE: buy_guard can use a LocalMark NAME (not address) to break the Guard→Service circular dependency.\n    The name is resolved to an address at transaction build time.\n  Phase 2 — PUBLISH: object='my-service' (string ref) + publish=true.\n    All L1-LOCKED fields must be set in Phase 1; Phase 2 only flips the publish flag.\n  Post-publish updates: buy_guard, sales, description, repositories (add), rewards (add), arbitrations (add), etc.",
               "type": "boolean"
             }
           },
@@ -2415,6 +2565,17 @@
                                 "type": "string",
                                 "description": "Node name. ⚠️ T1 LOSSY POINT (B-1): do NOT name a node 'refund'/'refunded'/'deposit_refunded'/'deposit_deducted'/'disputed'/'cancelled' to model fund return or dispute — funds MUST move through the Allocation waterfall (order_allocators), NOT through Machine terminal nodes (R-M1-11). A node named 'refund' is a semantic lie: reaching it does not move funds by itself. Model refund as a refund-to-Order Allocator slot (a { Signer } or Order-owner recipient), and model dispute as the bound Arbitration, not a Machine node."
                               },
+                              "role": {
+                                "description": "OPTIONAL business role tag for display layers and template reuse (E-9). SESSION METADATA ONLY — the on-chain node struct carries name+pairs, so this is NOT stored on-chain; the MCP echoes it back as a NODE ROLES constraint warning and seed templates annotate it. Semantics: draft = pre-start cancellable, active = work in progress, delivered = work submitted awaiting acceptance, final = settlement endpoint (advancing here should trigger the Allocation fund release), cancelled = refund endpoint (advancing here should trigger the refund Allocator).",
+                                "type": "string",
+                                "enum": [
+                                  "draft",
+                                  "active",
+                                  "delivered",
+                                  "final",
+                                  "cancelled"
+                                ]
+                              },
                               "pairs": {
                                 "type": "array",
                                 "items": {
@@ -2446,7 +2607,7 @@
                                             "description": "Forward name"
                                           },
                                           "namedOperator": {
-                                            "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                            "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                             "anyOf": [
                                               {
                                                 "type": "string"
@@ -2591,6 +2752,17 @@
                                 "type": "string",
                                 "description": "Node name. ⚠️ T1 LOSSY POINT (B-1): do NOT name a node 'refund'/'refunded'/'deposit_refunded'/'deposit_deducted'/'disputed'/'cancelled' to model fund return or dispute — funds MUST move through the Allocation waterfall (order_allocators), NOT through Machine terminal nodes (R-M1-11). A node named 'refund' is a semantic lie: reaching it does not move funds by itself. Model refund as a refund-to-Order Allocator slot (a { Signer } or Order-owner recipient), and model dispute as the bound Arbitration, not a Machine node."
                               },
+                              "role": {
+                                "description": "OPTIONAL business role tag for display layers and template reuse (E-9). SESSION METADATA ONLY — the on-chain node struct carries name+pairs, so this is NOT stored on-chain; the MCP echoes it back as a NODE ROLES constraint warning and seed templates annotate it. Semantics: draft = pre-start cancellable, active = work in progress, delivered = work submitted awaiting acceptance, final = settlement endpoint (advancing here should trigger the Allocation fund release), cancelled = refund endpoint (advancing here should trigger the refund Allocator).",
+                                "type": "string",
+                                "enum": [
+                                  "draft",
+                                  "active",
+                                  "delivered",
+                                  "final",
+                                  "cancelled"
+                                ]
+                              },
                               "pairs": {
                                 "type": "array",
                                 "items": {
@@ -2622,7 +2794,7 @@
                                             "description": "Forward name"
                                           },
                                           "namedOperator": {
-                                            "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                            "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                             "anyOf": [
                                               {
                                                 "type": "string"
@@ -2905,7 +3077,7 @@
                                       "description": "Forward name"
                                     },
                                     "namedOperator": {
-                                      "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                      "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                       "anyOf": [
                                         {
                                           "type": "string"
@@ -3084,7 +3256,7 @@
                   "properties": {
                     "json_or_markdown_file": {
                       "type": "string",
-                      "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing workflow states and transitions:\n- name: Node identifier\n- pairs: Array of {prior_node, forwards, threshold} defining connections\n- forwards: Operations available from this node\n- threshold: Required weight to advance\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
+                      "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing workflow states and transitions:\n- name: Node identifier\n- role: (optional) business role tag for display layers — one of draft/active/delivered/final/cancelled. SESSION METADATA ONLY (not stored on-chain; echoed back as a NODE ROLES warning)\n- pairs: Array of {prior_node, forwards, threshold} defining connections\n- forwards: Operations available from this node\n- threshold: Required weight to advance\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
                     }
                   },
                   "required": [
@@ -3099,7 +3271,7 @@
               "type": "boolean"
             },
             "publish": {
-              "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable.",
+              "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable. ⚠️ Before publishing, enumerate the graph STOP NODES (nodes with no outgoing Pair) plus every waiting state (review window, handover, open dispute) and verify each has a defined fund exit in the Service order_allocators — withdrawal (release) AND refund. Machine + Allocator are immutable after publish (IMMUT-001); an uncovered stop node strands funds permanently (rule R-M5-03, checklist pattern.fund_flow_stop_node_coverage).",
               "type": "boolean"
             },
             "owner_receive": {
@@ -6520,7 +6692,7 @@
                       "properties": {
                         "coin": {
                           "type": "string",
-                          "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                          "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                         }
                       },
                       "required": [
@@ -6574,7 +6746,7 @@
               "type": "string"
             },
             "fee": {
-              "description": "Arbitration fee.",
+              "description": "Arbitration filing fee. FORMAT: a direct amount value — NOT wrapped in {balance: ...} (that CoinParam shape is only for dispute.fee, which pays a coin object). Accepted: smallest-unit number or string (e.g. 50000000 = 0.05 WOW at 9 decimals), or display format with the token symbol (e.g. \"0.05WOW\") — the Fund Processing Layer converts it using the Arbitration object's own token decimals. Default 0 on creation: disputes are then free (the filer's coin is fully refunded on filing) and the arbitrator earns no per-case fee.",
               "anyOf": [
                 {
                   "type": "number"
@@ -6594,7 +6766,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "voting_deadline": {
                   "default": 0,
@@ -6623,7 +6795,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "voting_deadline": {
                   "anyOf": [
@@ -6649,7 +6821,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "votes": {
                   "type": "array",
@@ -6661,7 +6833,7 @@
                   "description": "Proposition INDICES (0-based, u8) the voter agrees with — e.g. [0] votes for the first proposition. Re-voting REPLACES the voter's previous vote (old weight removed, new applied). Out-of-range index aborts with E_PROPOSITION_NOT_FOUND."
                 },
                 "voting_guard": {
-                  "description": "Optional Voting Guard for weighted voting. THREE PATHS are supported by the SDK and Move contract: (1) voting_guard PROVIDED → Guard-weighted vote (Guard verifies voter + determines vote weight via VoteWeight config); (2) voting_guard OMITTED but other guards trigger passport creation (e.g. env.permission_guard or usage_guard) → permission-only vote via passport; (3) voting_guard OMITTED and no passport context → vote (plain permission-only vote, no Guard). The Guard (when provided) must be in the Arbitration's voting_guard list.",
+                  "description": "Voting Guard for WEIGHTED voting. DECISION RULE (contract-enforced):\n(A) Arbitration HAS a non-empty voting_guard list → plain vote is REJECTED on-chain with E_VOTING_GUARD_USED (abort 2). You MUST provide this field set to ONE guard from the Arbitration's voting_guard list, and fill its submission: when the guard's vote_weight is {GuardIdentifier: pos}, the number you submit at that table position IS the vote weight; when it is {FixedValue: v}, no submission is needed (weight is fixed). The SDK then routes the call through the Guard-weighted vote path via a Passport. Omitting this field on such an Arbitration now fails fast pre-call with the list of valid guards.\n(B) Arbitration has NO voting_guard → omit this field; the SDK uses plain vote (weight 1, permission-gated), or the passport-gated vote path when other guards require it.\nBOTH (B) paths still assert ARBITRATION_VOTE=358 on-chain (the SDK now pre-checks 358 and fails fast with 'Missing permissions 358'). An empty voting_guard means EQUAL WEIGHT (1 person 1 vote), NOT permissionless — there is no permission-free vote entry. For genuinely open voting, configure a public voting_guard (op=\"set\") and vote via path (A): the weighted passport path authorizes by the guard and does NOT require 358.\nThe Guard (when provided) MUST be in the Arbitration's voting_guard list — an unlisted guard aborts with E_VOTING_GUARD_NOT_FOUND.",
                   "type": "string"
                 }
               },
@@ -6677,7 +6849,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "feedback": {
                   "type": "string",
@@ -6696,7 +6868,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "feedback": {
                   "type": "string",
@@ -6721,7 +6893,7 @@
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 },
                 "feedback": {
                   "type": "string",
@@ -6735,12 +6907,12 @@
               "additionalProperties": false
             },
             "arb_withdraw": {
-              "description": "Withdraw arbitration fees from the Arb object (arbitrator). Immediately from state 5 (Finished); from state 3 only after 30 days from the ruling time (no objection filed — silence = acceptance); rejected in states 0/1/2. State 4 (Objectionable) can NEVER withdraw (protocol 141): a contested case keeps its fee escrowed until the customer closes the objection cycle — reset → order.arb_confirm → new ruling → unchallenged (or accepted via finish).",
+              "description": "Withdraw arbitration fees from the Arb object (arbitrator). Immediately from state 5 (Finished); from state 3 only after 30 days from the ruling time (no objection filed — silence = acceptance); rejected in states 0/1/2. State 4 (Objectionable) can NEVER withdraw (protocol 141): a contested case keeps its fee escrowed until the customer closes the objection cycle — reset → order.arb_confirm → new ruling → unchallenged (or accepted via finish). ⚠️ TWO-STAGE FEE CASH-OUT (verified on testnet): this call does NOT pay the arbitrator's wallet — it moves the case fee into the Arbitration (Registration) object's own balance pool. To actually receive the money: fees_transfer (to a treasury or allocation) → treasury receive: \"recently\" (permission 253) → treasury withdraw → recipient payment receive. A successful arb_withdraw with no wallet balance change is EXPECTED, not a failure.",
               "type": "object",
               "properties": {
                 "arb": {
                   "type": "string",
-                  "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                  "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
                 }
               },
               "required": [
@@ -6791,7 +6963,7 @@
                   "type": "integer",
                   "minimum": 0,
                   "maximum": 9007199254740991,
-                  "description": "Payment index."
+                  "description": "0-based index of the fee payment inside the Arb case's fees table (query the Arb case with onchain_operations type 'q' / onchain_table_data to list its fees and their indices). REQUIRED — without it the transfer cannot name which fee record to move."
                 },
                 "newPayment": {
                   "description": "Name for the newly created payment object.",
@@ -7085,7 +7257,7 @@
             "object"
           ],
           "additionalProperties": false,
-          "description": "On-chain Arbitration operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create an Arbitration. NOTE:'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. ⚠️ PERMISSION RULE (contract-enforced): the Arbitration's permission MUST be DIFFERENT from the permission of any Service it will be bound to — binding an Arbitration that SHARES the Service's Permission aborts with E_ARBITRATION_PERMISSION_CONFLICT (error 33). Always create a DEDICATED Permission object for each Arbitration. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation."
+          "description": "On-chain Arbitration operations. TWO OBJECT KINDS — do not confuse them (§5.9): the ROOT 'object' field is the Arbitration (arbitrator REGISTRATION) object; the Arb (single CASE) created by 'dispute' is addressed via each case operation's 'arb' field. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create an Arbitration. NOTE:'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. ⚠️ PERMISSION RULE (contract-enforced): the Arbitration's permission MUST be DIFFERENT from the permission of any Service it will be bound to — binding an Arbitration that SHARES the Service's Permission aborts with E_ARBITRATION_PERMISSION_CONFLICT (error 33). Always create a DEDICATED Permission object for each Arbitration. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation."
         },
         "env": {
           "type": "object",
@@ -8885,7 +9057,7 @@
                       "properties": {
                         "coin": {
                           "type": "string",
-                          "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                          "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                         }
                       },
                       "required": [
@@ -10308,7 +10480,7 @@
                   "properties": {
                     "coin": {
                       "type": "string",
-                      "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                      "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                     }
                   },
                   "required": [
@@ -11476,7 +11648,7 @@
                                       "type": "string"
                                     }
                                   ],
-                                  "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate': basis-points rate, 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
+                                  "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
                                 },
                                 "mode": {
                                   "anyOf": [
@@ -11485,12 +11657,13 @@
                                       "enum": [
                                         "Amount",
                                         "Rate",
-                                        "Surplus"
+                                        "Surplus",
+                                        "RateGross"
                                       ]
                                     },
                                     {}
                                   ],
-                                  "description": "Allocation mode — determines how the `sharing` field is interpreted. Three modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set). Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate items (proportional to balance-fix) → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits (requires sum == 10000 unless Surplus present). Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2)."
+                                  "description": "Allocation mode — determines how the `sharing` field is interpreted. Four modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross', recommended) or number (0/1/2/3)."
                                 }
                               },
                               "required": [
@@ -11499,12 +11672,12 @@
                                 "mode"
                               ],
                               "additionalProperties": false,
-                              "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last."
+                              "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate/RateGross items second, Surplus last."
                             },
-                            "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
+                            "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate/RateGross + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix; RateGross proportional to the full pool) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; NET Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); RateGross sum must <= 10000 (never mixed with NET Rate while a fixed total is present); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
                           },
                           "fix": {
-                            "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation.",
+                            "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for NET Rate allocation (RateGross ignores fix and uses the full pool/`max`).",
                             "anyOf": [
                               {
                                 "type": "number"
@@ -11515,7 +11688,7 @@
                             ]
                           },
                           "max": {
-                            "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: total_rates = max - fix (instead of balance - fix)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
+                            "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: NET Rate total_rates = max - fix; RateGross total_rates = max (fix NOT subtracted)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
                             "anyOf": [
                               {
                                 "anyOf": [
@@ -11539,7 +11712,7 @@
                           "sharing"
                         ],
                         "additionalProperties": false,
-                        "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus."
+                        "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/RateGross/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate/RateGross → Surplus."
                       },
                       "description": "Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."
                     }
@@ -11550,7 +11723,7 @@
                     "allocators"
                   ],
                   "additionalProperties": false,
-                  "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus)."
+                  "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate/RateGross → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's NET Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus); RateGross-mode sharing[] must sum to <= 10000."
                 },
                 "coin": {
                   "anyOf": [
@@ -11580,7 +11753,7 @@
                       "properties": {
                         "coin": {
                           "type": "string",
-                          "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                          "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                         }
                       },
                       "required": [
@@ -17868,7 +18041,7 @@
                             "properties": {
                               "coin": {
                                 "type": "string",
-                                "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                                "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                               }
                             },
                             "required": [
@@ -17967,7 +18140,7 @@
                 "receive"
               ],
               "additionalProperties": false,
-              "description": "Receive mode: unwrap a CoinWrapper to the caller's wallet. Use after Allocation's alloc_by_guard creates a Payment with your address as a revenue recipient. The CoinWrapper holds your share — call this to convert it to actual coins in your wallet. Provide 'object' to unwrap a specific CoinWrapper, or OMIT it to auto-unwrap every CoinWrapper owned by the caller."
+              "description": "Receive mode: unwrap a CoinWrapper to the caller's wallet. Use after Allocation's alloc_by_guard creates a Payment with your address as a revenue recipient. The CoinWrapper holds your share — call this to convert it to actual coins in your wallet. Provide 'object' to unwrap a specific CoinWrapper, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. AUTO-CLAIM: when the allocation SIGNER and the recipient are the SAME account, the share is credited directly during settlement and NO CoinWrapper is created — a 'no CoinWrapper found' result in that case means the funds already arrived (verify via account_balance), it is NOT a failure."
             }
           ],
           "description": "On-chain Payment operations. TWO modes:\n(1) CREATE: Set 'object' with {name, type_parameter, ...}, 'revenue', and 'info' to create a new Payment.\n(2) RECEIVE: Set {receive: true} to unwrap CoinWrappers to your wallet. Provide 'object' (<coinwrapper_id_or_name>) to unwrap a specific one, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. type_parameter optional — auto-derived from the CoinWrapper's type."
@@ -19232,7 +19405,7 @@
               "additionalProperties": false
             },
             "required_info": {
-              "description": "Contact object ID (recipient) or WTS Proof object (delivery proof) that information has been delivered via Wowok Messenger.",
+              "description": "Credential recorded on the order: the merchant's IM user address resolved from the Service's Contact (zero cost) or a WTS Proof object id (on-chain delivery proof embedding that IM address and timestamp; costs gas). The information itself is delivered via Wowok Messenger.",
               "anyOf": [
                 {
                   "type": "string",