Hmbown/CodeWhale · error · RuntimeContractError

TUI fragment module must include ProjectInstructions variant

Error message

TUI fragment module must include ProjectInstructions variant (unified with core)

What it means

The TUI fragment module must reference 'ProjectInstructions' so the TUI's fragment set stays unified with core's injection types (the typed project-instruction import from #3978). A substring check over crates/tui/src/model_context/fragment.rs; dropping the variant from re-exports or a TUI-side enum fails.

Source

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

    if "MAX_FRAGMENT_BYTES" not in text or "enforce_byte_cap" not in text:
        raise RuntimeContractError(
            "bounded fragment module must enforce byte caps via enforce_byte_cap and MAX_FRAGMENT_BYTES"
        )

    # TUI must be unified with the core boundary (shared crates/core module)
    tui_fragment = REPO_ROOT / "crates" / "tui" / "src" / "model_context" / "fragment.rs"
    try:
        tui_text = tui_fragment.read_text(encoding="utf-8")
    except FileNotFoundError as error:
        raise RuntimeContractError(
            f"missing TUI fragment module: {tui_fragment} ({error})"
        ) from error
    if "codewhale_core::fragments" not in tui_text:
        raise RuntimeContractError(
            "TUI model_context/fragment.rs must re-export caps from codewhale_core::fragments (shared crates/core boundary)"
        )
    if "ProjectInstructions" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must include ProjectInstructions variant (unified with core)"
        )
    if "MAX_FRAGMENT_BYTES" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must enforce MAX_FRAGMENT_BYTES (10K-token ceiling)"
        )
    if "matches_text" not in tui_text:
        raise RuntimeContractError(
            "TUI fragment module must expose a matches_text recognizer"
        )


def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--receipt",
        type=Path,
        help="check an existing measurement JSON instead of compiling",

View on GitHub (pinned to 8880682c63)

Solutions

Keep ProjectInstructions in the re-export or enum used by crates/tui/src/model_context/fragment.rs
If the TUI enum is generated, ensure the generator emits all core variants
Verify: 'grep -n ProjectInstructions crates/tui/src/model_context/fragment.rs'

Example fix

// before (crates/tui/src/model_context/fragment.rs)
pub use codewhale_core::fragments::FragmentId::{Workspace, Permissions, Route};

// after
pub use codewhale_core::fragments::FragmentId::{Workspace, Permissions, Route, ProjectInstructions};

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
tui = Path("crates/tui/src/model_context/fragment.rs").read_text(encoding="utf-8")
assert "ProjectInstructions" in tui, "TUI fragment set lost ProjectInstructions"

Type guard

def is_runtime_contract_error(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and type(exc).__name__ == "RuntimeContractError"

Try / catch

try:
    check_fragment_caps()
except RuntimeContractError as error:
    print(f"[gate] {error}", file=sys.stderr)
    raise SystemExit(2)

Prevention

Use glob re-exports ('pub use codewhale_core::fragments::*') or keep explicit lists in sync with core variants
When core adds a FragmentId variant, mirror it into the TUI surface in the same commit
Grep ProjectInstructions in the TUI module after enum refactors

When it happens

Trigger: Removing ProjectInstructions from a 'pub use codewhale_core::fragments::...' list; deleting a TUI-local enum member; feature-gating the variant so the literal disappears from the file.

Common situations: Trimming re-export lists that look unused; splitting the TUI-side enum during a refactor.

Related errors

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