Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must enforce byte caps via…

Error message

bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES

What it means

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.

Solutions

1. 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.
2. If the helper was removed as dead code, keep it and annotate/mark it as the enforced cap entry point rather than deleting it.
3. Run `python scripts/check-runtime-contract-budget.py` after edits to verify all fragment-cap assertions pass.

Example fix

// before
impl ProjectInstructions {
    fn new(text: String) -> Self { Self { text } }
}

// after
pub const MAX_FRAGMENT_BYTES: usize = MAX_FRAGMENT_TOKENS * 4;

pub fn enforce_byte_cap(text: String) -> String {
    if text.len() <= MAX_FRAGMENT_BYTES { text } else { text.chars().take(MAX_FRAGMENT_BYTES / 4).collect() }
}

impl ProjectInstructions {
    fn new(text: String) -> Self { Self { text: enforce_byte_cap(text) } }
}

text = open('crates/core/src/fragments.rs').read()
assert 'MAX_FRAGMENT_BYTES' in text and 'enforce_byte_cap' in text, 'fragments.rs must keep MAX_FRAGMENT_BYTES and enforce_byte_cap'

def has_byte_cap_contract(module_text: str) -> bool:
    return 'MAX_FRAGMENT_BYTES' in module_text and 'enforce_byte_cap' in module_text

try:
    check_fragment_caps()
except RuntimeContractError as e:
    if 'enforce_byte_cap' in str(e):
        restore_byte_cap_helper_in_fragments_rs()

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• bounded fragment module must define a matches_text…
• bounded fragment module must define…
• bounded fragment module must define trait ContextFragment…
• PROJECT_INSTRUCTION_CANDIDATES missing required entry
• TUI fragment module must enforce MAX_FRAGMENT_BYTES…

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

Appendix: source

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

    for candidate in required_candidates:
        if candidate not in text:
            raise RuntimeContractError(
                f"PROJECT_INSTRUCTION_CANDIDATES missing required entry {candidate!r}"
            )

    # matches_text recognizer must exist on the fragment trait
    if "fn matches_text" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define a matches_text recognizer on the fragment trait"
        )
    if "trait ContextFragment" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define trait ContextFragment with matches_text"
        )

    # No unbounded fragment — enforce that creation clamps to MAX_FRAGMENT_BYTES
    if "MAX_FRAGMENT_BYTES" not in text or "enforce_byte_cap" not in text:
        raise RuntimeContractError(
            "bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES"
        )

    # TUI must be unified with the core boundary (shared crates/core module)
    tui_fragment = REPO_ROOT / "crates" / "tui" / "src" / "model_context" / "fragment.rs"
    try:
        tui_text = tui_fragment.read_text(encoding="utf-8")
    except FileNotFoundError as error:
        raise RuntimeContractError(
            f"missing TUI fragment module: {tui_fragment} ({error})"
        ) from error
    if "codewhale_core::fragments" not in tui_text:
        raise RuntimeContractError(
            "TUI model_context/fragment.rs must re-export caps from codewhale_core::fragments (shared crates/core boundary)"
        )
    if "ProjectInstructions" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must include ProjectInstructions variant (unified with core)"

View on GitHub (pinned to 433685b202)