Define failure handling task (T-303)

docs/api.md

@@ -220,7 +220,29 @@ T-302 在 Switcher 的 health 阶段先运行必需的注入 health check，再
 
 这些栅栏与注入失败测试只证明代码层面的调用顺序和 fail-closed 行为,不证明断电后硬件/驱动缓存、网络文件系统、文件锁或杀毒软件的物理表现。T-302 已完成代码整合；T-601 仍须在目标 Windows VM/真机执行断电与干扰故障注入。
 
-### 2.6 下载任务元数据 download-task.json(本地)
+### 2.6 安装预检与失败码
+
+在同句柄 size/SHA、ZIP 预扫描和严格 `app.json` 身份比对均通过后，提取器会在创建 `staging/` 前提供已规划 payload 的准确展开字节数、普通文件数和安全 entrypoint。安装 use case 必须以 `payload_bytes + 64 MiB` 查询 app root 所在卷的可用空间；可用空间不足时不创建 staging。预检不能替代写入、同步、切换或回滚阶段的 fail-closed I/O 错误处理。
+
+安装 use case 同时在上述位置检查当前 `current/<entrypoint>` 是否正在运行。容量与运行状态均通过 core 接口注入；检查失败按不可安全继续处理。v1 不强杀、不启动、不等待进程退出。Windows Toolhelp 枚举、正常退出等待与启动协议属于后续 T-401，不能进入 core。
+
+安装结果面向调用方的错误码为下表的稳定英文枚举；UI 负责本地化，原始错误只保留给 `errors.Is`、日志和诊断，不得进入 UI payload。
+
+| code | 含义 |
+| --- | --- |
+| `hash_mismatch` | 完成文件长度或 SHA-256 与已验签 Catalog selection 不符 |
+| `zip_path_escape` | ZIP/app manifest 路径违反共享 Windows 安全相对路径规则 |
+| `zip_corrupt` | ZIP 结构、CRC 或受限读取/提取不完整，不能作为有效包 |
+| `package_invalid` | package/app manifest 身份或协议不符合可信 selection |
+| `disk_full` | 可用空间小于 `payload_bytes + 64 MiB` |
+| `disk_check_failed` | 无法可靠取得可用空间或得到非法容量值 |
+| `app_running` | 当前目标程序仍在运行，更新不能替换 |
+| `target_state_unavailable` | 无法可靠取得目标运行状态 |
+| `install_failed` | 其他未细分的安装、健康、记录、切换或回滚失败 |
+
+上述任一预检或验证失败都发生在 switch 前；已有版本的 `current` 和 `installed-app.json` 必须保持可用，首次安装不得留下 executable `current`。
+
+### 2.7 下载任务元数据 download-task.json(本地)
 
 每个任务以稳定 `request_id` 为主键,元数据位于 `downloads/tasks/<request_id>.json`,字节文件位于 `downloads/files/<request_id>.part|.download`。本地路径只由客户端从 request_id 派生,不接受 URL 或 Content-Disposition 提供的文件名。