{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://abdess.github.io/retrobios/api/v1/schemas/core-probe-record.schema.json",
  "title": "RetroBIOS core probe record",
  "description": "One line of measurements/<emulator>.jsonl: one run of scripts/core_probe.py, a libretro core executed headless, in full, with what is needed to judge and reproduce it. Every repetition, its core logs and per-frame hashes, and the raw timing values are in the line. From record_version 4 every repetition and every variant carries the boot oracle's verdict (boots, bios_error, crash, hang, unknown) with the evidence that decided it. From record_version 5 each also names the BIOS the core ran (`bios_used`), and a record judged again from an earlier one's runs carries `judged_at` and `judged_by`.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "record_version",
    "id",
    "emulator",
    "subject",
    "supersedes",
    "kind",
    "recorded_at",
    "core",
    "frontend",
    "host",
    "inputs",
    "variants",
    "flags"
  ],
  "properties": {
    "record_version": {
      "enum": [
        3,
        4,
        5
      ],
      "description": "3: records before the boot oracle. 4: every repetition and variant carries `verdict` and `verdict_evidence`, and `inputs.oracle` names what the verdicts were judged against. 5: they also carry `bios_used`."
    },
    "id": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}-[0-9a-f]{12}$",
      "description": "Date and the first 12 hex digits of the sha256 of the record without its id (canonical JSON: sorted keys, no spaces). A record carried over from the first layout keeps its first id, which hashes that full record."
    },
    "emulator": {
      "$ref": "#/$defs/slug",
      "description": "The emulator profile the record is filed under: measurements/<emulator>.jsonl."
    },
    "subject": {
      "$ref": "#/$defs/slug",
      "description": "What the record tests. Reruns of one test share it, and the site shows the latest record of each."
    },
    "supersedes": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}-[0-9a-f]{12}$"
        }
      ],
      "description": "Id of an earlier record of the same file this one corrects. Lines are never rewritten."
    },
    "migrated_from_version": {
      "const": 1,
      "description": "Present on a record converted from the first layout, whose id hashes that layout."
    },
    "kind": {
      "enum": [
        "run",
        "bench",
        "check"
      ]
    },
    "recorded_at": {
      "type": "string",
      "format": "date-time"
    },
    "core": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "file",
        "sha256",
        "repo",
        "commit",
        "build_command",
        "compiler",
        "library_name",
        "library_version"
      ],
      "properties": {
        "file": {
          "type": "string",
          "minLength": 1
        },
        "sha256": {
          "$ref": "#/$defs/sha256"
        },
        "repo": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "commit": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[0-9a-f]{7,40}$"
        },
        "build_command": {
          "type": [
            "string",
            "null"
          ]
        },
        "compiler": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "library_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "library_version": {
          "type": [
            "string",
            "null"
          ]
        },
        "artifact": {
          "type": "string",
          "format": "uri",
          "description": "Where the .so was downloaded from, such as a libretro buildbot nightly. Absent for a core built locally."
        }
      }
    },
    "frontend": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "script",
        "commit",
        "script_modified",
        "script_sha256"
      ],
      "properties": {
        "script": {
          "enum": [
            "scripts/core_probe.py",
            "scripts/pack_probe.py",
            "scripts/standalone_probe.py"
          ]
        },
        "commit": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[0-9a-f]{40}$"
        },
        "script_modified": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "script_sha256": {
          "$ref": "#/$defs/sha256"
        }
      }
    },
    "host": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "cpu_model",
        "cpu_count",
        "os",
        "kernel",
        "machine",
        "python",
        "load_before",
        "load_after",
        "max_load"
      ],
      "properties": {
        "cpu_model": {
          "type": [
            "string",
            "null"
          ]
        },
        "cpu_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1
        },
        "os": {
          "type": "string"
        },
        "kernel": {
          "type": "string"
        },
        "machine": {
          "type": "string"
        },
        "python": {
          "type": "string"
        },
        "load_before": {
          "$ref": "#/$defs/load"
        },
        "load_after": {
          "$ref": "#/$defs/load"
        },
        "max_load": {
          "type": "number",
          "minimum": 0
        }
      }
    },
    "inputs": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "content",
        "options",
        "env",
        "frames",
        "warmup",
        "repetitions",
        "presses",
        "observables",
        "frame_hash_every",
        "joypad_ports"
      ],
      "properties": {
        "content": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "label",
                "sha1",
                "size",
                "tracks"
              ],
              "properties": {
                "label": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "sha1": {
                  "$ref": "#/$defs/sha1"
                },
                "size": {
                  "type": "integer",
                  "minimum": 0
                },
                "tracks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "file",
                      "sha1",
                      "size"
                    ],
                    "properties": {
                      "file": {
                        "type": "string"
                      },
                      "sha1": {
                        "$ref": "#/$defs/sha1"
                      },
                      "size": {
                        "type": "integer",
                        "minimum": 0
                      }
                    }
                  }
                }
              }
            }
          ]
        },
        "options": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "env": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "joypad_ports": {
          "type": "integer",
          "minimum": 0
        },
        "frames": {
          "type": "integer",
          "minimum": 1
        },
        "warmup": {
          "type": "integer",
          "minimum": 0
        },
        "repetitions": {
          "type": "integer",
          "minimum": 1
        },
        "presses": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "frame",
              "button",
              "length"
            ],
            "properties": {
              "frame": {
                "type": "integer",
                "minimum": 0
              },
              "button": {
                "type": "integer",
                "minimum": 0,
                "maximum": 15
              },
              "length": {
                "type": "integer",
                "minimum": 1
              }
            }
          }
        },
        "observables": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "frame_hash_every": {
          "type": "integer",
          "minimum": 0
        },
        "oracle": {
          "$ref": "#/$defs/oracle"
        }
      }
    },
    "variants": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "label",
          "system_files",
          "repetitions",
          "flags"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          },
          "system_files": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/$defs/sha1"
                }
              ]
            }
          },
          "repetitions": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/$defs/repetition"
            }
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "verdict": {
            "$ref": "#/$defs/verdict",
            "description": "The verdict every repetition of the variant agrees on, else unknown."
          },
          "verdict_evidence": {
            "$ref": "#/$defs/verdict_evidence"
          },
          "bios_used": {
            "$ref": "#/$defs/bios_used"
          }
        }
      }
    },
    "flags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "timing": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ms_per_frame",
        "fps"
      ],
      "properties": {
        "ms_per_frame": {
          "$ref": "#/$defs/stats"
        },
        "fps": {
          "$ref": "#/$defs/stats"
        }
      }
    },
    "check": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "claim",
        "method",
        "observable",
        "variable",
        "result"
      ],
      "properties": {
        "claim": {
          "type": "string",
          "minLength": 1
        },
        "method": {
          "type": "string",
          "minLength": 1
        },
        "observable": {
          "type": "string",
          "minLength": 1
        },
        "variable": {
          "type": "string",
          "minLength": 1
        },
        "result": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "status",
            "statement",
            "groups"
          ],
          "properties": {
            "status": {
              "enum": [
                "same",
                "differs",
                "inconclusive"
              ]
            },
            "statement": {
              "type": "string",
              "minLength": 1
            },
            "groups": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "value",
                  "variants"
                ],
                "properties": {
                  "value": {},
                  "variants": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "verdicts": {
              "type": "object",
              "additionalProperties": {
                "$ref": "#/$defs/verdict"
              },
              "description": "Variant label -> the variant's verdict."
            }
          }
        }
      }
    },
    "judged_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the runs of the record it supersedes were judged again, offline, against the current oracle. recorded_at stays the time the runs were made."
    },
    "judged_by": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "script",
        "commit",
        "script_sha256"
      ],
      "properties": {
        "script": {
          "const": "scripts/core_probe.py"
        },
        "commit": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[0-9a-f]{40}$"
        },
        "script_sha256": {
          "$ref": "#/$defs/sha256"
        }
      },
      "description": "The core_probe that judged the runs again: frontend names the one that ran them."
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "kind": {
            "const": "bench"
          }
        }
      },
      "then": {
        "required": [
          "timing"
        ],
        "properties": {
          "inputs": {
            "properties": {
              "repetitions": {
                "minimum": 5
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "check"
          }
        }
      },
      "then": {
        "required": [
          "check"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "record_version": {
            "enum": [
              4,
              5
            ]
          }
        }
      },
      "then": {
        "properties": {
          "inputs": {
            "required": [
              "oracle"
            ]
          },
          "variants": {
            "items": {
              "required": [
                "verdict",
                "verdict_evidence"
              ],
              "properties": {
                "repetitions": {
                  "items": {
                    "required": [
                      "verdict",
                      "verdict_evidence"
                    ]
                  }
                }
              }
            }
          },
          "check": {
            "properties": {
              "result": {
                "required": [
                  "verdicts"
                ]
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "record_version": {
            "const": 5
          }
        }
      },
      "then": {
        "properties": {
          "variants": {
            "items": {
              "required": [
                "bios_used"
              ],
              "properties": {
                "repetitions": {
                  "items": {
                    "required": [
                      "bios_used"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "sha1": {
      "type": "string",
      "pattern": "^[0-9a-f]{40}$"
    },
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "load": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": {
            "type": "number",
            "minimum": 0
          }
        }
      ]
    },
    "stats": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "median",
        "mean",
        "stdev",
        "min",
        "max",
        "raw"
      ],
      "properties": {
        "median": {
          "type": "number"
        },
        "mean": {
          "type": "number"
        },
        "stdev": {
          "type": "number",
          "minimum": 0
        },
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        },
        "raw": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "number"
          }
        }
      },
      "description": "Statistics over the repetitions, with the values they were computed from."
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9]+(?:[-_][a-z0-9]+)*$"
    },
    "repetition": {
      "type": "object",
      "required": [
        "loaded",
        "library_name",
        "logs"
      ],
      "properties": {
        "loaded": {
          "type": "boolean"
        },
        "library_name": {
          "type": "string"
        },
        "library_version": {
          "type": "string"
        },
        "fps_nominal": {
          "type": "number"
        },
        "frames": {
          "type": "integer",
          "minimum": 1
        },
        "warmup": {
          "type": "integer",
          "minimum": 0
        },
        "wall_s": {
          "type": "number",
          "minimum": 0
        },
        "ms_per_frame": {
          "type": "number",
          "minimum": 0
        },
        "fps": {
          "type": "number",
          "minimum": 0
        },
        "observables": {
          "type": "object"
        },
        "logs": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "frame",
              "level",
              "text"
            ],
            "properties": {
              "frame": {
                "type": "integer",
                "minimum": 0
              },
              "level": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "options_declared": {
          "type": "object"
        },
        "env_unanswered": {
          "type": "object"
        },
        "last_frame_size": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "tracing": {
          "type": "string"
        },
        "isolation": {
          "type": "string",
          "description": "How the core ran: `bwrap` (read-only tree, no network, the user's credentials masked, an empty environment beside the --env values) or `environment only: ...` with the reason bubblewrap was not used."
        },
        "input_queries": {
          "type": "integer",
          "minimum": 0
        },
        "input_pressed": {
          "type": "integer",
          "minimum": 0
        },
        "files_opened": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "path",
                  "sha1_after",
                  "sha1_staged"
                ],
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "sha1_after": {
                    "$ref": "#/$defs/sha1"
                  },
                  "sha1_staged": {
                    "oneOf": [
                      {
                        "type": "null"
                      },
                      {
                        "$ref": "#/$defs/sha1"
                      }
                    ]
                  }
                }
              }
            }
          ]
        },
        "files_probed_absent": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "verdict": {
          "$ref": "#/$defs/verdict"
        },
        "verdict_evidence": {
          "$ref": "#/$defs/verdict_evidence"
        },
        "exit": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "status",
            "signal"
          ],
          "properties": {
            "status": {
              "type": [
                "integer",
                "null"
              ]
            },
            "signal": {
              "type": [
                "string",
                "null"
              ]
            },
            "timeout_s": {
              "type": "number",
              "minimum": 0
            }
          },
          "description": "How a worker that did not finish ended: its exit status or the signal that killed it, or the timeout after which the probe killed it."
        },
        "bios_used": {
          "$ref": "#/$defs/bios_used"
        }
      }
    },
    "verdict": {
      "enum": [
        "boots",
        "bios_error",
        "crash",
        "hang",
        "unknown"
      ],
      "description": "boots: a reference frame of the content was reached. bios_error: an error pattern of the core log or a known error screen, and no reference frame. crash: the worker died. hang: killed after the timeout, or every sampled frame of the second half is one colour. unknown: none of these."
    },
    "verdict_evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "rule",
        "detail"
      ],
      "properties": {
        "rule": {
          "enum": [
            "reference_frame",
            "error_pattern",
            "error_screen",
            "exit_status",
            "timeout",
            "uniform_tail",
            "no_evidence",
            "repetitions_agree",
            "repetitions_disagree"
          ]
        },
        "detail": {
          "type": "string",
          "minLength": 1
        },
        "frame": {
          "type": "integer",
          "minimum": 0
        },
        "sha1": {
          "$ref": "#/$defs/sha1"
        },
        "stages": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/stage"
          },
          "description": "Stages of the reference frames the run reached, in the order first reached."
        },
        "pattern": {
          "type": "string"
        },
        "log": {
          "type": "string"
        },
        "exit_status": {
          "type": [
            "integer",
            "null"
          ]
        },
        "signal": {
          "type": [
            "string",
            "null"
          ]
        },
        "repetitions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/verdict"
          }
        },
        "bios_log": {
          "type": "string",
          "description": "The log line that names the BIOS the core ran."
        }
      }
    },
    "stage": {
      "enum": [
        "bios",
        "game"
      ],
      "description": "bios: a screen only the console's own BIOS draws (its logo). game: a screen of the content itself."
    },
    "oracle": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "file",
            "sha256",
            "references",
            "error_patterns",
            "error_screens"
          ],
          "properties": {
            "file": {
              "type": "string"
            },
            "sha256": {
              "$ref": "#/$defs/sha256"
            },
            "references": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "sha1",
                  "stage",
                  "shows"
                ],
                "properties": {
                  "sha1": {
                    "$ref": "#/$defs/sha1"
                  },
                  "stage": {
                    "$ref": "#/$defs/stage"
                  },
                  "shows": {
                    "type": "string"
                  }
                }
              }
            },
            "error_patterns": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "error_screens": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "sha1",
                  "shows"
                ],
                "properties": {
                  "sha1": {
                    "$ref": "#/$defs/sha1"
                  },
                  "shows": {
                    "type": "string"
                  }
                }
              }
            },
            "bios_patterns": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Log lines by which the core says it loaded the console's own BIOS: they add the bios stage when its screens are hidden."
            },
            "fallback_patterns": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Log lines after which the core runs its built-in BIOS."
            },
            "load_patterns": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Log lines naming the BIOS file the core loaded, in a group named path."
            }
          }
        }
      ],
      "description": "What the verdicts were judged against: the reference frames of this content and core, the core's error patterns, error screens and BIOS load patterns, from the oracle file at its sha256. Null when the run had no oracle entry."
    },
    "bios_used": {
      "type": "string",
      "pattern": "^(staged:.+|builtin|unknown)$",
      "description": "The BIOS the core ran, from its log: staged:<dest> for the staged file a load line names, builtin when a fallback line says the core ran its own BIOS (OpenBIOS, HLE), unknown when the log says neither. An opened file is no proof."
    }
  }
}