{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/policy-pack-v2.schema.json",
  "title": "Stella Ops PolicyPack v2",
  "description": "Canonical policy pack format supporting bidirectional JSON/Rego interop with structured remediation hints.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": {
      "type": "string",
      "const": "policy.stellaops.io/v2",
      "description": "Schema version identifier."
    },
    "kind": {
      "type": "string",
      "enum": ["PolicyPack", "PolicyOverride"],
      "description": "Document kind."
    },
    "metadata": { "$ref": "#/$defs/PolicyPackMetadata" },
    "spec": { "$ref": "#/$defs/PolicyPackSpec" }
  },
  "additionalProperties": false,
  "$defs": {
    "PolicyPackMetadata": {
      "type": "object",
      "required": ["name", "version"],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,62}$",
          "description": "Unique name (DNS-label format)."
        },
        "version": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+",
          "description": "Semantic version."
        },
        "description": {
          "type": "string",
          "maxLength": 500,
          "description": "Human-readable description."
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "SHA-256 digest of canonical content."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Creation timestamp (ISO 8601 UTC)."
        },
        "exportedFrom": { "$ref": "#/$defs/PolicyExportProvenance" },
        "parent": {
          "type": "string",
          "description": "Parent policy pack name (for PolicyOverride)."
        },
        "environment": {
          "type": "string",
          "description": "Target environment (for PolicyOverride)."
        }
      },
      "additionalProperties": false
    },
    "PolicyExportProvenance": {
      "type": "object",
      "required": ["engine", "engineVersion"],
      "properties": {
        "engine": {
          "type": "string",
          "description": "Exporting engine name."
        },
        "engineVersion": {
          "type": "string",
          "description": "Engine version."
        },
        "exportedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Export timestamp."
        }
      },
      "additionalProperties": false
    },
    "PolicyPackSpec": {
      "type": "object",
      "required": ["settings"],
      "properties": {
        "settings": { "$ref": "#/$defs/PolicyPackSettings" },
        "gates": {
          "type": "array",
          "items": { "$ref": "#/$defs/PolicyGateDefinition" },
          "description": "Gate definitions with typed configurations."
        },
        "rules": {
          "type": "array",
          "items": { "$ref": "#/$defs/PolicyRuleDefinition" },
          "description": "Rule definitions with match conditions."
        }
      },
      "additionalProperties": false
    },
    "PolicyPackSettings": {
      "type": "object",
      "required": ["defaultAction"],
      "properties": {
        "defaultAction": {
          "type": "string",
          "enum": ["allow", "warn", "block"],
          "description": "Default action when no rule matches."
        },
        "unknownsThreshold": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "default": 0.6,
          "description": "Threshold for unknowns budget."
        },
        "stopOnFirstFailure": {
          "type": "boolean",
          "default": true,
          "description": "Stop evaluation on first failure."
        },
        "deterministicMode": {
          "type": "boolean",
          "default": true,
          "description": "Enforce deterministic evaluation."
        }
      },
      "additionalProperties": false
    },
    "PolicyGateDefinition": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,62}$",
          "description": "Unique gate identifier."
        },
        "type": {
          "type": "string",
          "description": "Gate type (C# gate class name)."
        },
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Whether this gate is active."
        },
        "config": {
          "type": "object",
          "description": "Gate-specific configuration.",
          "additionalProperties": true
        },
        "environments": {
          "type": "object",
          "description": "Per-environment config overrides.",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "remediation": { "$ref": "#/$defs/RemediationHint" }
      },
      "additionalProperties": false
    },
    "PolicyRuleDefinition": {
      "type": "object",
      "required": ["name", "action"],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,62}$",
          "description": "Unique rule name."
        },
        "action": {
          "type": "string",
          "enum": ["allow", "warn", "block"],
          "description": "Action when matched."
        },
        "priority": {
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "description": "Evaluation priority (lower = first)."
        },
        "match": {
          "type": "object",
          "description": "Match conditions (dot-notation keys, typed values).",
          "additionalProperties": true
        },
        "remediation": { "$ref": "#/$defs/RemediationHint" }
      },
      "additionalProperties": false
    },
    "RemediationHint": {
      "type": "object",
      "required": ["code", "title", "severity"],
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^[A-Z][A-Z0-9_]{1,30}$",
          "description": "Machine-readable remediation code."
        },
        "title": {
          "type": "string",
          "maxLength": 200,
          "description": "Human-readable title."
        },
        "description": {
          "type": "string",
          "maxLength": 1000,
          "description": "Detailed explanation."
        },
        "actions": {
          "type": "array",
          "items": { "$ref": "#/$defs/RemediationAction" },
          "description": "Ordered remediation actions."
        },
        "references": {
          "type": "array",
          "items": { "$ref": "#/$defs/RemediationReference" },
          "description": "External references."
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"],
          "description": "Issue severity."
        }
      },
      "additionalProperties": false
    },
    "RemediationAction": {
      "type": "object",
      "required": ["type", "description"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["upgrade", "patch", "vex", "sign", "anchor", "generate", "override", "investigate", "mitigate"],
          "description": "Action type."
        },
        "description": {
          "type": "string",
          "maxLength": 500,
          "description": "What this action does."
        },
        "command": {
          "type": "string",
          "maxLength": 500,
          "description": "CLI command template with {placeholders}."
        }
      },
      "additionalProperties": false
    },
    "RemediationReference": {
      "type": "object",
      "required": ["title", "url"],
      "properties": {
        "title": {
          "type": "string",
          "maxLength": 200,
          "description": "Display title."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Reference URL."
        }
      },
      "additionalProperties": false
    }
  }
}