Charting a Path for Julia

Most ecosystems converge on a dedicated path type (or at least a dedicated vocabulary surface) to prevent accidental mixing of "text" and "namespace locations", and to concentrate path semantics in one place. Even where paths remain strings (notably .NET and Node), there is a strong push toward path-specific APIs (Path.Combine, path.join) and "path-like" protocols to reduce ad-hoc string manipulation.

A consistent boundary appears between lexical path operations (join, split, parent, extension, normalization) and effectual filesystem interaction. Some systems enforce this boundary by design (Rust keeps Path inert; filesystem operations live in std::fs), while others expose it through naming/API placement (C++17's lexical functions vs canonical, Python's "pure" vs "concrete" classes). The important lesson is to avoid implying that lexical rewriting is equivalent to semantic resolution, especially in the presence of symlinks.

Where explicit "handles" exist (file descriptors, streams, FileHandle, ports), they are treated as the authoritative reference to a resource and the place where permissions/capabilities naturally attach. Paths do not become handles through "resolution"; instead, opening a path yields a handle, and path canonicalisation (realpath/canonical/resolve) typically yields only another path value.

Path models differ most in how faithfully they represent platform reality. Rust and Racket emphasise round-tripping arbitrary OS paths (including non-UTF8) via OS-string/byte representations, making string conversion fallible. Python and many high-level models assume Unicode strings but still acknowledge platform-specific semantics (POSIX vs Windows path rules). A robust design must be explicit about what is representable, and what conversions are lossy or fail.

Successful path APIs provide a compact, predictable core (join/parent/basename/extension/absolute/relative, segment iteration) plus a small set of high-leverage conveniences (with_extension, with_name, suffixes, strip_prefix, ancestors). This reduces bespoke string parsing and yields consistent behaviour across the ecosystem.

Most mainstream standard libraries interpret paths in an ambient OS namespace (current working directory, mounted filesystems, process view). Where alternative contexts are needed, ecosystems either (a) provide explicit context objects (Java NIO.2 FileSystem, Go's fs.FS), or (b) introduce capability-flavoured directory handles as the root of resolution (WASI, cap-std, Zig's Dir). Even if not adopted everywhere, making "context" representable as a value enables sandboxing, testability, and predictable semantics for non-local backends.

• Treat paths as structured names with a coherent API; avoid "strings plus conventions" wherever possible.
• Keep lexical manipulation separate from effectual filesystem interaction; do not conflate canonicalisation with handle acquisition.
• Make handles the unit of authority and the primary return type of "open"-style operations.
• Be explicit about platform semantics and encoding/round-tripping guarantees.
• Provide a small core of primitives and a curated set of composable convenience transforms.
• Keep ambient OS behaviour as the ergonomic default, while ensuring the design leaves room for explicit context/capability patterns where needed.

Many successful designs make the filesystem itself the injectable boundary: you pass an FS/FileSystem/afero.Fs/llvm::vfs::FileSystem value into code, and all operations go through that object. This centralises backend choice, credentials/configuration, and view-construction, and avoids hard-wiring the ambient OS namespace into libraries.

There's a recurring split between:

Minimal, capability-friendly cores

for example, Go io/fs's Open + optional extensions, which maximise implementability and composability, and

Broad, os-shaped interfaces

(Afero) that better support real applications (writes, renames, permissions) but are harder to implement consistently across heterogeneous backends.

This suggests a "small core + layered extensions" approach scales best.

Even sophisticated VFS systems frequently keep pathnames as strings (Go io/fs, Afero, LLVM VFS, Linux syscalls, WASI path parameters). The safety and clarity then comes from (a) a strict path-name contract (Go), (b) scheme-in-string dispatch (fsspec), or (c) forcing resolution to be relative to explicit context/handles (WASI, openat-style APIs). A first-class Path value type is comparatively rare in VFS layers; it usually lives at the language level, not the VFS layer.

Powerful VFS designs tend to support composition :

• overlays/stacks (LLVM's OverlayFileSystem, Afero's CopyOnWriteFs )
• rooted/sub views (Go's fs.Sub, os.DirFS, Afero's BasePathFs )
• redirection/mapping (LLVM redirecting FS; fsspec protocol routing)

These primitives solve many practical problems (testing, reproducible builds, generated files, sandboxed plugins) without bespoke ad-hoc hooks.

Across OS-level and capability-flavoured designs, the most stable conceptual split is:

• name lookup/resolution, which are effectual/stateful, and may depend on mounts/symlinks/caches, producing
• handles, in the form of file descriptors, fs.File, vfs::File , file-like objects as the authority-bearing resource reference.

Some VFS approaches treat sandboxing as an emergent pattern (pass a rooted FS object; don't call the ambient one), while others make it the default (WASI: only pre-opened directory capabilities; descriptor-relative operations; absolute paths disallowed). The lesson is that capability-oriented designs work best when the API shape forces context/authority to be explicit (directory-handle-centric *at operations), rather than relying on convention.

When VFS spans non-POSIX backends (object stores, HTTP, archives), "filesystem-like" operations have unavoidable semantic differences (directories, atomicity, consistency, metadata fidelity). Systems either:

• embrace a "common denominator" contract (Go io/fs read-only, strict names), or
• provide a wide API but accept backend-specific sharp edges (Afero, fsspec).

A robust design should assume semantics are backend-dependent and avoid implying POSIX invariants unless guaranteed.

• Make filesystem context substitutable and injectable; avoid baking "the OS filesystem" into library code.
• Prefer a small core interface with optional extensions; keep richer surfaces layered.
• Treat resolution as effectual lookup that yields handles/metadata, not "better paths".
• Provide composition primitives (rooting/sub, overlay, redirection) as first-class building blocks.
• If capability/sandboxing matters, encode it in the API shape (handle-relative operations), not just documentation.
• Be explicit about semantic guarantees; don't pretend disparate backends share POSIX behaviour.

Pathlib separates out purely conceptual and filesystem-grounded paths as pure and concrete paths.

Operating on pure paths does not involve any interaction with the filesystem, while concrete paths check for symlinks, resolve symlinks, and verify various path operations using the filesystem. This also makes the transition from operating on the path to interacting with the filesystem explicit. Note that this is not true path "resolution" in the sense that concrete paths are still string based, instead of obtaining a resource handle.

Pathlib provides per-platform path classes, and aliases Path/PurePath based on the current platform. This preserves OS-specific semantics (drives/UNC, separators, etc.), and allows for working with non-native paths when needed, without forcing all callers to write per-platform code.

PEP 428 explicitly decides against deriving paths from str to avoid silent misuse.

PEP 519 creates a path protocol (os.PathLike / __fspath__) so that "path objects" can be accepted across the stdlib. Path objects can be demoted to str/bytes for legacy APIs, while constructors can promote strings into path objects.

The Pathlib API provides the basics (parent, parts, joinpath, home), and also a decent collection of utilities on top:

• suffix
• suffixes
• stem
• with_name
• with_stem
• with_suffix
• with_segments
• from_uri
• as_uri

Currently Julia covers the basics, but could probably do with some more convenience functions.

Convenience and separation

while having path manipulation and filesystem interaction methods all with the same class would be convenient, it is seen as more important to split the two, and provide Path/PurePath aliases to make the split more manageable.

Single ambient filesystem context

the host OS is always implicit

No capability model

there's no concept of authority, or restricted namespaces; access control is left to each calling context

Paths store the "pathname" in the native format, but allow viewing the path in a generic (POSIX) format too. There are explicit functions to go between the two forms.

Lexical operations (e.g. normalisation, relative path construction) are supported with a separate API from filesystem interaction (canonical / weakly_canonical).

Most effectual operations come in two forms: a exception throwing form, and a overloads with std::error_code& that report failures out-of-band.

Lexical purity vs. meaningful normalisation

having both lexical and filesystem operations operate on the same type is convenient, but introduces a softer separation of intent, and means that knowledge about whether a path refers to a real filesystem resource or not must be thought about and managed by the programmer.

Interoperative convenience vs. sharp edges

implicit convertibility to/from std::basic_string makes adoption easy and incremental, but also blur intent and creates more opportunities for surprises in cross-platform code.

No capability model

the approach is only concerned with modelling path names/transformations, and not the use of paths.

Single ambient filesystem context

there's no mechanism (or room to insert one) for different kinds of filesystems. Libraries must create parallel APIs.

Rust models paths like strings: Path is a borrowed view used pervasively in APIs, while PathBuf is an owned, mutable buffer for constructing and editing paths efficiently (push, pop, set_extension, etc.). This makes path-heavy code ergonomic without forcing allocations at every boundary.

Path/PathBuf are thin wrappers over OsStr/OsString, so they can represent platform-native paths that are not valid Unicode text. Conversions to &str are therefore fallible/optional, which forces callers to confront encoding rather than silently corrupting or rejecting valid OS paths.

The standard API covers the common "shape of a pathname" operations: iteration by components, file_name / file_stem / extension, parent, prefix/suffix tests, strip_prefix, joining, and targeted edits (with_extension, with_file_name, plus mutable PathBuf setters). It is deliberately narrower than pathlib's high-level conveniences (no standard home()/tilde expansion, globbing, recursive walking, etc.), which are see-as-needed in ecosystem crates.

Rust keeps path values largely inert: opening a file, reading metadata, canonicalising, iterating directories, etc. is primarily done via std::fs free functions or types. This makes "touches the filesystem" sites stand out in code, and ensures handles are explicit (std::fs::File being the canonical OS-backed handle wrapper).

Most filesystem APIs accept P: AsRef<Path>, allowing callers to pass &Path, PathBuf, &str, String, and other path-like inputs without a bespoke path-protocol mechanism. This makes adoption incremental while still standardising the "real" path vocabulary type at API boundaries.

Ergonomics vs purity

keeping most effects in std::fs sharpens the "names vs resources" distinction, but also means fewer "one object does everything" conveniences compared with pathlib.

Correctness vs string convenience

non-Unicode-capable paths reduce footguns on real systems, but push more code toward OsStr/OsString-aware manipulation when doing text-like operations.

Single ambient filesystem context

std assumes the host OS filesystem; multiple filesystem instances and VFS composition are not standardised in the core API.

No capability model in std

capability-oriented directory handles and sandbox-friendly "at-style" patterns are left to crates (notably outside std).

Filesystem procedures generally accept either a string or a path value, promoting strings via string->path, while procedures that produce filesystem paths return path values. This keeps "path-as-name" visible in values without forcing an all-at-once ecosystem migration away from strings.

Paths round-trip through byte strings more faithfully than through Unicode strings: path->string decodes using the platform's conventions and is explicitly documented as unsuitable for lossless "convert to string, tweak, convert back" workflows. This is a concrete example of separating display text from filesystem name representation.

Racket tracks a path's convention ("kind") and makes many non-effectual procedures sensitive to that kind. Construction from bytes supports an explicit 'unix/'windows convention, enabling manipulation of (say) Windows paths on Unix when no filesystem access is required.

Racket distinguishes several tiers of "make this path nicer":

Cleansing

many primitives cleanse inputs (e.g. redundant separators) before use; cleanse-path is explicitly non-effectual.

Filesystem-aware adjustment

resolve-path can dereference a single soft link, and simplify-path defaults to use-filesystem? = #t, potentially consulting the filesystem and accounting for soft links when eliminating .. to preserve referential meaning.

Pure mode

simplify-path with #f performs syntactic simplification without filesystem access (and can operate on paths for any platform).

Racket's I/O APIs return ports (e.g. open-input-file) which are the capability-bearing handles used for reading/writing; paths remain names that are interpreted during the open. Ports are backed by OS-level descriptors underneath.

The API includes primitives designed to avoid allocation patterns that arise from repeated splitting. For example, explode-path is documented to run in time proportional to the path length, unlike iterative split-path usage that allocates intermediate paths.

Interoperability convenience vs. strictness

accepting both strings and path values keeps APIs ergonomic, but weakens the type-level separation between "text" and "path name" compared to designs that require explicit promotion everywhere.

Convenient defaults vs. explicit context

some "pure" utilities still consult ambient process state (e.g. current-directory as a default base), which is pragmatic but less explicit than a fully capability-oriented model.

Ambient filesystem context

paths do not carry an explicit filesystem object/context; operations are fundamentally anchored to the host OS filesystem semantics.

No first-class capability model for namespace restriction

while ports are handles, there is no standard "directory capability" pattern (à la openat-style APIs) that makes authority over a subtree explicit in function signatures.

Common Lisp already has a first-class pathname object (with components like host/device/directory/name/type/version), and namestring is an implementation-defined textual rendering of a pathname. filepaths builds on this existing substrate rather than introducing a new path type.

filepaths explicitly focuses on structural/lexical operations (joins, component access, extension manipulation, structure tests) and avoids filesystem queries such as existence checks. This gives a sharp "names, not resources" boundary.

The library centers a set of operations that look very similar to what developers expect from newer path APIs: join, parent, with-name, with-parent, extension/with-extension/add-extension/drop-extension, and component conversion (components, from-list).

Nearly every function accepts either a pathname or a string, and provides explicit "ensure"/conversion helpers (ensure-path, ensure-string, to-string, from-string) to normalize inputs/outputs. This is a pragmatic interoperability story in a Lisp ecosystem where APIs frequently accept "pathname designators".

For cases where nil is ambiguous, it signals dedicated conditions (e.g. empty-path, no-filename, root-no-parent), which aligns with CL's condition system for recoverable errors.

Interoperative convenience vs. type clarity

accepting both strings and path objects makes adoption easy, but allows "stringly-path" to remain pervasive, weakening the signaling value of path-typed APIs.

Leverages CL pathnames vs. inherited complexity

reusing pathname avoids ecosystem fragmentation, but also inherits long-standing complexity/quirks of CL pathname semantics and conversions.

Not a filesystem abstraction

there is no VFS concept, no filesystem context object, and no capability/authority model—only lexical pathname manipulation.

Portability of textual syntax is constrained by CL

because namestring syntax is implementation-dependent (outside of logical pathnames), any string-based portability story depends on the underlying implementation's parsing/rendering choices.

The model starts with a set of absolute roots \(A\), relative components \(R\), and a pathjoin operator ⋅ such that relative paths form a free monoid (\(R^*\)) and (\(R^*\)) acts faithfully on absolute roots, generating absolute paths (\(A^*\)). This aims to capture "paths as names" with as few primitives as possible, while still deriving most common operations.

I think that paths actually best fit an ordered monoid, since there's a sensible partial order.

The framework explicitly allows multiple absolute roots (e.g. POSIX "/" vs Windows drive roots and other namespaces), and notes that "zero absolute roots" is theoretically possible but makes evaluation ill-defined for "absolute" lookup.

Given the core structure, the post derives familiar operations---parentdir and basename (tail/head), and then root, depth, parts, and within (a restricted "relative" that only works when one path is nested within the other). The emphasis is that these are lexical and don't require touching the backing system.

Resolution is modeled as an evaluation function (e: \(A^* \to \mathcal{P}(D)\)), mapping an absolute path name to a set of domain objects (to accommodate aliases, links, globs, XPath, etc.). The post distinguishes "MonoPath" schemas (0/1 object, like typical filesystem paths) from "MultiPath" schemas (0/many, like globs/XPath).

A key design lesson is that treating .. as an ordinary relative component breaks the free-monoid structure; instead the post introduces a special element (ϕ) defined via evaluation (intuitively, "append ϕ then evaluate equals evaluating the parent"). It then argues that POSIX .. semantics are not purely lexical in the presence of symlinks, motivating designs that avoid collapsing .. without filesystem access (and noting that some systems ban it outright).

A normalization function norm is defined to remove ϕ where possible without changing evaluation, and relative_to(x,y) is defined using a common-prefix computation plus the necessary number of ϕ "up-steps". The post explicitly notes that proofs of the normalization/equivalence properties are non-trivial and not completed there.

Two extensions are sketched: (1) "canonical name" schemas where evaluation is injective (one object ↔ one name), and (2) splitting file paths vs directory paths to restrict which joins are permitted—at the cost of losing a simple monoid over all relative paths (while preserving a free monoid for directory-relative paths).

• The high level of generality (covering URLs/XPath/globs/filesystems uniformly) clarifies what is fundamental versus conventional, but it can be too abstract to settle concrete API questions without additional constraints.
• Introducing ϕ enables familiar operations like relative_to, but it forces a careful split between lexical structure and effectual semantics—highlighting exactly where "stringy" normalization becomes unsound.

• This is a theoretical specification rather than an implementation guide; many operational details (errors, permissions, encodings, etc.) are out of scope.
• ϕ/.. cannot be made fully POSIX-faithful without consulting the filesystem (symlink interaction), and some schemas (notably multipaths like globs) may not admit any ϕ-like element at all.
• The "evaluation" function models name → object(s), but does not model handles/capabilities; it stops at identifying resources rather than representing authority to operate on them.

Rather than a dedicated path value type, Zig centralises path manipulation as functions that operate on []const u8 and expose platform-specific constants (e.g. directory separator and PATH-list delimiter).

Filesystem operations are intended to be performed relative to a Dir handle (an OS-backed resource), which can reduce TOCTOU hazards and makes "what subtree do we have authority over?" more explicit in APIs and call graphs. The presence of *Absolute convenience functions is increasingly treated as legacy/avoidable, since many are thin wrappers over cwd().* calls.

Many APIs accept []const u8, but Windows-specific variants exist that take wide strings (WTF-16), reflecting the platform's native calling conventions and making encoding/interoperability concerns explicit at the API boundary.

Simplicity and performance

treating paths as slices avoids object overhead and keeps path manipulation lightweight, but provides less structural guidance than a dedicated Path type.

Handle-first ergonomics

Dir-relative operations sharpen authority and robustness, but can feel heavier for simple scripts and push more users toward "plumbing" directory handles through APIs.

Platform realism

exposing wide-string Windows variants improves correctness/interoperability, but increases surface area and multiplies "which encoding do I use?" decisions.

Single ambient filesystem context

cwd() is the default anchor for many operations, and the model assumes the host OS filesystem semantics as the baseline context.

No datatype distinction between paths and strings

paths remain names (byte sequences); "handle-ness" only appears once a Dir/File is opened.

path operates over strings and returns strings. In fs, string paths are interpreted as UTF-8 sequences naming absolute/relative filenames, and relative paths are resolved against process.cwd(). Many fs APIs also accept Buffer and (for file:) WHATWG URL objects, which makes interoperability convenient but keeps the "path as text" boundary relatively soft.

The default path behavior follows the host platform, while path.posix and path.win32 provide explicit access to the other platform's parsing/joining rules. This allows cross-platform manipulation without changing the underlying representation (still strings).

Resource access is mediated by OS-backed handles: the promises API exposes a FileHandle object with explicit close(), while other APIs expose numeric file descriptors. This matches the "handle is authority" story operationally, even though it is not reflected in a capability-oriented path resolution model (paths remain globally interpretable strings).

Node's path functions are purely lexical; canonicalization and symlink resolution live in fs (e.g. realpath). This preserves a practical "names vs effects" separation, but with no distinct type-level boundary between lexical and resolved forms.

Simplicity and interoperability

strings keep the surface area small and integrate naturally with the JS ecosystem, but do not prevent accidental mixing of "text" and "path".

Cross-platform control vs ergonomics

explicit path.posix/path.win32 enables portable tooling, but correctness remains a caller responsibility because everything is still representationally a string.

Flexible inputs vs clarity

accepting Buffer/URL is pragmatic, but further blurs the conceptual model (multiple "path-like" carriers with different invariants).

Single ambient filesystem context

fs operations implicitly target the process-visible OS filesystem, with relative paths interpreted via process.cwd().

No capability model

while handles exist (FileHandle/fd), the dominant API surface remains ambient (global path resolution rather than resolution relative to an explicit directory capability).

No first-class path value

the model cannot leverage types to encode invariants (absolute vs relative, platform flavour, lexical vs canonical) beyond convention and runtime checks.

System.IO.Path is a "path algebra" of string-in/string-out helpers (join, split, query), while filesystem effects live in other types. This keeps naming operations distinct at the API level, but does not create a first-class path value type.

Path.Combine follows OS-like semantics: if any argument after the first is rooted, earlier components are discarded. Path.Join concatenates more mechanically (preserving duplicate separators), with normalization typically deferred to GetFullPath.

Path.GetFullPath resolves relative inputs using ambient process state (current directory; and, on Windows, drive-relative conventions). A base-path overload exists to avoid depending on ambient state when determinism matters.

The canonical "resource handle" is a stream (e.g. FileStream), and modern .NET also exposes File.OpenHandle returning a SafeFileHandle directly, making the "name → handle" boundary explicit when desired.

While System.IO itself is OS-filesystem-oriented, .NET includes other, scoped abstractions for non-physical or restricted views—most notably ASP.NET Core's IFileProvider (with physical, embedded, and composite providers). This is not the general-purpose System.IO model, and is intentionally narrower in scope.

Stringly paths

maximizes interoperability and keeps the core surface small, but conflates text with namespace locations and limits type-driven correctness and dispatch.

Convenient OS-like joins

Combine's rooted-path rule is pragmatic, but can produce surprising results if rootedness appears unexpectedly in inputs.

Exceptions as the primary error channel

simplifies common-case use, but makes "probe" patterns more awkward than explicit error-valued returns.

No first-class path value type in the BCL

path semantics remain "strings with conventions", despite a rich helper API.

No first-class filesystem-context object in System.IO

there is no standard FileSystem value you pass around to select a backend or restrict authority; alternate filesystem views are provided via separate subsystems (e.g. IFileProvider) rather than integrated into the core path+fs model.

A central design choice is making paths distinct from strings, rather than a string subtype. This forces explicit conversions at boundaries and reduces accidental misuse (e.g. treating text as a filesystem name or vice-versa). The package also preserves * for string concatenation and uses / for path joining.

FilePathsBase provides separate path types for differing platform semantics (POSIX vs Windows) and a "system" default intended to match the running platform, analogous to other ecosystems' platform-dispatched path aliases.

Paths are modelled as structured values (conceptually segments plus platform rules). The docs define an interface for implementing new AbstractPath subtypes, including operations to access components and to support common filesystem behaviours. This interface is intended to allow alternate path kinds beyond the local OS, even if the default types map to the ambient host filesystem.

Rather than introducing a new filesystem context object, the package primarily integrates by extending existing Base.Filesystem-style operations to accept AbstractPath. This makes the API feel "native" when it's in scope, but relies on broad method coverage and consistent adoption.

Ergonomics vs. "ambient by default"

the default system path types implicitly target the process-visible host filesystem, which is convenient but keeps the core model tied to ambient context.

Operator overloading vs. local surprises

using / for joins is ergonomic, but it must coexist with division and with user expectations about what operators mean in Julia codebases.

External package vs. ecosystem coherence

because this lives outside Base, interoperability depends on adoption and on the completeness of method extensions across Base/stdlibs and third-party packages.

Not a Base-level abstraction

it cannot enforce a ubiquitous "paths are paths" vocabulary across the ecosystem, so friction remains at API boundaries (conversion, missing overloads, mixed conventions).

No explicit capability or filesystem context object

authority and context remain largely implicit (host filesystem, process CWD), rather than being represented as explicit handles/capabilities.

Type instability

using Tuple{Vararg{String}} for segments makes access/modification O(1), but makes any operations that require the full path O(depth) which isn't great.

All path types are required to implement the AbstractTrees.jl interface, so that generic traversal utilities (e.g. walkpath) can be expressed in terms of standard tree algorithms rather than re-implemented per path type. This frames "a path is a node in a namespace tree" as a semantic guarantee, not just a metaphor.

This is complicated by symlinks, which is not addressed in the current design of FilePaths2.jl

FilePaths2 leans on the fact that "complete" paths can be described by strings from a root, and uses a PathSpec wrapper to support purely-parsed operations like determining parents and testing ancestry/antecedence relationships. A key consequence is that path strings used to construct path objects must be absolute, or must refer to an existing resource so the absolute path can be inferred.

Relative paths are treated as a "pun": they depend on ambient global state (e.g. a current directory) which may be ill-defined or nonsensical for remote backends, and they weaken what can be inferred (e.g. parent relationships). Relative forms may still exist as constructors or views, but the path object model aims to be absolute/anchored.

To avoid accidental network traffic and to make the "reasoning footprint" of operations clear, only a small set of functions are permitted to perform remote calls, and these must accept an update keyword (even if update=false can still error when the object lacks enough information). AbstractTrees.children, readdir, walkpath, ispath, isfile, and isdir are listed (with an explicit note the set may be incomplete).

For S3-like systems (key-value stores that "masquerade" as filesystems), the design asks: "what tree can be constructed from only what the API provides?". The proof-of-concept infers tree structure solely from key strings, which yields meaningful definitions for questions like isdir (e.g. "is this a strict ancestor of some leaf?") while acknowledging constraints (e.g. no truly empty directories).

Stronger invariants vs. friction

requiring absolute/anchored paths and restricting inference rules improves semantic clarity (especially for remote backends), but rejects common local patterns (relative paths) and may require more explicit anchoring in user code.

Cost transparency vs. ergonomic opacity

concentrating remote calls in a small set of "update-permitted" functions makes costs auditable, but can surprise users when seemingly simple queries error unless update=true is provided.

Tree-first abstraction vs. backend mismatch

forcing a tree model onto S3 enables generic tooling, but necessarily bakes in approximations (e.g. "directories" inferred from key prefixes) that are not native to the store.

• Incomplete: the project is a prototype, not a complete alternative to FilePathsBase.jl

A Path is not just syntax; it is associated with a specific FileSystem (via Path.getFileSystem()), and path operations are defined relative to that filesystem's rules. This enables multiple coexisting filesystem namespaces in one process without needing a "scheme-in-string" convention.

NIO.2 standardizes a provider model (FileSystemProvider) so new filesystems can be registered and constructed (commonly via URIs and environment maps). This is the key VFS "insertion point": alternate backends can provide their own Path and FileSystem implementations while reusing the same surface API.

The dominant pattern is: Path represents names; effectual operations live in Files and in opened handles (streams/channels). Even "real path" operations like toRealPath are effectual but still return a Path (a canonical name), not a resource handle.

The ZIP filesystem provider demonstrates the model end-to-end: each zip/JAR is a distinct FileSystem, and you operate inside it with ordinary Path and Files calls (copy, move, attributes), with provider-specific configuration carried via the environment map.

Java includes SecureDirectoryStream , which supports directory-relative operations designed to reduce TOCTOU races (an "openat-like" capability pattern), but most everyday APIs still center the ambient default filesystem and directory.

Ambient defaults remain central

Path.of(...) / Paths.get(...) and many idioms assume the default filesystem and process-wide working directory, so the "explicit FS" model is often bypassed in typical code.

Semantics leak across providers

cross-filesystem operations exist, but metadata, atomicity, link handling, and permission models can vary by provider, so portability can require extra care beyond just using Path .

Power vs. complexity

the SPI enables serious extensibility (archives, custom backends), but introduces lifecycle concerns (FileSystem can be Closeable) and a larger conceptual surface area than "OS filesystem only".

"Path carries context" vs. ergonomic ambient usage

binding Path to FileSystem is a clean model for multiple backends, but the ecosystem still needs strong conventions to avoid silently falling back to the default filesystem when a capability/context-driven style is desired.

The main ergonomic trick is that filesystem choice is often encoded in the string via a protocol (e.g. s3://…, gcs://…), and fsspec uses a registry to map protocol → filesystem implementation, so callers can stay backend-agnostic. This makes it easy for libraries to accept "a path" and let fsspec pick the right backend.

Rather than having a structured Path object carry context, fsspec typically places context on the filesystem instance: credentials, configuration, caching policy, async settings, etc. This makes the FS object the natural injection point for testability and "restricted views" (by handing out a preconfigured FS instance).

High-level entrypoints like fsspec.open / open_files produce an OpenFile wrapper where the actual low-level file object is created only when entering a context manager. This supports serialization/distribution patterns (common in distributed compute) without holding live connections in the object being passed around.

At its core, fsspec defines an abstract filesystem base (AbstractFileSystem) and expects implementations to provide a coherent set of file and directory operations. Beyond the core, it adds higher-level conveniences (globbing, mapping interfaces, caching layers, wrappers such as compression/text-mode handling) that can be applied across many backends.

Stringly-typed names

paths are usually plain strings/URIs rather than structured path values, so lexical path manipulation and cross-platform semantics largely remain conventions or backend-specific behaviour.

Semantic variance across backends

a uniform API can mask important differences (e.g. "directories" on object stores, eventual consistency, atomicity guarantees), so correctness sometimes requires backend knowledge.

No built-in capability model

while passing filesystem objects can approximate contextual restriction, the design does not make "authority" an explicit, typed part of the interface in the way WASI/cap-std style APIs do.

Very low adoption barrier vs. weaker invariants

scheme-based dispatch + duck-typed file-like objects makes integration easy for the ecosystem, but gives up the stronger guarantees a first-class Path value type and explicit resolution model can provide.

One surface API vs. leaky abstraction

fsspec succeeds by making diverse storage look "filesystem-ish", but the more "non-filesystem" a backend is, the more likely users encounter surprising edge cases that the API cannot fully abstract away.

fs.FS is intentionally just Open(name) (fs.File, error) , with optional extension interfaces (ReadFileFS, ReadDirFS, StatFS , etc.) that consumers can detect for more efficient implementations. The result is a low barrier to implementing a filesystem backend, while still allowing richer behaviour when available.

Unlike OS-native paths, io/fs path names are defined to be unrooted, UTF-8, slash-separated, and to forbid .., ., empty elements, and leading/trailing slashes (except "." as the root). This standardises traversal semantics across platforms and backends, and makes consumers simpler and more predictable.

os.DirFS(dir) produces an fs.FS rooted at a directory, letting libraries accept "a filesystem" rather than reaching for ambient OS state. This is a practical, lightweight step toward capability-style design (authority comes from which FS value you were given), even though it's not a full security boundary by default.

fs.Sub(fsys, dir) derives a subtree view. If the backend supports SubFS, it can implement this efficiently; otherwise fs.Sub provides a wrapper that rewrites names by prefixing dir . This encourages layering (e.g., "rooted view", "overlay view") without requiring a large inheritance hierarchy.

Go 1.16 explicitly positioned io/fs as a shared boundary: producers include embed.FS, zip.Reader, and os.DirFS; consumers include http.FS and ParseFS for templates. That standard-library buy-in is a large part of why the abstraction is widely usable.

Read-only core

the central abstraction does not model mutation (create/write/rename), so write-capable VFS designs need additional interfaces or a parallel API surface.

Stringly path names

the interface standardises name syntax, but doesn't introduce a first-class path value type; correctness relies on conventions plus fs.ValidPath .

Not automatically a sandbox

os.DirFS explicitly warns it is not a chroot-style security mechanism (symlinks can escape), and even the meaning of a relative DirFS("prefix") can be affected by later Chdir .

Portability vs expressiveness

forbidding rooted paths and .. makes traversal safer and backend-neutral, but diverges from "native path" expectations and pushes some concerns to adapters at the boundary.

Minimalism vs completeness

the tiny Open-only core made adoption easy (lots of implementers), but leaves substantial surface area (writing, atomic renames, permissions, links) outside the unifying abstraction.

The central move is to pass an afero.Fs into application/library code instead of calling os.* directly, so the caller controls the backing store (OS in production; MemMapFs in tests; wrappers in sandboxes).

Afero intentionally mirrors the standard os surface, aiming for incremental adoption and broad coverage of common filesystem mutations (create/write/rename/remove), not just read-only access.

Afero leans hard into wrapping and layering filesystems to construct behaviour: CopyOnWriteFs for overlays, CacheOnReadFs for read caching, BasePathFs for subtree restriction, plus ReadOnlyFs and other helpers.

Afero positions itself as complementary to Go's io/fs: you can wrap Afero backends to satisfy fs.FS (e.g. via afero.NewIOFS), and generally use io/fs where you only need read-only standard-library semantics.

Stringly "paths"

call sites still pass string names; Afero doesn't introduce a structured path value type, so lexical/path semantics remain the caller's responsibility (and may differ across backends).

Library-level confinement

wrappers like BasePathFs provide a "jail" within the abstraction, but don't prevent code from bypassing the model by calling os.* directly (so this is not an enforcement mechanism by itself).

Backend fidelity varies

many "non-POSIX" backends exist (cloud/streaming/etc.) and may not support the full set of POSIX-ish expectations (permissions, seeking, listings, etc.) uniformly.

Broad interface vs implementability

compared to io/fs 's deliberately minimal surface, Afero's richer, mutable API is more demanding for backend implementers — but is the reason it supports write-heavy apps, richer tests, and layered behaviours.

Powerful composition vs semantic sharp edges

overlay/caching layers are extremely useful, but can blur or distort semantics (e.g., error modes, metadata, atomicity) relative to a single "real" filesystem, especially across heterogeneous backends.

llvm::vfs::FileSystem is an abstract interface representing a namespace plus resolution rules (status, directory iteration, opening files). This makes the filesystem the unit of substitution (real FS vs overlays vs in-memory), rather than trying to encode "which filesystem?" into the path value itself.

The VFS API treats "paths" as names (string parameters), with explicit, effectual operations producing either metadata (Status) or resource handles ( vfs::File). The vfs::File object is the authoritative handle for subsequent reads/buffering/close, not the input path.

OverlayFileSystem composes multiple FileSystem instances into a stacked view, allowing higher layers to shadow files/directories from lower layers (a common compiler/tooling need for "overlaying" headers, SDKs, generated files, etc.).

RedirectingFileSystem supports building a VFS from a declarative description (LLVM's VFS overlay YAML format), enabling external tools to describe a logical tree that maps onto one or more physical locations—useful for build systems and reproducible compilation environments.

InMemoryFileSystem offers a fully synthetic implementation for unit tests and tooling pipelines; it can host files from buffers and participate in overlays, letting clients run "as if" a filesystem existed without touching disk.

Operations typically return ErrorOr<T> / std::error_code ­style results rather than exceptions, matching LLVM's broader style and making failure paths explicit at call sites—useful for tooling where "filesystem may be virtual / partial / inconsistent" is expected.

Excellent for toolchains, less "language-level"

treating the filesystem as the substitution point (rather than paths) is extremely effective for compilers and build tooling, but it leaves path correctness/safety largely as a convention rather than something enforced by a first-class Path type

Stringly-typed paths

there is no dedicated path value with enforced invariants; callers can still accidentally mix "text" and "path name", and path parsing/normalisation lives outside the VFS abstraction.

Not a capability model

while passing a FileSystem object is context injection , it does not (by itself) guarantee authority restriction the way directory-handle capability systems do; whether an FS is "sandboxed" depends on the specific implementation provided.

Inside the kernel, walking a pathname produces a resolved location in the mounted namespace, represented as a (dentry, vfsmount) pair ("a path"). The lookup process may need to instantiate dentries along the walk and load the corresponding inodes as needed.

Dentries are RAM-only objects used to cache namespace structure; the dentry cache is intentionally an incomplete, evictable view of the full namespace. Consequently, name resolution is inherently effectual and state-dependent even before you "open" anything.

Once a file is opened, subsequent operations are performed through the handle (file descriptor → kernel struct file) and dispatch through per-object operation tables. This is the VFS's core split: name lookup is one phase; I/O and metadata operations are another.

The meaning of a pathname is defined relative to the process's view of the mount tree: lookup proceeds through mountpoints as it walks components, so "the same string" can denote different resources in different mount namespaces.

Performance vs complexity

aggressive caching (dcache/icache) makes lookups fast, but increases conceptual complexity and makes "resolution" visibly dependent on kernel state.

Generic interface vs uniform semantics

VFS unifies how operations are invoked, but filesystems can still differ in edge semantics (atomicity, metadata fidelity, special files), so higher layers must be cautious about assuming POSIX-uniform behaviour.

Not a user-facing VFS API

this is primarily an internal kernel architecture; user code sees syscalls, not the VFS object model directly.

Stringly pathnames at the boundary

pathnames are still passed as strings to syscalls; the kernel's strong separation doesn't automatically give the language a first-class path value type.

A Plan 9 namespace is not a global OS singleton: processes inherit a namespace, can modify it (mount/bind), and those changes affect only that process (and its children, depending on how they're spawned). This makes the "context in which paths are interpreted" concrete and composable.

In 9P, you don't "resolve a path into a better path string"; you walk from an existing handle (fid) through a list of path segments, producing a new fid bound to the target object (subject to permissions). That fid is the authoritative reference you later open, read, write, and clunk .

Because access is standardized through 9P operations, diverse resources can be surfaced as file trees served by user-space components (editors, networking stacks, IPC services, synthetic /proc-like views, etc.), and then mounted into a process's namespace as needed.

bind can replace, prepend, or append trees, creating union directories where lookups search a list of members and creation semantics are controlled by flags (notably -c). This provides a principled "overlay FS" story at the namespace layer, rather than as a special filesystem feature.

A fid acts like a capability: once you have it, operations are scoped to that object; and crucially, walking is relative to a fid you already possess (e.g., the fid returned by attach). This lines up closely with modern handle-relative APIs (openat , WASI) where authority is mediated by directory handles rather than ambient absolute paths.

Powerful composition vs mental overhead

per-process, user-assembled namespaces enable elegant redirection/overlay/sandbox patterns, but they shift complexity from "global system configuration" into application/runtime composition.

Uniform protocol vs performance/semantics variance

a single file protocol makes extension easy, but remote/fileserver-backed resources can have very different latency and behaviour from local disk, and clients must expect resolution and metadata to be more "distributed-system-like."

Not a language-level path model

Plan 9's core innovation is at the OS/protocol layer; it doesn't, by itself, provide a first-class path value type with lexical operations the way modern language stdlibs do.

Portability/interoperability friction

outside Plan 9 (or plan9port/9P clients), the model doesn't map 1:1 onto mainstream OS APIs without adapters, and semantics can surprise POSIX-native tooling.

Rather than allowing a module to name arbitrary absolute paths, WASI starts execution with a set of directory handles supplied by the host/runtime ("pre-opens"). These handles define the only namespaces the module can traverse via path lookup, and they serve as the natural unit for granting or withholding filesystem authority.

Filesystem operations are largely phrased as methods on a descriptor (file or directory), with " -at" operations accepting a relative path—mirroring POSIX openat / renameat / unlinkat patterns. This keeps "resolution" (name lookup relative to a base) explicit in the call shape and makes it composable for sandboxing.

Path-taking operations are designed to prevent escaping the granted namespace: absolute/rooted paths are not permitted in key operations (and some operations explicitly reject symlink contents that are absolute/rooted). This shifts a large class of "path traversal" risks from application-level string handling into the runtime's enforced resolution logic.

Earlier WASI iterations used a fine-grained "rights" bitmask model; the (archived) wasi-filesystem interface notes moving away from explicit rights and toward a simpler "mode/flags" approach, with access control largely enforced by the host and by the descriptor's mutability constraints. This is a notable trade: simpler, more portable APIs, but less standardized, inspectable authority at the interface level.

Security-first ergonomics

requiring a base directory descriptor (and rejecting absolute paths) improves auditability and sandboxing, but increases friction when porting "ambient POSIX" code that assumes a process-wide current directory and global namespace.

Authority is clear, but coarse at the interface boundary

shifting detailed permissioning into the host/runtime simplifies the spec and implementations, but reduces the degree to which a module can introspect or statically reason about precise granted capabilities beyond "which pre-opens do I have, and are they mutable?".

Host-dependent semantics

the API is primarily intended for "host filesystem" access and does not try to fully normalize away OS differences; some behaviors are explicitly host/filesystem dependent.

String paths rather than structured path values

path parameters are WIT string s (not a first-class structured path type), so the interface doesn't itself provide a path-manipulation model—only resolution and operations.