@mneme-ai/core 0.8.4 → 0.10.0

package/dist/insights/who-knows.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect } from "vitest";
+import { scoreCandidate, tierOf, whoKnowsVerdict } from "./who-knows.js";
+const today = new Date("2026-05-04T00:00:00Z");
+const daysAgo = (n) => new Date(today.getTime() - n * 86_400_000).toISOString();
+describe("scoreCandidate — pure scoring function", () => {
+    it("returns 0 for zero commits", () => {
+        expect(scoreCandidate(0, daysAgo(0), today)).toBe(0);
+    });
+    it("recent commits score higher than old commits with the same count", () => {
+        const recent = scoreCandidate(10, daysAgo(5), today);
+        const old = scoreCandidate(10, daysAgo(300), today);
+        expect(recent).toBeGreaterThan(old);
+    });
+    it("more commits score higher than fewer with the same recency", () => {
+        const more = scoreCandidate(50, daysAgo(10), today);
+        const fewer = scoreCandidate(5, daysAgo(10), today);
+        expect(more).toBeGreaterThan(fewer);
+    });
+    it("uses log-scale volume — 100 commits is not 100× more than 1 commit", () => {
+        const one = scoreCandidate(1, daysAgo(0), today);
+        const hundred = scoreCandidate(100, daysAgo(0), today);
+        // log2(101) ≈ 6.66, log2(2) = 1 → hundred / one ≈ 6.66, NOT 100.
+        expect(hundred / one).toBeLessThan(10);
+    });
+    it("recency floors at 0.3 even for very old commits", () => {
+        const ancient = scoreCandidate(10, daysAgo(2000), today);
+        const oneYear = scoreCandidate(10, daysAgo(365), today);
+        // Both should be at or near the floor.
+        expect(ancient).toBeGreaterThan(0);
+        expect(oneYear).toBeGreaterThan(0);
+    });
+});
+describe("tierOf — readable expert tier", () => {
+    it('"definitive" for many recent commits', () => {
+        expect(tierOf(20, daysAgo(10), today)).toBe("definitive");
+    });
+    it('"active" for moderate recent commits', () => {
+        expect(tierOf(5, daysAgo(20), today)).toBe("active");
+    });
+    it('"stale" for any volume but very old', () => {
+        expect(tierOf(100, daysAgo(300), today)).toBe("stale");
+    });
+    it('"occasional" — middle ground (≥1 commit, < ACTIVE_DAYS old, but few)', () => {
+        expect(tierOf(1, daysAgo(40), today)).toBe("occasional");
+    });
+});
+describe("whoKnowsVerdict — turns a list of candidates into a single verdict", () => {
+    const cand = (overrides) => ({
+        name: "alice",
+        email: "alice@x",
+        commitCount: 10,
+        lastTouch: daysAgo(5),
+        filesTouched: 20,
+        score: 3.0,
+        tier: "active",
+        ...overrides,
+    });
+    it("returns empty verdict for empty candidate list", () => {
+        const v = whoKnowsVerdict([]);
+        expect(v.topExpert).toBeUndefined();
+        expect(v.confidencePct).toBe(0);
+        expect(v.totalCommits).toBe(0);
+    });
+    it("picks the highest-score candidate as topExpert", () => {
+        const v = whoKnowsVerdict([
+            cand({ name: "alice", score: 4.0, commitCount: 15 }),
+            cand({ name: "bob", score: 2.0, commitCount: 5 }),
+        ]);
+        expect(v.topExpert?.name).toBe("alice");
+        expect(v.backup?.name).toBe("bob");
+    });
+    it("computes confidencePct as share of total commits", () => {
+        const v = whoKnowsVerdict([
+            cand({ name: "alice", score: 4.0, commitCount: 15 }),
+            cand({ name: "bob", score: 2.0, commitCount: 5 }),
+        ]);
+        expect(v.confidencePct).toBe(75);
+    });
+    it("flags risk when top expert is stale", () => {
+        const v = whoKnowsVerdict([
+            cand({ name: "alice", tier: "stale", lastTouch: daysAgo(300), commitCount: 20 }),
+            cand({ name: "bob", tier: "active", lastTouch: daysAgo(5), commitCount: 5 }),
+        ]);
+        expect(v.risk?.toLowerCase()).toContain("stale");
+        expect(v.risk).toContain("bob"); // suggests backup
+    });
+    it("flags risk when no dominant expert (well-distributed)", () => {
+        const v = whoKnowsVerdict([
+            cand({ name: "alice", commitCount: 4, score: 1.5 }),
+            cand({ name: "bob", commitCount: 4, score: 1.4 }),
+            cand({ name: "carol", commitCount: 4, score: 1.3 }),
+            cand({ name: "dave", commitCount: 4, score: 1.2 }),
+        ]);
+        expect(v.confidencePct).toBe(25);
+        expect(v.risk?.toLowerCase()).toContain("distributed");
+    });
+    it("flags risk when top expert touched once", () => {
+        const v = whoKnowsVerdict([cand({ name: "alice", commitCount: 1 })]);
+        expect(v.risk?.toLowerCase()).toContain("once");
+    });
+    it("no risk when top expert is definitive + recent", () => {
+        const v = whoKnowsVerdict([
+            cand({ name: "alice", tier: "definitive", commitCount: 20, lastTouch: daysAgo(5), score: 5 }),
+            cand({ name: "bob", commitCount: 2, score: 1, tier: "occasional" }),
+        ]);
+        expect(v.risk).toBeUndefined();
+    });
+});
+//# sourceMappingURL=who-knows.test.js.map

package/dist/insights/who-knows.test.js.map

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

package/dist/quant/alpha.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `mneme alpha` — Kelly criterion for technical debt allocation.
+ *
+ * Each refactor/TD item is a "bet" with (expected payoff, variance).
+ * Kelly optimal fraction maximizes long-run growth: f* = edge / variance.
+ * In practice, we use FRACTIONAL Kelly (×0.25) to limit blow-up risk —
+ * the same lever Edward Thorp used to win Wall Street.
+ *
+ * Pure math + small heuristics for estimating edge/variance from history.
+ * No LLM. The CLI takes a JSON list of items OR auto-extracts from
+ * `mneme regret` + `mneme bus-factor` + `mneme paradox` data.
+ */
+export interface DebtItem {
+    /** Stable id — drives sorting + reporting. */
+    id: string;
+    /** Human-readable name shown in output. */
+    name: string;
+    /**
+     * Edge — expected return as a fraction. Positive = improves codebase
+     * (smaller diff sizes, fewer regrets, better velocity). Negative =
+     * outright wasteful (the item costs more than it returns).
+     */
+    edge: number;
+    /**
+     * Variance — squared volatility of the outcome. Higher = riskier bet,
+     * more dispersion in possible outcomes. Tiny number (0..1) — interpret
+     * as fraction-squared.
+     */
+    variance: number;
+    /** Estimated dev-days to complete. */
+    effortDays: number;
+}
+export interface KellyAllocation extends DebtItem {
+    /** Raw Kelly fraction f* = edge / variance. May be > 1 or negative. */
+    rawKelly: number;
+    /** Fractional Kelly (clamped to [0, 0.5] after multiplier). */
+    kellyFraction: number;
+    /** Allocated dev-days for this item out of the budget. */
+    allocatedDays: number;
+    /** Sort tier for display. */
+    tier: "skip" | "small" | "core" | "outsized";
+}
+export interface KellyResult {
+    items: KellyAllocation[];
+    totalAllocated: number;
+    budgetDays: number;
+    reserveDays: number;
+    /** Kelly multiplier used. 0.25 by default — conservative. */
+    kellyMultiplier: number;
+}
+/**
+ * Compute Kelly-optimal allocation for a list of debt items.
+ *
+ * Algorithm:
+ *   1. raw_kelly_i = edge_i / variance_i  (the canonical Kelly formula)
+ *   2. fractional_kelly_i = raw_kelly_i × multiplier (default 0.25)
+ *   3. clamp to [0, 0.5] — never bet > 50% of budget on one item
+ *   4. zero out negative-edge items (don't hold a losing bet)
+ *   5. normalize so allocations sum to ≤ budgetDays (leave reserve)
+ *   6. allocate dev-days proportionally
+ */
+export declare function kellyAllocate(items: DebtItem[], opts?: {
+    budgetDays: number;
+    multiplier?: number;
+    reserveFraction?: number;
+}): KellyResult;
+export declare function classifyTier(kellyFraction: number, edge: number): KellyAllocation["tier"];
+/**
+ * Estimate edge from historical data: a refactor's edge is the difference
+ * in (regret rate, bug rate, churn velocity) between BEFORE and AFTER
+ * similar past refactors in the same module.
+ *
+ * The CLI calls this with regret data + commit-coach signals; here we
+ * just expose the algorithm so it's testable in isolation.
+ */
+export declare function estimateEdge(opts: {
+    pastRegretRate: number;
+    pastChurnPerDay: number;
+    postRefactorRegretRate: number;
+    postRefactorChurnPerDay: number;
+}): number;
+/**
+ * Estimate variance — historical variance of payoff across similar past
+ * refactors. Higher when past outcomes were inconsistent.
+ */
+export declare function estimateVariance(historicalPayoffs: number[]): number;
+//# sourceMappingURL=alpha.d.ts.map

package/dist/quant/alpha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alpha.d.ts","sourceRoot":"","sources":["../../src/quant/alpha.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,QAAQ;IACvB,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,EAAE,EACjB,IAAI,GAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAuB,GAC/F,WAAW,CA6Cb;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAMzF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,uBAAuB,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,CAKT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,EAAE,GAAG,MAAM,CAMpE"}

package/dist/quant/alpha.js

@@ -0,0 +1,103 @@
+/**
+ * `mneme alpha` — Kelly criterion for technical debt allocation.
+ *
+ * Each refactor/TD item is a "bet" with (expected payoff, variance).
+ * Kelly optimal fraction maximizes long-run growth: f* = edge / variance.
+ * In practice, we use FRACTIONAL Kelly (×0.25) to limit blow-up risk —
+ * the same lever Edward Thorp used to win Wall Street.
+ *
+ * Pure math + small heuristics for estimating edge/variance from history.
+ * No LLM. The CLI takes a JSON list of items OR auto-extracts from
+ * `mneme regret` + `mneme bus-factor` + `mneme paradox` data.
+ */
+/**
+ * Compute Kelly-optimal allocation for a list of debt items.
+ *
+ * Algorithm:
+ *   1. raw_kelly_i = edge_i / variance_i  (the canonical Kelly formula)
+ *   2. fractional_kelly_i = raw_kelly_i × multiplier (default 0.25)
+ *   3. clamp to [0, 0.5] — never bet > 50% of budget on one item
+ *   4. zero out negative-edge items (don't hold a losing bet)
+ *   5. normalize so allocations sum to ≤ budgetDays (leave reserve)
+ *   6. allocate dev-days proportionally
+ */
+export function kellyAllocate(items, opts = { budgetDays: 25 }) {
+    const multiplier = opts.multiplier ?? 0.25;
+    const reserveFrac = opts.reserveFraction ?? 0.2;
+    const budget = Math.max(0, opts.budgetDays);
+    // 1. Raw + fractional Kelly per item.
+    const computed = items.map((item) => {
+        // Avoid division-by-zero — variance of 0 is unrealistic; treat as floor.
+        const v = Math.max(item.variance, 1e-6);
+        const rawKelly = item.edge / v;
+        let frac = rawKelly * multiplier;
+        if (frac < 0)
+            frac = 0; // never bet on a losing item
+        if (frac > 0.5)
+            frac = 0.5; // never bet > 50% on one item
+        return { ...item, rawKelly, kellyFraction: frac };
+    });
+    // 2. Normalize fractions to sum ≤ (1 - reserveFrac).
+    const totalFrac = computed.reduce((s, c) => s + c.kellyFraction, 0);
+    const targetTotal = 1 - reserveFrac;
+    const scale = totalFrac > targetTotal ? targetTotal / totalFrac : 1;
+    // 3. Allocate dev-days.
+    let allocatedSum = 0;
+    const allocations = computed.map((c) => {
+        const adjusted = c.kellyFraction * scale;
+        const allocatedDays = Math.round(budget * adjusted * 10) / 10;
+        allocatedSum += allocatedDays;
+        return {
+            ...c,
+            kellyFraction: adjusted,
+            allocatedDays,
+            tier: classifyTier(adjusted, c.edge),
+        };
+    });
+    // 4. Sort by allocated days desc — biggest bets first.
+    allocations.sort((a, b) => b.allocatedDays - a.allocatedDays);
+    return {
+        items: allocations,
+        totalAllocated: Math.round(allocatedSum * 10) / 10,
+        budgetDays: budget,
+        reserveDays: Math.round((budget - allocatedSum) * 10) / 10,
+        kellyMultiplier: multiplier,
+    };
+}
+export function classifyTier(kellyFraction, edge) {
+    if (edge < 0)
+        return "skip";
+    if (kellyFraction >= 0.2)
+        return "outsized";
+    if (kellyFraction >= 0.1)
+        return "core";
+    if (kellyFraction > 0)
+        return "small";
+    return "skip";
+}
+/**
+ * Estimate edge from historical data: a refactor's edge is the difference
+ * in (regret rate, bug rate, churn velocity) between BEFORE and AFTER
+ * similar past refactors in the same module.
+ *
+ * The CLI calls this with regret data + commit-coach signals; here we
+ * just expose the algorithm so it's testable in isolation.
+ */
+export function estimateEdge(opts) {
+    const regretImprovement = opts.pastRegretRate - opts.postRefactorRegretRate;
+    const churnImprovement = (opts.pastChurnPerDay - opts.postRefactorChurnPerDay) / Math.max(opts.pastChurnPerDay, 0.001);
+    // Weighted: regret matters more (bugs hurt more than churn).
+    return 0.7 * regretImprovement + 0.3 * churnImprovement;
+}
+/**
+ * Estimate variance — historical variance of payoff across similar past
+ * refactors. Higher when past outcomes were inconsistent.
+ */
+export function estimateVariance(historicalPayoffs) {
+    if (historicalPayoffs.length < 2)
+        return 0.1; // unknown — assume mid-range
+    const mean = historicalPayoffs.reduce((s, x) => s + x, 0) / historicalPayoffs.length;
+    const variance = historicalPayoffs.reduce((s, x) => s + (x - mean) * (x - mean), 0) / historicalPayoffs.length;
+    return Math.max(variance, 1e-6);
+}
+//# sourceMappingURL=alpha.js.map

package/dist/quant/alpha.js.map

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

package/dist/quant/alpha.test.d.ts

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

package/dist/quant/alpha.test.d.ts.map

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

package/dist/quant/alpha.test.js

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { kellyAllocate, classifyTier, estimateEdge, estimateVariance } from "./alpha.js";
+const item = (overrides) => ({
+    id: "x",
+    name: "X",
+    edge: 0.1,
+    variance: 0.05,
+    effortDays: 5,
+    ...overrides,
+});
+describe("kellyAllocate — basic invariants", () => {
+    it("never allocates negative days", () => {
+        const r = kellyAllocate([
+            item({ id: "good", edge: 0.2, variance: 0.05 }),
+            item({ id: "bad", edge: -0.1, variance: 0.05 }),
+        ], { budgetDays: 20 });
+        for (const a of r.items)
+            expect(a.allocatedDays).toBeGreaterThanOrEqual(0);
+        expect(r.items.find((a) => a.id === "bad").allocatedDays).toBe(0);
+        expect(r.items.find((a) => a.id === "bad").tier).toBe("skip");
+    });
+    it("raw Kelly is edge / variance", () => {
+        const r = kellyAllocate([item({ id: "x", edge: 0.2, variance: 0.05 })], { budgetDays: 100 });
+        expect(r.items[0].rawKelly).toBeCloseTo(4, 6);
+    });
+    it("applies fractional Kelly multiplier (default 0.25)", () => {
+        const r = kellyAllocate([item({ id: "x", edge: 0.2, variance: 0.1 })], { budgetDays: 100 });
+        // raw kelly = 2.0, × 0.25 = 0.5 (clamped to ceiling)
+        expect(r.items[0].kellyFraction).toBeLessThanOrEqual(0.5);
+    });
+    it("clamps any single item to ≤ 50% of budget", () => {
+        const r = kellyAllocate([item({ edge: 1.0, variance: 0.001 })], { budgetDays: 100, multiplier: 1 });
+        expect(r.items[0].kellyFraction).toBeLessThanOrEqual(0.5);
+    });
+    it("totalAllocated never exceeds budgetDays", () => {
+        const items = [];
+        for (let i = 0; i < 10; i++) {
+            items.push(item({ id: `i${i}`, edge: 0.3, variance: 0.05 }));
+        }
+        const r = kellyAllocate(items, { budgetDays: 25 });
+        expect(r.totalAllocated).toBeLessThanOrEqual(25);
+    });
+    it("reserves at least reserveFraction of the budget by default", () => {
+        const items = Array.from({ length: 5 }, (_, i) => item({ id: `i${i}`, edge: 0.5, variance: 0.05 }));
+        const r = kellyAllocate(items, { budgetDays: 25, reserveFraction: 0.2 });
+        expect(r.totalAllocated).toBeLessThanOrEqual(25 * 0.8 + 0.5); // float wiggle
+        expect(r.reserveDays).toBeGreaterThanOrEqual(25 * 0.2 - 0.5);
+    });
+});
+describe("kellyAllocate — sorting + tiers", () => {
+    it("sorts by allocated days desc", () => {
+        const r = kellyAllocate([
+            item({ id: "small", edge: 0.05, variance: 0.05 }),
+            item({ id: "big", edge: 0.5, variance: 0.05 }),
+            item({ id: "mid", edge: 0.2, variance: 0.05 }),
+        ], { budgetDays: 25 });
+        expect(r.items[0].id).toBe("big");
+        expect(r.items[r.items.length - 1].id).toBe("small");
+    });
+    it("classifies tiers — outsized > core > small > skip", () => {
+        expect(classifyTier(0.3, 0.2)).toBe("outsized");
+        expect(classifyTier(0.15, 0.2)).toBe("core");
+        expect(classifyTier(0.05, 0.2)).toBe("small");
+        expect(classifyTier(0.0, 0.2)).toBe("skip");
+        expect(classifyTier(0.5, -0.1)).toBe("skip"); // negative edge always skip
+    });
+});
+describe("kellyAllocate — edge cases", () => {
+    it("handles empty input", () => {
+        const r = kellyAllocate([], { budgetDays: 25 });
+        expect(r.items).toEqual([]);
+        expect(r.totalAllocated).toBe(0);
+        expect(r.reserveDays).toBe(25);
+    });
+    it("handles zero variance (avoids division by zero)", () => {
+        const r = kellyAllocate([item({ id: "x", edge: 0.1, variance: 0 })], { budgetDays: 100 });
+        expect(Number.isFinite(r.items[0].allocatedDays)).toBe(true);
+    });
+    it("zero-budget case allocates nothing", () => {
+        const r = kellyAllocate([item({ edge: 0.5, variance: 0.05 })], { budgetDays: 0 });
+        expect(r.totalAllocated).toBe(0);
+        expect(r.items[0].allocatedDays).toBe(0);
+    });
+    it("more permissive multiplier (0.5) allocates more aggressively than default (0.25)", () => {
+        // Use a low raw-Kelly so neither multiplier hits the per-item 0.5 ceiling.
+        const items = [item({ edge: 0.05, variance: 0.1 })];
+        const conservative = kellyAllocate(items, { budgetDays: 100, multiplier: 0.25 });
+        const aggressive = kellyAllocate(items, { budgetDays: 100, multiplier: 0.5 });
+        expect(aggressive.totalAllocated).toBeGreaterThan(conservative.totalAllocated);
+    });
+});
+describe("estimateEdge — derives expected return from historical signals", () => {
+    it("positive edge when post-refactor improves regret + churn", () => {
+        const e = estimateEdge({
+            pastRegretRate: 0.3,
+            pastChurnPerDay: 5,
+            postRefactorRegretRate: 0.1,
+            postRefactorChurnPerDay: 3,
+        });
+        expect(e).toBeGreaterThan(0);
+    });
+    it("negative edge when post-refactor is worse", () => {
+        const e = estimateEdge({
+            pastRegretRate: 0.1,
+            pastChurnPerDay: 5,
+            postRefactorRegretRate: 0.3,
+            postRefactorChurnPerDay: 8,
+        });
+        expect(e).toBeLessThan(0);
+    });
+    it("regret improvement weighted higher than churn improvement", () => {
+        const regretOnly = estimateEdge({
+            pastRegretRate: 0.5,
+            pastChurnPerDay: 5,
+            postRefactorRegretRate: 0,
+            postRefactorChurnPerDay: 5,
+        });
+        const churnOnly = estimateEdge({
+            pastRegretRate: 0.3,
+            pastChurnPerDay: 10,
+            postRefactorRegretRate: 0.3,
+            postRefactorChurnPerDay: 5,
+        });
+        expect(regretOnly).toBeGreaterThan(churnOnly);
+    });
+});
+describe("estimateVariance — sample variance of payoffs", () => {
+    it("zero (floor) for unknown / single sample", () => {
+        expect(estimateVariance([])).toBe(0.1);
+        expect(estimateVariance([0.2])).toBe(0.1);
+    });
+    it("computes variance correctly for multiple payoffs", () => {
+        const v = estimateVariance([0.1, 0.2, 0.3]);
+        // mean = 0.2, deviations: -0.1, 0, 0.1; variance = (0.01 + 0 + 0.01) / 3
+        expect(v).toBeCloseTo(0.00667, 4);
+    });
+    it("non-negative for any input", () => {
+        const inputs = [
+            [0, 0, 0],
+            [-0.5, 0.5],
+            [1, 1, 1, 1],
+        ];
+        for (const arr of inputs)
+            expect(estimateVariance(arr)).toBeGreaterThanOrEqual(0);
+    });
+});
+//# sourceMappingURL=alpha.test.js.map

package/dist/quant/alpha.test.js.map

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

package/dist/quant/backtest.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `mneme backtest` — validate insight commands retroactively.
+ *
+ * The killer property: every prediction Mneme makes ("this is risky") can
+ * be replayed against actual history to compute precision, recall, F1, and
+ * lift over a random baseline. This turns "we have an AI tool" into
+ * "we have an AI tool with measured edge against the past".
+ *
+ * Backtest works for any binary predictor: given a set of (commit,
+ * prediction) pairs and a window in which to count "trouble" outcomes,
+ * compute the standard classification metrics.
+ *
+ * Pure data analysis — no LLM. The actual replay (re-running a command at
+ * a frozen point in history) lives in the CLI command, but the metric
+ * math is here and unit-testable.
+ */
+export interface BacktestSample {
+    /** The thing being predicted on — a commit, file, etc. */
+    id: string;
+    /** Did the predictor say "trouble incoming"? */
+    predicted: boolean;
+    /** Did trouble actually happen within the validation window? */
+    actual: boolean;
+}
+export interface BacktestResult {
+    /** Total samples evaluated. */
+    n: number;
+    /** Confusion matrix counts. */
+    truePositives: number;
+    falsePositives: number;
+    trueNegatives: number;
+    falseNegatives: number;
+    /** Standard metrics. */
+    precision: number;
+    recall: number;
+    f1: number;
+    /** Base rate of positive outcomes (how often trouble happens randomly). */
+    baseRate: number;
+    /** Lift over base rate — precision / baseRate. */
+    lift: number;
+    /** Verdict label for the report. */
+    verdict: "no-edge" | "weak" | "real-edge" | "strong-edge";
+    /** Plain-English conclusion. */
+    conclusion: string;
+}
+/**
+ * Compute classification metrics + verdict from a list of (predicted,
+ * actual) samples. Pure math — no I/O, deterministic.
+ */
+export declare function backtest(samples: BacktestSample[]): BacktestResult;
+export declare function classifyVerdict(lift: number, precision: number, recall: number, n: number): BacktestResult["verdict"];
+/**
+ * Aggregate a backtest result into a one-line markdown badge for the
+ * README / docs. Format: "F1 = 0.67 · 2.4× lift · n=14".
+ */
+export declare function badge(result: BacktestResult): string;
+//# sourceMappingURL=backtest.d.ts.map

package/dist/quant/backtest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../../src/quant/backtest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,aAAa,CAAC;IAC1D,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,CAkClE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,CAAC,EAAE,MAAM,GACR,cAAc,CAAC,SAAS,CAAC,CAM3B;AAsBD;;;GAGG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEpD"}

package/dist/quant/backtest.js

@@ -0,0 +1,90 @@
+/**
+ * `mneme backtest` — validate insight commands retroactively.
+ *
+ * The killer property: every prediction Mneme makes ("this is risky") can
+ * be replayed against actual history to compute precision, recall, F1, and
+ * lift over a random baseline. This turns "we have an AI tool" into
+ * "we have an AI tool with measured edge against the past".
+ *
+ * Backtest works for any binary predictor: given a set of (commit,
+ * prediction) pairs and a window in which to count "trouble" outcomes,
+ * compute the standard classification metrics.
+ *
+ * Pure data analysis — no LLM. The actual replay (re-running a command at
+ * a frozen point in history) lives in the CLI command, but the metric
+ * math is here and unit-testable.
+ */
+/**
+ * Compute classification metrics + verdict from a list of (predicted,
+ * actual) samples. Pure math — no I/O, deterministic.
+ */
+export function backtest(samples) {
+    const n = samples.length;
+    let tp = 0;
+    let fp = 0;
+    let tn = 0;
+    let fn = 0;
+    for (const s of samples) {
+        if (s.predicted && s.actual)
+            tp += 1;
+        else if (s.predicted && !s.actual)
+            fp += 1;
+        else if (!s.predicted && !s.actual)
+            tn += 1;
+        else
+            fn += 1;
+    }
+    const precision = tp + fp === 0 ? 0 : tp / (tp + fp);
+    const recall = tp + fn === 0 ? 0 : tp / (tp + fn);
+    const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+    const baseRate = n === 0 ? 0 : (tp + fn) / n;
+    const lift = baseRate === 0 ? 0 : precision / baseRate;
+    const verdict = classifyVerdict(lift, precision, recall, n);
+    return {
+        n,
+        truePositives: tp,
+        falsePositives: fp,
+        trueNegatives: tn,
+        falseNegatives: fn,
+        precision,
+        recall,
+        f1,
+        baseRate,
+        lift,
+        verdict,
+        conclusion: buildConclusion(verdict, n, precision, recall, lift),
+    };
+}
+export function classifyVerdict(lift, precision, recall, n) {
+    if (n < 5)
+        return "no-edge"; // sample too small
+    if (lift >= 2.5 && precision >= 0.6 && recall >= 0.5)
+        return "strong-edge";
+    if (lift >= 1.5 && precision >= 0.4)
+        return "real-edge";
+    if (lift >= 1.1)
+        return "weak";
+    return "no-edge";
+}
+function buildConclusion(verdict, n, precision, recall, lift) {
+    switch (verdict) {
+        case "no-edge":
+            if (n < 5)
+                return `Sample size too small (n=${n}) to draw conclusions.`;
+            return `No detectable edge over random — precision ${(precision * 100).toFixed(0)}%, lift ${lift.toFixed(2)}×.`;
+        case "weak":
+            return `Weak edge — beats random by ${((lift - 1) * 100).toFixed(0)}% but precision is still ${(precision * 100).toFixed(0)}%. Use as a soft prior.`;
+        case "real-edge":
+            return `Real predictive edge — precision ${(precision * 100).toFixed(0)}%, ${lift.toFixed(1)}× over random.`;
+        case "strong-edge":
+            return `Strong edge — precision ${(precision * 100).toFixed(0)}%, recall ${(recall * 100).toFixed(0)}%, ${lift.toFixed(1)}× over random. Trust this predictor.`;
+    }
+}
+/**
+ * Aggregate a backtest result into a one-line markdown badge for the
+ * README / docs. Format: "F1 = 0.67 · 2.4× lift · n=14".
+ */
+export function badge(result) {
+    return `F1 = ${result.f1.toFixed(2)} · ${result.lift.toFixed(1)}× lift · n=${result.n}`;
+}
+//# sourceMappingURL=backtest.js.map