@mneme-ai/core 2.52.0 → 2.54.0

package/dist/nemesis/janus.d.ts

@@ -0,0 +1,93 @@
+/**
+ * v2.53.0 — JANUS organ: cross-vendor cluster-boundary detector.
+ *
+ * The two-faced Roman god — looks at past + future simultaneously.
+ *
+ * Closes Eve's identity-swap blind spot from the Million Dollar Secret
+ * simulation: MOLT (v2.52) detects INTRA-vendor drift (vendor X drifts
+ * over time) but misses CROSS-vendor swaps (vendor X mid-session
+ * starts behaving like vendor Y). The classifier might still pick Y as
+ * the new winner, but neither MOLT nor verify_identity surfaces the
+ * "you crossed a cluster boundary" event.
+ *
+ * Algorithm:
+ *   1. Build cluster centroids from seed corpus (per vendor, per
+ *      discriminative feature).
+ *   2. For an observation O, compute distance d(O, centroid_V) for every
+ *      known vendor V.
+ *   3. Assign O to the nearest centroid → "current basin".
+ *   4. Track per-session basin history. If basin changes between
+ *      observations → cross-cluster transition event.
+ *   5. Confidence: distance to old basin / distance to new basin (lower
+ *      ratio = sharper swap).
+ *
+ * Different from MOLT because MOLT compares pre/post WINDOWS of the
+ * SAME vendor's drift; JANUS detects the MOMENT a vendor's fingerprint
+ * crosses into a DIFFERENT vendor's basin.
+ *
+ * Composes: extractFingerprint + seedStats.
+ *
+ * Pure deterministic + defensive; never throws.
+ */
+import type { Fingerprint } from "./types.js";
+export interface ClusterDistance {
+    vendor: string;
+    distance: number;
+}
+export interface JanusBasin {
+    /** Nearest vendor centroid. */
+    basin: string;
+    /** Distance to nearest centroid. */
+    basinDistance: number;
+    /** Distance to SECOND-nearest centroid (margin signal). */
+    secondNearest: ClusterDistance | null;
+    /** Margin = secondNearest.distance - basinDistance. Larger = sharper assignment. */
+    margin: number;
+    /** All centroid distances, sorted ascending. */
+    allDistances: ClusterDistance[];
+}
+export interface JanusObservation {
+    fingerprint: Fingerprint;
+    basin: JanusBasin;
+}
+export interface JanusTransition {
+    fromBasin: string;
+    toBasin: string;
+    fromDistance: number;
+    toDistance: number;
+    /** Ratio of (distance to OLD basin from CURRENT obs) / (distance to NEW basin from CURRENT obs).
+     *  > 1 means the obs is clearly closer to NEW than OLD → confident swap. */
+    swapConfidence: number;
+    /** Plain-English citation. */
+    citation: string;
+}
+export interface JanusSessionResult {
+    observations: JanusObservation[];
+    transitions: JanusTransition[];
+    /** Did at least one cross-cluster swap fire? */
+    swapDetected: boolean;
+    hmac: string;
+}
+/**
+ * Locate which vendor cluster an observation belongs to.
+ * Defensive: empty stats → returns basin="unknown" with infinity distance.
+ */
+export declare function locateBasin(fingerprint: Fingerprint): JanusBasin;
+/**
+ * Observe a fixture; return {fingerprint, basin}.
+ */
+export declare function observe(fixture: {
+    diff: string;
+    prDescription: string;
+    commitMessages: string[];
+} | Fingerprint): JanusObservation;
+/**
+ * Walk a sequence of observations from the SAME session; surface
+ * cross-cluster transitions + an HMAC-signed verdict.
+ */
+export declare function detectIdentitySwap(observations: JanusObservation[], opts?: {
+    minMargin?: number;
+}): JanusSessionResult;
+/** Verify a session-result's HMAC. */
+export declare function verifyJanusResult(r: JanusSessionResult): boolean;
+//# sourceMappingURL=janus.d.ts.map

package/dist/nemesis/janus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"janus.d.ts","sourceRoot":"","sources":["../../src/nemesis/janus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,YAAY,CAAC;AASxD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,aAAa,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;gFAC4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,gDAAgD;IAChD,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAoBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,CAyBhE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,WAAW,GAAG,gBAAgB,CAMlI;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,kBAAkB,CAoCpB;AAWD,sCAAsC;AACtC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAQhE"}

package/dist/nemesis/janus.js

@@ -0,0 +1,160 @@
+/**
+ * v2.53.0 — JANUS organ: cross-vendor cluster-boundary detector.
+ *
+ * The two-faced Roman god — looks at past + future simultaneously.
+ *
+ * Closes Eve's identity-swap blind spot from the Million Dollar Secret
+ * simulation: MOLT (v2.52) detects INTRA-vendor drift (vendor X drifts
+ * over time) but misses CROSS-vendor swaps (vendor X mid-session
+ * starts behaving like vendor Y). The classifier might still pick Y as
+ * the new winner, but neither MOLT nor verify_identity surfaces the
+ * "you crossed a cluster boundary" event.
+ *
+ * Algorithm:
+ *   1. Build cluster centroids from seed corpus (per vendor, per
+ *      discriminative feature).
+ *   2. For an observation O, compute distance d(O, centroid_V) for every
+ *      known vendor V.
+ *   3. Assign O to the nearest centroid → "current basin".
+ *   4. Track per-session basin history. If basin changes between
+ *      observations → cross-cluster transition event.
+ *   5. Confidence: distance to old basin / distance to new basin (lower
+ *      ratio = sharper swap).
+ *
+ * Different from MOLT because MOLT compares pre/post WINDOWS of the
+ * SAME vendor's drift; JANUS detects the MOMENT a vendor's fingerprint
+ * crosses into a DIFFERENT vendor's basin.
+ *
+ * Composes: extractFingerprint + seedStats.
+ *
+ * Pure deterministic + defensive; never throws.
+ */
+import { createHmac } from "node:crypto";
+import { extractFingerprint } from "./features.js";
+import { seedStats } from "./calibration_corpus.js";
+const KEY_ENV = "MNEME_JANUS_KEY";
+const DEFAULT_KEY = "mneme-janus-v1";
+function keyOf() {
+    return process.env[KEY_ENV] ?? DEFAULT_KEY;
+}
+/** Euclidean distance between fingerprint and a vendor's per-feature means. */
+function distanceToCentroid(fp, stats) {
+    let sumSq = 0;
+    let count = 0;
+    for (const k of Object.keys(stats.features)) {
+        const v = fp[k];
+        if (typeof v !== "number" || !Number.isFinite(v))
+            continue;
+        const m = stats.features[k].mean;
+        const stdev = Math.max(stats.features[k].stdev, Math.abs(m) * 0.1, 1e-3);
+        // Normalized squared distance per feature
+        const z = (v - m) / stdev;
+        sumSq += z * z;
+        count++;
+    }
+    if (count === 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.sqrt(sumSq / count);
+}
+/**
+ * Locate which vendor cluster an observation belongs to.
+ * Defensive: empty stats → returns basin="unknown" with infinity distance.
+ */
+export function locateBasin(fingerprint) {
+    let stats;
+    try {
+        stats = seedStats();
+    }
+    catch {
+        return { basin: "unknown", basinDistance: Number.POSITIVE_INFINITY, secondNearest: null, margin: 0, allDistances: [] };
+    }
+    const distances = [];
+    for (const [vendor, s] of stats) {
+        distances.push({ vendor, distance: distanceToCentroid(fingerprint, s) });
+    }
+    distances.sort((a, b) => a.distance - b.distance);
+    if (distances.length === 0) {
+        return { basin: "unknown", basinDistance: Number.POSITIVE_INFINITY, secondNearest: null, margin: 0, allDistances: [] };
+    }
+    const nearest = distances[0];
+    const second = distances[1] ?? null;
+    const margin = second ? second.distance - nearest.distance : 0;
+    return {
+        basin: nearest.vendor,
+        basinDistance: nearest.distance,
+        secondNearest: second,
+        margin,
+        allDistances: distances,
+    };
+}
+/**
+ * Observe a fixture; return {fingerprint, basin}.
+ */
+export function observe(fixture) {
+    const fp = "multiline_commit_ratio" in fixture
+        ? fixture
+        : extractFingerprint(fixture);
+    const basin = locateBasin(fp);
+    return { fingerprint: fp, basin };
+}
+/**
+ * Walk a sequence of observations from the SAME session; surface
+ * cross-cluster transitions + an HMAC-signed verdict.
+ */
+export function detectIdentitySwap(observations, opts = {}) {
+    const minMargin = opts.minMargin ?? 0.5;
+    const transitions = [];
+    if (!Array.isArray(observations) || observations.length < 2) {
+        return signed({ observations: observations ?? [], transitions: [], swapDetected: false });
+    }
+    let prev = observations[0];
+    for (let i = 1; i < observations.length; i++) {
+        const cur = observations[i];
+        if (prev.basin.basin === cur.basin.basin) {
+            prev = cur;
+            continue;
+        }
+        // Only surface as a real swap when the new basin is clearly nearer.
+        if (cur.basin.margin < minMargin) {
+            prev = cur;
+            continue;
+        }
+        // Distance from CURRENT obs to PREVIOUS basin vs current basin
+        const prevBasinDistInCur = cur.basin.allDistances.find((d) => d.vendor === prev.basin.basin);
+        if (!prevBasinDistInCur || !Number.isFinite(prevBasinDistInCur.distance)) {
+            prev = cur;
+            continue;
+        }
+        const swapConfidence = prevBasinDistInCur.distance / Math.max(cur.basin.basinDistance, 1e-6);
+        transitions.push({
+            fromBasin: prev.basin.basin,
+            toBasin: cur.basin.basin,
+            fromDistance: prevBasinDistInCur.distance,
+            toDistance: cur.basin.basinDistance,
+            swapConfidence,
+            citation: `JANUS: identity swap detected — fingerprint crossed from ${prev.basin.basin} basin to ${cur.basin.basin} basin (swap confidence ${swapConfidence.toFixed(2)}x).`,
+        });
+        prev = cur;
+    }
+    return signed({ observations, transitions, swapDetected: transitions.length > 0 });
+}
+function signed(body) {
+    const hmac = createHmac("sha256", keyOf()).update(JSON.stringify({
+        transitions: body.transitions,
+        swapDetected: body.swapDetected,
+        obsCount: body.observations.length,
+    })).digest("hex");
+    return { ...body, hmac };
+}
+/** Verify a session-result's HMAC. */
+export function verifyJanusResult(r) {
+    if (!r || typeof r.hmac !== "string")
+        return false;
+    const expected = createHmac("sha256", keyOf()).update(JSON.stringify({
+        transitions: r.transitions,
+        swapDetected: r.swapDetected,
+        obsCount: r.observations.length,
+    })).digest("hex");
+    return expected === r.hmac;
+}
+//# sourceMappingURL=janus.js.map

package/dist/nemesis/janus.js.map

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

package/dist/nemesis/key_setup.d.ts

@@ -0,0 +1,65 @@
+/**
+ * v2.53.0 — HMAC KEY SETUP WIZARD + STRICT mode.
+ *
+ * Closes P0-1 from the v2.52 session audit: pre-v2.53 NEMESIS warned LOUD
+ * when falling back to the public default key, but didn't auto-fix it
+ * + didn't refuse to operate. Result: every developer who ignored the
+ * warning shipped HMAC receipts an attacker can forge.
+ *
+ * v2.53 protocol:
+ *   1. First-run wizard auto-generates a 32-byte random key + writes it
+ *      to .mneme/nemesis/hmac.key with 0o600 perms (owner-only).
+ *   2. MNEME_NEMESIS_STRICT=1 env var → key_management refuses to return
+ *      the default-insecure key (throws instead). For CI / production /
+ *      regulated environments.
+ *   3. Idempotent: re-running detects existing key + skips generation.
+ *
+ * Defensive: never throws on filesystem errors (best-effort), only the
+ * STRICT-mode refusal is intentional.
+ */
+export interface KeyWizardResult {
+    ok: boolean;
+    action: "generated-repo" | "generated-user" | "already-present" | "skipped" | "failed";
+    path?: string;
+    /** Length of the resolved key (or 0 on fail). */
+    keyLength: number;
+    reason: string;
+}
+export interface KeyWizardOpts {
+    repoRoot: string;
+    /** "repo" → write to <repoRoot>/.mneme/nemesis/hmac.key (default).
+     *  "user" → write to ~/.mneme/nemesis/hmac.key (cross-repo). */
+    target?: "repo" | "user";
+    /** Re-generate even if a key already exists. Default false. */
+    force?: boolean;
+    /** Don't write — only compute the would-be path + key length. */
+    dryRun?: boolean;
+}
+/**
+ * Run the key setup wizard. Idempotent; never overwrites an existing
+ * key unless force=true. Returns structured outcome.
+ */
+export declare function runKeyWizard(opts: KeyWizardOpts): KeyWizardResult;
+/**
+ * Check key file permissions (Unix only). Returns warning on world-readable
+ * files. On Windows, returns ok=true with note since chmod is a no-op.
+ */
+export declare function checkKeyPermissions(repoRoot: string): {
+    ok: boolean;
+    mode?: number;
+    reason: string;
+};
+/**
+ * STRICT MODE check: throws when the user is operating with a
+ * default-insecure HMAC key AND has opted into strict enforcement
+ * via MNEME_NEMESIS_STRICT=1. Call this from any code path that
+ * issues forensic-grade receipts (EU stamp / cli-activity / SIBYL).
+ *
+ * Non-strict mode: returns { ok: false, message } so caller can decide.
+ */
+export declare function strictKeyCheck(repoRoot: string): {
+    ok: boolean;
+    usingDefault: boolean;
+    message: string;
+};
+//# sourceMappingURL=key_setup.d.ts.map

package/dist/nemesis/key_setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key_setup.d.ts","sourceRoot":"","sources":["../../src/nemesis/key_setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;oEACgE;IAChE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAYD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAyDjE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAiBpG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiCxG"}

package/dist/nemesis/key_setup.js

@@ -0,0 +1,173 @@
+/**
+ * v2.53.0 — HMAC KEY SETUP WIZARD + STRICT mode.
+ *
+ * Closes P0-1 from the v2.52 session audit: pre-v2.53 NEMESIS warned LOUD
+ * when falling back to the public default key, but didn't auto-fix it
+ * + didn't refuse to operate. Result: every developer who ignored the
+ * warning shipped HMAC receipts an attacker can forge.
+ *
+ * v2.53 protocol:
+ *   1. First-run wizard auto-generates a 32-byte random key + writes it
+ *      to .mneme/nemesis/hmac.key with 0o600 perms (owner-only).
+ *   2. MNEME_NEMESIS_STRICT=1 env var → key_management refuses to return
+ *      the default-insecure key (throws instead). For CI / production /
+ *      regulated environments.
+ *   3. Idempotent: re-running detects existing key + skips generation.
+ *
+ * Defensive: never throws on filesystem errors (best-effort), only the
+ * STRICT-mode refusal is intentional.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+const REPO_KEY_REL = ".mneme/nemesis/hmac.key";
+const USER_KEY_REL = ".mneme/nemesis/hmac.key";
+function keyPath(opts) {
+    if (opts.target === "user")
+        return join(homedir(), USER_KEY_REL);
+    return join(opts.repoRoot, REPO_KEY_REL);
+}
+function envHasValidKey() {
+    const k = process.env["MNEME_NEMESIS_KEY"];
+    return typeof k === "string" && k.length >= 16;
+}
+/**
+ * Run the key setup wizard. Idempotent; never overwrites an existing
+ * key unless force=true. Returns structured outcome.
+ */
+export function runKeyWizard(opts) {
+    try {
+        if (envHasValidKey() && !opts.force) {
+            const env = process.env["MNEME_NEMESIS_KEY"];
+            return {
+                ok: true,
+                action: "skipped",
+                keyLength: env.length,
+                reason: "MNEME_NEMESIS_KEY already set — no file action needed",
+            };
+        }
+        const p = keyPath(opts);
+        if (existsSync(p) && !opts.force) {
+            try {
+                const k = readFileSync(p, "utf8").trim();
+                if (k.length >= 16) {
+                    return {
+                        ok: true,
+                        action: "already-present",
+                        path: p,
+                        keyLength: k.length,
+                        reason: `existing key at ${p} (${k.length} chars)`,
+                    };
+                }
+            }
+            catch { /* fall through to regenerate */ }
+        }
+        if (opts.dryRun) {
+            return {
+                ok: true,
+                action: opts.target === "user" ? "generated-user" : "generated-repo",
+                path: p,
+                keyLength: 64,
+                reason: `dry-run: would write a fresh 64-char hex key to ${p}`,
+            };
+        }
+        // Generate + write
+        const dir = p.replace(/[\/\\][^\/\\]+$/, "");
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch { /* ok */ }
+        const key = randomBytes(32).toString("hex");
+        writeFileSync(p, key + "\n", { mode: 0o600 });
+        // Best-effort chmod (Windows ignores)
+        try {
+            chmodSync(p, 0o600);
+        }
+        catch { /* */ }
+        return {
+            ok: true,
+            action: opts.target === "user" ? "generated-user" : "generated-repo",
+            path: p,
+            keyLength: key.length,
+            reason: `generated fresh 64-char hex key at ${p} (mode 0600)`,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            action: "failed",
+            keyLength: 0,
+            reason: `wizard failed: ${e.message}`,
+        };
+    }
+}
+/**
+ * Check key file permissions (Unix only). Returns warning on world-readable
+ * files. On Windows, returns ok=true with note since chmod is a no-op.
+ */
+export function checkKeyPermissions(repoRoot) {
+    const p = join(repoRoot, REPO_KEY_REL);
+    if (!existsSync(p))
+        return { ok: true, reason: "no key file present" };
+    try {
+        const s = statSync(p);
+        const mode = s.mode & 0o777;
+        if (process.platform === "win32") {
+            return { ok: true, mode, reason: "Windows: chmod is a no-op; key access controlled by NTFS ACLs" };
+        }
+        // Owner-only is the goal: 0o600
+        if (mode === 0o600 || mode === 0o400) {
+            return { ok: true, mode, reason: `mode ${mode.toString(8)} — owner-only (correct)` };
+        }
+        return { ok: false, mode, reason: `mode ${mode.toString(8)} is too permissive; should be 600 (owner read/write only)` };
+    }
+    catch (e) {
+        return { ok: false, reason: `stat failed: ${e.message}` };
+    }
+}
+/**
+ * STRICT MODE check: throws when the user is operating with a
+ * default-insecure HMAC key AND has opted into strict enforcement
+ * via MNEME_NEMESIS_STRICT=1. Call this from any code path that
+ * issues forensic-grade receipts (EU stamp / cli-activity / SIBYL).
+ *
+ * Non-strict mode: returns { ok: false, message } so caller can decide.
+ */
+export function strictKeyCheck(repoRoot) {
+    // Resolve via the same path key_management uses.
+    const env = process.env["MNEME_NEMESIS_KEY"];
+    if (typeof env === "string" && env.length >= 16) {
+        return { ok: true, usingDefault: false, message: "MNEME_NEMESIS_KEY env var set" };
+    }
+    const repo = join(repoRoot, REPO_KEY_REL);
+    if (existsSync(repo)) {
+        try {
+            const k = readFileSync(repo, "utf8").trim();
+            if (k.length >= 16)
+                return { ok: true, usingDefault: false, message: `repo key at ${repo}` };
+        }
+        catch { /* */ }
+    }
+    const user = join(homedir(), USER_KEY_REL);
+    if (existsSync(user)) {
+        try {
+            const k = readFileSync(user, "utf8").trim();
+            if (k.length >= 16)
+                return { ok: true, usingDefault: false, message: `user key at ${user}` };
+        }
+        catch { /* */ }
+    }
+    const strict = process.env["MNEME_NEMESIS_STRICT"] === "1";
+    if (strict) {
+        throw new Error("STRICT MODE: MNEME_NEMESIS_STRICT=1 set + no production key configured. " +
+            `Run: node -e "require('@mneme-ai/core').nemesis.runKeyWizard({repoRoot:'${repoRoot}'})" ` +
+            "OR set MNEME_NEMESIS_KEY env var (≥16 chars).");
+    }
+    return {
+        ok: false,
+        usingDefault: true,
+        message: "using default-insecure HMAC key — receipts are forgeable. Set MNEME_NEMESIS_STRICT=1 to enforce.",
+    };
+}
+//# sourceMappingURL=key_setup.js.map

package/dist/nemesis/key_setup.js.map

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

package/dist/nemesis/lethe.d.ts

@@ -0,0 +1,112 @@
+/**
+ * v2.54.0 — LETHE: GDPR forget primitive (Merkle exclusion proof).
+ *
+ * Greek mythology: river in Hades that erases memory.
+ *
+ * Problem: EU GDPR Art 17 (right to erasure) + AI-specific provisions
+ * require that personal data — including fingerprint-style behavioural
+ * markers — be REMOVABLE on request. But Mneme's HMAC chains are
+ * tamper-evident by design: removing rows breaks the chain.
+ *
+ * Solution (cryptographically rigorous, not just "delete"):
+ *   1. Build a Merkle tree over the chain rows.
+ *   2. To "forget" row R, REPLACE the row's leaf with `H("forgotten:" || nonce)`
+ *      where nonce is fresh per request.
+ *   3. Recompute the Merkle root from the modified leaves.
+ *   4. Issue a FORGET RECEIPT: signed proof tree showing
+ *      (a) the row WAS in the chain (by original leaf hash, kept ONLY as
+ *          the path to the root — never the content)
+ *      (b) the row is NOW erased (replacement leaf)
+ *      (c) the new Merkle root that subsequent verifiers can use
+ *      (d) timestamp + GDPR jurisdiction tag
+ *
+ * Verifiers downstream:
+ *   - Future readers see the new root + the FORGET ENVELOPE; they cannot
+ *     recover the original content (it was the only place stored).
+ *   - The exclusion proof is a few hundred bytes regardless of chain size.
+ *
+ * Composes: createHash + the existing HMAC-chained ledger pattern.
+ * Pure deterministic + defensive; never throws.
+ */
+export interface MerkleProofStep {
+    /** Sibling hash at this level. */
+    sibling: string;
+    /** Position of the current node relative to its sibling. */
+    position: "left" | "right";
+}
+export interface MerkleTree {
+    /** Root hash. */
+    root: string;
+    /** Leaf hashes (in input order). */
+    leaves: string[];
+    /** Total number of leaves. */
+    count: number;
+}
+/**
+ * Build a Merkle tree from a list of row contents. Odd-count layers
+ * duplicate the last element (standard Bitcoin-style construction).
+ */
+export declare function buildMerkleTree(rows: string[]): MerkleTree;
+/**
+ * Build an inclusion proof for the leaf at `index`.
+ * Returns the sibling path from the leaf up to (but not including) the root.
+ */
+export declare function buildInclusionProof(rows: string[], index: number): {
+    proof: MerkleProofStep[];
+    root: string;
+    leafHash: string;
+} | null;
+/** Verify an inclusion proof. Pure. */
+export declare function verifyInclusionProof(leafHash: string, proof: MerkleProofStep[], expectedRoot: string): boolean;
+export interface ForgetReceipt {
+    /** ISO-8601 timestamp of the forget request. */
+    at: string;
+    /** GDPR jurisdiction tag (EU/UK/etc) — for the audit trail. */
+    jurisdiction: string;
+    /** Source ledger identifier (e.g. "cli-activity.jsonl" / "drift-cursor.jsonl"). */
+    ledger: string;
+    /** Row index that was forgotten. */
+    forgottenIndex: number;
+    /** Inclusion proof THAT THE ROW WAS THERE (original leaf hash + path). */
+    originalLeafHash: string;
+    /** Replacement leaf hash. */
+    replacementLeafHash: string;
+    /** Merkle proof of inclusion of the original leaf in the ORIGINAL root. */
+    inclusionProof: MerkleProofStep[];
+    /** Original Merkle root (before erase). */
+    originalRoot: string;
+    /** New Merkle root (after erase). */
+    newRoot: string;
+    /** HMAC over the canonical receipt body. */
+    hmac: string;
+}
+export interface ForgetInput {
+    repoRoot: string;
+    ledgerRelative: string;
+    /** Which row to forget (0-based). */
+    rowIndex: number;
+    jurisdiction?: string;
+    /** Don't actually rewrite the ledger; only build the receipt. */
+    dryRun?: boolean;
+}
+export interface ForgetResult {
+    ok: boolean;
+    receipt?: ForgetReceipt;
+    newLedgerPath?: string;
+    backupPath?: string;
+    reason: string;
+}
+/**
+ * Read a JSONL ledger + perform GDPR forget on a specific row. Pure
+ * cryptographic operation; ledger rewrite + backup are best-effort.
+ */
+export declare function forgetRow(input: ForgetInput): ForgetResult;
+/** Verify a forget receipt cryptographically — does the inclusion proof
+ *  reconstruct the original root + does the HMAC match? Pure. */
+export declare function verifyForgetReceipt(receipt: ForgetReceipt): {
+    ok: boolean;
+    reason: string;
+};
+/** List all forget receipts in this repo. */
+export declare function listForgetReceipts(repoRoot: string): ForgetReceipt[];
+//# sourceMappingURL=lethe.d.ts.map

package/dist/nemesis/lethe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lethe.d.ts","sourceRoot":"","sources":["../../src/nemesis/lethe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAuBH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAiB1D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAsBtI;AAED,uCAAuC;AACvC,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,YAAY,EAAE,MAAM,GAC/D,OAAO,CAQT;AAMD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,cAAc,EAAE,eAAe,EAAE,CAAC;IAClC,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAqD1D;AAED;iEACiE;AACjE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQ3F;AAED,6CAA6C;AAC7C,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CASpE"}