What causes "FragmentId missing required variant {name}" in Hmbown/CodeWhale?

Hmbown/CodeWhale · error · RuntimeContractError

FragmentId missing required variant

Error message

FragmentId missing required variant {name}

What it means

The FragmentId enum in crates/core/src/fragments.rs must include every required injection type (Workspace, Permissions, Route, AgentTopology, SkillsTools, TokenBudget, ProjectInstructions, Constitution). The checker looks for the variant in several textual forms (Self::<Name>, a match arm `<Name> =>`, a quoted lowercase tag, or a bare word) and fails if none appear — meaning a required fragment type was removed or renamed from the enum.

Solutions

Re-add the missing variant to the FragmentId enum in crates/core/src/fragments.rs with the exact required name
If a variant was renamed, keep the required name in a match arm (`Name =>`) or lowercase string tag for contract continuity, or update required_fragments in the script as a reviewed contract change
Run `grep -n '<Name>' crates/core/src/fragments.rs` to confirm which textual form the checker needs

Example fix

// before (variant renamed)
enum FragmentId { Workspace, ..., ProjectDocs }
// after
enum FragmentId { Workspace, ..., ProjectInstructions }

Defensive patterns

Strategy: validation

Validate before calling

import re
REQUIRED = ["Workspace","Permissions","Route","AgentTopology","SkillsTools","TokenBudget","ProjectInstructions","Constitution"]
src = open('crates/core/src/fragments.rs').read()
for name in REQUIRED:
    if not re.search(rf'\b{name}\b', src):
        raise SystemExit(f'FragmentId missing required variant {name}')

Prevention

Keep all eight required variants in FragmentId; treat renames as contract changes
Update required_fragments in the script alongside any deliberate variant rename
Run the contract check whenever the enum is edited

When it happens

Trigger: Running scripts/check-runtime-contract-budget.py after deleting or renaming one of the eight required FragmentId variants in fragments.rs, or after a refactor that renames a variant (e.g. ProjectInstructions -> ProjectDocs) without a match-arm or string tag preserving the old name.

Common situations: Renaming variants during a fragment-module refactor; removing a fragment type believed unused; syncing fragments.rs from another fork where a variant was dropped.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

        )

    # Ensure every injection type is in FragmentId::all() and the
    # project-instruction import is present as a typed fragment.
    required_fragments = [
        "Workspace",
        "Permissions",
        "Route",
        "AgentTopology",
        "SkillsTools",
        "TokenBudget",
        "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)"

View on GitHub (pinned to 433685b202)