{"record":{"id":"c2609820ae61b57a","repo":"Hmbown/CodeWhale","slug":"invalid-kind-path-top-level-must-be-an-object","errorCode":null,"errorMessage":"invalid {kind} {path}: top level must be an object","messagePattern":"invalid (.+?) (.+?): top level must be an object","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":167,"sourceCode":"        )\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\n    ):\n        raise RuntimeContractError(","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-runtime-contract-budget.py#L149-L185","documentation":"The JSON file parsed successfully but its top level is not an object — the checker requires a dict to hold document_kind, schema_version, and the metric tree. A top-level array, string, or number fails immediately before any field validation runs. This guards the document shape at the earliest possible point.","triggerScenarios":"Wrapping receipts in a JSON array (for example multi-platform bundles); storing a bare string; saving a JSON fragment instead of the full document.","commonSituations":"Collecting receipts from several CI lanes into one file; tooling that emits arrays by default.","solutions":["Open the file and confirm it starts with `{`; if it is an array, extract the single relevant object","Regenerate the file with scripts/measure-runtime-contract.py rather than hand-assembling it","Pass one file per document to --receipt"],"exampleFix":"// before — file contains a top-level array\n[ { \"document_kind\": \"codewhale.runtime_contract_receipt\", ... } ]\n// after\n{ \"document_kind\": \"codewhale.runtime_contract_receipt\", ... }","handlingStrategy":"type-guard","validationCode":"doc = json.loads(text)\nassert isinstance(doc, dict), f'top level must be an object, got {type(doc).__name__}'","typeGuard":"def is_contract_document(value):\n    return isinstance(value, dict) and isinstance(value.get('document_kind'), str)","tryCatchPattern":null,"preventionTips":["Store one JSON object per file","Regenerate documents with the measure script rather than hand-assembling","Guard the top-level type in any tooling that writes receipts"],"tags":["python","json","type-check","validation"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}