Hmbown/CodeWhale · error · RuntimeContractError

MAX_FRAGMENTS_PER_CONTEXT

Error message

MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRAGMENT_MAX_COUNT_CEILING}

What it means

A belt-and-braces companion to the equality check: even if the equality gate above were relaxed, the count must never exceed 16. Since the checker currently requires exact equality with FRAGMENT_MAX_COUNT_CEILING, this branch is defense-in-depth for future ceiling changes, keeping the monotonic 'never exceed' contract explicit in the script.

Solutions

Lower MAX_FRAGMENTS_PER_CONTEXT in crates/core/src/fragments.rs to match the new ceiling
Or keep both at the current pinned value 16
Update both the script ceiling and the constant together in one reviewed change

Example fix

// script: FRAGMENT_MAX_COUNT_CEILING = 12, fragments.rs still 16
// before (crates/core/src/fragments.rs)
pub const MAX_FRAGMENTS_PER_CONTEXT: usize = 16;
// after
pub const MAX_FRAGMENTS_PER_CONTEXT: usize = 12;

Defensive patterns

Strategy: validation

Validate before calling

import re
CEILING = 16
src = open('crates/core/src/fragments.rs').read()
m = re.search(r'pub const MAX_FRAGMENTS_PER_CONTEXT:\s*usize\s*=\s*([0-9_]+)', src)
if m and int(m.group(1).replace('_','')) > CEILING:
    raise SystemExit('MAX_FRAGMENTS_PER_CONTEXT exceeds ceiling')

Prevention

Update the script ceiling and the constant in the same commit
Never raise the fragment count silently; it is a prompt-budget contract
Review the ceiling value whenever fragment types are added

When it happens

Trigger: Running the check when the parsed MAX_FRAGMENTS_PER_CONTEXT value is strictly greater than FRAGMENT_MAX_COUNT_CEILING — only reachable if the equality gate is loosened or the ceiling constant is lowered below the current literal.

Common situations: Lowering FRAGMENT_MAX_COUNT_CEILING in a budget-tightening change while fragments.rs still carries the old higher literal.

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

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

Appendix: source

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

            raise RuntimeContractError(
                f"DEFAULT_FRAGMENT_MAX_BYTES must be {FRAGMENT_DEFAULT_MAX_BYTES_CEILING}, got {default_bytes}"
            )
        if default_bytes > FRAGMENT_MAX_BYTES_CEILING:
            raise RuntimeContractError(
                f"DEFAULT_FRAGMENT_MAX_BYTES ({default_bytes}) must not exceed MAX_FRAGMENT_BYTES ({FRAGMENT_MAX_BYTES_CEILING})"
            )
    else:
        raise RuntimeContractError("DEFAULT_FRAGMENT_MAX_BYTES definition not found")

    max_count = const_value(
        r"pub const MAX_FRAGMENTS_PER_CONTEXT:\s*usize\s*=\s*([0-9_]+)"
    )
    if max_count != FRAGMENT_MAX_COUNT_CEILING:
        raise RuntimeContractError(
            f"MAX_FRAGMENTS_PER_CONTEXT must be {FRAGMENT_MAX_COUNT_CEILING}, got {max_count}"
        )
    if max_count > FRAGMENT_MAX_COUNT_CEILING:
        raise RuntimeContractError(
            f"MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRAGMENT_MAX_COUNT_CEILING}"
        )

    # Ensure every injection type is in FragmentId::all() and the
    # project-instruction import is present as a typed fragment.
    required_fragments = [
        "Workspace",
        "Permissions",
        "Route",
        "AgentTopology",
        "SkillsTools",
        "TokenBudget",
        "ProjectInstructions",
        "Constitution",
    ]
    for name in required_fragments:
        if f"Self::{name}" not in text and f"{name} =>" not in text and f'"{name.lower()}"' not in text.lower():
            # Fallback: search for enum variant declaration

View on GitHub (pinned to 433685b202)