The File System is a Menu, Not the Kitchen: Demystifying Stubbing

The Great File System Lie

For the last thirty years, consumer operating systems have trained us to think about storage in a very literal way. When you open a folder and see project_alpha_final.mov, you inherently trust that the exact magnetic sectors or silicon cells holding that movie are spinning directly underneath that file path.

If you move the file to an external hard drive, the icon disappears from your local folder and appears on the external drive. The visual metaphor strictly enforces the idea: the file system is the ground truth of a file's physical location.

But what if it wasn't?

What if your file system was just a menu at a restaurant? You look at the menu, you see a burger. But the burger isn't inside the menu. The menu is just a presentation layer. The burger is in the kitchen. And when you order it, someone goes to the kitchen, gets it, and puts it in front of you.

This separation between the presentation layer (the namespace you see in your OS) and the storage tier (where the bytes actually live) is the core concept behind HuskHoard. It’s a process called stubbing.

Why Mainframe Admins Already Get This

In enterprise computing, storage has always been tiered. Flash storage is fast but incredibly expensive. Tape storage is slow but incredibly cheap. To get the best of both worlds, mainframe systems were designed to automatically migrate cold (unused) data off the expensive fast tier and onto the cheap slow tier.

Crucially, they didn't change the file path when they moved the data.

If an application expected a payroll database to be at /data/payroll.db, it stayed there. The system simply hollowed out the file, moved the heavy bytes to tape, and left a tiny placeholder (a "stub") behind. When the payroll app woke up months later and tried to read the file, the OS paused the application, fetched the bytes back from tape, filled the file back in, and unpaused the application.

HuskHoard brings this exact enterprise concept to modern Linux environments using Rust.

Anatomy of a Stub: What Happens on Disk?

When the HuskHoard Janitor decides a file is cold (e.g., it hasn't been touched in 30 days), it securely copies the data to your tape library. Then, it turns the local file into a stub.

To the average sysadmin, a stub looks like dark magic. It is not a symlink. It is not a shortcut file. It is the original file, but we use a Linux system call called fallocate with the FALLOC_FL_PUNCH_HOLE flag.

By punching a hole, we tell the SSD filesystem: "Keep the inode. Keep the permissions. Keep the apparent file size so applications don't crash. But delete the actual data blocks."

We then slap a hidden extended attribute (xattr) on the file: trusted.husk.status = stubbed. Finally, HuskHoard uses utimensat to silently restore the original "Last Modified" and "Last Accessed" timestamps, so your backup software and IDEs don't even realize the file was touched.

This is the presentation layer at work. The file system is showing you the menu. But the 47GB of data is no longer on your SSD.

The Catalog: The Real Ground Truth

If the file system no longer holds the physical data, where is the ground truth?

In HuskHoard, the ground truth is the Husk Catalog — a highly optimized SQLite database (husk_catalog.db) running in Write-Ahead Logging (WAL) mode.

Every time a file is archived, the catalog records exactly where the payload went. It tracks the original path, the payload size, the compression ratio, the BLAKE3 checksum, and most importantly: the tape_uuid and the exact byte tape_offset.

The file system provides the namespace hierarchy (folders and permissions). The Catalog provides the physical map. You can completely destroy your Hot Tier SSD, and as long as you have your Catalog and your Tapes, HuskHoard can instantly recreate millions of zero-byte stubs to perfectly reconstruct your presentation layer in seconds.

The Interceptor: Magic via fanotify

So, the file is empty on disk, and the data is on a tape in a box. What happens when a user, an editor, or a Python script actually double-clicks or runs open() on that stubbed file?

If the OS just read the file, it would return thousands of gigabytes of empty zeroes (because we punched a hole in it). This is where the Husk Daemon steps in using a Linux kernel feature called fanotify.

HuskHoard intercepts the FAN_ACCESS_PERM event. Before the requesting application is allowed to read a single byte, HuskHoard pauses the application's thread.

If the data is on an active volume (like an online rclone cloud bucket or an inserted tape), HuskHoard streams the data back into the sparse file, verifies the BLAKE3 hash, strips the trusted.husk.status xattr, and tells the kernel: "Okay, let the application proceed."

From the application's perspective, the read operation didn't fail. It was just a really, really slow hard drive for a few minutes. It has no idea that the data was just summoned from a magnetic tape.

Why This Changes How You Buy Storage

Unlearning the idea that "the file system equals physical location" is conceptually difficult, but economically liberating. Once you accept that the file system is just a presentation layer, you stop buying expensive storage for cold data.

The next time you look at a file in your terminal or file explorer, remember: you're just looking at the menu. With HuskHoard, you can put the kitchen on a $105 tape cartridge, and your operating system will never know the difference.