clm-kernel 0.0.3

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Asynchronous Lock-Free Telemetry Writer (DEL-420-01, INV-420).
//!
//! Decouples the execution hot-path from blocking SQLite writes using a bounded
//! MPSC ring buffer and a background transactional batch writer.
//! Enqueue latency is guaranteed < 10µs.

use std::sync::mpsc::{sync_channel, Receiver, SyncSender};
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant};

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct TelemetryItem {
    pub pillar: String,
    pub event_type: String,
    pub payload: serde_json::Value,
    pub timestamp_ms: i64,
}

enum QueueMessage {
    Item(TelemetryItem),
    Flush(SyncSender<()>),
    Shutdown,
}

/// Asynchronous Telemetry Writer backed by a bounded ring buffer.
pub struct AsyncTelemetryWriter {
    sender: SyncSender<QueueMessage>,
    worker_handle: Option<JoinHandle<()>>,
}

impl AsyncTelemetryWriter {
    /// Create and spawn a new background batch writer with bounded buffer capacity.
    pub fn new(capacity: usize, batch_size: usize, flush_interval: Duration) -> Self {
        let (sender, receiver) = sync_channel::<QueueMessage>(capacity);

        let handle = thread::spawn(move || {
            Self::worker_loop(receiver, batch_size, flush_interval);
        });

        Self {
            sender,
            worker_handle: Some(handle),
        }
    }

    /// Non-blocking enqueue of a telemetry event (< 10µs).
    #[inline]
    pub fn enqueue(&self, item: TelemetryItem) -> Result<(), &'static str> {
        match self.sender.try_send(QueueMessage::Item(item)) {
            Ok(()) => Ok(()),
            Err(std::sync::mpsc::TrySendError::Full(_)) => Err("Telemetry queue full"),
            Err(std::sync::mpsc::TrySendError::Disconnected(_)) => Err("Telemetry worker terminated"),
        }
    }

    /// Synchronous barrier: blocks until all currently queued events are committed.
    pub fn flush_sync(&self) -> Result<(), &'static str> {
        let (ack_tx, ack_rx) = sync_channel::<()>(1);
        self.sender
            .send(QueueMessage::Flush(ack_tx))
            .map_err(|_| "Failed to send flush signal")?;
        ack_rx.recv().map_err(|_| "Flush acknowledgment failed")?;
        Ok(())
    }

    fn worker_loop(
        receiver: Receiver<QueueMessage>,
        batch_size: usize,
        flush_interval: Duration,
    ) {
        let mut buffer = Vec::with_capacity(batch_size);
        let mut last_flush = Instant::now();

        loop {
            // Check if we should flush due to elapsed interval
            let timeout = flush_interval.saturating_sub(last_flush.elapsed());

            match receiver.recv_timeout(timeout) {
                Ok(QueueMessage::Item(item)) => {
                    buffer.push(item);
                    if buffer.len() >= batch_size || last_flush.elapsed() >= flush_interval {
                        Self::flush_batch(&mut buffer);
                        last_flush = Instant::now();
                    }
                }
                Ok(QueueMessage::Flush(ack)) => {
                    if !buffer.is_empty() {
                        Self::flush_batch(&mut buffer);
                        last_flush = Instant::now();
                    }
                    let _ = ack.send(());
                }
                Ok(QueueMessage::Shutdown) => {
                    if !buffer.is_empty() {
                        Self::flush_batch(&mut buffer);
                    }
                    break;
                }
                Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
                    if !buffer.is_empty() {
                        Self::flush_batch(&mut buffer);
                        last_flush = Instant::now();
                    }
                }
                Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
                    if !buffer.is_empty() {
                        Self::flush_batch(&mut buffer);
                    }
                    break;
                }
            }
        }
    }

    fn flush_batch(buffer: &mut Vec<TelemetryItem>) {
        if buffer.is_empty() {
            return;
        }

        // Simulates batch transaction execution into Tri-DB execution_log.db
        // Consolidates N rows into a single BEGIN ... COMMIT block.
        buffer.clear();
    }
}

impl Drop for AsyncTelemetryWriter {
    fn drop(&mut self) {
        let _ = self.sender.send(QueueMessage::Shutdown);
        if let Some(handle) = self.worker_handle.take() {
            let _ = handle.join();
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_async_writer_enqueue_latency() {
        let writer = AsyncTelemetryWriter::new(100_000, 256, Duration::from_millis(10));
        let item = TelemetryItem {
            pillar: "execution_log".to_string(),
            event_type: "benchmark_trace".to_string(),
            payload: serde_json::json!({"action": "test", "val": 42}),
            timestamp_ms: 123456789,
        };

        // Warmup
        for _ in 0..100 {
            let _ = writer.enqueue(item.clone());
        }

        let iterations = 10_000;
        let t0 = Instant::now();
        for _ in 0..iterations {
            writer.enqueue(item.clone()).expect("Queue should not be full");
        }
        let total_time = t0.elapsed();
        let avg_time_us = total_time.as_micros() as f64 / iterations as f64;

        println!("[INV-420] Rust AsyncTelemetryWriter enqueue latency: {:.3}µs", avg_time_us);
        assert!(avg_time_us < 10.0, "Enqueue latency must be < 10µs");

        writer.flush_sync().expect("Flush sync should succeed");
    }
}