@wowok/agent-mcp 2.4.3 → 2.5.0

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

@@ -0,0 +1,41 @@
+export interface ParticipantRoleDef {
+    role: string;
+    permission_type: "Permission" | "NamedOperator" | "OrderHolder";
+    involved_in: string[];
+}
+export interface GuardRequirement {
+    forward: string;
+    scene: string;
+    purpose: string;
+}
+export interface MachineScene {
+    id: string;
+    name: string;
+    industry: string[];
+    scenario: string;
+    participants: ParticipantRoleDef[];
+    recommended_patterns: string[];
+    recommended_topology: string[];
+    guard_requirements: GuardRequirement[];
+    allocation_integration: string;
+    special_constraints: string[];
+    mutable_after_publish: boolean;
+    m_rounds_focus: string[];
+}
+export declare const MACHINE_SCENES: MachineScene[];
+export declare const MACHINE_LEDGER_VERSION = "1.0.0";
+export declare const MACHINE_SCENES_COUNT: number;
+export declare function findScene(id: string): MachineScene | undefined;
+export declare function getScenesByIndustry(industry: string): MachineScene[];
+export declare function getScenesByPattern(patternId: string): MachineScene[];
+export declare function getScenesByTopology(topologyId: string): MachineScene[];
+export declare function inferSceneFromFlow(description: string): MachineScene | undefined;
+export declare function getImmutableScenes(): MachineScene[];
+export declare function getScenesWithGuardRequirements(): MachineScene[];
+export declare function getReferencedGuardSceneIds(): Set<string>;
+export declare function listScenes(): Array<{
+    id: string;
+    name: string;
+    scenario: string;
+    patterns: string[];
+}>;

package/dist/knowledge/machine-ledger.js

@@ -0,0 +1,315 @@
+export const MACHINE_SCENES = [
+    {
+        id: "ecommerce_standard",
+        name: "Standard E-commerce Flow",
+        industry: ["ecommerce"],
+        scenario: "Order → Pay → Ship → Receive → Complete",
+        participants: [
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Order", "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: "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)",
+            "Receipt auto-triggers fund allocation",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M2", "M3", "M5", "M8"],
+    },
+    {
+        id: "ecommerce_with_exceptions",
+        name: "E-commerce Flow with Exception Branches",
+        industry: ["ecommerce"],
+        scenario: "Order → Pay → Ship → {Receive → Complete | Lost → Arbitration | 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"] },
+        ],
+        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",
+        special_constraints: [
+            "Lost node threshold=2 (customer + merchant dual-sig)",
+            "Competing Pair: Receive vs Lost (first-wins)",
+            "Arbitration flow independent of main flow",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M2", "M3", "M5", "M6", "M8"],
+    },
+    {
+        id: "rental_standard",
+        name: "Equipment Rental Flow",
+        industry: ["rental"],
+        scenario: "Reserve → Pay Deposit → Pickup → In Use → Return → Refund Deposit",
+        participants: [
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Reserve", "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: "Return", scene: "machine_forward_guard", purpose: "Verify equipment condition" },
+        ],
+        allocation_integration: "Return complete -> deposit refund + rental fee allocation",
+        special_constraints: [
+            "Deposit and rental fee separated (two Allocators)",
+            "Equipment damage verified by Guard (retained_submission stores inspection report)",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M2", "M3", "M5", "M8"],
+    },
+    {
+        id: "dual_signature",
+        name: "Dual-Signature Consensus Flow",
+        industry: ["ecommerce", "service", "logistics"],
+        scenario: "Critical node requires customer + merchant dual confirmation to advance",
+        participants: [
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Confirm"] },
+            { role: "merchant", permission_type: "Permission", involved_in: ["Confirm"] },
+        ],
+        recommended_patterns: ["P-M-AND"],
+        recommended_topology: ["P-M-LINEAR"],
+        guard_requirements: [
+            { forward: "Both Confirm", scene: "machine_forward_guard", purpose: "Verify identity" },
+        ],
+        allocation_integration: "After dual-sig -> fund allocation",
+        special_constraints: [
+            "threshold=2, two Forwards with weight=1 each",
+            "Customer Forward: namedOperator='' (OrderHolder)",
+            "Merchant Forward: permissionIndex=2",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M3", "M4", "M5"],
+    },
+    {
+        id: "weighted_voting",
+        name: "Weighted Voting Flow",
+        industry: ["governance", "arbitration"],
+        scenario: "Multi-party voting with unequal weights, accumulate to threshold to advance",
+        participants: [
+            { role: "chief", permission_type: "Permission", involved_in: ["Vote"] },
+            { role: "member", permission_type: "NamedOperator", involved_in: ["Vote"] },
+        ],
+        recommended_patterns: ["P-M-VOTE"],
+        recommended_topology: ["P-M-LINEAR"],
+        guard_requirements: [
+            { forward: "Vote", scene: "arbitration_voting_guard", purpose: "Verify voting eligibility + weight extraction" },
+        ],
+        allocation_integration: "After voting complete -> result execution",
+        special_constraints: [
+            "threshold=100, chief weight=60, member weight=40",
+            "GuardIdentifier must be numeric type (extracts weight)",
+            "Prevent double-voting (Guard queries arb.voted has)",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M3", "M4", "M5"],
+    },
+    {
+        id: "cross_machine_supply_chain",
+        name: "Cross-Machine Supply Chain",
+        industry: ["manufacturing", "logistics", "retail"],
+        scenario: "Supplier → Manufacturer → Retailer, each link is independent Machine",
+        participants: [
+            { role: "supplier", permission_type: "Permission", involved_in: ["Machine A"] },
+            { role: "manufacturer", permission_type: "Permission", involved_in: ["Machine B"] },
+            { role: "retailer", permission_type: "Permission", involved_in: ["Machine C"] },
+        ],
+        recommended_patterns: ["P-M-CROSS-MACHINE"],
+        recommended_topology: ["P-M-LINEAR"],
+        guard_requirements: [
+            { forward: "Start Manufacturing", scene: "machine_forward_guard", purpose: "Verify supplier Progress completed" },
+            { forward: "Start Retail", scene: "machine_forward_guard", purpose: "Verify manufacturer Progress completed" },
+        ],
+        allocation_integration: "Each Machine has independent allocation",
+        special_constraints: [
+            "Machine B's Guard uses convert_witness=100 to query Machine A's Progress",
+            "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)",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M3", "M8"],
+    },
+    {
+        id: "privacy_delivery",
+        name: "Privacy Delivery Flow",
+        industry: ["ecommerce", "logistics"],
+        scenario: "Privacy data delivered via Messenger (encrypted), chain stores only Proof",
+        participants: [
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Submit Proof"] },
+            { role: "merchant", permission_type: "Permission", involved_in: ["Verify Proof"] },
+        ],
+        recommended_patterns: ["P-M-SEQ"],
+        recommended_topology: ["P-M-LINEAR"],
+        guard_requirements: [
+            { forward: "Submit Proof", scene: "machine_forward_guard", purpose: "Verify Proof signature + timestamp" },
+        ],
+        allocation_integration: "After Proof verified -> continue flow",
+        special_constraints: [
+            "Uses tpl_forward_privacy_delivery_proof template (strict mode)",
+            "retained_submission preserves Proof address for arbitration query",
+            "Proof MUST be generated by messenger.submitChainProof",
+            "submitChainProof about_address = peerAddress (NOT sessionId)",
+            "Guard table item name <64 BCS bytes (MAX_NAME_LENGTH=64)",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M3", "M7"],
+    },
+    {
+        id: "reward_incentive",
+        name: "Reward Incentive Flow",
+        industry: ["ecommerce", "subscription", "education"],
+        scenario: "Trigger Reward claim after completing specific node",
+        participants: [
+            { role: "customer", permission_type: "OrderHolder", involved_in: ["Claim Reward"] },
+            { role: "platform", permission_type: "Permission", involved_in: ["Issue Reward"] },
+        ],
+        recommended_patterns: ["P-M-SEQ"],
+        recommended_topology: ["P-M-LINEAR"],
+        guard_requirements: [
+            { forward: "Claim", scene: "reward_guard", purpose: "Verify claim eligibility + prevent double-claim" },
+        ],
+        allocation_integration: "Reward is independent of Allocation",
+        special_constraints: [
+            "Reward Guard must prevent double-claim (R-X1-14 CRITICAL)",
+            "Uses query_reward_record_count == 0 for anti-reentry",
+            "Reward object must be already created",
+        ],
+        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",
+        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"] },
+        ],
+        recommended_patterns: ["P-M-VOTE", "P-M-SEQ"],
+        recommended_topology: ["P-M-LINEAR"],
+        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" },
+        ],
+        allocation_integration: "After ruling -> distribute funds according to ruling",
+        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",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M3", "M4", "M5", "M8"],
+    },
+    {
+        id: "subscription",
+        name: "Subscription / Membership Flow",
+        industry: ["subscription", "service"],
+        scenario: "Subscribe → Pay → Activate → [Renew | Expire] → Cancel/End",
+        participants: [
+            { role: "subscriber", permission_type: "OrderHolder", involved_in: ["Subscribe", "Renew", "Cancel"] },
+            { role: "provider", permission_type: "Permission", involved_in: ["Activate", "Pause"] },
+        ],
+        recommended_patterns: ["P-M-SEQ", "P-M-COMPETING"],
+        recommended_topology: ["P-M-LINEAR", "P-M-COMPETING"],
+        guard_requirements: [
+            { forward: "Renew", scene: "machine_forward_guard", purpose: "Time-lock verification" },
+            { forward: "Cancel", scene: "machine_forward_guard", purpose: "Verify subscription status" },
+        ],
+        allocation_integration: "Renew -> fund allocation | Expire -> stop service",
+        special_constraints: [
+            "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)",
+        ],
+        mutable_after_publish: false,
+        m_rounds_focus: ["M1", "M3", "M6", "M8"],
+    },
+];
+export const MACHINE_LEDGER_VERSION = "1.0.0";
+export const MACHINE_SCENES_COUNT = MACHINE_SCENES.length;
+export function findScene(id) {
+    return MACHINE_SCENES.find((s) => s.id === id);
+}
+export function getScenesByIndustry(industry) {
+    return MACHINE_SCENES.filter((s) => s.industry.includes(industry));
+}
+export function getScenesByPattern(patternId) {
+    return MACHINE_SCENES.filter((s) => s.recommended_patterns.includes(patternId));
+}
+export function getScenesByTopology(topologyId) {
+    return MACHINE_SCENES.filter((s) => s.recommended_topology.includes(topologyId));
+}
+export function inferSceneFromFlow(description) {
+    const lower = description.toLowerCase();
+    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("reward") || lower.includes("incentive")) {
+        return findScene("reward_incentive");
+    }
+    if (lower.includes("privacy") || lower.includes("messenger")) {
+        return findScene("privacy_delivery");
+    }
+    if (lower.includes("vote") || lower.includes("weight")) {
+        return findScene("weighted_voting");
+    }
+    if (lower.includes("dual-sig") || lower.includes("both confirm")) {
+        return findScene("dual_signature");
+    }
+    if (lower.includes("subscribe") || lower.includes("membership")) {
+        return findScene("subscription");
+    }
+    if (lower.includes("rental") || lower.includes("deposit")) {
+        return findScene("rental_standard");
+    }
+    if (lower.includes("lost") || lower.includes("return")) {
+        return findScene("ecommerce_with_exceptions");
+    }
+    if (lower.includes("ecommerce") || lower.includes("order")) {
+        return findScene("ecommerce_standard");
+    }
+    return undefined;
+}
+export function getImmutableScenes() {
+    return MACHINE_SCENES.filter((s) => !s.mutable_after_publish);
+}
+export function getScenesWithGuardRequirements() {
+    return MACHINE_SCENES.filter((s) => s.guard_requirements.length > 0);
+}
+export function getReferencedGuardSceneIds() {
+    const ids = new Set();
+    for (const scene of MACHINE_SCENES) {
+        for (const req of scene.guard_requirements) {
+            ids.add(req.scene);
+        }
+    }
+    return ids;
+}
+export function listScenes() {
+    return MACHINE_SCENES.map((s) => ({
+        id: s.id,
+        name: s.name,
+        scenario: s.scenario,
+        patterns: s.recommended_patterns,
+    }));
+}

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

@@ -0,0 +1,206 @@
+import { type MachineNode, type MachinePair } from "./machine-topology.js";
+export interface BusinessFlowPuzzle {
+    scenario_description: string;
+    scene_id?: string;
+    template_id?: string;
+    industry?: string;
+    participation_mode?: "P-M1" | "P-M2" | "P-M3" | "P-M4" | "P-M5";
+    referenced_machine_ids?: string[];
+    fork_source_template_id?: string;
+}
+export interface NodeDesignPuzzle {
+    nodes: Array<{
+        name: string;
+        description: string;
+        is_entry: boolean;
+        is_terminal: boolean;
+    }>;
+    topological_order: string[];
+    business_stage_mapping: Record<string, string>;
+}
+export interface GuardAcceptancePuzzle {
+    guard_bindings: Array<{
+        forward_id: {
+            pair_id: {
+                prev_node: string;
+                next_node: string;
+            };
+            forward_name: string;
+        };
+        guard_template_id?: string;
+        guard_address?: string;
+        purpose: string;
+        tested_on_testnet: boolean;
+    }>;
+    name_length_verified: boolean;
+    all_guards_created: boolean;
+    cross_machine_guards: Array<{
+        forward_id: {
+            pair_id: {
+                prev_node: string;
+                next_node: string;
+            };
+            forward_name: string;
+        };
+        upstream_machine_id: string;
+        upstream_node_name: string;
+    }>;
+}
+export interface ForwardPermission {
+    forward: {
+        pair_id: {
+            prev_node: string;
+            next_node: string;
+        };
+        forward_name: string;
+    };
+    namedOperator: {
+        type: "none" | "order_holder" | "role";
+        role?: string;
+    };
+    permissionIndex: {
+        type: "none" | "builtin" | "custom";
+        index?: number;
+    };
+    semantic: string;
+}
+export interface PermissionObjectConfig {
+    use_custom: boolean;
+    custom_indices?: Array<{
+        index: number;
+        name: string;
+        description: string;
+    }>;
+}
+export interface NamedOperatorRole {
+    role: string;
+    semantic: string;
+    assignment_timing: "at_progress_new_via_sdk" | "after_progress_new";
+}
+export interface PermissionModelPuzzle {
+    forward_permissions: ForwardPermission[];
+    permission_object?: PermissionObjectConfig;
+    named_operator_roles: NamedOperatorRole[];
+    completeness_verified: boolean;
+}
+export interface ThresholdWeightPuzzle {
+    pair_thresholds: Array<{
+        pair_id: {
+            prev_node: string;
+            next_node: string;
+        };
+        threshold: number;
+        semantic: string;
+    }>;
+    forward_weights: Array<{
+        forward_id: {
+            pair_id: {
+                prev_node: string;
+                next_node: string;
+            };
+            forward_name: string;
+        };
+        weight: number;
+        semantic: string;
+    }>;
+    execution_mode: string;
+    allocator_integration: Array<{
+        name: string;
+        trigger_node: string;
+        sharing_who: "Entity" | "OrderHolder" | "Custom";
+        recipient_description: string;
+    }>;
+}
+export interface BranchTopologyPuzzle {
+    topology_pattern: string;
+    branching_points: Array<{
+        node: string;
+        branches: string[];
+        branch_type: "parallel" | "competing";
+    }>;
+    merge_points: Array<{
+        node: string;
+        incoming_from: string[];
+    }>;
+    is_dag: boolean;
+}
+export interface OverallObjectivePuzzle {
+    primary_branch: {
+        start_node: string;
+        end_node: string;
+        description: string;
+    };
+    secondary_branches: Array<{
+        branch_name: string;
+        start_node: string;
+        end_node: string;
+        description: string;
+        trigger_condition: string;
+    }>;
+    success_criteria: string;
+    failure_criteria: string;
+}
+export interface RiskAssessmentPuzzle {
+    overall_risk_level: "low" | "medium" | "high" | "critical";
+    identified_risks: Array<{
+        rule_id: string;
+        name: string;
+        severity: string;
+        mitigation: string;
+    }>;
+    mitigation_strategy: string;
+    environment_readiness: {
+        permission_published: boolean;
+        guards_published: boolean;
+        arbitration_published: boolean;
+        reward_published: boolean;
+        testnet_tested: boolean;
+    };
+}
+export interface EnvironmentInfo {
+    network: "testnet" | "mainnet";
+    testnet_test_passed: boolean;
+    backup_created: boolean;
+    gas_estimation?: number;
+    user_address?: string;
+}
+export interface MachinePuzzle {
+    version: string;
+    business_flow: BusinessFlowPuzzle;
+    node_design: NodeDesignPuzzle;
+    guard_acceptance: GuardAcceptancePuzzle;
+    permission_model: PermissionModelPuzzle;
+    threshold_weight: ThresholdWeightPuzzle;
+    branch_topology: BranchTopologyPuzzle;
+    overall_objective: OverallObjectivePuzzle;
+    risk_assessment: RiskAssessmentPuzzle;
+    environment?: EnvironmentInfo;
+}
+export declare function initPuzzleFromIntent(intent: string): MachinePuzzle;
+export declare function initPuzzleFromTemplate(templateId: string): MachinePuzzle | undefined;
+export type MachineJsonInput = {
+    name?: string;
+    nodes: MachineNode[];
+    pairs: MachinePair[];
+    scene_id?: string;
+    template_id?: string;
+};
+export declare function initPuzzleFromMachineId(machineId: string, machineJson: MachineJsonInput): MachinePuzzle;
+export declare function initPuzzleFromFragments(fragments: MachineJsonInput[]): MachinePuzzle;
+export declare function initPuzzleForCrossChain(machineBId: string, machineBJson?: MachineJsonInput): MachinePuzzle;
+export declare function initPuzzleForForkModify(machineId: string, machineJson: MachineJsonInput): MachinePuzzle;
+export type PuzzleDimension = "A_business_flow" | "B_node_design" | "C_guard_acceptance" | "D_permission_model" | "E_threshold_weight" | "F_branch_topology" | "G_overall_objective" | "H_risk_assessment";
+export interface PuzzleCompleteness {
+    complete: boolean;
+    dimensions: Array<{
+        dimension: PuzzleDimension;
+        complete: boolean;
+        missing_fields: string[];
+    }>;
+    next_step: string;
+}
+export declare function checkPuzzleCompleteness(puzzle: MachinePuzzle): PuzzleCompleteness;
+export declare function recommendNextStep(puzzle: MachinePuzzle): string;
+export declare function derivePuzzleFromMachineJson(machine: MachineJsonInput): MachinePuzzle;
+export declare function generateConfirmationText(puzzle: MachinePuzzle): string;
+export declare const MACHINE_PUZZLE_VERSION = "1.0.0";