sela-core 1.0.7 → 1.0.9

package/dist/services/ReportMergeService.d.ts

@@ -0,0 +1,95 @@
+import { type HistoricalRun, type ReportData } from "./ReportGenerator.js";
+import { type HealEvent } from "./HealReportService.js";
+export interface MergeOptions {
+    /**
+     * Explicit shard report files (`sela-report.json` shape, or a bare event
+     * array). When empty, the caller is expected to have discovered files via
+     * {@link discoverShardFiles}.
+     */
+    shardFiles: string[];
+    /** Where the merged report + rolling history are written. */
+    targetDir: string;
+    /**
+     * Single dedup key for the merged history row. Defaults to
+     * GITHUB_RUN_ID ?? CI_PIPELINE_ID ?? ISO timestamp (resolved by
+     * ReportGenerator). Pass explicitly in CI so retries overwrite cleanly.
+     */
+    runId?: string;
+    /**
+     * Number of shards the pipeline launched. When provided and more than the
+     * number of readable shard files, the merge is flagged as partial.
+     */
+    expectedShards?: number;
+    /**
+     * Optional logger seam (tests inject a spy). Defaults to console.
+     */
+    logger?: {
+        warn: (msg: string) => void;
+        info: (msg: string) => void;
+    };
+}
+export interface MergeResult {
+    htmlPath: string;
+    /** Total events read across all shard files BEFORE dedup. */
+    totalEvents: number;
+    /** Events surviving content-identity dedup (== payload event count). */
+    uniqueEvents: number;
+    /** totalEvents - uniqueEvents. */
+    duplicatesDropped: number;
+    /** Shard files successfully parsed. */
+    shardsRead: number;
+    /** Shard files that existed/were passed but failed to parse. */
+    shardsSkipped: number;
+    /** expectedShards echoed back, or null when not supplied. */
+    shardsExpected: number | null;
+    /** max(0, expectedShards - shardsRead); 0 when not supplied. */
+    shardsMissing: number;
+    /** True when shardsMissing > 0 — the report is built from partial data. */
+    partial: boolean;
+    /** Human-readable advisories surfaced during the merge. */
+    warnings: string[];
+    /** The full computed payload (handy for tests / programmatic callers). */
+    data: ReportData;
+}
+export declare class ReportMergeService {
+    /**
+     * Discover shard report files inside `dir` whose filename matches `glob`.
+     * Only a single `*` wildcard is supported (e.g. `sela-shard-*.json`) — we
+     * deliberately avoid pulling in a glob dependency. Returns absolute paths,
+     * sorted for deterministic ordering.
+     */
+    static discoverShardFiles(dir: string, glob?: string): string[];
+    /**
+     * Content identity for an event. A retried test replayed on a different
+     * shard yields an identical identity and is collapsed to one. Timestamp is
+     * intentionally EXCLUDED — clock skew across runners must not defeat dedup.
+     */
+    static eventIdentity(e: HealEvent): string;
+    /**
+     * Read one shard file and return its events array.
+     * Accepts the `sela-report.json` shape (`{ events: [...] }`) or a bare
+     * `HealEvent[]`. Throws SelaError(SHARD_UNREADABLE) on malformed input so
+     * the caller can decide whether a single bad shard is fatal (it is not —
+     * `merge()` catches and flags it).
+     */
+    static readShardEvents(file: string): HealEvent[];
+    /**
+     * Read the prior rolling history with a STRICT integrity guard.
+     *   • Absent file               → [] (first run / clean bootstrap).
+     *   • Present, valid JSON array  → the array.
+     *   • Present but NOT a JSON array (corrupt / truncated / wrong shape)
+     *                                → THROW.
+     *
+     * The throw is the whole point: in the artifact flow the prior history was
+     * just downloaded; if it is corrupt we must NOT overwrite the durable copy
+     * with a fresh 1-entry window. Aborting forces an operator to look instead
+     * of silently destroying the trend.
+     */
+    static readPriorHistory(targetDir: string): HistoricalRun[];
+    /**
+     * Merge N shard reports into a single coherent history row + report.
+     * See the file header for the full rationale.
+     */
+    static merge(opts: MergeOptions): MergeResult;
+}
+//# sourceMappingURL=ReportMergeService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReportMergeService.d.ts","sourceRoot":"","sources":["../../src/services/ReportMergeService.ts"],"names":[],"mappings":"AAyCA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAQ3E,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACvE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,UAAU,CAAC;CAClB;AAMD,qBAAa,kBAAkB;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAsB,GAAG,MAAM,EAAE;IAe5E;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM;IAO1C;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE;IA2CjD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAuC3D;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW;CA6F9C"}

package/dist/services/SafetyGuard.d.ts

@@ -11,7 +11,7 @@ export interface HealContext {
 }
 export interface AIFixSummary {
     /**
-     * Raw AI confidence 0-100. `undefined` when the LLM omitted the field —
+     * Raw AI confidence 0-100. `undefined` when the LLM omitted the field -
      * SafetyGuard's hard-stop / review-threshold logic treats absence as the
      * conservative worst case (0) so unverified heals are NOT silently let
      * through, while downstream report renderers display "n/a".
@@ -24,9 +24,9 @@ export interface AIFixSummary {
     explanation?: string;
     /** Live innerText of the new selector fetched directly from the browser. */
     liveText?: string;
-    /** Baseline text from the DNA snapshot — what the element showed before. */
+    /** Baseline text from the DNA snapshot - what the element showed before. */
     dnaBaselineText?: string;
-    /** ARIA role from the DNA snapshot — used by the Intent Auditor. */
+    /** ARIA role from the DNA snapshot - used by the Intent Auditor. */
     dnaRole?: string;
     /** Visibility info captured from the candidate element (new selector). */
     liveVisibility?: VisibilityInfo;
@@ -51,7 +51,7 @@ export interface SafetyDecision {
      * REQUIRES_REVIEW) may omit it.
      */
     code?: SafetyGuardCode;
-    /** Structured info for policy-aware log messages in FixwrightEngine. */
+    /** Structured info for policy-aware log messages in SelaEngine. */
     meta?: {
         auditorVerdict?: "CONSISTENT" | "SUSPICIOUS" | "INCONSISTENT";
         auditorConfidence?: number;
@@ -89,9 +89,6 @@ export declare class SafetyGuard {
     evaluate(context: HealContext, aiFix: AIFixSummary): Promise<SafetyDecision>;
     private isSemanticOpposite;
     classifyFunctionalRole(text: string): FunctionalRole;
-    computeSemanticSimilarity(a: string, b: string): number;
-    private levenshteinDistance;
-    private jaccardSimilarity;
 }
 export {};
 //# sourceMappingURL=SafetyGuard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"SafetyGuard.d.ts","sourceRoot":"","sources":["../../src/services/SafetyGuard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SafetyGuard.d.ts","sourceRoot":"","sources":["../../src/services/SafetyGuard.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAsB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM1E,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,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,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,mEAAmE;IACnE,IAAI,CAAC,EAAE;QACL,cAAc,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC;QAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,qFAAqF;QACrF,mBAAmB,CAAC,EAAE;YACpB,aAAa,EAAE,MAAM,CAAC;YACtB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC;YACd,kBAAkB,EAAE,MAAM,CAAC;SAC5B,CAAC;KACH,CAAC;CACH;AA4DD,KAAK,cAAc,GACf,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,MAAM,GACN,iBAAiB,GACjB,iBAAiB,GACjB,SAAS,CAAC;AA6Jd;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAqB;IAEvC;;;;OAIG;gBACS,GAAG,CAAC,EAAE,kBAAkB,GAAG,kBAAkB;IAMzD,OAAO,CAAC,MAAM,CAAC,aAAa;IAgBtB,QAAQ,CACZ,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC;IAyS1B,OAAO,CAAC,kBAAkB;IAwB1B,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;CAUrD"}

package/dist/services/SafetyGuard.js

@@ -10,12 +10,11 @@ const SelaError_1 = require("../errors/SelaError");
 const DEFAULT_THRESHOLDS = {
     confidenceHardStop: 85,
     confidenceReviewThreshold: 95,
-    assertionSimilarityFloor: 0.7,
     auditorConfidenceMin: 75,
     allowSuspicious: false,
     auditorStrictness: "balanced",
 };
-// Binary semantic opposites — always trigger FAIL_HARD regardless of mode,
+// Binary semantic opposites - always trigger FAIL_HARD regardless of mode,
 // because they indicate a state inversion (pass→fail, success→error, etc.)
 // that almost certainly masks a real logical regression.
 const SEMANTIC_OPPOSITE_PAIRS = new Set([
@@ -190,7 +189,7 @@ const ROLE_KEYWORDS = new Map([
     ],
 ]);
 // Pre-compiled word-boundary regexes for the role classifier.  Built
-// once at module load — classifyFunctionalRole() is on the hot heal
+// 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,
@@ -242,7 +241,7 @@ class SafetyGuard {
                 return {
                     level: "FAIL_HARD",
                     code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_VISIBILITY_GHOST,
-                    reason: `Visibility Gate: candidate element is a Ghost (${vis.ghostReason}) — ` +
+                    reason: `Visibility Gate: candidate element is a Ghost (${vis.ghostReason}) - ` +
                         `functionally absent from the user's perspective`,
                     canProceed: false,
                 };
@@ -253,12 +252,12 @@ class SafetyGuard {
                     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}" — ` +
+                        reason: `Visibility Gate: candidate element is occluded by an overlay on branch "${context.branch}" - ` +
                             `hard-fail policy active on main`,
                         canProceed: false,
                     };
                 }
-                console.warn(`[SafetyGuard] ⚠️  Occlusion detected on branch "${context.branch ?? "unknown"}" — ` +
+                console.warn(`[SafetyGuard] ⚠️  Occlusion detected on branch "${context.branch ?? "unknown"}" - ` +
                     `escalating to REQUIRES_REVIEW (not hard-failing on non-main branch)`);
                 return {
                     level: "REQUIRES_REVIEW",
@@ -273,7 +272,7 @@ class SafetyGuard {
             return {
                 level: "BLOCKED",
                 code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_LOW_CONFIDENCE,
-                reason: `Confidence too low (${confidence}/100 < ${this.thresholds.confidenceHardStop}) — refusing to heal`,
+                reason: `Confidence too low (${confidence}/100 < ${this.thresholds.confidenceHardStop}) - refusing to heal`,
                 canProceed: false,
             };
         }
@@ -284,16 +283,18 @@ class SafetyGuard {
         //
         // When liveText + dnaBaselineText are both available and differ, we
         // synthesise a contentChange pair and apply the full inversion-check
-        // pipeline on it — regardless of what the AI reported.
+        // pipeline on it - regardless of what the AI reported.
         //
         // If the AI DID report contentChange we use that (more precise than raw
         // innerText, which may include child element noise).
         let effectiveContentChange = aiFix.contentChange;
-        if (!effectiveContentChange && liveText !== undefined && dnaBaselineText !== undefined) {
+        if (!effectiveContentChange &&
+            liveText !== undefined &&
+            dnaBaselineText !== undefined) {
             const normLive = liveText.trim();
             const normDNA = dnaBaselineText.trim();
             if (normLive !== normDNA && normLive.length > 0 && normDNA.length > 0) {
-                console.warn(`[SafetyGuard] 🚨 Zero-Trust override — AI omitted contentChange but live DOM differs:\n` +
+                console.warn(`[SafetyGuard] 🚨 Zero-Trust override - AI omitted contentChange but live DOM differs:\n` +
                     `  DNA baseline : "${normDNA}"\n` +
                     `  Live text    : "${normLive}"`);
                 effectiveContentChange = { oldText: normDNA, newText: normLive };
@@ -301,7 +302,9 @@ class SafetyGuard {
         }
         // ── 3. Structural-only heal (no text change detected) ────────
         if (!effectiveContentChange) {
-            const level = confidence < this.thresholds.confidenceReviewThreshold ? "REQUIRES_REVIEW" : "SAFE";
+            const level = confidence < this.thresholds.confidenceReviewThreshold
+                ? "REQUIRES_REVIEW"
+                : "SAFE";
             return {
                 level,
                 reason: `Structural selector change only (confidence=${confidence})`,
@@ -313,12 +316,12 @@ class SafetyGuard {
         console.log(`[SafetyGuard] 🔬 Content change (${source}): "${oldText}" → "${newText}"`);
         // ── 4. Binary semantic-opposite guard ────────────────────────
         // Applies in ALL modes: "Enabled"→"Disabled", "Success"→"Error", etc.
-        // These always indicate a state inversion — never safe to auto-heal.
+        // These always indicate a state inversion - never safe to auto-heal.
         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}" — ` +
+                reason: `Semantic inversion detected: "${oldText}" ↔ "${newText}" - ` +
                     `state inversions mask logical regressions`,
                 canProceed: false,
             };
@@ -334,30 +337,28 @@ class SafetyGuard {
             return {
                 level: "FAIL_HARD",
                 code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_STATUS_INVERSION,
-                reason: `Status inversion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) — ` +
+                reason: `Status inversion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) - ` +
                     `masking a logic failure is not permitted`,
                 canProceed: false,
             };
         }
         // Cross-role swap (e.g. DELETE → CANCEL, SUBMIT → NAVIGATE)
-        if (oldRole !== "UNKNOWN" &&
-            newRole !== "UNKNOWN" &&
-            oldRole !== newRole) {
+        if (oldRole !== "UNKNOWN" && newRole !== "UNKNOWN" && oldRole !== newRole) {
             if (mode === "assertion") {
                 // Assertion explicitly checked the old functional text; a different
                 // 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}) — ` +
+                    reason: `Functional role swap in assertion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) - ` +
                         `the assertion was verifying a specific functional state`,
                     canProceed: false,
                 };
             }
-            // Action mode: allow with warning — a UI refactor may rename a control
+            // Action mode: allow with warning - a UI refactor may rename a control
             // (e.g. "Delete" button renamed "Remove" or merged into a menu)
             console.warn(`[SafetyGuard] ⚠️  Functional role change in action: ` +
-                `"${oldText}" (${oldRole}) → "${newText}" (${newRole}) — review recommended`);
+                `"${oldText}" (${oldRole}) → "${newText}" (${newRole}) - review recommended`);
             return {
                 level: "REQUIRES_REVIEW",
                 reason: `Functional role change in action: "${oldText}" (${oldRole}) → "${newText}" (${newRole})`,
@@ -392,7 +393,7 @@ class SafetyGuard {
                 return {
                     level: "FAIL_HARD",
                     code: SelaError_1.SAFETY_GUARD_CODES.FAIL_HARD_AUDITOR_INCONSISTENT,
-                    reason: `Intent Auditor — INCONSISTENT: ${auditVerdict.reason}` +
+                    reason: `Intent Auditor - INCONSISTENT: ${auditVerdict.reason}` +
                         (auditVerdict.inversionType
                             ? ` [inversion: ${auditVerdict.inversionType}]`
                             : ""),
@@ -409,23 +410,23 @@ class SafetyGuard {
                     return {
                         level: "BLOCKED",
                         code: SelaError_1.SAFETY_GUARD_CODES.BLOCKED_AUDITOR_SUSPICIOUS,
-                        reason: `Intent Auditor — SUSPICIOUS in assertion mode: ${auditVerdict.reason}`,
+                        reason: `Intent Auditor - SUSPICIOUS in assertion mode: ${auditVerdict.reason}`,
                         canProceed: false,
                         meta,
                     };
                 }
                 if (this.thresholds.allowSuspicious && mode === "assertion") {
-                    console.log(`[SafetyGuard] ℹ️  allowSuspicious=true — SUSPICIOUS in assertion mode escalated to REQUIRES_REVIEW`);
+                    console.log(`[SafetyGuard] ℹ️  allowSuspicious=true - SUSPICIOUS in assertion mode escalated to REQUIRES_REVIEW`);
                 }
                 return {
                     level: "REQUIRES_REVIEW",
-                    reason: `Intent Auditor — SUSPICIOUS in ${mode} mode: ${auditVerdict.reason}`,
+                    reason: `Intent Auditor - SUSPICIOUS in ${mode} mode: ${auditVerdict.reason}`,
                     canProceed: true,
                     meta,
                 };
             }
-            // CONSISTENT — fall through to similarity gate
-            console.log(`[SafetyGuard] ✅ Intent Auditor — CONSISTENT (${auditVerdict.confidence}%): ${auditVerdict.reason}`);
+            // CONSISTENT - fall through to confidence tiers
+            console.log(`[SafetyGuard] ✅ Intent Auditor - CONSISTENT (${auditVerdict.confidence}%): ${auditVerdict.reason}`);
             if (auditVerdict.scoreBreakdown) {
                 const { rawConfidence, penalty, bonus } = auditVerdict.scoreBreakdown;
                 if (penalty !== 0 || bonus !== 0) {
@@ -440,32 +441,11 @@ class SafetyGuard {
                 }
             }
         }
-        // ── 8. Semantic similarity gate (same-role or both UNKNOWN) ──
-        // For same-role pairs (e.g. SUBMIT→SUBMIT: "Submit"→"Send") we skip
-        // the similarity gate entirely — the role match is sufficient proof
-        // of functional equivalence.
-        //
-        // The gate is only applied when BOTH roles are UNKNOWN in assertion
-        // mode, where we have no functional category to fall back on.
-        if (mode === "assertion" && oldRole === "UNKNOWN" && newRole === "UNKNOWN") {
-            const similarity = this.computeSemanticSimilarity(oldText, newText);
-            console.log(`[SafetyGuard] 📊 Similarity: "${oldText}" ↔ "${newText}" = ${(similarity * 100).toFixed(1)}%`);
-            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`,
-                    canProceed: false,
-                };
-            }
-        }
-        // ── 9. Confidence tiers ──────────────────────────────────────
+        // ── 8. Confidence tiers ──────────────────────────────────────
         if (confidence < this.thresholds.confidenceReviewThreshold) {
             return {
                 level: "REQUIRES_REVIEW",
-                reason: `Low-confidence fix (${confidence}/100) — tagging for manual review`,
+                reason: `Low-confidence fix (${confidence}/100) - tagging for manual review`,
                 canProceed: true,
                 meta: localAuditMeta,
             };
@@ -515,62 +495,5 @@ class SafetyGuard {
         }
         return "UNKNOWN";
     }
-    // ─────────────────────────────────────────────────────────────
-    // SEMANTIC SIMILARITY  (no external dependencies)
-    //
-    // Combined score: 0.5 × levenshtein_similarity + 0.5 × jaccard_similarity
-    //
-    // Levenshtein captures character-level similarity (typos, abbreviations).
-    // Jaccard captures word-level overlap (shared vocabulary, different order).
-    // The 50/50 blend is robust against short labels where one metric misleads.
-    // ─────────────────────────────────────────────────────────────
-    computeSemanticSimilarity(a, b) {
-        const na = a.toLowerCase().trim();
-        const nb = b.toLowerCase().trim();
-        if (na === nb)
-            return 1;
-        const maxLen = Math.max(na.length, nb.length);
-        const levSim = maxLen === 0 ? 1 : 1 - this.levenshteinDistance(na, nb) / maxLen;
-        const jaccard = this.jaccardSimilarity(na, nb);
-        return 0.5 * levSim + 0.5 * jaccard;
-    }
-    // ─────────────────────────────────────────────────────────────
-    // PRIVATE: Levenshtein distance (space-optimised two-row DP)
-    // ─────────────────────────────────────────────────────────────
-    levenshteinDistance(a, b) {
-        const m = a.length;
-        const n = b.length;
-        if (m === 0)
-            return n;
-        if (n === 0)
-            return m;
-        let prev = Array.from({ length: n + 1 }, (_, i) => i);
-        let curr = new Array(n + 1);
-        for (let i = 1; i <= m; i++) {
-            curr[0] = i;
-            for (let j = 1; j <= n; j++) {
-                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-                curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-            }
-            [prev, curr] = [curr, prev];
-        }
-        return prev[n];
-    }
-    // ─────────────────────────────────────────────────────────────
-    // PRIVATE: Jaccard word-set similarity
-    // ─────────────────────────────────────────────────────────────
-    jaccardSimilarity(a, b) {
-        const setA = new Set(a.split(/\s+/).filter(Boolean));
-        const setB = new Set(b.split(/\s+/).filter(Boolean));
-        if (setA.size === 0 && setB.size === 0)
-            return 1;
-        let intersection = 0;
-        for (const w of setA) {
-            if (setB.has(w))
-                intersection++;
-        }
-        const union = setA.size + setB.size - intersection;
-        return union === 0 ? 1 : intersection / union;
-    }
 }
 exports.SafetyGuard = SafetyGuard;

package/dist/services/SelectorSanitizer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * True when `value` is (or contains, in a `>>` chain) a Playwright internal
+ * engine selector. These start with the `internal:` engine prefix.
+ */
+export declare function isInternalEngineSelector(value: string): boolean;
+interface MethodDescriptor {
+    method: string;
+    primaryArg: string;
+    options?: Record<string, string | boolean | number>;
+}
+/**
+ * Parse a SINGLE internal selector segment into a method descriptor, or null
+ * when it is not a recognised internal form (so callers REFUSE rather than
+ * guess). Mirrors the engine→public mapping used by ASTSourceUpdater.
+ */
+export declare function parseInternalSelector(selector: string): MethodDescriptor | null;
+export declare function buildMethodCall(receiver: string, desc: MethodDescriptor): string;
+/**
+ * Translate an internal selector string into an idiomatic Playwright method
+ * expression rooted at `receiver`. Handles `>>` chains by chaining each
+ * segment. Returns null when ANY segment is an unrecognised internal form
+ * (frame `internal:control=…` plumbing, unknown engines) — the caller must
+ * then refuse rather than emit something fragile.
+ */
+export declare function internalToMethodExpression(selector: string, receiver?: string): string | null;
+/**
+ * Convert an internal engine selector into a VALID PUBLIC `.locator()` string,
+ * preserving `>>` chaining. Returns null when ANY internal segment has no
+ * public string engine (so the caller must method-shift or refuse instead of
+ * stuffing an unusable string into a constant).
+ *
+ * Example: `internal:role=button[name="Update System"i]`
+ *        → `role=button[name="Update System"]`
+ */
+export declare function internalToPublicSelectorString(selector: string): string | null;
+export interface SanitizeResult {
+    /** The (possibly rewritten) expression text. */
+    text: string;
+    /** True when the original contained an internal selector that was rewritten. */
+    sanitized: boolean;
+    /** False when an internal selector remained that could NOT be translated. */
+    safe: boolean;
+}
+/**
+ * Rewrite any `recv.locator("internal:…")` / `recv.frameLocator("internal:…")`
+ * inside `expr` to its idiomatic method form. Returns `safe:false` when an
+ * internal selector remains that cannot be translated, so the caller refuses
+ * to write it.
+ */
+export declare function sanitizeLocatorExpression(expr: string): SanitizeResult;
+export {};
+//# sourceMappingURL=SelectorSanitizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SelectorSanitizer.d.ts","sourceRoot":"","sources":["../../src/services/SelectorSanitizer.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D;AAMD,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA6D/E;AAWD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAyBhF;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAS,GAChB,MAAM,GAAG,IAAI,CAmBf;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB9E;AAMD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAgEtE"}