u280_hardware_promoter/

coordination.rs

//! Complete canonical Phase-B coordination burn-chain verification.

use crate::canonical::{canonical_line, hex_lower, is_lower_hex, parse_canonical_line, sha256_hex};
use crate::model::RequestFileLocator;
use crate::{FailureCode, PromotionError, PromotionRequest, PromotionResult};
use rustix::fs::{CWD, Mode, OFlags, ResolveFlags, openat2};
use rustix::process::geteuid;
use serde::{Deserialize, Serialize};
use sha2::{Digest as _, Sha256};
use std::collections::BTreeSet;
use std::fs::{File, Metadata};
use std::os::unix::fs::{FileExt as _, MetadataExt as _};
use std::path::{Component, Path, PathBuf};

const BURN_SCHEMA: u64 = 1;
const BURN_CONTRACT: &str = "hashsigs-u280-phase-b-coordination-burn-v1";
const GENESIS_SHA256: &str = "0000000000000000000000000000000000000000000000000000000000000000";
const PROJECT_LEDGER: &str = "hashsigs-project-coordination";
const ED25519_LEDGER: &str = "ed25519-agent-coordination";
const MAXIMUM_HISTORY_BYTES: usize = 64 * 1024 * 1024;
const MAXIMUM_RECORD_BYTES: usize = 64 * 1024;
const MAXIMUM_MANIFEST_BYTES: u64 = 64 * 1024;
pub(crate) const MAXIMUM_COORDINATION_INTENT_BYTES: u64 = 64 * 1024;

#[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(deny_unknown_fields)]
struct CoordinationGrantWire {
    ledger_id: String,
    entry_id: String,
    entry_bytes: u64,
    entry_sha256: String,
}

impl CoordinationGrantWire {
    fn validate(&self, expected_ledger: &str) -> PromotionResult<()> {
        let canonical_id = !self.entry_id.is_empty()
            && self.entry_id.len() <= 128
            && self.entry_id.bytes().all(|byte| {
                byte.is_ascii_lowercase()
                    || byte.is_ascii_digit()
                    || matches!(byte, b'.' | b'_' | b':' | b'-')
            });
        if self.ledger_id != expected_ledger
            || !canonical_id
            || self.entry_bytes == 0
            || !is_lower_hex(&self.entry_sha256, 64, true)
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "coordination grant binding is non-canonical or out of order",
            ));
        }
        Ok(())
    }
}
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct IntentBinding {
    bytes: u64,
    sha256: String,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct CoordinationBurnWire {
    schema: u64,
    contract: String,
    sequence: u64,
    run_id: String,
    intent: IntentBinding,
    grants: Vec<CoordinationGrantWire>,
    previous_sha256: String,
    record_sha256: String,
}

impl CoordinationBurnWire {
    fn validate_shape(&self) -> PromotionResult<()> {
        if self.schema != BURN_SCHEMA
            || self.contract != BURN_CONTRACT
            || !is_lower_hex(&self.run_id, 32, true)
            || self.intent.bytes == 0
            || self.intent.bytes > MAXIMUM_COORDINATION_INTENT_BYTES
            || !is_lower_hex(&self.intent.sha256, 64, false)
            || self.grants.len() != 2
            || !is_lower_hex(&self.previous_sha256, 64, false)
            || !is_lower_hex(&self.record_sha256, 64, false)
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "coordination burn record has a non-canonical shape",
            ));
        }
        self.grants[0].validate(PROJECT_LEDGER)?;
        self.grants[1].validate(ED25519_LEDGER)?;
        if self.grants[0].entry_id == self.grants[1].entry_id {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "the two coordination grant entry identifiers must differ",
            ));
        }
        Ok(())
    }

    fn recomputed_record_sha256(&self) -> PromotionResult<String> {
        let grants = self
            .grants
            .iter()
            .map(|grant| {
                CoordinationBurnGrantHashInput::new(
                    &grant.ledger_id,
                    &grant.entry_id,
                    grant.entry_bytes,
                    &grant.entry_sha256,
                )
            })
            .collect::<Vec<_>>();
        recompute_coordination_burn_record_sha256(
            self.sequence,
            &self.run_id,
            self.intent.bytes,
            &self.intent.sha256,
            &grants,
            &self.previous_sha256,
        )
    }
}

#[derive(Serialize)]
struct CoordinationBurnHashBody<'a> {
    schema: u64,
    contract: &'static str,
    sequence: u64,
    run_id: &'a str,
    intent: CoordinationBurnIntentHashInput<'a>,
    grants: &'a [CoordinationBurnGrantHashInput],
    previous_sha256: &'a str,
}

#[derive(Serialize)]
struct CoordinationBurnIntentHashInput<'a> {
    bytes: u64,
    sha256: &'a str,
}

#[derive(Serialize)]
pub(crate) struct CoordinationBurnGrantHashInput {
    ledger_id: String,
    entry_id: String,
    entry_bytes: u64,
    entry_sha256: String,
}

impl CoordinationBurnGrantHashInput {
    pub(crate) fn new(
        ledger_id: &str,
        entry_id: &str,
        entry_bytes: u64,
        entry_sha256: &str,
    ) -> Self {
        Self {
            ledger_id: ledger_id.to_owned(),
            entry_id: entry_id.to_owned(),
            entry_bytes,
            entry_sha256: entry_sha256.to_owned(),
        }
    }
}

pub(crate) fn recompute_coordination_burn_record_sha256(
    sequence: u64,
    run_id: &str,
    intent_bytes: u64,
    intent_sha256: &str,
    grants: &[CoordinationBurnGrantHashInput],
    previous_sha256: &str,
) -> PromotionResult<String> {
    let body = CoordinationBurnHashBody {
        schema: BURN_SCHEMA,
        contract: BURN_CONTRACT,
        sequence,
        run_id,
        intent: CoordinationBurnIntentHashInput {
            bytes: intent_bytes,
            sha256: intent_sha256,
        },
        grants,
        previous_sha256,
    };
    let mut canonical = canonical_line(&body)?;
    let newline = canonical.pop();
    debug_assert_eq!(newline, Some(b'\n'));
    Ok(sha256_hex(&canonical))
}

/// One grant binding proven by a complete canonical coordination history.
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct VerifiedCoordinationGrant {
    ledger_id: String,
    entry_id: String,
    entry_bytes: u64,
    entry_sha256: String,
}

impl VerifiedCoordinationGrant {
    /// Stable ledger identifier.
    #[must_use]
    pub fn ledger_id(&self) -> &str {
        &self.ledger_id
    }

    /// Immutable grant entry identifier.
    #[must_use]
    pub fn entry_id(&self) -> &str {
        &self.entry_id
    }

    /// Exact byte count of the immutable grant entry.
    #[must_use]
    pub const fn entry_bytes(&self) -> u64 {
        self.entry_bytes
    }

    /// Immutable grant entry SHA-256.
    #[must_use]
    pub fn entry_sha256(&self) -> &str {
        &self.entry_sha256
    }
}

/// Opaque selected burn proven to be the exact last record and receipt for the
/// requested run. It has no serde implementation or public constructor.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VerifiedCoordinationBurn {
    sequence: u64,
    run_id: String,
    intent_bytes: u64,
    intent_sha256: String,
    grants: Vec<VerifiedCoordinationGrant>,
    previous_sha256: String,
    record_sha256: String,
}

impl VerifiedCoordinationBurn {
    /// Zero-based position in the complete history.
    #[must_use]
    pub const fn sequence(&self) -> u64 {
        self.sequence
    }

    /// Phase-B run identity bound to the selected receipt.
    #[must_use]
    pub fn run_id(&self) -> &str {
        &self.run_id
    }

    /// Exact byte count of the canonical coordination intent.
    #[must_use]
    pub const fn intent_bytes(&self) -> u64 {
        self.intent_bytes
    }

    /// SHA-256 of the canonical coordination intent.
    #[must_use]
    pub fn intent_sha256(&self) -> &str {
        &self.intent_sha256
    }

    /// Ordered immutable grant bindings.
    #[must_use]
    pub fn grants(&self) -> &[VerifiedCoordinationGrant] {
        &self.grants
    }

    /// Previous coordination burn-record SHA-256.
    #[must_use]
    pub fn previous_sha256(&self) -> &str {
        &self.previous_sha256
    }

    /// SHA-256 of this record's canonical body.
    #[must_use]
    pub fn record_sha256(&self) -> &str {
        &self.record_sha256
    }
}

impl From<CoordinationBurnWire> for VerifiedCoordinationBurn {
    fn from(wire: CoordinationBurnWire) -> Self {
        Self {
            sequence: wire.sequence,
            run_id: wire.run_id,
            intent_bytes: wire.intent.bytes,
            intent_sha256: wire.intent.sha256,
            grants: wire
                .grants
                .into_iter()
                .map(|grant| VerifiedCoordinationGrant {
                    ledger_id: grant.ledger_id,
                    entry_id: grant.entry_id,
                    entry_bytes: grant.entry_bytes,
                    entry_sha256: grant.entry_sha256,
                })
                .collect(),
            previous_sha256: wire.previous_sha256,
            record_sha256: wire.record_sha256,
        }
    }
}

/// Verified global replay index for one complete genesis-rooted snapshot.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct CoordinationChain {
    records: u64,
    selected_burn: VerifiedCoordinationBurn,
    run_ids: BTreeSet<String>,
    intent_sha256s: BTreeSet<String>,
    grant_replay_keys: BTreeSet<(String, String, String)>,
    exact_grant_bindings: BTreeSet<(String, String, u64, String)>,
}

impl CoordinationChain {
    /// Number of contiguous records, including the selected last burn.
    #[must_use]
    pub const fn records(&self) -> u64 {
        self.records
    }

    /// Exact last history record, run binding, and selected receipt.
    #[must_use]
    pub const fn selected_burn(&self) -> &VerifiedCoordinationBurn {
        &self.selected_burn
    }

    /// Reports whether a run identity already exists anywhere in the history.
    #[must_use]
    pub fn contains_run_id(&self, run_id: &str) -> bool {
        self.run_ids.contains(run_id)
    }

    /// Reports whether an intent digest already exists anywhere in the history.
    #[must_use]
    pub fn contains_intent_sha256(&self, sha256: &str) -> bool {
        self.intent_sha256s.contains(sha256)
    }

    /// Reports whether an exact ledger/entry/digest triple was already burned.
    #[must_use]
    pub fn contains_grant(&self, ledger_id: &str, entry_id: &str, entry_sha256: &str) -> bool {
        self.grant_replay_keys.contains(&(
            ledger_id.to_owned(),
            entry_id.to_owned(),
            entry_sha256.to_owned(),
        ))
    }

    /// Reports whether an exact ledger/entry/byte-count/digest tuple was burned.
    #[must_use]
    pub fn contains_exact_grant(
        &self,
        ledger_id: &str,
        entry_id: &str,
        entry_bytes: u64,
        entry_sha256: &str,
    ) -> bool {
        self.exact_grant_bindings.contains(&(
            ledger_id.to_owned(),
            entry_id.to_owned(),
            entry_bytes,
            entry_sha256.to_owned(),
        ))
    }
}

struct CoordinationChainBuilder {
    expected_sequence: u64,
    previous: String,
    run_ids: BTreeSet<String>,
    intents: BTreeSet<String>,
    grant_replay_keys: BTreeSet<(String, String, String)>,
    exact_grant_bindings: BTreeSet<(String, String, u64, String)>,
    last_record: Option<CoordinationBurnWire>,
    last_line: Vec<u8>,
}

impl CoordinationChainBuilder {
    fn new() -> Self {
        Self {
            expected_sequence: 0,
            previous: GENESIS_SHA256.to_owned(),
            run_ids: BTreeSet::new(),
            intents: BTreeSet::new(),
            grant_replay_keys: BTreeSet::new(),
            exact_grant_bindings: BTreeSet::new(),
            last_record: None,
            last_line: Vec::new(),
        }
    }

    fn push(&mut self, line: &[u8]) -> PromotionResult<()> {
        let record: CoordinationBurnWire =
            parse_canonical_line(line, MAXIMUM_RECORD_BYTES, "coordination burn record").map_err(
                |error| PromotionError::new(FailureCode::CoordinationChain, error.to_string()),
            )?;
        record.validate_shape()?;
        if record.sequence != self.expected_sequence
            || record.previous_sha256 != self.previous
            || record.recomputed_record_sha256()? != record.record_sha256
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "coordination history is not one contiguous recomputed genesis chain",
            ));
        }
        if !self.run_ids.insert(record.run_id.clone())
            || !self.intents.insert(record.intent.sha256.clone())
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationReplay,
                "coordination history repeats a run ID or intent digest",
            ));
        }
        for grant in &record.grants {
            if !self.grant_replay_keys.insert((
                grant.ledger_id.clone(),
                grant.entry_id.clone(),
                grant.entry_sha256.clone(),
            )) {
                return Err(PromotionError::new(
                    FailureCode::CoordinationReplay,
                    "coordination history repeats a ledger grant binding",
                ));
            }
            let inserted = self.exact_grant_bindings.insert((
                grant.ledger_id.clone(),
                grant.entry_id.clone(),
                grant.entry_bytes,
                grant.entry_sha256.clone(),
            ));
            debug_assert!(inserted);
        }
        self.expected_sequence = self.expected_sequence.checked_add(1).ok_or_else(|| {
            PromotionError::new(
                FailureCode::CoordinationChain,
                "coordination history sequence overflow",
            )
        })?;
        self.previous.clone_from(&record.record_sha256);
        self.last_line.clear();
        self.last_line.extend_from_slice(line);
        self.last_record = Some(record);
        Ok(())
    }

    fn finish(
        self,
        expected_run_id: &str,
        selected_wire: CoordinationBurnWire,
        selected_receipt: &[u8],
    ) -> PromotionResult<CoordinationChain> {
        let Some(last_record) = self.last_record else {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "coordination history contains no canonical burn record",
            ));
        };
        if last_record != selected_wire
            || last_record.run_id.as_str() != expected_run_id
            || self.last_line != selected_receipt
            || canonical_line(&last_record)? != selected_receipt
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationChain,
                "selected burn receipt is not the exact last record for the requested run",
            ));
        }
        Ok(CoordinationChain {
            records: self.expected_sequence,
            selected_burn: last_record.into(),
            run_ids: self.run_ids,
            intent_sha256s: self.intents,
            grant_replay_keys: self.grant_replay_keys,
            exact_grant_bindings: self.exact_grant_bindings,
        })
    }
}

fn parse_selected_receipt(bytes: &[u8]) -> PromotionResult<CoordinationBurnWire> {
    let selected: CoordinationBurnWire = parse_canonical_line(
        bytes,
        MAXIMUM_RECORD_BYTES,
        "selected coordination burn receipt",
    )
    .map_err(|error| PromotionError::new(FailureCode::CoordinationChain, error.to_string()))?;
    selected.validate_shape()?;
    Ok(selected)
}

/// Exact locator and immutable byte binding supplied by the request model.
///
/// This is only an integration seam. It is not evidence until consumed by
/// [`retain_verified_coordination_snapshot`].
#[derive(Debug, Eq, PartialEq)]
struct CoordinationFileBinding {
    absolute_path: PathBuf,
    bytes: u64,
    sha256: String,
}

impl CoordinationFileBinding {
    fn from_request_locator(locator: &RequestFileLocator<'_>) -> Self {
        Self {
            absolute_path: PathBuf::from(locator.absolute_path()),
            bytes: locator.bytes(),
            sha256: locator.sha256().to_owned(),
        }
    }
}

/// The three files making one closed coordination snapshot.
///
/// All three request paths must be direct children of the same immutable root.
/// Deriving that root from the locators prevents an adapter from silently
/// treating unrelated parent directories as one snapshot.
#[derive(Debug, Eq, PartialEq)]
struct CoordinationSnapshotBinding {
    root: PathBuf,
    history: CoordinationFileBinding,
    manifest: CoordinationFileBinding,
    selected_receipt: CoordinationFileBinding,
}

impl CoordinationSnapshotBinding {
    fn from_request(request: &PromotionRequest) -> PromotionResult<Self> {
        let locators = request.coordination_locators();
        Self::from_direct_children(
            CoordinationFileBinding::from_request_locator(
                locators.complete_burn_history_snapshot(),
            ),
            CoordinationFileBinding::from_request_locator(locators.history_snapshot_manifest()),
            CoordinationFileBinding::from_request_locator(locators.selected_burn_receipt()),
        )
    }

    fn from_direct_children(
        history: CoordinationFileBinding,
        manifest: CoordinationFileBinding,
        selected_receipt: CoordinationFileBinding,
    ) -> PromotionResult<Self> {
        let root = history
            .absolute_path
            .parent()
            .ok_or_else(|| {
                coordination_error("coordination history has no absolute parent directory")
            })?
            .to_owned();
        if manifest.absolute_path.parent() != Some(root.as_path())
            || selected_receipt.absolute_path.parent() != Some(root.as_path())
        {
            return Err(coordination_error(
                "coordination snapshot inputs do not share one direct parent",
            ));
        }
        Ok(Self {
            root,
            history,
            manifest,
            selected_receipt,
        })
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct SnapshotFingerprint {
    dev: u64,
    ino: u64,
    mode: u32,
    uid: u32,
    nlink: u64,
    bytes: u64,
    blocks: u64,
    mtime: i64,
    mtime_nsec: i64,
    ctime: i64,
    ctime_nsec: i64,
}

impl SnapshotFingerprint {
    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(),
            blocks: metadata.blocks(),
            mtime: metadata.mtime(),
            mtime_nsec: metadata.mtime_nsec(),
            ctime: metadata.ctime(),
            ctime_nsec: metadata.ctime_nsec(),
        }
    }

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

#[derive(Debug)]
struct RetainedCoordinationFile {
    relative: String,
    file: File,
    fingerprint: SnapshotFingerprint,
    binding: CoordinationFileBinding,
}

/// Descriptor-retained proof of one complete coordination snapshot.
///
/// The type deliberately implements neither `Clone` nor serde. A digest-only
/// copy cannot stand in for the retained root and file descriptors.
#[derive(Debug)]
pub(crate) struct VerifiedCoordinationSnapshot {
    expected_run_id: String,
    root_path: PathBuf,
    root: File,
    root_fingerprint: SnapshotFingerprint,
    history: RetainedCoordinationFile,
    manifest: RetainedCoordinationFile,
    selected_receipt: RetainedCoordinationFile,
    chain: CoordinationChain,
}

#[allow(dead_code)] // Remaining accessors belong to the future complete evidence combiner.
impl VerifiedCoordinationSnapshot {
    #[must_use]
    pub(crate) const fn chain(&self) -> &CoordinationChain {
        &self.chain
    }

    #[must_use]
    pub(crate) const fn selected_burn(&self) -> &VerifiedCoordinationBurn {
        self.chain.selected_burn()
    }

    #[must_use]
    pub(crate) fn root(&self) -> &Path {
        &self.root_path
    }

    #[must_use]
    pub(crate) fn history_binding(&self) -> (u64, &str) {
        (self.history.binding.bytes, &self.history.binding.sha256)
    }

    #[must_use]
    pub(crate) fn manifest_binding(&self) -> (u64, &str) {
        (self.manifest.binding.bytes, &self.manifest.binding.sha256)
    }

    #[must_use]
    pub(crate) fn selected_receipt_binding(&self) -> (u64, &str) {
        (
            self.selected_receipt.binding.bytes,
            &self.selected_receipt.binding.sha256,
        )
    }

    /// Re-hashes and reparses all retained inputs, proving that both their
    /// descriptors and descriptor-rooted pathnames still name the snapshot.
    pub(crate) fn revalidate(&self) -> PromotionResult<()> {
        revalidate_root_path(&self.root_path, &self.root, &self.root_fingerprint)?;
        revalidate_retained_file(&self.root, &self.history)?;
        revalidate_retained_file(&self.root, &self.manifest)?;
        revalidate_retained_file(&self.root, &self.selected_receipt)?;

        let manifest = read_small_retained(&self.manifest, MAXIMUM_MANIFEST_BYTES)?;
        let selected = read_small_retained(
            &self.selected_receipt,
            u64::try_from(MAXIMUM_RECORD_BYTES).expect("record bound fits u64"),
        )?;
        verify_history_manifest(&manifest, &self.history)?;
        let reparsed = verify_streaming_history(&self.history, &selected, &self.expected_run_id)?;
        if reparsed != self.chain {
            return Err(coordination_error(
                "coordination snapshot proof changed during final revalidation",
            ));
        }

        revalidate_retained_file(&self.root, &self.history)?;
        revalidate_retained_file(&self.root, &self.manifest)?;
        revalidate_retained_file(&self.root, &self.selected_receipt)?;
        revalidate_root_path(&self.root_path, &self.root, &self.root_fingerprint)
    }
}

/// Securely opens, consumes, and retains a complete coordination snapshot.
/// The only locator source is the validated request; callers cannot inject a
/// parallel path, length, digest, or run identity.
///
/// # Errors
///
/// Returns [`FailureCode::CoordinationChain`] for an insecure or mutable path,
/// a malformed manifest, any byte-binding mismatch, or an invalid burn chain.
#[allow(dead_code)] // Called only by the future complete evidence combiner.
pub(crate) fn retain_verified_coordination_snapshot(
    request: &PromotionRequest,
) -> PromotionResult<VerifiedCoordinationSnapshot> {
    let expected_run_id = request.run_id();
    let binding = CoordinationSnapshotBinding::from_request(request)?;
    if !is_lower_hex(expected_run_id, 32, true) {
        return Err(coordination_error(
            "coordination snapshot expected run ID is non-canonical",
        ));
    }
    validate_absolute_path(&binding.root, "coordination snapshot root")?;
    validate_file_binding(
        &binding.root,
        &binding.history,
        u64::try_from(MAXIMUM_HISTORY_BYTES).expect("history bound fits u64"),
        "coordination history",
    )?;
    validate_file_binding(
        &binding.root,
        &binding.manifest,
        MAXIMUM_MANIFEST_BYTES,
        "coordination history manifest",
    )?;
    validate_file_binding(
        &binding.root,
        &binding.selected_receipt,
        u64::try_from(MAXIMUM_RECORD_BYTES).expect("record bound fits u64"),
        "selected coordination receipt",
    )?;
    if binding.history.absolute_path == binding.manifest.absolute_path
        || binding.history.absolute_path == binding.selected_receipt.absolute_path
        || binding.manifest.absolute_path == binding.selected_receipt.absolute_path
    {
        return Err(coordination_error(
            "coordination snapshot inputs must have three distinct pathnames",
        ));
    }

    let (root, root_fingerprint) = open_immutable_root(&binding.root)?;
    revalidate_root_path(&binding.root, &root, &root_fingerprint)?;
    let history = open_retained_file(&root, binding.history, "coordination history")?;
    let manifest = open_retained_file(&root, binding.manifest, "coordination history manifest")?;
    let selected_receipt = open_retained_file(
        &root,
        binding.selected_receipt,
        "selected coordination receipt",
    )?;
    if history.fingerprint.same_object(&manifest.fingerprint)
        || history
            .fingerprint
            .same_object(&selected_receipt.fingerprint)
        || manifest
            .fingerprint
            .same_object(&selected_receipt.fingerprint)
    {
        return Err(coordination_error(
            "coordination snapshot inputs alias one retained file object",
        ));
    }

    let manifest_bytes = read_small_retained(&manifest, MAXIMUM_MANIFEST_BYTES)?;
    let selected_bytes = read_small_retained(
        &selected_receipt,
        u64::try_from(MAXIMUM_RECORD_BYTES).expect("record bound fits u64"),
    )?;
    verify_history_manifest(&manifest_bytes, &history)?;
    let chain = verify_streaming_history(&history, &selected_bytes, expected_run_id)?;
    revalidate_root_path(&binding.root, &root, &root_fingerprint)?;

    let snapshot = VerifiedCoordinationSnapshot {
        expected_run_id: expected_run_id.to_owned(),
        root_path: binding.root,
        root,
        root_fingerprint,
        history,
        manifest,
        selected_receipt,
        chain,
    };
    snapshot.revalidate()?;
    Ok(snapshot)
}

fn validate_file_binding(
    root: &Path,
    binding: &CoordinationFileBinding,
    maximum_bytes: u64,
    label: &str,
) -> PromotionResult<()> {
    validate_absolute_path(&binding.absolute_path, label)?;
    let _ = direct_child_name(root, &binding.absolute_path, label)?;
    if binding.bytes == 0
        || binding.bytes > maximum_bytes
        || !is_lower_hex(&binding.sha256, 64, false)
    {
        return Err(coordination_error(format!(
            "{label} binding is empty, oversized, or has a non-canonical SHA-256"
        )));
    }
    Ok(())
}

fn validate_absolute_path(path: &Path, label: &str) -> PromotionResult<()> {
    let Some(text) = path.to_str() else {
        return Err(coordination_error(format!("{label} path is not UTF-8")));
    };
    let canonical = text.starts_with('/')
        && text.len() > 1
        && !text.ends_with('/')
        && !text.contains("//")
        && !text.contains('\0')
        && path
            .components()
            .all(|component| matches!(component, Component::RootDir | Component::Normal(_)));
    if !canonical {
        return Err(coordination_error(format!(
            "{label} is not a traversal-free canonical absolute path"
        )));
    }
    Ok(())
}

fn direct_child_name(root: &Path, path: &Path, label: &str) -> PromotionResult<String> {
    let relative = path
        .strip_prefix(root)
        .map_err(|_| coordination_error(format!("{label} is not beneath the snapshot root")))?;
    let mut components = relative.components();
    let Some(Component::Normal(name)) = components.next() else {
        return Err(coordination_error(format!(
            "{label} is not a direct snapshot child"
        )));
    };
    if components.next().is_some() {
        return Err(coordination_error(format!(
            "{label} is not a direct snapshot child"
        )));
    }
    let name = name
        .to_str()
        .ok_or_else(|| coordination_error(format!("{label} basename is not UTF-8")))?;
    if name.is_empty()
        || name.contains('/')
        || name.contains('\0')
        || name.contains('\n')
        || name.contains('\r')
    {
        return Err(coordination_error(format!(
            "{label} basename is non-canonical"
        )));
    }
    Ok(name.to_owned())
}

fn open_immutable_root(path: &Path) -> PromotionResult<(File, SnapshotFingerprint)> {
    let descriptor = openat2(
        CWD,
        path,
        OFlags::RDONLY | OFlags::DIRECTORY | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| coordination_error(format!("cannot securely open snapshot root: {error}")))?;
    let root = File::from(descriptor);
    let metadata = root
        .metadata()
        .map_err(|error| coordination_error(format!("cannot stat snapshot root: {error}")))?;
    if !metadata.file_type().is_dir()
        || metadata.uid() != geteuid().as_raw()
        || metadata.mode() & 0o222 != 0
    {
        return Err(coordination_error(
            "coordination snapshot root must be owner-retained and non-writable",
        ));
    }
    Ok((root, SnapshotFingerprint::from_metadata(&metadata)))
}

fn open_retained_file(
    root: &File,
    binding: CoordinationFileBinding,
    label: &str,
) -> PromotionResult<RetainedCoordinationFile> {
    let root_path = binding
        .absolute_path
        .parent()
        .ok_or_else(|| coordination_error(format!("{label} has no snapshot parent")))?;
    let relative = direct_child_name(root_path, &binding.absolute_path, label)?;
    let descriptor = openat2(
        root,
        relative.as_str(),
        OFlags::RDONLY | OFlags::NONBLOCK | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| coordination_error(format!("cannot securely open {label}: {error}")))?;
    let file = File::from(descriptor);
    let fingerprint = immutable_file_fingerprint(&file, label)?;
    if fingerprint.bytes != binding.bytes {
        return Err(coordination_error(format!(
            "{label} descriptor length differs from its request binding"
        )));
    }
    Ok(RetainedCoordinationFile {
        relative,
        file,
        fingerprint,
        binding,
    })
}

fn immutable_file_fingerprint(file: &File, label: &str) -> PromotionResult<SnapshotFingerprint> {
    let metadata = file
        .metadata()
        .map_err(|error| coordination_error(format!("cannot stat {label}: {error}")))?;
    let allocated = metadata.blocks().saturating_mul(512);
    if !metadata.file_type().is_file()
        || metadata.nlink() != 1
        || metadata.uid() != geteuid().as_raw()
        || metadata.mode() & 0o222 != 0
        || metadata.size() == 0
        || allocated < metadata.size()
    {
        return Err(coordination_error(format!(
            "{label} must be a nonempty, non-sparse, unaliased, owner-retained, non-writable regular file"
        )));
    }
    Ok(SnapshotFingerprint::from_metadata(&metadata))
}

fn revalidate_root_path(
    root_path: &Path,
    root: &File,
    expected: &SnapshotFingerprint,
) -> PromotionResult<()> {
    let descriptor_metadata = root
        .metadata()
        .map_err(|error| coordination_error(format!("cannot restat snapshot root: {error}")))?;
    let descriptor_fingerprint = SnapshotFingerprint::from_metadata(&descriptor_metadata);
    if descriptor_fingerprint != *expected {
        return Err(coordination_error(
            "coordination snapshot root descriptor changed",
        ));
    }
    let (path_root, path_fingerprint) = open_immutable_root(root_path)?;
    drop(path_root);
    if path_fingerprint != *expected {
        return Err(coordination_error(
            "coordination snapshot root pathname changed",
        ));
    }
    Ok(())
}

fn revalidate_retained_file(
    root: &File,
    retained: &RetainedCoordinationFile,
) -> PromotionResult<()> {
    let descriptor_fingerprint = immutable_file_fingerprint(&retained.file, &retained.relative)?;
    if descriptor_fingerprint != retained.fingerprint {
        return Err(coordination_error(format!(
            "retained coordination file descriptor changed: {}",
            retained.relative
        )));
    }
    let descriptor = openat2(
        root,
        retained.relative.as_str(),
        OFlags::RDONLY | OFlags::NONBLOCK | OFlags::CLOEXEC | OFlags::NOFOLLOW,
        Mode::empty(),
        ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS | ResolveFlags::NO_MAGICLINKS,
    )
    .map_err(|error| {
        coordination_error(format!(
            "cannot reopen retained coordination path {}: {error}",
            retained.relative
        ))
    })?;
    let path_file = File::from(descriptor);
    let path_fingerprint = immutable_file_fingerprint(&path_file, &retained.relative)?;
    if path_fingerprint != retained.fingerprint {
        return Err(coordination_error(format!(
            "coordination pathname no longer identifies its retained file: {}",
            retained.relative
        )));
    }
    Ok(())
}

fn read_small_retained(
    retained: &RetainedCoordinationFile,
    maximum_bytes: u64,
) -> PromotionResult<Vec<u8>> {
    if retained.fingerprint.bytes > maximum_bytes {
        return Err(coordination_error(format!(
            "retained coordination file exceeds its strict bound: {}",
            retained.relative
        )));
    }
    let capacity = usize::try_from(retained.fingerprint.bytes).map_err(|_| {
        coordination_error(format!(
            "retained coordination file is too large for this host: {}",
            retained.relative
        ))
    })?;
    let mut bytes = vec![0_u8; capacity];
    retained
        .file
        .read_exact_at(&mut bytes, 0)
        .map_err(|error| {
            coordination_error(format!(
                "cannot read retained coordination file {}: {error}",
                retained.relative
            ))
        })?;
    let mut extra = [0_u8; 1];
    if retained
        .file
        .read_at(&mut extra, retained.fingerprint.bytes)
        .map_err(|error| {
            coordination_error(format!(
                "cannot check retained coordination EOF {}: {error}",
                retained.relative
            ))
        })?
        != 0
        || immutable_file_fingerprint(&retained.file, &retained.relative)? != retained.fingerprint
        || sha256_hex(&bytes) != retained.binding.sha256
    {
        return Err(coordination_error(format!(
            "retained coordination file changed or differs from its binding: {}",
            retained.relative
        )));
    }
    Ok(bytes)
}

fn verify_history_manifest(
    bytes: &[u8],
    history: &RetainedCoordinationFile,
) -> PromotionResult<()> {
    if bytes.is_empty() || bytes.last() != Some(&b'\n') || !bytes.is_ascii() {
        return Err(coordination_error(
            "coordination history manifest is empty, truncated, or non-ASCII",
        ));
    }
    let body = &bytes[..bytes.len() - 1];
    if body.contains(&b'\n')
        || body.len() != 66_usize.saturating_add(history.relative.len())
        || body.get(64..66) != Some(&b"  "[..])
        || body.get(..64) != Some(history.binding.sha256.as_bytes())
        || body.get(66..) != Some(history.relative.as_bytes())
    {
        return Err(coordination_error(
            "coordination history manifest does not contain the exact sole history binding",
        ));
    }
    Ok(())
}

fn verify_streaming_history(
    history: &RetainedCoordinationFile,
    selected_receipt: &[u8],
    expected_run_id: &str,
) -> PromotionResult<CoordinationChain> {
    let selected_wire = parse_selected_receipt(selected_receipt)?;
    let mut builder = CoordinationChainBuilder::new();
    let mut hasher = Sha256::new();
    let mut buffer = vec![0_u8; 64 * 1024].into_boxed_slice();
    let mut line = Vec::with_capacity(MAXIMUM_RECORD_BYTES.min(4096));
    let mut offset = 0_u64;
    while offset < history.fingerprint.bytes {
        let remaining = history.fingerprint.bytes - offset;
        let requested = usize::try_from(
            remaining.min(u64::try_from(buffer.len()).expect("buffer length fits u64")),
        )
        .expect("bounded history chunk fits usize");
        let amount = history
            .file
            .read_at(&mut buffer[..requested], offset)
            .map_err(|error| {
                coordination_error(format!("cannot stream coordination history: {error}"))
            })?;
        if amount == 0 {
            return Err(coordination_error(
                "coordination history was truncated during streaming",
            ));
        }
        hasher.update(&buffer[..amount]);
        for byte in &buffer[..amount] {
            line.push(*byte);
            if line.len() > MAXIMUM_RECORD_BYTES {
                return Err(coordination_error(
                    "coordination history record exceeds its strict bound",
                ));
            }
            if *byte == b'\n' {
                builder.push(&line)?;
                line.clear();
            }
        }
        offset = offset
            .checked_add(u64::try_from(amount).expect("usize fits u64"))
            .ok_or_else(|| coordination_error("coordination history byte-count overflow"))?;
    }
    let mut extra = [0_u8; 1];
    if !line.is_empty()
        || history
            .file
            .read_at(&mut extra, history.fingerprint.bytes)
            .map_err(|error| {
                coordination_error(format!("cannot check coordination history EOF: {error}"))
            })?
            != 0
        || immutable_file_fingerprint(&history.file, &history.relative)? != history.fingerprint
        || offset != history.binding.bytes
        || hex_lower(&hasher.finalize()) != history.binding.sha256
    {
        return Err(coordination_error(
            "coordination history is truncated, changed, or differs from its exact binding",
        ));
    }
    builder.finish(expected_run_id, selected_wire, selected_receipt)
}

fn coordination_error(message: impl Into<String>) -> PromotionError {
    PromotionError::new(FailureCode::CoordinationChain, message)
}

/// Verifies a complete, bounded, canonical JSONL history from sequence zero.
///
/// The expected byte count and digest must come from the separately sealed
/// history-snapshot manifest. Every record is reserialized and rehashed; the
/// chain rejects gaps, forks represented by a wrong predecessor, and global
/// replay of run IDs, intent digests, or grant triples.
///
/// # Errors
///
/// Returns [`FailureCode::CoordinationChain`] for malformed or incomplete
/// history and [`FailureCode::CoordinationReplay`] for a repeated identity.
pub fn verify_complete_burn_history(
    request: &PromotionRequest,
    bytes: &[u8],
    selected_receipt: &[u8],
) -> PromotionResult<CoordinationChain> {
    let (expected_bytes, expected_sha256) = request.coordination_history_binding();
    if bytes.is_empty()
        || bytes.len() > MAXIMUM_HISTORY_BYTES
        || u64::try_from(bytes.len()).ok() != Some(expected_bytes)
        || !is_lower_hex(expected_sha256, 64, false)
        || sha256_hex(bytes) != expected_sha256
        || bytes.last() != Some(&b'\n')
    {
        return Err(PromotionError::new(
            FailureCode::CoordinationChain,
            "coordination history is empty, truncated, oversized, or differs from its manifest binding",
        ));
    }
    let (selected_receipt_expected_bytes, selected_receipt_expected_sha256) =
        request.selected_burn_binding();
    if selected_receipt.is_empty()
        || u64::try_from(selected_receipt.len()).ok() != Some(selected_receipt_expected_bytes)
        || !is_lower_hex(selected_receipt_expected_sha256, 64, false)
        || sha256_hex(selected_receipt) != selected_receipt_expected_sha256
    {
        return Err(PromotionError::new(
            FailureCode::CoordinationChain,
            "selected coordination receipt or run binding is non-canonical or differs from its manifest binding",
        ));
    }
    let selected_wire = parse_selected_receipt(selected_receipt)?;
    let mut builder = CoordinationChainBuilder::new();
    for line in bytes.split_inclusive(|byte| *byte == b'\n') {
        builder.push(line)?;
    }
    builder.finish(request.run_id(), selected_wire, selected_receipt)
}

#[cfg(test)]
fn synthetic_burn_record(sequence: u64, previous_sha256: &str, salt: u8) -> CoordinationBurnWire {
    let mut wire = CoordinationBurnWire {
        schema: BURN_SCHEMA,
        contract: BURN_CONTRACT.to_owned(),
        sequence,
        run_id: format!("{salt:02x}{}", "1".repeat(30)),
        intent: IntentBinding {
            bytes: 100,
            sha256: format!("{salt:02x}{}", "2".repeat(62)),
        },
        grants: vec![
            CoordinationGrantWire {
                ledger_id: PROJECT_LEDGER.to_owned(),
                entry_id: format!("project-{salt}"),
                entry_bytes: 10,
                entry_sha256: format!("{salt:02x}{}", "3".repeat(62)),
            },
            CoordinationGrantWire {
                ledger_id: ED25519_LEDGER.to_owned(),
                entry_id: format!("ed25519-{salt}"),
                entry_bytes: 11,
                entry_sha256: format!("{salt:02x}{}", "4".repeat(62)),
            },
        ],
        previous_sha256: previous_sha256.to_owned(),
        record_sha256: String::new(),
    };
    wire.record_sha256 = wire.recomputed_record_sha256().unwrap();
    wire
}

#[cfg(test)]
pub(crate) fn synthetic_chain(salt: u8) -> CoordinationChain {
    let wire = synthetic_burn_record(0, GENESIS_SHA256, salt);
    let receipt = canonical_line(&wire).unwrap();
    let request =
        crate::model::synthetic_request_with_coordination(&wire.run_id, &receipt, &receipt);
    verify_complete_burn_history(&request, &receipt, &receipt).unwrap()
}

#[cfg(test)]
mod tests {
    use super::{
        CoordinationBurnWire, CoordinationSnapshotBinding, GENESIS_SHA256, synthetic_burn_record,
        verify_complete_burn_history,
    };
    use crate::FailureCode;
    use crate::canonical::{canonical_line, sha256_hex};
    use crate::model::{
        synthetic_request_with_coordination, synthetic_request_with_coordination_snapshot,
    };
    use std::fs;
    use std::os::unix::fs::PermissionsExt;
    use std::path::{Path, PathBuf};
    use std::sync::atomic::{AtomicU64, Ordering};

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

    struct TestSnapshotRoot {
        path: PathBuf,
    }

    impl TestSnapshotRoot {
        fn new() -> Self {
            let path = std::env::temp_dir().join(format!(
                "hashsigs-promoter-coordination-{}-{}",
                std::process::id(),
                NEXT_SNAPSHOT_ROOT.fetch_add(1, Ordering::Relaxed)
            ));
            fs::create_dir(&path).unwrap();
            set_mode(&path, 0o700);
            Self { path }
        }

        fn path(&self) -> &Path {
            &self.path
        }

        fn child(&self, name: &str) -> PathBuf {
            self.path.join(name)
        }

        fn write_file(&self, name: &str, bytes: &[u8], mode: u32) -> PathBuf {
            let path = self.child(name);
            fs::write(&path, bytes).unwrap();
            set_mode(&path, mode);
            path
        }

        fn seal(&self) {
            set_mode(&self.path, 0o500);
        }
    }

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

    struct SnapshotFixture {
        root: TestSnapshotRoot,
        request: crate::PromotionRequest,
        selected_path: PathBuf,
        selected_bytes: Vec<u8>,
    }

    fn set_mode(path: &Path, mode: u32) {
        fs::set_permissions(path, fs::Permissions::from_mode(mode)).unwrap();
    }

    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 history_manifest(history: &[u8]) -> Vec<u8> {
        format!("{}  history.jsonl\n", sha256_hex(history)).into_bytes()
    }

    fn snapshot_request(
        root: &TestSnapshotRoot,
        run_id: &str,
        history: &[u8],
        manifest: &[u8],
        selected: &[u8],
    ) -> crate::PromotionRequest {
        let history_path = root.child("history.jsonl");
        let manifest_path = root.child("history.SHA256SUMS");
        let selected_path = root.child("selected.json");
        synthetic_request_with_coordination_snapshot(
            run_id,
            [
                (history_path.to_str().unwrap(), history),
                (manifest_path.to_str().unwrap(), manifest),
                (selected_path.to_str().unwrap(), selected),
            ],
        )
    }

    fn valid_snapshot_fixture(salt: u8) -> SnapshotFixture {
        let burn = record(0, GENESIS_SHA256, salt);
        let history = canonical_line(&burn).unwrap();
        let selected_bytes = history.clone();
        let manifest = history_manifest(&history);
        let root = TestSnapshotRoot::new();
        root.write_file("history.jsonl", &history, 0o400);
        root.write_file("history.SHA256SUMS", &manifest, 0o400);
        let selected_path = root.write_file("selected.json", &selected_bytes, 0o400);
        let request = snapshot_request(&root, &burn.run_id, &history, &manifest, &selected_bytes);
        root.seal();
        SnapshotFixture {
            root,
            request,
            selected_path,
            selected_bytes,
        }
    }

    fn record(sequence: u64, previous: &str, salt: u8) -> CoordinationBurnWire {
        synthetic_burn_record(sequence, previous, salt)
    }

    fn verify(
        history: &[u8],
        selected: &CoordinationBurnWire,
    ) -> crate::PromotionResult<super::CoordinationChain> {
        let selected_bytes = canonical_line(selected).unwrap();
        let request =
            synthetic_request_with_coordination(&selected.run_id, history, &selected_bytes);
        verify_complete_burn_history(&request, history, &selected_bytes)
    }

    #[test]
    fn complete_chain_recomputes_genesis_and_global_uniqueness() {
        let first = record(0, GENESIS_SHA256, 1);
        let second = record(1, first.record_sha256.as_str(), 2);
        let mut history = canonical_line(&first).unwrap();
        history.extend(canonical_line(&second).unwrap());
        let state = verify(&history, &second).unwrap();
        assert_eq!(state.records(), 2);
        assert_eq!(state.selected_burn().run_id(), second.run_id.as_str());
        assert_eq!(
            state.selected_burn().record_sha256(),
            second.record_sha256.as_str()
        );
        assert!(state.contains_run_id(&first.run_id));
        assert!(state.contains_grant(
            &first.grants[0].ledger_id,
            &first.grants[0].entry_id,
            &first.grants[0].entry_sha256
        ));
    }

    #[test]
    fn gap_and_replay_are_rejected() {
        let first = record(0, GENESIS_SHA256, 1);
        let gap = record(2, first.record_sha256.as_str(), 2);
        let mut gap_history = canonical_line(&first).unwrap();
        gap_history.extend(canonical_line(&gap).unwrap());
        assert_eq!(
            verify(&gap_history, &gap).unwrap_err().code(),
            FailureCode::CoordinationChain
        );

        let mut replay = record(1, first.record_sha256.as_str(), 2);
        replay.run_id.clone_from(&first.run_id);
        replay.record_sha256 = replay.recomputed_record_sha256().unwrap();
        let mut replay_history = canonical_line(&first).unwrap();
        replay_history.extend(canonical_line(&replay).unwrap());
        assert_eq!(
            verify(&replay_history, &replay).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );
    }

    #[test]
    fn coordination_replay_key_ignores_changed_grant_byte_metadata() {
        let first = record(0, GENESIS_SHA256, 1);
        let mut second = record(1, &first.record_sha256, 2);
        second.grants[0]
            .ledger_id
            .clone_from(&first.grants[0].ledger_id);
        second.grants[0]
            .entry_id
            .clone_from(&first.grants[0].entry_id);
        second.grants[0]
            .entry_sha256
            .clone_from(&first.grants[0].entry_sha256);
        second.grants[0].entry_bytes = first.grants[0].entry_bytes + 1;
        second.record_sha256 = second.recomputed_record_sha256().unwrap();
        let mut history = canonical_line(&first).unwrap();
        history.extend(canonical_line(&second).unwrap());
        assert_eq!(
            verify(&history, &second).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );
    }

    #[test]
    fn selected_receipt_and_run_must_bind_the_exact_last_record() {
        let first = record(0, GENESIS_SHA256, 1);
        let second = record(1, first.record_sha256.as_str(), 2);
        let mut history = canonical_line(&first).unwrap();
        history.extend(canonical_line(&second).unwrap());
        let first_bytes = canonical_line(&first).unwrap();
        let request = synthetic_request_with_coordination(&second.run_id, &history, &first_bytes);
        assert_eq!(
            verify_complete_burn_history(&request, &history, &first_bytes,)
                .unwrap_err()
                .code(),
            FailureCode::CoordinationChain
        );
    }

    #[test]
    fn retained_snapshot_binding_is_derived_only_from_request_locators() {
        let request =
            synthetic_request_with_coordination(&"1".repeat(32), b"history\n", b"receipt\n");
        let binding = CoordinationSnapshotBinding::from_request(&request).unwrap();
        assert_eq!(binding.root, std::path::Path::new("/evidence"));
        assert_eq!(
            binding.history.absolute_path,
            std::path::Path::new("/evidence/coordination-history.jsonl")
        );
        assert_eq!(binding.history.bytes, 8);
        assert_eq!(
            binding.history.sha256,
            crate::canonical::sha256_hex(b"history\n")
        );
        assert_eq!(
            binding.manifest.absolute_path,
            std::path::Path::new("/evidence/coordination-history.SHA256SUMS")
        );
        assert_eq!(binding.manifest.bytes, 10);
        assert_eq!(binding.manifest.sha256, "8".repeat(64));
        assert_eq!(
            binding.selected_receipt.absolute_path,
            std::path::Path::new("/evidence/coordination-burn.json")
        );
        assert_eq!(binding.selected_receipt.bytes, 8);
        assert_eq!(
            binding.selected_receipt.sha256,
            crate::canonical::sha256_hex(b"receipt\n")
        );
    }

    #[test]
    fn retained_snapshot_rejects_manifest_content_mismatch() {
        let burn = record(0, GENESIS_SHA256, 3);
        let history = canonical_line(&burn).unwrap();
        let manifest = format!("{}  history.jsonl\n", "0".repeat(64)).into_bytes();
        let root = TestSnapshotRoot::new();
        root.write_file("history.jsonl", &history, 0o400);
        root.write_file("history.SHA256SUMS", &manifest, 0o400);
        root.write_file("selected.json", &history, 0o400);
        let request = snapshot_request(&root, &burn.run_id, &history, &manifest, &history);
        root.seal();
        assert_eq!(
            super::retain_verified_coordination_snapshot(&request)
                .unwrap_err()
                .code(),
            FailureCode::CoordinationChain
        );
    }

    #[test]
    fn retained_snapshot_rejects_hardlink_alias() {
        let burn = record(0, GENESIS_SHA256, 4);
        let history = canonical_line(&burn).unwrap();
        let manifest = history_manifest(&history);
        let root = TestSnapshotRoot::new();
        let history_path = root.write_file("history.jsonl", &history, 0o400);
        root.write_file("history.SHA256SUMS", &manifest, 0o400);
        fs::hard_link(&history_path, root.child("selected.json")).unwrap();
        let request = snapshot_request(&root, &burn.run_id, &history, &manifest, &history);
        root.seal();
        assert_eq!(
            super::retain_verified_coordination_snapshot(&request)
                .unwrap_err()
                .code(),
            FailureCode::CoordinationChain
        );
    }

    #[test]
    fn retained_snapshot_rejects_writable_inputs() {
        let burn = record(0, GENESIS_SHA256, 5);
        let history = canonical_line(&burn).unwrap();
        let manifest = history_manifest(&history);
        let root = TestSnapshotRoot::new();
        root.write_file("history.jsonl", &history, 0o600);
        root.write_file("history.SHA256SUMS", &manifest, 0o400);
        root.write_file("selected.json", &history, 0o400);
        let request = snapshot_request(&root, &burn.run_id, &history, &manifest, &history);
        root.seal();
        assert_eq!(
            super::retain_verified_coordination_snapshot(&request)
                .unwrap_err()
                .code(),
            FailureCode::CoordinationChain
        );
    }

    #[test]
    fn retained_snapshot_final_revalidation_detects_path_substitution() {
        let fixture = valid_snapshot_fixture(6);
        let snapshot = super::retain_verified_coordination_snapshot(&fixture.request).unwrap();
        snapshot.revalidate().unwrap();

        set_mode(fixture.root.path(), 0o700);
        fs::rename(&fixture.selected_path, fixture.root.child("selected.old")).unwrap();
        fs::write(&fixture.selected_path, &fixture.selected_bytes).unwrap();
        set_mode(&fixture.selected_path, 0o400);
        fixture.root.seal();
        assert_eq!(
            snapshot.revalidate().unwrap_err().code(),
            FailureCode::CoordinationChain
        );
    }

    #[test]
    fn retained_snapshot_final_revalidation_detects_in_place_change() {
        let fixture = valid_snapshot_fixture(7);
        let snapshot = super::retain_verified_coordination_snapshot(&fixture.request).unwrap();
        snapshot.revalidate().unwrap();

        let mut changed = fixture.selected_bytes.clone();
        changed[0] ^= 1;
        set_mode(&fixture.selected_path, 0o600);
        fs::write(&fixture.selected_path, changed).unwrap();
        set_mode(&fixture.selected_path, 0o400);
        assert_eq!(
            snapshot.revalidate().unwrap_err().code(),
            FailureCode::CoordinationChain
        );
    }
}