HTTP API: reasoning

One advisory capability and who can provide it now: a row of the capacity table reasoning.advisors reports. An empty available is answered by the local review.

use majordomus_cli::capability::builtin::reasoning::AdvisorCapacity;

let row: AdvisorCapacity = serde_json::from_value(serde_json::json!({
    "capability": "code_review", "description": "Critique of a change.", "available": [],
})).unwrap();
assert_eq!(row.capability, "code_review");
assert!(row.available.is_empty());

An open circuit: the consultation that opened it, the failures behind it, and when it closes. Derived from the records and the clock, never stored.

use majordomus_cli::reasoning::availability::*;
use majordomus_cli::reasoning::catalogue::{AdvisorCatalogue, References};
use majordomus_cli::reasoning::record::ConsultationStatus;

struct All;
impl Presence for All {
    fn executable(&self, _: &str) -> bool { true }
    fn variable(&self, _: &str) -> bool { true }
}
let c: AdvisorCatalogue = majordomus_cli::metadata::yaml::parse_into(
    "version: 1\ncapabilities:\n  - id: code_review\n    description: x\nadvisors:\n  - id: a\n    title: A\n    transport: cli\n    adapter: a-cli\n    executable: a\n    capabilities: [code_review]\n",
).unwrap();
let limited = [Outcome {
    id: "consultation-1".into(), advisor: "a".into(),
    status: ConsultationStatus::RateLimited, at: 0, retry_after: Some(60),
}];
let refs = References::default();
let states = derive_availability(&c, &Inputs {
    refs: &refs, presence: &All, mode: ReasoningMode::Standard, disabled: &[],
    history: &limited, peers: &[], now: 10, cooldown: None,
});
let circuit: &AdvisorCircuit = states[0].circuit.as_ref().unwrap();
assert_eq!(circuit.opened_by, "consultation-1");
assert_eq!(circuit.until, "1970-01-01T00:01:00Z");

One advisor as it stands now: what the catalogue declares of it, its status, the one machine word saying why, and what was probed. The row reasoning.advisors reports and the policy plans over.

use majordomus_cli::reasoning::availability::*;
use majordomus_cli::reasoning::catalogue::{AdvisorCatalogue, References};

struct Nothing;
impl Presence for Nothing {
    fn executable(&self, _: &str) -> bool { false }
    fn variable(&self, _: &str) -> bool { false }
}
let c: AdvisorCatalogue = majordomus_cli::metadata::yaml::parse_into(
    "version: 1\ncapabilities:\n  - id: code_review\n    description: x\nadvisors:\n  - id: a\n    title: A\n    transport: local_runtime\n    adapter: a-rt\n    executable: rt\n    capabilities: [code_review]\n",
).unwrap();
let refs = References::default();
let state: AdvisorState = derive_availability(&c, &Inputs {
    refs: &refs, presence: &Nothing, mode: ReasoningMode::Standard, disabled: &[],
    history: &[], peers: &[], now: 0, cooldown: None,
})
.remove(0);
assert_eq!((state.id.as_str(), state.status), ("a", AdvisorStatus::Unavailable));
assert_eq!(state.probe, "executable rt on PATH");
assert!(state.circuit.is_none() && !state.recovering);

An advisor's standing: whether it may be asked now and, when not, which kind of reason keeps it out. Only available advisors enter a plan.

use majordomus_cli::reasoning::availability::AdvisorStatus;

assert_eq!(serde_json::to_value(AdvisorStatus::NotConfigured).unwrap(), "not_configured");
let s: AdvisorStatus = serde_json::from_str("\"rate_limited\"").unwrap();
assert_eq!(s, AdvisorStatus::RateLimited);

How an advisor is reached. The transport decides how its presence is probed (a credential variable, an executable, a mesh link) and whether offline mode admits it.

use majordomus_cli::reasoning::catalogue::AdvisorTransport;

let t: AdvisorTransport = serde_json::from_str("\"local_runtime\"").unwrap();
assert_eq!(t, AdvisorTransport::LocalRuntime);
assert!(!t.is_remote());

Token counts an adapter reported. Absent when the transport reports none; never estimated.

The state sums these into its totals. A missing count reads as zero, so an adapter that reports only one of the two still records what it reported.

use majordomus_cli::reasoning::record::AdvisorUsage;

let u: AdvisorUsage = serde_json::from_str(r#"{"input_tokens": 120}"#).unwrap();
assert_eq!(u, AdvisorUsage { input_tokens: 120, output_tokens: 0 });

The answer of reasoning.advisors: the mode in force, how many advisors may and may not be asked, every advisor's state, the capacity per advisory capability, and the catalogue's own findings. operational is true whatever the counts.

use majordomus_cli::capability::builtin::reasoning::AdvisorsReport;

let report: AdvisorsReport = serde_json::from_value(serde_json::json!({
    "operational": true,
    "mode": { "mode": "ci", "source": "CI" },
    "available": 0, "unavailable": 0, "advisors": [], "capacity": [],
})).unwrap();
assert!(report.operational && report.advisors.is_empty());
assert_eq!(report.mode.source, "CI");
assert!(report.diagnostics.is_empty(), "absent findings are the ordinary case");

Where an assessment stands, from open through validated.

The standing is derived, never stored: an unresolved disagreement makes it disputed whatever else is recorded; otherwise its standing conclusion and that conclusion's validations decide it, and without a conclusion a recorded plan makes it planned.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, AssessmentStanding};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("assessment-1", 1, json!({ "kind": "assessment", "subject": "s" })));
assert_eq!(derive(&loaded, None).assessments[0].standing, AssessmentStanding::Open);

loaded.records.push(rec("disagreement-2", 2, json!({
    "kind": "disagreement", "assessment": "assessment-1",
    "positions": [
        { "source": "primary", "position": "A" },
        { "source": "consultation-9", "position": "B" },
    ],
    "discriminating_question": "do callers retry?",
})));
assert_eq!(derive(&loaded, None).assessments[0].standing, AssessmentStanding::Disputed);

One assessment and where it stands.

The view carries what a reader needs to pick the work up: the subject, its materiality, its derived standing, the conclusion that stands for it and the questions it left open.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::policy::Materiality;
use majordomus_cli::reasoning::state::{derive, AssessmentView};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("assessment-1", 1, json!({
    "kind": "assessment", "subject": "lock scope", "materiality": "trivial",
    "questions": ["is it held across an await?"],
})));
let state = derive(&loaded, None);
let view: &AssessmentView = &state.assessments[0];
assert_eq!((view.id.as_str(), view.task.as_str()), ("assessment-1", "t"));
assert_eq!(view.materiality, Materiality::Trivial);
assert_eq!(view.conclusion, None);
assert_eq!(view.questions, ["is it held across an await?"]);

One conclusion, as the state reports it.

Besides the decision and its computed review, the view counts the validations recorded against the conclusion and names the later conclusion that superseded it, if any. A superseded conclusion stays in the list; the report leaves it out.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, ConclusionView};
use majordomus_cli::reasoning::store::Loaded;

let conclusion = |decision: &str, supersedes: Option<&str>| {
    json!({
        "kind": "conclusion", "assessment": "assessment-0", "decision": decision,
        "rationale": "r", "supersedes": supersedes,
        "reviewed_by": [], "independent_review_count": 0,
    })
};
let mut loaded = Loaded::default();
loaded.records.push(rec("conclusion-1", 1, conclusion("A", None)));
loaded.records.push(rec("validation-2", 2, json!({
    "kind": "validation", "conclusion": "conclusion-1", "check": "x", "outcome": "fail",
})));
loaded.records.push(rec("conclusion-3", 3, conclusion("B", Some("conclusion-1"))));

let state = derive(&loaded, None);
let first: &ConclusionView = &state.conclusions[0];
assert_eq!((first.validations_passed, first.validations_failed), (0, 1));
assert_eq!(first.superseded_by.as_deref(), Some("conclusion-3"));
assert_eq!(state.conclusions[1].superseded_by, None);

How a consultation ended, as the adapter classified it.

Only a completed consultation carries advice and counts as review; every other status is a degradation that is recorded so the state can report it, never hidden. The wire form is the snake_case word that ConsultationStatus::as_str returns.

use majordomus_cli::reasoning::record::ConsultationStatus;

let s: ConsultationStatus = serde_json::from_str("\"rate_limited\"").unwrap();
assert_eq!(s, ConsultationStatus::RateLimited);
assert!(!s.is_transient());
assert!(ConsultationStatus::Timeout.is_transient());

One consultation, as the state reports it.

A failed consultation is reported as plainly as a completed one: its status and the adapter's diagnostic stand where the advice would, so degradation is visible rather than silently absent.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::record::ConsultationStatus;
use majordomus_cli::reasoning::state::{derive, ConsultationView};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("consultation-1", 1, json!({
    "kind": "consultation", "plan": "plan-0", "advisor": "alpha",
    "status": "timeout", "diagnostic": "timeout: no answer in 60s",
})));
let state = derive(&loaded, None);
let view: &ConsultationView = &state.consultations[0];
assert_eq!(view.status, ConsultationStatus::Timeout);
assert_eq!(view.conclusion, None);
assert_eq!(view.diagnostic.as_deref(), Some("timeout: no answer in 60s"));
assert_eq!(state.totals.consultations_failed, 1);

One side of a disagreement: whose position it is, and the position in one line.

The source is primary for the executor, or the id of a completed consultation; the store refuses a position sourced from a consultation that did not complete.

use majordomus_cli::reasoning::record::DisagreementPosition;

let p = DisagreementPosition { source: "primary".into(), position: "keep the lock".into() };
let json = serde_json::to_value(&p).unwrap();
assert_eq!(json, serde_json::json!({ "source": "primary", "position": "keep the lock" }));

One disagreement, as the state reports it.

The view names the question that decides the disagreement and, once a resolution is recorded, the resolution and the position its evidence favoured. A view without a resolution is an unsettled disagreement that blocks its assessment.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, DisagreementView};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("disagreement-1", 1, json!({
    "kind": "disagreement", "assessment": "assessment-0",
    "positions": [
        { "source": "primary", "position": "A" },
        { "source": "consultation-9", "position": "B" },
    ],
    "discriminating_question": "do callers retry?",
})));
loaded.records.push(rec("resolution-2", 2, json!({
    "kind": "resolution", "disagreement": "disagreement-1",
    "experiment": "read the callers", "outcome": "none retries",
    "favours": "consultation-9",
    "evidence": [{ "kind": "file", "reference": "src/caller.rs" }],
})));
let state = derive(&loaded, None);
let view: &DisagreementView = &state.disagreements[0];
assert_eq!(view.discriminating_question, "do callers retry?");
assert_eq!(view.resolution.as_deref(), Some("resolution-2"));
assert_eq!(view.favours.as_deref(), Some("consultation-9"));

One advisor left out of the plan, its standing when the plan was made, and why: its status, a capability it does not offer, or a budget already spent.

use majordomus_cli::reasoning::availability::{AdvisorState, AdvisorStatus, ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::{plan, ExcludedAdvisor, Materiality, PlanRequest};

fn advisor(id: &str, adapter: &str, status: &str) -> AdvisorState {
    serde_json::from_value(serde_json::json!({
        "id": id, "title": id, "transport": "api", "adapter": adapter,
        "capabilities": ["independent_reasoning"], "status": status,
        "reason": "present", "probe": "",
    }))
    .unwrap()
}
let mode = ModeResolution { mode: ReasoningMode::Standard, source: "default".into() };
let request = PlanRequest { materiality: Materiality::Material, ..Default::default() };
let states = [advisor("a", "x-api", "available"), advisor("b", "y-api", "available")];
let p = plan(&request, &mode, &states);
let left: &ExcludedAdvisor = &p.excluded[0];
assert_eq!((left.advisor.as_str(), left.status), ("b", AdvisorStatus::Available));
assert!(left.reason.contains("budget was spent"));

How much the uncertain decision could matter. Ordered from trivial to critical: with the mode it sets the review budget, and from material up a decision taken alone carries the structured local review.

use majordomus_cli::reasoning::policy::Materiality;

assert_eq!(Materiality::default(), Materiality::Low);
assert!(Materiality::Material < Materiality::Critical);
let m: Materiality = serde_json::from_str("\"high\"").unwrap();
assert_eq!(m, Materiality::High);

The mode in force and what decided it, as resolve_mode returns it. A plan and a report carry the source beside the mode, so a reader learns why the mode is what it is.

use majordomus_cli::reasoning::availability::{resolve_mode, ModeResolution, ReasoningMode};

let r: ModeResolution = resolve_mode(None, true, None);
assert_eq!(r, ModeResolution { mode: ReasoningMode::Ci, source: "CI".into() });

What the plan decided: consult the selected advisors, decide on local evidence, or reuse a standing conclusion. Deciding locally is an ordinary outcome, not a failure.

use majordomus_cli::reasoning::availability::{ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::{plan, Materiality, PlanOutcome, PlanRequest};

let mode = ModeResolution { mode: ReasoningMode::Ci, source: "CI".into() };
let request = PlanRequest { materiality: Materiality::Critical, ..Default::default() };
let outcome: PlanOutcome = plan(&request, &mode, &[]).outcome;
assert_eq!(outcome, PlanOutcome::DecideLocally);
assert_eq!(serde_json::to_value(outcome).unwrap(), "decide_locally");

A stored record's body: the admitted input, with whatever the writer computed.

It mirrors ReasoningInput variant for variant, except that a plan is stored as a StoredPlan and a conclusion as a StoredConclusion. Only the store produces one, by admitting an input; its JSON form is tagged by kind like the input's.

use majordomus_cli::reasoning::record::{AssessmentInput, ReasoningBody};

let body = ReasoningBody::Assessment(AssessmentInput {
    subject: "lock scope".into(),
    ..Default::default()
});
assert_eq!(body.kind(), "assessment");
assert_eq!(serde_json::to_value(&body).unwrap()["kind"], "assessment");

The answer of reasoning.check: whether it is clean, the checks performed in order, and every finding. ok is true exactly when findings is empty.

use majordomus_cli::capability::builtin::reasoning::ReasoningCheck;

let clean: ReasoningCheck = serde_json::from_value(serde_json::json!({
    "ok": true, "checks": ["catalogue"], "findings": [],
})).unwrap();
assert!(clean.ok && clean.findings.is_empty());
assert_eq!(clean.checks, ["catalogue"]);

How sure the primary executor is of its current hypothesis. high lowers the review budget by one; the other levels leave it as the mode and materiality set it.

use majordomus_cli::reasoning::availability::{ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::{plan, Materiality, PlanRequest, ReasoningConfidence};

let mode = ModeResolution { mode: ReasoningMode::Strict, source: "default".into() };
let budget = |confidence: ReasoningConfidence| {
    let request = PlanRequest { materiality: Materiality::Critical, confidence, ..Default::default() };
    plan(&request, &mode, &[]).budget
};
assert_eq!(budget(ReasoningConfidence::Medium), 3);
assert_eq!(budget(ReasoningConfidence::High), 2);

A reference to something that supports a claim.

Evidence is a pointer, never a copy: a path, a case, an id or a command line, with an optional one-line note of what it shows. Unknown fields are refused, so a misspelt field is an error rather than a silently dropped claim.

use majordomus_cli::reasoning::record::{ReasoningEvidence, ReasoningEvidenceKind};

let e: ReasoningEvidence = serde_json::from_value(serde_json::json!({
    "kind": "file",
    "reference": "src/worker.rs:42",
}))
.unwrap();
assert_eq!(e.kind, ReasoningEvidenceKind::File);
assert_eq!(e.note, None);

let typo = serde_json::from_value::<ReasoningEvidence>(serde_json::json!({
    "kind": "file", "reference": "x", "notes": "misspelt",
}));
assert!(typo.is_err());

What a piece of evidence is.

The kind tells a reader how to follow the reference: open a file, run a test, read an ADR or a rule, show a commit. A prior external opinion is a kind of its own so that an advisor's earlier conclusion, handed to another advisor, is never read as a fact.

use majordomus_cli::reasoning::record::ReasoningEvidenceKind;

let kind: ReasoningEvidenceKind = serde_json::from_str("\"prior_external_opinion\"").unwrap();
assert_eq!(kind, ReasoningEvidenceKind::PriorExternalOpinion);
assert_eq!(serde_json::to_string(&ReasoningEvidenceKind::Adr).unwrap(), "\"adr\"");

A record with everything it rests on and everything that rests on it.

It carries the record itself, the assessment it belongs to, and that assessment's whole provenance chain as timeline steps in order. A record that belongs to no assessment has a chain of itself alone.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{explain, ReasoningExplanation};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("attempt-1", 1, json!({
    "kind": "attempt", "attempt": "inline it", "observed_failure": "still slow",
})));
let e: ReasoningExplanation = explain(&loaded, "attempt-1").unwrap();
assert_eq!(e.record.id, "attempt-1");
assert_eq!(e.assessment, None);
assert_eq!(e.chain.len(), 1);

One finding of a reasoning check: which check, where, and what is wrong.

check is one of CHECKS; subject is a repository-relative path, a record id or an advisor; message is one sentence saying what the rule refuses. Findings are reported, never repaired.

use majordomus_cli::reasoning::catalogue::{AdvisorCatalogue, References};
use majordomus_cli::reasoning::check::{run, ReasoningFinding, CHECKS};
use majordomus_cli::reasoning::store::Loaded;

let root = tempfile::tempdir().unwrap();
let loaded = Loaded { records: vec![], unreadable: vec!["t/broken.json".into()] };
let found = run(root.path(), &AdvisorCatalogue::default(), &References::default(), &loaded);
let expected = ReasoningFinding {
    check: "records".into(),
    subject: "t/broken.json".into(),
    message: "a reasoning record that does not parse".into(),
};
assert_eq!(found, [expected]);
assert!(CHECKS.contains(&found[0].check.as_str()));

Anything a session records, as authored.

The JSON form is tagged by kind, with the variant's fields beside the tag. This is what the CLI, HTTP and MCP surfaces accept; crate::reasoning::store::admit turns it into the ReasoningBody that is stored, or refuses it.

use majordomus_cli::reasoning::record::ReasoningInput;

let input: ReasoningInput = serde_json::from_value(serde_json::json!({
    "kind": "plan",
    "assessment": "assessment-1",
}))
.unwrap();
assert!(matches!(input, ReasoningInput::Plan(ref p) if p.assessment == "assessment-1"));
let unknown = serde_json::json!({ "kind": "opinion", "text": "x" });
assert!(serde_json::from_value::<ReasoningInput>(unknown).is_err());

How much independent review a session may use, and where from. The policy reads it for the review budget; availability reads it to leave advisors out (ci all of them, offline every one that leaves the machine). standard is the default.

use majordomus_cli::reasoning::availability::ReasoningMode;

assert_eq!(ReasoningMode::default(), ReasoningMode::Standard);
assert_eq!(serde_json::to_value(ReasoningMode::Offline).unwrap(), "offline");
let m: ReasoningMode = serde_json::from_str("\"strict\"").unwrap();
assert_eq!(m, ReasoningMode::Strict);

A phase of the reasoning timeline.

Each record maps to one phase: a plan to consulting, local or reuse by its outcome, a consultation to an advisor response or a degradation by its status, and every other kind to the phase of the same name.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, ReasoningPhase};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("consultation-1", 1, json!({
    "kind": "consultation", "plan": "plan-0", "advisor": "alpha", "status": "unavailable",
})));
let phases: Vec<ReasoningPhase> =
    derive(&loaded, None).timeline.iter().map(|s| s.phase).collect();
assert_eq!(phases, [ReasoningPhase::Degradation]);
let word = serde_json::to_value(ReasoningPhase::AdvisorResponse).unwrap();
assert_eq!(word, "advisor_response");

A stored record: a body with the envelope only the writer stamps.

The envelope carries the schema and version, a unique id, the task, the time it was recorded, the commit the checkout was on and the secret shapes redacted from its text. One record is one JSON file in the store; the store reads back only records whose schema and version match.

use majordomus_cli::reasoning::record::*;

let record = ReasoningRecord {
    schema: RECORD_SCHEMA.into(),
    version: RECORD_VERSION,
    id: "attempt-20261001T000000Z-abcdef".into(),
    task: "untasked".into(),
    recorded_at: "2026-10-01T00:00:00Z".into(),
    head: None,
    redacted: vec![],
    body: ReasoningBody::Attempt(AttemptInput {
        assessment: None,
        attempt: "inline the call".into(),
        observed_failure: "the test still fails".into(),
        assumption_invalidated: None,
        evidence: vec![],
        updated_hypothesis: None,
    }),
};
let text = serde_json::to_string(&record).unwrap();
assert!(!text.contains("\"head\""), "an absent head is not written");
let back: ReasoningRecord = serde_json::from_str(&text).unwrap();
assert_eq!(back.id, record.id);
assert_eq!(back.body.kind(), "attempt");

The input of reasoning.record: one record, as authored, tagged by its kind. The writer computes everything else (id, task, stamp, a plan's selection) itself.

use majordomus_cli::capability::builtin::reasoning::ReasoningRecordInput;
use majordomus_cli::reasoning::record::ReasoningInput;

let input: ReasoningRecordInput = serde_json::from_value(serde_json::json!({
    "record": { "kind": "plan", "assessment": "assessment-1" },
})).unwrap();
assert!(matches!(input.record, ReasoningInput::Plan(ref p) if p.assessment == "assessment-1"));

The answer of reasoning.record: the record as stored, where it was written, and the timeline step it adds.

use majordomus_cli::capability::builtin::reasoning::ReasoningRecorded;

let schema = serde_json::to_value(schemars::schema_for!(ReasoningRecorded)).unwrap();
for field in ["record", "path", "step"] {
    assert!(schema["required"].as_array().unwrap().iter().any(|f| f == field), "{field}");
}

The reasoning state of a task (or of every task).

It is what every surface reports: the assessments, consultations, disagreements and conclusions of the task, the timeline of every record, the totals, and the store files that could not be read. Derived by derive(), never stored.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, task: &str, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": task,
####         "recorded_at": "2026-10-01T00:00:00Z", "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, ReasoningState};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
let assessment = |subject: &str| json!({ "kind": "assessment", "subject": subject });
loaded.records.push(rec("assessment-1", "t1", assessment("a")));
loaded.records.push(rec("assessment-2", "t2", assessment("b")));
loaded.unreadable.push("t2/broken.json".into());

let one: ReasoningState = derive(&loaded, Some("t1"));
assert_eq!((one.task.as_str(), one.assessments.len()), ("t1", 1));
let all = derive(&loaded, None);
assert_eq!((all.task.as_str(), all.totals.records), ("all", 2));
assert_eq!(all.unreadable, ["t2/broken.json"]);

The answer of reasoning.status: the mode in force, the advisor counts, the state the records derive, and that state rendered as the Markdown a handover carries.

use majordomus_cli::capability::builtin::reasoning::ReasoningStatus;

let schema = serde_json::to_value(schemars::schema_for!(ReasoningStatus)).unwrap();
for field in ["mode", "advisors_available", "advisors_unavailable", "state", "report"] {
    assert!(schema["required"].as_array().unwrap().iter().any(|f| f == field), "{field}");
}

One step of the timeline: when, which record, which phase, and one line saying what happened.

The summary is cut to a single line of at most 140 characters, so a timeline renders the same on a terminal, a page and a handover.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, ReasoningPhase, ReasoningStep};
use majordomus_cli::reasoning::store::Loaded;

let mut loaded = Loaded::default();
loaded.records.push(rec("attempt-1", 1, json!({
    "kind": "attempt", "attempt": "share the client\nacross threads",
    "observed_failure": "the handle is not Sync",
})));
let state = derive(&loaded, None);
let step: &ReasoningStep = &state.timeline[0];
assert_eq!(step.at, "2026-10-01T00:00:01Z");
assert_eq!(step.phase, ReasoningPhase::Attempt);
assert_eq!(step.summary, "share the client failed: the handle is not Sync");

Totals over the records of the derived task: counts, reviewers and reported tokens.

Independent reviewers are distinct advisors with at least one completed consultation; token counts are summed only from what adapters reported, never estimated.

#### use majordomus_cli::reasoning::record::ReasoningRecord;
#### use serde_json::json;
#### fn rec(id: &str, n: u32, body: serde_json::Value) -> ReasoningRecord {
####     serde_json::from_value(json!({
####         "schema": "majordomus/reasoning-record", "version": 1, "id": id, "task": "t",
####         "recorded_at": format!("2026-10-01T00:00:{n:02}Z"), "body": body,
####     }))
####     .unwrap()
#### }
use majordomus_cli::reasoning::state::{derive, ReasoningTotals};
use majordomus_cli::reasoning::store::Loaded;

let answer = |plan: &str| {
    json!({
        "kind": "consultation", "plan": plan, "advisor": "alpha", "status": "completed",
        "conclusion": "A", "stance": "supports",
        "usage": { "input_tokens": 100, "output_tokens": 20 },
    })
};
let mut loaded = Loaded::default();
loaded.records.push(rec("consultation-1", 1, answer("plan-a")));
loaded.records.push(rec("consultation-2", 2, answer("plan-b")));
let totals: ReasoningTotals = derive(&loaded, None).totals;
assert_eq!(totals.consultations_completed, 2);
assert_eq!(totals.independent_reviewers, 1, "one advisor, however often asked");
assert_eq!((totals.input_tokens, totals.output_tokens), (200, 40));

The plan: the decision with its reasons attached. It carries what it answered (mode, materiality, confidence, capabilities), the budget, the outcome with one sentence of why, every advisor selected or excluded, and the local review when one is due.

use majordomus_cli::reasoning::availability::{ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::{plan, Materiality, PlanRequest, ReviewPlan, LOCAL_REVIEW};

let mode = ModeResolution { mode: ReasoningMode::Offline, source: "MAJORDOMUS_REASONING_MODE".into() };
let request = PlanRequest { materiality: Materiality::Material, ..Default::default() };
let p: ReviewPlan = plan(&request, &mode, &[]);
assert_eq!(p.mode_source, "MAJORDOMUS_REASONING_MODE");
assert_eq!(p.capabilities, ["independent_reasoning"]);
assert_eq!((p.budget, p.available), (1, 0));
assert_eq!(p.local_review.len(), LOCAL_REVIEW.len());
assert!(p.reason.starts_with("no available advisor offers"));

One selected advisor, the requested capabilities it covers, and why the greedy selection chose it at its position.

use majordomus_cli::reasoning::availability::{AdvisorState, ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::{plan, Materiality, PlanRequest, SelectedAdvisor};

fn advisor(id: &str, adapter: &str, status: &str) -> AdvisorState {
    serde_json::from_value(serde_json::json!({
        "id": id, "title": id, "transport": "api", "adapter": adapter,
        "capabilities": ["independent_reasoning"], "status": status,
        "reason": "present", "probe": "",
    }))
    .unwrap()
}
let mode = ModeResolution { mode: ReasoningMode::Standard, source: "default".into() };
let request = PlanRequest { materiality: Materiality::Material, ..Default::default() };
let p = plan(&request, &mode, &[advisor("a", "x-api", "available")]);
let chosen: &SelectedAdvisor = &p.selected[0];
assert_eq!(chosen.advisor, "a");
assert_eq!(chosen.covers, ["independent_reasoning"]);
assert!(chosen.why.starts_with("the first available advisor"));

Where an advisor's answer stands relative to the executor's hypothesis.

A completed consultation must state its stance; the store refuses one without it. The stance is a label for the timeline, not a vote: agreement settles nothing.

use majordomus_cli::reasoning::record::Stance;

let s: Stance = serde_json::from_str("\"alternative\"").unwrap();
assert_eq!(s, Stance::Alternative);
assert!(serde_json::from_str::<Stance>("\"agrees\"").is_err());

A conclusion as stored: the input and what only the writer computes.

The input is flattened, so a stored conclusion reads as the input plus two fields: the advisors whose completed consultations it cites, each once and in canonical order, and their count. Both are computed at admission and checked again by reasoning.check, so a hand-edited count is reported.

use majordomus_cli::reasoning::record::{ConclusionInput, StoredConclusion};

let stored = StoredConclusion {
    input: ConclusionInput {
        assessment: "assessment-1".into(),
        decision: "keep the lock".into(),
        rationale: "measured".into(),
        ..Default::default()
    },
    reviewed_by: vec!["alpha".into()],
    independent_review_count: 1,
};
let json = serde_json::to_value(&stored).unwrap();
assert_eq!(json["decision"], "keep the lock");
assert_eq!(json["independent_review_count"], 1);

A plan as stored: the decision and the availability it was made against.

The store builds it when it admits a PlanInput; nothing else does. The snapshot of availability is what a later consultation is admitted against, so an answer that arrives after the advisor's circuit opened still belongs to the plan that asked for it.

use majordomus_cli::reasoning::availability::{ModeResolution, ReasoningMode};
use majordomus_cli::reasoning::policy::PlanOutcome;
use majordomus_cli::reasoning::record::*;
use majordomus_cli::reasoning::store::{admit, Admission, Loaded};

let mode = ModeResolution { mode: ReasoningMode::Standard, source: "default".into() };
let admission = Admission { mode: &mode, availability: &[] };
let mut loaded = Loaded::default();
loaded.records.push(ReasoningRecord {
    schema: RECORD_SCHEMA.into(),
    version: RECORD_VERSION,
    id: "assessment-1".into(),
    task: "t".into(),
    recorded_at: "2026-10-01T00:00:01Z".into(),
    head: None,
    redacted: vec![],
    body: ReasoningBody::Assessment(AssessmentInput {
        subject: "a name".into(),
        ..Default::default()
    }),
});
let input = ReasoningInput::Plan(PlanInput { assessment: "assessment-1".into() });
let ReasoningBody::Plan(stored) = admit(input, &loaded, &admission).unwrap() else {
    panic!("a plan input is stored as a plan");
};
let stored: StoredPlan = stored;
assert_eq!(stored.assessment, "assessment-1");
assert_eq!(stored.plan.outcome, PlanOutcome::DecideLocally);
assert!(stored.availability.is_empty());

Whether a performed validation step passed or failed.

One failed validation is enough to mark the assessment's standing as validation_failed in the derived state, whatever else passed.

use majordomus_cli::reasoning::record::ValidationOutcome;

let o: ValidationOutcome = serde_json::from_str("\"fail\"").unwrap();
assert_eq!(o, ValidationOutcome::Fail);
assert_eq!(serde_json::to_string(&ValidationOutcome::Pass).unwrap(), "\"pass\"");