@vellumai/assistant 0.8.0 → 0.8.2

package/src/memory/migrations/249-normalize-slack-external-content.ts

@@ -0,0 +1,240 @@
+import {
+  readSlackMetadata,
+  type SlackMessageMetadata,
+} from "../../messaging/providers/slack/message-metadata.js";
+import {
+  parseExternalContentEnvelope,
+  unwrapExternalContentForDisplay,
+} from "../../security/untrusted-content.js";
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_normalize_slack_external_content_v1";
+const BATCH_SIZE = 100;
+
+interface CandidateMessageRow {
+  rowid: number;
+  id: string;
+  role: string;
+  content: string;
+  metadata: string;
+}
+
+interface NormalizedMessageRow {
+  content: string;
+  metadata: string;
+}
+
+export function migrateNormalizeSlackExternalContent(
+  database: DrizzleDb,
+): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+
+    const tableExists = raw
+      .query(
+        `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'messages'`,
+      )
+      .get();
+    if (!tableExists) return;
+
+    let lastRowid = 0;
+
+    for (;;) {
+      const rows = raw
+        .query(
+          /*sql*/ `
+            SELECT rowid, id, role, content, metadata
+            FROM messages
+            WHERE rowid > ?
+              AND metadata LIKE '%"slackMeta"%'
+              AND (
+                content LIKE '%<external_content%'
+                OR metadata NOT LIKE '%"provenanceTrustClass"%'
+              )
+            ORDER BY rowid
+            LIMIT ?
+          `,
+        )
+        .all(lastRowid, BATCH_SIZE) as CandidateMessageRow[];
+
+      if (rows.length === 0) break;
+
+      for (const row of rows) {
+        lastRowid = row.rowid;
+        const normalized = normalizeSlackMessageRow(row);
+        if (!normalized) continue;
+
+        raw
+          .query(`UPDATE messages SET content = ?, metadata = ? WHERE id = ?`)
+          .run(normalized.content, normalized.metadata, row.id);
+      }
+    }
+  });
+}
+
+export function downNormalizeSlackExternalContent(_database: DrizzleDb): void {
+  // Irreversible by design: this migration discards redundant persisted
+  // wrappers and leaves runtime assembly responsible for model boundaries.
+}
+
+function normalizeSlackMessageRow(
+  row: CandidateMessageRow,
+): NormalizedMessageRow | null {
+  const parsed = parseSlackMetadataEnvelope(row.metadata);
+  if (!parsed) return null;
+
+  const normalizedContent = normalizeMessageContent(row.content);
+  if (normalizedContent !== null) {
+    const { metadata } = parsed;
+    if (
+      !Object.prototype.hasOwnProperty.call(metadata, "provenanceTrustClass")
+    ) {
+      metadata.provenanceTrustClass = "unknown";
+    }
+
+    return {
+      content: normalizedContent,
+      metadata: JSON.stringify(metadata),
+    };
+  }
+
+  if (isLegacyGuardianBackfillRow(row, parsed)) {
+    const { metadata } = parsed;
+    metadata.provenanceTrustClass = "guardian";
+    if (
+      !Object.prototype.hasOwnProperty.call(metadata, "provenanceSourceChannel")
+    ) {
+      metadata.provenanceSourceChannel = "slack";
+    }
+
+    return {
+      content: row.content,
+      metadata: JSON.stringify(metadata),
+    };
+  }
+
+  return null;
+}
+
+function parseSlackMetadataEnvelope(rawMetadata: string): {
+  metadata: Record<string, unknown>;
+  slackMeta: SlackMessageMetadata;
+} | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawMetadata);
+  } catch {
+    return null;
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const metadata = parsed as Record<string, unknown>;
+  if (typeof metadata.slackMeta !== "string") return null;
+  const slackMeta = readSlackMetadata(metadata.slackMeta);
+  if (!slackMeta) return null;
+  return { metadata, slackMeta };
+}
+
+function normalizeMessageContent(content: string): string | null {
+  const wholeEnvelope = parseExternalContentEnvelope(content);
+  if (wholeEnvelope) {
+    return wholeEnvelope.content;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(parsed)) {
+    return null;
+  }
+
+  let changed = false;
+  const normalizedBlocks = parsed.map((block) => {
+    if (block === null || typeof block !== "object" || Array.isArray(block)) {
+      return block;
+    }
+    const record = block as Record<string, unknown>;
+    if (record.type !== "text" || typeof record.text !== "string") {
+      return block;
+    }
+
+    const unwrapped = unwrapExternalContentForDisplay(record.text);
+    if (unwrapped === record.text) {
+      return block;
+    }
+
+    changed = true;
+    return { ...record, text: unwrapped };
+  });
+
+  return changed ? JSON.stringify(normalizedBlocks) : null;
+}
+
+function isLegacyGuardianBackfillRow(
+  row: CandidateMessageRow,
+  parsed: {
+    metadata: Record<string, unknown>;
+    slackMeta: SlackMessageMetadata;
+  },
+): boolean {
+  if (row.role !== "user") return false;
+  if (parsed.slackMeta.eventKind !== "message") return false;
+  if (
+    Object.prototype.hasOwnProperty.call(
+      parsed.metadata,
+      "provenanceTrustClass",
+    )
+  ) {
+    return false;
+  }
+
+  // Old live Slack turns were written with turn-channel metadata. Old
+  // backfill rows were written directly with only `slackMeta`, and the old
+  // backfill invariant was: non-guardian non-empty text was stored wrapped,
+  // while guardian-authored non-empty text was stored raw. Only stamp the
+  // non-empty raw-text case; attachment-only / empty rows stay conservative.
+  if (
+    Object.prototype.hasOwnProperty.call(parsed.metadata, "userMessageChannel")
+  ) {
+    return false;
+  }
+
+  return hasNonEmptyRawText(row.content);
+}
+
+function hasNonEmptyRawText(content: string): boolean {
+  if (parseExternalContentEnvelope(content)) return false;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return content.trim().length > 0;
+  }
+
+  if (typeof parsed === "string") {
+    return parsed.trim().length > 0 && !parseExternalContentEnvelope(parsed);
+  }
+
+  if (!Array.isArray(parsed)) return false;
+
+  return parsed.some((block) => {
+    if (block === null || typeof block !== "object" || Array.isArray(block)) {
+      return false;
+    }
+    const text = (block as Record<string, unknown>).text;
+    return (
+      typeof text === "string" &&
+      text.trim().length > 0 &&
+      !parseExternalContentEnvelope(text)
+    );
+  });
+}

package/src/memory/migrations/__tests__/244-provider-connection-status-label.test.ts

@@ -0,0 +1,84 @@
+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 * as schema from "../../schema.js";
+import { migrateCreateProviderConnections } from "../243-provider-connections.js";
+import { migrateProviderConnectionStatusLabel } from "../244-provider-connection-status-label.js";
+
+interface ColumnRow {
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  return drizzle(sqlite, { schema });
+}
+
+describe("migration 244 — provider_connection status + label", () => {
+  test("adds status (NOT NULL DEFAULT active) and label (nullable) columns", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    // Bootstrap provider_connections table via migration 243.
+    migrateCreateProviderConnections(db);
+
+    // Verify the new columns are absent before migration 244.
+    const colsBefore = raw.query(`PRAGMA table_info(provider_connections)`).all() as ColumnRow[];
+    const namesBefore = colsBefore.map((c) => c.name);
+    expect(namesBefore).not.toContain("status");
+    expect(namesBefore).not.toContain("label");
+
+    migrateProviderConnectionStatusLabel(db);
+
+    const cols = raw.query(`PRAGMA table_info(provider_connections)`).all() as ColumnRow[];
+    const colMap = Object.fromEntries(cols.map((c) => [c.name, c]));
+
+    // status: NOT NULL, default 'active'
+    expect(colMap["status"]).toBeDefined();
+    expect(colMap["status"].notnull).toBe(1);
+    expect(colMap["status"].dflt_value).toBe("'active'");
+
+    // label: nullable
+    expect(colMap["label"]).toBeDefined();
+    expect(colMap["label"].notnull).toBe(0);
+    expect(colMap["label"].dflt_value).toBeNull();
+  });
+
+  test("is idempotent — running twice does not throw", () => {
+    const db = createTestDb();
+    migrateCreateProviderConnections(db);
+    migrateProviderConnectionStatusLabel(db);
+    expect(() => migrateProviderConnectionStatusLabel(db)).not.toThrow();
+  });
+
+  test("existing rows get status=active from column default", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    // Seed a row before adding the status column.
+    migrateCreateProviderConnections(db);
+
+    // Verify canonical connections got the default.
+    migrateProviderConnectionStatusLabel(db);
+
+    const rows = raw.query(`SELECT name, status, label FROM provider_connections`).all() as Array<{
+      name: string;
+      status: string;
+      label: string | null;
+    }>;
+    expect(rows.length).toBeGreaterThan(0);
+    for (const row of rows) {
+      expect(row.status).toBe("active");
+      expect(row.label).toBeNull();
+    }
+  });
+});

package/src/memory/migrations/__tests__/245-memory-retrospective-state.test.ts

@@ -0,0 +1,125 @@
+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 * as schema from "../../schema.js";
+import { migrateMemoryRetrospectiveState } from "../245-memory-retrospective-state.js";
+
+interface ColumnRow {
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+
+interface ForeignKeyRow {
+  id: number;
+  seq: number;
+  table: string;
+  from: string;
+  to: string;
+  on_update: string;
+  on_delete: string;
+}
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  // `withCrashRecovery` (used by the migration) reads/writes a
+  // `memory_checkpoints` table. Seed a minimal version so the migration's
+  // structural setup can be exercised without booting the entire
+  // db-init pipeline.
+  sqlite.exec(`
+    CREATE TABLE memory_checkpoints (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  // The state table FK references `conversations(id)`, so the test DB needs
+  // that table to exist before we can apply the FK. Use a minimal table —
+  // we're only checking the migration's structural output, not exercising
+  // cascade behavior end-to-end.
+  sqlite.exec(`
+    CREATE TABLE conversations (
+      id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  return drizzle(sqlite, { schema });
+}
+
+describe("migration 245 — memory_retrospective_state", () => {
+  test("creates the table with the expected columns and primary key", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateMemoryRetrospectiveState(db);
+
+    const cols = raw
+      .query(`PRAGMA table_info(memory_retrospective_state)`)
+      .all() as ColumnRow[];
+    const colMap = Object.fromEntries(cols.map((c) => [c.name, c]));
+
+    expect(colMap["conversation_id"]).toBeDefined();
+    expect(colMap["conversation_id"].pk).toBe(1);
+
+    expect(colMap["last_processed_message_id"]).toBeDefined();
+    expect(colMap["last_processed_message_id"].notnull).toBe(1);
+
+    expect(colMap["last_run_at"]).toBeDefined();
+    expect(colMap["last_run_at"].notnull).toBe(1);
+  });
+
+  test("FK on conversation_id is ON DELETE CASCADE", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateMemoryRetrospectiveState(db);
+
+    const fks = raw
+      .query(`PRAGMA foreign_key_list(memory_retrospective_state)`)
+      .all() as ForeignKeyRow[];
+
+    expect(fks).toHaveLength(1);
+    expect(fks[0]!.from).toBe("conversation_id");
+    expect(fks[0]!.table).toBe("conversations");
+    expect(fks[0]!.to).toBe("id");
+    expect(fks[0]!.on_delete).toBe("CASCADE");
+  });
+
+  test("is idempotent — running twice does not throw", () => {
+    const db = createTestDb();
+
+    migrateMemoryRetrospectiveState(db);
+    expect(() => migrateMemoryRetrospectiveState(db)).not.toThrow();
+  });
+
+  test("deleting a conversation cascades to its state row", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    migrateMemoryRetrospectiveState(db);
+
+    raw.exec(`INSERT INTO conversations (id, created_at) VALUES ('c1', 0)`);
+    raw.exec(
+      `INSERT INTO memory_retrospective_state (conversation_id, last_processed_message_id, last_run_at) VALUES ('c1', 'm1', 1000)`,
+    );
+
+    const before = raw
+      .query(`SELECT COUNT(*) AS c FROM memory_retrospective_state`)
+      .get() as { c: number };
+    expect(before.c).toBe(1);
+
+    raw.exec(`DELETE FROM conversations WHERE id = 'c1'`);
+
+    const after = raw
+      .query(`SELECT COUNT(*) AS c FROM memory_retrospective_state`)
+      .get() as { c: number };
+    expect(after.c).toBe(0);
+  });
+});

package/src/memory/migrations/__tests__/246-backfill-provider-connection-label.test.ts

@@ -0,0 +1,192 @@
+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 * as schema from "../../schema.js";
+import { migrateCreateProviderConnections } from "../243-provider-connections.js";
+import { migrateProviderConnectionStatusLabel } from "../244-provider-connection-status-label.js";
+import { migrateBackfillProviderConnectionLabel } from "../246-backfill-provider-connection-label.js";
+
+interface ConnectionRow {
+  name: string;
+  label: string | null;
+}
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  return drizzle(sqlite, { schema });
+}
+
+/// Ensure the `memory_checkpoints` table exists in test DBs — it's normally
+/// provisioned by earlier infra migrations that the test harness doesn't
+/// pull in. Schema mirrors what other backfill migrations expect.
+function ensureCheckpointsTable(db: ReturnType<typeof createTestDb>): void {
+  const raw = getSqliteFrom(db);
+  raw.exec(`
+    CREATE TABLE IF NOT EXISTS memory_checkpoints (
+      key TEXT PRIMARY KEY,
+      value TEXT,
+      updated_at INTEGER
+    )
+  `);
+}
+
+/// Bring the test DB up to the state right before migration 246 runs:
+/// provider_connections table present + status/label columns added.
+function prepareSchemaThroughMigration244(
+  db: ReturnType<typeof createTestDb>,
+): void {
+  migrateCreateProviderConnections(db);
+  migrateProviderConnectionStatusLabel(db);
+  ensureCheckpointsTable(db);
+}
+
+describe("migration 246 — backfill provider_connection label", () => {
+  test("sets label = name for rows where label is NULL", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    prepareSchemaThroughMigration244(db);
+
+    // Insert a row with label = NULL (simulating a pre-244 connection).
+    const now = Date.now();
+    raw
+      .query(
+        `INSERT INTO provider_connections (name, provider, auth, status, label, created_at, updated_at) VALUES (?, ?, ?, 'active', NULL, ?, ?)`,
+      )
+      .run("anthropic-personal", "anthropic", JSON.stringify({ type: "api_key", credential: "credential/anthropic/api_key" }), now, now);
+
+    migrateBackfillProviderConnectionLabel(db);
+
+    const row = raw
+      .query(`SELECT name, label FROM provider_connections WHERE name = ?`)
+      .get("anthropic-personal") as ConnectionRow;
+    expect(row.label).toBe("anthropic-personal");
+  });
+
+  test("sets label = name for rows where label is empty/whitespace", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    prepareSchemaThroughMigration244(db);
+
+    const now = Date.now();
+    raw
+      .query(
+        `INSERT INTO provider_connections (name, provider, auth, status, label, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?)`,
+      )
+      .run("openai-empty", "openai", JSON.stringify({ type: "api_key", credential: "credential/openai/api_key" }), "", now, now);
+    raw
+      .query(
+        `INSERT INTO provider_connections (name, provider, auth, status, label, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?)`,
+      )
+      .run("openai-whitespace", "openai", JSON.stringify({ type: "api_key", credential: "credential/openai/api_key" }), "   ", now, now);
+
+    migrateBackfillProviderConnectionLabel(db);
+
+    const empty = raw
+      .query(`SELECT label FROM provider_connections WHERE name = ?`)
+      .get("openai-empty") as ConnectionRow;
+    const whitespace = raw
+      .query(`SELECT label FROM provider_connections WHERE name = ?`)
+      .get("openai-whitespace") as ConnectionRow;
+    expect(empty.label).toBe("openai-empty");
+    expect(whitespace.label).toBe("openai-whitespace");
+  });
+
+  test("does NOT overwrite rows where the user has set a non-empty label", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    prepareSchemaThroughMigration244(db);
+
+    const now = Date.now();
+    raw
+      .query(
+        `INSERT INTO provider_connections (name, provider, auth, status, label, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?)`,
+      )
+      .run("anthropic-work", "anthropic", JSON.stringify({ type: "api_key", credential: "credential/anthropic/api_key" }), "Anthropic — Work", now, now);
+
+    migrateBackfillProviderConnectionLabel(db);
+
+    const row = raw
+      .query(`SELECT label FROM provider_connections WHERE name = ?`)
+      .get("anthropic-work") as ConnectionRow;
+    expect(row.label).toBe("Anthropic — Work");
+  });
+
+  test("is idempotent — second run does not re-clobber a later user-cleared label", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    prepareSchemaThroughMigration244(db);
+
+    const now = Date.now();
+    raw
+      .query(
+        `INSERT INTO provider_connections (name, provider, auth, status, label, created_at, updated_at) VALUES (?, ?, ?, 'active', NULL, ?, ?)`,
+      )
+      .run("anthropic-personal", "anthropic", JSON.stringify({ type: "api_key", credential: "credential/anthropic/api_key" }), now, now);
+
+    // First run: backfills NULL → "anthropic-personal".
+    migrateBackfillProviderConnectionLabel(db);
+    expect(
+      (raw.query(`SELECT label FROM provider_connections WHERE name = ?`).get("anthropic-personal") as ConnectionRow).label,
+    ).toBe("anthropic-personal");
+
+    // User clears the label after the backfill ran.
+    raw.query(`UPDATE provider_connections SET label = NULL WHERE name = ?`).run("anthropic-personal");
+
+    // Second run: should NOT re-clobber the user's deliberate clear, because
+    // the checkpoint was set on the first successful run.
+    migrateBackfillProviderConnectionLabel(db);
+    expect(
+      (raw.query(`SELECT label FROM provider_connections WHERE name = ?`).get("anthropic-personal") as ConnectionRow).label,
+    ).toBeNull();
+  });
+
+  test("checkpoint is set after a successful run", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    prepareSchemaThroughMigration244(db);
+
+    migrateBackfillProviderConnectionLabel(db);
+
+    const checkpoint = raw
+      .query(`SELECT key FROM memory_checkpoints WHERE key = ?`)
+      .get("backfill_provider_connection_label") as { key: string } | null;
+    expect(checkpoint).not.toBeNull();
+    expect(checkpoint?.key).toBe("backfill_provider_connection_label");
+  });
+
+  test("no-op when provider_connections table is absent (first-boot edge)", () => {
+    const db = createTestDb();
+    ensureCheckpointsTable(db);
+
+    // Don't run 243/244 — the table doesn't exist yet.
+    expect(() => migrateBackfillProviderConnectionLabel(db)).not.toThrow();
+
+    // Checkpoint should still get set so we don't retry forever.
+    const raw = getSqliteFrom(db);
+    const checkpoint = raw
+      .query(`SELECT key FROM memory_checkpoints WHERE key = ?`)
+      .get("backfill_provider_connection_label");
+    expect(checkpoint).not.toBeNull();
+  });
+
+  test("no-op when label column is absent (244 hasn't run yet) — no checkpoint set", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    migrateCreateProviderConnections(db); // 243 only, NOT 244
+    ensureCheckpointsTable(db);
+
+    expect(() => migrateBackfillProviderConnectionLabel(db)).not.toThrow();
+
+    // Crucially: no checkpoint should be set, so the backfill can run later
+    // once 244 has provisioned the column.
+    const checkpoint = raw
+      .query(`SELECT key FROM memory_checkpoints WHERE key = ?`)
+      .get("backfill_provider_connection_label");
+    expect(checkpoint).toBeNull();
+  });
+});

package/src/memory/migrations/index.ts

@@ -201,6 +201,19 @@ export {
 } from "./237-heartbeat-runs.js";
 export { migrateScheduleRetryPolicy } from "./238-schedule-retry-policy.js";
 export { migrateTraceEventsCreatedAtIndex } from "./239-trace-events-created-at-index.js";
+export { migrateConversationInferenceProfileSession } from "./240-conversation-inference-profile-session.js";
+export { migrateActivationStateFkCascade } from "./241-activation-state-fk-cascade.js";
+export { migrateMessageBookmarks } from "./242-message-bookmarks.js";
+export { migrateCreateProviderConnections } from "./243-provider-connections.js";
+export { migrateProviderConnectionStatusLabel } from "./244-provider-connection-status-label.js";
+export { migrateMemoryRetrospectiveState } from "./245-memory-retrospective-state.js";
+export { migrateBackfillProviderConnectionLabel } from "./246-backfill-provider-connection-label.js";
+export { migrateExternalConversationBindingThreadId } from "./247-external-conversation-binding-thread-id.js";
+export { createOnboardingEventsTable } from "./248-create-onboarding-events.js";
+export {
+  downNormalizeSlackExternalContent,
+  migrateNormalizeSlackExternalContent,
+} from "./249-normalize-slack-external-content.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -48,6 +48,7 @@ import { downMemoryV2ActivationLogs } from "./234-memory-v2-activation-logs.js";
 import { downSlackCompactionWatermark } from "./235-slack-compaction-watermark.js";
 import { downToolInvocationsMatchedRuleId } from "./236-tool-invocations-matched-rule-id.js";
 import { downHeartbeatRuns } from "./237-heartbeat-runs.js";
+import { downNormalizeSlackExternalContent } from "./249-normalize-slack-external-content.js";
 
 export interface MigrationRegistryEntry {
   /** The checkpoint key written to memory_checkpoints on completion. */
@@ -412,6 +413,13 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
       "Create heartbeat_runs table for tracking heartbeat execution lifecycle with CAS state transitions",
     down: downHeartbeatRuns,
   },
+  {
+    key: "migration_normalize_slack_external_content_v1",
+    version: 48,
+    description:
+      "Normalize legacy persisted Slack external_content wrappers back to raw message content",
+    down: downNormalizeSlackExternalContent,
+  },
 ];
 
 export function getMaxMigrationVersion(): number {