{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/finding-explainability/v2.json",
  "title": "Finding Explainability Predicate Schema",
  "description": "Schema for finding-explainability/v2 predicate type - vulnerability finding with assumptions, falsifiability criteria, and evidence-based confidence",
  "type": "object",
  "required": [
    "findingId",
    "vulnerabilityId",
    "packageName",
    "packageVersion",
    "generatedAt",
    "engineVersion"
  ],
  "properties": {
    "findingId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9-]+$",
      "description": "Unique identifier for this finding"
    },
    "vulnerabilityId": {
      "type": "string",
      "pattern": "^(CVE-[0-9]{4}-[0-9]+|GHSA-.+|OSV-.+|[A-Z]+-[0-9]+)$",
      "description": "The vulnerability ID (CVE, GHSA, OSV, etc.)"
    },
    "packageName": {
      "type": "string",
      "minLength": 1,
      "description": "Name of the affected package"
    },
    "packageVersion": {
      "type": "string",
      "minLength": 1,
      "description": "Version of the affected package"
    },
    "severity": {
      "type": "string",
      "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"],
      "description": "Severity level of the vulnerability"
    },
    "fixedVersion": {
      "type": ["string", "null"],
      "description": "Version that fixes the vulnerability, if known"
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when this report was generated"
    },
    "engineVersion": {
      "type": "string",
      "description": "Version of the explainability engine"
    },
    "explanation": {
      "type": "string",
      "description": "Human-readable explanation of the finding"
    },
    "detailedNarrative": {
      "type": "string",
      "description": "Detailed narrative for auditor review"
    },
    "assumptions": {
      "$ref": "#/$defs/AssumptionSet"
    },
    "falsifiability": {
      "$ref": "#/$defs/FalsifiabilityCriteria"
    },
    "confidenceScore": {
      "$ref": "#/$defs/EvidenceDensityScore"
    },
    "recommendedActions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RecommendedAction"
      },
      "description": "List of recommended remediation actions"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "AssumptionSet": {
      "type": "object",
      "description": "Collection of assumptions made during analysis",
      "required": ["id", "createdAt", "assumptions"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this assumption set"
        },
        "contextId": {
          "type": ["string", "null"],
          "description": "ID of the finding this assumption set belongs to"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "When this assumption set was created"
        },
        "assumptions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Assumption"
          },
          "description": "List of assumptions"
        }
      },
      "additionalProperties": false
    },
    "Assumption": {
      "type": "object",
      "description": "A single assumption made during vulnerability analysis",
      "required": ["category", "key", "assumedValue", "source", "confidence"],
      "properties": {
        "category": {
          "type": "string",
          "enum": [
            "CompilerFlag",
            "RuntimeConfig",
            "FeatureGate",
            "LoaderBehavior",
            "NetworkExposure",
            "ProcessPrivilege",
            "MemoryProtection",
            "SyscallAvailability"
          ],
          "description": "Category of the assumption"
        },
        "key": {
          "type": "string",
          "description": "Identifier for what is being assumed (e.g., flag name, config key)"
        },
        "assumedValue": {
          "type": "string",
          "description": "The value being assumed"
        },
        "observedValue": {
          "type": ["string", "null"],
          "description": "The actually observed value, if verified"
        },
        "source": {
          "type": "string",
          "enum": ["Default", "StaticAnalysis", "RuntimeObservation", "UserProvided", "Inferred"],
          "description": "How this assumption was derived"
        },
        "confidence": {
          "type": "string",
          "enum": ["Low", "Medium", "High", "Verified"],
          "description": "Confidence level in this assumption"
        }
      },
      "additionalProperties": false
    },
    "FalsifiabilityCriteria": {
      "type": "object",
      "description": "Criteria that would disprove or falsify the finding",
      "required": ["id", "findingId", "generatedAt", "criteria"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this falsifiability assessment"
        },
        "findingId": {
          "type": "string",
          "description": "ID of the finding being assessed"
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When this assessment was generated"
        },
        "status": {
          "type": "string",
          "enum": ["Unknown", "Falsified", "NotFalsified", "PartiallyEvaluated"],
          "description": "Overall falsifiability status"
        },
        "summary": {
          "type": ["string", "null"],
          "description": "Human-readable summary of falsifiability assessment"
        },
        "criteria": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FalsificationCriterion"
          },
          "description": "Individual falsification criteria"
        }
      },
      "additionalProperties": false
    },
    "FalsificationCriterion": {
      "type": "object",
      "description": "A single criterion that could falsify the finding",
      "required": ["type", "description", "status"],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PackageNotPresent",
            "VersionMismatch",
            "CodeUnreachable",
            "FeatureDisabled",
            "MitigationPresent",
            "NoNetworkExposure",
            "InsufficientPrivileges",
            "PatchApplied",
            "ConfigurationPrevents",
            "RuntimePrevents"
          ],
          "description": "Type of falsification criterion"
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of what would falsify the finding"
        },
        "checkExpression": {
          "type": ["string", "null"],
          "description": "Machine-readable expression to check this criterion"
        },
        "evidence": {
          "type": ["string", "null"],
          "description": "Evidence supporting the criterion status"
        },
        "status": {
          "type": "string",
          "enum": ["Pending", "Satisfied", "NotSatisfied", "Inconclusive"],
          "description": "Status of this criterion evaluation"
        }
      },
      "additionalProperties": false
    },
    "EvidenceDensityScore": {
      "type": "object",
      "description": "Confidence score based on evidence density",
      "required": ["score", "level"],
      "properties": {
        "score": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Numeric confidence score (0.0 to 1.0)"
        },
        "level": {
          "type": "string",
          "enum": ["Low", "Medium", "High", "Verified"],
          "description": "Confidence level tier"
        },
        "factorBreakdown": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0
          },
          "description": "Breakdown of contributing factors and their scores"
        },
        "explanation": {
          "type": "string",
          "description": "Human-readable explanation of the confidence assessment"
        },
        "improvementRecommendations": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Recommendations for improving confidence"
        }
      },
      "additionalProperties": false
    },
    "RecommendedAction": {
      "type": "object",
      "description": "A recommended remediation action",
      "required": ["priority", "action", "rationale", "effort"],
      "properties": {
        "priority": {
          "type": "integer",
          "minimum": 1,
          "description": "Priority order (1 = highest)"
        },
        "action": {
          "type": "string",
          "description": "Description of the recommended action"
        },
        "rationale": {
          "type": "string",
          "description": "Why this action is recommended"
        },
        "effort": {
          "type": "string",
          "enum": ["Low", "Medium", "High"],
          "description": "Estimated effort level"
        }
      },
      "additionalProperties": false
    }
  }
}