@wowok/agent-mcp 3.3.2 → 3.3.5

package/dist/schemas/onchain_operations_machine.schema.json

@@ -1213,6 +1213,15 @@
               "type": "null"
             }
           ]
+        },
+        "reentry_kind": {
+          "description": "AP-3 loop-semantics declaration for the publish audit (ctra F-06 root cure): overrides the word-stem loop classifier when the node graph contains a cycle. 'none' = default (word-stem classification) / 'review-loop' = same-order no-charge revisits / 'paid-cycle' = per-revisit fee, fund gate required. MCP-side audit declaration ONLY (pre_publish harness hook) — never sent on-chain; the handler strips it before the SDK call. Mirror of the template frontmatter twin (template-loader).",
+          "type": "string",
+          "enum": [
+            "none",
+            "review-loop",
+            "paid-cycle"
+          ]
         }
       },
       "required": [
@@ -1359,7 +1368,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_order.schema.json

@@ -62,6 +62,10 @@
             }
           ]
         },
+        "required_info_bind": {
+          "description": "Bind a WTS Proof object as this order's required_info credential — the CONTROLLED alternative to required_info. OWNER-ONLY: the order owner (the buyer) signs; any other signer (including the merchant or an agent) aborts (E_NOT_THE_OWNER). The chain verifies the Proof is about THIS order AND was created by the order holder BEFORE writing, and freezes the Proof object on success — a Proof about another order or created by another account is refused (E_REQUIRED_INFO_PROOF_NOT_BOUND) with NOTHING written, closing the cross-order proof-reuse hole that plain required_info has. The sensitive payload itself (channel name, contact address, ...) stays off-chain inside the Proof — exchange/inspect it over Wowok Messenger. ACCEPTED FORMS: a Proof object ID (0x…) or a REGISTERED mark name. Mutually exclusive with required_info in one call (both entries write order.required_info).",
+          "type": "string"
+        },
         "progress": {
           "description": "Advance order process",
           "type": "object",
@@ -157,7 +161,25 @@
           "additionalProperties": false
         },
         "arb_claim_compensation": {
-          "description": "Specify the adjudicated Arb object to obtain order compensation. Succeeds even when the ruled indemnity is 0 — the claim closes the case (state 5) and lets the arbitrator withdraw the dispute fee immediately.",
+          "description": "Specify the adjudicated Arb object to obtain order compensation. ZERO-INDEMNITY GATE (BF-14, chain abort 11): when the ruling's indemnity is 0 (a dismissal) the claim is REFUSED on-chain — the case stays open, the dispute fee stays escrowed (withdrawable by the arbitrator only after the 30-day window closes with no objection, or blocked while an objection is pending), and `order.claimed_by` is NOT written. A claim that DOES pay (indemnity > 0) closes the case (state 5), pays the claimant, writes `order.claimed_by`, and releases the fee path. DIRECTION CAUTION: because only paying claims write `claimed_by`, a dismissal leaves it `none` — refund-style rails gated on `claimed_by == none` stay LIVE after a dismissal, while merchant-recovery rails gated on `claimed_by != none` can never fire (F-BS-54). Read ruling DIRECTION from `arb.indemnity.amount` (query 1641), never from `claimed_by`. F05 REVERSE GATE (yfd-ln-261024): when this order's escrow is ALREADY fully released (allocation balance 0 of a positive order amount), the claim is REFUSED unless acknowledge_dual_payout is true — pairing a paid compensation with a completed escrow track is a netting decision the operator must state (see acknowledge_dual_payout).",
+          "type": "object",
+          "properties": {
+            "arb": {
+              "type": "string",
+              "description": "Arb object ID or name."
+            }
+          },
+          "required": [
+            "arb"
+          ],
+          "additionalProperties": false
+        },
+        "acknowledge_dual_payout": {
+          "description": "Explicit opt-in for a KNOWN double payout on the compensation-claim direction: when this order's escrow is already FULLY released (allocation balance 0 of a positive order amount) and this call claims the arbitration compensation on top, the call is REFUSED unless this flag is true. The escrow track and the compensation track are independent by design — the chain will not stop the second payout, so the operator must state the netting decision deliberately. Leave unset for claims on orders whose escrow is intact or partially released.",
+          "type": "boolean"
+        },
+        "arb_case_conclude": {
+          "description": "DISMISSAL CONVERGER (F-BS-54/56, F-OF2-01): stamp a CONCLUDED, DEFENDANT-FAVORED ruling onto this order through the service's case-conclusion entry so the `claimed_by == none` refund rails close AT RULING TIME instead of staying live forever. PERMISSIONLESS: any keeper (merchant agent, watchdog, even the buyer) may drive it; it writes the claimed_by=case flag and MOVES NO FUNDS. The chain refuses anything but a concluded (Arbitrated/Withdrawn) case leaving NO indemnity (E_CASE_NOT_DISMISSAL_CONCLUSION, abort 48). TYPICAL KEEPER LOOP after a 0-indemnity ruling: arb_claim_compensation aborts 11 (BF-14 zero-indemnity gate) → call THIS to close the refund rails → the escrow can then only exit through the merchant-recovery rails.",
           "type": "object",
           "properties": {
             "arb": {
@@ -309,7 +331,7 @@
           "additionalProperties": false
         },
         "order_renew": {
-          "description": "Renewal in ONE transaction: pays into the order's allocation and advances the renew forward atomically (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).",
+          "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.",
           "type": "object",
           "properties": {
             "allocation": {
@@ -585,7 +607,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_progress.schema.json

@@ -325,12 +325,12 @@
           ]
         },
         "review": {
-          "description": "Structured review composite (REVIEW component): after this forward succeeds, write the structured reputation record into a Repository (+ optional reward claim), reusing this call's passport submission. Requires operate (the chain fires only after a successful forward).",
+          "description": "Structured review composite (REVIEW component): with a passport submission the structured-record write runs BEFORE this forward (the review-edge credential anchors the PRE node — F01), then the forward, then the optional reward claim. Requires operate. Steps are reported in semantic.review_steps.",
           "type": "object",
           "properties": {
             "repository": {
               "type": "string",
-              "description": "Repository object ID or name that stores the structured reputation record. The matching policy key must accept a JSON payload {rating, tags?, orderRef?}. id_from options (C30): Signer = one record per BUYER (rewrite = own-record overwrite); None + a write_guard with id_from_submission = one record per bound OBJECT/ORDER (the row id is the raw bound Order address — the verified once-per-order review shape); Clock = append-only log. PREFERRED: the service's review repository EMITTED BY THE BUILD PLAN when review_mode was set (AR-1) — resolve it from the service's repositories list (service_panorama / onchain_objects, name suffix '_review') — never guess an address."
+              "description": "Repository object ID or name that stores the structured reputation record. The matching policy key must accept a JSON payload {rating, tags?, orderRef?}. id_from options (C30): None = one record per bound OBJECT/ORDER with a write_guard (row id = the order address — the compile-emitted default AND the verified once-per-order review shape, F09); Signer = one record per BUYER (rewrite = own-record overwrite; a repeat buyer can only ever hold ONE row across all their orders — do not use for per-order reviews); Clock = append-only log. PREFERRED: the service's review repository EMITTED BY THE BUILD PLAN when review_mode was set (AR-1) — resolve it from the service's repositories list (service_panorama / onchain_objects, name suffix '_review') — never guess an address."
             },
             "policy": {
               "description": "Policy RULE NAME to write under (the repository's PolicyRule whose value_type is String — the chain writes the structured record as a JSON string row). MUST match an existing policy of the target repository. Default 'review' (the compile-emitted review policy name). A mismatch aborts the write AFTER the forward — the review-edge credential is single-use, so the row can never be re-written; resolve the exact name from the build plan / service_panorama before calling.",
@@ -356,7 +356,7 @@
               "type": "string"
             },
             "reward_claim": {
-              "description": "Optional reward claim chained after the repository write (fail-isolated: a failed claim never undoes the write or the forward).",
+              "description": "Optional reward claim chained after the repository write (fail-isolated: a failed claim never undoes the write or the forward). PARADIGM NOTE (two-phase, esln E-4): the passport verifies every submission guard BEFORE the forward runs, so a reward guard that READS the review row written by this very chain (impact-gated incentives) cannot pass here — it aborts with E_VERIFY_FAILED even though the row lands moments later. Review-gated rewards are a TWO-STEP flow: this chained claim only fits guards that do NOT read the fresh row; an impact-gated reward is claimed in a SECOND, separate call (fresh submission) after the review row exists.",
               "type": "object",
               "properties": {
                 "reward": {
@@ -530,7 +530,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_proof.schema.json

@@ -248,7 +248,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_repository.schema.json

@@ -496,6 +496,10 @@
                             "description": "vecvecu8"
                           }
                         ]
+                      },
+                      "write_once": {
+                        "description": "Write-once switch. When true, a record written under this policy can never be overwritten: a second write to an EXISTING id aborts with repository error 24 (E_POLICY_WRITE_ONCE_CONFLICT). Multiple distinct ids still write normally. Omitted/false keeps the legacy overwrite-allowed behavior. Judges row identity, not the writer — combine with a Signer id_from for one permanent row per account, or a caller-supplied id for a permanently sealed record.",
+                        "type": "boolean"
                       }
                     },
                     "required": [
@@ -1094,7 +1098,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_reward.schema.json

@@ -243,7 +243,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 (protocol 154): 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 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)."
                       }
                     },
                     "required": [
@@ -307,7 +307,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 (protocol 154): 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 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)."
                       }
                     },
                     "required": [
@@ -357,7 +357,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 (protocol 154): 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 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)."
                   },
                   {
                     "type": "null"
@@ -747,7 +747,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",

package/dist/schemas/onchain_operations_service.schema.json

@@ -548,7 +548,7 @@
                 "value"
               ],
               "additionalProperties": false,
-              "description": "Raise one product's price by a delta. Only the named product is touched; an unknown sale_name is a silent on-chain no-op — the MCP pre-gate resolves the name against the live sales list and refuses the call before send, and the response carries a {field, before, after} read-back delta."
+              "description": "Raise one product's price by a delta. Only the named product is touched; 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, and the response carries a {field, before, after} read-back delta."
             },
             {
               "type": "object",
@@ -570,7 +570,7 @@
                       "type": "string"
                     }
                   ],
-                  "description": "Price DECREASE delta in the Service token's smallest units (e.g. 100000000 = -0.1 WOW). If the delta exceeds the current price, the price clamps to 0. NOT the new absolute price."
+                  "description": "Price DECREASE delta in the Service token's smallest units (e.g. 100000000 = -0.1 WOW). Must not exceed the current price: an oversized reduce ABORTS on chain (code 41) and does NOT clamp. NOT the new absolute price."
                 }
               },
               "required": [
@@ -579,7 +579,7 @@
                 "value"
               ],
               "additionalProperties": false,
-              "description": "Lower one product's price by a delta. Only the named product is touched; an unknown sale_name is a silent on-chain no-op — the MCP pre-gate refuses unknown names before send; the response carries a {field, before, after} read-back delta."
+              "description": "Lower one product's price by a delta. Only the named product is touched; an unknown sale_name aborts on chain (code 32) — the MCP pre-gate refuses unknown names before send; an oversized delta is refused by the chain (code 41) instead of clamping; the response carries a {field, before, after} read-back delta."
             },
             {
               "type": "object",
@@ -610,7 +610,7 @@
                 "value"
               ],
               "additionalProperties": false,
-              "description": "Restock one product by a delta. Only the named product is touched; an unknown sale_name is a silent on-chain no-op — the MCP pre-gate refuses unknown names before send; the response carries a {field, before, after} read-back delta."
+              "description": "Restock one product by a delta. 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",
@@ -641,7 +641,7 @@
                 "value"
               ],
               "additionalProperties": false,
-              "description": "Reduce one product's stock by a delta (e.g. write-off damaged units). Only the named product is touched; an unknown sale_name is a silent on-chain no-op — the MCP pre-gate refuses unknown names before send."
+              "description": "Reduce one product's stock by a delta (e.g. write-off damaged units). Only the named product is touched; an unknown sale_name aborts on chain (code 32) — the MCP pre-gate refuses unknown names before send."
             },
             {
               "type": "object",
@@ -665,7 +665,56 @@
                 "suspension"
               ],
               "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 is a silent on-chain no-op — the MCP pre-gate refuses unknown names before send; the response carries a {field, before, after} read-back delta."
+              "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."
+            }
+          ]
+        },
+        "restock": {
+          "description": "Refund restocking (permission 305 SERVICE_SALES). op:'flag' opts ONE live product into restock-on-refund; op:'order' puts the units a REFUNDED order purchased back on shelf. The order path is all-or-nothing: every purchased line must be flagged and still live before any unit moves (otherwise the chain aborts 46/32), so half a restock is impossible. Do NOT fake a restock with stock_add when the order carries several lines — use op:'order' so quantities come from the order itself.",
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "op": {
+                  "type": "string",
+                  "const": "flag"
+                },
+                "sale_name": {
+                  "type": "string",
+                  "description": "Name of the LIVE product whose restock-on-refund flag is set"
+                },
+                "flagged": {
+                  "type": "boolean",
+                  "description": "true = refunded orders of this SKU put their purchased units back on shelf; false = opt out."
+                }
+              },
+              "required": [
+                "op",
+                "sale_name",
+                "flagged"
+              ],
+              "additionalProperties": false,
+              "description": "Opt ONE live product in/out of restock-on-refund. An unknown sale_name aborts on chain (code 32); delisting the product is the kill switch. Without the flag, the order-level restock op refuses that line (code 46)."
+            },
+            {
+              "type": "object",
+              "properties": {
+                "op": {
+                  "type": "string",
+                  "const": "order"
+                },
+                "order": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Address or local name of the REFUNDED order whose purchased units go back on shelf."
+                }
+              },
+              "required": [
+                "op",
+                "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. Emits one stock-restocked event per line."
             }
           ]
         },
@@ -937,7 +986,7 @@
               "type": "number"
             },
             "allow_zero_total": {
-              "description": "FREE-TIER ESCAPE HATCH (BKN-P2): a coupon that would drive the final total to 0 (MINUS value >= the cheapest SKU price, or RATES value 10000) is BLOCKED at issuance by default. Set true ONLY to declare a deliberate zero-price product: the issuance then proceeds with a disclosure that zero-total orders carry an empty escrow and NEVER trigger reward/incentive rails. Omit (default false) for normal discounts.",
+              "description": "DISCLOSURE-ONLY FLAG — it has NO on-chain effect (F-BS-74: the on-chain Discount struct has no such field; a coupon minted with it is byte-identical to one without, and zero-total BUYS are refused by the chain's zero-total gate regardless — order_new_zero_total_dead_order client-side, abort 42 on-chain). Setting true only downgrades the MCP issuance BLOCK for a coupon that zeroes the cheapest SKU into a warning. There is NO free-product escape hatch today: price a deliberate free tier at 1 smallest unit (or deliver it outside the sales rails). Omit (default) for normal discounts.",
               "type": "boolean"
             },
             "time_ms_end": {
@@ -1042,7 +1091,7 @@
           "additionalProperties": false
         },
         "customer_required": {
-          "description": "Customer required information labels. Such as phone, email, shipping_address, etc. ⚠️ HARD LINKAGE (SDK-enforced): if customer_required is set (non-empty), the Service MUST also bind a Contact via `um` — otherwise the customer's private information cannot be delivered through end-to-end encrypted Messenger (which routes to the Contact bound as um). Set `um` together with customer_required.",
+          "description": "Customer required information labels. Such as phone, email, shipping_address, etc. DECLARATIVE ONLY: nothing on-chain or in the SDK reads this field — it is a pure listing declaration of what the customer will be asked to provide. It is NOT enforced against order_new and NOT linked to any delivery path by the SDK. OPERATIONAL PAIRING (convention, not enforcement): deliver the actual private information via end-to-end encrypted Messenger to the Service's Contact bound as `um` — bind `um` when you use customer_required, or the customer has no encrypted channel to send it through. To ENFORCE delivery on-chain, mount the pattern.required_info_evidence_gate Guard on the goods/funds forward (see order_new.order_required_info).",
           "type": "array",
           "items": {
             "type": "string",
@@ -1050,7 +1099,7 @@
           }
         },
         "order_allocators": {
-          "description": "Order fund allocator. Max 100 allocators (MAX_ALLOCATOR_COUNT). ✅ EACH allocator has a guard, and EVERY allocator whose guard address matches the supplied guard RUNS — they are NOT mutually exclusive and NOT first-match-wins. One guard may legitimately authorize several distribution rules (different fix / rate / cap); each contributes its own Payment and consumes its own once-slot (keyed by the allocator index). Allocators are evaluated in vector order against the SHRINKING pool, so a later allocator only sees the balance left by the earlier ones — which is exactly how a waterfall (e.g. Amount fee + net Rate split) is built. On-chain truth: wow::allocation (allocation.move:513-515, `while` loop over all allocators, `if (guard address == alloc.guard)`). ⚠️ If you WANT mutual exclusion you must express it inside the Guard itself (make the conditions logically exclusive). Set to null to clear. ⚠️ IMMUTABLE after publish except APPEND: order_allocators full replacement can ONLY be done BEFORE publish=true (on-chain check rejects after publish — E_ALREADY_PUBLISHED). After publish, the ONLY mutation is order_allocators_append (prefix-frozen extension — see that field). There is NO pause+lock exception for order_allocators (unlike arbitrations/rewards which have time-lock removal). PRE-PUBLISH CHECKLIST: verify all guard names resolve, all sharing amounts are correct, threshold is set, and recipient types (Entity/Signer/GuardIdentifier) are intended before calling publish=true. GuardIdentifier sharing mode: {who: {GuardIdentifier: <u8>}, sharing: <rate>, mode: 'Rate'} — resolves recipient from the Guard table submission at allocation time. BINDING SEMANTICS (contract-enforced, abort code 15): in a Service-created Allocation EVERY GuardIdentifier submission must equal the PAYING order — it is always 'the order', never a third party whose address is supplied at trigger time; use {who:{Entity:...}} for named parties. Canonical order pattern: the recipient slot is the single submitted Order (constrained by the Guard — service binding, qualifying node, signer==order.owner); funds land at that order object and are receivable only by its owner (object receipt = owner receipt). Safety is determined by constraint sufficiency — run the recipient constraint audit before publish. Fixed recipients should use {who:{Entity:...}}; unbound Signer recipients are a CRITICAL theft risk. MULTI-CALL ALLOCATION: an allocation can be executed MULTIPLE times (no consumed flag in contract). Use Amount mode (not Surplus) for recurring allocations — an uncapped Surplus sweeps the entire remaining balance on first run. For monthly payment scenarios, create multiple Allocators with time-based Guards + Amount mode sharing items.",
+          "description": "Order fund allocator. Max 100 allocators (MAX_ALLOCATOR_COUNT). ✅ EACH allocator has a guard, and EVERY allocator whose guard address matches the supplied guard RUNS — they are NOT mutually exclusive and NOT first-match-wins. One guard may legitimately authorize several distribution rules (different fix / rate / cap); each contributes its own Payment and consumes its own once-slot (keyed by the allocator index). Allocators are evaluated in vector order against the SHRINKING pool, so a later allocator only sees the balance left by the earlier ones — which is exactly how a waterfall (e.g. Amount fee + net Rate split) is built. On-chain truth: wow::allocation (allocation.move:507-509, `while` loop over all allocators, `if (guard address == alloc.guard)`). ⚠️ If you WANT mutual exclusion you must express it inside the Guard itself (make the conditions logically exclusive). Set to null to clear. ⚠️ IMMUTABLE after publish except APPEND: order_allocators full replacement can ONLY be done BEFORE publish=true (on-chain check rejects after publish — E_ALREADY_PUBLISHED). After publish, the ONLY mutation is order_allocators_append (prefix-frozen extension — see that field). There is NO pause+lock exception for order_allocators (unlike arbitrations/rewards which have time-lock removal). PRE-PUBLISH CHECKLIST: verify all guard names resolve, all sharing amounts are correct, threshold is set, and recipient types (Entity/Signer/GuardIdentifier) are intended before calling publish=true. GuardIdentifier sharing mode: {who: {GuardIdentifier: <u8>}, sharing: <rate>, mode: 'Rate'} — resolves recipient from the Guard table submission at allocation time. BINDING SEMANTICS (contract-enforced, abort code 15): in a Service-created Allocation EVERY GuardIdentifier submission must equal the PAYING order — it is always 'the order', never a third party whose address is supplied at trigger time; use {who:{Entity:...}} for named parties. Canonical order pattern: the recipient slot is the single submitted Order (constrained by the Guard — service binding, qualifying node, signer==order.owner); funds land at that order object and are receivable only by its owner (object receipt = owner receipt). Safety is determined by constraint sufficiency — run the recipient constraint audit before publish. Fixed recipients should use {who:{Entity:...}}; unbound Signer recipients are a CRITICAL theft risk. MULTI-CALL ALLOCATION: an allocation can be executed MULTIPLE times (no consumed flag in contract). Use Amount mode (not Surplus) for recurring allocations — an uncapped Surplus sweeps the entire remaining balance on first run. For monthly payment scenarios, create multiple Allocators with time-based Guards + Amount mode sharing items.",
           "anyOf": [
             {
               "type": "object",
@@ -1094,7 +1143,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 (protocol 154): 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 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)."
                                     }
                                   },
                                   "required": [
@@ -1154,7 +1203,7 @@
                                   "type": "string"
                                 }
                               ],
-                              "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n• mode='Formula' (protocol 154): basis-points COEFFICIENT (MUST be <= 10000) of a RUNTIME repository scalar — payout = clamp(coefficient × scalar / 10000, 0, headroom). Does NOT join any rate sum (its base is the queried scalar, not the pool) and skips the Amount>=threshold declaration check. Bind the slot's data source via allocation formula_spec_set, else the scalar reads 0.\n⚠️ T1 LOSSY POINT (B-2, updated by protocol 154): Amount/Rate/RateGross/Surplus values are PRE-CONFIGURED and STATIC — a free-form continuous amount still cannot be expressed with them. Protocol 154's Formula mode covers the bounded case: a coefficient (<= 10000 bps) of an attested repository aggregate (record count / value sum) — use it for runtime-proportional payouts; for anything richer, model (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations."
+                              "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n• mode='Formula': basis-points COEFFICIENT (MUST be <= 10000) of a RUNTIME repository scalar — payout = clamp(coefficient × scalar / 10000, 0, headroom). Does NOT join any rate sum (its base is the queried scalar, not the pool) and skips the Amount>=threshold declaration check. Bind the slot's data source via allocation formula_spec_set, else the scalar reads 0.\n⚠️ T1 LOSSY POINT (B-2): Amount/Rate/RateGross/Surplus values are PRE-CONFIGURED and STATIC — a free-form continuous amount still cannot be expressed with them. Formula mode covers the bounded case: a coefficient (<= 10000 bps) of an attested repository aggregate (record count / value sum) — use it for runtime-proportional payouts; for anything richer, model (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations."
                             },
                             "mode": {
                               "anyOf": [
@@ -1170,7 +1219,7 @@
                                 },
                                 {}
                               ],
-                              "description": "Allocation mode — determines how the `sharing` field is interpreted. Modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Formula scalar legs, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n• Formula (4, protocol 154): `sharing` is a basis-points COEFFICIENT (<= 10000, ERATE_EXCEEDS_10000=6) applied to a RUNTIME scalar queried from a Repository at alloc() time — amount = clamp(coefficient × scalar / 10000, 0, headroom). The scalar comes from the slot's bound FormulaSpec (record-count or value-sum over a repository policy key, predicate wire identical to the 1173/1174 count/sum-where guard queries; explicit candidate ids, max 100, empty list = zero hits = scalar 0). A Formula leg does NOT join total_rate (its base is the queried scalar, not the pool) and its presence SKIPS the Amount-sum >= threshold declaration check (payout is runtime-defined). Requires a spec bound via allocation formula_spec_set — an unbound Formula slot prices its scalar as 0. Gated on-chain by the enable_allocator_formula_pricing feature (EFORMULA_DISABLED=23); binding a malformed spec aborts (EFORMULA_SPEC_INVALID=24).\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Formula scalar legs → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Use Formula for payouts proportional to an attested on-chain aggregate (e.g. N records served, total value logged in a Repository) that cannot be known at configuration time. Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross'/'Formula', recommended) or number (0/1/2/3/4)."
+                              "description": "Allocation mode — determines how the `sharing` field is interpreted. Modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Formula scalar legs, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n• Formula (4): `sharing` is a basis-points COEFFICIENT (<= 10000, ERATE_EXCEEDS_10000=6) applied to a RUNTIME scalar queried from a Repository at alloc() time — amount = clamp(coefficient × scalar / 10000, 0, headroom). The scalar comes from the slot's bound FormulaSpec (record-count or value-sum over a repository policy key, predicate wire identical to the 1173/1174 count/sum-where guard queries; explicit candidate ids, max 100, empty list = zero hits = scalar 0). A Formula leg does NOT join total_rate (its base is the queried scalar, not the pool) and its presence SKIPS the Amount-sum >= threshold declaration check (payout is runtime-defined). Requires a spec bound via allocation formula_spec_set — an unbound Formula slot prices its scalar as 0. binding a malformed spec aborts (EFORMULA_SPEC_INVALID=24).\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Formula scalar legs → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Use Formula for payouts proportional to an attested on-chain aggregate (e.g. N records served, total value logged in a Repository) that cannot be known at configuration time. Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross'/'Formula', recommended) or number (0/1/2/3/4)."
                             }
                           },
                           "required": [
@@ -1280,7 +1329,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 (protocol 154): 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 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)."
                                 }
                               },
                               "required": [
@@ -1340,7 +1389,7 @@
                               "type": "string"
                             }
                           ],
-                          "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n• mode='Formula' (protocol 154): basis-points COEFFICIENT (MUST be <= 10000) of a RUNTIME repository scalar — payout = clamp(coefficient × scalar / 10000, 0, headroom). Does NOT join any rate sum (its base is the queried scalar, not the pool) and skips the Amount>=threshold declaration check. Bind the slot's data source via allocation formula_spec_set, else the scalar reads 0.\n⚠️ T1 LOSSY POINT (B-2, updated by protocol 154): Amount/Rate/RateGross/Surplus values are PRE-CONFIGURED and STATIC — a free-form continuous amount still cannot be expressed with them. Protocol 154's Formula mode covers the bounded case: a coefficient (<= 10000 bps) of an attested repository aggregate (record count / value sum) — use it for runtime-proportional payouts; for anything richer, model (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations."
+                          "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n• mode='Formula': basis-points COEFFICIENT (MUST be <= 10000) of a RUNTIME repository scalar — payout = clamp(coefficient × scalar / 10000, 0, headroom). Does NOT join any rate sum (its base is the queried scalar, not the pool) and skips the Amount>=threshold declaration check. Bind the slot's data source via allocation formula_spec_set, else the scalar reads 0.\n⚠️ T1 LOSSY POINT (B-2): Amount/Rate/RateGross/Surplus values are PRE-CONFIGURED and STATIC — a free-form continuous amount still cannot be expressed with them. Formula mode covers the bounded case: a coefficient (<= 10000 bps) of an attested repository aggregate (record count / value sum) — use it for runtime-proportional payouts; for anything richer, model (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations."
                         },
                         "mode": {
                           "anyOf": [
@@ -1356,7 +1405,7 @@
                             },
                             {}
                           ],
-                          "description": "Allocation mode — determines how the `sharing` field is interpreted. Modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Formula scalar legs, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n• Formula (4, protocol 154): `sharing` is a basis-points COEFFICIENT (<= 10000, ERATE_EXCEEDS_10000=6) applied to a RUNTIME scalar queried from a Repository at alloc() time — amount = clamp(coefficient × scalar / 10000, 0, headroom). The scalar comes from the slot's bound FormulaSpec (record-count or value-sum over a repository policy key, predicate wire identical to the 1173/1174 count/sum-where guard queries; explicit candidate ids, max 100, empty list = zero hits = scalar 0). A Formula leg does NOT join total_rate (its base is the queried scalar, not the pool) and its presence SKIPS the Amount-sum >= threshold declaration check (payout is runtime-defined). Requires a spec bound via allocation formula_spec_set — an unbound Formula slot prices its scalar as 0. Gated on-chain by the enable_allocator_formula_pricing feature (EFORMULA_DISABLED=23); binding a malformed spec aborts (EFORMULA_SPEC_INVALID=24).\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Formula scalar legs → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Use Formula for payouts proportional to an attested on-chain aggregate (e.g. N records served, total value logged in a Repository) that cannot be known at configuration time. Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross'/'Formula', recommended) or number (0/1/2/3/4)."
+                          "description": "Allocation mode — determines how the `sharing` field is interpreted. Modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Formula scalar legs, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\n• Formula (4): `sharing` is a basis-points COEFFICIENT (<= 10000, ERATE_EXCEEDS_10000=6) applied to a RUNTIME scalar queried from a Repository at alloc() time — amount = clamp(coefficient × scalar / 10000, 0, headroom). The scalar comes from the slot's bound FormulaSpec (record-count or value-sum over a repository policy key, predicate wire identical to the 1173/1174 count/sum-where guard queries; explicit candidate ids, max 100, empty list = zero hits = scalar 0). A Formula leg does NOT join total_rate (its base is the queried scalar, not the pool) and its presence SKIPS the Amount-sum >= threshold declaration check (payout is runtime-defined). Requires a spec bound via allocation formula_spec_set — an unbound Formula slot prices its scalar as 0. binding a malformed spec aborts (EFORMULA_SPEC_INVALID=24).\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Formula scalar legs → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Use Formula for payouts proportional to an attested on-chain aggregate (e.g. N records served, total value logged in a Repository) that cannot be known at configuration time. Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross'/'Formula', recommended) or number (0/1/2/3/4)."
                         }
                       },
                       "required": [
@@ -1799,6 +1848,15 @@
         },
         "creation_plan": {
           "description": "WIZARD CONTRACT: the Plan JSON that merchant_guide delivered (its creation_plan / plan field), passed back VERBATIM on the Service publish call (data.publish=true). The publish gate replays the plan's freeze matrix (preflight) right before submission and REJECTS the publish when any gate fails (structural issues, critical audit findings, or a failed rule check) — this closes the preflight bypass where a plan that failed merchant_guide's audit could still be materialized manually. OMIT this field on every NON-publish call and on fully manual (non-wizard) builds — the manual path is unchanged and never gated by this field. Do NOT edit, trim, or 'improve' the plan in transit: a mutated plan is rejected (target cross-check) and the publish must be redone from merchant_guide."
+        },
+        "reentry_kind": {
+          "description": "AP-3 loop-semantics declaration for the publish audit (ctra F-06 root cure): overrides the word-stem loop classifier when the machine graph contains a cycle. 'none' = default (word-stem classification) / 'review-loop' = same-order no-charge revisits / 'paid-cycle' = per-revisit fee, fund gate required. MCP-side audit declaration ONLY (pre_publish harness hook) — never sent on-chain; the handler strips it before the SDK call. Mirror of the template frontmatter twin (template-loader).",
+          "type": "string",
+          "enum": [
+            "none",
+            "review-loop",
+            "paid-cycle"
+          ]
         }
       },
       "required": [
@@ -1945,7 +2003,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 (protocol 154): 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 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)."
                     },
                     "b_submission": {
                       "type": "boolean",