Hmbown/CodeWhale · error · RuntimeContractError

invalid {kind} {path}: {error}

Error message

invalid {kind} {path}: {error}

What it means

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.

Source

Thrown at scripts/check-runtime-contract-budget.py:165

            ("representative_context", "stages", stage, "identity_sha256"),
            f"representative {label} stage identity digest",
        )
        for stage, label in REPRESENTATIVE_STAGES
    ),
)


class RuntimeContractError(ValueError):
    """A receipt or budget is missing a required, well-typed metric."""


def load_json(path: Path, kind: str) -> dict[str, Any]:
    try:
        document = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError as error:
        raise RuntimeContractError(f"missing {kind}: {path}") from error
    except (OSError, json.JSONDecodeError) as error:
        raise RuntimeContractError(f"invalid {kind} {path}: {error}") from error
    if not isinstance(document, dict):
        raise RuntimeContractError(f"invalid {kind} {path}: top level must be an object")
    return document


def validate_document(
    document: dict[str, Any], expected_kind: str, source: str
) -> None:
    actual_kind = document.get("document_kind")
    if actual_kind != expected_kind:
        raise RuntimeContractError(
            f"{source} document_kind must be `{expected_kind}`, got {actual_kind!r}"
        )
    version = document.get("schema_version")
    if (
        isinstance(version, bool)
        or not isinstance(version, int)
        or version != SCHEMA_VERSION

View on GitHub (pinned to 8880682c63)

Solutions

1. Run `python3 -m json.tool <file>` on the offending path to locate the syntax error
2. Fix the JSON: remove trailing commas and comments, quote keys
3. If it was an OSError, check file permissions and readability
4. Prefer regenerating the budget via `--update` over hand-editing ceilings

Example fix

// before
{
  "document_kind": "codewhale.runtime_contract_receipt",
}
// after
{
  "document_kind": "codewhale.runtime_contract_receipt"
}

import json
doc = json.loads(path.read_text(encoding='utf-8'))  # pre-parse to surface syntax errors early

try:
    doc = load_json(path, 'budget')
except RuntimeContractError as e:
    subprocess.run(['python3', '-m', 'json.tool', str(path)])
    raise

When it happens

Trigger: Hand-editing scripts/runtime-contract-budget.json and leaving a trailing comma; a file truncated mid-write; unreadable permissions; non-UTF-8 content.

Common situations: Manual ceiling tweaks that break JSON syntax; editor auto-format mishaps; partially copied or synced files.

Related errors

• baseline provenance build profile/sample count changed
• invalid {kind} {path}: top level must be an object
• {source} document_kind must be `{expected_kind}`, got {actua
• {kind} is missing required field `{dotted}`
• {kind} tool surface_profile must be `{TOOL_SURFACE_PROFILE}`

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/44e8db9d33a5c8b3. Report an issue: GitHub.