direct: document the top-level-field constraint of CompactState's shallow copy

The shallow copy keeps the caller's value (reused for the deploy API call)
untouched only for top-level scalar hashed fields; a nested field would need
a deep copy. Note the constraint so it isn't silently broken later.

Co-authored-by: Isaac

Author: shreyas-goenka

bundle/direct/dresources/state_compaction.go

@@ -56,7 +56,10 @@ func CompactState(cfg *ResourceLifecycleConfig, state any) (any, error) {
 		return state, nil
 	}
 
-	// Shallow copy so the caller's value (reused for the deploy) is untouched.
+	// Shallow copy so the caller's value (reused for the deploy) is untouched. This is
+	// safe only because every hashed_in_state field is a top-level scalar (e.g.
+	// serialized_dashboard): SetByString overwrites it on the copy directly. A field
+	// reached through a shared pointer/slice/map would need a deep copy here.
 	out := reflect.New(rv.Type().Elem())
 	out.Elem().Set(rv.Elem())
 	compacted := out.Interface()