phasesmith-persistence 0.3.0

//! Canonical, Python-free project persistence and stable summary reporting.
//!
//! Project bundles are directories containing `manifest.json` plus a numeric
//! `arrays.npz`. Wire records are explicit and versioned; live domain types do
//! not derive serialization directly.
//! Applications normally use this crate through
//! [`phasesmith::persistence`](https://docs.rs/phasesmith/latest/phasesmith/).
//!
//! # Bundle contract
//!
//! - `manifest.json` contains the format version, explicit wire records, array
//!   descriptors, shapes, dtypes, and hashes.
//! - `arrays.npz` contains typed little-endian numeric arrays.
//! - loads validate the exact member set, hashes, shapes, dtypes, finiteness,
//!   cross-record identities, and caller-selected [`ProjectReadLimits`].
//! - overwrite replaces only the two library-owned files and preserves
//!   unrelated application content in the directory.
//!
//! # Saving and loading
//!
//! ```no_run
//! use std::collections::BTreeMap;
//! use phasesmith_model::{ProjectRecord, RecordId};
//! use phasesmith_persistence::{
//!     ProjectReadLimits, ProjectSaveOptions, load_project, save_project,
//! };
//!
//! let project = ProjectRecord {
//!     project_id: RecordId::new("example")?,
//!     revision: 0,
//!     name: "Example".into(),
//!     histograms: Vec::new(),
//!     tof_histograms: Vec::new(),
//!     phases: Vec::new(),
//!     metadata: BTreeMap::new(),
//! };
//! save_project("example.psproj", &project, ProjectSaveOptions::default())?;
//! let restored = load_project("example.psproj", ProjectReadLimits::default())?;
//! assert_eq!(restored.project_id, project.project_id);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! Use [`save_rietveld_project`] / [`load_rietveld_project`] or
//! [`save_tof_lebail_project`] / [`load_tof_lebail_project`] when the bundle
//! must retain runnable single-histogram analyses. Joint TOF geometry state uses
//! [`save_tof_multibank_geometry_project`] and
//! [`load_tof_multibank_geometry_project`]. Structural multi-bank TOF state uses
//! [`save_structural_tof_multibank_project`] and
//! [`load_structural_tof_multibank_project`]. TOF histograms keep microseconds
//! separate from constant-wavelength degree coordinates. Reporting functions
//! produce stable JSON summaries without exposing internal wire records.

mod arrays;
mod report;
mod rietveld_wire;
mod tof_multibank_wire;
mod tof_structural_wire;
mod tof_wire;
mod wire;

use std::collections::BTreeMap;
use std::error::Error;
use std::fmt::{Display, Formatter};
use std::fs;
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};

use arrays::{ArrayDescriptor, read_npz, sha256_hex, write_npz};
use phasesmith_model::{DomainError, ProjectRecord};
use phasesmith_workflows::{
    RietveldProjectState, StructuralTofMultiBankProjectState, TofLeBailProjectState,
    TofMultiBankGeometryProjectState,
};
use serde::{Deserialize, Serialize};

pub use report::{
    HistogramSummary, PhaseSummary, ProjectReportSaveOptions, ProjectSummaryReport,
    project_summary_json, write_project_summary_json, write_project_summary_json_with_options,
};

/// Current native project bundle wire version.
pub const PROJECT_FORMAT_VERSION: u32 = 5;
/// Canonical manifest filename within a project directory.
pub const PROJECT_MANIFEST_NAME: &str = "manifest.json";
/// Canonical `NumPy` archive filename within a project directory.
pub const PROJECT_ARRAYS_NAME: &str = "arrays.npz";

const MANIFEST_BACKUP_NAME: &str = ".manifest.json.phasesmith-backup";
const ARRAYS_BACKUP_NAME: &str = ".arrays.npz.phasesmith-backup";

static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0);

/// Resource limits applied before allocating project records and arrays.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ProjectReadLimits {
    /// Maximum manifest byte count.
    pub max_manifest_bytes: u64,
    /// Maximum compressed NPZ byte count.
    pub max_archive_bytes: u64,
    /// Maximum number of declared arrays.
    pub max_arrays: usize,
    /// Maximum element count of one array.
    pub max_array_elements: usize,
    /// Maximum combined uncompressed NPY bytes.
    pub max_uncompressed_array_bytes: u64,
    /// Maximum histogram count.
    pub max_histograms: usize,
    /// Maximum structural phase count.
    pub max_phases: usize,
}

impl Default for ProjectReadLimits {
    fn default() -> Self {
        Self {
            max_manifest_bytes: 16 * 1024 * 1024,
            max_archive_bytes: 256 * 1024 * 1024,
            max_arrays: 10_000,
            max_array_elements: 50_000_000,
            max_uncompressed_array_bytes: 512 * 1024 * 1024,
            max_histograms: 10_000,
            max_phases: 10_000,
        }
    }
}

impl ProjectReadLimits {
    fn validate(self) -> Result<(), PersistenceError> {
        if self.max_manifest_bytes == 0
            || self.max_archive_bytes == 0
            || self.max_arrays == 0
            || self.max_array_elements == 0
            || self.max_uncompressed_array_bytes == 0
            || self.max_histograms == 0
            || self.max_phases == 0
        {
            return Err(PersistenceError::InvalidLimits);
        }
        Ok(())
    }
}

/// Native project save behavior.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct ProjectSaveOptions {
    /// Replace only the two library-owned files in an existing directory.
    pub overwrite: bool,
}

/// Structured native persistence failure.
#[derive(Debug)]
pub enum PersistenceError {
    /// A configured read limit is zero.
    InvalidLimits,
    /// Input exceeded an explicit resource limit.
    LimitExceeded {
        /// Stable explanation naming the limit.
        message: String,
    },
    /// A path has the wrong kind or overwrite policy.
    InvalidDestination {
        /// Stable explanation.
        message: String,
    },
    /// Filesystem operation failed.
    Io(std::io::Error),
    /// Manifest JSON syntax or shape is invalid.
    Json(serde_json::Error),
    /// Unsupported project format version.
    UnsupportedVersion {
        /// Rejected version.
        version: u32,
    },
    /// Array descriptor, shape, dtype, or value is invalid.
    InvalidArray {
        /// Stable explanation.
        message: String,
    },
    /// NPZ/NPY archive structure or hashes are invalid.
    InvalidArchive {
        /// Stable explanation.
        message: String,
    },
    /// Wire record is invalid or inconsistent.
    InvalidRecord {
        /// Stable explanation.
        message: String,
    },
    /// Reconstructed domain project failed validation.
    Domain(DomainError),
}

impl Display for PersistenceError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::InvalidLimits => formatter.write_str("all project read limits must be positive"),
            Self::LimitExceeded { message }
            | Self::InvalidDestination { message }
            | Self::InvalidArray { message }
            | Self::InvalidArchive { message }
            | Self::InvalidRecord { message } => formatter.write_str(message),
            Self::Io(error) => Display::fmt(error, formatter),
            Self::Json(error) => Display::fmt(error, formatter),
            Self::UnsupportedVersion { version } => {
                write!(formatter, "unsupported native project format {version}")
            }
            Self::Domain(error) => Display::fmt(error, formatter),
        }
    }
}

impl Error for PersistenceError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Io(error) => Some(error),
            Self::Json(error) => Some(error),
            Self::Domain(error) => Some(error),
            _ => None,
        }
    }
}

impl From<std::io::Error> for PersistenceError {
    fn from(error: std::io::Error) -> Self {
        Self::Io(error)
    }
}

impl From<serde_json::Error> for PersistenceError {
    fn from(error: serde_json::Error) -> Self {
        Self::Json(error)
    }
}

#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct ArchiveRecord {
    file: String,
    sha256: String,
}

#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct ProjectManifest {
    format_version: u32,
    archive: ArchiveRecord,
    arrays: BTreeMap<String, ArrayDescriptor>,
    project: wire::WireProject,
    #[serde(default)]
    rietveld_analyses: Option<Vec<rietveld_wire::WireRietveldAnalysis>>,
    #[serde(default)]
    tof_lebail_analyses: Option<Vec<tof_wire::WireTofLeBailAnalysis>>,
    #[serde(default)]
    tof_multibank_geometry_analyses:
        Option<Vec<tof_multibank_wire::WireTofMultiBankGeometryAnalysis>>,
    #[serde(default)]
    structural_tof_multibank_analyses: Option<Vec<tof_structural_wire::WireStructuralTofAnalysis>>,
}

#[derive(Debug, Deserialize)]
struct ProjectVersionProbe {
    format_version: u32,
}

type LoadedProjectParts = (
    ProjectRecord,
    Vec<rietveld_wire::WireRietveldAnalysis>,
    Vec<tof_wire::WireTofLeBailAnalysis>,
    Vec<tof_multibank_wire::WireTofMultiBankGeometryAnalysis>,
    Vec<tof_structural_wire::WireStructuralTofAnalysis>,
    BTreeMap<String, arrays::ArrayData>,
);

/// Save one validated native project as canonical JSON plus NPZ.
///
/// Only `manifest.json` and `arrays.npz` are created or replaced; unrelated
/// files in an existing directory remain untouched.
///
/// # Errors
///
/// Returns [`PersistenceError`] for invalid domain state, unsupported values,
/// serialization, archive, filesystem, or overwrite failures.
pub fn save_project(
    path: impl AsRef<Path>,
    project: &ProjectRecord,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    project.validate().map_err(PersistenceError::Domain)?;
    save_project_parts(
        path.as_ref(),
        project,
        Vec::new(),
        Vec::new(),
        Vec::new(),
        Vec::new(),
        BTreeMap::new(),
        options,
    )
}

/// Save one validated project and all runnable native Rietveld analyses.
///
/// # Errors
///
/// Returns [`PersistenceError`] for invalid cross-record state, serialization,
/// archive, filesystem, or overwrite failures.
pub fn save_rietveld_project(
    path: impl AsRef<Path>,
    state: &RietveldProjectState,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    state
        .validate()
        .map_err(|error| PersistenceError::InvalidRecord {
            message: format!("invalid native Rietveld project state: {error}"),
        })?;
    save_project_parts(
        path.as_ref(),
        &state.project,
        rietveld_wire::encode_analyses(state),
        Vec::new(),
        Vec::new(),
        Vec::new(),
        BTreeMap::new(),
        options,
    )
}

/// Save one validated project and all resumable fixed-instrument TOF Le Bail analyses.
///
/// # Errors
///
/// Returns [`PersistenceError`] for invalid cross-record state, serialization,
/// archive, filesystem, or overwrite failures.
pub fn save_tof_lebail_project(
    path: impl AsRef<Path>,
    state: &TofLeBailProjectState,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    state
        .validate()
        .map_err(|error| PersistenceError::InvalidRecord {
            message: format!("invalid native TOF project state: {error}"),
        })?;
    let (analyses, arrays) = tof_wire::encode_analyses(state)?;
    save_project_parts(
        path.as_ref(),
        &state.project,
        Vec::new(),
        analyses,
        Vec::new(),
        Vec::new(),
        arrays,
        options,
    )
}

/// Save one validated project and all resumable joint multi-bank TOF analyses.
///
/// # Errors
///
/// Returns [`PersistenceError`] for invalid cross-record state, serialization,
/// archive, filesystem, or overwrite failures.
pub fn save_tof_multibank_geometry_project(
    path: impl AsRef<Path>,
    state: &TofMultiBankGeometryProjectState,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    state
        .validate()
        .map_err(|error| PersistenceError::InvalidRecord {
            message: format!("invalid joint TOF project state: {error}"),
        })?;
    let (analyses, arrays) = tof_multibank_wire::encode_analyses(state)?;
    save_project_parts(
        path.as_ref(),
        &state.project,
        Vec::new(),
        Vec::new(),
        analyses,
        Vec::new(),
        arrays,
        options,
    )
}

/// Save one validated project and all resumable structural multi-bank TOF analyses.
///
/// # Errors
///
/// Returns [`PersistenceError`] for invalid cross-record state, serialization,
/// archive, filesystem, or overwrite failures.
pub fn save_structural_tof_multibank_project(
    path: impl AsRef<Path>,
    state: &StructuralTofMultiBankProjectState,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    state
        .validate()
        .map_err(|error| PersistenceError::InvalidRecord {
            message: format!("invalid structural TOF project state: {error}"),
        })?;
    save_project_parts(
        path.as_ref(),
        &state.project,
        Vec::new(),
        Vec::new(),
        Vec::new(),
        tof_structural_wire::encode_analyses(state),
        BTreeMap::new(),
        options,
    )
}

#[allow(clippy::too_many_arguments)] // One explicit slot per independently versioned analysis family.
fn save_project_parts(
    path: &Path,
    project: &ProjectRecord,
    rietveld_analyses: Vec<rietveld_wire::WireRietveldAnalysis>,
    tof_lebail_analyses: Vec<tof_wire::WireTofLeBailAnalysis>,
    tof_multibank_geometry_analyses: Vec<tof_multibank_wire::WireTofMultiBankGeometryAnalysis>,
    structural_tof_multibank_analyses: Vec<tof_structural_wire::WireStructuralTofAnalysis>,
    analysis_arrays: BTreeMap<String, arrays::ArrayData>,
    options: ProjectSaveOptions,
) -> Result<PathBuf, PersistenceError> {
    let destination = absolute_path(path)?;
    if destination.is_dir() {
        recover_interrupted_save(&destination)?;
    }
    validate_destination(&destination, options)?;
    let (wire_project, mut arrays) = wire::encode_project(project)?;
    for (name, value) in analysis_arrays {
        if arrays.insert(name.clone(), value).is_some() {
            return Err(PersistenceError::InvalidRecord {
                message: format!("duplicate project/analysis array name {name:?}"),
            });
        }
    }
    let encoded_archive = write_npz(&arrays)?;
    let descriptors = arrays
        .iter()
        .map(|(name, value)| (name.clone(), value.descriptor()))
        .collect();
    let manifest = ProjectManifest {
        format_version: PROJECT_FORMAT_VERSION,
        archive: ArchiveRecord {
            file: PROJECT_ARRAYS_NAME.to_owned(),
            sha256: sha256_hex(&encoded_archive),
        },
        arrays: descriptors,
        project: wire_project,
        rietveld_analyses: Some(rietveld_analyses),
        tof_lebail_analyses: Some(tof_lebail_analyses),
        tof_multibank_geometry_analyses: Some(tof_multibank_geometry_analyses),
        structural_tof_multibank_analyses: Some(structural_tof_multibank_analyses),
    };
    let mut encoded_manifest = serde_json::to_string_pretty(&manifest)?;
    encoded_manifest.push('\n');

    let parent = destination
        .parent()
        .ok_or_else(|| PersistenceError::InvalidDestination {
            message: "project destination has no parent directory".to_owned(),
        })?;
    fs::create_dir_all(parent)?;
    let temporary = create_temporary_directory(parent, &destination)?;
    let write_result: Result<(), PersistenceError> = (|| {
        write_synced_file(&temporary.join(PROJECT_ARRAYS_NAME), &encoded_archive)?;
        write_synced_file(
            &temporary.join(PROJECT_MANIFEST_NAME),
            encoded_manifest.as_bytes(),
        )?;
        fs::create_dir_all(&destination)?;
        if options.overwrite {
            backup_owned_file(
                &destination.join(PROJECT_MANIFEST_NAME),
                &destination.join(MANIFEST_BACKUP_NAME),
            )?;
            backup_owned_file(
                &destination.join(PROJECT_ARRAYS_NAME),
                &destination.join(ARRAYS_BACKUP_NAME),
            )?;
        }
        fs::rename(
            temporary.join(PROJECT_ARRAYS_NAME),
            destination.join(PROJECT_ARRAYS_NAME),
        )?;
        fs::rename(
            temporary.join(PROJECT_MANIFEST_NAME),
            destination.join(PROJECT_MANIFEST_NAME),
        )?;
        sync_directory(&destination)?;
        remove_if_exists(&destination.join(MANIFEST_BACKUP_NAME))?;
        remove_if_exists(&destination.join(ARRAYS_BACKUP_NAME))?;
        sync_directory(&destination)?;
        Ok(())
    })();
    if write_result.is_err() && destination.is_dir() {
        let _ = recover_interrupted_save(&destination);
    }
    let _ = fs::remove_dir_all(&temporary);
    write_result?;
    Ok(destination)
}

/// Load and fully validate one canonical native project directory.
///
/// # Errors
///
/// Returns [`PersistenceError`] for resource, filesystem, JSON, hash, archive,
/// wire-record, or domain validation failures.
pub fn load_project(
    path: impl AsRef<Path>,
    limits: ProjectReadLimits,
) -> Result<ProjectRecord, PersistenceError> {
    let (
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        mut arrays,
    ) = load_project_parts(path.as_ref(), limits)?;
    let project = tof_structural_wire::decode_state(project, structural_analyses, limits)?.project;
    let project =
        tof_multibank_wire::decode_state(project, multibank_analyses, &mut arrays, limits)?.project;
    let project = tof_wire::decode_state(project, tof_analyses, &mut arrays, limits)?.project;
    if !arrays.is_empty() {
        return Err(PersistenceError::InvalidRecord {
            message: "manifest contains arrays that are not referenced by the project".to_owned(),
        });
    }
    Ok(rietveld_wire::decode_state(project, rietveld_analyses, limits)?.project)
}

/// Load and validate one project plus all native Rietveld analyses.
///
/// Version-1 native projects load with an empty analysis list.
///
/// # Errors
///
/// Returns [`PersistenceError`] for resource, filesystem, JSON, hash, archive,
/// wire-record, domain, or Rietveld validation failures.
pub fn load_rietveld_project(
    path: impl AsRef<Path>,
    limits: ProjectReadLimits,
) -> Result<RietveldProjectState, PersistenceError> {
    let (
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        mut arrays,
    ) = load_project_parts(path.as_ref(), limits)?;
    let project = tof_structural_wire::decode_state(project, structural_analyses, limits)?.project;
    let project =
        tof_multibank_wire::decode_state(project, multibank_analyses, &mut arrays, limits)?.project;
    let project = tof_wire::decode_state(project, tof_analyses, &mut arrays, limits)?.project;
    if !arrays.is_empty() {
        return Err(PersistenceError::InvalidRecord {
            message: "manifest contains arrays that are not referenced by the project".to_owned(),
        });
    }
    rietveld_wire::decode_state(project, rietveld_analyses, limits)
}

/// Load and validate one project plus all resumable fixed-instrument TOF Le Bail analyses.
///
/// Version-1 and version-2 native projects load with an empty analysis list.
///
/// # Errors
///
/// Returns [`PersistenceError`] for resource, filesystem, JSON, hash, archive,
/// wire-record, domain, or TOF workflow validation failures.
pub fn load_tof_lebail_project(
    path: impl AsRef<Path>,
    limits: ProjectReadLimits,
) -> Result<TofLeBailProjectState, PersistenceError> {
    let (
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        mut arrays,
    ) = load_project_parts(path.as_ref(), limits)?;
    let project = tof_structural_wire::decode_state(project, structural_analyses, limits)?.project;
    let project =
        tof_multibank_wire::decode_state(project, multibank_analyses, &mut arrays, limits)?.project;
    rietveld_wire::decode_state(project.clone(), rietveld_analyses, limits)?;
    let state = tof_wire::decode_state(project, tof_analyses, &mut arrays, limits)?;
    if !arrays.is_empty() {
        return Err(PersistenceError::InvalidRecord {
            message: "manifest contains arrays that are not referenced by the project".to_owned(),
        });
    }
    Ok(state)
}

/// Load and validate one project plus all resumable joint multi-bank TOF analyses.
///
/// Versions 1 through 3 load with an empty joint-analysis list.
///
/// # Errors
///
/// Returns [`PersistenceError`] for resource, filesystem, JSON, hash, archive,
/// wire-record, domain, or joint TOF validation failures.
pub fn load_tof_multibank_geometry_project(
    path: impl AsRef<Path>,
    limits: ProjectReadLimits,
) -> Result<TofMultiBankGeometryProjectState, PersistenceError> {
    let (
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        mut arrays,
    ) = load_project_parts(path.as_ref(), limits)?;
    let project = tof_structural_wire::decode_state(project, structural_analyses, limits)?.project;
    rietveld_wire::decode_state(project.clone(), rietveld_analyses, limits)?;
    let project = tof_wire::decode_state(project, tof_analyses, &mut arrays, limits)?.project;
    let state = tof_multibank_wire::decode_state(project, multibank_analyses, &mut arrays, limits)?;
    if !arrays.is_empty() {
        return Err(PersistenceError::InvalidRecord {
            message: "manifest contains arrays that are not referenced by the project".to_owned(),
        });
    }
    Ok(state)
}

/// Load and validate one project plus all resumable structural multi-bank TOF analyses.
///
/// Versions 1 through 4 load with an empty structural-analysis list.
///
/// # Errors
///
/// Returns [`PersistenceError`] for resource, filesystem, JSON, hash, archive,
/// wire-record, domain, or structural TOF validation failures.
pub fn load_structural_tof_multibank_project(
    path: impl AsRef<Path>,
    limits: ProjectReadLimits,
) -> Result<StructuralTofMultiBankProjectState, PersistenceError> {
    let (
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        mut arrays,
    ) = load_project_parts(path.as_ref(), limits)?;
    rietveld_wire::decode_state(project.clone(), rietveld_analyses, limits)?;
    let project = tof_wire::decode_state(project, tof_analyses, &mut arrays, limits)?.project;
    let project =
        tof_multibank_wire::decode_state(project, multibank_analyses, &mut arrays, limits)?.project;
    let state = tof_structural_wire::decode_state(project, structural_analyses, limits)?;
    if !arrays.is_empty() {
        return Err(PersistenceError::InvalidRecord {
            message: "manifest contains arrays that are not referenced by the project".to_owned(),
        });
    }
    Ok(state)
}

#[allow(clippy::too_many_lines)] // The explicit version/field matrix is kept together for auditability.
fn load_project_parts(
    path: &Path,
    limits: ProjectReadLimits,
) -> Result<LoadedProjectParts, PersistenceError> {
    limits.validate()?;
    let source = absolute_path(path)?;
    if source.is_dir() {
        recover_interrupted_save(&source)?;
    }
    let manifest_path = source.join(PROJECT_MANIFEST_NAME);
    let archive_path = source.join(PROJECT_ARRAYS_NAME);
    let manifest_bytes = read_bounded_file(
        &manifest_path,
        limits.max_manifest_bytes,
        "project manifest exceeds max_manifest_bytes",
    )?;
    let version: ProjectVersionProbe = serde_json::from_slice(&manifest_bytes)?;
    if !(1..=PROJECT_FORMAT_VERSION).contains(&version.format_version) {
        return Err(PersistenceError::UnsupportedVersion {
            version: version.format_version,
        });
    }
    let manifest: ProjectManifest = serde_json::from_slice(&manifest_bytes)?;
    let rietveld_analyses = match (manifest.format_version, manifest.rietveld_analyses) {
        (1, None) => Vec::new(),
        (1, Some(_)) => {
            return Err(PersistenceError::InvalidRecord {
                message: "native project format 1 cannot declare Rietveld analyses".to_owned(),
            });
        }
        (2..=5, Some(analyses)) => analyses,
        (2..=5, None) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} requires Rietveld analyses",
                    manifest.format_version
                ),
            });
        }
        _ => unreachable!("format version checked above"),
    };
    let tof_analyses = match (manifest.format_version, manifest.tof_lebail_analyses) {
        (1 | 2, None) => Vec::new(),
        (1 | 2, Some(_)) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} cannot declare TOF Le Bail analyses",
                    manifest.format_version
                ),
            });
        }
        (3..=5, Some(analyses)) => analyses,
        (3..=5, None) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} requires TOF Le Bail analyses",
                    manifest.format_version
                ),
            });
        }
        _ => unreachable!("format version checked above"),
    };
    let multibank_analyses = match (
        manifest.format_version,
        manifest.tof_multibank_geometry_analyses,
    ) {
        (1..=3, None) => Vec::new(),
        (1..=3, Some(_)) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} cannot declare joint TOF analyses",
                    manifest.format_version
                ),
            });
        }
        (4 | 5, Some(analyses)) => analyses,
        (4 | 5, None) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} requires joint TOF analyses",
                    manifest.format_version
                ),
            });
        }
        _ => unreachable!("format version checked above"),
    };
    let structural_analyses = match (
        manifest.format_version,
        manifest.structural_tof_multibank_analyses,
    ) {
        (1..=4, None) => Vec::new(),
        (1..=4, Some(_)) => {
            return Err(PersistenceError::InvalidRecord {
                message: format!(
                    "native project format {} cannot declare structural TOF analyses",
                    manifest.format_version
                ),
            });
        }
        (5, Some(analyses)) => analyses,
        (5, None) => {
            return Err(PersistenceError::InvalidRecord {
                message: "native project format 5 requires structural TOF analyses".to_owned(),
            });
        }
        _ => unreachable!("format version checked above"),
    };
    if manifest.format_version < 3 && wire::has_tof_histograms(&manifest.project) {
        return Err(PersistenceError::InvalidRecord {
            message: format!(
                "native project format {} cannot declare TOF histograms",
                manifest.format_version
            ),
        });
    }
    if manifest.archive.file != PROJECT_ARRAYS_NAME {
        return Err(PersistenceError::InvalidArchive {
            message: "project archive filename is invalid".to_owned(),
        });
    }
    if manifest.arrays.len() > limits.max_arrays {
        return Err(PersistenceError::LimitExceeded {
            message: "project manifest exceeds max_arrays".to_owned(),
        });
    }
    let archive_bytes = read_bounded_file(
        &archive_path,
        limits.max_archive_bytes,
        "project archive exceeds max_archive_bytes",
    )?;
    if sha256_hex(&archive_bytes) != manifest.archive.sha256 {
        return Err(PersistenceError::InvalidArchive {
            message: "project archive SHA-256 mismatch".to_owned(),
        });
    }
    let mut arrays = read_npz(&archive_bytes, &manifest.arrays, limits)?;
    let project = wire::decode_project_parts(manifest.project, &mut arrays, limits)?;
    Ok((
        project,
        rietveld_analyses,
        tof_analyses,
        multibank_analyses,
        structural_analyses,
        arrays,
    ))
}

fn read_bounded_file(
    path: &Path,
    maximum_bytes: u64,
    limit_message: &str,
) -> Result<Vec<u8>, PersistenceError> {
    let mut bytes = Vec::new();
    fs::File::open(path)?
        .take(maximum_bytes.saturating_add(1))
        .read_to_end(&mut bytes)?;
    if u64::try_from(bytes.len()).map_or(true, |length| length > maximum_bytes) {
        return Err(PersistenceError::LimitExceeded {
            message: limit_message.to_owned(),
        });
    }
    Ok(bytes)
}

fn absolute_path(path: &Path) -> Result<PathBuf, PersistenceError> {
    if path.is_absolute() {
        return Ok(path.to_owned());
    }
    Ok(std::env::current_dir()?.join(path))
}

fn validate_destination(
    destination: &Path,
    options: ProjectSaveOptions,
) -> Result<(), PersistenceError> {
    if destination.exists() && !destination.is_dir() {
        return Err(PersistenceError::InvalidDestination {
            message: format!(
                "project path exists and is not a directory: {}",
                destination.display()
            ),
        });
    }
    if destination.exists() && !options.overwrite {
        return Err(PersistenceError::InvalidDestination {
            message: format!(
                "project directory already exists: {}",
                destination.display()
            ),
        });
    }
    Ok(())
}

fn create_temporary_directory(
    parent: &Path,
    destination: &Path,
) -> Result<PathBuf, PersistenceError> {
    let stem = destination
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or("project");
    for _ in 0..100 {
        let sequence = TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed);
        let candidate = parent.join(format!(".{stem}-{}-{sequence}.tmp", std::process::id()));
        match fs::create_dir(&candidate) {
            Ok(()) => return Ok(candidate),
            Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
            Err(error) => return Err(PersistenceError::Io(error)),
        }
    }
    Err(PersistenceError::InvalidDestination {
        message: "could not allocate a temporary project directory".to_owned(),
    })
}

fn write_synced_file(path: &Path, bytes: &[u8]) -> Result<(), PersistenceError> {
    let mut file = fs::File::create(path)?;
    file.write_all(bytes)?;
    file.sync_all()?;
    Ok(())
}

#[cfg(not(windows))]
fn sync_directory(path: &Path) -> Result<(), PersistenceError> {
    fs::File::open(path)?.sync_all()?;
    Ok(())
}

#[cfg(windows)]
fn sync_directory(_path: &Path) -> Result<(), PersistenceError> {
    // `File::open` cannot open directories on Windows. The project files are
    // individually synced before they are renamed, but the standard library
    // does not expose a portable equivalent of a Unix directory fsync.
    Ok(())
}

fn backup_owned_file(source: &Path, backup: &Path) -> Result<(), PersistenceError> {
    remove_if_exists(backup)?;
    if source.exists() {
        fs::rename(source, backup)?;
    }
    Ok(())
}

fn remove_if_exists(path: &Path) -> Result<(), PersistenceError> {
    match fs::remove_file(path) {
        Ok(()) => Ok(()),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(PersistenceError::Io(error)),
    }
}

fn recover_interrupted_save(directory: &Path) -> Result<(), PersistenceError> {
    let manifest = directory.join(PROJECT_MANIFEST_NAME);
    let arrays = directory.join(PROJECT_ARRAYS_NAME);
    let manifest_backup = directory.join(MANIFEST_BACKUP_NAME);
    let arrays_backup = directory.join(ARRAYS_BACKUP_NAME);
    let has_manifest_backup = manifest_backup.exists();
    let has_arrays_backup = arrays_backup.exists();
    if !has_manifest_backup && !has_arrays_backup {
        return Ok(());
    }
    if manifest.exists() && arrays.exists() {
        remove_if_exists(&manifest_backup)?;
        remove_if_exists(&arrays_backup)?;
        sync_directory(directory)?;
        return Ok(());
    }
    for (current, backup) in [(&arrays, &arrays_backup), (&manifest, &manifest_backup)] {
        if backup.exists() {
            remove_if_exists(current)?;
            fs::rename(backup, current)?;
        }
    }
    sync_directory(directory)?;
    Ok(())
}