Packaging
Make dependencies, state, and delivery contracts explicit.
A repository's shape is inferred from its layout; the surface is a separate concern. The dependency direction runs surfaces → api → lib, with independent API submodules. Runtime dependencies are deliberately minimal; delivered checks use the Python standard library and must run without importing the racecar package. State belongs to its declared persistence class: release, administrator-controlled, or runtime-accumulated.
Package Shapes
Layout is distinct from interface
A repository's package shape is inferred from its layout: src, src+server, server, or a flat Django arrangement. This is not the same as its public surface, which may be CLI, REST, MCP, a Django app, or an agent skill. Treating these dimensions independently prevents delivery structure from dictating interface semantics. The package can change shape without rewriting the underlying business capability.
Dependency Contracts
Surfaces above API above library
The package defines a strict direction of imports. Surface adapters depend on API, API depends on library, and independent API submodules do not import one another. Delivered check scripts remain standard-library-only and cannot import the racecar package, because an adopter receives the scripts without that package. The checkers must be runnable in the environment they are intended to grade.
Persistence Contracts
State has an owner and a lifetime
Release artifacts, administrator-controlled configuration, and runtime-generated state have different lifetimes and writers. Their placement must follow those distinctions. A file that changes during operation must not be treated as immutable package source; a released artifact must not silently become a runtime scratchpad. Explicit state ownership is part of reproducibility, auditability, and reliable upgrades.