{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://socair.ai/schema/report/v1.json",
  "title": "Socair Model Assurance Attestation",
  "description": "The cross-stack report contract. The engine produces it, the CLI prints it, the SvelteKit wizard renders it, and the MCP wrapper serves it. Versioned; breaking changes publish a new $id. v1 is frozen at the public release; before it, v1 changed in place with no external consumers (2026-10-02: the LEAD check status and findings.leads were added; 2026-10-09: the optional tier2 section and the Tier 2 pair of bounded statements were added).",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "header",
    "artifact",
    "scope",
    "checks",
    "findings",
    "assurance_level",
    "bounded_statement",
    "out_of_scope",
    "promotion_authorization",
    "verification",
    "issuer"
  ],
  "properties": {
    "schema_version": { "const": "socair.report/v1" },
    "header": {
      "type": "object",
      "additionalProperties": false,
      "required": ["document_id", "template_version", "issued_utc", "artifact_short", "assurance_level_awarded"],
      "properties": {
        "document_id": { "type": "string", "minLength": 1 },
        "template_version": { "type": "string", "minLength": 1 },
        "issued_utc": { "type": "string", "minLength": 1 },
        "rescan_due": { "type": "string", "format": "date-time" },
        "artifact_short": { "type": "string" },
        "assurance_level_awarded": { "type": "string", "minLength": 1 },
        "signer_name": { "type": "string" },
        "signer_role": { "type": "string" },
        "signer_key_id": { "type": "string" },
        "document_hash": { "type": "string" }
      }
    },
    "artifact": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "file_name", "sha256", "format", "size_bytes"],
      "properties": {
        "name": { "type": "string" },
        "architecture": { "type": "string" },
        "split": { "type": "string" },
        "repo_url": { "type": "string" },
        "commit_or_tag": { "type": "string" },
        "commit_sha": { "type": "string" },
        "publisher": { "type": "string" },
        "publisher_signing_status": { "type": "string" },
        "file_name": { "type": "string", "minLength": 1 },
        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
        "format": { "type": "string", "minLength": 1 },
        "size_bytes": { "type": "integer", "minimum": 0 },
        "quant_declared": { "type": "string" },
        "quant_observed": { "type": "string" },
        "tokenizer_hash": { "type": "string" },
        "chat_template_hash": { "type": "string" },
        "files": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["path", "sha256", "size_bytes", "role"],
            "properties": {
              "path": { "type": "string" },
              "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
              "size_bytes": { "type": "integer", "minimum": 0 },
              "role": { "type": "string", "enum": ["weights", "config", "tokenizer", "chat_template", "code", "adapter", "other"] }
            }
          }
        },
        "license": {
          "description": "The license the artifact states: id and name when its statements name one license, disagreement (and no id) when they name more, neither when none was identified. Identity, not a check; only a configured license policy grades it.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": { "type": "string", "description": "A ScanCode LicenseDB key, or a socair- key for a license ScanCode does not key." },
            "name": { "type": "string" },
            "sources": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["source", "value"],
                "properties": {
                  "source": { "type": "string" },
                  "value": { "type": "string" },
                  "id": { "type": "string" },
                  "note": { "type": "string" }
                }
              }
            },
            "disagreement": { "type": "string" }
          }
        },
        "base_models": {
          "description": "The base models the artifact declares (model card base_model, GGUF general.base_model.N), as declared; claims, not verified lineage.",
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name", "source"],
            "properties": {
              "name": { "type": "string" },
              "organization": { "type": "string" },
              "repo": { "type": "string" },
              "url": { "type": "string" },
              "source": { "type": "string" }
            }
          }
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["check_set_version", "execution_context", "input_path"],
      "properties": {
        "check_set_version": { "type": "string" },
        "tool_versions": { "type": "string" },
        "execution_context": { "type": "string" },
        "input_path": { "type": "string", "description": "How the input arrived: 'local path', or the source a bound provenance manifest records (e.g. 'airlock pull'). Never the path on the scanning host; the subject digest identifies the artifact." },
        "scan_start_utc": { "type": "string" },
        "scan_end_utc": { "type": "string" },
        "inference_budget": { "type": "string" },
        "reference_data": { "type": "string", "description": "The reference data the checks compared against: a signed feed by issuer, version, dates, and signing key, and each local input (denylist, tokenizer tables, reviewed templates, license policy) by file name and the SHA-256 of the bytes read, never by its path on the scanning host." },
        "intake_policy": {
          "type": "object",
          "description": "The intake policy (SOCAIR_INTAKE_POLICY) the Intake policy row was checked against: its file's base name and the SHA-256 of its bytes. Present exactly when that row is.",
          "additionalProperties": false,
          "required": ["name", "sha256"],
          "properties": {
            "name": { "type": "string", "minLength": 1 },
            "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
          }
        }
      }
    },
    "checks": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "looks_for", "status"],
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "looks_for": { "type": "string" },
          "status": { "enum": ["PASS", "FAIL", "LEAD", "NOT_TESTED"] },
          "evidence": { "type": "string" },
          "notes": { "type": "string" },
          "pass_means": { "type": "string" },
          "severity": { "enum": ["critical", "high", "medium", "low"] },
          "maps_to": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["framework", "id", "name"],
              "properties": {
                "framework": { "type": "string", "minLength": 1 },
                "version": { "type": "string", "minLength": 1, "description": "The edition of the framework the entry is from, such as 2026.09 for MITRE ATLAS or 2025 for the OWASP LLM Top 10. Absent in reports made before Socair recorded it." },
                "id": { "type": "string", "minLength": 1 },
                "name": { "type": "string", "minLength": 1 }
              }
            }
          }
        }
      }
    },
    "tier2": {
      "description": "Measurements made by running the model (docs/tier2.md). Absent when Tier 2 did not run. A measurement is never a verdict: one that raised a LEAD or FAIL has a check row (named with the suffix ' (Tier 2)') with that status, which withholds promotion; one that found nothing adds no row and authorizes nothing.",
      "type": "object",
      "additionalProperties": false,
      "required": ["statement", "helper", "node_classes", "measurements"],
      "properties": {
        "statement": { "const": "Tier 2 measurements ran the model through the endpoints the operator named, on the node classes listed here as the probe helper reported them; Socair did not observe the hardware or verify that an endpoint served the bytes identified by the artifact hash. A measurement is not a verdict: a LEAD or FAIL it raises is a check row and withholds promotion, and a measurement that found nothing adds no row, is not a PASS, and authorizes nothing." },
        "helper": { "type": "string", "minLength": 1, "description": "The probe helper's name and version, as it reports them." },
        "node_classes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["hash", "reported_by", "facts"],
            "properties": {
              "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "sha256 over the canonical JSON of facts: every field present, keys sorted, no whitespace, no HTML escaping. Any field change changes it." },
              "reported_by": { "enum": ["probe helper (not observed by Socair)"] },
              "facts": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "schema", "gpu_model", "compute_capability", "gpu_count", "interconnect", "driver", "vbios", "ecc", "mig", "cc_mode",
                  "cuda", "cublas", "cudnn", "nccl", "container_image_digest", "engine_name", "engine_version", "engine_commit",
                  "dtype", "weight_quantization", "kv_cache_quantization", "tensor_parallel_size", "pipeline_parallel_size", "expert_parallel_size",
                  "attention_backend", "cuda_graphs", "torch_compile", "eager", "batch_invariant", "prefix_caching", "chunked_prefill",
                  "speculative_decoding", "env"
                ],
                "properties": {
                  "schema": { "const": "socair.nodeclass/v1" },
                  "gpu_model": { "type": "string" },
                  "compute_capability": { "type": "string" },
                  "gpu_count": { "type": "integer", "minimum": 0 },
                  "interconnect": { "type": "string" },
                  "driver": { "type": "string" },
                  "vbios": { "type": "string" },
                  "ecc": { "type": ["boolean", "null"] },
                  "mig": { "type": "string" },
                  "cc_mode": { "type": "string" },
                  "cuda": { "type": "string" },
                  "cublas": { "type": "string" },
                  "cudnn": { "type": "string" },
                  "nccl": { "type": "string" },
                  "container_image_digest": { "type": "string" },
                  "engine_name": { "type": "string" },
                  "engine_version": { "type": "string" },
                  "engine_commit": { "type": "string" },
                  "dtype": { "type": "string" },
                  "weight_quantization": { "type": "string" },
                  "kv_cache_quantization": { "type": "string" },
                  "tensor_parallel_size": { "type": "integer", "minimum": 0 },
                  "pipeline_parallel_size": { "type": "integer", "minimum": 0 },
                  "expert_parallel_size": { "type": "integer", "minimum": 0 },
                  "attention_backend": { "type": "string" },
                  "cuda_graphs": { "type": ["boolean", "null"] },
                  "torch_compile": { "type": ["boolean", "null"] },
                  "eager": { "type": ["boolean", "null"] },
                  "batch_invariant": { "type": ["boolean", "null"] },
                  "prefix_caching": { "type": ["boolean", "null"] },
                  "chunked_prefill": { "type": ["boolean", "null"] },
                  "speculative_decoding": { "type": "string" },
                  "env": { "type": ["object", "null"], "additionalProperties": { "type": "string" } }
                }
              }
            }
          }
        },
        "measurements": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["check", "suite", "suite_version", "dataset_digest", "scorer", "n", "decoding", "engine", "node_class", "started_utc", "ended_utc", "outcome"],
            "properties": {
              "check": { "type": "string", "pattern": "^.*\\S.* \\(Tier 2\\)$" },
              "suite": { "type": "string", "minLength": 1 },
              "suite_version": { "type": "string", "minLength": 1 },
              "dataset_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
              "scorer": { "type": "string", "pattern": "^(deterministic|llm-judge:sha256:[0-9a-f]{64})$" },
              "n": { "type": "integer", "minimum": 0 },
              "score": { "type": "number" },
              "metrics": { "type": "object", "additionalProperties": { "type": "number" } },
              "ci95": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } },
              "decoding": {
                "type": "object",
                "additionalProperties": false,
                "required": ["temperature", "top_p", "max_tokens"],
                "properties": {
                  "temperature": { "type": "number", "minimum": 0 },
                  "top_p": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
                  "max_tokens": { "type": "integer", "minimum": 1 },
                  "seed": { "type": "integer" }
                }
              },
              "engine": { "type": "string", "minLength": 1 },
              "node_class": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
              "reference_node_class": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
              "started_utc": { "type": "string", "format": "date-time" },
              "ended_utc": { "type": "string", "format": "date-time" },
              "outcome": { "enum": ["measured", "lead", "fail", "error"], "description": "There is no pass. measured: completed and raised nothing, which is not evidence of absence. lead: a statistical or judged signal. fail: deterministic, matcher-confirmed evidence, named in evidence. error: did not complete." },
              "evidence": { "type": "string" },
              "notes": { "type": "string" }
            }
          }
        }
      }
    },
    "findings": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "fails": { "type": "array", "items": { "type": "string" } },
        "leads": { "type": "array", "items": { "type": "string" } },
        "not_tested": { "type": "array", "items": { "type": "string" } }
      }
    },
    "assurance_level": {
      "type": "object",
      "additionalProperties": false,
      "required": ["awarded"],
      "properties": {
        "awarded": { "type": "string", "minLength": 1 },
        "definition": { "type": "string" },
        "does_mean": { "type": "string" },
        "does_not_mean": { "type": "string" },
        "tier2_note": { "type": "string" }
      }
    },
    "bounded_statement": {
      "description": "One of four fixed sentences. A report without a tier2 section takes the first pair, one with it the second; within a pair, the first when no row is FAIL or LEAD, the second when any row is. Validation re-derives it from the document, so none may be edited per artifact.",
      "enum": [
        "For the artifact identified by its hash, the Tier 1 checks that returned PASS found no indicators within their stated scope. Rows marked NOT_TESTED were not examined, for the reason each row gives. Tier 1 runs no inference, so no model behavior was tested. Every surface outside that scope is listed under Out of scope.",
        "For the artifact identified by its hash, the Tier 1 checks found the indicators this report lists: each FAIL is positive evidence, and each LEAD is a suspicious signal that needs review. Rows marked NOT_TESTED were not examined, for the reason each row gives. Tier 1 runs no inference, so no model behavior was tested. Every surface outside that scope is listed under Out of scope.",
        "For the artifact identified by its hash, the Tier 1 checks that returned PASS found no indicators within their stated scope, and the Tier 2 measurements raised none. Rows marked NOT_TESTED were not examined, for the reason each row gives. Tier 2 ran the model only on the node classes and probe sets its measurements name, and a measurement that found nothing is not a PASS. Every surface outside that scope is listed under Out of scope.",
        "For the artifact identified by its hash, the checks found the indicators this report lists: each FAIL is positive evidence, and each LEAD is a suspicious signal that needs review; a row marked (Tier 2) was raised by a measurement made by running the model. Rows marked NOT_TESTED were not examined, for the reason each row gives. Tier 2 ran the model only on the node classes and probe sets its measurements name, and a measurement that found nothing is not a PASS. Every surface outside that scope is listed under Out of scope."
      ]
    },
    "out_of_scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["does_not_certify", "ceiling"],
      "properties": {
        "does_not_certify": { "type": "string", "minLength": 1 },
        "ceiling": { "type": "array", "minItems": 1, "items": { "type": "string" } },
        "unparsed_formats": { "type": "array", "items": { "type": "string" } },
        "untested_node_classes": { "type": "array", "items": { "type": "string" } },
        "not_run": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["name", "looks_for", "reason"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "looks_for": { "type": "string" },
              "reason": { "type": "string", "minLength": 1 }
            }
          }
        }
      }
    },
    "promotion_authorization": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authorized"],
      "properties": {
        "authorized": { "type": "boolean" },
        "state": { "enum": ["authorized", "authorized_with_conditions", "withheld", "escalated"] },
        "level": { "type": "string" },
        "conditions": { "type": "string" },
        "accepted_surfaces": { "type": "array", "items": { "type": "string" } },
        "accepted_by": { "type": "string" },
        "accepted_at": { "type": "string" },
        "acceptance_expires": { "type": "string", "format": "date-time" },
        "acceptance": { "type": "string", "contentEncoding": "base64" },
        "reviewed_document_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
      }
    },
    "verification": {
      "type": "object",
      "additionalProperties": false,
      "required": ["signing_method", "artifact_sha256"],
      "properties": {
        "document_hash": { "type": "string" },
        "signing_method": { "type": "string" },
        "signer_key_id": { "type": "string" },
        "artifact_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
        "rerun_instructions": { "type": "string" }
      }
    },
    "issuer": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority"],
      "properties": {
        "signed_by": { "type": "string" },
        "authority": { "type": "string" },
        "warrants": { "type": "string" },
        "excludes": { "type": "string" }
      }
    },
    "appendices": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "check_definitions": { "type": "string" },
        "sarif_reference": { "type": "string" },
        "glossary": { "type": "string" }
      }
    }
  }
}