feat: fail-fast preflight for extension update paths (+ e2e for >1-minor jumps and migration failure)

[WentingWu666666]

Context

Follow-up to #439, which tracked the schema-upgrade e2e gaps left open by #426.

#443 landed the test-only gaps that needed no operator change (schemaVersion: "auto", rollback within the safe window, multi-instance/HA rollout ordering, unpullable documentDBVersion). The remaining gaps from #439 were explicitly deferred because they all depend on one unmade decision: the operator has no update-path validation at all today. It runs a blanket ALTER EXTENSION documentdb UPDATE and relies entirely on PostgreSQL to resolve the path. Writing e2e tests for the failure modes first would just pin in whatever behavior falls out of that, so the contract needs to be ratified before the tests are meaningful.

This issue carries the design decision plus the work and tests that follow from it. Full write-up in this comment on #439.

Decision needed from maintainers

1. Confirm multi-minor jumps are a supported path, not rejected. The documentdb extension ships minors roughly monthly, at times bi-weekly. A user upgrading quarterly is already 3+ minors behind; twice-a-year is 6+. Adjacent-only (N → N+1) upgrades would mean 3–12 sequential rolling restarts to catch up, which in practice pushes users to never upgrade.
2. Confirm the fail-fast contract: block + surface a status condition when no update path exists, rather than firing ALTER EXTENSION and surfacing the raw PG error.
3. Confirm placement: controller only, or also a static check in the validating webhook. The path check needs DB connectivity, so the controller (which already holds a SQL executor and cluster handle) is the pragmatic home; only cheap static parts could move to the webhook.

The risk being managed

A jump only works if the extension ships a continuous chain of documentdb--A--B.sql update scripts. If any release omits its script, ALTER EXTENSION UPDATE fails at execution time with a raw PG error (extension has no update path from X to Y), re-fires every reconcile, and the user gets a cryptic failure with no actionable status.

Proposed implementation

PostgreSQL exposes the update-path graph read-only:

SELECT path FROM pg_extension_update_paths('documentdb')
WHERE source = '0.109-0' AND target = '0.113-0';

• Path resolvable → non-NULL arrow-joined sequence.
• No path → path IS NULL → fail-fast signal.

Hook this into documentdb_controller.go immediately before the SQLExecutor(... updateSQL) call. If no path exists: skip ALTER EXTENSION, emit a Warning event plus a SchemaUpgradeBlocked status condition (reason NoUpdatePath) naming the exact gap, and return cleanly without a crash-loop.

	Today	With preflight
When failure is learned	After firing ALTER EXTENSION	Before touching schema
Error quality	Raw PG error in logs	Actionable status condition + event
Visibility	Operator logs only	status.conditions on the CR
Loop behavior	Errors every reconcile	Clean stop

Scope

• Ratify the contract above with maintainers.
• Implement the pg_extension_update_paths preflight in documentdb_controller.go, with the SchemaUpgradeBlocked / NoUpdatePath condition and warning event.
• Unit coverage for the preflight (path present, path absent, same-version no-op).
• e2e: skipping more than one minor (jump > 1) — deferred from e2e: expand schema-upgrade coverage — gaps not covered by #426 #439. Assert a resolvable jump succeeds and data survives.
• e2e: multi-version chain — deferred from e2e: expand schema-upgrade coverage — gaps not covered by #426 #439. Chained upgrade across more than two versions (the test: add e2e schema-upgrade test for two-phase extension migration #426 spec covers only a single old→new hop).
• e2e: migration failure (ALTER EXTENSION UPDATE fails) — deferred from e2e: expand schema-upgrade coverage — gaps not covered by #426 #439. With the preflight in place this is reachable deterministically via a broken/absent update path; assert the operator surfaces the condition, does not corrupt data, and does not crash-loop.

Acceptance

The preflight is implemented and the three deferred e2e gaps from #439 are covered with appropriate labels/levels, or re-deferred with a documented rationale.

Follow-up to #439. Original coverage work in #426 and #443.

[WentingWu666666]

Implementation is up in #450.

What landed: a read-only pg_extension_update_paths preflight immediately before ALTER EXTENSION documentdb UPDATE. When the absence of an update path is positively proven, the operator skips the ALTER, emits a Warning event, and reports status.conditions[SchemaUpgradeBlocked]=True / NoUpdatePath with both versions and the remediation named. Anything inconclusive (SQL error, unparseable output, unexpected version format) fails open and behaves exactly as before.

Also closes the three e2e gaps deferred from #439. The migration-failure one no longer needs a doctored image: requesting a never-released patch version (e.g. 0.109.999 with 0.109.0 installed and a 0.110.0 binary) is admitted by the webhook, plans a migration, and has no update script — so it exercises the blocked path deterministically with stock images.

The three contract questions are still open — I proceeded because the preflight is strictly additive and doesn't foreclose any of the answers:

1. Multi-minor jumps supported? Treated as yes, matching current behavior. The preflight adds no restriction; it only surfaces what PostgreSQL would have done anyway. A "no" answer would be separate spec validation.
2. Webhook too, or controller only? Controller only, as this issue suggests as the pragmatic option — the webhook can't query a live database at admission time.
3. Recovery contract? Implemented as recoverable, not terminal: correcting spec.schemaVersion clears the condition and the migration proceeds. Pinned by an e2e spec.

@xgerman @alaye-ms — if any of those should land differently, happy to adjust in the PR; the implementation is deliberately compatible with all three outcomes.