@geekbeer/minion 3.36.0 → 3.40.1

package/core/db/helpers.js

@@ -0,0 +1,18 @@
+/**
+ * Shared helpers for migration files.
+ * These are passed as the second argument to each migration's up(db, helpers).
+ */
+
+function hasColumn(db, table, column) {
+  const cols = db.prepare(`PRAGMA table_info(${table})`).all()
+  return cols.some(c => c.name === column)
+}
+
+function tableExists(db, table) {
+  const row = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name = ?"
+  ).get(table)
+  return !!row
+}
+
+module.exports = { hasColumn, tableExists }

package/core/db/index.js

@@ -0,0 +1,146 @@
+/**
+ * SQLite Database Module
+ * Provides a singleton SQLite database connection for all minion stores.
+ * Uses better-sqlite3 (synchronous API) with WAL mode for performance.
+ * Falls back to Node.js built-in node:sqlite when better-sqlite3 is unavailable
+ * (e.g., no prebuilt binaries for the current Node.js version on Windows).
+ *
+ * Database file: $DATA_DIR/minion.db
+ *
+ * Schema changes are applied via migration files in ./migrations/.
+ * Any minion, regardless of the version it was last updated from, reaches the
+ * latest schema on boot because unapplied migrations run in sequence.
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+const { DATA_DIR } = require('../lib/platform')
+const { config } = require('../config')
+const helpers = require('./helpers')
+const migrations = require('./migrations')
+
+let _db = null
+
+function resolveDbPath() {
+  try {
+    fs.accessSync(DATA_DIR, fs.constants.W_OK)
+    return path.join(DATA_DIR, 'minion.db')
+  } catch {
+    return path.join(config.HOME_DIR, 'minion.db')
+  }
+}
+
+function openDatabase(dbPath) {
+  try {
+    const Database = require('better-sqlite3')
+    const db = new Database(dbPath)
+    db.pragma('journal_mode = WAL')
+    db.pragma('foreign_keys = ON')
+    console.log('[DB] Using better-sqlite3')
+    return db
+  } catch (e) {
+    console.log(`[DB] better-sqlite3 unavailable (${e.message}), trying node:sqlite...`)
+  }
+
+  try {
+    const { DatabaseSync } = require('node:sqlite')
+    const db = new DatabaseSync(dbPath)
+    db.exec('PRAGMA journal_mode = WAL')
+    db.exec('PRAGMA foreign_keys = ON')
+
+    db.pragma = function (str) {
+      const stmt = db.prepare(`PRAGMA ${str}`)
+      return stmt.get()
+    }
+
+    db.transaction = function (fn) {
+      return function (...args) {
+        db.exec('BEGIN')
+        try {
+          const result = fn(...args)
+          db.exec('COMMIT')
+          return result
+        } catch (e) {
+          db.exec('ROLLBACK')
+          throw e
+        }
+      }
+    }
+
+    console.log('[DB] Using node:sqlite (built-in)')
+    return db
+  } catch (e) {
+    throw new Error(
+      `[DB] No SQLite driver available. Install better-sqlite3 or use Node.js 22.5.0+ for built-in sqlite support. ` +
+      `better-sqlite3 error: check that Python and build tools are installed, or use Node.js 22 LTS which has prebuilt binaries. ` +
+      `node:sqlite error: ${e.message}`
+    )
+  }
+}
+
+function getDb() {
+  if (_db) return _db
+
+  const dbPath = resolveDbPath()
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true })
+
+  _db = openDatabase(dbPath)
+
+  runMigrations(_db)
+
+  console.log(`[DB] SQLite database initialized: ${dbPath}`)
+  return _db
+}
+
+/**
+ * Apply pending migrations in version order.
+ *
+ * Each migration runs in a transaction; failures roll back cleanly and prevent
+ * the schema_version row from being inserted, so the migration retries on the
+ * next boot. This is a behavior change from the pre-refactor code, which used
+ * try/catch + INSERT OR IGNORE that could leave migrations marked as applied
+ * even when ALTER TABLE silently failed.
+ */
+function runMigrations(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `)
+
+  const applied = new Set(
+    db.prepare('SELECT version FROM schema_version').all().map(r => r.version)
+  )
+
+  const insertVersion = db.prepare('INSERT INTO schema_version (version) VALUES (?)')
+
+  for (const m of migrations) {
+    if (applied.has(m.version)) continue
+
+    if (typeof m.shouldAutoApply === 'function' && m.shouldAutoApply(db)) {
+      console.log(`[DB] Migration ${m.version} (${m.name}): auto-apply (pre-existing state)`)
+      insertVersion.run(m.version)
+      continue
+    }
+
+    console.log(`[DB] Applying migration ${m.version}: ${m.name}...`)
+    const tx = db.transaction(() => {
+      m.up(db, helpers)
+      insertVersion.run(m.version)
+    })
+    tx()
+    console.log(`[DB] Migration ${m.version} (${m.name}) complete`)
+  }
+}
+
+function closeDb() {
+  if (_db) {
+    _db.close()
+    _db = null
+    console.log('[DB] SQLite database closed')
+  }
+}
+
+module.exports = { getDb, closeDb, runMigrations }

package/core/db/migrations/000_initial_schema.js

@@ -0,0 +1,157 @@
+/**
+ * Initial schema — the earliest known state of the DB, before any subsequent
+ * migrations. Each of migrations 001-008 applies one change additively on top.
+ *
+ * For existing DBs created by the pre-refactor code, `memories` already exists,
+ * so this migration auto-applies (marks applied without running) and lets the
+ * subsequent migrations catch the DB up to the latest schema. This guarantees
+ * that a minion updated from any past version reaches the latest schema, since
+ * unapplied migrations still run individually after the auto-apply.
+ */
+
+module.exports = {
+  version: 0,
+  name: 'initial_schema',
+
+  shouldAutoApply(db) {
+    const { tableExists } = require('../helpers')
+    return tableExists(db, 'memories')
+  },
+
+  up(db) {
+    db.exec(`
+      -- ==================== memories ====================
+      CREATE TABLE memories (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL DEFAULT 'Untitled',
+        category TEXT NOT NULL DEFAULT 'reference'
+          CHECK (category IN ('user', 'feedback', 'project', 'reference')),
+        content TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX idx_memories_category ON memories(category);
+      CREATE INDEX idx_memories_updated_at ON memories(updated_at DESC);
+
+      -- ==================== daily_logs ====================
+      CREATE TABLE daily_logs (
+        date TEXT PRIMARY KEY,
+        content TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- ==================== workspaces (cache from HQ) ====================
+      CREATE TABLE workspaces (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        slug TEXT NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      -- ==================== chat_sessions ====================
+      CREATE TABLE chat_sessions (
+        session_id TEXT PRIMARY KEY,
+        turn_count INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE TABLE chat_messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES chat_sessions(session_id) ON DELETE CASCADE,
+        role TEXT NOT NULL,
+        content TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+      );
+
+      CREATE INDEX idx_chat_messages_session ON chat_messages(session_id, id);
+
+      -- ==================== executions ====================
+      CREATE TABLE executions (
+        id TEXT PRIMARY KEY,
+        skill_name TEXT,
+        workflow_id TEXT,
+        status TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        data TEXT NOT NULL
+      );
+
+      CREATE INDEX idx_executions_workflow ON executions(workflow_id);
+      CREATE INDEX idx_executions_created ON executions(created_at DESC);
+
+      -- ==================== routines ====================
+      CREATE TABLE routines (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        data TEXT NOT NULL
+      );
+
+      CREATE INDEX idx_routines_name ON routines(name);
+
+      -- ==================== workflows ====================
+      CREATE TABLE workflows (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        data TEXT NOT NULL
+      );
+
+      CREATE INDEX idx_workflows_name ON workflows(name);
+
+      -- ==================== todos ====================
+      CREATE TABLE todos (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'pending'
+          CHECK (status IN ('pending', 'in_progress', 'done', 'cancelled')),
+        priority TEXT NOT NULL DEFAULT 'normal'
+          CHECK (priority IN ('low', 'normal', 'high', 'urgent')),
+        source_type TEXT
+          CHECK (source_type IS NULL OR source_type IN ('thread', 'workflow', 'directive', 'user', 'self')),
+        source_id TEXT,
+        project_id TEXT,
+        due_at TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        completed_at TEXT,
+        data TEXT
+      );
+
+      CREATE INDEX idx_todos_status ON todos(status);
+      CREATE INDEX idx_todos_project ON todos(project_id);
+      CREATE INDEX idx_todos_priority ON todos(priority);
+
+      -- ==================== emails ====================
+      CREATE TABLE emails (
+        id TEXT PRIMARY KEY,
+        from_address TEXT NOT NULL,
+        to_address TEXT NOT NULL,
+        subject TEXT DEFAULT '',
+        body_text TEXT DEFAULT '',
+        body_html TEXT DEFAULT '',
+        received_at TEXT NOT NULL,
+        is_read INTEGER DEFAULT 0,
+        labels TEXT DEFAULT '[]'
+      );
+
+      CREATE INDEX idx_emails_received_at ON emails(received_at DESC);
+      CREATE INDEX idx_emails_from ON emails(from_address);
+      CREATE INDEX idx_emails_is_read ON emails(is_read);
+
+      -- ==================== email_attachments ====================
+      CREATE TABLE email_attachments (
+        id TEXT PRIMARY KEY,
+        email_id TEXT NOT NULL REFERENCES emails(id) ON DELETE CASCADE,
+        filename TEXT NOT NULL,
+        content_type TEXT,
+        size_bytes INTEGER DEFAULT 0,
+        approved INTEGER DEFAULT 0,
+        data BLOB
+      );
+
+      CREATE INDEX idx_email_attachments_email ON email_attachments(email_id);
+    `)
+  },
+}

package/core/db/migrations/001_fts_trigram.js

@@ -0,0 +1,78 @@
+/**
+ * Create FTS5 virtual tables for memories and daily_logs with the trigram
+ * tokenizer (CJK/Japanese substring search support).
+ *
+ * Uses DROP IF EXISTS + CREATE so it doubles as a repair for DBs that were
+ * originally created with the default unicode61 tokenizer.
+ */
+
+module.exports = {
+  version: 1,
+  name: 'fts_trigram',
+
+  up(db) {
+    db.exec(`
+      DROP TRIGGER IF EXISTS memories_ai;
+      DROP TRIGGER IF EXISTS memories_ad;
+      DROP TRIGGER IF EXISTS memories_au;
+      DROP TABLE IF EXISTS memories_fts;
+
+      DROP TRIGGER IF EXISTS daily_logs_ai;
+      DROP TRIGGER IF EXISTS daily_logs_ad;
+      DROP TRIGGER IF EXISTS daily_logs_au;
+      DROP TABLE IF EXISTS daily_logs_fts;
+
+      CREATE VIRTUAL TABLE memories_fts USING fts5(
+        title,
+        content,
+        content=memories,
+        content_rowid=rowid,
+        tokenize='trigram'
+      );
+
+      CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+        INSERT INTO memories_fts(rowid, title, content)
+          VALUES (new.rowid, new.title, new.content);
+      END;
+
+      CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, title, content)
+          VALUES ('delete', old.rowid, old.title, old.content);
+      END;
+
+      CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, title, content)
+          VALUES ('delete', old.rowid, old.title, old.content);
+        INSERT INTO memories_fts(rowid, title, content)
+          VALUES (new.rowid, new.title, new.content);
+      END;
+
+      CREATE VIRTUAL TABLE daily_logs_fts USING fts5(
+        content,
+        content=daily_logs,
+        content_rowid=rowid,
+        tokenize='trigram'
+      );
+
+      CREATE TRIGGER daily_logs_ai AFTER INSERT ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(rowid, content)
+          VALUES (new.rowid, new.content);
+      END;
+
+      CREATE TRIGGER daily_logs_ad AFTER DELETE ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(daily_logs_fts, rowid, content)
+          VALUES ('delete', old.rowid, old.content);
+      END;
+
+      CREATE TRIGGER daily_logs_au AFTER UPDATE ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(daily_logs_fts, rowid, content)
+          VALUES ('delete', old.rowid, old.content);
+        INSERT INTO daily_logs_fts(rowid, content)
+          VALUES (new.rowid, new.content);
+      END;
+
+      INSERT INTO memories_fts(memories_fts) VALUES ('rebuild');
+      INSERT INTO daily_logs_fts(daily_logs_fts) VALUES ('rebuild');
+    `)
+  },
+}

package/core/db/migrations/002_emails_fts.js

@@ -0,0 +1,41 @@
+/**
+ * Add FTS5 virtual table for emails.subject and emails.body_text (trigram).
+ */
+
+module.exports = {
+  version: 2,
+  name: 'emails_fts',
+
+  up(db, { tableExists }) {
+    if (tableExists(db, 'emails_fts')) return
+
+    db.exec(`
+      CREATE VIRTUAL TABLE emails_fts USING fts5(
+        subject,
+        body_text,
+        content=emails,
+        content_rowid=rowid,
+        tokenize='trigram'
+      );
+
+      CREATE TRIGGER emails_ai AFTER INSERT ON emails BEGIN
+        INSERT INTO emails_fts(rowid, subject, body_text)
+          VALUES (new.rowid, new.subject, new.body_text);
+      END;
+
+      CREATE TRIGGER emails_ad AFTER DELETE ON emails BEGIN
+        INSERT INTO emails_fts(emails_fts, rowid, subject, body_text)
+          VALUES ('delete', old.rowid, old.subject, old.body_text);
+      END;
+
+      CREATE TRIGGER emails_au AFTER UPDATE ON emails BEGIN
+        INSERT INTO emails_fts(emails_fts, rowid, subject, body_text)
+          VALUES ('delete', old.rowid, old.subject, old.body_text);
+        INSERT INTO emails_fts(rowid, subject, body_text)
+          VALUES (new.rowid, new.subject, new.body_text);
+      END;
+
+      INSERT INTO emails_fts(emails_fts) VALUES ('rebuild');
+    `)
+  },
+}

package/core/db/migrations/003_memories_project_id.js

@@ -0,0 +1,17 @@
+/**
+ * Add memories.project_id for linking memories to projects.
+ */
+
+module.exports = {
+  version: 3,
+  name: 'memories_project_id',
+
+  up(db, { hasColumn }) {
+    if (hasColumn(db, 'memories', 'project_id')) return
+
+    db.exec(`
+      ALTER TABLE memories ADD COLUMN project_id TEXT DEFAULT NULL;
+      CREATE INDEX IF NOT EXISTS idx_memories_project_id ON memories(project_id);
+    `)
+  },
+}

package/core/db/migrations/004_chat_sessions_workspace.js

@@ -0,0 +1,18 @@
+/**
+ * Add chat_sessions.workspace_id so chat history can be scoped per workspace.
+ */
+
+module.exports = {
+  version: 4,
+  name: 'chat_sessions_workspace',
+
+  up(db, { hasColumn }) {
+    if (hasColumn(db, 'chat_sessions', 'workspace_id')) return
+
+    db.exec(`
+      ALTER TABLE chat_sessions ADD COLUMN workspace_id TEXT DEFAULT NULL;
+      CREATE INDEX IF NOT EXISTS idx_chat_sessions_workspace
+        ON chat_sessions(workspace_id, updated_at DESC);
+    `)
+  },
+}

package/core/db/migrations/005_todos_session_injection.js

@@ -0,0 +1,19 @@
+/**
+ * Add todos.session_id (link to chat session that created the todo) and
+ * todos.injection_count (how many times the todo has been injected into chat).
+ */
+
+module.exports = {
+  version: 5,
+  name: 'todos_session_injection',
+
+  up(db, { hasColumn }) {
+    if (!hasColumn(db, 'todos', 'session_id')) {
+      db.exec(`ALTER TABLE todos ADD COLUMN session_id TEXT`)
+    }
+    if (!hasColumn(db, 'todos', 'injection_count')) {
+      db.exec(`ALTER TABLE todos ADD COLUMN injection_count INTEGER NOT NULL DEFAULT 0`)
+    }
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_todos_session ON todos(session_id)`)
+  },
+}

package/core/db/migrations/006_daily_logs_workspace.js

@@ -0,0 +1,69 @@
+/**
+ * Scope daily_logs by workspace_id. SQLite cannot alter a PRIMARY KEY in place,
+ * so the table is rebuilt with a composite (workspace_id, date) PK.
+ *
+ * Existing rows are backfilled to the first workspace by name — or '' (legacy
+ * bucket) if the workspaces cache is empty (minion hasn't synced yet).
+ */
+
+module.exports = {
+  version: 6,
+  name: 'daily_logs_workspace',
+
+  up(db, { hasColumn }) {
+    if (hasColumn(db, 'daily_logs', 'workspace_id')) return
+
+    db.exec(`
+      DROP TRIGGER IF EXISTS daily_logs_ai;
+      DROP TRIGGER IF EXISTS daily_logs_ad;
+      DROP TRIGGER IF EXISTS daily_logs_au;
+      DROP TABLE IF EXISTS daily_logs_fts;
+
+      ALTER TABLE daily_logs RENAME TO daily_logs_old;
+
+      CREATE TABLE daily_logs (
+        workspace_id TEXT NOT NULL DEFAULT '',
+        date TEXT NOT NULL,
+        content TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (workspace_id, date)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_daily_logs_date ON daily_logs(date DESC);
+
+      INSERT INTO daily_logs (workspace_id, date, content, created_at, updated_at)
+        SELECT COALESCE((SELECT id FROM workspaces ORDER BY name LIMIT 1), ''),
+               date, content, created_at, updated_at
+        FROM daily_logs_old;
+
+      DROP TABLE daily_logs_old;
+
+      CREATE VIRTUAL TABLE daily_logs_fts USING fts5(
+        content,
+        content=daily_logs,
+        content_rowid=rowid,
+        tokenize='trigram'
+      );
+
+      CREATE TRIGGER daily_logs_ai AFTER INSERT ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(rowid, content)
+          VALUES (new.rowid, new.content);
+      END;
+
+      CREATE TRIGGER daily_logs_ad AFTER DELETE ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(daily_logs_fts, rowid, content)
+          VALUES ('delete', old.rowid, old.content);
+      END;
+
+      CREATE TRIGGER daily_logs_au AFTER UPDATE ON daily_logs BEGIN
+        INSERT INTO daily_logs_fts(daily_logs_fts, rowid, content)
+          VALUES ('delete', old.rowid, old.content);
+        INSERT INTO daily_logs_fts(rowid, content)
+          VALUES (new.rowid, new.content);
+      END;
+
+      INSERT INTO daily_logs_fts(daily_logs_fts) VALUES ('rebuild');
+    `)
+  },
+}

package/core/db/migrations/007_workspace_scoping.js

@@ -0,0 +1,29 @@
+/**
+ * Scope workflows, routines, and executions by workspace_id.
+ *
+ * Existing rows keep workspace_id = '' (legacy bucket); they'll be naturally
+ * overwritten as HQ re-syncs workflows and routines after the upgrade.
+ */
+
+module.exports = {
+  version: 7,
+  name: 'workspace_scoping',
+
+  up(db, { hasColumn }) {
+    if (!hasColumn(db, 'workflows', 'workspace_id')) {
+      db.exec(`ALTER TABLE workflows ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''`)
+    }
+    if (!hasColumn(db, 'routines', 'workspace_id')) {
+      db.exec(`ALTER TABLE routines ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''`)
+    }
+    if (!hasColumn(db, 'executions', 'workspace_id')) {
+      db.exec(`ALTER TABLE executions ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''`)
+    }
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_workflows_workspace ON workflows(workspace_id, name);
+      CREATE INDEX IF NOT EXISTS idx_routines_workspace ON routines(workspace_id, name);
+      CREATE INDEX IF NOT EXISTS idx_executions_workspace ON executions(workspace_id, created_at DESC);
+    `)
+  },
+}

package/core/db/migrations/008_todos_workspace.js

@@ -0,0 +1,22 @@
+/**
+ * Scope todos by workspace_id.
+ *
+ * Existing rows stay at '' (legacy bucket) until the caller (chat /
+ * thread-watcher / directive) starts passing workspace_id explicitly.
+ */
+
+module.exports = {
+  version: 8,
+  name: 'todos_workspace',
+
+  up(db, { hasColumn }) {
+    if (!hasColumn(db, 'todos', 'workspace_id')) {
+      db.exec(`ALTER TABLE todos ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''`)
+    }
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_todos_workspace ON todos(workspace_id, status);
+      CREATE INDEX IF NOT EXISTS idx_todos_workspace_session ON todos(workspace_id, session_id);
+    `)
+  },
+}

package/core/db/migrations/index.js

@@ -0,0 +1,41 @@
+/**
+ * Auto-loads all migration files in this directory.
+ *
+ * Naming conventions:
+ *   - Legacy (frozen, 000-008): NNN_<name>.js
+ *   - New migrations:          YYYYMMDDHHMMSS_<name>.js
+ *
+ * Both sort correctly in lexicographic order because "008_..." < "20260101000000_...".
+ *
+ * Each migration module must export:
+ *   - version: number       (unique integer; used as schema_version primary key)
+ *   - name: string          (human-readable identifier)
+ *   - up(db, helpers)       (applies the change; runs in a transaction)
+ *   - shouldAutoApply?(db)  (optional; return true to mark applied without running up())
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const files = fs.readdirSync(__dirname)
+  .filter(f => f.endsWith('.js') && f !== 'index.js')
+  .sort()
+
+const migrations = files.map(f => {
+  const mod = require(path.join(__dirname, f))
+  if (typeof mod.version !== 'number' || !mod.name || typeof mod.up !== 'function') {
+    throw new Error(`[DB] Invalid migration file: ${f} (must export { version, name, up })`)
+  }
+  return mod
+})
+
+// Guard against duplicate version numbers
+const seen = new Set()
+for (const m of migrations) {
+  if (seen.has(m.version)) {
+    throw new Error(`[DB] Duplicate migration version: ${m.version}`)
+  }
+  seen.add(m.version)
+}
+
+module.exports = migrations