nexcore_crystalbook/lib.rs
1//! # The Crystalbook
2//!
3//! Immutable, content-addressed scientific documents with Merkle integrity
4//! and cryptographic seal chains.
5//!
6//! ## What This Is
7//!
8//! The Crystalbook is NexVigilant's founding document — Eight Laws of System
9//! Homeostasis by Matthew A. Campion, PharmD. This crate provides the
10//! document model, content-addressing, integrity verification, cryptographic
11//! sealing, and diagnostic assessment that make the Crystalbook scientifically
12//! immutable and transparently verifiable.
13//!
14//! ## Architecture
15//!
16//! ```text
17//! .crystalbook file (JSON)
18//! │
19//! ▼
20//! CrystalbookDocument
21//! ├── cells: Vec<Cell> ← content-addressed (SHA-256)
22//! ├── merkle_root: String ← Merkle tree root over cell hashes
23//! ├── seals: SealChain ← hash-linked immutability chain
24//! └── metadata: DocumentMetadata ← author, version, theme
25//! ```
26//!
27//! Every cell's source is hashed. The hashes form a Merkle tree. The root
28//! hash seals the entire document. Seals form a hash-linked chain — each
29//! references the previous, making the history tamper-evident.
30//!
31//! ## Modules
32//!
33//! | Module | Purpose |
34//! |--------|---------|
35//! | [`cell`] | The atom — content-addressed cells with typed content |
36//! | [`merkle`] | The lattice — balanced binary Merkle tree with proofs |
37//! | [`seal`] | The chain — cryptographic immutability via hash-linked seals |
38//! | [`document`] | The container — ties cells + Merkle + seals together |
39//! | [`diagnostic`] | The instrument — 8 Laws system health assessment |
40//! | [`theme`] | The identity — crystal dark visual constants |
41//!
42//! ## Quick Start
43//!
44//! ```rust
45//! use nexcore_crystalbook::document::crystalbook_v2;
46//! use nexcore_crystalbook::merkle::MerkleTree;
47//!
48//! // Build the canonical Crystalbook
49//! let mut doc = crystalbook_v2();
50//! assert_eq!(doc.cell_count(), 11);
51//! assert!(doc.verify_integrity());
52//! assert!(doc.validate().is_valid());
53//!
54//! // Seal it
55//! let seal_id = doc.seal("Matthew A. Campion, PharmD");
56//! assert!(doc.is_sealed());
57//!
58//! // Prove a cell's membership
59//! let tree = doc.merkle_tree();
60//! let proof = tree.proof_for_cell(1).unwrap(); // Law I
61//! assert!(MerkleTree::verify_proof(&tree.root(), &proof));
62//! ```
63
64#![forbid(unsafe_code)]
65#![warn(missing_docs)]
66#![cfg_attr(
67 not(test),
68 deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)
69)]
70
71pub mod cell;
72pub mod diagnostic;
73pub mod document;
74pub mod execute;
75pub mod io;
76pub mod merkle;
77pub mod render;
78pub mod seal;
79pub mod theme;