VB-Toml to DB migration: sync toml to DB as first step

crates/but-db/src/lib.rs

@@ -46,15 +46,19 @@
 //! Add a new optional string named 'note' to ClaudePermissionRequest in @crates/but-db/tests/db/table/claude.rs
 //! ```
 #![expect(clippy::inconsistent_digit_grouping)]
+#![deny(missing_docs)]
 
 #[cfg(feature = "poll")]
+/// Polling helpers to watch for database-backed state changes.
 pub mod poll;
 
 mod handle;
 mod table;
 mod transaction;
 
+/// Cache database helpers and typed accessors.
 pub mod cache;
+/// Migration helpers for applying and configuring database schema updates.
 pub mod migration;
 
 use std::path::PathBuf;
@@ -69,6 +73,7 @@ pub use table::{
     gerrit_metadata::GerritMeta,
     forge_reviews::ForgeReview,
     ci_checks::CiCheck,
+    virtual_branches::{VbBranchTarget, VbStack, VbStackHead, VbState, VirtualBranchesSnapshot, VirtualBranchesHandle, VirtualBranchesHandleMut},
 };
 
 /// The migrations to run, in any order, as ordering is maintained by their date number.
@@ -83,6 +88,7 @@ pub const MIGRATIONS: &[&[M<'static>]] = &[
     table::gerrit_metadata::M,
     table::forge_reviews::M,
     table::ci_checks::M,
+    table::virtual_branches::M,
 ];
 
 /// A migration and all the necessary data associated with it to perform it once.

crates/but-db/src/migration.rs

@@ -161,16 +161,17 @@ const DIESEL_SCHEMA_MIGRATION_TABLE: &str =
 )";
 
 /// Improve parallelism and make it non-fatal.
-/// Blanket setting from https://github.com/the-lean-crate/criner/discussions/5, maybe needs tuning.
+/// Blanket setting from <https://github.com/the-lean-crate/criner/discussions/5>, maybe needs tuning.
 /// Also, it's a known issue, maybe order matters?
-/// https://github.com/diesel-rs/diesel/issues/2365#issuecomment-2899347817
+/// <https://github.com/diesel-rs/diesel/issues/2365#issuecomment-2899347817>
 /// TODO: the busy_timeout doesn't seem to be effective.
-pub(crate) fn improve_concurrency(conn: &rusqlite::Connection) -> anyhow::Result<()> {
+pub fn improve_concurrency(conn: &rusqlite::Connection) -> anyhow::Result<()> {
     let query = r#"
         PRAGMA journal_mode = WAL;               -- better write-concurrency,
         PRAGMA synchronous = NORMAL;             -- fsync only in critical moments,
         PRAGMA wal_autocheckpoint = 1000;        -- write WAL changes back every 1000 pages, for an average 1MB WAL file.,
         PRAGMA wal_checkpoint(TRUNCATE);         -- free some space by truncating possibly massive WAL files from the last run.,
+        PRAGMA foreign_keys = ON;                -- enforce FK integrity for normalized data.
         "#;
     conn.execute_batch(query)?;
     conn.busy_timeout(BUSY_TIMEOUT)?;

crates/but-db/src/poll.rs

@@ -4,12 +4,16 @@ use tokio::{sync::oneshot, task::JoinHandle};
 use crate::DbHandle;
 
 bitflags! {
-    /// What kind of data to listen to
+    /// What kind of data to listen to in [`crate::poll::poll_changes()`]
     #[derive(Default, Debug, Copy, Clone, Eq, PartialEq)]
     pub struct ItemKind: u8 {
+        /// Changes in `butler_actions`.
         const Actions = 1 << 0;
+        /// Changes in `workflows`.
         const Workflows = 1 << 1;
+        /// Changes in `hunk_assignments`.
         const Assignments = 1 << 2;
+        /// Changes in `workspace_rules`.
         const Rules = 1 << 3;
     }
 }
@@ -196,8 +200,11 @@ impl DbHandle {
     }
 }
 
+/// A running background watcher task and its cancellation channel.
 pub struct DBWatcherHandle {
+    /// Sender used to request graceful cancellation of the watcher task.
     pub cancel_tx: Option<oneshot::Sender<()>>,
+    /// Join handle for the spawned watcher task.
     pub handle: JoinHandle<()>,
 }
 
@@ -211,6 +218,9 @@ impl Drop for DBWatcherHandle {
     }
 }
 
+/// Start a background async watcher that emits events for all supported [`ItemKind`] values.
+///
+/// The watcher polls the database every 500ms and forwards detected item changes to `send_event`.
 pub fn watch_in_background(
     db: &DbHandle,
     send_event: impl Fn(ItemKind) -> anyhow::Result<()> + Send + Sync + 'static,

crates/but-db/src/table/butler_actions.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use serde::{Deserialize, Serialize};
 
 use crate::{DbHandle, M, Transaction};

crates/but-db/src/table/ci_checks.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use serde::{Deserialize, Serialize};
 
 use crate::{DbHandle, M, Transaction};

crates/but-db/src/table/claude.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use rusqlite::OptionalExtension;
 use serde::{Deserialize, Serialize};
 

crates/but-db/src/table/file_write_locks.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use serde::{Deserialize, Serialize};
 
 use crate::{DbHandle, M, Transaction};

crates/but-db/src/table/forge_reviews.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use serde::{Deserialize, Serialize};
 
 use crate::{DbHandle, M, Transaction};

crates/but-db/src/table/gerrit_metadata.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use rusqlite::OptionalExtension;
 use serde::{Deserialize, Serialize};
 

crates/but-db/src/table/hunk_assignments.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use serde::{Deserialize, Serialize};
 
 use crate::{DbHandle, M, Transaction};

crates/but-db/src/table/mod.rs

@@ -7,6 +7,7 @@ pub(crate) mod file_write_locks;
 pub(crate) mod forge_reviews;
 pub(crate) mod gerrit_metadata;
 pub(crate) mod hunk_assignments;
+pub(crate) mod virtual_branches;
 pub(crate) mod workflows;
 pub(crate) mod workspace_rules;