mesh-contracts/seats/mesh-placement/seat.json

{
  "format": 1,
  "seat": "mesh-placement",
  "scope": "mesh",
  "grain": "seat-list",
  "decision": "novox/hq ADR 0567",
  "verbs": [
    {
      "name": "placement",
      "description": "Read placement: one node's key, the nodes one module is placed on, or every key, each with its revision, and how full the state is against its cap. With history, one node's or one module's changes in order: a revision the state keeps whole, an older one as the proposal's changes from its placement-changed event.",
      "optional": true,
      "input": {
        "properties": {
          "history": {
            "description": "\"true\": the changes in order, from the stream and the state's revisions",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "module": {
            "description": "one module: the nodes it is placed on",
            "type": "string"
          },
          "node": {
            "description": "one node",
            "type": "string"
          },
          "seats": {
            "description": "\"true\": who holds each seat, and on which node (the state seat-holders); with node, that node's",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "proposals",
      "description": "Every open proposal of placement: its changes, the revision of each key it was laid over, its candidates, every node's answer, the differences computed and answered, its verdict and its ask. Narrowed to one by id.",
      "optional": true,
      "input": {
        "properties": {
          "id": {
            "description": "one proposal's id",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "propose",
      "description": "Propose a change of placement, with why: laid over the current keys and refused at once, naming every finding, when the result cannot be placed (two modules on one host port, a provider not placed, a seat held once held twice, two nodes with one address, two hubs, a module the indexer does not hold, a node with no record). Otherwise the nodes it touches compose it in shadow and answer, and on a passing verdict the operator is asked to approve it. Who proposes is the caller, as the runtime proves it. An add-node from mesh-enrolment, whose warrant names its node and address, is written with no ask of its own: its Approve is the enrolment's (ADR 0587 §7).",
      "optional": true,
      "input": {
        "additionalProperties": false,
        "properties": {
          "changes": {
            "description": "the changes, each an object with `op`: place (node, module, ports, bindings), take-off (node, module), pin (node, provision, provider {node, module}), unpin (node, provision), hold (node, module, claim, scope, kind, site), unhold (node, module, claim), decide (node, field, value: a decided field of the node, its address among them), config (node, module, mesh-wide, layer, mesh-wide-values, values), add-node (node, decided, keys: a joining node, mesh-enrolment's alone, the proposal's one change, with the enrolment's warrant, its tunnel key alone at the operator's yes; ADR 0587 §7), remove-node (node: a joining node never confirmed, taken off when its enrolment ends; mesh-enrolment's alone, on the same warrant)",
            "items": {
              "required": [
                "op",
                "node"
              ],
              "type": "object"
            },
            "minItems": 1,
            "type": "array"
          },
          "warrant": {
            "description": "for an add-node alone: the enrolment's warrant {node, address, ask, warrant}, naming the change's node and address",
            "required": [
              "node",
              "address",
              "ask",
              "warrant"
            ],
            "type": "object"
          },
          "why": {
            "description": "why, shown to the operator with the proposal",
            "type": "string"
          }
        },
        "required": [
          "why",
          "changes"
        ],
        "type": "object"
      }
    },
    {
      "name": "withdraw",
      "description": "Withdraw an open proposal: its key and its candidates are deleted and placement-withdrawn carries it whole. With why.",
      "optional": true,
      "input": {
        "properties": {
          "id": {
            "description": "the proposal's id",
            "type": "string"
          },
          "why": {
            "description": "why, kept in the event",
            "type": "string"
          }
        },
        "required": [
          "id",
          "why"
        ],
        "type": "object"
      }
    },
    {
      "name": "again",
      "description": "Judge an open proposal now with the answers that stand, and raise its ask again when its verdict passes and the operator's channel does not hold the ask. Nothing more: the recovery of a proposal whose judgement or ask was lost.",
      "optional": true,
      "input": {
        "properties": {
          "id": {
            "description": "the proposal's id",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      }
    }
  ]
}