mesh.cooperation
Whether this runtime cooperates and why not when it does not: its runtime and stream, the repository identity links are matched on, the link protocol and features, the heartbeat and expiry, every linked peer with its link state, last exchange, round trip and failures, every refused candidate with the rule that refused it, and the counters of handshakes, syncs, reconnects, expiries, replicated and refused events.
Whether this runtime cooperates and why not when it does not: its runtime and stream, the repository identity links are matched on, the link protocol and features, the heartbeat and expiry, every linked peer with its link state, last exchange, round trip and failures, every refused candidate with the rule that refused it, and the counters of handshakes, syncs, reconnects, expiries, replicated and refused events.
- query
- experimental
- module mesh
- #mesh
- #coordination
- #cooperation
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_mesh_cooperation |
| HTTP | GET /api/v1/mesh/cooperation operationId mesh.cooperation |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · Empty
No input.
No properties: the capability takes no input.
JSON Schema
{
"additionalProperties": false,
"description": "No input.",
"title": "Empty",
"type": "object"
}output · CooperationStatus
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");| property | type | required | description |
|---|---|---|---|
| active | boolean | yes | Whether cooperation runs in this process. |
| counters | reference | yes | Counters. |
| endpoints | array | yes | Where this runtime answers. |
| expiry_seconds | integer | yes | Seconds of silence before expiry. |
| features | array | yes | The link features carried. |
| heartbeat_seconds | integer | yes | Seconds between heartbeats. |
| journal | reference | yes | The journal's tallies. |
| peers | array | yes | Every linked peer, by runtime key. |
| protocol | array | yes | The link protocol range spoken. |
| reason | string | null | no | Why not, when it does not. |
| refused | array | yes | Candidates refused, by endpoint. |
| repository | one of 2 | no | The repository identity links are matched on. |
| runtime | string | null | no | This runtime, <node>-<runtime>. |
| seeds | array | yes | The declared seeds. |
| started_at | string | null | no | When cooperation started, RFC 3339. |
| stream | one of 2 | no | This runtime's current stream. |
JSON Schema
{
"$defs": {
"CooperationCounters": {
"description": "The link and replication counters since start: what this runtime did, not what it\nholds. They are monotonic and never reset, so two readings a minute apart are a rate —\nwhich is the only way to tell a mesh that is working from one that is retrying, since\nboth show the same peers in the same states.\n\nThe counts are split by direction throughout (`handshakes_out` against\n`handshakes_in`, `refused_in` against `refused_out`) because a runtime that refuses\neveryone and one that everyone refuses need opposite remedies.\n\n```\n# use std::collections::BTreeMap;\n# use std::sync::{Arc, Mutex, Weak};\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::*;\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};\n# use majordomus_cli::mesh::trust::TrustPolicy;\n# #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);\n# impl LinkTransport for Net {\n# fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {\n# let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))\n# .ok_or_else(|| format!(\"{e}: nobody there\"))?;\n# Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }\n# let net = Arc::new(Net::default());\n# let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {\n# identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),\n# repository: of_root_commits(&[\"root\".into()]), endpoints: vec![endpoint.into()],\n# version: \"doc\".into(), config: CooperationConfig::default(),\n# trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,\n# registry: Arc::new(MeshRegistry::new()),\n# transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,\n# checkout: CheckoutFacts::default() }).unwrap();\n# net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };\n# let (a, b) = (runtime(\"a:1\"), runtime(\"b:1\"));\nlet key = a.dial(&[\"b:1\".into()]).unwrap();\na.sync_with(&key).unwrap();\n\nlet dialer: CooperationCounters = a.status().counters;\nlet answerer = b.status().counters;\nassert_eq!((dialer.handshakes_out, dialer.syncs_out), (1, 1));\nassert_eq!((answerer.handshakes_in, answerer.syncs_in), (1, 1), \"the other side of it\");\nassert_eq!(answerer.handshakes_out, 0, \"B never dialed anybody\");\n```",
"properties": {
"claims_refused": {
"description": "Claims refused for a conflict.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"dial_failures": {
"description": "Dials that reached no endpoint.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events_sent": {
"description": "Events pushed in sync requests.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events_served": {
"description": "Events served in sync answers.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"handshakes_in": {
"description": "Handshakes this runtime accepted.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"handshakes_out": {
"description": "Handshakes this runtime completed as the dialer.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"peers_expired": {
"description": "Links expired.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"reconnects": {
"description": "Re-handshakes after an expiry or a dropped link.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"refused_in": {
"additionalProperties": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"description": "Hellos and syncs this runtime refused, by code.",
"type": "object"
},
"refused_out": {
"additionalProperties": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"description": "Refusals this runtime received or applied to a welcome, by code.",
"type": "object"
},
"restarts": {
"description": "Peer restarts observed.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"syncs_failed": {
"description": "Sync rounds that failed in transport.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"syncs_in": {
"description": "Sync rounds this runtime answered.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"syncs_out": {
"description": "Sync rounds this runtime completed as the dialer.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"threads": {
"description": "Cooperation threads alive now.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"handshakes_out",
"handshakes_in",
"dial_failures",
"syncs_out",
"syncs_failed",
"syncs_in",
"events_sent",
"events_served",
"reconnects",
"restarts",
"peers_expired",
"claims_refused",
"threads",
"refused_in",
"refused_out"
],
"type": "object"
},
"JournalTallies": {
"description": "The journal's counters since start: how much it holds, how much it has written,\nreceived, absorbed, refused, held back and compacted away. They are what makes a\nreplication problem diagnosable from one machine — a runtime whose `received` never\nrises is not linked, one whose `rejected` rises is being sent something it will not\ntake, and one whose `pending` stays high is missing an event ahead of what it has.\n\n```\nuse std::sync::Arc;\nuse majordomus_cli::mesh::identity::NodeIdentity;\nuse majordomus_cli::mesh::journal::{EventBody, Journal, JournalTallies};\n\nlet j = Journal::open(Arc::new(NodeIdentity::ephemeral().unwrap()), \"0000000000000001\",\n \"repo\".into(), None).unwrap();\nlet before: JournalTallies = j.tallies();\nassert_eq!((before.written, before.events), (0, 0));\n\nj.append_own(EventBody::SessionClosed { session: \"s1\".into() }).unwrap();\nlet after = j.tallies();\nassert_eq!((after.written, after.events, after.streams), (1, 1, 1));\nassert!(after.lamport > before.lamport);\n```",
"properties": {
"compacted": {
"description": "Events dropped by compaction since start.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"duplicates": {
"description": "Duplicate deliveries absorbed.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events": {
"description": "Events held.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"lamport": {
"description": "The highest Lamport stamp seen.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"opaque": {
"description": "Events of a kind this executable does not interpret, held and relayed.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"pending": {
"description": "Events held for a gap right now.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"received": {
"description": "Events received and stored.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"rejected": {
"description": "Events refused.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"streams": {
"description": "Streams tracked.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"unread_bytes": {
"default": 0,
"description": "Bytes of the journal file the last reload left unread because they lie beyond\n`MAX_RELOAD_BYTES`: on disk and kept by compaction, and not in memory. Nonzero fails\n`mesh doctor`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"unreadable": {
"default": 0,
"description": "Lines of the journal file the last reload could not read: torn, corrupt, or written\nby something that is not this journal. Counted, never silently dropped.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"write_failures": {
"default": 0,
"description": "Appends to the journal file that failed since start: the events were held in memory\nand replicated, and are not on this machine's disk. Nonzero fails `mesh doctor`.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"written": {
"description": "Events written by this runtime since start.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"streams",
"events",
"written",
"received",
"duplicates",
"rejected",
"pending",
"compacted",
"opaque",
"lamport"
],
"type": "object"
},
"LinkRefusal": {
"description": "A refusal: the code, the reason in words, and the protocol range of the refuser so a\nversion mismatch is diagnosable from either end.\n\nCarrying the refuser's protocol range in every refusal, not only in the one about\nprotocols, is what makes a version problem visible from the side that has the log: the\ndialer sees what the answerer speaks without anyone having to read the other machine.\n\n```\nuse majordomus_cli::mesh::link::{LinkRefusal, RefusalCode, LINK_PROTOCOL_MAX};\n\nlet refusal = LinkRefusal::new(RefusalCode::Untrusted, \"the key is not in the allowlist\");\nassert_eq!(refusal.code, RefusalCode::Untrusted);\nassert_eq!(refusal.proto_max, LINK_PROTOCOL_MAX);\nassert_eq!(refusal.to_string(), \"untrusted: the key is not in the allowlist\");\n```",
"properties": {
"code": {
"$ref": "#/$defs/RefusalCode",
"description": "The rule that refused."
},
"detail": {
"description": "Why, in words.",
"type": "string"
},
"proto_max": {
"description": "The refuser's newest protocol.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"proto_min": {
"description": "The refuser's oldest protocol.",
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"code",
"detail",
"proto_min",
"proto_max"
],
"type": "object"
},
"LinkState": {
"description": "A link's standing, from this runtime's side. It is a statement about a connection and\nnever about the peer: a runtime reachable only through a third party is `Expired` here\nwhile its streams beat on everywhere, which is why claims follow streams and not this.\n\nThe variants are ordered by how far the link has fallen, so the worst link in a table\nis the maximum and a reader never has to rank them by hand.\n\n```\nuse majordomus_cli::mesh::cooperation::LinkState;\n\nlet table = [LinkState::Connected, LinkState::Unreachable, LinkState::Degraded];\nassert_eq!(table.iter().max(), Some(&LinkState::Unreachable), \"the worst link shows\");\nassert_eq!(serde_json::to_value(LinkState::Connected).unwrap(), \"connected\");\n```",
"oneOf": [
{
"const": "connecting",
"description": "Handshaking, or never yet exchanged.",
"type": "string"
},
{
"const": "connected",
"description": "An exchange within two heartbeats.",
"type": "string"
},
{
"const": "degraded",
"description": "Rounds are failing; the last exchange is under half the expiry old.",
"type": "string"
},
{
"const": "unreachable",
"description": "The last exchange is over half the expiry old; the link is about to expire.",
"type": "string"
},
{
"const": "expired",
"description": "No exchange within the expiry: the link is dropped and will be re-dialed.",
"type": "string"
}
]
},
"MeshRepositoryBasis": {
"description": "What the repository identity was derived from, which a reader needs in order to judge\nit: an identity taken from the root commits is a fact about the history two clones\nshare, while a declared one is a decision somebody made, and only the second can be\nchanged by editing a file.\n\n```\nuse majordomus_cli::mesh::repository::{declared, of_root_commits, MeshRepositoryBasis};\n\nassert_eq!(declared(\"majordomus\").unwrap().basis, MeshRepositoryBasis::Declared);\nassert_eq!(\n of_root_commits(&[\"a\".repeat(40)]).basis,\n MeshRepositoryBasis::RootCommits,\n);\n```",
"oneOf": [
{
"const": "declared",
"description": "`cooperation.repository` in the mesh declaration.",
"type": "string"
},
{
"const": "root_commits",
"description": "The repository's root commits.",
"type": "string"
}
]
},
"MeshRepositoryIdentity": {
"description": "A repository's mesh identity, carried by every advertisement, link and event, together\nwith the account of where it came from. The `detail` exists so that a person told two\ncheckouts are not the same repository can see what each one was derived from instead of\ncomparing two opaque digests.\n\n```\nuse majordomus_cli::mesh::repository::MeshRepositoryIdentity;\nuse majordomus_cli::mesh::repository::of_root_commits;\n\nlet identity: MeshRepositoryIdentity = of_root_commits(&[\"a\".repeat(40)]);\nassert_eq!(identity.id.len(), 32, \"32 hex characters, on every machine\");\nassert_eq!(identity.detail, \"aaaaaaaaaaaa\", \"the evidence, short enough to read\");\n```",
"properties": {
"basis": {
"$ref": "#/$defs/MeshRepositoryBasis",
"description": "What it was derived from."
},
"detail": {
"description": "The evidence, human-readable: the declared value, or the root commits.",
"type": "string"
},
"id": {
"description": "32 hex: what advertisements, links and events carry.",
"type": "string"
}
},
"required": [
"id",
"basis",
"detail"
],
"type": "object"
},
"PeerView": {
"description": "One peer as every surface shows it: who it is, how this runtime reaches it, and what\nthe link has been through. The counters are carried per peer rather than only in the\ntotals because the question a person asks of a flapping mesh is which peer is flapping,\nand `restarts` answers a different one from `reconnects` — a peer whose process keeps\ndying, against a link that keeps dropping under a process that never did.\n\n```\n# use std::collections::BTreeMap;\n# use std::sync::{Arc, Mutex, Weak};\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::*;\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::{LinkReply, LinkTransport, Signed, HELLO_PATH};\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};\n# use majordomus_cli::mesh::trust::TrustPolicy;\n# #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);\n# impl LinkTransport for Net {\n# fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {\n# let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))\n# .ok_or_else(|| format!(\"{e}: nobody there\"))?;\n# Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }\n# let net = Arc::new(Net::default());\n# let runtime = |endpoint: &str| { let c = Cooperation::new(CooperationSetup {\n# identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),\n# repository: of_root_commits(&[\"root\".into()]), endpoints: vec![endpoint.into()],\n# version: \"doc\".into(), config: CooperationConfig::default(),\n# trust: TrustConfig { policy: TrustPolicy::Tofu, allow: vec![] }, journal_path: None,\n# registry: Arc::new(MeshRegistry::new()),\n# transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,\n# checkout: CheckoutFacts::default() }).unwrap();\n# net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };\n# let (a, b) = (runtime(\"a:1\"), runtime(\"b:1\"));\na.dial(&[\"b:1\".into()]).unwrap();\n\nlet peer: &PeerView = &a.peers()[0];\nassert_eq!(peer.runtime, b.runtime_key(), \"the durable identity, not the endpoint\");\nassert!(peer.outbound, \"this runtime dials it\");\nassert_eq!(peer.handshakes, 1);\nassert_eq!(peer.restarts, 0, \"the peer's process has not died under the link\");\n```",
"properties": {
"endpoint": {
"description": "The endpoint this runtime dials, when it does.",
"type": [
"string",
"null"
]
},
"endpoints": {
"description": "Where the peer answers.",
"items": {
"type": "string"
},
"type": "array"
},
"failures": {
"description": "Consecutive failed rounds.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"features": {
"description": "The link features the peer carries.",
"items": {
"type": "string"
},
"type": "array"
},
"handshakes": {
"description": "Handshakes completed with this peer.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"inbound": {
"description": "Whether the peer dials this runtime.",
"type": "boolean"
},
"instance": {
"description": "The current instance.",
"type": "string"
},
"last_error": {
"description": "The last failure, in words.",
"type": [
"string",
"null"
]
},
"last_exchange_ms": {
"description": "Milliseconds since the last successful exchange in either direction.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"linked_at": {
"description": "When the current link was established, RFC 3339.",
"type": "string"
},
"local": {
"description": "Whether the peer runs on this machine (the same node key).",
"type": "boolean"
},
"name": {
"description": "The node's display name.",
"type": "string"
},
"node": {
"description": "The node (machine key digest).",
"type": "string"
},
"outbound": {
"description": "Whether this runtime dials the peer.",
"type": "boolean"
},
"protocol": {
"description": "The negotiated link protocol.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"reconnects": {
"description": "Handshakes after an expiry or a dropped link.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"restarts": {
"description": "New instances of the peer seen (its process restarted).",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"rtt_ms": {
"description": "The last round trip, milliseconds.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"runtime": {
"description": "`<node>-<runtime>`: the peer's durable identity.",
"type": "string"
},
"state": {
"$ref": "#/$defs/LinkState",
"description": "The link's standing."
},
"trust": {
"$ref": "#/$defs/TrustState",
"description": "The trust verdict the link was admitted under."
},
"version": {
"description": "The executable version.",
"type": "string"
}
},
"required": [
"runtime",
"node",
"instance",
"name",
"version",
"local",
"trust",
"protocol",
"features",
"endpoints",
"state",
"outbound",
"inbound",
"failures",
"handshakes",
"reconnects",
"restarts",
"linked_at"
],
"type": "object"
},
"RefusalCode": {
"description": "Why a link message was turned down. Every refusal is typed, counted and shown: a mesh\nthat refuses a peer says which rule did, instead of dropping a socket.\n\nThe codes are the diagnosis a person needs when two runtimes will not link, and they\nare deliberately distinct where the remedies differ: `Untrusted` is a key to add,\n`RepositoryMismatch` is two different repositories, `SelfLink` is a configuration that\ndials its own endpoint, and `UnknownLink` is not a failure at all but an instruction to\nsay hello again.\n\n```\nuse majordomus_cli::mesh::link::RefusalCode;\n\n// the wire word is the code's identity across surfaces, and it is stable\nassert_eq!(RefusalCode::RepositoryMismatch.as_str(), \"repository_mismatch\");\nassert_eq!(\n serde_json::to_value(RefusalCode::Untrusted).unwrap(),\n serde_json::json!(\"untrusted\"),\n);\nassert_ne!(RefusalCode::Untrusted, RefusalCode::RepositoryMismatch);\n```",
"oneOf": [
{
"const": "malformed",
"description": "Not the shape of the message.",
"type": "string"
},
{
"const": "oversized",
"description": "Over `MAX_LINK_MESSAGE`.",
"type": "string"
},
{
"const": "protocol_unsupported",
"description": "The protocol ranges do not meet.",
"type": "string"
},
{
"const": "signature",
"description": "The signature does not verify.",
"type": "string"
},
{
"const": "stale",
"description": "The timestamp is outside the skew window.",
"type": "string"
},
{
"const": "replay",
"description": "A nonce or a counter already seen.",
"type": "string"
},
{
"const": "repository_mismatch",
"description": "The peer serves another repository: the isolation rule.",
"type": "string"
},
{
"const": "untrusted",
"description": "The peer's key is not trusted by this runtime's policy: discovery is not trust.",
"type": "string"
},
{
"const": "self_link",
"description": "The peer is this very runtime.",
"type": "string"
},
{
"const": "not_active",
"description": "This runtime's cooperation is not active.",
"type": "string"
},
{
"const": "unknown_link",
"description": "The link id is unknown here: the answerer restarted or expired the link; say hello.",
"type": "string"
},
{
"const": "capacity",
"description": "A bound of this runtime is full.",
"type": "string"
},
{
"const": "feature_unsupported",
"description": "The peer lacks a feature the operation needs.",
"type": "string"
},
{
"const": "misaddressed",
"description": "A hello addressed to another runtime: captured on its way there and replayed here.",
"type": "string"
}
]
},
"RefusedView": {
"description": "A candidate that was refused, with the rule that refused it. A refusal is kept and\nshown rather than logged and dropped, because the commonest mesh failure is a link that\nnever forms: a person who declared a seed and sees no peer needs the decision that was\nmade about it — the wrong repository, a key nobody allowed, a clock too far out — and\nthe direction says which side made it.\n\n```\n# use std::collections::BTreeMap;\n# use std::sync::{Arc, Mutex, Weak};\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::*;\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::{LinkReply, LinkTransport, RefusalCode, Signed, HELLO_PATH};\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::{of_root_commits, runtime_id};\n# use majordomus_cli::mesh::trust::TrustPolicy;\n# #[derive(Default)] struct Net(Mutex<BTreeMap<String, Weak<Cooperation>>>);\n# impl LinkTransport for Net {\n# fn post(&self, e: &str, p: &str, m: &Signed) -> Result<LinkReply, String> {\n# let peer = (self.0.lock().unwrap().get(e).and_then(Weak::upgrade))\n# .ok_or_else(|| format!(\"{e}: nobody there\"))?;\n# Ok(if p == HELLO_PATH { peer.accept_hello(m) } else { peer.accept_sync(m) }) } }\n# let net = Arc::new(Net::default());\n# let runtime = |endpoint: &str, policy: TrustPolicy| {\n# let c = Cooperation::new(CooperationSetup {\n# identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: runtime_id(endpoint),\n# repository: of_root_commits(&[\"root\".into()]), endpoints: vec![endpoint.into()],\n# version: \"doc\".into(), config: CooperationConfig::default(),\n# trust: TrustConfig { policy, allow: vec![] }, journal_path: None,\n# registry: Arc::new(MeshRegistry::new()),\n# transport: Arc::clone(&net) as Arc<dyn LinkTransport>, board: None,\n# checkout: CheckoutFacts::default() }).unwrap();\n# net.0.lock().unwrap().insert(endpoint.into(), Arc::downgrade(&c)); c };\n# let a = runtime(\"a:1\", TrustPolicy::Tofu);\n# let strict = runtime(\"s:1\", TrustPolicy::DenyUnknown);\na.dial(&[\"s:1\".into()]).expect_err(\"reachable, and not trusted\");\n\nlet refused: &RefusedView = &strict.status().refused[0];\nassert_eq!(refused.refusal.code, RefusalCode::Untrusted);\nassert_eq!(refused.direction, \"inbound\", \"this runtime refused the hello\");\nassert_eq!(refused.runtime.as_deref(), Some(a.runtime_key()));\n```",
"properties": {
"at": {
"description": "When, RFC 3339.",
"type": "string"
},
"direction": {
"description": "`outbound` (this runtime refused the peer's welcome, or the peer refused this\nhello) or `inbound` (this runtime refused the peer's hello).",
"type": "string"
},
"endpoint": {
"description": "The endpoint dialed, or `inbound:<runtime>` for a refused hello.",
"type": "string"
},
"refusal": {
"$ref": "#/$defs/LinkRefusal",
"description": "The refusal."
},
"runtime": {
"description": "The peer's runtime key, when its card said.",
"type": [
"string",
"null"
]
}
},
"required": [
"endpoint",
"direction",
"refusal",
"at"
],
"type": "object"
},
"StreamId": {
"description": "One stream: a run of one runtime of one node. `<node 32 hex>-<runtime 16 hex>-<instance\n16 hex>`. The node is the machine's key, the runtime is one checkout's server on that\nmachine, the instance is one process run of that server — so two worktrees on one\nmachine are two streams, and a restart is a new stream of the same runtime.\n\nNumbering events within a stream rather than globally is what makes replication cheap\nand unambiguous: a gap in one stream is visible without coordinating with anyone, and\n`(stream, seq)` identifies an event on every machine that holds it.\n\n```\nuse majordomus_cli::mesh::journal::StreamId;\n\nlet id = StreamId::new(&\"a\".repeat(32), &\"b\".repeat(16), &\"c\".repeat(16)).unwrap();\nassert_eq!(id.node(), \"a\".repeat(32));\nassert_eq!(id.runtime(), \"b\".repeat(16));\n\n// a restart is a new stream, and the same runtime\nlet after = StreamId::new(&\"a\".repeat(32), &\"b\".repeat(16), &\"d\".repeat(16)).unwrap();\nassert_ne!(after, id);\nassert_eq!(after.runtime_key(), id.runtime_key());\n```",
"type": "string"
},
"TrustState": {
"description": "What the policy decided about one node.",
"oneOf": [
{
"description": "Valid, recorded, trusted for nothing. The resting state of an unknown node.",
"properties": {
"state": {
"const": "observed",
"type": "string"
}
},
"required": [
"state"
],
"type": "object"
},
{
"description": "The policy trusts this key; `detail` says which rule did (`allowlist`, `tofu`).",
"properties": {
"detail": {
"type": "string"
},
"state": {
"const": "trusted",
"type": "string"
}
},
"required": [
"state",
"detail"
],
"type": "object"
},
{
"description": "The policy rejected this node; `detail` says why (for instance a TOFU key\nchange). A rejected node stays listed — an operator debugging a mesh needs to\nsee what was refused, not wonder about silence.",
"properties": {
"detail": {
"type": "string"
},
"state": {
"const": "rejected",
"type": "string"
}
},
"required": [
"state",
"detail"
],
"type": "object"
}
]
}
},
"description": "The whole cooperation runtime, as every surface reports it: the command line, the HTTP\nsurface and MCP all render this one value, so that a person and an agent asking the same\nquestion of the same runtime are never told different things.\n\nIt answers in one reading the three questions a mesh raises — is this runtime\ncooperating at all, what does it speak, and who is it linked to — and it stays\nanswerable when the answer is no: an inactive runtime still reports its protocol range\nand the reason, rather than an absence the caller has to interpret.\n\n```\n# use std::sync::Arc;\n# use majordomus_cli::mesh::config::{CooperationConfig, TrustConfig};\n# use majordomus_cli::mesh::cooperation::{CheckoutFacts, Cooperation, CooperationSetup};\n# use majordomus_cli::mesh::identity::NodeIdentity;\n# use majordomus_cli::mesh::link::HttpTransport;\n# use majordomus_cli::mesh::registry::MeshRegistry;\n# use majordomus_cli::mesh::repository::of_root_commits;\n# let cooperation = Cooperation::new(CooperationSetup {\n# identity: Arc::new(NodeIdentity::ephemeral().unwrap()), runtime: \"0000000000000001\".into(),\n# repository: of_root_commits(&[\"root\".into()]), endpoints: vec![\"127.0.0.1:9\".into()],\n# version: \"doc\".into(), config: CooperationConfig::default(), trust: TrustConfig::default(),\n# journal_path: None, registry: Arc::new(MeshRegistry::new()),\n# transport: Arc::new(HttpTransport), board: None, checkout: CheckoutFacts::default(),\n# }).unwrap();\nuse majordomus_cli::mesh::cooperation::CooperationStatus;\n\nlet running: CooperationStatus = cooperation.status();\nassert_eq!(running.runtime.as_deref(), Some(cooperation.runtime_key()));\nassert!(running.peers.is_empty(), \"nothing is dialed until something dials\");\n\n// and where there is no runtime at all, the same shape says why\nlet none = CooperationStatus::inactive(\"the mesh declaration is disabled\");\nassert_eq!(none.protocol, running.protocol, \"still answerable about what it speaks\");\n```",
"properties": {
"active": {
"description": "Whether cooperation runs in this process.",
"type": "boolean"
},
"counters": {
"$ref": "#/$defs/CooperationCounters",
"description": "Counters."
},
"endpoints": {
"description": "Where this runtime answers.",
"items": {
"type": "string"
},
"type": "array"
},
"expiry_seconds": {
"description": "Seconds of silence before expiry.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"features": {
"description": "The link features carried.",
"items": {
"type": "string"
},
"type": "array"
},
"heartbeat_seconds": {
"description": "Seconds between heartbeats.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"journal": {
"$ref": "#/$defs/JournalTallies",
"description": "The journal's tallies."
},
"peers": {
"description": "Every linked peer, by runtime key.",
"items": {
"$ref": "#/$defs/PeerView"
},
"type": "array"
},
"protocol": {
"description": "The link protocol range spoken.",
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"format": "uint32",
"minimum": 0,
"type": "integer"
},
{
"format": "uint32",
"minimum": 0,
"type": "integer"
}
],
"type": "array"
},
"reason": {
"description": "Why not, when it does not.",
"type": [
"string",
"null"
]
},
"refused": {
"description": "Candidates refused, by endpoint.",
"items": {
"$ref": "#/$defs/RefusedView"
},
"type": "array"
},
"repository": {
"anyOf": [
{
"$ref": "#/$defs/MeshRepositoryIdentity"
},
{
"type": "null"
}
],
"description": "The repository identity links are matched on."
},
"runtime": {
"description": "This runtime, `<node>-<runtime>`.",
"type": [
"string",
"null"
]
},
"seeds": {
"description": "The declared seeds.",
"items": {
"type": "string"
},
"type": "array"
},
"started_at": {
"description": "When cooperation started, RFC 3339.",
"type": [
"string",
"null"
]
},
"stream": {
"anyOf": [
{
"$ref": "#/$defs/StreamId"
},
{
"type": "null"
}
],
"description": "This runtime's current stream."
}
},
"required": [
"active",
"protocol",
"features",
"heartbeat_seconds",
"expiry_seconds",
"endpoints",
"seeds",
"peers",
"refused",
"counters",
"journal"
],
"title": "CooperationStatus",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.