> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/architecture/system-architecture) for how these decisions shape the component topology, or [Security Architecture](/architecture/security-architecture) for the trust boundaries that follow from ADR-004 and ADR-005.