{
  "format": 1,
  "seat": "mesh-config",
  "scope": "mesh",
  "grain": "whole",
  "domain": "Config",
  "decision": "novox/hq ADR 0348, ADR 0565",
  "verbs": [
    {
      "name": "config",
      "description": "Set, clear, list or read the history of config values: mesh config or node config for a predefined key, or a module's own value on one node, each set with why, validated, and naming each module on each node whose value moves.",
      "optional": true,
      "input": {
        "properties": {
          "action": {
            "description": "list (when not given), set, clear or history",
            "type": "string"
          },
          "by": {
            "description": "who gave the value at the controller's terminal",
            "type": "string"
          },
          "key": {
            "description": "the config key",
            "type": "string"
          },
          "limit": {
            "description": "for history: at most this many, newest",
            "type": "number"
          },
          "module": {
            "description": "a module: its own value, with node",
            "type": "string"
          },
          "node": {
            "description": "a node",
            "type": "string"
          },
          "value": {
            "description": "for set: the value, of the key's type: a number, a string, a boolean, or for a trusted key an object or a list"
          },
          "why": {
            "description": "for set and clear: why",
            "type": "string"
          }
        },
        "type": "object"
      },
      "answer": {
        "type": "object",
        "description": "the values asked, or the one set or cleared, or its history"
      }
    },
    {
      "name": "renames",
      "optional": true,
      "description": "The open renames of config values (design 32 *A config value renamed*): per rename the module, the old and new name, when it moved, and the nodes still holding the old name open.",
      "input": {
        "type": "object",
        "properties": {
          "module": {
            "type": "string",
            "description": "one module (optional)"
          }
        }
      },
      "callers": "any caller whose role grants it; the checker asks it",
      "answer": {
        "type": "object",
        "properties": {
          "renames": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "module": {
                  "type": "string",
                  "description": "the module"
                },
                "from": {
                  "type": "string",
                  "description": "the old name"
                },
                "to": {
                  "type": "string",
                  "description": "the new name"
                },
                "at": {
                  "type": "string",
                  "description": "when it moved, RFC 3339"
                },
                "open": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "the nodes still holding the old name open"
                }
              },
              "required": [
                "module",
                "from",
                "to"
              ]
            },
            "description": "every open rename"
          }
        },
        "required": [
          "renames"
        ]
      }
    }
  ],
  "description": "The mesh's config values: read and set one, and the renames still open. mesh-config's own events stay under its own subjects (ADR 0620 §2).",
  "holder-events": [
    {
      "name": "config-changed",
      "subject": "mesh.mod.<holder>.event.config-changed"
    },
    {
      "name": "renamed",
      "subject": "mesh.stream.<holder>.event.renamed",
      "family": "config.events",
      "body": {
        "type": "object",
        "properties": {
          "module": {
            "type": "string",
            "description": "the module"
          },
          "from": {
            "type": "string",
            "description": "the old name"
          },
          "to": {
            "type": "string",
            "description": "the new name"
          },
          "at": {
            "type": "string",
            "description": "when, RFC 3339"
          }
        },
        "required": [
          "module",
          "from",
          "to",
          "at"
        ]
      }
    },
    {
      "name": "retiring",
      "subject": "mesh.stream.<holder>.event.retiring",
      "family": "config.events",
      "body": {
        "type": "object",
        "properties": {
          "module": {
            "type": "string",
            "description": "the module"
          },
          "key": {
            "type": "string",
            "description": "the value's or secret's name"
          },
          "kind": {
            "type": "string",
            "enum": [
              "value",
              "secret"
            ]
          },
          "since": {
            "type": "string",
            "description": "since when, RFC 3339"
          },
          "ask": {
            "type": "string",
            "description": "the ask's id"
          }
        },
        "required": [
          "module",
          "key",
          "kind",
          "since"
        ]
      }
    },
    {
      "name": "retired",
      "subject": "mesh.stream.<holder>.event.retired",
      "family": "config.events",
      "body": {
        "type": "object",
        "properties": {
          "module": {
            "type": "string",
            "description": "the module"
          },
          "name": {
            "type": "string",
            "description": "the name"
          },
          "node": {
            "type": "string",
            "description": "the node"
          },
          "ask": {
            "type": "string",
            "description": "the ask's id"
          }
        },
        "required": [
          "module",
          "name"
        ]
      }
    }
  ],
  "states": [
    {
      "name": "resolved",
      "template": "state",
      "key-forms": [
        {
          "key": "<node>.<module>.<key>",
          "value": {
            "type": "object",
            "description": "the value a module on a node takes for a config key, and where it came from",
            "properties": {
              "node": {
                "type": "string"
              },
              "module": {
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "value": {},
              "source": {
                "type": "string"
              },
              "predefined": {
                "type": "string",
                "description": "the predefined key the value falls back to"
              },
              "required": {
                "type": "boolean",
                "description": "an unset value is the operator's own to set"
              },
              "trusted": {
                "type": "boolean"
              }
            },
            "required": [
              "node",
              "module",
              "key",
              "source"
            ]
          },
          "description": "one resolved value"
        }
      ],
      "description": "the value each module on each node takes for each config key, built from the sources alone"
    },
    {
      "name": "kept",
      "template": "state",
      "key-forms": [
        {
          "key": "<owner>.<repository>.<number>.<node>.<module>.<key>",
          "value": {
            "type": "object",
            "description": "an approved held value, kept apart from the values mesh-config resolves, laid only over the composition of its own pull request at its head (ADR 0565 clause 5)",
            "properties": {
              "pull": {
                "type": "string",
                "description": "the pull request, owner/repository#number"
              },
              "head": {
                "type": "string",
                "description": "the head the declaration was read at"
              },
              "declaration": {
                "type": "string",
                "description": "the digest of what the declaration holds the value to; the value stays only while it is the same"
              },
              "node": {
                "type": "string"
              },
              "module": {
                "type": "string"
              },
              "key": {
                "type": "string",
                "description": "the config key"
              },
              "value": {
                "description": "the value held, as the operator approved it"
              },
              "by": {
                "type": "string"
              },
              "via": {
                "type": "string",
                "description": "where the value was proposed from"
              },
              "why": {
                "type": "string"
              },
              "approved": {
                "type": "string",
                "description": "who approved it, as the proposal kept it"
              },
              "proposal": {
                "type": "string",
                "description": "the proposal's id"
              },
              "at": {
                "type": "string",
                "format": "date-time",
                "description": "when it was kept"
              }
            },
            "required": [
              "pull",
              "head",
              "declaration",
              "node",
              "module",
              "key",
              "value"
            ]
          },
          "description": "one held value: the pull request (owner, repository and number, none holding a dot), the node, the module and the config key, which may hold dots"
        }
      ],
      "description": "the approved held values of open pull requests, read by the checker and the assigner's composition check"
    }
  ]
}