Hmbown/CodeWhale · error · RuntimeContractError

MAX_FRAGMENT_BYTES must be {FRAGMENT_MAX_BYTES_CEILING}, got

Error message

MAX_FRAGMENT_BYTES must be {FRAGMENT_MAX_BYTES_CEILING}, got {literal}

What it means

When MAX_FRAGMENT_BYTES is defined as a numeric literal (rather than the canonical MAX_FRAGMENT_TOKENS * 4 form), check_fragment_caps() requires the literal to equal FRAGMENT_MAX_BYTES_CEILING = 40_000. The byte cap is the hard clamp enforced by enforce_byte_cap, so a literal drift here changes runtime truncation behavior without any review.

Source

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

            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(
            "MAX_FRAGMENT_BYTES must be defined as MAX_FRAGMENT_TOKENS * 4 or as 40000"
        )
    # DEFAULT is defined as 4 * 1024 (canonical) or 4096 literal
    has_default_multiplication = re.search(
        r"pub const DEFAULT_FRAGMENT_MAX_BYTES:\s*usize\s*=\s*4\s*\*\s*1024", text
    )
    default_literal = re.search(
        r"pub const DEFAULT_FRAGMENT_MAX_BYTES:\s*usize\s*=\s*([0-9_]+)", text
    )
    if has_default_multiplication:
        # canonical 4*1024 == 4096, which equals ceiling
        pass
    elif default_literal:
        default_bytes = int(default_literal.group(1).replace("_", ""))

View on GitHub (pinned to 8880682c63)

Solutions

Prefer the canonical form: pub const MAX_FRAGMENT_BYTES: usize = MAX_FRAGMENT_TOKENS * 4;
Or restore the exact literal 40_000 (or 40_000 with underscores)
If a raise is intentional, make it an explicit reviewed change that also updates FRAGMENT_MAX_BYTES_CEILING in the checker

Example fix

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

// after - canonical form
pub const MAX_FRAGMENT_BYTES: usize = MAX_FRAGMENT_TOKENS * 4; // 40_000

Defensive patterns

Strategy: validation

Validate before calling

import re
from pathlib import Path

EXPECTED_MAX_FRAGMENT_BYTES = 40_000
CANONICAL = re.compile(
    r"pub const MAX_FRAGMENT_BYTES:\s*usize\s*=\s*MAX_FRAGMENT_TOKENS\s*\*\s*4"
)
LITERAL = re.compile(r"pub const MAX_FRAGMENT_BYTES:\s*usize\s*=\s*([0-9_]+)")


def byte_cap_ok() -> bool:
    text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
    if CANONICAL.search(text):
        return True
    m = LITERAL.search(text)
    return m is not None and int(m.group(1).replace("_", "")) == EXPECTED_MAX_FRAGMENT_BYTES

Prevention

Prefer the canonical MAX_FRAGMENT_TOKENS * 4 form so the byte cap tracks the token cap automatically
If you use a literal, keep it exactly 40_000
Revert debugging raises before committing; run this gate locally to catch leftovers

When it happens

Trigger: Editing pub const MAX_FRAGMENT_BYTES: usize = 40_000; to any other number - for example 80_000 while debugging truncation, or 40_001 by typo. Note that both the literal form and the multiplication form are accepted, but the literal must be exactly 40_000.

Common situations: Debugging a fragment-truncation bug by raising the byte cap locally and committing it; codemods converting the multiplication form to a literal with a wrong value.

Related errors

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