sela-core 0.1.0-alpha.1

package/dist/services/HealingAdvisory.d.ts

@@ -0,0 +1,30 @@
+export declare enum AdvisoryCode {
+    BLAST_RADIUS_BLOCKED = "BLAST_RADIUS_BLOCKED",
+    BLAST_RADIUS_WARNING = "BLAST_RADIUS_WARNING",
+    CROSS_FILE_MUTATION = "CROSS_FILE_MUTATION",
+    MANUAL_REVIEW_TEMPLATE_COMPLEX = "MANUAL_REVIEW_TEMPLATE_COMPLEX",
+    MANUAL_REVIEW_CONDITIONAL_RETURN = "MANUAL_REVIEW_CONDITIONAL_RETURN",
+    POST_MUTATION_TYPE_ERROR = "POST_MUTATION_TYPE_ERROR",
+    /**
+     * A definition-site string constant was healed to a valid PUBLIC selector
+     * string (e.g. `role=button[name="…"]`) because the constant is consumed by
+     * `.locator(VAR)` and cannot hold a semantic locator. The AI's preferred
+     * semantic method form (e.g. `getByRole(...)`) is suggested as a cleaner,
+     * optional refactor.
+     */
+    SEMANTIC_UPGRADE_SUGGESTED = "SEMANTIC_UPGRADE_SUGGESTED"
+}
+export interface Advisory {
+    code: AdvisoryCode;
+    message: string;
+    affectedFile: string;
+    affectedLine?: number;
+    suggestedAction: string;
+}
+export declare class AdvisoryBuffer {
+    private items;
+    push(advisory: Advisory): void;
+    flush(): void;
+    get length(): number;
+}
+//# sourceMappingURL=HealingAdvisory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HealingAdvisory.d.ts","sourceRoot":"","sources":["../../src/services/HealingAdvisory.ts"],"names":[],"mappings":"AAUA,oBAAY,YAAY;IACtB,oBAAoB,yBAAyB;IAC7C,oBAAoB,yBAAyB;IAC7C,mBAAmB,wBAAwB;IAC3C,8BAA8B,mCAAmC;IACjE,gCAAgC,qCAAqC;IACrE,wBAAwB,6BAA6B;IACrD;;;;;;OAMG;IACH,0BAA0B,+BAA+B;CAC1D;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAkB;IAE/B,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAI9B,KAAK,IAAI,IAAI;IAab,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF"}

package/dist/services/HealingAdvisory.js

@@ -0,0 +1,51 @@
+"use strict";
+// ═══════════════════════════════════════════════════════════════════
+// HealingAdvisory  (T-12)
+//
+// Typed advisory system for definition-site mutations.
+// Advisories are buffered during the AST phase and flushed AFTER
+// Playwright prints its test result - prevents interleaving.
+// ═══════════════════════════════════════════════════════════════════
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdvisoryBuffer = exports.AdvisoryCode = void 0;
+const logger_1 = require("../utils/logger");
+var AdvisoryCode;
+(function (AdvisoryCode) {
+    AdvisoryCode["BLAST_RADIUS_BLOCKED"] = "BLAST_RADIUS_BLOCKED";
+    AdvisoryCode["BLAST_RADIUS_WARNING"] = "BLAST_RADIUS_WARNING";
+    AdvisoryCode["CROSS_FILE_MUTATION"] = "CROSS_FILE_MUTATION";
+    AdvisoryCode["MANUAL_REVIEW_TEMPLATE_COMPLEX"] = "MANUAL_REVIEW_TEMPLATE_COMPLEX";
+    AdvisoryCode["MANUAL_REVIEW_CONDITIONAL_RETURN"] = "MANUAL_REVIEW_CONDITIONAL_RETURN";
+    AdvisoryCode["POST_MUTATION_TYPE_ERROR"] = "POST_MUTATION_TYPE_ERROR";
+    /**
+     * A definition-site string constant was healed to a valid PUBLIC selector
+     * string (e.g. `role=button[name="…"]`) because the constant is consumed by
+     * `.locator(VAR)` and cannot hold a semantic locator. The AI's preferred
+     * semantic method form (e.g. `getByRole(...)`) is suggested as a cleaner,
+     * optional refactor.
+     */
+    AdvisoryCode["SEMANTIC_UPGRADE_SUGGESTED"] = "SEMANTIC_UPGRADE_SUGGESTED";
+})(AdvisoryCode || (exports.AdvisoryCode = AdvisoryCode = {}));
+class AdvisoryBuffer {
+    items = [];
+    push(advisory) {
+        this.items.push(advisory);
+    }
+    flush() {
+        if (this.items.length === 0)
+            return;
+        logger_1.logger.info("\n[Sela Advisories] ══════════════════════════════════════");
+        for (const a of this.items) {
+            const loc = a.affectedLine != null ? `:${a.affectedLine + 1}` : "";
+            logger_1.logger.info(`  [${a.code}] ${a.message}`);
+            logger_1.logger.info(`    File:   ${a.affectedFile}${loc}`);
+            logger_1.logger.info(`    Action: ${a.suggestedAction}`);
+        }
+        logger_1.logger.info("[Sela Advisories] ══════════════════════════════════════\n");
+        this.items = [];
+    }
+    get length() {
+        return this.items.length;
+    }
+}
+exports.AdvisoryBuffer = AdvisoryBuffer;

package/dist/services/HealingCacheService.d.ts

@@ -0,0 +1,135 @@
+import type { SmartChainSegment, SelectorSegment } from "./LLMService";
+export type HealCacheMode = "action" | "assertion";
+export interface CacheKeyInput {
+    /** Absolute or project-relative spec path containing the failing locator. */
+    filePath: string;
+    /** 1-based line of the failing call site - paired with filePath as a fingerprint. */
+    line: number;
+    /**
+     * Stable content hash of the DNA snapshot used to drive the heal. When the
+     * DNA rewrites, this changes - every cached entry for the old DNA
+     * silently stops matching and ages out via TTL.
+     */
+    dnaContentHash: string;
+    /** The original broken selector. */
+    brokenSelector: string;
+    /** Heal mode the cached fix was produced under. */
+    mode: HealCacheMode;
+}
+export interface HealingCacheEntry {
+    /** Full SHA1 of the CacheKeyInput tuple. */
+    key: string;
+    filePath: string;
+    line: number;
+    dnaContentHash: string;
+    brokenSelector: string;
+    mode: HealCacheMode;
+    healedSelector: string;
+    chainSegments?: SmartChainSegment[];
+    segments?: SelectorSegment[];
+    confidence?: number;
+    contentChange?: {
+        oldText: string;
+        newText: string;
+    };
+    explanation?: string;
+    alternatives?: string[];
+    /**
+     * True when SafetyGuard cleared this fix in the originating session
+     * (SAFE or REQUIRES_REVIEW). Unsafe entries are never replayed.
+     */
+    safe: boolean;
+    createdAt: string;
+    /** ISO timestamp after which the entry is considered expired and ignored. */
+    ttlExpiresAt: string;
+    lastHitAt?: string;
+    hitCount: number;
+}
+interface CacheFile {
+    schemaVersion: 1;
+    entries: Record<string, HealingCacheEntry>;
+}
+export interface HealingCacheSetInput extends CacheKeyInput {
+    healedSelector: string;
+    chainSegments?: SmartChainSegment[];
+    segments?: SelectorSegment[];
+    confidence?: number;
+    contentChange?: {
+        oldText: string;
+        newText: string;
+    };
+    explanation?: string;
+    alternatives?: string[];
+    safe: boolean;
+    /** Optional override for entry-level TTL (ms). Defaults to env / 7d. */
+    ttlMs?: number;
+}
+export declare function computeCacheKey(input: CacheKeyInput): string;
+/**
+ * Convenience helper - fingerprint the JSON form of a DNA snapshot so
+ * the cache key changes whenever the DNA is rewritten.
+ */
+export declare function hashDnaContent(dna: unknown): string;
+export declare class HealingCacheService {
+    private readonly cacheDir;
+    private readonly filename;
+    private readonly lockDir;
+    private readonly tmpSuffix;
+    private readonly bakSuffix;
+    /** Cross-process mutex (Layer 2) — shared mkdir-lock primitive. */
+    private readonly lock;
+    private inFlight;
+    constructor(opts?: {
+        cacheDir?: string;
+        filename?: string;
+    });
+    /**
+     * Read-only lookup. Bumps `hitCount` / `lastHitAt` IN-MEMORY only on
+     * the returned entry reference - never persisted on the get() path.
+     * This eliminates the read-write race where parallel workers each
+     * call get() and serialise full entries-map snapshots back to disk,
+     * overwriting peer set() operations.
+     */
+    get(input: CacheKeyInput): HealingCacheEntry | null;
+    /**
+     * Persist a new cache entry. Serialises against in-process writers
+     * AND across processes via the mkdir lock. The in-process chain
+     * isolates each `await` so a rejected upstream Promise never
+     * deadlocks downstream callers.
+     */
+    set(input: HealingCacheSetInput): Promise<void>;
+    /** Synchronous variant - used by teardown / CLI paths. */
+    setSync(input: HealingCacheSetInput): void;
+    /** Wipe every entry. Used by tests and the (forthcoming) `sela cache clear` CLI. */
+    clear(): void;
+    /** Returns the parsed cache file (or an empty shell on failure). */
+    read(): CacheFile;
+    /** Absolute path of the on-disk cache file. */
+    filePath(): string;
+    /**
+     * Prunes expired entries. Cheap O(n) scan - intended for engine
+     * startup. Returns the number of entries removed.
+     */
+    pruneExpired(): number;
+    private isExpired;
+    private lockedWrite;
+    private buildEntry;
+    /**
+     * Reads + parses the cache file. Tolerates every realistic failure
+     * (missing, empty, malformed, wrong schema version) by returning a
+     * fresh empty shell - the contract is "cache misses are silent".
+     */
+    private safeRead;
+    /**
+     * Atomic write via the shared {@link atomicWriteFile} primitive: write to a
+     * pid-temp, copy current to `<file>.bak`, then rename. The rename is the
+     * single commit point - a crash before it leaves the prior file intact.
+     */
+    private atomicWrite;
+    private acquireLockWithBackoff;
+    private withFileLockSync;
+    private releaseLock;
+}
+export declare const sharedHealingCache: HealingCacheService;
+export {};
+//# sourceMappingURL=HealingCacheService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HealingCacheService.d.ts","sourceRoot":"","sources":["../../src/services/HealingCacheService.ts"],"names":[],"mappings":"AAiEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAMvE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEnD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,SAAS;IACjB,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAmBD,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAc5D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOnD;AAMD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAIhC,OAAO,CAAC,QAAQ,CAAoC;gBAExC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAiB3D;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,IAAI;IAgBnD;;;;;OAKG;IACG,GAAG,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCrD,0DAA0D;IAC1D,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI;IAU1C,oFAAoF;IACpF,KAAK,IAAI,IAAI;IAeb,oEAAoE;IACpE,IAAI,IAAI,SAAS;IAIjB,+CAA+C;IAC/C,QAAQ,IAAI,MAAM;IAIlB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAmBtB,OAAO,CAAC,SAAS;YAOH,WAAW;IAkBzB,OAAO,CAAC,UAAU;IA8BlB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAqChB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,WAAW;CAGpB;AAMD,eAAO,MAAM,kBAAkB,qBAA4B,CAAC"}

package/dist/services/HealingCacheService.js

@@ -0,0 +1,404 @@
+"use strict";
+// src/services/HealingCacheService.ts
+//
+// Local healing cache - short-circuits the LLM round-trip when an
+// identical heal-context has been resolved successfully in a prior
+// session.
+//
+// Cache key (matches DX MVP Phase 6 plan):
+//   SHA1(filePath + ":" + line + "::" + dnaContentHash + "::" + brokenSelector + "::" + mode)
+//   Including `dnaContentHash` means a DNA rewrite automatically
+//   invalidates every entry keyed against that fingerprint - old
+//   entries simply stop matching and age out via TTL.
+//
+// Cache value:
+//   `{ chainSegments, segments, confidence, contentChange, explanation,
+//      alternatives, safe, createdAt, ttlExpiresAt, hitCount, lastHitAt }`.
+//   TTL defaults to 7 days; overridable via `SELA_CACHE_TTL_DAYS`.
+//
+// Storage:
+//   `.sela-cache.json` in process.cwd() by default (configurable via the
+//   constructor for tests). Single-file map of SHA1 keys → entry.
+//   Schema-versioned (`schemaVersion: 1`).
+//
+// Concurrency model (three layers, identical to the plan):
+//
+//   1. In-process mutex
+//      `inFlight: Promise<void>` chain. Concurrent setters in the SAME
+//      Node process queue behind one another via the chained Promise.
+//      Any rejection on the chain is swallowed before the next call
+//      awaits it, so a single bad write CANNOT deadlock subsequent
+//      callers.
+//
+//   2. Cross-process file lock
+//      Playwright workers run as separate processes - atomic
+//      `mkdir <cacheDir>/.sela-cache.lock` is used as the mutex. Second
+//      process gets `EEXIST`, polls with exponential backoff
+//      (50ms → 800ms, max 6 retries ≈ 3.15 s ceiling). Lock is held
+//      only across the read-modify-write window, never during reads.
+//
+//   3. Atomic write via temp + rename
+//      Write to `.sela-cache.json.tmp`, copy the previous file to
+//      `.sela-cache.json.bak`, then `fs.renameSync(tmp, target)` -
+//      atomic on POSIX and on Windows (Node ≥14) when source and
+//      target share a volume (always true here).
+//
+// Read path:
+//   memory check → file check (no lock) → on miss the caller (SelaEngine)
+//   acquires the LLM via the normal path; cache writes happen post-success.
+//
+// `get()` is strictly read-only on disk: hit-count / lastHitAt are
+// bumped IN-MEMORY only - they never trigger a disk write. This avoids
+// the documented bug where concurrent worker `get()` calls would
+// overwrite valid `set()` operations from peer workers.
+//
+// Failure tolerance: any read failure (missing, malformed JSON, wrong
+// schema, EACCES, …) returns "no entries" instead of throwing. The
+// cache is a latency optimisation - never a hard dependency of the
+// heal pipeline.
+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.sharedHealingCache = exports.HealingCacheService = void 0;
+exports.computeCacheKey = computeCacheKey;
+exports.hashDnaContent = hashDnaContent;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const FileLock_1 = require("../utils/FileLock");
+const atomicWrite_1 = require("../utils/atomicWrite");
+const logger_1 = require("../utils/logger");
+// ═══════════════════════════════════════════════════════════════════
+// KEY HASH
+// ═══════════════════════════════════════════════════════════════════
+const KEY_SEPARATOR = "::";
+const DEFAULT_TTL_DAYS = 7;
+function defaultTtlMs() {
+    const raw = process.env.SELA_CACHE_TTL_DAYS;
+    if (!raw)
+        return DEFAULT_TTL_DAYS * 24 * 60 * 60 * 1000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        return DEFAULT_TTL_DAYS * 24 * 60 * 60 * 1000;
+    }
+    return n * 24 * 60 * 60 * 1000;
+}
+function computeCacheKey(input) {
+    // Normalise filePath separators so a cache entry written from a Windows
+    // worker is still found from a POSIX worker hitting the same repo.
+    const normPath = path.resolve(input.filePath).split(path.sep).join("/");
+    return (0, crypto_1.createHash)("sha1")
+        .update([
+        normPath + ":" + input.line,
+        input.dnaContentHash,
+        input.brokenSelector,
+        input.mode,
+    ].join(KEY_SEPARATOR))
+        .digest("hex");
+}
+/**
+ * Convenience helper - fingerprint the JSON form of a DNA snapshot so
+ * the cache key changes whenever the DNA is rewritten.
+ */
+function hashDnaContent(dna) {
+    try {
+        const json = typeof dna === "string" ? dna : JSON.stringify(dna ?? {});
+        return (0, crypto_1.createHash)("sha1").update(json).digest("hex");
+    }
+    catch {
+        return "no-dna";
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// HealingCacheService
+// ═══════════════════════════════════════════════════════════════════
+class HealingCacheService {
+    cacheDir;
+    filename;
+    lockDir;
+    tmpSuffix = ".tmp";
+    bakSuffix = ".bak";
+    /** Cross-process mutex (Layer 2) — shared mkdir-lock primitive. */
+    lock;
+    // In-process serialisation. Every new set() chains onto the prior
+    // tail Promise. The chain is fault-tolerant - see `set()` below.
+    inFlight = Promise.resolve();
+    constructor(opts) {
+        this.cacheDir = opts?.cacheDir ?? process.cwd();
+        this.filename = opts?.filename ?? ".sela-cache.json";
+        this.lockDir = path.join(this.cacheDir, ".sela-cache.lock");
+        // Preserve the historical schedules: async 50→800ms (≈3.15s ceiling),
+        // sync busy-wait 10→100ms. Logged warnings keep the cache's prefix.
+        this.lock = new FileLock_1.FileLock(this.lockDir, {
+            delaysMs: [50, 100, 200, 400, 800, 800],
+            syncDelaysMs: [10, 25, 50, 100],
+            logger: { warn: (m) => logger_1.logger.warn(`HealingCache: ${m}`) },
+        });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PUBLIC API
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Read-only lookup. Bumps `hitCount` / `lastHitAt` IN-MEMORY only on
+     * the returned entry reference - never persisted on the get() path.
+     * This eliminates the read-write race where parallel workers each
+     * call get() and serialise full entries-map snapshots back to disk,
+     * overwriting peer set() operations.
+     */
+    get(input) {
+        const key = computeCacheKey(input);
+        const file = this.safeRead();
+        const entry = file.entries[key];
+        if (!entry)
+            return null;
+        if (!entry.safe)
+            return null;
+        if (this.isExpired(entry))
+            return null;
+        // In-memory only - DO NOT write back. Hit-count drift across workers
+        // is acceptable; corrupting peer writes is not.
+        entry.hitCount = (entry.hitCount ?? 0) + 1;
+        entry.lastHitAt = new Date().toISOString();
+        return entry;
+    }
+    /**
+     * Persist a new cache entry. Serialises against in-process writers
+     * AND across processes via the mkdir lock. The in-process chain
+     * isolates each `await` so a rejected upstream Promise never
+     * deadlocks downstream callers.
+     */
+    async set(input) {
+        if (DryRunGuard_1.DryRunGuard.active()) {
+            // Don't pollute the cache during a SELA_DRY_RUN session.
+            return;
+        }
+        // Chain onto the previous tail, but swallow rejections via a
+        // `.catch(noop)` adapter. Without this, an earlier rejected set()
+        // would propagate through every subsequent `await prev` and either
+        // throw at the wrong caller or - worse - leak through the finally
+        // block without releasing the queue. The wrapper guarantees the
+        // queue is FIFO and rejection-safe.
+        const prev = this.inFlight.catch(() => {
+            /* swallow - upstream failure handled by its own caller */
+        });
+        let release;
+        const myTurn = new Promise((res) => {
+            release = res;
+        });
+        this.inFlight = myTurn;
+        try {
+            await prev;
+            await this.lockedWrite(input);
+        }
+        finally {
+            // Always release - even on throw - so the next queued caller
+            // unblocks. Errors still propagate up to *this* caller normally.
+            release();
+        }
+    }
+    /** Synchronous variant - used by teardown / CLI paths. */
+    setSync(input) {
+        if (DryRunGuard_1.DryRunGuard.active())
+            return;
+        this.withFileLockSync(() => {
+            const file = this.safeRead();
+            const key = computeCacheKey(input);
+            file.entries[key] = this.buildEntry(key, input, file.entries[key]);
+            this.atomicWrite(file);
+        });
+    }
+    /** Wipe every entry. Used by tests and the (forthcoming) `sela cache clear` CLI. */
+    clear() {
+        this.withFileLockSync(() => {
+            const target = path.join(this.cacheDir, this.filename);
+            const bak = target + this.bakSuffix;
+            const tmp = target + this.tmpSuffix;
+            for (const f of [target, bak, tmp]) {
+                try {
+                    if (fs.existsSync(f))
+                        fs.unlinkSync(f);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        });
+    }
+    /** Returns the parsed cache file (or an empty shell on failure). */
+    read() {
+        return this.safeRead();
+    }
+    /** Absolute path of the on-disk cache file. */
+    filePath() {
+        return path.join(this.cacheDir, this.filename);
+    }
+    /**
+     * Prunes expired entries. Cheap O(n) scan - intended for engine
+     * startup. Returns the number of entries removed.
+     */
+    pruneExpired() {
+        let removed = 0;
+        this.withFileLockSync(() => {
+            const file = this.safeRead();
+            for (const [k, e] of Object.entries(file.entries)) {
+                if (this.isExpired(e)) {
+                    delete file.entries[k];
+                    removed++;
+                }
+            }
+            if (removed > 0)
+                this.atomicWrite(file);
+        });
+        return removed;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // INTERNAL - read / write / lock
+    // ─────────────────────────────────────────────────────────────
+    isExpired(entry) {
+        if (!entry.ttlExpiresAt)
+            return false;
+        const t = Date.parse(entry.ttlExpiresAt);
+        if (!Number.isFinite(t))
+            return false;
+        return t <= Date.now();
+    }
+    async lockedWrite(input) {
+        const acquired = await this.acquireLockWithBackoff();
+        if (!acquired) {
+            logger_1.logger.warn(`HealingCache: could not acquire lock at ${this.lockDir} - write skipped`);
+            return;
+        }
+        try {
+            const file = this.safeRead();
+            const key = computeCacheKey(input);
+            file.entries[key] = this.buildEntry(key, input, file.entries[key]);
+            this.atomicWrite(file);
+        }
+        finally {
+            this.releaseLock();
+        }
+    }
+    buildEntry(key, input, prev) {
+        const now = new Date().toISOString();
+        const ttlMs = input.ttlMs ?? defaultTtlMs();
+        const ttlExpiresAt = new Date(Date.now() + ttlMs).toISOString();
+        return {
+            key,
+            filePath: input.filePath,
+            line: input.line,
+            dnaContentHash: input.dnaContentHash,
+            brokenSelector: input.brokenSelector,
+            mode: input.mode,
+            healedSelector: input.healedSelector,
+            chainSegments: input.chainSegments,
+            segments: input.segments,
+            confidence: input.confidence,
+            contentChange: input.contentChange,
+            explanation: input.explanation,
+            alternatives: input.alternatives,
+            safe: input.safe,
+            createdAt: prev?.createdAt ?? now,
+            ttlExpiresAt,
+            lastHitAt: prev?.lastHitAt,
+            hitCount: prev?.hitCount ?? 0,
+        };
+    }
+    /**
+     * Reads + parses the cache file. Tolerates every realistic failure
+     * (missing, empty, malformed, wrong schema version) by returning a
+     * fresh empty shell - the contract is "cache misses are silent".
+     */
+    safeRead() {
+        const target = path.join(this.cacheDir, this.filename);
+        let raw;
+        try {
+            raw = fs.readFileSync(target, "utf8");
+        }
+        catch {
+            return { schemaVersion: 1, entries: {} };
+        }
+        if (!raw || raw.trim().length === 0) {
+            return { schemaVersion: 1, entries: {} };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            logger_1.logger.warn(`HealingCache: corrupt cache file at ${target} - starting fresh (${err.message})`);
+            return { schemaVersion: 1, entries: {} };
+        }
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed) ||
+            parsed.schemaVersion !== 1 ||
+            typeof parsed.entries !== "object" ||
+            parsed.entries === null ||
+            Array.isArray(parsed.entries)) {
+            logger_1.logger.warn(`HealingCache: unknown cache schema at ${target} - starting fresh`);
+            return { schemaVersion: 1, entries: {} };
+        }
+        return parsed;
+    }
+    /**
+     * Atomic write via the shared {@link atomicWriteFile} primitive: write to a
+     * pid-temp, copy current to `<file>.bak`, then rename. The rename is the
+     * single commit point - a crash before it leaves the prior file intact.
+     */
+    atomicWrite(file) {
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+        const target = path.join(this.cacheDir, this.filename);
+        (0, atomicWrite_1.atomicWriteFile)(target, JSON.stringify(file, null, 2), { backup: true });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // FILE LOCK - delegated to the shared mkdir-based mutex (Layer 2)
+    // ─────────────────────────────────────────────────────────────
+    acquireLockWithBackoff() {
+        return this.lock.acquire();
+    }
+    withFileLockSync(fn) {
+        this.lock.withLockSync(fn);
+    }
+    releaseLock() {
+        this.lock.release();
+    }
+}
+exports.HealingCacheService = HealingCacheService;
+// ═══════════════════════════════════════════════════════════════════
+// Module-level singleton - engines reuse the same cache file by default
+// ═══════════════════════════════════════════════════════════════════
+exports.sharedHealingCache = new HealingCacheService();

package/dist/services/HealthReportService.d.ts

@@ -0,0 +1,10 @@
+import type { DnaIndex, HealthReport } from "./types.js";
+export interface IHealthReportService {
+    generate(index: DnaIndex): HealthReport;
+    format(report: HealthReport): string;
+}
+export declare class HealthReportService implements IHealthReportService {
+    generate(index: DnaIndex): HealthReport;
+    format(report: HealthReport): string;
+}
+//# sourceMappingURL=HealthReportService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HealthReportService.d.ts","sourceRoot":"","sources":["../../src/services/HealthReportService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAa,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IACxC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC;CACtC;AAoBD,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,YAAY;IAkBvC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;CA0FrC"}