HTTP API: release

The exemption a decision applied, by class.

use majordomus_cli::release::landing::AppliedExemption;
let e = AppliedExemption { id: "plan-records".into(), reason: "plan records".into() };
assert_eq!(e.id, "plan-records");

What a landing allocates, and why, step by step.

use majordomus_cli::release::compat::Impact;
use majordomus_cli::release::landing::{decide, LandingDecision, ReleasePolicy, DECISION_SCHEMA};
use majordomus_cli::release::version::Version;
let d: LandingDecision = decide(Version::parse("1.2.3").unwrap(), Impact::None, &ReleasePolicy::default(), &[]);
assert_eq!(d.schema, DECISION_SCHEMA);
assert_eq!(d.next_version, "1.2.3", "nothing moved and nothing is owed");

Whether the integration executor allocates the version when it lands a pull request.

use majordomus_cli::release::landing::Allocation;
// a policy that says nothing changes nothing: a pull request raises its own version
assert_eq!(Allocation::default(), Allocation::Off);
let a: Allocation = serde_json::from_str("\"landing\"").unwrap();
assert_eq!(a.as_str(), "landing");

The release this tree is measured against, and how it was found.

use majordomus_cli::release::compat::Baseline;
let baseline = Baseline {
    version: "0.5.0".into(),
    reference: "v0.5.0".into(),
    read_at: "3a032c1e033b".into(),
    commit: "3a032c1e033b".into(),
    recorded: true,
    atoms: 300,
    fingerprint: "sha256:…".into(),
};
// `recorded` is the half that matters: a baseline taken from a tag alone is reported.
assert!(baseline.recorded);
assert_eq!(baseline.reference, "v0.5.0");

One change, from one commit.

Whether a change added, removed or altered part of the contract.

use majordomus_cli::release::compat::Direction;
assert_eq!(Direction::Removed.sign(), '-');

The changes of one kind, with the heading and the rank that decide where they are shown.

The grouping is in the document rather than in each renderer. It was in the Markdown renderer alone, and the site — which cannot see a Rust function — grouped alphabetically instead, so the same changelog read in two orders depending on which surface showed it. A presentation order stated once and carried is the only kind that survives a projection.

The whole changelog.

One published artifact, from the release record's own evidence.

What the commit subjects since the baseline said about themselves.

Evidence, never authority. It is here so that a person can see the human account and the measured one side by side, and so that VersionPlan::understated can say when the two disagree — which is the case this whole subsystem exists to catch.

use majordomus_cli::release::compat::{CommitEvidence, Impact};
let commits = CommitEvidence {
    commits: 24,
    implied: Impact::Patch,
    breaking: Vec::new(),
};
// The contract moved by a minor and the subjects claim a patch: the plan reports that
// disagreement rather than deferring to the words.
assert!(commits.implied < Impact::Minor);

One decision, as the layer's own ADR object states it.

Something about the release state that a person should be told, whatever the verdict.

use majordomus_cli::release::compat::{Diagnostic, Severity};
let d = Diagnostic {
    id: "tag-without-record".into(),
    severity: Severity::Warning,
    message: "v0.1.0 is tagged and the layer holds no release record for it".into(),
};
assert_eq!(d.severity, Severity::Warning, "a warning states the plan still stands");

How much a change moves the contract.

Ordered, so that "the declared bump covers what is required" is a comparison rather than a table:

use majordomus_cli::release::compat::Impact;
assert!(Impact::Major > Impact::Minor);
assert!(Impact::Minor > Impact::Patch);
assert!(Impact::Patch > Impact::None);

The compatibility policy, named and versioned.

use majordomus_cli::release::compat::{Impact, Policy, POLICY_SCHEMA};
use majordomus_cli::release::version::Version;
let policy = Policy::for_version(Version::parse("0.5.0").unwrap());
assert_eq!(policy.schema, POLICY_SCHEMA, "a verdict carries the rules it was reached under");
assert_eq!(policy.required_of(Impact::Major), Impact::Minor);

How this project turns a measured impact into the version it owes.

Semantic versioning hands 0.y.z a blanket exemption — "anything MAY change at any time" — and Elm refuses the exemption by starting every package at 1.0.0, because a rule with an escape hatch is a rule about when to use the hatch. This repository is 0.x and has not earned 1.0.0, so neither answer is available: demanding major would demand 1.0.0 for a single removal, and granting the exemption would let a breaking change ship as a patch.

So below 1.0.0 the floor is a minor. Any movement of the surface, gone or new, is at least a minor release; only an unchanged surface owes nothing. That is the strongest signal 0.x has, and a removal is still named as breaking whatever the verdict, so the evidence does not quietly become a minor along with the number.

At 1.0.0 the shift ends: Mode::Semver is the ordinary rule, and the transition is one line of Policy::required_of.

use majordomus_cli::release::compat::{Mode, Policy};
use majordomus_cli::release::version::Version;
assert_eq!(Policy::for_version(Version::parse("0.9.0").unwrap()).mode, Mode::Pre1_0Strict);
assert_eq!(Policy::for_version(Version::parse("1.0.0").unwrap()).mode, Mode::Semver);

Which capability answered with this document, and where that capability is projected.

The document carries its own provenance so that a reader — a person on the site, a client over MCP — can find the same value elsewhere without anything having to enumerate the routes. A page that listed them would be declaring them a second time, which is the failure site-check's registry and cli assertions exist to catch; it caught this one.

use majordomus_cli::release::model::ProducedBy;
let by = ProducedBy {
    capability: "release.changelog".into(),
    cli: Some("majordomus release changelog".into()),
    http: Some("/api/v1/changelog".into()),
    mcp_tool: None,
    mcp_resource: Some("majordomus://changelog".into()),
};
let json = serde_json::to_value(&by).unwrap();
assert_eq!(json["capability"], "release.changelog");
// a surface the capability is not projected on is absent, not null
assert!(json.get("mcp_tool").is_none());
assert_eq!(ProducedBy::default().capability, "");

A record of the layer that a commit names in its own text.

Inferred, never declared beside the commit: an issue id or a milestone id appearing in a subject or a body is a reference, and the layer already holds the object it refers to. A reference to something the layer does not have is not carried — a link to a record that does not exist is worse than no link, because the reader cannot tell until they follow it.

use majordomus_cli::release::model::Reference;
let r = Reference {
    kind: "issue".into(),
    id: "I1305".into(),
    title: "An observed contract has a fingerprint".into(),
    route: Some("/plan/i1305/".into()),
};
let json = serde_json::to_value(&r).unwrap();
assert_eq!(json["id"], "I1305");
assert_eq!(json["route"], "/plan/i1305/");
// a reference the site has no page for carries no route rather than an invented one
let bare = Reference { route: None, ..r };
assert!(serde_json::to_value(&bare).unwrap().get("route").is_none());

One version's worth of changelog.

How much a diagnostic matters.

An error says the plan itself cannot be trusted and blocks the verdict; a warning says something about the release state is wrong and the verdict stands anyway; a note says something true and not wrong, so that the warnings keep meaning what they say.

use majordomus_cli::release::compat::Severity;
assert_ne!(Severity::Error, Severity::Warning);
assert_ne!(Severity::Warning, Severity::Note);

Whether the tree may land or ship as it stands.

use majordomus_cli::release::compat::Status;
assert_ne!(Status::Ok, Status::Blocked);

One movement of the public contract, with the reason it counts for what it does.

use majordomus_cli::release::compat::{Direction, Impact, SurfaceChange, SurfaceKind};
let change = SurfaceChange {
    impact: Impact::Major,
    direction: Direction::Removed,
    surface: SurfaceKind::Http,
    capability: "alpha.list".into(),
    id: "GET /api/v1/alpha".into(),
    detail: "the capability survives; this way of reaching it does not".into(),
};
assert_eq!(change.to_string(), "- route GET /api/v1/alpha");

Which projection of the contract a change is in.

Not where it was found — everything here is found in the registry — but which promise it is, so that a reader sees "a route is gone" rather than a JSON pointer.

use majordomus_cli::release::compat::SurfaceKind;
assert_eq!(SurfaceKind::Http.as_str(), "route");

Who answered a version report's next: the public contract, the contract with the commits — or no one, because the contract could not be measured.

ADR 0051 makes the contract the authority and demotes conventional commits to evidence, so DecidedBy::Contract is the normal answer. An unmeasurable contract is refused, not guessed: DecidedBy::Undecided leaves next absent and carries the reason, and the commit inference stays what it always is, evidence — never the answer in its place.

use majordomus_cli::release::model::DecidedBy;
assert_eq!(serde_json::to_value(DecidedBy::Contract).unwrap(), "contract");
assert_eq!(DecidedBy::Undecided.as_str(), "undecided");
assert_eq!(DecidedBy::default(), DecidedBy::Undecided);

The whole answer: what moved, what that requires, and what the tree declares.

One value, and every surface renders it — the command line, /api/v1/release/analysis, the MCP tool, the Cockpit panel, the generated document and the CI gate. There is no second computation anywhere, which is the property that makes the number mean something.

use majordomus_cli::release::compat::{Status, VersionPlan};
#### use majordomus_cli::release::compat::{Baseline, CommitEvidence, Impact, Policy};
#### use majordomus_cli::release::version::Version;
let plan = VersionPlan {
    policy: Policy::for_version(Version::parse("0.5.0").unwrap()),
    baseline: Baseline {
        version: "0.5.0".into(), reference: "v0.5.0".into(), read_at: "3a032c1e".into(),
        commit: "3a032c1e".into(), recorded: true, atoms: 300, fingerprint: "sha256:a".into(),
    },
    declared_version: "0.5.0".into(),
    tool_version: "0.5.0".into(),
    writers_agree: true,
    atoms: 333,
    fingerprint: "sha256:b".into(),
    implied: Impact::Minor,
    required: Impact::Minor,
    declared: Impact::None,
    required_version: "0.6.0".into(),
    status: Status::Blocked,
    breaking: false,
    changes: Vec::new(),
    commits: CommitEvidence { commits: 24, implied: Impact::Patch, breaking: Vec::new() },
    understated: true,
    diagnostics: Vec::new(),
};
// The contract requires a minor and the version declares none: this tree may not land.
assert_eq!(plan.status, Status::Blocked);
assert!(plan.declared < plan.required);
assert!(plan.understated, "the commit subjects claim less than the contract did");

What the version is, what the public contract requires it to become, and what the commits since the last release say about themselves.

next is the contract's answer (ADR 0051): the analysis' required_version, or the smallest release above the last when that requirement is the last release itself. The commit inference is evidence — bump and commits_imply — and never the answer: when the contract cannot be measured next is absent, decided_by is undecided and contract_unreadable says why. The selection is crate::release::version::select, the one function release bump also takes its default target from.