mesh.nodes

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

{
  "$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"
}