Crate of_execution

Expand description

Execution routing and adapter contracts for Orderflow.

§`of_execution`

of_execution is the execution routing and OMS crate for Orderflow. It builds on of_execution_core by adding adapter contracts, route configuration, bounded event buffers, simulated execution, journals, route-scoped risk, concurrent command ownership, and reusable order-management helpers.

The crate is additive to the analytics runtime. It does not change market-data adapter behavior and does not merge execution state into of_runtime. Strategies can read analytics from of_runtime and send orders through of_execution, while those two domains stay separate.

§First Release: 0.1.0

of_execution publishes as 0.1.0 inside the Orderflow 0.4.0 release. This is intentional. The market-data runtime and bindings are on the established 0.4.0 line; execution routing, adapter traits, journals, and OMS helpers are new public crate surfaces and should carry their own compatibility signal.

Versioning rules:

of_execution depends on of_execution_core = 0.1;
existing analytics crates do not depend on of_execution;
of_ffi_c 0.4.0, Python 0.4.0, and Java 0.4.0 expose execution through additive handles/classes backed by this crate;
future 0.1.x releases should prefer additive changes and clear migration notes for adapter authors.

§Design Goals

Keep the synchronous engine deterministic and single-owner.
Preserve route/account/symbol scoped risk accounting.
Use typed requests and reports on the hot path.
Use caller-owned bounded event buffers.
Surface backpressure explicitly instead of hiding it in unbounded queues.
Keep adapter contracts provider-neutral.
Provide a concurrent worker without forcing a Tokio/async runtime.
Make journaling, recovery, and reconciliation additive and replaceable.

§Public API Inventory

Core result and error types:

Event buffers and adapter metadata:

Routing and risk:

Journaling:

Engine and simulation:

Concurrent execution:

OMS helpers:

§Layer Model

flowchart TD
  Strategy[Strategy / host language]
  Engine[ExecutionEngine<br/>or ConcurrentExecutionEngine]
  Route[RouteConfig / RouteKey]
  Risk[RiskLimits / RiskCheck]
  Journal[ExecutionJournal]
  State[OrderStateMachine]
  Adapter[ExecutionAdapter]
  Venue[Venue, broker, or simulator]

  Strategy --> Engine
  Engine --> Route
  Engine --> Risk
  Engine --> Journal
  Engine --> State
  Engine --> Adapter --> Venue

The synchronous ExecutionEngine is the canonical state owner. The ConcurrentExecutionEngine is a wrapper that lets many producer threads submit commands while one worker thread owns the synchronous engine.

§Adapter Contract

Implement ExecutionAdapter to connect a venue, broker, simulator, REST API, WebSocket API, FIX session, or native SDK.

Required methods:

connect()
submit(req, out)
cancel(req, out)
amend(req, out)
poll(out)
recover_open_orders(out)
capabilities()
health()

Adapters write canonical ExecutionEvent values into caller-owned ExecutionEventBuffer instances. They should not leak provider-specific report structs past the adapter boundary.

§ExecutionEventBuffer

ExecutionEventBuffer is a bounded event vector used by adapters and engine calls.

Important behavior:

with_capacity(capacity) allocates bounded storage.
push(event) fails with ExecutionError::BufferFull when full.
clear() retains capacity for reuse.
as_slice() and as_mut_slice() expose currently stored events.
drain_into(out) moves events into another bounded buffer.
max_len() returns configured capacity.

This buffer model matters for low latency and FFI. The caller controls memory growth and the engine never silently drops order events.

§Route Configuration

RouteConfig binds:

route_id
account_id
symbol
enabled
risk_limits

The engine indexes routes by RouteKey:

flowchart LR
  RouteId[route_id]
  AccountId[account_id]
  Symbol[execution symbol]
  Key[RouteKey]

  RouteId --> Key
  AccountId --> Key
  Symbol --> Key

Open-order count and open notional are calculated only within the matched route/account/symbol. This allows one engine to handle multiple symbols without cross-symbol contamination.

Example:

ES route: max one open order.
NQ route: max one open order.
A second ES order is rejected.
A first NQ order is accepted.

§Synchronous Engine

ExecutionEngine<A, R, J> owns:

adapter A
risk gate R
journal J
route table
order-state machines
open-order price cache
metrics
scratch event buffer

Lifecycle:

Build the engine with ExecutionEngine::new(adapter, risk, journal, routes).
Call start().
Call submit, cancel, amend, poll, or recover_open_orders.
Inspect order_state, metrics, health, routes, or replay_journal.

Submit path:

reject if the engine is not started,
validate the request shape,
find the configured route,
build route-scoped risk context,
check route risk limits,
check custom risk gate,
record the command in the journal,
create local pending state,
call the adapter,
apply returned events through the state machine,
record events in the journal,
copy events to the caller output buffer.

The adapter never receives a request that failed local validation or pre-trade risk.

Cancel and amend paths verify the original client order id is known locally. Amends also check replacement quantity/notional before routing.

§Simulated Execution

SimExecutionAdapter is deterministic and intended for:

integration tests,
binding smoke tests,
strategy validation,
replay examples,
examples that should not touch a live broker.

Helpers:

simulated_engine creates a single-route engine.
simulated_engine_with_routes creates a multi-route engine.

The multi-route helper uses route-scoped limits and AllowAllRiskGate, because the engine already enforces each route’s RiskLimits.

use of_execution::{simulated_engine_with_routes, ExecutionEventBuffer, RouteConfig};
use of_execution_core::{
    AccountId, ClientOrderId, ExecutionSymbol, OrderPrice, OrderQty,
    OrderRequest, OrderSide, OrderType, RiskLimits, RouteId, StrategyId,
    TimeInForce,
};

let route = RouteConfig {
    route_id: RouteId::new("SIM")?,
    account_id: AccountId::new("ACC")?,
    symbol: ExecutionSymbol::new("SIM", "ES")?,
    enabled: true,
    risk_limits: RiskLimits {
        kill_switch: false,
        max_order_qty: 100,
        max_order_notional: 1_000_000,
        max_open_orders: 10,
        max_open_notional: 10_000_000,
        price_band_ticks: 0,
    },
};

let mut engine = simulated_engine_with_routes(vec![route]);
engine.start()?;

let req = OrderRequest {
    client_order_id: ClientOrderId::new("C1")?,
    account_id: AccountId::new("ACC")?,
    route_id: RouteId::new("SIM")?,
    strategy_id: StrategyId::new("STRAT")?,
    symbol: ExecutionSymbol::new("SIM", "ES")?,
    side: OrderSide::Buy,
    order_type: OrderType::Limit,
    time_in_force: TimeInForce::Day,
    quantity: OrderQty::new(1)?,
    limit_price: OrderPrice::new(5000)?,
    stop_price: OrderPrice(0),
    ts_exchange_ns: 0,
    ts_recv_ns: 1,
};

let mut events = ExecutionEventBuffer::with_capacity(8);
engine.submit(req, &mut events)?;
assert!(!events.is_empty());

§Journaling

ExecutionJournal records commands and events:

record_command
record_event
replay

InMemoryJournal is useful for tests and embedded simulation. FileExecutionJournal is an append-only durable implementation in the OMS helper surface.

Journal records use JournalRecord:

Command
Event

Command kinds use JournalCommandKind:

Submit
Cancel
Amend
Poll
RecoverOpenOrders

Production deployments can replace the journal with a WAL, mmap-backed writer, database, or replicated log by implementing ExecutionJournal.

§Concurrent Worker

ConcurrentExecutionEngine gives concurrent producer access while preserving single-owner order-state mutation.

flowchart LR
  A[Producer A]
  B[Producer B]
  C[Producer C]
  CQ[Bounded command queue]
  Worker[Worker owns<br/>ExecutionEngine]
  RQ[Bounded report queue]

  A --> CQ
  B --> CQ
  C --> CQ
  CQ --> Worker
  Worker --> RQ

Properties:

many producer handles can enqueue commands,
command queue capacity is explicit,
report queue capacity is explicit,
the worker owns adapter and order state,
reports include command sequence, command kind, result, and events,
no Tokio runtime is required,
order-state transitions remain serial and deterministic.

Use ExecutionCommandSender when producers should not own the worker handle.

Important methods:

ConcurrentExecutionEngine::spawn(engine, config)
command_sender()
send(command)
try_send(command)
recv_report()
try_recv_report()
recv_report_timeout(timeout)
request_stop()
join()

The sender exposes convenience methods:

submit(req)
try_submit(req)
cancel(req)
amend(req)
poll()
recover_open_orders()
stop()

ConcurrentExecutionError::Backpressure means the bounded command or report path is full. Callers should retry, pause strategy intent, alert, or trip a circuit breaker instead of assuming the command was accepted.

§OMS Helper Surface

§Command correlation

CommandId, RequestId, CommandIdGenerator, and CommandCorrelation let hosts associate strategy intent, submitted commands, and reports without relying only on venue ids.

§Event fanout

ExecutionEventFanout publishes execution events to bounded ExecutionEventSubscriber queues.

Full subscriber queues drop deliveries and increment dropped_events(). This is suitable for telemetry or UI subscribers that must not block the main execution path.

§Lifecycle

ExecutionLifecycle tracks ExecutionAdapterState transitions and returns ExecutionLifecycleSnapshot values. Use it to expose adapter state changes such as disconnected, connecting, ready, recovering, degraded, and stopped.

§Durable journal

[FileExecutionJournal::open(path, sync_on_write)] creates an append-only journal. sync_on_write = true is safer but slower. false is faster but less durable on sudden power loss.

§Reconciliation

[reconcile_open_orders(local, venue)] compares local open-order state against venue open-order state and returns a ReconciliationReport.

Actions:

The function reports differences. It does not mutate state or cancel orders.

§Safety policies

DisconnectPolicy describes route behavior during disconnects:

Hold
RejectNew
CancelOpenOrders
Freeze

RouteSafetyPolicy combines disconnect policy, kill switch state, and whether cancels are allowed while killed.

§Advanced risk

AdvancedRiskLimits and AdvancedRiskGate add helpers beyond RiskLimits:

message-rate limit,
absolute position limit,
gross notional limit,
reduce-only mode,
basic route limits.

§Position ledger

PositionLedger folds trade execution events into Position values keyed by PositionKey. It tracks net quantity, buy quantity, sell quantity, gross notional, and average price. It is an OMS-side exposure helper, not a complete accounting system.

§Normalization

VenueOrderCapabilities and normalize_order_type validate canonical order type and TIF choices against provider capabilities. Unsupported order types and TIFs return structured RiskRejectReason values from of_execution_core.

§Telemetry

ExecutionTelemetry tracks counts and latency totals. It is intentionally small so deployments can export metrics to Prometheus, statsd, OpenTelemetry, or internal systems without making this crate depend on any one telemetry stack.

§Sharding

ShardRouter maps ShardKey values to deterministic shard indexes. Sharding should preserve order lifecycle ordering within a route/account/symbol scope while allowing independent scopes to run on separate workers.

§Throttling

OrderThrottle is a token-bucket style helper:

new(capacity, refill_per_sec)
allow(now_ns)
tokens()

Use it before enqueueing commands when a venue or broker has strict message limits.

§Replay simulation

ReplayDecision, ReplayResult, and replay_simulated_oms support deterministic strategy decision replay using the simulated adapter.

§Provider adapter SDK helpers

ProviderAdapterContext, ExecutionAdapterFactory, and ProviderAdapterSdk provide reusable scaffolding for adapter authors.

§Error Model

ExecutionError variants:

Disconnected
BufferFull
RouteNotFound
RiskRejected
Core
Adapter
Journal

ConcurrentExecutionError variants:

Backpressure
Disconnected
Stopped
WorkerPanic
Execution

Risk rejection is not an adapter failure. It is a structured local decision, usually accompanied by a rejection event.

§Low-Latency Notes

Use typed requests, not JSON, on the command path.
Keep adapter output in caller-owned ExecutionEventBuffer values.
Prefer bounded queues for worker and fanout paths.
Apply pre-trade risk before provider I/O.
Keep one owner for order-state mutation.
Do not call strategy code while holding adapter locks.
Export metrics out of band rather than formatting strings on the hot path.

§When To Use Which API

Use ExecutionEngine when:

you are writing Rust,
one owner thread already exists,
deterministic synchronous control is desired,
you are building tests, replay harnesses, or simulations.

Use ConcurrentExecutionEngine when:

many producer threads submit commands,
explicit queue backpressure matters,
one worker should own adapter and order state,
you do not want to depend on Tokio.

Use the C/Python/Java concurrent bindings when:

host-language code needs non-blocking command queueing,
host code should poll command reports,
native code should preserve deterministic state internally.

§What This Crate Does Not Do

This crate does not:

implement a live provider transport,
parse FIX/REST/WebSocket messages,
provide financial advice,
guarantee venue-side execution behavior,
replace broker-side risk controls,
make the dashboard secure for remote production access.

Use of_execution_adapters for reusable provider scaffolds, and implement custom ExecutionAdapter types for broker-specific behavior.

§Documentation

Additional project documentation:

docs/handbook/05h-of-execution-reference.md
docs/handbook/09-oms-architecture.md
docs/handbook/10-oms-cookbook.md
docs/handbook/11-low-latency-design.md
docs/handbook/13-recovery-and-operations.md

Structs§

AdvancedRiskGate: Advanced risk gate with basic limits plus message-rate checks.
AdvancedRiskLimits: Advanced additive risk limits.
AllowAllRiskGate: Pass-through risk hook for engines that rely on route-scoped limits.
CommandCorrelation: Correlation envelope for an execution command.
CommandId: Monotonic command identifier assigned before a command enters an OMS queue.
CommandIdGenerator: Lock-free monotonic command id generator.
ConcurrentExecutionConfig: Configuration for the concurrent execution worker.
ConcurrentExecutionEngine: Concurrent owner for a synchronous execution engine.
ExecutionCapabilities: Execution adapter capabilities.
ExecutionCommandReport: Result report emitted by a concurrent execution worker.
ExecutionCommandSender: Cloneable concurrent command handle for an execution worker.
ExecutionEngine: Execution engine for one adapter and one route set.
ExecutionEventBuffer: Caller-owned event buffer used by execution adapters.
ExecutionEventFanout: Bounded execution-event fanout for multiple consumers.
ExecutionEventSubscriber: Event subscriber for execution fanout.
ExecutionHealth: Execution adapter health snapshot.
ExecutionLifecycle: Mutable lifecycle tracker for adapters and supervisors.
ExecutionLifecycleSnapshot: Execution lifecycle snapshot.
ExecutionMetrics: Execution metrics snapshot.
ExecutionTelemetry: Additive execution telemetry.
FileExecutionJournal: Durable append-only execution journal.
InMemoryJournal: In-memory execution journal for tests and embedded hosts.
NormalizedOrderType: Normalized venue order encoding.
OrderThrottle: Token-bucket style order throttler.
Position: Position for one account/strategy/symbol scope.
PositionKey: Position key.
PositionLedger: Fill and position ledger.
ProviderAdapterContext: Provider adapter context supplied to convenience adapter builders.
ProviderAdapterSdk: Convenience SDK helpers for provider adapters.
ReconciliationItem: One reconciliation difference.
ReconciliationReport: Open-order reconciliation report.
ReplayDecision: Replay decision used by the OMS simulation harness.
ReplayResult: Replay result for deterministic OMS simulation.
RequestId: Request identifier used to correlate strategy intent, command queue entry, and downstream execution reports.
RouteConfig: Execution route configuration.
RouteKey: Stable lookup key for a configured execution route.
RouteSafetyPolicy: Safety policy for one route scope.
ShardKey: Route sharding key.
ShardRouter: Deterministic sharding helper.
SimExecutionAdapter: Deterministic simulated execution adapter.
VenueOrderCapabilities: Venue-specific order type and TIF capabilities.

Enums§

ConcurrentExecutionError: Error returned by the concurrent execution wrapper.
DisconnectPolicy: Route safety behavior during disconnects and kill switches.
ExecutionAdapterState: Venue adapter/session lifecycle state.
ExecutionCommand: Command payload sent to a concurrent execution worker.
ExecutionCommandKind: Command kind sent to a concurrent execution worker.
ExecutionError: Execution-layer error.
JournalCommandKind: Journal command kind.
JournalRecord: Execution journal record.
LatencyClass: Adapter latency classification.
ReconciliationAction: Open-order reconciliation action.

Traits§

ExecutionAdapter: Common execution adapter interface.
ExecutionAdapterFactory: Factory trait for provider-specific execution adapters.
ExecutionJournal: Execution journal hook.

Functions§

normalize_order_type: Validates and normalizes order type/TIF against venue capabilities.
reconcile_open_orders: Reconciles local open-order state against venue state.
replay_simulated_oms: Runs a deterministic simulated OMS replay.
simulated_engine: Creates a one-route simulated execution engine.
simulated_engine_with_routes: Creates a simulated execution engine for multiple configured routes.

Type Aliases§

ExecutionResult: Execution result alias.