Architecture summary

Aikido architecture

This document summarizes the implemented system, the locked target architecture, and the migration boundary between them. It does not replace the versioned architecture documents in the repository.

Architecture object: Policy operating system
Decision contract: Immutable policy-state pack
Realized-truth owner: Runtime and evaluator
Migration status: In progress

1. Target flow

Git
  code, schemas, versioned contracts

market + discovery          research_control
  facts + evidence           queues + operational boards
        |                              |
        +-------------+----------------+
                      |
                      v
             pack compiler / publication
                      |
                      v
            immutable PolicyStatePack
                      |
                      v
PolicyStatePack -> Policy -> RequestedTargetExposure
                                      |
                                      v
                             Runtime / Realizer
                                      |
                                      v
                              ExecutionReport
                                      |
                                      v
                           Evaluation / EpisodeResult

Point-in-time compilation occurs at one publication boundary. Once a pack is loaded, policy and runtime do not depend on live warehouse reads. Policy produces intent; runtime applies executable mechanics; evaluation judges realized outcomes.

2. Authority model

The architecture distinguishes three forms of authority:

Question	Authority	Includes
What research evidence exists?	`discovery`	Config payloads, exact evaluations, trades, daily evidence, provenance
What was available to policy?	Frozen `PolicyStatePack`	Decision-time slice, cutoff, identity, hashes, lineage, allowed context
What actually happened?	Runtime and evaluator output	Executable state, fills, account ledger, drawdown, episode outcome

Scores, dashboards, mutable current views, compatibility snapshots, and leaderboards are projections. They are not substitutes for one of these authority surfaces.

3. Current implementation

Concern	Current surface	Target role	Status
Market facts	Legacy and `market.*` compatibility surfaces	`market`	Converging
Signal research evidence	`discovery.signal_*` and legacy discovery surfaces	`discovery`	Converging
Research operations	`research_control` jobs, plans, and boards	Operational control plane	Aligned
Decision publication	Pack registry, manifests, builders, and active pointer	Single pack compiler and publication boundary	Converging
Policy and simulation	`policy-kernel`, `policy-sim`, `policy-sim-env`	Pack input to requested exposure	Converging
Realization and accounting	Runtime and shared simulation/evaluation components	One execution and account truth core	Converging
Historical PIT snapshots	`portfolio.snapshot*` and compatibility views	Optional rebuildable cache only	Transitional

4. Core contracts

Policy input and output

PolicyStatePack -> Policy -> RequestedTargetExposure

The policy state pack is an immutable point-in-time input. The policy output expresses desired exposure; it is not a fill or an account fact.

Runtime realization and audit

RequestedTargetExposure
    -> ExecutableExposure
    -> RealizedExecutionState
    -> ExecutionReport

Contract binding, rounding, continuity, fill representation, and accounting belong to the realizer. Policy-specific selection or sizing logic does not.

Evaluation

ExecutionReport + account path -> EpisodeResult -> promotion gates

Only realized runtime/evaluator output can support claims about deployability. Research-screening scores and constituent-level results cannot substitute for account-path replay.

5. Storage roles

Git: Code, schemas, contracts, documentation, and deliberately reviewed small manifests.
ClickHouse: Market facts, canonical research evidence, and large immutable warehouse data.
Postgres: Queues, operational control state, publication pointers, deployment state, and runtime coordination.
Artifact storage: Immutable generated pack payloads, manifests, checksums, and lineage sidecars.

Postgres is not a second research warehouse. ClickHouse is not a hot decision-loop dependency. Git is not used as bulk evidence storage.

6. Runtime and research invariants

At least 126 out-of-sample trading days are required for a result to count as evidence; 189 is the target.
Holdout data is measurement-only and cannot change weights, filters, parameters, or gates.
Replay and live runtime use the same session and accounting semantics.
Positions are flat at 16:00 ET and are not carried overnight.
All market-bar and trade time reasoning uses America/New_York.
Every evidence-producing run records its exact data publication and provenance.
Search, training, canonical replay, and live-shadow may differ in speed but not in account truth.
A challenger is not promoted from one scalar metric or one short window.

7. Migration order

Keep the target boundaries and authority rules fixed.
Ground research inventory and boards in canonical discovery evidence.
Move one real baseline end to end through the frozen pack contract.
Demonstrate parity with the legacy scheduled path using realized outcomes.
Move downstream consumers from live PIT reads to pack consumption.
Drain or minimize transitional portfolio.* surfaces.
Continue converging runtime, simulation, and evaluation on one truth core.

Source documents

docs/problem_frame.md
docs/SYSTEM_INVARIANTS.md
docs/architecture.md
docs/research/ideal_system_target_state_2026-04-21.md
docs/research/current_to_target_system_map_2026-04-21.md
docs/research/target_state_compliance_checklist_2026-04-21.md
docs/policy_pack_system_v1.md