docs: clarify exported public-API contract for cosmo-only symbols

ysmolski flagged three exported symbols as suspicious because their
only callers in this repository are tests. The author's intent was
to expose them for external consumers (wundergraph/cosmo router).

Add minimal godoc comments to make the contract explicit:

- MergeRepresentationVariableNodes also has one in-repo production
  caller (visitor.go:1812), confirming public-API status.
- RecordL2KeyEvent and RecordFetchTiming have zero in-repo production
  callers; doc notes they are kept exported for cosmo and should be
  internalized in the next breaking window if cosmo stops using them.

No signature changes, no internalization.

Addresses ysmolski review on PR #1259 (representation_variable.go:21,
cache_analytics.go:278).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jensneuse

v2/pkg/engine/plan/representation_variable.go

@@ -63,6 +63,8 @@ func BuildRepresentationVariableNode(definition *ast.Document, cfg FederationFie
 }
 
 // MergeRepresentationVariableNodes merges multiple representation variable objects into one.
+// It is part of the public planner API consumed by external integrations
+// such as wundergraph/cosmo; breaking changes require coordinated downstream updates.
 func MergeRepresentationVariableNodes(objects []*resolve.Object) *resolve.Object {
 	fieldCount := 0
 	for _, object := range objects {

v2/pkg/engine/resolve/cache_analytics.go

@@ -274,6 +274,8 @@ func (c *CacheAnalyticsCollector) RecordL1KeyEvent(kind CacheKeyEventKind, entit
 }
 
 // RecordL2KeyEvent records an L2 cache key lookup event. Main thread only.
+// It is exported for external consumers such as cosmo router; this repository
+// has no production caller. If cosmo no longer uses it, internalize it in the next breaking window.
 // Use MergeL2Events to merge events collected on per-result slices from goroutines.
 func (c *CacheAnalyticsCollector) RecordL2KeyEvent(kind CacheKeyEventKind, entityType, cacheKey, dataSource string, byteSize int) {
 	c.l2KeyEvents = append(c.l2KeyEvents, CacheKeyEvent{
@@ -352,6 +354,8 @@ func (c *CacheAnalyticsCollector) MergeEntitySources(sources []entitySourceRecor
 }
 
 // RecordFetchTiming records a fetch timing event. Main thread only.
+// It is exported for external consumers such as cosmo router; this repository
+// has no production caller. If cosmo no longer uses it, internalize it in the next breaking window.
 func (c *CacheAnalyticsCollector) RecordFetchTiming(event FetchTimingEvent) {
 	c.fetchTimings = append(c.fetchTimings, event)
 }