feat(sovereign): implement the Memory-Mapped L3 'SovereignState' interlock structure

Engineered the hardware-enforced 64-byte boundary for the Sentinel/Spreader ecosystem. Forged institutional man pages and Chronicled Epoch 14 outlining the architecture shift from Daemons to Silicon Gates.

Author: quantDIY

.agent/skills/l3_sovereign_contract/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: L3 Sovereign Contract Architecture
+description: The Primary Lesson for building Hardware-Enforced Logic Gates via Memory-Mapped L3 Cache Interlocks inside QuanuX.
+---
+
+# The L3 Sovereign Contract (Primary Lesson)
+
+## Concept
+Software is slow. Hardware is absolute. Standard architecture evaluates risk conditions using OS-scheduled threads communicating via condition variables, mutexes, or even ring buffers. At 59ns latency ranges, the act of evaluating risk introduces jitter that invalidates the edge.
+
+## Implementation: The SovereignState
+
+QuanuX introduces the `quanux::SovereignState` paradigm.
+1. **The Contract**: A strict `alignas(64)` C++ struct (`64 bytes`), designed to perfectly occupy exactly one physical line in the CPU L3 Cache.
+2. **The Components**:
+    *   `std::atomic<uint8_t> risk_interlock`: The hardware kill-switch. When `0`, the Spreader is active. When `1`, it is halted.
+    *   `telemetry_tap`: A tightly bounded circular buffer (e.g., `L3Snapshot telemetry_tap[3]`) bridging telemetry into the Visual Interface asynchronously without affecting the Execution Core.
+3. **The Governance**: Mapped via HugePages (or Intel RDT), the Spreader (Core 3) continuously reads the atomic bitmask (`CMP`). If the Sentinel (Core 5) flips the bit to `1`, the memory cache line synchronizes globally, and the Spreader halts instantly without OS context switching.
+
+## Rules of Engagement
+*   **Never modify the 64-byte structural boundary.** Padding must always be calculated (e.g., `uint8_t _pad[X]`) to guarantee `sizeof(SovereignState) == 64`.
+*   **Never block inside the Sentinel.** The Sentinel loop updates the L3 contract asynchronously. Doing I/O (like `std::cout`) breaks deterministic scheduling.

QuanuX-Common/cpp/include/quanux/sovereign_state.hpp

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+
+namespace quanux {
+
+enum class ExecutionState : uint8_t {
+  IDLE = 0,
+  WORKING = 1,
+  PARTIAL = 2,
+  HEDGING = 3
+};
+
+// 16-byte packed snapshot representing the Level 3 Book Tap
+struct L3Snapshot {
+  float best_bid;
+  float best_ask;
+  float alpha;
+  uint32_t tsc_lo;
+};
+
+/**
+ * SovereignState: The Memory-Mapped L3 Hardware Contract
+ *
+ * Strict 64-byte alignment ensuring the Spreader (Core 3), Sentinel (Core 5),
+ * and Clerk (Core 7) can synchronize risk interlocking and telemetry taps
+ * globally across the CPU cache in a single locked assembly cycle.
+ */
+struct alignas(64) SovereignState {
+  // 0 = Clear, 1 = Halt
+  std::atomic<uint8_t> risk_interlock;
+
+  // Core Execution State Sequence
+  std::atomic<ExecutionState> execution_state;
+
+  // Ring buffer head pointer for telemetry
+  std::atomic<uint8_t> tap_index;
+
+  // Explicit padding to securely bridge the 16-byte structural boundary
+  uint8_t _pad[13];
+
+  // Circular buffer acting as the visual flight recorder tap for UI ingestion
+  L3Snapshot telemetry_tap[3];
+};
+
+// Compiler-enforced hardware boundary assertions
+static_assert(sizeof(SovereignState) == 64,
+              "SovereignState MUST BE exactly 64 bytes (1 L3 Cache Line).");
+static_assert(alignof(SovereignState) == 64,
+              "SovereignState MUST BE correctly aligned to 64 bytes.");
+
+} // namespace quanux

docs/IMMORTAL_RATIONALE.md

@@ -97,4 +97,16 @@ The Pilot writes high-level Python logic within the GUI. The mutation fires dire
 
 By injecting the Strategy Forge into the exact same low-latency interface handling our precision telemetry, the ecosystem reaches its final form. We did not build another trading application; we established command and control over the architecture itself. 
 
+## Epoch 14: The Sovereign Sentinel
+
+The Odyssey shifted. We are no longer building apps; we are architecting silicon behavior. Standard software logic structures introduce unacceptable execution risks at 59ns latency environments.
+
+Enter the Sovereign Sentinel. 
+
+We established a "Hardware-Enforced Logic Gate" utilizing a 64-byte Memory-Mapped Interlock `SovereignState`. Mapped directly to a fixed segment of the L3 cache using strict HugePage pinning (or Intel RDT), this structural contract bridges Core 3 (The Spreader), Core 5 (The Sentinel), and Core 7 (The Clerk).
+
+The `risk_interlock` operates as an atomic bitmask (0 = Clear, 1 = Halt). It exists so precisely mapped in memory that the Spreader can execute a single `CMP` assembly instruction to verify risk status before unleashing packets—yielding near-zero runtime branching cost. Meanwhile, the bare-metal Sentinel loop on Core 5 passively updates this state based on algorithmic telemetry without ever requesting an interrupt syscall. 
+
+We moved from "daemons evaluating logic" to physical physics-driven state machines traversing an L3 bus line.
+
 **End of Rationale.**

docs/man/quanux-l3-tap.1

@@ -0,0 +1,16 @@
+.TH QUANUX-L3-TAP 1 "FEBRUARY 2026" "QuanuX Institutional" "QuanuX Manual Pages"
+.SH NAME
+quanux-l3-tap \- High-Fidelity Visual Flight Recorder
+.SH SYNOPSIS
+.B quanux-l3-tap
+[\fIOPTIONS\fR]
+.SH DESCRIPTION
+The
+.B quanux-l3-tap
+subsystem orchestrates the bridging of binary hardware telemetry into the Neural DOM. It listens passively to the `telemetry_tap` circular buffer running inside the \fBSovereignState\fR L3 cache contract.
+
+By ingesting exact `L3Snapshot` packets containing Bids, Asks, Alpha strings, and raw TSC timestamps, the tap bypasses software simulation and presents the immutable visual representation of what the C++ kernel consumed precisely when an execution was fired.
+.SH USAGE
+This tap natively routes the telemetry payload through a Rust Tauri adapter. Run the desktop cockpit to enable visual output against the React DOM.
+.SH AUTHORS
+Built by the QuanuX Foundation.

docs/man/quanux-sovereign.1

@@ -0,0 +1,21 @@
+.TH QUANUX-SOVEREIGN 1 "FEBRUARY 2026" "QuanuX Institutional" "QuanuX Manual Pages"
+.SH NAME
+quanux-sovereign \- Hardware-Enforced Risk Management Gate
+.SH SYNOPSIS
+.B quanux-sovereign
+[\fIOPTIONS\fR]
+.SH DESCRIPTION
+The
+.B quanux-sovereign
+daemon represents the "Adult in the Room" for the QuanuX Distributed Execution framework. Running strictly as a bare-metal C++ loop on an isolated core (ordinarily Core 5), the Sentinel possesses unilateral authority over the L3 Cache \fBSovereignState\fR.
+
+It enforces the fundamental risk guardrails of the trading strategy without relying on context switches or syscall routing, avoiding de-scheduling jitter.
+.SH HARDWARE CONTRACT
+The Sovereign Sentinel interacts directly with the 64-byte `quanux::SovereignState` struct mapped in the L3. It manages:
+.TP
+.BR risk_interlock
+An atomic uint8_t flag. If an anomaly is hit (Max Notional, Max Position, Stale Data via TSC delta), the Sentinel asserts this pin to \fB1\fR. In the next clock cycle, the Spreader (Core 3) will halt all inbound order executions.
+.SH ISOLATION
+The Sentinel is expressly forbidden from triggering \fBstd::cout\fR or interacting with the OS scheduler.
+.SH AUTHORS
+Built by the QuanuX Foundation.