Skip to main content

alec_ffi/
lib.rs

1// ALEC - Adaptive Lazy Evolving Compression
2// Copyright (c) 2025 David Martin Venti
3//
4// Dual-licensed under AGPL-3.0 and Commercial License.
5// See LICENSE file for details.
6
7//! C/C++ bindings for ALEC compression library
8//!
9//! This crate provides a C-compatible FFI layer for the ALEC compression
10//! library, enabling use from C/C++ firmware and embedded systems.
11//!
12//! # Safety
13//!
14//! All functions in this module use raw pointers.
15//! Callers must ensure:
16//! - Pointers are valid and non-null (unless documented otherwise)
17//! - Buffer sizes are accurate
18//! - Handles are not used after being freed
19//! - Thread safety is managed by the caller
20
21#![cfg_attr(not(feature = "std"), no_std)]
22#![allow(clippy::not_unsafe_ptr_arg_deref)]
23
24#[cfg(not(feature = "std"))]
25extern crate alloc;
26
27// Zephyr RTOS support: global allocator via k_malloc/k_free, no panic handler
28#[cfg(feature = "zephyr")]
29mod zephyr_support {
30    use core::alloc::{GlobalAlloc, Layout};
31
32    extern "C" {
33        // k_aligned_alloc is required instead of k_malloc because k_malloc
34        // returns 4-byte aligned memory on ARM. Rust types such as
35        // Vec<(u16, f64)> and BTreeMap nodes require 8-byte alignment;
36        // using k_malloc causes misaligned access (UB) on Cortex-M33.
37        fn k_aligned_alloc(align: usize, size: usize) -> *mut u8;
38        fn k_free(ptr: *mut u8);
39    }
40
41    struct ZephyrAllocator;
42
43    unsafe impl GlobalAlloc for ZephyrAllocator {
44        unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
45            unsafe { k_aligned_alloc(layout.align(), layout.size()) }
46        }
47
48        unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout) {
49            unsafe { k_free(ptr) }
50        }
51    }
52
53    #[global_allocator]
54    static ALLOCATOR: ZephyrAllocator = ZephyrAllocator;
55
56    /// No-op on Zephyr — heap is managed by the RTOS.
57    ///
58    /// Provided for API compatibility with bare-metal builds.
59    #[no_mangle]
60    pub extern "C" fn alec_heap_init() {
61        // Zephyr manages its own heap; nothing to do.
62    }
63
64    #[panic_handler]
65    fn panic(_: &core::panic::PanicInfo) -> ! {
66        loop {}
67    }
68}
69
70// Bare-metal support: global allocator and panic handler
71#[cfg(feature = "bare-metal")]
72mod bare_metal_support {
73    use embedded_alloc::LlffHeap as Heap;
74
75    #[global_allocator]
76    static HEAP: Heap = Heap::empty();
77
78    /// Initialize the heap allocator. Must be called before any alloc usage.
79    ///
80    /// # Safety
81    ///
82    /// Must be called exactly once, before any heap allocation.
83    #[no_mangle]
84    pub unsafe extern "C" fn alec_heap_init() {
85        const HEAP_SIZE: usize = 8192;
86        static mut HEAP_MEM: [u8; HEAP_SIZE] = [0; HEAP_SIZE];
87        unsafe {
88            HEAP.init(&raw mut HEAP_MEM as usize, HEAP_SIZE);
89        }
90    }
91
92    /// Initialize the heap allocator with a caller-provided buffer.
93    ///
94    /// Required on RTOSes (FreeRTOS, Milesight firmware) where the heap
95    /// region is managed by the integrator and must not be statically
96    /// embedded in the ALEC library itself.
97    ///
98    /// # Arguments
99    ///
100    /// * `buf` - Pointer to the start of the heap region. Must remain
101    ///   valid for the lifetime of the program. Must be non-NULL.
102    /// * `len` - Size of the heap region in bytes. Must be > 0.
103    ///
104    /// # Safety
105    ///
106    /// * Must be called exactly once, before any ALEC allocation.
107    /// * `buf` must point to `len` bytes of writable memory that stays
108    ///   valid for the lifetime of the process.
109    /// * This function must not be combined with `alec_heap_init()`.
110    /// * No-op if `buf` is NULL or `len == 0`.
111    #[no_mangle]
112    pub unsafe extern "C" fn alec_heap_init_with_buffer(buf: *mut u8, len: usize) {
113        if buf.is_null() || len == 0 {
114            return;
115        }
116        unsafe {
117            HEAP.init(buf as usize, len);
118        }
119    }
120
121    #[panic_handler]
122    fn panic(_info: &core::panic::PanicInfo) -> ! {
123        loop {}
124    }
125}
126
127#[cfg(not(feature = "std"))]
128use alloc::{boxed::Box, vec::Vec};
129
130use core::ffi::{c_char, CStr};
131use core::slice;
132#[cfg(feature = "std")]
133use std::path::Path;
134
135use alec::classifier::Classifier;
136use alec::context::{Context, ContextConfig};
137use alec::protocol::{ChannelInput, RawData};
138#[cfg(feature = "decoder")]
139use alec::Decoder;
140use alec::Encoder;
141
142/// Key used when `observe()`-ing channel `i` in a fixed-channel frame.
143/// Must match `Encoder::fixed_channel_source_id` — kept here because
144/// that helper is `pub(crate)` inside the `alec` crate.
145#[inline]
146fn fixed_channel_source_id(i: usize) -> u32 {
147    (i as u32) + 1
148}
149
150// ============================================================================
151// Default configuration values (also documented in AlecEncoderConfig)
152// ============================================================================
153
154/// Default history size per source (validated on 99-message EM500-CO2 dataset).
155pub const ALEC_DEFAULT_HISTORY_SIZE: u32 = 20;
156/// Default maximum number of patterns retained in the dictionary.
157pub const ALEC_DEFAULT_MAX_PATTERNS: u32 = 256;
158/// Default maximum memory budget for the context (bytes).
159pub const ALEC_DEFAULT_MAX_MEMORY_BYTES: u32 = 2048;
160/// Default keyframe interval (messages between forced Raw32 keyframes).
161pub const ALEC_DEFAULT_KEYFRAME_INTERVAL: u32 = 50;
162/// Default for smart-resync via LoRaWAN downlink.
163pub const ALEC_DEFAULT_SMART_RESYNC: bool = true;
164
165/// Default pre-warm channel count. `0` disables the pre-warm (legacy
166/// behaviour — first encode allocates per-channel state).
167pub const ALEC_DEFAULT_NUM_CHANNELS: u32 = 0;
168
169/// Runtime configuration for a new ALEC encoder.
170///
171/// Mirrors the Milesight-integration defaults (history=20,
172/// patterns=256, memory=2048B, keyframe=50, smart_resync=true).
173///
174/// Pass a NULL pointer to `alec_encoder_new_with_config` to use all
175/// defaults. Any numeric field set to 0 is replaced by its default, so
176/// callers can opt in to a single override while keeping the rest.
177/// `num_channels` is the only documented exception — `0` means "do not
178/// pre-warm" (legacy behaviour), any positive value activates the
179/// init-time pre-warm described below.
180#[repr(C)]
181#[derive(Debug, Clone, Copy)]
182pub struct AlecEncoderConfig {
183    /// Per-source history window size. Default: 20.
184    pub history_size: u32,
185    /// Maximum patterns retained in the context dictionary. Default: 256.
186    pub max_patterns: u32,
187    /// Maximum memory budget for the context in bytes. Default: 2048.
188    pub max_memory_bytes: u32,
189    /// Interval (in messages) between forced Raw32 keyframes. Default: 50.
190    /// Set to 0 to disable periodic keyframes.
191    pub keyframe_interval: u32,
192    /// If true, the encoder honours downlink-driven resync requests
193    /// (via `alec_force_keyframe`). Default: true.
194    pub smart_resync: bool,
195    /// **v1.3.9 addition.** Number of fixed channels to pre-allocate at
196    /// encoder-creation time. When > 0, `alec_encoder_new_with_config`
197    /// immediately allocates one `SourceStats` entry per channel (ids
198    /// `1..=num_channels`, matching the `fixed_channel_source_id`
199    /// convention), so the first call to `alec_encode_multi_fixed`
200    /// performs ZERO heap allocations.
201    ///
202    /// Set to the number of channels your firmware uses (5 for the
203    /// Milesight EM500-CO2). `0` disables the pre-warm and keeps the
204    /// pre-v1.3.9 behaviour — the first encode allocates on demand,
205    /// which can panic on heaps partially consumed between
206    /// `alec_encoder_new_with_config` and the first encode.
207    ///
208    /// Upper bound: 64 (matches `Encoder::encode_multi_fixed`'s
209    /// channel cap). Values above 64 are treated as 0.
210    pub num_channels: u32,
211}
212
213impl AlecEncoderConfig {
214    /// Return a config pre-populated with all Milesight defaults.
215    pub fn defaults() -> Self {
216        Self {
217            history_size: ALEC_DEFAULT_HISTORY_SIZE,
218            max_patterns: ALEC_DEFAULT_MAX_PATTERNS,
219            max_memory_bytes: ALEC_DEFAULT_MAX_MEMORY_BYTES,
220            keyframe_interval: ALEC_DEFAULT_KEYFRAME_INTERVAL,
221            smart_resync: ALEC_DEFAULT_SMART_RESYNC,
222            num_channels: ALEC_DEFAULT_NUM_CHANNELS,
223        }
224    }
225
226    /// Resolve the effective config, replacing any 0 numeric field by
227    /// its default. Numeric fields set to 0 are treated as "use default"
228    /// rather than "disable" — except `keyframe_interval` and
229    /// `num_channels`, where 0 is a legitimate value (disable keyframes
230    /// / disable the v1.3.9 pre-warm respectively).
231    fn resolved(self) -> Self {
232        let d = Self::defaults();
233        Self {
234            history_size: if self.history_size == 0 {
235                d.history_size
236            } else {
237                self.history_size
238            },
239            max_patterns: if self.max_patterns == 0 {
240                d.max_patterns
241            } else {
242                self.max_patterns
243            },
244            max_memory_bytes: if self.max_memory_bytes == 0 {
245                d.max_memory_bytes
246            } else {
247                self.max_memory_bytes
248            },
249            // keyframe_interval == 0 is a valid value (disabled), so keep as-is.
250            keyframe_interval: self.keyframe_interval,
251            smart_resync: self.smart_resync,
252            // num_channels == 0 means "no pre-warm" (legacy behaviour), keep as-is.
253            // Values above 64 (encode_multi_fixed's channel cap) are clamped to 0
254            // so the caller is not silently given an encoder that pre-warmed too
255            // many sources and then failed at encode time.
256            num_channels: if self.num_channels > 64 {
257                0
258            } else {
259                self.num_channels
260            },
261        }
262    }
263
264    /// Build an `alec::context::ContextConfig` from this FFI config.
265    fn to_context_config(self) -> ContextConfig {
266        let r = self.resolved();
267        ContextConfig {
268            history_size: r.history_size as usize,
269            max_patterns: r.max_patterns as usize,
270            max_memory: r.max_memory_bytes as usize,
271            ..ContextConfig::default()
272        }
273    }
274}
275
276/// Hash a C source_id string to a u32 for context keying.
277/// Returns 0 if the pointer is null.
278fn hash_source_id(source_id: *const c_char) -> u32 {
279    if source_id.is_null() {
280        return 0;
281    }
282    let bytes = unsafe { CStr::from_ptr(source_id) }.to_bytes();
283    // Map to 1..=127 so the source_id always encodes as a 1-byte varint.
284    // 0 is reserved for NULL / "no source".
285    (xxhash_rust::xxh64::xxh64(bytes, 0) % 127 + 1) as u32
286}
287
288/// Result codes for ALEC FFI functions
289#[repr(C)]
290#[derive(Debug, Clone, Copy, PartialEq, Eq)]
291pub enum AlecResult {
292    /// Operation completed successfully
293    Ok = 0,
294    /// Invalid input data provided
295    ErrorInvalidInput = 1,
296    /// Output buffer is too small
297    ErrorBufferTooSmall = 2,
298    /// Encoding operation failed
299    ErrorEncodingFailed = 3,
300    /// Decoding operation failed
301    ErrorDecodingFailed = 4,
302    /// Null pointer was provided
303    ErrorNullPointer = 5,
304    /// Invalid UTF-8 string
305    ErrorInvalidUtf8 = 6,
306    /// File I/O error
307    ErrorFileIo = 7,
308    /// Context version mismatch
309    ErrorVersionMismatch = 8,
310    /// Corrupt or malformed context-state data (bad magic, bad CRC,
311    /// truncated buffer, etc.). Produced by `alec_decoder_import_state`.
312    ErrorCorruptData = 9,
313}
314
315/// Opaque encoder handle
316///
317/// Created with `alec_encoder_new()`, freed with `alec_encoder_free()`.
318/// Do not access internal fields directly.
319pub struct AlecEncoder {
320    encoder: Encoder,
321    classifier: Classifier,
322    context: Context,
323    /// If set, the next encode call should emit a keyframe (Raw32 for all
324    /// channels). Consumed by the Bloc B/C fixed-channel encode path.
325    /// Plumbed here in Bloc A so downlink handlers can set the flag
326    /// immediately without waiting for the encode path to land.
327    force_keyframe_pending: bool,
328    /// Number of encoded messages since the last keyframe. Used by the
329    /// fixed-channel encode path (Bloc C) to trigger periodic keyframes.
330    #[allow(dead_code)] // Consumed by Bloc C keyframe mechanism.
331    messages_since_keyframe: u32,
332    /// Configured keyframe interval (0 disables periodic keyframes).
333    #[allow(dead_code)] // Consumed by Bloc C keyframe mechanism.
334    keyframe_interval: u32,
335    /// Honour downlink-driven resync.
336    smart_resync: bool,
337}
338
339/// Opaque decoder handle
340///
341/// Created with `alec_decoder_new()`, freed with `alec_decoder_free()`.
342/// Do not access internal fields directly.
343///
344/// Decoder FFI is only available when the `decoder` Cargo feature is
345/// enabled (default on hosted/server builds, off on `zephyr`/MCU builds).
346#[cfg(feature = "decoder")]
347pub struct AlecDecoder {
348    decoder: Decoder,
349    context: Context,
350    /// Header sequence number observed on the most recent multi-frame
351    /// decode (None if none has been decoded yet).
352    last_header_sequence: Option<u16>,
353    /// Number of missing frames detected on the most recent decode
354    /// (clipped to 255). 0 means no gap.
355    last_gap_size: u8,
356}
357
358// ============================================================================
359// Version and Utility Functions
360// ============================================================================
361
362/// Get the ALEC library version string
363///
364/// # Returns
365///
366/// A null-terminated string containing the version (e.g., "1.0.0").
367/// The returned pointer is valid for the lifetime of the program.
368///
369/// # Example (C)
370///
371/// ```c
372/// printf("ALEC version: %s\n", alec_version());
373/// ```
374#[no_mangle]
375pub extern "C" fn alec_version() -> *const c_char {
376    // Include null terminator
377    static VERSION: &[u8] = b"1.3.10\0";
378    VERSION.as_ptr() as *const c_char
379}
380
381/// Convert a result code to a human-readable string
382///
383/// # Arguments
384///
385/// * `result` - The result code to convert
386///
387/// # Returns
388///
389/// A null-terminated string describing the result.
390/// The returned pointer is valid for the lifetime of the program.
391#[no_mangle]
392pub extern "C" fn alec_result_to_string(result: AlecResult) -> *const c_char {
393    let msg: &'static [u8] = match result {
394        AlecResult::Ok => b"Success\0",
395        AlecResult::ErrorInvalidInput => b"Invalid input data\0",
396        AlecResult::ErrorBufferTooSmall => b"Output buffer too small\0",
397        AlecResult::ErrorEncodingFailed => b"Encoding failed\0",
398        AlecResult::ErrorDecodingFailed => b"Decoding failed\0",
399        AlecResult::ErrorNullPointer => b"Null pointer provided\0",
400        AlecResult::ErrorInvalidUtf8 => b"Invalid UTF-8 string\0",
401        AlecResult::ErrorFileIo => b"File I/O error\0",
402        AlecResult::ErrorVersionMismatch => b"Context version mismatch\0",
403        AlecResult::ErrorCorruptData => b"Corrupt or malformed context state\0",
404    };
405    msg.as_ptr() as *const c_char
406}
407
408// ============================================================================
409// Encoder Functions
410// ============================================================================
411
412/// Create a new ALEC encoder
413///
414/// # Returns
415///
416/// A pointer to a new encoder, or NULL on allocation failure.
417/// The encoder must be freed with `alec_encoder_free()` when no longer needed.
418///
419/// # Example (C)
420///
421/// ```c
422/// AlecEncoder* enc = alec_encoder_new();
423/// if (enc == NULL) {
424///     // Handle allocation failure
425/// }
426/// // ... use encoder ...
427/// alec_encoder_free(enc);
428/// ```
429#[no_mangle]
430pub extern "C" fn alec_encoder_new() -> *mut AlecEncoder {
431    let defaults = AlecEncoderConfig::defaults();
432    let encoder = Box::new(AlecEncoder {
433        encoder: Encoder::new(),
434        classifier: Classifier::default(),
435        context: Context::new(),
436        force_keyframe_pending: false,
437        messages_since_keyframe: 0,
438        keyframe_interval: defaults.keyframe_interval,
439        smart_resync: defaults.smart_resync,
440    });
441    Box::into_raw(encoder)
442}
443
444/// Create a new encoder with checksum enabled
445///
446/// # Returns
447///
448/// A pointer to a new encoder with checksum enabled, or NULL on failure.
449#[no_mangle]
450pub extern "C" fn alec_encoder_new_with_checksum() -> *mut AlecEncoder {
451    let defaults = AlecEncoderConfig::defaults();
452    let encoder = Box::new(AlecEncoder {
453        encoder: Encoder::with_checksum(),
454        classifier: Classifier::default(),
455        context: Context::new(),
456        force_keyframe_pending: false,
457        messages_since_keyframe: 0,
458        keyframe_interval: defaults.keyframe_interval,
459        smart_resync: defaults.smart_resync,
460    });
461    Box::into_raw(encoder)
462}
463
464/// Create a new ALEC encoder with a custom configuration.
465///
466/// Mirrors the Milesight integration requirements: the caller specifies
467/// `history_size`, `max_patterns`, `max_memory_bytes`, `keyframe_interval`,
468/// `smart_resync` and (v1.3.9+) `num_channels`. See `AlecEncoderConfig`
469/// for defaults.
470///
471/// # Arguments
472///
473/// * `config` - Pointer to an `AlecEncoderConfig`. If NULL, all defaults
474///   are used. Numeric fields set to 0 are replaced by their default
475///   (except `keyframe_interval`, where 0 disables periodic keyframes,
476///   and `num_channels`, where 0 disables the v1.3.9 pre-warm).
477///
478/// # v1.3.9 pre-warm
479///
480/// If `config.num_channels > 0`, one `SourceStats` entry is pre-allocated
481/// per channel (ids `1..=num_channels`) at encoder-creation time. This
482/// moves per-channel heap allocations out of the hot encode path and
483/// prevents OOM panics on MCUs with a partially-consumed heap at
484/// firmware init. Recommended for all fixed-channel MCU deployments.
485///
486/// # Returns
487///
488/// A pointer to a new encoder, or NULL on allocation failure.
489/// Must be freed with `alec_encoder_free()`.
490#[no_mangle]
491pub extern "C" fn alec_encoder_new_with_config(
492    config: *const AlecEncoderConfig,
493) -> *mut AlecEncoder {
494    let cfg = if config.is_null() {
495        AlecEncoderConfig::defaults()
496    } else {
497        unsafe { *config }.resolved()
498    };
499
500    let mut context = Context::with_config(cfg.to_context_config());
501
502    // v1.3.9 pre-warm: pre-allocate per-channel SourceStats so the
503    // first `alec_encode_multi_fixed` call performs ZERO heap
504    // allocation. Keys match `fixed_channel_source_id(i) = i + 1`.
505    // `resolved()` clamps `num_channels > 64` to 0, so we never
506    // over-allocate.
507    for i in 0..cfg.num_channels {
508        context.ensure_source_stats(i + 1);
509    }
510
511    let encoder = Box::new(AlecEncoder {
512        encoder: Encoder::new(),
513        classifier: Classifier::default(),
514        context,
515        force_keyframe_pending: false,
516        messages_since_keyframe: 0,
517        keyframe_interval: cfg.keyframe_interval,
518        smart_resync: cfg.smart_resync,
519    });
520    Box::into_raw(encoder)
521}
522
523/// Force the next encode call to emit a keyframe (Raw32 for all channels).
524///
525/// Intended to be called from a LoRaWAN downlink handler receiving the
526/// 0xFF resync command from the server-side sidecar. The keyframe is
527/// emitted by the next call to `alec_encode_multi_fixed`: marker 0xA2,
528/// Raw32 for every channel.
529///
530/// No-op if `encoder` is NULL or if the encoder was configured with
531/// `smart_resync = false`.
532///
533/// Most integrators will prefer the `alec_downlink_handler` wrapper,
534/// which parses a raw downlink payload and applies the right action.
535///
536/// # Arguments
537///
538/// * `encoder` - Encoder handle.
539#[no_mangle]
540pub extern "C" fn alec_force_keyframe(encoder: *mut AlecEncoder) {
541    if encoder.is_null() {
542        return;
543    }
544    let enc = unsafe { &mut *encoder };
545    if !enc.smart_resync {
546        return;
547    }
548    enc.force_keyframe_pending = true;
549}
550
551/// Parse a raw LoRaWAN downlink payload and apply the right action
552/// to the encoder.
553///
554/// This is a convenience wrapper over `alec_force_keyframe`. A single
555/// command byte is defined today:
556///
557/// - `0xFF` — "request immediate keyframe": the encoder's next
558///   `alec_encode_multi_fixed` call will emit marker `0xA2` and
559///   Raw32 for every channel.
560///
561/// Any other first byte is treated as an invalid command and the
562/// encoder state is left untouched. Additional bytes after byte 0
563/// are reserved for future commands and are currently ignored.
564///
565/// Worst-case drift after a packet loss:
566///
567/// - No smart resync (downlink disabled):
568///   `drift ≤ keyframe_interval × uplink_period`
569///   (e.g. 50 × 10 min ≈ 8 h at a 10-minute cadence).
570/// - With smart resync + downlink `0xFF`:
571///   `drift ≤ 1 × uplink_period` (next uplink is a keyframe).
572///
573/// # Arguments
574///
575/// * `encoder` - Encoder handle.
576/// * `data` - Downlink payload bytes (the raw LoRaWAN FRMPayload).
577/// * `len` - Length of `data` in bytes.
578///
579/// # Returns
580///
581/// * `ALEC_OK` if the downlink was a recognized command and was
582///   applied.
583/// * `ALEC_ERROR_NULL_POINTER` if `encoder` or `data` is NULL.
584/// * `ALEC_ERROR_INVALID_INPUT` for an empty payload or unknown
585///   command byte — encoder state is NOT modified.
586#[no_mangle]
587pub extern "C" fn alec_downlink_handler(
588    encoder: *mut AlecEncoder,
589    data: *const u8,
590    len: usize,
591) -> AlecResult {
592    if encoder.is_null() || data.is_null() {
593        return AlecResult::ErrorNullPointer;
594    }
595    if len == 0 {
596        return AlecResult::ErrorInvalidInput;
597    }
598    // SAFETY: caller promised `data` is valid for `len` bytes.
599    let cmd = unsafe { *data };
600    match cmd {
601        0xFF => {
602            alec_force_keyframe(encoder);
603            AlecResult::Ok
604        }
605        other => {
606            log::warn!(
607                "ALEC downlink: unknown command byte 0x{:02X} ({} byte payload, ignored)",
608                other,
609                len
610            );
611            AlecResult::ErrorInvalidInput
612        }
613    }
614}
615
616/// Free an encoder
617///
618/// # Arguments
619///
620/// * `encoder` - Encoder to free. May be NULL (no-op).
621///
622/// # Safety
623///
624/// The encoder must not be used after calling this function.
625#[no_mangle]
626pub extern "C" fn alec_encoder_free(encoder: *mut AlecEncoder) {
627    if !encoder.is_null() {
628        unsafe {
629            drop(Box::from_raw(encoder));
630        }
631    }
632}
633
634/// Encode a single floating-point value
635///
636/// # Arguments
637///
638/// * `encoder` - Encoder handle (must not be NULL)
639/// * `value` - The value to encode
640/// * `timestamp` - Timestamp for the value (can be 0 if not used)
641/// * `source_id` - Source identifier string (null-terminated, can be NULL)
642/// * `output` - Output buffer for encoded data
643/// * `output_capacity` - Size of output buffer in bytes
644/// * `output_len` - Pointer to store actual encoded length
645///
646/// # Returns
647///
648/// `ALEC_OK` on success, error code otherwise.
649#[no_mangle]
650pub extern "C" fn alec_encode_value(
651    encoder: *mut AlecEncoder,
652    value: f64,
653    timestamp: u64,
654    source_id: *const c_char,
655    output: *mut u8,
656    output_capacity: usize,
657    output_len: *mut usize,
658) -> AlecResult {
659    // Null checks
660    if encoder.is_null() || output.is_null() || output_len.is_null() {
661        return AlecResult::ErrorNullPointer;
662    }
663
664    let enc = unsafe { &mut *encoder };
665    let sid = hash_source_id(source_id);
666
667    // Create RawData with hashed source_id for per-channel context isolation
668    let raw_data = RawData::with_source(sid, value, timestamp);
669
670    // Classify the data
671    let classification = enc.classifier.classify(&raw_data, &enc.context);
672
673    // Encode the message
674    let message = enc.encoder.encode(&raw_data, &classification, &enc.context);
675
676    // Convert to bytes
677    let encoded = message.to_bytes();
678    if encoded.len() > output_capacity {
679        return AlecResult::ErrorBufferTooSmall;
680    }
681
682    let output_slice = unsafe { slice::from_raw_parts_mut(output, output_capacity) };
683    output_slice[..encoded.len()].copy_from_slice(&encoded);
684    unsafe {
685        *output_len = encoded.len();
686    }
687
688    // Observe the data for context learning
689    enc.context.observe(&raw_data);
690
691    AlecResult::Ok
692}
693
694/// Encode multiple values with adaptive per-channel compression.
695///
696/// Each channel is independently classified (P1–P5) and encoded using the
697/// optimal strategy (Repeated, Delta8, Delta16, etc.). P5 channels are
698/// excluded from the output frame but their context is still updated.
699///
700/// # Arguments
701///
702/// * `encoder` - Encoder handle
703/// * `values` - Array of f64 values to encode (one per channel)
704/// * `value_count` - Number of channels
705/// * `timestamps` - Per-channel timestamps (array of uint64_t), or NULL to
706///   use 0 for all channels
707/// * `source_ids` - Per-channel source identifier strings (array of
708///   `const char*`), or NULL for automatic index-based IDs
709/// * `priorities` - Per-channel priority overrides (1–5), or NULL for
710///   classifier-assigned priorities
711/// * `output` - Output buffer for encoded data
712/// * `output_capacity` - Size of output buffer in bytes
713/// * `output_len` - Pointer to store actual encoded length
714///
715/// # Returns
716///
717/// `ALEC_OK` on success, error code otherwise.
718#[no_mangle]
719pub extern "C" fn alec_encode_multi(
720    encoder: *mut AlecEncoder,
721    values: *const f64,
722    value_count: usize,
723    timestamps: *const u64,
724    source_ids: *const *const c_char,
725    priorities: *const u8,
726    output: *mut u8,
727    output_capacity: usize,
728    output_len: *mut usize,
729) -> AlecResult {
730    // Null checks
731    if encoder.is_null() || values.is_null() || output.is_null() || output_len.is_null() {
732        return AlecResult::ErrorNullPointer;
733    }
734
735    if value_count == 0 {
736        return AlecResult::ErrorInvalidInput;
737    }
738
739    let enc = unsafe { &mut *encoder };
740    let values_slice = unsafe { slice::from_raw_parts(values, value_count) };
741
742    // Build ChannelInput array
743    let channels: Vec<ChannelInput> = (0..value_count)
744        .map(|i| {
745            let sid = if source_ids.is_null() {
746                // Use index+1 as source_id (1-byte varint, non-zero)
747                (i as u32) + 1
748            } else {
749                let ptr = unsafe { *source_ids.add(i) };
750                hash_source_id(ptr)
751            };
752
753            ChannelInput {
754                name_id: i as u8,
755                source_id: sid,
756                value: values_slice[i],
757            }
758        })
759        .collect();
760
761    // Apply priority overrides if provided
762    let timestamp = if timestamps.is_null() {
763        0u64
764    } else {
765        // Use first timestamp for the shared header
766        unsafe { *timestamps }
767    };
768
769    // If priorities are provided, set critical thresholds to force classification.
770    // Otherwise let the classifier decide naturally.
771    // For now, we use the classifier and override priorities post-classification.
772    let (message, classifications) =
773        enc.encoder
774            .encode_multi_adaptive(&channels, timestamp, &enc.context, &enc.classifier);
775
776    // If explicit priorities were provided, we need to re-encode with those.
777    // However, the cleaner approach is to let the classifier work and use the
778    // priorities parameter as an override. Since encode_multi_adaptive already
779    // classified, and the user's priority is just a hint, we accept the
780    // classifier result. If the caller passes priorities != NULL, we could
781    // use them, but for v1.3 we trust the classifier.
782    let _ = priorities; // Reserved for future override support
783    let _ = classifications;
784
785    // Convert to bytes
786    let encoded = message.to_bytes();
787    if encoded.len() > output_capacity {
788        return AlecResult::ErrorBufferTooSmall;
789    }
790
791    let output_slice = unsafe { slice::from_raw_parts_mut(output, output_capacity) };
792    output_slice[..encoded.len()].copy_from_slice(&encoded);
793    unsafe {
794        *output_len = encoded.len();
795    }
796
797    // Observe ALL channels (including P5) for context learning.
798    // Use name_id as source_id — matches encode/decode convention for multi frames.
799    for ch in &channels {
800        let rd = RawData::with_source(ch.name_id as u32, ch.value, timestamp);
801        enc.context.observe(&rd);
802    }
803
804    AlecResult::Ok
805}
806
807/// Save encoder context to a file (for preload generation)
808///
809/// # Arguments
810///
811/// * `encoder` - Encoder handle
812/// * `path` - File path (null-terminated string)
813/// * `sensor_type` - Sensor type identifier (null-terminated string)
814///
815/// # Returns
816///
817/// `ALEC_OK` on success, error code otherwise.
818#[cfg(feature = "std")]
819#[no_mangle]
820pub extern "C" fn alec_encoder_save_context(
821    encoder: *mut AlecEncoder,
822    path: *const c_char,
823    sensor_type: *const c_char,
824) -> AlecResult {
825    if encoder.is_null() || path.is_null() || sensor_type.is_null() {
826        return AlecResult::ErrorNullPointer;
827    }
828
829    let enc = unsafe { &*encoder };
830
831    let path_str = match unsafe { CStr::from_ptr(path) }.to_str() {
832        Ok(s) => s,
833        Err(_) => return AlecResult::ErrorInvalidUtf8,
834    };
835
836    let sensor_type_str = match unsafe { CStr::from_ptr(sensor_type) }.to_str() {
837        Ok(s) => s,
838        Err(_) => return AlecResult::ErrorInvalidUtf8,
839    };
840
841    match enc
842        .context
843        .save_to_file(Path::new(path_str), sensor_type_str)
844    {
845        Ok(()) => AlecResult::Ok,
846        Err(_) => AlecResult::ErrorFileIo,
847    }
848}
849
850/// Load encoder context from a preload file
851///
852/// # Arguments
853///
854/// * `encoder` - Encoder handle
855/// * `path` - File path to preload (null-terminated string)
856///
857/// # Returns
858///
859/// `ALEC_OK` on success, error code otherwise.
860#[cfg(feature = "std")]
861#[no_mangle]
862pub extern "C" fn alec_encoder_load_context(
863    encoder: *mut AlecEncoder,
864    path: *const c_char,
865) -> AlecResult {
866    if encoder.is_null() || path.is_null() {
867        return AlecResult::ErrorNullPointer;
868    }
869
870    let enc = unsafe { &mut *encoder };
871
872    let path_str = match unsafe { CStr::from_ptr(path) }.to_str() {
873        Ok(s) => s,
874        Err(_) => return AlecResult::ErrorInvalidUtf8,
875    };
876
877    match Context::load_from_file(Path::new(path_str)) {
878        Ok(ctx) => {
879            enc.context = ctx;
880            AlecResult::Ok
881        }
882        Err(_) => AlecResult::ErrorFileIo,
883    }
884}
885
886/// Get the current context version
887///
888/// # Arguments
889///
890/// * `encoder` - Encoder handle
891///
892/// # Returns
893///
894/// The context version number, or 0 if encoder is NULL.
895#[no_mangle]
896pub extern "C" fn alec_encoder_context_version(encoder: *const AlecEncoder) -> u32 {
897    if encoder.is_null() {
898        return 0;
899    }
900    let enc = unsafe { &*encoder };
901    enc.context.context_version()
902}
903
904// ============================================================================
905// Encoder context save / load with RAM buffers (v1.3.7)
906//
907// Buffer-based mirror of alec_decoder_context_save / _context_load, callable
908// from MCUs that have no filesystem. In addition to the Context payload
909// (predictions, patterns, dictionary — reused from the decoder's ALCS
910// serialization), the encoder blob also carries the runtime state needed
911// to roll back a discarded frame exactly: the encoder sequence counter,
912// the pending force-keyframe flag and messages-since-last-keyframe.
913//
914// Wire format (little-endian for the header, ALCS payload is already
915// little-endian):
916//
917//   Offset  Size  Field
918//   0       4     magic "ALEE" (ALec Encoder state)
919//   4       1     format version (= 1)
920//   5       1     flags (bit 0: force_keyframe_pending)
921//   6       2     sequence              (u16 big-endian)
922//   8       4     messages_since_keyframe (u32 big-endian)
923//   12      4     alcs_len              (u32 big-endian)
924//   16      8     header xxh64         (bytes [0..16), big-endian)
925//   24      N     ALCS payload (Context::to_preload_bytes, CRC32 inside)
926//
927// The header xxh64 catches corruption of any of the small fields above
928// (sequence/flags/msk) that ALCS's inner CRC wouldn't notice. The ALCS
929// inner CRC32 covers the bulk Context payload.
930// ============================================================================
931
932/// Magic bytes identifying an encoder-state buffer.
933const ENC_STATE_MAGIC: [u8; 4] = *b"ALEE";
934/// Current encoder-state wire format version.
935const ENC_STATE_VERSION: u8 = 1;
936/// Fixed header size before the embedded ALCS payload.
937const ENC_STATE_HEADER_SIZE: usize = 24;
938/// Sensor-type tag used when serializing the context portion. Kept
939/// stable so the embedded ALCS bytes remain interoperable with the
940/// decoder's `_context_load` / `_import_state` readers.
941const ENC_STATE_CTX_TAG: &str = "ffi";
942
943/// bit 0 of the flags byte: `force_keyframe_pending`.
944const ENC_FLAG_FORCE_KEYFRAME: u8 = 0b0000_0001;
945
946/// Save the encoder's runtime state to a caller-provided RAM buffer.
947///
948/// The saved blob captures:
949/// * The full `Context` — per-channel prediction model (EMA, last
950///   values, history), pattern dictionary and context version.
951/// * The encoder's sequence counter.
952/// * The pending force-keyframe flag and the messages-since-keyframe
953///   counter consumed by the periodic keyframe mechanism.
954///
955/// Intended use (firmware, v1.3.7):
956///
957/// ```text
958///     snapshot      = alec_encoder_context_save(enc, buf, cap, &len)
959///     wire          = alec_encode_multi_fixed(enc, …)
960///     if wire_len > ceiling:
961///         alec_encoder_context_load(enc, buf, len)   // roll back
962///         alec_force_keyframe(enc)                   // next frame = keyframe
963/// ```
964///
965/// On `ALEC_ERROR_BUFFER_TOO_SMALL`, `*written` reports the exact
966/// size the buffer would have needed and `buf` is NOT modified
967/// (no partial write — callers can safely retry with a larger buffer).
968///
969/// # Arguments
970///
971/// * `enc`     - Encoder handle.
972/// * `buf`     - Destination buffer.
973/// * `buf_cap` - Size of `buf` in bytes.
974/// * `written` - Out: bytes written (on success) or required size
975///   (on `ALEC_ERROR_BUFFER_TOO_SMALL`).
976///
977/// # Returns
978///
979/// * `ALEC_OK` on success.
980/// * `ALEC_ERROR_BUFFER_TOO_SMALL` if `buf_cap` is too small —
981///   `*written` reports the required size, `buf` is unchanged.
982/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer.
983/// * `ALEC_ERROR_ENCODING_FAILED` if the underlying context
984///   serialization fails (pathological config).
985#[no_mangle]
986pub extern "C" fn alec_encoder_context_save(
987    enc: *const AlecEncoder,
988    buf: *mut u8,
989    buf_cap: usize,
990    written: *mut usize,
991) -> AlecResult {
992    if enc.is_null() || buf.is_null() || written.is_null() {
993        return AlecResult::ErrorNullPointer;
994    }
995    let e = unsafe { &*enc };
996
997    // v1.3.9: zero-heap streaming write directly into the caller's
998    // buffer. We avoid the ~1.5 KB temporary `Vec<u8>` that the
999    // previous implementation produced via `Context::to_preload_bytes`
1000    // — that allocation was the reported crash trigger on the
1001    // partner's 4 KB heap Cortex-M4.
1002    //
1003    // Contract (unchanged from v1.3.7 / v1.3.8):
1004    //   * on success: `*written` = total bytes written, return Ok.
1005    //   * on BufferTooSmall: `*written` = required size, `buf` NOT
1006    //     touched (no partial write). Callers can retry with a
1007    //     larger buffer.
1008    //   * on any other error: return EncodingFailed, `buf` / `written`
1009    //     semantics best-effort (no partial writes from this path
1010    //     because we size-check everything up front).
1011
1012    // Required size = 24-byte encoder header + ALCS payload.
1013    let alcs_needed = match e.context.preload_bytes_len(ENC_STATE_CTX_TAG) {
1014        Ok(n) => n,
1015        Err(_) => return AlecResult::ErrorEncodingFailed,
1016    };
1017    let total = ENC_STATE_HEADER_SIZE + alcs_needed;
1018    if total > buf_cap {
1019        unsafe { *written = total };
1020        return AlecResult::ErrorBufferTooSmall;
1021    }
1022
1023    let out = unsafe { slice::from_raw_parts_mut(buf, buf_cap) };
1024
1025    // --- 24-byte encoder-state header (see module comment above) ---
1026    out[0..4].copy_from_slice(&ENC_STATE_MAGIC);
1027    out[4] = ENC_STATE_VERSION;
1028    out[5] = if e.force_keyframe_pending {
1029        ENC_FLAG_FORCE_KEYFRAME
1030    } else {
1031        0
1032    };
1033    out[6..8].copy_from_slice(&e.encoder.sequence().to_be_bytes());
1034    out[8..12].copy_from_slice(&e.messages_since_keyframe.to_be_bytes());
1035    out[12..16].copy_from_slice(&(alcs_needed as u32).to_be_bytes());
1036    let hdr_hash = xxhash_rust::xxh64::xxh64(&out[0..16], 0);
1037    out[16..24].copy_from_slice(&hdr_hash.to_be_bytes());
1038
1039    // --- ALCS payload written directly into the caller buffer ---
1040    // Byte-identical to the v1.3.8 output — same ALCS wire format.
1041    let alcs_slice = &mut out[ENC_STATE_HEADER_SIZE..ENC_STATE_HEADER_SIZE + alcs_needed];
1042    let alcs_written = match e.context.write_preload_bytes(ENC_STATE_CTX_TAG, alcs_slice) {
1043        Ok(n) => n,
1044        Err(_) => return AlecResult::ErrorEncodingFailed,
1045    };
1046    debug_assert_eq!(alcs_written, alcs_needed);
1047
1048    unsafe { *written = total };
1049    AlecResult::Ok
1050}
1051
1052/// Restore encoder state from bytes produced by `alec_encoder_context_save`.
1053///
1054/// On success the encoder's `context`, `sequence`, `force_keyframe_pending`
1055/// and `messages_since_keyframe` are all overwritten. Static
1056/// configuration (`keyframe_interval`, `smart_resync`, checksum flag)
1057/// is preserved — those are properties of the encoder instance, not
1058/// of the transient runtime state.
1059///
1060/// # State transitions (v1.3.9)
1061///
1062/// On a tight-heap MCU, building the new `Context` while the old one
1063/// is still alive briefly needs ~2× the per-instance heap — enough to
1064/// blow a 4 KB allocator. v1.3.9 trades the previous all-or-nothing
1065/// contract for a heap-safe three-phase restore:
1066///
1067/// 1. **Pre-validate** the input buffer without any allocation
1068///    (magic, version, header xxh64, ALCS magic/CRC). If anything
1069///    fails here → return `ALEC_ERROR_CORRUPT_DATA`, encoder
1070///    **unchanged** (old contract preserved for the common
1071///    caller-error case — wrong magic, CRC mismatch, truncation,
1072///    etc.).
1073/// 2. **Free** the old Context by replacing it with a fresh empty
1074///    `Context`. Peak heap now drops back to ~1 × Context.
1075/// 3. **Rebuild** the new Context from the input buffer. Peak heap
1076///    is now ~1 × Context (new) instead of ~2 × (old + new). If the
1077///    inner `from_preload_bytes` still fails for some reason that
1078///    the pre-validator didn't catch (structural inconsistency
1079///    between advertised counts and inner section lengths), the
1080///    encoder ends up in a *freshly reset* state. This is the
1081///    single behavioural change vs v1.3.8 and is documented under
1082///    `ALEC_ERROR_CORRUPT_DATA` below.
1083///
1084/// # Arguments
1085///
1086/// * `enc`     - Encoder handle.
1087/// * `buf`     - Input bytes produced by `alec_encoder_context_save`.
1088/// * `buf_len` - Length of `buf` in bytes.
1089///
1090/// # Returns
1091///
1092/// * `ALEC_OK` on success.
1093/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer.
1094/// * `ALEC_ERROR_CORRUPT_DATA` if `buf` cannot be parsed.
1095///   * If the pre-validator rejects the buffer (bad magic, unknown
1096///     format version, header xxh64 mismatch, length mismatch,
1097///     ALCS CRC mismatch): the encoder is **unchanged**.
1098///   * If the outer validation succeeded but the inner
1099///     `from_preload_bytes` fails (rare, implies a CRC-valid but
1100///     structurally inconsistent buffer): the encoder is left in a
1101///     **freshly reset state** — not the old state, not corrupted.
1102///     Callers can safely `alec_force_keyframe` + resume encoding;
1103///     the decoder will resync on the next keyframe.
1104#[no_mangle]
1105pub extern "C" fn alec_encoder_context_load(
1106    enc: *mut AlecEncoder,
1107    buf: *const u8,
1108    buf_len: usize,
1109) -> AlecResult {
1110    if enc.is_null() || buf.is_null() {
1111        return AlecResult::ErrorNullPointer;
1112    }
1113    if buf_len < ENC_STATE_HEADER_SIZE {
1114        return AlecResult::ErrorCorruptData;
1115    }
1116    let data = unsafe { slice::from_raw_parts(buf, buf_len) };
1117
1118    // === PHASE 1: Pre-validate (zero heap allocation) ===
1119    // Magic + version.
1120    if data[0..4] != ENC_STATE_MAGIC {
1121        return AlecResult::ErrorCorruptData;
1122    }
1123    if data[4] != ENC_STATE_VERSION {
1124        return AlecResult::ErrorCorruptData;
1125    }
1126    // Header xxh64 — catches corruption of flags/sequence/msk/alcs_len.
1127    let stored_hash = u64::from_be_bytes([
1128        data[16], data[17], data[18], data[19], data[20], data[21], data[22], data[23],
1129    ]);
1130    let computed_hash = xxhash_rust::xxh64::xxh64(&data[0..16], 0);
1131    if stored_hash != computed_hash {
1132        return AlecResult::ErrorCorruptData;
1133    }
1134    // ALCS payload length must account for all remaining bytes exactly.
1135    let alcs_len = u32::from_be_bytes([data[12], data[13], data[14], data[15]]) as usize;
1136    if alcs_len != buf_len.saturating_sub(ENC_STATE_HEADER_SIZE) {
1137        return AlecResult::ErrorCorruptData;
1138    }
1139    let alcs = &data[ENC_STATE_HEADER_SIZE..ENC_STATE_HEADER_SIZE + alcs_len];
1140
1141    // Zero-heap ALCS header / CRC check — walks the buffer, computes
1142    // the CRC32 table-based checksum against the rodata lookup, and
1143    // returns a bool. Rejects the common failure modes
1144    // (corruption, wrong format) before we touch the encoder.
1145    if !Context::validate_preload_header(alcs) {
1146        return AlecResult::ErrorCorruptData;
1147    }
1148
1149    // === PHASE 2: Drop the old Context (frees heap) ===
1150    // Extract scalar fields we'll need below BEFORE we take any
1151    // mutable borrow of the encoder.
1152    let flags = data[5];
1153    let sequence = u16::from_be_bytes([data[6], data[7]]);
1154    let msk = u32::from_be_bytes([data[8], data[9], data[10], data[11]]);
1155
1156    let e = unsafe { &mut *enc };
1157    // `Context::new()` is stack-only (no allocations until a source
1158    // is inserted). Assigning it drops the old Context here,
1159    // returning its BTreeMap nodes / Vec<f64> history / Pattern data
1160    // to the allocator.
1161    e.context = Context::new();
1162
1163    // === PHASE 3: Build the new Context from the pre-validated buffer ===
1164    // Peak heap now is only ~1× Context (the new one being built),
1165    // not ~2× (old + new). Still calls into `from_preload_bytes`,
1166    // whose allocations all end up persistent in the returned
1167    // Context — no intermediate scratch Vec / temp Box.
1168    match Context::from_preload_bytes(alcs) {
1169        Ok(ctx) => {
1170            e.context = ctx;
1171            e.encoder.restore_sequence(sequence);
1172            e.messages_since_keyframe = msk;
1173            e.force_keyframe_pending = (flags & ENC_FLAG_FORCE_KEYFRAME) != 0;
1174            AlecResult::Ok
1175        }
1176        Err(_) => {
1177            // Unreachable on buffers produced by this library (the
1178            // v1.3.9 validator + ALCS CRC32 catch every malformation
1179            // we can emit). Defensive: if some third-party writer
1180            // produced a CRC-valid but structurally inconsistent
1181            // buffer, the encoder is left with the fresh
1182            // `Context::new()` from Phase 2 — documented behaviour.
1183            AlecResult::ErrorCorruptData
1184        }
1185    }
1186}
1187
1188// ============================================================================
1189// Decoder Functions
1190//
1191// All decoder FFI is gated behind the `decoder` Cargo feature, which is on
1192// by default for hosted/server builds and OFF for `--features zephyr` MCU
1193// builds (encoder-only firmware target). The decoder requires `std` for
1194// HashMap / Vec / String.
1195// ============================================================================
1196
1197/// Create a new ALEC decoder
1198///
1199/// # Returns
1200///
1201/// A pointer to a new decoder, or NULL on allocation failure.
1202/// The decoder must be freed with `alec_decoder_free()` when no longer needed.
1203#[cfg(feature = "decoder")]
1204#[no_mangle]
1205pub extern "C" fn alec_decoder_new() -> *mut AlecDecoder {
1206    let decoder = Box::new(AlecDecoder {
1207        decoder: Decoder::new(),
1208        context: Context::new(),
1209        last_header_sequence: None,
1210        last_gap_size: 0,
1211    });
1212    Box::into_raw(decoder)
1213}
1214
1215/// Create a new decoder with checksum verification enabled
1216///
1217/// # Returns
1218///
1219/// A pointer to a new decoder with checksum enabled, or NULL on failure.
1220#[cfg(feature = "decoder")]
1221#[no_mangle]
1222pub extern "C" fn alec_decoder_new_with_checksum() -> *mut AlecDecoder {
1223    let decoder = Box::new(AlecDecoder {
1224        decoder: Decoder::with_checksum_verification(),
1225        context: Context::new(),
1226        last_header_sequence: None,
1227        last_gap_size: 0,
1228    });
1229    Box::into_raw(decoder)
1230}
1231
1232/// Create a new ALEC decoder with a custom configuration.
1233///
1234/// Mirrors `alec_encoder_new_with_config` for the decoder side. The
1235/// `AlecEncoderConfig` struct is reused because the decoder must run
1236/// with the same `history_size`, `max_patterns` and `max_memory_bytes`
1237/// as the matching encoder for the prediction model to stay in sync.
1238///
1239/// `keyframe_interval` and `smart_resync` are encoder-only knobs and
1240/// are accepted but ignored on the decoder side.
1241///
1242/// # Arguments
1243///
1244/// * `config` - Pointer to an `AlecEncoderConfig`. If NULL, all defaults
1245///   are used. Numeric fields set to 0 are replaced by their default.
1246///
1247/// # Returns
1248///
1249/// A pointer to a new decoder, or NULL on allocation failure.
1250/// Must be freed with `alec_decoder_free()`.
1251#[cfg(feature = "decoder")]
1252#[no_mangle]
1253pub extern "C" fn alec_decoder_new_with_config(
1254    config: *const AlecEncoderConfig,
1255) -> *mut AlecDecoder {
1256    let cfg = if config.is_null() {
1257        AlecEncoderConfig::defaults()
1258    } else {
1259        unsafe { *config }.resolved()
1260    };
1261
1262    let context = Context::with_config(cfg.to_context_config());
1263    let decoder = Box::new(AlecDecoder {
1264        decoder: Decoder::new(),
1265        context,
1266        last_header_sequence: None,
1267        last_gap_size: 0,
1268    });
1269    Box::into_raw(decoder)
1270}
1271
1272/// Reset a decoder to its initial state.
1273///
1274/// Wipes all per-channel prediction state (the per-source EMA, last
1275/// values, history) and clears the session-tracking counters
1276/// (`last_header_sequence`, `last_gap_size`). The next frame the
1277/// decoder sees should be a keyframe (marker `0xA2`) which will
1278/// re-seed the prediction state from Raw32 values.
1279///
1280/// Use after detecting an unrecoverable desync that the in-band gap
1281/// recovery can't handle (e.g. the server-side sidecar restarting
1282/// without a saved context).
1283///
1284/// No-op if `dec` is NULL.
1285#[cfg(feature = "decoder")]
1286#[no_mangle]
1287pub extern "C" fn alec_decoder_reset(dec: *mut AlecDecoder) {
1288    if dec.is_null() {
1289        return;
1290    }
1291    let d = unsafe { &mut *dec };
1292    d.decoder.reset();
1293    d.context.reset_to_baseline();
1294    d.last_header_sequence = None;
1295    d.last_gap_size = 0;
1296}
1297
1298/// Check whether the most recent decode detected a sequence gap.
1299///
1300/// The server-side sidecar uses this to decide whether to issue a
1301/// resync downlink (0xFF) to the device. The gap size is the number
1302/// of missing frames between the previous `last_sequence` and the
1303/// current one, clipped to 255.
1304///
1305/// # Arguments
1306///
1307/// * `decoder`      - Decoder handle.
1308/// * `out_gap_size` - Out parameter receiving the gap size (may be NULL).
1309///
1310/// # Returns
1311///
1312/// `true` if the most recent multi-frame decode observed missing
1313/// frames (gap > 0). `false` if no gap, if no decode has been
1314/// performed yet, or if `decoder` is NULL.
1315#[cfg(feature = "decoder")]
1316#[no_mangle]
1317pub extern "C" fn alec_decoder_gap_detected(
1318    decoder: *const AlecDecoder,
1319    out_gap_size: *mut u8,
1320) -> bool {
1321    if decoder.is_null() {
1322        if !out_gap_size.is_null() {
1323            unsafe { *out_gap_size = 0 };
1324        }
1325        return false;
1326    }
1327    let dec = unsafe { &*decoder };
1328    if !out_gap_size.is_null() {
1329        unsafe { *out_gap_size = dec.last_gap_size };
1330    }
1331    dec.last_gap_size > 0
1332}
1333
1334/// Free a decoder
1335///
1336/// # Arguments
1337///
1338/// * `decoder` - Decoder to free. May be NULL (no-op).
1339#[cfg(feature = "decoder")]
1340#[no_mangle]
1341pub extern "C" fn alec_decoder_free(decoder: *mut AlecDecoder) {
1342    if !decoder.is_null() {
1343        unsafe {
1344            drop(Box::from_raw(decoder));
1345        }
1346    }
1347}
1348
1349/// Decode compressed data to a single value
1350///
1351/// # Arguments
1352///
1353/// * `decoder` - Decoder handle
1354/// * `input` - Compressed input data
1355/// * `input_len` - Length of input data
1356/// * `value` - Pointer to store decoded value
1357/// * `timestamp` - Pointer to store decoded timestamp (can be NULL)
1358///
1359/// # Returns
1360///
1361/// `ALEC_OK` on success, error code otherwise.
1362#[cfg(feature = "decoder")]
1363#[no_mangle]
1364pub extern "C" fn alec_decode_value(
1365    decoder: *mut AlecDecoder,
1366    input: *const u8,
1367    input_len: usize,
1368    value: *mut f64,
1369    timestamp: *mut u64,
1370) -> AlecResult {
1371    if decoder.is_null() || input.is_null() || value.is_null() {
1372        return AlecResult::ErrorNullPointer;
1373    }
1374
1375    let dec = unsafe { &mut *decoder };
1376    let input_slice = unsafe { slice::from_raw_parts(input, input_len) };
1377
1378    match dec.decoder.decode_bytes(input_slice, &dec.context) {
1379        Ok(decoded_data) => {
1380            unsafe {
1381                *value = decoded_data.value;
1382                if !timestamp.is_null() {
1383                    *timestamp = decoded_data.timestamp;
1384                }
1385            }
1386            AlecResult::Ok
1387        }
1388        Err(_) => AlecResult::ErrorDecodingFailed,
1389    }
1390}
1391
1392/// Decode compressed data to multiple values
1393///
1394/// # Arguments
1395///
1396/// * `decoder` - Decoder handle
1397/// * `input` - Compressed input data
1398/// * `input_len` - Length of input data
1399/// * `values` - Output buffer for decoded values
1400/// * `values_capacity` - Maximum number of values that can be stored
1401/// * `values_count` - Pointer to store actual number of decoded values
1402///
1403/// # Returns
1404///
1405/// `ALEC_OK` on success, error code otherwise.
1406#[cfg(feature = "decoder")]
1407#[no_mangle]
1408pub extern "C" fn alec_decode_multi(
1409    decoder: *mut AlecDecoder,
1410    input: *const u8,
1411    input_len: usize,
1412    values: *mut f64,
1413    values_capacity: usize,
1414    values_count: *mut usize,
1415) -> AlecResult {
1416    if decoder.is_null() || input.is_null() || values.is_null() || values_count.is_null() {
1417        return AlecResult::ErrorNullPointer;
1418    }
1419
1420    let dec = unsafe { &mut *decoder };
1421    let input_slice = unsafe { slice::from_raw_parts(input, input_len) };
1422
1423    // First parse the message from bytes
1424    let message = match alec::protocol::EncodedMessage::from_bytes(input_slice) {
1425        Some(msg) => msg,
1426        None => return AlecResult::ErrorDecodingFailed,
1427    };
1428
1429    // Gap detection: compute the number of missing frames between the
1430    // previous header sequence and this one. `decode_multi` does not
1431    // touch `Decoder::last_sequence`, so we track it here at the FFI
1432    // layer. Clipped to 255 to fit `last_gap_size: u8`.
1433    let cur_seq = message.header.sequence;
1434    dec.last_gap_size = match dec.last_header_sequence {
1435        Some(prev) => {
1436            let diff = cur_seq.wrapping_sub(prev);
1437            if diff == 0 {
1438                0 // same frame replayed — treat as no gap
1439            } else {
1440                let missing = diff.saturating_sub(1);
1441                missing.min(u8::MAX as u16) as u8
1442            }
1443        }
1444        None => 0,
1445    };
1446    dec.last_header_sequence = Some(cur_seq);
1447
1448    match dec.decoder.decode_multi(&message, &dec.context) {
1449        Ok(value_pairs) => {
1450            if value_pairs.len() > values_capacity {
1451                return AlecResult::ErrorBufferTooSmall;
1452            }
1453
1454            let values_slice = unsafe { slice::from_raw_parts_mut(values, values_capacity) };
1455            for (i, (_, val)) in value_pairs.iter().enumerate() {
1456                values_slice[i] = *val;
1457            }
1458            unsafe {
1459                *values_count = value_pairs.len();
1460            }
1461            AlecResult::Ok
1462        }
1463        Err(_) => AlecResult::ErrorDecodingFailed,
1464    }
1465}
1466
1467/// Load decoder context from a preload file
1468///
1469/// # Arguments
1470///
1471/// * `decoder` - Decoder handle
1472/// * `path` - File path to preload (null-terminated string)
1473///
1474/// # Returns
1475///
1476/// `ALEC_OK` on success, error code otherwise.
1477#[cfg(all(feature = "decoder", feature = "std"))]
1478#[no_mangle]
1479pub extern "C" fn alec_decoder_load_context(
1480    decoder: *mut AlecDecoder,
1481    path: *const c_char,
1482) -> AlecResult {
1483    if decoder.is_null() || path.is_null() {
1484        return AlecResult::ErrorNullPointer;
1485    }
1486
1487    let dec = unsafe { &mut *decoder };
1488
1489    let path_str = match unsafe { CStr::from_ptr(path) }.to_str() {
1490        Ok(s) => s,
1491        Err(_) => return AlecResult::ErrorInvalidUtf8,
1492    };
1493
1494    match Context::load_from_file(Path::new(path_str)) {
1495        Ok(ctx) => {
1496            dec.context = ctx;
1497            AlecResult::Ok
1498        }
1499        Err(_) => AlecResult::ErrorFileIo,
1500    }
1501}
1502
1503/// Get the current decoder context version
1504///
1505/// # Arguments
1506///
1507/// * `decoder` - Decoder handle
1508///
1509/// # Returns
1510///
1511/// The context version number, or 0 if decoder is NULL.
1512#[cfg(feature = "decoder")]
1513#[no_mangle]
1514pub extern "C" fn alec_decoder_context_version(decoder: *const AlecDecoder) -> u32 {
1515    if decoder.is_null() {
1516        return 0;
1517    }
1518    let dec = unsafe { &*decoder };
1519    dec.context.context_version()
1520}
1521
1522// ============================================================================
1523// Bloc B — Compact fixed-channel FFI (Milesight EM500-CO2)
1524// ============================================================================
1525
1526/// Encode a fixed-channel frame using the compact 4-byte header
1527/// (Milesight EM500-CO2 wire format).
1528///
1529/// The number of channels is passed explicitly and must match the
1530/// value used by the peer decoder — the wire format does not carry
1531/// it. The encoder keeps a positional view of the channels, so
1532/// `values[i]` is the value for channel index `i`.
1533///
1534/// If `keyframe_interval > 0` and `messages_since_keyframe`
1535/// has reached that interval, OR if `alec_force_keyframe` was called
1536/// since the last encode AND `smart_resync` is enabled, this frame
1537/// is emitted as a **keyframe** (marker 0xA2, Raw32 for every
1538/// channel). Otherwise a regular data frame (marker 0xA1) is emitted.
1539///
1540/// # Arguments
1541///
1542/// * `encoder`         - Encoder handle (must not be NULL).
1543/// * `values` - Per-channel f64 values, positional.
1544/// * `channel_count` - Number of channels in `values`.
1545/// * `output` - Destination buffer for the wire bytes.
1546/// * `output_capacity` - Size of `output` in bytes.
1547/// * `out_len` - Pointer receiving the number of bytes written to
1548///   `output`.
1549///
1550/// # Returns
1551///
1552/// `ALEC_OK` on success. `ALEC_ERROR_BUFFER_TOO_SMALL` if the
1553/// encoded frame does not fit in `output`. `ALEC_ERROR_INVALID_INPUT`
1554/// for zero channels. `ALEC_ERROR_NULL_POINTER` for any required
1555/// NULL pointer.
1556///
1557/// The caller can detect that the frame must be replaced by the
1558/// legacy TLV fallback by comparing `*out_len` against the 11-byte
1559/// LoRaWAN ceiling: if `*out_len > 11`, emit the TLV frame instead.
1560#[no_mangle]
1561pub extern "C" fn alec_encode_multi_fixed(
1562    encoder: *mut AlecEncoder,
1563    values: *const f64,
1564    channel_count: usize,
1565    output: *mut u8,
1566    output_capacity: usize,
1567    out_len: *mut usize,
1568) -> AlecResult {
1569    if encoder.is_null() || values.is_null() || output.is_null() || out_len.is_null() {
1570        return AlecResult::ErrorNullPointer;
1571    }
1572    if channel_count == 0 {
1573        return AlecResult::ErrorInvalidInput;
1574    }
1575
1576    let enc = unsafe { &mut *encoder };
1577    let values_slice = unsafe { slice::from_raw_parts(values, channel_count) };
1578    let output_slice = unsafe { slice::from_raw_parts_mut(output, output_capacity) };
1579
1580    // Decide whether this frame should be a keyframe.
1581    let periodic_due =
1582        enc.keyframe_interval > 0 && enc.messages_since_keyframe >= enc.keyframe_interval;
1583    let downlink_forced = enc.force_keyframe_pending && enc.smart_resync;
1584    let keyframe = periodic_due || downlink_forced;
1585
1586    match enc
1587        .encoder
1588        .encode_multi_fixed(values_slice, &enc.context, keyframe, output_slice)
1589    {
1590        Ok(n) => {
1591            unsafe {
1592                *out_len = n;
1593            }
1594
1595            // Counter housekeeping — only after a successful encode.
1596            // On a keyframe we reset to 1 (not 0): the keyframe IS the
1597            // first frame of the next cycle, so subsequent keyframes
1598            // land at a fixed modular offset (e.g. interval=10 →
1599            // frames 10, 20, 30 …). Off-by-one matters for the spec's
1600            // "Frames 10 and 20 must be Raw32" assertion.
1601            if keyframe {
1602                enc.messages_since_keyframe = 1;
1603                enc.force_keyframe_pending = false;
1604            } else {
1605                enc.messages_since_keyframe = enc.messages_since_keyframe.saturating_add(1);
1606            }
1607
1608            // Observe each channel so the next encode sees this value
1609            // in the prediction cache. We observe the ORIGINAL input
1610            // (not the reconstructed value): on truly-stable signals
1611            // this is what lets `Repeated` fire frame-after-frame.
1612            // Observing the reconstructed value would break Repeated
1613            // detection because f32 roundtrip of e.g. 3.600 yields
1614            // 3.5999999046…, which is > f64::EPSILON away from 3.600.
1615            //
1616            // The trade-off is a bounded drift between encoder and
1617            // decoder contexts on delta-encoded channels. This drift
1618            // is capped by the periodic keyframe mechanism: every
1619            // `keyframe_interval` frames the encoder emits Raw32 for
1620            // every channel, which forces the decoder's view back to
1621            // f32-precision truth. See `test_encode_decode_fixed_roundtrip_5ch`.
1622            for (i, &v) in values_slice.iter().enumerate() {
1623                let rd = RawData::with_source(fixed_channel_source_id(i), v, 0);
1624                enc.context.observe(&rd);
1625            }
1626
1627            AlecResult::Ok
1628        }
1629        Err(alec::error::AlecError::Encode(alec::error::EncodeError::BufferTooSmall {
1630            ..
1631        })) => AlecResult::ErrorBufferTooSmall,
1632        Err(alec::error::AlecError::Encode(alec::error::EncodeError::PayloadTooLarge {
1633            ..
1634        })) => AlecResult::ErrorInvalidInput,
1635        Err(_) => AlecResult::ErrorEncodingFailed,
1636    }
1637}
1638
1639/// Decode a fixed-channel frame produced by `alec_encode_multi_fixed`.
1640///
1641/// The wire format does NOT carry the channel count — encoder and
1642/// decoder must agree on it out-of-band (the LoRaWAN device model
1643/// pins a fixed channel count per DevEUI). The decoder uses
1644/// `max_channels` as both the channel count and the capacity of
1645/// `values_out`; `*num_channels_out` is set to that same value on
1646/// success.
1647///
1648/// On a successful decode:
1649///   - `values_out[..*num_channels_out]` receives the decoded values
1650///     in channel order.
1651///   - `*sequence_out` receives the wire sequence number.
1652///   - `*is_keyframe_out` is `true` when the frame's marker was `0xA2`.
1653///   - The decoder's last-sequence and last-ctx-version are updated.
1654///   - The gap size (if any) is available via `alec_decoder_gap_detected`.
1655///
1656/// # Arguments
1657///
1658/// * `dec`              - Decoder handle.
1659/// * `frame_data`       - Raw ALEC wire bytes (starting at the marker byte).
1660/// * `frame_len`        - Length of `frame_data` in bytes.
1661/// * `values_out`       - Destination buffer for decoded channel values.
1662/// * `max_channels`     - Capacity of `values_out` AND number of channels
1663///   in the frame. Must match the encoder's count.
1664/// * `num_channels_out` - Out: number of channels written to `values_out`.
1665///   May be NULL if the caller does not need it.
1666/// * `sequence_out`     - Out: sequence number from the compact header.
1667///   May be NULL.
1668/// * `is_keyframe_out`  - Out: `true` iff the frame was a keyframe (`0xA2`).
1669///   May be NULL.
1670///
1671/// # Returns
1672///
1673/// * `ALEC_OK` on success.
1674/// * `ALEC_ERROR_INVALID_INPUT` for zero channels or a non-ALEC marker byte.
1675/// * `ALEC_ERROR_BUFFER_TOO_SMALL` if the input is shorter than the header
1676///   + bitmap + data bytes.
1677/// * `ALEC_ERROR_DECODING_FAILED` for any other decode error.
1678/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer
1679///   (`dec`, `frame_data`, `values_out`).
1680#[cfg(feature = "decoder")]
1681#[no_mangle]
1682pub extern "C" fn alec_decode_multi_fixed(
1683    dec: *mut AlecDecoder,
1684    frame_data: *const u8,
1685    frame_len: usize,
1686    values_out: *mut f64,
1687    max_channels: usize,
1688    num_channels_out: *mut usize,
1689    sequence_out: *mut u16,
1690    is_keyframe_out: *mut bool,
1691) -> AlecResult {
1692    if dec.is_null() || frame_data.is_null() || values_out.is_null() {
1693        return AlecResult::ErrorNullPointer;
1694    }
1695    if max_channels == 0 {
1696        return AlecResult::ErrorInvalidInput;
1697    }
1698
1699    let d = unsafe { &mut *dec };
1700    let input_slice = unsafe { slice::from_raw_parts(frame_data, frame_len) };
1701    let output_slice = unsafe { slice::from_raw_parts_mut(values_out, max_channels) };
1702    let channel_count = max_channels;
1703
1704    match d
1705        .decoder
1706        .decode_multi_fixed(input_slice, channel_count, &d.context, output_slice)
1707    {
1708        Ok(info) => {
1709            // Mirror the gap tracking used by the legacy multi path
1710            // so `alec_decoder_gap_detected` returns the same view
1711            // regardless of which decode entry point was used.
1712            d.last_header_sequence = Some(info.sequence);
1713            d.last_gap_size = info.gap_size;
1714
1715            // Bloc C recovery: on a non-keyframe frame, if the
1716            // decoder observed a sequence gap OR a context-version
1717            // mismatch, wipe the per-channel prediction state so
1718            // stale Delta predictions cannot silently corrupt the
1719            // next decode. The next keyframe (marker 0xA2) will
1720            // re-seed the state. A keyframe itself NEVER triggers a
1721            // reset — its payload is Raw32 for every channel and
1722            // fully re-builds the context on its own.
1723            if !info.keyframe {
1724                if info.gap_size > 0 {
1725                    log::warn!(
1726                        "ALEC gap detected on fixed-channel decode: {} frame(s) missing \
1727                         (seq={}), context reset to baseline",
1728                        info.gap_size,
1729                        info.sequence
1730                    );
1731                    d.context.reset_to_baseline();
1732                } else if info.context_mismatch {
1733                    // Also surface a u32-level check via the core
1734                    // Context::check_version API. We truncate our
1735                    // tracked u32 version to the low 16 bits so the
1736                    // comparison is wire-format-accurate; the full
1737                    // u32 version is informational only here.
1738                    let wire_ver = info.context_version as u32;
1739                    let _result = d.context.check_version(wire_ver);
1740                    log::warn!(
1741                        "ALEC ctx_ver mismatch on fixed-channel decode: \
1742                         wire={}, context reset to baseline",
1743                        info.context_version
1744                    );
1745                    d.context.reset_to_baseline();
1746                }
1747            }
1748
1749            // Observe every decoded value so the NEXT frame can
1750            // decode delta-encoded channels correctly. This runs
1751            // AFTER any reset_to_baseline(): on a keyframe these
1752            // observations reconstruct the prediction state from
1753            // the Raw32 values, which is exactly what we want.
1754            for (i, &value) in output_slice.iter().take(channel_count).enumerate() {
1755                let rd = RawData::with_source(fixed_channel_source_id(i), value, 0);
1756                d.context.observe(&rd);
1757            }
1758
1759            // Surface frame-level outputs (all optional).
1760            if !num_channels_out.is_null() {
1761                unsafe { *num_channels_out = channel_count };
1762            }
1763            if !sequence_out.is_null() {
1764                unsafe { *sequence_out = info.sequence };
1765            }
1766            if !is_keyframe_out.is_null() {
1767                unsafe { *is_keyframe_out = info.keyframe };
1768            }
1769
1770            AlecResult::Ok
1771        }
1772        Err(alec::error::AlecError::Decode(alec::error::DecodeError::BufferTooShort {
1773            ..
1774        })) => AlecResult::ErrorBufferTooSmall,
1775        Err(alec::error::AlecError::Decode(alec::error::DecodeError::MalformedMessage {
1776            reason,
1777            ..
1778        })) if reason.contains("not a fixed-channel ALEC frame") => AlecResult::ErrorInvalidInput,
1779        Err(_) => AlecResult::ErrorDecodingFailed,
1780    }
1781}
1782
1783/// Feed raw sensor values into the decoder to advance its prediction
1784/// model, **without** an ALEC wire frame.
1785///
1786/// Use this on the server side when the device sent a legacy TLV
1787/// frame (or any non-ALEC wire format) instead of an ALEC frame for
1788/// a given uplink — typically because the ALEC-encoded frame would
1789/// have exceeded the LoRaWAN payload ceiling and the firmware fell
1790/// back to TLV. The encoder advanced its sequence counter, its
1791/// `context_version`, and its per-channel prediction state when it
1792/// produced the discarded frame; the decoder needs to mirror those
1793/// state changes or the next real ALEC frame will be reported as a
1794/// sequence gap (and trigger a `reset_to_baseline`).
1795///
1796/// After this call, the decoder is in the exact same prediction
1797/// state as it would be if `alec_decode_multi_fixed` had decoded the
1798/// matching ALEC wire bytes. Subsequent ALEC frames decode correctly
1799/// without a "gap detected" warning.
1800///
1801/// # State changes (mirrors `alec_decode_multi_fixed`)
1802///
1803/// 1. The wire-equivalent sequence (= `last_fixed_sequence + 1`,
1804///    matching what the encoder would have written) is recorded —
1805///    `alec_decoder_gap_detected` returns `false` after this call.
1806/// 2. The wire-equivalent ctx_version (= low 16 bits of the
1807///    decoder's CURRENT `context.version`, captured BEFORE the
1808///    observe loop) is recorded so a context-version mismatch on
1809///    the next real frame is computed against the right baseline.
1810/// 3. Each value is fed through `Context::observe` — same loop as
1811///    the post-decode path in `alec_decode_multi_fixed`. This
1812///    advances `context.version` by `num_values`.
1813///
1814/// # Arguments
1815///
1816/// * `dec`        - Decoder handle.
1817/// * `values`     - Array of `f64` sensor values, in the same channel
1818///   order the encoder uses.
1819/// * `num_values` - Number of values in `values`. Must be in `1..=64`
1820///   (matching `alec_encode_multi_fixed`'s channel cap).
1821///
1822/// # Returns
1823///
1824/// * `ALEC_OK` on success.
1825/// * `ALEC_ERROR_NULL_POINTER` if `dec` or `values` is NULL.
1826/// * `ALEC_ERROR_INVALID_INPUT` if `num_values == 0` or `num_values > 64`.
1827///
1828/// # Zero heap
1829///
1830/// This function performs zero heap allocations once the decoder's
1831/// per-channel `SourceStats` entries exist (i.e. after the first
1832/// observation per source_id, or after `num_channels` pre-warm at
1833/// `alec_decoder_new_with_config` time).
1834#[cfg(feature = "decoder")]
1835#[no_mangle]
1836pub extern "C" fn alec_decoder_feed_values(
1837    dec: *mut AlecDecoder,
1838    values: *const f64,
1839    num_values: usize,
1840) -> AlecResult {
1841    if dec.is_null() || values.is_null() {
1842        return AlecResult::ErrorNullPointer;
1843    }
1844    // Match the encoder's `Encoder::encode_multi_fixed` cap of 64
1845    // channels. Reject 0 (no-op) and >64 (out of wire-format range)
1846    // up front — same shape as `alec_encode_multi_fixed`.
1847    if num_values == 0 || num_values > 64 {
1848        return AlecResult::ErrorInvalidInput;
1849    }
1850
1851    let d = unsafe { &mut *dec };
1852    let values_slice = unsafe { slice::from_raw_parts(values, num_values) };
1853
1854    // Step 1: capture the wire-equivalent ctx_ver BEFORE observing.
1855    // The encoder writes `(context.version & 0xFFFF) as u16` into the
1856    // CompactHeader BEFORE its post-encode observe loop; we mirror
1857    // that exactly so a future real frame's ctx_ver-mismatch check
1858    // sees the same value the encoder will write.
1859    let wire_ctx_ver = (d.context.context_version() & 0xFFFF) as u16;
1860
1861    // Step 2: compute the wire-equivalent sequence. The encoder
1862    // increments its `Encoder::sequence` once per encode call; the
1863    // wire seq is the pre-increment value. The decoder's
1864    // `last_fixed_sequence` records what wire seq it last saw; the
1865    // next frame (real or "ghost") would be `last + 1`. None means
1866    // "no frame yet" — the encoder's first wire seq is 0, so we use
1867    // u16::MAX so wrapping_add(1) lands on 0.
1868    let wire_seq = d
1869        .decoder
1870        .last_fixed_sequence()
1871        .unwrap_or(u16::MAX)
1872        .wrapping_add(1);
1873
1874    // Step 3: advance the alec::Decoder's fixed-path trackers. This
1875    // is the only place we need a setter on the inner Decoder —
1876    // `Decoder::record_fixed_frame` was added in v1.3.10 for exactly
1877    // this use case.
1878    d.decoder.record_fixed_frame(wire_seq, wire_ctx_ver);
1879
1880    // Step 4: FFI-layer trackers — mirror the post-decode bookkeeping
1881    // in `alec_decode_multi_fixed`. By construction `feed_values` is
1882    // the lockstep path (no gap, no version mismatch), so gap_size = 0.
1883    d.last_header_sequence = Some(wire_seq);
1884    d.last_gap_size = 0;
1885
1886    // Step 5: per-channel observe — same loop as the post-decode
1887    // path. Each `observe` increments `context.version` by 1; after
1888    // `num_values` observes the decoder's context.version has
1889    // advanced by exactly the same amount the encoder's did when it
1890    // produced the discarded frame.
1891    for (i, &v) in values_slice.iter().enumerate() {
1892        let rd = RawData::with_source(fixed_channel_source_id(i), v, 0);
1893        d.context.observe(&rd);
1894    }
1895
1896    AlecResult::Ok
1897}
1898
1899// ============================================================================
1900// Bloc D — Context persistence FFI
1901//
1902// These functions expose Context::to_preload_bytes / from_preload_bytes to
1903// C callers. Intended use: the ChirpStack sidecar periodically exports each
1904// DevEUI's decoder context (Redis persistence) and restores it on startup.
1905// ============================================================================
1906
1907/// Compute the exact number of bytes `alec_decoder_export_state` would
1908/// write for this decoder + sensor_type. Lets the caller allocate the
1909/// right-sized buffer up front without any reallocation.
1910///
1911/// # Arguments
1912///
1913/// * `decoder`     - Decoder handle.
1914/// * `sensor_type` - Null-terminated sensor-type identifier.
1915/// * `out_size`    - Pointer receiving the required size in bytes.
1916///
1917/// # Returns
1918///
1919/// `ALEC_OK` on success; `ALEC_ERROR_NULL_POINTER` for a NULL pointer;
1920/// `ALEC_ERROR_INVALID_UTF8` if `sensor_type` is not valid UTF-8;
1921/// `ALEC_ERROR_INVALID_INPUT` if `sensor_type` exceeds 255 bytes.
1922#[cfg(feature = "decoder")]
1923#[no_mangle]
1924pub extern "C" fn alec_decoder_export_state_size(
1925    decoder: *const AlecDecoder,
1926    sensor_type: *const c_char,
1927    out_size: *mut usize,
1928) -> AlecResult {
1929    if decoder.is_null() || sensor_type.is_null() || out_size.is_null() {
1930        return AlecResult::ErrorNullPointer;
1931    }
1932    let dec = unsafe { &*decoder };
1933    let sens_str = match unsafe { CStr::from_ptr(sensor_type) }.to_str() {
1934        Ok(s) => s,
1935        Err(_) => return AlecResult::ErrorInvalidUtf8,
1936    };
1937    match dec.context.to_preload_bytes(sens_str) {
1938        Ok(bytes) => {
1939            unsafe { *out_size = bytes.len() };
1940            AlecResult::Ok
1941        }
1942        Err(_) => AlecResult::ErrorInvalidInput,
1943    }
1944}
1945
1946/// Serialize the decoder's context to a caller-provided buffer.
1947///
1948/// The output is a self-contained byte buffer (magic `ALCS`, CRC32
1949/// protected) that can be persisted to Redis, a file, etc. Typical
1950/// size is 1-2 KB for a 5-channel EM500-CO2 decoder with
1951/// `history_size = 20`.
1952///
1953/// Session state (last_header_sequence, last_gap_size) is **NOT**
1954/// serialized — those are transient tracking counters that reset
1955/// naturally on sidecar restart.
1956///
1957/// # Arguments
1958///
1959/// * `decoder` - Decoder handle.
1960/// * `sensor_type` - Null-terminated sensor-type identifier (≤ 255 bytes).
1961/// * `out_buf` - Destination buffer.
1962/// * `out_capacity` - Size of `out_buf` in bytes.
1963/// * `out_len` - Pointer receiving the number of bytes written (on
1964///   success) or the required size (on `ALEC_ERROR_BUFFER_TOO_SMALL`).
1965///
1966/// # Returns
1967///
1968/// * `ALEC_OK` on success.
1969/// * `ALEC_ERROR_BUFFER_TOO_SMALL` if `out_capacity` is less than the
1970///   required size. In that case `*out_len` is set to the required
1971///   size and `out_buf` is NOT written (no partial write).
1972/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer.
1973/// * `ALEC_ERROR_INVALID_UTF8` if `sensor_type` is not valid UTF-8.
1974/// * `ALEC_ERROR_INVALID_INPUT` if `sensor_type` exceeds 255 bytes.
1975#[cfg(feature = "decoder")]
1976#[no_mangle]
1977pub extern "C" fn alec_decoder_export_state(
1978    decoder: *const AlecDecoder,
1979    sensor_type: *const c_char,
1980    out_buf: *mut u8,
1981    out_capacity: usize,
1982    out_len: *mut usize,
1983) -> AlecResult {
1984    if decoder.is_null() || sensor_type.is_null() || out_buf.is_null() || out_len.is_null() {
1985        return AlecResult::ErrorNullPointer;
1986    }
1987    let dec = unsafe { &*decoder };
1988    let sens_str = match unsafe { CStr::from_ptr(sensor_type) }.to_str() {
1989        Ok(s) => s,
1990        Err(_) => return AlecResult::ErrorInvalidUtf8,
1991    };
1992    let bytes = match dec.context.to_preload_bytes(sens_str) {
1993        Ok(b) => b,
1994        Err(_) => return AlecResult::ErrorInvalidInput,
1995    };
1996    if bytes.len() > out_capacity {
1997        // Buffer too small — report the required size but do not
1998        // partially write the output (contract: out_buf unchanged).
1999        unsafe { *out_len = bytes.len() };
2000        return AlecResult::ErrorBufferTooSmall;
2001    }
2002    let out_slice = unsafe { slice::from_raw_parts_mut(out_buf, out_capacity) };
2003    out_slice[..bytes.len()].copy_from_slice(&bytes);
2004    unsafe { *out_len = bytes.len() };
2005    AlecResult::Ok
2006}
2007
2008/// Restore a decoder's context from bytes produced by
2009/// `alec_decoder_export_state`.
2010///
2011/// On success, `decoder.context` is replaced by the deserialized
2012/// context. The decoder's session state — `last_header_sequence` and
2013/// `last_gap_size` — is **preserved** (those are transient
2014/// frame-level trackers, not context state).
2015///
2016/// If the input buffer is corrupted (bad magic, CRC mismatch,
2017/// truncation, etc.), the decoder is NOT modified in any way —
2018/// neither the context nor the session state. The caller can safely
2019/// retry after repairing the input.
2020///
2021/// # Arguments
2022///
2023/// * `decoder`  - Decoder handle.
2024/// * `data`     - Input bytes produced by `alec_decoder_export_state`.
2025/// * `data_len` - Length of `data` in bytes.
2026///
2027/// # Returns
2028///
2029/// * `ALEC_OK` on success.
2030/// * `ALEC_ERROR_NULL_POINTER` for a NULL pointer.
2031/// * `ALEC_ERROR_CORRUPT_DATA` if `data` cannot be parsed (bad magic,
2032///   CRC mismatch, truncation, unknown format version).
2033#[cfg(feature = "decoder")]
2034#[no_mangle]
2035pub extern "C" fn alec_decoder_import_state(
2036    decoder: *mut AlecDecoder,
2037    data: *const u8,
2038    data_len: usize,
2039) -> AlecResult {
2040    if decoder.is_null() || data.is_null() {
2041        return AlecResult::ErrorNullPointer;
2042    }
2043    let data_slice = unsafe { slice::from_raw_parts(data, data_len) };
2044    match Context::from_preload_bytes(data_slice) {
2045        Ok(ctx) => {
2046            let dec = unsafe { &mut *decoder };
2047            // Replace context only — session state (last_header_sequence,
2048            // last_gap_size) is intentionally preserved.
2049            dec.context = ctx;
2050            AlecResult::Ok
2051        }
2052        Err(_) => AlecResult::ErrorCorruptData,
2053    }
2054}
2055
2056// ============================================================================
2057// Decoder context save / load (sensor-type-agnostic, v1.3.6+)
2058//
2059// Thin wrappers over alec_decoder_export_state / alec_decoder_import_state
2060// that hide the `sensor_type` tag from callers that don't use it. The
2061// underlying preload format requires a sensor-type label; we use a fixed
2062// "ffi" tag so the produced bytes remain interoperable with the lower-level
2063// `_state` APIs (an "ffi"-tagged buffer is also a valid preload buffer).
2064// ============================================================================
2065
2066/// Sensor-type tag used by `alec_decoder_context_save`. Kept short
2067/// (≤ 255 bytes) and version-stable so the produced bytes round-trip
2068/// across `_save` / `_load` and across `_state` / `_state` boundaries.
2069#[cfg(feature = "decoder")]
2070const FFI_CONTEXT_TAG: &str = "ffi";
2071
2072/// Save the decoder's context to a caller-provided buffer.
2073///
2074/// On success `*written` reports the number of bytes written to `buf`.
2075/// On `ALEC_ERROR_BUFFER_TOO_SMALL`, `*written` reports the required
2076/// size and `buf` is NOT modified (no partial write).
2077///
2078/// The output is a self-contained byte buffer (magic `ALCS`, CRC32
2079/// protected) suitable for Redis/disk persistence. Typical size is
2080/// 1–2 KB for a 5-channel decoder with `history_size = 20`.
2081///
2082/// Use `alec_decoder_context_load` (or the lower-level
2083/// `alec_decoder_import_state`) to restore.
2084///
2085/// Session state (`last_header_sequence`, `last_gap_size`) is NOT
2086/// serialized — those are transient frame-level trackers that reset
2087/// naturally when the sidecar restarts.
2088///
2089/// # Arguments
2090///
2091/// * `dec`     - Decoder handle.
2092/// * `buf`     - Destination buffer.
2093/// * `buf_cap` - Size of `buf` in bytes.
2094/// * `written` - Out: bytes written (on success) or required size
2095///   (on `ALEC_ERROR_BUFFER_TOO_SMALL`).
2096///
2097/// # Returns
2098///
2099/// * `ALEC_OK` on success.
2100/// * `ALEC_ERROR_BUFFER_TOO_SMALL` if `buf_cap` is too small —
2101///   `*written` reports the required size, `buf` is unchanged.
2102/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer.
2103#[cfg(feature = "decoder")]
2104#[no_mangle]
2105pub extern "C" fn alec_decoder_context_save(
2106    dec: *const AlecDecoder,
2107    buf: *mut u8,
2108    buf_cap: usize,
2109    written: *mut usize,
2110) -> AlecResult {
2111    if dec.is_null() || buf.is_null() || written.is_null() {
2112        return AlecResult::ErrorNullPointer;
2113    }
2114    let d = unsafe { &*dec };
2115    let bytes = match d.context.to_preload_bytes(FFI_CONTEXT_TAG) {
2116        Ok(b) => b,
2117        Err(_) => return AlecResult::ErrorEncodingFailed,
2118    };
2119    if bytes.len() > buf_cap {
2120        unsafe { *written = bytes.len() };
2121        return AlecResult::ErrorBufferTooSmall;
2122    }
2123    let out_slice = unsafe { slice::from_raw_parts_mut(buf, buf_cap) };
2124    out_slice[..bytes.len()].copy_from_slice(&bytes);
2125    unsafe { *written = bytes.len() };
2126    AlecResult::Ok
2127}
2128
2129/// Restore the decoder's context from bytes produced by
2130/// `alec_decoder_context_save` (or `alec_decoder_export_state`).
2131///
2132/// On success the decoder's `context` is replaced; session state
2133/// (`last_header_sequence`, `last_gap_size`) is preserved. On
2134/// `ALEC_ERROR_CORRUPT_DATA` the decoder is NOT modified.
2135///
2136/// # Arguments
2137///
2138/// * `dec`     - Decoder handle.
2139/// * `buf`     - Input bytes.
2140/// * `buf_len` - Length of `buf` in bytes.
2141///
2142/// # Returns
2143///
2144/// * `ALEC_OK` on success.
2145/// * `ALEC_ERROR_NULL_POINTER` for a NULL required pointer.
2146/// * `ALEC_ERROR_CORRUPT_DATA` if `buf` cannot be parsed (bad magic,
2147///   CRC mismatch, truncation, unknown format version).
2148#[cfg(feature = "decoder")]
2149#[no_mangle]
2150pub extern "C" fn alec_decoder_context_load(
2151    dec: *mut AlecDecoder,
2152    buf: *const u8,
2153    buf_len: usize,
2154) -> AlecResult {
2155    if dec.is_null() || buf.is_null() {
2156        return AlecResult::ErrorNullPointer;
2157    }
2158    let data_slice = unsafe { slice::from_raw_parts(buf, buf_len) };
2159    match Context::from_preload_bytes(data_slice) {
2160        Ok(ctx) => {
2161            let d = unsafe { &mut *dec };
2162            d.context = ctx;
2163            AlecResult::Ok
2164        }
2165        Err(_) => AlecResult::ErrorCorruptData,
2166    }
2167}
2168
2169// ============================================================================
2170// Tests
2171// ============================================================================
2172
2173#[cfg(test)]
2174mod tests {
2175    use super::*;
2176    use std::ptr;
2177
2178    #[test]
2179    fn test_version() {
2180        let version = alec_version();
2181        assert!(!version.is_null());
2182        let version_str = unsafe { CStr::from_ptr(version) }.to_str().unwrap();
2183        assert_eq!(version_str, "1.3.10");
2184    }
2185
2186    #[test]
2187    fn test_result_to_string() {
2188        let ok_str = alec_result_to_string(AlecResult::Ok);
2189        assert!(!ok_str.is_null());
2190        let ok = unsafe { CStr::from_ptr(ok_str) }.to_str().unwrap();
2191        assert_eq!(ok, "Success");
2192    }
2193
2194    #[test]
2195    fn test_encoder_lifecycle() {
2196        let enc = alec_encoder_new();
2197        assert!(!enc.is_null());
2198        alec_encoder_free(enc);
2199    }
2200
2201    #[test]
2202    fn test_encoder_free_null() {
2203        // Should not crash
2204        alec_encoder_free(ptr::null_mut());
2205    }
2206
2207    #[test]
2208    fn test_decoder_lifecycle() {
2209        let dec = alec_decoder_new();
2210        assert!(!dec.is_null());
2211        alec_decoder_free(dec);
2212    }
2213
2214    #[test]
2215    fn test_encode_value() {
2216        let enc = alec_encoder_new();
2217        assert!(!enc.is_null());
2218
2219        let mut output = [0u8; 256];
2220        let mut output_len: usize = 0;
2221
2222        let result = alec_encode_value(
2223            enc,
2224            22.5,
2225            1234567890,
2226            ptr::null(),
2227            output.as_mut_ptr(),
2228            output.len(),
2229            &mut output_len,
2230        );
2231
2232        assert_eq!(result, AlecResult::Ok);
2233        assert!(output_len > 0);
2234
2235        alec_encoder_free(enc);
2236    }
2237
2238    #[test]
2239    fn test_encode_null_pointer() {
2240        let mut output = [0u8; 256];
2241        let mut output_len: usize = 0;
2242
2243        let result = alec_encode_value(
2244            ptr::null_mut(),
2245            22.5,
2246            0,
2247            ptr::null(),
2248            output.as_mut_ptr(),
2249            output.len(),
2250            &mut output_len,
2251        );
2252
2253        assert_eq!(result, AlecResult::ErrorNullPointer);
2254    }
2255
2256    #[test]
2257    fn test_encode_multi() {
2258        let enc = alec_encoder_new();
2259        let values: [f64; 4] = [22.0, 22.5, 23.0, 22.8];
2260        let mut output = [0u8; 256];
2261        let mut output_len: usize = 0;
2262
2263        let result = alec_encode_multi(
2264            enc,
2265            values.as_ptr(),
2266            values.len(),
2267            ptr::null(), // timestamps
2268            ptr::null(), // source_ids
2269            ptr::null(), // priorities
2270            output.as_mut_ptr(),
2271            output.len(),
2272            &mut output_len,
2273        );
2274
2275        assert_eq!(result, AlecResult::Ok);
2276        assert!(output_len > 0);
2277
2278        alec_encoder_free(enc);
2279    }
2280
2281    #[test]
2282    fn test_context_version() {
2283        let enc = alec_encoder_new();
2284        let version = alec_encoder_context_version(enc);
2285        assert_eq!(version, 0); // Initial version
2286
2287        // Encode some data to increment version
2288        let mut output = [0u8; 256];
2289        let mut output_len: usize = 0;
2290        alec_encode_value(
2291            enc,
2292            22.5,
2293            0,
2294            ptr::null(),
2295            output.as_mut_ptr(),
2296            output.len(),
2297            &mut output_len,
2298        );
2299
2300        let new_version = alec_encoder_context_version(enc);
2301        assert!(new_version > version);
2302
2303        alec_encoder_free(enc);
2304    }
2305
2306    #[test]
2307    fn test_encoder_with_checksum() {
2308        let enc = alec_encoder_new_with_checksum();
2309        assert!(!enc.is_null());
2310
2311        let mut output = [0u8; 256];
2312        let mut output_len: usize = 0;
2313
2314        let result = alec_encode_value(
2315            enc,
2316            22.5,
2317            0,
2318            ptr::null(),
2319            output.as_mut_ptr(),
2320            output.len(),
2321            &mut output_len,
2322        );
2323
2324        assert_eq!(result, AlecResult::Ok);
2325        alec_encoder_free(enc);
2326    }
2327
2328    #[test]
2329    fn test_encode_value_with_source_id() {
2330        let enc = alec_encoder_new();
2331        let mut output = [0u8; 256];
2332        let mut output_len: usize = 0;
2333
2334        let source = b"temperature\0";
2335        let result = alec_encode_value(
2336            enc,
2337            22.5,
2338            0,
2339            source.as_ptr() as *const c_char,
2340            output.as_mut_ptr(),
2341            output.len(),
2342            &mut output_len,
2343        );
2344
2345        assert_eq!(result, AlecResult::Ok);
2346        assert!(output_len > 0);
2347
2348        // Encoding with NULL source_id should also work (defaults to 0)
2349        let result2 = alec_encode_value(
2350            enc,
2351            22.5,
2352            1,
2353            ptr::null(),
2354            output.as_mut_ptr(),
2355            output.len(),
2356            &mut output_len,
2357        );
2358        assert_eq!(result2, AlecResult::Ok);
2359
2360        alec_encoder_free(enc);
2361    }
2362
2363    #[test]
2364    fn test_hash_source_id() {
2365        // NULL returns 0
2366        assert_eq!(hash_source_id(ptr::null()), 0);
2367
2368        // Non-null returns a deterministic hash in 1..=127 (1-byte varint)
2369        let a = b"temperature\0";
2370        let b = b"pressure\0";
2371        let ha = hash_source_id(a.as_ptr() as *const c_char);
2372        let hb = hash_source_id(b.as_ptr() as *const c_char);
2373        assert!(
2374            ha >= 1 && ha <= 127,
2375            "hash out of 1-byte varint range: {}",
2376            ha
2377        );
2378        assert!(
2379            hb >= 1 && hb <= 127,
2380            "hash out of 1-byte varint range: {}",
2381            hb
2382        );
2383        assert_ne!(ha, hb);
2384
2385        // Same input → same hash
2386        let ha2 = hash_source_id(a.as_ptr() as *const c_char);
2387        assert_eq!(ha, ha2);
2388    }
2389
2390    #[test]
2391    fn test_encode_decode_roundtrip() {
2392        let enc = alec_encoder_new();
2393        let dec = alec_decoder_new();
2394
2395        let original_value = 22.5;
2396        let mut encoded = [0u8; 256];
2397        let mut encoded_len: usize = 0;
2398
2399        // Encode
2400        let result = alec_encode_value(
2401            enc,
2402            original_value,
2403            12345,
2404            ptr::null(),
2405            encoded.as_mut_ptr(),
2406            encoded.len(),
2407            &mut encoded_len,
2408        );
2409        assert_eq!(result, AlecResult::Ok);
2410
2411        // Decode
2412        let mut decoded_value: f64 = 0.0;
2413        let mut decoded_timestamp: u64 = 0;
2414        let result = alec_decode_value(
2415            dec,
2416            encoded.as_ptr(),
2417            encoded_len,
2418            &mut decoded_value,
2419            &mut decoded_timestamp,
2420        );
2421        assert_eq!(result, AlecResult::Ok);
2422        assert!((decoded_value - original_value).abs() < 0.01);
2423
2424        alec_encoder_free(enc);
2425        alec_decoder_free(dec);
2426    }
2427
2428    // ============================================================================
2429    // Bloc A1: Config FFI + keyframe + gap detection
2430    // ============================================================================
2431
2432    #[test]
2433    fn test_encoder_config_defaults_constants() {
2434        // Guard against silent drift of the Milesight-integration defaults.
2435        assert_eq!(ALEC_DEFAULT_HISTORY_SIZE, 20);
2436        assert_eq!(ALEC_DEFAULT_MAX_PATTERNS, 256);
2437        assert_eq!(ALEC_DEFAULT_MAX_MEMORY_BYTES, 2048);
2438        assert_eq!(ALEC_DEFAULT_KEYFRAME_INTERVAL, 50);
2439        assert!(ALEC_DEFAULT_SMART_RESYNC);
2440
2441        let d = AlecEncoderConfig::defaults();
2442        assert_eq!(d.history_size, ALEC_DEFAULT_HISTORY_SIZE);
2443        assert_eq!(d.max_patterns, ALEC_DEFAULT_MAX_PATTERNS);
2444        assert_eq!(d.max_memory_bytes, ALEC_DEFAULT_MAX_MEMORY_BYTES);
2445        assert_eq!(d.keyframe_interval, ALEC_DEFAULT_KEYFRAME_INTERVAL);
2446        assert!(d.smart_resync);
2447    }
2448
2449    #[test]
2450    fn test_encoder_new_with_config_null_uses_defaults() {
2451        let enc = alec_encoder_new_with_config(ptr::null());
2452        assert!(!enc.is_null());
2453        let e = unsafe { &*enc };
2454        assert_eq!(e.keyframe_interval, ALEC_DEFAULT_KEYFRAME_INTERVAL);
2455        assert!(e.smart_resync);
2456        assert!(!e.force_keyframe_pending);
2457        assert_eq!(e.messages_since_keyframe, 0);
2458        alec_encoder_free(enc);
2459    }
2460
2461    #[test]
2462    fn test_encoder_new_with_config_custom() {
2463        let cfg = AlecEncoderConfig {
2464            history_size: 10,
2465            max_patterns: 128,
2466            max_memory_bytes: 1024,
2467            keyframe_interval: 25,
2468            smart_resync: false,
2469            num_channels: 0,
2470        };
2471        let enc = alec_encoder_new_with_config(&cfg);
2472        assert!(!enc.is_null());
2473        let e = unsafe { &*enc };
2474        assert_eq!(e.keyframe_interval, 25);
2475        assert!(!e.smart_resync);
2476        alec_encoder_free(enc);
2477    }
2478
2479    #[test]
2480    fn test_encoder_new_with_config_zero_uses_defaults() {
2481        // Numeric fields set to 0 (except keyframe_interval) should
2482        // fall back to the Milesight defaults.
2483        let cfg = AlecEncoderConfig {
2484            history_size: 0,
2485            max_patterns: 0,
2486            max_memory_bytes: 0,
2487            keyframe_interval: 0, // 0 means "disabled", kept as-is
2488            smart_resync: true,
2489            num_channels: 0,
2490        };
2491        let enc = alec_encoder_new_with_config(&cfg);
2492        assert!(!enc.is_null());
2493        let e = unsafe { &*enc };
2494        // keyframe_interval=0 must be preserved verbatim (disabled).
2495        assert_eq!(e.keyframe_interval, 0);
2496        // Encoding should still succeed — history/patterns/memory got defaults.
2497        let mut output = [0u8; 256];
2498        let mut output_len: usize = 0;
2499        let result = alec_encode_value(
2500            enc,
2501            22.5,
2502            0,
2503            ptr::null(),
2504            output.as_mut_ptr(),
2505            output.len(),
2506            &mut output_len,
2507        );
2508        assert_eq!(result, AlecResult::Ok);
2509        alec_encoder_free(enc);
2510    }
2511
2512    #[test]
2513    fn test_force_keyframe_sets_flag() {
2514        let enc = alec_encoder_new();
2515        assert!(!enc.is_null());
2516        assert!(!unsafe { &*enc }.force_keyframe_pending);
2517        alec_force_keyframe(enc);
2518        assert!(unsafe { &*enc }.force_keyframe_pending);
2519        alec_encoder_free(enc);
2520    }
2521
2522    #[test]
2523    fn test_force_keyframe_null_is_noop() {
2524        // Must not crash on NULL.
2525        alec_force_keyframe(ptr::null_mut());
2526    }
2527
2528    #[test]
2529    fn test_force_keyframe_respects_smart_resync_disabled() {
2530        let cfg = AlecEncoderConfig {
2531            history_size: 0,
2532            max_patterns: 0,
2533            max_memory_bytes: 0,
2534            keyframe_interval: 50,
2535            smart_resync: false,
2536            num_channels: 0,
2537        };
2538        let enc = alec_encoder_new_with_config(&cfg);
2539        alec_force_keyframe(enc);
2540        // smart_resync=false → force_keyframe is a no-op.
2541        assert!(!unsafe { &*enc }.force_keyframe_pending);
2542        alec_encoder_free(enc);
2543    }
2544
2545    #[test]
2546    fn test_gap_detected_null_decoder() {
2547        let mut gap: u8 = 42;
2548        let detected = alec_decoder_gap_detected(ptr::null(), &mut gap);
2549        assert!(!detected);
2550        assert_eq!(gap, 0);
2551
2552        // NULL out_gap_size is also fine.
2553        let detected2 = alec_decoder_gap_detected(ptr::null(), ptr::null_mut());
2554        assert!(!detected2);
2555    }
2556
2557    #[test]
2558    fn test_gap_detected_fresh_decoder() {
2559        // No decode has happened yet — no gap.
2560        let dec = alec_decoder_new();
2561        let mut gap: u8 = 99;
2562        let detected = alec_decoder_gap_detected(dec, &mut gap);
2563        assert!(!detected);
2564        assert_eq!(gap, 0);
2565        alec_decoder_free(dec);
2566    }
2567
2568    /// End-to-end: encode 5 multi-frames, drop two between frame #1 and #2
2569    /// from the decoder's perspective, verify the gap is reported.
2570    #[test]
2571    fn test_gap_detected_after_dropped_frames() {
2572        let enc = alec_encoder_new();
2573        let dec = alec_decoder_new();
2574
2575        let values: [f64; 4] = [22.0, 22.5, 23.0, 22.8];
2576        let mut frames: Vec<Vec<u8>> = Vec::new();
2577        for _ in 0..5 {
2578            let mut out = [0u8; 128];
2579            let mut out_len = 0usize;
2580            let res = alec_encode_multi(
2581                enc,
2582                values.as_ptr(),
2583                values.len(),
2584                ptr::null(),
2585                ptr::null(),
2586                ptr::null(),
2587                out.as_mut_ptr(),
2588                out.len(),
2589                &mut out_len,
2590            );
2591            assert_eq!(res, AlecResult::Ok);
2592            frames.push(out[..out_len].to_vec());
2593        }
2594
2595        // Decode frame 0 (no gap yet).
2596        let mut vals = [0f64; 4];
2597        let mut vcount: usize = 0;
2598        let r0 = alec_decode_multi(
2599            dec,
2600            frames[0].as_ptr(),
2601            frames[0].len(),
2602            vals.as_mut_ptr(),
2603            vals.len(),
2604            &mut vcount,
2605        );
2606        assert_eq!(r0, AlecResult::Ok);
2607        let mut gap: u8 = 0;
2608        assert!(!alec_decoder_gap_detected(dec, &mut gap));
2609        assert_eq!(gap, 0);
2610
2611        // Skip frames 1 and 2, decode frame 3 → gap of 2.
2612        let r3 = alec_decode_multi(
2613            dec,
2614            frames[3].as_ptr(),
2615            frames[3].len(),
2616            vals.as_mut_ptr(),
2617            vals.len(),
2618            &mut vcount,
2619        );
2620        assert_eq!(r3, AlecResult::Ok);
2621        let mut gap: u8 = 0;
2622        assert!(alec_decoder_gap_detected(dec, &mut gap));
2623        assert_eq!(gap, 2);
2624
2625        // Decode frame 4 — contiguous with frame 3 → no gap.
2626        let r4 = alec_decode_multi(
2627            dec,
2628            frames[4].as_ptr(),
2629            frames[4].len(),
2630            vals.as_mut_ptr(),
2631            vals.len(),
2632            &mut vcount,
2633        );
2634        assert_eq!(r4, AlecResult::Ok);
2635        let mut gap: u8 = 99;
2636        assert!(!alec_decoder_gap_detected(dec, &mut gap));
2637        assert_eq!(gap, 0);
2638
2639        alec_encoder_free(enc);
2640        alec_decoder_free(dec);
2641    }
2642
2643    /// cbindgen should surface the new symbols. This test is a compile-time
2644    /// guarantee that the FFI entry points exist with the expected signatures.
2645    #[test]
2646    fn test_ffi_symbols_exist() {
2647        let _new: extern "C" fn(*const AlecEncoderConfig) -> *mut AlecEncoder =
2648            alec_encoder_new_with_config;
2649        let _force: extern "C" fn(*mut AlecEncoder) = alec_force_keyframe;
2650        let _gap: extern "C" fn(*const AlecDecoder, *mut u8) -> bool = alec_decoder_gap_detected;
2651        let _enc_fixed: extern "C" fn(
2652            *mut AlecEncoder,
2653            *const f64,
2654            usize,
2655            *mut u8,
2656            usize,
2657            *mut usize,
2658        ) -> AlecResult = alec_encode_multi_fixed;
2659        let _dec_fixed: extern "C" fn(
2660            *mut AlecDecoder,
2661            *const u8,
2662            usize,
2663            *mut f64,
2664            usize,
2665            *mut usize,
2666            *mut u16,
2667            *mut bool,
2668        ) -> AlecResult = alec_decode_multi_fixed;
2669        let _dec_new_cfg: extern "C" fn(*const AlecEncoderConfig) -> *mut AlecDecoder =
2670            alec_decoder_new_with_config;
2671        let _dec_reset: extern "C" fn(*mut AlecDecoder) = alec_decoder_reset;
2672        let _ctx_save: extern "C" fn(*const AlecDecoder, *mut u8, usize, *mut usize) -> AlecResult =
2673            alec_decoder_context_save;
2674        let _ctx_load: extern "C" fn(*mut AlecDecoder, *const u8, usize) -> AlecResult =
2675            alec_decoder_context_load;
2676    }
2677
2678    // ========================================================================
2679    // Bloc B5 — Compact fixed-channel tests
2680    //
2681    // A synthesized slow-drift EM500-CO2 dataset is used in lieu of a
2682    // 99-message CSV that is not shipped with the repo. The dataset is
2683    // built to reproduce the regime described in docs/CONTEXT.md:
2684    //   - 5 channels: battery / temperature / humidity / CO2 / pressure
2685    //   - 99 messages at a 10-minute cadence
2686    //   - slow drift on all channels → most channels encode as Repeated
2687    //     or Delta8 in steady state
2688    // ========================================================================
2689
2690    /// Deterministic 99-message EM500-CO2 slow-drift dataset.
2691    ///
2692    /// Real EM500-CO2 sensors are polled every 10 minutes on a very
2693    /// slow-drift signal. The raw sensor has coarse quantization
2694    /// (battery 0.001V, temperature 0.01°C, humidity 0.1%, CO2 1ppm,
2695    /// pressure 0.01hPa) and values typically REPEAT across many
2696    /// consecutive reads. This dataset reproduces that regime with
2697    /// step changes that are rare and small (≤1 quantization step),
2698    /// matching the ~58% Repeated / ~42% Delta8 distribution cited
2699    /// in docs/CONTEXT.md.
2700    fn em500_co2_dataset() -> Vec<[f64; 5]> {
2701        const N: usize = 99;
2702        let mut out = Vec::with_capacity(N);
2703        // Values change rarely; most frames carry exact repeats.
2704        // Channel 0: battery (V). Drops by 1mV every ~33 frames.
2705        // Channel 1: temperature (°C). Walks ±0.01 every ~4 frames.
2706        // Channel 2: humidity (%). Walks ±0.1 every ~7 frames.
2707        // Channel 3: CO2 (ppm). +1 ppm every ~3 frames (slow ramp).
2708        // Channel 4: pressure (hPa). ±0.01 every ~11 frames.
2709        for i in 0..N {
2710            // Battery at 10mV granularity (real LoRaWAN battery
2711            // telemetry — devices don't change 1mV in 10 minutes,
2712            // and scale_factor=100 can't represent sub-0.01V anyway).
2713            let battery = 3.60 - 0.01 * ((i / 33) as f64);
2714            let temp_step = if i % 8 < 4 { 0.01 } else { 0.00 };
2715            let temperature = 22.50 + temp_step;
2716            let humidity = 45.0 + 0.1 * ((i / 7) % 3) as f64;
2717            let co2 = 420.0 + (i / 3) as f64;
2718            let pressure = 1013.25 + 0.01 * ((i / 11) % 3) as f64;
2719            out.push([battery, temperature, humidity, co2, pressure]);
2720        }
2721        out
2722    }
2723
2724    /// Run the whole dataset through a fresh encoder+decoder pair and
2725    /// return (per-frame wire bytes, per-frame decoded values).
2726    fn encode_decode_dataset(
2727        data: &[[f64; 5]],
2728        cfg: Option<AlecEncoderConfig>,
2729    ) -> (Vec<Vec<u8>>, Vec<[f64; 5]>) {
2730        let enc = match cfg {
2731            Some(c) => alec_encoder_new_with_config(&c),
2732            None => alec_encoder_new(),
2733        };
2734        let dec = alec_decoder_new();
2735
2736        let mut frames = Vec::with_capacity(data.len());
2737        let mut decoded = Vec::with_capacity(data.len());
2738
2739        let mut out = [0u8; 128];
2740        let mut out_len: usize = 0;
2741        let mut values = [0f64; 5];
2742
2743        for row in data {
2744            let r = alec_encode_multi_fixed(
2745                enc,
2746                row.as_ptr(),
2747                row.len(),
2748                out.as_mut_ptr(),
2749                out.len(),
2750                &mut out_len,
2751            );
2752            assert_eq!(r, AlecResult::Ok);
2753            let frame = out[..out_len].to_vec();
2754
2755            let r2 = alec_decode_multi_fixed(
2756                dec,
2757                frame.as_ptr(),
2758                frame.len(),
2759                values.as_mut_ptr(),
2760                values.len(),
2761                ptr::null_mut(),
2762                ptr::null_mut(),
2763                ptr::null_mut(),
2764            );
2765            assert_eq!(
2766                r2,
2767                AlecResult::Ok,
2768                "decode failed at frame {}",
2769                frames.len()
2770            );
2771
2772            frames.push(frame);
2773            decoded.push(values);
2774        }
2775
2776        alec_encoder_free(enc);
2777        alec_decoder_free(dec);
2778        (frames, decoded)
2779    }
2780
2781    /// B5-1. Encode 99 real-shaped EM500-CO2 rows through the FFI,
2782    /// decode each frame, and verify the values round-trip within
2783    /// one quantization step.
2784    ///
2785    /// Delta encoding uses a global scale_factor of 100 (1/100
2786    /// resolution), so each frame carries ≤0.005 of quantization
2787    /// error per channel. The moving-average prediction residue on
2788    /// top of that is bounded by the history EMA alpha — with
2789    /// slow-drift inputs the combined error stays well under
2790    /// `0.01` (one quantization step).
2791    #[test]
2792    fn test_encode_decode_fixed_roundtrip_5ch() {
2793        let data = em500_co2_dataset();
2794        let (_frames, decoded) = encode_decode_dataset(&data, None);
2795        assert_eq!(decoded.len(), data.len());
2796        // Allowed drift is expressed in units of each channel's
2797        // native sensor resolution at `scale_factor=100` granularity:
2798        //   battery  0.01 V (LoRaWAN 10mV telemetry)
2799        //   temp     0.01 °C
2800        //   humidity 0.1 %
2801        //   CO2      1 ppm
2802        //   pressure 0.01 hPa
2803        // We allow ≤ 1 physical LSB of drift on every channel, which
2804        // is effectively lossless at the application level.
2805        let max_drift = [0.01_f64, 0.01, 0.1, 1.0, 0.01];
2806        for (i, (src, dst)) in data.iter().zip(decoded.iter()).enumerate() {
2807            for ch in 0..5 {
2808                let diff = (src[ch] - dst[ch]).abs();
2809                assert!(
2810                    diff <= max_drift[ch] + 1e-9,
2811                    "frame {} ch {}: expected {}, got {}, diff {} (max {})",
2812                    i,
2813                    ch,
2814                    src[ch],
2815                    dst[ch],
2816                    diff,
2817                    max_drift[ch]
2818                );
2819            }
2820        }
2821    }
2822
2823    /// B5-2. Property: from message 8 onward, the compact wire
2824    /// frame must fit in the 11-byte LoRaWAN ceiling on the slow-drift
2825    /// EM500-CO2 profile.
2826    #[test]
2827    fn test_fixed_header_11b_ceiling() {
2828        let data = em500_co2_dataset();
2829        // Use a large keyframe_interval to stop periodic keyframes
2830        // from interfering with the steady-state size assertion.
2831        let cfg = AlecEncoderConfig {
2832            history_size: 0,
2833            max_patterns: 0,
2834            max_memory_bytes: 0,
2835            keyframe_interval: 10_000,
2836            smart_resync: false,
2837            num_channels: 0,
2838        };
2839        let (frames, _decoded) = encode_decode_dataset(&data, Some(cfg));
2840
2841        // Skip the warm-up window. Message 0 has no prediction at all,
2842        // and a handful of subsequent messages still produce Raw32 for
2843        // a channel while the per-source EMA settles. Docs/CONTEXT.md
2844        // assumes frames from ~#8 onward are steady-state.
2845        let warmup = 8;
2846        for (i, frame) in frames.iter().enumerate().skip(warmup) {
2847            assert!(
2848                frame.len() <= 11,
2849                "frame #{} was {} bytes > 11B ceiling",
2850                i,
2851                frame.len()
2852            );
2853        }
2854    }
2855
2856    /// B5-3. The very first frame has no prediction history available
2857    /// so every channel falls back to Raw32 — this frame is expected
2858    /// to exceed the 11-byte LoRaWAN ceiling, and the caller must
2859    /// detect that and send a legacy TLV frame instead.
2860    #[test]
2861    fn test_cold_start_first_frame() {
2862        let data = em500_co2_dataset();
2863        let enc = alec_encoder_new();
2864        let mut out = [0u8; 64];
2865        let mut out_len: usize = 0;
2866        let r = alec_encode_multi_fixed(
2867            enc,
2868            data[0].as_ptr(),
2869            data[0].len(),
2870            out.as_mut_ptr(),
2871            out.len(),
2872            &mut out_len,
2873        );
2874        assert_eq!(r, AlecResult::Ok);
2875
2876        // Layout: 1B marker + 4B header + 2B bitmap (5 ch × 2 bits = 10 bits)
2877        //         + 5 × 4B Raw32 = 27 bytes exactly.
2878        assert_eq!(out_len, 27, "cold-start frame should be 27B");
2879        assert!(out_len > 11, "cold-start frame must exceed 11B ceiling");
2880        // Marker is the data marker (cold start frame is NOT a keyframe —
2881        // the FFI only emits 0xA2 when the force/periodic rules fire).
2882        assert_eq!(out[0], 0xA1);
2883        alec_encoder_free(enc);
2884    }
2885
2886    /// B5-4. Context version truncates u32 → u16 and wraps at 65535.
2887    /// The decoder must accept the wrap without flagging a mismatch.
2888    #[test]
2889    fn test_ctx_ver_wraparound() {
2890        // Start the encoder's context just below the wrap boundary.
2891        let enc = alec_encoder_new();
2892        let dec = alec_decoder_new();
2893
2894        unsafe {
2895            (*enc).context.set_version(65530);
2896            (*dec).context.set_version(65530);
2897        }
2898
2899        let row = [3.6, 22.5, 45.0, 420.0, 1013.25];
2900        let mut out = [0u8; 64];
2901        let mut out_len: usize = 0;
2902        let mut values = [0f64; 5];
2903
2904        let mut seen_pre_wrap = false;
2905        let mut seen_post_wrap = false;
2906        // Each encode-step observes 5 channels → +5 ctx_version per frame.
2907        // 10 frames × 5 obs = 50 obs → passes through 65535 → 0.
2908        for i in 0..10 {
2909            let r = alec_encode_multi_fixed(
2910                enc,
2911                row.as_ptr(),
2912                row.len(),
2913                out.as_mut_ptr(),
2914                out.len(),
2915                &mut out_len,
2916            );
2917            assert_eq!(r, AlecResult::Ok);
2918
2919            // Read the wire context_version.
2920            let cv = u16::from_be_bytes([out[3], out[4]]);
2921            if cv > 60_000 {
2922                seen_pre_wrap = true;
2923            }
2924            if cv < 1_000 {
2925                seen_post_wrap = true;
2926            }
2927
2928            let r2 = alec_decode_multi_fixed(
2929                dec,
2930                out.as_ptr(),
2931                out_len,
2932                values.as_mut_ptr(),
2933                values.len(),
2934                ptr::null_mut(),
2935                ptr::null_mut(),
2936                ptr::null_mut(),
2937            );
2938            assert_eq!(
2939                r2,
2940                AlecResult::Ok,
2941                "decode failed at wrap boundary, frame {}",
2942                i
2943            );
2944        }
2945
2946        assert!(seen_pre_wrap, "never observed a ctx_ver near the wrap edge");
2947        assert!(seen_post_wrap, "ctx_ver never wrapped to a low value");
2948
2949        alec_encoder_free(enc);
2950        alec_decoder_free(dec);
2951    }
2952
2953    /// B5-5. A non-ALEC first byte (e.g. the legacy TLV header byte)
2954    /// must return a clean error, NOT panic.
2955    #[test]
2956    fn test_marker_byte_dispatch() {
2957        let data = em500_co2_dataset();
2958        let enc = alec_encoder_new();
2959        let dec = alec_decoder_new();
2960
2961        let mut out = [0u8; 64];
2962        let mut out_len: usize = 0;
2963        let r = alec_encode_multi_fixed(
2964            enc,
2965            data[0].as_ptr(),
2966            data[0].len(),
2967            out.as_mut_ptr(),
2968            out.len(),
2969            &mut out_len,
2970        );
2971        assert_eq!(r, AlecResult::Ok);
2972        assert_eq!(out[0], 0xA1); // regular data marker
2973
2974        // 0xA1 frame decodes successfully.
2975        let mut values = [0f64; 5];
2976        let r_ok = alec_decode_multi_fixed(
2977            dec,
2978            out.as_ptr(),
2979            out_len,
2980            values.as_mut_ptr(),
2981            values.len(),
2982            ptr::null_mut(),
2983            ptr::null_mut(),
2984            ptr::null_mut(),
2985        );
2986        assert_eq!(r_ok, AlecResult::Ok);
2987
2988        // Corrupt marker to a known-not-ALEC byte (legacy TLV first
2989        // byte is 0x7A for MessageType::DataFixedChannel but a
2990        // production TLV message begins with 0x5A = Data | P3 | v1).
2991        let mut corrupt = out[..out_len].to_vec();
2992        corrupt[0] = 0x5A;
2993        let r_err = alec_decode_multi_fixed(
2994            alec_decoder_new(), // fresh decoder so prior state doesn't leak
2995            corrupt.as_ptr(),
2996            corrupt.len(),
2997            values.as_mut_ptr(),
2998            values.len(),
2999            ptr::null_mut(),
3000            ptr::null_mut(),
3001            ptr::null_mut(),
3002        );
3003        assert_eq!(r_err, AlecResult::ErrorInvalidInput);
3004
3005        alec_encoder_free(enc);
3006        alec_decoder_free(dec);
3007    }
3008
3009    /// B5-6. With `keyframe_interval=10` on a stable signal, the
3010    /// frames at interval boundaries must be larger (Raw32 for all
3011    /// channels) while the in-between frames should be compact
3012    /// (mostly Repeated/Delta8).
3013    #[test]
3014    fn test_keyframe_forced_at_interval() {
3015        let cfg = AlecEncoderConfig {
3016            history_size: 0,
3017            max_patterns: 0,
3018            max_memory_bytes: 0,
3019            keyframe_interval: 10,
3020            smart_resync: true,
3021            num_channels: 0,
3022        };
3023        let enc = alec_encoder_new_with_config(&cfg);
3024        // Stable signal: identical row every frame.
3025        let row = [3.6, 22.5, 45.0, 420.0, 1013.25];
3026        let mut out = [0u8; 64];
3027        let mut out_len: usize = 0;
3028        let mut frames: Vec<(usize, u8)> = Vec::new();
3029
3030        for _ in 0..25 {
3031            let r = alec_encode_multi_fixed(
3032                enc,
3033                row.as_ptr(),
3034                row.len(),
3035                out.as_mut_ptr(),
3036                out.len(),
3037                &mut out_len,
3038            );
3039            assert_eq!(r, AlecResult::Ok);
3040            frames.push((out_len, out[0]));
3041        }
3042
3043        // Layout sizes for 5 channels:
3044        //   keyframe (Raw32 ×5) = 1 + 4 + 2 + 20 = 27 bytes, marker 0xA2
3045        //   steady   (Repeated ×5) = 1 + 4 + 2 + 0 = 7 bytes, marker 0xA1
3046        let keyframe_indices: Vec<usize> = frames
3047            .iter()
3048            .enumerate()
3049            .filter(|(_, (_, m))| *m == 0xA2)
3050            .map(|(i, _)| i)
3051            .collect();
3052
3053        // Frame #10 and #20 are the interval boundaries (counter reaches 10).
3054        assert_eq!(keyframe_indices, vec![10, 20]);
3055        for (i, (len, marker)) in frames.iter().enumerate() {
3056            if *marker == 0xA2 {
3057                assert_eq!(*len, 27, "keyframe at #{} should be 27B, got {}", i, *len);
3058            } else {
3059                assert_eq!(*marker, 0xA1);
3060                // Frame 0 is the cold-start Raw32 frame (27B).
3061                if i == 0 {
3062                    assert_eq!(*len, 27);
3063                } else {
3064                    assert!(*len <= 11, "data frame at #{} is {} bytes > 11B", i, *len);
3065                }
3066            }
3067        }
3068
3069        alec_encoder_free(enc);
3070    }
3071
3072    /// Diagnostic (ignored by default) — prints per-frame sizes and
3073    /// encoding distribution for the synthesized EM500-CO2 dataset.
3074    /// Run with `cargo test -p alec-ffi diag_fixed_sizes -- --ignored --nocapture`.
3075    #[test]
3076    #[ignore]
3077    fn diag_fixed_sizes() {
3078        let data = em500_co2_dataset();
3079        // Disable periodic keyframes so the observed sizes reflect
3080        // pure steady-state encoding.
3081        let cfg = AlecEncoderConfig {
3082            history_size: 0,
3083            max_patterns: 0,
3084            max_memory_bytes: 0,
3085            keyframe_interval: 10_000,
3086            smart_resync: false,
3087            num_channels: 0,
3088        };
3089        let (frames, _) = encode_decode_dataset(&data, Some(cfg));
3090        let mut counts = [0u32; 4]; // Repeated, Delta8, Delta16, Raw32
3091        for frame in &frames {
3092            // 5 channels → 2 bitmap bytes starting at offset 5.
3093            let b0 = frame[5];
3094            let b1 = frame[6];
3095            for i in 0..5 {
3096                let bits = if i < 4 { (b0 >> (i * 2)) & 3 } else { b1 & 3 };
3097                counts[bits as usize] += 1;
3098            }
3099        }
3100        let total_ch = 99 * 5;
3101        println!("\n=== FIXED-CHANNEL DIAGNOSTIC ===");
3102        let sizes: Vec<usize> = frames.iter().map(|f| f.len()).collect();
3103        let total: usize = sizes.iter().sum();
3104        println!(
3105            "99 frames: total={} avg={:.2} B/frame  min={} max={}",
3106            total,
3107            total as f64 / 99.0,
3108            sizes.iter().min().unwrap(),
3109            sizes.iter().max().unwrap()
3110        );
3111        let warm = 8;
3112        let steady: Vec<usize> = sizes[warm..].to_vec();
3113        let stotal: usize = steady.iter().sum();
3114        println!(
3115            "steady (frame>={}): total={} avg={:.2} B/frame  max={}",
3116            warm,
3117            stotal,
3118            stotal as f64 / steady.len() as f64,
3119            steady.iter().max().unwrap()
3120        );
3121        let labels = ["Repeated", "Delta8", "Delta16", "Raw32"];
3122        println!("encoding distribution across {} channels:", total_ch);
3123        for i in 0..4 {
3124            println!(
3125                "  {:10}: {:4}  ({:.1}%)",
3126                labels[i],
3127                counts[i],
3128                100.0 * counts[i] as f64 / total_ch as f64
3129            );
3130        }
3131        // Dump a typical steady-state frame.
3132        let idx = 30;
3133        println!(
3134            "Frame #{}: {} bytes = {:02X?}",
3135            idx,
3136            frames[idx].len(),
3137            &frames[idx][..]
3138        );
3139    }
3140
3141    /// B5-7. `alec_force_keyframe` forces the very next frame to be
3142    /// a keyframe (marker 0xA2, Raw32 for every channel), and the
3143    /// frame after that returns to the compact encoding.
3144    #[test]
3145    fn test_force_keyframe_ffi() {
3146        let cfg = AlecEncoderConfig {
3147            history_size: 0,
3148            max_patterns: 0,
3149            max_memory_bytes: 0,
3150            keyframe_interval: 10_000, // avoid periodic keyframes
3151            smart_resync: true,
3152            num_channels: 0,
3153        };
3154        let enc = alec_encoder_new_with_config(&cfg);
3155        let row = [3.6, 22.5, 45.0, 420.0, 1013.25];
3156        let mut out = [0u8; 64];
3157        let mut out_len: usize = 0;
3158
3159        // Warm up the context with a few stable frames.
3160        for _ in 0..5 {
3161            let r = alec_encode_multi_fixed(
3162                enc,
3163                row.as_ptr(),
3164                row.len(),
3165                out.as_mut_ptr(),
3166                out.len(),
3167                &mut out_len,
3168            );
3169            assert_eq!(r, AlecResult::Ok);
3170        }
3171        // After warm-up the frame is compact (data marker).
3172        assert_eq!(out[0], 0xA1);
3173        let warm_len = out_len;
3174        assert!(
3175            warm_len <= 11,
3176            "warm frame should be <=11B, got {}",
3177            warm_len
3178        );
3179
3180        // Downlink-style force: next encode must be a keyframe.
3181        alec_force_keyframe(enc);
3182        let r = alec_encode_multi_fixed(
3183            enc,
3184            row.as_ptr(),
3185            row.len(),
3186            out.as_mut_ptr(),
3187            out.len(),
3188            &mut out_len,
3189        );
3190        assert_eq!(r, AlecResult::Ok);
3191        assert_eq!(out[0], 0xA2, "forced frame must carry the keyframe marker");
3192        assert_eq!(
3193            out_len, 27,
3194            "forced keyframe must be Raw32 for all channels"
3195        );
3196
3197        // The frame after the keyframe must be compact again.
3198        let r = alec_encode_multi_fixed(
3199            enc,
3200            row.as_ptr(),
3201            row.len(),
3202            out.as_mut_ptr(),
3203            out.len(),
3204            &mut out_len,
3205        );
3206        assert_eq!(r, AlecResult::Ok);
3207        assert_eq!(out[0], 0xA1, "post-keyframe frame must be a data frame");
3208        assert!(
3209            out_len <= 11,
3210            "post-keyframe frame should be <=11B, got {}",
3211            out_len
3212        );
3213
3214        alec_encoder_free(enc);
3215    }
3216
3217    // ========================================================================
3218    // Bloc C5 — Packet-loss recovery tests
3219    // ========================================================================
3220
3221    /// Helper: build a matched encoder + decoder pair with
3222    /// a small keyframe_interval suitable for test runtime.
3223    fn new_pair(keyframe_interval: u32) -> (*mut AlecEncoder, *mut AlecDecoder) {
3224        let cfg = AlecEncoderConfig {
3225            history_size: 0,
3226            max_patterns: 0,
3227            max_memory_bytes: 0,
3228            keyframe_interval,
3229            smart_resync: true,
3230            num_channels: 0,
3231        };
3232        (alec_encoder_new_with_config(&cfg), alec_decoder_new())
3233    }
3234
3235    /// Encode one frame on `enc` into `out` and return its length.
3236    fn do_encode(enc: *mut AlecEncoder, row: &[f64; 5], out: &mut [u8; 64]) -> usize {
3237        let mut n: usize = 0;
3238        let r = alec_encode_multi_fixed(
3239            enc,
3240            row.as_ptr(),
3241            row.len(),
3242            out.as_mut_ptr(),
3243            out.len(),
3244            &mut n,
3245        );
3246        assert_eq!(r, AlecResult::Ok);
3247        n
3248    }
3249
3250    /// Decode `frame` on `dec`. Returns the decoded values.
3251    fn do_decode(dec: *mut AlecDecoder, frame: &[u8]) -> [f64; 5] {
3252        let mut values = [0f64; 5];
3253        let r = alec_decode_multi_fixed(
3254            dec,
3255            frame.as_ptr(),
3256            frame.len(),
3257            values.as_mut_ptr(),
3258            values.len(),
3259            ptr::null_mut(),
3260            ptr::null_mut(),
3261            ptr::null_mut(),
3262        );
3263        assert_eq!(r, AlecResult::Ok);
3264        values
3265    }
3266
3267    /// C5-1. `reset_to_baseline` wipes per-channel prediction state
3268    /// so the next encode can only fall back to Raw32 (no prediction
3269    /// to delta against). Existing patterns in the dictionary are
3270    /// preserved (the FFI path never registers any, so the dict is
3271    /// empty to begin with — but the contract matters for preloaded
3272    /// contexts).
3273    #[test]
3274    fn test_reset_to_baseline_wipes_stats() {
3275        let (enc, _dec) = new_pair(10_000); // no periodic keyframes
3276        let row = [3.60, 22.50, 45.0, 420.0, 1013.25];
3277        let mut out = [0u8; 64];
3278
3279        // Build up 20 frames of prediction state.
3280        for _ in 0..20 {
3281            do_encode(enc, &row, &mut out);
3282        }
3283        // Context should now hold non-trivial state.
3284        let e = unsafe { &*enc };
3285        assert!(e.context.last_value(1).is_some());
3286        assert!(e.context.last_value(5).is_some());
3287        let pre_version = e.context.version();
3288
3289        // Reset.
3290        unsafe { &mut *enc }.context.reset_to_baseline();
3291
3292        // All per-channel last_value are cleared — but the version
3293        // counter is preserved (see C1 contract).
3294        let e = unsafe { &*enc };
3295        assert!(e.context.last_value(1).is_none());
3296        assert!(e.context.last_value(5).is_none());
3297        assert_eq!(e.context.version(), pre_version);
3298
3299        // Next encode, with no prediction available, must fall back
3300        // to Raw32 on every channel — same wire shape as a keyframe
3301        // (minus the 0xA2 marker, since this is a regular frame).
3302        // Layout: 1 marker + 4 header + 2 bitmap + 5×Raw32 = 27 B.
3303        let n = do_encode(enc, &row, &mut out);
3304        assert_eq!(n, 27, "post-reset frame must be Raw32-all-channels (27 B)");
3305        assert_eq!(out[0], 0xA1);
3306        let b0 = out[5];
3307        let b1 = out[6];
3308        // All bitmap bits = 0b11 = Raw32.
3309        assert_eq!(b0, 0b1111_1111);
3310        assert_eq!(b1 & 0b11, 0b11);
3311
3312        alec_encoder_free(enc);
3313    }
3314
3315    /// C5-2. Simulate a 4-frame gap (encoder produces frames 0..=20
3316    /// but frames 15..=18 never reach the decoder). On frame 19 the
3317    /// decoder must detect gap_size=4 and trigger a reset; full
3318    /// recovery must happen at the next periodic keyframe (frame 20
3319    /// with keyframe_interval=10).
3320    #[test]
3321    fn test_packet_loss_recovery_at_keyframe() {
3322        let (enc, dec) = new_pair(10);
3323        let row = [3.60, 22.50, 45.0, 420.0, 1013.25];
3324        let mut out = [0u8; 64];
3325        let mut frames: Vec<Vec<u8>> = Vec::new();
3326
3327        // Encode 21 frames (0..=20). Frame 10 and 20 are keyframes.
3328        for _ in 0..=20 {
3329            let n = do_encode(enc, &row, &mut out);
3330            frames.push(out[..n].to_vec());
3331        }
3332        assert_eq!(frames[10][0], 0xA2, "frame 10 must be a keyframe");
3333        assert_eq!(frames[20][0], 0xA2, "frame 20 must be a keyframe");
3334
3335        // Decode frames 0..=14 normally.
3336        for f in &frames[0..=14] {
3337            do_decode(dec, f);
3338        }
3339        // Do NOT decode frames 15..=18 — simulate 4 dropped uplinks.
3340
3341        // Decode frame 19 → gap_size = 4 reported, reset triggered.
3342        do_decode(dec, &frames[19]);
3343        let mut gap: u8 = 0;
3344        assert!(alec_decoder_gap_detected(dec, &mut gap));
3345        assert_eq!(gap, 4, "decoder must report 4-frame gap");
3346
3347        // After the reset, the decoder's last_value is cleared for
3348        // every channel, so any subsequent Delta/Repeated-encoded
3349        // frame would error out. Frame 19 itself does NOT error
3350        // because we observe the decoded values *after* the reset
3351        // (re-seeding the context from frame 19's output).
3352
3353        // Frame 20 is a keyframe — Raw32 for every channel, so it
3354        // decodes correctly regardless of context state, and it
3355        // re-synchronises the decoder for good.
3356        let values_20 = do_decode(dec, &frames[20]);
3357        for (ch, &v) in row.iter().enumerate() {
3358            let tol = [0.01_f64, 0.01, 0.1, 1.0, 0.01][ch];
3359            assert!(
3360                (v - values_20[ch]).abs() <= tol,
3361                "ch {}: expected {}, got {}",
3362                ch,
3363                v,
3364                values_20[ch]
3365            );
3366        }
3367
3368        alec_encoder_free(enc);
3369        alec_decoder_free(dec);
3370    }
3371
3372    /// C5-3. No silent corruption: when the encoder emits a stable
3373    /// signal and the decoder drops frame 20, subsequent frames
3374    /// 21..=49 are either clearly divergent or clearly re-synced
3375    /// by the next keyframe at frame 50. Frame 50+ MUST decode
3376    /// within sensor resolution.
3377    #[test]
3378    fn test_no_silent_corruption() {
3379        let (enc, dec) = new_pair(50);
3380        let mut out = [0u8; 64];
3381        let mut frames: Vec<Vec<u8>> = Vec::new();
3382        // Slow-drift signal — mostly Repeated, occasional Delta8.
3383        let rows: Vec<[f64; 5]> = (0..100)
3384            .map(|i| [3.60, 22.50, 45.0, 420.0 + (i / 3) as f64, 1013.25])
3385            .collect();
3386        for row in &rows {
3387            let n = do_encode(enc, row, &mut out);
3388            frames.push(out[..n].to_vec());
3389        }
3390
3391        // Decode frames 0..=19 normally.
3392        for f in &frames[0..=19] {
3393            do_decode(dec, f);
3394        }
3395        // Drop frame 20 entirely.
3396
3397        // Decode frames 21..=49. The first one triggers reset; the
3398        // rest may or may not decode successfully (Delta frames
3399        // error out because there is no prediction after reset). We
3400        // ignore the outcome — the contract is only that the
3401        // decoder does not panic and does not silently corrupt the
3402        // post-keyframe values.
3403        for f in &frames[21..50] {
3404            let mut v = [0f64; 5];
3405            let _ = alec_decode_multi_fixed(
3406                dec,
3407                f.as_ptr(),
3408                f.len(),
3409                v.as_mut_ptr(),
3410                v.len(),
3411                ptr::null_mut(),
3412                ptr::null_mut(),
3413                ptr::null_mut(),
3414            );
3415        }
3416
3417        // Frame 50 is a keyframe — decode must succeed and values
3418        // must match the corresponding input within sensor LSB.
3419        let values_50 = do_decode(dec, &frames[50]);
3420        assert_eq!(frames[50][0], 0xA2);
3421        let expected = rows[50];
3422        let tols = [0.01_f64, 0.01, 0.1, 1.0, 0.01];
3423        for ch in 0..5 {
3424            assert!(
3425                (expected[ch] - values_50[ch]).abs() <= tols[ch] + 1e-9,
3426                "ch {} at frame 50: expected {}, got {}",
3427                ch,
3428                expected[ch],
3429                values_50[ch]
3430            );
3431        }
3432        // Frames 51..=60 must also decode correctly now that the
3433        // context is re-synced.
3434        for i in 51..=60 {
3435            let values = do_decode(dec, &frames[i]);
3436            for ch in 0..5 {
3437                assert!(
3438                    (rows[i][ch] - values[ch]).abs() <= tols[ch] + 1e-9,
3439                    "ch {} at frame {}: expected {}, got {}",
3440                    ch,
3441                    i,
3442                    rows[i][ch],
3443                    values[ch]
3444                );
3445            }
3446        }
3447
3448        alec_encoder_free(enc);
3449        alec_decoder_free(dec);
3450    }
3451
3452    /// C5-4. Smart resync via the downlink handler: decoder detects
3453    /// a gap and calls `alec_downlink_handler(enc, [0xFF], 1)` to
3454    /// request an immediate keyframe. Recovery happens on the very
3455    /// next uplink, not at the far-off periodic keyframe.
3456    #[test]
3457    fn test_smart_resync_downlink() {
3458        let (enc, dec) = new_pair(10_000); // no periodic keyframes
3459        let row = [3.60, 22.50, 45.0, 420.0, 1013.25];
3460        let mut out = [0u8; 64];
3461        let mut frames: Vec<Vec<u8>> = Vec::new();
3462
3463        // Encode 10 frames. Decoder drops frame 5.
3464        for _ in 0..10 {
3465            let n = do_encode(enc, &row, &mut out);
3466            frames.push(out[..n].to_vec());
3467        }
3468        for f in &frames[0..=4] {
3469            do_decode(dec, f);
3470        }
3471        // Skip frame 5. Decoding frame 6..=9 will produce divergent
3472        // values, but that's fine — the point is the RESYNC.
3473        for f in &frames[6..=9] {
3474            let mut v = [0f64; 5];
3475            let _ = alec_decode_multi_fixed(
3476                dec,
3477                f.as_ptr(),
3478                f.len(),
3479                v.as_mut_ptr(),
3480                v.len(),
3481                ptr::null_mut(),
3482                ptr::null_mut(),
3483                ptr::null_mut(),
3484            );
3485        }
3486
3487        // Decoder realises it's out of sync — simulate the sidecar
3488        // checking alec_decoder_gap_detected and sending a 0xFF
3489        // downlink. The device-side integration calls the downlink
3490        // handler on the encoder:
3491        let cmd = [0xFF_u8];
3492        let r = alec_downlink_handler(enc, cmd.as_ptr(), cmd.len());
3493        assert_eq!(r, AlecResult::Ok);
3494        assert!(
3495            unsafe { &*enc }.force_keyframe_pending,
3496            "downlink 0xFF must arm the force-keyframe flag"
3497        );
3498
3499        // The very next uplink (frame 10) MUST be a keyframe.
3500        let n = do_encode(enc, &row, &mut out);
3501        assert_eq!(out[0], 0xA2, "post-downlink frame must be a keyframe");
3502        assert_eq!(n, 27);
3503
3504        // Decoder catches up immediately.
3505        let values = do_decode(dec, &out[..n]);
3506        let tols = [0.01_f64, 0.01, 0.1, 1.0, 0.01];
3507        for ch in 0..5 {
3508            assert!(
3509                (row[ch] - values[ch]).abs() <= tols[ch] + 1e-9,
3510                "ch {}: expected {}, got {}",
3511                ch,
3512                row[ch],
3513                values[ch]
3514            );
3515        }
3516
3517        // Without smart resync, recovery would have required waiting
3518        // for the next periodic keyframe at frame keyframe_interval
3519        // (50 by default) — an 8h drift on EM500-CO2's 10-min cadence.
3520        // With smart resync, recovery happened on frame 10 — a 10-min
3521        // drift. That is the order-of-magnitude improvement.
3522
3523        alec_encoder_free(enc);
3524        alec_decoder_free(dec);
3525    }
3526
3527    /// C5-5. An unknown downlink command is rejected with
3528    /// `ALEC_ERROR_INVALID_INPUT` and leaves the encoder state
3529    /// unchanged.
3530    #[test]
3531    fn test_downlink_handler_invalid_command() {
3532        let enc = alec_encoder_new();
3533        assert!(!unsafe { &*enc }.force_keyframe_pending);
3534
3535        let cmd = [0x00_u8];
3536        let r = alec_downlink_handler(enc, cmd.as_ptr(), cmd.len());
3537        assert_eq!(r, AlecResult::ErrorInvalidInput);
3538        assert!(
3539            !unsafe { &*enc }.force_keyframe_pending,
3540            "unknown downlink must NOT arm the force-keyframe flag"
3541        );
3542
3543        // Another uncommon but not-special byte.
3544        let cmd = [0x7E_u8, 0xFF, 0xAA];
3545        let r = alec_downlink_handler(enc, cmd.as_ptr(), cmd.len());
3546        assert_eq!(r, AlecResult::ErrorInvalidInput);
3547        assert!(!unsafe { &*enc }.force_keyframe_pending);
3548
3549        // NULL / empty inputs are defensively handled.
3550        assert_eq!(
3551            alec_downlink_handler(ptr::null_mut(), cmd.as_ptr(), cmd.len()),
3552            AlecResult::ErrorNullPointer
3553        );
3554        assert_eq!(
3555            alec_downlink_handler(enc, ptr::null(), 1),
3556            AlecResult::ErrorNullPointer
3557        );
3558        assert_eq!(
3559            alec_downlink_handler(enc, cmd.as_ptr(), 0),
3560            AlecResult::ErrorInvalidInput
3561        );
3562
3563        alec_encoder_free(enc);
3564    }
3565
3566    /// C5-6. A deliberately-corrupted context_version on the decoder
3567    /// triggers a mismatch when the next non-keyframe arrives; the
3568    /// decoder resets and recovers at the subsequent keyframe.
3569    #[test]
3570    fn test_context_mismatch_triggers_reset() {
3571        let (enc, dec) = new_pair(10);
3572        let row = [3.60, 22.50, 45.0, 420.0, 1013.25];
3573        let mut out = [0u8; 64];
3574        let mut frames: Vec<Vec<u8>> = Vec::new();
3575
3576        // Encode 12 frames (0..=11); frame 10 is a keyframe.
3577        for _ in 0..=11 {
3578            let n = do_encode(enc, &row, &mut out);
3579            frames.push(out[..n].to_vec());
3580        }
3581
3582        // Decode 0..=8 normally.
3583        for f in &frames[0..=8] {
3584            do_decode(dec, f);
3585        }
3586
3587        // Corrupt the decoder's tracked ctx_ver to something that
3588        // looks like a backwards jump (outside ctx_version_compatible's
3589        // tolerance of 256 forward units). The encoder's ctx_ver is
3590        // currently 9*5=45 post-observation; we pretend the decoder
3591        // last saw a version ~30k ahead so the next non-keyframe
3592        // trips the mismatch detector.
3593        unsafe { &mut *dec }.decoder.reset();
3594        // reset() clears last_fixed_sequence too, so replay a frame
3595        // to re-arm sequence tracking:
3596        do_decode(dec, &frames[8]);
3597        // Now set last_fixed_ctx_version artificially by pushing
3598        // through a synthesised decode state. A cleaner API would be
3599        // nice — for the test we use the *encoded* route: change
3600        // our tracked version by decoding a frame whose payload we
3601        // hand-crafted. Since that's gnarly, instead we simulate
3602        // the effect by directly walking into a known-mismatch
3603        // scenario: inject a frame whose ctx_ver is very far from
3604        // what the decoder expects.
3605
3606        // Build a synthetic non-keyframe with an impossible ctx_ver
3607        // (wire bytes: 0xA1 <seq> <ctx> <bitmap> …). Use frame 9's
3608        // real bytes but rewrite bytes 3..=4 (ctx_ver).
3609        let mut tampered = frames[9].clone();
3610        // Replace ctx_ver with 0x1234 — far from the decoder's
3611        // current state (which just observed frame 8 ≈ version ~45).
3612        tampered[3] = 0x12;
3613        tampered[4] = 0x34;
3614
3615        // Before the tamper the decoder has seen at least 9 identical
3616        // readings for channel 1, so its per-source observation count
3617        // is ≥ 3 and `predict()` reports the `MovingAverage` model.
3618        use alec::context::PredictionModel;
3619        let model_before = unsafe { &*dec }.context.predict(1).unwrap().model_type;
3620        assert_eq!(model_before, PredictionModel::MovingAverage);
3621
3622        // Decoding the tampered frame must surface a mismatch and
3623        // trigger `reset_to_baseline()`. The decode itself may
3624        // produce garbage values for Delta-encoded channels (since
3625        // the reset happens after decode but before the re-observe),
3626        // which is acceptable — the contract is that subsequent
3627        // keyframe decodes are correct.
3628        let mut v = [0f64; 5];
3629        let _ = alec_decode_multi_fixed(
3630            dec,
3631            tampered.as_ptr(),
3632            tampered.len(),
3633            v.as_mut_ptr(),
3634            v.len(),
3635            ptr::null_mut(),
3636            ptr::null_mut(),
3637            ptr::null_mut(),
3638        );
3639
3640        // After the reset the history has been wiped. The FFI then
3641        // re-observes the single tampered frame's output, so each
3642        // per-channel observation count is exactly 1 and
3643        // `predict()` reports the `LastValue` model (count < 3
3644        // branch in SourceStats::predict). If the reset had NOT
3645        // fired, count would be 10 and the model would still be
3646        // MovingAverage.
3647        let model_after = unsafe { &*dec }.context.predict(1).unwrap().model_type;
3648        assert_eq!(
3649            model_after,
3650            PredictionModel::LastValue,
3651            "reset_to_baseline should have dropped source_stats count below the \
3652             MovingAverage threshold (count < 3)"
3653        );
3654
3655        // Frame 10 is a real keyframe — decode must succeed and
3656        // values must match the input within sensor tolerance.
3657        let values_10 = do_decode(dec, &frames[10]);
3658        assert_eq!(frames[10][0], 0xA2);
3659        let tols = [0.01_f64, 0.01, 0.1, 1.0, 0.01];
3660        for ch in 0..5 {
3661            assert!(
3662                (row[ch] - values_10[ch]).abs() <= tols[ch] + 1e-9,
3663                "ch {}: expected {}, got {}",
3664                ch,
3665                row[ch],
3666                values_10[ch]
3667            );
3668        }
3669
3670        alec_encoder_free(enc);
3671        alec_decoder_free(dec);
3672    }
3673
3674    // ========================================================================
3675    // Bloc D4 — Context persistence FFI tests
3676    // ========================================================================
3677
3678    /// Helper: CString-safe sensor type.
3679    const SENSOR_TYPE: &[u8] = b"em500-co2\0";
3680
3681    /// Run `frames` rows through the encoder + decoder. Returns the
3682    /// wire frames for later replay.
3683    fn drive_pair(enc: *mut AlecEncoder, dec: *mut AlecDecoder, rows: &[[f64; 5]]) -> Vec<Vec<u8>> {
3684        let mut out = [0u8; 64];
3685        let mut out_len: usize = 0;
3686        let mut values = [0f64; 5];
3687        let mut frames = Vec::with_capacity(rows.len());
3688        for row in rows {
3689            let r = alec_encode_multi_fixed(
3690                enc,
3691                row.as_ptr(),
3692                row.len(),
3693                out.as_mut_ptr(),
3694                out.len(),
3695                &mut out_len,
3696            );
3697            assert_eq!(r, AlecResult::Ok);
3698            let frame = out[..out_len].to_vec();
3699            let r2 = alec_decode_multi_fixed(
3700                dec,
3701                frame.as_ptr(),
3702                frame.len(),
3703                values.as_mut_ptr(),
3704                values.len(),
3705                ptr::null_mut(),
3706                ptr::null_mut(),
3707                ptr::null_mut(),
3708            );
3709            assert_eq!(r2, AlecResult::Ok);
3710            frames.push(frame);
3711        }
3712        frames
3713    }
3714
3715    /// D4-1. End-to-end in-memory roundtrip: train a decoder's
3716    /// context, export → import into a fresh decoder, then verify
3717    /// that both decoders produce identical output for the same
3718    /// subsequent encoded frames.
3719    #[test]
3720    fn test_context_roundtrip_in_memory() {
3721        // Slow-drift signal so frames stay compact.
3722        let rows: Vec<[f64; 5]> = (0..30)
3723            .map(|i| [3.60, 22.50, 45.0, 420.0 + (i / 3) as f64, 1013.25])
3724            .collect();
3725
3726        let cfg = AlecEncoderConfig {
3727            history_size: 0,
3728            max_patterns: 0,
3729            max_memory_bytes: 0,
3730            keyframe_interval: 10_000, // avoid periodic keyframes
3731            smart_resync: false,
3732            num_channels: 0,
3733        };
3734        let enc = alec_encoder_new_with_config(&cfg);
3735        let dec_orig = alec_decoder_new();
3736
3737        // Train.
3738        let _ = drive_pair(enc, dec_orig, &rows);
3739
3740        // Export the trained decoder.
3741        let mut size: usize = 0;
3742        let r = alec_decoder_export_state_size(
3743            dec_orig,
3744            SENSOR_TYPE.as_ptr() as *const c_char,
3745            &mut size,
3746        );
3747        assert_eq!(r, AlecResult::Ok);
3748        assert!(size > 0 && size < 3072, "export size {} out of range", size);
3749        let mut buf = vec![0u8; size];
3750        let mut written: usize = 0;
3751        let r = alec_decoder_export_state(
3752            dec_orig,
3753            SENSOR_TYPE.as_ptr() as *const c_char,
3754            buf.as_mut_ptr(),
3755            buf.len(),
3756            &mut written,
3757        );
3758        assert_eq!(r, AlecResult::Ok);
3759        assert_eq!(written, size);
3760
3761        // Fresh decoder, import the state.
3762        let dec_new = alec_decoder_new();
3763        let r = alec_decoder_import_state(dec_new, buf.as_ptr(), buf.len());
3764        assert_eq!(r, AlecResult::Ok);
3765
3766        // Drive 10 more frames on the encoder and decode each
3767        // through BOTH decoders. Identical output confirms the
3768        // restored context is operationally equivalent.
3769        let more: Vec<[f64; 5]> = (30..40)
3770            .map(|i| [3.60, 22.50, 45.0, 420.0 + (i / 3) as f64, 1013.25])
3771            .collect();
3772        let mut out = [0u8; 64];
3773        let mut out_len: usize = 0;
3774        for row in &more {
3775            let r = alec_encode_multi_fixed(
3776                enc,
3777                row.as_ptr(),
3778                row.len(),
3779                out.as_mut_ptr(),
3780                out.len(),
3781                &mut out_len,
3782            );
3783            assert_eq!(r, AlecResult::Ok);
3784            let frame = &out[..out_len];
3785
3786            let mut v_orig = [0f64; 5];
3787            let mut v_new = [0f64; 5];
3788            assert_eq!(
3789                alec_decode_multi_fixed(
3790                    dec_orig,
3791                    frame.as_ptr(),
3792                    frame.len(),
3793                    v_orig.as_mut_ptr(),
3794                    v_orig.len(),
3795                    ptr::null_mut(),
3796                    ptr::null_mut(),
3797                    ptr::null_mut(),
3798                ),
3799                AlecResult::Ok
3800            );
3801            assert_eq!(
3802                alec_decode_multi_fixed(
3803                    dec_new,
3804                    frame.as_ptr(),
3805                    frame.len(),
3806                    v_new.as_mut_ptr(),
3807                    v_new.len(),
3808                    ptr::null_mut(),
3809                    ptr::null_mut(),
3810                    ptr::null_mut(),
3811                ),
3812                AlecResult::Ok
3813            );
3814            // Bit-exact equality — both decoders ran the same
3815            // reconstruction logic on the same wire bytes with
3816            // identically-seeded contexts.
3817            for ch in 0..5 {
3818                assert_eq!(
3819                    v_orig[ch].to_bits(),
3820                    v_new[ch].to_bits(),
3821                    "ch {} diverged between original and restored decoder",
3822                    ch
3823                );
3824            }
3825        }
3826
3827        alec_encoder_free(enc);
3828        alec_decoder_free(dec_orig);
3829        alec_decoder_free(dec_new);
3830    }
3831
3832    /// D4-2. `export_state_size` matches the length reported by a
3833    /// real export call.
3834    #[test]
3835    fn test_export_state_size_matches_export() {
3836        let enc = alec_encoder_new();
3837        let dec = alec_decoder_new();
3838        let rows: Vec<[f64; 5]> = (0..12)
3839            .map(|_| [3.60, 22.50, 45.0, 420.0, 1013.25])
3840            .collect();
3841        let _ = drive_pair(enc, dec, &rows);
3842
3843        let mut size: usize = 0;
3844        let r =
3845            alec_decoder_export_state_size(dec, SENSOR_TYPE.as_ptr() as *const c_char, &mut size);
3846        assert_eq!(r, AlecResult::Ok);
3847
3848        let mut buf = vec![0u8; size];
3849        let mut written: usize = 0;
3850        let r = alec_decoder_export_state(
3851            dec,
3852            SENSOR_TYPE.as_ptr() as *const c_char,
3853            buf.as_mut_ptr(),
3854            buf.len(),
3855            &mut written,
3856        );
3857        assert_eq!(r, AlecResult::Ok);
3858        assert_eq!(written, size);
3859
3860        alec_encoder_free(enc);
3861        alec_decoder_free(dec);
3862    }
3863
3864    /// D4-3. Too-small buffer → `ALEC_ERROR_BUFFER_TOO_SMALL`. The
3865    /// buffer is NOT written to (no partial write); `*out_len`
3866    /// reports the required size.
3867    #[test]
3868    fn test_export_buffer_too_small() {
3869        let enc = alec_encoder_new();
3870        let dec = alec_decoder_new();
3871        let rows: Vec<[f64; 5]> = (0..8)
3872            .map(|_| [3.60, 22.50, 45.0, 420.0, 1013.25])
3873            .collect();
3874        let _ = drive_pair(enc, dec, &rows);
3875
3876        // Tiny buffer pre-filled with a sentinel. After the failed
3877        // export every byte must still be the sentinel.
3878        let mut buf = [0xAAu8; 10];
3879        let mut written: usize = 0;
3880        let r = alec_decoder_export_state(
3881            dec,
3882            SENSOR_TYPE.as_ptr() as *const c_char,
3883            buf.as_mut_ptr(),
3884            buf.len(),
3885            &mut written,
3886        );
3887        assert_eq!(r, AlecResult::ErrorBufferTooSmall);
3888        assert!(
3889            written > buf.len(),
3890            "expected *out_len to report required size, got {}",
3891            written
3892        );
3893        for (i, &b) in buf.iter().enumerate() {
3894            assert_eq!(b, 0xAA, "buf[{}] was written despite error", i);
3895        }
3896
3897        alec_encoder_free(enc);
3898        alec_decoder_free(dec);
3899    }
3900
3901    /// D4-4. Corrupt input → `ALEC_ERROR_CORRUPT_DATA`. The
3902    /// decoder's context is NOT modified.
3903    #[test]
3904    fn test_import_corrupt_data() {
3905        let enc = alec_encoder_new();
3906        let dec = alec_decoder_new();
3907        let rows: Vec<[f64; 5]> = (0..8)
3908            .map(|_| [3.60, 22.50, 45.0, 420.0, 1013.25])
3909            .collect();
3910        let _ = drive_pair(enc, dec, &rows);
3911
3912        // Capture a snapshot we can compare against.
3913        let mut snap = vec![0u8; 4096];
3914        let mut snap_len: usize = 0;
3915        assert_eq!(
3916            alec_decoder_export_state(
3917                dec,
3918                SENSOR_TYPE.as_ptr() as *const c_char,
3919                snap.as_mut_ptr(),
3920                snap.len(),
3921                &mut snap_len,
3922            ),
3923            AlecResult::Ok
3924        );
3925        let snap_pre = snap[..snap_len].to_vec();
3926
3927        // Random garbage → CORRUPT_DATA.
3928        let garbage = [0x00u8, 0x11, 0x22, 0x33, 0x44, 0x55];
3929        let r = alec_decoder_import_state(dec, garbage.as_ptr(), garbage.len());
3930        assert_eq!(r, AlecResult::ErrorCorruptData);
3931
3932        // Bytes with the right magic but bad CRC → also CORRUPT_DATA.
3933        let mut tampered = snap_pre.clone();
3934        let mid = tampered.len() / 2;
3935        tampered[mid] ^= 0xFF;
3936        let r = alec_decoder_import_state(dec, tampered.as_ptr(), tampered.len());
3937        assert_eq!(r, AlecResult::ErrorCorruptData);
3938
3939        // Snapshot the decoder again — must match pre-import bytes
3940        // exactly, confirming the failed imports left the context
3941        // untouched.
3942        let mut snap2 = vec![0u8; 4096];
3943        let mut snap2_len: usize = 0;
3944        assert_eq!(
3945            alec_decoder_export_state(
3946                dec,
3947                SENSOR_TYPE.as_ptr() as *const c_char,
3948                snap2.as_mut_ptr(),
3949                snap2.len(),
3950                &mut snap2_len,
3951            ),
3952            AlecResult::Ok
3953        );
3954        assert_eq!(snap2_len, snap_len);
3955        assert_eq!(&snap2[..snap2_len], &snap_pre[..]);
3956
3957        alec_encoder_free(enc);
3958        alec_decoder_free(dec);
3959    }
3960
3961    /// D4-5. Session state (last_header_sequence, last_gap_size) is
3962    /// preserved across an import.
3963    #[test]
3964    fn test_session_state_preserved_on_import() {
3965        let enc = alec_encoder_new();
3966        let dec = alec_decoder_new();
3967        let rows: Vec<[f64; 5]> = (0..5)
3968            .map(|_| [3.60, 22.50, 45.0, 420.0, 1013.25])
3969            .collect();
3970        let _ = drive_pair(enc, dec, &rows);
3971
3972        // Overwrite the session-state fields with a known tuple.
3973        unsafe {
3974            (*dec).last_header_sequence = Some(42);
3975            (*dec).last_gap_size = 2;
3976        }
3977
3978        // Export and re-import — session state should survive.
3979        let mut buf = vec![0u8; 4096];
3980        let mut n: usize = 0;
3981        assert_eq!(
3982            alec_decoder_export_state(
3983                dec,
3984                SENSOR_TYPE.as_ptr() as *const c_char,
3985                buf.as_mut_ptr(),
3986                buf.len(),
3987                &mut n,
3988            ),
3989            AlecResult::Ok
3990        );
3991        assert_eq!(
3992            alec_decoder_import_state(dec, buf.as_ptr(), n),
3993            AlecResult::Ok
3994        );
3995
3996        let dec_ref = unsafe { &*dec };
3997        assert_eq!(dec_ref.last_header_sequence, Some(42));
3998        assert_eq!(dec_ref.last_gap_size, 2);
3999
4000        alec_encoder_free(enc);
4001        alec_decoder_free(dec);
4002    }
4003
4004    /// D4-6. Exporting a context just after `reset_to_baseline()`
4005    /// produces a valid serialized buffer whose `source_stats`
4006    /// section is empty. Patterns registered before the reset are
4007    /// preserved (Bloc C contract — see `reset_to_baseline`).
4008    #[test]
4009    fn test_export_after_reset_to_baseline() {
4010        let enc = alec_encoder_new();
4011        let dec = alec_decoder_new();
4012        let rows: Vec<[f64; 5]> = (0..30)
4013            .map(|_| [3.60, 22.50, 45.0, 420.0, 1013.25])
4014            .collect();
4015        let _ = drive_pair(enc, dec, &rows);
4016
4017        // Register one pattern directly on the context so we can
4018        // check it survives the reset.
4019        use alec::context::Pattern;
4020        let code = unsafe { &mut *dec }
4021            .context
4022            .register_pattern(Pattern::new(vec![0x11, 0x22, 0x33]))
4023            .unwrap();
4024
4025        // Reset → export → import → verify.
4026        unsafe { &mut *dec }.context.reset_to_baseline();
4027        let mut buf = vec![0u8; 4096];
4028        let mut n: usize = 0;
4029        assert_eq!(
4030            alec_decoder_export_state(
4031                dec,
4032                SENSOR_TYPE.as_ptr() as *const c_char,
4033                buf.as_mut_ptr(),
4034                buf.len(),
4035                &mut n,
4036            ),
4037            AlecResult::Ok
4038        );
4039
4040        let dec_fresh = alec_decoder_new();
4041        assert_eq!(
4042            alec_decoder_import_state(dec_fresh, buf.as_ptr(), n),
4043            AlecResult::Ok
4044        );
4045
4046        // source_stats is empty (predict returns None for any sid).
4047        let d = unsafe { &*dec_fresh };
4048        assert!(d.context.predict(1).is_none());
4049        assert!(d.context.predict(5).is_none());
4050        // Pattern registered pre-reset must still be in the dictionary.
4051        assert!(d.context.get_pattern(code).is_some());
4052
4053        alec_encoder_free(enc);
4054        alec_decoder_free(dec);
4055        alec_decoder_free(dec_fresh);
4056    }
4057
4058    /// NULL-safety on the three new FFI entry points.
4059    #[test]
4060    fn test_persistence_ffi_null_safety() {
4061        use std::ptr;
4062        let dec = alec_decoder_new();
4063        let mut n: usize = 0;
4064        let mut buf = [0u8; 4];
4065
4066        // export_state_size
4067        assert_eq!(
4068            alec_decoder_export_state_size(
4069                ptr::null(),
4070                SENSOR_TYPE.as_ptr() as *const c_char,
4071                &mut n
4072            ),
4073            AlecResult::ErrorNullPointer
4074        );
4075        assert_eq!(
4076            alec_decoder_export_state_size(dec, ptr::null(), &mut n),
4077            AlecResult::ErrorNullPointer
4078        );
4079        assert_eq!(
4080            alec_decoder_export_state_size(
4081                dec,
4082                SENSOR_TYPE.as_ptr() as *const c_char,
4083                ptr::null_mut()
4084            ),
4085            AlecResult::ErrorNullPointer
4086        );
4087
4088        // export_state
4089        assert_eq!(
4090            alec_decoder_export_state(
4091                ptr::null(),
4092                SENSOR_TYPE.as_ptr() as *const c_char,
4093                buf.as_mut_ptr(),
4094                buf.len(),
4095                &mut n,
4096            ),
4097            AlecResult::ErrorNullPointer
4098        );
4099
4100        // import_state
4101        assert_eq!(
4102            alec_decoder_import_state(ptr::null_mut(), buf.as_ptr(), buf.len()),
4103            AlecResult::ErrorNullPointer
4104        );
4105        assert_eq!(
4106            alec_decoder_import_state(dec, ptr::null(), buf.len()),
4107            AlecResult::ErrorNullPointer
4108        );
4109
4110        alec_decoder_free(dec);
4111    }
4112}