Module preflight

Expand description

The preflight: whether Majordomus is actually in force in this checkout, and what proves each part of that claim.

The super::RepositoryEnvironment says what this checkout is — its branch, its toolchains, where a server published its address. It does not say what is proven: an address that accepts a connection is not a server of this version serving this checkout, a rule file on disk is not a rule anything enforces, and a recorded test run is not a run of the tree in front of you. Until this module, the entry banner drew a ✓ beside the Cockpit on the strength of a TCP connection while the server behind it was two versions old. The preflight is the value that refuses that.

§One verdict per claim, and no verdict without evidence

Every Check carries a Verdict and the Evidence behind it. The three verdicts that assert something is in force — Verdict::Verified, Verdict::Active and Verdict::Fresh — cannot be constructed without evidence: Check::new turns such a claim into Verdict::Unknown and says why. That is the whole rule project.entry-reports-only-evidence enforces, and it is enforced in the type rather than in each renderer.

§Two halves: observing and deriving

observe reads — the lease, one loopback request, the session and task records, the evidence ledger, one git log of the deployment ref — and returns Observations, plain data. derive() turns observations into a Preflight and reads nothing, so every verdict in this file is a test over a value rather than over a machine. The command line, the HTTP route, the MCP tool and resource, the Cockpit and the entry banner all render the value derive() returns.

§What it never does

It never builds the index on the entry path (the rule tally comes from the cache a full resolution wrote, and says when it was counted), never contacts anything but the loopback address a server of this checkout published, never runs a test, a build or a generator, and never writes outside .ai/local/.

use majordomus_cli::environment::preflight::{derive, Observations, Verdict};

// a checkout nobody has observed anything about
let preflight = derive(&Observations::empty("demo", 0));
// nothing is claimed in force, and nothing absent is dressed up as present
assert!(preflight.sections.iter().flat_map(|s| &s.checks).all(|c| !c.verdict.proves()));
assert_eq!(preflight.check("integration.server").unwrap().verdict, Verdict::Unknown);
assert_eq!(preflight.check("verification.deployment").unwrap().verdict, Verdict::Unavailable);

Structs§

Check: One claim, its verdict, and what the verdict rests on.
ContinuityObservation: What the continuity commands last left in this checkout’s continuity.json: the handovers other devices published that could be resumed here, as the last sync computed them, and how that sync went. Read from that one file — never from the store, never from a remote — so that entering a directory costs no git call and no network.
CoverageDimensions: Covered over total for each of the three dimensions llvm-cov measures: lines, functions and regions, of the crate with its test code excluded.
CoverageFraction: One dimension of a measurement: executed over executable.
CoverageRecord: One recorded coverage measurement: the fields of COVERAGE_RECORD this reads.
EpisodeObservation: The open episode, read from session-current.yaml, with whether it is this checkout’s.
Evidence: One thing a verdict rests on: where it was read and what was seen there.
GenerationRecord: One recorded generation check: the fields of GENERATION_RECORD this reads.
GitObservation: What git said about the work tree, taken from the snapshot’s one git status rather than asked again.
HandoverObservation: The handover a resuming worker would be given, judged by continuity’s own freshness rule.
Observations: Everything derive() decides from. Plain data: a test builds one by hand.
PeersObservation: The peer board’s tally, when somebody asked it.
Preflight: Whether Majordomus is in force in this checkout, claim by claim, with the evidence.
Probe: What a reading may cost: whether it may ask the server, ask the peer board, and use the checkout’s cache for answers that spawn git.
RulesTally: The rule corpus, counted by crate::rules::report against a commit.
Section: A group of checks: repository, session, governance, integration, verification.
ServerObservation: What the lease named and what the address it names answered, if it was asked.
TaskObservation: The task record, read from current.yaml through the continuity module’s own reader.

Enums§

CoverageObservation: The last coverage measurement scripts/rust-coverage recorded, as it recorded it.
DeploymentObservation: The newest commit of the deployment ref, and the source commit it says it was built from.
GenerationObservation: The last generation check scripts/pages current recorded, and the tree HEAD has now.
LedgerObservation: The evidence ledger, joined to the tree in front of you.
PolicyObservation: Whether the policy parsed, was refused, or was never read by this call.
RulesObservation: Where the rule tally came from: counted now, taken from the cache, or not there at all.
Verdict: What the repository can show about one claim.

Constants§

ANSWER_BUDGET: How long the one loopback request to a published server may take. Loopback answers in about a millisecond or is not there; anything slower is a machine under load, and a shell prompt is not the place to wait for it.
BOARD_BUDGET: How long the peer board may take when a person asked for the preflight. The board gathers every checkout’s, which is tens of milliseconds on a quiet machine and more on a loaded one; entry never asks it, so this budget is spent only when somebody is waiting for the answer.
COVERAGE_RECORD: Where scripts/rust-coverage records the last measurement it made itself, relative to the repository root. Local state: a measurement belongs to the checkout that ran it.
GENERATION_RECORD: Where scripts/pages current — the generation check the pre-commit hook runs — records its last verdict, relative to the repository root.
PAGES_REF: The ref the site deployment is read from: the remote-tracking copy of the branch scripts/pages publishes, whose every commit names the source commit it was built from (source: <sha>). A local ref, so reading it contacts nothing — and it is only as recent as the last fetch, which every verdict built on it says.
RULES_TIER: The path under the local half where a full resolution leaves the rule tally for the entry path to read. It lives in the environment cache file, as one more tier.
SCHEMA: The schema identity of Preflight.
SCHEMA_VERSION: The version of SCHEMA; it rises when a reader of the old shape would misread the new.

Functions§

cached_rules: The rule tally a full resolution left for the entry path, when there is one.
compact: The short form an entry prints: who and where, one line of the claims that matter most, and the most urgent thing to look at.
derive: The preflight these observations support. Reads nothing.
full: The whole preflight, a section per heading and a line per claim, with its evidence.
mark: The mark a terminal draws beside a verdict. A success mark only for a verdict that proves something, which is the one guarantee a person reading a banner needs.
observe: Read everything a preflight is decided from.
observe_coverage: The coverage record scripts/rust-coverage left, read as it is: one small file, no git.
observe_generation: The generation record scripts/pages current left, and HEAD’s tree to judge it against. Git is asked only when there is a record to judge.
store_rules: Leave a rule tally for the entry path. Never fatal: a checkout that cannot be written still gets a preflight, just one that says the rules were not counted.