{"record":{"id":"a33d091ea55f886b","repo":"Hmbown/CodeWhale","slug":"bounded-fragment-module-must-enforce-byte-caps-via-enforce","errorCode":null,"errorMessage":"bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES","messagePattern":"bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":589,"sourceCode":"    for candidate in required_candidates:\n        if candidate not in text:\n            raise RuntimeContractError(\n                f\"PROJECT_INSTRUCTION_CANDIDATES missing required entry {candidate!r}\"\n            )\n\n    # matches_text recognizer must exist on the fragment trait\n    if \"fn matches_text\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must define a matches_text recognizer on the fragment trait\"\n        )\n    if \"trait ContextFragment\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must define trait ContextFragment with matches_text\"\n        )\n\n    # No unbounded fragment — enforce that creation clamps to MAX_FRAGMENT_BYTES\n    if \"MAX_FRAGMENT_BYTES\" not in text or \"enforce_byte_cap\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES\"\n        )\n\n    # TUI must be unified with the core boundary (shared crates/core module)\n    tui_fragment = REPO_ROOT / \"crates\" / \"tui\" / \"src\" / \"model_context\" / \"fragment.rs\"\n    try:\n        tui_text = tui_fragment.read_text(encoding=\"utf-8\")\n    except FileNotFoundError as error:\n        raise RuntimeContractError(\n            f\"missing TUI fragment module: {tui_fragment} ({error})\"\n        ) from error\n    if \"codewhale_core::fragments\" not in tui_text:\n        raise RuntimeContractError(\n            \"TUI model_context/fragment.rs must re-export caps from codewhale_core::fragments (shared crates/core boundary)\"\n        )\n    if \"ProjectInstructions\" not in tui_text:\n        raise RuntimeContractError(\n            \"TUI fragment module must include ProjectInstructions variant (unified with core)\"","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/scripts/check-runtime-contract-budget.py#L571-L607","documentation":"The bounded-fragment contract (issue #5264) forbids unbounded context fragments: creation must clamp through an enforce_byte_cap function using the MAX_FRAGMENT_BYTES constant. If either literal is absent from crates/core/src/fragments.rs, check_fragment_caps raises this error. It fails closed so a fragment path that bypasses the 40_000-byte ceiling cannot ship.","triggerScenarios":"Running the contract check when fragments.rs is missing 'MAX_FRAGMENT_BYTES' or 'enforce_byte_cap' in its text — e.g. the cap function was renamed (clamp_bytes, truncate), inlined into constructors, or the constant redefined under another name.","commonSituations":"A perf refactor inlines the byte-cap clamp and deletes the helper; the constant is renamed to MAX_BYTES; new fragment constructors build content without calling enforce_byte_cap and the helper is removed as 'dead code'; the dead-code budget script pushes removal of an apparently-unused helper.","solutions":["Restore/define `pub const MAX_FRAGMENT_BYTES: usize` and a `pub fn enforce_byte_cap(...)` in crates/core/src/fragments.rs and call the latter from every fragment constructor.","If the helper was removed as dead code, keep it and annotate/mark it as the enforced cap entry point rather than deleting it.","Run `python scripts/check-runtime-contract-budget.py` after edits to verify all fragment-cap assertions pass."],"exampleFix":"// before\nimpl ProjectInstructions {\n    fn new(text: String) -> Self { Self { text } }\n}\n\n// after\npub const MAX_FRAGMENT_BYTES: usize = MAX_FRAGMENT_TOKENS * 4;\n\npub fn enforce_byte_cap(text: String) -> String {\n    if text.len() <= MAX_FRAGMENT_BYTES { text } else { text.chars().take(MAX_FRAGMENT_BYTES / 4).collect() }\n}\n\nimpl ProjectInstructions {\n    fn new(text: String) -> Self { Self { text: enforce_byte_cap(text) } }\n}","handlingStrategy":"validation","validationCode":"text = open('crates/core/src/fragments.rs').read()\nassert 'MAX_FRAGMENT_BYTES' in text and 'enforce_byte_cap' in text, 'fragments.rs must keep MAX_FRAGMENT_BYTES and enforce_byte_cap'","typeGuard":"def has_byte_cap_contract(module_text: str) -> bool:\n    return 'MAX_FRAGMENT_BYTES' in module_text and 'enforce_byte_cap' in module_text","tryCatchPattern":"try:\n    check_fragment_caps()\nexcept RuntimeContractError as e:\n    if 'enforce_byte_cap' in str(e):\n        restore_byte_cap_helper_in_fragments_rs()","preventionTips":["Route every fragment constructor through enforce_byte_cap; never inline a private clamp that could be deleted as dead code.","Before removing 'unused' helpers in fragments.rs, run scripts/check-runtime-contract-budget.py — some are contract-required.","Do not rename MAX_FRAGMENT_BYTES; the checker greps the literal in two crates."],"tags":["rust","static-analysis","contract-check","fragments","byte-cap"],"backgroundTag":"file-size-limit-exceeded","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}