ROADMAP-14 — P2 — Type the run-repository interface; delete the hasattr/guard lattice #106

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M16-T01 · Priority: P2 · Effort: medium

Problem

The interfaces the project claims (core depends only on abstract interfaces) are duck-typed as Any at the seams, and the compiler is disabled exactly where it matters:

• Agent.__init__(memory: Any) then 4 hasattr checks (create_run/save_messages/update_run/get_messages)
• trace is typed TraceSink | None yet still duck-checked (hasattr(self.trace, "record"))
• TieredMemoryStore.run_store: Any + 5 hasattr/getattr guards
• Request paths in routes.py duck-check get_run/get_run_trace, and deps.py returns a union type whose purpose is to advertise concrete methods that should live on the interface

Evidence

• agentkit/memory/tiered.py:24,48,61,73,86,97
• agentkit/core/agent.py:143,176,199,214,261,394
• agentkit/api/routes.py:61,109,137,143–145
• agentkit/api/deps.py:62

Suggested fix / acceptance criteria

• A RunRepository Protocol (create_run/update_run/get_run/get_run_trace/list_runs)
• TieredMemoryStore.run_store, Agent.memory (session + run halves clearly typed), and deps return types use it
• All hasattr/getattr guards deleted from prod paths; mypy --strict clean
• Existing suite green without test-double signature changes beyond implementing the Protocol

Suggested branch / commit

refactor/run-store-protocol · refactor(core): type the run-repository interface and delete duck-typing guards