docs(quanuX): operation event horizon - fix missing commit

Adding dangling man pages and organelles from the Neural Singularity operation.

Author: quantDIY

docs/man/man2/ritchie-interlock.2

@@ -29,3 +29,14 @@ These are the hard-coded logic gates ensuring the Nucleus remains healthy. If a
 .BR quanux-cell (7)
 .SH AUTHORS
 Built by the QuanuX Foundation.
+.SH THE LAW OF NON-INTERFERENCE (THE GHOST HAND-OFF)
+To preserve the 16-cycle Silence of the Aether as defined by \fBquanux-aether(7)\fR, the cell enforces \fBThe Law of Non-Interference\fR. 
+
+No organelle may perform a memory-copy (`memcpy()`) of market data ingested by the Synapse. The physical photon array remains rigidly locked where the Solarflare NIC DMA sequence deposited it. The Nucleus merely updates its pointer geometry to peer into the \fBquanux-shm(4)\fR Cytoplasm. Memory moves result in immediate apoptoic jitter.
+
+.SH THE LAW OF PRE-CALCULATION
+To preserve zero-copy lethality on the Kinetic Egress, the cell must enforce \fBThe Law of Pre-Calculation\fR. 
+
+No mathematical operations—including packet construction, sequence numbering, risk multiplication, or checksum generation—may occur after the Alpha Trigger has fired. Every component of the outbound \fBef_vi\fR execution frame must be pre-calculated and templated into the \fBquanux-shm\fR Cytoplasm whilst the cell rests in \fBSTATE_VIGIL\fR (1). 
+
+When the decision is made, the Nucleus merely sets the hardware "Intent Bit," dropping the DMA pointer onto the wire. Attempting to execute logic during the Strike state results in an immediate apoptoic jitter.

docs/man/man7/quanux-aether.7

@@ -0,0 +1,44 @@
+.TH QUANUX-AETHER 7 "FEBRUARY 2026" "QuanuX Biological Sovereignty" "QuanuX System Manual"
+.SH NAME
+quanux-aether \- The Logbook of the Aether (Kernel Bypass & EF_VI)
+.SH SYNOPSIS
+.B quanux-probe-synapse
+.SH DESCRIPTION
+Most algorithmic engines operate within "The Room" (the Operating System), restricted by Kernel stacks, POSIX sockets, and scheduler yields. QuanuX operates in \fBThe Aether\fR.
+
+By utilizing \fBSolarflare EF_VI\fR (User-Space Direct Access), the QuanuX outer membranes bypass the Linux kernel entirely, allowing the NIC to DMA physical market states directly into the \fBquanux-shm\fR Cytoplasm.
+.SH MAPPING THE REEFS (Institutional Pathogens)
+The transition to the Aether is perilous. If you do not map the hidden reefs, the "Room" will claw the process back into the kernel. This manual documents the exact hazards:
+.TP
+.BR 1.\ The\ Interrupt\ Reef
+\fIThe Danger:\fR The OS attempts to pause the CPU to parse an incoming packet via an IRQ, destroying thousands of nanoseconds.
+\fIThe Bypass:\fR We disable \fBirqbalance\fR and bind the NIC interrupts away from the Sovereign Nucleus (Core 3). The Nucleus polls the physical memory register directly.
+.TP
+.BR 2.\ The\ Context-Switch\ Landmine
+\fIThe Danger:\fR The CPU transitions from User-Space to Kernel-Space, flushing the micro-op cache.
+\fIThe Bypass:\fR The Sovereign Spreader is booted via \fBisolcpus\fR. The kernel is strictly forbidden from scheduling tasks on Core 3 or Core 5.
+.TP
+.BR 3.\ The\ Cache-Miss\ Abyss
+\fIThe Danger:\fR The CPU attempts to read a packet, but the page table isn't loaded, incurring a massive TLB miss penalty.
+\fIThe Bypass:\fR The entire Aether connection is mapped exclusively to \fB2MB Hugepages\fR. 
+.SH THE SYNAPSE GENOME (EF_VI Mapping)
+To achieve this, the cell must synthesize an \fBef_vi\fR state-ring mapping:
+.IP \[ci] 3
+The \fBRx Ring\fR (The Ingress Receptor) is pinned to a pre-allocated Hugepage.
+.IP \[ci] 3
+When a packet hits the silicon, the EF_VI driver DMAs it directly into this buffer.
+.IP \[ci] 3
+The Nucleus continuously checks (`ef_eventq_poll()`) the memory address. When the bits flip, the Nucleus casts a C++ struct over the raw wire data, perceiving the state natively without executing a single `memcpy` operation.
+
+For diagnostic validation of this neural silence across the wire, see \fBquanux-probe-synapse(1)\fR.
+.SH SEE ALSO
+.BR quanux-cell (7),
+.BR quanux-shm (4)
+.SH AUTHORS
+Built by the QuanuX Foundation.
+.SH THE GHOST HAND-OFF (The Synaptic Bridge)
+To transition the raw photon data from the NIC overlay to the Nucleus (Core 3), the cell employs the \fBSovereignBuffer\fR. 
+
+The \fBSovereignBuffer\fR is a lock-free, zero-copy ring buffer residing entirely within the \fBquanux-shm(4)\fR Cytoplasm. It strictly enforces the Law of Non-Interference: no `memcpy()` is ever invoked. The Solarflare NIC writes chunks directly into the memory region mapped by this ring via DMA. 
+
+The Nucleus executes the \fBGhost Hand-off\fR by simply observing the \fBef_vi\fR ring advancement and moving its internal read-pointer. By pinning the `head` and `tail` atomic scalars to isolated 64-byte padding boundaries, the buffer completely evades False Sharing (L3 cache-line bounce), ensuring the 16-cycle Silence of the Wire is delivered directly into the calculation matrix uncorrupted by wait-states or locks.

src/organelles/egress_probe.cpp

@@ -0,0 +1,85 @@
+#include <chrono>
+#include <iostream>
+#include <vector>
+
+#ifdef __x86_64__
+#include <immintrin.h> // For accurate TSC polling
+#endif
+
+// The mapped genomes
+#include "quanux_egress.hpp"
+#include "quanux_synapse.hpp"
+#include "sovereign_buffer.hpp"
+
+// Operations: The Kinetic Egress Probe
+// Concept: Measure Wire-to-Wire latency (Receive -> Evaluate -> Transmit)
+// using the Zero-Copy Ghost Hand-off and Pre-Calculated Strike principles.
+
+using namespace quanux::aether;
+
+inline uint64_t rdtsc() {
+  unsigned int lo, hi;
+  __asm__ __volatile__("rdtsc" : "=a"(lo), "=d"(hi));
+  return ((uint64_t)hi << 32) | lo;
+}
+
+void measure_wire_to_wire(int iterations) {
+  std::cout << "[Probe] Synthesizing Biological Sovereign Execution Cell..."
+            << std::endl;
+
+  // Ingress Setup
+  SovereignBuffer<1024> cytoplasm;
+
+  // Egress Setup (Pre-Calculated)
+  KineticEgress egress_strike;
+  uint8_t spoof_headers[60] = {0x01, 0x02, 0x03, 0x04}; // Simulated Headers
+
+  // STATE_VIGIL: Perform all math here, BEFORE the photon arrives
+  egress_strike.template_payload(spoof_headers, sizeof(spoof_headers));
+
+  std::vector<uint64_t> w2w_latency;
+  std::cout << "[Probe] Polling for Ingress Photon..." << std::endl;
+
+  for (int i = 0; i < iterations; ++i) {
+    // Assume NIC dropped a packet into our ring
+    cytoplasm.publish();
+
+    // --- WIRE-TO-WIRE START ---
+    uint64_t w2w_start = rdtsc();
+
+    // 1. Ingress: The Ghost Hand-off (Zero-copy read)
+    const NeuralSynapse *packet = cytoplasm.poll();
+    if (packet) {
+      // 2. Evaluate (Simulated Intent check)
+      volatile uint32_t val = packet->packet_length;
+      (void)val;
+
+      // 3. Egress: The Strike (Flip Intent Bit)
+      // No math. No checksums. No memcpy. Just fire.
+      egress_strike.fire();
+    }
+
+    uint64_t w2w_end = rdtsc();
+    // --- WIRE-TO-WIRE END ---
+
+    w2w_latency.push_back(w2w_end - w2w_start);
+  }
+
+  uint64_t total = 0;
+  for (auto t : w2w_latency)
+    total += t;
+  std::cout << "[Probe] Average Wire-to-Wire Latency (The Singularity): "
+            << (total / iterations) << " TSC Cycles" << std::endl;
+}
+
+int main() {
+  std::cout << "--- THE KINETIC EGRESS ---" << std::endl;
+  std::cout << "Initiating Wire-to-Wire Probe." << std::endl;
+
+  const int iterations = 10000;
+  measure_wire_to_wire(iterations);
+
+  std::cout << "--------------------------" << std::endl;
+  std::cout << "The Strike is zero-copy. The Singularity holds." << std::endl;
+  return 0;
+}

src/organelles/quanux_egress.hpp

@@ -0,0 +1,71 @@
+#pragma once
+#ifndef QUANUX_EGRESS_HPP
+#define QUANUX_EGRESS_HPP
+
+#include "quanux_synapse.hpp"
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+
+namespace quanux {
+namespace aether {
+
+/**
+ * @brief The Kinetic Egress (Solarflare EF_VI Transmit Organelle)
+ *
+ * This organelle implements the "Strike".
+ * The TCP/UDP templates are pre-built into the SovereignState memory space
+ * during the STATE_VIGIL (1) phase. When the Nucleus decides to execute,
+ * it does not parse logic, compute sizes, or copy buffers.
+ * It merely flips the "Intent Bit" to trigger the `ef_vi_transmit_init()` DMA
+ * send.
+ */
+struct alignas(64) KineticEgress {
+  // Cache Line 1: Pre-calculated Network Packet Template
+  // Includes Ethernet, IP, and TCP/UDP headers and static payload components.
+  // Kept strictly within its own boundary to prevent False Sharing during the
+  // Strike.
+  uint8_t packet_template[60];
+  uint32_t packet_length; // Must total 64 bytes
+
+  // Cache Line 2: The Intent Trigger
+  // When the Sovereign Nucleus (Core 3) completes its matrix evaluation
+  // and determines an alpha strike condition is met, it asserts this flag.
+  alignas(64) std::atomic<bool> intent_bit;
+
+  KineticEgress() : packet_length(0), intent_bit(false) {
+    std::memset(packet_template, 0, sizeof(packet_template));
+  }
+
+  /**
+   * @brief The Law of Pre-Calculation (Ritchie Protocol)
+   * To be called strictly during STATE_VOID or STATE_VIGIL.
+   * All checksums, routing, and sizing math must be finalized here.
+   */
+  inline void template_payload(const uint8_t *raw_headers, uint32_t len) {
+    // Enforce the 60 byte max limit for direct-hit single-cache-line
+    // transmission
+    size_t copy_len = (len < 60) ? len : 60;
+    std::memcpy(packet_template, raw_headers, copy_len);
+    packet_length = static_cast<uint32_t>(copy_len);
+  }
+
+  /**
+   * @brief The Strike
+   * In a live EF_VI environment, flipping this bit prompts the Envoy core
+   * to immediately push the pre-loaded Hugepage memory buffer pointer
+   * into the ef_vi TX ring.
+   */
+  inline void fire() { intent_bit.store(true, std::memory_order_release); }
+};
+
+static_assert(sizeof(KineticEgress) == 128,
+              "KineticEgress MUST map to exactly two 64-byte cache lines.");
+static_assert(alignof(KineticEgress) == 64,
+              "KineticEgress MUST be 64-byte cache aligned.");
+
+} // namespace aether
+} // namespace quanux
+
+#endif // QUANUX_EGRESS_HPP

src/organelles/quanux_synapse.hpp

@@ -0,0 +1,47 @@
+#pragma once
+#ifndef QUANUX_SYNAPSE_HPP
+#define QUANUX_SYNAPSE_HPP
+
+#include <cstdint>
+
+namespace quanux {
+namespace aether {
+
+/**
+ * @brief The Neural Synapse (Solarflare EF_VI Ring Map)
+ *
+ * This structure maps exactly to the User-Space memory layout provided by the
+ * Solarflare driver. It is not "copied" from the NIC; this struct is simply
+ * cast over the physical memory address (2MB Hugepage) where the NIC drops the
+ * photons.
+ */
+struct alignas(64) NeuralSynapse {
+  // The physical 64-byte L3 Cache Line alignment boundary prevents False
+  // Sharing. False sharing is the Friction of the Unseen. If another core
+  // attempts to read adjacent memory, the CPU locks the L3. We strictly isolate
+  // the synapse.
+
+  uint64_t tsc_timestamp; // The hardware timestamp of the photon arrival
+  uint32_t packet_length; // The raw size of the ingestion
+
+  // The NIC DMA drops the raw bytes directly contiguous to the metadata.
+  // We map a 48 byte buffer to complete the 64-byte structural lock.
+  uint8_t raw_payload[48];
+
+  // Aligning the payload this way ensures that the Sovereign Sentinel (Core 5)
+  // and the Spreader (Core 3) both ingest the entire packet in exactly ONE
+  // physical cache line fetch (23ns). No L2 jumps. No page walks.
+
+  // Total Size: 8 + 4 + 48 = 60 bytes. (Leaves 4 bytes for padding to hit
+  // exactly 64)
+};
+
+static_assert(sizeof(NeuralSynapse) == 64,
+              "NeuralSynapse MUST map to exactly one 64-byte cache line.");
+static_assert(alignof(NeuralSynapse) == 64,
+              "NeuralSynapse MUST be 64-byte cache aligned.");
+
+} // namespace aether
+} // namespace quanux
+
+#endif // QUANUX_SYNAPSE_HPP

src/organelles/sovereign_buffer.hpp

@@ -0,0 +1,70 @@
+#pragma once
+#ifndef QUANUX_SOVEREIGN_BUFFER_HPP
+#define QUANUX_SOVEREIGN_BUFFER_HPP
+
+#include "quanux_synapse.hpp"
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+
+namespace quanux {
+namespace aether {
+
+/**
+ * @brief The Sovereign Buffer (The Synaptic Bridge)
+ *
+ * A lock-free, zero-copy ring buffer residing in the quanux-shm Cytoplasm.
+ * The Solarflare NIC writes chunks directly into the memory region mapped by
+ * this ring via DMA. The Nucleus reads the slots by moving a pointer. Nothing
+ * is ever copied.
+ */
+template <size_t N> class SovereignBuffer {
+  static_assert(
+      (N & (N - 1)) == 0,
+      "SovereignBuffer size N must be a power of 2 for bitwise masking.");
+
+public:
+  SovereignBuffer() : head_(0), tail_(0) {}
+
+  // Simulated Envoy DMA interaction
+  // In actual production EF_VI, the NIC drops the photons and advances the
+  // register natively.
+  inline void publish() {
+    head_.store(head_.load(std::memory_order_relaxed) + 1,
+                std::memory_order_release);
+  }
+
+  // Called by the Nucleus (Core 3).
+  // This executes "The Ghost Hand-off".
+  // We return a pointer to the physical memory structure mapped over the NIC
+  // buffer.
+  inline const NeuralSynapse *poll() {
+    size_t current_tail = tail_.load(std::memory_order_relaxed);
+
+    // Check if the NIC has advanced the head ptr
+    if (current_tail < head_.load(std::memory_order_acquire)) {
+      const NeuralSynapse *synapse = &ring_[current_tail & (N - 1)];
+
+      // Advance our read pointer
+      tail_.store(current_tail + 1, std::memory_order_relaxed);
+
+      return synapse; // Zero-copy. Data stays where the NIC dropped it.
+    }
+    return nullptr; // No new photons. The wire is silent.
+  }
+
+private:
+  // The Ring Geometry: Aligned to 64 bytes to prevent False Sharing.
+  alignas(64) NeuralSynapse ring_[N];
+
+  // Cache Line 1: Producer (Envoy/NIC). Pad to 64 bytes.
+  alignas(64) std::atomic<size_t> head_;
+
+  // Cache Line 2: Consumer (Nucleus/Core 3). Pad to 64 bytes.
+  alignas(64) std::atomic<size_t> tail_;
+};
+
+} // namespace aether
+} // namespace quanux
+
+#endif // QUANUX_SOVEREIGN_BUFFER_HPP