{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/operation.schema.json",
  "title": "Gentle AI negotiated review operation result",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "contract",
    "operation",
    "result"
  ],
  "properties": {
    "schema": {
      "const": "gentle-ai.review-integration.operation/v1"
    },
    "contract": {
      "const": "gentle-ai.review-integration/v1"
    },
    "operation": {
      "enum": [
        "review.finalize",
        "review.validate",
        "review.bind_sdd",
        "review.retry_final_verification"
      ]
    },
    "result": {
      "oneOf": [
        {
          "$ref": "#/$defs/finalize"
        },
        {
          "$ref": "#/$defs/validate"
        },
        {
          "$ref": "#/$defs/bind_sdd"
        },
        {
          "$ref": "#/$defs/retry_final_verification"
        }
      ]
    }
  },
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^sha256:[0-9a-f]{64}$"
    },
    "finalize": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "operation",
        "lineage_id",
        "state",
        "action",
        "store_revision"
      ],
      "properties": {
        "operation": {
          "const": "review/finalize"
        },
        "lineage_id": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "minLength": 1
        },
        "action": {
          "type": "string",
          "minLength": 1
        },
        "store_revision": {
          "$ref": "#/$defs/sha256"
        },
        "eligibility": {
          "$ref": "status.schema.json#/$defs/action_eligibility"
        },
        "next_transition": {
          "$ref": "status.schema.json#/$defs/next_transition"
        },
        "validation_request": {
          "$ref": "targeted-validation-request.schema.json"
        },
        "escalation": {
          "$comment": "Present only when the authority is escalated. Carries the accounting sentence with spent, remaining and total correction lines, so a caller learns the numbers without a second call.",
          "type": "string",
          "minLength": 1
        },
        "advisory_findings": {
          "$ref": "#/$defs/advisory_findings"
        }
      },
      "allOf": [
        {
          "if": {
            "required": [
              "validation_request"
            ]
          },
          "then": {
            "properties": {
              "state": {
                "const": "correction_required"
              }
            }
          }
        },
        {
          "if": {
            "required": [
              "advisory_findings"
            ]
          },
          "then": {
            "properties": {
              "state": {
                "const": "approved"
              }
            }
          }
        }
      ]
    },
    "advisory_findings": {
      "$comment": "Additive and optional. Present only on an approved lineage that froze at least one non-blocking finding, it names the disposition that lineage's routing already decided (outcome plus absence from the correction ledger) instead of leaving a consumer to infer it from a bare severity string. It changes nothing about which findings block: a corrected blocker is excluded rather than relabelled, and the statement says the approval stands and that no correction transition is offered.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "statement",
        "findings"
      ],
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 1
        },
        "findings": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "severity",
              "disposition"
            ],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "lens": {
                "type": "string",
                "minLength": 1
              },
              "location": {
                "type": "string",
                "minLength": 1
              },
              "severity": {
                "type": "string",
                "enum": [
                  "BLOCKER",
                  "CRITICAL",
                  "WARNING",
                  "SUGGESTION"
                ]
              },
              "disposition": {
                "$comment": "informational: a non-severe finding that never entered classification and requires no action. follow_up: a severe finding proved to originate outside the frozen candidate, recorded for separate later work. refuted: a severe inferential finding the refuter knocked down.",
                "enum": [
                  "informational",
                  "follow_up",
                  "refuted"
                ]
              }
            }
          }
        }
      }
    },
    "validate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "result",
        "allowed",
        "action",
        "reason",
        "context"
      ],
      "properties": {
        "schema": {
          "const": "gentle-ai.review-gate-result/v1"
        },
        "result": {
          "enum": [
            "allow",
            "scope-changed",
            "invalidated",
            "escalated"
          ]
        },
        "allowed": {
          "type": "boolean"
        },
        "action": {
          "type": "string",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "minLength": 1
        },
        "context": {
          "type": "object"
        },
        "delivery": {
          "const": "disabled/unmanaged"
        }
      }
    },
    "bind_sdd": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "revision",
        "change",
        "lineage",
        "authority_revision",
        "receipt_hash",
        "gate_context"
      ],
      "properties": {
        "schema": {
          "const": "gentle-ai.sdd-review-binding/v1"
        },
        "revision": {
          "$ref": "#/$defs/sha256"
        },
        "change": {
          "type": "string",
          "minLength": 1
        },
        "lineage": {
          "type": "string",
          "minLength": 1
        },
        "authority_revision": {
          "$ref": "#/$defs/sha256"
        },
        "receipt_hash": {
          "$ref": "#/$defs/sha256"
        },
        "gate_context": {
          "type": "object"
        }
      }
    },
    "retry_final_verification": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "operation",
        "predecessor_lineage_id",
        "predecessor_revision",
        "lineage_id",
        "state",
        "store_revision",
        "target_identity",
        "incident_digest",
        "recovery_disposition"
      ],
      "properties": {
        "operation": {
          "const": "review.retry_final_verification"
        },
        "predecessor_lineage_id": {
          "type": "string",
          "maxLength": 128,
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "predecessor_revision": {
          "$ref": "#/$defs/sha256"
        },
        "lineage_id": {
          "type": "string",
          "maxLength": 128,
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "state": {
          "const": "validating"
        },
        "store_revision": {
          "$ref": "#/$defs/sha256"
        },
        "target_identity": {
          "$ref": "#/$defs/sha256"
        },
        "incident_digest": {
          "$ref": "#/$defs/sha256"
        },
        "recovery_disposition": {
          "const": "final_verification_retry"
        }
      }
    }
  }
}
