Rename or Rewrite

"Dragging a file two folders over and dragging it to a USB stick look identical. Underneath, one moves a label and the other rewrites a book."

The Same Gesture, Two Realities

To a user, a move is a move: drag it, drop it, done. But the filesystem has two completely different operations hiding under that one gesture. If source and destination are on the same volume, a move is a rename — the bytes never move, only the directory entry changes, and it's effectively instant and atomic. If they're on different volumes — internal disk to USB, laptop to SMB share — the bytes must be physically copied to the new volume and then the original deleted.

Why the Split Is a Safety Boundary

This isn't a performance footnote; it's where the danger lives. A same-volume rename has nothing to lose: the bytes stay put, so there's no window where the file exists in one place, no place, or two places incompletely. A cross-volume move has all of that risk — the copy can half-finish, the destination volume can vanish, and deleting the source too early loses the only complete copy. Waygate branches on this the moment a plan is validated, because the two operations need entirely different safety machinery.

Same-Volume Still Revalidates

Even the 'easy' same-volume rename isn't a blind call. Waygate revalidates identity and collision state first — is this still the file we meant, and is the destination name free or does the plan's collision decision apply? Only then does it issue the coordinated rename. Easy doesn't mean careless; it means the safety machinery is smaller because the risk is smaller.

Same-volume move is a coordinated rename; cross-volume move is copy → verify → publish → delete → verify absence. The bytes-move-or-not distinction is a safety boundary, not a speed detail — a rename has nothing to lose, while a cross-volume move has a destructive barrier that demands verification before the source is ever touched.

You can't tell from the path alone. Two paths that look sibling-close can live on different volumes (a mounted folder, a firmlink, an external drive mounted deep in the tree). Waygate decides same-vs-cross by comparing volume identity, not by string-matching path prefixes — because the prefix can lie about where the bytes actually live.

Code

The branch that decides everything downstream·swift

func executeMove(_ plan: OperationPlan) async throws {
    let src = try revalidate(plan.source)
    let dstVolume = try volumeIdentity(of: plan.destination)
    let srcVolume = try volumeIdentity(of: src)

    if srcVolume == dstVolume {
        // SAME VOLUME: a rename. Bytes never move. Nothing to lose.
        try await coordinatedRename(src, to: plan.destination, plan)
    } else {
        // CROSS VOLUME: the full destructive sequence.
        let staged  = try await copyToStaging(src, on: dstVolume)
        try await verify(staged, matches: plan.expectedMetadata)
        let published = try await publish(staged, as: plan.destination)
        try await deleteSource(src)          // <- distinct destructive barrier
        try await verifyAbsence(src)
    }
}

Exercise

Move a file between two folders on your internal disk, then move a file to a USB drive, and time both. The first is near-instant; the second scales with file size. Explain why in terms of what physically happens to the bytes, and then explain why the slow one needs a verification step the fast one doesn't.

Hint

The same-volume move only rewrites a directory entry, so size doesn't matter — nothing is copied. The cross-volume move physically writes every byte to the new volume, which takes time and can be interrupted. Because bytes actually traveled, you have to confirm they all arrived correctly before deleting the source; the rename had nothing to confirm.

The Same Gesture, Two Realities

Why the Split Is a Safety Boundary

Same-Volume Still Revalidates

Code

External links

Exercise

Progress

Comments 0