0.1.0 release prep: 1.16 floor, four contract-bug fixes, hex.pm docs reconciliation

[ivarvong]

Prep for the first Hex release (vfs 0.1.0). The name is confirmed available on hex.pm. Two parts: the floor/config tightening (first three commits), and the must-fix list from a multi-agent release-readiness audit (final commit) — four real contract bugs plus a sweep of every public-facing doc that would have shipped stale to hex.pm.

Lower the Elixir floor to 1.16

• elixir: "~> 1.18" → "~> 1.16". The library code uses no 1.17/1.18-only features (no built-in JSON, Duration, Date.shift, etc.).
• CI gains a real floor lane: Elixir 1.16.3 / OTP 26.2 (1.16 predates OTP 27), alongside 1.18, 1.20-rc, and the consolidation lane.

Tighten mix config

• Removed application/0 — its extra_applications: [:logger] was dead config; Logger is never used and telemetry auto-starts as a dependency.
• consolidate_protocols now reads VFS_CONSOLIDATE_PROTOCOLS — CI set that env var but mix.exs ignored it, so the "consolidate=true" lane tested nothing.
• Removed elixirc_options: [warnings_as_errors: true] — redundant with the check alias and risky for consumers. CI still enforces zero-warnings via mix check.
• Moved mix vfs.audit / mix vfs.mutate out of the package (lib/mix/tasks/ → dev/, compiled in dev/test only).
• def cli re-added for preferred_envs: [check: :test] so a bare mix check works outside MIX_ENV=test (an earlier commit dropped it as "1.17+ only" — Mix.Project.cli/0 is 1.15+, so it's floor-safe; the 1.16 CI lane proves it). mix setup now also installs the pre-commit hook CLAUDE.md promises.

Contract bugs (each locked in by a property in contracts_test.exs, written RED first)

• Mount-table readdir listed duplicate names — sibling mounts under a shared synthetic parent (/a/b + /a/c) each contributed "a" to readdir("/"). Synthetic children now dedupe at the source.
• VFS.Memory mkdir violated the :eexist contract for implicit directories and root, and parents: true errored on the second call. Any existing directory is now :eexist; parents: true is an idempotent success no-op (mkdir -p semantics). The stateful-property reference model encoded the old semantics and was corrected with it.
• Dispatcher errors leaked backend-internal paths in messages — :path was rewritten into the user's namespace but the default :message still named the mount-stripped path. New VFS.Error.put_path/2 regenerates the default message on rewrite; custom backend messages are preserved.
• VFS.Memory.new/1 accepted non-binary seed keys/values, deferring the crash to first read. Both now raise a clear ArgumentError at construction, with adversarial input properties.

Also: VFS.readdir/2's @spec narrowed the protocol's Enumerable.t(String.t()) to a list (the dispatcher's own unbounded branch returns a Stream); the VFS moduledoc claimed telemetry wrapped every public op when four lookups aren't instrumented. Both now match reality.

Public docs / packaging for hex.pm

• README: real hex install snippet ({:vfs, "~> 0.1.0"}), stated 1.16 floor, relative links replaced with absolute GitHub URLs (they 404 on hexdocs).
• SPEC.md: explicit dated amendment reconciling the pre-implementation draft with the shipped surface — 10-callback protocol with %VFS.Error{} returns, real capability set, Skeleton/mount-table sketches matching shipped code, grep/glob/cp/mv reframed as consumer-side. Rationale and decision table untouched.
• CLAUDE.md: 1.16 floor, "9 callbacks" → 10, :mkdir capability documented, fictional Skeleton read_file/2 override corrected, real four-leg CI matrix described.
• CHANGELOG: stamped 0.1.0 (2026-06-10), duplicate ### Added merged, autolink warnings fixed, the new fixes documented.
• mix.exs docs config: filter_modules keeps maintainer-only Mix tasks out of hexdocs; VFS.Error/VFS.StreamOptions added to docs groups.

Verification

• mix check: green from a bare prompt — format, compile -W, credo 0 issues, dialyzer 0 errors, 100.0% line coverage on every file
• mix test --include integration: 38 doctests, 52 properties, 340 tests, 0 failures
• mix docs: zero warnings (was 5+)
• mix vfs.audit: 0 high / 0 medium / 0 low
• mix hex.build: clean; tarball metadata shows only telemetry ~> 1.3, ~> 1.16

Release note

After merge, publishing is: git tag v0.1.0 && git push --tags && mix hex.publish — the tag must exist for source_ref and the CHANGELOG compare links to resolve.

🤖 Generated with Claude Code