@wowok/agent-mcp 3.4.0 → 3.4.2

package/dist/schemas/onchain_operations_service.schema.json

@@ -107,8 +107,19 @@
                     "type": "object",
                     "properties": {
                       "name": {
+                        "description": "Name of the product or service to purchase. Must match a listed sale name EXACTLY (the buy path resolves each item by exact name match) and MUST be ≤ 64 bytes (UTF-8): the on-chain buy path caps buyer-sent item names at 64 bytes even though the merchant side lists names up to 256 bytes — a longer name aborts E_NAME_LENGTH_EXCEEDED (abort 1) before anything else runs (F-RQ-01). When the exact name is impractical (long/CJK names that risk transport corruption), OMIT it and use sale_id or sale_name instead — the handler resolves the reference against the Service's LIVE sales list and fills this name for you (CHAN-P1-16).",
+                        "type": "string"
+                      },
+                      "sale_id": {
+                        "description": "CHAN-P1-16: buy by the SKU's 0-based INDEX in the Service's live sales list (the order the service_quote / query lists them). The handler resolves the index to the live sale (name + price), rewrites item.name on your behalf, and echoes `sale_index + sale_name + price` in the response — the exact name never crosses the wire. Out-of-range index → refused with the full live index table (index + name + price) so one retry lands. Consumed by the MCP gate, never reaches the chain.",
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      "sale_name": {
+                        "description": "CHAN-P1-16: buy by SKU NAME matched against the Service's LIVE sales list (exact match first; whitespace/case-tolerant, then containment when the name was corrupted in transport). Exactly one live match → the handler fills item.name and echoes `sale_index + sale_name + price`; several candidates → refused with every candidate's index; none → refused with the full live index table. Consumed by the MCP gate, never reaches the chain.",
                         "type": "string",
-                        "description": "Name of the product or service to purchase"
+                        "minLength": 1
                       },
                       "quantity": {
                         "anyOf": [
@@ -123,12 +134,11 @@
                       },
                       "wip_hash": {
                         "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.",
+                        "description": "WIP pin hash. HARD RULE (h1z9 card 13 #17, unified doctrine): when the product's wip_hash is NON-EMPTY, the buyer MUST pass this exact value — NEVER \"\". The chain quote aborts (E_WIP_HASH_NOT_MATCH) when the pin mismatches, which is the delivery-integrity guarantee. To skip copying the hash, set derive_wip_from_listing:true on the order_new object instead (explicit opt-in; the response then warns 'wip_pin: auto-filled — no WYSIWYG guarantee'). 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",
                       "quantity",
                       "wip_hash"
                     ],
@@ -186,6 +196,10 @@
                 "payment_index": {
                   "description": "Payment index",
                   "type": "number"
+                },
+                "derive_wip_from_listing": {
+                  "description": "EXPLICIT OPT-IN to wip-hash auto-fill (h1z9 card 13 #17: the ONLY sanctioned auto-fill path). true = for every item whose wip_hash is empty, the CURRENT listing hash is injected at order time and the response warns 'wip_pin: auto-filled — no WYSIWYG guarantee': the merchant may rebind the .wip file later, and an injected hash follows the listing while an explicitly passed hash stays pinned. Absent/false = the hard rule applies: pass each product's wip_hash EXACTLY (NEVER \"\" when the product has a pin) or the order is refused before send. This flag is consumed by the MCP gate and never reaches the chain.",
+                  "type": "boolean"
                 }
               },
               "required": [
@@ -195,38 +209,46 @@
             },
             "agents": {
               "description": "Order agents. Agents can operate the order, such as canceling the order, modifying the order status, etc.; but cannot receive the funds received by the order.",
-              "type": "object",
-              "properties": {
-                "entities": {
-                  "minItems": 1,
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name_or_address": {
-                        "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)."
-                      },
-                      "local_mark_first": {
-                        "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                        "type": "boolean"
+              "anyOf": [
+                {
+                  "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "entities": {
+                      "minItems": 1,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "name_or_address": {
+                            "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)."
+                          },
+                          "local_mark_first": {
+                            "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                            "type": "boolean"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                       }
                     },
-                    "additionalProperties": false,
-                    "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
-                  }
-                },
-                "check_all_founded": {
-                  "default": true,
-                  "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
-                  "type": "boolean"
+                    "check_all_founded": {
+                      "default": true,
+                      "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "entities",
+                    "check_all_founded"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Used to batch find account or object IDs by name"
                 }
-              },
-              "required": [
-                "entities",
-                "check_all_founded"
-              ],
-              "additionalProperties": false
+              ]
             },
             "order_required_info": {
               "description": "Contact object ID or WTS Proof object, RECORDED on the Order as evidence that the order holder delivered the private information the Service declares in customer_required (e.g. phone/email/shipping_address). ACCEPTED FORMS (upwc-cat-261017 T10 live probe): an on-chain object ADDRESS (0x…), a REGISTERED mark name, or the Contact/Proof object itself — a bare account name is NOT an object reference and fails with 'not found'; RECORD-ONLY, NOT ENFORCED: nothing on-chain reads this field — the purchase entry never requires it, and an order supplying none of the declared fields is still created. FLOW: the order holder sends the information to the Service's Contact (um) via end-to-end encrypted Messenger, then passes the Contact object ID or the generated WTS Proof here. To ENFORCE delivery on-chain, mount the pattern.required_info_evidence_gate Guard on the forward that hands over goods or funds, asserting order.required_info is some (presence-only — the recorded address value is never a guard condition; accepting the delivered information is the merchant's confirming forward). ATTESTATION-ONLY: the recorded value is self-attested, has no on-chain readback, and MUST NOT be used as a gate condition. PER-ORDER BINDING: when the listing genuinely promises a per-order credential, use the dedicated controlled bind operation (order_required_info_bind) with a Proof whose about is THIS order and whose creator is the order holder — the chain verifies both at write time and rejects a mismatch without writing anything. The reuse model (one Contact Proof across orders) stays the default for this plain record field; pick per listing promise, not per habit. BOUNDARY: that binding proves the credential AUTHOR only, never its content or any rating — do not mirror it onto review/reward claims; public reviews are Repository rows whose values are enforced guard-side via data-value probes, not through Proof objects.",
@@ -234,18 +256,26 @@
             },
             "transfer": {
               "description": "Set the new owner of the order. Requires order owner permission to set.",
-              "type": "object",
-              "properties": {
-                "name_or_address": {
-                  "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)."
+              "anyOf": [
+                {
+                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                 },
-                "local_mark_first": {
-                  "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                  "type": "boolean"
+                {
+                  "type": "object",
+                  "properties": {
+                    "name_or_address": {
+                      "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)."
+                    },
+                    "local_mark_first": {
+                      "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                 }
-              },
-              "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. 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 'my_shop_svc_v1_0001') — unnamed orders (head.name = null) are only address-referenceable, which breaks downstream queries, displays and audits (E-8).",
@@ -356,7 +386,7 @@
                     "properties": {
                       "name": {
                         "type": "string",
-                        "description": "Name of the product or service for sale"
+                        "description": "Name of the product or service for sale. ⚠️ 64-BYTE BUY LIMIT (F-RQ-01): the chain lists this name up to 256 bytes but validates the BUYER-SENT item name at only 64 bytes at buy time. A name of 65–256 bytes lists fine yet makes the SKU PERMANENTLY unbuyable — every order aborts E_NAME_LENGTH_EXCEEDED (abort 1). Keep SKU names ≤ 64 bytes (UTF-8); renaming cannot fix a dead SKU (the buy path matches items by EXACT name — a new name is a NEW SKU). service_quote.buyable reports this per item."
                       },
                       "price": {
                         "anyOf": [
@@ -389,8 +419,9 @@
                         "description": "WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. ⚠️ NETWORK DEPLOYMENT REQUIRED: the URL is stored ON-CHAIN and every customer fetches it when placing an order. A local file path (C:\\..., /path/file.wip), a localhost/loopback URL or a LAN private-IP URL is unreachable by customers on other machines — it passes the merchant-side set-time verification but makes order_new abort 100% for customers. Either deploy the .wip file to a public endpoint (GitHub Pages / IPFS / your own website) and set this to the public URL, or leave it empty (\"\") to skip WIP verification (TESTING ONLY). Example: \"https://cdn.example.com/products/phone_v1.wip\""
                       },
                       "wip_hash": {
-                        "type": "string",
-                        "description": "The 'meta.hash' field INSIDE the sale's WIP file (a content hash of the file's JSON payload), committed on-chain by the merchant. NOT the SHA-256 of the .wip file bytes — hashing the downloaded file (shasum -a 256) yields a DIFFERENT value and fails verification; use the hash embedded in the file's meta section (wip_file verify reports it). BUY RULE: if this is NON-EMPTY, the buyer MUST pass this exact value as wip_hash when creating an order (ServiceBuyItem.wip_hash) — NEVER use \"\". Pinning the on-chain hash prevents the merchant from replacing the WIP file (a legitimate update) between the buyer's view and order placement, ensuring 'what you see is what you get'. EMPTY means no hash was committed (TESTING ONLY, no delivery-integrity guarantee)."
+                        "default": "",
+                        "description": "The 'meta.hash' field INSIDE the sale's WIP file (a content hash of the file's JSON payload), committed on-chain by the merchant. NOT the SHA-256 of the .wip file bytes — hashing the downloaded file (shasum -a 256) yields a DIFFERENT value and fails verification; use the hash embedded in the file's meta section (wip_file verify reports it). BUY RULE: if this is NON-EMPTY, the buyer MUST pass this exact value as wip_hash when creating an order (ServiceBuyItem.wip_hash) — NEVER use \"\". Pinning the on-chain hash prevents the merchant from replacing the WIP file (a legitimate update) between the buyer's view and order placement, ensuring 'what you see is what you get'. EMPTY means no hash was committed (TESTING ONLY, no delivery-integrity guarantee).",
+                        "type": "string"
                       }
                     },
                     "required": [
@@ -427,7 +458,7 @@
                     "properties": {
                       "name": {
                         "type": "string",
-                        "description": "Name of the product or service for sale"
+                        "description": "Name of the product or service for sale. ⚠️ 64-BYTE BUY LIMIT (F-RQ-01): the chain lists this name up to 256 bytes but validates the BUYER-SENT item name at only 64 bytes at buy time. A name of 65–256 bytes lists fine yet makes the SKU PERMANENTLY unbuyable — every order aborts E_NAME_LENGTH_EXCEEDED (abort 1). Keep SKU names ≤ 64 bytes (UTF-8); renaming cannot fix a dead SKU (the buy path matches items by EXACT name — a new name is a NEW SKU). service_quote.buyable reports this per item."
                       },
                       "price": {
                         "anyOf": [
@@ -460,8 +491,9 @@
                         "description": "WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. ⚠️ NETWORK DEPLOYMENT REQUIRED: the URL is stored ON-CHAIN and every customer fetches it when placing an order. A local file path (C:\\..., /path/file.wip), a localhost/loopback URL or a LAN private-IP URL is unreachable by customers on other machines — it passes the merchant-side set-time verification but makes order_new abort 100% for customers. Either deploy the .wip file to a public endpoint (GitHub Pages / IPFS / your own website) and set this to the public URL, or leave it empty (\"\") to skip WIP verification (TESTING ONLY). Example: \"https://cdn.example.com/products/phone_v1.wip\""
                       },
                       "wip_hash": {
-                        "type": "string",
-                        "description": "The 'meta.hash' field INSIDE the sale's WIP file (a content hash of the file's JSON payload), committed on-chain by the merchant. NOT the SHA-256 of the .wip file bytes — hashing the downloaded file (shasum -a 256) yields a DIFFERENT value and fails verification; use the hash embedded in the file's meta section (wip_file verify reports it). BUY RULE: if this is NON-EMPTY, the buyer MUST pass this exact value as wip_hash when creating an order (ServiceBuyItem.wip_hash) — NEVER use \"\". Pinning the on-chain hash prevents the merchant from replacing the WIP file (a legitimate update) between the buyer's view and order placement, ensuring 'what you see is what you get'. EMPTY means no hash was committed (TESTING ONLY, no delivery-integrity guarantee)."
+                        "default": "",
+                        "description": "The 'meta.hash' field INSIDE the sale's WIP file (a content hash of the file's JSON payload), committed on-chain by the merchant. NOT the SHA-256 of the .wip file bytes — hashing the downloaded file (shasum -a 256) yields a DIFFERENT value and fails verification; use the hash embedded in the file's meta section (wip_file verify reports it). BUY RULE: if this is NON-EMPTY, the buyer MUST pass this exact value as wip_hash when creating an order (ServiceBuyItem.wip_hash) — NEVER use \"\". Pinning the on-chain hash prevents the merchant from replacing the WIP file (a legitimate update) between the buyer's view and order placement, ensuring 'what you see is what you get'. EMPTY means no hash was committed (TESTING ONLY, no delivery-integrity guarantee).",
+                        "type": "string"
                       }
                     },
                     "required": [
@@ -667,6 +699,34 @@
               ],
               "additionalProperties": false,
               "description": "Suspend or resume ONE product without removing it (keeps price/stock/WIP binding). The retail-style 'out of stock / listing inactive' state. Only the named product is touched; an unknown sale_name aborts on chain (code 32) — the MCP pre-gate refuses unknown names before send; the response carries a {field, before, after} read-back delta."
+            },
+            {
+              "type": "object",
+              "properties": {
+                "op": {
+                  "type": "string",
+                  "const": "wip_set"
+                },
+                "sale_name": {
+                  "type": "string",
+                  "description": "Name of the product whose WIP file is (re)bound"
+                },
+                "wip": {
+                  "type": "string",
+                  "description": "New WIP file URL for the product. Same network-deployment rule as the add/set wip field: production MUST use a public HTTP URL to a .wip file (a local path, localhost/loopback or LAN URL passes the merchant-side set-time verification but aborts order_new for every customer). \"\" clears WIP verification (TESTING ONLY — the product then has no pin)."
+                },
+                "wip_hash": {
+                  "description": "Expected meta.hash embedded in the new WIP file — when provided it is VERIFIED against the file before send (mismatch aborts pre-send); the on-chain pin is always derived from the file's own meta.hash. Pass it whenever the value is known: after the rebind, buyers pinning the OLD hash abort at quote (E_WIP_HASH_NOT_MATCH) until they re-copy the NEW hash.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "op",
+                "sale_name",
+                "wip"
+              ],
+              "additionalProperties": false,
+              "description": "Rebind ONE product's WIP file (and pin) without touching its price, stock or suspension — fields not supplied here keep the live on-chain values. An unknown sale_name aborts on chain (code 32) — the MCP pre-gate resolves the name against the live sales list and refuses the call before send. Executed as read-merge-rewrite: the handler reads the live sales list, changes only the named product's wip/wip_hash, and replays the full table as an op:set — a concurrent catalog edit between read and rewrite would be overwritten, so run this when no other catalog change is in flight. Announce the new pin hash to holders of the old one: their orders abort E_WIP_HASH_NOT_MATCH after the rebind until they re-copy it."
             }
           ]
         },
@@ -715,7 +775,7 @@
                 "order"
               ],
               "additionalProperties": false,
-              "description": "Put back the units one refunded order purchased, read from the order's own purchase lines (the caller cannot add extra units). Two-pass all-or-nothing on chain: every line must be restock-flagged and still live before the first unit moves (unflagged → code 46, delisted → code 32), so a partial restock is impossible. Once-per-order (code 49 on replay) and ownership-bound (a foreign order aborts code 26); the applied state is queryable via the restock_applied read. Emits one stock-restocked event per line."
+              "description": "Put back the units one refunded order purchased, read from the order's own purchase lines (the caller cannot add extra units). Two-pass all-or-nothing on chain: every line must be restock-flagged and still live before the first unit moves (unflagged → code 46, delisted → code 32), so a partial restock is impossible. Once-per-order (code 49 on replay) and ownership-bound (a foreign order aborts code 26); the applied state lives in a RestockStamp dynamic field on the service (no public query primitive) — the MCP pre-gate reads that stamp before send and refuses a replay (restock_order_already_applied) so no gas is burned. Emits one stock-restocked event per line."
             }
           ]
         },
@@ -947,7 +1007,7 @@
           "properties": {
             "name": {
               "type": "string",
-              "description": "Discount name"
+              "description": "Discount name. MUST be ≤ 64 bytes (UTF-8): the chain applies the same 64-byte name cap to discount rows as to SKU names, at listing time — a longer name aborts E_NAME_LENGTH_EXCEEDED (abort 1) at creation (F-RQ-01)."
             },
             "discount_type": {
               "anyOf": [
@@ -999,38 +1059,46 @@
               "description": "Number of SEPARATE Discount (coupon) objects minted — total delivered = count × number of recipients. Each coupon object is SINGLE-USE (consumed on first use). This is NOT a per-coupon reuse count: count:2 creates 2 independent one-time coupons, not 1 coupon usable twice."
             },
             "recipient": {
-              "type": "object",
-              "properties": {
-                "entities": {
-                  "minItems": 1,
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name_or_address": {
-                        "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)."
-                      },
-                      "local_mark_first": {
-                        "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                        "type": "boolean"
+              "anyOf": [
+                {
+                  "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "entities": {
+                      "minItems": 1,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "name_or_address": {
+                            "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)."
+                          },
+                          "local_mark_first": {
+                            "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                            "type": "boolean"
+                          }
+                        },
+                        "additionalProperties": false,
+                        "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                       }
                     },
-                    "additionalProperties": false,
-                    "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
-                  }
-                },
-                "check_all_founded": {
-                  "default": true,
-                  "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
-                  "type": "boolean"
+                    "check_all_founded": {
+                      "default": true,
+                      "description": "Whether to check all entities are found. Defaults to true: abort and throw if ANY entity cannot be resolved. Set false only when partial resolution is explicitly intended (only found IDs are returned)",
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "entities",
+                    "check_all_founded"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Used to batch find account or object IDs by name"
                 }
-              },
-              "required": [
-                "entities",
-                "check_all_founded"
               ],
-              "additionalProperties": false,
               "description": "Discount recipient. OBJECT FORM REQUIRED (T9 az3-mn-261013): a bare string is REJECTED here — pass {entities: [{name_or_address: '<account_name_or_0x_address>'}]} (example: {entities: [{name_or_address: 'buyer1'}]}). Total coupons delivered = count × number of recipients."
             },
             "transferable": {
@@ -1071,18 +1139,26 @@
               "description": "Coupon object IDs or local names to transfer. You MUST own these Discount objects. Each coupon must have been minted with transferable:true — otherwise the chain aborts with E_DISCOUNT_NOT_TRANSFERABLE (semantic code service:10). Coupons stay single-use; the transfer does not change that. There is NO batch entry on-chain — each coupon is delivered by its own singleton call (fanned out automatically); prefer ONE coupon per transaction for coupon migrations (SDK cap MAX_DISCOUNT_COUNT_ONCE still applies)."
             },
             "recipient": {
-              "type": "object",
-              "properties": {
-                "name_or_address": {
-                  "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)."
+              "anyOf": [
+                {
+                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                 },
-                "local_mark_first": {
-                  "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                  "type": "boolean"
+                {
+                  "type": "object",
+                  "properties": {
+                    "name_or_address": {
+                      "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)."
+                    },
+                    "local_mark_first": {
+                      "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                 }
-              },
-              "additionalProperties": false,
+              ],
               "description": "Destination address (or account/local mark resolvable to one). ALL listed coupons are moved to this single address in one call."
             }
           },
@@ -1145,7 +1221,7 @@
                                       "type": "integer",
                                       "minimum": 0,
                                       "maximum": 255,
-                                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails such as full refunds). SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
+                                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails whose payee is NOT the order itself, such as settlement releases and incentive/bounty claims). NEVER arm 254 on a refund rail: a refund pays the submitted Order through user slot 0, and a refund leg re-entered in a later renewal period would abort E_ONCE_TRIGGERED (16) forever — refund once-ness comes from the terminal-node topology, never from a once slot. SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
                                     }
                                   },
                                   "required": [
@@ -1158,26 +1234,34 @@
                                   "type": "object",
                                   "properties": {
                                     "Entity": {
-                                      "type": "object",
-                                      "properties": {
-                                        "name_or_address": {
-                                          "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)."
+                                      "anyOf": [
+                                        {
+                                          "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                                         },
-                                        "local_mark_first": {
-                                          "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                                          "type": "boolean"
+                                        {
+                                          "type": "object",
+                                          "properties": {
+                                            "name_or_address": {
+                                              "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)."
+                                            },
+                                            "local_mark_first": {
+                                              "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                                              "type": "boolean"
+                                            }
+                                          },
+                                          "additionalProperties": false,
+                                          "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                                         }
-                                      },
-                                      "additionalProperties": false,
-                                      "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
+                                      ],
+                                      "description": "Account or address lookup. Can be a simple string (recommended for AI) or full object with explicit local_mark_first control. String form auto-converts to { name_or_address: <string>, local_mark_first: true }."
                                     }
                                   },
                                   "required": [
                                     "Entity"
                                   ],
                                   "additionalProperties": false,
-                                  "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
+                                  "description": "Static address resolved via LocalMark. Format: {Entity: 'mark_name'} (string shorthand) or {Entity: {name_or_address: 'mark_name'}} (full object).F-RQ-11 (rq2 promotion): string shorthand accepted — the FIX-005 transform resolves local marks first."
                                 },
                                 {
                                   "type": "object",
@@ -1331,7 +1415,7 @@
                                   "type": "integer",
                                   "minimum": 0,
                                   "maximum": 255,
-                                  "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails such as full refunds). SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
+                                  "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails whose payee is NOT the order itself, such as settlement releases and incentive/bounty claims). NEVER arm 254 on a refund rail: a refund pays the submitted Order through user slot 0, and a refund leg re-entered in a later renewal period would abort E_ONCE_TRIGGERED (16) forever — refund once-ness comes from the terminal-node topology, never from a once slot. SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
                                 }
                               },
                               "required": [
@@ -1344,26 +1428,34 @@
                               "type": "object",
                               "properties": {
                                 "Entity": {
-                                  "type": "object",
-                                  "properties": {
-                                    "name_or_address": {
-                                      "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)."
+                                  "anyOf": [
+                                    {
+                                      "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                                     },
-                                    "local_mark_first": {
-                                      "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                                      "type": "boolean"
+                                    {
+                                      "type": "object",
+                                      "properties": {
+                                        "name_or_address": {
+                                          "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)."
+                                        },
+                                        "local_mark_first": {
+                                          "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                                          "type": "boolean"
+                                        }
+                                      },
+                                      "additionalProperties": false,
+                                      "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                                     }
-                                  },
-                                  "additionalProperties": false,
-                                  "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
+                                  ],
+                                  "description": "Account or address lookup. Can be a simple string (recommended for AI) or full object with explicit local_mark_first control. String form auto-converts to { name_or_address: <string>, local_mark_first: true }."
                                 }
                               },
                               "required": [
                                 "Entity"
                               ],
                               "additionalProperties": false,
-                              "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
+                              "description": "Static address resolved via LocalMark. Format: {Entity: 'mark_name'} (string shorthand) or {Entity: {name_or_address: 'mark_name'}} (full object).F-RQ-11 (rq2 promotion): string shorthand accepted — the FIX-005 transform resolves local marks first."
                             },
                             {
                               "type": "object",
@@ -1524,18 +1616,26 @@
           "type": "object",
           "properties": {
             "receipt": {
-              "type": "object",
-              "properties": {
-                "name_or_address": {
-                  "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)."
+              "anyOf": [
+                {
+                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                 },
-                "local_mark_first": {
-                  "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
-                  "type": "boolean"
+                {
+                  "type": "object",
+                  "properties": {
+                    "name_or_address": {
+                      "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)."
+                    },
+                    "local_mark_first": {
+                      "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks",
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account. name_or_address is REQUIRED — {} resolves to nothing useful and is rejected."
                 }
-              },
-              "additionalProperties": false,
+              ],
               "description": "Receipt address that will receive the withdrawn funds (as a new Payment object)"
             },
             "payment_info": {
@@ -1867,6 +1967,13 @@
       "additionalProperties": false,
       "description": "On-chain Service operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create a Service. 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. (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."
     },
+    "idempotency_key": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._:-]+$",
+      "description": "F-RQ-13A (prescription ⑨): idempotency key for this business attempt. REPLAY GUARD: if a previous call with the SAME key is still open (dispatched but outcome unresolved, or already committed), this call is HELD — you get a structured state_conflict envelope with the prior attempt's verification data instead of a second on-chain submission (the ghost-order guard: two live mainnet orders, two escrows). Lifecycle: a deterministic failure (nothing submitted / provably reverted) clears the key — fix the cause and retry with the SAME key; an unknown-outcome failure (submission may have landed) keeps the key HELD — verify on-chain state first (result.submission_verification tells you where to look), and only retry with a NEW key once the outcome is resolved. Keep one key per business attempt (e.g. 'ord-20261030-042-buy'); do not reuse across attempts."
+    },
     "env": {
       "type": "object",
       "properties": {
@@ -2005,7 +2112,7 @@
                       "type": "integer",
                       "minimum": 0,
                       "maximum": 255,
-                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails such as full refunds). SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
+                      "description": "Identifier (0-255) for data lookup in Guard table. Slot consensus (enforced on-chain at guard table construction): 0-220 = user slots (free for business guards); 221-253 = PROTOCOL-RESERVED (rejected on-chain — reserved so future protocol features get fixed slots without colliding with published guards); 255 = ONCE replay-protection slot on Allocation (byte-keyed, the submitted bytes are the once-key — use for per-period keys like period-<N>); 254 = ONCE-FOR-OBJECT slot on Allocation (chain-derived key = bcs(the Allocation's payment_info.for_object); the submitted bytes are ignored and the submission only arms the slot — use for one-shot per-order rails whose payee is NOT the order itself, such as settlement releases and incentive/bounty claims). NEVER arm 254 on a refund rail: a refund pays the submitted Order through user slot 0, and a refund leg re-entered in a later renewal period would abort E_ONCE_TRIGGERED (16) forever — refund once-ness comes from the terminal-node topology, never from a once slot. SLOT 0 SEMANTICS: slot 0 carries the transacted Order address by convention. As a submission slot it is legal on order/allocation/machine rails (the order exists when those verify), but FORBIDDEN on a Service buy_guard — the order does not exist when the buy-time passport is verified, so the mount is refused (service abort 43)."
                     },
                     "b_submission": {
                       "type": "boolean",