@mneme-ai/sdk 2.55.0

package/dist/benchmark.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @mneme-ai/sdk/benchmark — built-in SDK-vs-CLI speedup proof.
+ *
+ * Wild feature: users can prove the claimed 30-80× speedup on their own
+ * hardware in one call. Compares N in-process SDK calls against the same
+ * N CLI subprocess calls + reports the ratio.
+ *
+ * Refuses to lie: if the SDK is slower (e.g. on a niche platform), it
+ * surfaces that too.
+ */
+export interface BenchmarkResult {
+    op: string;
+    iterations: number;
+    sdkMeanMs: number;
+    sdkTotalMs: number;
+    cliMeanMs: number;
+    cliTotalMs: number;
+    speedupRatio: number;
+    /** True when SDK strictly faster than CLI on average. */
+    sdkWins: boolean;
+}
+export interface BenchmarkOpts {
+    iterations?: number;
+    cliBin?: string;
+    /** Skip the CLI side (useful when CLI not built). */
+    skipCli?: boolean;
+}
+/** Bench EU stamp (fastest hot path; the one we promise <30ms). */
+export declare function benchEuStamp(opts?: BenchmarkOpts): Promise<BenchmarkResult>;
+/** Bench NEMESIS classify_calibrated. */
+export declare function benchClassify(opts?: BenchmarkOpts): Promise<BenchmarkResult>;
+/** Run the full bench suite. */
+export declare function vsCli(opts?: BenchmarkOpts): Promise<{
+    ok: boolean;
+    results: BenchmarkResult[];
+    averageSpeedup: number;
+    at: string;
+}>;
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../src/benchmark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAYD,mEAAmE;AACnE,wBAAsB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAmCrF;AAED,yCAAyC;AACzC,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkCtF;AAED,gCAAgC;AAChC,wBAAsB,KAAK,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC;IAC7D,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAeD"}

package/dist/benchmark.js

@@ -0,0 +1,115 @@
+/**
+ * @mneme-ai/sdk/benchmark — built-in SDK-vs-CLI speedup proof.
+ *
+ * Wild feature: users can prove the claimed 30-80× speedup on their own
+ * hardware in one call. Compares N in-process SDK calls against the same
+ * N CLI subprocess calls + reports the ratio.
+ *
+ * Refuses to lie: if the SDK is slower (e.g. on a niche platform), it
+ * surfaces that too.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import * as core from "@mneme-ai/core";
+function findCliBin() {
+    const candidates = [
+        resolve(process.cwd(), "packages/cli/bin/mneme.js"),
+        resolve(process.cwd(), "node_modules/mneme-ai/bin/mneme.js"),
+        resolve(process.cwd(), "node_modules/.bin/mneme"),
+    ];
+    for (const c of candidates)
+        if (existsSync(c))
+            return c;
+    return null;
+}
+/** Bench EU stamp (fastest hot path; the one we promise <30ms). */
+export async function benchEuStamp(opts = {}) {
+    const iter = opts.iterations ?? 20;
+    const input = { message: "bench commit", vendor: "claude-code", confidence: 0.9 };
+    // SDK warm
+    core.nemesis.stampArticle50(input);
+    const sdk0 = performance.now();
+    for (let i = 0; i < iter; i++)
+        core.nemesis.stampArticle50({ ...input, message: `msg ${i}` });
+    const sdkTotal = performance.now() - sdk0;
+    let cliTotal = 0;
+    let cliMean = 0;
+    if (!opts.skipCli) {
+        const cli = opts.cliBin ?? findCliBin();
+        if (cli && existsSync(cli)) {
+            const cli0 = performance.now();
+            for (let i = 0; i < iter; i++) {
+                spawnSync(process.execPath, [cli, "nemesis", "eu_stamp", "--message", `msg ${i}`, "--vendor", "claude-code"], { encoding: "utf8", timeout: 5000 });
+            }
+            cliTotal = performance.now() - cli0;
+            cliMean = cliTotal / iter;
+        }
+    }
+    const sdkMean = sdkTotal / iter;
+    const speedup = cliMean > 0 ? cliMean / sdkMean : 0;
+    return {
+        op: "nemesis.eu_stamp",
+        iterations: iter,
+        sdkMeanMs: +sdkMean.toFixed(2),
+        sdkTotalMs: +sdkTotal.toFixed(2),
+        cliMeanMs: +cliMean.toFixed(2),
+        cliTotalMs: +cliTotal.toFixed(2),
+        speedupRatio: +speedup.toFixed(1),
+        sdkWins: speedup > 1.5,
+    };
+}
+/** Bench NEMESIS classify_calibrated. */
+export async function benchClassify(opts = {}) {
+    const iter = opts.iterations ?? 20;
+    const fx = { diff: "+const x = 1;\n+function foo() { return x; }\n", prDescription: "## Changes\n- a\n", commitMessages: ["x"] };
+    const fp = core.nemesis.extractFingerprint(fx);
+    core.nemesis.classifyAgentCalibrated(fp);
+    const sdk0 = performance.now();
+    for (let i = 0; i < iter; i++)
+        core.nemesis.classifyAgentCalibrated(fp);
+    const sdkTotal = performance.now() - sdk0;
+    let cliTotal = 0, cliMean = 0;
+    if (!opts.skipCli) {
+        const cli = opts.cliBin ?? findCliBin();
+        if (cli && existsSync(cli)) {
+            const cli0 = performance.now();
+            const payload = JSON.stringify(fx);
+            for (let i = 0; i < iter; i++) {
+                spawnSync(process.execPath, [cli, "nemesis", "classify", "--stdin"], { encoding: "utf8", input: payload, timeout: 8000 });
+            }
+            cliTotal = performance.now() - cli0;
+            cliMean = cliTotal / iter;
+        }
+    }
+    const sdkMean = sdkTotal / iter;
+    const speedup = cliMean > 0 ? cliMean / sdkMean : 0;
+    return {
+        op: "nemesis.classify",
+        iterations: iter,
+        sdkMeanMs: +sdkMean.toFixed(2),
+        sdkTotalMs: +sdkTotal.toFixed(2),
+        cliMeanMs: +cliMean.toFixed(2),
+        cliTotalMs: +cliTotal.toFixed(2),
+        speedupRatio: +speedup.toFixed(1),
+        sdkWins: speedup > 1.5,
+    };
+}
+/** Run the full bench suite. */
+export async function vsCli(opts = {}) {
+    const results = [
+        await benchEuStamp(opts),
+        await benchClassify(opts),
+    ];
+    const avg = results
+        .filter((r) => r.speedupRatio > 0)
+        .reduce((s, r) => s + r.speedupRatio, 0)
+        / Math.max(1, results.filter((r) => r.speedupRatio > 0).length);
+    return {
+        ok: results.every((r) => r.sdkWins || r.cliMeanMs === 0),
+        results,
+        averageSpeedup: +avg.toFixed(1),
+        at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=benchmark.js.map

package/dist/benchmark.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @mneme-ai/sdk — async-iterator event bus.
+ *
+ * Wild feature: every primitive can stream EVENTS as the work happens
+ * (tournament rounds, drift detections, audit findings, etc) — no SDK
+ * I've seen does this. Pattern:
+ *
+ *   for await (const ev of mneme.tournament.events()) {
+ *     console.log(ev.round, ev.caught);
+ *   }
+ *
+ * Implemented as a tiny in-process pub/sub with AbortSignal support.
+ * No external dep; zero overhead when nobody subscribes.
+ */
+export type MnemeEventKind = "tournament.round" | "tournament.complete" | "molt.detected" | "swap.detected" | "stamp.issued" | "verify.complete" | "lethe.forgotten" | "gavel.packed" | "nimbus.published" | "perf.budget.exceeded";
+export interface MnemeEvent<T = unknown> {
+    kind: MnemeEventKind;
+    at: number;
+    data: T;
+}
+type Listener<T = unknown> = (ev: MnemeEvent<T>) => void;
+declare class EventBus {
+    private listeners;
+    private globalListeners;
+    on(kind: MnemeEventKind, listener: Listener): () => void;
+    onAny(listener: Listener): () => void;
+    emit<T>(ev: MnemeEvent<T>): void;
+    listenerCount(): number;
+}
+export declare function getEventBus(): EventBus;
+/**
+ * Get an async iterator over events matching `kinds` (all kinds if omitted).
+ * Stops when AbortSignal aborts.
+ *
+ *   const ac = new AbortController();
+ *   for await (const ev of subscribeEvents(["tournament.round"], { signal: ac.signal })) {
+ *     if (ev.data.round >= 10) ac.abort();
+ *   }
+ */
+export declare function subscribeEvents(kinds?: MnemeEventKind[], opts?: {
+    signal?: AbortSignal;
+}): AsyncIterableIterator<MnemeEvent>;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,eAAe,GACf,eAAe,GACf,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,cAAc,GACd,kBAAkB,GAClB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,CAAC,CAAC;CACT;AAED,KAAK,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEzD,cAAM,QAAQ;IACZ,OAAO,CAAC,SAAS,CAAiD;IAClE,OAAO,CAAC,eAAe,CAA4B;IAEnD,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI;IAMxD,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI;IAKrC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAUhC,aAAa,IAAI,MAAM;CAKxB;AAGD,wBAAgB,WAAW,IAAI,QAAQ,CAAuB;AAE9D;;;;;;;;GAQG;AACH,wBAAuB,eAAe,CACpC,KAAK,CAAC,EAAE,cAAc,EAAE,EACxB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAClC,qBAAqB,CAAC,UAAU,CAAC,CA4CnC"}

package/dist/events.js

@@ -0,0 +1,107 @@
+/**
+ * @mneme-ai/sdk — async-iterator event bus.
+ *
+ * Wild feature: every primitive can stream EVENTS as the work happens
+ * (tournament rounds, drift detections, audit findings, etc) — no SDK
+ * I've seen does this. Pattern:
+ *
+ *   for await (const ev of mneme.tournament.events()) {
+ *     console.log(ev.round, ev.caught);
+ *   }
+ *
+ * Implemented as a tiny in-process pub/sub with AbortSignal support.
+ * No external dep; zero overhead when nobody subscribes.
+ */
+class EventBus {
+    listeners = new Map();
+    globalListeners = new Set();
+    on(kind, listener) {
+        if (!this.listeners.has(kind))
+            this.listeners.set(kind, new Set());
+        this.listeners.get(kind).add(listener);
+        return () => this.listeners.get(kind)?.delete(listener);
+    }
+    onAny(listener) {
+        this.globalListeners.add(listener);
+        return () => this.globalListeners.delete(listener);
+    }
+    emit(ev) {
+        const ls = this.listeners.get(ev.kind);
+        if (ls)
+            for (const l of ls) {
+                try {
+                    l(ev);
+                }
+                catch { /* swallow — never let a bad subscriber kill the bus */ }
+            }
+        for (const l of this.globalListeners) {
+            try {
+                l(ev);
+            }
+            catch { /* */ }
+        }
+    }
+    listenerCount() {
+        let n = this.globalListeners.size;
+        for (const s of this.listeners.values())
+            n += s.size;
+        return n;
+    }
+}
+const _globalBus = new EventBus();
+export function getEventBus() { return _globalBus; }
+/**
+ * Get an async iterator over events matching `kinds` (all kinds if omitted).
+ * Stops when AbortSignal aborts.
+ *
+ *   const ac = new AbortController();
+ *   for await (const ev of subscribeEvents(["tournament.round"], { signal: ac.signal })) {
+ *     if (ev.data.round >= 10) ac.abort();
+ *   }
+ */
+export async function* subscribeEvents(kinds, opts = {}) {
+    const bus = getEventBus();
+    const queue = [];
+    let resolveNext = null;
+    let aborted = false;
+    const off = kinds && kinds.length > 0
+        ? kinds.map((k) => bus.on(k, (ev) => push(ev)))
+        : [bus.onAny((ev) => push(ev))];
+    function push(ev) {
+        if (resolveNext) {
+            resolveNext({ value: ev, done: false });
+            resolveNext = null;
+        }
+        else {
+            queue.push(ev);
+        }
+    }
+    if (opts.signal) {
+        opts.signal.addEventListener("abort", () => {
+            aborted = true;
+            if (resolveNext) {
+                resolveNext({ value: undefined, done: true });
+                resolveNext = null;
+            }
+        });
+    }
+    try {
+        while (!aborted) {
+            if (queue.length > 0) {
+                yield queue.shift();
+                continue;
+            }
+            const next = await new Promise((resolve) => {
+                resolveNext = resolve;
+            });
+            if (next.done)
+                break;
+            yield next.value;
+        }
+    }
+    finally {
+        for (const fn of off)
+            fn();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @mneme-ai/sdk — World-class premium SDK for Mneme.
+ *
+ * Native, in-process API for embedding Mneme primitives in any AI vendor /
+ * IDE plugin / agent runtime. 30-80× faster than the CLI subprocess.
+ *
+ * Quick start:
+ *
+ *   import { createMneme } from "@mneme-ai/sdk";
+ *
+ *   const mneme = createMneme();                  // uses cwd/.mneme + env keys
+ *   const v = await mneme.verify`Mneme is a CLI tool`;
+ *   console.log(v.data?.verdict);  // → "FUSION"
+ *
+ *   const fp = mneme.nemesis.fingerprint({ diff, prDescription, commitMessages });
+ *   const id = mneme.nemesis.classify(fp.data);
+ *   const stamp = mneme.nemesis.stamp({ message: "fix bug", vendor: "claude-code" });
+ *
+ *   for await (const ev of mneme.events(["stamp.issued"])) {
+ *     telemetry.recordStamp(ev.data);
+ *   }
+ *
+ *   const bench = await mneme.benchmark.vsCli();
+ *   console.log(`SDK averages ${bench.averageSpeedup}× faster than CLI`);
+ */
+import { NemesisSdk, type MnemeInstanceOpts } from "./nemesis.js";
+import { verify as verifyFn, verifyTagged } from "./verify.js";
+import * as truth from "./truth.js";
+import * as benchmark from "./benchmark.js";
+import { type MnemeEventKind, type MnemeEvent } from "./events.js";
+export * from "./types.js";
+export * from "./lock.js";
+export * from "./events.js";
+export type { MnemeInstanceOpts } from "./nemesis.js";
+export { NemesisSdk } from "./nemesis.js";
+export { verify, verifyTagged, type VerifyOpts, type VerifyResult } from "./verify.js";
+export { runProbe, runAllProbes, listProbes } from "./truth.js";
+export { vsCli as benchVsCli, benchEuStamp, benchClassify, type BenchmarkResult } from "./benchmark.js";
+/**
+ * Tagged-template-literal compatible verify dispatcher.
+ *
+ * Calling shape:
+ *   - `mneme.verify("claim string", opts?)` — plain call
+ *   - `mneme.verify\`Mneme is a CLI tool\`` — tagged template
+ */
+interface VerifyDispatcher {
+    (claim: string, opts?: Parameters<typeof verifyFn>[1]): ReturnType<typeof verifyFn>;
+    (strings: TemplateStringsArray, ...subs: unknown[]): ReturnType<typeof verifyTagged>;
+}
+export interface MnemeSdk {
+    /** NEMESIS engine surface (typed + in-process). */
+    nemesis: NemesisSdk;
+    /** Tagged-template-friendly verify. */
+    verify: VerifyDispatcher;
+    /** TRUTH GATE in-process probe runner. */
+    truth: typeof truth;
+    /** Built-in SDK-vs-CLI benchmark. */
+    benchmark: typeof benchmark;
+    /** Async-iterator event stream (kinds = [] means all). */
+    events: (kinds?: MnemeEventKind[]) => AsyncIterableIterator<MnemeEvent>;
+    /** The opts the instance was created with. */
+    readonly opts: MnemeInstanceOpts;
+    /** Version of the SDK runtime. */
+    readonly version: string;
+}
+/**
+ * Create a Mneme SDK instance. Returns a stable object — every call to
+ * createMneme() with the same opts returns equivalent state but
+ * independent ledger writers (use for multi-tenant tests).
+ */
+export declare function createMneme(opts?: MnemeInstanceOpts): MnemeSdk;
+/** SDK metadata for telemetry / about. */
+export declare const SDK_VERSION = "2.55.0";
+export declare const SDK_DESCRIPTION = "World-class premium in-process SDK for Mneme \u2014 30-80\u00D7 faster than CLI subprocess.";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEpF,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAE5B,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAExG;;;;;;GAMG;AACH,UAAU,gBAAgB;IACxB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;IACpF,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;CACtF;AAYD,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,0CAA0C;IAC1C,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,qCAAqC;IACrC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,cAAc,EAAE,KAAK,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACxE,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,iBAAsB,GAAG,QAAQ,CAqBlE;AAED,0CAA0C;AAC1C,eAAO,MAAM,WAAW,WAAW,CAAC;AACpC,eAAO,MAAM,eAAe,gGAAsF,CAAC"}

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * @mneme-ai/sdk — World-class premium SDK for Mneme.
+ *
+ * Native, in-process API for embedding Mneme primitives in any AI vendor /
+ * IDE plugin / agent runtime. 30-80× faster than the CLI subprocess.
+ *
+ * Quick start:
+ *
+ *   import { createMneme } from "@mneme-ai/sdk";
+ *
+ *   const mneme = createMneme();                  // uses cwd/.mneme + env keys
+ *   const v = await mneme.verify`Mneme is a CLI tool`;
+ *   console.log(v.data?.verdict);  // → "FUSION"
+ *
+ *   const fp = mneme.nemesis.fingerprint({ diff, prDescription, commitMessages });
+ *   const id = mneme.nemesis.classify(fp.data);
+ *   const stamp = mneme.nemesis.stamp({ message: "fix bug", vendor: "claude-code" });
+ *
+ *   for await (const ev of mneme.events(["stamp.issued"])) {
+ *     telemetry.recordStamp(ev.data);
+ *   }
+ *
+ *   const bench = await mneme.benchmark.vsCli();
+ *   console.log(`SDK averages ${bench.averageSpeedup}× faster than CLI`);
+ */
+import { NemesisSdk } from "./nemesis.js";
+import { verify as verifyFn, verifyTagged } from "./verify.js";
+import * as truth from "./truth.js";
+import * as benchmark from "./benchmark.js";
+import { subscribeEvents } from "./events.js";
+export * from "./types.js";
+export * from "./lock.js";
+export * from "./events.js";
+export { NemesisSdk } from "./nemesis.js";
+export { verify, verifyTagged } from "./verify.js";
+export { runProbe, runAllProbes, listProbes } from "./truth.js";
+export { vsCli as benchVsCli, benchEuStamp, benchClassify } from "./benchmark.js";
+function buildVerifyDispatcher() {
+    const dispatcher = ((firstArg, ...rest) => {
+        if (Array.isArray(firstArg) && "raw" in firstArg) {
+            return verifyTagged(firstArg, ...rest);
+        }
+        return verifyFn(firstArg, rest[0]);
+    });
+    return dispatcher;
+}
+/**
+ * Create a Mneme SDK instance. Returns a stable object — every call to
+ * createMneme() with the same opts returns equivalent state but
+ * independent ledger writers (use for multi-tenant tests).
+ */
+export function createMneme(opts = {}) {
+    // STRICT mode mirroring
+    if (opts.strict) {
+        if (!opts.hmacKey && !process.env["MNEME_NEMESIS_KEY"]) {
+            throw new Error("createMneme({ strict: true }) requires opts.hmacKey OR MNEME_NEMESIS_KEY env");
+        }
+    }
+    // If hmacKey provided inline, inject into env for the in-process consumers
+    if (opts.hmacKey && !process.env["MNEME_NEMESIS_KEY"]) {
+        process.env["MNEME_NEMESIS_KEY"] = opts.hmacKey;
+    }
+    const nemesis = new NemesisSdk(opts);
+    return {
+        nemesis,
+        verify: buildVerifyDispatcher(),
+        truth,
+        benchmark,
+        events: (kinds) => subscribeEvents(kinds),
+        opts: Object.freeze({ ...opts }),
+        version: "2.55.0",
+    };
+}
+/** SDK metadata for telemetry / about. */
+export const SDK_VERSION = "2.55.0";
+export const SDK_DESCRIPTION = "World-class premium in-process SDK for Mneme — 30-80× faster than CLI subprocess.";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAwC,MAAM,aAAa,CAAC;AAEpF,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAsC,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,YAAY,EAAE,aAAa,EAAwB,MAAM,gBAAgB,CAAC;AAcxG,SAAS,qBAAqB;IAC5B,MAAM,UAAU,GAAG,CAAC,CAAC,QAAuC,EAAE,GAAG,IAAe,EAAE,EAAE;QAClF,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAK,QAAiC,EAAE,CAAC;YAC3E,OAAO,YAAY,CAAC,QAAgC,EAAE,GAAG,IAAI,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,QAAQ,CAAC,QAAkB,EAAE,IAAI,CAAC,CAAC,CAA+C,CAAC,CAAC;IAC7F,CAAC,CAAqB,CAAC;IACvB,OAAO,UAAU,CAAC;AACpB,CAAC;AAmBD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA0B,EAAE;IACtD,wBAAwB;IACxB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,2EAA2E;IAC3E,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO;QACL,OAAO;QACP,MAAM,EAAE,qBAAqB,EAAE;QAC/B,KAAK;QACL,SAAS;QACT,MAAM,EAAE,CAAC,KAAwB,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC;QAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,QAAQ;KAClB,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,mFAAmF,CAAC"}

package/dist/lock.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @mneme-ai/sdk file-lock adapter.
+ *
+ * Fixes the race condition the user identified:
+ *   "CLI mneme verify ... + Cursor SDK writing HMAC chain simultaneously
+ *    → race in writing .mneme/cli-activity.jsonl"
+ *
+ * Strategy: simple advisory lock via `.lock` sentinel file with PID +
+ * stale-detection. No external dependency (no proper-lockfile import) —
+ * stays compatible with bundler tree-shake + works in container/serverless.
+ *
+ * Pure deterministic + defensive; never throws.
+ */
+export interface LockResult {
+    acquired: boolean;
+    /** The lock file path (for telemetry / debug). */
+    lockPath: string;
+    /** When the lock was acquired (or last detected to be held). */
+    at: number;
+    /** PID holding the lock (or null on acquire failure). */
+    holderPid?: number;
+    reason?: string;
+}
+/**
+ * Try to acquire an advisory lock on a target file. Non-blocking: returns
+ * { acquired: false } immediately on failure.
+ *
+ * Caller MUST call releaseLock when done.
+ */
+export declare function acquireLock(targetPath: string): LockResult;
+export declare function releaseLock(lockResult: Pick<LockResult, "lockPath" | "acquired">): void;
+/**
+ * Run a critical section under the lock. Releases the lock even when fn
+ * throws. Returns { acquired: false } envelope when the lock could not
+ * be acquired (caller decides whether to retry).
+ */
+export declare function withLock<T>(targetPath: string, fn: () => T | Promise<T>, opts?: {
+    retries?: number;
+    retryDelayMs?: number;
+}): Promise<{
+    ok: boolean;
+    data?: T;
+    reason?: string;
+}>;
+/** Diagnostic: check if a lock currently exists + is fresh. */
+export declare function isLocked(targetPath: string): {
+    locked: boolean;
+    holderPid?: number;
+    ageMs?: number;
+};
+/** Test-only: lockPath getter. */
+export declare function __lockPathForTest(targetPath: string): string;
+/**
+ * Wrap a function so that every call serialises through the lock for
+ * a given path. Useful for wrapping ledger writers transparently.
+ */
+export declare function serializeOnLock<Args extends unknown[], R>(lockTarget: string, fn: (...a: Args) => R | Promise<R>): (...a: Args) => Promise<{
+    ok: boolean;
+    data?: R;
+    reason?: string;
+}>;
+export declare const STALE_LOCK_MS = 5000;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAoC1D;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC,GAAG,IAAI,CAGvF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBrD;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAWpG;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACvD,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACjC,CAAC,GAAG,CAAC,EAAE,IAAI,KAAK,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAErE;AAED,eAAO,MAAM,aAAa,OAAW,CAAC"}