Module environment 

The repository environment: one typed snapshot of what this checkout is right now — the project, the repository, version control, the toolchains it declares, what the layer holds, the workflows a person can run, the provider projections and the local services — with a provenance entry for every fact in it.

It is the canonical source for every surface that says any of those things. The direnv banner, majordomus env, GET /api/v1/environment, the MCP resource majordomus://environment, the Cockpit’s overview and the documentation are renderings of this one value; none of them discovers anything of its own. That is the whole point: before it existed, “what branch is this and what is running” was a shell pipeline in whoever’s dotfiles, and a second one in the next surface that wanted it.

Two resolutions, one model

Building the index costs seconds, and the banner runs on every cd. So a snapshot is resolved in one of two modes (Resolution), and both produce the same type:

• Resolution::Full reads everything, including the index, and writes the cache.
• Resolution::Fast reads only what is cheap — one git call, one just call, a few file reads — and takes the rest from the cache written by the last full resolution. What no cache can supply is reported as unknown, never guessed and never defaulted: a count that is not a count is worse than no count.

The modes differ in what they may read, never in what they mean. fast_and_full_agree holds them to that.

What is canonical, and what is derived

Fact	Canonical source
project name, version, licence, summary	the crate manifest and crate::about, at compile time
repository root, layer sections	.ai/manifest.yaml, through crate::repository::Repository
version control	one git status --porcelain=v2 --branch
toolchains	the manifest that declares each one
what the layer holds	the index, through the capability registry
workflows	just --dump --dump-format json
provider projections	the policy’s projections[]
services	the capability registry’s routes and the shared server’s lease

Nothing in this module writes to the repository outside .ai/local/, and nothing in it opens a socket to anything but the loopback address the lease names.

Re-exports

pub use cache::Cache;

pub use cache::CachedTier;

pub use resolve::resolve;

pub use resolve::EnvironmentQuery;

pub use resolve::Inputs;

pub use vcs::GitWorkingTree;

pub use vcs::VcsState;

Modules

cache

The snapshot cache: the two or three answers a fast resolution cannot afford to compute, kept beside the shared server’s lease under the checkout-local half of the layer.

preflight

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

probe

Bounded outside contact: the only two things the environment resolver does that it cannot finish on its own — run a program, and open a socket — each with a hard budget.

render

The banner: a snapshot rendered for a person at a terminal.

resolve

The resolver: one function that builds a RepositoryEnvironment, and the only place any surface gets one.

services

The local services of a repository: what this executable serves, where, and whether anything is answering there now.

shell

Shell export: the few variables a shell working in this repository benefits from, emitted so that eval "$(majordomus env export)" is safe whatever the repository is called and wherever it lives.

text

Terminal text: making repository metadata safe to print, and measuring it in columns rather than in bytes.

toolchain

Toolchains: the ones this repository declares, and what is installed for them.

vcs

Version control for the environment snapshot: branch, head, upstream, how far ahead and behind, and what is dirty — from one git status --porcelain=v2 --branch.

workflows

Workflows: the recipes a person can run here, read from the workflow runner’s own structured description of them.

Structs

FieldSource

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.

KindCount

How many valid objects of one kind the layer holds.

LayerSummary

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.

ProjectIdentity

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.

ProviderState

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

ReasoningSummary

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

RepositoryEnvironment

The snapshot: what this checkout is, right now.

RepositoryIdentity

The checkout this snapshot is of.

ServiceState

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.

ToolchainState

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.

WorkflowCatalogue

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

WorkflowDescriptor

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

WorkflowEntrypoint

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

WorkflowParameter

One parameter of a workflow.

Enums

Confidence

How far a resolved value can be trusted.

ProjectionState

Where one provider projection stands against its policy.

Resolution

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”.

ServiceAvailability

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.

TierState

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.

ToolchainAvailability

Whether a declared toolchain is usable here.

Constants

SCHEMA

The schema identity of RepositoryEnvironment. It travels in the snapshot itself, so a document read from a cache, an API or a file says which contract it was written under; SCHEMA_VERSION rises when a reader of the old shape would misread the new one.

SCHEMA_VERSION

The version of SCHEMA. A cache entry written under a different version is not read.