Hmbown/CodeWhale · error · RuntimeContractError

bounded fragment module missing required marker

Error message

bounded fragment module missing required marker {marker!r}

What it means

The fragment module must contain three exact HTML-comment markers (`<!-- cw:ctx:workspace -->`, `<!-- cw:ctx:project_instructions -->`, `<!-- cw:ctx:constitution -->`). These markers are pinned by tests and the prompt prefix cache (KV-cache stability), so they must not change shape. A missing marker means the fragment renderer no longer emits the pinned string, which would invalidate cached prefixes or break tests.

Solutions

1. Restore the exact marker string in crates/core/src/fragments.rs (copy the literal from required_markers in scripts/check-runtime-contract-budget.py)
2. If markers must change, it is a deliberate cache-breaking migration: update tests, the prefix cache contract, and required_markers together with review
3. Check for whitespace differences — the comparison is exact substring, so `<!--cw:ctx:workspace-->` without spaces fails

Example fix

// before
const WORKSPACE_MARKER: &str = "<!--cw:ctx:workspace-->"; // spaces removed
// after
const WORKSPACE_MARKER: &str = "<!-- cw:ctx:workspace -->";

MARKERS = ["<!-- cw:ctx:workspace -->", "<!-- cw:ctx:project_instructions -->", "<!-- cw:ctx:constitution -->"]
src = open('crates/core/src/fragments.rs').read()
missing = [m for m in MARKERS if m not in src]
if missing:
    raise SystemExit(f'missing pinned markers: {missing}')

When it happens

Trigger: Running scripts/check-runtime-contract-budget.py when any of the three `cw:ctx:` marker strings is absent from fragments.rs — e.g. after changing marker formatting, renaming a marker, or removing the code path that defines it.

Common situations: Rebranding or reformatting context markers; 'cleaning up' comments that are actually load-bearing contract strings; a merge that dropped one marker's definition.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• bounded fragment module must expose…
• catalog cache unavailable
• DEFAULT_FRAGMENT_MAX_BYTES
• DEFAULT_FRAGMENT_MAX_BYTES definition not found
• DEFAULT_FRAGMENT_MAX_BYTES must be

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

Appendix: source

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

        "ProjectInstructions",
        "Constitution",
    ]
    for name in required_fragments:
        if f"Self::{name}" not in text and f"{name} =>" not in text and f'"{name.lower()}"' not in text.lower():
            # Fallback: search for enum variant declaration
            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",

View on GitHub (pinned to 433685b202)