> ## 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 Experiment Lifecycle State Machine

> State diagram for Experiment states, valid and invalid transitions, and operator actions permitted at each stage.

Every EMEP experiment follows a strict lifecycle. States track progress from creation through completion, failure, or archival. This page defines the state machine, valid transitions, and operator actions.

## State Diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> CREATED : Experiment defined
    CREATED --> PREPARING : Resources allocated
    PREPARING --> RUNNING : Environment validated
    PREPARING --> FAILED : Validation error
    PREPARING --> CANCELLED : Operator abort
    RUNNING --> EVALUATING : Merge / evolution complete
    RUNNING --> FAILED : Runtime error
    RUNNING --> CANCELLED : Operator abort
    EVALUATING --> COMPLETED : All benchmarks finished
    EVALUATING --> FAILED : Evaluation error
    EVALUATING --> CANCELLED : Operator abort
    COMPLETED --> ARCHIVED : Operator archive
    FAILED --> ARCHIVED : Operator archive
    CANCELLED --> ARCHIVED : Operator archive
    ARCHIVED --> [*] : Retention expired
```

## State Definitions

| State      | Definition                                                  | Entry Condition                                                |
| ---------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
| CREATED    | Experiment defined with configuration and benchmark splits  | Operator submits experiment configuration                      |
| PREPARING  | Resources allocated, models imported, environment validated | System confirms resource availability and model integrity      |
| RUNNING    | Merge operations or evolutionary search actively executing  | Environment validation passes                                  |
| EVALUATING | Candidate models undergoing benchmark evaluation            | Merge or evolution stage completes                             |
| COMPLETED  | All operations finished, results recorded, artifacts stored | All benchmarks complete without error                          |
| FAILED     | Unrecoverable error terminated the experiment               | Runtime or evaluation error that cannot be retried             |
| CANCELLED  | Operator or policy halted the experiment before completion  | Explicit abort command issued                                  |
| ARCHIVED   | Experiment retained for audit but no longer active          | Operator archives a COMPLETED, FAILED, or CANCELLED experiment |

## Valid Transitions

| From       | To         | Trigger                                                  |
| ---------- | ---------- | -------------------------------------------------------- |
| CREATED    | PREPARING  | System allocates resources and begins model import       |
| PREPARING  | RUNNING    | All imports and validations succeed                      |
| PREPARING  | FAILED     | Import failure, shape mismatch, or environment error     |
| PREPARING  | CANCELLED  | Operator issues abort before RUNNING                     |
| RUNNING    | EVALUATING | Merge or evolution stage signals completion              |
| RUNNING    | FAILED     | OOM, numerical error, or unhandled exception             |
| RUNNING    | CANCELLED  | Operator issues abort during execution                   |
| EVALUATING | COMPLETED  | All benchmarks finish, metrics logged, artifacts signed  |
| EVALUATING | FAILED     | Benchmark corruption, timeout, or contamination detected |
| EVALUATING | CANCELLED  | Operator issues abort during evaluation                  |
| COMPLETED  | ARCHIVED   | Operator requests archival after review                  |
| FAILED     | ARCHIVED   | Operator requests archival for post-mortem               |
| CANCELLED  | ARCHIVED   | Operator requests archival for record keeping            |

## Invalid Transitions

The following transitions are explicitly prohibited:

| Invalid Transition   | Reason                                                |
| -------------------- | ----------------------------------------------------- |
| CREATED → RUNNING    | Skipping preparation risks environment mismatch       |
| CREATED → EVALUATING | No candidates exist without preparation and execution |
| CREATED → COMPLETED  | Impossible without execution                          |
| RUNNING → COMPLETED  | Evaluation must run independently                     |
| EVALUATING → RUNNING | Re-running merge would invalidate evaluation state    |
| COMPLETED → RUNNING  | Completed experiments are immutable                   |
| ARCHIVED → any state | Archival is terminal; clone experiment to restart     |
| FAILED → RUNNING     | Failed experiments must be cloned, not resumed        |
| CANCELLED → RUNNING  | Cancelled experiments must be cloned, not resumed     |

## Operator Actions by State

| State      | Allowed Actions                                                             | Prohibited Actions                    |
| ---------- | --------------------------------------------------------------------------- | ------------------------------------- |
| CREATED    | Edit configuration, delete experiment, start preparation                    | Start execution, view partial results |
| PREPARING  | Cancel experiment, view import logs                                         | Edit configuration, skip validation   |
| RUNNING    | Cancel experiment, view progress metrics, view logs                         | Edit configuration, force evaluation  |
| EVALUATING | Cancel experiment, view benchmark progress, view logs                       | Edit configuration, skip benchmarks   |
| COMPLETED  | Archive experiment, clone experiment, export results, view full report      | Edit configuration, restart execution |
| FAILED     | Archive experiment, clone experiment, view error logs, view partial results | Restart execution, edit configuration |
| CANCELLED  | Archive experiment, clone experiment, view logs                             | Restart execution, edit configuration |
| ARCHIVED   | View read-only report, export results, delete after retention               | All mutating actions                  |

## State Persistence

Experiment states are stored in ExperimentTracker as append-only log entries. Each transition records:

* Previous state
* New state
* Timestamp (UTC)
* Trigger (system event or operator command)
* Associated artifact references

This log is signed at each transition to prevent tampering.

## Next Steps

See [Experiment Tracking](/tracking/experiment-tracking) for the logging and persistence details, or [Data Flow Map](/maps/data-flow-map) for the data classes that move through these states.