EMEP Architectural Decision Records

ADR-001 through ADR-012 covering modular architecture, safetensors, offline-first mode, evidence-tagged docs, and reference runtime assumptions.

Architectural Decision Records (ADRs) capture the reasoning behind major design choices in EMEP. Each record includes the decision, status, rationale, consequences, and any superseding record.

Decision Table

ID	Title	Status	Rationale	Consequences	Superseded by
ADR-001	Modular component architecture	Accepted	Enables independent testing, replacement, and parallel development of merge, evolution, and evaluation subsystems	Increased interface complexity; requires strict contract definitions	None
ADR-002	No MergeKit lock-in	Accepted	Prevents dependency on a single external library whose roadmap may diverge from EMEP needs	Must re-implement core merge strategies; full control over tensor operations	None
ADR-003	Safetensors as primary artifact format	Accepted	Memory-mapped loading, fast I/O, no pickle execution risk, security scanning compatible	All model I/O must convert to/from safetensors; legacy pickle checkpoints require migration	None
ADR-004	ed25519 artifact signing	Accepted	Modern, fast, widely supported elliptic-curve signatures for provenance and supply chain integrity	Key management infrastructure required; verification mandatory in enterprise mode	None
ADR-005	Offline-first enterprise mode	Accepted	Satisfies air-gapped deployment requirements for regulated and secure environments	All external dependencies (Hub, package indexes) must be mirrorable; updates are manual	None
ADR-006	Hidden Test Set isolation	Accepted	Prevents overfitting and benchmark contamination by strictly separating optimization and final evaluation data	EvaluationEngine must enforce split boundaries; operators cannot override	None
ADR-007	Evolution non-optimizing against test data	Accepted	Extends ADR-006: evolutionary search uses only Optimization Set and Validation Set	FitnessEngine must reject Hidden Test Set metrics; any violation aborts experiment	None
ADR-008	Semantic versioning for Enterprise Models	Accepted	Communicates breaking changes, compatibility guarantees, and release stability to downstream consumers	Version bump policy required; automated checks against API surface changes	None
ADR-009	Evidence-tagged documentation	Accepted	Distinguishes established research from hypotheses, assumptions, and unvalidated results, reducing reader confusion	Every claim must carry a tag; untagged claims are flagged in review	None
ADR-010	Mermaid as primary diagram format	Accepted	Plain-text, version-controllable, renderable in docs and GitHub, no proprietary tool dependency	Complex layouts may require manual adjustment; limited interactive features	None
ADR-011	Python 3.11 as reference runtime	Accepted	Match target deployment environment; balance new features with stability	Components must run on 3.11; newer syntax is prohibited	None
ADR-012	PyTorch as reference tensor engine	Accepted	De facto standard for open-weight models; extensive ecosystem for CUDA, quantization, and export	Ties EMEP to PyTorch release cadence; alternative backends require abstraction layer	None

Status Definitions

• Proposed: Under discussion, not yet approved
• Accepted: Approved and active; implementation must conform
• Deprecated: Superseded by a newer ADR; do not use for new work
• Rejected: Explicitly declined; record retained to prevent recurrence

Consequence Patterns

Accepted ADRs create obligations:

• ADR-001: Every new component needs a defined interface contract and unit test plan
• ADR-002: Merge strategies must be native implementations with documented algorithms
• ADR-003: All model artifacts pass through safetensors conversion on import
• ADR-004: ArtifactStore rejects unsigned writes in enterprise mode
• ADR-005: Installation documentation includes mirror setup instructions
• ADR-006 / 007: ExperimentTracker logs split assignments at creation time and enforces immutability
• ADR-008: DeploymentManager rejects releases without valid semantic version
• ADR-009: Documentation review checklist includes evidence tag verification
• ADR-010: All specification pages include at least one Mermaid diagram
• ADR-011 / 012: CI runs on Python 3.11 with PyTorch stable

Next Steps

See System Architecture for how these decisions shape the component topology, or Security Architecture for the trust boundaries that follow from ADR-004 and ADR-005.