Add capability-aware diagnostics with explicit older-cluster fallbacks #409

Problem

New diagnostics must not turn korvid into a latest-Kubernetes-only TUI. A server version does not establish that a feature is enabled, its controller or driver is installed, its metrics are exposed, or the current principal can read the evidence. Conversely, a failed or denied read must not be reported as an unsupported feature or a healthy empty result.

Goal and first-version scope

Provide a shared, bounded capability/evidence contract for the nine proposed diagnostic enhancements. Existing core-resource workflows remain usable when optional APIs or integrations are unavailable. No LLM is required.

For each diagnostic, report the selected API/version, available evidence, coverage, observation time, and a reasoned state: available, partially available, unsupported, access denied, unavailable/error, or not yet known. Report a disabled feature gate or missing installation only when evidence actually establishes that reason.

Compatibility and UI contract

• Reuse existing discovery, authorization checks, and bounded read paths, including resources served only through non-preferred API versions. Discovery-advertised verbs are not proof of user permission; permission checks are advisory and actual reads remain authoritative.
• Use explicitly supported API-version adapters. A newer server version alone must not enable an action, and an unfamiliar schema must not be silently interpreted as a known one.
• Detect capabilities at their real scope: API server, selected namespace/principal, node, driver, or metrics provider. A mixed cluster must not inherit one global yes/no result from a single node.
• Keep the basic diagnostic accessible; explain unavailable detail in the panel and keep keyboard help/Action Palette availability consistent. Do not silently replace native gang scheduling or native workload certificates with a different feature and claim equivalence.
• Scope cached observations to context/session identity, namespace and authorization state as appropriate. Refresh/invalidate on context or credential changes; discard late results from the old context. Bound retries and cache lifetime so failures are not permanent capability decisions.
• Show missing, stale, partial, and denied evidence explicitly. Do not infer feature enablement from an empty list or call missing metrics zero.
• Preserve independently optional observability/agent/MCP dependencies, current layer boundaries, constructor injection, masking, and existing approval/audit invariants. No extra privileges, hidden cluster-wide scans, or write probes.

Support policy

Choose and document the oldest supported Kubernetes version before claiming a tested version range. This issue does not invent a minimum version or promise support for every historical cluster. Distinguish verified integration-test coverage from fixture-only schema compatibility. Record field/API prerequisites rather than unverified release-stage claims.

Acceptance criteria

• Diagnostic code can consume capability facts without depending on Textual or duplicating version-string gates.
• API absent, served non-preferred version, unknown schema, denied discovery/read, transient transport failure, disabled feature when observable, and missing metrics produce distinct, useful outcomes.
• Older-cluster baseline views remain usable with all optional integrations absent.
• Partial listings, mixed-node support, stale observations, context changes, credential changes, and late worker results cannot produce a false complete/healthy result.
• The documented matrix covers the chosen oldest supported release, representative intermediate releases, and the newest qualified release, with optional features both present and absent.
• Tests enforce bounded/cancellable reads, no Secret payload reads, no mutation probes, and no optional-extra import regressions.

Planning

Scheduled for v0.7.0 as the shared diagnostic foundation. Preserve the already-selected v0.6.0 scope (#404, #405, #406, #408) and the v0.5.0 release contract (#387). The nine feature enhancements are separate work and are not required to close this foundation issue. No release date is committed.

Related: #49 (RBAC-limited operation), #345 (non-preferred API discovery), #389 (Pulse), #388 (Action Palette).

Upstream references

• Kubernetes API concepts
• Kubernetes authorization
• Kubernetes feature gates

Feature issue map

The following are separate deliverables assigned to planning milestones, not release-date guarantees. This shared foundation is scheduled for v0.7.0. Completing this foundation does not require completing its consumers; the feature issues depend on #409, not the reverse.

v0.7.0 — Baseline diagnostics

• Explain ConfigMap and Secret propagation by consumer and mount mode #410 — ConfigMap/Secret consumption and propagation explanation.
• Explain workload creation failures with ResourceQuota and LimitRange evidence #411 — ResourceQuota/LimitRange workload-creation constraints.

v0.8.0 — Operational explanations

• Explain field-level managers and reconciliation risks without inventing change history #412 — Field-level managers and reconciliation evidence.
• Explain standard NetworkPolicy decisions for an explicitly selected Pod pair #413 — Standard NetworkPolicy explanation for a selected Pod pair.
• Explain resource pressure with optional PSI evidence and older-cluster baselines #414 — Baseline resource diagnosis with optional PSI pressure evidence.
• Explain HPA decisions and zero-replica states using observed controller evidence #417 — HPA decision evidence and qualified zero-replica interpretation.

v0.9.0 — Environment-dependent integrations

• Explain accelerator allocation with device-plugin baselines and optional DRA evidence #415 — Legacy accelerator-resource baseline plus DRA allocation details.
• Explain workload-group scheduling with Job baselines and optional native PodGroup support #416 — Existing Job baseline plus native workload-group scheduling details.
• Explain workload identity and certificate status without reading credentials #418 — Identity-reference baseline plus native/cert-manager certificate status.