feat(cache-analytics): add ForceHashAnalyticsKeys planner override

Adds a Configuration.ForceHashAnalyticsKeys planner flag. When set, the
plan visitor ORs it onto the per-entity HashAnalyticsKeys setting so a
true value can never be downgraded by per-entity SDL config.

Use case: router operators need a guarantee that no raw entity key ever
leaves the engine via analytics (PII / GDPR), regardless of what each
subgraph SDL declares.

Author: SkArchon

v2/pkg/engine/plan/caching_planner_state.go

@@ -880,11 +880,18 @@ func (s *cachingPlannerState) entityCacheAnalytics(typeName string) *resolve.Obj
 		// Extract full key structure from @key SelectionSets
 		keys := fedConfig.Keys.FilterByTypeAndResolvability(typeName, true)
 		keyFields := extractKeyFields(keys, typeName)
-		// Get hash mode from entity cache config (default false)
+		// Get hash mode from entity cache config (default false), then OR
+		// with the planner's global ForceHashAnalyticsKeys flag. The global
+		// flag exists so router operators can guarantee that no raw entity
+		// key ever leaves the engine via analytics, regardless of what each
+		// subgraph SDL declares.
 		var hashKeys bool
 		if cacheConfig := fedConfig.EntityCacheConfig(typeName); cacheConfig != nil {
 			hashKeys = cacheConfig.HashAnalyticsKeys
 		}
+		if s.visitor.Config.ForceHashAnalyticsKeys {
+			hashKeys = true
+		}
 		result := &resolve.ObjectCacheAnalytics{
 			KeyFields: keyFields,
 			HashKeys:  hashKeys,

v2/pkg/engine/plan/configuration.go

@@ -50,6 +50,15 @@ type Configuration struct {
 	// DisableEntityCaching disables planning of L2 entity caching metadata and mutation-impact logic.
 	// L1 cache templates are still generated regardless of this setting.
 	DisableEntityCaching bool
+
+	// ForceHashAnalyticsKeys, when true, forces every entity's plan-time
+	// HashKeys flag to true regardless of the per-entity HashAnalyticsKeys
+	// setting in the federation config. The plan visitor ORs this with the
+	// per-entity setting; a true value here cannot be downgraded by the
+	// per-entity flag. Use this when the analytics export pipeline must
+	// avoid emitting raw entity keys (e.g., to satisfy PII / GDPR boundaries).
+	// Default: false (per-entity setting controls hashing).
+	ForceHashAnalyticsKeys bool
 	// DisableFetchProvidesData disables planning of meta information about which fields are provided by a fetch
 	DisableFetchProvidesData bool
 

v2/pkg/engine/plan/visitor_cache_analytics_test.go

@@ -0,0 +1,75 @@
+package plan
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestVisitor_ForceHashAnalyticsKeys verifies that Configuration.ForceHashAnalyticsKeys
+// ORs onto the per-entity HashAnalyticsKeys setting and cannot be downgraded by the
+// per-entity flag. This is the core invariant the global override exists to provide:
+// router operators need to guarantee no raw entity key leaves the engine via analytics
+// (PII / GDPR), regardless of what each subgraph SDL declares.
+func TestVisitor_ForceHashAnalyticsKeys(t *testing.T) {
+	cases := []struct {
+		name          string
+		perEntityHash bool
+		forceHash     bool
+		wantHashKeys  bool
+	}{
+		{"both off — raw keys", false, false, false},
+		{"per-entity on, force off — per-entity wins (true)", true, false, true},
+		{"per-entity off, force on — force overrides", false, true, true},
+		{"both on — true", true, true, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			metadata := &DataSourceMetadata{
+				FederationMetaData: FederationMetaData{
+					Keys: FederationFieldConfigurations{
+						{TypeName: "User", SelectionSet: "id"},
+					},
+					EntityCaching: EntityCacheConfigurations{
+						{
+							TypeName:          "User",
+							CacheName:         "default",
+							HashAnalyticsKeys: tc.perEntityHash,
+						},
+					},
+				},
+			}
+			ds, err := NewDataSourceConfiguration[any]("ds-1", nil, metadata, nil)
+			require.NoError(t, err)
+
+			v := &Visitor{
+				Config: Configuration{
+					DataSources:            []DataSource{ds},
+					ForceHashAnalyticsKeys: tc.forceHash,
+				},
+			}
+			caching := newCachingPlannerState(v)
+
+			analytics := caching.entityCacheAnalytics("User")
+			require.NotNil(t, analytics, "User is an entity, analytics must be non-nil")
+			assert.Equal(t, tc.wantHashKeys, analytics.HashKeys,
+				"HashKeys = perEntity(%v) || force(%v)", tc.perEntityHash, tc.forceHash)
+		})
+	}
+
+	t.Run("non-entity returns nil regardless of force flag", func(t *testing.T) {
+		// ForceHashAnalyticsKeys must not cause non-entities to spuriously
+		// report as entities — it only ORs the HashKeys field on entities
+		// that already exist in the federation config.
+		v := &Visitor{
+			Config: Configuration{
+				DataSources:            nil,
+				ForceHashAnalyticsKeys: true,
+			},
+		}
+		caching := newCachingPlannerState(v)
+		assert.Nil(t, caching.entityCacheAnalytics("NotAnEntity"))
+	})
+}