ArgosFS

Compatibility

A real FUSE surface, tested like one.

ArgosFS exposes mounted filesystem behavior for metadata, byte-oriented names, xattrs, rename flags, sticky directories, special inode types, import/export roundtrips, and durability hooks.

Coverage matrix

Compatibility is tracked by behavior, not just API count.

The matrix focuses on observable filesystem behavior: what applications see through a mounted FUSE filesystem and what survives metadata export, import, failure, and repair paths.

Area
Status
Coverage
Read/write/create
Passed
Rust integration tests, mounted FUSE smoke, overwrite paths, truncate paths, and range-write behavior.
chmod/chown/truncate/utimens
Passed
Split permission checks in FUSE setattr, timestamp updates, ownership changes, and export ordering.
xattrs and ACLs
Bounded
user.*, POSIX ACLs, and ArgosFS system xattrs are handled explicitly with error reporting for unsupported forms.
rename flags
Passed
RENAME_NOREPLACE and RENAME_EXCHANGE; whiteout is rejected rather than silently misapplied.
non-UTF-8 names
Passed
FUSE byte names round-trip through reversible internal encoding and are decoded for user-visible path iteration.
hard links and symlinks
Passed
Hard-link permission checks, symlink target decoding, and rootfs metadata roundtrips are covered by regression tests.
special files
Bounded
Device numbers, FIFOs, sockets, and root metadata are preserved in import/export paths when the host permissions allow it.
pjdfstest/xfstests
Tracked
Scripts emit stable JSONL and skipped records when external suites or privileges are unavailable.

Why compatibility is hard

A filesystem is more than reading and writing bytes.

Many FUSE demos pass simple file tests while failing on edge cases that real Linux systems rely on. ArgosFS tracks these cases because root filesystem use makes small metadata mistakes visible.

Names

Byte-oriented paths

Linux path components are bytes, not guaranteed UTF-8 strings. ArgosFS therefore uses reversible encoding instead of dropping invalid names.

Metadata

Import/export order

Directory metadata must be applied after children are created in some cases, and ownership should be restored before mode when permission bits matter.

Durability

fsync and journal checks

Application-visible durability requires syncing the right metadata and shard state, not just returning success from the FUSE handler.

Permissions

Sticky and hard-link rules

Rename and link behavior must respect sticky directories, source permissions, and target existence semantics.

Regression guardrails

Compatibility checks are meant to be repeatable.

The scripts are plain shell and JSONL-oriented so failures can be stored as artifacts rather than lost in terminal output.

Local validation

Useful test commands

  • cargo test for core Rust integration coverage.
  • scripts/compat/run_fuse_smoke.sh for mounted filesystem behavior.
  • scripts/compat/run_deep_roundtrip.sh for byte names, xattrs, import/export, and metadata preservation.
  • scripts/compat/run_pjdfstest.sh for optional POSIX suite integration.
  • scripts/ci/check_regressions.sh for high-signal project-specific guards.

Run locally

Compatibility scripts are plain shell.

Use a temporary mountpoint for smoke testing, and record outputs into paper-data when running reproducible experiments.

scripts/compat/run_fuse_smoke.sh
scripts/compat/run_deep_roundtrip.sh /mnt/argosfs
scripts/compat/run_pjdfstest.sh /mnt/argosfs paper-data/compat/pjdfstest.jsonl
scripts/ci/check_regressions.sh