feat(filesystem): copy-on-write Overlay for sound, preview-gated filesystem effects

[ivarvong]

Summary

• Pyex.Filesystem.Overlay — the filesystem counterpart to Pyex.Storage.Overlay (feat(storage): copy-on-write Overlay backend for sound, preview-gated effects #138): a VFS.Mountable decorator with lower/upper layers and map-as-set whiteouts. Reads check upper first, fall through to lower; writes/mkdir land in upper; rm records a whiteout instead of touching lower. diff/1 reports %{added, modified, deleted}; commit/1 applies the diff onto lower (deletes first, then writes).
• A StreamData differential property test (test/pyex/filesystem/overlay_test.exs) generates random write/mkdir/rm/rm -r sequences and asserts the overlay, staged then committed, is byte-for-byte identical to applying the same sequence directly — per-op (does each operation succeed/fail identically?) and on final committed state (does a full walk of the tree match?). It found three real bugs in the implementation that 3 hand-written example tests had missed, within the first ~40 generated runs:
  1. mkdir/write_file delegated straight to upper, which doesn't have the ancestor chain when a directory only exists (implicitly or explicitly) in lower — mkdir("/keep/c") failed :enoent even though /keep is clearly a directory in the merged view.
  2. write_file/mkdir cleared the whiteout at the exact path they touched — unnecessary for read correctness (every read already checks upper first), but wrong for commit/1: recreating a path as a different type than it had in lower left the old entry un-deleted, silently swallowed by an :eexist at commit.
  3. lower-only implicit directories (VFS.Memory's model — the same model a real S3 prefix follows: a directory exists only because it has descendants) stayed "visible" through the overlay even after every descendant was staged as removed, because lower.stat alone has no idea what the overlay staged on top of it.
  4. Fixing (1) by forcing parents: true on the underlying upper call had its own side effect: VFS.Memory's parents: true permanently materializes every intermediate ancestor as an explicit directory, which then outlives removal of the original leaf and gets spuriously recreated at commit. Added explicit_dirs bookkeeping so commit/1 only recreates directories the caller genuinely targeted.
• Two coverage gaps the hand-written tests never touched: materialize/2 (via a small addition to the existing test/support/counting_fs.ex fixture + new tests in vfs_threading_test.exs, mirroring that file's established threading-proof pattern) and walk/3 — the VFS.Skeleton-composed default, which neither diff/1 nor commit/1 ever calls on the overlay itself (only on upper alone), so a direct test was the only way to prove it dispatches correctly through this module's own stat/readdir.

Why this exists / where it came from

vfs's own SPEC.md documents this exact pattern ("CoW overlay — the agent staging pattern") but deliberately ships it as a worked example, not a stock impl — the promotion criterion the spec names is real usage across consumers. This lands it in pyex first, under pyex's test suite and dual-version (1.19/1.20) Dialyzer, before it's a candidate for promotion upstream.

Dialyzer note

Two spots needed the same "avoid opaque MapSet friction" treatment already used in Pyex.Storage.Overlay, one level further than a struct field:

• whiteouts and explicit_dirs are maps-as-sets (not MapSet) in the struct — same fix as Storage.Overlay.deletes.
• capabilities/1 can't dynamically derive from Mountable.capabilities(upper) — any op combining a protocol-dispatched MapSet with a fresh one triggered call_without_opaque on 1.20 locally. Fixed by returning a static {:read, :write, :mkdir}, mirroring VFS.Memory's own static (zero-friction) capabilities/1.

Local Dialyzer (1.20.0-rc.3) is clean. Per the project's own caution, this doesn't prove clean on CI's 1.19 — watching CI to confirm.

Test plan

• mix format --check-formatted
• mix compile --warnings-as-errors
• mix test — 6193 tests, 303 properties, 0 failures
• The new differential property test additionally stress-run at 2000 iterations across 16 different random seeds (32,000+ generated op sequences) with zero failures, beyond the max_runs: 100 committed for CI
• mix dialyzer — clean locally (1.20.0-rc.3)
• CI green on 1.19/1.20 (watching after push)

🤖 Generated with Claude Code

https://claude.ai/code/session_019NokzcR7BiAigPgC78zpk9