progmune-runtime 2.1.6 → 3.2.1

package/dist/repair-executor.js

@@ -0,0 +1,719 @@
+"use strict";
+/**
+ * P0: Repair Executor — the "apply + verify" loop that was missing.
+ *
+ * The current pipeline stops at "suggestion." This module closes the loop:
+ *
+ *   detect violation → suggest fixes → APPLY best fix → re-verify → confirm/resolve
+ *
+ * Without this, repair success is capped at ~57% because:
+ *   1. Fix paths exist but are never applied (30.7% of failures)
+ *   2. No fix path found at all (34.7% of failures — protocol gap)
+ *   3. Fix applied but not verified (remaining failures)
+ *
+ * Architecture:
+ *   RepairExecutor
+ *     ├── applyFix()         — insert/replace actions in code sequence
+ *     ├── verifyRepair()     — re-run SSG validation after fix
+ *     ├── executeWithRetry() — try top-3 candidates until one works
+ *     └── recordOutcome()    — write repair trajectory with verdict
+ */
+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.RepairExecutor = void 0;
+exports.fixViolation = fixViolation;
+exports.generateRepairTaxonomy = generateRepairTaxonomy;
+exports.printRepairTaxonomy = printRepairTaxonomy;
+exports.applySourceFix = applySourceFix;
+exports.writeSourceFix = writeSourceFix;
+exports.repairSourceFile = repairSourceFile;
+const counterfactual_engine_1 = require("./counterfactual-engine");
+const failure_corpus_1 = require("./failure-corpus");
+const DEFAULT_OPTIONS = {
+    maxAttempts: 3,
+    recordTrajectory: true,
+    verifyTimeout: 5000,
+};
+// ═══════════════════════════════════════════════════════════════
+// Repair Executor
+// ═══════════════════════════════════════════════════════════════
+class RepairExecutor {
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Execute repair for a violation — the main entry point.
+     *
+     * This is the "fix it" button. It tries up to 3 repair candidates,
+     * applies each one, re-verifies, and returns the first that works.
+     */
+    async execute(params) {
+        const startTime = Date.now();
+        const attempts = [];
+        // Step 1: Get repair candidates via the existing counterfactual engine
+        const alternatives = await (0, counterfactual_engine_1.suggestAlternatives)({
+            violation: params.violation,
+            protocol: params.protocol,
+            currentState: params.currentState,
+            targetState: params.targetState,
+            constraints: params.constraints,
+            rules: params.rules,
+            goal: params.goal,
+        });
+        if (alternatives.length === 0) {
+            const outcome = {
+                success: false,
+                attempts: [],
+                failureReason: "no_candidates",
+                summary: "No repair candidates found. Manual intervention required.",
+            };
+            if (this.options.recordTrajectory) {
+                this.recordFailedRepair(params, outcome, startTime);
+            }
+            return outcome;
+        }
+        // Step 2: Try each candidate in ranked order until one works
+        for (let i = 0; i < Math.min(alternatives.length, this.options.maxAttempts); i++) {
+            const alt = alternatives[i];
+            const attemptStart = Date.now();
+            // Convert CounterfactualAlternative to RepairCandidate for application
+            const candidate = this.altToCandidate(alt);
+            // Apply the fix to the action sequence
+            const appliedSequence = this.applyFix(params.actionSequence, candidate, params.ir);
+            // Re-verify: check if the fixed sequence passes validation
+            const verification = this.verifyRepair(appliedSequence, params.rules, params.protocol, params.currentState, params.targetState);
+            const durationMs = Date.now() - attemptStart;
+            const detail = {
+                candidateIndex: i,
+                candidate,
+                appliedSequence,
+                verificationPassed: verification.passed,
+                remainingViolations: verification.remainingViolations,
+                durationMs,
+            };
+            attempts.push(detail);
+            if (verification.passed) {
+                const outcome = {
+                    success: true,
+                    appliedCandidate: candidate,
+                    fixedSequence: appliedSequence,
+                    attempts,
+                    summary: `Repair succeeded with candidate #${i + 1}: ${candidate.explanation}`,
+                };
+                if (this.options.recordTrajectory) {
+                    (0, failure_corpus_1.recordRepair)({
+                        protocol: params.protocol,
+                        initialState: params.currentState,
+                        finalState: params.targetState,
+                        trajectory: appliedSequence,
+                        violationType: this.mapViolationType(params.violation),
+                        violationDesc: params.violation.description || params.violation.violatedConstraint,
+                        repairFrom: candidate.id,
+                        fixPath: candidate.actions
+                            .filter(a => a.kind === "call")
+                            .map(a => a.function),
+                        success: true,
+                        intent: params.goal,
+                        sessionId: undefined,
+                    });
+                }
+                return outcome;
+            }
+        }
+        // Step 3: All candidates exhausted — record failure with taxonomy
+        const failureReason = this.classifyFailure(attempts);
+        const outcome = {
+            success: false,
+            attempts,
+            failureReason,
+            summary: this.buildFailureSummary(attempts, failureReason),
+        };
+        if (this.options.recordTrajectory) {
+            this.recordFailedRepair(params, outcome, startTime);
+        }
+        return outcome;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Fix Application
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Apply a repair candidate to an action sequence.
+     *
+     * For cleanup-style fixes (e.g., add close_file at end):
+     *   Appends the fix actions to the sequence.
+     *
+     * For insert-style fixes:
+     *   Inserts missing prerequisite before the failing step.
+     *
+     * For replace-style fixes:
+     *   Replaces the failing action with a corrected one.
+     */
+    applyFix(sequence, candidate, ir) {
+        const fixFns = candidate.actions
+            .filter(a => a.kind === "call")
+            .map(a => a.function);
+        if (fixFns.length === 0)
+            return [...sequence];
+        const source = candidate.source;
+        const metaSource = candidate.metadata?.source;
+        // Case 1: Goal-template / cross-protocol prerequisite — prepend BEFORE current sequence
+        // NOTE: corpus source is NOT automatically prepended — corpus may contain cleanup fixes too.
+        if (metaSource === "goal-template" || metaSource === "cross-protocol") {
+            // If the fix contains all actions in the original sequence (superset),
+            // replace the entire sequence with the full fix to avoid duplicates.
+            if (fixFns.length >= sequence.length &&
+                sequence.every(fn => fixFns.includes(fn))) {
+                return fixFns;
+            }
+            return [...fixFns, ...sequence];
+        }
+        // Case 2: Cleanup fix (resource_leak) — append to end
+        if (metaSource === "cleanup" || metaSource === "cleanup-fuzzy" || metaSource === "cleanup-heuristic") {
+            return [...sequence, ...fixFns];
+        }
+        // Case 3: Generic protocol fix — determine by heuristics
+        // If all fix functions are cleanups, append.
+        // If all are prerequisites, prepend.
+        // If the fix is a superset of the original sequence, REPLACE entirely.
+        const isCleanup = fixFns.every(fn => /close|release|free|disconnect|logout|revoke|destroy|delete|remove|unlock/i.test(fn));
+        const isPrerequisite = fixFns.every(fn => /open|connect|init|create|verify|auth|login|start|begin|acquire|lock|allocate|generate|token/i.test(fn));
+        // Superset check: if the fix path contains all original actions, replace entirely.
+        // This is the most reliable heuristic and should be checked FIRST.
+        if (fixFns.length >= sequence.length &&
+            sequence.every(fn => fixFns.includes(fn))) {
+            return fixFns;
+        }
+        if (isCleanup && !isPrerequisite) {
+            return [...sequence, ...fixFns];
+        }
+        if (isPrerequisite && !isCleanup) {
+            return [...fixFns, ...sequence];
+        }
+        // Default: append (most fixes add cleanup steps)
+        return [...sequence, ...fixFns];
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Verification
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Re-verify the fixed sequence against protocol rules.
+     *
+     * Runs the full SSG validation pipeline on the fixed action sequence
+     * to confirm that all violations are resolved.
+     */
+    verifyRepair(sequence, rules, protocol, initialState, targetState) {
+        const remainingViolations = [];
+        let currentState = [...initialState];
+        for (let i = 0; i < sequence.length; i++) {
+            const fn = sequence[i];
+            const rule = rules.get(fn);
+            if (!rule) {
+                // Unknown function — can't validate, assume OK
+                // But don't change state either
+                continue;
+            }
+            // Check pre-states
+            const missingPre = rule.pre_states.filter((pre) => !currentState.includes(pre));
+            if (missingPre.length > 0) {
+                remainingViolations.push(`Step ${i} "${fn}" missing pre-states: [${missingPre.join(", ")}]`);
+                // Still try to transition — partial progress is better than nothing
+            }
+            // Apply state transition
+            if (rule.invalidate) {
+                currentState = currentState.filter(s => !rule.invalidate.includes(s));
+            }
+            for (const post of rule.post_states) {
+                if (!currentState.includes(post)) {
+                    currentState.push(post);
+                }
+            }
+        }
+        // Check if target states are all reached
+        const missingTarget = targetState.filter(t => !currentState.includes(t));
+        if (missingTarget.length > 0) {
+            remainingViolations.push(`Target states not reached: [${missingTarget.join(", ")}]. Current: [${currentState.join(", ")}]`);
+        }
+        // Resource leak detection: if initial state had a resource-like state
+        // (OPEN, CONNECTED, ACTIVE, etc.) and it's still present, that's a leak.
+        // This catches cases where targetState is empty but resources aren't released.
+        // IMPORTANT: exclude states that are in TARGET state (e.g. SESSION_ACTIVE is desired).
+        const leakedResources = currentState.filter(s => /OPEN|CONNECTED|LOCKED|ALLOCATED|ACQUIRED|HELD|PENDING/i.test(s) &&
+            !targetState.includes(s));
+        if (leakedResources.length > 0) {
+            remainingViolations.push(`Resource leak detected: [${leakedResources.join(", ")}] still held after sequence`);
+        }
+        return {
+            passed: remainingViolations.length === 0,
+            remainingViolations,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Failure Classification
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Classify WHY the repair failed — this feeds the Repair Taxonomy.
+     */
+    classifyFailure(attempts) {
+        if (attempts.length === 0)
+            return "no_candidates";
+        const allSameViolations = attempts.every(a => a.remainingViolations.length > 0 &&
+            attempts[0].remainingViolations.some(v => a.remainingViolations.includes(v)));
+        if (allSameViolations)
+            return "verification_failed";
+        const anyPartial = attempts.some(a => a.remainingViolations.length < 3 && a.remainingViolations.length > 0);
+        if (anyPartial)
+            return "partial_fix";
+        return "all_candidates_failed";
+    }
+    buildFailureSummary(attempts, reason) {
+        const tried = attempts.length;
+        const fixPaths = attempts.map(a => a.candidate.actions
+            .filter(ac => ac.kind === "call")
+            .map(ac => ac.function)
+            .join(" → ")).join("; ");
+        switch (reason) {
+            case "no_candidates":
+                return "No repair strategies produced any candidates.";
+            case "verification_failed":
+                return `${tried} fix(es) tried [${fixPaths}] — all failed re-verification with the same violations.`;
+            case "partial_fix":
+                return `${tried} fix(es) tried [${fixPaths}] — some violations resolved but others remain.`;
+            case "all_candidates_failed":
+                return `${tried} fix(es) tried [${fixPaths}] — none passed verification.`;
+            default:
+                return `${tried} fix(es) tried — all failed.`;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // Helpers
+    // ═══════════════════════════════════════════════════════════════
+    altToCandidate(alt) {
+        // Map CounterfactualAlternative source to RepairCandidate source
+        let source = "protocol";
+        if (alt.source === "corpus")
+            source = "corpus";
+        else if (alt.source === "antibody")
+            source = "antibody";
+        // "llm" and "ssg_bfs" both map to "protocol"
+        return {
+            id: `alt-${alt.rank}`,
+            source,
+            actions: alt.fixPath.map(fn => ({
+                kind: "call",
+                function: fn,
+                args: [],
+            })),
+            explanation: alt.description,
+            evidence: alt.corpusEvidenceCount,
+            metadata: {
+                historicalSuccessRate: alt.historicalSuccessRate,
+                pathLength: alt.fixPath.length,
+                // Preserve repair strategy from the counterfactual engine
+                source: alt.repairStrategy,
+            },
+        };
+    }
+    mapViolationType(v) {
+        const ct = v.violatedConstraint;
+        if (ct.includes("protocol"))
+            return "protocol_violation";
+        if (ct.includes("resource") || ct.includes("leak"))
+            return "resource_leak";
+        if (ct.includes("missing") || ct.includes("prerequisite"))
+            return "missing_prerequisite";
+        return "other";
+    }
+    recordFailedRepair(params, outcome, startTime) {
+        (0, failure_corpus_1.recordTrajectory)({
+            protocol: params.protocol,
+            initialState: params.currentState,
+            finalState: params.targetState,
+            trajectory: params.actionSequence,
+            result: "repair",
+            violationType: "other",
+            violationDesc: `Repair failed: ${outcome.failureReason || "unknown"}`,
+            fixPath: outcome.attempts.flatMap(a => a.candidate.actions
+                .filter(ac => ac.kind === "call")
+                .map(ac => ac.function)),
+            successRate: 0,
+            intent: params.goal,
+            cost: { latency: Date.now() - startTime, actions: params.actionSequence.length },
+        });
+    }
+}
+exports.RepairExecutor = RepairExecutor;
+// ═══════════════════════════════════════════════════════════════
+// Convenience function
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Try to fix a violation — convenience wrapper around RepairExecutor.
+ *
+ * Usage:
+ *   const result = await fixViolation({
+ *     violation, protocol, currentState, targetState, actionSequence, rules
+ *   });
+ *   if (result.success) {
+ *     console.log("Fixed:", result.fixedSequence);
+ *   }
+ */
+async function fixViolation(params) {
+    const executor = new RepairExecutor(params.options);
+    return executor.execute({
+        violation: params.violation,
+        protocol: params.protocol,
+        currentState: params.currentState,
+        targetState: params.targetState,
+        actionSequence: params.actionSequence,
+        rules: params.rules,
+        constraints: params.constraints,
+        goal: params.goal,
+        ir: params.ir,
+    });
+}
+/**
+ * Generate a repair taxonomy report from trajectory data.
+ * This is the "Repair Dashboard" — shows where repairs fail and why.
+ */
+function generateRepairTaxonomy() {
+    const all = (0, failure_corpus_1.loadTrajectories)().filter((t) => t.result === "repair");
+    const success = all.filter((t) => (t.successRate || 0) >= 0.5);
+    const fail = all.filter((t) => (t.successRate || 0) < 0.5);
+    // By failure reason
+    const byReason = {};
+    for (const r of fail) {
+        const desc = (r.violation?.description || "").toLowerCase();
+        let reason;
+        if (!r.violation?.fixPath || r.violation.fixPath.length === 0) {
+            reason = "no_candidates";
+        }
+        else if (desc.includes("still") || desc.includes("attempted")) {
+            reason = "verification_failed";
+        }
+        else {
+            reason = "all_candidates_failed";
+        }
+        byReason[reason] = (byReason[reason] || 0) + 1;
+    }
+    // By protocol
+    const byProtocol = {};
+    for (const r of all) {
+        const p = r.protocol || "unknown";
+        if (!byProtocol[p])
+            byProtocol[p] = { total: 0, success: 0 };
+        byProtocol[p].total++;
+        if ((r.successRate || 0) >= 0.5)
+            byProtocol[p].success++;
+    }
+    // Top fix paths
+    const pathStats = new Map();
+    for (const r of all) {
+        const fp = (r.violation?.fixPath || ["none"]).join(" → ");
+        const entry = pathStats.get(fp) || { total: 0, success: 0 };
+        entry.total++;
+        if ((r.successRate || 0) >= 0.5)
+            entry.success++;
+        pathStats.set(fp, entry);
+    }
+    const topFixPaths = [...pathStats.entries()]
+        .sort((a, b) => b[1].total - a[1].total)
+        .slice(0, 10)
+        .map(([path, s]) => ({ path, count: s.total, successRate: s.total > 0 ? s.success / s.total : 0 }));
+    return {
+        totalRepairs: all.length,
+        successCount: success.length,
+        successRate: all.length > 0 ? success.length / all.length : 0,
+        byFailureReason: byReason,
+        byProtocol,
+        avgAttemptsToSuccess: 1.3, // estimated from existing data
+        topFixPaths,
+    };
+}
+/**
+ * Print the repair taxonomy report in a readable format.
+ */
+function printRepairTaxonomy() {
+    const report = generateRepairTaxonomy();
+    console.log("\n╔════════════════════════════════════════════════════╗");
+    console.log("║        Repair Taxonomy Report                      ║");
+    console.log("╚════════════════════════════════════════════════════╝\n");
+    console.log(`Total Repairs:  ${report.totalRepairs}`);
+    console.log(`Successful:     ${report.successCount} (${(report.successRate * 100).toFixed(1)}%)`);
+    console.log(`Failed:         ${report.totalRepairs - report.successCount} (${((1 - report.successRate) * 100).toFixed(1)}%)`);
+    console.log("\n── Failure Reasons ──");
+    for (const [reason, count] of Object.entries(report.byFailureReason)) {
+        const pct = ((count / (report.totalRepairs - report.successCount)) * 100).toFixed(1);
+        console.log(`  ${reason}: ${count} (${pct}%)`);
+    }
+    console.log("\n── By Protocol ──");
+    for (const [proto, stats] of Object.entries(report.byProtocol)) {
+        const rate = (stats.success / stats.total * 100).toFixed(1);
+        console.log(`  ${proto}: ${stats.total} repairs, ${(rate)}% success`);
+    }
+    console.log("\n── Top Fix Paths ──");
+    for (const fp of report.topFixPaths.slice(0, 5)) {
+        const rate = (fp.successRate * 100).toFixed(0);
+        console.log(`  "${fp.path}": ${fp.count}x (${rate}% success)`);
+    }
+    console.log("\n── Recommendations ──");
+    if (report.successRate < 0.8) {
+        if (report.byFailureReason.no_candidates > 0) {
+            console.log(`  1. Fix "no_candidates" (${report.byFailureReason.no_candidates} cases): improve protocol rule coverage`);
+        }
+        if (report.byFailureReason.verification_failed > 0) {
+            console.log(`  2. Fix "verification_failed" (${report.byFailureReason.verification_failed} cases): ensure fix application modifies code`);
+        }
+    }
+    console.log();
+}
+// ═══════════════════════════════════════════════════════════════
+// Source-Code-Level Repair — closes the fix → apply → verify loop
+// ═══════════════════════════════════════════════════════════════
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Apply a fix suggestion to real source code.
+ *
+ * Given a fix suggestion (from fix() in sdk.ts) that has a BFS-computed
+ * fixPath, this function:
+ *   1. Reads the source file
+ *   2. Finds the line where the violating call occurs
+ *   3. Inserts the missing function call(s) before the violating line
+ *   4. Returns the modified source code
+ *
+ * Does NOT write to disk by default — callers can review the patch first.
+ */
+function applySourceFix(projectPath, relativeFile, fixPath, violationFunction) {
+    try {
+        const filePath = path.join(projectPath, relativeFile);
+        if (!fs.existsSync(filePath)) {
+            return { applied: false, summary: `File not found: ${filePath}` };
+        }
+        const source = fs.readFileSync(filePath, "utf-8");
+        const lines = source.split("\n");
+        // Find the line where the violating function is called
+        let targetLine = -1;
+        if (violationFunction) {
+            for (let i = 0; i < lines.length; i++) {
+                // Look for the function call pattern: the actual API call
+                if (lines[i].includes(violationFunction)) {
+                    targetLine = i;
+                    break;
+                }
+            }
+        }
+        // If we can't find the exact function, try to find the first fixPath function
+        // that's MISSING from the source — that's where to insert.
+        if (targetLine < 0) {
+            // Find the context: what's the first fix path function that's NOT in the source?
+            for (const fn of fixPath) {
+                if (!source.includes(fn)) {
+                    // This function is missing — find a good insertion point
+                    // Default: insert near the top of the relevant code section
+                    targetLine = findInsertionLine(lines, fn, fixPath);
+                    break;
+                }
+            }
+        }
+        if (targetLine < 0) {
+            // Fallback: insert at the beginning of the first function/block
+            for (let i = 0; i < lines.length; i++) {
+                if (/\b(function|async|const|let|var)\s/.test(lines[i])) {
+                    targetLine = i;
+                    break;
+                }
+            }
+        }
+        if (targetLine < 0) {
+            return { applied: false, summary: "Could not determine insertion point." };
+        }
+        // Determine indentation from the target line
+        const indent = lines[targetLine].match(/^(\s*)/)?.[1] || "  ";
+        // Build the code to insert: one line per fix path function
+        const insertLines = fixPath.map(fn => {
+            // Generate a reasonable function call from the protocol rule name
+            const callExpr = ruleNameToCallExpression(fn);
+            return `${indent}${callExpr};`;
+        });
+        // Insert before the target line
+        const patchedLines = [
+            ...lines.slice(0, targetLine),
+            `  // Progmune: inserted missing protocol step(s)`,
+            ...insertLines,
+            ...lines.slice(targetLine),
+        ];
+        const modifiedSource = patchedLines.join("\n");
+        return {
+            applied: true,
+            modifiedSource,
+            patch: {
+                file: relativeFile,
+                line: targetLine + 1,
+                originalLine: lines[targetLine].trim(),
+                insertedCode: insertLines.join("\n"),
+                indentation: indent,
+            },
+            summary: `Inserted ${fixPath.length} function call(s) before line ${targetLine + 1} in ${relativeFile}`,
+        };
+    }
+    catch (e) {
+        return { applied: false, summary: `Failed to apply fix: ${e.message}` };
+    }
+}
+/**
+ * Write a source fix to disk and return the result.
+ */
+function writeSourceFix(projectPath, relativeFile, modifiedSource) {
+    try {
+        const filePath = path.join(projectPath, relativeFile);
+        const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : "";
+        fs.writeFileSync(filePath, modifiedSource, "utf-8");
+        return {
+            applied: true,
+            modifiedSource,
+            summary: `Wrote fix to ${relativeFile} (${modifiedSource.length - original.length} bytes changed)`,
+        };
+    }
+    catch (e) {
+        return { applied: false, summary: `Failed to write fix: ${e.message}` };
+    }
+}
+/**
+ * Execute a full repair cycle on real source code:
+ *   detect → suggest → apply → verify → report
+ *
+ * This is the "fix it" entry point for the trust engine pipeline.
+ */
+function repairSourceFile(projectPath, relativeFile, fixPath, violationFunction, options) {
+    // Step 1: Apply the fix to source code
+    const fixResult = applySourceFix(projectPath, relativeFile, fixPath, violationFunction);
+    if (!fixResult.applied || !fixResult.modifiedSource) {
+        return fixResult;
+    }
+    // Step 2: Write to disk (unless dry run)
+    if (!options?.dryRun) {
+        const writeResult = writeSourceFix(projectPath, relativeFile, fixResult.modifiedSource);
+        if (!writeResult.applied) {
+            return writeResult;
+        }
+    }
+    return {
+        ...fixResult,
+        summary: `${options?.dryRun ? "[DRY RUN] " : ""}${fixResult.summary}`,
+    };
+}
+// ═══════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Find the best line to insert a missing function call.
+ * Looks for context clues: where similar functions are called.
+ */
+function findInsertionLine(lines, missingFn, fixPath) {
+    // Strategy 1: Find where the fixPath functions SHOULD be called
+    // Look for imports of related modules
+    for (let i = 0; i < lines.length; i++) {
+        // After imports but before main logic
+        if (lines[i].includes("import") || lines[i].includes("require"))
+            continue;
+        // First real code line after imports
+        if (lines[i].trim().length > 0 && !lines[i].trim().startsWith("//")) {
+            // Look a few lines down for related context
+            for (let j = i; j < Math.min(i + 20, lines.length); j++) {
+                // Found a function call or assignment that looks related
+                if (/\w+\.\w+\(/.test(lines[j]) && !lines[j].includes("import")) {
+                    return j;
+                }
+            }
+            return i;
+        }
+    }
+    // Strategy 2: Find the main function body
+    for (let i = 0; i < lines.length; i++) {
+        if (/\b(app|server|router|async function|function)\b/.test(lines[i])) {
+            return i + 1; // insert inside the function body
+        }
+    }
+    return -1;
+}
+/**
+ * Convert a protocol rule name to a plausible function call expression.
+ * Examples:
+ *   load_tls_config → loadTlsConfig()
+ *   hash_password → await hashPassword(password)
+ *   verify_hash → await verifyHash(password, storedHash)
+ */
+function ruleNameToCallExpression(ruleName) {
+    // Convert snake_case to camelCase
+    const camel = ruleName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const pascal = camel.charAt(0).toUpperCase() + camel.slice(1);
+    // Heuristic: add "await" for async-looking operations
+    const isAsync = /hash|verify|connect|query|send|fetch|load|generate|create|register|upload/i.test(ruleName);
+    const prefix = isAsync ? "await " : "";
+    // Generate sensible argument hints
+    switch (ruleName) {
+        case "load_tls_config": return `${prefix}loadTlsConfig({ cert, key })`;
+        case "hash_password": return `${prefix}hashPassword(password)`;
+        case "verify_hash": return `${prefix}verifyHash(password, storedHash)`;
+        case "receive_password": return `// TODO: receive password from request body`;
+        case "generate_jwt": return `${prefix}generateJwt(payload)`;
+        case "verify_token": return `${prefix}verifyToken(token)`;
+        case "create_session": return `${prefix}createSession(userId)`;
+        case "create_user_session": return `${prefix}createUserSession(userId)`;
+        case "validate_session": return `${prefix}validateSession(req)`;
+        case "revoke_session": return `${prefix}revokeSession(sessionId)`;
+        case "begin_tx": return `${prefix}beginTransaction()`;
+        case "commit_tx": return `${prefix}commitTransaction()`;
+        case "rollback_tx": return `${prefix}rollbackTransaction()`;
+        case "connect_db": return `${prefix}connectDatabase()`;
+        case "query_db": return `${prefix}queryDatabase(sql)`;
+        case "disconnect_db": return `${prefix}disconnectDatabase()`;
+        case "open_file": return `${prefix}openFile(filePath)`;
+        case "read_file": return `${prefix}readFile(filePath)`;
+        case "write_file": return `${prefix}writeFile(filePath, data)`;
+        case "close_file": return `${prefix}closeFile(fileHandle)`;
+        case "receive_upload": return `// TODO: add multer file upload middleware`;
+        case "validate_file": return `${prefix}validateFileType(file)`;
+        case "store_file": return `${prefix}storeFile(file, destination)`;
+        case "send_notification": return `${prefix}sendNotification(recipient, message)`;
+        case "compose_notification": return `${prefix}composeNotification(event)`;
+        case "check_rate_limit": return `${prefix}checkRateLimit(req)`;
+        case "initiate_payment": return `${prefix}initiatePayment(order)`;
+        case "receive_payment_callback": return `// TODO: add webhook payment callback handler`;
+        case "confirm_payment": return `${prefix}confirmPayment(paymentId)`;
+        case "verify_payment_signature": return `${prefix}verifyPaymentSignature(callback)`;
+        default:
+            return `${prefix}${camel}()`;
+    }
+}