HTTP API: intent_realization

Which work realises which intent: every task of this checkout's ledger with the episodes, providers and handovers that carried it, every closed session record and every claim on the peer board, joined through the plan to the intents they serve, each link marked declared, observed, derived or inferred; each intent's unmet criteria with the issues serving them; and the drift between closed work and current evidence. Derived on every read and stored nowhere, so an intent outlives every session and provider that worked on it.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

intent_realization

GET /api/v1/intents/explain intent_realization.explain

Why an intent stands where it stands

One intent explained from the derivations alone: a sentence for its stage naming each milestone's derived status, a sentence per criterion naming its evidence state, the plan's coverage of it and the command that reproduces it, a sentence for the work and providers realising it, and each drift finding; beside them the derived intent, the coverage of its criteria, its realization and the work linked to it.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_intent_explain
$ intent explain

Query parameters

name	type	required	description	examples
id	string	yes	The intent's id.	first-intent: "a-session-leaves-what-it-observed"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/intents/explain?id=a-session-leaves-what-it-observed"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntentExplanation	Why an intent stands where it stands: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/intents/realization intent_realization.work

Which work realises which intent, and what each still lacks

Every unit of work this checkout can see — ledger tasks with their episodes, providers and handovers, closed session records, peer claims — with every intent it realises through issue, milestone and criterion, each link's provenance (declared: the work cites the issue; observed: its episode moved the issue; derived: its branch names the issue; inferred: only an open issue's scope overlaps) or the first missing link; every intent with its unmet criteria and the issues serving each, the work and providers realising it, and its drift: closed_work_contradicted when every milestone is DONE and a criterion's evidence is stale or failing, closed_work_unproven when it never existed, criterion_closed_unmet when every serving issue is DONE and the criterion is not met; and where the stage and the verdict disagree (ADR 0107), evidence_ahead_of_plan when the verdict is satisfied while the stage is planned or executing, closed_work_not_satisfied when every milestone is DONE and the verdict is unsatisfied or unknown. Live work serving no intent is a warning.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_intent_realization
$ intent realization

Query parameters

name	type	required	description	examples
intent	string	no	An intent id. When given, only that intent, the work linked to it and its findings are answered; the unlinked work is left out.	first-intent: "a-session-leaves-what-it-observed"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/intents/realization?intent=a-session-leaves-what-it-observed"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntentRealization	Which work realises which intent, and what each still lacks: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

IntentEpisode

object

One execution episode of a piece of work, and the provider that ran it when a record says. A provider is never guessed: an episode opened by hand has none.

use majordomus_cli::intent_realization::IntentEpisode;
let e = IntentEpisode {
    session: "s-1".into(),
    provider: "codex".into(),
    provider_session: String::new(),
};
assert_eq!(e.provider, "codex");

property	type	required	description
session	string	no	The episode id, `s-...`; empty for a peer's connection, which is not an episode.
provider	string	no	The provider, as its own events or the peer's client name it; empty when unknown.
provider_session	string	no	The provider's own session identity, when recorded.

Used by IntentWorkUnit

IntentExplanation

object

Why an intent stands where it stands: the record, each sentence that explains the stage and each criterion, the plan's coverage of its criteria, and the work realising it.

use majordomus_cli::intent_realization::IntentExplanation;
// every sentence is derived; an explanation holds no authored status
let fields = serde_json::to_value(schemars::schema_for!(IntentExplanation)).unwrap();
assert!(fields["properties"]["because"].is_object());

property	type	required	description
intent	IntentView → IntentView	yes	The intent, derived.
because	array of string	yes	One sentence per fact the stage rests on: the stage, each criterion, the work.
coverage	array of CriterionCoverage → CriterionCoverage	yes	The plan's coverage of each of its criteria.
realization	IntentRealizationView → IntentRealizationView	yes	Its realization.
work	array of IntentRealizedWork → IntentRealizedWork	yes	Every unit of work linked to it, with its links.

Used by intent_realization.explain

IntentLink

object

One link from a piece of work to an intent: through which issue and milestone, serving which of its criteria, read from which fact, known how.

use majordomus_cli::intent::IntentStage;
use majordomus_cli::intent_realization::{IntentLink, IntentLinkProvenance, IntentLinkVia};
let l = IntentLink {
    intent: "intent-lifecycle".into(), stage: IntentStage::Executing,
    milestone: "intent-lifecycle".into(), issue: "I1900".into(),
    criteria: vec!["stage-is-derived".into()],
    via: IntentLinkVia::BranchIssue, provenance: IntentLinkProvenance::Derived,
};
assert_eq!(l.provenance, l.via.provenance());

property	type	required	description
intent	string	yes	The intent.
stage	IntentStage → IntentStage	yes	Its derived stage.
milestone	string	yes	The milestone that links the issue to it.
issue	string	yes	The issue that links the work to that milestone.
criteria	array of string	no	The criteria of this intent the issue declares it serves; empty when it declares none.
via	IntentLinkVia → IntentLinkVia	yes	The fact the link was read from.
provenance	IntentLinkProvenance → IntentLinkProvenance	yes	How the link is known, from `via`.

Used by IntentRealizedWork

IntentLinkProvenance

"declared" | "observed" | "derived" | "inferred"

How a link from a piece of work to an issue is known, strongest first.

use majordomus_cli::intent_realization::IntentLinkProvenance;
assert_eq!(
    serde_json::to_string(&IntentLinkProvenance::Inferred).unwrap(),
    "\"inferred\""
);
assert!(IntentLinkProvenance::Observed < IntentLinkProvenance::Derived);

declaredThe work names the issue itself.
observedA recorded event shows the work's episode moving the issue.
derivedThe branch the work ran on names the issue, by the worktree naming rule.
inferredNothing stronger exists, and an open issue's scope overlaps the work's scope.

Used by IntentLink IntentWorkRef

IntentLinkVia

"named_issue" | "moved_issue" | "branch_issue" | "scope_overlap"

The fact a link was read from.

use majordomus_cli::intent_realization::IntentLinkVia;
assert_eq!(serde_json::to_string(&IntentLinkVia::BranchIssue).unwrap(), "\"branch_issue\"");
assert_eq!(IntentLinkVia::ScopeOverlap.provenance().as_str(), "inferred");

named_issueThe claim or the task's own words cite the issue by id.
moved_issueA plan transition in the work's episode, or the session record's issues.
branch_issueThe branch name carries the issue id.
scope_overlapAn open issue's scope overlaps the work's scope.

Used by IntentLink

IntentRealization

object

Every intent, realised, and every unit of work, joined: what majordomus intent realization answers.

use majordomus_cli::intent_realization::IntentRealization;
let r = IntentRealization { intents: vec![], work: vec![], orphans: 0, findings: vec![] };
assert_eq!(r.orphans, 0);

property	type	required	description
intents	array of IntentRealizationView → IntentRealizationView	yes	Every intent, in identity order.
work	array of IntentRealizedWork → IntentRealizedWork	yes	Every unit of work read, with its links.
orphans	integer (uint)	yes	How many units of work realise no intent.
findings	array of IntentFinding → IntentFinding	yes	Every finding: each intent's drift, then the live work that serves no intent.

Used by intent_realization.work

IntentRealizationView

object

One intent, realised: how far reality is from it, the work realising it and by whom, and the drift between closed work and current evidence.

use majordomus_cli::intent::IntentStage;
use majordomus_cli::intent_realization::IntentRealizationView;
let v = IntentRealizationView {
    intent: "x".into(), title: "X".into(), stage: IntentStage::Verifying,
    criteria: 2, met: 1, unmet: vec![], work: vec![], providers: vec![], findings: vec![],
};
assert!(v.met < v.criteria);

property	type	required	description
intent	string	yes	The intent.
title	string	yes	Its title.
stage	IntentStage → IntentStage	yes	Its derived stage.
criteria	integer (uint)	yes	How many criteria it declares.
met	integer (uint)	yes	How many have current evidence.
unmet	array of IntentUnmetCriterion → IntentUnmetCriterion	yes	Every criterion without current evidence.
work	array of IntentWorkRef → IntentWorkRef	yes	Every unit of work linked to it, strongest link first.
providers	array of string	yes	Every provider that ran work linked to it, each once.
findings	array of IntentFinding → IntentFinding	yes	Drift between the plan's closure and the evidence.

Used by IntentExplanation IntentRealization

IntentRealizedWork

object

A unit of work with every intent it realises, or the reason it realises none.

use majordomus_cli::intent_realization::{IntentRealizedWork, IntentWorkKind, IntentWorkUnit};
let w = IntentRealizedWork {
    work: IntentWorkUnit::new(IntentWorkKind::Task, "t-1"),
    links: vec![],
    unlinked: Some("it names no issue".into()),
};
assert!(w.links.is_empty() && w.unlinked.is_some());

property	type	required	description
work	IntentWorkUnit → IntentWorkUnit	yes	The work, as recorded.
links	array of IntentLink → IntentLink	yes	Every intent it realises, strongest link per issue.
unlinked	string \| null	no	When it realises none: the first link that is missing.

Used by IntentExplanation IntentRealization

IntentUnmetCriterion

object

A criterion an intent still lacks, with the issues that declare they serve it.

use majordomus_cli::intent::IntentEvidenceState;
use majordomus_cli::intent_realization::IntentUnmetCriterion;
let c = IntentUnmetCriterion {
    id: "surfaces-agree".into(), criterion: "the surfaces agree".into(),
    evidence: "test".into(), state: IntentEvidenceState::Stale,
    reproduce: None, issues: vec!["I1900".into()],
};
assert_eq!(c.state, IntentEvidenceState::Stale);

property	type	required	description
id	string	yes	The criterion id.
criterion	string	yes	What must be observably true.
evidence	string	yes	The kind of evidence that settles it.
state	IntentEvidenceState → IntentEvidenceState	yes	Why it is not met.
reproduce	string \| null	no	The command that produces its evidence, when one is known.
issues	array of string	no	The issues declaring they serve it, in plan order.

Used by IntentRealizationView

IntentWorkKind

"task" | "peer_claim" | "session_record"

Which record a unit of work was read from.

use majordomus_cli::intent_realization::IntentWorkKind;
assert_eq!(serde_json::to_string(&IntentWorkKind::PeerClaim).unwrap(), "\"peer_claim\"");

taskA task of this checkout's ledger: the durable unit a handover continues, across every episode that worked on it.
peer_claimA claim a peer announced on the shared server's board.
session_recordA closed session record of the shared layer whose episode this checkout's ledger does not hold — another machine's or another checkout's work.

Used by IntentWorkRef IntentWorkUnit

IntentWorkRef

object

A unit of work as one intent sees it: which record, how it stands, and the strongest link.

use majordomus_cli::intent_realization::{IntentLinkProvenance, IntentWorkKind, IntentWorkRef};
let r = IntentWorkRef {
    kind: IntentWorkKind::Task, id: "t-1".into(), outcome: "active".into(),
    provenance: IntentLinkProvenance::Observed, providers: vec!["codex".into()],
    handovers: 1,
};
assert_eq!(r.handovers, 1);

property	type	required	description
kind	IntentWorkKind → IntentWorkKind	yes	Which record.
id	string	yes	Its identity there.
outcome	string	no	Where it stands.
provenance	IntentLinkProvenance → IntentLinkProvenance	yes	The strongest of its links to this intent.
providers	array of string	no	The providers that ran it.
handovers	integer (uint)	yes	How many handovers carried it.

Used by IntentRealizationView

IntentWorkUnit

object

One unit of work as its records describe it, before it is joined to any intent.

use majordomus_cli::intent_realization::{IntentWorkKind, IntentWorkUnit};
let unit = IntentWorkUnit::new(IntentWorkKind::Task, "t-1");
assert!(unit.episodes.is_empty());
assert_eq!(unit.id, "t-1");

property	type	required	description
kind	IntentWorkKind → IntentWorkKind	yes	Which record it was read from.
id	string	yes	Its identity in that record: a task id, a session id, or `<peer>/<claim>`.
title	string	no	What it says it is, in its own words.
outcome	string	no	Where it stands: a task's outcome, a session's, or `attached`/`departed` for a claim.
branches	array of string	no	The branches it ran on, in first-seen order.
scope	array of string	no	The paths it claims.
episodes	array of IntentEpisode → IntentEpisode	no	Every episode that worked on it, in first-seen order.
handovers	array of string	no	The handovers that carried it from one episode to the next, repository-relative.
named_issues	array of string	no	Issue ids its own words cite.
moved_issues	array of string	no	Issue ids a recorded event shows it moving.

Used by IntentRealizedWork