@wowok/skills 1.1.13 → 1.2.1

package/examples/MyShop_Advanced/MyShop_Advanced.md

@@ -6,6 +6,24 @@ An advanced e-commerce example demonstrating escrow with multiple order fund all
 
 ***
 
+## ⚠️ Running Principle
+
+> **Run the example in full every time (repeatable).** This example uses `replaceExistName: true` on all object creations — each run generates new objects with new addresses. If you skip build steps, operations may silently act on orphaned objects from previous runs, producing incorrect results. Old objects' configurations do not reflect the current document version.
+
+- **Execution order**: Part 1 (read) → Part 2 Steps 1–14 (build all) → Part 3 (customer flow) → Part 4 (fund allocation). Do not skip steps — each depends on objects created by prior steps.
+- **Prerequisites**: `myshop_merchant` ≥ 0.05 WOW (gas), `myshop_customer` ≥ 0.15 WOW (gas + order payment). All on-chain operations require `env.confirmed: true`.
+
+### 🔐 Two-Step Confirmation Flow (Production Safety)
+
+This example sets `env.confirmed: true` on irreversible operations (e.g., `publish: true` on Machine) for brevity. In real deployments, follow the two-step flow enforced by the ConfirmGate safety layer:
+
+1. **Phase 1 — Preview**: Call the tool **without** `env.confirmed`. The server returns `{ status: "pending_confirmation", confirmation_text: "..." }` containing the full operation summary, risk assessment, and irreversible-action warnings.
+2. **Phase 2 — Confirm**: Review `confirmation_text` with the user. Only after explicit user approval, call the tool again **with** `env.confirmed: true` to actually execute the on-chain transaction.
+
+> Skipping Phase 1 means the user never sees the risk summary before gas is spent. Always preview first, then confirm.
+
+***
+
 ## Core Requirements & Features
 
 | Requirement                    | Description                                                               | Implementation                                                                        |
@@ -23,7 +41,7 @@ An advanced e-commerce example demonstrating escrow with multiple order fund all
 2. **Privacy-Preserving Logistics**: Merchant handles logistics independently using any logistics provider. Tracking numbers are shared privately via Messenger (not on-chain), with only Merkle Root submitted on-chain as proof of communication
 3. **Reward Incentive Model**: Additional reward pool for excellent service (Wonderful reward) and compensation for lost packages
 4. **Multi-Path Workflow**: Order can complete through normal delivery, wonderful rating, or various return paths
-5. **Dual-Signature Returns**: Return processes require both customer and merchant confirmation (threshold=2)
+5. **Dual-Signature Returns**: Receipt return processes require both customer and merchant confirmation (threshold=2). Non-receipt returns (customer never received goods) require only merchant confirmation of goods recovery (threshold=1), since the customer has nothing to return and their non-receipt was already confirmed when entering the Non-receipt Return node.
 
 ### Important Design Principle: "Who Completes the Key Action, Who Submits the Proof"
 
@@ -43,7 +61,7 @@ This advanced example demonstrates an enterprise-grade e-commerce system with:
 
 - **Single WIP-Verified Product**: One product listing ("The Three-Body Problem + Author Signature") with WIP file verification
 - **Multi-Path Workflow**: Order progress with delivery confirmation, wonderful rating, lost handling, and multiple return paths
-- **Dual-Signature Returns**: Return processes require confirmation from both customer and merchant
+- **Dual-Signature Returns**: Receipt returns require both customer and merchant confirmation; non-receipt returns require only merchant confirmation of goods recovery
 - **Reward Incentive System**: Reward pool for excellent service and compensation for lost packages
 - **Time-Based Auto-Completion**: Orders auto-complete after time thresholds
 
@@ -101,7 +119,7 @@ graph TD
 
     RR["Receipt Return (Dual-Sig)<br/>Threshold = 2"]:::dualsig
     RF["Return Fail (Merchant)<br/>Time >= 10 days"]:::merchant
-    RC["Return Complete (Dual-Sig)<br/>Threshold = 2"]:::dualsig
+    RC["Return Complete<br/>From Receipt: Dual-Sig (threshold=2)<br/>From Non-receipt: Merchant only (threshold=1)"]:::dualsig
 
     START --> OC
     START --> OR
@@ -167,6 +185,13 @@ Understanding the correct order for creating WoWok objects is crucial for a succ
 │  └────────┬────────┘                                                        │
 │           │                                                                 │
 │           ▼                                                                 │
+│  ┌─────────────────┐                                                       │
+│  │    Treasury     │◄─── Requires: Permission (same as Service)            │
+│  │(myshop_treasury │     Aggregates merchant revenue                       │
+│  │      _v2)       │     Referenced by order_allocators (Phase 6)          │
+│  └────────┬────────┘                                                        │
+│           │                                                                 │
+│           ▼                                                                 │
 │  Phase 2: Guard Creation                                                    │
 │  ═══════════════════════                                                    │
 │                                                                             │
@@ -251,6 +276,7 @@ Understanding the correct order for creating WoWok objects is crucial for a succ
 | 1     | **Permission**       | None                 | Permission is the foundation. Machine and Service both reference a permission object for access control.      |
 | 1b    | **Permission Indexes** | Permission         | Grant permission indexes 1000 and 1001 to merchant. Required for Machine node operations.                     |
 | 2     | **Service (Empty)**  | Permission           | Create Service without publishing first to obtain its name. This name is used in Guard verification.          |
+| 2b    | **Treasury**         | Permission           | Treasury aggregates merchant revenue. Uses same Permission as Service. Referenced by order\_allocators in Phase 7. |
 | 3     | **Guards**           | Service Name         | Guards must verify that orders belong to the correct Service. They query Service name and Progress state.     |
 | 4     | **Machine**          | Permission, Guards   | Machine requires guards for node verification. Guards need Service name which is now available.               |
 | 5     | **Machine Binding**  | Service, Machine     | Bind Machine to Service before publishing. Once published, Machine cannot be bound.                           |
@@ -266,6 +292,7 @@ Understanding the correct order for creating WoWok objects is crucial for a succ
 1. **Permission First**: Every major object (Machine, Service) requires a permission object. Create this first.
 2. **Permission Indexes**: Grant permission indexes 1000 and 1001 to merchant account. These are used in Machine node forwards.
 3. **Service Before Guards**: Create Service without publishing to get its name. Guards use Service name to verify orders belong to the correct service.
+3b. **Treasury for Fund Aggregation**: Create Treasury with the same Permission as the Service. Merchant revenue flows to the Treasury (not the Service address), making allocators inherently safe (R-C3-06) and aggregating public funds for operational distribution.
 4. **Guards Before Machine**: Machine nodes reference guards for verification. Create all guards first, then create Machine with guard references.
 5. **Machine Binding Before Publish**: Bind Machine to Service before publishing. Once published, Machine cannot be bound.
 6. **Arbitration Before Service Update**: Arbitration must be created before Service update so it can be bound to Service.
@@ -285,6 +312,12 @@ Phase 2: Service Creation
     ├── Publish: FALSE
     └── Record the Service address for Guard creation
 
+Phase 2b: Treasury Creation
+└── 2b. Create Treasury (myshop_treasury_v2)
+    ├── Permission: myshop_perm_v2 (same as Service)
+    ├── Type parameter: 0x2::wow::WOW
+    └── Aggregates merchant revenue; referenced by order_allocators (Phase 7)
+
 Phase 3: Guard Creation (Machine Guards)
 └── 3. Create Machine Guards (4 guards)
     ├── machine_merkle_root_v2 (verify string length = 66)
@@ -474,6 +507,39 @@ Create the Service without publishing to obtain its address for Guard creation.
 
 ***
 
+### Step 3b: Create Treasury (Merchant Revenue Aggregation)
+
+Create a Treasury object to aggregate merchant revenue. The Treasury uses the **same Permission** as the Service (`myshop_perm_v2`) for consistency — a single permission organization governs both fund collection and service operations.
+
+**Prompt**: Create Treasury "myshop\_treasury\_v2" with permission "myshop\_perm\_v2", type parameter "0x2::wow::WOW".
+
+```json
+{
+  "operation_type": "treasury",
+  "data": {
+    "object": {
+      "name": "myshop_treasury_v2",
+      "type_parameter": "0x2::wow::WOW",
+      "permission": "myshop_perm_v2",
+      "replaceExistName": true
+    },
+    "description": "Treasury for aggregating MyShop merchant revenue. Uses the same Permission as the Service (myshop_perm_v2) for consistency — a single permission organization governs both fund collection and service operations."
+  },
+  "env": {
+    "account": "myshop_merchant",
+    "network": "mainnet",
+    "no_cache": true
+  }
+}
+```
+
+> **Treasury-First Rule**: Following the fund-flow design pattern established in the Insurance example, merchant revenue flows to `myshop_treasury_v2` (not directly to the Service address). This:
+> 1. **Aggregates public funds** for operational distribution and accounting
+> 2. **Makes allocators inherently safe** (R-C3-06) — funds always flow to the fixed Treasury regardless of caller, so no Signer binding is needed in the Guard
+> 3. **Uses permission consistency** — Treasury and Service share `myshop_perm_v2`, ensuring unified governance
+
+***
+
 ### Step 4: Create Guards (Machine Guards)
 
 Create Guards using the Service address. Guards verify order state and service ownership.
@@ -522,6 +588,85 @@ Create Guards using the Service address. Guards verify order state and service o
 }
 ```
 
+**Guard 1b: machine_messenger_proof_v2** - Strict-mode privacy delivery (alternative to Guard 1)
+
+> **Two standard modes for "privacy info delivered via Messenger but not suitable for on-chain publication":**
+>
+> | Mode | Guard | Submission | Verification | Trust model |
+> |------|-------|-----------|-------------|-------------|
+> | **Broad** | `machine_merkle_root_v2` (Guard 1) | String (Merkle Root) | Length == 66 | Trusts submitter honesty; counterparty disputes via own Messenger log. Arbitration basis. |
+> | **Strict** | `machine_messenger_proof_v2` (Guard 1b) | Proof addr + Order addr | Signer==proof.signer ∧ proof.time>order.time ∧ order.service==service | Submitter accountability (谁得利谁举证); no content verification. |
+>
+> Machine forwards may reference **either** Guard 1 or Guard 1b — choose before publishing (Forward.guard is immutable). The same strict Guard can be reused across all forwards that need Merkle-Root verification (shipping, lost, returns, etc.).
+
+```json
+{
+  "operation_type": "guard",
+  "data": {
+    "namedNew": {
+      "name": "machine_messenger_proof_v2",
+      "replaceExistName": true
+    },
+    "description": "Strict-mode privacy delivery: verify Signer==proof.signer AND proof.time>order.time AND order.service==service (verifier submits Proof+Order object addresses)",
+    "table": [
+      {"identifier": 0, "b_submission": true, "value_type": "Address", "name": "Proof object from submitChainProof"},
+      {"identifier": 1, "b_submission": true, "value_type": "Address", "name": "Order object submitted by verifier"},
+      {"identifier": 2, "b_submission": false, "value_type": "Address", "name": "service_address", "value": "three_body_signature_service_v2"}
+    ],
+    "root": {
+      "type": "logic_and",
+      "nodes": [
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "context", "context": "Signer"},
+            {"type": "query", "query": "proof.signer", "object": {"identifier": 0}, "parameters": []}
+          ]
+        },
+        {
+          "type": "logic_as_u256_greater",
+          "nodes": [
+            {"type": "query", "query": "proof.time", "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.time", "object": {"identifier": 1}, "parameters": []}
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "query", "query": "order.service", "object": {"identifier": 1}, "parameters": []},
+            {"type": "identifier", "identifier": 2}
+          ]
+        }
+      ]
+    }
+  },
+  "env": {
+    "account": "myshop_merchant",
+    "network": "mainnet",
+    "no_cache": true
+  }
+}
+```
+
+**Three conditions (logic_and):**
+1. **Submitter accountability** — `logic_equal[context(Signer), query("proof.signer", obj=proof)]`: the transaction signer must be the Proof's signer (the party who generated the Proof via `submitChainProof`). Suppresses R-C3-01.
+2. **Freshness** — `logic_as_u256_greater[query("proof.time", obj=proof), query("order.time", obj=order)]`: the Proof was created after the order, preventing stale-proof replay. (`proof.time` has invariant `clock_derived`, always > 0.)
+3. **Project binding** — `logic_equal[query("order.service", obj=order), identifier[2]]`: the submitted Order belongs to `three_body_signature_service_v2`. Suppresses R-C3-05 (cross-project bypass).
+
+**Generating the Proof (provider side, before submitting to the forward):**
+```json
+// SDK call: messenger.submitChainProof(env, peerAddress, description?)
+// - about_address is set to peerAddress (the customer's address)
+// - pass the order_id in description to associate the Proof with the order
+// Returns: { proofAddress, txHash }
+```
+
+**Runtime submission (verifier side, advancing the Machine forward):**
+- Broad mode (Guard 1): submit one String identifier — the Merkle Root.
+- Strict mode (Guard 1b): submit two Address identifiers — the Proof object address (identifier 0) and the Order object address (identifier 1).
+
+> No content verification is performed in either mode — only submission responsibility. The counterparty can dispute a fraudulent claim by checking their own Messenger conversation for the alleged dialogue. This follows the 谁得利谁举证 (whoever benefits bears the burden of proof) principle.
+
 **Guard 2: machine_time_10d_v2** - Verify 10-day timeout (864000000 ms)
 
 ```json
@@ -606,9 +751,10 @@ Create Guards using the Service address. Guards verify order state and service o
   "data": {
     "namedNew": {
       "name": "service_merchant_win_v2",
+      "tags": ["order", "merchant-win", "level3-scene-combined"],
       "replaceExistName": true
     },
-    "description": "Verify order at merchant win nodes (Order Complete, Wonderful, Return Fail) AND order belongs to three_body_signature_service_v2",
+    "description": "Verify order at merchant win nodes (Order Complete, Wonderful, Return Fail) AND order belongs to three_body_signature_service_v2. VERIFIER CONSTRAINT LEVEL 3 (scene-combined): No Signer binding needed because the allocator uses sharing.who=Entity (myshop_treasury_v2) — funds always flow to the Treasury regardless of caller (R-C3-06 safe). Two-fold verification: (1) order at merchant win node, (2) order belongs to this service (prevents cross-service theft, R-C3-05).",
     "table": [
       {"identifier": 0, "b_submission": true, "value_type": "Address", "name": "order_id"},
       {"identifier": 1, "b_submission": false, "value_type": "String", "value": "Order Complete"},
@@ -625,21 +771,21 @@ Create Guards using the Service address. Guards verify order state and service o
             {
               "type": "logic_string_nocase_equal",
               "nodes": [
-                {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+                {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
                 {"type": "identifier", "identifier": 1}
               ]
             },
             {
               "type": "logic_string_nocase_equal",
               "nodes": [
-                {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+                {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
                 {"type": "identifier", "identifier": 2}
               ]
             },
             {
               "type": "logic_string_nocase_equal",
               "nodes": [
-                {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+                {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
                 {"type": "identifier", "identifier": 3}
               ]
             }
@@ -648,7 +794,7 @@ Create Guards using the Service address. Guards verify order state and service o
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1563, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
             {"type": "identifier", "identifier": 4}
           ]
         }
@@ -663,11 +809,85 @@ Create Guards using the Service address. Guards verify order state and service o
 }
 ```
 
-**Guard Logic:**
-1. 验证订单当前节点是 Order Complete、Wonderful 或 Return Fail（商家胜利节点）
-2. 验证订单的 Service 地址等于当前 Guard 所属的 Service 地址（使用 `order.service` 查询指令 ID 1563）
+**Guard Explanation (Two-fold Verification — Level 3 Scene-Combined):**
+- **Table Item 0**: Order address (submitted at runtime)
+- **Table Items 1-3**: Constant strings "Order Complete", "Wonderful", "Return Fail" (merchant win node names)
+- **Table Item 4**: Constant address `three_body_signature_service_v2` (this service's on-chain address)
+- **Condition 1 — Merchant Win Node**: `logic_or` of three `logic_string_nocase_equal` checks against `query("progress.current", witness="OrderProgress")` — verifies the order is at one of the merchant win nodes
+- **Condition 2 — Service Ownership**: `logic_equal[query("order.service"), identifier[4]]` — verifies the submitted Order's `service` field equals `three_body_signature_service_v2`, **preventing cross-service theft** where someone submits another service's order (R-C3-05)
+- **root**: `logic_and` of both conditions — all must pass for allocation to proceed
+
+> **Risk Elimination (R-C3-06) — Level 3 Scene-Combined Design**: The allocator uses `"who": {"Entity": {"name_or_address": "myshop_treasury_v2"}}` (funds flow to the fixed Treasury address). This is inherently safe because funds go to a fixed recipient regardless of caller — **no Signer binding is needed**. The scene itself (Entity sharing to Treasury) ensures fund-flow safety, which is the Level 3 scene-combined pattern. Removing the Signer binding also eliminates R-C4-04 (Level 1 strict binding convenience warning) and avoids the lock-in risk of binding to a fixed merchant address.
 ```
 
+**Guard 4 — Alternative Shorthand Form (VecString + vec_contains_string_nocase)**
+
+The `logic_or` of three `logic_string_nocase_equal` checks above can be collapsed into a single `vec_contains_string_nocase` over a `VecString` constant. Both forms are **semantically equivalent** (verified by `guard-examples-lint.spec.ts` → "Semantic Equivalence" tests: identical risk diagnostics, identical `root_type`, identical `errors`/`ready` state). The shorthand is preferred when the candidate set has ≥ 2 entries — it scales linearly with the vector length instead of duplicating the query node N times.
+
+```json
+{
+  "operation_type": "guard",
+  "data": {
+    "namedNew": {
+      "name": "service_merchant_win_v2",
+      "tags": ["order", "merchant-win", "level3-scene-combined"],
+      "replaceExistName": true
+    },
+    "description": "Verify order at merchant win nodes (Order Complete, Wonderful, Return Fail) AND order belongs to three_body_signature_service_v2. SHORTHAND: collapses three String constants + logic_or[logic_string_nocase_equal x 3] into a single VecString + vec_contains_string_nocase. Semantically equivalent to the original form (see guard-examples-lint 'Semantic Equivalence' tests).",
+    "table": [
+      {"identifier": 0, "b_submission": true, "value_type": "Address", "name": "order_id"},
+      {"identifier": 1, "b_submission": false, "value_type": "VecString", "value": ["Order Complete", "Wonderful", "Return Fail"], "name": "merchant_win_nodes"},
+      {"identifier": 2, "b_submission": false, "value_type": "Address", "name": "service_address", "value": "three_body_signature_service_v2"}
+    ],
+    "root": {
+      "type": "logic_and",
+      "nodes": [
+        {
+          "type": "vec_contains_string_nocase",
+          "nodes": [
+            {"type": "identifier", "identifier": 1},
+            {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []}
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
+            {"type": "identifier", "identifier": 2}
+          ]
+        }
+      ]
+    }
+  },
+  "env": {
+    "account": "myshop_merchant",
+    "network": "mainnet",
+    "no_cache": true
+  }
+}
+```
+
+**Shorthand Equivalence Explanation:**
+
+| Aspect | Original Form | Shorthand Form |
+|---|---|---|
+| `table` count | 5 entries (1 Address + 3 String + 1 Address) | 3 entries (1 Address + 1 VecString + 1 Address) |
+| Condition 1 node | `logic_or` of 3 × `logic_string_nocase_equal` | `vec_contains_string_nocase` (single node) |
+| Condition 2 node | `logic_equal` (unchanged) | `logic_equal` (unchanged) |
+| `root` type | `logic_and` | `logic_and` (identical) |
+| Risk diagnostics (R-C3-*) | identical | identical (security-equivalent) |
+| Lint diagnostics (LE-04, SG-01, SG-03) | identical | identical |
+| SH-03 warnings (missing `name`) | 3 (the 3 unnamed String constants) | 0 (the VecString is named `merchant_win_nodes`) |
+| Total warnings | 5 | 2 (3 fewer — the eliminated SH-03s) |
+
+**Why the shorthand is preferred:**
+- **Fewer table entries**: 3 vs 5 (40% reduction). Adding a new merchant-win node is a one-line edit to the `value` array instead of a new identifier + new `logic_string_nocase_equal` branch.
+- **No SH-03 nits**: The single `VecString` entry is naturally named (`merchant_win_nodes`), eliminating the 3 missing-name warnings.
+- **Linear scaling**: For N candidate nodes, the original grows as O(N) identifiers + O(N) `logic_string_nocase_equal` branches under one `logic_or` (capped at 8 children). The shorthand stays at 1 identifier + 1 `vec_contains_string_nocase` node regardless of N.
+- **Same security posture**: Risk-layer diagnostics are byte-identical (R-C3-05, R-C3-06, etc. all evaluate the same), so the Level 3 scene-combined design and R-C3-06 suppression are preserved.
+
+**Equivalence verification**: See `d:\wowok\agent\mcp\src\knowledge\__tests__\guard-examples-lint.spec.ts` → describe block `"Semantic Equivalence — Shorthand vs Original (VecString + vec_contains_string_nocase)"`. The 8-test suite verifies: identical `root_type`, identical `errors`/`ready`, identical risk diagnostic codes, identical lint diagnostic codes (excluding SH-03), fewer SH-03 warnings, reduced `table_count`, no SDK syntax errors, and complete `risk_assessment`.
+
 **Guard 5: machine_service_order_v2** - Verify order belongs to this Service
 
 ```json
@@ -688,7 +908,7 @@ Create Guards using the Service address. Guards verify order state and service o
       "nodes": [
         {
           "type": "query",
-          "query": 1563,
+          "query": "order.service",
           "object": {"identifier": 0},
           "parameters": []
         },
@@ -717,9 +937,10 @@ Create Guards using the Service address. Guards verify order state and service o
   "data": {
     "namedNew": {
       "name": "service_customer_win_v2",
+      "tags": ["order", "customer-win", "level2-dynamic-binding"],
       "replaceExistName": true
     },
-    "description": "Verify order at customer win nodes (Lost, Return Complete) AND order belongs to three_body_signature_service_v2",
+    "description": "Verify order at customer win nodes (Lost, Return Complete) AND order belongs to three_body_signature_service_v2. VERIFIER CONSTRAINT LEVEL 2 (dynamic identity binding): Signer bound to query('order.owner') — only the order's rightful owner can trigger the refund. RISK ELIMINATION: Three-fold verification - (1) order at customer win node, (2) signer is order.owner (dynamic query, prevents fund theft - only order owner can trigger their own refund), (3) order belongs to three_body_signature_service_v2 (prevents cross-service theft).",
     "table": [
       {"identifier": 0, "b_submission": true, "value_type": "Address", "name": "order_id"},
       {"identifier": 1, "b_submission": false, "value_type": "String", "value": "Lost"},
@@ -735,14 +956,14 @@ Create Guards using the Service address. Guards verify order state and service o
             {
               "type": "logic_string_nocase_equal",
               "nodes": [
-                {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+                {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
                 {"type": "identifier", "identifier": 1}
               ]
             },
             {
               "type": "logic_string_nocase_equal",
               "nodes": [
-                {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+                {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
                 {"type": "identifier", "identifier": 2}
               ]
             }
@@ -751,7 +972,14 @@ Create Guards using the Service address. Guards verify order state and service o
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1563, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.owner", "object": {"identifier": 0}, "parameters": []},
+            {"type": "context", "context": "Signer"}
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
             {"type": "identifier", "identifier": 3}
           ]
         }
@@ -766,11 +994,90 @@ Create Guards using the Service address. Guards verify order state and service o
 }
 ```
 
-**Guard Logic:**
-1. 验证订单当前节点是 Lost 或 Return Complete（客户胜利节点）
-2. 验证订单的 Service 地址等于当前 Guard 所属的 Service 地址（使用 `order.service` 查询指令 ID 1563）
+**Guard Explanation (Three-fold Verification — Level 2 Dynamic Binding):**
+- **Table Item 0**: Order address (submitted at runtime)
+- **Table Items 1-2**: Constant strings "Lost", "Return Complete" (customer win node names)
+- **Table Item 3**: Constant address `three_body_signature_service_v2` (this service's on-chain address)
+- **Condition 1 — Customer Win Node**: `logic_or` of two `logic_string_nocase_equal` checks against `query("progress.current", witness="OrderProgress")` — verifies the order is at one of the customer win nodes
+- **Condition 2 — Signer is Order Owner (Level 2 Dynamic)**: `logic_equal[query("order.owner"), context(Signer)]` — verifies the transaction caller is the order's owner (dynamic query, not a fixed address). This is the **Level 2 dynamic identity binding** pattern: the Signer is bound to a query result (not a fixed address), so it survives personnel changes and avoids the R-C4-04 lock-in risk. **Prevents fund theft by unauthorized callers** (R-C3-01/R-C3-06). Only the customer who placed the order can trigger the refund.
+- **Condition 3 — Service Ownership**: `logic_equal[query("order.service"), identifier[3]]` — verifies the submitted Order's `service` field equals `three_body_signature_service_v2`, **preventing cross-service theft** where someone submits another service's order (R-C3-05)
+- **root**: `logic_and` of all three conditions — all must pass for allocation to proceed
+
+> **Risk Elimination (R-C3-06) — CRITICAL — Level 2 Dynamic Binding**: The allocator uses `"who": {"Signer": "signer"}` (funds go to the caller). This is safe ONLY because Condition 2 binds the Signer to `query("order.owner")` (dynamic query — Level 2). Without this binding, anyone could submit any Lost/Return Complete order and steal 100% of funds. The dynamic query pattern ensures funds always flow to the order's rightful owner, regardless of who calls the transaction. Unlike Level 1 (fixed address), Level 2 dynamic binding does NOT trigger R-C4-04 because the bound identity is a query result, not an immutable address constant.
 ```
 
+**Guard 6 — Alternative Shorthand Form (VecString + vec_contains_string_nocase)**
+
+The `logic_or` of two `logic_string_nocase_equal` checks above can be collapsed into a single `vec_contains_string_nocase` over a `VecString` constant. Both forms are **semantically equivalent** (verified by `guard-examples-lint.spec.ts` → "Semantic Equivalence — Guard 6 Shorthand" tests: identical risk diagnostics, identical `root_type`, identical `errors`/`ready` state).
+
+```json
+{
+  "operation_type": "guard",
+  "data": {
+    "namedNew": {
+      "name": "service_customer_win_v2",
+      "tags": ["order", "customer-win", "level2-dynamic-binding"],
+      "replaceExistName": true
+    },
+    "description": "Verify order at customer win nodes (Lost, Return Complete) AND order belongs to three_body_signature_service_v2. SHORTHAND: collapses two String constants + logic_or[logic_string_nocase_equal x 2] into a single VecString + vec_contains_string_nocase. Semantically equivalent to the original form (see guard-examples-lint 'Semantic Equivalence — Guard 6 Shorthand' tests).",
+    "table": [
+      {"identifier": 0, "b_submission": true, "value_type": "Address", "name": "order_id"},
+      {"identifier": 1, "b_submission": false, "value_type": "VecString", "value": ["Lost", "Return Complete"], "name": "customer_win_nodes"},
+      {"identifier": 2, "b_submission": false, "value_type": "Address", "name": "service_address", "value": "three_body_signature_service_v2"}
+    ],
+    "root": {
+      "type": "logic_and",
+      "nodes": [
+        {
+          "type": "vec_contains_string_nocase",
+          "nodes": [
+            {"type": "identifier", "identifier": 1},
+            {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []}
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "query", "query": "order.owner", "object": {"identifier": 0}, "parameters": []},
+            {"type": "context", "context": "Signer"}
+          ]
+        },
+        {
+          "type": "logic_equal",
+          "nodes": [
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
+            {"type": "identifier", "identifier": 2}
+          ]
+        }
+      ]
+    }
+  },
+  "env": {
+    "account": "myshop_merchant",
+    "network": "mainnet",
+    "no_cache": true
+  }
+}
+```
+
+**Shorthand Equivalence Explanation:**
+
+| Aspect | Original Form | Shorthand Form |
+|---|---|---|
+| `table` count | 4 entries (1 Address + 2 String + 1 Address) | 3 entries (1 Address + 1 VecString + 1 Address) |
+| Condition 1 node | `logic_or` of 2 × `logic_string_nocase_equal` | `vec_contains_string_nocase` (single node) |
+| Condition 2 node (Signer binding) | `logic_equal` (unchanged) | `logic_equal` (unchanged) |
+| Condition 3 node (Service ownership) | `logic_equal` (unchanged) | `logic_equal` (unchanged) |
+| `root` type | `logic_and` | `logic_and` (identical) |
+| Risk diagnostics (R-C3-*) | identical | identical (security-equivalent) |
+| Lint diagnostics (LE-04, SG-01, SG-03) | identical | identical |
+| SH-03 warnings (missing `name`) | 2 (the 2 unnamed String constants) | 0 (the VecString is named `customer_win_nodes`) |
+| Total warnings | 4 | 2 (2 fewer — the eliminated SH-03s) |
+
+**Case-sensitivity note (critical)**: The source uses `logic_string_nocase_equal` (case-insensitive), so the target is `vec_contains_string_nocase` (case-insensitive). If the source had used `logic_equal` on String (case-sensitive — "Lost" ≠ "lost"), the target would have to be `vec_contains_string` (case-sensitive) to preserve semantics. **Mixing case-sensitive and case-insensitive operators in the same `logic_or` is NOT convertible** — the original `logic_or` must be kept because there is no single `vec_contains_*` variant that captures both behaviors. This is a fundamental limitation of the contains shorthand: it is syntactic sugar, not a universal replacement.
+
+**Equivalence verification**: See `d:\wowok\agent\mcp\src\knowledge\__tests__\guard-examples-lint.spec.ts` → describe block `"Semantic Equivalence — Guard 6 Shorthand (service_customer_win_v2: VecString + vec_contains_string_nocase)"`. The 8-test suite verifies: identical `root_type`, identical `errors`/`ready`, identical risk diagnostic codes, identical lint diagnostic codes (excluding SH-03), fewer SH-03 warnings, reduced `table_count`, no SDK syntax errors, and complete `risk_assessment`.
+
 ***
 
 ### Step 5: Create Machine (Multi-Path Workflow)
@@ -1007,25 +1314,19 @@ Create Machine with all nodes and guards in a single operation.
                 },
                 {
                   "name": "Confirm Return Received",
-                  "weight": 1,
-                  "namedOperator": ""
+                  "permissionIndex": 1001,
+                  "weight": 1
                 }
               ]
             },
             {
               "prev_node": "Non-receipt Return",
-              "threshold": 2,
+              "threshold": 1,
               "forwards": [
                 {
-                  "name": "Submit Return Merkle Root",
-                  "weight": 1,
-                  "namedOperator": "",
-                  "guard": { "guard": "machine_merkle_root_v2" }
-                },
-                {
-                  "name": "Confirm Return Received",
-                  "weight": 1,
-                  "namedOperator": ""
+                  "name": "Confirm Goods Recovered",
+                  "permissionIndex": 1001,
+                  "weight": 1
                 }
               ]
             }
@@ -1199,14 +1500,14 @@ Configure order_allocators to define fund distribution rules, then publish the S
       ]
     },
     "order_allocators": {
-      "description": "Order fund allocation - 100% to Service when order complete/wonderful/return fail, 100% to Order when lost/return complete",
+      "description": "Order fund allocation - 100% to Treasury when order complete/wonderful/return fail, 100% to Order owner when lost/return complete",
       "threshold": 1,
       "allocators": [
         {
           "guard": "service_merchant_win_v2",
           "sharing": [
             {
-              "who": {"Entity": {"name_or_address": "three_body_signature_service_v2"}},
+              "who": {"Entity": {"name_or_address": "myshop_treasury_v2"}},
               "sharing": 10000,
               "mode": "Rate"
             }
@@ -1244,16 +1545,51 @@ Configure order_allocators to define fund distribution rules, then publish the S
 
 **Fund Allocation Rules:**
 
-| Guard | Condition | Recipient | Amount |
-|-------|-----------|-----------|--------|
-| service_merchant_win_v2 | Node is Order Complete / Wonderful / Return Fail | Service (merchant) | 100% |
-| service_customer_win_v2 | Node is Lost / Return Complete | Order (customer) | 100% |
+| Guard | Condition | Recipient | Amount | Verifier Level |
+|-------|-----------|-----------|--------|----------------|
+| service_merchant_win_v2 | Node is Order Complete / Wonderful / Return Fail | Treasury (merchant revenue aggregation) | 100% | Level 3 (no Signer binding) |
+| service_customer_win_v2 | Node is Lost / Return Complete | Order owner (customer, via Signer) | 100% | Level 2 dynamic (Signer == order.owner) |
 
 **Recipient Types:**
-- **Service**: 资金分配给 Service 对象（商家收款）
-- **Order**: 资金分配给 Order 对象（客户收款，订单所有者可以提取）
+- `{ "Entity": { "name_or_address": "myshop_treasury_v2" } }` - Funds flow to the fixed Treasury address (merchant revenue aggregation). Safest — funds go to a fixed recipient regardless of caller. Uses the same Permission as the Service for governance consistency. **No Signer binding needed in the Guard** (R-C3-06 safe, Level 3 scene-combined).
+- `{ "Signer": "signer" }` - Transaction sender (caller). **⚠️ R-C3-06 Risk**: If the Guard does NOT bind the Signer to an authorized address, anyone who passes the Guard can steal 100% of funds. Safe ONLY when the Guard includes a `logic_equal[context(Signer), <authorized_address_or_query>]` check. This example uses Level 2 dynamic binding (`query("order.owner")`) — funds flow to the order's rightful owner.
+
+> **R-C3-06 Risk Elimination — Guard + Sharing Coupling**: The `order_allocators` scene couples Guard verification (WHO can trigger) with sharing recipient (WHERE funds go). This example uses two verifier constraint levels:
+> - **Merchant win allocator** (`sharing.who = Entity → myshop_treasury_v2`, **Level 3 scene-combined**): Funds flow to the fixed Treasury address. Inherently safe — funds go to a fixed recipient regardless of caller. The `service_merchant_win_v2` Guard does NOT bind `context(Signer)` — the scene itself (Entity sharing to Treasury) ensures fund-flow safety. This is the recommended Level 3 pattern: no Signer binding, no R-C4-04 lock-in risk, no inconvenience.
+> - **Customer win allocator** (`sharing.who = Signer`, **Level 2 dynamic binding**): Funds flow to the caller. Safe ONLY because `service_customer_win_v2` Guard binds `context(Signer)` to `query("order.owner")` (dynamic query — Level 2). This ensures funds always flow to the order's rightful owner — only the customer who placed the order can receive the refund.
+>
+> **Treasury-First Rule**: Following the fund-flow design pattern established in the Insurance example, merchant revenue flows to `myshop_treasury_v2` (not the Service address). This aggregates public funds for operational distribution and makes the allocator inherently safe (R-C3-06). The Treasury uses the same Permission as the Service (`myshop_perm_v2`) for governance consistency.
 ```
 
+### Verifier Constraint Design Notes
+
+This example demonstrates all three verifier constraint levels across its Guards. The verifier constraint level classifies how strictly the Signer identity is constrained, trading off security against convenience.
+
+| Guard | Level | Pattern | Why |
+|-------|-------|---------|-----|
+| Guard 1-3 (machine_merkle_root_v2, machine_service_order_v2, machine_time_*) | Level 3 | No Signer binding | Machine forward's `permissionIndex` already verifies operator identity — Signer binding is redundant |
+| Guard 4 (service_merchant_win_v2) | Level 3 | No Signer binding | Allocator uses `sharing.who=Entity` (myshop_treasury_v2) — funds flow to fixed Treasury regardless of caller (R-C3-06 safe). Two-fold verification: node + order.service binding |
+| Guard 5 (machine_service_order_v2) | Level 3 | No Signer binding | Project-binding only (order.service check); machine forward verifies operator |
+| Guard 6 (service_customer_win_v2) | Level 2 dynamic | Signer == query("order.owner") | Allocator uses `sharing.who=Signer` — funds flow to caller, must bind to order owner to prevent theft |
+| Reward guards (reward_wonderful_v2, reward_lost_v2, reward_shipping_timeout_v2) | Level 3 | No Signer binding | One-time claim via record count; funds flow to fixed reward pool recipient |
+
+**Key design decisions**:
+
+1. **Merchant funds → Treasury (not Service)**: Following the Treasury-first rule, merchant revenue flows to `myshop_treasury_v2` (created with the same Permission as the Service). This aggregates public funds for operations and distribution, and makes the allocator inherently safe (R-C3-06) — no Signer binding needed (Level 3).
+
+2. **Customer refunds → order.owner (dynamic)**: Customer refunds must go to the actual customer who placed the order. The Level 2 dynamic binding (`query("order.owner")`) ensures only the rightful owner receives the refund, regardless of who calls the transaction. Unlike Level 1 (fixed address), this survives customer account changes.
+
+3. **No Level 1 strict binding anywhere**: No Guard uses `logic_equal[context(Signer), fixed_address]` because:
+   - The merchant role may change (personnel rotation) — Level 1 would lock the Guard to one address permanently
+   - The Treasury pattern makes Signer binding unnecessary for the merchant allocator (Level 3)
+   - The dynamic `order.owner` query is more appropriate for customer refunds (Level 2 dynamic)
+   - Level 1 would trigger R-C4-04 (convenience warning) and create operational risk
+
+**Alternative designs considered**:
+- **Guard 4 could use Level 2 identity-set** (merchant OR admin via permission.owner OR has admin) — **rejected** because Treasury (Entity sharing) already makes Signer binding redundant. Adding Level 2 would add complexity without safety benefit.
+- **Guard 6 could use Level 2 identity-set** (order.owner OR order.agent via 1562 OR 1567) — **viable** if agents should be able to trigger refunds on behalf of customers. The current single-customer design (Level 2 dynamic, `order.owner` only) is simpler and sufficient for this example. See `tpl_allocator_identity_set_order_holder` template for the identity-set construction pattern.
+- **Guard 4 could use Level 2 dynamic permission** (permission.owner OR has admin, with dynamic permission via 1488) — **viable** for scenarios where the Service may rotate its permission. See `tpl_allocator_identity_set_service_provider_dynamic` template for this pattern. Rejected here because the Treasury pattern already provides fund-flow safety without Signer binding.
+
 ***
 
 ### Step 11: Create Empty Reward Object (Optional)
@@ -1314,21 +1650,21 @@ Create guards for reward verification with double-claim protection:
         {
           "type": "logic_string_nocase_equal",
           "nodes": [
-            {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+            {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
             {"type": "identifier", "identifier": 1}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1562, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.owner", "object": {"identifier": 0}, "parameters": []},
             {"type": "context", "context": "Signer"}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1563, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
             {"type": "identifier", "identifier": 3}
           ]
         },
@@ -1376,21 +1712,21 @@ Create guards for reward verification with double-claim protection:
         {
           "type": "logic_string_nocase_equal",
           "nodes": [
-            {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+            {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
             {"type": "identifier", "identifier": 1}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1562, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.owner", "object": {"identifier": 0}, "parameters": []},
             {"type": "context", "context": "Signer"}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1563, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
             {"type": "identifier", "identifier": 3}
           ]
         },
@@ -1438,21 +1774,21 @@ Create guards for reward verification with double-claim protection:
         {
           "type": "logic_string_nocase_equal",
           "nodes": [
-            {"type": "query", "query": 1253, "object": {"identifier": 0, "convert_witness": 100}, "parameters": []},
+            {"type": "query", "query": "progress.current", "object": {"identifier": 0, "convert_witness": "OrderProgress"}, "parameters": []},
             {"type": "identifier", "identifier": 1}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1562, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.owner", "object": {"identifier": 0}, "parameters": []},
             {"type": "context", "context": "Signer"}
           ]
         },
         {
           "type": "logic_equal",
           "nodes": [
-            {"type": "query", "query": 1563, "object": {"identifier": 0}, "parameters": []},
+            {"type": "query", "query": "order.service", "object": {"identifier": 0}, "parameters": []},
             {"type": "identifier", "identifier": 3}
           ]
         },
@@ -2138,6 +2474,36 @@ Customer requests return after delivery confirmation.
 }
 ```
 
+> **Receipt Return path**: Steps 9.3 + 9.4 complete the Receipt Return → Return Complete transition (threshold=2, dual-signature). The customer submits return tracking (Merkle Root), and the merchant confirms receipt of the returned goods.
+
+**Step 9.5: Merchant Confirms Goods Recovered (Non-receipt Return path)**
+
+For the Non-receipt Return path, the customer never received the goods and has nothing to return. The customer's non-receipt was already confirmed when entering the Non-receipt Return node (dual-signature at entry). The transition to Return Complete requires only the merchant to confirm goods recovery (threshold=1).
+
+```json
+{
+  "operation_type": "progress",
+  "data": {
+    "object": "myshop_progress_v2",
+    "operate": {
+      "operation": {
+        "next_node_name": "Return Complete",
+        "forward": "Confirm Goods Recovered"
+      },
+      "hold": false,
+      "message": "Goods recovered by merchant - non-receipt return complete"
+    }
+  },
+  "env": {
+    "account": "myshop_merchant",
+    "network": "mainnet",
+    "no_cache": true
+  }
+}
+```
+
+> **Non-receipt Return path**: Only Step 9.5 is needed (threshold=1, merchant-only). No customer action required — the customer never received the goods and has nothing to return or submit. The merchant confirms the goods have been recovered (e.g., returned by logistics to the merchant).
+
 ***
 
 ### Step 10: Return Fail (Timeout)
@@ -2285,7 +2651,7 @@ When order reaches Lost or Return Complete, customer can withdraw funds.
 This advanced e-commerce example demonstrates:
 
 1. **Multi-Path Workflow**: Orders can complete through normal delivery, wonderful rating, or various return paths
-2. **Dual-Signature Returns**: Return processes require confirmation from both parties (threshold=2)
+2. **Dual-Signature Returns**: Receipt returns require confirmation from both parties (threshold=2); non-receipt returns require only merchant confirmation of goods recovery (threshold=1)
 3. **Time-Based Auto-Completion**: Orders auto-complete after time thresholds (10 days from shipping, 2 days from delivery)
 4. **Guard-Based Verification**: All state transitions and fund allocations are protected by guards
 5. **Reward Incentive System**: Wonderful ratings receive rewards, lost packages and shipping delays receive compensation