Compatibility and limits
The four published Effect Virtual FS packages implement a documented subset of POSIX filesystem behavior.
They do not provide a mounted host filesystem, a complete POSIX implementation, or a way to intercept direct calls to
node:fs.
This page records the supported package format, runtime evidence, filesystem differences, and resource limits. Follow the API links for exact types and signatures.
Package compatibility
| Package | Module format | Purpose |
|---|---|---|
@effect-vfs/core | ESM only | Runtime-neutral volumes, callers, handles, snapshots, and overlays |
@effect-vfs/memory | ESM only | Effect FileSystem.FileSystem adapter |
@effect-vfs/persistence | ESM only | Named SQLite checkpoints and live-image storage |
@effect-vfs/nfs | ESM only | NFSv4.1 export with guarded experimental writes |
Use an ES module build. Each published package declares its supported Effect range in
peerDependencies.effect. To check a specific release, run npm view @effect-vfs/core@VERSION peerDependencies.effect with its version.
The current core and memory source manifests declare ~4.1.4, and the qualification jobs use Effect 4.1.4.
Match any @effect/* providers to the installed Effect version.
The published manifests do not declare a minimum consumer Node.js version. See the tested configurations below. The SQLite provider requires Bun. Core and memory can also run on Node.js.
Memory execution mode
Memory volumes default to execution: "cooperative". Opt in to execution: "sync" when namespace and handle operations
must complete synchronously. Operations still return Effects, and construction can require asynchronous setup.
import { Effect } from "effect"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
const program = Effect.gen(function*() {
const volume = yield* Vfs.make({ execution: "sync" })
const caller = yield* volume.caller()
yield* caller.mkdir("/work")
return yield* caller.stat("/work")
})All callers and handles on that volume share the mode. Fixture, snapshot and overlay constructors accept the same
option. Restoring without it selects cooperative scheduling; snapshots and images do not store execution policy.
MemoryFileSystem.layerFromFixture(fixture, { execution: "sync" }) also supports the mode. Existing make and layer
values keep their cooperative defaults. A live storage constructor rejects sync mode, even for a store reporting
memory-only durability.
Sync coordination does not yield while owning state. Large paths, files, directories or subscriber sets can therefore
block the thread. Snapshot and overlay processing can yield after immutable capture, and watch streams wait for events.
The mode does not promise synchronous completion for arbitrary Effect programs, custom runtime hooks or community
work outside the engine. It does not provide a native node:fs adapter.
Ordinary same-volume reentry fails with VolumeBusy. Scope cleanup can invalidate a handle during an active operation
and reclaim its inode before that operation returns. Once a transition starts, installation and cleanup finish before
interruption is delivered; an interruption can therefore report a completed mutation. Recursive helpers retain their
existing partial-progress boundaries. No failed synchronous operation is left queued to mutate later.
Runtime evidence
Core and memory support the following runtime configurations. Both CI jobs import the built package exports, read and write a seeded file, interrupt a watch and check its release, apply a snapshot delta, search the restored snapshot, and round-trip a reference key. They exercise both the runtime's Effect crypto provider and asynchronous WebCrypto.
| Supported runtime | Operating system | CI check |
|---|---|---|
| Node.js 24.21.0 | Ubuntu 24.04 x64 | Core and memory, Node 24.21.0 |
| Bun 1.4.4 | Ubuntu 24.04 x64 | Core and memory, Bun 1.4.4 |
The Bun job also checks seek, sparse writes and truncate against both the memory adapter and host files. Earlier host-file failures on Bun 1.4.0 on macOS are recorded in #275. The Linux checks do not qualify macOS, Windows, or other runtime versions.
Browser bundling. The memory build bundles for a browser target and executes the bundle under Node.js. Browser and worker execution. These environments are outside the supported list. CI does not run the packages there.
The native Node filesystem provider and SQLite persistence have separate runtime checks. The core and memory rows do not extend to those packages.
Portable snapshot-delta operations use Effect's Digest and SecureRandom services. Supply the appropriate Effect crypto
layer for the runtime at the application boundary.
Implemented filesystem behavior
The core supports regular files, directories, symbolic links, hard links, component-by-component path lookup, directory-relative lookup, scoped file and directory handles, metadata, permissions, namespace changes, watches, and snapshot capture.
The behavior follows documented POSIX.1-2024 rules for this subset, with these important boundaries:
- typed Effect failures replace global
errno; - Effect scopes manage derived callers, handles, and watch subscriptions;
- caller privilege is explicit and does not come from the host process;
- storage is dense and in memory, not sparse or host-backed; and
- the memory adapter may follow Effect
FileSystembehavior where it differs from the lower-level core contract.
These packages do not claim full POSIX conformance. They do not provide a C filesystem API, simulated process,
device files, FIFOs, filesystem sockets, or descriptor duplication. Directory trees move between a host and a volume
only as explicit copies through TreeTransfer, within the losses its Effect FileSystem adapter declares. The NFS server
tracks read locks between NFS clients, but direct VFS callers do not participate in those locks. Named checkpoints
are explicit copies. The separate SQLite live-image store does not currently qualify for host fsync durability.
Reference keys
volume.referenceKey(reference) returns a ReferenceKey: the volume identity, an epoch, the object's inode number,
and a tag. The tag is 16 bytes of HMAC-SHA-256 over the other three under a secret only the volume holds. The schema
carries the identity, epoch and tag as base64 and the inode number as a decimal string, so a key can be stored or
sent and decoded again. volume.resolveReferenceKey(key) returns the same reference traversal would.
- Every construction draws a new epoch and secret:
make,fromSnapshot,fromFixture, andmakeOverlay. A key never resolves in another volume, even one restored under the same identity. - A live volume keeps its epoch and secret across a reopen, so its keys resolve to the same objects after a restart.
- A key from another identity or epoch fails
ForeignReference, a key whose object is goneStaleReference, and a malformed key or one whose tag the volume did not computeInvalidReference. An unlinked file stays resolvable while a handle holds it. - Resolution is on the volume, not a caller, and checks no permission. Inode numbers are sequential, but a holder of one key cannot write another's tag, so a key reaches only an object some key was issued for.
- Rolling a live store back to an older image can reuse an inode number for a different object. The key cannot detect that.
- Two live volumes opened from one image, such as a copied store or a second open of the same bytes, share its identity, epoch and secret, so a key minted in one resolves to whatever holds that inode in the other. A live image has one writer; do not serve a copied store under persistent NFS filehandles beside the original.
Path limits
| Limit | Value | Configurable |
|---|---|---|
| Path component | 255 bytes | No |
| Symbolic-link traversals during one resolution | 40 | No |
| Total encoded path length | Unlimited by default | Yes, with maxPathBytes |
| String path encoding | Valid UTF-8 without NUL or lone surrogates | No |
BytePath preserves arbitrary non-NUL filename bytes. String-returning operations fail when a stored name cannot be
represented as UTF-8.
Absolute paths ignore a supplied directory base. Relative paths can use a live DirectoryHandle from the same volume.
Volume capacity limits
Pass optional limits when creating or restoring a core volume.
| Option | What it limits | Default |
|---|---|---|
maxEntries | Namespace entries | No configured limit |
maxBytes | Logical bytes held by regular files and symbolic-link targets | No configured limit |
maxFileBytes | Bytes in one regular file | 4,294,967,295 bytes |
maxPathBytes | Total encoded bytes accepted for one path | No configured limit |
The dense-file ceiling of 4,294,967,295 bytes is fixed. maxFileBytes may lower it but cannot raise it. File contents and
symbolic-link targets are charged once per inode, so hard links do not duplicate their byte charge. An unlinked file
remains charged while an open handle keeps it alive.
The VirtualFileSystem API reference documents VolumeOptions and the constructors that
accept it.
Watch behavior
volume.watch() opens a scoped stream of future committed create, update, and remove events.
- Events are not replayed.
- Registration is coordinated with mutations so an event cannot be lost while the subscription becomes active.
maxWatchEventsdefaults to 256 queued events per subscriber and can be configured on a volume.- When a subscriber loses events, it receives
Rescanat/and must read the volume again. - Closing the owning scope releases the subscription.
volume.watch({ scope })narrows the stream to one object reference and, unlessrecursiveisfalse, its subtree. Changes outside the scope never count toward its queue. The scope follows renames of the object and its ancestors, a move out of it arrives asRemoveand a move into it asCreate,Rescannames the object's current path, and the stream ends afterRemovefor the object once its last name is gone.
A slow consumer does not retain an unbounded event history. Treat Rescan as an invalidation signal, not a replay.
Tree operations
Three caller verbs work on a whole tree. Only a recursive mkdir is one change; the other two are compositions of
smaller operations, so another caller can change the tree while they run.
caller.walk(directory)streams every entry below a directory, depth first and in the byte order of each directory's names, with its path relative to the directory, its reference, its kind, and its depth. It reads one directory at a time, holds no handle, reports symbolic links without following them, and refreshes no access time. It reaches each directory by name, as a path does, so it needs search permission on the directories above it and skips a directory that went away or was renamed out of the tree after it was listed.maxDepth,maxEntries, andmaxBytesare optional and fail withLimitExceededwhen passed.mkdir(path, { recursive: true })creates every missing directory on the path in one change, asmkdir -pdoes, so a failure creates none of them. It follows symbolic links on the way, walks dot names, and succeeds when the final directory exists.remove(entry, { recursive: true })empties a directory entry by entry, each by name, and stops at the first failure, whose path names the entry it stopped at. A directory with entries must be readable; no permission is changed to make it so.forceforgives only the target itself going missing.
Glob limits
Globbing belongs to the memory adapter. Patterns may be relative to the selected root or absolute.
The local portable implementation supports *, Unicode-aware ?, **, character classes and ranges,
POSIX character classes, class negation, escaping, and nested comma-list brace expansion. Expansion
uses the upstream limits of 10,000 alternatives, a maximum expanded length of 2²² and 64 brace levels.
It does not support extglobs, numeric brace ranges or whole-pattern negation.
A trailing slash matches directories only. Hidden names require an explicit leading dot in the pattern
segment through the published FileSystem interface. Symlink directories are followed through explicit
segments, and never recursively through **. Results follow depth-first order with sorted entries per
directory. Excluded directories are pruned before reading them. Unreadable wildcard-reached directories
are skipped; named unreadable directories fail.
Snapshot decode limits
decodeSnapshot and decodeSnapshotSink require a DecodeLimits value with its four counts. There is no default
decode policy.
| Field | Work it bounds |
|---|---|
maxEncodedBytes | Encoded snapshot input bytes |
maxRecords | Stored objects, one node each, the root included |
maxEntries | Namespace entries, counting every name of a hard link |
maxDecodedBytes | Decoded bytes of names, file contents and link targets |
maxLineBytes | One line of the encoding; optional, maxEncodedBytes |
Encoded and decoded byte budgets use ByteSize.ByteSize. Record and entry limits are numbers. Restoring the decoded
snapshot also applies the destination volume's capacity limits.
See the Snapshot API reference and
VirtualFileSystem API reference.
Snapshot delta limits
One complete SnapshotDeltaLimits policy applies to delta creation, inspection, encoding, decoding, and application.
Omitting it selects the frozen SnapshotDeltaLimits.default policy. SnapshotDeltaLimits.constrained is a smaller preset
for memory-sensitive environments. A custom policy must provide every field.
The policy bounds encoded and decoded delta bytes, the bytes hashed for each snapshot's identity, base and target
records, the changes a delta holds, the records an applied delta produces, namespace entries, output payload bytes, and
the target records carried over from the base. Byte budgets use ByteSize.ByteSize; record
and entry budgets use numbers.
See the Snapshot delta API reference for the preset values and complete policy schema.
Volume limits and delta-work limits apply independently. The default delta budget rejects a measured 10,000-file workspace that fits its volume quotas. See the qualified 10,000-file example for the complete volume and delta settings, the measured memory cost, and the workload's limits.
Which limits callers can configure
| Area | Caller-configurable |
|---|---|
| Volume capacity and total path length | Yes, through VolumeOptions |
| Snapshot decoding | Yes, and a complete policy is required |
| Snapshot delta work | Yes, through a preset or complete custom policy |
| Path component length and symlink traversal count | No |
| Dense-file hard ceiling | No, but maxFileBytes can lower it |
| Watch queue | Yes, through maxWatchEvents |
| Glob brace expansion | No |
Effect 4.1 migration
Effect 4.1 replaces the Crypto service with Digest and SecureRandom from effect/crypto. Volume constructors and
layers, snapshot deltas and the NFS server now require Digest.Digest | SecureRandom.SecureRandom where they required
Crypto.Crypto; the live image stores require only Digest.Digest. NodeCrypto.layer and BunCrypto.layer provide
both, so a program that already provides one needs no change. Digest.layerWebCrypto and SecureRandom.layerWebCrypto
provide them without a platform package. BunServices.layer does not include them. Provider defects remain defects.
Effect peers are restricted to the 4.1 patch line.
Effect 4.1's FileSystem.make requires readDirectoryEntries and derives glob. The memory adapter now exposes its
typed entry listing as readDirectoryEntries and keeps the local glob implementation described below, so glob results
are unchanged. FileSystemTesting gains a readDirectoryEntries handler; its glob traversal still passes through the
decorated readDirectory, stat and readLink handlers.
Effect 4.0.5 migration
This migration uses published Effect 4.0.5 packages. Its crypto requirements remain
Crypto.Crypto, supplied by the matching Node or Bun crypto layer. Crypto provider
failures are defects; filesystem, storage I/O and protocol failures retain their domain errors.
The unreleased SecureRandom and Digest service split is tracked by TODOs at the capture points.
Device, inode and link-count metadata now use bigint values. Keep these values as bigints, including when grouping hard links. Positioned reads and readAlloc leave the sequential cursor unchanged. Opening with noFollow rejects the final symlink while following symlinks in parents. Watch onReady runs after registration can buffer events. Access checks enforce every requested readable and writable permission; access without flags remains an existence check.
The local glob implementation follows the pinned Effect portable algorithm. It matches Unicode characters, accepts absolute and normalized patterns, returns depth-first results, prunes excluded directories before reading them and skips unreadable directories reached through wildcards. Explicitly named unreadable directories still fail. Traversal performs ordinary directory reads, which may update access times under relatime. Snapshot Search retains its bounded contract. The FileSystemTesting glob handler runs once before traversal, and nested reads and stats pass through the decorated primitive handlers.
Effect 4.0.5 does not expose portable Glob, readDirectoryEntries or lstat. The adapter's internal typed-entry helper returns bare names and entry kinds, including dangling symlinks, for local glob traversal. These are internal implementation details, not additional methods promised on Effect's FileSystem service. The local matcher supports the future dot option, but the published service interface does not yet advertise it. TODOs identify when upstream implementations can replace these helpers. No compatibility service or fake upstream module is introduced.