Atlas evidence item

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.inorbit.hr/atlas/evidence/v0.json",
  "title": "Atlas evidence item",
  "description": "One piece of evidence with what it rests on (RFC 0086, ADR 0009 and 0016): its reference, the class of the observer that produced it, how it was obtained, everything it was derived from and every way it can fail together with other evidence. Corroboration counts only between independent sources, and two items are dependent when they share an ancestor or a failure mode; proof rules count groups, not items. The shape of tbd_atlas_core::evidence::EvidenceItem, with ids written as the API writes every Atlas id (prefix and UUID, never a bare UUID). The reference is https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/evidence_ref and the class https://schemas.inorbit.hr/atlas/observer/v0.json#/$defs/observer_class; a validator loads all three. The rules the type enforces are enforced here: a model's output is an interpretation and a person's answer testimony and neither can be anything else, no instrument interprets or testifies, an extraction is an interpretation, testimony is testimony, and an item always has its observer among its failure modes. An item names its evidence and its method; it never carries the evidence's content, a prompt or a credential, and every object is closed so a field outside these is refused. Fields the API leaves at their default (an empty list) may be absent. Draft line: it may still be corrected.",
  "type": "object",
  "additionalProperties": false,
  "required": ["reference", "class", "method", "failure_modes"],
  "properties": {
    "reference": {
      "description": "The evidence: its kind and its id, prefixed by the kind (obv_, art_, ext_, tst_ or clm_) and a UUID.",
      "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/evidence_ref"
    },
    "class": {
      "description": "The class of the observer that produced it.",
      "$ref": "https://schemas.inorbit.hr/atlas/observer/v0.json#/$defs/observer_class"
    },
    "method": {
      "description": "How it was obtained.",
      "$ref": "#/$defs/method"
    },
    "ancestors": {
      "description": "Everything it was derived from, recorded at derivation time. Its own reference is implied and not listed. Empty when none.",
      "type": "array",
      "maxItems": 256,
      "uniqueItems": true,
      "items": {
        "$ref": "https://schemas.inorbit.hr/atlas/fact/v0.json#/$defs/evidence_ref"
      }
    },
    "failure_modes": {
      "description": "How it can fail together with other evidence. Its observer is always one.",
      "type": "array",
      "minItems": 1,
      "maxItems": 256,
      "uniqueItems": true,
      "items": {
        "$ref": "#/$defs/failure_mode"
      },
      "contains": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": { "const": "observer" }
        }
      }
    }
  },
  "allOf": [
    {
      "if": {
        "required": ["class"],
        "properties": { "class": { "const": "model_extractor" } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "const": "model_interpretation" } } } }
      }
    },
    {
      "if": {
        "required": ["class"],
        "properties": { "class": { "const": "human_testimony" } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "const": "human_testimony" } } } }
      }
    },
    {
      "if": {
        "required": ["class"],
        "properties": { "class": { "enum": ["direct_sensor", "deterministic_extractor", "external_system"] } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "not": { "enum": ["model_interpretation", "human_testimony"] } } } } }
      }
    },
    {
      "if": {
        "required": ["reference"],
        "properties": { "reference": { "required": ["type"], "properties": { "type": { "const": "extraction" } } } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "const": "model_interpretation" } } } }
      }
    },
    {
      "if": {
        "required": ["reference"],
        "properties": { "reference": { "required": ["type"], "properties": { "type": { "const": "testimony" } } } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "const": "human_testimony" } } } }
      }
    },
    {
      "if": {
        "required": ["reference"],
        "properties": { "reference": { "required": ["type"], "properties": { "type": { "enum": ["observation", "artifact"] } } } }
      },
      "then": {
        "properties": { "method": { "properties": { "category": { "not": { "enum": ["model_interpretation", "human_testimony"] } } } } }
      }
    }
  ],
  "$defs": {
    "method": {
      "description": "How a piece of evidence was obtained (tbd_atlas_core::method::EvidenceMethod): a connector's method with strict, versioned semantics. Two connectors that both produce logs are not equivalent if one keeps a complete, tamper-evident audit log and the other samples a tenth of its application logs; the method says which.",
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "category", "semantics_version", "coverage", "trust", "classification"],
      "properties": {
        "name": {
          "description": "The connector's name for it: dotted lowercase parts, at most 64 characters (grafana.promql.query, sensors.signal).",
          "type": "string",
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
        },
        "category": {
          "description": "What kind of evidence it is. A closed set: proof contracts are written against it.",
          "enum": [
            "static_resolution",
            "runtime_observation",
            "runtime_state",
            "application_trace",
            "metrics",
            "logs",
            "configuration",
            "source_construction",
            "external_record",
            "documentation",
            "text_search",
            "model_interpretation",
            "human_testimony"
          ]
        },
        "semantics_version": {
          "description": "The version of the method's semantics; a change of meaning is a new version.",
          "type": "integer",
          "minimum": 0,
          "maximum": 4294967295
        },
        "coverage": {
          "description": "How completely it sees: best_effort makes no completeness claim, sampled keeps a declared share in parts per thousand (1 to 999), complete sees everything in scope or reports what it missed.",
          "type": "object",
          "required": ["model"],
          "oneOf": [
            {
              "additionalProperties": false,
              "properties": { "model": { "const": "best_effort" } }
            },
            {
              "additionalProperties": false,
              "required": ["per_mille"],
              "properties": {
                "model": { "const": "sampled" },
                "per_mille": { "type": "integer", "minimum": 1, "maximum": 999 }
              }
            },
            {
              "additionalProperties": false,
              "properties": { "model": { "const": "complete" } }
            }
          ]
        },
        "trust": {
          "description": "How far its output can be trusted not to have been altered: mutable can be edited after the fact, authoritative is the system of record, tamper_evident is append-only and signed.",
          "enum": ["mutable", "authoritative", "tamper_evident"]
        },
        "classification": {
          "description": "How sensitive its output is, which decides where it may go.",
          "enum": ["public", "internal", "confidential", "restricted"]
        },
        "capabilities": {
          "description": "What else it can do, declared by the connector (historical, streaming), each 1 to 64 of letters, digits and . _ : / -. Empty when none.",
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._:/-]{1,64}$"
          }
        }
      }
    },
    "label": {
      "description": "A name for a clock, a host, a boot or an upstream source: 1 to 128 characters, no spaces or control characters.",
      "type": "string",
      "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]{1,128}$"
    },
    "failure_mode": {
      "description": "A way two pieces of evidence can fail together (tbd_atlas_core::evidence::FailureMode): read by the same observer, timed by the same host clock, seen through the same kernel in the same boot, derived from the same upstream source, or produced by the same model and prompt (named by digest).",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "v"],
          "properties": {
            "type": { "const": "observer" },
            "v": { "$ref": "https://schemas.inorbit.hr/atlas/observer/v0.json#/$defs/observer_id" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "v"],
          "properties": {
            "type": { "const": "host_clock" },
            "v": { "$ref": "#/$defs/label" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "v"],
          "properties": {
            "type": { "const": "kernel" },
            "v": {
              "type": "object",
              "additionalProperties": false,
              "required": ["host", "boot"],
              "properties": {
                "host": { "$ref": "#/$defs/label" },
                "boot": { "$ref": "#/$defs/label" }
              }
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "v"],
          "properties": {
            "type": { "const": "upstream" },
            "v": { "$ref": "#/$defs/label" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["type", "v"],
          "properties": {
            "type": { "const": "model" },
            "v": { "$ref": "https://schemas.inorbit.hr/atlas/observation/v0.json#/$defs/digest" }
          }
        }
      ]
    }
  }
}