Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. Goal: testability and AI-navigability.

Vocabulary (use these terms exactly)

• Module — anything with an interface and implementation (function, class, package, slice)
• Interface — everything a caller must know: types, invariants, error modes, ordering, config
• Depth — leverage at the interface: much behavior behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation
• Seam — where an interface lives; a place behavior can be altered without editing in place
• Adapter — a concrete thing satisfying an interface at a seam
• Leverage — what callers get from depth
• Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place

Key principles:

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.