scr_runtime_compression/
lib.rs

1//! `scr-runtime-compression` — Runtime integration adapter for semantic-memory.
2//!
3//! Provides:
4//! - [`CompressedSearchPath`] — search path wrapper that carries compression metadata
5//! - [`ExactFallbackAdapter`] — decode adapter that decompresses via turbo-quant / fib-quant
6//!
7//! ## Design principles
8//!
9//! - **Never owns codec truth** — all compression/decompression is delegated to
10//!   `turbo-quant` and `fib-quant`. This crate holds only the integration layer.
11//! - **No `unwrap` in production paths** — all fallible operations return `Result` or `Option`.
12//! - **Rust 2021, MSRV 1.75** — compatible with the workspace minimum.
13
14mod codec_dispatch;
15mod compressed_search_path;
16mod error;
17mod exact_fallback_adapter;
18
19pub use codec_dispatch::{build_adapter, decode, encode, select_codec, CodecDispatch};
20pub use compressed_search_path::CompressedSearchPath;
21pub use error::{CompressionError, DecompressError};
22pub use exact_fallback_adapter::ExactFallbackAdapter;
23
24/// Codec identity for runtime dispatch.
25///
26/// Each compressed representation carries a codec discriminant so the adapter
27/// can delegate to the correct encoder/decoder without static knowledge of the
28/// underlying codec crate.
29#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
30#[serde(rename_all = "snake_case")]
31pub enum CodecId {
32    /// TurboQuant polar-code + residual-sketch codec.
33    TurboQuant,
34    /// FibQuant radial-angular codec.
35    FibQuant,
36    /// Polar-only quantization (asymmetric, no reconstruction).
37    Polar,
38    /// QJL random-projection sketch (asymmetric inner-product).
39    Qjl,
40    /// Uncompressed representation (identity pass-through).
41    Uncompressed,
42}
43
44impl CodecId {
45    /// Returns `true` if this codec requires exact fallback on decode.
46    pub fn requires_exact_fallback(self) -> bool {
47        matches!(self, Self::TurboQuant | Self::FibQuant)
48    }
49}
50
51impl std::fmt::Display for CodecId {
52    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
53        match self {
54            Self::TurboQuant => write!(f, "turbo_quant"),
55            Self::FibQuant => write!(f, "fib_quant"),
56            Self::Polar => write!(f, "polar"),
57            Self::Qjl => write!(f, "qjl"),
58            Self::Uncompressed => write!(f, "uncompressed"),
59        }
60    }
61}
scr_runtime_compression/lib.rs

scr_runtime_compression/
lib.rs
