sela-core 1.0.5 → 1.0.7

package/dist/services/SafetyGuard.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SafetyGuard = void 0;
 const IntentAuditor_1 = require("./IntentAuditor");
+const SelaError_1 = require("../errors/SelaError");
 // ═══════════════════════════════════════════════════════════════════
 // DEFAULT THRESHOLDS  (match pre-config hardcoded values exactly)
 // ═══════════════════════════════════════════════════════════════════
@@ -55,6 +56,9 @@ const SEMANTIC_OPPOSITE_PAIRS = new Set([
     "valid|invalid",
     "invalid|valid",
 ]);
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 const ROLE_KEYWORDS = new Map([
     [
         "SUBMIT",
@@ -185,21 +189,47 @@ const ROLE_KEYWORDS = new Map([
         ]),
     ],
 ]);
-// ═══════════════════════════════════════════════════════════════════
-// SafetyGuard
-// ═══════════════════════════════════════════════════════════════════
+// Pre-compiled word-boundary regexes for the role classifier.  Built
+// once at module load — classifyFunctionalRole() is on the hot heal
+// path, so we don't pay for regex construction per call.
+const ROLE_KEYWORD_REGEXES = Array.from(ROLE_KEYWORDS, ([role, keywords]) => ({
+    role,
+    regexes: Array.from(keywords, (kw) => new RegExp(`\\b${escapeRegExp(kw)}\\b`, "i")),
+}));
 class SafetyGuard {
     intentAuditor;
     thresholds;
-    constructor(thresholds) {
-        this.thresholds = thresholds ?? DEFAULT_THRESHOLDS;
-        this.intentAuditor = new IntentAuditor_1.IntentAuditor();
+    /**
+     * Accepts either the legacy positional `thresholds` argument or an
+     * options bag (DI-friendly).  Existing call sites keep working
+     * unchanged.
+     */
+    constructor(arg) {
+        const opts = SafetyGuard.normalizeArgs(arg);
+        this.thresholds = opts.thresholds ?? DEFAULT_THRESHOLDS;
+        this.intentAuditor = opts.intentAuditor ?? new IntentAuditor_1.IntentAuditor();
+    }
+    static normalizeArgs(arg) {
+        if (!arg)
+            return {};
+        // Heuristic: an options bag has either `intentAuditor` or a nested
+        // `thresholds` field; otherwise the value itself is a ResolvedThresholds.
+        if ("intentAuditor" in arg || "thresholds" in arg) {
+            return arg;
+        }
+        return { thresholds: arg };
     }
     // ─────────────────────────────────────────────────────────────
     // PUBLIC ENTRY POINT
     // ─────────────────────────────────────────────────────────────
     async evaluate(context, aiFix) {
-        const { confidence, liveText, dnaBaselineText } = aiFix;
+        const { liveText, dnaBaselineText } = aiFix;
+        // Conservative fallback for missing confidence: treat as 0 so the
+        // hardStop / reviewThreshold rules still gate the heal. Reporting layers
+        // separately render the absence as "n/a" via fmtPct.
+        const confidence = typeof aiFix.confidence === "number" && Number.isFinite(aiFix.confidence)
+            ? aiFix.confidence
+            : 0;
         const { mode } = context;
         // ── 0. Visibility Gate ───────────────────────────────────────
         // Runs before any confidence or content checks.  A ghost element
@@ -211,6 +241,7 @@ class SafetyGuard {
             if (vis.isGhost) {
                 return {
                     level: "FAIL_HARD",
+                    code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_VISIBILITY_GHOST,
                     reason: `Visibility Gate: candidate element is a Ghost (${vis.ghostReason}) — ` +
                         `functionally absent from the user's perspective`,
                     canProceed: false,
@@ -221,6 +252,7 @@ class SafetyGuard {
                 if (isMainBranch) {
                     return {
                         level: "FAIL_HARD",
+                        code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_VISIBILITY_OCCLUDED,
                         reason: `Visibility Gate: candidate element is occluded by an overlay on branch "${context.branch}" — ` +
                             `hard-fail policy active on main`,
                         canProceed: false,
@@ -240,6 +272,7 @@ class SafetyGuard {
         if (confidence < this.thresholds.confidenceHardStop) {
             return {
                 level: "BLOCKED",
+                code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_LOW_CONFIDENCE,
                 reason: `Confidence too low (${confidence}/100 < ${this.thresholds.confidenceHardStop}) — refusing to heal`,
                 canProceed: false,
             };
@@ -284,6 +317,7 @@ class SafetyGuard {
         if (this.isSemanticOpposite(oldText, newText)) {
             return {
                 level: "FAIL_HARD",
+                code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_SEMANTIC_INVERSION,
                 reason: `Semantic inversion detected: "${oldText}" ↔ "${newText}" — ` +
                     `state inversions mask logical regressions`,
                 canProceed: false,
@@ -299,6 +333,7 @@ class SafetyGuard {
         if (isStatusInversion) {
             return {
                 level: "FAIL_HARD",
+                code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_STATUS_INVERSION,
                 reason: `Status inversion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) — ` +
                     `masking a logic failure is not permitted`,
                 canProceed: false,
@@ -313,6 +348,7 @@ class SafetyGuard {
                 // function being found is almost certainly a wrong element fix.
                 return {
                     level: "BLOCKED",
+                    code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_ROLE_SWAP_ASSERTION,
                     reason: `Functional role swap in assertion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) — ` +
                         `the assertion was verifying a specific functional state`,
                     canProceed: false,
@@ -355,6 +391,7 @@ class SafetyGuard {
             if (auditVerdict.verdict === "INCONSISTENT") {
                 return {
                     level: "FAIL_HARD",
+                    code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_AUDITOR_INCONSISTENT,
                     reason: `Intent Auditor — INCONSISTENT: ${auditVerdict.reason}` +
                         (auditVerdict.inversionType
                             ? ` [inversion: ${auditVerdict.inversionType}]`
@@ -371,6 +408,7 @@ class SafetyGuard {
                 if (!this.thresholds.allowSuspicious && mode === "assertion") {
                     return {
                         level: "BLOCKED",
+                        code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_AUDITOR_SUSPICIOUS,
                         reason: `Intent Auditor — SUSPICIOUS in assertion mode: ${auditVerdict.reason}`,
                         canProceed: false,
                         meta,
@@ -415,6 +453,7 @@ class SafetyGuard {
             if (similarity < this.thresholds.assertionSimilarityFloor) {
                 return {
                     level: "BLOCKED",
+                    code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_SIMILARITY_FLOOR,
                     reason: `Text divergence too high in assertion: "${oldText}" → "${newText}" ` +
                         `(similarity=${(similarity * 100).toFixed(1)}% < ${(this.thresholds.assertionSimilarityFloor * 100).toFixed(0)}%) — ` +
                         `possible content regression`,
@@ -449,16 +488,29 @@ class SafetyGuard {
     // ─────────────────────────────────────────────────────────────
     // FUNCTIONAL ROLE CLASSIFICATION
     //
-    // Returns the first role whose keyword set contains the text
-    // (exact match or substring). Returns UNKNOWN when no role matches.
+    // Returns the first role whose keyword matches the text as a whole
+    // word (delimited by \b boundaries).  Returns UNKNOWN when no role
+    // matches.
+    //
+    // Why \b instead of `.includes(kw)`:
+    //   - "unauthorized".includes("authorize")  → true   ← bug
+    //   - "offline".includes("on")              → true   ← bug
+    //   - "disconnected".includes("connected")  → true   ← bug
+    //   - "inactive".includes("active")         → true   ← bug
+    // The substring approach mis-classified negations into the
+    // positive role of their root word, silently bypassing
+    // FAIL_HARD_STATUS_INVERSION.  Word-boundary regex eliminates
+    // these collisions while keeping multi-word keywords ("sign in")
+    // and punctuation-flanked matches ("Submit!") working.
     // ─────────────────────────────────────────────────────────────
     classifyFunctionalRole(text) {
         const normalized = text.toLowerCase().trim();
-        for (const [role, keywords] of ROLE_KEYWORDS) {
-            for (const kw of keywords) {
-                if (normalized === kw || normalized.includes(kw)) {
+        if (normalized.length === 0)
+            return "UNKNOWN";
+        for (const { role, regexes } of ROLE_KEYWORD_REGEXES) {
+            for (const re of regexes) {
+                if (re.test(normalized))
                     return role;
-                }
             }
         }
         return "UNKNOWN";

package/dist/services/SourceUpdater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/SourceUpdater.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAMtD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AA0YD,qBAAa,aAAa;IAMxB,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,UAAU,CAAC,EAAE,eAAe,EAAE,EAC9B,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EACpD,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EACxC,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,EACvC,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,EACrD,UAAU,CAAC,EAAE,OAAO,GACnB,YAAY;IAoDf,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,WAAW;IAwS1B,OAAO,CAAC,MAAM,CAAC,2BAA2B;IA8E1C,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA8EvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAoErC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAsBjC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6DpC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuCpC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6CvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqCrC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqGrC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA0BjC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAatC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAgBlD,MAAM,CAAC,cAAc,CACnB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,YAAY;IA0Cf,0FAA0F;IAC1F,MAAM,CAAC,eAAe,IAAI,IAAI;CAG/B"}
+{"version":3,"file":"SourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/SourceUpdater.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA4BtD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAqZD,qBAAa,aAAa;IAMxB,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,UAAU,CAAC,EAAE,eAAe,EAAE,EAC9B,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EACpD,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EACxC,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,EACvC,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,EACrD,UAAU,CAAC,EAAE,OAAO,GACnB,YAAY;IAoDf,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,WAAW;IAiT1B,OAAO,CAAC,MAAM,CAAC,2BAA2B;IA8E1C,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA8EvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAoErC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAsBjC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6DpC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuCpC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6CvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqCrC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqGrC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA0BjC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAatC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAgBlD,MAAM,CAAC,cAAc,CACnB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,YAAY;IA0Cf,0FAA0F;IAC1F,MAAM,CAAC,eAAe,IAAI,IAAI;CAG/B"}

package/dist/services/SourceUpdater.js

@@ -38,6 +38,23 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const ASTSourceUpdater_1 = require("./ASTSourceUpdater");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
+const SelaError_1 = require("../errors/SelaError");
+// Centralised write gate — every disk-mutating `fs.writeFileSync` call in
+// this module routes through `persistFile` so the SELA_DRY_RUN bypass is
+// enforced in one place, and the Clean-Room WorkspaceSnapshotService
+// records contentBefore/contentAfter for isolated in-memory diffing.
+function persistFile(filePath, content) {
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        DryRunGuard_1.DryRunGuard.logSkippedWrite("writeFileSync", filePath);
+        return false;
+    }
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(filePath);
+    fs.writeFileSync(filePath, content, "utf8");
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(filePath);
+    return true;
+}
 // ─────────────────────────────────────────────────────────────────
 // QUOTE MANAGEMENT
 // ─────────────────────────────────────────────────────────────────
@@ -301,6 +318,13 @@ function updateTemplateLiteralPreservingVars(line, oldSelector, newSelector, dom
 // ─────────────────────────────────────────────────────────────────
 function runGitOperations(absoluteFilePath, createBranch, relativeFilePath) {
     const filename = path.basename(relativeFilePath);
+    // Dry-run gate — suppress branch creation, `git add`, and auto-commit.
+    // Mirrors the persistFile() skip so a dry run is fully observable in CI
+    // without ever producing a commit.
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        console.log(`[SourceUpdater] 🌵 Dry Run — skip git operations for ${filename}`);
+        return;
+    }
     try {
         // Bail out if HEAD is detached (CI SHA checkout, rebase mid-flight, etc.)
         try {
@@ -367,7 +391,7 @@ class SourceUpdater {
             const indent = lines[lineIdx].match(/^(\s*)/)?.[1] ?? "";
             const comment = `${indent}// TODO [Sela]: replace "${oldSelector}" with "${newSelector}"`;
             lines.splice(lineIdx, 0, comment);
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] 💬 Comment-only: inserted TODO at line ${caller.line} in ${path.basename(filePath)}`);
             return {
                 success: false,
@@ -441,6 +465,13 @@ class SourceUpdater {
             console.log(`[SourceUpdater] ⚠️ AST engine exhausted (${astResult.reason}), falling back to Regex`);
         }
         catch (astError) {
+            // Developer pinned the failing statement with `// sela-fail-fast` —
+            // propagate the directive instead of swallowing into the Regex
+            // fallback chain (which would defeat the whole point of the gate).
+            if ((0, SelaError_1.isSelaErrorFrom)(astError, "ASTUpdater") &&
+                astError.code === SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE) {
+                throw astError;
+            }
             console.warn(`[SourceUpdater] ⚠️ AST engine error: ${astError.message}. Falling back to Regex`);
         }
         // ── 2. Regex Fallback ──────────────────────────────────────────
@@ -452,7 +483,7 @@ class SourceUpdater {
             if (contentChange) {
                 const assertResult = SourceUpdater.strategyAssertionHealing(lines, 1, contentChange, true);
                 if (assertResult.success) {
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     console.log(`[SourceUpdater] ✅ Regex Strategy G (Assertion Healing) SUCCESS`);
                     return assertResult;
                 }
@@ -479,7 +510,7 @@ class SourceUpdater {
             const layeredResult = SourceUpdater.strategyLayeredHealing(lines, callerLine, oldSelector, aiSegments, fullSelectorContext);
             if (layeredResult.success) {
                 tryAssertionHealing();
-                fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                persistFile(filePath, lines.join("\n"));
                 console.log(`[SourceUpdater] ✅ Strategy 0 (Layered Healing) SUCCESS — line ${layeredResult.lineUpdated + 1}`);
                 return layeredResult;
             }
@@ -488,7 +519,7 @@ class SourceUpdater {
         const chainCollapseResult = SourceUpdater.strategyChainCollapse_Regex(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainCollapseResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy F (Chain Collapse) SUCCESS`);
             return chainCollapseResult;
         }
@@ -496,7 +527,7 @@ class SourceUpdater {
         const chainResult = SourceUpdater.strategyChainCollapse(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 1 (Chain Collapse) SUCCESS`);
             return chainResult;
         }
@@ -504,7 +535,7 @@ class SourceUpdater {
         const directResult = SourceUpdater.strategyDirectLiteral(lines, callerLine, oldSelector, effectiveNewSelector);
         if (directResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 2 (Direct Literal) SUCCESS`);
             return directResult;
         }
@@ -512,7 +543,7 @@ class SourceUpdater {
         const varResult = SourceUpdater.strategyUpstreamVariable(lines, callerLine, oldSelector, effectiveNewSelector);
         if (varResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 3 (Upstream Variable) SUCCESS`);
             return varResult;
         }
@@ -520,7 +551,7 @@ class SourceUpdater {
         const chainDedupResult = SourceUpdater.strategyChainedLocator(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainDedupResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 4 (Chained Dedup) SUCCESS`);
             return chainDedupResult;
         }
@@ -528,7 +559,7 @@ class SourceUpdater {
         const fnResult = SourceUpdater.strategyFunctionReturn(lines, callerLine, oldSelector, effectiveNewSelector, domContext, dnaAttrHint);
         if (fnResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 5 (Function Return) SUCCESS`);
             return fnResult;
         }
@@ -536,7 +567,7 @@ class SourceUpdater {
         const scanResult = SourceUpdater.strategyGlobalScan(lines, oldSelector, effectiveNewSelector);
         if (scanResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 6 (Global Scan) SUCCESS`);
             return scanResult;
         }
@@ -544,7 +575,7 @@ class SourceUpdater {
         if (contentChange) {
             const assertResult = SourceUpdater.strategyAssertionHealing(lines, callerLine, contentChange);
             if (assertResult.success) {
-                fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                persistFile(filePath, lines.join("\n"));
                 console.log(`[SourceUpdater] ✅ Strategy G (Assertion Healing) SUCCESS`);
                 return assertResult;
             }
@@ -1008,7 +1039,7 @@ class SourceUpdater {
                 if (pattern.test(lines[i])) {
                     const safeNew = sanitizeForInjection(newArgument, q);
                     lines[i] = lines[i].replace(pattern, `$1${safeNew}$2`);
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     return { success: true, reason: "argument updated", lineUpdated: i };
                 }
             }
@@ -1016,7 +1047,7 @@ class SourceUpdater {
                 if (pattern.test(lines[i])) {
                     const safeNew = sanitizeForInjection(newArgument, q);
                     lines[i] = lines[i].replace(pattern, `$1${safeNew}$2`);
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     return { success: true, reason: "argument updated", lineUpdated: i };
                 }
             }

package/dist/services/WorkspaceSnapshotService.d.ts

@@ -0,0 +1,71 @@
+export interface FileSnapshot {
+    /** Absolute, normalised path of the tracked file. */
+    absolutePath: string;
+    /** Project-relative path (posix slashes) — for diff headers + PR commits. */
+    relativePath: string;
+    /**
+     * Disk content captured BEFORE Sela's first write to this file.
+     * May contain the developer's uncommitted edits — that's the point.
+     */
+    contentBefore: string;
+    /** Disk content captured AFTER Sela's latest write. `null` until first postWrite(). */
+    contentAfter: string | null;
+    /** Content of the file at `HEAD` (last committed) — `null` when untracked / no git. */
+    headContent: string | null;
+    /** True when `contentBefore !== headContent`, i.e. developer had dirty edits. */
+    hadUncommittedChanges: boolean;
+    /** True when the file did not exist on disk before Sela touched it. */
+    createdBySela: boolean;
+}
+export declare class WorkspaceSnapshotService {
+    private snapshots;
+    private cwd;
+    constructor(cwd?: string);
+    /** Override the cwd used for relative-path + HEAD lookups (tests). */
+    setCwd(cwd: string): void;
+    /**
+     * Record the pre-mutation state of `filePath` if not already tracked.
+     * Idempotent — only the FIRST call per file matters.
+     */
+    preWrite(filePath: string): void;
+    /**
+     * Refresh the post-mutation state. Safe to call multiple times — each
+     * call overwrites `contentAfter` with the latest disk state.
+     */
+    postWrite(filePath: string): void;
+    /** Lookup by absolute or relative path. Returns `null` when untracked. */
+    getSnapshot(filePath: string): FileSnapshot | null;
+    /** Every tracked snapshot. Insertion order. */
+    getAllSnapshots(): FileSnapshot[];
+    /**
+     * Did Sela actually mutate this file? True when contentAfter exists and
+     * differs from contentBefore.
+     */
+    isMutated(filePath: string): boolean;
+    /** All snapshots with a real mutation recorded. */
+    getMutatedSnapshots(): FileSnapshot[];
+    /**
+     * Rewind every tracked file on disk to `contentBefore` — restoring the
+     * developer's pre-Sela workspace state byte-for-byte.
+     */
+    restoreOriginal(): void;
+    /**
+     * Rewind a SINGLE tracked file on disk to `contentBefore`. Used by the
+     * Local DX interactive review flow when the developer rejects a fix.
+     * Returns true when the rewind happened, false when the file is untracked.
+     */
+    restoreOriginalByPath(filePath: string): boolean;
+    private rewindSnapshot;
+    /**
+     * Forward every tracked file on disk to `contentAfter` (no-op for files
+     * that were never written). Used by PRAutomationService to reapply
+     * Sela's mutations after a `git stash pop` round-trip.
+     */
+    restoreMutated(): void;
+    clear(): void;
+    private normalise;
+    private toRelative;
+    private readHeadContent;
+}
+export declare const sharedWorkspaceSnapshot: WorkspaceSnapshotService;
+//# sourceMappingURL=WorkspaceSnapshotService.d.ts.map

package/dist/services/WorkspaceSnapshotService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceSnapshotService.d.ts","sourceRoot":"","sources":["../../src/services/WorkspaceSnapshotService.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uFAAuF;IACvF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,GAAG,CAAS;gBAER,GAAG,GAAE,MAAsB;IAIvC,sEAAsE;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAqBhC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IASjC,0EAA0E;IAC1E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIlD,+CAA+C;IAC/C,eAAe,IAAI,YAAY,EAAE;IAIjC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMpC,mDAAmD;IACnD,mBAAmB,IAAI,YAAY,EAAE;IAMrC;;;OAGG;IACH,eAAe,IAAI,IAAI;IAMvB;;;;OAIG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOhD,OAAO,CAAC,cAAc;IAUtB;;;;OAIG;IACH,cAAc,IAAI,IAAI;IAOtB,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;CAcxB;AAED,eAAO,MAAM,uBAAuB,0BAAiC,CAAC"}

package/dist/services/WorkspaceSnapshotService.js

@@ -0,0 +1,202 @@
+"use strict";
+// src/services/WorkspaceSnapshotService.ts
+//
+// Clean-Room Architecture — file 1 of 2.
+//
+// Tracks the EXACT content of every file Sela mutates during a session, so:
+//   • The HTML report diff can be generated from an isolated in-memory diff
+//     (developer's dirty pre-existing edits NEVER bleed in).
+//   • PRAutomationService can restore the developer's pre-Sela workspace
+//     byte-for-byte after a PR is opened on an isolated branch.
+//
+// Lifecycle:
+//   preWrite(path)   — first call per file records `contentBefore` (disk
+//                      snapshot right before Sela touches it) + HEAD blob.
+//   postWrite(path)  — refreshes `contentAfter` (latest disk state).
+//   restoreOriginal()— writes contentBefore back to every tracked file.
+//   restoreMutated() — writes contentAfter back to every tracked file.
+//   clear()          — empties the ledger.
+//
+// Singleton `sharedWorkspaceSnapshot` is the canonical instance the
+// SourceUpdater / ASTSourceUpdater write hooks talk to.
+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.sharedWorkspaceSnapshot = exports.WorkspaceSnapshotService = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+class WorkspaceSnapshotService {
+    snapshots = new Map();
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    /** Override the cwd used for relative-path + HEAD lookups (tests). */
+    setCwd(cwd) {
+        this.cwd = cwd;
+    }
+    /**
+     * Record the pre-mutation state of `filePath` if not already tracked.
+     * Idempotent — only the FIRST call per file matters.
+     */
+    preWrite(filePath) {
+        const abs = this.normalise(filePath);
+        if (this.snapshots.has(abs))
+            return;
+        const exists = fs.existsSync(abs);
+        const contentBefore = exists ? fs.readFileSync(abs, "utf8") : "";
+        const headContent = this.readHeadContent(abs);
+        const hadUncommittedChanges = headContent !== null && headContent !== contentBefore;
+        this.snapshots.set(abs, {
+            absolutePath: abs,
+            relativePath: this.toRelative(abs),
+            contentBefore,
+            contentAfter: null,
+            headContent,
+            hadUncommittedChanges,
+            createdBySela: !exists,
+        });
+    }
+    /**
+     * Refresh the post-mutation state. Safe to call multiple times — each
+     * call overwrites `contentAfter` with the latest disk state.
+     */
+    postWrite(filePath) {
+        const abs = this.normalise(filePath);
+        const snap = this.snapshots.get(abs);
+        if (!snap)
+            return;
+        snap.contentAfter = fs.existsSync(abs)
+            ? fs.readFileSync(abs, "utf8")
+            : "";
+    }
+    /** Lookup by absolute or relative path. Returns `null` when untracked. */
+    getSnapshot(filePath) {
+        return this.snapshots.get(this.normalise(filePath)) ?? null;
+    }
+    /** Every tracked snapshot. Insertion order. */
+    getAllSnapshots() {
+        return Array.from(this.snapshots.values());
+    }
+    /**
+     * Did Sela actually mutate this file? True when contentAfter exists and
+     * differs from contentBefore.
+     */
+    isMutated(filePath) {
+        const snap = this.getSnapshot(filePath);
+        if (!snap || snap.contentAfter === null)
+            return false;
+        return snap.contentAfter !== snap.contentBefore;
+    }
+    /** All snapshots with a real mutation recorded. */
+    getMutatedSnapshots() {
+        return this.getAllSnapshots().filter((s) => s.contentAfter !== null && s.contentAfter !== s.contentBefore);
+    }
+    /**
+     * Rewind every tracked file on disk to `contentBefore` — restoring the
+     * developer's pre-Sela workspace state byte-for-byte.
+     */
+    restoreOriginal() {
+        for (const snap of this.snapshots.values()) {
+            this.rewindSnapshot(snap);
+        }
+    }
+    /**
+     * Rewind a SINGLE tracked file on disk to `contentBefore`. Used by the
+     * Local DX interactive review flow when the developer rejects a fix.
+     * Returns true when the rewind happened, false when the file is untracked.
+     */
+    restoreOriginalByPath(filePath) {
+        const snap = this.getSnapshot(filePath);
+        if (!snap)
+            return false;
+        this.rewindSnapshot(snap);
+        return true;
+    }
+    rewindSnapshot(snap) {
+        if (snap.createdBySela) {
+            if (fs.existsSync(snap.absolutePath)) {
+                fs.unlinkSync(snap.absolutePath);
+            }
+            return;
+        }
+        fs.writeFileSync(snap.absolutePath, snap.contentBefore, "utf8");
+    }
+    /**
+     * Forward every tracked file on disk to `contentAfter` (no-op for files
+     * that were never written). Used by PRAutomationService to reapply
+     * Sela's mutations after a `git stash pop` round-trip.
+     */
+    restoreMutated() {
+        for (const snap of this.snapshots.values()) {
+            if (snap.contentAfter === null)
+                continue;
+            fs.writeFileSync(snap.absolutePath, snap.contentAfter, "utf8");
+        }
+    }
+    clear() {
+        this.snapshots.clear();
+    }
+    // ────────────────────────────────────────────────────────────────
+    // INTERNAL
+    // ────────────────────────────────────────────────────────────────
+    normalise(raw) {
+        if (!raw)
+            return raw;
+        const abs = path.isAbsolute(raw) ? raw : path.resolve(this.cwd, raw);
+        return path.normalize(abs);
+    }
+    toRelative(abs) {
+        const rel = path.relative(this.cwd, abs);
+        return rel.split(path.sep).join("/");
+    }
+    readHeadContent(abs) {
+        try {
+            const rel = this.toRelative(abs);
+            const out = (0, child_process_1.execSync)(`git show HEAD:"${rel}"`, {
+                cwd: this.cwd,
+                encoding: "utf8",
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            return out.toString();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.WorkspaceSnapshotService = WorkspaceSnapshotService;
+exports.sharedWorkspaceSnapshot = new WorkspaceSnapshotService();