evidence.stamp

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.

query
behaviorally_verified
module evidence
#evidence
#tests
#provenance

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	—
HTTP	—
command line	majordomus evidence stamp

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · EvidenceStampInput

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"]}"#);

property	type	required	description
exclude	array	no	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.
producer	one of 2	no	The producer whose run this is: `suite`, `crate` or `coverage`.
report	string \| null	no	The report the run wrote; a local recording needs it named.

JSON Schema

{
  "$defs": {
    "EvidenceProducer": {
      "description": "Which report an entry of a run belongs to: the suite's TSV, `cargo test`'s output, or a\ncoverage summary.\n\nThe serde word is the word a person types and a document carries (`suite`, `crate`,\n`coverage`), and `EvidenceProducer::parse` reads exactly those three back. A word that\nnames no report is not a producer, so a misspelled one is refused where it is read\nrather than guessed at.\n\n```\nuse majordomus_cli::evidence::EvidenceProducer;\n\nassert_eq!(EvidenceProducer::parse(\"crate\"), Some(EvidenceProducer::Crate));\nassert_eq!(EvidenceProducer::Coverage.as_str(), \"coverage\");\nassert_eq!(serde_json::to_value(EvidenceProducer::Suite).unwrap(), \"suite\");\nassert_eq!(EvidenceProducer::parse(\"Suite\"), None, \"the word is exact\");\n```",
      "oneOf": [
        {
          "const": "suite",
          "description": "The suite runner's TSV report (`MJ_TEST_REPORT` of `test/run.sh`).",
          "type": "string"
        },
        {
          "const": "crate",
          "description": "`cargo test`'s output: one result line per test binary.",
          "type": "string"
        },
        {
          "const": "coverage",
          "description": "A coverage summary (`scripts/rust-coverage --summary-json`).",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "What a run asks to have measured about the checkout it leaves: its producer, its report,\nand its own untracked outputs, which are not a change to what it tested.\n\n```\nuse majordomus_cli::capability::builtin::evidence::EvidenceStampInput;\nuse majordomus_cli::evidence::EvidenceProducer;\n\nlet input: EvidenceStampInput =\n    serde_json::from_str(r#\"{\"producer\": \"suite\", \"exclude\": [\"dist\"]}\"#).unwrap();\nassert_eq!(input.producer, Some(EvidenceProducer::Suite));\nassert_eq!(input.exclude, [\"dist\"]);\nassert_eq!(serde_json::to_string(&input).unwrap(), r#\"{\"producer\":\"suite\",\"exclude\":[\"dist\"]}\"#);\n```",
  "properties": {
    "exclude": {
      "description": "The run's own untracked outputs, as repository paths: a file, or a directory with\neverything under it. A pattern, the whole checkout or a path holding tracked files is\nrefused.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "producer": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceProducer"
        },
        {
          "type": "null"
        }
      ],
      "description": "The producer whose run this is: `suite`, `crate` or `coverage`."
    },
    "report": {
      "description": "The report the run wrote; a local recording needs it named.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "EvidenceStampInput",
  "type": "object"
}

output · EvidenceProvenance

What a run measured about its own checkout when it ended.

Only commit and working_tree are required: a producing job's tree file ({"commit","working_tree","excluded"}) is a valid, minimal measurement. It names no report, so it is accepted only for a CI recording.

use majordomus_cli::evidence::{EvidenceProvenance, TreeState};
let head = "0123456789abcdef0123456789abcdef01234567";
let p: EvidenceProvenance = serde_json::from_value(serde_json::json!({
    "commit": head, "working_tree": "clean", "excluded": ["suite.tsv"]
})).unwrap();
assert_eq!(p.working_tree, TreeState::Clean);
assert!(p.report.is_none());

property	type	required	description
commit	string	yes	The full commit the checkout was at.
excluded	array	no	The run's own untracked outputs that were excluded, the report among them when it is inside the checkout. The ledger is always ignored and not listed. default []
host	one of 2	no	The machine.
measured_at	string \| null	no	When it was measured, RFC 3339 UTC.
producer	one of 2	no	Which report this measures, when named.
recorder	string \| null	no	The version of the executable that measured.
report	one of 2	no	The report measured.
run	one of 2	no	The CI run, when there was one.
toolchain	one of 2	no	The producer's toolchain.
working_tree	reference	yes	The tree, the evidence ledger ignored and the run's own untracked outputs excluded.

JSON Schema

{
  "$defs": {
    "EvidenceHost": {
      "additionalProperties": false,
      "description": "The machine the run measured on.\n\n```\nuse majordomus_cli::evidence::EvidenceHost;\nlet h = EvidenceHost { os: std::env::consts::OS.into(), arch: std::env::consts::ARCH.into() };\nassert!(!h.os.is_empty());\n```",
      "properties": {
        "arch": {
          "description": "`std::env::consts::ARCH`.",
          "type": "string"
        },
        "os": {
          "description": "`std::env::consts::OS`.",
          "type": "string"
        }
      },
      "required": [
        "os",
        "arch"
      ],
      "type": "object"
    },
    "EvidenceProducer": {
      "description": "Which report an entry of a run belongs to: the suite's TSV, `cargo test`'s output, or a\ncoverage summary.\n\nThe serde word is the word a person types and a document carries (`suite`, `crate`,\n`coverage`), and `EvidenceProducer::parse` reads exactly those three back. A word that\nnames no report is not a producer, so a misspelled one is refused where it is read\nrather than guessed at.\n\n```\nuse majordomus_cli::evidence::EvidenceProducer;\n\nassert_eq!(EvidenceProducer::parse(\"crate\"), Some(EvidenceProducer::Crate));\nassert_eq!(EvidenceProducer::Coverage.as_str(), \"coverage\");\nassert_eq!(serde_json::to_value(EvidenceProducer::Suite).unwrap(), \"suite\");\nassert_eq!(EvidenceProducer::parse(\"Suite\"), None, \"the word is exact\");\n```",
      "oneOf": [
        {
          "const": "suite",
          "description": "The suite runner's TSV report (`MJ_TEST_REPORT` of `test/run.sh`).",
          "type": "string"
        },
        {
          "const": "crate",
          "description": "`cargo test`'s output: one result line per test binary.",
          "type": "string"
        },
        {
          "const": "coverage",
          "description": "A coverage summary (`scripts/rust-coverage --summary-json`).",
          "type": "string"
        }
      ]
    },
    "EvidenceReportArtifact": {
      "additionalProperties": false,
      "description": "The report a measurement belongs to: where it was and what its bytes were.\n\n```\nuse majordomus_cli::evidence::EvidenceReportArtifact;\nlet r: EvidenceReportArtifact =\n    serde_json::from_str(r#\"{\"path\":\"suite.tsv\",\"digest\":\"sha256:00\",\"bytes\":3}\"#).unwrap();\nassert_eq!(r.bytes, 3);\n```",
      "properties": {
        "bytes": {
          "description": "How many bytes it held.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "digest": {
          "description": "`sha256:<hex>` of the report's bytes.",
          "type": "string"
        },
        "path": {
          "description": "Repository-relative when the report is inside the checkout, else its file name alone.\nNever a machine path.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "digest",
        "bytes"
      ],
      "type": "object"
    },
    "EvidenceRun": {
      "description": "The continuous-integration run an execution was recorded in: enough to navigate back to\nthe run that produced it.\n\n`Origin` says what kind of run it was and deliberately names no provider. This names the\none run, in the words the provider addressed it with when it happened — its identifier,\nits attempt, the workflow and job, and the address a reader follows — because a link built\nlater from a template would point wherever the template's idea of the provider had drifted\nto. Only an adapter constructs it; nothing in the model reads the provider's name.\n\n```\nuse majordomus_cli::evidence::RunRef;\n\nlet actions = |k: &str| {\n    let v = match k {\n        \"GITHUB_ACTIONS\" => \"true\",\n        \"GITHUB_SERVER_URL\" => \"https://github.com\",\n        \"GITHUB_REPOSITORY\" => \"owner/repo\",\n        \"GITHUB_RUN_ID\" => \"42\",\n        \"GITHUB_RUN_ATTEMPT\" => \"2\",\n        \"GITHUB_WORKFLOW\" => \"validate\",\n        \"GITHUB_JOB\" => \"evidence\",\n        _ => return None,\n    };\n    Some(v.to_string())\n};\nlet run = RunRef::from_env(actions).unwrap();\nassert_eq!(run.id, \"42\");\nassert_eq!(run.attempt, 2);\nassert_eq!(run.url, \"https://github.com/owner/repo/actions/runs/42/attempts/2\");\n// a run that names neither its pull request's head nor its event still names itself\nassert_eq!((run.head_sha, run.event), (None, None));\n\nlet head = \"0123456789abcdef0123456789abcdef01234567\";\nlet pull = |k: &str| match k {\n    \"MJ_RUN_HEAD_SHA\" => Some(head.to_string()),\n    \"GITHUB_EVENT_NAME\" => Some(\"pull_request\".to_string()),\n    _ => actions(k),\n};\nlet run = RunRef::from_env(pull).unwrap();\nassert_eq!(run.head_sha.as_deref(), Some(head));\nassert_eq!(run.event.as_deref(), Some(\"pull_request\"));\n\n// outside a run there is nothing to name, and a half-described run is not a run\nassert!(RunRef::from_env(|_| None).is_none());\nassert!(RunRef::from_env(|k| (k == \"GITHUB_ACTIONS\").then(|| \"true\".to_string())).is_none());\n```",
      "properties": {
        "attempt": {
          "description": "Which attempt of the run, counted from 1.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "event": {
          "description": "The event that started the run: `push`, `pull_request`, `schedule`,\n`workflow_dispatch`.",
          "type": [
            "string",
            "null"
          ]
        },
        "head_sha": {
          "description": "The pull request's head commit when the run was a pull-request run (its `commit` is\nGitHub's merge commit, the tree that ran). Carried beside the commit, never\nsubstituted for it.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The provider's identifier of the run.",
          "type": "string"
        },
        "job": {
          "description": "The job within the run that recorded the execution.",
          "type": "string"
        },
        "provider": {
          "description": "The provider that ran it, as the adapter that recorded it names it.",
          "type": "string"
        },
        "url": {
          "description": "Where a reader finds the run, as the provider addressed it at the time.",
          "type": "string"
        },
        "workflow": {
          "description": "The workflow the run belongs to.",
          "type": "string"
        }
      },
      "required": [
        "provider",
        "id",
        "attempt",
        "workflow",
        "job",
        "url"
      ],
      "type": "object"
    },
    "EvidenceToolchain": {
      "additionalProperties": false,
      "description": "The toolchain the run's producer used.\n\n```\nuse majordomus_cli::evidence::EvidenceToolchain;\nlet t: EvidenceToolchain =\n    serde_json::from_str(r#\"{\"name\":\"rustc\",\"version\":\"1.2.3\",\"source\":\"pinned\"}\"#).unwrap();\nassert_eq!(t.version, \"1.2.3\");\n```",
      "properties": {
        "name": {
          "description": "The executable: `rustc`, `bash`.",
          "type": "string"
        },
        "source": {
          "$ref": "#/$defs/EvidenceToolchainSource",
          "description": "How the version was known."
        },
        "version": {
          "description": "Its version.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "version",
        "source"
      ],
      "type": "object"
    },
    "EvidenceToolchainSource": {
      "description": "How a toolchain's version was known: asked of the executable, or read from the pin the\nrepository declares.\n\n```\nuse majordomus_cli::evidence::EvidenceToolchainSource;\nassert_eq!(serde_json::to_value(EvidenceToolchainSource::Pinned).unwrap(), \"pinned\");\n```",
      "oneOf": [
        {
          "const": "measured",
          "description": "The executable answered `--version`.",
          "type": "string"
        },
        {
          "const": "pinned",
          "description": "The repository pins it (`rust-toolchain.toml`), and the pin is what ran.",
          "type": "string"
        }
      ]
    },
    "EvidenceTreeState": {
      "description": "Whether a tree was the commit it sits on: the three words the ledger and git already\nuse, typed.\n\n`unknown` is not a softer `clean`. It is what is recorded when git could not be asked,\nand not knowing is not proof, so every rule here treats it as not clean.\n\n```\nuse majordomus_cli::evidence::freshness::TreeState;\n\nassert_eq!(TreeState::parse(\"clean\"), TreeState::Clean);\nassert_eq!(TreeState::parse(\"dirty\"), TreeState::Dirty);\n// a word nobody wrote down is not a clean tree\nassert_eq!(TreeState::parse(\"spotless\"), TreeState::Unknown);\nassert_eq!(TreeState::Dirty.as_str(), \"dirty\");\nassert_eq!(serde_json::to_value(TreeState::Unknown).unwrap(), \"unknown\");\n```",
      "oneOf": [
        {
          "const": "clean",
          "description": "The tree was the commit: nothing but the evidence ledger differed from it.",
          "type": "string"
        },
        {
          "const": "dirty",
          "description": "Something other than the evidence ledger differed from the commit.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Git could not be asked, or the word recorded is none of the three.",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "What a run measured about its own checkout when it ended.\n\nOnly `commit` and `working_tree` are required: a producing job's tree file\n(`{\"commit\",\"working_tree\",\"excluded\"}`) is a valid, minimal measurement. It names no\nreport, so it is accepted only for a CI recording.\n\n```\nuse majordomus_cli::evidence::{EvidenceProvenance, TreeState};\nlet head = \"0123456789abcdef0123456789abcdef01234567\";\nlet p: EvidenceProvenance = serde_json::from_value(serde_json::json!({\n    \"commit\": head, \"working_tree\": \"clean\", \"excluded\": [\"suite.tsv\"]\n})).unwrap();\nassert_eq!(p.working_tree, TreeState::Clean);\nassert!(p.report.is_none());\n```",
  "properties": {
    "commit": {
      "description": "The full commit the checkout was at.",
      "type": "string"
    },
    "excluded": {
      "default": [],
      "description": "The run's own untracked outputs that were excluded, the report among them when it is\ninside the checkout. The ledger is always ignored and not listed.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "host": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceHost"
        },
        {
          "type": "null"
        }
      ],
      "description": "The machine."
    },
    "measured_at": {
      "description": "When it was measured, RFC 3339 UTC.",
      "type": [
        "string",
        "null"
      ]
    },
    "producer": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceProducer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which report this measures, when named."
    },
    "recorder": {
      "description": "The version of the executable that measured.",
      "type": [
        "string",
        "null"
      ]
    },
    "report": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceReportArtifact"
        },
        {
          "type": "null"
        }
      ],
      "description": "The report measured."
    },
    "run": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceRun"
        },
        {
          "type": "null"
        }
      ],
      "description": "The CI run, when there was one."
    },
    "toolchain": {
      "anyOf": [
        {
          "$ref": "#/$defs/EvidenceToolchain"
        },
        {
          "type": "null"
        }
      ],
      "description": "The producer's toolchain."
    },
    "working_tree": {
      "$ref": "#/$defs/EvidenceTreeState",
      "description": "The tree, the evidence ledger ignored and the run's own untracked outputs excluded."
    }
  },
  "required": [
    "commit",
    "working_tree"
  ],
  "title": "EvidenceProvenance",
  "type": "object"
}

Policies

benchmark: waived — waived: external_dependency
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	waived (external_dependency)	0

Claims implemented beside it

Attached by the file that implements each claim; every one links to its page with the implementation and the test that proves it.

guaranteed evidence-navigates-both-waysEvery claim names the test that proves it and every test names the claims it proves, from one derivationtest: test/cases/124_evidence.sh