The Filesystem Owns the Files

"The disk is the database. Your app is a window, not a warehouse."

Who Owns the Truth?

Every serious file manager has to answer one question before it writes a line of code: where does the truth live? The tempting wrong answer is "in my app" — build a fast local index of the whole disk, show that, and reconcile later. It feels fast and it is a trap. The moment your index and the disk disagree — and they will, constantly, because other apps, Finder, and the OS all change files — your app is confidently showing a lie.

Waygate's Answer

The filesystem owns the files. Full stop. Bytes, names, metadata, permissions, mount contents — all canonical where they live. Waygate's database stores exactly three kinds of thing: workspace state (which folders are open, tab and window layout), references (bookmarks and resource identifiers that point at files without copying them), and operation evidence (the journal of what it did). Never a mirror of the directory tree.

The Projection Discipline

What you see in a Waygate pane is a projection: a fresh read of a live location, rendered into rows. Close the app, reopen it, and it doesn't restore "the files" — it restores the reference to the folder and re-reads it. If the folder changed while the app was closed, the new read shows the change. There is no cached truth to go stale, because there was never a cached truth at all.

The live filesystem is truth; the browser is a projection of it. Waygate persists references and evidence, never a shadow directory catalog that could drift into authority. If the app's picture and the disk ever disagree, the disk wins — always, and by design.

The first architecture I sketched for Waygate had a local 'file index' table — I thought caching the tree would make everything snappy. Dad drew a single arrow on it, from the disk to the app, and said 'that's the only direction truth flows.' I deleted the index table that night. Every hard bug I later avoided — stale rows, phantom files, deletes that hit the wrong thing — traces back to not having a second copy of the truth to keep in sync.

Code

What Waygate's database is (and isn't)·text

  WAYGATE SQLITE STORES            WAYGATE SQLITE NEVER STORES
  --------------------            ---------------------------
  workspace: open folders,        a copy of the directory tree
    tabs, window layout           file contents / bytes
  references: bookmarks +         'the list of files in /some/folder'
    resource identifiers          anything treated as the truth
  operation journal (evidence)      about what's on disk right now

  The disk is the database. This SQLite file is a notebook
  ABOUT the disk, never a copy OF it.

A row is a projection, resolved fresh·swift

// A browser row is derived from a live URL each time it's shown,
// not read back from a stored snapshot.
struct BrowserRow {
    let reference: LocationReference   // bookmark + resource id (points AT the file)
    // display values below are PROJECTED from a fresh read, never authoritative:
    var displayName: String
    var size: Int64?
    var modified: Date?
}

// On refresh, we re-resolve the reference against the live filesystem.
// If it no longer resolves, the row goes visibly offline -- we do NOT
// invent a value from the last time we saw it.

Exercise

Think of a time an app showed you a file that wasn't really there anymore — a 'recent files' list pointing at something you'd deleted, a sync client insisting a file existed. Diagnose it: where was that app keeping its truth, and why did it disagree with the disk? How would 're-read instead of cache' have prevented it?

Hint

Almost every 'phantom file' bug is a stale second copy of the truth. The app cached a list and never noticed the disk moved on. 'The filesystem is canonical, re-read don't cache' isn't a performance choice — it's the only way to never show a file that isn't there.

The Filesystem Owns the Files

Who Owns the Truth?

Waygate's Answer

The Projection Discipline

Code

External links

Exercise

Progress

Comments 0