u280_hardware_promoter/

journal.rs

//! Private, hash-chained promotion anti-replay journal model.

use crate::canonical::{canonical_line, is_lower_hex, parse_canonical_line, sha256_hex};
use crate::coordination::{
    CoordinationBurnGrantHashInput, MAXIMUM_COORDINATION_INTENT_BYTES, VerifiedCoordinationBurn,
    VerifiedCoordinationSnapshot, recompute_coordination_burn_record_sha256,
};
use crate::{FailureCode, PromotionError, PromotionRequest, PromotionResult};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;

const PREACCEPTANCE_JOURNAL_SCHEMA: u64 = 1;
const PREACCEPTANCE_JOURNAL_CONTRACT: &str =
    "hashsigs-u280-hardware-promotion-preacceptance-journal-v1";
const LEGACY_JOURNAL_SCHEMA: u64 = 1;
const LEGACY_JOURNAL_CONTRACT: &str = "hashsigs-u280-hardware-promotion-journal-v1";
const GENESIS_SHA256: &str = "0000000000000000000000000000000000000000000000000000000000000000";
const MAXIMUM_JOURNAL_BYTES: usize = 64 * 1024 * 1024;
const MAXIMUM_RECORD_BYTES: usize = 128 * 1024;

/// Immutable evidence identities consumed by one promotion attempt.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct PromotionIdentity {
    run_id: String,
    intent_bytes: u64,
    intent_sha256: String,
    grants: Vec<PromotionGrantBinding>,
    route_seal_sha256: String,
    transport_manifest_sha256: String,
    oracle_receipt_sha256: String,
    oracle_result_manifest_sha256: String,
    coordination_burn_sequence: u64,
    coordination_burn_previous_sha256: String,
    coordination_burn_record_sha256: String,
}

/// Opaque run/intent/burn identity shared by the request-derived document,
/// durable state burn, and atomic publication transaction.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct PromotionTransactionIdentity {
    run_id: String,
    intent_sha256: String,
    coordination_burn_record_sha256: String,
}

impl PromotionTransactionIdentity {
    /// Exact Phase-B run identity.
    #[must_use]
    pub fn run_id(&self) -> &str {
        &self.run_id
    }
}

impl PromotionIdentity {
    /// Builds an anti-replay identity from a retained coordination snapshot
    /// and exact digests revalidated by the eventual evidence combiner.
    ///
    /// # Errors
    ///
    /// Returns [`FailureCode::CoordinationChain`] if retained snapshot
    /// revalidation fails, [`FailureCode::IdentityJoin`] if the request and
    /// selected burn disagree, or [`FailureCode::StateBurn`] if any supplied
    /// artifact digest is not a canonical lowercase SHA-256.
    #[allow(dead_code)] // Called only by the future complete evidence combiner.
    pub(crate) fn from_verified_evidence(
        request: &PromotionRequest,
        snapshot: &VerifiedCoordinationSnapshot,
        route_seal_sha256: &str,
        transport_manifest_sha256: &str,
        oracle_receipt_sha256: &str,
        oracle_result_manifest_sha256: &str,
    ) -> PromotionResult<Self> {
        snapshot.revalidate()?;
        let identity = Self::from_revalidated_burn(
            request,
            snapshot.selected_burn(),
            route_seal_sha256,
            transport_manifest_sha256,
            oracle_receipt_sha256,
            oracle_result_manifest_sha256,
        )?;
        snapshot.revalidate()?;
        Ok(identity)
    }

    fn from_revalidated_burn(
        request: &PromotionRequest,
        burn: &VerifiedCoordinationBurn,
        route_seal_sha256: &str,
        transport_manifest_sha256: &str,
        oracle_receipt_sha256: &str,
        oracle_result_manifest_sha256: &str,
    ) -> PromotionResult<Self> {
        let digests = [
            route_seal_sha256,
            transport_manifest_sha256,
            oracle_receipt_sha256,
            oracle_result_manifest_sha256,
        ];
        if digests
            .into_iter()
            .any(|digest| !is_lower_hex(digest, 64, false))
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "promotion identity contains a non-canonical artifact SHA-256",
            ));
        }
        if request.run_id() != burn.run_id() {
            return Err(PromotionError::new(
                FailureCode::IdentityJoin,
                "validated promotion request and selected coordination burn identify different runs",
            ));
        }
        let grants = burn
            .grants()
            .iter()
            .map(|grant| PromotionGrantBinding {
                ledger_id: grant.ledger_id().to_owned(),
                entry_id: grant.entry_id().to_owned(),
                entry_bytes: grant.entry_bytes(),
                entry_sha256: grant.entry_sha256().to_owned(),
            })
            .collect::<Vec<_>>();
        let grant_hash_inputs = grants
            .iter()
            .map(|grant| {
                CoordinationBurnGrantHashInput::new(
                    &grant.ledger_id,
                    &grant.entry_id,
                    grant.entry_bytes,
                    &grant.entry_sha256,
                )
            })
            .collect::<Vec<_>>();
        if recompute_coordination_burn_record_sha256(
            burn.sequence(),
            burn.run_id(),
            burn.intent_bytes(),
            burn.intent_sha256(),
            &grant_hash_inputs,
            burn.previous_sha256(),
        )? != burn.record_sha256()
        {
            return Err(PromotionError::new(
                FailureCode::IdentityJoin,
                "verified coordination burn copied fields do not recompute",
            ));
        }
        Ok(Self {
            run_id: burn.run_id().to_owned(),
            intent_bytes: burn.intent_bytes(),
            intent_sha256: burn.intent_sha256().to_owned(),
            grants,
            route_seal_sha256: route_seal_sha256.to_owned(),
            transport_manifest_sha256: transport_manifest_sha256.to_owned(),
            oracle_receipt_sha256: oracle_receipt_sha256.to_owned(),
            oracle_result_manifest_sha256: oracle_result_manifest_sha256.to_owned(),
            coordination_burn_sequence: burn.sequence(),
            coordination_burn_previous_sha256: burn.previous_sha256().to_owned(),
            coordination_burn_record_sha256: burn.record_sha256().to_owned(),
        })
    }

    /// Typed identity that must match the document, durable burn, and output.
    #[must_use]
    pub(crate) fn transaction_identity(&self) -> PromotionTransactionIdentity {
        PromotionTransactionIdentity {
            run_id: self.run_id.clone(),
            intent_sha256: self.intent_sha256.clone(),
            coordination_burn_record_sha256: self.coordination_burn_record_sha256.clone(),
        }
    }
}

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

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

impl PromotionGrantBinding {
    fn replay_key(&self) -> PromotionGrantReplayKey {
        PromotionGrantReplayKey {
            ledger_id: self.ledger_id.clone(),
            entry_id: self.entry_id.clone(),
            entry_sha256: self.entry_sha256.clone(),
        }
    }
}

/// One canonical preacceptance private-state journal record.
///
/// This transitional wire is not the final promotion-journal v2 contract and
/// cannot carry a hardware-acceptance claim. The final wire remains undefined
/// until `FinalEvidenceJoin` exists.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PreacceptanceJournalRecord {
    schema: u64,
    contract: String,
    sequence: u64,
    run_id: String,
    intent_bytes: u64,
    intent_sha256: String,
    grants: Vec<PromotionGrantBinding>,
    route_seal_sha256: String,
    transport_manifest_sha256: String,
    oracle_receipt_sha256: String,
    oracle_result_manifest_sha256: String,
    coordination_burn_sequence: u64,
    coordination_burn_previous_sha256: String,
    coordination_burn_record_sha256: String,
    previous_promotion_record_sha256: String,
    record_sha256: String,
}

impl PreacceptanceJournalRecord {
    /// Monotonic zero-based private journal sequence.
    #[must_use]
    pub const fn sequence(&self) -> u64 {
        self.sequence
    }

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

    pub(crate) fn transaction_identity(&self) -> PromotionTransactionIdentity {
        PromotionTransactionIdentity {
            run_id: self.run_id.clone(),
            intent_sha256: self.intent_sha256.clone(),
            coordination_burn_record_sha256: self.coordination_burn_record_sha256.clone(),
        }
    }

    /// Canonical newline-terminated bytes appended to private state.
    ///
    /// # Errors
    ///
    /// Returns an error only if serialization unexpectedly fails.
    pub fn canonical_line(&self) -> PromotionResult<Vec<u8>> {
        canonical_line(self)
    }

    fn validate_shape(&self) -> PromotionResult<()> {
        let correct_grants = self.grants.len() == 2
            && self.grants[0].ledger_id == "hashsigs-project-coordination"
            && self.grants[1].ledger_id == "ed25519-agent-coordination"
            && self.grants[0].entry_id != self.grants[1].entry_id
            && self.grants.iter().all(|grant| {
                !grant.entry_id.is_empty()
                    && grant.entry_id.len() <= 128
                    && grant.entry_id.bytes().all(|byte| {
                        byte.is_ascii_lowercase()
                            || byte.is_ascii_digit()
                            || matches!(byte, b'.' | b'_' | b':' | b'-')
                    })
                    && grant.entry_bytes > 0
                    && is_lower_hex(&grant.entry_sha256, 64, true)
            });
        let digests = [
            self.intent_sha256.as_str(),
            self.route_seal_sha256.as_str(),
            self.transport_manifest_sha256.as_str(),
            self.oracle_receipt_sha256.as_str(),
            self.oracle_result_manifest_sha256.as_str(),
            self.coordination_burn_previous_sha256.as_str(),
            self.coordination_burn_record_sha256.as_str(),
            self.previous_promotion_record_sha256.as_str(),
            self.record_sha256.as_str(),
        ];
        if self.schema != PREACCEPTANCE_JOURNAL_SCHEMA
            || self.contract != PREACCEPTANCE_JOURNAL_CONTRACT
            || !is_lower_hex(&self.run_id, 32, true)
            || self.intent_bytes == 0
            || self.intent_bytes > MAXIMUM_COORDINATION_INTENT_BYTES
            || !correct_grants
            || digests
                .into_iter()
                .any(|digest| !is_lower_hex(digest, 64, false))
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "promotion journal record has a non-canonical shape",
            ));
        }
        if self.coordination_burn_sequence == 0
            && self.coordination_burn_previous_sha256 != GENESIS_SHA256
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "sequence-zero copied coordination burn does not use the fixed genesis predecessor",
            ));
        }
        let grants = self
            .grants
            .iter()
            .map(|grant| {
                CoordinationBurnGrantHashInput::new(
                    &grant.ledger_id,
                    &grant.entry_id,
                    grant.entry_bytes,
                    &grant.entry_sha256,
                )
            })
            .collect::<Vec<_>>();
        if recompute_coordination_burn_record_sha256(
            self.coordination_burn_sequence,
            &self.run_id,
            self.intent_bytes,
            &self.intent_sha256,
            &grants,
            &self.coordination_burn_previous_sha256,
        )? != self.coordination_burn_record_sha256
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "preacceptance journal copied coordination burn does not recompute",
            ));
        }
        Ok(())
    }

    fn recomputed_sha256(&self) -> PromotionResult<String> {
        let body = PreacceptanceJournalBody {
            schema: self.schema,
            contract: self.contract.clone(),
            sequence: self.sequence,
            run_id: self.run_id.clone(),
            intent_bytes: self.intent_bytes,
            intent_sha256: self.intent_sha256.clone(),
            grants: self.grants.clone(),
            route_seal_sha256: self.route_seal_sha256.clone(),
            transport_manifest_sha256: self.transport_manifest_sha256.clone(),
            oracle_receipt_sha256: self.oracle_receipt_sha256.clone(),
            oracle_result_manifest_sha256: self.oracle_result_manifest_sha256.clone(),
            coordination_burn_sequence: self.coordination_burn_sequence,
            coordination_burn_previous_sha256: self.coordination_burn_previous_sha256.clone(),
            coordination_burn_record_sha256: self.coordination_burn_record_sha256.clone(),
            previous_promotion_record_sha256: self.previous_promotion_record_sha256.clone(),
        };
        body.sha256()
    }
}

#[derive(Serialize)]
struct PreacceptanceJournalBody {
    schema: u64,
    contract: String,
    sequence: u64,
    run_id: String,
    intent_bytes: u64,
    intent_sha256: String,
    grants: Vec<PromotionGrantBinding>,
    route_seal_sha256: String,
    transport_manifest_sha256: String,
    oracle_receipt_sha256: String,
    oracle_result_manifest_sha256: String,
    coordination_burn_sequence: u64,
    coordination_burn_previous_sha256: String,
    coordination_burn_record_sha256: String,
    previous_promotion_record_sha256: String,
}

impl PreacceptanceJournalBody {
    fn sha256(&self) -> PromotionResult<String> {
        let mut bytes = canonical_line(self)?;
        let newline = bytes.pop();
        debug_assert_eq!(newline, Some(b'\n'));
        Ok(sha256_hex(&bytes))
    }
}

/// The historical promotion-journal v1 is accepted only as an already-consumed
/// replay prefix. New records are never emitted in this shape because it
/// omitted intent and grant entry byte counts, so its copied burn cannot be
/// independently recomputed.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
struct LegacyPromotionJournalRecord {
    schema: u64,
    contract: String,
    sequence: u64,
    run_id: String,
    intent_sha256: String,
    grants: Vec<PromotionGrantReplayKey>,
    route_seal_sha256: String,
    transport_manifest_sha256: String,
    oracle_receipt_sha256: String,
    oracle_result_manifest_sha256: String,
    coordination_burn_sequence: u64,
    coordination_burn_previous_sha256: String,
    coordination_burn_record_sha256: String,
    previous_promotion_record_sha256: String,
    record_sha256: String,
}

impl LegacyPromotionJournalRecord {
    fn validate_shape(&self) -> PromotionResult<()> {
        let correct_grants = self.grants.len() == 2
            && self.grants[0].ledger_id == "hashsigs-project-coordination"
            && self.grants[1].ledger_id == "ed25519-agent-coordination"
            && self.grants[0].entry_id != self.grants[1].entry_id
            && self.grants.iter().all(|grant| {
                canonical_entry_id(&grant.entry_id) && is_lower_hex(&grant.entry_sha256, 64, true)
            });
        let digests = [
            self.intent_sha256.as_str(),
            self.route_seal_sha256.as_str(),
            self.transport_manifest_sha256.as_str(),
            self.oracle_receipt_sha256.as_str(),
            self.oracle_result_manifest_sha256.as_str(),
            self.coordination_burn_previous_sha256.as_str(),
            self.coordination_burn_record_sha256.as_str(),
            self.previous_promotion_record_sha256.as_str(),
            self.record_sha256.as_str(),
        ];
        if self.schema != LEGACY_JOURNAL_SCHEMA
            || self.contract != LEGACY_JOURNAL_CONTRACT
            || !is_lower_hex(&self.run_id, 32, true)
            || !correct_grants
            || digests
                .into_iter()
                .any(|digest| !is_lower_hex(digest, 64, false))
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "legacy promotion journal record has a non-canonical shape",
            ));
        }
        if self.coordination_burn_sequence == 0
            && self.coordination_burn_previous_sha256 != GENESIS_SHA256
        {
            return Err(PromotionError::new(
                FailureCode::StateBurn,
                "sequence-zero legacy copied coordination burn does not use the fixed genesis predecessor",
            ));
        }
        Ok(())
    }

    fn recomputed_sha256(&self) -> PromotionResult<String> {
        LegacyPromotionJournalBody {
            schema: self.schema,
            contract: self.contract.clone(),
            sequence: self.sequence,
            run_id: self.run_id.clone(),
            intent_sha256: self.intent_sha256.clone(),
            grants: self.grants.clone(),
            route_seal_sha256: self.route_seal_sha256.clone(),
            transport_manifest_sha256: self.transport_manifest_sha256.clone(),
            oracle_receipt_sha256: self.oracle_receipt_sha256.clone(),
            oracle_result_manifest_sha256: self.oracle_result_manifest_sha256.clone(),
            coordination_burn_sequence: self.coordination_burn_sequence,
            coordination_burn_previous_sha256: self.coordination_burn_previous_sha256.clone(),
            coordination_burn_record_sha256: self.coordination_burn_record_sha256.clone(),
            previous_promotion_record_sha256: self.previous_promotion_record_sha256.clone(),
        }
        .sha256()
    }
}

#[derive(Serialize)]
struct LegacyPromotionJournalBody {
    schema: u64,
    contract: String,
    sequence: u64,
    run_id: String,
    intent_sha256: String,
    grants: Vec<PromotionGrantReplayKey>,
    route_seal_sha256: String,
    transport_manifest_sha256: String,
    oracle_receipt_sha256: String,
    oracle_result_manifest_sha256: String,
    coordination_burn_sequence: u64,
    coordination_burn_previous_sha256: String,
    coordination_burn_record_sha256: String,
    previous_promotion_record_sha256: String,
}

impl LegacyPromotionJournalBody {
    fn sha256(&self) -> PromotionResult<String> {
        let mut bytes = canonical_line(self)?;
        let newline = bytes.pop();
        debug_assert_eq!(newline, Some(b'\n'));
        Ok(sha256_hex(&bytes))
    }
}

#[derive(Deserialize, Serialize)]
#[serde(untagged)]
enum PromotionJournalWire {
    Preacceptance(PreacceptanceJournalRecord),
    Legacy(LegacyPromotionJournalRecord),
}

fn canonical_entry_id(entry_id: &str) -> bool {
    !entry_id.is_empty()
        && entry_id.len() <= 128
        && entry_id.bytes().all(|byte| {
            byte.is_ascii_lowercase()
                || byte.is_ascii_digit()
                || matches!(byte, b'.' | b'_' | b':' | b'-')
        })
}

/// Reconstructed append position and global replay sets for private state.
#[derive(Clone, Debug)]
pub struct PromotionJournalState {
    next_sequence: u64,
    last_sha256: String,
    run_ids: BTreeSet<String>,
    intent_sha256s: BTreeSet<String>,
    transport_manifest_sha256s: BTreeSet<String>,
    oracle_result_manifest_sha256s: BTreeSet<String>,
    grant_replay_keys: BTreeSet<PromotionGrantReplayKey>,
}

impl PromotionJournalState {
    /// Sequence that the next durable record must use.
    #[must_use]
    pub const fn next_sequence(&self) -> u64 {
        self.next_sequence
    }

    /// Builds the next explicitly preacceptance record and rejects every
    /// cross-archive replay key.
    ///
    /// # Errors
    ///
    /// Returns [`FailureCode::CoordinationReplay`] if any globally unique key
    /// has already appeared, or [`FailureCode::StateBurn`] on overflow.
    pub(crate) fn next_record(
        &self,
        identity: &PromotionIdentity,
    ) -> PromotionResult<PreacceptanceJournalRecord> {
        if self.run_ids.contains(&identity.run_id)
            || self.intent_sha256s.contains(&identity.intent_sha256)
            || self
                .transport_manifest_sha256s
                .contains(&identity.transport_manifest_sha256)
            || self
                .oracle_result_manifest_sha256s
                .contains(&identity.oracle_result_manifest_sha256)
            || identity
                .grants
                .iter()
                .any(|grant| self.grant_replay_keys.contains(&grant.replay_key()))
        {
            return Err(PromotionError::new(
                FailureCode::CoordinationReplay,
                "private promotion state already consumed this run, intent, archive, oracle result, or ledger grant",
            ));
        }
        let body = PreacceptanceJournalBody {
            schema: PREACCEPTANCE_JOURNAL_SCHEMA,
            contract: PREACCEPTANCE_JOURNAL_CONTRACT.to_owned(),
            sequence: self.next_sequence,
            run_id: identity.run_id.clone(),
            intent_bytes: identity.intent_bytes,
            intent_sha256: identity.intent_sha256.clone(),
            grants: identity.grants.clone(),
            route_seal_sha256: identity.route_seal_sha256.clone(),
            transport_manifest_sha256: identity.transport_manifest_sha256.clone(),
            oracle_receipt_sha256: identity.oracle_receipt_sha256.clone(),
            oracle_result_manifest_sha256: identity.oracle_result_manifest_sha256.clone(),
            coordination_burn_sequence: identity.coordination_burn_sequence,
            coordination_burn_previous_sha256: identity.coordination_burn_previous_sha256.clone(),
            coordination_burn_record_sha256: identity.coordination_burn_record_sha256.clone(),
            previous_promotion_record_sha256: self.last_sha256.clone(),
        };
        let record_sha256 = body.sha256()?;
        let record = PreacceptanceJournalRecord {
            schema: body.schema,
            contract: body.contract,
            sequence: body.sequence,
            run_id: body.run_id,
            intent_bytes: body.intent_bytes,
            intent_sha256: body.intent_sha256,
            grants: body.grants,
            route_seal_sha256: body.route_seal_sha256,
            transport_manifest_sha256: body.transport_manifest_sha256,
            oracle_receipt_sha256: body.oracle_receipt_sha256,
            oracle_result_manifest_sha256: body.oracle_result_manifest_sha256,
            coordination_burn_sequence: body.coordination_burn_sequence,
            coordination_burn_previous_sha256: body.coordination_burn_previous_sha256,
            coordination_burn_record_sha256: body.coordination_burn_record_sha256,
            previous_promotion_record_sha256: body.previous_promotion_record_sha256,
            record_sha256,
        };
        record.validate_shape()?;
        Ok(record)
    }
}

/// Reparses a bounded legacy-plus-preacceptance private journal from genesis.
///
/// No final promotion-journal v2 wire is recognized or emitted here.
///
/// # Errors
///
/// Rejects truncated/non-canonical lines, chain gaps, body-hash mismatches, and
/// replay of any required cross-archive uniqueness key.
pub fn verify_promotion_journal(bytes: &[u8]) -> PromotionResult<PromotionJournalState> {
    if bytes.len() > MAXIMUM_JOURNAL_BYTES || (!bytes.is_empty() && bytes.last() != Some(&b'\n')) {
        return Err(PromotionError::new(
            FailureCode::StateBurn,
            "promotion journal is oversized or has a truncated final line",
        ));
    }
    let mut state = PromotionJournalState {
        next_sequence: 0,
        last_sha256: GENESIS_SHA256.to_owned(),
        run_ids: BTreeSet::new(),
        intent_sha256s: BTreeSet::new(),
        transport_manifest_sha256s: BTreeSet::new(),
        oracle_result_manifest_sha256s: BTreeSet::new(),
        grant_replay_keys: BTreeSet::new(),
    };
    let mut saw_preacceptance = false;
    for line in bytes.split_inclusive(|byte| *byte == b'\n') {
        let wire: PromotionJournalWire =
            parse_canonical_line(line, MAXIMUM_RECORD_BYTES, "promotion journal record")
                .map_err(|error| PromotionError::new(FailureCode::StateBurn, error.to_string()))?;
        match wire {
            PromotionJournalWire::Preacceptance(record) => {
                record.validate_shape()?;
                verify_chain_position(
                    &state,
                    record.sequence,
                    &record.previous_promotion_record_sha256,
                    &record.record_sha256,
                    record.recomputed_sha256()?,
                )?;
                insert_common_replay_keys(
                    &mut state,
                    &record.run_id,
                    &record.intent_sha256,
                    &record.transport_manifest_sha256,
                    &record.oracle_result_manifest_sha256,
                )?;
                for grant in &record.grants {
                    if !state.grant_replay_keys.insert(grant.replay_key()) {
                        return Err(replay_error());
                    }
                }
                advance_journal_state(&mut state, record.record_sha256)?;
                saw_preacceptance = true;
            }
            PromotionJournalWire::Legacy(record) => {
                if saw_preacceptance {
                    return Err(PromotionError::new(
                        FailureCode::StateBurn,
                        "legacy promotion records are only accepted before the preacceptance prefix transition",
                    ));
                }
                record.validate_shape()?;
                verify_chain_position(
                    &state,
                    record.sequence,
                    &record.previous_promotion_record_sha256,
                    &record.record_sha256,
                    record.recomputed_sha256()?,
                )?;
                insert_common_replay_keys(
                    &mut state,
                    &record.run_id,
                    &record.intent_sha256,
                    &record.transport_manifest_sha256,
                    &record.oracle_result_manifest_sha256,
                )?;
                for grant in &record.grants {
                    if !state.grant_replay_keys.insert(grant.clone()) {
                        return Err(replay_error());
                    }
                }
                advance_journal_state(&mut state, record.record_sha256)?;
            }
        }
    }
    Ok(state)
}

fn verify_chain_position(
    state: &PromotionJournalState,
    sequence: u64,
    previous_sha256: &str,
    record_sha256: &str,
    recomputed_sha256: String,
) -> PromotionResult<()> {
    if sequence != state.next_sequence
        || previous_sha256 != state.last_sha256
        || recomputed_sha256 != record_sha256
    {
        return Err(PromotionError::new(
            FailureCode::StateBurn,
            "promotion journal is not one contiguous recomputed genesis chain",
        ));
    }
    Ok(())
}

fn insert_common_replay_keys(
    state: &mut PromotionJournalState,
    run_id: &str,
    intent_sha256: &str,
    transport_manifest_sha256: &str,
    oracle_result_manifest_sha256: &str,
) -> PromotionResult<()> {
    if !state.run_ids.insert(run_id.to_owned())
        || !state.intent_sha256s.insert(intent_sha256.to_owned())
        || !state
            .transport_manifest_sha256s
            .insert(transport_manifest_sha256.to_owned())
        || !state
            .oracle_result_manifest_sha256s
            .insert(oracle_result_manifest_sha256.to_owned())
    {
        return Err(replay_error());
    }
    Ok(())
}

fn advance_journal_state(
    state: &mut PromotionJournalState,
    record_sha256: String,
) -> PromotionResult<()> {
    state.next_sequence = state.next_sequence.checked_add(1).ok_or_else(|| {
        PromotionError::new(
            FailureCode::StateBurn,
            "promotion journal sequence overflow",
        )
    })?;
    state.last_sha256 = record_sha256;
    Ok(())
}

fn replay_error() -> PromotionError {
    PromotionError::new(
        FailureCode::CoordinationReplay,
        "promotion journal contains a repeated cross-archive identity",
    )
}

#[cfg(test)]
pub(crate) fn synthetic_identity(salt: u8) -> PromotionIdentity {
    let digest = |n: u8| format!("{salt:02x}{n:02x}{}", "1".repeat(60));
    let mut identity = PromotionIdentity {
        run_id: format!("{salt:02x}{}", "2".repeat(30)),
        intent_bytes: 100 + u64::from(salt),
        intent_sha256: digest(1),
        grants: vec![
            PromotionGrantBinding {
                ledger_id: "hashsigs-project-coordination".to_owned(),
                entry_id: format!("project-{salt}"),
                entry_bytes: 200 + u64::from(salt),
                entry_sha256: digest(2),
            },
            PromotionGrantBinding {
                ledger_id: "ed25519-agent-coordination".to_owned(),
                entry_id: format!("ed25519-{salt}"),
                entry_bytes: 300 + u64::from(salt),
                entry_sha256: digest(3),
            },
        ],
        route_seal_sha256: digest(4),
        transport_manifest_sha256: digest(5),
        oracle_receipt_sha256: digest(6),
        oracle_result_manifest_sha256: digest(7),
        coordination_burn_sequence: 0,
        coordination_burn_previous_sha256: GENESIS_SHA256.to_owned(),
        coordination_burn_record_sha256: String::new(),
    };
    let grants = identity
        .grants
        .iter()
        .map(|grant| {
            CoordinationBurnGrantHashInput::new(
                &grant.ledger_id,
                &grant.entry_id,
                grant.entry_bytes,
                &grant.entry_sha256,
            )
        })
        .collect::<Vec<_>>();
    let record_sha256 = recompute_coordination_burn_record_sha256(
        identity.coordination_burn_sequence,
        &identity.run_id,
        identity.intent_bytes,
        &identity.intent_sha256,
        &grants,
        &identity.coordination_burn_previous_sha256,
    )
    .unwrap();
    identity.coordination_burn_record_sha256 = record_sha256;
    identity
}

#[cfg(test)]
fn legacy_record(identity: &PromotionIdentity) -> LegacyPromotionJournalRecord {
    let body = LegacyPromotionJournalBody {
        schema: LEGACY_JOURNAL_SCHEMA,
        contract: LEGACY_JOURNAL_CONTRACT.to_owned(),
        sequence: 0,
        run_id: identity.run_id.clone(),
        intent_sha256: identity.intent_sha256.clone(),
        grants: identity
            .grants
            .iter()
            .map(PromotionGrantBinding::replay_key)
            .collect(),
        route_seal_sha256: identity.route_seal_sha256.clone(),
        transport_manifest_sha256: identity.transport_manifest_sha256.clone(),
        oracle_receipt_sha256: identity.oracle_receipt_sha256.clone(),
        oracle_result_manifest_sha256: identity.oracle_result_manifest_sha256.clone(),
        coordination_burn_sequence: identity.coordination_burn_sequence,
        coordination_burn_previous_sha256: identity.coordination_burn_previous_sha256.clone(),
        coordination_burn_record_sha256: identity.coordination_burn_record_sha256.clone(),
        previous_promotion_record_sha256: GENESIS_SHA256.to_owned(),
    };
    let record_sha256 = body.sha256().unwrap();
    LegacyPromotionJournalRecord {
        schema: body.schema,
        contract: body.contract,
        sequence: body.sequence,
        run_id: body.run_id,
        intent_sha256: body.intent_sha256,
        grants: body.grants,
        route_seal_sha256: body.route_seal_sha256,
        transport_manifest_sha256: body.transport_manifest_sha256,
        oracle_receipt_sha256: body.oracle_receipt_sha256,
        oracle_result_manifest_sha256: body.oracle_result_manifest_sha256,
        coordination_burn_sequence: body.coordination_burn_sequence,
        coordination_burn_previous_sha256: body.coordination_burn_previous_sha256,
        coordination_burn_record_sha256: body.coordination_burn_record_sha256,
        previous_promotion_record_sha256: body.previous_promotion_record_sha256,
        record_sha256,
    }
}

#[cfg(test)]
mod tests {
    use super::{
        GENESIS_SHA256, PREACCEPTANCE_JOURNAL_CONTRACT, PreacceptanceJournalRecord,
        PromotionIdentity, legacy_record, synthetic_identity, verify_promotion_journal,
    };
    use crate::FailureCode;
    use crate::canonical::canonical_line;
    use crate::coordination::{
        CoordinationBurnGrantHashInput, MAXIMUM_COORDINATION_INTENT_BYTES,
        recompute_coordination_burn_record_sha256, synthetic_chain,
    };
    use crate::model::synthetic_request;

    fn recompute_journal_hash_only(record: &mut PreacceptanceJournalRecord) {
        record.record_sha256 = record.recomputed_sha256().unwrap();
    }

    fn recompute_copied_burn_and_journal(record: &mut PreacceptanceJournalRecord) {
        let grants = record
            .grants
            .iter()
            .map(|grant| {
                CoordinationBurnGrantHashInput::new(
                    &grant.ledger_id,
                    &grant.entry_id,
                    grant.entry_bytes,
                    &grant.entry_sha256,
                )
            })
            .collect::<Vec<_>>();
        let copied_burn_sha256 = recompute_coordination_burn_record_sha256(
            record.coordination_burn_sequence,
            &record.run_id,
            record.intent_bytes,
            &record.intent_sha256,
            &grants,
            &record.coordination_burn_previous_sha256,
        )
        .unwrap();
        record.coordination_burn_record_sha256 = copied_burn_sha256;
        recompute_journal_hash_only(record);
    }

    fn assert_journal_only_mutation_rejected(record: &mut PreacceptanceJournalRecord) {
        recompute_journal_hash_only(record);
        assert_eq!(
            verify_promotion_journal(&record.canonical_line().unwrap())
                .unwrap_err()
                .code(),
            FailureCode::StateBurn
        );
    }

    #[test]
    fn journal_hash_chain_round_trips_and_advances() {
        let empty = verify_promotion_journal(b"").unwrap();
        let first = empty.next_record(&synthetic_identity(1)).unwrap();
        let first_line = first.canonical_line().unwrap();
        let one = verify_promotion_journal(&first_line).unwrap();
        assert_eq!(one.next_sequence(), 1);
        let second = one.next_record(&synthetic_identity(2)).unwrap();
        let mut journal = first_line;
        journal.extend(second.canonical_line().unwrap());
        assert_eq!(
            verify_promotion_journal(&journal).unwrap().next_sequence(),
            2
        );
    }

    #[test]
    fn state_rejects_cross_archive_replay_before_append() {
        let empty = verify_promotion_journal(b"").unwrap();
        let first_identity = synthetic_identity(1);
        let first = empty.next_record(&first_identity).unwrap();
        let one = verify_promotion_journal(&first.canonical_line().unwrap()).unwrap();
        assert_eq!(
            one.next_record(&first_identity).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );

        let mut transport_replay = synthetic_identity(2);
        transport_replay
            .transport_manifest_sha256
            .clone_from(&first_identity.transport_manifest_sha256);
        assert_eq!(
            one.next_record(&transport_replay).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );
    }

    #[test]
    fn preacceptance_records_reject_same_grant_digest_with_different_bytes() {
        let empty = verify_promotion_journal(b"").unwrap();
        let first = empty.next_record(&synthetic_identity(1)).unwrap();
        let first_line = first.canonical_line().unwrap();
        let one = verify_promotion_journal(&first_line).unwrap();
        let mut second = one.next_record(&synthetic_identity(2)).unwrap();
        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;
        recompute_copied_burn_and_journal(&mut second);

        let mut journal = first_line;
        journal.extend(second.canonical_line().unwrap());
        assert_eq!(
            verify_promotion_journal(&journal).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );
    }

    #[test]
    fn copied_burn_fields_cannot_be_changed_by_rehashing_only_the_journal() {
        let empty = verify_promotion_journal(b"").unwrap();
        let original = empty.next_record(&synthetic_identity(1)).unwrap();

        let mut intent_bytes = original.clone();
        intent_bytes.intent_bytes += 1;
        assert_journal_only_mutation_rejected(&mut intent_bytes);

        let mut grant_bytes = original.clone();
        grant_bytes.grants[0].entry_bytes += 1;
        assert_journal_only_mutation_rejected(&mut grant_bytes);

        let mut burn_sequence = original.clone();
        burn_sequence.coordination_burn_sequence = 1;
        assert_journal_only_mutation_rejected(&mut burn_sequence);

        let mut copied_burn_digest = original.clone();
        copied_burn_digest.coordination_burn_record_sha256 = "e".repeat(64);
        assert_journal_only_mutation_rejected(&mut copied_burn_digest);

        let mut run_id = original;
        run_id.run_id = "f".repeat(32);
        assert_journal_only_mutation_rejected(&mut run_id);
    }

    #[test]
    fn copied_burn_caps_intent_and_requires_genesis_for_sequence_zero() {
        let empty = verify_promotion_journal(b"").unwrap();
        let original = empty.next_record(&synthetic_identity(1)).unwrap();

        let mut oversized_intent = original.clone();
        oversized_intent.intent_bytes = MAXIMUM_COORDINATION_INTENT_BYTES + 1;
        recompute_copied_burn_and_journal(&mut oversized_intent);
        assert_eq!(
            verify_promotion_journal(&oversized_intent.canonical_line().unwrap())
                .unwrap_err()
                .code(),
            FailureCode::StateBurn
        );

        let mut non_genesis = original;
        assert_eq!(
            non_genesis.coordination_burn_previous_sha256,
            GENESIS_SHA256
        );
        non_genesis.coordination_burn_previous_sha256 = "a".repeat(64);
        recompute_copied_burn_and_journal(&mut non_genesis);
        assert_eq!(
            verify_promotion_journal(&non_genesis.canonical_line().unwrap())
                .unwrap_err()
                .code(),
            FailureCode::StateBurn
        );
    }

    #[test]
    fn legacy_prefix_is_consumed_but_never_reemitted() {
        let legacy_identity = synthetic_identity(1);
        let legacy_line = canonical_line(&legacy_record(&legacy_identity)).unwrap();
        let state = verify_promotion_journal(&legacy_line).unwrap();

        let mut grant_replay = synthetic_identity(2);
        grant_replay.grants[0].ledger_id = legacy_identity.grants[0].ledger_id.clone();
        grant_replay.grants[0].entry_id = legacy_identity.grants[0].entry_id.clone();
        grant_replay.grants[0].entry_sha256 = legacy_identity.grants[0].entry_sha256.clone();
        grant_replay.grants[0].entry_bytes = legacy_identity.grants[0].entry_bytes + 1;
        assert_eq!(
            state.next_record(&grant_replay).unwrap_err().code(),
            FailureCode::CoordinationReplay
        );

        let next = state.next_record(&synthetic_identity(2)).unwrap();
        assert_eq!(next.schema, 1);
        assert_eq!(next.contract, PREACCEPTANCE_JOURNAL_CONTRACT);
        assert!(next.grants.iter().all(|grant| grant.entry_bytes > 0));
    }

    #[test]
    fn promotion_identity_requires_request_and_revalidated_burn_run_join() {
        let chain = synthetic_chain(7);
        let matching = synthetic_request(chain.selected_burn().run_id());
        assert!(
            PromotionIdentity::from_revalidated_burn(
                &matching,
                chain.selected_burn(),
                &"a".repeat(64),
                &"b".repeat(64),
                &"c".repeat(64),
                &"d".repeat(64),
            )
            .is_ok()
        );

        let mismatched = synthetic_request(&"f".repeat(32));
        assert_eq!(
            PromotionIdentity::from_revalidated_burn(
                &mismatched,
                chain.selected_burn(),
                &"a".repeat(64),
                &"b".repeat(64),
                &"c".repeat(64),
                &"d".repeat(64),
            )
            .unwrap_err()
            .code(),
            FailureCode::IdentityJoin
        );
    }
}