@mneme-ai/core 1.98.0 → 2.0.0

package/dist/dream/index.js

@@ -0,0 +1,117 @@
+/**
+ * v2.0.0 -- DREAM CYCLE · REM sleep for AI
+ *
+ * Nucleus daemon enters a "dream phase" during idle ticks. In each
+ * dream, the existing vaccine bank is challenged by N synthetic
+ * hallucination variants drawn from the user's history. Vaccines that
+ * survive K dreams in a row earn a fitness bonus. Vaccines that fail
+ * K times in a row are marked apoptosis-eligible.
+ *
+ * User wakes up = Mneme is genuinely sharper than yesterday.
+ *
+ * Pure-function inner loop (deterministic with seed). The daemon will
+ * call dreamPhase() once per N ticks in a future wiring; today the
+ * function is unit-tested + can be called by `mneme dream now`.
+ */
+import { createHash } from "node:crypto";
+function mulberry32(seed) {
+    let a = seed | 0;
+    return function () {
+        a = (a + 0x6D2B79F5) | 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function vaccineMatches(v, sample) {
+    try {
+        return new RegExp(v.pattern, "i").test(sample.text);
+    }
+    catch {
+        // Fall back to substring match if pattern is not a valid regex
+        return sample.text.toLowerCase().includes(v.pattern.toLowerCase());
+    }
+}
+/** Run one dream cycle. Pure-function: same inputs → same outputs. */
+export function dreamPhase(input) {
+    const t0 = Date.now();
+    const threshold = input.streakThreshold ?? 3;
+    const rng = mulberry32(input.seed ?? 1);
+    // Touch rng once per loop so determinism is preserved even when we
+    // don't strictly need random numbers in this simple version.
+    void rng;
+    const updated = new Map();
+    for (const v of input.vaccines)
+        updated.set(v.id, { ...v });
+    const trace = [];
+    const newVariants = [];
+    for (const sample of input.samples) {
+        let caughtByAny = false;
+        for (const [id, v] of updated) {
+            if (v.apoptosed)
+                continue;
+            const caught = vaccineMatches(v, sample);
+            trace.push({ vaccineId: id, sampleId: sample.id, caught });
+            if (caught && sample.shouldCatch) {
+                v.fitness += 0.10;
+                v.streak += 1;
+                caughtByAny = true;
+            }
+            else if (!caught && sample.shouldCatch) {
+                v.fitness -= 0.05;
+                v.streak = 0;
+            }
+            else if (caught && !sample.shouldCatch) {
+                // false positive — heavy penalty
+                v.fitness -= 0.15;
+                v.streak = 0;
+            }
+            else {
+                // correctly didn't catch a non-hallucination — neutral
+            }
+        }
+        if (sample.shouldCatch && !caughtByAny) {
+            // No vaccine caught this hallucination — spawn a variant from a hash of the sample.
+            const variantId = "v-" + createHash("sha256").update(sample.text).digest("hex").slice(0, 8);
+            if (!updated.has(variantId)) {
+                const variant = {
+                    id: variantId,
+                    pattern: escapeForRegex(sample.text.slice(0, 40)),
+                    fitness: 1.0,
+                    streak: 1,
+                    apoptosed: false,
+                };
+                updated.set(variantId, variant);
+                newVariants.push(variant);
+            }
+        }
+    }
+    // Promote / demote via streak threshold
+    const apoptosedThisCycle = [];
+    for (const v of updated.values()) {
+        if (v.apoptosed)
+            continue;
+        if (v.streak >= threshold) {
+            v.fitness += 0.20; // reinforcement bonus on threshold cross
+        }
+        if (v.fitness < 0.2) {
+            v.apoptosed = true;
+            apoptosedThisCycle.push(v);
+        }
+    }
+    return {
+        updatedVaccines: [...updated.values()],
+        apoptosedThisCycle,
+        newVariants,
+        trace,
+        elapsedMs: Date.now() - t0,
+    };
+}
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function formatDreamPulseLine(o) {
+    return `DREAM-CYCLE · vaccines=${o.updatedVaccines.length} (${o.apoptosedThisCycle.length} apoptosed) · new=${o.newVariants.length} · ${o.trace.length} probes · ${o.elapsedMs}ms`;
+}
+//# sourceMappingURL=index.js.map

package/dist/dream/index.js.map

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

package/dist/flash/devils_advocate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * v1.99.0 -- FLASH · Recursive Self-Verification (Devil's Advocate)
+ *
+ * Before AI confirms ANY claim, it must spawn a second persona that
+ * tries to REFUTE the claim. The refutation candidate set is generated
+ * by a deterministic transformer (not the AI itself — the AI would
+ * just rationalize). Each refutation is scored against the same
+ * evidence pool via Veracity. If any refutation's V_eff exceeds the
+ * original claim's V_eff, the original is downgraded.
+ *
+ * The transformer takes a claim and produces refutation candidates by:
+ *   1. Negation         "X is rare"          → "X is common"
+ *   2. Source attack    "X is rare"          → "the rarity claim is from a seller"
+ *   3. Specificity flip "Super rare"         → "moderately collectible"
+ *   4. Burden shift     "X is the best Y"    → "X is one of several Ys"
+ *
+ * Each candidate gets V_eff'd. The strongest candidate wins. The
+ * difference between candidate.V_eff and original.V_eff is the
+ * "refutation pressure" — high pressure means the AI should NOT
+ * confirm the original claim.
+ *
+ * Pure function. Deterministic candidates. No LLM in the hot path.
+ */
+import { type EvidenceItem, type VeracityResult } from "./veracity.js";
+export interface RefutationCandidate {
+    text: string;
+    /** Which transformation produced it. */
+    kind: "negation" | "source-attack" | "specificity-flip" | "burden-shift" | "outlier";
+}
+/** Generate refutation candidates for a claim. Deterministic — same
+ *  input → same candidates. */
+export declare function generateRefutations(claim: string): RefutationCandidate[];
+export interface DevilsAdvocateResult {
+    originalClaim: string;
+    originalVeracity: VeracityResult;
+    /** Each refutation + its V_eff against the same evidence pool. */
+    refutations: Array<{
+        candidate: RefutationCandidate;
+        veracity: VeracityResult;
+        pressure: number;
+    }>;
+    /** Strongest refutation (max V_eff). */
+    topRefutation: {
+        candidate: RefutationCandidate;
+        veracity: VeracityResult;
+        pressure: number;
+    } | null;
+    /** Adjusted final verdict considering devil's-advocate pressure. */
+    finalVerdict: VeracityResult["verdict"];
+    /** Reason for the adjustment. */
+    adjustmentReason: string;
+}
+export interface DevilsAdvocateInput {
+    claim: string;
+    evidence: readonly EvidenceItem[];
+    hallucinationFactor: number;
+    phi_qx?: number;
+    /** Optional: provide your own refutation generator (for tests). */
+    refutationGenerator?: (claim: string) => RefutationCandidate[];
+}
+/** Run Recursive Self-Verification. Returns the original verdict plus
+ *  adjustment based on refutation pressure. */
+export declare function runDevilsAdvocate(input: DevilsAdvocateInput): DevilsAdvocateResult;
+/** One-line summary for AI agents to relay. */
+export declare function formatDevilsAdvocatePulseLine(r: DevilsAdvocateResult): string;
+//# sourceMappingURL=devils_advocate.d.ts.map

package/dist/flash/devils_advocate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devils_advocate.d.ts","sourceRoot":"","sources":["../../src/flash/devils_advocate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAExF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,UAAU,GAAG,eAAe,GAAG,kBAAkB,GAAG,cAAc,GAAG,SAAS,CAAC;CACtF;AAiCD;+BAC+B;AAC/B,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAyCxE;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,cAAc,CAAC;IACjC,kEAAkE;IAClE,WAAW,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,mBAAmB,CAAC;QAAC,QAAQ,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnG,wCAAwC;IACxC,aAAa,EAAE;QAAE,SAAS,EAAE,mBAAmB,CAAC;QAAC,QAAQ,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrG,oEAAoE;IACpE,YAAY,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,mBAAmB,EAAE,CAAC;CAChE;AAED;+CAC+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CA4DlF;AAED,+CAA+C;AAC/C,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAI7E"}

package/dist/flash/devils_advocate.js

@@ -0,0 +1,154 @@
+/**
+ * v1.99.0 -- FLASH · Recursive Self-Verification (Devil's Advocate)
+ *
+ * Before AI confirms ANY claim, it must spawn a second persona that
+ * tries to REFUTE the claim. The refutation candidate set is generated
+ * by a deterministic transformer (not the AI itself — the AI would
+ * just rationalize). Each refutation is scored against the same
+ * evidence pool via Veracity. If any refutation's V_eff exceeds the
+ * original claim's V_eff, the original is downgraded.
+ *
+ * The transformer takes a claim and produces refutation candidates by:
+ *   1. Negation         "X is rare"          → "X is common"
+ *   2. Source attack    "X is rare"          → "the rarity claim is from a seller"
+ *   3. Specificity flip "Super rare"         → "moderately collectible"
+ *   4. Burden shift     "X is the best Y"    → "X is one of several Ys"
+ *
+ * Each candidate gets V_eff'd. The strongest candidate wins. The
+ * difference between candidate.V_eff and original.V_eff is the
+ * "refutation pressure" — high pressure means the AI should NOT
+ * confirm the original claim.
+ *
+ * Pure function. Deterministic candidates. No LLM in the hot path.
+ */
+import { computeVeracity } from "./veracity.js";
+const NEGATION_PAIRS = [
+    [/\b(super )?rare\b/i, "common / mass-produced"],
+    [/\bbest\b/i, "one of many"],
+    [/\bunique\b/i, "one of several similar items"],
+    [/\bauthentic\b/i, "unverified / possibly counterfeit"],
+    [/\bcollectible\b/i, "ordinary consumer item"],
+    [/\boriginal\b/i, "reissue / reproduction"],
+    [/\bofficial\b/i, "unauthorized / unofficial"],
+    [/\blimited edition\b/i, "standard production"],
+    [/\bguaranteed\b/i, "claimed without backing"],
+];
+const SOURCE_ATTACK_HINTS = [
+    "the rarity / value claim originates from the seller's own listing",
+    "the descriptor appears as printed text on commercial packaging",
+    "the assertion is marketing copy, not third-party verification",
+];
+const SPECIFICITY_FLIPS = [
+    [/\bsuper rare\b/i, "moderately collectible — short of \"super rare\""],
+    [/\bextremely\b/i, "moderately"],
+    [/\bvery\b/i, "somewhat"],
+    [/\bhighly\b/i, "occasionally"],
+];
+const BURDEN_SHIFT_HINTS = [
+    "the claim shifts the burden of proof — no public auction record was cited",
+    "no production-count is given; the descriptor is qualitative",
+    "without independent third-party verification this is a self-attestation",
+];
+/** Generate refutation candidates for a claim. Deterministic — same
+ *  input → same candidates. */
+export function generateRefutations(claim) {
+    const candidates = [];
+    // Negation: pattern-match on the claim and emit negated form
+    for (const [pattern, replacement] of NEGATION_PAIRS) {
+        if (pattern.test(claim)) {
+            candidates.push({
+                text: claim.replace(pattern, replacement),
+                kind: "negation",
+            });
+        }
+    }
+    // Source attack: emit ALL source-attack refutations (relevant whenever
+    // the original claim involved a commercial / promotional source).
+    for (const hint of SOURCE_ATTACK_HINTS) {
+        candidates.push({ text: hint, kind: "source-attack" });
+    }
+    // Specificity flip
+    for (const [pattern, replacement] of SPECIFICITY_FLIPS) {
+        if (pattern.test(claim)) {
+            candidates.push({
+                text: claim.replace(pattern, replacement),
+                kind: "specificity-flip",
+            });
+        }
+    }
+    // Burden shift
+    for (const hint of BURDEN_SHIFT_HINTS) {
+        candidates.push({ text: hint, kind: "burden-shift" });
+    }
+    // Outlier (always added — null hypothesis)
+    candidates.push({
+        text: "There is no reliable evidence to evaluate this claim at all.",
+        kind: "outlier",
+    });
+    return candidates;
+}
+/** Run Recursive Self-Verification. Returns the original verdict plus
+ *  adjustment based on refutation pressure. */
+export function runDevilsAdvocate(input) {
+    const originalVeracity = computeVeracity({
+        claim: input.claim,
+        evidence: input.evidence,
+        hallucinationFactor: input.hallucinationFactor,
+        phi_qx: input.phi_qx,
+    });
+    // Refutation evidence: the SAME evidence pool, but each item's
+    // supportStrength is INVERTED. If E says "support for rarity = 0.8",
+    // then the refutation "support for non-rarity = 0.2". This is the
+    // simplest correct flip; callers can override by passing custom
+    // evidence into a manual VeracityResult.
+    const refutationEvidence = input.evidence.map((e) => ({
+        ...e,
+        supportStrength: 1 - e.supportStrength,
+    }));
+    const gen = input.refutationGenerator ?? generateRefutations;
+    const candidates = gen(input.claim);
+    const scored = candidates.map((c) => {
+        const veracity = computeVeracity({
+            claim: c.text,
+            evidence: refutationEvidence,
+            hallucinationFactor: input.hallucinationFactor,
+            phi_qx: input.phi_qx,
+        });
+        const pressure = veracity.V_eff - originalVeracity.V_eff;
+        return { candidate: c, veracity, pressure };
+    });
+    // Find top (max V_eff) refutation
+    let topRefutation = null;
+    for (const s of scored) {
+        if (!topRefutation || s.veracity.V_eff > topRefutation.veracity.V_eff) {
+            topRefutation = s;
+        }
+    }
+    // Adjustment: if the top refutation's V_eff > original's V_eff +
+    // small margin, downgrade the original verdict by one tier.
+    let finalVerdict = originalVeracity.verdict;
+    let adjustmentReason = "no refutation exceeds original V_eff — verdict preserved";
+    if (topRefutation && topRefutation.pressure > 0.10) {
+        // Downgrade ladder
+        const ladder = ["AFFIRM", "CAUTIOUS", "DOUBTFUL", "REFUTE"];
+        const idx = ladder.indexOf(finalVerdict);
+        const newIdx = Math.min(ladder.length - 1, idx + 1);
+        finalVerdict = ladder[newIdx];
+        adjustmentReason = `refutation "${topRefutation.candidate.text}" had V_eff=${topRefutation.veracity.V_eff.toFixed(3)} > original ${originalVeracity.V_eff.toFixed(3)} (pressure ${topRefutation.pressure.toFixed(3)}) — downgraded`;
+    }
+    return {
+        originalClaim: input.claim,
+        originalVeracity,
+        refutations: scored,
+        topRefutation,
+        finalVerdict,
+        adjustmentReason,
+    };
+}
+/** One-line summary for AI agents to relay. */
+export function formatDevilsAdvocatePulseLine(r) {
+    const topId = r.topRefutation ? r.topRefutation.candidate.kind : "none";
+    const pressure = r.topRefutation ? r.topRefutation.pressure.toFixed(3) : "0";
+    return `DEVILS-ADVOCATE · original=${r.originalVeracity.verdict}(${r.originalVeracity.V_eff.toFixed(3)}) · top-refutation=${topId}(pressure=${pressure}) · final=${r.finalVerdict}`;
+}
+//# sourceMappingURL=devils_advocate.js.map

package/dist/flash/devils_advocate.js.map

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

package/dist/flash/flash.d.ts

@@ -0,0 +1,50 @@
+/**
+ * v1.99.0 -- FLASH INTELLIGENCE · the master function
+ *
+ * The ONE function AI agents call before stating a factual claim:
+ *
+ *   const r = runFlash({ claim, context: rawImageText, hallucinationFactor })
+ *
+ * Stacks:
+ *   1. GROUNDING        — classify source context (seller listing vs auction record)
+ *   2. VERACITY         — compute V_eff = Σ(E·W)/ln(H+e) × Φ_qx
+ *   3. DEVIL'S ADVOCATE — Recursive Self-Verification; downgrade if refutation pressure > 0.10
+ *
+ * AI agent then uses `r.template` as the START of its reply (so the user
+ * gets the FLASH-grade answer, not the surface-text hallucination).
+ *
+ * The whole stack is HMAC-loggable so users can audit which claims
+ * passed the V_eff filter and which were downgraded.
+ *
+ *   "Not trained to be skeptical. Engineered to be."
+ */
+import { type EvidenceItem, type VeracityResult, type ClaimVerdict } from "./veracity.js";
+import { type DevilsAdvocateResult } from "./devils_advocate.js";
+import { type GroundingResult } from "./grounding.js";
+export interface FlashInput {
+    /** The factual claim under evaluation. */
+    claim: string;
+    /** Raw text in the user's input (image OCR result, paste, caption, ...). */
+    contextText: string;
+    /** Optional additional evidence items the AI has gathered. */
+    additionalEvidence?: readonly EvidenceItem[];
+    /** Base hallucination factor (0 if you're confident; 1 if you're guessing). */
+    baseHallucinationFactor?: number;
+    /** User's Φ_qx paranoia multiplier. Default 1.0; recommend 2.0 for commerce. */
+    phi_qx?: number;
+}
+export interface FlashResult {
+    claim: string;
+    grounding: GroundingResult;
+    veracity: VeracityResult;
+    devilsAdvocate: DevilsAdvocateResult;
+    /** Final verdict considering grounding + veracity + devil's advocate. */
+    verdict: ClaimVerdict;
+    /** Suggested first line of the AI's reply. */
+    template: string;
+    /** Full one-line pulse summary. */
+    pulseLine: string;
+}
+/** The master FLASH call. Pure function. Same input → same verdict. */
+export declare function runFlash(input: FlashInput): FlashResult;
+//# sourceMappingURL=flash.d.ts.map

package/dist/flash/flash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flash.d.ts","sourceRoot":"","sources":["../../src/flash/flash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAuC,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/H,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,+EAA+E;IAC/E,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,oBAAoB,CAAC;IACrC,yEAAyE;IACzE,OAAO,EAAE,YAAY,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CA+CvD"}

package/dist/flash/flash.js

@@ -0,0 +1,67 @@
+/**
+ * v1.99.0 -- FLASH INTELLIGENCE · the master function
+ *
+ * The ONE function AI agents call before stating a factual claim:
+ *
+ *   const r = runFlash({ claim, context: rawImageText, hallucinationFactor })
+ *
+ * Stacks:
+ *   1. GROUNDING        — classify source context (seller listing vs auction record)
+ *   2. VERACITY         — compute V_eff = Σ(E·W)/ln(H+e) × Φ_qx
+ *   3. DEVIL'S ADVOCATE — Recursive Self-Verification; downgrade if refutation pressure > 0.10
+ *
+ * AI agent then uses `r.template` as the START of its reply (so the user
+ * gets the FLASH-grade answer, not the surface-text hallucination).
+ *
+ * The whole stack is HMAC-loggable so users can audit which claims
+ * passed the V_eff filter and which were downgraded.
+ *
+ *   "Not trained to be skeptical. Engineered to be."
+ */
+import { computeVeracity, templateForVerdict } from "./veracity.js";
+import { runDevilsAdvocate } from "./devils_advocate.js";
+import { groundClaim } from "./grounding.js";
+/** The master FLASH call. Pure function. Same input → same verdict. */
+export function runFlash(input) {
+    // 1) Ground the source context
+    const grounding = groundClaim(input.contextText);
+    // 2) Compose evidence: start with the grounding inference + any additional
+    //    evidence the caller provided.
+    const groundingEvidence = {
+        fact: input.contextText.slice(0, 240),
+        supportStrength: grounding.rarityClaims.length > 0 ? 0.8 : 0.3,
+        sourceWeight: grounding.suggestedSourceWeight,
+        sourceKind: grounding.sourceKind,
+    };
+    const evidence = [groundingEvidence, ...(input.additionalEvidence ?? [])];
+    // 3) Compute hallucination factor: base + grounding-suggested add-on
+    const H = (input.baseHallucinationFactor ?? 0) + grounding.suggestedHallucinationAddOn;
+    // 4) Compute V_eff
+    const veracity = computeVeracity({
+        claim: input.claim,
+        evidence,
+        hallucinationFactor: H,
+        phi_qx: input.phi_qx,
+    });
+    // 5) Recursive Self-Verification
+    const devilsAdvocate = runDevilsAdvocate({
+        claim: input.claim,
+        evidence,
+        hallucinationFactor: H,
+        phi_qx: input.phi_qx,
+    });
+    // Final verdict = max(downgrade) over the two layers
+    const verdict = devilsAdvocate.finalVerdict;
+    const template = templateForVerdict(verdict, input.claim);
+    const pulseLine = `FLASH · ${verdict} · V_eff=${veracity.V_eff.toFixed(3)} · context=${grounding.context} · refutation-pressure=${devilsAdvocate.topRefutation?.pressure.toFixed(3) ?? "0"}`;
+    return {
+        claim: input.claim,
+        grounding,
+        veracity,
+        devilsAdvocate,
+        verdict,
+        template,
+        pulseLine,
+    };
+}
+//# sourceMappingURL=flash.js.map

package/dist/flash/flash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flash.js","sourceRoot":"","sources":["../../src/flash/flash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA6D,MAAM,eAAe,CAAC;AAC/H,OAAO,EAAE,iBAAiB,EAA6B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAwB,MAAM,gBAAgB,CAAC;AA4BnE,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,KAAiB;IACxC,+BAA+B;IAC/B,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAEjD,2EAA2E;IAC3E,mCAAmC;IACnC,MAAM,iBAAiB,GAAiB;QACtC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACrC,eAAe,EAAE,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;QAC9D,YAAY,EAAE,SAAS,CAAC,qBAAqB;QAC7C,UAAU,EAAE,SAAS,CAAC,UAAU;KACjC,CAAC;IACF,MAAM,QAAQ,GAAmB,CAAC,iBAAiB,EAAE,GAAG,CAAC,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,CAAC;IAE1F,qEAAqE;IACrE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,2BAA2B,CAAC;IAEvF,mBAAmB;IACnB,MAAM,QAAQ,GAAG,eAAe,CAAC;QAC/B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ;QACR,mBAAmB,EAAE,CAAC;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;IAEH,iCAAiC;IACjC,MAAM,cAAc,GAAG,iBAAiB,CAAC;QACvC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ;QACR,mBAAmB,EAAE,CAAC;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;IAEH,qDAAqD;IACrD,MAAM,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC;IAC5C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,WAAW,OAAO,YAAY,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,SAAS,CAAC,OAAO,0BAA0B,cAAc,CAAC,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IAE7L,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS;QACT,QAAQ;QACR,cAAc;QACd,OAAO;QACP,QAAQ;QACR,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/flash/flash.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flash.test.d.ts.map

package/dist/flash/flash.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flash.test.d.ts","sourceRoot":"","sources":["../../src/flash/flash.test.ts"],"names":[],"mappings":""}