The Destructive Barrier

"'The copy returned' is a hope. 'The copy is verified present at the destination' is a fact. Only facts may authorize a delete."

The Most Dangerous Line in the Whole App

In a cross-volume move, there is exactly one line that can permanently lose data: the one that deletes the source. Every other step is recoverable — a failed copy leaves the source untouched, a bad verify just stops the operation. But deleting the source is irreversible, and if the destination copy isn't actually good, you've just destroyed the only complete version. Waygate treats that line as a barrier: a gate that requires positive evidence to cross.

Evidence, Not Optimism

The rule is blunt: a source is never removed because a copy started, and never because a copy call returned. Returning without an error is not evidence the bytes are all there and correct. Before the delete, Waygate must hold proof — the destination exists, its size and metadata match the plan's expectations, and the published file is at the real destination name. Only with that evidence in the journal does the destructive barrier open.

When a Crash Lands on the Barrier

Now the interesting case: the app crashes after publishing the destination but before deleting the source. Both copies now exist on disk. A naive tool might, on restart, assume the move finished and delete the source — or assume it failed and delete the destination. Waygate does neither. The journal marks the destructive barrier as incomplete, recovery verifies both sides, and it only proceeds when the identity evidence is deterministic. If it isn't, the operation waits in needsReview. Two copies is a safe state; a wrong guess is not.

Source deletion is a distinct destructive barrier, opened only by evidence. A source is never removed because a copy started or merely returned. Before the delete, the destination must be verified present and correct; a crash on the barrier leaves both copies and routes to deterministic recovery or review — never a guess.

The classic data-loss move. The single most common way file tools destroy data is deleting the source on the strength of a copy call that returned success while the destination was incomplete — a truncated write, a silently-failed SMB flush, a full disk that reported OK. 'It returned' is the trap. The barrier exists to replace optimism with verification.

Code

The barrier: proof required before the irreversible step·swift

func crossDestructiveBarrier(_ plan: OperationPlan,
                             staged: URL, published: URL) async throws {
    // Gather POSITIVE evidence the destination is real and correct:
    let dstVals = try published.resourceValues(forKeys: [.fileSizeKey,
                                                         .contentModificationDateKey])
    guard dstVals.fileSize == plan.expectedMetadata.size,
          try await bytesVerified(published, against: plan)
    else {
        throw OpError.destinationNotVerified   // do NOT delete the source
    }
    try await journal.mark(plan.id, .verified, evidence: dstVals)

    // ONLY NOW may the destructive barrier open:
    try await deleteSource(plan.source)
    try await journal.mark(plan.id, .committed)
}
// If the process dies before `.committed`, both copies exist and the
// journal says the barrier is incomplete -> recovery, never a blind delete.

A crash on the barrier is a SAFE state·text

  copy --> verify --> publish --| CRASH |--> delete source --> done
                                ^
                                both copies exist here

  naive tool on restart:  'probably finished' -> delete source   (risky!)
                          'probably failed'   -> delete dest     (risky!)

  Waygate on restart:  journal says barrier INCOMPLETE ->
                       verify both sides. Deterministic? finish safely.
                       Uncertain? needsReview. Two copies never lose data.

Exercise

Write out the exact sequence of a cross-volume move and mark the single irreversible step. For every step before it, say what recovery does if a crash happens there (hint: usually 'nothing was lost'). For the irreversible step, state the evidence that must exist in the journal before it's allowed to run.

Hint

Copy, verify, publish are all recoverable — a crash there leaves the source intact, so recovery can just retry or discard the staged copy. The delete-source step is the only irreversible one, and the evidence gating it is: the destination file exists, at the right name, with size and content verified against the plan. No evidence, no delete.

The Most Dangerous Line in the Whole App

Evidence, Not Optimism

When a Crash Lands on the Barrier

Code

External links

Exercise

Progress

Comments 0