Filesystem Compatibility & Conformance

Swarmfile mounts as a real drive - for example /Volumes/Projects on macOS, a drive letter on Windows, a mount point on Linux - through FUSE/FUSE-T and WinFsp, not through a synced local folder. The exact location is per-machine and runtime-determined; check the tray's Status tab for yours. That distinction matters for exactly the kind of file your native apps care about: does a rename actually rename, does a lock actually stop a second writer, does opening a 200 GB file touch the whole thing or just the bytes you read.

This page states plainly what's verified today, per platform, and what isn't built yet. We'd rather list a gap here than have you discover it in production.

What's verified#

Every row below is exercised by an automated write-semantics harness that drives the mounted filesystem the way an application does - not the internal storage code directly - on a live mount per platform.

Declared gaps#

Not built, and not silently missing - each of these is a real limitation today, not a bug we haven't found:

• Hard links. Not supported on any platform. Our metadata model is one entry = one path = one content id; a hard link needs a content-identity indirection the schema doesn't have. (For what it's worth, most consumer cloud-sync tools don't model hard links either - they just don't tell you that up front.)

• Symlink creation on Windows. Windows mounts read and follow symlinks correctly but refuse to create one. Creating a Windows symlink as an unprivileged process requires Developer Mode or a specific privilege - support would work for some users and silently fail for others on the same drive, so we refuse consistently instead.

• Extended attributes / alternate data streams on Windows. Not implemented yet.

• fallocate / copy_file_range / lseek(SEEK_HOLE). Not implemented on either POSIX adapter yet.

• fcntl() byte-range advisory locks are kernel-local only. They don't coordinate across machines - that's a different mechanism from the hub-enforced byte-range locking API above. An app that relies on plain POSIX advisory locks for multi-writer coordination (rather than calling into the lock API) gets locking that looks like it works but only protects against other processes on the same machine.

• A file isn't readable the instant it's written. A write returns, the handle closes, and a fresh open of the same path can still read zero bytes for a short window - until the upload and the metadata commit settle. Measured on Windows: immediately after close the file reported 0 bytes, and the full 4 MB about a second later. This is a mount backed by remote storage, not a local disk, and that gap is where the difference shows. It matters for one specific shape of workflow: write a file and immediately read it back in the same script - a save-then-verify step, or a render job that re-opens its own output. Interactive use never notices. If you need to be sure, swarmfile status reports the number of pending uploads, and zero means the engine has nothing left in flight; on macOS and Linux a plain sync does the same job. Our own conformance harnesses all wait this way, on every platform.

• access() / faccessat() aren't enforced locally. Permission is decided hub-side by the ACL system, not by local file mode bits, so a pre-flight access() check reports success even for a write the hub will later refuse.

• A read can WAIT, if you opt into streaming files that are still uploading. Off by default, and this is why. stream_in_flight (see the config reference) lets a file that has never finished uploading be opened - it reports the size it is going to be, and reads work. A read into a range that has not arrived yet then has to wait for it. That wait is bounded (15 s by default), and when it runs out the read returns a retryable error - EAGAIN on macOS and Linux, STATUS_RETRY on Windows - rather than an I/O error, because an application that sees an I/O error part way through a file usually decides the file is damaged and discards your document. A stall is the correct answer for a player; a corrupt-file error is not. Two consequences worth knowing before you turn it on: an application that treats any read failure as fatal will give up rather than retry, and the wait itself has not yet been measured against a real editing application on either platform - which is the reason the default is off rather than on. It only ever applies to a file with no committed version yet, so nothing you are already reading changes behavior.

• macOS: ditto fails on the drive. This is an accepted trade, not a bug we've missed. To stop macOS writing an AppleDouble ._ sidecar for every file - which doubled every file's storage, locks, and history, and cluttered the view for Windows/Linux collaborators - the mount enables NFS namedattr. The side effect is that ditto specifically gives up with an error and writes nothing, from a probe it does above our layer that we can't intercept. Plain cp/cp -R, rsync, and the Finder all work; the fix is to use one of those instead. ditto is what some installers and build scripts reach for, so it's worth knowing before a build step relies on it.

How we verify this#

Each platform has its own conformance harness driving the live mount, and a shared manifest checks that the three harnesses actually agree on what they claim to cover - a capability wired into one platform and not another has, in the past, gone unnoticed for a while. When we close a gap, the harness grows with it; when we can't close one yet, it's listed above instead of left for you to find.

How this compares to typical cloud storage clients#

Most general-purpose cloud storage clients - the kind built primarily for syncing documents and photos - are sync engines wearing a filesystem's clothing: a background process reconciling a local folder against the cloud, not a filesystem driver with defined semantics for the operations above. That's a fine model for a folder of PDFs. It tends to fall over for exactly the workloads Swarmfile targets: whole-file download before an app can open anything, no cross-process byte-range locking, and "two people edited it" resolved by keeping both files rather than by a lock.

This isn't a hypothetical concern - it shows up in vendor documentation for the professional tools this product is built for. Autodesk's own support article on using cloud-synced services with Revit files states that file-based worksharing isn't supported on common cloud-sync storage, and names corruption of the central model and lost work as the consequence. Esri's knowledge base similarly documents common problems running ArcGIS Pro against cloud storage services. If you're evaluating any filesystem - including this one - for this kind of workload, the questions worth asking are the ones this page answers: is locking enforced per byte range or just per whole file, is it enforced on every platform your team actually uses, and is any of it independently verified rather than asserted.