@spec walk(VFS.Mountable.t(), VFS.Mountable.path(), keyword()) :: Enumerable.t()

Default walk/3 — lazy, depth-first traversal composed from stat/2 and readdir/2. Returns a Stream of {path, %VFS.Stat{}} tuples.

Options:

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

Laziness contract

The traversal is fully lazy: Stream.take/2 halts as soon as the consumer has enough, and the underlying readdir/2 is consumed one entry at a time. This means:

• Unbounded directories work. A backend whose readdir/2 returns a Stream of arbitrary length (e.g. a paginated S3 lister, a virtual /integers/N namespace) composes correctly with walk |> Stream.take(N) — only the first N entries' worth of directory work is performed.
• Deep trees work. The traversal is recursive but each recursion produces a Stream, so an infinite-depth tree is bounded by what the consumer takes.

Errors

Errors during traversal (e.g. a readdir that fails because the directory was deleted between calls) are silent — the offending subtree is skipped and walk continues. Callers needing strict error surfacing should stat the root first or compose their own walk.

Cache state populated during enumeration does not escape — see the cache-eviction caveat in VFS.Mountable.