[Unique-Divine]

Let compatible patches yield to later chain upgrades

Add compatiblePatch so a node can run a compatible binary now and automatically select the next active upgrade image. For example, a snapshot observer can use 2.21.2 during the current 2.21 upgrade period without a permanent version pin.

Rationale

overrideVersion takes precedence over all upgrade history and persists on individual ChainNodes after group removal. It is unsuitable for a compatible patch that should be superseded by a future governance upgrade. The new setting identifies the existing upgrade period by height; it does not schedule an on-chain upgrade or infer consensus compatibility from a version number.

Key Changes

1. Add optional compatiblePatch: {version, upgradeHeight} to ChainNodes, node groups and validator configuration. Height 0 identifies the initial genesis period.
2. Apply the patch only when its height matches the upgrade selected by existing rules. Scheduled upgrades leave it active; ongoing, completed or skipped later upgrades supersede it as appropriate for the existing selector.
3. Propagate group updates and removal, generate CRDs/deepcopy/reference docs, and validate a nonempty version and nonnegative height.
4. Retain legacy override precedence and document the controlled one-time migration needed for existing pins.

1 - Upgrade and restart behavior

current upgrade period + matching patch -> compatible patch image
future upgrade merely scheduled        -> keep compatible patch image
later upgrade becomes active           -> later upgrade image
pod recreated with obsolete patch      -> keep later upgrade image

Unit coverage checks exact height matching, genesis, unordered history, scheduled and missing-image upgrades, ongoing/completed/skipped upgrades, legacy precedence, and state-sync selection. Controller coverage rebuilds a pod from persisted completed-upgrade status with the obsolete setting still present. All 50 integration specs pass, including real-API validation and group propagation/removal.

Existing governance E2E cases now retain a genesis-period patch on the observer, perform their real upgrade, delete that pod, and verify its replacement keeps the new image and resumes block progress. They reuse the source image as the patch to avoid requiring another compatible release fixture. The full Docker/Kind suite passed in GitHub CI: 104 of 104 E2E specs, including governance upgrades and observer recreation for Nibiru, CosmosHub and Osmosis. The check took 31m16s. Unit and integration checks also passed, with all 50 integration specs green.

2 - Deployment and release

Publish the reviewed operator as v2.2.1-nibiru.1 after checks pass. Mainnet adoption stays in NibiruChain/iac#2828 and requires installing these updated CRDs before configuring the field. The existing upstream chart can select the patched image once the Terraform module exposes imageTag.

This PR does not remove production overrides. Set the new patch to the same binary and verified active upgrade height, then clear group and individual legacy pins through a controlled IaC migration. Subsequent governance upgrades need no patch-setting cleanup. Removing an active patch deliberately returns the node to its recorded upgrade-period image.

An independent read-only review found no blocking issues. The exported functional patch applies cleanly to upstream v2.2.1, retaining its API and module path.

Compatibility remains the operator's responsibility; Cosmopilot does not establish that an arbitrary configured binary is safe for consensus.