sprawling-storage 0.0.10

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// Copyright (c) 2026 2youg1 and the sprawling contributors

//! A tree kept for its node between runs: whether somebody holds it,
//! and how it is taken back into use.

use super::super::lease::{FileWork, WorktreeLease};
use super::super::name::WorktreeName;
use super::super::weight::measure;
use super::Worktrees;
use super::open_tree;
use crate::error::StorageError;

/// Why a tree is locked: a run holds it.
const LEASE_REASON: &str = "held by a sprawling run";

/// What [`Worktrees::claim`] finds under a name.
pub(super) enum Standing {
    Held,
    Kept(git2::Worktree),
    Absent,
}

impl Worktrees {
    /// Lifts every lease a previous writer of this city left behind.
    ///
    /// A city has one writer, and `_writer` is the proof that the caller
    /// is it: while it is held, no lock can belong to a run that is
    /// still alive, so every lock is one a dead process never gave
    /// back. A city with no repository has no trees to free.
    ///
    /// # Errors
    /// Propagates a repository that cannot list, read or unlock its
    /// trees.
    pub fn lift_abandoned_leases(
        city_root: &std::path::Path,
        _writer: &crate::JsonlLedger,
    ) -> Result<(), StorageError> {
        let refuse = |op: &'static str, err: git2::Error| StorageError::Worktree {
            op,
            detail: format!("{}: {err}", city_root.display()),
        };
        let repo = match git2::Repository::open(city_root) {
            Ok(repo) => repo,
            Err(err) if err.code() == git2::ErrorCode::NotFound => return Ok(()),
            Err(err) => return Err(refuse("open the city repository", err)),
        };
        let names = repo
            .worktrees()
            .map_err(|err| refuse("list worktrees", err))?;
        for name in names.iter().flatten().flatten() {
            let tree = repo
                .find_worktree(name)
                .map_err(|err| refuse("find a worktree", err))?;
            let lock = tree
                .is_locked()
                .map_err(|err| refuse("read a worktree lock", err))?;
            match lock {
                git2::WorktreeLockStatus::Locked(_) => tree
                    .unlock()
                    .map_err(|err| refuse("unlock a worktree", err))?,
                git2::WorktreeLockStatus::Unlocked => {}
            }
        }
        Ok(())
    }

    /// Where `name` stands: held under a lock, kept on disk for its
    /// node, or not there at all.
    ///
    /// A registration with no directory under it is what an interrupted
    /// placement or a person deleting the tree by hand leaves, and it is
    /// taken back here - the same reflex the index has about a cache it
    /// doubts - so that `E_WORKTREE_BUSY` keeps meaning that somebody is
    /// working.
    pub(super) fn standing(&self, name: &WorktreeName) -> Result<Standing, StorageError> {
        let tree = match self.repo.find_worktree(name.as_str()) {
            Ok(tree) => tree,
            Err(err) if err.code() == git2::ErrorCode::NotFound => return Ok(Standing::Absent),
            Err(err) => {
                return Err(StorageError::Worktree {
                    op: "find a worktree",
                    detail: format!("{}: {err}", name.as_str()),
                });
            }
        };
        if !tree.path().exists() {
            self.forget(name.as_str())?;
            return Ok(Standing::Absent);
        }
        let lock = tree.is_locked().map_err(|err| StorageError::Worktree {
            op: "read a worktree lock",
            detail: format!("{}: {err}", name.as_str()),
        })?;
        Ok(match lock {
            git2::WorktreeLockStatus::Locked(_) => Standing::Held,
            git2::WorktreeLockStatus::Unlocked => Standing::Kept(tree),
        })
    }

    /// Takes a kept tree back into use: the node's branch moved up to
    /// the trunk when the trunk already holds all of it, the index read
    /// back from that branch head, every tracked file under `scopes`
    /// forced to it and every untracked one there removed, then the
    /// lock. Git rewrites only the files that differ, and only inside
    /// the scope, so a node's second run costs what it left behind in
    /// its own scope, not the size of the city.
    ///
    /// The index is read back whole before the narrowed checkout, unless
    /// it already writes the branch head's tree, because that checkout
    /// moves only the entries it writes: an entry outside the scope that
    /// names anything but the branch head - the last run's commit after
    /// the branch followed the trunk, or a path a run staged and never
    /// offered - would be committed by the next scoped offer. The
    /// comparison comes first because reading back walks the whole tree,
    /// and a reclaim that finds the branch and the index where the last
    /// run left them is the common case.
    pub(super) fn reattach(
        &self,
        name: &WorktreeName,
        tree: &git2::Worktree,
        scopes: &[String],
    ) -> Result<WorktreeLease, StorageError> {
        self.follow_trunk(name)?;
        let work = restore(tree, name.as_str(), scopes)?;
        tree.lock(Some(LEASE_REASON))
            .map_err(|err| StorageError::Worktree {
                op: "lock a worktree",
                detail: format!("{}: {err}", name.as_str()),
            })?;
        let weight = measure(tree.path())?;
        Ok(WorktreeLease {
            name: name.clone(),
            path: tree.path().to_path_buf(),
            disk: weight.bytes,
            work: FileWork {
                walked: weight.walked,
                ..work
            },
        })
    }

    /// Moves `name`'s branch to the trunk when the trunk descends from
    /// it. A branch with work the trunk lacks stays where it is: that
    /// work is still waiting for its merge.
    fn follow_trunk(&self, name: &WorktreeName) -> Result<(), StorageError> {
        let refuse = |op: &'static str, err: git2::Error| StorageError::Worktree {
            op,
            detail: format!("{}: {err}", name.as_str()),
        };
        let mut branch = self
            .repo
            .find_branch(name.as_str(), git2::BranchType::Local)
            .map_err(|err| refuse("find a node branch", err))?;
        let tip = branch
            .get()
            .peel_to_commit()
            .map_err(|err| refuse("read a node branch", err))?
            .id();
        let trunk = self
            .repo
            .head()
            .and_then(|head| head.peel_to_commit())
            .map_err(|err| refuse("read the city trunk", err))?
            .id();
        let behind = tip != trunk
            && self
                .repo
                .graph_descendant_of(trunk, tip)
                .map_err(|err| refuse("judge a fast-forward", err))?;
        if behind {
            branch
                .get_mut()
                .set_target(trunk, "follow the trunk")
                .map_err(|err| refuse("move a node branch", err))?;
        }
        Ok(())
    }
}

/// Puts `tree` on `branch` and forces every tracked file under `scopes`
/// to its head, removing what is untracked there, and counts what that
/// wrote (`crates/storage/spec/Worktree.lean` §8-31). The index is read back from the head first
/// when it does not already write the head's tree, for the reason
/// [`Worktrees::reattach`] gives.
///
/// The worktree's HEAD is pointed at `branch` when it names anything
/// else: a stock taken over by a node still names the stock's branch
/// (`crates/storage/spec/Worktree/Trees/Stock.lean` §8-35), and a checkout of the wrong head would hand the
/// node another line of work.
///
/// # Errors
/// Propagates a tree whose repository, head, index or checkout git
/// refuses.
pub(super) fn restore(
    tree: &git2::Worktree,
    branch: &str,
    scopes: &[String],
) -> Result<FileWork, StorageError> {
    let refuse = |op: &'static str, err: git2::Error| StorageError::Worktree {
        op,
        detail: format!("{branch}: {err}"),
    };
    let repo = open_tree(tree).map_err(|err| refuse("open a kept worktree", err))?;
    let wanted = format!("refs/heads/{branch}");
    let pointed = repo
        .find_reference("HEAD")
        .map_err(|err| refuse("read a kept worktree's HEAD", err))?;
    if pointed.symbolic_target_bytes() != Some(wanted.as_bytes()) {
        repo.reference_symbolic("HEAD", &wanted, true, "point the tree at its node's branch")
            .map_err(|err| refuse("point a kept worktree at its branch", err))?;
    }
    let head = repo
        .head()
        .and_then(|head| head.peel_to_tree())
        .map_err(|err| refuse("read a kept worktree's branch", err))?;
    let mut index = repo
        .index()
        .map_err(|err| refuse("read a kept worktree's index", err))?;
    if !index_writes_tree(&mut index, head.id())
        .map_err(|err| refuse("compare a kept worktree's index", err))?
    {
        index
            .read_tree(&head)
            .and_then(|()| index.write())
            .map_err(|err| refuse("reset a kept worktree's index", err))?;
    }
    let mut work = FileWork::default();
    let mut checkout = git2::build::CheckoutBuilder::new();
    checkout
        .force()
        .remove_untracked(true)
        .notify_on(
            git2::CheckoutNotificationType::UPDATED | git2::CheckoutNotificationType::UNTRACKED,
        )
        .notify(|kind, _, _, target, workdir| {
            count_change(&mut work, kind, (target.is_some(), workdir.is_some()));
            true
        });
    for spec in crate::checkpoint::scan::pathspec::of(scopes) {
        checkout.path(spec);
    }
    repo.checkout_head(Some(&mut checkout))
        .map_err(|err| refuse("reset a kept worktree", err))?;
    drop(checkout);
    Ok(work)
}

/// Counts one change a reattaching checkout announced before making it
/// (`crates/storage/spec/Worktree.lean` §8-31). `present` says whether the branch head holds the
/// path and whether the disk does: a tracked file the head lacks is
/// removed, one the disk lacks is created, and any other is rewritten;
/// an untracked entry is removed.
fn count_change(work: &mut FileWork, kind: git2::CheckoutNotificationType, present: (bool, bool)) {
    let count = if kind.contains(git2::CheckoutNotificationType::UNTRACKED) {
        &mut work.removed
    } else {
        match present {
            (false, _) => &mut work.removed,
            (true, false) => &mut work.created,
            (true, true) => &mut work.rewritten,
        }
    };
    *count = count.saturating_add(1);
}

/// Writes the tree `index` holds into the object store and says whether
/// it is `tree`.
///
/// Where no entry changed since the index last wrote or read a tree, the
/// index's own tree cache answers without hashing anything; otherwise
/// only the subtrees whose entries changed are written. An index holding
/// a conflict writes no tree, and so is not `tree`.
fn index_writes_tree(index: &mut git2::Index, tree: git2::Oid) -> Result<bool, git2::Error> {
    match index.write_tree() {
        Ok(written) => Ok(written == tree),
        Err(err) if err.code() == git2::ErrorCode::Unmerged => Ok(false),
        Err(err) => Err(err),
    }
}

#[cfg(test)]
#[allow(
    clippy::unwrap_used,
    clippy::arithmetic_side_effects,
    reason = "test code"
)]
mod tests {
    use super::super::super::lease::FileWork;
    use super::super::Landing;
    use super::super::tests::{bulk_city, city, entries, name, owner};
    use crate::checkpoint::Checkpoint;
    use kernel::TimeMs;
    use std::path::Path;

    fn read(path: &Path) -> String {
        std::fs::read_to_string(path).unwrap()
    }

    /// `crates/storage/spec/Worktree.lean` §8-31: a placement writes the tree's files once and walks
    /// the city once; a reclaim writes what the last run changed in its
    /// scope and nothing else. Judged at two sizes, so a cost that grows
    /// with the tree where it should not is a failure here rather than a
    /// slower reading somewhere else.
    #[test]
    fn claiming_a_tree_costs_what_it_places_and_restores() {
        for files in [32, 64] {
            let dir = tempfile::tempdir().unwrap();
            let trees = bulk_city(dir.path(), files);
            let scope = ["bulk".to_owned()];
            let city = entries(dir.path());

            let placed = trees.claim(&name("node-1"), &scope).unwrap();
            let tree = placed.path().to_path_buf();
            assert_eq!(
                placed.work(),
                FileWork {
                    created: files,
                    rewritten: 0,
                    removed: 0,
                    walked: city,
                },
                "a placement at {files} files"
            );

            std::fs::write(tree.join("bulk").join("file-0000.txt"), b"changed by a run").unwrap();
            std::fs::write(tree.join("bulk").join("stray.txt"), b"left by a run").unwrap();
            trees.release(placed).unwrap();
            let restored = trees.claim(&name("node-1"), &scope).unwrap();
            assert_eq!(
                restored.work(),
                FileWork {
                    created: 0,
                    rewritten: 1,
                    removed: 1,
                    walked: entries(&tree),
                },
                "a reclaim after a run at {files} files"
            );

            trees.release(restored).unwrap();
            let unchanged = trees.claim(&name("node-1"), &scope).unwrap();
            assert_eq!(
                unchanged.work(),
                FileWork {
                    walked: entries(&tree),
                    ..FileWork::default()
                },
                "a reclaim with nothing to restore at {files} files"
            );
        }
    }

    /// A kept tree claimed again writes only its scope, and what the node
    /// offers from it moves only that scope: the trunk's work elsewhere,
    /// which this tree never checked out, lands in the city untouched.
    #[test]
    fn a_kept_tree_claimed_again_checks_out_only_its_scope_and_offers_only_that() {
        let dir = tempfile::tempdir().unwrap();
        let trees = city(dir.path());
        let city_docs = dir.path().join("docs").join("plan.md");
        let land_city = |t: u64| {
            Checkpoint::open(dir.path())
                .unwrap()
                .land(&[], TimeMs::new(t), &owner(), "checkpoint: city")
                .unwrap()
        };
        std::fs::create_dir_all(city_docs.parent().unwrap()).unwrap();
        std::fs::write(
            &city_docs, b"v1
",
        )
        .unwrap();
        land_city(1_500);
        let lab = ["lab".to_owned()];
        trees
            .release(trees.claim(&name("node-1"), &lab).unwrap())
            .unwrap();
        std::fs::write(
            &city_docs, b"v2
",
        )
        .unwrap();
        std::fs::write(
            dir.path().join("lab").join("notes.md"),
            b"second
",
        )
        .unwrap();
        let trunk = land_city(2_000);

        let again = trees.claim(&name("node-1"), &lab).unwrap();
        assert_eq!(
            (
                read(&again.path().join("lab").join("notes.md")),
                read(&again.path().join("docs").join("plan.md"))
            ),
            (
                "second
"
                .to_owned(),
                "v1
"
                .to_owned()
            ),
            "the scope follows the trunk and nothing outside it is written"
        );

        std::fs::write(
            again.path().join("lab").join("notes.md"),
            b"from the node
",
        )
        .unwrap();
        Checkpoint::open(again.path())
            .unwrap()
            .land(&lab, TimeMs::new(3_000), &owner(), "offer: lab")
            .unwrap();
        let of = owner();
        trees
            .plan_merge(again.name())
            .unwrap()
            .apply(&Landing {
                t: TimeMs::new(4_000),
                of: &of,
                subject: "merge: node-1",
                reviewed_by_person: false,
            })
            .unwrap();
        let repo = git2::Repository::open(dir.path()).unwrap();
        let before = repo
            .find_commit(git2::Oid::from_str(&trunk).unwrap())
            .unwrap()
            .tree()
            .unwrap();
        let after = repo.head().unwrap().peel_to_tree().unwrap();
        let moved: Vec<String> = repo
            .diff_tree_to_tree(Some(&before), Some(&after), None)
            .unwrap()
            .deltas()
            .filter_map(|delta| delta.new_file().path().map(|p| p.display().to_string()))
            .collect();
        assert_eq!(
            (moved, read(&city_docs)),
            (
                vec!["lab/notes.md".to_owned()],
                "v2
"
                .to_owned()
            ),
            "the merge moves the scope alone"
        );
    }

    /// A path a run staged outside its scope and never offered does not
    /// ride along with the node's next offer, although the trunk did not
    /// move in between: the next claim finds an index that no longer
    /// names the branch head, and reads it back.
    #[test]
    fn a_path_staged_outside_the_scope_does_not_ride_along_with_the_next_offer() {
        let dir = tempfile::tempdir().unwrap();
        let trees = city(dir.path());
        let lab = ["lab".to_owned()];
        let first = trees.claim(&name("node-1"), &lab).unwrap();
        let stray = first.path().join("docs").join("stray.md");
        std::fs::create_dir_all(stray.parent().unwrap()).unwrap();
        std::fs::write(&stray, b"not this node's").unwrap();
        let staging = git2::Repository::open(first.path()).unwrap();
        let mut index = staging.index().unwrap();
        index.add_path(Path::new("docs/stray.md")).unwrap();
        index.write().unwrap();
        trees.release(first).unwrap();

        let again = trees.claim(&name("node-1"), &lab).unwrap();
        std::fs::write(again.path().join("lab").join("notes.md"), b"from the node").unwrap();
        Checkpoint::open(again.path())
            .unwrap()
            .land(&lab, TimeMs::new(3_000), &owner(), "offer: lab")
            .unwrap();
        let offered = git2::Repository::open(again.path()).unwrap();
        let head = offered.head().unwrap().peel_to_commit().unwrap();
        let moved: Vec<String> = offered
            .diff_tree_to_tree(
                Some(&head.parent(0).unwrap().tree().unwrap()),
                Some(&head.tree().unwrap()),
                None,
            )
            .unwrap()
            .deltas()
            .filter_map(|delta| delta.new_file().path().map(|p| p.display().to_string()))
            .collect();
        assert_eq!(
            moved,
            vec!["lab/notes.md".to_owned()],
            "the offer moves the scope alone"
        );
    }

    /// A node's next run finds its tree where it left it: releasing gives
    /// the lease back and keeps the files, so the next claim neither
    /// measures the city nor checks the whole tree out again.
    #[test]
    fn a_released_tree_stays_on_disk_for_the_nodes_next_run() {
        let dir = tempfile::tempdir().unwrap();
        let trees = city(dir.path());
        let lease = trees.claim(&name("node-1"), &[]).unwrap();
        let path = lease.path().to_path_buf();
        let notes = path.join("lab").join("notes.md");
        let written = std::fs::metadata(&notes).unwrap().modified().unwrap();

        trees.release(lease).unwrap();
        assert!(notes.exists(), "a released tree keeps its files");
        assert_eq!(trees.live().unwrap(), vec![name("node-1")]);

        let again = trees.claim(&name("node-1"), &[]).unwrap();
        // The same directory, spelled two ways: git answers with the long
        // name, and a Windows runner's temp directory hands out its 8.3 one.
        assert_eq!(
            std::fs::canonicalize(again.path()).unwrap(),
            std::fs::canonicalize(&path).unwrap()
        );
        assert_eq!(
            std::fs::metadata(&notes).unwrap().modified().unwrap(),
            written,
            "a file the node's branch already holds is not written again"
        );
        assert!(dir.path().join("lab").join("notes.md").exists());
    }

    /// A kept tree whose node has nothing unmerged follows the trunk: a
    /// node that starts from where the city was when it last ran would do
    /// its next work on files somebody has since changed, and every merge
    /// of it would be refused as stale.
    #[test]
    fn a_kept_tree_with_nothing_unmerged_starts_from_the_trunk_as_it_now_stands() {
        let dir = tempfile::tempdir().unwrap();
        let trees = city(dir.path());
        trees
            .release(trees.claim(&name("node-1"), &[]).unwrap())
            .unwrap();
        std::fs::write(
            dir.path().join("lab").join("notes.md"),
            b"second
    ",
        )
        .unwrap();
        Checkpoint::open(dir.path())
            .unwrap()
            .land(&[], TimeMs::new(2_000), &owner(), "checkpoint: lab")
            .unwrap();

        let again = trees.claim(&name("node-1"), &[]).unwrap();
        assert_eq!(
            std::fs::read_to_string(again.path().join("lab").join("notes.md")).unwrap(),
            "second
    "
        );
    }
}