RFC: Decouple the VirtualMCPServer CRD schema from the vMCP config model

[ChrisJBurns]

Summary

Proposes decoupling the VirtualMCPServer CRD's spec.config from the internal
pkg/vmcp/config model. Today they are the same Go type, so controller-gen
walks the internal config tree into the public CRD — meaning any internal config
change leaks into the public API. This RFC introduces an operator-owned mirror
type plus a converter seam, delivered as an incremental, provably
non-breaking migration guarded by drift tests.

Why an RFC

The full change is large and hard to review as one diff. This RFC frames the
direction — and, importantly, the two-phase, one-subtree-per-PR migration
so reviewers can see that the implementation PR is just step 1a of a deliberate,
gated sequence, not a big bang.

Highlights

• Zero user-facing change for the mechanical decoupling (byte-identical CRD,
  enforced by a zero-diff gate on every PR).
• Drift is caught automatically — structural parity, round-trip transcode
  fuzz, and a categorical no-leak boundary test.
• Follows the established Kubernetes internal-vs-versioned types pattern; the
  telemetry path (spectoconfig) is the existing in-repo template.
• Phase 1 = mechanical decoupling (non-breaking, incremental). Phase 2 =
  the actual API evolution (Kubernetes-native refs, deprecating duplicate fields,
  v1beta2 if needed) — the only place real user-facing change happens.

Implementation

Phase 1a is implemented in toolhive#5238.

🤖 Generated with Claude Code

[ChrisJBurns]

Thanks for the thorough review — all six points addressed in 544f815.

• Move RFCs to correct folder #2 (HIGH, equivalence overstated): Softened. The tests are now scoped as catching structural (parity) and value-loss (round-trip) drift only; the Summary/Goals/Alternative 2/Testing Strategy now state plainly that marker/CEL/enum/default/doc-comment parity is not covered and is accepted residual risk, with the mirror's markers named as the single source of truth for CRD validation. Code-gen (Alternative 3) is promoted to recommended end-state as the only thing that closes this gap, cited explicitly from Alternative 2.
• Port THV-1497 #3 (superseding a Draft): Reworded throughout — it now "revisits the unified-types recommendation in THV-0023 (which remains in Draft) and the implementation that adopted it," and the metadata Supersedes: became Revisits:.
• Port THV-1566 #4 ("categorical" only at end-state): Goals now frame "categorically cannot reach the CRD" as an end-state property; added that the no-leak boundary widens one package per PR (after 1a it bars only pkg/vmcp/config; audit/ratelimit/telemetry/auth-types still get walked until mirrored).
• Port THV-1592 #5 (inapt k8s precedent): References now lead with the in-repo spectoconfig converter as the precise precedent; the k8s internal-vs-versioned analogy is demoted to "loosely analogous" (version-conversion via conversion-gen vs same-version cross-domain transcode; only the round-trip-fuzz methodology is borrowed).
• Port THV-1681 #6 (zero-diff gate insufficient): Added task operator-generate (deepcopy) to the gate; clarified it proves schema + generated-code stability but not converter behaviour (covered by round-trip fuzz + envtest/e2e), and noted marker-order sensitivity.
• Port THV-2063 #7 (cross-CRD RateLimitConfig divergence): Phase 1c is now an explicit single cross-CRD cutover (MCPServer + VirtualMCPServer in one PR), since mirroring vMCP alone would leave two sources generating the same schema — a transient divergence per-CRD drift tests can't catch; a cross-CRD parity test is named as the fallback if they must be split.