qualia_core_db/container_10d/
crc32c.rs

1//! Shared CRC-32C (Castagnoli, reflected) — the canonical integrity primitive
2//! for the `.10d` container and the `q42/p64_weight.rs` weight container.
3//!
4//! **P0.3** consolidates the two previously-duplicated implementations (one in
5//! `q42/p64_weight.rs`, one in `container_10d/section.rs`) into this single
6//! module. Both call sites delegate here. The P0.3 acceptance gate verifies
7//! that `p64_weight.rs` checksums stay byte-identical after delegation (the
8//! p64 round-trip tests are the proof — they fail on any CRC change).
9//!
10//! Algorithm: CRC-32C (Castagnoli), reflected, init = 0xFFFF_FFFF, polynomial
11//! 0x82F63B78 (the reflected form of 0x1EDC6F41), final XOR = 0xFFFF_FFFF
12//! (i.e., bitwise NOT).
13//!
14//! **Implementation:** 256-entry slice table (built once via `OnceLock`) —
15//! bit-identical to the historical table-less 8-shift-per-byte loop (pinned by
16//! the RFC 3720 check value + `crc32c_table_matches_tableless_bit_identical`).
17//! Table form is far faster over multi-hundred-MB P64 tensors (toolkit probe:
18//! SmolLM2 `from_p64` spent tens of seconds in table-less CRC).
19//!
20//! The canonical check value (the ASCII string `"123456789"` → `0xE3069283`)
21//! is pinned by a test below so a future refactor cannot silently change the
22//! algorithm.
23
24use std::sync::OnceLock;
25
26/// CRC-32C (Castagnoli, reflected) over `data`.
27#[inline]
28pub fn crc32c(data: &[u8]) -> u32 {
29    !crc32c_update(0xFFFF_FFFF, data)
30}
31
32/// Incremental CRC-32C update: continue a running CRC over `data` starting
33/// from `crc` (the previous state, NOT yet final-XOR'd). Returns the updated
34/// state (also NOT yet final-XOR'd). To get the final checksum, bitwise-NOT
35/// the result (or call [`crc32c`] for the one-shot form).
36#[inline]
37pub fn crc32c_update(mut crc: u32, data: &[u8]) -> u32 {
38    let table = crc32c_table();
39    for &byte in data {
40        let idx = ((crc ^ byte as u32) & 0xFF) as usize;
41        crc = table[idx] ^ (crc >> 8);
42    }
43    crc
44}
45
46fn crc32c_table() -> &'static [u32; 256] {
47    static TABLE: OnceLock<[u32; 256]> = OnceLock::new();
48    TABLE.get_or_init(|| {
49        let mut t = [0u32; 256];
50        for i in 0..256 {
51            let mut crc = i as u32;
52            for _ in 0..8 {
53                crc = (crc >> 1) ^ (0x82F6_3B78 & 0u32.wrapping_sub(crc & 1));
54            }
55            t[i] = crc;
56        }
57        t
58    })
59}
60
61/// Historical table-less loop — kept for the bit-identical parity test only.
62#[cfg(test)]
63fn crc32c_update_tableless(mut crc: u32, data: &[u8]) -> u32 {
64    for &byte in data {
65        crc ^= byte as u32;
66        for _ in 0..8 {
67            crc = (crc >> 1) ^ (0x82F6_3B78 & 0u32.wrapping_sub(crc & 1));
68        }
69    }
70    crc
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76
77    #[test]
78    fn crc32c_check_value_123456789_is_e3069283() {
79        assert_eq!(crc32c(b"123456789"), 0xE306_9283);
80    }
81
82    #[test]
83    fn crc32c_empty_input_is_final_xor_of_init() {
84        assert_eq!(crc32c(&[]), 0x0000_0000);
85    }
86
87    #[test]
88    fn crc32c_incremental_matches_one_shot() {
89        let data = b"The quick brown fox jumps over the lazy dog";
90        let one_shot = crc32c(data);
91        let mut state = crc32c_update(0xFFFF_FFFF, &data[..10]);
92        state = crc32c_update(state, &data[10..20]);
93        state = crc32c_update(state, &data[20..]);
94        assert_eq!(!state, one_shot);
95    }
96
97    #[test]
98    fn crc32c_table_matches_tableless_bit_identical() {
99        let samples: &[&[u8]] = &[
100            b"",
101            b"123456789",
102            b"The quick brown fox jumps over the lazy dog",
103            &[0u8; 4096],
104        ];
105        for s in samples {
106            let table = !crc32c_update(0xFFFF_FFFF, s);
107            let ref_ = !crc32c_update_tableless(0xFFFF_FFFF, s);
108            assert_eq!(table, ref_, "mismatch on sample len={}", s.len());
109        }
110        let all: Vec<u8> = (0u8..=255).collect();
111        assert_eq!(
112            !crc32c_update(0xFFFF_FFFF, &all),
113            !crc32c_update_tableless(0xFFFF_FFFF, &all)
114        );
115    }
116
117    #[test]
118    fn crc32c_is_deterministic() {
119        let data = b"deterministic input";
120        assert_eq!(crc32c(data), crc32c(data));
121    }
122}
qualia_core_db/container_10d/crc32c.rs

qualia_core_db/container_10d/
crc32c.rs
