codebase-designlisted

# Codebase design Design deep modules: substantial behavior behind a small interface, placed at a real seam and tested through that interface. Optimize for caller leverage and maintainer locality. ## Vocabulary - **Module:** anything with one interface and an implementation, from a function to a package. - **Interface:** everything a caller must know: types, invariants, ordering, errors, configuration, and relevant performance behavior. - **Implementation:** the behavior hidden inside a module. - **Depth:** useful behavior per unit of interface a caller must learn. - **Seam:** a place where behavior can change without editing the caller at that place. - **Adapter:** a concrete implementation that satisfies an interface at a seam. - **Leverage:** capability callers gain from a small interface. - **Locality:** change, knowledge, bugs, and verification concentrated in one place. Use these terms consistently. Prefer **seam** over the overloaded word **boundary** when discussing replaceable behavior. ## Design checks - Reduce methods and parameters when callers do not need the exposed choice. - Hide repeated orchestration, invariants, and error handling inside the module. - Apply the deletion test: deleting a useful module should make its complexity reappear across its callers. A layer whose complexity simply vanishes was probably a pass-through. - Treat the interface as the test surface. Tests should survive internal refactors. - Accept dependencies at real seams instea