1use 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
27pub(crate) trait MigrationTransactions {
34 fn admitted<T>(
37 &mut self,
38 operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
39 ) -> Result<T, SqliteError>;
40}
41
42#[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 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
93pub struct Migration {
99 pub id: &'static str,
101 pub up_sql: &'static str,
103 pub down_sql: Option<&'static str>,
105 pub is_already_applied: Option<fn(&Connection) -> bool>,
109}
110
111pub struct ServiceSchemaPlan {
113 pub service: &'static str,
115 pub sqlite: &'static [Migration],
117 pub postgres: &'static [Migration],
119}
120
121const SCHEMA_VERSION_TABLE: &str = include_str!("../sql/schema-version-table.sql");
122
123pub 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
137pub 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
152pub(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
172fn apply_service_migration(
175 conn: &Connection,
176 plan: &ServiceSchemaPlan,
177 migration: &Migration,
178 admission: &WriteAdmission,
179) -> Result<(), SqliteError> {
180 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 if let Some(check) = migration.is_already_applied {
196 if check(&tx) {
197 return Ok(());
198 }
199 }
200
201 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
257pub struct VersionedMigration {
267 pub version: u32,
269 pub name: &'static str,
271 pub up: &'static str,
274}
275
276const 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
350pub(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
426fn 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 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
449fn 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
496pub(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
518pub const ATTACHMENT_CUTOVER_VERSION: u32 = 21;
520
521pub fn latest_schema_version() -> u32 {
526 MIGRATIONS.last().map(|m| m.version).unwrap_or(0)
527}
528
529pub const ANN_WRITE_LOG_DDL: &str = V11_UP;
537
538pub const ANN_WRITE_LOG_MODEL_SEQ_INDEX_DDL: &str = V12_UP;
543
544pub const ANN_CONSUMER_PENDING_DDL: &str = include_str!("../sql/ann-consumer-pending-ddl.sql");
551
552pub const VECTOR_PROVENANCE_DDL: &str = V43_UP;
555
556pub const EMBEDDING_MODELS_DDL: &str = include_str!("../sql/embedding-models-ddl.sql");
562
563pub 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 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#[derive(Clone, Copy, Debug, Eq, PartialEq)]
907pub enum AttachmentCutoverStatus {
908 Pending,
910 Incomplete,
912 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
997pub 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
1015fn 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
1030pub 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 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
1115fn 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 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
1275pub 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
1287pub 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
1298pub(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#[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
1489pub 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
1501pub 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
1512pub(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
1546fn 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
1563fn 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
1639fn 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
1655pub fn schema_version_probe() -> khive_storage::types::SqlStatement {
1657 khive_storage::types::SqlStatement::new(SCHEMA_VERSION_PROBE_SQL, Vec::new())
1658}
1659
1660pub 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
1677pub 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
1686pub 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1696pub struct PageAccounting {
1697 pub page_size: u64,
1699 pub page_count: u64,
1701 pub freelist_count: u64,
1704}
1705
1706pub 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
1722pub 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
1736pub 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 validate_applied_migration_ledger(conn, current_version)?;
1768 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
1786pub 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 pub(crate) static STALE_READ_BARRIER: Mutex<Option<Arc<Barrier>>> = Mutex::new(None);
1801 pub(crate) static LOCKED_FAST_FORWARDS: AtomicU32 = AtomicU32::new(0);
1803 pub(crate) static BUSY_OBSERVED: std::sync::atomic::AtomicBool =
1807 std::sync::atomic::AtomicBool::new(false);
1808
1809 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 pub(crate) static WINNER_COMMITTED: std::sync::atomic::AtomicBool =
1820 std::sync::atomic::AtomicBool::new(false);
1821 pub(crate) static LOSER_SAW_WINNER_COMMIT: std::sync::atomic::AtomicBool =
1826 std::sync::atomic::AtomicBool::new(false);
1827
1828 std::thread_local! {
1829 pub(crate) static PARTICIPATE: std::cell::Cell<bool> =
1832 const { std::cell::Cell::new(false) };
1833 pub(crate) static FIRST_BEGIN_DONE: std::cell::Cell<bool> =
1835 const { std::cell::Cell::new(false) };
1836 }
1837}
1838
1839fn 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
1889pub 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 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 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
1938fn 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
1959enum MigrationStep {
1961 Applied,
1963 AppliedBySibling(u32),
1966 Deferred,
1968}
1969
1970fn 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 #[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 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 writes.admitted(|conn| validate_applied_migration_ledger(conn, applied_version))?;
2031
2032 Ok(applied_version)
2033}
2034
2035fn 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 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 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
2076fn apply_versioned_migration(
2079 conn: &mut Connection,
2080 migration: &VersionedMigration,
2081 admission: &WriteAdmission,
2082 latest_version: u32,
2083) -> Result<MigrationStep, SqliteError> {
2084 #[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 #[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 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 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 test_sync::LOSER_SAW_WINNER_COMMIT
2137 .store(test_sync::WINNER_COMMITTED.load(SeqCst), SeqCst);
2138 }
2139 }
2140
2141 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 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 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 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 pub engine_name: String,
2278 pub model_id: String,
2280 pub key_version: String,
2282 pub dimensions: u32,
2284 pub status: String,
2286 pub activated_at: Option<i64>,
2288 pub superseded_at: Option<i64>,
2290}
2291
2292pub 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
2319pub(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#[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#[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;