trader-mcp/Strategy_Runtime.md

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:

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.