@wowok/agent-mcp 2.5.2 → 2.5.4

package/dist/knowledge/index.js

@@ -208,6 +208,15 @@ export { BRIDGE_RISK_RULES, BRIDGE_RISK_VERSION, checkBridgeRisks, getBridgeRisk
 export { TOOLS_REFERENCE, getToolReference, searchToolReference, getToolSequence, };
 export { SCENARIO_MODES, SCENARIO_MODES_VERSION, MODE_COMPOSITIONS, matchScenarioMode, inferScenarioTraits, getScenarioMode, listScenarioModes, getShippedModes, getModeCompositions, };
 export { GUARD_DESIGN_PATTERNS, GUARD_DESIGN_PATTERNS_VERSION, VERIFIER_LEVEL_GUIDANCE, getGuardDesignPattern, searchGuardDesignPatterns, getPatternsByHost, getPatternsByIndustry, getPatternsByDataSourceClass, getVerifierLevelGuidance, suggestPatternForRequirement, };
+import { loadOverrides as loadOverridesFromDisk } from "./overrides-loader.js";
+let KNOWLEDGE_OVERRIDES = loadOverridesFromDisk();
+export function getKnowledgeOverrides() {
+    return KNOWLEDGE_OVERRIDES;
+}
+export function refreshKnowledgeOverrides() {
+    KNOWLEDGE_OVERRIDES = loadOverridesFromDisk(true);
+    return KNOWLEDGE_OVERRIDES;
+}
 export function getKnowledgeBase() {
     return {
         version: {

package/dist/knowledge/machine-context.d.ts

@@ -8,7 +8,7 @@ import { type ChecklistResult } from "./machine-confirm.js";
 import { type GuardScene } from "./guard-ledger.js";
 export declare const MACHINE_CONTEXT_VERSION = "1.0.0";
 export interface VerificationNote {
-    topic: "bReplace" | "um" | "consensus_repositories" | "namedOperator_assignment" | "cross_machine_dependency";
+    topic: "bReplace" | "um" | "consensus_repositories" | "namedOperator_assignment" | "cross_machine_dependency" | "first_node_semantics_service_bound";
     judgment: "YES" | "PARTIAL" | "NO";
     verified_semantic: string;
     code_reference: string;

package/dist/knowledge/machine-context.js

@@ -52,6 +52,23 @@ export const MACHINE_VERIFICATION_NOTES = [
         code_reference: "progress.move (progress::new, assert_published) + guard.move (convert_witness)",
         affected_modes: ["cross_machine", "pre_publish_check"],
     },
+    {
+        topic: "first_node_semantics_service_bound",
+        judgment: "YES",
+        verified_semantic: "For Service-bound Machines, the entry node (prev_node='' target) represents a " +
+            "POST-PAYMENT state, because Service.buy() performs quote + buy (payment) + " +
+            "order_allocation + order_progress ATOMICALLY in a single transaction. The Machine " +
+            "must NOT include separate 'Order', 'Pay', 'Reserve', or 'Subscribe' nodes — those " +
+            "actions are handled by the Service layer before the Progress (Machine instance) " +
+            "is created. All nodes after entry represent ORDER PROCESSING stages (fulfillment, " +
+            "delivery, confirmation, review, refund), NOT payment actions. Correct entry node " +
+            "examples: 'Paid', 'DepositPaid', 'Active'. Incorrect: 'OrderCreated', 'Reserved', " +
+            "'Subscribed'. See machine-ledger.ts first_node_semantics field per scene and " +
+            "machine-templates.ts example_nodes/example_pairs for the canonical structure.",
+        code_reference: "ts-sdk\\packages\\wowok\\src\\w\\call\\service.ts (buy: quote -> buy -> order_allocation -> order_progress) " +
+            "+ machine-ledger.ts (first_node_semantics field) + machine-templates.ts (example_nodes)",
+        affected_modes: ["initial_design", "mid_design_review", "pre_publish_check"],
+    },
 ];
 export function getMachineKnowledgeSnapshot() {
     const verifiedYes = MACHINE_VERIFICATION_NOTES.filter((n) => n.judgment === "YES").length;
@@ -632,7 +649,11 @@ function buildPromptHints(ctx) {
             hints.push("Start by confirming the matched scene and selecting a template.");
             if (ctx.matched_scene) {
                 hints.push(`Scene "${ctx.matched_scene.name}" recommends patterns: ${ctx.matched_scene.recommended_patterns.join(", ")}.`);
+                if (ctx.matched_scene.first_node_semantics) {
+                    hints.push(`First-node semantics: ${ctx.matched_scene.first_node_semantics}`);
+                }
             }
+            hints.push("⚠ First node convention: For Service-bound Machines, the entry node (prev_node='' target) MUST represent a POST-PAYMENT state (e.g. 'Paid', 'DepositPaid'). Do NOT add 'Order'/'Pay'/'Reserve'/'Subscribe' nodes — Service.buy() handles payment atomically before Progress is created.");
             if (ctx.suggested_templates.length > 0) {
                 hints.push(`Top template suggestion: ${ctx.suggested_templates[0].id} (${ctx.suggested_templates[0].name}).`);
             }

package/dist/knowledge/machine-ledger.d.ts

@@ -19,6 +19,7 @@ export interface MachineScene {
     guard_requirements: GuardRequirement[];
     allocation_integration: string;
     special_constraints: string[];
+    first_node_semantics: string;
     mutable_after_publish: boolean;
     m_rounds_focus: string[];
 }

package/dist/knowledge/machine-ledger.js

@@ -3,22 +3,25 @@ export const MACHINE_SCENES = [
         id: "ecommerce_standard",
         name: "Standard E-commerce Flow",
         industry: ["ecommerce"],
-        scenario: "Order → Pay → Ship → Receive → Complete",
+        scenario: "Paid (entry) → Ship → Receive → Complete",
         participants: [
-            { role: "customer", permission_type: "OrderHolder", involved_in: ["Order", "Receive"] },
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Receive"] },
             { role: "merchant", permission_type: "Permission", involved_in: ["Ship"] },
         ],
         recommended_patterns: ["P-M-SEQ"],
         recommended_topology: ["P-M-LINEAR"],
         guard_requirements: [
-            { forward: "Ship", scene: "machine_forward_guard", purpose: "Verify payment completion" },
+            { forward: "Ship", scene: "machine_forward_guard", purpose: "Verify order is paid (post-buy state)" },
             { forward: "Receive", scene: "machine_forward_guard", purpose: "Verify identity" },
         ],
         allocation_integration: "Complete node -> Allocator distributes funds to merchant",
         special_constraints: [
-            "Payment must complete before shipping (Guard verifies order.amount is paid)",
+            "First node 'Paid' represents post-payment state — buy() completes payment atomically before Progress is created",
+            "No separate 'Order' or 'Pay' nodes needed — payment is handled by Service.buy(), not Machine",
+            "All nodes after entry represent order processing (ship, receive, complete), NOT payment actions",
             "Receipt auto-triggers fund allocation",
         ],
+        first_node_semantics: "Paid — order has been created and paid via Service.buy(); Machine starts at post-payment state",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M2", "M3", "M5", "M8"],
     },
@@ -26,24 +29,26 @@ export const MACHINE_SCENES = [
         id: "ecommerce_with_exceptions",
         name: "E-commerce Flow with Exception Branches",
         industry: ["ecommerce"],
-        scenario: "Order → Pay → Ship → {Receive → Complete | Lost → Arbitration | Return → Refund}",
+        scenario: "Paid (entry) → Ship → {Receive → Complete | Lost (terminal) | Return → Refund}",
         participants: [
-            { role: "customer", permission_type: "OrderHolder", involved_in: ["Order", "Receive", "Return"] },
-            { role: "merchant", permission_type: "Permission", involved_in: ["Ship", "Refund"] },
-            { role: "arbitrator", permission_type: "NamedOperator", involved_in: ["Arbitration"] },
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Receive", "Return", "Lost"] },
+            { role: "merchant", permission_type: "Permission", involved_in: ["Ship", "Refund", "Lost"] },
         ],
         recommended_patterns: ["P-M-SEQ", "P-M-COMPETING"],
         recommended_topology: ["P-M-LINEAR", "P-M-COMPETING"],
         guard_requirements: [
             { forward: "Lost", scene: "machine_forward_guard", purpose: "Dual-sig to confirm lost" },
-            { forward: "Arbitration", scene: "arbitration_usage_guard", purpose: "Verify arbitration eligibility" },
         ],
-        allocation_integration: "Complete->merchant | Refund->customer | Arb->arbitrator",
+        allocation_integration: "Complete->merchant | Refund->customer | Lost->escrow or partial refund (Allocator only). Disputes are NOT modeled here — they flow through Order + Arbitration object off-Machine.",
         special_constraints: [
-            "Lost node threshold=2 (customer + merchant dual-sig)",
-            "Competing Pair: Receive vs Lost (first-wins)",
-            "Arbitration flow independent of main flow",
+            "First node 'Paid' represents post-payment state — buy() completes payment atomically before Progress is created",
+            "No separate 'Order' or 'Pay' nodes needed — payment is handled by Service.buy(), not Machine",
+            "Lost node threshold=2 (customer + merchant dual-sig) — Lost is a TERMINAL node, not a path to arbitration",
+            "Competing Pair: Receive vs Lost vs Return (first-wins)",
+            "DISPUTE INDEPENDENCE: arbitration is NOT a Machine node. If a Lost-terminal order later needs dispute resolution, the customer files arbitration::dispute(order, arbitration) against the Arbitration object bound to the Service — completely off-Machine. Arbitrators live in Arbitration.voting_guard, never in Permission or NamedOperator.",
+            "Refund Allocation must use sharing.who=OrderHolder (refund to customer, NOT merchant)",
         ],
+        first_node_semantics: "Paid — order has been created and paid via Service.buy(); Machine starts at post-payment state",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M2", "M3", "M5", "M6", "M8"],
     },
@@ -51,22 +56,25 @@ export const MACHINE_SCENES = [
         id: "rental_standard",
         name: "Equipment Rental Flow",
         industry: ["rental"],
-        scenario: "Reserve → Pay Deposit → Pickup → In Use → Return → Refund Deposit",
+        scenario: "DepositPaid (entry) → Pickup → In Use → Return → Refund Deposit",
         participants: [
-            { role: "customer", permission_type: "OrderHolder", involved_in: ["Reserve", "Pickup", "Return"] },
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Pickup", "Return"] },
             { role: "merchant", permission_type: "Permission", involved_in: ["Deliver", "Refund Deposit"] },
         ],
         recommended_patterns: ["P-M-SEQ"],
         recommended_topology: ["P-M-LINEAR"],
         guard_requirements: [
-            { forward: "Pickup", scene: "machine_forward_guard", purpose: "Verify deposit paid" },
+            { forward: "Pickup", scene: "machine_forward_guard", purpose: "Verify deposit paid (post-buy state)" },
             { forward: "Return", scene: "machine_forward_guard", purpose: "Verify equipment condition" },
         ],
         allocation_integration: "Return complete -> deposit refund + rental fee allocation",
         special_constraints: [
+            "First node 'DepositPaid' represents post-payment state — buy() completes deposit payment atomically before Progress is created",
+            "No separate 'Reserve' or 'PayDeposit' nodes needed — reservation and payment are handled by Service.buy(), not Machine",
             "Deposit and rental fee separated (two Allocators)",
             "Equipment damage verified by Guard (retained_submission stores inspection report)",
         ],
+        first_node_semantics: "DepositPaid — deposit has been paid via Service.buy(); Machine starts at post-deposit state",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M2", "M3", "M5", "M8"],
     },
@@ -90,6 +98,7 @@ export const MACHINE_SCENES = [
             "Customer Forward: namedOperator='' (OrderHolder)",
             "Merchant Forward: permissionIndex=2",
         ],
+        first_node_semantics: "Initiated — order has been created and paid via Service.buy(); Machine starts at post-payment state, awaiting dual-sig confirmation",
         mutable_after_publish: false,
         m_rounds_focus: ["M3", "M4", "M5"],
     },
@@ -113,6 +122,7 @@ export const MACHINE_SCENES = [
             "GuardIdentifier must be numeric type (extracts weight)",
             "Prevent double-voting (Guard queries arb.voted has)",
         ],
+        first_node_semantics: "VoteOpened — dispute has been submitted (order already paid via Service.buy()); Machine starts at post-payment dispute state",
         mutable_after_publish: false,
         m_rounds_focus: ["M3", "M4", "M5"],
     },
@@ -138,7 +148,9 @@ export const MACHINE_SCENES = [
             "Cross-Machine dependency is one-way (no cycles)",
             "Each Machine must be published independently",
             "Dependency verification: indirect via progress::new -> assert_published (see 06 §14.6)",
+            "Each Machine in the chain starts at a post-payment state (each link's Service.buy() handles payment independently)",
         ],
+        first_node_semantics: "UpstreamVerified — order has been paid via upstream Service.buy(); Machine starts at post-payment state, verifying upstream completion",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M3", "M8"],
     },
@@ -163,7 +175,9 @@ export const MACHINE_SCENES = [
             "Proof MUST be generated by messenger.submitChainProof",
             "submitChainProof about_address = peerAddress (NOT sessionId)",
             "Guard table item name <64 BCS bytes (MAX_NAME_LENGTH=64)",
+            "First node represents post-payment state — payment is handled by Service.buy(), not Machine",
         ],
+        first_node_semantics: "Paid — order has been created and paid via Service.buy(); Machine starts at post-payment state, awaiting proof submission",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M3", "M7"],
     },
@@ -187,42 +201,45 @@ export const MACHINE_SCENES = [
             "Uses query_reward_record_count == 0 for anti-reentry",
             "Reward object must be already created",
         ],
+        first_node_semantics: "Eligible — order has been created and paid via Service.buy(); Machine starts at post-payment state, customer is eligible to claim reward",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M3", "M8"],
     },
     {
-        id: "arbitration_flow",
-        name: "Arbitration Flow",
-        industry: ["ecommerce", "service", "rental"],
-        scenario: "Dispute → Submit → Vote → Ruling → Execute",
+        id: "wonder_feedback",
+        name: "Wonder Feedback Flow (Post-Completion Rating)",
+        industry: ["ecommerce", "service", "rental", "subscription", "education"],
+        scenario: "Paid (entry) → ... → Completed → {Wonder | NoWonder} (rating terminals)",
         participants: [
-            { role: "disputant", permission_type: "OrderHolder", involved_in: ["Submit Dispute"] },
-            { role: "arbitrator", permission_type: "NamedOperator", involved_in: ["Vote"] },
-            { role: "system", permission_type: "Permission", involved_in: ["Execute Ruling"] },
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Wonder", "NoWonder"] },
+            { role: "merchant", permission_type: "Permission", involved_in: ["Completed"] },
         ],
-        recommended_patterns: ["P-M-VOTE", "P-M-SEQ"],
-        recommended_topology: ["P-M-LINEAR"],
+        recommended_patterns: ["P-M-SEQ", "P-M-COMPETING"],
+        recommended_topology: ["P-M-LINEAR", "P-M-COMPETING"],
         guard_requirements: [
-            { forward: "Submit Dispute", scene: "arbitration_usage_guard", purpose: "Verify dispute eligibility + prevent double-dispute" },
-            { forward: "Vote", scene: "arbitration_voting_guard", purpose: "Verify voting eligibility + extract weight" },
+            { forward: "Praise", scene: "machine_forward_guard", purpose: "Verify Progress.current == 'Completed' (rating only after completion)" },
+            { forward: "Complain", scene: "machine_forward_guard", purpose: "Verify Progress.current == 'Completed' (rating only after completion)" },
         ],
-        allocation_integration: "After ruling -> distribute funds according to ruling",
+        allocation_integration: "Completed -> merchant allocation (terminal); Wonder/NoWonder are reputation terminals — no fund allocation. Reward object (independent) claims fire when Progress.current == 'wonder'",
         special_constraints: [
-            "Arbitration object must be already created",
-            "Prevent double-dispute (R-X1-14 HIGH)",
-            "Prevent double-vote (R-X1-14 CRITICAL)",
-            "MAX_DISPUTE_COUNT=10 per order",
+            "Dispute MUST NOT be modeled as machine nodes — disputes flow through Order + Arbitration object, independent of this Machine",
+            "Wonder/NoWonder are POST-completion terminals: order is already settled when customer rates",
+            "Both Wonder and NoWonder forwards have named_operator='' (OrderHolder) — rating is a customer-only action",
+            "Reward object (if bound) MUST use a Guard verifying Progress.current == 'wonder' AND order.holder == signer — no Permission needed for reward claim",
+            "Competing Pair: Praise vs Complain (first-wins; one rating per order)",
+            "No dispute/refund/arbitration nodes in this Machine — those flows live off-Machine",
         ],
+        first_node_semantics: "Paid — order has been created and paid via Service.buy(); Machine starts at post-payment state, same as e-commerce baseline",
         mutable_after_publish: false,
-        m_rounds_focus: ["M1", "M3", "M4", "M5", "M8"],
+        m_rounds_focus: ["M1", "M2", "M3", "M5", "M8"],
     },
     {
         id: "subscription",
         name: "Subscription / Membership Flow",
         industry: ["subscription", "service"],
-        scenario: "Subscribe → Pay → Activate → [Renew | Expire] → Cancel/End",
+        scenario: "Paid (entry) → Activate → [Renew | Expire] → Cancel/End",
         participants: [
-            { role: "subscriber", permission_type: "OrderHolder", involved_in: ["Subscribe", "Renew", "Cancel"] },
+            { role: "subscriber", permission_type: "OrderHolder", involved_in: ["Renew", "Cancel"] },
             { role: "provider", permission_type: "Permission", involved_in: ["Activate", "Pause"] },
         ],
         recommended_patterns: ["P-M-SEQ", "P-M-COMPETING"],
@@ -233,11 +250,14 @@ export const MACHINE_SCENES = [
         ],
         allocation_integration: "Renew -> fund allocation | Expire -> stop service",
         special_constraints: [
+            "First node 'Paid' represents post-payment state — buy() completes subscription payment atomically before Progress is created",
+            "No separate 'Subscribe' or 'Pay' nodes needed — subscription and payment are handled by Service.buy(), not Machine",
             "Time-lock: context(Clock) >= progress.entry_time + duration",
             "Competing Pair: Renew vs Expire (first-wins)",
             "Repository records subscription status",
             "Note: Machine.consensus_repositories is declarative-only and NOT auto-passed to Progress (see 06 §14.4)",
         ],
+        first_node_semantics: "Paid — subscription has been created and paid via Service.buy(); Machine starts at post-payment state, awaiting activation",
         mutable_after_publish: false,
         m_rounds_focus: ["M1", "M3", "M6", "M8"],
     },
@@ -261,8 +281,11 @@ export function inferSceneFromFlow(description) {
     if (lower.includes("supply chain") || lower.includes("cross-machine")) {
         return findScene("cross_machine_supply_chain");
     }
-    if (lower.includes("arbitration") || lower.includes("dispute")) {
-        return findScene("arbitration_flow");
+    if (lower.includes("wonder") || lower.includes("praise") || lower.includes("complain")
+        || lower.includes("thumbs_up") || lower.includes("thumbs_down")
+        || lower.includes("rating") || lower.includes("feedback")
+        || lower.includes("好评") || lower.includes("差评")) {
+        return findScene("wonder_feedback");
     }
     if (lower.includes("reward") || lower.includes("incentive")) {
         return findScene("reward_incentive");

package/dist/knowledge/machine-risk.js

@@ -109,6 +109,29 @@ export const MACHINE_RISK_RULES = [
         auto_fixable: false,
         related_constraint: "MC-C-04",
     },
+    {
+        id: "R-M1-11",
+        name: "Dispute anti-pattern — machine illegally models dispute flow",
+        category: "structural",
+        severity: "critical",
+        description: "Machine contains nodes named 'disputed', 'refunded', 'arb', 'arbitration', " +
+            "'dispute', or 'refund'. This is a CRITICAL design anti-pattern because " +
+            "dispute is INDEPENDENT of the machine workflow. Dispute flows through: " +
+            "Order → Arbitration.dispute() → Arb object → arbitration() ruling → " +
+            "arb_withdraw by order holder. Arbitrators are configured in " +
+            "Arbitration.voting_guard, NOT in Permission. Merchants who model " +
+            "dispute in the machine (e.g., 'disputed → refunded' forward guarded " +
+            "by Permission index 1500) create dead-end paths because no one has " +
+            "Permission 1500 — arbitrators are NOT Permission holders.",
+        detection: "Match node names against regex /^(disputed|refunded|arb|arbitration|dispute|refund)$/i",
+        recommendation: "Remove all dispute/refund nodes from the machine. Instead: (1) bind an " +
+            "Arbitration object to the Service via Service.arbitrations, (2) configure " +
+            "arbitrators via Arbitration.voting_guard_add, (3) deposit compensation_fund " +
+            "to the Service. Disputes are then filed via arbitration::dispute(order, " +
+            "arbitration) — completely independent of the machine workflow.",
+        auto_fixable: false,
+        related_constraint: "dispute_independence_principle",
+    },
     {
         id: "R-M2-01",
         name: "Guard not created",