DOLPHIN/prod/TODO_RUNTIME_FLAGS.md

# TODO: Runtime Flags / Toggle System for Dolphin

**Filed**: 2026-04-06  
**Priority**: Medium — needed before live trading

## Problem

Currently there is no way to input toggles/flags into the paper or live trading system
at runtime without editing code and restarting services. This creates operational friction
and risk (code edits in production).

## Current Workaround

Environment variables read at service startup:
- `DOLPHIN_FAST_RECOVERY=1` — bypasses bounded recovery in SurvivalStack (paper only)

## Desired Capabilities

1. **Runtime toggles** — change behavior without restart (e.g., via Hazelcast IMap or HTTP endpoint)
2. **Paper vs Live flags** — some toggles should only apply in paper mode
3. **Audit trail** — log when flags change, who changed them, previous value
4. **Safety** — certain flags (like disabling risk limits) should require confirmation or be paper-only

## Candidate Flags

| Flag | Description | Paper/Live |
|---|---|---|
| `FAST_RECOVERY` | Skip bounded recovery dynamics | Paper only |
| `FORCE_POSTURE` | Override posture to specific value | Paper only |
| `PAUSE_ENTRIES` | Stop new entries without changing posture | Both |
| `MAX_LEVERAGE_OVERRIDE` | Cap leverage below algo default | Both |
| `LOG_LEVEL` | Change log verbosity at runtime | Both |

## Implementation Options

1. **Hazelcast IMap** (`DOLPHIN_FLAGS`) — already have Hz, services already connected. Read on each tick. Simple.
2. **HTTP control plane** — small Flask/FastAPI sidecar. More discoverable, but another service.
3. **File-based** — watch a JSON file. Simple but no audit trail.

Recommendation: Start with option 1 (Hz IMap). One map, services poll it. TUI can show/edit flags.
initial: import DOLPHIN baseline 2026-04-21 from dolphinng5_predict working tree Includes core prod + GREEN/BLUE subsystems: - prod/ (BLUE harness, configs, scripts, docs) - nautilus_dolphin/ (GREEN Nautilus-native impl + dvae/ preserved) - adaptive_exit/ (AEM engine + models/bucket_assignments.pkl) - Observability/ (EsoF advisor, TUI, dashboards) - external_factors/ (EsoF producer) - mc_forewarning_qlabs_fork/ (MC regime/envelope) Excludes runtime caches, logs, backups, and reproducible artifacts per .gitignore. 2026-04-21 16:58:38 +02:00			`# TODO: Runtime Flags / Toggle System for Dolphin`

			`Filed: 2026-04-06`
			`Priority: Medium — needed before live trading`

			`## Problem`

			`Currently there is no way to input toggles/flags into the paper or live trading system`
			`at runtime without editing code and restarting services. This creates operational friction`
			`and risk (code edits in production).`

			`## Current Workaround`

			`Environment variables read at service startup:`
			- `DOLPHIN_FAST_RECOVERY=1` — bypasses bounded recovery in SurvivalStack (paper only)

			`## Desired Capabilities`

			`1. Runtime toggles — change behavior without restart (e.g., via Hazelcast IMap or HTTP endpoint)`
			`2. Paper vs Live flags — some toggles should only apply in paper mode`
			`3. Audit trail — log when flags change, who changed them, previous value`
			`4. Safety — certain flags (like disabling risk limits) should require confirmation or be paper-only`

			`## Candidate Flags`

			`\| Flag \| Description \| Paper/Live \|`
			`\|---\|---\|---\|`
			\| `FAST_RECOVERY` \| Skip bounded recovery dynamics \| Paper only \|
			\| `FORCE_POSTURE` \| Override posture to specific value \| Paper only \|
			\| `PAUSE_ENTRIES` \| Stop new entries without changing posture \| Both \|
			\| `MAX_LEVERAGE_OVERRIDE` \| Cap leverage below algo default \| Both \|
			\| `LOG_LEVEL` \| Change log verbosity at runtime \| Both \|

			`## Implementation Options`

			1. Hazelcast IMap (`DOLPHIN_FLAGS`) — already have Hz, services already connected. Read on each tick. Simple.
			`2. HTTP control plane — small Flask/FastAPI sidecar. More discoverable, but another service.`
			`3. File-based — watch a JSON file. Simple but no audit trail.`

			`Recommendation: Start with option 1 (Hz IMap). One map, services poll it. TUI can show/edit flags.`