{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://vclaw.dev/schemas/video/artifacts/clip-qc.schema.json",
  "title": "ClipQcReport",
  "description": "Per-second headcount QC over a project's rendered scene clips. Fills the gap between consistency-audit (ONE mid-frame, identity only) and motion-qc (nine frames, morph/vanish only): neither counts people, so a figure walking into frame partway through a clip is invisible to both — the defect that shipped eight clips of a 37-shot film. Written by `vclaw video clip-qc` to artifacts/clip-qc.json.",
  "type": "object",
  "required": ["schemaVersion", "projectSlug", "generatedAt", "scenes", "findings", "ok"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": { "const": 1 },
    "projectSlug": { "type": "string", "minLength": 1 },
    "generatedAt": { "type": "string", "format": "date-time" },
    "ok": {
      "type": "boolean",
      "description": "False when any scene carries an error-severity finding."
    },
    "scenes": {
      "type": "array",
      "items": { "$ref": "#/definitions/SceneResult" }
    },
    "findings": {
      "type": "array",
      "description": "Flattened findings across every scene.",
      "items": { "$ref": "#/definitions/Finding" }
    }
  },
  "definitions": {
    "Finding": {
      "type": "object",
      "required": ["sceneIndex", "code", "severity", "message"],
      "additionalProperties": false,
      "properties": {
        "sceneIndex": { "type": "integer", "minimum": 0 },
        "code": {
          "type": "string",
          "enum": ["headcount-variance", "headcount-exceeds-cast", "frame-extraction-failed"],
          "description": "headcount-variance: the count CHANGES across the clip (someone entered or left). headcount-exceeds-cast: more people than the scene names (invented or duplicated cast). frame-extraction-failed: no frame could be sampled."
        },
        "severity": { "type": "string", "enum": ["error", "warning"] },
        "message": { "type": "string", "minLength": 1 }
      }
    },
    "SceneResult": {
      "type": "object",
      "required": ["sceneIndex", "clipPath", "framesSampled", "counts", "findings", "ok"],
      "additionalProperties": false,
      "properties": {
        "sceneIndex": { "type": "integer", "minimum": 0 },
        "clipPath": { "type": "string", "minLength": 1 },
        "framesSampled": { "type": "integer", "minimum": 0 },
        "counts": {
          "type": "array",
          "description": "People counted per sampled frame, in time order.",
          "items": { "type": "integer", "minimum": 0 }
        },
        "expectedCast": {
          "type": "integer",
          "minimum": 0,
          "description": "Distinct people the storyboard names for this scene (its `characters` field union the @tags resolving to a registered character). Absent when unknown."
        },
        "filmstripPath": {
          "type": "string",
          "description": "Contact sheet of every sampled second, written to projects/<slug>/qc/. Rendered even without a vision key — it is the artefact a human reads."
        },
        "findings": {
          "type": "array",
          "items": { "$ref": "#/definitions/Finding" }
        },
        "ok": { "type": "boolean" }
      }
    }
  }
}
