environment.status
One snapshot of this checkout: project identity, repository identity, version control, declared toolchains, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services with the address a running server published. Every value carries where it came from.
One snapshot of this checkout: project identity, repository identity, version control, declared toolchains, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services with the address a running server published. Every value carries where it came from.
- query
- behaviorally_verified
- module environment
- #environment
- #repository
- #introspection
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_environment resource majordomus://environment |
| HTTP | GET /api/v1/environment operationId environment.status |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · EnvironmentInput
What to include in the snapshot.
| property | type | required | description |
|---|---|---|---|
| probe_services | boolean | no | Contact the local address a running server published, to say whether it answers. Off by default: a served request should not open a socket to another server on behalf of its caller, and the caller usually is that server. default false |
JSON Schema
{
"additionalProperties": false,
"description": "What to include in the snapshot.",
"properties": {
"probe_services": {
"default": false,
"description": "Contact the local address a running server published, to say whether it answers.\nOff by default: a served request should not open a socket to another server on\nbehalf of its caller, and the caller usually is that server.",
"type": "boolean"
}
},
"title": "EnvironmentInput",
"type": "object"
}output · RepositoryEnvironment
The snapshot: what this checkout is, right now. Every surface that reports any of this renders this value. Collections are in a documented, stable order — kinds and workflows by name, services and providers in the order their canonical source declares them, diagnostics in the order they were found — so that two snapshots of the same repository serialise identically apart from [`RepositoryEnvironment::generated_at`].
| property | type | required | description |
|---|---|---|---|
| diagnostics | array | yes | Everything that went wrong or is worth knowing, in the order it was found. |
| generated_at | string | yes | When it was taken, RFC 3339 in UTC. |
| layer | reference | yes | What the layer holds. |
| project | reference | yes | What the project is. |
| provenance | array | yes | Where every field came from. |
| providers | array | yes | The provider projections the policy declares, in the policy's order. |
| repository | reference | yes | What the checkout is. |
| resolution | reference | yes | How completely it was resolved. |
| schema | string | yes | The contract this document follows, `majordomus/repository-environment/v1`. |
| services | array | yes | The local services, in the order the service table declares them. |
| toolchains | array | yes | The toolchains the repository declares, sorted by id. |
| vcs | reference | yes | What version control says. |
| workflows | reference | yes | The workflows a person can run. |
JSON Schema
{
"$defs": {
"Confidence": {
"description": "How far a resolved value can be trusted.",
"oneOf": [
{
"const": "exact",
"description": "Read from its canonical source during this resolution.",
"type": "string"
},
{
"const": "cached",
"description": "Read from a cache whose fingerprint still matches its inputs.",
"type": "string"
},
{
"const": "unknown",
"description": "Not resolved.",
"type": "string"
}
]
},
"Diagnostic": {
"description": "One finding about the declarative state, named by a stable code, tied to a path where\nthere is one, and carrying the command that reproduces it where there is one.",
"properties": {
"code": {
"description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`.",
"type": "string"
},
"message": {
"description": "What is wrong, for a person; the code is for a program.",
"type": "string"
},
"path": {
"description": "Repository-relative path of the file concerned, when there is one.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
}
},
"required": [
"severity",
"code",
"message"
],
"type": "object"
},
"FieldSource": {
"description": "Where one field of the snapshot came from. This is what makes an inferred system\ndebuggable: every fact can name the thing that decided it, so \"why does it say that\"\nis answered by the tool rather than by reading its source.",
"properties": {
"confidence": {
"$ref": "#/$defs/Confidence",
"description": "How certain the value is."
},
"field": {
"description": "The field, in dotted form: `services.cockpit.url`, `vcs.branch`.",
"type": "string"
},
"resolver": {
"description": "The part of this executable that read it.",
"type": "string"
},
"source": {
"description": "What decided it: a file, a command, a compile-time constant, the cache.",
"type": "string"
},
"value": {
"description": "The value as it appears in the snapshot, rendered for a person; absent for a field\nthat resolved to nothing.",
"type": [
"string",
"null"
]
}
},
"required": [
"field",
"source",
"resolver",
"confidence"
],
"type": "object"
},
"GitWorkingTree": {
"description": "The state of one work tree, as porcelain v2 reports it.",
"properties": {
"ahead": {
"description": "Commits this branch has that its upstream does not; `None` without an upstream.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"behind": {
"description": "Commits the upstream has that this branch does not; `None` without an upstream.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"branch": {
"description": "The branch, or `None` when HEAD is detached or unborn.",
"type": [
"string",
"null"
]
},
"changed_paths": {
"description": "Every path that is not clean, repository-relative, in git's order. Used to decide\nwhether the cached tier is still valid, and shown to nobody.",
"items": {
"type": "string"
},
"type": "array"
},
"clean": {
"description": "Whether nothing at all is staged, modified, untracked or conflicted.",
"type": "boolean"
},
"conflicted": {
"description": "Files with an unresolved merge.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"detached": {
"description": "Whether HEAD names a commit directly rather than a branch.",
"type": "boolean"
},
"head": {
"description": "The commit HEAD names, or `None` in a repository with no commits yet.",
"type": [
"string",
"null"
]
},
"modified": {
"description": "Tracked files changed in the work tree and not staged.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"staged": {
"description": "Tracked files with staged changes.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"untracked": {
"description": "Files git does not track and is not ignoring.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"upstream": {
"description": "The upstream the branch tracks, when it tracks one.",
"type": [
"string",
"null"
]
}
},
"required": [
"detached",
"staged",
"modified",
"untracked",
"conflicted",
"clean"
],
"type": "object"
},
"KindCount": {
"description": "How many valid objects of one kind the layer holds.",
"properties": {
"count": {
"description": "How many objects of it the index holds.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"kind": {
"description": "The kind, as `share/kinds.yaml` declares it.",
"type": "string"
}
},
"required": [
"kind",
"count"
],
"type": "object"
},
"LayerSummary": {
"description": "What the layer holds, counted per kind, plus the registry the executable composes.\nEvery number here comes from the index — the same objects every other surface serves —\nand never from counting files that match a pattern: a file that does not parse is not\na rule, and a count that says otherwise is a lie a person acts on.",
"properties": {
"capabilities": {
"description": "How many capabilities the registry holds.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"degraded": {
"description": "Whether the layer read cleanly.",
"type": [
"boolean",
"null"
]
},
"invalid": {
"description": "How many files the layer declared that did not become objects.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"kinds": {
"description": "One entry per kind present, sorted by kind.",
"items": {
"$ref": "#/$defs/KindCount"
},
"type": "array"
},
"objects": {
"description": "How many objects the index holds.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"state": {
"$ref": "#/$defs/TierState",
"description": "Where these numbers came from."
}
},
"required": [
"state"
],
"type": "object"
},
"ProjectIdentity": {
"description": "What the project is, from the crate manifest and the prose written once in\n[`crate::about`]. Every field here is a compile-time constant of this executable: there\nis no file to read, nothing to parse, and nothing that can disagree with the binary\nthat answers.",
"properties": {
"commit": {
"description": "The commit it was built from, or `unknown` outside a work tree.",
"type": "string"
},
"license": {
"description": "The SPDX licence identifier.",
"type": "string"
},
"name": {
"description": "The product name.",
"type": "string"
},
"profile": {
"description": "The cargo profile it was built with.",
"type": "string"
},
"repository": {
"description": "The source repository.",
"type": "string"
},
"summary": {
"description": "One sentence: what this is.",
"type": "string"
},
"target": {
"description": "The Rust target triple this executable was built for.",
"type": "string"
},
"version": {
"description": "The version of this executable, from the crate manifest.",
"type": "string"
}
},
"required": [
"name",
"version",
"summary",
"license",
"repository",
"target",
"profile",
"commit"
],
"type": "object"
},
"ProjectionState": {
"description": "Where one provider projection stands against its policy.",
"oneOf": [
{
"const": "current",
"description": "The file matches the rendering byte for byte.",
"type": "string"
},
{
"const": "stale",
"description": "The file differs: it was hand-edited, or the policy moved under it.",
"type": "string"
},
{
"const": "absent",
"description": "The file is not there.",
"type": "string"
},
{
"const": "unknown",
"description": "It could not be rendered, so nothing can be said.",
"type": "string"
}
]
},
"ProviderState": {
"description": "One provider projection the policy declares, and whether the file on disk still matches\nwhat the policy renders.",
"properties": {
"always_loaded": {
"description": "Whether the provider loads this file into every context.",
"type": "boolean"
},
"id": {
"description": "The provider id, as the policy names it: `agents`, `claude-code`.",
"type": "string"
},
"state": {
"$ref": "#/$defs/ProjectionState",
"description": "Whether the file matches what the policy renders now."
},
"target": {
"description": "The repository-relative file it renders to.",
"type": "string"
}
},
"required": [
"id",
"target",
"state",
"always_loaded"
],
"type": "object"
},
"RepositoryIdentity": {
"description": "The checkout this snapshot is of.",
"properties": {
"layer_schema": {
"description": "The manifest's `schema`, `ai-repository/v1`.",
"type": "string"
},
"linked_worktree": {
"description": "Whether this checkout is a linked work tree rather than the main one.",
"type": "boolean"
},
"local_path": {
"description": "The checkout-local half of the layer, repository-relative. Never tracked, and\nwhere anything this checkout alone knows — the server's lease, this snapshot's\ncache — is kept.",
"type": "string"
},
"name": {
"description": "The name a person calls it: the base name of the root directory.",
"type": "string"
},
"root": {
"description": "The root, absolute. The same value `repository.info` reports.",
"type": "string"
},
"sections": {
"additionalProperties": {
"type": "string"
},
"description": "Section name to repository-relative path, as the manifest declares them.",
"type": "object"
}
},
"required": [
"name",
"root",
"layer_schema",
"sections",
"local_path",
"linked_worktree"
],
"type": "object"
},
"Resolution": {
"description": "How completely a snapshot was resolved. Carried in the snapshot because a consumer must\nbe able to tell \"there is no server running\" from \"nobody looked\".",
"oneOf": [
{
"const": "fast",
"description": "Only what is cheap enough for a shell prompt; the rest from the cache.",
"type": "string"
},
{
"const": "full",
"description": "Everything, including the index. Writes the cache.",
"type": "string"
}
]
},
"ServiceAvailability": {
"description": "Whether a service answers. `Unknown` is a real answer and never a disguised `no`: a\nprobe that timed out and a port that refused the connection lead a reader to different\nactions.",
"oneOf": [
{
"const": "available",
"description": "The address accepted a connection.",
"type": "string"
},
{
"const": "not_running",
"description": "No server holds the repository's lease, or the address refused the connection.",
"type": "string"
},
{
"const": "unknown",
"description": "The probe did not finish in its budget, or this resolution did not probe.",
"type": "string"
}
]
},
"ServiceState": {
"description": "One local service of this repository: what it is, where it is, and whether anything\nanswers there. The path is the one the router serves; the URL exists only while a\nserver does.",
"properties": {
"availability": {
"$ref": "#/$defs/ServiceAvailability",
"description": "Whether anything answers there."
},
"id": {
"description": "A stable id, `[a-z][a-z0-9-]*`.",
"type": "string"
},
"path": {
"description": "The absolute path the router serves it under.",
"type": "string"
},
"title": {
"description": "The short name a person reads.",
"type": "string"
},
"url": {
"description": "The full URL, when a server is running and published its address.",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"title",
"path",
"availability"
],
"type": "object"
},
"Severity": {
"description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither.",
"oneOf": [
{
"const": "info",
"description": "Worth knowing; changes nothing.",
"type": "string"
},
{
"const": "warning",
"description": "Something to look at; the object is still served.",
"type": "string"
},
{
"const": "error",
"description": "The file is excluded and the index is degraded.",
"type": "string"
}
]
},
"TierState": {
"description": "Where a tier of the snapshot came from. A tier the active resolution cannot reach is\n[`TierState::Unavailable`] with the reason, and its values are absent rather than zero.",
"oneOf": [
{
"const": "resolved",
"description": "Read from its canonical source during this resolution.",
"type": "string"
},
{
"const": "cached",
"description": "Taken from the cache written by an earlier full resolution.",
"type": "string"
},
{
"const": "unavailable",
"description": "Neither available; the values are absent and the reason is a diagnostic.",
"type": "string"
}
]
},
"ToolchainAvailability": {
"description": "Whether a declared toolchain is usable here.",
"oneOf": [
{
"const": "installed",
"description": "Installed, and its version answered.",
"type": "string"
},
{
"const": "missing",
"description": "The executable is not on the path.",
"type": "string"
},
{
"const": "unknown",
"description": "Nobody asked: this resolution may not run a subprocess for it, and no cache held it.",
"type": "string"
}
]
},
"ToolchainState": {
"description": "A toolchain the repository declares, and what is installed for it. The three are kept\napart on purpose: a repository can declare a version nobody has, and a machine can have\na version no repository asked for, and reporting either as the other is how a version\nmismatch stays invisible for a week.",
"properties": {
"availability": {
"$ref": "#/$defs/ToolchainAvailability",
"description": "Where the installed version stands."
},
"declared": {
"description": "The version the repository declares, when it declares one.",
"type": [
"string",
"null"
]
},
"declared_by": {
"description": "The repository-relative file that declares it.",
"type": "string"
},
"id": {
"description": "A stable id, `[a-z][a-z0-9-]*`: `rust`, `node`.",
"type": "string"
},
"installed": {
"description": "The version installed here, when it could be asked and the answer is not stale.",
"type": [
"string",
"null"
]
},
"title": {
"description": "The short name a person reads.",
"type": "string"
}
},
"required": [
"id",
"title",
"declared_by",
"availability"
],
"type": "object"
},
"VcsState": {
"description": "What version control says about the checkout, or why it could not be asked.",
"oneOf": [
{
"$ref": "#/$defs/GitWorkingTree",
"description": "`git` answered.",
"properties": {
"state": {
"const": "git",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"description": "`git` could not be asked, or this is not a work tree.",
"properties": {
"reason": {
"description": "What went wrong.",
"type": "string"
},
"state": {
"const": "unavailable",
"type": "string"
}
},
"required": [
"state",
"reason"
],
"type": "object"
}
]
},
"WorkflowCatalogue": {
"description": "The workflows a person can run here, as the workflow runner itself describes them.",
"properties": {
"entrypoints": {
"description": "The entry point of each group, in the order the groups are declared: what a person\nnew to the repository runs first. Derived, never listed anywhere.",
"items": {
"$ref": "#/$defs/WorkflowEntrypoint"
},
"type": "array"
},
"source": {
"description": "The command that produced them, when one did.",
"type": [
"string",
"null"
]
},
"state": {
"$ref": "#/$defs/TierState",
"description": "Where these came from."
},
"workflows": {
"description": "Every public workflow, sorted by name.",
"items": {
"$ref": "#/$defs/WorkflowDescriptor"
},
"type": "array"
}
},
"required": [
"state"
],
"type": "object"
},
"WorkflowDescriptor": {
"description": "One workflow: a recipe of the repository's `justfile`, as `just` describes it.",
"properties": {
"confirm": {
"description": "Whether it asks before it runs (`[confirm]`).",
"type": "boolean"
},
"dependencies": {
"description": "The recipes it runs first, in order.",
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"description": "The recipe's doc comment, when it has one.",
"type": [
"string",
"null"
]
},
"group": {
"description": "The `[group(...)]` it belongs to, when it declares one.",
"type": [
"string",
"null"
]
},
"name": {
"description": "The name a person types after `just`.",
"type": "string"
},
"namespace": {
"description": "The module path, for a recipe in an imported module; empty at the root.",
"type": [
"string",
"null"
]
},
"parameters": {
"description": "Its parameters, in declaration order.",
"items": {
"$ref": "#/$defs/WorkflowParameter"
},
"type": "array"
}
},
"required": [
"name",
"confirm"
],
"type": "object"
},
"WorkflowEntrypoint": {
"description": "The entry point of one group of workflows: what the group is, and the one workflow that\nstands for it.",
"properties": {
"command": {
"description": "The command a person types.",
"type": "string"
},
"description": {
"description": "The workflow's description, when it has one.",
"type": [
"string",
"null"
]
},
"group": {
"description": "The group, as the justfile declares it.",
"type": "string"
},
"workflow": {
"description": "The workflow that stands for the group.",
"type": "string"
}
},
"required": [
"group",
"workflow",
"command"
],
"type": "object"
},
"WorkflowParameter": {
"description": "One parameter of a workflow.",
"properties": {
"name": {
"description": "The name.",
"type": "string"
},
"required": {
"description": "Whether it must be given.",
"type": "boolean"
},
"variadic": {
"description": "Whether it may be repeated (`*args`, `+args`).",
"type": "boolean"
}
},
"required": [
"name",
"variadic",
"required"
],
"type": "object"
}
},
"description": "The snapshot: what this checkout is, right now.\n\nEvery surface that reports any of this renders this value. Collections are in a\ndocumented, stable order — kinds and workflows by name, services and providers in the\norder their canonical source declares them, diagnostics in the order they were found —\nso that two snapshots of the same repository serialise identically apart from\n[`RepositoryEnvironment::generated_at`].",
"properties": {
"diagnostics": {
"description": "Everything that went wrong or is worth knowing, in the order it was found.",
"items": {
"$ref": "#/$defs/Diagnostic"
},
"type": "array"
},
"generated_at": {
"description": "When it was taken, RFC 3339 in UTC.",
"type": "string"
},
"layer": {
"$ref": "#/$defs/LayerSummary",
"description": "What the layer holds."
},
"project": {
"$ref": "#/$defs/ProjectIdentity",
"description": "What the project is."
},
"provenance": {
"description": "Where every field came from.",
"items": {
"$ref": "#/$defs/FieldSource"
},
"type": "array"
},
"providers": {
"description": "The provider projections the policy declares, in the policy's order.",
"items": {
"$ref": "#/$defs/ProviderState"
},
"type": "array"
},
"repository": {
"$ref": "#/$defs/RepositoryIdentity",
"description": "What the checkout is."
},
"resolution": {
"$ref": "#/$defs/Resolution",
"description": "How completely it was resolved."
},
"schema": {
"description": "The contract this document follows, `majordomus/repository-environment/v1`.",
"type": "string"
},
"services": {
"description": "The local services, in the order the service table declares them.",
"items": {
"$ref": "#/$defs/ServiceState"
},
"type": "array"
},
"toolchains": {
"description": "The toolchains the repository declares, sorted by id.",
"items": {
"$ref": "#/$defs/ToolchainState"
},
"type": "array"
},
"vcs": {
"$ref": "#/$defs/VcsState",
"description": "What version control says."
},
"workflows": {
"$ref": "#/$defs/WorkflowCatalogue",
"description": "The workflows a person can run."
}
},
"required": [
"schema",
"generated_at",
"resolution",
"project",
"repository",
"vcs",
"toolchains",
"layer",
"workflows",
"providers",
"services",
"diagnostics",
"provenance"
],
"title": "RepositoryEnvironment",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- process — up to 4 entries in the process, 3s each, scoped by the registry fingerprint
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.