@graftland/hmr 0.0.0-stage → 0.2.0-beta.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# @graftland/hmr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English |
+[简体中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-CN.md)
+|
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-TW.md)
+
+Reloads plugin modules on Node.js without restarting the process.
+
+```sh
+npm install @graftland/hmr effect
+```
+
+`Hmr.make` gives you an importer for the loader. It also gives you `reload` and
+`watch`, which replace plugins with new code. It needs Node.js 22.19 or later.
+
+## Watching files
+
+`watch` uses native filesystem events, so reloads happen quickly. It also checks
+the contents of loaded, versioned modules inside the watched paths once per
+second. This catches changes that the native backend missed. For example:
+
+- the startup window of the macOS directory watcher
+- a save between an import and the watcher installation
+
+How the checks work:
+
+- A newly loaded module is compared with the bytes that its module hook read. So
+  adding a plugin through configuration does not count as a file change.
+- Each disk observation is tied to an import attempt and to the bytes that the
+  attempt actually read.
+- A newer committed or failed attempt makes older observations invalid. So a
+  save between a snapshot and an import cannot leave the running plugin on the
+  wrong version.
+- An unchanged failed attempt stays acknowledged until the next change. Polling
+  does not retry it again and again.
+- The check respects `recursive`. It stops when the consumer closes the stream.
+- Its cost depends on the contents of those modules, not on the size of the
+  directory tree.
+
+`watch(paths, options)` accepts `filter(absolutePath)` in addition to
+`recursive`, `onReady`, and `debounce`. The predicate filters both native events
+and periodic content checks. By default, every path is accepted. For example:
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+The CLI uses this filter for JavaScript and TypeScript module files outside
+`node_modules`. YAML configuration changes belong to the loader. They never
+trigger an HMR reload of every entry.
+
+## Failures
+
+Debouncing does not make file writes atomic. If a reload meets incomplete code,
+it emits `Failed` with the original `Cause`. A later content change can start
+recovery, even without another native event.
+
+Watcher I/O failures and reconciliation I/O failures both fail the stream. So
+consumers should handle both failure channels.
+
+`onReady` reports that the watcher is installed. It is not an operating-system
+delivery barrier.
+
+## When a restart is needed
+
+CommonJS and native dependencies need a process restart. HMR tracks dependency
+facts by generation for the session. This includes dynamic imports during plugin
+activation, after the entry import completes. Once HMR records such a
+dependency, later reloads of that generation return `Skipped` with
+`restart-required`.
+
+Loading through `require` is not isolated by ESM URL versions. This includes
+`require(esm)`. HMR is careful here. It treats a versioned module's import of
+`node:module` (or `module`) as getting a native loading capability that it
+cannot track. That dependency graph returns `Skipped / restart-required`, even
+if the module only uses another utility from `node:module`. HMR records the
+capability before use. This covers CommonJS cache hits, and it stays valid when
+another entry gets the same capability. Use static or dynamic ESM imports for
+dependencies that need hot reload.
+
+Watchers report known native-loading restart requirements even without a file
+notification, including when a plugin acquires the capability after startup. The
+periodic status check suppresses unchanged reports. This warning does not mean
+that a reload occurred.
+
+Local file entry leases and their reachable dependency edges keep the requested
+path and its resolved target, together with the importing parent and generation.
+Reload checks this relationship before it imports, and again before it publishes
+any replacement. The same owned graph supplies polling, including dependencies
+from failed attempts awaiting retry; releasing the last lease removes its graph
+from these checks. If a symlink target changed, reload returns
+`Skipped / restart-required` with the affected request URLs. Every running
+plugin stays unchanged. Polling checks this relationship too. This includes
+targets with identical content and missed native events. Restart the process
+after you retarget an entry or helper. HMR does not invalidate Node's resolution
+caches. These checks cover local file requests in the tracked dependency graph.
+They do not cover changes to package export maps or bare-package resolution.
+
+## Entry leases
+
+`importerScoped(specifier)` is an Effect that needs `Scope`. Each call owns a
+lease on the entry. The last release removes the entry from later reloads.
+
+`importerScoped(specifier, { observationScope })` separates the observation
+lease from temporary importer resources. `ModuleResolver` passes this scope as
+the importer's second argument. Keep it alive while failed entries await retry,
+and close it when replacing the observation attempt or removing the entry.
+Candidate resources can close immediately on failure without deleting that
+observation. Omitting the option uses the caller's scope.
+
+The CLI passes this importer to `ModuleResolver`. Each configuration entry owns
+its observation scope independently of activation resources. A failed first
+import remains observable after candidate cleanup. Retrying replaces the old
+observation generation; removing or disabling the entry closes it.
+
+How polling and restarts work with leases:
+
+- Polling finds its file set from each live lease. It uses the running
+  generation and the latest uncommitted import attempt.
+- It keeps failed imports and missing local dependencies, so it can retry them.
+- It stops reading an entry, and the dependencies only that entry uses, when the
+  last owner closes.
+- A successful replacement retires the old dependency graph.
+- Only dependencies that can be reached from leased entries can require a
+  restart.
+- The Promise-based `importer` keeps its registrations until the HMR session
+  closes.
+
+## Replacement conflicts
+
+Sometimes entries shared one Plugin object, but now they export different
+objects. Then reload returns `Skipped` with reason `ambiguous-exports` and the
+affected module URLs.
+
+Two other cases return `Skipped` with reason `identity-conflict` and the
+conflicting module URLs:
+
+- Replacement identities overlap, such as `P → Q, Q → R`.
+- A mapping does not match the existing runtime aliases.
+
+In all of these cases, nothing is replaced. Restart the application, or restore
+a mapping that can be represented. Validation and alias publication share the
+core replacement transaction.
+
+Native watcher producers observe their complete Exit after source cleanup and
+before entering background stream merging. Mixed interruption failures are
+logged there with the full Cause; pure interruption is silent. Ordinary backend
+failures still propagate to the consumer without duplicate logging.
+
+## Cancellation
+
+When a module fails during cancellation, HMR records the original failure with
+its full Cause. It does this before pending interruption can hide the completed
+Exit.
+
+## Documentation
+
+- [Hot reload](https://graftland.github.io/graft/hot-reload/)
+
+Part of [Graft](https://github.com/graftland/graft). Licensed under
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,120 @@
+# @graftland/hmr
+
+[English](https://github.com/graftland/graft/blob/main/packages/hmr/README.md)
+| 简体中文 |
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-TW.md)
+
+在 Node.js 上热重载插件模块，无需重启进程。
+
+```sh
+npm install @graftland/hmr effect
+```
+
+`Hmr.make` 为加载器提供一个 importer，同时提供 `reload` 和
+`watch`，用新代码替换插件。需要 Node.js 22.19 或更高版本。
+
+## 监视文件
+
+`watch`
+使用原生文件系统事件，所以重载很快。它还会每秒检查一次监视路径内已加载的、带版本的模块的内容，以捕获原生后端漏掉的变更。例如：
+
+- macOS 目录监视器的启动窗口期
+- import 与监视器安装之间发生的保存
+
+检查的工作方式：
+
+- 新加载的模块会与它的模块钩子读取的字节进行比较。所以通过配置添加插件，不会被算作文件变更。
+- 每次磁盘观察都与一次 import 尝试以及该尝试实际读取的字节相关联。
+- 更新的已提交或已失败的尝试会使更早的观察失效。所以在快照与 import 之间发生的保存，不会让正在运行的插件停留在错误的版本上。
+- 未发生变化的失败尝试会保持已确认状态，直到下一次变更。轮询不会反复重试它。
+- 检查遵循 `recursive`，并在消费者关闭流时停止。
+- 它的开销取决于这些模块的内容，而不是目录树的大小。
+
+首次导入失败后，观察租约仍由配置项持有，与立即关闭的候选资源 scope 分离。修正模块后，即使原生通知丢失，也能通过轮询恢复。重试替换观察代次，移除或禁用配置项则关闭观察 scope。
+
+`watch(paths, options)` 除了 `recursive`、`onReady` 和 `debounce` 之外，还接受
+`filter(absolutePath)`。这个谓词同时过滤原生事件和定期的内容检查。默认接受所有路径。例如：
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+CLI 对 `node_modules`
+之外的 JavaScript 和 TypeScript 模块文件使用这个过滤器。YAML 配置的变更属于加载器处理，永远不会触发对所有条目的 HMR 重载。
+
+## 失败
+
+防抖不会让文件写入变成原子操作。如果重载遇到不完整的代码，它会发出
+`Failed`，并带上原始的
+`Cause`。之后的内容变更可以触发恢复，即使没有新的原生事件。
+
+监视器 I/O 失败和对账 I/O 失败都会使流失败。所以消费者应该处理这两个失败通道。
+
+`onReady` 表示监视器已安装。它不是操作系统层面的事件投递屏障。
+
+## 何时需要重启
+
+CommonJS 和原生依赖需要重启进程。HMR 按会话的 generation 跟踪依赖信息，其中包括入口 import 完成之后、插件激活期间的动态 import。一旦 HMR 记录了这样的依赖，该 generation 之后的重载都会返回
+`Skipped`，原因是 `restart-required`。
+
+通过 `require` 加载的模块不受 ESM URL 版本的隔离，包括
+`require(esm)`。HMR 在这里很谨慎：带版本的模块只要 import 了 `node:module`（或
+`module`），HMR 就认为它获得了一种无法跟踪的原生加载能力。该依赖图会返回
+`Skipped / restart-required`，即使这个模块只用了 `node:module`
+里的其他工具。HMR 在使用之前就记录这种能力，这样可以覆盖 CommonJS 缓存命中的情况，并且在另一个入口获得同样的能力时仍然有效。需要热重载的依赖请使用静态或动态的 ESM
+import。
+
+即使没有文件通知，监听也会报告已知的原生加载重启要求，包括启动后才获取该能力的插件。周期性状态检查不会重复报告相同状态；这条警告不表示已经执行重载。
+
+本地文件入口及其可达依赖边会按代次保留请求路径、导入方和物理目标。入口和依赖共用检查逻辑及轮询数据；失败待重试的依赖图继续保留，最后一个租约释放后不再参与检查。重载在 import 之前检查这个关系，在发布任何替换之前再检查一次。如果符号链接的目标变了，重载会返回
+`Skipped / restart-required`，并附上受影响的请求 URL，所有正在运行的插件保持不变。轮询也会检查这个关系，包括内容相同的目标和漏掉的原生事件。重新指定入口或 helper 的目标之后，请重启进程。HMR 不会使 Node 的解析缓存失效。这些检查覆盖跟踪依赖图中的本地文件请求，不覆盖包的 export
+map 或裸包解析的变化。
+
+## 入口租约
+
+`importerScoped(specifier)` 是一个需要 `Scope`
+的 Effect。每次调用都持有该入口的一个租约。最后一个租约释放后，该入口不再参与之后的重载。
+
+`importerScoped(specifier, { observationScope })`
+将观察租约与候选导入的临时资源分开。`ModuleResolver`
+通过 importer 的第二个参数传递这个 scope。失败条目等待重试时应保留它，替换观察尝试或移除条目时关闭它；候选资源仍在失败时立即清理。省略该选项时使用调用方的 scope。
+
+原生 watcher 在源资源清理完成后、进入后台合并边界之前观察完整 Exit。包含失败的中断会在这里记录完整 Cause，纯中断保持安静；普通后端失败继续交给消费方处理，不重复记录。
+
+CLI 把这个 importer 传给
+`ModuleResolver`。它的入口 scope 在配置更新、激活失败或激活等待期间保持存活，并在入口被移除时关闭。
+
+轮询和重启如何与租约配合：
+
+- 轮询根据每个存活的租约确定文件集合，使用正在运行的 generation 和最近一次未提交的 import 尝试。
+- 它会保留失败的 import 和缺失的本地依赖，以便重试。
+- 当最后一个所有者关闭时，它不再读取该入口以及仅被该入口使用的依赖。
+- 成功的替换会让旧的依赖图退役。
+- 只有从被租用的入口可以到达的依赖，才可能要求重启。
+- 基于 Promise 的 `importer` 会保留它的注册，直到 HMR 会话关闭。
+
+## 替换冲突
+
+有时多个入口原本共享同一个 Plugin 对象，现在却导出了不同的对象。此时重载返回
+`Skipped`，原因是 `ambiguous-exports`，并附上受影响的模块 URL。
+
+另外两种情况会返回 `Skipped`，原因是 `identity-conflict`，并附上冲突的模块 URL：
+
+- 替换的标识有重叠，例如 `P → Q, Q → R`。
+- 映射与现有的运行时别名不一致。
+
+在所有这些情况下，都不会替换任何东西。请重启应用，或恢复一个可以表示的映射。校验与别名发布共用核心的替换事务。
+
+## 取消
+
+模块在取消期间失败时，HMR 会连同完整的 Cause 一起记录原始失败。它在待处理的中断掩盖已完成的 Exit 之前完成这一步。
+
+## 文档
+
+- [热重载](https://graftland.github.io/graft/zh-cn/hot-reload/)
+
+属于 [Graft](https://github.com/graftland/graft)。基于
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 许可。

package/README.zh-TW.md

@@ -0,0 +1,120 @@
+# @graftland/hmr
+
+[English](https://github.com/graftland/graft/blob/main/packages/hmr/README.md) |
+[简体中文](https://github.com/graftland/graft/blob/main/packages/hmr/README.zh-CN.md)
+| 繁體中文
+
+在 Node.js 上熱重載外掛模組，不需要重新啟動行程。
+
+```sh
+npm install @graftland/hmr effect
+```
+
+`Hmr.make` 為載入器提供一個 importer，同時提供 `reload` 和
+`watch`，用新程式碼取代外掛。需要 Node.js 22.19 或更新版本。
+
+## 監看檔案
+
+`watch`
+使用原生檔案系統事件，所以重載很快。它還會每秒檢查一次監看路徑內已載入的、帶版本的模組的內容，以捕捉原生後端漏掉的變更。例如：
+
+- macOS 目錄監看器的啟動空窗期
+- import 與監看器安裝之間發生的儲存
+
+檢查的運作方式：
+
+- 新載入的模組會與它的模組鉤子讀取的位元組進行比較。所以透過設定新增外掛，不會被算作檔案變更。
+- 每次磁碟觀察都與一次 import 嘗試，以及該嘗試實際讀取的位元組相關聯。
+- 較新的已提交或已失敗的嘗試會使較舊的觀察失效。所以在快照與 import 之間發生的儲存，不會讓正在執行的外掛停留在錯誤的版本上。
+- 未發生變化的失敗嘗試會保持已確認狀態，直到下一次變更。輪詢不會反覆重試它。
+- 檢查遵循 `recursive`，並在消費者關閉串流時停止。
+- 它的開銷取決於這些模組的內容，而不是目錄樹的大小。
+
+`watch(paths, options)` 除了 `recursive`、`onReady` 和 `debounce` 之外，還接受
+`filter(absolutePath)`。這個謂詞同時過濾原生事件和定期的內容檢查。預設接受所有路徑。例如：
+
+```ts
+hmr.watch([directory], {
+	recursive: true,
+	filter: (path) => path.endsWith(".mjs"),
+})
+```
+
+CLI 對 `node_modules`
+之外的 JavaScript 和 TypeScript 模組檔案使用這個過濾器。YAML 設定的變更屬於載入器處理，永遠不會觸發對所有項目的 HMR 重載。
+
+## 失敗
+
+防抖動不會讓檔案寫入變成原子操作。如果重載遇到不完整的程式碼，它會發出
+`Failed`，並帶上原始的
+`Cause`。之後的內容變更可以觸發復原，即使沒有新的原生事件。
+
+監看器 I/O 失敗和對帳 I/O 失敗都會使串流失敗。所以消費者應該處理這兩個失敗通道。
+
+`onReady` 表示監看器已安裝。它不是作業系統層級的事件投遞屏障。
+
+## 何時需要重新啟動
+
+CommonJS 和原生相依套件需要重新啟動行程。HMR 依工作階段的 generation 追蹤相依資訊，其中包括入口 import 完成之後、外掛啟用期間的動態 import。一旦 HMR 記錄了這樣的相依套件，該 generation 之後的重載都會回傳
+`Skipped`，原因是 `restart-required`。
+
+透過 `require` 載入的模組不受 ESM URL 版本的隔離，包括
+`require(esm)`。HMR 在這裡很謹慎：帶版本的模組只要 import 了 `node:module`（或
+`module`），HMR 就認為它取得了一種無法追蹤的原生載入能力。該相依圖會回傳
+`Skipped / restart-required`，即使這個模組只用了 `node:module`
+裡的其他工具。HMR 在使用之前就記錄這種能力，這樣可以涵蓋 CommonJS 快取命中的情況，並且在另一個入口取得同樣的能力時仍然有效。需要熱重載的相依套件請使用靜態或動態的 ESM
+import。
+
+即使沒有檔案通知，監聽也會回報已知的原生載入重新啟動要求，包括啟動後才取得該能力的外掛。週期性狀態檢查不會重複回報相同狀態；這條警告不表示已經執行重載。
+
+本機檔案入口及其可達相依邊會按代次保留請求路徑、匯入方和實體目標。入口和相依檔案共用檢查邏輯及輪詢資料；失敗待重試的相依圖繼續保留，最後一個租約釋放後不再參與檢查。重載在 import 之前檢查這個關係，在發布任何取代之前再檢查一次。如果符號連結的目標變了，重載會回傳
+`Skipped / restart-required`，並附上受影響的請求 URL，所有正在執行的外掛保持不變。輪詢也會檢查這個關係，包括內容相同的目標和漏掉的原生事件。重新指定入口或 helper 的目標之後，請重新啟動行程。HMR 不會使 Node 的解析快取失效。這些檢查涵蓋追蹤相依圖中的本機檔案請求，不涵蓋套件的 export
+map 或裸套件解析的變化。
+
+## 入口租約
+
+`importerScoped(specifier)` 是一個需要 `Scope`
+的 Effect。每次呼叫都持有該入口的一個租約。最後一個租約釋放後，該入口不再參與之後的重載。
+
+首次匯入失敗後，觀察租約仍由設定項目持有，與立即關閉的候選資源 scope 分離。修正模組後，即使原生通知遺失，也能透過輪詢復原。重試會取代觀察代次，移除或停用設定項目則關閉觀察 scope。
+
+`importerScoped(specifier, { observationScope })`
+將觀察租約與候選匯入的暫時資源分開。`ModuleResolver`
+透過 importer 的第二個參數傳遞這個 scope。失敗項目等待重試時應保留它，取代觀察嘗試或移除項目時關閉它；候選資源仍在失敗時立即清理。省略此選項時使用呼叫端的 scope。
+
+原生 watcher 在來源資源清理完成後、進入背景合併邊界之前觀察完整 Exit。包含失敗的中斷會在這裡記錄完整 Cause，純中斷不記錄錯誤；一般後端失敗繼續交給消費端處理，不重複記錄。
+
+CLI 把這個 importer 傳給
+`ModuleResolver`。它的入口 scope 在設定更新、啟用失敗或啟用等待期間保持存活，並在入口被移除時關閉。
+
+輪詢和重新啟動如何與租約配合：
+
+- 輪詢根據每個存活的租約決定檔案集合，使用正在執行的 generation 和最近一次未提交的 import 嘗試。
+- 它會保留失敗的 import 和缺少的本機相依套件，以便重試。
+- 當最後一個擁有者關閉時，它不再讀取該入口以及僅被該入口使用的相依套件。
+- 成功的取代會讓舊的相依圖退役。
+- 只有從被租用的入口可以到達的相依套件，才可能要求重新啟動。
+- 以 Promise 為基礎的 `importer` 會保留它的註冊，直到 HMR 工作階段關閉。
+
+## 取代衝突
+
+有時多個入口原本共用同一個 Plugin 物件，現在卻匯出了不同的物件。此時重載回傳
+`Skipped`，原因是 `ambiguous-exports`，並附上受影響的模組 URL。
+
+另外兩種情況會回傳 `Skipped`，原因是 `identity-conflict`，並附上衝突的模組 URL：
+
+- 取代的識別有重疊，例如 `P → Q, Q → R`。
+- 對應與現有的執行期別名不一致。
+
+在所有這些情況下，都不會取代任何東西。請重新啟動應用程式，或還原成一個可以表示的對應。驗證與別名發布共用核心的取代交易。
+
+## 取消
+
+模組在取消期間失敗時，HMR 會連同完整的 Cause 一起記錄原始失敗。它在待處理的中斷掩蓋已完成的 Exit 之前完成這一步。
+
+## 文件
+
+- [熱重載](https://graftland.github.io/graft/zh-tw/hot-reload/)
+
+屬於 [Graft](https://github.com/graftland/graft)。依
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 授權。