[dependencies]
lcpfs = "2026.1"

🌙 LCPFS

LCP File System

A Copy-on-Write Filesystem in Pure Rust

---

Abstract

LCPFS is a copy-on-write filesystem written entirely in Rust. It brings ZFS-equivalent capabilities — snapshots, clones, RAID-Z, compression, encryption, checksumming — to any platform, from embedded systems to enterprise servers.

Why LCPFS?

• Memory-safe: Rust eliminates entire classes of bugs (buffer overflows, use-after-free, data races)
• Portable: no_std compatible — runs on bare metal, custom kernels, or standard operating systems
• Complete: 41 modules, 92K lines, 1,841 tests — not a proof-of-concept
• Modern cryptography: Post-quantum (Kyber-1024), ChaCha20-Poly1305, AES-256-GCM

[dependencies]
lcpfs = "2026.1"

No kernel patches. No external dependencies. Just add the crate.

---

Table of Contents

1. Metrics
2. Performance
3. Features
4. Quick Start
5. Architecture
6. Comparison
7. Testing
8. The Coherence Paradigm
9. License & Acknowledgments

---

📊 Metrics

All metrics are reproducible. Commands provided.

Metric	Value	Verification
Source lines (production)	~92,000	tokei src/ (Code column)
Source files	229	`find src -name “*.rs”
Modules	41	`ls -d src/*/
Test functions	1,841	`grep -r “#[test]” src
unsafe blocks	123	`grep -r “unsafe {” src/
Language	100% Rust	GitHub linguist
License	Apache 2.0	LICENSE
Architectures	x86_64, AArch64	src/arch/

---

⚡ Performance

Measured on: Intel i7-13650HX, DDR5-4800, Windows 11 Build: --release with LTO

Category	Operation	Throughput
Checksum	BLAKE3	2,303 MB/s
	SHA-256	2,339 MB/s
	Verify (compute + compare)	2,119 MB/s
Compression	LZ4 compress	3,881 MB/s
	LZ4 decompress	5,023 MB/s
Encryption	ChaCha20-Poly1305	1,167 MB/s
	PBKDF2 (1000 rounds)	13,037 ops/s
Cache	ARC lookup	159M ops/s
	ARC insert	3,944 MB/s
RAID-Z	Parity calculation	29,192 MB/s
I/O	Sequential write	24,885 MB/s
	Sequential read	24,872 MB/s
	Random 4K	7.1M IOPS
Dedup	DDT lookup	599K ops/s

Run the full benchmark suite:

cargo test --release lcpfs_benchmark_report -- --nocapture

These benchmarks use in-memory buffers. Actual throughput depends on storage backend, data entropy, and system load.

---

🔧 Features

Core (Tested)

Category	Capabilities	Module
POSIX	Files, directories, symlinks, hardlinks, permissions, ACLs, xattrs	fscore/
Copy-on-Write	Snapshots (O(1)), clones, reflinks	storage/
RAID	RAID-Z1/Z2/Z3, dRAID, mirrors, self-healing	raid/ (100 tests)
Integrity	BLAKE3 checksums on every block, scrubbing	integrity/
Compression	LZ4 (no_std), ZSTD, LZMA (std feature)	compress/
Encryption	ChaCha20-Poly1305, AES-256-GCM (AES-NI)	crypto/ (82 tests)
Post-Quantum	Kyber-1024 lattice key encapsulation	crypto/kyber.rs
Caching	ARC (Adaptive Replacement Cache), L2ARC	cache/
Deduplication	Block-level, DDT hash table	dedup/
Replication	Send/receive snapshot streams	delta/ (62 tests)

Extended (31 Total)

Full feature list with modules

#	Feature	Module	Tests
1	Vector/Semantic Search	vector/	67
2	Time-Travel Queries	timetravel/	117
3	Git-Style Branching	branch/	99
4	Native S3 Gateway	s3/	78
5	WASM Storage Plugins	wasm/	43
6	Distributed Cluster Mode	distributed/	87
7	Content-Aware Compression	ml/content_aware.rs	41
8	Full-Text Search	fts/	13
9	Filesystem Events (inotify-like)	notify/	38
10	Native NFS Server	nfs/	98
11	Thin Provisioning	thin/	66
12	Online Defragmentation	defrag/	6
13	Key Rotation	crypto/key_rotation.rs	17
14	Multi-File Transactions	txn/	70
15	User/Group Quotas	quota/	37
16	Data Lineage Tracking	lineage/	27
17	Delta Sync (rsync-like)	delta/	62
18	Compression Dictionaries	dictcomp/	48
19	Erasure Coding	raid/erasure.rs	—
20	Secure Erase (DoD/Gutmann)	mgmt/secure_erase.rs	—
21	LunaVault Encrypted Containers	vault/	44
22	LunAr Native Archive Support	archive/	17
23	Trash / Recycle Bin	trash/	11
24	Automatic Versioning	mgmt/versioning.rs	—
25	Storage Analytics	analytics/	7
26	Sparse Files	sparse/	9
27	Alternate Data Streams	streams/	10
28	Telemetry (Prometheus/Grafana)	telemetry/	17
29	Hardware Acceleration	hw/	107
30	Cloud Storage Backends	cloud/	31
31	ML Prefetching	ml/	78

---

🚀 Quick Start

Install:

[dependencies]
lcpfs = "2026.1"                           # no_std (universal)
lcpfs = { version = "2026.1", features = ["std"] }  # with ZSTD/LZMA

Use:

use lcpfs::{Pool, register_device};

// Register your block device
let dev_id = register_device(Box::new(MyBlockDevice::new()));

// Create pool
let mut pool = Pool::create_pool(dev_id, "tank")?;

// Create file
let fd = pool.create("/data.txt", 0o644)?;
pool.write(fd, b"Hello, LCPFS!")?;
pool.close(fd)?;

// Snapshot (instant, O(1))
pool.snapshot("backup-001")?;

// Clone (instant, zero-copy)
pool.clone("backup-001", "experiment")?;

---

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│  ZPL (POSIX Layer)                              │
│  Files · Directories · Permissions · xattrs     │
├─────────────────────────────────────────────────┤
│  DMU (Data Management Unit)                     │
│  Objects · Transactions · Block Allocation      │
├─────────────────────────────────────────────────┤
│  ARC (Adaptive Replacement Cache)               │
│  Recency (T1) · Frequency (T2) · Ghost Lists    │
├─────────────────────────────────────────────────┤
│  ZIO Pipeline                                   │
│  Compress → Dedup → Encrypt → Checksum          │
├─────────────────────────────────────────────────┤
│  VDEV (Virtual Devices)                         │
│  RAID-Z · Mirrors · dRAID · Self-Healing        │
├─────────────────────────────────────────────────┤
│  BlockDevice Trait                              │
│  NVMe · SATA · virtio-blk · Custom              │
└─────────────────────────────────────────────────┘

---

📐 Comparison

Property	LCPFS	OpenZFS	Btrfs
Language	Rust	C	C
Lines of code	~92K	~500K¹	~350K²
Memory safety	Compiler-enforced	Manual	Manual
no_std support	✅	❌	❌
Copy-on-write	✅	✅	✅
Snapshots	✅	✅	✅
RAID-Z	✅	✅	❌
Send/Receive	✅	✅	✅
Post-quantum crypto	✅	❌	❌
GPU compression	✅	❌	❌

¹ Verify: git clone https://github.com/openzfs/zfs && cloc zfs/ ² Verify: cloc linux/fs/btrfs/ on kernel source

---

🧪 Testing

cargo test                    # Core tests (no_std compatible)
cargo test --features std     # With ZSTD/LZMA compression
cargo test --all-features     # Full test suite

Category	Module(s)	Tests
Time-Travel	timetravel/	117
Hardware Accel	hw/	107
RAID/Erasure	raid/	100
Branching	branch/	99
NFS Server	nfs/	98
Distributed	distributed/	87
Crypto/Encryption	crypto/	82
ML/Prefetch	ml/	78
S3 Gateway	s3/	78
Transactions	txn/	70
Vector Search	vector/	67
Thin Provision	thin/	66
Delta Sync	delta/	62
Networking	net/	50
Dict Compress	dictcomp/	48
Vault	vault/	44
WASM	wasm/	43
Other	remaining	325
Total	all	1,841

---

🌙 The Coherence Paradigm

LCPFS is the storage layer for LunaOS — an operating system built on a new theoretical foundation called the First Law of Computational Physics (LCP).

You don’t need to understand LCP to use LCPFS. But if you’re curious:

The Core Idea

The LCP states that any persistent system must continuously reduce its internal disorder:

dε/dt ≤ 0

Where ε (epsilon) is "Conceptual Error" — the gap between what a system believes and what’s actually true. Corruption, inconsistency, data loss — these are all forms of ε.

How This Applies to Filesystems

Problem	ε Increase	LCPFS Solution
Bit rot corrupts data	ε ↑	BLAKE3 checksums detect it
Disk fails	ε → ∞	RAID-Z has redundant copies
Power loss mid-write	ε ↑	Copy-on-write: old data intact until commit
Wasted space	ε ↑ (inefficiency)	Compression reduces entropy

LunaOS Integration

When running under LunaOS, additional capabilities are unlocked:

Feature	Description
Autonomous Scrubbing	Kernel monitors ε, triggers checks automatically
Predictive Evacuation	Kernel detects drive failure patterns
Thermal Tiering	Kernel optimizes hot/cold data placement
Adaptive Compression	Kernel selects algorithm per-block

On other operating systems (Linux, Windows, etc.), LCPFS provides all core features but requires manual administration. LunaOS automates these decisions.

"There are no coincidences. There is only convergence." — The Architect

For the full theory: The Coherence Paradigm (PDF)

---

📜 License

Apache License, Version 2.0 — See LICENSE

---

🙏 Acknowledgments

LCPFS stands on the shoulders of giants. We are deeply grateful to:

Filesystems & Storage

Project	Contribution
OpenZFS	Copy-on-write architecture, ARC, RAID-Z, send/receive, the entire conceptual foundation
Redox OS	Proving Rust can build a full operating system; no_std filesystem patterns
Btrfs	Subvolume concepts, reflink implementation ideas

Verification & Security

Project	Contribution
seL4	Pioneering mathematical verification of system software; proving correctness is achievable
VeraCrypt	Hidden volume / deniable encryption concepts (LunaVault design)

Cryptography

Project	Contribution
RustCrypto	ChaCha20-Poly1305, AES-GCM, BLAKE3, SHA-2, HMAC, PBKDF2
CRYSTALS-Kyber	Post-quantum key encapsulation (NIST PQC winner)
CRYSTALS-Dilithium	Post-quantum signatures
x25519-dalek	Elliptic curve key exchange

Compression

Project	Contribution
LZ4	Algorithm design (Yann Collet)
Zstandard	Algorithm design (Yann Collet)
7-Zip / LZMA	LZMA/LZMA2 algorithms (Igor Pavlov)
lz4_flex	Pure Rust LZ4 we built upon

The Rust Ecosystem

Project	Contribution
Rust	The language that makes memory-safe systems programming possible
The Rust Foundation	Stewardship of the ecosystem
spin	no_std Mutex implementation
lazy_static	Static initialization patterns

Research & Theory

Work	Contribution
Landauer’s Principle (Rolf Landauer, 1961)	Thermodynamic foundation of computational cost
Dissipative Structures (Ilya Prigogine)	Non-equilibrium thermodynamics of ordered systems
Free Energy Principle (Karl Friston)	Predictive processing framework
Negentropy (Erwin Schrödinger, 1944)	"What is Life?" — the original insight

---

If we’ve used your work and failed to credit you, please open an issue. Attribution matters.

---

📚 Resources

Resource	Link
API Documentation	docs.rs/lcpfs
Examples	examples/
Issues	GitHub Issues
The Coherence Paradigm	Paper (PDF)

---

Part of the LunaOS Ecosystem

🌙

dε/dt ≤ 0