Implement app update orchestration (T-402)

docs/api.md

@@ -382,6 +382,24 @@ SoftBoxUpdater.exe --pid <主程序PID> --staging <暂存目录> --target <目
 v1:进程快照判断运行 → 提示用户保存关闭 → 等待正常退出 → 超时取消更新,**不默认强杀**。
 V1.1:命名管道 `\\.\pipe\softbox.<app-id>`,盒子发送 `{"command": "prepare_update", "request_id": "..."}`,子软件保存数据回复 `ready` 后自行退出。
 
+### 6.1 子软件更新编排 v1
+
+`core/application/update` 只接受外层已经从验证/过滤 Catalog 取得的 `install.InstallRequest`，并再次要求 package 与 architecture 精确匹配。它先读取受控本地 `installed-app.json` + `current`，要求旧记录有完整且安全的启动元数据，并且 Catalog 目标版本严格高于本地 SemVer；不得由 UI 或下载事件提供 EXE、路径、参数、URL、版本或 hash。
+
+若旧 entrypoint 未运行，编排直接委托 `InstallService`；若运行，则顺序固定为：后台取得关闭确认 → 按配置的 1 秒至 10 分钟上限等待**自然退出** → 委托 `InstallService`。等待器仅轮询 T-401 的完整 entrypoint 身份，支持 context 取消；不能调用 kill/TerminateProcess、shell、脚本或 IPC。等待完成后安装器仍在 staging 前和 `current → backup` 紧邻前复查运行状态，因此用户重新启动旧版本会安全返回既有 `app_running`，不覆盖 current。
+
+| code | 含义 |
+| --- | --- |
+| `not_installed` | 没有受控安装记录 |
+| `update_metadata_invalid` / `update_target_unsafe` | 历史记录缺启动元数据，或旧 entrypoint/current 布局不安全 |
+| `update_not_available` | Catalog 版本与本地相同或更低 |
+| `target_state_unavailable` | 无法可靠判定旧 entrypoint 是否运行 |
+| `close_confirmation_unavailable` / `close_declined` | 无法取得关闭确认，或用户拒绝关闭 |
+| `exit_wait_canceled` / `exit_wait_timeout` / `exit_wait_unavailable` | 等待被取消、达到上限，或进程快照等待不可用 |
+| `install_failed` | 已委托安装器但安装失败；原始 `InstallError` 链仍保留其 stage/code |
+
+更新编排自身不写 `current`、`backup`、transaction、`data/` 或 `licenses/`。production cmd 目前没有可信 Catalog、许可证和 completed-download 消费来源，也没有关闭确认 UI，因此尚未装配该用例；不得用 allow-all 授权或测试 fake 宣称更新闭环已经启用。
+
 ## 待实现时确认
 
 - 清单密钥 ID/轮换字段定稿后同步 `schemas/`。