{
  "openapi": "3.1.0",
  "info": {
    "title": "KillSwitch proposed control API",
    "version": "0.1.0",
    "description": "Engineering design draft. No running product API or production guarantees. Operator authentication, MFA assurance mapping, and actual policies require implementation review."
  },
  "servers": [
    {
      "url": "https://control.example.invalid",
      "description": "Non-operational example server; replace only after an authenticated sandbox exists."
    }
  ],
  "security": [
    {
      "OperatorToken": []
    }
  ],
  "paths": {
    "/v1/workloads": {
      "get": {
        "operationId": "listWorkloads",
        "summary": "List authorized workloads",
        "description": "Returns only workloads in the caller's policy scope. No cross-environment enumeration.",
        "x-required-action": "killswitch:Read",
        "x-implementation-status": "proposed",
        "responses": {
          "200": {
            "description": "Current authorized representation.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkloadPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 512
            },
            "description": "Opaque cursor bound to the authenticated scope."
          }
        ]
      }
    },
    "/v1/workloads/{workloadId}": {
      "parameters": [
        {
          "name": "workloadId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getWorkload",
        "summary": "Read current workload coverage",
        "description": "Coverage is an observation of the enrolled boundary, not a claim of permanent containment.",
        "x-required-action": "killswitch:Read",
        "x-implementation-status": "proposed",
        "responses": {
          "200": {
            "description": "Current authorized representation.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workload"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/workloads/{workloadId}/stop-requests": {
      "parameters": [
        {
          "name": "workloadId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "operationId": "requestStop",
        "summary": "Latch quarantine and accept a stop operation",
        "description": "Atomically persists quarantine, the stop operation, and its dispatch outbox. Does not assert stopped execution. A same-generation repeat resolves to the existing stop operation. GET the operation for its current assessment.",
        "x-required-action": "killswitch:Stop",
        "x-implementation-status": "proposed",
        "responses": {
          "202": {
            "description": "Accepted resource; acceptance is not execution or recovery completion.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Location": {
                "description": "Relative URL of the accepted resource.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/v1/operations/00000000-0000-4000-8000-000000000002"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopOperation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StopRequest"
              }
            }
          }
        }
      }
    },
    "/v1/operations/{operationId}": {
      "parameters": [
        {
          "name": "operationId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getStopOperation",
        "summary": "Read independently observed stop results",
        "description": "VERIFIED_STOPPED requires every required check key to be present once and PASSED with attributable fresh observations. Later contradictory evidence appends another verification attempt.",
        "x-required-action": "killswitch:Read",
        "x-implementation-status": "proposed",
        "responses": {
          "200": {
            "description": "Current authorized representation.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StopOperation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/workloads/{workloadId}/recovery-reviews": {
      "parameters": [
        {
          "name": "workloadId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "operationId": "requestRecoveryReview",
        "summary": "Request human review of a verified stop",
        "description": "Requires the current quarantined generation and its verified stop operation. Creates a review only; does not restart or restore access.",
        "x-required-action": "killswitch:RequestRecovery",
        "x-implementation-status": "proposed",
        "responses": {
          "202": {
            "description": "Accepted resource; acceptance is not execution or recovery completion.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Location": {
                "description": "Relative URL of the accepted resource.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/v1/recovery-reviews/00000000-0000-4000-8000-000000000003"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecoveryReview"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecoveryReviewRequest"
              }
            }
          }
        }
      }
    },
    "/v1/recovery-reviews/{reviewId}": {
      "parameters": [
        {
          "name": "reviewId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getRecoveryReview",
        "summary": "Read a generation-bound recovery review",
        "description": "Approval is not restoration. Only the trusted provisioner can consume the single-use permission for the specified next generation.",
        "x-required-action": "killswitch:Read",
        "x-implementation-status": "proposed",
        "responses": {
          "200": {
            "description": "Current authorized representation.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecoveryReview"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/recovery-reviews/{reviewId}/approvals": {
      "parameters": [
        {
          "name": "reviewId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "operationId": "approveRecoveryReview",
        "summary": "Record an authorized human recovery decision",
        "description": "Requires REQUESTED state, matching revision, current generation, fresh required verification, and configured human authentication assurance. Approval creates a short-lived single-use provisioning permission; it cannot clear the old generation's deny or latch.",
        "x-required-action": "killswitch:ApproveRecovery",
        "x-implementation-status": "proposed",
        "responses": {
          "202": {
            "description": "Accepted resource; acceptance is not execution or recovery completion.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Location": {
                "description": "Relative URL of the accepted resource.",
                "schema": {
                  "type": "string",
                  "format": "uri-reference",
                  "example": "/v1/recovery-reviews/00000000-0000-4000-8000-000000000003"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecoveryReview"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, identifier, or additional mutation field.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or unacceptable authentication.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient action permission or configured authentication assurance.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource absent or not visible in the authenticated scope.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale generation/revision, invalid review state, or conflicting idempotency-key reuse.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry only after the indicated interval.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Retry-After": {
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Acceptance or observation could not be established. Retry mutations with the same key and body.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecoveryApprovalRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OperatorToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Configured issuer/audience/signature/expiry validation plus action and authentication-assurance policy. A JWT alone is not proof of MFA."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Durable application idempotency key, scoped to environment/action/target. Reuse with a different semantic payload returns 409. Proposed retention: seven days."
      }
    },
    "schemas": {
      "Coverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "COMPLETE",
              "INCOMPLETE",
              "STALE"
            ]
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "boundary": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "status",
          "observedAt",
          "boundary"
        ]
      },
      "Workload": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "generation": {
            "type": "integer",
            "minimum": 1
          },
          "state": {
            "type": "string",
            "enum": [
              "ENROLLING",
              "ARMED",
              "QUARANTINED",
              "RECOVERING",
              "RETIRED"
            ]
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          },
          "registeredTaskCount": {
            "type": "integer",
            "minimum": 0
          },
          "stopOperationId": {
            "type": "string",
            "format": "uuid"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "generation",
          "state",
          "coverage",
          "registeredTaskCount",
          "updatedAt"
        ]
      },
      "WorkloadPage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workload"
            },
            "maxItems": 100
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          }
        },
        "required": [
          "items",
          "nextCursor"
        ]
      },
      "StopRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expectedGeneration": {
            "type": "integer",
            "minimum": 1
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500,
            "description": "A concise operational reason; do not include secrets or confidential prompt data."
          }
        },
        "required": [
          "expectedGeneration",
          "reason"
        ]
      },
      "Check": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "launch_fence",
              "launch_reservations",
              "runtime",
              "coverage",
              "gateway",
              "in_flight",
              "identity"
            ]
          },
          "required": {
            "type": "boolean",
            "const": true
          },
          "result": {
            "type": "string",
            "enum": [
              "PENDING",
              "PASSED",
              "FAILED",
              "UNKNOWN"
            ]
          },
          "observedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "summary": {
            "type": "string",
            "maxLength": 500
          },
          "evidenceRefs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 100
          }
        },
        "required": [
          "key",
          "required",
          "result",
          "observedAt",
          "summary",
          "evidenceRefs"
        ],
        "allOf": [
          {
            "if": {
              "properties": {
                "result": {
                  "const": "PASSED"
                }
              },
              "required": [
                "result"
              ]
            },
            "then": {
              "properties": {
                "observedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "evidenceRefs": {
                  "minItems": 1
                }
              }
            }
          }
        ]
      },
      "StopOperation": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workloadId": {
            "type": "string",
            "format": "uuid"
          },
          "generation": {
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "ACCEPTED",
              "ENFORCING",
              "VERIFYING",
              "VERIFIED_STOPPED",
              "PARTIAL",
              "FAILED",
              "UNKNOWN"
            ]
          },
          "quarantineLatched": {
            "type": "boolean",
            "const": true
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            },
            "minItems": 7,
            "maxItems": 7,
            "description": "Exactly one entry for each required check key. The service must enforce key uniqueness and verification invariants."
          },
          "verificationAttempt": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "workloadId",
          "generation",
          "status",
          "quarantineLatched",
          "checks",
          "verificationAttempt",
          "createdAt",
          "updatedAt"
        ]
      },
      "RecoveryReviewRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expectedGeneration": {
            "type": "integer",
            "minimum": 1
          },
          "stopOperationId": {
            "type": "string",
            "format": "uuid"
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500,
            "description": "A concise operational reason; do not include secrets or confidential prompt data."
          }
        },
        "required": [
          "expectedGeneration",
          "stopOperationId",
          "reason"
        ]
      },
      "RecoveryApprovalRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expectedRevision": {
            "type": "integer",
            "minimum": 1
          },
          "reason": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500,
            "description": "A concise operational reason; do not include secrets or confidential prompt data."
          }
        },
        "required": [
          "expectedRevision",
          "reason"
        ]
      },
      "RecoveryReview": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workloadId": {
            "type": "string",
            "format": "uuid"
          },
          "generation": {
            "type": "integer",
            "minimum": 1
          },
          "nextGeneration": {
            "type": "integer",
            "minimum": 1
          },
          "stopOperationId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "REQUESTED",
              "APPROVED",
              "REJECTED",
              "EXPIRED",
              "CONSUMED"
            ]
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "permitExpiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "workloadId",
          "generation",
          "nextGeneration",
          "stopOperationId",
          "status",
          "revision",
          "permitExpiresAt",
          "createdAt",
          "updatedAt"
        ],
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "APPROVED"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "permitExpiresAt": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "invalid_request",
              "unauthenticated",
              "forbidden",
              "not_found",
              "conflict",
              "rate_limited",
              "unavailable"
            ]
          },
          "message": {
            "type": "string",
            "maxLength": 500
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "code",
          "message",
          "requestId"
        ]
      }
    }
  }
}