{"record":{"id":"ee4f160edbc2c961","repo":"Hmbown/CodeWhale","slug":"kind-tool-surface-profile-must-be-tool-surface","errorCode":null,"errorMessage":"{kind} tool surface_profile must be `{TOOL_SURFACE_PROFILE}`, got {profile!r}","messagePattern":"(.+?) tool surface_profile must be `(.+?)`, got (.+?)","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":207,"sourceCode":"\ndef required_value(document: dict[str, Any], path: MetricPath, kind: str) -> Any:\n    value: Any = document\n    dotted = \".\".join(path)\n    for part in path:\n        if not isinstance(value, dict) or part not in value:\n            raise RuntimeContractError(f\"{kind} is missing required field `{dotted}`\")\n        value = value[part]\n    return value\n\n\ndef tool_identity_digest(names: list[str]) -> str:\n    return hashlib.sha256(\"\\0\".join(names).encode(\"utf-8\")).hexdigest()\n\n\ndef validate_identity_structure(document: dict[str, Any], kind: str) -> None:\n    profile = required_value(document, (\"tool_catalog\", \"surface_profile\"), kind)\n    if profile != TOOL_SURFACE_PROFILE:\n        raise RuntimeContractError(\n            f\"{kind} tool surface_profile must be `{TOOL_SURFACE_PROFILE}`, \"\n            f\"got {profile!r}\"\n        )\n\n    for mode, _label in VISIBLE_MODES:\n        for surface, _surface_label in TOOL_SURFACES:\n            base = (\"tool_catalog\", \"modes\", mode, surface)\n            names = required_value(document, (*base, \"tool_names\"), kind)\n            dotted_names = \".\".join((*base, \"tool_names\"))\n            if (\n                not isinstance(names, list)\n                or any(not isinstance(name, str) or not name for name in names)\n                or names != sorted(set(names))\n            ):\n                raise RuntimeContractError(\n                    f\"{kind} field `{dotted_names}` must be sorted unique non-empty strings\"\n                )\n            count = metric_value(document, (*base, \"tools\"), kind)","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/scripts/check-runtime-contract-budget.py#L189-L225","documentation":"validate_identity_structure compared tool_catalog.surface_profile against the pinned constant `production-default-builtins-no-mcp-no-host-interpreters-v1` and found a different value. The profile string pins the exact tool surface configuration (default builtins, no MCP servers, no host interpreters) under which all tool-catalog ceilings are meaningful; a receipt measured under any other surface is incomparable. Both receipt and budget must carry the same profile.","triggerScenarios":"Measuring with MCP servers configured or host interpreters enabled; changing the default builtin tool set; using a stale receipt from before a profile rename; hand-editing the profile string in the JSON.","commonSituations":"Developer machines with local MCP configuration leaking into measurement; tool-surface redefinitions; mixing receipts across versions.","solutions":["Re-run the measurement in the canonical configuration: default builtins, no MCP servers, no host interpreters","Verify tool_catalog.surface_profile in the receipt matches the TOOL_SURFACE_PROFILE constant at the top of scripts/check-runtime-contract-budget.py","If the surface definition intentionally changed, update TOOL_SURFACE_PROFILE and regenerate the budget with --update as one reviewed change"],"exampleFix":"// before\n\"tool_catalog\": { \"surface_profile\": \"production-default-builtins-with-mcp-v1\", ... }\n// after\n\"tool_catalog\": { \"surface_profile\": \"production-default-builtins-no-mcp-no-host-interpreters-v1\", ... }","handlingStrategy":"validation","validationCode":"expected = 'production-default-builtins-no-mcp-no-host-interpreters-v1'\nassert doc['tool_catalog']['surface_profile'] == expected, doc['tool_catalog']['surface_profile']","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Measure in the canonical surface configuration: default builtins, no MCP servers, no host interpreters","Keep local MCP configuration out of measurement environments","Regenerate receipt and budget together whenever the surface definition changes"],"tags":["python","json","validation","configuration","tooling"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}