majordomus_cli/capability/builtin/

evidence.rs

//! The `evidence` module: from a claim to the run that proves it, and back.
//!
//! `docs/CLAIMS.yaml` binds a claim to a test by path. [`crate::evidence`] binds that path
//! to the runs actually recorded against it. These capabilities are the one declaration of
//! that join, and every surface — the command line, the HTTP API and its OpenAPI operation,
//! the MCP tool a client reads — is derived from it. There is no second evidence model
//! behind any of them.
//!
//! # Both directions
//!
//! A relation that can only be walked one way is half a relation. `evidence.claim` answers
//! "what proves this claim"; `evidence.test` answers "what does this test prove", listing
//! every claim that names it. They read the same derivation, so the two answers cannot
//! disagree.
//!
//! # Why the recorder is here and not exposed over the network
//!
//! `evidence.record` writes a tracked file, and this executable's MCP and HTTP surfaces are
//! read-only — that is a property of the server, not an accident of what has been built.
//! So it declares a command line and nothing else, which
//! [`Visibility::Developer`](crate::capability::Visibility) is exactly the word for: offered
//! to whoever runs the executable and to nobody over a network. Declaring it as a capability
//! rather than as a hand-written command is what keeps it inside the registry, the command
//! graph and the generated reference instead of in the inventory of commands nothing derives.
//!
//! ```
//! use majordomus_cli::capability::builtin::evidence;
//!
//! let m = evidence::module();
//! assert_eq!(m.id.as_str(), "evidence");
//! let ids: Vec<&str> = m
//!     .capabilities
//!     .iter()
//!     .map(|e| e.capability.id.as_str())
//!     .collect();
//! assert_eq!(
//!     ids,
//!     [
//!         "evidence.report",
//!         "evidence.claim",
//!         "evidence.test",
//!         "evidence.record",
//!         "evidence.stamp"
//!     ]
//! );
//!
//! // the recorder writes a tracked file, so it is offered to whoever runs the executable
//! // and to nobody over a network; that is what keeps the server read-only
//! let record = m
//!     .capabilities
//!     .iter()
//!     .find(|e| e.capability.id.as_str() == "evidence.record")
//!     .unwrap();
//! assert!(record.capability.exposure.mcp.is_none());
//! assert!(record.capability.exposure.http.is_none());
//! assert_eq!(
//!     record.capability.exposure.cli.as_ref().unwrap().path,
//!     ["evidence".to_string(), "record".to_string()]
//! );
//! ```
//!
//! # Why the stamp is offered only to whoever runs the executable
//!
//! `evidence.stamp` writes nothing, but it reads a file whose path its caller names (the
//! report it digests) and measures the checkout it runs in. A network client must not choose
//! a path this executable reads, so the stamp too declares a command line and nothing else.

//! # Example
//!
//! The capabilities, and every projection — the command line, the HTTP operation, the MCP
//! tool — is derived from that one declaration.
//!
//! ```
//! use majordomus_cli::capability::builtin::evidence::module;
//! let m = module();
//! assert_eq!(m.id.as_str(), "evidence");
//! assert_eq!(m.capabilities.len(), 5);
//! ```

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::capability::benchmark::{BenchmarkCases, CaseContext, NamedCase};
use crate::capability::handler::{CapabilityError, Context};
use crate::capability::model::{
    BenchmarkPolicy, CachePolicy, CapabilityKind, CliExposure, Exposure, McpResource, Stability,
    WaiverReason,
};
use crate::capability::module::ModuleDescriptor;
use crate::evidence::{
    self, freshness, ClaimProof, EvidenceDropped, EvidenceProducer, EvidenceProvenance,
    EvidenceReport, EvidenceRunRecord, Execution, Ledger, LedgerTarget, Origin, ProofState,
    RecordRequest, StampRequest, TreeState,
};
use crate::{capability, module};

use super::{get, mcp};

/// The URI under which the whole evidence report is read as an MCP resource.
pub const EVIDENCE_URI: &str = "majordomus://evidence";

// ---------------------------------------------------------------- inputs

#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
/// Which part of the matrix to answer for, and at which revision.
///
/// Every filter narrows, and they compose; saying nothing asks for the whole matrix at the
/// working tree. A key nothing recognises is refused rather than dropped, because a
/// misspelled filter that read as "no filter" would answer a question nobody asked and look
/// like a clean one.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::EvidenceReportInput;
/// use majordomus_cli::evidence::{ProofState, TreeState};
///
/// let all: EvidenceReportInput = serde_json::from_str("{}").unwrap();
/// assert!(all.state.is_none() && all.status.is_none() && !all.findings_only);
/// assert!(all.presented.is_none(), "the working tree unless a commit is named");
///
/// let narrowed: EvidenceReportInput =
///     serde_json::from_str(r#"{"state": "stale", "findings_only": true}"#).unwrap();
/// assert_eq!(narrowed.state, Some(ProofState::Stale));
/// assert!(narrowed.findings_only);
///
/// let at: EvidenceReportInput =
///     serde_json::from_str(r#"{"presented": "HEAD", "presented_tree": "dirty"}"#).unwrap();
/// assert_eq!(at.presented.as_deref(), Some("HEAD"));
/// assert_eq!(at.presented_tree, Some(TreeState::Dirty));
///
/// assert!(serde_json::from_str::<EvidenceReportInput>(r#"{"states": "stale"}"#).is_err());
/// ```
pub struct EvidenceReportInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Only claims in this proof state (`proven`, `inputs_unchanged`, `stale`, `failing`,
    /// `not_run`, `unrunnable`, `no_test`). Absent: every claim.
    pub state: Option<ProofState>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Only claims declaring this status (`guaranteed`, `advisory`, `planned`, `rejected`).
    /// Absent: every claim.
    pub status: Option<String>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    /// Only the claims whose declared status the evidence does not support, with the
    /// findings. The tallies still count the whole matrix, so a filtered answer never
    /// misreports how much of it was examined.
    pub findings_only: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Judge at this revision, as committed, rather than at the working tree: `HEAD`, or
    /// any name of the checked-out commit. It must be the checked-out commit; the ledger is
    /// read as that commit holds it, and a run the working ledger holds that the commit's
    /// does not can only withhold `proven`. Absent: the working tree.
    pub presented: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// What the caller knows about the presented commit's tree (`clean`, `dirty`,
    /// `unknown`). It can only weaken the measured state, never assert a clean tree over a
    /// dirty checkout, and it means nothing without `presented`.
    pub presented_tree: Option<TreeState>,
}

impl BenchmarkCases for EvidenceReportInput {
    /// The whole matrix and the findings, at the working tree. No case fills `presented`:
    /// the benchmark repository is not a git repository, so every revision it could name is
    /// refused, and such a case would time the refusal and be counted as coverage of the
    /// judgement it never reached.
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        vec![
            NamedCase::new("all", EvidenceReportInput::default()),
            NamedCase::new(
                "findings",
                EvidenceReportInput {
                    findings_only: true,
                    ..Default::default()
                },
            ),
        ]
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
/// One claim of the matrix, named by the id it is declared under.
///
/// The id is required, and there is no spelling of this input that means "every claim" —
/// that question belongs to `evidence.report`. An id the matrix does not declare is a
/// not-found from the handler rather than an empty proof.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::EvidenceClaimInput;
///
/// let input: EvidenceClaimInput =
///     serde_json::from_str(r#"{"claim": "evidence-both-directions"}"#).unwrap();
/// assert_eq!(input.claim, "evidence-both-directions");
///
/// // no id is a usage error, never a request for all of them
/// assert!(serde_json::from_str::<EvidenceClaimInput>("{}").is_err());
/// ```
pub struct EvidenceClaimInput {
    /// The claim id, as `docs/CLAIMS.yaml` spells it.
    pub claim: String,
}

impl BenchmarkCases for EvidenceClaimInput {
    fn benchmark_cases(ctx: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        // a claim this repository actually has, so the case measures the join rather than
        // the refusal; a hard-coded id would be a second declaration of the matrix
        let claim = ctx
            .index
            .objects
            .iter()
            .find(|o| o.kind == "claim")
            .map(|o| o.identity.clone())
            .unwrap_or_else(|| "no-claim".to_string());
        vec![NamedCase::new("first-claim", EvidenceClaimInput { claim })]
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
/// One test, by its stable identity or by the path a claim names it with.
///
/// Both spellings reach the same test. `docs/CLAIMS.yaml` names a path, the ledger keys on
/// an identity, and a caller holding one of them should not have to know the other; the
/// handler resolves a path to the identity and reads the same derivation either way.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::EvidenceTestInput;
/// use majordomus_cli::evidence::{Runner, TestId};
///
/// let by_path: EvidenceTestInput =
///     serde_json::from_str(r#"{"test": "test/cases/84_distribution_model.sh"}"#).unwrap();
/// let id = TestId::of(&by_path.test).unwrap();
/// assert_eq!(id.as_string(), "suite:84_distribution_model");
/// assert_eq!(id.runner, Runner::Suite);
///
/// // an identity is not a path: `TestId::of` reads paths, and the handler parses the
/// // `<runner>:<name>` form itself
/// let by_id: EvidenceTestInput = serde_json::from_str(r#"{"test": "crate:why"}"#).unwrap();
/// assert!(TestId::of(&by_id.test).is_none());
/// ```
pub struct EvidenceTestInput {
    /// `suite:84_distribution_model`, `crate:why`, or the path itself
    /// (`test/cases/84_distribution_model.sh`), which is resolved to the same identity.
    pub test: String,
}

impl BenchmarkCases for EvidenceTestInput {
    fn benchmark_cases(ctx: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        let test = ctx
            .index
            .objects
            .iter()
            .filter(|o| o.kind == "claim")
            .find_map(|o| {
                o.metadata
                    .get("test")
                    .and_then(|v| v.as_str())
                    .and_then(evidence::TestId::of)
            })
            .map(|t| t.as_string())
            .unwrap_or_else(|| "suite:00_yaml_flatten".to_string());
        vec![NamedCase::new("first-test", EvidenceTestInput { test })]
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
/// A run to record into the ledger.
///
/// Paths to what the runners already wrote, not a run to perform: the recorder reads a
/// report, carries into each result what that run measured about its own checkout, and
/// merges it. The reports are optional and may be given together; an absent origin is
/// `local`, and an absent ledger is the tracked one.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::EvidenceRecordInput;
///
/// let input: EvidenceRecordInput =
///     serde_json::from_str(r#"{"suite": "tmp/report.tsv"}"#).unwrap();
/// assert_eq!(input.suite.as_deref(), Some("tmp/report.tsv"));
/// assert!(input.crate_output.is_none() && input.origin.is_none());
///
/// // what was not given is not written back as null: the shape a client reads is the
/// // shape it sent
/// assert_eq!(
///     serde_json::to_string(&input).unwrap(),
///     r#"{"suite":"tmp/report.tsv"}"#
/// );
/// ```
pub struct EvidenceRecordInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// The runner's TSV report: `MJ_TEST_REPORT=<file> bash test/run.sh`.
    pub suite: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// A file holding `cargo test`'s output, for the crate's own integration tests.
    pub crate_output: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Where the run happened: `local` (the default), `ci` or `release`.
    pub origin: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    /// A measurement per report: the file `majordomus evidence stamp` wrote at the end of
    /// that run, as `<file>` or `<producer>=<file>` (`suite`, `crate`, `coverage`). Without a
    /// producer word, the producer is the file's own, else the only report given.
    pub provenance: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// A coverage summary: what `scripts/rust-coverage --summary-json` wrote.
    pub coverage: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// The ledger to merge into: `repo` (the default, the tracked ledger) or `local` (the
    /// ignored one under `.ai/local/`, which moves no verdict).
    pub ledger: Option<LedgerTarget>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// Also write the run record to this file.
    pub run_record: Option<String>,
}

impl BenchmarkCases for EvidenceRecordInput {
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        // nothing: the capability is waived from the benchmark because it writes a tracked
        // file, and timing it in a loop would rewrite the repository's evidence
        Vec::new()
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
/// What a run asks to have measured about the checkout it leaves: its producer, its report,
/// and its own untracked outputs, which are not a change to what it tested.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::EvidenceStampInput;
/// use majordomus_cli::evidence::EvidenceProducer;
///
/// let input: EvidenceStampInput =
///     serde_json::from_str(r#"{"producer": "suite", "exclude": ["dist"]}"#).unwrap();
/// assert_eq!(input.producer, Some(EvidenceProducer::Suite));
/// assert_eq!(input.exclude, ["dist"]);
/// assert_eq!(serde_json::to_string(&input).unwrap(), r#"{"producer":"suite","exclude":["dist"]}"#);
/// ```
pub struct EvidenceStampInput {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// The producer whose run this is: `suite`, `crate` or `coverage`.
    pub producer: Option<EvidenceProducer>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    /// The report the run wrote; a local recording needs it named.
    pub report: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    /// The run's own untracked outputs, as repository paths: a file, or a directory with
    /// everything under it. A pattern, the whole checkout or a path holding tracked files is
    /// refused.
    pub exclude: Vec<String>,
}

impl BenchmarkCases for EvidenceStampInput {
    /// Nothing: the benchmark repository (`src/synthetic.rs`) is not a git work tree, so
    /// every case would time a refusal ("there is no commit to measure") rather than a
    /// measurement. The capability is waived as depending on an external `git`.
    fn benchmark_cases(_: &CaseContext<'_>) -> Vec<NamedCase<Self>> {
        Vec::new()
    }
}

// ---------------------------------------------------------------- outputs

#[derive(Debug, Clone, Serialize, JsonSchema)]
/// One claim with everything the repository can say about its proof, and the way back out
/// to the test that carries it.
///
/// The proof is flattened in, so a client reads one claim rather than an evidence wrapper
/// around one; the executions and the other claims the same test proves sit beside it.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::ClaimEvidence;
/// use majordomus_cli::evidence::ClaimProof;
///
/// let proof: ClaimProof = serde_json::from_value(serde_json::json!({
///     "id": "evidence-both-directions",
///     "claim": "a claim and its test answer for each other",
///     "status": "guaranteed",
///     "source": null,
///     "implementation": null,
///     "test_path": "test/cases/84_distribution_model.sh",
///     "test": "suite:84_distribution_model",
///     "state": "not_run",
///     "meaning": "no run of this test has been recorded",
///     "execution": null,
///     "changed": [],
///     "reproduce": "bash test/run.sh 84_distribution_model"
/// }))
/// .unwrap();
///
/// let answer = ClaimEvidence {
///     proof,
///     executions: Vec::new(),
///     also_proves: vec!["evidence-record-is-not-networked".to_string()],
/// };
/// let json = serde_json::to_value(&answer).unwrap();
/// assert_eq!(json["id"], "evidence-both-directions");
/// assert!(json.get("proof").is_none(), "the claim is flattened in, not nested");
/// assert_eq!(json["also_proves"], serde_json::json!(["evidence-record-is-not-networked"]));
/// // a list even where the ledger keeps one: retention is a decision that may change,
/// // and a client that read a bare object would break when it did
/// assert_eq!(json["executions"], serde_json::json!([]));
/// ```
pub struct ClaimEvidence {
    /// The claim, joined to its evidence.
    #[serde(flatten)]
    pub proof: ClaimProof,
    /// Every execution the ledger holds for this claim's test — today one, the latest, and
    /// a list because the ledger's retention is a decision that may change and a client
    /// that read a bare object would break when it did.
    pub executions: Vec<Execution>,
    /// The other claims the same test proves. A test shared by twelve claims is a test
    /// whose failure is twelve findings, and a reader of one of them should be able to see
    /// the other eleven without searching.
    pub also_proves: Vec<String>,
}

#[derive(Debug, Clone, Serialize, JsonSchema)]
/// One test, and what it proves.
///
/// The other direction of [`ClaimEvidence`], read from the test's end: its identity, its
/// source and whether that source is still the one that ran, the command that runs it
/// again, and every claim that names it.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::TestEvidence;
/// use majordomus_cli::evidence::TestId;
///
/// let id = TestId::of("apps/majordomus-cli/tests/why.rs").unwrap();
/// let answer = TestEvidence {
///     test: id.as_string(),
///     runner: id.runner,
///     source: id.source(),
///     present: true,
///     reproduce: id.reproduce(),
///     execution: None,
///     digest_matches: None,
///     proves: Vec::new(),
/// };
/// assert_eq!(answer.test, "crate:why");
/// assert_eq!(answer.reproduce, "cargo test --test why");
///
/// // nothing recorded: the two provenance keys are absent rather than null, so "no
/// // execution" cannot be read as an execution that said nothing
/// let json = serde_json::to_value(&answer).unwrap();
/// assert!(json.get("execution").is_none() && json.get("digest_matches").is_none());
/// assert_eq!(json["proves"], serde_json::json!([]));
/// ```
pub struct TestEvidence {
    /// The stable identity: `suite:<case>` or `crate:<binary>`.
    pub test: String,
    /// Which runner owns it.
    pub runner: evidence::Runner,
    /// Its own source, repository-relative.
    pub source: String,
    /// Whether that source is in this checkout.
    pub present: bool,
    /// The command that runs this one test.
    pub reproduce: String,
    /// The latest recorded execution, when there is one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub execution: Option<Execution>,
    /// Whether the test's source still hashes to what the execution recorded. `None` when
    /// there is no execution, or the source is not there to hash.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub digest_matches: Option<bool>,
    /// Every claim that names this test, with the state each is in.
    pub proves: Vec<ClaimProof>,
}

#[derive(Debug, Clone, Serialize, JsonSchema)]
/// What a recording did: how much of the run reached the ledger, and under what provenance.
///
/// The recorder decides nothing, and this report says so. A result no runner in this
/// repository owns is named in `unknown` rather than written under a guessed identity, and
/// a failure is recorded like a pass — the ledger holds what happened, so `passed` is a
/// count and never a filter.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::RecordReport;
///
/// let report = RecordReport {
///     recorded: 3,
///     passed: 2,
///     commit: "06fa258913a1b2c3d4e5f60718293a4b5c6d7e8f".to_string(),
///     working_tree: "clean".to_string(),
///     unknown: vec!["docs/CLAIMS.yaml".to_string()],
///     dropped: vec![],
///     ledger: majordomus_cli::evidence::LEDGER_PATH.to_string(),
///     run_record: serde_json::from_value(serde_json::json!({
///         "schema": 1, "id": "local:06fa258913a1:20260926T120000Z", "origin": "local",
///         "commit": "06fa258913a1b2c3d4e5f60718293a4b5c6d7e8f", "working_tree": "clean",
///         "recorded_at": "2026-09-26T12:00:00Z", "ledger": "repo"
///     }))
///     .unwrap(),
/// };
/// // the failing test is one of the three recorded, not a fourth thing that was dropped
/// assert_eq!(report.recorded - report.passed, 1);
/// assert!(report.ledger.starts_with(".ai/repo/"));
///
/// let json = serde_json::to_value(&report).unwrap();
/// assert_eq!(json["unknown"].as_array().unwrap().len(), 1);
/// assert_eq!(json["working_tree"], "clean");
/// // a suite-only recording listed nothing, and its document is what it always was
/// assert!(json.get("dropped").is_none());
/// ```
pub struct RecordReport {
    /// How many executions were written.
    pub recorded: usize,
    /// How many of them passed.
    pub passed: usize,
    /// The commit they were recorded against.
    pub commit: String,
    /// The tree's state at the time.
    pub working_tree: String,
    /// Results the run named that no runner in this repository owns.
    pub unknown: Vec<String>,
    /// What the reports held that no claim can name yet: the crate's unit-test binary, its
    /// doctests. Listed rather than ignored, and absent from the document when empty.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub dropped: Vec<EvidenceDropped>,
    /// Where the ledger was written: the path of the target the recording named.
    pub ledger: String,
    /// The recording as a typed run.
    pub run_record: EvidenceRunRecord,
}

// ---------------------------------------------------------------- handlers

fn root_of(ctx: &Context) -> std::path::PathBuf {
    std::path::PathBuf::from(&ctx.index.repository.root)
}

fn internal(e: crate::error::Error) -> CapabilityError {
    CapabilityError::Internal(e.to_string())
}

/// The whole joined report, read fresh: the ledger is a file that changes outside this
/// process, and an answer kept past a change of it would be the stale evidence this module
/// exists to name. The executor keeps the capability's answer per checkout state only
/// (`CachePolicy::Checkout`), which an edit of the ledger moves.
fn full_report(ctx: &Context) -> Result<EvidenceReport, CapabilityError> {
    let root = root_of(ctx);
    let ledger = Ledger::load(&root).map_err(internal)?;
    Ok(evidence::report(&ctx.index, &ledger))
}

/// The joined report at the checked-out commit, as committed: the ledger that commit holds,
/// and the runs the working ledger holds beside it, which can only withhold `proven`.
fn report_at_commit(
    ctx: &Context,
    rev: &str,
    given: Option<TreeState>,
) -> Result<EvidenceReport, CapabilityError> {
    let root = root_of(ctx);
    let presented =
        freshness::presented_commit(&root, rev, given).map_err(CapabilityError::InvalidInput)?;
    let commit = presented.commit().unwrap_or_default().to_string();
    let ledger = freshness::ledger_at(&root, &commit).map_err(internal)?;
    let held = freshness::uncommitted(&root, &ledger).map_err(internal)?;
    Ok(evidence::report_at(&ctx.index, &ledger, &presented, &held))
}

fn report(ctx: &Context, input: EvidenceReportInput) -> Result<EvidenceReport, CapabilityError> {
    let mut r = match (&input.presented, input.presented_tree) {
        (Some(rev), given) => report_at_commit(ctx, rev, given)?,
        (None, Some(_)) => {
            return Err(CapabilityError::InvalidInput(
                "`presented_tree` weakens the measured tree of a presented commit, and no \
                 commit was presented: name one with `presented`"
                    .to_string(),
            ))
        }
        (None, None) => full_report(ctx)?,
    };
    // the tallies are taken before the filter: a filtered answer says how much of the
    // matrix it looked at, never how much it returned
    if input.findings_only {
        let named: std::collections::BTreeSet<&str> =
            r.findings.iter().map(|f| f.claim.as_str()).collect();
        r.claims.retain(|c| named.contains(c.id.as_str()));
    }
    if let Some(state) = input.state {
        r.claims.retain(|c| c.state == state);
    }
    if let Some(status) = &input.status {
        r.claims.retain(|c| &c.status == status);
    }
    Ok(r)
}

fn claim(ctx: &Context, input: EvidenceClaimInput) -> Result<ClaimEvidence, CapabilityError> {
    let r = full_report(ctx)?;
    let Some(proof) = r.claims.iter().find(|c| c.id == input.claim).cloned() else {
        return Err(CapabilityError::NotFound(format!(
            "`{}` is not a claim of docs/CLAIMS.yaml",
            input.claim
        )));
    };
    let also_proves = proof
        .test
        .as_ref()
        .map(|t| {
            r.claims
                .iter()
                .filter(|c| c.test.as_ref() == Some(t) && c.id != proof.id)
                .map(|c| c.id.clone())
                .collect()
        })
        .unwrap_or_default();
    let executions = proof.execution.clone().into_iter().collect();
    Ok(ClaimEvidence {
        proof,
        executions,
        also_proves,
    })
}

fn test(ctx: &Context, input: EvidenceTestInput) -> Result<TestEvidence, CapabilityError> {
    // a path and an identity both name the same test; a client that has one should not
    // have to know the other's spelling
    let id = evidence::TestId::of(&input.test)
        .or_else(|| {
            let (prefix, name) = input.test.split_once(':')?;
            let runner = match prefix {
                "suite" => evidence::Runner::Suite,
                "crate" => evidence::Runner::Crate,
                _ => return None,
            };
            // the same rule the path form applies: one grammar, not two that disagree
            evidence::TestId::named(runner, name)
        })
        .ok_or_else(|| {
            CapabilityError::InvalidInput(format!(
                "`{}` names no test: give `suite:<case>`, `crate:<binary>`, or the path of a \
                 case under test/cases/ or an integration test under apps/majordomus-cli/tests/",
                input.test
            ))
        })?;

    let root = root_of(ctx);
    let r = full_report(ctx)?;
    let key = id.as_string();
    let proves: Vec<ClaimProof> = r
        .claims
        .iter()
        .filter(|c| c.test.as_deref() == Some(key.as_str()))
        .cloned()
        .collect();
    let ledger = Ledger::load(&root).map_err(internal)?;
    let execution = ledger.latest(&key).cloned();
    let digest_matches = execution.as_ref().and_then(|e| e.digest_matches(&root));
    Ok(TestEvidence {
        test: key,
        runner: id.runner,
        source: id.source(),
        present: root.join(id.source()).exists(),
        reproduce: id.reproduce(),
        execution,
        digest_matches,
        proves,
    })
}

fn record(ctx: &Context, input: EvidenceRecordInput) -> Result<RecordReport, CapabilityError> {
    let root = root_of(ctx);
    let origin = match input.origin.as_deref() {
        None => Origin::Local,
        Some(w) => Origin::parse(w).ok_or_else(|| {
            CapabilityError::InvalidInput(format!(
                "`{w}` is not an origin: it is `local`, `ci` or `release`"
            ))
        })?,
    };
    // A CI run names itself from its environment; a local run has no run to name, and a
    // local recording inside a CI job's shell is still not that job's evidence.
    let run = match origin {
        Origin::Ci => evidence::RunRef::from_env(|k| std::env::var(k).ok()),
        Origin::Local | Origin::Release => None,
    };
    let ledger = input.ledger.unwrap_or_default();
    let given: Vec<EvidenceProducer> = [
        (EvidenceProducer::Suite, input.suite.is_some()),
        (EvidenceProducer::Crate, input.crate_output.is_some()),
        (EvidenceProducer::Coverage, input.coverage.is_some()),
    ]
    .into_iter()
    .filter_map(|(p, is)| is.then_some(p))
    .collect();
    let provenance =
        EvidenceProvenance::resolve(&input.provenance, &given).map_err(CapabilityError::Refused)?;
    let req = RecordRequest {
        suite: input.suite.map(std::path::PathBuf::from),
        crate_output: input.crate_output.map(std::path::PathBuf::from),
        run,
        provenance,
        coverage: input.coverage.map(std::path::PathBuf::from),
        ledger,
        run_record: input.run_record.map(std::path::PathBuf::from),
        ..RecordRequest::new(origin)
    };
    let got = evidence::record(&root, &req).map_err(refused_or_internal)?;
    Ok(RecordReport {
        recorded: got.recorded,
        passed: got.passed,
        commit: got.commit,
        working_tree: got.working_tree,
        unknown: got.unknown,
        dropped: got.dropped,
        ledger: ledger.path().to_string(),
        run_record: got.run_record,
    })
}

/// A refusal of the evidence surface is the caller's to fix; anything else is this
/// executable's.
fn refused_or_internal(e: crate::error::Error) -> CapabilityError {
    match e {
        crate::error::Error::InvalidSurface { reason, .. } => CapabilityError::Refused(reason),
        other => internal(other),
    }
}

fn stamp(ctx: &Context, input: EvidenceStampInput) -> Result<EvidenceProvenance, CapabilityError> {
    let req = StampRequest {
        producer: input.producer,
        report: input.report.map(std::path::PathBuf::from),
        exclude: input.exclude,
        run: evidence::RunRef::from_env(|k| std::env::var(k).ok()),
    };
    evidence::stamp(&root_of(ctx), &req).map_err(refused_or_internal)
}

// ---------------------------------------------------------------- the module

/// The `evidence` module: claims joined to the runs recorded against them.
///
/// The declaration is the whole of what the capabilities are — every projection, from
/// the HTTP route to the MCP tool to the word a person types, is read out of what it
/// returns. Nothing here caches: the ledger is a file that changes outside this process,
/// and a cached answer would be exactly the stale evidence the module exists to name.
///
/// ```
/// use majordomus_cli::capability::builtin::evidence::module;
/// use majordomus_cli::capability::CachePolicy;
///
/// let m = module();
/// let report = m
///     .capabilities
///     .iter()
///     .find(|e| e.capability.id.as_str() == "evidence.report")
///     .unwrap();
/// assert_eq!(report.capability.exposure.http.as_ref().unwrap().path, "/api/v1/evidence");
/// assert_eq!(
///     report.capability.exposure.mcp.as_ref().unwrap().tool.as_deref(),
///     Some("majordomus_evidence")
/// );
///
/// // `evidence.test` is spelled `majordomus evidence proves`: `test` is a word the fish
/// // completion adapter refuses, and the identity is not the command
/// let test = m
///     .capabilities
///     .iter()
///     .find(|e| e.capability.id.as_str() == "evidence.test")
///     .unwrap();
/// assert_eq!(test.capability.exposure.cli.as_ref().unwrap().path[1], "proves");
///
/// // the ledger changes outside this process: kept, if at all, per checkout state only
/// assert!(m.capabilities.iter().all(|e| matches!(
///     e.capability.cache,
///     CachePolicy::Disabled | CachePolicy::Checkout { .. }
/// )));
/// ```
pub fn module() -> ModuleDescriptor {
    module! {
        id: "evidence",
        title: "Evidence",
        description: "What actually ran, against which commit, and whether it still proves anything. The claims matrix binds a claim to a test by path; the ledger under .ai/repo/evidence records the latest execution of every test with the commit, the tree state, the digest of the test's own source, the time, the origin and the command that runs it again. Joining the two answers, per claim, whether the repository can honestly call it proven — and distinguishes a run recorded against this very commit from one whose inputs merely have not changed since, because collapsing those two is how a green badge stops meaning anything.",
        stability: Stability::BehaviorallyVerified,
        capabilities: [
            capability! {
                id: "evidence.report",
                title: "Every claim against the evidence recorded for it",
                description: "The whole claims matrix joined to the ledger and judged at the presented revision: the working tree by default, or the checked-out commit as committed, read from the ledger that commit holds. Per claim: the proof state, the sentence explaining how that state was derived, why when the state alone does not say, the execution behind it, the files that changed since it, and the command that produces it again. A run on a commit the presented revision does not contain is stale, a test that declined to run is not run, and a run the working ledger holds that the presented commit's does not can only withhold proven. The tallies count the whole matrix even when the answer is filtered, and the findings name every claim that declares a guarantee the evidence does not support. Kept per checkout state, never longer: the ledger is a file that changes outside this process, and an edit of it, of a test or of any tracked file, a new untracked file, a commit or a new ref is a new answer.",
                input: EvidenceReportInput,
                output: EvidenceReport,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: Some(crate::capability::model::McpExposure {
                        tool: Some("majordomus_evidence".into()),
                        resource: Some(McpResource { uri: EVIDENCE_URI.into(), name: "evidence".into() }),
                    }),
                    http: get("/api/v1/evidence"),
                    cli: Some(CliExposure { path: vec!["evidence".into(), "show".into()] }),
                },
                tags: ["evidence", "claims", "tests", "verification", "provenance"],
                cache: CachePolicy::Checkout { max_entries: 8 },
                handler: report,
            },
            capability! {
                id: "evidence.claim",
                title: "What proves this claim",
                description: "One claim with its proof state, the execution behind it — outcome, duration, commit, tree state, digest, time and origin — the command that reproduces it, and the other claims the same test proves. A claim the matrix does not declare is a not-found rather than an empty answer, because a typo that read as 'this claim has no evidence' is the one answer this capability must never give.",
                input: EvidenceClaimInput,
                output: ClaimEvidence,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: mcp("majordomus_evidence_claim"),
                    http: get("/api/v1/evidence/claim"),
                    cli: Some(CliExposure { path: vec!["evidence".into(), "claim".into()] }),
                },
                tags: ["evidence", "claims", "verification", "provenance"],
                cache: CachePolicy::Checkout { max_entries: 32 },
                handler: claim,
            },
            capability! {
                id: "evidence.test",
                title: "What this test proves",
                description: "One test — by identity or by the path a claim names it with — with its latest execution, whether its source still hashes to what that execution recorded, the command that runs it again, and every claim that names it. This is the reverse of evidence.claim and reads the same derivation, so the two directions cannot disagree.",
                input: EvidenceTestInput,
                output: TestEvidence,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: mcp("majordomus_evidence_test"),
                    http: get("/api/v1/evidence/test"),
                    cli: Some(CliExposure { path: vec!["evidence".into(), "proves".into()] }),
                },
                tags: ["evidence", "tests", "verification", "provenance"],
                cache: CachePolicy::Disabled,
                handler: test,
            },
            capability! {
                id: "evidence.record",
                kind: CapabilityKind::Command,
                title: "Record a run that happened",
                description: "Reads what the runs already wrote — the suite's TSV report, cargo test's output, a coverage summary — carries into each result what that run measured about its own checkout (the commit and the tree, from the measurement `evidence stamp` wrote), with the digest of the test's own source, the time and the origin, and merges it into the ledger. It records; it decides nothing: a case that failed is a case the runner said failed, and a test no report named is left exactly as it was, so recording one case never erases the evidence for the rest. It refuses a tree with no commit, a measurement of another commit or of another report, a local measurement that names no report, and a CI report without a measurement; a local report recorded without one carries the tree unknown, which never reads proven. Every recording returns a run record (its commit, the tree each report's run measured, its totals and what was absent, dropped or unknown, and a coverage summary bound to its commit), and --ledger local writes only the ignored local ledger. A crate binary that ran no test, or only a filtered subset, is recorded as a skip, and what no claim can name yet (the crate's own unit tests, its doctests) is listed as dropped.",
                input: EvidenceRecordInput,
                output: RecordReport,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: None,
                    http: None,
                    cli: Some(CliExposure { path: vec!["evidence".into(), "record".into()] }),
                },
                tags: ["evidence", "tests", "provenance"],
                cache: CachePolicy::Disabled,
                benchmark: BenchmarkPolicy::Waived { reason: WaiverReason::Destructive },
                handler: record,
            },
            capability! {
                id: "evidence.stamp",
                title: "Measure the tree a run left behind",
                description: "The one measurement a runner takes at the end of its run, for evidence record --provenance: the commit; the tree, ignoring the evidence ledger and the run's own untracked outputs, never a tracked change; the producer; its toolchain; the recorder's version; the report's digest; the host; the CI run. It writes nothing. It is offered only on the command line because it reads a path its caller names.",
                input: EvidenceStampInput,
                output: EvidenceProvenance,
                stability: Stability::BehaviorallyVerified,
                exposure: Exposure {
                    mcp: None,
                    http: None,
                    cli: Some(CliExposure { path: vec!["evidence".into(), "stamp".into()] }),
                },
                tags: ["evidence", "tests", "provenance"],
                cache: CachePolicy::Disabled,
                benchmark: BenchmarkPolicy::Waived { reason: WaiverReason::ExternalDependency },
                handler: stamp,
            },
        ],
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// One capability's declared projections: its id, the MCP tool it answers as, the HTTP
    /// path it is served at, and the words of its command line. Named because the tuple is
    /// read four times below and an anonymous one of this width is a type nobody can talk
    /// about.
    type Projection<'a> = (&'a str, Option<&'a str>, Option<&'a str>, &'a [&'a str]);

    /// The declaration is the only place these names exist; every projection derives from
    /// it. This is the assertion a refactor that dropped an exposure would fail.
    #[test]
    fn the_declaration_yields_the_projections_it_claims() {
        let m = module();
        assert_eq!(m.id.as_str(), "evidence");
        let expected: &[Projection<'_>] = &[
            (
                "evidence.report",
                Some("majordomus_evidence"),
                Some("/api/v1/evidence"),
                &["evidence", "show"],
            ),
            (
                "evidence.claim",
                Some("majordomus_evidence_claim"),
                Some("/api/v1/evidence/claim"),
                &["evidence", "claim"],
            ),
            (
                "evidence.test",
                Some("majordomus_evidence_test"),
                Some("/api/v1/evidence/test"),
                &["evidence", "proves"],
            ),
            ("evidence.record", None, None, &["evidence", "record"]),
            ("evidence.stamp", None, None, &["evidence", "stamp"]),
        ];
        let ids: Vec<&str> = m
            .capabilities
            .iter()
            .map(|e| e.capability.id.as_str())
            .collect();
        let want: Vec<&str> = expected.iter().map(|(id, _, _, _)| *id).collect();
        assert_eq!(ids, want);
        for (e, (id, tool, path, cli)) in m.capabilities.iter().zip(expected) {
            let x = &e.capability.exposure;
            assert_eq!(
                x.mcp.as_ref().and_then(|m| m.tool.as_deref()),
                *tool,
                "{id}"
            );
            assert_eq!(x.http.as_ref().map(|h| h.path.as_str()), *path, "{id}");
            assert_eq!(
                x.cli.as_ref().map(|c| c.path.clone()),
                Some(cli.iter().map(|s| s.to_string()).collect::<Vec<_>>()),
                "{id} lost or renamed its command line"
            );
            // the ledger changes outside this process, so an answer is kept, if at all, only
            // per checkout state, which an edit of the ledger moves
            assert!(
                matches!(
                    e.capability.cache,
                    CachePolicy::Disabled | CachePolicy::Checkout { .. }
                ),
                "{id} may cache only per checkout state: the ledger changes outside this process"
            );
        }
    }

    /// The recorder writes a tracked file. It must be a command, and it must be offered to
    /// whoever runs the executable and to nobody over a network — this server is read-only,
    /// and a write reachable over MCP or HTTP would end that.
    #[test]
    fn only_the_recorder_writes_and_it_is_not_reachable_over_the_network() {
        for e in module().capabilities {
            let id = e.capability.id.as_str().to_string();
            let x = &e.capability.exposure;
            if id == "evidence.record" {
                assert!(
                    !e.capability.kind.is_read_only(),
                    "{id} is declared a query"
                );
                assert!(x.mcp.is_none(), "{id} is reachable over MCP");
                assert!(x.http.is_none(), "{id} is reachable over HTTP");
                assert_eq!(
                    e.capability.visibility,
                    crate::capability::Visibility::Developer,
                    "{id} must be a developer capability"
                );
                assert!(
                    matches!(e.capability.benchmark, BenchmarkPolicy::Waived { .. }),
                    "{id} must not be timed in a loop: it writes a tracked file"
                );
            } else if id == "evidence.stamp" {
                // a read, but of a path its caller names: a network client must not choose a
                // file this executable reads, so it is offered only on the command line; and
                // it is waived, because the benchmark repository is not a git work tree
                assert!(e.capability.kind.is_read_only(), "{id} writes");
                assert!(x.mcp.is_none(), "{id} is reachable over MCP");
                assert!(x.http.is_none(), "{id} is reachable over HTTP");
                assert_eq!(
                    e.capability.visibility,
                    crate::capability::Visibility::Developer,
                    "{id} must be a developer capability"
                );
                assert!(
                    matches!(
                        e.capability.benchmark,
                        BenchmarkPolicy::Waived {
                            reason: WaiverReason::ExternalDependency
                        }
                    ),
                    "{id} is waived for its external git"
                );
            } else {
                assert!(e.capability.kind.is_read_only(), "{id} writes");
                assert!(
                    x.mcp.is_some() && x.http.is_some(),
                    "{id} lost a projection"
                );
            }
        }
    }

    /// Every read capability carries a command line, and every command line it carries is
    /// under one word. A capability that claimed a path `cli.rs` does not declare would
    /// fail the projection closure; this is the half that says the module meant to have one.
    #[test]
    fn every_capability_is_reachable_from_the_command_line() {
        for e in module().capabilities {
            let cli = e
                .capability
                .exposure
                .cli
                .as_ref()
                .unwrap_or_else(|| panic!("{} has no command line", e.capability.id));
            assert_eq!(
                cli.path.first().map(String::as_str),
                Some("evidence"),
                "{} is not under `majordomus evidence`",
                e.capability.id
            );
            assert_eq!(cli.path.len(), 2, "{}", e.capability.id);
        }
    }

    /// A tree state means something only about a presented commit, and a revision the
    /// repository cannot name is refused with its name rather than judged at something else.
    #[test]
    fn a_presented_revision_is_checked_before_anything_is_judged() {
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let ctx = repo.context().unwrap();
        match ctx.execute(
            "evidence.report",
            serde_json::json!({ "presented_tree": "dirty" }),
        ) {
            Err(CapabilityError::InvalidInput(m)) => {
                assert!(m.contains("presented"), "{m}")
            }
            other => panic!("a tree state with no commit was accepted: {other:?}"),
        }
        // the benchmark repository is not a git repository, so no revision resolves there
        match ctx.execute(
            "evidence.report",
            serde_json::json!({ "presented": "HEAD", "presented_tree": "clean" }),
        ) {
            Err(CapabilityError::InvalidInput(m)) => assert!(m.contains("HEAD"), "{m}"),
            other => panic!("a revision that names nothing was judged: {other:?}"),
        }
        // and the working tree is still the default
        let v = ctx
            .execute("evidence.report", serde_json::json!({}))
            .unwrap();
        assert_eq!(v["presented"]["revision"], "working_tree");
    }

    /// What a crate run held that no claim can name yet reaches the recording's answer, in
    /// the order the output held it, and a recording with nothing dropped carries no
    /// `dropped` at all, so a suite-only recording answers as it did before the list existed.
    #[test]
    fn the_recording_answers_with_what_it_dropped() {
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .arg("-C")
                .arg(repo.root())
                .args(args)
                .output()
                .unwrap();
            assert!(out.status.success(), "git {args:?}");
        };
        git(&["init", "-q"]);
        git(&["config", "user.email", "t@example.com"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-q", "-m", "fixture"]);
        let ctx = repo.context().unwrap();

        let reports = tempfile::tempdir().unwrap();
        let log = reports.path().join("crate.log");
        std::fs::write(
            &log,
            "     Running unittests src/lib.rs (target/debug/deps/majordomus_cli-1)\n\
             test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out\n\
                Doc-tests majordomus_cli\n\
             test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out\n",
        )
        .unwrap();
        let v = ctx
            .execute(
                "evidence.record",
                serde_json::json!({ "crate_output": log.to_string_lossy() }),
            )
            .unwrap();
        assert_eq!(v["recorded"], 0, "{v}");
        let dropped: Vec<(&str, &str)> = v["dropped"]
            .as_array()
            .unwrap_or_else(|| panic!("no dropped list: {v}"))
            .iter()
            .map(|d| {
                (
                    d["producer"].as_str().unwrap_or("?"),
                    d["what"].as_str().unwrap_or("?"),
                )
            })
            .collect();
        assert_eq!(
            dropped,
            [
                ("crate", "unittests src/lib.rs"),
                ("crate", "doc-tests majordomus_cli")
            ]
        );

        let tsv = reports.path().join("run.tsv");
        std::fs::write(&tsv, "99_ghost\tok\t1\tparallel\n").unwrap();
        let v = ctx
            .execute(
                "evidence.record",
                serde_json::json!({ "suite": tsv.to_string_lossy() }),
            )
            .unwrap();
        assert!(v.get("dropped").is_none(), "{v}");
    }

    /// Each ledger a report reads — the one a presented commit holds, the working copy
    /// beside it, and the working tree's own — is refused when it cannot be read, rather
    /// than read as a ledger that recorded nothing.
    #[test]
    fn an_unreadable_ledger_is_refused_at_every_revision() {
        use crate::evidence::LEDGER_PATH;
        let repo = crate::synthetic::SyntheticRepository::small().unwrap();
        let git = |args: &[&str]| {
            let out = std::process::Command::new("git")
                .arg("-C")
                .arg(repo.root())
                .args(args)
                .output()
                .unwrap();
            String::from_utf8_lossy(&out.stdout).trim().to_string()
        };
        git(&["init", "-q"]);
        git(&["config", "user.email", "t@example.com"]);
        git(&["config", "user.name", "t"]);
        git(&["add", "-A"]);
        git(&["commit", "-q", "-m", "fixture"]);
        let ctx = repo.context().unwrap();
        let at_head = serde_json::json!({ "presented": "HEAD" });

        let v = ctx.execute("evidence.report", at_head.clone()).unwrap();
        assert_eq!(v["presented"]["revision"], git(&["rev-parse", "HEAD"]));
        assert_eq!(v["presented"]["tree"], "clean");

        let refused = |input: serde_json::Value| match ctx.execute("evidence.report", input) {
            Err(CapabilityError::Internal(m)) => m,
            other => panic!("an unreadable ledger was judged past: {other:?}"),
        };
        // the working copy cannot be read: a run it may hold cannot be ruled out
        std::fs::create_dir_all(repo.root().join(".ai/repo/evidence")).unwrap();
        std::fs::write(repo.root().join(LEDGER_PATH), "not a ledger").unwrap();
        assert!(refused(at_head.clone()).contains("cannot be ruled out"));
        assert!(refused(serde_json::json!({})).contains(LEDGER_PATH));
        // and the ledger the commit holds cannot be read either
        git(&["add", "-A"]);
        git(&["commit", "-q", "-m", "an unreadable ledger"]);
        assert!(refused(at_head).contains(LEDGER_PATH));
    }
}