Summary

This MR fixes an unsafe file replacement flow where replacing an existing destination could leave the folder in an inconsistent state if an error occurred mid-operation. The update ensures that destination replacement is handled more safely using a temporary backup and atomic move semantics.

Motivation / Context

When copying or moving a file into a directory that already contains a file with the same name, failures during the replacement process could result in both the source and destination being lost. This indicated that the operation was not atomic and lacked proper recovery guarantees.

Changes

• Introduced a temporary destination backup using a UUID-based filename
• Replaced direct overwrite logic with LLMove to improve atomicity
• Ensured the original destination can be restored if the move fails
• Added best-effort cleanup for temporary backup files after success
• Improved error reporting with contextual information when recovery fails
• Avoided introducing new abbreviated or single-letter variable names

Behavior Changes

• File replacement now guarantees that a valid file exists after the operation, even if an intermediate step fails
• In rare failure cases, a temporary backup file may remain and is explicitly logged

Testing

• Manually tested file replacement when a destination file already exists
• Verified correct behavior when:
  • Move succeeds
  • Move fails and restore succeeds
  • Move fails and restore fails
• Confirmed no regression for non-conflicting copy operations

Risks & Mitigations

• Risk: Temporary backup files may remain if cleanup fails
• Mitigation: Cleanup is logged and non-blocking; filesystem consistency is preserved

Backwards Compatibility

• No breaking changes

Checklist

• Verified filesystem consistency after failed replace scenarios
• Error handling paths tested and logged
• No unrelated refactors or formatting changes