module FileMutationQueue

Per-file serialization queue for concurrent tool execution.

When tools run in parallel (via threads or async fibers), multiple tools may target the same file simultaneously. Without serialization, a sequence like [read → patch → write] on the same file would race and lose edits.

This module provides a single public method:

Brute::FileMutationQueue.serialize("/path/to/file") do # snapshot + read + modify + write — all atomic for this path end

Design (mirrors pi-mono's withFileMutationQueue):

• Operations on the SAME file are serialized (run one at a time)
• Operations on DIFFERENT files run fully in parallel (independent mutexes)
• Symlink-aware: resolves real paths so aliases share one mutex
• Error-safe: mutex is always released in ensure, so failures never deadlock
• Self-cleaning: per-file mutexes are removed when no longer in use

Ruby 3.4's Mutex is fiber-scheduler-aware, so this works correctly with both :thread and :task (Async) concurrency strategies.