@wowok/agent-mcp 2.4.1 → 2.5.0

package/dist/knowledge/guard-templates.d.ts

@@ -20,6 +20,7 @@ export interface GuardTemplate {
     relevant_risks: string[];
     creation_notes: string[];
     example_use_case: string;
+    verifier_constraint_level?: "level1_strict" | "level2_identity_set" | "level3_scene_combined";
 }
 export declare const GUARD_TEMPLATES: GuardTemplate[];
 export declare function getTemplatesByScene(sceneId: string): GuardTemplate[];

package/dist/knowledge/guard-templates.js

@@ -26,6 +26,7 @@ export const GUARD_TEMPLATES = [
             "If the Service is already published, the table can use the address directly; otherwise use the name (P16 circular reference)",
         ],
         example_use_case: "Internal testing phase for camera equipment rental, allowing only the first 50 seed users to place rental orders.",
+        verifier_constraint_level: "level2_identity_set",
     },
     {
         id: "tpl_allocator_threshold",
@@ -55,6 +56,202 @@ export const GUARD_TEMPLATES = [
             "Threshold boundary must be tested: behavior when exactly equal to the threshold (> vs >=)",
         ],
         example_use_case: "E-commerce platform: order amount > 1000 WOW triggers 3-way allocation (platform + merchant + logistics); otherwise 2-way allocation (platform + merchant).",
+        verifier_constraint_level: "level3_scene_combined",
+    },
+    {
+        id: "tpl_allocator_treasury_personal",
+        scene_id: "service_order_allocators_guard",
+        name: "Treasury + personal address allocation (Entity sharing)",
+        description: "2 allocators representing 2 merchant collection approaches: (1) named Treasury address for public fund aggregation, (2) fixed personal address. " +
+            "Uses sharing.who=Entity so funds always flow to the legitimate recipient regardless of caller — no Signer binding needed in Guard. " +
+            "Guards verify the order is at the Complete node + belongs to the service (project binding).",
+        recommended_patterns: ["P02", "P10", "P16"],
+        parameters: [
+            { name: "service_name", type: "string", description: "Service object name (circular ref via P16 — resolved after Service publish)", required: true,
+                constraint: "Must be a name, not an address (the Service is not yet published when the Guard is created)" },
+            { name: "complete_node_name", type: "string", description: "Expected node name that triggers allocation (e.g. 'Complete')", required: true,
+                default: "Complete", constraint: "Must exactly match the Machine node name (case-sensitive)" },
+            { name: "treasury_name", type: "string", description: "Named Treasury object (created with the Service's permission)", required: true,
+                constraint: "Treasury must be created before the Service; use the SAME permission as the Service for consistency" },
+            { name: "personal_address", type: "address", description: "Fixed personal collection address (e.g. the permission creator's address)", required: true },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address", object_type: "Order",
+                name: "order_id (Order object submitted at runtime)" },
+            { identifier: 1, b_submission: false, value_type: "String", value: "${complete_node_name}",
+                name: "Expected Complete node name (case-sensitive)" },
+            { identifier: 2, b_submission: false, value_type: "Address", value: "${service_name}",
+                name: "Service object (project binding, circular ref via name)" },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "query", query: "progress.current", object: { identifier: 0, convert_witness: "OrderProgress" }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "query", query: "order.service", object: { identifier: 0 }, parameters: [] },
+                        { type: "identifier", identifier: 2 },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["insurance", "ecommerce", "travel", "rental", "subscription"],
+        relevant_risks: ["R-C3-05", "R-C3-06", "R-X1-05", "R-X1-01"],
+        creation_notes: [
+            "2 Guard objects with IDENTICAL root/table but DIFFERENT descriptions (allocators require unique guard addresses — no two allocators may reference the same Guard).",
+            "sharing.who=Entity (Treasury/personal) — no Signer binding needed in the Guard (R-C3-06 safe).",
+            "First-match-wins: only the first allocator (Treasury) executes; the personal allocator is an alternative (swap the allocators order to activate personal collection).",
+            "Treasury should be created with the SAME permission as the Service (permission consistency — different permissions = minor risk).",
+            "order.service binding (query 1563) suppresses R-C3-05 (cross-project bypass prevents premature allocation on foreign orders).",
+            "order_allocators is immutable after Service publish — verify the Guard logic and sharing config before publishing.",
+        ],
+        example_use_case: "Insurance service: after a claim reaches the Complete node, order funds are allocated to the insurance Treasury " +
+            "(approach 1, for operational fund aggregation) or to the provider's personal address (approach 2, for direct income).",
+        verifier_constraint_level: "level3_scene_combined",
+    },
+    {
+        id: "tpl_allocator_identity_set_order_holder",
+        scene_id: "service_order_allocators_guard",
+        name: "Order-holder identity-set allocation (Level 2)",
+        description: "Level 2 identity-set binding: Signer is order.owner (1562, Address) OR order.agent (1567, Bool with [Signer] param). " +
+            "Demonstrates the mixed return-type construction pattern — Address-returning queries are wrapped in logic_equal, " +
+            "while Bool-returning queries (suffix 'has') are used directly as logic_or children. " +
+            "Combined with order.service binding (R-C3-05) for cross-service theft prevention. " +
+            "Use when either the order owner or an authorized agent should be able to trigger allocation (e.g. refund to caller).",
+        recommended_patterns: ["P02", "P10", "P16"],
+        parameters: [
+            { name: "service_name", type: "string", description: "Service object name (circular ref via P16)", required: true,
+                constraint: "Must be a name, not an address (the Service is not yet published when the Guard is created)" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address", object_type: "Order",
+                name: "order_id (Order object submitted at runtime)" },
+            { identifier: 1, b_submission: false, value_type: "Address", value: "${service_name}",
+                name: "Service object (project binding, circular ref via name)" },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_or",
+                    nodes: [
+                        {
+                            type: "logic_equal",
+                            nodes: [
+                                { type: "query", query: "order.owner", object: { identifier: 0 }, parameters: [] },
+                                { type: "context", context: "Signer" },
+                            ],
+                        },
+                        {
+                            type: "query",
+                            query: "order.agent has",
+                            object: { identifier: 0 },
+                            parameters: [{ type: "context", context: "Signer" }],
+                        },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "query", query: "order.service", object: { identifier: 0 }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["ecommerce", "rental", "travel", "subscription"],
+        relevant_risks: ["R-C3-01", "R-C3-05", "R-C3-06", "R-C4-04"],
+        creation_notes: [
+            "MIXED RETURN-TYPE CONSTRUCTION (key Level 2 pattern): query 1562 (order.owner) returns Address → wrap in logic_equal with context(Signer); query 1567 (order.agent has) returns Bool → use directly as logic_or child with parameters: [context(Signer)].",
+            "logic_or wrapping of the Signer check suppresses R-C4-04 (Level 1 strict binding convenience warning) — this is the recommended Level 2 alternative.",
+            "Use this pattern when sharing.who=Signer (funds flow to caller) AND either the owner or an agent should be authorized to trigger allocation.",
+            "order.service binding (query 1563) suppresses R-C3-05 (cross-project bypass).",
+            "If agents are not needed, use the simpler Level 2 dynamic pattern: logic_equal[query(1562), context(Signer)] without logic_or.",
+        ],
+        example_use_case: "Refund allocation: when an order is cancelled, either the order owner or an authorized agent can trigger the refund. " +
+            "The Guard verifies Signer is order.owner OR order.agent, and that the order belongs to this service.",
+        verifier_constraint_level: "level2_identity_set",
+    },
+    {
+        id: "tpl_allocator_identity_set_service_provider_dynamic",
+        scene_id: "service_order_allocators_guard",
+        name: "Service-provider identity-set allocation with dynamic permission (Level 2)",
+        description: "Level 2 identity-set binding with DYNAMIC permission address: Signer is permission.owner (1002, Address) OR " +
+            "has admin (1004, Bool with [Signer] param). The permission address is submitted by the caller and verified " +
+            "against service.permission (1488) — this survives permission rotation without rebuilding the Guard. " +
+            "Use when the Service may rotate its permission (like a company changing its board) and a static permission " +
+            "address would break the Guard.",
+        recommended_patterns: ["P02", "P10", "P16"],
+        parameters: [
+            { name: "service_name", type: "string", description: "Service object name (circular ref via P16)", required: true,
+                constraint: "Must be a name, not an address (the Service is not yet published when the Guard is created)" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address", object_type: "Order",
+                name: "order_id (Order object submitted at runtime)" },
+            { identifier: 1, b_submission: false, value_type: "Address", value: "${service_name}",
+                name: "Service object (project binding, circular ref via name)" },
+            { identifier: 2, b_submission: true, value_type: "Address", object_type: "Permission",
+                name: "permission_id (Permission object submitted by caller — must equal service.permission)" },
+        ],
+        example_root: {
+            type: "logic_and",
+            nodes: [
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "query", query: "order.service", object: { identifier: 0 }, parameters: [] },
+                        { type: "identifier", identifier: 1 },
+                    ],
+                },
+                {
+                    type: "logic_equal",
+                    nodes: [
+                        { type: "query", query: "service.permission", object: { identifier: 1 }, parameters: [] },
+                        { type: "identifier", identifier: 2 },
+                    ],
+                },
+                {
+                    type: "logic_or",
+                    nodes: [
+                        {
+                            type: "logic_equal",
+                            nodes: [
+                                { type: "query", query: "permission.owner", object: { identifier: 2 }, parameters: [] },
+                                { type: "context", context: "Signer" },
+                            ],
+                        },
+                        {
+                            type: "query",
+                            query: "permission.admin has",
+                            object: { identifier: 2 },
+                            parameters: [{ type: "context", context: "Signer" }],
+                        },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["ecommerce", "rental", "insurance", "travel", "subscription"],
+        relevant_risks: ["R-C3-01", "R-C3-05", "R-C3-06", "R-C4-04"],
+        creation_notes: [
+            "DYNAMIC PERMISSION VERIFICATION (key pattern): caller submits a Permission address (identifier 2); Guard verifies query(1488: service.permission) == submitted permission, then checks 1002/1004 against the submitted permission. This survives permission rotation — if the Service changes its permission, the Guard still works without rebuilding.",
+            "MIXED RETURN-TYPE CONSTRUCTION: query 1002 (permission.owner) returns Address → wrap in logic_equal; query 1004 (permission.admin has) returns Bool → use directly as logic_or child with parameters: [context(Signer)].",
+            "logic_or wrapping of the Signer check suppresses R-C4-04 (Level 1 strict binding convenience warning).",
+            "THREE conditions in logic_and: (1) order.service binding (R-C3-05), (2) dynamic permission verification, (3) identity set (owner OR admin).",
+            "Static permission alternative (simpler but breaks on rotation): use a table constant for the permission address instead of b_submission=true + 1488 verification.",
+            "Repository-based address set (most flexible, most complex): store the permission address set in a Repository and query dynamically — only for extreme flexibility needs.",
+        ],
+        example_use_case: "Merchant allocation: the Service may rotate its permission (like a company changing its board). " +
+            "The caller submits the current permission address; the Guard verifies it matches service.permission (1488), " +
+            "then checks that Signer is the permission owner or has admin rights.",
+        verifier_constraint_level: "level2_identity_set",
     },
     {
         id: "tpl_forward_node_check",
@@ -75,8 +272,8 @@ export const GUARD_TEMPLATES = [
         example_root: {
             type: "logic_equal",
             left: {
-                type: "query", query: "progress.current_node_name",
-                object: { identifier: 0, convert_witness: 100 },
+                type: "query", query: "progress.current",
+                object: { identifier: 0, convert_witness: "OrderProgress" },
                 parameters: [],
             },
             right: { type: "identifier", identifier: 1 },
@@ -89,6 +286,79 @@ export const GUARD_TEMPLATES = [
             "Node names are case-sensitive; query returns a String type",
         ],
         example_use_case: "Camera equipment rental flow: the user must be at the 'pending return' node to perform the return operation.",
+        verifier_constraint_level: "level3_scene_combined",
+    },
+    {
+        id: "tpl_forward_privacy_delivery_proof",
+        scene_id: "machine_forward_guard",
+        name: "Privacy-delivery Proof verification (strict mode, Messenger → on-chain Proof)",
+        description: "Strict-mode guard for 'privacy information delivered via Messenger but not suitable for on-chain publication' " +
+            "(e.g. shipping details, return addresses, private credentials). The verifier submits BOTH a Proof object address " +
+            "(generated by messenger.submitChainProof) AND the Order object address. Three conditions verify: " +
+            "(1) Signer == proof.signer (submitter accountability — 'whoever benefits bears the burden of proof'), " +
+            "(2) proof.time > order.time (proof created after the order — freshness, prevents stale-proof replay), " +
+            "(3) order.service == service (project binding, suppresses R-C3-05 cross-project bypass). " +
+            "No content verification — only submission responsibility. The counterparty can dispute by checking their own " +
+            "Messenger conversation. Broad-mode alternative (verify Merkle Root string length == 66 via P15) is documented " +
+            "in creation_notes — broad mode trusts the submitter's honesty and is suitable when the Guard is mainly an " +
+            "arbitration basis rather than a fund-flow gate.",
+        recommended_patterns: ["P10", "P15"],
+        parameters: [
+            { name: "service_name", type: "string", description: "Service object name (circular ref via P16 — resolved after Service publish)", required: true,
+                constraint: "Must be a name, not an address (the Service is not yet published when the Guard is created)" },
+        ],
+        example_table: [
+            { identifier: 0, b_submission: true, value_type: "Address", object_type: "Proof",
+                name: "proof_object (Proof address generated by messenger.submitChainProof, submitted by verifier at runtime)",
+                binding_constraint: "Must be a Proof object created AFTER the order; signer must equal the transaction Signer" },
+            { identifier: 1, b_submission: true, value_type: "Address", object_type: "Order",
+                name: "order_object (Order address submitted by verifier at runtime)",
+                binding_constraint: "Must belong to the service declared in identifier 2 (order.service == service)" },
+            { identifier: 2, b_submission: false, value_type: "Address", value: "${service_name}",
+                name: "Service object (project binding, circular ref via name)" },
+        ],
+        example_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 },
+                    ],
+                },
+            ],
+        },
+        applicable_industries: ["ecommerce", "logistics", "service", "privacy delivery"],
+        relevant_risks: ["R-C3-01", "R-C3-05", "R-X1-12"],
+        creation_notes: [
+            "STRICT MODE (this template): verifier submits Proof + Order addresses. Three conditions: Signer==proof.signer (submitter accountability), proof.time>order.time (freshness), order.service==service (project binding). No content verification — only submission responsibility ('beneficiary bears burden of proof' principle).",
+            "BROAD MODE ALTERNATIVE: use P15 retained_submission with a String submission (the Merkle Root) and verify calc_string_length == 66 (0x prefix + 64 hex chars). Broad mode trusts the submitter's honesty; the counterparty can dispute by checking their own Messenger conversation. Broad mode is suitable when the Guard is mainly an arbitration basis, not a fund-flow gate.",
+            "Guard table supports MULTIPLE b_submission=true Address identifiers (no submission count limit) — this template uses two: Proof (identifier 0) and Order (identifier 1).",
+            "submitChainProof(env, peerAddress, description?) sets Proof.about = peerAddress (the counterparty's address). Pass the order_id as a string in the description parameter to associate the Proof with an order (e.g. description: 'order:0x123...').",
+            "Query IDs (all zero-parameter): proof.signer=1958, proof.time=1960 (invariant clock_derived, always >0), order.time=1574, order.service=1563.",
+            "Forward.guard is immutable after Machine publish — choose broad vs strict before publishing.",
+            "The same strict Guard can be reused across ALL Machine forwards that need merkle-root verification (shipping, lost, returns, etc.) — the verifier just submits the relevant Proof + Order each time.",
+            "Condition (1) Signer==proof.signer suppresses R-C3-01 (submission not bound to Signer). Condition (3) order.service==service suppresses R-C3-05 (cross-project submission bypass).",
+        ],
+        example_use_case: "MyShop e-commerce: after delivering shipping details / return addresses via Messenger (privacy info not suitable for on-chain publication), " +
+            "the provider generates a Proof via submitChainProof and submits it with the Order address to advance the Machine forward. " +
+            "The Guard verifies the submitter is the Proof's signer, the Proof was created after the order, and the order belongs to this service.",
+        verifier_constraint_level: "level3_scene_combined",
     },
     {
         id: "tpl_submission_signer_binding",
@@ -126,6 +396,7 @@ export const GUARD_TEMPLATES = [
             "Providing a binding_constraint field describing value rules is recommended (R-X1-12)",
         ],
         example_use_case: "On equipment return, the user submits the 'return' operation; the Guard verifies that the submitter is the service provider and that the operation type is correct.",
+        verifier_constraint_level: "level1_strict",
     },
     {
         id: "tpl_reward_one_time_claim",
@@ -160,6 +431,7 @@ export const GUARD_TEMPLATES = [
             "Reward guard is iterable; duplicate-claim protection requires rebuilding the Guard to update the Repository address",
         ],
         example_use_case: "New-user first-order reward: query the user's historical order count via Repository; allow claim only when record_count==0.",
+        verifier_constraint_level: "level3_scene_combined",
     },
     {
         id: "tpl_write_guard_type_check",
@@ -201,6 +473,7 @@ export const GUARD_TEMPLATES = [
             "EntityRegistrar (0xaab) and EntityLinker (0xaaa) are fixed system addresses",
         ],
         example_use_case: "E-commerce platform merchant writes product review data; the Guard verifies that the writer is a registered Entity and not a system address.",
+        verifier_constraint_level: "level1_strict",
     },
     {
         id: "tpl_usage_guard_threshold",
@@ -231,6 +504,7 @@ export const GUARD_TEMPLATES = [
             "When Arbitration bPaused=true, blocking takes priority (checked before Guard)",
         ],
         example_use_case: "Rental service dispute: only disputes with order amount ≥ 10 WOW are accepted, filtering out small-amount conflicts.",
+        verifier_constraint_level: "level3_scene_combined",
     },
     {
         id: "tpl_voting_guard_numeric_weight",
@@ -261,6 +535,7 @@ export const GUARD_TEMPLATES = [
             "Deriving weights from the Arb object via witness is recommended, rather than submitting them directly",
         ],
         example_use_case: "3-person arbitration panel: chief arbitrator weight 3, regular arbitrators weight 1, majority vote decision.",
+        verifier_constraint_level: "level2_identity_set",
     },
     {
         id: "tpl_gen_passport_identity",
@@ -291,6 +566,7 @@ export const GUARD_TEMPLATES = [
             "The generated Passport can be used as submission data for subsequent operations",
         ],
         example_use_case: "After the user passes identity verification, a Passport is generated; this Passport is then submitted as an identity credential in subsequent service purchases.",
+        verifier_constraint_level: "level1_strict",
     },
 ];
 export function getTemplatesByScene(sceneId) {

package/dist/knowledge/guard-translation.js

@@ -1,3 +1,4 @@
+import { MAX_SUBMISSION_SIZE_PASSPORT } from "@wowok/wowok";
 export const SEMANTIC_TO_SCHEMA_RULES = [
     {
         id: "P02",
@@ -523,7 +524,7 @@ export const SEMANTIC_TO_SCHEMA_RULES = [
             "The submitted object address should be bound to Signer (query the signer/owner field of the submitted object to validate ownership)",
             "Submitted numeric values should have range checks (>= min, <= max)",
             "Total table size must not exceed 40000 bytes",
-            "Total submission bytes must not exceed 256",
+            `Total submission bytes must not exceed ${MAX_SUBMISSION_SIZE_PASSPORT}`,
         ],
         example: {
             root: {
@@ -1000,12 +1001,12 @@ export const GUARD_CONSTRAINT_RULES = [
     },
     {
         id: "RUN_SUB_03",
-        name: "submission total bytes ≤ MAX_SUBMISSION_SIZE (256)",
-        description: "The total bytes of all data submitted at runtime must not exceed 256",
+        name: `submission total bytes ≤ MAX_SUBMISSION_SIZE_PASSPORT (${MAX_SUBMISSION_SIZE_PASSPORT})`,
+        description: `The total bytes of all data submitted at runtime must not exceed ${MAX_SUBMISSION_SIZE_PASSPORT}`,
         category: "table",
         phase: "runtime",
-        validation_logic: "total_submission_bytes <= 256",
-        failure_message: "Submission exceeds MAX_SUBMISSION_SIZE (256 bytes)",
+        validation_logic: `total_submission_bytes <= ${MAX_SUBMISSION_SIZE_PASSPORT}`,
+        failure_message: `Submission exceeds MAX_SUBMISSION_SIZE_PASSPORT (${MAX_SUBMISSION_SIZE_PASSPORT} bytes)`,
         verification_location: "Move verify L252",
     },
     {