HTTP API: environment

How far a resolved value can be trusted.

Where the values of one snapshot came from.

Where one field of the snapshot came from. This is what makes an inferred system debuggable: every fact can name the thing that decided it, so "why does it say that" is answered by the tool rather than by reading its source.

The state of one work tree, as porcelain v2 reports it.

How many valid objects of one kind the layer holds.

What the layer holds, counted per kind, plus the registry the executable composes. Every number here comes from the index — the same objects every other surface serves — and never from counting files that match a pattern: a file that does not parse is not a rule, and a count that says otherwise is a lie a person acts on.

Whether Majordomus is in force in this checkout, claim by claim, with the evidence.

use majordomus_cli::environment::preflight::{derive, Observations, Preflight};
let p = derive(&Observations::empty("demo", 0));
assert_eq!(p.schema, Preflight::schema_id());
assert_eq!(p.verdicts().len(), p.sections.iter().map(|s| s.checks.len()).sum::<usize>());

One claim, its verdict, and what the verdict rests on.

use majordomus_cli::environment::preflight::{Check, Evidence, Verdict};

// a claim of something in force without evidence is not accepted as one
let bare = Check::new("integration.mcp", "MCP", Verdict::Verified, "healthy", vec![]);
assert_eq!(bare.verdict, Verdict::Unknown);
assert!(bare.summary.contains("no evidence"));

let backed = Check::new(
    "integration.mcp", "MCP", Verdict::Verified, "served",
    vec![Evidence::new("GET /", "surface mcp ready")],
);
assert_eq!(backed.verdict, Verdict::Verified);

One thing a verdict rests on: where it was read and what was seen there.

use majordomus_cli::environment::preflight::Evidence;
let e = Evidence::new(".ai/repo/evidence/ledger.json", "6 recorded runs");
assert_eq!(e.source, ".ai/repo/evidence/ledger.json");

A group of checks: repository, session, governance, integration, verification.

use majordomus_cli::environment::preflight::{derive, Observations, Section};
let p = derive(&Observations::empty("demo", 0));
let ids: Vec<&str> = p.sections.iter().map(|s| s.id.as_str()).collect();
assert_eq!(ids, ["repository", "session", "governance", "integration", "verification"]);
// every check in a section carries the section's id as its prefix
let session: &Section = &p.sections[1];
assert!(session.checks.iter().all(|c| c.id.starts_with("session.")));

What the repository can show about one claim.

Nine words, not a boolean, because the actions they call for differ: stale is re-run the proof, unavailable is nothing is there, unknown is nobody looked, and not_applicable is there is nothing to look for.

use majordomus_cli::environment::preflight::Verdict;
assert!(Verdict::Verified.proves() && Verdict::Active.proves() && Verdict::Fresh.proves());
assert!(!Verdict::Stale.proves() && !Verdict::NotApplicable.proves());
assert_eq!(Verdict::NotApplicable.as_str(), "not_applicable");
// the most urgent first: a failure outranks a stale proof, which outranks an absence
assert!(Verdict::Failed.urgency() < Verdict::Stale.urgency());
assert_eq!(Verdict::Verified.urgency(), None);

What the project is, from the crate manifest and the prose written once in crate::about. Every field here is a compile-time constant of this executable: there is no file to read, nothing to parse, and nothing that can disagree with the binary that answers.

Where one provider projection stands against its policy.

One provider projection the policy declares, and whether the file on disk still matches what the policy renders.

Reasoning as the environment reports it: a summary of reasoning.advisors, from the same derivation, never a provider list of its own.

use majordomus_cli::environment::ReasoningSummary;

let summary: ReasoningSummary = serde_json::from_value(serde_json::json!({
    "operational": true, "mode": "offline", "available": ["local"], "unavailable": 2,
})).unwrap();
assert!(summary.operational);
assert_eq!(summary.available, ["local"]);
assert_eq!(serde_json::to_value(&summary).unwrap()["unavailable"], 2);

The snapshot: what this checkout is, right now.

Every surface that reports any of this renders this value. Collections are in a documented, stable order — kinds and workflows by name, services and providers in the order their canonical source declares them, diagnostics in the order they were found — so that two snapshots of the same repository serialise identically apart from RepositoryEnvironment::generated_at.

The checkout this snapshot is of.

How completely a snapshot was resolved. Carried in the snapshot because a consumer must be able to tell "there is no server running" from "nobody looked".

Whether a service answers. Unknown is a real answer and never a disguised no: a probe that timed out and a port that refused the connection lead a reader to different actions.

One local service of this repository: what it is, where it is, and whether anything answers there. The path is the one the router serves; the URL exists only while a server does.

Where a tier of the snapshot came from. A tier the active resolution cannot reach is TierState::Unavailable with the reason, and its values are absent rather than zero.

Whether a declared toolchain is usable here.

A toolchain the repository declares, and what is installed for it. The three are kept apart on purpose: a repository can declare a version nobody has, and a machine can have a version no repository asked for, and reporting either as the other is how a version mismatch stays invisible for a week.

What version control says about the checkout, or why it could not be asked.

The workflows a person can run here, as the workflow runner itself describes them.

One workflow: a recipe of the repository's justfile, as just describes it.

The entry point of one group of workflows: what the group is, and the one workflow that stands for it.

One parameter of a workflow.