Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define trait ContextFragment…

Error message

bounded fragment module must define trait ContextFragment with matches_text

What it means

check_fragment_caps requires crates/core/src/fragments.rs to declare `trait ContextFragment` (with matches_text), making fragments a typed trait rather than ad-hoc strings. If the literal 'trait ContextFragment' is missing from the module text the check raises this error. This pins the fragment abstraction to its canonical trait name in the shared core crate.

Solutions

1. Declare `pub trait ContextFragment` in crates/core/src/fragments.rs, including a `fn matches_text` method.
2. If the trait was renamed, revert the rename or re-introduce `trait ContextFragment` as the canonical name in fragments.rs.
3. Keep both the trait and its matches_text method in the same file — the checker greps fragments.rs only.

Example fix

// before (fragments.rs — trait living in another module)
pub use crate::context::Fragment as ContextFragment;

// after
pub trait ContextFragment {
    fn matches_text(&self, text: &str) -> bool;
}

text = open('crates/core/src/fragments.rs').read()
assert 'trait ContextFragment' in text, 'fragments.rs must declare trait ContextFragment'

def has_context_fragment_trait(module_text: str) -> bool:
    return 'trait ContextFragment' in module_text

try:
    check_fragment_caps()
except RuntimeContractError as e:
    if 'trait ContextFragment' in str(e):
        declare_context_fragment_trait_in_fragments_rs()

When it happens

Trigger: Running the contract check when fragments.rs contains matches_text but no `trait ContextFragment` declaration — the trait was renamed (e.g. to Fragment), moved to another module, or the file only has impls for a trait defined elsewhere.

Common situations: A trait rename during refactor; trait hoisted into a new fragments/ directory module leaving fragments.rs without the declaration; a generated or templated module scaffold missing the trait; git revert dropping the trait block.

Related errors

• bounded fragment module must define a matches_text…
• bounded fragment module must define…
• bounded fragment module must enforce byte caps via…
• PROJECT_INSTRUCTION_CANDIDATES missing required entry
• TUI fragment module must include ProjectInstructions…

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

Appendix: source

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

        ".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 433685b202)