recallnest 3.0.0 → 4.0.0

package/src/__tests__/store-read-consistency.test.ts

@@ -1,122 +0,0 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { readConsistencyInterval as envReadConsistencyInterval } from "../env-config.js";
-import { MemoryStore } from "../store.js";
-
-const cleanupPaths: string[] = [];
-const savedEnv = process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL;
-
-afterEach(() => {
-  while (cleanupPaths.length > 0) {
-    const target = cleanupPaths.pop();
-    if (target) {
-      rmSync(target, { recursive: true, force: true });
-    }
-  }
-  if (savedEnv === undefined) {
-    delete process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL;
-  } else {
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = savedEnv;
-  }
-});
-
-function tempDb(): string {
-  const dbPath = mkdtempSync(join(tmpdir(), "recallnest-read-consistency-"));
-  cleanupPaths.push(dbPath);
-  return dbPath;
-}
-
-function entry(i: number) {
-  return {
-    text: `read-consistency memory ${i}`,
-    vector: [0.1 * i, 0.2 * i, 0.3 * i],
-    category: "fact" as const,
-    scope: "project:rci-test",
-    importance: 0.5,
-  };
-}
-
-// A writer always sees its own commits on its own handle; the staleness gap
-// only exists ACROSS handles. Two independent MemoryStore instances against
-// the same dbPath reproduce the cross-process topology (CLI ingest vs resident
-// MCP/API/UI server) in-process: the writer deletes a row after the reader's
-// handle has already opened the table.
-describe("read consistency across independent connections", () => {
-  it("default (env unset) is strong consistency: reader sees the writer's delete", async () => {
-    delete process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL;
-    const dbPath = tempDb();
-
-    const writer = new MemoryStore({ dbPath, vectorDim: 3 });
-    const e1 = await writer.store(entry(1));
-    await writer.store(entry(2));
-
-    const reader = new MemoryStore({ dbPath, vectorDim: 3 });
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(2);
-
-    await writer.delete(e1.id);
-
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(1);
-  });
-
-  it("env 'off' restores the legacy pinned-handle behavior (negative control)", async () => {
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "off";
-    const dbPath = tempDb();
-
-    const writer = new MemoryStore({ dbPath, vectorDim: 3 });
-    const e1 = await writer.store(entry(1));
-    await writer.store(entry(2));
-
-    const reader = new MemoryStore({ dbPath, vectorDim: 3 });
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(2);
-
-    await writer.delete(e1.id);
-
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(2);
-  });
-
-  it("explicit config wins over env: interval 0 sees the delete despite env 'off'", async () => {
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "off";
-    const dbPath = tempDb();
-
-    const writer = new MemoryStore({ dbPath, vectorDim: 3 });
-    const e1 = await writer.store(entry(1));
-    await writer.store(entry(2));
-
-    const reader = new MemoryStore({ dbPath, vectorDim: 3, readConsistencyInterval: 0 });
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(2);
-
-    await writer.delete(e1.id);
-
-    expect((await reader.list(undefined, undefined, 20, 0)).length).toBe(1);
-  });
-
-  // Cross-handle visibility behavior is pinned by the three tests above;
-  // what remains is the env parsing matrix of the resolver itself.
-  it("env resolver: unset/empty → 0, off/none → undefined, numbers pass, junk clamps to 0", () => {
-    delete process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL;
-    expect(envReadConsistencyInterval()).toBe(0);
-
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "";
-    expect(envReadConsistencyInterval()).toBe(0);
-
-    for (const legacy of ["off", "none"]) {
-      process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = legacy;
-      expect(envReadConsistencyInterval()).toBeUndefined();
-    }
-
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "7";
-    expect(envReadConsistencyInterval()).toBe(7);
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "1.5";
-    expect(envReadConsistencyInterval()).toBe(1.5);
-    process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = "0";
-    expect(envReadConsistencyInterval()).toBe(0);
-
-    for (const junk of ["-3", "abc", "Infinity", "NaN"]) {
-      process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL = junk;
-      expect(envReadConsistencyInterval()).toBe(0);
-    }
-  });
-});

package/src/__tests__/store-schema-migration.test.ts

@@ -1,87 +0,0 @@
-import { describe, expect, it, afterEach } from "bun:test";
-import { mkdtemp, rm } from "fs/promises";
-import { tmpdir } from "os";
-import { join } from "path";
-import * as lancedb from "@lancedb/lancedb";
-
-import { MemoryStore } from "../store.js";
-
-const DIM = 4;
-
-/**
- * Regression: the pre-2026-04-09 table schema has 8 columns (no language /
- * fts_text). The old migration check sampled a row to detect missing columns,
- * so a 0-row legacy table never migrated and EVERY write then failed with
- * "Found field not in schema: language". Production hit exactly this: a table
- * created one day before the columns existed, empty for 3 months.
- */
-
-async function createLegacyTable(dbPath: string, withRow: boolean) {
-  const db = await lancedb.connect(dbPath);
-  const seed = [
-    {
-      id: "__seed__",
-      text: withRow ? "legacy row" : "",
-      vector: new Array(DIM).fill(0),
-      category: "other",
-      scope: "s",
-      importance: 0.5,
-      timestamp: 1,
-      metadata: "{}",
-    },
-  ];
-  const t = await db.createTable("memories", seed);
-  if (!withRow) await t.delete('id = "__seed__"');
-  return t;
-}
-
-describe("MemoryStore schema migration (empty legacy table)", () => {
-  let dir = "";
-  afterEach(async () => {
-    if (dir) await rm(dir, { recursive: true, force: true });
-    dir = "";
-  });
-
-  it("migrates an EMPTY legacy table so writes succeed", async () => {
-    dir = await mkdtemp(join(tmpdir(), "rn-mig-empty-"));
-    await createLegacyTable(dir, false);
-
-    const store = new MemoryStore({ dbPath: dir, vectorDim: DIM });
-    const entry = await store.store({
-      text: "first write after migration",
-      vector: new Array(DIM).fill(0.1),
-      category: "other",
-      scope: "s",
-      importance: 0.5,
-    });
-    expect(entry.id).toBeTruthy();
-
-    const db = await lancedb.connect(dir);
-    const t = await db.openTable("memories");
-    const fields = (await t.schema()).fields.map((f) => f.name);
-    expect(fields).toContain("language");
-    expect(fields).toContain("fts_text");
-  });
-
-  it("migrates a NON-EMPTY legacy table and backfills defaults", async () => {
-    dir = await mkdtemp(join(tmpdir(), "rn-mig-full-"));
-    await createLegacyTable(dir, true);
-
-    const store = new MemoryStore({ dbPath: dir, vectorDim: DIM });
-    await store.store({
-      text: "second row",
-      vector: new Array(DIM).fill(0.2),
-      category: "other",
-      scope: "s",
-      importance: 0.5,
-    });
-
-    const db = await lancedb.connect(dir);
-    const t = await db.openTable("memories");
-    const rows = await t.query().toArray();
-    expect(rows).toHaveLength(2);
-    const legacy = rows.find((r) => r.id === "__seed__") as any;
-    expect(legacy.language).toBe("en");
-    expect(legacy.fts_text).toBe("legacy row");
-  });
-});

package/src/__tests__/store-scope-audit.test.ts

@@ -1,81 +0,0 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { MemoryStore, classifyLegacyScope } from "../store.js";
-
-const cleanupPaths: string[] = [];
-
-afterEach(() => {
-  while (cleanupPaths.length > 0) {
-    const target = cleanupPaths.pop();
-    if (target) {
-      rmSync(target, { recursive: true, force: true });
-    }
-  }
-});
-
-function createStore(): MemoryStore {
-  const dbPath = mkdtempSync(join(tmpdir(), "recallnest-scope-audit-"));
-  cleanupPaths.push(dbPath);
-  return new MemoryStore({
-    dbPath,
-    vectorDim: 3,
-  });
-}
-
-describe("classifyLegacyScope", () => {
-  it("flags missing, empty, and global scope values", () => {
-    expect(classifyLegacyScope(undefined)).toBe("missing");
-    expect(classifyLegacyScope(null)).toBe("missing");
-    expect(classifyLegacyScope("")).toBe("empty");
-    expect(classifyLegacyScope("   ")).toBe("empty");
-    expect(classifyLegacyScope("global")).toBe("global");
-    expect(classifyLegacyScope(" global ")).toBe("global");
-    expect(classifyLegacyScope("project:recallnest")).toBeUndefined();
-  });
-});
-
-describe("MemoryStore.auditLegacyScopes", () => {
-  it("reports global and empty scope rows without mixing in valid scoped data", async () => {
-    const store = createStore();
-
-    await store.store({
-      text: "Scoped memory should not appear in the audit.",
-      vector: [1, 0, 0],
-      category: "entities",
-      scope: "project:recallnest",
-      importance: 0.8,
-      metadata: "{}",
-    });
-    await store.store({
-      text: "Historical row that used the global fallback.",
-      vector: [0, 1, 0],
-      category: "events",
-      scope: "global",
-      importance: 0.5,
-      metadata: "{}",
-    });
-    await store.store({
-      text: "Historical row that was written without a real scope.",
-      vector: [0, 0, 1],
-      category: "events",
-      scope: "   ",
-      importance: 0.4,
-      metadata: "{}",
-    });
-
-    const audit = await store.auditLegacyScopes(10);
-
-    expect(audit.totalCount).toBe(2);
-    expect(audit.counts).toEqual({
-      missing: 0,
-      empty: 1,
-      global: 1,
-    });
-    expect(audit.samples).toHaveLength(2);
-    expect(audit.samples.map((sample) => sample.kind).sort()).toEqual(["empty", "global"]);
-    expect(audit.samples.every((sample) => sample.scope !== "project:recallnest")).toBe(true);
-  });
-});

package/src/__tests__/store-upsert.test.ts

@@ -1,201 +0,0 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { MemoryStore, deterministicId, type MemoryEntry } from "../store.js";
-import { getWriteCount } from "../activity-counter.js";
-
-/**
- * P0-2 回归：store()/storeBatch() 改走 upsert（delete+add 入全局 store-write 锁）后，
- * 相同 deterministicId 的写入是幂等的 —— 同 (scope,text) 写两次只留一行，不再堆 dup-id。
- */
-
-const tmpDirs: string[] = [];
-
-function makeStore(): MemoryStore {
-  const dir = mkdtempSync(join(tmpdir(), "recallnest-upsert-"));
-  tmpDirs.push(dir);
-  return new MemoryStore({ dbPath: dir, vectorDim: 3 });
-}
-
-afterEach(() => {
-  while (tmpDirs.length > 0) {
-    try {
-      rmSync(tmpDirs.pop()!, { recursive: true, force: true });
-    } catch {
-      /* ignore */
-    }
-  }
-});
-
-describe("store P0-2 idempotency (upsert-backed store/storeBatch)", () => {
-  it("store() of the same (scope,text) twice yields one row, latest wins", async () => {
-    const store = makeStore();
-    const scope = "project:upsert-test";
-    await store.store({ text: "同一条内容", vector: [1, 0, 0], category: "entities", scope, importance: 0.7, metadata: "{}" });
-    await store.store({ text: "同一条内容", vector: [1, 0, 0], category: "entities", scope, importance: 0.9, metadata: "{}" });
-
-    const rows = await store.list([scope]);
-    const target = rows.filter((r) => r.text === "同一条内容");
-    expect(target.length).toBe(1);
-    expect(target[0].importance).toBeCloseTo(0.9, 5); // upsert overwrote the 0.7 row
-  });
-
-  it("upsert() with the same id twice overwrites (single row, latest content)", async () => {
-    const store = makeStore();
-    const scope = "project:upsert-test";
-    const id = deterministicId(scope, "anchor");
-    const base: MemoryEntry = {
-      id,
-      text: "v1",
-      vector: [0, 1, 0],
-      category: "entities",
-      scope,
-      importance: 0.5,
-      timestamp: Date.now(),
-      metadata: "{}",
-      language: "en",
-      fts_text: "v1",
-    };
-    await store.upsert(base);
-    await store.upsert({ ...base, text: "v2", fts_text: "v2", importance: 0.8 });
-
-    const rows = await store.list([scope]);
-    const byId = rows.filter((r) => r.id === id);
-    expect(byId.length).toBe(1);
-    expect(byId[0].text).toBe("v2");
-  });
-
-  it("upsert failure leaves the prior row intact (mergeInsert is atomic — no delete+add loss)", async () => {
-    const store = makeStore(); // vectorDim 3
-    const scope = "project:upsert-test";
-    const id = deterministicId(scope, "atomic-anchor");
-    const good: MemoryEntry = {
-      id, text: "original", vector: [1, 0, 0], category: "entities", scope, importance: 0.5,
-      timestamp: Date.now(), metadata: "{}", language: "en", fts_text: "original",
-    };
-    await store.upsert(good);
-
-    // Inject a write failure. With the old delete-then-add path the delete would already
-    // have removed the row before add threw (row lost); the atomic mergeInsert touches
-    // nothing on failure, so the prior row must survive.
-    const table = (store as unknown as { table: { mergeInsert: unknown } }).table;
-    const orig = table.mergeInsert;
-    table.mergeInsert = () => {
-      throw new Error("simulated write failure");
-    };
-    try {
-      await expect(store.upsert({ ...good, text: "corrupt", fts_text: "corrupt" })).rejects.toThrow("simulated write failure");
-    } finally {
-      table.mergeInsert = orig;
-    }
-
-    const survivor = (await store.list([scope])).filter((r) => r.id === id);
-    expect(survivor.length).toBe(1);
-    expect(survivor[0].text).toBe("original"); // prior row preserved, not lost
-  });
-
-  it("storeBatch() honors a caller-supplied id (idempotent re-run)", async () => {
-    const store = makeStore();
-    const scope = "project:upsert-test";
-    const fixedId = deterministicId(scope, "batch-anchor");
-    const entry = {
-      id: fixedId,
-      text: "batch-a",
-      vector: [0, 0, 1] as number[],
-      category: "entities" as const,
-      scope,
-      importance: 0.6,
-      metadata: "{}",
-    };
-    await store.storeBatch([entry]);
-    await store.storeBatch([{ ...entry, text: "batch-a-updated", fts_text: "batch-a-updated" }]);
-
-    const rows = await store.list([scope]);
-    const byId = rows.filter((r) => r.id === fixedId);
-    expect(byId.length).toBe(1);
-    expect(byId[0].text).toBe("batch-a-updated");
-  });
-
-  it("storeBatch() collapses in-batch duplicate ids (latest-wins) into one row", async () => {
-    const store = makeStore();
-    const scope = "project:upsert-test";
-    const stored = await store.storeBatch([
-      { text: "dup-in-batch", vector: [1, 0, 0], category: "entities", scope, importance: 0.3, metadata: "{}" },
-      { text: "dup-in-batch", vector: [1, 0, 0], category: "entities", scope, importance: 0.8, metadata: "{}" },
-    ]);
-    expect(stored).toBe(1); // two same-(scope,text) entries collapse to one
-    const rows = await store.list([scope]);
-    const target = rows.filter((r) => r.text === "dup-in-batch");
-    expect(target.length).toBe(1);
-    expect(target[0].importance).toBeCloseTo(0.8, 5); // last occurrence wins
-  });
-
-  // A store whose activity-stats sits in its own unique dir (dirname(dbPath)), so the
-  // per-scope counter assertions are isolated from other tests' shared tmproot writes.
-  function makeIsolatedStore(): { store: MemoryStore; statsPath: string } {
-    const dir = mkdtempSync(join(tmpdir(), "recallnest-count-"));
-    tmpDirs.push(dir);
-    const dbPath = join(dir, "lancedb");
-    return { store: new MemoryStore({ dbPath, vectorDim: 3 }), statsPath: join(dir, "activity-stats.json") };
-  }
-
-  it("store() increments the per-scope write counter once each (no double-count via upsert)", async () => {
-    const { store, statsPath } = makeIsolatedStore();
-    const scope = "cc:project:count-a";
-    await store.store({ text: "m1", vector: [1, 0, 0], category: "entities", scope, importance: 0.5, metadata: "{}" });
-    await store.store({ text: "m2", vector: [0, 1, 0], category: "entities", scope, importance: 0.5, metadata: "{}" });
-    // store()→upsert() counts once per call; two stores ⇒ 2 (not 4).
-    expect(getWriteCount(scope, { statsPath })).toBe(2);
-  });
-
-  it("storeBatch() counts per scope by number of entries in that scope", async () => {
-    const { store, statsPath } = makeIsolatedStore();
-    await store.storeBatch([
-      { text: "a", vector: [1, 0, 0], category: "entities", scope: "cc:s1", importance: 0.5, metadata: "{}" },
-      { text: "b", vector: [0, 1, 0], category: "entities", scope: "cc:s1", importance: 0.5, metadata: "{}" },
-      { text: "c", vector: [0, 0, 1], category: "entities", scope: "cc:s2", importance: 0.5, metadata: "{}" },
-    ]);
-    expect(getWriteCount("cc:s1", { statsPath })).toBe(2);
-    expect(getWriteCount("cc:s2", { statsPath })).toBe(1);
-  });
-
-  it("storeBatch() with an in-batch duplicate counts the collapsed row once", async () => {
-    const { store, statsPath } = makeIsolatedStore();
-    await store.storeBatch([
-      { text: "dup", vector: [1, 0, 0], category: "entities", scope: "cc:s3", importance: 0.3, metadata: "{}" },
-      { text: "dup", vector: [1, 0, 0], category: "entities", scope: "cc:s3", importance: 0.8, metadata: "{}" },
-    ]);
-    expect(getWriteCount("cc:s3", { statsPath })).toBe(1); // deduped to one row ⇒ counted once
-  });
-
-  it("storeBatch() without ids still stores distinct entries", async () => {
-    const store = makeStore();
-    const scope = "project:upsert-test";
-    const stored = await store.storeBatch([
-      { text: "batch-x", vector: [1, 0, 0], category: "entities", scope, importance: 0.5, metadata: "{}" },
-      { text: "batch-y", vector: [0, 1, 0], category: "entities", scope, importance: 0.5, metadata: "{}" },
-    ]);
-    expect(stored).toBe(2);
-    const rows = await store.list([scope]);
-    expect(rows.filter((r) => r.text === "batch-x" || r.text === "batch-y").length).toBe(2);
-  });
-});
-
-describe("update() vector fallback (2026-07-23 null-vector regression)", () => {
-  it("metadata-only update preserves the original vector on healthy rows", async () => {
-    const store = makeStore();
-    const scope = "project:nullvec-test";
-    const entry = await store.store({
-      text: "健康行", vector: [0.1, 0.2, 0.3], category: "events", scope, importance: 0.7, metadata: "{}",
-    });
-    const updated = await store.update(entry.id, { metadata: JSON.stringify({ touched: true }) });
-    expect(updated).not.toBeNull();
-    // 修复 row.vector null-guard 后，正常行的 vector 必须原样保留（回归保护）
-    const rows = await store.list([scope]);
-    expect(rows.length).toBe(1);
-    const meta = JSON.parse(rows[0].metadata || "{}") as Record<string, unknown>;
-    expect(meta.touched).toBe(true);
-  });
-});

package/src/__tests__/supersede-chain.test.ts

@@ -1,154 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import {
-  buildSupersedeMetadata,
-  buildSupersedeMetadataForNew,
-  parseEvolution,
-  traceEvolution,
-  patchEvolution,
-  defaultEvolution,
-} from "../memory-evolution.js";
-
-describe("HP-1: Superseded chain enhancement", () => {
-  describe("bidirectional linking", () => {
-    it("buildSupersedeMetadata marks old → supersededBy", () => {
-      const oldMeta = patchEvolution("{}", defaultEvolution());
-      const result = buildSupersedeMetadata(oldMeta, "new-id");
-      const evo = parseEvolution(result);
-      expect(evo.status).toBe("superseded");
-      expect(evo.supersededBy).toBe("new-id");
-      expect(evo.validUntil).toBeGreaterThan(0);
-    });
-
-    it("buildSupersedeMetadataForNew marks new → supersedes + note", () => {
-      const newMeta = patchEvolution("{}", defaultEvolution());
-      const result = buildSupersedeMetadataForNew(newMeta, "old-id", "updated preference");
-      const evo = parseEvolution(result);
-      expect(evo.status).toBe("active"); // new memory stays active
-      expect(evo.supersedes).toBe("old-id");
-      expect(evo.evolutionNote).toBe("updated preference");
-    });
-
-    it("bidirectional: old.supersededBy == new.id AND new.supersedes == old.id", () => {
-      const oldMeta = patchEvolution("{}", defaultEvolution());
-      const newMeta = patchEvolution("{}", defaultEvolution());
-
-      const updatedOld = buildSupersedeMetadata(oldMeta, "new-id");
-      const updatedNew = buildSupersedeMetadataForNew(newMeta, "old-id");
-
-      const oldEvo = parseEvolution(updatedOld);
-      const newEvo = parseEvolution(updatedNew);
-
-      expect(oldEvo.supersededBy).toBe("new-id");
-      expect(newEvo.supersedes).toBe("old-id");
-    });
-  });
-
-  describe("traceEvolution", () => {
-    it("traces a 3-node chain", async () => {
-      // v1 → v2 → v3
-      const entries: Record<string, { metadata: string; timestamp: number }> = {
-        v1: {
-          metadata: patchEvolution("{}", {
-            status: "superseded",
-            supersededBy: "v2",
-            validFrom: 1000,
-            validUntil: 2000,
-          }),
-          timestamp: 1000,
-        },
-        v2: {
-          metadata: patchEvolution("{}", {
-            status: "superseded",
-            supersedes: "v1",
-            supersededBy: "v3",
-            evolutionNote: "added detail",
-            validFrom: 2000,
-            validUntil: 3000,
-          }),
-          timestamp: 2000,
-        },
-        v3: {
-          metadata: patchEvolution("{}", {
-            status: "active",
-            supersedes: "v2",
-            evolutionNote: "corrected error",
-            validFrom: 3000,
-          }),
-          timestamp: 3000,
-        },
-      };
-
-      const getEntry = async (id: string) => entries[id] ?? null;
-
-      // Trace from v2 (middle)
-      const trace = await traceEvolution("v2", getEntry);
-      expect(trace.length).toBe(3);
-      expect(trace[0].id).toBe("v1");
-      expect(trace[0].direction).toBe("predecessor");
-      expect(trace[1].id).toBe("v2");
-      expect(trace[1].direction).toBe("self");
-      expect(trace[2].id).toBe("v3");
-      expect(trace[2].direction).toBe("successor");
-    });
-
-    it("handles single node (no chain)", async () => {
-      const getEntry = async (id: string) => {
-        if (id === "solo") return { metadata: patchEvolution("{}", defaultEvolution()), timestamp: 1000 };
-        return null;
-      };
-
-      const trace = await traceEvolution("solo", getEntry);
-      expect(trace.length).toBe(1);
-      expect(trace[0].direction).toBe("self");
-    });
-
-    it("respects maxDepth", async () => {
-      // Create a long chain: v0 → v1 → v2 → ... → v20
-      const entries: Record<string, { metadata: string; timestamp: number }> = {};
-      for (let i = 0; i <= 20; i++) {
-        entries[`v${i}`] = {
-          metadata: patchEvolution("{}", {
-            status: i < 20 ? "superseded" : "active",
-            supersedes: i > 0 ? `v${i - 1}` : null,
-            supersededBy: i < 20 ? `v${i + 1}` : null,
-            validFrom: i * 1000,
-          }),
-          timestamp: i * 1000,
-        };
-      }
-
-      const getEntry = async (id: string) => entries[id] ?? null;
-      const trace = await traceEvolution("v10", getEntry, 3);
-      // maxDepth=3: at most 3 predecessors + self + 3 successors = 7
-      expect(trace.length).toBeLessThanOrEqual(7);
-    });
-
-    it("handles missing entries gracefully", async () => {
-      const entries: Record<string, { metadata: string; timestamp: number }> = {
-        v1: {
-          metadata: patchEvolution("{}", {
-            status: "active",
-            supersedes: "missing",
-            validFrom: 1000,
-          }),
-          timestamp: 1000,
-        },
-      };
-      const getEntry = async (id: string) => entries[id] ?? null;
-      const trace = await traceEvolution("v1", getEntry);
-      expect(trace.length).toBe(1); // only self, missing predecessor stops chain
-    });
-  });
-
-  describe("backward compatibility", () => {
-    it("parseEvolution defaults new fields to null", () => {
-      // Old metadata without supersedes/evolutionNote
-      const oldMeta = JSON.stringify({
-        evolution: { status: "active", version: 1, accessCount: 0 },
-      });
-      const evo = parseEvolution(oldMeta);
-      expect(evo.supersedes).toBeNull();
-      expect(evo.evolutionNote).toBeNull();
-    });
-  });
-});