Filesystem Compatibility & Conformance

Swarmfile mounts as a real drive - ~/Swarmfile on macOS and Linux, a drive letter on Windows - through FUSE/FUSE-T and WinFsp, not through a synced local folder. The exact location is per-machine and can be configured (the engine's mount_point; Windows picks its drive letter at runtime), so read yours from the Desktop App's Status pill rather than hard-coding a path. 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 works today, per platform, and what's a known gap.

What's verified#

Most rows below are exercised by automated write-semantics tests that drive the mounted filesystem the way an application does - not the internal storage code directly - on a live mount per platform. A few rows (adapter capabilities and platform-specific behavior) are covered by targeted tests instead; the Notes column says when.

Declared gaps#

Each of these is a documented limitation:

• 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.

• 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.

• Renaming an alternate data stream itself. Renaming the base file that carries a stream works normally, and the stream travels with it. Renaming just the stream - file.txt:secret to file.txt:hidden - is out of scope and refused outright, not silently mishandled: we won't rename the base file when you only asked to rename one of its streams, and we won't leave the stream qualifier in a request that no path would ever resolve to.

• Extended attributes on Windows. Not implemented - a deliberate scope decision, separate from alternate data streams (see the verified-capabilities table above, which streams are supported).

• A save the hub refuses reaches the app as EIO. When a save is refused (a file held elsewhere, a plan or policy refusal, a root-create restriction, quarantine), the application only sees a generic I/O error; the reason is written under Why did my save fail? in the tray and printed by swarmfile sync stuck. The errno is deliberately generic, so read the reason there rather than from the app's error dialog.

• fallocate / copy_file_range / lseek(SEEK_HOLE). Not implemented on the POSIX adapters.

• 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.

• Windows: a memory-mapped view can outlive the handle for reads, not for writes. Reading through a memory-mapped view works, including when an application closes the file handle before reading the map - git does exactly that with .git/config, which is why git init/commit/status work on the mount. Writing through a mapping is only served while a file handle is open: an application that maps a file read-write, closes the handle, and then writes through the view can have those write-backs fail. Keep the handle open until the mapping is unmapped, or write through the handle. Read-only mappings (the common case, git included) are unaffected.

• A file isn't readable the instant it's written - for about a second, on Windows. The engine itself publishes the new content synchronously as the flush completes (the local metadata row, size included, is updated before close returns), so a script that opens the file through a fresh handle gets the new bytes on macOS and Linux. Windows can still report the old attributes (0 bytes for a new file, the previous size for an overwrite) for up to its 1-second Cache Manager revalidation timeout, because the kernel caches file info between revalidations. It matters for any workflow that writes a file and immediately reads it back - a save-then-verify step, a render job that re-opens its own output, or an app that reloads the file right after saving. A person clicking around is usually slower than the one-second window, but not always: reopening a just-saved file within that second can still see the old size. If you need certainty, wait on the engine rather than the clock: swarmfile uploads --wait blocks until the upload queue is empty, and swarmfile status splits the rest - pending uploads (blocks still going up), commits pending (bytes up, commit not landed; a plan-held commit shows under quota-held commits). (A plain sync forces pending writes to flush locally but does not wait for the hub upload and commit, so use the counters, not sync, when that distinction matters.)

• 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, for a file that is still uploading. A file that has never finished uploading can be opened - it reports the size it is going to be, and reads work. A read into a range that has not arrived yet waits for it, bounded at 15 s by default, and returns a retryable error - EAGAIN on macOS and Linux, STATUS_IO_TIMEOUT on Windows - rather than an I/O error if the wait times out, 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. It only ever applies to a file with no committed version yet, so nothing you are already reading changes behavior.

• macOS: ditto works. Plain cp/cp -R, rsync, Finder, and the installers and build scripts that reach for ditto all work.

• macOS extended attributes are local-only. The drive is mounted without NFS named attributes, so macOS keeps Finder tags, comments, and the like the way it does on any such volume: in an AppleDouble ._name file beside the original. Swarmfile keeps those ._ files, and .DS_Store, on the machine that wrote them and never syncs them (see Sync Exclusions) - cp -p, ditto, and xattr work with them on that machine, but a teammate (or that machine after a fresh install) won't see them. Windows alternate data streams are the exception and do travel (except the Zone.Identifier Mark of the Web, which stays local); POSIX xattrs crossing machines would be a hub-side format addition, not a mount fix.

How we verify this#

Each platform has its own conformance suite driving the live mount, and a shared manifest keeps the three platforms' coverage aligned - a capability missing on one platform is caught rather than left for you to find. Known gaps are listed above.

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.