@mneme-ai/core 2.21.8-lite → 2.22.0-lite

package/dist/companion/companion.test.d.ts

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

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

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

package/dist/companion/companion.test.js

@@ -0,0 +1,215 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { contractFor, findContract, formatContract, parseArgSchema, validateArgs, dryRun, stageCommit, applyCommit, predictNext, formatStoryline, computeOutcomeStats, commonMistakes, companionFor, formatCompanion, companionableCoverage, listCompanionable, } from "./index.js";
+import { dropPheromone } from "../atlas/pheromone.js";
+const SAMPLE_VERIFY = { command: "mneme verify-self --score", since: "2.21.4", group: "trust", what: "🔒 Emit ONE NUMBER 0-100 trust score.", when: "CI gate." };
+const SAMPLE_DESTRUCTIVE = { command: "mneme mortuary fire", since: "2.21.2", group: "mortuary", what: "⚱️ Force the dead-man switch to fire NOW and generate all encrypted bundles.", when: "Testing." };
+const SAMPLE_NETWORK = { command: "mneme apoptosis federation-push", since: "2.21.0", group: "apoptosis_network", what: "Push the local apoptosis corpus to a peer via HMAC-signed bundle.", when: "Periodic federation." };
+describe("companion (v2.22.0)", () => {
+    let repo;
+    beforeEach(() => { repo = mkdtempSync(join(tmpdir(), "mneme-companion-")); });
+    afterEach(() => { try {
+        rmSync(repo, { recursive: true, force: true });
+    }
+    catch { /* */ } });
+    // ─── CONTRACT ──────────────────────────────────────────────────────
+    describe("contract derivation", () => {
+        it("read-only verb gets DEFCON 5", () => {
+            const c = contractFor(SAMPLE_VERIFY);
+            expect(c.defcon).toBe(5);
+            expect(c.readOnly).toBe(true);
+            expect(c.idempotency).toBe("read-only");
+        });
+        it("destructive verb gets DEFCON 1 or 2", () => {
+            const c = contractFor(SAMPLE_DESTRUCTIVE);
+            expect([1, 2]).toContain(c.defcon);
+            expect(c.readOnly).toBe(false);
+        });
+        it("network verb sets reachesNetwork", () => {
+            const c = contractFor(SAMPLE_NETWORK);
+            expect(c.reachesNetwork).toBe(true);
+        });
+        it("findContract resolves real catalog verb", () => {
+            const c = findContract("mneme verify-self --score");
+            expect(c?.verb).toContain("verify-self");
+        });
+        it("findContract returns null on unknown", () => {
+            expect(findContract("mneme totally-not-a-verb-xyz")).toBeNull();
+        });
+        it("formatContract includes DEFCON badge + summary", () => {
+            const out = formatContract(contractFor(SAMPLE_VERIFY));
+            expect(out).toContain("CONTRACT");
+            expect(out).toContain("DEFCON");
+            expect(out).toContain("read-only");
+        });
+    });
+    // ─── AUTOSPEC ──────────────────────────────────────────────────────
+    describe("autospec arg schema", () => {
+        it("parseArgSchema picks up required + optional positionals", () => {
+            const s = parseArgSchema("mneme some <required> [optional]");
+            expect(s.positional).toHaveLength(2);
+            expect(s.positional[0].required).toBe(true);
+            expect(s.positional[1].required).toBe(false);
+        });
+        it("variadic positional captured", () => {
+            const s = parseArgSchema("mneme do <words...>");
+            expect(s.positional[0].variadic).toBe(true);
+        });
+        it("--flag with value vs without value", () => {
+            const s = parseArgSchema("mneme x --vendor <v> --json");
+            expect(s.options.vendor?.type).toBe("string");
+            expect(s.options.vendor?.required).toBe(true);
+            expect(s.options.json?.type).toBe("boolean");
+        });
+        it("validateArgs rejects missing required positional", () => {
+            const s = parseArgSchema("mneme x <required>");
+            const r = validateArgs(s, { positional: [] });
+            expect(r.ok).toBe(false);
+            expect(r.errors[0]?.field).toBe("positional");
+        });
+        it("validateArgs accepts complete args", () => {
+            const s = parseArgSchema("mneme x <name> --vendor <v>");
+            const r = validateArgs(s, { positional: ["alice"], options: { vendor: "claude" } });
+            expect(r.ok).toBe(true);
+        });
+        it("validateArgs flags missing required option", () => {
+            const s = parseArgSchema("mneme x --vendor <v>");
+            const r = validateArgs(s, { positional: [], options: {} });
+            expect(r.ok).toBe(false);
+            expect(r.errors[0]?.field).toContain("vendor");
+        });
+    });
+    // ─── DOPPELGANGER ──────────────────────────────────────────────────
+    describe("doppelganger (copy-on-write dry-run)", () => {
+        it("dryRun returns no fileEffects when the simulator does nothing", async () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            writeFileSync(join(repo, ".mneme/a.json"), "{}");
+            const r = await dryRun(repo, () => { });
+            expect(r.fileEffects).toEqual([]);
+            expect(r.exitCode).toBe(0);
+        });
+        it("dryRun captures added file in shadow", async () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            const r = await dryRun(repo, (shadow) => {
+                writeFileSync(join(shadow, ".mneme/b.json"), "{}");
+            });
+            expect(r.fileEffects.some((e) => e.kind === "added" && e.path === ".mneme/b.json")).toBe(true);
+        });
+        it("dryRun captures changed file", async () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            writeFileSync(join(repo, ".mneme/c.json"), "{}");
+            const r = await dryRun(repo, (shadow) => {
+                writeFileSync(join(shadow, ".mneme/c.json"), "{\"k\":1}");
+            });
+            expect(r.fileEffects.some((e) => e.kind === "changed" && e.path === ".mneme/c.json")).toBe(true);
+        });
+        it("dryRun exit code captures verb error", async () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            const r = await dryRun(repo, () => { throw Object.assign(new Error("boom"), { code: 7 }); });
+            expect(r.exitCode).toBe(7);
+            expect(r.stderrSample).toContain("boom");
+        });
+        it("known network use → leakage=possible", async () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            const r = await dryRun(repo, () => { }, { knownNetworkUse: true });
+            expect(r.leakage).toBe("possible");
+        });
+        it("stageCommit + applyCommit round-trip writes files into repo", () => {
+            mkdirSync(join(repo, ".mneme"), { recursive: true });
+            const stage = stageCommit(repo);
+            mkdirSync(join(stage.stagePath, ".mneme"), { recursive: true });
+            writeFileSync(join(stage.stagePath, ".mneme/staged.json"), JSON.stringify({ committed: true }));
+            applyCommit(stage.stagePath, repo);
+            const out = require("node:fs").readFileSync(join(repo, ".mneme/staged.json"), "utf8");
+            expect(JSON.parse(out).committed).toBe(true);
+        });
+        it("stageCommit.rollback removes staged files", () => {
+            const stage = stageCommit(repo);
+            writeFileSync(join(stage.stagePath, "x"), "");
+            stage.rollback();
+            expect(require("node:fs").existsSync(stage.stagePath)).toBe(false);
+        });
+    });
+    // ─── STORYLINE ─────────────────────────────────────────────────────
+    describe("storyline (Markov over pheromone)", () => {
+        it("predictNext + predictPrior work after dropping pheromones in sequence", () => {
+            dropPheromone(repo, { verb: "mneme earthquake probe" });
+            dropPheromone(repo, { verb: "mneme earthquake drift" });
+            dropPheromone(repo, { verb: "mneme earthquake probe" });
+            dropPheromone(repo, { verb: "mneme earthquake drift" });
+            const next = predictNext(repo, "mneme earthquake probe");
+            expect(next.length).toBeGreaterThan(0);
+            expect(next[0].to).toContain("earthquake drift");
+        });
+        it("returns [] when no pheromone data yet", () => {
+            expect(predictNext(repo, "mneme whatever")).toEqual([]);
+        });
+        it("formatStoryline handles empty + populated cases", () => {
+            expect(formatStoryline("mneme x", [], [])).toContain("STORYLINE");
+            expect(formatStoryline("mneme x", [], [])).toContain("no data yet");
+        });
+    });
+    // ─── LEARN LOOP ────────────────────────────────────────────────────
+    describe("learn loop", () => {
+        it("computeOutcomeStats counts success vs failure", () => {
+            dropPheromone(repo, { verb: "mneme x", outcome: "success" });
+            dropPheromone(repo, { verb: "mneme x", outcome: "success" });
+            dropPheromone(repo, { verb: "mneme x", outcome: "failure" });
+            const s = computeOutcomeStats(repo, "mneme x");
+            expect(s.successes).toBe(2);
+            expect(s.failures).toBe(1);
+            expect(s.successRate).toBeCloseTo(2 / 3, 2);
+        });
+        it("commonMistakes surfaces recent-failure-cluster when recent rate < 60%", () => {
+            for (let i = 0; i < 5; i++)
+                dropPheromone(repo, { verb: "mneme y", outcome: "failure" });
+            dropPheromone(repo, { verb: "mneme y", outcome: "success" });
+            const m = commonMistakes(repo, "mneme y");
+            expect(m.length).toBeGreaterThan(0);
+            expect(m[0].pattern).toBe("recent-failure-cluster");
+        });
+        it("commonMistakes returns [] when no failures recorded", () => {
+            dropPheromone(repo, { verb: "mneme z", outcome: "success" });
+            expect(commonMistakes(repo, "mneme z")).toEqual([]);
+        });
+    });
+    // ─── COMPOSED COMPANION ────────────────────────────────────────────
+    describe("companionFor composed view", () => {
+        it("returns a Companion for a known catalog verb", () => {
+            const c = companionFor("mneme verify-self --score", { repoRoot: repo });
+            expect(c?.verb).toContain("verify-self");
+            expect(c?.contract.readOnly).toBe(true);
+            expect(c?.argSchema).toBeDefined();
+        });
+        it("hasLiveData=false on fresh repo; true after pheromone hit", () => {
+            const a = companionFor("mneme verify-self --score", { repoRoot: repo });
+            expect(a?.hasLiveData).toBe(false);
+            dropPheromone(repo, { verb: "mneme verify-self --score" });
+            const b = companionFor("mneme verify-self --score", { repoRoot: repo });
+            expect(b?.hasLiveData).toBe(true);
+        });
+        it("formatCompanion includes all 5 sections", () => {
+            const out = formatCompanion(companionFor("mneme verify-self --score", { repoRoot: repo }));
+            expect(out).toContain("CONTRACT");
+            expect(out).toContain("ARG SCHEMA");
+            expect(out).toContain("STORYLINE");
+            expect(out).toContain("OUTCOME STATS");
+            expect(out).toContain("COMMON MISTAKES");
+        });
+        it("listCompanionable returns the whole catalog sorted", () => {
+            const list = listCompanionable();
+            expect(list.length).toBeGreaterThan(50);
+            const sorted = [...list].sort();
+            expect(list).toEqual(sorted);
+        });
+        it("companionableCoverage reports contract + autospec coverage", () => {
+            const cov = companionableCoverage(repo);
+            expect(cov.total).toBeGreaterThan(50);
+            expect(cov.coverageContract).toBeGreaterThan(0.9);
+            expect(cov.coverageAutospec).toBeGreaterThan(0.9);
+        });
+    });
+});
+//# sourceMappingURL=companion.test.js.map

package/dist/companion/companion.test.js.map

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

package/dist/companion/contract.d.ts

@@ -0,0 +1,56 @@
+/**
+ * v2.22.0 — COMPANION · CONTRACT.
+ *
+ * Each verb in the catalog gets a derived contract: preconditions,
+ * postconditions, side-effects, idempotency level, DEFCON impact.
+ * The contract is auto-derived from the manifest entry first, then
+ * optionally overridden by a hand-authored file at
+ * `packages/core/src/companion/overrides/<verb-slug>.json`.
+ *
+ * Why this lives apart from `agent_manifest.ts`:
+ *   - manifest is the single-line "what + when" surface AI agents
+ *     read by default;
+ *   - contract is the deep structured form AI agents read BEFORE
+ *     invoking a verb the first time. They serve different audiences.
+ */
+import { type ManifestCommand } from "../agent_manifest.js";
+export type DefconLevel = 1 | 2 | 3 | 4 | 5;
+export type IdempotencyLevel = "read-only" | "idempotent" | "additive" | "destructive";
+export interface VerbContract {
+    v: 1;
+    verb: string;
+    since: string;
+    group: string;
+    /** Plain-English summary (= manifest `what`). */
+    summary: string;
+    /** When to invoke (= manifest `when`). */
+    invokeWhen: string;
+    /** Preconditions that MUST hold or invocation should be refused. */
+    preconditions: string[];
+    /** Outcome guarantees. */
+    postconditions: string[];
+    /** Files/state Mneme writes when this verb succeeds. */
+    sideEffects: string[];
+    /** Repeatable without harm? */
+    idempotency: IdempotencyLevel;
+    /** Impact tier — drives doppelganger requirement. */
+    defcon: DefconLevel;
+    /** Whether the verb is read-only (no fs/network mutation). */
+    readOnly: boolean;
+    /** Whether the verb consults an external network endpoint. */
+    reachesNetwork: boolean;
+    /** Cross-verb storyline hints — common predecessors / successors. */
+    comesAfter: string[];
+    comesBefore: string[];
+    /** Where the contract came from. */
+    source: "auto" | "override" | "hybrid";
+}
+/** Derive (and override if a file exists) the contract for a single
+ *  catalog entry. Pure function — no disk writes. */
+export declare function contractFor(entry: ManifestCommand): VerbContract;
+/** Return contracts for every catalog verb. Used by the conductor's
+ *  planner + as the canonical companion seed. */
+export declare function allContracts(catalog?: ManifestCommand[]): VerbContract[];
+export declare function findContract(verb: string, catalog?: ManifestCommand[]): VerbContract | null;
+export declare function formatContract(c: VerbContract): string;
+//# sourceMappingURL=contract.d.ts.map

package/dist/companion/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/companion/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEnF,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAO5C,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,aAAa,CAAC;AAEvF,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,0BAA0B;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,wDAAwD;IACxD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,+BAA+B;IAC/B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,qDAAqD;IACrD,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,cAAc,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oCAAoC;IACpC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;CACxC;AA4GD;qDACqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,CAsBhE;AAED;iDACiD;AACjD,wBAAgB,YAAY,CAAC,OAAO,GAAE,eAAe,EAA0B,GAAG,YAAY,EAAE,CAE/F;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAe,EAA0B,GAAG,YAAY,GAAG,IAAI,CAQlH;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAwBtD"}

package/dist/companion/contract.js

@@ -0,0 +1,209 @@
+/**
+ * v2.22.0 — COMPANION · CONTRACT.
+ *
+ * Each verb in the catalog gets a derived contract: preconditions,
+ * postconditions, side-effects, idempotency level, DEFCON impact.
+ * The contract is auto-derived from the manifest entry first, then
+ * optionally overridden by a hand-authored file at
+ * `packages/core/src/companion/overrides/<verb-slug>.json`.
+ *
+ * Why this lives apart from `agent_manifest.ts`:
+ *   - manifest is the single-line "what + when" surface AI agents
+ *     read by default;
+ *   - contract is the deep structured form AI agents read BEFORE
+ *     invoking a verb the first time. They serve different audiences.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MNEME_COMMAND_CATALOG } from "../agent_manifest.js";
+// ─── HEURISTIC AUTO-DERIVATION ────────────────────────────────────────
+// Hints are matched as whole words in the description and as substrings
+// inside the command verb. Terms here MUST be unambiguous — e.g. "abort"
+// + "rollback" appear in many neutral descriptions ("exit on ABORT
+// band", "rollback safety"), so we drop them from destructive list.
+const READ_HINTS = ["list", "show", "print", "verify", "audit", "diagnose", "probe", "scan", "report", "status", "view", "stats", "leaderboard", "atlas", "tags", "hot", "bloom", "route", "rights", "doctor"];
+const DESTRUCTIVE_HINTS = ["delete", "remove", "uninstall", "purge", "wipe", "nuke", "destroy", "revoke"];
+const IRREVERSIBLE_HINTS = ["uninstall", "publish to npm", "deploy", "fire", "cull"];
+const NETWORK_HINTS = ["push", "fetch", "sync", "transmit", "broadcast", "federation"];
+/** Match a hint as a whole word in the command-verb portion (heavier
+ *  weight) or in the description (lighter weight). Avoids false
+ *  positives like "ABORT" inside a trust-band enum string. */
+function hintHits(entry, hints) {
+    // Command-name is the strongest signal — match anywhere in the verb token.
+    const cmd = entry.command.toLowerCase();
+    for (const h of hints)
+        if (cmd.includes(h))
+            return true;
+    // Description: word-boundary only, to skip enum-value spelunking.
+    const desc = entry.what.toLowerCase();
+    for (const h of hints) {
+        const re = new RegExp(`\\b${h.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&")}\\b`);
+        if (re.test(desc))
+            return true;
+    }
+    return false;
+}
+function detectReadOnly(entry) {
+    const isRead = hintHits(entry, READ_HINTS);
+    const isDestructive = hintHits(entry, DESTRUCTIVE_HINTS);
+    return isRead && !isDestructive;
+}
+function detectNetwork(entry) {
+    const haystack = `${entry.command} ${entry.what}`.toLowerCase();
+    // some verbs say "no network" explicitly — respect that
+    if (/(no network|offline|pure local|no\s+llm)/.test(haystack))
+        return false;
+    return hintHits(entry, NETWORK_HINTS);
+}
+function detectDefcon(entry) {
+    if (hintHits(entry, IRREVERSIBLE_HINTS))
+        return 1;
+    if (hintHits(entry, DESTRUCTIVE_HINTS))
+        return 2;
+    if (detectNetwork(entry))
+        return 3;
+    if (detectReadOnly(entry))
+        return 5;
+    return 4; // local-mutating default
+}
+function detectIdempotency(entry) {
+    if (detectReadOnly(entry))
+        return "read-only";
+    const haystack = `${entry.command} ${entry.what}`.toLowerCase();
+    if (DESTRUCTIVE_HINTS.some((h) => haystack.includes(h)))
+        return "destructive";
+    if (/(append|record|log|drop\s+pheromone|capture|inscribe)/.test(haystack))
+        return "additive";
+    return "idempotent";
+}
+function detectSideEffects(entry) {
+    const out = [];
+    const m = entry.what.match(/`(\.mneme\/[^`]+|node_modules\/[^`]+|\$HOME[^`]+|~\/\.mneme[^`]+)`/g);
+    if (m)
+        for (const path of m)
+            out.push(`writes ${path.replace(/`/g, "")}`);
+    if (detectNetwork(entry))
+        out.push("reaches an external network endpoint");
+    if (out.length === 0 && !detectReadOnly(entry))
+        out.push("mutates local state (unspecified — improve the manifest entry)");
+    return out;
+}
+function detectPreconditions(entry) {
+    const out = [];
+    // very simple rule-based — works for the obvious cases
+    const w = entry.what.toLowerCase();
+    if (/baseline|probes/.test(w))
+        out.push("≥5 probes recorded for the target vendor");
+    if (/key|hmac|sig/.test(w))
+        out.push("install HMAC key exists at .mneme/<feature>/*.key");
+    if (/inbox|pulse|daemon/.test(w))
+        out.push("Mneme daemon is reachable OR the verb falls back to disk read");
+    if (out.length === 0)
+        out.push("none beyond installed Mneme + readable repo root");
+    return out;
+}
+function detectPostconditions(entry) {
+    if (detectReadOnly(entry))
+        return ["returns stdout payload; no state change"];
+    return ["records a side-effect listed above OR returns a non-zero exit code"];
+}
+// ─── OVERRIDE LOADING ────────────────────────────────────────────────
+function overrideDir() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return join(here, "overrides");
+    }
+    catch {
+        return ""; // no overrides reachable
+    }
+}
+function slugify(command) {
+    return command.replace(/^mneme\s+/, "").replace(/[\s<>\[\]|'"]+/g, "_").toLowerCase();
+}
+function loadOverride(verb) {
+    const dir = overrideDir();
+    if (!dir)
+        return null;
+    const p = join(dir, `${slugify(verb)}.json`);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// ─── PUBLIC API ──────────────────────────────────────────────────────
+/** Derive (and override if a file exists) the contract for a single
+ *  catalog entry. Pure function — no disk writes. */
+export function contractFor(entry) {
+    const auto = {
+        v: 1,
+        verb: entry.command,
+        since: entry.since,
+        group: entry.group,
+        summary: entry.what,
+        invokeWhen: entry.when,
+        preconditions: detectPreconditions(entry),
+        postconditions: detectPostconditions(entry),
+        sideEffects: detectSideEffects(entry),
+        idempotency: detectIdempotency(entry),
+        defcon: detectDefcon(entry),
+        readOnly: detectReadOnly(entry),
+        reachesNetwork: detectNetwork(entry),
+        comesAfter: [],
+        comesBefore: [],
+        source: "auto",
+    };
+    const override = loadOverride(entry.command);
+    if (!override)
+        return auto;
+    return { ...auto, ...override, source: "hybrid" };
+}
+/** Return contracts for every catalog verb. Used by the conductor's
+ *  planner + as the canonical companion seed. */
+export function allContracts(catalog = MNEME_COMMAND_CATALOG) {
+    return catalog.map(contractFor);
+}
+export function findContract(verb, catalog = MNEME_COMMAND_CATALOG) {
+    const stems = [verb, "mneme " + verb, verb.replace(/^mneme\s+/, "")];
+    for (const entry of catalog) {
+        if (stems.includes(entry.command))
+            return contractFor(entry);
+        // prefix match — `mneme earthquake` matches `mneme earthquake drift`
+        if (entry.command.startsWith(verb) || entry.command.startsWith(stems[1]))
+            return contractFor(entry);
+    }
+    return null;
+}
+export function formatContract(c) {
+    const lines = [];
+    const defconBadge = c.defcon === 5 ? "🟢 5 read-only"
+        : c.defcon === 4 ? "🟡 4 mutates local state"
+            : c.defcon === 3 ? "🟠 3 reaches network"
+                : c.defcon === 2 ? "🔴 2 destructive (recoverable)"
+                    : "💀 1 irreversible";
+    lines.push(`📜 CONTRACT — ${c.verb}`);
+    lines.push("");
+    lines.push(`  Since:           ${c.since}  ·  group: ${c.group}  ·  source: ${c.source}`);
+    lines.push(`  DEFCON:          ${defconBadge}`);
+    lines.push(`  Idempotency:     ${c.idempotency}`);
+    lines.push(`  Read-only:       ${c.readOnly ? "yes" : "no"}  ·  Network: ${c.reachesNetwork ? "yes" : "no"}`);
+    lines.push("");
+    lines.push(`  Summary:         ${c.summary}`);
+    lines.push(`  Invoke when:     ${c.invokeWhen}`);
+    lines.push("");
+    lines.push(`  Preconditions:`);
+    for (const x of c.preconditions)
+        lines.push(`    - ${x}`);
+    lines.push(`  Postconditions:`);
+    for (const x of c.postconditions)
+        lines.push(`    - ${x}`);
+    lines.push(`  Side-effects:`);
+    for (const x of c.sideEffects)
+        lines.push(`    - ${x}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=contract.js.map

package/dist/companion/contract.js.map

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

package/dist/companion/doppelganger.d.ts

@@ -0,0 +1,84 @@
+/**
+ * v2.22.0 — COMPANION · DOPPELGANGER.
+ *
+ * Copy-on-write fs overlay that runs a verb's effects in a SHADOW
+ * directory and returns the diff. AI agent sees EXACT changes before
+ * committing.
+ *
+ * Implementation strategy:
+ *   1. Caller hands us a `repoRoot` + a function that simulates the
+ *      verb (no real I/O).
+ *   2. We seed the shadow by copying repo state lazily (overlay style
+ *      — only files the verb touches are materialised).
+ *   3. We invoke the verb against the shadow via dependency injection
+ *      (`fs` proxy + `process.exit` shim).
+ *   4. We compute the diff: files added / changed / removed; exit
+ *      code; would-be network calls.
+ *
+ * Limitations (honest):
+ *   - Verbs that call native C++ code (sharp, sqlite native) bypass
+ *     the proxy. We catch *most* of them via the existing DLL-extract
+ *     mechanism but cannot guarantee 100 % coverage. Doppelganger
+ *     reports a `leakage: "possible"` flag for verbs known to use
+ *     native modules.
+ *   - Network I/O is currently *blocked* in shadow mode (any outbound
+ *     request returns a "would-fetch" record instead of executing).
+ *     This means doppelganger preview for network-bound verbs is
+ *     approximate: we can predict "would call URL X" but not the
+ *     response.
+ */
+export interface FileEffect {
+    path: string;
+    kind: "added" | "changed" | "removed";
+    beforeSha?: string;
+    afterSha?: string;
+    beforeBytes?: number;
+    afterBytes?: number;
+}
+export interface DoppelgangerResult {
+    /** What the verb would do if executed for real. */
+    fileEffects: FileEffect[];
+    /** Process exit code the verb would return. */
+    exitCode: number;
+    /** Network endpoints the verb would have called (URLs, not responses). */
+    wouldFetch: string[];
+    /** Stdout the verb would have written. */
+    stdoutSample: string;
+    /** Stderr the verb would have written. */
+    stderrSample: string;
+    /** Honest signal: parts of the verb that escaped the doppelganger. */
+    leakage: "none" | "possible" | "definite";
+    leakageReason?: string;
+}
+export interface DoppelgangerOptions {
+    /** Whether the verb is known to call native code (sharp, sqlite). */
+    knownNativeUse?: boolean;
+    /** Whether the verb reaches network. */
+    knownNetworkUse?: boolean;
+}
+/** Run `verbFn` in a shadow copy of `repoRoot` and return the diff.
+ *  `verbFn` receives the shadow path; it should perform its work
+ *  AGAINST THAT PATH (the caller wires its own dependency injection;
+ *  see conductor.executePlan for the canonical usage). */
+export declare function dryRun<T = void>(repoRoot: string, verbFn: (shadowRoot: string) => Promise<T> | T, opts?: DoppelgangerOptions): Promise<DoppelgangerResult & {
+    result?: T;
+}>;
+export interface CommitOptions {
+    /** Where to stage; defaults to a sibling temp dir. */
+    stageRoot?: string;
+}
+/** Two-phase commit primitive used by the conductor: stage to a temp
+ *  dir, atomically move into place, or rollback by deleting the stage.
+ *  Returns the staged path so the conductor can either rename or
+ *  remove. */
+export declare function stageCommit(repoRoot: string, opts?: CommitOptions): {
+    stagePath: string;
+    rollback: () => void;
+};
+/** Atomically apply staged files into `repoRoot`. Uses `rename` when
+ *  same filesystem; falls back to `cp -r + rm` otherwise. Caller-side
+ *  contract: every file in `stagePath` has been verified by the
+ *  doppelganger. */
+export declare function applyCommit(stagePath: string, repoRoot: string): void;
+export declare function formatDoppelganger(r: DoppelgangerResult): string;
+//# sourceMappingURL=doppelganger.d.ts.map

package/dist/companion/doppelganger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doppelganger.d.ts","sourceRoot":"","sources":["../../src/companion/doppelganger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA6CD,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wCAAwC;IACxC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;0DAG0D;AAC1D,wBAAsB,MAAM,CAAC,CAAC,GAAG,IAAI,EACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9C,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC,CAiC9C;AAED,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;cAGc;AACd,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAAE,CAOnH;AAED;;;oBAGoB;AACpB,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAwBrE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAsBhE"}