Hmbown/CodeWhale · error · RuntimeContractError

receipt metric `representative_context.fixture_id` must be

Error message

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

What it means

Receipts must be measured against the canonical representative-context fixture; representative_context.fixture_id must equal REPRESENTATIVE_FIXTURE_ID. A different fixture id means the receipt describes a different measurement setup and cannot be compared or converted to a budget.

Solutions

Regenerate the receipt using the current fixture so fixture_id matches REPRESENTATIVE_FIXTURE_ID
Update fixture_id to the exact constant from check-runtime-contract-budget.py
If the fixture legitimately changed, bump REPRESENTATIVE_FIXTURE_ID and regenerate all receipts

Example fix

// before (stale fixture)
"representative_context": {"fixture_id": "fixture-2025-06"}
// after
"representative_context": {"fixture_id": "fixture-2026-09"}

Defensive patterns

Strategy: validation

Validate before calling

from scripts.check_runtime_contract_budget import REPRESENTATIVE_FIXTURE_ID
rep = doc.get("representative_context", {})
assert isinstance(rep, dict) and rep.get("fixture_id") == REPRESENTATIVE_FIXTURE_ID

Try / catch

try:
    budget = budget_from_receipt(receipt)
except RuntimeContractError as e:
    if "fixture_id must be" in str(e):
        raise SystemExit("receipt measured against a different fixture; regenerate")
    raise

Prevention

Import REPRESENTATIVE_FIXTURE_ID rather than hardcoding the id
Regenerate all receipts when the fixture changes and commit them together
Record the fixture id in CI artifacts to catch skew before compare

When it happens

Trigger: validate_receipt encounters fixture_id that is missing, null, or any string other than REPRESENTATIVE_FIXTURE_ID.

Common situations: The fixture was renamed/rotated in the repo but old receipts still reference the previous id; measuring against a locally modified fixture; version skew between the receipt producer and the checking script.

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

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

Appendix: source

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

    validate_document(receipt, RECEIPT_KIND, "receipt")
    skill_discovery = receipt.get("skill_discovery")
    identical = (
        skill_discovery.get("prompts_byte_identical")
        if isinstance(skill_discovery, dict)
        else None
    )
    if identical is not True:
        raise RuntimeContractError(
            "receipt metric `skill_discovery.prompts_byte_identical` must be true"
        )
    representative = receipt.get("representative_context")
    fixture_id = (
        representative.get("fixture_id")
        if isinstance(representative, dict)
        else None
    )
    if fixture_id != REPRESENTATIVE_FIXTURE_ID:
        raise RuntimeContractError(
            "receipt metric `representative_context.fixture_id` must be "
            f"`{REPRESENTATIVE_FIXTURE_ID}`, got {fixture_id!r}"
        )
    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

View on GitHub (pinned to 433685b202)