feat(cache-analytics): add FieldPath dimension for value-type traversal

Extends entity field-hash analytics to scalars reached from an entity
through pure value-type traversal (e.g. User.address.street where Address
has no @key). Hashes attribute to the nearest enclosing entity for cache
identity; the new FieldPath dimension disambiguates leaves at arbitrary
nesting depth (User.address.street vs User.profile.location.street).

- EntityFieldHash gains FieldPath []string (schema names, no array indices)
- HashFieldValue takes a fieldPath param and defensively copies the slice
  so callers can reuse a scratch buffer
- plan/visitor.go marks scalars under value-type ancestors via a new
  hasEntityAncestor() walk over Walker.TypeDefinitions
- resolvable.go tracks currentEntityFieldPath as a push/pop stack across
  walkObject; reset to nil at every entity boundary, restored on exit
- renderFieldValue eligibility check trusts the plan-time CacheAnalyticsHash
  flag and falls back to a polymorphic interface-on-entity match

Author: SkArchon

v2/pkg/engine/datasource/graphql_datasource/graphql_datasource_federation_test.go

@@ -2061,6 +2061,7 @@ func TestGraphQLDataSourceFederation(t *testing.T) {
 																				Names: []string{"account.service"},
 																			},
 																			ExactParentTypeName: "ShippingInfo",
+																			CacheAnalyticsHash:  true,
 																		},
 																		Value: &resolve.String{
 																			Path: []string{"z"},

v2/pkg/engine/plan/visitor.go

@@ -550,10 +550,20 @@ func (v *Visitor) resolveFieldInfo(ref, typeRef int, onTypeNames [][]byte) *reso
 	}
 
 	// Mark non-key fields on concrete entity types for cache analytics hashing;
-	// polymorphic parents fall through to the runtime fallback.
+	// polymorphic parents fall through to the runtime fallback. Also mark scalar
+	// fields on value types reachable from an entity through pure value-type
+	// traversal (e.g. User.address.street where Address has no @key) — these
+	// are attributed to the nearest enclosing entity for cache identity.
 	if v.Walker.EnclosingTypeDefinition.Kind == ast.NodeKindObjectTypeDefinition {
 		if analytics := v.entityCacheAnalytics(enclosingTypeName); analytics != nil {
 			fieldInfo.CacheAnalyticsHash = !analytics.IsKeyField(fieldName)
+		} else if v.hasEntityAncestor() {
+			// Value-type scalar nested under an entity scope. Plan-time
+			// CacheAnalyticsHash gates the runtime emission; the resolvable
+			// will attribute the hash to currentEntityTypeName (the nearest
+			// enclosing entity preserved by walkObject's save/restore) with
+			// ExactParentTypeName recorded separately for disambiguation.
+			fieldInfo.CacheAnalyticsHash = true
 		}
 	}
 
@@ -2614,6 +2624,33 @@ func (v *Visitor) entityCacheAnalytics(typeName string) *resolve.ObjectCacheAnal
 	return nil
 }
 
+// hasEntityAncestor reports whether the current field's enclosing scope sits
+// inside an entity reached via pure value-type traversal (no nested entity
+// boundary above it). The immediate enclosing type is assumed already checked
+// by the caller and not to be an entity. We walk the type-definition chain
+// backwards and return true at the first entity found; an interface ancestor
+// is conservatively treated as a non-entity stop (the runtime polymorphic
+// fallback handles those).
+func (v *Visitor) hasEntityAncestor() bool {
+	td := v.Walker.TypeDefinitions
+	// The last entry is the current EnclosingTypeDefinition (the immediate
+	// parent of the field). Walk strictly above it.
+	for i := len(td) - 2; i >= 0; i-- {
+		node := td[i]
+		if node.Kind != ast.NodeKindObjectTypeDefinition {
+			continue
+		}
+		typeName := node.NameString(v.Definition)
+		if typeName == "" {
+			continue
+		}
+		if analytics := v.entityCacheAnalytics(typeName); analytics != nil {
+			return true
+		}
+	}
+	return false
+}
+
 // polymorphicEntityCacheAnalytics returns per-concrete-type cache analytics for an
 // interface/union object. Returns nil when none of the possible types is an entity
 // (so the caller can assign unconditionally).

v2/pkg/engine/resolve/cache_analytics.go

@@ -97,16 +97,21 @@ type SubgraphErrorEvent struct {
 	Code       string    // error code from errors[0].extensions.code (empty if not present)
 }
 
-// EntityFieldHash stores an xxhash of a scalar field value on an entity type,
-// along with the entity's key data and the source of the data.
+// EntityFieldHash stores an xxhash of a scalar field value reached from inside
+// an entity scope. KeyRaw/KeyHash always refer to the enclosing entity's @key,
+// even when the field lives on a nested value type. FieldPath is the schema-name
+// chain from the entity down to (but not including) the leaf — nil for direct
+// entity scalars, e.g. User.address.street → []string{"address"}. Array indexes
+// are omitted; nested entities reset the path.
 type EntityFieldHash struct {
 	Timestamp  time.Time // when the hash was computed; stamped by HashFieldValue if zero
-	EntityType string
+	EntityType string    // enclosing entity type name (cache identity)
+	FieldPath  []string  // schema-name field path from the enclosing entity to the parent (nil for direct entity scalars)
 	FieldName  string
 	FieldHash  uint64      // xxhash of the non-key field value
 	KeyRaw     string      // raw key JSON e.g. {"id":"1234"} (when HashKeys=false)
 	KeyHash    uint64      // xxhash of key JSON (when HashKeys=true)
-	Source     FieldSource // where the entity data came from (L1/L2/Subgraph)
+	Source     FieldSource // category: where the entity data came from (L1/L2/Subgraph/ShadowCached)
 	DataSource string      // subgraph name that owns this entity (empty if not resolvable)
 }
 
@@ -314,16 +319,28 @@ func (c *CacheAnalyticsCollector) RecordWrite(event CacheWriteEvent) {
 }
 
 // HashFieldValue computes an xxhash of the given field value bytes and records it
-// as an EntityFieldHash with entity key and source information. dataSource is
-// the subgraph name that owns the entity (may be empty if not resolvable).
-func (c *CacheAnalyticsCollector) HashFieldValue(entityType, fieldName string, valueBytes []byte, keyRaw string, keyHash uint64, source FieldSource, dataSource string) {
+// as an EntityFieldHash with entity key and source information.
+//
+// entityType is the enclosing entity type name (cache identity). fieldPath is
+// the chain of schema field names from the enclosing entity down to (but not
+// including) the hashed leaf — empty for direct entity scalars. The slice is
+// copied so callers may reuse their scratch buffer. dataSource is the
+// subgraph name that owns the entity (may be empty if not resolvable).
+func (c *CacheAnalyticsCollector) HashFieldValue(entityType, fieldName string, fieldPath []string, valueBytes []byte, keyRaw string, keyHash uint64, source FieldSource, dataSource string) {
 	c.xxh.Reset()
 	_, _ = c.xxh.Write(valueBytes)
 	hash := c.xxh.Sum64()
 
+	var pathCopy []string
+	if len(fieldPath) > 0 {
+		pathCopy = make([]string, len(fieldPath))
+		copy(pathCopy, fieldPath)
+	}
+
 	c.fieldHashes = append(c.fieldHashes, EntityFieldHash{
 		Timestamp:  time.Now(),
 		EntityType: entityType,
+		FieldPath:  pathCopy,
 		FieldName:  fieldName,
 		FieldHash:  hash,
 		KeyRaw:     keyRaw,

v2/pkg/engine/resolve/cache_analytics_test.go

@@ -136,8 +136,8 @@ func TestCacheAnalyticsCollector_FieldHashing(t *testing.T) {
 	t.Run("same input produces same hash", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
 
 		snap := c.Snapshot()
 		assert.Equal(t, 2, len(snap.FieldHashes))
@@ -151,8 +151,8 @@ func TestCacheAnalyticsCollector_FieldHashing(t *testing.T) {
 	t.Run("different input produces different hash", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
-		c.HashFieldValue("User", "name", []byte(`"Bob"`), `{"id":"2"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Bob"`), `{"id":"2"}`, 0, FieldSourceSubgraph, "")
 
 		snap := c.Snapshot()
 		assert.Equal(t, 2, len(snap.FieldHashes))
@@ -162,7 +162,7 @@ func TestCacheAnalyticsCollector_FieldHashing(t *testing.T) {
 	t.Run("hashed keys mode", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), "", 12345, FieldSourceL1, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), "", 12345, FieldSourceL1, "")
 
 		snap := c.Snapshot()
 		assert.Equal(t, 1, len(snap.FieldHashes))
@@ -174,9 +174,9 @@ func TestCacheAnalyticsCollector_FieldHashing(t *testing.T) {
 	t.Run("field source tracking", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceL1, "")
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceL2, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceL1, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceL2, "")
 
 		snap := c.Snapshot()
 		assert.Equal(t, 3, len(snap.FieldHashes))
@@ -1564,7 +1564,7 @@ func TestFieldSourceShadowCached(t *testing.T) {
 	t.Run("HashFieldValue with FieldSourceShadowCached", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "username", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceShadowCached, "")
+		c.HashFieldValue("User", "username", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceShadowCached, "")
 
 		snap := c.Snapshot()
 		require.Equal(t, 1, len(snap.FieldHashes))
@@ -1577,8 +1577,8 @@ func TestFieldSourceShadowCached(t *testing.T) {
 	t.Run("can distinguish from other sources", func(t *testing.T) {
 		c := NewCacheAnalyticsCollector()
 
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
-		c.HashFieldValue("User", "name", []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceShadowCached, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", nil, []byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceShadowCached, "")
 
 		snap := c.Snapshot()
 		require.Equal(t, 2, len(snap.FieldHashes))
@@ -1589,6 +1589,99 @@ func TestFieldSourceShadowCached(t *testing.T) {
 	})
 }
 
+// TestCacheAnalyticsCollector_FieldPath verifies the FieldPath dimension on
+// EntityFieldHash, which disambiguates value-type scalars nested at arbitrary
+// depth under an entity (e.g. User.address.street vs User.profile.name).
+// EntityType remains the cache identity in all cases; schema-aware consumers
+// resolve the parent type by walking FieldPath against the schema.
+func TestCacheAnalyticsCollector_FieldPath(t *testing.T) {
+	t.Run("direct entity scalar has nil field path", func(t *testing.T) {
+		c := NewCacheAnalyticsCollector()
+
+		// User.email — direct scalar on the entity, no value-type traversal.
+		c.HashFieldValue("User", "email", nil, []byte(`"a@b.com"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+
+		snap := c.Snapshot()
+		require.Equal(t, 1, len(snap.FieldHashes))
+		assert.Equal(t, "User", snap.FieldHashes[0].EntityType)
+		assert.Equal(t, "email", snap.FieldHashes[0].FieldName)
+		assert.Nil(t, snap.FieldHashes[0].FieldPath)
+	})
+
+	t.Run("value-type scalars under same entity attribute to that entity", func(t *testing.T) {
+		c := NewCacheAnalyticsCollector()
+
+		// User.address.street and .city — Address is a value type under User.
+		// Both attribute to User for cache identity (same KeyRaw).
+		c.HashFieldValue("User", "street", []string{"address"}, []byte(`"1 Main"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "city", []string{"address"}, []byte(`"NYC"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+
+		snap := c.Snapshot()
+		require.Equal(t, 2, len(snap.FieldHashes))
+		for i, want := range []string{"street", "city"} {
+			assert.Equal(t, "User", snap.FieldHashes[i].EntityType)
+			assert.Equal(t, want, snap.FieldHashes[i].FieldName)
+			assert.Equal(t, []string{"address"}, snap.FieldHashes[i].FieldPath)
+			assert.Equal(t, `{"id":"1"}`, snap.FieldHashes[i].KeyRaw)
+		}
+	})
+
+	t.Run("siblings on different value-type parents do not collapse", func(t *testing.T) {
+		// Same FieldName "name" reached via different value-type paths
+		// (User.profile.name vs User.address.name) — recorded as two distinct
+		// events because their FieldPath differs.
+		c := NewCacheAnalyticsCollector()
+		c.HashFieldValue("User", "name", []string{"profile"}, []byte(`"Profile-Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "name", []string{"address"}, []byte(`"Home"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+
+		snap := c.Snapshot()
+		require.Equal(t, 2, len(snap.FieldHashes))
+		assert.Equal(t, []string{"profile"}, snap.FieldHashes[0].FieldPath)
+		assert.Equal(t, []string{"address"}, snap.FieldHashes[1].FieldPath)
+		assert.NotEqual(t, snap.FieldHashes[0].FieldHash, snap.FieldHashes[1].FieldHash)
+	})
+
+	t.Run("field path captures arbitrary nesting depth", func(t *testing.T) {
+		// User.profile.location.street is two value-type hops deep.
+		c := NewCacheAnalyticsCollector()
+		c.HashFieldValue("User", "street",
+			[]string{"profile", "location"},
+			[]byte(`"1 Main"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+
+		snap := c.Snapshot()
+		require.Equal(t, 1, len(snap.FieldHashes))
+		assert.Equal(t, "User", snap.FieldHashes[0].EntityType)
+		assert.Equal(t, []string{"profile", "location"}, snap.FieldHashes[0].FieldPath)
+		assert.Equal(t, "street", snap.FieldHashes[0].FieldName)
+	})
+
+	t.Run("field path is copied so caller scratch buffers can be reused", func(t *testing.T) {
+		// Many call sites will pass a reusable scratch slice. The collector
+		// must defensively copy so a subsequent push by the caller does not
+		// mutate already-recorded events.
+		c := NewCacheAnalyticsCollector()
+		scratch := []string{"profile"}
+		c.HashFieldValue("User", "name", scratch,
+			[]byte(`"Alice"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		// Caller mutates the scratch slice after the call.
+		scratch[0] = "MUTATED"
+		scratch = append(scratch, "more")
+
+		snap := c.Snapshot()
+		require.Equal(t, 1, len(snap.FieldHashes))
+		assert.Equal(t, []string{"profile"}, snap.FieldHashes[0].FieldPath, "stored path must be unaffected by caller mutation")
+	})
+
+	t.Run("empty field path is stored as nil for direct entity scalars", func(t *testing.T) {
+		c := NewCacheAnalyticsCollector()
+		c.HashFieldValue("User", "email", nil,
+			[]byte(`"a@b"`), `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		snap := c.Snapshot()
+		require.Equal(t, 1, len(snap.FieldHashes))
+		assert.Nil(t, snap.FieldHashes[0].FieldPath, "direct entity scalars should record nil FieldPath")
+	})
+}
+
 // TestShadowComparisonEvent_Recording verifies that shadow comparison events
 // capture all fields (hash, size, age, TTL) needed to detect staleness.
 func TestShadowComparisonEvent_Recording(t *testing.T) {
@@ -1755,7 +1848,7 @@ func BenchmarkFieldHashing(b *testing.B) {
 
 	b.ResetTimer()
 	for b.Loop() {
-		c.HashFieldValue("User", "id", value, `{"id":"1"}`, 0, FieldSourceSubgraph, "")
+		c.HashFieldValue("User", "id", nil, value, `{"id":"1"}`, 0, FieldSourceSubgraph, "")
 	}
 }
 
@@ -2056,7 +2149,7 @@ func TestSnapshotSlicesAreIndependent(t *testing.T) {
 	c.RecordError(SubgraphErrorEvent{DataSource: "ds-orig"})
 	c.RecordMutationEvent(MutationEvent{EntityType: "User-orig"})
 	c.RecordCacheOperationError(CacheOperationError{DataSource: "ds-orig"})
-	c.HashFieldValue("User-orig", "name", []byte(`"a"`), "k-orig", 1, FieldSourceL1, "")
+	c.HashFieldValue("User-orig", "name", nil, []byte(`"a"`), "k-orig", 1, FieldSourceL1, "")
 
 	snap := c.Snapshot()
 
@@ -2078,7 +2171,7 @@ func TestSnapshotSlicesAreIndependent(t *testing.T) {
 		c.RecordError(SubgraphErrorEvent{DataSource: "ds-new"})
 		c.RecordMutationEvent(MutationEvent{EntityType: "User-new"})
 		c.RecordCacheOperationError(CacheOperationError{DataSource: "ds-new"})
-		c.HashFieldValue("User-new", "name", []byte(`"z"`), "k-new", 2, FieldSourceL2, "")
+		c.HashFieldValue("User-new", "name", nil, []byte(`"z"`), "k-new", 2, FieldSourceL2, "")
 	}
 
 	// Full-slice assertions — snapshot must still show the original events.

v2/pkg/engine/resolve/loader_cache.go

@@ -2502,7 +2502,7 @@ func (l *Loader) compareShadowValues(res *result, info *FetchInfo) {
 				if fieldVal != nil {
 					fieldBytes := fieldVal.MarshalTo(nil)
 					l.ctx.cacheAnalytics.HashFieldValue(
-						entityType, fieldName, fieldBytes,
+						entityType, fieldName, nil, fieldBytes,
 						keyRaw, 0, FieldSourceShadowCached, dataSource,
 					)
 				}