Runtime flow

If you only remember one thing about fbtf, remember this: the runner is the coordinator, not the source of truth for everything.

The runtime is built from four main parts:

1. market — defines the contract/tick assumptions for the run
2. feed — provides bars in order
3. strategy — produces intents based on the current context
4. broker — applies those intents to paper-trading state

High-level sequence

For each bar:

1. the feed advances to the next bar
2. the runner builds the strategy context
3. the strategy decides whether to emit an intent
4. the broker updates paper state from the bar and any accepted order logic
5. diagnostics, runtime events, and result snapshots are updated

The exact details differ a little between historical replay and live paper mode, but the mental model is the same.

Strategy context

Strategy code sees a context object rather than direct mutable runtime state.

That context includes things like:

• the current bar
• the bar index
• the current paper position/account view
• services (when configured)
• lifecycle/session metadata where relevant

The point is to keep strategy code explicit and testable.

Intents, not side effects

defineStrategy() is designed around returning intents like buy, sell, or close, not directly mutating the broker.

That keeps decision logic and execution logic separate.

Historical feed vs live feed

Historical

• finite replay
• deterministic ordering
• easier to reason about end-to-end

Live

• event-driven input
• duplicates/out-of-order behavior matters
• timeout and stale-decision behavior matters more

The integration tests in the repo are valuable here because they lock down the edge cases around live sequencing.

Broker role

The paper broker is responsible for:

• tracking orders
• tracking fills
• tracking trades
• maintaining account and position state
• applying slippage/commission assumptions

The runner should not duplicate those concerns.

Result assembly

After completion, the run result is assembled from the broker/account/diagnostic state into a structured result object.

That is what powers the result contracts and the experiment reporting layer.

Recommended mental model

Think about fbtf like this:

• feed answers: what bar are we on?
• strategy answers: what do we want to do?
• broker answers: what actually happened to paper state?
• runner answers: how do these pieces move in order?