@vellumai/assistant 0.5.5 → 0.5.7

package/src/memory/migrations/169-rename-gmail-provider-key-to-google.ts

@@ -1,4 +1,5 @@
-import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
 import { withCrashRecovery } from "./validate-migration-state.js";
 
 /**
@@ -62,3 +63,52 @@ export function migrateRenameGmailProviderKeyToGoogle(
     },
   );
 }
+
+/**
+ * Reverse: rename "integration:google" back to "integration:gmail" across
+ * OAuth tables.
+ *
+ * Mirrors the forward migration logic but in the opposite direction. If
+ * `integration:gmail` already exists (shouldn't normally happen on rollback),
+ * deletes the google rows to avoid duplicates.
+ */
+export function migrateRenameGmailProviderKeyToGoogleDown(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  raw.exec("PRAGMA foreign_keys = OFF");
+  try {
+    const gmailExists = raw
+      .prepare(
+        /*sql*/ `SELECT 1 FROM oauth_providers WHERE provider_key = 'integration:gmail'`,
+      )
+      .get();
+
+    if (gmailExists) {
+      // Old gmail rows already exist — delete the google ones to avoid duplication.
+      raw.exec(
+        /*sql*/ `DELETE FROM oauth_connections WHERE provider_key = 'integration:google'`,
+      );
+      raw.exec(
+        /*sql*/ `DELETE FROM oauth_apps WHERE provider_key = 'integration:google'`,
+      );
+      raw.exec(
+        /*sql*/ `DELETE FROM oauth_providers WHERE provider_key = 'integration:google'`,
+      );
+    } else {
+      // Rename google back to gmail — children first, then parent.
+      raw.exec(
+        /*sql*/ `UPDATE oauth_connections SET provider_key = 'integration:gmail' WHERE provider_key = 'integration:google'`,
+      );
+      raw.exec(
+        /*sql*/ `UPDATE oauth_apps SET provider_key = 'integration:gmail' WHERE provider_key = 'integration:google'`,
+      );
+      raw.exec(
+        /*sql*/ `UPDATE oauth_providers SET provider_key = 'integration:gmail' WHERE provider_key = 'integration:google'`,
+      );
+    }
+  } finally {
+    raw.exec("PRAGMA foreign_keys = ON");
+  }
+}

package/src/memory/migrations/174-rename-thread-starters-table.ts

@@ -1,4 +1,5 @@
-import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
 import { withCrashRecovery } from "./validate-migration-state.js";
 
 /**
@@ -51,3 +52,48 @@ export function migrateRenameThreadStartersTable(database: DrizzleDb): void {
     },
   );
 }
+
+/**
+ * Reverse: rename conversation_starters back to thread_starters and recreate
+ * old index names.
+ *
+ * Idempotent — skips if the old table already exists or the new table is
+ * absent.
+ */
+export function migrateRenameThreadStartersTableDown(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  // Guard: new table must exist
+  const newTableExists = raw
+    .query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'conversation_starters'`,
+    )
+    .get();
+  if (!newTableExists) return;
+
+  // Guard: old table must not already exist
+  const oldTableExists = raw
+    .query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'thread_starters'`,
+    )
+    .get();
+  if (oldTableExists) return;
+
+  // Rename the table back
+  raw.exec(
+    /*sql*/ `ALTER TABLE conversation_starters RENAME TO thread_starters`,
+  );
+
+  // Drop new indexes and recreate with old names
+  raw.exec(/*sql*/ `DROP INDEX IF EXISTS idx_conversation_starters_batch`);
+  raw.exec(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_thread_starters_batch ON thread_starters(generation_batch, created_at)`,
+  );
+
+  raw.exec(/*sql*/ `DROP INDEX IF EXISTS idx_conversation_starters_card_type`);
+  raw.exec(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_thread_starters_card_type ON thread_starters(card_type, scope_id)`,
+  );
+}

package/src/memory/migrations/176-drop-capability-card-state.ts

@@ -34,3 +34,16 @@ export function migrateDropCapabilityCardState(database: DrizzleDb): void {
     raw.exec(/*sql*/ `DROP TABLE IF EXISTS capability_card_categories`);
   });
 }
+
+/**
+ * Reverse: no-op.
+ *
+ * The forward migration deleted rows (card-type conversation starters,
+ * generate_capability_cards jobs, capability_cards checkpoints) and dropped
+ * the capability_card_categories table. The deleted data cannot be restored
+ * — it was discarded as dead state after the capability card feature was
+ * removed.
+ */
+export function migrateDropCapabilityCardStateDown(_database: DrizzleDb): void {
+  // No-op — see comment above.
+}

package/src/memory/migrations/180-backfill-inline-attachments-to-disk.ts

@@ -64,3 +64,19 @@ export function migrateBackfillInlineAttachmentsToDisk(
     },
   );
 }
+
+/**
+ * Reverse: no-op.
+ *
+ * The forward migration moved attachment data from inline base64 in the
+ * database to on-disk files and cleared the dataBase64 column. The original
+ * base64 data has been deleted from the DB, and re-reading it from disk
+ * back into the database would be unreliable (file paths may have changed,
+ * disk files may have been cleaned up). The on-disk files remain intact
+ * and functional.
+ */
+export function migrateBackfillInlineAttachmentsToDiskDown(
+  _database: DrizzleDb,
+): void {
+  // No-op — see comment above.
+}

package/src/memory/migrations/181-rename-thread-starters-checkpoints.ts

@@ -1,4 +1,5 @@
-import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
 import { withCrashRecovery } from "./validate-migration-state.js";
 
 /**
@@ -44,3 +45,29 @@ export function migrateRenameThreadStartersCheckpoints(
     },
   );
 }
+
+/**
+ * Reverse: rename checkpoint keys from "conversation_starters:" back to
+ * "thread_starters:" prefix.
+ *
+ * Mirrors the forward migration but in reverse. Handles collisions the same
+ * way — if an old-prefix key already exists, the new-prefix key is dropped.
+ */
+export function migrateRenameThreadStartersCheckpointsDown(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  // 1. Delete conversation_starters: keys where a corresponding
+  //    thread_starters: key already exists.
+  raw.exec(/*sql*/ `DELETE FROM memory_checkpoints
+     WHERE key LIKE 'conversation_starters:%'
+       AND replace(key, 'conversation_starters:', 'thread_starters:') IN (
+         SELECT key FROM memory_checkpoints WHERE key LIKE 'thread_starters:%'
+       )`);
+
+  // 2. Rename remaining keys back to the old prefix.
+  raw.exec(
+    /*sql*/ `UPDATE memory_checkpoints SET key = replace(key, 'conversation_starters:', 'thread_starters:') WHERE key LIKE 'conversation_starters:%'`,
+  );
+}

package/src/memory/migrations/189-drop-simplified-memory.ts

@@ -0,0 +1,42 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Drop simplified-memory tables and reducer checkpoint columns added by
+ * the simplified-memory-v1 plan, reverting to the legacy item/tier/XML
+ * memory system.
+ */
+export function migrateDropSimplifiedMemory(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  // Drop simplified-memory tables (idempotent — IF EXISTS).
+  raw.exec(`DROP TABLE IF EXISTS time_contexts`);
+  raw.exec(`DROP TABLE IF EXISTS open_loops`);
+  raw.exec(`DROP TABLE IF EXISTS memory_observations`);
+  raw.exec(`DROP TABLE IF EXISTS memory_chunks`);
+  raw.exec(`DROP TABLE IF EXISTS memory_episodes`);
+
+  // Remove reducer checkpoint columns from conversations.
+  // SQLite doesn't support DROP COLUMN before 3.35.0, but Bun's built-in
+  // SQLite is >= 3.38, so this is safe.
+  for (const col of [
+    "memory_reduced_through_message_id",
+    "memory_dirty_tail_since_message_id",
+    "memory_last_reduced_at",
+  ]) {
+    try {
+      raw.exec(`ALTER TABLE conversations DROP COLUMN ${col}`);
+    } catch {
+      // Column doesn't exist — already cleaned up.
+    }
+  }
+
+  // Remove embedding rows for archive target types that no longer exist.
+  try {
+    raw.exec(
+      `DELETE FROM memory_embeddings WHERE target_type IN ('observation', 'chunk', 'episode')`,
+    );
+  } catch {
+    // Column doesn't exist — table was never migrated to include target_type.
+  }
+}

package/src/memory/migrations/190-call-session-skip-disclosure.ts

@@ -0,0 +1,15 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+/**
+ * Add skip_disclosure column to call_sessions so outbound calls can
+ * skip the disclosure announcement on a per-call basis.
+ */
+export function migrateCallSessionSkipDisclosure(database: DrizzleDb): void {
+  try {
+    database.run(
+      /*sql*/ `ALTER TABLE call_sessions ADD COLUMN skip_disclosure INTEGER NOT NULL DEFAULT 0`,
+    );
+  } catch {
+    /* already exists */
+  }
+}

package/src/memory/migrations/191-backfill-audio-attachment-mime-types.ts

@@ -0,0 +1,64 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+/**
+ * Backfill MIME types for audio attachments that were stored with
+ * "application/octet-stream" because the EXTENSION_MIME_MAP was
+ * missing audio format entries.
+ *
+ * Updates mime_type based on the file extension in original_filename.
+ */
+
+const AUDIO_EXT_MIME: Record<string, string> = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+  aac: "audio/aac",
+  m4a: "audio/x-m4a",
+  opus: "audio/opus",
+};
+
+export function migrateBackfillAudioAttachmentMimeTypes(
+  database: DrizzleDb,
+): void {
+  withCrashRecovery(
+    database,
+    "migration_backfill_audio_attachment_mime_types_v1",
+    () => {
+      const raw = getSqliteFrom(database);
+
+      for (const [ext, mime] of Object.entries(AUDIO_EXT_MIME)) {
+        const pattern = `%.${ext}`;
+        const result = raw
+          .query(
+            `UPDATE attachments
+             SET mime_type = ?, kind = 'document'
+             WHERE lower(original_filename) LIKE ?
+               AND mime_type = 'application/octet-stream'`,
+          )
+          .run(mime, pattern);
+
+        if ((result as { changes?: number }).changes) {
+          console.log(
+            `Backfilled ${(result as { changes: number }).changes} .${ext} attachments → ${mime}`,
+          );
+        }
+      }
+    },
+  );
+}
+
+/**
+ * Reverse: no-op.
+ *
+ * The forward migration corrected incorrect MIME types (application/octet-stream)
+ * to their proper audio/* values. Restoring the wrong MIME types would break
+ * audio playback and file handling. The corrected values are the desired state.
+ */
+export function migrateBackfillAudioAttachmentMimeTypesDown(
+  _database: DrizzleDb,
+): void {
+  // No-op — see comment above.
+}

package/src/memory/migrations/192-contacts-user-file-column.ts

@@ -0,0 +1,15 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+export function migrateContactsUserFileColumn(database: DrizzleDb): void {
+  withCrashRecovery(database, "migration_contacts_user_file_column_v1", () => {
+    const raw = getSqliteFrom(database);
+
+    try {
+      raw.exec(/*sql*/ `ALTER TABLE contacts ADD COLUMN user_file TEXT`);
+    } catch {
+      /* already exists */
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -126,10 +126,11 @@ export { migrateRenameThreadStartersCheckpoints } from "./181-rename-thread-star
 export { migrateOAuthProvidersDisplayMetadata } from "./182-oauth-providers-display-metadata.js";
 export { migrateConversationForkLineage } from "./183-add-conversation-fork-lineage.js";
 export { migrateLlmRequestLogProvider } from "./184-llm-request-log-provider.js";
-export { migrateMemoryBriefState } from "./185-memory-brief-state.js";
-export { migrateMemoryArchiveTables } from "./186-memory-archive.js";
-export { migrateMemoryReducerCheckpoints } from "./187-memory-reducer-checkpoints.js";
 export { migrateScheduleQuietFlag } from "./188-schedule-quiet-flag.js";
+export { migrateDropSimplifiedMemory } from "./189-drop-simplified-memory.js";
+export { migrateCallSessionSkipDisclosure } from "./190-call-session-skip-disclosure.js";
+export { migrateBackfillAudioAttachmentMimeTypes } from "./191-backfill-audio-attachment-mime-types.js";
+export { migrateContactsUserFileColumn } from "./192-contacts-user-file-column.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,
@@ -137,6 +138,7 @@ export {
 } from "./registry.js";
 export {
   recoverCrashedMigrations,
+  rollbackMemoryMigration,
   validateMigrationState,
   withCrashRecovery,
 } from "./validate-migration-state.js";

package/src/memory/migrations/registry.ts

@@ -1,3 +1,43 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { downJobDeferrals } from "./001-job-deferrals.js";
+import { downMemoryEntityRelationDedup } from "./004-entity-relation-dedup.js";
+import { downMemoryItemsFingerprintScopeUnique } from "./005-fingerprint-scope-unique.js";
+import { downMemoryItemsScopeSaltedFingerprints } from "./006-scope-salted-fingerprints.js";
+import { downAssistantIdToSelf } from "./007-assistant-id-to-self.js";
+import { downRemoveAssistantIdColumns } from "./008-remove-assistant-id-columns.js";
+import { downLlmUsageEventsDropAssistantId } from "./009-llm-usage-events-drop-assistant-id.js";
+import { downBackfillInboxThreadState } from "./014-backfill-inbox-thread-state.js";
+import { downDropActiveSearchIndex } from "./015-drop-active-search-index.js";
+import { downNotificationTablesSchema } from "./019-notification-tables-schema-migration.js";
+import { downRenameChannelToVellum } from "./020-rename-macos-ios-channel-to-vellum.js";
+import { downEmbeddingVectorBlob } from "./024-embedding-vector-blob.js";
+import { downEmbeddingsNullableVectorJson } from "./026a-embeddings-nullable-vector-json.js";
+import { downNormalizePhoneIdentities } from "./036-normalize-phone-identities.js";
+import { downBackfillGuardianPrincipalId } from "./126-backfill-guardian-principal-id.js";
+import { downGuardianPrincipalIdNotNull } from "./127-guardian-principal-id-not-null.js";
+import { downContactsNotesColumn } from "./134-contacts-notes-column.js";
+import { downBackfillContactInteractionStats } from "./135-backfill-contact-interaction-stats.js";
+import { downDropAssistantIdColumns } from "./136-drop-assistant-id-columns.js";
+import { downBackfillUsageCacheAccounting } from "./140-backfill-usage-cache-accounting.js";
+import { downRenameVerificationTable } from "./141-rename-verification-table.js";
+import { downRenameVerificationSessionIdColumn } from "./142-rename-verification-session-id-column.js";
+import { downRenameGuardianVerificationValues } from "./143-rename-guardian-verification-values.js";
+import { downRenameVoiceToPhone } from "./144-rename-voice-to-phone.js";
+import { migrateDropAccountsTableDown } from "./145-drop-accounts-table.js";
+import { migrateRemindersToSchedulesDown } from "./147-migrate-reminders-to-schedules.js";
+import { migrateDropRemindersTableDown } from "./148-drop-reminders-table.js";
+import { migrateOAuthAppsClientSecretPathDown } from "./150-oauth-apps-client-secret-path.js";
+import {
+  migrateGuardianTimestampsEpochMsDown,
+  migrateGuardianTimestampsRebuildDown,
+} from "./162-guardian-timestamps-epoch-ms.js";
+import { migrateRenameGmailProviderKeyToGoogleDown } from "./169-rename-gmail-provider-key-to-google.js";
+import { migrateRenameThreadStartersTableDown } from "./174-rename-thread-starters-table.js";
+import { migrateDropCapabilityCardStateDown } from "./176-drop-capability-card-state.js";
+import { migrateBackfillInlineAttachmentsToDiskDown } from "./180-backfill-inline-attachments-to-disk.js";
+import { migrateRenameThreadStartersCheckpointsDown } from "./181-rename-thread-starters-checkpoints.js";
+import { migrateBackfillAudioAttachmentMimeTypesDown } from "./191-backfill-audio-attachment-mime-types.js";
+
 export interface MigrationRegistryEntry {
   /** The checkpoint key written to memory_checkpoints on completion. */
   key: string;
@@ -7,6 +47,8 @@ export interface MigrationRegistryEntry {
   dependsOn?: string[];
   /** Human-readable description for diagnostics and future authorship guidance. */
   description: string;
+  /** Reverse the migration. Must be idempotent — safe to re-run. */
+  down: (database: DrizzleDb) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -26,18 +68,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 1,
     description:
       "Reconcile legacy deferral history from attempts column into deferrals column",
+    down: downJobDeferrals,
   },
   {
     key: "migration_memory_entity_relations_dedup_v1",
     version: 2,
     description:
       "Deduplicate entity relation edges before enforcing the (source, target, relation) unique index",
+    down: downMemoryEntityRelationDedup,
   },
   {
     key: "migration_memory_items_fingerprint_scope_unique_v1",
     version: 3,
     description:
       "Replace column-level UNIQUE on fingerprint with compound (fingerprint, scope_id) unique index",
+    down: downMemoryItemsFingerprintScopeUnique,
   },
   {
     key: "migration_memory_items_scope_salted_fingerprints_v1",
@@ -45,12 +90,14 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_memory_items_fingerprint_scope_unique_v1"],
     description:
       "Recompute memory item fingerprints to include scope_id prefix after schema change",
+    down: downMemoryItemsScopeSaltedFingerprints,
   },
   {
     key: "migration_normalize_assistant_id_to_self_v1",
     version: 5,
     description:
       'Normalize all assistant_id values in scoped tables to the implicit "self" single-tenant identity',
+    down: downAssistantIdToSelf,
   },
   {
     key: "migration_remove_assistant_id_columns_v1",
@@ -58,6 +105,7 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Rebuild four tables to drop the assistant_id column after normalization",
+    down: downRemoveAssistantIdColumns,
   },
   {
     key: "migration_remove_assistant_id_lue_v1",
@@ -65,36 +113,42 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Remove assistant_id column from llm_usage_events (separate checkpoint from the four-table migration)",
+    down: downLlmUsageEventsDropAssistantId,
   },
   {
     key: "backfill_inbox_thread_state_from_bindings",
     version: 8,
     description:
       "Seed assistant_inbox_thread_state from external_conversation_bindings",
+    down: downBackfillInboxThreadState,
   },
   {
     key: "drop_active_search_index_v1",
     version: 9,
     description:
       "Drop old idx_memory_items_active_search so it can be recreated with updated covering columns",
+    down: downDropActiveSearchIndex,
   },
   {
     key: "migration_notification_tables_schema_v1",
     version: 10,
     description:
       "Drop legacy enum-based notification tables so they can be recreated with the new signal-contract schema",
+    down: downNotificationTablesSchema,
   },
   {
     key: "migration_rename_macos_ios_channel_to_vellum_v1",
     version: 11,
     description:
       "Rename macos and ios channel identifiers to vellum across all tables",
+    down: downRenameChannelToVellum,
   },
   {
     key: "migration_embedding_vector_blob_v1",
     version: 12,
     description:
       "Add vector_blob BLOB column to memory_embeddings and backfill from vector_json for compact binary storage",
+    down: downEmbeddingVectorBlob,
   },
   {
     key: "migration_embeddings_nullable_vector_json_v1",
@@ -102,18 +156,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_embedding_vector_blob_v1"],
     description:
       "Rebuild memory_embeddings to make vector_json nullable (pre-100 DBs had NOT NULL)",
+    down: downEmbeddingsNullableVectorJson,
   },
   {
     key: "migration_normalize_phone_identities_v1",
     version: 14,
     description:
       "Normalize phone-like identity fields to E.164 format across guardian bindings, verification challenges, canonical requests, ingress members, and rate limits",
+    down: downNormalizePhoneIdentities,
   },
   {
     key: "migration_backfill_guardian_principal_id_v3",
     version: 15,
     description:
       "Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests",
+    down: downBackfillGuardianPrincipalId,
   },
   {
     key: "migration_guardian_principal_id_not_null_v1",
@@ -121,18 +178,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_backfill_guardian_principal_id_v3"],
     description:
       "Enforce NOT NULL on channel_guardian_bindings.guardian_principal_id after backfill",
+    down: downGuardianPrincipalIdNotNull,
   },
   {
     key: "migration_contacts_notes_column_v1",
     version: 17,
     description:
       "Consolidate relationship/importance/response_expectation/preferred_tone into a single notes TEXT column, then drop the legacy columns",
+    down: downContactsNotesColumn,
   },
   {
     key: "backfill_contact_interaction_stats",
     version: 18,
     description:
       "Backfill contacts.last_interaction from the max lastSeenAt across each contact's channels",
+    down: downBackfillContactInteractionStats,
   },
   {
     key: "migration_drop_assistant_id_columns_v1",
@@ -140,48 +200,56 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Drop assistant_id columns from all 16 daemon tables after normalization to single-tenant identity",
+    down: downDropAssistantIdColumns,
   },
   {
     key: "migration_backfill_usage_cache_accounting_v1",
     version: 20,
     description:
       "Backfill historical Anthropic llm_usage_events rows from llm_request_logs with cache-aware pricing",
+    down: downBackfillUsageCacheAccounting,
   },
   {
     key: "migration_rename_verification_table_v1",
     version: 21,
     description:
       "Rename channel_guardian_verification_challenges table to channel_verification_sessions and update indexes",
+    down: downRenameVerificationTable,
   },
   {
     key: "migration_rename_verification_session_id_column_v1",
     version: 22,
     description:
       "Rename guardian_verification_session_id column in call_sessions to verification_session_id",
+    down: downRenameVerificationSessionIdColumn,
   },
   {
     key: "migration_rename_guardian_verification_values_v1",
     version: 23,
     description:
       "Rename persisted guardian_verification call_mode and guardian_voice_verification_* event_type values to drop the guardian_ prefix",
+    down: downRenameGuardianVerificationValues,
   },
   {
     key: "migration_rename_voice_to_phone_v1",
     version: 24,
     description:
       'Rename stored "voice" channel values to "phone" across all tables with channel text columns',
+    down: downRenameVoiceToPhone,
   },
   {
     key: "migration_drop_accounts_table_v1",
     version: 25,
     description:
       "Drop the unused legacy accounts table and its leftover indexes after account_manage removal",
+    down: migrateDropAccountsTableDown,
   },
   {
     key: "migration_reminders_to_schedules_v1",
     version: 26,
     description:
       "Copy all existing reminders into cron_jobs as one-shot schedules with correct status and field mapping",
+    down: migrateRemindersToSchedulesDown,
   },
   {
     key: "migration_drop_reminders_table_v1",
@@ -189,18 +257,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_reminders_to_schedules_v1"],
     description:
       "Drop the legacy reminders table and its index after data migration to cron_jobs",
+    down: migrateDropRemindersTableDown,
   },
   {
     key: "migration_oauth_apps_client_secret_path_v1",
     version: 28,
     description:
       "Add client_secret_credential_path column to oauth_apps and backfill existing rows with convention-based paths",
+    down: migrateOAuthAppsClientSecretPathDown,
   },
   {
     key: "migration_guardian_timestamps_epoch_ms_v1",
     version: 29,
     description:
       "Convert guardian table timestamps from ISO 8601 text to epoch ms integers for consistency with all other tables",
+    down: migrateGuardianTimestampsEpochMsDown,
   },
   {
     key: "migration_guardian_timestamps_rebuild_v1",
@@ -208,18 +279,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_guardian_timestamps_epoch_ms_v1"],
     description:
       "Rebuild guardian tables so timestamp columns have INTEGER affinity instead of TEXT",
+    down: migrateGuardianTimestampsRebuildDown,
   },
   {
     key: "migration_rename_gmail_provider_key_to_google_v1",
     version: 31,
     description:
       "Rename integration:gmail provider key to integration:google across oauth_providers, oauth_apps, and oauth_connections",
+    down: migrateRenameGmailProviderKeyToGoogleDown,
   },
   {
     key: "migration_rename_thread_starters_table_v1",
     version: 32,
     description:
       "Rename thread_starters table to conversation_starters and recreate indexes with new names",
+    down: migrateRenameThreadStartersTableDown,
   },
   {
     key: "migration_drop_capability_card_state_v1",
@@ -227,12 +301,14 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_rename_thread_starters_table_v1"],
     description:
       "Remove deleted capability-card rows, jobs, checkpoints, and category state",
+    down: migrateDropCapabilityCardStateDown,
   },
   {
     key: "migration_backfill_inline_attachments_v1",
     version: 34,
     description:
       "Backfill existing inline base64 attachments to on-disk storage and clear dataBase64",
+    down: migrateBackfillInlineAttachmentsToDiskDown,
   },
   {
     key: "migration_rename_thread_starters_checkpoints_v1",
@@ -240,12 +316,26 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_rename_thread_starters_table_v1"],
     description:
       "Rename checkpoint keys from thread_starters: to conversation_starters: prefix so renamed code paths find existing generation state",
+    down: migrateRenameThreadStartersCheckpointsDown,
+  },
+  {
+    key: "migration_backfill_audio_attachment_mime_types_v1",
+    version: 36,
+    description:
+      "Backfill correct MIME types for audio attachments stored as application/octet-stream due to missing extension map entries",
+    down: migrateBackfillAudioAttachmentMimeTypesDown,
   },
 ];
 
+export function getMaxMigrationVersion(): number {
+  return Math.max(...MIGRATION_REGISTRY.map((e) => e.version));
+}
+
 export interface MigrationValidationResult {
   /** Keys of migrations whose checkpoint has value 'started' — started but never completed. */
   crashed: string[];
   /** Pairs where a completed migration's declared prerequisite is missing from checkpoints. */
   dependencyViolations: Array<{ migration: string; missingDependency: string }>;
+  /** Checkpoint keys present in the database but absent from the migration registry — likely from a newer version. */
+  unknownCheckpoints: string[];
 }