Module watcher 

Filesystem watcher with debounced batch events.

Provides deterministic event coalescing: all events within a debounce window are collected, de-duplicated, sorted lexicographically, and emitted as a single batch. This ensures the same final DB state regardless of event arrival order.

Threading Design

This watcher uses thread-safe synchronization for concurrent access. The legacy pending state fields use Arc<Mutex<T>> to allow safe access from multiple threads during concurrent operations and shutdown.

Thread safety: Arc<Mutex<T>> provides runtime mutual exclusion and is safe to share across threads. The mutex will panic if poisoned (consistent with RefCell behavior).

Global Lock Ordering

This module participates in the global lock ordering hierarchy:

1. watcher state locks (legacy_pending_batch, legacy_pending_index)—acquired first
2. indexer shared state locks (dirty_paths)—acquired second
3. wakeup channel send (highest priority)—acquired last

Rule: Never send to wakeup channel while holding other locks.

See src/indexer.rs::PipelineSharedState for full lock ordering documentation.

See MANUAL.md for architecture details.

Modules

async_watcher

Async filesystem watcher with tokio

Structs

FileEvent

Legacy: File event emitted by the watcher (DEPRECATED).

FileSystemWatcher

Filesystem watcher that emits debounced batches of dirty paths.

WatcherBatch

Deterministic batch of dirty file paths.

WatcherConfig

Filesystem watcher configuration

Enums

EventType

Type of file event (DEPRECATED - not used in batch processing).