# Real-Time FS Watch & Incremental Reconciliation

DiskTracker combines high-speed parallel traversals with active background observability to keep directory structures up to date without repeatedly rescanning whole trees.

---

## 📥 Watch Engine & Atomic Ingestion

DiskTracker monitors filesystem modifications using native platform events. The portable backend uses Rust [`notify`](https://crates.io/crates/notify). On Linux, DiskTracker first attempts a fanotify-assisted backend and falls back to `notify` if the kernel or process permissions deny fanotify marks.

* **Atomic Event Ingestion**: Live file modifications, deletions, renames, overflow notifications, and creations are normalized into filesystem events (`FsEvent`).
* **Dirty Queue Batching**: Events are pushed into a `DirtyQueue` structure that debounces events and de-duplicates multiple consecutive edits on identical paths.
* **WAL SQLite Batch Logging**: Debounced modifications are flushed periodically in single-transaction batches into the `mutation_log` SQLite table.

### Linux Fanotify-Assisted Backend

Linux watch sessions use `DISKTRACKER_WATCH_BACKEND=auto` by default:

* **Fanotify mount marks**: When available, DiskTracker adds mount-level fanotify marks for write and queue-overflow visibility without relying only on one inotify watch per directory.
* **Precise path fallback in the same stream**: Delete and rename paths are still sourced from `notify`, because fanotify path reconstruction for those events can require extra privileges.
* **Deterministic fallback**: If fanotify is unavailable, denied, or unsupported, the watch session continues with `notify` automatically. Use `DISKTRACKER_WATCH_BACKEND=notify` to force the portable path, or `DISKTRACKER_WATCH_BACKEND=fanotify` to require the Linux-assisted path.

---

## ⚡ $O(\text{changes})$ Incremental Alignment

In standard directory indexers, a file change forces a full recursive folder scan to recalculate parent and ancestor folder sizes. DiskTracker achieves highly efficient updates:

* **Directory-Level Event Grouping**: Live file changes are mapped directly to their immediate parent directory identifier.
* **Avoiding Recursion**: Bypasses directory-tree recursion by applying changes to leaf directory records.
* **Lazy Bottom-Up Reconciliation**: Re-evaluates affected directories, then floats calculated delta changes up to the root. Full physical scans are reserved for explicit `disktracker reconcile --full`.

---

## 📂 Bounded Child Scans

When updates occur, DiskTracker reads only the direct children of the modified folder:

* **Bounded Traversal Scope**: Uses shallow directory reads (`std::fs::read_dir`) on modified directories rather than restarting from the watch root.
* **Targeted New-Subtree Scans**: Existing child directories reuse cached sizes. Brand-new child directories are scanned recursively once so their subtrees can be inserted into the mmap state.

---

## 🔒 Sibling Prefix-Safe Validation

Simple string operations (like `path.starts_with(parent_path)`) can lead to corrupt size assignments if directories share name prefixes (e.g., matching `/var/lib_sibling` against `/var/lib` because the letters match).

DiskTracker implements strict path boundary assertions:

* **Absolute Byte Boundaries**: Splits paths into component arrays and validates parent-child matching on exact subdirectory segments.
* **Prefix Collisions Avoided**: Ensures size modifications and events are only propagated to verified, authentic parent-child lines.

---

## 📈 Continuous Delta Bubble-Up

Once local modifications are processed at the leaf level, they propagate instantly:

* **In-Memory Updates**: Updates are bubbled up through the active memory map directly to the root node, ensuring consistent lookups.
* **Snapshot Alignment**: Preserves identical directory and file metadata in both memory-mapped caches and physical SQLite tables during real-time watches.