@vellumai/assistant 0.5.16 → 0.6.1

package/src/__tests__/llm-usage-store.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 mock.module("../util/logger.js", () => ({
   getLogger: () =>
@@ -7,7 +7,7 @@ mock.module("../util/logger.js", () => ({
     }),
 }));
 
-import { getDb, initializeDb, resetDb } from "../memory/db.js";
+import { getDb, initializeDb } from "../memory/db.js";
 import {
   getUsageDayBuckets,
   getUsageGroupBreakdown,
@@ -21,10 +21,6 @@ import type { PricingResult, UsageEventInput } from "../usage/types.js";
 // Initialize db once before all tests
 initializeDb();
 
-afterAll(() => {
-  resetDb();
-});
-
 function makeInput(overrides?: Partial<UsageEventInput>): UsageEventInput {
   return {
     provider: "anthropic",

package/src/__tests__/log-export-workspace.test.ts

@@ -5,8 +5,6 @@
  * - audit-data.json with tool invocation records
  * - daemon-logs/ with log file contents
  * - config-snapshot.json with sanitized config
- * - workspace/ with text files, SQL dumps for .db files, and proper
- *   filtering (excluded directories, binary files, symlinks).
  */
 
 import { spawnSync } from "node:child_process";
@@ -16,16 +14,14 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
-  symlinkSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterAll, describe, expect, mock, test } from "bun:test";
+import { describe, expect, mock, test } from "bun:test";
 
 // Set up temp directories before mocking
-const testDir = process.env.VELLUM_WORKSPACE_DIR!;
-const testWorkspaceDir = testDir;
+const testWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
 mkdirSync(testWorkspaceDir, { recursive: true });
 
 mock.module("../util/logger.js", () => ({
@@ -40,15 +36,11 @@ mock.module("../util/secure-keys.js", () => ({
   getSecureKeyAsync: async () => undefined,
 }));
 
-import { initializeDb, resetDb } from "../memory/db.js";
+import { initializeDb } from "../memory/db.js";
 import { logExportRouteDefinitions } from "../runtime/routes/log-export-routes.js";
 
 initializeDb();
 
-afterAll(() => {
-  resetDb();
-});
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -56,11 +48,13 @@ afterAll(() => {
 const routes = logExportRouteDefinitions();
 const exportRoute = routes.find((r) => r.endpoint === "export")!;
 
-async function callExport(): Promise<Response> {
+async function callExport(
+  body: Record<string, unknown> = {},
+): Promise<Response> {
   const req = new Request("http://localhost/v1/export", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({}),
+    body: JSON.stringify(body),
   });
   const url = new URL(req.url);
   return exportRoute.handler({
@@ -89,73 +83,37 @@ async function extractArchive(res: Response): Promise<string> {
   return extractDir;
 }
 
-/** Recursively lists all files under a directory as relative paths. */
-function listFiles(dir: string, base = dir): string[] {
-  const result: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      result.push(...listFiles(full, base));
-    } else {
-      result.push(full.slice(base.length + 1));
-    }
-  }
-  return result;
-}
-
 // ---------------------------------------------------------------------------
-// Seed workspace files
+// Seed test data
 // ---------------------------------------------------------------------------
 
-// Text files — should be included
-writeFileSync(join(testWorkspaceDir, "IDENTITY.md"), "# My Identity\nHello");
-mkdirSync(join(testWorkspaceDir, "notes"), { recursive: true });
-writeFileSync(join(testWorkspaceDir, "notes", "daily.txt"), "Some daily notes");
-
-// SQLite DB file — should be dumped as .sql
-mkdirSync(join(testWorkspaceDir, "data", "db"), { recursive: true });
-// Create a real sqlite db with a table
-import { Database } from "bun:sqlite";
-const wsDbPath = join(testWorkspaceDir, "data", "db", "assistant.db");
-const wsDb = new Database(wsDbPath);
-wsDb.run("CREATE TABLE test_table (id INTEGER PRIMARY KEY, name TEXT)");
-wsDb.run("INSERT INTO test_table (name) VALUES ('hello')");
-wsDb.close();
-
-// Excluded directory: embedding-models/
-mkdirSync(join(testWorkspaceDir, "embedding-models"), { recursive: true });
+// config.json at workspace root — needed for config-snapshot test
 writeFileSync(
-  join(testWorkspaceDir, "embedding-models", "model.bin"),
-  "large binary model data",
+  join(testWorkspaceDir, "config.json"),
+  JSON.stringify({ provider: "anthropic" }),
 );
 
-// Excluded directory: data/qdrant/
-mkdirSync(join(testWorkspaceDir, "data", "qdrant"), { recursive: true });
+// Daemon log files — used for date filtering tests
+const logsDir = join(testWorkspaceDir, "data", "logs");
+mkdirSync(logsDir, { recursive: true });
 writeFileSync(
-  join(testWorkspaceDir, "data", "qdrant", "index.bin"),
-  "vector index data",
+  join(logsDir, "assistant-2025-01-10.log"),
+  "log entry from Jan 10\n",
 );
-
-// Binary file — should be skipped
 writeFileSync(
-  join(testWorkspaceDir, "binary-file.dat"),
-  Buffer.from([0x48, 0x65, 0x6c, 0x00, 0x6f]), // contains null byte
+  join(logsDir, "assistant-2025-01-15.log"),
+  "log entry from Jan 15\n",
 );
-
-// config.json at workspace root — should be skipped (already in configSnapshot)
 writeFileSync(
-  join(testWorkspaceDir, "config.json"),
-  JSON.stringify({ provider: "anthropic" }),
+  join(logsDir, "assistant-2025-01-20.log"),
+  "log entry from Jan 20\n",
 );
-
-// Symlink pointing outside workspace — should be skipped
-const outsideFile = join(testDir, "outside-secret.txt");
-writeFileSync(outsideFile, "sensitive data outside workspace");
-try {
-  symlinkSync(outsideFile, join(testWorkspaceDir, "sneaky-link.txt"));
-} catch {
-  // Symlink creation may fail on some platforms; tests will still pass
-}
+writeFileSync(
+  join(logsDir, "assistant-2025-01-25.log"),
+  "log entry from Jan 25\n",
+);
+// Non-dated log file — should always be included regardless of time filter
+writeFileSync(join(logsDir, "vellum.log"), "non-dated log content\n");
 
 // ---------------------------------------------------------------------------
 // Tests
@@ -189,90 +147,95 @@ describe("POST /v1/export — tar.gz archive", () => {
     }
   });
 
-  test("archive contains workspace text files", async () => {
+  test("archive contains config-snapshot.json when config exists", async () => {
     const res = await callExport();
     const dir = await extractArchive(res);
     try {
-      const identity = readFileSync(
-        join(dir, "workspace", "IDENTITY.md"),
-        "utf-8",
-      );
-      expect(identity).toBe("# My Identity\nHello");
-
-      const daily = readFileSync(
-        join(dir, "workspace", "notes", "daily.txt"),
+      const configContent = readFileSync(
+        join(dir, "config-snapshot.json"),
         "utf-8",
       );
-      expect(daily).toBe("Some daily notes");
+      const parsed = JSON.parse(configContent);
+      expect(parsed.provider).toBe("anthropic");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+});
 
-  test("archive contains SQLite DB dumps as .sql files", async () => {
-    const res = await callExport();
+describe("POST /v1/export — daemon log date filtering", () => {
+  test("excludes log files before startTime", async () => {
+    // startTime = Jan 14 — should exclude assistant-2025-01-10.log
+    const startTime = new Date("2025-01-14T00:00:00.000Z").getTime();
+    const res = await callExport({ startTime });
     const dir = await extractArchive(res);
     try {
-      const sqlContent = readFileSync(
-        join(dir, "workspace", "data", "db", "assistant.db.sql"),
-        "utf-8",
-      );
-      expect(sqlContent).toContain("CREATE TABLE");
-      expect(sqlContent).toContain("test_table");
+      const logFiles = readdirSync(join(dir, "daemon-logs"));
+      expect(logFiles).not.toContain("assistant-2025-01-10.log");
+      expect(logFiles).toContain("assistant-2025-01-15.log");
+      expect(logFiles).toContain("assistant-2025-01-20.log");
+      expect(logFiles).toContain("assistant-2025-01-25.log");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  test("archive excludes embedding-models/ and data/qdrant/", async () => {
-    const res = await callExport();
+  test("excludes log files after endTime", async () => {
+    // endTime = Jan 22 — should exclude assistant-2025-01-25.log
+    const endTime = new Date("2025-01-22T00:00:00.000Z").getTime();
+    const res = await callExport({ endTime });
     const dir = await extractArchive(res);
     try {
-      const files = listFiles(join(dir, "workspace"));
-      const embeddingFiles = files.filter((f) =>
-        f.startsWith("embedding-models/"),
-      );
-      const qdrantFiles = files.filter((f) => f.startsWith("data/qdrant/"));
-      expect(embeddingFiles).toHaveLength(0);
-      expect(qdrantFiles).toHaveLength(0);
+      const logFiles = readdirSync(join(dir, "daemon-logs"));
+      expect(logFiles).toContain("assistant-2025-01-10.log");
+      expect(logFiles).toContain("assistant-2025-01-15.log");
+      expect(logFiles).toContain("assistant-2025-01-20.log");
+      expect(logFiles).not.toContain("assistant-2025-01-25.log");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  test("archive excludes binary files and config.json at workspace root", async () => {
-    const res = await callExport();
+  test("filters log files by both startTime and endTime", async () => {
+    // startTime = Jan 14, endTime = Jan 22 — should only include Jan 15 and Jan 20
+    const startTime = new Date("2025-01-14T00:00:00.000Z").getTime();
+    const endTime = new Date("2025-01-22T00:00:00.000Z").getTime();
+    const res = await callExport({ startTime, endTime });
     const dir = await extractArchive(res);
     try {
-      const files = listFiles(join(dir, "workspace"));
-      expect(files).not.toContain("binary-file.dat");
-      expect(files).not.toContain("config.json");
+      const logFiles = readdirSync(join(dir, "daemon-logs"));
+      expect(logFiles).not.toContain("assistant-2025-01-10.log");
+      expect(logFiles).toContain("assistant-2025-01-15.log");
+      expect(logFiles).toContain("assistant-2025-01-20.log");
+      expect(logFiles).not.toContain("assistant-2025-01-25.log");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  test("archive excludes symlinks", async () => {
-    const res = await callExport();
+  test("always includes non-dated log files regardless of time filter", async () => {
+    const startTime = new Date("2025-01-14T00:00:00.000Z").getTime();
+    const endTime = new Date("2025-01-22T00:00:00.000Z").getTime();
+    const res = await callExport({ startTime, endTime });
     const dir = await extractArchive(res);
     try {
-      const files = listFiles(join(dir, "workspace"));
-      expect(files).not.toContain("sneaky-link.txt");
+      const logFiles = readdirSync(join(dir, "daemon-logs"));
+      expect(logFiles).toContain("vellum.log");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  test("archive contains config-snapshot.json when config exists", async () => {
+  test("includes all log files when no time filter is specified", async () => {
     const res = await callExport();
     const dir = await extractArchive(res);
     try {
-      const configContent = readFileSync(
-        join(dir, "config-snapshot.json"),
-        "utf-8",
-      );
-      const parsed = JSON.parse(configContent);
-      expect(parsed.provider).toBe("anthropic");
+      const logFiles = readdirSync(join(dir, "daemon-logs"));
+      expect(logFiles).toContain("assistant-2025-01-10.log");
+      expect(logFiles).toContain("assistant-2025-01-15.log");
+      expect(logFiles).toContain("assistant-2025-01-20.log");
+      expect(logFiles).toContain("assistant-2025-01-25.log");
+      expect(logFiles).toContain("vellum.log");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

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

@@ -496,9 +496,9 @@ describe("atomic write safety", () => {
     });
 
     const skillDir = join(TEST_DIR, "skills", "atomic-overwrite");
-    const files = readdirSync(skillDir);
-    // Only SKILL.md should exist — no .tmp-* leftover files
-    expect(files).toEqual(["SKILL.md"]);
+    const files = readdirSync(skillDir).sort();
+    // SKILL.md and install-meta.json should exist — no .tmp-* leftover files
+    expect(files).toEqual(["SKILL.md", "install-meta.json"]);
 
     const content = readFileSync(join(skillDir, "SKILL.md"), "utf-8");
     expect(content).toContain('name: "V2"');
@@ -649,7 +649,7 @@ describe("version metadata", () => {
     expect(readSkillVersion("no-version")).toBeNull();
   });
 
-  test("createManagedSkill writes version.json when version is provided", () => {
+  test("createManagedSkill writes install-meta.json when version is provided", () => {
     createManagedSkill({
       id: "versioned",
       name: "Versioned",
@@ -662,7 +662,7 @@ describe("version metadata", () => {
     expect(version).toBe("v1:abc123");
   });
 
-  test("version.json contains valid JSON with version and installedAt", () => {
+  test("install-meta.json contains valid JSON with origin, version, and installedAt", () => {
     createManagedSkill({
       id: "version-meta",
       name: "Meta",
@@ -671,16 +671,43 @@ describe("version metadata", () => {
       version: "v1:deadbeef",
     });
 
-    const metaPath = join(TEST_DIR, "skills", "version-meta", "version.json");
+    const metaPath = join(
+      TEST_DIR,
+      "skills",
+      "version-meta",
+      "install-meta.json",
+    );
     expect(existsSync(metaPath)).toBe(true);
     const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    expect(meta.origin).toBe("custom");
     expect(meta.version).toBe("v1:deadbeef");
     expect(typeof meta.installedAt).toBe("string");
     // installedAt should be a valid ISO date
     expect(new Date(meta.installedAt).toISOString()).toBe(meta.installedAt);
   });
 
-  test("overwrite updates version.json", () => {
+  test("install-meta.json includes installedBy when contactId is provided", () => {
+    createManagedSkill({
+      id: "with-contact",
+      name: "With Contact",
+      description: "Has contactId",
+      bodyMarkdown: "Body.",
+      contactId: "contact-uuid-456",
+    });
+
+    const metaPath = join(
+      TEST_DIR,
+      "skills",
+      "with-contact",
+      "install-meta.json",
+    );
+    expect(existsSync(metaPath)).toBe(true);
+    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    expect(meta.origin).toBe("custom");
+    expect(meta.installedBy).toBe("contact-uuid-456");
+  });
+
+  test("overwrite updates install-meta.json", () => {
     createManagedSkill({
       id: "update-version",
       name: "V1",
@@ -701,21 +728,21 @@ describe("version metadata", () => {
     expect(readSkillVersion("update-version")).toBe("v1:second");
   });
 
-  test("readSkillVersion returns null for corrupted version.json", () => {
+  test("readSkillVersion returns null for corrupted install-meta.json", () => {
     createManagedSkill({
       id: "corrupt-version",
       name: "Corrupt",
-      description: "Will corrupt version file",
+      description: "Will corrupt meta file",
       bodyMarkdown: "Body.",
       version: "v1:valid",
     });
 
-    // Corrupt the version.json
+    // Corrupt the install-meta.json
     const metaPath = join(
       TEST_DIR,
       "skills",
       "corrupt-version",
-      "version.json",
+      "install-meta.json",
     );
     writeFileSync(metaPath, "{invalid json!!!", "utf-8");
 

package/src/__tests__/mcp-abort-signal.test.ts

@@ -7,6 +7,11 @@ mock.module("../security/secure-keys.js", () => ({
   deleteSecureKeyAsync: jest.fn().mockResolvedValue("deleted"),
 }));
 
+// Mock platform-callback-registration (imported by client.ts)
+mock.module("../inbound/platform-callback-registration.js", () => ({
+  shouldUsePlatformCallbacks: jest.fn().mockReturnValue(false),
+}));
+
 const { McpClient } = await import("../mcp/client.js");
 const { McpServerManager } = await import("../mcp/manager.js");
 const { createMcpTool } = await import("../tools/mcp/mcp-tool-factory.js");

package/src/__tests__/mcp-client-auth.test.ts

@@ -7,6 +7,11 @@ mock.module("../security/secure-keys.js", () => ({
   deleteSecureKeyAsync: jest.fn().mockResolvedValue("deleted"),
 }));
 
+// Mock platform-callback-registration (imported by client.ts)
+mock.module("../inbound/platform-callback-registration.js", () => ({
+  shouldUsePlatformCallbacks: jest.fn().mockReturnValue(false),
+}));
+
 const { McpClient } = await import("../mcp/client.js");
 
 /**

package/src/__tests__/memory-jobs-worker-backoff.test.ts

@@ -34,15 +34,9 @@ mock.module("../memory/jobs-store.js", () => ({
   deferMemoryJob: () => "deferred",
   failMemoryJob: () => {},
   failStalledJobs: () => 0,
-  enqueueCleanupStaleSupersededItemsJob: () => null,
   enqueuePruneOldConversationsJob: () => null,
 }));
 
-// Mock db.js (rawRun used in sweepStaleItems)
-mock.module("../memory/db.js", () => ({
-  rawRun: () => 0,
-}));
-
 import {
   POLL_INTERVAL_MAX_MS,
   POLL_INTERVAL_MIN_MS,
@@ -90,7 +84,7 @@ describe("memory jobs worker adaptive poll interval", () => {
         timeoutDelays.push(delay);
         pendingCallbacks.push(fn);
       }
-      return 999 as unknown as ReturnType<typeof setTimeout>;
+      return (999 as unknown) as ReturnType<typeof setTimeout>;
     }) as typeof setTimeout;
     globalThis.clearTimeout = (() => {}) as typeof clearTimeout;
 
@@ -129,7 +123,7 @@ describe("memory jobs worker adaptive poll interval", () => {
 
       // Should eventually reach the cap
       expect(timeoutDelays[timeoutDelays.length - 1]).toBe(
-        POLL_INTERVAL_MAX_MS,
+        POLL_INTERVAL_MAX_MS
       );
     } finally {
       globalThis.setTimeout = originalSetTimeout;

package/src/__tests__/memory-recall-log-store.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 mock.module("../util/logger.js", () => ({
   getLogger: () =>
@@ -18,10 +18,11 @@ mock.module("../config/loader.js", () => ({
   }),
 }));
 
-import { getDb, initializeDb, resetDb } from "../memory/db.js";
+import { getDb, initializeDb } from "../memory/db.js";
 import {
   backfillMemoryRecallLogMessageId,
   getMemoryRecallLogByMessageIds,
+  normalizeTopCandidates,
   recordMemoryRecallLog,
 } from "../memory/memory-recall-log-store.js";
 import { memoryRecallLogs } from "../memory/schema.js";
@@ -33,10 +34,6 @@ function resetTables(): void {
   db.delete(memoryRecallLogs).run();
 }
 
-afterAll(() => {
-  resetDb();
-});
-
 describe("memory-recall-log-store", () => {
   beforeEach(() => {
     resetTables();
@@ -65,6 +62,7 @@ describe("memory-recall-log-store", () => {
       topCandidatesJson: [{ id: "c1", score: 0.9 }],
       injectedText: "some memory context",
       reason: "user query matched memories",
+      queryContext: "what is the weather like",
     });
 
     backfillMemoryRecallLogMessageId(conversationId, messageId);
@@ -88,6 +86,34 @@ describe("memory-recall-log-store", () => {
     expect(result!.topCandidates).toEqual([{ id: "c1", score: 0.9 }]);
     expect(result!.injectedText).toBe("some memory context");
     expect(result!.reason).toBe("user query matched memories");
+    expect(result!.queryContext).toBe("what is the weather like");
+  });
+
+  test("queryContext defaults to null when omitted", () => {
+    const conversationId = "conv-no-query-ctx";
+    const messageId = "msg-no-query-ctx";
+
+    recordMemoryRecallLog({
+      conversationId,
+      enabled: true,
+      degraded: false,
+      semanticHits: 1,
+      mergedCount: 1,
+      selectedCount: 1,
+      tier1Count: 1,
+      tier2Count: 0,
+      hybridSearchLatencyMs: 50,
+      sparseVectorUsed: false,
+      injectedTokens: 100,
+      latencyMs: 80,
+      topCandidatesJson: [],
+    });
+
+    backfillMemoryRecallLogMessageId(conversationId, messageId);
+
+    const result = getMemoryRecallLogByMessageIds([messageId]);
+    expect(result).not.toBeNull();
+    expect(result!.queryContext).toBeNull();
   });
 
   test("returns null when no log exists for a messageId", () => {
@@ -152,4 +178,106 @@ describe("memory-recall-log-store", () => {
     expect(secondLog).not.toBeNull();
     expect(secondLog!.degraded).toBe(true);
   });
+
+  test("normalizes SSE-event format candidates to inspector format on read", () => {
+    const conversationId = "conv-normalize-sse";
+    const messageId = "msg-normalize-sse";
+
+    // Store candidates in SSE-event format (key/finalScore/semantic/recency/kind)
+    recordMemoryRecallLog({
+      conversationId,
+      enabled: true,
+      degraded: false,
+      semanticHits: 2,
+      mergedCount: 1,
+      selectedCount: 1,
+      tier1Count: 1,
+      tier2Count: 0,
+      hybridSearchLatencyMs: 100,
+      sparseVectorUsed: false,
+      injectedTokens: 200,
+      latencyMs: 120,
+      topCandidatesJson: [
+        {
+          key: "node-abc",
+          finalScore: 0.85,
+          semantic: 0.9,
+          recency: 0.1,
+          kind: "episode",
+          type: "episodic",
+        },
+      ],
+    });
+
+    backfillMemoryRecallLogMessageId(conversationId, messageId);
+
+    const result = getMemoryRecallLogByMessageIds([messageId]);
+    expect(result).not.toBeNull();
+    const candidates = result!.topCandidates as Array<Record<string, unknown>>;
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0]).toEqual({
+      nodeId: "node-abc",
+      score: 0.85,
+      semanticSimilarity: 0.9,
+      recencyBoost: 0.1,
+      type: "episodic",
+    });
+    // kind should be stripped
+    expect(candidates[0]).not.toHaveProperty("kind");
+    // Old field names should not be present
+    expect(candidates[0]).not.toHaveProperty("key");
+    expect(candidates[0]).not.toHaveProperty("finalScore");
+    expect(candidates[0]).not.toHaveProperty("semantic");
+    expect(candidates[0]).not.toHaveProperty("recency");
+  });
+
+  test("passes through candidates already in inspector format unchanged", () => {
+    const conversationId = "conv-normalize-inspector";
+    const messageId = "msg-normalize-inspector";
+
+    // Store candidates already in inspector format (nodeId/score/semanticSimilarity/recencyBoost)
+    recordMemoryRecallLog({
+      conversationId,
+      enabled: true,
+      degraded: false,
+      semanticHits: 1,
+      mergedCount: 1,
+      selectedCount: 1,
+      tier1Count: 1,
+      tier2Count: 0,
+      hybridSearchLatencyMs: 80,
+      sparseVectorUsed: false,
+      injectedTokens: 100,
+      latencyMs: 90,
+      topCandidatesJson: [
+        {
+          nodeId: "node-xyz",
+          score: 0.92,
+          semanticSimilarity: 0.88,
+          recencyBoost: 0.05,
+          type: "semantic",
+        },
+      ],
+    });
+
+    backfillMemoryRecallLogMessageId(conversationId, messageId);
+
+    const result = getMemoryRecallLogByMessageIds([messageId]);
+    expect(result).not.toBeNull();
+    const candidates = result!.topCandidates as Array<Record<string, unknown>>;
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0]).toEqual({
+      nodeId: "node-xyz",
+      score: 0.92,
+      semanticSimilarity: 0.88,
+      recencyBoost: 0.05,
+      type: "semantic",
+    });
+  });
+
+  test("normalizeTopCandidates handles non-array input", () => {
+    expect(normalizeTopCandidates(null)).toBeNull();
+    expect(normalizeTopCandidates("not-an-array")).toBe("not-an-array");
+    expect(normalizeTopCandidates(42)).toBe(42);
+  });
 });