mesh.cooperation

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Whether cooperation runs in this process."
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why not, when it does not."
    },
    "runtime": {
      "type": [
        "string",
        "null"
      ],
      "description": "This runtime, `<node>-<runtime>`."
    },
    "stream": {
      "anyOf": [
        {
          "$ref": "#/$defs/StreamId"
        },
        {
          "type": "null"
        }
      ],
      "description": "This runtime's current stream."
    },
    "repository": {
      "anyOf": [
        {
          "$ref": "#/$defs/MeshRepositoryIdentity"
        },
        {
          "type": "null"
        }
      ],
      "description": "The repository identity links are matched on."
    },
    "protocol": {
      "type": "array",
      "prefixItems": [
        {
          "type": "integer",
          "format": "uint32",
          "minimum": 0
        },
        {
          "type": "integer",
          "format": "uint32",
          "minimum": 0
        }
      ],
      "minItems": 2,
      "maxItems": 2,
      "description": "The link protocol range spoken."
    },
    "features": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The link features carried."
    },
    "heartbeat_seconds": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "Seconds between heartbeats."
    },
    "expiry_seconds": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "Seconds of silence before expiry."
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Where this runtime answers."
    },
    "seeds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The declared seeds."
    },
    "peers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PeerView"
      },
      "description": "Every linked peer, by runtime key."
    },
    "refused": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RefusedView"
      },
      "description": "Candidates refused, by endpoint."
    },
    "counters": {
      "$ref": "#/$defs/CooperationCounters",
      "description": "Counters."
    },
    "journal": {
      "$ref": "#/$defs/JournalTallies",
      "description": "The journal's tallies."
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When cooperation started, RFC 3339."
    }
  },
  "required": [
    "active",
    "protocol",
    "features",
    "heartbeat_seconds",
    "expiry_seconds",
    "endpoints",
    "seeds",
    "peers",
    "refused",
    "counters",
    "journal"
  ],
  "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```",
  "title": "CooperationStatus",
  "$defs": {
    "StreamId": {
      "type": "string",
      "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```"
    },
    "MeshRepositoryIdentity": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "32 hex: what advertisements, links and events carry."
        },
        "basis": {
          "$ref": "#/$defs/MeshRepositoryBasis",
          "description": "What it was derived from."
        },
        "detail": {
          "type": "string",
          "description": "The evidence, human-readable: the declared value, or the root commits."
        }
      },
      "required": [
        "id",
        "basis",
        "detail"
      ],
      "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```"
    },
    "MeshRepositoryBasis": {
      "oneOf": [
        {
          "type": "string",
          "const": "declared",
          "description": "`cooperation.repository` in the mesh declaration."
        },
        {
          "type": "string",
          "const": "root_commits",
          "description": "The repository's root commits."
        }
      ],
      "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```"
    },
    "PeerView": {
      "type": "object",
      "properties": {
        "runtime": {
          "type": "string",
          "description": "`<node>-<runtime>`: the peer's durable identity."
        },
        "node": {
          "type": "string",
          "description": "The node (machine key digest)."
        },
        "instance": {
          "type": "string",
          "description": "The current instance."
        },
        "name": {
          "type": "string",
          "description": "The node's display name."
        },
        "version": {
          "type": "string",
          "description": "The executable version."
        },
        "local": {
          "type": "boolean",
          "description": "Whether the peer runs on this machine (the same node key)."
        },
        "trust": {
          "$ref": "#/$defs/TrustState",
          "description": "The trust verdict the link was admitted under."
        },
        "protocol": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "The negotiated link protocol."
        },
        "features": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The link features the peer carries."
        },
        "endpoints": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Where the peer answers."
        },
        "state": {
          "$ref": "#/$defs/LinkState",
          "description": "The link's standing."
        },
        "outbound": {
          "type": "boolean",
          "description": "Whether this runtime dials the peer."
        },
        "inbound": {
          "type": "boolean",
          "description": "Whether the peer dials this runtime."
        },
        "endpoint": {
          "type": [
            "string",
            "null"
          ],
          "description": "The endpoint this runtime dials, when it does."
        },
        "last_exchange_ms": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "Milliseconds since the last successful exchange in either direction."
        },
        "rtt_ms": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "The last round trip, milliseconds."
        },
        "failures": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Consecutive failed rounds."
        },
        "last_error": {
          "type": [
            "string",
            "null"
          ],
          "description": "The last failure, in words."
        },
        "handshakes": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Handshakes completed with this peer."
        },
        "reconnects": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Handshakes after an expiry or a dropped link."
        },
        "restarts": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "New instances of the peer seen (its process restarted)."
        },
        "linked_at": {
          "type": "string",
          "description": "When the current link was established, RFC 3339."
        }
      },
      "required": [
        "runtime",
        "node",
        "instance",
        "name",
        "version",
        "local",
        "trust",
        "protocol",
        "features",
        "endpoints",
        "state",
        "outbound",
        "inbound",
        "failures",
        "handshakes",
        "reconnects",
        "restarts",
        "linked_at"
      ],
      "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```"
    },
    "TrustState": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "observed"
            }
          },
          "required": [
            "state"
          ],
          "description": "Valid, recorded, trusted for nothing. The resting state of an unknown node."
        },
        {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "trusted"
            },
            "detail": {
              "type": "string"
            }
          },
          "required": [
            "state",
            "detail"
          ],
          "description": "The policy trusts this key; `detail` says which rule did (`allowlist`, `tofu`)."
        },
        {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "rejected"
            },
            "detail": {
              "type": "string"
            }
          },
          "required": [
            "state",
            "detail"
          ],
          "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."
        }
      ],
      "description": "What the policy decided about one node."
    },
    "LinkState": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "RefusedView": {
      "type": "object",
      "properties": {
        "endpoint": {
          "type": "string",
          "description": "The endpoint dialed, or `inbound:<runtime>` for a refused hello."
        },
        "direction": {
          "type": "string",
          "description": "`outbound` (this runtime refused the peer's welcome, or the peer refused this\nhello) or `inbound` (this runtime refused the peer's hello)."
        },
        "runtime": {
          "type": [
            "string",
            "null"
          ],
          "description": "The peer's runtime key, when its card said."
        },
        "refusal": {
          "$ref": "#/$defs/LinkRefusal",
          "description": "The refusal."
        },
        "at": {
          "type": "string",
          "description": "When, RFC 3339."
        }
      },
      "required": [
        "endpoint",
        "direction",
        "refusal",
        "at"
      ],
      "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```"
    },
    "LinkRefusal": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/RefusalCode",
          "description": "The rule that refused."
        },
        "detail": {
          "type": "string",
          "description": "Why, in words."
        },
        "proto_min": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "The refuser's oldest protocol."
        },
        "proto_max": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "The refuser's newest protocol."
        }
      },
      "required": [
        "code",
        "detail",
        "proto_min",
        "proto_max"
      ],
      "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```"
    },
    "RefusalCode": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "CooperationCounters": {
      "type": "object",
      "properties": {
        "handshakes_out": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Handshakes this runtime completed as the dialer."
        },
        "handshakes_in": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Handshakes this runtime accepted."
        },
        "dial_failures": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Dials that reached no endpoint."
        },
        "syncs_out": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Sync rounds this runtime completed as the dialer."
        },
        "syncs_failed": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Sync rounds that failed in transport."
        },
        "syncs_in": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Sync rounds this runtime answered."
        },
        "events_sent": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events pushed in sync requests."
        },
        "events_served": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events served in sync answers."
        },
        "reconnects": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Re-handshakes after an expiry or a dropped link."
        },
        "restarts": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Peer restarts observed."
        },
        "peers_expired": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Links expired."
        },
        "claims_refused": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Claims refused for a conflict."
        },
        "threads": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Cooperation threads alive now."
        },
        "refused_in": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          },
          "description": "Hellos and syncs this runtime refused, by code."
        },
        "refused_out": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          },
          "description": "Refusals this runtime received or applied to a welcome, by code."
        }
      },
      "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"
      ],
      "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```"
    },
    "JournalTallies": {
      "type": "object",
      "properties": {
        "streams": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Streams tracked."
        },
        "events": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Events held."
        },
        "written": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events written by this runtime since start."
        },
        "received": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events received and stored."
        },
        "duplicates": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Duplicate deliveries absorbed."
        },
        "rejected": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events refused."
        },
        "pending": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Events held for a gap right now."
        },
        "compacted": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Events dropped by compaction since start."
        },
        "opaque": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Events of a kind this executable does not interpret, held and relayed."
        },
        "lamport": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The highest Lamport stamp seen."
        },
        "write_failures": {
          "type": "integer",
          "format": "uint64",
          "minimum": 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`.",
          "default": 0
        },
        "unreadable": {
          "type": "integer",
          "format": "uint64",
          "minimum": 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.",
          "default": 0
        },
        "unread_bytes": {
          "type": "integer",
          "format": "uint64",
          "minimum": 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`.",
          "default": 0
        }
      },
      "required": [
        "streams",
        "events",
        "written",
        "received",
        "duplicates",
        "rejected",
        "pending",
        "compacted",
        "opaque",
        "lamport"
      ],
      "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```"
    }
  }
}