{"record":{"id":"44e8db9d33a5c8b3","repo":"Hmbown/CodeWhale","slug":"invalid-kind-path-error","errorCode":null,"errorMessage":"invalid {kind} {path}: {error}","messagePattern":"invalid (.+?) (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":165,"sourceCode":"            (\"representative_context\", \"stages\", stage, \"identity_sha256\"),\n            f\"representative {label} stage identity digest\",\n        )\n        for stage, label in REPRESENTATIVE_STAGES\n    ),\n)\n\n\nclass RuntimeContractError(ValueError):\n    \"\"\"A receipt or budget is missing a required, well-typed metric.\"\"\"\n\n\ndef load_json(path: Path, kind: str) -> dict[str, Any]:\n    try:\n        document = json.loads(path.read_text(encoding=\"utf-8\"))\n    except FileNotFoundError as error:\n        raise RuntimeContractError(f\"missing {kind}: {path}\") from error\n    except (OSError, json.JSONDecodeError) as error:\n        raise RuntimeContractError(f\"invalid {kind} {path}: {error}\") from error\n    if not isinstance(document, dict):\n        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","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-runtime-contract-budget.py#L147-L183","documentation":"The receipt or budget file exists but could not be read or parsed: an OSError (permissions, I/O) or json.JSONDecodeError (malformed JSON) escaped load_json. Hand-edited budget files are the usual source — trailing commas, comments, unquoted keys, or truncated files. The underlying error text is appended so you can pinpoint the byte position.","triggerScenarios":"Hand-editing scripts/runtime-contract-budget.json and leaving a trailing comma; a file truncated mid-write; unreadable permissions; non-UTF-8 content.","commonSituations":"Manual ceiling tweaks that break JSON syntax; editor auto-format mishaps; partially copied or synced files.","solutions":["Run `python3 -m json.tool <file>` on the offending path to locate the syntax error","Fix the JSON: remove trailing commas and comments, quote keys","If it was an OSError, check file permissions and readability","Prefer regenerating the budget via `--update` over hand-editing ceilings"],"exampleFix":"// before\n{\n  \"document_kind\": \"codewhale.runtime_contract_receipt\",\n}\n// after\n{\n  \"document_kind\": \"codewhale.runtime_contract_receipt\"\n}","handlingStrategy":"validation","validationCode":"import json\ndoc = json.loads(path.read_text(encoding='utf-8'))  # pre-parse to surface syntax errors early","typeGuard":null,"tryCatchPattern":"try:\n    doc = load_json(path, 'budget')\nexcept RuntimeContractError as e:\n    subprocess.run(['python3', '-m', 'json.tool', str(path)])\n    raise","preventionTips":["Never hand-edit budget JSON; use --update","Validate edits with python3 -m json.tool","Keep files UTF-8 and writes atomic"],"tags":["python","json","validation"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}