Hmbown/CodeWhale · error · RuntimeContractError

missing bounded fragment module

Error message

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

What it means

check_fragment_caps reads the bounded-fragment Rust module (FRAGMENT_MODULE, the file defining MAX_FRAGMENT_TOKENS/MAX_FRAGMENT_BYTES) to verify caps match the checker's ceilings. If the module file does not exist (FileNotFoundError from read_text), it raises RuntimeContractError naming the missing path. The KV-cache fragment budget cannot be audited without its source of truth.

Solutions

1. Restore or locate the fragment module (e.g. `git checkout -- <path>` or find the renamed file) so FRAGMENT_MODULE resolves.
2. If the module legitimately moved, update the FRAGMENT_MODULE constant in check-runtime-contract-budget.py.
3. Verify you are in a full checkout of the repository, not a sparse/partial one.
4. Check you are on a branch that contains the fragments module (git log on the path).

Example fix

# before
FRAGMENT_MODULE = REPO_ROOT / "crates" / "core" / "src" / "old_fragments.rs"
# after
FRAGMENT_MODULE = REPO_ROOT / "crates" / "core" / "src" / "bounded_fragments.rs"

from pathlib import Path
mod = Path("crates/core/src/bounded_fragments.rs")
if not mod.exists():
    raise SystemExit(f"fragment module missing: {mod}; restore or update FRAGMENT_MODULE")

def fragment_module_available(path) -> bool:
    from pathlib import Path
    return Path(path).is_file()

try:
    check_fragment_caps()
except FileNotFoundError as e:
    print(f"fragment module missing ({e}); is this a full checkout?", file=sys.stderr)
    sys.exit(1)

When it happens

Trigger: Running the checker when the Rust source file at FRAGMENT_MODULE has been moved, renamed, deleted, or the repo is a partial/sparse checkout missing crates/core's fragment module.

Common situations: A refactor renamed the fragments module without updating FRAGMENT_MODULE in the checker; working from an archive or sparse checkout that excluded the crate; checking out an old tag before the module existed.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• missing TUI fragment module
• agent profile provider cannot be empty
• agent profile provider must be a simple provider id
• Antigravity cloud-code request is missing a model id
• app-server auth token cannot be empty

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

Appendix: source

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

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 433685b202)