Hmbown/CodeWhale · error · RuntimeContractError

missing bounded fragment module: {FRAGMENT_MODULE} ({error})

Error message

missing bounded fragment module: {FRAGMENT_MODULE} ({error})

What it means

check_fragment_caps(), the static pre-gate that runs before any measurement, reads crates/core/src/fragments.rs and fails closed with FileNotFoundError context when the module is absent. The message embeds the full expected path and the OS error. It protects the bounded-fragment hard caps (issue #5264) from being silently skipped by moving the module.

Source

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

FRAGMENT_MODULE = REPO_ROOT / "crates" / "core" / "src" / "fragments.rs"
FRAGMENT_MAX_TOKENS_CEILING = 10_000
FRAGMENT_MAX_BYTES_CEILING = FRAGMENT_MAX_TOKENS_CEILING * 4
FRAGMENT_DEFAULT_MAX_BYTES_CEILING = 4 * 1024
FRAGMENT_MAX_COUNT_CEILING = 16


def check_fragment_caps() -> None:
    """Gate the bounded fragment hard caps (issue #5264).

    Static check — no cargo needed. Fails closed if the fragment module is
    missing, if any cap has been raised without review, or if the
    project-instruction import is absent.
    """
    try:
        text = FRAGMENT_MODULE.read_text(encoding="utf-8")
    except FileNotFoundError as error:
        raise RuntimeContractError(
            f"missing bounded fragment module: {FRAGMENT_MODULE} ({error})"
        ) from error

    def const_value(pattern: str) -> int:
        match = re.search(pattern, text)
        if not match:
            raise RuntimeContractError(f"fragment cap missing: {pattern}")
        try:
            return int(match.group(1).replace("_", ""))
        except ValueError as error:
            raise RuntimeContractError(f"fragment cap not an int: {pattern}") from error

    max_tokens = const_value(r"pub const MAX_FRAGMENT_TOKENS:\s*usize\s*=\s*([0-9_]+)")
    if max_tokens != FRAGMENT_MAX_TOKENS_CEILING:
        raise RuntimeContractError(
            f"MAX_FRAGMENT_TOKENS must be {FRAGMENT_MAX_TOKENS_CEILING}, got {max_tokens}"
        )
    # MAX_FRAGMENT_BYTES must be defined as MAX_FRAGMENT_TOKENS * 4 (canonical)

View on GitHub (pinned to 8880682c63)

Solutions

Restore crates/core/src/fragments.rs at the exact path (or update FRAGMENT_MODULE in the checker as part of the move, keeping the caps)
Run the checker from a full checkout of this repository; REPO_ROOT is derived from the script location
If the module was intentionally relocated, port the cap regexes to the new file in the same commit so the gate keeps failing closed on missing caps

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path


def fragment_module_present() -> bool:
    return Path("crates/core/src/fragments.rs").is_file()

Prevention

Run the checker from a full checkout; it resolves REPO_ROOT from its own location
If you sparse-checkout in CI, include crates/core/src/fragments.rs and crates/tui/src/model_context/fragment.rs
When relocating the module, update FRAGMENT_MODULE in the same commit so the gate keeps failing closed

When it happens

Trigger: Running the checker from a partial or sparse checkout that lacks crates/core; a refactor renaming or relocating fragments.rs without updating FRAGMENT_MODULE; invoking the script from outside the repository root with a copied-but-incomplete tree.

Common situations: CI sparse-checkout configs that only include scripts/ and crates/tui/; archiving only some crates for a docker layer; branch experiments that split fragments into a submodule.

Related errors

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