Scope & Assumptions

Goal

Move core-specific types from shared types/ layer into core/types/ to follow Clean Architecture principles where domain types live in the domain layer.

Non-goals:

• Changing the shared types that are correctly utils-level
• Adding re-export indirection layers
• Modifying any business logic

Scope & Assumptions

In scope:

• Create src/tunacode/core/types/ directory structure
• Move 9 core-specific types to core/types/
• Update 17 files in core to import from new location
• Delete 2 dead types (CommandContext, ProcessRequestCallback)
• Update DEPENDENCY_MAP.md

Out of scope:

• Changes to UI layer
• Changes to tools layer
• New features or behavior changes

Assumptions:

• The existing core/types.py re-export pattern can be expanded
• Tests pass after import path changes
• No circular import issues will arise

Deliverables (DoD)

1. src/tunacode/core/types/ directory with moved types
2. All 17 core files updated to import from core/types/
3. Dead code deleted from types/dataclasses.py and types/callbacks.py
4. ruff check passes
5. uv run pytest passes
6. DEPENDENCY_MAP.md updated

Readiness (DoR)

• Research document complete
• Best practice verified (Clean Architecture standard)
• File inventory complete (17 files, 26 imports)
• Types categorized (9 to move, 2 to delete)

Milestones

• M1: Create core/types/ structure and move types
• M2: Update all import statements
• M3: Delete dead code and verify

Work Breakdown (Tasks)

Task 1: Create core/types/ directory structure

Summary: Create the directory and initial __init__.py Files: src/tunacode/core/types/__init__.py Acceptance:

• Directory exists
• __init__.py exports nothing yet (placeholder)

Task 2: Move core-specific types to core/types/

Summary: Move 9 types from types/ to core/types/ Types to move:

• ResponseState (from dataclasses.py)
• AgentState (from dataclasses.py)
• StateManagerProtocol (from state.py)
• SessionStateProtocol (from state.py)
• ConversationState (from state_structures.py)
• TaskState (from state_structures.py)
• RuntimeState (from state_structures.py)
• UsageState (from state_structures.py)
• ToolCallRegistry (from tool_registry.py)

Files touched:

• Create: src/tunacode/core/types/state.py
• Create: src/tunacode/core/types/protocols.py
• Create: src/tunacode/core/types/registry.py
• Update: src/tunacode/core/types/__init__.py

Acceptance:

• All 9 types defined in core/types/
• Exports work via from tunacode.core.types import X

Task 3: Update 17 core files to import from core/types/

Summary: Change import statements from tunacode.types to tunacode.core.types for moved types Files to update (17):

1. core/state.py
2. core/user_configuration.py
3. core/lsp_status.py
4. core/types.py (the re-export file)
5. core/configuration.py
6. core/logging/manager.py
7. core/agents/main.py
8. core/agents/agent_components/agent_config.py
9. core/agents/agent_components/agent_helpers.py
10. core/agents/agent_components/response_state.py
11. core/agents/agent_components/state_transition.py
12. core/agents/agent_components/streaming.py
13. core/agents/agent_components/orchestrator/orchestrator.py
14. core/agents/agent_components/orchestrator/tool_dispatcher.py
15. core/agents/agent_components/orchestrator/usage_tracker.py
16. core/agents/resume/sanitize.py
17. core/agents/resume/sanitize_debug.py

Acceptance:

• All imports updated
• ruff check passes
• No import errors at runtime

Task 4: Delete dead code

Summary: Remove unused types from shared types layer Delete:

• CommandContext from types/dataclasses.py
• ProcessRequestCallback from types/callbacks.py

Acceptance:

• Dead code removed
• No references remain
• ruff check passes

Task 5: Verify and update documentation

Summary: Run tests, update DEPENDENCY_MAP.md Files:

• docs/architecture/DEPENDENCY_MAP.md

Acceptance:

• uv run pytest passes
• DEPENDENCY_MAP.md reflects new structure
• core → types import count reduced

Risks & Mitigations

Test Strategy

• Run existing test suite: uv run pytest
• Manual verification: python -c "from tunacode.core.types import AgentState"
• No new tests needed (structural change only)

Tickets Created

References

• Research: memory-bank/research/2026-01-27_00-10-38_issue-311-core-types-layer-violation.md
• Issue: https://github.com/alchemiststudiosDOTai/tunacode/issues/311
• Clean Architecture best practice: domain types live in domain layer