mmaprototype: add overview comment to a few new test cases

Author: tbg

pkg/kv/kvserver/allocator/mmaprototype/testdata/cluster_state/rebalance_replica

@@ -1,3 +1,22 @@
+# Tests rebalancing a replica from a local store to a remote store (stores on
+# different nodes).
+#
+# Scenario: Store s1 on node 1 initially holds the replica and lease for range 1.
+# The test rebalances the replica (and lease) from s1 to s2 on node 2.
+#
+# Steps and expectations:
+# 1. Creates pending changes for the rebalance, verifying load adjustments
+#    immediately reflect the pending state.
+# 2. Simulates enactment: when s1's leaseholder message arrives without the
+#    range (indicating s1 no longer has the lease), both changes are considered
+#    enacted simultaneously. The range state is removed since the lease moved to
+#    a non-local store.
+# 3. Tracks load adjustments: pending changes adjust load until store-reported
+#    load reflects the change (after >10s of enactment). Load messages arriving
+#    too early (<10s after enactment) result in incorrect adjusted loads (negative
+#    for s1, inflated for s2) until later load messages arrive.
+# 4. Verifies changes are removed from load tracking once store-reported load
+#    reflects the change.
 set-store
   store-id=1 node-id=1 attrs=purple locality-tiers=region=us-west-1,zone=us-west-1a
   store-id=2 node-id=2 attrs=yellow locality-tiers=region=us-east-1,zone=us-east-1a
@@ -125,9 +144,9 @@ store-load-msg
   store-id=1 node-id=2 load=[5,5,5] capacity=[100,100,100] secondary-load=1 load-time=14s
 ----
 
-# Neither load is recent enough to be considered as accounting for the enacted
-# changes. So s2 adjusted load appears very high and s1 adjusted load becomes
-# negative.
+# Neither load is recent enough (computePendingChangesReflectedInLatestLoad
+# timeout) to be considered as accounting for the enacted changes. So s2
+# adjusted load appears very high and s1 adjusted load becomes negative.
 get-load-info
 ----
 store-id=1 node-id=1 reported=[cpu:5, write-bandwidth:5, byte-size:5] adjusted=[cpu:-75, write-bandwidth:-75, byte-size:-75] node-reported-cpu=80 node-adjusted-cpu=-80 seq=6

pkg/kv/kvserver/allocator/mmaprototype/testdata/cluster_state/rebalance_replica_local_stores

@@ -1,3 +1,28 @@
+# Tests rebalancing a replica between two local stores (stores on the same node).
+#
+# Scenario: Two stores (s1, s2) on node 1. Initially, s1 holds the replica and
+# lease for range 1. The test rebalances the replica (and lease) from s1 to s2,
+# then back from s2 to s1.
+#
+# Steps and expectations:
+# 1. Creates pending changes for the rebalance, verifying load adjustments
+#    immediately reflect the pending state.
+# 2. Simulates enactment: when s2's leaseholder message arrives showing it has
+#    the lease, change 1 (add to s2) is marked enacted. Change 2 (remove from
+#    s1) remains pending until s1 is removed from the replica set.
+# 3. Verifies enacted changes cannot be rejected (they're removed from
+#    pendingChanges).
+# 4. Verifies no-rollback changes cannot be rejected once any change in the
+#    set is enacted.
+# 5. Tracks load adjustments: pending changes adjust load until store-reported
+#    load reflects the change (after 10s of enactment). After that, the change
+#    is removed from load tracking but may remain for GC.
+# 6. Tests GC: changes marked no-rollback cannot be GC'd via normal GC (which
+#    requires undo). They're only removed once store-reported load reflects the
+#    change.
+# 7. Rebalances back from s2 to s1 and verifies changes are GC'd after the
+#    normal GC duration.
+#
 # Two stores on the same node.
 set-store
   store-id=1 node-id=1 attrs=purple locality-tiers=region=us-west-1,zone=us-west-1a

pkg/kv/kvserver/allocator/mmaprototype/testdata/cluster_state/rebalance_replica_local_stores_enacted_gc

@@ -1,4 +1,17 @@
-# Two stores on the same node.
+# Tests GC of partially enacted changes when rebalancing between local stores.
+# This is a variation of rebalance_replica_local_stores in which a rebalancing
+# operation is partially enacted but the remainder is ultimately garbage collected.
+#
+# - The range initially initially sits on (n1s1,n3s3), and is then rebalanced to
+#   (n1s2,n3s4), i.e. moved between n1's two stores.
+# - The second half of the pending change (removal of s1) never gets enacted.
+# - That change is pending is no-rollback due to the first half having been enacted.
+#   After 30s (partiallyEnactedGCDuration) has elapsed since the partial
+#   enactment, the removal is GC'd with the next leaseholder message. In
+#   particular, this change does not have to wait for the much longer regular GC
+#   timeout.
+# - A second rebalance is carried out on the same range, while an enacted remnant
+#   of the first operation remains.
 set-store
   store-id=1 node-id=1 attrs=purple locality-tiers=region=us-west-1,zone=us-west-1a
   store-id=2 node-id=1 attrs=yellow locality-tiers=region=us-east-1,zone=us-east-1a
@@ -109,7 +122,9 @@ change-id=2 store-id=1 node-id=1 range-id=1 load-delta=[cpu:-2, write-bandwidth:
   prev=(replica-id=1 type=VOTER_FULL leaseholder=true)
   next=(replica-id=none type=VOTER_FULL)
 
-# Same store leaseholder msg from s2. The pending change for s1 is gc'd.
+# Same store leaseholder msg from s2. The pending change for s1 is gc'd because
+# the more aggressive partiallyEnactedGCDuration (30s) applies. It is immaterial
+# that the message originates from s2 and not s1.
 store-leaseholder-msg
 store-id=2
   range-id=1 load=[3,3,3] raft-cpu=2 config=(num_replicas=3 constraints={'+region=us-west-1:1'} voter_constraints={'+region=us-west-1:1'})