autoupdate

type Device struct {
	ID   string
	Name string
	// Version is the build the device reports. Empty or the legacy placeholder
	// means it has not told us, which Plan treats as "leave alone".
	Version string
	// ProtocolVersion is the negotiated session version, used to tell a device
	// that can be upgraded remotely from one that must be done by hand.
	ProtocolVersion int
	// AgentProtocol is the protocol the agent advertised at hello — more than
	// ProtocolVersion when the device is newer than the hub. A target speaking
	// less than the larger of the two would move the device backwards.
	AgentProtocol int
	// Online is whether there is a live session to send the request on.
	Online bool
	// Busy is whether the device is running work right now.
	Busy bool
	// AdminHeld is whether an operator has cordoned or drained it.
	AdminHeld bool
	// Upgrading is whether this device has already been asked and has not yet
	// come back. It is what keeps MaxInFlight meaningful across sweeps.
	Upgrading bool
	// Channel is the update channel the device reports: "edge" lets it follow
	// the hub's own build, anything else is releases only (Task 20376).
	Channel string
	// Sequence is the device's build's place on main (Task 20380), zero when
	// it carries none. Its installer refuses anything earlier, so the planner
	// never asks for it.
	Sequence int
}

type Hub struct {
	Version  string
	Protocol int
	// Edge is what CI published of the hub's own build (Task 20376): nil when
	// the hub runs a release or a build no edge build can match, else whether
	// "edge:<commit>" exists and the protocol its manifest claims. It is what
	// "match the hub" means for a device on the edge channel.
	Edge *executor.EdgeBuild
}

type Policy struct {
	// Enabled turns automatic upgrades on. Off by default, and deliberately:
	// a hub that silently reboots edge devices because it was installed with a
	// helpful default is a hub nobody trusts with hardware.
	Enabled bool `json:"enabled"`

	// TargetVersion is the release every device should converge on. Empty
	// means the control plane's own build, which is the sane default — the
	// hub and its agents are two halves of one protocol, and "match the hub"
	// is the invariant an operator actually wants.
	//
	// A pinned tag is honoured as written, including when it is older than the
	// hub: staged rollouts and rollbacks both need the fleet to sit on a
	// version the control plane is not running.
	TargetVersion string `json:"target_version,omitempty"`

	// MaxInFlight bounds concurrent upgrades. Zero uses DefaultMaxInFlight.
	MaxInFlight int `json:"max_in_flight,omitempty"`
}

type Verdict struct {
	Device Device
	// Upgrade is whether to send the request now.
	Upgrade bool
	// Target is what to ask this device for when Upgrade is set. Per device,
	// because "match the hub" is the hub's edge build for a device on the edge
	// channel and is refused outright for one that is not.
	Target string
	// Reason explains the decision either way, in the operator's terms. It is
	// shown in the UI beside the device, so a fleet that is not converging can
	// be understood without reading logs.
	Reason string
}