Broker integration

Crucible separates strategy decisions from broker-specific execution. Strategies propose intents through the strategy SDK; the runtime applies risk and durability requirements before handing execution commands to an adapter. The adapter translates those commands into broker requests and returns execution observations.

The current Rust interface is ExchangeAdapter in platform-execution. This page explains selected parts of that runtime integration contract. It is separate from the published strategy-author SDK and is not a standalone broker SDK or a complete adapter implementation.

Selected interface

// Selected method signatures.
fn submit(
    &mut self,
    cmd: ExecutionCommand,
) -> Result<(), ExecError>;
 
fn poll_events(
    &mut self,
) -> Vec<ExecutionEvent>;
 
fn command_outcome(
    &mut self,
    command_id: CommandId,
) -> CommandOutcome;

These signatures belong to ExchangeAdapter: Send. The enclosing trait, other methods, and default implementations are omitted; the excerpt is not runnable Rust on its own. The actual command_outcome default returns CommandOutcome::Unknown. An adapter must establish a more specific outcome from broker evidence before returning it.

Commands and execution feedback

Normal place, amend, cancel, and cancel-all operations enter through submit. An adapter must deduplicate commands by command_id. Successful local submission is not evidence of broker acceptance or a fill.

poll_events returns acknowledgements, rejections, fills, and order-state updates for the runtime to process. Business rejections are execution events; infrastructure failures use ExecError. An adapter must preserve the contract's causal ordering and identity requirements when translating broker reports.

The strategy receives execution feedback through its own SDK events. It does not receive a broker handle through StrategyContext.

Uncertain delivery and recovery

A connection failure can leave the runtime uncertain whether a command reached the broker. Retrying an uncertain command can duplicate an order. The recovery contract therefore distinguishes three outcomes:

Outcome	Meaning for recovery
`NotAccepted`	The broker confirms it never accepted the command and it cannot later produce an acknowledgement or fill. A retry may be considered under the runtime's admission rules.
`Accepted`	The broker accepted the command. Recover its state through reconciliation rather than resubmitting it.
`Unknown`	Acceptance cannot be established. Recovery must stop rather than retry or proceed on an assumption.

Pre-acceptance backoff, rate-limit, disconnected, and degraded errors likewise promise that this submission attempt was not accepted. Ambiguous delivery must not be classified as one of those retryable pre-acceptance failures.

Completing an adapter

The full interface also covers connectivity, broker queries for open orders, positions and balances, market-data input for simulation, and emergency cancellation. Live adapters must supply connectivity and reconciliation behavior; default disconnected state and unavailable queries do not establish readiness.

Broker integration also needs qualification of order types, instrument and quantity conventions, partial fills, rate limits, reconnect behavior, command identity and recovery. Broker network work and queue-capacity waits belong outside the target strategy evaluation path; the existence of a synchronous trait method does not itself guarantee nonblocking behavior.

Broker coverage

The adapter interface is an extension boundary, not a claim that a particular broker or asset class is supported. Consult the matching release's integration documentation for implemented adapters, supported order semantics, operating modes and qualification evidence. The public product page does not promise universal broker compatibility.

See the Crucible overview for current integration scope, the strategy SDK for the strategy boundary, and the runbook for operating controls and recovery.