Hmbown/CodeWhale · error · RuntimeContractError

MAX_FRAGMENT_TOKENS must be {FRAGMENT_MAX_TOKENS_CEILING}, g

Error message

MAX_FRAGMENT_TOKENS must be {FRAGMENT_MAX_TOKENS_CEILING}, got {max_tokens}

What it means

check_fragment_caps() parses MAX_FRAGMENT_TOKENS out of crates/core/src/fragments.rs and requires it to equal FRAGMENT_MAX_TOKENS_CEILING = 10_000 exactly. Raising (or lowering) the token ceiling is a reviewed maintainer decision, so the gate fails closed on any unilateral change; the message reports both the expected and actual values.

Source

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

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

Solutions

Restore pub const MAX_FRAGMENT_TOKENS: usize = 10_000; in crates/core/src/fragments.rs
If a raise is genuinely needed, open it as an explicit decision: change the cap and FRAGMENT_MAX_TOKENS_CEILING together with review, and note the rationale (mirroring the budget _comment convention)
Shrink the oversized fragment (chunking/truncation via enforce_byte_cap) instead of raising the ceiling

Example fix

// before (crates/core/src/fragments.rs)
pub const MAX_FRAGMENT_TOKENS: usize = 20_000;

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

Defensive patterns

Strategy: validation

Validate before calling

import re
from pathlib import Path

EXPECTED_MAX_FRAGMENT_TOKENS = 10_000


def token_cap_ok() -> bool:
    text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
    m = re.search(r"pub const MAX_FRAGMENT_TOKENS:\s*usize\s*=\s*([0-9_]+)", text)
    if m is None:
        return False
    return int(m.group(1).replace("_", "")) == EXPECTED_MAX_FRAGMENT_TOKENS

Prevention

Do not raise the token cap to fit content - shrink or chunk the fragment instead
Cap changes are maintainer decisions: pair any change with the checker's ceiling constant and a written rationale
Watch rebases that reintroduce a temporary local raise of 10_000

When it happens

Trigger: A PR edits pub const MAX_FRAGMENT_TOKENS: usize to anything other than 10_000 - for example 20_000 to accommodate larger fragments. Downstream, MAX_FRAGMENT_BYTES (defined as MAX_FRAGMENT_TOKENS * 4) would silently double, which is precisely what this gate prevents.

Common situations: Developers bumping the cap to make a large context fragment fit during local testing and committing it accidentally; rebasing over a branch that carried a temporary raise.

Related errors

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