docs: Batch 4+5 Doxygen — crypto, thrift, AI tier (21 headers)

Batch 4 (9 headers): aes_ctr, aes_core, aes_gcm, cipher_interface,
pme, key_metadata, post_quantum, thrift/compact, thrift/types.

Batch 5 (12 headers): event_bus, feature_reader, feature_writer,
mpmc_ring, quantized_vector, wal_mapped_segment, wal, column_batch,
streaming_sink, row_lineage, vector_type, tensor_bridge.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Johnson-Ogundeji

include/signet/ai/column_batch.hpp

@@ -20,6 +20,10 @@
 //
 // Phase 9b: MPMC ColumnBatch Event Bus.
 
+/// @file column_batch.hpp
+/// @brief Column-major batch of feature rows for zero-copy tensor wrapping
+///        and WAL serialization in ML inference pipelines.
+
 #pragma once
 
 #include "signet/error.hpp"
@@ -38,16 +42,17 @@
 
 namespace signet::forge {
 
-// Convenience alias
+/// Convenience alias for TensorDataType (shorter schema declarations).
 using TDT = TensorDataType;
 
 // ============================================================================
 // ColumnDesc — schema descriptor for one column in a ColumnBatch
 // ============================================================================
 
+/// Describes a single column in a ColumnBatch schema.
 struct ColumnDesc {
-    std::string    name;
-    TensorDataType dtype = TensorDataType::FLOAT64;  ///< physical storage type
+    std::string    name;                                  ///< Column name (e.g. "price", "volume")
+    TensorDataType dtype = TensorDataType::FLOAT64;       ///< Physical storage type (always stored as double internally)
 };
 
 // ============================================================================
@@ -57,17 +62,25 @@ struct ColumnDesc {
 // wrapping.  Each column is a contiguous std::vector<double>.
 // ============================================================================
 
+/// A column-major batch of feature rows for ML inference and WAL serialization.
+///
+/// Data is stored in column-major layout (columns_[col][row]) so each column
+/// is a contiguous double array suitable for zero-copy wrapping as a TensorView
+/// or ONNX OrtValue without transposition.
+///
+/// Typically shared across threads via SharedColumnBatch (std::shared_ptr).
+/// @see SharedColumnBatch, make_column_batch, EventBus
 class ColumnBatch {
 public:
     // -------------------------------------------------------------------------
     // Producer-side metadata (set before publishing)
     // -------------------------------------------------------------------------
 
-    std::string source_id;    ///< exchange / feed identifier
-    std::string symbol;       ///< instrument symbol
-    int64_t     seq_first  = 0;  ///< first WAL sequence in this batch
-    int64_t     seq_last   = 0;  ///< last WAL sequence in this batch
-    int64_t     created_ns = 0;  ///< batch creation timestamp (ns since epoch)
+    std::string source_id;       ///< Exchange / feed identifier
+    std::string symbol;          ///< Instrument symbol
+    int64_t     seq_first  = 0;  ///< First WAL sequence number in this batch
+    int64_t     seq_last   = 0;  ///< Last WAL sequence number in this batch
+    int64_t     created_ns = 0;  ///< Batch creation timestamp (ns since epoch)
 
     // -------------------------------------------------------------------------
     // Factory
@@ -92,11 +105,12 @@ class ColumnBatch {
         return b;
     }
 
+    /// Default constructor (empty batch, no schema).
     ColumnBatch() = default;
-    ColumnBatch(ColumnBatch&&) = default;
-    ColumnBatch& operator=(ColumnBatch&&) = default;
-    ColumnBatch(const ColumnBatch&) = default;
-    ColumnBatch& operator=(const ColumnBatch&) = default;
+    ColumnBatch(ColumnBatch&&) = default;            ///< Move constructor.
+    ColumnBatch& operator=(ColumnBatch&&) = default; ///< Move assignment.
+    ColumnBatch(const ColumnBatch&) = default;            ///< Copy constructor.
+    ColumnBatch& operator=(const ColumnBatch&) = default; ///< Copy assignment.
 
     // -------------------------------------------------------------------------
     // Build API — called from producer thread
@@ -115,11 +129,17 @@ class ColumnBatch {
         return expected<void>{};
     }
 
+    /// Append one row from an initializer list (e.g. `push_row({1.0, 2.0})`).
+    /// @param values Feature values (must match num_columns()).
+    /// @return Error on schema mismatch.
     [[nodiscard]] expected<void> push_row(std::initializer_list<double> values) {
         std::vector<double> tmp(values);
         return push_row(tmp.data(), tmp.size());
     }
 
+    /// Append one row from a vector.
+    /// @param values Feature values (must match num_columns()).
+    /// @return Error on schema mismatch.
     [[nodiscard]] expected<void> push_row(const std::vector<double>& values) {
         return push_row(values.data(), values.size());
     }
@@ -128,10 +148,14 @@ class ColumnBatch {
     // Query API — called from consumer / ML thread
     // -------------------------------------------------------------------------
 
+    /// Number of rows currently in the batch.
     [[nodiscard]] size_t num_rows()    const noexcept { return num_rows_; }
+    /// Number of columns defined by the schema.
     [[nodiscard]] size_t num_columns() const noexcept { return schema_.size(); }
+    /// True if the batch contains no rows.
     [[nodiscard]] bool   empty()       const noexcept { return num_rows_ == 0; }
 
+    /// The schema (column descriptors) this batch was created with.
     [[nodiscard]] const std::vector<ColumnDesc>& schema() const noexcept {
         return schema_;
     }
@@ -163,6 +187,13 @@ class ColumnBatch {
     // buffer.  output_dtype defaults to FLOAT32 for ONNX compatibility.
     // -------------------------------------------------------------------------
 
+    /// Assemble all columns into a single 2D [rows x cols] OwnedTensor.
+    ///
+    /// Uses BatchTensorBuilder internally. The default output type is FLOAT32
+    /// for direct ONNX Runtime consumption.
+    ///
+    /// @param output_dtype Desired element type (default FLOAT32).
+    /// @return OwnedTensor of shape {num_rows, num_columns}, or Error if empty.
     [[nodiscard]] expected<OwnedTensor> as_tensor(
             TensorDataType output_dtype = TensorDataType::FLOAT32) const {
 
@@ -191,6 +222,14 @@ class ColumnBatch {
     //   [float64 values × num_rows] × num_columns   (column-major)
     // -------------------------------------------------------------------------
 
+    /// Serialize the batch into a WAL StreamRecord.
+    ///
+    /// The binary payload uses little-endian column-major format. The default
+    /// type_id 0x434F4C42 ("COLB") identifies ColumnBatch records in the WAL.
+    ///
+    /// @param timestamp_ns Override timestamp (0 = use created_ns).
+    /// @param type_id      Record type tag for WAL routing.
+    /// @return StreamRecord with the serialized batch payload.
     [[nodiscard]] StreamRecord to_stream_record(
             int64_t  timestamp_ns = 0,
             uint32_t type_id      = 0x434F4C42u /*"COLB"*/) const {
@@ -241,6 +280,13 @@ class ColumnBatch {
     // Deserialise a StreamRecord payload back into a ColumnBatch
     // -------------------------------------------------------------------------
 
+    /// Deserialize a StreamRecord payload back into a ColumnBatch.
+    ///
+    /// Inverse of to_stream_record(). Reads the binary column-major format
+    /// and reconstructs the schema, columns, and row data.
+    ///
+    /// @param rec StreamRecord previously produced by to_stream_record().
+    /// @return Reconstructed ColumnBatch, or Error on truncated/corrupt payload.
     [[nodiscard]] static expected<ColumnBatch> from_stream_record(
             const StreamRecord& rec) {
 
@@ -299,11 +345,14 @@ class ColumnBatch {
     // Utility
     // -------------------------------------------------------------------------
 
+    /// Clear all row data while preserving the schema.
     void clear() {
         for (auto& col : columns_) col.clear();
         num_rows_ = 0;
     }
 
+    /// Pre-allocate storage for the given number of rows in each column.
+    /// @param rows Number of rows to reserve capacity for.
     void reserve(size_t rows) {
         for (auto& col : columns_) col.reserve(rows);
     }
@@ -318,6 +367,8 @@ class ColumnBatch {
 // SharedColumnBatch — the unit transferred between threads
 // ---------------------------------------------------------------------------
 
+/// Thread-safe shared pointer to a ColumnBatch -- the unit transferred
+/// between producer and consumer threads via EventBus.
 using SharedColumnBatch = std::shared_ptr<ColumnBatch>;
 
 /// Convenience factory: create a shared batch with a given schema.

include/signet/ai/event_bus.hpp

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Johnson Ogundeji
-// event_bus.hpp — Multi-tier event bus for SignetStack Signet Forge
+/// @file event_bus.hpp
+/// @brief Multi-tier event bus for routing SharedColumnBatch events through three tiers.
 //
 // Routes SharedColumnBatch events through three tiers:
 //
@@ -57,6 +58,12 @@ namespace signet::forge {
 // EventBusOptions — defined outside EventBus for Apple Clang compat
 // ============================================================================
 
+/// Configuration options for EventBus.
+///
+/// Defined at namespace scope (not nested in EventBus) to work around an
+/// Apple Clang restriction on default member initializers in nested aggregates.
+///
+/// @see EventBus
 struct EventBusOptions {
     size_t tier2_capacity = 4096;   ///< Tier-2 MPMC ring capacity (power-of-2)
     size_t tier1_capacity = 256;    ///< Default capacity for make_channel()
@@ -67,27 +74,42 @@ struct EventBusOptions {
 // EventBus — multi-tier SharedColumnBatch router
 // ============================================================================
 
+/// Multi-tier event bus for routing SharedColumnBatch events.
+///
+/// Routes batches through three tiers:
+///   - **Tier 1** -- SPSC dedicated channels (sub-us, one per producer-consumer pair).
+///   - **Tier 2** -- MPMC shared pool (us, N producers to M worker threads).
+///   - **Tier 3** -- WAL / StreamingSink (ms, async durable logging).
+///
+/// The bus is non-copyable and non-movable due to its internal mutex.
+/// Wrap in `std::unique_ptr<EventBus>` if heap allocation is needed.
+///
+/// @see EventBusOptions, MpmcRing, StreamingSink
 class EventBus {
 public:
+    /// Alias for the options struct.
     using Options = EventBusOptions;
 
     // -------------------------------------------------------------------------
     // Channel — Tier-1 dedicated MpmcRing used as SPSC
     // -------------------------------------------------------------------------
 
+    /// Tier-1 dedicated channel type (MpmcRing used as SPSC when single-writer).
     using Channel = MpmcRing<SharedColumnBatch>;
 
     // -------------------------------------------------------------------------
     // Construction
     // -------------------------------------------------------------------------
 
+    /// Construct an EventBus with the given options.
+    /// @param opts  Configuration controlling tier capacities and Tier-3 enablement.
     explicit EventBus(Options opts = {})
         : opts_(opts)
         , tier2_(std::make_unique<MpmcRing<SharedColumnBatch>>(
                      opts.tier2_capacity)) {}
 
-    EventBus(EventBus&&) = delete;
-    EventBus& operator=(EventBus&&) = delete;
+    EventBus(EventBus&&) = delete;            ///< Non-movable (contains mutex).
+    EventBus& operator=(EventBus&&) = delete; ///< Non-movable (contains mutex).
     EventBus(const EventBus&) = delete;
     EventBus& operator=(const EventBus&) = delete;
     ~EventBus() = default;
@@ -113,7 +135,9 @@ class EventBus {
         return ch;
     }
 
-    /// Look up an existing channel; returns nullptr if not found.
+    /// Look up an existing channel by name.
+    /// @param name  Logical channel identifier.
+    /// @return Shared pointer to the channel, or nullptr if not found.
     [[nodiscard]] std::shared_ptr<Channel> channel(
             const std::string& name) const {
         std::lock_guard<std::mutex> lk(channels_mutex_);
@@ -129,7 +153,8 @@ class EventBus {
     ///
     /// Also forwards to Tier-3 sink (if attached and opts_.enable_tier3).
     ///
-    /// Returns false if the Tier-2 ring is full (caller may retry or drop).
+    /// @param batch  The column batch to publish (moved into the ring).
+    /// @return true on success; false if the Tier-2 ring is full (caller may retry or drop).
     bool publish(SharedColumnBatch batch) {
         // Tier 3 first (cheap shared_ptr copy, async submit)
         if (opts_.enable_tier3 && sink_) {
@@ -147,8 +172,9 @@ class EventBus {
         return true;
     }
 
-    /// Pop from the shared Tier-2 ring (for worker threads).
-    /// Returns false if the ring is empty (caller should back off / yield).
+    /// Pop a batch from the shared Tier-2 ring (for worker threads).
+    /// @param out  Receives the popped batch on success.
+    /// @return true if a batch was popped; false if the ring is empty (caller should back off / yield).
     bool pop(SharedColumnBatch& out) {
         return tier2_->pop(out);
     }
@@ -158,15 +184,21 @@ class EventBus {
     // =========================================================================
 
     /// Attach a StreamingSink for Tier-3 durable logging.
+    ///
     /// The bus does NOT take ownership; the sink must outlive the bus.
+    ///
+    /// @param sink  Pointer to an externally owned StreamingSink.
     void attach_sink(StreamingSink* sink) {
         sink_ = sink;
     }
 
+    /// Detach the currently attached Tier-3 sink (no-op if none attached).
     void detach_sink() {
         sink_ = nullptr;
     }
 
+    /// Check whether a Tier-3 StreamingSink is currently attached.
+    /// @return true if a sink is attached.
     [[nodiscard]] bool has_sink() const noexcept {
         return sink_ != nullptr;
     }
@@ -175,12 +207,15 @@ class EventBus {
     // Stats
     // =========================================================================
 
+    /// Snapshot of cumulative event bus counters.
     struct Stats {
-        uint64_t published   = 0;
-        uint64_t dropped     = 0;   ///< Tier-2 ring full
-        uint64_t tier3_drops = 0;   ///< Tier-3 sink full / not attached
+        uint64_t published   = 0;   ///< Total batches successfully enqueued to Tier-2.
+        uint64_t dropped     = 0;   ///< Batches dropped because the Tier-2 ring was full.
+        uint64_t tier3_drops = 0;   ///< Batches dropped at the Tier-3 sink (full or not attached).
     };
 
+    /// Return a snapshot of the cumulative event bus statistics.
+    /// @return Stats struct with relaxed-order atomic reads.
     [[nodiscard]] Stats stats() const noexcept {
         return Stats{
             published_.load(std::memory_order_relaxed),
@@ -189,6 +224,7 @@ class EventBus {
         };
     }
 
+    /// Reset all counters to zero.
     void reset_stats() noexcept {
         published_.store(0, std::memory_order_relaxed);
         dropped_.store(0, std::memory_order_relaxed);
@@ -199,8 +235,11 @@ class EventBus {
     // Introspection
     // =========================================================================
 
+    /// Approximate number of batches currently in the Tier-2 ring.
     [[nodiscard]] size_t tier2_size()     const noexcept { return tier2_->size(); }
+    /// Capacity of the Tier-2 MPMC ring (power-of-two, set by EventBusOptions).
     [[nodiscard]] size_t tier2_capacity() const noexcept { return tier2_->capacity(); }
+    /// Number of named Tier-1 channels that have been created.
     [[nodiscard]] size_t num_channels()   const {
         std::lock_guard<std::mutex> lk(channels_mutex_);
         return channels_.size();