Hmbown/CodeWhale · error · RuntimeContractError

TUI fragment module must enforce MAX_FRAGMENT_BYTES…

Error message

TUI fragment module must enforce MAX_FRAGMENT_BYTES (10K-token ceiling)

What it means

The TUI fragment module must reference MAX_FRAGMENT_BYTES, proving the TUI applies the same 40_000-byte (10K-token) fragment ceiling as core rather than allowing larger local fragments. If the literal is absent from crates/tui/src/model_context/fragment.rs, check_fragment_caps raises this error. It fails closed on the shared cap contract from issue #5264.

Solutions

Import and use MAX_FRAGMENT_BYTES from codewhale_core::fragments in crates/tui/src/model_context/fragment.rs, clamping fragment content via enforce_byte_cap.
If the import was removed as unused, restore it — it is contractually required to appear in this file.
Run `python scripts/check-runtime-contract-budget.py` to verify the whole fragment-cap section passes.

Example fix

// before
fn build_fragment(text: String) -> Fragment { Fragment::Retrieved(text) }

// after
use codewhale_core::fragments::{enforce_byte_cap, MAX_FRAGMENT_BYTES};

fn build_fragment(text: String) -> Fragment {
    let _ = MAX_FRAGMENT_BYTES;
    Fragment::Retrieved(enforce_byte_cap(text))
}

Defensive patterns

Strategy: validation

Validate before calling

text = open('crates/tui/src/model_context/fragment.rs').read()
assert 'MAX_FRAGMENT_BYTES' in text, 'TUI fragment module must reference MAX_FRAGMENT_BYTES'

Type guard

def tui_enforces_fragment_cap(tui_text: str) -> bool:
    return 'MAX_FRAGMENT_BYTES' in tui_text

Try / catch

try:
    check_fragment_caps()
except RuntimeContractError as e:
    if 'MAX_FRAGMENT_BYTES (10K-token ceiling)' in str(e) and 'model_context' in str(e):
        import_max_fragment_bytes_in_tui_module()

Prevention

Clamp all TUI-side fragment construction with enforce_byte_cap so the MAX_FRAGMENT_BYTES import stays live and meaningful.
Do not let lint cleanup remove the cap import from model_context/fragment.rs; the checker requires it there.
Run the contract check in CI so cap regressions fail before merge.

When it happens

Trigger: Running the contract check when the TUI fragment module exists and has ProjectInstructions but never mentions MAX_FRAGMENT_BYTES — caps imported under different names, cap logic removed locally, or fragments built without clamping in the TUI path.

Common situations: A TUI-side refactor replaces the imported constant with a local limit under a different name; a cleanup removes 'unused' imports leaving fragments unclamped; a contributor implements TUI fragments without knowing the shared-cap contract.

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

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

Appendix: source

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

    # 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)"
        )
    if "MAX_FRAGMENT_BYTES" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must enforce MAX_FRAGMENT_BYTES (10K-token ceiling)"
        )
    if "matches_text" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must expose a matches_text recognizer"
        )


def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--receipt",
        type=Path,
        help="check an existing measurement JSON instead of compiling",
    )
    parser.add_argument(
        "--budget",
        type=Path,

View on GitHub (pinned to 433685b202)