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

# quanuxctl risk: manage risk state and capital caps

> View global notional exposure, update daily caps, and force node re-hydration via NATS JetStream — all without interrupting live C++ execution threads.

`quanuxctl risk` gives you a stateless control surface over the QuanuX risk plane. It never connects directly to a database or interrupts live C++ execution threads via RPC. Instead, it communicates exclusively through the CNATS JetStream KV store, where the running `RiskKernel` instances on each node listen asynchronously for updates and apply them to their local RAM state without pausing the execution loop.

## Synopsis

```
quanuxctl risk <command> [arguments]
```

## The Sovereign Sentinel

Before exploring the commands, it helps to understand what you are controlling. Risk enforcement in QuanuX is handled by the **Sovereign Sentinel** — an independent C++ binary pinned to Core 5 of the execution CPU. The Sentinel runs a bare-metal loop with no OS context switching, enforcing risk rules via hardware cache operations at 11.33 nanoseconds.

The Sentinel enforces the following rules continuously:

| Rule                   | Trigger condition                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stale tick (drift)** | TSC heartbeat delta exceeds 3,000,000 cycles (\~1ms at 3GHz). Indicates stale market data.                                                                                   |
| **Notional breach**    | `abs_pos × best_bid` exceeds the configured hard cap (e.g., \$5M).                                                                                                           |
| **Order storm**        | `orders_fired` count climbs faster than the allocated burst per second.                                                                                                      |
| **Partial fill**       | `ExecutionState::PARTIAL` is registered. Sentinel replaces `max_position_limit_` with the exact executed quantity, allowing hedging exits but blocking further accumulation. |

When the Sentinel detects a violation, it asserts a `LOCK BTS` (Bit Test and Set) instruction on the `risk_interlock` byte in the shared L3 cache. The Spreader on Core 3 detects this within \~59ns and enters `STATE_HALT`.

<Warning>
  `STATE_HALT` is a terminal state initiated by hardware-level interlock. It cannot be overridden by software configuration. To recover, you must investigate the root cause of the Sentinel violation, resolve the position or data condition that triggered it, and restart the engine via `systemctl restart quanux-engine`.
</Warning>

## Commands

### `view-state`

Subscribes to the NATS JetStream KV store (Bucket: `RISK_STATE`) and returns the current real-time aggregated global notional exposure.

```bash theme={null}
quanuxctl risk view-state
```

This command reads `global.notional.exposure` from the KV store. It proves global state without locking any C++ hot-path memory or querying a database.

**Example:**

```bash theme={null}
$ quanuxctl risk view-state
```

### `update-cap`

Publishes a new daily notional cap limit to the NATS subject `quanux.control.risk.cap`. Running `RiskKernel` instances subscribe to this subject on asynchronous background threads and apply the new cap to their `daily_notional_cap_` variable without pausing the primary execution loop.

```bash theme={null}
quanuxctl risk update-cap <new_cap_value>
```

<ParamField path="new_cap_value" type="int64" required>
  The new daily notional cap as an `int64` implied 2-decimal scalar. Multiply the dollar value by 100 to express cents. For example, $1,000,000.00 is `100000000` and $25,000,000.00 is `2500000000`.
</ParamField>

**Example** — Set the global notional limit to \$25,000,000:

```bash theme={null}
quanuxctl risk update-cap 2500000000
```

<Note>
  Cap updates propagate to all active `RiskKernel` instances across the mesh asynchronously. There is no synchronous acknowledgement — the update is durable in JetStream and nodes will apply it when they process the message. Allow a few seconds before expecting the new cap to be reflected in `view-state`.
</Note>

### `force-hydrate`

Commands a specific node to drop its `is_hot_` flag to `false`, suspend local trading, perform a blocking thread read from the JetStream KV store to re-seed its RAM matrix, verify the SHA-256 hash of the global state, and then restore execution.

```bash theme={null}
quanuxctl risk force-hydrate <node_id>
```

<ParamField path="node_id" type="string" required>
  The target node identifier (e.g., `SFO-EXEC-01`, `LON-EXEC-02`). Node IDs correspond to the names in your QuanuX node inventory.
</ParamField>

Use `force-hydrate` in the following scenarios:

* After a STONITH fencing event, when a standby node has been promoted and needs to synchronize its local RAM matrix with the current global JetStream record before resuming live trading
* When you suspect a node's local risk state has drifted from the global consensus due to a network partition or restart

**Example** — Re-hydrate a newly promoted node in London after a STONITH event:

```bash theme={null}
quanuxctl risk force-hydrate LON-EXEC-02
```

## The Ritchie FSM states

The QuanuX execution engine is governed by the Ritchie Finite State Machine. Risk events transition the engine through these states:

| State            | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `STATE_VOID`     | Initial state. Engine has not yet received market data or confirmed connectivity.             |
| Running states   | Normal execution. The Sentinel continuously monitors the risk rules above.                    |
| `STATE_RECOVERY` | Transitional state. Engine encountered a recoverable condition and is re-synchronizing state. |
| `STATE_HALT`     | Terminal halted state. Triggered by a Sentinel violation. Trading is suspended entirely.      |

<Tip>
  You can observe FSM state transitions in real time by subscribing to the NATS mesh: `nats sub "quanux.telemetry.fsm.*"`. Every state change is published as a durable JetStream message for forensic reconstruction.
</Tip>

## Examples

<CodeGroup>
  ```bash Audit current risk state theme={null}
  $ quanuxctl risk view-state
  ```

  ```bash Update daily cap to $25M theme={null}
  $ quanuxctl risk update-cap 2500000000
  ```

  ```bash Re-hydrate a promoted standby node theme={null}
  $ quanuxctl risk force-hydrate LON-EXEC-02
  ```
</CodeGroup>

## Architecture note

The risk plane is intentionally severed from the execution plane at the hardware level. The Sentinel binary runs on Core 5. The Spreader runs on Core 3. They share state only through a 64-byte L3 cache "Dead Drop." No syscall, mutex, or OS scheduler is involved in the risk check itself — only a `LOCK BTS` assembly instruction that the Spreader detects within one L3 cache bus synchronization cycle. This is why the Sentinel cannot be disabled in software: it does not operate through software.