[Jason Wilder (jwilder)]

Summary

Add a reviewable HostUpgrade specification and design in designs/host-upgrade.md as the basis for a later implementation plan.

• Define agent-owned host updates that preserve identity and avoid unnecessary HostReplace downtime, including GPU validation costs.
• Select the backend per MachineOperation and delegate native updates to adapters for package managers, RAUC, Trident, and future integrations such as Ubuntu Core, Mender, and OSTree.
• Describe package selection through OS-specific channels, including security-only updates, and named installed packages.
• Simplify operation controls to rebootPolicy and restartNode, with recovery timing and rollback configured per backend.
• Cover durable execution, restart/reboot recovery, A/B confirmation and fallback, maintenance coordination, status, and security boundaries.
• Include illustrative requests, current-code references, verification criteria, and open decisions for human review.

Validation

• Validated all five YAML examples and their simplified request fields.
• Checked 20 repository source references and line ranges.
• Checked all 18 numbered sections, Markdown fences, whitespace, and repository text conventions.
• git diff --cached --check passed before commit.

[Jordan Olshevski (jveski)]

The API makes sense, I don't have any concerns. 🚢