{
  "format": 1,
  "seat": "operator-channel",
  "scope": "mesh",
  "grain": "whole",
  "decision": "novox/hq ADR 0259",
  "holder-declares": true,
  "description": "Asking a person and answering on a channel (ADR 0259): held by the router, the messenger module, whose manifest declares the seat; written from that seat entry (design 26).",
  "verbs": [
    {
      "name": "open",
      "description": "What is open now: every message the operator was sent about something still wrong, urgent first, oldest first.",
      "input": {
        "type": "object",
        "properties": {},
        "description": "no arguments"
      },
      "answer": {
        "type": "object",
        "description": "the open messages"
      }
    },
    {
      "name": "history",
      "description": "What was said to the operator lately, newest first, the refusals, and what waits to be sent on each channel.",
      "input": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "description": "at most this many of each (default 50)"
          }
        }
      },
      "answer": {
        "type": "object",
        "description": "the sends, refusals and what waits"
      }
    },
    {
      "name": "notify",
      "description": "Tell the operator something, as a module that uses the seat: a key, urgent or warning, one line, and what it is about; clear says it is over.",
      "input": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "the message's key"
          },
          "severity": {
            "type": "string",
            "enum": [
              "urgent",
              "warning"
            ]
          },
          "summary": {
            "type": "string",
            "description": "one line"
          },
          "subject": {
            "type": "string",
            "description": "what it is about"
          },
          "headline": {
            "type": "string",
            "description": "plain words"
          },
          "explanation": {
            "type": "string",
            "description": "one or two plain sentences"
          },
          "resolved": {
            "type": "string",
            "description": "the line said when it is over"
          },
          "clear": {
            "type": "boolean",
            "description": "it is over"
          }
        }
      },
      "answer": {
        "type": "object",
        "description": "what was sent"
      }
    },
    {
      "name": "tell",
      "description": "Tell the operator a plain notice that needs no answer and opens no condition (ADR 0380).",
      "input": {
        "type": "object",
        "properties": {
          "headline": {
            "type": "string",
            "description": "plain words"
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "one or two plain lines"
          },
          "subject": {
            "type": "string",
            "description": "what it is about"
          }
        }
      },
      "answer": {
        "type": "object",
        "description": "what was sent"
      }
    },
    {
      "name": "asks",
      "description": "The asks the router holds: open first, then the last month's, each with how it ended.",
      "input": {
        "type": "object",
        "properties": {},
        "description": "no arguments"
      },
      "answer": {
        "type": "object",
        "description": "the asks"
      }
    }
  ],
  "accepts": [
    {
      "name": "ask",
      "by-caller": true,
      "body": {
        "$ref": "#/defs/Ask"
      }
    },
    {
      "name": "cancel",
      "by-caller": true,
      "body": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "the ask's id"
          }
        },
        "required": [
          "id"
        ]
      }
    },
    {
      "name": "condition",
      "by-caller": true,
      "body": {
        "$ref": "#/defs/Condition"
      }
    }
  ],
  "events": [
    {
      "name": "decided",
      "by-caller": true,
      "body": {
        "$ref": "#/defs/Warrant"
      }
    }
  ],
  "family": {
    "name": "operator-channel.decided",
    "max-age-days": 7
  },
  "records": [
    {
      "name": "asks",
      "key": "<asker>.<id>",
      "value": {
        "type": "object",
        "description": "one ask the router holds and how it stands"
      }
    }
  ],
  "holder-events": [
    {
      "name": "refused",
      "subject": "mesh.mod.<holder>.event.refused"
    },
    {
      "name": "offered",
      "subject": "mesh.mod.<holder>.event.offered",
      "family": "the router's restricted stream (design 55 § 11)",
      "body": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "the ask's id"
          },
          "asker": {
            "type": "string",
            "description": "its asker"
          },
          "headline": {
            "type": "string",
            "description": "its headline"
          },
          "channels": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "the channels it was offered on"
          }
        },
        "required": [
          "id",
          "asker"
        ]
      }
    },
    {
      "name": "closed",
      "subject": "mesh.mod.<holder>.event.closed",
      "family": "the router's restricted stream (design 55 § 11)",
      "body": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "the ask's id"
          },
          "asker": {
            "type": "string",
            "description": "its asker"
          },
          "how": {
            "type": "string",
            "enum": [
              "answered",
              "expired",
              "cancelled",
              "replaced",
              "unlinked"
            ]
          }
        },
        "required": [
          "id",
          "asker",
          "how"
        ]
      }
    }
  ],
  "defs": {
    "Ask": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "the asker's own id"
        },
        "headline": {
          "type": "string",
          "description": "a few plain words"
        },
        "explanation": {
          "type": "string",
          "description": "what happened and what it means"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/defs/Option"
          },
          "description": "the answers it offers"
        },
        "who": {
          "type": "string",
          "description": "who may answer: operator"
        },
        "expires": {
          "type": "string",
          "description": "when it ends unanswered, RFC 3339"
        },
        "on-expiry": {
          "type": "string",
          "description": "what the asker then does"
        },
        "about": {
          "type": "string",
          "description": "what it is about: a newer ask about it replaces the older"
        },
        "urgent": {
          "type": "boolean",
          "description": "urgent"
        },
        "whole": {
          "type": "string",
          "description": "the explanation with its values whole"
        },
        "details": {
          "type": "string",
          "description": "its secondary words"
        },
        "whole-details": {
          "type": "string",
          "description": "the details whole"
        }
      },
      "required": [
        "id",
        "headline",
        "explanation",
        "options",
        "who",
        "expires",
        "on-expiry"
      ]
    },
    "Option": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "the option's id"
        },
        "label": {
          "type": "string",
          "description": "the button's label"
        },
        "does": {
          "type": "string",
          "description": "what it does, in plain words"
        },
        "level": {
          "type": "string",
          "description": "the proof its answer needs"
        },
        "binds": {
          "type": "string",
          "description": "the digest of exactly what the asker performs when it is chosen"
        }
      },
      "required": [
        "id",
        "label",
        "does",
        "level"
      ]
    },
    "Warrant": {
      "type": "object",
      "properties": {
        "ask": {
          "type": "string",
          "description": "the ask"
        },
        "asker": {
          "type": "string",
          "description": "its asker"
        },
        "about": {
          "type": "string",
          "description": "what it was about"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "chosen",
            "expired",
            "cancelled",
            "replaced",
            "refused"
          ]
        },
        "option": {
          "type": "string",
          "description": "the option chosen"
        },
        "label": {
          "type": "string",
          "description": "its label"
        },
        "level": {
          "type": "string",
          "description": "its level"
        },
        "by": {
          "$ref": "#/defs/Person"
        },
        "channel": {
          "type": "string",
          "description": "the module it came through"
        },
        "proofs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "the proofs present"
        },
        "at": {
          "type": "string",
          "description": "when, RFC 3339"
        },
        "ask-digest": {
          "type": "string",
          "description": "the digest of the ask as the router took it"
        },
        "words": {
          "type": "string",
          "description": "why it ended without a choice, or what refused it"
        }
      },
      "required": [
        "ask",
        "asker",
        "outcome",
        "at"
      ]
    },
    "Person": {
      "type": "object",
      "properties": {
        "who": {
          "type": "string",
          "description": "the role"
        },
        "kind": {
          "type": "string",
          "description": "the channel kind"
        },
        "identity": {
          "type": "string",
          "description": "the account"
        },
        "display": {
          "type": "string",
          "description": "the name shown"
        },
        "verified": {
          "type": "string",
          "description": "how the router knew"
        }
      },
      "required": [
        "who",
        "kind",
        "identity",
        "verified"
      ]
    },
    "Condition": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the form's version, 1"
        },
        "key": {
          "type": "string",
          "description": "the condition's key"
        },
        "severity": {
          "type": "string",
          "description": "urgent or warning"
        },
        "subject": {
          "type": "object",
          "properties": {
            "scope": {
              "type": "string",
              "description": "scope"
            },
            "id": {
              "type": "string",
              "description": "id"
            },
            "machine": {
              "type": "string",
              "description": "machine"
            }
          },
          "required": [
            "scope",
            "id"
          ]
        },
        "state": {
          "type": "string",
          "description": "raised or cleared"
        },
        "summary": {
          "type": "string",
          "description": "one line"
        },
        "headline": {
          "type": "string",
          "description": "plain words"
        },
        "needs": {
          "type": "string",
          "description": "what it needs"
        },
        "explanation": {
          "type": "string",
          "description": "plain words"
        },
        "resolved": {
          "type": "string",
          "description": "the line said when it is over"
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "description": "label"
              },
              "verb": {
                "type": "string",
                "description": "verb"
              },
              "machine": {
                "type": "string",
                "description": "machine"
              },
              "arguments": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "level": {
                "type": "string",
                "description": "level"
              }
            },
            "required": [
              "label",
              "verb"
            ]
          },
          "description": "the answers it offers"
        }
      },
      "required": [
        "v",
        "key",
        "subject",
        "state"
      ]
    }
  }
}