Module fs/watch

File-system change notifications (fs.watch, plans/archive/STD_API_AUDIT.md §7 P1).

A Watcher observes one path — a directory (entries created, removed, renamed or written) or a single file — through the runtime's native backend (inotify on Linux, kqueue on macOS, ReadDirectoryChangesW on Windows; the std/sys/events layer). Events are delivered on the event loop and queued inside the watcher; read them with the non-blocking poll() or the awaitable next(io). next is the Stream trait's method (std/async/stream.yo), so a watcher composes: w.filter(…).map(…).take(n).

{ watch, WatchOptions, FsEventKind } :: import("std/fs/watch");
w := watch(Path.new(`./logs`), WatchOptions.defaults(), exn);
ev := io.await(w.next(io), io); // Option(FsEvent) — .None once closed
match(ev, .Some(e) => println(`${e.name} ${e.kind}`), .None => ());
w.close();

close() is idempotent and runs automatically when the last reference to the watcher goes away, so a watcher that simply falls out of scope stops its native watch rather than leaving the event loop calling back into freed memory.

Event kinds follow the backend's (and libuv's) two-way split: Rename covers create / delete / move, Change covers a write or metadata change. name is the entry name relative to a watched directory (the file's own name when a file is watched) on every platform — on macOS the runtime diffs a snapshot of the directory and reports each changed entry; an event about the directory itself (or a vanished root) carries an empty name. Platforms coalesce differently, so a single write may surface as one or several Changes — treat the stream as "something happened", not as an exact journal.

Stability

unstable — shipped in v0.2.20 and still unstable at v0.2.24. This is a deliberate extension of the one-release window, not drift: the Windows backend is not delivered, and the shape of Windows change delivery (ReadDirectoryChangesW batches renames as paired events) is the one thing most likely to move Change. macOS and Linux are usable today. Freezing follows Windows delivery, not a release count.