mesh.nodes
Every runtime this process has observed, one record per node and runtime slot, deduplicated across every discovery source, in node-id order: identity, trust, presence, endpoints, capabilities, repositories, provenance and versions. In memory, gone with the process.
Every runtime this process has observed, one record per node and runtime slot, deduplicated across every discovery source, in node-id order: identity, trust, presence, endpoints, capabilities, repositories, provenance and versions. In memory, gone with the process.
- query
- experimental
- module mesh
- #mesh
- #coordination
- #discovery
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_mesh_nodes |
| HTTP | GET /api/v1/mesh/nodes operationId mesh.nodes |
| 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 · NodeList
The answer of
mesh.nodes: every node this process has observed.| property | type | required | description |
|---|---|---|---|
| count | integer | yes | How many nodes the registry holds. |
| nodes | array | yes | The nodes, in node-id order — the one canonical order every surface shows. |
JSON Schema
{
"$defs": {
"InstanceId": {
"description": "One run of a node: 16 hex characters of OS entropy, new at every process start. A\nrestart keeps the node id and changes this, which is how a reader tells \"the same\nnode came back\" from \"the same process is still there\".",
"type": "string"
},
"MeshSource": {
"description": "Where an observation came from. A record accumulates these; provenance is the answer\nto \"why do I see this node\".",
"oneOf": [
{
"const": "udp_multicast",
"description": "A multicast datagram.",
"type": "string"
},
{
"const": "udp_broadcast",
"description": "A broadcast datagram.",
"type": "string"
},
{
"const": "rendezvous",
"description": "A rendezvous answer or registration.",
"type": "string"
},
{
"const": "synthetic",
"description": "A synthetic provider (tests, self-check).",
"type": "string"
}
]
},
"NodeId": {
"description": "The stable identity of a node: 32 hex characters of the SHA-256 of its Ed25519 public\nkey. Derived, never chosen: two nodes with one id hold one key.",
"type": "string"
},
"NodeRecord": {
"description": "One discovered node: the canonical record every surface projects.",
"properties": {
"capabilities": {
"description": "Advertised transports (`http`, `mcp`, `ws`).",
"items": {
"type": "string"
},
"type": "array"
},
"display_name": {
"description": "The node's own display name. Presentation only.",
"type": "string"
},
"endpoints": {
"description": "Advertised `host:port` authorities.",
"items": {
"type": "string"
},
"type": "array"
},
"first_seen": {
"description": "First seen, RFC 3339.",
"type": "string"
},
"instance_id": {
"$ref": "#/$defs/InstanceId",
"description": "The node's current run."
},
"last_seen": {
"description": "Last seen, RFC 3339.",
"type": "string"
},
"node_id": {
"$ref": "#/$defs/NodeId",
"description": "The node id: the digest of the key below."
},
"presence": {
"$ref": "#/$defs/Presence",
"description": "Whether the node is answering now."
},
"protocol_version": {
"description": "The advertised protocol version.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"public_key": {
"description": "The Ed25519 public key that proved this record's advertisements.",
"type": "string"
},
"repositories": {
"description": "Advertised repository digests.",
"items": {
"type": "string"
},
"type": "array"
},
"restarts": {
"description": "How many instances this node id has shown (a restart increments it).",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"runtime": {
"default": "",
"description": "The runtime slot: which server of the node (one per checkout), 16 hex; empty for a\nversion-1 advertisement. A record is one runtime: two worktrees of one machine are\ntwo records under one node id and one key.",
"type": "string"
},
"sources": {
"description": "Every source this node was seen through, most recent sighting per source.",
"items": {
"$ref": "#/$defs/Sighting"
},
"type": "array"
},
"trust": {
"$ref": "#/$defs/TrustState",
"description": "What the policy decided."
},
"version": {
"description": "The advertised executable version.",
"type": "string"
}
},
"required": [
"node_id",
"public_key",
"display_name",
"instance_id",
"trust",
"presence",
"endpoints",
"capabilities",
"repositories",
"protocol_version",
"version",
"sources",
"first_seen",
"last_seen",
"restarts"
],
"type": "object"
},
"Presence": {
"description": "Whether the node is answering now, by its own announcements.",
"oneOf": [
{
"const": "present",
"description": "An advertisement arrived within `PRESENCE_TTL`.",
"type": "string"
},
{
"const": "absent",
"description": "Nothing within the TTL; the node may be gone or unreachable. It stays listed\nuntil `RETENTION` passes, then expires out entirely.",
"type": "string"
}
]
},
"Sighting": {
"description": "One provenance entry: a source, and where the observation physically came from.",
"properties": {
"at": {
"description": "When, RFC 3339.",
"type": "string"
},
"path": {
"description": "The network path, as text: a sender address, an interface, a rendezvous URL.",
"type": "string"
},
"source": {
"$ref": "#/$defs/MeshSource",
"description": "The provider kind that saw it."
}
},
"required": [
"source",
"path",
"at"
],
"type": "object"
},
"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 answer of `mesh.nodes`: every node this process has observed.",
"properties": {
"count": {
"description": "How many nodes the registry holds.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"nodes": {
"description": "The nodes, in node-id order — the one canonical order every surface shows.",
"items": {
"$ref": "#/$defs/NodeRecord"
},
"type": "array"
}
},
"required": [
"count",
"nodes"
],
"title": "NodeList",
"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.