Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must define a matches_text recognize

Error message

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

What it means

The ContextFragment trait must declare a 'fn matches_text' recognizer (matching incoming text back to a fragment id). The gate substring-checks 'fn matches_text' in crates/core/src/fragments.rs; renaming the method, moving it off the trait, or deleting it fails this check.

Source

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

            "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 8880682c63)

Solutions

1. Keep 'fn matches_text(&self, haystack: &str) -> bool;' declared on 'pub trait ContextFragment' in crates/core/src/fragments.rs
2. If the method must be renamed, update the gate string at scripts/check-runtime-contract-budget.py:571 in the same reviewed commit - but prefer keeping the name (searchability contract)
3. Verify: 'grep -n "fn matches_text" crates/core/src/fragments.rs'

Example fix

// before (crates/core/src/fragments.rs)
pub trait ContextFragment {
    fn recognizes(&self, haystack: &str) -> bool;
}

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

from pathlib import Path
text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
assert "fn matches_text" in text, "matches_text recognizer missing from trait"

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 matches_text to recognizes/contains_text; moving the method to an impl block or free function; deleting the recognizer after its last caller moved.

Common situations: Trait refactors; consolidating recognition logic into a helper during cleanup.

Related errors

• bounded fragment module must expose load_project_instruction
• bounded fragment module must define trait ContextFragment wi
• 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

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