pi-mega-compact 0.11.3 → 0.11.5

package/src/dedup/raptor/raptor.test.ts

@@ -1,297 +0,0 @@
-/**
- * raptor.test.ts — hermetic unit tests for the Sprint 13 RAPTOR module.
- *
- * No network: the default summarizer is deterministic extractive, and Ollama is
- * only reached when MEGACOMPACT_RAPTOR_MODEL is set (never here). Retrieval from
- * the live store is never touched (shadow mode), so recallAndInline output is
- * unchanged by construction.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { TrigramEmbedder } from "../../embedder.js";
-import { kmeanspp } from "./kmeans.js";
-import {
-  applyHallucinationGuardrails,
-  sourceTokenSet,
-  extractEntities,
-  makeUngroundedSummary,
-} from "./guardrails.js";
-import { buildRaptorTree, type Leaf } from "./tree.js";
-import { stagedExpansion } from "./retrieval.js";
-import { runRaptor } from "./index.js";
-import { Logger } from "../../log.js";
-import {
-  listRaptorNodes,
-  clearRaptorNodes,
-  closeStore,
-} from "../../store/sqlite.js";
-import type { EngineMessage } from "../../types.js";
-
-const baseTmp = mkdtempSync(join(tmpdir(), "mc-raptor-"));
-
-function msg(text: string): EngineMessage {
-  return { role: "user", text };
-}
-
-/** Build N distinct leaves with deterministic content. */
-function makeLeaves(n: number, embedder = new TrigramEmbedder()): Leaf[] {
-  const leaves: Leaf[] = [];
-  for (let i = 0; i < n; i++) {
-    const text = `topic ${i % 7}: the module ${i} validated the session token and refreshed the cache for region ${i}`;
-    leaves.push({
-      id: `leaf_${i}`,
-      messages: [msg(text)],
-      sourceText: text,
-      embedding: embedder.embed(text),
-    });
-  }
-  return leaves;
-}
-
-// --- kmeans: near-zero-variance merge guard ---------------------------------
-
-test("kmeanspp merges identical points into a single cluster (QA #11)", () => {
-  const p = [1, 0, 0];
-  const points = [p, p, p, p, p];
-  const r = kmeanspp(points, 3, { seed: 1 });
-  assert.equal(r.k, 1);
-  assert.deepEqual(r.assignments, [0, 0, 0, 0, 0]);
-});
-
-test("kmeanspp separates two well-separated clusters", () => {
-  const a = [1, 0, 0];
-  const b = [0, 1, 0];
-  const points = [a, a, a, b, b, b];
-  const r = kmeanspp(points, 2, { seed: 7 });
-  assert.equal(r.k, 2);
-  // All the a's share one assignment, all the b's another.
-  const firstGroup = r.assignments[0];
-  const secondGroup = r.assignments[3];
-  assert.notEqual(firstGroup, secondGroup);
-  for (let i = 0; i < 3; i++) assert.equal(r.assignments[i], firstGroup);
-  for (let i = 3; i < 6; i++) assert.equal(r.assignments[i], secondGroup);
-});
-
-// --- guardrails: catch hallucination (QA #16) ------------------------------
-
-test("guardrails flag an un-grounded entity as extractive_fallback", () => {
-  const embedder = new TrigramEmbedder();
-  const realSource = "the auth module validates the session token";
-  const summary = makeUngroundedSummary(realSource, "ZkPhant0mCorp");
-  const sources = [realSource];
-  const r = applyHallucinationGuardrails({
-    summary,
-    sources,
-    centroid: embedder.embed(realSource),
-    embedder,
-    sourceTokens: sourceTokenSet(sources),
-  });
-  assert.equal(r.marker, "extractive_fallback");
-  assert.equal(r.grounded, false);
-});
-
-test("guardrails pass a faithful, grounded summary", () => {
-  const embedder = new TrigramEmbedder();
-  const src = "the auth module validates the session token and refreshes the cache";
-  const summary = "the auth module validates the session token";
-  const sources = [src];
-  const r = applyHallucinationGuardrails({
-    summary,
-    sources,
-    centroid: embedder.embed(src),
-    embedder,
-    sourceTokens: sourceTokenSet(sources),
-  });
-  assert.equal(r.grounded, true);
-  assert.ok(r.marker === "high" || r.marker === "low");
-  assert.notEqual(r.marker, "extractive_fallback");
-});
-
-test("extractEntities lowercases candidate tokens", () => {
-  const e = extractEntities("The AuthModule validates the token_abc 42 times");
-  assert.ok(e.includes("authmodule"));
-  assert.ok(e.includes("token_abc"));
-});
-
-// --- tree: <10 leaves → single node -----------------------------------------
-
-test("tree with <10 leaves yields a single root node", () => {
-  const leaves = makeLeaves(5);
-  const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder() });
-  assert.equal(tree.nodes.size, 1);
-  assert.equal(tree.rootId, "r0_0");
-  assert.equal(tree.levels, 1);
-  assert.equal(tree.timedOut, false);
-});
-
-// --- tree: 1K fixture builds within budget ----------------------------------
-
-test("tree builds within 5s on a 1000-leaf fixture", () => {
-  const leaves = makeLeaves(1000);
-  const t0 = Date.now();
-  const tree = buildRaptorTree(leaves, {
-    embedder: new TrigramEmbedder(),
-    budgetMs: 5000,
-    clustersPerLevel: 8,
-  });
-  const elapsed = Date.now() - t0;
-  assert.ok(elapsed < 5000, `build took ${elapsed}ms (over 5s budget)`);
-  assert.ok(tree.nodes.size > 1, "expected a multi-level tree");
-  assert.ok(tree.rootId !== null);
-});
-
-// --- tree: budget timeout → extractive fallback root ------------------------
-
-test("tree respects the budget: a tiny budget forces an extractive fallback root", () => {
-  const leaves = makeLeaves(200);
-  const tree = buildRaptorTree(leaves, {
-    embedder: new TrigramEmbedder(),
-    budgetMs: 0, // forces immediate timeout on the first level
-    clustersPerLevel: 4,
-  });
-  assert.equal(tree.timedOut, true);
-  assert.equal(tree.rootId, "r99_0");
-  assert.ok(tree.nodes.has("r99_0"));
-});
-
-// --- extractiveFallbackRoot returns levels: 100 ------------------------------
-
-test("extractiveFallbackRoot returns levels: 100 (via zero budget)", () => {
-  const leaves = makeLeaves(50);
-  const tree = buildRaptorTree(leaves, {
-    embedder: new TrigramEmbedder(),
-    budgetMs: 0, // forces extractive fallback on first within() check
-    clustersPerLevel: 4,
-  });
-  assert.equal(tree.timedOut, true);
-  assert.equal(tree.levels, 100, "extractive fallback root must report levels: 100");
-  assert.ok(tree.rootId, "fallback root has a rootId");
-  const root = tree.nodes.get(tree.rootId!);
-  assert.ok(root, "fallback root node exists in nodes map");
-  assert.equal(root!.level, 99, "fallback root node level is 99");
-  assert.equal(root!.parentId, null, "fallback root parentId is null");
-});
-
-// --- parentId population on a multi-level tree --------------------------------
-
-test("buildRaptorTree populates parentId for non-root internal nodes, root keeps null", () => {
-  const embedder = new TrigramEmbedder();
-  // >= 10 leaves with clustersPerLevel small enough to produce 2 levels
-  // of internal nodes (level-1 cluster nodes + level-2 root via collapse).
-  const leaves = makeLeaves(20);
-  const tree = buildRaptorTree(leaves, { embedder, clustersPerLevel: 4 });
-
-  // Must have at least 2 levels of internal nodes.
-  assert.ok(tree.levels >= 2, `expected >= 2 levels, got ${tree.levels}`);
-  assert.ok(tree.rootId, "tree must have a root");
-
-  // The root keeps parentId null.
-  const root = tree.nodes.get(tree.rootId!);
-  assert.ok(root, "root node in map");
-  assert.equal(root!.parentId, null, "root parentId must be null");
-
-  // Every non-root internal node must have a non-null parentId pointing to
-  // another node in the tree (its parent).
-  let nonRootCount = 0;
-  for (const node of tree.nodes.values()) {
-    if (node.id === tree.rootId) continue;
-    nonRootCount++;
-    assert.ok(
-      node.parentId !== null,
-      `non-root node ${node.id} must have non-null parentId`,
-    );
-    assert.ok(
-      tree.nodes.has(node.parentId!),
-      `parentId ${node.parentId} of node ${node.id} must exist in tree`,
-    );
-    assert.notEqual(
-      node.parentId,
-      node.id,
-      `node ${node.id} must not be its own parent`,
-    );
-  }
-  assert.ok(nonRootCount > 0, "tree must have at least one non-root internal node");
-});
-
-// --- retrieval: staged expansion returns leaf ids ---------------------------
-
-test("stagedExpansion returns diversified leaf ids for a query", () => {
-  const leaves = makeLeaves(20);
-  const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder(), clustersPerLevel: 4 });
-  const hits = stagedExpansion("the auth module validates the session token", tree, {
-    embedder: new TrigramEmbedder(),
-    k: 3,
-    topM: 3,
-  });
-  assert.ok(hits.length > 0);
-  assert.ok(hits.length <= 3);
-  // All returned ids are raw leaf ids (not internal node ids).
-  for (const id of hits) assert.ok(id.startsWith("leaf_"));
-});
-
-// --- shadow mode: builds + persists, never alters retrieval -----------------
-
-test("runRaptor builds + persists a shadow tree without throwing", () => {
-  const dir = join(baseTmp, `shadow-${Math.floor(performance.now())}`);
-  const leaves = makeLeaves(40);
-  const logger = new Logger({
-    enabled: true,
-    now: () => 0,
-    path: join(dir, "events.log"),
-  });
-  const tree = runRaptor(leaves, {
-    stateDir: dir,
-    sessionId: "sess_raptor",
-    embedder: new TrigramEmbedder(),
-    logger,
-  });
-  assert.ok(tree !== null);
-  // Tree was persisted to raptor_nodes.
-  const stored = listRaptorNodes("sess_raptor", dir);
-  assert.ok(stored.length > 0, "shadow tree should be persisted");
-  // Quality markers are valid values.
-  for (const n of stored) {
-    assert.ok(["high", "low", "extractive_fallback"].includes(n.qualityMarker) || n.qualityMarker === "low");
-  }
-  clearRaptorNodes("sess_raptor", dir);
-  closeStore(dir);
-});
-
-test("shadow mode does NOT change recallAndInline output (separation)", () => {
-  // The orchestrator persists to raptor_nodes only. The live store's
-  // recallAndInline path (vectorStore.search) reads context_chunks, never
-  // raptor_nodes, so building a RAPTOR tree is observably independent.
-  const dir = join(baseTmp, `sep-${Math.floor(performance.now())}`);
-  const leaves = makeLeaves(15);
-  const before = listRaptorNodes("sess_sep", dir);
-  runRaptor(leaves, {
-    stateDir: dir,
-    sessionId: "sess_sep",
-    embedder: new TrigramEmbedder(),
-  });
-  const after = listRaptorNodes("sess_sep", dir);
-  // Building RAPTOR only ever writes raptor_nodes; context_chunks is untouched.
-  assert.deepEqual(before, []);
-  assert.ok(after.length > 0);
-  clearRaptorNodes("sess_sep", dir);
-  closeStore(dir);
-});
-
-// --- eval: redundancy reduction ≥ 15% (nodes << leaves) ---------------------
-
-test("eval: RAPTOR reduces node count substantially vs flat (≥15%)", () => {
-  const leaves = makeLeaves(100);
-  const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder(), clustersPerLevel: 8 });
-  const reduction = 1 - tree.nodes.size / leaves.length;
-  assert.ok(reduction >= 0.15, `redundancy reduction ${reduction.toFixed(2)} < 0.15`);
-});
-
-// --- cleanup ----------------------------------------------------------------
-
-test("RAPTOR cleanup", () => {
-  rmSync(baseTmp, { recursive: true, force: true });
-});

package/src/dedup/raptor/retrieval.test.ts

@@ -1,118 +0,0 @@
-/**
- * retrieval.test.ts — unit tests for the reverse-index parent lookup.
- *
- * Verifies that buildChildParentIndex (retrieval.ts) produces the same
- * parent for each leaf as the old linear-scan semantics:
- *   [...tree.nodes.values()].find(n => n.children.includes(lid))
- *
- * Uses a hand-built tree with a known structure so the comparison is
- * deterministic and independent of the tree builder.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { buildChildParentIndex } from "./retrieval.js";
-import type { RaptorTree, RaptorNode } from "./tree.js";
-
-/** Build a minimal hand-crafted RaptorTree with 2 levels of internal nodes. */
-function handBuiltTree(): RaptorTree {
-  // 8 leaves (leaf_0..leaf_7) under 2 level-1 nodes, under 1 root.
-  const r1_0: RaptorNode = {
-    id: "r1_0",
-    level: 1,
-    parentId: null, // will be set by builder in production, but not needed here
-    children: ["leaf_0", "leaf_1", "leaf_2", "leaf_3"],
-    summary: "cluster A",
-    embedding: [1, 0, 0],
-    qualityMarker: "low",
-    tokenEstimate: 10,
-  };
-  const r1_1: RaptorNode = {
-    id: "r1_1",
-    level: 1,
-    parentId: null,
-    children: ["leaf_4", "leaf_5", "leaf_6", "leaf_7"],
-    summary: "cluster B",
-    embedding: [0, 1, 0],
-    qualityMarker: "low",
-    tokenEstimate: 10,
-  };
-  const root: RaptorNode = {
-    id: "root",
-    level: 2,
-    parentId: null,
-    children: [
-      "leaf_0", "leaf_1", "leaf_2", "leaf_3",
-      "leaf_4", "leaf_5", "leaf_6", "leaf_7",
-    ],
-    summary: "root summary",
-    embedding: [0.5, 0.5, 0],
-    qualityMarker: "low",
-    tokenEstimate: 20,
-  };
-  const nodes = new Map<string, RaptorNode>([
-    ["r1_0", r1_0],
-    ["r1_1", r1_1],
-    ["root", root],
-  ]);
-  return { nodes, rootId: "root", levels: 3, timedOut: false };
-}
-
-test("buildChildParentIndex: index-derived parent matches linear-scan parent for each leaf", () => {
-  const tree = handBuiltTree();
-  const leafIds = [
-    "leaf_0", "leaf_1", "leaf_2", "leaf_3",
-    "leaf_4", "leaf_5", "leaf_6", "leaf_7",
-  ];
-
-  const index = buildChildParentIndex(tree);
-
-  for (const lid of leafIds) {
-    // Old linear-scan semantics: find the first node whose children include lid.
-    const linearParent = [...tree.nodes.values()].find((n) =>
-      n.children.includes(lid),
-    );
-
-    // Index-derived parent.
-    const indexParent = index.get(lid);
-
-    // Both must agree.
-    assert.equal(
-      indexParent?.id ?? null,
-      linearParent?.id ?? null,
-      `leaf ${lid}: index parent (${indexParent?.id}) != linear parent (${linearParent?.id})`,
-    );
-  }
-});
-
-test("buildChildParentIndex: first writer wins (no overwrite for shared leaf)", () => {
-  // If two internal nodes both list the same leaf id in their children, the
-  // index keeps the FIRST one encountered — matching the find() semantics
-  // which also returns the first match.
-  const r1_0: RaptorNode = {
-    id: "r1_0", level: 1, parentId: null,
-    children: ["leaf_0", "leaf_1"],
-    summary: "A", embedding: [1, 0], qualityMarker: "low", tokenEstimate: 5,
-  };
-  const r1_1: RaptorNode = {
-    id: "r1_1", level: 1, parentId: null,
-    children: ["leaf_0", "leaf_2"], // leaf_0 shared with r1_0
-    summary: "B", embedding: [0, 1], qualityMarker: "low", tokenEstimate: 5,
-  };
-  const nodes = new Map<string, RaptorNode>([["r1_0", r1_0], ["r1_1", r1_1]]);
-  const tree: RaptorTree = { nodes, rootId: null, levels: 2, timedOut: false };
-
-  const index = buildChildParentIndex(tree);
-
-  // leaf_0 appears in both r1_0 and r1_1. The index and find() both return
-  // whichever comes first in iteration order.
-  const linearParent = [...tree.nodes.values()].find((n) =>
-    n.children.includes("leaf_0"),
-  );
-  const indexParent = index.get("leaf_0");
-  assert.equal(
-    indexParent?.id ?? null,
-    linearParent?.id ?? null,
-    "first-writer wins: index and linear scan agree on shared leaf",
-  );
-});