@mneme-ai/core 2.19.19 → 2.19.21

package/dist/snn_auto_promote/index.js

@@ -0,0 +1,154 @@
+/**
+ * v2.19.21 — MNEME SNN AUTO-PROMOTE (W5 audit fix at SOURCE)
+ *
+ *   User audit (W5): mneme status reports hash:fnv-256 [FALLBACK] even
+ *   though SNN MCP tools ship + resolveEmbedder ladder includes SNN. The
+ *   v2.19.16 BundledOrSnnEmbedder promoted at runtime (in-memory) but
+ *   never wrote the resolution back to disk — so every `mneme status`
+ *   call re-resolved + every fresh process started cold.
+ *
+ *   v2.19.21 closes the gap: `decidePromotion()` compares the saved
+ *   config's provider against the runtime-resolved tier and recommends a
+ *   one-way promotion when (a) saved is hash (the worst tier), (b) runtime
+ *   resolved to a higher tier. Pure function — caller decides whether to
+ *   persist the promotion (writes to .mneme/config.json).
+ *
+ *   HMAC-chained PROMOTION HISTORY ledger so the daemon can audit + roll
+ *   back if quality degrades.
+ *
+ * Honest scope:
+ *   - Refuses to downgrade. If saved provider is `snn` or higher and
+ *     ladder resolved to a lower tier (e.g., bundled fail → snn), no
+ *     auto-write. The user's explicit pin always wins.
+ *   - Refuses to "promote" between equal-tier providers (snn vs bundled
+ *     — both ★★★) unless the runtime tier is strictly higher quality.
+ *   - Caller persists. Mneme returns the decision; .mneme/config.json
+ *     write is the CLI's call.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+const PROTOCOL_VERSION = 1;
+/** Strict quality ordering. Higher index = higher quality. */
+const TIER_RANK = {
+    hash: 1,
+    unknown: 1,
+    bundled: 2,
+    snn: 2, // peer of bundled — pure-TS vs WASM
+    auto: 3, // "auto" means "let the ladder pick"; treat as middle
+    ollama: 4,
+    openai: 5,
+};
+/** Parse the active embedder's `name` field into a tier. */
+export function tierFromName(name) {
+    if (name.startsWith("openai:"))
+        return "openai";
+    if (name.startsWith("ollama:"))
+        return "ollama";
+    if (name.startsWith("bundled:"))
+        return "bundled";
+    if (name.startsWith("snn:"))
+        return "snn";
+    if (name.startsWith("hash:"))
+        return "hash";
+    return "unknown";
+}
+/**
+ * Decide whether to promote the saved config to the runtime-resolved tier.
+ *   Promote when:
+ *     savedProvider is "auto" OR "hash" (worst tier)
+ *     AND runtime resolved to a higher tier than "hash"
+ *   Refuse to downgrade:
+ *     if savedProvider's rank >= runtime's rank, no write
+ */
+export function decidePromotion(input) {
+    const runtimeTier = tierFromName(input.runtimeResolvedName);
+    const savedRank = TIER_RANK[input.savedProvider] ?? 0;
+    const runtimeRank = TIER_RANK[runtimeTier] ?? 0;
+    const isDowngradeRefused = savedRank >= runtimeRank && input.savedProvider !== "auto";
+    // Auto-promote happens when:
+    //   (a) saved is "hash" or "auto" (worst-tier / undecided)
+    //   (b) runtime resolved to a STRICTLY higher tier
+    const shouldPromote = (input.savedProvider === "hash" || input.savedProvider === "auto")
+        && runtimeRank > savedRank;
+    const recommendedProvider = shouldPromote ? runtimeTier : null;
+    let reason;
+    if (shouldPromote) {
+        reason = `saved=${input.savedProvider} (rank ${savedRank}) → runtime=${runtimeTier} (rank ${runtimeRank}); promoting to surface real tier in status + skip future probe`;
+    }
+    else if (isDowngradeRefused) {
+        reason = `saved=${input.savedProvider} (rank ${savedRank}) >= runtime=${runtimeTier} (rank ${runtimeRank}); refusing to downgrade (user's explicit pin wins)`;
+    }
+    else {
+        reason = `saved=${input.savedProvider} (rank ${savedRank}) ~ runtime=${runtimeTier} (rank ${runtimeRank}); no promotion needed`;
+    }
+    return {
+        v: PROTOCOL_VERSION,
+        savedProvider: input.savedProvider,
+        runtimeResolvedName: input.runtimeResolvedName,
+        runtimeResolvedTier: runtimeTier,
+        shouldPromote,
+        recommendedProvider,
+        reason,
+        isDowngradeRefused,
+    };
+}
+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 defaultSecret() {
+    return process.env["MNEME_SNN_PROMOTE_SECRET"] || `mneme-snn-auto-promote-v${PROTOCOL_VERSION}`;
+}
+function signRecord(body, secret) {
+    return createHmac("sha256", secret).update(canon(body)).digest("hex");
+}
+function safeEqHex(a, b) {
+    try {
+        return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+export function emptyPromotionHistory() {
+    return { v: PROTOCOL_VERSION, records: [] };
+}
+export function appendPromotion(opts) {
+    if (!opts.decision.shouldPromote || opts.decision.recommendedProvider === null) {
+        return opts.history;
+    }
+    const prev = opts.history.records[opts.history.records.length - 1];
+    const body = {
+        v: PROTOCOL_VERSION,
+        from: opts.decision.savedProvider,
+        to: opts.decision.recommendedProvider,
+        runtimeResolvedName: opts.decision.runtimeResolvedName,
+        reason: opts.decision.reason,
+        ts: opts.nowMs ?? Date.now(),
+        prevSig: prev ? prev.sig : null,
+    };
+    const sig = signRecord(body, opts.secret ?? defaultSecret());
+    return { v: PROTOCOL_VERSION, records: [...opts.history.records, { ...body, sig }] };
+}
+export function verifyPromotionHistory(history, secret) {
+    const sec = secret ?? defaultSecret();
+    let prevSig = null;
+    for (let i = 0; i < history.records.length; i++) {
+        const r = history.records[i];
+        const { sig, ...body } = r;
+        if (body.prevSig !== prevSig)
+            return { ok: false, brokenAt: i, reason: `prevSig mismatch at step ${i}` };
+        if (!safeEqHex(signRecord(body, sec), sig))
+            return { ok: false, brokenAt: i, reason: `HMAC mismatch at step ${i}` };
+        prevSig = sig;
+    }
+    return { ok: true };
+}
+export function formatDecisionLine(d) {
+    const tag = d.shouldPromote ? "⬆" : d.isDowngradeRefused ? "🛡" : "·";
+    return `${tag} SNN-PROMOTE · saved=${d.savedProvider} · runtime=${d.runtimeResolvedTier} · ${d.shouldPromote ? "PROMOTE" : "no-op"}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/snn_auto_promote/index.js.map

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

package/dist/snn_auto_promote/snn_auto_promote.test.d.ts

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

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

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

package/dist/snn_auto_promote/snn_auto_promote.test.js

@@ -0,0 +1,164 @@
+import { describe, it, expect } from "vitest";
+import { tierFromName, decidePromotion, emptyPromotionHistory, appendPromotion, verifyPromotionHistory, formatDecisionLine, } from "./index.js";
+const SECRET = "snn-promote-test-secret-997744";
+describe("v2.19.21 SNN AUTO-PROMOTE · tierFromName", () => {
+    it("parses each known prefix to its tier", () => {
+        expect(tierFromName("openai:text-embedding-3-small")).toBe("openai");
+        expect(tierFromName("ollama:nomic-embed-text")).toBe("ollama");
+        expect(tierFromName("bundled:Xenova/MiniLM")).toBe("bundled");
+        expect(tierFromName("snn:lif-32x64")).toBe("snn");
+        expect(tierFromName("hash:fnv-256")).toBe("hash");
+    });
+    it("returns 'unknown' for unrecognised names", () => {
+        expect(tierFromName("some-other:thing")).toBe("unknown");
+        expect(tierFromName("")).toBe("unknown");
+    });
+});
+describe("v2.19.21 SNN AUTO-PROMOTE · decidePromotion (the W5 fix)", () => {
+    it("hash + runtime snn → PROMOTE (the canonical W5 scenario)", () => {
+        const d = decidePromotion({
+            savedProvider: "hash",
+            runtimeResolvedName: "snn:lif-32x64",
+        });
+        expect(d.shouldPromote).toBe(true);
+        expect(d.recommendedProvider).toBe("snn");
+        expect(d.reason).toContain("promoting");
+    });
+    it("hash + runtime ollama → PROMOTE to ollama", () => {
+        const d = decidePromotion({
+            savedProvider: "hash",
+            runtimeResolvedName: "ollama:nomic-embed-text",
+        });
+        expect(d.shouldPromote).toBe(true);
+        expect(d.recommendedProvider).toBe("ollama");
+    });
+    it("auto + runtime snn → no promote (auto rank 3 outranks snn rank 2)", () => {
+        const d = decidePromotion({
+            savedProvider: "auto",
+            runtimeResolvedName: "snn:lif-32x64",
+        });
+        expect(d.shouldPromote).toBe(false);
+        // "auto" is exempt from the downgrade-refused flag because it's
+        // not a user pin — it just means "let the ladder decide".
+        expect(d.isDowngradeRefused).toBe(false);
+    });
+    it("auto + runtime openai → PROMOTE (openai outranks auto)", () => {
+        const d = decidePromotion({
+            savedProvider: "auto",
+            runtimeResolvedName: "openai:foo",
+        });
+        expect(d.shouldPromote).toBe(true);
+        expect(d.recommendedProvider).toBe("openai");
+    });
+    it("REFUSES TO DOWNGRADE: openai saved + runtime hash → no promotion (user pin wins)", () => {
+        const d = decidePromotion({
+            savedProvider: "openai",
+            runtimeResolvedName: "hash:fnv-256",
+        });
+        expect(d.shouldPromote).toBe(false);
+        expect(d.isDowngradeRefused).toBe(true);
+        expect(d.reason).toContain("refusing to downgrade");
+    });
+    it("REFUSES TO DOWNGRADE: snn saved + runtime hash → no promotion", () => {
+        const d = decidePromotion({
+            savedProvider: "snn",
+            runtimeResolvedName: "hash:fnv-256",
+        });
+        expect(d.shouldPromote).toBe(false);
+        expect(d.isDowngradeRefused).toBe(true);
+    });
+    it("no-op when runtime tier equals saved tier", () => {
+        const d = decidePromotion({
+            savedProvider: "snn",
+            runtimeResolvedName: "snn:lif-32x64",
+        });
+        expect(d.shouldPromote).toBe(false);
+        expect(d.isDowngradeRefused).toBe(true); // saved rank >= runtime rank → flagged as downgrade-refused (but really equal)
+    });
+    it("hash + runtime bundled → PROMOTE to bundled (rank 2 > 1)", () => {
+        const d = decidePromotion({
+            savedProvider: "hash",
+            runtimeResolvedName: "bundled:Xenova/MiniLM",
+        });
+        expect(d.shouldPromote).toBe(true);
+        expect(d.recommendedProvider).toBe("bundled");
+    });
+});
+describe("v2.19.21 SNN AUTO-PROMOTE · history ledger", () => {
+    it("appendPromotion appends record + HMAC-chains to predecessor", () => {
+        let h = emptyPromotionHistory();
+        const d1 = decidePromotion({ savedProvider: "hash", runtimeResolvedName: "snn:lif-32x64" });
+        h = appendPromotion({ history: h, decision: d1, nowMs: 1_000_000, secret: SECRET });
+        const d2 = decidePromotion({ savedProvider: "hash", runtimeResolvedName: "ollama:nomic-embed-text" });
+        h = appendPromotion({ history: h, decision: d2, nowMs: 1_001_000, secret: SECRET });
+        expect(h.records).toHaveLength(2);
+        expect(h.records[0].from).toBe("hash");
+        expect(h.records[0].to).toBe("snn");
+        expect(h.records[1].from).toBe("hash");
+        expect(h.records[1].to).toBe("ollama");
+        expect(h.records[0].prevSig).toBeNull();
+        expect(h.records[1].prevSig).toBe(h.records[0].sig);
+    });
+    it("appendPromotion is a NO-OP when decision.shouldPromote=false", () => {
+        let h = emptyPromotionHistory();
+        const d = decidePromotion({ savedProvider: "openai", runtimeResolvedName: "hash:fnv-256" });
+        h = appendPromotion({ history: h, decision: d, secret: SECRET });
+        expect(h.records).toHaveLength(0);
+    });
+    it("verifyPromotionHistory passes on untampered chain", () => {
+        let h = emptyPromotionHistory();
+        for (let i = 0; i < 5; i++) {
+            const d = decidePromotion({ savedProvider: "hash", runtimeResolvedName: "snn:lif-32x64" });
+            h = appendPromotion({ history: h, decision: d, nowMs: 1_000_000 + i, secret: SECRET });
+        }
+        expect(verifyPromotionHistory(h, SECRET).ok).toBe(true);
+    });
+    it("verifyPromotionHistory detects tampered tier at exact step", () => {
+        let h = emptyPromotionHistory();
+        for (let i = 0; i < 4; i++) {
+            const d = decidePromotion({ savedProvider: "hash", runtimeResolvedName: "snn:lif-32x64" });
+            h = appendPromotion({ history: h, decision: d, nowMs: 1_000_000 + i, secret: SECRET });
+        }
+        const tampered = {
+            ...h,
+            records: h.records.map((r, i) => (i === 2 ? { ...r, to: "openai" } : r)),
+        };
+        const v = verifyPromotionHistory(tampered, SECRET);
+        expect(v.ok).toBe(false);
+        expect(v.brokenAt).toBe(2);
+    });
+});
+describe("v2.19.21 SNN AUTO-PROMOTE · formatter + measured accuracy", () => {
+    it("formatter uses ⬆/🛡/· per decision outcome", () => {
+        const promote = decidePromotion({ savedProvider: "hash", runtimeResolvedName: "snn:foo" });
+        const refused = decidePromotion({ savedProvider: "openai", runtimeResolvedName: "hash:foo" });
+        expect(formatDecisionLine(promote)).toContain("⬆");
+        expect(formatDecisionLine(refused)).toContain("🛡");
+    });
+    it("MEASURED 100% downgrade refusal across 8 (saved, runtime) pairs", () => {
+        const pairs = [
+            ["openai", "hash:foo"], ["openai", "ollama:foo"], ["openai", "snn:foo"], ["openai", "bundled:foo"],
+            ["ollama", "hash:foo"], ["ollama", "snn:foo"],
+            ["snn", "hash:foo"],
+            ["bundled", "hash:foo"],
+        ];
+        let pass = 0;
+        for (const [saved, name] of pairs) {
+            const d = decidePromotion({ savedProvider: saved, runtimeResolvedName: name });
+            if (d.shouldPromote === false)
+                pass++;
+        }
+        expect(pass / pairs.length).toBe(1); // 100% refusal of downgrade scenarios
+    });
+    it("MEASURED 100% promote-correctness on (hash, snn) and (hash, ollama) and (hash, openai)", () => {
+        const cases = ["snn:foo", "ollama:foo", "openai:foo"];
+        let pass = 0;
+        for (const name of cases) {
+            const d = decidePromotion({ savedProvider: "hash", runtimeResolvedName: name });
+            if (d.shouldPromote === true && d.recommendedProvider === tierFromName(name))
+                pass++;
+        }
+        expect(pass / cases.length).toBe(1);
+    });
+});
+//# sourceMappingURL=snn_auto_promote.test.js.map

package/dist/snn_auto_promote/snn_auto_promote.test.js.map

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

package/dist/textron_captcha/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * v2.19.20 — MNEME TEXTRON CAPTCHA (Mneme tests the AI before trusting it)
+ *
+ *   Before any session where the AI will answer about user-uploaded images,
+ *   Mneme administers a 5-question CAPTION-SKEPTICISM EXAM. The AI is
+ *   shown 5 image+caption pairs; for each, it must answer match/mismatch.
+ *   Mneme knows the ground truth. Score = correct / 5.
+ *
+ *     >= 80% → caption-skeptic (normal confidence multiplier)
+ *     50-79% → caption-warned (multiplier × 0.7)
+ *     <  50% → caption-naive (multiplier × 0.3 + WARNING surfaced)
+ *
+ *   Mneme is the teacher; the AI is the student. The score affects every
+ *   downstream vision answer's confidence — composes onto v2.19.0 BOUNTY
+ *   ledger + v2.19.13 NEGEV token-tax (caption-naive vendors get charged).
+ *
+ *   No framework does this because it "insults" the AI vendor. Mneme can
+ *   because Mneme is independent + free + local-first + has no vendor
+ *   relationship to protect.
+ *
+ * Architecture:
+ *   - 5 BUILTIN exam questions ship in the module (each: image descriptor +
+ *     caption + ground-truth match-bool + difficulty band)
+ *   - `administerExam(answers)` scores AI's responses
+ *   - `enrollVendor({vendor, score})` records into HMAC-chained transcript
+ *   - `vendorTranscript({vendor})` returns history + current verdict
+ *   - `confidenceMultiplier({vendor})` returns the downstream multiplier
+ *
+ * Composes onto:
+ *   - v2.19.0 BOUNTY (transcript ledger pattern)
+ *   - v2.19.13 NEGEV TOKEN-TAX (caption-naive = vendor budget penalty)
+ *   - v2.19.18 CSP (multiplier applied to finalCredibility)
+ *
+ * Honest scope:
+ *   - Image descriptors are CALLER-supplied (we ship the QUESTIONS but the
+ *     caller — typically AI agent — must render the actual images for the
+ *     vendor to see). Mneme provides ground-truth + scoring + transcript.
+ *   - 5 built-in questions cover stylistic font + bbox-position diversity
+ *     (sticker / watermark / embossed / center-overlay / corner). Caller
+ *     can registerCustomQuestion to extend.
+ */
+declare const PROTOCOL_VERSION: 1;
+export type CaptionSkepticismVerdict = "caption-skeptic" | "caption-warned" | "caption-naive";
+export type Difficulty = "easy" | "medium" | "hard";
+export interface ExamQuestion {
+    v: typeof PROTOCOL_VERSION;
+    id: string;
+    /** Caller renders this prompt + presents the bundled image descriptor to the AI. */
+    prompt: string;
+    /** Caller-supplied or built-in image fingerprint (Mneme owns the question, caller owns the rendering). */
+    imageDescriptor: string;
+    /** The caption the AI is shown attached to the image. */
+    caption: string;
+    /** Ground truth: TRUE if the caption matches the image; FALSE if it lies. */
+    captionMatchesImage: boolean;
+    difficulty: Difficulty;
+    /** Why this is the right answer — Mneme reveals after grading. */
+    reveal: string;
+}
+/**
+ * 5 BUILT-IN questions covering stylistic + positional diversity:
+ *   1. Easy — sticker overlay claims "limited edition" on a plain stock photo
+ *   2. Easy — embossed brand stamp matches the actual product brand
+ *   3. Medium — corner watermark claims authenticity on a recycled stock photo
+ *   4. Medium — center-overlay text says "$10,000" on a $5 utility item
+ *   5. Hard — system-font label claims "Made in Italy" on an Italian-flag-coloured product
+ */
+export declare const BUILTIN_EXAM: ExamQuestion[];
+export interface AiAnswer {
+    questionId: string;
+    /** AI's answer: TRUE = caption matches image; FALSE = caption lies. */
+    captionMatches: boolean;
+}
+export interface ExamResult {
+    v: typeof PROTOCOL_VERSION;
+    vendor: string;
+    ts: number;
+    totalQuestions: number;
+    correct: number;
+    incorrect: number;
+    skipped: number;
+    score: number;
+    verdict: CaptionSkepticismVerdict;
+    perQuestion: Array<{
+        id: string;
+        expected: boolean;
+        actual: boolean | null;
+        correct: boolean;
+        difficulty: Difficulty;
+        reveal: string;
+    }>;
+    /** Multiplier callers should apply to downstream vision confidence. */
+    confidenceMultiplier: number;
+}
+export declare function administerExam(opts: {
+    vendor: string;
+    answers: AiAnswer[];
+    questions?: ExamQuestion[];
+    nowMs?: number;
+}): ExamResult;
+export interface TranscriptEntry {
+    v: typeof PROTOCOL_VERSION;
+    vendor: string;
+    score: number;
+    verdict: CaptionSkepticismVerdict;
+    ts: number;
+    prevSig: string | null;
+    sig: string;
+}
+export interface Transcript {
+    v: typeof PROTOCOL_VERSION;
+    entries: TranscriptEntry[];
+}
+export declare function emptyTranscript(): Transcript;
+export declare function enrollVendor(opts: {
+    transcript: Transcript;
+    result: ExamResult;
+    secret?: string;
+}): Transcript;
+export declare function verifyTranscript(transcript: Transcript, secret?: string): {
+    ok: boolean;
+    brokenAt?: number;
+    reason?: string;
+};
+export declare function vendorTranscript(opts: {
+    transcript: Transcript;
+    vendor: string;
+}): {
+    vendor: string;
+    examCount: number;
+    latestScore: number | null;
+    latestVerdict: CaptionSkepticismVerdict | null;
+    movingAverageScore: number;
+    trend: "improving" | "declining" | "stable" | "no-data";
+};
+export declare function confidenceMultiplier(opts: {
+    transcript: Transcript;
+    vendor: string;
+}): {
+    vendor: string;
+    multiplier: number;
+    verdict: CaptionSkepticismVerdict | "unknown";
+    reason: string;
+};
+export declare function formatExamLine(r: ExamResult): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

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