Skip to main content

qualia_core_db/
wal.rs

1#![allow(unused)]
2#[cfg(not(target_arch = "wasm32"))]
3use std::fs::{File, OpenOptions};
4use std::io::{self, Read, Seek, SeekFrom, Write};
5use std::path::Path;
6
7use ed25519_dalek::{Signature, SigningKey};
8
9use crate::agency::{scrub_quin_volatile, sign_graph_mutation, stamp_fiduciary_metadata};
10use crate::crdt::SuspendedTransactionQueue;
11use crate::modalities::logic::core::WebizenOpcode;
12use crate::NQuin;
13use crate::PermissiveRoutingLane;
14
15// ── WAL file layout ──────────────────────────────────────────────────────────
16//
17// Byte 0..32   — `prev_dag_hash`: SHA-256 of the last DagNode committed from this WAL.
18//                All-zero = no prior checkpoint.
19// Byte 32..    — Packed 48-byte NQuin records (append-only).
20//
21// On `checkpoint_to_dag()` the current quins are committed to the DagStore, then
22// `prev_dag_hash` is rewritten in-place and the NQuin region is truncated.
23// On crash-recovery the `prev_dag_hash` survives so the new checkpoint chains
24// correctly onto the previous DAG node.
25
26/// Magic sentinel written as the message for WAL checkpoint DagNodes.
27const WAL_CHECKPOINT_MSG: &str = "wal:checkpoint";
28/// Size of the fixed WAL header (just the prev_dag_hash).
29const WAL_HEADER_SIZE: u64 = 32;
30
31/// The Write-Ahead Log (WAL) ensures mobile fault tolerance by appending all
32/// 48-byte Quin mutations directly to flash memory synchronously before they are
33/// packed into the larger 40KB SuperBlock structures.
34///
35/// The WAL also maintains a `prev_dag_hash` linking each checkpoint into the
36/// `git_bridge::DagStore` Merkle-DAG so the full write history is content-addressed.
37pub struct WriteAheadLog {
38    #[cfg(not(target_arch = "wasm32"))]
39    file: File,
40    #[cfg(target_arch = "wasm32")]
41    file: Vec<u8>,
42    /// SHA-256 of the most recent DagNode committed from this WAL.
43    /// `[0u8; 32]` means no prior checkpoint — next call to `checkpoint_to_dag` triggers `genesis_node`.
44    pub prev_dag_hash: [u8; 32],
45}
46
47#[cfg(not(target_arch = "wasm32"))]
48impl WriteAheadLog {
49    /// Opens or creates the append-only WAL file at `path`.
50    ///
51    /// If the file already has a 32-byte header (prior checkpoint hash), it is read
52    /// back so the chain is preserved across restarts.
53    pub fn open<P: AsRef<Path>>(path: P) -> std::io::Result<Self> {
54        let mut file = OpenOptions::new()
55            .create(true)
56            .write(true)
57            .read(true)
58            .open(path)?;
59
60        let file_len = file.seek(SeekFrom::End(0))?;
61
62        // Read existing prev_dag_hash from the header, or write a zero header for new files.
63        let prev_dag_hash = if file_len >= WAL_HEADER_SIZE {
64            file.seek(SeekFrom::Start(0))?;
65            let mut h = [0u8; 32];
66            file.read_exact(&mut h)?;
67            // Seek back to end for appending.
68            file.seek(SeekFrom::End(0))?;
69            h
70        } else {
71            // New or empty file: write zero header so the layout is established.
72            file.seek(SeekFrom::Start(0))?;
73            file.write_all(&[0u8; 32])?;
74            file.sync_all()?;
75            file.seek(SeekFrom::End(0))?;
76            [0u8; 32]
77        };
78
79        Ok(Self {
80            file,
81            prev_dag_hash,
82        })
83    }
84
85    /// Synchronously appends a NQuin to the log and flushes to disk.
86    /// This prevents data loss if the OS kills the process.
87    pub fn append_mutation(&mut self, quin: &NQuin) -> std::io::Result<()> {
88        // Always append — the file cursor is already at the end after open().
89        self.file.write_all(quin_as_bytes(quin))?;
90        self.file.sync_all()?;
91        Ok(())
92    }
93
94    /// Append with volatile field scrub after durable sync (wipes transient reasoning state).
95    pub fn append_mutation_volatile(&mut self, quin: &mut NQuin) -> std::io::Result<()> {
96        self.file.write_all(quin_as_bytes(quin))?;
97        self.file.sync_all()?;
98        scrub_quin_volatile(quin);
99        Ok(())
100    }
101
102    /// Reconstructs uncommitted NQuins from the WAL (skips the 32-byte header).
103    pub fn recover(&mut self) -> std::io::Result<Vec<NQuin>> {
104        self.file.seek(SeekFrom::Start(WAL_HEADER_SIZE))?;
105
106        let mut buffer = Vec::new();
107        self.file.read_to_end(&mut buffer)?;
108
109        let quin_size = std::mem::size_of::<NQuin>();
110        let mut recovered = Vec::with_capacity(buffer.len() / quin_size);
111
112        // Only read complete 48-byte chunks — partial chunks mean a mid-write crash; discard.
113        for chunk in buffer.chunks_exact(quin_size) {
114            let quin: NQuin = unsafe { std::ptr::read_unaligned(chunk.as_ptr() as *const NQuin) };
115            recovered.push(quin);
116        }
117
118        Ok(recovered)
119    }
120
121    /// Wipes the NQuin region of the WAL after a SuperBlock commit, preserving the header.
122    ///
123    /// Call `checkpoint_to_dag` **before** this so the hash chain is updated first.
124    pub fn truncate(&mut self) -> std::io::Result<()> {
125        self.file.set_len(WAL_HEADER_SIZE)?;
126        self.file.seek(SeekFrom::End(0))?;
127        self.file.sync_all()?;
128        Ok(())
129    }
130
131    /// Commit the current WAL contents as a DagNode, updating `prev_dag_hash`.
132    ///
133    /// If the WAL is empty (no quins since the last checkpoint), this is a no-op and
134    /// returns the existing `prev_dag_hash`.
135    ///
136    /// Typical call sequence:
137    /// ```text
138    /// wal.checkpoint_to_dag(&mut dag_store, author_did, now_ms())?;
139    /// wal.truncate()?;
140    /// ```
141    pub fn checkpoint_to_dag(
142        &mut self,
143        dag_store: &mut crate::git_bridge::DagStore,
144        author_did: u64,
145        timestamp_ms: u64,
146    ) -> std::io::Result<[u8; 32]> {
147        let quins = self.recover()?;
148        if quins.is_empty() {
149            return Ok(self.prev_dag_hash);
150        }
151
152        let new_hash = if self.prev_dag_hash == [0u8; 32] {
153            dag_store.genesis_node(&quins, author_did, timestamp_ms, WAL_CHECKPOINT_MSG)
154        } else {
155            dag_store.commit_node(
156                self.prev_dag_hash,
157                &quins,
158                author_did,
159                timestamp_ms,
160                WAL_CHECKPOINT_MSG,
161            )
162        };
163
164        // Persist the new hash into the WAL header so it survives a crash.
165        self.file.seek(SeekFrom::Start(0))?;
166        self.file.write_all(&new_hash)?;
167        self.file.sync_all()?;
168        // Restore cursor to end for continued appending.
169        self.file.seek(SeekFrom::End(0))?;
170
171        self.prev_dag_hash = new_hash;
172        Ok(new_hash)
173    }
174
175    /// Return the number of NQuin records currently buffered in the WAL.
176    pub fn buffered_count(&mut self) -> std::io::Result<usize> {
177        let file_len = self.file.seek(SeekFrom::End(0))?;
178        let data_len = file_len.saturating_sub(WAL_HEADER_SIZE);
179        Ok((data_len as usize) / std::mem::size_of::<NQuin>())
180    }
181}
182
183#[cfg(target_arch = "wasm32")]
184impl WriteAheadLog {
185    /// Opens.
186    pub fn open<P: AsRef<Path>>(_path: P) -> std::io::Result<Self> {
187        let mut file = Vec::with_capacity(1024);
188        file.extend_from_slice(&[0u8; 32]);
189        Ok(Self {
190            file,
191            prev_dag_hash: [0; 32],
192        })
193    }
194
195    /// Appends a durable mutation record for `quin`.
196    pub fn append_mutation(&mut self, quin: &NQuin) -> std::io::Result<()> {
197        self.file.extend_from_slice(quin_as_bytes(quin));
198        Ok(())
199    }
200
201    /// Appends a mutation flagged volatile (not expected to survive crash recovery).
202    pub fn append_mutation_volatile(&mut self, quin: &mut NQuin) -> std::io::Result<()> {
203        self.file.extend_from_slice(quin_as_bytes(quin));
204        scrub_quin_volatile(quin);
205        Ok(())
206    }
207
208    /// Replays the log, returning all durable mutations in order.
209    pub fn recover(&mut self) -> std::io::Result<Vec<NQuin>> {
210        if self.file.len() < WAL_HEADER_SIZE as usize {
211            return Ok(Vec::new());
212        }
213        let quin_size = std::mem::size_of::<NQuin>();
214        let data = &self.file[WAL_HEADER_SIZE as usize..];
215        let mut recovered = Vec::with_capacity(data.len() / quin_size);
216
217        for chunk in data.chunks_exact(quin_size) {
218            let quin: NQuin = unsafe { std::ptr::read_unaligned(chunk.as_ptr() as *const NQuin) };
219            recovered.push(quin);
220        }
221
222        Ok(recovered)
223    }
224
225    /// Clears the log after successful checkpoint.
226    pub fn truncate(&mut self) -> std::io::Result<()> {
227        self.file.truncate(WAL_HEADER_SIZE as usize);
228        Ok(())
229    }
230
231    /// Checkpoints buffered mutations into the DAG store.
232    pub fn checkpoint_to_dag(
233        &mut self,
234        dag_store: &mut crate::git_bridge::DagStore,
235        author_did: u64,
236        timestamp_ms: u64,
237    ) -> std::io::Result<[u8; 32]> {
238        let quins = self.recover()?;
239        if quins.is_empty() {
240            return Ok(self.prev_dag_hash);
241        }
242
243        let new_hash = if self.prev_dag_hash == [0u8; 32] {
244            dag_store.genesis_node(&quins, author_did, timestamp_ms, WAL_CHECKPOINT_MSG)
245        } else {
246            dag_store.commit_node(
247                self.prev_dag_hash,
248                &quins,
249                author_did,
250                timestamp_ms,
251                WAL_CHECKPOINT_MSG,
252            )
253        };
254
255        if self.file.len() >= 32 {
256            self.file[0..32].copy_from_slice(&new_hash);
257        }
258        self.prev_dag_hash = new_hash;
259        Ok(new_hash)
260    }
261
262    /// Mutations buffered but not yet checkpointed.
263    pub fn buffered_count(&mut self) -> std::io::Result<usize> {
264        let data_len = self.file.len().saturating_sub(WAL_HEADER_SIZE as usize);
265        Ok(data_len / std::mem::size_of::<NQuin>())
266    }
267}
268
269#[inline]
270fn quin_as_bytes(quin: &NQuin) -> &[u8] {
271    unsafe {
272        std::slice::from_raw_parts(
273            (quin as *const NQuin) as *const u8,
274            std::mem::size_of::<NQuin>(),
275        )
276    }
277}
278
279/// Outcome of routing a sieve-emitted Quin into the ledger pipeline.
280#[derive(Debug, Clone, Copy, PartialEq, Eq)]
281pub enum WalHandoffResult {
282    Committed,
283    Suspended { agreement_id: u64 },
284}
285
286/// Fiduciary-stamped, signed WAL handoff for neuro-symbolic graph mutations (zero String parse).
287pub fn commit_semantic_mutation(
288    wal: &mut WriteAheadLog,
289    quin: &mut NQuin,
290    principal_did_hash: u64,
291    agent_did_hash: u64,
292    signing_key: &SigningKey,
293    suspended: &mut SuspendedTransactionQueue,
294) -> io::Result<WalHandoffResult> {
295    stamp_fiduciary_metadata(quin, principal_did_hash, agent_did_hash);
296    let _sig: Signature = sign_graph_mutation(signing_key, quin);
297
298    if quin.identify_routing_lane() == PermissiveRoutingLane::EnforceBilateralMicroCommons {
299        let agreement_id = quin.context;
300        let tx = crate::crdt::SuspendedTransaction {
301            agreement_id,
302            threshold: 2,
303            collected_signatures: 1,
304            registers: [None; 16],
305            bytecode_buffer: [None; 64],
306            yielded_op: Some(WebizenOpcode::LoadModel(0)),
307            suspended_quin: *quin,
308        };
309        if suspended.push(tx).is_err() {
310            return Err(std::io::Error::new(
311                std::io::ErrorKind::Other,
312                "suspended transaction queue full",
313            ));
314        }
315        scrub_quin_volatile(quin);
316        return Ok(WalHandoffResult::Suspended { agreement_id });
317    }
318
319    wal.append_mutation_volatile(quin)?;
320    Ok(WalHandoffResult::Committed)
321}
322
323/// Appends a mutation to the global Write-Ahead Log.
324/// For the MVP/MCP, we write to a default location or stderr.
325pub fn append_mutation(quin: &NQuin) -> io::Result<()> {
326    // In a real implementation this would use a globally managed WAL lock.
327    // For now we open it locally or just pass.
328    let mut wal = WriteAheadLog::open("qualia_global.wal")?;
329    wal.append_mutation(quin)
330}
331
332/// Logs an adversarial conduct violation to the WAL when the Sentinel VM halts execution.
333pub fn log_adversarial_conduct(
334    intent_quin: &NQuin,
335    violation_code: u8,
336    vm_cycles: u64,
337) -> io::Result<()> {
338    let violation_quin = NQuin {
339        subject: intent_quin.subject,
340        predicate: crate::q_hash("q42:conductViolation"),
341        object: intent_quin.object,
342        context: intent_quin.context,
343        metadata: (violation_code as u64) | (vm_cycles << 8),
344        parity: 0,
345    };
346    append_mutation(&violation_quin)
347}
348
349/// Logs a rule-evaluation audit event to the WAL.
350///
351/// For each `RuleResult` in `results`, appends a `q42:ruleEvaluation` Quin to the
352/// WAL with:
353/// - `subject`    = the evaluated Quin's subject
354/// - `predicate`  = `q_hash("q42:ruleEvaluation")`
355/// - `object`     = `q_hash(rule_name)` (the rule that was evaluated)
356/// - `context`    = the contract graph hash
357/// - `metadata`   = bit 0 = passed/failed; bits [8..15] = result count
358///
359/// This ensures every rule evaluation is durable, replayable, and auditable —
360/// the general-purpose event API complement to `log_adversarial_conduct`.
361pub fn log_rule_evaluation(
362    input_quin: &NQuin,
363    results: &[crate::modalities::logic::rules::RuleResult],
364    contract_hash: u64,
365) -> io::Result<()> {
366    let eval_predicate = crate::modalities::logic::rules::RULE_EVAL_PREDICATE;
367    let result_count = results.len().min(255) as u64;
368    for (i, result) in results.iter().enumerate().take(255) {
369        let rule_hash = crate::q_hash(&result.rule_name);
370        let mut metadata = if result.passed { 1u64 } else { 0u64 };
371        metadata |= (i as u64) << 16;
372        metadata |= result_count << 8;
373        let eval_quin = NQuin {
374            subject: input_quin.subject,
375            predicate: eval_predicate,
376            object: rule_hash,
377            context: contract_hash,
378            metadata,
379            parity: 0,
380        };
381        append_mutation(&eval_quin)?;
382    }
383    Ok(())
384}
385
386#[cfg(test)]
387mod tests {
388    use super::*;
389    use tempfile::NamedTempFile;
390
391    fn make_quin(subject: u64, object: u64) -> NQuin {
392        NQuin {
393            subject,
394            predicate: 2,
395            object,
396            context: 4,
397            metadata: 0,
398            parity: 0,
399        }
400    }
401
402    #[test]
403    fn wal_append_and_recover() {
404        let tmp = NamedTempFile::new().unwrap();
405        let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
406
407        wal.append_mutation(&make_quin(1, 3)).unwrap();
408        wal.append_mutation(&make_quin(10, 30)).unwrap();
409
410        let recovered = wal.recover().unwrap();
411        assert_eq!(recovered.len(), 2, "WAL must recover 2 quins");
412        assert_eq!(recovered[0].subject, 1);
413        assert_eq!(recovered[1].object, 30);
414
415        wal.truncate().unwrap();
416        assert_eq!(wal.recover().unwrap().len(), 0, "WAL truncation failed");
417    }
418
419    #[test]
420    fn wal_header_persists_across_reopen() {
421        let tmp = NamedTempFile::new().unwrap();
422        {
423            let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
424            assert_eq!(wal.prev_dag_hash, [0u8; 32]);
425            wal.append_mutation(&make_quin(42, 99)).unwrap();
426        }
427        // Reopen — header must still be there; quin must be recoverable.
428        {
429            let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
430            assert_eq!(wal.prev_dag_hash, [0u8; 32]);
431            let quins = wal.recover().unwrap();
432            assert_eq!(quins.len(), 1);
433            assert_eq!(quins[0].subject, 42);
434        }
435    }
436
437    #[test]
438    fn wal_checkpoint_to_dag_chains_nodes() {
439        let tmp = NamedTempFile::new().unwrap();
440        let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
441        let mut dag = crate::git_bridge::DagStore::new();
442        const AUTHOR: u64 = 0xA007_0001;
443
444        // First checkpoint — should produce a genesis node.
445        wal.append_mutation(&make_quin(1, 1)).unwrap();
446        wal.append_mutation(&make_quin(2, 2)).unwrap();
447        let hash1 = wal.checkpoint_to_dag(&mut dag, AUTHOR, 1000).unwrap();
448        assert_ne!(hash1, [0u8; 32], "genesis hash must be non-zero");
449        assert_eq!(wal.prev_dag_hash, hash1);
450        wal.truncate().unwrap();
451        assert_eq!(wal.recover().unwrap().len(), 0);
452
453        // Second checkpoint — should produce a commit node chained from hash1.
454        wal.append_mutation(&make_quin(3, 3)).unwrap();
455        let hash2 = wal.checkpoint_to_dag(&mut dag, AUTHOR, 2000).unwrap();
456        assert_ne!(hash2, hash1, "second checkpoint must have a different hash");
457        assert_eq!(wal.prev_dag_hash, hash2);
458        wal.truncate().unwrap();
459
460        // Verify DAG has 2 nodes.
461        let serialized = dag.serialize();
462        assert!(!serialized.is_empty());
463    }
464
465    #[test]
466    fn wal_checkpoint_empty_wal_is_noop() {
467        let tmp = NamedTempFile::new().unwrap();
468        let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
469        let mut dag = crate::git_bridge::DagStore::new();
470
471        // Empty WAL — checkpoint must return the existing (zero) prev_dag_hash.
472        let hash = wal.checkpoint_to_dag(&mut dag, 0, 0).unwrap();
473        assert_eq!(hash, [0u8; 32]);
474        // An empty DagStore serializes to just the 8-byte node-count header (count=0).
475        let serialized = dag.serialize();
476        let node_count = u64::from_le_bytes(serialized[..8].try_into().unwrap());
477        assert_eq!(node_count, 0, "no DagNodes should be created for empty WAL");
478    }
479
480    #[test]
481    fn wal_buffered_count() {
482        let tmp = NamedTempFile::new().unwrap();
483        let mut wal = WriteAheadLog::open(tmp.path()).unwrap();
484        assert_eq!(wal.buffered_count().unwrap(), 0);
485        wal.append_mutation(&make_quin(1, 1)).unwrap();
486        wal.append_mutation(&make_quin(2, 2)).unwrap();
487        assert_eq!(wal.buffered_count().unwrap(), 2);
488    }
489}