Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must enforce byte caps via enforce_b

Error message

bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES

What it means

Enforces the 'no unbounded fragment' rule: fragments.rs must reference both MAX_FRAGMENT_BYTES and a clamp helper named enforce_byte_cap (fn enforce_byte_cap(raw, max_bytes) truncates fragment content at creation). Since MAX_FRAGMENT_BYTES is already validated earlier in the function, this practically fires when enforce_byte_cap is renamed, inlined away, or deleted so fragment construction no longer clamps.

Source

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

    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 8880682c63)

Solutions

1. Restore 'fn enforce_byte_cap(raw: String, max_bytes: usize) -> String' in crates/core/src/fragments.rs and route fragment construction through it
2. If the helper must be renamed or shared, keep a thin wrapper named enforce_byte_cap - the gate is a substring check
3. Verify: 'grep -n enforce_byte_cap crates/core/src/fragments.rs'

Example fix

// before (crates/core/src/fragments.rs)
let content = raw.truncate(max_bytes); // inlined clamp, helper deleted

// after
fn enforce_byte_cap(raw: String, max_bytes: usize) -> String { /* truncate */ }
let content = enforce_byte_cap(raw, MAX_FRAGMENT_BYTES);

from pathlib import Path
text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
assert "MAX_FRAGMENT_BYTES" in text and "enforce_byte_cap" in text, "byte-cap enforcement missing"

def is_runtime_contract_error(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and type(exc).__name__ == "RuntimeContractError"

try:
    check_fragment_caps()
except RuntimeContractError as error:
    print(f"[gate] {error}", file=sys.stderr)
    raise SystemExit(2)

When it happens

Trigger: Inlining truncation at call sites with str::truncate; renaming the helper to clamp_bytes; removing the helper after switching to a different bounding strategy.

Common situations: Performance or cleanliness refactors of fragment constructors; unifying clamping into generic newtypes.

Related errors

• DEFAULT_FRAGMENT_MAX_BYTES ({default_bytes}) must not exceed
• DEFAULT_FRAGMENT_MAX_BYTES definition not found
• MAX_FRAGMENTS_PER_CONTEXT must be {FRAGMENT_MAX_COUNT_CEILIN
• MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRA
• FragmentId missing required variant {name}

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/a33d091ea55f886b. Report an issue: GitHub.