{"record":{"id":"71f2cbcf96580d7b","repo":"Hmbown/CodeWhale","slug":"receipt-schema-version-changed","errorCode":null,"errorMessage":"receipt schema_version changed","messagePattern":"receipt schema_version changed","errorType":"exception","errorClass":"PersistenceBacklogError","httpStatus":null,"severity":"error","filePath":"scripts/check-persistence-backlog-budget.py","lineNumber":150,"sourceCode":"        \"sample_count\": 1,\n    }\n\n\ndef validate_receipt(\n    receipt: dict[str, Any],\n    *,\n    expected_source: dict[str, Any] | None = None,\n    require_clean_source: bool = False,\n) -> None:\n    missing = [field for field in REQUIRED_RECEIPT_FIELDS if field not in receipt]\n    if missing:\n        raise PersistenceBacklogError(\n            \"receipt missing required field(s): \" + \", \".join(missing)\n        )\n    if receipt[\"document_kind\"] != RECEIPT_KIND:\n        raise PersistenceBacklogError(f\"receipt document_kind must be {RECEIPT_KIND}\")\n    if receipt[\"schema_version\"] != SCHEMA_VERSION:\n        raise PersistenceBacklogError(\"receipt schema_version changed\")\n    for field, expected in FIXTURE.items():\n        validate_frozen_field(field, receipt[field], expected)\n    if not isinstance(receipt[\"source_sha\"], str) or not SOURCE_SHA_PATTERN.fullmatch(\n        receipt[\"source_sha\"]\n    ):\n        raise PersistenceBacklogError(\"receipt source_sha must be an exact lowercase Git SHA\")\n    if type(receipt[\"source_dirty\"]) is not bool:\n        raise PersistenceBacklogError(\"receipt source_dirty must be boolean\")\n    for field, prefix in ((\"rustc_version\", \"rustc \"), (\"cargo_version\", \"cargo \")):\n        if not isinstance(receipt[field], str) or not receipt[field].startswith(prefix):\n            raise PersistenceBacklogError(f\"receipt {field} must be a version string\")\n    validate_frozen_field(\"build_profile\", receipt[\"build_profile\"], \"test\")\n    validate_frozen_field(\"sample_count\", receipt[\"sample_count\"], 1)\n    if expected_source is not None:\n        for field in (\n            \"source_sha\",\n            \"source_dirty\",\n            \"rustc_version\",","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-persistence-backlog-budget.py#L132-L168","documentation":"Raised in validate_receipt (scripts/check-persistence-backlog-budget.py:149-150) when receipt[\"schema_version\"] != 2 (SCHEMA_VERSION). The version gate ensures the receipt layout matches what this checker knows how to interpret before any field is trusted.","triggerScenarios":"Checking a v1 receipt with a v2 checker after bumping SCHEMA_VERSION; regenerating the budget but reusing an old receipt; a draft schema bump where only one side was updated.","commonSituations":"Schema migrations where receipts, baseline, budget, and checker must move in lockstep; long-lived receipts checked out alongside updated tooling.","solutions":["Regenerate the receipt (and baseline receipt) with the current measure script after any schema bump.","When bumping SCHEMA_VERSION, update checker, Rust emitter, budget, and both receipts in one atomic commit.","Discard receipts whose schema_version predates the current gate."],"exampleFix":"// receipt (before)\n\"schema_version\": 1\n// receipt (after)\n\"schema_version\": 2","handlingStrategy":"type-guard","validationCode":"if receipt.get(\"schema_version\") != 2:\n    sys.exit(\"receipt schema is not v2; regenerate with the current measure script\")","typeGuard":"def is_current_schema(doc: dict) -> bool:\n    return doc.get(\"schema_version\") == 2","tryCatchPattern":"try:\n    validate_receipt(receipt)\nexcept PersistenceBacklogError as e:\n    if \"schema_version changed\" in str(e):\n        raise RuntimeError(\"schema migration incomplete: regenerate receipt and baseline\") from e\n    raise","preventionTips":["Bump SCHEMA_VERSION, emitter, budget, and both receipts atomically.","Regenerate every receipt artifact immediately after a version bump.","Refuse to load receipts whose schema_version predates the checker."],"tags":["validation","json","schema-version","migration"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}