sela-core 1.0.8 → 1.0.9

package/dist/services/ReportGenerator.d.ts

@@ -1,4 +1,77 @@
 import type { HealEvent, HealEventKind } from "./HealReportService";
+export declare const TIME_SAVED_CONSTANTS: {
+    /** A healed selector saved an engineer from manually hunting + patching. */
+    readonly PER_HEAL: 12;
+    /**
+     * Catching a masked regression is worth more — it would have silently
+     * changed test semantics and required a full debugging cycle to uncover.
+     */
+    readonly PER_PROTECT: 18;
+    /**
+     * Partial value: Sela narrowed the debug scope even when it couldn't fix.
+     */
+    readonly PER_FAILED: 4;
+};
+/**
+ * Persisted after every run. Kept in a rolling window of up to 14 entries
+ * by HealReportService. Used to render the Management trend chart.
+ *
+ * **Backend addition required:** HealReportService.flushToDisk() reads
+ * `.sela-history.json`, appends the result of
+ * `ReportGenerator.buildCurrentHistoricalRun()`, trims to 14 entries, writes
+ * it back, and passes the array into `ReportGenerator.generate()`.
+ */
+export interface HistoricalRun {
+    /** Stable identifier — defaults to ISO timestamp but can be CI run ID. */
+    id: string;
+    /** Human-readable x-axis label shown in the trend chart (e.g. "Jan 15"). */
+    label: string;
+    healed: number;
+    protected: number;
+    failed: number;
+    /**
+     * Mean `aiConfidence` across all events in the run (0–100).
+     * Computed by `buildCurrentHistoricalRun()`.
+     * 0 when no events carried a confidence value.
+     */
+    avg_confidence: number;
+    /** Estimated developer minutes saved this run. */
+    time_saved_min: number;
+    /** ISO 8601 — used for deduplication and display sorting. */
+    timestamp: string;
+}
+export interface RoiMetrics {
+    /**
+     * Estimated minutes of developer time saved in THIS run.
+     * Mirrors stats.timeSavedMin — kept here so callers don't need to import
+     * both interfaces.
+     */
+    timeSavedThisRunMin: number;
+    /**
+     * Cumulative minutes saved across all historical runs (including current).
+     * The Management Dashboard renders this as "Total Time Saved This Month"
+     * when the history window covers ~30 days.
+     */
+    timeSavedCumulativeMin: number;
+    /**
+     * Number of PROTECTED events in this run.
+     * Each represents a regression that would have silently mutated test
+     * semantics had Sela auto-applied the AI fix.
+     */
+    bugsPrevented: number;
+    /**
+     * Percentage of all healing attempts (HEALED + PROTECTED) where the
+     * Intent Auditor's final confidence was ≥ 80. Rendered as the
+     * "High Confidence Rate" KPI in the Management view.
+     * `null` when there are no audited events.
+     */
+    highConfidenceRatePct: number | null;
+    /**
+     * Mean aiConfidence across HEALED events only (0–100).
+     * `null` when there are no healed events with a confidence value.
+     */
+    avgHealConfidence: number | null;
+}
 export interface ReportStats {
     total: number;
     healed: number;
@@ -6,64 +79,77 @@ export interface ReportStats {
     protectedCnt: number;
     iframeCnt: number;
     shadowCnt: number;
-    /** Estimated developer time saved, in minutes. */
+    /** Estimated developer minutes saved this run. */
     timeSavedMin: number;
 }
-/**
- * The canonical JSON payload embedded into sela-report.html and
- * mirrored verbatim into sela-report.json.  Treat this as a public
- * contract - additive changes only.
- */
 export interface ReportData {
     generatedAt: string;
     startedAt: string;
     cwd: string;
     events: HealEvent[];
     stats: ReportStats;
+    roi: RoiMetrics;
+    /**
+     * Rolling window of up to 14 runs injected from `.sela-history.json`.
+     * Empty array when no history file exists yet (first run).
+     */
+    historical_runs: HistoricalRun[];
 }
-/**
- * Time-saved heuristics (minutes per event).  Exposed as a constant
- * so tests pin the math against the same source as production.
- */
-export declare const TIME_SAVED_CONSTANTS: {
-    readonly PER_HEAL: 12;
-    readonly PER_PROTECT: 18;
-    readonly PER_FAILED: 4;
-};
 export declare const MANDATORY_FIELDS_BY_KIND: Readonly<Record<HealEventKind, ReadonlyArray<string>>>;
 export declare class ReportGenerator {
     /**
-     * Validates a single event against MANDATORY_FIELDS_BY_KIND.  Throws
-     * a SelaError(subsystem="Report") on the first violation found.  No
-     * partial diagnosis: the report is all-or-nothing.
+     * Validates a single event against MANDATORY_FIELDS_BY_KIND.
+     * Throws a SelaError(subsystem="Report") on the first violation.
      */
     static validateEvent(event: unknown): asserts event is HealEvent;
     /**
-     * Validates every event in the buffer.  Returns the array unchanged
-     * when all events pass.  Throws on the first violation.
+     * Validates every event in the buffer. Returns the typed array when all
+     * events pass. Throws on the first violation.
      */
     static validateAll(events: ReadonlyArray<unknown>): HealEvent[];
     /**
-     * Pure stats computation.  No clock, no IO - easy to pin in tests.
+     * Pure aggregate counters. No clock, no IO — trivially pinnable in tests.
      */
     static computeStats(events: ReadonlyArray<HealEvent>): ReportStats;
     /**
-     * Build the ReportData payload from a raw event buffer.  Validates
-     * every event first.  `now` / `startedAt` are injectable so tests
-     * pin them deterministically.
+     * Derives Management Dashboard KPIs from the event buffer + historical runs.
+     *
+     * `historicalRuns` should already include the current run if you want
+     * cumulative totals to include this run — pass the array AFTER appending
+     * via `buildCurrentHistoricalRun()`.
+     */
+    static computeRoiMetrics(events: ReadonlyArray<HealEvent>, historicalRuns: ReadonlyArray<HistoricalRun>, stats: ReportStats): RoiMetrics;
+    /**
+     * Builds the `HistoricalRun` entry for the current run so the caller can
+     * append it to the persisted sidecar file.
+     *
+     * `runId` — optional override; defaults to ISO timestamp. Pass a CI run ID
+     * (e.g. `process.env.GITHUB_RUN_ID`) when available so deduplication is
+     * reliable across retries.
+     */
+    static buildCurrentHistoricalRun(events: ReadonlyArray<HealEvent>, stats: ReportStats, opts?: {
+        runId?: string;
+        now?: () => Date;
+    }): HistoricalRun;
+    /**
+     * Validates every event, computes all metrics, and assembles the
+     * `ReportData` payload ready for serialisation.
+     *
+     * `historicalRuns` — pass the array from `.sela-history.json` BEFORE
+     * appending the current run; this method appends it internally so the
+     * trend chart always includes the present run.
      */
     static generate(events: ReadonlyArray<unknown>, opts?: {
         cwd?: string;
         startedAt?: string;
+        historicalRuns?: HistoricalRun[];
+        runId?: string;
         now?: () => Date;
     }): ReportData;
     /**
-     * Format a confidence value for UI consumption.  Returns a
-     * percentage string ("87%") for finite numbers, "n/a" for anything
-     * else.  NEVER emits literal "undefined" / "null" / "NaN".
-     *
-     * Public so the HTML template's `fmtPct()` can be replaced by this
-     * single source of truth in a future refactor.
+     * Format a confidence value for UI consumption.
+     * Returns a percentage string ("87%") for finite numbers, "n/a" for
+     * anything else. NEVER emits literal "undefined" / "null" / "NaN".
      */
     static formatConfidence(value: unknown): string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"ReportGenerator.d.ts","sourceRoot":"","sources":["../../src/services/ReportGenerator.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EAId,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;CAIvB,CAAC;AAmCX,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC7C,MAAM,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAK7C,CAAC;AA0BF,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS;IAuChE;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,EAAE;IAK/D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,WAAW;IA4BlE;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CACb,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,IAAI,GAAE;QACJ,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;KACb,GACL,UAAU;IAYb;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAOhD"}
+{"version":3,"file":"ReportGenerator.d.ts","sourceRoot":"","sources":["../../src/services/ReportGenerator.ts"],"names":[],"mappings":"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"}

package/dist/services/ReportGenerator.js

@@ -1,49 +1,46 @@
 "use strict";
 // src/services/ReportGenerator.ts
 //
-// Pure (no-IO) report layer.  Takes the HealReportService event buffer
-// and produces a stable, validated JSON shape that the HTML template
-// and any external consumer (CI dashboards, telemetry forwarders)
-// can rely on.
+// Sela Insights — Pure (no-IO) report layer.
 //
-// Design goals:
-//   1. SCHEMA ENFORCED.  Every event passed through ReportGenerator
-//      is validated against MANDATORY_FIELDS_BY_KIND - a SelaError
-//      with subsystem="Report" is thrown for any malformed input.
-//      The HTML template never sees a partial event.
-//
-//   2. CONFIDENCE NEVER LEAKS.  formatConfidence() and the rendered
-//      `confidenceLabel` field always produce either a "<n>%" string
-//      or "n/a" - never `undefined`, `null`, or a stringified
-//      "undefined".  The JS embedded in HealReportService already
-//      uses fmtPct() for the same reason; this module is the
-//      authoritative implementation.
-//
-//   3. STATS DETERMINISTIC.  computeStats() exposes the time-saved
-//      constants via TIME_SAVED_CONSTANTS so tests can pin the math
-//      without duplicating the multipliers.
-//
-//   4. NO IO.  Disk writes still live in HealReportService.flushToDisk
-//      so this module stays trivially unit-testable.
+// Responsibilities:
+//   1. SCHEMA VALIDATION  — every event is validated against
+//      MANDATORY_FIELDS_BY_KIND before the HTML template ever sees it.
+//   2. STATS + METRICS    — computeStats(), computeRoiMetrics(), and
+//      buildCurrentHistoricalRun() are the single source of truth for
+//      every number rendered in the Management Dashboard.
+//   3. CONFIDENCE SAFETY  — formatConfidence() always emits "<n>%" or
+//      "n/a"; never "undefined", "null", or "NaN".
+//   4. NO IO              — disk operations stay in HealReportService so
+//      this module is trivially unit-testable without mocking fs.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReportGenerator = exports.MANDATORY_FIELDS_BY_KIND = exports.TIME_SAVED_CONSTANTS = void 0;
 const SelaError_1 = require("../errors/SelaError");
-/**
- * Time-saved heuristics (minutes per event).  Exposed as a constant
- * so tests pin the math against the same source as production.
- */
+// ─────────────────────────────────────────────────────────────────────────────
+// TIME-SAVED HEURISTICS  (minutes per event kind)
+// Exposed as a constant so tests can pin the math against the same multipliers
+// as production without duplicating them.
+// ─────────────────────────────────────────────────────────────────────────────
 exports.TIME_SAVED_CONSTANTS = {
+    /** A healed selector saved an engineer from manually hunting + patching. */
     PER_HEAL: 12,
+    /**
+     * Catching a masked regression is worth more — it would have silently
+     * changed test semantics and required a full debugging cycle to uncover.
+     */
     PER_PROTECT: 18,
+    /**
+     * Partial value: Sela narrowed the debug scope even when it couldn't fix.
+     */
     PER_FAILED: 4,
 };
-// ───────────────────────────────────────────────────────────────────
-// Field manifests - mandatory for each event kind
+// ─────────────────────────────────────────────────────────────────────────────
+// FIELD MANIFESTS  — mandatory per event kind
 //
-// "Mandatory" = the HTML template will render an unintelligible card
-// without this field.  Anything optional belongs in the interface
-// declarations in HealReportService.ts but NOT here.
-// ───────────────────────────────────────────────────────────────────
+// "Mandatory" means the HTML card renderer produces a broken / misleading UI
+// without this field. Optional fields belong in the interface declarations in
+// HealReportService.ts but NOT here.
+// ─────────────────────────────────────────────────────────────────────────────
 const COMMON_MANDATORY = [
     "kind",
     "stableId",
@@ -71,9 +68,9 @@ exports.MANDATORY_FIELDS_BY_KIND = {
     PROTECTED: [...COMMON_MANDATORY, ...PROTECTED_MANDATORY],
 };
 const VALID_KINDS = new Set(["HEALED", "FAILED", "PROTECTED"]);
-// ───────────────────────────────────────────────────────────────────
-// Helpers
-// ───────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+// HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
 function throwReport(code, reason, ctx = {}) {
     throw new SelaError_1.SelaError({ subsystem: "Report", code, reason, context: ctx });
 }
@@ -84,14 +81,28 @@ function isPresent(value) {
         return false;
     return true;
 }
-// ───────────────────────────────────────────────────────────────────
+function shortDateLabel(iso) {
+    try {
+        const d = new Date(iso);
+        return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+    }
+    catch {
+        return iso.slice(0, 10);
+    }
+}
+function mean(values) {
+    if (values.length === 0)
+        return null;
+    return Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // ReportGenerator
-// ───────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
 class ReportGenerator {
+    // ── Validation ────────────────────────────────────────────────────────────
     /**
-     * Validates a single event against MANDATORY_FIELDS_BY_KIND.  Throws
-     * a SelaError(subsystem="Report") on the first violation found.  No
-     * partial diagnosis: the report is all-or-nothing.
+     * Validates a single event against MANDATORY_FIELDS_BY_KIND.
+     * Throws a SelaError(subsystem="Report") on the first violation.
      */
     static validateEvent(event) {
         if (!event || typeof event !== "object") {
@@ -99,7 +110,7 @@ class ReportGenerator {
         }
         const ev = event;
         if (!ev.kind || !VALID_KINDS.has(ev.kind)) {
-            throwReport(SelaError_1.REPORT_CODES.UNKNOWN_KIND, `Unknown event.kind "${String(ev.kind)}" - must be HEALED|FAILED|PROTECTED`, { stableId: ev.stableId });
+            throwReport(SelaError_1.REPORT_CODES.UNKNOWN_KIND, `Unknown event.kind "${String(ev.kind)}" — must be HEALED|FAILED|PROTECTED`, { stableId: ev.stableId });
         }
         const required = exports.MANDATORY_FIELDS_BY_KIND[ev.kind];
         for (const field of required) {
@@ -108,29 +119,25 @@ class ReportGenerator {
                 throwReport(SelaError_1.REPORT_CODES.MISSING_FIELD, `${ev.kind} event missing mandatory field "${field}"`, { stableId: ev.stableId, kind: ev.kind, field });
             }
         }
-        // Field-type sanity for the fields we publicly mandate.
         if (typeof ev.sourceLine !== "number") {
             throwReport(SelaError_1.REPORT_CODES.INVALID_FIELD_TYPE, `Field "sourceLine" must be a number, received ${typeof ev.sourceLine}`, { stableId: ev.stableId, kind: ev.kind, field: "sourceLine" });
         }
     }
     /**
-     * Validates every event in the buffer.  Returns the array unchanged
-     * when all events pass.  Throws on the first violation.
+     * Validates every event in the buffer. Returns the typed array when all
+     * events pass. Throws on the first violation.
      */
     static validateAll(events) {
         for (const e of events)
             ReportGenerator.validateEvent(e);
         return events;
     }
+    // ── Stats ─────────────────────────────────────────────────────────────────
     /**
-     * Pure stats computation.  No clock, no IO - easy to pin in tests.
+     * Pure aggregate counters. No clock, no IO — trivially pinnable in tests.
      */
     static computeStats(events) {
-        let healed = 0;
-        let failed = 0;
-        let protectedCnt = 0;
-        let iframeCnt = 0;
-        let shadowCnt = 0;
+        let healed = 0, failed = 0, protectedCnt = 0, iframeCnt = 0, shadowCnt = 0;
         for (const e of events) {
             if (e.kind === "HEALED")
                 healed++;
@@ -156,34 +163,114 @@ class ReportGenerator {
             timeSavedMin,
         };
     }
+    // ── ROI Metrics ───────────────────────────────────────────────────────────
     /**
-     * Build the ReportData payload from a raw event buffer.  Validates
-     * every event first.  `now` / `startedAt` are injectable so tests
-     * pin them deterministically.
+     * Derives Management Dashboard KPIs from the event buffer + historical runs.
+     *
+     * `historicalRuns` should already include the current run if you want
+     * cumulative totals to include this run — pass the array AFTER appending
+     * via `buildCurrentHistoricalRun()`.
+     */
+    static computeRoiMetrics(events, historicalRuns, stats) {
+        // bugs prevented = all PROTECTED events this run
+        const bugsPrevented = stats.protectedCnt;
+        // cumulative time saved across all historical runs (includes current if
+        // caller appended it before passing here)
+        const timeSavedCumulativeMin = historicalRuns.reduce((sum, r) => sum + r.time_saved_min, 0);
+        // high-confidence rate: among events that have an auditor confidence,
+        // what fraction scored ≥ 80?
+        const audited = events.filter((e) => (e.kind === "HEALED" || e.kind === "PROTECTED") &&
+            e.auditor != null &&
+            typeof e.auditor.confidence === "number" &&
+            isFinite(e.auditor.confidence));
+        const highConfidenceRatePct = audited.length === 0
+            ? null
+            : Math.round((audited.filter((e) => (e.auditor.confidence ?? 0) >= 80).length /
+                audited.length) *
+                100);
+        // avg heal confidence (HEALED events only)
+        const healedWithConf = events.filter((e) => e.kind === "HEALED")
+            .map((e) => e.aiConfidence)
+            .filter((v) => typeof v === "number" && isFinite(v));
+        const avgHealConfidence = mean(healedWithConf);
+        return {
+            timeSavedThisRunMin: stats.timeSavedMin,
+            timeSavedCumulativeMin,
+            bugsPrevented,
+            highConfidenceRatePct,
+            avgHealConfidence,
+        };
+    }
+    // ── Historical run builder ────────────────────────────────────────────────
+    /**
+     * Builds the `HistoricalRun` entry for the current run so the caller can
+     * append it to the persisted sidecar file.
+     *
+     * `runId` — optional override; defaults to ISO timestamp. Pass a CI run ID
+     * (e.g. `process.env.GITHUB_RUN_ID`) when available so deduplication is
+     * reliable across retries.
+     */
+    static buildCurrentHistoricalRun(events, stats, opts = {}) {
+        const now = opts.now ? opts.now() : new Date();
+        const ts = now.toISOString();
+        const confidenceValues = events
+            .filter((e) => typeof e.aiConfidence === "number")
+            .map((e) => e.aiConfidence)
+            .filter((v) => isFinite(v));
+        const avg_confidence = confidenceValues.length > 0
+            ? Math.round(confidenceValues.reduce((a, b) => a + b, 0) /
+                confidenceValues.length)
+            : 0;
+        return {
+            id: opts.runId ?? ts,
+            label: shortDateLabel(ts),
+            healed: stats.healed,
+            protected: stats.protectedCnt,
+            failed: stats.failed,
+            avg_confidence,
+            time_saved_min: stats.timeSavedMin,
+            timestamp: ts,
+        };
+    }
+    // ── Full payload builder ──────────────────────────────────────────────────
+    /**
+     * Validates every event, computes all metrics, and assembles the
+     * `ReportData` payload ready for serialisation.
+     *
+     * `historicalRuns` — pass the array from `.sela-history.json` BEFORE
+     * appending the current run; this method appends it internally so the
+     * trend chart always includes the present run.
      */
     static generate(events, opts = {}) {
         const validated = ReportGenerator.validateAll(events);
         const now = opts.now ?? (() => new Date());
+        const stats = ReportGenerator.computeStats(validated);
+        const currentRun = ReportGenerator.buildCurrentHistoricalRun(validated, stats, { runId: opts.runId, now });
+        // Merge history: drop any prior entry with the same id, append current,
+        // then keep only the most recent HISTORY_WINDOW entries.
+        const HISTORY_WINDOW = 14;
+        const prior = (opts.historicalRuns ?? []).filter((r) => r.id !== currentRun.id);
+        const historical_runs = [...prior, currentRun].slice(-HISTORY_WINDOW);
+        const roi = ReportGenerator.computeRoiMetrics(validated, historical_runs, stats);
         return {
             generatedAt: now().toISOString(),
             startedAt: opts.startedAt ?? now().toISOString(),
             cwd: opts.cwd ?? process.cwd(),
             events: validated,
-            stats: ReportGenerator.computeStats(validated),
+            stats,
+            roi,
+            historical_runs,
         };
     }
+    // ── Confidence formatter ──────────────────────────────────────────────────
     /**
-     * Format a confidence value for UI consumption.  Returns a
-     * percentage string ("87%") for finite numbers, "n/a" for anything
-     * else.  NEVER emits literal "undefined" / "null" / "NaN".
-     *
-     * Public so the HTML template's `fmtPct()` can be replaced by this
-     * single source of truth in a future refactor.
+     * Format a confidence value for UI consumption.
+     * Returns a percentage string ("87%") for finite numbers, "n/a" for
+     * anything else. NEVER emits literal "undefined" / "null" / "NaN".
      */
     static formatConfidence(value) {
         if (typeof value === "number" && Number.isFinite(value)) {
-            const clamped = Math.max(0, Math.min(100, Math.round(value)));
-            return `${clamped}%`;
+            return `${Math.max(0, Math.min(100, Math.round(value)))}%`;
         }
         return "n/a";
     }

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

@@ -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;

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

@@ -1 +1 @@
-{"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,wEAAwE;IACxE,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"}
+{"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"}