🗂️

Waygate Quest

New: 2026-07-24Updated: 2026-07-24

Build a file manager you'd trust with the delete key

The origin story of Waygate — Dad's native macOS dual-pane file workbench, the file-workbench sibling of the image engine Ember and the voice engine Firekeeper. Why you build a bounded Path Finder replacement instead of trusting your files to a copy operation you can't inspect, and what every architectural choice teaches about the one thing a file manager is actually for: changing files without ever losing one.

8 tracks · 36 lessons · ~7h · difficulty: intermediate-to-advanced

Level 0Lost in Finder

0 XP0/36 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Waygate is not a prettier Finder, not a plugin platform, not a second Pippa brain. It is a native AppKit app that owns exactly one hard problem — safe, inspectable file mutation — and wraps it in the useful thirty percent of Path Finder that Dad actually touches: a source list, two independent panes with tabs and breadcrumbs, Preview and Info, mounted-network management, and a durable operation journal. This quest walks that app end to end: why trustworthy mutation outranks visual parity, where Waygate sits in the fire-family of siblings, the projection-not-truth model that keeps the browser from ever becoming a shadow of the disk, the write-before-mutate operation engine and its state machine, the copy-verify-then-delete rule that is the whole reason cross-volume moves are safe, collision as an explicit decision instead of a guess, why slow I/O can never own the main thread, why mounts and secrets stay with macOS, and the discipline of stopping in needsReview when the evidence runs out. It is the file workbench telling its own origin story — conceptual open-sourcing, not a repo you clone.

Tracks

01🚪The Bounded Thirty
0/4 lessons
What Waygate is, why it's bounded, and why panes are the easy half
Before any Swift, the orientation. Waygate is a native macOS dual-pane file workbench — a deliberate replacement for the thirty percent of Path Finder Dad actually uses, not a clone of its whole programmable universe. This track sets the thesis that governs every later decision: trustworthy mutation outranks visual parity. It places Waygate in the fire-family of siblings, explains why 'the useful thirty percent' is a feature and not a shortcut, and draws the line that keeps the app from rotting into a plugin OS.
Lesson list (4)
Quiz · 4 questions→
02🪞Projection, Not Truth
0/5 lessons
The browser is a view of the disk, never a copy of it
The single mental model that separates a trustworthy file manager from a fragile one: the filesystem is canonical, and everything Waygate shows is a refreshable projection of it. This track builds that model brick by brick — why a path string is never an identity, why refresh re-enumerates instead of trusting a cache, why Waygate's database must never become a shadow directory tree, and why every operation revalidates the live world at apply time instead of trusting what was on screen.
Lesson list (5)
Quiz · 4 questions→
03📓Write Before Mutate
0/5 lessons
The operation engine, the journal, and the one door every change goes through
The beating heart of Waygate. Every file change — create, rename, copy, move, replace, Trash, tag — becomes an immutable plan that crosses exactly one engine, and that engine writes its intent to a durable journal before the first byte moves. This track builds the operation engine from the ground up: why there is one mutation boundary and not many, why the journal is written first, the state machine every operation walks, why the UI is forbidden from touching files directly, and why the plan is an immutable, hashed snapshot.
Lesson list (5)
Quiz · 4 questions→
04✅Copy, Verify, Then Delete
0/5 lessons
The rule that makes moving a file across volumes actually safe
The single most important sequence in a file manager, and the one most tools get subtly wrong. Moving a file to another volume is not one operation — it is copy, verify, publish, delete source, verify absence, in that order, with a hard barrier before the delete. This track builds that sequence: same-volume versus cross-volume moves, why source deletion is a distinct destructive barrier, how staging and publishing work, why a partial copy is never allowed to become the destination, and why Trash is a system workflow, not a fabricated universal undo.
Lesson list (5)
Quiz · 4 questions→
05⚖️Collision Is a Decision
0/4 lessons
When two files want the same name, the app must never guess
What happens when the destination is already occupied is where careless file managers quietly overwrite the wrong thing. In Waygate, a collision is an explicit, durable decision — skip, keep both, replace, or cancel — captured in the plan, never inferred from a stale UI default. This track covers explicit collision policy, why Batch Rename is a plan builder rather than a privileged shortcut, why a multi-item operation is never sold as globally atomic, and how the Selection Basket collects references without ever moving a byte.
Lesson list (4)
Quiz · 4 questions→
06🧵Slow I/O Never Owns the Main Thread
0/5 lessons
The filesystem can block forever, so the UI must never wait on it
Apple explicitly warns that file calls can block for an indeterminate time on file providers, USB media, and SMB. A file manager that runs I/O on the main thread will freeze — the beachball every network file manager is infamous for. This track covers the concurrency and filesystem-semantics rules that keep Waygate responsive and correct: why enumeration, metadata, preview, and mutation all run off the main thread with coordinated access, why packages are atomic and symlinks stay links, why cloud placeholders must not be materialized by accident, and why metadata is preserved or the operation fails loudly.
Lesson list (5)
Quiz · 4 questions→
07🔐Mounts and Secrets Stay with macOS
0/4 lessons
The app remembers where a share lives, never how to unlock it
Network volumes and credentials are the part of a file manager most likely to leak secrets or lie about state. Waygate draws a hard line: it stores a sanitized endpoint and asks macOS to connect, but the actual mount truth and the actual passwords belong to the system, never to Waygate. This track covers why a saved endpoint is not an active mount, why credentials live only in macOS and Keychain, the deliberate decision not to sandbox and the strict compensating boundary that comes with it, and why the app has no root, no helper, and no escape hatch.
Lesson list (4)
Quiz · 4 questions→
08🛟Uncertainty Stops Destruction
0/4 lessons
When the evidence runs out, the app stops — it never guesses at a delete
The final track, and the payoff of everything before it. When a crash, an unmount, or an ambiguous state leaves an operation half-finished, Waygate never runs destructive recovery just because the app relaunched. It reconstructs evidence from the journal, then chooses read-only inspection, evidence-backed forward progress, safe rollback, or needsReview. This track covers how recovery reconstructs evidence, why needsReview is a feature and not a failure, the boundary where Pippa may propose but only Waygate validates and only Dad applies, and closes with why owning your file workbench is worth building.
Lesson list (4)
Quiz · 4 questions→

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.

Tracks

01🚪The Bounded Thirty

02🪞Projection, Not Truth

03📓Write Before Mutate

04✅Copy, Verify, Then Delete

05⚖️Collision Is a Decision

06🧵Slow I/O Never Owns the Main Thread

07🔐Mounts and Secrets Stay with macOS

08🛟Uncertainty Stops Destruction