Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define a matches_text…

Error message

bounded fragment module must define a matches_text recognizer on the fragment trait

What it means

The contract requires that fragment content recognition lives in a `fn matches_text` inside crates/core/src/fragments.rs, so fragments decide applicability by inspecting text. If the literal 'fn matches_text' is absent from the module text, check_fragment_caps raises this error. It prevents fragment traits from being implemented without a text recognizer (issue #5264 bounded-fragment contract).

Solutions

1. Define `fn matches_text` in crates/core/src/fragments.rs (on the ContextFragment trait or its impls) so the literal appears in the module.
2. If the recognizer moved, move it back or keep a definition/re-export in fragments.rs — the check requires the fn text in that exact file.
3. Restore the original name matches_text if a rename broke the check; the name is part of the frozen contract.

Example fix

// before (fragments.rs)
pub trait ContextFragment { fn applies(&self, text: &str) -> bool; }

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

text = open('crates/core/src/fragments.rs').read()
assert 'fn matches_text' in text, 'fragments.rs must define fn matches_text'

def has_matches_text(module_text: str) -> bool:
    return 'fn matches_text' in module_text

try:
    check_fragment_caps()
except RuntimeContractError as e:
    if 'matches_text recognizer' in str(e):
        restore_matches_text_in_fragments_rs()

When it happens

Trigger: Running the contract check when crates/core/src/fragments.rs has no function defined with the exact signature text 'fn matches_text' (renamed to matches, made a closure, moved to another crate, or implemented only as a trait default elsewhere).

Common situations: A refactor renames matches_text to something shorter; the recognizer is moved to a sibling module like context_budget.rs; the trait is declared but its method is implemented only in the TUI crate, leaving fragments.rs without the fn.

Related errors

• bounded fragment module must define…
• bounded fragment module must define trait ContextFragment…
• 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/60ca1e983be1dacb. Report an issue: GitHub.

Appendix: source

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

            "bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES"
        )
    # Required candidate files from #3978
    required_candidates = [
        ".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:

View on GitHub (pinned to 433685b202)