Deployment recovery

当资源或部署记录指向的来源不再可访问，或者用户需要把资源切换到新的仓库、路径或镜像时，source relink 是显式恢复动作。

执行前确认目标资源、当前来源、新来源和预期环境。执行后通过下一次部署或资源详情确认 Appaloft 读取的是新的来源。

不要把 relink 当成普通重试。Relink 会改变后续部署读取的 source，适合处理仓库迁移、目录重组、镜像来源变化或本地 source 指纹失效。

Preview cleanup 用于删除某个 pull request、分支或临时来源产生的预览部署。清理对象必须由 preview 类型和 preview id 定位，不能误删生产环境或普通部署历史。

清理后应检查：

• 预览部署实例是否停止。
• 预览访问地址是否不再展示为有效入口。
• 生产部署和普通历史记录是否未被影响。
• 后续同一 preview id 是否可以重新创建。

当部署失败、被取消或观察流中断时，先读取恢复就绪，而不是直接执行重试或回滚：

appaloft deployments recovery-readiness <deploymentId>

这个查询只读。它会返回：

• recoverable、retryable、redeployable、rollbackReady 等机器可读字段。
• retry、redeploy、rollback 三类动作的阻塞原因，以及 active attempt 是否适合取消的上下文。
• 可用的 rollback candidates，以及候选是否缺少 artifact 或快照。
• 安全的下一步建议，例如查看详情、日志、事件流或诊断摘要。

当前 retry、redeploy、rollback 和 active-attempt cancel 写命令已启用。当 readiness 返回缺少快照、缺少 artifact、readiness 过期、运行时正在被占用或候选不兼容时，恢复命令仍会被阻塞。

Agent 不应该在失败后直接重试。它应先读取 recovery readiness，并把阻塞原因、可用候选和安全下一步返回给用户。只有 readiness 明确允许时，才建议 retry、redeploy 或 rollback。

如果 readiness 要求先看日志或诊断摘要，agent 应返回对应命令，而不是直接修改运行时、远端状态或 secret。

Retry 的语义是“基于失败部署的不可变 snapshot intent 创建新的部署 attempt”。它不是重放旧事件，也不是在旧 attempt 中继续执行失败阶段。

检查 readiness 后，可以运行 appaloft deployments retry <deploymentId>，或调用 POST /api/deployments/{deploymentId}/retry。

Redeploy 的语义是“使用当前 Resource profile 再部署一次”。它会读取当前资源配置、环境配置、target 和 destination，不复用旧部署快照。

如果当前 Resource profile 缺失、漂移或不再能通过 admission，readiness 会把 redeploy 标记为阻塞。

检查 readiness 后，可以运行 appaloft deployments redeploy <resourceId>，或调用 POST /api/resources/{resourceId}/redeploy。

Rollback 的语义是“基于历史成功部署的 snapshot 和 Docker/OCI artifact 创建新的 rollback attempt”。它不会从当前 Resource profile 重新 plan，也不会恢复数据库、volume、队列或外部依赖状态。

检查 readiness 并选择 rollback-ready candidate 后，可以运行 appaloft deployments rollback <deploymentId> --candidate <candidateDeploymentId>，或调用 POST /api/deployments/{deploymentId}/rollback。

Cancel 用于停止一个尚未完成的 deployment attempt。它不会删除部署历史、日志、事件、runtime artifact、route intent、Resource 或环境配置。

运行 appaloft deployments cancel <deploymentId> --confirm <deploymentId>，或调用 POST /api/deployments/{deploymentId}/cancel。--confirm 必须和 deployment id 完全一致；已经成功、失败、取消或回滚的 terminal attempt 会被拒绝。

Archive 会把一个 terminal deployment attempt 从默认历史列表隐藏起来，但不会删除日志、事件、runtime artifact、provider job log、audit row、route state、rollback candidate 或 operator-work evidence。运行 appaloft deployments archive <deploymentId> --confirm <deploymentId>，或调用 POST /api/deployments/{deploymentId}/archive。

Prune 默认只是 dry-run。运行 appaloft deployments prune --before <iso>，或调用 POST /api/deployments/prune。破坏性清理必须显式传入 dryRun: false，并且只会删除早于 cutoff、已经归档、处于 terminal 状态、且没有 source/retry/rollback/supersede/provider-log/runtime-log/runtime-control 保留引用的 attempt。

rollback candidate 必须是同一资源下的历史成功部署，并且仍保留必要信息：

• deployment snapshot；
• environment snapshot；
• runtime target / destination identity；
• Docker/OCI artifact identity，例如 image、digest、local image id 或 Compose artifact。

如果 artifact 已被清理、快照不完整、target 不兼容，或恢复需要数据/volume 回滚，readiness 会返回阻塞原因并建议改选候选、重新部署或先做诊断。

输入校验失败应先修正输入。执行阶段临时失败可以重试。verify 失败要先看健康摘要和日志，再决定修复配置、重试或回滚。

推荐判断：

Web console 会把恢复动作放在部署状态附近。CLI 适合 preview cleanup、source relink、retry、redeploy、rollback 和 cancel。HTTP API 应暴露可机器判断的状态、错误 code 和恢复建议。

恢复动作不应该要求用户直接修改数据库或手动删除运行时状态。