{"record":{"id":"0ddb1776e80eb736","repo":"Hmbown/CodeWhale","slug":"codewhale-terminal-receipt-exceeded-its-total-boun","errorCode":null,"errorMessage":"Codewhale terminal receipt exceeded its total bound","messagePattern":"Codewhale terminal receipt exceeded its total bound","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"integrations/verifiers-codewhale/codewhale_harness/harness.py","lineNumber":272,"sourceCode":"\ndef _bounded_terminal(meta: dict[str, Any]) -> dict[str, Any]:\n    terminal: dict[str, Any] = {}\n    for key in _TERMINAL_FIELDS:\n        if key not in meta or meta[key] is None:\n            continue\n        value = meta[key]\n        if isinstance(value, str):\n            if len(value) > MAX_TERMINAL_STRING_CHARS:\n                raise RuntimeError(\"Codewhale terminal receipt exceeded its string bound\")\n        elif isinstance(value, int) and not isinstance(value, bool):\n            if value < 0 or value > 2**63 - 1:\n                raise RuntimeError(\"Codewhale terminal receipt contained an invalid count\")\n        else:\n            raise RuntimeError(\"Codewhale terminal receipt contained a non-scalar field\")\n        terminal[key] = value\n    encoded = json.dumps(terminal, sort_keys=True, separators=(\",\", \":\")).encode()\n    if len(encoded) > MAX_TERMINAL_RECEIPT_BYTES:\n        raise RuntimeError(\"Codewhale terminal receipt exceeded its total bound\")\n    return terminal\n\n\ndef _install_script(version: str) -> str:\n    version_q = shlex.quote(version)\n    install_q = shlex.quote(INSTALL_DIR)\n    release_q = shlex.quote(RELEASE_ROOT)\n    return f\"\"\"\nset -eu\nversion={version_q}\ninstall_dir={install_q}\nrelease_root={release_q}\nif [ \"$(uname -s)\" != Linux ]; then\n    echo \"automatic Codewhale installation supports Linux runtimes; set binary_path\" >&2\n    exit 1\nfi\ncase \"$(uname -m)\" in\n    x86_64|amd64) platform=linux-x64 ;;","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/integrations/verifiers-codewhale/codewhale_harness/harness.py#L254-L290","documentation":"The harness re-encodes the terminal metadata receipt it extracted from Codewhale's stream-json output and enforces a hard 8 KiB ceiling (MAX_TERMINAL_RECEIPT_BYTES = 8_192 in harness.py). After each field passes per-value bounds (strings <= 512 chars, ints in [0, 2^63-1]), the whole dict is JSON-dumped and its byte length is checked. This error means the receipt was structurally valid but its combined fields serialized to more than 8192 bytes, so the harness refuses to retain it in trace metadata.","triggerScenarios":"A Codewhale binary emits a terminal metadata event whose _TERMINAL_FIELDS (provider, model, status, error_category, the four sha256 fields, token counts, etc.) collectively exceed 8192 bytes when JSON-encoded with sort_keys and compact separators. Typical cause: several string fields each near the 512-char limit (e.g. a very long model name plus long status/termination_reason/error_category strings), or a binary version that adds fields beyond the pinned 0.9.1 set.","commonSituations":"Version skew: a newer or locally patched Codewhale facade (binary_path override) emits richer metadata than release 0.9.1; debug builds that embed long diagnostic strings into status/error_category; provider identifiers that include long suffixes. The harness pins version 0.9.1 for reproducible rollouts precisely to avoid this drift.","solutions":["Pin CodewhaleHarnessConfig.version to the supported release (default '0.9.1') so the terminal receipt field set and sizes match what the harness validates.","If using binary_path with a candidate build, shorten the oversized string fields (model, provider, status, termination_reason, error_category) in the facade's terminal metadata so the encoded receipt stays under 8192 bytes.","Reproduce locally: json.dumps(terminal, sort_keys=True, separators=(',', ':')) on the facade's metadata event and inspect which fields dominate the 8192-byte budget.","If a legitimately larger receipt is required, raise MAX_TERMINAL_RECEIPT_BYTES and MAX_TERMINAL_STRING_CHARS in harness.py deliberately, with a matching change on the producer side."],"exampleFix":"# before: facade writes unbounded diagnostic into the receipt\nmeta['error_category'] = f'{exc!r}'  # can be thousands of chars\n\n# after: bounded field, receipt stays under the total bound\nmeta['error_category'] = exc.__class__.__name__[:512]","handlingStrategy":"validation","validationCode":"def receipt_fits_bound(terminal: dict) -> bool:\n    encoded = json.dumps(terminal, sort_keys=True, separators=(\",\", \":\")).encode()\n    return len(encoded) <= 8192 and all(\n        len(v) <= 512 for v in terminal.values() if isinstance(v, str)\n    )","typeGuard":"def is_bounded_terminal(meta: dict) -> bool:\n    allowed = {\"receipt_kind\", \"provider\", \"model\", \"status\"}  # subset check\n    return isinstance(meta, dict) and receipt_fits_bound(meta) and all(\n        isinstance(v, (str, int)) and not isinstance(v, bool) for v in meta.values()\n    )","tryCatchPattern":null,"preventionTips":["Pin CodewhaleHarnessConfig.version to the release the harness contract was written for (0.9.1).","When testing candidate facades via binary_path, assert json.dumps(terminal, sort_keys=True, separators=(',', ':')) stays under 8192 bytes in facade unit tests.","Keep receipt string fields (model, provider, status, error_category) bounded to well under 512 chars at emission time."],"tags":["json","limits","validation","codewhale-harness","metadata"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}