HTTP API: shared types

The active task of this checkout, when there is one.

When the state behind an answer was read: the freshness contract of a capability answer.

Declared once and carried in the output type of every answer that is a picture of state, so that the output schema, OpenAPI, the MCP tool schemas and the command line's JSON all carry it without a transport of their own. It is set where the state is read — the index build, the git read — never by the executor, which knows when a handler ran and not when the state it read was taken.

use std::time::{Duration, UNIX_EPOCH};
use majordomus_cli::index::AnswerObservation;
let at = UNIX_EPOCH + Duration::from_secs(1_788_000_000);
let o = AnswerObservation::taken("git read", at, Some(Duration::from_secs(120)));
assert_eq!(o.observed_at, "2026-08-29T10:40:00Z");
assert_eq!(o.stale_after.as_deref(), Some("2026-08-29T10:42:00Z"));
assert!(!o.is_stale_at(at + Duration::from_secs(120)));
assert!(o.is_stale_at(at + Duration::from_secs(121)));

A stable, globally meaningful identity: a namespace, a dot, and a local part. repository.info and objects.get for executables; <kind>.<identity> for a declarative object (rule.majordomus.scope-integrity@1, document.docs/CLI.md, policy..ai/repo/policy.yaml).

Grammar: the namespace matches [a-z][a-z0-9_-]*; the local part is non-empty and carries no whitespace or control character, any other Unicode included, because it is opaque: a path, a versioned identity, or a name, as the kind's identity rule produced it.

What a capability is. Three kinds exist because three semantics exist: something that is executed and changes nothing, something that is executed and changes this process's own memory, and something that is read. A command may also write the repository's own tracked records, which its kind does not say and its execution policy does (ExecutionPolicy::writes_repository).

How long a call takes is not a kind. A read that walks every file of the layer is still a read, and the thing that makes it worth watching — that it reports as it goes and stops when it is asked to — is one property of its handler, declared with crate::capability::Executable::cancellable and carried on ExecutionPolicy.

Where a capability came from. Never an absolute path.

Which checkouts a reading of the server status covers.

The two answers cost differently and that is the whole reason the choice exists: the repository's checkouts are read from git's registry of them and each one costs a lease read and a probe, while this checkout alone costs one of each and enumerates nothing. The word each variant serialises to is the word the query parameter, the tool input and the command-line flag all take.

use majordomus_cli::capability::builtin::server::Checkouts;
assert_eq!(serde_json::to_value(Checkouts::This).unwrap(), "this");
assert_eq!(serde_json::to_value(Checkouts::Repository).unwrap(), "repository");
assert_eq!(Checkouts::default(), Checkouts::Repository, "the wide answer is what a caller who says nothing has always got");

How well a criterion is carried by the plan: whether work exists for it, whether that work is gated by evidence, and whether the recorded gap already saw it true.

use majordomus_cli::intent_plan::CoverageStrength;
// the wire spelling every surface answers with
assert_eq!(serde_json::to_string(&CoverageStrength::Weak).unwrap(), "\"weak\"");
// the order is the one a reader ranks by: uncovered is the worst
assert!(CoverageStrength::Uncovered < CoverageStrength::Covered);

One issue as coverage sees it: which milestone carries it, the status the plan derived for it, and how much evidence it owes before it may be DONE.

use majordomus_cli::intent_plan::CoveringIssue;
let issue = CoveringIssue {
    id: "I1901".into(),
    milestone: "intent-planning".into(),
    status: "READY".into(),
    evidence_need: 2,
};
// an issue that owes no evidence covers a criterion only weakly
assert!(issue.evidence_need > 0);

One criterion of one intent, and the work that carries it: the live issues that serve it, the milestones those issues sit under, and the strength derived from them.

use majordomus_cli::intent_plan::{CoverageStrength, CriterionCoverage};
let c = CriterionCoverage {
    intent: "intent-planning".into(),
    criterion: "gap-is-recorded".into(),
    strength: CoverageStrength::Uncovered,
    issues: vec![],
    milestones: vec![],
};
// nothing serves it, so nothing in the plan will make it true
assert_eq!(c.strength, CoverageStrength::Uncovered);
assert!(c.issues.is_empty());

One finding about the declarative state, named by a stable code, tied to a path where there is one, and carrying the command that reproduces it where there is one.

How far a record's recorded commit is from the commit this checkout is on.

The four words are the shell tool's, deliberately. A reader that met advanced from one surface and stale from another would have to learn the same four facts twice.

The body of every error response.

What went wrong, as the HTTP projection names it.

One recorded run of one test: the whole of what this repository durably remembers about it.

Every field is provenance. A result with no commit is an anonymous green, which is the thing a badge must never be derived from.

use majordomus_cli::evidence::{digest_of, Execution, Origin, Outcome, Runner, TestId};

let id = TestId::of("apps/majordomus-cli/tests/why.rs").unwrap();
let run = Execution {
    test: id.as_string(),
    runner: Runner::Crate,
    source: id.source(),
    outcome: Outcome::Pass,
    seconds: 12,
    commit: "0".repeat(40),
    working_tree: "clean".into(),
    digest: digest_of(b"fn main() {}"),
    at: "2026-09-11T00:00:00Z".into(),
    origin: Origin::Ci,
    command: id.reproduce(),
    run: None,
};

// it is a value in a tracked JSON file, so it has to survive the file unchanged
let back: Execution = serde_json::from_str(&serde_json::to_string(&run).unwrap()).unwrap();
assert_eq!(back, run);
assert_eq!(back.test, "crate:why");
assert_eq!(back.command, "cargo test --test why");

Example

One recorded run, with the provenance the runner did not carry: which commit, which tree state, the digest of the test's own source, when, and how to run it again.

use majordomus_cli::evidence::{Execution, Origin, Outcome, Runner};
let e = Execution {
    test: "suite:07_scope".into(),
    runner: Runner::Suite,
    source: "test/cases/07_scope.sh".into(),
    outcome: Outcome::Pass,
    seconds: 3,
    commit: "a04b65c9".into(),
    working_tree: "clean".into(),
    digest: "sha256:00".into(),
    at: "2026-09-11T00:00:00Z".into(),
    origin: Origin::Local,
    command: "bash test/run.sh 07_scope".into(),
    run: None,
};
assert!(e.outcome.proves());

Where a run happened. The canonical model is provider-neutral: a CI adapter records Ci, and nothing here knows or cares which CI it was.

use majordomus_cli::evidence::Origin;

assert_eq!(Origin::parse("CI"), Some(Origin::Ci));
assert_eq!(Origin::parse("local"), Some(Origin::Local));
// naming the provider is the adapter's business; the ledger records the kind of run,
// so a repository that changes CI does not change what its old evidence says
assert!(Origin::parse("github-actions").is_none());

Example

use majordomus_cli::evidence::Origin;
assert_eq!(Origin::parse("ci"), Some(Origin::Ci));
assert_eq!(Origin::parse("nowhere"), None);

What a run said about one test.

NotRun is deliberately absent: it is the absence of an execution, not an outcome one had. Encoding it here would let a recorder write "this did not run" and have it counted among the things that did.

use majordomus_cli::evidence::Outcome;

assert!(Outcome::parse("ok").proves());
assert!(!Outcome::parse("timeout").proves());
// exactly one of the five is evidence of anything; the other four are reasons there
// is none, kept apart because "it declined" and "the harness broke" are different bugs
assert_eq!(Outcome::parse("skipped"), Outcome::Skip);
assert_eq!(Outcome::parse("nonsense"), Outcome::Error);

Example

use majordomus_cli::evidence::Outcome;
assert!(Outcome::parse("ok").proves());
assert_eq!(Outcome::parse("wat"), Outcome::Error);

The continuous-integration run an execution was recorded in: enough to navigate back to the run that produced it.

Origin says what kind of run it was and deliberately names no provider. This names the one run, in the words the provider addressed it with when it happened — its identifier, its attempt, the workflow and job, and the address a reader follows — because a link built later from a template would point wherever the template's idea of the provider had drifted to. Only an adapter constructs it; nothing in the model reads the provider's name.

use majordomus_cli::evidence::RunRef;

let actions = |k: &str| {
    let v = match k {
        "GITHUB_ACTIONS" => "true",
        "GITHUB_SERVER_URL" => "https://github.com",
        "GITHUB_REPOSITORY" => "owner/repo",
        "GITHUB_RUN_ID" => "42",
        "GITHUB_RUN_ATTEMPT" => "2",
        "GITHUB_WORKFLOW" => "validate",
        "GITHUB_JOB" => "evidence",
        _ => return None,
    };
    Some(v.to_string())
};
let run = RunRef::from_env(actions).unwrap();
assert_eq!(run.id, "42");
assert_eq!(run.attempt, 2);
assert_eq!(run.url, "https://github.com/owner/repo/actions/runs/42/attempts/2");
// a run that names neither its pull request's head nor its event still names itself
assert_eq!((run.head_sha, run.event), (None, None));

let head = "0123456789abcdef0123456789abcdef01234567";
let pull = |k: &str| match k {
    "MJ_RUN_HEAD_SHA" => Some(head.to_string()),
    "GITHUB_EVENT_NAME" => Some("pull_request".to_string()),
    _ => actions(k),
};
let run = RunRef::from_env(pull).unwrap();
assert_eq!(run.head_sha.as_deref(), Some(head));
assert_eq!(run.event.as_deref(), Some("pull_request"));

// outside a run there is nothing to name, and a half-described run is not a run
assert!(RunRef::from_env(|_| None).is_none());
assert!(RunRef::from_env(|k| (k == "GITHUB_ACTIONS").then(|| "true".to_string())).is_none());

Which runner produced a result, and therefore how the test is named and re-run.

The repository has exactly two that a claim may name today. A third would be a variant here and a branch in TestId::of; a claim naming something neither runner produces is reported as ProofState::Unrunnable rather than silently counted as covered.

use majordomus_cli::evidence::{Runner, TestId};

// which runner owns a test is read off where the test lives, never declared
assert_eq!(TestId::of("test/cases/07_scope.sh").unwrap().runner, Runner::Suite);
assert_eq!(
    TestId::of("apps/majordomus-cli/tests/why.rs").unwrap().runner,
    Runner::Crate
);
// and a path under neither directory belongs to no runner at all
assert!(TestId::of("test/lib.sh").is_none());

Example

use majordomus_cli::evidence::Runner;
assert_eq!(Runner::Suite.prefix(), "suite");
assert_eq!(Runner::Crate.prefix(), "crate");

What running a capability changes outside the caller.

Classified, never declared: it follows from the kind, which is the field a declaration already carries. A projection reads this to decide whether to ask before running something — the Cockpit's confirmation is derived from it — instead of naming capabilities it must treat carefully, which is a list that goes stale the day after it is written.

How old a record is, judged against session.freshness in the policy.

This is the second of two independent judgements every record carries, and it exists because the first one cannot answer this question. Divergence says where a record's commit sits relative to HEAD; advanced means that commit is an ancestor of this one, which sounds like agreement and is identically true on the day the record is written and a month later. Between 2026-09-05 and 2026-09-11 this repository served a handover that was advanced and six days dead, and every surface that read this model — MCP, the HTTP API, the Cockpit — presented its Next Action as the thing to do (ADR 0052).

The thresholds are policy and are read, never restated here: a constant in this file would be a second source of truth for a number the policy owns, and a repository whose policy predates the key is reported as Freshness::Unknown naming the missing key rather than judged against a default nobody declared.

The five words divide into two groups, and the division is the one a caller acts on: fresh and aging are current and may be presented as the instruction, stale and invalid must be shown as history, and unknown is neither — a record nobody can date is not thereby an old record, and treating it as one would quietly discard a briefing that is perfectly good. Freshness::history is that division, and it is the only place it is decided.

use majordomus_cli::capability::builtin::continuity::Freshness;

// the two renderings are one value: the serialised word is the word `as_str` gives,
// so a reader who met `stale` from MCP and from the command line met one fact
let stale = serde_json::to_value(Freshness::Stale).unwrap();
assert_eq!(stale, serde_json::json!("stale"));
assert_eq!(stale.as_str(), Some(Freshness::Stale.as_str()));

// and the division a caller acts on: absence of a judgement is not a bad judgement
assert!(Freshness::Stale.history() && Freshness::Invalid.history());
assert!(!Freshness::Unknown.history(), "undated is not old");
assert!(!Freshness::Fresh.history() && !Freshness::Aging.history());

Where one dimension of the system stands. Ordered by severity, so the worst check decides the whole.

One criterion with the evidence behind it: what the record declared, what the ledger says about it, whether that meets it, and the command that would produce the evidence again.

use majordomus_cli::evidence::ProofState;
use majordomus_cli::intent::{IntentCriterion, IntentEvidenceState};
let c = IntentCriterion {
    id: "stage-is-derived".into(),
    criterion: "the stage follows the plan".into(),
    evidence: "test".into(),
    reference: "apps/majordomus-cli/tests/intent.rs".into(),
    state: IntentEvidenceState::NotRun,
    met: false,
    proof: Some(ProofState::NotRun),
    reproduce: None,
};
// nothing recorded is not a pass
assert!(!c.met);

What the evidence behind one criterion says, as a word. Only Current meets a criterion: a stale, failing, unrecorded or underivable reference never does, and neither does one that resolves to nothing.

Whether a recorded run is current is not decided here. A test or claim criterion is judged by the evidence module's one truth table (evidence::freshness()) at the working tree and read through evidence::current, the same judgement the claim report and the subject pages make; IntentEvidenceState::judged is the whole of the translation. So the state follows the evidence both ways: a criterion met today reads stale or failing the moment the ledger or the tree says so, and met again once a current pass is recorded.

use majordomus_cli::intent::IntentEvidenceState;
assert_eq!(serde_json::to_string(&IntentEvidenceState::NotRun).unwrap(), "\"not_run\"");
assert_ne!(IntentEvidenceState::Stale, IntentEvidenceState::Current);

One validation finding: its level, a stable code a reader greps for, the intent or milestone it is about, one line of what is wrong, and the command that shows it again.

use majordomus_cli::intent::{IntentFinding, FAIL};
let f = IntentFinding {
    level: FAIL.into(),
    code: "unknown_milestone".into(),
    subject: "intent-lifecycle".into(),
    message: "`no-such` is not a milestone".into(),
    reproduce: "majordomus intent validate".into(),
};
assert_eq!(f.level, "FAIL");
assert_eq!(f.reproduce, "majordomus intent validate");

One milestone an intent names, as the plan derives it. A milestone that does not resolve is carried with resolved: false rather than dropped, because a name that points at nothing is a finding and not an absence.

use majordomus_cli::intent::IntentMilestone;
let named = IntentMilestone { id: "no-such".into(), resolved: false, status: None };
assert!(!named.resolved);
assert!(named.status.is_none());

Where an intent stands, derived on every read and stored nowhere.

use majordomus_cli::intent::IntentStage;
// one word every surface prints, and an order that follows the work
assert_eq!(IntentStage::Executing.as_str(), "executing");
assert!(IntentStage::Declared < IntentStage::Satisfied);

Whether the evidence alone settles an intent, and which criteria hold it back: every unmet criterion, in the order the record declares them. Empty when the verdict is satisfied, and when it is unknown because the intent declares no criterion.

use majordomus_cli::intent::{verdict, IntentVerdict, IntentVerdictState};
// an intent that declares no criterion cannot be settled by evidence
let v: IntentVerdict = verdict(&[]);
assert_eq!(v.state, IntentVerdictState::Unknown);
assert!(v.reasons.is_empty());

One criterion that holds a verdict back from satisfied: which one, the kind of evidence it names, and the state that evidence is in — the criterion's own words, not new ones.

use majordomus_cli::intent::{IntentEvidenceState, IntentVerdictReason};
let r = IntentVerdictReason {
    criterion: "probe-passes".into(),
    evidence: "test".into(),
    state: IntentEvidenceState::NotRun,
};
assert_eq!(r.state, IntentEvidenceState::NotRun);

What the evidence alone says about an intent, as a word: derived from its criteria and never from the plan, so it can read satisfied while a milestone is still open (ADR 0107).

use majordomus_cli::intent::IntentVerdictState;
let word = serde_json::to_string(&IntentVerdictState::Unsatisfied).unwrap();
assert_eq!(word, "\"unsatisfied\"");
assert_eq!(IntentVerdictState::Satisfied.as_str(), "satisfied");

One intent, as its record declares it and as the plan and the ledger derive it: the statement and invariants as authored, each milestone with its derived status, each criterion with the state of its evidence, the stage that follows from both, and the verdict that follows from the evidence alone.

use majordomus_cli::intent::{verdict, IntentStage, IntentVerdictState, IntentView};
let view = IntentView {
    id: "intent-lifecycle".into(),
    title: "Work is traceable to the intent it serves".into(),
    statement: "A reader can ask what work is for.".into(),
    invariants: vec!["no intent status is stored".into()],
    stage: IntentStage::Declared,
    milestones: vec![],
    satisfaction: vec![],
    met: 0,
    verdict: verdict(&[]),
    governance: vec!["adr:adr-0070".into()],
    non_goals: vec![],
    superseded_by: None,
    source: ".ai/repo/project/intents/intent-lifecycle.yaml".into(),
};
// a record naming no milestone that resolves has not been planned
assert_eq!(view.stage, IntentStage::Declared);
// and one declaring no criterion cannot be settled by evidence
assert_eq!(view.verdict.state, IntentVerdictState::Unknown);

Where an object came from. Every field is computed from the repository, never authored.

One object, summarised for a listing.

A peer's identity for the life of the server: p1, p2, ... in attachment order. p1 is the session that started the server.

What the repository can say about one claim's proof, right now.

Ordered from strongest to weakest, so a summary that sorts by this reads as a ranking.

use majordomus_cli::evidence::ProofState;

let mut states = vec![ProofState::NotRun, ProofState::Stale, ProofState::Proven];
states.sort();
assert_eq!(
    states,
    vec![ProofState::Proven, ProofState::Stale, ProofState::NotRun]
);

// the two strongest are deliberately not one state: `inputs unchanged` is the absence
// of a known invalidation, and collapsing it into `proven` is the unaccountable badge
assert_ne!(ProofState::Proven, ProofState::InputsUnchanged);
assert!(ProofState::Proven < ProofState::InputsUnchanged);
assert!(ProofState::InputsUnchanged.passing());

Example

use majordomus_cli::evidence::ProofState;
assert!(ProofState::Proven.passing());
assert!(!ProofState::NotRun.passing());
assert!(!ProofState::InputsUnchanged.meaning().is_empty());

What a conventional commit says it did.

The set is the one the repository's own commit convention uses; a commit whose subject does not parse is ChangeKind::Other and still appears, because a changelog that silently drops what it cannot classify is a changelog that lies by omission.

Where a checkout's server stands, decided from its lease, whether the server the lease names answers for that checkout, and whether what answers is this executable's code.

use majordomus_cli::capability::builtin::server::ServerStanding;
let all = [ServerStanding::Absent, ServerStanding::Starting, ServerStanding::Ready,
           ServerStanding::Outdated, ServerStanding::Stale];
let words: Vec<&str> = all.iter().map(|s| s.as_str()).collect();
assert_eq!(words, ["absent", "starting", "ready", "outdated", "stale"]);
assert_eq!(serde_json::from_str::<ServerStanding>("\"stale\"").unwrap(), ServerStanding::Stale);

How bad a diagnostic is. Error excludes the file it concerns from the index and puts the index into the degraded state; Warning and Info do neither.

Where a capability stands, in the repository's own vocabulary for claims. A capability that is Planned or Unsupported may be listed but is never executable through any projection; the registry refuses to build otherwise.

The registry counted: by source, kind, stability and projection.