> ## 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.

# MergeEngine: Pipeline, Interface, and Failure Modes

> MergeEngine specification for EMEP. Defines the full merge pipeline from model sources through strategy selection, tensor operations, numerical validation, and candidate registration. Includes failure modes.

MergeEngine is the central orchestrator for all model merging operations in EMEP. This page defines its purpose, interface, pipeline stages, and the exact flow from two or more source models to a registered candidate.

## Purpose

MergeEngine takes validated, compatible models and produces a merged candidate. It delegates architecture and compatibility checks to ModelCompatibilityAnalyzer, tensor operations to TensorEngine, and strategy selection to MergeStrategy plug-ins.

## Interface

```python theme={null}
def merge(
    sources: List[ModelManifest],
    strategy: MergeStrategy,
    config: MergeConfig,
    experiment_id: Optional[UUID] = None
) -> CandidateManifest
```

| Parameter      | Type                 | Description                     |
| -------------- | -------------------- | ------------------------------- |
| sources        | List\[ModelManifest] | Two or more models to merge     |
| strategy       | MergeStrategy        | Selected merge strategy plug-in |
| config         | MergeConfig          | Strategy-specific parameters    |
| experiment\_id | Optional\[UUID]      | Links merge to an experiment    |

Returns a CandidateManifest with status, artifact URI, and merge provenance.

## Full Merge Pipeline

```mermaid theme={null}
flowchart TD
    START([START]) --> SOURCES[Model Sources]
    SOURCES --> IMPORT[Import via ModelLoader]
    IMPORT --> META[Metadata Extraction]
    META --> ARCH[Arch Check: ModelCompatibilityAnalyzer]
    ARCH --> TOKEN[Tokenizer Check]
    TOKEN --> SHAPE[Shape Check]
    SHAPE --> DTYPE[Dtype Check]
    DTYPE --> DECISION[Compatibility Decision]
    DECISION -->|INCOMPATIBLE| FAIL_COMPAT[FAIL: incompatible]
    DECISION -->|CONDITIONALLY_COMPATIBLE| TASK[Task/Weight Extraction if required]
    DECISION -->|COMPATIBLE| STRATEGY[Strategy Selection]
    TASK --> STRATEGY
    STRATEGY --> PARAM[Param Validation]
    PARAM -->|invalid| FAIL_PARAM[FAIL: invalid parameters]
    PARAM -->|valid| TENSOR[Tensor Ops via TensorEngine]
    TENSOR --> NUMERICAL[Numerical Validation]
    NUMERICAL -->|NaN/Inf| FAIL_NUM[FAIL: numerical instability]
    NUMERICAL -->|pass| OUTPUT[Output Model]
    OUTPUT --> ARTIFACT[Artifact Validation]
    ARTIFACT -->|fail| FAIL_ART[FAIL: artifact corrupt]
    ARTIFACT -->|pass| BENCH[Benchmark]
    BENCH --> REGISTER[Candidate Registration]
    REGISTER --> END([END])
    FAIL_COMPAT --> END
    FAIL_PARAM --> END
    FAIL_NUM --> END
    FAIL_ART --> END
```

## MergeStrategy Plug-In System

MergeEngine loads strategies as plug-ins. Each strategy implements:

```python theme={null}
class MergeStrategy(Protocol):
    def validate(self, sources: List[ModelManifest], config: MergeConfig) -> ValidationResult
    def execute(self, sources: List[ModelManifest], config: MergeConfig, tensor_engine: TensorEngine) -> MergedStateDict
    def required_compatibility(self) -> CompatibilityLevel
```

Strategies declare their required compatibility level. A strategy requiring COMPATIBLE will reject CONDITIONALLY\_COMPATIBLE pairs. A strategy accepting CONDITIONALLY\_COMPATIBLE must handle the discrepancy internally.

## Failure Modes

| Stage                | Failure                  | Cause                           | Outcome                        |
| -------------------- | ------------------------ | ------------------------------- | ------------------------------ |
| Import               | Hash mismatch            | Corruption or tampering         | FAIL, alert                    |
| Arch Check           | INCOMPATIBLE             | Architecture mismatch           | FAIL, no candidate             |
| Tokenizer Check      | INCOMPATIBLE             | Tokenizer mismatch              | FAIL, no candidate             |
| Shape Check          | INCOMPATIBLE             | Tensor shape mismatch           | FAIL, no candidate             |
| Strategy Selection   | No strategy accepts pair | Compatibility level too low     | FAIL                           |
| Param Validation     | Invalid config           | Wrong parameter types or ranges | FAIL                           |
| Tensor Ops           | OOM                      | GPU memory exhausted            | FAIL, retry with smaller batch |
| Numerical Validation | NaN/Inf                  | Instability in merge math       | FAIL, quarantine               |
| Artifact Validation  | Corrupt output           | Write error or truncation       | FAIL                           |
| Benchmark            | Timeout                  | Benchmark exceeds wall clock    | INCOMPLETE                     |

## Cross-Links

* [Merge Strategies](/merge/merge-strategies) for available strategies.
* [Tensor Operations](/merge/tensor-operations) for low-level ops.
* [Merge Validation](/merge/merge-validation) for post-merge checks.
* [Model Compatibility](/compatibility/model-compatibility) for the compatibility decision.