The Selection Basket Moves No Bytes

"The basket is a shopping list, not a shopping cart. Nothing leaves the shelf until you check out."

A Collector, Not a Mover

The Selection Basket solves a real annoyance: you want to gather files from five different folders and then copy them somewhere as a group. The naive way to build it would be to actually move those files into a hidden staging folder as you add them. Waygate refuses that. The basket stores ordered location references plus display hints — and adding or removing an entry has zero filesystem effect. The files never leave their homes until you submit a real operation.

Stale Entries Stay Visibly Stale

Because the basket holds references, not copies, an entry can go stale — the file it points at gets renamed, moved, or deleted while it sits in the basket. Waygate doesn't hide that. A stale or offline entry stays visibly stale; it can't quietly resolve to a same-named replacement, and it can't authorize a mutation. You see that the reference no longer points at a live file, and you decide what to do — exactly the projection-not-truth discipline from Track 2, applied to the basket.

Submission Builds a Normal Plan

When you finally drag the basket to a destination or hit copy/move, nothing magic happens: the basket builds a normal immutable operation plan from its references and hands it to the one engine. Same revalidation, same journaling, same collision handling, same per-item evidence as any other operation. The basket is just a nicer way to assemble the sources; the mutation itself is the ordinary, safe path you already know.

The Selection Basket stores ordered references and display hints; it moves no bytes. Adding or removing an entry has no filesystem effect, stale or offline targets remain visibly stale and cannot authorize mutation, and submitting builds a normal immutable operation plan through the one engine.

Track cleared — collisions and gathering are safe. Explicit collision policy, Batch Rename as a plan builder, no all-or-nothing fiction, and a byte-free Selection Basket. Notice the pattern: every one of these is a new client of the same engine and the same projection rules, never a fork of them — the Track 1 promise about fixed surfaces, kept. Next: why none of this can be allowed to freeze the UI.

Code

The basket holds references; submit turns them into a plan·swift

struct SelectionBasket {
    private(set) var entries: [LocationReference] = []   // ordered, no bytes

    mutating func add(_ ref: LocationReference) { entries.append(ref) }   // no FS effect
    mutating func remove(at i: Int) { entries.remove(at: i) }             // no FS effect

    // Each entry revalidates on display; stale ones show offline, don't act:
    func liveness() -> [ReferenceState] { entries.map { $0.revalidateForDisplay() } }
}

func submit(_ basket: SelectionBasket, to dest: LocationReference, kind: OperationKind) async {
    let plan = OperationPlan(kind: kind, sources: basket.entries,
                             destination: dest, collision: .ask,
                             expected: basket.entries.map(\.identityHint))
    await engine.submit(plan)   // ordinary immutable plan, ordinary engine
}

Exercise

Compare two Selection Basket designs: (A) moves files into a hidden staging folder as you add them; (B) stores references and moves nothing until submit. List what breaks in design A when a user adds a file, quits the app, and comes back — or when they add a file then delete it from Finder. Why is the reference design the only one that stays honest?

Hint

Design A has already mutated the filesystem just by adding to the basket — now the file is 'gone' from its original folder, quitting mid-session strands files in a hidden folder, and the user's mental model ('I only put it in a list') is violated. Design B never touched anything: a file deleted in Finder simply shows as a stale basket entry. Only the reference design keeps 'add to basket' free of side effects.

The Selection Basket Moves No Bytes

A Collector, Not a Mover

Stale Entries Stay Visibly Stale

Submission Builds a Normal Plan

Code

External links

Exercise

Progress

Comments 0