sela-core 0.1.0-alpha.1

package/dist/services/ReportGenerator.js

@@ -0,0 +1,278 @@
+"use strict";
+// src/services/ReportGenerator.ts
+//
+// Sela Insights — Pure (no-IO) report layer.
+//
+// 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 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 per event kind
+//
+// "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",
+    "sourceFile",
+    "sourceLine",
+    "timestamp",
+];
+const HEALED_MANDATORY = [
+    "oldSelector",
+    "newSelector",
+    "dnaBefore",
+];
+const FAILED_MANDATORY = [
+    "oldSelector",
+    "reason",
+];
+const PROTECTED_MANDATORY = [
+    "oldSelector",
+    "reason",
+    "safetyLevel",
+];
+exports.MANDATORY_FIELDS_BY_KIND = {
+    HEALED: [...COMMON_MANDATORY, ...HEALED_MANDATORY],
+    FAILED: [...COMMON_MANDATORY, ...FAILED_MANDATORY],
+    PROTECTED: [...COMMON_MANDATORY, ...PROTECTED_MANDATORY],
+};
+const VALID_KINDS = new Set(["HEALED", "FAILED", "PROTECTED"]);
+// ─────────────────────────────────────────────────────────────────────────────
+// HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+function throwReport(code, reason, ctx = {}) {
+    throw new SelaError_1.SelaError({ subsystem: "Report", code, reason, context: ctx });
+}
+function isPresent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "string" && value.length === 0)
+        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.
+     */
+    static validateEvent(event) {
+        if (!event || typeof event !== "object") {
+            throwReport(SelaError_1.REPORT_CODES.MALFORMED_EVENT, `Event must be an object, received ${event === null ? "null" : typeof event}`);
+        }
+        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 });
+        }
+        const required = exports.MANDATORY_FIELDS_BY_KIND[ev.kind];
+        for (const field of required) {
+            const val = ev[field];
+            if (!isPresent(val)) {
+                throwReport(SelaError_1.REPORT_CODES.MISSING_FIELD, `${ev.kind} event missing mandatory field "${field}"`, { stableId: ev.stableId, kind: ev.kind, field });
+            }
+        }
+        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 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 aggregate counters. No clock, no IO — trivially pinnable in tests.
+     */
+    static computeStats(events) {
+        let healed = 0, failed = 0, protectedCnt = 0, iframeCnt = 0, shadowCnt = 0;
+        for (const e of events) {
+            if (e.kind === "HEALED")
+                healed++;
+            else if (e.kind === "FAILED")
+                failed++;
+            else if (e.kind === "PROTECTED")
+                protectedCnt++;
+            if (e.inIframe)
+                iframeCnt++;
+            if (e.inShadowDom)
+                shadowCnt++;
+        }
+        const timeSavedMin = healed * exports.TIME_SAVED_CONSTANTS.PER_HEAL +
+            protectedCnt * exports.TIME_SAVED_CONSTANTS.PER_PROTECT +
+            failed * exports.TIME_SAVED_CONSTANTS.PER_FAILED;
+        return {
+            total: events.length,
+            healed,
+            failed,
+            protectedCnt,
+            iframeCnt,
+            shadowCnt,
+            timeSavedMin,
+        };
+    }
+    // ── ROI Metrics ───────────────────────────────────────────────────────────
+    /**
+     * 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,
+            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".
+     */
+    static formatConfidence(value) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return `${Math.max(0, Math.min(100, Math.round(value)))}%`;
+        }
+        return "n/a";
+    }
+}
+exports.ReportGenerator = ReportGenerator;

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

@@ -0,0 +1,112 @@
+import { IntentAuditor } from "./IntentAuditor";
+import { ResolvedThresholds } from "../config/SelaConfig";
+import { VisibilityInfo, AncestorNode, AnchorInfo } from "../types";
+import { SafetyGuardCode } from "../errors/SelaError";
+import { FunctionalRole } from "./safety/roleClassifier";
+export type HealMode = "assertion" | "action";
+export interface HealContext {
+    mode: HealMode;
+    action?: string;
+    /** Current git branch; used for occlusion policy (hard-fail on main). */
+    branch?: string;
+}
+export interface AIFixSummary {
+    /**
+     * 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".
+     */
+    confidence?: number;
+    contentChange?: {
+        oldText: string;
+        newText: string;
+    };
+    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. */
+    dnaBaselineText?: string;
+    /** ARIA role from the DNA snapshot - used by the Intent Auditor. */
+    dnaRole?: string;
+    /** Visibility info captured from the candidate element (new selector). */
+    liveVisibility?: VisibilityInfo;
+    /** Ancestry chain captured from the candidate element at heal-time. */
+    liveAncestry?: AncestorNode[];
+    /** Label/row anchors captured from the candidate element. */
+    liveAnchors?: AnchorInfo;
+    /** Ancestry chain from the DNA snapshot. */
+    dnaAncestry?: AncestorNode[];
+    /** Label/row anchors from the DNA snapshot. */
+    dnaAnchors?: AnchorInfo;
+}
+export type RiskLevel = "SAFE" | "REQUIRES_REVIEW" | "FAIL_HARD" | "BLOCKED";
+/**
+ * Engine-facing action derived from the risk level (decision #1, quarantine):
+ *   - APPLY  : write the heal to source and use it this run    (SAFE)
+ *   - HOLD   : propose the heal but DO NOT write or execute it;
+ *              quarantined for explicit approval               (REQUIRES_REVIEW)
+ *   - REJECT : refuse the heal outright                        (BLOCKED / FAIL_HARD)
+ *
+ * `canProceed` is retained for back-compat (true ⇔ not REJECT); `disposition`
+ * is the three-way signal the engine branches on so that REQUIRES_REVIEW no
+ * longer silently writes to disk.
+ */
+export type SafetyDisposition = "APPLY" | "HOLD" | "REJECT";
+export declare function dispositionFor(level: RiskLevel): SafetyDisposition;
+export interface SafetyDecision {
+    level: RiskLevel;
+    reason: string;
+    canProceed: boolean;
+    /**
+     * Three-way engine action derived from `level`.  Populated centrally by
+     * evaluate(); rules need not set it.  Optional on the type so test
+     * fixtures can build bare decisions, but always present on a value
+     * returned from evaluate().
+     */
+    disposition?: SafetyDisposition;
+    /**
+     * Machine-readable error code from SAFETY_GUARD_CODES.  Always populated
+     * for rejection decisions (BLOCKED / FAIL_HARD) so callers can throw a
+     * SelaError without re-parsing `reason`.  Pass-through decisions (SAFE /
+     * REQUIRES_REVIEW) may omit it.
+     */
+    code?: SafetyGuardCode;
+    /** Structured info for policy-aware log messages in SelaEngine. */
+    meta?: {
+        auditorVerdict?: "CONSISTENT" | "SUSPICIOUS" | "INCONSISTENT";
+        auditorConfidence?: number;
+        /** Score breakdown forwarded from IntentAuditor for engine-level summary logging. */
+        auditScoreBreakdown?: {
+            rawConfidence: number;
+            penalty: number;
+            bonus: number;
+            adjustedConfidence: number;
+        };
+    };
+}
+/**
+ * Constructor options for SafetyGuard.
+ *
+ * - `thresholds`: per-instance threshold overrides (existing behavior).
+ * - `intentAuditor`: pre-built IntentAuditor.  Tests inject a stub so
+ *   SafetyGuard can be unit-tested without an Anthropic key.
+ */
+export interface SafetyGuardOptions {
+    thresholds?: ResolvedThresholds;
+    intentAuditor?: IntentAuditor;
+}
+export declare class SafetyGuard {
+    private intentAuditor;
+    private thresholds;
+    /**
+     * Accepts either the legacy positional `thresholds` argument or an
+     * options bag (DI-friendly).  Existing call sites keep working
+     * unchanged.
+     */
+    constructor(arg?: ResolvedThresholds | SafetyGuardOptions);
+    private static normalizeArgs;
+    evaluate(context: HealContext, aiFix: AIFixSummary): Promise<SafetyDecision>;
+    classifyFunctionalRole(text: string): FunctionalRole;
+}
+//# sourceMappingURL=SafetyGuard.d.ts.map

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

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

package/dist/services/SafetyGuard.js

@@ -0,0 +1,87 @@
+"use strict";
+// src/services/SafetyGuard.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafetyGuard = void 0;
+exports.dispositionFor = dispositionFor;
+const IntentAuditor_1 = require("./IntentAuditor");
+const PipelineContext_1 = require("./safety/PipelineContext");
+const rules_1 = require("./safety/rules");
+const roleClassifier_1 = require("./safety/roleClassifier");
+function dispositionFor(level) {
+    switch (level) {
+        case "SAFE":
+            return "APPLY";
+        case "REQUIRES_REVIEW":
+            return "HOLD";
+        case "BLOCKED":
+        case "FAIL_HARD":
+            return "REJECT";
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// DEFAULT THRESHOLDS  (match pre-config hardcoded values exactly)
+// ═══════════════════════════════════════════════════════════════════
+const DEFAULT_THRESHOLDS = {
+    confidenceHardStop: 85,
+    confidenceReviewThreshold: 95,
+    auditorConfidenceMin: 75,
+    allowSuspicious: false,
+    auditorStrictness: "balanced",
+};
+class SafetyGuard {
+    intentAuditor;
+    thresholds;
+    /**
+     * Accepts either the legacy positional `thresholds` argument or an
+     * options bag (DI-friendly).  Existing call sites keep working
+     * unchanged.
+     */
+    constructor(arg) {
+        const opts = SafetyGuard.normalizeArgs(arg);
+        this.thresholds = opts.thresholds ?? DEFAULT_THRESHOLDS;
+        this.intentAuditor = opts.intentAuditor ?? new IntentAuditor_1.IntentAuditor();
+    }
+    static normalizeArgs(arg) {
+        if (!arg)
+            return {};
+        // Heuristic: an options bag has either `intentAuditor` or a nested
+        // `thresholds` field; otherwise the value itself is a ResolvedThresholds.
+        if ("intentAuditor" in arg || "thresholds" in arg) {
+            return arg;
+        }
+        return { thresholds: arg };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PUBLIC ENTRY POINT
+    //
+    // Builds the shared PipelineContext, then runs the ordered rule
+    // chain.  The first rule to return a SafetyDecision short-circuits;
+    // the terminal ConfidenceTierRule always returns, so the loop never
+    // falls through (the post-loop throw is a defensive invariant guard).
+    // ─────────────────────────────────────────────────────────────
+    async evaluate(context, aiFix) {
+        const ctx = (0, PipelineContext_1.buildContext)(context, aiFix, this.thresholds, this.intentAuditor);
+        for (const rule of rules_1.SAFETY_RULES) {
+            const decision = await rule.run(ctx);
+            if (decision) {
+                // Stamp the engine-facing disposition centrally so every rule's
+                // verdict carries it without each rule having to set it.
+                decision.disposition = dispositionFor(decision.level);
+                return decision;
+            }
+        }
+        // Unreachable: ConfidenceTierRule is terminal and always decides.
+        throw new Error("[SafetyGuard] rule pipeline exhausted without a decision - this is a bug");
+    }
+    // ─────────────────────────────────────────────────────────────
+    // FUNCTIONAL ROLE CLASSIFICATION (public for tests / external use)
+    //
+    // Thin delegate to the extracted pure classifier.  Kept on the class
+    // so existing callers (`new SafetyGuard().classifyFunctionalRole(...)`)
+    // and the adversarial test suite continue to work unchanged.
+    // ─────────────────────────────────────────────────────────────
+    classifyFunctionalRole(text) {
+        return (0, roleClassifier_1.classifyFunctionalRole)(text);
+    }
+}
+exports.SafetyGuard = SafetyGuard;

package/dist/services/Sanitizer.d.ts

@@ -0,0 +1,28 @@
+export interface SanitizeOptions {
+    /**
+     * Mask the `value=` of `<input>` elements whose type is password/tel/email.
+     * Structural (type-driven), so it never touches a button label. Default true.
+     */
+    redactInputValues?: boolean;
+    /** Extra already-compiled patterns, each masked to [REDACTED]. */
+    customPatterns?: RegExp[];
+}
+export declare const REDACTIONS: {
+    readonly EMAIL: "[EMAIL_REDACTED]";
+    readonly CREDIT_CARD: "[CC_REDACTED]";
+    readonly CVV: "[CVV_REDACTED]";
+    readonly PHONE: "[PHONE_REDACTED]";
+    readonly PASSWORD: "[PASSWORD_REDACTED]";
+    readonly BEARER: "[BEARER_REDACTED]";
+    readonly TOKEN: "[TOKEN_REDACTED]";
+    readonly GENERIC: "[REDACTED]";
+};
+/**
+ * Mask PII/secrets in a single string. Pure — returns a new string; the input
+ * is never mutated. Safe to call on already-sanitized text (idempotent on the
+ * placeholders, which contain no maskable patterns).
+ */
+export declare function sanitizeText(input: string, opts?: SanitizeOptions): string;
+/** Compile customPatterns (regex source strings) → RegExp[]; skip invalid. */
+export declare function compileCustomPatterns(sources: string[]): RegExp[];
+//# sourceMappingURL=Sanitizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Sanitizer.d.ts","sourceRoot":"","sources":["../../src/services/Sanitizer.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AA8CX;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,MAAM,CAyC9E;AAsBD,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAYjE"}