{
  "format": 1,
  "seat": "operator-channel",
  "scope": "mesh",
  "grain": "whole",
  "domain": "Operator and conversation",
  "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
  },
  "states": [
    {
      "name": "asks",
      "template": "state",
      "key-forms": [
        {
          "key": "<asker>.<id>",
          "value": {
            "type": "object",
            "description": "one ask the router holds and how it stands, as the router's tool states it",
            "properties": {
              "key": {
                "type": "string",
                "description": "<asker>.<id>"
              },
              "asker": {
                "type": "string",
                "description": "its asker"
              },
              "headline": {
                "type": "string",
                "description": "its headline"
              },
              "state": {
                "type": "string",
                "description": "how it stands: open, chosen, expired, cancelled, replaced or refused"
              },
              "opened": {
                "type": "string",
                "description": "when it was opened, RFC 3339"
              },
              "expires": {
                "type": "string",
                "description": "when it ends unanswered, RFC 3339"
              },
              "offered_on": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "the channels it was offered on"
              },
              "asker_told": {
                "type": "boolean",
                "description": "its asker has been told how it ended"
              },
              "answer": {
                "type": "string",
                "description": "how it ended, in words"
              }
            },
            "required": [
              "key",
              "asker",
              "headline",
              "state",
              "opened",
              "expires"
            ]
          },
          "description": "one ask the router holds and how it stands"
        }
      ],
      "description": "the asks a module raised and the router holds, one key per asker and ask"
    }
  ],
  "holder-events": [
    {
      "name": "refused",
      "subject": "mesh.mod.<holder>.event.refused"
    },
    {
      "name": "offered",
      "subject": "mesh.stream.<holder>.event.offered",
      "family": "router.asks",
      "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.stream.<holder>.event.closed",
      "family": "router.asks",
      "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"
      ]
    },
    "Button": {
      "type": "object",
      "description": "one answer a channel offers: its label and the router's one-time ticket for it",
      "properties": {
        "label": {
          "type": "string",
          "description": "the button's label"
        },
        "ticket": {
          "type": "string",
          "description": "the router's one-time ticket for it"
        }
      },
      "required": [
        "label",
        "ticket"
      ]
    },
    "Message": {
      "type": "object",
      "description": "the work a channel takes on the bench channel: shown with buttons (show), shown again in place (edit) or said (send); the words are the router's, shown as given",
      "properties": {
        "handle": {
          "type": "string",
          "description": "the router's name for it, the same across a show and its edits"
        },
        "title": {
          "type": "string",
          "description": "its title"
        },
        "body": {
          "type": "string",
          "description": "its body"
        },
        "buttons": {
          "type": "array",
          "items": {
            "$ref": "#/defs/Button"
          },
          "description": "the answers it offers (none for a send)"
        },
        "note": {
          "type": "string",
          "description": "its secondary words after the body and the buttons: who asked and when, what each answer does, when it expires, the ask's details"
        },
        "urgent": {
          "type": "boolean",
          "description": "urgent"
        },
        "silent": {
          "type": "boolean",
          "description": "shown without notifying"
        },
        "reply": {
          "type": "string",
          "description": "the choice or link request this answers, by its id: the channel shows it where that was made"
        },
        "to": {
          "type": "string",
          "description": "the account linked as the operator on this kind, where the channel sends what is not a reply; empty when none is linked"
        },
        "secret": {
          "type": "boolean",
          "description": "the words carry something shown once (a link's code): the channel keeps no copy"
        }
      },
      "required": [
        "handle",
        "title",
        "body"
      ]
    },
    "Sender": {
      "type": "object",
      "description": "who a channel's service says sent something; the router alone judges whether that is the operator",
      "properties": {
        "identity": {
          "type": "string",
          "description": "the account"
        },
        "display": {
          "type": "string",
          "description": "the name it shows"
        },
        "authenticated": {
          "type": "boolean",
          "description": "whether the service authenticated it"
        }
      },
      "required": [
        "identity",
        "authenticated"
      ]
    },
    "Choice": {
      "type": "object",
      "description": "a button chosen on a channel, said on the bench intake as the event `choice`",
      "properties": {
        "id": {
          "type": "string",
          "description": "the channel's own for this arrival, unique, so the router acts on it once"
        },
        "ticket": {
          "type": "string",
          "description": "the ticket of the button"
        },
        "handle": {
          "type": "string",
          "description": "the message's handle"
        },
        "sender": {
          "$ref": "#/defs/Sender"
        },
        "at": {
          "type": "string",
          "description": "when, RFC 3339",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "ticket",
        "sender",
        "at"
      ]
    },
    "LinkAsked": {
      "type": "object",
      "description": "somebody on a channel asking to be linked as the operator, said on the bench intake as the event `link`",
      "properties": {
        "id": {
          "type": "string",
          "description": "the channel's own for this arrival"
        },
        "sender": {
          "$ref": "#/defs/Sender"
        },
        "at": {
          "type": "string",
          "description": "when, RFC 3339",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "sender",
        "at"
      ]
    },
    "Failed": {
      "type": "object",
      "description": "a message a channel could not deliver, said on the bench intake as the event `failed`",
      "properties": {
        "handle": {
          "type": "string",
          "description": "the message's handle"
        },
        "why": {
          "type": "string",
          "description": "why"
        },
        "permanent": {
          "type": "boolean",
          "description": "trying again cannot help"
        },
        "at": {
          "type": "string",
          "description": "when, RFC 3339",
          "format": "date-time"
        }
      },
      "required": [
        "handle",
        "why",
        "at"
      ]
    },
    "Standing": {
      "type": "object",
      "description": "what a channel says of itself at least every five minutes and whenever it changes, on the bench intake as the event `standing`",
      "properties": {
        "ready": {
          "type": "boolean",
          "description": "it can send now"
        },
        "why": {
          "type": "string",
          "description": "why not"
        },
        "edits-silently": {
          "type": "boolean",
          "description": "its edits notify nobody"
        },
        "at": {
          "type": "string",
          "description": "when, RFC 3339",
          "format": "date-time"
        }
      },
      "required": [
        "ready",
        "at"
      ]
    },
    "Code": {
      "type": "object",
      "description": "a code a person typed on a channel, asked as the proof `code` on the bench intake by request and reply: never in an event, never kept",
      "properties": {
        "sender": {
          "$ref": "#/defs/Sender"
        },
        "code": {
          "type": "string",
          "description": "the code"
        },
        "purpose": {
          "type": "string",
          "description": "what it is for"
        }
      },
      "required": [
        "sender",
        "code",
        "purpose"
      ]
    },
    "ProofAnswer": {
      "type": "object",
      "description": "the router's answer to a proof",
      "properties": {
        "accepted": {
          "type": "boolean",
          "description": "whether it was taken"
        },
        "words": {
          "type": "string",
          "description": "words to say to the person"
        }
      },
      "required": [
        "accepted",
        "words"
      ]
    }
  }
}