Module file_watcher 

Cross-process file-watcher convenience for the change-event surface.

watch_mem_repo starts a notify-backed file-system watcher against <gitdir>/refs/heads/ and surfaces a std::sync::mpsc::Receiver of MemChangedEvents. Consumers that do not share the writer’s crate::Engine instance (the bridge HEAD-watcher, a UI live-update path, audit-log workers, webhook notifiers) consume events through this surface; the wire shape matches the in-process callback API exactly so the same downstream code paths work for both sources.

Gated behind the file-watcher Cargo feature — notify is a non-trivial dependency and consumers that only need the in-process crate::Engine::subscribe_mem_changes path should not pay for it. Without the feature enabled the module disappears entirely.

Design

• watch_mem_repo spawns a background thread running the notify-event loop and returns a MemRepoWatcher handle that owns the notify::PollWatcher (chosen over RecommendedWatcher for cross-platform determinism — see the rationale at the PollWatcher::new call site). A per-mem HashMap<mem_name, last_seen_sha> (a shared Arc<Mutex<…>> seeded before the thread starts) lets each emitted event’s previous field reflect the actual transition.
• On startup the thread scans the existing refs/heads/ tree and seeds the SHA map without emitting synthetic history events — consumers see changes from this point forward, never replay.
• Per file-system event the thread re-reads the touched ref file (or the directory holding it for hierarchical layouts) and emits a MemChangedEvent if the SHA changed. Notify can deliver bursts; the SHA-comparison gate deduplicates them.
• The returned MemRepoWatcher handle owns the notify watcher; dropping it cancels the watch and the background thread joins on its event channel disconnecting.

Limitations

• Reads loose refs only (the typical case for an actively-written mem-repo). Packed refs (<gitdir>/packed-refs) are not parsed in v1 — production deployments that compact refs need a follow-up. Loose refs created after compaction still surface normally.
• Read-only consumers must poll [crate::ops::changes_since] for any history that landed before the watcher started.

Structs

MemRepoWatcher

RAII handle returned by watch_mem_repo. Dropping the handle stops the watcher (the underlying notify watcher is dropped, cancelling the OS-level subscription, and the background thread exits when its event channel disconnects).

RosterFileChanged

Walk the initial refs/heads/ tree and read each loose ref’s 40-char SHA. The map this returns seeds the per-mem state so the first event emitted for any mem carries the right previous value (rather than always an empty string). A roster-file change, as the roster watcher reports it. Carries no diff: the consumer runs the engine’s reconciliation (every operation does, and memstead_reload / the ui-api reload force it), which computes the applied change from the file.

Enums

FileWatcherError

Errors surfaced by watch_mem_repo.

Functions

watch_mem_repo

Start a file-system watcher on <gitdir>/refs/heads/ and surface a receiver of MemChangedEvents. See the module docs for the design and the limitations (loose-refs only, no synthetic replay).

watch_roster

Watch the workspace’s mount roster (.memstead/state/mounts.json) alongside the mem-repo refs: one event per observed write, over the same polling watcher and cadence watch_mem_repo uses. The workspace store directory is watched (not the file), so a roster written by rename-into-place still surfaces. RefsHeadsMissing is reused for a workspace whose store directory does not exist.