sela-core 1.0.6 → 1.0.7

package/dist/engine/SelaEngine.js

@@ -36,15 +36,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SelaEngine = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 const LLMService_1 = require("../services/LLMService");
+const WorkspaceSnapshotService_1 = require("../services/WorkspaceSnapshotService");
+const IsolatedDiff_1 = require("../utils/IsolatedDiff");
 const SnapshotService_1 = require("../services/SnapshotService");
 const DOMUtils_1 = require("../utils/DOMUtils");
 const SourceUpdater_1 = require("../services/SourceUpdater");
+const ASTSourceUpdater_1 = require("../services/ASTSourceUpdater");
 const SafetyGuard_1 = require("../services/SafetyGuard");
+const HealingCacheService_1 = require("../services/HealingCacheService");
 const ConfigLoader_1 = require("../config/ConfigLoader");
+const DryRunGuard_1 = require("../config/DryRunGuard");
 const HealReportService_1 = require("../services/HealReportService");
 const PRAutomationService_1 = require("../services/PRAutomationService");
+const PendingPromptLedger_1 = require("../services/PendingPromptLedger");
+const SelaError_1 = require("../errors/SelaError");
 /**
  * Graceful percentage formatter for engine-side log lines. Mirrors the helper
  * in PRAutomationService / HealReportService so a missing AI/auditor
@@ -53,10 +59,25 @@ const PRAutomationService_1 = require("../services/PRAutomationService");
 function fmtPctEngine(v) {
     return typeof v === "number" && Number.isFinite(v) ? `${v}%` : "n/a";
 }
+/**
+ * Truthy when the current process is a CI runner. We accept the standard
+ * `CI=1`/`CI=true` convention used by GitHub Actions, GitLab, CircleCI,
+ * Buildkite, etc. Anything else (empty string, undefined, `0`, `false`)
+ * is treated as Local DX mode.
+ */
+function isCiEnvironment() {
+    const raw = process.env.CI;
+    if (raw === undefined || raw === null)
+        return false;
+    const v = String(raw).trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
 class SelaEngine {
     llmService;
     snapshotService;
     safetyGuard;
+    astDirectiveScanner;
+    healingCache;
     config;
     dnaBuffer = new Map();
     healMetaBuffer = new Map();
@@ -66,6 +87,14 @@ class SelaEngine {
         this.llmService = new LLMService_1.LLMService();
         this.snapshotService = new SnapshotService_1.SnapshotService();
         this.safetyGuard = new SafetyGuard_1.SafetyGuard(this.config.thresholds);
+        // Dedicated lightweight ts-morph project used only for the leading-comment
+        // pre-scan. Keeping it separate from the SourceUpdater's project avoids
+        // polluting that cache with files we may never actually mutate.
+        this.astDirectiveScanner = new ASTSourceUpdater_1.ASTSourceUpdater();
+        // Local healing cache — short-circuits the LLM call when an identical
+        // (filePath, oldSelector) pair was healed safely in a prior session.
+        // Disabled when SELA_NO_CACHE=1; reads/writes skipped during dry runs.
+        this.healingCache = HealingCacheService_1.sharedHealingCache;
     }
     // ─────────────────────────────────────────────────────────────
     // healArgument — repairs a wrong action argument (e.g. selectOption)
@@ -76,10 +105,10 @@ class SelaEngine {
             const { dom } = await DOMUtils_1.DOMUtils.getNeighborhoodDom(page, selector);
             const neighborhoodDom = dom;
             const targetIntent = action === "selectOption"
-                ? `ARGUMENT_HEALING: The selectOption argument "${oldArgument}" does not exist.
-Look at the <select> element in the DOM and find all <option> elements inside it.
-Return in 'new_selector' ONLY the TEXT CONTENT of the closest matching <option>.
-For example: if the options are "Male" and "Female" and the old argument was "Man", return "Male".
+                ? `ARGUMENT_HEALING: The selectOption argument "${oldArgument}" does not exist.
+Look at the <select> element in the DOM and find all <option> elements inside it.
+Return in 'new_selector' ONLY the TEXT CONTENT of the closest matching <option>.
+For example: if the options are "Male" and "Female" and the old argument was "Man", return "Male".
 CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only, exactly as it appears in the option.`
                 : `Fix the broken argument "${oldArgument}" for action "${action}". Return the correct value.`;
             const aiFix = await this.llmService.getFix({
@@ -108,6 +137,37 @@ CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only
         // Resolve file path for report purposes (project-relative when possible).
         const reportFile = this._toReportFile(filePath);
         const testTitle = this.testTitleBuffer.get(stableId);
+        // ── Developer fail-fast directive pre-gate ──────────────────────
+        // Scan the failing statement's leading comments for `// sela-fail-fast`
+        // BEFORE the expensive LLM round-trip. When present, record a
+        // "Skipped by Developer" FailedEvent and propagate the canonical
+        // SelaError(AST_HEAL_DISABLED_BY_DIRECTIVE) so retries are skipped too.
+        try {
+            this.astDirectiveScanner.enforceFailFastDirective({ filePath, line });
+        }
+        catch (directiveErr) {
+            if ((0, SelaError_1.isSelaErrorFrom)(directiveErr, "ASTUpdater") &&
+                directiveErr.code === SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE) {
+                console.warn(`[Sela] 🛑 Skipped by Developer — ${directiveErr.reason}`);
+                const skipEvent = {
+                    kind: "FAILED",
+                    stableId,
+                    sourceFile: reportFile,
+                    sourceLine: line,
+                    testTitle,
+                    timestamp: new Date().toISOString(),
+                    framePath: [],
+                    inIframe: false,
+                    inShadowDom: false,
+                    oldSelector: elementSelectorOnly,
+                    reason: "Skipped by Developer (sela-fail-fast directive)",
+                    dnaBefore: null,
+                };
+                HealReportService_1.sharedHealReport.record(skipEvent);
+                throw directiveErr;
+            }
+            throw directiveErr;
+        }
         // Snapshot for report event context (loaded once below, used at all exit paths).
         let lastKnownStateForReport = null;
         let aiFixForReport = null;
@@ -134,19 +194,19 @@ CRITICAL: Do NOT return a CSS selector like "#my-select". Return plain text only
             const intentDescription = lastKnownState
                 ? `The element that was a ${lastKnownState.tagName} with text "${lastKnownState.text}"`
                 : `Element identified by ${stableId}`;
-            const contentChangeInstructions = `
-
-[CONTENT CHANGE DETECTION]:
-If the element's VISIBLE TEXT has changed compared to its previous value${oldText ? ` ("${oldText}")` : ""}, you MUST include a "contentChange" field.
-NOTE: This change will NOT be applied automatically to the source code to prevent masking potential bugs.
-It will only be presented as a suggested fix in the terminal.
-{
-  "contentChange": {
-    "oldText": "<the previous visible text>",
-    "newText": "<the new visible text as it appears in the current DOM>"
-  }
-}
-This is required so that any expect(...).toHaveText("${oldText ?? "..."}") assertions in the test file can be automatically updated to match the new text.
+            const contentChangeInstructions = `
+
+[CONTENT CHANGE DETECTION]:
+If the element's VISIBLE TEXT has changed compared to its previous value${oldText ? ` ("${oldText}")` : ""}, you MUST include a "contentChange" field.
+NOTE: This change will NOT be applied automatically to the source code to prevent masking potential bugs.
+It will only be presented as a suggested fix in the terminal.
+{
+  "contentChange": {
+    "oldText": "<the previous visible text>",
+    "newText": "<the new visible text as it appears in the current DOM>"
+  }
+}
+This is required so that any expect(...).toHaveText("${oldText ?? "..."}") assertions in the test file can be automatically updated to match the new text.
 If the text has NOT changed, omit the "contentChange" field entirely.`;
             // ── Semantic anchor context hint for the LLM ─────────────────────
             // When DNA v2 anchor data exists, tell the AI which label and row
@@ -171,16 +231,56 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     "\n" +
                     "Prioritize selectors that preserve these relationships (e.g. filter by row key, then target by label).");
             })();
-            console.log(`[Sela] 🔍 Step 3: Requesting AI fix from LLM...`);
-            const aiFix = await this.llmService.getFix({
-                targetIntent: intentDescription,
-                failedSelector: fullSelector,
-                previousState: lastKnownState || {},
-                currentDom: neighborhoodDom +
-                    contextHint +
-                    anchorContextHint +
-                    contentChangeInstructions,
-            });
+            // ── Cache pre-check ────────────────────────────────────────────
+            // When a prior session healed this exact (filePath, oldSelector)
+            // pair AND SafetyGuard cleared it, replay the cached fix instead
+            // of paying the LLM round-trip. Disabled when SELA_NO_CACHE=1.
+            // The synthetic aiFix is fed through SafetyGuard exactly like a
+            // fresh LLM response — cache is a latency optimisation, never a
+            // safety bypass.
+            let aiFix = null;
+            let cacheHit = false;
+            // Fingerprint inputs the cache key depends on. Recomputed every
+            // heal so a DNA rewrite — which changes `dnaContentHash` —
+            // automatically invalidates every prior entry without an explicit
+            // purge.
+            const dnaContentHash = (0, HealingCacheService_1.hashDnaContent)(lastKnownState ?? null);
+            const cacheKeyInput = {
+                filePath,
+                line,
+                dnaContentHash,
+                brokenSelector: fullSelector,
+                mode: healMode,
+            };
+            if (!this.config.noCache) {
+                const cached = this.healingCache.get(cacheKeyInput);
+                if (cached) {
+                    console.log(`[Sela] 🧊 Cache hit (0ms LLM) — replaying healed selector "${cached.healedSelector}"`);
+                    aiFix = {
+                        status: "FIXED",
+                        new_selector: cached.healedSelector,
+                        chainSegments: cached.chainSegments,
+                        segments: cached.segments ??
+                            [{ type: "element", selector: cached.healedSelector }],
+                        confidence: cached.confidence,
+                        contentChange: cached.contentChange,
+                        explanation: cached.explanation ?? "Replayed from local healing cache",
+                    };
+                    cacheHit = true;
+                }
+            }
+            if (!cacheHit) {
+                console.log(`[Sela] 🔍 Step 3: Requesting AI fix from LLM...`);
+                aiFix = await this.llmService.getFix({
+                    targetIntent: intentDescription,
+                    failedSelector: fullSelector,
+                    previousState: lastKnownState || {},
+                    currentDom: neighborhoodDom +
+                        contextHint +
+                        anchorContextHint +
+                        contentChangeInstructions,
+                });
+            }
             aiFixForReport = aiFix;
             if (aiFix && aiFix.status === "FIXED") {
                 console.log(`[Sela] 🔍 Step 3: AI responded ✅`);
@@ -278,7 +378,24 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                         contentChange: aiFix.contentChange,
                     };
                     HealReportService_1.sharedHealReport.record(protectedEvent);
-                    throw new Error(`[SafetyGuard] ${safetyDecision.level}: ${safetyDecision.reason}`);
+                    throw new SelaError_1.SelaError({
+                        subsystem: "SafetyGuard",
+                        code: safetyDecision.code ?? SelaError_1.SAFETY_GUARD_CODES.GENERIC_REJECTION,
+                        reason: safetyDecision.reason,
+                        context: {
+                            filePath: reportFile,
+                            line,
+                            selector: elementSelectorOnly,
+                            healedSelector: newFullSelector,
+                            stableId,
+                            testTitle,
+                            branch,
+                            safetyLevel: safetyDecision.level,
+                            auditorVerdict: safetyDecision.meta?.auditorVerdict,
+                            auditorConfidence: safetyDecision.meta?.auditorConfidence,
+                            aiConfidence: aiFix.confidence,
+                        },
+                    });
                 }
                 // ── Heal-completion score summary ─────────────────────────────────
                 // Emits a single consolidated line showing AI confidence plus the
@@ -312,13 +429,14 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     (sameFileDef ? defSite?.line : undefined) ??
                     line;
                 const mutatedFilePath = !sameFileDef && defSite ? defSite.file : filePath;
-                // Capture the native unified diff straight from git. This runs AFTER
-                // SourceUpdater flushed the file to disk and BEFORE any `git add` —
-                // so `git diff HEAD` reports the exact pending change at the real
-                // mutated line. No in-process line-index math, no off-by-one when
-                // JumpToDef lands above the failure site, and cross-file healing
-                // falls out for free.
-                const gitUnifiedDiff = this._captureGitDiff(mutatedFilePath);
+                // Clean-Room isolated diff. We diff the in-memory snapshot recorded
+                // by WorkspaceSnapshotService (contentBefore — disk state right
+                // before Sela's first write to this file) against the post-write
+                // disk state. The result contains EXCLUSIVELY Sela's selector swap;
+                // any developer dirty edits sit identically in both buffers and
+                // therefore cancel out. Falls back to "" when the snapshot is
+                // missing (cross-file healing into an untracked path, etc.).
+                const gitUnifiedDiff = this._captureIsolatedDiff(mutatedFilePath);
                 const firstChange = this._extractFirstChangeFromDiff(gitUnifiedDiff);
                 // Backward-compat: keep oldCodeLine/newCodeLine populated from the
                 // first -/+ pair inside the diff. When git produced no diff (file
@@ -368,6 +486,7 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     framePath: successfulPath,
                     inIframe: successfulPath.length > 0,
                     inShadowDom: liveSnapshot?.isInShadowDom ?? false,
+                    dryRun: DryRunGuard_1.DryRunGuard.active() ? true : undefined,
                     oldSelector: elementSelectorOnly,
                     newSelector: canonicalSelector,
                     oldCodeLine,
@@ -396,6 +515,25 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                     contentChange: aiFix.contentChange,
                 };
                 HealReportService_1.sharedHealReport.record(healedEvent);
+                // ── Cache write — persist this safe heal for future sessions ──
+                // Best-effort: failures are logged inside the service and never
+                // block the heal return. Skipped automatically during dry runs
+                // and when SELA_NO_CACHE=1.
+                if (!this.config.noCache && !cacheHit) {
+                    this.healingCache
+                        .set({
+                        ...cacheKeyInput,
+                        healedSelector: canonicalSelector,
+                        chainSegments: aiFix.chainSegments,
+                        segments: aiFix.segments,
+                        confidence: aiFix.confidence,
+                        contentChange: aiFix.contentChange,
+                        explanation: aiFix.explanation,
+                        alternatives: this._buildAlternatives(aiFix.chainSegments, aiFix.segments),
+                        safe: true,
+                    })
+                        .catch((err) => console.warn(`[HealingCache] ⚠️  set() failed: ${err?.message ?? err}`));
+                }
                 return canonicalSelector;
             }
             // AI did not return FIXED — record as FAILED.
@@ -421,7 +559,11 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         catch (error) {
             console.error(`[Sela] ❌ Healing Failure:`, error.message);
             // Avoid double-recording when a SafetyGuard PROTECTED event was already pushed.
-            const isSafetyBlock = typeof error?.message === "string" && error.message.includes("[SafetyGuard]");
+            // Prefer the structured instanceof check; fall back to message-substring
+            // detection for any legacy throw sites that have not yet been migrated.
+            const isSafetyBlock = (0, SelaError_1.isSelaErrorFrom)(error, "SafetyGuard") ||
+                (typeof error?.message === "string" && error.message.includes("[Sela-SafetyGuard]")) ||
+                (typeof error?.message === "string" && error.message.includes("[SafetyGuard]"));
             const isNotFoundAlreadyRecorded = typeof error?.message === "string" && error.message === "AI could not provide a fix";
             if (!isSafetyBlock && !isNotFoundAlreadyRecorded) {
                 const failedEvent = {
@@ -471,36 +613,37 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         }
     }
     /**
-     * Capture the native `git diff --unified=1 HEAD -- <file>` for the file the
-     * AST mutation just wrote to. Returns an empty string when git is not
-     * available, the file is not tracked, or any other failure — callers must
-     * treat empty output as "no diff captured" and fall back to a direct disk
-     * read of the mutated line.
+     * Clean-Room isolated diff: render a unified diff between the file's
+     * pre-Sela disk snapshot (`contentBefore`) and the post-write disk state
+     * (`contentAfter`) captured by `WorkspaceSnapshotService`. Returns "" when
+     * the file was never tracked (no snapshot) or the AST mutation produced
+     * no net change.
      *
-     * Path safety: the absolute path is always wrapped in double quotes after
-     * escaping any embedded double quotes, which makes the call safe on Windows
-     * paths containing spaces or backslashes as well as POSIX paths.
+     * This is what makes the HTML report immune to developer dirty edits: any
+     * pre-existing uncommitted changes live in BOTH buffers identically and
+     * are therefore filtered out by the diff. The output contains only Sela's
+     * selector swap.
      */
-    _captureGitDiff(filePath) {
+    _captureIsolatedDiff(filePath) {
         try {
             const cleaned = this._toReportFile(filePath);
             const abs = path.isAbsolute(cleaned)
                 ? cleaned
                 : path.resolve(process.cwd(), cleaned);
-            if (!abs || !fs.existsSync(abs))
+            if (!abs)
+                return "";
+            const snap = WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.getSnapshot(abs);
+            if (!snap || snap.contentAfter === null)
                 return "";
-            const quoted = `"${abs.replace(/"/g, '\\"')}"`;
-            const out = (0, child_process_1.execSync)(`git diff --unified=1 HEAD -- ${quoted}`, {
-                cwd: process.cwd(),
-                encoding: "utf-8",
-                stdio: ["pipe", "pipe", "pipe"],
-                windowsHide: true,
+            if (snap.contentBefore === snap.contentAfter)
+                return "";
+            return (0, IsolatedDiff_1.generateUnifiedDiff)(snap.contentBefore, snap.contentAfter, {
+                filePath: snap.relativePath,
+                context: 1,
             });
-            return out.toString();
         }
         catch (err) {
-            // git missing / not a repo / file untracked vs HEAD → log & fall back.
-            console.debug?.(`[Sela] git diff capture skipped: ${err?.message ?? err}`);
+            console.debug?.(`[Sela] isolated diff capture skipped: ${err?.message ?? err}`);
             return "";
         }
     }
@@ -681,26 +824,54 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
                 console.warn(`[Sela] ⚠️  Failed to write insights report: ${err.message}`);
             }
         }
-        // ── PR Automation — batched git-flow at session end ─────────────
-        if (this.config.prAutomation.enabled) {
-            try {
-                const branchInfo = (0, PRAutomationService_1.detectBranch)(process.cwd());
-                const decision = (0, PRAutomationService_1.decideEffectiveStrategy)(this.config.prAutomation, branchInfo.branch, healedEvents);
-                if (decision.downgradeReason) {
-                    console.warn(`[Sela PR] ⚠️  Strategy downgraded: '${decision.configured}' → '${decision.effective}' ` +
-                        `(reason: ${decision.downgradeReason}, ` +
-                        `minAI: ${fmtPctEngine(decision.minAiConfidence)}, ` +
-                        `minAuditor: ${fmtPctEngine(decision.minAuditorConfidence)})`);
+        // ── Dual-Mode post-run lifecycle ─────────────────────────────────
+        //
+        // CI (process.env.CI truthy) → Clean-Room PR automation (existing flow).
+        // Local DX (CI falsy)        → Interactive CLI review of each mutated
+        //                              file; Apply keeps the on-disk fix, Reject
+        //                              rewinds via WorkspaceSnapshotService.
+        //
+        // The interactive branch deliberately bypasses PR automation because:
+        //   • AST fixes are ALREADY persisted to disk (the test passed on them).
+        //   • Local devs want to inspect + cherry-pick, not auto-commit.
+        if (isCiEnvironment()) {
+            if (this.config.prAutomation.enabled) {
+                try {
+                    const branchInfo = (0, PRAutomationService_1.detectBranch)(process.cwd());
+                    const decision = (0, PRAutomationService_1.decideEffectiveStrategy)(this.config.prAutomation, branchInfo.branch, healedEvents);
+                    if (decision.downgradeReason) {
+                        console.warn(`[Sela PR] ⚠️  Strategy downgraded: '${decision.configured}' → '${decision.effective}' ` +
+                            `(reason: ${decision.downgradeReason}, ` +
+                            `minAI: ${fmtPctEngine(decision.minAiConfidence)}, ` +
+                            `minAuditor: ${fmtPctEngine(decision.minAuditorConfidence)})`);
+                    }
+                    else {
+                        console.log(`[Sela PR] 🎯 Effective strategy: '${decision.effective}' on branch '${branchInfo.branch ?? "unknown"}'`);
+                    }
+                    const ctx = { cwd: process.cwd(), reportHtmlPath };
+                    await (0, PRAutomationService_1.execute)(this.config.prAutomation, decision, healedEvents, branchInfo, ctx);
+                    await (0, PRAutomationService_1.handleBugDetected)(this.config.prAutomation.onBugDetected, protectedEvents, branchInfo, ctx);
                 }
-                else {
-                    console.log(`[Sela PR] 🎯 Effective strategy: '${decision.effective}' on branch '${branchInfo.branch ?? "unknown"}'`);
+                catch (err) {
+                    console.warn(`[Sela PR] ⚠️  PR automation step failed: ${err.message}`);
                 }
-                const ctx = { cwd: process.cwd(), reportHtmlPath };
-                await (0, PRAutomationService_1.execute)(this.config.prAutomation, decision, healedEvents, branchInfo, ctx);
-                await (0, PRAutomationService_1.handleBugDetected)(this.config.prAutomation.onBugDetected, protectedEvents, branchInfo, ctx);
+            }
+        }
+        else if (healedEvents.length > 0) {
+            // Local DX: do NOT block this process on stdin — workers have no
+            // TTY and would deadlock until Playwright's per-test timeout fires.
+            // Serialise the mutated snapshots to a cross-process ledger; the
+            // SelaReporter drains it from `onEnd()` in the main process where
+            // an interactive `readline` is safe.
+            try {
+                (0, PendingPromptLedger_1.writePendingPromptsLedger)({
+                    cwd: process.cwd(),
+                    workspace: WorkspaceSnapshotService_1.sharedWorkspaceSnapshot,
+                    healedEvents,
+                });
             }
             catch (err) {
-                console.warn(`[Sela PR] ⚠️  PR automation step failed: ${err.message}`);
+                console.warn(`[Sela] ⚠️  Pending-prompts ledger write failed: ${err.message}`);
             }
         }
         // Clear the report buffer last so any downstream consumers (e.g. test
@@ -708,6 +879,12 @@ If the text has NOT changed, omit the "contentChange" field entirely.`;
         if (HealReportService_1.sharedHealReport.hasContent()) {
             HealReportService_1.sharedHealReport.clear();
         }
+        // Drop the Clean-Room workspace snapshot ledger so the next session
+        // starts with an empty `contentBefore` map. Without this, a long-lived
+        // Node process (`vitest --watch`, IDE test runner) would carry stale
+        // pre-Sela snapshots from one session into the next, causing the
+        // isolated-diff layer to compare against the wrong baseline.
+        WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.clear();
     }
     // ─────────────────────────────────────────────────────────────
     // fetchLiveText — frame-aware innerText fetch (zero-trust probe)

package/dist/errors/SelaError.d.ts

@@ -0,0 +1,133 @@
+export type SelaSubsystem = "SafetyGuard" | "IntentAuditor" | "ASTUpdater" | "Proxy" | "LLMService" | "Registry" | "ChainValidator" | "Engine" | "Report";
+export interface SelaErrorContext {
+    filePath?: string;
+    line?: number;
+    column?: number;
+    selector?: string;
+    healedSelector?: string;
+    stableId?: string;
+    testTitle?: string;
+    testFile?: string;
+    branch?: string;
+    /** SafetyGuard verdict level when the error originated in SafetyGuard. */
+    safetyLevel?: "BLOCKED" | "FAIL_HARD" | "REQUIRES_REVIEW" | "SAFE";
+    /** Auditor verdict surfaced in the context for SafetyGuard rejections. */
+    auditorVerdict?: "CONSISTENT" | "INCONSISTENT" | "SUSPICIOUS";
+    /** Raw + adjusted LLM confidence so downstream telemetry can plot drift. */
+    aiConfidence?: number;
+    auditorConfidence?: number;
+    /** Free-form extension slot. Prefer adding a named field above when possible. */
+    [key: string]: unknown;
+}
+export interface SelaErrorJSON {
+    name: string;
+    subsystem: SelaSubsystem;
+    code: string;
+    reason: string;
+    message: string;
+    context: SelaErrorContext;
+    stack?: string;
+    cause?: string;
+}
+export interface SelaErrorInit {
+    subsystem: SelaSubsystem;
+    /**
+     * Stable machine-readable error code. Must match `[A-Z][A-Z0-9_]+`.
+     * Recommended convention: short subsystem-prefix + verb/noun.
+     * See SELA_ERROR_CODES below for the canonical catalogue.
+     */
+    code: string;
+    /** Human-readable explanation. Becomes the tail of the formatted message. */
+    reason: string;
+    context?: SelaErrorContext;
+    /** Original error wrapped by this SelaError, if any. */
+    cause?: unknown;
+}
+export declare class SelaError extends Error {
+    readonly subsystem: SelaSubsystem;
+    readonly code: string;
+    readonly reason: string;
+    readonly context: SelaErrorContext;
+    constructor(init: SelaErrorInit);
+    static formatMessage(subsystem: SelaSubsystem, code: string, reason: string): string;
+    toJSON(): SelaErrorJSON;
+}
+export declare function isSelaError(err: unknown): err is SelaError;
+export declare function isSelaErrorFrom(err: unknown, subsystem: SelaSubsystem): err is SelaError;
+export declare const SAFETY_GUARD_CODES: {
+    readonly FAIL_HARD_VISIBILITY_GHOST: "SG_FAIL_HARD_VISIBILITY_GHOST";
+    readonly FAIL_HARD_VISIBILITY_OCCLUDED: "SG_FAIL_HARD_VISIBILITY_OCCLUDED";
+    readonly BLOCKED_LOW_CONFIDENCE: "SG_BLOCKED_LOW_CONFIDENCE";
+    readonly FAIL_HARD_SEMANTIC_INVERSION: "SG_FAIL_HARD_SEMANTIC_INVERSION";
+    readonly FAIL_HARD_STATUS_INVERSION: "SG_FAIL_HARD_STATUS_INVERSION";
+    readonly BLOCKED_ROLE_SWAP_ASSERTION: "SG_BLOCKED_ROLE_SWAP_ASSERTION";
+    readonly FAIL_HARD_AUDITOR_INCONSISTENT: "SG_FAIL_HARD_AUDITOR_INCONSISTENT";
+    readonly BLOCKED_AUDITOR_SUSPICIOUS: "SG_BLOCKED_AUDITOR_SUSPICIOUS";
+    readonly BLOCKED_SIMILARITY_FLOOR: "SG_BLOCKED_SIMILARITY_FLOOR";
+    /** Generic dispatcher when SafetyDecision arrives without an explicit code. */
+    readonly GENERIC_REJECTION: "SG_GENERIC_REJECTION";
+};
+export type SafetyGuardCode = (typeof SAFETY_GUARD_CODES)[keyof typeof SAFETY_GUARD_CODES];
+export declare const INTENT_AUDITOR_CODES: {
+    /** Caller asked for an audit but no Anthropic client was configured. */
+    readonly DISABLED: "IA_DISABLED";
+    readonly INVALID_JSON: "IA_INVALID_JSON";
+    readonly CALL_FAILED: "IA_CALL_FAILED";
+};
+export type IntentAuditorCode = (typeof INTENT_AUDITOR_CODES)[keyof typeof INTENT_AUDITOR_CODES];
+export declare const LLM_SERVICE_CODES: {
+    readonly NO_API_KEY: "LLM_NO_API_KEY";
+    readonly INVALID_JSON: "LLM_INVALID_JSON";
+    readonly MISSING_SEGMENTS: "LLM_MISSING_SEGMENTS";
+    readonly NOT_FOUND: "LLM_NOT_FOUND";
+    readonly API_CALL_FAILED: "LLM_API_CALL_FAILED";
+};
+export type LLMServiceCode = (typeof LLM_SERVICE_CODES)[keyof typeof LLM_SERVICE_CODES];
+export declare const AST_UPDATER_CODES: {
+    readonly UNSUPPORTED_NODE: "AST_UNSUPPORTED_NODE";
+    readonly TEMPLATE_LITERAL_SKIP: "AST_TEMPLATE_LITERAL_SKIP";
+    readonly CIRCULAR_RECEIVER: "AST_CIRCULAR_RECEIVER";
+    readonly DEFINITION_NOT_FOUND: "AST_DEFINITION_NOT_FOUND";
+    readonly MAX_DEPTH_EXCEEDED: "AST_MAX_DEPTH_EXCEEDED";
+    readonly SAVE_FAILED: "AST_SAVE_FAILED";
+    /**
+     * Developer pinned the failing statement with `// sela-fail-fast`.
+     * Heal pipeline is aborted before any LLM call; FailedEvent is
+     * recorded with category "Skipped by Developer".
+     */
+    readonly HEAL_DISABLED_BY_DIRECTIVE: "AST_HEAL_DISABLED_BY_DIRECTIVE";
+};
+export type ASTUpdaterCode = (typeof AST_UPDATER_CODES)[keyof typeof AST_UPDATER_CODES];
+export declare const PROXY_CODES: {
+    readonly FRAME_SCOPED: "PRX_FRAME_SCOPED";
+    readonly REBUILD_FAILED: "PRX_REBUILD_FAILED";
+    readonly NON_LOCATOR_TARGET: "PRX_NON_LOCATOR_TARGET";
+};
+export type ProxyCode = (typeof PROXY_CODES)[keyof typeof PROXY_CODES];
+export declare const REGISTRY_CODES: {
+    readonly CONTEXT_MISMATCH: "REG_CONTEXT_MISMATCH";
+    readonly FINGERPRINT_COLLISION: "REG_FINGERPRINT_COLLISION";
+};
+export type RegistryCode = (typeof REGISTRY_CODES)[keyof typeof REGISTRY_CODES];
+export declare const REPORT_CODES: {
+    /** Event passed to the validator was null, undefined, or not an object. */
+    readonly MALFORMED_EVENT: "REP_MALFORMED_EVENT";
+    /** Event.kind is not one of HEALED|FAILED|PROTECTED. */
+    readonly UNKNOWN_KIND: "REP_UNKNOWN_KIND";
+    /** Event is missing a field declared mandatory for its kind. */
+    readonly MISSING_FIELD: "REP_MISSING_FIELD";
+    /** Event contains a field of the wrong type. */
+    readonly INVALID_FIELD_TYPE: "REP_INVALID_FIELD_TYPE";
+    /** Disk write failed during flushToDisk(). */
+    readonly FLUSH_FAILED: "REP_FLUSH_FAILED";
+};
+export type ReportCode = (typeof REPORT_CODES)[keyof typeof REPORT_CODES];
+export declare const CHAIN_VALIDATOR_CODES: {
+    readonly TYPE_FLOW: "CV_TYPE_FLOW";
+    readonly SCHEMA: "CV_SCHEMA";
+    readonly RECEIVER: "CV_RECEIVER";
+    readonly PLACEMENT: "CV_PLACEMENT";
+    readonly SEMANTIC_DOWNGRADE: "CV_SEMANTIC_DOWNGRADE";
+};
+export type ChainValidatorCode = (typeof CHAIN_VALIDATOR_CODES)[keyof typeof CHAIN_VALIDATOR_CODES];
+//# sourceMappingURL=SelaError.d.ts.map

package/dist/errors/SelaError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelaError.d.ts","sourceRoot":"","sources":["../../src/errors/SelaError.ts"],"names":[],"mappings":"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"}