A Partial Copy Is Never the Destination

"Cancel doesn't mean 'undo the world.' It means 'stop cleanly, and clean up only what I know for certain is mine.'"

Pause and Cancel Are Cooperative

A long copy has to be interruptible — a user should be able to pause it or cancel it. But interruption can't happen at a random instant, or you'd leave the operation in an unknown state. Waygate makes pause and cancel cooperative: the engine checks for a pause/cancel request only at safe checkpoints — between files in a multi-item copy, between chunks in a large transfer. At those points the state is known and the journal is consistent, so stopping is clean.

The Partial Stage Is Never Promoted

Here's the core rule this lesson defends: a partial stage is never presented as the destination. If you cancel a copy midway, the half-written staging item does not get published to the real name — publishing only ever happens after full verification, which a canceled copy never reaches. The user sees the operation stop; they never see a truncated file wearing the destination's name. Cancel stops the road before the reveal, so the costume never comes off.

Cleanup Cleans Only What It Owns

When an operation cancels, it may clean up — but only artifacts it positively owns (its own staging items), and only when there's no uncertainty. It will delete .waygate-stage-op_7a3f because the journal proves that item belongs to this operation and the operation didn't finish. It will not touch anything it can't prove it created. Ambiguity means leave it and flag it, never a speculative delete. Directory copies build a bounded, lazy work graph off the main thread, and progress honestly separates bytes, items, current item, and indeterminate work — so a pause always lands somewhere the engine understands.

Pause and cancel are cooperative; a partial stage is never published, and cleanup touches only positively-owned artifacts with no uncertainty. Stopping happens at safe checkpoints where the state is known. A canceled copy leaves an obviously-incomplete staging item the journal owns — never a truncated file at the real destination name.

Honest progress is a safety feature, not just UX. Distinguishing bytes copied, items done, the current item, and indeterminate work isn't only about a nicer progress bar. It's what lets pause land on a real checkpoint and lets recovery reason about exactly how far an operation got. A single fake percentage would hide the very information the engine needs to stop safely.

Code

Cooperative checkpoints; cleanup only what the journal proves is ours·swift

func copyItems(_ items: [URL], _ plan: OperationPlan) async throws {
    for (i, item) in items.enumerated() {
        try Task.checkCancellation()          // safe checkpoint: BETWEEN items
        if await controls.isPaused { await controls.waitUntilResumed() }
        let staged = try await copyOne(item, plan)
        try await journal.mark(plan.id, .itemStaged(i), evidence: staged)
    }
}

func onCancel(_ plan: OperationPlan) async throws {
    // Delete ONLY staging items the journal proves belong to this op:
    for artifact in journal.ownedStagingArtifacts(plan.id) {
        if journal.isUnambiguouslyOwned(artifact) {
            try? FileManager.default.removeItem(at: artifact)
        } // else: leave it, flag it -- never a speculative delete
    }
}

Exercise

A user copies 100 files to a network share and cancels at file 40. Describe the correct end state: what's at the destination, what's in staging, what got cleaned up, and what the journal says. Then explain why 'cancel = undo everything' would be both surprising and unsafe here.

Hint

Correct end state: files 1-39 are verified and published at the destination and stay there; file 40's staging item is cleaned up (the journal proves it's ours and incomplete); files 41-100 never started. 'Undo everything' would have to re-delete 39 files that legitimately arrived — surprising to the user and a fresh chance to delete the wrong thing. Cancel stops; it doesn't reverse verified work.

A Partial Copy Is Never the Destination

Pause and Cancel Are Cooperative

The Partial Stage Is Never Promoted

Cleanup Cleans Only What It Owns

Code

External links

Exercise

Progress

Comments 0