> ## Documentation Index
> Fetch the complete documentation index at: https://quantform.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution

> Execution mode defines runtime semantics for strategy behavior, timestamps, storage usage, and execution side effects.

Use one strategy shape and choose the mode based on where you are in the development lifecycle.

## Modes at a glance

| Mode     | Purpose                                | Typical use                                                          |
| -------- | -------------------------------------- | -------------------------------------------------------------------- |
| `paper`  | Simulation with live-like runtime flow | Validate logic against current market streams without real execution |
| `replay` | Historical backtest flow               | Deterministic strategy verification on a fixed time window           |
| `live`   | Production execution                   | Real order/transaction execution after validation                    |

## Runtime API

Use `useExecutionMode()` to inspect the active mode:

```ts theme={null}
const { isReplay, isSimulation } = useExecutionMode();
```

* `isSimulation` is `true` for non-live modes
* `recording` is configured through CLI mode options for `paper` and `live`

## CLI commands

* `qf paper <strategy>`
* `qf replay <strategy> --from <date> --to <date>`
* `qf live <strategy>`

All commands load the same strategy module and inject mode-specific dependencies.

## Paper mode

Use `paper` when strategy logic is still evolving and you want real-time behavior without real capital impact.

Typical characteristics:

* live-like event flow
* simulated execution paths
* optional recording for diagnostics (`--recording`)

```bash theme={null}
qf paper pipeline --id paper-sol-v1 --recording
```

## Replay mode

Use `replay` for deterministic backtesting over a fixed period.

Replay characteristics:

* uses historical storage streams
* aligns runtime time with replay scheduler
* allows reproducible validations when window and inputs are fixed

```bash theme={null}
qf replay pipeline --from 2025-01-01 --to 2025-01-07 --id replay-week-1
```

For replay-safe code paths, use `useTimestamp` and replay-aware branching.

## Live mode

Use `live` only after paper + replay confidence gates pass.

Typical characteristics:

* production connectors and execution
* real risk and real fills
* optional recording for audit and analysis

```bash theme={null}
qf live pipeline --id live-main --recording
```

## Mode-aware branching patterns

`useSimulator(simulated, real)` picks simulated logic for any non-live run.

`useReplay(backtest, real)` picks backtest logic only in replay mode.

```ts theme={null}
import { useReplay, useSimulator } from '@quantform/core';

const orderExecutor = useSimulator(simulatedExecutor, liveExecutor);
const marketSource = useReplay(historicalSource, realtimeSource);
```

Use this approach to keep strategy orchestration stable while switching execution internals per mode.

## Recommended promotion flow

1. Build logic in `paper` mode.
2. Validate deterministically in `replay` mode on targeted windows.
3. Promote to `live` with explicit session ID and recording where needed.
4. Keep mode branching explicit and minimal to reduce divergence.

## Common mistakes

* Using `Date.now()` instead of `useTimestamp` in replay-sensitive logic
* Mixing live side effects into replay code paths
* Skipping paper/replay validation before live rollout
* Over-branching strategy flow by mode instead of branching only execution edges