lcpfs 2026.1.101

<div align="center">

# 🌙 LCPFS


### **LCP File System**


*A Copy-on-Write Filesystem in Pure Rust*

[![Crates.io](https://img.shields.io/crates/v/lcpfs.svg)](https://crates.io/crates/lcpfs)
[![Documentation](https://docs.rs/lcpfs/badge.svg)](https://docs.rs/lcpfs)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![no_std](https://img.shields.io/badge/no__std-compatible-green.svg)]()

</div>

---

## 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

```toml
[dependencies]
lcpfs = "2026.1"
```

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

---

## Table of Contents


1. [Metrics](#-metrics)
2. [Performance](#-performance)
3. [Features](#-features)
4. [Quick Start](#-quick-start)
5. [Architecture](#-architecture)
6. [Comparison](#-comparison)
7. [Testing](#-testing)
8. [The Coherence Paradigm](#-the-coherence-paradigm)
9. [License & Acknowledgments](#-license)

---

## 📊 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" \| wc -l` |
| Modules | 41 | `ls -d src/*/ \| wc -l` |
| Test functions | 1,841 | `grep -r "#\[test\]" src \| wc -l` |
| unsafe blocks | 123 | `grep -r "unsafe {" src/ \| wc -l` |
| Language | 100% Rust | GitHub linguist |
| License | Apache 2.0 | [LICENSE](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:

```bash
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)


<details>
<summary>Full feature list with modules</summary>

| # | 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 |

</details>

---

## 🚀 Quick Start


**Install:**

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

**Use:**

```rust
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


```bash
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](https://github.com/artst3in/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)](https://www.researchgate.net/publication/397504998_The_Coherence_Paradigm_The_Universal_Law_of_Existence_and_The_Axiom_of_Engineering_Necessity)

---

## 📜 License


Apache License, Version 2.0 — See [LICENSE](LICENSE)

---

## 🙏 Acknowledgments


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

### Filesystems & Storage


| Project | Contribution |
|---------|--------------|
| **[OpenZFS](https://openzfs.org/)** | Copy-on-write architecture, ARC, RAID-Z, send/receive, the entire conceptual foundation |
| **[Redox OS](https://redox-os.org/)** | Proving Rust can build a full operating system; `no_std` filesystem patterns |
| **[Btrfs](https://btrfs.readthedocs.io/)** | Subvolume concepts, reflink implementation ideas |

### Verification & Security


| Project | Contribution |
|---------|--------------|
| **[seL4](https://sel4.systems/)** | Pioneering mathematical verification of system software; proving correctness is achievable |
| **[VeraCrypt](https://veracrypt.fr/)** | Hidden volume / deniable encryption concepts (LunaVault design) |

### Cryptography


| Project | Contribution |
|---------|--------------|
| **[RustCrypto](https://github.com/RustCrypto)** | ChaCha20-Poly1305, AES-GCM, BLAKE3, SHA-2, HMAC, PBKDF2 |
| **[CRYSTALS-Kyber](https://pq-crystals.org/kyber/)** | Post-quantum key encapsulation (NIST PQC winner) |
| **[CRYSTALS-Dilithium](https://pq-crystals.org/dilithium/)** | Post-quantum signatures |
| **[x25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek)** | Elliptic curve key exchange |

### Compression


| Project | Contribution |
|---------|--------------|
| **[LZ4](https://lz4.org/)** | Algorithm design (Yann Collet) |
| **[Zstandard](https://facebook.github.io/zstd/)** | Algorithm design (Yann Collet) |
| **[7-Zip / LZMA](https://7-zip.org/)** | LZMA/LZMA2 algorithms (Igor Pavlov) |
| **[lz4_flex](https://github.com/PSeitz/lz4_flex)** | Pure Rust LZ4 we built upon |

### The Rust Ecosystem


| Project | Contribution |
|---------|--------------|
| **[Rust](https://rust-lang.org/)** | The language that makes memory-safe systems programming possible |
| **[The Rust Foundation](https://foundation.rust-lang.org/)** | Stewardship of the ecosystem |
| **[spin](https://github.com/mvdnes/spin-rs)** | no_std Mutex implementation |
| **[lazy_static](https://github.com/rust-lang-nursery/lazy-static.rs)** | 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](https://github.com/artst3in/lcpfs/issues). Attribution matters.

---

## 📚 Resources


| Resource | Link |
|----------|------|
| API Documentation | [docs.rs/lcpfs](https://docs.rs/lcpfs) |
| Examples | [examples/](examples/) |
| Issues | [GitHub Issues](https://github.com/artst3in/lcpfs/issues) |
| The Coherence Paradigm | [Paper (PDF)](https://www.researchgate.net/publication/397504998_The_Coherence_Paradigm_The_Universal_Law_of_Existence_and_The_Axiom_of_Engineering_Necessity) |

---

<div align="center">

**Part of the LunaOS Ecosystem**

🌙

**dε/dt ≤ 0**

</div>