feat: fail-fast preflight for schema upgrade path (multi-minor jumps)

[WentingWu666666]

Summary

Adds an operator-side fail-fast update-path preflight before running ALTER EXTENSION documentdb UPDATE, so a schema upgrade that PostgreSQL cannot resolve is detected up front instead of failing every reconcile.

Follow-up to #426 / part of #439 (the "skip more than one minor" / multi-version-chain gap).

Motivation

The documentdb extension ships minors frequently (roughly every couple of weeks), so users may bump more than one minor in a single change. ALTER EXTENSION ... UPDATE can chain intermediate documentdb--A--B.sql scripts, but only when the extension actually packages that continuous chain. When the chain is broken, ALTER EXTENSION UPDATE fails at execution time with a raw no update path error on every reconcile, with no actionable signal.

What this does

• Before the ALTER EXTENSION, query pg_extension_update_paths('documentdb') for a non-NULL path from the installed schema to the target (same version graph ALTER EXTENSION UPDATE walks internally).
• If a path exists → proceed as before.
• If not → skip the ALTER, leave schema/data untouched, and emit a SchemaUpgradePathMissing Warning event (mirroring the existing ExtensionRollback precedent).
• A no-op (source == target) short-circuits to "path exists" without querying.
• The preflight only runs in single-step modes (auto / explicit version); two-phase mode returns early before it, so those paths are unaffected.

Tests

• New unit test: no-path case skips ALTER, emits the Warning event, leaves the status schema version un-bumped.
• New extensionUpdatePathExists unit tests: source==target short-circuit, has-path, no-path, and SQL error propagation.
• Existing ALTER-path mocks converted from order-based to content-based branching to account for the extra preflight query.
• go test ./internal/controller/... green (163 specs).

Design note / open question

The status API has no Conditions field today, so this surfaces the failure via a Warning event only (consistent with ExtensionRollback). Adding a status condition would need a CRD/deepcopy regen — flagging as a possible follow-up. See the design comment on #439; pending maintainer sign-off on the fail-fast contract and webhook-vs-controller placement.

Follow-ups (not in this PR)

• e2e multi-minor jump test (success path + broken-chain), which needs 3+ versions / a crafted gap in CI.

Refs: #439

[documentdb-triage-tool]

🤖 Auto-triaged by documentdb-triage-tool.

Applied: go, test, enhancement
Project fields suggested: Component controllers · Priority P2 · Effort M · Status In Progress
Confidence: 0.85 (mixed)

Reasoning

component from path globs (controllers, test); effort from diff stats (245+17 LOC, 2 files); LLM: Adds a fail-fast preflight check in the reconcile loop to detect broken schema upgrade chains before executing ALTER EXTENSION, preventing repeated reconcile failures with no actionable signal — a meaningful functional improvement confined to the controller/extension upgrade logic.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.