> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Circuit Breaker

> Three layers of automated safety: Rust CriticalityMonitor (15 indicators), Rust KillChain (6-phase incident response), and a Python daemon thread for portfolio-wide emergency stop.

The swarm has three independent safety mechanisms. None of them can be overridden by any LLM or strategic layer. If any one triggers, everything stops.

## Three Safety Layers

<CardGroup cols={3}>
  <Card title="CriticalityMonitor" icon="triangle-exclamation">
    **Compiled Rust.** 15 systemic risk indicators run every 60 seconds. When criticality exceeds the threshold, it triggers the KillChain and deploys the avalanche reserve.
  </Card>

  <Card title="KillChain" icon="skull-crossbones">
    **Compiled Rust + Python callbacks.** 6-phase automated incident response: detect, contain, preserve, diagnose, remediate, learn. Genome blacklisting prevents failed strategies from re-evolving.
  </Card>

  <Card title="Circuit Breaker" icon="shield-halved">
    **Python daemon thread.** No LLM. Reads engine metrics every 2 seconds. Emergency stop with no override path.
  </Card>
</CardGroup>

## CriticalityMonitor (Rust)

15 indicators computed from price series, volume data, and feed spreads:

| Indicator               | What It Detects                                       |
| ----------------------- | ----------------------------------------------------- |
| Correlation convergence | All assets moving together (diversification collapse) |
| Contagion score         | Stress spreading across markets                       |
| Hurst exponent          | Long-range dependence, trending vs mean-reverting     |
| Two-scale volatility    | Microstructure noise vs true volatility               |
| Market entropy          | Information content of price moves                    |
| Transfer entropy        | Causal information flow between markets               |
| VPIN                    | Volume-synchronized probability of informed trading   |
| Liquidity score         | Available depth across venues                         |
| Spread widening         | Bid-ask deterioration                                 |
| Amihud ratio            | Price impact per unit volume                          |
| BOCPD                   | Bayesian online changepoint detection                 |
| CUSUM                   | Cumulative sum control chart for regime breaks        |

```python theme={null}
# The CriticalityMonitor runs automatically in the Hive oversight loop
report = hive.criticality.compute_report(
    price_series={"BTC-YES": [0.65, 0.66, 0.64, ...]},
    volume_series={"BTC-YES": [1000, 1200, 800, ...]},
    feed_spreads={"BTC-YES": [0.01, 0.02, 0.01, ...]},
)

print(f"Overall criticality: {report.overall_score}")
print(f"Avalanche triggered: {report.overall_score > config.avalanche_deploy_threshold}")
```

When `overall_score` exceeds `avalanche_deploy_threshold` (default 0.30), the Hive deploys the avalanche reserve (15% of capital held back for exactly this scenario) and triggers the KillChain.

## KillChain (Rust + Python)

Six phases execute in sequence with Python callbacks at each step. Once triggered, all 6 phases run. The Hive can't suppress an incident or skip phases.

```python theme={null}
from horizon._horizon import Severity

# Register response handlers
hive.kill_chain.on_contain(lambda incident: pause_affected_agents(incident))
hive.kill_chain.on_preserve(lambda incident: snapshot_full_state(incident))
hive.kill_chain.on_diagnose(lambda incident: identify_root_cause(incident))
hive.kill_chain.on_remediate(lambda incident: kill_and_blacklist(incident))
hive.kill_chain.on_learn(lambda incident: record_for_evolution(incident))

# Manual trigger (or automatic via CriticalityMonitor)
hive.kill_chain.trigger(
    Severity.Sev1Critical,
    "portfolio_drawdown_15pct",
    ["agent-001", "agent-002"],
    pnl_impact=-15000.0,
)
```

| Phase         | Action                                                                      |
| ------------- | --------------------------------------------------------------------------- |
| **Detect**    | Identify the incident type and severity                                     |
| **Contain**   | Pause affected agents, halt new orders                                      |
| **Preserve**  | Snapshot full state for post-mortem                                         |
| **Diagnose**  | Identify root cause (which agent, which strategy)                           |
| **Remediate** | Kill responsible agents, blacklist their genomes                            |
| **Learn**     | Record the incident for evolutionary pressure (bad genomes can't re-evolve) |

Genome blacklisting is permanent. A strategy genome that caused a Sev1 incident will never be spawned again by the EvolutionEngine or AgentFactory.

## Circuit Breaker (Python Thread)

A daemon thread with no LLM involvement. Reads numbers from the engines, compares to hard limits, acts. No reasoning, no prompts, no exceptions.

### Why No LLM

An LLM might rationalize a losing position. Misinterpret drawdown as noise. Convince itself to override a limit. The circuit breaker doesn't reason. It compares two numbers. If `portfolio_drawdown > max_drawdown`, everything stops.

### How It Runs

A Python `threading.Thread` with `daemon=True`. Every 2 seconds:

1. Reads portfolio metrics from every engine.
2. Checks each metric against its limit.
3. If any check fails, triggers an emergency stop.
4. Publishes the result to the event bus.

| Check              | What It Reads                           | Limit                            | Action             |
| ------------------ | --------------------------------------- | -------------------------------- | ------------------ |
| Portfolio drawdown | Peak-to-trough P\&L across all engines  | `max_drawdown_pct` (default 20%) | Emergency stop all |
| Daily P\&L         | Sum of realized + unrealized P\&L today | Configurable                     | Pause all agents   |
| Per-agent capital  | Agent notional vs allocated capital     | 1x allocation                    | Pause that agent   |
| Stuck detection    | Time since last event from an agent     | 5 minutes                        | Flag as stuck      |

### Emergency Stop

When triggered:

1. Cancels every open order across every exchange.
2. Pauses all agents.
3. Publishes an event with the failing metric, value, and limit.
4. Only the human operator can restart.

## Where They Sit in the Stack

| Layer | Enforcer                  | What                                                                           | Override           |
| ----- | ------------------------- | ------------------------------------------------------------------------------ | ------------------ |
| 1     | Rust Engine               | 8-point risk pipeline: kill switch, bounds, limits, cap, drawdown, rate, dedup | No                 |
| 2     | SwarmCoordinator (Rust)   | Capital allocation per agent, fitness-weighted rebalancing                     | No                 |
| 3     | KillChain (Rust)          | 6-phase incident response with genome blacklisting                             | No                 |
| 4     | Circuit Breaker (Python)  | Portfolio drawdown, daily P\&L, stuck detection                                | No                 |
| 5     | AutonomyController (Rust) | Progressive trust gating on all Hive decisions                                 | Can't override 1-4 |

Each layer runs independently. If the KillChain misses something, the circuit breaker catches it. If the circuit breaker thread dies, the Rust engine's per-order risk pipeline still rejects every bad order.