@mneme-ai/core 2.19.41 → 2.19.43

package/dist/mneme_version.d.ts

@@ -1,15 +1,26 @@
 /**
  * Resolve the running Mneme version from disk (package.json), with the
  * env-var as a secondary source. NEVER falls back to a hard-coded
- * string -- those bit-rot the moment a new version ships (root cause
- * of bug #5: MCP server reporting "1.27.9" while CLI shows "1.43.0").
+ * string -- those bit-rot the moment a new version ships.
  *
- * Lookup order:
+ * Bug history:
+ *   - v1.43 bug #5: MCP server reporting "1.27.9" while CLI shows "1.43.0"
+ *     (fixed by walking up for @mneme-ai/core package.json).
+ *   - v2.19.41 N4: `mneme system upgrade --json '{"mode":"check"}'`
+ *     reported current=0.0.0 because env was empty AND resolver only
+ *     accepted @mneme-ai/core name. When MCP server runs from npm-global
+ *     install, packages/mcp is a sibling of core under node_modules, not
+ *     a parent -- walking up never found a "@mneme-ai/core" package.json.
+ *
+ * v2.19.43 lookup order (robust against npm-global install where sibling
+ * packages don't have core as a parent):
  *   1. process.env.npm_package_version (set when launched via `npm run`)
- *   2. Walk up from this module's directory looking for `package.json`
- *      with `"name": "@mneme-ai/core"`. That's the source of truth.
- *   3. Final fallback: literal string "0.0.0-unknown" -- chosen so it's
- *      OBVIOUSLY wrong when surfaced, instead of silently outdated.
+ *   2. Walk up from this module's directory for ANY package.json whose
+ *      name matches the Mneme family (@mneme-ai/{core,mcp,cli,embeddings,
+ *      correlator}, or the umbrella mneme-ai). All 5 ship lock-step.
+ *   3. Walk up for any package.json with a Mneme-shaped name (covers
+ *      future families we add).
+ *   4. Final fallback: literal "0.0.0-unknown" so the bad value is OBVIOUS.
  */
 export declare function resolveMnemeVersion(): string;
 /** For tests: clear the memoized value so a re-read happens. */

package/dist/mneme_version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mneme_version.d.ts","sourceRoot":"","sources":["../src/mneme_version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,wBAAgB,mBAAmB,IAAI,MAAM,CA0B5C;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,IAAI,IAAI,CAAmB"}
+{"version":3,"file":"mneme_version.d.ts","sourceRoot":"","sources":["../src/mneme_version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAoCH,wBAAgB,mBAAmB,IAAI,MAAM,CAwB5C;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,IAAI,IAAI,CAAmB"}

package/dist/mneme_version.js

@@ -1,44 +1,82 @@
 /**
  * Resolve the running Mneme version from disk (package.json), with the
  * env-var as a secondary source. NEVER falls back to a hard-coded
- * string -- those bit-rot the moment a new version ships (root cause
- * of bug #5: MCP server reporting "1.27.9" while CLI shows "1.43.0").
+ * string -- those bit-rot the moment a new version ships.
  *
- * Lookup order:
+ * Bug history:
+ *   - v1.43 bug #5: MCP server reporting "1.27.9" while CLI shows "1.43.0"
+ *     (fixed by walking up for @mneme-ai/core package.json).
+ *   - v2.19.41 N4: `mneme system upgrade --json '{"mode":"check"}'`
+ *     reported current=0.0.0 because env was empty AND resolver only
+ *     accepted @mneme-ai/core name. When MCP server runs from npm-global
+ *     install, packages/mcp is a sibling of core under node_modules, not
+ *     a parent -- walking up never found a "@mneme-ai/core" package.json.
+ *
+ * v2.19.43 lookup order (robust against npm-global install where sibling
+ * packages don't have core as a parent):
  *   1. process.env.npm_package_version (set when launched via `npm run`)
- *   2. Walk up from this module's directory looking for `package.json`
- *      with `"name": "@mneme-ai/core"`. That's the source of truth.
- *   3. Final fallback: literal string "0.0.0-unknown" -- chosen so it's
- *      OBVIOUSLY wrong when surfaced, instead of silently outdated.
+ *   2. Walk up from this module's directory for ANY package.json whose
+ *      name matches the Mneme family (@mneme-ai/{core,mcp,cli,embeddings,
+ *      correlator}, or the umbrella mneme-ai). All 5 ship lock-step.
+ *   3. Walk up for any package.json with a Mneme-shaped name (covers
+ *      future families we add).
+ *   4. Final fallback: literal "0.0.0-unknown" so the bad value is OBVIOUS.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 let cached = null;
+const MNEME_FAMILY = new Set([
+    "@mneme-ai/core",
+    "@mneme-ai/mcp",
+    "@mneme-ai/cli",
+    "@mneme-ai/embeddings",
+    "@mneme-ai/correlator",
+    "mneme-ai",
+]);
+function walkUpForPackageJson(startDir, accept) {
+    let dir = startDir;
+    for (let i = 0; i < 12; i++) {
+        const pkg = join(dir, "package.json");
+        if (existsSync(pkg)) {
+            try {
+                const parsed = JSON.parse(readFileSync(pkg, "utf8"));
+                if (typeof parsed.version === "string" && /^\d+\.\d+\.\d+/.test(parsed.version) && accept(parsed.name)) {
+                    return parsed.version;
+                }
+            }
+            catch { /* keep walking */ }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
 export function resolveMnemeVersion() {
     if (cached)
         return cached;
+    // 1) env var (npm run only)
     const env = process.env["npm_package_version"];
     if (env && /^\d+\.\d+\.\d+/.test(env)) {
         cached = env;
         return env;
     }
+    // 2) walk up for ANY Mneme-family package.json
     try {
         const here = fileURLToPath(import.meta.url);
-        let dir = dirname(here);
-        for (let i = 0; i < 10; i++) {
-            const pkg = join(dir, "package.json");
-            if (existsSync(pkg)) {
-                const parsed = JSON.parse(readFileSync(pkg, "utf8"));
-                if (parsed.name === "@mneme-ai/core" && typeof parsed.version === "string") {
-                    cached = parsed.version;
-                    return parsed.version;
-                }
-            }
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
+        const startDir = dirname(here);
+        const familyHit = walkUpForPackageJson(startDir, (name) => !!name && MNEME_FAMILY.has(name));
+        if (familyHit) {
+            cached = familyHit;
+            return familyHit;
+        }
+        // 3) widen the net to any Mneme-shaped name
+        const anyHit = walkUpForPackageJson(startDir, (name) => !!name && (name.startsWith("@mneme-ai/") || name === "mneme-ai" || name === "mneme"));
+        if (anyHit) {
+            cached = anyHit;
+            return anyHit;
         }
     }
     catch { /* fall through */ }

package/dist/mneme_version.js.map

@@ -1 +1 @@
-{"version":3,"file":"mneme_version.js","sourceRoot":"","sources":["../src/mneme_version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC,MAAM,UAAU,mBAAmB;IACjC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC/C,IAAI,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,CAAC;QACb,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YACtC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAwC,CAAC;gBAC5F,IAAI,MAAM,CAAC,IAAI,KAAK,gBAAgB,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;oBAC3E,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;oBACxB,OAAO,MAAM,CAAC,OAAO,CAAC;gBACxB,CAAC;YACH,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,MAAM,KAAK,GAAG;gBAAE,MAAM;YAC1B,GAAG,GAAG,MAAM,CAAC;QACf,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAC9B,MAAM,GAAG,eAAe,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,uBAAuB,KAAW,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC"}
+{"version":3,"file":"mneme_version.js","sourceRoot":"","sources":["../src/mneme_version.ts"],"names":[],"mappings":"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"}

package/dist/mneme_version.test.js

@@ -39,5 +39,20 @@ describe("mneme_version · resolution", () => {
         const v = resolveMnemeVersion();
         expect(v).not.toBe("not-a-version");
     });
+    // v2.19.43 N4 regression — pre-v2.19.43 the resolver only accepted
+    // @mneme-ai/core; on npm-global install the MCP package is a SIBLING
+    // not a parent, so walking up never found core's package.json and the
+    // resolver returned "0.0.0-unknown". Caller (system.upgrade) then
+    // reported "current: 0.0.0" + advertised an upgrade with wrong baseline.
+    it("never returns 0.0.0 when running from a real install (regression for N4)", () => {
+        delete process.env["npm_package_version"];
+        _resetMnemeVersionCache();
+        const v = resolveMnemeVersion();
+        expect(v).not.toBe("0.0.0");
+        expect(v).not.toBe("0.0.0-unknown");
+        // Should pick up a sibling Mneme-family package.json even when running
+        // from packages/mcp or packages/cli.
+        expect(v).toMatch(/^\d+\.\d+\.\d+/);
+    });
 });
 //# sourceMappingURL=mneme_version.test.js.map

package/dist/mneme_version.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"mneme_version.test.js","sourceRoot":"","sources":["../src/mneme_version.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElF,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,IAAI,KAAyB,CAAC;IAC9B,UAAU,CAAC,GAAG,EAAE;QACd,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC3C,uBAAuB,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IACH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;;YAC9D,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,KAAK,CAAC;QAChD,uBAAuB,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC/B,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,4EAA4E;QAC5E,iFAAiF;QACjF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACpC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,eAAe,CAAC;QACrD,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"mneme_version.test.js","sourceRoot":"","sources":["../src/mneme_version.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElF,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,IAAI,KAAyB,CAAC;IAC9B,UAAU,CAAC,GAAG,EAAE;QACd,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC3C,uBAAuB,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IACH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;;YAC9D,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,KAAK,CAAC;QAChD,uBAAuB,EAAE,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC/B,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC;QAC7C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,4EAA4E;QAC5E,iFAAiF;QACjF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACpC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,eAAe,CAAC;QACrD,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,qEAAqE;IACrE,sEAAsE;IACtE,kEAAkE;IAClE,yEAAyE;IACzE,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC1C,uBAAuB,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACpC,uEAAuE;QACvE,qCAAqC;QACrC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/proof_of_saving/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * v2.19.42 — PROOF OF SAVING (the wild idea no other AI tool ships).
+ *
+ *   "OpenAI / Anthropic charge you per token. Enterprises pay millions
+ *    and have no third-party-verifiable evidence of what they saved by
+ *    routing through any optimisation layer. PROOF OF SAVING mints an
+ *    HMAC-signed Merkle-rooted certificate from a batch of Governor
+ *    decisions: a Saving Manifest the procurement team can hand to
+ *    auditors. Replayable, tamper-evident, vendor-neutral. The
+ *    auditor doesn't need to trust Mneme's implementation — they
+ *    re-hash the decisions and re-derive the same Merkle root.
+ *
+ *    This composes onto v2.19.40 TOKEN GOVERNOR (decisions are the
+ *    leaves) + v2.19.34 APOSTILLE (same HMAC-chain pattern) + v2.19.34
+ *    ETERNITY (certificate pins across vendors so the saving survives
+ *    even if the optimiser provider disappears). It is the missing
+ *    enterprise procurement primitive: 'show me PROOF you saved my
+ *    company money.'
+ *
+ *    Wild because no AI optimisation vendor (LangChain / Helicone /
+ *    Portkey / Vellum / Braintrust) issues replayable savings
+ *    certificates — they show you a dashboard chart and ask you to
+ *    trust the SQL behind it. Mneme issues a 4KB JSON certificate
+ *    auditors can verify offline in 5ms."
+ */
+declare const PROTOCOL_VERSION: 1;
+export interface GovernedDecisionShape {
+    /** Stable id (some callers use signature; we sha256 the whole object). */
+    signature: string;
+    tokensUsedActual: number;
+    estTokensSavedVsDirect: number;
+    stage: number;
+}
+export interface SavingsCertificate {
+    v: typeof PROTOCOL_VERSION;
+    /** ISO timestamp of cert mint. */
+    mintedAt: string;
+    /** Window the savings cover. */
+    windowStartMs: number;
+    windowEndMs: number;
+    /** Number of governed AI calls in the window. */
+    decisionCount: number;
+    /** Total tokens that would have been spent without Mneme. */
+    totalDirectTokens: number;
+    /** Total tokens actually spent through the Governor cascade. */
+    totalActualTokens: number;
+    /** totalDirectTokens - totalActualTokens. Always >= 0 by design. */
+    totalTokensSaved: number;
+    /** Hit rate per stage (Stage 1 = cache, Stage 2 = local, etc). */
+    stageBreakdown: Record<string, {
+        calls: number;
+        tokensSaved: number;
+    }>;
+    /** Estimated USD saved at caller-supplied $-per-token. */
+    estUsdSaved: number;
+    /** Caller-supplied $-per-token used for the USD estimate. */
+    usdPerToken: number;
+    /** Merkle root over decision signatures (replay-verifiable). */
+    merkleRoot: string;
+    /** Number of leaves in the Merkle tree. */
+    merkleLeafCount: number;
+    /** HMAC over the canonicalised cert body. */
+    hmac: string;
+}
+export interface MintCertInput {
+    decisions: GovernedDecisionShape[];
+    windowStartMs: number;
+    windowEndMs: number;
+    /** Caller's blended $-per-token estimate. Default: $0.000002 (≈$2/1M). */
+    usdPerToken?: number;
+    /** Optional HMAC secret. Default: env MNEME_PROOF_SECRET. */
+    secret?: string;
+    /** Optional mint timestamp (defaults to Date.now). */
+    nowMs?: number;
+}
+/** Mint a savings certificate from a batch of Governor decisions. */
+export declare function mintSavingsCertificate(input: MintCertInput): SavingsCertificate;
+/**
+ * Verify a savings certificate. Returns { ok, reason } so callers can
+ * surface specific failure reasons (HMAC mismatch / Merkle mismatch /
+ * arithmetic violation).
+ */
+export declare function verifySavingsCertificate(cert: SavingsCertificate, decisions: GovernedDecisionShape[], secret?: string): {
+    ok: boolean;
+    reason?: string;
+};
+/** Render a human-readable summary safe to surface to a procurement dashboard. */
+export declare function formatCertificate(cert: SavingsCertificate): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/proof_of_saving/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proof_of_saving/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,QAAA,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAEpC,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,EAAE,OAAO,gBAAgB,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqCD,qEAAqE;AACrE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,kBAAkB,CA2C/E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,qBAAqB,EAAE,EAClC,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBlC;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAkBlE"}

package/dist/proof_of_saving/index.js

@@ -0,0 +1,153 @@
+/**
+ * v2.19.42 — PROOF OF SAVING (the wild idea no other AI tool ships).
+ *
+ *   "OpenAI / Anthropic charge you per token. Enterprises pay millions
+ *    and have no third-party-verifiable evidence of what they saved by
+ *    routing through any optimisation layer. PROOF OF SAVING mints an
+ *    HMAC-signed Merkle-rooted certificate from a batch of Governor
+ *    decisions: a Saving Manifest the procurement team can hand to
+ *    auditors. Replayable, tamper-evident, vendor-neutral. The
+ *    auditor doesn't need to trust Mneme's implementation — they
+ *    re-hash the decisions and re-derive the same Merkle root.
+ *
+ *    This composes onto v2.19.40 TOKEN GOVERNOR (decisions are the
+ *    leaves) + v2.19.34 APOSTILLE (same HMAC-chain pattern) + v2.19.34
+ *    ETERNITY (certificate pins across vendors so the saving survives
+ *    even if the optimiser provider disappears). It is the missing
+ *    enterprise procurement primitive: 'show me PROOF you saved my
+ *    company money.'
+ *
+ *    Wild because no AI optimisation vendor (LangChain / Helicone /
+ *    Portkey / Vellum / Braintrust) issues replayable savings
+ *    certificates — they show you a dashboard chart and ask you to
+ *    trust the SQL behind it. Mneme issues a 4KB JSON certificate
+ *    auditors can verify offline in 5ms."
+ */
+import { createHmac } from "node:crypto";
+const PROTOCOL_VERSION = 1;
+function defaultSecret() {
+    return process.env["MNEME_PROOF_SECRET"] || `mneme-proof-of-saving-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 sha256Hex(s) {
+    return createHmac("sha256", "mneme-proof-leaf").update(s).digest("hex");
+}
+function signCert(body, secret) {
+    return createHmac("sha256", secret).update(canon(body)).digest("hex");
+}
+/** Build a Merkle root over an array of leaf strings. Deterministic. */
+function merkleRoot(leaves) {
+    if (leaves.length === 0)
+        return sha256Hex("∅");
+    let level = leaves.map(sha256Hex);
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const a = level[i];
+            const b = level[i + 1] ?? a;
+            next.push(sha256Hex(a + ":" + b));
+        }
+        level = next;
+    }
+    return level[0];
+}
+/** Mint a savings certificate from a batch of Governor decisions. */
+export function mintSavingsCertificate(input) {
+    const usdPerToken = input.usdPerToken ?? 0.000002; // $2 / 1M tokens default
+    const secret = input.secret ?? defaultSecret();
+    const nowMs = input.nowMs ?? Date.now();
+    const stageBreakdown = {
+        "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 },
+    };
+    let totalActual = 0;
+    let totalSaved = 0;
+    for (const d of input.decisions) {
+        totalActual += d.tokensUsedActual;
+        totalSaved += d.estTokensSavedVsDirect;
+        const k = String(d.stage);
+        if (stageBreakdown[k]) {
+            stageBreakdown[k].calls += 1;
+            stageBreakdown[k].tokensSaved += d.estTokensSavedVsDirect;
+        }
+    }
+    const totalDirect = totalActual + totalSaved;
+    const leaves = input.decisions.map((d) => d.signature);
+    const root = merkleRoot(leaves);
+    const body = {
+        v: PROTOCOL_VERSION,
+        mintedAt: new Date(nowMs).toISOString(),
+        windowStartMs: input.windowStartMs,
+        windowEndMs: input.windowEndMs,
+        decisionCount: input.decisions.length,
+        totalDirectTokens: totalDirect,
+        totalActualTokens: totalActual,
+        totalTokensSaved: totalSaved,
+        stageBreakdown,
+        estUsdSaved: totalSaved * usdPerToken,
+        usdPerToken,
+        merkleRoot: root,
+        merkleLeafCount: leaves.length,
+    };
+    return { ...body, hmac: signCert(body, secret) };
+}
+/**
+ * Verify a savings certificate. Returns { ok, reason } so callers can
+ * surface specific failure reasons (HMAC mismatch / Merkle mismatch /
+ * arithmetic violation).
+ */
+export function verifySavingsCertificate(cert, decisions, secret) {
+    const sec = secret ?? defaultSecret();
+    // 1) Arithmetic invariants must hold internally.
+    if (cert.totalTokensSaved < 0)
+        return { ok: false, reason: "negative totalTokensSaved" };
+    if (cert.totalDirectTokens !== cert.totalActualTokens + cert.totalTokensSaved) {
+        return { ok: false, reason: "totalDirect != actual + saved" };
+    }
+    if (cert.decisionCount !== decisions.length) {
+        return { ok: false, reason: `decisionCount ${cert.decisionCount} != supplied ${decisions.length}` };
+    }
+    // 2) Merkle root must match the supplied decisions.
+    const recomputedRoot = merkleRoot(decisions.map((d) => d.signature));
+    if (recomputedRoot !== cert.merkleRoot) {
+        return { ok: false, reason: `Merkle root mismatch (expected ${cert.merkleRoot}, recomputed ${recomputedRoot})` };
+    }
+    // 3) HMAC must verify (using the same secret).
+    const { hmac, ...body } = cert;
+    const expected = signCert(body, sec);
+    if (expected !== hmac)
+        return { ok: false, reason: "HMAC mismatch — forged certificate or wrong secret" };
+    return { ok: true };
+}
+/** Render a human-readable summary safe to surface to a procurement dashboard. */
+export function formatCertificate(cert) {
+    const days = Math.max(1, Math.round((cert.windowEndMs - cert.windowStartMs) / 86_400_000));
+    const lines = [];
+    lines.push(`🪙 MNEME PROOF OF SAVING — v${cert.v}`);
+    lines.push(`   Window: ${new Date(cert.windowStartMs).toISOString().slice(0, 10)} → ${new Date(cert.windowEndMs).toISOString().slice(0, 10)} (${days} days)`);
+    lines.push(`   Calls governed: ${cert.decisionCount.toLocaleString()}`);
+    lines.push(`   Tokens that would have shipped direct: ${cert.totalDirectTokens.toLocaleString()}`);
+    lines.push(`   Tokens actually spent via Governor:    ${cert.totalActualTokens.toLocaleString()}`);
+    lines.push(`   Tokens saved:                          ${cert.totalTokensSaved.toLocaleString()} (${((cert.totalTokensSaved / Math.max(1, cert.totalDirectTokens)) * 100).toFixed(1)}%)`);
+    lines.push(`   USD saved (@ ${cert.usdPerToken}/token):         $${cert.estUsdSaved.toFixed(2)}`);
+    lines.push(`   Stage breakdown:`);
+    for (const [stage, stats] of Object.entries(cert.stageBreakdown)) {
+        if (stats.calls === 0)
+            continue;
+        lines.push(`     Stage ${stage}: ${stats.calls} calls, ${stats.tokensSaved.toLocaleString()} tokens saved`);
+    }
+    lines.push(`   Merkle root: ${cert.merkleRoot.slice(0, 16)}…  (${cert.merkleLeafCount} leaves)`);
+    lines.push(`   HMAC:        ${cert.hmac.slice(0, 16)}…  (verify with mneme.proof.verify)`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=index.js.map

package/dist/proof_of_saving/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/proof_of_saving/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAmDpC,SAAS,aAAa;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,0BAA0B,gBAAgB,EAAE,CAAC;AAC3F,CAAC;AAED,SAAS,KAAK,CAAC,CAAU;IACvB,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAChE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9D,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,CAAE,CAA6B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AACnH,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,UAAU,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,QAAQ,CAAC,IAAsC,EAAE,MAAc;IACtE,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,wEAAwE;AACxE,SAAS,UAAU,CAAC,MAAgB;IAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACpB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,CAAC,CAAE,CAAC;AACnB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,sBAAsB,CAAC,KAAoB;IACzD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,QAAQ,CAAC,CAAC,yBAAyB;IAC5E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAExC,MAAM,cAAc,GAA2D;QAC7E,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;QACjC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;QACjC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;QACjC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;QACjC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;KAClC,CAAC;IACF,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAChC,WAAW,IAAI,CAAC,CAAC,gBAAgB,CAAC;QAClC,UAAU,IAAI,CAAC,CAAC,sBAAsB,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YAC7B,cAAc,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,sBAAsB,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAEhC,MAAM,IAAI,GAAqC;QAC7C,CAAC,EAAE,gBAAgB;QACnB,QAAQ,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;QACvC,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM;QACrC,iBAAiB,EAAE,WAAW;QAC9B,iBAAiB,EAAE,WAAW;QAC9B,gBAAgB,EAAE,UAAU;QAC5B,cAAc;QACd,WAAW,EAAE,UAAU,GAAG,WAAW;QACrC,WAAW;QACX,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,MAAM,CAAC,MAAM;KAC/B,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAwB,EACxB,SAAkC,EAClC,MAAe;IAEf,MAAM,GAAG,GAAG,MAAM,IAAI,aAAa,EAAE,CAAC;IAEtC,iDAAiD;IACjD,IAAI,IAAI,CAAC,gBAAgB,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACzF,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,IAAI,CAAC,aAAa,gBAAgB,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;IACtG,CAAC;IAED,oDAAoD;IACpD,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACrE,IAAI,cAAc,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,IAAI,CAAC,UAAU,gBAAgB,cAAc,GAAG,EAAE,CAAC;IACnH,CAAC;IAED,+CAA+C;IAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC/B,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oDAAoD,EAAE,CAAC;IAE1G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,+BAA+B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC;IAC9J,KAAK,CAAC,IAAI,CAAC,sBAAsB,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,CAAC,6CAA6C,IAAI,CAAC,iBAAiB,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACnG,KAAK,CAAC,IAAI,CAAC,6CAA6C,IAAI,CAAC,iBAAiB,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACnG,KAAK,CAAC,IAAI,CAAC,6CAA6C,IAAI,CAAC,gBAAgB,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACzL,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,WAAW,qBAAqB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClG,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACjE,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC;YAAE,SAAS;QAChC,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,KAAK,KAAK,CAAC,KAAK,WAAW,KAAK,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAC9G,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC,eAAe,UAAU,CAAC,CAAC;IACjG,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,qCAAqC,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/proof_of_saving/proof_of_saving.test.d.ts

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

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

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

package/dist/proof_of_saving/proof_of_saving.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { mintSavingsCertificate, verifySavingsCertificate, formatCertificate, } from "./index.js";
+const SECRET = "proof-test-secret-77";
+function makeDecisions(n, fixedSaving = 100, fixedActual = 50) {
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        out.push({
+            signature: `sig-${i}-${Math.random().toString(36).slice(2, 10)}`,
+            tokensUsedActual: fixedActual,
+            estTokensSavedVsDirect: fixedSaving,
+            stage: ((i % 4) + 1),
+        });
+    }
+    return out;
+}
+describe("v2.19.42 PROOF OF SAVING · mint + verify round trip", () => {
+    it("mints a certificate with correct arithmetic", () => {
+        const decisions = makeDecisions(10);
+        const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: 1000, secret: SECRET });
+        expect(cert.decisionCount).toBe(10);
+        expect(cert.totalActualTokens).toBe(500);
+        expect(cert.totalTokensSaved).toBe(1000);
+        expect(cert.totalDirectTokens).toBe(1500);
+        expect(cert.merkleLeafCount).toBe(10);
+        expect(cert.hmac.length).toBe(64);
+    });
+    it("verify returns ok on a fresh cert", () => {
+        const decisions = makeDecisions(5);
+        const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        expect(verifySavingsCertificate(cert, decisions, SECRET).ok).toBe(true);
+    });
+    it("verify detects tampered HMAC", () => {
+        const decisions = makeDecisions(3);
+        const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        const tampered = { ...cert, totalTokensSaved: cert.totalTokensSaved + 100 };
+        expect(verifySavingsCertificate(tampered, decisions, SECRET).ok).toBe(false);
+    });
+    it("verify detects swapped decisions (Merkle mismatch)", () => {
+        const a = makeDecisions(3);
+        const cert = mintSavingsCertificate({ decisions: a, windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        const b = makeDecisions(3);
+        const r = verifySavingsCertificate(cert, b, SECRET);
+        expect(r.ok).toBe(false);
+        expect(r.reason).toContain("Merkle");
+    });
+    it("verify detects wrong secret", () => {
+        const decisions = makeDecisions(2);
+        const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        expect(verifySavingsCertificate(cert, decisions, "wrong-secret").ok).toBe(false);
+    });
+    it("empty decisions list still produces a valid cert (zero savings)", () => {
+        const cert = mintSavingsCertificate({ decisions: [], windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        expect(cert.decisionCount).toBe(0);
+        expect(cert.totalTokensSaved).toBe(0);
+        expect(verifySavingsCertificate(cert, [], SECRET).ok).toBe(true);
+    });
+    it("USD estimate uses caller-supplied usdPerToken", () => {
+        const cert = mintSavingsCertificate({ decisions: makeDecisions(10, 1000, 0), windowStartMs: 0, windowEndMs: 1, usdPerToken: 0.00001, secret: SECRET });
+        expect(cert.estUsdSaved).toBe(10000 * 0.00001);
+    });
+});
+describe("v2.19.42 PROOF OF SAVING · stage breakdown + format", () => {
+    it("stage breakdown counts calls and tokens per stage", () => {
+        const decisions = makeDecisions(20);
+        const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        const total = Object.values(cert.stageBreakdown).reduce((s, b) => s + b.calls, 0);
+        expect(total).toBe(20);
+    });
+    it("formatCertificate produces multi-line human-readable text", () => {
+        const cert = mintSavingsCertificate({ decisions: makeDecisions(3), windowStartMs: 0, windowEndMs: 1, secret: SECRET });
+        const txt = formatCertificate(cert);
+        expect(txt).toContain("PROOF OF SAVING");
+        expect(txt).toContain("Tokens saved");
+        expect(txt).toContain("Merkle root");
+    });
+});
+describe("v2.19.42 PROOF OF SAVING · 1000-iter fuzz", () => {
+    it("mint + verify cycle never throws on random batches", () => {
+        for (let i = 0; i < 1000; i++) {
+            const n = Math.floor(Math.random() * 30);
+            const decisions = makeDecisions(n, Math.floor(Math.random() * 1000), Math.floor(Math.random() * 500));
+            const cert = mintSavingsCertificate({ decisions, windowStartMs: 0, windowEndMs: i, secret: SECRET, nowMs: i });
+            expect(verifySavingsCertificate(cert, decisions, SECRET).ok).toBe(true);
+        }
+    });
+});
+//# sourceMappingURL=proof_of_saving.test.js.map

package/dist/proof_of_saving/proof_of_saving.test.js.map

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

package/dist/squadron/acgv_explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acgv_explain.d.ts","sourceRoot":"","sources":["../../src/squadron/acgv_explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,YAAY,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IACnD,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAyE3E;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E"}
+{"version":3,"file":"acgv_explain.d.ts","sourceRoot":"","sources":["../../src/squadron/acgv_explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,YAAY,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IACnD,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAyE3E;AA+BD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAe7E"}

package/dist/squadron/acgv_explain.js

@@ -84,17 +84,47 @@ export function explain(result, claim) {
         }
     }
 }
+/**
+ * v2.19.43 N8 fix — presentation consistency invariant.
+ *
+ * User audit (2026-05-18): `mneme verify "Mneme is written in Rust AND
+ * mneme.truth.forensic is registered"` rendered:
+ *   🌑 IMPOSSIBLE -- REFUTED -- language=rust is impossible ...
+ *   ...
+ *     ✅ TRUTH-FORENSIC verdict: ACCEPTED. Every assertion grounded ...
+ *
+ * The headline used trafficLight=black (🌑 IMPOSSIBLE) but the plain
+ * text leaked a ✅ from the appended forensic explanation. Both emoji
+ * present → user confused about which verdict won.
+ *
+ * Invariant: the headline emoji is canonical; any conflicting
+ * verdict glyphs in the plain block get neutralised to a neutral mark
+ * (●). The verdict text itself is preserved so power-users still see
+ * "TRUTH-FORENSIC verdict: ACCEPTED" — only the contradicting emoji
+ * is stripped.
+ */
+function neutraliseConflictingEmoji(plain, headlineLight) {
+    if (!plain)
+        return plain;
+    // Map every other-traffic-light glyph to a neutral bullet.
+    const neutralise = (glyph) => `●`;
+    const allow = { green: "✅", yellow: "⚠️", red: "❌", black: "🌑" };
+    const keep = allow[headlineLight];
+    return plain
+        .replace(/✅|⚠️|❌|🌑/g, (m) => (m === keep ? m : neutralise(m)));
+}
 /** Format the explained verdict for terminal output. ~10 lines, scannable. */
 export function renderExplained(ev, claim) {
     const glyph = ev.trafficLight === "green" ? "✅" : ev.trafficLight === "yellow" ? "⚠️" : ev.trafficLight === "red" ? "❌" : "🌑";
     const tone = ev.trafficLight === "green" ? "TRUSTWORTHY" : ev.trafficLight === "yellow" ? "MIXED" : ev.trafficLight === "red" ? "REFUTED" : "IMPOSSIBLE";
+    const cleanPlain = neutraliseConflictingEmoji(ev.plain, ev.trafficLight);
     return [
         `${glyph} ${tone} -- ${ev.headline}`,
         ``,
         `Claim: "${claim.length > 90 ? claim.slice(0, 87) + "..." : claim}"`,
         ``,
         `What this means:`,
-        `  ${ev.plain}`,
+        `  ${cleanPlain}`,
         ``,
         `Next step:`,
         `  -> ${ev.nextAction}`,