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 -> #889 -> #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 (2d1b31dfa3e996f5ba7a9bfcd0a3a259775f2923...5822b7e4d75a7ea39e51e12f3fe07f204483f2fb, exact PR three-dot diff)
• Model: gpt-5.6-sol

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

---

Review Summary

Overall Risk: NONE

Findings

No findings.

Notes

The authoritative diff is documentation-only. The qualification procedure remains fail-closed: every gate must pass before release promotion. No runtime, protobuf, database, pool configuration, or credential-handling code changed.

---

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