NexFS

v0.3.0 — 51/51 Tests Passing

NexFS is the Nexus sovereign filesystem. It is implemented in Zig with zero dynamic allocation, designed to run on everything from flash chips to enterprise storage arrays.

Core Format

The on-disk format uses fixed-size structures for predictable performance:

Structure	Size	Purpose
Superblock	128 bytes (dual)	Volume identity, format version, storage class × network scope
Inode	128 bytes	File/directory metadata, extent pointers
Extent	16 bytes	Contiguous block range
DirEntry	48 bytes + name	Directory entry with inode reference
BAM Entry	12 bytes	Block Allocation Map entry

Dual Superblock

NexFS writes two superblocks (primary and backup). On mount, both are read and the one with the higher generation number is used. This provides crash recovery — if power is lost during a superblock update, the backup is still valid.

Superblock Identity

Each volume carries a dual-axis identity:

storage_class × network_scope

• storage_class: 0x00 (Core), 0x01 (Sovereign), 0x02 (Mesh)
• network_scope: Encoded in the superblock flags

This identity determines which feature set the volume supports at mount time.

Volume Profiles

Profile	Storage Class	Features
Core (0x00)	Minimal	Basic read/write, inode tree, BAM
Sovereign (0x01)	Full local	+ CAS, CDC, DAG, TimeWarp
Mesh (0x02)	Networked	+ Wire protocol, peer sync

Sovereign Extensions

When running with nexfs_sovereign enabled, NexFS adds:

Content-Addressable Store (CAS)

Files are addressed by their BLAKE3 hash. Two files with identical content share the same storage blocks. Deduplication is automatic and transparent.

Content-Defined Chunking (CDC)

Large files are split at content-determined boundaries (not fixed-size blocks). This means small edits to a large file only require re-storing the changed chunks, not the entire file.

DAG Versioning

File history is stored as a directed acyclic graph (Merkle DAG). Each version points to its parent(s). This enables:

• Efficient branching and merging
• Cryptographic verification of history integrity
• Lightweight forks that share unchanged data

TimeWarp Snapshots

Instant filesystem snapshots using copy-on-write DAG nodes. Creating a snapshot is O(1) — it just records a new root pointer in the DAG.

Hash Strategy

NexFS uses different hash algorithms for different purposes:

Hash	Use	Why
BLAKE3-256	CAS content addressing (default)	Fast, parallelizable, cryptographic
BLAKE3-128	Compact CAS (constrained devices)	Half the hash, still collision-resistant
XXH3-64	BAM checksums, internal integrity	Ultra-fast, non-cryptographic
SipHash-128	CellID generation for UTCP	Keyed, DoS-resistant
Ed25519	ProvChain signatures	Digital signatures for audit trail

C FFI

NexFS exposes a C-compatible API for integration with other components:

nexfs_format()      // Format a volume
nexfs_mount()       // Mount a volume
nexfs_unmount()     // Unmount
nexfs_is_mounted()  // Check mount status
nexfs_read()        // Read file data
nexfs_write()       // Write file data
nexfs_create()      // Create a file
nexfs_mkdir()       // Create a directory
nexfs_delete()      // Delete a file
nexfs_rmdir()       // Remove a directory

Wire Protocol

For networked volumes (Mesh profile), NexFS uses a wire protocol over UTCP:

Message	Purpose
BLOCK_WANT	Request a block by hash
BLOCK_PUT	Deliver a block
DAG_SYNC	Synchronize DAG heads between peers

This protocol enables peer-to-peer storage synchronization without a central server.