test(document): support macOS filename semantics

[SchahinRohani]

Summary

Make non-UTF-8 filename validation portable across Linux and macOS.

Changes

• Extracted filename validation into a directly testable helper
• Added a portable Unix test for non-UTF-8 filename validation
• Kept the full filesystem integration test on Linux
• Accounted for macOS rejecting non-UTF-8 filenames at the filesystem boundary

Checklist

• Single-purpose PR (one concern, one PR)
• Linked issue (if applicable): #