@mneme-ai/core 0.9.0 → 0.10.0

package/dist/insights/regret.test.js

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest";
+import { detectRegrets, summarizeRegrets } from "./regret.js";
+const cmt = (hash, date, subject, body = "", files = []) => ({
+    hash,
+    shortHash: hash.slice(0, 7),
+    authorName: "alice",
+    authorEmail: "alice@x",
+    authorDate: `${date}T12:00:00Z`,
+    committerDate: `${date}T12:00:00Z`,
+    subject,
+    body,
+    parents: [],
+    files,
+});
+describe("detectRegrets — revert (strongest signal)", () => {
+    it("detects explicit revert that names the shipped commit hash", () => {
+        const commits = [
+            cmt("a1b2c3d", "2024-08-01", "feat: enable HTTP/3", "", ["src/edge.ts"]),
+            cmt("e4f5g6h", "2024-08-03", "Revert \"feat: enable HTTP/3\"", "Reverts a1b2c3d — broke mobile", ["src/edge.ts"]),
+        ];
+        const regrets = detectRegrets(commits, { windowDays: 7 });
+        expect(regrets).toHaveLength(1);
+        expect(regrets[0].kind).toBe("revert");
+        expect(regrets[0].daysToFix).toBeCloseTo(2, 0);
+    });
+    it("detects revert from shared-files heuristic when subject is generic", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: new caching", "", ["src/cache.ts"]),
+            cmt("a2", "2024-08-04", "revert caching change", "", ["src/cache.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("revert");
+    });
+});
+describe("detectRegrets — hotfix and fix kinds", () => {
+    it("flags hotfix when follow-up has 'hotfix' marker AND shares files", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "refactor: simplify session middleware", "", ["src/auth.ts"]),
+            cmt("a2", "2024-08-01", "hotfix: CSRF check disappeared in refactor", "", ["src/auth.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("hotfix");
+    });
+    it("flags 'fix' kind when follow-up is a generic fix touching same files", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "perf: cache user lookup", "", ["src/users.ts"]),
+            cmt("a2", "2024-08-04", "fix: cache invalidation race", "", ["src/users.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("fix");
+    });
+    it("doesn't double-flag commits that ARE themselves fixes", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "fix: typo", "", ["README.md"]),
+            cmt("a2", "2024-08-02", "fix: another typo", "", ["README.md"]),
+        ];
+        // Neither is a regret — both are fix-shaped subjects.
+        expect(detectRegrets(commits)).toEqual([]);
+    });
+});
+describe("detectRegrets — window enforcement", () => {
+    it("respects the windowDays cutoff", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-15", "fix: thing broke", "", ["x.ts"]), // 14 days later
+        ];
+        expect(detectRegrets(commits, { windowDays: 7 })).toEqual([]);
+        expect(detectRegrets(commits, { windowDays: 30 })).toHaveLength(1);
+    });
+    it("respects minDaysToFix lower bound (filter out same-day micro-fixes)", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-01", "fix: typo", "", ["x.ts"]),
+        ];
+        expect(detectRegrets(commits, { minDaysToFix: 1 })).toEqual([]);
+        expect(detectRegrets(commits, { minDaysToFix: 0 })).toHaveLength(1);
+    });
+});
+describe("detectRegrets — only one regret per shipped commit", () => {
+    it("returns the first follow-up only (avoids double-counting)", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: first attempt at fix", "", ["x.ts"]),
+            cmt("a3", "2024-08-04", "fix: second attempt", "", ["x.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        expect(regrets).toHaveLength(1);
+        expect(regrets[0].followup.shortHash).toBe("a2");
+    });
+});
+describe("detectRegrets — output ordering and content", () => {
+    it("sorts results by ship date descending (newest regret first)", () => {
+        const commits = [
+            cmt("old1", "2024-01-01", "feat: a", "", ["x.ts"]),
+            cmt("old2", "2024-01-02", "fix: a broke", "", ["x.ts"]),
+            cmt("new1", "2024-08-01", "feat: b", "", ["y.ts"]),
+            cmt("new2", "2024-08-03", "fix: b broke", "", ["y.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        expect(regrets).toHaveLength(2);
+        expect(regrets[0].shipped.shortHash).toBe("new1");
+        expect(regrets[1].shipped.shortHash).toBe("old1");
+    });
+    it("attaches a lesson string when the follow-up body has explanatory text", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: thing crashed", "the cache invalidation was racing with the eviction sweep", ["x.ts"]),
+        ];
+        const r = detectRegrets(commits)[0];
+        expect(r.lesson).toContain("cache invalidation");
+    });
+});
+describe("summarizeRegrets — repo-level metrics", () => {
+    it("computes regretRate over non-fix shipped commits", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: A broke", "", ["x.ts"]),
+            cmt("a3", "2024-08-03", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-04", "feat: C", "", ["z.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        const summary = summarizeRegrets(commits, regrets);
+        // Non-fix shipped: a1, a3, a4 → 3 candidates. 1 regret. → 1/3 ≈ 0.33
+        expect(summary.totalShipped).toBe(3);
+        expect(summary.totalRegrets).toBe(1);
+        expect(summary.regretRate).toBeCloseTo(1 / 3, 2);
+    });
+    it("counts byKind correctly", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "Revert \"feat: A\"", "", ["x.ts"]),
+            cmt("a3", "2024-08-03", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-04", "hotfix: B explosion", "", ["y.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        const summary = summarizeRegrets(commits, regrets);
+        expect(summary.byKind.revert).toBe(1);
+        expect(summary.byKind.hotfix).toBe(1);
+    });
+    it("reports averageDaysToFix", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-03", "fix: A", "", ["x.ts"]), // 2 days
+            cmt("a3", "2024-08-10", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-14", "fix: B", "", ["y.ts"]), // 4 days
+        ];
+        const summary = summarizeRegrets(commits, detectRegrets(commits));
+        expect(summary.averageDaysToFix).toBeCloseTo(3, 1);
+    });
+    it("returns 0 metrics when there are no regrets", () => {
+        const summary = summarizeRegrets([cmt("a", "2024-08-01", "feat: stable", "", ["x"])], []);
+        expect(summary.regretRate).toBe(0);
+        expect(summary.averageDaysToFix).toBe(0);
+    });
+});
+//# sourceMappingURL=regret.test.js.map

package/dist/insights/regret.test.js.map

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

package/dist/insights/who-knows.d.ts

@@ -45,4 +45,22 @@ export declare function whoKnows(store: MnemeStore, opts: WhoKnowsOptions): Expe
 /** log-based commit weight × recency multiplier. Pure function, easy to test. */
 export declare function scoreCandidate(commitCount: number, lastTouchIso: string, now: Date): number;
 export declare function tierOf(commitCount: number, lastTouchIso: string, now: Date): ExpertCandidate["tier"];
+/**
+ * Verdict-shaped summary built from the full candidate list. Surfaces the
+ * single most likely person to ask + a confidence percentage + a fallback
+ * recommendation, instead of letting the user scan a list of names.
+ */
+export interface ExpertVerdict {
+    /** The single most likely expert (or undefined when no candidates). */
+    topExpert?: ExpertCandidate;
+    /** Confidence percentage 0..100 — share of total commits attributed to the top. */
+    confidencePct: number;
+    /** Backup expert if the top is stale or has insufficient share. */
+    backup?: ExpertCandidate;
+    /** A 1-line risk note when the top expert is stale or shares too thinly. */
+    risk?: string;
+    /** Total commits matched across all candidates (sum of commitCount). */
+    totalCommits: number;
+}
+export declare function whoKnowsVerdict(candidates: ExpertCandidate[]): ExpertVerdict;
 //# sourceMappingURL=who-knows.d.ts.map

package/dist/insights/who-knows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"who-knows.d.ts","sourceRoot":"","sources":["../../src/insights/who-knows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CA6DpF;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAQ3F;AAED,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAOpG"}
+{"version":3,"file":"who-knows.d.ts","sourceRoot":"","sources":["../../src/insights/who-knows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CA6DpF;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAQ3F;AAED,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAOpG;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,aAAa,CAoB5E"}

package/dist/insights/who-knows.js

@@ -93,4 +93,33 @@ export function tierOf(commitCount, lastTouchIso, now) {
         return "stale";
     return "occasional";
 }
+export function whoKnowsVerdict(candidates) {
+    if (candidates.length === 0) {
+        return { confidencePct: 0, totalCommits: 0 };
+    }
+    const sorted = [...candidates].sort((a, b) => b.score - a.score);
+    const top = sorted[0];
+    const total = candidates.reduce((s, c) => s + c.commitCount, 0);
+    const pct = total === 0 ? 0 : Math.round((top.commitCount / total) * 100);
+    const backup = sorted[1];
+    let risk;
+    if (top.tier === "stale") {
+        risk = `Top expert is STALE — last touched ${formatDaysAgo(top.lastTouch)} ago. Consider asking ${backup?.name ?? "someone with recent activity"} instead.`;
+    }
+    else if (pct < 30 && candidates.length >= 3) {
+        risk = `No single dominant expert — ${candidates.length} people share the work. Knowledge is well-distributed but no one will know everything.`;
+    }
+    else if (top.commitCount === 1) {
+        risk = "Top expert touched the topic only once — treat as weak signal.";
+    }
+    return { topExpert: top, confidencePct: pct, backup, risk, totalCommits: total };
+}
+function formatDaysAgo(iso) {
+    const d = (Date.now() - new Date(iso).getTime()) / 86_400_000;
+    if (d < 30)
+        return `${Math.round(d)}d`;
+    if (d < 365)
+        return `${Math.round(d / 30)}mo`;
+    return `${(d / 365).toFixed(1)}y`;
+}
 //# sourceMappingURL=who-knows.js.map

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

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

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { scoreCandidate, tierOf } from "./who-knows.js";
+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", () => {
@@ -44,4 +44,66 @@ describe("tierOf — readable expert tier", () => {
         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

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