512 2026 01 27 00 10 38 Issue 311 Core Types Layer Violation 11872dd0

Research - Issue #311: core → types Layer Violation

Date: 2026-01-27 Owner: claude-agent Phase: Research Issue: https://github.com/alchemiststudiosDOTai/tunacode/issues/311

Goal

Understand the scope and implications of the core → types layer violation reported in issue #311, and determine the correct remediation approach.

Findings

The Reported Problem

Issue #311 proposes a strict 5-layer hierarchy:

ui (Layer 0) → core (Layer 1) → tools/indexing/lsp (Layer 2) → utils (Layer 3) → types/configuration (Layer 4)

Under this model, core should NOT directly import from types (skips Layer 2 and 3).

Current Architecture (DEPENDENCY_MAP.md)

The frozen baseline (2026-01-26) shows a different model:

ui          → outer layer (TUI)
core        → business logic
tools       → agent tools
indexing    → code indexing infrastructure
lsp         → language server protocol
─────────────────────────────────
utils       ┐
types       │ utils-level (importable from anywhere)
configuration│
constants   ┘

Key difference: Types is classified as "utils-level" - a horizontal layer that ANY vertical layer can import from. This is consistent with CLAUDE.md Gate 2.

Architectural Contradiction

The frozen baseline marks core → types: 26 imports as "✅ valid".

Import Inventory (17 files, 26 imports)

State Management (5 imports)

Core Types Re-export (2 imports)

Configuration (1 import)

Logging (1 import)

Agent Core (1 import)

Agent Components (8 imports)

Orchestrator (4 imports)

Resume/Sanitization (4 imports)

Types Layer Analysis

The src/tunacode/types/ directory contains 9 files with types in three categories:

Category A: Valid Utils-Level (Should Stay)

These types are used across multiple layers and are correctly placed:

Category B: Core-Specific (Candidates for Move)

These types are ONLY used by core and should not be in utils-level:

Category C: Dead Code (Delete)

Key Patterns Found

Pattern 1: Core Facade (commit 10b48c30)

• When UI needed LSP functionality, a facade was created in core
• Pattern: ui → core/facade.py → tools/implementation.py → lsp/

Pattern 2: Move to Utils (commit be735754)

• Shared constants moved from tools to utils/system/ignore_patterns.py
• Both tools and indexing import from there

Pattern 3: Central Re-export (current)

• types/__init__.py re-exports everything, hiding internal structure
• core/types.py already re-exports a subset for core's use

Knowledge Gaps

1. Architectural Intent Unclear: Is issue #311's strict layering the desired target state, or is the current "types as utils-level" the correct model?

2. Migration Strategy: If we adopt strict layering, do we:

   • Move core-specific types to core/types/?
   • Create re-exports in utils layer?
   • Use dependency injection?

3. Backward Compatibility: How do we handle the 26 existing imports without breaking changes?

Recommendations

Option A: Keep Current Architecture (Minimal Change)

If types/ remains "utils-level":

• Close issue #311 as "works as designed"
• Delete dead code (CommandContext, ProcessRequestCallback)
• Update documentation to clarify the model

Option B: Strict Layer Enforcement (Issue #311's Proposal)

If we adopt strict layering:

Phase 1: Move Core-Specific Types

1. Create src/tunacode/core/types/ directory
2. Move: ResponseState, AgentState, StateManagerProtocol, SessionStateProtocol
3. Move: ConversationState, TaskState, RuntimeState, UsageState
4. Move: ToolCallRegistry
5. Update 17 files in core to import from core/types/

Phase 2: Cleanup

1. Delete dead code: CommandContext, ProcessRequestCallback
2. Update types/__init__.py to only export utils-level types

Phase 3: Verify

1. Run grimp to confirm zero violations
2. Update DEPENDENCY_MAP.md

My Recommendation

Option B is the correct path forward, but with nuance:

The current architecture has types/ as utils-level because it evolved organically. Issue #311 correctly identifies that core-specific types (protocols, state structures) should live in core, not in a shared layer.

However, the issue's proposed fix (re-exports through utils/tools) adds indirection. The cleaner fix is:

1. Move core-specific types to core/types/ - types that describe core's internal structure belong in core
2. Keep shared types in types/ - primitives, callbacks, canonical message types remain utils-level
3. Result: core imports its own types directly (no indirection), and shared types from utils-level (valid)

This maintains the "utils-level is importable anywhere" principle while moving core-specific implementation details out of the shared layer.

References

• Issue: https://github.com/alchemiststudiosDOTai/tunacode/issues/311
• docs/architecture/DEPENDENCY_MAP.md - Current baseline
• CLAUDE.md Gate 2 - Dependency direction rules
• src/tunacode/types/ - Types layer (9 files)
• src/tunacode/core/types.py - Existing core re-export pattern