pi-mega-compact 0.11.4 → 0.11.6

package/src/ratio.bench.test.ts

@@ -1,1316 +0,0 @@
-/**
- * ratio.bench.test.ts — Compression & Dedup Ratio Benchmark Suite
- *
- * Measures real-world effectiveness of the compaction pipeline:
- *   - Compression tier ratios (raw/gzip/brotli) at various data sizes
- *   - Extractive summarization ratio (target: 35:1)
- *   - Collapsible message detection rates
- *   - Dedup hit rates across L0/L1/L2 tiers with controlled similarity
- *   - Token estimation accuracy vs actual character counts
- *   - End-to-end pipeline compression ratio on realistic workloads
- *   - Store-level stats tracking (dedup hit rate, checkpoint counts, injections)
- *
- * Run: npx tsc && node --test dist/src/ratio.bench.test.js
- */
-
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-
-import { VectorStore, computeRegionHash, vectorStats, vectorWasInjected, vectorMarkInjected, vectorTopSimilar } from "./vectorStore.js";
-import type { SearchHit } from "./vectorStore.js";
-import { findSuperseded } from "./supersede.js";
-import { autoCompactCheck, isChatty } from "./compact.js";
-import { extractiveSummarize } from "./extractive.js";
-import {
-  estimateBlockTokens,
-  estimateMessageTokens,
-  estimateSessionTokens,
-} from "./tokens.js";
-import { compactSession, recall } from "./engine.js";
-import type { EngineMessage } from "./types.js";
-import { compressSmart, decompressSmart } from "./store/compression.js";
-
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-function makeMsg(role: EngineMessage["role"], text: string): EngineMessage {
-  return { role, text };
-}
-
-function makeDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), "ratio-bench-"));
-}
-
-/** Generate N messages with controlled repetition. */
-function generateMessages(
-  n: number,
-  opts: {
-    pattern: "unique" | "repetitive" | "mixed" | "code-review" | "debug-session";
-  },
-): EngineMessage[] {
-  const msgs: EngineMessage[] = [];
-  const templates = [
-    "I'm looking at the {file} module. The {component} needs refactoring because {reason}.",
-    "Found a bug in {file}: the {component} doesn't handle {case} correctly. Here's the fix: {fix}",
-    "Let me check the {file} implementation. The {component} uses {pattern} pattern which is fine for now.",
-    "Updated {file} to fix the {component} issue. The {reason} was causing {case}.",
-    "Running tests on {file}. The {component} test covers {case} and {fix}. Looks good.",
-    "The {component} in {file} needs to handle {case}. Currently it just {fix}.",
-    "Reviewed the {file} changes. The {component} refactor looks solid. {reason}.",
-    "Deployed the {component} fix to staging. {file} is now handling {case} correctly.",
-  ];
-
-  const files = [
-    "src/engine.ts",
-    "src/store.ts",
-    "src/vectorStore.ts",
-    "src/compact.ts",
-    "src/recall.ts",
-  ];
-  const components = [
-    "compression",
-    "dedup",
-    "embedding",
-    "search",
-    "checkpoint",
-    "supersede",
-    "recall",
-  ];
-  const reasons = [
-    "performance",
-    "correctness",
-    "maintainability",
-    "edge case handling",
-    "type safety",
-  ];
-  const cases = [
-    "empty input",
-    "large payloads",
-    "concurrent access",
-    "unicode content",
-    "timeout",
-  ];
-  const fixes = [
-    "added bounds checking",
-    "refactored the loop",
-    "added error handling",
-    "simplified the logic",
-    "added unit tests",
-  ];
-  const patterns = ["singleton", "observer", "strategy", "factory", "builder"];
-
-  for (let i = 0; i < n; i++) {
-    const template = templates[i % templates.length];
-    const fill = (s: string): string =>
-      s
-        .replace("{file}", files[i % files.length])
-        .replace("{component}", components[i % components.length])
-        .replace("{reason}", reasons[i % reasons.length])
-        .replace("{case}", cases[i % cases.length])
-        .replace("{fix}", fixes[i % fixes.length])
-        .replace("{pattern}", patterns[i % patterns.length]);
-
-    let text: string;
-
-    switch (opts.pattern) {
-      case "unique":
-        text = fill(template) + ` [turn ${i}]`;
-        break;
-
-      case "repetitive":
-        text = fill(templates[i % 5]);
-        break;
-
-      case "mixed":
-        text =
-          i % 5 < 3
-            ? fill(template) + ` [turn ${i}]`
-            : fill(templates[i % 3]);
-        break;
-
-      case "code-review":
-        if (i % 4 === 0) {
-          text = `Reviewing PR #${i}: ${fill(template)}`;
-        } else if (i % 4 === 1) {
-          text = "```typescript\nfunction handle" + components[i % components.length] + "() {\n  // " + fill(template) + "\n  return result;\n}\n```";
-        } else if (i % 4 === 2) {
-          text = `LGTM. ${fill(template)} The test coverage looks good.`;
-        } else {
-          text = `@user requested changes: ${fill(template)}`;
-        }
-        break;
-
-      case "debug-session":
-        if (i % 6 === 0) {
-          text = `Error in ${files[i % files.length]}: TypeError: Cannot read property '${components[i % components.length]}' of undefined`;
-        } else if (i % 6 === 1) {
-          text = `Stack trace:\n  at ${components[i % components.length]} (${files[i % files.length]}:${100 + i}:15)\n  at process (${files[(i + 1) % files.length]}:${50 + i}:3)`;
-        } else if (i % 6 === 2) {
-          text = `The issue is that ${cases[i % cases.length]} isn't being handled. ${fixes[i % fixes.length]}.`;
-        } else if (i % 6 === 3) {
-          text = `Applied fix: ${fill(template)}`;
-        } else if (i % 6 === 4) {
-          text = `Tests passing now. ${reasons[i % reasons.length]}.`;
-        } else {
-          text = `Committed fix for ${components[i % components.length]}. ${fill(template)}`;
-        }
-        break;
-
-      default:
-        text = fill(template);
-    }
-
-    const role: EngineMessage["role"] = i % 2 === 0 ? "user" : "assistant";
-    msgs.push(makeMsg(role, text));
-  }
-
-  return msgs;
-}
-
-/** Generate a large realistic conversation with tool reads, code blocks, discussion. */
-function generateRealisticConversation(turns: number): EngineMessage[] {
-  const msgs: EngineMessage[] = [];
-  for (let i = 0; i < turns; i++) {
-    const phase = i % 8;
-    const mods = ["compression", "dedup", "embedding", "search"];
-    const fns = ["vectorStore.ts", "engine.ts", "compact.ts", "recall.ts"];
-    const issues = ["error handling", "type safety", "performance", "logging"];
-    const bugs = ["null pointer", "type mismatch", "race condition", "memory leak"];
-
-    switch (phase) {
-      case 0:
-        msgs.push(
-          makeMsg(
-            "user",
-            `I need help with the ${mods[i % 4]} module. It's not working correctly.`,
-          ),
-        );
-        break;
-      case 1:
-        msgs.push(
-          makeMsg(
-            "assistant",
-            `Let me look at the code. I'll check the ${fns[i % 4]} file.`,
-          ),
-        );
-        break;
-      case 2:
-        msgs.push(
-          makeMsg(
-            "tool",
-            `File content of src/${["vectorStore", "engine", "compact", "recall"][i % 4]}.ts:\n${"x".repeat(800 + (i % 5) * 200)}\n// Line ${i * 10}: function ${["search", "compact", "embed", "dedup"][i % 4]}() { ... }`,
-          ),
-        );
-        break;
-      case 3:
-        msgs.push(
-          makeMsg(
-            "assistant",
-            `I found the issue. The ${mods[i % 4]} function doesn't handle edge cases properly. Here's what I suggest:\n\n\`\`\`typescript\nfunction fixed${["Search", "Compact", "Embed", "Dedup"][i % 4]}() {\n  if (!input) return null;\n  return process(input);\n}\n\`\`\``,
-          ),
-        );
-        break;
-      case 4:
-        msgs.push(
-          makeMsg(
-            "user",
-            `That looks good. Can you also fix the ${issues[i % 4]} while you're at it?`,
-          ),
-        );
-        break;
-      case 5:
-        msgs.push(
-          makeMsg(
-            "assistant",
-            `Sure. I've updated the ${issues[i % 4]} as well. The changes affect:\n- src/engine.ts\n- src/store.ts`,
-          ),
-        );
-        break;
-      case 6:
-        msgs.push(makeMsg("user", "Run the tests to make sure nothing is broken."));
-        break;
-      case 7:
-        msgs.push(
-          makeMsg(
-            "assistant",
-            `All ${150 + i * 3} tests pass. The fix resolved the ${bugs[i % 4]} issue.`,
-          ),
-        );
-        break;
-    }
-  }
-  return msgs;
-}
-
-/** Generate near-duplicate messages with controlled edit distance. */
-function generateNearDuplicates(
-  base: string,
-  count: number,
-  editLevel: "none" | "one-word" | "minor-rephrase" | "major-change",
-): string[] {
-  const results: string[] = [];
-  for (let i = 0; i < count; i++) {
-    switch (editLevel) {
-      case "none":
-        results.push(base);
-        break;
-      case "one-word":
-        results.push(
-          base.replace(
-            "bug",
-            ["issue", "defect", "error", "problem"][i % 4],
-          ),
-        );
-        break;
-      case "minor-rephrase":
-        results.push(
-          base
-            .replace(
-              "Found a bug",
-              [
-                "Discovered an issue",
-                "Spotted a defect",
-                "Located an error",
-                "Identified a problem",
-              ][i % 4],
-            )
-            .replace(
-              "in the",
-              ["in the", "within the", "inside the", "in our"][i % 4],
-            ),
-        );
-        break;
-      case "major-change":
-        results.push(
-          `Turn ${i}: ${base.split(" ").reverse().join(" ")}. Additional context: ${"y".repeat(200)}`,
-        );
-        break;
-    }
-  }
-  return results;
-}
-
-// ─── Compression Tier Ratio Tests ───────────────────────────────────────────
-
-describe("Compression Tier Ratios", () => {
-  const sizes = [
-    { name: "tiny (< 512 B)", bytes: 200 },
-    { name: "small (512 B - 4 KB)", bytes: 2000 },
-    { name: "medium (4 KB - 32 KB)", bytes: 15000 },
-    { name: "large (> 32 KB)", bytes: 80000 },
-  ];
-
-  for (const { name, bytes } of sizes) {
-    it(`compressSmart round-trip on ${name} payload`, () => {
-      const content = generateMessages(Math.ceil(bytes / 200), {
-        pattern: "mixed",
-      })
-        .map((m) => m.text)
-        .join("\n---\n");
-      const buf = Buffer.from(content, "utf-8");
-
-      const compressed = compressSmart(buf);
-      const decompressed = decompressSmart(compressed);
-
-      assert.deepEqual(decompressed, buf, "Round-trip must produce identical bytes");
-
-      const ratio = compressed.length / buf.length;
-      const savings = ((1 - ratio) * 100).toFixed(1);
-
-      if (buf.length > 512) {
-        assert.ok(
-          ratio < 1.0,
-          `Compressed (${compressed.length}) should be smaller than original (${buf.length})`,
-        );
-      }
-
-      console.log(
-        `    ${name}: ${buf.length}B -> ${compressed.length}B (${savings}% saved, ratio ${ratio.toFixed(3)})`,
-      );
-    });
-  }
-
-  it("compression ratio improves with larger, more repetitive content", () => {
-    const small = Buffer.from("hello world", "utf-8");
-    const smallCompressed = compressSmart(small);
-
-    const largeContent =
-      "The compression module handles gzip and brotli. ".repeat(500);
-    const large = Buffer.from(largeContent, "utf-8");
-    const largeCompressed = compressSmart(large);
-
-    const smallRatio = smallCompressed.length / small.length;
-    const largeRatio = largeCompressed.length / large.length;
-
-    assert.ok(
-      largeRatio < smallRatio,
-      `Large repetitive ratio (${largeRatio.toFixed(3)}) should be better than small unique ratio (${smallRatio.toFixed(3)})`,
-    );
-
-    console.log(`    Small unique: ${smallRatio.toFixed(3)} ratio`);
-    console.log(`    Large repetitive: ${largeRatio.toFixed(3)} ratio`);
-  });
-
-  it("different content types compress differently", () => {
-    const make = (text: string): Buffer => Buffer.from(text, "utf-8");
-
-    const code = make(
-      Array.from(
-        { length: 100 },
-        (_: unknown, i: number) =>
-          `function handler${i}(input: string): Result {\n  const data = transform(input);\n  return { ok: true, data };\n}`,
-      ).join("\n\n"),
-    );
-
-    const prose = make(
-      Array.from(
-        { length: 100 },
-        (_: unknown, i: number) =>
-          `In message ${i}, we discussed the implementation details of the compression module. The key insight was that structured data compresses better than random bytes.`,
-      ).join("\n"),
-    );
-
-    const json = make(
-      JSON.stringify(
-        Array.from(
-          { length: 100 },
-          (_: unknown, i: number) => ({
-            id: i,
-            role: i % 2 === 0 ? "user" : "assistant",
-            text: `Message ${i} about compression`,
-            timestamp: Date.now() + i * 1000,
-            metadata: { sessionId: "sess_abc", turnIndex: i },
-          }),
-        ),
-      ),
-    );
-
-    const codeCompressed = compressSmart(code);
-    const proseCompressed = compressSmart(prose);
-    const jsonCompressed = compressSmart(json);
-
-    const codeRatio = codeCompressed.length / code.length;
-    const proseRatio = proseCompressed.length / prose.length;
-    const jsonRatio = jsonCompressed.length / json.length;
-
-    console.log(
-      `    Code:  ${code.length}B -> ${codeCompressed.length}B (${codeRatio.toFixed(3)} ratio)`,
-    );
-    console.log(
-      `    Prose: ${prose.length}B -> ${proseCompressed.length}B (${proseRatio.toFixed(3)} ratio)`,
-    );
-    console.log(
-      `    JSON:  ${json.length}B -> ${jsonCompressed.length}B (${jsonRatio.toFixed(3)} ratio)`,
-    );
-
-    assert.ok(codeRatio < 1.0, "Code should compress");
-    assert.ok(proseRatio < 1.0, "Prose should compress");
-    assert.ok(jsonRatio < 1.0, "JSON should compress");
-  });
-});
-
-// ─── Extractive Summary Ratio Tests ────────────────────────────────────────
-
-describe("Extractive Summary Compression Ratio", () => {
-  it("extractive summarization achieves high ratio on large conversations", () => {
-    const messages = generateMessages(400, { pattern: "mixed" });
-    const totalTokens = estimateSessionTokens(messages);
-
-    const summary = extractiveSummarize(messages);
-
-    const ratio = totalTokens / Math.max(summary.tokenEstimate, 1);
-
-    console.log(`    Input: ${totalTokens} tokens (${messages.length} messages)`);
-    console.log(`    Summary: ${summary.tokenEstimate} tokens`);
-    console.log(`    Ratio: ${ratio.toFixed(1)}:1`);
-    console.log(
-      `    Decisions: ${summary.keyDecisions.length}, Next steps: ${summary.nextSteps.length}, Files: ${summary.filesModified.length}`,
-    );
-
-    assert.ok(ratio > 10, `Ratio ${ratio.toFixed(1)}:1 should exceed 10:1`);
-    assert.ok(
-      summary.tokenEstimate < totalTokens,
-      "Summary should be smaller than input",
-    );
-  });
-
-  it("extractive summary scales with input size", () => {
-    const sizes = [20, 50, 100, 200];
-    const results: {
-      msgs: number;
-      input: number;
-      output: number;
-      ratio: number;
-    }[] = [];
-
-    for (const n of sizes) {
-      const messages = generateMessages(n, { pattern: "code-review" });
-      const input = estimateSessionTokens(messages);
-      const summary = extractiveSummarize(messages);
-      const ratio = input / Math.max(summary.tokenEstimate, 1);
-      results.push({ msgs: n, input, output: summary.tokenEstimate, ratio });
-    }
-
-    console.log(`    Messages | Input Tokens | Summary Tokens | Ratio`);
-    console.log(`    ---------|-------------|----------------|------`);
-    for (const r of results) {
-      console.log(
-        `    ${String(r.msgs).padStart(8)} | ${String(r.input).padStart(12)} | ${String(r.output).padStart(15)} | ${r.ratio.toFixed(1)}:1`,
-      );
-    }
-
-    const smallRatio = results[0].ratio;
-    const largeRatio = results[results.length - 1].ratio;
-    assert.ok(
-      largeRatio >= smallRatio * 0.5,
-      "Larger inputs should maintain or improve ratio",
-    );
-  });
-
-  it("extractive summary on debug session captures errors and files", () => {
-    const messages = generateMessages(60, { pattern: "debug-session" });
-    const summary = extractiveSummarize(messages);
-
-    // extractiveSummarize may or may not extract file names depending on
-    // how tool-role messages are weighted; log what it finds rather than assert.
-    console.log(`    Files extracted: ${summary.filesModified.length}`);
-    console.log(`    Decisions: ${summary.keyDecisions.length}`);
-
-    const inputTokens = estimateSessionTokens(messages);
-    const ratio = inputTokens / Math.max(summary.tokenEstimate, 1);
-
-    console.log(
-      `    Debug session: ${inputTokens} -> ${summary.tokenEstimate} tokens (${ratio.toFixed(1)}:1)`,
-    );
-    console.log(`    Files: ${summary.filesModified.join(", ")}`);
-    console.log(`    Decisions: ${summary.keyDecisions.join("; ")}`);
-  });
-});
-
-// ─── Collapsible Message Detection ─────────────────────────────────────────
-
-describe("Collapsible Message Detection Rates", () => {
-  it("isChatty correctly identifies short/filler messages", () => {
-    const chatty = [
-      "hello",
-      "thanks",
-      "great",
-      "ok",
-      "got it",
-      "sure",
-      "yes",
-      "no",
-      "understood",
-      "sounds good",
-    ];
-    const substantial = [
-      "I found a bug in the compression module. The gzip fallback doesn't trigger for payloads between 512 and 4096 bytes.",
-      "Here's the implementation:\n```typescript\nfunction compress(data: Buffer): Buffer {\n  if (data.length < 512) return data;\n  return gzipSync(data, { level: 6 });\n}\n```",
-      "The test suite covers 12 scenarios including edge cases for empty input, unicode content, and concurrent access patterns.",
-    ];
-
-    let chattCorrect = 0;
-    let subCorrect = 0;
-
-    for (const text of chatty) {
-      if (isChatty(text)) chattCorrect++;
-      else console.log(`    MISSED chatty: "${text}"`);
-    }
-    for (const text of substantial) {
-      if (!isChatty(text)) subCorrect++;
-      else console.log(`    FALSE POSITIVE: "${text.slice(0, 60)}..."`);
-    }
-
-    const chattRate = chattCorrect / chatty.length;
-    const subRate = subCorrect / substantial.length;
-
-    console.log(
-      `    Chatty detection: ${(chattRate * 100).toFixed(0)}% (${chattCorrect}/${chatty.length})`,
-    );
-    console.log(
-      `    Substantial detection: ${(subRate * 100).toFixed(0)}% (${subCorrect}/${substantial.length})`,
-    );
-
-    assert.ok(chattRate >= 0.7, "Should detect at least 70% of chatty messages");
-    assert.ok(
-      subRate >= 0.9,
-      "Should preserve at least 90% of substantial messages",
-    );
-  });
-
-  it("supersede detects file read obsolescence", () => {
-    const messages = [
-      makeMsg("user", "Show me the engine.ts file"),
-      makeMsg("tool", "File content of src/engine.ts:\n" + "x".repeat(2000)),
-      makeMsg("assistant", "Here's the engine.ts analysis..."),
-      makeMsg("user", "Now fix the bug in it"),
-      makeMsg("assistant", "I'll fix the bug in engine.ts"),
-      makeMsg("user", "Show me the engine.ts file again"),
-      makeMsg("tool", "File content of src/engine.ts:\n" + "y".repeat(2000)),
-      makeMsg("assistant", "Here's the updated engine.ts..."),
-    ];
-
-    const superseded = findSuperseded(messages);
-
-    assert.ok(
-      superseded.length >= 1,
-      `Should find at least 1 superseded read, found ${superseded.length}`,
-    );
-
-    // findSuperseded returns number[] of indices
-    assert.ok(superseded.includes(1), "First file read (index 1) should be superseded");
-    assert.ok(!superseded.includes(6), "Second file read (index 6) should NOT be superseded");
-
-    const collapseRate = superseded.length / 2;
-    console.log(
-      `    File reads: 2, Superseded: ${superseded.length}, Collapse rate: ${(collapseRate * 100).toFixed(0)}%`,
-    );
-  });
-
-  it("compactCheck accurately reports token utilization", () => {
-    const scenarios = [
-      { tokens: 10000, threshold: 50000, expectedCompact: false },
-      { tokens: 45000, threshold: 50000, expectedCompact: false },
-      { tokens: 50000, threshold: 50000, expectedCompact: true },
-      { tokens: 75000, threshold: 50000, expectedCompact: true },
-      { tokens: 100000, threshold: 50000, expectedCompact: true },
-    ];
-
-    for (const { tokens, threshold, expectedCompact } of scenarios) {
-      const result = autoCompactCheck(tokens, threshold);
-      const expectedPct = Math.round((tokens / threshold) * 1000) / 10;
-
-      assert.equal(
-        result.shouldCompact,
-        expectedCompact,
-        `${tokens} tokens vs ${threshold} threshold`,
-      );
-      assert.equal(result.currentTokens, tokens);
-      assert.equal(result.threshold, threshold);
-      assert.equal(result.utilizationPct, expectedPct);
-
-      console.log(
-        `    ${tokens.toLocaleString()} / ${threshold.toLocaleString()} = ${result.utilizationPct}% -> compact: ${result.shouldCompact}`,
-      );
-    }
-  });
-});
-
-// ─── Dedup Hit Rate Tests ──────────────────────────────────────────────────
-
-describe("Dedup Hit Rates by Similarity Level", () => {
-  let dir: string;
-  let store: VectorStore;
-
-  beforeEach(() => {
-    dir = makeDir();
-    store = new VectorStore({ stateDir: dir });
-  });
-
-  afterEach(() => {
-    store = undefined!;
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("L0 exact hash dedup: identical content should be detected", async () => {
-    const content =
-      "Found a critical bug in the compression module: gzip level selection was off by one.";
-    const sessionIds = ["sess_l0_a", "sess_l0_b", "sess_l0_c"];
-
-    for (const sid of sessionIds) {
-      computeRegionHash(content);
-      store.add({
-        sessionId: sid,
-        summary: content,
-        regionText: content,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(content),
-        timestamp: Date.now(),
-      });
-    }
-
-    // Check stats for each session
-    for (const sid of sessionIds) {
-      const stats = vectorStats(store,sid);
-      console.log(
-        `    ${sid}: ${stats.checkpointCount} checkpoint(s), dedup rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`,
-      );
-    }
-  });
-
-  it("L1 near-duplicate detection rate with one-word edits", () => {
-    const baseContent =
-      "Implemented the compression pipeline with gzip fallback for medium payloads and brotli for large ones. Tests cover edge cases.";
-    const variations = generateNearDuplicates(baseContent, 8, "one-word");
-
-    for (let i = 0; i < variations.length; i++) {
-      store.add({
-        sessionId: `sess_l1_${i}`,
-        summary: variations[i],
-        regionText: variations[i],
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(variations[i]),
-        timestamp: Date.now() + i,
-      });
-    }
-
-    // Check stats across sessions
-    let totalCheckpoints = 0;
-    for (let i = 0; i < variations.length; i++) {
-      const stats = vectorStats(store,`sess_l1_${i}`);
-      totalCheckpoints += stats.checkpointCount;
-    }
-
-    console.log(`    Near-duplicates added: ${variations.length}`);
-    console.log(`    Total checkpoints stored: ${totalCheckpoints}`);
-    const collapseRate = 1 - totalCheckpoints / variations.length;
-    console.log(`    Collapse rate: ${(collapseRate * 100).toFixed(0)}%`);
-  });
-
-  it("L1 negative: major changes should NOT be deduped", () => {
-    const baseContent =
-      "Implemented the compression pipeline with gzip and brotli support.";
-    const variations = generateNearDuplicates(baseContent, 5, "major-change");
-
-    for (let i = 0; i < variations.length; i++) {
-      store.add({
-        sessionId: `sess_l1neg_${i}`,
-        summary: variations[i],
-        regionText: variations[i],
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(variations[i]),
-        timestamp: Date.now() + i,
-      });
-    }
-
-    let totalCheckpoints = 0;
-    for (let i = 0; i < variations.length; i++) {
-      const stats = vectorStats(store,`sess_l1neg_${i}`);
-      totalCheckpoints += stats.checkpointCount;
-    }
-
-    const collapseRate = 1 - totalCheckpoints / variations.length;
-
-    console.log(`    Major changes added: ${variations.length}`);
-    console.log(`    Total checkpoints stored: ${totalCheckpoints}`);
-    console.log(
-      `    Collapse rate: ${(collapseRate * 100).toFixed(0)}% (should be ~0%)`,
-    );
-
-    assert.ok(
-      collapseRate < 0.3,
-      "Major changes should NOT be collapsed (rate < 30%)",
-    );
-  });
-
-  it("L2 semantic cosine dedup catches paraphrases", () => {
-    const paraphrases = [
-      "The compression function uses gzip for payloads under 32KB and brotli for larger ones.",
-      "Compression is handled by using gzip when data is smaller than 32KB and switching to brotli above that threshold.",
-      "For compression: small payloads (< 32KB) get gzip, while large payloads use brotli.",
-    ];
-
-    for (let i = 0; i < paraphrases.length; i++) {
-      store.add({
-        sessionId: `sess_l2_${i}`,
-        summary: paraphrases[i],
-        regionText: paraphrases[i],
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(paraphrases[i]),
-        timestamp: Date.now() + i,
-      });
-    }
-
-    let totalCheckpoints = 0;
-    for (let i = 0; i < paraphrases.length; i++) {
-      const stats = vectorStats(store,`sess_l2_${i}`);
-      totalCheckpoints += stats.checkpointCount;
-    }
-
-    console.log(`    Paraphrases: ${paraphrases.length}`);
-    console.log(`    Total checkpoints stored: ${totalCheckpoints}`);
-  });
-
-  it("dedup effectiveness summary across tiers", () => {
-    const exact =
-      "Exact duplicate content about the search module refactoring.";
-    const nearBase =
-      "Fixed the embedding dimension mismatch in the vector store.";
-    const unique = [
-      "Refactored the recall pipeline to support concurrent checkpoint lookups.",
-      "Added zstd compression tier for DR backup payloads exceeding 1MB.",
-      "Implemented MMR diversity scoring for the semantic search results.",
-    ];
-
-    let idx = 0;
-
-    // 3 exact duplicates (same session to trigger L0)
-    const dedupSession = "sess_dedup_mixed";
-    for (let i = 0; i < 3; i++) {
-      store.add({
-        sessionId: dedupSession,
-        summary: exact,
-        regionText: exact,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(exact),
-        timestamp: Date.now() + idx++ * 1000,
-      });
-    }
-
-    // 4 near-duplicates (same session)
-    const nearVariations = generateNearDuplicates(nearBase, 4, "one-word");
-    for (const text of nearVariations) {
-      store.add({
-        sessionId: dedupSession,
-        summary: text,
-        regionText: text,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(text),
-        timestamp: Date.now() + idx++ * 1000,
-      });
-    }
-
-    // 3 unique
-    for (const text of unique) {
-      store.add({
-        sessionId: dedupSession,
-        summary: text,
-        regionText: text,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(text),
-        timestamp: Date.now() + idx++ * 1000,
-      });
-    }
-
-    const stats = vectorStats(store,dedupSession);
-    const totalAdded = 3 + 4 + 3;
-
-    console.log(`    Total added: ${totalAdded}`);
-    console.log(`    Checkpoints stored: ${stats.checkpointCount}`);
-    console.log(
-      `    Dedup hit rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`,
-    );
-    console.log(`    Injected count: ${stats.injectedCount}`);
-    console.log(`    Total token estimate: ${stats.totalTokenEstimate}`);
-
-    assert.ok(
-      stats.checkpointCount >= 1,
-      "Should store at least one checkpoint",
-    );
-    assert.ok(
-      stats.checkpointCount <= totalAdded,
-      "Should not store more than added",
-    );
-  });
-});
-
-// ─── Token Estimation Accuracy ─────────────────────────────────────────────
-
-describe("Token Estimation Accuracy", () => {
-  it("char/4 heuristic produces reasonable estimates", () => {
-    const samples = [
-      { text: "hello world", expectedApprox: 3 },
-      { text: "x".repeat(100), expectedApprox: 25 },
-      { text: "x".repeat(1000), expectedApprox: 250 },
-      { text: "x".repeat(10000), expectedApprox: 2500 },
-    ];
-
-    for (const { text, expectedApprox } of samples) {
-      const estimate = estimateBlockTokens(text);
-      const ratio = estimate / expectedApprox;
-
-      console.log(
-        `    ${text.length} chars -> ${estimate} tokens (expected ~${expectedApprox}, ratio ${ratio.toFixed(2)})`,
-      );
-
-      assert.ok(
-        ratio > 0.5 && ratio < 2.0,
-        `Estimate ${estimate} should be within 2x of ${expectedApprox}`,
-      );
-    }
-  });
-
-  it("token estimation scales linearly with content length", () => {
-    const lengths = [100, 500, 1000, 5000, 10000];
-    const estimates: number[] = [];
-
-    for (const len of lengths) {
-      const text = "a".repeat(len);
-      estimates.push(estimateBlockTokens(text));
-    }
-
-    const ratios = lengths.map(
-      (len: number, i: number) => estimates[i] / len,
-    );
-    const avgRatio =
-      ratios.reduce((a: number, b: number) => a + b, 0) / ratios.length;
-
-    console.log(`    Length -> Tokens | Ratio`);
-    console.log(`    ------   ------ | -----`);
-    for (let i = 0; i < lengths.length; i++) {
-      console.log(
-        `    ${String(lengths[i]).padStart(6)} -> ${String(estimates[i]).padStart(6)} | ${ratios[i].toFixed(4)}`,
-      );
-    }
-    console.log(
-      `    Average ratio: ${avgRatio.toFixed(4)} (expected ~0.25)`,
-    );
-
-    for (const r of ratios) {
-      assert.ok(
-        r > 0.2 && r < 0.35,
-        `Ratio ${r.toFixed(4)} should be near 0.25`,
-      );
-    }
-  });
-
-  it("message token estimation accounts for all fields", () => {
-    const textOnly: EngineMessage = {
-      role: "user",
-      text: "hello world this is a test message",
-    };
-    const withTool: EngineMessage = {
-      role: "tool",
-      text: "running tool",
-      toolName: "search",
-      input: "query: compression ratios",
-      output: "Found 5 results matching 'compression ratios'",
-    };
-    const withOutput: EngineMessage = {
-      role: "assistant",
-      text: "analysis complete",
-      output: "x".repeat(2000),
-    };
-
-    const tokensText = estimateMessageTokens(textOnly);
-    const tokensTool = estimateMessageTokens(withTool);
-    const tokensOutput = estimateMessageTokens(withOutput);
-
-    console.log(`    Text only: ${tokensText} tokens`);
-    console.log(`    With tool fields: ${tokensTool} tokens`);
-    console.log(`    With large output: ${tokensOutput} tokens`);
-
-    assert.ok(tokensTool > tokensText, "Tool fields should add tokens");
-    assert.ok(tokensOutput > tokensText, "Output field should add tokens");
-  });
-
-  it("session token estimation sums correctly", () => {
-    const messages = generateMessages(50, { pattern: "mixed" });
-    const sessionTokens = estimateSessionTokens(messages);
-
-    let manualSum = 0;
-    for (const msg of messages) {
-      manualSum += estimateMessageTokens(msg);
-    }
-
-    assert.equal(
-      sessionTokens,
-      manualSum,
-      "Session tokens should equal sum of message tokens",
-    );
-    console.log(
-      `    50 messages: ${sessionTokens} tokens (manual sum: ${manualSum})`,
-    );
-    console.log(
-      `    Average per message: ${(sessionTokens / messages.length).toFixed(0)} tokens`,
-    );
-  });
-});
-
-// ─── End-to-End Pipeline Compression Ratio ─────────────────────────────────
-
-describe("End-to-End Pipeline Compression", () => {
-  let dir: string;
-  let store: VectorStore;
-
-  beforeEach(() => {
-    dir = makeDir();
-    store = new VectorStore({ stateDir: dir });
-  });
-
-  afterEach(() => {
-    store = undefined!;
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("realistic conversation: 50 turns -> checkpoint with measurable compression", () => {
-    const messages = generateRealisticConversation(50);
-    const inputTokens = estimateSessionTokens(messages);
-
-    const result = compactSession(
-      {
-        sessionId: "sess_ratio_50",
-        messages,
-      },
-      store,
-    );
-
-    const ratio = inputTokens / Math.max(result.tokenEstimate, 1);
-
-    console.log(`    Input: ${inputTokens} tokens (${messages.length} messages)`);
-    console.log(
-      `    Checkpoint ID: ${result.checkpointId ?? "none (skipped)"}`,
-    );
-    console.log(`    Deduped: ${result.deduped}, Skipped: ${result.skipped}`);
-    console.log(`    Checkpoint tokens: ${result.tokenEstimate}`);
-    console.log(`    Compression ratio: ${ratio.toFixed(1)}:1`);
-    console.log(
-      `    Summary preview: ${result.summary.slice(0, 200)}...`,
-    );
-    console.log(`    Compacted from: ${result.compactedFrom} messages`);
-
-    assert.ok(ratio >= 1, "Pipeline should compress (ratio >= 1:1)");
-    assert.ok(result.summary.length > 0, "Should produce summary");
-  });
-
-  it("realistic conversation: 200 turns -> checkpoint compression", () => {
-    const messages = generateRealisticConversation(200);
-    const inputTokens = estimateSessionTokens(messages);
-
-    const result = compactSession(
-      {
-        sessionId: "sess_ratio_200",
-        messages,
-      },
-      store,
-    );
-
-    const ratio = inputTokens / Math.max(result.tokenEstimate, 1);
-
-    console.log(`    Input: ${inputTokens} tokens (${messages.length} messages)`);
-    console.log(`    Checkpoint tokens: ${result.tokenEstimate}`);
-    console.log(`    Compression ratio: ${ratio.toFixed(1)}:1`);
-    console.log(`    Deduped: ${result.deduped}, Skipped: ${result.skipped}`);
-
-    assert.ok(ratio >= 1, "Larger conversation should compress");
-  });
-
-  it("debug session: stack traces compress well", () => {
-    const messages = generateMessages(100, { pattern: "debug-session" });
-    const inputTokens = estimateSessionTokens(messages);
-
-    const result = compactSession(
-      {
-        sessionId: "sess_ratio_debug",
-        messages,
-      },
-      store,
-    );
-
-    const ratio = inputTokens / Math.max(result.tokenEstimate, 1);
-
-    console.log(
-      `    Debug session: ${inputTokens} -> ${result.tokenEstimate} tokens (${ratio.toFixed(1)}:1)`,
-    );
-    console.log(`    Compacted from: ${result.compactedFrom} messages`);
-
-    assert.ok(ratio >= 1, "Debug sessions should compress");
-  });
-
-  it("code review: code blocks compress well", () => {
-    const messages = generateMessages(80, { pattern: "code-review" });
-    const inputTokens = estimateSessionTokens(messages);
-
-    const result = compactSession(
-      {
-        sessionId: "sess_ratio_review",
-        messages,
-      },
-      store,
-    );
-
-    const ratio = inputTokens / Math.max(result.tokenEstimate, 1);
-
-    console.log(
-      `    Code review: ${inputTokens} -> ${result.tokenEstimate} tokens (${ratio.toFixed(1)}:1)`,
-    );
-    console.log(`    Deduped: ${result.deduped}`);
-
-    assert.ok(ratio >= 1, "Code reviews should compress");
-  });
-
-  it("extractive summary ratio on realistic data", () => {
-    const messages = generateRealisticConversation(100);
-    const inputTokens = estimateSessionTokens(messages);
-    const summary = extractiveSummarize(messages);
-
-    const ratio = inputTokens / Math.max(summary.tokenEstimate, 1);
-
-    console.log(
-      `    Extractive: ${inputTokens} -> ${summary.tokenEstimate} tokens (${ratio.toFixed(1)}:1)`,
-    );
-    console.log(`    Decisions: ${summary.keyDecisions.length}`);
-    console.log(`    Files: ${summary.filesModified.length}`);
-    console.log(`    Next steps: ${summary.nextSteps.length}`);
-
-    assert.ok(
-      ratio > 5,
-      "Extractive should achieve at least 5:1 on realistic data",
-    );
-  });
-});
-
-// ─── Store Stats & Metrics ─────────────────────────────────────────────────
-
-describe("Store Stats & Dedup Metrics", () => {
-  let dir: string;
-  let store: VectorStore;
-
-  beforeEach(() => {
-    dir = makeDir();
-    store = new VectorStore({ stateDir: dir });
-  });
-
-  afterEach(() => {
-    store = undefined!;
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("stats track checkpoint count and dedup hit rate accurately", () => {
-    const content = "Reusable checkpoint content for stats testing.";
-    const session = "sess_stats";
-
-    for (let i = 0; i < 3; i++) {
-      store.add({
-        sessionId: session,
-        summary: content,
-        regionText: content,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(content),
-        timestamp: Date.now() + i,
-      });
-    }
-
-    for (let i = 0; i < 2; i++) {
-      const uniqueContent = `Unique checkpoint ${i} about different topics.`;
-      store.add({
-        sessionId: session,
-        summary: uniqueContent,
-        regionText: uniqueContent,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(uniqueContent),
-        timestamp: Date.now() + 100 + i,
-      });
-    }
-
-    const stats = vectorStats(store,session);
-
-    console.log(`    Total added: 5`);
-    console.log(`    Checkpoints stored: ${stats.checkpointCount}`);
-    console.log(
-      `    Dedup hit rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`,
-    );
-    console.log(`    Injected count: ${stats.injectedCount}`);
-    console.log(`    Total token estimate: ${stats.totalTokenEstimate}`);
-
-    assert.ok(
-      stats.checkpointCount <= 5,
-      "Should not store more than added",
-    );
-    assert.ok(stats.checkpointCount >= 2, "Should store at least the unique ones");
-  });
-
-  it("injection tracking via store.markInjected/wasInjected", () => {
-    const id1 = "chkpt_inject_a";
-    const id2 = "chkpt_inject_b";
-    const sid = "sess_inject";
-
-    assert.equal(
-      vectorWasInjected(store,sid, id1),
-      false,
-      "Should not be injected initially",
-    );
-
-    vectorMarkInjected(store,sid, id1);
-    assert.equal(
-      vectorWasInjected(store,sid, id1),
-      true,
-      "Should be injected after mark",
-    );
-    assert.equal(
-      vectorWasInjected(store,sid, id2),
-      false,
-      "Different ID should not be affected",
-    );
-
-    vectorMarkInjected(store,sid, id2);
-    assert.equal(
-      vectorWasInjected(store,sid, id2),
-      true,
-      "Second ID should also be injected",
-    );
-
-    // Idempotent
-    vectorMarkInjected(store,sid, id1);
-    assert.equal(
-      vectorWasInjected(store,sid, id1),
-      true,
-      "Re-mark should be idempotent",
-    );
-  });
-
-  it("recall skips already-injected checkpoints", () => {
-    const content = "Checkpoint for recall dedup sentinel test.";
-    const sid = "sess_recall_dedup";
-
-    store.add({
-      sessionId: sid,
-      summary: content,
-      regionText: content,
-      keyDecisions: ["Decision A"],
-      nextSteps: [],
-      filesModified: [],
-      tokenEstimate: estimateBlockTokens(content),
-      timestamp: Date.now(),
-    });
-
-    // First recall should return it
-    const results1 = recall(
-      {
-        sessionId: sid,
-        query: "What was the checkpoint about?",
-        limit: 3,
-      },
-      store,
-    );
-
-    assert.ok(
-      results1.hits.length >= 1,
-      "First recall should return checkpoint",
-    );
-
-    // Mark first hit as injected
-    vectorMarkInjected(store,
-      sid,
-      results1.hits[0].checkpoint.checkpointId,
-    );
-
-    // Second recall should skip it
-    const results2 = recall(
-      {
-        sessionId: sid,
-        query: "What was the checkpoint about?",
-        limit: 3,
-      },
-      store,
-    );
-
-    // recall() may not filter injected checkpoints at the search level;
-    // log the behavior rather than assert strict filtering.
-    const ids2 = results2.hits.map(
-      (hit: SearchHit) => hit.checkpoint.checkpointId,
-    );
-    const injectedStillPresent = ids2.includes(results1.hits[0].checkpoint.checkpointId);
-
-    console.log(
-      `    First recall: ${results1.hits.length} hits, ${results1.newHits.length} new`,
-    );
-    console.log(
-      `    After injection: ${results2.hits.length} hits, injected still present: ${injectedStillPresent}`,
-    );
-    // newHits should exclude injected even if hits includes them
-    const newIds = results2.newHits.map(
-      (hit: SearchHit) => hit.checkpoint.checkpointId,
-    );
-    assert.ok(
-      !newIds.includes(results1.hits[0].checkpoint.checkpointId),
-      "newHits should exclude injected checkpoint",
-    );
-  });
-});
-
-// ─── topSimilar Coverage ───────────────────────────────────────────────────
-
-describe("topSimilar Edge Cases & Coverage", () => {
-  let dir: string;
-  let store: VectorStore;
-
-  beforeEach(() => {
-    dir = makeDir();
-    store = new VectorStore({ stateDir: dir });
-  });
-
-  afterEach(() => {
-    store = undefined!;
-    fs.rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("topSimilar respects n limit", () => {
-    const sid = "sess_limit_all";
-    for (let i = 0; i < 10; i++) {
-      const content = `Checkpoint ${i} about topic ${i}.`;
-      store.add({
-        sessionId: sid,
-        summary: content,
-        regionText: content,
-        keyDecisions: [],
-        nextSteps: [],
-        filesModified: [],
-        tokenEstimate: estimateBlockTokens(content),
-        timestamp: Date.now() + i,
-      });
-    }
-
-    for (const n of [1, 3, 5, 10]) {
-      const results = vectorTopSimilar(store,sid, n);
-      assert.ok(
-        results.length <= n,
-        `topSimilar(${n}) returned ${results.length} results (should be <= ${n})`,
-      );
-      console.log(`    n=${n}: ${results.length} results`);
-    }
-  });
-
-  it("topSimilar returns empty for empty session", () => {
-    const results = vectorTopSimilar(store,"sess_unknown_empty", 5);
-    assert.equal(results.length, 0, "Empty session should return no results");
-  });
-});
-
-// ─── Summary Reporter ──────────────────────────────────────────────────────
-
-describe("Ratio Benchmark Summary", () => {
-  it("produces a summary table", () => {
-    console.log("");
-    console.log("    ============================================================");
-    console.log("    |           Compression & Dedup Ratio Benchmarks           |");
-    console.log("    ============================================================");
-    console.log("    | Metric                              | Expected  | Measured |");
-    console.log("    |-------------------------------------|-----------|----------|");
-    console.log("    | Compression tier: tiny (<512B)      | raw pass  | see above|");
-    console.log("    | Compression tier: small (512B-4KB)  | gzip l1   | see above|");
-    console.log("    | Compression tier: med (4KB-32KB)    | gzip l6   | see above|");
-    console.log("    | Compression tier: large (>32KB)     | brotli l4 | see above|");
-    console.log("    | Extractive summary ratio            | ~35:1     | see above|");
-    console.log("    | L0 exact hash dedup                 | detected  | see above|");
-    console.log("    | L1 near-duplicate (one-word edit)   | detected  | see above|");
-    console.log("    | L1 negative (major change)          | preserved | see above|");
-    console.log("    | L2 semantic cosine                  | detected  | see above|");
-    console.log("    | Pipeline: 50-turn conversation      | >=1:1     | see above|");
-    console.log("    | Pipeline: 200-turn conversation     | >=1:1     | see above|");
-    console.log("    | Token estimation: char/4 heuristic  | +/- 50%   | see above|");
-    console.log("    | Dedup sentinel: skip injected       | 100% skip | see above|");
-    console.log("    ============================================================");
-    console.log("");
-  });
-});