Introduce RuntimeConfig wrapper for vMCP ConfigMap surface

[ChrisJBurns]

Summary

VirtualMCPServerSpec.Config is typed as pkg/vmcp/config.Config in v1beta1, so controller-gen walks every field reachable from Config into the public CRD schema. That blocks adding operator-resolved sidecar fields (per-backend secret-identifier maps, resolved CA bundle paths, future BackendHeaderForward for MCPServerEntry references, etc.) without churning the CRD and triggering the v1beta1 stability gate.

This PR introduces pkg/vmcp/config.RuntimeConfig: a wrapper that embeds Config inline and is the designated home for operator-resolved fields. Today the wrapper adds nothing — marshalled YAML is byte-identical, parsed YAML is identical, and task operator-manifests produces zero CRD diff. Future PRs add sidecar fields onto RuntimeConfig without touching the public Config or v1beta1.

This is a foundational refactor for #4996 / #5013 (forward MCPServerEntry.headerForward to vMCP outbound requests). The current #5013 implementation adds 96 lines of CRD YAML and 86 lines of crd-api.md because HeaderForward was placed on StaticBackendConfig (a Config-reachable type). Once this PR lands, #5013 can be reworked to put the field on RuntimeConfig instead — net CRD diff drops to zero.

Wiring

• Loader: YAMLLoader.Load now returns *RuntimeConfig. Callers that only need user-facing Config fields read them through the embed (rc.Name, rc.Group, etc.); callers that consume sidecars read them off the wrapper directly. Strict KnownFields(true) validation is preserved.
• Operator write: cmd/thv-operator/controllers/virtualmcpserver_vmcpconfig.go wraps *Config in RuntimeConfig{} before YAML marshal. Single write path, single read path.
• CLI boundary: loadAndValidateConfig in pkg/vmcp/cli/serve.go and validate.go unwrap to *Config to keep the existing serve pipeline tight. A comment marks where to thread the wrapper through when a sidecar consumer arrives.

Tests pinning the seam

• pkg/vmcp/config/runtime_config_test.go:
  • TestRuntimeConfig_MarshalsIdenticallyToConfig — byte-identity vs Config today.
  • TestRuntimeConfig_Load_RoundTrip — Load through the operator's write shape.
  • TestRuntimeConfig_DisjointTopLevelTags — reflect-based check that catches a future field on RuntimeConfig sharing a JSON or YAML key with any Config field. encoding/json (anonymous-field promotion) and yaml.v3 (,inline) handle key collisions differently, so a collision would silently produce divergent serialization. This is forward-looking — today the wrapper has no extras and the test is trivially green.
• cmd/thv-operator/pkg/spectoconfig/runtime_config_drift_test.go:
  • Asserts RuntimeConfig is a strict superset of Config.
  • Any extras must appear in runtimeOnlyLeafJustifications with a written rationale (today empty).
  • Catches stale entries and contradicting classifications.
  • Lives operator-side because the drift harness in cmd/thv-operator/internal/testutil/ is operator-internal.

Acceptance gate

git diff main -- deploy/charts/operator-crds/ docs/operator/crd-api.md is empty after running both:

task operator-manifests
task operator-generate

The wrapper is invisible to controller-gen because RuntimeConfig is not field-referenced from any v1beta1 type. The doc on RuntimeConfig calls out the only way to break that invariant (retyping VirtualMCPServerSpec.Config from config.Config to config.RuntimeConfig — don't).

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change
• Refactoring
• Documentation
• Other

Test plan

• task build passes (verified via go build ./...)
• task test passes for all touched packages (pkg/vmcp/..., cmd/thv-operator/pkg/spectoconfig/...)
• New unit tests:
  • TestRuntimeConfig_MarshalsIdenticallyToConfig
  • TestRuntimeConfig_Load_RoundTrip
  • TestRuntimeConfig_DisjointTopLevelTags
  • TestRuntimeConfigSeam (operator-side drift test)
• task operator-manifests and task operator-generate produce zero diff under deploy/charts/operator-crds/ and docs/operator/crd-api.md

Special notes for reviewers

• Pure refactor, no behaviour change. The wrapper adds zero serialized keys today; YAML output and parse semantics are identical to Config directly. The point is to establish the seam now so the next operator-resolved field doesn't have to fight v1beta1 stability.
• Load() signature change. YAMLLoader.Load() now returns *RuntimeConfig instead of *Config. Most existing callers are field-access only (works transparently through embed). Two callers needed &cfg.Config for Validator.Validate(*Config). The CLI's loadAndValidateConfig unwraps to *Config at its return boundary to keep the serve pipeline tight; a comment documents the migration path when a sidecar consumer is added.
• Drift test placement. Test lives in cmd/thv-operator/pkg/spectoconfig/runtime_config_drift_test.go because the drift harness lives in cmd/thv-operator/internal/testutil/ and is operator-internal. The TYPES it tests live in pkg/vmcp/config/. This layering is acceptable; moving the harness up to a shared location is out of scope for this PR.

Implementation plan

Approved plan (AI-assisted)

Three agents reviewed the design before commit:

• toolhive-expert verified caller safety: 3 production + 8 test callers of Load() covered, single ConfigMap write path, no checksum fixtures pinned to current YAML.
• kubernetes-go-expert verified the four key claims (CRD invisibility, deepcopy-skip, ,inline semantics, strict-decode behaviour). One refinement landed in the type doc — the only way to leak RuntimeConfig fields into the CRD is retyping VirtualMCPServerSpec.Config, now explicitly called out.
• go-architect caught two real issues that were addressed before commit: (1) collapsed Load/LoadRuntime into one Load() returning *RuntimeConfig (interface pollution; lossy view would have become a latent bug); (2) added the disjoint-tag reflect test to catch the top forward-looking hazard.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.96%. Comparing base (9211a36) to head (471ae22).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5238      +/-   ##
==========================================
+ Coverage   67.91%   67.96%   +0.05%     
==========================================
  Files         610      612       +2     
  Lines       62522    62724     +202     
==========================================
+ Hits        42464    42633     +169     
- Misses      16879    16900      +21     
- Partials     3179     3191      +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.