{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.orbytlabs.ai/specs/command-record-v1/schema.json",
  "title": "Orbyt Command Record v1",
  "version": 1,
  "license": "MIT",
  "$comment": "Generated by scripts/specs/command-record-v1.mjs from command-record.mjs. Apply the semantic rules below after schema validation. Record validation does not establish an external effect.",
  "x-semantic-rules": [
    "requested_at, expires_at and transitions[].at must be strings accepted by JavaScript Date.parse.",
    "expires_at must be later than requested_at.",
    "A committed transition must not be later than expires_at.",
    "For configure, payload.from and payload.to must differ under JavaScript strict equality."
  ],
  "type": "object",
  "properties": {
    "command_record_version": {
      "const": 1
    },
    "id": {
      "$ref": "#/$defs/commandId"
    },
    "kind": {
      "enum": [
        "pause",
        "resume",
        "cancel",
        "dispatch",
        "configure",
        "revert",
        "compensate"
      ]
    },
    "target": {
      "type": "object",
      "properties": {
        "scope": {
          "enum": [
            "global",
            "seat",
            "run",
            "workflow",
            "configuration",
            "audit"
          ]
        },
        "id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "scope"
      ],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "scope": {
                "const": "global"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "type": "null"
              }
            }
          },
          "else": {
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "\\S"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "scope": {
                "const": "audit"
              }
            }
          },
          "then": {
            "properties": {
              "id": {
                "not": {
                  "enum": [
                    "packages/collective/src/check-agent-confinement.mjs"
                  ]
                }
              }
            }
          }
        }
      ]
    },
    "payload": {
      "type": "object"
    },
    "expected_revision": {
      "$ref": "#/$defs/sha"
    },
    "reason": {
      "type": "string",
      "pattern": "\\S"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "\\S"
    },
    "requested_at": {
      "type": "string"
    },
    "expires_at": {
      "type": "string"
    },
    "executor": {
      "type": "object",
      "properties": {
        "app": {
          "const": "orbyt-collective-executor"
        },
        "acting_for": {
          "type": "string",
          "pattern": "\\S",
          "not": {
            "pattern": "@"
          }
        },
        "role": {
          "enum": [
            "owner",
            "admin",
            "operator"
          ]
        }
      },
      "required": [
        "app",
        "acting_for",
        "role"
      ],
      "additionalProperties": false
    },
    "state": {
      "enum": [
        "requested",
        "committed",
        "effective",
        "observed",
        "rejected",
        "expired",
        "superseded"
      ]
    },
    "transitions": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "state": {
            "enum": [
              "requested",
              "committed",
              "effective",
              "observed",
              "rejected",
              "expired",
              "superseded"
            ]
          },
          "at": {
            "type": "string"
          },
          "evidence": {
            "type": "string",
            "pattern": "^(sha|run|path|finding|http|read|operator):\\S"
          }
        },
        "required": [
          "state",
          "at",
          "evidence"
        ],
        "additionalProperties": false
      }
    },
    "cannot_undo": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "outcome": {
      "type": [
        "string",
        "null"
      ]
    },
    "observed_effect": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "command_record_version",
    "id",
    "kind",
    "target",
    "payload",
    "expected_revision",
    "reason",
    "idempotency_key",
    "requested_at",
    "expires_at",
    "executor",
    "state",
    "transitions",
    "cannot_undo",
    "outcome",
    "observed_effect"
  ],
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "kind": {
            "const": "pause"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "global",
                  "seat"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "a run already past recheck-halt for its final push",
              "an email already sent by the in-flight run"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "resume"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "global",
                  "seat"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "acknowledge_provenance": {
                "type": "boolean"
              }
            },
            "required": [],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "quota spent by runs that resume"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "cancel"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "run"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "run_id": {
                "$ref": "#/$defs/runId"
              }
            },
            "required": [
              "run_id"
            ],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "work the run committed before the cancel",
              "a cancelled conclusion is indistinguishable from a timeout kill without the step count"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "dispatch"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "workflow"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "workflow": {
                "$ref": "#/$defs/workflow"
              },
              "inputs": {
                "type": "object",
                "propertyNames": {
                  "not": {
                    "enum": [
                      "supervised",
                      "command_id"
                    ]
                  }
                },
                "additionalProperties": {
                  "type": [
                    "string",
                    "number",
                    "boolean",
                    "null"
                  ]
                }
              },
              "supervised": {
                "type": "boolean"
              }
            },
            "required": [
              "workflow"
            ],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "quota",
              "a landing",
              "an email, if the seat sends one"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "configure"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "seat",
                  "configuration",
                  "audit"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string",
                "pattern": "\\S"
              },
              "from": {
                "type": [
                  "string",
                  "number",
                  "boolean",
                  "null"
                ]
              },
              "to": {
                "type": [
                  "string",
                  "number",
                  "boolean",
                  "null"
                ]
              }
            },
            "required": [
              "path",
              "from",
              "to"
            ],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "runs already scheduled by GitHub on the old cron in the current hour"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "revert"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "global",
                  "seat",
                  "configuration"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "sha": {
                "$ref": "#/$defs/sha"
              }
            },
            "required": [
              "sha"
            ],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": [
              "an email",
              "spent quota",
              "an external side effect of the landed run"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "compensate"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "properties": {
              "scope": {
                "enum": [
                  "global",
                  "seat",
                  "run",
                  "workflow",
                  "configuration"
                ]
              }
            }
          },
          "payload": {
            "type": "object",
            "properties": {
              "action": {}
            },
            "required": [
              "action"
            ],
            "additionalProperties": false
          },
          "cannot_undo": {
            "const": []
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "observed",
              "rejected",
              "expired",
              "superseded"
            ]
          }
        }
      },
      "then": {
        "properties": {
          "outcome": {
            "type": "string"
          }
        }
      }
    }
  ],
  "oneOf": [
    {
      "properties": {
        "state": {
          "const": "requested"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 1,
              "maxItems": 1,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "committed"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 2,
              "maxItems": 2,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "effective"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 3,
              "maxItems": 3,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "effective"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "observed"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 4,
              "maxItems": 4,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "effective"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "observed"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "rejected"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 4,
              "maxItems": 4,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "effective"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "rejected"
                    }
                  }
                }
              ]
            },
            {
              "minItems": 3,
              "maxItems": 3,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "rejected"
                    }
                  }
                }
              ]
            },
            {
              "minItems": 2,
              "maxItems": 2,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "rejected"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "expired"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 2,
              "maxItems": 2,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "expired"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "properties": {
        "state": {
          "const": "superseded"
        },
        "transitions": {
          "anyOf": [
            {
              "minItems": 4,
              "maxItems": 4,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "effective"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "superseded"
                    }
                  }
                }
              ]
            },
            {
              "minItems": 3,
              "maxItems": 3,
              "prefixItems": [
                {
                  "properties": {
                    "state": {
                      "const": "requested"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "committed"
                    }
                  }
                },
                {
                  "properties": {
                    "state": {
                      "const": "superseded"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ],
  "$defs": {
    "commandId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^cmd_[0-9a-z]{9}[0-9a-f]{16}$"
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/commandId"
          }
        }
      ]
    },
    "sha": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{40}$"
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/sha"
          }
        }
      ]
    },
    "workflow": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]+\\.ya?ml$"
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/workflow"
          }
        }
      ]
    },
    "runId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d+$"
        },
        {
          "type": "integer",
          "minimum": 0,
          "exclusiveMaximum": 1e+21
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/runId"
          }
        }
      ]
    }
  }
}