Skip to main content

khive_db/
migrations.rs

1//! Schema migration system for the SQLite storage layer.
2//!
3//! Two APIs coexist:
4//! - **Legacy per-service migrations** (`ServiceSchemaPlan` / `apply_schema_plan`):
5//!   used by pack-scoped schemas.
6//! - **Versioned migrations** (`MIGRATIONS` / `run_migrations`): the forward-only
7//!   migration pipeline for the core tables.
8//!
9//! Raw migration entry points require a connection opened by rusqlite;
10//! externally owned handles wrapped with `Connection::from_handle` are not
11//! supported. They reject inherited transactions. If rollback and close cannot
12//! establish an outcome, the original connection is retired before its volume
13//! lease is released and the caller receives `WriterSettlementUnknown`.
14
15use khive_storage::blob::ContentRef;
16use rusqlite::{Connection, OptionalExtension};
17use std::path::{Path, PathBuf};
18
19use crate::error::SqliteError;
20use crate::pool::WriteAdmission;
21use crate::stores::blob::{try_acquire_database_gc_owner_for_path, DatabaseGcOwnerGuard};
22
23#[path = "raw_migration_settlement.rs"]
24mod raw_migration_settlement;
25use raw_migration_settlement::{RawMigrationTransactions, RawMigrationWriteUnit};
26
27/// The write side of a migration run.
28///
29/// ADR-154 section 4 admits each migration transaction on its own: the volume
30/// lease is taken before the transaction begins and released once it has
31/// settled, so a multi-version upgrade never holds the volume for the whole
32/// run. Implementations own that per-call lease and settlement.
33pub(crate) trait MigrationTransactions {
34    /// Run one write transaction, or one autocommit write, under a fresh
35    /// admission.
36    fn admitted<T>(
37        &mut self,
38        operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
39    ) -> Result<T, SqliteError>;
40}
41
42/// Captured disk-guard settings and shared volume-lock directory for a SQLite
43/// writer.
44///
45/// Construction validates configuration without reading or writing a database.
46/// Cooperating callers must choose the same absolute volume-lock directory.
47#[derive(Clone, Debug)]
48pub struct MigrationWritePolicy {
49    disk_guard: crate::EffectiveDiskGuardConfig,
50    volume_lock_dir: PathBuf,
51}
52
53impl MigrationWritePolicy {
54    pub fn new(
55        disk_guard: crate::EffectiveDiskGuardConfig,
56        volume_lock_dir: impl Into<PathBuf>,
57    ) -> Result<Self, SqliteError> {
58        disk_guard.validate()?;
59        let volume_lock_dir = volume_lock_dir.into();
60        if !volume_lock_dir.is_absolute() {
61            return Err(SqliteError::InvalidConfig(
62                "migration volume-lock directory must be absolute".to_string(),
63            ));
64        }
65        Ok(Self {
66            disk_guard,
67            volume_lock_dir,
68        })
69    }
70
71    /// Resolve both settings from the process environment. The lock directory
72    /// follows [`crate::default_volume_lock_dir`], the same per-user default the
73    /// public SQLite constructors use.
74    pub fn from_environment() -> Result<Self, SqliteError> {
75        let disk_guard = crate::DiskGuardEnvironment::capture().resolve(None, None)?;
76        Self::new(disk_guard, crate::default_volume_lock_dir()?)
77    }
78
79    pub fn disk_guard_config(&self) -> crate::EffectiveDiskGuardConfig {
80        self.disk_guard
81    }
82
83    pub fn volume_lock_dir(&self) -> &Path {
84        &self.volume_lock_dir
85    }
86}
87
88#[path = "session_identity_migration.rs"]
89mod session_identity_migration;
90
91mod memory_visibility;
92
93// =============================================================================
94// Legacy per-service migration API (preserved for backward compatibility)
95// =============================================================================
96
97/// A single legacy migration step within a `ServiceSchemaPlan`.
98pub struct Migration {
99    /// Unique identifier for this migration.
100    pub id: &'static str,
101    /// SQL to apply (forward direction).
102    pub up_sql: &'static str,
103    /// SQL to revert (optional).
104    pub down_sql: Option<&'static str>,
105    /// Optional read-only predicate: returns true if migration was already
106    /// applied through a mechanism other than the migration tracker. It runs
107    /// while this connection holds the SQLite write lock.
108    pub is_already_applied: Option<fn(&Connection) -> bool>,
109}
110
111/// A pack-scoped schema plan containing migrations for SQLite and Postgres.
112pub struct ServiceSchemaPlan {
113    /// Service name used as a key in the `_schema_versions` tracking table.
114    pub service: &'static str,
115    /// SQLite-specific migration steps, applied in order.
116    pub sqlite: &'static [Migration],
117    /// Postgres-specific migration steps (reserved for future use).
118    pub postgres: &'static [Migration],
119}
120
121const SCHEMA_VERSION_TABLE: &str = include_str!("../sql/schema-version-table.sql");
122
123/// Apply a pack-scoped schema plan, tracking each migration in `_schema_versions`.
124/// A mutable connection lets the wrapper retire an unsettled original handle.
125pub fn apply_schema_plan(
126    conn: &mut Connection,
127    plan: &ServiceSchemaPlan,
128) -> Result<(), SqliteError> {
129    let admission = WriteAdmission::for_canonical_path(canonical_connection_database_path(conn)?)?;
130    apply_schema_plan_with_admission(
131        &mut RawMigrationTransactions::new(conn, &admission),
132        plan,
133        &admission,
134    )
135}
136
137/// Apply a raw connection's schema plan with a captured policy and lock path.
138pub fn apply_schema_plan_with_policy(
139    conn: &mut Connection,
140    plan: &ServiceSchemaPlan,
141    policy: &MigrationWritePolicy,
142) -> Result<(), SqliteError> {
143    let admission =
144        WriteAdmission::for_migration_policy(canonical_connection_database_path(conn)?, policy)?;
145    apply_schema_plan_with_admission(
146        &mut RawMigrationTransactions::new(conn, &admission),
147        plan,
148        &admission,
149    )
150}
151
152/// Apply a service schema plan. The tracking-table bootstrap and each
153/// migration are separate admitted write units (ADR-154 section 4).
154pub(crate) fn apply_schema_plan_with_admission(
155    writes: &mut impl MigrationTransactions,
156    plan: &ServiceSchemaPlan,
157    admission: &WriteAdmission,
158) -> Result<(), SqliteError> {
159    writes.admitted(|conn| {
160        admission.check()?;
161        conn.execute_batch(SCHEMA_VERSION_TABLE)?;
162        require_autocommit(conn, "schema-version bootstrap")
163    })?;
164
165    for migration in plan.sqlite {
166        writes.admitted(|conn| apply_service_migration(conn, plan, migration, admission))?;
167    }
168
169    Ok(())
170}
171
172/// Apply one service migration in its own IMMEDIATE transaction unless its
173/// predicate or the ledger says it has already been applied.
174fn apply_service_migration(
175    conn: &Connection,
176    plan: &ServiceSchemaPlan,
177    migration: &Migration,
178    admission: &WriteAdmission,
179) -> Result<(), SqliteError> {
180    // Serialize the admission decision with other writers. Checking the
181    // predicate or ledger before BEGIN IMMEDIATE lets a second opener see
182    // stale state and replay a migration after the first one commits.
183    let tx = rusqlite::Transaction::new_unchecked(conn, rusqlite::TransactionBehavior::Immediate)?;
184    if let Err(error) = admission.check() {
185        let rollback = tx.rollback();
186        return Err(capacity_refusal_after_rollback(
187            conn,
188            rollback,
189            error,
190            "service schema migration",
191        ));
192    }
193
194    // Check if custom predicate says it's already applied
195    if let Some(check) = migration.is_already_applied {
196        if check(&tx) {
197            return Ok(());
198        }
199    }
200
201    // Check if tracked as applied
202    let already: bool = tx.query_row(
203        "SELECT COUNT(*) > 0 FROM _schema_versions WHERE service = ?1 AND migration_id = ?2",
204        rusqlite::params![plan.service, migration.id],
205        |row| row.get(0),
206    )?;
207
208    if already {
209        return Ok(());
210    }
211
212    tx.execute_batch(migration.up_sql)?;
213
214    tx.execute(
215        "INSERT INTO _schema_versions (service, migration_id, applied_at) VALUES (?1, ?2, ?3)",
216        rusqlite::params![
217            plan.service,
218            migration.id,
219            chrono::Utc::now().timestamp_micros(),
220        ],
221    )?;
222    tx.commit()?;
223    Ok(())
224}
225
226fn require_autocommit(conn: &Connection, operation: &str) -> Result<(), SqliteError> {
227    if conn.is_autocommit() {
228        Ok(())
229    } else {
230        Err(SqliteError::InvalidData(format!(
231            "{operation} did not return the SQLite connection to autocommit"
232        )))
233    }
234}
235
236pub(crate) fn capacity_refusal_after_rollback(
237    conn: &Connection,
238    rollback: rusqlite::Result<()>,
239    refusal: SqliteError,
240    operation: &str,
241) -> SqliteError {
242    if let Err(error) = rollback {
243        return SqliteError::InvalidData(format!(
244            "{operation} capacity refusal could not roll back: {error}; \
245             initial refusal: {refusal}"
246        ));
247    }
248    if !conn.is_autocommit() {
249        return SqliteError::InvalidData(format!(
250            "{operation} capacity refusal rolled back without restoring autocommit; \
251             initial refusal: {refusal}"
252        ));
253    }
254    refusal
255}
256
257// =============================================================================
258// Versioned migration system
259// =============================================================================
260
261/// A single forward-only schema migration.
262///
263/// Migrations are applied in order from the current DB version to the target
264/// version. Each migration runs in its own transaction; a failure rolls back
265/// that migration and leaves the DB at the prior version.
266pub struct VersionedMigration {
267    /// Monotonically increasing version number, starting at 1.
268    pub version: u32,
269    /// Short human-readable name for the migration (used in the audit table).
270    pub name: &'static str,
271    /// SQL to apply this migration. May contain multiple statements separated
272    /// by semicolons; `execute_batch` runs them all.
273    pub up: &'static str,
274}
275
276// V1: complete schema, loaded from sql/schema.sql.
277// Fresh-start repo (v0.2.8) — all schema in one migration, no incremental versions.
278const V1_UP: &str = include_str!("../sql/schema.sql");
279
280const V2_UP: &str = include_str!("../sql/002-narrow-fts-sections-update-trigger.sql");
281
282const V3_UP: &str = include_str!("../sql/003-backfill-domain-mirror-atoms.sql");
283
284const V4_UP: &str = include_str!("../sql/004-fts-consolidation.sql");
285
286const V5_UP: &str = include_str!("../sql/005-unique-comm-external-id.sql");
287
288const V6_UP: &str = include_str!("../sql/006-brain-retune-driver.sql");
289
290const V7_UP: &str = include_str!("../sql/007-notes-seq.sql");
291
292const V8_UP: &str = include_str!("../sql/008-notes-seq-repair.sql");
293
294const V9_UP: &str = include_str!("../sql/009-entities-name-ci-index.sql");
295
296const V10_UP: &str = include_str!("../sql/010-entities-content-ref.sql");
297
298const V11_UP: &str = include_str!("../sql/011-ann-write-log.sql");
299
300const V12_UP: &str = include_str!("../sql/012-ann-write-log-model-seq-index.sql");
301
302const V13_UP: &str = include_str!("../sql/013-list-cursor-sequences.sql");
303
304const V14_UP: &str = include_str!("../sql/014-graph-edges-id-unique.sql");
305
306const V15_UP: &str = include_str!("../sql/015-serve-ledger-attribution.sql");
307
308const V16_UP: &str = include_str!("../sql/016-gtd-dependency-cycle-guards.sql");
309
310const V17_UP: &str = include_str!("../sql/017-agents-ddl.sql");
311
312const V18_UP: &str = include_str!("../sql/018-ann-consumer-pending.sql");
313
314const V19_UP: &str = include_str!("../sql/019-list-cursor-backfill-repair.sql");
315
316const V20_UP: &str = include_str!("../sql/020-blob-gc-claims.sql");
317
318const V22_UP: &str = include_str!("../sql/022-notes-unread-probe-recipient.sql");
319
320const V23_UP: &str = include_str!("../sql/023-fts-record-kind.sql");
321
322const V24_UP: &str = include_str!("../sql/024-fts-rowid-map.sql");
323
324const V25_UP: &str = include_str!("../sql/025-notes-unread-probe-recipient-direction.sql");
325
326const V26_UP: &str = include_str!("../sql/026-knowledge-fts-repair.sql");
327
328const V27_UP: &str = include_str!("../sql/027-notes-hot-property-indexes.sql");
329const V28_UP: &str = include_str!("../sql/028-notes-key.sql");
330
331const V29_UP: &str = include_str!("../sql/029-note-streams.sql");
332const V30_UP: &str = include_str!("../sql/030-tool-source-mounts.sql");
333const V31_UP: &str = include_str!("../sql/031-note-versions.sql");
334const V32_UP: &str = include_str!("../sql/032-knowledge-count-indexes.sql");
335const V33_UP: &str = include_str!("../sql/033-notes-message-recipient-direction.sql");
336const V34_UP: &str = include_str!("../sql/034-notes-namespace-created.sql");
337const V35_UP: &str = include_str!("../sql/035-notes-unread-probe-recipient-type-direction.sql");
338const V36_UP: &str = include_str!("../sql/036-events-operation-attribution.sql");
339const V37_UP: &str = include_str!("../sql/037-entity-versions.sql");
340const V38_UP: &str = include_str!("../sql/038-entities-legacy-type-index.sql");
341const V39_UP: &str = include_str!("../sql/039-knowledge-cursor-indexes.sql");
342const SESSION_IDENTITY_UP: &str = include_str!("../sql/040-session-source-scope.sql");
343const SESSION_IDENTITY_MIGRATION_NAME: &str = "session_source_scoped_identity";
344const V41_UP: &str = include_str!("../sql/041-sender-transport.sql");
345const V42_UP: &str = include_str!("../sql/042-comm-external-id-channel-scope.sql");
346const V43_UP: &str = include_str!("../sql/043-vector-provenance.sql");
347const V44_COLUMNS: &str = include_str!("../sql/044-comm-outbound-due-a-columns.sql");
348const V44_UP: &str = include_str!("../sql/044-comm-outbound-due-b-index.sql");
349
350/// V44 may follow a direct-store bootstrap, whose idempotent notes DDL
351/// already supplies the two columns. Backfill before building the index so
352/// existing future retries are excluded by its deadline range immediately.
353pub(crate) fn migrate_outbound_due_key(tx: &rusqlite::Transaction<'_>) -> rusqlite::Result<()> {
354    let has_column = |name: &str| -> rusqlite::Result<bool> {
355        tx.query_row(
356            "SELECT EXISTS(SELECT 1 FROM pragma_table_info('notes') WHERE name = ?1)",
357            [name],
358            |row| row.get(0),
359        )
360    };
361    match (has_column("strict_due_key")?, has_column("due_source")?) {
362        (false, false) => tx.execute_batch(V44_COLUMNS)?,
363        (true, true) => {}
364        _ => return Err(rusqlite::Error::InvalidQuery),
365    }
366
367    let mut after_id = String::new();
368    let mut first_page = true;
369    loop {
370        let rows: Vec<(String, String)> = {
371            let comparator = if first_page { ">=" } else { ">" };
372            let mut stmt = tx.prepare(&format!(
373                "SELECT id, json_extract(properties, '$.next_attempt_at') FROM notes \
374                 WHERE id {comparator} ?1 AND json_type(properties, '$.next_attempt_at') = 'text' \
375                 ORDER BY id LIMIT 500"
376            ))?;
377            let collected = stmt
378                .query_map([&after_id], |row| Ok((row.get(0)?, row.get(1)?)))?
379                .collect::<rusqlite::Result<_>>()?;
380            collected
381        };
382        if rows.is_empty() {
383            break;
384        }
385        after_id = rows.last().expect("nonempty V44 page").0.clone();
386        first_page = false;
387        for (id, source) in rows {
388            if let Some(key) = crate::pool::strict_rfc3339_key(&source) {
389                tx.execute(
390                    "UPDATE notes SET strict_due_key = ?1, due_source = ?2 \
391                     WHERE id = ?3 AND (strict_due_key IS NOT ?1 OR due_source IS NOT ?2)",
392                    rusqlite::params![key, source, id],
393                )?;
394            }
395        }
396    }
397    tx.execute_batch(V44_UP)
398}
399
400const RECIPIENT_TRANSPORT_VERSION: u32 = 45;
401const V45_UP: &str = include_str!("../sql/045-recipient-transport.sql");
402const V46_UP: &str = include_str!("../sql/046-memory-visibility-receipts.sql");
403const V47_UP: &str = include_str!("../sql/047-attachment-role-quarantine.sql");
404const V49_UP: &str = include_str!("../sql/049-git-note-property-indexes.sql");
405
406const V50_UP: &str = include_str!("../sql/050-entity-list-plans.sql");
407const V51_UP: &str = include_str!("../sql/051-schedule-core-indexes.sql");
408const V52_UP: &str = include_str!("../sql/052-comm-core-indexes.sql");
409const V53_UP: &str = include_str!("../sql/053-entity-kind-list-order.sql");
410const MEMORY_VISIBILITY_CUTOVER_VERSION: u32 = 54;
411const V54_UP: &str = include_str!("../sql/054-memory-visibility-epochs.sql");
412
413const V55_UP: &str = include_str!("../sql/055-knowledge-cursor-domain-tags.sql");
414const V56_UP: &str = include_str!("../sql/056-atom-weights.sql");
415const V57_UP: &str = include_str!("../sql/057-retrieval-snapshots.sql");
416const V58_UP: &str = include_str!("../sql/058-proposal-archive.sql");
417const V59_UP: &str = include_str!("../sql/059-comm-legacy-quarantine-index.sql");
418const V60_UP: &str = include_str!("../sql/060-note-stream-truncation.sql");
419const V61_UP: &str = include_str!("../sql/061-edge-governance.sql");
420const V62_UP: &str = include_str!("../sql/062-authority-store.sql");
421const V63_UP: &str = include_str!("../sql/063-pending-entity-indexes.sql");
422const V64_UP: &str = include_str!("../sql/064-node-confirmed-pins.sql");
423const V65_UP: &str = include_str!("../sql/065-graph-edges-target-relation-index.sql");
424const V66_UP: &str = include_str!("../sql/066-comm-undelivered-due-index.sql");
425
426/// Retained V66 schema needs only its ledger restored, not an index rebuild.
427fn migrate_undelivered_due_index(tx: &rusqlite::Transaction<'_>) -> rusqlite::Result<()> {
428    let installed: Option<String> = tx
429        .query_row(
430            include_str!("../sql/comm-outbound-due-index-definition.sql"),
431            [],
432            |row| row.get(0),
433        )
434        .optional()?;
435    let (_, create) = V66_UP
436        .split_once("CREATE INDEX")
437        .ok_or(rusqlite::Error::InvalidQuery)?;
438    let expected = format!("CREATE INDEX{create}");
439    // SQLite omits the terminal semicolon. Preserve every interior byte,
440    // including whitespace in SQL string literals, when comparing definitions.
441    if installed.as_deref().is_some_and(|sql| {
442        sql.trim().trim_end_matches(';') == expected.trim().trim_end_matches(';')
443    }) {
444        return Ok(());
445    }
446    tx.execute_batch(V66_UP)
447}
448
449// Ledger-tail replay may retain the physical column; accept only its exact shape.
450fn migrate_proposal_archive(tx: &rusqlite::Transaction<'_>) -> Result<(), SqliteError> {
451    let migration_error = |error: rusqlite::Error| {
452        SqliteError::migration_with_cause(
453            58,
454            format!("proposals_open.archived_at migration failed: {error}"),
455            error,
456        )
457    };
458    let column = tx
459        .query_row(
460            include_str!("../sql/proposal-archive-column.sql"),
461            [],
462            |row| {
463                Ok((
464                    row.get::<_, String>(0)?,
465                    row.get::<_, i64>(1)?,
466                    row.get::<_, Option<String>>(2)?,
467                    row.get::<_, i64>(3)?,
468                    row.get::<_, i64>(4)?,
469                ))
470            },
471        )
472        .optional()
473        .map_err(migration_error)?;
474    match column {
475        None => tx.execute_batch(V58_UP).map_err(migration_error),
476        Some((declared_type, not_null, default, primary_key, hidden))
477            if declared_type.eq_ignore_ascii_case("INTEGER")
478                && not_null == 0
479                && default.is_none()
480                && primary_key == 0
481                && hidden == 0 =>
482        {
483            Ok(())
484        }
485        Some(_) => Err(SqliteError::migration_message(
486            58,
487            "incompatible proposals_open.archived_at: expected an ordinary nullable INTEGER column without a default or primary key",
488        )),
489    }
490}
491
492const V48_UP: &str = include_str!("../sql/048-acknowledgement-journal-a-table.sql");
493const ACKNOWLEDGEMENT_JOURNAL_INDEX: &str =
494    include_str!("../sql/048-acknowledgement-journal-b-index.sql");
495
496/// A ledger-tail replay keeps already-current journal state and retry metadata.
497pub(crate) fn migrate_acknowledgement_journal(
498    tx: &rusqlite::Transaction<'_>,
499) -> rusqlite::Result<()> {
500    let columns: i64 = tx.query_row(
501        "SELECT count(*) FROM pragma_table_info('comm_ack_work') \
502         WHERE name IN ('attempt_count','not_before','retirement_reason')",
503        [],
504        |row| row.get(0),
505    )?;
506    match columns {
507        0 => tx.execute_batch(V48_UP)?,
508        3 => {}
509        _ => return Err(rusqlite::Error::InvalidQuery),
510    }
511    tx.execute_batch(ACKNOWLEDGEMENT_JOURNAL_INDEX)
512}
513
514const V21_STAGE_UP: &str = include_str!("../sql/021-attachments-a-stage.sql");
515
516const V21_ATTACHMENT_FENCES_UP: &str = include_str!("../sql/021-attachments-b-claim-fences.sql");
517
518/// Core schema version reserved for ADR-121's attachments-first cutover.
519pub const ATTACHMENT_CUTOVER_VERSION: u32 = 21;
520
521/// The latest schema version this build's migration chain produces.
522///
523/// Terminal-version assertions belong on this, not on a hardcoded number:
524/// a literal decays into a wrong claim the next time a migration is added.
525pub fn latest_schema_version() -> u32 {
526    MIGRATIONS.last().map(|m| m.version).unwrap_or(0)
527}
528
529/// DDL for the `ann_write_log` delta table.
530///
531/// Shared between migration V11 and the belt-and-suspenders creation in
532/// `StorageBackend::vectors_for_namespace` (same pattern as
533/// [`EMBEDDING_MODELS_DDL`]): every database that hosts `vec_*` tables must
534/// also have the write log, or vector writes would fail on databases opened
535/// without `run_migrations()`. The `.sql` file is `IF NOT EXISTS`-idempotent.
536pub const ANN_WRITE_LOG_DDL: &str = V11_UP;
537
538/// DDL for the `ann_write_log` model/kind/field-leading index (ADR-118 §"Cost
539/// bound"), shared between migration V12 and the belt-and-suspenders creation
540/// in `StorageBackend::vectors_for_namespace` for the same reason as
541/// [`ANN_WRITE_LOG_DDL`].
542pub const ANN_WRITE_LOG_MODEL_SEQ_INDEX_DDL: &str = V12_UP;
543
544/// Idempotent DDL for pending ANN-consumer lifecycle metadata (#1479).
545///
546/// The V18 migration additionally translates legacy zero-watermark rows once.
547/// This constant deliberately contains only idempotent DDL: vector-store open
548/// paths may execute it repeatedly and must never demote a valid active
549/// checkpoint at sequence zero back to pending.
550pub const ANN_CONSUMER_PENDING_DDL: &str = include_str!("../sql/ann-consumer-pending-ddl.sql");
551
552/// Sidecar DDL registered in the migration ledger. Direct vector-store
553/// construction leaves this schema to the versioned migration.
554pub const VECTOR_PROVENANCE_DDL: &str = V43_UP;
555
556/// DDL for the `_embedding_models` registry table.
557///
558/// Shared between the V1 schema and the belt-and-suspenders creation in
559/// `StorageBackend::vectors_for_namespace`. Both sites reference this constant so
560/// the schema cannot silently diverge if the registry evolves.
561pub const EMBEDDING_MODELS_DDL: &str = include_str!("../sql/embedding-models-ddl.sql");
562
563/// Canonical versioned migration ledger in ascending order.
564///
565/// [`run_migrations`] applies the ordinary prefix and may complete V21 through
566/// its zero-legacy-reference fast path. A legacy V20 database records V21 only
567/// when [`finalize_attachment_cutover`] commits the application-assisted
568/// cutover.
569pub const MIGRATIONS: &[VersionedMigration] = &[
570    VersionedMigration {
571        version: 1,
572        name: "initial_schema",
573        up: V1_UP,
574    },
575    VersionedMigration {
576        version: 2,
577        name: "narrow_fts_sections_update_trigger",
578        up: V2_UP,
579    },
580    VersionedMigration {
581        version: 3,
582        name: "backfill_domain_mirror_atoms",
583        up: V3_UP,
584    },
585    VersionedMigration {
586        version: 4,
587        name: "fts_consolidation",
588        up: V4_UP,
589    },
590    VersionedMigration {
591        version: 5,
592        name: "unique_comm_message_external_id",
593        up: V5_UP,
594    },
595    VersionedMigration {
596        version: 6,
597        name: "brain_retune_driver",
598        up: V6_UP,
599    },
600    VersionedMigration {
601        version: 7,
602        name: "notes_seq",
603        up: V7_UP,
604    },
605    VersionedMigration {
606        version: 8,
607        name: "notes_seq_repair",
608        up: V8_UP,
609    },
610    VersionedMigration {
611        version: 9,
612        name: "entities_name_ci_index",
613        up: V9_UP,
614    },
615    VersionedMigration {
616        version: 10,
617        name: "entities_content_ref",
618        up: V10_UP,
619    },
620    VersionedMigration {
621        version: 11,
622        name: "ann_write_log",
623        up: V11_UP,
624    },
625    VersionedMigration {
626        version: 12,
627        name: "ann_write_log_model_seq_index",
628        up: V12_UP,
629    },
630    VersionedMigration {
631        version: 13,
632        name: "list_cursor_sequences",
633        up: V13_UP,
634    },
635    VersionedMigration {
636        version: 14,
637        name: "graph_edges_id_unique",
638        up: V14_UP,
639    },
640    VersionedMigration {
641        version: 15,
642        name: "serve_ledger_attribution",
643        up: V15_UP,
644    },
645    VersionedMigration {
646        version: 16,
647        name: "gtd_dependency_cycle_guards",
648        up: V16_UP,
649    },
650    VersionedMigration {
651        version: 17,
652        name: "agents_ddl",
653        up: V17_UP,
654    },
655    VersionedMigration {
656        version: 18,
657        name: "ann_consumer_pending",
658        up: V18_UP,
659    },
660    VersionedMigration {
661        version: 19,
662        name: "list_cursor_backfill_repair",
663        up: V19_UP,
664    },
665    VersionedMigration {
666        version: 20,
667        name: "blob_gc_claims",
668        up: V20_UP,
669    },
670    VersionedMigration {
671        version: ATTACHMENT_CUTOVER_VERSION,
672        name: "attachments_first_class",
673        // V21 is coordinated rather than an unconditional SQL migration.
674        // The runner special-cases it below; exposing the stage DDL here keeps
675        // the ledger entry self-describing for migration inspection tooling.
676        up: V21_STAGE_UP,
677    },
678    VersionedMigration {
679        version: 22,
680        name: "notes_unread_probe_recipient",
681        up: V22_UP,
682    },
683    VersionedMigration {
684        version: 23,
685        name: "fts_record_kind",
686        up: V23_UP,
687    },
688    VersionedMigration {
689        version: 24,
690        name: "fts_rowid_map",
691        up: V24_UP,
692    },
693    VersionedMigration {
694        version: 25,
695        name: "notes_unread_probe_recipient_direction",
696        up: V25_UP,
697    },
698    VersionedMigration {
699        version: 26,
700        name: "knowledge_fts_repair",
701        up: V26_UP,
702    },
703    VersionedMigration {
704        version: 27,
705        name: "notes_hot_property_indexes",
706        up: V27_UP,
707    },
708    VersionedMigration {
709        version: 28,
710        name: "notes_key",
711        up: V28_UP,
712    },
713    VersionedMigration {
714        version: 29,
715        name: "note_streams",
716        up: V29_UP,
717    },
718    VersionedMigration {
719        version: 30,
720        name: "tool_source_mounts",
721        up: V30_UP,
722    },
723    VersionedMigration {
724        version: 31,
725        name: "note_versions",
726        up: V31_UP,
727    },
728    VersionedMigration {
729        version: 32,
730        name: "knowledge_count_indexes",
731        up: V32_UP,
732    },
733    VersionedMigration {
734        version: 33,
735        name: "notes_message_recipient_direction",
736        up: V33_UP,
737    },
738    VersionedMigration {
739        version: 34,
740        name: "notes_namespace_created",
741        up: V34_UP,
742    },
743    VersionedMigration {
744        version: 35,
745        name: "notes_unread_probe_recipient_type_direction",
746        up: V35_UP,
747    },
748    VersionedMigration {
749        version: 36,
750        name: "events_operation_attribution",
751        up: V36_UP,
752    },
753    VersionedMigration {
754        version: 37,
755        name: "entity_versions",
756        up: V37_UP,
757    },
758    VersionedMigration {
759        version: 38,
760        name: "entities_legacy_type_index",
761        up: V38_UP,
762    },
763    VersionedMigration {
764        version: 39,
765        name: "knowledge_cursor_indexes",
766        up: V39_UP,
767    },
768    VersionedMigration {
769        version: 40,
770        name: SESSION_IDENTITY_MIGRATION_NAME,
771        up: SESSION_IDENTITY_UP,
772    },
773    VersionedMigration {
774        version: 41,
775        name: "sender_transport",
776        up: V41_UP,
777    },
778    VersionedMigration {
779        version: 42,
780        name: "comm_external_id_channel_scope",
781        up: V42_UP,
782    },
783    VersionedMigration {
784        version: 43,
785        name: "vector_provenance",
786        up: V43_UP,
787    },
788    VersionedMigration {
789        version: 44,
790        name: "comm_outbound_due",
791        up: V44_UP,
792    },
793    VersionedMigration {
794        version: RECIPIENT_TRANSPORT_VERSION,
795        name: "recipient_transport",
796        up: V45_UP,
797    },
798    VersionedMigration {
799        version: 46,
800        name: "memory_visibility_receipts",
801        up: V46_UP,
802    },
803    VersionedMigration {
804        version: 47,
805        name: "attachment_role_quarantine",
806        up: V47_UP,
807    },
808    VersionedMigration {
809        version: 48,
810        name: "acknowledgement_journal",
811        up: V48_UP,
812    },
813    VersionedMigration {
814        version: 49,
815        name: "git_note_property_indexes",
816        up: V49_UP,
817    },
818    VersionedMigration {
819        version: 50,
820        name: "entity_list_plans",
821        up: V50_UP,
822    },
823    VersionedMigration {
824        version: 51,
825        name: "schedule_core_indexes",
826        up: V51_UP,
827    },
828    VersionedMigration {
829        version: 52,
830        name: "comm_core_indexes",
831        up: V52_UP,
832    },
833    VersionedMigration {
834        version: 53,
835        name: "entity_kind_list_order",
836        up: V53_UP,
837    },
838    VersionedMigration {
839        version: MEMORY_VISIBILITY_CUTOVER_VERSION,
840        name: "memory_visibility_epochs",
841        up: V54_UP,
842    },
843    VersionedMigration {
844        version: 55,
845        name: "knowledge_atom_cursor_all_live_tags",
846        up: V55_UP,
847    },
848    VersionedMigration {
849        version: 56,
850        name: "atom_weight_tables",
851        up: V56_UP,
852    },
853    VersionedMigration {
854        version: 57,
855        name: "retrieval_snapshot_tables",
856        up: V57_UP,
857    },
858    VersionedMigration {
859        version: 58,
860        name: "proposal_archive",
861        up: V58_UP,
862    },
863    VersionedMigration {
864        version: 59,
865        name: "comm_legacy_quarantine_index",
866        up: V59_UP,
867    },
868    VersionedMigration {
869        version: 60,
870        name: "note_stream_truncation",
871        up: V60_UP,
872    },
873    VersionedMigration {
874        version: 61,
875        name: "edge_governance",
876        up: V61_UP,
877    },
878    VersionedMigration {
879        version: 62,
880        name: "authority_store",
881        up: V62_UP,
882    },
883    VersionedMigration {
884        version: 63,
885        name: "pending_entity_indexes",
886        up: V63_UP,
887    },
888    VersionedMigration {
889        version: 64,
890        name: "node_confirmed_pins",
891        up: V64_UP,
892    },
893    VersionedMigration {
894        version: 65,
895        name: "graph_edges_target_relation_index",
896        up: V65_UP,
897    },
898    VersionedMigration {
899        version: 66,
900        name: "comm_undelivered_due_index",
901        up: V66_UP,
902    },
903];
904
905/// Durable state of ADR-121's boot-gated, two-stage attachment cutover.
906#[derive(Clone, Copy, Debug, Eq, PartialEq)]
907pub enum AttachmentCutoverStatus {
908    /// V20 is current and no stage marker has been committed.
909    Pending,
910    /// Stage 1 committed; boot must finish verified pack-owned attachments.
911    Incomplete,
912    /// V21, the attachment fences, and the attachment-only schema committed.
913    Complete,
914}
915
916fn schema_object_exists(
917    conn: &Connection,
918    object_type: &str,
919    name: &str,
920) -> Result<bool, SqliteError> {
921    conn.query_row(
922        "SELECT COUNT(*) > 0 FROM sqlite_master WHERE type = ?1 AND name = ?2",
923        rusqlite::params![object_type, name],
924        |row| row.get(0),
925    )
926    .map_err(Into::into)
927}
928
929fn schema_column_exists(conn: &Connection, table: &str, column: &str) -> Result<bool, SqliteError> {
930    conn.query_row(
931        "SELECT COUNT(*) > 0 FROM pragma_table_info(?1) WHERE name = ?2",
932        rusqlite::params![table, column],
933        |row| row.get(0),
934    )
935    .map_err(Into::into)
936}
937
938fn require_attachment_schema_objects(
939    conn: &Connection,
940    objects: &[(&str, &str)],
941    phase: &str,
942) -> Result<(), SqliteError> {
943    for (object_type, name) in objects {
944        if !schema_object_exists(conn, object_type, name)? {
945            return Err(SqliteError::InvalidData(format!(
946                "attachment cutover {phase} state is missing {object_type} {name:?}"
947            )));
948        }
949    }
950    Ok(())
951}
952
953fn validate_incomplete_attachment_schema(conn: &Connection) -> Result<(), SqliteError> {
954    require_attachment_schema_objects(
955        conn,
956        &[
957            ("table", "attachments"),
958            ("index", "idx_attachments_content_ref"),
959        ],
960        "incomplete",
961    )?;
962    require_legacy_attachment_fences(conn)
963}
964
965fn validate_complete_attachment_schema(conn: &Connection) -> Result<(), SqliteError> {
966    require_attachment_schema_objects(
967        conn,
968        &[
969            ("table", "attachments"),
970            ("table", "blob_gc_claims"),
971            ("index", "idx_attachments_content_ref"),
972            ("index", "idx_blob_gc_claims_content_ref"),
973            ("trigger", "attachments_reject_claimed_blob_insert"),
974            ("trigger", "attachments_reject_claimed_blob_update"),
975        ],
976        "complete",
977    )?;
978    if schema_column_exists(conn, "entities", "content_ref")? {
979        return Err(SqliteError::InvalidData(
980            "attachment cutover is complete but entities.content_ref still exists".into(),
981        ));
982    }
983    for (object_type, name) in [
984        ("index", "idx_entities_content_ref"),
985        ("trigger", "entities_reject_claimed_blob_insert"),
986        ("trigger", "entities_reject_claimed_blob_update"),
987    ] {
988        if schema_object_exists(conn, object_type, name)? {
989            return Err(SqliteError::InvalidData(format!(
990                "attachment cutover is complete but legacy {object_type} {name:?} still exists"
991            )));
992        }
993    }
994    Ok(())
995}
996
997/// Whether the migration chain would stop at [`ATTACHMENT_CUTOVER_VERSION`] and
998/// leave the store for the host's application-assisted cutover, read without
999/// mutating the connection.
1000///
1001/// `false` for a store already at or past the cutover version, since the chain
1002/// never reaches that step again. Below it, the answer is the chain's own
1003/// condition evaluated on the store as it is now: the cutover is `Incomplete`,
1004/// or an entity still holds a legacy `content_ref`. A store whose `entities`
1005/// table has no `content_ref` column yet (no table, or a store below V10) holds
1006/// no legacy reference. An impossible marker and ledger pair is an error, as it
1007/// is for the chain.
1008pub fn attachment_cutover_would_defer(conn: &Connection) -> Result<bool, SqliteError> {
1009    if read_schema_version(conn)? >= ATTACHMENT_CUTOVER_VERSION {
1010        return Ok(false);
1011    }
1012    cutover_defers(conn, attachment_cutover_status(conn)?)
1013}
1014
1015/// The V21 deferral condition, shared by the chain and
1016/// [`attachment_cutover_would_defer`] so there is one copy of it.
1017fn cutover_defers(conn: &Connection, status: AttachmentCutoverStatus) -> Result<bool, SqliteError> {
1018    let legacy_refs: i64 = if schema_column_exists(conn, "entities", "content_ref")? {
1019        conn.query_row(
1020            "SELECT COUNT(*) FROM entities WHERE content_ref IS NOT NULL",
1021            [],
1022            |row| row.get(0),
1023        )?
1024    } else {
1025        0
1026    };
1027    Ok(status == AttachmentCutoverStatus::Incomplete || legacy_refs != 0)
1028}
1029
1030/// Inspect the coordinated V21 state without mutating the connection.
1031///
1032/// The marker and migration ledger form one state machine. Impossible pairs
1033/// fail closed instead of being guessed into a resumable state.
1034pub fn attachment_cutover_status(
1035    conn: &Connection,
1036) -> Result<AttachmentCutoverStatus, SqliteError> {
1037    let version = read_schema_version(conn)?;
1038    let marker_table = schema_object_exists(conn, "table", "attachment_cutover_state")?;
1039    if !marker_table {
1040        if version >= ATTACHMENT_CUTOVER_VERSION {
1041            return Err(SqliteError::InvalidData(format!(
1042                "migration V{ATTACHMENT_CUTOVER_VERSION} is recorded but its attachment cutover marker is absent"
1043            )));
1044        }
1045        if schema_object_exists(conn, "table", "attachments")? {
1046            return Err(SqliteError::InvalidData(
1047                "attachments table exists without the durable attachment cutover marker".into(),
1048            ));
1049        }
1050        return Ok(AttachmentCutoverStatus::Pending);
1051    }
1052
1053    let marker: Option<(String, Option<i64>)> = conn
1054        .query_row(
1055            "SELECT state, completed_at FROM attachment_cutover_state WHERE singleton = 1",
1056            [],
1057            |row| Ok((row.get(0)?, row.get(1)?)),
1058        )
1059        .optional()?;
1060    match marker {
1061        Some((state, None)) if state == "incomplete" => {
1062            if version >= ATTACHMENT_CUTOVER_VERSION {
1063                Err(SqliteError::InvalidData(format!(
1064                    "attachment cutover is incomplete but migration V{ATTACHMENT_CUTOVER_VERSION} is already recorded"
1065                )))
1066            } else {
1067                validate_incomplete_attachment_schema(conn)?;
1068                Ok(AttachmentCutoverStatus::Incomplete)
1069            }
1070        }
1071        Some((state, Some(_))) if state == "complete" => {
1072            // Later migrations (V22+) are recorded on top of a completed
1073            // cutover in the normal course; only a ledger BELOW V21 beside a
1074            // complete marker is an impossible pair.
1075            if version >= ATTACHMENT_CUTOVER_VERSION {
1076                validate_complete_attachment_schema(conn)?;
1077                Ok(AttachmentCutoverStatus::Complete)
1078            } else {
1079                Err(SqliteError::InvalidData(format!(
1080                    "attachment cutover is complete but schema ledger is at V{version}, below V{ATTACHMENT_CUTOVER_VERSION}"
1081                )))
1082            }
1083        }
1084        Some((state, completed_at)) => Err(SqliteError::InvalidData(format!(
1085            "invalid attachment cutover marker state {state:?} with completed_at={completed_at:?}"
1086        ))),
1087        None => Err(SqliteError::InvalidData(
1088            "attachment cutover marker table exists without its singleton row".into(),
1089        )),
1090    }
1091}
1092
1093fn require_legacy_attachment_fences(conn: &Connection) -> Result<(), SqliteError> {
1094    if !schema_column_exists(conn, "entities", "content_ref")? {
1095        return Err(SqliteError::InvalidData(
1096            "attachment cutover requires legacy entities.content_ref until finalization".into(),
1097        ));
1098    }
1099    for (object_type, name) in [
1100        ("table", "blob_gc_claims"),
1101        ("index", "idx_blob_gc_claims_content_ref"),
1102        ("index", "idx_entities_content_ref"),
1103        ("trigger", "entities_reject_claimed_blob_insert"),
1104        ("trigger", "entities_reject_claimed_blob_update"),
1105    ] {
1106        if !schema_object_exists(conn, object_type, name)? {
1107            return Err(SqliteError::InvalidData(format!(
1108                "attachment cutover requires legacy {object_type} {name:?} until finalization"
1109            )));
1110        }
1111    }
1112    Ok(())
1113}
1114
1115// length() and GLOB both stop scanning at an embedded NUL, so a value of 64
1116// hex characters followed by a NUL and arbitrary trailing bytes would pass
1117// both. Deriving the canonical byte width from the connection's own text
1118// encoding (rather than assuming UTF-8) keeps this arm correct on a database
1119// pinned to UTF-16 and fails closed if the probe returns something else,
1120// matching the pattern already used by `validate_blob_gc_evidence`.
1121fn canonical_content_ref_byte_width(conn: &Connection) -> Result<i64, SqliteError> {
1122    let width: i64 = conn.query_row("SELECT length(CAST('x' AS BLOB))", [], |row| row.get(0))?;
1123    if !(1..=4).contains(&width) {
1124        return Err(SqliteError::InvalidData(format!(
1125            "the text-encoding width probe returned {width}; refusing canonicality validation"
1126        )));
1127    }
1128    Ok(width * 64)
1129}
1130
1131fn validate_canonical_legacy_refs(conn: &Connection) -> Result<(), SqliteError> {
1132    let canonical_bytes = canonical_content_ref_byte_width(conn)?;
1133    let invalid: Option<String> = conn
1134        .query_row(
1135            "SELECT id FROM entities \
1136             WHERE content_ref IS NOT NULL \
1137               AND (typeof(content_ref) <> 'text' \
1138                 OR length(content_ref) <> 64 \
1139                 OR length(CAST(content_ref AS BLOB)) <> ?1 \
1140                 OR content_ref GLOB '*[^0-9a-f]*') \
1141             LIMIT 1",
1142            [canonical_bytes],
1143            |row| row.get(0),
1144        )
1145        .optional()?;
1146    if let Some(id) = invalid {
1147        return Err(SqliteError::InvalidData(format!(
1148            "entities.content_ref for record {id:?} is not a canonical 64-character lowercase hexadecimal ContentRef"
1149        )));
1150    }
1151    Ok(())
1152}
1153
1154fn validate_canonical_attachment_and_claim_refs(conn: &Connection) -> Result<(), SqliteError> {
1155    let canonical_bytes = canonical_content_ref_byte_width(conn)?;
1156    for (table, identity) in [
1157        ("attachments", "record_uuid"),
1158        ("blob_gc_claims", "root_key"),
1159    ] {
1160        let sql = format!(
1161            "SELECT {identity} FROM {table} \
1162             WHERE typeof(content_ref) <> 'text' \
1163                OR length(content_ref) <> 64 \
1164                OR length(CAST(content_ref AS BLOB)) <> ?1 \
1165                OR content_ref GLOB '*[^0-9a-f]*' \
1166             LIMIT 1"
1167        );
1168        let invalid: Option<String> = conn
1169            .query_row(&sql, [canonical_bytes], |row| row.get(0))
1170            .optional()?;
1171        if let Some(owner) = invalid {
1172            return Err(SqliteError::InvalidData(format!(
1173                "{table}.content_ref for {identity} {owner:?} is not canonical"
1174            )));
1175        }
1176    }
1177    Ok(())
1178}
1179
1180fn validate_attachment_record_owners(conn: &Connection) -> Result<(), SqliteError> {
1181    let dangling: Option<(String, String)> = conn
1182        .query_row(
1183            "SELECT record_uuid, substrate FROM attachments AS attachment \
1184             WHERE (substrate = 'entity' AND NOT EXISTS ( \
1185                       SELECT 1 FROM entities WHERE id = attachment.record_uuid \
1186                   )) \
1187                OR (substrate = 'note' AND NOT EXISTS ( \
1188                       SELECT 1 FROM notes WHERE id = attachment.record_uuid \
1189                   )) \
1190             LIMIT 1",
1191            [],
1192            |row| Ok((row.get(0)?, row.get(1)?)),
1193        )
1194        .optional()?;
1195    if let Some((record_uuid, substrate)) = dangling {
1196        return Err(SqliteError::InvalidData(format!(
1197            "attachment role references absent {substrate} record {record_uuid:?}"
1198        )));
1199    }
1200    Ok(())
1201}
1202
1203fn validate_legacy_content_backfill(conn: &Connection) -> Result<(), SqliteError> {
1204    let conflict: Option<String> = conn
1205        .query_row(
1206            "SELECT entity.id FROM entities AS entity \
1207             LEFT JOIN attachments AS attachment \
1208               ON attachment.record_uuid = entity.id AND attachment.role = 'content' \
1209             WHERE entity.content_ref IS NOT NULL \
1210               AND (attachment.record_uuid IS NULL \
1211                 OR attachment.substrate <> 'entity' \
1212                 OR attachment.content_ref <> entity.content_ref) \
1213             LIMIT 1",
1214            [],
1215            |row| row.get(0),
1216        )
1217        .optional()?;
1218    if let Some(record_uuid) = conflict {
1219        return Err(SqliteError::InvalidData(format!(
1220            "legacy content attachment for entity {record_uuid:?} is missing or conflicts with entities.content_ref"
1221        )));
1222    }
1223    Ok(())
1224}
1225
1226fn stage_attachment_cutover_on_connection(conn: &Connection, now: i64) -> Result<(), SqliteError> {
1227    require_legacy_attachment_fences(conn)?;
1228    conn.execute_batch(V21_STAGE_UP)?;
1229    validate_canonical_legacy_refs(conn)?;
1230    validate_canonical_attachment_and_claim_refs(conn)?;
1231
1232    let conflict: Option<String> = conn
1233        .query_row(
1234            "SELECT entity.id FROM entities AS entity \
1235             JOIN attachments AS attachment \
1236               ON attachment.record_uuid = entity.id AND attachment.role = 'content' \
1237             WHERE entity.content_ref IS NOT NULL \
1238               AND (attachment.substrate <> 'entity' \
1239                 OR attachment.content_ref <> entity.content_ref) \
1240             LIMIT 1",
1241            [],
1242            |row| row.get(0),
1243        )
1244        .optional()?;
1245    if let Some(record_uuid) = conflict {
1246        return Err(SqliteError::InvalidData(format!(
1247            "existing content attachment for entity {record_uuid:?} conflicts with entities.content_ref"
1248        )));
1249    }
1250
1251    conn.execute(
1252        "INSERT INTO attachments \
1253         (record_uuid, substrate, role, content_ref, media_type, size_bytes, created_at) \
1254         SELECT id, 'entity', 'content', content_ref, NULL, NULL, created_at \
1255         FROM entities WHERE content_ref IS NOT NULL \
1256         ON CONFLICT(record_uuid, role) DO NOTHING",
1257        [],
1258    )?;
1259    validate_legacy_content_backfill(conn)?;
1260
1261    // The caller holds the canonical database GC owner, so every preexisting
1262    // claim is abandoned. Clearing happens before the durable incomplete
1263    // marker is exposed and remains inside this one transaction.
1264    conn.execute("DELETE FROM blob_gc_claims", [])?;
1265    conn.execute(
1266        "INSERT INTO attachment_cutover_state \
1267         (singleton, state, started_at, completed_at) \
1268         VALUES (1, 'incomplete', ?1, NULL) \
1269         ON CONFLICT(singleton) DO NOTHING",
1270        [now],
1271    )?;
1272    Ok(())
1273}
1274
1275/// Commit stage 1 of the coordinated V21 migration.
1276///
1277/// The caller must hold [`crate::stores::blob::DatabaseGcOwnerGuard`] for the
1278/// canonical database before entering this function and retain it through
1279/// application backfill and finalization. This function owns one IMMEDIATE
1280/// SQLite transaction; a failure leaves neither its DDL nor marker visible.
1281pub fn stage_attachment_cutover(conn: &mut Connection) -> Result<(), SqliteError> {
1282    let admission = WriteAdmission::for_canonical_path(canonical_connection_database_path(conn)?)?;
1283    RawMigrationWriteUnit::new(conn, &admission)?
1284        .run(|conn| stage_attachment_cutover_with_admission(conn, &admission))
1285}
1286
1287/// Stage attachment cutover with an explicit raw-connection policy.
1288pub fn stage_attachment_cutover_with_policy(
1289    conn: &mut Connection,
1290    policy: &MigrationWritePolicy,
1291) -> Result<(), SqliteError> {
1292    let admission =
1293        WriteAdmission::for_migration_policy(canonical_connection_database_path(conn)?, policy)?;
1294    RawMigrationWriteUnit::new(conn, &admission)?
1295        .run(|conn| stage_attachment_cutover_with_admission(conn, &admission))
1296}
1297
1298/// Stage attachment cutover using admission already held by a pooled caller.
1299pub(crate) fn stage_attachment_cutover_with_admission(
1300    conn: &mut Connection,
1301    admission: &WriteAdmission,
1302) -> Result<(), SqliteError> {
1303    match attachment_cutover_status(conn)? {
1304        AttachmentCutoverStatus::Complete => return Ok(()),
1305        AttachmentCutoverStatus::Pending | AttachmentCutoverStatus::Incomplete => {}
1306    }
1307    if read_schema_version(conn)? != ATTACHMENT_CUTOVER_VERSION - 1 {
1308        return Err(SqliteError::InvalidData(format!(
1309            "attachment cutover stage requires canonical V{} schema",
1310            ATTACHMENT_CUTOVER_VERSION - 1
1311        )));
1312    }
1313
1314    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
1315    if let Err(error) = admission.check() {
1316        let rollback = tx.rollback();
1317        return Err(capacity_refusal_after_rollback(
1318            conn,
1319            rollback,
1320            error,
1321            "attachment cutover stage",
1322        ));
1323    }
1324    let status = attachment_cutover_status(&tx)?;
1325    if status == AttachmentCutoverStatus::Complete {
1326        return Ok(());
1327    }
1328    stage_attachment_cutover_on_connection(&tx, chrono::Utc::now().timestamp_micros())?;
1329    tx.commit()?;
1330    Ok(())
1331}
1332
1333/// Add one host-verified pack-owned attachment during V21 stage 2.
1334///
1335/// This helper is deliberately transaction-neutral: it neither begins nor
1336/// commits a transaction. The boot coordinator can therefore apply the full
1337/// verified vector in one caller-owned IMMEDIATE transaction while retaining
1338/// the canonical database GC owner. Reapplying the same role and content is
1339/// idempotent; a different substrate or digest for that role fails closed.
1340#[allow(clippy::too_many_arguments)]
1341pub fn apply_generic_verified_attachment(
1342    conn: &Connection,
1343    record_uuid: &str,
1344    substrate: &str,
1345    role: &str,
1346    content_ref: &ContentRef,
1347    media_type: Option<&str>,
1348    size_bytes: Option<u64>,
1349    created_at: i64,
1350) -> Result<(), SqliteError> {
1351    if attachment_cutover_status(conn)? != AttachmentCutoverStatus::Incomplete {
1352        return Err(SqliteError::InvalidData(
1353            "verified application attachments may only be applied while V21 cutover is incomplete"
1354                .into(),
1355        ));
1356    }
1357    if role.is_empty() || role.chars().any(char::is_control) {
1358        return Err(SqliteError::InvalidData(
1359            "attachment role must be non-empty and contain no control characters".into(),
1360        ));
1361    }
1362    let size_bytes = size_bytes.map(i64::try_from).transpose().map_err(|_| {
1363        SqliteError::InvalidData("attachment size_bytes exceeds SQLite INTEGER".into())
1364    })?;
1365    let owner_table = match substrate {
1366        "entity" => "entities",
1367        "note" => "notes",
1368        other => {
1369            return Err(SqliteError::InvalidData(format!(
1370                "attachment substrate must be 'entity' or 'note', got {other:?}"
1371            )))
1372        }
1373    };
1374    let owner_sql = format!("SELECT COUNT(*) > 0 FROM {owner_table} WHERE id = ?1");
1375    let owner_exists: bool = conn.query_row(&owner_sql, [record_uuid], |row| row.get(0))?;
1376    if !owner_exists {
1377        return Err(SqliteError::InvalidData(format!(
1378            "cannot attach role {role:?}: {substrate} record {record_uuid:?} does not exist"
1379        )));
1380    }
1381    let claimed: bool = conn.query_row(
1382        "SELECT COUNT(*) > 0 FROM blob_gc_claims WHERE content_ref = ?1",
1383        [content_ref.as_str()],
1384        |row| row.get(0),
1385    )?;
1386    if claimed {
1387        return Err(SqliteError::InvalidData(format!(
1388            "cannot attach claimed content_ref {} during V21 cutover",
1389            content_ref.as_str()
1390        )));
1391    }
1392
1393    let changed = conn.execute(
1394        "INSERT INTO attachments \
1395         (record_uuid, substrate, role, content_ref, media_type, size_bytes, created_at) \
1396         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) \
1397         ON CONFLICT(record_uuid, role) DO UPDATE SET \
1398             media_type = excluded.media_type, \
1399             size_bytes = excluded.size_bytes, \
1400             created_at = excluded.created_at \
1401         WHERE attachments.substrate = excluded.substrate \
1402           AND attachments.content_ref = excluded.content_ref",
1403        rusqlite::params![
1404            record_uuid,
1405            substrate,
1406            role,
1407            content_ref.as_str(),
1408            media_type,
1409            size_bytes,
1410            created_at,
1411        ],
1412    )?;
1413    if changed == 0 {
1414        return Err(SqliteError::InvalidData(format!(
1415            "attachment role {role:?} for record {record_uuid:?} conflicts with an existing substrate or content_ref"
1416        )));
1417    }
1418    Ok(())
1419}
1420
1421fn finalize_attachment_cutover_on_connection(
1422    conn: &Connection,
1423    now: i64,
1424) -> Result<(), SqliteError> {
1425    require_legacy_attachment_fences(conn)?;
1426    validate_canonical_legacy_refs(conn)?;
1427    validate_canonical_attachment_and_claim_refs(conn)?;
1428    validate_attachment_record_owners(conn)?;
1429    validate_legacy_content_backfill(conn)?;
1430
1431    let remaining_claims: i64 =
1432        conn.query_row("SELECT COUNT(*) FROM blob_gc_claims", [], |row| row.get(0))?;
1433    if remaining_claims != 0 {
1434        return Err(SqliteError::InvalidData(format!(
1435            "attachment cutover cannot finalize while {remaining_claims} blob GC claim rows remain"
1436        )));
1437    }
1438
1439    let uncovered_model: Option<String> = conn
1440        .query_row(
1441            "SELECT model.id FROM entities AS model \
1442             WHERE model.entity_type = 'moodboard_model' \
1443               AND model.content_ref IS NOT NULL \
1444               AND NOT EXISTS ( \
1445                   SELECT 1 FROM attachments AS attachment \
1446                   WHERE attachment.record_uuid = model.id \
1447                     AND attachment.substrate = 'entity' \
1448                     AND attachment.role = 'fann-network' \
1449               ) \
1450             LIMIT 1",
1451            [],
1452            |row| row.get(0),
1453        )
1454        .optional()?;
1455    if let Some(record_uuid) = uncovered_model {
1456        return Err(SqliteError::InvalidData(format!(
1457            "moodboard_model {record_uuid:?} has legacy content but no verified 'fann-network' attachment"
1458        )));
1459    }
1460
1461    conn.execute_batch(V21_ATTACHMENT_FENCES_UP)?;
1462    conn.execute_batch(
1463        "DROP TRIGGER entities_reject_claimed_blob_insert; \
1464         DROP TRIGGER entities_reject_claimed_blob_update; \
1465         DROP INDEX idx_entities_content_ref; \
1466         ALTER TABLE entities DROP COLUMN content_ref;",
1467    )?;
1468    conn.execute(
1469        "UPDATE attachment_cutover_state \
1470         SET state = 'complete', completed_at = ?1 \
1471         WHERE singleton = 1 AND state = 'incomplete'",
1472        [now],
1473    )?;
1474    Ok(())
1475}
1476
1477fn record_attachment_cutover_migration(conn: &Connection, now: i64) -> Result<(), SqliteError> {
1478    let migration = MIGRATIONS
1479        .iter()
1480        .find(|migration| migration.version == ATTACHMENT_CUTOVER_VERSION)
1481        .expect("V21 migration must be registered");
1482    conn.execute(
1483        "INSERT INTO _schema_migrations (version, name, applied_at) VALUES (?1, ?2, ?3)",
1484        rusqlite::params![migration.version, migration.name, now],
1485    )?;
1486    Ok(())
1487}
1488
1489/// Atomically switch an explicitly staged database to attachment-only V21.
1490///
1491/// The caller must still hold the canonical database GC owner. The exclusive
1492/// transition revalidates every legacy and attachment reference, verifies
1493/// moodboard model role coverage, replaces the claim fences, removes the old
1494/// column, marks the cutover complete, and records V21 in one transaction.
1495pub fn finalize_attachment_cutover(conn: &mut Connection) -> Result<(), SqliteError> {
1496    let admission = WriteAdmission::for_canonical_path(canonical_connection_database_path(conn)?)?;
1497    RawMigrationWriteUnit::new(conn, &admission)?
1498        .run(|conn| finalize_attachment_cutover_with_admission(conn, &admission))
1499}
1500
1501/// Finalize attachment cutover with an explicit raw-connection policy.
1502pub fn finalize_attachment_cutover_with_policy(
1503    conn: &mut Connection,
1504    policy: &MigrationWritePolicy,
1505) -> Result<(), SqliteError> {
1506    let admission =
1507        WriteAdmission::for_migration_policy(canonical_connection_database_path(conn)?, policy)?;
1508    RawMigrationWriteUnit::new(conn, &admission)?
1509        .run(|conn| finalize_attachment_cutover_with_admission(conn, &admission))
1510}
1511
1512/// Finalize attachment cutover using admission already held by a pooled caller.
1513pub(crate) fn finalize_attachment_cutover_with_admission(
1514    conn: &mut Connection,
1515    admission: &WriteAdmission,
1516) -> Result<(), SqliteError> {
1517    if attachment_cutover_status(conn)? == AttachmentCutoverStatus::Complete {
1518        return Ok(());
1519    }
1520    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Exclusive)?;
1521    if let Err(error) = admission.check() {
1522        let rollback = tx.rollback();
1523        return Err(capacity_refusal_after_rollback(
1524            conn,
1525            rollback,
1526            error,
1527            "attachment cutover finalization",
1528        ));
1529    }
1530    match attachment_cutover_status(&tx)? {
1531        AttachmentCutoverStatus::Complete => return Ok(()),
1532        AttachmentCutoverStatus::Pending => {
1533            return Err(SqliteError::InvalidData(
1534                "attachment cutover must complete stage 1 before finalization".into(),
1535            ))
1536        }
1537        AttachmentCutoverStatus::Incomplete => {}
1538    }
1539    let now = chrono::Utc::now().timestamp_micros();
1540    finalize_attachment_cutover_on_connection(&tx, now)?;
1541    record_attachment_cutover_migration(&tx, now)?;
1542    tx.commit()?;
1543    Ok(())
1544}
1545
1546/// Read the ordered migration ledger prefix without interpreting its rows.
1547fn read_applied_migration_ledger(
1548    conn: &Connection,
1549    through_version: u32,
1550) -> Result<Vec<(u32, String)>, SqliteError> {
1551    let mut stmt = conn.prepare(
1552        "SELECT version, name FROM _schema_migrations \
1553         WHERE version <= ?1 ORDER BY version ASC",
1554    )?;
1555    let rows = stmt
1556        .query_map([through_version], |row| {
1557            Ok((row.get::<_, u32>(0)?, row.get::<_, String>(1)?))
1558        })?
1559        .collect::<Result<Vec<_>, _>>()?;
1560    Ok(rows)
1561}
1562
1563/// Require the applied versions through `through_version` to be the exact
1564/// contiguous canonical prefix of [`MIGRATIONS`]. A matching `MAX(version)` is
1565/// insufficient: a missing middle row or foreign version can expose a
1566/// materially different schema while retaining the same maximum.
1567fn validate_applied_migration_versions(
1568    applied: &[(u32, String)],
1569    through_version: u32,
1570) -> Result<(), SqliteError> {
1571    let expected: Vec<&VersionedMigration> = MIGRATIONS
1572        .iter()
1573        .filter(|migration| migration.version <= through_version)
1574        .collect();
1575    let mut applied_index = 0;
1576
1577    for migration in expected {
1578        let Some((version, applied_name)) = applied.get(applied_index) else {
1579            return Err(SqliteError::InvalidData(format!(
1580                "migration history is missing version {} ('{}'); the applied ledger must be \
1581                 the exact contiguous canonical sequence through version {through_version}",
1582                migration.version, migration.name,
1583            )));
1584        };
1585        if *version < migration.version {
1586            return Err(SqliteError::InvalidData(format!(
1587                "migration history contains unknown version {version} recorded as \
1588                 '{applied_name}'; the applied ledger must contain only canonical versions"
1589            )));
1590        }
1591        if *version > migration.version {
1592            return Err(SqliteError::InvalidData(format!(
1593                "migration history is missing version {} ('{}'); found version {version} \
1594                 next instead",
1595                migration.version, migration.name,
1596            )));
1597        }
1598        applied_index += 1;
1599    }
1600
1601    if let Some((version, name)) = applied.get(applied_index) {
1602        return Err(SqliteError::InvalidData(format!(
1603            "migration history contains unknown version {version} recorded as '{name}'; \
1604             the applied ledger must contain only canonical versions"
1605        )));
1606    }
1607
1608    Ok(())
1609}
1610
1611fn validate_applied_migration_names(
1612    applied: &[(u32, String)],
1613    through_version: u32,
1614    allow_known_v19_repairs: bool,
1615) -> Result<(), SqliteError> {
1616    for ((version, applied_name), migration) in applied.iter().zip(
1617        MIGRATIONS
1618            .iter()
1619            .filter(|migration| migration.version <= through_version),
1620    ) {
1621        debug_assert_eq!(*version, migration.version);
1622        if migration.name != applied_name.as_str() {
1623            if allow_known_v19_repairs && matches!(*version, 13 | 14) {
1624                continue;
1625            }
1626            return Err(SqliteError::InvalidData(format!(
1627                "migration version {version} is recorded under name '{applied_name}', \
1628                 expected '{expected}'. This database's migration history does not match \
1629                 the current binary; recreate it from the current schema or repair the \
1630                 specific known divergence via a dedicated migration.",
1631                expected = migration.name,
1632            )));
1633        }
1634    }
1635
1636    Ok(())
1637}
1638
1639/// Confirm the complete applied ledger is the canonical prefix, including
1640/// names. The only historical V13/V14 name divergence is repaired by V19
1641/// before this validator runs for a pre-V19 database.
1642fn validate_applied_migration_ledger(
1643    conn: &Connection,
1644    through_version: u32,
1645) -> Result<(), SqliteError> {
1646    let applied = read_applied_migration_ledger(conn, through_version)?;
1647    validate_applied_migration_versions(&applied, through_version)?;
1648    validate_applied_migration_names(&applied, through_version, false)
1649}
1650
1651const MIGRATION_TRACKING_TABLE: &str = include_str!("../sql/schema-migrations-table.sql");
1652
1653const SCHEMA_VERSION_PROBE_SQL: &str = "SELECT COALESCE(MAX(version), 0) FROM _schema_migrations";
1654
1655/// Build the schema-ledger version query without opening a reader or decoding its result.
1656pub fn schema_version_probe() -> khive_storage::types::SqlStatement {
1657    khive_storage::types::SqlStatement::new(SCHEMA_VERSION_PROBE_SQL, Vec::new())
1658}
1659
1660/// Read the applied schema version from an open connection **without** running
1661/// migrations. Returns 0 when the `_schema_migrations` ledger is absent (an
1662/// un-migrated or empty database); any other failure (BUSY, IO) propagates —
1663/// collapsing it to 0 would misreport a live database as un-migrated. Never
1664/// writes.
1665pub fn read_schema_version(conn: &Connection) -> Result<u32, SqliteError> {
1666    match conn.query_row(SCHEMA_VERSION_PROBE_SQL, [], |row| row.get(0)) {
1667        Ok(version) => Ok(version),
1668        Err(rusqlite::Error::SqliteFailure(_, Some(ref msg)))
1669            if msg.contains("no such table: _schema_migrations") =>
1670        {
1671            Ok(0)
1672        }
1673        Err(e) => Err(e.into()),
1674    }
1675}
1676
1677/// Open `path` read-only and report its applied schema version without creating
1678/// or migrating the file. The caller must ensure `path` exists — opening a
1679/// missing file read-only errors rather than creating it. This is the path used
1680/// by schema-inspection commands that must not mutate the database.
1681pub fn inspect_schema_version(path: &std::path::Path) -> Result<u32, SqliteError> {
1682    let conn = crate::pool::open_read_only_snapshot_connection(path)?;
1683    read_schema_version(&conn)
1684}
1685
1686/// Open `path` read-only and require the exact canonical current ledger and
1687/// physical cutover state, without creating files or applying migrations.
1688pub fn inspect_schema_is_current(path: &std::path::Path) -> Result<u32, SqliteError> {
1689    let conn = crate::pool::open_read_only_snapshot_connection(path)?;
1690    validate_schema_is_current(&conn)
1691}
1692
1693/// Page accounting for one database file. Each value is a single pragma read,
1694/// so the cost does not grow with the file.
1695#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1696pub struct PageAccounting {
1697    /// `PRAGMA page_size`, in bytes.
1698    pub page_size: u64,
1699    /// `PRAGMA page_count`: every page in the database, free pages included.
1700    pub page_count: u64,
1701    /// `PRAGMA freelist_count`: pages that later writes can reuse but that stay
1702    /// in the file until a `VACUUM`.
1703    pub freelist_count: u64,
1704}
1705
1706/// Open `path` read-only and report its page accounting without creating,
1707/// migrating or walking the file. The caller must ensure `path` exists.
1708pub fn inspect_page_accounting(path: &std::path::Path) -> Result<PageAccounting, SqliteError> {
1709    let conn = crate::pool::open_read_only_snapshot_connection(path)?;
1710    let read = |pragma: &str| -> Result<u64, SqliteError> {
1711        let value: i64 = conn.query_row(pragma, [], |row| row.get(0))?;
1712        u64::try_from(value)
1713            .map_err(|_| SqliteError::InvalidData(format!("{pragma} returned {value}")))
1714    };
1715    Ok(PageAccounting {
1716        page_size: read("PRAGMA page_size")?,
1717        page_count: read("PRAGMA page_count")?,
1718        freelist_count: read("PRAGMA freelist_count")?,
1719    })
1720}
1721
1722/// Open `path` read-only and run `PRAGMA integrity_check` over the whole file,
1723/// returning every row SQLite reports: exactly `["ok"]` for a sound file. The
1724/// check reads every page, so its cost grows with the file. No error limit is
1725/// applied: the pragma's default stops at 100 rows, so the largest limit it
1726/// accepts is passed instead.
1727pub fn inspect_integrity(path: &std::path::Path) -> Result<Vec<String>, SqliteError> {
1728    let conn = crate::pool::open_read_only_snapshot_connection(path)?;
1729    let mut statement = conn.prepare(&format!("PRAGMA integrity_check({})", i32::MAX))?;
1730    let rows = statement
1731        .query_map([], |row| row.get::<_, String>(0))?
1732        .collect::<Result<Vec<_>, _>>()?;
1733    Ok(rows)
1734}
1735
1736/// Require an already-open database to match this build's latest core schema
1737/// without applying migrations.
1738///
1739/// A read-only snapshot behind the current migration set cannot be repaired in
1740/// place, while a snapshot ahead of the binary may contain schema this build
1741/// does not understand. Both directions fail with an actionable diagnostic; an
1742/// exact match performs no writes.
1743pub fn validate_schema_is_current(conn: &Connection) -> Result<u32, SqliteError> {
1744    let current_version = read_schema_version(conn)?;
1745    let latest_version = latest_schema_version();
1746
1747    if current_version < latest_version {
1748        return Err(SqliteError::InvalidData(format!(
1749            "read-only database schema version {current_version} is behind the latest known \
1750             migration {latest_version}; migrate a writable copy with this build before opening \
1751             the snapshot read-only"
1752        )));
1753    }
1754    if current_version > latest_version {
1755        return Err(SqliteError::InvalidData(format!(
1756            "read-only database schema version {current_version} is ahead of the latest known \
1757             migration {latest_version}; use a compatible newer build or recreate the snapshot"
1758        )));
1759    }
1760
1761    // Numeric equality alone is not enough: a database can carry the current
1762    // maximum version under renamed or foreign migration ledger entries while
1763    // exposing a materially different schema. Writable boot runs this same
1764    // closed-name validation in `bootstrap_migration_ledger`; snapshot inspection
1765    // must not accept a history that ordinary boot would reject merely because
1766    // it cannot repair it in place.
1767    validate_applied_migration_ledger(conn, current_version)?;
1768    // `>=`, not `==`: later migrations (V22+) record on top of a completed
1769    // cutover, and a ledger at the latest version must not exempt the
1770    // physical cutover state from validation.
1771    if current_version >= ATTACHMENT_CUTOVER_VERSION
1772        && attachment_cutover_status(conn)? != AttachmentCutoverStatus::Complete
1773    {
1774        return Err(SqliteError::InvalidData(
1775            "read-only database has not completed the V21 attachment cutover".into(),
1776        ));
1777    }
1778
1779    if current_version >= MEMORY_VISIBILITY_CUTOVER_VERSION {
1780        memory_visibility::validate_cutover(conn)?;
1781    }
1782
1783    Ok(current_version)
1784}
1785
1786/// Require the complete core migration ledger and readable memory provenance
1787/// schema without applying migrations or inferring an individual note's epoch.
1788pub fn validate_memory_visibility_cutover(conn: &Connection) -> Result<(), SqliteError> {
1789    validate_schema_is_current(conn).map(|_| ())
1790}
1791
1792#[cfg(test)]
1793pub(crate) mod test_sync {
1794    use std::sync::atomic::AtomicU32;
1795    use std::sync::{Arc, Barrier, Mutex};
1796
1797    /// When set, `run_versioned_migrations` parks after its initial (stale)
1798    /// ledger read until every racing thread has arrived — forcing the
1799    /// contended interleaving the concurrent-boot test asserts on.
1800    pub(crate) static STALE_READ_BARRIER: Mutex<Option<Arc<Barrier>>> = Mutex::new(None);
1801    /// Counts entries into the under-lock sibling fast-forward branch.
1802    pub(crate) static LOCKED_FAST_FORWARDS: AtomicU32 = AtomicU32::new(0);
1803    /// Set by the SQLite busy handler installed on participating connections:
1804    /// `true` means SQLite itself reported a blocked lock acquisition to the
1805    /// loser — actual contention, not merely an intended attempt.
1806    pub(crate) static BUSY_OBSERVED: std::sync::atomic::AtomicBool =
1807        std::sync::atomic::AtomicBool::new(false);
1808
1809    /// Busy handler for participating test connections: records that SQLite
1810    /// observed a busy acquisition, then keeps retrying.
1811    pub(crate) fn record_busy(_count: i32) -> bool {
1812        BUSY_OBSERVED.store(true, std::sync::atomic::Ordering::SeqCst);
1813        std::thread::sleep(std::time::Duration::from_millis(1));
1814        true
1815    }
1816
1817    /// Set by the winner immediately before committing its first migration
1818    /// transaction — i.e. before the write lock is first released.
1819    pub(crate) static WINNER_COMMITTED: std::sync::atomic::AtomicBool =
1820        std::sync::atomic::AtomicBool::new(false);
1821    /// Recorded by the loser when its first `BEGIN IMMEDIATE` returns: whether
1822    /// the winner had already committed at that moment. `true` is direct
1823    /// evidence the loser's lock acquisition blocked across the winner's held
1824    /// write lock rather than the two calls serializing by scheduler accident.
1825    pub(crate) static LOSER_SAW_WINNER_COMMIT: std::sync::atomic::AtomicBool =
1826        std::sync::atomic::AtomicBool::new(false);
1827
1828    std::thread_local! {
1829        /// Opt-in flag: only threads that set this participate in the barrier,
1830        /// so unrelated tests migrating in parallel are never parked.
1831        pub(crate) static PARTICIPATE: std::cell::Cell<bool> =
1832            const { std::cell::Cell::new(false) };
1833        /// Whether this thread has already instrumented its first BEGIN.
1834        pub(crate) static FIRST_BEGIN_DONE: std::cell::Cell<bool> =
1835            const { std::cell::Cell::new(false) };
1836    }
1837}
1838
1839/// Apply the ordinary unapplied migration prefix in order.
1840///
1841/// The operation is idempotent and each ordinary migration runs in its own
1842/// transaction. V21 is the application-assisted exception: a database with no
1843/// legacy content references may complete V21 atomically here, while a legacy
1844/// database stops successfully at V20 so the async host can stage, verify, and
1845/// finalize the attachment cutover. Errors on a non-contiguous migration array,
1846/// a non-canonical applied ledger, or a failed migration.
1847fn canonical_connection_database_path(conn: &Connection) -> Result<Option<PathBuf>, SqliteError> {
1848    let configured = conn.path().unwrap_or_default();
1849    let raw_path = if configured.is_empty() {
1850        conn.query_row(
1851            "SELECT file FROM pragma_database_list WHERE name = 'main'",
1852            [],
1853            |row| row.get::<_, String>(0),
1854        )?
1855    } else {
1856        configured.to_string()
1857    };
1858
1859    if raw_path.is_empty() {
1860        return Ok(None);
1861    }
1862    let canonical = std::fs::canonicalize(&raw_path).map_err(SqliteError::Io)?;
1863    #[cfg(any(unix, windows))]
1864    crate::pool::opened_sqlite_file_identity(conn, &canonical)?;
1865    Ok(Some(canonical))
1866}
1867
1868fn validate_database_gc_owner(
1869    conn: &Connection,
1870    owner: &DatabaseGcOwnerGuard,
1871) -> Result<(), SqliteError> {
1872    let connection_path = canonical_connection_database_path(conn)?;
1873    if owner.database_path() != connection_path.as_deref() {
1874        return Err(SqliteError::InvalidData(format!(
1875            "database GC owner targets {:?}, but migration connection targets {:?}",
1876            owner.database_path(),
1877            connection_path.as_deref(),
1878        )));
1879    }
1880    Ok(())
1881}
1882
1883pub fn run_migrations(conn: &mut Connection) -> Result<u32, SqliteError> {
1884    let database_path = canonical_connection_database_path(conn)?;
1885    let admission = WriteAdmission::for_canonical_path(database_path.clone())?;
1886    run_raw_migrations_with_admission(conn, database_path, &admission)
1887}
1888
1889/// Run migrations on a raw connection with a captured admission policy.
1890pub fn run_migrations_with_policy(
1891    conn: &mut Connection,
1892    policy: &MigrationWritePolicy,
1893) -> Result<u32, SqliteError> {
1894    let database_path = canonical_connection_database_path(conn)?;
1895    let admission = WriteAdmission::for_migration_policy(database_path.clone(), policy)?;
1896    run_raw_migrations_with_admission(conn, database_path, &admission)
1897}
1898
1899fn run_raw_migrations_with_admission(
1900    conn: &mut Connection,
1901    database_path: Option<PathBuf>,
1902    admission: &WriteAdmission,
1903) -> Result<u32, SqliteError> {
1904    if let Some(database_path) = database_path {
1905        // This raw API may have been handed a connection behind an opaque pool
1906        // writer guard. Never wait here and invert the canonical
1907        // owner-before-writer order; fail closed and direct production callers
1908        // to `StorageBackend::prepare_core_schema` instead.
1909        let owner = try_acquire_database_gc_owner_for_path(database_path).map_err(|error| {
1910            SqliteError::InvalidData(format!(
1911                "failed to acquire database GC owner before schema migration: {error}"
1912            ))
1913        })?;
1914        return run_migrations_with_database_gc_owner(
1915            &mut RawMigrationTransactions::new(conn, admission),
1916            &owner,
1917            admission,
1918        );
1919    }
1920
1921    // A raw in-memory connection has no durable/cross-process GC domain. The
1922    // production in-memory backend still uses the owner-aware path below.
1923    run_versioned_migrations(
1924        &mut RawMigrationTransactions::new(conn, admission),
1925        None,
1926        admission,
1927    )
1928}
1929
1930pub(crate) fn run_migrations_with_database_gc_owner(
1931    writes: &mut impl MigrationTransactions,
1932    owner: &DatabaseGcOwnerGuard,
1933    admission: &WriteAdmission,
1934) -> Result<u32, SqliteError> {
1935    run_versioned_migrations(writes, Some(owner), admission)
1936}
1937
1938/// Raise-only to a 5s busy_timeout floor for one admitted migration unit and
1939/// restore the caller's value after it. Concurrent boots (multiple processes
1940/// migrating the same file) contend on SQLite's write lock; a short hot-path
1941/// busy_timeout cannot wait out a sibling's migration, and a caller whose
1942/// configured timeout is already longer is never reduced.
1943fn with_migration_busy_timeout<T>(
1944    conn: &mut Connection,
1945    operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
1946) -> Result<T, SqliteError> {
1947    let prior_busy_ms: i64 = conn.query_row("PRAGMA busy_timeout", [], |row| row.get(0))?;
1948    let raised = prior_busy_ms < 5_000;
1949    if raised {
1950        conn.busy_timeout(std::time::Duration::from_secs(5))?;
1951    }
1952    let result = operation(conn);
1953    if raised {
1954        let _ = conn.busy_timeout(std::time::Duration::from_millis(prior_busy_ms.max(0) as u64));
1955    }
1956    result
1957}
1958
1959/// What one admitted versioned-migration transaction did.
1960enum MigrationStep {
1961    /// This transaction applied the migration and committed.
1962    Applied,
1963    /// A sibling had already recorded this version or later; the value is the
1964    /// ledger maximum read under the write lock.
1965    AppliedBySibling(u32),
1966    /// V21 on a legacy database: left for the application-assisted cutover.
1967    Deferred,
1968}
1969
1970/// Bring the core schema to the latest version.
1971///
1972/// ADR-154 section 4 admits each migration transaction on its own, so the
1973/// ledger bootstrap with the pre-lock ledger read is one admitted unit and
1974/// every migration that still has to run is another, re-reading the ledger
1975/// under the write lock. No volume lease is held from one version to the next.
1976fn run_versioned_migrations(
1977    writes: &mut impl MigrationTransactions,
1978    owner: Option<&DatabaseGcOwnerGuard>,
1979    admission: &WriteAdmission,
1980) -> Result<u32, SqliteError> {
1981    let current_version = writes.admitted(|conn| {
1982        if let Some(owner) = owner {
1983            validate_database_gc_owner(conn, owner)?;
1984        }
1985        with_migration_busy_timeout(conn, |conn| bootstrap_migration_ledger(conn, admission))
1986    })?;
1987
1988    // Deterministic-contention hook: parks every caller after the stale ledger
1989    // read (no SQLite lock and no volume lease held) until all racing test
1990    // threads have observed it, so they are then released to compete for the
1991    // IMMEDIATE write lock of their first migration.
1992    #[cfg(test)]
1993    if test_sync::PARTICIPATE.with(|p| p.get()) {
1994        let barrier = test_sync::STALE_READ_BARRIER.lock().unwrap().clone();
1995        if let Some(barrier) = barrier {
1996            barrier.wait();
1997        }
1998    }
1999    let latest_version = latest_schema_version();
2000
2001    let mut applied_version = current_version;
2002    // Floor advanced when a sibling's work is observed under the write lock,
2003    // so a losing process skips the remaining already-applied migrations
2004    // without opening a transaction for each.
2005    let mut skip_through = current_version;
2006
2007    for migration in MIGRATIONS {
2008        if migration.version <= skip_through {
2009            applied_version = applied_version.max(migration.version);
2010            continue;
2011        }
2012        let step = writes.admitted(|conn| {
2013            with_migration_busy_timeout(conn, |conn| {
2014                apply_versioned_migration(conn, migration, admission, latest_version)
2015            })
2016        })?;
2017        match step {
2018            MigrationStep::Applied => applied_version = migration.version,
2019            MigrationStep::AppliedBySibling(sibling_version) => {
2020                skip_through = sibling_version.min(latest_version);
2021                applied_version = applied_version.max(migration.version);
2022            }
2023            MigrationStep::Deferred => break,
2024        }
2025    }
2026
2027    // Validate again after the loop: our own commits and any under-lock
2028    // sibling fast-forward must both leave the exact canonical ledger, not
2029    // merely advance its maximum version.
2030    writes.admitted(|conn| validate_applied_migration_ledger(conn, applied_version))?;
2031
2032    Ok(applied_version)
2033}
2034
2035/// Create the migration ledger if it is missing and validate what it records,
2036/// returning the recorded version. The read is taken before any migration
2037/// write lock; each migration re-reads the ledger under that lock.
2038fn bootstrap_migration_ledger(
2039    conn: &mut Connection,
2040    admission: &WriteAdmission,
2041) -> Result<u32, SqliteError> {
2042    admission.check()?;
2043    conn.execute_batch(MIGRATION_TRACKING_TABLE)?;
2044    require_autocommit(conn, "migration-tracking bootstrap")?;
2045
2046    let current_version: u32 = read_schema_version(conn)?;
2047
2048    // A database whose recorded version is ahead of the latest known migration
2049    // predates the consolidated V1 baseline (ADR-015) — e.g. it still carries the
2050    // pre-consolidation V2..V22 ledger — or was written by a newer build. Either
2051    // way the baseline schema would be silently skipped, leaving the process on a
2052    // stale schema. Fail loudly instead of corrupting silently.
2053    let latest_version = latest_schema_version();
2054    if current_version > latest_version {
2055        return Err(SqliteError::InvalidData(format!(
2056            "database schema version {current_version} is ahead of the latest known migration \
2057             {latest_version}. This database predates the consolidated baseline (ADR-015) or was \
2058             written by a newer build. Recreate it from the current schema; in-place downgrade is \
2059             not supported."
2060        )));
2061    }
2062
2063    // Every writable upgrade starts from an exact canonical version sequence;
2064    // fail before applying new migrations if MAX(version) hides a missing or
2065    // foreign row. A pre-V19 database may still carry the V13/V14 name
2066    // divergence that V19 exists to repair. Name validation therefore permits
2067    // exactly those two rows before V19, while every unrelated mismatch still
2068    // fails before any new migration is applied.
2069    let applied = read_applied_migration_ledger(conn, current_version)?;
2070    validate_applied_migration_versions(&applied, current_version)?;
2071    validate_applied_migration_names(&applied, current_version, current_version < 19)?;
2072
2073    Ok(current_version)
2074}
2075
2076/// Apply one versioned migration in its own IMMEDIATE transaction, probing
2077/// capacity after BEGIN and before its first statement (ADR-154 section 4).
2078fn apply_versioned_migration(
2079    conn: &mut Connection,
2080    migration: &VersionedMigration,
2081    admission: &WriteAdmission,
2082    latest_version: u32,
2083) -> Result<MigrationStep, SqliteError> {
2084    // IMMEDIATE: take the write lock up front so concurrent boots serialize
2085    // here instead of failing mid-migration when a DEFERRED transaction
2086    // upgrades to a write.
2087    #[cfg(test)]
2088    let instrumented_first_begin =
2089        test_sync::PARTICIPATE.with(|p| p.get()) && !test_sync::FIRST_BEGIN_DONE.with(|f| f.get());
2090    #[cfg(test)]
2091    if instrumented_first_begin {
2092        test_sync::FIRST_BEGIN_DONE.with(|f| f.set(true));
2093    }
2094    // Replaces the busy_timeout raised for this unit on a participating test
2095    // connection: records SQLite-observed contention, then keeps retrying.
2096    #[cfg(test)]
2097    if test_sync::PARTICIPATE.with(|p| p.get()) {
2098        conn.busy_handler(Some(test_sync::record_busy))?;
2099    }
2100    let tx = conn
2101        .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
2102        .map_err(|e| SqliteError::migration(migration.version, e))?;
2103    if let Err(error) = admission.check() {
2104        let rollback = tx.rollback();
2105        return Err(capacity_refusal_after_rollback(
2106            conn,
2107            rollback,
2108            error,
2109            "core schema migration",
2110        ));
2111    }
2112
2113    // Re-check under the write lock: a sibling process may have applied
2114    // this migration (and possibly later ones) while we waited. Running
2115    // its DDL again would fail; fast-forward past everything it applied.
2116    let sibling_version: u32 = tx
2117        .query_row(SCHEMA_VERSION_PROBE_SQL, [], |row| row.get(0))
2118        .map_err(|e| SqliteError::migration(migration.version, e))?;
2119    #[cfg(test)]
2120    if instrumented_first_begin {
2121        use std::sync::atomic::Ordering::SeqCst;
2122        if sibling_version == 0 {
2123            // Winner: hold the write lock until SQLite has reported a
2124            // busy acquisition to the loser (its busy handler fired) —
2125            // proof the loser's BEGIN is actually blocked on this held
2126            // lock, not merely intended. Bounded so a regression fails
2127            // the assertion instead of hanging the test.
2128            let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
2129            while !test_sync::BUSY_OBSERVED.load(SeqCst) && std::time::Instant::now() < deadline {
2130                std::thread::yield_now();
2131            }
2132        } else {
2133            // Loser: our first BEGIN just returned. Record whether the
2134            // winner had already committed — true means we blocked across
2135            // its held lock.
2136            test_sync::LOSER_SAW_WINNER_COMMIT
2137                .store(test_sync::WINNER_COMMITTED.load(SeqCst), SeqCst);
2138        }
2139    }
2140
2141    // The ahead-of-latest guard above ran on a pre-lock read; a newer
2142    // build may have committed a version past ours while we waited for
2143    // the write lock. Accepting it (clamped) would return Ok on a schema
2144    // this binary does not understand — reject it the same way.
2145    if sibling_version > latest_version {
2146        return Err(SqliteError::InvalidData(format!(
2147            "database schema version {sibling_version} is ahead of the latest known \
2148             migration {latest_version} (committed by a concurrent process while this \
2149             one waited for the migration write lock). This build cannot run against \
2150             the newer schema; upgrade the binary or recreate the database."
2151        )));
2152    }
2153
2154    if sibling_version >= migration.version {
2155        #[cfg(test)]
2156        test_sync::LOCKED_FAST_FORWARDS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2157        return Ok(MigrationStep::AppliedBySibling(sibling_version));
2158    }
2159
2160    if migration.version == 46 {
2161        memory_visibility::capture_pre_v46(&tx)
2162            .map_err(|error| SqliteError::migration(migration.version, error))?;
2163        #[cfg(test)]
2164        memory_visibility::test_state::stop_at(memory_visibility::test_state::Stop::AfterCapture)?;
2165    }
2166
2167    if migration.version == ATTACHMENT_CUTOVER_VERSION {
2168        let status = attachment_cutover_status(&tx)
2169            .map_err(|e| SqliteError::migration(migration.version, e))?;
2170        let defers = cutover_defers(&tx, status)
2171            .map_err(|e| SqliteError::migration(migration.version, e))?;
2172
2173        // V21 belongs to the boot coordinator. Ordinary backend open may
2174        // finish the degenerate zero-ref case atomically, but it must not
2175        // expose a dual-source interval or eagerly stage a legacy DB.
2176        if defers {
2177            drop(tx);
2178            return Ok(MigrationStep::Deferred);
2179        }
2180        if status != AttachmentCutoverStatus::Pending {
2181            return Err(SqliteError::migration_message(
2182                migration.version,
2183                format!("unexpected attachment cutover state {status:?}"),
2184            ));
2185        }
2186
2187        let now = chrono::Utc::now().timestamp_micros();
2188        stage_attachment_cutover_on_connection(&tx, now)
2189            .map_err(|e| SqliteError::migration(migration.version, e))?;
2190        finalize_attachment_cutover_on_connection(&tx, now)
2191            .map_err(|e| SqliteError::migration(migration.version, e))?;
2192    } else if migration.version == 36 {
2193        // The events store DDL may already have added these columns.
2194        crate::stores::event::ensure_operation_attribution_columns(&tx)
2195            .map_err(|error| SqliteError::migration(migration.version, error))?;
2196    } else if migration.version == 44 {
2197        migrate_outbound_due_key(&tx)
2198            .map_err(|error| SqliteError::migration(migration.version, error))?;
2199    } else if migration.version == 48 {
2200        migrate_acknowledgement_journal(&tx)
2201            .map_err(|error| SqliteError::migration(migration.version, error))?;
2202    } else if migration.version == 58 {
2203        migrate_proposal_archive(&tx)?;
2204    } else if migration.version == 66 {
2205        migrate_undelivered_due_index(&tx)
2206            .map_err(|error| SqliteError::migration(migration.version, error))?;
2207    } else if migration.name == SESSION_IDENTITY_MIGRATION_NAME {
2208        tx.execute_batch(migration.up)
2209            .map_err(|error| SqliteError::migration(migration.version, error))?;
2210        session_identity_migration::apply(&tx)
2211            .map_err(|error| SqliteError::migration(migration.version, error))?;
2212    } else {
2213        tx.execute_batch(migration.up)
2214            .map_err(|e| SqliteError::migration(migration.version, e))?;
2215    }
2216
2217    let visibility_counts = if migration.version == MEMORY_VISIBILITY_CUTOVER_VERSION {
2218        Some(
2219            memory_visibility::cutover_counts(&tx)
2220                .map_err(|error| SqliteError::migration(migration.version, error))?,
2221        )
2222    } else {
2223        None
2224    };
2225
2226    // V19's repair contract includes normalizing the two known-divergent
2227    // recorded names. `_schema_migrations` is created and owned by this
2228    // runner (not by any migration file), so the normalization lives
2229    // here, in the same transaction that applies V19's SQL. Exact,
2230    // closed set — versions 13 and 14 only; any other (version, name)
2231    // mismatch still fails startup via validate_applied_migration_ledger.
2232    if migration.version == 19 {
2233        tx.execute_batch(
2234            "UPDATE _schema_migrations SET name = 'list_cursor_sequences' WHERE version = 13;\n\
2235             UPDATE _schema_migrations SET name = 'graph_edges_id_unique' WHERE version = 14;",
2236        )
2237        .map_err(|e| SqliteError::migration(migration.version, e))?;
2238    }
2239
2240    let now = chrono::Utc::now().timestamp_micros();
2241    tx.execute(
2242        "INSERT INTO _schema_migrations (version, name, applied_at) VALUES (?1, ?2, ?3) \
2243         ON CONFLICT(version) DO NOTHING",
2244        rusqlite::params![migration.version, migration.name, now],
2245    )
2246    .map_err(|e| SqliteError::migration(migration.version, e))?;
2247
2248    #[cfg(test)]
2249    if instrumented_first_begin {
2250        test_sync::WINNER_COMMITTED.store(true, std::sync::atomic::Ordering::SeqCst);
2251    }
2252
2253    #[cfg(test)]
2254    if migration.version == MEMORY_VISIBILITY_CUTOVER_VERSION {
2255        memory_visibility::test_state::stop_at(
2256            memory_visibility::test_state::Stop::BeforeCutoverCommit,
2257        )?;
2258    }
2259    tx.commit()
2260        .map_err(|e| SqliteError::migration(migration.version, e))?;
2261    if let Some(counts) = visibility_counts {
2262        memory_visibility::log_counts(&counts, conn.path().unwrap_or(":memory:"));
2263    }
2264    #[cfg(test)]
2265    if migration.version == 46 {
2266        memory_visibility::test_state::stop_at(
2267            memory_visibility::test_state::Stop::AfterV46Commit,
2268        )?;
2269    }
2270
2271    Ok(MigrationStep::Applied)
2272}
2273
2274#[derive(Debug)]
2275pub struct EmbeddingModelRegistryRecord {
2276    /// Vector engine name (e.g. `"paraphrase"`).
2277    pub engine_name: String,
2278    /// Model identifier (e.g. `"all-minilm-l6-v2"`).
2279    pub model_id: String,
2280    /// Canonical deduplication key combining engine and model.
2281    pub key_version: String,
2282    /// Embedding dimensionality.
2283    pub dimensions: u32,
2284    /// Lifecycle status (`"active"` or `"superseded"`).
2285    pub status: String,
2286    /// Epoch timestamp when the model was activated.
2287    pub activated_at: Option<i64>,
2288    /// Epoch timestamp when the model was superseded.
2289    pub superseded_at: Option<i64>,
2290}
2291
2292/// Query the `_embedding_models` registry.
2293///
2294/// Opens the database at `db` (defaults to `~/.khive/khive.db`) and
2295/// returns all registry rows, optionally filtered by `engine_name`.
2296/// Returns an empty vec if the database or table does not exist.
2297pub fn query_embedding_models(
2298    db: Option<&std::path::Path>,
2299    engine_filter: Option<&str>,
2300) -> Result<Vec<EmbeddingModelRegistryRecord>, SqliteError> {
2301    let path = db.map(std::path::Path::to_path_buf).unwrap_or_else(|| {
2302        std::env::var("HOME")
2303            .map(std::path::PathBuf::from)
2304            .unwrap_or_else(|_| std::path::PathBuf::from("."))
2305            .join(".khive/khive.db")
2306    });
2307    if !path.exists() {
2308        return Ok(Vec::new());
2309    }
2310    let conn = Connection::open_with_flags(
2311        path,
2312        rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY
2313            | rusqlite::OpenFlags::SQLITE_OPEN_NO_MUTEX
2314            | rusqlite::OpenFlags::SQLITE_OPEN_URI,
2315    )?;
2316    query_embedding_models_conn(&conn, engine_filter)
2317}
2318
2319/// Query `_embedding_models` from an existing connection (testable without a file).
2320///
2321/// Returns an empty vec if the table does not exist.
2322pub(crate) fn query_embedding_models_conn(
2323    conn: &Connection,
2324    engine_filter: Option<&str>,
2325) -> Result<Vec<EmbeddingModelRegistryRecord>, SqliteError> {
2326    let exists: bool = conn.query_row(
2327        "SELECT COUNT(*) > 0 FROM sqlite_master \
2328         WHERE type='table' AND name='_embedding_models'",
2329        [],
2330        |row| row.get(0),
2331    )?;
2332    if !exists {
2333        return Ok(Vec::new());
2334    }
2335
2336    let sql = if engine_filter.is_some() {
2337        "SELECT engine_name, model_id, key_version, dim, status, activated_at, superseded_at \
2338         FROM _embedding_models WHERE engine_name = ?1 \
2339         ORDER BY engine_name, activated_at IS NULL, activated_at"
2340    } else {
2341        "SELECT engine_name, model_id, key_version, dim, status, activated_at, superseded_at \
2342         FROM _embedding_models \
2343         ORDER BY engine_name, activated_at IS NULL, activated_at"
2344    };
2345    let mut stmt = conn.prepare(sql)?;
2346    let map_row = |row: &rusqlite::Row<'_>| {
2347        let dim_raw: i64 = row.get(3)?;
2348        let dimensions = u32::try_from(dim_raw).map_err(|_| {
2349            rusqlite::Error::FromSqlConversionFailure(
2350                3,
2351                rusqlite::types::Type::Integer,
2352                Box::new(std::io::Error::other(format!(
2353                    "_embedding_models.dim value {dim_raw} is outside the valid u32 range [0, {}]",
2354                    u32::MAX,
2355                ))),
2356            )
2357        })?;
2358        Ok(EmbeddingModelRegistryRecord {
2359            engine_name: row.get(0)?,
2360            model_id: row.get(1)?,
2361            key_version: row.get(2)?,
2362            dimensions,
2363            status: row.get(4)?,
2364            activated_at: row.get(5)?,
2365            superseded_at: row.get(6)?,
2366        })
2367    };
2368
2369    if let Some(engine) = engine_filter {
2370        stmt.query_map([engine], map_row)?
2371            .collect::<Result<Vec<_>, _>>()
2372            .map_err(Into::into)
2373    } else {
2374        stmt.query_map([], map_row)?
2375            .collect::<Result<Vec<_>, _>>()
2376            .map_err(Into::into)
2377    }
2378}
2379
2380// Test fixtures use the public policy constructor and a private lock namespace.
2381#[cfg(test)]
2382pub(crate) fn migration_test_policy() -> MigrationWritePolicy {
2383    MigrationWritePolicy::new(
2384        crate::DiskGuardEnvironment::capture()
2385            .resolve(None, None)
2386            .expect("test disk policy"),
2387        crate::PoolConfig::for_test()
2388            .volume_lock_dir
2389            .expect("test volume-lock directory"),
2390    )
2391    .expect("valid test migration policy")
2392}
2393
2394#[cfg(test)]
2395pub(crate) fn run_migrations_for_test(conn: &mut Connection) -> Result<u32, SqliteError> {
2396    run_migrations_with_policy(conn, &migration_test_policy())
2397}
2398
2399#[cfg(test)]
2400fn apply_schema_plan_for_test(
2401    conn: &mut Connection,
2402    plan: &ServiceSchemaPlan,
2403) -> Result<(), SqliteError> {
2404    apply_schema_plan_with_policy(conn, plan, &migration_test_policy())
2405}
2406
2407#[cfg(test)]
2408fn stage_attachment_cutover_for_test(conn: &mut Connection) -> Result<(), SqliteError> {
2409    stage_attachment_cutover_with_policy(conn, &migration_test_policy())
2410}
2411
2412#[cfg(test)]
2413fn finalize_attachment_cutover_for_test(conn: &mut Connection) -> Result<(), SqliteError> {
2414    finalize_attachment_cutover_with_policy(conn, &migration_test_policy())
2415}
2416
2417// =============================================================================
2418// Tests
2419// =============================================================================
2420
2421#[cfg(test)]
2422#[path = "entity_version_migration_measurement.rs"]
2423mod entity_version_measurement;
2424
2425#[cfg(test)]
2426#[path = "migrations_tests.rs"]
2427mod tests;
2428
2429#[cfg(test)]
2430#[path = "raw_migration_settlement_tests.rs"]
2431mod raw_settlement_tests;
2432
2433#[cfg(test)]
2434#[path = "git_note_index_migration_tests.rs"]
2435mod git_note_indexes;
2436
2437#[cfg(test)]
2438#[path = "entity_list_index_migration_tests.rs"]
2439mod entity_list_indexes;
2440
2441#[cfg(test)]
2442#[path = "schedule_core_index_migration_tests.rs"]
2443mod schedule_core_index_migration_tests;
2444
2445#[cfg(test)]
2446#[path = "comm_core_index_migration_tests.rs"]
2447mod comm_core_index_migration_tests;
2448
2449#[cfg(test)]
2450#[path = "knowledge_cursor_tag_migration_tests.rs"]
2451mod knowledge_cursor_tag_migration_tests;