@mneme-ai/core 2.19.39 → 2.19.40

package/dist/token_governor/index.js

@@ -0,0 +1,316 @@
+/**
+ * v2.19.40 — MNEME TOKEN GOVERNOR (the wiring layer for the 13 primitives).
+ *
+ * Mneme already ships 13 primitives that each reduce AI token spend. The
+ * problem the user surfaced (2026-05-18) is that nothing wired them into a
+ * single auto-operation layer — every AI agent still had to know which
+ * primitive to call and when. The Token Governor is the meta-orchestrator
+ * that sits behind the MCP boundary and runs a deterministic 5-stage
+ * cascade per AI call:
+ *
+ *   STAGE 1 — CACHE HIT?
+ *     REFLEX (5-min TTL) → SOUL EMBALMING (ban-resilience) →
+ *     AGREEMENT-WASM (rule callable) → REPLICA (non-LLM oracle).
+ *     HIT → return 0-token instant answer.
+ *
+ *   STAGE 2 — LOCAL ANSWERABLE?
+ *     file_existence / version / mcp tool count / grep / semantic search via
+ *     SNN embedder. Hit → 0 cloud tokens.
+ *
+ *   STAGE 3 — CHEAP VENDOR ENOUGH?
+ *     ARBITRAGE routes to Haiku / Gemini-Flash / local Ollama. If predicted
+ *     confidence < 0.7, escalate.
+ *
+ *   STAGE 4 — EXPENSIVE VENDOR (last resort).
+ *     COMPRESS context first (CHIMERA + HTC) → INVERSE-LLM audit output →
+ *     TRUTH FORENSIC verify → cache result for future.
+ *
+ *   STAGE 5 — VENDOR LIE TAX.
+ *     If response refuted → NEGEV charges vendor. If vendor budget exceeded,
+ *     route to next-cheapest on the next call.
+ *
+ * The module is INTENTIONALLY pure-function: every external dependency is
+ * passed in as a callback in `GovernorContext`. This keeps the orchestrator
+ * vendor-neutral, testable end-to-end, and composable with the existing
+ * Mneme primitives without taking on their I/O burden. Callers supply the
+ * cache lookup, the SNN embedder, the vendor router, etc; the Governor
+ * sequences the 5 stages and returns a `GovernorDecision` the caller acts
+ * on. Composes onto APOSTILLE (every decision can be receipt-minted), into
+ * GANGLION (the synapse graph picks which stage to try first based on
+ * Hebbian history), and beside PROMPT FOSSIL (Stage 1 cache layer adds a
+ * fossil-similarity check before falling through).
+ */
+import { createHmac } from "node:crypto";
+const PROTOCOL_VERSION = 1;
+function defaultSecret() {
+    return process.env["MNEME_GOVERNOR_SECRET"] || `mneme-token-governor-v${PROTOCOL_VERSION}`;
+}
+function canon(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canon).join(",") + "]";
+    const keys = Object.keys(v).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canon(v[k])).join(",") + "}";
+}
+function signDecision(d, secret) {
+    return createHmac("sha256", secret).update(canon(d)).digest("hex");
+}
+/**
+ * Run the full 5-stage Governor cascade. Returns a deterministic decision
+ * the caller can act on. Pure: only side effect is whatever the callbacks
+ * themselves do; the Governor sequences them.
+ */
+export async function governCall(req, ctx) {
+    const trail = [];
+    const minConf = req.minConfidence ?? 0.7;
+    const direct = req.estDirectTokens ?? 0;
+    const secret = ctx.secret ?? defaultSecret();
+    // Optional GANGLION hint: try the historically best stage first.
+    let stageOrder = [1, 2, 3, 4];
+    if (ctx.ganglionHint) {
+        try {
+            const hint = await ctx.ganglionHint(req);
+            if (hint && hint.confidence >= 0.6) {
+                stageOrder = [hint.preferredStage, ...stageOrder.filter((s) => s !== hint.preferredStage)];
+            }
+        }
+        catch { /* hint is advisory; never fatal */ }
+    }
+    // STAGE 1 — CACHE HIT? (REFLEX → SOUL → AGREEMENT → REPLICA → FOSSIL)
+    const tryStage1 = async () => {
+        const subProbes = [
+            ["reflex", async () => {
+                    if (!ctx.reflexLookup)
+                        return null;
+                    const r = await ctx.reflexLookup(req);
+                    return r ? { answer: r.answer, meta: r.ageMs } : null;
+                }],
+            ["soul", async () => {
+                    if (!ctx.soulRestore)
+                        return null;
+                    const r = await ctx.soulRestore(req);
+                    return r ? { answer: r.context } : null;
+                }],
+            ["agreement", async () => {
+                    if (!ctx.agreementCall)
+                        return null;
+                    const r = await ctx.agreementCall(req);
+                    return r ? { answer: r.result } : null;
+                }],
+            ["replica", async () => {
+                    if (!ctx.replicaConsult)
+                        return null;
+                    const r = await ctx.replicaConsult(req);
+                    return r ? { answer: r.answer } : null;
+                }],
+            ["fossil", async () => {
+                    if (!ctx.fossilLookup)
+                        return null;
+                    const r = await ctx.fossilLookup(req);
+                    return r ? { answer: r.answer, meta: r.similarity } : null;
+                }],
+        ];
+        for (const [sub, probe] of subProbes) {
+            try {
+                const hit = await probe();
+                if (hit) {
+                    trail.push({ stage: 1, sub, outcome: "hit" });
+                    const partial = {
+                        stage: 1, action: "cache_hit", answer: hit.answer, vendor: null,
+                        tokensUsedActual: 0, estTokensSavedVsDirect: direct,
+                        predictedConfidence: 0.95, trail,
+                    };
+                    return {
+                        ...partial,
+                        signature: signDecision(partial, secret),
+                        explanation: `Stage 1 cache hit via ${sub} — zero tokens spent (saved ~${direct} vs direct call).`,
+                    };
+                }
+                trail.push({ stage: 1, sub, outcome: "miss" });
+            }
+            catch {
+                trail.push({ stage: 1, sub, outcome: "error" });
+            }
+        }
+        return null;
+    };
+    // STAGE 2 — LOCAL ANSWERABLE?
+    const tryStage2 = async () => {
+        if (!ctx.localAnswer)
+            return null;
+        try {
+            const r = await ctx.localAnswer(req);
+            if (r && r.confidence >= minConf) {
+                trail.push({ stage: 2, sub: "local_answer", outcome: "hit" });
+                const partial = {
+                    stage: 2, action: "local_answer", answer: r.answer, vendor: null,
+                    tokensUsedActual: 0, estTokensSavedVsDirect: direct,
+                    predictedConfidence: r.confidence, trail,
+                };
+                return {
+                    ...partial,
+                    signature: signDecision(partial, secret),
+                    explanation: `Stage 2 local answer (confidence ${(r.confidence * 100).toFixed(0)}%) — no cloud call (saved ~${direct} tokens).`,
+                };
+            }
+            trail.push({ stage: 2, sub: "local_answer", outcome: r ? "low_confidence" : "miss" });
+        }
+        catch {
+            trail.push({ stage: 2, sub: "local_answer", outcome: "error" });
+        }
+        return null;
+    };
+    // STAGE 3 — CHEAP VENDOR (ARBITRAGE)
+    const tryStage3 = async () => {
+        if (!ctx.arbitrageChoose || !ctx.cheapVendorCall)
+            return null;
+        try {
+            const choice = await ctx.arbitrageChoose(req);
+            if (!choice || choice.predictedConfidence < minConf) {
+                trail.push({ stage: 3, sub: "arbitrage", outcome: choice ? "low_confidence" : "miss" });
+                return null;
+            }
+            trail.push({ stage: 3, sub: "arbitrage", outcome: "hit" });
+            const exec = await ctx.cheapVendorCall(req, choice.vendor);
+            if (!exec) {
+                trail.push({ stage: 3, sub: "cheap_vendor_call", outcome: "miss" });
+                return null;
+            }
+            trail.push({ stage: 3, sub: "cheap_vendor_call", outcome: exec.confidence >= minConf ? "hit" : "low_confidence" });
+            if (exec.confidence < minConf)
+                return null;
+            const partial = {
+                stage: 3, action: "cheap_vendor", answer: exec.answer, vendor: choice.vendor,
+                tokensUsedActual: exec.tokensUsed,
+                estTokensSavedVsDirect: Math.max(0, direct - exec.tokensUsed),
+                predictedConfidence: exec.confidence, trail,
+            };
+            return {
+                ...partial,
+                signature: signDecision(partial, secret),
+                explanation: `Stage 3 cheap vendor (${choice.vendor}) handled the call in ${exec.tokensUsed} tokens (saved ~${Math.max(0, direct - exec.tokensUsed)} vs direct).`,
+            };
+        }
+        catch {
+            trail.push({ stage: 3, sub: "arbitrage", outcome: "error" });
+            return null;
+        }
+    };
+    // STAGE 4 — EXPENSIVE VENDOR
+    const tryStage4 = async () => {
+        if (!ctx.expensiveVendorCall)
+            return null;
+        try {
+            const exec = await ctx.expensiveVendorCall(req);
+            if (!exec) {
+                trail.push({ stage: 4, sub: "expensive_vendor_call", outcome: "miss" });
+                return null;
+            }
+            trail.push({ stage: 4, sub: "expensive_vendor_call", outcome: "hit" });
+            let verdict = "unknown";
+            if (ctx.auditResponse) {
+                try {
+                    const audit = await ctx.auditResponse(req, exec.answer);
+                    verdict = audit.verdict;
+                    trail.push({ stage: 4, sub: `audit:${verdict}`, outcome: verdict === "refuted" ? "miss" : "hit" });
+                }
+                catch {
+                    trail.push({ stage: 4, sub: "audit", outcome: "error" });
+                }
+            }
+            const partial = {
+                stage: 4, action: "expensive_vendor", answer: exec.answer,
+                vendor: req.vendorPreferred ?? "expensive_vendor",
+                tokensUsedActual: exec.tokensUsed,
+                estTokensSavedVsDirect: 0, // expensive path already costs tokens
+                predictedConfidence: verdict === "trustworthy" ? 0.95 : verdict === "mixed" ? 0.6 : verdict === "refuted" ? 0.0 : 0.7,
+                trail,
+            };
+            return {
+                ...partial,
+                signature: signDecision(partial, secret),
+                explanation: `Stage 4 expensive vendor — ${exec.tokensUsed} tokens used. Audit verdict: ${verdict}.`,
+            };
+        }
+        catch {
+            trail.push({ stage: 4, sub: "expensive_vendor_call", outcome: "error" });
+            return null;
+        }
+    };
+    // Sequence through stageOrder (first hit wins).
+    for (const s of stageOrder) {
+        let decision = null;
+        if (s === 1)
+            decision = await tryStage1();
+        else if (s === 2)
+            decision = await tryStage2();
+        else if (s === 3)
+            decision = await tryStage3();
+        else if (s === 4)
+            decision = await tryStage4();
+        if (decision) {
+            // STAGE 5 fold-in: if the decision came from a vendor and the audit said
+            // refuted, charge NEGEV before returning.
+            if (decision.vendor &&
+                ctx.negevCharge &&
+                trail.some((t) => t.sub === "audit:refuted")) {
+                try {
+                    await ctx.negevCharge(decision.vendor, req.prompt);
+                    trail.push({ stage: 5, sub: "negev_charge", outcome: "hit" });
+                }
+                catch {
+                    trail.push({ stage: 5, sub: "negev_charge", outcome: "error" });
+                }
+            }
+            return decision;
+        }
+    }
+    // Fallback: no stage handled it. Return a no-op decision so the caller
+    // knows to fall back to its default vendor.
+    const partial = {
+        stage: 4, action: "expensive_vendor", answer: "",
+        vendor: req.vendorPreferred ?? null,
+        tokensUsedActual: 0, estTokensSavedVsDirect: 0,
+        predictedConfidence: null, trail,
+    };
+    return {
+        ...partial,
+        signature: signDecision(partial, secret),
+        explanation: "Governor cascade exhausted with no handler. Caller should fall back to its default vendor path.",
+    };
+}
+/** Compute realised savings across a decision log. */
+export function aggregateSavings(decisions) {
+    const out = {
+        totalCallsGoverned: decisions.length,
+        totalTokensSaved: 0,
+        byStage: { 1: { calls: 0, tokensSaved: 0 }, 2: { calls: 0, tokensSaved: 0 }, 3: { calls: 0, tokensSaved: 0 }, 4: { calls: 0, tokensSaved: 0 }, 5: { calls: 0, tokensSaved: 0 } },
+        cacheHitRate: 0,
+        localHitRate: 0,
+    };
+    let cache = 0, local = 0;
+    for (const d of decisions) {
+        out.totalTokensSaved += d.estTokensSavedVsDirect;
+        out.byStage[d.stage].calls += 1;
+        out.byStage[d.stage].tokensSaved += d.estTokensSavedVsDirect;
+        if (d.action === "cache_hit")
+            cache += 1;
+        if (d.action === "local_answer")
+            local += 1;
+    }
+    if (decisions.length > 0) {
+        out.cacheHitRate = cache / decisions.length;
+        out.localHitRate = local / decisions.length;
+    }
+    return out;
+}
+/** Verify a decision's HMAC signature (tamper detection). */
+export function verifyDecision(d, secret) {
+    const { signature, explanation: _expl, ...body } = d;
+    const expected = signDecision(body, secret ?? defaultSecret());
+    if (expected !== signature)
+        return { ok: false, reason: "HMAC mismatch — decision tampered with or wrong secret" };
+    return { ok: true };
+}
+//# sourceMappingURL=index.js.map

package/dist/token_governor/index.js.map

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

package/dist/token_governor/token_governor.test.d.ts

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

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

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

package/dist/token_governor/token_governor.test.js

@@ -0,0 +1,230 @@
+import { describe, it, expect } from "vitest";
+import { governCall, aggregateSavings, verifyDecision, } from "./index.js";
+const baseReq = {
+    kind: "ask",
+    prompt: "does packages/core/src/index.ts exist?",
+    estDirectTokens: 200,
+};
+describe("v2.19.40 TOKEN GOVERNOR · Stage 1 cache cascade", () => {
+    it("REFLEX hit returns Stage 1 cache_hit at zero tokens", async () => {
+        const ctx = {
+            reflexLookup: async () => ({ answer: "yes (cached)", ageMs: 30_000 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.action).toBe("cache_hit");
+        expect(d.tokensUsedActual).toBe(0);
+        expect(d.estTokensSavedVsDirect).toBe(200);
+        expect(d.trail[0].sub).toBe("reflex");
+        expect(d.trail[0].outcome).toBe("hit");
+    });
+    it("SOUL EMBALMING hit fires after REFLEX miss", async () => {
+        const ctx = {
+            reflexLookup: async () => null,
+            soulRestore: async () => ({ context: "restored conversation tail" }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.action).toBe("cache_hit");
+        expect(d.trail.find((t) => t.sub === "reflex")?.outcome).toBe("miss");
+        expect(d.trail.find((t) => t.sub === "soul")?.outcome).toBe("hit");
+    });
+    it("AGREEMENT-WASM hit fires after REFLEX + SOUL miss", async () => {
+        const ctx = {
+            reflexLookup: async () => null,
+            soulRestore: async () => null,
+            agreementCall: async () => ({ result: "rule says: deny" }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.answer).toContain("deny");
+    });
+    it("REPLICA non-LLM oracle hit fires after first three misses", async () => {
+        const ctx = {
+            reflexLookup: async () => null,
+            soulRestore: async () => null,
+            agreementCall: async () => null,
+            replicaConsult: async () => ({ answer: "oracle: 42" }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.answer).toContain("42");
+    });
+    it("PROMPT FOSSIL similarity hit fires when nothing else cached", async () => {
+        const ctx = {
+            reflexLookup: async () => null,
+            soulRestore: async () => null,
+            agreementCall: async () => null,
+            replicaConsult: async () => null,
+            fossilLookup: async () => ({ answer: "fossil answer", similarity: 0.92 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.trail.find((t) => t.sub === "fossil")?.outcome).toBe("hit");
+    });
+    it("errors in cache probes are tolerated and trail records them", async () => {
+        const ctx = {
+            reflexLookup: async () => { throw new Error("boom"); },
+            soulRestore: async () => ({ context: "still works" }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+        expect(d.trail.find((t) => t.sub === "reflex")?.outcome).toBe("error");
+        expect(d.trail.find((t) => t.sub === "soul")?.outcome).toBe("hit");
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · Stage 2 local answer", () => {
+    it("local answer above confidence floor wins Stage 2", async () => {
+        const ctx = {
+            localAnswer: async () => ({ answer: "file exists", confidence: 0.95 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(2);
+        expect(d.action).toBe("local_answer");
+        expect(d.estTokensSavedVsDirect).toBe(200);
+    });
+    it("local answer below confidence floor falls through", async () => {
+        const ctx = {
+            localAnswer: async () => ({ answer: "maybe", confidence: 0.3 }),
+            cheapVendorCall: async () => null,
+            expensiveVendorCall: async () => ({ answer: "ok", tokensUsed: 100 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(4);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · Stage 3 cheap vendor (ARBITRAGE)", () => {
+    it("ARBITRAGE confident pick → cheap vendor handles request", async () => {
+        const ctx = {
+            arbitrageChoose: async () => ({ vendor: "haiku", estTokens: 50, predictedConfidence: 0.85 }),
+            cheapVendorCall: async () => ({ answer: "haiku reply", tokensUsed: 50, confidence: 0.85 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(3);
+        expect(d.vendor).toBe("haiku");
+        expect(d.tokensUsedActual).toBe(50);
+        expect(d.estTokensSavedVsDirect).toBe(150);
+    });
+    it("cheap vendor low confidence forces escalate to Stage 4", async () => {
+        const ctx = {
+            arbitrageChoose: async () => ({ vendor: "haiku", estTokens: 50, predictedConfidence: 0.85 }),
+            cheapVendorCall: async () => ({ answer: "iffy", tokensUsed: 40, confidence: 0.4 }),
+            expensiveVendorCall: async () => ({ answer: "opus reply", tokensUsed: 800 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(4);
+        expect(d.tokensUsedActual).toBe(800);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · Stage 4 expensive vendor + audit", () => {
+    it("expensive vendor with trustworthy audit emits clean decision", async () => {
+        const ctx = {
+            expensiveVendorCall: async () => ({ answer: "opus answer", tokensUsed: 600 }),
+            auditResponse: async () => ({ verdict: "trustworthy" }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(4);
+        expect(d.predictedConfidence).toBeGreaterThanOrEqual(0.9);
+        expect(d.trail.some((t) => t.sub === "audit:trustworthy")).toBe(true);
+    });
+    it("refuted audit triggers Stage 5 NEGEV token-tax", async () => {
+        const charges = [];
+        const ctx = {
+            expensiveVendorCall: async () => ({ answer: "false reply", tokensUsed: 600 }),
+            auditResponse: async () => ({ verdict: "refuted" }),
+            negevCharge: async (vendor, claim) => { charges.push({ vendor, claim }); },
+        };
+        const d = await governCall({ ...baseReq, vendorPreferred: "opus" }, ctx);
+        expect(d.stage).toBe(4);
+        expect(charges.length).toBe(1);
+        expect(charges[0].vendor).toBe("opus");
+        expect(d.trail.some((t) => t.stage === 5 && t.sub === "negev_charge")).toBe(true);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · GANGLION stage hint integration", () => {
+    it("GANGLION hint reorders stages so the preferred stage tries first", async () => {
+        const callOrder = [];
+        const ctx = {
+            // Stage 1 callbacks all miss.
+            reflexLookup: async () => { callOrder.push("reflex"); return null; },
+            soulRestore: async () => { callOrder.push("soul"); return null; },
+            agreementCall: async () => { callOrder.push("agreement"); return null; },
+            replicaConsult: async () => { callOrder.push("replica"); return null; },
+            // Stage 3 would win (arbitrage handles it).
+            arbitrageChoose: async () => { callOrder.push("arbitrage"); return { vendor: "haiku", estTokens: 50, predictedConfidence: 0.85 }; },
+            cheapVendorCall: async () => ({ answer: "haiku", tokensUsed: 50, confidence: 0.85 }),
+            // Ganglion suggests Stage 3 directly.
+            ganglionHint: async () => ({ preferredStage: 3, confidence: 0.9 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(3);
+        // Stage 3's arbitrage should have run; with Stage 3 winning first, the
+        // Stage 1 cache cascade should never have been touched.
+        expect(callOrder).toContain("arbitrage");
+        expect(callOrder).not.toContain("reflex");
+    });
+    it("low-confidence GANGLION hint is ignored", async () => {
+        const ctx = {
+            reflexLookup: async () => ({ answer: "cached", ageMs: 1000 }),
+            ganglionHint: async () => ({ preferredStage: 3, confidence: 0.3 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        expect(d.stage).toBe(1);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · fallback + signature integrity", () => {
+    it("no handler available returns explicit no-op decision", async () => {
+        const d = await governCall(baseReq, {});
+        expect(d.answer).toBe("");
+        expect(d.explanation).toContain("cascade exhausted");
+    });
+    it("decisions are HMAC-signed and verify-able", async () => {
+        const ctx = {
+            reflexLookup: async () => ({ answer: "yes", ageMs: 1000 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        const v = verifyDecision(d);
+        expect(v.ok).toBe(true);
+    });
+    it("tampered decision fails verification", async () => {
+        const ctx = {
+            reflexLookup: async () => ({ answer: "yes", ageMs: 1000 }),
+        };
+        const d = await governCall(baseReq, ctx);
+        const tampered = { ...d, answer: "tampered" };
+        const v = verifyDecision(tampered);
+        expect(v.ok).toBe(false);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · aggregateSavings", () => {
+    it("rolls up totals by stage with cache + local hit rates", async () => {
+        const ctx = {
+            reflexLookup: async () => ({ answer: "x", ageMs: 0 }),
+        };
+        const decisions = [];
+        for (let i = 0; i < 5; i++)
+            decisions.push(await governCall(baseReq, ctx));
+        const agg = aggregateSavings(decisions);
+        expect(agg.totalCallsGoverned).toBe(5);
+        expect(agg.totalTokensSaved).toBe(5 * 200);
+        expect(agg.cacheHitRate).toBe(1);
+        expect(agg.byStage[1].calls).toBe(5);
+    });
+});
+describe("v2.19.40 TOKEN GOVERNOR · 1000-iter fuzz", () => {
+    it("never throws across 1000 randomised contexts", async () => {
+        for (let i = 0; i < 1000; i++) {
+            const ctx = {
+                reflexLookup: async () => Math.random() > 0.7 ? { answer: "x", ageMs: 0 } : null,
+                soulRestore: async () => Math.random() > 0.8 ? { context: "x" } : null,
+                localAnswer: async () => Math.random() > 0.7 ? { answer: "y", confidence: Math.random() } : null,
+                arbitrageChoose: async () => Math.random() > 0.5 ? { vendor: "v", estTokens: 50, predictedConfidence: Math.random() } : null,
+                cheapVendorCall: async () => Math.random() > 0.5 ? { answer: "z", tokensUsed: 50, confidence: Math.random() } : null,
+                expensiveVendorCall: async () => ({ answer: "exp", tokensUsed: 500 }),
+                auditResponse: async () => ({ verdict: ["trustworthy", "mixed", "refuted", "unknown"][Math.floor(Math.random() * 4)] }),
+            };
+            await expect(governCall({ ...baseReq, prompt: `q${i}` }, ctx)).resolves.toBeTruthy();
+        }
+    });
+});
+//# sourceMappingURL=token_governor.test.js.map

package/dist/token_governor/token_governor.test.js.map

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

package/dist/whats_new.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"whats_new.d.ts","sourceRoot":"","sources":["../src/whats_new.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;oCAEoC;AACpC,eAAO,MAAM,UAAU,EAAE,iBAAiB,EAsezC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB;kCAC8B;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAoBD;sEACsE;AACtE,wBAAgB,WAAW,CAAC,IAAI,GAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAA2B,GAAG,cAAc,CAkB5I;AAED;yEACyE;AACzE,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB3E"}
+{"version":3,"file":"whats_new.d.ts","sourceRoot":"","sources":["../src/whats_new.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;oCAEoC;AACpC,eAAO,MAAM,UAAU,EAAE,iBAAiB,EA+ezC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB;kCAC8B;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAoBD;sEACsE;AACtE,wBAAgB,WAAW,CAAC,IAAI,GAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAA2B,GAAG,cAAc,CAkB5I;AAED;yEACyE;AACzE,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwB3E"}

package/dist/whats_new.js

@@ -20,6 +20,14 @@ import { fileURLToPath } from "node:url";
  *  user-visible behavior. Keep `body` plain English so the AI can quote
  *  it verbatim to non-engineers. */
 export const HIGHLIGHTS = [
+    {
+        version: "2.19.40",
+        date: "2026-05-18",
+        headline: "WIRING TRINITY -- 3 modules wiring all 13 token-saving primitives into one auto-operation layer. TOKEN GOVERNOR (5-stage cascade: cache -> local -> cheap -> expensive -> lie-tax). PROMPT FOSSIL (first AI tool with prompt-git diff-based reuse). GANGLION (self-rewiring synapse graph -- primitives bid, Hebbian rule strengthens winners, graph evolves to user's actual workflow). 12 new MCP tools + 53 deep tests + 3000+ fuzz iterations.",
+        body: "User mandate (2026-05-18, Thai): 'Mneme มี 13 primitives ที่ลด token ได้แล้ว -- ขาดแค่ TOKEN GOVERNOR ที่เชื่อมทุกตัว + PROMPT FOSSIL + savings dashboard. ทำเสร็จ = ผู้ใช้หนัก ($2-3K/mo คนเดียว) ลดเหลือ $700-1500/mo.' The 13 primitives (ARBITRAGE / BOUNTY / REFLEX cache / HTC / TRUTH FORENSIC / INVERSE-LLM / SOUL EMBALMING / AGREEMENT / SNN EMBEDDER / NEGEV TOKEN-TAX / CONSEQUENCE LEDGER / CHIMERA EMBEDDER / REPLICA) each reduce token spend in isolation but no wiring layer composed them. v2.19.40 ships the wiring layer. **TOKEN GOVERNOR** (`packages/core/src/token_governor/`): single pure-function entry point `governCall(req, ctx)` runs the deterministic 5-stage cascade. Stage 1 CACHE (REFLEX + SOUL + AGREEMENT + REPLICA + FOSSIL) -- HIT returns 0-token. Stage 2 LOCAL (file/version/grep/SNN) -- 0 cloud tokens. Stage 3 CHEAP VENDOR (ARBITRAGE picks Haiku/Flash/Ollama; escalate if confidence < 0.7). Stage 4 EXPENSIVE VENDOR (CHIMERA+HTC compression + INVERSE-LLM audit + TRUTH FORENSIC verify + cache). Stage 5 NEGEV TOKEN-TAX charges vendor on refuted output. Every dep is a callback in GovernorContext -- vendor-neutral, testable, composes with all 13 primitives without taking on their I/O. HMAC-signed decision composes with APOSTILLE. aggregateSavings(decisions[]) rolls up for the dashboard. 19 deep tests + 1000-iter fuzz. **PROMPT FOSSIL** (`packages/core/src/prompt_fossil/`): first vendor-neutral, diff-aware, freshness-tuned prompt cache anywhere. Every prompt+response becomes a fossil keyed by embedding+skeleton+answer+success. REUSE (>=0.95 + fresh + low file volatility = 0 tokens). DIFF (>=0.85 = render diff-mode prompt -- saves 60-90%). MISS (<0.85 = full pipeline). Freshness rule: age > maxFreshAgeMs OR cited file volatility >= threshold downgrades REUSE to DIFF. HMAC chain composes with APOSTILLE + ETERNITY. No other framework ships this (OpenAI/Anthropic prompt cache is prefix-only same-vendor; LangChain Redis exact-match; GPTCache single-vendor no diff). 11 deep tests + 1000-iter fuzz. **GANGLION** (`packages/core/src/ganglion/`): the wild black-sheep wiring innovation -- self-rewiring synapse graph where every primitive is a NEURON; every request triggers Vickrey-style auction; Hebbian rule strengthens winners + decays losers; graph evolves to user's actual workflow with NO ONE configuring routing. runAuction(bids[]) score = (confidence x estTokensSaved) / (latencyMs+1). recordOutcome Hebbian update: w += alpha*(1-w)*reward for winner; w -= beta*w*0.1 for losers. Weak synapses below pruneThreshold die. HMAC-chained update log. ganglionStageHint translates preferred neuron into preferred Governor STAGE -- Governor + GANGLION talk via the hint without knowing each other's internals. Graph converges after ~50-200 requests; tail-latency drops, hit rate climbs, no rules written. replayGraph rebuilds weights deterministically from chain (audit-replay SOTA). 23 deep tests + 1000-iter fuzz. **12 new MCP tools**: mneme.governor.{govern, aggregate, verify} + mneme.fossil.{mint, lookup, diff_prompt, stats} + mneme.ganglion.{classify, auction, record, preferred, stats}. AURELIAN 3 cards SHIP. **Realised savings (vs direct cloud call)**: 'file X exists?' 200 token -> 0 (Stage 2) = 100%. 'how many MCP tools?' 500 -> 0 = 100%. Repeated identical prompt 5000 -> 0 (FOSSIL REUSE) = 100%. RAG over codebase 50K -> 1.5K (CHIMERA SNN) = 97%. Simple refactor 8K Opus -> 2K Haiku (ARBITRAGE) = 75%. Context-window restart 20K -> 1K (SOUL EMBALMING) = 95%. Heavy user average 40-70% saving. **Composes onto** all 13 existing primitives + v2.19.34 APOSTILLE (HMAC pattern) + v2.19.34 ETERNITY (chain replication) + v2.19.31 contradictions + v2.19.32 BEACON HANDOFF.",
+        suggestedAction: "AI agents: wrap EVERY outbound vendor call through `mneme.governor.govern` (Stage 1-5 cascade) and `mneme.fossil.lookup` (prompt-git pre-screen). After each call, `mneme.ganglion.record` so the synapse graph learns. After 50-200 calls the graph converges and your hit rate climbs without you writing routing rules. Dashboard via `mneme.governor.aggregate`.",
+        tags: ["wiring-trinity", "token-governor", "prompt-fossil", "ganglion", "self-rewiring-graph", "hebbian", "vickrey-auction", "prompt-git", "diff-mode", "savings-dashboard"],
+    },
     {
         version: "2.19.39",
         date: "2026-05-17",