Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module must expose…

Error message

bounded fragment module must expose load_project_instruction_fragment (project-instruction import as typed fragment)

What it means

The contract requires that project instructions (e.g. .cursorrules, copilot-instructions.md) are imported through a typed fragment — a dedicated function named load_project_instruction_fragment in the bounded fragment module — rather than injected as ad-hoc text bypassing the byte/count caps. If the function name is absent from fragments.rs, the gate fails because the import path would evade the fragment budget and the audit trail.

Solutions

1. Restore (or re-add) `fn load_project_instruction_fragment` in crates/core/src/fragments.rs and route project-instruction imports through it
2. If the function moved to another module, note the checker only scans fragments.rs — keep an exported definition (or the exact identifier) in that file, or update the script as a reviewed contract change
3. Also verify PROJECT_INSTRUCTION_CANDIDATES is still defined, as the next gate checks it

Example fix

// before (ad-hoc import in config layer)
config.push(format!("<!-- cw:ctx:project_instructions -->\n{}", raw));
// after (crates/core/src/fragments.rs)
fn load_project_instruction_fragment() -> Fragment { ... } // typed, capped

src = open('crates/core/src/fragments.rs').read()
if 'load_project_instruction_fragment' not in src:
    raise SystemExit('typed project-instruction fragment loader missing')

When it happens

Trigger: Running scripts/check-runtime-contract-budget.py after removing load_project_instruction_fragment from fragments.rs, renaming it, or replacing the typed-fragment import path with an untyped string injection elsewhere in the module.

Common situations: Refactoring project-instruction loading into a config layer without the typed fragment wrapper; renaming the function during cleanup; reverting part of the fragment module from an older branch that predates the typed import.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• DEFAULT_FRAGMENT_MAX_BYTES
• DEFAULT_FRAGMENT_MAX_BYTES definition not found
• DEFAULT_FRAGMENT_MAX_BYTES must be
• FragmentId missing required variant
• MAX_FRAGMENT_BYTES must be defined as MAX_FRAGMENT_TOKENS *…

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

Appendix: source

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

            if not re.search(rf"\b{name}\b", text):
                raise RuntimeContractError(
                    f"FragmentId missing required variant {name}"
                )
    # Marker stability — these strings are pinned by tests / prefix cache
    required_markers = [
        "<!-- cw:ctx:workspace -->",
        "<!-- cw:ctx:project_instructions -->",
        "<!-- cw:ctx:constitution -->",
    ]
    for marker in required_markers:
        if marker not in text:
            raise RuntimeContractError(
                f"bounded fragment module missing required marker {marker!r}"
            )

    # Project-instruction import must be a typed fragment, not ad-hoc
    if "load_project_instruction_fragment" not in text:
        raise RuntimeContractError(
            "bounded fragment module must expose load_project_instruction_fragment (project-instruction import as typed fragment)"
        )
    if "PROJECT_INSTRUCTION_CANDIDATES" not in text:
        raise RuntimeContractError(
            "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}"

View on GitHub (pinned to 433685b202)