progmune-runtime 2.1.6 → 3.2.0

package/dist/graph-viz.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Capability Graph Visualization
+ *
+ * Renders the capability network as a Mermaid diagram + DOT graph.
+ * The graph has become the most valuable engineering asset —
+ * this module makes it visible.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMermaid = generateMermaid;
+exports.generateDOT = generateDOT;
+exports.generateChainViz = generateChainViz;
+exports.generateGraphReport = generateGraphReport;
+const fs = __importStar(require("fs"));
+const strategy_planner_1 = require("./strategy-planner");
+/**
+ * Generate a Mermaid flowchart of the capability graph.
+ */
+function generateMermaid(ir, opts = {}) {
+    const maxNodes = opts.maxNodes || 50;
+    const showDataFlow = opts.showDataFlow !== false;
+    const showTopology = opts.showTopology !== false;
+    const minWeight = opts.minEdgeWeight || 0.2;
+    const lines = ["```mermaid", "graph LR"];
+    // Collect nodes
+    const exported = ir.filter((f) => f.exported).slice(0, maxNodes);
+    // Node styling by score/domain
+    for (const f of exported) {
+        const hasProduces = (f.produces || []).length > 0;
+        const hasRequires = (f.requires || []).length > 0;
+        const hasPurpose = !!f.purpose;
+        let style = "";
+        if (hasProduces && hasRequires)
+            style = "[/";
+        else if (hasProduces)
+            style = "[(";
+        else
+            style = "[";
+        const endStyle = hasProduces && hasRequires ? "/]" : hasProduces ? ")]" : "]";
+        // Tag-based coloring
+        const tags = (f.tags || []).join(",");
+        const tooltip = (f.purpose || f.name).slice(0, 40).replace(/"/g, "'");
+        const nodeId = f.name.replace(/[^a-zA-Z0-9]/g, "_");
+        lines.push(`  ${nodeId}${style}"${f.name}"${endStyle}`);
+    }
+    // Data-flow edges
+    if (showDataFlow) {
+        const nameSet = new Set(exported.map(f => f.name));
+        for (const f of exported) {
+            if (!f.produces)
+                continue;
+            for (const p of f.produces) {
+                for (const other of exported) {
+                    if (other.name === f.name)
+                        continue;
+                    if ((other.requires || []).includes(p)) {
+                        lines.push(`  ${f.name.replace(/[^a-zA-Z0-9]/g, "_")} -->|"${p}"| ${other.name.replace(/[^a-zA-Z0-9]/g, "_")}`);
+                    }
+                }
+            }
+        }
+    }
+    lines.push("```");
+    return lines.join("\n");
+}
+/**
+ * Generate a DOT graph for use with Graphviz.
+ */
+function generateDOT(ir, opts = {}) {
+    const maxNodes = opts.maxNodes || 100;
+    const lines = [
+        "digraph CapabilityGraph {",
+        '  rankdir=LR;',
+        '  node [shape=box, style=rounded];',
+        '  edge [fontsize=8];',
+    ];
+    const exported = ir.filter((f) => f.exported).slice(0, maxNodes);
+    for (const f of exported) {
+        const label = `${f.name}\\n${(f.purpose || "").slice(0, 30)}`;
+        const color = (f.produces || []).length > 0 ? "lightblue" : "lightgray";
+        lines.push(`  "${f.name}" [label="${label}", fillcolor=${color}, style="filled,rounded"];`);
+    }
+    for (const f of exported) {
+        if (!f.produces)
+            continue;
+        for (const p of f.produces) {
+            for (const other of exported) {
+                if (other.name === f.name)
+                    continue;
+                if ((other.requires || []).includes(p)) {
+                    lines.push(`  "${f.name}" -> "${other.name}" [label="${p}"];`);
+                }
+            }
+        }
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+/**
+ * Generate a focused visualization of a single intent's chain.
+ */
+function generateChainViz(intent, ir, maxChains = 1) {
+    const { chains } = (0, strategy_planner_1.selectCapabilityChains)(intent, ir, maxChains);
+    if (chains.length === 0)
+        return `// No chains found for "${intent}"`;
+    const chain = chains[0];
+    const lines = [
+        `## Chain: "${intent}" (score: ${chain.score.toFixed(1)})`,
+        "",
+        "```mermaid",
+        "graph LR",
+    ];
+    for (let i = 0; i < chain.nodes.length; i++) {
+        const node = chain.nodes[i];
+        const nodeId = node.name.replace(/[^a-zA-Z0-9]/g, "_");
+        const meta = [
+            `★${node.score.toFixed(1)}`,
+            ...(node.produces || []).slice(0, 2),
+        ].join("<br/>");
+        lines.push(`  ${nodeId}["${node.name}<br/><small>${meta}</small>"]`);
+        if (i > 0) {
+            const prev = chain.nodes[i - 1];
+            // Show data-flow if exists
+            const flow = (prev.produces || []).filter(p => (node.requires || []).includes(p));
+            const label = flow.length > 0 ? flow[0] : "→";
+            lines.push(`  ${prev.name.replace(/[^a-zA-Z0-9]/g, "_")} -->|"${label}"| ${nodeId}`);
+        }
+    }
+    lines.push("```");
+    return lines.join("\n");
+}
+/**
+ * Generate a summary report of the capability graph.
+ */
+function generateGraphReport(ir) {
+    const fns = ir.length;
+    const exported = ir.filter((f) => f.exported).length;
+    const withProduces = ir.filter((f) => (f.produces || []).length > 0).length;
+    const withRequires = ir.filter((f) => (f.requires || []).length > 0).length;
+    const withPurpose = ir.filter((f) => f.purpose).length;
+    // Count data-flow edges
+    let edges = 0;
+    for (const f of ir) {
+        if (!f.produces)
+            continue;
+        for (const p of f.produces) {
+            for (const other of ir) {
+                if (other.name === f.name)
+                    continue;
+                if ((other.requires || []).includes(p))
+                    edges++;
+            }
+        }
+    }
+    // Top domains by tag
+    const tagCounts = new Map();
+    for (const f of ir) {
+        for (const t of (f.tags || [])) {
+            tagCounts.set(t, (tagCounts.get(t) || 0) + 1);
+        }
+    }
+    const topTags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    const lines = [
+        "# Capability Graph Report",
+        "",
+        "## Overview",
+        `- Total functions: **${fns}**`,
+        `- Exported: **${exported}**`,
+        `- With produces: **${withProduces}** (${Math.round(withProduces / fns * 100)}%)`,
+        `- With requires: **${withRequires}** (${Math.round(withRequires / fns * 100)}%)`,
+        `- With purpose: **${withPurpose}** (${Math.round(withPurpose / fns * 100)}%)`,
+        `- Data-flow edges: **${edges}**`,
+        "",
+        "## Top Domains",
+        "| Tag | Functions |",
+        "|-----|----------|",
+        ...topTags.map(([tag, count]) => `| ${tag} | ${count} |`),
+        "",
+        "## Coverage Trend",
+        `- v2.1.4: requires ~26%, produces ~26%, purpose ~30%`,
+        `- v2.5.x: requires **46%**, produces **62%**, purpose **100%**`,
+        `- Target (v2.6): requires **80%+**, produces **80%+**`,
+    ];
+    return lines.join("\n");
+}
+/** CLI: generate report + DOT file */
+if (require.main === module) {
+    const ir = JSON.parse(fs.readFileSync("ir.json", "utf-8")).functions || [];
+    const report = generateGraphReport(ir);
+    console.log(report);
+    const dot = generateDOT(ir, { maxNodes: 100 });
+    fs.writeFileSync("capability_graph.dot", dot);
+    console.log(`\nDOT file written to capability_graph.dot`);
+    console.log(`Render: dot -Tpng capability_graph.dot -o capability_graph.png`);
+    // Generate sample chain visualizations
+    const chains = [
+        "generate benchmark report",
+        "validate actions and extract IR",
+        "list all sessions and find failure patterns",
+    ];
+    for (const intent of chains) {
+        const viz = generateChainViz(intent, ir);
+        console.log(`\n${viz}`);
+    }
+}

package/dist/guided-frontier.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * P4.5: Reward-Guided Frontier
+ *
+ * Priority queue BFS that uses learned reward signals to guide search.
+ *
+ *   priority = rewardProbability + bridgeBonus + coverageBonus
+ *
+ * Where:
+ *   - rewardProbability: from LogisticRewardModel (how likely is this path to be accepted?)
+ *   - bridgeBonus: bonus for paths that cross protocol boundaries (diversity)
+ *   - coverageBonus: bonus for paths that visit rarely-seen states (exploration)
+ *
+ * Unlike standard BFS (FIFO), this explores promising paths first,
+ * increasing the chance of finding high-quality candidates within depth limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guidedSearch = guidedSearch;
+exports.guidedSearchMulti = guidedSearchMulti;
+const DEFAULT_GUIDED_CONFIG = {
+    rewardWeight: 0.5,
+    bridgeWeight: 0.3,
+    coverageWeight: 0.2,
+    maxPaths: 15,
+    maxDepth: 10,
+};
+// ═══════════════════════════════════════════════════════════════
+// Priority Queue
+// ═══════════════════════════════════════════════════════════════
+class PriorityQueue {
+    constructor() {
+        this.items = [];
+    }
+    enqueue(item, priority) {
+        this.items.push({ item, priority });
+        this.items.sort((a, b) => b.priority - a.priority); // descending
+    }
+    dequeue() {
+        return this.items.shift()?.item;
+    }
+    get length() { return this.items.length; }
+}
+// ═══════════════════════════════════════════════════════════════
+// Reward Estimator
+// ═══════════════════════════════════════════════════════════════
+/** Heuristic reward: shorter paths are safer (proxy for reward probability). */
+function estimateReward(actions) {
+    if (actions.length === 0)
+        return 0.5;
+    const normLength = Math.min(1, actions.length / 10);
+    return 1.0 - normLength * 0.5; // 0.5 ~ 1.0
+}
+/** Check if a function name bridges two protocols. */
+function isBridgeAction(fn) {
+    // Functions that produce states consumed by other protocols
+    const bridges = ["create_session", "logout", "open_file", "close_file", "connect_db", "disconnect_db", "extractIR", "recordSession"];
+    return bridges.includes(fn);
+}
+/** Track state visit frequency for coverage bonus. */
+class StateCoverage {
+    constructor() {
+        this.visits = new Map();
+    }
+    visit(state) {
+        this.visits.set(state, (this.visits.get(state) || 0) + 1);
+    }
+    bonus(state) {
+        const count = this.visits.get(state) || 0;
+        // Rarely visited states get higher bonus
+        return Math.max(0, 1.0 - count / 5);
+    }
+}
+// ═══════════════════════════════════════════════════════════════
+// Guided Frontier Search
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Reward-guided frontier search.
+ *
+ * Uses a priority queue where each partial path is scored by:
+ *   priority = rewardWeight × rewardProbability
+ *            + bridgeWeight × bridgeBonus
+ *            + coverageWeight × coverageBonus
+ *
+ * This biases exploration toward paths that are:
+ *   1. Likely to be accepted (short, safe)
+ *   2. Cross protocol boundaries (diverse)
+ *   3. Visit rarely-seen states (exploratory)
+ */
+function guidedSearch(rules, currentStates, targetStates, config) {
+    const cfg = { ...DEFAULT_GUIDED_CONFIG, ...config };
+    const results = [];
+    const coverage = new StateCoverage();
+    const queue = new PriorityQueue();
+    // Enqueue initial state
+    const initPriority = cfg.rewardWeight * 0.5 + cfg.bridgeWeight * 0.3 + cfg.coverageWeight * 0.2;
+    queue.enqueue({
+        states: new Set(currentStates),
+        actions: [],
+        stateList: [...currentStates],
+        depth: 0,
+    }, initPriority);
+    const visited = new Set();
+    visited.add([...currentStates].sort().join(","));
+    while (queue.length > 0 && results.length < cfg.maxPaths) {
+        const current = queue.dequeue();
+        if (!current)
+            break;
+        if (current.depth >= cfg.maxDepth)
+            continue;
+        const { states, actions, stateList, depth } = current;
+        // Check target reached
+        if (targetStates.length > 0 && targetStates.every(t => states.has(t)) && actions.length > 0) {
+            results.push({
+                actions: [...actions],
+                states: [...stateList],
+                cost: depth,
+                found: true,
+                rewardScore: estimateReward(actions),
+                priority: 0, // filled below
+            });
+            continue;
+        }
+        // Resource cleanup detection
+        if (targetStates.length === 0 && actions.length > 0) {
+            const hasOpen = states.has("FILE_OPEN") || states.has("DB_CONNECTED");
+            if (!hasOpen) {
+                results.push({
+                    actions: [...actions],
+                    states: [...stateList],
+                    cost: depth,
+                    found: true,
+                    rewardScore: estimateReward(actions),
+                    priority: 0,
+                });
+                continue;
+            }
+        }
+        for (const [fn, rule] of rules) {
+            const preOk = rule.pre_states.length === 0 || rule.pre_states.every(p => states.has(p));
+            if (!preOk)
+                continue;
+            const nextStates = new Set(states);
+            if (rule.invalidate)
+                rule.invalidate.forEach(s => { nextStates.delete(s); coverage.visit(s); });
+            for (const post of rule.post_states) {
+                nextStates.add(post);
+                coverage.visit(post);
+            }
+            const nextKey = [...nextStates].sort().join(",");
+            if (visited.has(nextKey))
+                continue;
+            visited.add(nextKey);
+            const newActions = [...actions, fn];
+            // Compute priority
+            const rewardProb = estimateReward(newActions);
+            const bridgeBonus = isBridgeAction(fn) ? 0.3 : 0;
+            const covBonus = [...nextStates].reduce((s, st) => s + coverage.bonus(st), 0) / Math.max(1, nextStates.size);
+            const priority = cfg.rewardWeight * rewardProb +
+                cfg.bridgeWeight * bridgeBonus +
+                cfg.coverageWeight * covBonus;
+            queue.enqueue({
+                states: nextStates,
+                actions: newActions,
+                stateList: [...stateList, ...rule.post_states],
+                depth: depth + 1,
+            }, priority);
+        }
+    }
+    // Fill priority scores
+    for (const r of results) {
+        r.priority = cfg.rewardWeight * r.rewardScore;
+    }
+    return results.sort((a, b) => b.priority - a.priority);
+}
+/**
+ * Multi-start guided search: try multiple initial states.
+ */
+function guidedSearchMulti(rules, currentStatesCandidates, targetStates, config) {
+    const allResults = [];
+    for (const startStates of currentStatesCandidates) {
+        const paths = guidedSearch(rules, startStates, targetStates, config);
+        allResults.push(...paths);
+    }
+    // Deduplicate and sort by priority
+    const seen = new Set();
+    const unique = [];
+    for (const p of allResults) {
+        const key = p.actions.join("→");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(p);
+    }
+    return unique.sort((a, b) => b.priority - a.priority);
+}

package/dist/hierarchical-planner.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * P5.2: Hierarchical Planner
+ *
+ * Three-level search: Goal → Skill → Action
+ *
+ * Uses SkillLibrary to lift planning from the action space into
+ * the skill space, reducing search depth by an order of magnitude.
+ *
+ * When a Goal matches a known Skill chain, the planner expands
+ * the skill into its action sequence directly — no BFS needed.
+ *
+ * When no skills match, falls back to action-level Frontier BFS.
+ *
+ * DiscoveryModel guides the search toward discoverable paths,
+ * prioritizing skill chains that are most likely to yield candidates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HierarchicalPlanner = void 0;
+exports.createHierarchicalPlanner = createHierarchicalPlanner;
+const skill_library_1 = require("./skill-library");
+const guided_frontier_1 = require("./guided-frontier");
+// ═══════════════════════════════════════════════════════════════
+// Hierarchical Planner
+// ═══════════════════════════════════════════════════════════════
+class HierarchicalPlanner {
+    constructor(library, rules, discoveryModel) {
+        this.library = library;
+        this.rules = rules;
+        this.discoveryModel = discoveryModel;
+    }
+    /**
+     * Plan a repair using Goal → Skill → Action hierarchy.
+     *
+     * 1. Check if any single skill directly satisfies the goal
+     * 2. If not, try composing multiple skills into a chain
+     * 3. If no skill chain works, fall back to action-level Frontier BFS
+     *
+     * @param goal Natural language goal (for discovery scoring)
+     * @param currentStates Current protocol states
+     * @param targetStates Desired protocol states
+     * @param violationType Type of violation
+     * @param maxCandidates Max number of candidates to return
+     */
+    plan(goal, currentStates, targetStates, violationType, maxCandidates = 10) {
+        const candidates = [];
+        // ── Level 1: Direct skill match ──
+        const applicable = this.library.findApplicable(currentStates);
+        for (const skill of applicable) {
+            // Does this skill's effects satisfy the target?
+            const effectsMatch = targetStates.length === 0 || targetStates.every(t => skill.effects.includes(t));
+            // Or does the skill produce a cleanup effect?
+            const cleanupMatch = targetStates.length === 0 && skill.effects.length > 0;
+            if (effectsMatch || cleanupMatch) {
+                const score = this.scoreSkill(skill, goal, violationType);
+                candidates.push({
+                    actions: skill.macro,
+                    skillChain: [skill.id],
+                    source: "skill",
+                    score,
+                });
+            }
+        }
+        // ── Level 2: Composed skill chain ──
+        if (targetStates.length > 0) {
+            const chains = this.library.compose(currentStates, targetStates, 4);
+            for (const chain of chains) {
+                const actions = this.library.expand(chain);
+                const avgScore = chain.reduce((s, sk) => s + this.scoreSkill(sk, goal, violationType), 0) / chain.length;
+                candidates.push({
+                    actions,
+                    skillChain: chain.map(s => s.id),
+                    source: "skill-compose",
+                    score: avgScore,
+                });
+            }
+        }
+        // ── Level 3: Action-level Frontier BFS (fallback) ──
+        const frontierPaths = (0, guided_frontier_1.guidedSearch)(this.rules, currentStates, targetStates);
+        for (const path of frontierPaths.slice(0, maxCandidates)) {
+            // Skip if this path is already covered by a skill
+            const alreadyCovered = candidates.some(c => c.actions.length === path.actions.length &&
+                c.actions.every((a, i) => a === path.actions[i]));
+            if (!alreadyCovered) {
+                candidates.push({
+                    actions: path.actions,
+                    skillChain: [],
+                    source: "frontier",
+                    score: path.priority || 0.5,
+                });
+            }
+        }
+        // Sort by score descending, deduplicate, return top K
+        const seen = new Set();
+        const unique = [];
+        for (const c of candidates.sort((a, b) => b.score - a.score)) {
+            const key = c.actions.join("→");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            unique.push(c);
+        }
+        return unique.slice(0, maxCandidates);
+    }
+    /**
+     * Score a skill using discovery model + acceptance rate.
+     *
+     *   score = discoveryProb × 0.5 + acceptanceRate × 0.3 + matchBonus × 0.2
+     */
+    scoreSkill(skill, goal, violationType) {
+        let discoveryProb = 0.5;
+        if (this.discoveryModel) {
+            discoveryProb = this.discoveryModel.predict({
+                protocol: skill.protocol,
+                violationType,
+                isResourceLeak: violationType === "resource_leak" ? 1 : 0,
+                isMissingPrereq: violationType === "missing_prerequisite" ? 1 : 0,
+                isIllegalState: violationType === "illegal_state_transition" ? 1 : 0,
+                currentStateCount: skill.preconditions.length,
+            });
+        }
+        const matchBonus = skill.goal.toLowerCase().includes(goal.toLowerCase().slice(0, 10)) ? 1.0 : 0.5;
+        return discoveryProb * 0.5 + skill.acceptanceRate * 0.3 + matchBonus * 0.2;
+    }
+    /**
+     * Quick plan: return only skill-based candidates (no BFS fallback).
+     * Fast path for common repairs.
+     */
+    quickPlan(goal, currentStates) {
+        const applicable = this.library.findApplicable(currentStates);
+        return applicable.map(skill => ({
+            actions: skill.macro,
+            skillChain: [skill.id],
+            source: "skill",
+            score: skill.acceptanceRate,
+        })).sort((a, b) => b.score - a.score);
+    }
+}
+exports.HierarchicalPlanner = HierarchicalPlanner;
+// ═══════════════════════════════════════════════════════════════
+// Convenience factory
+// ═══════════════════════════════════════════════════════════════
+function createHierarchicalPlanner(telemetry, // PlannerTelemetry
+rules, discoveryModel) {
+    const library = new skill_library_1.SkillLibrary();
+    library.learn(telemetry, rules);
+    return new HierarchicalPlanner(library, rules, discoveryModel);
+}