quilt-rs 0.44.0

//!
//! Module that contains various structs and helpers to work with `.quilt/lineage.json`.

use std::collections::BTreeMap;
use std::path::Path;
use std::path::PathBuf;

use serde::Deserialize;
use serde::Serialize;
use tracing::log;

#[cfg(test)]
use tempfile::TempDir;

use crate::Error;
use crate::InstallPackageError;
use crate::Res;
use crate::error::LineageError;
use crate::io::storage::Storage;
use crate::io::storage::StorageExt;
use crate::paths;
use quilt_uri::Namespace;

mod status;
pub use status::Change;
pub use status::ChangeSet;
pub use status::InstalledPackageStatus;
pub use status::UpstreamState;

mod state;
pub use state::PackageState;
pub use state::PackageStateReport;

mod package;
pub use package::CommitState;
pub use package::LineagePaths;
pub use package::PackageLineage;
pub use package::PathState;
pub use package::SyncScope;

mod home;
pub use home::DEFAULT_HOME_DIR_NAME;
pub use home::Home;

/// It's essentially just a map of `PackageLineage`.
/// Represents the contents of `.quilt/data.json`
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Default)]
pub struct DomainLineage {
    #[serde(default = "BTreeMap::new")]
    pub packages: BTreeMap<Namespace, PackageLineage>,
    #[serde(default)]
    pub home: Home,
}

impl DomainLineage {
    pub fn new(home_dir: impl AsRef<Path>) -> Self {
        DomainLineage {
            packages: BTreeMap::new(),
            home: Home::from(home_dir),
        }
    }

    /// Returns a sorted vector of all namespaces in the lineage
    #[must_use]
    pub fn namespaces(&self) -> Vec<Namespace> {
        let mut namespaces: Vec<Namespace> = self.packages.keys().cloned().collect();
        namespaces.sort();
        namespaces
    }

    #[cfg(test)]
    pub fn from_temp_dir() -> Res<(Self, tempfile::TempDir)> {
        let temp_dir = TempDir::new()?;
        Ok((DomainLineage::new(temp_dir.path()), temp_dir))
    }
}

impl AsRef<PathBuf> for DomainLineage {
    fn as_ref(&self) -> &PathBuf {
        self.home.as_ref()
    }
}

impl DomainLineage {
    pub fn from_slice(input: &[u8]) -> Res<Self> {
        let result: Result<Self, serde_json::Error> = serde_json::from_slice(input);

        match result {
            Ok(lineage) => {
                if lineage.as_ref().as_os_str().is_empty() {
                    return Err(Error::Lineage(LineageError::MissingHome));
                }
                Ok(lineage)
            }
            Err(err) => {
                log::error!("Failed to parse DomainLineage from `{input:?}`");
                Err(Error::Lineage(LineageError::Parse(err)))
            }
        }
    }
}

/// Wrapper for reading and writing `DomainLineage`
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct DomainLineageIo {
    path: PathBuf,
}

// TODO impl std::io::Write and std::io::Read for DomainLineageIo
impl DomainLineageIo {
    #[must_use]
    pub fn new(path: PathBuf) -> Self {
        DomainLineageIo { path }
    }

    pub async fn read(&self, storage: &(impl Storage + Sync)) -> Res<DomainLineage> {
        match storage.read_bytes(&self.path).await {
            Ok(bytes) => DomainLineage::from_slice(&bytes),
            Err(_) if !storage.exists(&self.path).await => {
                Err(Error::Lineage(LineageError::Missing))
            }
            Err(e) => Err(e),
        }
    }

    /// Read a specific package lineage from the domain lineage
    pub async fn read_package_lineage(
        &self,
        storage: &(impl Storage + Sync),
        namespace: &Namespace,
    ) -> Res<(PathBuf, PackageLineage)> {
        let domain_lineage = self.read(storage).await?;

        match domain_lineage.packages.get(namespace) {
            Some(package_lineage) => {
                let package_home = paths::package_home(&domain_lineage.home, namespace);
                Ok((package_home, package_lineage.clone()))
            }
            None => Err(Error::InstallPackage(InstallPackageError::NotInstalled(
                namespace.clone(),
            ))),
        }
    }

    /// `data.json.lock`, beside the file it guards. `data.json` itself is
    /// replaced by rename, and a lock on the old file would guard nothing.
    fn lock_path(&self) -> PathBuf {
        let mut path = self.path.clone().into_os_string();
        path.push(".lock");
        PathBuf::from(path)
    }

    /// **The short lock.** Under `data.json.lock`: re-read the whole record,
    /// let `step` change it, and write it back if it changed. An error from
    /// `step` writes nothing.
    ///
    /// Every write of `data.json` goes through here, so the short lock is held
    /// for a re-read, a splice and a write, never for a writer's slow work.
    /// The file holds every package's entry, so this is where writers of
    /// different packages meet. A writer of one package holds that package's
    /// lock (see [`InstalledPackage::lock`](crate::InstalledPackage::lock))
    /// from its first read, and takes this one only inside it.
    pub async fn update<T>(
        &self,
        storage: &(impl Storage + Sync),
        step: impl FnOnce(&mut DomainLineage) -> Res<T>,
    ) -> Res<T> {
        let _locked = storage.lock_exclusive(self.lock_path()).await?;
        let mut lineage = self.read(storage).await?;
        let before = lineage.clone();
        let out = step(&mut lineage)?;
        if lineage != before {
            self.write_unlocked(storage, &lineage).await?;
        }
        Ok(out)
    }

    /// [`Self::update`] for one package's entry: `step` sees `None` when the
    /// package is not installed, and setting it to `None` removes the entry.
    pub async fn update_package_lineage<T>(
        &self,
        storage: &(impl Storage + Sync),
        namespace: &Namespace,
        step: impl FnOnce(&mut Option<PackageLineage>) -> Res<T>,
    ) -> Res<T> {
        self.update(storage, |lineage| {
            let mut entry = lineage.packages.remove(namespace);
            let out = step(&mut entry);
            if let Some(entry) = entry {
                lineage.packages.insert(namespace.clone(), entry);
            }
            out
        })
        .await
    }

    /// Apply `edit` to one package's entry under the lock and write it: a
    /// field update that does not depend on other work. A package that is not
    /// installed is an error.
    pub async fn edit_package_lineage(
        &self,
        storage: &(impl Storage + Sync),
        namespace: &Namespace,
        edit: impl FnOnce(&mut PackageLineage),
    ) -> Res<PackageLineage> {
        self.update_package_lineage(storage, namespace, |entry| {
            let package = entry.as_mut().ok_or_else(|| {
                Error::InstallPackage(InstallPackageError::NotInstalled(namespace.clone()))
            })?;
            edit(package);
            Ok(package.clone())
        })
        .await
    }

    /// Point the domain at `home`, creating its folder.
    ///
    /// The folder is created before `data.json` is written, so a home that
    /// can't be created is never stored. When `home` is already the stored
    /// one, only a missing folder is created and `data.json` is not rewritten.
    /// Refuses with
    /// [`LineageError::HomeInUse`] and changes nothing when `home` differs and
    /// any package is installed, because their working folders live under the
    /// current home. [`DomainLineageIo::overwrite_home`] skips that check.
    pub async fn set_home(
        &self,
        storage: &(impl Storage + Sync),
        home: impl AsRef<Path>,
    ) -> Res<DomainLineage> {
        self.change_home(storage, home, false).await
    }

    /// [`DomainLineageIo::set_home`] without the installed-packages check.
    ///
    /// Installed packages keep their entries, so they then point at folders
    /// under the new home, where none of their files are.
    pub async fn overwrite_home(
        &self,
        storage: &(impl Storage + Sync),
        home: impl AsRef<Path>,
    ) -> Res<DomainLineage> {
        self.change_home(storage, home, true).await
    }

    /// Read, check and write `data.json` under the short lock, so a package
    /// writer's splice can't land between the check and the write.
    async fn change_home(
        &self,
        storage: &(impl Storage + Sync),
        home: impl AsRef<Path>,
        overwrite: bool,
    ) -> Res<DomainLineage> {
        let _locked = storage.lock_exclusive(self.lock_path()).await?;
        match storage.read_bytes(&self.path).await {
            Ok(bytes) => {
                let (mut lineage, home_missing) = match DomainLineage::from_slice(&bytes) {
                    Ok(lineage) => (lineage, false),
                    Err(Error::Lineage(LineageError::MissingHome)) => {
                        (serde_json::from_slice(&bytes)?, true)
                    }
                    Err(err) => return Err(err),
                };
                let home = Home::from(home);
                if lineage.home == home {
                    storage.create_dir_all(home.as_ref()).await?;
                    return Ok(lineage);
                }
                if !overwrite && !home_missing && !lineage.packages.is_empty() {
                    return Err(Error::Lineage(LineageError::HomeInUse {
                        home: lineage.home.as_ref().clone(),
                        installed: lineage.packages.len(),
                    }));
                }
                storage.create_dir_all(home.as_ref()).await?;
                lineage.home = home;
                self.write_unlocked(storage, &lineage).await?;
                Ok(lineage)
            }
            Err(_) if !storage.exists(&self.path).await => {
                storage.create_dir_all(home.as_ref()).await?;
                let lineage = DomainLineage::new(home);
                self.write_unlocked(storage, &lineage).await?;
                Ok(lineage)
            }
            Err(e) => Err(e),
        }
    }

    /// Replace the whole record, under the lock. For setting a domain up; a
    /// writer of one package goes through [`Self::update_package_lineage`], or
    /// it writes back every other package's entry as it read them.
    pub async fn write(
        &self,
        storage: &(impl Storage + Sync),
        lineage: DomainLineage,
    ) -> Res<DomainLineage> {
        let _locked = storage.lock_exclusive(self.lock_path()).await?;
        self.write_unlocked(storage, &lineage).await?;
        Ok(lineage)
    }

    async fn write_unlocked(
        &self,
        storage: &(impl Storage + Sync),
        lineage: &DomainLineage,
    ) -> Res {
        let contents = serde_json::to_string_pretty(lineage)?;
        storage
            .write_byte_stream(self.path.clone(), contents.into_bytes().into())
            .await
    }

    #[must_use]
    pub fn create_package_lineage(&self, namespace: Namespace) -> PackageLineageIo {
        PackageLineageIo::new(self.clone(), namespace)
    }
}

/// Wrapper for reading and writing `PackageLineage`
/// It re-uses `DomainLineageIo`
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PackageLineageIo {
    domain_lineage: DomainLineageIo,
    namespace: Namespace,
}

impl PackageLineageIo {
    /// See [`DomainLineageIo::edit_package_lineage`]: a field update under the
    /// lock, for callers that do not need to compute from the entry first.
    pub async fn edit(
        &self,
        storage: &(impl Storage + Sync),
        edit: impl FnOnce(&mut PackageLineage),
    ) -> Res<PackageLineage> {
        self.domain_lineage
            .edit_package_lineage(storage, &self.namespace, edit)
            .await
    }

    #[must_use]
    pub fn new(domain_lineage: DomainLineageIo, namespace: Namespace) -> Self {
        PackageLineageIo {
            domain_lineage,
            namespace,
        }
    }

    pub async fn read(&self, storage: &(impl Storage + Sync)) -> Res<(PathBuf, PackageLineage)> {
        self.domain_lineage
            .read_package_lineage(storage, &self.namespace)
            .await
    }

    /// The whole domain's record this package's entry lives in.
    pub(crate) async fn read_domain(&self, storage: &(impl Storage + Sync)) -> Res<DomainLineage> {
        self.domain_lineage.read(storage).await
    }

    pub async fn package_home(&self, storage: &(impl Storage + Sync)) -> Res<PathBuf> {
        Ok(self
            .domain_home(storage)
            .await?
            .join(self.namespace.to_string()))
    }

    pub async fn domain_home(&self, storage: &(impl Storage + Sync)) -> Res<Home> {
        let domain_lineage = self.domain_lineage.read(storage).await?;
        Ok(domain_lineage.home)
    }

    /// Splices `lineage` in as this package's entry, under the short lock,
    /// leaving every other package's entry as it is on disk now. The caller
    /// holds the package's lock, so the entry it replaces is the one it read.
    pub async fn write(
        &self,
        storage: &(impl Storage + Sync),
        lineage: PackageLineage,
    ) -> Res<PackageLineage> {
        self.domain_lineage
            .update_package_lineage(storage, &self.namespace, |entry| {
                *entry = Some(lineage.clone());
                Ok(lineage)
            })
            .await
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    use test_log::test;

    use aws_sdk_s3::primitives::ByteStream;
    use aws_smithy_types::base64;

    use crate::io::storage::mocks::MockStorage;
    use crate::object_hash::Sha256ChunkedHash;
    use quilt_uri::ManifestUri;

    #[test]
    fn test_syntax_error() {
        assert_eq!(
            DomainLineage::from_slice(b"err").unwrap_err().to_string(),
            "Failed to parse lineage file: expected value at line 1 column 1".to_string()
        );
    }

    #[test]
    fn test_wrong_key() {
        // NOTE: @fiskus I don't think this is developer friendly
        //       I'd like to remove serde(default), so this test fails
        assert!(DomainLineage::from_slice(br#"{"notkey": 123}"#).is_err());
    }

    #[test]
    fn test_wrong_value() {
        assert!(
            DomainLineage::from_slice(br#"{"packages": 123}"#)
                .unwrap_err()
                .to_string()
                .starts_with("Failed to parse lineage file: invalid type:")
        );
    }

    #[test]
    fn test_missing_working_directory() {
        assert_eq!(
            DomainLineage::from_slice(br#"{"packages":{}}"#)
                .unwrap_err()
                .to_string(),
            "Domain lineage missing Home directory".to_string()
        );
    }

    #[test]
    fn test_with_working_directory() -> Res {
        let lineage =
            DomainLineage::from_slice(br#"{"packages":{},"home":"/tmp/working_dir"}"#).unwrap();
        assert_eq!(lineage.as_ref(), &PathBuf::from("/tmp/working_dir"));
        Ok(())
    }

    #[test]
    fn test_domain_lineage_from_temp_dir() -> Res {
        let (lineage, temp_dir) = DomainLineage::from_temp_dir()?;
        assert_eq!(lineage.as_ref(), &temp_dir.path().to_path_buf());
        assert!(lineage.packages.is_empty());
        Ok(())
    }

    #[test]
    fn test_namespaces() -> Res {
        let mut lineage = DomainLineage::new("/tmp/home");

        // Empty lineage should return empty vector
        assert_eq!(lineage.namespaces(), [] as [Namespace; 0]);

        // Add some packages
        lineage
            .packages
            .insert(Namespace::from(("foo", "bar")), PackageLineage::default());
        lineage
            .packages
            .insert(Namespace::from(("abc", "xyz")), PackageLineage::default());
        lineage.packages.insert(
            Namespace::from(("test", "package")),
            PackageLineage::default(),
        );

        // Check that namespaces are returned in sorted order
        let namespaces = lineage.namespaces();
        assert_eq!(namespaces.len(), 3);
        assert_eq!(namespaces[0], Namespace::from(("abc", "xyz")));
        assert_eq!(namespaces[1], Namespace::from(("foo", "bar")));
        assert_eq!(namespaces[2], Namespace::from(("test", "package")));

        Ok(())
    }

    #[test]
    fn test_deserialize_package_lineage_without_remote() {
        let json = r#"{
            "commit": null,
            "base_hash": "",
            "latest_hash": "",
            "paths": {}
        }"#;
        let lineage: PackageLineage = serde_json::from_str(json).unwrap();
        assert_eq!(lineage.remote_uri, None);
    }

    #[test]
    fn test_serialize_package_lineage_without_remote() {
        let lineage = PackageLineage::default();
        let json = serde_json::to_string(&lineage).unwrap();
        // "remote" key should be omitted when remote_uri is None
        assert!(!json.contains("remote"));
    }

    /// A record written before the sync scope existed still parses, and reads
    /// as the sparse-checkout default — the whole reason adopting the field
    /// costs no migration.
    #[test]
    fn a_record_without_a_sync_scope_reads_as_individual_files() {
        let json = r#"{
            "commit": null,
            "base_hash": "",
            "latest_hash": "",
            "paths": {}
        }"#;
        let lineage: PackageLineage = serde_json::from_str(json).unwrap();
        assert_eq!(lineage.sync_scope, SyncScope::IndividualFiles);
        assert!(!lineage.sync_scope.covers_untracked());
    }

    /// And the other direction: an opted-in package round-trips.
    #[test]
    fn an_entire_package_scope_survives_a_round_trip() {
        let lineage = PackageLineage {
            sync_scope: SyncScope::EntirePackage,
            ..PackageLineage::default()
        };
        let json = serde_json::to_string(&lineage).unwrap();
        assert!(json.contains(r#""sync_scope":"entire_package""#), "{json}");

        let parsed: PackageLineage = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.sync_scope, SyncScope::EntirePackage);
        assert!(parsed.sync_scope.covers_untracked());
    }

    /// The default scope writes **no key**, so turning the feature on does not
    /// rewrite `sync_scope` into the record of every installed package — and
    /// dropping the field later erases it on the next write, since the record
    /// is re-serialized whole.
    #[test]
    fn the_default_scope_writes_no_key() {
        let json = serde_json::to_string(&PackageLineage::default()).unwrap();
        assert!(!json.contains("sync_scope"), "{json}");
    }

    #[test(tokio::test)]
    async fn test_domain_lineage_from_file() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(
                &file_path,
                ByteStream::from_static(br#"{"packages":{},"home":"/home/directory"}"#),
            )
            .await?;
        let lineage = DomainLineageIo::new(file_path).read(&storage).await?;
        assert_eq!(lineage, DomainLineage::new("/home/directory"));
        Ok(())
    }

    #[test(tokio::test)]
    async fn test_set_home_repairs_existing_lineage_with_missing_home() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(
                &file_path,
                ByteStream::from_static(br#"{"packages":{},"home":""}"#),
            )
            .await?;

        let lineage = DomainLineageIo::new(file_path)
            .set_home(&storage, "/home/directory")
            .await?;

        assert_eq!(lineage, DomainLineage::new("/home/directory"));
        Ok(())
    }

    /// The stored bytes are compact JSON and `write` pretty-prints, so any
    /// rewrite would change them.
    #[test(tokio::test)]
    async fn set_home_to_the_current_home_writes_nothing() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        let stored = br#"{"packages":{},"home":"/home/directory"}"#;
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(stored))
            .await?;

        let lineage = DomainLineageIo::new(file_path.clone())
            .set_home(&storage, "/home/directory")
            .await?;

        assert_eq!(lineage, DomainLineage::new("/home/directory"));
        assert_eq!(storage.read_bytes(&file_path).await?, stored.to_vec());
        assert!(
            storage.exists("/home/directory").await,
            "a missing folder is still created"
        );
        Ok(())
    }

    const ONE_INSTALLED: &[u8] =
        br#"{"packages":{"foo/bar":{"commit":null,"base_hash":"","latest_hash":"","paths":{}}},"home":"/old/home"}"#;

    #[test(tokio::test)]
    async fn set_home_refuses_a_new_home_while_packages_are_installed() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(ONE_INSTALLED))
            .await?;

        let err = DomainLineageIo::new(file_path.clone())
            .set_home(&storage, "/new/home")
            .await
            .unwrap_err();

        assert!(
            matches!(
                &err,
                Error::Lineage(LineageError::HomeInUse { home, installed: 1 })
                    if home == &PathBuf::from("/old/home")
            ),
            "{err:?}"
        );
        assert_eq!(
            err.to_string(),
            "Cannot change the home: 1 package is installed in /old/home"
        );
        assert_eq!(
            storage.read_bytes(&file_path).await?,
            ONE_INSTALLED.to_vec()
        );
        assert!(!storage.exists("/new/home").await, "no folder is created");
        Ok(())
    }

    #[test(tokio::test)]
    async fn set_home_to_the_current_home_is_allowed_while_packages_are_installed() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(ONE_INSTALLED))
            .await?;

        let lineage = DomainLineageIo::new(file_path)
            .set_home(&storage, "/old/home")
            .await?;

        assert_eq!(lineage.home, Home::from("/old/home"));
        Ok(())
    }

    #[test(tokio::test)]
    async fn overwrite_home_changes_the_home_while_packages_are_installed() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(ONE_INSTALLED))
            .await?;
        let io = DomainLineageIo::new(file_path);

        io.overwrite_home(&storage, "/new/home").await?;

        let lineage = io.read(&storage).await?;
        assert_eq!(lineage.home, Home::from("/new/home"));
        assert_eq!(lineage.namespaces(), vec![Namespace::from(("foo", "bar"))]);
        Ok(())
    }

    #[test(tokio::test)]
    async fn set_home_creates_the_home_folder() -> Res {
        let storage = MockStorage::default();

        DomainLineageIo::new(PathBuf::from("foo"))
            .set_home(&storage, "/new/home")
            .await?;

        assert!(storage.exists("/new/home").await);
        Ok(())
    }

    #[test(tokio::test)]
    async fn changing_the_home_creates_the_new_folder() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(ONE_INSTALLED))
            .await?;

        DomainLineageIo::new(file_path)
            .overwrite_home(&storage, "/new/home")
            .await?;

        assert!(storage.exists("/new/home").await);
        Ok(())
    }

    /// A file where the home's parent should be makes the folder impossible
    /// to create.
    #[test(tokio::test)]
    async fn a_home_that_cannot_be_created_is_not_stored() -> Res {
        let storage = MockStorage::default();
        storage
            .write_byte_stream("/blocked", ByteStream::from_static(b"a file"))
            .await?;
        let file_path = PathBuf::from("foo");
        storage
            .write_byte_stream(&file_path, ByteStream::from_static(ONE_INSTALLED))
            .await?;

        DomainLineageIo::new(file_path.clone())
            .overwrite_home(&storage, "/blocked/home")
            .await
            .unwrap_err();

        assert_eq!(
            storage.read_bytes(&file_path).await?,
            ONE_INSTALLED.to_vec()
        );
        Ok(())
    }

    #[test(tokio::test)]
    async fn a_first_home_that_cannot_be_created_writes_no_record() -> Res {
        let storage = MockStorage::default();
        storage
            .write_byte_stream("/blocked", ByteStream::from_static(b"a file"))
            .await?;
        let file_path = PathBuf::from("foo");

        DomainLineageIo::new(file_path.clone())
            .set_home(&storage, "/blocked/home")
            .await
            .unwrap_err();

        assert!(!storage.exists(&file_path).await);
        Ok(())
    }

    #[test]
    fn home_in_use_counts_packages_in_plural() {
        let err = LineageError::HomeInUse {
            home: PathBuf::from("/old/home"),
            installed: 3,
        };
        assert_eq!(
            err.to_string(),
            "Cannot change the home: 3 packages are installed in /old/home"
        );
    }

    #[test(tokio::test)]
    async fn test_domain_lineage_from_nothing() -> Res {
        let storage = MockStorage::default();
        let lineage = DomainLineageIo::new(PathBuf::from("does-not-exist"))
            .read(&storage)
            .await
            .unwrap_err();
        assert!(matches!(lineage, Error::Lineage(LineageError::Missing)));
        Ok(())
    }

    #[test(tokio::test)]
    async fn test_domain_lineage_write() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("foo");
        assert!(!storage.exists(&file_path).await);
        let bytes = "0123456789abcdef".as_bytes();
        let working_dir = PathBuf::from("/tmp/working_dir");
        DomainLineageIo::new(file_path.clone())
            .write(
                &storage,
                DomainLineage {
                    home: Home::new(working_dir),
                    packages: BTreeMap::from([(
                        ("foo", "bar").into(),
                        PackageLineage {
                            commit: None,
                            remote_uri: Some(ManifestUri {
                                bucket: "bucket".to_string(),
                                namespace: ("foo", "bar").into(),
                                hash: "abcdef".to_string(),
                                origin: None,
                            }),
                            base_hash: "abcdef".to_string(),
                            latest_hash: "abcdef".to_string(),
                            paths: BTreeMap::from([(
                                PathBuf::from("foo"),
                                PathState {
                                    timestamp: chrono::DateTime::from_timestamp_millis(
                                        1_737_031_820_534,
                                    )
                                    .unwrap(),
                                    hash: Sha256ChunkedHash::from_async_read(
                                        bytes,
                                        bytes.len() as u64,
                                    )
                                    .await?
                                    .into(),
                                },
                            )]),
                            ..PackageLineage::default()
                        },
                    )]),
                },
            )
            .await?;
        assert!(storage.exists(&file_path).await);
        let file_contents = storage.read_bytes(&file_path).await?;
        let lineage = DomainLineage::from_slice(&file_contents)?;

        assert_eq!(lineage.as_ref(), &PathBuf::from("/tmp/working_dir"));

        let multihash_from_lineage = lineage
            .packages
            .get(&(("foo".to_string(), "bar".to_string()).into()))
            .unwrap()
            .paths
            .get(&PathBuf::from("foo"))
            .unwrap()
            .hash;
        let hash_from_lineage = base64::encode(multihash_from_lineage.digest());
        assert_eq!(
            hash_from_lineage,
            "Xb1PbjJeWof4zD7zuHc9PI7sLiz/Ykj4gphlaZEt3xA="
        );
        Ok(())
    }

    #[test(tokio::test)]
    async fn test_read_package_lineage() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("lineage.json");
        let namespace = Namespace::from(("foo", "bar"));
        let package_lineage = PackageLineage {
            commit: None,
            remote_uri: Some(ManifestUri {
                bucket: "bucket".to_string(),
                namespace: namespace.clone(),
                hash: "abcdef".to_string(),
                origin: None,
            }),
            base_hash: "abcdef".to_string(),
            latest_hash: "abcdef".to_string(),
            paths: BTreeMap::new(),
            ..PackageLineage::default()
        };

        // Create a domain lineage with a package
        let lineage = DomainLineage {
            home: Home::from("/home/user/quilt"),
            packages: BTreeMap::from([(namespace.clone(), package_lineage.clone())]),
        };

        // Write it to storage
        let lineage_io = DomainLineageIo::new(file_path.clone());
        lineage_io.write(&storage, lineage).await?;

        // Read the package lineage
        let (package_home, read_package_lineage) = lineage_io
            .read_package_lineage(&storage, &namespace)
            .await?;

        // Verify the results
        assert_eq!(package_home, PathBuf::from("/home/user/quilt/foo/bar"));
        assert_eq!(read_package_lineage, package_lineage);

        // Try reading a non-existent package
        let non_existent = Namespace::from(("does", "notexist"));
        let result = lineage_io
            .read_package_lineage(&storage, &non_existent)
            .await;
        assert!(matches!(
            result.unwrap_err(),
            Error::InstallPackage(InstallPackageError::NotInstalled(ns)) if ns == non_existent
        ));

        Ok(())
    }

    #[test(tokio::test)]
    async fn test_update_package_lineage() -> Res {
        let storage = MockStorage::default();
        let file_path = PathBuf::from("lineage.json");
        let lineage_io = DomainLineageIo::new(file_path.clone());

        // Create an initial domain lineage with home directory
        let initial_lineage = DomainLineage {
            home: Home::from("/home/user/quilt"),
            packages: BTreeMap::new(),
        };

        // Write the initial lineage
        lineage_io.write(&storage, initial_lineage).await?;

        // Create a package lineage to write
        let namespace = Namespace::from(("foo", "bar"));
        let package_lineage = PackageLineage {
            commit: None,
            remote_uri: Some(ManifestUri {
                bucket: "bucket".to_string(),
                namespace: namespace.clone(),
                hash: "abcdef".to_string(),
                origin: None,
            }),
            base_hash: "abcdef".to_string(),
            latest_hash: "abcdef".to_string(),
            paths: BTreeMap::new(),
            ..PackageLineage::default()
        };

        // Write the package lineage
        let written_lineage = lineage_io
            .update_package_lineage(&storage, &namespace, |entry| {
                *entry = Some(package_lineage.clone());
                Ok(package_lineage.clone())
            })
            .await?;

        // Verify the written lineage matches what we provided
        assert_eq!(written_lineage, package_lineage);

        // Read the domain lineage to verify the package was added
        let domain_lineage = lineage_io.read(&storage).await?;
        assert_eq!(domain_lineage.packages.len(), 1);
        assert!(domain_lineage.packages.contains_key(&namespace));
        assert_eq!(
            domain_lineage.packages.get(&namespace).unwrap(),
            &package_lineage
        );

        // Update the package lineage
        let updated_package_lineage = PackageLineage {
            commit: Some(CommitState {
                timestamp: chrono::Utc::now(),
                hash: String::new(),
                prev_hashes: Vec::new(),
            }),
            ..package_lineage.clone()
        };

        // Write the updated package lineage
        lineage_io
            .update_package_lineage(&storage, &namespace, |entry| {
                *entry = Some(updated_package_lineage.clone());
                Ok(())
            })
            .await?;

        // Read the domain lineage again to verify the update
        let updated_domain_lineage = lineage_io.read(&storage).await?;
        assert_eq!(updated_domain_lineage.packages.len(), 1);
        assert!(updated_domain_lineage.packages.contains_key(&namespace));
        assert_eq!(
            updated_domain_lineage.packages.get(&namespace).unwrap(),
            &updated_package_lineage
        );

        Ok(())
    }

    /// The narrow edit reads the domain, changes one field, and writes — so a
    /// value another writer put in the same entry *before* that read survives,
    /// which is the point of not holding a copy across other work.
    #[test(tokio::test)]
    async fn edit_package_lineage_preserves_the_rest_of_the_entry() -> Res {
        let storage = MockStorage::default();
        let namespace = Namespace::from(("foo", "bar"));
        let lineage_io = DomainLineageIo::new(PathBuf::from("lineage.json"));
        lineage_io
            .write(
                &storage,
                DomainLineage {
                    home: Home::from("/home/user/quilt"),
                    packages: BTreeMap::from([(namespace.clone(), PackageLineage::default())]),
                },
            )
            .await?;

        // Stand in for a concurrent operation that advanced the entry.
        lineage_io
            .edit_package_lineage(&storage, &namespace, |l| {
                l.base_hash = "advanced".to_string();
            })
            .await?;

        let updated = lineage_io
            .edit_package_lineage(&storage, &namespace, |l| {
                l.sync_scope = package::SyncScope::EntirePackage;
            })
            .await?;

        assert_eq!(updated.sync_scope, package::SyncScope::EntirePackage);
        assert_eq!(
            updated.base_hash, "advanced",
            "the scope write must not roll back the other writer"
        );
        Ok(())
    }

    /// A package that is not installed is an error, not a silent insert.
    #[test(tokio::test)]
    async fn edit_package_lineage_refuses_an_unknown_namespace() -> Res {
        let storage = MockStorage::default();
        let lineage_io = DomainLineageIo::new(PathBuf::from("lineage.json"));
        lineage_io
            .write(&storage, DomainLineage::new("/home/user/quilt"))
            .await?;

        let err = lineage_io
            .edit_package_lineage(&storage, &Namespace::from(("no", "such")), |l| {
                l.sync_scope = package::SyncScope::EntirePackage;
            })
            .await
            .unwrap_err();
        assert!(matches!(
            err,
            Error::InstallPackage(InstallPackageError::NotInstalled(_))
        ));
        Ok(())
    }

    #[test(tokio::test)]
    async fn test_domain_lineage_create_package_lineage() -> Res {
        let namespace = ("foo", "bar");
        let domain_lineage = DomainLineageIo::default();
        let lineage = domain_lineage.create_package_lineage(namespace.into());
        assert_eq!(
            lineage,
            PackageLineageIo {
                namespace: namespace.into(),
                domain_lineage,
            }
        );
        Ok(())
    }
}