Hmbown/CodeWhale · error · RuntimeContractError

budget metric `representative_context.fixture_id` must be

Error message

budget metric `representative_context.fixture_id` must be `{REPRESENTATIVE_FIXTURE_ID}`, got {fixture_id!r}

What it means

check-runtime-contract-budget.py enforces that the measured receipt's representative context is tied to a single pinned fixture (`representative-v1`) so byte/token budgets stay comparable across runs. If `representative_context.fixture_id` in the budget document is missing, has the wrong type, or names a different fixture, validate_budget raises RuntimeContractError. This keeps the stored budget from silently describing a different measurement corpus.

Solutions

1. Set `representative_context.fixture_id` to exactly "representative-v1" in the budget JSON (or run with `--update` to regenerate the budget from a current receipt).
2. Check `scripts/runtime-contract-budget.json` for a stale or typo'd fixture id and correct it.
3. If the fixture itself legitimately changed, update REPRESENTATIVE_FIXTURE_ID in the script and regenerate the budget in the same change.
4. Ensure the parent `representative_context` key is a JSON object, not a list or scalar.

Example fix

// before (budget JSON)
"representative_context": { "fixture_id": "representative-v2", ... }
// after
"representative_context": { "fixture_id": "representative-v1", ... }

import json
budget = json.load(open("scripts/runtime-contract-budget.json"))
assert budget.get("representative_context", {}).get("fixture_id") == "representative-v1", "stale or wrong fixture_id in budget"

def has_valid_fixture(budget: dict) -> bool:
    rc = budget.get("representative_context")
    return isinstance(rc, dict) and rc.get("fixture_id") == "representative-v1"

try:
    subprocess.run(["python3", "scripts/check-runtime-contract-budget.py", "--receipt", receipt], check=True)
except subprocess.CalledProcessError:
    # fixture id drifted: regenerate budget via --update after review
    ...

When it happens

Trigger: Calling validate_budget (directly or via compare) on a budget JSON whose `representative_context.fixture_id` is absent, not a dict parent, or any value other than "representative-v1"; also hand-editing scripts/runtime-contract-budget.json and renaming the fixture.

Common situations: A developer regenerates or edits the budget file by hand; a new fixture version was introduced elsewhere but the budget was updated without bumping fixture_id (or vice versa); an older budget file predates the fixture_id field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• baseline_observation.accepted_requests must equal…
• baseline_observation.
• budget baseline_receipt path changed
• budget document_kind must be
• budget fixture. must remain

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/d2ae49f6f08d4cfa. Report an issue: GitHub.

Appendix: source

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

        )
    representative_identical = representative.get("prompts_byte_identical")
    if representative_identical is not True:
        raise RuntimeContractError(
            "receipt metric `representative_context.prompts_byte_identical` must be true"
        )
    validate_identity_structure(receipt, "receipt")


def validate_budget(budget: dict[str, Any]) -> None:
    validate_document(budget, BUDGET_KIND, "budget")
    representative = budget.get("representative_context")
    fixture_id = (
        representative.get("fixture_id")
        if isinstance(representative, dict)
        else None
    )
    if fixture_id != REPRESENTATIVE_FIXTURE_ID:
        raise RuntimeContractError(
            "budget metric `representative_context.fixture_id` must be "
            f"`{REPRESENTATIVE_FIXTURE_ID}`, got {fixture_id!r}"
        )
    validate_identity_structure(budget, "budget")


def metric_value(document: dict[str, Any], path: MetricPath, kind: str) -> int:
    value = required_value(document, path, kind)
    dotted = ".".join(path)
    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
        raise RuntimeContractError(
            f"{kind} metric `{dotted}` must be a non-negative integer"
        )
    return value


def compare(
    receipt: dict[str, Any], budget: dict[str, Any]

View on GitHub (pinned to 433685b202)