@wowok/agent-mcp 2.4.3 → 2.5.0

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

@@ -0,0 +1,57 @@
+export interface MachineNode {
+    name: string;
+    description?: string;
+}
+export interface MachineForward {
+    name: string;
+    weight: number;
+    named_operator?: string;
+    permission_index?: number;
+    guard?: string;
+    retained_submission?: string | string[] | number[];
+}
+export interface MachinePair {
+    prev_node: string;
+    next_node: string;
+    threshold: number;
+    forwards: MachineForward[];
+}
+export interface MachineTopology {
+    entry_nodes: string[];
+    terminal_nodes: string[];
+    orphaned_nodes: string[];
+    dead_end_nodes: string[];
+    dead_branches: DeadBranch[];
+    has_cycles: boolean;
+    cycle_nodes: string[][];
+    reachability: Map<string, Set<string>>;
+    node_count: number;
+    pair_count: number;
+    forward_count: number;
+    within_limits: {
+        max_node_count: boolean;
+        max_node_pair_count: boolean;
+        max_forward_count: boolean;
+        max_forward_order_count: boolean;
+    };
+}
+export interface DeadBranch {
+    pair: {
+        prev_node: string;
+        next_node: string;
+    };
+    reason: string;
+    competing_with: string[];
+}
+import { MAX_NODE_COUNT, MAX_NODE_PAIR_COUNT, MAX_FORWARD_COUNT, MAX_FORWARD_ORDER_COUNT } from "./onchain-constants.js";
+export { MAX_NODE_COUNT, MAX_NODE_PAIR_COUNT, MAX_FORWARD_COUNT, MAX_FORWARD_ORDER_COUNT, };
+export declare function analyzeTopology(nodes: MachineNode[], pairs: MachinePair[]): MachineTopology;
+export declare function detectCycle(nodes: MachineNode[], pairs: MachinePair[]): {
+    has_cycles: boolean;
+    cycle_nodes: string[][];
+};
+export declare function isReachableFromEntry(node: string, topology: MachineTopology): boolean;
+export declare function getNodesReachingTerminals(topology: MachineTopology): Set<string>;
+export declare function formatTopologySummary(topology: MachineTopology): string;
+export declare function identifyTopologyPattern(pairs: MachinePair[]): string;
+export declare const MACHINE_TOPOLOGY_VERSION = "1.0.0";

package/dist/knowledge/machine-topology.js

@@ -0,0 +1,234 @@
+import { MAX_NODE_COUNT, MAX_NODE_PAIR_COUNT, MAX_FORWARD_COUNT, MAX_FORWARD_ORDER_COUNT, } from "./onchain-constants.js";
+export { MAX_NODE_COUNT, MAX_NODE_PAIR_COUNT, MAX_FORWARD_COUNT, MAX_FORWARD_ORDER_COUNT, };
+export function analyzeTopology(nodes, pairs) {
+    const nodeNames = nodes.map((n) => n.name);
+    const nodeSet = new Set(nodeNames);
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const name of nodeNames) {
+        outgoing.set(name, []);
+        incoming.set(name, []);
+    }
+    for (const pair of pairs) {
+        if (!outgoing.has(pair.prev_node) && pair.prev_node !== "") {
+            outgoing.set(pair.prev_node, []);
+        }
+        if (!incoming.has(pair.next_node)) {
+            incoming.set(pair.next_node, []);
+        }
+        if (pair.prev_node !== "") {
+            outgoing.get(pair.prev_node).push(pair.next_node);
+        }
+        incoming.get(pair.next_node).push(pair.prev_node);
+    }
+    const entry_nodes = pairs
+        .filter((p) => p.prev_node === "")
+        .map((p) => p.next_node)
+        .filter((n) => nodeSet.has(n));
+    const terminal_nodes = nodeNames.filter((n) => (outgoing.get(n) || []).length === 0);
+    const orphaned_nodes = nodeNames.filter((n) => !entry_nodes.includes(n) && (incoming.get(n) || []).length === 0);
+    const dead_end_nodes = nodeNames.filter((n) => (outgoing.get(n) || []).length === 0 && !terminal_nodes.includes(n));
+    const { has_cycles, cycle_nodes } = detectCycles(nodeNames, pairs);
+    const dead_branches = analyzeDeadBranches(pairs);
+    const reachability = computeReachability(nodeNames, pairs);
+    const totalForwards = pairs.reduce((sum, p) => sum + p.forwards.length, 0);
+    const maxForwardsInPair = Math.max(0, ...pairs.map((p) => p.forwards.length));
+    const maxRetainedSubmissionsPerForward = Math.max(0, ...pairs.flatMap((p) => p.forwards.map((f) => countRetainedSubmissions(f.retained_submission))));
+    const within_limits = {
+        max_node_count: nodes.length <= MAX_NODE_COUNT,
+        max_node_pair_count: pairs.length <= MAX_NODE_PAIR_COUNT,
+        max_forward_count: maxForwardsInPair <= MAX_FORWARD_COUNT,
+        max_forward_order_count: maxRetainedSubmissionsPerForward <= MAX_FORWARD_ORDER_COUNT,
+    };
+    return {
+        entry_nodes,
+        terminal_nodes,
+        orphaned_nodes,
+        dead_end_nodes,
+        dead_branches,
+        has_cycles,
+        cycle_nodes,
+        reachability,
+        node_count: nodes.length,
+        pair_count: pairs.length,
+        forward_count: totalForwards,
+        within_limits,
+    };
+}
+function countRetainedSubmissions(retained_submission) {
+    if (retained_submission === undefined || retained_submission === null)
+        return 0;
+    if (Array.isArray(retained_submission))
+        return retained_submission.length;
+    if (typeof retained_submission === 'string') {
+        return retained_submission.length > 0 ? 1 : 0;
+    }
+    return 0;
+}
+export function detectCycle(nodes, pairs) {
+    const nodeNames = nodes.map((n) => n.name);
+    return detectCycles(nodeNames, pairs);
+}
+function detectCycles(nodeNames, pairs) {
+    const adj = new Map();
+    for (const name of nodeNames)
+        adj.set(name, []);
+    for (const pair of pairs) {
+        if (pair.prev_node !== "" && adj.has(pair.prev_node)) {
+            adj.get(pair.prev_node).push(pair.next_node);
+        }
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const name of nodeNames)
+        color.set(name, WHITE);
+    const cycles = [];
+    const path = [];
+    function dfs(u) {
+        color.set(u, GRAY);
+        path.push(u);
+        for (const v of adj.get(u) || []) {
+            if (color.get(v) === GRAY) {
+                const cycleStart = path.indexOf(v);
+                cycles.push(path.slice(cycleStart));
+                return true;
+            }
+            if (color.get(v) === WHITE) {
+                if (dfs(v))
+                    return true;
+            }
+        }
+        path.pop();
+        color.set(u, BLACK);
+        return false;
+    }
+    for (const name of nodeNames) {
+        if (color.get(name) === WHITE) {
+            dfs(name);
+        }
+    }
+    return {
+        has_cycles: cycles.length > 0,
+        cycle_nodes: cycles,
+    };
+}
+function analyzeDeadBranches(pairs) {
+    const dead = [];
+    const byPrevNode = new Map();
+    for (const pair of pairs) {
+        if (!byPrevNode.has(pair.prev_node))
+            byPrevNode.set(pair.prev_node, []);
+        byPrevNode.get(pair.prev_node).push(pair);
+    }
+    for (const [prev, groupPairs] of byPrevNode) {
+        if (groupPairs.length <= 1)
+            continue;
+        const minThreshold = Math.min(...groupPairs.map((p) => p.threshold));
+        for (const pair of groupPairs) {
+            if (pair.threshold > minThreshold * 2) {
+                dead.push({
+                    pair: { prev_node: pair.prev_node, next_node: pair.next_node },
+                    reason: `Threshold ${pair.threshold} is much higher than competing minimum ${minThreshold}. Likely always loses.`,
+                    competing_with: groupPairs
+                        .filter((p) => p !== pair)
+                        .map((p) => p.next_node),
+                });
+            }
+        }
+    }
+    return dead;
+}
+function computeReachability(nodeNames, pairs) {
+    const adj = new Map();
+    for (const name of nodeNames)
+        adj.set(name, []);
+    for (const pair of pairs) {
+        if (pair.prev_node !== "") {
+            if (!adj.has(pair.prev_node))
+                adj.set(pair.prev_node, []);
+            adj.get(pair.prev_node).push(pair.next_node);
+        }
+    }
+    const reachability = new Map();
+    for (const start of nodeNames) {
+        const visited = new Set();
+        const queue = [start];
+        while (queue.length > 0) {
+            const u = queue.shift();
+            for (const v of adj.get(u) || []) {
+                if (!visited.has(v)) {
+                    visited.add(v);
+                    queue.push(v);
+                }
+            }
+        }
+        reachability.set(start, visited);
+    }
+    return reachability;
+}
+export function isReachableFromEntry(node, topology) {
+    for (const entry of topology.entry_nodes) {
+        if (entry === node)
+            return true;
+        if (topology.reachability.get(entry)?.has(node))
+            return true;
+    }
+    return false;
+}
+export function getNodesReachingTerminals(topology) {
+    const result = new Set();
+    for (const [node, reachable] of topology.reachability) {
+        for (const terminal of topology.terminal_nodes) {
+            if (reachable.has(terminal)) {
+                result.add(node);
+                break;
+            }
+        }
+    }
+    return result;
+}
+export function formatTopologySummary(topology) {
+    const lines = [
+        `Nodes: ${topology.node_count} (max 100)`,
+        `Pairs: ${topology.pair_count} (max 40)`,
+        `Forwards: ${topology.forward_count} (max 20 per Pair)`,
+        "",
+        `Entry nodes: ${topology.entry_nodes.join(", ") || "(none)"}`,
+        `Terminal nodes: ${topology.terminal_nodes.join(", ") || "(none)"}`,
+        `Orphaned nodes: ${topology.orphaned_nodes.join(", ") || "(none)"}`,
+        `Dead branches: ${topology.dead_branches.length}`,
+        `Cycles: ${topology.has_cycles ? "YES (❌ invalid DAG)" : "NO (✓ valid DAG)"}`,
+        "",
+        `Within on-chain limits: ${topology.within_limits.max_node_count &&
+            topology.within_limits.max_node_pair_count &&
+            topology.within_limits.max_forward_count &&
+            topology.within_limits.max_forward_order_count
+            ? "YES ✓"
+            : "NO ❌"}`,
+    ];
+    return lines.join("\n");
+}
+export function identifyTopologyPattern(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";
+        }
+    }
+    for (const [next, prevs] of toNode) {
+        if (prevs.length > 1) {
+            return "P-M-FORKMERGE";
+        }
+    }
+    return "P-M-LINEAR";
+}
+export const MACHINE_TOPOLOGY_VERSION = "1.0.0";

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

@@ -0,0 +1,96 @@
+export interface SemanticToMachineRule {
+    id: string;
+    pattern_name: string;
+    category: "execution" | "topology" | "permission" | "integration";
+    semantic_intent: string;
+    match_keywords: string[];
+    schema_elements: {
+        threshold: number | "dynamic";
+        forward_count: number | "dynamic";
+        permission_model: "single" | "mixed";
+        pair_count: number | "dynamic";
+        structure: string;
+    };
+    constraints: string[];
+    example: Record<string, unknown>;
+}
+export declare const SEMANTIC_TO_MACHINE_RULES: SemanticToMachineRule[];
+export interface NodeFieldExplanation {
+    field: string;
+    type: string;
+    required: boolean;
+    semantic: string;
+    constraint: string;
+}
+export declare const NODE_FIELD_EXPLANATIONS: NodeFieldExplanation[];
+export declare const PAIR_FIELD_EXPLANATIONS: NodeFieldExplanation[];
+export declare const FORWARD_FIELD_EXPLANATIONS: NodeFieldExplanation[];
+export declare function identifyExecutionMode(pair: {
+    threshold: number;
+    forwards: Array<{
+        weight: number;
+        named_operator?: string;
+        permission_index?: number;
+    }>;
+}): string;
+export declare function identifyTopology(pairs: Array<{
+    prev_node: string;
+    next_node: string;
+}>): string;
+export declare function matchSemanticPattern(intent: string): SemanticToMachineRule | undefined;
+export declare function explainForwardPermission(forward: {
+    named_operator?: string;
+    permission_index?: number;
+}): string;
+export interface MachineConstraintRule {
+    id: string;
+    name: string;
+    description: string;
+    category: "creation" | "structure" | "publish" | "runtime" | "node_operation";
+    verification_location: string;
+    on_chain_enforced: boolean;
+}
+export declare const MACHINE_CONSTRAINT_RULES: MachineConstraintRule[];
+export declare function getConstraintsByCategory(category: MachineConstraintRule["category"]): MachineConstraintRule[];
+export declare function getConstraintById(id: string): MachineConstraintRule | undefined;
+export declare function getOnChainConstraints(): MachineConstraintRule[];
+export declare function getOffChainConstraints(): MachineConstraintRule[];
+export declare const MACHINE_TRANSLATION_VERSION = "1.0.0";
+export declare const MACHINE_PATTERNS_COUNT: number;
+export declare const MACHINE_CONSTRAINTS_COUNT: number;
+import type { MachineForward, MachinePair } from "./machine-topology.js";
+export interface MachineNodeForExplanation {
+    name: string;
+    description?: string;
+    pairs?: MachinePair[];
+    all_pairs?: MachinePair[];
+}
+export interface NodeSemantic {
+    name: string;
+    role: "entry" | "normal" | "terminal" | "branch" | "merge";
+    pairs: PairSemantic[];
+    description?: string;
+}
+export interface PairSemantic {
+    prev_node: string;
+    next_node: string;
+    threshold: number;
+    execution_pattern: string;
+    forwards: ForwardSemantic[];
+}
+export interface ForwardSemantic {
+    name: string;
+    permission: string;
+    weight: number;
+    guard: GuardBindingSemantic | null;
+    retained_submission: string | string[] | number[] | null;
+}
+export interface GuardBindingSemantic {
+    address: string;
+    immutable_required: true;
+    note: string;
+}
+export declare function identifyNodeRole(node: MachineNodeForExplanation): NodeSemantic["role"];
+export declare function explainNode(node: MachineNodeForExplanation): NodeSemantic;
+export declare function explainPair(pair: MachinePair): PairSemantic;
+export declare function explainForward(forward: MachineForward): ForwardSemantic;