amaters_core/
lib.rs

1//! # AmateRS Core - Fully Homomorphic Encrypted Database Engine
2//!
3//! **amaters-core** is the kernel of the AmateRS distributed database,
4//! providing Encryption-in-Use capabilities via TFHE (Fully Homomorphic Encryption).
5//!
6//! ## Core Principles
7//!
8//! - **Encryption in Use**: All data remains encrypted during computation
9//! - **Zero Trust**: Servers never see plaintext data
10//! - **Deterministic**: Reproducible results with cryptographic proofs
11//! - **High Performance**: GPU-accelerated FHE operations
12//!
13//! ## Architecture
14//!
15//! AmateRS consists of four core components inspired by Japanese mythology:
16//!
17//! | Component | Origin | Role |
18//! |-----------|--------|------|
19//! | **Iwato** (岩戸) | Heavenly Rock Cave | Storage Engine |
20//! | **Yata** (八咫鏡) | Eight-Span Mirror | Compute Engine |
21//! | **Ukehi** (宇気比) | Sacred Pledge | Consensus Layer |
22//! | **Musubi** (結び) | The Knot | Network Layer |
23//!
24//! ## Modules
25//!
26//! - [`error`] - Comprehensive error types and recovery strategies
27//! - [`types`] - Core types (CipherBlob, Key, Query)
28//! - [`traits`] - Storage engine trait definitions
29//! - [`storage`] - Iwato storage engine (LSM-Tree with WiscKey)
30//! - [`compute`] - Yata FHE execution engine
31//! - [`validation`] - Input validation helpers
32//!
33//! ## Quick Start
34//!
35//! ```rust,ignore
36//! use amaters_core::{
37//!     storage::MemoryStorage,
38//!     traits::StorageEngine,
39//!     types::{CipherBlob, Key},
40//! };
41//!
42//! #[tokio::main]
43//! async fn main() -> anyhow::Result<()> {
44//!     let storage = MemoryStorage::new();
45//!
46//!     let key = Key::from_str("secret_data");
47//!     let encrypted = CipherBlob::new(vec![/* encrypted bytes */]);
48//!
49//!     storage.put(&key, &encrypted).await?;
50//!     let retrieved = storage.get(&key).await?;
51//!
52//!     Ok(())
53//! }
54//! ```
55//!
56//! ## Feature Flags
57//!
58//! - `storage` - Enable storage engine (Iwato)
59//! - `compute` - Enable FHE compute engine (Yata)
60//! - `parallel` - Enable parallel operations with Rayon
61//! - `mmap` - Enable memory-mapped storage
62//! - `gpu` - Enable GPU acceleration
63//! - `cuda` - Enable CUDA backend (requires `gpu`)
64//! - `metal` - Enable Metal backend (requires `gpu`)
65//!
66//! ## Security Model
67//!
68//! See the [technical whitepaper](../AmateRS--Tech-EN.md) for details on:
69//! - Threat model and countermeasures
70//! - Post-quantum security guarantees
71//! - Key management best practices
72//!
73//! ## Development Status
74//!
75//! **Phase 1 (MVP):** Basic storage and compute stubs ✅
76//! **Phase 2:** Full LSM-Tree and FHE integration 🚧
77//! **Phase 3:** Distributed consensus and GPU acceleration 📋
78
79#![recursion_limit = "512"]
80#![allow(dead_code)]
81#![allow(clippy::type_complexity)]
82#![allow(clippy::too_many_arguments)]
83
84pub mod compute;
85pub mod error;
86pub mod storage;
87pub mod traits;
88pub mod types;
89pub mod utils;
90pub mod validation;
91
92// Re-exports for convenience
93pub use error::{AmateRSError, ErrorContext, Result};
94pub use traits::StorageEngine;
95pub use types::{CipherBlob, ColumnRef, Key, Predicate, Query, QueryBuilder, Update, col};
96
97/// Library version
98pub const VERSION: &str = env!("CARGO_PKG_VERSION");
99
100/// Library name
101pub const NAME: &str = env!("CARGO_PKG_NAME");
102
103#[cfg(test)]
104mod tests {
105    use super::*;
106
107    #[test]
108    fn test_version() {
109        // VERSION is a compile-time constant from CARGO_PKG_VERSION
110        // It should be in semver format (e.g., "0.1.0")
111        assert!(VERSION.contains('.'), "VERSION should be semver format");
112        assert_eq!(NAME, "amaters-core");
113    }
114}
amaters_core/lib.rs

amaters_core/
lib.rs
