@spec capabilities(t()) :: MapSet.t(capability())

Return the set of capabilities this impl supports.

Capability claims should match observed behavior: for example, a backend without :mkdir should consistently return :erofs or :enotsup from mkdir/3.

@spec exists?(t(), path()) :: {boolean(), t()}

Return whether path exists, plus the possibly cache-updated impl.

Implementations normalize path, check both files and directories, and return the updated impl even for negative lookups so lazy backends can keep metadata caches warm.

@spec materialize(
  t(),
  keyword()
) :: {:ok, t()} | {:error, VFS.Error.t()}

Pre-warm any internal cache. No-op for non-lazy backends. Lazy backends (e.g. partial-clone exgit repos) use this to avoid per-blob round-trips during a subsequent bulk traversal.

@spec mkdir(t(), path(), keyword()) :: {:ok, t()} | {:error, VFS.Error.t()}

Create a directory at path. Options:

• :parents — create missing intermediate directories (mkdir -p)

@spec readdir(t(), path()) ::
  {:ok, Enumerable.t(String.t()), t()} | {:error, VFS.Error.t()}

Return entries directly under directory path — names only, no leading slash, no path separators within names.

Returns an Enumerable.t/0 of strings. Backends with bounded directories should return a list (the simplest Enumerable; length/1 and Enum.sort/1 work natively on it). Backends with paginated or unbounded listings (S3 with many keys, a database-backed store, a virtual /integers/N namespace) should return a Stream. Consumers should treat the result as an Enumerable: use Enum.to_list/1 or Stream.take/2 as appropriate; do not assume length/1 works.

Order: bounded backends should return entries in lexicographic order by convention (matches POSIX, S3 ListObjects). Unbounded backends document their order in the impl's moduledoc.

@spec rm(t(), path(), keyword()) :: {:ok, t()} | {:error, VFS.Error.t()}

Remove path. Options:

• :recursive — remove a directory and all contents (default false). Without :recursive, rm on a directory returns {:error, %VFS.Error{kind: :eisdir}}.

@spec stat(t(), path()) :: {:ok, VFS.Stat.t(), t()} | {:error, VFS.Error.t()}

Return metadata for path.

Success returns %VFS.Stat{} and the updated impl. Failure returns a structured %VFS.Error{}; callers pattern-match on error.kind.

@spec stream_read(t(), path(), keyword()) ::
  {:ok, Enumerable.t(binary()), t()} | {:error, VFS.Error.t()}

Open path for streaming read. Returns an Enumerable.t/0 that emits binary chunks. Options:

• :chunk_size — default 64 * 1024
• :byte_range — {start, length} — start is 0-based, returns up to length bytes starting at start
• :line_range — {first, last} — 1-based, inclusive line numbers; last may be :end to read to EOF

The returned impl reflects state needed to open the stream; cache state populated during enumeration does not escape (see walk/3 caveat).

@spec walk(t(), path(), keyword()) :: Enumerable.t({path(), VFS.Stat.t()})

Lazily walk the tree under root. Returns an Enumerable.t/0 that emits {path, %VFS.Stat{}} tuples. Options:

• :max_depth — :infinity (default) or non-neg integer
• :include_dirs — emit directory entries themselves (default false)

Returns a bare Enumerable.t/0, not a {:ok, _, t} tuple. Cache state populated during enumeration does not escape; call materialize/2 first for agent loops that re-touch files after a walk.

Default-implementation traversal is depth-first and fully lazy: Stream.take/2 halts the traversal as soon as the consumer has enough, including over backends whose readdir/2 returns an unbounded Enumerable.t/0 (paginated S3 listings, virtual /integers/N-style namespaces, database cursors). The default walker pulls one entry at a time from each directory's readdir output.

When the mount table contains overlapping mounts, walk respects longest-prefix shadowing — paths reachable only through a shadowed prefix are not yielded, matching read_file/2's point-lookup behavior.

@spec write_file(t(), path(), binary(), keyword()) ::
  {:ok, t()} | {:error, VFS.Error.t()}

Write content to path.

Success returns the updated impl. Read-only wrappers should return :erofs; backends that fundamentally cannot write should return :enotsup. Options are reserved for future use.