unsafe_review_core/

api.rs

use crate::analysis::{pipeline, receipts};
use crate::domain::{CardId, ReviewCard};
use crate::freshness::AnalysisIdentity;
use crate::input::workspace;
use crate::output::{
    agent, badges, comment_plan, confirmation, gate_manifest, human, json, lsp, markdown, outcome,
    policy_report, receipt_audit, repair_queue, sarif, usefulness_telemetry, witness_plan,
};
use crate::policy::SnapshotCoverage;
use crate::util::path_display;
use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Scope {
    Diff,
    Repo,
}

impl Scope {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Diff => "diff",
            Self::Repo => "repo",
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum AnalysisMode {
    Instant,
    Draft,
    Ready,
    Repo,
}

impl AnalysisMode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Instant => "instant",
            Self::Draft => "draft",
            Self::Ready => "ready",
            Self::Repo => "repo",
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum PolicyMode {
    Advisory,
    NoNewDebt,
    Blocking,
}

impl PolicyMode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Advisory => "advisory",
            Self::NoNewDebt => "no-new-debt",
            Self::Blocking => "blocking",
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum DiffSource {
    NoneRepoScan,
    Text(String),
    File(PathBuf),
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RepoScanPhase {
    Discovering,
    Scanning,
    Complete,
}

impl RepoScanPhase {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Discovering => "discovering",
            Self::Scanning => "scanning",
            Self::Complete => "complete",
        }
    }
}

/// Why a repo scan stopped short of scanning every discovered file.
///
/// A `Complete` scan has `stop_reason: None` (or equivalently `"none"`
/// in the JSON sidecar).  Every other variant indicates a bounded-but-partial
/// run; `completed` stays `false` for all partial variants.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RepoStopReason {
    /// Scan ran to completion — every in-scope file was read.
    None,
    /// `--max-cards N` was reached; scanning stopped after `N` cards were emitted.
    MaxCards,
    /// `--timeout-seconds N` elapsed while the scan was in progress.
    Timeout,
    /// A unix signal (SIGTERM / SIGINT) interrupted the scan.
    Terminated,
    /// The scan did not complete due to an analysis or report-write error
    /// (anything that is not a timeout, signal, or cap).
    Error,
}

impl RepoStopReason {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::None => "none",
            Self::MaxCards => "max_cards",
            Self::Timeout => "timeout",
            Self::Terminated => "terminated",
            Self::Error => "error",
        }
    }
}

/// Per-file scan timing entry.  Diagnostic only — not a coverage claim,
/// proof, UB-free, Miri-clean, site-execution, or performance guarantee.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PerFileScanStats {
    /// Repository-relative path of the scanned file.
    pub file: PathBuf,
    /// Wall-clock milliseconds spent scanning this file (parse + site detection).
    pub scan_ms: u64,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RepoScanStatus {
    pub schema_version: String,
    pub phase: RepoScanPhase,
    pub elapsed_ms: u64,
    pub files_discovered: usize,
    pub files_scanned: usize,
    pub cards_found: usize,
    pub last_path: Option<PathBuf>,
    pub completed: bool,
    /// Whether this is a partial (bounded) scan result.
    /// `true` for max-cards, timeout, and signal-terminated scans.
    pub partial: bool,
    /// The reason the scan stopped.  `None` for a complete scan, or one of the
    /// named stop reasons for a bounded/interrupted scan.
    pub stop_reason: RepoStopReason,
    /// The configured card cap when `stop_reason == MaxCards`; `None` otherwise.
    pub cap: Option<usize>,
    /// Per-file timing breakdown for diagnostic use.  Present only when the
    /// scan covered fewer than [`FILE_TIMINGS_CAP`] files; `None` for large
    /// scans (cap honesty: the field is absent, not silently truncated).
    /// This is a **diagnostic aperture only** — not a coverage claim, proof,
    /// UB-free, Miri-clean, site-execution, or performance guarantee.
    pub file_timings: Option<Vec<PerFileScanStats>>,
    /// Total bytes written to the output artifact(s) for this run.  `Some`
    /// only after the final report file is successfully written; `None` for
    /// in-progress, error, timeout, signal-terminated, and capped states where
    /// no final artifact was produced.
    ///
    /// This is a **diagnostic aperture only** — it measures the disk footprint
    /// of this run's output, not the files scanned.  It is not a coverage
    /// claim, proof, UB-free, Miri-clean, site-execution, or performance
    /// guarantee.
    pub output_bytes: Option<u64>,
}

/// Maximum number of files for which per-file timing is collected.
/// Scans touching more files omit `file_timings` entirely rather than
/// silently emitting a partial list (truncation honesty).
pub const FILE_TIMINGS_CAP: usize = 100;

#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct DiscoveryOptions {
    pub include: Vec<String>,
    pub exclude: Vec<String>,
    pub respect_gitignore: bool,
    pub large_repo_ignores: bool,
    pub max_files: Option<usize>,
}

impl DiscoveryOptions {
    pub fn repo_defaults() -> Self {
        Self {
            respect_gitignore: true,
            large_repo_ignores: true,
            ..Self::default()
        }
    }
}

#[derive(Clone, Debug)]
pub struct AnalyzeInput {
    pub root: PathBuf,
    pub scope: Scope,
    pub diff: DiffSource,
    pub mode: AnalysisMode,
    pub policy: PolicyMode,
    pub include_unchanged_tests: bool,
    pub max_cards: Option<usize>,
}

impl Default for AnalyzeInput {
    fn default() -> Self {
        Self {
            root: PathBuf::from("."),
            scope: Scope::Diff,
            diff: DiffSource::NoneRepoScan,
            mode: AnalysisMode::Draft,
            policy: PolicyMode::Advisory,
            include_unchanged_tests: true,
            max_cards: None,
        }
    }
}

#[derive(Clone, Debug, Default)]
pub struct Summary {
    pub rust_files: usize,
    pub changed_files: usize,
    pub changed_rust_files: usize,
    pub changed_non_rust_files: usize,
    pub unsafe_sites: usize,
    pub cards: usize,
    pub open_actionable_gaps: usize,
    pub contract_missing: usize,
    pub guard_missing: usize,
    pub guarded_unwitnessed: usize,
    pub unsafe_unreached: usize,
    pub requires_loom: usize,
    pub miri_unsupported: usize,
    pub static_unknown: usize,
    /// Coverage movement counts (SPEC-0030).
    ///
    /// `new_gaps`      — open actionable cards not in the baseline ledger.
    /// `worsened_gaps` — baseline cards whose coverage regressed (requires a saved coverage
    ///                   snapshot; always 0 until `baseline init` authoring lands).
    /// `improved_gaps` — baseline cards whose evidence coverage improved (at least one slot
    ///                   advanced and no slot regressed; requires a saved coverage snapshot;
    ///                   always 0 until `baseline init` authoring lands).
    ///                   Precedence: worsened > improved > inherited.  A card is only counted
    ///                   improved if it is not already counted worsened.
    ///                   An improved card is still advisory, still open, still present — it is
    ///                   NOT resolved, NOT safe, NOT UB-free, NOT Miri-clean, and NOT a
    ///                   site-execution claim.
    /// `resolved_gaps` — baseline ledger entries whose card is no longer present.
    /// `inherited_gaps`— baseline-known cards still open and unchanged.
    ///
    /// On a diff-scoped run `new_gaps` is constrained to changed-line sites;
    /// on a repo-mode run it counts all open actionable non-baseline gaps.
    pub new_gaps: usize,
    pub worsened_gaps: usize,
    pub improved_gaps: usize,
    pub resolved_gaps: usize,
    pub inherited_gaps: usize,
    /// True when the scan emitted fewer cards than it discovered because the
    /// `max_cards` cap was exceeded and spread-selection dropped the remainder
    /// (SPEC-0035 `stop_reason=max_cards`).
    ///
    /// This is *projected* from the pipeline's cap decision, never re-derived by
    /// a consumer from `unsafe_sites > cards` (registry FM8, project-vs-re-derive).
    /// Every count in this summary is understated while it is true, so any surface
    /// that renders a count must also disclose the cap.
    pub scan_capped: bool,
    /// The `max_cards` value in effect when `scan_capped` is true; `None` on an
    /// uncapped run.
    pub card_cap: Option<usize>,
}

impl Summary {
    /// One-line disclosure for a capped scan, or `None` when the scan was complete.
    ///
    /// Single source of the wording so the terminal, PR summary, and witness plan
    /// cannot drift apart. It reports coverage of the emitted card set only: it is
    /// not a memory-safety, UB-free, Miri-clean, site-execution, or
    /// precision/recall claim, and a complete scan is not one either.
    pub fn capped_scan_notice(&self) -> Option<String> {
        if !self.scan_capped {
            return None;
        }
        let cap = match self.card_cap {
            Some(cap) => format!("--max-cards {cap}"),
            None => "the card cap".to_string(),
        };
        Some(format!(
            "Partial scan: {} of {} discovered unsafe sites are shown ({cap}). \
             Every count above is capped, not a complete inventory — rerun without \
             the cap to see the rest.",
            self.cards, self.unsafe_sites
        ))
    }
}

#[derive(Clone, Debug)]
pub struct AnalyzeOutput {
    pub analysis_identity: AnalysisIdentity,
    pub schema_version: String,
    pub tool: String,
    pub root: PathBuf,
    pub scope: Scope,
    pub mode: AnalysisMode,
    pub policy: PolicyMode,
    pub summary: Summary,
    pub cards: Vec<ReviewCard>,
    /// On a diff-scoped run, the set of candidate files that were scanned.
    /// Empty for full-scan (repo-mode) runs.  Used to distinguish "baseline
    /// card resolved because we scanned its file and it is gone" from "baseline
    /// card not present because its file was out of diff scope" (SPEC-0030).
    pub diff_scoped_files: BTreeSet<PathBuf>,
    /// Per-card coverage snapshot loaded from `policy/unsafe-review-baseline-snapshot.toml`.
    ///
    /// Output renderers use this to project the per-card `baseline_state`/`outcome_movement`
    /// from the same slot-level comparison the summary uses (SPEC-0030 §single-truth).
    /// Empty when no snapshot file exists (no worsened/improved projection possible).
    pub coverage_snapshot: BTreeMap<String, SnapshotCoverage>,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReviewCardConfirmationProjection {
    pub hypothesis_to_confirm: String,
    pub build_this_first: String,
    pub minimal_repro_steps: Vec<String>,
    pub minimal_repro_limitation: String,
    pub confirmation_step: String,
}

#[derive(Clone, Debug)]
pub struct RepoScanEvent {
    pub status: RepoScanStatus,
    pub partial_output: Option<AnalyzeOutput>,
}

pub fn analyze(input: AnalyzeInput) -> Result<AnalyzeOutput, String> {
    pipeline::analyze(input)
}

pub fn analyze_with_discovery(
    input: AnalyzeInput,
    discovery: DiscoveryOptions,
) -> Result<AnalyzeOutput, String> {
    pipeline::analyze_with_discovery(input, discovery)
}

pub fn analyze_with_discovery_and_progress<F>(
    input: AnalyzeInput,
    discovery: DiscoveryOptions,
    progress: F,
) -> Result<AnalyzeOutput, String>
where
    F: FnMut(&RepoScanStatus) -> Result<(), String>,
{
    pipeline::analyze_with_discovery_and_progress(input, discovery, progress)
}

pub fn analyze_with_discovery_and_repo_events<F>(
    input: AnalyzeInput,
    discovery: DiscoveryOptions,
    events: F,
) -> Result<AnalyzeOutput, String>
where
    F: FnMut(&RepoScanEvent) -> Result<(), String>,
{
    pipeline::analyze_with_discovery_and_repo_events(input, discovery, events)
}

pub fn discover_repo_files(
    root: PathBuf,
    discovery: DiscoveryOptions,
) -> Result<Vec<PathBuf>, String> {
    workspace::discover_rust_files(&root, &discovery)
}

pub fn validate_witness_receipts(root: PathBuf) -> Result<usize, String> {
    receipts::validate_receipts(&root)
}

pub fn audit_witness_receipts(input: AnalyzeInput) -> Result<ReceiptAuditReport, String> {
    let output = pipeline::analyze_without_receipts(input)?;
    receipts::audit_receipts(&output)
}

pub fn evaluate_policy_report(mut input: AnalyzeInput) -> Result<PolicyReport, String> {
    input.policy = PolicyMode::Advisory;
    let output = pipeline::analyze(input)?;
    policy_report::evaluate(&output)
}

pub fn evaluate_policy_report_from_output(output: &AnalyzeOutput) -> Result<PolicyReport, String> {
    policy_report::evaluate(output)
}

/// Run cost aperture measured by the CLI emit layer and injected into
/// `usefulness-telemetry.json` (SPEC-0038 §scan_cost).
///
/// Core must not measure wall time — this struct carries the two cost fields
/// that only the CLI layer can observe.
///
/// Diagnostic only — not a coverage claim, proof, UB-free, Miri-clean,
/// site-execution, or performance guarantee.
#[derive(Clone, Debug, Default)]
pub struct ScanCost {
    /// Wall-clock milliseconds from before `analyze()` through the last artifact
    /// write, measured in the CLI emit layer.
    pub elapsed_ms: u64,
    /// Total bytes written across all output artifacts for this run, accumulated
    /// in the CLI emit layer.  The telemetry file itself is excluded (it is
    /// rendered before its own bytes are known).
    pub output_bytes_total: u64,
}

/// Traceable evidence metadata that the CLI layer assembles from argv, git, and the
/// filesystem before calling the JSON renderer.
///
/// This is "traceable evidence metadata", not proof: the fields identify the inputs
/// used to produce an artifact so that two runs against different diffs cannot emit
/// byte-identical clean receipts, but they do not prove correctness or memory safety.
#[derive(Clone, Debug, Default)]
pub struct Provenance {
    /// Absolute path of the resolved workspace root (additive alongside the existing
    /// relative `root` field which remains unchanged for compatibility).
    pub root_abs: Option<String>,
    /// Resolved base commit SHA (when `--base` was supplied and git resolution succeeded).
    pub base_sha: Option<String>,
    /// Resolved HEAD commit SHA (when `--base` was supplied and git resolution succeeded).
    pub head_sha: Option<String>,
    /// Path of the diff file (when `--diff <file>` was supplied).
    pub diff_path: Option<String>,
    /// SHA-256 hex digest of the diff file content (when `--diff <file>` was supplied).
    pub diff_sha256: Option<String>,
    /// RFC3339 UTC timestamp at which the artifact was generated.
    pub generated_at: String,
    /// Whether the working tree had uncommitted changes when the tool ran (None = git unavailable).
    pub dirty_worktree: Option<bool>,
}

impl Provenance {
    /// Build a minimal provenance block stamped with the current UTC time.
    pub fn new_now() -> Self {
        use std::time::{SystemTime, UNIX_EPOCH};
        let secs = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        Self {
            generated_at: unix_secs_to_iso_datetime_utc(secs),
            ..Self::default()
        }
    }
}

/// Regenerate `expected.cards.json` for each named fixture (or all registered
/// fixtures if `names` is empty), always writing LF line endings.
///
/// Called by `cargo run -p xtask -- bless-goldens [fixture ...]`.
/// Does not execute witnesses or assess soundness.
pub fn bless_fixture_card_goldens(names: &[&str]) -> Result<Vec<PathBuf>, String> {
    json::bless_fixture_card_goldens(names)
}

/// Runtime-root-aware variant of [`bless_fixture_card_goldens`].
///
/// This is used by `xtask` so a reused shared target directory cannot make a
/// cached binary read or write fixtures from the checkout where it was compiled.
pub fn bless_fixture_card_goldens_from_workspace(
    workspace: &Path,
    names: &[&str],
) -> Result<Vec<PathBuf>, String> {
    json::bless_fixture_card_goldens_from_workspace(workspace, names)
}

/// Regenerate surface goldens (`expected.lsp.json`, `expected.repair-queue.json`)
/// for a single named fixture, writing LF line endings.
///
/// `surfaces` must contain only `"lsp"`, `"repair-queue"`, or
/// `"comment-plan"`. Paths inside the rendered JSON are normalised to relative
/// form so goldens are byte-stable.
pub fn bless_fixture_surface_goldens(
    fixture: &str,
    surfaces: &[&str],
) -> Result<Vec<PathBuf>, String> {
    json::bless_fixture_surface_goldens(fixture, surfaces)
}

/// Runtime-root-aware variant of [`bless_fixture_surface_goldens`].
///
/// This is used by `xtask` so a reused shared target directory cannot make a
/// cached binary read fixtures from the checkout where it was compiled.
pub fn bless_fixture_surface_goldens_from_workspace(
    workspace: &Path,
    fixture: &str,
    surfaces: &[&str],
) -> Result<Vec<PathBuf>, String> {
    json::bless_fixture_surface_goldens_from_workspace(workspace, fixture, surfaces)
}

/// Render a single surface for a fixture as the bless path would write it
/// (normalised, LF-terminated) without writing a file.
///
/// Used by `check-fixture-surface-parity` to produce the reference text for
/// diffing against the committed golden.
pub fn render_fixture_surface(fixture: &str, surface: &str) -> Result<String, String> {
    json::render_fixture_surface(fixture, surface)
}

/// Runtime-root-aware variant of [`render_fixture_surface`].
///
/// This is used by `xtask` so parity and determinism checks render from the
/// active workspace root selected at runtime.
pub fn render_fixture_surface_from_workspace(
    workspace: &Path,
    fixture: &str,
    surface: &str,
) -> Result<String, String> {
    json::render_fixture_surface_from_workspace(workspace, fixture, surface)
}

pub fn render_json(output: &AnalyzeOutput) -> String {
    json::render(output)
}

/// Render the JSON analyze artifact with attached traceable evidence metadata.
///
/// The `provenance` block is inserted as a nested object in the output.
/// `tool_version` also appears top-level beside `tool` for consumer grep-ability.
pub fn render_json_with_provenance(output: &AnalyzeOutput, provenance: &Provenance) -> String {
    json::render_with_provenance(output, provenance)
}

pub fn render_human(output: &AnalyzeOutput) -> String {
    human::render(output)
}

pub fn render_human_short(output: &AnalyzeOutput) -> String {
    human::render_short(output)
}

pub fn render_markdown(output: &AnalyzeOutput) -> String {
    markdown::render(output)
}

pub fn render_pr_summary(output: &AnalyzeOutput) -> String {
    markdown::render_pr_summary(output)
}

pub fn render_github_summary(output: &AnalyzeOutput) -> String {
    markdown::render_github_summary(output)
}

pub fn render_sarif(output: &AnalyzeOutput) -> String {
    sarif::render(output)
}

pub fn render_comment_plan(output: &AnalyzeOutput) -> String {
    comment_plan::render(output)
}

pub fn render_lsp(output: &AnalyzeOutput) -> String {
    lsp::render(output)
}

pub fn project_editor(output: &AnalyzeOutput) -> lsp::EditorProjection {
    lsp::project_editor(output)
}

/// Project only the canonical editor diagnostics without constructing hovers
/// or code actions that a caller does not need.
pub fn project_editor_diagnostics(output: &AnalyzeOutput) -> Vec<lsp::EditorDiagnostic> {
    lsp::project_editor_diagnostics(output)
}

/// Project only actionable canonical editor diagnostics for live transport.
pub fn project_actionable_editor_diagnostics(output: &AnalyzeOutput) -> Vec<lsp::EditorDiagnostic> {
    lsp::project_actionable_editor_diagnostics(output)
}

/// Render the rich hover markdown for a single [`ReviewCard`] as the live LSP
/// server would produce it.
///
/// The returned string is the same content that `lsp.json` embeds in its
/// `hovers[].contents` field: obligations, evidence state (contract / guard /
/// reach / witness), hazard families, verify commands, witness route, handoff
/// commands, and the advisory trust boundary.
///
/// This is **advisory evidence only**: no memory-safety proof, no UB-free
/// status, no Miri-clean status, and not a site-execution claim unless a
/// matching witness receipt says so.
pub fn render_lsp_hover(card: &ReviewCard) -> String {
    lsp::render_hover(card)
}

pub fn render_witness_plan(output: &AnalyzeOutput) -> String {
    witness_plan::render(output)
}

pub fn render_repair_queue(output: &AnalyzeOutput) -> String {
    repair_queue::render(output)
}

/// Render the `unsafe-review-gate.json` routing manifest (SPEC-0034).
///
/// The manifest is a thin index over the artifacts a `first-pr`/`repo` run
/// produced, plus the SPEC-0030 movement summary.  It is fully deterministic —
/// it carries no timestamp or wall-time field — so it is safe to include in
/// byte-compared goldens or reproducibility rails.
pub fn render_gate_manifest(output: &AnalyzeOutput) -> String {
    gate_manifest::render(output)
}

/// Render `unsafe-review-gate.json` for a `repo` run (SPEC-0034 parity).
///
/// Repo mode writes a single output file rather than a bundle directory, so
/// the first-pr-specific artifact pointers (`pr_summary`, `sarif`, `lsp`, …)
/// are absent — they were not emitted and must not be faked (SPEC-0034:
/// "Missing optional artifacts are omitted, not faked.").
///
/// `report_filename` is the basename of the `--out` file (e.g. `"repo.json"`);
/// it becomes the `artifacts.cards` pointer so downstream consumers can locate
/// the ReviewCard dataset relative to the manifest.
///
/// The `status` field is always `"advisory"` — the manifest carries posture,
/// never a merge verdict, not proof, not UB-free, not Miri-clean, not a
/// site-execution claim.
pub fn render_gate_manifest_repo(output: &AnalyzeOutput, report_filename: &str) -> String {
    gate_manifest::render_repo(output, report_filename)
}

/// Render the `usefulness-telemetry.json` low-noise usefulness telemetry artifact (SPEC-0038).
///
/// This is a pure projection from `AnalyzeOutput` — no new analysis.
/// Diagnostic operational usefulness only: not calibrated precision/recall,
/// not accuracy measurement, not memory-safety proof, not UB-free status,
/// not Miri-clean status, not a site-execution claim, not a gate, and not
/// a merge verdict.
pub fn render_usefulness_telemetry(output: &AnalyzeOutput) -> String {
    usefulness_telemetry::render(output)
}

/// Render `usefulness-telemetry.json` with CLI-layer scan cost injected
/// (SPEC-0038 §scan_cost).
///
/// The `cost` argument carries `elapsed_ms` and `output_bytes_total` measured
/// in the CLI emit layer — fields that core cannot compute itself (core must
/// not measure wall time).  When `cost` is `None` the `scan_cost` section is
/// omitted and the output is identical to `render_usefulness_telemetry`.
pub fn render_usefulness_telemetry_with_cost(
    output: &AnalyzeOutput,
    cost: Option<&ScanCost>,
) -> String {
    usefulness_telemetry::render_with_cost(output, cost)
}

pub fn project_review_card_confirmation(card: &ReviewCard) -> ReviewCardConfirmationProjection {
    let minimal_repro = confirmation::minimal_repro(card);
    ReviewCardConfirmationProjection {
        hypothesis_to_confirm: confirmation::hypothesis_to_confirm(card),
        build_this_first: confirmation::build_this_first(card).summary,
        minimal_repro_steps: minimal_repro.steps().to_vec(),
        minimal_repro_limitation: minimal_repro.limitation().to_string(),
        confirmation_step: confirmation::confirmation_step(card),
    }
}

pub fn render_badge_jsons(output: &AnalyzeOutput) -> (String, String) {
    badges::render(output)
}

pub fn compare_outcome_json(before_json: &str, after_json: &str) -> Result<OutcomeReport, String> {
    outcome::compare_json(before_json, after_json)
}

pub fn render_outcome_json(report: &OutcomeReport) -> String {
    outcome::render_json(report)
}

pub fn render_outcome_markdown(report: &OutcomeReport) -> String {
    outcome::render_markdown(report)
}

pub fn render_receipt_audit_json(report: &ReceiptAuditReport) -> String {
    receipt_audit::render_json(report)
}

pub fn render_receipt_audit_markdown(report: &ReceiptAuditReport) -> String {
    receipt_audit::render_markdown(report)
}

pub fn render_policy_report_json(report: &PolicyReport) -> String {
    policy_report::render_json(report)
}

pub fn render_policy_report_markdown(report: &PolicyReport) -> String {
    policy_report::render_markdown(report)
}

pub fn explain_card(output: &AnalyzeOutput, id: &CardId) -> Option<String> {
    output
        .cards
        .iter()
        .find(|card| &card.id == id)
        .map(markdown::render_card_detail)
}

pub fn collect_context(output: &AnalyzeOutput, id: &CardId) -> Option<String> {
    output
        .cards
        .iter()
        .find(|card| &card.id == id)
        .map(|card| agent::render_with_output(output, card))
}

/// Render a `file_range_scan` envelope for SPEC-0033.
///
/// Collects packets for all cards whose unsafe site overlaps `file:line_start-line_end`
/// (1-based, both endpoints inclusive).  If `changed_only` is `true`, further
/// restricts to cards whose `baseline_state` is `new` or `worsened` (SPEC-0030).
///
/// File paths are matched by normalizing both to forward-slash display form,
/// then checking whether the card's site file ends with the queried fragment so
/// callers may pass either root-relative or short relative paths (e.g. `src/lib.rs`).
/// The `root` parameter is used to strip a leading root prefix from the queried path
/// before the suffix comparison.
pub fn collect_context_range(
    output: &AnalyzeOutput,
    root: &Path,
    file: &Path,
    line_start: u32,
    line_end: u32,
    changed_only: bool,
) -> String {
    let queried_display = path_display(file);
    let root_display = path_display(root);

    // Strip the workspace root prefix from the queried path so that callers
    // can use either a short relative path ("src/lib.rs") or an absolute one.
    let queried_suffix = queried_display
        .strip_prefix(&root_display)
        .map(|rest| rest.trim_start_matches('/'))
        .unwrap_or(&queried_display);

    // Pre-filter to the requested file; range + changed-only filtering happens
    // inside render_range_scan.
    let file_cards: Vec<&ReviewCard> = output
        .cards
        .iter()
        .filter(|card| {
            let card_file = path_display(&card.site.location.file);
            card_file == queried_display
                || card_file == queried_suffix
                || card_file.ends_with(&format!("/{queried_suffix}"))
        })
        .collect();

    let statuses = comment_plan::card_statuses(output);
    agent::render_range_scan_with_output(
        output,
        queried_display,
        line_start,
        line_end,
        changed_only,
        &file_cards,
        None,
        &statuses,
    )
}

/// Result returned by `baseline_init` summarizing what was captured.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BaselineInitResult {
    /// Number of open actionable cards captured as baseline entries.
    pub captured: usize,
    /// Whether the baseline ledger file already existed before this run.
    pub ledger_existed: bool,
    /// Path to the baseline ledger written.
    pub ledger_path: PathBuf,
    /// Path to the coverage snapshot written.
    pub snapshot_path: PathBuf,
    /// The open actionable cards captured, in scan order.
    /// Used by the CLI to display a debt scope listing for brownfield adoption.
    pub cards: Vec<ReviewCard>,
}

struct BaselineInitPlan {
    result: BaselineInitResult,
    ledger_entries: Vec<crate::policy::LedgerEntry>,
    snapshot_entries: BTreeMap<String, crate::policy::SnapshotCoverage>,
}

/// `baseline init` (SPEC-0030): scan the repo for open actionable cards, capture each
/// card's identity and coverage state, and write both the baseline ledger and the coverage
/// snapshot.  Idempotent — re-running overwrites with a fresh snapshot of the current state.
///
/// The honest default `reason` and `review_after` are set to record pre-existing debt only;
/// no card is marked safe, reviewed, or UB-free.
///
/// `review_after` defaults to one year from today's date.
pub fn baseline_init(
    root: &Path,
    out: Option<&Path>,
    review_after: Option<&str>,
) -> Result<BaselineInitResult, String> {
    let plan = baseline_init_plan(root, out, review_after)?;
    crate::policy::merge_and_write_baseline_ledger(&plan.result.ledger_path, &plan.ledger_entries)?;
    crate::policy::write_coverage_snapshot(&plan.result.snapshot_path, &plan.snapshot_entries)?;
    Ok(plan.result)
}

/// Preview the baseline entries that `baseline init` would author without writing files.
/// The returned result is the same plan used by the applying command, preserving one
/// source of truth for card selection and output paths.
pub fn baseline_init_preview(
    root: &Path,
    out: Option<&Path>,
    review_after: Option<&str>,
) -> Result<BaselineInitResult, String> {
    Ok(baseline_init_plan(root, out, review_after)?.result)
}

fn baseline_init_plan(
    root: &Path,
    out: Option<&Path>,
    review_after: Option<&str>,
) -> Result<BaselineInitPlan, String> {
    use crate::domain::coverage::CoverageBlock;
    use crate::policy::{LedgerEntry, SnapshotCoverage};
    use std::collections::BTreeMap;

    let ledger_path = out
        .map(Path::to_path_buf)
        .unwrap_or_else(|| root.join("policy/unsafe-review-baseline.toml"));
    let snapshot_path = baseline_snapshot_path(&ledger_path);
    let ledger_existed = ledger_path.is_file();

    // Run a full repo scan to get all current cards.
    let output = pipeline::analyze(AnalyzeInput {
        root: root.to_path_buf(),
        scope: Scope::Repo,
        diff: DiffSource::NoneRepoScan,
        mode: AnalysisMode::Repo,
        policy: PolicyMode::Advisory,
        include_unchanged_tests: true,
        max_cards: None,
    })?;

    // Determine review_after date (required by ledger validator).
    let review_after = review_after
        .map(ToOwned::to_owned)
        .unwrap_or_else(default_review_after_date);

    // Collect open actionable cards.
    let mut ledger_entries: Vec<LedgerEntry> = Vec::new();
    let mut snapshot_entries: BTreeMap<String, SnapshotCoverage> = BTreeMap::new();
    let mut actionable_cards: Vec<ReviewCard> = Vec::new();

    for card in &output.cards {
        if card.class.is_actionable() {
            ledger_entries.push(LedgerEntry {
                card_id: card.id.0.clone(),
                owner: "baseline-init".to_string(),
                reason: "captured by `baseline init`; pre-existing debt, not reviewed as safe"
                    .to_string(),
                evidence: "baseline-init: captured by baseline init; pre-existing debt".to_string(),
                review_after: Some(review_after.clone()),
                expires: None,
            });
            let block = CoverageBlock::derive(card);
            snapshot_entries.insert(
                card.id.0.clone(),
                SnapshotCoverage {
                    contract_coverage: block.contract_coverage.as_str().to_string(),
                    guard_coverage: block.guard_coverage.as_str().to_string(),
                    test_reach_coverage: block.test_reach_coverage.as_str().to_string(),
                    witness_receipt_coverage: block.witness_receipt_coverage.as_str().to_string(),
                },
            );
            actionable_cards.push(card.clone());
        }
    }

    Ok(BaselineInitPlan {
        result: BaselineInitResult {
            captured: ledger_entries.len(),
            ledger_existed,
            ledger_path,
            snapshot_path,
            cards: actionable_cards,
        },
        ledger_entries,
        snapshot_entries,
    })
}

/// `baseline add` (SPEC-0030): add or update a single baseline entry (plus its snapshot state)
/// by re-analyzing the repo, finding the card matching `card_id`, and recording its current
/// coverage state.
///
/// Returns `Err` if the card cannot be found in the current scan.
pub fn baseline_add(
    root: &Path,
    card_id: &str,
    owner: &str,
    reason: &str,
    evidence: &str,
    review_after: Option<&str>,
    out: Option<&Path>,
) -> Result<(), String> {
    use crate::domain::coverage::CoverageBlock;
    use crate::policy::{
        LedgerEntry, SnapshotCoverage, load_coverage_snapshot, merge_and_write_baseline_ledger,
        write_coverage_snapshot,
    };
    use std::collections::BTreeMap;

    let ledger_path = out
        .map(Path::to_path_buf)
        .unwrap_or_else(|| root.join("policy/unsafe-review-baseline.toml"));
    let snapshot_path = baseline_snapshot_path(&ledger_path);

    // Run a full repo scan.
    let output = pipeline::analyze(AnalyzeInput {
        root: root.to_path_buf(),
        scope: Scope::Repo,
        diff: DiffSource::NoneRepoScan,
        mode: AnalysisMode::Repo,
        policy: PolicyMode::Advisory,
        include_unchanged_tests: true,
        max_cards: None,
    })?;

    // Find the specific card.
    let card = output
        .cards
        .iter()
        .find(|card| card.id.0 == card_id)
        .ok_or_else(|| format!("card `{card_id}` not found in current repo scan"))?;

    let review_after = review_after
        .map(ToOwned::to_owned)
        .unwrap_or_else(default_review_after_date);

    let entry = LedgerEntry {
        card_id: card_id.to_string(),
        owner: owner.to_string(),
        reason: reason.to_string(),
        evidence: evidence.to_string(),
        review_after: Some(review_after),
        expires: None,
    };

    // Update the snapshot.
    let mut snapshot = load_coverage_snapshot(&snapshot_path)?;
    let block = CoverageBlock::derive(card);
    snapshot.insert(
        card_id.to_string(),
        SnapshotCoverage {
            contract_coverage: block.contract_coverage.as_str().to_string(),
            guard_coverage: block.guard_coverage.as_str().to_string(),
            test_reach_coverage: block.test_reach_coverage.as_str().to_string(),
            witness_receipt_coverage: block.witness_receipt_coverage.as_str().to_string(),
        },
    );

    // Sort snapshot to BTreeMap (already sorted).
    let sorted_snapshot: BTreeMap<String, SnapshotCoverage> = snapshot.into_iter().collect();

    merge_and_write_baseline_ledger(&ledger_path, &[entry])?;
    write_coverage_snapshot(&snapshot_path, &sorted_snapshot)?;

    Ok(())
}

/// `baseline status` (issue #1893): classify every baseline ledger entry, plus every
/// currently open actionable card the ledger does not represent, into the ten SPEC-0030
/// baseline-health buckets. Read-only — runs a full repo scan and reads policy files;
/// writes nothing.
///
/// Degrades instead of failing outright when the baseline ledger itself fails the
/// analyzer's strict per-entry validation (bad card_id shape, or missing
/// owner/reason/evidence) — implemented in `baseline_status_with_date`; see also
/// [`crate::policy::baseline_health::BaselineHealthReport::card_scan_error`].
pub fn baseline_status(root: &Path) -> Result<BaselineHealthReport, String> {
    let today = policy_report::current_utc_date()?;
    baseline_status_with_date(root, &today)
}

fn baseline_status_with_date(root: &Path, today: &str) -> Result<BaselineHealthReport, String> {
    use crate::policy::{
        LedgerKind, baseline_health, is_expired, load_baseline_entries_lenient,
        load_coverage_snapshot, load_ledger_entries,
    };

    // Load the baseline ledger leniently FIRST (cheap, no repo scan) so its result is
    // available before attempting the full-repo card scan below (issue #1893 review
    // finding).
    let ledger_path = root.join("policy/unsafe-review-baseline.toml");
    let ledger_entries = load_baseline_entries_lenient(&ledger_path)?;
    // Capture the strict loader's exact failure before the repo scan. On Windows the
    // analyzer's file discovery can normalize the root while loading policy, so
    // comparing a rendered path substring is not reliable (mixed `/` and `\\`
    // separators can make the same path compare unequal). The lenient read above
    // already proved the ledger is syntactically usable for per-entry diagnosis; the
    // same strict-loader error from `pipeline::analyze`, after separator normalization,
    // therefore identifies precisely the degraded health case this command is allowed
    // to tolerate. Every other analyzer error remains fatal.
    let strict_baseline_error = load_ledger_entries(&ledger_path, LedgerKind::Baseline).err();

    // `pipeline::analyze` loads `PolicyState` internally, which uses the *strict*
    // ledger loader for the baseline file — the exact per-entry validation
    // `identity_unmatched` exists to tolerate. A baseline ledger entry with a bad
    // card_id shape or missing owner/reason/evidence (real TOML, just failing that
    // strict per-entry check) would otherwise abort the repo scan entirely, defeating
    // the corrupt-ledger-diagnosis purpose of this command before it could ever report
    // `identity_unmatched` for the offending row. Since `load_baseline_entries_lenient`
    // just proved the file itself parses (only the strict per-entry checks differ),
    // treat that specific failure as "current-card data unavailable" and still produce
    // a report — every other failure (a genuinely unparseable ledger, a broken
    // suppression ledger, a source-scan error, and so on) still fails `baseline_status`
    // outright, same as before.
    let analyze_result = pipeline::analyze(AnalyzeInput {
        root: root.to_path_buf(),
        scope: Scope::Repo,
        diff: DiffSource::NoneRepoScan,
        mode: AnalysisMode::Repo,
        policy: PolicyMode::Advisory,
        include_unchanged_tests: true,
        max_cards: None,
    });
    //
    // The degrade branch keys off equality with the strict baseline-loader failure
    // captured above, normalizing only path separators. This keeps the exception
    // fail-closed: a source scan, suppression-ledger, or other analyzer error cannot be
    // mistaken for the diagnosable baseline-entry failure.
    let (current_cards, card_scan_error) = match analyze_result {
        Ok(output) => (output.cards, None),
        Err(err)
            if strict_baseline_error
                .as_deref()
                .is_some_and(|expected| expected.replace('\\', "/") == err.replace('\\', "/")) =>
        {
            (Vec::new(), Some(err))
        }
        Err(err) => return Err(err),
    };

    // Only currently-active (non-expired) suppressions count as `suppression_overlap`
    // (issue #1893 review finding): an expired suppression is already surfaced as its
    // own ledger-health problem (`policy report`'s `expired_suppressions`), and folding
    // it into `suppression_overlap` too would double-report the same stale entry under
    // two different labels. Reuses the canonical expiry predicate — no second expiry
    // model. Note this does not affect `new_unbaselined`: the core analyzer already
    // classifies any card matching *any* suppression entry (active or expired) as
    // `Suppressed`, which is not actionable, before `baseline_health` ever sees it.
    let suppression_path = root.join("policy/unsafe-review-suppressions.toml");
    let suppression_ids: BTreeSet<String> =
        load_ledger_entries(&suppression_path, LedgerKind::Suppression)?
            .into_iter()
            .filter(|entry| !is_expired(entry.expires.as_deref(), today))
            .map(|entry| entry.card_id)
            .collect();

    let snapshot_path = baseline_snapshot_path(&ledger_path);
    let (snapshot, snapshot_load_error) = match load_coverage_snapshot(&snapshot_path) {
        Ok(map) => (Some(map), None),
        Err(err) => (None, Some(err)),
    };

    let input = baseline_health::BaselineHealthInput {
        today,
        current_cards: &current_cards,
        ledger_entries: &ledger_entries,
        suppression_ids: &suppression_ids,
        snapshot: snapshot.as_ref(),
        snapshot_load_error: snapshot_load_error.as_deref(),
    };
    let mut report = baseline_health::classify(&input);
    report.card_scan_error = card_scan_error;
    Ok(report)
}

/// `baseline refresh --dry-run` (issue #1893): build the deterministic per-entry action
/// plan from the same classification as `baseline_status`. Writes nothing; there is no
/// apply mode (SPEC-0030 non-goal — a future apply command would be separately
/// approved, explicit, idempotent, and refuse to overwrite a changed ledger).
pub fn baseline_refresh_preview(root: &Path) -> Result<BaselineRefreshPlan, String> {
    let report = baseline_status(root)?;
    Ok(crate::policy::baseline_health::build_refresh_plan(&report))
}

pub fn render_baseline_status_json(report: &BaselineHealthReport) -> String {
    crate::output::baseline_health::render_status_json(report)
}

pub fn render_baseline_status_human(report: &BaselineHealthReport) -> String {
    crate::output::baseline_health::render_status_human(report)
}

pub fn render_baseline_refresh_json(plan: &BaselineRefreshPlan) -> String {
    crate::output::baseline_health::render_refresh_json(plan)
}

pub fn render_baseline_refresh_human(plan: &BaselineRefreshPlan) -> String {
    crate::output::baseline_health::render_refresh_human(plan)
}

pub use crate::policy::baseline_health::{
    BaselineHealthCounts, BaselineHealthEntry, BaselineHealthReport, BaselineRefreshPlan,
    HealthBucket, RefreshAction, RefreshPlanEntry, RefreshPlanSummary,
};

/// Derive the coverage snapshot path from the baseline ledger path: the snapshot is written
/// as a sibling `<ledger-stem>-snapshot.toml`. The default ledger
/// `policy/unsafe-review-baseline.toml` keeps producing
/// `policy/unsafe-review-baseline-snapshot.toml`, and a custom `--out` keeps both files
/// together instead of writing the snapshot into the scanned `--root` (which would edit a
/// repo unsafe-review only promised to read).
fn baseline_snapshot_path(ledger_path: &Path) -> PathBuf {
    let stem = ledger_path
        .file_stem()
        .map(|stem| stem.to_string_lossy().into_owned())
        .unwrap_or_else(|| "unsafe-review-baseline".to_string());
    ledger_path.with_file_name(format!("{stem}-snapshot.toml"))
}

/// Default `review_after` date: one year from today (ISO 8601 YYYY-MM-DD).
fn default_review_after_date() -> String {
    // Use a fixed date offset from June 2026 (the current date per context).
    // We can't use std::time for date arithmetic without chrono, so we hardcode
    // a safe one-year increment from a known epoch base.
    // This is called only in baseline authoring, not in analysis; precision is not critical.
    compute_review_after_date()
}

fn compute_review_after_date() -> String {
    // Use SystemTime to get the current date offset by ~365 days.
    use std::time::{SystemTime, UNIX_EPOCH};
    let secs = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    // Approximate: add 365 days worth of seconds.
    let future_secs = secs + 365 * 24 * 3600;
    // Convert to a YYYY-MM-DD string using a simple algorithm.
    unix_secs_to_iso_date(future_secs)
}

/// Extend the date-only helper to a full RFC3339 UTC timestamp (e.g. `2026-06-07T21:30:00Z`).
///
/// The time portion is always `T00:00:00Z` (midnight UTC) because we only have
/// second-level granularity and already discard the sub-day remainder in the
/// date calculation.  For a provenance `generated_at` field this is sufficient
/// — the date binds the artifact to a calendar day without requiring chrono.
pub(crate) fn unix_secs_to_iso_datetime_utc(secs: u64) -> String {
    let date = unix_secs_to_iso_date(secs);
    // Compute HH:MM:SS from the remaining seconds in the day.
    let remainder = secs % 86400;
    let hh = remainder / 3600;
    let mm = (remainder % 3600) / 60;
    let ss = remainder % 60;
    format!("{date}T{hh:02}:{mm:02}:{ss:02}Z")
}

fn unix_secs_to_iso_date(secs: u64) -> String {
    // Days since Unix epoch.
    let days = secs / 86400;
    // Gregorian calendar calculation.
    let mut remaining_days = days;
    let mut year = 1970u32;
    loop {
        let days_in_year = if is_leap_year(year) { 366 } else { 365 };
        if remaining_days < days_in_year {
            break;
        }
        remaining_days -= days_in_year;
        year += 1;
    }
    let mut month = 1u32;
    loop {
        let days_in_month = days_in_month(year, month);
        if remaining_days < days_in_month {
            break;
        }
        remaining_days -= days_in_month;
        month += 1;
    }
    let day = remaining_days + 1;
    format!("{year:04}-{month:02}-{day:02}")
}

fn is_leap_year(year: u32) -> bool {
    year.is_multiple_of(400) || (year.is_multiple_of(4) && !year.is_multiple_of(100))
}

fn days_in_month(year: u32, month: u32) -> u64 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 => {
            if is_leap_year(year) {
                29
            } else {
                28
            }
        }
        _ => 30,
    }
}

pub use outcome::OutcomeReport;
pub use policy_report::PolicyReport;
pub use receipts::ReceiptAuditReport;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::domain::coverage::CoverageBlock;
    use crate::policy::{LedgerKind, load_coverage_snapshot, load_ledger_entries};
    use std::fs;
    use std::time::{SystemTime, UNIX_EPOCH};

    #[test]
    fn analysis_mode_strings_cover_every_variant() {
        assert_eq!(AnalysisMode::Instant.as_str(), "instant");
        assert_eq!(AnalysisMode::Draft.as_str(), "draft");
        assert_eq!(AnalysisMode::Ready.as_str(), "ready");
        assert_eq!(AnalysisMode::Repo.as_str(), "repo");
    }

    #[test]
    fn policy_mode_strings_cover_every_variant() {
        assert_eq!(PolicyMode::Advisory.as_str(), "advisory");
        assert_eq!(PolicyMode::NoNewDebt.as_str(), "no-new-debt");
        assert_eq!(PolicyMode::Blocking.as_str(), "blocking");
    }

    #[test]
    fn analyze_input_default_is_advisory_diff_draft_with_unchanged_tests() {
        let input = AnalyzeInput::default();

        assert_eq!(input.root, PathBuf::from("."));
        assert_eq!(input.scope, Scope::Diff);
        assert_eq!(input.diff, DiffSource::NoneRepoScan);
        assert_eq!(input.mode, AnalysisMode::Draft);
        assert_eq!(input.policy, PolicyMode::Advisory);
        assert!(input.include_unchanged_tests);
        assert_eq!(input.max_cards, None);
    }

    #[test]
    fn baseline_snapshot_path_keeps_default_canonical_location() {
        let ledger = Path::new("repo/policy/unsafe-review-baseline.toml");
        assert_eq!(
            baseline_snapshot_path(ledger),
            PathBuf::from("repo/policy/unsafe-review-baseline-snapshot.toml")
        );
    }

    #[test]
    fn baseline_snapshot_path_follows_custom_out_as_sibling() {
        let ledger = Path::new("elsewhere/bun-baseline.toml");
        assert_eq!(
            baseline_snapshot_path(ledger),
            PathBuf::from("elsewhere/bun-baseline-snapshot.toml")
        );
    }

    #[test]
    fn baseline_snapshot_path_handles_extension_less_out() {
        let ledger = Path::new("elsewhere/baseline");
        assert_eq!(
            baseline_snapshot_path(ledger),
            PathBuf::from("elsewhere/baseline-snapshot.toml")
        );
    }

    #[test]
    fn baseline_add_persists_exact_coverage_block_snapshot_for_canonical_identity()
    -> Result<(), String> {
        // Advisory parity proof for issue #2122: baseline_add is a ReviewCard
        // consumer. It must resolve the exact canonical id from the current repo
        // scan and persist the four CoverageBlock::derive slots without
        // reclassification. This is ledger/snapshot evidence, not a safety,
        // UB-free, Miri-clean, or site-execution claim.
        let root = unique_temp_dir("baseline-add-parity-success")?;
        fs::create_dir_all(&root).map_err(|err| format!("create temp root failed: {err}"))?;
        install_fixture_repo(&root, "raw_pointer_alignment")?;

        let output = pipeline::analyze(AnalyzeInput {
            root: root.clone(),
            scope: Scope::Repo,
            diff: DiffSource::NoneRepoScan,
            mode: AnalysisMode::Repo,
            policy: PolicyMode::Advisory,
            include_unchanged_tests: true,
            max_cards: None,
        })?;
        let card_id = output
            .cards
            .first()
            .ok_or("fixture should emit at least one card")?
            .id
            .0
            .clone();
        let source_card = output
            .cards
            .iter()
            .find(|card| card.id.0 == card_id)
            .ok_or("selected card disappeared")?
            .clone();
        let expected_block = CoverageBlock::derive(&source_card);

        baseline_add(
            &root,
            &card_id,
            "triage-owner",
            "pre-existing debt; not reviewed as safe",
            "baseline-add parity proof",
            Some("2027-08-10"),
            None,
        )?;

        let ledger_path = root.join("policy/unsafe-review-baseline.toml");
        let snapshot_path = baseline_snapshot_path(&ledger_path);
        let ledger_entries = load_ledger_entries(&ledger_path, LedgerKind::Baseline)?;
        expect_eq("ledger entry count", ledger_entries.len(), 1)?;
        let ledger_entry = &ledger_entries[0];
        expect_eq(
            "ledger card_id",
            ledger_entry.card_id.as_str(),
            card_id.as_str(),
        )?;
        expect_eq("ledger owner", ledger_entry.owner.as_str(), "triage-owner")?;
        expect_eq(
            "ledger reason",
            ledger_entry.reason.as_str(),
            "pre-existing debt; not reviewed as safe",
        )?;
        expect_eq(
            "ledger evidence",
            ledger_entry.evidence.as_str(),
            "baseline-add parity proof",
        )?;
        expect_eq(
            "ledger review_after",
            ledger_entry.review_after.as_deref(),
            Some("2027-08-10"),
        )?;
        // Advisory ledger fields stay as ledger metadata; classification stays on the card.
        expect_eq(
            "ledger owner does not reclassify ReviewCard class",
            ledger_entry.owner.as_str() != source_card.class.as_str(),
            true,
        )?;

        let snapshot = load_coverage_snapshot(&snapshot_path)?;
        let stored = snapshot
            .get(&card_id)
            .ok_or_else(|| format!("snapshot missing card_id {card_id}"))?;
        expect_eq(
            "contract_coverage parity",
            stored.contract_coverage.as_str(),
            expected_block.contract_coverage.as_str(),
        )?;
        expect_eq(
            "guard_coverage parity",
            stored.guard_coverage.as_str(),
            expected_block.guard_coverage.as_str(),
        )?;
        expect_eq(
            "test_reach_coverage parity",
            stored.test_reach_coverage.as_str(),
            expected_block.test_reach_coverage.as_str(),
        )?;
        expect_eq(
            "witness_receipt_coverage parity",
            stored.witness_receipt_coverage.as_str(),
            expected_block.witness_receipt_coverage.as_str(),
        )?;

        // Updating the same card keeps the same snapshot derivation but overwrites
        // ledger metadata (owner/reason/evidence are ledger fields, not ReviewCard fields).
        baseline_add(
            &root,
            &card_id,
            "second-owner",
            "updated reason; still debt",
            "second evidence",
            Some("2027-09-01"),
            None,
        )?;
        let ledger_entries_2 = load_ledger_entries(&ledger_path, LedgerKind::Baseline)?;
        expect_eq("ledger entry count after update", ledger_entries_2.len(), 1)?;
        expect_eq(
            "ledger owner after update",
            ledger_entries_2[0].owner.as_str(),
            "second-owner",
        )?;
        let snapshot_2 = load_coverage_snapshot(&snapshot_path)?;
        let stored_2 = snapshot_2
            .get(&card_id)
            .ok_or_else(|| format!("snapshot missing after update {card_id}"))?;
        expect_eq(
            "contract_coverage stable after ledger update",
            stored_2.contract_coverage.as_str(),
            expected_block.contract_coverage.as_str(),
        )?;
        expect_eq(
            "witness_receipt_coverage stable after ledger update",
            stored_2.witness_receipt_coverage.as_str(),
            expected_block.witness_receipt_coverage.as_str(),
        )?;

        fs::remove_dir_all(&root).map_err(|err| format!("remove temp root failed: {err}"))?;
        Ok(())
    }

    #[test]
    fn baseline_add_missing_identity_fails_without_mutating_ledger_or_snapshot()
    -> Result<(), String> {
        // Advisory parity proof: a missing identity must fail closed with an
        // error naming the requested id, and must not mutate existing ledger or
        // snapshot state. No safety or reviewed-as-safe claim.
        let root = unique_temp_dir("baseline-add-missing-no-mutate")?;
        fs::create_dir_all(&root).map_err(|err| format!("create temp root failed: {err}"))?;
        install_fixture_repo(&root, "raw_pointer_alignment")?;

        let output = pipeline::analyze(AnalyzeInput {
            root: root.clone(),
            scope: Scope::Repo,
            diff: DiffSource::NoneRepoScan,
            mode: AnalysisMode::Repo,
            policy: PolicyMode::Advisory,
            include_unchanged_tests: true,
            max_cards: None,
        })?;
        let real_id = output
            .cards
            .first()
            .ok_or("fixture should emit at least one card")?
            .id
            .0
            .clone();

        baseline_add(
            &root,
            &real_id,
            "owner-a",
            "existing debt",
            "evidence-a",
            Some("2027-08-10"),
            None,
        )?;

        let ledger_path = root.join("policy/unsafe-review-baseline.toml");
        let snapshot_path = baseline_snapshot_path(&ledger_path);
        let ledger_before = fs::read_to_string(&ledger_path)
            .map_err(|err| format!("read ledger before failed: {err}"))?;
        let snapshot_before = fs::read_to_string(&snapshot_path)
            .map_err(|err| format!("read snapshot before failed: {err}"))?;

        let missing_id = "UR-missing-fixture-src-lib-rs-owner-operation-unknown-c999";
        let err = baseline_add(
            &root,
            missing_id,
            "owner-b",
            "reason-b",
            "evidence-b",
            Some("2027-08-10"),
            None,
        )
        .err()
        .ok_or_else(|| "baseline_add with missing id should fail".to_string())?;
        if !err.contains(missing_id) {
            return Err(format!(
                "missing-id error should name the requested id: actual={err:?}, expected fragment={missing_id:?}"
            ));
        }
        if !err.contains("not found in current repo scan") {
            return Err(format!(
                "missing-id error should mention not found in current repo scan: actual={err:?}"
            ));
        }

        let ledger_after = fs::read_to_string(&ledger_path)
            .map_err(|err| format!("read ledger after failed: {err}"))?;
        let snapshot_after = fs::read_to_string(&snapshot_path)
            .map_err(|err| format!("read snapshot after failed: {err}"))?;
        expect_eq(
            "ledger unchanged after missing-id failure",
            ledger_after,
            ledger_before,
        )?;
        expect_eq(
            "snapshot unchanged after missing-id failure",
            snapshot_after,
            snapshot_before,
        )?;

        // A missing id must also fail when no ledger exists yet (fresh repo),
        // without creating one.
        let fresh_root = unique_temp_dir("baseline-add-missing-fresh")?;
        fs::create_dir_all(&fresh_root)
            .map_err(|err| format!("create fresh root failed: {err}"))?;
        install_fixture_repo(&fresh_root, "raw_pointer_alignment")?;
        let missing_err = baseline_add(
            &fresh_root,
            missing_id,
            "owner-c",
            "reason-c",
            "evidence-c",
            Some("2027-08-10"),
            None,
        )
        .err()
        .ok_or_else(|| "fresh missing-id baseline_add should fail".to_string())?;
        if !missing_err.contains(missing_id) {
            return Err(format!(
                "fresh missing-id error should name the requested id: actual={missing_err:?}"
            ));
        }
        let fresh_ledger = fresh_root.join("policy/unsafe-review-baseline.toml");
        let fresh_snapshot = baseline_snapshot_path(&fresh_ledger);
        if fresh_ledger.exists() {
            return Err("fresh missing-id must not create a ledger file".to_string());
        }
        if fresh_snapshot.exists() {
            return Err("fresh missing-id must not create a snapshot file".to_string());
        }

        fs::remove_dir_all(&root).map_err(|err| format!("remove temp root failed: {err}"))?;
        fs::remove_dir_all(&fresh_root)
            .map_err(|err| format!("remove fresh root failed: {err}"))?;
        Ok(())
    }

    fn unique_temp_dir(prefix: &str) -> Result<PathBuf, String> {
        let nanos = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map_err(|err| format!("system clock before UNIX_EPOCH: {err}"))?
            .as_nanos();
        let pid = std::process::id();
        Ok(std::env::temp_dir().join(format!("{prefix}-{pid}-{nanos}")))
    }

    fn install_fixture_repo(root: &Path, fixture: &str) -> Result<(), String> {
        let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        let fixture_root = manifest_dir.join("../../fixtures").join(fixture);
        if !fixture_root.is_dir() {
            return Err(format!("fixture not found: {}", fixture_root.display()));
        }
        copy_dir_recursive(&fixture_root.join("src"), &root.join("src"))?;
        let cargo_src = fixture_root.join("Cargo.toml");
        let cargo_dst = root.join("Cargo.toml");
        if cargo_src.is_file() {
            fs::copy(&cargo_src, &cargo_dst)
                .map_err(|err| format!("copy Cargo.toml failed: {err}"))?;
        }
        Ok(())
    }

    fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<(), String> {
        fs::create_dir_all(dst).map_err(|err| format!("create {} failed: {err}", dst.display()))?;
        for entry in
            fs::read_dir(src).map_err(|err| format!("read_dir {} failed: {err}", src.display()))?
        {
            let entry = entry.map_err(|err| format!("read_dir entry failed: {err}"))?;
            let file_type = entry
                .file_type()
                .map_err(|err| format!("file_type failed: {err}"))?;
            let src_path = entry.path();
            let dst_path = dst.join(entry.file_name());
            if file_type.is_dir() {
                copy_dir_recursive(&src_path, &dst_path)?;
            } else if file_type.is_file() {
                fs::copy(&src_path, &dst_path)
                    .map_err(|err| format!("copy {} failed: {err}", src_path.display()))?;
            }
        }
        Ok(())
    }

    fn expect_eq<T>(context: &str, actual: T, expected: T) -> Result<(), String>
    where
        T: std::fmt::Debug + PartialEq,
    {
        if actual == expected {
            Ok(())
        } else {
            Err(format!(
                "{context} mismatch: actual={actual:?}, expected={expected:?}"
            ))
        }
    }
}