u280_hardware_promoter/

publication.rs

//! Exclusive hidden-sibling construction and atomic no-replace publication.

use crate::canonical::sha256_hex;
use crate::{
    DurablePromotionBurn, FailureCode, PromotionDocument, PromotionError, PromotionResult,
    PromotionTransactionIdentity,
};
use rustix::fs::{
    CWD, FileType, Mode, OFlags, RawDir, RenameFlags, ResolveFlags, fchmod, fsync, mkdirat,
    openat2, renameat_with,
};
use rustix::io::Errno;
use rustix::process::geteuid;
use std::collections::BTreeSet;
use std::fs::{File, Metadata};
use std::io::Write;
use std::mem::MaybeUninit;
use std::os::unix::fs::MetadataExt;
use std::path::{Path, PathBuf};

const RESULT_FILE: &str = "promotion-result.json";
const MANIFEST_FILE: &str = "SHA256SUMS";
const DIRECTORY_BUFFER_BYTES: usize = 16 * 1024;
const MAXIMUM_RESULT_BYTES: usize = 1024 * 1024;

#[derive(Clone, Debug, Eq, PartialEq)]
struct Fingerprint {
    dev: u64,
    ino: u64,
    mode: u32,
    uid: u32,
    nlink: u64,
    bytes: u64,
}

impl Fingerprint {
    fn from_metadata(metadata: &Metadata) -> Self {
        Self {
            dev: metadata.dev(),
            ino: metadata.ino(),
            mode: metadata.mode(),
            uid: metadata.uid(),
            nlink: metadata.nlink(),
            bytes: metadata.size(),
        }
    }

    fn same_object(&self, other: &Self) -> bool {
        self.dev == other.dev && self.ino == other.ino
    }
}

/// Private hidden-sibling candidate that has not yet been published.
#[derive(Debug)]
pub struct AtomicPublication {
    output_path: PathBuf,
    parent_path: PathBuf,
    parent: File,
    parent_fingerprint: Fingerprint,
    output_name: String,
    temporary_name: String,
    directory: File,
    directory_fingerprint: Fingerprint,
    transaction: PromotionTransactionIdentity,
    manifest_bytes: u64,
    manifest_sha256: String,
    result_bytes: u64,
    result_sha256: String,
}

/// Receipt for one successful `RENAME_NOREPLACE` publication.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PublicationReceipt {
    output_path: PathBuf,
    manifest_bytes: u64,
    manifest_sha256: String,
    promotion_journal_record_sha256: String,
}

impl PublicationReceipt {
    /// Newly published immutable result directory.
    #[must_use]
    pub fn output_path(&self) -> &Path {
        &self.output_path
    }

    /// Byte count of the result directory's canonical `SHA256SUMS`.
    #[must_use]
    pub const fn manifest_bytes(&self) -> u64 {
        self.manifest_bytes
    }

    /// SHA-256 of the canonical `SHA256SUMS`.
    #[must_use]
    pub fn manifest_sha256(&self) -> &str {
        &self.manifest_sha256
    }

    /// Durable private-state record that preceded publication.
    #[must_use]
    pub fn promotion_journal_record_sha256(&self) -> &str {
        &self.promotion_journal_record_sha256
    }
}

impl AtomicPublication {
    /// Constructs and seals a candidate in a brand-new hidden sibling.
    ///
    /// The parent and candidate are descriptor-rooted with symlink resolution
    /// disabled. Both files use `O_EXCL`, are fsynced, rehashed, checked for a
    /// hard-link count of one, and changed to mode 0400; the directory becomes
    /// mode 0500. Existing output or temporary names are rejected.
    ///
    /// # Errors
    ///
    /// Returns [`FailureCode::Publication`] for any path, identity, write,
    /// recheck, permission, or exclusivity failure.
    pub fn prepare(output_path: &Path, document: &PromotionDocument) -> PromotionResult<Self> {
        validate_absolute_output(output_path)?;
        let (parent_path, output_name) = split_output_path(output_path)?;
        validate_component(&output_name)?;
        let transaction = document.transaction_identity().clone();
        let run_id = transaction.run_id();
        if run_id.len() != 32
            || !run_id
                .bytes()
                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
            || !run_id.bytes().any(|byte| byte != b'0')
        {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "publication run_id is not canonical 128-bit lowercase hex",
            ));
        }
        let temporary_name = format!(".hashsigs-u280-promotion-{run_id}.tmp");
        validate_component(&temporary_name)?;
        let parent = open_absolute_directory(&parent_path)?;
        let parent_fingerprint = private_parent_fingerprint(&parent)?;
        require_missing(&parent, &output_name, "output directory")?;
        require_missing(&parent, &temporary_name, "hidden publication candidate")?;
        mkdirat(&parent, temporary_name.as_str(), Mode::RWXU).map_err(|error| {
            publication_error("cannot create hidden publication candidate", error)
        })?;
        fsync(&parent)
            .map_err(|error| publication_error("cannot fsync publication parent", error))?;
        let directory = open_directory_beneath(&parent, &temporary_name)?;
        fchmod(&directory, Mode::RWXU)
            .map_err(|error| publication_error("cannot set candidate mode 0700", error))?;
        let directory_fingerprint = Fingerprint::from_metadata(
            &directory
                .metadata()
                .map_err(|error| publication_error("cannot stat publication candidate", error))?,
        );

        let result_bytes = document.canonical_bytes()?;
        if result_bytes.is_empty() || result_bytes.len() > MAXIMUM_RESULT_BYTES {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "canonical promotion document is empty or exceeds 1 MiB",
            ));
        }
        let result_digest = write_exclusive(&directory, RESULT_FILE, &result_bytes)?;
        let manifest = format!("{}  {RESULT_FILE}\n", result_digest.sha256);
        let manifest_digest = write_exclusive(&directory, MANIFEST_FILE, manifest.as_bytes())?;
        require_exact_tree(&directory, &result_digest, &manifest_digest)?;
        fchmod(&directory, Mode::RUSR | Mode::XUSR)
            .map_err(|error| publication_error("cannot set candidate mode 0500", error))?;
        fsync(&directory)
            .map_err(|error| publication_error("cannot fsync sealed candidate", error))?;
        fsync(&parent)
            .map_err(|error| publication_error("cannot fsync publication parent", error))?;
        let sealed = Fingerprint::from_metadata(
            &directory
                .metadata()
                .map_err(|error| publication_error("cannot restat sealed candidate", error))?,
        );
        if !sealed.same_object(&directory_fingerprint) || sealed.mode & 0o777 != 0o500 {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "sealed candidate identity or mode changed",
            ));
        }

        Ok(Self {
            output_path: parent_path.join(&output_name),
            parent_path,
            parent,
            parent_fingerprint,
            output_name,
            temporary_name,
            directory,
            directory_fingerprint: sealed,
            transaction,
            manifest_bytes: manifest_digest.bytes,
            manifest_sha256: manifest_digest.sha256,
            result_bytes: result_digest.bytes,
            result_sha256: result_digest.sha256,
        })
    }

    /// Revalidates the durable burn and every caller-owned immutable input,
    /// then atomically renames the sealed candidate with `RENAME_NOREPLACE`.
    ///
    /// State was already appended and fsynced before this method can be called.
    /// Any failure or crash leaves the identity consumed and no success output.
    ///
    /// # Errors
    ///
    /// Returns the revalidation failure unchanged, or
    /// [`FailureCode::Publication`] if the candidate cannot be atomically
    /// published without overwrite.
    pub fn publish<F>(
        self,
        mut burn: DurablePromotionBurn,
        revalidate_all_inputs: F,
    ) -> PromotionResult<PublicationReceipt>
    where
        F: FnOnce() -> PromotionResult<()>,
    {
        if burn.transaction_identity() != &self.transaction
            || !self.transaction.eq(&burn.record().transaction_identity())
        {
            return Err(PromotionError::new(
                FailureCode::IdentityJoin,
                "publication document and durable state burn identify different transactions",
            ));
        }
        burn.revalidate()?;
        revalidate_all_inputs()?;
        require_exact_tree(
            &self.directory,
            &FileDigest {
                bytes: self.result_bytes,
                sha256: self.result_sha256.clone(),
            },
            &FileDigest {
                bytes: self.manifest_bytes,
                sha256: self.manifest_sha256.clone(),
            },
        )?;
        let now = Fingerprint::from_metadata(
            &self
                .directory
                .metadata()
                .map_err(|error| publication_error("cannot restat candidate", error))?,
        );
        if now != self.directory_fingerprint {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "sealed publication candidate changed before rename",
            ));
        }
        let parent_path_descriptor = open_absolute_directory(&self.parent_path)?;
        let parent_path_fingerprint = private_parent_fingerprint(&parent_path_descriptor)?;
        if !parent_path_fingerprint.same_object(&self.parent_fingerprint) {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "publication parent pathname no longer identifies the retained private parent",
            ));
        }
        require_missing(&self.parent, &self.output_name, "output directory")?;
        let temporary_path = open_directory_beneath(&self.parent, &self.temporary_name)?;
        let temporary_path_fingerprint = Fingerprint::from_metadata(
            &temporary_path
                .metadata()
                .map_err(|error| publication_error("cannot restat temporary path", error))?,
        );
        if temporary_path_fingerprint != self.directory_fingerprint {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "hidden temporary pathname was substituted before rename",
            ));
        }
        require_exact_tree(
            &temporary_path,
            &FileDigest {
                bytes: self.result_bytes,
                sha256: self.result_sha256.clone(),
            },
            &FileDigest {
                bytes: self.manifest_bytes,
                sha256: self.manifest_sha256.clone(),
            },
        )?;
        // The callback is a transitional boundary until the final evidence
        // combiner supplies a typed retained-input token. Revalidate private
        // state again after that arbitrary code and every other fallible
        // preflight, leaving no unchecked callback window before rename.
        burn.revalidate()?;
        renameat_with(
            &self.parent,
            self.temporary_name.as_str(),
            &self.parent,
            self.output_name.as_str(),
            RenameFlags::NOREPLACE,
        )
        .map_err(|error| publication_error("atomic no-replace publication failed", error))?;
        fsync(&self.parent)
            .map_err(|error| publication_error("cannot fsync published result parent", error))?;
        let parent_after = open_absolute_directory(&self.parent_path)?;
        if !private_parent_fingerprint(&parent_after)?.same_object(&self.parent_fingerprint) {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "publication parent pathname changed during atomic rename",
            ));
        }
        let published = open_directory_beneath(&self.parent, &self.output_name)?;
        let published_fingerprint = Fingerprint::from_metadata(
            &published
                .metadata()
                .map_err(|error| publication_error("cannot stat published result", error))?,
        );
        if !published_fingerprint.same_object(&self.directory_fingerprint)
            || published_fingerprint.mode & 0o777 != 0o500
        {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "published result does not name the sealed candidate object",
            ));
        }
        require_missing(
            &self.parent,
            &self.temporary_name,
            "renamed hidden publication candidate",
        )?;
        Ok(PublicationReceipt {
            output_path: self.output_path,
            manifest_bytes: self.manifest_bytes,
            manifest_sha256: self.manifest_sha256,
            promotion_journal_record_sha256: burn.record().record_sha256().to_owned(),
        })
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct FileDigest {
    bytes: u64,
    sha256: String,
}

fn write_exclusive(directory: &File, name: &str, bytes: &[u8]) -> PromotionResult<FileDigest> {
    validate_component(name)?;
    let descriptor = openat2(
        directory,
        name,
        OFlags::RDWR | OFlags::CREATE | OFlags::EXCL | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::RUSR | Mode::WUSR,
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| publication_error(&format!("cannot exclusively create {name}"), error))?;
    let mut file = File::from(descriptor);
    file.write_all(bytes)
        .map_err(|error| publication_error(&format!("cannot write {name}"), error))?;
    file.sync_all()
        .map_err(|error| publication_error(&format!("cannot fsync {name}"), error))?;
    let before = regular_file(&file, name)?;
    if before.bytes != u64::try_from(bytes.len()).expect("usize fits u64") {
        return Err(PromotionError::new(
            FailureCode::Publication,
            format!("exclusive file {name} has the wrong byte count"),
        ));
    }
    let observed = read_small_at(&file, before.bytes, name)?;
    if observed != bytes {
        return Err(PromotionError::new(
            FailureCode::Publication,
            format!("exclusive file {name} differs from supplied bytes"),
        ));
    }
    fchmod(&file, Mode::RUSR)
        .map_err(|error| publication_error(&format!("cannot set {name} mode 0400"), error))?;
    file.sync_all()
        .map_err(|error| publication_error(&format!("cannot fsync read-only {name}"), error))?;
    let after = regular_file(&file, name)?;
    if !after.same_object(&before) || after.mode & 0o777 != 0o400 {
        return Err(PromotionError::new(
            FailureCode::Publication,
            format!("exclusive file {name} identity or mode changed"),
        ));
    }
    fsync(directory)
        .map_err(|error| publication_error("cannot fsync candidate directory", error))?;
    Ok(FileDigest {
        bytes: before.bytes,
        sha256: sha256_hex(bytes),
    })
}

fn require_exact_tree(
    directory: &File,
    expected_result: &FileDigest,
    expected_manifest: &FileDigest,
) -> PromotionResult<()> {
    let scan_descriptor = openat2(
        directory,
        ".",
        OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| publication_error("cannot duplicate candidate descriptor", error))?;
    let mut buffer = [MaybeUninit::<u8>::uninit(); DIRECTORY_BUFFER_BYTES];
    let mut iterator = RawDir::new(scan_descriptor, &mut buffer);
    let mut names = BTreeSet::new();
    while let Some(entry) = iterator.next() {
        let entry = entry
            .map_err(|error| publication_error("cannot enumerate publication candidate", error))?;
        let raw = entry.file_name().to_bytes();
        if raw == b"." || raw == b".." {
            continue;
        }
        let name = std::str::from_utf8(raw).map_err(|error| {
            publication_error("publication candidate has a non-UTF-8 name", error)
        })?;
        validate_component(name)?;
        if !names.insert(name.to_owned()) {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "publication candidate contains a duplicate name",
            ));
        }
        let child = openat2(
            directory,
            name,
            OFlags::PATH | OFlags::CLOEXEC | OFlags::NOFOLLOW,
            Mode::empty(),
            ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
        )
        .map_err(|error| publication_error("cannot inspect candidate entry", error))?;
        let file = File::from(child);
        let metadata = file
            .metadata()
            .map_err(|error| publication_error("cannot stat candidate entry", error))?;
        if FileType::from_raw_mode(metadata.mode()) != FileType::RegularFile
            || metadata.nlink() != 1
            || metadata.mode() & 0o777 != 0o400
        {
            return Err(PromotionError::new(
                FailureCode::Publication,
                "publication candidate contains a symlink, special file, hard-link alias, or writable file",
            ));
        }
    }
    let expected = BTreeSet::from([RESULT_FILE.to_owned(), MANIFEST_FILE.to_owned()]);
    if names != expected {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication candidate file set is incomplete or has an extra entry",
        ));
    }
    for (name, expected_digest) in [
        (RESULT_FILE, expected_result),
        (MANIFEST_FILE, expected_manifest),
    ] {
        let descriptor = openat2(
            directory,
            name,
            OFlags::RDONLY | OFlags::CLOEXEC | OFlags::NOFOLLOW,
            Mode::empty(),
            ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
        )
        .map_err(|error| publication_error("cannot reopen sealed candidate file", error))?;
        let file = File::from(descriptor);
        let fingerprint = regular_file(&file, name)?;
        if fingerprint.bytes != expected_digest.bytes || fingerprint.mode & 0o777 != 0o400 {
            return Err(PromotionError::new(
                FailureCode::Publication,
                format!("sealed candidate file {name} changed size or mode"),
            ));
        }
        let bytes = read_small_at(&file, fingerprint.bytes, name)?;
        if sha256_hex(&bytes) != expected_digest.sha256 {
            return Err(PromotionError::new(
                FailureCode::Publication,
                format!("sealed candidate file {name} changed digest"),
            ));
        }
        let after = regular_file(&file, name)?;
        if after != fingerprint {
            return Err(PromotionError::new(
                FailureCode::Publication,
                format!("sealed candidate file {name} changed while revalidated"),
            ));
        }
    }
    Ok(())
}

fn read_small_at(file: &File, bytes: u64, label: &str) -> PromotionResult<Vec<u8>> {
    let length = usize::try_from(bytes).map_err(|error| {
        publication_error(&format!("{label} is too large for this host"), error)
    })?;
    let mut output = vec![0_u8; length];
    std::os::unix::fs::FileExt::read_exact_at(file, &mut output, 0)
        .map_err(|error| publication_error(&format!("cannot reread {label}"), error))?;
    Ok(output)
}

fn regular_file(file: &File, label: &str) -> PromotionResult<Fingerprint> {
    let metadata = file
        .metadata()
        .map_err(|error| publication_error(&format!("cannot stat {label}"), error))?;
    if !metadata.file_type().is_file() || metadata.nlink() != 1 {
        return Err(PromotionError::new(
            FailureCode::Publication,
            format!("{label} is not an unaliased regular file"),
        ));
    }
    Ok(Fingerprint::from_metadata(&metadata))
}

fn split_output_path(output: &Path) -> PromotionResult<(PathBuf, String)> {
    if !output.is_absolute() {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication output must be an absolute direct child path",
        ));
    }
    let parent = output.parent().ok_or_else(|| {
        PromotionError::new(FailureCode::Publication, "publication output has no parent")
    })?;
    let name = output
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| {
            PromotionError::new(
                FailureCode::Publication,
                "publication output name is not canonical UTF-8",
            )
        })?
        .to_owned();
    Ok((parent.to_owned(), name))
}

fn validate_absolute_output(output: &Path) -> PromotionResult<()> {
    let Some(value) = output.to_str() else {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication output must be canonical UTF-8",
        ));
    };
    let canonical = value.starts_with('/')
        && value.len() > 1
        && !value.ends_with('/')
        && !value.contains("//")
        && value
            .split('/')
            .skip(1)
            .all(|component| !component.is_empty() && component != "." && component != "..");
    if !canonical {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication output is not a traversal-free canonical absolute path",
        ));
    }
    Ok(())
}

fn validate_component(name: &str) -> PromotionResult<()> {
    let valid = !name.is_empty()
        && name != "."
        && name != ".."
        && name
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'));
    if !valid {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication path contains a non-canonical or traversal component",
        ));
    }
    Ok(())
}

fn open_absolute_directory(path: &Path) -> PromotionResult<File> {
    let descriptor = openat2(
        CWD,
        path,
        OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| publication_error("cannot securely open publication parent", error))?;
    Ok(File::from(descriptor))
}

fn private_parent_fingerprint(parent: &File) -> PromotionResult<Fingerprint> {
    let metadata = parent
        .metadata()
        .map_err(|error| publication_error("cannot stat publication parent", error))?;
    if !metadata.file_type().is_dir()
        || metadata.uid() != geteuid().as_raw()
        || metadata.mode() & 0o777 != 0o700
    {
        return Err(PromotionError::new(
            FailureCode::Publication,
            "publication parent must be a direct owner-only mode-0700 directory",
        ));
    }
    Ok(Fingerprint::from_metadata(&metadata))
}

fn open_directory_beneath(parent: &File, name: &str) -> PromotionResult<File> {
    validate_component(name)?;
    let descriptor = openat2(
        parent,
        name,
        OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| publication_error("cannot securely open publication child", error))?;
    Ok(File::from(descriptor))
}

fn require_missing(parent: &File, name: &str, label: &str) -> PromotionResult<()> {
    match openat2(
        parent,
        name,
        OFlags::PATH | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    ) {
        Err(Errno::NOENT) => Ok(()),
        Ok(_) => Err(PromotionError::new(
            FailureCode::Publication,
            format!("{label} already exists; overwrite is forbidden"),
        )),
        Err(error) => Err(publication_error(
            &format!("cannot safely inspect {label}"),
            error,
        )),
    }
}

fn publication_error(label: &str, error: impl std::fmt::Display) -> PromotionError {
    PromotionError::new(FailureCode::Publication, format!("{label}: {error}"))
}

#[cfg(test)]
mod tests {
    use super::{AtomicPublication, RESULT_FILE};
    use crate::journal::synthetic_identity;
    use crate::{
        FailureCode, PromotionDocument, PromotionError, PromotionFailure, burn_promotion_identity,
    };
    use std::fs;
    use std::os::unix::fs::{PermissionsExt, symlink};
    use std::path::{Path, PathBuf};
    use std::sync::atomic::{AtomicU64, Ordering};

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

    struct TestRoot(PathBuf);

    impl TestRoot {
        fn new() -> Self {
            let path = std::env::temp_dir().join(format!(
                "hashsigs-u280-promoter-{}-{}",
                std::process::id(),
                NEXT.fetch_add(1, Ordering::Relaxed)
            ));
            fs::create_dir(&path).unwrap();
            fs::set_permissions(&path, fs::Permissions::from_mode(0o700)).unwrap();
            Self(path)
        }
    }

    impl Drop for TestRoot {
        fn drop(&mut self) {
            make_writable(&self.0);
            let _ = fs::remove_dir_all(&self.0);
        }
    }

    fn make_writable(path: &Path) {
        let Ok(metadata) = fs::symlink_metadata(path) else {
            return;
        };
        if metadata.file_type().is_symlink() {
            let _ = fs::remove_file(path);
        } else if metadata.is_dir() {
            let _ = fs::set_permissions(path, fs::Permissions::from_mode(0o700));
            if let Ok(entries) = fs::read_dir(path) {
                for entry in entries.flatten() {
                    make_writable(&entry.path());
                }
            }
        } else {
            let _ = fs::set_permissions(path, fs::Permissions::from_mode(0o600));
        }
    }

    fn failure_document(identity: &crate::journal::PromotionIdentity) -> PromotionDocument {
        let error = PromotionError::new(FailureCode::RouteUnaccepted, "synthetic fixture");
        PromotionDocument::Failure(PromotionFailure::new(
            &identity.transaction_identity(),
            &error,
        ))
    }

    #[test]
    fn durable_burn_precedes_atomic_no_replace_publication() {
        let root = TestRoot::new();
        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("result");
        let identity = synthetic_identity(1);
        let document = failure_document(&identity);
        let candidate = AtomicPublication::prepare(&output, &document).unwrap();
        let burn = burn_promotion_identity(&state, &identity).unwrap();
        let receipt = candidate.publish(burn, || Ok(())).unwrap();
        assert_eq!(receipt.output_path(), output);
        assert!(output.join("SHA256SUMS").is_file());
        assert_eq!(
            AtomicPublication::prepare(&output, &document)
                .unwrap_err()
                .code(),
            FailureCode::Publication
        );
    }

    #[test]
    fn existing_symlink_and_late_hardlink_alias_are_rejected() {
        let root = TestRoot::new();
        let target = root.0.join("target");
        fs::create_dir(&target).unwrap();
        let symlink_output = root.0.join("symlink-output");
        symlink(&target, &symlink_output).unwrap();
        let identity = synthetic_identity(2);
        assert_eq!(
            AtomicPublication::prepare(&symlink_output, &failure_document(&identity))
                .unwrap_err()
                .code(),
            FailureCode::Publication
        );

        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("hardlink-output");
        let candidate = AtomicPublication::prepare(&output, &failure_document(&identity)).unwrap();
        let hidden = output
            .parent()
            .unwrap()
            .join(&candidate.temporary_name)
            .join(RESULT_FILE);
        fs::hard_link(&hidden, root.0.join("alias.json")).unwrap();
        let burn = burn_promotion_identity(&state, &identity).unwrap();
        assert_eq!(
            candidate.publish(burn, || Ok(())).unwrap_err().code(),
            FailureCode::Publication
        );
        assert!(!output.exists());
    }

    #[test]
    fn substituted_temporary_path_fails_with_no_final_output() {
        let root = TestRoot::new();
        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("substitution-output");
        let identity = synthetic_identity(3);
        let candidate = AtomicPublication::prepare(&output, &failure_document(&identity)).unwrap();
        let hidden = root.0.join(&candidate.temporary_name);
        let displaced = root.0.join("displaced-candidate");
        fs::rename(&hidden, &displaced).unwrap();
        fs::create_dir(&hidden).unwrap();
        fs::set_permissions(&hidden, fs::Permissions::from_mode(0o500)).unwrap();
        let burn = burn_promotion_identity(&state, &identity).unwrap();
        assert_eq!(
            candidate.publish(burn, || Ok(())).unwrap_err().code(),
            FailureCode::Publication
        );
        assert!(!output.exists());
    }

    #[test]
    fn cross_run_document_and_burn_are_rejected_before_rename() {
        let root = TestRoot::new();
        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("cross-run-output");
        let document_identity = synthetic_identity(4);
        let burn_identity = synthetic_identity(5);
        let candidate =
            AtomicPublication::prepare(&output, &failure_document(&document_identity)).unwrap();
        let burn = burn_promotion_identity(&state, &burn_identity).unwrap();
        assert_eq!(
            candidate.publish(burn, || Ok(())).unwrap_err().code(),
            FailureCode::IdentityJoin
        );
        assert!(!output.exists());
    }

    #[test]
    fn renamed_state_path_invalidates_durable_token_before_publication() {
        let root = TestRoot::new();
        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("state-rename-output");
        let identity = synthetic_identity(6);
        let candidate = AtomicPublication::prepare(&output, &failure_document(&identity)).unwrap();
        let burn = burn_promotion_identity(&state, &identity).unwrap();
        fs::rename(&state, root.0.join("displaced-state")).unwrap();
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        assert_eq!(
            candidate.publish(burn, || Ok(())).unwrap_err().code(),
            FailureCode::StateBurn
        );
        assert!(!output.exists());
    }

    #[test]
    fn state_replacement_inside_input_callback_is_caught_before_rename() {
        let root = TestRoot::new();
        let state = root.0.join("state");
        fs::create_dir(&state).unwrap();
        fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
        let output = root.0.join("callback-state-replacement-output");
        let identity = synthetic_identity(7);
        let candidate = AtomicPublication::prepare(&output, &failure_document(&identity)).unwrap();
        let burn = burn_promotion_identity(&state, &identity).unwrap();
        let displaced = root.0.join("callback-displaced-state");
        assert_eq!(
            candidate
                .publish(burn, || {
                    fs::rename(&state, &displaced).unwrap();
                    fs::create_dir(&state).unwrap();
                    fs::set_permissions(&state, fs::Permissions::from_mode(0o700)).unwrap();
                    Ok(())
                })
                .unwrap_err()
                .code(),
            FailureCode::StateBurn
        );
        assert!(!output.exists());
    }
}