@wowok/agent-mcp 2.4.3 → 2.5.0

package/dist/knowledge/machine-translation.js

@@ -0,0 +1,513 @@
+export const SEMANTIC_TO_MACHINE_RULES = [
+    {
+        id: "P-M-SEQ",
+        pattern_name: "Sequential Execution",
+        category: "execution",
+        semantic_intent: "Single actor advances workflow one step at a time. Each Pair has threshold=1 with a single Forward weight=1.",
+        match_keywords: ["sequential", "linear", "one step at a time"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: "dynamic",
+            structure: "Each Pair: { threshold: 1, forwards: [{ name, weight: 1, namedOperator | permissionIndex }] }",
+        },
+        constraints: [
+            "Each Forward must have at least one of namedOperator or permissionIndex",
+            "weight > 0 (typically 1)",
+            "prev_node references must form a valid DAG (no cycles)",
+        ],
+        example: {
+            pair: {
+                prev_node: "NodeA",
+                next_node: "NodeB",
+                threshold: 1,
+                forwards: [{ name: "Advance", weight: 1, named_operator: "" }],
+            },
+        },
+    },
+    {
+        id: "P-M-AND",
+        pattern_name: "Parallel AND (Dual-Signature Consensus)",
+        category: "execution",
+        semantic_intent: "Multiple parties must ALL contribute to advance. Pair threshold=N with N Forwards (weight=1 each). All must execute.",
+        match_keywords: ["and", "all", "dual-sig", "both confirm", "both must"],
+        schema_elements: {
+            threshold: 2,
+            forward_count: 2,
+            permission_model: "mixed",
+            pair_count: 1,
+            structure: "Pair: { threshold: N, forwards: [{ weight: 1, namedOperator: '' }, { weight: 1, permissionIndex: 2 }] }",
+        },
+        constraints: [
+            "threshold must equal the number of required Forwards",
+            "Each Forward must have a distinct permission model (no two identical)",
+            "If either party fails to sign, workflow stalls — consider adding timeout Guard",
+            "Each Forward counted once per session (repeated execution adds no weight)",
+        ],
+        example: {
+            pair: {
+                prev_node: "Initiated",
+                next_node: "Approved",
+                threshold: 2,
+                forwards: [
+                    { name: "CustomerApprove", weight: 1, named_operator: "" },
+                    { name: "MerchantApprove", weight: 1, permission_index: 2 },
+                ],
+            },
+        },
+    },
+    {
+        id: "P-M-OR",
+        pattern_name: "Parallel OR (Any-One Execution)",
+        category: "execution",
+        semantic_intent: "Any one of multiple paths can advance the workflow. Multiple Pairs, each threshold=1.",
+        match_keywords: ["or", "any", "either"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: "dynamic",
+            structure: "Multiple Pairs from same prev_node, each with threshold=1",
+        },
+        constraints: [
+            "Distinct next_node for each Pair (or distinct Forward)",
+            "If targets are different nodes, this becomes COMPETING topology",
+            "If targets are same node, alternative paths converge (FORKMERGE)",
+        ],
+        example: {
+            pairs: [
+                {
+                    prev_node: "Choice",
+                    next_node: "PathA",
+                    threshold: 1,
+                    forwards: [{ name: "ChooseA", weight: 1, named_operator: "" }],
+                },
+                {
+                    prev_node: "Choice",
+                    next_node: "PathB",
+                    threshold: 1,
+                    forwards: [{ name: "ChooseB", weight: 1, named_operator: "" }],
+                },
+            ],
+        },
+    },
+    {
+        id: "P-M-VOTE",
+        pattern_name: "Weighted Voting",
+        category: "execution",
+        semantic_intent: "Multiple parties vote with unequal weights. threshold=100, varied weights (e.g. 60+40). " +
+            "Guard extracts weight dynamically from Arbitration object.",
+        match_keywords: ["vote", "weight", "stakeholder"],
+        schema_elements: {
+            threshold: 100,
+            forward_count: "dynamic",
+            permission_model: "mixed",
+            pair_count: 1,
+            structure: "Pair: { threshold: 100, forwards: [{ weight: 60, permissionIndex: 2, guard: arb_voting_guard }, { weight: 8, namedOperator: 'member', guard: arb_voting_guard }] }",
+        },
+        constraints: [
+            "Guard MUST check arb.voted has [Signer] to prevent double-voting (R-X1-14 CRITICAL)",
+            "Weight is query-derived from Arbitration object (not hardcoded in Forward)",
+            "Competing Pair often added: Approved vs Rejected (timeout) — first-wins",
+            "Forward weight field is just session counter; actual weight from Guard",
+        ],
+        example: {
+            pair: {
+                prev_node: "Voting",
+                next_node: "Approved",
+                threshold: 100,
+                forwards: [
+                    { name: "ChiefVote", weight: 60, permission_index: 2, guard: "arb_voting_guard" },
+                    { name: "MemberVote", weight: 8, named_operator: "member", guard: "arb_voting_guard" },
+                ],
+            },
+        },
+    },
+    {
+        id: "P-M-HYBRID",
+        pattern_name: "Hybrid Mode (Key Party Required + Others Optional)",
+        category: "execution",
+        semantic_intent: "One key party must contribute, others are optional. threshold=5 with mixed weights (3+1+1).",
+        match_keywords: ["hybrid", "mixed", "key party"],
+        schema_elements: {
+            threshold: 5,
+            forward_count: 3,
+            permission_model: "mixed",
+            pair_count: 1,
+            structure: "Pair: { threshold: 5, forwards: [{ weight: 3, permissionIndex: 2 (key) }, { weight: 1, namedOperator: 'role1' }, { weight: 1, namedOperator: 'role2' }] }",
+        },
+        constraints: [
+            "Key party's weight must alone be insufficient (otherwise optional parties are meaningless)",
+            "Total weight of all Forwards must be >= threshold",
+            "Each Forward must have distinct permission model",
+        ],
+        example: {
+            pair: {
+                prev_node: "Review",
+                next_node: "Approved",
+                threshold: 5,
+                forwards: [
+                    { name: "ManagerApprove", weight: 3, permission_index: 2 },
+                    { name: "EngineerApprove", weight: 1, named_operator: "engineer" },
+                    { name: "QAApprove", weight: 1, named_operator: "qa" },
+                ],
+            },
+        },
+    },
+    {
+        id: "P-M-LINEAR",
+        pattern_name: "Linear Flow (No Branches)",
+        category: "topology",
+        semantic_intent: "Workflow progresses in a straight line with no branches.",
+        match_keywords: ["linear", "straight", "no branches"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: "dynamic",
+            structure: "Chain of Pairs: A->B->C->D->...->Terminal",
+        },
+        constraints: [
+            "Exactly one entry Pair (prev_node='')",
+            "Exactly one terminal node (no outgoing Pairs)",
+            "Each non-terminal node has exactly one outgoing Pair",
+        ],
+        example: {
+            topology: "Entry -> A -> B -> C -> Terminal",
+        },
+    },
+    {
+        id: "P-M-FORKMERGE",
+        pattern_name: "Fork-Merge (Parallel Branches Converging)",
+        category: "topology",
+        semantic_intent: "Main flow forks into multiple parallel branches, then merges back to main flow.",
+        match_keywords: ["fork", "merge", "parallel"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: "dynamic",
+            permission_model: "mixed",
+            pair_count: "dynamic",
+            structure: "ForkNode -> {BranchA, BranchB} -> MergeNode",
+        },
+        constraints: [
+            "Multiple Pairs from ForkNode (one per branch)",
+            "All branches must eventually reach MergeNode",
+            "MergeNode has multiple incoming Pairs (merge point)",
+            "Threshold at MergeNode determines if all branches must complete or just some",
+        ],
+        example: {
+            topology: "ForkNode -> BranchA -> MergeNode; ForkNode -> BranchB -> MergeNode",
+        },
+    },
+    {
+        id: "P-M-COMPETING",
+        pattern_name: "Competing Pairs (Mutually Exclusive Branches)",
+        category: "topology",
+        semantic_intent: "Multiple Pairs from same node compete; first Pair to meet threshold wins, others abandoned.",
+        match_keywords: ["competing", "exclusive", "race"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: "dynamic",
+            structure: "Same prev_node -> multiple next_nodes (each Pair independent)",
+        },
+        constraints: [
+            "Mutually exclusive — only one Pair can complete per session",
+            "First Pair to reach threshold wins",
+            "Other incomplete Pairs are abandoned",
+            "Verify no dead branches (a Pair that always loses to another)",
+        ],
+        example: {
+            topology: "Shipped -> Received; Shipped -> Lost; Shipped -> Return (first wins)",
+        },
+    },
+    {
+        id: "P-M-PERM-SINGLE",
+        pattern_name: "Single Permission",
+        category: "permission",
+        semantic_intent: "Forward uses only one permission type: namedOperator OR permissionIndex.",
+        match_keywords: ["single permission"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: 1,
+            structure: "Forward: { name, weight: 1, namedOperator: '<role>' | permissionIndex: <index> } (only one set)",
+        },
+        constraints: [
+            "Either namedOperator or permissionIndex is set (not both)",
+            "Empty namedOperator='' grants OrderHolder (order owner + agents)",
+        ],
+        example: {
+            forward: { name: "Ship", weight: 1, permission_index: 2 },
+        },
+    },
+    {
+        id: "P-M-PERM-MIXED",
+        pattern_name: "Mixed Permission (Either-Or)",
+        category: "permission",
+        semantic_intent: "Forward allows EITHER permission to execute (internal staff OR external roles).",
+        match_keywords: ["mixed permission", "either"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "mixed",
+            pair_count: 1,
+            structure: "Forward: { name, weight: 1, namedOperator: '<role>', permissionIndex: <index> } (both set)",
+        },
+        constraints: [
+            "Both namedOperator and permissionIndex are set",
+            "Executor needs EITHER permission — passing either check is sufficient",
+            "Use case: allow internal staff OR external role to execute the same Forward",
+        ],
+        example: {
+            forward: { name: "Confirm", weight: 1, named_operator: "auditor", permission_index: 2 },
+        },
+    },
+    {
+        id: "P-M-CROSS-MACHINE",
+        pattern_name: "Cross-Machine Dependency",
+        category: "integration",
+        semantic_intent: "Machine B's Forward Guard queries Machine A's Progress to verify upstream completion.",
+        match_keywords: ["cross-machine", "supply chain", "upstream"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: 1,
+            structure: "Forward: { guard: 'upstream_progress_guard', retained_submission: 'upstream_progress_id' }",
+        },
+        constraints: [
+            "Machine A MUST be published before Machine B (dependency order)",
+            "Guard uses convert_witness=100 to convert submitted Order/Progress ID into queryable Progress",
+            "Cross-Machine dependency is one-way (no cycles)",
+            "Dependency verification: indirect via progress::new -> assert_published (see 06 §14.6)",
+            "retained_submission stores upstream Progress ID for audit",
+        ],
+        example: {
+            forward: {
+                name: "VerifyUpstream",
+                weight: 1,
+                permission_index: 2,
+                guard: "upstream_progress_guard",
+                retained_submission: "upstream_progress_id",
+            },
+        },
+    },
+    {
+        id: "P-M-ALLOCATION-INTEGRATED",
+        pattern_name: "Allocation-Integrated Terminal",
+        category: "integration",
+        semantic_intent: "Terminal node triggers Allocator to distribute funds. Allocation independent of Machine flow.",
+        match_keywords: ["allocation", "fund distribution", "terminal"],
+        schema_elements: {
+            threshold: 1,
+            forward_count: 1,
+            permission_model: "single",
+            pair_count: 1,
+            structure: "Terminal node -> Allocator entry (configured on Service order_allocators)",
+        },
+        constraints: [
+            "Terminal node must be referenced in Service order_allocators",
+            "Allocator Guard verifies progress.current == terminal_node_name",
+            "sharing.who determines fund recipient (Entity / OrderHolder / etc.)",
+            "Multiple Allocators can fire on different terminal nodes",
+        ],
+        example: {
+            terminal_node: "Complete",
+            allocator: { trigger_node: "Complete", sharing_who: "Entity", recipient: "merchant_treasury" },
+        },
+    },
+];
+export const NODE_FIELD_EXPLANATIONS = [
+    { field: "name", type: "string", required: true, semantic: "Node name (unique identifier)", constraint: "<=64 BCS bytes, globally unique" },
+    { field: "description", type: "string", required: false, semantic: "Human-readable description", constraint: "<=MAX_DESCRIPTION_LENGTH" },
+    { field: "b_pause", type: "boolean", required: false, semantic: "Whether node is paused (blocks execution)", constraint: "Default false" },
+    { field: "b_submission", type: "boolean", required: false, semantic: "Whether submission is allowed at this node", constraint: "Used for retained_submission storage" },
+];
+export const PAIR_FIELD_EXPLANATIONS = [
+    { field: "prev_node", type: "string", required: true, semantic: "Source node (empty '' = entry point)", constraint: "Must reference existing node or ''" },
+    { field: "next_node", type: "string", required: true, semantic: "Target node", constraint: "Must reference existing node" },
+    { field: "threshold", type: "number", required: true, semantic: "Required total forward weight to advance", constraint: ">=0, typically 1-100" },
+    { field: "forwards", type: "array<Forward>", required: true, semantic: "List of Forwards in this Pair", constraint: "1-20 Forwards per Pair" },
+];
+export const FORWARD_FIELD_EXPLANATIONS = [
+    { field: "name", type: "string", required: true, semantic: "Forward name (unique within Pair)", constraint: "<=64 BCS bytes, unique within Pair" },
+    { field: "weight", type: "number", required: true, semantic: "Weight contribution to threshold", constraint: ">0, typically 1-100" },
+    { field: "namedOperator", type: "string (optional)", required: false, semantic: "Named operator role ('' = OrderHolder)", constraint: "Optional, but Forward needs at least one permission" },
+    { field: "permissionIndex", type: "number (optional)", required: false, semantic: "Permission index (custom or builtin)", constraint: "< Permission.indices.length" },
+    { field: "guard", type: "address (optional)", required: false, semantic: "Guard object address for validation", constraint: "Must be CREATE-only Guard, already created" },
+    { field: "retained_submission", type: "string (optional)", required: false, semantic: "Key for storing submitted values in history", constraint: "Uniquely located by (current_node, next_node, forward_name)" },
+];
+export function identifyExecutionMode(pair) {
+    const { threshold, forwards } = pair;
+    const fwdCount = forwards.length;
+    if (threshold === 1 && fwdCount === 1) {
+        return "P-M-SEQ (Sequential)";
+    }
+    if (threshold === fwdCount && fwdCount >= 2) {
+        const hasMixed = forwards.some((f) => f.permission_index !== undefined) &&
+            forwards.some((f) => f.named_operator !== undefined);
+        return hasMixed ? "P-M-AND (Parallel AND / Dual-Signature)" : "P-M-AND (Parallel AND)";
+    }
+    if (threshold === 100 && forwards.some((f) => f.weight < 50 && f.weight > 0)) {
+        return "P-M-VOTE (Weighted Voting)";
+    }
+    if (threshold < fwdCount && threshold > 1) {
+        return "P-M-HYBRID (Hybrid Mode)";
+    }
+    if (threshold === 1 && fwdCount >= 1) {
+        return "P-M-OR (Parallel OR) or P-M-SEQ (if single Forward)";
+    }
+    return "Unknown (manual review needed)";
+}
+export function identifyTopology(pairs) {
+    const fromNode = new Map();
+    const toNode = new Map();
+    for (const p of pairs) {
+        if (!fromNode.has(p.prev_node))
+            fromNode.set(p.prev_node, []);
+        fromNode.get(p.prev_node).push(p.next_node);
+        if (!toNode.has(p.next_node))
+            toNode.set(p.next_node, []);
+        toNode.get(p.next_node).push(p.prev_node);
+    }
+    for (const [prev, nexts] of fromNode) {
+        if (nexts.length > 1 && prev !== "") {
+            return "P-M-COMPETING (Competing Pairs)";
+        }
+    }
+    for (const [next, prevs] of toNode) {
+        if (prevs.length > 1) {
+            return "P-M-FORKMERGE (Fork-Merge)";
+        }
+    }
+    return "P-M-LINEAR (Linear Flow)";
+}
+export function matchSemanticPattern(intent) {
+    const lower = intent.toLowerCase();
+    return SEMANTIC_TO_MACHINE_RULES.find((rule) => rule.match_keywords.some((kw) => lower.includes(kw.toLowerCase())));
+}
+export function explainForwardPermission(forward) {
+    const hasNamed = forward.named_operator !== undefined && forward.named_operator !== null;
+    const hasPerm = forward.permission_index !== undefined && forward.permission_index !== null;
+    if (hasNamed && hasPerm) {
+        const role = forward.named_operator === "" ? "OrderHolder" : `role "${forward.named_operator}"`;
+        return `Mixed permission: ${role} OR Permission index ${forward.permission_index} (either sufficient)`;
+    }
+    if (hasNamed) {
+        if (forward.named_operator === "") {
+            return "OrderHolder (order owner + agents)";
+        }
+        return `NamedOperator role "${forward.named_operator}"`;
+    }
+    if (hasPerm) {
+        return `Permission index ${forward.permission_index}`;
+    }
+    return "❌ INVALID: no permission set (Forward must have at least one of namedOperator or permissionIndex)";
+}
+export const MACHINE_CONSTRAINT_RULES = [
+    { id: "MC-C-01", name: `Node count <= ${MAX_NODE_COUNT}`, description: "MAX_NODE_COUNT", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-02", name: `Pair count per node <= ${MAX_NODE_PAIR_COUNT}`, description: "MAX_NODE_PAIR_COUNT", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-03", name: `Forward count per Pair <= ${MAX_FORWARD_COUNT}`, description: "MAX_FORWARD_COUNT", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-04", name: "Node name unique", description: "name globally unique", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-05", name: "Forward name unique within Pair", description: "name unique within Pair", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-06", name: "Node name <= 64 BCS bytes", description: "MAX_NAME_LENGTH", category: "creation", verification_location: "common.ts", on_chain_enforced: true },
+    { id: "MC-C-07", name: "Forward has at least one permission", description: "namedOperator or permissionIndex", category: "creation", verification_location: "wowok-machine SKILL", on_chain_enforced: false },
+    { id: "MC-C-08", name: "permissionIndex valid", description: "< Permission.indices.length", category: "creation", verification_location: "permission.move", on_chain_enforced: true },
+    { id: "MC-C-09", name: "Guard already created", description: "guard field references existing Guard", category: "creation", verification_location: "guard.move", on_chain_enforced: true },
+    { id: "MC-C-10", name: "Guard immutable", description: "Guard.b_immutable == true", category: "creation", verification_location: "guard.move", on_chain_enforced: true },
+    { id: "MC-C-11", name: "retained_submission index valid", description: "Corresponds to Guard table b_submission=true", category: "creation", verification_location: "guard.move", on_chain_enforced: true },
+    { id: "MC-C-12", name: "prev_node references valid", description: "Points to existing node or ''", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-13", name: "threshold >= 0", description: "Non-negative", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-14", name: "weight > 0", description: "Positive", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-15", name: "description length", description: "<= MAX_DESCRIPTION_LENGTH", category: "creation", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-C-16", name: "bReplace scope", description: "Acts on existing node's pairs list, not whole Machine", category: "node_operation", verification_location: "machine.move:405-443", on_chain_enforced: true },
+    { id: "MC-C-17", name: "bReplace=false merge semantics", description: "Incremental merge by prev_node into existing pairs", category: "node_operation", verification_location: "machine.move:418-443", on_chain_enforced: true },
+    { id: "MC-C-18", name: "Non-existing node append", description: "push_back new node (no clear triggered)", category: "node_operation", verification_location: "machine.move:418-443", on_chain_enforced: true },
+    { id: "MC-C-19", name: "Full node replacement via file entry", description: "NodeJsonOrMarkdownFileSchema (not bReplace=true)", category: "node_operation", verification_location: "machine.ts:93-112", on_chain_enforced: false },
+    { id: "MC-S-01", name: "At least one entry point", description: "Pair with prev_node=''", category: "structure", verification_location: "machine-topology.ts", on_chain_enforced: false },
+    { id: "MC-S-02", name: "At least one terminal", description: "Node with no outgoing Pairs", category: "structure", verification_location: "machine-topology.ts", on_chain_enforced: false },
+    { id: "MC-S-03", name: "No orphaned nodes", description: "All non-entry nodes have incoming Pair", category: "structure", verification_location: "machine-topology.ts", on_chain_enforced: false },
+    { id: "MC-S-04", name: "No dead branches", description: "All thresholds achievable", category: "structure", verification_location: "machine-topology.ts", on_chain_enforced: false },
+    { id: "MC-S-05", name: "DAG acyclic", description: "No cycle references", category: "structure", verification_location: "machine-topology.ts", on_chain_enforced: false },
+    { id: "MC-P-01", name: "All Guards tested", description: "gen_passport passed", category: "publish", verification_location: "machine-confirm.ts", on_chain_enforced: false },
+    { id: "MC-P-02", name: "Backup exported", description: "machineNode2file executed", category: "publish", verification_location: "machine-confirm.ts", on_chain_enforced: false },
+    { id: "MC-P-03", name: "Testnet verified", description: "(recommended) testnet passed", category: "publish", verification_location: "machine-confirm.ts", on_chain_enforced: false },
+    { id: "MC-P-04", name: "User 100% confirmed", description: "ConfirmGate passed", category: "publish", verification_location: "machine-confirm.ts", on_chain_enforced: false },
+    { id: "MC-P-05", name: "Service created (if bound)", description: "Service exists", category: "publish", verification_location: "machine-context.ts", on_chain_enforced: false },
+    { id: "MC-R-01", name: "Node ops fail after publish", description: "E_ALREADY_PUBLISHED", category: "runtime", verification_location: "machine.move", on_chain_enforced: true },
+    { id: "MC-R-02", name: "Session accumulation correct", description: "weight accumulation logic", category: "runtime", verification_location: "progress.move", on_chain_enforced: true },
+    { id: "MC-R-03", name: "Competing Pair first-wins", description: "First Pair to reach threshold wins", category: "runtime", verification_location: "progress.move", on_chain_enforced: true },
+];
+export function getConstraintsByCategory(category) {
+    return MACHINE_CONSTRAINT_RULES.filter((r) => r.category === category);
+}
+export function getConstraintById(id) {
+    return MACHINE_CONSTRAINT_RULES.find((r) => r.id === id);
+}
+export function getOnChainConstraints() {
+    return MACHINE_CONSTRAINT_RULES.filter((r) => r.on_chain_enforced);
+}
+export function getOffChainConstraints() {
+    return MACHINE_CONSTRAINT_RULES.filter((r) => !r.on_chain_enforced);
+}
+export const MACHINE_TRANSLATION_VERSION = "1.0.0";
+export const MACHINE_PATTERNS_COUNT = SEMANTIC_TO_MACHINE_RULES.length;
+export const MACHINE_CONSTRAINTS_COUNT = MACHINE_CONSTRAINT_RULES.length;
+import { MAX_NODE_COUNT, MAX_NODE_PAIR_COUNT, MAX_FORWARD_COUNT, } from "./onchain-constants.js";
+export function identifyNodeRole(node) {
+    const allPairs = node.all_pairs ?? [];
+    const outgoing = (node.pairs ?? allPairs).filter((p) => p.prev_node === node.name);
+    const incoming = allPairs.filter((p) => p.next_node === node.name);
+    const isEntry = allPairs.some((p) => p.prev_node === "" && p.next_node === node.name);
+    const isTerminal = outgoing.length === 0;
+    if (isEntry)
+        return "entry";
+    if (isTerminal)
+        return "terminal";
+    const nextNodes = new Set(outgoing.map((p) => p.next_node));
+    if (nextNodes.size > 1)
+        return "branch";
+    const prevNodes = new Set(incoming.map((p) => p.prev_node).filter((n) => n !== ""));
+    if (prevNodes.size > 1)
+        return "merge";
+    return "normal";
+}
+function explainGuardBinding(guardAddress) {
+    return {
+        address: guardAddress,
+        immutable_required: true,
+        note: `Guard ${guardAddress} validates this Forward's execution; ` +
+            `must be immutable (b_immutable=true) and pre-created on-chain.`,
+    };
+}
+export function explainNode(node) {
+    const outgoingPairs = node.pairs ?? [];
+    return {
+        name: node.name,
+        role: identifyNodeRole(node),
+        pairs: outgoingPairs.map((p) => explainPair(p)),
+        description: node.description,
+    };
+}
+export function explainPair(pair) {
+    return {
+        prev_node: pair.prev_node,
+        next_node: pair.next_node,
+        threshold: pair.threshold,
+        execution_pattern: identifyExecutionMode(pair),
+        forwards: pair.forwards.map((f) => explainForward(f)),
+    };
+}
+export function explainForward(forward) {
+    return {
+        name: forward.name,
+        permission: explainForwardPermission(forward),
+        weight: forward.weight,
+        guard: forward.guard ? explainGuardBinding(forward.guard) : null,
+        retained_submission: forward.retained_submission ?? null,
+    };
+}

package/dist/knowledge/mcp-schema-audit-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/mcp-schema-audit-cli.js

@@ -0,0 +1,45 @@
+import { scanAllMcpSchemas, formatAuditReport, MCP_SCHEMA_AUDIT_VERSION } from './mcp-schema-audit.js';
+import * as fs from 'fs';
+import * as path from 'path';
+console.log(`MCP Schema Audit v${MCP_SCHEMA_AUDIT_VERSION}`);
+console.log('Auditing 4 layers: ts-sdk → Zod → Generated → Deployed ...');
+const result = scanAllMcpSchemas();
+console.log(`\nAudited ${result.census.length} tools, found ${result.total_findings} findings.`);
+console.log(`  Stubs: ${result.stub_count}, Full schemas: ${result.full_schema_count}`);
+console.log(`  any/unknown: ${result.any_unknown_instances.length} total (${result.fixable_any_count} fixable, ${result.legitimate_any_count} legitimate)`);
+const report = formatAuditReport(result);
+const outputPath = path.resolve('d:/wowok/wiki/market/GLM3/mcp-schema-audit-report.md');
+fs.writeFileSync(outputPath, report, 'utf-8');
+console.log(`\nReport written to ${outputPath}`);
+console.log('\n=== Per-Tool Census ===');
+console.log('Tool'.padEnd(28) + 'L3-Input'.padEnd(14) + 'L3-Output'.padEnd(14) + 'L4-Status'.padEnd(14) + 'L4-Props');
+for (const c of result.census) {
+    const l3i = c.layer3_generated.input_exists ? `${(c.layer3_generated.input_size_bytes / 1024).toFixed(1)}KB` : 'MISSING';
+    const l3o = c.layer3_generated.output_exists ? `${(c.layer3_generated.output_size_bytes / 1024).toFixed(1)}KB` : 'MISSING';
+    const l4s = !c.layer4_deployed.file_exists ? 'MISSING' : c.layer4_deployed.is_stub ? 'STUB' : 'FULL';
+    console.log(c.name.padEnd(28) +
+        l3i.padEnd(14) +
+        l3o.padEnd(14) +
+        l4s.padEnd(14) +
+        c.layer4_deployed.properties_count);
+}
+console.log('\n=== Findings by Severity ===');
+for (const sev of ['critical', 'high', 'medium', 'low', 'info']) {
+    const arr = result.findings_by_severity.get(sev) ?? [];
+    if (arr.length > 0)
+        console.log(`  ${sev.padEnd(10)} ${arr.length}`);
+}
+console.log('\n=== Findings by Category ===');
+for (const cat of ['stub_inconsistency', 'layer_parity', 'handler_types', 'output_coverage', 'generation_sync', 'reflection']) {
+    const arr = result.findings_by_category.get(cat) ?? [];
+    if (arr.length > 0)
+        console.log(`  ${cat.padEnd(22)} ${arr.length}`);
+}
+console.log('\n=== any/unknown by Pattern ===');
+const patternGroups = new Map();
+for (const inst of result.any_unknown_instances) {
+    patternGroups.set(inst.pattern, (patternGroups.get(inst.pattern) ?? 0) + 1);
+}
+for (const [pattern, count] of [...patternGroups.entries()].sort((a, b) => b[1] - a[1])) {
+    console.log(`  ${pattern.padEnd(24)} ${count}`);
+}

package/dist/knowledge/mcp-schema-audit.d.ts

@@ -0,0 +1,90 @@
+export declare const DEPLOYED_TOOLS_DIR = "c:\\Users\\zhou\\.trae-cn\\mcps\\s_wowok-7838e181\\solo_agent\\mcp_wagent\\tools";
+export declare const GENERATED_SCHEMAS_DIR = "d:\\wowok\\agent\\mcp\\dist\\schemas";
+export declare const MCP_SRC_SCHEMA_DIR = "d:\\wowok\\agent\\mcp\\src\\schema";
+export declare const MCP_SRC_TOOLS_DIR = "d:\\wowok\\agent\\mcp\\src\\tools";
+export declare const GENERATION_SCRIPT = "d:\\wowok\\agent\\mcp\\scripts\\generate-json-schemas.ts";
+export declare const TOOLS_INDEX_FILE = "d:\\wowok\\agent\\mcp\\src\\tools\\index.ts";
+export declare const MCP_SCHEMA_AUDIT_VERSION = "1.0.0";
+export interface ToolDescriptor {
+    name: string;
+    input_schema_export: string;
+    output_schema_export: string | null;
+}
+export declare const TOOLS_17: readonly ToolDescriptor[];
+export type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export type FindingCategory = 'layer_census' | 'stub_inconsistency' | 'layer_parity' | 'any_unknown' | 'handler_types' | 'output_coverage' | 'generation_sync' | 'reflection';
+export interface Finding {
+    rule_id: string;
+    severity: FindingSeverity;
+    category: FindingCategory;
+    tool_name: string;
+    description: string;
+    location?: string;
+    fix?: string;
+}
+export interface LayerCensus {
+    name: string;
+    layer2_zod: {
+        input_schema_export: string;
+        output_schema_export: string | null;
+        schema_dir: string;
+    };
+    layer3_generated: {
+        input_schema_file: string;
+        output_schema_file: string;
+        input_exists: boolean;
+        output_exists: boolean;
+        input_size_bytes: number;
+        output_size_bytes: number;
+    };
+    layer4_deployed: {
+        tool_descriptor_file: string;
+        file_exists: boolean;
+        is_stub: boolean;
+        properties_count: number;
+        required_count: number;
+        has_schema_hint: boolean;
+        has_additional_properties_false: boolean;
+        has_dollar_schema: boolean;
+        has_oneof: boolean;
+        has_anyof: boolean;
+        has_allof: boolean;
+        union_count: number;
+    };
+}
+export type AnyUnknownPattern = 'z.any()' | 'z.unknown()' | 'args: any' | 'Promise<any>' | 'Record<string, any>' | 'as any' | ': any' | '<any>';
+export type AnyUnknownCategory = 'fixable' | 'legitimate' | 'external';
+export interface AnyUnknownInstance {
+    file: string;
+    line: number;
+    code: string;
+    pattern: AnyUnknownPattern;
+    category: AnyUnknownCategory;
+    reason: string;
+    fix_suggestion?: string;
+}
+export interface ScanResult {
+    census: LayerCensus[];
+    findings: Finding[];
+    any_unknown_instances: AnyUnknownInstance[];
+    findings_by_severity: Map<FindingSeverity, Finding[]>;
+    findings_by_category: Map<FindingCategory, Finding[]>;
+    total_findings: number;
+    fixable_any_count: number;
+    legitimate_any_count: number;
+    external_any_count: number;
+    stub_count: number;
+    full_schema_count: number;
+}
+export declare function loadLayer4Deployed(toolName: string): LayerCensus['layer4_deployed'] | null;
+export declare function loadLayer3Generated(toolName: string): LayerCensus['layer3_generated'];
+export declare function analyzeLayerCensus(): LayerCensus[];
+export declare function analyzeDeployedStubInconsistency(census: LayerCensus[]): Finding[];
+export declare function analyzeLayerParity(census: LayerCensus[]): Finding[];
+export declare function analyzeAnyUnknownCensus(): AnyUnknownInstance[];
+export declare function analyzeHandlerTypeSafety(instances: AnyUnknownInstance[]): Finding[];
+export declare function analyzeOutputSchemaCoverage(census: LayerCensus[]): Finding[];
+export declare function analyzeGenerationScriptSync(): Finding[];
+export declare function analyzeSchemaQueryReflection(census: LayerCensus[]): Finding[];
+export declare function scanAllMcpSchemas(): ScanResult;
+export declare function formatAuditReport(result: ScanResult): string;