Hmbown/CodeWhale · error · RuntimeContractError

{kind} is missing required field `{dotted}`

Error message

{kind} is missing required field `{dotted}`

What it means

required_value walked a dotted metric path (for example tool_catalog.modes.plan.full.tools) and hit either a non-dict intermediate value or a missing key. The METRICS/IDENTITIES tables in the checker define every path that must exist in both receipt and budget, so this fires when the JSON lacks a section — typically a budget predating newly added metrics, or a hand-edited document with deleted keys.

Source

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

            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
    ):
        raise RuntimeContractError(
            f"{source} schema_version must be {SCHEMA_VERSION}, got {version!r}"
        )


def required_value(document: dict[str, Any], path: MetricPath, kind: str) -> Any:
    value: Any = document
    dotted = ".".join(path)
    for part in path:
        if not isinstance(value, dict) or part not in value:
            raise RuntimeContractError(f"{kind} is missing required field `{dotted}`")
        value = value[part]
    return value


def tool_identity_digest(names: list[str]) -> str:
    return hashlib.sha256("\0".join(names).encode("utf-8")).hexdigest()


def validate_identity_structure(document: dict[str, Any], kind: str) -> None:
    profile = required_value(document, ("tool_catalog", "surface_profile"), kind)
    if profile != TOOL_SURFACE_PROFILE:
        raise RuntimeContractError(
            f"{kind} tool surface_profile must be `{TOOL_SURFACE_PROFILE}`, "
            f"got {profile!r}"
        )

    for mode, _label in VISIBLE_MODES:
        for surface, _surface_label in TOOL_SURFACES:

View on GitHub (pinned to 8880682c63)

Solutions

1. Add the missing nested section named by the dotted path to the JSON document
2. Regenerate the budget from a passing measurement: `python3 scripts/check-runtime-contract-budget.py --update`
3. Regenerate stale receipts with the current scripts/measure-runtime-contract.py

Example fix

// before — budget JSON lacks the section tool_catalog.modes.operate.active
// after — regenerate instead of hand-patching
# python3 scripts/measure-runtime-contract.py > receipt.json
# python3 scripts/check-runtime-contract-budget.py --receipt receipt.json --update

def has_path(doc, parts):
    for p in parts:
        if not isinstance(doc, dict) or p not in doc:
            return False
        doc = doc[p]
    return True
assert all(has_path(budget, path) for path, _ in METRICS)

When it happens

Trigger: The checker gained new metrics (schema growth) but scripts/runtime-contract-budget.json was not regenerated; a hand-edit deleted a nested section; a receipt produced by an older measure-runtime-contract.py.

Common situations: Pulling checker updates that add metrics; partial manual budget edits; stale receipts from old branches.

Related errors

• {source} document_kind must be `{expected_kind}`, got {actua
• receipt missing required field(s): " + ", ".join(missing)
• baseline provenance build profile/sample count changed
• invalid {kind} {path}: {error}
• invalid {kind} {path}: top level must be an object

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