@mneme-ai/core 2.61.0 → 2.63.0

package/dist/mirrage/index.js

@@ -0,0 +1,296 @@
+/**
+ * v2.62.0 — MIRRAGE: live conscience for AI agents via MCP reverse-channel.
+ *
+ * User-framing roadmap (set v2.60 → continuing): conscience + memory +
+ * diplomat + bodyguard + time machine. v2.60=bodyguard (SKELETON KEY),
+ * v2.61=diplomat (PASSPORT), v2.62=**conscience** (MIRRAGE).
+ *
+ * Pre-MIRRAGE pattern: AI agent generates draft → user sees draft →
+ * IF user notices factual error → user corrects. Mneme only enters
+ * after user complaint. That's reactive.
+ *
+ * MIRRAGE flips it: BEFORE the agent commits a draft, it calls
+ * `mneme.mirrage.scan {draft}`; Mneme returns per-sentence nudges
+ * graded by 5-level CONSCIENCE LADDER (hint/suggestion/warning/
+ * block/reject) + suggested edit. The agent reads the nudges back
+ * into its own context and self-corrects BEFORE shipping to user.
+ *
+ * The "reverse channel" angle: MCP is normally pull (agent asks
+ * tool). MIRRAGE = push (Mneme injects warnings into agent's
+ * reflection step). One of the few legitimate uses of the MCP
+ * sampling primitive — agent's own model reads Mneme's verdict
+ * inline.
+ *
+ * 5 wild innovations:
+ *
+ *  1. CONSCIENCE LADDER (`conscience_ladder.ts`) — 5 escalation
+ *     tiers (hint/suggestion/warning/block/reject) by risk score.
+ *     Blocking tiers refuse to ship until agent retracts.
+ *
+ *  2. NUDGE-FATIGUE GATING — if the same agent received N similar
+ *     nudges in the last 60min, downgrade priority. Avoid spam.
+ *
+ *  3. CROSS-AGENT WISDOM SHARING — when an agent ACK's a nudge,
+ *     the lesson becomes a candidate broadcast for other agents
+ *     in the project. Wisdom propagates.
+ *
+ *  4. STREAMING PARTIAL SCAN — accept cursor position; only scan
+ *     sentences that ENDED before cursor (in-progress sentence
+ *     skipped). Lets agents call scan continuously while writing.
+ *
+ *  5. HMAC-CHAINED NUDGE LEDGER — every scan + ack chains HMACs.
+ *     Tamper-evident; court-admissible record of what the agent
+ *     was warned about + when.
+ */
+import { createHash, createHmac } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { splitSentences } from "./sentence_splitter.js";
+import { extractFeatures, riskFromFeatures } from "./heuristics.js";
+import { LEVELS, anyBlocks, levelForRisk } from "./conscience_ladder.js";
+const KEY_ENV = "MNEME_MIRRAGE_KEY";
+const DEFAULT_KEY = "mneme-mirrage-v1";
+function keyOf() { return process.env[KEY_ENV] ?? DEFAULT_KEY; }
+/* ── Canonical JSON HMAC (same convention as PASSPORT) ──────────── */
+function canonicalJson(o) {
+    if (o === undefined)
+        return "null";
+    if (o === null || typeof o !== "object")
+        return JSON.stringify(o);
+    if (Array.isArray(o))
+        return "[" + o.map((x) => canonicalJson(x === undefined ? null : x)).join(",") + "]";
+    const entries = Object.entries(o).filter(([, v]) => v !== undefined);
+    entries.sort(([a], [b]) => a.localeCompare(b));
+    return "{" + entries.map(([k, v]) => JSON.stringify(k) + ":" + canonicalJson(v)).join(",") + "}";
+}
+function signHmac(body) {
+    return createHmac("sha256", keyOf()).update(canonicalJson(body)).digest("hex");
+}
+function ledgerPath(cwd) {
+    return join(cwd, ".mneme", "mirrage", "ledger.jsonl");
+}
+function lastLedgerHmac(cwd) {
+    try {
+        const lines = readFileSync(ledgerPath(cwd), "utf8").trim().split(/\n/).filter((l) => l.trim().length > 0);
+        if (lines.length === 0)
+            return "";
+        return JSON.parse(lines[lines.length - 1]).hmac;
+    }
+    catch {
+        return "";
+    }
+}
+function appendLedger(cwd, entry) {
+    const prevHmac = lastLedgerHmac(cwd);
+    const body = { ...entry, prevHmac };
+    const hmac = createHmac("sha256", keyOf()).update(prevHmac).update(canonicalJson(body)).digest("hex");
+    const row = { ...body, hmac };
+    try {
+        mkdirSync(dirname(ledgerPath(cwd)), { recursive: true });
+        appendFileSync(ledgerPath(cwd), JSON.stringify(row) + "\n");
+    }
+    catch { /* noop */ }
+    return row;
+}
+export function readLedger(cwd) {
+    try {
+        return readFileSync(ledgerPath(cwd), "utf8").trim().split(/\n/).filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+export function verifyLedgerChain(cwd) {
+    const lines = readLedger(cwd);
+    let prevHmac = "";
+    for (let i = 0; i < lines.length; i++) {
+        const row = lines[i];
+        if (row.prevHmac !== prevHmac)
+            return { ok: false, rows: i, brokenAt: i };
+        const { hmac, ...body } = row;
+        const expected = createHmac("sha256", keyOf()).update(prevHmac).update(canonicalJson(body)).digest("hex");
+        if (expected !== hmac)
+            return { ok: false, rows: i, brokenAt: i };
+        prevHmac = hmac;
+    }
+    return { ok: true, rows: lines.length };
+}
+/* ── Nudge-fatigue gating ───────────────────────────────────────── */
+function fatiguePath(cwd) {
+    return join(cwd, ".mneme", "mirrage", "fatigue.json");
+}
+function readFatigue(cwd) {
+    try {
+        return JSON.parse(readFileSync(fatiguePath(cwd), "utf8"));
+    }
+    catch {
+        return { records: {} };
+    }
+}
+function writeFatigue(cwd, f) {
+    try {
+        mkdirSync(dirname(fatiguePath(cwd)), { recursive: true });
+        writeFileSync(fatiguePath(cwd), JSON.stringify(f, null, 2));
+    }
+    catch { /* noop */ }
+}
+function sentenceFingerprint(sentence) {
+    // Normalise whitespace + lowercase + hash.
+    const norm = sentence.replace(/\s+/g, " ").trim().toLowerCase();
+    return createHash("sha256").update(norm).digest("hex").slice(0, 16);
+}
+/**
+ * Downgrade priority if the agent recently ACK'd N similar nudges.
+ * Returns a 0..1 multiplier on risk (1.0 = no fatigue; 0.6 = downgraded).
+ */
+function fatigueMultiplier(cwd, agent, fingerprint) {
+    const f = readFatigue(cwd);
+    const key = `${agent}|${fingerprint}`;
+    const rec = f.records[key];
+    if (!rec)
+        return 1.0;
+    const hoursSince = (Date.now() - new Date(rec.lastSeen).getTime()) / (60 * 60 * 1000);
+    if (hoursSince > 1)
+        return 1.0; // fatigue resets after 1 hour
+    // After 3 ACKs in 1 hour → downgrade 40%.
+    return Math.max(0.6, 1.0 - rec.count * 0.13);
+}
+/* ── Cross-agent wisdom broadcast ───────────────────────────────── */
+function wisdomPath(cwd) {
+    return join(cwd, ".mneme", "mirrage", "wisdom_broadcasts.jsonl");
+}
+export function broadcastWisdom(cwd, lesson) {
+    try {
+        mkdirSync(dirname(wisdomPath(cwd)), { recursive: true });
+        appendFileSync(wisdomPath(cwd), JSON.stringify({ ...lesson, at: new Date().toISOString() }) + "\n");
+    }
+    catch { /* noop */ }
+}
+export function readWisdom(cwd) {
+    try {
+        return readFileSync(wisdomPath(cwd), "utf8").trim().split(/\n/).filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/* ── Scan ───────────────────────────────────────────────────────── */
+function suggestedReplacement(sentence, features) {
+    // Simple hedging: if absolutes were the driver, hedge them.
+    let s = sentence;
+    if (features.absolutes > 0) {
+        s = s.replace(/\balways\b/gi, "often")
+            .replace(/\bnever\b/gi, "rarely")
+            .replace(/\ball\b/gi, "many")
+            .replace(/\bevery\b/gi, "many")
+            .replace(/\bdefinitely\b/gi, "likely")
+            .replace(/\bcertainly\b/gi, "likely")
+            .replace(/\babsolutely\b/gi, "likely")
+            .replace(/\bguaranteed\b/gi, "likely")
+            .replace(/\bcannot\b/gi, "may not")
+            .replace(/\bmust\b/gi, "should");
+        if (s !== sentence)
+            return s;
+    }
+    // If entity-driven, the agent should verify — we don't auto-rewrite entities.
+    return undefined;
+}
+export function scanDraft(input) {
+    const at = new Date().toISOString();
+    const cwd = input.cwd ?? process.cwd();
+    const minRisk = input.minRisk ?? 0.30;
+    const t0 = performance.now();
+    const draft = typeof input.draft === "string" ? input.draft : "";
+    const all = splitSentences(draft);
+    // Streaming filter: only sentences ending strictly before cursor.
+    const sentences = typeof input.cursorPos === "number"
+        ? all.filter((s) => s.end <= input.cursorPos)
+        : all;
+    const nudges = [];
+    for (const sent of sentences) {
+        const features = extractFeatures(sent.text);
+        const { risk: rawRisk, drivers } = riskFromFeatures(features);
+        const fp = sentenceFingerprint(sent.text);
+        const mul = input.noFatigueGate ? 1.0 : fatigueMultiplier(cwd, input.agent, fp);
+        const risk = Math.max(0, Math.min(1, rawRisk * mul));
+        const level = levelForRisk(risk);
+        if (!level || risk < minRisk)
+            continue;
+        const suggested = suggestedReplacement(sent.text, features);
+        const meta = LEVELS[level];
+        const nudgeBody = {
+            sentence: sent.text,
+            offset: sent.start,
+            level, symbol: meta.symbol, risk: +risk.toFixed(4),
+            drivers, suggested, blocksShip: meta.blocksShip, features,
+        };
+        nudges.push({
+            ...nudgeBody,
+            id: createHash("sha256").update(`${at}|${sent.start}|${sent.text}`).digest("hex").slice(0, 16),
+            hmac: signHmac(nudgeBody),
+        });
+    }
+    // Compose suggested edit: replace nudge sentences with suggested form or drop.
+    let suggestedEdit = draft;
+    for (const n of nudges.slice().sort((a, b) => b.offset - a.offset)) {
+        const end = n.offset + n.sentence.length;
+        const replacement = n.suggested ?? `[retracted: ${n.symbol} ${n.level}]`;
+        suggestedEdit = suggestedEdit.slice(0, n.offset) + replacement + suggestedEdit.slice(end);
+    }
+    const scanId = createHash("sha256").update(`${at}|${input.agent}|${draft.slice(0, 64)}`).digest("hex").slice(0, 16);
+    const totalLatencyMs = +(performance.now() - t0).toFixed(2);
+    const blocksShip = anyBlocks(nudges.map((n) => n.level));
+    const bodyForHmac = { scanId, at, agent: input.agent, draftLength: draft.length, sentenceCount: sentences.length, nudges, suggestedEdit, blocksShip, totalLatencyMs };
+    const hmac = signHmac(bodyForHmac);
+    if (!input.noLedger)
+        appendLedger(cwd, { kind: "scan", at, scanId, agent: input.agent });
+    return { ...bodyForHmac, hmac };
+}
+export function verifyScanResult(r) {
+    if (!r || typeof r.hmac !== "string")
+        return false;
+    const { hmac, ...body } = r;
+    return signHmac(body) === hmac;
+}
+export function acknowledgeNudge(input) {
+    const cwd = input.cwd ?? process.cwd();
+    // Bump fatigue counter for this (agent, fingerprint) so future scans downgrade.
+    if (input.fingerprint) {
+        const f = readFatigue(cwd);
+        const key = `${input.agent}|${input.fingerprint}`;
+        const rec = f.records[key];
+        f.records[key] = { count: (rec?.count ?? 0) + 1, lastSeen: new Date().toISOString() };
+        writeFatigue(cwd, f);
+    }
+    // Append ledger row.
+    appendLedger(cwd, { kind: "ack", at: new Date().toISOString(), scanId: input.scanId, agent: input.agent, nudgeId: input.nudgeId, level: input.level });
+    // Broadcast wisdom if requested.
+    let broadcast = false;
+    if (input.broadcast && input.sentence && input.level && input.reason) {
+        broadcastWisdom(cwd, { sourceAgent: input.agent, sentence: input.sentence, level: input.level, reason: input.reason });
+        appendLedger(cwd, { kind: "broadcast", at: new Date().toISOString(), scanId: input.scanId, agent: input.agent, nudgeId: input.nudgeId, level: input.level });
+        broadcast = true;
+    }
+    return { ok: true, hint: broadcast ? "acked + wisdom broadcast" : "acked", broadcast };
+}
+/* ── Render ─────────────────────────────────────────────────────── */
+export function renderBanner(r) {
+    const lines = [
+        `🪞 MIRRAGE · ${r.nudges.length} nudge(s) on ${r.sentenceCount} sentence(s) — ${r.totalLatencyMs}ms`,
+        r.blocksShip ? "   🛑 SHIP BLOCKED until retract" : "   ✓ ship allowed",
+        "",
+    ];
+    for (const n of r.nudges) {
+        lines.push(`   ${n.symbol} ${n.level.padEnd(11)} risk=${(n.risk * 100).toFixed(0)}%  ${n.sentence.slice(0, 100)}${n.sentence.length > 100 ? "…" : ""}`);
+        if (n.drivers.length > 0)
+            lines.push(`        ↳ ${n.drivers.join(" · ")}`);
+        if (n.suggested)
+            lines.push(`        ↳ suggested: ${n.suggested.slice(0, 100)}`);
+    }
+    return lines.join("\n");
+}
+/* ── Re-exports ─────────────────────────────────────────────────── */
+export { splitSentences } from "./sentence_splitter.js";
+export { extractFeatures, riskFromFeatures } from "./heuristics.js";
+export { LEVELS, levelForRisk, anyBlocks } from "./conscience_ladder.js";
+//# sourceMappingURL=index.js.map

package/dist/mirrage/index.js.map

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

package/dist/mirrage/sentence_splitter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * v2.62.0 — MIRRAGE sentence splitter.
+ *
+ * Splits a draft into sentence chunks suitable for per-claim ACGV /
+ * heuristic check. Handles:
+ *   - common English abbreviations (Mr., Dr., e.g., i.e., etc.)
+ *   - decimal numbers (3.14)
+ *   - URLs / file paths (https://example.com / src/file.ts)
+ *   - inline code blocks (preserved as single chunk)
+ *
+ * Pure, defensive — never throws.
+ */
+export interface Sentence {
+    /** Original sentence text. */
+    text: string;
+    /** Character offset where the sentence starts in the original draft. */
+    start: number;
+    /** Character offset where the sentence ends (exclusive). */
+    end: number;
+}
+export declare function splitSentences(draft: string): Sentence[];
+//# sourceMappingURL=sentence_splitter.d.ts.map

package/dist/mirrage/sentence_splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentence_splitter.d.ts","sourceRoot":"","sources":["../../src/mirrage/sentence_splitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAwDxD"}

package/dist/mirrage/sentence_splitter.js

@@ -0,0 +1,86 @@
+/**
+ * v2.62.0 — MIRRAGE sentence splitter.
+ *
+ * Splits a draft into sentence chunks suitable for per-claim ACGV /
+ * heuristic check. Handles:
+ *   - common English abbreviations (Mr., Dr., e.g., i.e., etc.)
+ *   - decimal numbers (3.14)
+ *   - URLs / file paths (https://example.com / src/file.ts)
+ *   - inline code blocks (preserved as single chunk)
+ *
+ * Pure, defensive — never throws.
+ */
+const ABBREVIATIONS = new Set([
+    "mr", "mrs", "ms", "dr", "prof", "sr", "jr", "st", "vs", "etc",
+    "e.g", "i.e", "u.s", "u.k", "no", "vol", "fig", "approx", "min", "max",
+    "inc", "ltd", "co", "corp", "esp", "incl", "exc",
+]);
+export function splitSentences(draft) {
+    if (typeof draft !== "string" || draft.length === 0)
+        return [];
+    const out = [];
+    let buf = "";
+    let bufStart = 0;
+    let i = 0;
+    let inCode = false;
+    let inUrl = false;
+    const flush = (offset) => {
+        const trimmed = buf.trim();
+        if (trimmed.length > 0) {
+            out.push({ text: trimmed, start: bufStart + buf.indexOf(trimmed), end: offset });
+        }
+        buf = "";
+        bufStart = offset;
+    };
+    while (i < draft.length) {
+        const ch = draft[i];
+        const next = draft[i + 1] ?? "";
+        // Track inline code blocks (single backtick segments).
+        if (ch === "`") {
+            inCode = !inCode;
+            buf += ch;
+            i++;
+            continue;
+        }
+        if (inCode) {
+            buf += ch;
+            i++;
+            continue;
+        }
+        // Track URLs heuristically: "://" entered, exit on whitespace.
+        if (ch === ":" && draft.slice(i, i + 3) === "://")
+            inUrl = true;
+        if (inUrl && /\s/.test(ch))
+            inUrl = false;
+        if (inUrl) {
+            buf += ch;
+            i++;
+            continue;
+        }
+        // Decimals: digit . digit → keep
+        if (ch === "." && /\d/.test(draft[i - 1] ?? "") && /\d/.test(next)) {
+            buf += ch;
+            i++;
+            continue;
+        }
+        // Abbreviation lookback: split only when next char is space/newline AND
+        // preceding word is NOT a known abbreviation.
+        if ((ch === "." || ch === "!" || ch === "?") && (/\s|$/.test(next) || i === draft.length - 1)) {
+            buf += ch;
+            // Inspect last word before the punctuation.
+            const lastSpace = Math.max(buf.lastIndexOf(" ", buf.length - 2), buf.lastIndexOf("\n", buf.length - 2));
+            const lastWord = buf.slice(lastSpace + 1, buf.length - 1).toLowerCase();
+            if (!ABBREVIATIONS.has(lastWord)) {
+                flush(i + 1);
+                bufStart = i + 1;
+            }
+            i++;
+            continue;
+        }
+        buf += ch;
+        i++;
+    }
+    flush(draft.length);
+    return out;
+}
+//# sourceMappingURL=sentence_splitter.js.map

package/dist/mirrage/sentence_splitter.js.map

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

package/dist/time_crystal/gotcha_detector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * v2.63.0 — TIME-CRYSTAL gotcha detector.
+ *
+ * When an approach has MIXED outcomes (worked for some agents, failed
+ * for others), the failure-environment pattern is signal: there exists
+ * a CONDITION under which the approach breaks. Surface that.
+ *
+ * Algorithm:
+ *  1. For each approach group with ≥1 success AND ≥1 failure,
+ *     compute the env keys / values that appear MORE OFTEN in
+ *     failures than successes (information gain).
+ *  2. Emit gotcha rows: { approach, triggerConditions, severity }.
+ *  3. Also fold any explicit free-text notes that contain "fail" /
+ *     "break" / "ไม่ work" / "พัง" / "doesn't" keywords.
+ */
+import type { WisdomRecord } from "./ranking.js";
+export interface Gotcha {
+    approach: string;
+    /** Env conditions where this approach has elevated failure risk. */
+    triggerConditions: Array<{
+        key: string;
+        value: string;
+        failRateGain: number;
+    }>;
+    /** 0..1 severity score (higher = more reliable failure pattern). */
+    severity: number;
+    /** Free-text notes from contributors. */
+    notes: string[];
+}
+export declare function detectGotchas(records: WisdomRecord[]): Gotcha[];
+//# sourceMappingURL=gotcha_detector.d.ts.map

package/dist/time_crystal/gotcha_detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gotcha_detector.d.ts","sourceRoot":"","sources":["../../src/time_crystal/gotcha_detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,iBAAiB,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CA4D/D"}

package/dist/time_crystal/gotcha_detector.js

@@ -0,0 +1,81 @@
+/**
+ * v2.63.0 — TIME-CRYSTAL gotcha detector.
+ *
+ * When an approach has MIXED outcomes (worked for some agents, failed
+ * for others), the failure-environment pattern is signal: there exists
+ * a CONDITION under which the approach breaks. Surface that.
+ *
+ * Algorithm:
+ *  1. For each approach group with ≥1 success AND ≥1 failure,
+ *     compute the env keys / values that appear MORE OFTEN in
+ *     failures than successes (information gain).
+ *  2. Emit gotcha rows: { approach, triggerConditions, severity }.
+ *  3. Also fold any explicit free-text notes that contain "fail" /
+ *     "break" / "ไม่ work" / "พัง" / "doesn't" keywords.
+ */
+const FAILURE_WORDS = /\b(fail|fails|failed|fails?|break|breaks?|broke|doesn'?t|don'?t work|พัง|ใช้ไม่ได้|ไม่ work)\b/i;
+export function detectGotchas(records) {
+    const byApproach = new Map();
+    for (const r of records) {
+        const k = r.approach.replace(/\s+/g, " ").trim().toLowerCase();
+        const list = byApproach.get(k) ?? [];
+        list.push(r);
+        byApproach.set(k, list);
+    }
+    const gotchas = [];
+    for (const [key, list] of byApproach.entries()) {
+        const successes = list.filter((r) => r.outcome === "success");
+        const failures = list.filter((r) => r.outcome === "failure");
+        if (failures.length === 0)
+            continue; // no signal
+        if (successes.length === 0 && failures.length < 3)
+            continue; // too few to call it a pattern
+        // Compute per-(key,value) failure-rate gain.
+        const envKeys = new Set();
+        for (const r of [...successes, ...failures])
+            for (const k of Object.keys(r.env ?? {}))
+                envKeys.add(k);
+        const triggers = [];
+        for (const k of envKeys) {
+            const valuesSeen = new Set();
+            for (const r of [...successes, ...failures]) {
+                const v = r.env?.[k];
+                if (v)
+                    valuesSeen.add(v);
+            }
+            for (const v of valuesSeen) {
+                const failCountWithV = failures.filter((r) => r.env?.[k] === v).length;
+                const succCountWithV = successes.filter((r) => r.env?.[k] === v).length;
+                const totalWithV = failCountWithV + succCountWithV;
+                if (totalWithV < 2)
+                    continue;
+                const failRate = failCountWithV / totalWithV;
+                const overallFailRate = failures.length / (failures.length + successes.length);
+                const gain = failRate - overallFailRate;
+                if (gain >= 0.30 && failRate >= 0.50) {
+                    triggers.push({ key: k, value: v, failRateGain: +gain.toFixed(3) });
+                }
+            }
+        }
+        // Aggregate explicit notes that look like failure descriptions.
+        const notes = [];
+        for (const r of list) {
+            if (r.note && FAILURE_WORDS.test(r.note)) {
+                const norm = r.note.trim();
+                if (norm.length > 0 && !notes.includes(norm))
+                    notes.push(norm);
+            }
+        }
+        if (triggers.length === 0 && notes.length === 0)
+            continue;
+        const severity = Math.min(1, 0.4 + triggers.length * 0.15 + notes.length * 0.10 + (failures.length / Math.max(1, list.length)) * 0.30);
+        gotchas.push({
+            approach: list[0].approach, // representative casing
+            triggerConditions: triggers.sort((a, b) => b.failRateGain - a.failRateGain).slice(0, 5),
+            severity: +severity.toFixed(3),
+            notes: notes.slice(0, 5),
+        });
+    }
+    return gotchas.sort((a, b) => b.severity - a.severity);
+}
+//# sourceMappingURL=gotcha_detector.js.map

package/dist/time_crystal/gotcha_detector.js.map

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