@wowok/agent-mcp 3.1.6 → 3.2.0

package/dist/schemas/onchain_operations_service.schema.json

@@ -110,7 +110,7 @@
                         "type": "string",
                         "description": "Name of the product or service to purchase"
                       },
-                      "stock": {
+                      "quantity": {
                         "anyOf": [
                           {
                             "type": "number"
@@ -119,16 +119,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
@@ -163,7 +164,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": [
@@ -247,7 +248,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": {
@@ -377,7 +378,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",
@@ -448,7 +449,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",
@@ -481,7 +482,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",
@@ -518,6 +519,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)."
             }
           ]
         },
@@ -967,7 +1116,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": [
@@ -976,12 +1125,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": [
@@ -990,12 +1140,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"
@@ -1006,7 +1156,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": [
@@ -1030,7 +1180,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)."
                 }
@@ -1041,7 +1191,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"
@@ -1089,7 +1239,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": [
@@ -1420,7 +1570,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"
         }
       },

package/dist/schemas/onchain_operations_treasury.schema.json

@@ -213,7 +213,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": [

package/dist/schemas/onchain_table_data.output.json

@@ -2904,7 +2904,7 @@
                         "type": "null"
                       }
                     ],
-                    "description": "Buyer-submitted Contact object or WTS proof id (order.required_info); null when not submitted"
+                    "description": "Buyer-recorded credential (order.required_info): the merchant's IM user address resolved from the Service's Contact (zero cost) or an on-chain WTS Proof object id (embeds the IM address + last-message timestamp); null when not submitted"
                   },
                   "progress_next": {
                     "anyOf": [
@@ -7600,7 +7600,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"
@@ -9062,6 +9062,59 @@
           "additionalProperties": false,
           "description": "ONE-CALL full business-intelligence context of an on-chain Service (K3 22 / Business Service tab): base data + machine workflow graph + buy_guard/permission/allocator guards + related objects + supply chain + deterministic BusinessReport + recent orders. Every section degrades gracefully — failures are reported in `data_gaps`. Read-only."
         },
+        {
+          "type": "object",
+          "properties": {
+            "query_type": {
+              "type": "string",
+              "const": "service_quote"
+            },
+            "service_address": {
+              "type": "string",
+              "description": "On-chain Service object address (or LocalMark name). Required when query_type='service_quote'."
+            },
+            "items": {
+              "description": "Basket to quote. Omit to quote EVERY sale with quantity 1 (the floor basket — order quantity is chosen at buy time, so per-unit prices are the authoritative input).",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Sale name exactly as configured on the Service."
+                  },
+                  "quantity": {
+                    "default": 1,
+                    "description": "Units of this item in the basket (default 1).",
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 10000
+                  }
+                },
+                "required": [
+                  "name",
+                  "quantity"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "context_network": {
+              "type": "string",
+              "enum": [
+                "testnet",
+                "mainnet",
+                "localnet"
+              ],
+              "description": "Network for the query — equivalent to the `network` parameter (prefer `network`). Defaults to the user's CURRENT network (client UI selection / authority config) when omitted. 'localnet' is for internal test use against a local fullnode."
+            }
+          },
+          "required": [
+            "query_type",
+            "service_address"
+          ],
+          "additionalProperties": false,
+          "description": "READ-ONLY pre-purchase quote of a Service (finding 3.6 — order_new total_pay pre-check): per-item unit price × quantity, the basket total that order_new.buy.total_pay.balance must exactly equal (the on-chain buy aborts on any drift), and the order_allocators fee-split preview (sharing rows of the FIRST allocator — the normal payout path; guards select per-case allocators such as refund/damage, so the live split depends on which guard passes). Mirrors the on-chain price×quantity semantics WITHOUT calling quote on-chain and NEVER submits a transaction. Amounts are payment-token smallest units plus a human display when the token precision resolves."
+        },
         {
           "type": "object",
           "properties": {
@@ -10643,7 +10696,7 @@
                     "description": "Business meaning of advancing to this node. Example: 'Guide starts the day service'"
                   },
                   "gains": {
-                    "description": "Gains for the caller if this option is chosen (K3 Game G1 gain separation). Example: ['Settlement triggered — funds released to provider']",
+                    "description": "Gains for the caller if this option is chosen (K3 Game G1 gain separation). Example: ['Settlement unlocked — funds releasable to provider via an explicit allocation step']",
                     "type": "array",
                     "items": {
                       "type": "string"
@@ -10890,7 +10943,7 @@
                         "description": "Business meaning of advancing to this node. Example: 'Guide starts the day service'"
                       },
                       "gains": {
-                        "description": "Gains for the caller if this option is chosen (K3 Game G1 gain separation). Example: ['Settlement triggered — funds released to provider']",
+                        "description": "Gains for the caller if this option is chosen (K3 Game G1 gain separation). Example: ['Settlement unlocked — funds releasable to provider via an explicit allocation step']",
                         "type": "array",
                         "items": {
                           "type": "string"

package/dist/schemas/persona_operation.output.json

@@ -44,14 +44,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "layer": {
@@ -3083,14 +3076,7 @@
                 "type": "array",
                 "items": {
                   "type": "string",
-                  "enum": [
-                    "freelance",
-                    "rental",
-                    "education",
-                    "travel",
-                    "subscription",
-                    "retail"
-                  ]
+                  "pattern": "^[a-z][a-z0-9_]*$"
                 }
               },
               "long_term": {
@@ -8809,14 +8795,7 @@
                 "type": "array",
                 "items": {
                   "type": "string",
-                  "enum": [
-                    "freelance",
-                    "rental",
-                    "education",
-                    "travel",
-                    "subscription",
-                    "retail"
-                  ]
+                  "pattern": "^[a-z][a-z0-9_]*$"
                 }
               },
               "long_term": {
@@ -14548,14 +14527,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "long_term": {
@@ -20276,14 +20248,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "preferences": {
@@ -20386,14 +20351,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "long_term": {
@@ -26106,14 +26064,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "layer": {
@@ -29058,14 +29009,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "long_term": {
@@ -37611,14 +37555,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "layer": {
@@ -40542,14 +40479,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "long_term": {
@@ -46262,14 +46192,7 @@
               "type": "array",
               "items": {
                 "type": "string",
-                "enum": [
-                  "freelance",
-                  "rental",
-                  "education",
-                  "travel",
-                  "subscription",
-                  "retail"
-                ]
+                "pattern": "^[a-z][a-z0-9_]*$"
               }
             },
             "layer": {