{"record":{"id":"60ca1e983be1dacb","repo":"Hmbown/CodeWhale","slug":"bounded-fragment-module-must-define-a-matches-text","errorCode":null,"errorMessage":"bounded fragment module must define a matches_text recognizer on the fragment trait","messagePattern":"bounded fragment module must define a matches_text recognizer on the fragment trait","errorType":"exception","errorClass":"RuntimeContractError","httpStatus":null,"severity":"error","filePath":"scripts/check-runtime-contract-budget.py","lineNumber":579,"sourceCode":"            \"bounded fragment module must define PROJECT_INSTRUCTION_CANDIDATES\"\n        )\n    # Required candidate files from #3978\n    required_candidates = [\n        \".cursorrules\",\n        \".clinerules\",\n        \".windsurf/rules\",\n        \".gemini\",\n        \".github/copilot-instructions.md\",\n    ]\n    for candidate in required_candidates:\n        if candidate not in text:\n            raise RuntimeContractError(\n                f\"PROJECT_INSTRUCTION_CANDIDATES missing required entry {candidate!r}\"\n            )\n\n    # matches_text recognizer must exist on the fragment trait\n    if \"fn matches_text\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must define a matches_text recognizer on the fragment trait\"\n        )\n    if \"trait ContextFragment\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must define trait ContextFragment with matches_text\"\n        )\n\n    # No unbounded fragment — enforce that creation clamps to MAX_FRAGMENT_BYTES\n    if \"MAX_FRAGMENT_BYTES\" not in text or \"enforce_byte_cap\" not in text:\n        raise RuntimeContractError(\n            \"bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES\"\n        )\n\n    # TUI must be unified with the core boundary (shared crates/core module)\n    tui_fragment = REPO_ROOT / \"crates\" / \"tui\" / \"src\" / \"model_context\" / \"fragment.rs\"\n    try:\n        tui_text = tui_fragment.read_text(encoding=\"utf-8\")\n    except FileNotFoundError as error:","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/scripts/check-runtime-contract-budget.py#L561-L597","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Define `fn matches_text` in crates/core/src/fragments.rs (on the ContextFragment trait or its impls) so the literal appears in the module.","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.","Restore the original name matches_text if a rename broke the check; the name is part of the frozen contract."],"exampleFix":"// before (fragments.rs)\npub trait ContextFragment { fn applies(&self, text: &str) -> bool; }\n\n// after\npub trait ContextFragment {\n    fn matches_text(&self, text: &str) -> bool;\n}","handlingStrategy":"validation","validationCode":"text = open('crates/core/src/fragments.rs').read()\nassert 'fn matches_text' in text, 'fragments.rs must define fn matches_text'","typeGuard":"def has_matches_text(module_text: str) -> bool:\n    return 'fn matches_text' in module_text","tryCatchPattern":"try:\n    check_fragment_caps()\nexcept RuntimeContractError as e:\n    if 'matches_text recognizer' in str(e):\n        restore_matches_text_in_fragments_rs()","preventionTips":["Do not rename trait methods in fragments.rs without grepping scripts/check-runtime-contract-budget.py for literal name checks.","Keep the recognizer implementation in fragments.rs itself, not only in downstream crates.","Run the script locally before pushing any fragments-related refactor."],"tags":["rust","static-analysis","contract-check","fragments"],"backgroundTag":"method-not-implemented","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}