{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://scoperail.fokalabs.io/method/evidence-envelope.schema.json",
  "title": "ScopeRail evidence envelope",
  "description": "References and access states that make a response or proposal reviewable without requiring raw source content in telemetry.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "requestRef",
    "scope",
    "coverage",
    "items",
    "limitations",
    "generatedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 160
    },
    "requestRef": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "subjectRef"
      ],
      "properties": {
        "subjectRef": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "tenantRef": {
          "type": "string",
          "maxLength": 200
        },
        "siteRef": {
          "type": "string",
          "maxLength": 200
        },
        "routeRef": {
          "type": "string",
          "maxLength": 300
        }
      }
    },
    "coverage": {
      "type": "string",
      "enum": [
        "sufficient",
        "partial",
        "insufficient"
      ]
    },
    "items": {
      "type": "array",
      "maxItems": 128,
      "items": {
        "$ref": "#/$defs/evidenceItem"
      }
    },
    "limitations": {
      "type": "array",
      "maxItems": 32,
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 500
      }
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "evidenceItem": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "kind",
        "sourceRef",
        "accessState",
        "observedAt",
        "supports"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "kind": {
          "type": "string",
          "enum": [
            "document",
            "live_state",
            "tool_result",
            "policy",
            "user_input"
          ]
        },
        "sourceRef": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "sourceVersion": {
          "type": "string",
          "maxLength": 160
        },
        "accessState": {
          "type": "string",
          "enum": [
            "allowed",
            "filtered",
            "unavailable",
            "denied"
          ]
        },
        "observedAt": {
          "type": "string",
          "format": "date-time"
        },
        "freshUntil": {
          "type": "string",
          "format": "date-time"
        },
        "contentDigest": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{16,256}$",
          "description": "Optional integrity reference. A digest is not anonymization."
        },
        "citationLabel": {
          "type": "string",
          "maxLength": 240
        },
        "supports": {
          "type": "array",
          "maxItems": 24,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 240
          }
        },
        "retrievalScore": {
          "type": "number",
          "description": "Optional ranking diagnostic. It is not a calibrated truth score."
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "accessState": {
                "enum": [
                  "filtered",
                  "denied"
                ]
              }
            },
            "required": [
              "accessState"
            ]
          },
          "then": {
            "properties": {
              "supports": {
                "maxItems": 0
              }
            }
          }
        }
      ]
    }
  }
}