Transport / kernel-facing Unix mount
PreviewFUSE
FUSE is the kernel-facing route for a host that can provide the FUSE device and mount capability. The repository also keeps a mount-free loopback/codec path so applications can use the same contract without a kernel mount.
Linux needs /dev/fuse, a FUSE userspace helper where the selected lifecycle uses one, and the required mount capability. The CLI probes these prerequisites. The repository's FUSE path is not the same thing as macFUSE, and macOS FSKit is documented separately.
Mount-free tests exercise codecs, loopback drivers, and userspace sessions. A native mount is a separate privileged/platform test; do not infer it from a decoded FUSE frame or a successful Rust driver operation.
Mount-free FUSE session and codec evidence plus a revision-specific hosted Linux mount checkpoint exist; callback, native lifecycle, FSKit, cancellation, crash/restart, concurrency, and durability gates remain external. The Rust-backed ./fuse barrel now exposes oracle-shaped typed GETATTR/SETATTR,READ/WRITE,OPEN/OPENDIR, CREATE,LOOKUP, READLINK, and STATFScodecs alongside BATCH_FORGET/INTERRUPT,POLL, FALLOCATE, RENAME2,LSEEK, and COPY_FILE_RANGE. The advanced operation packet validates framing and keeps unsupported valid requests at ENOSYS without mutating the session. The N-API xattr packet adds SETXATTR, GETXATTR,LISTXATTR, and REMOVEXATTR codecs with pinned-oracle coverage across protocol contexts, malformed, truncated, trailing, and declared-size checks. The existing raw-layout IOCTL request/reply and typedBMAP request/reply bodies are now covered by pinned-oracle differentials as well; these remain focused codecs rather than a full native session. The latest packet also adds typedGETLK/SETLK/SETLKW request codecs and the typed GETLK reply. Its pinned-oracle differential covers the 48-byte request, 24-byte reply, truncation, trailing-byte, and empty status-reply boundaries; generated bindings, declarations, typecheck, release build, and the full N-API suite passed. Native FUSE lock/session semantics remain open. The latest packet also adds typedSYMLINK, MKNOD, MKDIR,UNLINK, RMDIR, RENAME,RENAME2, LINK, ACCESS,FALLOCATE, and LSEEK bodies with generated declarations and explicit CommonJS/ESM exports. Pinned byte/decode differentials and artifact aggregation passed; this remains mount-free codec evidence. Other existingRELEASE/RELEASEDIR, FLUSH,FSYNC/FSYNCDIR,packDirents/unpackDirents, andpackDirentsPlus/unpackDirentsPlus. Pinned 7.8/7.39/7.41 differential tests cover protocol bytes, legacy layouts, truncation, trailing data, UTF-8 names, 8-byte alignment, bounded packing, integer coercion, malformed input, embedded-NUL rejection, and inode parity. Current-tree Rust session coverage adds 16 frame-level cases for the simple namespace operations above, including rollback and inode-path cleanup, error/state preservation, regular-fileMKNOD fallback, symlink access checks, and theNAME_MAX boundary. Existing session tests cover focusedACCESS, BATCH_FORGET, and fail-closedINTERRUPT validation; six INIT tests cover negotiatedFUSE_INIT_EXTand flags2 handling. A revision-specific hosted Linux FUSE job passed on 35ffbfa, but the current W01-FUSE tracker keeps hosted /dev/fuse, callback-event, FSKit, cancellation/concurrency, crash/restart, and durability qualification as external gates. The current packet also adds fail-closed native mount-option validation plus FuseMountHooks andFuseTransportError exactly-once terminal reporting; this is current-tree and mount-free evidence, not a fresh hosted native pass. The mount-free lock session now covers GETLK,SETLK, same-owner replacement/unlock, andRELEASE/DESTROY cleanup in 19 focused cases; serialized SETLKW returns explicit EAGAIN, so native POSIX locking is not advertised yet. The automatic mount bridge now carries one owned onTransportError callback through the FUSE, 9P, and NFS paths, and the native request loop isolates backend panic and stop-aware cancellation into bounded session cleanup. Local macOS and Linux-target checks pass; hosted Linux callback, fault, crash/restart, and concurrent native execution remain external. The mount-free N-API session keeps INIT defaults conservative rather than advertising asynchronous or parallel capabilities that the serialized path cannot provide. Native FUSE now has up to 16 positional read workers with a serialized reply writer and targeted interrupt handling; the eight-client native harness compiles and now also includes blocked-read teardown and backend-panic callback cases, all awaiting hosted /dev/fuse execution. The current W01 packet also adds public FuseSessionoptions, negotiated state, inode views, request/reply/error counters, assertion and transport-error callbacks, notification encoders, and destroy-state readback. On the actual Darwin 27 arm64 host,/dev/fuse is absent and the non-Linux mount path returnsUnsupportedPlatform without touching the requested path; the supported native macOS path is NFS, with no macFUSE or FSKit FUSE parity claim. The automatic mount facade now reports the configured FUSE fsname through its shared source property; unsupported-platform FUSE objects return no source. This is local/source parity; exact-SHA hosted runs remain pending and do not close native evidence. Hosted Linux callback, concurrency, close-race, crash/restart, and durability execution remain open. The current native frame ledger also requires a modernFUSE_WRITE header plus one page (4176 bytes) before advertising max_frame; the remaining mount-member decisions are recorded explicitly in the transport README. This is validation and scope evidence, not hosted /dev/fuse proof. Hosted native-FUSE runs 35657075892 and35659287961 still timed out both unmount cases at the 15-second bound, including the corrected descriptor-drain path, so no hosted native-FUSE acceptance is claimed. The subsequent manual run35662415701 passed ordinary round-trip and backend-panic close but still timed out blocked-read unmount and kernel read, so the latest stop-aware terminal-reply fix also remains unaccepted. A newer non-canceling manual run 35666436803 atac04a93 again passed round-trip and backend-panic callback/close, but blocked-read unmount exceeded the 15-second harness bound; overlapping lazy detach with the stop grace is the current fix, not a hosted lifecycle pass. The newer published candidate1bdd6adf narrows the forced-detach fallback to confirmedEBUSY and dispatched exact-tip run35673738166; all Node, Rust, and native-FUSE jobs were queued at the latest ledger snapshot, so no current-tip acceptance is claimable. Plain-flag RENAME2 is now supported at session dispatch; unsupported flags remain explicit ENOSYS with no mutation. The no-reply FORGET path follows the pinned session behavior: a malformed body is ignored without releasing the inode, while valid FORGET releases its lookup count. MalformedBATCH_FORGET frames remain validated before any inode release. This is a session-boundary behavior, not native mount proof.FALLOCATE, LSEEK, andCOPY_FILE_RANGE remain unsupported boundaries. The Lima source packet at commit 467da6a7 now also passes the repository's in-process PGlite native-FUSE scope: mounted PGlite connection reopen and PGlite-backed SQLite compositions pass without external credentials. This closes the local PGlite qualification gap, but hosted exact-tip native-FUSE acceptance and the wider W01 release and provider gates remain open. The published CLI at source 32b85965 also passes a strict Lima Ubuntu arm64 native-FUSE smoke: the memory driver mounted throughmount-rs --transport fuse, a fixed payload survived readback before and after rename, the old name was absent and the new name present, SIGINT shut down the process, and the mount was absent afterward (CLI_FUSE_STRICT_SMOKE=PASS). This closes local shipped-CLI usability on Linux only; hosted terminal native-FUSE and wider release gates remain open. The latest terminal CI packet 35698854392 at source116e9ed4 canceled its native-FUSE job before a hosted/dev/fuse result. A newer manual run35715585800 at source e175f80a left native-FUSE job 106706185799 queued with no runner, completion time, conclusion, or step output. Its successor run35716364566 at source 4e9260ea was cancelled before any job was created by another mainline push, and the next run35716566393 at 924009af is pending. No hosted native-FUSE result is claimable from these queue/cancellation states; exact-current-tip terminal evidence remains required. Callback delivery, close races, crash/restart, concurrency, locks, and durability remain open. The immutable W05 candidate in CI run 35714144497 also passed its native-FUSE job 106701527830: injected read-panic recovery and the exercised mount, SQLite, PGlite, and cleanup tests all passed. This is candidate job-scoped Linux evidence, not current-main hosted acceptance or a release decision; exact-tip hosted native-FUSE and the wider provider/release gates remain open. The follow-up implementation at source 85362348 hardens the Linux FUSE control plane at the hosted failure boundary: terminalFUSE_DESTROY aborts blocked positional-read workers immediately, the invalid-device regression uses a readyeventfd, and the retryable-unmount fixture exercises a real mounted path. Host FUSE tests passed 15/15, Linux-target test compilation and formatting/diff checks passed, but hosted Linux Rust/native-FUSE confirmation remains required; this is local implementation evidence, not a new hosted acceptance claim. The subsequent FUSE fix at source 40a9a3d8 addresses the rootless fusermount3 EBUSY blocked-read path by draining the serving task before lazy detach and recognizing a successful handoff; native and automatic test mountpoints also use unique suffixes. Lima requalification at 65776be passed native 3/3, automatic concurrent 2/2, CLI 3/3, SQLite restart 2/2, fault 1/1, native PGlite reopen 1/1, and PGlite compositions 1/1 with no stale mounts or processes. This remains local Linux evidence; no hosted /dev/fuse result is promoted.
What the transport exposes
The codec represents a broad protocol-7.41 wire surface, while the current native session dispatch intentionally supports a smaller set. Unsupported native operations return explicit errors rather than being silently claimed as complete parity.
Check the mount-free and native boundaries separately
cargo test -p mount-rs-fuse --locked
cargo run --locked -p mount-rs-cli -- probe
# Only on a prepared Linux host, when explicitly enabled:
MOUNT_RS_CLI_NATIVE_FUSE=1 cargo test -p mount-rs-cli --test native_lifecycle -- --ignored --nocaptureSafe use and lifecycle
Keep mountpoints empty and owned by the test process, unmount on every exit path, and treat elevated mount capability as a host prerequisite, not as a reason to broaden the test's filesystem scope.
Current limitations
The codec is not a complete native session. The public Node barrel now covers typed READ/WRITE,GETATTR/SETATTR,OPEN/OPENDIR, CREATE,LOOKUP, READLINK, STATFS,SYMLINK, MKNOD, MKDIR,UNLINK, RMDIR, RENAME,LINK, ACCESS,BATCH_FORGET, INTERRUPT, POLL,FALLOCATE, RENAME2, LSEEK,GETLK/SETLK/SETLKW, andCOPY_FILE_RANGE, RELEASE/RELEASEDIR,FLUSH, and FSYNC/FSYNCDIR bodies, plus SETXATTR/GETXATTR/LISTXATTR/REMOVEXATTR request/reply codecs andREADDIR/READDIRPLUS directory codecs. These are focused mount-free boundaries: malformed or trailing advanced requests fail closed and valid unsupported operations still returnENOSYS. Full request/reply, init negotiation, session, and native-mount surfaces remain open. The current-tree Rust session packet adds 16 frame-level cases for SYMLINK, MKNOD,MKDIR, UNLINK, RMDIR,RENAME, LINK, and ACCESS, including error/state cleanup, regular-file MKNOD fallback, and the POSIX 255-byte name limit. Advanced FALLOCATE/LSEEKsemantics and the native device/mount remain open. Plain-flagRENAME2 now participates in the Rust session path; unsupported flag bits return ENOSYS without mutating the namespace, while COPY_FILE_RANGE remains unsupported. FUSE evidence does not qualify NFS, 9P, or FSKit.
Sources: FUSE transport boundary · FUSE body codec tests · N-API FUSE parity ledger · W01 FUSE progress tracker · CLI native prerequisites · Historical hosted Linux transport CI · Latest hosted FUSE diagnostic · Latest hosted FUSE status packet · Current exact-tip FUSE qualification · Lima in-process PGlite qualification · Hosted FUSE queue blocker · Hosted FUSE cancellation refresh · Pending current-tip FUSE run · Lima shipped-CLI FUSE smoke · Candidate native FUSE sub-gate · FUSE teardown/read control-plane hardening · FUSE blocked-read unmount and lazy-detach fix