# Architecture

Sovereign Engine v2 is a multi-language repository with several execution paths. The Python research router, engine task router, provider adapters, native runtimes, and desktop clients have distinct interfaces and validation scopes.

## Python execution paths

```mermaid
flowchart TD
    Runner[run.py] --> Routing[RoutingPipeline]
    Runner --> Agent[ReActAgent]
    Agent --> Model[Model interface]
    Runner --> Bedrock[BedrockBackend]
    Bridge[HTTPBridge] --> Multi[MultiProvider]
    Bridge --> Registry[ToolRegistry]
    Bridge --> BridgeAgent[Bridge ReActAgent]
    Engine[SovereignEngine draft wiring] --> Routing
    Engine --> Agent
    Engine --> Continuity[ContinuityManager]
    Engine --> Ledger[WORMLedger]
```

This diagram shows construction/call relationships in the source, not a successful end-to-end run. The unified engine and bridge agent paths contain interface mismatches described in [deployment readiness](docs/PRODUCTION_HARDENING.md).

| Component | Contract |
|---|---|
| [RoutingPipeline](src/routing/pipeline.py) | Text/context to trace and expert dispatch result |
| [AgentDispatch](src/routing/dispatch.py) | Async expert callbacks returning dictionaries |
| [ReActAgent](src/agents/react.py) | Task entity and optional initial context to a reasoning/tool loop |
| [ToolRegistry](src/tools/registry.py) | Tool definitions, lookup, schemas, and policy metadata |
| [ContinuityManager](src/continuity/manager.py) | Synchronous state transitions and backend coordination |
| [WORMLedger](src/core/evidence.py) | Synchronous event append, scan, and chain checks |
| [HTTPBridge](src/bridge/http_server.py) | HTTP handlers for provider chat, tools, keys, and routing traces |

## Routing boundaries

The engine routes task text through parsing, symbolic/Jordan/Jacobian analysis, constraints, sparse activation, and dispatch. Its selected experts need real asynchronous implementations supplied by the caller.

The independent [research router](research/sparse-routing/) instead operates on a graph model. It measures synthetic edge costs and rank, proposes topology changes, verifies invariants, and commits accepted states. Its benchmark does not time the agent's LLM generation.

[MultiProvider](src/runtime/providers/multi.py) chooses a provider/model using task classification and fallback. This is distinct from the eleven-stage RoutingPipeline; `/chat` calls MultiProvider directly.

## Native and desktop layers

- [Python machine runtime](src/runtime/machine/): bytecode/IR utilities, stack VM, native interop, and x86 code generation.
- [native/](native/): NASM sources and C dispatcher.
- [ide/CMakeLists.txt](ide/CMakeLists.txt): native Windows C/C++ client.
- [ide/desktop/](ide/desktop/): Electron/TypeScript workbench sources with separate package scripts.
- [ide/beam/](ide/beam/): WebAssembly experiments.

These layers are not interchangeable implementations of one validated executable. See [IDE](docs/IDE.md) and [Machine runtime](docs/MACHINE_CODE.md).

## Models and research

[src/models/](src/models/) contains recurrent memory, BURT-IMMA, checkpoint/pruning helpers, and text output modules. [hf/](hf/) provides model packaging and corpus schema artifacts. [training/](training/) provides the Swift corpus/swarm visualization library.

[cobalt/](cobalt/), [kernels/](kernels/), [magma/](magma/), [narm/](narm/), and [catn/](catn/) use their own compiler and runtime assumptions. Formal sources and manuscripts are under [research/](research/). Source presence, formal assumptions, compilation, and measured behavior must be reported separately.

## Further reading

Use the [documentation index](docs/README.md) for starter and technical guides. [Security](docs/SECURITY.md) describes enforcement boundaries; [Validation](docs/VALIDATION.md) records the checks actually performed.