# Strategy Runtime

This is the canonical runtime / engine document for `trader-mcp`.

## Overview

The system is split into:
- strategy definition
- persisted instance record
- runtime execution
- dashboard rendering

## Instance identity

Immutable identity fields:
- `id`
- `strategy_type`
- `account_id`
- `market_symbol`
- `base_currency`
- `counter_currency`

These should stay stable and audit-friendly.

## Mutable fields

- `mode` (`off`, `observe`, `active`)
- `config`
- runtime state snapshots

## State persistence

- the engine owns snapshotting and restore
- strategies only define state shape (`STATE_SCHEMA`)
- persisted state is stored separately from config
- state should be saved at lifecycle boundaries:
  - tick
  - pause
  - unload
  - reload/config change
  - clean shutdown

## Mode semantics

- `off`: not instantiated
- `observe`: instantiated, ticks enabled, trading disabled
- `active`: instantiated, ticks enabled, trading enabled
- `paused`: runtime freeze, not persisted as a mode

## Reconciliation

The engine reconciles DB records to runtime:

```python
if record.mode != "off" and record.id not in running:
    load_instance(record)

if record.mode == "off" and record.id in running:
    unload_instance(record.id)
```

## Reload semantics

Default behavior:
- unload old runtime
- restore state snapshot when available
- load new runtime

Selective state carryover is acceptable only through engine-managed persistence.

## Dashboard responsibilities

The dashboard shows:
- identity
- config
- mode
- runtime status
- rendered widgets

It does not own trading logic.