Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define trait ContextFragment wi

Error message

bounded fragment module must define trait ContextFragment with matches_text

What it means

The gate requires the literal text 'trait ContextFragment' in crates/core/src/fragments.rs - the shared trait all bounded context fragments implement. It fails when the trait is renamed, or when fragments.rs is split so the trait definition lives in a submodule the gate (which reads only fragments.rs) cannot see.

Source

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

        ".cursorrules",
        ".clinerules",
        ".windsurf/rules",
        ".gemini",
        ".github/copilot-instructions.md",
    ]
    for candidate in required_candidates:
        if candidate not in text:
            raise RuntimeContractError(
                f"PROJECT_INSTRUCTION_CANDIDATES missing required entry {candidate!r}"
            )

    # matches_text recognizer must exist on the fragment trait
    if "fn matches_text" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define a matches_text recognizer on the fragment trait"
        )
    if "trait ContextFragment" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define trait ContextFragment with matches_text"
        )

    # No unbounded fragment — enforce that creation clamps to MAX_FRAGMENT_BYTES
    if "MAX_FRAGMENT_BYTES" not in text or "enforce_byte_cap" not in text:
        raise RuntimeContractError(
            "bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES"
        )

    # TUI must be unified with the core boundary (shared crates/core module)
    tui_fragment = REPO_ROOT / "crates" / "tui" / "src" / "model_context" / "fragment.rs"
    try:
        tui_text = tui_fragment.read_text(encoding="utf-8")
    except FileNotFoundError as error:
        raise RuntimeContractError(
            f"missing TUI fragment module: {tui_fragment} ({error})"
        ) from error
    if "codewhale_core::fragments" not in tui_text:

View on GitHub (pinned to 8880682c63)

Solutions

1. Keep 'pub trait ContextFragment' declared inside crates/core/src/fragments.rs
2. If splitting the module, update FRAGMENT_MODULE in scripts/check-runtime-contract-budget.py:428 to point at the file that now holds the trait, in the same commit
3. Verify: 'grep -n "trait ContextFragment" crates/core/src/fragments.rs'

Example fix

# before: trait moved to crates/core/src/fragment_trait.rs, fragments.rs only re-exports
# (gate still reads fragments.rs -> fails)
pub use crate::fragment_trait::ContextFragment;

# after: keep the trait definition in fragments.rs (or update FRAGMENT_MODULE)
pub trait ContextFragment { /* ... */ }

from pathlib import Path
text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
assert "trait ContextFragment" in text, "ContextFragment trait not declared in fragments.rs"

def is_runtime_contract_error(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and type(exc).__name__ == "RuntimeContractError"

try:
    check_fragment_caps()
except RuntimeContractError as error:
    print(f"[gate] {error}", file=sys.stderr)
    raise SystemExit(2)

When it happens

Trigger: Renaming ContextFragment to Fragment/ContextSection; converting fragments.rs into a fragments/ directory with the trait in a sub-file while the gate still reads the old single file.

Common situations: Module-growth refactors splitting the 600+ line fragments.rs; trait renames during API cleanup.

Related errors

• bounded fragment module must define a matches_text recognize
• DEFAULT_FRAGMENT_MAX_BYTES ({default_bytes}) must not exceed
• DEFAULT_FRAGMENT_MAX_BYTES definition not found
• MAX_FRAGMENTS_PER_CONTEXT must be {FRAGMENT_MAX_COUNT_CEILIN
• MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRA

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