@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/memory/__tests__/conversation-queries.test.ts

@@ -155,7 +155,7 @@ describe("countConversations", () => {
     const priv = createConversation("private-1");
     setConversationType(priv.id, "private");
 
-    expect(countConversations(true)).toBe(2);
+    expect(countConversations("background")).toBe(2);
   });
 
   test("includes standard conversations with group_id system:background in background count", () => {
@@ -170,13 +170,13 @@ describe("countConversations", () => {
     createConversation("foreground-1");
 
     // WHEN counting background conversations
-    const bgCount = countConversations(true);
+    const bgCount = countConversations("background");
 
     // THEN the heartbeat conversation is included
     expect(bgCount).toBe(1);
 
     // AND excluded from the foreground count
-    expect(countConversations(false)).toBe(1);
+    expect(countConversations("standard")).toBe(1);
   });
 
   test("excludes standard conversations with group_id system:background from foreground count", () => {
@@ -191,7 +191,59 @@ describe("countConversations", () => {
 
     // WHEN counting foreground conversations
     // THEN the heartbeat is excluded
-    expect(countConversations(false)).toBe(2);
+    expect(countConversations("standard")).toBe(2);
+  });
+
+  test('"scheduled" count returns only scheduled rows', () => {
+    // GIVEN one scheduled, one background, and one foreground conversation
+    createConversation({ title: "sched-1", conversationType: "scheduled" });
+    createConversation({ title: "bg-1", conversationType: "background" });
+    createConversation("foreground-1");
+
+    // WHEN counting scheduled conversations
+    // THEN only the scheduled row is counted (background is excluded)
+    expect(countConversations("scheduled")).toBe(1);
+  });
+
+  describe("archiveStatus", () => {
+    test("defaults to active — archived rows are excluded from the count", () => {
+      // GIVEN one live and one archived foreground conversation
+      createConversation("live-1");
+      const archived = createConversation("archived-1");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id = ?",
+        Date.now(),
+        archived.id,
+      );
+
+      expect(countConversations()).toBe(1);
+    });
+
+    test('archiveStatus "archived" returns the archived count only', () => {
+      createConversation("live-1");
+      const a1 = createConversation("archived-1");
+      const a2 = createConversation("archived-2");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id IN (?, ?)",
+        Date.now(),
+        a1.id,
+        a2.id,
+      );
+
+      expect(countConversations("standard", "archived")).toBe(2);
+    });
+
+    test('archiveStatus "all" returns both', () => {
+      createConversation("live-1");
+      const archived = createConversation("archived-1");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id = ?",
+        Date.now(),
+        archived.id,
+      );
+
+      expect(countConversations("standard", "all")).toBe(2);
+    });
   });
 });
 
@@ -215,7 +267,7 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, true);
+    const bgList = listConversations(100, "background");
 
     // THEN both background and heartbeat conversations are returned
     expect(bgList).toHaveLength(2);
@@ -236,7 +288,7 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing foreground conversations
-    const fgList = listConversations(100, false);
+    const fgList = listConversations(100, "standard");
 
     // THEN only the foreground conversation is returned
     expect(fgList).toHaveLength(1);
@@ -252,16 +304,148 @@ describe("listConversations", () => {
     );
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, true);
+    const bgList = listConversations(100, "background");
 
     // THEN it appears in the background list
     expect(bgList).toHaveLength(1);
     expect(bgList[0]!.title).toBe("schedule-routed");
 
     // AND not in the foreground list
-    const fgList = listConversations(100, false);
+    const fgList = listConversations(100, "standard");
     expect(fgList).toHaveLength(0);
   });
+
+  test('"scheduled" fetch returns only scheduled rows and excludes plain background', () => {
+    // GIVEN a scheduled conversation, a background conversation, and a foreground one
+    createConversation({ title: "sched-1", conversationType: "scheduled" });
+    createConversation({ title: "bg-1", conversationType: "background" });
+    createConversation("foreground-1");
+
+    // WHEN listing scheduled conversations
+    const scheduledList = listConversations(100, "scheduled");
+
+    // THEN only the scheduled conversation is returned
+    expect(scheduledList).toHaveLength(1);
+    expect(scheduledList[0]!.title).toBe("sched-1");
+  });
+
+  test('"scheduled" fetch includes standard rows routed to group_id system:scheduled but not system:background', () => {
+    // GIVEN a standard conversation routed to system:scheduled
+    const scheduledRouted = createConversation("schedule-routed");
+    rawRun(
+      "UPDATE conversations SET group_id = 'system:scheduled' WHERE id = ?",
+      scheduledRouted.id,
+    );
+
+    // AND a standard conversation routed to system:background
+    const backgroundRouted = createConversation("background-routed");
+    rawRun(
+      "UPDATE conversations SET group_id = 'system:background' WHERE id = ?",
+      backgroundRouted.id,
+    );
+
+    // WHEN listing scheduled conversations
+    const scheduledList = listConversations(100, "scheduled");
+
+    // THEN only the system:scheduled row appears
+    expect(scheduledList).toHaveLength(1);
+    expect(scheduledList[0]!.title).toBe("schedule-routed");
+  });
+
+  test('"scheduled" fetch excludes subagent runs', () => {
+    // GIVEN a scheduled conversation produced by a subagent
+    createConversation({
+      title: "subagent-sched",
+      conversationType: "scheduled",
+      source: "subagent",
+    });
+
+    // WHEN listing scheduled conversations
+    const scheduledList = listConversations(100, "scheduled");
+
+    // THEN the subagent run is excluded
+    expect(scheduledList).toHaveLength(0);
+  });
+
+  describe("archiveStatus", () => {
+    test("defaults to active — archived rows are excluded", () => {
+      // GIVEN a live conversation and an archived one
+      createConversation("live-1");
+      const archived = createConversation("archived-1");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id = ?",
+        Date.now(),
+        archived.id,
+      );
+
+      // WHEN listing without an explicit archiveStatus
+      const rows = listConversations(100, "standard");
+
+      // THEN only the live conversation appears
+      expect(rows).toHaveLength(1);
+      expect(rows[0]!.title).toBe("live-1");
+    });
+
+    test('archiveStatus "archived" returns only archived rows', () => {
+      // GIVEN a live conversation and an archived one
+      createConversation("live-1");
+      const archived = createConversation("archived-1");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id = ?",
+        Date.now(),
+        archived.id,
+      );
+
+      // WHEN listing with archiveStatus "archived"
+      const rows = listConversations(100, "standard", 0, "archived");
+
+      // THEN only the archived conversation appears
+      expect(rows).toHaveLength(1);
+      expect(rows[0]!.title).toBe("archived-1");
+    });
+
+    test('archiveStatus "all" returns both active and archived rows', () => {
+      // GIVEN a live conversation and an archived one
+      createConversation("live-1");
+      const archived = createConversation("archived-1");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id = ?",
+        Date.now(),
+        archived.id,
+      );
+
+      // WHEN listing with archiveStatus "all"
+      const rows = listConversations(100, "standard", 0, "all");
+
+      // THEN both conversations appear
+      expect(rows).toHaveLength(2);
+      const titles = rows.map((c) => c.title);
+      expect(titles).toContain("live-1");
+      expect(titles).toContain("archived-1");
+    });
+
+    test('archiveStatus "archived" composes with background-only', () => {
+      // GIVEN an archived background conversation and an archived foreground one
+      const archivedBg = createConversation({
+        title: "archived-bg",
+        conversationType: "background",
+      });
+      const archivedFg = createConversation("archived-fg");
+      rawRun(
+        "UPDATE conversations SET archived_at = ? WHERE id IN (?, ?)",
+        Date.now(),
+        archivedBg.id,
+        archivedFg.id,
+      );
+
+      // WHEN listing archived background conversations
+      const rows = listConversations(100, "background", 0, "archived");
+
+      // THEN only the archived background row appears
+      expect(rows).toHaveLength(1);
+      expect(rows[0]!.title).toBe("archived-bg");
+    });
+  });
 });
 
 describe("listConversationsBySource", () => {

package/src/memory/__tests__/db-maintenance.test.ts

@@ -25,16 +25,37 @@ const { initializeDb } = await import("../db-init.js");
 const { deleteMemoryCheckpoint, getMemoryCheckpoint } =
   await import("../checkpoints.js");
 const { maybeRunDbMaintenance } = await import("../db-maintenance.js");
+const { getLastUserMessageTimestamp } = await import("../conversation-crud.js");
 const { getDbPath } = await import("../../util/platform.js");
 
 initializeDb();
 
 const MAINTENANCE_CHECKPOINT_KEY = "db_maintenance:last_run";
+const QUIET_PERIOD_MS = 3 * 60 * 60 * 1000;
 
 beforeEach(() => {
   deleteMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY);
+  const sqlite = getSqlite();
+  sqlite.exec("DELETE FROM messages");
+  sqlite.exec("DELETE FROM conversations");
 });
 
+/** Insert a message row directly, bypassing indexing/job side effects. */
+function insertMessage(role: "user" | "assistant", createdAt: number): void {
+  const sqlite = getSqlite();
+  const convId = `conv-${createdAt}-${role}`;
+  sqlite
+    .prepare(
+      "INSERT OR IGNORE INTO conversations (id, created_at, updated_at) VALUES (?, ?, ?)",
+    )
+    .run(convId, createdAt, createdAt);
+  sqlite
+    .prepare(
+      "INSERT INTO messages (id, conversation_id, role, content, created_at) VALUES (?, ?, ?, ?, ?)",
+    )
+    .run(`msg-${createdAt}-${role}`, convId, role, "[]", createdAt);
+}
+
 /** Inflate the test DB with bloat that VACUUM can reclaim. */
 function inflateAndDelete(byteTarget: number): void {
   const sqlite = getSqlite();
@@ -112,4 +133,111 @@ describe("maybeRunDbMaintenance", () => {
     const pagesAfter = readPageCount();
     expect(pagesAfter).toBeLessThan(pagesBefore);
   }, 60_000);
+
+  test("defers maintenance while the last user message is within the quiet period", async () => {
+    /** VACUUM must not fire while the user is active, so a recent user
+     *  message keeps maintenance deferred. */
+    // GIVEN the user sent a message one minute ago (well within the quiet period)
+    const now = Date.now();
+    insertMessage("user", now - 60_000);
+
+    // WHEN maintenance is considered
+    await maybeRunDbMaintenance(now);
+
+    // THEN it is deferred — the checkpoint is never stamped, so a later idle
+    // tick will retry
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBeNull();
+  });
+
+  test("runs maintenance once the quiet period has elapsed since the last user message", async () => {
+    /** After the user has been quiet for longer than the quiet period,
+     *  maintenance is allowed to run. */
+    // GIVEN the last user message is older than the quiet period
+    const now = Date.now();
+    insertMessage("user", now - (QUIET_PERIOD_MS + 60_000));
+
+    // WHEN maintenance is considered
+    await maybeRunDbMaintenance(now);
+
+    // THEN it runs and stamps the checkpoint
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+
+  test("ignores quiet period when no user message exists", async () => {
+    /** A fresh install with no user messages must not be blocked from ever
+     *  running maintenance. */
+    // GIVEN no user messages exist
+    const now = Date.now();
+
+    // WHEN maintenance is considered
+    await maybeRunDbMaintenance(now);
+
+    // THEN it runs and stamps the checkpoint
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+
+  test("a recent assistant message does not keep maintenance deferred", async () => {
+    /** The gate keys off user activity only — background assistant writes
+     *  must not postpone maintenance indefinitely. */
+    // GIVEN the user has been quiet past the quiet period
+    const now = Date.now();
+    insertMessage("user", now - (QUIET_PERIOD_MS + 60_000));
+    // AND the assistant wrote a message recently
+    insertMessage("assistant", now - 60_000);
+
+    // WHEN maintenance is considered
+    await maybeRunDbMaintenance(now);
+
+    // THEN it still runs, since only user activity gates it
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+});
+
+describe("getLastUserMessageTimestamp", () => {
+  test("returns 0 when no user message exists", () => {
+    /** With only non-user rows present, there is no user activity to report. */
+    // GIVEN only an assistant message exists
+    insertMessage("assistant", Date.now());
+
+    // WHEN the last user message timestamp is read
+    const result = getLastUserMessageTimestamp();
+
+    // THEN it reports 0 (no user activity)
+    expect(result).toBe(0);
+  });
+
+  test("returns the most recent user message by timestamp, ignoring assistant rows", () => {
+    /** The lookup reports the newest user-message timestamp and must skip
+     *  non-user rows even when they are more recent. */
+    // GIVEN two user messages and a newer assistant message
+    const base = Date.now();
+    insertMessage("user", base - 10_000);
+    insertMessage("user", base - 5_000);
+    insertMessage("assistant", base);
+
+    // WHEN the last user message timestamp is read
+    const result = getLastUserMessageTimestamp();
+
+    // THEN it returns the most recent user message, not the assistant row
+    expect(result).toBe(base - 5_000);
+  });
+
+  test("reports the newest user timestamp even when an older turn was inserted later", () => {
+    /** `forkConversation` copies a parent's user turns into the fork with
+     *  their original (older) `created_at` but fresh row ids, so insertion
+     *  order can place an old turn last. The lookup must key off `created_at`
+     *  so a fork can't make recent activity look stale and prematurely
+     *  un-gate maintenance. */
+    // GIVEN a recent user message
+    const base = Date.now();
+    insertMessage("user", base - 5_000);
+    // AND a later insert of an older user turn (as a fork copy would produce)
+    insertMessage("user", base - 60 * 60 * 1000);
+
+    // WHEN the last user message timestamp is read
+    const result = getLastUserMessageTimestamp();
+
+    // THEN it reports the genuinely most recent turn, not the last-inserted one
+    expect(result).toBe(base - 5_000);
+  });
 });

package/src/memory/__tests__/jobs-store-job-classes.test.ts

@@ -40,11 +40,12 @@ describe("memory job classes", () => {
     expect(set.size).toBe(SLOW_LLM_JOB_TYPES.length);
   });
 
-  test("memory_v3_consolidate is a slow LLM job (lane isolation)", () => {
-    // It hands off to a background agent for up to 15 min, like
+  test("memory_v3_maintain is a slow LLM job (lane isolation)", () => {
+    // It runs an LLM classify-union pass over unassigned pages, like
     // memory_v2_consolidate; it must not sit in the fast lane and starve
-    // short jobs. The mechanical v3 jobs intentionally stay fast.
-    expect(SLOW_LLM_JOB_TYPES).toContain("memory_v3_consolidate");
+    // short jobs. The retired v3 job literals intentionally stay out.
+    expect(SLOW_LLM_JOB_TYPES).toContain("memory_v3_maintain");
+    expect(SLOW_LLM_JOB_TYPES).not.toContain("memory_v3_consolidate");
     expect(SLOW_LLM_JOB_TYPES).not.toContain("memory_v3_index_maintenance");
     expect(SLOW_LLM_JOB_TYPES).not.toContain("memory_v3_edge_learning");
   });

package/src/memory/__tests__/jobs-worker-v2-schedule.test.ts

@@ -72,6 +72,7 @@ const CONSOLIDATE_CHECKPOINT_KEY = "memory_v2_consolidate_last_run";
 
 function buildConfig(overrides: {
   v2Enabled?: boolean;
+  consolidationEnabled?: boolean;
   intervalHours?: number;
   maxBufferLines?: number | null;
 }) {
@@ -79,6 +80,13 @@ function buildConfig(overrides: {
   if (overrides.v2Enabled !== undefined) {
     partial.memory.v2.enabled = overrides.v2Enabled;
   }
+  if (overrides.consolidationEnabled !== undefined) {
+    (
+      partial.memory.v2 as typeof partial.memory.v2 & {
+        consolidation_enabled?: boolean;
+      }
+    ).consolidation_enabled = overrides.consolidationEnabled;
+  }
   if (overrides.intervalHours !== undefined) {
     partial.memory.v2.consolidation_interval_hours = overrides.intervalHours;
   }
@@ -110,6 +118,15 @@ function countPendingJobs(type: string): number {
     .all().length;
 }
 
+function consolidationJobPayloads(): Record<string, unknown>[] {
+  return getDb()
+    .select({ payload: memoryJobs.payload })
+    .from(memoryJobs)
+    .where(eq(memoryJobs.type, "memory_v2_consolidate"))
+    .all()
+    .map((row) => JSON.parse(row.payload) as Record<string, unknown>);
+}
+
 // Initialize the DB once for the file; clear per-test tables in beforeEach
 // rather than tearing down the singleton, which is slow because it re-runs
 // every migration on the next access.
@@ -138,6 +155,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
     maybeEnqueueGraphMaintenanceJobs(config, Date.now());
 
     expect(countPendingJobs("memory_v2_consolidate")).toBe(1);
+    expect(consolidationJobPayloads()).toEqual([{ trigger: "automatic" }]);
     // v1 entries are suppressed when v2 is active.
     expect(countPendingJobs("graph_decay")).toBe(0);
     expect(countPendingJobs("graph_consolidate")).toBe(0);
@@ -170,6 +188,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
     maybeEnqueueGraphMaintenanceJobs(config, now);
 
     expect(countPendingJobs("memory_v2_consolidate")).toBe(1);
+    expect(consolidationJobPayloads()).toEqual([{ trigger: "automatic" }]);
   });
 
   test("respects a custom consolidation_interval_hours value", () => {
@@ -231,6 +250,28 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
     expect(countPendingJobs("graph_narrative_refine")).toBe(1);
     expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
   });
+
+  test("automatic consolidation off suppresses the v2 schedule without re-enabling v1 maintenance", () => {
+    const config = buildConfig({
+      v2Enabled: true,
+      consolidationEnabled: false,
+      intervalHours: 1,
+    });
+
+    deleteMemoryCheckpoint("graph_maintenance:decay:last_run");
+    deleteMemoryCheckpoint("graph_maintenance:consolidate:last_run");
+    deleteMemoryCheckpoint("graph_maintenance:pattern_scan:last_run");
+    deleteMemoryCheckpoint("graph_maintenance:narrative:last_run");
+    deleteMemoryCheckpoint(CONSOLIDATE_CHECKPOINT_KEY);
+
+    maybeEnqueueGraphMaintenanceJobs(config, Date.now());
+
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
+    expect(countPendingJobs("graph_decay")).toBe(0);
+    expect(countPendingJobs("graph_consolidate")).toBe(0);
+    expect(countPendingJobs("graph_pattern_scan")).toBe(0);
+    expect(countPendingJobs("graph_narrative_refine")).toBe(0);
+  });
 });
 
 describe("maybeEnqueueGraphMaintenanceJobs — buffer-size trigger", () => {
@@ -369,4 +410,19 @@ describe("maybeEnqueueGraphMaintenanceJobs — buffer-size trigger", () => {
 
     expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
   });
+
+  test("size trigger inert when automatic consolidation is disabled", () => {
+    const config = buildConfig({
+      v2Enabled: true,
+      consolidationEnabled: false,
+      intervalHours: 1,
+      maxBufferLines: 1,
+    });
+
+    writeBuffer(100);
+
+    maybeEnqueueGraphMaintenanceJobs(config, Date.now());
+
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
+  });
 });

package/src/memory/__tests__/memory-retrospective-job.test.ts

@@ -57,7 +57,7 @@ let addMessageCalls: Array<{
   conversationId: string;
   role: string;
   content: string;
-  metadata: unknown;
+  options: unknown;
 }> = [];
 
 // Per-conversation overrides for getConversation. Lets fork-path tests stage
@@ -137,9 +137,9 @@ mock.module("../conversation-crud.js", () => ({
     conversationId: string,
     role: string,
     content: string,
-    metadata: unknown,
+    options: unknown,
   ) => {
-    addMessageCalls.push({ conversationId, role, content, metadata });
+    addMessageCalls.push({ conversationId, role, content, options });
   },
   deleteConversation: (id: string) => {
     deletedConversationIds.push(id);
@@ -316,10 +316,11 @@ describe("memoryRetrospectiveJob", () => {
     expect(bootstrapCalls[0]!.forkParentConversationId).toBe("src-conv-1");
   });
 
-  test("legacy path: wake opts include suppressWakeSurface so the full retrospective prompt isn't rendered as a 'Conversation Woke' card body to clients", async () => {
+  test("legacy path: wake is scoped to memory saves and suppresses the internal wake surface", async () => {
     await memoryRetrospectiveJob(makeJob(), stubConfig);
 
     expect(wakeCalls).toHaveLength(1);
+    expect(wakeCalls[0]!.opts.allowedTools).toEqual(["remember"]);
     expect(wakeCalls[0]!.opts.suppressWakeSurface).toBe(true);
   });
 
@@ -519,7 +520,9 @@ describe("memoryRetrospectiveJob", () => {
     expect(addMessageCalls).toHaveLength(1);
     expect(addMessageCalls[0]!.conversationId).toBe("fork-conv-1");
     expect(addMessageCalls[0]!.role).toBe("user");
-    expect(addMessageCalls[0]!.metadata).toEqual({
+    expect(
+      (addMessageCalls[0]!.options as Record<string, unknown>).metadata,
+    ).toEqual({
       kind: "memory_retrospective_instruction",
       hidden: true,
     });
@@ -535,7 +538,7 @@ describe("memoryRetrospectiveJob", () => {
     expect(forkCalls[0]!.groupId).toBe("system:background");
   });
 
-  test("fork path: wake opts include suppressWakeSurface so clients don't render an empty wake card on top of the '(Retrospective)' fork", async () => {
+  test("fork path: wake is scoped to memory saves and suppresses the internal wake surface", async () => {
     forkFlagEnabled = true;
     await memoryRetrospectiveJob(makeJob(), stubConfig);
 
@@ -543,6 +546,7 @@ describe("memoryRetrospectiveJob", () => {
     expect(wakeCalls).toHaveLength(1);
     expect(wakeCalls[0]!.conversationId).toBe("fork-conv-1");
     const opts = wakeCalls[0]!.opts;
+    expect(opts.allowedTools).toEqual(["remember"]);
     expect(opts.suppressWakeSurface).toBe(true);
     // Sanity: the other fork-specific opts the handler relies on are still set.
     expect(opts.skipHintInjection).toBe(true);

package/src/memory/__tests__/memory-v3-selections-migration.test.ts

@@ -0,0 +1,103 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { getSqliteFrom } from "../db-connection.js";
+import { migrateAddMemoryV3Selections } from "../migrations/268-add-memory-v3-selections.js";
+import * as schema from "../schema.js";
+
+interface ColumnRow {
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+
+interface IndexRow {
+  name: string;
+}
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  return drizzle(sqlite, { schema });
+}
+
+describe("memory_v3_selections migration", () => {
+  test("creates table with expected columns", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateAddMemoryV3Selections(db);
+
+    const columns = raw
+      .query(`PRAGMA table_info(memory_v3_selections)`)
+      .all() as ColumnRow[];
+    const byName = new Map(columns.map((c) => [c.name, c]));
+
+    expect(byName.get("conversation_id")?.type).toBe("TEXT");
+    expect(byName.get("conversation_id")?.notnull).toBe(1);
+    expect(byName.get("conversation_id")?.pk).toBe(1);
+
+    expect(byName.get("turn")?.type).toBe("INTEGER");
+    expect(byName.get("turn")?.notnull).toBe(1);
+    expect(byName.get("turn")?.pk).toBe(2);
+
+    expect(byName.get("slug")?.type).toBe("TEXT");
+    expect(byName.get("slug")?.notnull).toBe(1);
+    expect(byName.get("slug")?.pk).toBe(3);
+
+    expect(byName.get("source")?.type).toBe("TEXT");
+    expect(byName.get("source")?.notnull).toBe(1);
+
+    expect(byName.get("pinned")?.type).toBe("INTEGER");
+    expect(byName.get("pinned")?.notnull).toBe(1);
+    expect(byName.get("pinned")?.dflt_value).toBe("0");
+
+    expect(byName.get("created_at")?.type).toBe("INTEGER");
+    expect(byName.get("created_at")?.notnull).toBe(1);
+  });
+
+  test("creates the conversation-turn index", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateAddMemoryV3Selections(db);
+
+    const indexes = raw
+      .query(`PRAGMA index_list(memory_v3_selections)`)
+      .all() as IndexRow[];
+    const indexNames = new Set(indexes.map((i) => i.name));
+
+    expect(indexNames.has("idx_memory_v3_selections_conv")).toBe(true);
+  });
+
+  test("is idempotent — re-running does not throw and preserves rows", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateAddMemoryV3Selections(db);
+
+    raw
+      .query(
+        /*sql*/ `
+        INSERT INTO memory_v3_selections (
+          conversation_id, turn, slug, source, pinned, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `,
+      )
+      .run("conv-abc", 3, "page-slug", "lane-a", 1, 1000);
+
+    expect(() => migrateAddMemoryV3Selections(db)).not.toThrow();
+
+    const row = raw
+      .query(
+        `SELECT slug FROM memory_v3_selections WHERE conversation_id = 'conv-abc' AND turn = 3`,
+      )
+      .get() as { slug: string } | null;
+    expect(row?.slug).toBe("page-slug");
+  });
+});