@mneme-ai/core 0.22.2 → 0.23.0

package/dist/retrieve/ddtree.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DDTree — Best-First Search through a commit ancestor tree.
+ *
+ * Inspired by KAT-0B's DDTree (a BinaryHeap-driven candidate exploration
+ * loop bounded by an exploration budget). Mneme uses it under `mneme why`
+ * to walk *back* through parent commits looking for the deepest plausible
+ * "this is why X exists" answer — strictly better than flat semantic
+ * retrieval, which can't follow causal ancestry.
+ *
+ * Semantics:
+ *   1. Caller supplies a `scoreFn(commit, depth, parentScore)` — typically
+ *      relevance × depth-decay × parent-score.
+ *   2. We maintain a max-heap keyed by score and pop the best candidate
+ *      until either the budget is exhausted or the heap is empty.
+ *   3. Each pop is classified: accepted, pruned-floor, pruned-depth, or
+ *      pruned-budget (for nodes still on the heap when budget runs out).
+ *   4. Parents of an accepted node are scored and pushed back in.
+ *
+ * Heap implementation: a simple binary max-heap on a flat array. We avoid
+ * Node v22's experimental `node:priority-queue` for portability — Mneme
+ * supports Node 18+. See `MaxHeap` below.
+ *
+ * Cycle handling: merge commits can — in theory — produce diamond-shaped
+ * ancestry where the same hash appears twice. We track a `visited` Set so
+ * each commit is processed at most once (the first/highest-score path wins).
+ */
+import type { Commit } from "../types.js";
+export interface DDTreeOptions {
+    /** Max nodes to explore (controls cost). Default 32. */
+    budget?: number;
+    /** Max depth from root before pruning. Default 6. */
+    maxDepth?: number;
+    /** Score floor — nodes below this are pruned. Default 0.05. */
+    scoreFloor?: number;
+}
+export interface DDTreeNode {
+    commit: Commit;
+    depth: number;
+    /** Combined score: relevance × decay-by-depth × parent score. */
+    score: number;
+    /** Parent commit hash (the *child* in graph terms — i.e. the node we
+     *  expanded from to reach this commit). Undefined for root nodes. */
+    parent?: string;
+    /** Why this node was pruned, or "accepted". */
+    status: "accepted" | "pruned-floor" | "pruned-depth" | "pruned-budget";
+}
+export interface DDTreeResult {
+    /** All explored nodes with verdict (in pop order). */
+    visited: DDTreeNode[];
+    /** Accepted nodes only, sorted by score (highest first). */
+    accepted: DDTreeNode[];
+    budgetUsed: number;
+}
+/** Score function: relevance × decay-by-depth × log_priors etc. Caller provides. */
+export type ScoreFn = (commit: Commit, depth: number, parentScore: number) => number;
+/** Look up a commit's parent hashes. Caller provides (typically from store). */
+export type ParentResolver = (hash: string) => string[];
+/** Look up a commit by hash. Caller provides. */
+export type CommitResolver = (hash: string) => Commit | undefined;
+/**
+ * Best-First Search through commit ancestors. See module docstring.
+ *
+ * Returns every node we touched (with verdict), the sorted list of
+ * accepted nodes, and how much of the budget we consumed.
+ */
+export declare function exploreDDTree(rootHashes: string[], scoreFn: ScoreFn, parents: ParentResolver, commits: CommitResolver, opts?: DDTreeOptions): DDTreeResult;
+//# sourceMappingURL=ddtree.d.ts.map

package/dist/retrieve/ddtree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddtree.d.ts","sourceRoot":"","sources":["../../src/retrieve/ddtree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd;yEACqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,UAAU,GAAG,cAAc,GAAG,cAAc,GAAG,eAAe,CAAC;CACxE;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;AAErF,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;AAExD,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAqElE;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,aAAkB,GACvB,YAAY,CA+Fd"}

package/dist/retrieve/ddtree.js

@@ -0,0 +1,156 @@
+/**
+ * Simple binary max-heap on score. Stable enough for our needs — when two
+ * nodes tie on score, insertion order roughly wins (heap structure means
+ * "roughly", not "strictly", but this is fine for exploration).
+ */
+class MaxHeap {
+    data = [];
+    get size() {
+        return this.data.length;
+    }
+    push(item) {
+        this.data.push(item);
+        this.siftUp(this.data.length - 1);
+    }
+    pop() {
+        const n = this.data.length;
+        if (n === 0)
+            return undefined;
+        const top = this.data[0];
+        const last = this.data.pop();
+        if (n > 1) {
+            this.data[0] = last;
+            this.siftDown(0);
+        }
+        return top;
+    }
+    /** Drain remaining items (for "pruned-budget" reporting). */
+    drain() {
+        const out = [...this.data];
+        this.data = [];
+        return out;
+    }
+    siftUp(i) {
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (this.data[parent].score >= this.data[i].score)
+                break;
+            [this.data[parent], this.data[i]] = [this.data[i], this.data[parent]];
+            i = parent;
+        }
+    }
+    siftDown(i) {
+        const n = this.data.length;
+        while (true) {
+            const l = 2 * i + 1;
+            const r = 2 * i + 2;
+            let best = i;
+            if (l < n && this.data[l].score > this.data[best].score)
+                best = l;
+            if (r < n && this.data[r].score > this.data[best].score)
+                best = r;
+            if (best === i)
+                break;
+            [this.data[best], this.data[i]] = [this.data[i], this.data[best]];
+            i = best;
+        }
+    }
+}
+/**
+ * Best-First Search through commit ancestors. See module docstring.
+ *
+ * Returns every node we touched (with verdict), the sorted list of
+ * accepted nodes, and how much of the budget we consumed.
+ */
+export function exploreDDTree(rootHashes, scoreFn, parents, commits, opts = {}) {
+    const budget = opts.budget ?? 32;
+    const maxDepth = opts.maxDepth ?? 6;
+    const scoreFloor = opts.scoreFloor ?? 0.05;
+    const heap = new MaxHeap();
+    const visited = [];
+    const seen = new Set(); // cycle / diamond protection
+    let budgetUsed = 0;
+    // Seed: each root scored with parentScore=1 (no prior).
+    for (const hash of rootHashes) {
+        const c = commits(hash);
+        if (!c)
+            continue;
+        const score = scoreFn(c, 0, 1);
+        heap.push({ hash, depth: 0, score });
+    }
+    while (heap.size > 0 && budgetUsed < budget) {
+        const item = heap.pop();
+        if (seen.has(item.hash))
+            continue; // cycle / diamond
+        seen.add(item.hash);
+        const commit = commits(item.hash);
+        if (!commit)
+            continue;
+        budgetUsed++;
+        // Floor check first — cheap and short-circuits deep pruning.
+        if (item.score < scoreFloor) {
+            visited.push({
+                commit,
+                depth: item.depth,
+                score: item.score,
+                parent: item.parent,
+                status: "pruned-floor",
+            });
+            continue;
+        }
+        // Depth check.
+        if (item.depth >= maxDepth) {
+            visited.push({
+                commit,
+                depth: item.depth,
+                score: item.score,
+                parent: item.parent,
+                status: "pruned-depth",
+            });
+            continue;
+        }
+        // Accept and expand.
+        visited.push({
+            commit,
+            depth: item.depth,
+            score: item.score,
+            parent: item.parent,
+            status: "accepted",
+        });
+        const childDepth = item.depth + 1;
+        for (const parentHash of parents(item.hash)) {
+            if (seen.has(parentHash))
+                continue;
+            const parentCommit = commits(parentHash);
+            if (!parentCommit)
+                continue;
+            const childScore = scoreFn(parentCommit, childDepth, item.score);
+            heap.push({
+                hash: parentHash,
+                depth: childDepth,
+                score: childScore,
+                parent: item.hash,
+            });
+        }
+    }
+    // Anything still in the heap when we hit the budget wall is "pruned-budget".
+    for (const leftover of heap.drain()) {
+        if (seen.has(leftover.hash))
+            continue;
+        const c = commits(leftover.hash);
+        if (!c)
+            continue;
+        visited.push({
+            commit: c,
+            depth: leftover.depth,
+            score: leftover.score,
+            parent: leftover.parent,
+            status: "pruned-budget",
+        });
+    }
+    const accepted = visited
+        .filter((n) => n.status === "accepted")
+        .sort((a, b) => b.score - a.score);
+    return { visited, accepted, budgetUsed };
+}
+//# sourceMappingURL=ddtree.js.map

package/dist/retrieve/ddtree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddtree.js","sourceRoot":"","sources":["../../src/retrieve/ddtree.ts"],"names":[],"mappings":"AAyEA;;;;GAIG;AACH,MAAM,OAAO;IACH,IAAI,GAAe,EAAE,CAAC;IAE9B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED,IAAI,CAAC,IAAc;QACjB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,GAAG;QACD,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAG,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,6DAA6D;IAC7D,KAAK;QACH,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,MAAM,CAAC,CAAS;QACtB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAE,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK;gBAAE,MAAM;YAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAE,CAAC,CAAC;YACxE,CAAC,GAAG,MAAM,CAAC;QACb,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,CAAS;QACxB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC,KAAK;gBAAE,IAAI,GAAG,CAAC,CAAC;YACpE,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC,KAAK;gBAAE,IAAI,GAAG,CAAC,CAAC;YACpE,IAAI,IAAI,KAAK,CAAC;gBAAE,MAAM;YACtB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC,CAAC;YACpE,CAAC,GAAG,IAAI,CAAC;QACX,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAoB,EACpB,OAAgB,EAChB,OAAuB,EACvB,OAAuB,EACvB,OAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC;IAE3C,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC,CAAC,6BAA6B;IAC7D,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,wDAAwD;IACxD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,UAAU,GAAG,MAAM,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAG,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,kBAAkB;QACrD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEpB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM;YAAE,SAAS;QAEtB,UAAU,EAAE,CAAC;QAEb,6DAA6D;QAC7D,IAAI,IAAI,CAAC,KAAK,GAAG,UAAU,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,cAAc;aACvB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,eAAe;QACf,IAAI,IAAI,CAAC,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,cAAc;aACvB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,qBAAqB;QACrB,OAAO,CAAC,IAAI,CAAC;YACX,MAAM;YACN,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,UAAU;SACnB,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QAClC,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,SAAS;YACnC,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;YACzC,IAAI,CAAC,YAAY;gBAAE,SAAS;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACjE,IAAI,CAAC,IAAI,CAAC;gBACR,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,UAAU;gBACjB,MAAM,EAAE,IAAI,CAAC,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QACtC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,OAAO,CAAC,IAAI,CAAC;YACX,MAAM,EAAE,CAAC;YACT,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,MAAM,EAAE,eAAe;SACxB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO;SACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC;SACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAErC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAC3C,CAAC"}

package/dist/retrieve/ddtree.test.d.ts

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

package/dist/retrieve/ddtree.test.d.ts.map

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

package/dist/retrieve/ddtree.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import { exploreDDTree } from "./ddtree.js";
+/** Build a fake commit. We only care about hash for tree shape; everything
+ *  else is filled with throwaway values to satisfy the type. */
+function makeCommit(hash, parents = []) {
+    return {
+        hash,
+        shortHash: hash.slice(0, 7),
+        authorName: "Test",
+        authorEmail: "test@example.com",
+        authorDate: "2025-01-01T00:00:00Z",
+        committerDate: "2025-01-01T00:00:00Z",
+        subject: `commit ${hash}`,
+        body: "",
+        files: [],
+        parents,
+    };
+}
+/** Build resolvers from a flat list of commits. */
+function makeResolvers(commits) {
+    const byHash = new Map(commits.map((c) => [c.hash, c]));
+    return {
+        parents: (h) => byHash.get(h)?.parents ?? [],
+        commits: (h) => byHash.get(h),
+    };
+}
+describe("exploreDDTree — basic ancestry walk", () => {
+    it("explores root → 3 parents and accepts all under generous budget", () => {
+        // Tree:  A -> B, C, D    (A has three parents)
+        const a = makeCommit("A", ["B", "C", "D"]);
+        const b = makeCommit("B", []);
+        const c = makeCommit("C", []);
+        const d = makeCommit("D", []);
+        const { parents, commits } = makeResolvers([a, b, c, d]);
+        // Constant score 1.0 — everything stays well above the floor.
+        const score = () => 1;
+        const result = exploreDDTree(["A"], score, parents, commits, {
+            budget: 5,
+            maxDepth: 6,
+            scoreFloor: 0.05,
+        });
+        expect(result.budgetUsed).toBe(4);
+        expect(result.accepted.map((n) => n.commit.hash).sort()).toEqual([
+            "A",
+            "B",
+            "C",
+            "D",
+        ]);
+        expect(result.visited.every((n) => n.status === "accepted")).toBe(true);
+    });
+    it("records parent hash for each non-root accepted node", () => {
+        const a = makeCommit("A", ["B"]);
+        const b = makeCommit("B", []);
+        const { parents, commits } = makeResolvers([a, b]);
+        const r = exploreDDTree(["A"], () => 1, parents, commits, { budget: 5 });
+        const accB = r.accepted.find((n) => n.commit.hash === "B");
+        expect(accB?.parent).toBe("A");
+        const accA = r.accepted.find((n) => n.commit.hash === "A");
+        expect(accA?.parent).toBeUndefined();
+    });
+});
+describe("exploreDDTree — pruning", () => {
+    it("prunes deep nodes when depth >= maxDepth", () => {
+        // Linear chain A -> B -> C -> D -> E
+        const chain = ["A", "B", "C", "D", "E"].map((h, i, arr) => makeCommit(h, arr[i + 1] ? [arr[i + 1]] : []));
+        const { parents, commits } = makeResolvers(chain);
+        const r = exploreDDTree(["A"], () => 1, parents, commits, {
+            budget: 100,
+            maxDepth: 2, // accept depths 0, 1; prune at depth 2
+            scoreFloor: 0,
+        });
+        const acc = r.accepted.map((n) => `${n.commit.hash}@${n.depth}`).sort();
+        expect(acc).toEqual(["A@0", "B@1"]);
+        const prunedDepth = r.visited.filter((n) => n.status === "pruned-depth");
+        expect(prunedDepth.map((n) => n.commit.hash)).toEqual(["C"]);
+    });
+    it("prunes nodes whose score falls below the scoreFloor", () => {
+        // A -> B; score decays exponentially with depth.
+        const a = makeCommit("A", ["B"]);
+        const b = makeCommit("B", []);
+        const { parents, commits } = makeResolvers([a, b]);
+        // depth 0 -> 1.0, depth 1 -> 0.01 (below floor 0.05)
+        const score = (_c, depth) => Math.pow(0.01, depth);
+        const r = exploreDDTree(["A"], score, parents, commits, {
+            budget: 100,
+            maxDepth: 6,
+            scoreFloor: 0.05,
+        });
+        expect(r.accepted.map((n) => n.commit.hash)).toEqual(["A"]);
+        const floored = r.visited.filter((n) => n.status === "pruned-floor");
+        expect(floored.map((n) => n.commit.hash)).toEqual(["B"]);
+    });
+    it("marks remaining heap as pruned-budget when budget exhausted", () => {
+        // Wide tree: root A with parents B,C,D,E,F (5 parents).
+        const a = makeCommit("A", ["B", "C", "D", "E", "F"]);
+        const others = ["B", "C", "D", "E", "F"].map((h) => makeCommit(h, []));
+        const { parents, commits } = makeResolvers([a, ...others]);
+        // Distinct scores so only the highest-score parents get accepted first.
+        const scoreMap = { A: 1, B: 0.9, C: 0.8, D: 0.7, E: 0.6, F: 0.5 };
+        const score = (c) => scoreMap[c.hash];
+        const r = exploreDDTree(["A"], score, parents, commits, {
+            budget: 3, // accept A + 2 best parents; rest -> pruned-budget
+            maxDepth: 6,
+            scoreFloor: 0,
+        });
+        expect(r.budgetUsed).toBe(3);
+        expect(r.accepted.map((n) => n.commit.hash)).toEqual(["A", "B", "C"]);
+        const budgetPruned = r.visited.filter((n) => n.status === "pruned-budget");
+        expect(budgetPruned.map((n) => n.commit.hash).sort()).toEqual([
+            "D",
+            "E",
+            "F",
+        ]);
+    });
+});
+describe("exploreDDTree — robustness", () => {
+    it("handles a cycle in the parent graph without looping forever", () => {
+        // Pathological: A -> B, B -> A (cycle).
+        const a = makeCommit("A", ["B"]);
+        const b = makeCommit("B", ["A"]);
+        const { parents, commits } = makeResolvers([a, b]);
+        const r = exploreDDTree(["A"], () => 1, parents, commits, {
+            budget: 100,
+            maxDepth: 10,
+            scoreFloor: 0,
+        });
+        // Should terminate; each node visited once.
+        expect(r.accepted.map((n) => n.commit.hash).sort()).toEqual(["A", "B"]);
+        expect(r.budgetUsed).toBe(2);
+    });
+    it("handles a diamond (merge) — same hash reachable two ways, processed once", () => {
+        // A -> B, A -> C, both B and C -> D.
+        const a = makeCommit("A", ["B", "C"]);
+        const b = makeCommit("B", ["D"]);
+        const c = makeCommit("C", ["D"]);
+        const d = makeCommit("D", []);
+        const { parents, commits } = makeResolvers([a, b, c, d]);
+        const r = exploreDDTree(["A"], () => 1, parents, commits, {
+            budget: 100,
+            maxDepth: 10,
+            scoreFloor: 0,
+        });
+        const dCount = r.visited.filter((n) => n.commit.hash === "D").length;
+        expect(dCount).toBe(1);
+        expect(r.accepted.map((n) => n.commit.hash).sort()).toEqual([
+            "A",
+            "B",
+            "C",
+            "D",
+        ]);
+    });
+    it("ignores root hashes that don't resolve to a commit", () => {
+        const a = makeCommit("A", []);
+        const { parents, commits } = makeResolvers([a]);
+        const r = exploreDDTree(["MISSING", "A"], () => 1, parents, commits, {
+            budget: 5,
+        });
+        expect(r.accepted.map((n) => n.commit.hash)).toEqual(["A"]);
+    });
+    it("returns an empty result when no roots resolve", () => {
+        const { parents, commits } = makeResolvers([]);
+        const r = exploreDDTree(["NOPE"], () => 1, parents, commits);
+        expect(r.accepted).toEqual([]);
+        expect(r.visited).toEqual([]);
+        expect(r.budgetUsed).toBe(0);
+    });
+    it("orders accepted by score descending", () => {
+        const a = makeCommit("A", ["B", "C"]);
+        const b = makeCommit("B", []);
+        const c = makeCommit("C", []);
+        const { parents, commits } = makeResolvers([a, b, c]);
+        const scores = { A: 0.5, B: 0.9, C: 0.7 };
+        const r = exploreDDTree(["A"], (cm) => scores[cm.hash], parents, commits, {
+            budget: 5,
+            scoreFloor: 0,
+        });
+        const order = r.accepted.map((n) => n.commit.hash);
+        expect(order).toEqual(["B", "C", "A"]);
+    });
+});
+//# sourceMappingURL=ddtree.test.js.map

package/dist/retrieve/ddtree.test.js.map

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

package/dist/retrieve/index.d.ts

@@ -3,4 +3,7 @@ export * from "./rerank.js";
 export * from "./intent.js";
 export * from "./synthesize.js";
 export * from "./novel-scoring.js";
+export * from "./ddtree.js";
+export * from "./stream.js";
+export * from "./leviathan.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/retrieve/index.js

@@ -3,4 +3,7 @@ export * from "./rerank.js";
 export * from "./intent.js";
 export * from "./synthesize.js";
 export * from "./novel-scoring.js";
+export * from "./ddtree.js";
+export * from "./stream.js";
+export * from "./leviathan.js";
 //# sourceMappingURL=index.js.map

package/dist/retrieve/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieve/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/retrieve/leviathan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Leviathan citation verification — speculative-decoding-style draft/target
+ * loop applied to LLM answers.
+ *
+ * Algorithm 1 from the Leviathan paper: a fast "draft" model proposes,
+ * a strict "target" rejects un-supported tokens, residual sampling re-drafts.
+ *
+ * Mneme's adaptation:
+ *   - Draft     = the LLM's synthesized answer (already produced by `synthesize()`)
+ *   - Target    = a deterministic citation matcher (each backticked hash must
+ *                 exist in the evidence pool AND the surrounding sentence must
+ *                 contextually match the cited commit's subject)
+ *   - Reject    = mark the unverified claim with `[unverified: ...]` so the
+ *                 user sees what was filtered (no silent deletion)
+ *   - Residual  = `degraded: true` when too many rejections — caller should
+ *                 warn the user that trust is reduced
+ *
+ * The keyword/token-overlap match is intentionally lightweight (no embedding
+ * call). Cosine on a sentence-level embedding would be more accurate but
+ * Mneme's core stays dep-free; embeddings live in the embeddings package and
+ * we don't want a runtime cycle. Empirically the 0.2 token-overlap floor
+ * catches "hash present, sentence completely unrelated" without flagging
+ * legitimate paraphrases.
+ */
+import type { EventSink } from "./stream.js";
+export interface LeviathanInput {
+    /** The raw LLM answer text. */
+    answer: string;
+    /** Evidence pool (ordered by relevance). Each must have hash + subject. */
+    evidence: Array<{
+        hash: string;
+        shortHash: string;
+        subject: string;
+    }>;
+    /** Optional event sink for tracing rejections. */
+    events?: EventSink;
+}
+/** Per-claim verdict. */
+export type LeviathanVerdict = "verified" | "hash-not-in-evidence" | "claim-not-supported" | "no-citation";
+export interface LeviathanResult {
+    /** The cleaned answer with unverified claims wrapped in `[unverified: ...]`. */
+    cleanedAnswer: string;
+    /** Per-claim verification trace. */
+    verifications: Array<{
+        claimText: string;
+        citedHash?: string;
+        verdict: LeviathanVerdict;
+        reason: string;
+    }>;
+    /** 0..1 — fraction of citation-bearing claims that verified. */
+    trustScore: number;
+    /** True if too many rejections (trustScore < 0.6). */
+    degraded: boolean;
+}
+/**
+ * Run Algorithm-1-style verification on an LLM answer.
+ *
+ * The loop is single-pass (we don't actually re-draft, since the answer is
+ * already paid-for). Instead we tag rejected spans inline so the renderer
+ * can dim/strikethrough them.
+ */
+export declare function verifyAnswerLeviathan(input: LeviathanInput): LeviathanResult;
+/**
+ * Lightweight Jaccard-like token overlap: shared tokens / total unique tokens
+ * after dropping stopwords + the cited hash itself. Symmetric, in [0,1].
+ */
+export declare function tokenOverlap(sentence: string, subject: string): number;
+//# sourceMappingURL=leviathan.d.ts.map

package/dist/retrieve/leviathan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leviathan.d.ts","sourceRoot":"","sources":["../../src/retrieve/leviathan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,kDAAkD;IAClD,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,yBAAyB;AACzB,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,sBAAsB,GACtB,qBAAqB,GACrB,aAAa,CAAC;AAElB,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,aAAa,EAAE,KAAK,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,gBAAgB,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAQD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CA6E5E;AAiDD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQtE"}