{"record":{"id":"a96336d8d50266be","repo":"Hmbown/CodeWhale","slug":"source-schema-version-must-be-schema-version-got-version-r","errorCode":null,"errorMessage":"{source} schema_version must be {SCHEMA_VERSION}, got {version!r}","messagePattern":"(.+?) schema_version must be (.+?), got (.+?)","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":186,"sourceCode":"        raise RuntimeContractError(f\"invalid {kind} {path}: top level must be an object\")\n    return document\n\n\ndef validate_document(\n    document: dict[str, Any], expected_kind: str, source: str\n) -> None:\n    actual_kind = document.get(\"document_kind\")\n    if actual_kind != expected_kind:\n        raise RuntimeContractError(\n            f\"{source} document_kind must be `{expected_kind}`, got {actual_kind!r}\"\n        )\n    version = document.get(\"schema_version\")\n    if (\n        isinstance(version, bool)\n        or not isinstance(version, int)\n        or version != SCHEMA_VERSION\n    ):\n        raise RuntimeContractError(\n            f\"{source} schema_version must be {SCHEMA_VERSION}, got {version!r}\"\n        )\n\n\ndef required_value(document: dict[str, Any], path: MetricPath, kind: str) -> Any:\n    value: Any = document\n    dotted = \".\".join(path)\n    for part in path:\n        if not isinstance(value, dict) or part not in value:\n            raise RuntimeContractError(f\"{kind} is missing required field `{dotted}`\")\n        value = value[part]\n    return value\n\n\ndef tool_identity_digest(names: list[str]) -> str:\n    return hashlib.sha256(\"\\0\".join(names).encode(\"utf-8\")).hexdigest()\n\n","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/scripts/check-runtime-contract-budget.py#L168-L204","documentation":"validate_document requires `schema_version` to be the integer SCHEMA_VERSION (currently 1) — booleans are explicitly rejected. Any missing, non-integer, boolean, or wrong-version value raises this RuntimeContractError, guarding against consuming documents produced by an incompatible schema version.","triggerScenarios":"A receipt/budget JSON with schema_version 0, 2, \"1\", 1.0, true, or the field missing entirely.","commonSituations":"Documents generated by an older/newer version of the tool after a schema bump; hand-edited files where the version was mistyped as a string or removed; YAML-to-JSON conversion that turned 1 into \"1\" or true.","solutions":["Set `\"schema_version\": 1` (plain integer) in the document to match the checker's SCHEMA_VERSION.","If the file is from an incompatible tool version, regenerate it with the current measure/checker scripts instead of editing the version by hand.","Ensure the producer serializes the version as a JSON number, not a string or boolean."],"exampleFix":"// before\n{\"document_kind\": \"...\", \"schema_version\": \"1\"}\n// after\n{\"document_kind\": \"...\", \"schema_version\": 1}","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\ndoc = json.loads(Path(path).read_text(encoding=\"utf-8\"))\nversion = doc.get(\"schema_version\")\nif isinstance(version, bool) or not isinstance(version, int) or version != 1:\n    raise SystemExit(f\"{path}: schema_version must be 1, got {version!r}\")","typeGuard":"def has_valid_schema_version(doc, expected: int = 1) -> bool:\n    v = doc.get(\"schema_version\") if isinstance(doc, dict) else None\n    return not isinstance(v, bool) and isinstance(v, int) and v == expected","tryCatchPattern":"try:\n    validate_document(doc, RECEIPT_KIND, \"receipt\")\nexcept RuntimeContractError as e:\n    if \"schema_version\" in str(e):\n        print(\"regenerate the document with the current tool version\")\n    raise","preventionTips":["Always emit schema_version as a JSON integer matching the checker's SCHEMA_VERSION.","Regenerate receipts with the current measure/check scripts after a schema bump rather than editing the version field.","Beware conversions that stringify numbers (YAML -> JSON) — verify with `python3 -m json.tool`."],"tags":["python","json","schema","versioning"],"backgroundTag":"schema-validation-failed","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}