progmune-runtime 2.1.6 → 3.2.1

package/dist/discovery-model.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * P4.5+: Discovery Reward Model
+ *
+ * Predicts P(candidate_exists | goal, protocol, violation) rather than
+ * P(accepted | candidate). This is the signal that should drive
+ * Guided Frontier — not "how likely is this path to be accepted?"
+ * but "how likely is a path through this state to even be found?"
+ *
+ * Training data: benchmark attributions (foundCandidate = 1 - missingCandidate)
+ * Features: protocol, violation type, state context
+ *
+ * When 57% of failures are missing_candidate, the most valuable signal
+ * for search guidance is discoverability, not acceptability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryModel = void 0;
+exports.generateDiscoverabilityReport = generateDiscoverabilityReport;
+exports.printDiscoverabilityReport = printDiscoverabilityReport;
+function sigmoid(z) {
+    if (z > 20)
+        return 1.0;
+    if (z < -20)
+        return 0.0;
+    return 1.0 / (1.0 + Math.exp(-z));
+}
+// ═══════════════════════════════════════════════════════════════
+// Discovery Model
+// ═══════════════════════════════════════════════════════════════
+const KNOWN_PROTOCOLS = ["FileProtocol", "AuthProtocol", "DBProtocol", "IRProtocol", "_global"];
+const KNOWN_VIOLATIONS = ["resource_leak", "missing_prerequisite", "illegal_state_transition"];
+function featuresToArray(f) {
+    const protoBits = KNOWN_PROTOCOLS.map(p => f.protocol === p ? 1.0 : 0.0);
+    const violBits = KNOWN_VIOLATIONS.map(v => f.violationType === v ? 1.0 : 0.0);
+    return [
+        f.isResourceLeak,
+        f.isMissingPrereq,
+        f.isIllegalState,
+        f.currentStateCount / 10,
+        ...protoBits,
+        ...violBits,
+    ];
+}
+const FEATURE_DIM = 4 + KNOWN_PROTOCOLS.length + KNOWN_VIOLATIONS.length; // 4 + 5 + 3 = 12
+class DiscoveryModel {
+    constructor(weights, bias) {
+        this.weights = weights || new Array(FEATURE_DIM).fill(0);
+        this.bias = bias || 0;
+        this.trained = weights !== undefined;
+        this.trainedSamples = 0;
+    }
+    get isTrained() { return this.trained; }
+    get sampleCount() { return this.trainedSamples; }
+    /** Predict probability that a candidate exists for this context. */
+    predict(features) {
+        return sigmoid(this.score(featuresToArray(features)));
+    }
+    score(x) {
+        return x.reduce((s, v, i) => s + this.weights[i] * v, 0) + this.bias;
+    }
+    // ── Training ──
+    static samplesFromAttributions(attributed) {
+        return attributed.map(a => ({
+            features: {
+                protocol: a.protocol,
+                violationType: a.violationType,
+                isResourceLeak: a.violationType === "resource_leak" ? 1 : 0,
+                isMissingPrereq: a.violationType === "missing_prerequisite" ? 1 : 0,
+                isIllegalState: a.violationType === "illegal_state_transition" ? 1 : 0,
+                currentStateCount: 1,
+            },
+            label: a.failureReason !== "missing_candidate" ? 1 : 0,
+            goal: a.goal,
+        }));
+    }
+    static train(samples, learningRate = 0.01, epochs = 100) {
+        if (samples.length < 10)
+            return new DiscoveryModel();
+        let w = new Array(FEATURE_DIM).fill(0).map(() => (Math.random() - 0.5) * 0.1);
+        let b = 0.0;
+        for (let epoch = 0; epoch < epochs; epoch++) {
+            const shuffled = [...samples].sort(() => Math.random() - 0.5);
+            for (const sample of shuffled) {
+                const x = featuresToArray(sample.features);
+                const z = w.reduce((s, wi, i) => s + wi * x[i], 0) + b;
+                const p = sigmoid(z);
+                const error = p - sample.label;
+                for (let i = 0; i < FEATURE_DIM; i++) {
+                    w[i] -= learningRate * error * x[i];
+                }
+                b -= learningRate * error;
+            }
+        }
+        const model = new DiscoveryModel(w, b);
+        model.trained = true;
+        model.trainedSamples = samples.length;
+        return model;
+    }
+    /** Feature importance for interpretability. */
+    featureImportance() {
+        const names = [
+            "isResourceLeak", "isMissingPrereq", "isIllegalState", "stateCount",
+            ...KNOWN_PROTOCOLS.map(p => `proto:${p}`),
+            ...KNOWN_VIOLATIONS.map(v => `viol:${v}`),
+        ];
+        return names.map((name, i) => ({ name, weight: this.weights[i] }))
+            .sort((a, b) => Math.abs(b.weight) - Math.abs(a.weight));
+    }
+}
+exports.DiscoveryModel = DiscoveryModel;
+/**
+ * Generate a discoverability report: which protocol/violation combinations
+ * are least likely to have candidates found?
+ */
+function generateDiscoverabilityReport(model) {
+    const predictions = [];
+    for (const proto of KNOWN_PROTOCOLS) {
+        for (const viol of KNOWN_VIOLATIONS) {
+            const features = {
+                protocol: proto,
+                violationType: viol,
+                isResourceLeak: viol === "resource_leak" ? 1 : 0,
+                isMissingPrereq: viol === "missing_prerequisite" ? 1 : 0,
+                isIllegalState: viol === "illegal_state_transition" ? 1 : 0,
+                currentStateCount: 1,
+            };
+            const discoverability = model.predict(features);
+            predictions.push({
+                protocol: proto,
+                violationType: viol,
+                discoverability,
+                priority: 1 - discoverability,
+            });
+        }
+    }
+    return predictions.sort((a, b) => b.priority - a.priority);
+}
+function printDiscoverabilityReport(predictions) {
+    console.log("\n─── Discoverability Report ───");
+    console.log("Protocol          Violation                Discover  Priority");
+    console.log("─────────────────────────────────────────────────────────────");
+    for (const p of predictions.slice(0, 10)) {
+        const disc = (p.discoverability * 100).toFixed(0).padStart(4);
+        const pri = (p.priority * 100).toFixed(0).padStart(4);
+        const icon = p.priority > 0.5 ? "🔴" : p.priority > 0.3 ? "🟡" : "🟢";
+        console.log(`  ${p.protocol.padEnd(16)} ${p.violationType.padEnd(22)} ${disc}%   ${pri}%  ${icon}`);
+    }
+    console.log();
+}

package/dist/discovery-optimize.test.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * P4.5-4.7: Guided Frontier + Macro Mining + Discovery Analytics Tests
+ */
+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 });
+const vitest_1 = require("vitest");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const guided_frontier_1 = require("./guided-frontier");
+const macro_repair_1 = require("./macro-repair");
+const discovery_analytics_1 = require("./discovery-analytics");
+const planner_telemetry_1 = require("./planner-telemetry");
+function mergeProtocolRules(...maps) {
+    const m = new Map();
+    for (const mp of maps)
+        for (const [k, v] of mp)
+            m.set(k, v);
+    return m;
+}
+const fileRules = new Map([
+    ["open_file", { pre_states: [], post_states: ["FILE_OPEN"] }],
+    ["write_file", { pre_states: ["FILE_OPEN"], post_states: [] }],
+    ["close_file", { pre_states: ["FILE_OPEN"], post_states: [], invalidate: ["FILE_OPEN"] }],
+]);
+const authRules = new Map([
+    ["verify_password", { pre_states: ["UNAUTHENTICATED"], post_states: ["PASSWORD_VERIFIED"] }],
+    ["generate_jwt", { pre_states: ["PASSWORD_VERIFIED"], post_states: ["TOKEN_ISSUED"], invalidate: ["PASSWORD_VERIFIED"] }],
+    ["create_session", { pre_states: ["TOKEN_ISSUED"], post_states: ["SESSION_ACTIVE"], invalidate: ["TOKEN_ISSUED"] }],
+    ["logout", { pre_states: ["SESSION_ACTIVE"], post_states: ["UNAUTHENTICATED"], invalidate: ["SESSION_ACTIVE"] }],
+]);
+const dbRules = new Map([
+    ["connect_db", { pre_states: [], post_states: ["DB_CONNECTED"] }],
+    ["query_db", { pre_states: ["DB_CONNECTED"], post_states: [] }],
+    ["disconnect_db", { pre_states: ["DB_CONNECTED"], post_states: [], invalidate: ["DB_CONNECTED"] }],
+]);
+const OPT_DIR = path.resolve(__dirname, "..", "test-discovery-optimize");
+process.env.PROGMUNE_PROJECT_DIR = OPT_DIR;
+fs.mkdirSync(OPT_DIR, { recursive: true });
+fs.mkdirSync(path.join(OPT_DIR, ".progmune_corpus", "telemetry"), { recursive: true });
+function seedHighAcceptanceTelemetry(n) {
+    const t = new planner_telemetry_1.PlannerTelemetry(path.join(OPT_DIR, ".progmune_corpus", "telemetry", `opt-${Date.now()}.jsonl`));
+    // Pattern: "open_file → write_file → close_file" accepted 90% of the time
+    for (let i = 0; i < n; i++) {
+        const actions = ["open_file", "write_file", "close_file"];
+        const fp = (0, planner_telemetry_1.candidateFingerprint)("FileProtocol", actions, "resource_leak");
+        const id = t.recordDecision({
+            goal: "safely write config file",
+            protocol: "FileProtocol", violationType: "resource_leak",
+            candidates: [{ candidateId: fp, source: "protocol", evidenceSources: ["protocol"], actions, explanation: "full sequence" }],
+            selectedCandidateId: fp,
+            cost: { latencyMs: 3 + Math.random() * 5 },
+        });
+        const accepted = Math.random() < 0.9;
+        t.recordFeedback(id, {
+            decision: accepted ? "accepted" : "rejected",
+            executionResult: accepted ? { success: true, violations: [] } : { success: false, violations: ["resource_leak"] },
+            timestamp: Date.now(),
+        });
+    }
+    // Auth pattern: accepted 85%
+    for (let i = 0; i < n; i++) {
+        const actions = ["verify_password", "generate_jwt", "create_session"];
+        const fp = (0, planner_telemetry_1.candidateFingerprint)("AuthProtocol", actions, "missing_prerequisite");
+        const id = t.recordDecision({
+            goal: "authenticate user",
+            protocol: "AuthProtocol", violationType: "missing_prerequisite",
+            candidates: [{ candidateId: fp, source: "protocol", evidenceSources: ["protocol"], actions, explanation: "auth flow" }],
+            selectedCandidateId: fp,
+        });
+        const accepted = Math.random() < 0.85;
+        t.recordFeedback(id, {
+            decision: accepted ? "accepted" : "rejected",
+            executionResult: accepted ? { success: true, violations: [] } : undefined,
+            timestamp: Date.now(),
+        });
+    }
+    return t;
+}
+(0, vitest_1.describe)("P4.5 Reward-Guided Frontier", () => {
+    (0, vitest_1.it)("guided search finds paths with priority ordering", () => {
+        const rules = mergeProtocolRules(authRules, fileRules, dbRules);
+        const paths = (0, guided_frontier_1.guidedSearch)(rules, ["UNAUTHENTICATED"], ["SESSION_ACTIVE"]);
+        (0, vitest_1.expect)(paths.length).toBeGreaterThan(0);
+        // Should find auth path
+        const hasAuth = paths.some(p => p.actions.includes("verify_password") && p.actions.includes("generate_jwt"));
+        (0, vitest_1.expect)(hasAuth).toBe(true);
+        // Paths should be sorted by priority (descending)
+        for (let i = 1; i < paths.length; i++) {
+            (0, vitest_1.expect)(paths[i - 1].priority).toBeGreaterThanOrEqual(paths[i].priority);
+        }
+    });
+    (0, vitest_1.it)("multi-start finds paths from different initial states", () => {
+        const rules = mergeProtocolRules(fileRules, authRules);
+        const paths = (0, guided_frontier_1.guidedSearchMulti)(rules, [
+            ["FILE_OPEN"],
+            ["UNAUTHENTICATED"],
+        ], ["SESSION_ACTIVE"]);
+        (0, vitest_1.expect)(paths.length).toBeGreaterThan(0);
+        // Should include paths from both starting points
+        (0, vitest_1.expect)(paths.every(p => p.found)).toBe(true);
+    });
+});
+(0, vitest_1.describe)("P4.6 Macro Repair Mining", () => {
+    (0, vitest_1.it)("mines high-acceptance patterns from telemetry", () => {
+        const telemetry = seedHighAcceptanceTelemetry(50);
+        const macros = (0, macro_repair_1.mineMacroRepairs)(telemetry, 0.7, 3);
+        (0, vitest_1.expect)(macros.length).toBeGreaterThanOrEqual(1);
+        // File repair pattern should be mined
+        const fileMacro = macros.find(m => m.protocol === "FileProtocol");
+        (0, vitest_1.expect)(fileMacro).toBeDefined();
+        (0, vitest_1.expect)(fileMacro.acceptanceRate).toBeGreaterThan(0.7);
+        (0, vitest_1.expect)(fileMacro.actions).toEqual(["open_file", "write_file", "close_file"]);
+        (0, macro_repair_1.printMacroReport)(macros);
+    });
+    (0, vitest_1.it)("persists and loads macros", () => {
+        const telemetry = seedHighAcceptanceTelemetry(60);
+        const mined = (0, macro_repair_1.mineMacroRepairs)(telemetry, 0.7, 3);
+        const fp = (0, macro_repair_1.saveMacroRepairs)(mined);
+        (0, vitest_1.expect)(fs.existsSync(fp)).toBe(true);
+        const loaded = (0, macro_repair_1.loadMacroRepairs)();
+        (0, vitest_1.expect)(loaded.length).toBeGreaterThanOrEqual(mined.length);
+    });
+    (0, vitest_1.it)("filters out low-frequency patterns", () => {
+        const telemetry = new planner_telemetry_1.PlannerTelemetry(path.join(OPT_DIR, ".progmune_corpus", "telemetry", `lowfreq-${Date.now()}.jsonl`));
+        // Only 2 samples — below minFrequency=3
+        for (let i = 0; i < 2; i++) {
+            const fp = (0, planner_telemetry_1.candidateFingerprint)("FileProtocol", ["close_file"], "resource_leak");
+            const id = telemetry.recordDecision({
+                goal: "test", protocol: "FileProtocol",
+                candidates: [{ candidateId: fp, source: "protocol", evidenceSources: ["protocol"], actions: ["close_file"], explanation: "close" }],
+                selectedCandidateId: fp,
+            });
+            telemetry.recordFeedback(id, { decision: "accepted", executionResult: { success: true, violations: [] }, timestamp: Date.now() });
+        }
+        const macros = (0, macro_repair_1.mineMacroRepairs)(telemetry, 0.7, 3);
+        (0, vitest_1.expect)(macros.length).toBe(0); // not enough frequency
+    });
+});
+(0, vitest_1.describe)("P4.7 Discovery Analytics", () => {
+    (0, vitest_1.it)("computes discovery metrics from attributions", () => {
+        const attributed = [
+            { caseId: "c1", goal: "safely write", protocol: "FileProtocol", violationType: "resource_leak", expectedRepair: ["close_file"], candidatesReturned: 2, rank: 1, failureReason: "success" },
+            { caseId: "c2", goal: "safely write", protocol: "FileProtocol", violationType: "resource_leak", expectedRepair: ["close_file"], candidatesReturned: 1, rank: null, failureReason: "bad_ranking" },
+            { caseId: "c3", goal: "authenticate", protocol: "AuthProtocol", violationType: "missing_prerequisite", expectedRepair: ["generate_jwt"], candidatesReturned: 0, rank: null, failureReason: "missing_candidate" },
+            { caseId: "c4", goal: "logout user", protocol: "AuthProtocol", violationType: "illegal_state_transition", expectedRepair: ["logout"], candidatesReturned: 0, rank: null, failureReason: "missing_candidate" },
+        ];
+        const metrics = (0, discovery_analytics_1.computeDiscoveryMetrics)(attributed);
+        (0, vitest_1.expect)(metrics.totalCases).toBe(4);
+        (0, vitest_1.expect)(metrics.overall).toBe(0.5); // 2/4 discovered
+        // FileProtocol: 2/2 discovered
+        (0, vitest_1.expect)(metrics.byProtocol["FileProtocol"]).toBe(1.0);
+        // AuthProtocol: 0/2 discovered
+        (0, vitest_1.expect)(metrics.byProtocol["AuthProtocol"]).toBe(0);
+        // resource_leak: 2/2, missing_prerequisite: 0/1, illegal_state_transition: 0/1
+        (0, vitest_1.expect)(metrics.byViolation["resource_leak"]).toBe(1.0);
+        (0, vitest_1.expect)(metrics.byViolation["missing_prerequisite"]).toBe(0);
+    });
+    (0, vitest_1.it)("generates full analytics report", async () => {
+        const telemetry = seedHighAcceptanceTelemetry(30);
+        const report = await (0, discovery_analytics_1.generateFullAnalyticsReport)(telemetry);
+        (0, vitest_1.expect)(report.discovery.totalCases).toBeGreaterThanOrEqual(49);
+        (0, vitest_1.expect)(report.macroCount).toBeGreaterThanOrEqual(1);
+        (0, vitest_1.expect)(report.topMacros.length).toBeGreaterThanOrEqual(1);
+        (0, discovery_analytics_1.printDiscoveryDashboard)(report);
+    });
+});

package/dist/discovery-trace.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * P3.24-27: Search Trace + Bridge Learning + Discovery Benchmark + Replay
+ *
+ * P3.24: Record WHY candidates are missing. Decompose 57% missing_candidate
+ *   into missing_action, missing_transition, depth_limit, bridge_missing.
+ *
+ * P3.25: Protocol Bridge Learning — cross-protocol state bridges.
+ *   Auth → File → DB → IR → Queue. Frontier BFS across protocols.
+ *
+ * P3.26: Discovery Benchmark — three-tier metric:
+ *   DiscoveryRate (any correct candidate?) → Ranking (Top-1/Top-3) → Execution.
+ *
+ * P3.27: Counterfactual Replay — off-policy evaluation.
+ *   Replay historical decisions with new ranker/frontier, compare acceptance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceSearch = traceSearch;
+exports.decomposeMissingCandidate = decomposeMissingCandidate;
+exports.computeDiscoveryReport = computeDiscoveryReport;
+exports.printDiscoveryReport = printDiscoveryReport;
+exports.evaluateOffPolicy = evaluateOffPolicy;
+exports.printReplayEvaluation = printReplayEvaluation;
+exports.learnProtocolBridges = learnProtocolBridges;
+const protocol_coverage_1 = require("./protocol-coverage");
+/**
+ * Trace a frontier search and classify WHY candidates are missing.
+ */
+function traceSearch(rules, currentStates, targetStates, expectedRepair, strategy = "frontier", goal, maxDepth = 6) {
+    const trace = {
+        strategy, goal,
+        expandedNodes: [], prunedNodes: [], deadEnds: [],
+        maxDepthReached: 0, candidateGenerated: false, candidateCount: 0,
+    };
+    const visited = new Set();
+    const queue = [
+        { states: new Set(currentStates), actions: [], depth: 0 },
+    ];
+    visited.add([...currentStates].sort().join(","));
+    while (queue.length > 0) {
+        const { states, actions, depth } = queue.shift();
+        trace.maxDepthReached = Math.max(trace.maxDepthReached, depth);
+        if (depth >= maxDepth) {
+            trace.deadEnds.push({ node: [...states].join(","), reason: "depth_limit" });
+            continue;
+        }
+        let anyRuleApplied = false;
+        for (const [fn, rule] of rules) {
+            const preOk = rule.pre_states.length === 0 || rule.pre_states.every(p => states.has(p));
+            if (!preOk)
+                continue;
+            anyRuleApplied = true;
+            const next = new Set(states);
+            if (rule.invalidate)
+                rule.invalidate.forEach(s => next.delete(s));
+            for (const post of rule.post_states)
+                next.add(post);
+            const key = [...next].sort().join(",");
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            trace.expandedNodes.push(fn);
+            const newActions = [...actions, fn];
+            // Check if this reaches the expected repair
+            if (expectedRepair.every(fn => newActions.includes(fn))) {
+                trace.candidateGenerated = true;
+                trace.candidateCount++;
+            }
+            queue.push({ states: next, actions: newActions, depth: depth + 1 });
+        }
+        if (!anyRuleApplied && depth > 0) {
+            trace.deadEnds.push({ node: [...states].join(","), reason: "precondition_failed" });
+        }
+    }
+    // Classify missing candidates by analyzing dead ends
+    for (const fn of expectedRepair) {
+        if (!rules.has(fn)) {
+            trace.deadEnds.push({ node: fn, reason: "missing_action" });
+        }
+    }
+    return trace;
+}
+/**
+ * Decompose a search failure into root causes.
+ */
+function decomposeMissingCandidate(traces) {
+    const result = {
+        total: traces.length,
+        missingAction: 0,
+        missingTransition: 0,
+        depthLimit: 0,
+        bridgeMissing: 0,
+        preconditionFailed: 0,
+    };
+    for (const t of traces) {
+        if (t.candidateGenerated)
+            continue;
+        for (const de of t.deadEnds) {
+            switch (de.reason) {
+                case "missing_action":
+                    result.missingAction++;
+                    break;
+                case "missing_transition":
+                    result.missingTransition++;
+                    break;
+                case "depth_limit":
+                    result.depthLimit++;
+                    break;
+                case "bridge_missing":
+                    result.bridgeMissing++;
+                    break;
+                case "precondition_failed":
+                    result.preconditionFailed++;
+                    break;
+            }
+        }
+    }
+    return result;
+}
+function computeDiscoveryReport(results) {
+    const total = results.length;
+    const discovered = results.filter(r => r.discovery).length;
+    const top1 = results.filter(r => r.top1Hit).length;
+    const top3 = results.filter(r => r.top3Hit).length;
+    const avgCand = results.reduce((s, r) => s + r.candidateCount, 0) / Math.max(1, total);
+    // Aggregate decompositions
+    const allTraces = results
+        .filter(r => !r.discovery && r.decomposition)
+        .map(r => r.decomposition);
+    const merged = {
+        total: allTraces.length,
+        missingAction: allTraces.reduce((s, d) => s + d.missingAction, 0),
+        missingTransition: allTraces.reduce((s, d) => s + d.missingTransition, 0),
+        depthLimit: allTraces.reduce((s, d) => s + d.depthLimit, 0),
+        bridgeMissing: allTraces.reduce((s, d) => s + d.bridgeMissing, 0),
+        preconditionFailed: allTraces.reduce((s, d) => s + d.preconditionFailed, 0),
+    };
+    return {
+        cases: total,
+        discoveryRate: total > 0 ? discovered / total : 0,
+        top3Rate: total > 0 ? top3 / total : 0,
+        top1Rate: total > 0 ? top1 / total : 0,
+        avgCandidates: avgCand,
+        gapBreakdown: merged,
+    };
+}
+function printDiscoveryReport(report) {
+    console.log("\n╔════════════════════════════════════════════════════╗");
+    console.log("║   Discovery Benchmark                              ║");
+    console.log("╚════════════════════════════════════════════════════╝\n");
+    const dr = (report.discoveryRate * 100).toFixed(0);
+    const t1 = (report.top1Rate * 100).toFixed(0);
+    const t3 = (report.top3Rate * 100).toFixed(0);
+    console.log(`Cases:             ${report.cases}`);
+    console.log(`Discovery Rate:    ${dr}%  (any correct candidate found)`);
+    console.log(`Top-3 Accuracy:    ${t3}%`);
+    console.log(`Top-1 Accuracy:    ${t1}%`);
+    console.log(`Avg Candidates:    ${report.avgCandidates.toFixed(1)}`);
+    console.log();
+    if (report.gapBreakdown.total > 0) {
+        console.log("─── Missing Candidate Decomposition ───");
+        const g = report.gapBreakdown;
+        console.log(`  missing_action:       ${g.missingAction}`);
+        console.log(`  missing_transition:   ${g.missingTransition}`);
+        console.log(`  depth_limit:          ${g.depthLimit}`);
+        console.log(`  bridge_missing:       ${g.bridgeMissing}`);
+        console.log(`  precondition_failed:  ${g.preconditionFailed}`);
+        console.log();
+    }
+    const discoveryGap = report.discoveryRate - report.top1Rate;
+    if (discoveryGap > 0.15) {
+        console.log(`  ⚠️  Discovery→Top1 gap: ${(discoveryGap * 100).toFixed(0)}% — ranking is the bottleneck`);
+    }
+    else if (report.discoveryRate < 0.5) {
+        console.log(`  ⚠️  Discovery < 50% — candidate generation is the bottleneck`);
+    }
+    console.log();
+}
+/**
+ * Off-policy evaluation: compare old system vs new system.
+ *
+ * Given historical decisions (what was proposed, what was accepted),
+ * and a new candidate generator, compute how the new system would
+ * have performed on the same decisions.
+ */
+function evaluateOffPolicy(decisions, newCandidateGenerator, matchFn = (c, a) => a.every(fn => c.includes(fn))) {
+    let baselineAccepted = 0;
+    let newAccepted = 0;
+    for (const d of decisions) {
+        // Baseline: was the accepted candidate in the original proposals?
+        if (d.acceptedActions) {
+            const baseMatch = d.candidates.some(c => matchFn(c, d.acceptedActions));
+            if (baseMatch)
+                baselineAccepted++;
+        }
+        // New: would the new generator have found the accepted candidate?
+        const newCandidates = newCandidateGenerator(d.goal, d.protocol);
+        if (d.acceptedActions && newCandidates.some(c => matchFn(c, d.acceptedActions))) {
+            newAccepted++;
+        }
+    }
+    const total = decisions.length;
+    return {
+        totalDecisions: total,
+        baselineAccepted,
+        baselineRate: total > 0 ? baselineAccepted / total : 0,
+        newAccepted,
+        newRate: total > 0 ? newAccepted / total : 0,
+        delta: total > 0 ? (newAccepted - baselineAccepted) / total : 0,
+        improvement: newAccepted > baselineAccepted,
+    };
+}
+function printReplayEvaluation(eval_) {
+    console.log("\n╔════════════════════════════════════════════════════╗");
+    console.log("║   Counterfactual Replay (Off-Policy)                ║");
+    console.log("╚════════════════════════════════════════════════════╝\n");
+    const base = (eval_.baselineRate * 100).toFixed(1);
+    const nw = (eval_.newRate * 100).toFixed(1);
+    const delta = (eval_.delta * 100).toFixed(1);
+    const sign = eval_.delta > 0 ? "+" : "";
+    console.log(`Decisions Replayed:  ${eval_.totalDecisions}`);
+    console.log(`Baseline (old):      ${base}%  (${eval_.baselineAccepted}/${eval_.totalDecisions})`);
+    console.log(`New System:          ${nw}%  (${eval_.newAccepted}/${eval_.totalDecisions})`);
+    console.log(`Δ:                   ${sign}${delta}%`);
+    console.log();
+    if (eval_.improvement) {
+        console.log(`  ✅ New system outperforms baseline by ${sign}${delta}%`);
+    }
+    else if (eval_.delta === 0) {
+        console.log("  ═  No change. New system matches baseline.");
+    }
+    else {
+        console.log(`  ❌ New system regresses by ${sign}${delta}%`);
+    }
+    console.log();
+}
+/**
+ * Learn cross-protocol bridges from benchmark failures.
+ *
+ * When a benchmark expects auth → file → db chains, but the
+ * protocols are isolated, infer bridges connecting them.
+ */
+function learnProtocolBridges(crossProtocolFailures) {
+    const defs = (0, protocol_coverage_1.loadDefaultProtocolDefinitions)();
+    const protoRules = new Map(defs.map(p => [p.name, p.rules]));
+    const bridges = [];
+    const bridgeCounts = new Map();
+    for (const f of crossProtocolFailures) {
+        // Determine which protocols are involved
+        const involved = new Set();
+        for (const fn of f.expectedRepair) {
+            for (const [name, rules] of protoRules) {
+                if (rules.has(fn))
+                    involved.add(name);
+            }
+        }
+        const protoList = [...involved];
+        for (let i = 0; i < protoList.length - 1; i++) {
+            const from = protoList[i];
+            const to = protoList[i + 1];
+            const key = `${from}→${to}`;
+            bridgeCounts.set(key, (bridgeCounts.get(key) || 0) + 1);
+        }
+    }
+    const maxCount = Math.max(1, ...[...bridgeCounts.values()]);
+    for (const [key, count] of bridgeCounts) {
+        const [from, to] = key.split("→");
+        bridges.push({
+            fromProtocol: from, toProtocol: to,
+            viaState: "COMPLETED", targetState: "INIT",
+            confidence: count / maxCount,
+            evidenceCount: count,
+        });
+    }
+    return bridges.sort((a, b) => b.confidence - a.confidence);
+}