1use crate::NQuin;
17use std::collections::HashSet;
18use std::io::{self, Read, Seek, SeekFrom, Write};
19
20pub const Q42J_MAGIC: [u8; 4] = *b"Q42J";
22
23pub const Q42J_VERSION: u16 = 1;
25
26pub const Q42J_HEADER_SIZE: usize = 128;
28
29#[repr(u16)]
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum JournalApplicationProfile {
33 GenericSemantic = 0x0001,
35 PoetWorkspace = 0x0002,
37 SimulationWorld = 0x0003,
39 ClinicalRecord = 0x0004,
41 CivicCommons = 0x0005,
43}
44
45impl Default for JournalApplicationProfile {
46 fn default() -> Self {
48 Self::GenericSemantic
49 }
50}
51
52impl TryFrom<u16> for JournalApplicationProfile {
53 type Error = JournalError;
54 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#[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 fn default() -> Self {
80 Self::Sanctuary
81 }
82}
83
84#[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 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 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 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#[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 #[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 fn try_from(val: u8) -> Result<Self, Self::Error> {
236 Self::from_u8(val).ok_or(JournalError::UnknownFrameType(val))
237 }
238}
239
240#[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 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 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
296pub 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#[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 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 pub fn add_quin(&mut self, quin: NQuin) {
342 self.adds.push(quin);
343 }
344
345 pub fn remove_quin(&mut self, quin: NQuin) {
347 self.removes.push(quin);
348 }
349
350 pub fn bind_lexicon(&mut self, token_hash: u64, iri: String) {
352 self.lexicon_bindings.push((token_hash, iri));
353 }
354}
355
356pub 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 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 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 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 pub fn append_transaction(&mut self, tx: &JournalTransaction) -> Result<(), JournalError> {
410 self.storage.seek(SeekFrom::End(0))?;
411
412 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 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 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 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 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 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 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 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 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 }
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 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 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 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
648pub 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 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 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 pub fn current_tick(&self) -> u64 {
702 self.current_tick
703 }
704
705 pub fn advance_tick(&mut self, tick: u64) {
708 if tick > self.current_tick {
709 self.current_tick = tick;
710 }
711 }
712
713 pub fn stage_add(&mut self, quin: NQuin) {
715 self.staged_adds.push(quin);
716 }
717
718 pub fn stage_remove(&mut self, quin: NQuin) {
720 self.staged_removes.push(quin);
721 }
722
723 pub fn rollback_staged(&mut self) {
725 self.staged_adds.clear();
726 self.staged_removes.clear();
727 }
728
729 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 self.journal.append_transaction(&tx)?;
745
746 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 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 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
795pub 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
807pub 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 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 fn from(e: io::Error) -> Self {
852 Self::Io(e)
853 }
854}
855
856impl std::fmt::Display for JournalError {
857 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 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 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 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}