sela-core 1.0.6 → 1.0.8

package/dist/services/ASTSourceUpdater.js

@@ -37,6 +37,9 @@ exports.ASTSourceUpdater = void 0;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ts_morph_1 = require("ts-morph");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
+const SelaError_1 = require("../errors/SelaError");
 const HealingRegistry_1 = require("../engine/HealingRegistry");
 const ArgumentTypeAnalyzer_1 = require("./ArgumentTypeAnalyzer");
 const BlastRadiusAnalyzer_1 = require("./BlastRadiusAnalyzer");
@@ -47,7 +50,7 @@ const CrossFileHealer_1 = require("./CrossFileHealer");
 const HealingAdvisory_1 = require("./HealingAdvisory");
 const ChainValidator_1 = require("./ChainValidator");
 // ═══════════════════════════════════════════════════════════════════
-// FIX #1 — normalizeSelector utility
+// FIX #1 - normalizeSelector utility
 // ═══════════════════════════════════════════════════════════════════
 function normalizeSelector(s) {
     return s
@@ -67,7 +70,7 @@ function normalizeSelector(s) {
 // of "varName", or null otherwise.
 //
 // Why this matters:
-//   const shadowBtn = shadowBtn.getByRole(…)   ← CIRCULAR — must be caught
+//   const shadowBtn = shadowBtn.getByRole(…)   ← CIRCULAR - must be caught
 //   const shadowBtn = page.getByRole(…)        ← CORRECT
 //
 // We walk UP the ancestor chain from the call node looking for a
@@ -80,7 +83,7 @@ function getEnclosingVariableDeclaration(node) {
         if (ts_morph_1.Node.isVariableDeclaration(current)) {
             return current;
         }
-        // Stop climbing past statement boundaries — we only want the immediate
+        // Stop climbing past statement boundaries - we only want the immediate
         // enclosing declaration, not a declaration somewhere further up the tree.
         if (ts_morph_1.Node.isBlock(current) ||
             ts_morph_1.Node.isSourceFile(current) ||
@@ -118,7 +121,7 @@ function isInsideOwnInitializer(callNode, varName) {
 function resolveSafeReceiver(proposedReceiver, rootReceiver, callNode) {
     if (isInsideOwnInitializer(callNode, proposedReceiver)) {
         console.log(`[ScopeGuard] 🔒 Circular reference prevented: ` +
-            `"${proposedReceiver}" is being initialized — ` +
+            `"${proposedReceiver}" is being initialized - ` +
             `falling back to root receiver "${rootReceiver}"`);
         return rootReceiver;
     }
@@ -551,7 +554,7 @@ class MethodMapper {
         for (const seg of segments) {
             const callText = MethodMapper.build(currentReceiver, seg);
             if (callText === null) {
-                console.warn(`[MethodMapper] Cannot build segment type "${seg.type}" — aborting chain`);
+                console.warn(`[MethodMapper] Cannot build segment type "${seg.type}" - aborting chain`);
                 return null;
             }
             const methodPart = callText.slice(currentReceiver.length);
@@ -614,7 +617,7 @@ function deduplicateChainSegments(aiSegments, contextSegments) {
     if (overlap === 0)
         return { deduped: aiSegments, stripped: 0 };
     console.log(`[ChainDedup] ✂️  Stripping ${overlap}/${contextSegments.length} duplicate leading ` +
-        `segment(s) — context already encodes them`);
+        `segment(s) - context already encodes them`);
     return { deduped: aiSegments.slice(overlap), stripped: overlap };
 }
 const PAGE_ROOT_NAMES = new Set([
@@ -723,7 +726,34 @@ function resolveVariableToSegments(sourceFile, varName, beforeLine, depth = 0) {
     };
 }
 // ═══════════════════════════════════════════════════════════════════
-// NODE TRANSFORMATION STRATEGY — Scope-Aware, Zero-Redundancy
+// SHARED PERSISTENCE HOOK
+//
+// Module-level write gate shared between `ASTSourceUpdater` and the
+// internal `NodeTransformationStrategy`. Centralises three concerns
+// every `saveSync` call site needs:
+//   1. `DryRunGuard.active()` short-circuit - keeps the mutation in
+//      memory but suppresses the on-disk write under SELA_DRY_RUN.
+//   2. `sharedWorkspaceSnapshot.preWrite()` - captures `contentBefore`
+//      so the Clean-Room ledger / Local DX rollback can rewind.
+//   3. `sharedWorkspaceSnapshot.postWrite()` - refreshes `contentAfter`
+//      so `getMutatedSnapshots()` (driving the pending-prompts ledger
+//      and the interactive CLI prompt) sees the new disk state.
+//
+// Strategies do NOT receive the persistence service via DI - they call
+// this helper directly. Same singleton, zero coupling, one code path.
+// ═══════════════════════════════════════════════════════════════════
+function persistSourceFile(sourceFile) {
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        DryRunGuard_1.DryRunGuard.logSkippedWrite("saveSync", sourceFile.getFilePath());
+        return;
+    }
+    const fp = sourceFile.getFilePath();
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(fp);
+    sourceFile.saveSync();
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(fp);
+}
+// ═══════════════════════════════════════════════════════════════════
+// NODE TRANSFORMATION STRATEGY - Scope-Aware, Zero-Redundancy
 // ═══════════════════════════════════════════════════════════════════
 class NodeTransformationStrategy {
     chainValidator;
@@ -793,8 +823,10 @@ class NodeTransformationStrategy {
         // When AI's first segment TYPE matches the receiver variable's defining type
         // but with a different selector, the AI is replacing the receiver context.
         // Strategy: update the receiver variable's definition, then use remaining
-        // segments with the receiver var — preserving developer's variable structure.
-        if (!forcedReceiver && discoveredAstRoot && !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
+        // segments with the receiver var - preserving developer's variable structure.
+        if (!forcedReceiver &&
+            discoveredAstRoot &&
+            !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
             const typeCheckRes = resolveVariableToSegments(sourceFile, discoveredAstRoot, caller.line);
             if (typeCheckRes.segments.length > 0 && workingSegments.length > 0) {
                 const receiverDefType = typeCheckRes.segments[typeCheckRes.segments.length - 1].type;
@@ -893,8 +925,9 @@ class NodeTransformationStrategy {
             // to prevent.  Skip the candidate; the semantic gate owns this case.
             const firstArg = call.getArguments()[0];
             if (firstArg &&
-                (ts_morph_1.Node.isIdentifier(firstArg) || ts_morph_1.Node.isPropertyAccessExpression(firstArg))) {
-                console.log(`[NodeTransform] 🛑 skip — first arg is ${firstArg.getKindName()} ` +
+                (ts_morph_1.Node.isIdentifier(firstArg) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArg))) {
+                console.log(`[NodeTransform] 🛑 skip - first arg is ${firstArg.getKindName()} ` +
                     `"${firstArg.getText()}" (semantic dispatch owns definition-site mutations)`);
                 continue;
             }
@@ -906,12 +939,12 @@ class NodeTransformationStrategy {
             // Before we build code, we must verify that the proposed receiver
             // does not create a circular self-reference.
             //
-            // Case A — forcedReceiver is set (strip-and-force path):
+            // Case A - forcedReceiver is set (strip-and-force path):
             //   Check if the chainTop lives inside the initializer of that var.
             //   If yes, fall back to the actual AST root (e.g. "page").
             //
-            // Case B — no forced receiver:
-            //   Use astRoot directly — it was walked up from the call node and
+            // Case B - no forced receiver:
+            //   Use astRoot directly - it was walked up from the call node and
             //   is always either "page" or a stable variable reference.
             // ══════════════════════════════════════════════════════════════
             let effectiveReceiver;
@@ -959,7 +992,7 @@ class NodeTransformationStrategy {
                 `  ${newCode.split("\n")[0]}`);
             try {
                 chainTop.replaceWithText(newCode);
-                sourceFile.saveSync();
+                persistSourceFile(sourceFile);
                 return {
                     success: true,
                     reason: `scope-aware transform [${effectiveReceiver}]: ${resolvedSegments.length} segments`,
@@ -1146,7 +1179,7 @@ class NodeTransformationStrategy {
         console.log(`[NodeTransform] 🔬 Partial: segment[${changedIdx}] .${currentMethodName}() → ${newCallText}`);
         try {
             targetCall.replaceWithText(newCallText);
-            sourceFile.saveSync();
+            persistSourceFile(sourceFile);
             return {
                 success: true,
                 reason: `partial: seg[${changedIdx}] .${currentMethodName}() → .${newSeg.type}()`,
@@ -1161,7 +1194,7 @@ class NodeTransformationStrategy {
     }
     updateReceiverDefinition(sourceFile, varName, segType, newSelector, callerLine) {
         // Collect all matching declarations, then pick the closest one that
-        // appears strictly BEFORE callerLine — prevents accidentally updating
+        // appears strictly BEFORE callerLine - prevents accidentally updating
         // a same-named variable in a different test block that happens to be
         // within the 100-line distance window.
         const declarations = sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration);
@@ -1201,7 +1234,7 @@ class NodeTransformationStrategy {
             if (!ts_morph_1.Node.isStringLiteral(firstArg))
                 continue;
             firstArg.replaceWithText(`"${newSelector}"`);
-            sourceFile.saveSync();
+            persistSourceFile(sourceFile);
             return true;
         }
         return false;
@@ -1272,7 +1305,7 @@ class NodeTransformationStrategy {
                         .map((d) => `[TS${d.getCode()}] ${d.getMessageText()}`)
                         .join(", "));
                 if (/\.(getBy\w+|frameLocator)\s*\(/.test(code)) {
-                    console.warn(`[NodeTransform] ⚠️  Semantic method detected — bypassing validation`);
+                    console.warn(`[NodeTransform] ⚠️  Semantic method detected - bypassing validation`);
                     return true;
                 }
                 return false;
@@ -1529,6 +1562,112 @@ class ASTSourceUpdater {
     flushAdvisories() {
         this.advisoryBuffer.flush();
     }
+    /**
+     * Centralised write hook for every ts-morph `saveSync` call in this class.
+     * When `SELA_DRY_RUN` is active the AST mutation stays in memory but the
+     * on-disk file is left untouched - the heal pipeline can still compute a
+     * candidate diff via `sourceFile.getFullText()` and the report layer
+     * tags the event with `dryRun: true`.
+     */
+    _persistChanges(sourceFile) {
+        persistSourceFile(sourceFile);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // FAIL-FAST DIRECTIVE SCAN
+    //
+    // Walks the leading comment ranges of the failing statement (and the
+    // CallExpression node when it differs) looking for the directive
+    // `// sela-fail-fast`.  When found, throws `SelaError(ASTUpdater,
+    // AST_HEAL_DISABLED_BY_DIRECTIVE)` so SelaEngine can short-circuit
+    // BEFORE the LLM call and record a FailedEvent in the "Skipped by
+    // Developer" category.
+    //
+    // Implementation note - ts-morph's `Node.getLeadingCommentRanges()`
+    // returns `ts.CommentRange[]` (offsets, not text). We slice the full
+    // source text by `(pos, end)` to recover the raw comment for each
+    // range, matching both `//` line comments and `/* */` block comments
+    // with either `sela-fail-fast` or `@sela-fail-fast` spelling.
+    // ─────────────────────────────────────────────────────────────────
+    scanFailFastDirective(caller) {
+        const filePath = this.resolveFilePath(caller.filePath);
+        if (!filePath)
+            return { failFast: false };
+        let sourceFile = this.project.getSourceFile(filePath);
+        if (sourceFile) {
+            sourceFile.refreshFromFileSystemSync();
+        }
+        else {
+            sourceFile = this.project.addSourceFileAtPath(filePath);
+        }
+        if (caller.line <= 0)
+            return { failFast: false };
+        const failureNode = this.findNodeAtLine(sourceFile, caller.line);
+        if (!failureNode)
+            return { failFast: false };
+        const statement = this.getEnclosingStatement(failureNode);
+        // Collect candidate comment-owning nodes: enclosing statement (catches
+        // pre-statement comments) AND the failure node itself (catches inline
+        // pre-CallExpression comments inside multi-line chains). De-dup by
+        // offset to avoid double-matching.
+        const fullText = sourceFile.getFullText();
+        const seen = new Set();
+        const nodes = [];
+        if (statement)
+            nodes.push(statement);
+        if (failureNode !== statement)
+            nodes.push(failureNode);
+        const DIRECTIVE_RE = /\/[\/*]\s*@?sela-fail-fast\b/i;
+        for (const node of nodes) {
+            let ranges = [];
+            try {
+                ranges = node.getLeadingCommentRanges() ?? [];
+            }
+            catch {
+                ranges = [];
+            }
+            for (const r of ranges) {
+                const pos = r.getPos();
+                const end = r.getEnd();
+                const key = `${pos}:${end}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const text = fullText.slice(pos, end);
+                if (DIRECTIVE_RE.test(text)) {
+                    const lineNum = sourceFile.getLineAndColumnAtPos(pos).line;
+                    return {
+                        failFast: true,
+                        matchedComment: text.trim(),
+                        matchedLine: lineNum,
+                    };
+                }
+            }
+        }
+        return { failFast: false };
+    }
+    /**
+     * Convenience helper - runs `scanFailFastDirective` and throws the
+     * canonical SelaError when the directive is present. Used by SelaEngine
+     * as the very first gate inside `heal()`.
+     */
+    enforceFailFastDirective(caller) {
+        const result = this.scanFailFastDirective(caller);
+        if (!result.failFast)
+            return;
+        throw new SelaError_1.SelaError({
+            subsystem: "ASTUpdater",
+            code: SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE,
+            reason: `Heal disabled by developer directive at ${path.basename(caller.filePath)}` +
+                (result.matchedLine ? `:${result.matchedLine}` : ""),
+            context: {
+                filePath: caller.filePath,
+                line: caller.line,
+                directiveLine: result.matchedLine,
+                directiveText: result.matchedComment,
+                category: "Skipped by Developer",
+            },
+        });
+    }
     constructor() {
         this.project = new ts_morph_1.Project({
             useInMemoryFileSystem: false,
@@ -1654,7 +1793,7 @@ class ASTSourceUpdater {
             sourceFile = this.project.addSourceFileAtPath(filePath);
         }
         if (caller.line <= 0) {
-            console.log(`[ASTUpdater] ⚠️  line ${caller.line} invalid — Attempting Global Template Strategy`);
+            console.log(`[ASTUpdater] ⚠️  line ${caller.line} invalid - Attempting Global Template Strategy`);
             const globalResult = this.strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector);
             if (globalResult && globalResult.success) {
                 if (contentChange)
@@ -1673,6 +1812,14 @@ class ASTSourceUpdater {
         const statement = failureNode
             ? this.getEnclosingStatement(failureNode)
             : undefined;
+        // ─── Developer fail-fast directive ─────────────────────────────
+        // Scan leading comments on the enclosing statement (and the failure
+        // node when they differ) for `// sela-fail-fast`. When present, abort
+        // all heal work with SelaError(AST_HEAL_DISABLED_BY_DIRECTIVE) so the
+        // engine records a FailedEvent in the "Skipped by Developer" bucket.
+        // Defense-in-depth - SelaEngine also calls this at the very start of
+        // heal() to skip the LLM round-trip entirely.
+        this.enforceFailFastDirective(caller);
         const suspectIdentifier = statement
             ? this.identifySuspectIdentifier(statement, caller.line)
             : null;
@@ -1683,7 +1830,7 @@ class ASTSourceUpdater {
         // HARD EXIT: any non-null result (success OR failure) stops all
         // subsequent AST strategies.  When the locator argument is an
         // Identifier, PropertyAccess, or TemplateLiteral, the gate owns
-        // the mutation — NT/H must never override the symbolic reference.
+        // the mutation - NT/H must never override the symbolic reference.
         const semanticResult = this.semanticDispatch(sourceFile, caller, oldSelector, newSelector);
         if (semanticResult !== null) {
             if (semanticResult.success) {
@@ -1692,7 +1839,7 @@ class ASTSourceUpdater {
                 }
                 return this.broadcastAndReturn(semanticResult, oldSelector, newSelector, caller);
             }
-            // Failure (blast-radius block, trace failed, syntax error) — hard stop.
+            // Failure (blast-radius block, trace failed, syntax error) - hard stop.
             console.log(`[SemanticDispatch] 🚫 Hard stop (${semanticResult.strategy}): ${semanticResult.reason}`);
             return semanticResult;
         }
@@ -1741,7 +1888,7 @@ class ASTSourceUpdater {
         };
     }
     // ═══════════════════════════════════════════════════════════════
-    // STRATEGY H — Smart Chain (Legacy fallback)
+    // STRATEGY H - Smart Chain (Legacy fallback)
     // ═══════════════════════════════════════════════════════════════
     strategySmartChain(sourceFile, caller, oldSelector, oldSem, smartSegments, originalChainHint, suspectIdentifier) {
         console.log(`[ASTUpdater] 🔗 Strategy H v2: Smart Chain (${smartSegments.length} segments)`);
@@ -1815,13 +1962,14 @@ class ASTSourceUpdater {
             return b.chainDepth - a.chainDepth;
         });
         for (const { leafCall, chainTop, rootReceiver, chainDepth, originalText, } of candidates) {
-            // Identifier/PropertyAccess guard — mirrors the NT guard.
+            // Identifier/PropertyAccess guard - mirrors the NT guard.
             // Strategy H must never substitute a hardcoded string for a symbolic
             // reference; the semantic dispatch gate owns definition-site mutations.
             const firstArgH = leafCall.getArguments()[0];
             if (firstArgH &&
-                (ts_morph_1.Node.isIdentifier(firstArgH) || ts_morph_1.Node.isPropertyAccessExpression(firstArgH))) {
-                console.log(`[StrategyH] 🛑 skip — first arg is ${firstArgH.getKindName()} ` +
+                (ts_morph_1.Node.isIdentifier(firstArgH) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArgH))) {
+                console.log(`[StrategyH] 🛑 skip - first arg is ${firstArgH.getKindName()} ` +
                     `"${firstArgH.getText()}" (semantic dispatch owns definition-site mutations)`);
                 continue;
             }
@@ -1850,7 +1998,7 @@ class ASTSourceUpdater {
             console.log(`[ASTUpdater] 🔗 H: full replace (depth=${chainDepth}) →\n${newCode}`);
             try {
                 chainTop.replaceWithText(newCode);
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: `smart chain applied (${resolvedSegments.length} segments, depth=${chainDepth})`,
@@ -1891,8 +2039,9 @@ class ASTSourceUpdater {
         // Block H-partial from substituting a literal for an Identifier/PropertyAccess arg.
         const targetFirstArg = targetCall.getArguments()[0];
         if (targetFirstArg &&
-            (ts_morph_1.Node.isIdentifier(targetFirstArg) || ts_morph_1.Node.isPropertyAccessExpression(targetFirstArg))) {
-            console.log(`[H-partial] 🛑 skip — arg is ${targetFirstArg.getKindName()} ` +
+            (ts_morph_1.Node.isIdentifier(targetFirstArg) ||
+                ts_morph_1.Node.isPropertyAccessExpression(targetFirstArg))) {
+            console.log(`[H-partial] 🛑 skip - arg is ${targetFirstArg.getKindName()} ` +
                 `"${targetFirstArg.getText()}" (semantic dispatch owns this)`);
             return null;
         }
@@ -1914,7 +2063,7 @@ class ASTSourceUpdater {
         console.log(`[ASTUpdater] 🔗 H partial: .${currentMethodName}() → ${newCallText}`);
         try {
             targetCall.replaceWithText(newCallText);
-            sourceFile.saveSync();
+            this._persistChanges(sourceFile);
             return {
                 success: true,
                 reason: `partial chain heal: segment[${changedIdx}] .${currentMethodName}() → .${newSeg.type}()`,
@@ -1928,7 +2077,7 @@ class ASTSourceUpdater {
         }
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY F — Chain Collapse
+    // STRATEGY F - Chain Collapse
     // ─────────────────────────────────────────────────────────────
     strategyChainCollapse(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] ⛓️  Strategy F: Chain Collapse (upward traversal)`);
@@ -1975,7 +2124,7 @@ class ASTSourceUpdater {
             const newCallText = buildCallText(rootReceiver, newSem);
             try {
                 chainTop.replaceWithText(newCallText);
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: `chain collapsed atomically (depth=${chainDepth})`,
@@ -1994,7 +2143,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY G — Assertion Healing
+    // STRATEGY G - Assertion Healing
     // ─────────────────────────────────────────────────────────────
     runStrategyG(sourceFile, caller, locatorVarName, contentChange) {
         if (!contentChange)
@@ -2026,7 +2175,7 @@ class ASTSourceUpdater {
         return null;
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY A — Frame Upstream Healing
+    // STRATEGY A - Frame Upstream Healing
     // ─────────────────────────────────────────────────────────────
     strategyFrameUpstream(sourceFile, caller, oldElementSelector, aiSegments, fullSelectorContext) {
         console.log(`[ASTUpdater] 🧠 Strategy A: Frame Upstream`);
@@ -2059,7 +2208,7 @@ class ASTSourceUpdater {
                     }
                 }
                 if (anyFixed) {
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     return {
                         success: true,
                         reason: `upstream variable '${varName}' fixed`,
@@ -2070,7 +2219,7 @@ class ASTSourceUpdater {
                 for (const change of changedFrames) {
                     const result = this.replaceStringLiteralInRange(sourceFile, change.old, change.new, declLine, Math.min(sourceFile.getEndLineNumber(), declLine + 8));
                     if (result !== null) {
-                        sourceFile.saveSync();
+                        this._persistChanges(sourceFile);
                         return {
                             success: true,
                             reason: "multi-line frame fixed",
@@ -2085,7 +2234,7 @@ class ASTSourceUpdater {
             for (const change of changedFrames) {
                 const result = this.replaceStringLiteralInRange(sourceFile, change.old, change.new, Math.max(1, caller.line - 15), caller.line);
                 if (result !== null) {
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     return {
                         success: true,
                         reason: "inline frame fixed",
@@ -2102,7 +2251,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY B — Deep Symbol Resolution
+    // STRATEGY B - Deep Symbol Resolution
     // ─────────────────────────────────────────────────────────────
     strategyDeepSymbolResolution(sourceFile, caller, oldSelector, newSelector, oldSem, newSem, suspectIdentifier) {
         console.log(`[ASTUpdater] 🔭 Strategy B: Deep Symbol Resolution`);
@@ -2166,10 +2315,10 @@ class ASTSourceUpdater {
                     const newCallText = buildCallText(effectiveReceiver, newSem);
                     try {
                         chainTop.replaceWithText(newCallText);
-                        sourceFile.saveSync();
+                        this._persistChanges(sourceFile);
                         const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                         if (cascadePairs.length > 0) {
-                            sourceFile.saveSync();
+                            this._persistChanges(sourceFile);
                             HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                         }
                         return {
@@ -2208,10 +2357,10 @@ class ASTSourceUpdater {
                 const { chainTop: tailChainTop, rootReceiver } = climbToChainTop(tailCall);
                 try {
                     tailChainTop.replaceWithText(buildCallText(rootReceiver, newSem));
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                     if (cascadePairs.length > 0) {
-                        sourceFile.saveSync();
+                        this._persistChanges(sourceFile);
                         HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                     }
                     return {
@@ -2228,10 +2377,10 @@ class ASTSourceUpdater {
             }
             const fixed = this.replaceChainTailOnly(tailCall, newSem, newSelector);
             if (fixed) {
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                 if (cascadePairs.length > 0) {
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                 }
                 return {
@@ -2253,7 +2402,7 @@ class ASTSourceUpdater {
             if (chainDepth > 0 || isLeafOfChain(call)) {
                 try {
                     stmtChainTop.replaceWithText(buildCallText(rootReceiver, newSem));
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     return {
                         success: true,
                         reason: "direct statement chain collapse",
@@ -2264,10 +2413,10 @@ class ASTSourceUpdater {
                 catch { }
             }
             if (this.replaceChainTailOnly(call, newSem, newSelector)) {
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                 if (cascadePairs.length > 0) {
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                 }
                 return {
@@ -2286,7 +2435,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY C — Inline Semantic Fix
+    // STRATEGY C - Inline Semantic Fix
     // ─────────────────────────────────────────────────────────────
     strategyInlineSemanticFix(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] 🎯 Strategy C: Inline Semantic Fix`);
@@ -2301,10 +2450,10 @@ class ASTSourceUpdater {
                 try {
                     chainTop.replaceWithText(buildCallText(rootReceiver, newSem));
                     const fixLine = chainTop.getStartLineNumber();
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                     if (cascadePairs.length > 0) {
-                        sourceFile.saveSync();
+                        this._persistChanges(sourceFile);
                         HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                     }
                     return {
@@ -2319,10 +2468,10 @@ class ASTSourceUpdater {
             }
             if (this.applySemanticFix(call, newSem, newSelector)) {
                 const fixLine = call.getStartLineNumber();
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
                 if (cascadePairs.length > 0) {
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
                 }
                 return {
@@ -2344,7 +2493,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY D — Template Literal
+    // STRATEGY D - Template Literal
     // ─────────────────────────────────────────────────────────────
     strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector) {
         console.log(`[ASTUpdater] 🔤 Strategy D: Template Literal`);
@@ -2385,7 +2534,7 @@ class ASTSourceUpdater {
             if (newText !== fullText) {
                 tmpl.replaceWithText(newText.trim());
                 const line = tmpl.getStartLineNumber();
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: "template literal suffix updated",
@@ -2401,7 +2550,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY E — Semantic Fragment Scan
+    // STRATEGY E - Semantic Fragment Scan
     // ─────────────────────────────────────────────────────────────
     strategySemanticFragmentScan(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] 🔎 Strategy E: Semantic Fragment Scan`);
@@ -2430,7 +2579,7 @@ class ASTSourceUpdater {
             if (chainDepth > 0 || isLeafOfChain(call)) {
                 try {
                     chainTop.replaceWithText(buildCallText(rootReceiver, newSem));
-                    sourceFile.saveSync();
+                    this._persistChanges(sourceFile);
                     return {
                         success: true,
                         reason: `fragment scan chain collapse .${callSem.method}() @ line ${call.getStartLineNumber()}`,
@@ -2441,7 +2590,7 @@ class ASTSourceUpdater {
                 catch { }
             }
             if (this.replaceChainTailOnly(call, newSem, newSelector)) {
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: `fragment scan fixed .${callSem.method}() @ line ${call.getStartLineNumber()}`,
@@ -2522,7 +2671,7 @@ class ASTSourceUpdater {
     /**
      * Guard: returns false when replacing oldNode with proposedNewText would
      * substitute a hardcoded string literal for an Identifier or
-     * PropertyAccessExpression — which is the definition-site mutation bug.
+     * PropertyAccessExpression - which is the definition-site mutation bug.
      * All other replacements are allowed.
      */
     static isSafeReplacement(oldNode, proposedNewText) {
@@ -2546,7 +2695,7 @@ class ASTSourceUpdater {
                 firstArg.replaceWithText(`"${safe}"`);
             }
             else {
-                console.warn(`[ASTUpdater] ⚠️ replaceCallArgument: blocked unsafe replacement — ` +
+                console.warn(`[ASTUpdater] ⚠️ replaceCallArgument: blocked unsafe replacement - ` +
                     `arg is ${firstArg.getKindName()}, not a string literal. ` +
                     `Heal at definition site instead.`);
                 return false;
@@ -2618,7 +2767,7 @@ class ASTSourceUpdater {
             const propName = firstArg.getName();
             const result = this.updateObjectProperty(sourceFile, objName, propName, oldSem.primaryArg, newSem.primaryArg);
             if (result !== null) {
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: `'${objName}.${propName}' updated`,
@@ -2848,10 +2997,10 @@ class ASTSourceUpdater {
                     shape === "PROPERTY_ACCESS" ||
                     shape === "TEMPLATE_LITERAL") {
                     console.log(`[SemanticDispatch] 🛑 hard-block: "${node.getText()}" is ${shape} ` +
-                        `but trace failed — preserving call site`);
+                        `but trace failed - preserving call site`);
                     return {
                         success: false,
-                        reason: `semantic guard: could not trace "${node.getText()}" — call site preserved`,
+                        reason: `semantic guard: could not trace "${node.getText()}" - call site preserved`,
                         strategy: "semantic-guard",
                     };
                 }
@@ -2874,21 +3023,21 @@ class ASTSourceUpdater {
             if (blast.risk === "high") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
-                    message: `Mutation blocked — ${blast.testFunctionCount} tests reference this constant.`,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this constant.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Review all referencing tests before changing this constant.",
                 });
                 return {
                     success: false,
-                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this constant — manual review required`,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this constant - manual review required`,
                     strategy: "semantic-identifier",
                 };
             }
             if (blast.risk === "medium") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
-                    message: `Mutated constant used in ${blast.testFunctionCount} tests — verify no regressions.`,
+                    message: `Mutated constant used in ${blast.testFunctionCount} tests - verify no regressions.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Run the full test suite to confirm all references still pass.",
@@ -2900,7 +3049,7 @@ class ASTSourceUpdater {
             if (!this.validateFileSyntax(targetFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-identifier",
                 };
             }
@@ -2910,7 +3059,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-identifier",
                 lineUpdated: result.lineUpdated,
                 healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: targetFile.getFilePath(), line: result.lineUpdated },
+                definitionSite: {
+                    file: targetFile.getFilePath(),
+                    line: result.lineUpdated,
+                },
                 blastRadius: blast.testFunctionCount,
             };
         }
@@ -2939,21 +3091,21 @@ class ASTSourceUpdater {
             if (blast.risk === "high") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
-                    message: `Mutation blocked — ${blast.testFunctionCount} tests reference this property.`,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this property.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Review all referencing tests before changing this property.",
                 });
                 return {
                     success: false,
-                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this property — manual review required`,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this property - manual review required`,
                     strategy: "semantic-property-access",
                 };
             }
             if (blast.risk === "medium") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
-                    message: `Mutated property used in ${blast.testFunctionCount} tests — verify no regressions.`,
+                    message: `Mutated property used in ${blast.testFunctionCount} tests - verify no regressions.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Run the full test suite to confirm all references still pass.",
@@ -2965,7 +3117,7 @@ class ASTSourceUpdater {
             if (!this.validateFileSyntax(targetFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-property-access",
                 };
             }
@@ -2975,7 +3127,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-property-access",
                 lineUpdated: result.lineUpdated,
                 healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: targetFile.getFilePath(), line: result.lineUpdated },
+                definitionSite: {
+                    file: targetFile.getFilePath(),
+                    line: result.lineUpdated,
+                },
                 blastRadius: blast.testFunctionCount,
             };
         }
@@ -3019,10 +3174,11 @@ class ASTSourceUpdater {
                     }
                 }
             }
-            if (patchResult.reason.includes("structural") || patchResult.reason.includes("not found")) {
+            if (patchResult.reason.includes("structural") ||
+                patchResult.reason.includes("not found")) {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
-                    message: `Template literal requires structural change — automated patch skipped.`,
+                    message: `Template literal requires structural change - automated patch skipped.`,
                     affectedFile: sourceFile.getFilePath(),
                     affectedLine: node.getStartLineNumber() - 1,
                     suggestedAction: "Manually update the template literal and its callers.",
@@ -3032,11 +3188,11 @@ class ASTSourceUpdater {
         }
         const lineUpdated = node.getStartLineNumber() - 1;
         node.replaceWithText(patchResult.patchedTemplate);
-        sourceFile.saveSync();
+        this._persistChanges(sourceFile);
         if (!this.validateFileSyntax(sourceFile)) {
             return {
                 success: false,
-                reason: "post-mutation syntax validation failed — reverted",
+                reason: "post-mutation syntax validation failed - reverted",
                 strategy: "semantic-template",
             };
         }
@@ -3064,18 +3220,22 @@ class ASTSourceUpdater {
             if (ts_morph_1.Node.isCallExpression(init)) {
                 return this.handleCallExpressionArg(init, sourceFile, oldSpanVal, newSpanVal);
             }
-            if (ts_morph_1.Node.isStringLiteral(init) || ts_morph_1.Node.isNoSubstitutionTemplateLiteral(init)) {
+            if (ts_morph_1.Node.isStringLiteral(init) ||
+                ts_morph_1.Node.isNoSubstitutionTemplateLiteral(init)) {
                 const result = InitializerUpdater_1.InitializerUpdater.apply(init, sourceFile, newSpanVal);
                 if (!result)
                     return null;
-                sourceFile.saveSync();
+                this._persistChanges(sourceFile);
                 return {
                     success: true,
                     reason: `span literal updated via trace`,
                     strategy: "semantic-template",
                     lineUpdated: result.lineUpdated,
                     healedLocatorString: result.healedLocatorString,
-                    definitionSite: { file: sourceFile.getFilePath(), line: result.lineUpdated },
+                    definitionSite: {
+                        file: sourceFile.getFilePath(),
+                        line: result.lineUpdated,
+                    },
                 };
             }
             if (ts_morph_1.Node.isTemplateExpression(init)) {
@@ -3089,7 +3249,7 @@ class ASTSourceUpdater {
         if (fnAnalysis.kind === "complex") {
             this.advisoryBuffer.push({
                 code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_CONDITIONAL_RETURN,
-                message: `Function has conditional/complex return — automated patch skipped. Reason: ${fnAnalysis.reason}`,
+                message: `Function has conditional/complex return - automated patch skipped. Reason: ${fnAnalysis.reason}`,
                 affectedFile: sourceFile.getFilePath(),
                 suggestedAction: "Manually update the function's return expression.",
             });
@@ -3102,7 +3262,7 @@ class ASTSourceUpdater {
             if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-call-expression",
                 };
             }
@@ -3112,7 +3272,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-call-expression",
                 lineUpdated: result.lineUpdated,
                 healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: fnAnalysis.functionFile.getFilePath(), line: result.lineUpdated },
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: result.lineUpdated,
+                },
             };
         }
         if (fnAnalysis.kind === "template") {
@@ -3122,7 +3285,7 @@ class ASTSourceUpdater {
                 if (patchResult.reason.includes("structural")) {
                     this.advisoryBuffer.push({
                         code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
-                        message: `Function template return requires structural change — automated patch skipped.`,
+                        message: `Function template return requires structural change - automated patch skipped.`,
                         affectedFile: fnAnalysis.functionFile.getFilePath(),
                         affectedLine: fnAnalysis.functionLine - 1,
                         suggestedAction: "Manually update the function's template literal.",
@@ -3132,11 +3295,11 @@ class ASTSourceUpdater {
             }
             const lineUpdated = fnAnalysis.templateNode.getStartLineNumber() - 1;
             fnAnalysis.templateNode.replaceWithText(patchResult.patchedTemplate);
-            fnAnalysis.functionFile.saveSync();
+            this._persistChanges(fnAnalysis.functionFile);
             if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-call-expression",
                 };
             }
@@ -3146,7 +3309,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-call-expression",
                 lineUpdated,
                 healedLocatorString: newSelector,
-                definitionSite: { file: fnAnalysis.functionFile.getFilePath(), line: lineUpdated },
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: lineUpdated,
+                },
             };
         }
         return null;
@@ -3162,11 +3328,13 @@ class ASTSourceUpdater {
             return !ALLOWED_CODES.has(d.getCode());
         });
         if (syntaxErrors.length > 0) {
-            const msgs = syntaxErrors.map((d) => String(d.getMessageText())).join("; ");
-            console.warn(`[SemanticDispatch] ⚠️ syntax errors after mutation: ${msgs} — reverting`);
+            const msgs = syntaxErrors
+                .map((d) => String(d.getMessageText()))
+                .join("; ");
+            console.warn(`[SemanticDispatch] ⚠️ syntax errors after mutation: ${msgs} - reverting`);
             this.advisoryBuffer.push({
                 code: HealingAdvisory_1.AdvisoryCode.POST_MUTATION_TYPE_ERROR,
-                message: `Post-mutation type errors detected — mutation reverted. Errors: ${msgs}`,
+                message: `Post-mutation type errors detected - mutation reverted. Errors: ${msgs}`,
                 affectedFile: sourceFile.getFilePath(),
                 suggestedAction: "Manually inspect and fix the type errors introduced by this heal.",
             });