HTTP API: obligations

What this checkout's active task owes, and how much of it is still true.

A clone that has never run the lifecycle answers this too, and answers it as absence: present false, no task, and a finding saying so. "Nothing owed" and "nothing to owe it" are different facts, and a served instance must not report the second as the first.

use majordomus_cli::capability::builtin::obligations::Closure;
let fresh: Closure = serde_json::from_str(
    r#"{"present":false,"worktree":"/srv/clone","branch":"master","closed":false,
        "tallies":{},
        "findings":["no active task in this checkout (.ai/local/state/current.yaml); nothing owes anything here"]}"#,
)
.unwrap();
assert!(!fresh.present && !fresh.closed, "nothing that does not exist is closed");
assert!(fresh.task.is_none() && fresh.obligations.is_empty());
assert_eq!(fresh.findings.len(), 1, "absence is reported, not implied");

The task.evidence line that discharged an obligation, as the ledger holds it.

Nothing older is consulted: evidence is superseded by evidence, and the ledger keeps the history for a reader that wants it.

use majordomus_cli::capability::builtin::obligations::Evidence;
let e: Evidence = serde_json::from_str(
    r#"{"recorded_at":"2026-09-09T21:01:00Z","head":"f00ba7","branch":"master",
        "kind":"ci","command":"scripts/ci/reference-check","inputs_hash":"7f68b9"}"#,
)
.unwrap();
assert_eq!(e.head, "f00ba7", "the envelope's commit is what a remote fact is judged against");
assert!(e.artifact.is_empty(), "one of command and artifact; narrative is not evidence");

One token a task may declare in requires, as the distribution ships it.

remote and inputs are what decide how its evidence is judged, and they are the file's decision rather than this reader's: a fact the working tree cannot establish is bound to the commit it was taken at, and everything else is bound to the bytes of the files its pathspecs select.

use majordomus_cli::capability::builtin::obligations::Obligation;
let push: Obligation = serde_json::from_str(
    r#"{"id":"push","title":"The commit reached the remote",
        "summary":"The branch's head exists on the remote it tracks.",
        "discharged_by":"git","remote":true}"#,
)
.unwrap();
assert!(push.remote);
assert!(push.inputs.is_empty(), "a remote fact is bound to a commit, not to a tree");

One obligation the task declared, joined with what the vocabulary says about it and with the evidence that does or does not discharge it.

The vocabulary's fields are repeated here on purpose: a client asking what this task owes gets the token's title, its summary and the command that would discharge it in the same answer, and needs no second call to render a report.

use majordomus_cli::capability::builtin::obligations::{ObligationClosure, ObligationState};
let owed: ObligationClosure = serde_json::from_str(
    r#"{"id":"pages","title":"The published site serves this commit","remote":true,
        "state":"owed","detail":"owed, and no evidence was recorded",
        "reproduce":"majordomus evidence --covers pages --command 'scripts/pages verify'"}"#,
)
.unwrap();
assert_eq!(owed.state, ObligationState::Owed);
assert!(owed.evidence.is_none() && owed.staleness.is_none(), "nothing to label");
assert!(owed.reproduce.starts_with("majordomus evidence"), "a finding carries its repair");

Where one obligation stands.

The words are the validator's verdicts, not a severity scale: stale is not a worse owed, it is evidence that was true and no longer describes what it proved.

use majordomus_cli::capability::builtin::obligations::ObligationState;
// only one of the four lets a task be called completed
let completable = |s: ObligationState| s == ObligationState::Discharged;
assert!(completable(ObligationState::Discharged));
assert!(!completable(ObligationState::Stale), "evidence that no longer describes the tree");
assert!(!completable(ObligationState::Owed));
assert!(!completable(ObligationState::Undeclared));

The vocabulary the distribution ships: every token there is.

count is measured from obligations rather than written down, so a token added to the file is counted by the same act that declares it.

use majordomus_cli::capability::builtin::obligations::Vocabulary;
let v: Vocabulary = serde_json::from_str(
    r#"{"version":1,"source":"/opt/majordomus/share/obligations.yaml","count":1,
        "obligations":[{"id":"commit","title":"The work is committed",
                        "summary":"In the branch's history, not the working tree.",
                        "discharged_by":"git","remote":false}]}"#,
)
.unwrap();
assert_eq!(v.count, v.obligations.len());
assert_eq!(v.version, 1, "the only shape this reader accepts");