Module freshness 

Freshness: whether a recorded run still proves anything at the revision a reader is shown.

A passing run is a fact about the tree it measured. Whether it is also a fact about the tree in front of a reader depends on three things the run cannot know: whether the revision presented contains the commit the run was recorded on, what changed between the two, and whether either tree was the commit it claims to be. This module decides that, once, for every surface — the evidence report, the rules report, and every later reader of the ledger — so that no two of them can disagree about what a run still proves.

The pieces

• Presented — what is judged: the reader’s working tree, or the checked-out commit judged as committed (presented_commit), with the ledger committed in it (ledger_at);
• compare — the containment of the evidence commit in the presented revision, and the paths that changed between them (changed_between);
• freshness — the one truth table, pure, from a recorded run to a Judgement;
• current — whether a judgement is current evidence, for a reader that counts a route as met: proven, or inputs_unchanged from a run on a tree that was its commit;
• weakened_by — the monotone rule: a supplementary record may withhold proven and never grant it; its first source is uncommitted, the executions the working ledger holds that the presented commit’s ledger does not;
• aggregate — how several states make one, with a failure outranking an absence.

Example

The truth table without a repository: a recorded skip is not a failure, and only a pass the presented revision contains, with nothing but the ledger changed since, on a clean tree at both ends, is proven.

use majordomus_cli::evidence::freshness::{freshness, Comparison, Recorded, TreeState};
use majordomus_cli::evidence::{Execution, ProofState};
use majordomus_cli::git::Containment;

let run = |outcome: &str| -> Execution {
    serde_json::from_value(serde_json::json!({
        "test": "suite:07_scope", "runner": "suite", "source": "test/cases/07_scope.sh",
        "outcome": outcome, "seconds": 1, "commit": "a".repeat(40),
        "working_tree": "clean", "digest": "sha256:0", "at": "2026-09-26T00:00:00Z",
        "origin": "local", "command": "bash test/run.sh 07_scope"
    }))
    .unwrap()
};
let nothing_changed = Comparison {
    containment: Containment::Contains,
    changed: Some(Default::default()),
};
let inputs = vec!["test/cases/07_scope.sh".to_string()];
let judge = |e: &Execution| {
    freshness(
        Recorded::Ran(e),
        Some(&inputs),
        "test/cases/07_scope.sh",
        false,
        Some(&nothing_changed),
        TreeState::Clean,
    )
};
assert_eq!(judge(&run("pass")).state, ProofState::Proven);
assert_eq!(judge(&run("skip")).state, ProofState::NotRun);
assert_eq!(judge(&run("error")).state, ProofState::Failing);

Structs

Comparison

What git says about one evidence commit against the presented revision: whether the revision contains it, and what changed between them.

Judgement

One verdict, with what it rests on.

Supplementary

A record read beside the verdict’s own execution, which may weaken it and never strengthens it.

Enums

Presented

The revision a verdict is about.

Recorded

What the ledger holds for one route’s test, before any comparison.

TreeState

Whether a tree was the commit it sits on: the three words the ledger and git already use, typed.

Constants

UNCOMMITTED_RUN

The phrase a detail uses for a run the working ledger holds and the presented commit’s ledger does not: the first source of weakened_by.

Functions

aggregate

Several states made one: a failure outranks an absence, and otherwise the weakest part that can carry proof decides.

changed_between

Every path that differs between the evidence commit and the presented revision, or None when git cannot answer — which no caller may read as “nothing changed”.

compare

Compare one evidence commit with the presented revision. For the working tree the containing commit is HEAD (an unborn HEAD contains nothing anyone can name); for a presented commit it is that commit.

current

Whether a verdict of freshness is current evidence of what its route names: the one answer a reader that counts a route as met — an intent criterion, for one — asks for, so that no such reader draws its own line between a pass and a proof.

freshness

The one truth table: what a recorded run proves at the presented revision.

ledger_at

The ledger as commit holds it: git show <commit>:.ai/repo/evidence/ledger.json.

presented_commit

The checked-out commit, presented as committed.

uncommitted

Every execution the working copy of the ledger holds that committed does not.

weakened_by

The monotone rule: a supplementary record may withhold proven and never grant it.