Hmbown/CodeWhale · error · RuntimeContractError

FragmentId missing required variant {name}

Error message

FragmentId missing required variant {name}

What it means

The gate verifies the FragmentId enum in crates/core/src/fragments.rs keeps all eight injection-type variants (Workspace, Permissions, Route, AgentTopology, SkillsTools, TokenBudget, ProjectInstructions, Constitution). It probes for 'Self::Name', 'Name =>', or the lowercased name, then falls back to a word-boundary regex over the whole file - so it only fires when the variant name appears nowhere at all, i.e. it was renamed or removed.

Source

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

        )

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

Solutions

1. Restore the missing variant (named in the error) in the FragmentId enum in crates/core/src/fragments.rs
2. If a rename is intentional, either keep the required enum name and map display labels separately, or update required_fragments in scripts/check-runtime-contract-budget.py:518-527 in the same reviewed commit
3. Confirm absence first: 'grep -n Constitution crates/core/src/fragments.rs'

Example fix

// before (crates/core/src/fragments.rs)
pub enum FragmentId {
    Workspace,
    Permissions,
    // Constitution removed during merge with Workspace
}

// after
pub enum FragmentId {
    Workspace,
    Permissions,
    Constitution,
}

from pathlib import Path
text = Path("crates/core/src/fragments.rs").read_text(encoding="utf-8")
required = ["Workspace", "Permissions", "Route", "AgentTopology", "SkillsTools", "TokenBudget", "ProjectInstructions", "Constitution"]
missing = [name for name in required if name not in text]
assert not missing, f"FragmentId variants missing: {missing}"

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 a variant everywhere in fragments.rs (Constitution -> Charter); deleting a variant when merging injection types; moving FragmentId out of fragments.rs so the names no longer occur in the file the gate reads.

Common situations: Terminology refactors ('Constitution' -> 'Principles'); collapsing Workspace+Route into one fragment; extracting FragmentId into a submodule during a model_context reorganization.

Related errors

• TUI fragment module must include ProjectInstructions variant
• 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
• MAX_FRAGMENTS_PER_CONTEXT ({max_count}) must not exceed {FRA

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