treeship_core/session/

package.rs

//! `.treeship` package builder and reader.
//!
//! A `.treeship` package is a directory (or tar archive) containing:
//!
//! - `receipt.json`   -- the canonical Session Receipt
//! - `merkle.json`    -- standalone Merkle tree data
//! - `render.json`    -- Explorer render hints
//! - `artifacts/`     -- referenced artifact payloads
//! - `proofs/`        -- inclusion proofs and zk proofs
//! - `preview.html`   -- static preview (optional)

use std::path::{Path, PathBuf};

use crate::statements::ApprovalStatement;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

use super::receipt::{SessionReceipt, RECEIPT_TYPE};
use crate::statements::{
    approval_revocation_record_digest, approval_use_record_digest,
    journal_checkpoint_record_digest, ApprovalRevocation, ApprovalUse, JournalCheckpoint,
    ReplayCheck, ReplayCheckLevel,
};

/// Errors from package operations.
#[derive(Debug)]
pub enum PackageError {
    Io(std::io::Error),
    Json(serde_json::Error),
    InvalidPackage(String),
}

impl std::fmt::Display for PackageError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Io(e) => write!(f, "package io: {e}"),
            Self::Json(e) => write!(f, "package json: {e}"),
            Self::InvalidPackage(msg) => write!(f, "invalid package: {msg}"),
        }
    }
}

impl std::error::Error for PackageError {}
impl From<std::io::Error> for PackageError {
    fn from(e: std::io::Error) -> Self {
        Self::Io(e)
    }
}
impl From<serde_json::Error> for PackageError {
    fn from(e: serde_json::Error) -> Self {
        Self::Json(e)
    }
}

/// Manifest file inside the package root.
const RECEIPT_FILE: &str = "receipt.json";
const MERKLE_FILE: &str = "merkle.json";
const RENDER_FILE: &str = "render.json";
const ARTIFACTS_DIR: &str = "artifacts";
const PROOFS_DIR: &str = "proofs";
const PREVIEW_FILE: &str = "preview.html";

// Approval Authority package layout (v0.9.9 PR 4).
// approvals/index.json -- top-level index of every approval evidence
//                          file in this package
// approvals/grants/<grant_id>.json    -- copy of the signed
//                          ApprovalStatement envelope (already in
//                          artifacts/ via the chain; mirrored here for
//                          single-directory access during verify)
// approvals/uses/<use_id>.json        -- ApprovalUse record from the
//                          local journal at session-close time
// approvals/checkpoints/<id>.json     -- JournalCheckpoint records that
//                          cover the included uses (PR 6 Hub
//                          checkpoint signing extends this)
const APPROVALS_DIR: &str = "approvals";
const APPROVALS_GRANTS: &str = "approvals/grants";
const APPROVALS_USES: &str = "approvals/uses";
const APPROVALS_CHECKPOINTS: &str = "approvals/checkpoints";
const APPROVALS_INDEX_FILE: &str = "approvals/index.json";

/// Optional approval evidence to embed in the package alongside the
/// receipt + artifacts. None means "no approvals consumed during this
/// session, or none worth exporting." Empty vectors mean "we looked and
/// found nothing"; the resulting package omits the `approvals/` dir
/// entirely so absence is unambiguous.
///
/// Ownership of the evidence stays with the caller: `session::close`
/// gathers the grant envelopes from the chain, the uses from the local
/// journal, and any covering checkpoints, then hands them off here.
#[derive(Debug, Clone, Default)]
pub struct ApprovalsBundle {
    /// Bytes of the signed ApprovalStatement envelopes that authorized
    /// any consumed uses. Each entry is `(grant_id, raw_envelope_json)`.
    /// Stored verbatim so the package's verifier can re-check the
    /// signature without re-serializing.
    pub grants: Vec<(String, Vec<u8>)>,
    /// ApprovalUse records pulled from the local journal at close time.
    /// `action_artifact_id` should be backfilled before passing to
    /// build_package (see `commands/session.rs`).
    pub uses: Vec<ApprovalUse>,
    /// JournalCheckpoints that cover the included uses. Optional; may
    /// be empty even when uses are present (PR 6 fills these in).
    pub checkpoints: Vec<JournalCheckpoint>,
    /// Explicit revocations we wanted to surface (e.g. a use whose
    /// grant was revoked after consumption -- the package should still
    /// show the consumed evidence and the revocation alongside).
    /// Empty in PR 4; reserved.
    pub revocations: Vec<ApprovalRevocation>,

    /// Bytes of each action artifact's signed envelope that consumed an
    /// approval. Each entry is `(action_artifact_id, raw_envelope_json)`.
    /// v0.9.10 PR A: shipped to close the action↔use binding gap. The
    /// verifier extracts `meta.approval_use_id` from each envelope and
    /// cross-checks it against the package's use records. Empty in
    /// pre-v0.9.10 packages; readers must treat absence as "binding
    /// not asserted by package" rather than "binding present and OK."
    pub action_envelopes: Vec<(String, Vec<u8>)>,
}

/// `approvals/index.json` -- top-level inventory of evidence in the
/// package. Lets a consumer pre-flight what's there before opening
/// every file; doubles as a stable shape for downstream tooling.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApprovalsIndex {
    /// Stable schema marker so future versions can fan out cleanly.
    #[serde(rename = "type")]
    pub type_: String,
    pub schema_version: u32,
    /// Stable kebab-case ids of grants present. Order matches
    /// `grants/` filename order.
    pub grants: Vec<String>,
    /// Use ids present.
    pub uses: Vec<String>,
    pub checkpoints: Vec<String>,
    pub revocations: Vec<String>,
}

impl ApprovalsIndex {
    pub fn type_string() -> &'static str {
        "treeship/approvals-index/v1"
    }
}

/// Result of building a package.
pub struct PackageOutput {
    /// Path to the package directory.
    pub path: PathBuf,
    /// SHA-256 digest of the canonical receipt.json.
    pub receipt_digest: String,
    /// Merkle root hex (if present).
    pub merkle_root: Option<String>,
    /// Number of files in the package.
    pub file_count: usize,
}

/// Build a `.treeship` package directory from a composed receipt.
///
/// Writes all package files into `output_dir/<session_id>.treeship/`.
/// Returns metadata about the written package.
///
/// Backwards-compatible wrapper: callers that don't have approval
/// evidence to export pass through here unchanged. Callers that do
/// (`session::close` with consumed approvals) call
/// `build_package_with_approvals` directly.
pub fn build_package(
    receipt: &SessionReceipt,
    output_dir: &Path,
) -> Result<PackageOutput, PackageError> {
    build_package_with_approvals(receipt, output_dir, None)
}

/// Like `build_package` but also embeds approval evidence (PR 4 of v0.9.9).
/// `bundle = None` is identical to `build_package`; the `approvals/`
/// directory is omitted entirely so absence stays unambiguous.
pub fn build_package_with_approvals(
    receipt: &SessionReceipt,
    output_dir: &Path,
    bundle: Option<&ApprovalsBundle>,
) -> Result<PackageOutput, PackageError> {
    let session_id = &receipt.session.id;
    let pkg_dir = output_dir.join(format!("{session_id}.treeship"));

    std::fs::create_dir_all(&pkg_dir)?;
    std::fs::create_dir_all(pkg_dir.join(ARTIFACTS_DIR))?;
    std::fs::create_dir_all(pkg_dir.join(PROOFS_DIR))?;

    let mut file_count = 0usize;

    // 1. receipt.json -- canonical serialization
    let receipt_bytes = serde_json::to_vec_pretty(receipt)?;
    std::fs::write(pkg_dir.join(RECEIPT_FILE), &receipt_bytes)?;
    file_count += 1;

    let receipt_hash = Sha256::digest(&receipt_bytes);
    let receipt_digest = format!("sha256:{}", hex::encode(receipt_hash));

    // 2. merkle.json -- standalone copy of the Merkle section
    let merkle_bytes = serde_json::to_vec_pretty(&receipt.merkle)?;
    std::fs::write(pkg_dir.join(MERKLE_FILE), &merkle_bytes)?;
    file_count += 1;

    // 3. render.json
    let render_bytes = serde_json::to_vec_pretty(&receipt.render)?;
    std::fs::write(pkg_dir.join(RENDER_FILE), &render_bytes)?;
    file_count += 1;

    // 4. Write inclusion proofs as individual files
    for proof_entry in &receipt.merkle.inclusion_proofs {
        let proof_bytes = serde_json::to_vec_pretty(proof_entry)?;
        let filename = format!("{}.proof.json", proof_entry.artifact_id);
        std::fs::write(pkg_dir.join(PROOFS_DIR).join(filename), &proof_bytes)?;
        file_count += 1;
    }

    // 5. preview.html stub
    if receipt.render.generate_preview {
        let preview = render_preview_html_with_approvals(receipt, bundle);
        std::fs::write(pkg_dir.join(PREVIEW_FILE), preview.as_bytes())?;
        file_count += 1;
    }

    // 6. Approval evidence (v0.9.9 PR 4). Only writes when the caller
    // supplied a bundle AND that bundle has at least one entry; an empty
    // bundle behaves the same as None so a session with no consumed
    // approvals doesn't leave behind an empty `approvals/` directory.
    if let Some(b) = bundle {
        if !b.grants.is_empty()
            || !b.uses.is_empty()
            || !b.checkpoints.is_empty()
            || !b.revocations.is_empty()
            || !b.action_envelopes.is_empty()
        {
            std::fs::create_dir_all(pkg_dir.join(APPROVALS_GRANTS))?;
            std::fs::create_dir_all(pkg_dir.join(APPROVALS_USES))?;
            std::fs::create_dir_all(pkg_dir.join(APPROVALS_CHECKPOINTS))?;
            // v0.9.10 PR A: write action envelopes that consumed an
            // approval. The artifacts/ directory was created earlier
            // for the package layout but never populated; closing the
            // action↔use binding gap requires the verifier to be able
            // to read each consuming action's `meta.approval_use_id`.
            std::fs::create_dir_all(pkg_dir.join(ARTIFACTS_DIR))?;
            for (artifact_id, envelope_bytes) in &b.action_envelopes {
                let safe = sanitize_filename(artifact_id);
                std::fs::write(
                    pkg_dir.join(ARTIFACTS_DIR).join(format!("{safe}.json")),
                    envelope_bytes,
                )?;
                file_count += 1;
            }

            let mut grant_ids = Vec::with_capacity(b.grants.len());
            for (grant_id, envelope_bytes) in &b.grants {
                let safe = sanitize_filename(grant_id);
                std::fs::write(
                    pkg_dir.join(APPROVALS_GRANTS).join(format!("{safe}.json")),
                    envelope_bytes,
                )?;
                grant_ids.push(grant_id.clone());
                file_count += 1;
            }

            let mut use_ids = Vec::with_capacity(b.uses.len());
            for u in &b.uses {
                let safe = sanitize_filename(&u.use_id);
                let bytes = serde_json::to_vec_pretty(u)?;
                std::fs::write(
                    pkg_dir.join(APPROVALS_USES).join(format!("{safe}.json")),
                    &bytes,
                )?;
                use_ids.push(u.use_id.clone());
                file_count += 1;
            }

            let mut checkpoint_ids = Vec::with_capacity(b.checkpoints.len());
            for cp in &b.checkpoints {
                let safe = sanitize_filename(&cp.checkpoint_id);
                let bytes = serde_json::to_vec_pretty(cp)?;
                std::fs::write(
                    pkg_dir
                        .join(APPROVALS_CHECKPOINTS)
                        .join(format!("{safe}.json")),
                    &bytes,
                )?;
                checkpoint_ids.push(cp.checkpoint_id.clone());
                file_count += 1;
            }

            let mut revocation_ids = Vec::with_capacity(b.revocations.len());
            for rev in &b.revocations {
                let safe = sanitize_filename(&rev.revocation_id);
                let bytes = serde_json::to_vec_pretty(rev)?;
                std::fs::write(
                    pkg_dir
                        .join(APPROVALS_DIR)
                        .join(format!("revocations-{safe}.json")),
                    &bytes,
                )?;
                revocation_ids.push(rev.revocation_id.clone());
                file_count += 1;
            }

            let index = ApprovalsIndex {
                type_: ApprovalsIndex::type_string().into(),
                schema_version: 1,
                grants: grant_ids,
                uses: use_ids,
                checkpoints: checkpoint_ids,
                revocations: revocation_ids,
            };
            let index_bytes = serde_json::to_vec_pretty(&index)?;
            std::fs::write(pkg_dir.join(APPROVALS_INDEX_FILE), &index_bytes)?;
            file_count += 1;
        }
    }

    Ok(PackageOutput {
        path: pkg_dir,
        receipt_digest,
        merkle_root: receipt.merkle.root.clone(),
        file_count,
    })
}

/// Sanitize an id (artifact_id, use_id, checkpoint_id) into a filesystem-safe
/// filename. Underscores everything that isn't alphanumeric, dash, or dot.
/// Not a security boundary; the digest chain is the integrity check.
fn sanitize_filename(s: &str) -> String {
    s.chars()
        .map(|c| {
            if c.is_ascii_alphanumeric() || c == '-' || c == '.' || c == '_' {
                c
            } else {
                '_'
            }
        })
        .collect()
}

/// Read approval evidence embedded in a package, if any. Returns
/// `Ok(ApprovalsBundle::default())` when the package has no `approvals/`
/// directory (the typical case for sessions that didn't consume any
/// scoped approvals). Errors only on malformed JSON inside files that
/// the index claims exist.
///
/// Quiet on missing-directory by design: PR 4 packages and pre-PR-4
/// packages should both round-trip through verify without spurious
/// failures.
pub fn read_approvals_bundle(pkg_dir: &Path) -> Result<ApprovalsBundle, PackageError> {
    let approvals_dir = pkg_dir.join(APPROVALS_DIR);
    if !approvals_dir.is_dir() {
        return Ok(ApprovalsBundle::default());
    }

    let mut bundle = ApprovalsBundle::default();

    // Grants are raw envelopes by file; we don't parse here, the
    // verify layer can re-check the signature.
    let grants_dir = pkg_dir.join(APPROVALS_GRANTS);
    if grants_dir.is_dir() {
        for entry in std::fs::read_dir(&grants_dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("json") {
                continue;
            }
            let id = path
                .file_stem()
                .and_then(|s| s.to_str())
                .unwrap_or("")
                .to_string();
            let bytes = std::fs::read(&path)?;
            bundle.grants.push((id, bytes));
        }
    }

    let uses_dir = pkg_dir.join(APPROVALS_USES);
    if uses_dir.is_dir() {
        for entry in std::fs::read_dir(&uses_dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("json") {
                continue;
            }
            let bytes = std::fs::read(&path)?;
            let u: ApprovalUse = serde_json::from_slice(&bytes)?;
            bundle.uses.push(u);
        }
    }

    let cps_dir = pkg_dir.join(APPROVALS_CHECKPOINTS);
    if cps_dir.is_dir() {
        for entry in std::fs::read_dir(&cps_dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("json") {
                continue;
            }
            let bytes = std::fs::read(&path)?;
            let cp: JournalCheckpoint = serde_json::from_slice(&bytes)?;
            bundle.checkpoints.push(cp);
        }
    }

    // v0.9.10 PR A: read action envelopes shipped to support the
    // action↔use binding check. Pre-v0.9.10 packages have an empty
    // artifacts/ dir (the dir was created but never populated); the
    // bundle's `action_envelopes` stays empty in that case, and the
    // verifier reports the binding row honestly as "not asserted by
    // package" rather than silently passing.
    let arts_dir = pkg_dir.join(ARTIFACTS_DIR);
    if arts_dir.is_dir() {
        for entry in std::fs::read_dir(&arts_dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("json") {
                continue;
            }
            let id = path
                .file_stem()
                .and_then(|s| s.to_str())
                .unwrap_or("")
                .to_string();
            let bytes = std::fs::read(&path)?;
            bundle.action_envelopes.push((id, bytes));
        }
    }

    Ok(bundle)
}

/// Read and parse a `.treeship` package from disk.
pub fn read_package(pkg_dir: &Path) -> Result<SessionReceipt, PackageError> {
    let receipt_path = pkg_dir.join(RECEIPT_FILE);
    if !receipt_path.exists() {
        return Err(PackageError::InvalidPackage(format!(
            "missing {RECEIPT_FILE} in {}",
            pkg_dir.display()
        )));
    }
    let bytes = std::fs::read(&receipt_path)?;
    let receipt: SessionReceipt = serde_json::from_slice(&bytes)?;

    if receipt.type_ != RECEIPT_TYPE {
        return Err(PackageError::InvalidPackage(format!(
            "unexpected type: {} (expected {RECEIPT_TYPE})",
            receipt.type_
        )));
    }

    Ok(receipt)
}

/// Verify a `.treeship` package locally.
///
/// Returns a list of check results. All must pass for the package to be valid.
///
/// Auto-loads the operator's trust roots from
/// `TrustRootStore::default_path()`. Use
/// [`verify_package_with_trust`] when the trust store is already in
/// hand (CLI paths that take a `Ctx`, or tests).
///
/// Audit lane J fix-up: `open_default_or_empty` propagates `Malformed`
/// and `PermissionsTooOpen` errors -- those are operator
/// misconfiguration that must NOT be silently downgraded to an empty
/// trust store (an empty store fails verification of any hub-org
/// checkpoint, which is the right end-state, but the operator needs a
/// clear "your trust file is broken" diagnostic instead of a misleading
/// "untrusted issuer" message). Surface the error as a `trust-root`
/// fail row and stop before doing real work that depends on trust.
pub fn verify_package(pkg_dir: &Path) -> Result<Vec<VerifyCheck>, PackageError> {
    let trust = match crate::trust::TrustRootStore::open_default_or_empty() {
        Ok(t) => t,
        Err(e) => {
            // Build a minimal check list so the caller's printer still
            // renders a coherent failure rather than silently routing
            // through a fake empty store.
            return Ok(vec![VerifyCheck::fail(
                "trust-root",
                &format!("trust store unreadable: {e}"),
            )]);
        }
    };
    verify_package_with_trust(pkg_dir, &trust)
}

/// Like `verify_package` but takes an explicit `TrustRootStore` so the
/// caller can verify with a constructed-in-memory trust set (tests) or
/// a non-default location (CLI `--trust-roots`).
pub fn verify_package_with_trust(
    pkg_dir: &Path,
    trust: &crate::trust::TrustRootStore,
) -> Result<Vec<VerifyCheck>, PackageError> {
    let mut checks = Vec::new();

    // 1. receipt.json exists and parses
    let receipt = match read_package(pkg_dir) {
        Ok(r) => {
            checks.push(VerifyCheck::pass(
                "receipt.json",
                "Parses as valid Session Receipt",
            ));
            r
        }
        Err(e) => {
            checks.push(VerifyCheck::fail(
                "receipt.json",
                &format!("Failed to parse: {e}"),
            ));
            return Ok(checks);
        }
    };

    // 2. Type field
    if receipt.type_ == RECEIPT_TYPE {
        checks.push(VerifyCheck::pass("type", "Correct receipt type"));
    } else {
        checks.push(VerifyCheck::fail(
            "type",
            &format!("Expected {RECEIPT_TYPE}, got {}", receipt.type_),
        ));
    }

    // 3. Determinism: re-serialize and check digest matches.
    //
    // IMPORTANT SCOPE NOTE (do not read this row as integrity): this only
    // confirms the receipt struct round-trips to the same bytes. It is NOT a
    // signature check. The Merkle root below covers ONLY the artifact IDs;
    // the receipt's timeline, side_effects, tool_usage, and narrative are
    // composed from the (unsigned) event log and are NOT cryptographically
    // bound by anything in this package. An attacker who edits those fields
    // and re-serializes will pass determinism and pass the Merkle check.
    // The authenticated anchor over the whole receipt is the actor-signed
    // `session.v1` record (which binds receipt_digest) in the agent's chain;
    // embedding + requiring it here is tracked as a follow-up. Until then,
    // `package verify` authenticates the ARTIFACTS, not the narrative, and
    // says so via the explicit scope check below.
    let receipt_path = pkg_dir.join(RECEIPT_FILE);
    let on_disk = std::fs::read(&receipt_path)?;
    let re_serialized = serde_json::to_vec_pretty(&receipt)?;
    if on_disk == re_serialized {
        checks.push(VerifyCheck::pass(
            "determinism",
            "receipt.json round-trips identically (structural, NOT a signature)",
        ));
    } else {
        // Not a hard failure -- pretty-print whitespace may differ
        checks.push(VerifyCheck::warn(
            "determinism",
            "receipt.json does not byte-match after re-serialization",
        ));
    }

    // 3b. Honest scope of what this package authenticates. The receipt body
    // (timeline / side_effects / tool_usage / narrative) is derived from the
    // unsigned event log and carries no signature in the package, so a reader
    // must not mistake a green package for an authenticated ledger of what
    // the agent did. Only the artifacts + Merkle root are cryptographically
    // bound.
    checks.push(VerifyCheck::warn(
        "receipt_body_binding",
        "timeline/side-effects/narrative are NOT signed in this package — only the artifacts and Merkle root are cryptographically bound. For an authenticated record of the session, verify the actor-signed session.v1 record (or the published report).",
    ));

    // 4. Merkle root re-computation
    if !receipt.artifacts.is_empty() {
        // Recompute under the receipt's declared merkle version so
        // legacy (v0.10.2 and earlier, version=1, no domain separation)
        // receipts continue to verify. New receipts always emit v2.
        // Construct through the validating `with_version` so an unknown
        // version surfaces as a hard fail rather than silently falling
        // back to v1.
        let version = receipt.merkle.merkle_version;
        let mut tree = match crate::merkle::MerkleTree::with_version(version) {
            Ok(t) => t,
            Err(e) => {
                checks.push(VerifyCheck::fail(
                    "merkle_root",
                    &format!("receipt declared unknown merkle_version: {e}"),
                ));
                // Skip the remaining merkle/inclusion work; emit the
                // leaf_count + timeline tail and return.
                return Ok(finish_package_checks(checks, &receipt));
            }
        };
        for art in &receipt.artifacts {
            tree.append(&art.artifact_id);
        }
        let root_bytes = tree.root();
        let recomputed_root = root_bytes.map(|r| format!("mroot_{}", hex::encode(r)));
        let root_hex = root_bytes.map(hex::encode).unwrap_or_default();

        if recomputed_root == receipt.merkle.root {
            checks.push(VerifyCheck::pass(
                "merkle_root",
                "Merkle root matches recomputed value",
            ));
        } else {
            checks.push(VerifyCheck::fail(
                "merkle_root",
                &format!(
                    "Mismatch: on-disk {:?} vs recomputed {:?}",
                    receipt.merkle.root, recomputed_root
                ),
            ));
        }

        // 5. Verify each inclusion proof. Per-proof merkle_version must
        // match the receipt section's declared version — drift is a
        // hard fail (smuggled v1 proof inside a v2 receipt would
        // otherwise dispatch through the weaker hashing path).
        for proof_entry in &receipt.merkle.inclusion_proofs {
            if proof_entry.proof.merkle_version != version {
                checks.push(VerifyCheck::fail(
                    &format!("inclusion:{}", proof_entry.artifact_id),
                    &format!(
                        "proof merkle_version {} != receipt section v{}",
                        proof_entry.proof.merkle_version, version,
                    ),
                ));
                continue;
            }
            let verified = crate::merkle::MerkleTree::verify_proof(
                version,
                &root_hex,
                &proof_entry.artifact_id,
                &proof_entry.proof,
            );
            if verified {
                checks.push(VerifyCheck::pass(
                    &format!("inclusion:{}", proof_entry.artifact_id),
                    "Inclusion proof valid",
                ));
            } else {
                checks.push(VerifyCheck::fail(
                    &format!("inclusion:{}", proof_entry.artifact_id),
                    "Inclusion proof failed verification",
                ));
            }
        }
    } else {
        checks.push(VerifyCheck::warn("merkle_root", "No artifacts to verify"));
    }

    // 6. Leaf count matches artifacts
    if receipt.merkle.leaf_count == receipt.artifacts.len() {
        checks.push(VerifyCheck::pass(
            "leaf_count",
            "Leaf count matches artifact count",
        ));
    } else {
        checks.push(VerifyCheck::fail(
            "leaf_count",
            &format!(
                "leaf_count {} != artifact count {}",
                receipt.merkle.leaf_count,
                receipt.artifacts.len()
            ),
        ));
    }

    // 7. Timeline ordering (determinism rule: timestamp, sequence_no, event_id)
    let ordered = receipt.timeline.windows(2).all(|w| {
        (&w[0].timestamp, w[0].sequence_no, &w[0].event_id)
            <= (&w[1].timestamp, w[1].sequence_no, &w[1].event_id)
    });
    if ordered {
        checks.push(VerifyCheck::pass(
            "timeline_order",
            "Timeline is correctly ordered",
        ));
    } else {
        checks.push(VerifyCheck::fail(
            "timeline_order",
            "Timeline entries are not in deterministic order",
        ));
    }

    // event_log completeness: when session::close skipped malformed
    // event log lines, the count is recorded on receipt.proofs.event_log_skipped.
    // Surface as WARN (not FAIL) because the receipt is still
    // cryptographically valid -- we just want a downstream verifier to
    // know that some evidence was dropped before the receipt was sealed.
    // A future --strict flag can promote this to FAIL.
    // Codex adversarial review finding #8.
    if receipt.proofs.event_log_skipped > 0 {
        checks.push(VerifyCheck::warn(
            "event_log_completeness",
            &format!(
                "{} event(s) skipped during close (malformed lines in events.jsonl). \
                 Receipt is cryptographically valid but does not represent the full event stream. \
                 Inspect close-time stderr or the events.jsonl directly to investigate.",
                receipt.proofs.event_log_skipped,
            ),
        ));
    }

    if receipt.proofs.reconcile_untracked_truncated > 0 {
        checks.push(VerifyCheck::warn(
            "reconcile_completeness",
            &format!(
                "untracked git reconcile exceeded cap {} (saw at least {}). \
                 Per-file synthetic events were skipped and the receipt is bounded, not complete for untracked files.",
                receipt.proofs.reconcile_untracked_cap,
                receipt.proofs.reconcile_untracked_truncated,
            ),
        ));
    }

    // AUD-07: the git-diff backstop was disabled between session start and
    // close (git worked at start — a HEAD was captured — but not at close).
    // A file changed via a non-AgentWroteFile channel could be missing from
    // the "Files changed" ledger with no other signal, so this must not read
    // as a clean, complete audit trail.
    if receipt.proofs.reconcile_degraded {
        checks.push(VerifyCheck::warn(
            "reconcile_degraded",
            "the git reconcile backstop was UNAVAILABLE at session close although git worked at start \
             (.git removed, corrupt index, or git not on PATH). Files changed outside a captured \
             AgentWroteFile event may be MISSING from this receipt's file ledger — treat the \
             \"Files changed\" list as incomplete.",
        ));
    }

    // 8. Approval evidence -- v0.9.9 PR 4. Three independent replay
    // checks, each emitted as its own VerifyCheck row so the printer
    // (and downstream tooling) can render them separately.
    //
    //   replay-package-local      duplicate uses INSIDE this package
    //   replay-included-checkpoint  embedded JournalCheckpoints verify standalone
    //
    // The local-journal level requires access to the workspace journal,
    // which the package alone doesn't carry; that check runs in the CLI
    // verify_package wrapper that has Ctx access. The hub-org level is
    // reserved for PR 6 -- not claimed without a real Hub checkpoint.
    let bundle = read_approvals_bundle(pkg_dir).unwrap_or_default();
    add_approval_evidence_checks(&mut checks, &bundle, trust);

    Ok(checks)
}

/// Tail of `verify_package`: emit leaf_count and timeline-order checks.
/// Used by the early-return path when an unknown merkle version aborts
/// Merkle recomputation — those two checks are independent of the tree
/// version and still meaningful to surface.
fn finish_package_checks(
    mut checks: Vec<VerifyCheck>,
    receipt: &SessionReceipt,
) -> Vec<VerifyCheck> {
    if receipt.merkle.leaf_count == receipt.artifacts.len() {
        checks.push(VerifyCheck::pass(
            "leaf_count",
            "Leaf count matches artifact count",
        ));
    } else {
        checks.push(VerifyCheck::fail(
            "leaf_count",
            &format!(
                "leaf_count {} != artifact count {}",
                receipt.merkle.leaf_count,
                receipt.artifacts.len(),
            ),
        ));
    }

    let ordered = receipt.timeline.windows(2).all(|w| {
        (&w[0].timestamp, w[0].sequence_no, &w[0].event_id)
            <= (&w[1].timestamp, w[1].sequence_no, &w[1].event_id)
    });
    if ordered {
        checks.push(VerifyCheck::pass(
            "timeline_order",
            "Timeline is correctly ordered",
        ));
    } else {
        checks.push(VerifyCheck::fail(
            "timeline_order",
            "Timeline entries are not in deterministic order",
        ));
    }

    checks
}

/// Emit the package-local + included-checkpoint replay checks. Both are
/// fully offline: package-local scans the embedded uses for duplicates;
/// included-checkpoint walks the embedded checkpoint records and
/// re-derives each `record_digest` against its stored value.
///
/// The local-journal check is NOT here -- it requires workspace access
/// and is added by the CLI wrapper in `commands/package.rs` that has the
/// resolved config_path. Keeping these two pure means an offline tool
/// (Hub-side validator, third-party verifier) can run the same checks
/// without needing a Treeship workspace.
pub(crate) fn add_approval_evidence_checks(
    checks: &mut Vec<VerifyCheck>,
    bundle: &ApprovalsBundle,
    trust: &crate::trust::TrustRootStore,
) {
    if bundle.uses.is_empty() && bundle.checkpoints.is_empty() {
        // Nothing to assert. Stay quiet rather than emit a "skipped"
        // row -- session packages without approvals shouldn't drag in
        // approval rows by accident.
        return;
    }

    // -- replay-package-local --
    // Two distinct violation cases inside the package:
    //   (a) uses sharing (grant_id, nonce_digest) EXCEED max_uses on
    //       that grant. Two uses of a max_uses=2 grant is fine; three
    //       is the violation. max_uses is read from the use record's
    //       own `max_uses` field (a snapshot from consume time).
    //   (b) two ApprovalUse records with the same use_id -- a copy
    //       artifact from a corrupt build, never legitimate.
    use std::collections::HashMap;
    let mut by_nonce: HashMap<(String, String), Vec<&ApprovalUse>> = HashMap::new();
    let mut by_use_id: HashMap<&str, Vec<&ApprovalUse>> = HashMap::new();
    for u in &bundle.uses {
        by_nonce
            .entry((u.grant_id.clone(), u.nonce_digest.clone()))
            .or_default()
            .push(u);
        by_use_id.entry(&u.use_id).or_default().push(u);
    }
    let over_max: Vec<((String, String), Vec<&ApprovalUse>, u32)> = by_nonce
        .iter()
        .filter_map(|(key, uses)| {
            let max = uses.iter().filter_map(|u| u.max_uses).next()?;
            if (uses.len() as u32) > max {
                Some((key.clone(), uses.to_vec(), max))
            } else {
                None
            }
        })
        .collect();
    let dup_use_ids: Vec<(&&str, &Vec<&ApprovalUse>)> =
        by_use_id.iter().filter(|(_, v)| v.len() > 1).collect();

    if over_max.is_empty() && dup_use_ids.is_empty() {
        checks.push(VerifyCheck::pass(
            "replay-package-local",
            &format!(
                "no duplicate approval use inside package ({} uses scanned)",
                bundle.uses.len()
            ),
        ));
    } else {
        let mut detail = String::from("package-local replay violation:");
        for ((grant_id, _nd), uses, max) in &over_max {
            detail.push_str(&format!(
                " grant {grant_id} consumed {} times in this package (max_uses={max});",
                uses.len(),
            ));
        }
        for (uid, uses) in &dup_use_ids {
            detail.push_str(&format!(" use_id {uid} appears {} times;", uses.len()));
        }
        checks.push(VerifyCheck::fail("replay-package-local", &detail));
    }

    // -- replay-included-checkpoint --
    // For each checkpoint, recompute its record_digest from canonical
    // form. If the stored digest doesn't match, the checkpoint was
    // tampered after sealing.
    if !bundle.checkpoints.is_empty() {
        let mut tampered = Vec::new();
        for cp in &bundle.checkpoints {
            let recomputed = journal_checkpoint_record_digest(cp);
            if recomputed != cp.record_digest {
                tampered.push((
                    cp.checkpoint_id.clone(),
                    cp.record_digest.clone(),
                    recomputed,
                ));
            }
        }
        if tampered.is_empty() {
            checks.push(VerifyCheck::pass(
                "replay-included-checkpoint",
                &format!(
                    "{} included journal checkpoint(s) verify offline",
                    bundle.checkpoints.len()
                ),
            ));
        } else {
            let detail = tampered
                .iter()
                .map(|(id, expected, actual)| {
                    format!("checkpoint {id} tampered (stored {expected}, recomputed {actual})")
                })
                .collect::<Vec<_>>()
                .join("; ");
            checks.push(VerifyCheck::fail("replay-included-checkpoint", &detail));
        }
    }

    // -- approval-use-record-digest --
    // Each ApprovalUse carries its own record_digest computed over the
    // canonical form of the record (minus the digest itself). Tampering
    // any field changes the digest. v0.9.10 PR A renames this from the
    // older `approval-use-integrity` because the prior label suggested
    // it covered nonce/action binding -- it didn't, and Codex's v0.9.9
    // adversarial review flagged the over-claim. The honest scope of
    // this row is "each use's stored digest matches its canonical
    // recompute"; the binding checks are now separate rows below.
    let mut tampered_uses = Vec::new();
    for u in &bundle.uses {
        let recomputed = approval_use_record_digest(u);
        if recomputed != u.record_digest {
            tampered_uses.push((u.use_id.clone(), u.record_digest.clone(), recomputed));
        }
    }
    if !bundle.uses.is_empty() {
        if tampered_uses.is_empty() {
            checks.push(VerifyCheck::pass(
                "approval-use-record-digest",
                &format!("{} use record(s) recompute identically", bundle.uses.len()),
            ));
        } else {
            let detail = tampered_uses
                .iter()
                .map(|(id, expected, actual)| {
                    format!("use {id} tampered (stored {expected}, recomputed {actual})")
                })
                .collect::<Vec<_>>()
                .join("; ");
            checks.push(VerifyCheck::fail("approval-use-record-digest", &detail));
        }
    }

    // -- approval-use-nonce-binding --
    // Cross-check each use's `nonce_digest` against the corresponding
    // grant's *signed* nonce. v0.9.9 trusted the use's nonce_digest
    // verbatim, which let an attacker who controls the package mutate
    // it (and recompute record_digest) to claim consumption of a grant
    // whose nonce was never actually used. This row closes that gap.
    //
    // Discipline: the grant envelope is the source of truth. Before
    // pulling the raw `nonce` from the grant's payload we verify the
    // envelope's *content addressing* -- recompute the artifact_id
    // from the envelope's PAE bytes and confirm it equals the grant_id
    // the package claims. v0.9.10 PR A round 1 only parsed the
    // envelope without this check; that left a forgery window where
    // an attacker could ship an arbitrary unsigned envelope under any
    // grant_id filename. v0.9.10 PR A round 2 closes the window: only
    // a bytes-identical envelope produces the same artifact_id under
    // SHA-256.
    if !bundle.uses.is_empty() {
        use crate::attestation::envelope::Envelope;
        use crate::attestation::{artifact_id_from_pae, pae};
        use crate::statements::{nonce_digest, ApprovalStatement};
        let mut grant_nonce_digest: std::collections::HashMap<String, String> =
            std::collections::HashMap::new();
        let mut tampered_grants: Vec<String> = Vec::new();
        for (grant_id, env_bytes) in &bundle.grants {
            let env = match Envelope::from_json(env_bytes) {
                Ok(e) => e,
                Err(_) => {
                    tampered_grants.push(format!("grant {grant_id} envelope unparseable"));
                    continue;
                }
            };
            // Content-addressing check: derive the artifact_id from
            // the envelope's PAE bytes and confirm it matches the
            // claimed grant_id. If they differ the envelope was
            // substituted or its bytes were tampered post-sign.
            let derived = match env.payload_bytes() {
                Ok(p) => artifact_id_from_pae(&pae(&env.payload_type, &p)),
                Err(_) => {
                    tampered_grants.push(format!("grant {grant_id} envelope payload undecodable"));
                    continue;
                }
            };
            if &derived != grant_id {
                tampered_grants.push(format!(
                    "grant {grant_id} envelope content derives to {derived} -- envelope substituted or tampered",
                ));
                continue;
            }
            let approval: ApprovalStatement = match env.unmarshal_statement() {
                Ok(a) => a,
                Err(_) => {
                    tampered_grants
                        .push(format!("grant {grant_id} payload not an ApprovalStatement"));
                    continue;
                }
            };
            grant_nonce_digest.insert(grant_id.clone(), nonce_digest(&approval.nonce));
        }
        let mut mismatches: Vec<String> = Vec::new();
        let mut missing_grants: Vec<String> = Vec::new();
        for u in &bundle.uses {
            match grant_nonce_digest.get(&u.grant_id) {
                Some(expected) => {
                    if expected != &u.nonce_digest {
                        mismatches.push(format!(
                            "use {} claims nonce_digest {} but grant {} signed nonce hashes to {}",
                            u.use_id, u.nonce_digest, u.grant_id, expected,
                        ));
                    }
                }
                None => {
                    missing_grants.push(format!(
                        "use {} references grant {} but no usable grant envelope is in the package",
                        u.use_id, u.grant_id,
                    ));
                }
            }
        }
        if mismatches.is_empty() && missing_grants.is_empty() && tampered_grants.is_empty() {
            checks.push(VerifyCheck::pass(
                "approval-use-nonce-binding",
                &format!(
                    "{} use record(s) bind to content-addressed grant signed nonces",
                    bundle.uses.len(),
                ),
            ));
        } else {
            let mut parts: Vec<String> = Vec::new();
            if !tampered_grants.is_empty() {
                parts.push(tampered_grants.join("; "));
            }
            if !mismatches.is_empty() {
                parts.push(mismatches.join("; "));
            }
            if !missing_grants.is_empty() {
                parts.push(missing_grants.join("; "));
            }
            checks.push(VerifyCheck::fail(
                "approval-use-nonce-binding",
                &parts.join("; "),
            ));
        }
    }

    // -- approval-use-action-binding --
    // Cross-check each consuming action's `meta.approval_use_id`
    // against the package's use records. v0.9.9 ignored this pointer
    // entirely; the package didn't even ship action envelopes, so the
    // verifier could not see the field. v0.9.10 PR A: action envelopes
    // ride along in `artifacts/`, and this row pins that every action
    // declaring it consumed an approval has a use record for that
    // exact use_id, with matching grant_id and matching
    // `nonce_digest(approval_nonce)`.
    //
    // Honesty rule: when bundle.action_envelopes is empty (pre-v0.9.10
    // packages, or a v0.9.10 package with no consuming actions
    // recorded), this row reports `not asserted by package` rather
    // than silent PASS.
    if !bundle.uses.is_empty() {
        use crate::attestation::envelope::Envelope;
        use crate::attestation::{artifact_id_from_pae, pae};
        use crate::statements::{nonce_digest, ActionStatement};
        if bundle.action_envelopes.is_empty() {
            checks.push(VerifyCheck::warn(
                "approval-use-action-binding",
                "no action envelopes embedded -- action↔use binding not asserted by package (pre-v0.9.10)",
            ));
        } else {
            let use_ids: std::collections::HashSet<&str> =
                bundle.uses.iter().map(|u| u.use_id.as_str()).collect();
            let mut violations: Vec<String> = Vec::new();
            let mut bound_count = 0usize;
            for (artifact_id, env_bytes) in &bundle.action_envelopes {
                let env = match Envelope::from_json(env_bytes) {
                    Ok(e) => e,
                    Err(_) => {
                        violations.push(format!("action {artifact_id} envelope unparseable"));
                        continue;
                    }
                };
                // Content-addressing gate: derive the artifact_id
                // from the envelope's PAE bytes and require it to
                // match the filename stem the package shipped this
                // envelope under. Without this gate an attacker
                // controlling the package can write any forged
                // unsigned action JSON to artifacts/<id>.json and the
                // binding rows would trust it.
                let derived = match env.payload_bytes() {
                    Ok(p) => artifact_id_from_pae(&pae(&env.payload_type, &p)),
                    Err(_) => {
                        violations
                            .push(format!("action {artifact_id} envelope payload undecodable"));
                        continue;
                    }
                };
                if &derived != artifact_id {
                    violations.push(format!(
                        "action {artifact_id} envelope content derives to {derived} -- envelope substituted or tampered",
                    ));
                    continue;
                }
                let action: ActionStatement = match env.unmarshal_statement() {
                    Ok(a) => a,
                    Err(_) => {
                        violations.push(format!("action {artifact_id} not an ActionStatement"));
                        continue;
                    }
                };
                let raw_nonce = match action.approval_nonce.as_deref() {
                    Some(n) => n,
                    None => continue,
                };
                let claimed_use_id = action
                    .meta
                    .as_ref()
                    .and_then(|m| m.get("approval_use_id"))
                    .and_then(|v| v.as_str());
                let Some(claimed_use_id) = claimed_use_id else {
                    violations.push(format!(
                        "action {artifact_id} consumed an approval but its meta has no approval_use_id"
                    ));
                    continue;
                };
                if !use_ids.contains(claimed_use_id) {
                    violations.push(format!(
                        "action {artifact_id} claims approval_use_id={} but no such use is embedded",
                        claimed_use_id,
                    ));
                    continue;
                }
                let expected = nonce_digest(raw_nonce);
                let matched_use = bundle.uses.iter().find(|u| u.use_id == claimed_use_id);
                if let Some(u) = matched_use {
                    if u.nonce_digest != expected {
                        violations.push(format!(
                            "action {artifact_id} approval_nonce hashes to {} but use {} stores nonce_digest {}",
                            expected, claimed_use_id, u.nonce_digest,
                        ));
                        continue;
                    }
                }
                bound_count += 1;
            }
            if violations.is_empty() {
                checks.push(VerifyCheck::pass(
                    "approval-use-action-binding",
                    &format!(
                        "{bound_count} consuming action(s) bind cleanly to content-addressed envelope(s)",
                    ),
                ));
            } else {
                checks.push(VerifyCheck::fail(
                    "approval-use-action-binding",
                    &violations.join("; "),
                ));
            }
        }
    }

    // -- approval-use-chain-continuity --
    // v0.9.9 verified each use's individual record_digest but never
    // walked the `previous_record_digest` chain across the embedded
    // records. An attacker could rewrite an entire chain consistently
    // (recomputing each digest along the way) and the per-record
    // checks all passed.
    //
    // Algorithm (v0.9.10 PR A round 2): build a graph of embedded
    // records keyed by record_digest, then require the embedded
    // records to form a SINGLE linked list with exactly one genesis
    // (previous_record_digest == "") and no cycles, forks, or
    // disconnected subchains.
    //
    //   - Dangling prev pointer (not in `owned`) -> fail.
    //   - More than one record with prev == ""    -> fail (mid-chain
    //     genesis is a forgery primitive).
    //   - Two records sharing the same prev       -> fail (fork).
    //   - Cycle reached during the walk           -> fail.
    //   - Walk doesn't reach every record         -> fail (disconnected
    //     subchain).
    //
    // We can only check *internal* consistency offline -- the package
    // doesn't ship the workspace journal's full history, so the chain
    // we see may be a contiguous prefix or window. Anchoring against
    // a Hub-signed checkpoint is replay-hub-org's job; here we report
    // structural consistency only.
    if !bundle.uses.is_empty() || !bundle.checkpoints.is_empty() {
        use std::collections::{HashMap, HashSet};
        // Each record carries a label for diagnostics + its own
        // record_digest + previous_record_digest.
        struct Node<'a> {
            label: String,
            digest: &'a str,
            prev: &'a str,
        }
        let mut nodes: Vec<Node> = Vec::new();
        for u in &bundle.uses {
            nodes.push(Node {
                label: format!("use {}", u.use_id),
                digest: u.record_digest.as_str(),
                prev: u.previous_record_digest.as_str(),
            });
        }
        for cp in &bundle.checkpoints {
            nodes.push(Node {
                label: format!("checkpoint {}", cp.checkpoint_id),
                digest: cp.record_digest.as_str(),
                prev: cp.previous_record_digest.as_str(),
            });
        }

        let owned: HashSet<&str> = std::iter::once("")
            .chain(nodes.iter().map(|n| n.digest))
            .collect();

        let mut violations: Vec<String> = Vec::new();
        // Dangling prev: pointer not in owned set.
        for n in &nodes {
            if !owned.contains(n.prev) {
                violations.push(format!(
                    "{} previous_record_digest {} not anchored in package",
                    n.label, n.prev,
                ));
            }
        }
        // Genesis count: only one record allowed to have prev == "".
        let genesis: Vec<&Node> = nodes.iter().filter(|n| n.prev.is_empty()).collect();
        if genesis.len() > 1 {
            violations.push(format!(
                "{} records claim previous_record_digest='' (genesis): {}",
                genesis.len(),
                genesis
                    .iter()
                    .map(|n| n.label.clone())
                    .collect::<Vec<_>>()
                    .join(", "),
            ));
        }
        // Forks: two records sharing the same non-empty prev.
        let mut by_prev: HashMap<&str, Vec<&Node>> = HashMap::new();
        for n in &nodes {
            by_prev.entry(n.prev).or_default().push(n);
        }
        for (prev, group) in &by_prev {
            if group.len() > 1 && !prev.is_empty() {
                violations.push(format!(
                    "fork: {} records share previous_record_digest {}: {}",
                    group.len(),
                    prev,
                    group
                        .iter()
                        .map(|n| n.label.clone())
                        .collect::<Vec<_>>()
                        .join(", "),
                ));
            }
        }

        // Walk from genesis (if exactly one) following digest-as-prev
        // links. Detect cycles and unreachable records.
        if violations.is_empty() {
            let by_digest: HashMap<&str, &Node> = nodes.iter().map(|n| (n.digest, n)).collect();
            let next_of: HashMap<&str, &Node> = nodes
                .iter()
                .filter(|n| !n.prev.is_empty())
                .map(|n| (n.prev, n))
                .collect();
            let start = genesis.first().copied();
            let mut visited: HashSet<&str> = HashSet::new();
            let mut current = start;
            while let Some(node) = current {
                if !visited.insert(node.digest) {
                    violations.push(format!(
                        "cycle detected at {} (record_digest {})",
                        node.label, node.digest,
                    ));
                    break;
                }
                current = next_of.get(node.digest).copied();
            }
            // Disconnected: walk didn't include every node.
            if violations.is_empty() && visited.len() != nodes.len() {
                let unreached: Vec<String> = nodes
                    .iter()
                    .filter(|n| !visited.contains(n.digest))
                    .map(|n| n.label.clone())
                    .collect();
                if !unreached.is_empty() {
                    violations.push(format!(
                        "disconnected subchain: {} record(s) not reachable from genesis: {}",
                        unreached.len(),
                        unreached.join(", "),
                    ));
                }
            }
            let _ = by_digest; // reserved for future cross-checks
        }

        if violations.is_empty() {
            checks.push(VerifyCheck::pass(
                "approval-use-chain-continuity",
                &format!(
                    "{} record(s) form a single connected linked list from one genesis with no cycles or forks",
                    nodes.len(),
                ),
            ));
        } else {
            checks.push(VerifyCheck::fail(
                "approval-use-chain-continuity",
                &violations.join("; "),
            ));
        }
    }

    // -- replay-hub-org -- v0.9.9 PR 6.
    // The strongest level Treeship can speak to today. The release
    // rule is non-negotiable: PASS only when (1) at least one embedded
    // checkpoint declares kind=HubOrg, (2) every required Hub field is
    // populated, (3) the signature verifies against the embedded
    // public key, AND (4) the checkpoint covers every embedded
    // ApprovalUse via covered_use_ids. Anything short of that means
    // "no row" or "fail" -- never silent pass.
    //
    // No row at all when the package has no Hub-kind checkpoint:
    // matches the v0.9.9 PR 4-5 behavior where the panel renders
    // "- hub-org   not checked (no Hub checkpoint in package)" so a
    // reader doesn't misread an absent row as a failure.
    let hub_checkpoints: Vec<&JournalCheckpoint> = bundle
        .checkpoints
        .iter()
        .filter(|cp| cp.checkpoint_kind == crate::statements::CheckpointKind::HubOrg)
        .collect();
    if !hub_checkpoints.is_empty() {
        let mut all_ok = true;
        let mut details: Vec<String> = Vec::new();
        let mut have_valid_signature = false;
        // Security-critical failures (untrusted-issuer / tampered /
        // not-hub-kind) must FAIL unconditionally, not warn. Audit
        // lane J fix-up: previously these emitted WARN and the CLI
        // wrapper's --strict promoted to FAIL, which meant the
        // headline audit case (self-signed hub-org forgery) passed
        // green-but-yellow in default mode. The release rule is
        // "trust pinning is on by default"; expressed in this row
        // as "any signature/issuer failure is a hard fail."
        let mut security_fatal = false;

        for cp in &hub_checkpoints {
            match crate::statements::verify_hub_checkpoint_signature(cp, trust) {
                crate::statements::HubCheckpointVerification::Valid => {
                    have_valid_signature = true;
                    // Coverage: every embedded use_id MUST appear in
                    // this checkpoint's covered_use_ids. A checkpoint
                    // that doesn't cover the package's uses cannot
                    // promote replay-hub-org for those uses.
                    let covered: std::collections::HashSet<&String> =
                        cp.covered_use_ids.iter().collect();
                    let missing: Vec<String> = bundle
                        .uses
                        .iter()
                        .filter(|u| !covered.contains(&u.use_id))
                        .map(|u| u.use_id.clone())
                        .collect();
                    if missing.is_empty() {
                        details.push(format!(
                            "{} signed by {} verifies; covers {} use(s)",
                            cp.checkpoint_id,
                            cp.hub_id,
                            cp.covered_use_ids.len(),
                        ));
                    } else {
                        all_ok = false;
                        details.push(format!(
                            "{} verifies but does not cover {} use(s): {}",
                            cp.checkpoint_id,
                            missing.len(),
                            missing.join(", "),
                        ));
                    }
                }
                crate::statements::HubCheckpointVerification::MissingFields(field) => {
                    all_ok = false;
                    details.push(format!(
                        "{} declares kind=hub-org but field `{}` is missing",
                        cp.checkpoint_id, field,
                    ));
                }
                crate::statements::HubCheckpointVerification::Tampered => {
                    all_ok = false;
                    security_fatal = true;
                    details.push(format!(
                        "{} hub signature failed verification (tampered or wrong key)",
                        cp.checkpoint_id,
                    ));
                }
                crate::statements::HubCheckpointVerification::NotHubKind => {
                    // Filter ensures this is unreachable; keep the
                    // arm so a future filter relaxation doesn't go
                    // silent.
                    all_ok = false;
                    security_fatal = true;
                    details.push(format!(
                        "{} kind toggled out of hub-org during verify",
                        cp.checkpoint_id,
                    ));
                }
                crate::statements::HubCheckpointVerification::UntrustedIssuer => {
                    all_ok = false;
                    security_fatal = true;
                    details.push(format!(
                        "{} hub_public_key is not a trusted root (configure via `treeship trust add`)",
                        cp.checkpoint_id,
                    ));
                }
            }
        }
        if all_ok && have_valid_signature {
            checks.push(VerifyCheck::pass("replay-hub-org", &details.join("; ")));
        } else if security_fatal {
            // Untrusted issuer or tampered signature: fail-by-default
            // regardless of --strict. Self-signed forgeries must not
            // pass yellow.
            checks.push(VerifyCheck::fail("replay-hub-org", &details.join("; ")));
        } else {
            // Hub checkpoint is present but does not satisfy every
            // non-security gate (missing-field, coverage gap).
            // Default mode warns; the CLI verify wrapper's --strict
            // promotes to fail.
            checks.push(VerifyCheck::warn("replay-hub-org", &details.join("; ")));
        }
    }
    // No hub-org checkpoints embedded -> no row. The Approval
    // Authority panel still renders "- hub-org   not checked".

    let _ = ReplayCheckLevel::HubOrg;
    let _ = approval_revocation_record_digest as fn(&ApprovalRevocation) -> String;
    let _ = ReplayCheck::not_performed;
}

/// A single verification check result.
#[derive(Debug, Clone)]
pub struct VerifyCheck {
    pub name: String,
    pub status: VerifyStatus,
    pub detail: String,
}

/// Status of a verification check.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VerifyStatus {
    Pass,
    Fail,
    Warn,
}

impl VerifyCheck {
    pub fn pass(name: &str, detail: &str) -> Self {
        Self {
            name: name.into(),
            status: VerifyStatus::Pass,
            detail: detail.into(),
        }
    }
    pub fn fail(name: &str, detail: &str) -> Self {
        Self {
            name: name.into(),
            status: VerifyStatus::Fail,
            detail: detail.into(),
        }
    }
    pub fn warn(name: &str, detail: &str) -> Self {
        Self {
            name: name.into(),
            status: VerifyStatus::Warn,
            detail: detail.into(),
        }
    }
}

impl VerifyCheck {
    pub fn passed(&self) -> bool {
        self.status == VerifyStatus::Pass
    }
}

/// HTML template for the self-contained verifier preview.
/// Loaded at compile time so the binary carries no runtime file dependencies.
const PREVIEW_TEMPLATE: &str = include_str!("preview_template.html");

/// Brand display serif (Fraunces, SIL OFL 1.1) — latin variable slice, weights
/// 300..500. Embedded as base64 into the self-contained preview so the document
/// renders with the brand type offline, no CDN. Body and mono use the system
/// stack. See design/fonts/.
// Vendored inside the crate, not referenced out of the workspace. `cargo
// package` only tarballs files under the crate root, so an `include_bytes!`
// reaching up to `design/fonts/` builds fine here and fails to compile once
// published -- which is exactly how treeship-core missed crates.io in v0.22.0
// while npm and PyPI shipped. Kept in sync with `design/fonts/` by
// `scripts/check-vendored-fonts.py`.
const FRAUNCES_WOFF2: &[u8] = include_bytes!("../../assets/fonts/fraunces-latin-var.woff2");

/// The `data:` URI for the embedded Fraunces woff2, substituted into the
/// template's `@font-face`. Standard (not URL-safe) base64: it sits in a CSS
/// `url(...)`, not a URL path.
fn fraunces_data_uri() -> String {
    use base64::engine::general_purpose::STANDARD;
    use base64::Engine;
    format!("data:font/woff2;base64,{}", STANDARD.encode(FRAUNCES_WOFF2))
}

/// Generate a self-contained preview.html that embeds the receipt JSON
/// and runs Merkle verification client-side using Web Crypto API.
///
/// The HTML works fully air-gapped: no network calls, no CDN, no server.
/// Open it in any modern browser and it automatically verifies the receipt
/// and shows pass/fail for each check.
pub fn render_preview_html(receipt: &SessionReceipt) -> String {
    render_preview_html_with_approvals(receipt, None)
}

/// What the preview shows under "Approval gates": every grant the package
/// embeds under `approvals/grants` and every use under `approvals/uses`.
///
/// The preview used to read approvals only from the chained artifacts, so a
/// session whose approvals were consumed (and therefore exported into the
/// `approvals/` directory, where the verifier checks them) rendered "No
/// approval gates recorded" while `package verify` printed `PASS
/// replay-local-journal`. This is the same evidence the verifier reads,
/// summarised for a reader. A grant envelope that does not parse is listed
/// by id with `parsed: false` rather than dropped: the reader should see
/// that evidence exists even when this page cannot describe it.
pub fn preview_approvals_json(bundle: Option<&ApprovalsBundle>) -> serde_json::Value {
    let Some(b) = bundle else {
        return serde_json::Value::Null;
    };
    if b.grants.is_empty() && b.uses.is_empty() {
        return serde_json::Value::Null;
    }
    let grants: Vec<serde_json::Value> = b
        .grants
        .iter()
        .map(|(grant_id, bytes)| {
            let parsed = crate::attestation::Envelope::from_json(bytes)
                .ok()
                .and_then(|env| env.unmarshal_statement::<ApprovalStatement>().ok());
            match parsed {
                Some(st) => serde_json::json!({
                    "grant_id": grant_id,
                    "parsed": true,
                    "approver": st.approver,
                    "description": st.description,
                    "timestamp": st.timestamp,
                    "expires_at": st.expires_at,
                    "scope": st.scope.as_ref().map(|sc| serde_json::json!({
                        "allowed_actors": sc.allowed_actors,
                        "allowed_actions": sc.allowed_actions,
                        "allowed_subjects": sc.allowed_subjects,
                        "max_uses": sc.max_actions,
                        "valid_until": sc.valid_until,
                    })),
                }),
                None => serde_json::json!({ "grant_id": grant_id, "parsed": false }),
            }
        })
        .collect();
    let uses: Vec<serde_json::Value> = b
        .uses
        .iter()
        .map(|u| serde_json::to_value(u).unwrap_or(serde_json::Value::Null))
        .collect();
    serde_json::json!({ "grants": grants, "uses": uses })
}

/// `render_preview_html`, plus the approval evidence the package embeds.
pub fn render_preview_html_with_approvals(
    receipt: &SessionReceipt,
    bundle: Option<&ApprovalsBundle>,
) -> String {
    let approvals_json = preview_approvals_json(bundle).to_string();
    let safe_approvals = approvals_json.replace('<', r"\u003c");
    let receipt_json = serde_json::to_string_pretty(receipt).unwrap_or_else(|_| "{}".to_string());
    // Defense-in-depth: escape </script sequences so a malicious receipt
    // field cannot break out of the JSON data block. The primary defense
    // is type="application/json" which the HTML parser does not execute,
    // but this escaping adds a second layer.
    // Escape ALL '<' as '\u003c' in the JSON string to prevent any
    // case-variant of </script> from breaking out of the data block.
    // This is bulletproof: no HTML parser can see a tag open inside the JSON.
    let safe_json = receipt_json.replace('<', r"\u003c");

    // The only placeholder that must take the receipt JSON is the data
    // block. replacen(.., 1) substitutes exactly that first occurrence, so
    // even if the token is ever reused elsewhere in the template (e.g. a JS
    // placeholder check) the receipt body is never injected into it. The
    // template's own placeholder check uses a split sentinel for the same
    // reason. The page title is set at runtime from the parsed JSON.
    PREVIEW_TEMPLATE
        .replacen("__RECEIPT_JSON__", &safe_json, 1)
        .replacen("__APPROVALS_JSON__", &safe_approvals, 1)
        .replace("__FONT_FRAUNCES__", &fraunces_data_uri())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::session::event::*;
    use crate::session::manifest::SessionManifest;
    use crate::session::receipt::{ArtifactEntry, ReceiptComposer};

    fn make_receipt() -> SessionReceipt {
        let manifest = SessionManifest::new(
            "ssn_pkg_test".into(),
            "agent://test".into(),
            "2026-04-05T08:00:00Z".into(),
            1743843600000,
        );

        let mk = |seq: u64, inst: &str, et: EventType| -> SessionEvent {
            SessionEvent {
                session_id: "ssn_pkg_test".into(),
                event_id: format!("evt_{:016x}", seq),
                timestamp: format!("2026-04-05T08:{:02}:00Z", seq),
                sequence_no: seq,
                trace_id: "trace_1".into(),
                span_id: format!("span_{seq}"),
                parent_span_id: None,
                agent_id: format!("agent://{inst}"),
                agent_instance_id: inst.into(),
                agent_name: inst.into(),
                agent_role: None,
                host_id: "host_1".into(),
                tool_runtime_id: None,
                event_type: et,
                artifact_ref: None,
                meta: None,
            }
        };

        let events = vec![
            mk(0, "root", EventType::SessionStarted),
            mk(
                1,
                "root",
                EventType::AgentStarted {
                    parent_agent_instance_id: None,
                },
            ),
            mk(
                2,
                "root",
                EventType::AgentCalledTool {
                    tool_name: "read_file".into(),
                    tool_input_digest: None,
                    tool_output_digest: None,
                    duration_ms: Some(10),
                },
            ),
            mk(
                3,
                "root",
                EventType::AgentCompleted {
                    termination_reason: None,
                },
            ),
            mk(
                4,
                "root",
                EventType::SessionClosed {
                    summary: Some("Done".into()),
                    duration_ms: Some(60000),
                },
            ),
        ];

        let artifacts = vec![ArtifactEntry {
            artifact_id: "art_001".into(),
            payload_type: "action".into(),
            digest: None,
            signed_at: None,
        }];

        ReceiptComposer::compose(&manifest, &events, artifacts)
    }

    #[test]
    fn build_and_read_package() {
        let receipt = make_receipt();
        let tmp = std::env::temp_dir().join(format!("treeship-pkg-test-{}", rand::random::<u32>()));

        let output = build_package(&receipt, &tmp).unwrap();
        assert!(output.path.exists());
        assert!(output.path.join("receipt.json").exists());
        assert!(output.path.join("merkle.json").exists());
        assert!(output.path.join("render.json").exists());
        assert!(output.path.join("preview.html").exists());
        assert!(output.receipt_digest.starts_with("sha256:"));
        assert!(output.file_count >= 4);

        // Read back
        let read_back = read_package(&output.path).unwrap();
        assert_eq!(read_back.session.id, "ssn_pkg_test");
        assert_eq!(read_back.type_, RECEIPT_TYPE);

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn verify_valid_package() {
        let receipt = make_receipt();
        let tmp =
            std::env::temp_dir().join(format!("treeship-pkg-verify-{}", rand::random::<u32>()));

        let output = build_package(&receipt, &tmp).unwrap();
        let checks = verify_package(&output.path).unwrap();

        let fails: Vec<_> = checks
            .iter()
            .filter(|c| c.status == VerifyStatus::Fail)
            .collect();
        assert!(fails.is_empty(), "unexpected failures: {fails:?}");

        let passes: Vec<_> = checks
            .iter()
            .filter(|c| c.status == VerifyStatus::Pass)
            .collect();
        assert!(
            passes.len() >= 5,
            "expected at least 5 pass checks, got {}",
            passes.len()
        );

        let _ = std::fs::remove_dir_all(&tmp);
    }

    // AUD-07: a receipt stamped reconcile_degraded must surface a WARN on
    // verify, so a consumer is told the file ledger may be incomplete rather
    // than reading the package as a clean, complete audit trail.
    #[test]
    fn verify_warns_when_reconcile_degraded() {
        let mut receipt = make_receipt();
        receipt.proofs.reconcile_degraded = true;
        let tmp =
            std::env::temp_dir().join(format!("treeship-pkg-degraded-{}", rand::random::<u32>()));

        let output = build_package(&receipt, &tmp).unwrap();
        let checks = verify_package(&output.path).unwrap();

        let warned = checks
            .iter()
            .any(|c| c.name == "reconcile_degraded" && c.status == VerifyStatus::Warn);
        assert!(warned, "expected a reconcile_degraded WARN, got {checks:?}");
        // It is a WARN, not a hard fail (the signatures/Merkle are still valid).
        let fails: Vec<_> = checks
            .iter()
            .filter(|c| c.status == VerifyStatus::Fail)
            .collect();
        assert!(fails.is_empty(), "must not hard-fail: {fails:?}");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn verify_no_degraded_warn_when_clean() {
        // The default receipt has reconcile_degraded=false: no such WARN.
        let receipt = make_receipt();
        let tmp =
            std::env::temp_dir().join(format!("treeship-pkg-clean-{}", rand::random::<u32>()));
        let output = build_package(&receipt, &tmp).unwrap();
        let checks = verify_package(&output.path).unwrap();
        assert!(
            !checks.iter().any(|c| c.name == "reconcile_degraded"),
            "clean receipt must not emit a reconcile_degraded check"
        );
        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn verify_detects_missing_receipt() {
        let tmp =
            std::env::temp_dir().join(format!("treeship-pkg-empty-{}", rand::random::<u32>()));
        std::fs::create_dir_all(&tmp).unwrap();

        let err = read_package(&tmp);
        assert!(err.is_err());

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn preview_html_renders_approval_evidence_from_the_bundle() {
        // The package embeds consumed approvals under approvals/ (that is what
        // `package verify` checks as replay-local-journal). The preview must
        // show them too: a reader saw "No approval gates recorded" on a
        // session whose approval was minted, spent once, and verified.
        use crate::attestation::sign::sign;
        use crate::attestation::Ed25519Signer;
        use crate::statements::ApprovalScope;
        use crate::statements::TYPE_APPROVAL_USE;

        let receipt = make_receipt();
        assert_eq!(preview_approvals_json(None), serde_json::Value::Null);
        assert_eq!(
            preview_approvals_json(Some(&ApprovalsBundle::default())),
            serde_json::Value::Null,
            "an empty bundle is the same as none"
        );

        let signer = Ed25519Signer::generate("key_test_preview").unwrap();
        let mut grant = ApprovalStatement::new("human://operator", "nonce-preview-0001");
        grant.description = Some("apply change chg-0001: 3% clearance".into());
        grant.scope = Some(ApprovalScope {
            max_actions: Some(1),
            valid_until: None,
            allowed_actors: vec!["agent://merchant".into()],
            allowed_actions: vec!["commerce.tool.apply_change.intent".into()],
            allowed_subjects: vec!["change://chg-0001".into()],
            extra: None,
        });
        let signed = sign("application/vnd.treeship.approval.v1+json", &grant, &signer).unwrap();
        let grant_id = signed.artifact_id.to_string();
        let grant_bytes = serde_json::to_vec(&signed.envelope).unwrap();

        let use_record = ApprovalUse {
            type_: TYPE_APPROVAL_USE.into(),
            use_id: "use_preview_0001".into(),
            grant_id: grant_id.clone(),
            grant_digest: signed.digest.clone(),
            nonce_digest: "sha256:00".into(),
            actor: "agent://merchant".into(),
            action: "commerce.tool.apply_change.intent".into(),
            subject: "change://chg-0001".into(),
            session_id: Some("ssn_pkg_test".into()),
            action_artifact_id: Some("art_apply_intent".into()),
            receipt_digest: None,
            use_number: 1,
            max_uses: Some(1),
            idempotency_key: None,
            created_at: "2026-09-07T10:45:49Z".into(),
            expires_at: None,
            previous_record_digest: String::new(),
            record_digest: String::new(),
            signature: None,
            signature_alg: None,
            signing_key_id: None,
        };
        let bundle = ApprovalsBundle {
            grants: vec![
                (grant_id.clone(), grant_bytes),
                ("art_garbage".into(), b"not json".to_vec()),
            ],
            uses: vec![use_record],
            ..Default::default()
        };

        let summary = preview_approvals_json(Some(&bundle));
        let grants = summary["grants"].as_array().unwrap();
        assert_eq!(grants.len(), 2);
        assert_eq!(grants[0]["parsed"], true);
        assert_eq!(grants[0]["approver"], "human://operator");
        assert_eq!(grants[0]["scope"]["max_uses"], 1);
        assert_eq!(
            grants[0]["scope"]["allowed_subjects"][0],
            "change://chg-0001"
        );
        // An unparsable grant is listed, not dropped, and says so.
        assert_eq!(grants[1]["parsed"], false);
        assert_eq!(grants[1]["grant_id"], "art_garbage");
        let uses = summary["uses"].as_array().unwrap();
        assert_eq!(uses[0]["use_number"], 1);
        assert_eq!(uses[0]["action_artifact_id"], "art_apply_intent");

        let html = render_preview_html_with_approvals(&receipt, Some(&bundle));
        assert!(html.contains("id=\"approvals-data\""));
        assert!(html.contains("\"approver\":\"human://operator\""));
        assert!(html.contains("\"subject\":\"change://chg-0001\""));
        assert!(
            !html.contains("__APPROVALS_JSON__"),
            "placeholder must be substituted"
        );
        // Without a bundle the data block is a JSON null, never an empty
        // string that would throw in JSON.parse and hide the whole page.
        let plain = render_preview_html(&receipt);
        assert!(plain.contains("type=\"application/json\">null</script>"));
    }

    #[test]
    fn preview_html_contains_session_info() {
        let receipt = make_receipt();
        let html = render_preview_html(&receipt);
        assert!(html.contains("ssn_pkg_test"));
        assert!(html.contains("treeship.dev"));
        assert!(html.contains("Timeline"));

        // Regression: the receipt JSON must land ONLY in the data block,
        // never in the inline JS. A prior bug used replace() (all matches)
        // against a template that carried the placeholder token twice (data
        // slot + a JS placeholder check), injecting the receipt body into a
        // JS string literal. That produced an uncaught SyntaxError, so the
        // whole script never ran and the preview hung on "Verifying
        // receipt...". The JS check now uses a split sentinel that must
        // survive substitution verbatim, and replacen(.., 1) fills only the
        // first occurrence.
        assert!(
            html.contains("'__RECEIPT'+'_JSON__'"),
            "JS placeholder check was clobbered by the receipt substitution",
        );
        assert!(
            !html.contains("application/json\">__RECEIPT_JSON__</script>"),
            "data slot was not substituted with the receipt JSON",
        );
        // The session id (a receipt value) must appear inside the data block,
        // not leak into executable JS, so a quick structural sanity check:
        // there is exactly one unsubstituted token left at most (none here).
        assert_eq!(
            html.matches("__RECEIPT_JSON__").count(),
            0,
            "no raw placeholder token should remain after substitution",
        );
    }
}