Add diagnostics for cache-population race investigation

terraform-cache-brownfield started failing on config_scope/global mode
assertions after passing consistently through build #3. Static tracing
couldn't fully confirm whether the cause is an NSX search-index
consistency race or a runID mismatch across separate terraform apply
processes, so add targeted logging (no behavior change) to make the
next failure self-evident: log the resourceType/id/runID/currentTags
when a provider-managed tag gets re-patched, and log the populated
bucket size when a resourceID is still missing right after a bulk
search just populated that bucket.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ksamoray

nsxt/cache.go

@@ -502,6 +502,12 @@ func (c *typeScopedCache) readCache(resourceID string, resourceType string, d *s
 	if val != nil {
 		return val, nil
 	}
+	// Diagnostic only (no behavior change): a non-zero bucketSize here means the bulk
+	// search that just populated this bucket returned other objects of this type just fine,
+	// but not the one this read was for — evidence of an NSX search-index consistency lag
+	// (the object exists but wasn't indexed yet) rather than a cold/empty bucket.
+	bucketSize := len(tc.data[query])
+	populateEvents = append(populateEvents, cacheLogEvent{"DEBUG", fmt.Sprintf("Cache post-populate miss: resourceType=%s id=%s query=%q bucketSize=%d", resourceType, resourceID, query, bucketSize)})
 	return nil, errCacheUseBackendDirect
 }
 
@@ -870,7 +876,7 @@ func CacheAwareResourceRead[T any](d *schema.ResourceData, m interface{}, connec
 
 	// Only stamp provider-managed tags in config_scope mode.
 	if isConfigScopedCacheMode(m) {
-		_, patchErr := ensureProviderManagedTagsWithPatchFunc(obj, m, patchFunc)
+		_, patchErr := ensureProviderManagedTagsWithPatchFunc(obj, m, resourceType, resourceID, patchFunc)
 		if patchErr != nil {
 			log.Printf("[WARNING] Failed to patch provider-managed tags for %s %s: %v", resourceType, resourceID, patchErr) //nolint:gosec
 		}
@@ -1006,8 +1012,27 @@ func stripProviderManagedTagsFromAny(obj interface{}) {
 	tagsField.Set(reflect.ValueOf(userTags))
 }
 
+// formatModelTagsForLog renders tags as scope=tag pairs for diagnostic log lines.
+func formatModelTagsForLog(tags []model.Tag) string {
+	parts := make([]string, 0, len(tags))
+	for _, tag := range tags {
+		scope := ""
+		if tag.Scope != nil {
+			scope = *tag.Scope
+		}
+		val := ""
+		if tag.Tag != nil {
+			val = *tag.Tag
+		}
+		parts = append(parts, fmt.Sprintf("%s=%s", scope, val))
+	}
+	return "[" + strings.Join(parts, ", ") + "]"
+}
+
 // ensureProviderManagedTagsWithPatchFunc adds provider-managed tags to obj via patchFunc when missing.
-func ensureProviderManagedTagsWithPatchFunc[T any](obj T, m interface{}, patchFunc func(obj T) error) (interface{}, error) {
+// resourceType/resourceID are for diagnostic logging only (identifying which object this
+// decision was made for) and do not affect the decision itself.
+func ensureProviderManagedTagsWithPatchFunc[T any](obj T, m interface{}, resourceType string, resourceID string, patchFunc func(obj T) error) (interface{}, error) {
 	objValue := reflect.ValueOf(obj)
 	for objValue.IsValid() && objValue.Kind() == reflect.Pointer {
 		if objValue.IsNil() {
@@ -1056,7 +1081,8 @@ func ensureProviderManagedTagsWithPatchFunc[T any](obj T, m interface{}, patchFu
 	if !needsPatch {
 		return nil, nil
 	}
-	log.Printf("[DEBUG] Provider-managed tag missing; patching object to add scope=%s", managedDefaultTagScope) //nolint:gosec
+	log.Printf("[DEBUG] Provider-managed tag missing; patching object to add scope=%s resourceType=%s id=%s runID=%q expectedManagedTags=%s currentTags=%s", //nolint:gosec
+		managedDefaultTagScope, resourceType, resourceID, runID, formatModelTagsForLog(expectedManagedTags), formatModelTagsForLog(currentTags))
 
 	userTags := make([]model.Tag, 0)
 	for _, tag := range currentTags {

nsxt/cache_test.go

@@ -174,7 +174,7 @@ func TestUnitNsxt_ensureProviderManagedTagsWithPatchFunc(t *testing.T) {
 		}}
 		called := false
 
-		patched, err := ensureProviderManagedTagsWithPatchFunc(obj, m, func(o *testTagObj) error {
+		patched, err := ensureProviderManagedTagsWithPatchFunc(obj, m, "TestType", "test-id", func(o *testTagObj) error {
 			called = true
 			return nil
 		})
@@ -196,7 +196,7 @@ func TestUnitNsxt_ensureProviderManagedTagsWithPatchFunc(t *testing.T) {
 		}}
 		called := false
 
-		patched, err := ensureProviderManagedTagsWithPatchFunc(obj, m, func(o *testTagObj) error {
+		patched, err := ensureProviderManagedTagsWithPatchFunc(obj, m, "TestType", "test-id", func(o *testTagObj) error {
 			called = true
 			return nil
 		})

nsxt/cache_unit_test.go

@@ -7,7 +7,9 @@
 package nsxt
 
 import (
+	"bytes"
 	"errors"
+	"log"
 	"testing"
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -264,6 +266,40 @@ func TestUnitNsxt_readCacheMissingIDBypassesBackend(t *testing.T) {
 	assert.True(t, errors.Is(err, errCacheUseBackendDirect))
 }
 
+// TestUnitNsxt_readCachePostPopulateMissLogsBucketSize is a diagnostic-only regression
+// test (see brownfield_cache_test investigation): when the bulk search that just populated
+// a bucket returns other objects of the type but not the one this read was for, readCache
+// must log "Cache post-populate miss" with the actual (non-zero) bucket size, distinguishing
+// this from a cold/empty bucket — the signal used to tell an NSX search-index consistency
+// race apart from a genuinely absent object.
+func TestUnitNsxt_readCachePostPopulateMissLogsBucketSize(t *testing.T) {
+	sv := groupStructValue(t, "g1", "my-group", "/infra/domains/default/groups/g1")
+	stub := &seqQueryListClient{responses: []nsxModel.SearchResponse{
+		{Results: []*data.StructValue{sv}, ResultCount: i64(1)},
+	}}
+	defer setupCliQueryClientStub(t, stub)()
+
+	d := schema.TestResourceDataRaw(t, cacheTestSchema(), map[string]interface{}{})
+	m := nsxtClients{CommonConfig: commonProviderConfig{CacheMode: "config_scope"}}
+	c := &typeScopedCache{byTyp: make(map[string]*resourceTypeCache)}
+
+	var logBuf bytes.Buffer
+	origOutput := log.Writer()
+	log.SetOutput(&logBuf)
+	defer log.SetOutput(origOutput)
+
+	_, err := c.readCache("g2", resourceTypeGroup, d, m, nil)
+	assert.True(t, errors.Is(err, errCacheUseBackendDirect))
+
+	logged := logBuf.String()
+	assert.Contains(t, logged, "Cache post-populate miss: resourceType=Group id=g2")
+	// converListToMapByType indexes the populated object (g1) under multiple keys (id and
+	// display_name), so bucketSize is >1 here — the point is just that it's non-zero,
+	// proving the bucket really was populated with other objects rather than staying empty.
+	assert.NotContains(t, logged, "bucketSize=0", "bucket held the other populated object (g1), so size must not be reported as 0")
+	assert.Contains(t, logged, "bucketSize=2")
+}
+
 func TestUnitNsxt_getListOfPolicyResourcesCompositeMergesRules(t *testing.T) {
 	parentPath := "/infra/domains/default/security-policies/sp1"
 	converter := bindings.NewTypeConverter()