recallnest 2.3.0 → 2.5.4

package/src/__tests__/doctor.test.ts

@@ -0,0 +1,319 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  assessContinuityBaseline,
+  assessScopeInventoryReport,
+  describeSecretPresence,
+  formatDoctorResults,
+  loadContinuityBaselineEntries,
+} from "../doctor.js";
+import type { MemoryEntry } from "../store.js";
+
+function buildEntry(
+  id: string,
+  category: MemoryEntry["category"],
+  text: string,
+  scope: string,
+  metadata: Record<string, unknown> = {},
+): MemoryEntry {
+  return {
+    id,
+    text,
+    vector: [],
+    category,
+    scope,
+    importance: 0.8,
+    timestamp: Date.parse("2026-03-17T00:00:00.000Z"),
+    metadata: JSON.stringify(metadata),
+  };
+}
+
+describe("assessContinuityBaseline", () => {
+  it("reports full coverage when all canonical continuity seeds are present", () => {
+    const seeds = {
+      patterns: [
+        {
+          title: "Cross-window continuity handoff",
+          trigger: "When opening a fresh terminal window",
+          steps: ["Call resume_context before coding."],
+          outcome: "Fresh windows recover stable context.",
+          tools: ["resume_context"],
+          importance: 0.9,
+          source: "agent",
+        },
+      ],
+      cases: [
+        {
+          title: "Continuity eval checkpoint isolation",
+          problem: "Eval reads live checkpoints.",
+          solutionSteps: ["Use fixture checkpoints instead."],
+          outcome: "Continuity eval becomes deterministic.",
+          tools: ["eval:continuity"],
+          source: "agent",
+          scope: "recallnest",
+          importance: 0.85,
+        },
+      ],
+      memories: [
+        {
+          text: "RecallNest is the shared memory layer for Claude Code, Codex, and Gemini CLI.",
+          category: "entities",
+          scope: "recallnest",
+          source: "agent",
+          importance: 0.9,
+          canonicalKey: "entities:recallnest:shared-memory-layer",
+        },
+      ],
+    };
+
+    const entries: MemoryEntry[] = [
+      buildEntry(
+        "pattern-1",
+        "patterns",
+        "Workflow pattern: Cross-window continuity handoff",
+        "memory:agent",
+        { workflowPattern: { title: "Cross-window continuity handoff" } },
+      ),
+      buildEntry(
+        "case-1",
+        "cases",
+        "Case: Continuity eval checkpoint isolation",
+        "recallnest",
+        { caseMemory: { title: "Continuity eval checkpoint isolation" } },
+      ),
+      buildEntry(
+        "memory-1",
+        "entities",
+        "RecallNest is the shared memory layer for Claude Code, Codex, and Gemini CLI.",
+        "recallnest",
+        { canonicalKey: "entities:recallnest:shared-memory-layer" },
+      ),
+    ];
+
+    const assessment = assessContinuityBaseline(entries, seeds as any);
+
+    expect(assessment.found).toEqual({ patterns: 1, cases: 1, memories: 1 });
+    expect(assessment.missing).toEqual({ patterns: [], cases: [], memories: [] });
+  });
+
+  it("reports missing canonical seeds by category", () => {
+    const seeds = {
+      patterns: [
+        {
+          title: "Recall before repo exploration",
+          trigger: "When startup context is sparse",
+          steps: ["Run search_memory before local repo exploration."],
+          outcome: "Fresh windows recover task-specific continuity.",
+          tools: ["resume_context", "search_memory"],
+          importance: 0.9,
+          source: "agent",
+        },
+      ],
+      cases: [
+        {
+          title: "RecallNest scope fallback cleanup",
+          problem: "Project continuity prefers raw transcript notes.",
+          solutionSteps: ["Prefer durable cases and patterns."],
+          outcome: "Stable project continuity becomes cleaner.",
+          tools: ["resume_context"],
+          source: "agent",
+          scope: "recallnest",
+          importance: 0.85,
+        },
+      ],
+      memories: [
+        {
+          text: "RecallNest continuity revolves around three primitives.",
+          category: "entities",
+          scope: "recallnest",
+          source: "agent",
+          importance: 0.9,
+          canonicalKey: "entities:recallnest:continuity-primitives",
+        },
+      ],
+    };
+
+    const entries: MemoryEntry[] = [
+      buildEntry(
+        "pattern-1",
+        "patterns",
+        "Workflow pattern: Cross-window continuity handoff",
+        "memory:agent",
+        { workflowPattern: { title: "Cross-window continuity handoff" } },
+      ),
+    ];
+
+    const assessment = assessContinuityBaseline(entries, seeds as any);
+
+    expect(assessment.found).toEqual({ patterns: 0, cases: 0, memories: 0 });
+    expect(assessment.missing.patterns).toEqual(["Recall before repo exploration"]);
+    expect(assessment.missing.cases).toEqual(["RecallNest scope fallback cleanup"]);
+    expect(assessment.missing.memories).toEqual(["entities:recallnest:continuity-primitives"]);
+  });
+
+  it("loads enough entries for baseline checks when the index is larger than the legacy 5000-entry window", async () => {
+    const targetEntry = buildEntry(
+      "pattern-target",
+      "patterns",
+      "Workflow pattern: RecallNest MCP transport rollout",
+      "project:recallnest",
+      { workflowPattern: { title: "RecallNest MCP transport rollout" } },
+    );
+    const entries: MemoryEntry[] = [
+      ...Array.from({ length: 5000 }, (_, index) => buildEntry(
+        `noise-${index}`,
+        "patterns",
+        `Workflow pattern: Noise ${index}`,
+        "memory:agent",
+        { workflowPattern: { title: `Noise ${index}` } },
+      )),
+      targetEntry,
+    ];
+    const listCalls: Array<[string[] | undefined, string | undefined, number | undefined, number | undefined]> = [];
+    const store = {
+      async list(scopeFilter?: string[], category?: string, limit = 20, offset = 0): Promise<MemoryEntry[]> {
+        listCalls.push([scopeFilter, category, limit, offset]);
+        return entries.slice(offset, offset + limit);
+      },
+    };
+
+    const loaded = await loadContinuityBaselineEntries(store as any, entries.length);
+    const assessment = assessContinuityBaseline(loaded, {
+      patterns: [
+        {
+          title: "RecallNest MCP transport rollout",
+          trigger: "When RecallNest continuity work touches MCP transport wiring under project scope",
+          steps: ["Call resume_context with project:recallnest before transport changes."],
+          outcome: "RecallNest transport changes stay project-scoped.",
+          tools: ["resume_context", "search_memory", "eval:continuity"],
+          source: "agent",
+          scope: "project:recallnest",
+          importance: 0.87,
+        },
+      ],
+      cases: [],
+      memories: [],
+    } as any);
+
+    expect(listCalls).toEqual([[undefined, undefined, 5001, 0]]);
+    expect(assessment.found.patterns).toBe(1);
+    expect(assessment.missing.patterns).toEqual([]);
+  });
+});
+
+describe("assessScopeInventoryReport", () => {
+  it("reports a clean scope inventory when no unresolved anomalies remain", () => {
+    const result = assessScopeInventoryReport({
+      generatedAt: "2026-03-19T08:20:00.000Z",
+      sampleLimit: 5,
+      totalScannedCount: 42,
+      totalAnomalyCount: 0,
+      totalInvalidCount: 0,
+      totalReviewedCount: 1,
+      layers: [
+        {
+          layer: "memories",
+          scannedCount: 40,
+          anomalyCount: 0,
+          invalidCount: 0,
+          reviewedCount: 0,
+          counts: { missing: 0, empty: 0, global: 0 },
+          samples: [],
+          recommendation: "ok",
+        },
+        {
+          layer: "workflow-observations",
+          scannedCount: 2,
+          anomalyCount: 0,
+          invalidCount: 0,
+          reviewedCount: 1,
+          counts: { missing: 0, empty: 0, global: 0 },
+          samples: [],
+          recommendation: "ok",
+        },
+      ],
+    });
+
+    expect(result).toEqual({
+      name: "Scope inventory",
+      status: "pass",
+      message: "0 unresolved anomalies across 42 records; reviewed keeps 1",
+    });
+  });
+
+  it("warns when scope inventory still has unresolved anomalies or invalid files", () => {
+    const result = assessScopeInventoryReport({
+      generatedAt: "2026-03-19T08:20:00.000Z",
+      sampleLimit: 5,
+      totalScannedCount: 12,
+      totalAnomalyCount: 2,
+      totalInvalidCount: 1,
+      totalReviewedCount: 0,
+      layers: [
+        {
+          layer: "pins",
+          scannedCount: 4,
+          anomalyCount: 1,
+          invalidCount: 0,
+          reviewedCount: 0,
+          counts: { missing: 0, empty: 0, global: 1 },
+          samples: [{
+            layer: "pins",
+            id: "pin-legacy-1234",
+            kind: "global",
+            scope: "global",
+            context: "pin",
+            preview: "Legacy pin",
+            recordedAt: "2026-03-19T08:00:00.000Z",
+          }],
+          recommendation: "re-pin",
+        },
+        {
+          layer: "workflow-observations",
+          scannedCount: 8,
+          anomalyCount: 1,
+          invalidCount: 1,
+          reviewedCount: 0,
+          counts: { missing: 1, empty: 0, global: 0 },
+          samples: [],
+          recommendation: "review",
+        },
+      ],
+    });
+
+    expect(result.status).toBe("warn");
+    expect(result.name).toBe("Scope inventory");
+    expect(result.message).toContain("2 unresolved anomalies, 1 invalid file(s) across 12 records");
+    expect(result.message).toContain("pins:1");
+    expect(result.message).toContain("workflow-observations:1 invalid 1");
+    expect(result.message).toContain("sample pins:global:pin-lega");
+    expect(result.fix).toBe("bun run scope-inventory");
+  });
+});
+
+describe("formatDoctorResults", () => {
+  it("does not claim all clear when warnings are present", () => {
+    const output = formatDoctorResults([
+      { name: "Bun runtime", status: "pass", message: "ok" },
+      { name: "Scope inventory", status: "warn", message: "1 unresolved anomaly", fix: "bun run scope-inventory" },
+    ]);
+
+    expect(output).toContain("Review the ⚠️ items above before relying on this environment as a clean baseline.");
+    expect(output).not.toContain("All clear.");
+  });
+});
+
+describe("describeSecretPresence", () => {
+  it("reports only presence and never includes the configured value", () => {
+    const secret = "sensitive-value-that-must-not-appear";
+    const message = describeSecretPresence(secret, "placeholder");
+
+    expect(message).toBe("set");
+    expect(message).not.toContain(secret);
+  });
+
+  it("does not treat an absent or placeholder value as configured", () => {
+    expect(describeSecretPresence(undefined, "placeholder")).toBeNull();
+    expect(describeSecretPresence("placeholder", "placeholder")).toBeNull();
+  });
+});

package/src/__tests__/dream-pipeline.test.ts

@@ -0,0 +1,321 @@
+import { describe, expect, it, beforeEach, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDream, formatDreamResult, type DreamResult } from "../dream-pipeline.js";
+import type { MemoryEntry, MemoryStore } from "../store.js";
+import type { LLMClient } from "../llm-client.js";
+import type { Embedder } from "../embedder.js";
+import { resetWriteCount } from "../activity-counter.js";
+
+// Isolate the activity-counter (default path = <dataDir>/activity-stats.json) to a temp
+// dir so these tests never read/write the repo's data/activity-stats.json that the
+// production dream scheduler uses.
+let __origDataDir: string | undefined;
+beforeAll(() => {
+  __origDataDir = process.env.RECALLNEST_DATA_DIR;
+  process.env.RECALLNEST_DATA_DIR = mkdtempSync(join(tmpdir(), "rn-dp-datadir-"));
+});
+afterAll(() => {
+  if (__origDataDir === undefined) delete process.env.RECALLNEST_DATA_DIR;
+  else process.env.RECALLNEST_DATA_DIR = __origDataDir;
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(overrides: Partial<MemoryEntry> & { id: string }): MemoryEntry {
+  return {
+    text: "test memory",
+    vector: [1, 0, 0, 0, 0],
+    category: "events",
+    scope: "project:test",
+    importance: 0.5,
+    timestamp: Date.now(),
+    metadata: JSON.stringify({
+      evolution: {
+        status: "active",
+        version: 1,
+        accessCount: 0,
+        lastAccessedAt: null,
+        supersededBy: null,
+        consolidatedInto: null,
+        contributedToPattern: null,
+        sourceMemories: [],
+        validFrom: Date.now(),
+        validUntil: null,
+      },
+    }),
+    ...overrides,
+  };
+}
+
+function createMockStore(entries: MemoryEntry[]): MemoryStore {
+  const stored: MemoryEntry[] = [...entries];
+  let storeCounter = 0;
+
+  return {
+    async list() { return stored; },
+    async stats() {
+      return {
+        totalCount: stored.length,
+        scopeCounts: {},
+        categoryCounts: {},
+      };
+    },
+    async store(entry: Partial<MemoryEntry>) {
+      const full = {
+        id: entry.id || `dream-${storeCounter++}`,
+        text: entry.text || "",
+        vector: entry.vector || [],
+        category: entry.category || "events",
+        scope: entry.scope || "project:test",
+        importance: entry.importance || 0.5,
+        timestamp: Date.now(),
+        metadata: entry.metadata || "{}",
+      } as MemoryEntry;
+      stored.push(full);
+      return full;
+    },
+    async update(id: string, upd: Partial<MemoryEntry>) {
+      const entry = stored.find(e => e.id === id);
+      if (entry && upd.metadata) entry.metadata = upd.metadata;
+      return entry || { id, text: "", vector: [], category: "events", scope: "project:test", importance: 0.5, timestamp: Date.now(), metadata: "{}" } as MemoryEntry;
+    },
+    async getById(id: string) {
+      return stored.find(e => e.id === id) || null;
+    },
+    // 模拟 store.patchMetadata 单写通道:读最新 metadata → patchFn → 写回。
+    async patchMetadata(
+      id: string,
+      patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
+      _scopeFilter?: string[],
+    ) {
+      const entry = stored.find(e => e.id === id);
+      if (!entry) return null;
+      let meta: Record<string, unknown>;
+      try {
+        const parsed: unknown = JSON.parse(entry.metadata || "{}");
+        meta = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+          ? (parsed as Record<string, unknown>)
+          : {};
+      } catch {
+        meta = {};
+      }
+      entry.metadata = JSON.stringify(patchFn(meta, entry));
+      return entry;
+    },
+    async vectorSearch(_vec: number[], limit: number, _threshold: number, _scopes?: string[]) {
+      return stored.slice(0, limit).map(e => ({ entry: e, score: 0.85 }));
+    },
+  } as unknown as MemoryStore;
+}
+
+function createMockLLM(): LLMClient {
+  return {
+    async generateL0() { return "consolidated insight"; },
+    async extractPattern() { return "discovered pattern"; },
+  } as unknown as LLMClient;
+}
+
+function createMockEmbedder(): Pick<Embedder, "embedPassage"> {
+  return {
+    async embedPassage() { return [0.5, 0.5, 0, 0, 0]; },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("runDream", () => {
+  beforeEach(() => {
+    // Reset the activity counter for the test scope between tests (per-scope API).
+    resetWriteCount("project:test");
+  });
+
+  it("skips when write count is below threshold", async () => {
+    const store = createMockStore([makeEntry({ id: "a" })]);
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      config: { minWritesForDream: 10 },
+    });
+
+    expect(result.ran).toBe(false);
+    expect(result.reason).toContain("insufficient_writes");
+    expect(result.phases.length).toBe(1);
+    expect(result.phases[0].phase).toBe("orient");
+  });
+
+  it("persists usageStatus snapshots during gather (P0 B-1, flag on)", async () => {
+    process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL = "true";
+    try {
+    const coldMeta = JSON.stringify({
+      accessCount: 8, // injection >= 6, useCount 0 -> cold
+      evolution: { status: "active", version: 1 },
+    });
+    const entries = [
+      makeEntry({ id: "cold-1", metadata: coldMeta }),
+      makeEntry({ id: "fresh-1" }), // unused 默认态:不写快照,防全库写放大
+    ];
+    const store = createMockStore(entries);
+
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+    });
+
+    expect(result.ran).toBe(true);
+    const cold = await store.getById("cold-1");
+    expect(JSON.parse(cold!.metadata!).usage.usageStatus).toBe("cold");
+    const fresh = await store.getById("fresh-1");
+    expect(JSON.parse(fresh!.metadata!).usage).toBeUndefined();
+    const gather = result.phases.find(p => p.phase === "gather");
+    expect(gather!.detail).toContain("usage snapshot: 1");
+    } finally {
+      delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+    }
+  });
+
+  it("skips usageStatus snapshots when use signal is inactive (flag off)", async () => {
+    delete process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL;
+    const coldMeta = JSON.stringify({
+      accessCount: 8,
+      evolution: { status: "active", version: 1 },
+    });
+    const store = createMockStore([makeEntry({ id: "cold-1", metadata: coldMeta })]);
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+    });
+    expect(result.ran).toBe(true);
+    const cold = await store.getById("cold-1");
+    expect(JSON.parse(cold!.metadata!).usage).toBeUndefined();
+    const gather = result.phases.find(p => p.phase === "gather");
+    expect(gather!.detail).not.toContain("usage snapshot");
+  });
+
+  it("runs when forced despite low write count", async () => {
+    const entries = [
+      makeEntry({ id: "a", vector: [0.9, 0.1, 0, 0, 0] }),
+      makeEntry({ id: "b", vector: [0.88, 0.12, 0, 0, 0] }),
+      makeEntry({ id: "c", vector: [0.92, 0.08, 0, 0, 0] }),
+    ];
+    const store = createMockStore(entries);
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+    });
+
+    expect(result.ran).toBe(true);
+    expect(result.phases.length).toBe(4);
+    expect(result.phases.map(p => p.phase)).toEqual(["orient", "gather", "consolidate", "prune"]);
+  });
+
+  it("completes early with too few active entries", async () => {
+    const store = createMockStore([
+      makeEntry({ id: "a" }),
+    ]);
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+      config: { minClusterSize: 3 },
+    });
+
+    expect(result.ran).toBe(true);
+    expect(result.reason).toBe("completed_early");
+  });
+
+  it("works without LLM (null) — only deterministic consolidation", async () => {
+    const entries = [
+      makeEntry({ id: "a", vector: [0.9, 0.1, 0, 0, 0] }),
+      makeEntry({ id: "b", vector: [0.88, 0.12, 0, 0, 0] }),
+      makeEntry({ id: "c", vector: [0.92, 0.08, 0, 0, 0] }),
+    ];
+    const store = createMockStore(entries);
+    const result = await runDream({
+      store,
+      llm: null,
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+    });
+
+    expect(result.ran).toBe(true);
+    expect(result.stats.insightsGenerated).toBe(0); // No LLM = no insights
+    expect(result.stats.patternsExtracted).toBe(0);
+  });
+
+  it("reports correct stats structure", async () => {
+    const entries = [
+      makeEntry({ id: "a", vector: [0.9, 0.1, 0, 0, 0] }),
+      makeEntry({ id: "b", vector: [0.88, 0.12, 0, 0, 0] }),
+      makeEntry({ id: "c", vector: [0.92, 0.08, 0, 0, 0] }),
+    ];
+    const store = createMockStore(entries);
+    const result = await runDream({
+      store,
+      llm: createMockLLM(),
+      embedder: createMockEmbedder(),
+      scope: "project:test",
+      force: true,
+    });
+
+    expect(result.stats.totalMemories).toBeGreaterThanOrEqual(0);
+    expect(result.stats.activeMemories).toBeGreaterThanOrEqual(0);
+    expect(typeof result.stats.clustersFound).toBe("number");
+    expect(typeof result.stats.insightsGenerated).toBe("number");
+    expect(typeof result.stats.patternsExtracted).toBe("number");
+    expect(typeof result.stats.mergedCount).toBe("number");
+    expect(typeof result.stats.archivedCount).toBe("number");
+  });
+});
+
+describe("formatDreamResult", () => {
+  it("formats skipped dream", () => {
+    const result: DreamResult = {
+      ran: false,
+      reason: "insufficient_writes (3/10)",
+      phases: [{ phase: "orient", detail: "50 memories, 3 writes" }],
+      stats: { totalMemories: 50, activeMemories: 0, writesSinceLastDream: 3, clustersFound: 0, insightsGenerated: 0, patternsExtracted: 0, mergedCount: 0, archivedCount: 0 },
+    };
+    const output = formatDreamResult(result);
+    expect(output).toContain("skipped");
+    expect(output).toContain("insufficient_writes");
+  });
+
+  it("formats completed dream with all phases", () => {
+    const result: DreamResult = {
+      ran: true,
+      phases: [
+        { phase: "orient", detail: "100 memories, 15 writes" },
+        { phase: "gather", detail: "80 active entries" },
+        { phase: "consolidate", detail: "3 clusters, 1 merged, 2 insights, 1 pattern" },
+        { phase: "prune", detail: "5 entries archived" },
+      ],
+      stats: { totalMemories: 100, activeMemories: 80, writesSinceLastDream: 15, clustersFound: 3, insightsGenerated: 2, patternsExtracted: 1, mergedCount: 1, archivedCount: 5 },
+    };
+    const output = formatDreamResult(result);
+    expect(output).toContain("Dream completed");
+    expect(output).toContain("[orient]");
+    expect(output).toContain("[consolidate]");
+    expect(output).toContain("[prune]");
+    expect(output).toContain("Patterns: 1");
+  });
+});