watcher: derive OS watch masks from a per-context Op subscription

[Properrr]

Note

Depends on #36416 — this branch is stacked on it (it needs Op::MOVE_FROM and rewrites the kqueue fflags helper that PR introduces). Opened as a draft; I'll rebase and mark ready once #36416 lands. Review the diff against that branch to see only this change.

What does this PR do?

Every bun.Watcher requested the same fixed inotify mask / kqueue fflags / ReadDirectoryChangesW filter regardless of what its context actually read, so consumers paid to have events delivered, decoded and dispatched only to drop them in a contains() check.

Watcher::init now takes the set of Ops its context consumes, and each backend derives its registration from it: file_mask/dir_mask (inotify), vnode_fflags (kqueue), notify_filter (ReadDirectoryChangesW). An op outside the set is never requested, so a context must not rely on one it did not subscribe to — that contract is documented on init.

The dev server subscribes to everything except METADATA: it keys off DELETE/RENAME and re-resolves whatever a directory event names, but a permission or timestamp change cannot alter the bundle graph. --hot/--watch keeps METADATA, since that is what makes touch and chmod observable at all.

The Windows filter is coarser than the other two by nature — it selects which changes wake the call rather than which FILE_ACTION_* come back, and one filter bit can produce several actions. Metadata is deliberately absent there: Windows reports it as FILE_ACTION_MODIFIED, indistinguishable from a content write, so requesting it would mis-report chmod as Op::WRITE.

This is not a throughput optimization

I want to be straight about that, because it would be easy to assume otherwise. Measured on a realistic workload (100 files, no synthetic chmod pass):

	full mask	−IN_ATTRIB	−dir IN_MODIFY
in-place save (editors, build writes)	400 events	400 (0%)	100 (−75%)
atomic save (write tmp + rename)	700 events	600 (−14%)	600 (−14%)

IN_ATTRIB never fires for an in-place write, and the drain path costs 0.24 µs/event against a ~211 ms reload — so event volume is not on the critical path. --watch reload latency is unchanged (211.7 ms vs 216.1 ms mean over 30 samples against a same-profile main build, i.e. within noise).

The value is that the registration now states what each consumer actually needs, and that narrowing a consumer is a one-line change. The one large lever — dir IN_MODIFY at −75% — is not taken here: it is how a file that is not individually watched gets noticed at all, so dropping it changes what the reloader sees and belongs in its own PR with its own measurement of per-event dispatch cost.

How did you verify your code works?

The dev server's resulting inotify file mask is byte-identical to the one requested before this change, verified with strace, so that narrowing is observably free:

--watch  (all)          IN_MODIFY|IN_ATTRIB|IN_MOVED_TO|IN_DELETE_SELF|IN_MOVE_SELF|IN_EXCL_UNLINK
DevServer (no METADATA) IN_MODIFY|IN_MOVED_TO|IN_DELETE_SELF|IN_MOVE_SELF|IN_EXCL_UNLINK

That also demonstrates the filter is actually filtering rather than merely plumbed — the two consumers register different masks.

Linux (x86_64): test/cli/watch, test/cli/hot, test/bake/dev/hot — 35 pass, 0 fail. The full test/bake/dev suite (26 files, 161 tests) also passes with the dev-server narrowing applied.

Windows is compile-checked only (cargo check --target x86_64-pc-windows-msvc); CI is the gate for the notify_filter hunk.

[Properrr]

Rebased (was conflicting, now mergeable). Force-pushed 2c0956d32 → 487c244f9.

This is stacked on #36416, so it needed replaying onto that PR's rebased head as well as onto current main. Five files conflicted; four were the same mechanical shape as #36416 — main narrowed visibility (pub → pub(crate), pub(crate) → private) on items this PR extends. Kept upstream's visibility with this PR's additions in each case:

• INotifyWatcher.rs — coalesce_interval, plus this PR's subscription field and file_mask
• KEventWatcher.rs — fd and new(), plus subscription and vnode_fflags
• WindowsWatcher.rs — the DirWatcher fields and next(), plus the filter field and notify_filter
• Watcher.rs — a doc comment both sides had reformatted; merged, and corrected the example to the real three-argument Watcher::init signature

The fifth needed judgement rather than merging: hot_reloader.rs. main deleted the unsafe fn init this PR was modifying, so I took the deletion rather than resurrecting it. The subscription argument was already applied by auto-merge to the call site that replaced it (Watcher::init(reloader, ctx.watcher_top_level_dir(), HOT_RELOAD_SUBSCRIPTION)), so nothing was lost — but that one is worth a second look from a reviewer, since it is the only resolution where I dropped code rather than combining it.

Verified across targets, since most of this lives behind #[cfg]: cargo check -p bun_watcher on linux, aarch64-apple-darwin and aarch64-pc-windows-msvc all clean. watcher-trace.test.ts 6 pass, test/cli/hot/hot.test.ts 12 pass.

Still a draft — flagging the rebase so the branch is reviewable, not proposing it for merge yet.