@graftland/package-manager 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,14 +1,229 @@
 # @graftland/package-manager
 
-Installs dependencies with npm, pnpm or Yarn, and rolls back on failure.
+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, and restores `package.json` and the lockfile if installing
-fails. `graft add` and `graft remove` use it.
+`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
 
@@ -16,3 +231,21 @@ fails. `graft add` and `graft remove` use it.
 
 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 声明。

package/README.zh-TW.md

@@ -0,0 +1,184 @@
+# @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-CN.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-tw/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 宣告。

package/dist/PackageManagerDeclaration.d.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export declare const PackageManagerName: Schema.Literals<readonly ["npm", "pnpm", "yarn"]>;
+/** Exact SemVer with optional prerelease and Corepack hash; ranges, URLs and arbitrary build metadata are unsupported. */
+export declare const PackageManagerDeclaration: Schema.TemplateLiteralParser<readonly [Schema.Literals<readonly ["npm", "pnpm", "yarn"]>, "@", Schema.decodeTo<Schema.SemVerFromString, Schema.String, never, never>]>;
+export type PackageManagerDeclaration = typeof PackageManagerDeclaration.Type;
+//# sourceMappingURL=PackageManagerDeclaration.d.ts.map

package/dist/PackageManagerDeclaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageManagerDeclaration.d.ts","names":[],"sources":["../src/PackageManagerDeclaration.ts"],"mappings":";qBAEa,oBAAkB,OAAA;;qBAkClB,2BAAyB,OAAA,gCAAA,OAAA,iDAAA,OAAA,SAAA,OAAA,kBAAA,OAAA;YAK1B,mCAAmC,0BAA0B"}

package/dist/PackageManagerDeclaration.js

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+// src/PackageManagerDeclaration.ts
+const PackageManagerName = Schema.Literals([
+	"npm",
+	"pnpm",
+	"yarn"
+]);
+const CorepackHash = Schema.Union([
+	Schema.Tuple([Schema.Literal("sha224"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{56}$/))]),
+	Schema.Tuple([Schema.Literal("sha256"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/))]),
+	Schema.Tuple([Schema.Literal("sha384"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{96}$/))]),
+	Schema.Tuple([Schema.Literal("sha512"), Schema.String.check(Schema.isPattern(/^[0-9a-f]{128}$/))])
+]);
+const isCorepackHash = Schema.is(CorepackHash);
+const Version = Schema.String.check(Schema.isMaxLength(256)).pipe(Schema.decodeTo(Schema.SemVerFromString)).check(Schema.makeFilter((version) => version.build.length === 0 || isCorepackHash(version.build), { expected: "no build metadata, or a Corepack sha224/sha256/sha384/sha512 lowercase hexadecimal hash" }));
+/** Exact SemVer with optional prerelease and Corepack hash; ranges, URLs and arbitrary build metadata are unsupported. */
+const PackageManagerDeclaration = Schema.TemplateLiteralParser([
+	PackageManagerName,
+	"@",
+	Version
+]);
+export { PackageManagerDeclaration, PackageManagerName };
+
+//# sourceMappingURL=PackageManagerDeclaration.js.map