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}