Skip to main content

oak_core/
sqlite.rs

1use rusqlite::{params, Connection, OptionalExtension};
2pub mod file_inspect;
3pub mod refs_inspect;
4pub mod tree_inspect;
5use std::collections::{HashMap, HashSet};
6use std::path::{Path, PathBuf};
7use std::sync::atomic::{AtomicU64, Ordering};
8use std::sync::Mutex;
9
10use crate::hash::hash_bytes;
11use crate::{
12    Blob, Branch, BranchStatus, CanonicalChangeSetV1, ChangeScopeV1, ChangeType, ChunkInfo,
13    CloseReason, Commit, FileChange, FileMode, Hash, Manifest, ManifestEntry, MetadataKey,
14    OakError, Result, Tree, TreeEntry, TreeEntryKind, CHANGE_SET_OBJECT_FORMAT_V1,
15};
16
17use crate::traits::{BlobSource, Repository, StatCacheEntry};
18
19/// Decode one stored `branches` row. A column that cannot be decoded yields
20/// an [`crate::UnreadableBranch`] naming the branch and column (fb-118);
21/// legacy SQLite-default timestamps decode losslessly.
22fn decode_branch_row(
23    name: String,
24    description: Option<String>,
25    parent_branch: Option<String>,
26    status: BranchStatus,
27    close_reason: Option<String>,
28    created_at: &str,
29) -> std::result::Result<Branch, crate::UnreadableBranch> {
30    let unreadable = |name: &str, column| crate::UnreadableBranch {
31        name: name.to_string(),
32        status,
33        column,
34    };
35    let Some(created_at) = crate::parse_stored_timestamp(created_at) else {
36        return Err(unreadable(&name, "created_at"));
37    };
38    let close_reason = match close_reason.as_deref().map(CloseReason::parse).transpose() {
39        Ok(reason) => reason,
40        Err(_) => return Err(unreadable(&name, "close_reason")),
41    };
42    Ok(Branch {
43        name,
44        description,
45        parent_branch,
46        status,
47        close_reason,
48        created_at,
49    })
50}
51
52fn advance_description_generation(conn: &Connection) -> Result<i64> {
53    conn.query_row(
54        "UPDATE branch_description_clock SET generation = generation + 1
55         WHERE singleton = 1 AND generation < 9223372036854775807 RETURNING generation",
56        [],
57        |row| row.get(0),
58    )
59    .map_err(|error| {
60        OakError::Database(format!(
61            "could not advance branch description generation: {error}"
62        ))
63    })
64}
65
66#[derive(Debug, Clone, PartialEq, Eq)]
67pub struct ChangeCaptureProvenance {
68    pub owner: String,
69    pub name: String,
70    pub origin: Option<String>,
71    pub source_branch: String,
72    pub base_commit: Option<Hash>,
73    pub captured_at: chrono::DateTime<chrono::Utc>,
74}
75
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct StoredChangeCapture {
78    pub capture_id: String,
79    pub change_set: CanonicalChangeSetV1,
80    pub provenance: ChangeCaptureProvenance,
81}
82
83struct ChangeCaptureRow {
84    change_id: String,
85    format_version: i64,
86    owner: String,
87    name: String,
88    origin: Option<String>,
89    source_branch: String,
90    base_commit: Option<String>,
91    captured_at: String,
92}
93
94struct ChangeSetRow {
95    schema_version: i64,
96    object_format: String,
97    base_tree: String,
98    result_tree: String,
99    scope_kind: String,
100    scope_paths_json: String,
101    descriptor_json: String,
102    created_at: String,
103}
104
105const MIGRATION_BASELINE: &str = include_str!("migrations/sqlite/0000_baseline.sql");
106const MIGRATION_0001_RELAX_BRANCH_FKS_AND_MESSAGE: &str =
107    include_str!("migrations/sqlite/0001_relax_branch_fks_and_message.sql");
108const MIGRATION_0002_RELAX_COMMITS_PARENT_HASH_FK: &str =
109    include_str!("migrations/sqlite/0002_relax_commits_parent_hash_fk.sql");
110const MIGRATION_0003_STAT_CACHE: &str = include_str!("migrations/sqlite/0003_stat_cache.sql");
111const MIGRATION_0004_STAT_CACHE_CTIME: &str =
112    include_str!("migrations/sqlite/0004_stat_cache_ctime.sql");
113const MIGRATION_0005_MERGE_PARENT_INDEX: &str =
114    include_str!("migrations/sqlite/0005_merge_parent_index.sql");
115const MIGRATION_0006_DROP_REDUNDANT_TREE_ENTRIES_INDEX: &str =
116    include_str!("migrations/sqlite/0006_drop_redundant_tree_entries_index.sql");
117const MIGRATION_0007_BLOBS_CODEC: &str = include_str!("migrations/sqlite/0007_blobs_codec.sql");
118const MIGRATION_0008_TREES_CONTENT: &str = include_str!("migrations/sqlite/0008_trees_content.sql");
119const MIGRATION_0009_RELAX_BLOB_CHUNKS_FK: &str =
120    include_str!("migrations/sqlite/0009_relax_blob_chunks_fk.sql");
121const MIGRATION_0010_BRANCH_CLOSE_REASON: &str =
122    include_str!("migrations/sqlite/0010_branch_close_reason.sql");
123const MIGRATION_0011_SERVE_MAPPING_PROOFS: &str =
124    include_str!("migrations/sqlite/0011_serve_mapping_proofs.sql");
125
126/// SQLite-backed repository for local storage
127pub struct SqliteRepository {
128    conn: Mutex<Connection>,
129    /// Whole-tree flattens served through this handle
130    /// ([`Repository::walk_tree`], and [`Repository::get_manifest`], which
131    /// goes through it). Each one reads every directory of a tree, so
132    /// commands with a "loads HEAD once" budget assert on it in tests.
133    tree_flattens: AtomicU64,
134    /// Individual tree objects read through this handle
135    /// ([`Repository::get_tree`]) — what any flatten, however it is spelled,
136    /// is made of.
137    tree_reads: AtomicU64,
138}
139
140/// One row per migration. Mirrors the structure on the postgres side. New
141/// migrations append to `MIGRATIONS` below; existing entries are immutable
142/// once shipped.
143struct Migration {
144    version: &'static str,
145    sql: &'static str,
146    required: bool,
147}
148
149/// Canonical ordering of migrations. Migrations 001..011 were squashed into
150/// `0000_baseline` on 2026-05-05; the `migration_already_applied` heuristic
151/// recognises previously-migrated repositories and marks the baseline as
152/// applied without re-running its DDL.
153const MIGRATIONS: &[Migration] = &[
154    Migration {
155        version: "0000_baseline",
156        sql: MIGRATION_BASELINE,
157        required: true,
158    },
159    Migration {
160        version: "0001_relax_branch_fks_and_message",
161        sql: MIGRATION_0001_RELAX_BRANCH_FKS_AND_MESSAGE,
162        required: true,
163    },
164    Migration {
165        version: "0002_relax_commits_parent_hash_fk",
166        sql: MIGRATION_0002_RELAX_COMMITS_PARENT_HASH_FK,
167        required: true,
168    },
169    Migration {
170        version: "0003_stat_cache",
171        sql: MIGRATION_0003_STAT_CACHE,
172        required: true,
173    },
174    Migration {
175        version: "0004_stat_cache_ctime",
176        sql: MIGRATION_0004_STAT_CACHE_CTIME,
177        required: true,
178    },
179    Migration {
180        version: "0005_merge_parent_index",
181        sql: MIGRATION_0005_MERGE_PARENT_INDEX,
182        required: true,
183    },
184    Migration {
185        version: "0006_drop_redundant_tree_entries_index",
186        sql: MIGRATION_0006_DROP_REDUNDANT_TREE_ENTRIES_INDEX,
187        required: true,
188    },
189    Migration {
190        version: "0007_blobs_codec",
191        sql: MIGRATION_0007_BLOBS_CODEC,
192        required: true,
193    },
194    Migration {
195        version: "0008_trees_content",
196        sql: MIGRATION_0008_TREES_CONTENT,
197        required: true,
198    },
199    Migration {
200        version: "0009_relax_blob_chunks_fk",
201        sql: MIGRATION_0009_RELAX_BLOB_CHUNKS_FK,
202        required: true,
203    },
204    Migration {
205        version: "0010_branch_close_reason",
206        sql: MIGRATION_0010_BRANCH_CLOSE_REASON,
207        required: true,
208    },
209    Migration {
210        version: "0011_serve_mapping_proofs",
211        sql: MIGRATION_0011_SERVE_MAPPING_PROOFS,
212        required: true,
213    },
214    Migration {
215        version: "0012_pending_branch_description",
216        sql: include_str!("migrations/sqlite/0012_pending_branch_description.sql"),
217        required: true,
218    },
219    Migration {
220        version: "0013_branch_description_generation",
221        sql: include_str!("migrations/sqlite/0013_branch_description_generation.sql"),
222        required: true,
223    },
224    Migration {
225        version: "0014_change_captures",
226        sql: include_str!("migrations/sqlite/0014_change_captures.sql"),
227        required: true,
228    },
229    Migration {
230        version: "0015_serve_published_objects",
231        sql: include_str!("migrations/sqlite/0015_serve_published_objects.sql"),
232        required: true,
233    },
234    Migration {
235        version: "0016_serve_stage_objects",
236        sql: include_str!("migrations/sqlite/0016_serve_stage_objects.sql"),
237        required: true,
238    },
239    Migration {
240        version: "0017_tag_releases",
241        sql: include_str!("migrations/sqlite/0017_tag_releases.sql"),
242        required: true,
243    },
244    Migration {
245        version: "0018_drop_tags_commit_fk",
246        sql: include_str!("migrations/sqlite/0018_drop_tags_commit_fk.sql"),
247        required: true,
248    },
249];
250
251/// zstd level for at-rest compression. 3 is the default — fast, and tree
252/// content / source blobs are highly compressible, so a higher level buys
253/// little for the per-write cost during bulk import.
254const ZSTD_LEVEL: i32 = 3;
255
256/// `blobs.codec` markers.
257const CODEC_RAW: i64 = 0;
258const CODEC_ZSTD: i64 = 1;
259
260fn zstd_compress(data: &[u8]) -> Result<Vec<u8>> {
261    zstd::encode_all(data, ZSTD_LEVEL)
262        .map_err(|e| OakError::Database(format!("zstd compress: {e}")))
263}
264
265fn zstd_decompress(data: &[u8]) -> Result<Vec<u8>> {
266    zstd::decode_all(data).map_err(|e| OakError::Database(format!("zstd decompress: {e}")))
267}
268
269/// Decompress a stored tree row. A manifest walk reads one row per directory,
270/// and [`zstd_decompress`] builds a fresh decompression context per call,
271/// which costs several times the decode itself on rows this small. Reuse one
272/// context and output buffer per thread. Tree frames don't record their
273/// decoded size, so the buffer grows on demand; rows past `MAX_REUSED` (or
274/// corrupt ones) go through the streaming decoder, which reports the error.
275fn zstd_decompress_tree(data: &[u8]) -> Result<Vec<u8>> {
276    use std::cell::RefCell;
277    const INITIAL: usize = 64 * 1024;
278    const KEEP: usize = 1024 * 1024;
279    const MAX_REUSED: usize = 16 * 1024 * 1024;
280    thread_local! {
281        static TREE_DECODER: RefCell<Option<(zstd::bulk::Decompressor<'static>, Vec<u8>)>> =
282            const { RefCell::new(None) };
283    }
284    // An empty row is an incomplete frame to the streaming decoder but
285    // decodes to nothing in bulk; keep the streaming decoder's error.
286    if data.is_empty() {
287        return zstd_decompress(data);
288    }
289    TREE_DECODER.with(|cell| {
290        let mut slot = cell.borrow_mut();
291        if slot.is_none() {
292            let decoder = zstd::bulk::Decompressor::new()
293                .map_err(|e| OakError::Database(format!("zstd decompress: {e}")))?;
294            *slot = Some((decoder, Vec::with_capacity(INITIAL)));
295        }
296        let (decoder, buf) = slot.as_mut().expect("decoder initialized above");
297        loop {
298            buf.clear();
299            match decoder.decompress_to_buffer(data, buf) {
300                Ok(_) => {
301                    let raw = buf.as_slice().to_vec();
302                    if buf.capacity() > KEEP {
303                        *buf = Vec::with_capacity(INITIAL);
304                    }
305                    return Ok(raw);
306                }
307                Err(_) if buf.capacity() < MAX_REUSED => buf.reserve(buf.capacity() * 4),
308                Err(_) => return zstd_decompress(data),
309            }
310        }
311    })
312}
313
314/// Encode blob content for storage: zstd when it actually shrinks, else raw.
315/// Returns the bytes to store and the codec marker. Hashing is always over the
316/// plaintext, so this choice never affects a blob's content-addressed identity.
317fn encode_blob(content: &[u8]) -> Result<(std::borrow::Cow<'_, [u8]>, i64)> {
318    let compressed = zstd_compress(content)?;
319    if compressed.len() < content.len() {
320        Ok((std::borrow::Cow::Owned(compressed), CODEC_ZSTD))
321    } else {
322        Ok((std::borrow::Cow::Borrowed(content), CODEC_RAW))
323    }
324}
325
326/// Decode stored blob content given its codec marker.
327fn decode_blob(content: Vec<u8>, codec: i64) -> Result<Vec<u8>> {
328    if codec == CODEC_ZSTD {
329        zstd_decompress(&content)
330    } else {
331        Ok(content)
332    }
333}
334
335/// Insert a tree in the new on-disk format (migration 0008): its canonical hash
336/// preimage, zstd-compressed, as a single `trees.content` row — no per-entry
337/// `tree_entries` rows. `conn` may be a plain connection, a transaction, or a
338/// savepoint (all deref to `Connection`).
339fn insert_tree_row(conn: &Connection, tree: &Tree) -> Result<()> {
340    let canonical = Tree::new(tree.entries.clone())?;
341    if canonical.hash != tree.hash {
342        return Err(OakError::InvalidHash(format!(
343            "tree {} does not match content hash {}",
344            tree.hash, canonical.hash
345        )));
346    }
347    let content = zstd_compress(&canonical.canonical_bytes())?;
348    conn.execute(
349        "INSERT OR IGNORE INTO trees (hash, content) VALUES (?1, ?2)",
350        params![canonical.hash.as_str(), content],
351    )
352    .map_err(|e| OakError::Database(e.to_string()))?;
353    Ok(())
354}
355
356/// Read a legacy tree (one stored as `tree_entries` rows, i.e. `trees.content`
357/// is NULL). Used as the fallback path in `get_tree` for repos written before
358/// migration 0008 / not yet compacted.
359fn read_tree_entries(conn: &Connection, hash: &Hash) -> Result<Tree> {
360    let mut stmt = conn
361        .prepare("SELECT name, kind, hash, mode FROM tree_entries WHERE tree_hash = ?1")
362        .map_err(|e| OakError::Database(e.to_string()))?;
363
364    let mut entries: Vec<TreeEntry> = stmt
365        .query_map(params![hash.as_str()], |row| {
366            let name: String = row.get(0)?;
367            let kind_str: String = row.get(1)?;
368            let entry_hash: String = row.get(2)?;
369            let mode_str: String = row.get(3)?;
370
371            let kind = match kind_str.as_str() {
372                "tree" => TreeEntryKind::Tree,
373                _ => TreeEntryKind::Blob,
374            };
375            let mode = match mode_str.as_str() {
376                "executable" => FileMode::Executable,
377                "symlink" => FileMode::Symlink,
378                _ => FileMode::Regular,
379            };
380            Ok(TreeEntry {
381                name,
382                kind,
383                hash: Hash(entry_hash),
384                mode,
385            })
386        })
387        .map_err(|e| OakError::Database(e.to_string()))?
388        .collect::<std::result::Result<Vec<_>, _>>()
389        .map_err(|e| OakError::Database(e.to_string()))?;
390
391    // Re-sort to match Tree::new canonical ordering (PK guarantees uniqueness,
392    // not row order).
393    entries.sort_by(|a, b| a.name.cmp(&b.name));
394    Ok(Tree {
395        hash: hash.clone(),
396        entries,
397    })
398}
399
400fn table_exists(conn: &Connection, name: &str) -> rusqlite::Result<bool> {
401    conn.query_row(
402        "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1)",
403        params![name],
404        |row| row.get(0),
405    )
406}
407
408fn column_exists(conn: &Connection, table: &str, column: &str) -> Result<bool> {
409    let mut stmt = conn
410        .prepare(&format!("PRAGMA table_info({table})"))
411        .map_err(|e| OakError::Database(e.to_string()))?;
412    let mut rows = stmt
413        .query([])
414        .map_err(|e| OakError::Database(e.to_string()))?;
415    while let Some(row) = rows.next().map_err(|e| OakError::Database(e.to_string()))? {
416        let name: String = row.get(1).map_err(|e| OakError::Database(e.to_string()))?;
417        if name == column {
418            return Ok(true);
419        }
420    }
421    Ok(false)
422}
423
424/// Heuristic: has this migration already been applied? A positive result
425/// lets the runner record the version without re-executing its DDL — used
426/// when an existing repository (created under the pre-squash chain) is
427/// opened by a build that only knows about the baseline.
428fn migration_already_applied(version: &str, conn: &Connection) -> Result<bool> {
429    match version {
430        // Baseline is "applied" iff the schema already has the canonical
431        // `commits` table — created by the original 001_initial and never
432        // dropped, so its presence implies the squashed baseline's effects
433        // are already in place.
434        "0000_baseline" => {
435            table_exists(conn, "commits").map_err(|e| OakError::Database(e.to_string()))
436        }
437        // 0001 rebuilds `commits`, `branches`, `branch_heads` to drop the
438        // strict FKs on branch_name/parent_branch and to make
439        // `commits.message` nullable. A freshly-created DB (built from the
440        // current `0000_baseline`) already has the relaxed schema, so the
441        // migration is a no-op there. Detect that case by checking whether
442        // the stored CREATE TABLE for `commits` still has `message TEXT
443        // NOT NULL` — the marker of the pre-relax schema.
444        "0001_relax_branch_fks_and_message" => {
445            let sql: Option<String> = conn
446                .query_row(
447                    "SELECT sql FROM sqlite_master WHERE type='table' AND name='commits'",
448                    [],
449                    |row| row.get(0),
450                )
451                .optional()
452                .map_err(|e| OakError::Database(e.to_string()))?;
453            // No `commits` table at all means the baseline hasn't run yet;
454            // leave to the baseline migration to set up. If `commits` is
455            // present and `message` is already nullable, the relax-pass is
456            // implicit and we mark this version applied without re-running.
457            Ok(sql
458                .map(|s| !s.contains("message TEXT NOT NULL"))
459                .unwrap_or(false))
460        }
461        // 0002 rebuilds `commits` to drop the FK on `parent_hash`. The
462        // current baseline still has that FK, so a freshly-applied
463        // baseline always needs this migration to run; only DBs that have
464        // already been migrated (the stored `commits` CREATE TABLE no
465        // longer mentions a FOREIGN KEY clause for parent_hash) should
466        // mark this version applied without re-running.
467        "0002_relax_commits_parent_hash_fk" => {
468            let sql: Option<String> = conn
469                .query_row(
470                    "SELECT sql FROM sqlite_master WHERE type='table' AND name='commits'",
471                    [],
472                    |row| row.get(0),
473                )
474                .optional()
475                .map_err(|e| OakError::Database(e.to_string()))?;
476            Ok(sql
477                .map(|s| !s.contains("FOREIGN KEY (parent_hash)"))
478                .unwrap_or(false))
479        }
480        // These migrations are single ADD COLUMN statements. If a repository
481        // was already upgraded but missed the corresponding tracker row, the
482        // column is the authoritative marker; re-running the ALTER would fail
483        // with "duplicate column name" and block opening the repo.
484        "0007_blobs_codec" => column_exists(conn, "blobs", "codec"),
485        "0008_trees_content" => column_exists(conn, "trees", "content"),
486        "0010_branch_close_reason" => column_exists(conn, "branches", "close_reason"),
487        "0012_pending_branch_description" => column_exists(conn, "branches", "description_pending"),
488        _ => Ok(false),
489    }
490}
491
492fn run_migrations(conn: &Connection) -> Result<()> {
493    conn.execute_batch(
494        "CREATE TABLE IF NOT EXISTS schema_migrations (
495            version TEXT PRIMARY KEY,
496            applied_at TEXT NOT NULL DEFAULT (datetime('now')),
497            succeeded INTEGER NOT NULL DEFAULT 1
498        )",
499    )
500    .map_err(|e| OakError::Database(e.to_string()))?;
501
502    for m in MIGRATIONS {
503        let already: Option<i64> = conn
504            .query_row(
505                "SELECT succeeded FROM schema_migrations WHERE version = ?1",
506                params![m.version],
507                |row| row.get(0),
508            )
509            .optional()
510            .map_err(|e| OakError::Database(e.to_string()))?;
511        if already == Some(1) {
512            continue;
513        }
514
515        // Tracker doesn't know about this migration. If the schema already
516        // reflects it (squashed baseline running against a database that
517        // was migrated under the old per-step chain), mark applied without
518        // re-running the DDL.
519        if migration_already_applied(m.version, conn)? {
520            conn.execute(
521                "INSERT INTO schema_migrations (version, succeeded) VALUES (?1, 1)
522                 ON CONFLICT(version) DO UPDATE SET succeeded = 1",
523                params![m.version],
524            )
525            .map_err(|e| OakError::Database(e.to_string()))?;
526            continue;
527        }
528
529        match conn.execute_batch(m.sql) {
530            Ok(_) => {
531                conn.execute(
532                    "INSERT INTO schema_migrations (version, succeeded) VALUES (?1, 1)
533                     ON CONFLICT(version) DO UPDATE SET succeeded = 1",
534                    params![m.version],
535                )
536                .map_err(|e| OakError::Database(e.to_string()))?;
537            }
538            Err(e) if m.required => {
539                return Err(OakError::Database(format!(
540                    "migration {} failed: {}",
541                    m.version, e
542                )));
543            }
544            Err(_) => {
545                // Best-effort migration — record as attempted so we don't
546                // retry every connect, but don't fail.
547                conn.execute(
548                    "INSERT INTO schema_migrations (version, succeeded) VALUES (?1, 0)
549                     ON CONFLICT(version) DO NOTHING",
550                    params![m.version],
551                )
552                .map_err(|e| OakError::Database(e.to_string()))?;
553            }
554        }
555    }
556    Ok(())
557}
558
559/// Restrict a freshly-created repo database to owner-only access (`0600`).
560///
561/// The repo `oak.db` can hold the user's API token (persisted on `oak clone`
562/// / `oak create`), so it must not land at the umask default (typically
563/// `0644`, world-readable) inside the working tree — mirroring the `0600`
564/// handling of `~/.oak/credentials`. No-op on non-Unix; best-effort (a chmod
565/// failure must not break opening the repo).
566fn harden_db_file_permissions(db_path: &Path) {
567    #[cfg(unix)]
568    {
569        use std::os::unix::fs::PermissionsExt;
570        let _ = std::fs::set_permissions(db_path, std::fs::Permissions::from_mode(0o600));
571    }
572    #[cfg(not(unix))]
573    {
574        let _ = db_path;
575    }
576}
577
578fn capture_integrity(capture_id: &str, detail: &str) -> OakError {
579    OakError::ChangeCaptureIntegrity {
580        capture_id: capture_id.to_string(),
581        detail: detail.to_string(),
582    }
583}
584
585fn validate_capture_id(capture_id: &str) -> Result<()> {
586    let suffix = capture_id
587        .strip_prefix("capture-")
588        .ok_or_else(|| capture_integrity(capture_id, "invalid capture occurrence identifier"))?;
589    if suffix.len() != 32
590        || !suffix
591            .bytes()
592            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
593    {
594        return Err(capture_integrity(
595            capture_id,
596            "invalid capture occurrence identifier",
597        ));
598    }
599    Ok(())
600}
601
602fn parse_native_hash(capture_id: &str, value: &str, label: &str) -> Result<Hash> {
603    if value.len() != 64
604        || !value
605            .bytes()
606            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
607    {
608        return Err(capture_integrity(
609            capture_id,
610            &format!("invalid {label} identity"),
611        ));
612    }
613    Hash::from_hex(value)
614        .map_err(|_| capture_integrity(capture_id, &format!("invalid {label} identity")))
615}
616
617fn validate_capture_segment(capture_id: &str, value: &str, label: &str) -> Result<()> {
618    if value.is_empty()
619        || value.len() > 255
620        || value.trim() != value
621        || value == "."
622        || value == ".."
623        || value
624            .chars()
625            .any(|c| c.is_whitespace() || c.is_control() || c == '/' || c == '\\')
626    {
627        return Err(capture_integrity(
628            capture_id,
629            &format!("invalid stored {label}"),
630        ));
631    }
632    Ok(())
633}
634
635fn validate_capture_branch(capture_id: &str, branch: &str) -> Result<()> {
636    if branch.is_empty()
637        || branch.trim() != branch
638        || branch
639            .chars()
640            .any(|c| c.is_whitespace() || c.is_control() || c == '/' || c == '\\')
641    {
642        return Err(capture_integrity(
643            capture_id,
644            "invalid stored source branch",
645        ));
646    }
647    Ok(())
648}
649
650fn validate_capture_origin(capture_id: &str, origin: &str) -> Result<()> {
651    if origin.len() > 2_048
652        || origin.chars().any(|c| c.is_whitespace() || c.is_control())
653        || origin.contains(['?', '#'])
654    {
655        return Err(capture_integrity(
656            capture_id,
657            "invalid stored repository origin",
658        ));
659    }
660    let authority_and_path = origin
661        .strip_prefix("https://")
662        .or_else(|| origin.strip_prefix("http://"))
663        .ok_or_else(|| capture_integrity(capture_id, "invalid stored repository origin"))?;
664    let authority = authority_and_path.split('/').next().unwrap_or_default();
665    if authority.is_empty() || authority.contains('@') {
666        return Err(capture_integrity(
667            capture_id,
668            "invalid stored repository origin",
669        ));
670    }
671    Ok(())
672}
673
674fn validate_capture_provenance(
675    capture_id: &str,
676    owner: &str,
677    name: &str,
678    origin: Option<&str>,
679    source_branch: &str,
680    base_commit: Option<&Hash>,
681) -> Result<()> {
682    validate_capture_segment(capture_id, owner, "repository owner")?;
683    validate_capture_segment(capture_id, name, "repository name")?;
684    validate_capture_branch(capture_id, source_branch)?;
685    if let Some(origin) = origin {
686        validate_capture_origin(capture_id, origin)?;
687    }
688    if let Some(base_commit) = base_commit {
689        parse_native_hash(capture_id, base_commit.as_str(), "base commit")?;
690    }
691    Ok(())
692}
693
694fn effective_head_in_connection(conn: &Connection, branch: &str) -> Result<Option<Hash>> {
695    let mut seen = HashSet::new();
696    let mut current = branch.to_string();
697    loop {
698        if !seen.insert(current.clone()) {
699            return Ok(None);
700        }
701        let head: Option<String> = conn
702            .query_row(
703                "SELECT head_hash FROM branch_heads WHERE branch_name = ?1",
704                [current.as_str()],
705                |row| row.get(0),
706            )
707            .optional()
708            .map_err(|error| OakError::Database(error.to_string()))?;
709        if let Some(head) = head {
710            return Ok(Some(Hash(head)));
711        }
712        let parent: Option<Option<String>> = conn
713            .query_row(
714                "SELECT parent_branch FROM branches WHERE name = ?1",
715                [current.as_str()],
716                |row| row.get(0),
717            )
718            .optional()
719            .map_err(|error| OakError::Database(error.to_string()))?;
720        match parent.flatten() {
721            Some(parent) => current = parent,
722            None => return Ok(None),
723        }
724    }
725}
726
727fn validate_capture_base_in_connection(
728    conn: &Connection,
729    capture_id: &str,
730    base_commit: Option<&Hash>,
731    base_tree: &Hash,
732) -> Result<()> {
733    let Some(base_commit) = base_commit else {
734        if base_tree != &Tree::empty_hash() {
735            return Err(capture_integrity(
736                capture_id,
737                "a headless capture must use the canonical empty base tree",
738            ));
739        }
740        return Ok(());
741    };
742    let manifest_hash: Option<String> = conn
743        .query_row(
744            "SELECT manifest_hash FROM commits WHERE hash = ?1",
745            [base_commit.as_str()],
746            |row| row.get(0),
747        )
748        .optional()
749        .map_err(|error| OakError::Database(error.to_string()))?;
750    let Some(manifest_hash) = manifest_hash else {
751        return Err(capture_integrity(
752            capture_id,
753            "the recorded base commit is unavailable",
754        ));
755    };
756    let manifest_hash = parse_native_hash(capture_id, &manifest_hash, "base commit tree")?;
757    if &manifest_hash != base_tree {
758        return Err(capture_integrity(
759            capture_id,
760            "the descriptor base tree does not match the recorded base commit",
761        ));
762    }
763    Ok(())
764}
765
766/// SQLite can report CANTOPEN when a full filesystem prevents WAL/SHM
767/// creation. Consult free space only after that specific failure; permissions
768/// and malformed database errors must retain their original diagnosis.
769fn sqlite_open_error(path: &Path, error: rusqlite::Error) -> OakError {
770    if matches!(&error, rusqlite::Error::SqliteFailure(code, _) if code.code == rusqlite::ErrorCode::DiskFull)
771    {
772        return OakError::DiskFull {
773            path: path.display().to_string(),
774        };
775    }
776    diagnose_open_storage_error(path, OakError::Database(error.to_string()))
777}
778
779fn diagnose_open_storage_error(path: &Path, error: OakError) -> OakError {
780    let OakError::Database(message) = &error else {
781        return error;
782    };
783    let sqlite_full = message == "database or disk is full";
784    let may_be_full = message.starts_with("unable to open database file")
785        || message.starts_with("disk I/O error");
786    if sqlite_full || (may_be_full && filesystem_is_full(path)) {
787        OakError::DiskFull {
788            path: path.display().to_string(),
789        }
790    } else {
791        error
792    }
793}
794
795#[cfg(unix)]
796fn filesystem_is_full(path: &Path) -> bool {
797    use std::os::unix::ffi::OsStrExt;
798    let Some(existing) = path.ancestors().find(|p| p.exists()) else {
799        return false;
800    };
801    let Ok(path) = std::ffi::CString::new(existing.as_os_str().as_bytes()) else {
802        return false;
803    };
804    let mut stats = std::mem::MaybeUninit::<libc::statvfs>::uninit();
805    // SAFETY: path is NUL terminated and stats points to writable storage.
806    if unsafe { libc::statvfs(path.as_ptr(), stats.as_mut_ptr()) } != 0 {
807        return false;
808    }
809    // SAFETY: statvfs initialized stats on success.
810    let stats = unsafe { stats.assume_init() };
811    stats.f_bavail == 0
812}
813
814#[cfg(not(unix))]
815fn filesystem_is_full(_path: &Path) -> bool {
816    false
817}
818
819/// Buffer between SQLite incremental blob I/O and the decoder.
820const STORED_BLOB_READ_BYTES: usize = 1024 * 1024;
821
822/// One open incremental-I/O handle on a `blobs.content` row, together with
823/// the read-only connection it belongs to.
824///
825/// The handle must stay open for the whole stream: SQLite finds an offset in
826/// a large row by walking its overflow-page chain, and only an open handle
827/// remembers that chain, so re-opening per read makes a sequential read
828/// quadratic. A handle borrows its connection, and the repository's own
829/// connection sits behind a mutex that must not stay locked between reads,
830/// so the stream owns a private read-only connection instead.
831struct StoredBlobRows {
832    // Field order is drop order: the handle is closed before its connection.
833    blob: rusqlite::blob::Blob<'static>,
834    _conn: Box<Connection>,
835}
836
837// SAFETY: `blob` borrows only `_conn`, which this struct owns exclusively and
838// which is never shared, so the pair is used by one thread at a time and may
839// move between threads together (`Connection` itself is `Send`).
840unsafe impl Send for StoredBlobRows {}
841
842impl StoredBlobRows {
843    fn open(db_path: &Path, rowid: i64) -> Result<Self> {
844        let conn = Box::new(
845            Connection::open_with_flags(db_path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)
846                .map_err(|e| OakError::Database(e.to_string()))?,
847        );
848        let blob = conn
849            .blob_open(rusqlite::MAIN_DB, "blobs", "content", rowid, true)
850            .map_err(|e| OakError::Database(e.to_string()))?;
851        // SAFETY: the handle borrows the boxed connection, whose heap address
852        // is stable for as long as `_conn` lives; the struct never hands out
853        // the connection and drops `blob` first (field order above), so the
854        // extended lifetime never outlives the connection it refers to.
855        let blob = unsafe {
856            std::mem::transmute::<rusqlite::blob::Blob<'_>, rusqlite::blob::Blob<'static>>(blob)
857        };
858        Ok(Self { blob, _conn: conn })
859    }
860}
861
862impl std::io::Read for StoredBlobRows {
863    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
864        std::io::Read::read(&mut self.blob, buf)
865    }
866}
867
868enum StoredBlobReaderInner {
869    Raw(std::io::BufReader<StoredBlobRows>),
870    Zstd(Box<zstd::stream::read::Decoder<'static, std::io::BufReader<StoredBlobRows>>>),
871}
872
873/// Reader returned by [`SqliteRepository::stored_blob_reader`].
874pub struct StoredBlobReader {
875    inner: StoredBlobReaderInner,
876}
877
878impl std::io::Read for StoredBlobReader {
879    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
880        match &mut self.inner {
881            StoredBlobReaderInner::Raw(rows) => rows.read(buf),
882            StoredBlobReaderInner::Zstd(decoder) => decoder.read(buf),
883        }
884    }
885}
886
887impl SqliteRepository {
888    /// Run `f` inside one read transaction when the connection isn't already
889    /// in one. In WAL mode every autocommit statement takes and releases the
890    /// shared-memory read lock itself, which dominates a loop of point lookups.
891    fn with_read_txn<T>(conn: &Connection, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T> {
892        if !conn.is_autocommit() {
893            return f(conn);
894        }
895        conn.execute_batch("BEGIN DEFERRED")
896            .map_err(|e| OakError::Database(e.to_string()))?;
897        let result = f(conn);
898        let end = conn
899            .execute_batch("COMMIT")
900            .map_err(|e| OakError::Database(e.to_string()));
901        let value = result?;
902        end?;
903        Ok(value)
904    }
905
906    /// `(size, chunk reference count)` of each stored blob, in order, without
907    /// reading blob bytes; `None` for a blob not stored locally. One read
908    /// transaction and two cached statements for the whole batch.
909    pub fn blob_descriptors(&self, hashes: &[&Hash]) -> Result<Vec<Option<(u64, usize)>>> {
910        let conn = self.conn.lock().unwrap();
911        Self::with_read_txn(&conn, |conn| {
912            let db = |e: rusqlite::Error| OakError::Database(e.to_string());
913            let mut size_stmt = conn
914                .prepare_cached("SELECT size FROM blobs WHERE hash = ?1")
915                .map_err(db)?;
916            let mut chunks_stmt = conn
917                .prepare_cached("SELECT COUNT(*) FROM blob_chunks WHERE blob_hash = ?1")
918                .map_err(db)?;
919            hashes
920                .iter()
921                .map(|hash| {
922                    let Some(size) = size_stmt
923                        .query_row(params![hash.as_str()], |row| row.get::<_, i64>(0))
924                        .optional()
925                        .map_err(db)?
926                    else {
927                        return Ok(None);
928                    };
929                    let chunk_refs: i64 = chunks_stmt
930                        .query_row(params![hash.as_str()], |row| row.get(0))
931                        .map_err(db)?;
932                    Ok(Some((size as u64, chunk_refs as usize)))
933                })
934                .collect()
935        })
936    }
937
938    /// Inspect an existing repository in one SQLite read transaction. Does not
939    /// create a database, migrate schema, chmod, or change journal mode. Normal
940    /// SQLite locking remains enabled (WAL coordination sidecars may be used).
941    /// Mutating Repository methods fail on this connection.
942    pub fn open_read_only(db_path: &Path) -> Result<Self> {
943        let conn = Connection::open_with_flags(db_path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)
944            .map_err(|e| OakError::Database(e.to_string()))?;
945        conn.busy_timeout(std::time::Duration::from_millis(100))
946            .map_err(|e| OakError::Database(e.to_string()))?;
947        conn.execute_batch("BEGIN DEFERRED")
948            .map_err(|e| OakError::Database(e.to_string()))?;
949        // Pin the read snapshot now. Refuse an unknown/partial schema rather
950        // than migrating it or interpreting missing columns as empty state.
951        {
952            let mut stmt = conn
953                .prepare("SELECT version, succeeded FROM schema_migrations LIMIT 1000")
954                .map_err(|e| OakError::Database(e.to_string()))?;
955            let rows = stmt
956                .query_map([], |r| Ok((r.get::<_, String>(0)?, r.get::<_, bool>(1)?)))
957                .map_err(|e| OakError::Database(e.to_string()))?;
958            let versions = rows
959                .collect::<std::result::Result<Vec<_>, _>>()
960                .map_err(|e| OakError::Database(e.to_string()))?;
961            if !versions
962                .iter()
963                .any(|(version, ok)| *ok && version == "0000_baseline")
964                || versions
965                    .iter()
966                    .any(|(version, ok)| !ok || !MIGRATIONS.iter().any(|m| m.version == version))
967            {
968                return Err(OakError::Database(
969                    "unsupported schema for read-only inspection".into(),
970                ));
971            }
972        }
973        Ok(Self {
974            conn: Mutex::new(conn),
975            tree_flattens: AtomicU64::new(0),
976            tree_reads: AtomicU64::new(0),
977        })
978    }
979
980    /// Open or create a SQLite repository at the given path
981    pub fn open(db_path: &Path) -> Result<Self> {
982        (|| -> Result<Self> {
983            let conn = Connection::open(db_path).map_err(|e| sqlite_open_error(db_path, e))?;
984            conn.busy_timeout(std::time::Duration::from_secs(5))
985                .map_err(|e| sqlite_open_error(db_path, e))?;
986            harden_db_file_permissions(db_path);
987
988            // Enable WAL mode for concurrent multi-process access
989            conn.execute_batch("PRAGMA journal_mode=WAL;")
990                .map_err(|e| sqlite_open_error(db_path, e))?;
991
992            run_migrations(&conn)?;
993
994            Ok(SqliteRepository {
995                conn: Mutex::new(conn),
996                tree_flattens: AtomicU64::new(0),
997                tree_reads: AtomicU64::new(0),
998            })
999        })()
1000        .map_err(|error| diagnose_open_storage_error(db_path, error))
1001    }
1002
1003    /// Open or create a SQLite repository at the given path with foreign-key
1004    /// enforcement disabled.
1005    ///
1006    /// Used by `oak mount` for its lazy blob cache: the mount stores a
1007    /// manifest whose entries reference blobs that haven't been fetched
1008    /// yet. The default schema declares `manifest_entries.blob_hash` as a
1009    /// foreign key to `blobs(hash)`; rusqlite enables enforcement by
1010    /// default, so inserts would fail. The mount cache is a private,
1011    /// per-mount store — relaxing FK enforcement is safe there because
1012    /// nothing else points at it.
1013    pub fn open_relaxed(db_path: &Path) -> Result<Self> {
1014        (|| -> Result<Self> {
1015            let conn = Connection::open(db_path).map_err(|e| sqlite_open_error(db_path, e))?;
1016            conn.busy_timeout(std::time::Duration::from_secs(5))
1017                .map_err(|e| sqlite_open_error(db_path, e))?;
1018            harden_db_file_permissions(db_path);
1019            conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=OFF;")
1020                .map_err(|e| sqlite_open_error(db_path, e))?;
1021            run_migrations(&conn)?;
1022            Ok(SqliteRepository {
1023                conn: Mutex::new(conn),
1024                tree_flattens: AtomicU64::new(0),
1025                tree_reads: AtomicU64::new(0),
1026            })
1027        })()
1028        .map_err(|error| diagnose_open_storage_error(db_path, error))
1029    }
1030
1031    /// A sequential reader over a stored blob's plaintext that never holds
1032    /// the whole blob: the stored row is read through SQLite incremental
1033    /// blob I/O on a private read-only connection (the repository's own
1034    /// connection is not locked while the stream is open) and zstd rows are
1035    /// decoded as a stream. It reads committed state. Returns the blob's
1036    /// declared size with the reader, or `None` when the blob has no
1037    /// content row. The caller verifies the bytes against the hash.
1038    pub fn stored_blob_reader(&self, hash: &Hash) -> Result<Option<(u64, StoredBlobReader)>> {
1039        let row: Option<(i64, i64, i64)> = {
1040            let conn = self.conn.lock().unwrap();
1041            conn.query_row(
1042                "SELECT rowid, size, codec FROM blobs WHERE hash = ?1",
1043                params![hash.as_str()],
1044                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
1045            )
1046            .optional()
1047            .map_err(|e| OakError::Database(e.to_string()))?
1048        };
1049        let Some((rowid, size, codec)) = row else {
1050            return Ok(None);
1051        };
1052        let rows = std::io::BufReader::with_capacity(
1053            STORED_BLOB_READ_BYTES,
1054            StoredBlobRows::open(&self.database_path()?, rowid)?,
1055        );
1056        let inner = if codec == CODEC_ZSTD {
1057            StoredBlobReaderInner::Zstd(Box::new(
1058                zstd::stream::read::Decoder::with_buffer(rows)
1059                    .map_err(|e| OakError::Database(format!("zstd decompress: {e}")))?,
1060            ))
1061        } else {
1062            StoredBlobReaderInner::Raw(rows)
1063        };
1064        Ok(Some((size as u64, StoredBlobReader { inner })))
1065    }
1066
1067    pub fn database_path(&self) -> Result<PathBuf> {
1068        let conn = self.conn.lock().unwrap();
1069        conn.path()
1070            .map(PathBuf::from)
1071            .ok_or_else(|| OakError::Database("repository is not file-backed".to_string()))
1072    }
1073
1074    /// Atomically publish a complete canonical descriptor and one immutable
1075    /// local capture occurrence after rechecking the branch snapshot inside
1076    /// the write transaction. Identical portable changes share one descriptor;
1077    /// provenance rows are never replaced or deduplicated.
1078    #[allow(clippy::too_many_arguments)]
1079    pub fn store_change_capture(
1080        &self,
1081        capture_id: &str,
1082        change_set: &CanonicalChangeSetV1,
1083        owner: &str,
1084        name: &str,
1085        origin: Option<&str>,
1086        source_branch: &str,
1087        base_commit: Option<&Hash>,
1088    ) -> Result<()> {
1089        validate_capture_id(capture_id)?;
1090        validate_capture_provenance(capture_id, owner, name, origin, source_branch, base_commit)?;
1091        let (scope_kind, scope_paths_json, descriptor_json) =
1092            self.validate_change_set_objects(capture_id, change_set)?;
1093        let now = chrono::Utc::now().to_rfc3339();
1094
1095        let mut conn = self.conn.lock().unwrap();
1096        let tx = conn
1097            .transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)
1098            .map_err(|error| OakError::Database(error.to_string()))?;
1099
1100        let current_branch: Option<String> = tx
1101            .query_row(
1102                "SELECT value FROM metadata WHERE key = ?1",
1103                [MetadataKey::CurrentBranch.as_str()],
1104                |row| row.get(0),
1105            )
1106            .optional()
1107            .map_err(|error| OakError::Database(error.to_string()))?;
1108        let current_head = effective_head_in_connection(&tx, source_branch)?;
1109        if current_branch.as_deref() != Some(source_branch) || current_head.as_ref() != base_commit
1110        {
1111            return Err(OakError::WorktreeCaptureRaced {
1112                detail: "the current branch or effective HEAD changed before durable capture publication"
1113                    .to_string(),
1114            });
1115        }
1116        validate_capture_base_in_connection(&tx, capture_id, base_commit, change_set.base_tree())?;
1117
1118        tx.execute(
1119            "INSERT OR IGNORE INTO change_sets
1120             (change_id, schema_version, object_format, base_tree_hash, result_tree_hash,
1121              scope_kind, scope_paths_json, descriptor_json, created_at)
1122             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
1123            params![
1124                change_set.id().as_str(),
1125                i64::from(change_set.schema_version()),
1126                change_set.object_format(),
1127                change_set.base_tree().as_str(),
1128                change_set.result_tree().as_str(),
1129                scope_kind,
1130                scope_paths_json,
1131                descriptor_json,
1132                now,
1133            ],
1134        )
1135        .map_err(|error| OakError::Database(error.to_string()))?;
1136
1137        let stored: (i64, String, String, String, String, String, String) = tx
1138            .query_row(
1139                "SELECT schema_version, object_format, base_tree_hash, result_tree_hash,
1140                        scope_kind, scope_paths_json, descriptor_json
1141                 FROM change_sets WHERE change_id = ?1",
1142                [change_set.id().as_str()],
1143                |row| {
1144                    Ok((
1145                        row.get(0)?,
1146                        row.get(1)?,
1147                        row.get(2)?,
1148                        row.get(3)?,
1149                        row.get(4)?,
1150                        row.get(5)?,
1151                        row.get(6)?,
1152                    ))
1153                },
1154            )
1155            .map_err(|_| capture_integrity(capture_id, "stored descriptor row is unreadable"))?;
1156        if stored
1157            != (
1158                i64::from(change_set.schema_version()),
1159                change_set.object_format().to_string(),
1160                change_set.base_tree().to_string(),
1161                change_set.result_tree().to_string(),
1162                scope_kind.to_string(),
1163                scope_paths_json.clone(),
1164                descriptor_json.clone(),
1165            )
1166        {
1167            return Err(capture_integrity(
1168                capture_id,
1169                "change ID already names a different or corrupt descriptor",
1170            ));
1171        }
1172
1173        tx.execute(
1174            "INSERT INTO change_captures
1175             (capture_id, change_id, format_version, repo_owner, repo_name, origin,
1176              source_branch, base_commit_hash, captured_at)
1177             VALUES (?1, ?2, 1, ?3, ?4, ?5, ?6, ?7, ?8)",
1178            params![
1179                capture_id,
1180                change_set.id().as_str(),
1181                owner,
1182                name,
1183                origin,
1184                source_branch,
1185                base_commit.map(Hash::as_str),
1186                now,
1187            ],
1188        )
1189        .map_err(|_| {
1190            capture_integrity(
1191                capture_id,
1192                "capture occurrence ID already exists or provenance could not be stored",
1193            )
1194        })?;
1195        tx.commit()
1196            .map_err(|error| OakError::Database(error.to_string()))?;
1197        Ok(())
1198    }
1199
1200    /// Resolve one durable capture occurrence and rederive its complete
1201    /// canonical descriptor from the immutable base/result tree objects.
1202    /// Working-tree bytes are never rescanned and inherited blobs are not
1203    /// hydrated by this lookup.
1204    pub fn get_change_capture(&self, capture_id: &str) -> Result<StoredChangeCapture> {
1205        if validate_capture_id(capture_id).is_err() {
1206            return Err(OakError::ChangeCaptureNotFound {
1207                capture_id: capture_id.to_string(),
1208            });
1209        }
1210        let conn = self.conn.lock().unwrap();
1211        let occurrence: Option<ChangeCaptureRow> = conn
1212            .query_row(
1213                "SELECT change_id, format_version, repo_owner, repo_name, origin,
1214                        source_branch, base_commit_hash, captured_at
1215                 FROM change_captures WHERE capture_id = ?1",
1216                [capture_id],
1217                |row| {
1218                    Ok(ChangeCaptureRow {
1219                        change_id: row.get(0)?,
1220                        format_version: row.get(1)?,
1221                        owner: row.get(2)?,
1222                        name: row.get(3)?,
1223                        origin: row.get(4)?,
1224                        source_branch: row.get(5)?,
1225                        base_commit: row.get(6)?,
1226                        captured_at: row.get(7)?,
1227                    })
1228                },
1229            )
1230            .optional()
1231            .map_err(|_| capture_integrity(capture_id, "capture occurrence row is unreadable"))?;
1232        let Some(ChangeCaptureRow {
1233            change_id,
1234            format_version,
1235            owner,
1236            name,
1237            origin,
1238            source_branch,
1239            base_commit,
1240            captured_at,
1241        }) = occurrence
1242        else {
1243            return Err(OakError::ChangeCaptureNotFound {
1244                capture_id: capture_id.to_string(),
1245            });
1246        };
1247        if format_version != 1 {
1248            return Err(capture_integrity(
1249                capture_id,
1250                "unsupported capture occurrence format",
1251            ));
1252        }
1253        let base_commit = base_commit
1254            .as_deref()
1255            .map(|value| parse_native_hash(capture_id, value, "base commit"))
1256            .transpose()?;
1257        validate_capture_provenance(
1258            capture_id,
1259            &owner,
1260            &name,
1261            origin.as_deref(),
1262            &source_branch,
1263            base_commit.as_ref(),
1264        )?;
1265        let captured_at = chrono::DateTime::parse_from_rfc3339(&captured_at)
1266            .map_err(|_| capture_integrity(capture_id, "invalid capture timestamp"))?
1267            .with_timezone(&chrono::Utc);
1268
1269        let descriptor: Option<ChangeSetRow> = conn
1270            .query_row(
1271                "SELECT schema_version, object_format, base_tree_hash, result_tree_hash,
1272                        scope_kind, scope_paths_json, descriptor_json, created_at
1273                 FROM change_sets WHERE change_id = ?1",
1274                [change_id.as_str()],
1275                |row| {
1276                    Ok(ChangeSetRow {
1277                        schema_version: row.get(0)?,
1278                        object_format: row.get(1)?,
1279                        base_tree: row.get(2)?,
1280                        result_tree: row.get(3)?,
1281                        scope_kind: row.get(4)?,
1282                        scope_paths_json: row.get(5)?,
1283                        descriptor_json: row.get(6)?,
1284                        created_at: row.get(7)?,
1285                    })
1286                },
1287            )
1288            .optional()
1289            .map_err(|_| capture_integrity(capture_id, "stored descriptor row is unreadable"))?;
1290        drop(conn);
1291        let Some(ChangeSetRow {
1292            schema_version,
1293            object_format,
1294            base_tree,
1295            result_tree,
1296            scope_kind,
1297            scope_paths_json,
1298            descriptor_json,
1299            created_at: descriptor_created_at,
1300        }) = descriptor
1301        else {
1302            return Err(capture_integrity(
1303                capture_id,
1304                "capture occurrence references a missing descriptor",
1305            ));
1306        };
1307        if schema_version != 1 || object_format != CHANGE_SET_OBJECT_FORMAT_V1 {
1308            return Err(capture_integrity(
1309                capture_id,
1310                "unsupported or corrupt change descriptor format",
1311            ));
1312        }
1313        chrono::DateTime::parse_from_rfc3339(&descriptor_created_at)
1314            .map_err(|_| capture_integrity(capture_id, "invalid descriptor timestamp"))?;
1315        let base_tree = parse_native_hash(capture_id, &base_tree, "base tree")?;
1316        let result_tree = parse_native_hash(capture_id, &result_tree, "result tree")?;
1317        let stored_change_id = parse_native_hash(capture_id, &change_id, "change ID")?;
1318        let paths: Vec<String> = serde_json::from_str(&scope_paths_json)
1319            .map_err(|_| capture_integrity(capture_id, "invalid descriptor scope"))?;
1320        let scope = match scope_kind.as_str() {
1321            "full" if scope_paths_json == "[]" => ChangeScopeV1::Full,
1322            "paths" => ChangeScopeV1::Paths { paths },
1323            _ => return Err(capture_integrity(capture_id, "invalid descriptor scope")),
1324        };
1325        let base_manifest = self
1326            .get_manifest(&base_tree)
1327            .map_err(|_| capture_integrity(capture_id, "base tree could not be validated"))?
1328            .ok_or_else(|| capture_integrity(capture_id, "base tree is missing"))?;
1329        let result_manifest = self
1330            .get_manifest(&result_tree)
1331            .map_err(|_| capture_integrity(capture_id, "result tree could not be validated"))?
1332            .ok_or_else(|| capture_integrity(capture_id, "result tree is missing"))?;
1333        let change_set =
1334            CanonicalChangeSetV1::from_manifests(&base_manifest, &result_manifest, scope)
1335                .map_err(|_| capture_integrity(capture_id, "descriptor could not be rederived"))?;
1336        let canonical_json = serde_json::to_string(&change_set)
1337            .map_err(|_| capture_integrity(capture_id, "descriptor could not be encoded"))?;
1338        let canonical_scope_json = match change_set.scope() {
1339            ChangeScopeV1::Full => "[]".to_string(),
1340            ChangeScopeV1::Paths { paths } => serde_json::to_string(paths).map_err(|_| {
1341                capture_integrity(capture_id, "descriptor scope could not be encoded")
1342            })?,
1343        };
1344        let expected_scope_kind = match change_set.scope() {
1345            ChangeScopeV1::Full => "full",
1346            ChangeScopeV1::Paths { .. } => "paths",
1347        };
1348        if change_set.id() != &stored_change_id
1349            || change_set.base_tree() != &base_tree
1350            || change_set.result_tree() != &result_tree
1351            || scope_kind != expected_scope_kind
1352            || scope_paths_json != canonical_scope_json
1353            || descriptor_json != canonical_json
1354        {
1355            return Err(capture_integrity(
1356                capture_id,
1357                "stored descriptor does not match its canonical tree-derived identity",
1358            ));
1359        }
1360        match base_commit.as_ref() {
1361            Some(base_commit) => {
1362                let commit = self
1363                    .get_commit(base_commit)
1364                    .map_err(|_| {
1365                        capture_integrity(capture_id, "the recorded base commit is unavailable")
1366                    })?
1367                    .ok_or_else(|| {
1368                        capture_integrity(capture_id, "the recorded base commit is unavailable")
1369                    })?;
1370                if commit.manifest_hash != base_tree {
1371                    return Err(capture_integrity(
1372                        capture_id,
1373                        "the descriptor base tree does not match the recorded base commit",
1374                    ));
1375                }
1376            }
1377            None if base_tree != Tree::empty_hash() => {
1378                return Err(capture_integrity(
1379                    capture_id,
1380                    "a headless capture must use the canonical empty base tree",
1381                ));
1382            }
1383            None => {}
1384        }
1385        Ok(StoredChangeCapture {
1386            capture_id: capture_id.to_string(),
1387            change_set,
1388            provenance: ChangeCaptureProvenance {
1389                owner,
1390                name,
1391                origin,
1392                source_branch,
1393                base_commit,
1394                captured_at,
1395            },
1396        })
1397    }
1398
1399    fn validate_change_set_objects(
1400        &self,
1401        capture_id: &str,
1402        change_set: &CanonicalChangeSetV1,
1403    ) -> Result<(&'static str, String, String)> {
1404        let base = self
1405            .get_manifest(change_set.base_tree())
1406            .map_err(|_| capture_integrity(capture_id, "base tree could not be validated"))?
1407            .ok_or_else(|| capture_integrity(capture_id, "base tree is missing"))?;
1408        let result = self
1409            .get_manifest(change_set.result_tree())
1410            .map_err(|_| capture_integrity(capture_id, "result tree could not be validated"))?
1411            .ok_or_else(|| capture_integrity(capture_id, "result tree is missing"))?;
1412        let rederived =
1413            CanonicalChangeSetV1::from_manifests(&base, &result, change_set.scope().clone())
1414                .map_err(|_| capture_integrity(capture_id, "descriptor could not be rederived"))?;
1415        if &rederived != change_set {
1416            return Err(capture_integrity(
1417                capture_id,
1418                "descriptor does not match its canonical tree-derived identity",
1419            ));
1420        }
1421        let (scope_kind, scope_paths_json) = match change_set.scope() {
1422            ChangeScopeV1::Full => ("full", "[]".to_string()),
1423            ChangeScopeV1::Paths { paths } => (
1424                "paths",
1425                serde_json::to_string(paths).map_err(|_| {
1426                    capture_integrity(capture_id, "descriptor scope could not be encoded")
1427                })?,
1428            ),
1429        };
1430        let descriptor_json = serde_json::to_string(change_set)
1431            .map_err(|_| capture_integrity(capture_id, "descriptor could not be encoded"))?;
1432        Ok((scope_kind, scope_paths_json, descriptor_json))
1433    }
1434
1435    ///
1436    /// The server's PostgreSQL schema is more permissive than the client's
1437    /// SQLite schema: `parent_branch` and `parent_hash` are unenforced on the
1438    /// server but FK-checked here. Bulk imports (e.g. `oak clone`) need to relax
1439    /// enforcement so that legitimate server data — branches whose parent has
1440    /// been deleted, or commits whose timestamp ordering doesn't match
1441    /// topology — can be ingested. Always re-enable after the bulk load so
1442    /// subsequent normal operations stay validated.
1443    pub fn set_foreign_keys(&self, enabled: bool) -> Result<()> {
1444        let conn = self.conn.lock().unwrap();
1445        let pragma = if enabled {
1446            "PRAGMA foreign_keys=ON;"
1447        } else {
1448            "PRAGMA foreign_keys=OFF;"
1449        };
1450        conn.execute_batch(pragma)
1451            .map_err(|e| OakError::Database(e.to_string()))?;
1452        Ok(())
1453    }
1454
1455    /// Reconcile cached metadata with a remote row, retaining pending local descriptions.
1456    ///
1457    /// `store_branch` is insert-only because local callers often create a
1458    /// placeholder branch row before later local edits. Remote refresh paths
1459    /// refresh lifecycle fields, but a locally edited description remains owned
1460    /// by the user until observed/published remotely with that exact value.
1461    /// Returns false when a newer local generation fenced out this response's
1462    /// description. Lifecycle reconciliation still follows the caller policy.
1463    pub fn upsert_branch_metadata_at_generation(
1464        &self,
1465        branch: &Branch,
1466        observed_generation: i64,
1467    ) -> Result<bool> {
1468        self.reconcile_branch_metadata(branch, true, observed_generation)
1469    }
1470
1471    /// Pull preserves existing local lifecycle decisions (e.g. an unsynced
1472    /// close) while refreshing descriptions that have no pending local edit.
1473    /// The parent branch is the exception: the server owns it (it restacks a
1474    /// branch when its parent lands), so a non-null remote parent always wins.
1475    /// Returns false if the response predates this branch's local generation.
1476    pub fn reconcile_pulled_branch_metadata(
1477        &self,
1478        branch: &Branch,
1479        observed_generation: i64,
1480    ) -> Result<bool> {
1481        self.reconcile_branch_metadata(branch, false, observed_generation)
1482    }
1483
1484    /// Capture before issuing a remote metadata request; never reconstruct this
1485    /// token from local state after the response arrives.
1486    pub fn description_generation(&self) -> Result<i64> {
1487        self.conn
1488            .lock()
1489            .unwrap()
1490            .query_row(
1491                "SELECT generation FROM branch_description_clock WHERE singleton = 1",
1492                [],
1493                |row| row.get(0),
1494            )
1495            .map_err(|error| OakError::Database(error.to_string()))
1496    }
1497
1498    fn reconcile_branch_metadata(
1499        &self,
1500        branch: &Branch,
1501        refresh_lifecycle: bool,
1502        observed_generation: i64,
1503    ) -> Result<bool> {
1504        let mut conn = self.conn.lock().unwrap();
1505        let tx = conn
1506            .savepoint()
1507            .map_err(|error| OakError::Database(error.to_string()))?;
1508        let generation = advance_description_generation(&tx)?;
1509        let fresh = tx
1510            .query_row(
1511                "SELECT description_generation <= ?2 FROM branches WHERE name = ?1",
1512                params![branch.name, observed_generation],
1513                |row| row.get::<_, bool>(0),
1514            )
1515            .optional()
1516            .map_err(|error| OakError::Database(error.to_string()))?
1517            .unwrap_or(true);
1518        tx.execute(
1519            "INSERT INTO branches (name, description, parent_branch, status, close_reason, created_at, description_generation) \
1520             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?9) \
1521             ON CONFLICT(name) DO UPDATE SET \
1522               description = CASE WHEN branches.description_generation <= ?8 AND branches.description_pending = 0 THEN excluded.description ELSE branches.description END, \
1523               description_pending = CASE WHEN branches.description_generation <= ?8 AND branches.description IS excluded.description THEN 0 ELSE branches.description_pending END, \
1524               description_generation = CASE WHEN branches.description_generation <= ?8 AND (branches.description_pending = 0 OR branches.description IS excluded.description) THEN ?9 ELSE branches.description_generation END, \
1525               parent_branch = CASE WHEN ?7 OR excluded.parent_branch IS NOT NULL THEN excluded.parent_branch ELSE branches.parent_branch END, \
1526               status = CASE WHEN ?7 THEN excluded.status ELSE branches.status END, \
1527               close_reason = CASE WHEN ?7 THEN excluded.close_reason ELSE branches.close_reason END, \
1528               created_at = CASE WHEN ?7 THEN excluded.created_at ELSE branches.created_at END",
1529            params![
1530                branch.name,
1531                branch.description,
1532                branch.parent_branch,
1533                branch.status.as_str(),
1534                branch.close_reason.as_ref().map(|r| r.as_str()),
1535                branch.created_at.to_rfc3339(),
1536                refresh_lifecycle,
1537                observed_generation,
1538                generation,
1539            ],
1540        )
1541        .map_err(|e| OakError::Database(e.to_string()))?;
1542        tx.commit()
1543            .map_err(|error| OakError::Database(error.to_string()))?;
1544        Ok(fresh)
1545    }
1546
1547    /// A description edited locally (or predating synchronization tracking)
1548    /// must not be replaced by a differing remote value.
1549    pub fn branch_description_pending(&self, name: &str) -> Result<bool> {
1550        let conn = self.conn.lock().unwrap();
1551        conn.query_row(
1552            "SELECT description_pending != 0 FROM branches WHERE name = ?1",
1553            [name],
1554            |row| row.get(0),
1555        )
1556        .optional()
1557        .map(|value| value.unwrap_or(false))
1558        .map_err(|error| OakError::Database(error.to_string()))
1559    }
1560
1561    /// Begin a relaxed-durability transaction for a bulk ingest (clone / pull).
1562    ///
1563    /// Lowers `synchronous` to `NORMAL` and opens a transaction, so the many
1564    /// per-object INSERTs that follow commit as a batch instead of fsync-ing
1565    /// once per statement. The default `synchronous=FULL` in WAL mode fsyncs
1566    /// on every auto-commit, and the clone ingest writes each chunk, blob,
1567    /// `blob_chunks` row, tree, and commit as its own statement — so that
1568    /// per-statement fsync dominates clone time on repos with many files.
1569    /// Subsequent `store_*` calls join this open transaction (SQLite leaves
1570    /// auto-commit mode while a manual `BEGIN` is active).
1571    ///
1572    /// Pair with [`Self::bulk_flush`] (called periodically to bound WAL
1573    /// growth on a large import) and exactly one of [`Self::bulk_commit`] /
1574    /// [`Self::bulk_rollback`]. Single-writer only: the caller must not issue
1575    /// writes through another handle to the same database while the batch is
1576    /// open, or that write will silently join — and ride the fate of — this
1577    /// transaction.
1578    pub fn bulk_begin(&self) -> Result<()> {
1579        let conn = self.conn.lock().unwrap();
1580        conn.execute_batch("PRAGMA synchronous=NORMAL; BEGIN;")
1581            .map_err(|e| OakError::Database(e.to_string()))?;
1582        Ok(())
1583    }
1584
1585    /// Commit the current bulk batch and immediately open the next, so a long
1586    /// import doesn't accumulate its entire dataset in the WAL before a single
1587    /// final commit. Cheap under `synchronous=NORMAL` — no fsync until the
1588    /// next checkpoint.
1589    pub fn bulk_flush(&self) -> Result<()> {
1590        let conn = self.conn.lock().unwrap();
1591        conn.execute_batch("COMMIT; BEGIN;")
1592            .map_err(|e| OakError::Database(e.to_string()))?;
1593        Ok(())
1594    }
1595
1596    /// Commit the bulk transaction and restore full durability.
1597    pub fn bulk_commit(&self) -> Result<()> {
1598        let conn = self.conn.lock().unwrap();
1599        conn.execute_batch("COMMIT; PRAGMA synchronous=FULL;")
1600            .map_err(|e| OakError::Database(e.to_string()))?;
1601        Ok(())
1602    }
1603
1604    /// Roll back an in-flight bulk transaction and restore full durability.
1605    /// Best-effort, for the error path so a failed import doesn't leave a
1606    /// dangling transaction or a half-applied batch behind.
1607    pub fn bulk_rollback(&self) {
1608        if let Ok(conn) = self.conn.lock() {
1609            let _ = conn.execute_batch("ROLLBACK; PRAGMA synchronous=FULL;");
1610        }
1611    }
1612
1613    /// Begin a normal durable write transaction.
1614    ///
1615    /// Unlike [`Self::bulk_begin`], this deliberately leaves SQLite's
1616    /// durability pragmas alone. Use it for small publication steps where the
1617    /// caller needs many repository setters to become observable as one unit.
1618    pub fn write_txn_begin(&self) -> Result<()> {
1619        let conn = self.conn.lock().unwrap();
1620        conn.execute_batch("BEGIN IMMEDIATE;")
1621            .map_err(|e| OakError::Database(e.to_string()))?;
1622        Ok(())
1623    }
1624
1625    /// Commit a transaction opened with [`Self::write_txn_begin`].
1626    pub fn write_txn_commit(&self) -> Result<()> {
1627        let conn = self.conn.lock().unwrap();
1628        conn.execute_batch("COMMIT;")
1629            .map_err(|e| OakError::Database(e.to_string()))?;
1630        Ok(())
1631    }
1632
1633    /// Roll back a transaction opened with [`Self::write_txn_begin`].
1634    pub fn write_txn_rollback(&self) {
1635        if let Ok(conn) = self.conn.lock() {
1636            let _ = conn.execute_batch("ROLLBACK;");
1637        }
1638    }
1639
1640    /// Remove a metadata row entirely (rather than storing an empty value).
1641    pub fn delete_metadata(&self, key: MetadataKey) -> Result<()> {
1642        let conn = self.conn.lock().unwrap();
1643        conn.execute("DELETE FROM metadata WHERE key = ?1", params![key.as_str()])
1644            .map_err(|e| OakError::Database(e.to_string()))?;
1645        Ok(())
1646    }
1647
1648    /// Create an in-memory repository (for testing)
1649    #[cfg(test)]
1650    pub fn in_memory() -> Result<Self> {
1651        let conn = Connection::open_in_memory().map_err(|e| OakError::Database(e.to_string()))?;
1652        run_migrations(&conn)?;
1653        Ok(SqliteRepository {
1654            conn: Mutex::new(conn),
1655            tree_flattens: AtomicU64::new(0),
1656            tree_reads: AtomicU64::new(0),
1657        })
1658    }
1659
1660    /// Open a [`BulkImporter`] against the same database file.
1661    ///
1662    /// The importer holds its own connection (so it can manage long-lived
1663    /// transactions independently of the regular repo's mutex), batches writes
1664    /// across `batch_size` commits, and caches inserted-tree hashes in memory
1665    /// to skip per-subtree EXISTS lookups during deeply repetitive imports
1666    /// (e.g. `oak clone <git-url>` or `oak init` over an existing `.git`).
1667    ///
1668    /// The caller must not concurrently issue writes via the underlying
1669    /// `SqliteRepository` until the importer is dropped or finished —
1670    /// SQLite only allows one writer at a time, and a clash will block.
1671    pub fn bulk_importer(&self, batch_size: usize) -> Result<BulkImporter> {
1672        let conn = self.conn.lock().unwrap();
1673        let path = conn
1674            .path()
1675            .ok_or_else(|| {
1676                OakError::Database("bulk importer requires a file-backed connection".to_string())
1677            })?
1678            .to_string();
1679        drop(conn);
1680        BulkImporter::open(Path::new(&path), batch_size)
1681    }
1682
1683    /// One-shot storage compaction. Converts the database to the compact
1684    /// on-disk format and reclaims the freed space:
1685    ///   1. Backfills `trees.content` for every legacy tree (one still stored as
1686    ///      `tree_entries` rows), verifying each reconstructed tree re-hashes to
1687    ///      its key before writing.
1688    ///   2. Drops the now-unused `tree_entries` table (only if every tree has
1689    ///      `content`, so the fallback path is never needed again).
1690    ///   3. Re-compresses legacy raw blobs (`codec = 0`) that actually shrink.
1691    ///   4. `VACUUM`s to shrink the file on disk.
1692    ///
1693    /// Idempotent: a second run finds nothing to backfill/recompress and just
1694    /// VACUUMs. `VACUUM` needs transient free disk roughly equal to the final
1695    /// database size.
1696    pub fn compact_storage(&self) -> Result<CompactStats> {
1697        let mut conn = self.conn.lock().unwrap();
1698
1699        // 1. Backfill legacy trees (content IS NULL) from tree_entries.
1700        let legacy_trees: Vec<String> = {
1701            let table = table_exists(&conn, "tree_entries")
1702                .map_err(|e| OakError::Database(e.to_string()))?;
1703            if !table {
1704                Vec::new() // already compacted away
1705            } else {
1706                let mut stmt = conn
1707                    .prepare("SELECT hash FROM trees WHERE content IS NULL")
1708                    .map_err(|e| OakError::Database(e.to_string()))?;
1709                let rows = stmt
1710                    .query_map([], |r| r.get::<_, String>(0))
1711                    .map_err(|e| OakError::Database(e.to_string()))?;
1712                rows.collect::<std::result::Result<Vec<_>, _>>()
1713                    .map_err(|e| OakError::Database(e.to_string()))?
1714            }
1715        };
1716
1717        let mut trees_backfilled = 0u64;
1718        if !legacy_trees.is_empty() {
1719            let tx = conn
1720                .transaction()
1721                .map_err(|e| OakError::Database(e.to_string()))?;
1722            for h in &legacy_trees {
1723                let hash = Hash(h.clone());
1724                let tree = read_tree_entries(&tx, &hash)?;
1725                // Integrity: the reconstructed tree must re-hash to its key.
1726                if hash_bytes(&tree.canonical_bytes()) != hash {
1727                    return Err(OakError::Database(format!(
1728                        "tree {h} failed integrity check during compaction"
1729                    )));
1730                }
1731                let content = zstd_compress(&tree.canonical_bytes())?;
1732                tx.execute(
1733                    "UPDATE trees SET content = ?2 WHERE hash = ?1",
1734                    params![h, content],
1735                )
1736                .map_err(|e| OakError::Database(e.to_string()))?;
1737                trees_backfilled += 1;
1738            }
1739            tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
1740        }
1741
1742        // 2. Drop tree_entries once every tree has content.
1743        let remaining_null: i64 = conn
1744            .query_row(
1745                "SELECT COUNT(*) FROM trees WHERE content IS NULL",
1746                [],
1747                |r| r.get(0),
1748            )
1749            .map_err(|e| OakError::Database(e.to_string()))?;
1750        let tree_entries_dropped = if remaining_null == 0
1751            && table_exists(&conn, "tree_entries").map_err(|e| OakError::Database(e.to_string()))?
1752        {
1753            conn.execute_batch("DROP TABLE IF EXISTS tree_entries;")
1754                .map_err(|e| OakError::Database(e.to_string()))?;
1755            true
1756        } else {
1757            false
1758        };
1759
1760        // 3. Re-compress legacy raw blobs that shrink.
1761        let raw_blobs: Vec<String> = {
1762            let mut stmt = conn
1763                .prepare("SELECT hash FROM blobs WHERE codec = 0")
1764                .map_err(|e| OakError::Database(e.to_string()))?;
1765            let rows = stmt
1766                .query_map([], |r| r.get::<_, String>(0))
1767                .map_err(|e| OakError::Database(e.to_string()))?;
1768            rows.collect::<std::result::Result<Vec<_>, _>>()
1769                .map_err(|e| OakError::Database(e.to_string()))?
1770        };
1771
1772        let mut blobs_recompressed = 0u64;
1773        if !raw_blobs.is_empty() {
1774            let tx = conn
1775                .transaction()
1776                .map_err(|e| OakError::Database(e.to_string()))?;
1777            for h in &raw_blobs {
1778                let content: Vec<u8> = tx
1779                    .query_row(
1780                        "SELECT content FROM blobs WHERE hash = ?1",
1781                        params![h],
1782                        |r| r.get(0),
1783                    )
1784                    .map_err(|e| OakError::Database(e.to_string()))?;
1785                let compressed = zstd_compress(&content)?;
1786                if compressed.len() < content.len() {
1787                    tx.execute(
1788                        "UPDATE blobs SET content = ?2, codec = 1 WHERE hash = ?1",
1789                        params![h, compressed],
1790                    )
1791                    .map_err(|e| OakError::Database(e.to_string()))?;
1792                    blobs_recompressed += 1;
1793                }
1794            }
1795            tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
1796        }
1797
1798        // 4. VACUUM (must run outside any transaction) to reclaim freed pages.
1799        conn.execute_batch("VACUUM;")
1800            .map_err(|e| OakError::Database(e.to_string()))?;
1801
1802        Ok(CompactStats {
1803            trees_backfilled,
1804            tree_entries_dropped,
1805            blobs_recompressed,
1806        })
1807    }
1808
1809    /// Replace a blob's chunk mapping wholesale. `store_blob_chunks` is
1810    /// `INSERT OR IGNORE` (append-only), which is right for ingest but can't
1811    /// correct an existing mapping — needed when a blob arrives mis-chunked
1812    /// from a skewed server and the client re-chunks the repaired plaintext.
1813    pub fn replace_blob_chunks(&self, blob_hash: &Hash, chunks: &[ChunkInfo]) -> Result<()> {
1814        let mut conn = self.conn.lock().unwrap();
1815        // Savepoint, not `transaction()`: pull ingest calls this inside an
1816        // already-open `BulkTxn` (same rationale as `store_tree`).
1817        let tx = conn
1818            .savepoint()
1819            .map_err(|e| OakError::Database(e.to_string()))?;
1820        tx.execute(
1821            "DELETE FROM blob_chunks WHERE blob_hash = ?1",
1822            params![blob_hash.as_str()],
1823        )
1824        .map_err(|e| OakError::Database(e.to_string()))?;
1825        for (index, chunk) in chunks.iter().enumerate() {
1826            tx.execute(
1827                "INSERT INTO blob_chunks (blob_hash, chunk_hash, chunk_index, offset, size) VALUES (?1, ?2, ?3, ?4, ?5)",
1828                params![
1829                    blob_hash.as_str(),
1830                    chunk.hash.as_str(),
1831                    index as i64,
1832                    chunk.offset as i64,
1833                    chunk.length as i64,
1834                ],
1835            )
1836            .map_err(|e| OakError::Database(e.to_string()))?;
1837        }
1838        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
1839        Ok(())
1840    }
1841
1842    /// Remove a cached chunk by content hash.
1843    ///
1844    /// Lazy hydration uses this to discard a previously-persisted corrupt row
1845    /// before retrying the download. Blob-to-chunk mappings are intentionally
1846    /// left intact: migration 0009 made those references metadata hints, so a
1847    /// later hydration can still use them to fetch the missing bytes.
1848    pub fn delete_chunk(&self, hash: &Hash) -> Result<()> {
1849        let conn = self.conn.lock().unwrap();
1850        conn.execute("DELETE FROM chunks WHERE hash = ?1", params![hash.as_str()])
1851            .map_err(|e| OakError::Database(e.to_string()))?;
1852        Ok(())
1853    }
1854
1855    /// Store `trees` (skipping ones already present), insert `commit` with
1856    /// its file rows, and point the commit's branch and the legacy head at
1857    /// it — all in one transaction. With `require_root`, refuses a commit
1858    /// whose root tree is neither in `trees` nor already stored.
1859    fn publish_commit(&self, commit: &Commit, trees: &[Tree], require_root: bool) -> Result<()> {
1860        let mut conn = self.conn.lock().unwrap();
1861        let tx = conn
1862            .transaction()
1863            .map_err(|e| OakError::Database(e.to_string()))?;
1864
1865        for tree in trees {
1866            let already_present: bool = tx
1867                .query_row(
1868                    "SELECT EXISTS(SELECT 1 FROM trees WHERE hash = ?1)",
1869                    params![tree.hash.as_str()],
1870                    |row| row.get(0),
1871                )
1872                .map_err(|e| OakError::Database(e.to_string()))?;
1873            if already_present {
1874                continue;
1875            }
1876            insert_tree_row(&tx, tree)?;
1877        }
1878
1879        if require_root {
1880            let root = &commit.manifest_hash;
1881            let root_present: bool = *root == Tree::empty_hash()
1882                || tx
1883                    .query_row(
1884                        "SELECT EXISTS(SELECT 1 FROM trees WHERE hash = ?1)",
1885                        params![root.as_str()],
1886                        |row| row.get(0),
1887                    )
1888                    .map_err(|e| OakError::Database(e.to_string()))?;
1889            if !root_present {
1890                return Err(OakError::ManifestNotFound(root.to_string()));
1891            }
1892        }
1893
1894        let inserted = tx
1895            .execute(
1896            "INSERT OR IGNORE INTO commits (hash, branch_name, parent_hash, merge_parent_hash, manifest_hash, author, message, timestamp) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
1897            params![
1898                commit.hash.as_str(),
1899                commit.branch_name.as_str(),
1900                commit.parent_hash.as_ref().map(|h| h.as_str()),
1901                commit.merge_parent_hash.as_ref().map(|h| h.as_str()),
1902                commit.manifest_hash.as_str(),
1903                commit.author.as_str(),
1904                commit.message.as_deref(),
1905                commit.timestamp.to_rfc3339(),
1906            ],
1907        )
1908            .map_err(|e| OakError::Database(e.to_string()))?;
1909
1910        if inserted != 0 {
1911            for file in &commit.files {
1912                let change_type_str = match file.change_type {
1913                    ChangeType::Added => "added",
1914                    ChangeType::Modified => "modified",
1915                    ChangeType::Deleted => "deleted",
1916                    ChangeType::Renamed => "renamed",
1917                };
1918                tx.execute(
1919                    "INSERT INTO commit_files (commit_hash, path, change_type, old_blob_hash, new_blob_hash, old_path) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
1920                    params![
1921                        commit.hash.as_str(),
1922                        file.path.as_str(),
1923                        change_type_str,
1924                        file.old_blob_hash.as_ref().map(|h| h.as_str()),
1925                        file.new_blob_hash.as_ref().map(|h| h.as_str()),
1926                        file.old_path.as_deref(),
1927                    ],
1928                )
1929                .map_err(|e| OakError::Database(e.to_string()))?;
1930            }
1931        }
1932
1933        tx.execute(
1934            "INSERT OR REPLACE INTO branch_heads (branch_name, head_hash) VALUES (?1, ?2)",
1935            params![commit.branch_name.as_str(), commit.hash.as_str()],
1936        )
1937        .map_err(|e| OakError::Database(e.to_string()))?;
1938
1939        tx.execute(
1940            "INSERT OR REPLACE INTO metadata (key, value) VALUES (?1, ?2)",
1941            params![MetadataKey::Head.as_str(), commit.hash.as_str()],
1942        )
1943        .map_err(|e| OakError::Database(e.to_string()))?;
1944
1945        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
1946        Ok(())
1947    }
1948}
1949
1950/// Outcome of [`SqliteRepository::compact_storage`].
1951#[derive(Debug, Clone, Default)]
1952pub struct CompactStats {
1953    /// Legacy trees converted from `tree_entries` rows to `trees.content`.
1954    pub trees_backfilled: u64,
1955    /// Whether the `tree_entries` table was dropped (all trees now compact).
1956    pub tree_entries_dropped: bool,
1957    /// Legacy raw blobs re-compressed with zstd.
1958    pub blobs_recompressed: u64,
1959}
1960
1961/// Bulk-write helper for git import (and similar one-shot replays).
1962///
1963/// Wraps a private connection to the repo's SQLite database that:
1964///   - Runs with relaxed durability pragmas (`synchronous=NORMAL`, larger cache,
1965///     `temp_store=MEMORY`) — appropriate for a re-runnable bulk import.
1966///   - Holds an outer transaction across `batch_size` commits, flushed
1967///     automatically when the threshold is reached. This collapses thousands
1968///     of per-commit `tx.commit()` fsyncs into a handful.
1969///   - Caches inserted tree hashes in a `HashSet` so unchanged subtrees skip
1970///     the SQL `SELECT EXISTS` lookup on every commit.
1971///
1972/// `finish()` flushes the final batch and must be called for the import to
1973/// be durable. If the importer is dropped without finishing, the open
1974/// transaction is rolled back.
1975pub struct BulkImporter {
1976    conn: Connection,
1977    tree_cache: HashSet<Hash>,
1978    uncommitted: usize,
1979    batch_size: usize,
1980    in_tx: bool,
1981}
1982
1983impl BulkImporter {
1984    fn open(db_path: &Path, batch_size: usize) -> Result<Self> {
1985        let conn = Connection::open(db_path).map_err(|e| OakError::Database(e.to_string()))?;
1986        conn.execute_batch(
1987            "PRAGMA journal_mode=WAL;
1988             PRAGMA synchronous=NORMAL;
1989             PRAGMA temp_store=MEMORY;
1990             PRAGMA cache_size=-262144;
1991             BEGIN;",
1992        )
1993        .map_err(|e| OakError::Database(e.to_string()))?;
1994        Ok(BulkImporter {
1995            conn,
1996            tree_cache: HashSet::new(),
1997            uncommitted: 0,
1998            batch_size: batch_size.max(1),
1999            in_tx: true,
2000        })
2001    }
2002
2003    /// Hash and insert a blob's content into the open batch.
2004    pub fn put_blob(&mut self, content: Vec<u8>) -> Result<Hash> {
2005        let blob = Blob::new(content);
2006        let (stored, codec) = encode_blob(&blob.content)?;
2007        self.conn
2008            .execute(
2009                "INSERT OR IGNORE INTO blobs (hash, content, size, codec) VALUES (?1, ?2, ?3, ?4)",
2010                params![blob.hash.as_str(), stored.as_ref(), blob.size as i64, codec],
2011            )
2012            .map_err(|e| OakError::Database(e.to_string()))?;
2013        Ok(blob.hash)
2014    }
2015
2016    /// Build a tree from manifest entries and insert all subtrees into the
2017    /// open batch. Subtrees already inserted in this importer session are
2018    /// skipped without a roundtrip; subtrees already present on disk from
2019    /// prior work fall through to `INSERT OR IGNORE` and silently no-op.
2020    pub fn put_tree(&mut self, entries: Vec<ManifestEntry>) -> Result<Hash> {
2021        let built = crate::build_tree(&entries)?;
2022        for tree in &built.trees {
2023            if !self.tree_cache.insert(tree.hash.clone()) {
2024                continue;
2025            }
2026            insert_tree_row(&self.conn, tree)?;
2027        }
2028        Ok(built.root_hash)
2029    }
2030
2031    /// Insert a single, already-built tree node into the open batch, skipping
2032    /// the write if this importer session already stored a tree with the same
2033    /// hash (same dedup as [`put_tree`], one node at a time).
2034    ///
2035    /// Lets a caller that builds trees bottom-up — the git converter memoizing
2036    /// on git tree oids — store each node as it's produced instead of handing
2037    /// over a flat manifest and rebuilding the whole hierarchy per commit.
2038    pub fn put_tree_node(&mut self, tree: &Tree) -> Result<()> {
2039        if self.tree_cache.insert(tree.hash.clone()) {
2040            insert_tree_row(&self.conn, tree)?;
2041        }
2042        Ok(())
2043    }
2044
2045    /// Insert a commit (plus its `commit_files`, if any) and tick the batch
2046    /// counter. Flushes the current transaction when the threshold is hit.
2047    pub fn store_commit(&mut self, commit: &Commit) -> Result<()> {
2048        let inserted = self
2049            .conn
2050            .execute(
2051                "INSERT OR IGNORE INTO commits (hash, branch_name, parent_hash, merge_parent_hash, manifest_hash, author, message, timestamp) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2052                params![
2053                    commit.hash.as_str(),
2054                    commit.branch_name,
2055                    commit.parent_hash.as_ref().map(|h| h.as_str()),
2056                    commit.merge_parent_hash.as_ref().map(|h| h.as_str()),
2057                    commit.manifest_hash.as_str(),
2058                    commit.author,
2059                    commit.message,
2060                    commit.timestamp.to_rfc3339(),
2061                ],
2062            )
2063            .map_err(|e| OakError::Database(e.to_string()))?;
2064
2065        if inserted == 0 {
2066            return Ok(());
2067        }
2068
2069        for file in &commit.files {
2070            let change_type_str = match file.change_type {
2071                ChangeType::Added => "added",
2072                ChangeType::Modified => "modified",
2073                ChangeType::Deleted => "deleted",
2074                ChangeType::Renamed => "renamed",
2075            };
2076            self.conn
2077                .execute(
2078                    "INSERT INTO commit_files (commit_hash, path, change_type, old_blob_hash, new_blob_hash, old_path) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
2079                    params![
2080                        commit.hash.as_str(),
2081                        file.path,
2082                        change_type_str,
2083                        file.old_blob_hash.as_ref().map(|h| h.as_str()),
2084                        file.new_blob_hash.as_ref().map(|h| h.as_str()),
2085                        file.old_path,
2086                    ],
2087                )
2088                .map_err(|e| OakError::Database(e.to_string()))?;
2089        }
2090
2091        self.uncommitted += 1;
2092        if self.uncommitted >= self.batch_size {
2093            self.flush_batch()?;
2094        }
2095        Ok(())
2096    }
2097
2098    fn flush_batch(&mut self) -> Result<()> {
2099        if !self.in_tx {
2100            return Ok(());
2101        }
2102        self.conn
2103            .execute_batch("COMMIT; BEGIN;")
2104            .map_err(|e| OakError::Database(e.to_string()))?;
2105        self.uncommitted = 0;
2106        Ok(())
2107    }
2108
2109    /// Commit the final batch. After this the importer is durable on disk.
2110    pub fn finish(mut self) -> Result<()> {
2111        if self.in_tx {
2112            self.conn
2113                .execute_batch("COMMIT;")
2114                .map_err(|e| OakError::Database(e.to_string()))?;
2115            self.in_tx = false;
2116        }
2117        Ok(())
2118    }
2119}
2120
2121impl Drop for BulkImporter {
2122    fn drop(&mut self) {
2123        if self.in_tx {
2124            // Best-effort rollback so a panicked / errored import doesn't leave
2125            // a half-applied batch behind. `finish()` clears `in_tx` first, so
2126            // a clean finish path skips this.
2127            let _ = self.conn.execute_batch("ROLLBACK;");
2128        }
2129    }
2130}
2131
2132/// How much blob content a [`Repository::put_blob_sources`] pipeline may hold
2133/// in memory at once (in-flight reads plus rows queued for insert).
2134const BLOB_BATCH_BUDGET_BYTES: i64 = 64 * 1024 * 1024;
2135
2136/// Below this much total hinted content, `put_blob_sources` skips the
2137/// streaming pipeline and stores the batch as one fused parallel pass plus a
2138/// single transaction. The pipeline's spawned thread + channel + budget
2139/// bookkeeping only pays for itself when there's enough content for reads and
2140/// hashes to genuinely overlap the inserts (multi-megabyte batches); on a
2141/// few-KB commit it's pure fixed cost per call — measurable as lost snapshot
2142/// throughput when many tiny commits contend for the same repository.
2143const BLOB_STREAMING_THRESHOLD_BYTES: i64 = 8 * 1024 * 1024;
2144
2145const BLOB_INSERT_SQL: &str =
2146    "INSERT OR IGNORE INTO blobs (hash, content, size, codec) VALUES (?1, ?2, ?3, ?4)";
2147
2148/// What a source counts against the byte budget: its hinted size clamped to
2149/// the whole budget (so an oversized file is admitted alone rather than
2150/// never); an unknown size is treated as "could be huge".
2151fn source_charge(source: &BlobSource) -> i64 {
2152    source.size_hint.map_or(BLOB_BATCH_BUDGET_BYTES, |s| {
2153        (s.min(i64::MAX as u64) as i64).min(BLOB_BATCH_BUDGET_BYTES)
2154    })
2155}
2156
2157/// Byte-budget gate bounding a `put_blob_sources` pipeline's in-flight
2158/// content. Workers [`ByteBudget::acquire`] a source's size before reading it
2159/// and the insert thread [`ByteBudget::release`]s after the row lands, so the
2160/// total stays under the cap without imposing pre-partitioned batches (whose
2161/// boundaries serialize — the tail batch overlaps nothing). [`ByteBudget::close`]
2162/// unparks every waiter for teardown when the releaser is gone, so an aborted
2163/// batch can't deadlock.
2164struct ByteBudget {
2165    remaining: std::sync::Mutex<i64>,
2166    available: std::sync::Condvar,
2167}
2168
2169impl ByteBudget {
2170    fn new(cap: i64) -> Self {
2171        Self {
2172            remaining: std::sync::Mutex::new(cap),
2173            available: std::sync::Condvar::new(),
2174        }
2175    }
2176
2177    /// Block until `n` bytes fit, then take them. Callers must clamp `n` to
2178    /// the cap (a charge larger than the cap would wait forever).
2179    fn acquire(&self, n: i64) {
2180        let mut remaining = self.remaining.lock().unwrap();
2181        while *remaining < n {
2182            remaining = self.available.wait(remaining).unwrap();
2183        }
2184        *remaining -= n;
2185    }
2186
2187    fn release(&self, n: i64) {
2188        *self.remaining.lock().unwrap() += n;
2189        self.available.notify_all();
2190    }
2191
2192    /// Open the gate unconditionally so every parked `acquire` returns.
2193    fn close(&self) {
2194        *self.remaining.lock().unwrap() = i64::MAX;
2195        self.available.notify_all();
2196    }
2197}
2198
2199impl Repository for SqliteRepository {
2200    fn store_blob(&self, blob: &Blob) -> Result<()> {
2201        let conn = self.conn.lock().unwrap();
2202        let (stored, codec) = encode_blob(&blob.content)?;
2203        conn.execute(
2204            "INSERT OR IGNORE INTO blobs (hash, content, size, codec) VALUES (?1, ?2, ?3, ?4)",
2205            params![blob.hash.as_str(), stored.as_ref(), blob.size as i64, codec],
2206        )
2207        .map_err(|e| OakError::Database(e.to_string()))?;
2208        Ok(())
2209    }
2210
2211    fn put_blob_sources(&self, sources: Vec<BlobSource>) -> Result<Vec<Hash>> {
2212        if sources.is_empty() {
2213            return Ok(Vec::new());
2214        }
2215        if sources.len() == 1 {
2216            // A one-blob batch gains nothing from an explicit transaction;
2217            // keep it a single autocommit insert like `put_blob`.
2218            let content = (sources.into_iter().next().unwrap().read)()?;
2219            return Ok(vec![self.put_blob(content)?]);
2220        }
2221
2222        use rayon::prelude::*;
2223
2224        // Small batch (by hinted bytes): read + hash + encode fused per blob
2225        // in one parallel pass, then insert everything in one transaction — a
2226        // `put_blob` loop would pay an autocommit (WAL append + sync) per
2227        // blob. The all-hashed-before-any-insert barrier is harmless at this
2228        // size, and skipping the streaming pipeline below keeps a tiny
2229        // commit's latency free of its thread/channel setup cost.
2230        let total_hinted = sources
2231            .iter()
2232            .map(source_charge)
2233            .fold(0i64, |acc, charge| acc.saturating_add(charge));
2234        if total_hinted <= BLOB_STREAMING_THRESHOLD_BYTES {
2235            let rows: Vec<(Hash, Vec<u8>, i64, i64)> = sources
2236                .into_par_iter()
2237                .map(|source| -> Result<(Hash, Vec<u8>, i64, i64)> {
2238                    let blob = Blob::new((source.read)()?);
2239                    let size = blob.size as i64;
2240                    let (encoded, codec) = encode_blob(&blob.content)?;
2241                    let stored = match encoded {
2242                        std::borrow::Cow::Owned(v) => v,
2243                        std::borrow::Cow::Borrowed(_) => blob.content,
2244                    };
2245                    Ok((blob.hash, stored, size, codec))
2246                })
2247                .collect::<Result<Vec<_>>>()?;
2248
2249            let mut conn = self.conn.lock().unwrap();
2250            let tx = conn
2251                .transaction()
2252                .map_err(|e| OakError::Database(e.to_string()))?;
2253            {
2254                let mut stmt = tx
2255                    .prepare(BLOB_INSERT_SQL)
2256                    .map_err(|e| OakError::Database(e.to_string()))?;
2257                for (hash, stored, size, codec) in &rows {
2258                    stmt.execute(params![hash.as_str(), stored, size, codec])
2259                        .map_err(|e| OakError::Database(e.to_string()))?;
2260                }
2261            }
2262            tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2263            return Ok(rows.into_iter().map(|(hash, _, _, _)| hash).collect());
2264        }
2265
2266        // Big batch: pipeline, not phases. Rayon workers read + hash + encode
2267        // each source fused per blob (so one file's read overlaps another's
2268        // BLAKE3/zstd) and stream finished rows over a channel to this
2269        // thread, which inserts them all inside ONE transaction. There is no
2270        // all-read or all-hash barrier anywhere: with a few large files the
2271        // insert of the first overlaps the hash of the last, and with
2272        // thousands of files the inserts run continuously behind the hashing
2273        // instead of after it.
2274        //
2275        // Memory is bounded by `BLOB_BATCH_BUDGET_BYTES`: a worker admits a
2276        // source's charge (see `source_charge`) before reading it, and the
2277        // charge is released only after the row has been inserted and dropped.
2278        let n = sources.len();
2279        let budget = ByteBudget::new(BLOB_BATCH_BUDGET_BYTES);
2280        type Row = (usize, Hash, Vec<u8>, i64, i64, i64);
2281        let (sender, receiver) = std::sync::mpsc::channel::<Row>();
2282
2283        let mut hashes: Vec<Option<Hash>> = Vec::with_capacity(n);
2284        hashes.resize_with(n, || None);
2285
2286        let (producer_result, consumer_result) = std::thread::scope(|scope| {
2287            let budget_ref = &budget;
2288            let producer = scope.spawn(move || -> Result<()> {
2289                sources
2290                    .into_par_iter()
2291                    .enumerate()
2292                    .try_for_each(|(idx, source)| -> Result<()> {
2293                        let charge = source_charge(&source);
2294                        budget_ref.acquire(charge);
2295                        let blob = Blob::new((source.read)()?);
2296                        let size = blob.size as i64;
2297                        let (encoded, codec) = encode_blob(&blob.content)?;
2298                        let stored = match encoded {
2299                            std::borrow::Cow::Owned(v) => v,
2300                            std::borrow::Cow::Borrowed(_) => blob.content,
2301                        };
2302                        sender
2303                            .send((idx, blob.hash, stored, size, codec, charge))
2304                            .map_err(|_| {
2305                                OakError::Database("blob batch insert aborted".to_string())
2306                            })
2307                    })
2308            });
2309
2310            let consumer_result = (|| -> Result<()> {
2311                let mut conn = self.conn.lock().unwrap();
2312                let tx = conn
2313                    .transaction()
2314                    .map_err(|e| OakError::Database(e.to_string()))?;
2315                {
2316                    let mut stmt = tx
2317                        .prepare(BLOB_INSERT_SQL)
2318                        .map_err(|e| OakError::Database(e.to_string()))?;
2319                    for (idx, hash, stored, size, codec, charge) in &receiver {
2320                        let inserted = stmt
2321                            .execute(params![hash.as_str(), stored, size, codec])
2322                            .map_err(|e| OakError::Database(e.to_string()));
2323                        drop(stored);
2324                        budget_ref.release(charge);
2325                        inserted?;
2326                        hashes[idx] = Some(hash);
2327                    }
2328                }
2329                tx.commit().map_err(|e| OakError::Database(e.to_string()))
2330            })();
2331
2332            // Teardown for the error path: this thread is the only budget
2333            // releaser, so a worker could be parked in `acquire` forever once
2334            // the insert loop has bailed. Closing the channel fails the sends
2335            // and opening the budget unparks the waiters, so the producer
2336            // drains with errors instead of deadlocking. Both are no-ops when
2337            // everything succeeded (the producer already finished — that's
2338            // what ended the insert loop).
2339            drop(receiver);
2340            budget.close();
2341            let producer_result = match producer.join() {
2342                Ok(result) => result,
2343                Err(_) => Err(OakError::Database(
2344                    "blob batch producer panicked".to_string(),
2345                )),
2346            };
2347            (producer_result, consumer_result)
2348        });
2349        consumer_result?;
2350        producer_result?;
2351        Ok(hashes
2352            .into_iter()
2353            .map(|h| h.expect("every source yields exactly one inserted row"))
2354            .collect())
2355    }
2356
2357    fn get_blob(&self, hash: &Hash) -> Result<Option<Blob>> {
2358        let conn = self.conn.lock().unwrap();
2359        let result: Option<(Vec<u8>, i64, i64)> = conn
2360            .prepare_cached("SELECT content, size, codec FROM blobs WHERE hash = ?1")
2361            .and_then(|mut stmt| {
2362                stmt.query_row(params![hash.as_str()], |row| {
2363                    Ok((row.get(0)?, row.get(1)?, row.get(2)?))
2364                })
2365                .optional()
2366            })
2367            .map_err(|e| OakError::Database(e.to_string()))?;
2368
2369        match result {
2370            None => Ok(None),
2371            Some((content, size, codec)) => Ok(Some(Blob {
2372                hash: hash.clone(),
2373                content: decode_blob(content, codec)?,
2374                size: size as u64,
2375            })),
2376        }
2377    }
2378
2379    fn has_blob(&self, hash: &Hash) -> Result<bool> {
2380        let conn = self.conn.lock().unwrap();
2381        let exists: bool = conn
2382            .prepare_cached("SELECT EXISTS(SELECT 1 FROM blobs WHERE hash = ?1)")
2383            .and_then(|mut stmt| stmt.query_row(params![hash.as_str()], |row| row.get(0)))
2384            .map_err(|e| OakError::Database(e.to_string()))?;
2385        Ok(exists)
2386    }
2387
2388    fn has_blobs(&self, hashes: &[&Hash]) -> Result<Vec<bool>> {
2389        let conn = self.conn.lock().unwrap();
2390        Self::with_read_txn(&conn, |conn| {
2391            let mut stmt = conn
2392                .prepare_cached("SELECT EXISTS(SELECT 1 FROM blobs WHERE hash = ?1)")
2393                .map_err(|e| OakError::Database(e.to_string()))?;
2394            hashes
2395                .iter()
2396                .map(|hash| {
2397                    stmt.query_row(params![hash.as_str()], |row| row.get(0))
2398                        .map_err(|e| OakError::Database(e.to_string()))
2399                })
2400                .collect()
2401        })
2402    }
2403
2404    fn get_blob_size(&self, hash: &Hash) -> Result<Option<u64>> {
2405        let conn = self.conn.lock().unwrap();
2406        conn.query_row(
2407            "SELECT size FROM blobs WHERE hash = ?1",
2408            params![hash.as_str()],
2409            |row| row.get::<_, i64>(0),
2410        )
2411        .optional()
2412        .map(|size| size.map(|size| size as u64))
2413        .map_err(|error| OakError::Database(error.to_string()))
2414    }
2415
2416    /// Write a manifest as a tree. The hash of `manifest` is already the tree
2417    /// root hash (computed by `Manifest::new` via `build_tree`), so this is
2418    /// just a tree-store of the corresponding nested structure.
2419    fn store_manifest(&self, manifest: &Manifest) -> Result<()> {
2420        self.put_tree(manifest.entries.clone()).map(|_| ())
2421    }
2422
2423    /// Read a manifest by hash. Reads from the tree tables.
2424    fn get_manifest(&self, hash: &Hash) -> Result<Option<Manifest>> {
2425        if self.has_tree(hash)? {
2426            let entries = self.walk_tree(hash)?;
2427            return Ok(Some(Manifest {
2428                hash: hash.clone(),
2429                entries,
2430            }));
2431        }
2432        Ok(None)
2433    }
2434
2435    // --- Tree operations ---
2436
2437    fn store_tree(&self, tree: &Tree) -> Result<()> {
2438        let mut conn = self.conn.lock().unwrap();
2439        // Use a savepoint, not `transaction()`: clone/pull ingest calls this
2440        // inside an already-open bulk transaction (`BulkTxn`), and SQLite
2441        // rejects a nested `BEGIN` ("cannot start a transaction within a
2442        // transaction"). A savepoint nests cleanly inside the bulk txn and, when
2443        // there's no outer transaction (a standalone call), still commits on its
2444        // own — so these writes stay atomic in both cases.
2445        let tx = conn
2446            .savepoint()
2447            .map_err(|e| OakError::Database(e.to_string()))?;
2448
2449        insert_tree_row(&tx, tree)?;
2450
2451        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2452        Ok(())
2453    }
2454
2455    fn walk_tree(&self, root: &Hash) -> Result<Vec<ManifestEntry>> {
2456        self.tree_flattens.fetch_add(1, Ordering::Relaxed);
2457        let mut fetch = |h: &Hash| -> Result<Tree> {
2458            self.get_tree(h)?
2459                .ok_or_else(|| OakError::ManifestNotFound(h.to_string()))
2460        };
2461        crate::flatten_tree(root, &mut fetch)
2462    }
2463
2464    fn get_tree(&self, hash: &Hash) -> Result<Option<Tree>> {
2465        self.tree_reads.fetch_add(1, Ordering::Relaxed);
2466        if hash == &Tree::empty_hash() {
2467            return Ok(Some(Tree::empty()));
2468        }
2469        let conn = self.conn.lock().unwrap();
2470
2471        // New format (migration 0008): a single compressed-content row.
2472        // `content` is NULL for legacy trees still stored as tree_entries rows.
2473        let row: Option<Option<Vec<u8>>> = conn
2474            .prepare_cached("SELECT content FROM trees WHERE hash = ?1")
2475            .and_then(|mut stmt| {
2476                stmt.query_row(params![hash.as_str()], |r| r.get::<_, Option<Vec<u8>>>(0))
2477                    .optional()
2478            })
2479            .map_err(|e| OakError::Database(e.to_string()))?;
2480
2481        match row {
2482            None => Ok(None), // no such tree
2483            Some(Some(content)) => {
2484                let raw = zstd_decompress_tree(&content)?;
2485                let actual = hash_bytes(&raw);
2486                if &actual != hash {
2487                    return Err(OakError::InvalidHash(format!(
2488                        "tree {} does not match stored content hash {}",
2489                        hash, actual
2490                    )));
2491                }
2492                Ok(Some(Tree::from_canonical_bytes(hash.clone(), &raw)?))
2493            }
2494            Some(None) => Ok(Some(read_tree_entries(&conn, hash)?)), // legacy fallback
2495        }
2496    }
2497
2498    fn has_tree(&self, hash: &Hash) -> Result<bool> {
2499        if hash == &Tree::empty_hash() {
2500            return Ok(true);
2501        }
2502        let conn = self.conn.lock().unwrap();
2503        let exists: bool = conn
2504            .query_row(
2505                "SELECT EXISTS(SELECT 1 FROM trees WHERE hash = ?1)",
2506                params![hash.as_str()],
2507                |row| row.get(0),
2508            )
2509            .map_err(|e| OakError::Database(e.to_string()))?;
2510        Ok(exists)
2511    }
2512
2513    /// Optimized `put_tree`: builds the nested tree, then inserts all tree
2514    /// objects in a single transaction, skipping subtrees whose hash already
2515    /// exists. This is the key write-path optimization for tree storage.
2516    fn put_tree(&self, entries: Vec<ManifestEntry>) -> Result<Hash> {
2517        let built = crate::build_tree(&entries)?;
2518        let mut conn = self.conn.lock().unwrap();
2519        // Savepoint, not `transaction()`: clone/pull ingest can call this
2520        // while a bulk transaction is already open, and standalone tree writes
2521        // still need this block to be all-or-nothing.
2522        let tx = conn
2523            .savepoint()
2524            .map_err(|e| OakError::Database(e.to_string()))?;
2525
2526        for tree in &built.trees {
2527            let already_present: bool = tx
2528                .query_row(
2529                    "SELECT EXISTS(SELECT 1 FROM trees WHERE hash = ?1)",
2530                    params![tree.hash.as_str()],
2531                    |row| row.get(0),
2532                )
2533                .map_err(|e| OakError::Database(e.to_string()))?;
2534            if already_present {
2535                continue;
2536            }
2537
2538            insert_tree_row(&tx, tree)?;
2539        }
2540
2541        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2542        Ok(built.root_hash)
2543    }
2544
2545    // --- Branch operations ---
2546
2547    fn close_branch(&self, name: &str, close_reason: Option<crate::CloseReason>) -> Result<()> {
2548        let conn = self.conn.lock().unwrap();
2549        conn.execute(
2550            "UPDATE branches SET status = ?1, close_reason = ?2 WHERE name = ?3",
2551            params![
2552                BranchStatus::Closed.as_str(),
2553                close_reason.as_ref().map(|r| r.as_str()),
2554                name,
2555            ],
2556        )
2557        .map_err(|e| OakError::Database(e.to_string()))?;
2558        Ok(())
2559    }
2560
2561    fn update_branch_close_reason(
2562        &self,
2563        name: &str,
2564        close_reason: crate::CloseReason,
2565    ) -> Result<()> {
2566        let conn = self.conn.lock().unwrap();
2567        conn.execute(
2568            "UPDATE branches SET close_reason = ?1 WHERE name = ?2",
2569            params![close_reason.as_str(), name],
2570        )
2571        .map_err(|e| OakError::Database(e.to_string()))?;
2572        Ok(())
2573    }
2574
2575    fn store_branch(&self, branch: &Branch) -> Result<()> {
2576        let mut conn = self.conn.lock().unwrap();
2577        let tx = conn
2578            .savepoint()
2579            .map_err(|error| OakError::Database(error.to_string()))?;
2580        let generation = advance_description_generation(&tx)?;
2581        tx.execute(
2582            "INSERT OR IGNORE INTO branches (name, description, parent_branch, status, close_reason, created_at, description_generation) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
2583            params![
2584                branch.name,
2585                branch.description,
2586                branch.parent_branch,
2587                branch.status.as_str(),
2588                branch.close_reason.as_ref().map(|r| r.as_str()),
2589                branch.created_at.to_rfc3339(),
2590                generation,
2591            ],
2592        )
2593        .map_err(|e| OakError::Database(e.to_string()))?;
2594        tx.commit()
2595            .map_err(|error| OakError::Database(error.to_string()))
2596    }
2597
2598    fn get_branch(&self, name: &str) -> Result<Option<Branch>> {
2599        // (description, parent_branch, status, close_reason, created_at)
2600        type BranchRow = (
2601            Option<String>,
2602            Option<String>,
2603            String,
2604            Option<String>,
2605            String,
2606        );
2607        let conn = self.conn.lock().unwrap();
2608        let result: Option<BranchRow> = conn
2609            .query_row(
2610                "SELECT description, parent_branch, status, close_reason, created_at FROM branches WHERE name = ?1",
2611                params![name],
2612                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?, row.get(4)?)),
2613            )
2614            .optional()
2615            .map_err(|e| OakError::Database(e.to_string()))?;
2616
2617        match result {
2618            Some((description, parent_branch, status_str, close_reason_str, created_at_str)) => {
2619                let status = BranchStatus::from_db_str(&status_str);
2620                decode_branch_row(
2621                    name.to_string(),
2622                    description,
2623                    parent_branch,
2624                    status,
2625                    close_reason_str,
2626                    &created_at_str,
2627                )
2628                .map(Some)
2629                .map_err(|unreadable| unreadable.to_error())
2630            }
2631            None => Ok(None),
2632        }
2633    }
2634
2635    fn list_branches(&self) -> Result<Vec<Branch>> {
2636        self.list_branches_isolated()?
2637            .into_iter()
2638            .map(|row| row.map_err(|unreadable| unreadable.to_error()))
2639            .collect()
2640    }
2641
2642    fn list_branches_isolated(
2643        &self,
2644    ) -> Result<Vec<std::result::Result<Branch, crate::UnreadableBranch>>> {
2645        let conn = self.conn.lock().unwrap();
2646        let mut stmt = conn
2647            .prepare("SELECT name, description, parent_branch, status, close_reason, created_at FROM branches ORDER BY created_at ASC")
2648            .map_err(|e| OakError::Database(e.to_string()))?;
2649
2650        let branches = stmt
2651            .query_map([], |row| {
2652                let name: String = row.get(0)?;
2653                let description: Option<String> = row.get(1)?;
2654                let parent_branch: Option<String> = row.get(2)?;
2655                let status_str: String = row.get(3)?;
2656                let close_reason_str: Option<String> = row.get(4)?;
2657                let created_at_str: String = row.get(5)?;
2658                Ok((
2659                    name,
2660                    description,
2661                    parent_branch,
2662                    status_str,
2663                    close_reason_str,
2664                    created_at_str,
2665                ))
2666            })
2667            .map_err(|e| OakError::Database(e.to_string()))?
2668            .collect::<std::result::Result<Vec<_>, _>>()
2669            .map_err(|e| OakError::Database(e.to_string()))?;
2670
2671        branches
2672            .into_iter()
2673            .map(
2674                |(
2675                    name,
2676                    description,
2677                    parent_branch,
2678                    status_str,
2679                    close_reason_str,
2680                    created_at_str,
2681                )| {
2682                    decode_branch_row(
2683                        name,
2684                        description,
2685                        parent_branch,
2686                        BranchStatus::from_db_str(&status_str),
2687                        close_reason_str,
2688                        &created_at_str,
2689                    )
2690                },
2691            )
2692            .map(Ok)
2693            .collect()
2694    }
2695
2696    fn update_branch_status(&self, name: &str, status: BranchStatus) -> Result<()> {
2697        let conn = self.conn.lock().unwrap();
2698        conn.execute(
2699            "UPDATE branches SET status = ?1 WHERE name = ?2",
2700            params![status.as_str(), name],
2701        )
2702        .map_err(|e| OakError::Database(e.to_string()))?;
2703        Ok(())
2704    }
2705
2706    fn set_branch_parent(&self, name: &str, parent: Option<&str>) -> Result<()> {
2707        let conn = self.conn.lock().unwrap();
2708        conn.execute(
2709            "UPDATE branches SET parent_branch = ?1 WHERE name = ?2",
2710            params![parent, name],
2711        )
2712        .map_err(|e| OakError::Database(e.to_string()))?;
2713        Ok(())
2714    }
2715
2716    fn update_branch_description(&self, name: &str, description: &str) -> Result<()> {
2717        let mut conn = self.conn.lock().unwrap();
2718        let tx = conn
2719            .savepoint()
2720            .map_err(|error| OakError::Database(error.to_string()))?;
2721        let generation = advance_description_generation(&tx)?;
2722        tx.execute(
2723            "UPDATE branches SET description = ?1, description_generation = ?3 WHERE name = ?2",
2724            params![description, name, generation],
2725        )
2726        .map_err(|e| OakError::Database(e.to_string()))?;
2727        tx.commit()
2728            .map_err(|error| OakError::Database(error.to_string()))
2729    }
2730
2731    fn edit_branch_description(&self, name: &str, description: &str) -> Result<()> {
2732        let mut conn = self.conn.lock().unwrap();
2733        let tx = conn
2734            .savepoint()
2735            .map_err(|error| OakError::Database(error.to_string()))?;
2736        let generation = advance_description_generation(&tx)?;
2737        tx.execute(
2738            "UPDATE branches SET description = ?1, description_pending = 1, description_generation = ?3 WHERE name = ?2",
2739            params![description, name, generation],
2740        )
2741        .map_err(|error| OakError::Database(error.to_string()))?;
2742        tx.commit()
2743            .map_err(|error| OakError::Database(error.to_string()))
2744    }
2745
2746    fn description_publication_generation(&self) -> Result<Option<i64>> {
2747        self.description_generation().map(Some)
2748    }
2749
2750    fn acknowledge_branch_description(
2751        &self,
2752        name: &str,
2753        description: Option<&str>,
2754        generation: Option<i64>,
2755    ) -> Result<()> {
2756        let mut conn = self.conn.lock().unwrap();
2757        let tx = conn
2758            .savepoint()
2759            .map_err(|error| OakError::Database(error.to_string()))?;
2760        // Publication changes which remote responses are safe to reconcile,
2761        // even when the text itself did not change. Fence fetches that began
2762        // before this acknowledgment, including while the POST was in flight.
2763        let acknowledged_generation = advance_description_generation(&tx)?;
2764        tx.execute(
2765            "UPDATE branches SET description_pending = 0, description_generation = ?4 WHERE name = ?1 AND description IS ?2 AND description_generation <= ?3",
2766            params![name, description, generation, acknowledged_generation],
2767        )
2768        .map_err(|error| OakError::Database(error.to_string()))?;
2769        tx.commit()
2770            .map_err(|error| OakError::Database(error.to_string()))
2771    }
2772
2773    fn rename_branch(&self, old_name: &str, new_name: &str) -> Result<()> {
2774        if old_name == new_name {
2775            return Ok(());
2776        }
2777        if new_name.is_empty() {
2778            return Err(OakError::Database("new branch name cannot be empty".into()));
2779        }
2780
2781        let mut conn = self.conn.lock().unwrap();
2782        // Savepoint, not `transaction()`: pull publishes branch renames inside
2783        // an already-open write transaction, while standalone branch rename
2784        // still needs this block to be all-or-nothing.
2785        let tx = conn
2786            .savepoint()
2787            .map_err(|e| OakError::Database(e.to_string()))?;
2788
2789        let exists: bool = tx
2790            .query_row(
2791                "SELECT 1 FROM branches WHERE name = ?1",
2792                params![old_name],
2793                |_| Ok(true),
2794            )
2795            .optional()
2796            .map_err(|e| OakError::Database(e.to_string()))?
2797            .unwrap_or(false);
2798        if !exists {
2799            return Err(OakError::BranchNotFound(old_name.to_string()));
2800        }
2801
2802        let conflict: bool = tx
2803            .query_row(
2804                "SELECT 1 FROM branches WHERE name = ?1
2805                 UNION
2806                 SELECT 1 FROM branch_heads WHERE branch_name = ?1",
2807                params![new_name],
2808                |_| Ok(true),
2809            )
2810            .optional()
2811            .map_err(|e| OakError::Database(e.to_string()))?
2812            .unwrap_or(false);
2813        if conflict {
2814            return Err(OakError::BranchAlreadyExists(new_name.to_string()));
2815        }
2816
2817        // Insert renamed row, repoint all references, then delete the old row.
2818        // Insert-before-update keeps FK semantics correct if foreign_keys are
2819        // ever turned on; the order below is safe with FKs OFF too.
2820        let generation = advance_description_generation(&tx)?;
2821        tx.execute(
2822            "INSERT INTO branches (name, description, parent_branch, status, close_reason, created_at, description_pending, description_generation) \
2823             SELECT ?1, description, parent_branch, status, close_reason, created_at, description_pending, ?3 FROM branches WHERE name = ?2",
2824            params![new_name, old_name, generation],
2825        )
2826        .map_err(|e| OakError::Database(e.to_string()))?;
2827
2828        tx.execute(
2829            "UPDATE branches SET parent_branch = ?1 WHERE parent_branch = ?2",
2830            params![new_name, old_name],
2831        )
2832        .map_err(|e| OakError::Database(e.to_string()))?;
2833
2834        tx.execute(
2835            "UPDATE commits SET branch_name = ?1 WHERE branch_name = ?2",
2836            params![new_name, old_name],
2837        )
2838        .map_err(|e| OakError::Database(e.to_string()))?;
2839
2840        tx.execute(
2841            "UPDATE branch_heads SET branch_name = ?1 WHERE branch_name = ?2",
2842            params![new_name, old_name],
2843        )
2844        .map_err(|e| OakError::Database(e.to_string()))?;
2845
2846        tx.execute(
2847            "UPDATE metadata SET value = ?1 WHERE key = ?2 AND value = ?3",
2848            params![new_name, MetadataKey::CurrentBranch.as_str(), old_name],
2849        )
2850        .map_err(|e| OakError::Database(e.to_string()))?;
2851
2852        tx.execute("DELETE FROM branches WHERE name = ?1", params![old_name])
2853            .map_err(|e| OakError::Database(e.to_string()))?;
2854
2855        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2856        Ok(())
2857    }
2858
2859    fn delete_branch(&self, name: &str) -> Result<()> {
2860        let mut conn = self.conn.lock().unwrap();
2861        let tx = conn
2862            .transaction()
2863            .map_err(|e| OakError::Database(e.to_string()))?;
2864        tx.execute(
2865            "DELETE FROM branch_heads WHERE branch_name = ?1",
2866            params![name],
2867        )
2868        .map_err(|e| OakError::Database(e.to_string()))?;
2869        tx.execute("DELETE FROM branches WHERE name = ?1", params![name])
2870            .map_err(|e| OakError::Database(e.to_string()))?;
2871        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2872        Ok(())
2873    }
2874
2875    fn get_branch_head(&self, name: &str) -> Result<Option<Hash>> {
2876        let conn = self.conn.lock().unwrap();
2877        let result: Option<String> = conn
2878            .query_row(
2879                "SELECT head_hash FROM branch_heads WHERE branch_name = ?1",
2880                params![name],
2881                |row| row.get(0),
2882            )
2883            .optional()
2884            .map_err(|e| OakError::Database(e.to_string()))?;
2885        Ok(result.map(Hash))
2886    }
2887
2888    fn set_branch_head(&self, name: &str, hash: &Hash) -> Result<()> {
2889        let conn = self.conn.lock().unwrap();
2890        conn.execute(
2891            "INSERT OR REPLACE INTO branch_heads (branch_name, head_hash) VALUES (?1, ?2)",
2892            params![name, hash.as_str()],
2893        )
2894        .map_err(|e| OakError::Database(e.to_string()))?;
2895        Ok(())
2896    }
2897
2898    fn reconcile_remote_merge_branch_state(
2899        &self,
2900        closed_branch: &str,
2901        new_branch: &Branch,
2902        seed_head: &Hash,
2903    ) -> Result<()> {
2904        let mut conn = self.conn.lock().unwrap();
2905        let tx = conn
2906            .transaction()
2907            .map_err(|e| OakError::Database(e.to_string()))?;
2908        let generation = advance_description_generation(&tx)?;
2909
2910        tx.execute(
2911            "UPDATE branches SET status = ?1 WHERE name = ?2",
2912            params![BranchStatus::Closed.as_str(), closed_branch],
2913        )
2914        .map_err(|e| OakError::Database(e.to_string()))?;
2915        tx.execute(
2916            "INSERT OR IGNORE INTO branches (name, description, parent_branch, status, close_reason, created_at, description_generation) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
2917            params![
2918                new_branch.name,
2919                new_branch.description,
2920                new_branch.parent_branch,
2921                new_branch.status.as_str(),
2922                new_branch.close_reason.as_ref().map(|r| r.as_str()),
2923                new_branch.created_at.to_rfc3339(),
2924                generation,
2925            ],
2926        )
2927        .map_err(|e| OakError::Database(e.to_string()))?;
2928        tx.execute(
2929            "INSERT OR REPLACE INTO branch_heads (branch_name, head_hash) VALUES (?1, ?2)",
2930            params![new_branch.name, seed_head.as_str()],
2931        )
2932        .map_err(|e| OakError::Database(e.to_string()))?;
2933        tx.execute(
2934            "INSERT OR REPLACE INTO metadata (key, value) VALUES (?1, ?2)",
2935            params![MetadataKey::Head.as_str(), seed_head.as_str()],
2936        )
2937        .map_err(|e| OakError::Database(e.to_string()))?;
2938        tx.execute(
2939            "INSERT OR REPLACE INTO metadata (key, value) VALUES (?1, ?2)",
2940            params![MetadataKey::CurrentBranch.as_str(), new_branch.name],
2941        )
2942        .map_err(|e| OakError::Database(e.to_string()))?;
2943
2944        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
2945        Ok(())
2946    }
2947
2948    // --- Commit operations ---
2949
2950    fn store_commit(&self, commit: &Commit) -> Result<()> {
2951        let mut conn = self.conn.lock().unwrap();
2952        // Savepoint rather than `transaction()` for the same reason as
2953        // `store_tree`: clone/pull's `store_pull_response` calls this inside an
2954        // open `BulkTxn`, where a nested `BEGIN` would error. A savepoint nests
2955        // there and still commits standalone.
2956        let tx = conn
2957            .savepoint()
2958            .map_err(|e| OakError::Database(e.to_string()))?;
2959
2960        let inserted = tx
2961            .execute(
2962            "INSERT OR IGNORE INTO commits (hash, branch_name, parent_hash, merge_parent_hash, manifest_hash, author, message, timestamp) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2963            params![
2964                commit.hash.as_str(),
2965                commit.branch_name,
2966                commit.parent_hash.as_ref().map(|h| h.as_str()),
2967                commit.merge_parent_hash.as_ref().map(|h| h.as_str()),
2968                commit.manifest_hash.as_str(),
2969                commit.author,
2970                commit.message,
2971                commit.timestamp.to_rfc3339(),
2972            ],
2973        )
2974            .map_err(|e| OakError::Database(e.to_string()))?;
2975
2976        if inserted != 0 {
2977            for file in &commit.files {
2978                let change_type_str = match file.change_type {
2979                    ChangeType::Added => "added",
2980                    ChangeType::Modified => "modified",
2981                    ChangeType::Deleted => "deleted",
2982                    ChangeType::Renamed => "renamed",
2983                };
2984
2985                tx.execute(
2986                    "INSERT INTO commit_files (commit_hash, path, change_type, old_blob_hash, new_blob_hash, old_path) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
2987                    params![
2988                        commit.hash.as_str(),
2989                        file.path,
2990                        change_type_str,
2991                        file.old_blob_hash.as_ref().map(|h| h.as_str()),
2992                        file.new_blob_hash.as_ref().map(|h| h.as_str()),
2993                        file.old_path,
2994                    ],
2995                )
2996                .map_err(|e| OakError::Database(e.to_string()))?;
2997            }
2998        }
2999
3000        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
3001        Ok(())
3002    }
3003
3004    fn get_commit(&self, hash: &Hash) -> Result<Option<Commit>> {
3005        let conn = self.conn.lock().unwrap();
3006
3007        #[allow(clippy::type_complexity)]
3008        let result: Option<(String, Option<String>, Option<String>, String, String, Option<String>, String)> = conn
3009            .query_row(
3010                "SELECT branch_name, parent_hash, merge_parent_hash, manifest_hash, author, message, timestamp FROM commits WHERE hash = ?1",
3011                params![hash.as_str()],
3012                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?, row.get(4)?, row.get(5)?, row.get(6)?)),
3013            )
3014            .optional()
3015            .map_err(|e| OakError::Database(e.to_string()))?;
3016
3017        let (
3018            branch_name,
3019            parent_hash,
3020            merge_parent_hash,
3021            manifest_hash,
3022            author,
3023            message,
3024            timestamp_str,
3025        ) = match result {
3026            Some(r) => r,
3027            None => return Ok(None),
3028        };
3029
3030        let mut stmt = conn
3031            .prepare("SELECT path, change_type, old_blob_hash, new_blob_hash, old_path FROM commit_files WHERE commit_hash = ?1")
3032            .map_err(|e| OakError::Database(e.to_string()))?;
3033
3034        let files: Vec<FileChange> = stmt
3035            .query_map(params![hash.as_str()], |row| {
3036                let path: String = row.get(0)?;
3037                let change_type_str: String = row.get(1)?;
3038                let old_blob_hash: Option<String> = row.get(2)?;
3039                let new_blob_hash: Option<String> = row.get(3)?;
3040                let old_path: Option<String> = row.get(4)?;
3041
3042                let change_type = match change_type_str.as_str() {
3043                    "added" => ChangeType::Added,
3044                    "deleted" => ChangeType::Deleted,
3045                    "renamed" => ChangeType::Renamed,
3046                    _ => ChangeType::Modified,
3047                };
3048
3049                Ok(FileChange {
3050                    path,
3051                    change_type,
3052                    old_blob_hash: old_blob_hash.map(Hash),
3053                    new_blob_hash: new_blob_hash.map(Hash),
3054                    old_path,
3055                    old_mode: None,
3056                    new_mode: None,
3057                })
3058            })
3059            .map_err(|e| OakError::Database(e.to_string()))?
3060            .collect::<std::result::Result<Vec<_>, _>>()
3061            .map_err(|e| OakError::Database(e.to_string()))?;
3062
3063        let timestamp = chrono::DateTime::parse_from_rfc3339(&timestamp_str)
3064            .map_err(|e| OakError::Database(e.to_string()))?
3065            .with_timezone(&chrono::Utc);
3066
3067        Ok(Some(Commit {
3068            hash: hash.clone(),
3069            branch_name,
3070            parent_hash: parent_hash.map(Hash),
3071            merge_parent_hash: merge_parent_hash.map(Hash),
3072            manifest_hash: Hash(manifest_hash),
3073            author,
3074            message,
3075            timestamp,
3076            files,
3077        }))
3078    }
3079
3080    fn repair_commit_fields(&self, verified: &Commit) -> Result<bool> {
3081        verified.verify_fields()?;
3082        let Some(stored) = self.get_commit(&verified.hash)? else {
3083            return Ok(false);
3084        };
3085        if stored.verify_fields().is_ok() {
3086            return Ok(false);
3087        }
3088        if stored.parent_hash != verified.parent_hash
3089            || stored.merge_parent_hash != verified.merge_parent_hash
3090            || stored.manifest_hash != verified.manifest_hash
3091        {
3092            return Err(OakError::InvalidHash(format!(
3093                "refusing to repair commit {}: the verified fields name different parents or a different manifest than the stored row",
3094                verified.hash.short()
3095            )));
3096        }
3097        let conn = self.conn.lock().unwrap();
3098        let changed = conn
3099            .execute(
3100                "UPDATE commits SET branch_name = ?2, author = ?3, message = ?4, timestamp = ?5 WHERE hash = ?1",
3101                params![
3102                    verified.hash.as_str(),
3103                    verified.branch_name,
3104                    verified.author,
3105                    verified.message,
3106                    verified.timestamp.to_rfc3339(),
3107                ],
3108            )
3109            .map_err(|e| OakError::Database(e.to_string()))?;
3110        Ok(changed != 0)
3111    }
3112
3113    fn has_commit(&self, hash: &Hash) -> Result<bool> {
3114        let conn = self.conn.lock().unwrap();
3115        let count: i64 = conn
3116            .query_row(
3117                "SELECT COUNT(*) FROM commits WHERE hash = ?1",
3118                params![hash.as_str()],
3119                |row| row.get(0),
3120            )
3121            .map_err(|e| OakError::Database(e.to_string()))?;
3122        Ok(count > 0)
3123    }
3124
3125    fn get_commits_for_branch(&self, branch_name: &str) -> Result<Vec<Commit>> {
3126        let conn = self.conn.lock().unwrap();
3127        let mut stmt = conn
3128            .prepare("SELECT hash FROM commits WHERE branch_name = ?1 ORDER BY timestamp ASC")
3129            .map_err(|e| OakError::Database(e.to_string()))?;
3130
3131        let hashes: Vec<String> = stmt
3132            .query_map(params![branch_name], |row| row.get(0))
3133            .map_err(|e| OakError::Database(e.to_string()))?
3134            .collect::<std::result::Result<Vec<_>, _>>()
3135            .map_err(|e| OakError::Database(e.to_string()))?;
3136
3137        drop(stmt);
3138        drop(conn);
3139
3140        let mut commits = Vec::new();
3141        for hash in hashes {
3142            if let Some(edit) = self.get_commit(&Hash(hash))? {
3143                commits.push(edit);
3144            }
3145        }
3146        Ok(commits)
3147    }
3148
3149    fn count_commits_for_branch(&self, branch_name: &str) -> Result<usize> {
3150        let conn = self.conn.lock().unwrap();
3151        let count: i64 = conn
3152            .query_row(
3153                "SELECT COUNT(*) FROM commits WHERE branch_name = ?1",
3154                params![branch_name],
3155                |row| row.get(0),
3156            )
3157            .map_err(|e| OakError::Database(e.to_string()))?;
3158        Ok(count as usize)
3159    }
3160
3161    fn merge_child_exists(&self, branch_head: &Hash) -> Result<bool> {
3162        let conn = self.conn.lock().unwrap();
3163        let exists: bool = conn
3164            .query_row(
3165                "SELECT EXISTS(SELECT 1 FROM commits WHERE merge_parent_hash = ?1)",
3166                params![branch_head.as_str()],
3167                |row| row.get(0),
3168            )
3169            .map_err(|e| OakError::Database(e.to_string()))?;
3170        Ok(exists)
3171    }
3172
3173    fn get_commits_since(&self, branch_name: &str, since: Option<&Hash>) -> Result<Vec<Commit>> {
3174        let all = self.get_commits_for_branch(branch_name)?;
3175
3176        match since {
3177            None => Ok(all),
3178            Some(since_hash) => {
3179                let mut found = false;
3180                let mut result = Vec::new();
3181                for commit in &all {
3182                    if &commit.hash == since_hash {
3183                        found = true;
3184                    } else if found {
3185                        result.push(commit.clone());
3186                    }
3187                }
3188                // If since_hash wasn't found in this branch's commits (e.g.
3189                // it belongs to a different branch), return all commits —
3190                // they are all new from the caller's perspective.
3191                if !found {
3192                    return Ok(all);
3193                }
3194                Ok(result)
3195            }
3196        }
3197    }
3198
3199    fn get_all_commits(&self) -> Result<Vec<Commit>> {
3200        let conn = self.conn.lock().unwrap();
3201        let mut stmt = conn
3202            .prepare("SELECT hash FROM commits ORDER BY timestamp ASC")
3203            .map_err(|e| OakError::Database(e.to_string()))?;
3204
3205        let hashes: Vec<String> = stmt
3206            .query_map([], |row| row.get(0))
3207            .map_err(|e| OakError::Database(e.to_string()))?
3208            .collect::<std::result::Result<Vec<_>, _>>()
3209            .map_err(|e| OakError::Database(e.to_string()))?;
3210
3211        drop(stmt);
3212        drop(conn);
3213
3214        let mut commits = Vec::new();
3215        for hash in hashes {
3216            if let Some(edit) = self.get_commit(&Hash(hash))? {
3217                commits.push(edit);
3218            }
3219        }
3220        Ok(commits)
3221    }
3222
3223    // --- Metadata ---
3224
3225    fn get_metadata(&self, key: MetadataKey) -> Result<Option<String>> {
3226        let conn = self.conn.lock().unwrap();
3227        let result: Option<String> = conn
3228            .query_row(
3229                "SELECT value FROM metadata WHERE key = ?1",
3230                params![key.as_str()],
3231                |row| row.get(0),
3232            )
3233            .optional()
3234            .map_err(|e| OakError::Database(e.to_string()))?;
3235        Ok(result)
3236    }
3237
3238    fn set_metadata(&self, key: MetadataKey, value: &str) -> Result<()> {
3239        let conn = self.conn.lock().unwrap();
3240        conn.execute(
3241            "INSERT OR REPLACE INTO metadata (key, value) VALUES (?1, ?2)",
3242            params![key.as_str(), value],
3243        )
3244        .map_err(|e| OakError::Database(e.to_string()))?;
3245        Ok(())
3246    }
3247
3248    fn insert_metadata_if_absent(&self, key: MetadataKey, value: &str) -> Result<bool> {
3249        let conn = self.conn.lock().unwrap();
3250        let inserted = conn
3251            .execute(
3252                "INSERT OR IGNORE INTO metadata (key, value) VALUES (?1, ?2)",
3253                params![key.as_str(), value],
3254            )
3255            .map_err(|e| OakError::Database(e.to_string()))?;
3256        Ok(inserted > 0)
3257    }
3258
3259    // --- Working-tree stat cache ---
3260
3261    fn load_stat_cache(&self) -> Result<HashMap<String, StatCacheEntry>> {
3262        let conn = self.conn.lock().unwrap();
3263        let mut stmt = conn
3264            .prepare("SELECT path, mtime_ns, ctime_ns, size, blob_hash FROM stat_cache")
3265            .map_err(|e| OakError::Database(e.to_string()))?;
3266        let rows = stmt
3267            .query_map([], |row| {
3268                Ok((
3269                    row.get::<_, String>(0)?,
3270                    StatCacheEntry {
3271                        mtime_ns: row.get(1)?,
3272                        ctime_ns: row.get(2)?,
3273                        size: row.get(3)?,
3274                        blob_hash: Hash(row.get::<_, String>(4)?),
3275                    },
3276                ))
3277            })
3278            .map_err(|e| OakError::Database(e.to_string()))?;
3279        let mut map = HashMap::new();
3280        for row in rows {
3281            let (path, entry) = row.map_err(|e| OakError::Database(e.to_string()))?;
3282            map.insert(path, entry);
3283        }
3284        Ok(map)
3285    }
3286
3287    fn update_stat_cache(
3288        &self,
3289        upserts: &[(String, StatCacheEntry)],
3290        removed: &[String],
3291    ) -> Result<()> {
3292        if upserts.is_empty() && removed.is_empty() {
3293            return Ok(());
3294        }
3295        let mut conn = self.conn.lock().unwrap();
3296        let tx = conn
3297            .transaction()
3298            .map_err(|e| OakError::Database(e.to_string()))?;
3299        {
3300            let mut upsert = tx
3301                .prepare(
3302                    "INSERT INTO stat_cache (path, mtime_ns, ctime_ns, size, blob_hash) VALUES (?1, ?2, ?3, ?4, ?5)
3303                     ON CONFLICT(path) DO UPDATE SET
3304                         mtime_ns = excluded.mtime_ns,
3305                         ctime_ns = excluded.ctime_ns,
3306                         size = excluded.size,
3307                         blob_hash = excluded.blob_hash",
3308                )
3309                .map_err(|e| OakError::Database(e.to_string()))?;
3310            for (path, entry) in upserts {
3311                upsert
3312                    .execute(params![
3313                        path,
3314                        entry.mtime_ns,
3315                        entry.ctime_ns,
3316                        entry.size,
3317                        entry.blob_hash.as_str()
3318                    ])
3319                    .map_err(|e| OakError::Database(e.to_string()))?;
3320            }
3321            let mut delete = tx
3322                .prepare("DELETE FROM stat_cache WHERE path = ?1")
3323                .map_err(|e| OakError::Database(e.to_string()))?;
3324            for path in removed {
3325                delete
3326                    .execute(params![path])
3327                    .map_err(|e| OakError::Database(e.to_string()))?;
3328            }
3329        }
3330        tx.commit().map_err(|e| OakError::Database(e.to_string()))?;
3331        Ok(())
3332    }
3333
3334    // --- Chunk operations ---
3335
3336    fn store_chunk(&self, hash: &Hash, content: &[u8]) -> Result<()> {
3337        let actual = hash_bytes(content);
3338        if &actual != hash {
3339            return Err(OakError::InvalidHash(format!(
3340                "chunk {} does not match content hash {}",
3341                hash, actual
3342            )));
3343        }
3344        let conn = self.conn.lock().unwrap();
3345        conn.execute(
3346            "INSERT OR IGNORE INTO chunks (hash, content, size) VALUES (?1, ?2, ?3)",
3347            params![hash.as_str(), content, content.len() as i64],
3348        )
3349        .map_err(|e| OakError::Database(e.to_string()))?;
3350        Ok(())
3351    }
3352
3353    fn get_chunk(&self, hash: &Hash) -> Result<Option<Vec<u8>>> {
3354        let conn = self.conn.lock().unwrap();
3355        let result: Option<Vec<u8>> = conn
3356            .query_row(
3357                "SELECT content FROM chunks WHERE hash = ?1",
3358                params![hash.as_str()],
3359                |row| row.get(0),
3360            )
3361            .optional()
3362            .map_err(|e| OakError::Database(e.to_string()))?;
3363        Ok(result)
3364    }
3365
3366    fn has_chunk(&self, hash: &Hash) -> Result<bool> {
3367        let conn = self.conn.lock().unwrap();
3368        let exists: bool = conn
3369            .query_row(
3370                "SELECT EXISTS(SELECT 1 FROM chunks WHERE hash = ?1)",
3371                params![hash.as_str()],
3372                |row| row.get(0),
3373            )
3374            .map_err(|e| OakError::Database(e.to_string()))?;
3375        Ok(exists)
3376    }
3377
3378    fn store_blob_chunks(&self, blob_hash: &Hash, chunks: &[ChunkInfo]) -> Result<()> {
3379        let conn = self.conn.lock().unwrap();
3380        for (index, chunk) in chunks.iter().enumerate() {
3381            conn.execute(
3382                "INSERT OR IGNORE INTO blob_chunks (blob_hash, chunk_hash, chunk_index, offset, size) VALUES (?1, ?2, ?3, ?4, ?5)",
3383                params![
3384                    blob_hash.as_str(),
3385                    chunk.hash.as_str(),
3386                    index as i64,
3387                    chunk.offset as i64,
3388                    chunk.length as i64,
3389                ],
3390            )
3391            .map_err(|e| OakError::Database(e.to_string()))?;
3392        }
3393        Ok(())
3394    }
3395
3396    fn get_blob_chunks(&self, blob_hash: &Hash) -> Result<Option<Vec<ChunkInfo>>> {
3397        let conn = self.conn.lock().unwrap();
3398        let mut stmt = conn
3399            .prepare(
3400                "SELECT chunk_hash, offset, size FROM blob_chunks WHERE blob_hash = ?1 ORDER BY chunk_index",
3401            )
3402            .map_err(|e| OakError::Database(e.to_string()))?;
3403
3404        let rows: Vec<ChunkInfo> = stmt
3405            .query_map(params![blob_hash.as_str()], |row| {
3406                let hash_str: String = row.get(0)?;
3407                let offset: i64 = row.get(1)?;
3408                let size: i64 = row.get(2)?;
3409                Ok(ChunkInfo {
3410                    hash: Hash(hash_str),
3411                    offset: offset as u64,
3412                    length: size as u32,
3413                })
3414            })
3415            .map_err(|e| OakError::Database(e.to_string()))?
3416            .collect::<std::result::Result<Vec<_>, _>>()
3417            .map_err(|e| OakError::Database(e.to_string()))?;
3418
3419        if rows.is_empty() {
3420            Ok(None)
3421        } else {
3422            Ok(Some(rows))
3423        }
3424    }
3425
3426    fn put_commit_and_advance_refs(
3427        &self,
3428        branch_name: String,
3429        parent_hash: Option<Hash>,
3430        merge_parent_hash: Option<Hash>,
3431        entries: Vec<ManifestEntry>,
3432        author: String,
3433        message: Option<String>,
3434        timestamp: chrono::DateTime<chrono::Utc>,
3435        files: Vec<FileChange>,
3436    ) -> Result<Hash> {
3437        // Build tree structure and hash the commit before opening the
3438        // transaction so the SQLite write lock is held only for publication.
3439        let built = crate::build_tree(&entries)?;
3440        let manifest_hash = built.root_hash.clone();
3441        let commit = Commit::with_timestamp(
3442            branch_name,
3443            parent_hash,
3444            merge_parent_hash,
3445            manifest_hash,
3446            author,
3447            message,
3448            files,
3449            timestamp,
3450        )?;
3451        let commit_hash = commit.hash.clone();
3452
3453        self.publish_commit(&commit, &built.trees, false)?;
3454        Ok(commit_hash)
3455    }
3456
3457    fn put_tree_commit_and_advance_refs(
3458        &self,
3459        branch_name: String,
3460        parent_hash: Option<Hash>,
3461        merge_parent_hash: Option<Hash>,
3462        root: Hash,
3463        trees: &[Tree],
3464        author: String,
3465        message: Option<String>,
3466        timestamp: chrono::DateTime<chrono::Utc>,
3467        files: Vec<FileChange>,
3468    ) -> Result<Hash> {
3469        let commit = Commit::with_timestamp(
3470            branch_name,
3471            parent_hash,
3472            merge_parent_hash,
3473            root,
3474            author,
3475            message,
3476            files,
3477            timestamp,
3478        )?;
3479        let commit_hash = commit.hash.clone();
3480        self.publish_commit(&commit, trees, true)?;
3481        Ok(commit_hash)
3482    }
3483}
3484
3485// --- Test instrumentation ---
3486
3487impl SqliteRepository {
3488    /// How many whole trees have been flattened through this handle by
3489    /// [`Repository::walk_tree`] or [`Repository::get_manifest`]. Test
3490    /// instrumentation for load budgets (e.g. `oak status --json` flattens
3491    /// HEAD exactly once).
3492    #[doc(hidden)]
3493    pub fn tree_flatten_count(&self) -> u64 {
3494        self.tree_flattens.load(Ordering::Relaxed)
3495    }
3496
3497    /// How many tree objects [`Repository::get_tree`] has been asked for
3498    /// through this handle. A flatten that bypasses `walk_tree` (a caller
3499    /// driving `flatten_tree` with its own fetch closure) still shows up
3500    /// here, one read per directory.
3501    #[doc(hidden)]
3502    pub fn tree_read_count(&self) -> u64 {
3503        self.tree_reads.load(Ordering::Relaxed)
3504    }
3505}
3506
3507#[cfg(test)]
3508mod tests {
3509    use super::*;
3510
3511    #[test]
3512    fn tree_decoder_reuses_context_and_grows_for_large_rows() {
3513        let small = b"blob\ta.txt\tabc\tregular".to_vec();
3514        // Larger than the initial 64 KiB buffer and poorly compressible.
3515        let large: Vec<u8> = (0..300_000u32)
3516            .map(|i| (i.wrapping_mul(2_654_435_761) >> 13) as u8)
3517            .collect();
3518        for raw in [&small, &large, &small] {
3519            let stored = zstd_compress(raw).unwrap();
3520            assert_eq!(&zstd_decompress_tree(&stored).unwrap(), raw);
3521        }
3522        let frame = zstd_compress(&small).unwrap();
3523        for bad in [
3524            b"not a zstd frame".to_vec(),
3525            Vec::new(),
3526            [frame.as_slice(), b"trailing"].concat(),
3527            frame[..frame.len() - 1].to_vec(),
3528        ] {
3529            assert_eq!(
3530                zstd_decompress_tree(&bad).is_err(),
3531                zstd_decompress(&bad).is_err(),
3532                "{bad:?}"
3533            );
3534        }
3535        let two = [frame.as_slice(), frame.as_slice()].concat();
3536        assert_eq!(
3537            zstd_decompress_tree(&two).unwrap(),
3538            zstd_decompress(&two).unwrap()
3539        );
3540        assert!(zstd_decompress_tree(b"not a zstd frame").is_err());
3541        // A failed row leaves the per-thread decoder usable.
3542        assert_eq!(
3543            zstd_decompress_tree(&zstd_compress(&small).unwrap()).unwrap(),
3544            small
3545        );
3546    }
3547
3548    fn delete_migration_row(db_path: &Path, version: &str) {
3549        let conn = Connection::open(db_path).unwrap();
3550        conn.execute(
3551            "DELETE FROM schema_migrations WHERE version = ?1",
3552            params![version],
3553        )
3554        .unwrap();
3555    }
3556
3557    fn migration_succeeded(db_path: &Path, version: &str) -> bool {
3558        let conn = Connection::open(db_path).unwrap();
3559        conn.query_row(
3560            "SELECT succeeded FROM schema_migrations WHERE version = ?1",
3561            params![version],
3562            |row| row.get::<_, i64>(0),
3563        )
3564        .optional()
3565        .unwrap()
3566            == Some(1)
3567    }
3568
3569    #[test]
3570    fn missing_0007_row_with_existing_blob_codec_is_marked_applied() {
3571        let temp = tempfile::TempDir::new().unwrap();
3572        let db_path = temp.path().join("oak.db");
3573        drop(SqliteRepository::open(&db_path).unwrap());
3574        delete_migration_row(&db_path, "0007_blobs_codec");
3575
3576        SqliteRepository::open(&db_path).unwrap();
3577
3578        assert!(migration_succeeded(&db_path, "0007_blobs_codec"));
3579    }
3580
3581    #[test]
3582    fn missing_0008_row_with_existing_tree_content_is_marked_applied() {
3583        let temp = tempfile::TempDir::new().unwrap();
3584        let db_path = temp.path().join("oak.db");
3585        drop(SqliteRepository::open(&db_path).unwrap());
3586        delete_migration_row(&db_path, "0008_trees_content");
3587
3588        SqliteRepository::open(&db_path).unwrap();
3589
3590        assert!(migration_succeeded(&db_path, "0008_trees_content"));
3591    }
3592
3593    #[test]
3594    fn test_blob_roundtrip() {
3595        let repo = SqliteRepository::in_memory().unwrap();
3596        let blob = Blob::from_str("hello world");
3597
3598        repo.store_blob(&blob).unwrap();
3599        let retrieved = repo.get_blob(&blob.hash).unwrap().unwrap();
3600
3601        assert_eq!(retrieved.hash, blob.hash);
3602        assert_eq!(retrieved.content, blob.content);
3603    }
3604
3605    #[test]
3606    fn test_tree_put_walk_roundtrip() {
3607        let repo = SqliteRepository::in_memory().unwrap();
3608        // Store the blobs first (FK enforcement at sqlite level requires they exist).
3609        for content in ["a", "b", "c"] {
3610            repo.store_blob(&Blob::from_str(content)).unwrap();
3611        }
3612
3613        let entries = vec![
3614            ManifestEntry {
3615                path: "src/lib.rs".to_string(),
3616                blob_hash: Blob::from_str("a").hash,
3617                mode: FileMode::Regular,
3618            },
3619            ManifestEntry {
3620                path: "src/bin/main.rs".to_string(),
3621                blob_hash: Blob::from_str("b").hash,
3622                mode: FileMode::Regular,
3623            },
3624            ManifestEntry {
3625                path: "README.md".to_string(),
3626                blob_hash: Blob::from_str("c").hash,
3627                mode: FileMode::Regular,
3628            },
3629        ];
3630
3631        let root = repo.put_tree(entries.clone()).unwrap();
3632        assert!(repo.has_tree(&root).unwrap());
3633
3634        let walked = repo.walk_tree(&root).unwrap();
3635        assert_eq!(walked.len(), 3);
3636
3637        let manifest = Manifest::new(entries);
3638        let walked_manifest = Manifest::new(walked);
3639        assert_eq!(manifest.hash, walked_manifest.hash);
3640    }
3641
3642    #[test]
3643    fn put_tree_commit_stores_new_trees_and_advances_refs() {
3644        let repo = SqliteRepository::in_memory().unwrap();
3645        let entry = |path: &str, content: &str| ManifestEntry {
3646            path: path.to_string(),
3647            blob_hash: crate::hash_string(content),
3648            mode: FileMode::Regular,
3649        };
3650        let base = crate::build_tree(&[entry("src/a.rs", "a"), entry("docs/x.md", "x")]).unwrap();
3651        for tree in &base.trees {
3652            repo.store_tree(tree).unwrap();
3653        }
3654        // An edit that reuses the stored `docs/` subtree by hash.
3655        let mut fetch = |h: &Hash| {
3656            repo.get_tree(h)?
3657                .ok_or_else(|| OakError::ManifestNotFound(h.to_string()))
3658        };
3659        let edited =
3660            crate::edit_tree(&base.root_hash, &[entry("src/a.rs", "a2")], &[], &mut fetch).unwrap();
3661        assert_eq!(edited.trees.len(), 2, "new root and src/ only");
3662
3663        let commit = repo
3664            .put_tree_commit_and_advance_refs(
3665                "feature".to_string(),
3666                None,
3667                None,
3668                edited.root_hash.clone(),
3669                &edited.trees,
3670                "tester".to_string(),
3671                None,
3672                chrono::Utc::now(),
3673                vec![],
3674            )
3675            .unwrap();
3676        assert_eq!(
3677            repo.get_branch_head("feature").unwrap(),
3678            Some(commit.clone())
3679        );
3680        assert_eq!(repo.get_head().unwrap(), Some(commit.clone()));
3681        assert_eq!(
3682            repo.get_commit(&commit).unwrap().unwrap().manifest_hash,
3683            edited.root_hash
3684        );
3685        let manifest = repo.get_manifest(&edited.root_hash).unwrap().unwrap();
3686        assert_eq!(
3687            manifest.hash,
3688            Manifest::new(vec![entry("src/a.rs", "a2"), entry("docs/x.md", "x")]).hash
3689        );
3690
3691        // A root that is neither passed nor stored is refused, and no ref moves.
3692        let dangling = crate::build_tree(&[entry("lost.txt", "lost")]).unwrap();
3693        let err = repo
3694            .put_tree_commit_and_advance_refs(
3695                "feature".to_string(),
3696                Some(commit.clone()),
3697                None,
3698                dangling.root_hash,
3699                &[],
3700                "tester".to_string(),
3701                None,
3702                chrono::Utc::now(),
3703                vec![],
3704            )
3705            .unwrap_err();
3706        assert!(matches!(err, OakError::ManifestNotFound(_)), "got {err:?}");
3707        assert_eq!(repo.get_branch_head("feature").unwrap(), Some(commit));
3708    }
3709
3710    #[test]
3711    fn store_tree_rejects_mismatched_storage_hash() {
3712        let repo = SqliteRepository::in_memory().unwrap();
3713        let tree = Tree::new(vec![TreeEntry {
3714            name: "a.txt".to_string(),
3715            kind: TreeEntryKind::Blob,
3716            hash: Hash::from_hex(&"a".repeat(64)).unwrap(),
3717            mode: FileMode::Regular,
3718        }])
3719        .unwrap();
3720        let mut tampered = tree.clone();
3721        tampered.hash = Hash::from_hex(&"b".repeat(64)).unwrap();
3722
3723        let err = repo.store_tree(&tampered).unwrap_err();
3724        assert!(
3725            matches!(err, OakError::InvalidHash(_)),
3726            "expected invalid hash error, got {err:?}"
3727        );
3728        assert!(!repo.has_tree(&tampered.hash).unwrap());
3729        assert!(repo.get_tree(&tampered.hash).unwrap().is_none());
3730    }
3731
3732    #[test]
3733    fn get_tree_rejects_compressed_row_under_mismatched_hash() {
3734        let repo = SqliteRepository::in_memory().unwrap();
3735        let tree = Tree::new(vec![TreeEntry {
3736            name: "a.txt".to_string(),
3737            kind: TreeEntryKind::Blob,
3738            hash: Hash::from_hex(&"a".repeat(64)).unwrap(),
3739            mode: FileMode::Regular,
3740        }])
3741        .unwrap();
3742        let claimed = Hash::from_hex(&"c".repeat(64)).unwrap();
3743        let content = zstd_compress(&tree.canonical_bytes()).unwrap();
3744        {
3745            let conn = repo.conn.lock().unwrap();
3746            conn.execute(
3747                "INSERT INTO trees (hash, content) VALUES (?1, ?2)",
3748                rusqlite::params![claimed.as_str(), content],
3749            )
3750            .unwrap();
3751        }
3752
3753        let err = repo.get_tree(&claimed).unwrap_err();
3754        assert!(
3755            matches!(err, OakError::InvalidHash(_)),
3756            "expected invalid hash error, got {err:?}"
3757        );
3758    }
3759
3760    #[test]
3761    fn legacy_tree_entries_fallback() {
3762        // A tree written in the pre-0008 format (trees.content NULL + per-entry
3763        // tree_entries rows) must still read back correctly via get_tree's
3764        // fallback, identically to the new compressed-content format.
3765        let repo = SqliteRepository::in_memory().unwrap();
3766        let entries = vec![
3767            TreeEntry {
3768                name: "a.txt".to_string(),
3769                kind: TreeEntryKind::Blob,
3770                hash: Hash::from_hex(&"a".repeat(64)).unwrap(),
3771                mode: FileMode::Executable,
3772            },
3773            TreeEntry {
3774                name: "sub".to_string(),
3775                kind: TreeEntryKind::Tree,
3776                hash: Hash::from_hex(&"b".repeat(64)).unwrap(),
3777                mode: FileMode::Regular,
3778            },
3779        ];
3780        let tree = Tree::new(entries).unwrap();
3781        {
3782            let conn = repo.conn.lock().unwrap();
3783            conn.execute(
3784                "INSERT INTO trees (hash) VALUES (?1)",
3785                rusqlite::params![tree.hash.as_str()],
3786            )
3787            .unwrap();
3788            for e in &tree.entries {
3789                let mode_str = match (e.kind, e.mode) {
3790                    (TreeEntryKind::Tree, _) => "tree",
3791                    (TreeEntryKind::Blob, FileMode::Regular) => "regular",
3792                    (TreeEntryKind::Blob, FileMode::Executable) => "executable",
3793                    (TreeEntryKind::Blob, FileMode::Symlink) => "symlink",
3794                };
3795                conn.execute(
3796                    "INSERT INTO tree_entries (tree_hash, name, kind, hash, mode) VALUES (?1, ?2, ?3, ?4, ?5)",
3797                    rusqlite::params![tree.hash.as_str(), e.name, e.kind.as_str(), e.hash.as_str(), mode_str],
3798                )
3799                .unwrap();
3800            }
3801        }
3802        let got = repo.get_tree(&tree.hash).unwrap().unwrap();
3803        assert_eq!(got.hash, tree.hash);
3804        assert_eq!(got.canonical_bytes(), tree.canonical_bytes());
3805    }
3806
3807    #[test]
3808    fn compact_storage_backfills_drops_and_recompresses() {
3809        let repo = SqliteRepository::in_memory().unwrap();
3810
3811        // A new-format tree via the normal write path (gets trees.content).
3812        repo.store_blob(&Blob::from_str("x")).unwrap();
3813        let new_root = repo
3814            .put_tree(vec![ManifestEntry {
3815                path: "dir/x.txt".to_string(),
3816                blob_hash: Blob::from_str("x").hash,
3817                mode: FileMode::Regular,
3818            }])
3819            .unwrap();
3820
3821        // A legacy tree: content NULL + tree_entries rows.
3822        let legacy = Tree::new(vec![TreeEntry {
3823            name: "old.txt".to_string(),
3824            kind: TreeEntryKind::Blob,
3825            hash: Hash::from_hex(&"c".repeat(64)).unwrap(),
3826            mode: FileMode::Regular,
3827        }])
3828        .unwrap();
3829        // A legacy raw blob: codec 0, compressible.
3830        let legacy_blob = Blob::from_str(&"zzzz ".repeat(80));
3831        {
3832            let conn = repo.conn.lock().unwrap();
3833            conn.execute(
3834                "INSERT INTO trees (hash) VALUES (?1)",
3835                rusqlite::params![legacy.hash.as_str()],
3836            )
3837            .unwrap();
3838            for e in &legacy.entries {
3839                conn.execute(
3840                    "INSERT INTO tree_entries (tree_hash, name, kind, hash, mode) VALUES (?1, ?2, ?3, ?4, 'regular')",
3841                    rusqlite::params![legacy.hash.as_str(), e.name, e.kind.as_str(), e.hash.as_str()],
3842                )
3843                .unwrap();
3844            }
3845            conn.execute(
3846                "INSERT INTO blobs (hash, content, size, codec) VALUES (?1, ?2, ?3, 0)",
3847                rusqlite::params![
3848                    legacy_blob.hash.as_str(),
3849                    legacy_blob.content,
3850                    legacy_blob.size as i64
3851                ],
3852            )
3853            .unwrap();
3854        }
3855
3856        let stats = repo.compact_storage().unwrap();
3857        assert_eq!(stats.trees_backfilled, 1);
3858        assert!(stats.tree_entries_dropped);
3859        assert!(stats.blobs_recompressed >= 1);
3860
3861        // tree_entries table is gone.
3862        {
3863            let conn = repo.conn.lock().unwrap();
3864            assert!(!table_exists(&conn, "tree_entries").unwrap());
3865        }
3866
3867        // Both trees and both blobs still read correctly.
3868        assert!(repo.get_tree(&new_root).unwrap().is_some());
3869        let got_legacy = repo.get_tree(&legacy.hash).unwrap().unwrap();
3870        assert_eq!(got_legacy.canonical_bytes(), legacy.canonical_bytes());
3871        assert_eq!(
3872            repo.get_blob(&legacy_blob.hash).unwrap().unwrap().content,
3873            legacy_blob.content
3874        );
3875
3876        // Idempotent: a second run is a no-op (plus a VACUUM).
3877        let stats2 = repo.compact_storage().unwrap();
3878        assert_eq!(stats2.trees_backfilled, 0);
3879        assert_eq!(stats2.blobs_recompressed, 0);
3880    }
3881
3882    #[test]
3883    fn legacy_raw_blob_fallback() {
3884        // A pre-0007 blob row (raw content, codec 0) must read back as plaintext
3885        // even though new writes would have zstd-compressed it.
3886        let repo = SqliteRepository::in_memory().unwrap();
3887        let blob = Blob::from_str(&"hello world ".repeat(50)); // very compressible
3888        {
3889            let conn = repo.conn.lock().unwrap();
3890            conn.execute(
3891                "INSERT INTO blobs (hash, content, size, codec) VALUES (?1, ?2, ?3, 0)",
3892                rusqlite::params![blob.hash.as_str(), blob.content, blob.size as i64],
3893            )
3894            .unwrap();
3895        }
3896        let got = repo.get_blob(&blob.hash).unwrap().unwrap();
3897        assert_eq!(got.content, blob.content);
3898    }
3899
3900    #[test]
3901    fn new_blob_compresses_and_roundtrips() {
3902        // A compressible blob stored through the normal path is zstd-encoded
3903        // (codec 1) yet returns identical plaintext.
3904        let repo = SqliteRepository::in_memory().unwrap();
3905        let blob = Blob::from_str(&"abcabcabc ".repeat(100));
3906        repo.store_blob(&blob).unwrap();
3907        let codec: i64 = {
3908            let conn = repo.conn.lock().unwrap();
3909            conn.query_row(
3910                "SELECT codec FROM blobs WHERE hash = ?1",
3911                rusqlite::params![blob.hash.as_str()],
3912                |r| r.get(0),
3913            )
3914            .unwrap()
3915        };
3916        assert_eq!(codec, 1, "compressible blob should store as zstd");
3917        let got = repo.get_blob(&blob.hash).unwrap().unwrap();
3918        assert_eq!(got.content, blob.content);
3919    }
3920
3921    #[test]
3922    fn test_tree_subtree_dedup() {
3923        let repo = SqliteRepository::in_memory().unwrap();
3924        for content in ["x", "y"] {
3925            repo.store_blob(&Blob::from_str(content)).unwrap();
3926        }
3927
3928        // Two roots that share the "shared/" subtree exactly.
3929        let entries_a = vec![
3930            ManifestEntry {
3931                path: "shared/x.txt".to_string(),
3932                blob_hash: Blob::from_str("x").hash,
3933                mode: FileMode::Regular,
3934            },
3935            ManifestEntry {
3936                path: "shared/y.txt".to_string(),
3937                blob_hash: Blob::from_str("y").hash,
3938                mode: FileMode::Regular,
3939            },
3940        ];
3941        let entries_b = vec![
3942            ManifestEntry {
3943                path: "shared/x.txt".to_string(),
3944                blob_hash: Blob::from_str("x").hash,
3945                mode: FileMode::Regular,
3946            },
3947            ManifestEntry {
3948                path: "shared/y.txt".to_string(),
3949                blob_hash: Blob::from_str("y").hash,
3950                mode: FileMode::Regular,
3951            },
3952            ManifestEntry {
3953                path: "extra.txt".to_string(),
3954                blob_hash: Blob::from_str("x").hash,
3955                mode: FileMode::Regular,
3956            },
3957        ];
3958
3959        let root_a = repo.put_tree(entries_a).unwrap();
3960        let root_b = repo.put_tree(entries_b).unwrap();
3961        assert_ne!(root_a, root_b);
3962
3963        // The "shared" subtree should be the same object for both roots.
3964        let shared_a = repo.subtree_at_path(&root_a, "shared").unwrap().unwrap();
3965        let shared_b = repo.subtree_at_path(&root_b, "shared").unwrap().unwrap();
3966        assert_eq!(shared_a, shared_b);
3967    }
3968
3969    #[test]
3970    fn test_tree_resolve_path() {
3971        let repo = SqliteRepository::in_memory().unwrap();
3972        repo.store_blob(&Blob::from_str("file")).unwrap();
3973        let entries = vec![ManifestEntry {
3974            path: "a/b/c.txt".to_string(),
3975            blob_hash: Blob::from_str("file").hash,
3976            mode: FileMode::Regular,
3977        }];
3978        let root = repo.put_tree(entries).unwrap();
3979
3980        let blob = repo.resolve_path_in_tree(&root, "a/b/c.txt").unwrap();
3981        assert!(blob.is_some());
3982        assert_eq!(blob.unwrap().kind, TreeEntryKind::Blob);
3983
3984        let dir = repo.resolve_path_in_tree(&root, "a/b").unwrap();
3985        assert_eq!(dir.unwrap().kind, TreeEntryKind::Tree);
3986
3987        let missing = repo.resolve_path_in_tree(&root, "a/zzz.txt").unwrap();
3988        assert!(missing.is_none());
3989    }
3990
3991    #[test]
3992    fn test_tree_put_idempotent() {
3993        let repo = SqliteRepository::in_memory().unwrap();
3994        repo.store_blob(&Blob::from_str("c")).unwrap();
3995        let entries = vec![ManifestEntry {
3996            path: "x.txt".to_string(),
3997            blob_hash: Blob::from_str("c").hash,
3998            mode: FileMode::Regular,
3999        }];
4000        let r1 = repo.put_tree(entries.clone()).unwrap();
4001        let r2 = repo.put_tree(entries).unwrap();
4002        assert_eq!(r1, r2);
4003    }
4004
4005    #[test]
4006    fn test_put_commit_and_advance_refs_stores_commit_and_moves_heads() {
4007        let repo = SqliteRepository::in_memory().unwrap();
4008        let blob = Blob::from_str("content");
4009        repo.store_blob(&blob).unwrap();
4010        let entries = vec![ManifestEntry {
4011            path: "file.txt".to_string(),
4012            blob_hash: blob.hash.clone(),
4013            mode: FileMode::Regular,
4014        }];
4015        let files = vec![FileChange {
4016            path: "file.txt".to_string(),
4017            change_type: ChangeType::Added,
4018            old_blob_hash: None,
4019            new_blob_hash: Some(blob.hash),
4020            old_path: None,
4021            old_mode: None,
4022            new_mode: None,
4023        }];
4024        let timestamp = chrono::DateTime::from_timestamp(1_700_000_000, 0).unwrap();
4025
4026        let commit_hash = repo
4027            .put_commit_and_advance_refs(
4028                "main".to_string(),
4029                None,
4030                None,
4031                entries,
4032                "tester <t@example.com>".to_string(),
4033                None,
4034                timestamp,
4035                files,
4036            )
4037            .unwrap();
4038
4039        assert_eq!(
4040            repo.get_branch_head("main").unwrap(),
4041            Some(commit_hash.clone())
4042        );
4043        assert_eq!(repo.get_head().unwrap(), Some(commit_hash.clone()));
4044        let commit = repo.get_commit(&commit_hash).unwrap().unwrap();
4045        assert_eq!(commit.timestamp, timestamp);
4046        assert_eq!(commit.files.len(), 1);
4047        let manifest = repo.get_manifest(&commit.manifest_hash).unwrap().unwrap();
4048        assert_eq!(manifest.entries.len(), 1);
4049        assert_eq!(manifest.entries[0].path, "file.txt");
4050    }
4051
4052    #[test]
4053    fn test_manifest_roundtrip() {
4054        let repo = SqliteRepository::in_memory().unwrap();
4055
4056        let blob = Blob::from_str("content");
4057        repo.store_blob(&blob).unwrap();
4058
4059        let manifest = Manifest::new(vec![ManifestEntry {
4060            path: "test.txt".to_string(),
4061            blob_hash: blob.hash.clone(),
4062            mode: FileMode::Regular,
4063        }]);
4064
4065        repo.store_manifest(&manifest).unwrap();
4066        let retrieved = repo.get_manifest(&manifest.hash).unwrap().unwrap();
4067
4068        assert_eq!(retrieved.hash, manifest.hash);
4069        assert_eq!(retrieved.entries.len(), 1);
4070        assert_eq!(retrieved.entries[0].path, "test.txt");
4071    }
4072
4073    #[test]
4074    fn test_branch_roundtrip() {
4075        let repo = SqliteRepository::in_memory().unwrap();
4076
4077        let br = Branch::new("feature-x".to_string(), Some("A feature".to_string()), None);
4078        repo.store_branch(&br).unwrap();
4079
4080        let retrieved = repo.get_branch("feature-x").unwrap().unwrap();
4081        assert_eq!(retrieved.name, "feature-x");
4082        assert_eq!(retrieved.description, Some("A feature".to_string()));
4083        assert_eq!(retrieved.status, BranchStatus::Open);
4084    }
4085
4086    #[test]
4087    fn test_commit_roundtrip() {
4088        let repo = SqliteRepository::in_memory().unwrap();
4089
4090        let blob = Blob::from_str("content");
4091        repo.store_blob(&blob).unwrap();
4092
4093        let manifest = Manifest::new(vec![ManifestEntry {
4094            path: "test.txt".to_string(),
4095            blob_hash: blob.hash.clone(),
4096            mode: FileMode::Regular,
4097        }]);
4098        repo.store_manifest(&manifest).unwrap();
4099
4100        let br = Branch::new("main".to_string(), None, None);
4101        repo.store_branch(&br).unwrap();
4102
4103        let commit = Commit::new(
4104            "main".to_string(),
4105            None,
4106            None,
4107            manifest.hash.clone(),
4108            "Test Author".to_string(),
4109            Some("Initial commit".to_string()),
4110            vec![FileChange {
4111                path: "test.txt".to_string(),
4112                change_type: ChangeType::Added,
4113                old_blob_hash: None,
4114                new_blob_hash: Some(blob.hash.clone()),
4115                old_path: None,
4116                old_mode: None,
4117                new_mode: None,
4118            }],
4119        )
4120        .unwrap();
4121
4122        repo.store_commit(&commit).unwrap();
4123        let retrieved = repo.get_commit(&commit.hash).unwrap().unwrap();
4124
4125        assert_eq!(retrieved.hash, commit.hash);
4126        assert_eq!(retrieved.branch_name, "main");
4127        assert_eq!(retrieved.message, Some("Initial commit".to_string()));
4128        assert_eq!(retrieved.files.len(), 1);
4129    }
4130
4131    #[test]
4132    fn store_commit_is_idempotent_for_file_changes() {
4133        let repo = SqliteRepository::in_memory().unwrap();
4134
4135        let blob = Blob::from_str("content");
4136        repo.store_blob(&blob).unwrap();
4137        let manifest = Manifest::new(vec![ManifestEntry {
4138            path: "test.txt".to_string(),
4139            blob_hash: blob.hash.clone(),
4140            mode: FileMode::Regular,
4141        }]);
4142        repo.store_manifest(&manifest).unwrap();
4143
4144        let commit = Commit::new(
4145            "main".to_string(),
4146            None,
4147            None,
4148            manifest.hash.clone(),
4149            "Test Author".to_string(),
4150            Some("Initial commit".to_string()),
4151            vec![FileChange {
4152                path: "test.txt".to_string(),
4153                change_type: ChangeType::Added,
4154                old_blob_hash: None,
4155                new_blob_hash: Some(blob.hash.clone()),
4156                old_path: None,
4157                old_mode: None,
4158                new_mode: None,
4159            }],
4160        )
4161        .unwrap();
4162
4163        repo.store_commit(&commit).unwrap();
4164        repo.store_commit(&commit).unwrap();
4165
4166        let conn = repo.conn.lock().unwrap();
4167        let count: i64 = conn
4168            .query_row(
4169                "SELECT COUNT(*) FROM commit_files WHERE commit_hash = ?1",
4170                rusqlite::params![commit.hash.as_str()],
4171                |row| row.get(0),
4172            )
4173            .unwrap();
4174        assert_eq!(count, 1);
4175    }
4176
4177    /// The server's squash commit, and the row older `oak merge` binaries
4178    /// stored for it: the server's hash over a placeholder author and the
4179    /// client's clock (zach/nas-monitoring 0b40b5ee).
4180    fn squash_commit_and_placeholder_row() -> (Commit, Commit) {
4181        let server = Commit::with_timestamp(
4182            "main".to_string(),
4183            None,
4184            Some(Hash("e5".repeat(32))),
4185            Tree::empty_hash(),
4186            "zach".to_string(),
4187            Some("Land the feature".to_string()),
4188            Vec::new(),
4189            chrono::DateTime::parse_from_rfc3339("2026-10-22T02:14:31.185316+00:00")
4190                .unwrap()
4191                .with_timezone(&chrono::Utc),
4192        )
4193        .unwrap();
4194        let placeholder = Commit {
4195            author: "<remote>".to_string(),
4196            timestamp: server.timestamp + chrono::Duration::microseconds(153_983),
4197            ..server.clone()
4198        };
4199        (server, placeholder)
4200    }
4201
4202    #[test]
4203    fn repair_commit_fields_rewrites_a_placeholder_row_to_the_verified_preimage() {
4204        let repo = SqliteRepository::in_memory().unwrap();
4205        let (server, placeholder) = squash_commit_and_placeholder_row();
4206        repo.store_commit(&placeholder).unwrap();
4207        // `store_commit` keeps the first row, so storing the verified commit
4208        // alone can't fix it.
4209        repo.store_commit(&server).unwrap();
4210        let err = repo
4211            .get_commit(&server.hash)
4212            .unwrap()
4213            .unwrap()
4214            .verify_fields()
4215            .unwrap_err();
4216        assert!(err.to_string().contains("author=\"<remote>\""), "{err}");
4217
4218        assert!(repo.repair_commit_fields(&server).unwrap());
4219        let repaired = repo.get_commit(&server.hash).unwrap().unwrap();
4220        repaired.verify_fields().unwrap();
4221        assert_eq!(repaired.author, "zach");
4222        assert_eq!(repaired.timestamp, server.timestamp);
4223
4224        // A row that already verifies is left alone.
4225        assert!(!repo.repair_commit_fields(&server).unwrap());
4226    }
4227
4228    #[test]
4229    fn repair_commit_fields_refuses_unverified_input_and_edge_changes() {
4230        let repo = SqliteRepository::in_memory().unwrap();
4231        let (server, placeholder) = squash_commit_and_placeholder_row();
4232        repo.store_commit(&placeholder).unwrap();
4233
4234        // The "repair" must itself reproduce the hash.
4235        assert!(repo.repair_commit_fields(&placeholder).is_err());
4236
4237        // A verified commit with the same hash but different graph edges
4238        // cannot exist without a BLAKE3 collision, so fake one by
4239        // rewriting the stored row's parent instead.
4240        repo.conn
4241            .lock()
4242            .unwrap()
4243            .execute(
4244                "UPDATE commits SET merge_parent_hash = ?2 WHERE hash = ?1",
4245                rusqlite::params![server.hash.as_str(), "ab".repeat(32)],
4246            )
4247            .unwrap();
4248        let err = repo.repair_commit_fields(&server).unwrap_err();
4249        assert!(err.to_string().contains("refusing to repair"), "{err}");
4250        assert_eq!(
4251            repo.get_commit(&server.hash).unwrap().unwrap().author,
4252            "<remote>"
4253        );
4254
4255        // Nothing stored under the hash: nothing to repair.
4256        let empty = SqliteRepository::in_memory().unwrap();
4257        assert!(!empty.repair_commit_fields(&server).unwrap());
4258    }
4259
4260    #[test]
4261    fn test_branch_head() {
4262        let repo = SqliteRepository::in_memory().unwrap();
4263
4264        let br = Branch::new("main".to_string(), None, None);
4265        repo.store_branch(&br).unwrap();
4266
4267        assert!(repo.get_branch_head("main").unwrap().is_none());
4268
4269        let blob = Blob::new(b"test".to_vec());
4270        repo.store_blob(&blob).unwrap();
4271        let manifest = Manifest::new(vec![ManifestEntry {
4272            path: "test.txt".to_string(),
4273            blob_hash: blob.hash.clone(),
4274            mode: FileMode::Regular,
4275        }]);
4276        repo.store_manifest(&manifest).unwrap();
4277
4278        let commit = Commit::new(
4279            "main".to_string(),
4280            None,
4281            None,
4282            manifest.hash.clone(),
4283            "test".to_string(),
4284            Some("test commit".to_string()),
4285            vec![],
4286        )
4287        .unwrap();
4288        repo.store_commit(&commit).unwrap();
4289
4290        repo.set_branch_head("main", &commit.hash).unwrap();
4291
4292        let retrieved = repo.get_branch_head("main").unwrap().unwrap();
4293        assert_eq!(retrieved, commit.hash);
4294    }
4295
4296    #[test]
4297    fn test_list_branches() {
4298        let repo = SqliteRepository::in_memory().unwrap();
4299
4300        let br1 = Branch::new("main".to_string(), None, None);
4301        let br2 = Branch::new(
4302            "feature".to_string(),
4303            Some("feature branch".to_string()),
4304            Some("main".to_string()),
4305        );
4306        repo.store_branch(&br1).unwrap();
4307        repo.store_branch(&br2).unwrap();
4308
4309        let all = repo.list_branches().unwrap();
4310        assert_eq!(all.len(), 2);
4311    }
4312
4313    #[test]
4314    fn legacy_sqlite_default_created_at_decodes_losslessly() {
4315        // fb-118: rows written through the column default `datetime('now')`
4316        // (space-separated UTC, no offset) used to abort every listing with
4317        // "premature end of input".
4318        let repo = SqliteRepository::in_memory().unwrap();
4319        repo.store_branch(&Branch::new("main".into(), None, None))
4320            .unwrap();
4321        repo.store_branch(&Branch::new("legacy".into(), None, Some("main".into())))
4322            .unwrap();
4323        repo.conn
4324            .lock()
4325            .unwrap()
4326            .execute(
4327                "UPDATE branches SET created_at = '2026-03-04 05:06:07' WHERE name = 'legacy'",
4328                [],
4329            )
4330            .unwrap();
4331
4332        let legacy = repo.get_branch("legacy").unwrap().unwrap();
4333        assert_eq!(legacy.created_at.to_rfc3339(), "2026-03-04T05:06:07+00:00");
4334        assert_eq!(repo.list_branches().unwrap().len(), 2);
4335    }
4336
4337    #[test]
4338    fn corrupt_created_at_is_isolated_to_its_row() {
4339        let repo = SqliteRepository::in_memory().unwrap();
4340        repo.store_branch(&Branch::new("main".into(), None, None))
4341            .unwrap();
4342        repo.store_branch(&Branch::new("broken".into(), None, Some("main".into())))
4343            .unwrap();
4344        repo.store_branch(&Branch::new("healthy".into(), None, Some("main".into())))
4345            .unwrap();
4346        repo.conn
4347            .lock()
4348            .unwrap()
4349            .execute(
4350                "UPDATE branches SET created_at = 'not-a-time' WHERE name = 'broken'",
4351                [],
4352            )
4353            .unwrap();
4354
4355        let rows = repo.list_branches_isolated().unwrap();
4356        assert_eq!(rows.len(), 3);
4357        let unreadable: Vec<_> = rows.iter().filter_map(|row| row.as_ref().err()).collect();
4358        assert_eq!(unreadable.len(), 1);
4359        assert_eq!(unreadable[0].name, "broken");
4360        assert_eq!(unreadable[0].column, "created_at");
4361        assert_eq!(unreadable[0].status, BranchStatus::Open);
4362        assert_eq!(unreadable[0].code(), crate::BRANCH_METADATA_UNREADABLE);
4363
4364        // Point reads of other rows are unaffected; the bad row's own read
4365        // fails with a typed error naming the branch, not a parser dump.
4366        assert!(repo.get_branch("healthy").unwrap().is_some());
4367        let error = repo.get_branch("broken").unwrap_err().to_string();
4368        assert!(error.contains("branch_metadata_unreadable"), "{error}");
4369        assert!(error.contains("'broken'") && error.contains("created_at"));
4370        assert!(!error.contains("not-a-time") && !error.contains("premature"));
4371    }
4372
4373    #[test]
4374    fn parse_stored_timestamp_accepts_rfc3339_and_sqlite_forms_only() {
4375        use crate::parse_stored_timestamp as parse;
4376        assert!(parse("2026-03-04T05:06:07.123456+00:00").is_some());
4377        assert!(parse("2026-03-04T05:06:07Z").is_some());
4378        assert_eq!(
4379            parse("2026-03-04 05:06:07.250").unwrap().to_rfc3339(),
4380            "2026-03-04T05:06:07.250+00:00"
4381        );
4382        assert!(parse("2026-03-04").is_none());
4383        assert!(parse("").is_none());
4384        assert!(parse("yesterday").is_none());
4385    }
4386
4387    #[test]
4388    fn test_commits_for_branch() {
4389        let repo = SqliteRepository::in_memory().unwrap();
4390
4391        let br = Branch::new("main".to_string(), None, None);
4392        repo.store_branch(&br).unwrap();
4393
4394        let manifest = Manifest::empty();
4395        repo.store_manifest(&manifest).unwrap();
4396
4397        let commit1 = Commit::new(
4398            "main".to_string(),
4399            None,
4400            None,
4401            manifest.hash.clone(),
4402            "author".to_string(),
4403            Some("commit 1".to_string()),
4404            vec![],
4405        )
4406        .unwrap();
4407        repo.store_commit(&commit1).unwrap();
4408
4409        let commit2 = Commit::new(
4410            "main".to_string(),
4411            Some(commit1.hash.clone()),
4412            None,
4413            manifest.hash.clone(),
4414            "author".to_string(),
4415            Some("commit 2".to_string()),
4416            vec![],
4417        )
4418        .unwrap();
4419        repo.store_commit(&commit2).unwrap();
4420
4421        let commits = repo.get_commits_for_branch("main").unwrap();
4422        assert_eq!(commits.len(), 2);
4423    }
4424
4425    #[test]
4426    fn test_count_commits_for_branch() {
4427        let repo = SqliteRepository::in_memory().unwrap();
4428
4429        let manifest = Manifest::empty();
4430        repo.store_manifest(&manifest).unwrap();
4431
4432        // A branch with no commits of its own (freshly seeded onto a parent)
4433        // counts zero — the unmerged-work baseline.
4434        assert_eq!(repo.count_commits_for_branch("feature").unwrap(), 0);
4435
4436        // One commit on `main`, two authored on `feature`. The count is keyed
4437        // strictly off the `branch_name` column, so `feature` reports 2
4438        // regardless of `main`'s history — exactly the "commits not yet merged
4439        // into the parent" signal.
4440        let base = Commit::new(
4441            "main".to_string(),
4442            None,
4443            None,
4444            manifest.hash.clone(),
4445            "author".to_string(),
4446            None,
4447            vec![],
4448        )
4449        .unwrap();
4450        repo.store_commit(&base).unwrap();
4451
4452        let feat1 = Commit::new(
4453            "feature".to_string(),
4454            Some(base.hash.clone()),
4455            None,
4456            manifest.hash.clone(),
4457            "author".to_string(),
4458            None,
4459            vec![],
4460        )
4461        .unwrap();
4462        repo.store_commit(&feat1).unwrap();
4463
4464        let feat2 = Commit::new(
4465            "feature".to_string(),
4466            Some(feat1.hash.clone()),
4467            None,
4468            manifest.hash.clone(),
4469            "author".to_string(),
4470            None,
4471            vec![],
4472        )
4473        .unwrap();
4474        repo.store_commit(&feat2).unwrap();
4475
4476        assert_eq!(repo.count_commits_for_branch("feature").unwrap(), 2);
4477        assert_eq!(repo.count_commits_for_branch("main").unwrap(), 1);
4478        // Matches the materializing path it optimizes.
4479        assert_eq!(
4480            repo.count_commits_for_branch("feature").unwrap(),
4481            repo.get_commits_for_branch("feature").unwrap().len()
4482        );
4483    }
4484
4485    #[test]
4486    fn test_merge_child_exists() {
4487        let repo = SqliteRepository::in_memory().unwrap();
4488
4489        let manifest = Manifest::empty();
4490        repo.store_manifest(&manifest).unwrap();
4491
4492        let feature = Commit::new(
4493            "feature".to_string(),
4494            None,
4495            None,
4496            manifest.hash.clone(),
4497            "author".to_string(),
4498            None,
4499            vec![],
4500        )
4501        .unwrap();
4502        repo.store_commit(&feature).unwrap();
4503
4504        assert!(!repo.merge_child_exists(&feature.hash).unwrap());
4505
4506        let main_merge = Commit::new(
4507            "main".to_string(),
4508            None,
4509            Some(feature.hash.clone()),
4510            manifest.hash.clone(),
4511            "author".to_string(),
4512            Some("merged feature".to_string()),
4513            vec![],
4514        )
4515        .unwrap();
4516        repo.store_commit(&main_merge).unwrap();
4517
4518        assert!(repo.merge_child_exists(&feature.hash).unwrap());
4519    }
4520
4521    #[test]
4522    fn test_metadata() {
4523        let repo = SqliteRepository::in_memory().unwrap();
4524
4525        assert!(repo.get_head().unwrap().is_none());
4526
4527        let hash = Hash("a".repeat(64));
4528        repo.set_head(&hash).unwrap();
4529
4530        let retrieved = repo.get_head().unwrap().unwrap();
4531        assert_eq!(retrieved, hash);
4532    }
4533
4534    #[test]
4535    fn test_current_branch() {
4536        let repo = SqliteRepository::in_memory().unwrap();
4537
4538        assert!(repo.get_current_branch_name().unwrap().is_none());
4539
4540        repo.set_current_branch("main").unwrap();
4541        let name = repo.get_current_branch_name().unwrap().unwrap();
4542        assert_eq!(name, "main");
4543    }
4544
4545    /// A repo created before the foreign key was dropped keeps its tags, with
4546    /// every column intact, and leaves enforcement as the connection set it.
4547    #[test]
4548    fn tag_foreign_key_migration_preserves_existing_tags() {
4549        let temp = tempfile::TempDir::new().unwrap();
4550        let path = temp.path().join("oak.db");
4551        drop(SqliteRepository::open(&path).unwrap());
4552
4553        // Put the database back to the schema before the migration.
4554        let conn = Connection::open(&path).unwrap();
4555        let commit = "cd".repeat(32);
4556        conn.execute_batch(&format!(
4557            "PRAGMA foreign_keys=OFF;
4558             DROP TABLE tags;
4559             CREATE TABLE tags (
4560                 name TEXT PRIMARY KEY,
4561                 commit_hash TEXT NOT NULL,
4562                 created_at TEXT NOT NULL DEFAULT (datetime('now')),
4563                 title TEXT,
4564                 notes TEXT,
4565                 is_prerelease INTEGER NOT NULL DEFAULT 0,
4566                 finalized INTEGER NOT NULL DEFAULT 0,
4567                 published_at TEXT,
4568                 created_by TEXT NOT NULL DEFAULT '',
4569                 revision INTEGER NOT NULL DEFAULT 0,
4570                 synced INTEGER NOT NULL DEFAULT 0,
4571                 FOREIGN KEY (commit_hash) REFERENCES commits(hash)
4572             );
4573             INSERT INTO tags VALUES ('v1.0', '{commit}', '2026-11-01T00:00:00+00:00',
4574                 'Title', 'Notes', 1, 1, '2026-11-02T00:00:00+00:00', 'bot', 7, 1);
4575             DELETE FROM schema_migrations WHERE version = '0018_drop_tags_commit_fk';"
4576        ))
4577        .unwrap();
4578        drop(conn);
4579
4580        let repo = SqliteRepository::open(&path).unwrap();
4581        let conn = repo.conn.lock().unwrap();
4582        let row: (String, String, String, i64, i64, String, i64, i64) = conn
4583            .query_row(
4584                "SELECT commit_hash, title, notes, is_prerelease, finalized, created_by, \
4585                        revision, synced FROM tags WHERE name = 'v1.0'",
4586                [],
4587                |r| {
4588                    Ok((
4589                        r.get(0)?,
4590                        r.get(1)?,
4591                        r.get(2)?,
4592                        r.get(3)?,
4593                        r.get(4)?,
4594                        r.get(5)?,
4595                        r.get(6)?,
4596                        r.get(7)?,
4597                    ))
4598                },
4599            )
4600            .unwrap();
4601        assert_eq!(
4602            row,
4603            (
4604                commit,
4605                "Title".into(),
4606                "Notes".into(),
4607                1,
4608                1,
4609                "bot".into(),
4610                7,
4611                1
4612            )
4613        );
4614
4615        let fks: i64 = conn
4616            .query_row(
4617                "SELECT COUNT(*) FROM pragma_foreign_key_list('tags')",
4618                [],
4619                |r| r.get(0),
4620            )
4621            .unwrap();
4622        assert_eq!(fks, 0);
4623        let enforced: i64 = conn
4624            .query_row("PRAGMA foreign_keys", [], |r| r.get(0))
4625            .unwrap();
4626        assert_eq!(enforced, 1, "the migration must not change enforcement");
4627    }
4628
4629    #[test]
4630    fn test_branch_description_update() {
4631        let repo = SqliteRepository::in_memory().unwrap();
4632
4633        let br = Branch::new("main".to_string(), Some("old desc".to_string()), None);
4634        repo.store_branch(&br).unwrap();
4635
4636        repo.update_branch_description("main", "new desc").unwrap();
4637
4638        let updated = repo.get_branch("main").unwrap().unwrap();
4639        assert_eq!(updated.description, Some("new desc".to_string()));
4640    }
4641
4642    #[test]
4643    fn legacy_description_requires_matching_baseline_before_remote_refresh() {
4644        let temp = tempfile::tempdir().unwrap();
4645        let path = temp.path().join("oak.db");
4646        {
4647            let repo = SqliteRepository::open(&path).unwrap();
4648            repo.store_branch(&Branch::new(
4649                "feature".into(),
4650                Some("legacy local".into()),
4651                None,
4652            ))
4653            .unwrap();
4654            // Fixture of the previous schema: no local/remote synchronization evidence.
4655            repo.conn
4656                .lock()
4657                .unwrap()
4658                .execute_batch(
4659                    "ALTER TABLE branches DROP COLUMN description_pending;
4660                 DELETE FROM schema_migrations WHERE version = '0012_pending_branch_description';",
4661                )
4662                .unwrap();
4663        }
4664        let repo = SqliteRepository::open(&path).unwrap();
4665        assert!(repo.branch_description_pending("feature").unwrap());
4666        let mut remote = Branch::new("feature".into(), Some("remote changed".into()), None);
4667        repo.upsert_branch_metadata_at_generation(&remote, repo.description_generation().unwrap())
4668            .unwrap();
4669        assert_eq!(
4670            repo.get_branch("feature")
4671                .unwrap()
4672                .unwrap()
4673                .description
4674                .as_deref(),
4675            Some("legacy local")
4676        );
4677        remote.description = Some("legacy local".into());
4678        repo.upsert_branch_metadata_at_generation(&remote, repo.description_generation().unwrap())
4679            .unwrap();
4680        assert!(!repo.branch_description_pending("feature").unwrap());
4681        remote.description = None;
4682        repo.upsert_branch_metadata_at_generation(&remote, repo.description_generation().unwrap())
4683            .unwrap();
4684        assert_eq!(
4685            repo.get_branch("feature").unwrap().unwrap().description,
4686            None
4687        );
4688    }
4689
4690    #[test]
4691    fn pending_description_survives_rename_and_stale_publish_ack() {
4692        let repo = SqliteRepository::in_memory().unwrap();
4693        repo.store_branch(&Branch::new("feature".into(), None, None))
4694            .unwrap();
4695        repo.edit_branch_description("feature", "pending").unwrap();
4696        repo.rename_branch("feature", "renamed").unwrap();
4697        assert!(repo.branch_description_pending("renamed").unwrap());
4698        repo.edit_branch_description("renamed", "newer").unwrap();
4699        repo.acknowledge_branch_description(
4700            "renamed",
4701            Some("pending"),
4702            repo.description_publication_generation().unwrap(),
4703        )
4704        .unwrap();
4705        assert!(repo.branch_description_pending("renamed").unwrap());
4706        repo.acknowledge_branch_description(
4707            "renamed",
4708            Some("newer"),
4709            repo.description_publication_generation().unwrap(),
4710        )
4711        .unwrap();
4712        assert!(!repo.branch_description_pending("renamed").unwrap());
4713    }
4714
4715    #[test]
4716    fn description_fetch_fence_covers_aba_new_rows_and_overlapping_refreshes() {
4717        let repo = SqliteRepository::in_memory().unwrap();
4718        let mut remote = Branch::new("feature".into(), Some("A".into()), None);
4719        repo.store_branch(&remote).unwrap();
4720        let before = repo.description_generation().unwrap();
4721        repo.edit_branch_description("feature", "B").unwrap();
4722        repo.edit_branch_description("feature", "A").unwrap();
4723        // Matching text from an older fetch cannot acknowledge an ABA edit.
4724        assert!(!repo
4725            .reconcile_pulled_branch_metadata(&remote, before)
4726            .unwrap());
4727        assert!(repo.branch_description_pending("feature").unwrap());
4728        repo.acknowledge_branch_description("feature", Some("A"), Some(before))
4729            .unwrap();
4730        assert!(
4731            repo.branch_description_pending("feature").unwrap(),
4732            "old successful POST cannot acknowledge an ABA edit"
4733        );
4734        repo.acknowledge_branch_description(
4735            "feature",
4736            Some("A"),
4737            repo.description_publication_generation().unwrap(),
4738        )
4739        .unwrap();
4740        remote.description = Some("stale remote".into());
4741        assert!(!repo
4742            .reconcile_pulled_branch_metadata(&remote, before)
4743            .unwrap());
4744        assert_eq!(
4745            repo.get_branch("feature")
4746                .unwrap()
4747                .unwrap()
4748                .description
4749                .as_deref(),
4750            Some("A")
4751        );
4752        let fresh = repo.description_generation().unwrap();
4753        assert!(repo
4754            .reconcile_pulled_branch_metadata(&remote, fresh)
4755            .unwrap());
4756        remote.description = Some("overlapping old response".into());
4757        assert!(!repo
4758            .upsert_branch_metadata_at_generation(&remote, fresh)
4759            .unwrap());
4760        assert_eq!(
4761            repo.get_branch("feature")
4762                .unwrap()
4763                .unwrap()
4764                .description
4765                .as_deref(),
4766            Some("stale remote")
4767        );
4768
4769        let before_creation = repo.description_generation().unwrap();
4770        let mut new_branch = Branch::new("new".into(), Some("locally created".into()), None);
4771        repo.store_branch(&new_branch).unwrap();
4772        new_branch.description = Some("older remote response".into());
4773        assert!(!repo
4774            .upsert_branch_metadata_at_generation(&new_branch, before_creation)
4775            .unwrap());
4776        assert_eq!(
4777            repo.get_branch("new")
4778                .unwrap()
4779                .unwrap()
4780                .description
4781                .as_deref(),
4782            Some("locally created")
4783        );
4784
4785        // A sibling edit does not unnecessarily block this branch's refresh.
4786        let before_sibling = repo.description_generation().unwrap();
4787        repo.edit_branch_description("new", "sibling update")
4788            .unwrap();
4789        assert!(repo
4790            .reconcile_pulled_branch_metadata(&remote, before_sibling)
4791            .unwrap());
4792    }
4793
4794    #[test]
4795    fn test_get_commits_since_edge_cases() {
4796        let repo = SqliteRepository::in_memory().unwrap();
4797
4798        let br = Branch::new("main".to_string(), None, None);
4799        repo.store_branch(&br).unwrap();
4800
4801        let manifest = Manifest::empty();
4802        repo.store_manifest(&manifest).unwrap();
4803
4804        // No commits - get_commits_since should return empty
4805        let commits = repo.get_commits_since("main", None).unwrap();
4806        assert!(commits.is_empty());
4807
4808        // With a non-existent since hash and no commits — returns empty (no commits on branch)
4809        let commits = repo
4810            .get_commits_since("main", Some(&Hash("nonexistent".to_string())))
4811            .unwrap();
4812        assert!(commits.is_empty());
4813    }
4814
4815    #[test]
4816    fn test_get_commits_since_cross_branch_hash_returns_all() {
4817        // When since_hash belongs to a different branch (not found in this
4818        // branch's commits), get_commits_since should return ALL commits
4819        // for this branch, since they are all new from the caller's view.
4820        let repo = SqliteRepository::in_memory().unwrap();
4821        let manifest = Manifest::empty();
4822        repo.store_manifest(&manifest).unwrap();
4823        repo.store_branch(&Branch::new("default".to_string(), None, None))
4824            .unwrap();
4825        repo.store_branch(&Branch::new(
4826            "update".to_string(),
4827            None,
4828            Some("default".to_string()),
4829        ))
4830        .unwrap();
4831
4832        // Commit on "default"
4833        let c_default = Commit::new(
4834            "default".to_string(),
4835            None,
4836            None,
4837            manifest.hash.clone(),
4838            "a".to_string(),
4839            Some("default commit".to_string()),
4840            vec![],
4841        )
4842        .unwrap();
4843        repo.store_commit(&c_default).unwrap();
4844
4845        // Commits on "update"
4846        let c_update1 = Commit::new(
4847            "update".to_string(),
4848            None,
4849            None,
4850            manifest.hash.clone(),
4851            "a".to_string(),
4852            Some("update commit 1".to_string()),
4853            vec![],
4854        )
4855        .unwrap();
4856        let c_update2 = Commit::new(
4857            "update".to_string(),
4858            Some(c_update1.hash.clone()),
4859            None,
4860            manifest.hash.clone(),
4861            "a".to_string(),
4862            Some("update commit 2".to_string()),
4863            vec![],
4864        )
4865        .unwrap();
4866        repo.store_commit(&c_update1).unwrap();
4867        repo.store_commit(&c_update2).unwrap();
4868
4869        // get_commits_since("update", default_branch_head) should return
4870        // ALL "update" commits since the hash doesn't belong to "update"
4871        let since = repo
4872            .get_commits_since("update", Some(&c_default.hash))
4873            .unwrap();
4874        assert_eq!(
4875            since.len(),
4876            2,
4877            "should return all update commits when since_hash is from another branch"
4878        );
4879        assert_eq!(since[0].message, Some("update commit 1".to_string()));
4880        assert_eq!(since[1].message, Some("update commit 2".to_string()));
4881    }
4882
4883    // ============================================================
4884    // Blob edge cases
4885    // ============================================================
4886
4887    #[test]
4888    fn test_has_blob() {
4889        let repo = SqliteRepository::in_memory().unwrap();
4890        let blob = Blob::from_str("test content");
4891
4892        assert!(!repo.has_blob(&blob.hash).unwrap());
4893        repo.store_blob(&blob).unwrap();
4894        assert!(repo.has_blob(&blob.hash).unwrap());
4895    }
4896
4897    #[test]
4898    fn test_get_nonexistent_blob() {
4899        let repo = SqliteRepository::in_memory().unwrap();
4900        let result = repo.get_blob(&Hash("nonexistent".to_string())).unwrap();
4901        assert!(result.is_none());
4902    }
4903
4904    #[test]
4905    fn test_store_blob_idempotent() {
4906        let repo = SqliteRepository::in_memory().unwrap();
4907        let blob = Blob::from_str("same content");
4908
4909        repo.store_blob(&blob).unwrap();
4910        repo.store_blob(&blob).unwrap(); // Should not error (INSERT OR IGNORE)
4911
4912        let retrieved = repo.get_blob(&blob.hash).unwrap().unwrap();
4913        assert_eq!(retrieved.content, blob.content);
4914    }
4915
4916    #[test]
4917    fn test_blob_empty_content() {
4918        let repo = SqliteRepository::in_memory().unwrap();
4919        let blob = Blob::new(Vec::new());
4920
4921        repo.store_blob(&blob).unwrap();
4922        let retrieved = repo.get_blob(&blob.hash).unwrap().unwrap();
4923        assert!(retrieved.content.is_empty());
4924        assert_eq!(retrieved.size, 0);
4925    }
4926
4927    #[test]
4928    fn test_put_blob_sources_matches_put_blob() {
4929        let repo = SqliteRepository::in_memory().unwrap();
4930        let contents: Vec<Vec<u8>> = vec![
4931            b"alpha".to_vec(),
4932            Vec::new(),
4933            b"alpha".to_vec(), // duplicate within one batch
4934            vec![0u8; 64 * 1024],
4935        ];
4936
4937        let hashes = repo
4938            .put_blob_sources(
4939                contents
4940                    .iter()
4941                    .cloned()
4942                    .map(BlobSource::from_content)
4943                    .collect(),
4944            )
4945            .unwrap();
4946        assert_eq!(hashes.len(), contents.len());
4947        for (content, hash) in contents.iter().zip(&hashes) {
4948            // Same canonical hash as the one-at-a-time path...
4949            assert_eq!(hash, &repo.put_blob(content.clone()).unwrap());
4950            // ...and the content round-trips.
4951            let retrieved = repo.get_blob(hash).unwrap().unwrap();
4952            assert_eq!(&retrieved.content, content);
4953        }
4954        assert_eq!(hashes[0], hashes[2]);
4955
4956        assert!(repo.put_blob_sources(Vec::new()).unwrap().is_empty());
4957
4958        // The deferred-source entry point yields the same canonical hashes,
4959        // in input order, with or without size hints.
4960        let sources: Vec<BlobSource> = contents
4961            .iter()
4962            .cloned()
4963            .enumerate()
4964            .map(|(i, c)| {
4965                let hint = if i % 2 == 0 {
4966                    Some(c.len() as u64)
4967                } else {
4968                    None
4969                };
4970                BlobSource::new(hint, move || Ok(c))
4971            })
4972            .collect();
4973        assert_eq!(repo.put_blob_sources(sources).unwrap(), hashes);
4974        assert!(repo.put_blob_sources(Vec::new()).unwrap().is_empty());
4975        // Single-source fast path (autocommit, no transaction) agrees too.
4976        let single = vec![BlobSource::new(None, || Ok(b"alpha".to_vec()))];
4977        assert_eq!(
4978            repo.put_blob_sources(single).unwrap(),
4979            vec![hashes[0].clone()]
4980        );
4981    }
4982
4983    #[test]
4984    fn test_blob_binary_content() {
4985        let repo = SqliteRepository::in_memory().unwrap();
4986        let binary_data: Vec<u8> = (0..=255).collect();
4987        let blob = Blob::new(binary_data.clone());
4988
4989        repo.store_blob(&blob).unwrap();
4990        let retrieved = repo.get_blob(&blob.hash).unwrap().unwrap();
4991        assert_eq!(retrieved.content, binary_data);
4992    }
4993
4994    // ============================================================
4995    // Manifest edge cases
4996    // ============================================================
4997
4998    #[test]
4999    fn test_get_nonexistent_manifest() {
5000        let repo = SqliteRepository::in_memory().unwrap();
5001        let result = repo.get_manifest(&Hash("nonexistent".to_string())).unwrap();
5002        assert!(result.is_none());
5003    }
5004
5005    #[test]
5006    fn test_manifest_with_multiple_entries() {
5007        let repo = SqliteRepository::in_memory().unwrap();
5008
5009        let blob1 = Blob::from_str("content1");
5010        let blob2 = Blob::from_str("content2");
5011        repo.store_blob(&blob1).unwrap();
5012        repo.store_blob(&blob2).unwrap();
5013
5014        let manifest = Manifest::new(vec![
5015            ManifestEntry {
5016                path: "src/main.rs".to_string(),
5017                blob_hash: blob1.hash.clone(),
5018                mode: FileMode::Regular,
5019            },
5020            ManifestEntry {
5021                path: "scripts/build.sh".to_string(),
5022                blob_hash: blob2.hash.clone(),
5023                mode: FileMode::Executable,
5024            },
5025        ]);
5026
5027        repo.store_manifest(&manifest).unwrap();
5028        let retrieved = repo.get_manifest(&manifest.hash).unwrap().unwrap();
5029
5030        assert_eq!(retrieved.entries.len(), 2);
5031        let paths: Vec<&str> = retrieved.entries.iter().map(|e| e.path.as_str()).collect();
5032        assert!(paths.contains(&"src/main.rs"));
5033        assert!(paths.contains(&"scripts/build.sh"));
5034
5035        // Check modes are preserved
5036        let exec_entry = retrieved
5037            .entries
5038            .iter()
5039            .find(|e| e.path == "scripts/build.sh")
5040            .unwrap();
5041        assert_eq!(exec_entry.mode, FileMode::Executable);
5042    }
5043
5044    #[test]
5045    fn test_store_manifest_idempotent() {
5046        let repo = SqliteRepository::in_memory().unwrap();
5047        let manifest = Manifest::empty();
5048
5049        repo.store_manifest(&manifest).unwrap();
5050        repo.store_manifest(&manifest).unwrap(); // Should not error
5051    }
5052
5053    // ============================================================
5054    // Branch edge cases
5055    // ============================================================
5056
5057    #[test]
5058    fn test_get_nonexistent_branch() {
5059        let repo = SqliteRepository::in_memory().unwrap();
5060        let result = repo.get_branch("nonexistent").unwrap();
5061        assert!(result.is_none());
5062    }
5063
5064    #[test]
5065    fn test_branch_status_update() {
5066        let repo = SqliteRepository::in_memory().unwrap();
5067        let br = Branch::new("feature".to_string(), None, None);
5068        repo.store_branch(&br).unwrap();
5069
5070        assert_eq!(
5071            repo.get_branch("feature").unwrap().unwrap().status,
5072            BranchStatus::Open
5073        );
5074
5075        repo.update_branch_status("feature", BranchStatus::Closed)
5076            .unwrap();
5077        assert_eq!(
5078            repo.get_branch("feature").unwrap().unwrap().status,
5079            BranchStatus::Closed
5080        );
5081
5082        repo.update_branch_status("feature", BranchStatus::Open)
5083            .unwrap();
5084        assert_eq!(
5085            repo.get_branch("feature").unwrap().unwrap().status,
5086            BranchStatus::Open
5087        );
5088    }
5089
5090    #[test]
5091    fn test_branch_with_parent() {
5092        let repo = SqliteRepository::in_memory().unwrap();
5093
5094        let main = Branch::new("main".to_string(), None, None);
5095        let feature = Branch::new(
5096            "feature".to_string(),
5097            Some("my feature".to_string()),
5098            Some("main".to_string()),
5099        );
5100        repo.store_branch(&main).unwrap();
5101        repo.store_branch(&feature).unwrap();
5102
5103        let retrieved = repo.get_branch("feature").unwrap().unwrap();
5104        assert_eq!(retrieved.parent_branch, Some("main".to_string()));
5105        assert_eq!(retrieved.description, Some("my feature".to_string()));
5106    }
5107
5108    #[test]
5109    fn test_get_branch_head_nonexistent() {
5110        let repo = SqliteRepository::in_memory().unwrap();
5111        let result = repo.get_branch_head("nonexistent").unwrap();
5112        assert!(result.is_none());
5113    }
5114
5115    #[test]
5116    fn test_rename_branch_rejects_orphan_target_head() {
5117        let repo = SqliteRepository::in_memory().unwrap();
5118        let manifest = Manifest::empty();
5119        repo.store_manifest(&manifest).unwrap();
5120
5121        repo.store_branch(&Branch::new("old".to_string(), None, None))
5122            .unwrap();
5123
5124        let old_commit = Commit::new(
5125            "old".to_string(),
5126            None,
5127            None,
5128            manifest.hash.clone(),
5129            "author".to_string(),
5130            Some("old".to_string()),
5131            vec![],
5132        )
5133        .unwrap();
5134        let target_commit = Commit::new(
5135            "target".to_string(),
5136            None,
5137            None,
5138            manifest.hash.clone(),
5139            "author".to_string(),
5140            Some("target".to_string()),
5141            vec![],
5142        )
5143        .unwrap();
5144        repo.store_commit(&old_commit).unwrap();
5145        repo.store_commit(&target_commit).unwrap();
5146        repo.set_branch_head("old", &old_commit.hash).unwrap();
5147        repo.set_branch_head("target", &target_commit.hash).unwrap();
5148
5149        let err = repo.rename_branch("old", "target").unwrap_err();
5150        assert!(
5151            matches!(err, OakError::BranchAlreadyExists(ref name) if name == "target"),
5152            "expected BranchAlreadyExists, got {err:?}"
5153        );
5154        assert_eq!(
5155            repo.get_branch_head("old").unwrap(),
5156            Some(old_commit.hash.clone())
5157        );
5158        assert_eq!(
5159            repo.get_branch_head("target").unwrap(),
5160            Some(target_commit.hash.clone())
5161        );
5162    }
5163
5164    // ============================================================
5165    // Commit edge cases
5166    // ============================================================
5167
5168    #[test]
5169    fn test_has_commit() {
5170        let repo = SqliteRepository::in_memory().unwrap();
5171        let manifest = Manifest::empty();
5172        repo.store_manifest(&manifest).unwrap();
5173        let br = Branch::new("main".to_string(), None, None);
5174        repo.store_branch(&br).unwrap();
5175
5176        let commit = Commit::new(
5177            "main".to_string(),
5178            None,
5179            None,
5180            manifest.hash.clone(),
5181            "author".to_string(),
5182            Some("test".to_string()),
5183            vec![],
5184        )
5185        .unwrap();
5186
5187        assert!(!repo.has_commit(&commit.hash).unwrap());
5188        repo.store_commit(&commit).unwrap();
5189        assert!(repo.has_commit(&commit.hash).unwrap());
5190    }
5191
5192    #[test]
5193    fn test_get_nonexistent_commit() {
5194        let repo = SqliteRepository::in_memory().unwrap();
5195        let result = repo.get_commit(&Hash("nonexistent".to_string())).unwrap();
5196        assert!(result.is_none());
5197    }
5198
5199    #[test]
5200    fn test_get_commits_since_with_valid_hash() {
5201        let repo = SqliteRepository::in_memory().unwrap();
5202        let manifest = Manifest::empty();
5203        repo.store_manifest(&manifest).unwrap();
5204        let br = Branch::new("main".to_string(), None, None);
5205        repo.store_branch(&br).unwrap();
5206
5207        let c1 = Commit::new(
5208            "main".to_string(),
5209            None,
5210            None,
5211            manifest.hash.clone(),
5212            "a".to_string(),
5213            Some("c1".to_string()),
5214            vec![],
5215        )
5216        .unwrap();
5217        let c2 = Commit::new(
5218            "main".to_string(),
5219            Some(c1.hash.clone()),
5220            None,
5221            manifest.hash.clone(),
5222            "a".to_string(),
5223            Some("c2".to_string()),
5224            vec![],
5225        )
5226        .unwrap();
5227        let c3 = Commit::new(
5228            "main".to_string(),
5229            Some(c2.hash.clone()),
5230            None,
5231            manifest.hash.clone(),
5232            "a".to_string(),
5233            Some("c3".to_string()),
5234            vec![],
5235        )
5236        .unwrap();
5237        repo.store_commit(&c1).unwrap();
5238        repo.store_commit(&c2).unwrap();
5239        repo.store_commit(&c3).unwrap();
5240
5241        // Get commits since c1 should return c2 and c3
5242        let since = repo.get_commits_since("main", Some(&c1.hash)).unwrap();
5243        assert_eq!(since.len(), 2);
5244        assert_eq!(since[0].message, Some("c2".to_string()));
5245        assert_eq!(since[1].message, Some("c3".to_string()));
5246
5247        // Get commits since c2 should return only c3
5248        let since = repo.get_commits_since("main", Some(&c2.hash)).unwrap();
5249        assert_eq!(since.len(), 1);
5250        assert_eq!(since[0].message, Some("c3".to_string()));
5251
5252        // Get commits since c3 should return empty
5253        let since = repo.get_commits_since("main", Some(&c3.hash)).unwrap();
5254        assert!(since.is_empty());
5255    }
5256
5257    #[test]
5258    fn test_get_all_commits() {
5259        let repo = SqliteRepository::in_memory().unwrap();
5260        let manifest = Manifest::empty();
5261        repo.store_manifest(&manifest).unwrap();
5262        repo.store_branch(&Branch::new("main".to_string(), None, None))
5263            .unwrap();
5264        repo.store_branch(&Branch::new(
5265            "feature".to_string(),
5266            None,
5267            Some("main".to_string()),
5268        ))
5269        .unwrap();
5270
5271        let c1 = Commit::new(
5272            "main".to_string(),
5273            None,
5274            None,
5275            manifest.hash.clone(),
5276            "a".to_string(),
5277            Some("main commit".to_string()),
5278            vec![],
5279        )
5280        .unwrap();
5281        let c2 = Commit::new(
5282            "feature".to_string(),
5283            None,
5284            None,
5285            manifest.hash.clone(),
5286            "a".to_string(),
5287            Some("feature commit".to_string()),
5288            vec![],
5289        )
5290        .unwrap();
5291        repo.store_commit(&c1).unwrap();
5292        repo.store_commit(&c2).unwrap();
5293
5294        let all = repo.get_all_commits().unwrap();
5295        assert_eq!(all.len(), 2);
5296    }
5297
5298    #[test]
5299    fn test_commit_with_file_changes() {
5300        let repo = SqliteRepository::in_memory().unwrap();
5301        let manifest = Manifest::empty();
5302        repo.store_manifest(&manifest).unwrap();
5303        let br = Branch::new("main".to_string(), None, None);
5304        repo.store_branch(&br).unwrap();
5305
5306        let blob_hash = Hash("abc123".repeat(11)[..64].to_string());
5307        let commit = Commit::new(
5308            "main".to_string(),
5309            None,
5310            None,
5311            manifest.hash.clone(),
5312            "author".to_string(),
5313            Some("with changes".to_string()),
5314            vec![
5315                FileChange {
5316                    path: "added.txt".to_string(),
5317                    change_type: ChangeType::Added,
5318                    old_blob_hash: None,
5319                    new_blob_hash: Some(blob_hash.clone()),
5320                    old_path: None,
5321                    old_mode: None,
5322                    new_mode: None,
5323                },
5324                FileChange {
5325                    path: "modified.txt".to_string(),
5326                    change_type: ChangeType::Modified,
5327                    old_blob_hash: Some(blob_hash.clone()),
5328                    new_blob_hash: Some(blob_hash.clone()),
5329                    old_path: None,
5330                    old_mode: None,
5331                    new_mode: None,
5332                },
5333                FileChange {
5334                    path: "deleted.txt".to_string(),
5335                    change_type: ChangeType::Deleted,
5336                    old_blob_hash: Some(blob_hash.clone()),
5337                    new_blob_hash: None,
5338                    old_path: None,
5339                    old_mode: None,
5340                    new_mode: None,
5341                },
5342            ],
5343        )
5344        .unwrap();
5345
5346        repo.store_commit(&commit).unwrap();
5347        let retrieved = repo.get_commit(&commit.hash).unwrap().unwrap();
5348
5349        assert_eq!(retrieved.files.len(), 3);
5350        assert!(retrieved
5351            .files
5352            .iter()
5353            .any(|f| f.path == "added.txt" && f.change_type == ChangeType::Added));
5354        assert!(retrieved
5355            .files
5356            .iter()
5357            .any(|f| f.path == "modified.txt" && f.change_type == ChangeType::Modified));
5358        assert!(retrieved
5359            .files
5360            .iter()
5361            .any(|f| f.path == "deleted.txt" && f.change_type == ChangeType::Deleted));
5362    }
5363
5364    // ============================================================
5365    // Chunk operations
5366    // ============================================================
5367
5368    #[test]
5369    fn test_chunk_roundtrip() {
5370        let repo = SqliteRepository::in_memory().unwrap();
5371        let data = b"chunk content here";
5372        let hash = hash_bytes(data);
5373
5374        assert!(!repo.has_chunk(&hash).unwrap());
5375        repo.store_chunk(&hash, data).unwrap();
5376        assert!(repo.has_chunk(&hash).unwrap());
5377
5378        let retrieved = repo.get_chunk(&hash).unwrap().unwrap();
5379        assert_eq!(retrieved, data);
5380    }
5381
5382    #[test]
5383    fn stored_blob_reader_streams_raw_and_compressed_rows() {
5384        use std::io::Read;
5385        let dir = tempfile::tempdir().unwrap();
5386        let repo = SqliteRepository::open(&dir.path().join("oak.db")).unwrap();
5387        let mut state = 0x9E37_79B9u32;
5388        let incompressible: Vec<u8> = (0..3 * 1024 * 1024 + 17)
5389            .map(|_| {
5390                state ^= state << 13;
5391                state ^= state >> 17;
5392                state ^= state << 5;
5393                (state & 0xFF) as u8
5394            })
5395            .collect();
5396        let compressible = b"oak stored blob reader\n".repeat(200_000);
5397        for content in [incompressible, compressible, Vec::new()] {
5398            let hash = repo.put_blob(content.clone()).unwrap();
5399            let (size, mut reader) = repo.stored_blob_reader(&hash).unwrap().unwrap();
5400            assert_eq!(size, content.len() as u64);
5401            let mut read = Vec::new();
5402            reader.read_to_end(&mut read).unwrap();
5403            assert!(read == content, "streamed bytes differ for {hash}");
5404            // Other repository calls interleave with an open reader.
5405            let (_, mut interleaved) = repo.stored_blob_reader(&hash).unwrap().unwrap();
5406            let mut first = [0u8; 7];
5407            let got = interleaved.read(&mut first).unwrap();
5408            assert_eq!(repo.get_blob_size(&hash).unwrap(), Some(size));
5409            assert_eq!(&first[..got], &content[..got]);
5410        }
5411        assert!(repo
5412            .stored_blob_reader(&crate::hash_bytes(b"absent"))
5413            .unwrap()
5414            .is_none());
5415    }
5416
5417    #[test]
5418    fn test_store_chunk_rejects_hash_mismatch() {
5419        let repo = SqliteRepository::in_memory().unwrap();
5420        let claimed = hash_bytes(b"expected");
5421
5422        let err = repo.store_chunk(&claimed, b"different").unwrap_err();
5423        assert!(
5424            matches!(err, OakError::InvalidHash(_)),
5425            "expected invalid hash error, got {err:?}"
5426        );
5427        assert!(!repo.has_chunk(&claimed).unwrap());
5428    }
5429
5430    #[test]
5431    fn test_get_nonexistent_chunk() {
5432        let repo = SqliteRepository::in_memory().unwrap();
5433        let result = repo.get_chunk(&Hash("nonexistent".to_string())).unwrap();
5434        assert!(result.is_none());
5435    }
5436
5437    #[test]
5438    fn test_blob_chunks_mapping() {
5439        let repo = SqliteRepository::in_memory().unwrap();
5440        let blob_hash = Hash("blobhash".repeat(8)[..64].to_string());
5441        let chunk1_data = b"chunk1data";
5442        let chunk2_data = b"chunk2data";
5443        let chunk1_hash = hash_bytes(chunk1_data);
5444        let chunk2_hash = hash_bytes(chunk2_data);
5445
5446        // Store the actual chunks first (FK constraint)
5447        repo.store_chunk(&chunk1_hash, chunk1_data).unwrap();
5448        repo.store_chunk(&chunk2_hash, chunk2_data).unwrap();
5449
5450        let chunks = vec![
5451            ChunkInfo {
5452                hash: chunk1_hash,
5453                offset: 0,
5454                length: 1024,
5455            },
5456            ChunkInfo {
5457                hash: chunk2_hash,
5458                offset: 1024,
5459                length: 512,
5460            },
5461        ];
5462
5463        // No mapping initially
5464        assert!(repo.get_blob_chunks(&blob_hash).unwrap().is_none());
5465
5466        repo.store_blob_chunks(&blob_hash, &chunks).unwrap();
5467
5468        let retrieved = repo.get_blob_chunks(&blob_hash).unwrap().unwrap();
5469        assert_eq!(retrieved.len(), 2);
5470        assert_eq!(retrieved[0].offset, 0);
5471        assert_eq!(retrieved[0].length, 1024);
5472        assert_eq!(retrieved[1].offset, 1024);
5473        assert_eq!(retrieved[1].length, 512);
5474    }
5475
5476    // ============================================================
5477    // Metadata edge cases
5478    // ============================================================
5479
5480    #[test]
5481    fn test_metadata_overwrite() {
5482        let repo = SqliteRepository::in_memory().unwrap();
5483
5484        repo.set_metadata(MetadataKey::RemoteUrl, "http://old.example.com")
5485            .unwrap();
5486        repo.set_metadata(MetadataKey::RemoteUrl, "http://new.example.com")
5487            .unwrap();
5488
5489        let val = repo.get_metadata(MetadataKey::RemoteUrl).unwrap().unwrap();
5490        assert_eq!(val, "http://new.example.com");
5491    }
5492
5493    #[test]
5494    fn test_metadata_nonexistent_key() {
5495        let repo = SqliteRepository::in_memory().unwrap();
5496        let result = repo.get_metadata(MetadataKey::ApiKey).unwrap();
5497        assert!(result.is_none());
5498    }
5499
5500    // ============================================================
5501    // BulkImporter
5502    // ============================================================
5503
5504    #[test]
5505    fn test_bulk_importer_roundtrip() {
5506        // Importer needs a file-backed connection — in-memory rejects.
5507        let tmp = tempfile::tempdir().unwrap();
5508        let db_path = tmp.path().join("oak.db");
5509        let repo = SqliteRepository::open(&db_path).unwrap();
5510        let branch = Branch::new("main".to_string(), None, None);
5511        repo.store_branch(&branch).unwrap();
5512
5513        let mut importer = repo.bulk_importer(2).unwrap();
5514        // Two commits, each with the same single-file manifest. Forces the
5515        // tree cache to short-circuit the second commit's subtree inserts.
5516        let blob_hash = importer.put_blob(b"hello".to_vec()).unwrap();
5517        let entries = vec![ManifestEntry {
5518            path: "a.txt".to_string(),
5519            blob_hash: blob_hash.clone(),
5520            mode: FileMode::Regular,
5521        }];
5522        let manifest_hash = importer.put_tree(entries.clone()).unwrap();
5523
5524        let ts = chrono::DateTime::from_timestamp(1_000_000, 0).unwrap();
5525        let c1 = Commit::with_timestamp(
5526            "main".to_string(),
5527            None,
5528            None,
5529            manifest_hash.clone(),
5530            "tester <t@example.com>".to_string(),
5531            None,
5532            vec![FileChange {
5533                path: "a.txt".to_string(),
5534                change_type: ChangeType::Added,
5535                old_blob_hash: None,
5536                new_blob_hash: Some(blob_hash.clone()),
5537                old_path: None,
5538                old_mode: None,
5539                new_mode: None,
5540            }],
5541            ts,
5542        )
5543        .unwrap();
5544        importer.store_commit(&c1).unwrap();
5545        importer.store_commit(&c1).unwrap();
5546        // Re-using the same entries on commit 2 exercises the in-memory
5547        // tree cache: build_tree returns the same subtree hashes, which the
5548        // importer should recognize without re-inserting.
5549        let manifest_hash2 = importer.put_tree(entries).unwrap();
5550        assert_eq!(manifest_hash, manifest_hash2);
5551        let c2 = Commit::with_timestamp(
5552            "main".to_string(),
5553            Some(c1.hash.clone()),
5554            None,
5555            manifest_hash2,
5556            "tester <t@example.com>".to_string(),
5557            None,
5558            Vec::new(),
5559            ts,
5560        )
5561        .unwrap();
5562        importer.store_commit(&c2).unwrap();
5563        importer.finish().unwrap();
5564
5565        // Both commits durable, blob readable through the normal repo.
5566        assert!(repo.has_commit(&c1.hash).unwrap());
5567        assert!(repo.has_commit(&c2.hash).unwrap());
5568        assert!(repo.has_blob(&blob_hash).unwrap());
5569        let manifest = repo.get_manifest(&manifest_hash).unwrap().unwrap();
5570        assert_eq!(manifest.entries.len(), 1);
5571        assert_eq!(manifest.entries[0].path, "a.txt");
5572        let commit_file_count: i64 = repo
5573            .conn
5574            .lock()
5575            .unwrap()
5576            .query_row(
5577                "SELECT COUNT(*) FROM commit_files WHERE commit_hash = ?1",
5578                rusqlite::params![c1.hash.as_str()],
5579                |row| row.get(0),
5580            )
5581            .unwrap();
5582        assert_eq!(commit_file_count, 1);
5583    }
5584
5585    #[test]
5586    fn test_bulk_importer_drop_rolls_back() {
5587        let tmp = tempfile::tempdir().unwrap();
5588        let db_path = tmp.path().join("oak.db");
5589        let repo = SqliteRepository::open(&db_path).unwrap();
5590
5591        let commit_hash = {
5592            let mut importer = repo.bulk_importer(100).unwrap();
5593            let blob_hash = importer.put_blob(b"ephemeral".to_vec()).unwrap();
5594            let entries = vec![ManifestEntry {
5595                path: "x.txt".to_string(),
5596                blob_hash,
5597                mode: FileMode::Regular,
5598            }];
5599            let manifest_hash = importer.put_tree(entries).unwrap();
5600            let c = Commit::with_timestamp(
5601                "main".to_string(),
5602                None,
5603                None,
5604                manifest_hash,
5605                "tester <t@example.com>".to_string(),
5606                None,
5607                Vec::new(),
5608                chrono::DateTime::from_timestamp(0, 0).unwrap(),
5609            )
5610            .unwrap();
5611            importer.store_commit(&c).unwrap();
5612            c.hash
5613            // importer dropped here without finish() → outer tx rolled back.
5614        };
5615
5616        // The unflushed commit must not be visible.
5617        assert!(!repo.has_commit(&commit_hash).unwrap());
5618    }
5619
5620    #[test]
5621    fn test_bulk_txn_commit_persists() {
5622        // Writes issued inside a bulk transaction are durable after commit —
5623        // this is the clone/pull ingest path (store_chunk et al. join the
5624        // open BEGIN rather than auto-committing per statement).
5625        let tmp = tempfile::tempdir().unwrap();
5626        let db_path = tmp.path().join("oak.db");
5627        let repo = SqliteRepository::open(&db_path).unwrap();
5628
5629        let a = hash_bytes(b"aaaa");
5630        let b = hash_bytes(b"bbbb");
5631        repo.bulk_begin().unwrap();
5632        repo.store_chunk(&a, b"aaaa").unwrap();
5633        repo.store_chunk(&b, b"bbbb").unwrap();
5634        repo.bulk_commit().unwrap();
5635
5636        assert!(repo.has_chunk(&a).unwrap());
5637        assert!(repo.has_chunk(&b).unwrap());
5638    }
5639
5640    #[test]
5641    fn test_bulk_txn_rollback_discards() {
5642        // bulk_rollback (the BulkTxn guard's drop path) must discard every
5643        // write made since bulk_begin, so a failed import leaves nothing
5644        // half-applied.
5645        let tmp = tempfile::tempdir().unwrap();
5646        let db_path = tmp.path().join("oak.db");
5647        let repo = SqliteRepository::open(&db_path).unwrap();
5648
5649        let a = hash_bytes(b"aaaa");
5650        repo.bulk_begin().unwrap();
5651        repo.store_chunk(&a, b"aaaa").unwrap();
5652        repo.bulk_rollback();
5653
5654        assert!(!repo.has_chunk(&a).unwrap());
5655        // Connection is usable again afterwards (rollback restored a clean
5656        // auto-commit state, not a dangling transaction).
5657        repo.store_chunk(&a, b"aaaa").unwrap();
5658        assert!(repo.has_chunk(&a).unwrap());
5659    }
5660
5661    #[test]
5662    fn test_bulk_txn_flush_checkpoints_then_rollback() {
5663        // bulk_flush commits the batch so far and opens the next one. A write
5664        // before the flush survives; a write after it (with no further
5665        // commit) is rolled back. This is what bounds WAL growth mid-import
5666        // without losing already-flushed objects.
5667        let tmp = tempfile::tempdir().unwrap();
5668        let db_path = tmp.path().join("oak.db");
5669        let repo = SqliteRepository::open(&db_path).unwrap();
5670
5671        let before = hash_bytes(b"keep");
5672        let after = hash_bytes(b"drop");
5673        repo.bulk_begin().unwrap();
5674        repo.store_chunk(&before, b"keep").unwrap();
5675        repo.bulk_flush().unwrap();
5676        repo.store_chunk(&after, b"drop").unwrap();
5677        repo.bulk_rollback();
5678
5679        assert!(repo.has_chunk(&before).unwrap());
5680        assert!(!repo.has_chunk(&after).unwrap());
5681    }
5682
5683    #[test]
5684    fn test_write_txn_commit_persists() {
5685        let repo = SqliteRepository::in_memory().unwrap();
5686
5687        repo.write_txn_begin().unwrap();
5688        repo.set_metadata(MetadataKey::RemoteUrl, "https://example.com")
5689            .unwrap();
5690        repo.write_txn_commit().unwrap();
5691
5692        assert_eq!(
5693            repo.get_metadata(MetadataKey::RemoteUrl)
5694                .unwrap()
5695                .as_deref(),
5696            Some("https://example.com")
5697        );
5698    }
5699
5700    #[test]
5701    fn test_write_txn_rollback_discards() {
5702        let repo = SqliteRepository::in_memory().unwrap();
5703
5704        repo.write_txn_begin().unwrap();
5705        repo.set_metadata(MetadataKey::RemoteUrl, "https://example.com")
5706            .unwrap();
5707        repo.write_txn_rollback();
5708
5709        assert_eq!(repo.get_metadata(MetadataKey::RemoteUrl).unwrap(), None);
5710        repo.set_metadata(MetadataKey::RemoteUrl, "https://example.com")
5711            .unwrap();
5712        assert_eq!(
5713            repo.get_metadata(MetadataKey::RemoteUrl)
5714                .unwrap()
5715                .as_deref(),
5716            Some("https://example.com")
5717        );
5718    }
5719}
5720
5721#[cfg(test)]
5722mod storage_diagnostic_tests {
5723    use super::*;
5724
5725    #[test]
5726    fn sqlite_full_becomes_typed_path_diagnostic() {
5727        let sqlite = rusqlite::Error::SqliteFailure(
5728            rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_FULL),
5729            None,
5730        );
5731        let error = sqlite_open_error(Path::new("repo/.oak/oak.db"), sqlite);
5732        assert!(matches!(error, OakError::DiskFull { path } if path == "repo/.oak/oak.db"));
5733    }
5734
5735    #[test]
5736    fn missing_database_parent_is_not_misreported_as_full() {
5737        let temp = tempfile::TempDir::new().unwrap();
5738        let path = temp.path().join("missing/oak.db");
5739        let error = SqliteRepository::open(&path).err().unwrap();
5740        assert!(matches!(error, OakError::Database(_)), "{error}");
5741        assert!(!path.exists());
5742    }
5743}