Skip to main content

qualia_core_db/
storage.rs

1//! SuperBlock Storage Engine
2//! Handles flushing 850 48-byte Quins into perfectly aligned 40,960-byte
3//! QualiaSuperBlock structures onto the NVMe disk format (`.qla`).
4
5pub mod mmap;
6
7use crate::{NQuin, QualiaSuperBlock, BLOCK_MULTIPLIER_SIZE, QUINS_PER_BLOCK};
8use std::fs::{File, OpenOptions};
9use std::io::{self, Seek, SeekFrom};
10use std::path::Path;
11
12/// The Physical I/O Persistence Writer.
13pub struct SuperBlockWriter {
14    file: File,
15    current_offset: u64,
16}
17
18impl SuperBlockWriter {
19    /// Opens the resource.
20    pub fn open<P: AsRef<Path>>(path: P) -> io::Result<Self> {
21        let mut file = OpenOptions::new()
22            .create(true)
23            .write(true)
24            .read(true)
25            .open(path)?;
26
27        let current_offset = file.seek(SeekFrom::End(0))?;
28
29        Ok(Self {
30            file,
31            current_offset,
32        })
33    }
34
35    /// Flushes an array of exact 850 Quins into a hardware-aligned block on disk.
36    pub fn flush_block(
37        &mut self,
38        sequence_id: u64,
39        owner_did: u64,
40        quins: &[NQuin; QUINS_PER_BLOCK],
41    ) -> io::Result<()> {
42        let mut block = Box::new(unsafe { std::mem::zeroed::<QualiaSuperBlock>() });
43
44        block.block_sequence_id = sequence_id;
45        block.storage_owner_did = owner_did;
46        block.active_quin_count = QUINS_PER_BLOCK as u64;
47        block.hardware_profile_flags = 0x01; // Edge device default profile
48
49        // Copy the array iteratively to avoid unaligned access panics
50        for i in 0..QUINS_PER_BLOCK {
51            block.quin_ledger[i] = quins[i];
52        }
53
54        // Real integrity checksum over the quin payload — CRC-32C, the same
55        // routine the .10d/.hmc containers use (replaces a former mock
56        // `0xABCD`). Computed over the ledger only (not the header), so a
57        // reader can recompute it over the same region. Complementary to the
58        // per-quin XOR-parity ECC: this covers the whole ledger in one word.
59        block.validation_checksum = {
60            let ledger_bytes = unsafe {
61                std::slice::from_raw_parts(
62                    block.quin_ledger.as_ptr() as *const u8,
63                    QUINS_PER_BLOCK * core::mem::size_of::<NQuin>(),
64                )
65            };
66            crate::container_10d::crc32c::crc32c(ledger_bytes)
67        };
68
69        // Convert the aligned struct directly into a byte slice
70        let bytes = unsafe {
71            std::slice::from_raw_parts(
72                (block.as_ref() as *const QualiaSuperBlock) as *const u8,
73                BLOCK_MULTIPLIER_SIZE,
74            )
75        };
76
77        #[cfg(target_family = "unix")]
78        {
79            use std::os::unix::fs::FileExt;
80            self.file.write_all_at(bytes, self.current_offset)?;
81        }
82
83        #[cfg(target_family = "windows")]
84        {
85            use std::os::windows::fs::FileExt;
86            let mut written = 0;
87            while written < BLOCK_MULTIPLIER_SIZE {
88                let n = self
89                    .file
90                    .seek_write(&bytes[written..], self.current_offset + written as u64)?;
91                if n == 0 {
92                    return Err(io::Error::new(
93                        io::ErrorKind::WriteZero,
94                        "Failed to write whole block",
95                    ));
96                }
97                written += n;
98            }
99        }
100
101        #[cfg(not(any(target_family = "unix", target_family = "windows")))]
102        {
103            use std::io::Write;
104            self.file.write_all(bytes)?;
105        }
106
107        // Sync to guarantee physical sector write
108        self.file.sync_data()?;
109        self.current_offset += BLOCK_MULTIPLIER_SIZE as u64;
110
111        crate::telemetry::SUPERBLOCK_IO_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
112
113        Ok(())
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use tempfile::NamedTempFile;
121
122    #[test]
123    fn test_flush_superblock() {
124        let temp_file = NamedTempFile::new().unwrap();
125        let mut writer = SuperBlockWriter::open(temp_file.path()).unwrap();
126
127        // Create an array of exactly 850 mock quins
128        let quins = [NQuin {
129            subject: 0,
130            predicate: 0,
131            object: 0,
132            context: 0,
133            metadata: 0,
134            parity: 0,
135        }; QUINS_PER_BLOCK];
136
137        let result = writer.flush_block(1, 42, &quins);
138        assert!(result.is_ok(), "Failed to flush SuperBlock");
139
140        // Verify the file size is exactly 40,960 bytes
141        let metadata = temp_file.as_file().metadata().unwrap();
142        assert_eq!(
143            metadata.len(),
144            BLOCK_MULTIPLIER_SIZE as u64,
145            "File size is not page aligned to 40,960 bytes"
146        );
147    }
148}
149
150// -----------------------------------------------------------------------------
151// Phase 5: Virtual File System (VFS) Abstraction
152// -----------------------------------------------------------------------------
153// Provides a unified storage interface for `.q42.bidx` offline index sync.
154// - Uses standard `std::fs` on native/Tauri targets.
155// - Uses Origin Private File System (OPFS) on `wasm32-unknown-unknown` targets.
156
157use std::future::Future;
158use std::pin::Pin;
159
160pub trait VirtualFileSystem {
161    /// Reads a chunk of data from the local storage hierarchy
162    #[cfg(not(target_arch = "wasm32"))]
163    fn read_chunk(
164        &self,
165        path: &str,
166    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>> + Send>>;
167    #[cfg(target_arch = "wasm32")]
168    /// Reads a chunk from `path`.
169    fn read_chunk(&self, path: &str) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>>>>;
170
171    /// Writes a chunk of data to the local storage hierarchy
172    #[cfg(not(target_arch = "wasm32"))]
173    fn write_chunk(
174        &self,
175        path: &str,
176        data: &[u8],
177    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send>>;
178    #[cfg(target_arch = "wasm32")]
179    /// Writes a chunk to `path`.
180    fn write_chunk(
181        &self,
182        path: &str,
183        data: &[u8],
184    ) -> Pin<Box<dyn Future<Output = Result<(), String>>>>;
185}
186
187#[cfg(not(target_arch = "wasm32"))]
188pub struct NativeVfs;
189
190#[cfg(not(target_arch = "wasm32"))]
191impl VirtualFileSystem for NativeVfs {
192    /// Reads a chunk from `path`.
193    fn read_chunk(
194        &self,
195        path: &str,
196    ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>> + Send>> {
197        let path = path.to_string();
198        Box::pin(async move { std::fs::read(&path).map_err(|e| e.to_string()) })
199    }
200
201    /// Writes a chunk to `path`.
202    fn write_chunk(
203        &self,
204        path: &str,
205        data: &[u8],
206    ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send>> {
207        let path = path.to_string();
208        let data = data.to_vec();
209        Box::pin(async move { std::fs::write(&path, data).map_err(|e| e.to_string()) })
210    }
211}
212
213#[cfg(target_arch = "wasm32")]
214pub struct OpfsVfs;
215
216#[cfg(target_arch = "wasm32")]
217impl VirtualFileSystem for OpfsVfs {
218    /// Reads a chunk from `path`.
219    fn read_chunk(&self, path: &str) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, String>>>> {
220        let path = path.to_string();
221        Box::pin(async move {
222            use wasm_bindgen::JsCast;
223            use wasm_bindgen_futures::JsFuture;
224
225            let window = web_sys::window().ok_or("No global window")?;
226            let navigator = window.navigator();
227            let storage = navigator.storage();
228
229            let dir_handle_val = JsFuture::from(storage.get_directory())
230                .await
231                .map_err(|e| format!("{:?}", e))?;
232            let dir_handle: web_sys::FileSystemDirectoryHandle = dir_handle_val.unchecked_into();
233
234            let file_handle_val = JsFuture::from(dir_handle.get_file_handle(&path))
235                .await
236                .map_err(|e| format!("{:?}", e))?;
237            let file_handle: web_sys::FileSystemFileHandle = file_handle_val.unchecked_into();
238
239            let file_val = JsFuture::from(file_handle.get_file())
240                .await
241                .map_err(|e| format!("{:?}", e))?;
242            let file: web_sys::File = file_val.unchecked_into();
243
244            let array_buffer_val = JsFuture::from(file.array_buffer())
245                .await
246                .map_err(|e| format!("{:?}", e))?;
247            let array_buffer: js_sys::ArrayBuffer = array_buffer_val.unchecked_into();
248
249            let uint8_array = js_sys::Uint8Array::new(&array_buffer);
250            Ok(uint8_array.to_vec())
251        })
252    }
253
254    /// Writes a chunk to `path`.
255    fn write_chunk(
256        &self,
257        path: &str,
258        data: &[u8],
259    ) -> Pin<Box<dyn Future<Output = Result<(), String>>>> {
260        let path = path.to_string();
261        let data = data.to_vec();
262        Box::pin(async move {
263            use wasm_bindgen::JsCast;
264            use wasm_bindgen_futures::JsFuture;
265
266            let window = web_sys::window().ok_or("No global window")?;
267            let navigator = window.navigator();
268            let storage = navigator.storage();
269
270            let dir_handle_val = JsFuture::from(storage.get_directory())
271                .await
272                .map_err(|e| format!("{:?}", e))?;
273            let dir_handle: web_sys::FileSystemDirectoryHandle = dir_handle_val.unchecked_into();
274
275            let options = web_sys::FileSystemGetFileOptions::new();
276            options.set_create(true);
277            let file_handle_val =
278                JsFuture::from(dir_handle.get_file_handle_with_options(&path, &options))
279                    .await
280                    .map_err(|e| format!("{:?}", e))?;
281            let file_handle: web_sys::FileSystemFileHandle = file_handle_val.unchecked_into();
282
283            let writable_val = JsFuture::from(file_handle.create_writable())
284                .await
285                .map_err(|e| format!("{:?}", e))?;
286            let writable: web_sys::FileSystemWritableFileStream = writable_val.unchecked_into();
287
288            let uint8_array = js_sys::Uint8Array::from(data.as_slice());
289            JsFuture::from(
290                writable
291                    .write_with_buffer_source(&uint8_array)
292                    .map_err(|e| format!("{:?}", e))?,
293            )
294            .await
295            .map_err(|e| format!("{:?}", e))?;
296            JsFuture::from(writable.close())
297                .await
298                .map_err(|e| format!("{:?}", e))?;
299
300            Ok(())
301        })
302    }
303}