{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://stellaops.io/schemas/reachability/ground-truth.schema.json",
  "title": "Reachability Ground Truth",
  "description": "Ground truth annotations for reachability test samples",
  "type": "object",
  "required": ["schema", "sampleId", "generatedAt", "generator", "targets", "entryPoints"],
  "properties": {
    "schema": {
      "type": "string",
      "const": "ground-truth-v1"
    },
    "sampleId": {
      "type": "string",
      "pattern": "^sample:[a-z]+:[a-z0-9-]+:[0-9]+$"
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "generator": {
      "type": "object",
      "required": ["name", "version"],
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "annotator": {
          "type": "string"
        }
      }
    },
    "targets": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/target"
      }
    },
    "entryPoints": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/entryPoint"
      }
    },
    "expectedUncertainty": {
      "$ref": "#/definitions/uncertainty"
    },
    "expectedGateDecisions": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/gateDecision"
      }
    }
  },
  "definitions": {
    "target": {
      "type": "object",
      "required": ["symbolId", "expected", "reasoning"],
      "properties": {
        "symbolId": {
          "type": "string",
          "pattern": "^sym:[a-z]+:.+"
        },
        "display": {
          "type": "string"
        },
        "purl": {
          "type": "string"
        },
        "expected": {
          "type": "object",
          "required": ["latticeState", "bucket", "reachable", "confidence"],
          "properties": {
            "latticeState": {
              "type": "string",
              "enum": ["U", "SR", "SU", "RO", "RU", "CR", "CU", "X"]
            },
            "bucket": {
              "type": "string",
              "enum": ["unknown", "direct", "runtime", "unreachable", "entrypoint"]
            },
            "reachable": {
              "type": "boolean"
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "pathLength": {
              "type": ["integer", "null"],
              "minimum": 0
            },
            "path": {
              "type": ["array", "null"],
              "items": {
                "type": "string"
              }
            }
          }
        },
        "reasoning": {
          "type": "string"
        }
      }
    },
    "entryPoint": {
      "type": "object",
      "required": ["symbolId", "phase", "source"],
      "properties": {
        "symbolId": {
          "type": "string"
        },
        "display": {
          "type": "string"
        },
        "phase": {
          "type": "string",
          "enum": ["load", "init", "runtime", "main", "fini"]
        },
        "source": {
          "type": "string"
        }
      }
    },
    "uncertainty": {
      "type": "object",
      "required": ["aggregateTier"],
      "properties": {
        "states": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["code", "entropy"],
            "properties": {
              "code": {
                "type": "string",
                "enum": ["U1", "U2", "U3", "U4"]
              },
              "entropy": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            }
          }
        },
        "aggregateTier": {
          "type": "string",
          "enum": ["T1", "T2", "T3", "T4"]
        },
        "riskScore": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "gateDecision": {
      "type": "object",
      "required": ["vulnId", "targetSymbol", "requestedStatus", "expectedDecision"],
      "properties": {
        "vulnId": {
          "type": "string"
        },
        "targetSymbol": {
          "type": "string"
        },
        "requestedStatus": {
          "type": "string",
          "enum": ["affected", "not_affected", "under_investigation", "fixed"]
        },
        "expectedDecision": {
          "type": "string",
          "enum": ["allow", "block", "warn"]
        },
        "expectedBlockedBy": {
          "type": "string"
        },
        "expectedReason": {
          "type": "string"
        }
      }
    }
  }
}