ANIMUS CORE //
Technical Architecture & Benchmark White Paper

1. Executive Architecture Overview

Animus Core is a low-latency telemetry and execution engine written in modern C++17, exposed to Python through a zero-copy nanobind bridge rather than a conventional serialize-and-copy interop layer. The design goal is narrow and specific: remove every avoidable cost between "an event exists in memory" and "a Python-side consumer can see it" — no heap allocation on the hot path, no serialization step, no lock contention on the transport itself.

Three architectural decisions carry most of that weight, and each is independently verifiable rather than asserted:

• →Cache-line-aligned payloads (alignas(64)) so that concurrent producers and consumers never invalidate each other's cache lines through unrelated data sharing the same line.
• →A lock-free MPMC ring buffer using per-slot sequence-number coordination (the Vyukov design), so producers and consumers each make progress via a single CAS on their own cursor, not a shared lock.
• →Invariant-TSC hardware cycle timing on the hot path instead of a system clock call, eliminating syscall/vDSO overhead from latency measurements themselves.

The sections below document each with the actual measurement methodology, not just the headline number — Section 6 gives the exact two commands to reproduce every number here on your own hardware.

2. 64-Byte Cache-Line Alignment & False-Sharing Elimination

Every event payload that crosses a producer/consumer boundary is declared alignas(64) and sized to exactly 64 bytes — one x86/ARM cache line, enforced at compile time via static_assert, not just documented:

struct alignas(64) Event {
    std::uint64_t sequence;
    std::uint64_t dispatch_tsc;
    std::uint32_t producer_id;
    std::uint32_t reserved0;
    std::uint64_t value;
    std::uint64_t reserved1[4];
};
static_assert(sizeof(Event) == 64, "Event must occupy exactly one cache line");
static_assert(alignof(Event) == 64, "Event must be cache-line aligned");

Alignment alone is a claim; the benchmark suite backs it with a direct A/B measurement. Two atomic counters are incremented by two threads pinned to distinct cores, once with both counters sharing a single cache line and once with each on its own line via alignas(64):

Speedup from eliminating false sharing: ~1.3x (representative run: 1.32x; range 1.3–1.35x across repeated runs), measured on the 24-thread development workstation described above — not a projected or theoretical figure. The speedup is computed and printed by the benchmark itself at runtime, not hardcoded. Run it yourself; the exact numbers will shift with core count and CPU generation, and that variance is expected, not a defect in the test.

3. Lock-Free MPMC Ring Buffer — Ingestion Throughput

The ring buffer is a bounded, lock-free, multi-producer/multi-consumer queue: every slot carries its own sequence number, so a producer or consumer coordinates with the specific slot it is about to touch rather than with one shared full/empty flag — allowing independent producers and consumers to make progress concurrently via a single compare-and-swap each.

Methodology: 8 producer threads, each pinned to a distinct logical core, concurrently enqueue into a ring pre-sized so it can never fill during the timed phase — a ~100-200ms burst, not a time-sustained measurement. Throughput is total events divided by wall-clock elapsed time. A separate, untimed correctness pass then drains the ring with 8 concurrent consumer threads and verifies an exact checksum over every event's payload — proving no event was lost, duplicated, or corrupted under contention, independent of the timing result.

The observed range spans both sides of the 16.5M target on the same machine, run to run. Investigated directly: system CPU load sampled immediately before each run showed no correlation with the outcome (the two lowest-load samples were still below target), ruling out ordinary background-process contention. The more likely explanation is the short ~100-200ms measurement window itself, sometimes catching the CPU package in a transient turbo-boost state and sometimes not. The correctness check is unconditional and has never failed across any run performed during this benchmark's validation.

4. Multi-Hour Soak & Reliability Verification

The 40-second sustained figure above establishes throughput; it does not establish that the engine holds correctness and its zero-allocation guarantee over the multi-hour, tens-of-billions-of-events duration a live production desk actually runs for. A separate, longer-duration soak run exists specifically to answer that — full interactive chronology in SOAK_TEST_AUDIT_REPORT.html.

Methodology: 8 producer + 8 consumer threads running simultaneously, compiled with -fsanitize=address -fsanitize=undefined rather than the clean -O3 build used above — this run is a memory-safety and correctness verification, not a peak-throughput citation, and its numbers should not be compared directly against the ~7.28M/sec clean-build figure without accounting for sanitizer overhead.

The 0–60 minute decline, explained rather than hidden: throughput opens at ~5.97M/sec and declines to ~5.16M/sec over the first hour before flattening. Two effects overlap: ASan/UBSan shadow-memory instrumentation is a constant throughput tax for the entire run (why the soak sits at 5.16M–5.9M/sec rather than the ~7.28M/sec clean-build figure), and the CPU package is likely still settling out of its initial turbo (PL2) state into its sustained (PL1) power limit — consistent with the curve's shape, though not independently confirmed with a temperature sensor during this run, and stated as inferred rather than measured. Correctness and heap-allocation counters stay flat across this exact window, which is what distinguishes a thermal/instrumentation effect from a code-level regression. The produced/consumed in-flight deficit also shrinks as a percentage over the steady-state window (0.0059% → 0.0022%) rather than growing — the signature that rules out a ring-buffer leak or consumer drain starvation, not just the exact zero-deficit figure at final completion in isolation.

5. Invariant-TSC Hardware Cycle Timing

Wall-clock timing calls (clock_gettime, QueryPerformanceCounter) cost real, measurable overhead on a latency budget measured in nanoseconds. Animus Core's timing primitives instead read the CPU's Time Stamp Counter directly via a serialized __rdtscp instruction:

• →Zero system calls, zero vDSO hops — a plain hardware register read.
• →Invariant-TSC verified at startup, not assumed: CPUID 0x80000007:EDX[8] is checked directly before any cycle-to-time conversion is trusted.
• →Calibrated, not guessed: cycles-per-nanosecond is measured by racing the TSC against std::chrono::steady_clock over a dedicated 200ms window at startup, rather than trusting an advertised base clock.

Measured cost of the read itself: ~10 ns per read, zero system calls, on a 2.4 GHz-class core — both the clock rate and the per-read cost are measured at runtime and printed, not hardcoded.

6. Zero-Copy Python Bridge (nanobind)

The Python-side consumption path is built on nanobind, exposing the ring buffer to Python as a TelemetryStream object whose drain() method pops events directly into a scratch buffer allocated once at construction — never in the hot loop — and returns an nb::ndarray view aliasing that same memory. Zero per-event Python objects are constructed; the entire batch crosses the language boundary as one array view.

Methodology: a background native producer thread feeds the ring unthrottled while the Python-side loop drains it continuously, timing only drain() itself with time.perf_counter_ns() — a concurrent, steady-state measurement, not a pre-filled-then-drained snapshot.

7. Bare-Metal Reproduction Protocol

Every number above should be treated as a claim until you've reproduced it on your own hardware. animus_sandbox/ is a standalone, dependency-free package built specifically for that: no dependency on the rest of the repository, and it ships its own build system.

make
./benchmark_harness

That's it. make builds with -O3 -march=native -std=c++17 -Wall -Wextra -Wpedantic (GCC/Clang); running the binary executes all three native measurements above and prints the results plainly, including whether your hardware met or missed the 16.5M+ pushes/sec target.

A CMake path (cmake -B build && cmake --build build --config Release) is also provided for cross-compiler builds and additionally builds the optional nanobind Python bridge module when a Python 3.8+ toolchain with nanobind installed is available, enabling reproduction of the Section 6 figure via python python_bridge_test.py. Full details in animus_sandbox/README.md.

The Section 4 multi-hour soak figures are reproduced separately via benchmarks/soak_test_engine.py driving animus_sandbox/soak_harness.cpp built with sanitizers — a multi-hour run, not part of this two-step quick check. See SOAK_TEST_AUDIT_REPORT.html for the full configuration.