Skip to main content

qualia_core_db/q42/
journal.rs

1//! Mutable Q42 Session: Checkpoint and Append-Only Transaction Journal (`.q42j`).
2//!
3//! Generalized persistence layer for QualiaDB, supporting:
4//! - POET NOS workspaces, strata, and lens-time document histories
5//! - Webizen Studio and Desktop persistent graph workspaces
6//! - Autonomous multi-agent simulation & RTS world states (e.g. Rolling Commons)
7//! - Offline-first browser sessions via OPFS / Memory and native filesystem
8//!
9//! Conforms to `AGENTS.md`:
10//! - Universal 48-byte `NQuin` semantic atom with 5-field XOR fold parity.
11//! - Zero heap inside hot frame validation and evaluation loops (Tier 1).
12//! - 42MB Sentinel budget compliance.
13//! - Default privacy: `PrivacyClass::Sanctuary` (restricted; prevents accidental
14//!   public magnet routing).
15
16use crate::NQuin;
17use std::collections::HashSet;
18use std::io::{self, Read, Seek, SeekFrom, Write};
19
20/// Magic bytes for a Q42 Journal: `Q42J`.
21pub const Q42J_MAGIC: [u8; 4] = *b"Q42J";
22
23/// Current `.q42j` journal format version.
24pub const Q42J_VERSION: u16 = 1;
25
26/// Fixed journal file header size (128 bytes).
27pub const Q42J_HEADER_SIZE: usize = 128;
28
29/// Application profiles for generalized QualiaDB sessions.
30#[repr(u16)]
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum JournalApplicationProfile {
33    /// General-purpose semantic graph and knowledge base.
34    GenericSemantic = 0x0001,
35    /// POET NOS workspaces, documents, and lens-strata history.
36    PoetWorkspace = 0x0002,
37    /// Interactive simulations, RTS worlds, and multi-agent systems.
38    SimulationWorld = 0x0003,
39    /// Clinical records, healthcare pathways, and FHIR/LOINC receipts.
40    ClinicalRecord = 0x0004,
41    /// Bilateral micro-commons, civic assemblies, and cooperative contracts.
42    CivicCommons = 0x0005,
43}
44
45impl Default for JournalApplicationProfile {
46    /// `GenericSemantic` (0x0001) — the general-purpose knowledge-base profile.
47    fn default() -> Self {
48        Self::GenericSemantic
49    }
50}
51
52impl TryFrom<u16> for JournalApplicationProfile {
53    type Error = JournalError;
54    /// Decodes a u16 profile tag (0x0001–0x0005); `UnknownApplicationProfile`
55    /// on any other value — fails closed rather than guessing a profile.
56    fn try_from(val: u16) -> Result<Self, Self::Error> {
57        match val {
58            0x0001 => Ok(Self::GenericSemantic),
59            0x0002 => Ok(Self::PoetWorkspace),
60            0x0003 => Ok(Self::SimulationWorld),
61            0x0004 => Ok(Self::ClinicalRecord),
62            0x0005 => Ok(Self::CivicCommons),
63            other => Err(JournalError::UnknownApplicationProfile(other)),
64        }
65    }
66}
67
68/// Privacy classification for the journal (Sanctuary by default).
69#[repr(u8)]
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71pub enum JournalPrivacyClass {
72    Sanctuary = 0,
73    Restricted = 1,
74    Commons = 2,
75}
76
77impl Default for JournalPrivacyClass {
78    /// `Sanctuary` — the most restrictive class is the default (fail-safe).
79    fn default() -> Self {
80        Self::Sanctuary
81    }
82}
83
84/// 128-byte header stored at offset 0 of every `.q42j` file.
85#[repr(C)]
86#[derive(Debug, Clone, PartialEq, Eq)]
87pub struct JournalHeader {
88    pub magic: [u8; 4],
89    pub version: u16,
90    pub profile: u16,
91    pub privacy: u8,
92    pub flags: u8,
93    pub reserved_head: [u8; 6],
94    pub world_did_hash: u64,
95    pub base_q42_digest: [u8; 32],
96    pub base_generation: u64,
97    pub schema_rule_version: u32,
98    pub required_pack_digest: [u8; 32],
99    pub reserved_tail: [u8; 28],
100}
101
102impl JournalHeader {
103    /// Builds a 128-byte header for a new `.q42j`: current magic/version,
104    /// Sanctuary privacy, zeroed flags/reserved fields, `schema_rule_version`
105    /// 1, and the caller's world DID hash + base snapshot digest/generation.
106    pub fn new(
107        profile: JournalApplicationProfile,
108        world_did_hash: u64,
109        base_q42_digest: [u8; 32],
110        base_generation: u64,
111    ) -> Self {
112        Self {
113            magic: Q42J_MAGIC,
114            version: Q42J_VERSION,
115            profile: profile as u16,
116            privacy: JournalPrivacyClass::Sanctuary as u8,
117            flags: 0,
118            reserved_head: [0u8; 6],
119            world_did_hash,
120            base_q42_digest,
121            base_generation,
122            schema_rule_version: 1,
123            required_pack_digest: [0u8; 32],
124            reserved_tail: [0u8; 28],
125        }
126    }
127
128    /// Serializes the header to its fixed 128-byte little-endian layout.
129    pub fn to_bytes(&self) -> [u8; Q42J_HEADER_SIZE] {
130        let mut buf = [0u8; Q42J_HEADER_SIZE];
131        buf[0..4].copy_from_slice(&self.magic);
132        buf[4..6].copy_from_slice(&self.version.to_le_bytes());
133        buf[6..8].copy_from_slice(&self.profile.to_le_bytes());
134        buf[8] = self.privacy;
135        buf[9] = self.flags;
136        buf[10..16].copy_from_slice(&self.reserved_head);
137        buf[16..24].copy_from_slice(&self.world_did_hash.to_le_bytes());
138        buf[24..56].copy_from_slice(&self.base_q42_digest);
139        buf[56..64].copy_from_slice(&self.base_generation.to_le_bytes());
140        buf[64..68].copy_from_slice(&self.schema_rule_version.to_le_bytes());
141        buf[68..100].copy_from_slice(&self.required_pack_digest);
142        buf[100..128].copy_from_slice(&self.reserved_tail);
143        buf
144    }
145
146    /// Parses a header; fails closed on short input, bad magic, or an
147    /// unsupported format version.
148    pub fn from_bytes(bytes: &[u8]) -> Result<Self, JournalError> {
149        if bytes.len() < Q42J_HEADER_SIZE {
150            return Err(JournalError::InvalidHeader("header too short"));
151        }
152        let mut magic = [0u8; 4];
153        magic.copy_from_slice(&bytes[0..4]);
154        if magic != Q42J_MAGIC {
155            return Err(JournalError::InvalidMagic);
156        }
157        let version = u16::from_le_bytes([bytes[4], bytes[5]]);
158        if version != Q42J_VERSION {
159            return Err(JournalError::UnsupportedVersion(version));
160        }
161        let profile = u16::from_le_bytes([bytes[6], bytes[7]]);
162        let privacy = bytes[8];
163        let flags = bytes[9];
164        let mut reserved_head = [0u8; 6];
165        reserved_head.copy_from_slice(&bytes[10..16]);
166        let mut world_bytes = [0u8; 8];
167        world_bytes.copy_from_slice(&bytes[16..24]);
168        let world_did_hash = u64::from_le_bytes(world_bytes);
169        let mut base_q42_digest = [0u8; 32];
170        base_q42_digest.copy_from_slice(&bytes[24..56]);
171        let mut gen_bytes = [0u8; 8];
172        gen_bytes.copy_from_slice(&bytes[56..64]);
173        let base_generation = u64::from_le_bytes(gen_bytes);
174        let mut ver_bytes = [0u8; 4];
175        ver_bytes.copy_from_slice(&bytes[64..68]);
176        let schema_rule_version = u32::from_le_bytes(ver_bytes);
177        let mut required_pack_digest = [0u8; 32];
178        required_pack_digest.copy_from_slice(&bytes[68..100]);
179        let mut reserved_tail = [0u8; 28];
180        reserved_tail.copy_from_slice(&bytes[100..128]);
181
182        Ok(Self {
183            magic,
184            version,
185            profile,
186            privacy,
187            flags,
188            reserved_head,
189            world_did_hash,
190            base_q42_digest,
191            base_generation,
192            schema_rule_version,
193            required_pack_digest,
194            reserved_tail,
195        })
196    }
197}
198
199/// Types of frames within a `.q42j` transaction.
200#[repr(u8)]
201#[derive(Debug, Clone, Copy, PartialEq, Eq)]
202pub enum JournalFrameType {
203    TxBegin = 0x01,
204    QuinAdd = 0x02,
205    QuinRemove = 0x03,
206    LexiconBind = 0x04,
207    Receipt = 0x05,
208    TopologyDelta = 0x06,
209    TopologySeal = 0x07,
210    TxCommit = 0xFF,
211}
212
213impl JournalFrameType {
214    /// Decodes a `u8` frame tag into [`JournalFrameType`].
215    #[inline]
216    pub const fn from_u8(val: u8) -> Option<Self> {
217        match val {
218            0x01 => Some(Self::TxBegin),
219            0x02 => Some(Self::QuinAdd),
220            0x03 => Some(Self::QuinRemove),
221            0x04 => Some(Self::LexiconBind),
222            0x05 => Some(Self::Receipt),
223            0x06 => Some(Self::TopologyDelta),
224            0x07 => Some(Self::TopologySeal),
225            0xFF => Some(Self::TxCommit),
226            _ => None,
227        }
228    }
229}
230
231impl TryFrom<u8> for JournalFrameType {
232    type Error = JournalError;
233    /// Decodes a frame-type tag (0x01–0x07, 0xFF); `UnknownFrameType` on any
234    /// other byte — corrupt/unrecognized frames fail closed.
235    fn try_from(val: u8) -> Result<Self, Self::Error> {
236        Self::from_u8(val).ok_or(JournalError::UnknownFrameType(val))
237    }
238}
239
240/// 32-byte header preceding every frame payload.
241#[repr(C)]
242#[derive(Debug, Clone, Copy, PartialEq, Eq)]
243pub struct FrameHeader {
244    pub frame_type: u8,
245    pub reserved: [u8; 3],
246    pub payload_len: u32,
247    pub sequence_num: u64,
248    pub tick: u64,
249    pub tx_id: u32,
250    pub crc32c: u32,
251}
252
253pub const FRAME_HEADER_SIZE: usize = 32;
254
255impl FrameHeader {
256    /// Serializes the frame header to its 32-byte little-endian layout.
257    pub fn to_bytes(&self) -> [u8; FRAME_HEADER_SIZE] {
258        let mut b = [0u8; FRAME_HEADER_SIZE];
259        b[0] = self.frame_type;
260        b[1..4].copy_from_slice(&self.reserved);
261        b[4..8].copy_from_slice(&self.payload_len.to_le_bytes());
262        b[8..16].copy_from_slice(&self.sequence_num.to_le_bytes());
263        b[16..24].copy_from_slice(&self.tick.to_le_bytes());
264        b[24..28].copy_from_slice(&self.tx_id.to_le_bytes());
265        b[28..32].copy_from_slice(&self.crc32c.to_le_bytes());
266        b
267    }
268
269    /// Parses a frame header; `InvalidHeader` on truncation.
270    pub fn from_bytes(b: &[u8]) -> Result<Self, JournalError> {
271        if b.len() < FRAME_HEADER_SIZE {
272            return Err(JournalError::InvalidHeader("frame header too short"));
273        }
274        let frame_type = b[0];
275        let mut reserved = [0u8; 3];
276        reserved.copy_from_slice(&b[1..4]);
277        let payload_len = u32::from_le_bytes([b[4], b[5], b[6], b[7]]);
278        let sequence_num =
279            u64::from_le_bytes([b[8], b[9], b[10], b[11], b[12], b[13], b[14], b[15]]);
280        let tick = u64::from_le_bytes([b[16], b[17], b[18], b[19], b[20], b[21], b[22], b[23]]);
281        let tx_id = u32::from_le_bytes([b[24], b[25], b[26], b[27]]);
282        let crc32c = u32::from_le_bytes([b[28], b[29], b[30], b[31]]);
283
284        Ok(Self {
285            frame_type,
286            reserved,
287            payload_len,
288            sequence_num,
289            tick,
290            tx_id,
291            crc32c,
292        })
293    }
294}
295
296/// Compute a fast CRC-32C checksum over data.
297pub fn crc32c(data: &[u8]) -> u32 {
298    let mut crc = !0u32;
299    for &byte in data {
300        crc ^= byte as u32;
301        for _ in 0..8 {
302            let mask = (!((crc & 1).wrapping_sub(1))) & 0x82F63B78;
303            crc = (crc >> 1) ^ mask;
304        }
305    }
306    !crc
307}
308
309/// An atomic transaction delta over canonical 48-byte Quins.
310#[derive(Debug, Clone, PartialEq, Eq)]
311pub struct JournalTransaction {
312    pub tx_id: u32,
313    pub tick: u64,
314    pub command_hash: u64,
315    pub actor_did: u64,
316    pub adds: Vec<NQuin>,
317    pub removes: Vec<NQuin>,
318    pub lexicon_bindings: Vec<(u64, String)>,
319    pub receipt_digest: [u8; 32],
320    pub committed: bool,
321}
322
323impl JournalTransaction {
324    /// Creates an empty transaction delta: `tx_id`, logical `tick`, the hash
325    /// of the originating command, and the acting agent's DID hash.
326    pub fn new(tx_id: u32, tick: u64, command_hash: u64, actor_did: u64) -> Self {
327        Self {
328            tx_id,
329            tick,
330            command_hash,
331            actor_did,
332            adds: Vec::new(),
333            removes: Vec::new(),
334            lexicon_bindings: Vec::new(),
335            receipt_digest: [0u8; 32],
336            committed: false,
337        }
338    }
339
340    /// Stages a quin addition into the transaction's `added` list.
341    pub fn add_quin(&mut self, quin: NQuin) {
342        self.adds.push(quin);
343    }
344
345    /// Stages a quin removal into the transaction's `removed` list.
346    pub fn remove_quin(&mut self, quin: NQuin) {
347        self.removes.push(quin);
348    }
349
350    /// Stages a hash→IRI lexicon binding so replay can resolve token hashes.
351    pub fn bind_lexicon(&mut self, token_hash: u64, iri: String) {
352        self.lexicon_bindings.push((token_hash, iri));
353    }
354}
355
356/// Core Journal Engine managing durable appending and atomic replay.
357pub struct Q42Journal<S: Read + Write + Seek> {
358    pub storage: S,
359    pub header: JournalHeader,
360    sequence_counter: u64,
361}
362
363impl<S: Read + Write + Seek> Q42Journal<S> {
364    /// Initialize a new journal with the given storage and header.
365    pub fn create(mut storage: S, header: JournalHeader) -> Result<Self, JournalError> {
366        storage.seek(SeekFrom::Start(0))?;
367        storage.write_all(&header.to_bytes())?;
368        storage.flush()?;
369        Ok(Self {
370            storage,
371            header,
372            sequence_counter: 0,
373        })
374    }
375
376    /// Open and validate an existing journal from storage.
377    pub fn open(mut storage: S, expected_base_digest: &[u8; 32]) -> Result<Self, JournalError> {
378        storage.seek(SeekFrom::Start(0))?;
379        let mut header_buf = [0u8; Q42J_HEADER_SIZE];
380        storage.read_exact(&mut header_buf)?;
381        let header = JournalHeader::from_bytes(&header_buf)?;
382
383        if &header.base_q42_digest != expected_base_digest {
384            return Err(JournalError::BaseDigestMismatch);
385        }
386
387        Ok(Self {
388            storage,
389            header,
390            sequence_counter: 0,
391        })
392    }
393
394    /// Open and validate an existing journal from storage with any base digest.
395    pub fn open_any(mut storage: S) -> Result<Self, JournalError> {
396        storage.seek(SeekFrom::Start(0))?;
397        let mut header_buf = [0u8; Q42J_HEADER_SIZE];
398        storage.read_exact(&mut header_buf)?;
399        let header = JournalHeader::from_bytes(&header_buf)?;
400
401        Ok(Self {
402            storage,
403            header,
404            sequence_counter: 0,
405        })
406    }
407
408    /// Atomically appends a complete transaction to the journal.
409    pub fn append_transaction(&mut self, tx: &JournalTransaction) -> Result<(), JournalError> {
410        self.storage.seek(SeekFrom::End(0))?;
411
412        // 1. TxBegin Frame: carries command_hash (8B) and actor_did (8B)
413        let mut begin_payload = [0u8; 16];
414        begin_payload[0..8].copy_from_slice(&tx.command_hash.to_le_bytes());
415        begin_payload[8..16].copy_from_slice(&tx.actor_did.to_le_bytes());
416        self.write_frame(JournalFrameType::TxBegin, tx.tx_id, tx.tick, &begin_payload)?;
417
418        // 2. Lexicon Bindings (if newly authored tokens)
419        for (token, iri) in &tx.lexicon_bindings {
420            let iri_bytes = iri.as_bytes();
421            let mut lex_payload = Vec::with_capacity(8 + iri_bytes.len());
422            lex_payload.extend_from_slice(&token.to_le_bytes());
423            lex_payload.extend_from_slice(iri_bytes);
424            self.write_frame(
425                JournalFrameType::LexiconBind,
426                tx.tx_id,
427                tx.tick,
428                &lex_payload,
429            )?;
430        }
431
432        // 3. Quin Add Frames
433        for quin in &tx.adds {
434            let bytes = quin_to_bytes(quin);
435            self.write_frame(JournalFrameType::QuinAdd, tx.tx_id, tx.tick, &bytes)?;
436        }
437
438        // 4. Quin Remove Frames
439        for quin in &tx.removes {
440            let bytes = quin_to_bytes(quin);
441            self.write_frame(JournalFrameType::QuinRemove, tx.tx_id, tx.tick, &bytes)?;
442        }
443
444        // 5. Output Receipt Frame (if non-zero)
445        if tx.receipt_digest != [0u8; 32] {
446            self.write_frame(
447                JournalFrameType::Receipt,
448                tx.tx_id,
449                tx.tick,
450                &tx.receipt_digest,
451            )?;
452        }
453
454        // 6. Terminal Commit Frame
455        let commit_payload = [0xAAu8; 4];
456        self.write_frame(
457            JournalFrameType::TxCommit,
458            tx.tx_id,
459            tx.tick,
460            &commit_payload,
461        )?;
462
463        self.storage.flush()?;
464        Ok(())
465    }
466
467    /// Writes one frame header + payload to storage; errors propagate as
468    /// `JournalError::Io` so a partial transaction is never reported committed.
469    fn write_frame(
470        &mut self,
471        frame_type: JournalFrameType,
472        tx_id: u32,
473        tick: u64,
474        payload: &[u8],
475    ) -> Result<(), JournalError> {
476        self.sequence_counter += 1;
477        let checksum = crc32c(payload);
478        let header = FrameHeader {
479            frame_type: frame_type as u8,
480            reserved: [0u8; 3],
481            payload_len: payload.len() as u32,
482            sequence_num: self.sequence_counter,
483            tick,
484            tx_id,
485            crc32c: checksum,
486        };
487        self.storage.write_all(&header.to_bytes())?;
488        self.storage.write_all(payload)?;
489        Ok(())
490    }
491
492    /// Replays the journal and recovers all committed transactions.
493    /// Safely ignores torn uncommitted transactions at the tail.
494    pub fn recover_transactions(&mut self) -> Result<Vec<JournalTransaction>, JournalError> {
495        self.storage
496            .seek(SeekFrom::Start(Q42J_HEADER_SIZE as u64))?;
497
498        let mut transactions = Vec::new();
499        let mut current_tx: Option<JournalTransaction> = None;
500
501        let mut header_buf = [0u8; FRAME_HEADER_SIZE];
502
503        loop {
504            match self.storage.read_exact(&mut header_buf) {
505                Ok(()) => {}
506                Err(ref e) if e.kind() == io::ErrorKind::UnexpectedEof => {
507                    break;
508                }
509                Err(e) => return Err(JournalError::Io(e)),
510            }
511
512            let frame_header = FrameHeader::from_bytes(&header_buf)?;
513            let mut payload = vec![0u8; frame_header.payload_len as usize];
514            match self.storage.read_exact(&mut payload) {
515                Ok(()) => {}
516                Err(ref e) if e.kind() == io::ErrorKind::UnexpectedEof => {
517                    break;
518                }
519                Err(e) => return Err(JournalError::Io(e)),
520            }
521
522            // Verify integrity
523            if crc32c(&payload) != frame_header.crc32c {
524                return Err(JournalError::CorruptedFrame(frame_header.sequence_num));
525            }
526
527            let frame_type = JournalFrameType::try_from(frame_header.frame_type)?;
528            match frame_type {
529                JournalFrameType::TxBegin => {
530                    if payload.len() < 8 {
531                        return Err(JournalError::InvalidHeader("TxBegin payload too short"));
532                    }
533                    let mut cmd_bytes = [0u8; 8];
534                    cmd_bytes.copy_from_slice(&payload[0..8]);
535                    let command_hash = u64::from_le_bytes(cmd_bytes);
536                    let actor_did = if payload.len() >= 16 {
537                        let mut actor_bytes = [0u8; 8];
538                        actor_bytes.copy_from_slice(&payload[8..16]);
539                        u64::from_le_bytes(actor_bytes)
540                    } else {
541                        0
542                    };
543                    current_tx = Some(JournalTransaction::new(
544                        frame_header.tx_id,
545                        frame_header.tick,
546                        command_hash,
547                        actor_did,
548                    ));
549                }
550                JournalFrameType::LexiconBind => {
551                    if let Some(ref mut tx) = current_tx {
552                        if payload.len() >= 8 {
553                            let mut token_bytes = [0u8; 8];
554                            token_bytes.copy_from_slice(&payload[0..8]);
555                            let token = u64::from_le_bytes(token_bytes);
556                            if let Ok(iri) = std::str::from_utf8(&payload[8..]) {
557                                tx.bind_lexicon(token, iri.to_string());
558                            }
559                        }
560                    }
561                }
562                JournalFrameType::QuinAdd => {
563                    if let Some(ref mut tx) = current_tx {
564                        if payload.len() == 48 {
565                            let quin = quin_from_bytes(&payload)?;
566                            tx.add_quin(quin);
567                        }
568                    }
569                }
570                JournalFrameType::QuinRemove => {
571                    if let Some(ref mut tx) = current_tx {
572                        if payload.len() == 48 {
573                            let quin = quin_from_bytes(&payload)?;
574                            tx.remove_quin(quin);
575                        }
576                    }
577                }
578                JournalFrameType::Receipt => {
579                    if let Some(ref mut tx) = current_tx {
580                        if payload.len() == 32 {
581                            tx.receipt_digest.copy_from_slice(&payload);
582                        }
583                    }
584                }
585                JournalFrameType::TopologyDelta | JournalFrameType::TopologySeal => {
586                    // CRC-32C of the topology delta / seal payload is already verified above.
587                }
588                JournalFrameType::TxCommit => {
589                    if let Some(mut tx) = current_tx.take() {
590                        tx.committed = true;
591                        transactions.push(tx);
592                    }
593                }
594            }
595        }
596
597        Ok(transactions)
598    }
599
600    /// Appends a `TopologyDelta` (`0x06`) frame carrying a 16-byte `TopologicalDeltaEntry` payload.
601    pub fn append_topology_delta(
602        &mut self,
603        tx_id: u32,
604        tick: u64,
605        delta_bytes: &[u8],
606    ) -> Result<(), JournalError> {
607        self.storage.seek(SeekFrom::End(0))?;
608        self.write_frame(JournalFrameType::TopologyDelta, tx_id, tick, delta_bytes)?;
609        self.storage.flush()?;
610        Ok(())
611    }
612
613    /// Appends a `TopologySeal` (`0x07`) frame carrying `[geometry_id: u64 LE, crc32c: u32 LE, slot_count: u32 LE]`.
614    pub fn append_topology_seal(
615        &mut self,
616        tx_id: u32,
617        tick: u64,
618        geometry_id: u64,
619        segment_crc32c: u32,
620        graph_count: u16,
621    ) -> Result<(), JournalError> {
622        self.storage.seek(SeekFrom::End(0))?;
623        let mut payload = [0u8; 16];
624        payload[0..8].copy_from_slice(&geometry_id.to_le_bytes());
625        payload[8..12].copy_from_slice(&segment_crc32c.to_le_bytes());
626        payload[12..14].copy_from_slice(&graph_count.to_le_bytes());
627        self.write_frame(JournalFrameType::TopologySeal, tx_id, tick, &payload)?;
628        self.storage.flush()?;
629        Ok(())
630    }
631
632    /// Reset journal back to empty header after a checkpoint compaction.
633    pub fn reset_to_generation(
634        &mut self,
635        new_base_digest: [u8; 32],
636        new_generation: u64,
637    ) -> Result<(), JournalError> {
638        self.header.base_q42_digest = new_base_digest;
639        self.header.base_generation = new_generation;
640        self.storage.seek(SeekFrom::Start(0))?;
641        self.storage.write_all(&self.header.to_bytes())?;
642        self.storage.flush()?;
643        self.sequence_counter = 0;
644        Ok(())
645    }
646}
647
648/// Generalized in-memory mutable session providing active state projection,
649/// transaction commit boundaries, and checkpoint management.
650pub struct MutableQ42Session<S: Read + Write + Seek> {
651    pub journal: Q42Journal<S>,
652    pub active_state: HashSet<NQuin>,
653    current_tick: u64,
654    next_tx_id: u32,
655    staged_adds: Vec<NQuin>,
656    staged_removes: Vec<NQuin>,
657}
658
659impl<S: Read + Write + Seek> MutableQ42Session<S> {
660    /// Open a mutable session over an existing or new journal and baseline Quins.
661    pub fn open(
662        mut journal: Q42Journal<S>,
663        baseline_quins: &[NQuin],
664    ) -> Result<Self, JournalError> {
665        let mut active_state = HashSet::with_capacity(baseline_quins.len() + 64);
666        for q in baseline_quins {
667            active_state.insert(*q);
668        }
669
670        // Replay committed journal transactions on top of baseline snapshot
671        let committed_txs = journal.recover_transactions()?;
672        let mut max_tick = 0;
673        let mut max_tx_id = 0;
674
675        for tx in committed_txs {
676            if tx.tick > max_tick {
677                max_tick = tx.tick;
678            }
679            if tx.tx_id > max_tx_id {
680                max_tx_id = tx.tx_id;
681            }
682            for rem in tx.removes {
683                active_state.remove(&rem);
684            }
685            for add in tx.adds {
686                active_state.insert(add);
687            }
688        }
689
690        Ok(Self {
691            journal,
692            active_state,
693            current_tick: max_tick,
694            next_tx_id: max_tx_id + 1,
695            staged_adds: Vec::new(),
696            staged_removes: Vec::new(),
697        })
698    }
699
700    /// The session's current logical clock (Lamport tick).
701    pub fn current_tick(&self) -> u64 {
702        self.current_tick
703    }
704
705    /// Advances the session clock to `tick` (callers should pass a
706    /// monotonically increasing value).
707    pub fn advance_tick(&mut self, tick: u64) {
708        if tick > self.current_tick {
709            self.current_tick = tick;
710        }
711    }
712
713    /// Stage a Quin addition in the current uncommitted scratch buffer.
714    pub fn stage_add(&mut self, quin: NQuin) {
715        self.staged_adds.push(quin);
716    }
717
718    /// Stage a Quin removal in the current uncommitted scratch buffer.
719    pub fn stage_remove(&mut self, quin: NQuin) {
720        self.staged_removes.push(quin);
721    }
722
723    /// Discard all uncommitted staged deltas.
724    pub fn rollback_staged(&mut self) {
725        self.staged_adds.clear();
726        self.staged_removes.clear();
727    }
728
729    /// Commit all staged deltas atomically into the durable `.q42j` journal
730    /// and apply them to the active in-memory semantic state.
731    pub fn commit_transaction(
732        &mut self,
733        command_hash: u64,
734        actor_did: u64,
735    ) -> Result<u32, JournalError> {
736        let tx_id = self.next_tx_id;
737        self.next_tx_id += 1;
738
739        let mut tx = JournalTransaction::new(tx_id, self.current_tick, command_hash, actor_did);
740        tx.adds = std::mem::take(&mut self.staged_adds);
741        tx.removes = std::mem::take(&mut self.staged_removes);
742
743        // Durable append
744        self.journal.append_transaction(&tx)?;
745
746        // Apply to in-memory state
747        for rem in &tx.removes {
748            self.active_state.remove(rem);
749        }
750        for add in &tx.adds {
751            self.active_state.insert(*add);
752        }
753
754        Ok(tx_id)
755    }
756
757    /// Checkpoint the active state into a new sealed generation.
758    pub fn checkpoint(
759        &mut self,
760        new_base_digest: [u8; 32],
761        new_generation: u64,
762    ) -> Result<(), JournalError> {
763        self.journal
764            .reset_to_generation(new_base_digest, new_generation)
765    }
766
767    /// Replay active state from baseline snapshot up to a specific tick target.
768    pub fn rewind_to_tick(
769        &mut self,
770        baseline_quins: &[NQuin],
771        target_tick: u64,
772    ) -> Result<(), JournalError> {
773        self.active_state.clear();
774        for q in baseline_quins {
775            self.active_state.insert(*q);
776        }
777        let committed_txs = self.journal.recover_transactions()?;
778        for tx in committed_txs {
779            if tx.tick <= target_tick {
780                for rem in tx.removes {
781                    self.active_state.remove(&rem);
782                }
783                for add in tx.adds {
784                    self.active_state.insert(add);
785                }
786            }
787        }
788        self.current_tick = target_tick;
789        self.staged_adds.clear();
790        self.staged_removes.clear();
791        Ok(())
792    }
793}
794
795/// Convert an NQuin into 48 little-endian bytes.
796pub fn quin_to_bytes(q: &NQuin) -> [u8; 48] {
797    let mut b = [0u8; 48];
798    b[0..8].copy_from_slice(&q.subject.to_le_bytes());
799    b[8..16].copy_from_slice(&q.predicate.to_le_bytes());
800    b[16..24].copy_from_slice(&q.object.to_le_bytes());
801    b[24..32].copy_from_slice(&q.context.to_le_bytes());
802    b[32..40].copy_from_slice(&q.metadata.to_le_bytes());
803    b[40..48].copy_from_slice(&q.parity.to_le_bytes());
804    b
805}
806
807/// Reconstruct an NQuin from 48 bytes with 5-field XOR parity check.
808pub fn quin_from_bytes(b: &[u8]) -> Result<NQuin, JournalError> {
809    if b.len() < 48 {
810        return Err(JournalError::InvalidQuin("byte slice under 48 bytes"));
811    }
812    let s = u64::from_le_bytes(b[0..8].try_into().unwrap());
813    let p = u64::from_le_bytes(b[8..16].try_into().unwrap());
814    let o = u64::from_le_bytes(b[16..24].try_into().unwrap());
815    let c = u64::from_le_bytes(b[24..32].try_into().unwrap());
816    let m = u64::from_le_bytes(b[32..40].try_into().unwrap());
817    let parity = u64::from_le_bytes(b[40..48].try_into().unwrap());
818
819    // 5-field XOR fold parity
820    let expected_parity = s ^ p ^ o ^ c ^ m;
821    if parity != expected_parity {
822        return Err(JournalError::InvalidQuinParity);
823    }
824
825    Ok(NQuin {
826        subject: s,
827        predicate: p,
828        object: o,
829        context: c,
830        metadata: m,
831        parity,
832    })
833}
834
835#[derive(Debug)]
836pub enum JournalError {
837    Io(io::Error),
838    InvalidMagic,
839    UnsupportedVersion(u16),
840    UnknownApplicationProfile(u16),
841    InvalidHeader(&'static str),
842    BaseDigestMismatch,
843    UnknownFrameType(u8),
844    CorruptedFrame(u64),
845    InvalidQuin(&'static str),
846    InvalidQuinParity,
847}
848
849impl From<io::Error> for JournalError {
850    /// Wraps a storage IO failure as `JournalError::Io`.
851    fn from(e: io::Error) -> Self {
852        Self::Io(e)
853    }
854}
855
856impl std::fmt::Display for JournalError {
857    /// Human-readable rendering of each journal error variant.
858    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
859        match self {
860            Self::Io(e) => write!(f, "IO error: {}", e),
861            Self::InvalidMagic => write!(f, "Invalid Q42J magic bytes"),
862            Self::UnsupportedVersion(v) => write!(f, "Unsupported Q42J version {}", v),
863            Self::UnknownApplicationProfile(p) => {
864                write!(f, "Unknown application profile 0x{:04X}", p)
865            }
866            Self::InvalidHeader(msg) => write!(f, "Invalid Q42J header: {}", msg),
867            Self::BaseDigestMismatch => write!(f, "Base .q42 digest does not match journal header"),
868            Self::UnknownFrameType(t) => write!(f, "Unknown journal frame type 0x{:02X}", t),
869            Self::CorruptedFrame(seq) => write!(f, "Corrupted frame at sequence {}", seq),
870            Self::InvalidQuin(msg) => write!(f, "Invalid NQuin in journal: {}", msg),
871            Self::InvalidQuinParity => write!(f, "NQuin parity fold verification failed"),
872        }
873    }
874}
875
876impl std::error::Error for JournalError {}
877
878#[cfg(test)]
879mod tests {
880    use super::*;
881    use std::io::Cursor;
882
883    fn sample_quin(s: u64, p: u64, o: u64, c: u64, m: u64) -> NQuin {
884        let parity = s ^ p ^ o ^ c ^ m;
885        NQuin {
886            subject: s,
887            predicate: p,
888            object: o,
889            context: c,
890            metadata: m,
891            parity,
892        }
893    }
894
895    #[test]
896    fn test_q42j_header_roundtrip() {
897        let digest = [0x42u8; 32];
898        let h = JournalHeader::new(
899            JournalApplicationProfile::PoetWorkspace,
900            0x1234_5678,
901            digest,
902            7,
903        );
904        let bytes = h.to_bytes();
905        let parsed = JournalHeader::from_bytes(&bytes).unwrap();
906        assert_eq!(h, parsed);
907        assert_eq!(
908            parsed.profile,
909            JournalApplicationProfile::PoetWorkspace as u16
910        );
911        assert_eq!(parsed.privacy, JournalPrivacyClass::Sanctuary as u8);
912    }
913
914    #[test]
915    fn test_q42j_single_transaction_commit_and_recover() {
916        let digest = [0x55u8; 32];
917        let h = JournalHeader::new(
918            JournalApplicationProfile::SimulationWorld,
919            0x9999,
920            digest,
921            1,
922        );
923        let storage = Cursor::new(Vec::new());
924        let mut journal = Q42Journal::create(storage, h).unwrap();
925
926        let q1 = sample_quin(100, 200, 300, 400, 500);
927        let q2 = sample_quin(101, 201, 301, 401, 501);
928
929        let mut tx = JournalTransaction::new(1, 10, 0xABCD, 0x1111);
930        tx.add_quin(q1);
931        tx.add_quin(q2);
932        journal.append_transaction(&tx).unwrap();
933
934        let recovered = journal.recover_transactions().unwrap();
935        assert_eq!(recovered.len(), 1);
936        assert_eq!(recovered[0].tx_id, 1);
937        assert_eq!(recovered[0].tick, 10);
938        assert_eq!(recovered[0].command_hash, 0xABCD);
939        assert_eq!(recovered[0].actor_did, 0x1111);
940        assert_eq!(recovered[0].adds, vec![q1, q2]);
941        assert!(recovered[0].committed);
942    }
943
944    #[test]
945    fn test_q42j_torn_transaction_tail_discard() {
946        let digest = [0x55u8; 32];
947        let h = JournalHeader::new(
948            JournalApplicationProfile::SimulationWorld,
949            0x9999,
950            digest,
951            1,
952        );
953        let storage = Cursor::new(Vec::new());
954        let mut journal = Q42Journal::create(storage, h).unwrap();
955
956        let q1 = sample_quin(100, 200, 300, 400, 500);
957        let mut tx1 = JournalTransaction::new(1, 10, 0x111, 0xAA);
958        tx1.add_quin(q1);
959        journal.append_transaction(&tx1).unwrap();
960
961        // Write half of tx2 without commit
962        journal.storage.seek(SeekFrom::End(0)).unwrap();
963        let frame_header = FrameHeader {
964            frame_type: JournalFrameType::TxBegin as u8,
965            reserved: [0; 3],
966            payload_len: 16,
967            sequence_num: 10,
968            tick: 11,
969            tx_id: 2,
970            crc32c: crc32c(&[0u8; 16]),
971        };
972        journal.storage.write_all(&frame_header.to_bytes()).unwrap();
973        journal.storage.write_all(&[0u8; 16]).unwrap();
974
975        // Replay should cleanly recover tx1 and ignore uncommitted tx2
976        let recovered = journal.recover_transactions().unwrap();
977        assert_eq!(recovered.len(), 1);
978        assert_eq!(recovered[0].tx_id, 1);
979    }
980
981    #[test]
982    fn test_q42j_corrupted_frame_fails_closed() {
983        let digest = [0x55u8; 32];
984        let h = JournalHeader::new(
985            JournalApplicationProfile::GenericSemantic,
986            0x9999,
987            digest,
988            1,
989        );
990        let storage = Cursor::new(Vec::new());
991        let mut journal = Q42Journal::create(storage, h).unwrap();
992
993        let q1 = sample_quin(100, 200, 300, 400, 500);
994        let mut tx = JournalTransaction::new(1, 10, 0x111, 0xAA);
995        tx.add_quin(q1);
996        journal.append_transaction(&tx).unwrap();
997
998        // Tamper with a payload byte in storage
999        let buf = journal.storage.get_mut();
1000        let last_idx = buf.len() - 2;
1001        buf[last_idx] ^= 0xFF;
1002
1003        assert!(matches!(
1004            journal.recover_transactions(),
1005            Err(JournalError::CorruptedFrame(_))
1006        ));
1007    }
1008
1009    #[test]
1010    fn test_q42j_base_digest_mismatch() {
1011        let digest = [0x55u8; 32];
1012        let h = JournalHeader::new(
1013            JournalApplicationProfile::GenericSemantic,
1014            0x9999,
1015            digest,
1016            1,
1017        );
1018        let mut storage = Cursor::new(Vec::new());
1019        Q42Journal::create(&mut storage, h).unwrap();
1020
1021        let wrong_digest = [0x77u8; 32];
1022        assert!(matches!(
1023            Q42Journal::open(storage, &wrong_digest),
1024            Err(JournalError::BaseDigestMismatch)
1025        ));
1026    }
1027
1028    #[test]
1029    fn test_mutable_q42_session_flow() {
1030        let digest = [0x12u8; 32];
1031        let h = JournalHeader::new(JournalApplicationProfile::PoetWorkspace, 0x42, digest, 1);
1032        let storage = Cursor::new(Vec::new());
1033        let journal = Q42Journal::create(storage, h).unwrap();
1034
1035        let base_quin = sample_quin(1, 2, 3, 4, 5);
1036        let mut session = MutableQ42Session::open(journal, &[base_quin]).unwrap();
1037
1038        assert_eq!(session.active_state.len(), 1);
1039
1040        let added_quin = sample_quin(10, 20, 30, 40, 50);
1041        session.stage_add(added_quin);
1042        session.stage_remove(base_quin);
1043        let tx_id = session.commit_transaction(0xFA, 0x88).unwrap();
1044        assert_eq!(tx_id, 1);
1045
1046        assert_eq!(session.active_state.len(), 1);
1047        assert!(session.active_state.contains(&added_quin));
1048        assert!(!session.active_state.contains(&base_quin));
1049    }
1050
1051    #[test]
1052    fn test_q42j_topology_delta_and_seal_framing_roundtrip() {
1053        assert_eq!(
1054            JournalFrameType::from_u8(0x06),
1055            Some(JournalFrameType::TopologyDelta)
1056        );
1057        assert_eq!(
1058            JournalFrameType::from_u8(0x07),
1059            Some(JournalFrameType::TopologySeal)
1060        );
1061        assert_eq!(
1062            JournalFrameType::try_from(0x06).unwrap(),
1063            JournalFrameType::TopologyDelta
1064        );
1065        assert_eq!(
1066            JournalFrameType::try_from(0x07).unwrap(),
1067            JournalFrameType::TopologySeal
1068        );
1069
1070        let digest = [0x33u8; 32];
1071        let h = JournalHeader::new(JournalApplicationProfile::PoetWorkspace, 0x77, digest, 1);
1072        let storage = Cursor::new(Vec::new());
1073        let mut journal = Q42Journal::create(storage, h).unwrap();
1074
1075        let delta_payload = [0x01u8; 16];
1076        journal
1077            .append_topology_delta(1, 5, &delta_payload)
1078            .unwrap();
1079        journal
1080            .append_topology_seal(1, 6, 0xCAFE_BABE_1234_5678, 0xE306_9283, 4)
1081            .unwrap();
1082
1083        let q1 = sample_quin(1, 2, 3, 4, 5);
1084        let mut tx = JournalTransaction::new(2, 7, 0x99, 0x44);
1085        tx.add_quin(q1);
1086        journal.append_transaction(&tx).unwrap();
1087
1088        let recovered = journal.recover_transactions().unwrap();
1089        assert_eq!(recovered.len(), 1);
1090        assert_eq!(recovered[0].tx_id, 2);
1091    }
1092}