Hmbown/CodeWhale · error · RuntimeContractError

MAX_FRAGMENT_TOKENS must be

Error message

MAX_FRAGMENT_TOKENS must be {FRAGMENT_MAX_TOKENS_CEILING}, got {max_tokens}

What it means

check_fragment_caps enforces one-way ceilings on the bounded-fragment constants: MAX_FRAGMENT_TOKENS must equal FRAGMENT_MAX_TOKENS_CEILING (10_000). If the module's parsed value differs, RuntimeContractError reports the expected ceiling and the actual value. This prevents silently raising the KV-cache fragment budget without an explicit, reviewed change to both the Rust source and the checker ceiling.

Solutions

1. Set `pub const MAX_FRAGMENT_TOKENS: usize = 10_000;` in the fragment module to match the ceiling.
2. If the raise is intentional and reviewed, update FRAGMENT_MAX_TOKENS_CEILING in check-runtime-contract-budget.py and the MAX_FRAGMENT_BYTES derivation (tokens * 4) in the same change.
3. Check git history of the fragment module to find which change moved the cap and confirm it was approved.
4. Re-run the checker to confirm all remaining caps (MAX_FRAGMENT_BYTES) also match.

Example fix

// before
pub const MAX_FRAGMENT_TOKENS: usize = 12_000;
// after
pub const MAX_FRAGMENT_TOKENS: usize = 10_000;

import re
text = open("crates/core/src/bounded_fragments.rs").read()
v = int(re.search(r"pub const MAX_FRAGMENT_TOKENS:\\s*usize\\s*=\\s*([0-9_]+)", text).group(1).replace("_", ""))
assert v == 10_000, f"MAX_FRAGMENT_TOKENS drifted to {v}; ceiling is 10_000"

def within_ceiling(tokens: int, ceiling: int = 10_000) -> bool:
    return tokens == ceiling

try:
    enforce_fragment_ceilings(text)
except BudgetCeilingViolation as e:
    print(f"{e}; revert or update the ceiling with review", file=sys.stderr)
    sys.exit(1)

When it happens

Trigger: Running the checker after MAX_FRAGMENT_TOKENS in the fragment module was changed to any value other than 10_000 — an intentional budget increase, a merge that took a different branch's value, or a typo while editing the constant.

Common situations: Someone raised the token cap to fit a larger prompt without updating the ceiling; a branch merge picked up a divergent cap; a bad cherry-pick altered the constant.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• baseline_observation.
• budget metric `representative_context.fixture_id` must be
• identity changed for
• baseline_observation.accepted_requests must equal…
• bounded fragment module must define a matches_text…

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

Appendix: source

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

    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)
    # or as a literal 40000. Either way the derived ceiling is 40_000.
    has_multiplication = re.search(
        r"pub const MAX_FRAGMENT_BYTES:\s*usize\s*=\s*MAX_FRAGMENT_TOKENS\s*\*\s*4", text
    )
    bytes_literal = re.search(
        r"pub const MAX_FRAGMENT_BYTES:\s*usize\s*=\s*([0-9_]+)", text
    )
    if bytes_literal:
        literal = int(bytes_literal.group(1).replace("_", ""))
        if literal != FRAGMENT_MAX_BYTES_CEILING:
            raise RuntimeContractError(
                f"MAX_FRAGMENT_BYTES must be {FRAGMENT_MAX_BYTES_CEILING}, got {literal}"
            )
    elif not has_multiplication:
        raise RuntimeContractError(

View on GitHub (pinned to 433685b202)