No Shadow Directory Tree

"The moment your database can answer 'what files are in that folder?', you have built a second filesystem — and now you own both."

The Line That Must Not Be Crossed

Waygate has a SQLite database, and it stores real, durable things. So where's the danger? It's a single question: can the database answer "what files are in /some/folder right now?" If yes, you've built a shadow directory tree — a second copy of the filesystem's structure that will drift the instant anything changes outside your app. Waygate's database is designed so it cannot answer that question. Only the disk can.

What Waygate Durably Stores

Everything in the database is either a reference or evidence, never contents. Workspace: which locations are open and how the window is laid out. Favorites: bookmarks plus a display hint, with no promise the target still exists. Presets: reference sets and layout. Saved network locations: a sanitized scheme, host, and share name — no credentials, no file list. The operation journal: what the engine did. Notice that not one of these is "the list of files in a folder."

Why Sync Clients Teach This the Hard Way

Cloud sync clients are the cautionary tale. To sync, they must maintain a shadow tree — a local model of what's on the server and what's on disk — and reconcile them. That shadow tree is the source of their worst bugs: files that reappear after deletion, conflicts that duplicate, phantom entries that won't clear. Waygate isn't a sync client and deliberately never builds that shadow, which is exactly why it can't inherit that whole family of bugs.

The database is a notebook about the disk, never a copy of it. Waygate stores references and evidence; it never persists a directory catalog that could become authoritative. If a table could answer 'what's in this folder,' that table would be a shadow filesystem — and the second copy is always where the drift bugs live.

The same rule, everywhere in the family. cwkPippa keeps this discipline too: its SQLite and vector store are derived mirrors of an append-only JSONL ground truth, rebuilt by replay rather than patched. Waygate applies the identical instinct to the filesystem — one truth, everything else a projection or a notebook about it.

Code

Every table is a reference or evidence — none is a file list·sql

-- Waygate's tables store pointers and history, never directory contents.

CREATE TABLE workspace (       -- which places are open + layout
  id INTEGER PRIMARY KEY,
  pane TEXT, tab_order INTEGER,
  location_bookmark BLOB,       -- a REFERENCE, not a file list
  view_state TEXT
);

CREATE TABLE favorites (       -- bookmarks + a display hint
  id INTEGER PRIMARY KEY,
  bookmark BLOB, display_name TEXT   -- no promise the target still exists
);

CREATE TABLE operation_journal ( -- EVIDENCE of what the engine did
  op_id TEXT PRIMARY KEY, state TEXT,
  source_ref BLOB, dest_ref BLOB, evidence TEXT
);

-- There is deliberately NO `directory_contents` table.
-- Ask the disk what's in a folder. Always.

Exercise

Look at a sync or backup tool you use and try to find its shadow tree — the local model of what it thinks is on disk or on the server. When has it ever disagreed with reality (a file that 'came back,' a stuck upload, a duplicate)? Then articulate why a file MANAGER, unlike a sync tool, can get away with owning no shadow tree at all.

Hint

Sync tools MUST model both sides to reconcile them — the shadow tree is unavoidable for them, and so are its drift bugs. A file manager only ever needs to show the disk as it is right now, so it can skip the shadow entirely and re-read on demand. Waygate isn't refusing a hard feature; it's refusing a burden it never needed.

The Line That Must Not Be Crossed

What Waygate Durably Stores

Why Sync Clients Teach This the Hard Way

Code

External links

Exercise

Progress

Comments 0