@graftland/package-manager 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,251 @@
-# Temporary Holding Version
+# @graftland/package-manager
 
-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/package-manager/README.zh-CN.md)
+|
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/package-manager/README.zh-TW.md)
+
+Installs dependencies with npm, pnpm, or Yarn, and rolls back on failure.
+
+The minimum supported Node.js version is 22.19. Windows is provided as is.
+Process-tree cleanup and rollback on Windows are not verified, and they are not
+promised.
+
+```sh
+npm install @graftland/package-manager effect
+```
+
+`make` detects the project's package manager. Its `install` adds, updates, or
+removes dependencies. If the install fails, it restores `package.json` and the
+lockfile. `graft add` and `graft remove` use it.
+
+## Installation ownership and recovery
+
+Use one manager per project. The caller must give the manager and its child
+processes exclusive write access to the project. This lasts from the start of an
+`install` call until it finishes, including recovery.
+
+- Do not edit project files during this time.
+- Do not run another installer at the same time.
+- Calls are serialized within one manager. Graft does not enforce a lock across
+  managers, editors, or processes.
+
+On POSIX, process cleanup covers only the installer's original process group.
+Installation scripts and recovery scripts must not create unmanaged writers.
+Examples are children in independent process groups, and daemons that keep
+writing project files. Graft does not provide OS-level containment. It does not
+discover escaped writers. Confirming that the original group has stopped does
+not prove that every possible descendant has stopped. Scripts that break this
+rule are outside the rollback guarantee.
+
+Managed paths must be regular files, or must be absent. `make` and each
+`install` use `lstat` to check the snapshot set. The snapshot set is
+`package.json`, lockfiles, and tracked configuration and installation-state
+files.
+
+- Symbolic links are rejected, including dangling links. Other file types are
+  rejected too.
+- The error is `UnsupportedFileTypeError`. It is raised before any transaction
+  write and before any installer starts.
+- The error shows the `path` and the `fileType`. The link and its target stay
+  unchanged.
+- A rejection before the transaction begins does not need recovery. It does not
+  make the manager unusable.
+
+### Rollback
+
+Rollback runs when installation fails or is interrupted before commit. It needs
+confirmation that the original process group has stopped. Then it does these
+things:
+
+- It restores the backed-up package files byte for byte. It keeps their recorded
+  permission bits and ownership.
+- It removes tracked files that were absent before installation.
+
+The tracked files include `package.json`, lockfiles, and the package-manager
+configuration and installation-state files that the manager tracks.
+
+Rollback overwrites changes made during installation. It does not detect
+conflicts. It does not merge edits.
+
+When the project already had a lockfile for the selected package manager,
+recovery also tries to repair `node_modules`. Recovery errors are kept together
+with the original failure. Recovery after a process crash is not promised.
+
+### File writes and process cleanup
+
+Accepted file writes have a completion boundary. Cancellation waits for the
+native operation to finish. This happens before rollback, before snapshot
+cleanup, and before the manager's lock is released. The transaction tracks its
+own file writes and the original installer group. Snapshot creation and rollback
+writes have the same completion guarantee.
+
+Each installer process and each recovery process has a ten-minute exit wait.
+Cancellation or expiry closes its process scope before files are restored.
+
+- The process receives SIGTERM.
+- If it has not stopped after five seconds, it receives SIGKILL.
+- On POSIX, even a successful kill must be followed by evidence that the
+  original process group no longer exists. Checks run every 20 milliseconds,
+  with at most 100 additional checks (two seconds of waiting) for short-lived
+  zombie groups to be reaped. EPERM is treated as continued presence, never as
+  absence.
+- If the group remains or a check fails, termination is unconfirmed: the manager
+  keeps its snapshot, skips rollback and recovery, and enters
+  `RecoveryRequired`.
+- Process cleanup failures stay in the returned cause, together with
+  installation and recovery failures.
+- The exit timeout does not include process cleanup or file restoration. It is
+  not a deadline for the whole install-and-recover operation.
+
+The Node adapter may replace the original OS errno with a generic kill failure.
+Only after a POSIX group check confirms absence does PackageManager resolve
+signal failures carrying ESRCH or the adapter's specific `Unknown` kill error
+with cause `Failed to kill child process`. This does not resolve other reasons
+in the same Cause: join failures, other kill errors, defects, and interruption
+remain failures. If the group still exists, the original Cause is preserved; if
+the group check fails, both complete Causes are retained.
+
+## Committed installs and snapshot cleanup
+
+A successful `install` result means the dependency changes are committed.
+
+`result.snapshotCleanupFailure` is an `Option<SnapshotCleanupFailure>`:
+
+- `None` means snapshot deletion succeeded.
+- `Some` contains `snapshotDirectory` and the complete cleanup `cause`,
+  including defects.
+
+A failure to delete the snapshot after commit does not turn the install into a
+failure. It does not trigger rollback. The manager stays usable, and
+`recoveryRequired` stays `None`.
+
+What callers should do:
+
+- Inspect this field. Report or record its Cause.
+- Retry the deletion of that snapshot directory after the filesystem problem is
+  fixed. The directory may be partly removed.
+- Do not restore the old snapshot. Do not repeat the install only because
+  snapshot deletion failed. Those changes are already committed.
+- The kept data may contain credentials, so make sure it is removed in the end.
+
+Failures before commit still fail the operation and run rollback. Any snapshot
+cleanup failure is combined with the original failure.
+
+Cancellation can stop a result from being delivered after commit. It is not
+proof that the changes were undone. In that case, cleanup failures are kept in
+the interrupted Cause.
+
+## When manual recovery is required
+
+Before an install changes project files, it saves a snapshot. The snapshot is in
+a private `graft-recovery-*` directory in the OS temporary directory.
+
+- Only a successful install or a complete rollback allows the snapshot to be
+  deleted and another install to run.
+- A committed install with a failed snapshot deletion is reported as described
+  above.
+- Process termination and transaction completion are separate conditions.
+  Stopping the writer lets rollback begin. It does not prove that rollback
+  succeeded.
+
+If any rollback step fails, the manager keeps the snapshot and needs manual
+recovery. This includes restoring files before or after recovery, and running
+the recovery installer. It applies even when the final file restoration
+succeeds, because failed recovery may have left `node_modules` incomplete.
+
+How the manager restores a file:
+
+1. It creates a temporary file in the target directory, exclusively and with
+   mode `0600`.
+2. It restores the saved uid/gid when the platform reports them. Then it
+   restores the permission bits.
+3. It syncs and closes the file.
+4. It renames the file over the target.
+
+Metadata failures and temporary-file cleanup failures also need manual recovery.
+They stay in the Cause. Timestamps, ACLs, and extended attributes are not
+recorded.
+
+If process termination cannot be confirmed, no further restoration or recovery
+runs. This avoids a conflict with a process that may still be writing.
+
+### The recovery error
+
+The Cause of the failed call keeps the original failure and all rollback and
+termination failures. It includes a `RecoveryRequiredError`, which has these
+fields:
+
+- `snapshotDirectory` gives the saved location.
+- `directory` identifies the project.
+- `recoveryCause` keeps the complete original and recovery Cause.
+- `operation` is `rollback` for an incomplete rollback with stopped writers. For
+  unconfirmed termination, it is `install` or `recover`. In that case,
+  `processId` and `terminationCause` give the process details.
+
+After cancellation, callers can also read `manager.recoveryRequired`. It is an
+Effect that yields `Option<RecoveryRequiredError>`. Callers do not need to catch
+an interrupted call.
+
+The manager rejects all later `install` calls for good, with this typed error.
+This includes calls that are already queued and calls with empty change sets.
+`readState` stays a read-only diagnostic operation. It may fail while project
+files are incomplete.
+
+### Steps to recover manually
+
+1. Identify the failed installer and all of its descendants, and stop them. The
+   recorded process ID is for diagnosis only. It does not prove that a later
+   process with the same ID belongs to the installation. Do not restore files or
+   start another installer until all writers have stopped.
+2. Fix the filesystem problem that stopped the restoration, such as file
+   permissions. Then restore the files:
+   - Open `snapshot.json` in `snapshotDirectory`. Check its project `directory`
+     and `agent`.
+   - For each `files` entry, copy the bytes from the named `backup` into a
+     temporary file beside the project's `name`. Create the temporary file
+     privately and exclusively.
+   - Restore the recorded `uid` and `gid` when they are not null. Then restore
+     `mode`. Do this before you replace the target.
+   - These metadata values are JSON integers. `mode` is the numeric permission
+     bitmask, not an octal-formatted string.
+   - Create parent directories as needed.
+   - A null `backup` means that the file was absent. Remove it if it exists now.
+3. Repair `node_modules` with the selected package manager. Use the restored
+   manifest and lockfile. After that process has stopped, restore the snapshot
+   files again if it rewrote them. The snapshot does not contain `node_modules`.
+4. Verify the project. Then delete the snapshot and create a new manager with
+   `make`. The old manager has no reset operation.
+
+Snapshots can contain credentials from package-manager configuration files. Keep
+them private. They survive the closing of the manager and of the Effect scope.
+But the OS may clean temporary directories. If manual recovery will be delayed,
+copy a kept snapshot to a safe, private place.
+
+This mechanism is not crash recovery. It is not a project lock across processes.
+Creating a new manager does not make a still-live installer safe.
+
+## Documentation
+
+- [Command line](https://graftland.github.io/graft/cli/)
+
+Part of [Graft](https://github.com/graftland/graft). Licensed under
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE).
+
+## Package manager declarations
+
+The shared `PackageManagerDeclaration` Schema accepts `npm`, `pnpm`, or `yarn`
+followed by an exact SemVer version (at most 256 characters), including optional
+prerelease identifiers. It rejects empty suffixes, leading zeros in numeric
+version/prerelease components, ranges, tags, URLs, and surrounding whitespace. A
+`+` suffix is reserved for a
+[Corepack hash](https://github.com/nodejs/corepack#when-authoring-packages):
+`sha224`, `sha256`, `sha384`, or `sha512`, followed by a dot and exactly 56, 64,
+96, or 128 lowercase hexadecimal characters respectively. Arbitrary SemVer build
+metadata is not supported here. Hash validation checks the declaration's syntax;
+it does not download or authenticate the package-manager archive.
+
+Both project creation and package-manager detection use this Schema, exported
+from `@graftland/package-manager/PackageManagerDeclaration`. Creation preserves
+the supplied declaration verbatim. An explicit detection `agent` still overrides
+the manifest declaration.

package/README.zh-CN.md

@@ -0,0 +1,183 @@
+# @graftland/package-manager
+
+[English](https://github.com/graftland/graft/blob/main/packages/package-manager/README.md)
+| 简体中文 |
+[繁體中文](https://github.com/graftland/graft/blob/main/packages/package-manager/README.zh-TW.md)
+
+使用 npm、pnpm 或 Yarn 安装依赖，并在失败时回滚。
+
+支持的最低 Node.js 版本是 22.19。Windows 按现状提供。Windows 上的进程树清理和回滚没有经过验证，也不作承诺。
+
+```sh
+npm install @graftland/package-manager effect
+```
+
+`make` 会检测项目所用的包管理器。它的 `install`
+可以添加、更新或移除依赖。如果安装失败，它会恢复 `package.json`
+和锁文件。`graft add` 和 `graft remove` 使用它。
+
+## 安装的所有权与恢复
+
+每个项目只使用一个管理器。调用方必须让管理器及其子进程独占项目的写入权限。这从一次
+`install` 调用开始，持续到它结束，包括恢复阶段。
+
+- 在此期间，不要编辑项目文件。
+- 不要同时运行另一个安装程序。
+- 同一个管理器内的调用是串行的。Graft 不会在多个管理器、编辑器或进程之间强制加锁。
+
+在 POSIX 上，进程清理只覆盖安装程序最初的进程组。安装脚本和恢复脚本不得创建不受管理的写入者。例如，处于独立进程组的子进程，以及持续写入项目文件的守护进程。Graft 不提供操作系统级别的隔离，也不会发现逃逸的写入者。确认最初的进程组已经停止，并不能证明所有可能的后代都已经停止。违反这条规则的脚本不在回滚保证的范围内。
+
+受管理的路径必须是普通文件，或者不存在。`make` 和每次 `install` 都使用 `lstat`
+检查快照集合。快照集合包括
+`package.json`、锁文件，以及被跟踪的配置文件和安装状态文件。
+
+- 符号链接会被拒绝，包括悬空链接。其他文件类型也会被拒绝。
+- 错误是
+  `UnsupportedFileTypeError`。它在任何事务写入之前、任何安装程序启动之前抛出。
+- 错误会给出 `path` 和 `fileType`。链接及其目标保持不变。
+- 在事务开始之前的拒绝，不需要恢复，也不会让管理器不可用。
+
+### 回滚
+
+当安装在提交之前失败或被中断时，会执行回滚。回滚需要先确认最初的进程组已经停止。然后它会做这些事：
+
+- 把已备份的包文件逐字节恢复，并保留它们记录下来的权限位和所有者。
+- 移除安装之前不存在的被跟踪文件。
+
+被跟踪的文件包括
+`package.json`、锁文件，以及管理器所跟踪的包管理器配置文件和安装状态文件。
+
+回滚会覆盖安装期间所做的更改。它不会检测冲突，也不会合并编辑。
+
+如果项目已经有所选包管理器的锁文件，恢复阶段还会尝试修复
+`node_modules`。恢复错误会与原始失败一起保留。不承诺在进程崩溃之后恢复。
+
+### 文件写入与进程清理
+
+已接受的文件写入有一个完成边界。取消会等待原生操作完成，然后才进行回滚、清理快照，以及释放管理器的锁。事务会跟踪它自己的文件写入以及最初的安装程序进程组。创建快照和回滚写入也有同样的完成保证。
+
+每个安装进程和每个恢复进程都有十分钟的退出等待时间。取消或超时会在恢复文件之前关闭它的进程 scope。
+
+- 进程会收到 SIGTERM。
+- 如果五秒后它还没有停止，就会收到 SIGKILL。
+- 在 POSIX 上，即使 kill 成功，也必须确认原进程组已不存在。每 20 毫秒检查一次，最多追加 100 次检查（等待两秒），给短暂残留的僵尸进程组留出回收窗口。EPERM 视为仍然存在，不视为已消失。
+- 如果进程组仍存在或检查失败，则终止未获确认：管理器保留快照，不执行回滚和恢复安装，并进入
+  `RecoveryRequired`。
+- 进程清理失败会与安装和恢复的失败一起保留在返回的 cause 中。
+- 退出超时不包括进程清理和文件恢复，也不是整个“安装并恢复”操作的截止时间。
+
+Node 适配器可能会把原始的操作系统 errno 替换为通用的 kill 失败。只有 POSIX 检查确认进程组不存在后，PackageManager 才消解携带 ESRCH 的信号失败，或适配器特定的
+`Unknown` kill 错误（cause 为
+`Failed to kill child process`）。同一 Cause 中的其他原因仍然保留，包括 join 失败、其他 kill 错误、defect 和中断。进程组仍存在时保留原始 Cause；检查失败时保留两个完整 Cause。
+
+## 已提交的安装与快照清理
+
+`install` 成功的结果表示依赖更改已经提交。
+
+`result.snapshotCleanupFailure` 是 `Option<SnapshotCleanupFailure>`：
+
+- `None` 表示快照删除成功。
+- `Some` 包含 `snapshotDirectory` 和完整的清理 `cause`，包括 defect。
+
+提交之后删除快照失败，不会让这次安装变成失败，也不会触发回滚。管理器仍然可用，`recoveryRequired`
+仍然是 `None`。
+
+调用方应该这样做：
+
+- 检查这个字段，报告或记录它的 Cause。
+- 在文件系统问题解决之后，重试删除该快照目录。该目录可能已被部分删除。
+- 不要恢复旧的快照，也不要仅仅因为快照删除失败就重复安装。那些更改已经提交了。
+- 保留下来的数据可能包含凭据，所以要确保它最终被删除。
+
+提交之前的失败仍然会使操作失败并执行回滚。任何快照清理失败都会与原始失败合并。
+
+取消可能会使提交之后的结果无法送达。这并不能证明更改已被撤销。这种情况下，清理失败会保留在被中断的 Cause 中。
+
+## 何时需要手动恢复
+
+在安装更改项目文件之前，会先保存一份快照。快照位于操作系统临时目录中一个私有的
+`graft-recovery-*` 目录里。
+
+- 只有成功的安装或完整的回滚，才允许删除快照并运行下一次安装。
+- 已提交但快照删除失败的安装，按上文所述报告。
+- 进程终止和事务完成是两个独立的条件。停止写入者，回滚才能开始，但这并不证明回滚成功。
+
+只要有任何一个回滚步骤失败，管理器就会保留快照，并需要手动恢复。这包括在恢复之前或之后恢复文件，以及运行恢复安装程序。即使最后的文件恢复成功，这条规则也适用，因为失败的恢复可能让
+`node_modules` 不完整。
+
+管理器如何恢复一个文件：
+
+1. 在目标目录中以独占方式创建临时文件，模式为 `0600`。
+2. 当平台报告了保存的 uid/gid 时，先恢复它们，然后恢复权限位。
+3. 对文件执行 sync 并关闭。
+4. 把该文件重命名覆盖到目标上。
+
+元数据失败和临时文件清理失败同样需要手动恢复，并保留在 Cause 中。时间戳、ACL 和扩展属性不会被记录。
+
+如果无法确认进程已经终止，就不会再进行任何恢复。这是为了避免与可能仍在写入的进程发生冲突。
+
+### 恢复错误
+
+失败调用的 Cause 会保留原始失败以及所有回滚和终止的失败。它包含一个
+`RecoveryRequiredError`，其字段如下：
+
+- `snapshotDirectory` 给出保存的位置。
+- `directory` 标识项目。
+- `recoveryCause` 保留完整的原始 Cause 和恢复 Cause。
+- `operation`：在写入者已停止但回滚不完整时是 `rollback`；在无法确认终止时是
+  `install` 或 `recover`，此时 `processId` 和 `terminationCause`
+  给出进程的详细信息。
+
+取消之后，调用方还可以读取 `manager.recoveryRequired`。它是一个产出
+`Option<RecoveryRequiredError>` 的 Effect。调用方不需要去捕获被中断的调用。
+
+管理器会永久拒绝之后所有的 `install`
+调用，并返回这个带类型的错误。这包括已经排队的调用，以及变更集为空的调用。`readState`
+仍然是只读的诊断操作。在项目文件不完整时，它可能失败。
+
+### 手动恢复的步骤
+
+1. 找出失败的安装程序及其所有后代，并停止它们。记录下来的进程 ID 只用于诊断，不能证明之后具有相同 ID 的进程属于这次安装。在所有写入者停止之前，不要恢复文件，也不要启动另一个安装程序。
+2. 解决阻止恢复的文件系统问题，例如文件权限。然后恢复文件：
+   - 打开 `snapshotDirectory` 中的 `snapshot.json`。检查其中的项目 `directory`
+     和 `agent`。
+   - 对每个 `files` 条目，把指定的 `backup` 中的字节复制到项目 `name`
+     旁边的临时文件中。以私有、独占的方式创建该临时文件。
+   - 当 `uid` 和 `gid` 不为 null 时，恢复记录下来的值，然后恢复
+     `mode`。请在替换目标之前完成这些。
+   - 这些元数据值是 JSON 整数。`mode`
+     是数值形式的权限位掩码，不是八进制格式的字符串。
+   - 按需创建父目录。
+   - `backup` 为 null 表示该文件原本不存在。如果它现在存在，就删除它。
+3. 使用所选的包管理器，基于已恢复的清单文件和锁文件修复
+   `node_modules`。该进程停止之后，如果它重写了快照中的文件，请再次恢复这些文件。快照不包含
+   `node_modules`。
+4. 验证项目。然后删除快照，并用 `make`
+   创建一个新的管理器。旧的管理器没有重置操作。
+
+快照可能包含来自包管理器配置文件的凭据。请保持私有。它们在管理器和 Effect
+scope 关闭之后依然存在。但是操作系统可能会清理临时目录。如果手动恢复会被推迟，请把保留的快照复制到一个安全的私有位置。
+
+这个机制不是崩溃恢复，也不是跨进程的项目锁。创建新的管理器，并不会让仍在运行的安装程序变得安全。
+
+## 文档
+
+- [命令行](https://graftland.github.io/graft/zh-cn/cli/)
+
+属于 [Graft](https://github.com/graftland/graft)。基于
+[Apache 2.0](https://github.com/graftland/graft/blob/main/LICENSE) 许可。
+
+## 包管理器声明
+
+共享的 `PackageManagerDeclaration` Schema 接受 `npm`、`pnpm` 或
+`yarn`，后跟精确的 SemVer 版本（版本部分最多 256 个字符），可包含预发布标识。它拒绝空后缀、版本及预发布数字标识的前导零、版本范围、标签、URL 和首尾空白。
+
+`+` 后缀仅用于
+[Corepack hash](https://github.com/nodejs/corepack#when-authoring-packages)：支持
+`sha224`、`sha256`、`sha384`、`sha512`，后跟点号及分别为 56、64、96、128 个字符的小写十六进制摘要。不支持普通 SemVer
+build metadata。这里只校验声明语法，不下载或验证包管理器压缩包的真实性。
+
+创建项目与检测包管理器使用同一个 Schema，可从
+`@graftland/package-manager/PackageManagerDeclaration`
+导入。创建时逐字保留传入的声明；检测时显式指定的 `agent`
+仍优先于 manifest 声明。