Aikido: Orientation

Aikido is a policy operating system spanning historical research, frozen policy artifacts, simulation, deployment control, and live account execution. The repository is too large to learn by treating every crate as equally important. Its central production boundary is:

frozen policy input → desired exposure → broker action → observed account truth

Design thesis

Aikido separates concurrent observation and policy computation from mutation by assigning each live account to one executor task, then continuously reconciling desired exposure against broker truth.

• Bounded channels make pressure and ownership transfer explicit.
• One task owns each mutable broker client and account state machine.
• Generic broker traits keep policy independent of protocol adapters.
• Reconciliation, not an order-return value, closes the control loop.

Two connected systems

The repository has a slow decision loop and a fast runtime loop.

Research may use warehouse data to evaluate a candidate. Downstream runtime behavior should instead consume frozen artifacts and control-plane state. That separation prevents a live process from silently changing because a mutable research query changed underneath it.

Runtime workspace center

The runtime path crosses several crates:

• aikido-engine owns bars, strategies, actions, positions, and configuration;
• policy-kernel owns shared policy/accounting semantics;
• fleet-policy-engine decides routing and allocation across deployments;
• aikido-runtime wires Tokio tasks, channels, brokers, journals, and live reconciliation;
• projectx-rs and rithmic-rs provide broker/protocol clients.

The runtime task graph

One process hosts many Tokio tasks:

BarFetcher(s) → SharedBarStore → SignalEngine(s) → SignalRouter
                                                    ↓
                                           AccountExecutor(s)
                                                    ↓
                                                  broker
                                                    │
                        ExecutorStateUpdate ─────────┘

The key ownership rule is one AccountExecutor per deployment/client. That task owns one mutable broker client and dynamically keyed per-contract runtime state. Other tasks communicate with it through commands rather than borrowing or locking the broker.

Scope

We will follow one fresh bar through strategy evaluation, routing, guardrails, execution, and feedback. We will also study desired-state convergence and broker reconciliation because success-path order placement alone is not the system’s architectural center.

Legacy fleet simulation, every research script, every broker API method, TUI rendering, and deployment operations remain outside the main trace.