Hmbown/CodeWhale · error · RuntimeContractError

missing TUI fragment module

Error message

missing TUI fragment module: {tui_fragment} ({error})

What it means

check_fragment_caps unifies the TUI with the shared core fragment boundary by reading crates/tui/src/model_context/fragment.rs. If that file does not exist, the FileNotFoundError is converted to this RuntimeContractError naming the missing path. The check fails closed because a missing TUI module means the shared-boundary contract cannot be verified.

Solutions

1. Recreate crates/tui/src/model_context/fragment.rs (restore from git history: `git log --diff-filter=D -- crates/tui/src/model_context/fragment.rs`).
2. If the module was intentionally moved, update this script's tui_fragment path in scripts/check-runtime-contract-budget.py as part of the documented migration.
3. Verify the TUI crate's module tree declares the file (mod fragment; in model_context/mod.rs) so it compiles and exists on disk.

Example fix

// before (model_context/mod.rs)
mod session; // fragment.rs deleted

// after
mod fragment;
mod session;

from pathlib import Path
assert Path('crates/tui/src/model_context/fragment.rs').exists(), 'TUI fragment module missing'

def tui_fragment_module_exists() -> bool:
    from pathlib import Path
    return Path('crates/tui/src/model_context/fragment.rs').is_file()

try:
    text = Path('crates/tui/src/model_context/fragment.rs').read_text()
except FileNotFoundError:
    restore_tui_fragment_module_from_git()

When it happens

Trigger: Running the contract check when crates/tui/src/model_context/fragment.rs is absent — the module was deleted, renamed (e.g. fragments.rs), moved out of model_context/, or a fresh branch predates the unification.

Common situations: A refactor moves the TUI fragment module to another directory; a stale worktree/branch from before the core-unification work; a bulk rename of model_context/ modules; contributor branch created before the module landed.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• missing bounded fragment module
• TUI fragment module must enforce MAX_FRAGMENT_BYTES…
• TUI fragment module must include ProjectInstructions…
• TUI model_context/fragment.rs must re-export caps from…
• bounded fragment module must define a matches_text…

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

Appendix: source

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

            "bounded fragment module must define a matches_text recognizer on the fragment trait"
        )
    if "trait ContextFragment" not in text:
        raise RuntimeContractError(
            "bounded fragment module must define trait ContextFragment with matches_text"
        )

    # No unbounded fragment — enforce that creation clamps to MAX_FRAGMENT_BYTES
    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"
        )

View on GitHub (pinned to 433685b202)