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

package/dist/companion/doppelganger.js

@@ -0,0 +1,227 @@
+/**
+ * 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.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync, statSync, cpSync } from "node:fs";
+import { join, relative, sep, dirname } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex").slice(0, 16);
+}
+function snapshotTree(root) {
+    const out = new Map();
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (name === "node_modules" || name === ".git")
+                continue;
+            const full = join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            let buf;
+            try {
+                buf = readFileSync(full);
+            }
+            catch {
+                continue;
+            }
+            const rel = relative(root, full).split(sep).join("/");
+            out.set(rel, { sha: sha256(buf), size: buf.length });
+        }
+    }
+    return out;
+}
+function diffSnapshots(before, after) {
+    const effects = [];
+    for (const [path, b] of before) {
+        const a = after.get(path);
+        if (!a)
+            effects.push({ path, kind: "removed", beforeSha: b.sha, beforeBytes: b.size });
+        else if (a.sha !== b.sha)
+            effects.push({ path, kind: "changed", beforeSha: b.sha, afterSha: a.sha, beforeBytes: b.size, afterBytes: a.size });
+    }
+    for (const [path, a] of after) {
+        if (!before.has(path))
+            effects.push({ path, kind: "added", afterSha: a.sha, afterBytes: a.size });
+    }
+    return effects;
+}
+/** 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 async function dryRun(repoRoot, verbFn, opts = {}) {
+    const shadow = join(tmpdir(), "mneme-doppel-" + randomBytes(4).toString("hex"));
+    // Bound the copy: only mirror `.mneme/` + the repo root manifest. Bulk
+    // of dev-time fs is irrelevant for verb dry-run and copying everything
+    // is prohibitive on big repos.
+    mkdirSync(shadow, { recursive: true });
+    try {
+        if (existsSync(join(repoRoot, ".mneme"))) {
+            cpSync(join(repoRoot, ".mneme"), join(shadow, ".mneme"), { recursive: true });
+        }
+        // Snapshot before.
+        const before = snapshotTree(shadow);
+        let exitCode = 0;
+        let result;
+        let stdoutSample = "";
+        let stderrSample = "";
+        const wouldFetch = [];
+        try {
+            result = await verbFn(shadow);
+        }
+        catch (e) {
+            exitCode = typeof e?.code === "number" ? e.code : 1;
+            stderrSample = (e?.message ?? String(e)).slice(0, 500);
+        }
+        const after = snapshotTree(shadow);
+        const fileEffects = diffSnapshots(before, after);
+        let leakage = "none";
+        let leakageReason;
+        if (opts.knownNativeUse) {
+            leakage = "possible";
+            leakageReason = "verb is known to load native modules (sharp/sqlite); effects from C++ code are not captured";
+        }
+        if (opts.knownNetworkUse) {
+            leakage = leakage === "none" ? "possible" : leakage;
+            leakageReason = (leakageReason ?? "") + (leakageReason ? " · " : "") + "verb reaches network; only URLs are previewed, not responses";
+        }
+        return { fileEffects, exitCode, wouldFetch, stdoutSample, stderrSample, leakage, leakageReason, result };
+    }
+    finally {
+        try {
+            rmSync(shadow, { recursive: true, force: true });
+        }
+        catch { /* */ }
+    }
+}
+/** 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 function stageCommit(repoRoot, opts = {}) {
+    const stage = opts.stageRoot ?? join(tmpdir(), "mneme-stage-" + randomBytes(4).toString("hex"));
+    mkdirSync(stage, { recursive: true });
+    return {
+        stagePath: stage,
+        rollback: () => { try {
+            rmSync(stage, { recursive: true, force: true });
+        }
+        catch { /* */ } },
+    };
+}
+/** 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 function applyCommit(stagePath, repoRoot) {
+    if (!existsSync(stagePath))
+        return;
+    const stack = [stagePath];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            const rel = relative(stagePath, full);
+            const target = join(repoRoot, rel);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                mkdirSync(target, { recursive: true });
+                stack.push(full);
+            }
+            else if (st.isFile()) {
+                mkdirSync(dirname(target), { recursive: true });
+                // overwrite — caller-side contract: doppelganger has previewed
+                writeFileSync(target, readFileSync(full));
+            }
+        }
+    }
+    try {
+        rmSync(stagePath, { recursive: true, force: true });
+    }
+    catch { /* */ }
+}
+export function formatDoppelganger(r) {
+    const lines = [`👻 DOPPELGANGER preview`, ""];
+    lines.push(`  Exit code:     ${r.exitCode}`);
+    lines.push(`  Leakage:       ${r.leakage}${r.leakageReason ? `  (${r.leakageReason})` : ""}`);
+    lines.push(`  Files added:   ${r.fileEffects.filter((e) => e.kind === "added").length}`);
+    lines.push(`  Files changed: ${r.fileEffects.filter((e) => e.kind === "changed").length}`);
+    lines.push(`  Files removed: ${r.fileEffects.filter((e) => e.kind === "removed").length}`);
+    if (r.wouldFetch.length > 0) {
+        lines.push("");
+        lines.push(`  Network calls (preview only):`);
+        for (const u of r.wouldFetch.slice(0, 6))
+            lines.push(`    - ${u}`);
+        if (r.wouldFetch.length > 6)
+            lines.push(`    (and ${r.wouldFetch.length - 6} more)`);
+    }
+    if (r.fileEffects.length > 0) {
+        lines.push("");
+        lines.push(`  File diff (first 12 entries):`);
+        for (const e of r.fileEffects.slice(0, 12)) {
+            const arrow = e.kind === "added" ? "+" : e.kind === "removed" ? "-" : "Δ";
+            lines.push(`    ${arrow} ${e.path}  ${e.kind === "added" ? `(+${e.afterBytes}B)` : e.kind === "removed" ? `(-${e.beforeBytes}B)` : `${e.beforeBytes}B → ${e.afterBytes}B`}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=doppelganger.js.map

package/dist/companion/doppelganger.js.map

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

package/dist/companion/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * v2.22.0 — COMPANION.
+ *
+ * Five composed primitives that turn every Mneme verb into an AI-
+ * agent-friendly surface:
+ *
+ *   1. CONTRACT    — pre/post-conditions, side-effects, DEFCON tier
+ *   2. AUTOSPEC    — JSON Schema for args + validate() helper
+ *   3. DOPPELGANGER — copy-on-write dry-run + diff
+ *   4. STORYLINE   — Markov chain over pheromone log
+ *   5. LEARN LOOP  — failure patterns + outcome stats
+ *
+ * Auto-registration: any new verb that appears in
+ * `MNEME_COMMAND_CATALOG` automatically gets contract + autospec.
+ * Doppelganger + storyline + learn-loop activate once the verb has
+ * been invoked at least once (pheromone seed).
+ *
+ * Public API:
+ *   companionFor(verb)       — composed Companion for a single verb
+ *   formatCompanion(c)       — human-readable rendering
+ *   listCompanionable()      — verbs that have full data
+ *   companionableCoverage()  — % of catalog with at least contract+autospec
+ */
+export { contractFor, allContracts, findContract, formatContract, type VerbContract, type DefconLevel, type IdempotencyLevel } from "./contract.js";
+export { parseArgSchema, schemaFor, validateArgs, formatSchema, allSchemas, type ArgSchema, type ValidateResult, type ProvidedArgs } from "./autospec.js";
+export { dryRun, stageCommit, applyCommit, formatDoppelganger, type DoppelgangerResult, type FileEffect, type DoppelgangerOptions, type CommitOptions } from "./doppelganger.js";
+export { predictNext, predictPrior, formatStoryline, type TransitionStats, type StorylineQuery } from "./storyline.js";
+export { computeOutcomeStats, commonMistakes, redactInvocation, formatOutcomeStats, formatMistakes, type VerbOutcomeStats, type CommonMistake, type RedactedInvocation } from "./learn_loop.js";
+import { type VerbContract } from "./contract.js";
+import { type ArgSchema } from "./autospec.js";
+import { type TransitionStats } from "./storyline.js";
+import { type VerbOutcomeStats, type CommonMistake } from "./learn_loop.js";
+import { type ManifestCommand } from "../agent_manifest.js";
+export interface Companion {
+    v: 1;
+    verb: string;
+    contract: VerbContract;
+    argSchema: ArgSchema;
+    storyline: {
+        next: TransitionStats[];
+        prior: TransitionStats[];
+    };
+    outcomeStats: VerbOutcomeStats;
+    commonMistakes: CommonMistake[];
+    /** Coverage flag — `false` means catalog metadata only, no live data yet. */
+    hasLiveData: boolean;
+    generatedAt: string;
+}
+export interface BuildCompanionOptions {
+    repoRoot?: string;
+    topK?: number;
+}
+export declare function companionFor(verb: string, opts?: BuildCompanionOptions): Companion | null;
+export declare function formatCompanion(c: Companion): string;
+/** Catalog-wide coverage report. Useful for CI + dashboards. */
+export interface CoverageReport {
+    total: number;
+    withContract: number;
+    withAutospec: number;
+    withLiveData: number;
+    coverageContract: number;
+    coverageAutospec: number;
+    coverageLiveData: number;
+}
+export declare function companionableCoverage(repoRoot: string, catalog?: ManifestCommand[]): CoverageReport;
+export declare function listCompanionable(catalog?: ManifestCommand[]): string[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/companion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpJ,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC1J,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjL,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACvH,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhM,OAAO,EAA6C,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAA2E,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrJ,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEnF,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE;QAAE,IAAI,EAAE,eAAe,EAAE,CAAC;QAAC,KAAK,EAAE,eAAe,EAAE,CAAA;KAAE,CAAC;IACjE,YAAY,EAAE,gBAAgB,CAAC;IAC/B,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,SAAS,GAAG,IAAI,CAsB7F;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAcpD;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,eAAe,EAA0B,GAAG,cAAc,CAoB1H;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,eAAe,EAA0B,GAAG,MAAM,EAAE,CAE9F"}

package/dist/companion/index.js

@@ -0,0 +1,100 @@
+/**
+ * v2.22.0 — COMPANION.
+ *
+ * Five composed primitives that turn every Mneme verb into an AI-
+ * agent-friendly surface:
+ *
+ *   1. CONTRACT    — pre/post-conditions, side-effects, DEFCON tier
+ *   2. AUTOSPEC    — JSON Schema for args + validate() helper
+ *   3. DOPPELGANGER — copy-on-write dry-run + diff
+ *   4. STORYLINE   — Markov chain over pheromone log
+ *   5. LEARN LOOP  — failure patterns + outcome stats
+ *
+ * Auto-registration: any new verb that appears in
+ * `MNEME_COMMAND_CATALOG` automatically gets contract + autospec.
+ * Doppelganger + storyline + learn-loop activate once the verb has
+ * been invoked at least once (pheromone seed).
+ *
+ * Public API:
+ *   companionFor(verb)       — composed Companion for a single verb
+ *   formatCompanion(c)       — human-readable rendering
+ *   listCompanionable()      — verbs that have full data
+ *   companionableCoverage()  — % of catalog with at least contract+autospec
+ */
+export { contractFor, allContracts, findContract, formatContract } from "./contract.js";
+export { parseArgSchema, schemaFor, validateArgs, formatSchema, allSchemas } from "./autospec.js";
+export { dryRun, stageCommit, applyCommit, formatDoppelganger } from "./doppelganger.js";
+export { predictNext, predictPrior, formatStoryline } from "./storyline.js";
+export { computeOutcomeStats, commonMistakes, redactInvocation, formatOutcomeStats, formatMistakes } from "./learn_loop.js";
+import { contractFor, findContract, formatContract } from "./contract.js";
+import { schemaFor, formatSchema } from "./autospec.js";
+import { predictNext, predictPrior, formatStoryline } from "./storyline.js";
+import { computeOutcomeStats, commonMistakes, formatOutcomeStats, formatMistakes } from "./learn_loop.js";
+import { MNEME_COMMAND_CATALOG } from "../agent_manifest.js";
+export function companionFor(verb, opts = {}) {
+    const contract = findContract(verb);
+    if (!contract)
+        return null;
+    const argSchema = schemaFor({ command: contract.verb, since: contract.since, what: contract.summary, when: contract.invokeWhen, group: contract.group });
+    const repoRoot = opts.repoRoot;
+    const next = repoRoot ? predictNext(repoRoot, contract.verb, { topK: opts.topK ?? 5 }) : [];
+    const prior = repoRoot ? predictPrior(repoRoot, contract.verb, { topK: opts.topK ?? 5 }) : [];
+    const outcomeStats = repoRoot
+        ? computeOutcomeStats(repoRoot, contract.verb)
+        : { verb: contract.verb, invocations: 0, successes: 0, failures: 0, successRate: 0, recentInvocations: 0, recentSuccessRate: 0 };
+    const mistakes = repoRoot ? commonMistakes(repoRoot, contract.verb) : [];
+    return {
+        v: 1,
+        verb: contract.verb,
+        contract,
+        argSchema,
+        storyline: { next, prior },
+        outcomeStats,
+        commonMistakes: mistakes,
+        hasLiveData: outcomeStats.invocations > 0,
+        generatedAt: new Date().toISOString(),
+    };
+}
+export function formatCompanion(c) {
+    return [
+        formatContract(c.contract),
+        "",
+        formatSchema(c.argSchema),
+        "",
+        formatStoryline(c.verb, c.storyline.next, c.storyline.prior),
+        "",
+        formatOutcomeStats(c.outcomeStats),
+        "",
+        formatMistakes(c.commonMistakes),
+        "",
+        `  // companion data live: ${c.hasLiveData ? "yes" : "no — invoke the verb at least once to seed"}`,
+    ].join("\n");
+}
+export function companionableCoverage(repoRoot, catalog = MNEME_COMMAND_CATALOG) {
+    let withContract = 0, withAutospec = 0, withLiveData = 0;
+    for (const entry of catalog) {
+        const c = contractFor(entry);
+        if (c)
+            withContract++;
+        const s = schemaFor(entry);
+        if (s)
+            withAutospec++;
+        const stats = computeOutcomeStats(repoRoot, entry.command);
+        if (stats.invocations > 0)
+            withLiveData++;
+    }
+    const total = catalog.length;
+    return {
+        total,
+        withContract,
+        withAutospec,
+        withLiveData,
+        coverageContract: total === 0 ? 0 : withContract / total,
+        coverageAutospec: total === 0 ? 0 : withAutospec / total,
+        coverageLiveData: total === 0 ? 0 : withLiveData / total,
+    };
+}
+export function listCompanionable(catalog = MNEME_COMMAND_CATALOG) {
+    return catalog.map((e) => e.command).sort();
+}
+//# sourceMappingURL=index.js.map

package/dist/companion/index.js.map

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

package/dist/companion/learn_loop.d.ts

@@ -0,0 +1,55 @@
+/**
+ * v2.22.0 — COMPANION · LEARN LOOP.
+ *
+ * Mines `.mneme/atlas/pheromones.jsonl` + (when opt-in)
+ * `.mneme/replay.jsonl` for per-verb failure patterns and surfaces
+ * them as pre-invocation hints.
+ *
+ * Privacy is opt-IN via Consent Fabric Article 2:
+ *   - `pheromone` telemetry → enables outcome aggregation
+ *   - `replay` telemetry    → enables structured arg pattern mining
+ *
+ * Arg values are NEVER stored as-is. Each argument is replaced with a
+ * type-tag (`<string>`, `<path>`, `<int>`, `<flag>`) so a pattern
+ * like "agents commonly omit --vendor" survives without leaking the
+ * actual vendor string.
+ *
+ * Pattern emission is heuristic + threshold-gated: a finding only
+ * surfaces after ≥ 3 observations of the same pattern across distinct
+ * timestamps. Goodhart's-law-resistant by design.
+ */
+import { type PheromoneHit } from "../atlas/pheromone.js";
+export interface VerbOutcomeStats {
+    verb: string;
+    invocations: number;
+    successes: number;
+    failures: number;
+    successRate: number;
+    /** Recent invocations (last 14 days) — helps spot regressions. */
+    recentInvocations: number;
+    recentSuccessRate: number;
+}
+export declare function computeOutcomeStats(repoRoot: string, verb: string, now?: number): VerbOutcomeStats;
+export interface CommonMistake {
+    pattern: string;
+    observations: number;
+    /** Heuristic confidence 0-1. */
+    confidence: number;
+    suggestion: string;
+}
+/** Mine common mistakes for a verb. Currently rule-based; ML can
+ *  swap in here when corpus is large. */
+export declare function commonMistakes(repoRoot: string, verb: string): CommonMistake[];
+export interface RedactedInvocation {
+    ts: string;
+    verb: string;
+    argSignature: string;
+    outcome: "success" | "failure";
+}
+/** Build a privacy-preserving signature from a pheromone hit + (when
+ *  enabled) the replay record. Values are stripped so signatures
+ *  describe the SHAPE of the invocation, not the data. */
+export declare function redactInvocation(h: PheromoneHit): RedactedInvocation;
+export declare function formatOutcomeStats(s: VerbOutcomeStats): string;
+export declare function formatMistakes(mistakes: CommonMistake[]): string;
+//# sourceMappingURL=learn_loop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"learn_loop.d.ts","sourceRoot":"","sources":["../../src/companion/learn_loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAID,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,gBAAgB,CAsBtG;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;yCACyC;AACzC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAiB9E;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED;;0DAE0D;AAC1D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,kBAAkB,CAOpE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAS9D;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,CAQhE"}

package/dist/companion/learn_loop.js

@@ -0,0 +1,105 @@
+/**
+ * v2.22.0 — COMPANION · LEARN LOOP.
+ *
+ * Mines `.mneme/atlas/pheromones.jsonl` + (when opt-in)
+ * `.mneme/replay.jsonl` for per-verb failure patterns and surfaces
+ * them as pre-invocation hints.
+ *
+ * Privacy is opt-IN via Consent Fabric Article 2:
+ *   - `pheromone` telemetry → enables outcome aggregation
+ *   - `replay` telemetry    → enables structured arg pattern mining
+ *
+ * Arg values are NEVER stored as-is. Each argument is replaced with a
+ * type-tag (`<string>`, `<path>`, `<int>`, `<flag>`) so a pattern
+ * like "agents commonly omit --vendor" survives without leaking the
+ * actual vendor string.
+ *
+ * Pattern emission is heuristic + threshold-gated: a finding only
+ * surfaces after ≥ 3 observations of the same pattern across distinct
+ * timestamps. Goodhart's-law-resistant by design.
+ */
+import { listPheromones } from "../atlas/pheromone.js";
+import { isFeatureEnabled } from "../consent_fabric/index.js";
+const RECENT_WINDOW_MS = 14 * 86_400_000;
+export function computeOutcomeStats(repoRoot, verb, now = Date.now()) {
+    const hits = listPheromones(repoRoot).filter((h) => h.verb === verb);
+    let s = 0, f = 0, rs = 0, rf = 0, ri = 0;
+    for (const h of hits) {
+        const ok = h.outcome !== "failure";
+        if (ok)
+            s++;
+        else
+            f++;
+        const t = Date.parse(h.ts);
+        if (!Number.isNaN(t) && now - t < RECENT_WINDOW_MS) {
+            ri++;
+            if (ok)
+                rs++;
+            else
+                rf++;
+        }
+    }
+    const invocations = s + f;
+    return {
+        verb,
+        invocations,
+        successes: s,
+        failures: f,
+        successRate: invocations === 0 ? 0 : s / invocations,
+        recentInvocations: ri,
+        recentSuccessRate: ri === 0 ? 0 : rs / ri,
+    };
+}
+/** Mine common mistakes for a verb. Currently rule-based; ML can
+ *  swap in here when corpus is large. */
+export function commonMistakes(repoRoot, verb) {
+    // Always-on rule: recent success rate dropping below 60 % means
+    // SOMETHING regressed; surface it.
+    const out = [];
+    const stats = computeOutcomeStats(repoRoot, verb);
+    if (stats.recentInvocations >= 3 && stats.recentSuccessRate < 0.6) {
+        out.push({
+            pattern: "recent-failure-cluster",
+            observations: stats.recentInvocations,
+            confidence: 1 - stats.recentSuccessRate,
+            suggestion: `Recent first-try success rate is ${(stats.recentSuccessRate * 100).toFixed(0)}%. Review args + preconditions; consider running \`mneme companion ${verb}\` first.`,
+        });
+    }
+    // Opt-in pattern miner: replay-style telemetry is gated.
+    if (!isFeatureEnabled(repoRoot, "replay"))
+        return out;
+    // (Reserved for v2.22.x — actual replay log mining.)
+    return out;
+}
+/** Build a privacy-preserving signature from a pheromone hit + (when
+ *  enabled) the replay record. Values are stripped so signatures
+ *  describe the SHAPE of the invocation, not the data. */
+export function redactInvocation(h) {
+    return {
+        ts: h.ts,
+        verb: h.verb,
+        argSignature: "(no args in current pheromone schema; v2.22.x integrates replay for richer signatures)",
+        outcome: h.outcome === "failure" ? "failure" : "success",
+    };
+}
+export function formatOutcomeStats(s) {
+    const lines = [`📈 OUTCOME STATS — ${s.verb}`, ""];
+    if (s.invocations === 0) {
+        lines.push("  (no pheromone data yet — opt IN via `mneme telemetry grant pheromone`)");
+        return lines.join("\n");
+    }
+    lines.push(`  Lifetime:    ${s.invocations} invocations · ${(s.successRate * 100).toFixed(1)}% success`);
+    lines.push(`  Last 14d:    ${s.recentInvocations} invocations · ${(s.recentSuccessRate * 100).toFixed(1)}% success`);
+    return lines.join("\n");
+}
+export function formatMistakes(mistakes) {
+    if (mistakes.length === 0)
+        return "🛡 COMMON MISTAKES — (none surfaced; not enough data or all clear)";
+    const lines = [`🛡 COMMON MISTAKES`, ""];
+    for (const m of mistakes) {
+        lines.push(`  ${m.pattern}  (${m.observations} obs · confidence=${(m.confidence * 100).toFixed(0)}%)`);
+        lines.push(`    → ${m.suggestion}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=learn_loop.js.map

package/dist/companion/learn_loop.js.map

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

package/dist/companion/storyline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * v2.22.0 — COMPANION · STORYLINE.
+ *
+ * Markov chain over the pheromone log: given a recently-invoked
+ * verb, predict the top-K verbs that COMMONLY come next. AI agent
+ * uses this to plan multi-step flows.
+ *
+ * State definition: each verb invocation is one symbol. Transitions
+ * are derived from successive invocations within a session-equivalent
+ * window (default 5 minutes). Order-1 chain (one-step lookback) is
+ * the default; higher orders supported but require more data.
+ *
+ * Composes with Atlas `hot` (which counts standalone usage) — Atlas
+ * tells you what's used overall; Storyline tells you what's used
+ * AFTER what.
+ */
+export interface TransitionStats {
+    /** "after this verb..." */
+    from: string;
+    /** ...this verb followed `count` times. */
+    to: string;
+    count: number;
+    /** Probability `to` follows `from` given any successor. */
+    probability: number;
+}
+export interface StorylineQuery {
+    topK?: number;
+    /** Maximum elapsed time between two hits for them to count as a
+     *  transition. Default 5 minutes — beyond that they're separate
+     *  sessions. */
+    windowMs?: number;
+}
+/** Predict the top-K verbs that commonly follow `verb` in pheromone
+ *  history. Returns an empty list when the verb hasn't been seen
+ *  often enough to build statistics. */
+export declare function predictNext(repoRoot: string, verb: string, q?: StorylineQuery): TransitionStats[];
+/** Reverse: which verbs commonly LEAD to `verb`? */
+export declare function predictPrior(repoRoot: string, verb: string, q?: StorylineQuery): TransitionStats[];
+export declare function formatStoryline(verb: string, next: TransitionStats[], prior: TransitionStats[]): string;
+//# sourceMappingURL=storyline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyline.d.ts","sourceRoot":"","sources":["../../src/companion/storyline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;oBAEgB;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAoBD;;wCAEwC;AACxC,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,cAAmB,GAAG,eAAe,EAAE,CAWrG;AAED,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,cAAmB,GAAG,eAAe,EAAE,CAetG;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,CAgBvG"}