@wowok/agent-mcp 3.3.9 → 3.4.1

package/dist/schemas/onchain_operations_machine.schema.json

@@ -197,38 +197,47 @@
                   "minLength": 1
                 },
                 "operators": {
-                  "type": "object",
-                  "properties": {
-                    "entities": {
-                      "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."
-                      }
-                    },
-                    "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": "Used to batch find account or object IDs by name"
+                  "description": "Batch account or address lookup. Can be an array of strings (recommended for AI) or full object with explicit control. Array form auto-converts to { entities: [...], check_all_founded: true }. Empty arrays and {} elements are REJECTED (no-op transaction guard)."
                 }
               },
               "required": [
@@ -523,10 +532,10 @@
                         "additionalProperties": false,
                         "description": "Node in Machine object"
                       },
-                      "description": "List of nodes to add or set."
+                      "description": "List of nodes to add (or replace in place when bReplace=true)."
                     },
                     "bReplace": {
-                      "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging.",
+                      "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging. This is the ONLY supported way to rewrite nodes on an EXISTING Machine.",
                       "type": "boolean"
                     }
                   },
@@ -714,7 +723,7 @@
                         "additionalProperties": false,
                         "description": "Node in Machine object"
                       },
-                      "description": "List of nodes to add or set."
+                      "description": "List of nodes for a freshly CREATED Machine. xk9 F-02: REFUSED on an existing Machine — op set implies a clear-and-rewrite of the on-chain node table that permanently corrupts it (E_EMPTY_MACHINE on every later publish, no repair). To rewrite an existing Machine use op:add with bReplace:true."
                     },
                     "bReplace": {
                       "description": "Whether to replace existing nodes. If true, existing nodes will be replaced; if false, nodes will be added by merging.",
@@ -726,7 +735,7 @@
                     "nodes"
                   ],
                   "additionalProperties": false,
-                  "description": "Set nodes."
+                  "description": "Set nodes (CREATE-ONLY — refused on an existing Machine; use add+bReplace there)."
                 },
                 {
                   "type": "object",
@@ -1061,7 +1070,7 @@
               "properties": {
                 "json_or_markdown_file": {
                   "type": "string",
-                  "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing a workflow STATE that an order\ncan rest in. Its Pairs are the INCOMING edges — this is the one convention the\nchain enforces, and getting it backwards silently builds a wrong graph:\n- name: Node identifier — the DESTINATION of every pair it owns\n- role: (optional) business role tag for display layers — one of draft/active/delivered/final/cancelled. SESSION METADATA ONLY (not stored on-chain; echoed back as a NODE ROLES warning)\n- pairs: Array of {prev_node, forwards, threshold} — edges ENTERING this node. The key is `prev_node`; `prior_node` is not recognized and is silently dropped.\n- forwards: Operations that advance INTO this node FROM its prev_node (NOT operations available from this node)\n- threshold: Weight required to migrate into this node along that pair\n\nDiagram `A --[Go]--> B` therefore lives in node **B**: {name:\"B\", pairs:[{prev_node:\"A\", forwards:[{name:\"Go\", weight:1}]}]}.\n\n**Forward names must determine the destination.** `next_node` is a CALLER argument\n(progress.move:540) and the chain resolves (current, next_node, forward) inside the\ndestination node (machine.move:275), so one forward name shared by two destinations\nfrom the same prev_node is legal and lets the caller pick the outcome — including\nwhether a refund Allocator ever fires. Give each destination its own forward name.\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
+                  "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing a workflow STATE that an order\ncan rest in. Its Pairs are the INCOMING edges — this is the one convention the\nchain enforces, and getting it backwards silently builds a wrong graph:\n- name: Node identifier — the DESTINATION of every pair it owns\n- role: (optional) business role tag for display layers — one of draft/active/delivered/final/cancelled. SESSION METADATA ONLY (not stored on-chain; echoed back as a NODE ROLES warning)\n- pairs: Array of {prev_node, forwards, threshold} — edges ENTERING this node. The key is `prev_node`; `prior_node` is not recognized and is silently dropped.\n- forwards: Operations that advance INTO this node FROM its prev_node (NOT operations available from this node)\n- threshold: Weight required to migrate into this node along that pair\n\nDiagram `A --[Go]--> B` therefore lives in node **B**: {name:\"B\", pairs:[{prev_node:\"A\", forwards:[{name:\"Go\", weight:1}]}]}.\n\n**Forward names must determine the destination.** `next_node` is a CALLER argument\nand the chain resolves (current, next_node, forward) inside the\ndestination node, so one forward name shared by two destinations\nfrom the same prev_node is legal and lets the caller pick the outcome — including\nwhether a refund Allocator ever fires. Give each destination its own forward name.\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
                 }
               },
               "required": [
@@ -1072,11 +1081,11 @@
           ]
         },
         "pause": {
-          "description": "Whether to pause generating new Progress objects. Chain truth (machine.move:657, the progress-generation entry asserts !bPaused): the pause gates NEW order entry only — in-flight Progress keeps advancing and settling (yfd-ln F-13 misread this as a freeze switch; it never was one).",
+          "description": "Whether to pause generating new Progress objects. Chain truth (the progress-generation entry asserts !bPaused): the pause gates NEW order entry only — in-flight Progress keeps advancing and settling (yfd-ln F-13 misread this as a freeze switch; it never was one).",
           "type": "boolean"
         },
         "publish": {
-          "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable. ⚠️ PUBLISH IS A ONE-WAY DOOR AND THE CHAIN VALIDATES THE WHOLE GRAPH AT THAT MOMENT: the on-chain publish gate rejects a Machine that is empty, has no entry edge (no pair with prev_node:\"\"), has an entry pair with no forward, references a prev_node that is not a node of this Machine, carries a forward with neither namedOperator nor permissionIndex (a guard is NOT an identity), or has a pair whose threshold exceeds the sum of its forward weights (each forward counts at most once). These aborts (machine:17-22) fire BEFORE the publish lands, so the graph is still editable — but after it succeeds, nodes/forwards, Guard bindings and Service.machine are frozen forever, and a broken graph would only surface at the first transition with no repair path. Send the nodes in the SAME call as publish:true (bReplace:true or op:\"set\") so the complete graph is validated together. ⚠️ Before publishing, enumerate the graph STOP NODES (nodes with no outgoing Pair) plus every waiting state (review window, handover, open dispute) and verify each has a defined fund exit in the Service order_allocators — withdrawal (release) AND refund. Machine + Allocator are immutable after publish (IMMUT-001); an uncovered stop node strands funds permanently (rule R-M5-03, checklist pattern.fund_flow_stop_node_coverage).",
+          "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable. ⚠️ PUBLISH IS A ONE-WAY DOOR AND THE CHAIN VALIDATES THE WHOLE GRAPH AT THAT MOMENT: the on-chain publish gate rejects a Machine that is empty, has no entry edge (no pair with prev_node:\"\"), has an entry pair with no forward, references a prev_node that is not a node of this Machine, carries a forward with neither namedOperator nor permissionIndex (a guard is NOT an identity), or has a pair whose threshold exceeds the sum of its forward weights (each forward counts at most once). These aborts (machine:17-22) fire BEFORE the publish lands, so the graph is still editable — but after it succeeds, nodes/forwards, Guard bindings and Service.machine are frozen forever, and a broken graph would only surface at the first transition with no repair path. Send the nodes in the SAME call as publish:true (bReplace:true or op:\"set\") so the complete graph is validated together. ⚠️ Before publishing, enumerate the graph STOP NODES (nodes with no outgoing Pair) plus every waiting state (review window, handover, open dispute) and verify each has a defined fund exit in the Service order_allocators — withdrawal (release) AND refund. Machine + Allocator are immutable after publish (IMMUT-001); an uncovered stop node strands funds permanently (rule R-M5-03, checklist pattern.fund_flow_stop_node_coverage). ⚠️ REBUILD COST DISCLOSURE (S12-②, ksk4 F-01): every business constant you bake into this graph (campaign deadline, goal, windows, schedules) becomes immutable WITH the machine. Changing even ONE constant after publish requires: new guard → clone the whole node graph into a NEW machine → publish → a NEW Service → re-hang every repository/reward/arbitration/allocator/WIP → republish (≈5 txs / ~1 min measured on a 16-node graph), and in-flight orders stay pointed at the OLD machine forever. THIS OPERATION WILL REQUIRE A NEW SERVICE if any baked-in parameter later changes — finalize mutable business parameters BEFORE publishing (Campaign-structure change is protocol-train scoped; the MCP face cannot patch a published machine).",
           "type": "boolean"
         },
         "owner_receive": {
@@ -1230,6 +1239,13 @@
       "additionalProperties": false,
       "description": "On-chain Machine operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, permission, ...} to create a Machine. 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": {
@@ -1250,7 +1266,7 @@
           "type": "boolean"
         },
         "network": {
-          "description": "Omit in client/chat contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
+          "description": "Omit in chat-client contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
           "type": "string",
           "enum": [
             "localnet",
@@ -1368,7 +1384,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",
@@ -1685,7 +1701,7 @@
                                 }
                               },
                               "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."
+                              "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."
                             },
                             {
                               "type": "string"
@@ -1710,6 +1726,7 @@
                               "type": "object",
                               "properties": {
                                 "entities": {
+                                  "minItems": 1,
                                   "type": "array",
                                   "items": {
                                     "type": "object",
@@ -1724,7 +1741,7 @@
                                       }
                                     },
                                     "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."
+                                    "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": {

package/dist/schemas/onchain_operations_order.schema.json

@@ -18,37 +18,46 @@
         },
         "agent": {
           "description": "Order agent. 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": {
-              "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."
-              }
-            },
-            "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
+          ]
         },
         "required_info": {
           "description": "Credential recorded on the order: the merchant's IM user address resolved from the Service's Contact (zero cost) or a WTS Proof object id (on-chain delivery proof embedding that IM address and timestamp; costs gas). The information itself is delivered via Wowok Messenger. ACCEPTED FORMS (upwc-cat-261017 T10 live probe): a Contact/Proof object ID (0x…), an account ADDRESS, or a REGISTERED mark name — a bare account display name is not an object reference and fails with 'not found'. WRITE PERMISSION: OWNER-ONLY — only the order owner (the buyer) can set or clear this field; any other signer (including the merchant/service owner) aborts on-chain (MoveAbort 1, 'Not the owner'). The merchant's role is to READ it and to receive the info over Messenger. ATTESTATION SEMANTICS: the recorded VALUE is self-attested and has no on-chain readback — never trust the value itself as a gate condition. A PRESENCE gate IS legitimate on-chain (query order.required_info is some — see pattern.required_info_evidence_gate): it proves the buyer recorded a credential before handover, without asserting what the credential says.",
@@ -317,18 +326,26 @@
         },
         "transfer_to": {
           "description": "Set 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
+          ]
         },
         "order_renew": {
           "description": "Renewal in ONE transaction: pays into the order's allocation and advances the renew forward (fund + record + advance in a single step). Replaces the legacy 3-transaction renewal split. The new Payment's sole recipient is the allocation object itself (enforced on-chain). PRE-STATE CONSTRAINT (esound-mn-261021 B-1): guards on the advanced forward read the COMMITTED pre-transaction balance — this same-PTB payment is INVISIBLE to them; NEVER bind an allocation.balance gate to the forward this call advances (it always aborts; identity/signer guards are fine). If the forward DOES carry a balance gate, do NOT call this tool — execute the TWO-TX RENEW RECIPE (esound2-mn-261022 R2-1): a balance/fund-gated renew or capture forward is satisfiable only when the capture funds were committed in a PRIOR transaction — split the coupled one-PTB call into TWO transactions: TX1 commits the period/capture funds into the order's Allocation (create the escrowed payment record, then have the allocation receive it; a hand-built PTB until the allocation top-up primitive ships on the package face), WAIT for its success, then TX2 advances the forward with the plain order-holder progress call — the gate now reads the committed balance and passes. The ONE-PTB data.order_renew stays the route for GATE-LESS renew forwards only. NEVER retry the same-PTB shape after the abort: the guard verdict is structural (guards read the pre-transaction snapshot, esound-mn-261021 B-1), not a transient balance shortfall. Structural alternatives that avoid the second transaction: prepaid-full at buy (staged-RELEASE semantics) or per-period NEW Orders.",
@@ -469,6 +486,13 @@
       "additionalProperties": false,
       "description": "On-chain, operate on an Order object."
     },
+    "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": {
@@ -489,7 +513,7 @@
           "type": "boolean"
         },
         "network": {
-          "description": "Omit in client/chat contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
+          "description": "Omit in chat-client contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
           "type": "string",
           "enum": [
             "localnet",
@@ -607,7 +631,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",
@@ -924,7 +948,7 @@
                                 }
                               },
                               "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."
+                              "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."
                             },
                             {
                               "type": "string"
@@ -949,6 +973,7 @@
                               "type": "object",
                               "properties": {
                                 "entities": {
+                                  "minItems": 1,
                                   "type": "array",
                                   "items": {
                                     "type": "object",
@@ -963,7 +988,7 @@
                                       }
                                     },
                                     "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."
+                                    "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": {

package/dist/schemas/onchain_operations_payment.schema.json

@@ -54,19 +54,27 @@
                 "type": "object",
                 "properties": {
                   "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": "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."
+                    ],
+                    "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 }."
                   },
                   "amount": {
                     "anyOf": [
@@ -200,6 +208,13 @@
       ],
       "description": "On-chain Payment operations. TWO modes:\n(1) CREATE: Set 'object' with {name, type_parameter, ...}, 'revenue', and 'info' to create a new Payment.\n(2) RECEIVE: Set {receive: true} to unwrap CoinWrappers to your wallet. Provide 'object' (<coinwrapper_id_or_name>) to unwrap a specific one, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. type_parameter optional — auto-derived from the CoinWrapper's type."
     },
+    "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": {
@@ -220,7 +235,7 @@
           "type": "boolean"
         },
         "network": {
-          "description": "Omit in client/chat contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
+          "description": "Omit in chat-client contexts — the runtime stamps the user's CURRENT network (the client's UI selection). Standalone MCP/CLI: omit to use the current network; set ONLY when the user explicitly names a different network (a mismatch pauses for user confirmation). Never guess or hardcode a network.",
           "type": "string",
           "enum": [
             "localnet",