@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/persistence/llm-request-log-writer-types.ts

@@ -0,0 +1,80 @@
+/**
+ * Type-only contract for the pluggable LLM request log WRITE backend — the
+ * write-side counterpart to `llm-request-log-source-types.ts` (reads).
+ *
+ * One implementation per backend:
+ *  - `LocalLlmRequestLogWriter` (in `llm-request-log-store.ts`) — the SQLite
+ *    `llm_request_logs` table, with full post-hoc mutation support.
+ *  - `ClickHouseLlmRequestLogSink` (`llm-request-log-sink-clickhouse.ts`) —
+ *    INSERT-only; the post-hoc mutators are documented no-ops.
+ *
+ * The store's exported write functions resolve the active backend per call
+ * (`readSource` config) and dispatch through this interface, so EVERY writer
+ * of the table goes through the same resolution — a future third-party
+ * backend implements this interface and slots into the resolver without the
+ * store growing per-backend branching.
+ *
+ * Methods are synchronous from the caller's point of view: the local backend
+ * writes synchronously on the per-LLM-call critical path (deliberate — see
+ * the store's slow-sync-log instrumentation), and remote backends are
+ * fire-and-forget (errors logged, never thrown into the turn).
+ */
+
+/** A fully-formed `llm_request_logs` row to insert. */
+export interface LlmRequestLogWriteRow {
+  id: string;
+  conversationId: string;
+  messageId: string | null;
+  provider: string | null;
+  requestPayload: string;
+  responsePayload: string;
+  createdAt: number;
+  agentLoopExitReason: string | null;
+  callSite: string | null;
+  /**
+   * JSON first-token latency waterfall. Persisted by the local backend only —
+   * remote INSERT-only backends drop it (their table schema doesn't carry it,
+   * matching the read source, which treats remote rows as having no latency).
+   */
+  latencyBreakdown?: string | null;
+}
+
+export interface LlmRequestLogWriter {
+  /**
+   * Insert one request-log row. Local: synchronous SQLite insert. Remote:
+   * fire-and-forget — a backend outage must never abort the turn.
+   */
+  insertRequestLog(row: LlmRequestLogWriteRow): void;
+
+  /**
+   * Stamp an `agent_loop_exit_reason` onto the backend's most-recent
+   * unstamped row for the conversation. INSERT-only backends no-op: their
+   * rows can't be updated after the fact, and mutating the OTHER backend's
+   * rows would corrupt history (e.g. stamping this turn's reason onto a
+   * stale local row from an earlier local-mode turn).
+   */
+  setAgentLoopExitReasonOnLatestLog(
+    conversationId: string,
+    reason: string,
+  ): void;
+
+  /**
+   * Backfill `message_id` onto the conversation's rows that don't have one
+   * yet. INSERT-only backends no-op (same reasoning as the exit-reason
+   * stamp — the NULL-scoped predicate is a heuristic over this backend's
+   * own rows).
+   */
+  backfillMessageIdOnLogs(conversationId: string, messageId: string): void;
+
+  /**
+   * Re-link rows from a set of source message IDs to a target message
+   * (message consolidation). INSERT-only backends no-op.
+   */
+  relinkLlmRequestLogs(fromMessageIds: string[], toMessageId: string): void;
+
+  /**
+   * Backfill `message_id` onto specific recovered rows (by row id) found
+   * unlinked on the read path. INSERT-only backends no-op.
+   */
+  backfillMessageIdOnRecoveredLogs(logIds: string[], messageId: string): void;
+}

package/src/persistence/llm-usage-store.ts

@@ -1,6 +1,7 @@
 import { and, asc, desc, eq, gt, or, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import { getTelemetryMainDb } from "../telemetry/telemetry-main-db.js";
 import type {
   PricingResult,
   UsageEvent,
@@ -153,7 +154,9 @@ function rowToUsageEvent(row: {
  * data and shouldn't be blocked by a single corrupt row.
  */
 function parseRawUsage(value: string | null): Record<string, unknown> | null {
-  if (value === null) return null;
+  if (value === null) {
+    return null;
+  }
   try {
     const parsed = JSON.parse(value);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
@@ -211,7 +214,7 @@ export function queryUnreportedUsageEvents(
   afterId: string | undefined,
   limit: number,
 ): UnreportedUsageEvent[] {
-  const db = getDb();
+  const db = getTelemetryMainDb();
   // JOIN to `conversations` to attach `conversationType`. LEFT JOIN
   // because `llm_usage_events.conversationId` is nullable — calls that
   // aren't tied to a conversation (memory consolidation, etc.) still

package/src/persistence/message-content-file.ts

@@ -3,8 +3,16 @@
  *
  * A `messages.content` value is a union of two shapes:
  *   - Inline: a JSON-serialized `ContentBlock[]` (or a legacy plain string).
- *   - Ref:    `{ "ref": "<workspace-relative path>" }` pointing at a JSONL
- *             delta file that folds to a `ContentBlock[]`.
+ *   - Ref:    `{ "ref": "conversations/<dir>/inflight/<uuid>.jsonl" }`
+ *             pointing at a JSONL delta file that folds to a
+ *             `ContentBlock[]`.
+ *
+ * The ref path is workspace-relative and MUST live under the reserved
+ * `conversations/` prefix with a `.jsonl` extension — the schema rejects
+ * anything else. This is the migration-safe discriminator against legacy
+ * plain-string rows: a legacy message whose entire text happens to parse as
+ * `{ "ref": … }` is only misread if it also names a reserved content path,
+ * which no organic legacy text does.
  *
  * The delta file is append-only. Each line is `{ i, seq, block }` where `i`
  * is the block index in the final array and `seq` is a monotonically
@@ -13,56 +21,75 @@
  * crash-truncated file still folds to the newest complete snapshot of each
  * block.
  *
- * All content reads must go through {@link resolveStoredMessageContent}
- * (wired into the message row mapper) — downstream consumers never see a
- * raw `{ ref }` value.
+ * {@link resolveMessageContentBlocks} is the single resolution seam:
+ * consumers take the raw stored string off the message row and resolve it
+ * to typed blocks here — a raw `{ ref }` value is never interpreted
+ * anywhere else.
  */
 
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 
+import { z } from "zod";
+
+import { contentBlockSchema } from "../providers/content-block-schema.js";
 import type { ContentBlock } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 
 const log = getLogger("message-content-file");
 
-/** Ref-shaped `messages.content` value pointing at a delta file. */
-export interface MessageContentRef {
-  /** Path of the JSONL delta file, relative to the workspace directory. */
-  ref: string;
-}
+/**
+ * Ref-shaped `messages.content` value. The reserved-path constraint is the
+ * discriminator that keeps legacy plain-string rows that parse as arbitrary
+ * JSON objects from being mistaken for a ref.
+ */
+export const messageContentRefSchema = z.object({
+  ref: z
+    .string()
+    .regex(
+      /^conversations\/.+\.jsonl$/,
+      "content refs must be workspace-relative paths under conversations/ ending in .jsonl",
+    ),
+});
+
+export type MessageContentRef = z.infer<typeof messageContentRefSchema>;
 
 /** One line of the append-only content delta file. */
-export interface ContentDeltaLine {
+const contentDeltaLineSchema = z.object({
   /** Index of `block` in the folded `ContentBlock[]`. */
-  i: number;
+  i: z.number(),
   /** Monotonic write sequence; the highest `seq` per `i` wins the fold. */
-  seq: number;
-  block: ContentBlock;
-}
+  seq: z.number(),
+  block: contentBlockSchema,
+});
+
+export type ContentDeltaLine = z.infer<typeof contentDeltaLineSchema>;
 
 /**
- * Narrow a parsed `messages.content` value to the ref shape. Strict on
- * purpose (exactly one key) so a legacy plain-string message that happens
- * to parse as an object can never be mistaken for a ref.
+ * Parse a raw `messages.content` string to a ref, or null when the value is
+ * inline content. The charCode fast path keeps the overwhelmingly common
+ * inline-array case to a single character check.
  */
-export function isMessageContentRef(
-  value: unknown,
-): value is MessageContentRef {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    Object.keys(value).length === 1 &&
-    typeof (value as { ref?: unknown }).ref === "string" &&
-    (value as { ref: string }).ref.length > 0
-  );
+export function parseContentRef(raw: string): MessageContentRef | null {
+  if (raw.charCodeAt(0) !== 0x7b /* '{' */) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = messageContentRefSchema.safeParse(parsed);
+  return result.success ? result.data : null;
 }
 
 /**
  * Resolve a workspace-relative content ref to an absolute path, rejecting
- * anything that escapes the workspace directory. Returns null on escape.
+ * anything that escapes the workspace directory (e.g. a ref containing
+ * `..` segments that still matched the reserved-prefix schema). Returns
+ * null on escape.
  */
 export function resolveContentRefPath(ref: string): string | null {
   const workspaceDir = resolve(getWorkspaceDir());
@@ -106,18 +133,11 @@ export function foldContentDeltas(text: string): ContentBlock[] {
     } catch {
       continue;
     }
-    if (typeof parsed !== "object" || parsed === null) {
-      continue;
-    }
-    const { i, seq, block } = parsed as Partial<ContentDeltaLine>;
-    if (
-      typeof i !== "number" ||
-      typeof seq !== "number" ||
-      typeof block !== "object" ||
-      block === null
-    ) {
+    const result = contentDeltaLineSchema.safeParse(parsed);
+    if (!result.success) {
       continue;
     }
+    const { i, seq, block } = result.data;
     const existing = byIndex.get(i);
     if (!existing || seq > existing.seq) {
       byIndex.set(i, { seq, block });
@@ -142,49 +162,140 @@ export function foldContentFile(absPath: string): ContentBlock[] | null {
   return foldContentDeltas(text);
 }
 
+/** Fold a validated ref to blocks; empty content on missing/escaping refs. */
+function resolveRefToBlocks(ref: MessageContentRef): ContentBlock[] {
+  const absPath = resolveContentRefPath(ref.ref);
+  if (!absPath) {
+    log.warn(
+      { ref: ref.ref },
+      "Content ref escapes the workspace directory; resolving as empty",
+    );
+    return [];
+  }
+  const blocks = foldContentFile(absPath);
+  if (blocks === null) {
+    // Normal for a row born in-flight that has not partial-flushed yet
+    // (fast replies inside the debounce window) — the file only exists
+    // once the first flush appends to it.
+    log.debug(
+      { ref: ref.ref },
+      "Content ref file missing or unreadable; resolving as empty",
+    );
+    return [];
+  }
+  return blocks;
+}
+
+/** Serialize an arbitrary value for embedding in a repaired text block. */
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Repair a historical block that fails the current schema. Field-level
+ * repair for the variants whose string fields consumers touch directly
+ * (text, tool_result, web_search_tool_result); any other block that at
+ * least carries a string `type` passes through untouched — persisted
+ * kinds outside the provider union (e.g. `ui_surface`) are live data
+ * whose renderers own their shape. Only type-less values are wrapped in
+ * a text block carrying their serialized payload.
+ */
+function coerceLegacyBlock(block: unknown): ContentBlock {
+  if (typeof block === "object" && block !== null) {
+    const rec = block as Record<string, unknown>;
+    if (rec.type === "text") {
+      return {
+        type: "text",
+        text: typeof rec.text === "string" ? rec.text : safeJson(rec.text),
+      };
+    }
+    if (rec.type === "tool_result" || rec.type === "web_search_tool_result") {
+      const toolUseId =
+        typeof rec.tool_use_id === "string" ? rec.tool_use_id : "";
+      if (rec.type === "web_search_tool_result") {
+        // content is opaque (provider-specific) — only the id needs repair.
+        return {
+          type: "web_search_tool_result",
+          tool_use_id: toolUseId,
+          content: rec.content,
+        };
+      }
+      return {
+        type: "tool_result",
+        tool_use_id: toolUseId,
+        content:
+          typeof rec.content === "string" ? rec.content : safeJson(rec.content),
+        ...(typeof rec.is_error === "boolean"
+          ? { is_error: rec.is_error }
+          : {}),
+      };
+    }
+    if (typeof rec.type === "string") {
+      return block as ContentBlock;
+    }
+  }
+  return { type: "text", text: safeJson(block) };
+}
+
 /**
- * Resolve a stored `messages.content` value to its inline JSON form.
+ * Resolve a stored `messages.content` value to a `ContentBlock[]`.
+ *
+ * This is the expressive form of the resolver:
+ *   - Inline `ContentBlock[]` JSON parses to its blocks.
+ *   - A `{ ref }` folds its delta file (empty on missing/escaping refs).
+ *   - A JSON string unwraps to its parsed value as a single text block
+ *     (parity with the legacy readers); any other legacy plain string or
+ *     non-array JSON becomes a text block carrying the raw value.
  *
- * Inline values (JSON `ContentBlock[]` or legacy plain strings) pass
- * through untouched — the common case costs one character check. Ref
- * values are resolved by folding the delta file and returning the folded
- * blocks as a JSON string, so every consumer downstream of the row mapper
- * sees the same shape it always has.
+ * Every returned block is guaranteed to satisfy the ContentBlock schema —
+ * historical rows with malformed or retired block shapes are repaired
+ * per-block ({@link coerceLegacyBlock}) rather than passed through, so
+ * consumers can use variant fields without runtime shape guards.
  *
- * Never throws. A missing/unreadable file or an escaping ref resolves to
- * `"[]"` (empty content) with a warning — content reads must not take
- * down read paths.
+ * Never throws — content reads must not take down read paths.
  */
-export function resolveStoredMessageContent(raw: string): string {
-  // Inline arrays start with '[', legacy plain strings rarely start with
-  // '{' — and when one does, the parse/shape checks below reject it.
-  if (typeof raw !== "string" || raw.charCodeAt(0) !== 0x7b /* '{' */) {
-    return raw;
+export function resolveMessageContentBlocks(raw: unknown): ContentBlock[] {
+  if (typeof raw !== "string") {
+    log.warn(
+      { rawType: typeof raw },
+      "Non-string stored message content; resolving as empty",
+    );
+    return [];
+  }
+  const ref = parseContentRef(raw);
+  if (ref) {
+    return resolveRefToBlocks(ref);
   }
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    return raw;
-  }
-  if (!isMessageContentRef(parsed)) {
-    return raw;
+    // legacy plain string
+    return [{ type: "text", text: raw }];
   }
-  const absPath = resolveContentRefPath(parsed.ref);
-  if (!absPath) {
-    log.warn(
-      { ref: parsed.ref },
-      "Content ref escapes the workspace directory; resolving as empty",
-    );
-    return "[]";
+  if (typeof parsed === "string") {
+    return [{ type: "text", text: parsed }];
   }
-  const blocks = foldContentFile(absPath);
-  if (blocks === null) {
+  if (Array.isArray(parsed)) {
+    const result = z.array(contentBlockSchema).safeParse(parsed);
+    if (result.success) {
+      return result.data;
+    }
+    // Historical rows may carry malformed or retired block shapes. Repair
+    // per block — valid blocks stay untouched — so the returned array
+    // always satisfies the schema. Only the rare invalid row pays this.
     log.warn(
-      { ref: parsed.ref },
-      "Content ref file missing or unreadable; resolving as empty",
+      { issueCount: result.error.issues.length },
+      "Inline content array has invalid block shapes; repairing per block",
     );
-    return "[]";
+    return parsed.map((block) => {
+      const one = contentBlockSchema.safeParse(block);
+      return one.success ? one.data : coerceLegacyBlock(block);
+    });
   }
-  return JSON.stringify(blocks);
+  return [{ type: "text", text: raw }];
 }

package/src/persistence/message-content.ts

@@ -1,14 +1,16 @@
 import type { ContentBlock } from "../providers/types.js";
 import { escapeXmlAttr } from "../util/xml.js";
 
-export function extractTextFromStoredMessageContent(raw: string): string {
+export function extractTextFromStoredMessageContent(
+  raw: string | ContentBlock[],
+): string {
   try {
-    const parsed = JSON.parse(raw) as unknown;
+    const parsed = Array.isArray(raw) ? raw : (JSON.parse(raw) as unknown);
     if (typeof parsed === "string") {
       return parsed;
     }
     if (!Array.isArray(parsed)) {
-      return raw;
+      return raw as string;
     }
     const blocks = parsed as ContentBlock[];
     const lines: string[] = [];
@@ -66,7 +68,7 @@ export function extractTextFromStoredMessageContent(raw: string): string {
     }
     return lines.join("\n").trim();
   } catch {
-    return raw;
+    return Array.isArray(raw) ? "" : raw;
   }
 }
 
@@ -93,18 +95,24 @@ function stableJson(value: unknown): string {
  * Parse failures fall back to returning the raw input trimmed (the
  * legacy-string path).
  */
-export function stringifyMessageContent(stored: string): string {
+export function stringifyMessageContent(
+  stored: string | ContentBlock[],
+): string {
   let parsed: unknown;
-  try {
-    parsed = JSON.parse(stored);
-  } catch {
-    return stored.trim();
+  if (Array.isArray(stored)) {
+    parsed = stored;
+  } else {
+    try {
+      parsed = JSON.parse(stored);
+    } catch {
+      return stored.trim();
+    }
   }
   if (typeof parsed === "string") {
     return parsed.trim();
   }
   if (!Array.isArray(parsed)) {
-    return stored.trim();
+    return (stored as string).trim();
   }
   const parts: string[] = [];
   for (const block of parsed) {

package/src/persistence/migrations/305-drop-contact-acl-columns.ts

@@ -9,8 +9,9 @@ const log = getLogger("migration-305");
  * Drops the redundant contact ACL columns now owned by the gateway DB.
  *
  * Combo 11 Phase B: the gateway DB is the source of truth for contact ACL,
- * making these assistant-DB columns redundant mirrors. Phase A already drained
- * every production read off them.
+ * making these assistant-DB columns redundant mirrors. Phase A drained the
+ * runtime reads; gateway data migrations m0006/m0008 still read them to seed a
+ * pre-cutover gateway, and checkpoint once they are gone.
  *
  * No DROP INDEX needed: the only contact_channels index
  * (idx_contact_channels_type_ext_chat on (type, external_chat_id)) covers none

package/src/persistence/migrations/325-create-config-setting-events.ts

@@ -0,0 +1,40 @@
+import { Database } from "bun:sqlite";
+
+import { getTelemetryDbPath } from "../../util/telemetry-db-path.js";
+import { type DrizzleDb, getTelemetrySqlite } from "../db-connection.js";
+
+/**
+ * Create the `config_setting_events` table on the dedicated telemetry database
+ * (`assistant-telemetry.db`), not the main DB. The migration runner passes the
+ * main DrizzleDb, but this table lives on the telemetry connection, so we open
+ * that connection and run DDL against it directly.
+ *
+ * Idempotent (`IF NOT EXISTS`). Writes are gated on `share_analytics`
+ * consent at the store level, so opted-out rows never exist and the
+ * reporter's standard 0 watermark default is safe. The index backs the
+ * telemetry reporter's compound `(created_at, id)` watermark cursor.
+ *
+ * The `mainDb` parameter is accepted to satisfy the migration-step signature but
+ * is not used — this migration operates exclusively on the telemetry DB.
+ */
+export function createConfigSettingEventsTable(_mainDb: DrizzleDb): void {
+  let raw: Database | null = getTelemetrySqlite();
+  if (!raw) {
+    // The dedicated connection failed to open (logged by openDedicatedDb).
+    // Fall back to opening the file directly so the migration still runs —
+    // the singleton will pick it up on a later access. This mirrors the
+    // fail-soft pattern of the other dedicated-DB migrations.
+    raw = new Database(getTelemetryDbPath());
+  }
+  raw.exec(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS config_setting_events (
+      id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL,
+      config_key TEXT NOT NULL,
+      config_value TEXT NOT NULL
+    )
+  `);
+  raw.exec(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_config_setting_events_created_at_id ON config_setting_events (created_at, id)`,
+  );
+}

package/src/persistence/migrations/326-move-injection-events-to-memory-db.ts

@@ -0,0 +1,104 @@
+import type { Database } from "bun:sqlite";
+
+import { getMemoryDbPath } from "../../util/memory-db-path.js";
+import {
+  type DrizzleDb,
+  getMemorySqlite,
+  getSqliteFrom,
+} from "../db-connection.js";
+import {
+  drainStagedTable,
+  type RelocationSpec,
+  stageTableForRelocation,
+} from "./helpers/relocation.js";
+
+/**
+ * Readers of `memory_v2_injection_events` bound their scans to the last
+ * 6 half-lives (6 × 3 days) — events past that window contribute <1.6% each
+ * to the decayed score and are never queried. Mirrors `READ_WINDOW_MS` in
+ * `plugins/defaults/memory/v2/injection-events.ts` (duplicated by design:
+ * persistence migrations do not import plugin code).
+ */
+const READ_WINDOW_MS = 6 * 3 * 24 * 60 * 60 * 1000;
+
+/**
+ * How to drain `memory_v2_injection_events` from `main` into the memory DB.
+ * Rows older than the score read window are purged without copying — no
+ * reader ever looks at them, so carrying them over would only re-seed dead
+ * weight in the new file.
+ */
+export const INJECTION_EVENTS_RELOCATION: RelocationSpec = {
+  table: "memory_v2_injection_events",
+  targetDbPath: getMemoryDbPath,
+  columns: ["id", "slug", "injected_at"],
+  copyWhere: `injected_at >= strftime('%s','now') * 1000 - ${READ_WINDOW_MS}`,
+};
+
+const CREATE_TABLE = /*sql*/ `
+  CREATE TABLE IF NOT EXISTS memory_v2_injection_events (
+    id INTEGER PRIMARY KEY,
+    slug TEXT NOT NULL,
+    injected_at INTEGER NOT NULL
+  )
+`;
+
+/**
+ * Create the `memory_v2_injection_events` table and its indexes on the memory
+ * connection. Idempotent (`IF NOT EXISTS`) — the dedicated connection itself
+ * performs no DDL on open, so this migration owns the schema. Exported so
+ * tests can stand up the memory-side schema without running the full drain.
+ */
+export function ensureInjectionEventsSchema(memoryRaw: Database): void {
+  memoryRaw.exec(CREATE_TABLE);
+  memoryRaw.exec(/*sql*/ `
+    CREATE INDEX IF NOT EXISTS idx_memory_v2_injection_events_slug_time
+      ON memory_v2_injection_events (slug, injected_at)
+  `);
+  memoryRaw.exec(/*sql*/ `
+    CREATE INDEX IF NOT EXISTS idx_memory_v2_injection_events_time
+      ON memory_v2_injection_events (injected_at)
+  `);
+}
+
+/**
+ * Move `memory_v2_injection_events` — the append-only EMA event log behind
+ * memory router tier-2 scoring — into the dedicated memory database
+ * (`assistant-memory.db`), alongside `memory_jobs` (migration 298). The log
+ * grows with every router selection; housing it with the other high-churn
+ * memory state keeps the main DB and its WAL out of that write path, and the
+ * accessors in `plugins/defaults/memory/v2/injection-events.ts` read/write it
+ * over the dedicated memory connection (see `getMemoryDb()`).
+ *
+ * Like migrations 297/298 the move is incremental: create the table (and
+ * indexes) on the memory connection, rename any populated
+ * `main.memory_v2_injection_events` aside to
+ * `memory_v2_injection_events__relocating`, then drain it in awaited batches
+ * (see `helpers/relocation.ts`) per {@link INJECTION_EVENTS_RELOCATION}. On a
+ * fresh install the main-side table created by migration 256 is empty, so
+ * staging just drops it.
+ *
+ * Throws (rather than returning) if the memory database cannot be opened, so
+ * the runner records the step as failed instead of applied and retries it on
+ * a later boot — never renaming the source aside without a target to write
+ * to. The throw is caught per-step by the runner, so startup is not aborted.
+ */
+export async function migrateMoveInjectionEventsToMemoryDb(
+  database: DrizzleDb,
+): Promise<void> {
+  const memoryRaw = getMemorySqlite();
+  if (!memoryRaw) {
+    throw new Error(
+      "memory database unavailable — deferring memory_v2_injection_events relocation",
+    );
+  }
+
+  ensureInjectionEventsSchema(memoryRaw);
+
+  const raw = getSqliteFrom(database);
+  const needsDrain = stageTableForRelocation(
+    raw,
+    INJECTION_EVENTS_RELOCATION.table,
+  );
+
+  if (needsDrain) await drainStagedTable(raw, INJECTION_EVENTS_RELOCATION);
+}