HTTP API: mesh

One command that admits a rule: the rule's label, its argument vector exactly as apply executes it, and the same quoted as one line a person pastes into a root shell. The two are projections of one vector, so what the report shows is what runs.

use std::net::Ipv4Addr;
use majordomus_cli::mesh::firewall::{plan, render, AdmitCommand, Backend};
use majordomus_cli::mesh::MeshConfig;

let config: MeshConfig = serde_json::from_value(serde_json::json!({
    "schema": "mesh/v1", "kind": "mesh-declaration", "id": "doc", "enabled": true,
})).unwrap();
let p = plan(Some(&config), &[Ipv4Addr::new(10, 0, 0, 2)], None);
let commands: Vec<AdmitCommand> = render(Backend::Ufw, &p, None);
assert_eq!(commands[0].argv[0], "ufw");
assert_eq!(commands[0].rule, "udp/7741 to 239.255.77.77 from any");
assert_eq!(commands[0].line, "ufw allow in proto udp to 239.255.77.77 port 7741 comment 'majordomus mesh: multicast discovery'");

The firewall front this host runs, as far as the executable can tell without privilege: decided by detect from the platform and the path, and the thing render, observe and apply are specific to.

use majordomus_cli::mesh::firewall::Backend;

assert_eq!(serde_json::to_value(Backend::ApplicationFirewall).unwrap(), "application_firewall");
assert_eq!(Backend::None.as_str(), "none");

The input of mesh.claim.

Whether a claim excludes others or only tells them. Both are useful and they answer different questions: an exclusive claim is a worker saying "do not edit this while I am", an advisory one is saying "I am here". Exclusive is the default because a claim taken without a thought about the mode is a claim somebody expects to be respected.

use majordomus_cli::mesh::journal::ClaimMode;

assert_eq!(ClaimMode::default(), ClaimMode::Exclusive);
assert_eq!(serde_json::to_value(ClaimMode::Advisory).unwrap(), serde_json::json!("advisory"));

Two live claims of different sessions whose scopes meet, at least one advisory: reported, never refused.

An overlap is information, not a verdict — it is how two workers find out they are in the same place without either being stopped. The meeting paths are listed pairwise rather than summarized, because the useful question is which path of mine meets which path of theirs.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{ClaimMode, EventBody, Journal, StreamLiveness};
use majordomus_cli::mesh::state::{fold, ClaimOverlap};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
for (claim, session, mode) in [
    ("c1", "s1", ClaimMode::Exclusive),
    ("c2", "s2", ClaimMode::Advisory),
] {
    j.append_own(EventBody::ClaimAcquired { claim: claim.into(), session: session.into(),
        scope: vec!["apps".into()], intent: None, mode, issue: None }).unwrap();
}

let state = fold(&j.events(), &|_| StreamLiveness::Own);
let overlap: &ClaimOverlap = &state.overlaps[0];
assert_ne!(overlap.first, overlap.second, "two claims, two sessions");
assert_eq!(overlap.paths, [("apps".to_string(), "apps".to_string())]);

A claim's standing, and — where it ended or lost — what ended it. The two variants that carry a string exist because the bare verdict is not actionable: a worker told its claim expired needs to know whether its session closed or its runtime stopped beating, and one told its claim is conflicted needs the key of the claim that beat it, which is the same key on every runtime.

use majordomus_cli::mesh::state::ClaimState;

assert!(ClaimState::Held.is_live());
assert!(ClaimState::Conflicted("s/c1".into()).is_live(), "still held, and not the winner");
assert!(!ClaimState::Released.is_live());

// the detail travels with the verdict, so a reader is never left asking who won
let value = serde_json::to_value(ClaimState::Conflicted("s/c1".into())).unwrap();
assert_eq!(value["state"], "conflicted");
assert_eq!(value["detail"], "s/c1");

One claim anywhere in the mesh: who took what, for what, and where it stands. The acquisition's Lamport stamp and sequence are carried rather than derived on demand, because they are what exclusivity is decided by — every runtime ranks two competing claims by the same triple and so names the same winner, with no message passing and no "last packet wins".

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{ClaimMode, EventBody, Journal, StreamLiveness};
use majordomus_cli::mesh::state::{fold, ClaimState, ClaimView};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::ClaimAcquired { claim: "c1".into(), session: "s1".into(),
    scope: vec!["apps/majordomus-cli".into()], intent: Some("document the mesh".into()),
    mode: ClaimMode::Exclusive, issue: Some("#184".into()) }).unwrap();

let state = fold(&j.events(), &|_| StreamLiveness::Own);
let claim: &ClaimView = &state.claims[0];
assert_eq!(claim.scope, ["apps/majordomus-cli"]);
assert_eq!(claim.state, ClaimState::Held);
assert!(claim.acquired_lamport > 0, "the order exclusivity is decided in");

The answer of mesh.handover.consume.

The link and replication counters since start: what this runtime did, not what it holds. They are monotonic and never reset, so two readings a minute apart are a rate — which is the only way to tell a mesh that is working from one that is retrying, since both show the same peers in the same states.

The counts are split by direction throughout (handshakes_out against handshakes_in, refused_in against refused_out) because a runtime that refuses everyone and one that everyone refuses need opposite remedies.

#### use std::collections::BTreeMap;
#### use std::sync::{Arc, Mutex, Weak};
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::*;
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};
#### use majordomus_cli::mesh::trust::TrustPolicy;
#### #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);
#### impl LinkTransport for Net {
####   fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {
####     let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))
####         .ok_or_else(|| format!("{e}: nobody there"))?;
####     Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }
#### let net = Arc::new(Net::default());
#### let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),
####     repository: of_root_commits(&["root".into()]), endpoints: vec![endpoint.into()],
####     version: "doc".into(), config: CooperationConfig::default(),
####     trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,
####     registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,
####     checkout: CheckoutFacts::default() }).unwrap();
####   net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };
#### let (a, b) = (runtime("a:1"), runtime("b:1"));
let key = a.dial(&["b:1".into()]).unwrap();
a.sync_with(&key).unwrap();

let dialer: CooperationCounters = a.status().counters;
let answerer = b.status().counters;
assert_eq!((dialer.handshakes_out, dialer.syncs_out), (1, 1));
assert_eq!((answerer.handshakes_in, answerer.syncs_in), (1, 1), "the other side of it");
assert_eq!(answerer.handshakes_out, 0, "B never dialed anybody");

The whole folded state, every collection in key order, and its digest: two runtimes that agree print the same digest.

The digest is the point. Convergence is otherwise a claim nobody can check from one machine; with it, two operators compare one short string and know whether their runtimes are looking at the same world. opaque_events is the other half of that honesty: events of kinds this executable does not interpret are counted and relayed rather than dropped, so a newer peer's traffic is visible instead of silently missing.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::{fold, CooperationState};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "cli") }).unwrap();

let events = j.events();
let state: CooperationState = fold(&events, &|_| StreamLiveness::Own);
assert_eq!(state.digest.len(), 32);

// the same events in another order, and twice over, are the same state
let mut shuffled = events.clone();
shuffled.reverse();
shuffled.extend(events);
assert_eq!(fold(&shuffled, &|_| StreamLiveness::Own).digest, state.digest);

The whole cooperation runtime, as every surface reports it: the command line, the HTTP surface and MCP all render this one value, so that a person and an agent asking the same question of the same runtime are never told different things.

It answers in one reading the three questions a mesh raises — is this runtime cooperating at all, what does it speak, and who is it linked to — and it stays answerable when the answer is no: an inactive runtime still reports its protocol range and the reason, rather than an absence the caller has to interpret.

#### use std::sync::Arc;
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::HttpTransport;
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::of_root_commits;
#### let cooperation = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: "0000000000000001".into(),
####     repository: of_root_commits(&["root".into()]), endpoints: vec!["127.0.0.1:9".into()],
####     version: "doc".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),
####     journal_path: None, registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),
#### }).unwrap();
use majordomus_cli::mesh::cooperation::CooperationStatus;

let running: CooperationStatus = cooperation.status();
assert_eq!(running.runtime.as_deref(), Some(cooperation.runtime_key()));
assert!(running.peers.is_empty(), "nothing is dialed until something dials");

// and where there is no runtime at all, the same shape says why
let none = CooperationStatus::inactive("the mesh declaration is disabled");
assert_eq!(none.protocol, running.protocol, "still answerable about what it speaks");

One check's verdict.

Whether an event this runtime wrote reached this machine's disk: what an append acknowledges, and the only thing a caller may say about it.

use majordomus_cli::mesh::journal::Durability;
assert_eq!(serde_json::to_value(Durability::NotDurable).unwrap(), "not_durable");
assert_eq!(Durability::default(), Durability::Unknown, "an answer that did not say");
assert!(Durability::Synced.is_on_disk() && !Durability::NotDurable.is_on_disk());

No input.

The wire envelope: the advertisement plus its signature.

The answer of mesh.events.

The firewall's own word, judged against the plan: the state, the evidence behind it, and the labels of the rules not admitted when the state is missing.

use majordomus_cli::mesh::firewall::{judge_ufw, plan, FirewallObservation, FirewallObservationState};

let o: FirewallObservation = judge_ufw("Status: inactive\n", &plan(None, &[], None));
assert_eq!(o.state, FirewallObservationState::Inactive);
assert!(o.missing.is_empty() && o.detail.contains("inactive"));

What the host's firewall says about the plan, as one word. Only missing is a failure on its own; unobservable is an absence that the kernel log may still turn into one.

use majordomus_cli::mesh::firewall::FirewallObservationState;

assert_eq!(serde_json::to_value(FirewallObservationState::Unobservable).unwrap(), "unobservable");

What the declaration implies this host must admit: the rules, the networks they admit from, the hub ports this machine is listed for, and the addresses the plan saw. The answer of plan; an empty rules is "nothing is needed", which is the answer for no declaration and for a disabled one.

use majordomus_cli::mesh::firewall::{plan, FirewallPlan};

let nothing: FirewallPlan = plan(None, &[], None);
assert!(nothing.rules.is_empty() && nothing.hub_ports.is_empty() && nothing.networks.is_empty());

The whole report: the plan, the backend, the commands, the firewall's word and the kernel's, with one verdict sentence and one ok. What mesh.firewall answers and what the doctor's firewall check reads.

use majordomus_cli::mesh::firewall::{report, FirewallReport, BLOCK_WINDOW_SECONDS};

let r: FirewallReport = report(None, &[], None);
assert!(r.ok && r.commands.is_empty());
assert_eq!(r.window_seconds, BLOCK_WINDOW_SECONDS);
assert_eq!(r.platform, std::env::consts::OS);

One inbound admission the mesh needs on this host: a protocol and a port, the group it is addressed to when it is multicast, the networks it may come from, and the sentence that says why. A rule is derived, never written by hand; FirewallRule::label is how a verdict names it.

use majordomus_cli::mesh::firewall::{FirewallRule, Protocol, Role};

let rule = FirewallRule {
    role: Role::Hub,
    protocol: Protocol::Tcp,
    port: 8791,
    destination: None,
    sources: vec!["192.168.7.0/24".into()],
    reason: "this machine is a declared rendezvous hub".into(),
};
assert_eq!(rule.label(), "tcp/8791 from 192.168.7.0/24");

A handover as the mesh carries it: the record's facts and its body, bounded.

What travels is the writing, plus the few facts that let a receiver file it — the task, the issue, the branch, the commit. No path of the author's disk is among them, because the checkout that reads this is somewhere else and a path from another machine is at best noise. Identity is the digest of the body, so a handover published twice by a retry or by two runtimes is one handover everywhere.

use majordomus_cli::mesh::journal::HandoverBody;

let body = "# Objective\nship the mesh\n".to_string();
let handover = HandoverBody {
    id: HandoverBody::digest_of(&body),
    task: Some("t-1".into()),
    issue: Some("#184".into()),
    milestone: None,
    branch: Some("feature/mesh-cooperation".into()),
    head: None,
    created_at: None,
    name: None,
    body,
};
assert_eq!(handover.id, HandoverBody::digest_of(&handover.body));

let wire = serde_json::to_value(&handover).unwrap();
assert!(wire.get("milestone").is_none(), "what it does not say is omitted");

The input of mesh.handover.consume.

The input of mesh.handover.publish.

A handover anywhere in the mesh, with everyone who has taken it. The id is the digest of the body, so the same handover published twice — by a retry, or by two runtimes that both saw it — is one handover here; and consumed_by is what keeps two workers from silently picking up the same continuity, since the list is folded from events every runtime holds.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, HandoverBody, Journal, StreamLiveness};
use majordomus_cli::mesh::state::{fold, HandoverView};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
let body = "# Objective\nship\n".to_string();
let handover = HandoverBody { id: HandoverBody::digest_of(&body), task: None, issue: None,
    milestone: None, branch: Some("feature/x".into()), head: None, created_at: None,
    name: None, body };
let id = handover.id.clone();
j.append_own(EventBody::HandoverPublished { handover }).unwrap();
j.append_own(EventBody::HandoverConsumed { handover: id.clone(), session: "s1".into() })
    .unwrap();

let state = fold(&j.events(), &|_| StreamLiveness::Own);
let view: &HandoverView = &state.handovers[0];
assert_eq!(view.id, id, "identified by what it says, not by who said it");
assert_eq!(view.consumed_by.len(), 1, "somebody has picked this one up");

One run of a node: 16 hex characters of OS entropy, new at every process start. A restart keeps the node id and changes this, which is how a reader tells "the same node came back" from "the same process is still there".

The journal's counters since start: how much it holds, how much it has written, received, absorbed, refused, held back and compacted away. They are what makes a replication problem diagnosable from one machine — a runtime whose received never rises is not linked, one whose rejected rises is being sent something it will not take, and one whose pending stays high is missing an event ahead of what it has.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, JournalTallies};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
let before: JournalTallies = j.tallies();
assert_eq!((before.written, before.events), (0, 0));

j.append_own(EventBody::SessionClosed { session: "s1".into() }).unwrap();
let after = j.tallies();
assert_eq!((after.written, after.events, after.streams), (1, 1, 1));
assert!(after.lamport > before.lamport);

A refusal: the code, the reason in words, and the protocol range of the refuser so a version mismatch is diagnosable from either end.

Carrying the refuser's protocol range in every refusal, not only in the one about protocols, is what makes a version problem visible from the side that has the log: the dialer sees what the answerer speaks without anyone having to read the other machine.

use majordomus_cli::mesh::link::{LinkRefusal, RefusalCode, LINK_PROTOCOL_MAX};

let refusal = LinkRefusal::new(RefusalCode::Untrusted, "the key is not in the allowlist");
assert_eq!(refusal.code, RefusalCode::Untrusted);
assert_eq!(refusal.proto_max, LINK_PROTOCOL_MAX);
assert_eq!(refusal.to_string(), "untrusted: the key is not in the allowlist");

What a hello or a sync answers over the wire: a signed message or a refusal. Both are successful replies — the transport carries them the same way and neither is an error — because a refusal is a decision this protocol wants recorded and shown, and an answer that arrived as an HTTP failure would be indistinguishable from a peer that is down.

use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::link::{sign, Domain, LinkReply, RefusalCode};

let node = NodeIdentity::ephemeral().unwrap();
let accepted = LinkReply::accepted(sign(&node, Domain::Welcome, serde_json::json!({})));
assert!(accepted.signed.is_some() && accepted.refusal.is_none());

let refused = LinkReply::refused(RefusalCode::SelfLink, "this runtime dialled itself");
assert!(refused.signed.is_none());
assert_eq!(refused.refusal.unwrap().code, RefusalCode::SelfLink);

A link's standing, from this runtime's side. It is a statement about a connection and never about the peer: a runtime reachable only through a third party is Expired here while its streams beat on everywhere, which is why claims follow streams and not this.

The variants are ordered by how far the link has fallen, so the worst link in a table is the maximum and a reader never has to rank them by hand.

use majordomus_cli::mesh::cooperation::LinkState;

let table = [LinkState::Connected, LinkState::Unreachable, LinkState::Degraded];
assert_eq!(table.iter().max(), Some(&LinkState::Unreachable), "the worst link shows");
assert_eq!(serde_json::to_value(LinkState::Connected).unwrap(), "connected");

One machine in the peer tree.

One live claim, told briefly: whose it is, what it is for and how many paths it holds, with its intent cut to SUMMARY_TEXT characters — enough to know whom to ask.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{ClaimMode, EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::fold;

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "claude-code") })
    .unwrap();
for (claim, path) in [("c1", "apps/a"), ("c2", "apps/b")] {
    j.append_own(EventBody::ClaimAcquired { claim: claim.into(), session: "s1".into(),
        scope: vec![path.into()], intent: Some("work".into()), mode: ClaimMode::Exclusive,
        issue: Some("#1".into()) }).unwrap();
}
j.append_own(EventBody::ClaimReleased { claim: "c1".into() }).unwrap();
let state = fold(&j.events(), &|_| StreamLiveness::Own);
use majordomus_cli::mesh::page::{summarize, ClaimBrief};

let summary = summarize(&state, &[]);
let newest: &ClaimBrief = summary.runtimes[0].newest_claim.as_ref().unwrap();
assert_eq!((newest.issue.as_deref(), newest.paths), (Some("#1"), 1));

Claims by standing: held, conflicted, released and expired. Held and conflicted are live; the other two are history, counted rather than listed.

use majordomus_cli::mesh::page::ClaimCounts;

let counts = ClaimCounts { held: 2, released: 5, ..ClaimCounts::default() };
assert_eq!(serde_json::to_value(&counts).unwrap()["released"], 5);

Which claims a full answer keeps: all of them, the ended ones included, or only those still live — the question an executor asks before it takes a lease.

use majordomus_cli::mesh::page::ClaimFilter;

assert_eq!(ClaimFilter::default(), ClaimFilter::All);
assert_eq!(serde_json::from_str::<ClaimFilter>(r#""live""#).unwrap(), ClaimFilter::Live);

The whole self-check.

One event as the wire and the store carry it. The body is kept as JSON so that an event of an unknown kind survives storage and relay byte-for-byte; MeshEvent::body interprets it.

Every field above the signature is covered by it, which is what makes a relay harmless: a runtime that forwards an event cannot alter its stream, its sequence, its repository or its body without the next reader noticing, and so vouches for nothing. The wall clock is the one field nothing is decided by — freshness is measured with beats and monotonic clocks, never by comparing two machines' idea of the time.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, MeshEvent};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionClosed { session: "s1".into() }).unwrap();

let event: &MeshEvent = &j.events()[0];
assert_eq!(event.seq, 1, "dense from 1 within its stream");
assert_eq!(event.kind(), "session_closed");
assert_eq!(event.id(), format!("{}/1", event.stream));

// a relayed byte changed anywhere under the signature is a different event
let mut tampered = event.clone();
tampered.repo = "another-repository".into();
assert_ne!(tampered.signing_bytes(), event.signing_bytes());

A handover nobody has taken, told briefly: the id mesh.handover.consume takes, who published it and what it continues. Its body stays in the full view.

use majordomus_cli::mesh::page::HandoverBrief;

let brief = HandoverBrief { id: "ab12".into(), runtime: "n-r".into(),
    branch: Some("feature/x".into()), issue: None, published_lamport: 7 };
assert_eq!(serde_json::to_value(&brief).unwrap()["branch"], "feature/x");

The answer of mesh.identity: this machine's node identity, public half only.

One collection of the folded state, as kind names it: a reader that wants only the reviews is not sent the claims.

use majordomus_cli::mesh::page::Kind;

assert_eq!(serde_json::from_str::<Kind>(r#""reviews""#).unwrap(), Kind::Reviews);
assert!(serde_json::from_str::<Kind>(r#""everything""#).is_err());

The provider's health, as every surface reports it.

What the repository identity was derived from, which a reader needs in order to judge it: an identity taken from the root commits is a fact about the history two clones share, while a declared one is a decision somebody made, and only the second can be changed by editing a file.

use majordomus_cli::mesh::repository::{declared, of_root_commits, MeshRepositoryBasis};

assert_eq!(declared("majordomus").unwrap().basis, MeshRepositoryBasis::Declared);
assert_eq!(
    of_root_commits(&["a".repeat(40)]).basis,
    MeshRepositoryBasis::RootCommits,
);

A repository's mesh identity, carried by every advertisement, link and event, together with the account of where it came from. The detail exists so that a person told two checkouts are not the same repository can see what each one was derived from instead of comparing two opaque digests.

use majordomus_cli::mesh::repository::MeshRepositoryIdentity;
use majordomus_cli::mesh::repository::of_root_commits;

let identity: MeshRepositoryIdentity = of_root_commits(&["a".repeat(40)]);
assert_eq!(identity.id.len(), 32, "32 hex characters, on every machine");
assert_eq!(identity.detail, "aaaaaaaaaaaa", "the evidence, short enough to read");

An open review request, told briefly: its key, what is to be reviewed and whom it asks. Only requests nobody has answered are listed in the summary.

use majordomus_cli::mesh::page::ReviewBrief;

let brief = ReviewBrief { key: "s/r1".into(), subject: "feature/x".into(), issue: None,
    reviewer: None };
assert!(serde_json::to_value(&brief).unwrap().get("issue").is_none(), "absent, not null");

One runtime, counted: its liveness and beat, its sessions and claims by standing, and its newest live claim. The summary lists these, the living runtimes first.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{ClaimMode, EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::fold;

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "claude-code") })
    .unwrap();
for (claim, path) in [("c1", "apps/a"), ("c2", "apps/b")] {
    j.append_own(EventBody::ClaimAcquired { claim: claim.into(), session: "s1".into(),
        scope: vec![path.into()], intent: Some("work".into()), mode: ClaimMode::Exclusive,
        issue: Some("#1".into()) }).unwrap();
}
j.append_own(EventBody::ClaimReleased { claim: "c1".into() }).unwrap();
let state = fold(&j.events(), &|_| StreamLiveness::Own);
use majordomus_cli::mesh::page::{summarize, RuntimeSummary};

let summary = summarize(&state, &[]);
let runtime: &RuntimeSummary = &summary.runtimes[0];
assert_eq!((runtime.sessions.active, runtime.claims.held, runtime.claims.released), (1, 1, 1));

Sessions by standing: how many are active, closed and expired. A count stays the same size however many sessions the mesh has seen, which is why the summary carries counts.

use majordomus_cli::mesh::page::SessionCounts;

let none = SessionCounts::default();
assert_eq!(serde_json::to_value(&none).unwrap(),
    serde_json::json!({ "active": 0, "closed": 0, "expired": 0 }));

Where an observation came from. A record accumulates these; provenance is the answer to "why do I see this node".

The answer of mesh.state.

The whole mesh, as every surface reports it.

The mesh in an answer a worker reads whole: counts, each runtime, the open reviews and the untaken handovers, every list bounded by SUMMARY_LIST with the rest counted.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{ClaimMode, EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::fold;

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "claude-code") })
    .unwrap();
for (claim, path) in [("c1", "apps/a"), ("c2", "apps/b")] {
    j.append_own(EventBody::ClaimAcquired { claim: claim.into(), session: "s1".into(),
        scope: vec![path.into()], intent: Some("work".into()), mode: ClaimMode::Exclusive,
        issue: Some("#1".into()) }).unwrap();
}
j.append_own(EventBody::ClaimReleased { claim: "c1".into() }).unwrap();
let state = fold(&j.events(), &|_| StreamLiveness::Own);
use majordomus_cli::mesh::page::{summarize, Summary};

let summary: Summary = summarize(&state, &[]);
assert_eq!((summary.claims.held, summary.claims.released), (1, 1));
assert_eq!(summary.digest, state.digest);

One verification check: what was checked, whether it holds, the evidence, and — when something is wrong or limited — the impact and what to do about it.

The impact and the remedy are carried with the verdict rather than left to whoever renders it, so that a failing check is actionable wherever it is read — in a terminal, in a JSON answer, or by an agent that has never seen the mesh before. A check that holds carries neither, because there is nothing to do.

#### use std::sync::Arc;
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::HttpTransport;
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::of_root_commits;
#### let cooperation = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: "0000000000000001".into(),
####     repository: of_root_commits(&["root".into()]), endpoints: vec!["127.0.0.1:9".into()],
####     version: "doc".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),
####     journal_path: None, registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),
#### }).unwrap();
use majordomus_cli::mesh::cooperation::MeshVerifyCheck;

let report = cooperation.verify();
let first: &MeshVerifyCheck = &report.checks[0];
assert_eq!(first.check, "cooperation");
assert!(first.detail.contains(cooperation.runtime_key()), "the evidence, not a verdict");
assert!(first.remediation.is_none(), "a check that holds asks for nothing");

What mesh verify found: the local checks, every peer's round, and the state digest afterwards. The digest is what makes the report worth running on two machines — two runtimes that print the same digest have the same sessions, claims, handovers and reviews, and two that do not have something to reconcile, whatever their links say.

ok is the conjunction of everything below it, so a caller may act on the one field and a person may read the rest to find out which part of it was false.

#### use std::sync::Arc;
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::HttpTransport;
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::of_root_commits;
#### let cooperation = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: "0000000000000001".into(),
####     repository: of_root_commits(&["root".into()]), endpoints: vec!["127.0.0.1:9".into()],
####     version: "doc".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),
####     journal_path: None, registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),
#### }).unwrap();
use majordomus_cli::mesh::cooperation::MeshVerifyReport;

let report: MeshVerifyReport = cooperation.verify();
assert_eq!(report.runtime.as_deref(), Some(cooperation.runtime_key()));
assert_eq!(report.digest, Some(cooperation.state().digest), "what a peer is compared to");
assert_eq!(report.ok, report.checks.iter().all(|c| c.ok), "one field for every check");

How much an answer about the mesh carries. The summary is the default because it is the answer a worker can read whole whatever the mesh's history; the full fold is one word away when a reader needs every record.

use majordomus_cli::mesh::page::View;

assert_eq!(View::default(), View::Summary);
assert_eq!(serde_json::to_value(View::Full).unwrap(), "full");

The stable identity of a node: 32 hex characters of the SHA-256 of its Ed25519 public key. Derived, never chosen: two nodes with one id hold one key.

The answer of mesh.nodes: every node this process has observed.

One discovered node: the canonical record every surface projects.

The answer of mesh.peer.

The answer of mesh.peers: machine → runtime → session → claim, every level from the one journal and the one link table.

What one sync round, run now rather than remembered, said about one peer. Verification does not report the link's standing and stop there: it exchanges with the peer and says whether the exchange worked and whether both sides ended holding the same marks, which is the difference between a peer that answers and a peer that agrees.

round_trip and converged are optional because a peer this runtime does not dial is not asked — an absent answer is not a failed one, and reporting false there would make an inbound-only link look broken every time.

#### use std::collections::BTreeMap;
#### use std::sync::{Arc, Mutex, Weak};
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::*;
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};
#### use majordomus_cli::mesh::trust::TrustPolicy;
#### #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);
#### impl LinkTransport for Net {
####   fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {
####     let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))
####         .ok_or_else(|| format!("{e}: nobody there"))?;
####     Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }
#### let net = Arc::new(Net::default());
#### let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),
####     repository: of_root_commits(&["root".into()]), endpoints: vec![endpoint.into()],
####     version: "doc".into(), config: CooperationConfig::default(),
####     trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,
####     registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,
####     checkout: CheckoutFacts::default() }).unwrap();
####   net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };
#### let (a, b) = (runtime("a:1"), runtime("b:1"));
a.dial(&["b:1".into()]).unwrap();

let dialer: &PeerVerdict = &a.verify().peers[0];
assert_eq!(dialer.round_trip, Some(true), "asked, and answered");

let answerer = &b.verify().peers[0];
assert!(!answerer.dialed, "B does not dial A, so B asks nothing of it");
assert_eq!(answerer.round_trip, None, "and reports no verdict it did not earn");

One peer as every surface shows it: who it is, how this runtime reaches it, and what the link has been through. The counters are carried per peer rather than only in the totals because the question a person asks of a flapping mesh is which peer is flapping, and restarts answers a different one from reconnects — a peer whose process keeps dying, against a link that keeps dropping under a process that never did.

#### use std::collections::BTreeMap;
#### use std::sync::{Arc, Mutex, Weak};
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::*;
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};
#### use majordomus_cli::mesh::trust::TrustPolicy;
#### #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);
#### impl LinkTransport for Net {
####   fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {
####     let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))
####         .ok_or_else(|| format!("{e}: nobody there"))?;
####     Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }
#### let net = Arc::new(Net::default());
#### let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),
####     repository: of_root_commits(&["root".into()]), endpoints: vec![endpoint.into()],
####     version: "doc".into(), config: CooperationConfig::default(),
####     trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,
####     registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,
####     checkout: CheckoutFacts::default() }).unwrap();
####   net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };
#### let (a, b) = (runtime("a:1"), runtime("b:1"));
a.dial(&["b:1".into()]).unwrap();

let peer: &PeerView = &a.peers()[0];
assert_eq!(peer.runtime, b.runtime_key(), "the durable identity, not the endpoint");
assert!(peer.outbound, "this runtime dials it");
assert_eq!(peer.handshakes, 1);
assert_eq!(peer.restarts, 0, "the peer's process has not died under the link");

Whether the node is answering now, by its own announcements.

The transport protocol of a rule: discovery is datagrams, registration and the link protocol are connections. Serialised as the word a firewall front takes.

use majordomus_cli::mesh::firewall::Protocol;

assert_eq!(serde_json::to_value(Protocol::Udp).unwrap(), "udp");
assert_eq!(serde_json::to_value(Protocol::Tcp).unwrap(), "tcp");

One provider's status: state, why, and its counters.

What everyone may know about this node: the id, the public key, a display name and this run's instance. Everything an advertisement carries; nothing that signs.

Why a link message was turned down. Every refusal is typed, counted and shown: a mesh that refuses a peer says which rule did, instead of dropping a socket.

The codes are the diagnosis a person needs when two runtimes will not link, and they are deliberately distinct where the remedies differ: Untrusted is a key to add, RepositoryMismatch is two different repositories, SelfLink is a configuration that dials its own endpoint, and UnknownLink is not a failure at all but an instruction to say hello again.

use majordomus_cli::mesh::link::RefusalCode;

// the wire word is the code's identity across surfaces, and it is stable
assert_eq!(RefusalCode::RepositoryMismatch.as_str(), "repository_mismatch");
assert_eq!(
    serde_json::to_value(RefusalCode::Untrusted).unwrap(),
    serde_json::json!("untrusted"),
);
assert_ne!(RefusalCode::Untrusted, RefusalCode::RepositoryMismatch);

Refused datagrams, by reason. The diagnosis of a hostile or misconfigured network: a mesh that hears garbage says so, with numbers, instead of being quietly empty.

A candidate that was refused, with the rule that refused it. A refusal is kept and shown rather than logged and dropped, because the commonest mesh failure is a link that never forms: a person who declared a seed and sees no peer needs the decision that was made about it — the wrong repository, a key nobody allowed, a clock too far out — and the direction says which side made it.

#### use std::collections::BTreeMap;
#### use std::sync::{Arc, Mutex, Weak};
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::*;
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::{LinkReply, LinkTransport, RefusalCode, Signed, HELLO_PATH};
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};
#### use majordomus_cli::mesh::trust::TrustPolicy;
#### #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);
#### impl LinkTransport for Net {
####   fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {
####     let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))
####         .ok_or_else(|| format!("{e}: nobody there"))?;
####     Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }
#### let net = Arc::new(Net::default());
#### let runtime = |endpoint: &str, policy: TrustPolicy| {
####   let c = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),
####     repository: of_root_commits(&["root".into()]), endpoints: vec![endpoint.into()],
####     version: "doc".into(), config: CooperationConfig::default(),
####     trust: TrustConfig { policy, allow: vec![] }, journal_path: None,
####     registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,
####     checkout: CheckoutFacts::default() }).unwrap();
####   net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };
#### let a = runtime("a:1", TrustPolicy::Tofu);
#### let strict = runtime("s:1", TrustPolicy::DenyUnknown);
a.dial(&["s:1".into()]).expect_err("reachable, and not trusted");

let refused: &RefusedView = &strict.status().refused[0];
assert_eq!(refused.refusal.code, RefusalCode::Untrusted);
assert_eq!(refused.direction, "inbound", "this runtime refused the hello");
assert_eq!(refused.runtime.as_deref(), Some(a.runtime_key()));

What a registration answers: whether the envelope was accepted, and the candidates the rendezvous holds. Defined here beside the client; the capability re-exports it.

The input of mesh.register: one signed envelope, exactly as the wire carries it.

The input of mesh.release.

One answer to a review request: who answered, what they decided, and why. The verdict is one of the three declared words, so a requester can act on it without reading the note; the note is where the reasoning goes and is optional, because "approved" often needs none.

use majordomus_cli::mesh::state::ReviewAnswer;

let answer = ReviewAnswer {
    session: "a1b2c3d4-r1-0f/s2".into(),
    verdict: "changes_requested".into(),
    note: Some("the fold is not deterministic".into()),
};
assert_eq!(answer.verdict, "changes_requested");

// the note is omitted rather than carried empty when there is nothing to say
let bare = ReviewAnswer { note: None, ..answer };
let value = serde_json::to_value(&bare).unwrap();
assert!(value.get("note").is_none());

The input of mesh.review.answer.

The input of mesh.review.request.

A review request's standing: whether anybody has answered it yet. There is deliberately no Approved or Rejected here — a request may be answered by several runtimes and the verdicts are the answers' own, so collapsing them into one state would throw away the disagreement that makes a second reviewer worth asking.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, StreamLiveness};
use majordomus_cli::mesh::state::{fold, ReviewState};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::ReviewRequested { review: "r1".into(), session: "s1".into(),
    subject: "feature/x".into(), scope: vec![], issue: None, reviewer: None, body: None }).unwrap();
let asked = fold(&j.events(), &|_| StreamLiveness::Own);
assert_eq!(asked.reviews[0].state, ReviewState::Open);

let request = asked.reviews[0].key.clone();
j.append_own(EventBody::ReviewAnswered { request, session: "s2".into(),
    verdict: "approved".into(), note: None }).unwrap();
assert_eq!(fold(&j.events(), &|_| StreamLiveness::Own).reviews[0].state, ReviewState::Answered);

One review request anywhere in the mesh, with every answer it has drawn. A request with no reviewer is an offer to the whole mesh rather than to nobody, which is why the answers are a list: any linked runtime carrying the reviews feature may add one, and they are kept in Lamport order so that every runtime reads them in the same sequence.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, StreamLiveness};
use majordomus_cli::mesh::state::{fold, ReviewView};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::ReviewRequested { review: "r1".into(), session: "s1".into(),
    subject: "feature/mesh-cooperation".into(), scope: vec!["src/mesh".into()],
    issue: Some("#184".into()), reviewer: None, body: None }).unwrap();
let request = fold(&j.events(), &|_| StreamLiveness::Own).reviews[0].key.clone();
j.append_own(EventBody::ReviewAnswered { request, session: "s2".into(),
    verdict: "approved".into(), note: Some("reads well".into()) }).unwrap();

let state = fold(&j.events(), &|_| StreamLiveness::Own);
let review: &ReviewView = &state.reviews[0];
assert_eq!(review.subject, "feature/mesh-cooperation");
assert_eq!(review.reviewer, None, "offered to the mesh, not addressed");
assert_eq!(review.answers[0].verdict, "approved");

The input of mesh.review.withdraw.

Why a rule exists: which part of the declaration implied it. The role is what a person reads beside the rule and what a verdict names, and it is serialised in snake case.

use majordomus_cli::mesh::firewall::Role;

assert_eq!(serde_json::to_value(Role::Hub).unwrap(), "hub");
let back: Role = serde_json::from_value(serde_json::json!("multicast")).unwrap();
assert_eq!(back, Role::Multicast);

One runtime in the peer tree.

The input of mesh.session.close.

What a session tells the mesh about itself. Every field is a public fact about work in progress; none is a path on the author's disk, a secret or a credential.

Almost everything here is optional, and that is the design: a session says what it knows, and a field it leaves out is omitted rather than carried empty, so a reader can tell "no task" from "a task called nothing". Opening the same session id again replaces this record, which is how a session that learns its branch later tells the mesh.

use majordomus_cli::mesh::journal::SessionInfo;

let mut info = SessionInfo::named("s1", "claude-code");
assert_eq!(info.task, None);
assert!(serde_json::to_value(&info).unwrap().get("task").is_none(), "unsaid, not empty");

info.branch = Some("feature/mesh-cooperation".into());
assert_eq!(serde_json::to_value(&info).unwrap()["branch"], "feature/mesh-cooperation");

The input of mesh.session.open: what a session says about itself.

One session in the peer tree.

A session's standing, as every runtime of the mesh reads it. The distinction that matters is between Closed and Expired: the first is a session that said it was finished, the second one whose runtime stopped beating and can no longer say anything. Both end the session's claims, but only the second is a machine nobody should expect an answer from.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::{fold, SessionState};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "cli") }).unwrap();
assert_eq!(fold(&j.events(), &|_| StreamLiveness::Own).sessions[0].state, SessionState::Active);

// the same events, read on a runtime that no longer hears the writer
let gone = fold(&j.events(), &|_| StreamLiveness::Expired);
assert_eq!(gone.sessions[0].state, SessionState::Expired);

One session anywhere in the mesh, as the fold sees it: what the session said about itself, where it is writing from, and whether it still counts. The key is <stream>/<session> rather than the session's own id, because two runtimes may both call a session s1 and the mesh has to hold them apart.

use std::sync::Arc;
use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::journal::{EventBody, Journal, SessionInfo, StreamLiveness};
use majordomus_cli::mesh::state::{fold, SessionView};

let j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), "0000000000000001",
    "repo".into(), None).unwrap();
j.append_own(EventBody::SessionOpened { info: SessionInfo::named("s1", "claude-code") })
    .unwrap();

let state = fold(&j.events(), &|_| StreamLiveness::Own);
let view: &SessionView = &state.sessions[0];
assert!(view.key.ends_with("/s1"), "qualified by the stream that wrote it: {}", view.key);
assert_eq!(view.info.client, "claude-code");
assert_eq!(view.runtime, view.stream.runtime_key());

One provenance entry: a source, and where the observation physically came from.

A signed message: a JSON body and the Ed25519 signature over its canonical bytes under the message's domain. The body stays JSON so that fields a newer peer adds survive verification here unchanged.

Keeping the body as JSON rather than as the bytes that were signed is what makes the protocol extensible: a field a newer peer added is carried through verification untouched, because the signature is checked over the canonical form of whatever is there rather than over a shape this version knows.

use majordomus_cli::mesh::identity::NodeIdentity;
use majordomus_cli::mesh::link::{sign, verify_signed, Domain, Signed};

let node = NodeIdentity::ephemeral().unwrap();
let signed: Signed = sign(&node, Domain::SyncRequest, serde_json::json!({ "b": 2, "a": 1 }));
assert_eq!(signed.sig.len(), 128, "hex Ed25519");

// key order is not content, so a round trip through JSON still verifies
let wire = serde_json::to_string(&signed).unwrap();
let back: Signed = serde_json::from_str(&wire).unwrap();
assert!(verify_signed(&node.public.public_key, Domain::SyncRequest, &back));

One stream: a run of one runtime of one node. <node 32 hex>-<runtime 16 hex>-<instance 16 hex>. The node is the machine's key, the runtime is one checkout's server on that machine, the instance is one process run of that server — so two worktrees on one machine are two streams, and a restart is a new stream of the same runtime.

Numbering events within a stream rather than globally is what makes replication cheap and unambiguous: a gap in one stream is visible without coordinating with anyone, and (stream, seq) identifies an event on every machine that holds it.

use majordomus_cli::mesh::journal::StreamId;

let id = StreamId::new(&"a".repeat(32), &"b".repeat(16), &"c".repeat(16)).unwrap();
assert_eq!(id.node(), "a".repeat(32));
assert_eq!(id.runtime(), "b".repeat(16));

// a restart is a new stream, and the same runtime
let after = StreamId::new(&"a".repeat(32), &"b".repeat(16), &"d".repeat(16)).unwrap();
assert_ne!(after, id);
assert_eq!(after.runtime_key(), id.runtime_key());

Whether a stream is speaking now, on this runtime's clock. It is a verdict about a stream and not about a link: a runtime reachable only through a relay is alive, and a runtime that crashed stops beating for everyone at once. Own is kept apart from Live because a runtime's own stream needs no evidence — it is the thing doing the beating.

use majordomus_cli::mesh::journal::StreamLiveness;

assert!(StreamLiveness::Own.is_alive() && StreamLiveness::Live.is_alive());
assert!(!StreamLiveness::Expired.is_alive());
assert_eq!(
    serde_json::to_value(StreamLiveness::Expired).unwrap(),
    serde_json::json!("expired"),
);

One stream's liveness.

The registry's tallies, for status and health.

What the policy decided about one node.

What an operation wrote, as its answer to the caller. Every mesh operation is an event appended to this runtime's journal, and the caller is handed the three facts it cannot work out for itself: the mesh-wide key of the thing it created, the event that says so, and the Lamport stamp that places it against everyone else's events.

The key is what a later operation is addressed by — a claim is released by the key its acquisition returned, never by the local name it was given — and the stamp is what a caller waiting for a peer to catch up compares against.

#### use std::sync::Arc;
#### use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};
#### use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};
#### use majordomus_cli::mesh::identity::NodeIdentity;
#### use majordomus_cli::mesh::link::HttpTransport;
#### use majordomus_cli::mesh::registry::MeshRegistry;
#### use majordomus_cli::mesh::repository::of_root_commits;
#### let cooperation = Cooperation::new(CooperationSetup {
####     identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: "0000000000000001".into(),
####     repository: of_root_commits(&["root".into()]), endpoints: vec!["127.0.0.1:9".into()],
####     version: "doc".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),
####     journal_path: None, registry: Arc::new(MeshRegistry::new()),
####     transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),
#### }).unwrap();
use majordomus_cli::mesh::cooperation::Written;
use majordomus_cli::mesh::journal::{ClaimMode, Durability, SessionInfo};

let session = SessionInfo::named("s1", "cli");
let written: Written = cooperation
    .claim(&session, vec!["docs".into()], None, ClaimMode::Advisory, None)
    .unwrap();
assert!(written.lamport > 0, "placed against every other runtime's events");
assert_eq!(written.durability, Durability::Memory, "this journal has no file");

// and the key it returned is how the claim is addressed from here on
cooperation.release(&written.key).unwrap();