StrataFS: High-Performance, Memory-Safe Linux VFS Storage Subsystem

StrataFS is a next-generation Linux kernel Virtual Filesystem (VFS) storage engine engineered in #![no_std] Rust and native C-FFI trampolines. Designed from first principles to eliminate memory corruption vulnerabilities, dynamic allocation deadlocks, and hierarchical directory bottlenecking, StrataFS delivers deterministic multi-million IOPS throughput for enterprise database systems, containerized cloud infrastructure, and modern NVMe hardware.

---

1. System Architecture

graph TD
    subgraph EnterpriseWorkloads["Workloads & Interfaces"]
        DB["Databases (PostgreSQL, RocksDB, ScyllaDB) with O_DIRECT"]
        K8s["Containers (Docker, Kubernetes) with SELinux & OCI"]
        POSIX["POSIX Applications (Buffered I/O, getdents64)"]
    end

    subgraph LinuxKernel["Linux Kernel VFS & Subsystems"]
        VFS["Linux VFS Triad (inode_ops / file_ops / address_space_ops)"]
        IOMAP["Linux iomap Framework (Direct I/O DMA Bypass)"]
        Shrinker["Linux Shrinker API (Non-Blocking kswapd Cache Eviction)"]
        RCU["RCU-Walk Path Traversal (LOOKUP_RCU)"]
    end

    subgraph FFIQuarantine["StrataFS FFI Airlock (Panic & ABI Isolation)"]
        Airlock["ffi_airlock & ffi_ptr_airlock (Catch Unwind Boundaries)"]
    end

    subgraph StrataFSCore["StrataFS Domain Core (no_std Rust, forbid(unsafe_code))"]
        Dispatcher["EngineDispatcher (Static Monomorphized Matching, 0 Vtables)"]
        LSM["LSM Adapter (MemTable + SIMD Bloom Filter + Adaptive Governor)"]
        BTree["B-Tree Adapter (Copy-on-Write Pages + Extent Coalescing)"]
        Alloc["Extent Allocator (Dual-Indexed Free Space B-Tree)"]
        Pool["AtomicReclaimPool (Lock-Free Tagged Memory Eviction)"]
    end

    subgraph HardwareStorage["Physical Hardware & Crash Consistency"]
        WAL["Epoch Group Commit WAL (Batches up to 64 TXs per REQ_FUA BIO)"]
        Superblock["Dual Ping-Pong Superblock (Multi-Sector 4KB Torn-Write Detection)"]
    end

    DB --> IOMAP
    POSIX --> VFS
    K8s --> VFS
    
    IOMAP --> Airlock
    VFS --> Airlock
    Shrinker --> Airlock
    RCU --> Airlock

    Airlock --> Dispatcher

    Dispatcher --> LSM
    Dispatcher --> BTree
    Dispatcher --> Alloc
    Dispatcher --> Pool

    LSM --> WAL
    BTree --> WAL
    Alloc --> Superblock

Loading

---

2. Core Architectural Breakthroughs

A. Zero-Cost Hexagonal Static Dispatch

• Zero Vtable Overhead: Storage engines (engine_lsm and engine_btree) are routed via compile-time monomorphized enums (EngineDispatcher), enabling LLVM to inline methods directly on hot I/O paths without dynamic dispatch penalty.
• Strict #![no_std] & #![forbid(unsafe_code)]: The core domain logic is mathematically isolated from unsafe pointer operations, which are quarantined strictly within the C-FFI airlock.

B. Modern iomap Direct I/O Bypass

• True Zero-Copy DMA: Direct I/O (O_DIRECT) maps logical file offsets to physical sectors via stratafs_iomap_begin. The Linux block layer dispatches DMA transfers directly between user-space RAM and NVMe flash, bypassing the page cache and saving CPU cycles.

C. Stable POSIX Directory Streaming (TABLE_DIR_SEQ: 0x06)

• Deterministic readdir / getdents64: Directory entries maintain a secondary monotonic 64-bit integer index (DatabaseKey::DirSequence).
• Emits synthetic . and .. dirents followed by the sequential stream in stratafs_iterate_shared, guaranteeing zero skips or duplicate files during concurrent file creations.

D. NVMe WAL Epoch Group Commit Engine

• Hardware Queue Saturation: Replaces single-transaction synchronous flushes with batching in execute_wal_group_commit. Drains up to 64 transactions from the SPSC Ring Buffer into a single multi-sector REQ_PREFLUSH | REQ_FUA physical BIO barrier, restoring NVMe queue depths ($\text{QD} \ge 32$).

E. Lock-Free Clean Memory Reclaim Pool

• OOM Live-Lock Immunity: The Linux Shrinker interface drains pre-committed, clean metadata objects via atomic CAS pop in AtomicReclaimPool without taking foreground spinlocks, guaranteeing instantaneous memory return to kswapd during severe memory storms.

F. Multi-Sector Flash Torn-Write Detection

• 4KB SSD Guard: Superblocks feature matching generation (Sector 0) and footer_generation (Sector 7) counters finalized by CRC32c checksums in StrataSuperblock. Partial writes across multi-sector flash pages are detected and rejected on mount, rolling back cleanly to the alternate superblock.

---

3. The 6 Hexagonal Domain Ports

Port Trait	Responsibility	In-Tree Implementations
MetaStoragePort	Directory entries, POSIX inode attributes, and sequential directory iteration	LsmAdapter, BTreeAdapter
BlockMappingPort	Translation of logical file offsets to physical disk sectors	LsmAdapter, BTreeAdapter
TransactionPort	Atomic transaction token life-cycle and WAL commit synchronization	LsmAdapter, BTreeAdapter
FreeSpaceManagerPort	Best-fit extent allocation, deallocation, and mathematical range coalescing	ExtentAllocator
MemoryReclaimPort	Non-blocking cache eviction and clean metadata reclamation for Linux shrinker	LsmAdapter, BTreeAdapter
XattrStoragePort	Extended attributes (TABLE_XATTR) for SELinux contexts, POSIX ACLs, and OCI	LsmAdapter, BTreeAdapter

---

4. Directory Structure

stratafs/
├── Cargo.toml                  # Cargo Workspace Root Configuration
├── clippy.toml                 # Static analysis & forbidden pattern bans
├── Makefile                    # Kbuild & DKMS module compilation rules
├── Kbuild                      # Linux in-kernel build manifest
├── LICENSE                     # GNU General Public License v2.0
├── README.md                   # Master System Architecture & Quickstart Guide
├── CONTRIBUTING.md             # Development & Verification Guidelines
├── AGENTS.md                   # Architecture Governance & Escalation Directives
├── .github/workflows/          # Automated Governance CI pipeline
├── docs/                       # 15 Architectural Specifications & ADRs 001–016
├── src/                        # Rust Kernel Driver Source (#![no_std])
│   ├── lib.rs                  # Module init, exit, and ELF section hooks
│   ├── core/                   # Safe Domain Core (#![forbid(unsafe_code)])
│   │   ├── domain/             # Superblock, Inodes, Universal Namespace
│   │   ├── memory/             # MemTableArena & AtomicReclaimPool
│   │   ├── ports.rs            # Hexagonal trait definitions
│   │   └── dispatcher.rs       # Static inlined EngineDispatcher
│   ├── adapters/               # LSM, CoW B-Tree, Extent Allocator, Rate Governor
│   ├── domain/                 # Universal errors and kernel error mappings
│   ├── wal/                    # 512B CRC32c WAL & SPSC Ring Buffer & Group Commit
│   └── ffi/                    # Unsafe C-FFI Airlock, VFS Mappings, Wait Queues
├── userspace/                  # Standard Rust (std) Utilities
│   ├── mkfs/                   # /sbin/mkfs.stratafs disk formatter
│   ├── mount/                  # /sbin/mount.stratafs pre-flight validator
│   └── fsck/                   # /sbin/fsck.stratafs multi-pass repair engine
├── telemetry/                  # Zero-overhead eBPF probes & kernel tracepoints
├── benchmarks/                 # FIO profiles, compilebench, pgbench, & aggregator
├── packaging/                  # DKMS configuration, Debian rules, RPM spec
├── scripts/                    # Build, Bindgen, and QEMU test runners
└── tests/                      # Kani Model Checking proofs & property tests

---

5. Quickstart & Build Instructions

Prerequisites

• Rust Toolchain: nightly with rust-src and clippy components.
• Linux Kernel Headers: Kernel 6.1+ headers (linux-headers-$(uname -r)).
• System Utilities: clang, bindgen, make, gcc, fio, python3.

1. Build the Kernel Module

# Compile kernel module (stratafs.ko) via local Kbuild
make module

# Or build via DKMS packaging target
make dkms_build

2. Build User-Space Storage Utilities

# Compile mkfs.stratafs, mount.stratafs, and fsck.stratafs
cargo build --release --workspace --exclude stratafs

3. Format and Mount a Volume

# Format block device with LSM storage engine
sudo ./target/release/mkfs.stratafs -e lsm -b 4096 /dev/nvme0n1

# Mount the StrataFS filesystem
sudo mkdir -p /mnt/stratafs
sudo ./target/release/mount.stratafs /dev/nvme0n1 /mnt/stratafs

# Verify mount
df -Th /mnt/stratafs

---

6. Verification, Testing & CI Governance

StrataFS enforces a strict, zero-tolerance verification gate:

# 1. Check workspace compilation and static type contracts
cargo check --workspace --tests

# 2. Run static analysis & forbidden type lints
cargo clippy --workspace --tests -- -D warnings

# 3. Execute all 21 property & unit tests
cargo test --workspace

# 4. Run Kani formal model checking proofs
cargo kani --tests

# 5. Run Python benchmark aggregator linting
python -m ruff check benchmarks/

Verification Matrix

• cargo check --workspace --tests: PASSED (0 Errors, 0 Warnings)
• cargo clippy --workspace --tests: PASSED (0 Errors, 0 Warnings)
• cargo test --workspace: PASSED (21/21 Tests, 100% Success Rate)
• python -m ruff check benchmarks/: PASSED (All checks passed)

---

7. Master Architecture Specification Index

Detailed architectural blueprints are maintained in docs/ and indexed in docs/ARCHITECTURE_INDEX.md:

1. 00. Architecture Overview
2. 01. VFS C/Rust FFI Bridge & Zero-Panic Governance
3. 02. Hexagonal Ports & Static Dispatch
4. 03. Universal Key-Value Namespace & Schema
5. 04. Memory Management, Arena Architecture & Shrinker
6. 05. Storage Engine Internals (LSM & CoW B-Tree)
7. 06. WAL & Crash Consistency Architecture
8. 07. POSIX VFS Triad & Operation Mapping
9. 08. Verification, Testing & CI Governance
10. 09. Production Telemetry, Benchmarking & Fleet Packaging
11. 10. User-Space Tooling & On-Disk Layout
12. 11. Offline Consistency & Repair (fsck)
13. 12. Free Space Management & B-Tree Extent Allocator
14. 13. Enterprise Capabilities (iomap, Shrinker, xattr, RCU)

---

8. License

StrataFS is open-source software licensed under the GNU General Public License v2.0 (GPL-2.0-only).