Define adjacent-release HA update qualification

[ankitgoswami]

Reviewable diff: +222/-0 across 2 files (excludes generated, test, and story files).

Summary

Defines the evidence required to support an adjacent-version HA application update from stable N to prerelease N+1. The same target tag and assets become stable only after migration compatibility, passive-first update, mixed-version forced takeover, bounded completion and timeout recovery, bidirectional failover, command recovery, infrastructure preservation, deployment-swap, forward-activation, updater interruption, and reboot gates pass on both amd64 and arm64.

Stack: #887 -> #888 -> #890 -> #891 -> #892. This documentation-only diff is relative to completion PR #891.

How it works

Operators publish the final N+1 tag and assets at the fixed official origin as a GitHub prerelease. HA does not offer UI-triggered updates, so qualification configures the root-owned updater environment to authorize only that exact target and then uses the explicit local operator command. The authorization is restored after every clean reinstall, verified before each update attempt, and removed after the run. The report requires clean-install qualification for the exact source and target artifacts and verifies that the target's reviewed qualification file and manifest metadata name the exact source. It first runs compatibility tests, then loads a sanitized production-scale N dataset into the HA cluster so the real passive updater runs migrations under sustained traffic. Gap-free active-health and VIP ownership recording starts before the passive update. Authenticated reads and uniquely identified commands continue through passive-first update and completion, with bounded success gaps; every background command must reach SUCCESS, except the deliberately interrupted PROCESSING rows. The live handoff carries one N PROCESSING row and PENDING successor into N+1, proving the interrupted row fails without replay and the successor dispatches. A separate exact-artifact run pauses after the old application stops, makes the updated peer unavailable, proves the updater enters its takeover wait, and requires automatic N recovery within 60 seconds. Rename-window and self-update faults require direct process and filesystem evidence before injection rather than inferring the window from an ambiguous durable marker. A client loaded from N must still work against the N+1 VIP. Another clean N baseline forces the updated N+1 passive to take over before completion, then updates the old N host through the ordinary passive command. Public and database-backed probes measure normal interruption below 15 seconds; container identity, PostgreSQL start times, updater checks, and one-at-a-time reboots finish the evidence. Forward-activation interruption must resume target startup and migrations; self-update interruption passes only when the updater converges to the same version as the retained application deployment. Only after every gate passes does a final drift guard re-resolve both commits, re-download the complete source and target asset sets, compare their recorded digests, and promote the unchanged prerelease to stable.

flowchart LR
  A["Verify N and N+1 artifacts"] --> P["Update passive"]
  P --> M["Exercise mixed versions"]
  M --> X["Force mixed-version takeover"]
  X --> C["Complete active within 15s"]
  C --> F["Fail over both directions"]
  F --> R["Reboot and verify"]
  R --> V{"Every gate passes?"}

Loading

Areas of the code involved

Area / package / file	What changed	Why it matters for review
deployment-files/ha/UPDATE_QUALIFICATION.md	Adds the adjacent-release procedure and result table	Check every support claim has direct, executable evidence
deployment-files/ha/README.md	Links the report	Check operator discoverability

Key technical decisions & trade-offs

• Only consecutive released artifacts are qualified; skipped versions remain unsupported.
• Qualification authorizes one exact GitHub prerelease through the local root-owned updater environment, then promotes the unchanged tag and assets only after every gate passes.
• The runbook reuses the baseline external recorder and the root-only qualification barriers from Complete HA updates through bounded failover #891; it adds no deployment controller or remote diagnostics.
• Interrupted PROCESSING work must fail without replay; its existing PENDING successor continues.
• The availability target is a bounded interruption below 15 seconds, not zero downtime.

Testing & validation

• The static HA profile check and diff check pass.
• Migration review, hardware recovery, timing, updater, and reboot evidence are pending; therefore this PR remains draft.

[github-actions]

🔐 Codex Security Review

Note: This is an automated security-focused code review generated by Codex.
It should be used as a supplementary check alongside human review.
False positives are possible - use your judgment.

Scope summary

• Reviewed pull request diff only (4a7d8814172ad3dbdd3ded9b88303f182a5a919d...86da4fd2fae3286dcca2bd8af1bb26b25bbb203a, exact PR three-dot diff)
• Model: gpt-5.6-sol

💡 Click "edited" above to see previous reviews for this PR.

---

Review Summary

Overall Risk: HIGH

Findings

[HIGH] Qualification depends on a missing baseline procedure

• Category: Reliability
• Location: deployment-files/ha/UPDATE_QUALIFICATION.md:55
• Description: The new procedure delegates mandatory baseline reports, recorder setup, gap rejection, and uncertainty-inclusive timing rules to QUALIFICATION.md, but that file does not exist in the reviewed commit.
• Impact: The release gate is not reproducible. Qualification is either blocked or performed with ad hoc evidence that may miss split-brain intervals and unsafe HA update behavior before promotion.
• Recommendation: Add the referenced version-controlled procedure in this PR or link to the correct existing document. It should define executable recorder/probe steps, timing rules, and required evidence; validate the link in CI.

Notes

The reviewed diff changes HA update documentation only; it does not modify runtime code, credentials, pool configuration, or generated protocol code.

---

_{Generated by Codex Security Review |
Triggered by: @ankitgoswami |
Review workflow run}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 86da4fd2fa

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Add or correct the baseline qualification link

This procedure depends on [QUALIFICATION.md](QUALIFICATION.md) for both the required baseline report and the recorder/gap rules, but that file is not present under deployment-files/ha or elsewhere in the repo (I searched for QUALIFICATION.md and the referenced recorder text). As written, operators cannot follow or audit the new HA update qualification because a required prerequisite procedure resolves to a missing document; either add the baseline qualification doc in this commit or point these references at the actual source of those rules.

Useful? React with 👍 / 👎.