Function with_file_lock 

pub async fn with_file_lock<T, F>(lock_path: &Path, f: F) -> StorageResult<T>
where
    T: Send + 'static,
    F: FnOnce() -> StorageResult<T> + Send + 'static,

Cross-process commit arbitration (#100): an advisory flock on lock_path, held for the closure’s scope — lock → read-modify-write → publish → release. Independent processes (e.g. separate CLI invocations) that take the same lock file cannot interleave their metadata cycles.

The blessed lock-file location for a metadata file is lock_file_for_metadata ({metadata-stem}.lock next to the file); the lock file is created on demand (missing parent directories included) and left in place after release — it is a rendezvous point, not a commit artifact.

The closure is synchronous and runs on the blocking pool: the flock can block arbitrarily long on a competing holder, so it must never run on an async executor thread. Because the closure is sync, it cannot await with_commit_actor — a cycle run here is serialized across processes but not against in-process async save_* cycles; use with_metadata_file_lock when both are required. Off unix this fails with StorageError::UnsupportedFormat rather than silently skipping arbitration.

The blocking-pool caveats documented on with_metadata_file_lock apply here identically: unbounded waits, non-abortable waiters, blocking-thread capacity.