pi-mega-compact 0.4.0

package/src/dedup/raptor/guardrails.ts

@@ -0,0 +1,112 @@
+/**
+ * guardrails.ts — hallucination defense for RAPTOR summary nodes (Sprint 13, QA #16).
+ *
+ * Four layers gate a candidate summary before it may be marked high-quality:
+ *   1. Claim grounding — every claim in the summary maps to source text
+ *      (no entity/claim appears that isn't supported by a source chunk).
+ *   2. Entity coverage — fraction of summary entities that are present in source.
+ *   3. Consistency — cosine(reEmbed(summary), cluster centroid) ≥ threshold.
+ *      This is the HARD gate: a low score means the summary drifted from the
+ *      source cluster, so we fall back to extractive (never serve a low-quality
+ *      LLM summary).
+ *   4. Quality markers — 'high' | 'low' | 'extractive_fallback' assigned from the
+ *      above.
+ *
+ * Pure functions, no network, no model. The consistency check uses the caller's
+ * embedder (the same local Embedder used everywhere else).
+ */
+
+import type { Embedder, Vector } from "../../embedder.js";
+import { cosineSimilarity } from "../../embedder.js";
+
+export type QualityMarker = "high" | "low" | "extractive_fallback";
+
+export interface GuardrailInput {
+  summary: string;
+  /** Source chunk texts the summary is supposed to cover. */
+  sources: string[];
+  /** Cluster centroid (embedding) the summary must stay consistent with. */
+  centroid: Vector;
+  /** The local embedder (reused from the rest of the pipeline). */
+  embedder: Embedder;
+  /** Deterministically-precomputed source tokens (uppercased words) for grounding. */
+  sourceTokens: Set<string>;
+  /** Consistency threshold; below this → extractive fallback (QA #16). */
+  consistencyThreshold?: number;
+}
+
+export interface GuardrailResult {
+  marker: QualityMarker;
+  entityCoverage: number; // 0..1
+  consistency: number; // cosine(summEmbed, centroid)
+  grounded: boolean;
+  reason: string;
+}
+
+const ENTITY_RE = /\b([A-Z][a-zA-Z0-9_]{2,}|[a-z_]+_[a-z_]+|\d{2,})\b/g;
+
+/** Extract candidate "entities"/tokens from a summary for grounding checks. */
+export function extractEntities(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(ENTITY_RE)) out.add(m[1].toLowerCase());
+  return [...out];
+}
+
+/** Lowercase word set from a body of source text (for grounding lookups). */
+export function sourceTokenSet(sources: string[]): Set<string> {
+  const set = new Set<string>();
+  for (const s of sources) for (const w of s.toLowerCase().split(/\W+/)) if (w) set.add(w);
+  return set;
+}
+
+/**
+ * Verify a summary against its sources + centroid.
+ *
+ * Faithfulness (QA #16): consistency is the hard gate. If the summary embedding
+ * is insufficiently similar to the cluster centroid, the summary is NOT faithful
+ * to the source — mark it 'extractive_fallback' so callers fall back to the
+ * deterministic extractive summary instead of serving a drifted LLM summary.
+ *
+ * grounding: every summary entity must appear in the source token set. A single
+ * un-grounded entity fails grounding (caught hallucination).
+ */
+export function applyHallucinationGuardrails(input: GuardrailInput): GuardrailResult {
+  const threshold = input.consistencyThreshold ?? 0.6;
+  const sourceTokens = input.sourceTokens;
+
+  // Layer 1 + 2: entity grounding & coverage.
+  const entities = extractEntities(input.summary);
+  let groundedCount = 0;
+  for (const e of entities) {
+    if (sourceTokens.has(e)) groundedCount++;
+  }
+  const entityCoverage = entities.length === 0 ? 1 : groundedCount / entities.length;
+  const grounded = entities.length === 0 || groundedCount === entities.length;
+
+  // Layer 3: consistency re-embed.
+  const summEmbed = input.embedder.embed(input.summary);
+  const consistency = cosineSimilarity(summEmbed, input.centroid);
+
+  // Layer 4: quality marker decision.
+  if (!grounded || consistency < threshold) {
+    return {
+      marker: "extractive_fallback",
+      entityCoverage,
+      consistency,
+      grounded,
+      reason: !grounded
+        ? "ungrounded entity in summary"
+        : `consistency ${consistency.toFixed(2)} < ${threshold} (drift from source)`,
+    };
+  }
+  const marker: QualityMarker = entityCoverage >= 0.7 ? "high" : "low";
+  return { marker, entityCoverage, consistency, grounded, reason: "ok" };
+}
+
+/**
+ * Convenience: build a fixture summary that is deliberately un-grounded (used by
+ * tests to prove the guardrail CATCHES a hallucination). Not used in production.
+ */
+export function makeUngroundedSummary(realSource: string, fakeEntity: string): string {
+  return `${realSource.slice(0, 60)} The quarterly revenue doubled to ${fakeEntity}.`;
+}

package/src/dedup/raptor/index.ts

@@ -0,0 +1,118 @@
+/**
+ * index.ts — RAPTOR orchestrator (Sprint 13, Phase 6).
+ *
+ * Entry point that turns a session's leaves into a hierarchical summary tree.
+ * Shadow mode (RAPTOR_SHADOW_MODE default true): the tree is BUILT and PERSISTED
+ * to raptor_nodes + logged, but is NOT used to serve retrieval. The live
+ * vectorStore.search path is untouched until Sprint 14 promotes RAPTOR.
+ *
+ * PREVENT-PI-004: no network here. Any Ollama call lives in summarizer.ts
+ * (localhost-only, annotated). This module is pure orchestration.
+ */
+
+import type { Embedder } from "../../embedder.js";
+import { defaultEmbedder } from "../../embedder.js";
+import { buildRaptorTree, type Leaf, type RaptorTree } from "./tree.js";
+import { stagedExpansion } from "./retrieval.js";
+import { Logger } from "../../log.js";
+import { saveRaptorTree, listRaptorNodes } from "../../store/sqlite.js";
+
+/** Shadow mode is on by default; set RAPTOR_SHADOW_MODE=false to serve live. */
+export function isShadowMode(): boolean {
+  return process.env.RAPTOR_SHADOW_MODE !== "false";
+}
+
+export interface RaptorOrchestratorOptions {
+  embedder?: Embedder;
+  stateDir: string;
+  sessionId: string;
+  budgetMs?: number;
+  clustersPerLevel?: number;
+  consistencyThreshold?: number;
+  /** Best-effort logger for shadow events. */
+  logger?: Logger;
+}
+
+/**
+ * Build the RAPTOR tree for a session's leaves. Per shadow-mode rules, the tree
+ * is persisted + logged regardless; whether it is served is the caller's choice
+ * (Sprint 13: it is built but NOT injected into recallAndInline).
+ *
+ * Returns the built tree (in-memory) for eval/tests, and persists it to the
+ * store. Never throws — on any build error it logs and returns null.
+ */
+export function runRaptor(
+  leaves: Leaf[],
+  opts: RaptorOrchestratorOptions,
+): RaptorTree | null {
+  const embedder = opts.embedder ?? defaultEmbedder();
+  const logger = opts.logger;
+  try {
+    const tree = buildRaptorTree(leaves, {
+      embedder,
+      budgetMs: opts.budgetMs,
+      clustersPerLevel: opts.clustersPerLevel,
+      consistencyThreshold: opts.consistencyThreshold,
+    });
+    saveRaptorTree(opts.sessionId, tree, opts.stateDir);
+    logger?.info("raptor_build", {
+      sessionId: opts.sessionId,
+      nodes: tree.nodes.size,
+      levels: tree.levels,
+      rootId: tree.rootId,
+      timedOut: tree.timedOut,
+      shadow: isShadowMode(),
+    });
+    if (isShadowMode()) {
+      // Build + log only. Do NOT replace retrieval.
+      logger?.info("raptor_shadow", { sessionId: opts.sessionId, served: false });
+    }
+    return tree;
+  } catch (e) {
+    logger?.error("raptor_build_failed", {
+      sessionId: opts.sessionId,
+      error: String(e instanceof Error ? e.message : e),
+    });
+    return null;
+  }
+}
+
+/**
+ * Staged retrieval over a persisted/session tree. Only meaningful when RAPTOR
+ * is promoted (Sprint 14); provided here so eval can measure it in shadow.
+ *
+ * Returns the leaf ids the staged expansion would serve for `query`.
+ */
+export function recallRaptor(
+  query: string,
+  sessionId: string,
+  opts: { embedder?: Embedder; stateDir: string; k?: number; topM?: number },
+): string[] {
+  const embedder = opts.embedder ?? defaultEmbedder();
+  const nodes = listRaptorNodes(sessionId, opts.stateDir);
+  if (nodes.length === 0) return [];
+  // Rehydrate a minimal in-memory tree (parent links reconstructed from children).
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const tree: RaptorTree = {
+    nodes: new Map(
+      nodes.map((n) => [
+        n.id,
+        {
+          id: n.id,
+          level: n.level,
+          parentId: n.parentId,
+          children: n.children,
+          summary: n.summary,
+          embedding: n.embedding,
+          qualityMarker: n.qualityMarker as any,
+          tokenEstimate: n.tokenEstimate,
+        },
+      ]),
+    ),
+    rootId: nodes.reduce<typeof nodes[number] | null>((best, n) => (!best || n.level > (best?.level ?? -1) ? n : best), null)?.id ?? null,
+    levels: Math.max(1, ...nodes.map((n) => n.level + 1)),
+    timedOut: false,
+  };
+  void byId;
+  return stagedExpansion(query, tree, { embedder, k: opts.k, topM: opts.topM });
+}

package/src/dedup/raptor/kmeans.ts

@@ -0,0 +1,156 @@
+/**
+ * kmeans.ts — k-means++ clustering over embeddings (Sprint 13, RAPTOR Phase 6).
+ *
+ * Pure TS, zero deps, deterministic (seeded). Used to group leaf chunks into
+ * nodes for the RAPTOR summary tree. QA #11: GMM is the spec's long-term target
+ * for cosine space; k-means++ is the shippable local default, with a
+ * near-zero-variance merge guard so degenerate inputs can't spin forever.
+ *
+ * PREVENT-PI-004: math only, no network, no model.
+ */
+
+import type { Vector } from "../../embedder.js";
+import { cosineSimilarity } from "../../embedder.js";
+
+/** Seeded PRNG (mulberry32) so clustering is deterministic across runs. */
+function rng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** L2 distance squared between two equal-length vectors. */
+function dist2(a: Vector, b: Vector): number {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) {
+    const d = a[i] - b[i];
+    s += d * d;
+  }
+  return s;
+}
+
+export interface KMeansResult {
+  /** Cluster assignment per input point (index → cluster id). */
+  assignments: number[];
+  /** Centroids, one per cluster. */
+  centroids: Vector[];
+  /** Number of clusters actually produced (may be < k for degenerate input). */
+  k: number;
+}
+
+/**
+ * k-means++ clustering. Deterministic given `seed`.
+ *
+ * Near-zero-variance guard (QA #11): if the max pairwise distance among input
+ * points is below `varianceFloor`, all points are effectively identical — return
+ * a single cluster (the mean) instead of iterating. Prevents the centroid-init
+ * from dividing by ~0 and keeps degenerate sessions from spinning.
+ */
+export function kmeanspp(
+  points: Vector[],
+  k: number,
+  opts: { seed?: number; maxIter?: number; varianceFloor?: number } = {},
+): KMeansResult {
+  const n = points.length;
+  const seed = opts.seed ?? 0x9e3779b9;
+  const maxIter = opts.maxIter ?? 25;
+  const varianceFloor = opts.varianceFloor ?? 1e-12;
+
+  if (n === 0) return { assignments: [], centroids: [], k: 0 };
+  if (n === 1) return { assignments: [0], centroids: [points[0].slice()], k: 1 };
+
+  // Near-zero-variance merge guard.
+  let maxPair = 0;
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      const d = dist2(points[i], points[j]);
+      if (d > maxPair) maxPair = d;
+    }
+  }
+  if (maxPair < varianceFloor) {
+    const mean = new Array<number>(points[0].length).fill(0);
+    for (const p of points) for (let i = 0; i < mean.length; i++) mean[i] += p[i] / n;
+    return { assignments: new Array<number>(n).fill(0), centroids: [mean], k: 1 };
+  }
+
+  const kk = Math.min(k, n);
+  const rand = rng(seed);
+
+  // k-means++ seeding: first centroid random, rest weighted by squared distance.
+  const centroids: Vector[] = [points[Math.floor(rand() * n)].slice()];
+  const d2 = new Array<number>(n).fill(Infinity);
+  while (centroids.length < kk) {
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+      const d = dist2(points[i], centroids[centroids.length - 1]);
+      if (d < d2[i]) d2[i] = d;
+      sum += d2[i];
+    }
+    if (sum === 0) {
+      // All remaining points coincide with an existing centroid.
+      for (const p of points) if (!centroids.some((c) => dist2(c, p) < 1e-12)) centroids.push(p.slice());
+      break;
+    }
+    let target = rand() * sum;
+    let chosen = 0;
+    for (let i = 0; i < n; i++) {
+      target -= d2[i];
+      if (target <= 0) { chosen = i; break; }
+    }
+    centroids.push(points[chosen].slice());
+  }
+
+  const assignments = new Array<number>(n).fill(0);
+  for (let iter = 0; iter < maxIter; iter++) {
+    let changed = false;
+    // Assign each point to its nearest centroid.
+    for (let i = 0; i < n; i++) {
+      let best = 0;
+      let bestD = Infinity;
+      for (let c = 0; c < centroids.length; c++) {
+        const d = dist2(points[i], centroids[c]);
+        if (d < bestD) { bestD = d; best = c; }
+      }
+      if (assignments[i] !== best) { assignments[i] = best; changed = true; }
+    }
+    // Recompute centroids as the mean of assigned points.
+    const sums = centroids.map(() => new Array<number>(points[0].length).fill(0));
+    const counts = new Array<number>(centroids.length).fill(0);
+    for (let i = 0; i < n; i++) {
+      const c = assignments[i];
+      counts[c]++;
+      for (let d = 0; d < points[i].length; d++) sums[c][d] += points[i][d];
+    }
+    for (let c = 0; c < centroids.length; c++) {
+      if (counts[c] === 0) continue; // keep prior centroid if a cluster emptied
+      centroids[c] = sums[c].map((s) => s / counts[c]);
+    }
+    if (!changed && iter > 0) break;
+  }
+
+  return { assignments, centroids, k: centroids.length };
+}
+
+/** Mean embedding of a set of vectors (used to reduce a cluster to its centroid). */
+export function meanVector(vectors: Vector[]): Vector {
+  if (vectors.length === 0) return [];
+  const dim = vectors[0].length;
+  const sum = new Array<number>(dim).fill(0);
+  for (const v of vectors) for (let i = 0; i < dim; i++) sum[i] += v[i];
+  return sum.map((s) => s / vectors.length);
+}
+
+/** Centroid of the union of two clusters (cosine-space "midpoint" via mean). */
+export function mergeCentroids(a: Vector, b: Vector): Vector {
+  return meanVector([a, b]);
+}
+
+/** Cosine distance (1 - cosine) — used by tree.ts for budget/quality checks. */
+export function cosineDistance(a: Vector, b: Vector): number {
+  return 1 - cosineSimilarity(a, b);
+}

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

@@ -0,0 +1,238 @@
+/**
+ * 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"));
+});
+
+// --- 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 });
+});