perf: gate schema migration probes behind PRAGMA user_version (#208) (#216)

initialize_schema ran up to eight throwaway `SELECT col ... LIMIT 1` probes on
every Database::open to detect missing columns — and open is called several
times per process, so on a fully-migrated DB this is pure wasted work every boot.

Gate the probe block on PRAGMA user_version: read it after the (still-ungated,
all-IF-NOT-EXISTS) DDL, return early when already at SCHEMA_VERSION, and stamp
the version once the column-add migrations have run. The DDL stays ungated so it
still back-fills newer objects (e.g. idx_entities_recall) on older databases.

Pre-existing databases sit at user_version=0, so they pay the probe pass exactly
once more (idempotent — columns already exist, no ALTERs fire) and are then
stamped; every subsequent open skips the block. A documented SCHEMA_VERSION
constant flags that adding a future probe requires a bump.

Addresses #208 item 4 (item 2, ONNX session cache, remains blocked by #212).

Tests: stamps_user_version_and_gates_migration_probes (fresh init stamps the
version; re-init is a data-preserving no-op) and migrates_pre_versioned_db_
missing_a_column (a user_version=0 legacy DB missing `visibility` still gets the
column added, then stamped). 41 passed / 0 failed (MSVC), build warning-free.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: tcconnally

src/schema.rs

@@ -69,10 +69,27 @@ CREATE TABLE IF NOT EXISTS state (
 );
 ";
 
+/// Current schema migration level, stamped into `PRAGMA user_version` once all
+/// the column-add migrations below have been applied. Bump this whenever you add
+/// a new ALTER-probe migration in `initialize_schema`, or existing databases
+/// (already at the previous level) will skip it.
+const SCHEMA_VERSION: i64 = 1;
+
 /// Initialize the v0.2.0 schema on a fresh database.
 pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Error>> {
+    // DDL is all IF NOT EXISTS, so it stays ungated: it both creates a fresh DB
+    // and back-fills newer objects (e.g. idx_entities_recall) on older ones.
     conn.execute_batch(DDL_V0_2_0)?;
 
+    // The column-add migrations below each prepare a throwaway `SELECT col LIMIT 1`
+    // probe. `open` runs several times per process, so on a fully-migrated DB this
+    // is pure wasted work. Gate it on PRAGMA user_version: run once when behind,
+    // then stamp current and skip on every subsequent open. (#208)
+    let user_version: i64 = conn.query_row("PRAGMA user_version", [], |r| r.get(0))?;
+    if user_version >= SCHEMA_VERSION {
+        return Ok(());
+    }
+
     // Add embedding column if it doesn't exist (migration from v0.2.0)
     let has_embedding: bool = conn
         .prepare("SELECT embedding FROM entities LIMIT 1")
@@ -129,6 +146,9 @@ pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Er
         conn.execute_batch("ALTER TABLE entities ADD COLUMN visibility TEXT DEFAULT 'workspace';")?;
     }
 
+    // Stamp the migration level so subsequent opens skip the probe block above.
+    conn.pragma_update(None, "user_version", SCHEMA_VERSION)?;
+
     Ok(())
 }
 
@@ -400,6 +420,74 @@ mod tests {
         assert!(is_v0_2_0(&conn).unwrap());
     }
 
+    #[test]
+    fn stamps_user_version_and_gates_migration_probes() {
+        // Fresh init stamps the current schema version.
+        let (conn, _path) = temp_db();
+        initialize_schema(&conn).expect("init schema");
+        let v: i64 = conn
+            .query_row("PRAGMA user_version", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(v, SCHEMA_VERSION, "fresh init must stamp the schema version");
+
+        // Re-running on an already-current DB is a no-op that preserves data and
+        // leaves the version untouched (the probe block is skipped).
+        conn.execute(
+            "INSERT INTO entities (id, category, key, body_json, created_at_unix_ms, last_accessed_unix_ms)
+             VALUES ('v-test', 'insight', 'k', '{}', 0, 0)",
+            [],
+        )
+        .unwrap();
+        initialize_schema(&conn).expect("re-init should be a no-op");
+        let v2: i64 = conn
+            .query_row("PRAGMA user_version", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(v2, SCHEMA_VERSION);
+        let count: i64 = conn
+            .query_row("SELECT COUNT(*) FROM entities WHERE id='v-test'", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(count, 1, "re-init must not drop data");
+    }
+
+    #[test]
+    fn migrates_pre_versioned_db_missing_a_column() {
+        // Simulate a legacy DB at user_version=0 that predates the visibility
+        // column: the gate must still run the probes and add the column, then
+        // stamp the version so later opens skip.
+        let (conn, _path) = temp_db();
+        // Base v0.2.0 columns the DDL's indexes reference, but WITHOUT the
+        // later ALTER-added columns (embedding/always_on/certainty/
+        // workspace_hash/agent_id/visibility, journal agent_id/audit_hash).
+        conn.execute_batch(
+            "CREATE TABLE entities (
+                id TEXT PRIMARY KEY, category TEXT NOT NULL DEFAULT 'general', key TEXT NOT NULL,
+                body_json TEXT NOT NULL DEFAULT '{}', archived INTEGER DEFAULT 0,
+                retrieval_count INTEGER DEFAULT 0,
+                created_at_unix_ms INTEGER NOT NULL, last_accessed_unix_ms INTEGER NOT NULL
+             );
+             CREATE TABLE journal (
+                id TEXT PRIMARY KEY, entity_id TEXT DEFAULT '',
+                created_at_unix_ms INTEGER NOT NULL
+             );",
+        )
+        .unwrap();
+        assert!(
+            conn.prepare("SELECT visibility FROM entities LIMIT 1").is_err(),
+            "precondition: legacy table lacks visibility"
+        );
+
+        initialize_schema(&conn).expect("migrate legacy db");
+
+        assert!(
+            conn.prepare("SELECT visibility FROM entities LIMIT 1").is_ok(),
+            "visibility column must be added during gated migration"
+        );
+        let v: i64 = conn
+            .query_row("PRAGMA user_version", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(v, SCHEMA_VERSION);
+    }
+
     #[test]
     fn creates_recall_ranking_index() {
         let (conn, _path) = temp_db();