Merge train: #9613 #9614 (+5 gate repairs, 3 pre-existing on main)

[proggeramlug]

Lands the validated train: #9613 (fs.watch uses OS change notifications — inotify/ReadDirectoryChangesW/kqueue via notify, FSEvents on macOS — instead of a 25 ms whole-tree re-walk on the main thread; #9591) and #9614 (Bun standalone extracted-filesystem root mapping).

Five gate repairs carried by the train, three of which were ALREADY RED ON MAIN from earlier landings:

• fix(runtime): root the assimilated thenable wrapper across the user then (#9539) #9595 (train88): 23 raw-handle debt sites across promise/assimilate.rs, promise/combinators.rs, util_promisify.rs and the new gc test converted to with_*/across_* combinators (timing-equivalent — the re-read still happens after the user then).
• fix(mysql2): align bundled fallback semantics #9564 (train80): the unrooted-local shape in mysql2/result.rs FIXED, not ceilinged — rows/fields arrays are rooted in a RuntimeHandleScope and the result tuple is allocated last, taking that file 44 -> 39 findings and the workspace total 566 -> 561. (The --no-raise-vs arm correctly refused the ceiling raise I first tried.)
• fix(runtime): fs.watch uses OS change notifications, not a 25 ms tree re-walk (#9591) #9613: two raw thread_local! blocks -> perry_thread_local!, plus written root-holder verdicts for QUEUE/SHARED; the FSEvents API dlopen cache allowlisted in global_sink_isolation.py with its reason; the macOS-dead RawEvent::Error variant cfg_attr-allowed.

Validation: run_lint_gates.sh all 62 gates pass; release build green; RUST_TEST_THREADS=1 perry-runtime 3037/0; perry-stdlib green; fs.watch + Bun integration suites 2/2 and 2/2; the #9591 gap fixture byte-identical to node.

Rebase-merge preserving authorship.

Summary by CodeRabbit

• New Features

  • Added --bunfs-root <dir> support for compiling Bun standalone sources and resolving virtual Bun paths against extracted files.
  • BunFS assets now work with imports, re-exports, require, node:fs, and Bun.file().

• Bug Fixes

  • fs.watch and fsPromises.watch now use native filesystem notifications for faster, lower-overhead event delivery, with a paced fallback when needed.
  • Watcher errors and lifecycle behavior are handled more reliably.
  • BunFS path validation prevents missing-file and path-traversal issues.

• Documentation

  • Documented the new --bunfs-root option and virtual path behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 24ad5618-0a80-4073-b725-2fb23414d772

📥 Commits

Reviewing files that changed from the base of the PR and between 666481e and e994ec6.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (36)

• changelog.d/9613-fs-watch-os-events.md
• changelog.d/9614-bunfs-root.md
• crates/perry-runtime/Cargo.toml
• crates/perry-runtime/src/bun_compat/mod.rs
• crates/perry-runtime/src/embedded.rs
• crates/perry-runtime/src/fs/dir_glob_watch.rs
• crates/perry-runtime/src/fs/dir_glob_watch/watch.rs
• crates/perry-runtime/src/fs/dir_glob_watch/watch_backend.rs
• crates/perry-runtime/src/fs/dir_glob_watch/watch_fsevents.rs
• crates/perry-runtime/src/gc/tests/runtime_roots/thenable_assimilation.rs
• crates/perry-runtime/src/lib.rs
• crates/perry-runtime/src/promise/assimilate.rs
• crates/perry-runtime/src/promise/combinators.rs
• crates/perry-runtime/src/util_promisify.rs
• crates/perry-stdlib/src/mysql2/result.rs
• crates/perry/src/commands/compile.rs
• crates/perry/src/commands/compile/asset_manifest.rs
• crates/perry/src/commands/compile/build_cache.rs
• crates/perry/src/commands/compile/collect_modules.rs
• crates/perry/src/commands/compile/collect_modules/import_helpers.rs
• crates/perry/src/commands/compile/collect_modules/static_require_transform.rs
• crates/perry/src/commands/compile/embed.rs
• crates/perry/src/commands/compile/init_order.rs
• crates/perry/src/commands/compile/resolve.rs
• crates/perry/src/commands/compile/run_pipeline.rs
• crates/perry/src/commands/compile/types.rs
• crates/perry/src/commands/dev.rs
• crates/perry/src/commands/run/mod.rs
• crates/perry/tests/issue_9591_fs_watch_native_events.rs
• crates/perry/tests/issue_9598_bunfs_root.rs
• docs/src/cli/flags.md
• scripts/gc_runtime_root_holders.json
• scripts/global_sink_isolation.py
• scripts/string_payload_access_baseline.txt
• scripts/unrooted_local_shape_baseline.json
• test-files/test_gap_9591_fs_watch_events.ts

---

📝 Walkthrough

Walkthrough

The change replaces timer-based filesystem watching with OS event backends and a paced fallback. It adds --bunfs-root support for Bun virtual paths and embedded assets. It also updates GC-managed pointer access to use transient handles.

Changes

OS-backed filesystem watching

Layer / File(s)	Summary
Native watcher backends and fallback polling crates/perry-runtime/src/fs/dir_glob_watch/*, crates/perry-runtime/Cargo.toml	fs.watch uses native notifications, shared watcher instances, macOS FSEvents, event queues, and an adaptive polling fallback.
Watch lifecycle and event delivery crates/perry-runtime/src/fs/dir_glob_watch/watch.rs, crates/perry-runtime/src/lib.rs	Watchers route events and errors through the runtime pump. ref(), unref(), close(), abort handling, and active-handle checks use backend state.
Watcher behavior and performance validation crates/perry/tests/issue_9591_fs_watch_native_events.rs, test-files/test_gap_9591_fs_watch_events.ts, changelog.d/9613-fs-watch-os-events.md	Tests cover native and fallback CPU usage, event delivery, recursive paths, promise iteration, close behavior, and process exit.

BunFS root support

Layer / File(s)	Summary
BunFS path contract and runtime access crates/perry/src/commands/compile/resolve.rs, crates/perry-runtime/src/embedded.rs, crates/perry-runtime/src/bun_compat/mod.rs	The compiler maps /$bunfs/root/ paths under a canonical root. Runtime file reads, existence checks, and sizes consult embedded content.
Compiler integration and asset embedding crates/perry/src/commands/compile/...	The compiler propagates bunfs_root through import, require, re-export, initialization, asset discovery, manifest, and cache logic.
Compile command wiring and validation crates/perry/src/commands/{dev.rs,run/mod.rs}, crates/perry/tests/issue_9598_bunfs_root.rs, docs/src/cli/flags.md	Compile entry points initialize the option. Tests and documentation cover relocated roots, module identity, asset access, and missing-module diagnostics.

Moving-GC pointer safety

Layer / File(s)	Summary
Transient handle access in runtime code crates/perry-runtime/src/promise/*, crates/perry-runtime/src/util_promisify.rs, crates/perry-runtime/src/gc/tests/runtime_roots/thenable_assimilation.rs, crates/perry-stdlib/src/mysql2/result.rs	Promise and thenable code uses handle closures. MySQL result construction roots child arrays before allocating the result tuple.
GC metadata and baseline updates scripts/gc_runtime_root_holders.json, scripts/*baseline*	GC census metadata records watcher storage, and pointer-access baselines reflect the updated handle usage.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Filesystem
  participant WatchBackend
  participant EventQueue
  participant RuntimePump
  participant JSWatcher
  Filesystem->>WatchBackend: emit filesystem change
  WatchBackend->>EventQueue: queue RawEvent
  EventQueue->>RuntimePump: notify main thread
  RuntimePump->>JSWatcher: deliver change or error

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch land-train90

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}