ANIMUS CORE SYSTEMS //
Technical Specification & Empirical Latency Evaluation

1. Executive Summary

On the critical execution path — order dispatch, tick ingestion, telemetry capture — the dominant latency cost is rarely the business logic itself. It is the serialization and IPC overhead surrounding it: marshalling a struct into a wire format, crossing a kernel syscall boundary, and copying the payload two to four times between producer and consumer. Conventional logging and messaging layers (synchronous file I/O, JSON/Protobuf encoding, socket-mediated queues) impose this cost on every single event, and that cost compounds directly into tail latency once thousands of events per second traverse the same path.

Animus Core removes that overhead structurally rather than optimizing around it: two zero-allocation, lock-free primitives placed directly in shared memory, one per delivery contract: animus::sys::ipc::BroadcastRing<T>, a lossy one-writer-to-many-readers ring for telemetry and market data whose writer never waits, and animus::sys::ipc::SpscQueue<T>, a lossless one-to-one queue for the execution and order path that refuses a push when full instead of overwriting. A producer writes a trivially-copyable record straight into a pre-sized slot — no heap allocation, no encode step, no syscall — and a consumer in a separate process reads that same memory directly. There is no wire format to parse because there is no wire; the struct layout in shared memory is the interchange format.

Measured on the reference configuration in Section 2, this architecture sustains a 30.3ns median (p50) per-event enqueue latency under a decoupled, non-blocking producer workload — see Section 3 for the full percentile distribution, methodology, and exact source citation; Section 4 for the separate MPMC/soak transport axis; and Section 5 for the integration surface.

2. Hardware & Reference System Configuration

The figures in Section 3 were produced by a real second OS process (not a mock, not an in-process simulation) on a GitHub Actions ubuntu-22.04 CI runner — run 33806378357. This is a shared cloud CI instance, not a dedicated, isolated bare-metal box, and that constraint is disclosed below exactly as it stands rather than omitted.

Full production-tuning profile (server-class CPU, isolcpus/nohz_full, HugePages, NUMA pinning, locked performance governor) is applied to a client's own hardware during Week 3 of an institutional pilot engagement — not asserted as already measured here. See BENCHMARK_DATASHEET.md §2.3 for that profile in full.

3. Empirical Benchmark Data

Per-event enqueue latency, decoupled/non-blocking overwrite mode, 10,000,000 synthetic ExecutionEvent records. The Animus Core Engine rows below are measured directly on the reference configuration in Section 2 (the first on the earlier ShmRing overwrite path, the second a 2026-10-01 re-run on the shipped BroadcastRing, 10,000,000 events, max observed 204,291 ns, same hosted-runner class but not the same machine) — source: AnimusCore_v1/BENCHMARKS.md, Phase 29. The Legacy Logging (spdlog) and Standard Async Ring rows are representative industry baselines for a synchronous file-backed logger and a typical allocating/lock-based async queue respectively — illustrative of the class of transport, not a measurement of a specific third-party deployment on this hardware.

Read the tail honestly: P99.9 is 2,695.2ns, not a smaller number — because CPU isolation was not applied on this run (Section 2), the reference host's own OS scheduling produces occasional tail outliers (max observed: 32,470.5 ns across 10M events) that a genuinely isolated core would suppress. That gap is disclosed here rather than rounded away, and closing it is exactly what the Week 3 isolation pass in a paid pilot is for. Reproduce these exact numbers: g++ -std=c++17 -O3 -march=x86-64-v3 -Iinclude benchmarks/harness_benchmark.cpp -o harness_benchmark -lpthread && ./harness_benchmark --events 10000000 --mode overwrite.

4. MPMC Throughput & Multi-Hour Soak Verification

A separate transport axis from Sections 2–3's shared-memory rings: animus::LockFreeRingBuffer<T>, a lock-free multi-producer/multi-consumer (MPMC) ring, under real 8-producer/8-consumer contention and a multi-hour continuous soak run. Source: AnimusCore_v1/BENCHMARKS.md · full soak chronology: SOAK_TEST_AUDIT_REPORT.html.

Test hardware: Intel Core i7-14650HX — 16 cores / 24 logical threads (8 Performance-cores w/ Hyper-Threading + 8 Efficiency-cores, confirmed by per-core isolation probe rather than vendor spec alone). 64-byte cache-line isolation (alignas(64)) on producer/consumer cursors, measured at a 4.55x throughput gain (4.21x–4.99x across 5 A/B runs) over an unpadded, false-sharing layout.

The 8-producer push-rate row measures producer-side enqueue speed alone, ring pre-sized so nothing drains during the ~100–200ms timed window — it is not a single-producer figure (all 8 producer threads are active) and not representative of sustained production load; the bimodal 13.5M–21.4M range is traced to the short window sometimes catching a transient CPU turbo-boost (PL2) state. For any citation of throughput under real producer+consumer load, use the ~7.28M/sec sustained figure — a single test session (one run, four samples), a strong first data point pending a second machine and a longer window before treating it as final.

The soak run is compiled with -fsanitize=address -fsanitize=undefined rather than the clean -O3 build used for the sustained figure above — a memory-safety and correctness verification, not a peak-throughput citation. It ran to completion and printed its final tally with no ASan/UBSan abort; a sanitizer build terminates immediately on a detected violation, so a clean run to completion is the sanitizer's own attestation that none occurred. The 5.16M–5.33M/s floor reflects that constant sanitizer shadow-memory tax, not the clean-build ~7.28M/s figure.

5. Hot-Path Integration Blueprint

The producer-side integration is two steps: create and initialise the ring once at startup, then call publish() on the hot path. It never allocates, never blocks, and never refuses a write — the writer does not know its readers exist, and a reader that falls more than capacity - 1 records behind detects it, counts the loss itself and snaps forward, instead of applying backpressure to the writer. For the execution path, SpscQueue<T> offers the opposite contract: try_push() returns false on a full queue and nothing is ever overwritten. This is the real API surface from include/animus/broadcast_ring.hpp, include/animus/spsc_queue.hpp and include/animus/execution_event.hpp, not a simplified pseudocode stand-in.

// One-time setup: a 40-byte, trivially-copyable wire record and a lossy
// broadcast ring placed directly in shared memory (no OS calls in the ring itself).
#include "animus/broadcast_ring.hpp"
#include "animus/shm_ipc.hpp"           // SharedMemoryRegion
#include "animus/execution_event.hpp"

using animus::ExecutionEvent;
using animus::sys::ipc::BroadcastRing;
using animus::sys::ipc::SharedMemoryRegion;

constexpr size_t kCapacity = 4096;              // power of two; newest kCapacity - 1 records readable
SharedMemoryRegion region;
BroadcastRing<ExecutionEvent> ring;
SharedMemoryRegion::create("animus_telemetry", BroadcastRing<ExecutionEvent>::required_bytes(kCapacity), region);
BroadcastRing<ExecutionEvent>::init(region.data(), region.size(), kCapacity, ring);

// Hot path: zero heap allocation, never blocks, never refuses a write.
void record_execution_event(uint64_t seq, int64_t price_ticks, int64_t qty, uint32_t instrument_id) {
    ExecutionEvent evt{};
    evt.sequence        = seq;
    evt.dispatch_ts_raw = __rdtsc();          // serialized read, see Section 2
    evt.price_ticks     = price_ticks;
    evt.quantity        = qty;
    evt.instrument_id   = instrument_id;

    ring.publish(evt);                        // non-blocking; the writer never waits on any reader
}

// Loss is counted by each reader, in its own memory — the writer cannot know
// what any one reader missed. A reader attaches, polls, and reads its own drop count.

A consumer in a separate process — C++ via BroadcastRing<ExecutionEvent>::attach(), or Python via the nanobind binding in bindings/animus_shm_py.cpp — attaches to the same named segment and reads the identical struct layout with no decode step in between.

6. Institutional Pilot Verification Protocol

These are the same three steps we run to reproduce Section 3's numbers on a prospect's own hardware during pilot onboarding — nothing here depends on machinery you cannot see.

1. 01
   Build the harness from source

   Clone the eval kit and compile benchmarks/harness_benchmark.cpp against your own toolchain (no vendored binary): g++ -std=c++17 -O3 -march=native -Iinclude benchmarks/harness_benchmark.cpp -o harness_benchmark -lpthread.

2. 02
   Run the producer, attach the consumer

   Launch ./harness_benchmark --events 10000000 --mode overwrite and, for a full loss-accounting pass, attach eval_kit/scripts/verify_stream.py from a second, genuinely separate OS process before the run completes.

3. 03
   Cross-check sequence gaps against dropped_count()

   The consumer's observed sequence gaps must equal the producer's own dropped_count() exactly. Any mismatch is a real correctness finding, not a rounding difference — treat it as a stop-ship signal during your own pilot, the same way we do.

Institutional pilots run this same protocol on your own hardware profile (Section 2's "Recommended production deployment profile") under an executed evaluation agreement. See docs/operations_legal/PILOT_PROGRAM.md for the full three-week structure.