{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://vclaw.dev/schemas/video/artifacts/keyframe-qc.schema.json",
  "title": "KeyframeQcReport",
  "description": "Fail-fast pre-render keyframe readiness gate report. Written by `vclaw video keyframe-qc` to artifacts/keyframe-qc.json. Verifies every storyboard scene has references/scene<i>-keyframe.png, that each file is a readable PNG, and that all keyframes share the dominant WxH; status is 'fail' iff any severity 'error' finding is present (a uniform-but-nonstandard size is advisory-only).",
  "type": "object",
  "required": [
    "schemaVersion",
    "projectSlug",
    "generatedAt",
    "sceneCount",
    "keyframeCount",
    "dominantDimensions",
    "findings",
    "status"
  ],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": { "const": 1 },
    "projectSlug": { "type": "string", "minLength": 1 },
    "generatedAt": { "type": "string", "format": "date-time" },
    "sceneCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Scene count read from artifacts/storyboard.json (0 when the storyboard is missing/unparseable)."
    },
    "keyframeCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of references/scene<i>-keyframe.png files present on disk (readable or not)."
    },
    "dominantDimensions": {
      "type": ["string", "null"],
      "pattern": "^[0-9]+x[0-9]+$",
      "description": "The dominant (most common) WxH among readable keyframes, e.g. \"1280x720\"; null when no keyframe could be read."
    },
    "findings": {
      "type": "array",
      "items": { "$ref": "#/definitions/Finding" }
    },
    "status": {
      "type": "string",
      "enum": ["pass", "fail"],
      "description": "'fail' iff any severity 'error' finding (missing storyboard, missing/unreadable keyframe, dimension mismatch)."
    }
  },
  "definitions": {
    "Finding": {
      "type": "object",
      "required": ["code", "severity", "detail"],
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "storyboard-missing",
            "keyframe-missing",
            "keyframe-unreadable",
            "keyframe-dimension-mismatch",
            "keyframe-nonstandard-size"
          ]
        },
        "severity": {
          "type": "string",
          "enum": ["error", "advisory"],
          "description": "'error' findings fail the gate; 'advisory' findings never do."
        },
        "sceneIndex": {
          "type": "integer",
          "minimum": 0,
          "description": "Present for per-scene findings (missing/unreadable/mismatched keyframes)."
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "description": "Absolute path of the file the finding is about, when file-scoped."
        },
        "detail": { "type": "string", "minLength": 1 }
      }
    }
  }
}