snapshot of https://github.com/seaweedfs/seaweedfs.git (master, 2026-09-16; blobs > 131072B omitted)

weed/storage/erasure_coding/ecbalancer/balancer_test.go

@@ -0,0 +1,863 @@
+package ecbalancer
+
+import (
+	"testing"
+
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+	"github.com/seaweedfs/seaweedfs/weed/storage/super_block"
+)
+
+func bits(ids ...int) erasure_coding.ShardBits {
+	var b erasure_coding.ShardBits
+	for _, id := range ids {
+		b = b.Set(erasure_coding.ShardId(id))
+	}
+	return b
+}
+
+// addEmptyNode adds an EC-empty destination node with six disks and capacity.
+func addEmptyNode(t *Topology, id, rackKey string) {
+	n := t.AddNode(id, "dc1", rackKey, 600)
+	for d := uint32(1); d <= 6; d++ {
+		n.AddDisk(d, "", 100, 0)
+	}
+}
+
+func ratio(d, p int) func(string) (int, int) {
+	return func(string) (int, int) { return d, p }
+}
+
+func TestPickBestDiskOnNode(t *testing.T) {
+	const vid = uint32(100)
+	const ds = erasure_coding.DataShardsCount
+	vk := volKey{collection: "c", vid: vid}
+
+	t.Run("skips disks with no free slots", func(t *testing.T) {
+		topo := NewTopology()
+		n := topo.AddNode("n1", "dc1", "dc1:r1", 100)
+		n.AddDisk(1, "", 0, 0)
+		n.AddDisk(2, "", 10, 0)
+		if got := pickBestDiskOnNode(n, vk, "", 0, ds); got != 2 {
+			t.Errorf("got disk %d, want 2", got)
+		}
+	})
+
+	t.Run("spreads a volume's shards across disks", func(t *testing.T) {
+		topo := NewTopology()
+		n := topo.AddNode("n1", "dc1", "dc1:r1", 100)
+		n.AddDisk(1, "", 10, 1)
+		n.AddDisk(2, "", 10, 0)
+		n.AddShards(vid, "c", 1, bits(0))
+		if got := pickBestDiskOnNode(n, vk, "", 5, ds); got != 2 {
+			t.Errorf("got disk %d, want 2 (disk 1 already holds this volume)", got)
+		}
+	})
+
+	t.Run("data shard avoids disk holding parity", func(t *testing.T) {
+		topo := NewTopology()
+		n := topo.AddNode("n1", "dc1", "dc1:r1", 100)
+		n.AddDisk(1, "", 10, 1)
+		n.AddDisk(2, "", 10, 0)
+		n.AddShards(vid, "c", 1, bits(ds)) // parity on disk 1
+		if got := pickBestDiskOnNode(n, vk, "", 0, ds); got != 2 {
+			t.Errorf("got disk %d, want 2 (anti-affinity)", got)
+		}
+	})
+
+	t.Run("anti-affinity follows the supplied ratio boundary", func(t *testing.T) {
+		topo := NewTopology()
+		n := topo.AddNode("n1", "dc1", "dc1:r1", 100)
+		n.AddDisk(1, "", 10, 1)
+		n.AddDisk(2, "", 10, 2)
+		n.AddShards(vid, "c", 1, bits(7)) // parity at 6+3
+		n.AddShards(vid, "c", 2, bits(2)) // data
+		if got := pickBestDiskOnNode(n, vk, "", 1, 6); got != 2 {
+			t.Errorf("ratio 6: got disk %d, want 2", got)
+		}
+		if got := pickBestDiskOnNode(n, vk, "", 1, erasure_coding.DataShardsCount); got != 1 {
+			t.Errorf("boundary 10: got disk %d, want 1", got)
+		}
+	})
+
+	t.Run("only matching disk type when set", func(t *testing.T) {
+		topo := NewTopology()
+		n := topo.AddNode("n1", "dc1", "dc1:r1", 100)
+		n.AddDisk(1, "ssd", 10, 0)
+		n.AddDisk(2, "hdd", 10, 0)
+		if got := pickBestDiskOnNode(n, vk, "hdd", 0, ds); got != 2 {
+			t.Errorf("got disk %d, want 2 (only hdd)", got)
+		}
+	})
+}
+
+func TestPlanSourceDiskAttribution(t *testing.T) {
+	shardsByDisk := map[uint32][]int{0: {0, 1, 2}, 1: {3, 4, 5}, 2: {6, 7}, 3: {8, 9}, 4: {10, 11}, 5: {12, 13}}
+	shardToDisk := map[int]uint32{}
+	for d, ss := range shardsByDisk {
+		for _, s := range ss {
+			shardToDisk[s] = d
+		}
+	}
+	topo := NewTopology()
+	src := topo.AddNode("node1", "dc1", "dc1:rack1", 0)
+	for d, ss := range shardsByDisk {
+		src.AddDisk(d, "", 0, len(ss))
+		src.AddShards(100, "col1", d, bits(ss...))
+	}
+	addEmptyNode(topo, "node2", "dc1:rack2")
+
+	moves := Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(10, 4)})
+	if len(moves) == 0 {
+		t.Fatal("expected moves")
+	}
+	for _, m := range moves {
+		if m.Phase != "cross_rack" {
+			continue
+		}
+		if want := shardToDisk[m.ShardID]; m.SourceDisk != want {
+			t.Errorf("shard %d: source disk %d, want %d", m.ShardID, m.SourceDisk, want)
+		}
+	}
+}
+
+func TestPlanSpreadsAcrossDestinationDisks(t *testing.T) {
+	topo := NewTopology()
+	src := topo.AddNode("node1", "dc1", "dc1:rack1", 0)
+	src.AddDisk(0, "", 0, 14)
+	src.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13))
+	addEmptyNode(topo, "node2", "dc1:rack2")
+
+	moves := Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(10, 4)})
+	distinct := map[uint32]bool{}
+	crossRack := 0
+	for _, m := range moves {
+		if m.Phase == "cross_rack" {
+			crossRack++
+			distinct[m.TargetDisk] = true
+		}
+	}
+	if crossRack != 7 {
+		t.Fatalf("got %d cross-rack moves, want 7", crossRack)
+	}
+	if len(distinct) != 6 {
+		t.Errorf("cross-rack moves used %d distinct disks, want 6: %v", len(distinct), distinct)
+	}
+}
+
+func TestPlanCrossRackParityAntiAffinity(t *testing.T) {
+	topo := NewTopology()
+	src := topo.AddNode("node1", "dc1", "dc1:rack1", 0)
+	src.AddDisk(0, "", 0, 3)
+	src.AddShards(100, "col1", 0, bits(0, 1, 2)) // 1 data + 2 parity at ratio 1+2
+	addEmptyNode(topo, "node2", "dc1:rack2")
+	addEmptyNode(topo, "node3", "dc1:rack3")
+
+	moves := Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(1, 2)})
+	if len(moves) == 0 {
+		t.Fatal("expected parity moves across racks")
+	}
+	for _, m := range moves {
+		if m.ShardID < 1 {
+			t.Errorf("data shard %d moved; it fits in rack1", m.ShardID)
+		}
+		if m.TargetNode == "node1" {
+			t.Errorf("parity shard %d moved onto data-bearing node1", m.ShardID)
+		}
+	}
+}
+
+func TestWithinRackParityAntiAffinity(t *testing.T) {
+	// Test the within-rack phase in isolation (the global phase, which balances
+	// total load, would otherwise also act on this single rack).
+	topo := NewTopology()
+	src := topo.AddNode("node1", "dc1", "dc1:rack1", 600)
+	src.AddDisk(0, "", 600, 3)
+	src.AddShards(100, "col1", 0, bits(0, 1, 2))
+	addEmptyNode(topo, "node2", "dc1:rack1")
+	addEmptyNode(topo, "node3", "dc1:rack1")
+
+	racks := buildRacks(topo.nodes)
+	moves := detectWithinRackImbalance(volKey{collection: "col1", vid: 100}, topo.nodes, racks, "", 0.01, 1, 2, nil)
+	if len(moves) == 0 {
+		t.Fatal("expected parity moves within rack")
+	}
+	for _, m := range moves {
+		if m.shardID < 1 {
+			t.Errorf("data shard %d moved; it fits on node1", m.shardID)
+		}
+		if m.target.id == "node1" {
+			t.Errorf("parity shard %d moved onto data-bearing node1", m.shardID)
+		}
+	}
+}
+
+func TestPlanReplicaPlacementCapsPerRack(t *testing.T) {
+	build := func() *Topology {
+		topo := NewTopology()
+		src := topo.AddNode("node1", "dc1", "dc1:rack1", 0)
+		src.AddDisk(0, "", 0, 6)
+		src.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5)) // all data at ratio 6+0
+		addEmptyNode(topo, "node2", "dc1:rack2")
+		addEmptyNode(topo, "node3", "dc1:rack3")
+		return topo
+	}
+
+	countCross := func(moves []Move) int {
+		n := 0
+		for _, m := range moves {
+			if m.Phase == "cross_rack" {
+				n++
+			}
+		}
+		return n
+	}
+
+	if got := countCross(Plan(build(), Options{ImbalanceThreshold: 0.01, Ratio: ratio(6, 0)})); got != 4 {
+		t.Fatalf("without replica placement: %d cross-rack moves, want 4", got)
+	}
+	rp := &super_block.ReplicaPlacement{DiffRackCount: 1}
+	if got := countCross(Plan(build(), Options{ImbalanceThreshold: 0.01, ReplicaPlacement: rp, Ratio: ratio(6, 0)})); got != 2 {
+		t.Errorf("with DiffRackCount=1: %d cross-rack moves, want 2", got)
+	}
+}
+
+func TestPlanDedup(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 5)
+	n1.AddDisk(0, "", 5, 2)
+	n1.AddShards(100, "col1", 0, bits(0, 1))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack2", 10)
+	n2.AddDisk(0, "", 10, 1)
+	n2.AddShards(100, "col1", 0, bits(0)) // shard 0 duplicated on node2
+
+	var dedup []Move
+	for _, m := range Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(10, 4)}) {
+		if m.Phase == "dedup" {
+			dedup = append(dedup, m)
+		}
+	}
+	if len(dedup) != 1 {
+		t.Fatalf("got %d dedup moves, want 1", len(dedup))
+	}
+	if dedup[0].ShardID != 0 || dedup[0].SourceNode != "node1" || dedup[0].TargetNode != "node1" {
+		t.Errorf("dedup move = %+v, want shard 0 deleted on node1 (fewer free slots)", dedup[0])
+	}
+}
+
+func TestCeilDivide(t *testing.T) {
+	for _, tc := range []struct{ a, b, want int }{{14, 3, 5}, {10, 3, 4}, {0, 5, 0}, {5, 0, 0}} {
+		if got := ceilDivide(tc.a, tc.b); got != tc.want {
+			t.Errorf("ceilDivide(%d,%d)=%d want %d", tc.a, tc.b, got, tc.want)
+		}
+	}
+}
+
+func allBits(n int) erasure_coding.ShardBits {
+	var b erasure_coding.ShardBits
+	for i := 0; i < n; i++ {
+		b = b.Set(erasure_coding.ShardId(i))
+	}
+	return b
+}
+
+// TestPlanConvergesToBalancedLoadOverRounds starts skewed -- machine 10.0.0.1 holds
+// 4 shards of every volume, the others 2 -- and runs repeated worker-style balance
+// passes (capped moves per pass). It must converge to an even per-machine shard load.
+func TestPlanConvergesToBalancedLoadOverRounds(t *testing.T) {
+	topo := NewTopology()
+	hosts := []string{"10.0.0.1", "10.0.0.2", "10.0.0.3", "10.0.0.4", "10.0.0.5", "10.0.0.6"}
+	for _, h := range hosts {
+		for _, p := range []string{":8080", ":8081"} {
+			n := topo.AddNode(h+p, "dc1", "dc1:rack1", 4000)
+			n.SetHost(h)
+			n.AddDisk(0, "", 4000, 0)
+		}
+	}
+	add := func(id string, vid uint32, ids ...int) {
+		n := topo.nodes[id]
+		n.AddShards(vid, "c1", 0, bits(ids...))
+		n.disks[0].shardCount += len(ids)
+		n.disks[0].freeSlots -= len(ids)
+		n.freeSlots -= len(ids)
+	}
+	const volumes = 60
+	for v := 0; v < volumes; v++ {
+		vid := uint32(v)
+		add("10.0.0.1:8080", vid, 0, 1) // machine 10.0.0.1 gets 4 shards/volume
+		add("10.0.0.1:8081", vid, 2, 3)
+		add("10.0.0.2:8080", vid, 4)
+		add("10.0.0.2:8081", vid, 5)
+		add("10.0.0.3:8080", vid, 6)
+		add("10.0.0.3:8081", vid, 7)
+		add("10.0.0.4:8080", vid, 8)
+		add("10.0.0.4:8081", vid, 9)
+		add("10.0.0.5:8080", vid, 10)
+		add("10.0.0.5:8081", vid, 11)
+		add("10.0.0.6:8080", vid, 12)
+		add("10.0.0.6:8081", vid, 13)
+	}
+
+	perMachine := func() map[string]int {
+		m := map[string]int{}
+		for _, h := range hosts {
+			m[h] = 0 // seed every host so a fully drained one still counts
+		}
+		for _, n := range topo.nodes {
+			for _, info := range n.shards {
+				m[n.host] += info.shardBits.Count()
+			}
+		}
+		return m
+	}
+	opts := Options{Ratio: ratio(10, 4), GlobalUtilizationBased: true, GlobalMaxMovesPerRack: 8}
+
+	rounds, converged := 0, false
+	for ; rounds < 200; rounds++ {
+		if len(Plan(topo, opts)) == 0 {
+			converged = true
+			break
+		}
+	}
+	if !converged {
+		t.Fatalf("balance did not converge within %d rounds", rounds)
+	}
+
+	pm := perMachine()
+	min, max := 1<<30, 0
+	for _, c := range pm {
+		if c < min {
+			min = c
+		}
+		if c > max {
+			max = c
+		}
+	}
+	t.Logf("converged after %d rounds: %v", rounds, pm)
+	if rounds < 2 {
+		t.Errorf("expected convergence to take multiple rounds (capped moves), took %d", rounds)
+	}
+	if float64(max) > 1.1*float64(min) {
+		t.Errorf("did not converge to balanced load: min=%d max=%d %v", min, max, pm)
+	}
+}
+
+func TestGlobalImbalanceMovesFromFullToEmpty(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 5)
+	n1.AddShards(100, "col1", 0, allBits(14))
+	n1.AddShards(200, "col1", 0, allBits(6))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack1", 30)
+	n2.AddShards(300, "col1", 0, allBits(2))
+
+	moves := detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, nil, nil, 0, true)
+	if len(moves) == 0 {
+		t.Fatal("expected global balance moves")
+	}
+	for _, m := range moves {
+		if m.phase != "global" || m.source.id != "node1" || m.target.id != "node2" {
+			t.Errorf("move = %+v, want global node1->node2", m)
+		}
+	}
+}
+
+// TestGlobalImbalanceHeterogeneousCapacity: node1 holds more shards but is less
+// utilized (high capacity); moves must drain the more-utilized node2.
+func TestGlobalImbalanceHeterogeneousCapacity(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 90)
+	n1.AddShards(100, "col1", 0, allBits(10))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack1", 2)
+	n2.AddShards(200, "col1", 0, allBits(3))
+
+	moves := detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, nil, nil, 0, true)
+	if len(moves) == 0 {
+		t.Fatal("expected moves from high-util node2 to low-util node1")
+	}
+	seen := map[[2]int]bool{}
+	for _, m := range moves {
+		if m.source.id != "node2" || m.target.id != "node1" {
+			t.Errorf("move = %+v, want node2->node1", m)
+		}
+		key := [2]int{int(m.volumeID), m.shardID}
+		if seen[key] {
+			t.Errorf("duplicate move for volume %d shard %d", m.volumeID, m.shardID)
+		}
+		seen[key] = true
+	}
+}
+
+func TestGlobalImbalanceSkipsFullNodes(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 10)
+	n1.AddShards(100, "col1", 0, allBits(14))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack1", 0) // full, cannot receive
+	n2.AddShards(200, "col1", 0, allBits(2))
+
+	if moves := detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, nil, nil, 0, true); len(moves) != 0 {
+		t.Fatalf("expected 0 moves (node2 full), got %d", len(moves))
+	}
+}
+
+// TestPlanBalancesSkewedDataParityWithEvenTotals guards the per-type gate: two
+// racks hold equal shard totals (7 each) but the data shards are skewed (7 vs 3).
+// A total-count gate would skip balancing; the per-type gate must still act.
+func TestPlanBalancesSkewedDataParityWithEvenTotals(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 100)
+	n1.AddDisk(0, "", 100, 7)
+	n1.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5, 6)) // 7 data shards
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack2", 100)
+	n2.AddDisk(0, "", 100, 7)
+	n2.AddShards(100, "col1", 0, bits(7, 8, 9, 10, 11, 12, 13)) // 3 data + 4 parity
+
+	moves := Plan(topo, Options{ImbalanceThreshold: 0, Ratio: ratio(10, 4)})
+
+	crossRack, dataMoved := 0, 0
+	for _, m := range moves {
+		if m.Phase == "cross_rack" {
+			crossRack++
+			if m.ShardID < 10 {
+				dataMoved++
+			}
+		}
+	}
+	if crossRack == 0 {
+		t.Fatal("even totals masked a data/parity skew: no cross-rack moves produced")
+	}
+	if dataMoved == 0 {
+		t.Error("expected skewed data shards to rebalance across racks")
+	}
+}
+
+// TestPlanVolumeRatioOverridesCollection verifies the per-volume ratio (reported on
+// the heartbeat, surfaced via Options.VolumeRatio) takes precedence over the
+// collection ratio, so a mixed-ratio collection is classified and spread by each
+// volume's own data/parity split. The same 14-shard volume is planned three ways:
+// the per-volume 7+7 override must reproduce the 7+7-collection plan and differ from
+// the 10+4-collection plan. A VolumeRatio that returns 0 defers to the collection
+// ratio (the always-0 OSS case), so existing collection-keyed behavior is preserved.
+func TestPlanVolumeRatioOverridesCollection(t *testing.T) {
+	build := func() *Topology {
+		topo := NewTopology()
+		n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 100)
+		n1.AddDisk(0, "", 100, 7)
+		n1.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5, 6))
+		n2 := topo.AddNode("node2", "dc1", "dc1:rack2", 100)
+		n2.AddDisk(0, "", 100, 7)
+		n2.AddShards(100, "col1", 0, bits(7, 8, 9, 10, 11, 12, 13))
+		return topo
+	}
+	crossRack := func(moves []Move) int {
+		n := 0
+		for _, m := range moves {
+			if m.Phase == "cross_rack" {
+				n++
+			}
+		}
+		return n
+	}
+
+	collection104 := crossRack(Plan(build(), Options{ImbalanceThreshold: 0, Ratio: ratio(10, 4)}))
+	collection77 := crossRack(Plan(build(), Options{ImbalanceThreshold: 0, Ratio: ratio(7, 7)}))
+	if collection104 == collection77 {
+		t.Fatalf("test setup: 10+4 and 7+7 collection plans must differ, both gave %d cross-rack moves", collection104)
+	}
+
+	// Collection ratio stays 10+4, but vol100 reports 7+7 per-volume; the planner
+	// must classify/spread vol100 as 7+7 and match the 7+7-collection plan.
+	perVolume := crossRack(Plan(build(), Options{
+		ImbalanceThreshold: 0,
+		Ratio:              ratio(10, 4),
+		VolumeRatio: func(collection string, vid uint32) (int, int) {
+			if collection == "col1" && vid == 100 {
+				return 7, 7
+			}
+			return 0, 0
+		},
+	}))
+	if perVolume != collection77 {
+		t.Errorf("per-volume 7+7 override gave %d cross-rack moves, want %d (the 7+7-collection plan)", perVolume, collection77)
+	}
+	if perVolume == collection104 {
+		t.Errorf("per-volume override had no effect: %d cross-rack moves, same as the 10+4 collection plan", perVolume)
+	}
+}
+
+// TestGlobalPrefersVolumeAbsentFromDestination guards the global phase's
+// volume-diversity preference: when draining a node, move a shard of a volume the
+// destination does not hold at all before piling a second shard of an
+// already-present volume onto it. node1 (full) holds vol100 and vol200; node2
+// (empty) holds only vol100, so the first global move should be a vol200 shard.
+func TestGlobalPrefersVolumeAbsentFromDestination(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 0)
+	n1.AddShards(100, "col1", 0, bits(0, 1))
+	n1.AddShards(200, "col1", 0, bits(0, 1))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack1", 3)
+	n2.AddShards(100, "col1", 0, bits(2))
+
+	moves := detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, nil, nil, 0, true)
+	if len(moves) == 0 {
+		t.Fatal("expected a global move from the full node")
+	}
+	if moves[0].volumeID != 200 {
+		t.Errorf("first global move is volume %d, want 200 (the volume absent from node2)", moves[0].volumeID)
+	}
+	for _, m := range moves {
+		if m.source.id != "node1" || m.target.id != "node2" {
+			t.Errorf("move %+v, want node1->node2", m)
+		}
+	}
+}
+
+// TestPlanKeepsCollectionsWithSameVolumeIdDistinct guards EC identity: a numeric
+// volume id reused across collections must not be merged. (A,5) on node1 and
+// (B,5) on node2 are different volumes, so neither dedup nor any move should
+// treat them as copies of one another.
+func TestPlanKeepsCollectionsWithSameVolumeIdDistinct(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 100)
+	n1.AddDisk(0, "", 100, 1)
+	n1.AddShards(5, "A", 0, bits(0))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack2", 100)
+	n2.AddDisk(0, "", 100, 1)
+	n2.AddShards(5, "B", 0, bits(0))
+
+	for _, m := range Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(10, 4)}) {
+		if m.Phase == "dedup" {
+			t.Errorf("dedup %+v: (A,5) and (B,5) are different volumes and must not be deduped", m)
+		}
+	}
+}
+
+// TestDedupFreesCapacityForLaterPhases checks that capacity opened by deleting a
+// duplicate is usable by a later phase in the same Plan. node2 is full (0 free)
+// but holds a duplicate of node1's shard 0; node1 is roomier, so dedup deletes
+// node2's copy, freeing a slot. The within-rack phase must then be able to move a
+// shard onto node2.
+func TestDedupFreesCapacityForLaterPhases(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("node1", "dc1", "dc1:rack1", 5)
+	n1.AddDisk(0, "", 5, 7)
+	n1.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5, 6))
+	n2 := topo.AddNode("node2", "dc1", "dc1:rack1", 0) // full
+	n2.AddDisk(0, "", 0, 1)
+	n2.AddShards(100, "col1", 0, bits(0)) // duplicate of node1's shard 0
+
+	moves := Plan(topo, Options{ImbalanceThreshold: 0.01, Ratio: ratio(10, 4)})
+
+	dedup := false
+	toNode2 := 0
+	for _, m := range moves {
+		if m.Phase == "dedup" {
+			dedup = true
+			continue
+		}
+		if m.TargetNode == "node2" {
+			toNode2++
+		}
+	}
+	if !dedup {
+		t.Fatal("expected a dedup move for the duplicated shard 0")
+	}
+	if toNode2 == 0 {
+		t.Error("slot freed by dedup on node2 was not usable by a later phase")
+	}
+}
+
+// TestWithinRackSpreadsAcrossMachines: a 10+4 volume's 14 shards all sit on boxA
+// (two of its servers), with three other machines free. Four machines is enough for
+// the spread to stay within parity, so the within-rack phase must move shards out
+// until no machine holds more than ceil(14/4)=4, even though they looked spread
+// across boxA's two nodes.
+func TestWithinRackSpreadsAcrossMachines(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id, host string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.SetHost(host)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	a1 := mk("a1", "boxA")
+	a2 := mk("a2", "boxA")
+	mk("b1", "boxB")
+	mk("c1", "boxC")
+	mk("d1", "boxD")
+	a1.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5, 6))     // 7 shards on boxA
+	a2.AddShards(100, "col1", 0, bits(7, 8, 9, 10, 11, 12, 13)) // 7 shards on boxA (all 14)
+
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 10, 4, nil)
+
+	perHost := map[string]int{}
+	for _, n := range topo.nodes {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			perHost[n.host] += info.shardBits.Count()
+		}
+	}
+	if len(perHost) < 3 {
+		t.Fatalf("shards not spread across machines: %v", perHost)
+	}
+	for h, c := range perHost {
+		if c > 4 {
+			t.Errorf("machine %s holds %d shards, want <=4 (ceil(14/4), within parity)", h, c)
+		}
+	}
+}
+
+// TestWithinRackMachineSpreadBalancesCombinedOccupancy: a 5+5 volume on two machines
+// where each shard type is already within its own per-type cap (boxA 3 data + 3
+// parity = 6, boxB 2 data + 2 parity = 4). Spreading data and parity independently
+// would leave boxA at 6, past parity; balancing the combined count must move one
+// shard to reach 5/5 so a machine loss stays recoverable.
+func TestWithinRackMachineSpreadBalancesCombinedOccupancy(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id, host string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.SetHost(host)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	a1 := mk("a1", "boxA")
+	a2 := mk("a2", "boxA") // two nodes on boxA -> numMachines(2) < numNodes(3)
+	b1 := mk("b1", "boxB")
+	a1.AddShards(100, "col1", 0, bits(0, 1, 2))    // 3 data
+	a2.AddShards(100, "col1", 0, bits(5, 6, 7))    // 3 parity (ids >= 5)
+	b1.AddShards(100, "col1", 0, bits(3, 4, 8, 9)) // 2 data + 2 parity
+
+	// dataShards=5, parityShards=5: feasibility ceil(10/2)=5 <= 5, so machine spread runs.
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 5, 5, nil)
+
+	perHost := map[string]int{}
+	for _, n := range topo.nodes {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			perHost[n.host] += info.shardBits.Count()
+		}
+	}
+	if perHost["boxA"] > 5 {
+		t.Errorf("boxA holds %d shards, want <=5 (parity); data and parity spread independently", perHost["boxA"])
+	}
+}
+
+// TestWithinRackMachineSpreadActsOnExactlyHalfSkew: a 5/4/3 machine layout for a 10+4
+// volume is only 50% skewed ((5-3)/4 = 0.5), which a 0.5 relative-imbalance threshold
+// would skip -- but the 5-shard machine is already past parity. The spread must act
+// regardless (the even cap, not a skew threshold, is the bound) and bring every
+// machine to <=ceil(12/3)=4.
+func TestWithinRackMachineSpreadActsOnExactlyHalfSkew(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id, host string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.SetHost(host)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	a1 := mk("a1", "boxA")
+	a2 := mk("a2", "boxA")
+	b1 := mk("b1", "boxB")
+	b2 := mk("b2", "boxB")
+	c1 := mk("c1", "boxC")
+	c2 := mk("c2", "boxC")
+	a1.AddShards(100, "col1", 0, bits(0, 1, 2))
+	a2.AddShards(100, "col1", 0, bits(3, 4)) // boxA = 5
+	b1.AddShards(100, "col1", 0, bits(5, 6))
+	b2.AddShards(100, "col1", 0, bits(7, 8)) // boxB = 4
+	c1.AddShards(100, "col1", 0, bits(9, 10))
+	c2.AddShards(100, "col1", 0, bits(11)) // boxC = 3
+
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 10, 4, nil)
+
+	perHost := map[string]int{}
+	for _, n := range topo.nodes {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			perHost[n.host] += info.shardBits.Count()
+		}
+	}
+	for h, c := range perHost {
+		if c > 4 {
+			t.Errorf("machine %s holds %d shards, want <=4 (ceil(12/3)); a 50%% skew was skipped", h, c)
+		}
+	}
+}
+
+// TestWithinRackSpreadUsesRackLocalShardCount: a rack holds only 7 shards of a 10+4
+// volume (cross-rack spreading moved the rest to other racks). Two machines can hold
+// those 7 within parity (ceil(7/2)=4), so machine spread must apply -- gating on the
+// full 14-shard total would wrongly fall back to node spread and pile 6 onto boxA's
+// two nodes, exceeding parity.
+func TestWithinRackSpreadUsesRackLocalShardCount(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id, host string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.SetHost(host)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	a1 := mk("a1", "boxA")
+	a2 := mk("a2", "boxA")
+	mk("b1", "boxB")
+	a1.AddShards(100, "col1", 0, bits(0, 1, 2, 3))
+	a2.AddShards(100, "col1", 0, bits(4, 5, 6)) // boxA holds all 7 of this rack's shards
+
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 10, 4, nil)
+
+	perHost := map[string]int{}
+	for _, n := range topo.nodes {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			perHost[n.host] += info.shardBits.Count()
+		}
+	}
+	if perHost["boxA"] > 4 {
+		t.Errorf("boxA holds %d shards, want <=4 (parity); rack-local feasibility not used", perHost["boxA"])
+	}
+	if perHost["boxB"] == 0 {
+		t.Error("no shards moved to boxB; machine spread did not apply")
+	}
+}
+
+// TestWithinRackNodeFallbackHonorsThreshold: one server per host with a 6/4 data
+// split is the cosmetic node fallback (a 2-node rack can't be machine-fault-tolerant
+// for a 10+4 volume). At 40% skew it's below the 0.5 threshold, so it must be left to
+// the global utilization phase rather than churned -- a count move here can worsen
+// utilization on unequal-capacity nodes.
+func TestWithinRackNodeFallbackHonorsThreshold(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	n1 := mk("n1") // distinct hosts (default host = id) -> node fallback
+	n2 := mk("n2")
+	n1.AddShards(100, "col1", 0, bits(0, 1, 2, 3, 4, 5)) // 6 data
+	n2.AddShards(100, "col1", 0, bits(6, 7, 8, 9))       // 4 data
+
+	moves := detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0.5, 10, 4, nil)
+	if len(moves) != 0 {
+		t.Errorf("node fallback moved %d shards on a 40%%-skewed 6/4 layout at threshold 0.5; want 0", len(moves))
+	}
+}
+
+// TestWithinRackSpreadDefaultsToNodes: with no SetHost each node is its own
+// machine, so the within-rack phase still spreads a volume off an overloaded node
+// exactly as before (machine grouping reduces to node grouping).
+func TestWithinRackSpreadDefaultsToNodes(t *testing.T) {
+	topo := NewTopology()
+	mk := func(id string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	n1 := mk("n1")
+	mk("n2")
+	mk("n3")
+	n1.AddShards(100, "col1", 0, allBits(14)) // all 14 piled on one node
+
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 10, 4, nil)
+
+	perNode := map[string]int{}
+	for id, n := range topo.nodes {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			perNode[id] = info.shardBits.Count()
+		}
+	}
+	if perNode["n1"] == 14 {
+		t.Fatal("no within-rack spread happened with one server per host")
+	}
+	if len(perNode) < 3 {
+		t.Errorf("shards not spread across all three nodes: %v", perNode)
+	}
+	// Per-type even caps: ceil(10/3) data + ceil(4/3) parity = 4+2 per node.
+	for id, c := range perNode {
+		if c > 6 {
+			t.Errorf("node %s holds %d shards, want <=6 (dataCap+parityCap)", id, c)
+		}
+	}
+}
+
+// TestGlobalDoesNotConcentrateVolumeAcrossMachines: when the volume's machine spread
+// is achievable (here 2 machines, a 2+2 volume, one machine can hold <= parity), a
+// load move must not raise a machine's shard count of the volume past the source's.
+// boxA's only volume is also on boxB, so pass 0 finds nothing and the sole pass-1
+// option is the cross-machine boxA->boxB move, which must be rejected (boxB already
+// holds as many shards as boxA). Same-machine node rebalancing would still be fine.
+func TestGlobalDoesNotConcentrateVolumeAcrossMachines(t *testing.T) {
+	topo := NewTopology()
+	a1 := topo.AddNode("a1", "dc1", "dc1:rack1", 0) // full -> high util, the max node
+	a1.SetHost("boxA")
+	a1.AddShards(100, "col1", 0, bits(0, 1))
+	b1 := topo.AddNode("b1", "dc1", "dc1:rack1", 0) // full -> cannot receive
+	b1.SetHost("boxB")
+	b1.AddShards(100, "col1", 0, bits(2, 3))
+	b2 := topo.AddNode("b2", "dc1", "dc1:rack1", 10) // empty -> low util, the min node
+	b2.SetHost("boxB")
+
+	data := map[volKey]int{{collection: "col1", vid: 100}: 2}
+	parity := map[volKey]int{{collection: "col1", vid: 100}: 2}
+	for _, m := range detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, data, parity, 0, true) {
+		if m.source.host != m.target.host {
+			t.Errorf("cross-machine global move %d.%d from %s to %s concentrates the volume on a machine",
+				m.volumeID, m.shardID, m.source.host, m.target.host)
+		}
+	}
+}
+
+// TestWithinRackMachineSkipsCappedMachine: a machine whose only node is already at
+// the per-node SameRackCount cap is not a viable target, and the within-rack spread
+// must move shards to the next machine that is, rather than picking the capped one
+// and skipping the move. Four machines (boxA has two nodes) make the spread active;
+// boxB's node holds two parity shards (== SameRackCount), so boxA's over-concentrated
+// data shards must land on the viable boxC/boxD.
+func TestWithinRackMachineSkipsCappedMachine(t *testing.T) {
+	rp, _ := super_block.NewReplicaPlacementFromString("002") // SameRackCount=2
+	topo := NewTopology()
+	mk := func(id, host string) *Node {
+		n := topo.AddNode(id, "dc1", "dc1:rack1", 100)
+		n.SetHost(host)
+		n.AddDisk(0, "", 100, 0)
+		return n
+	}
+	a1 := mk("a1", "boxA")
+	mk("a2", "boxA") // boxA's second node makes numMachines(4) < numNodes(5)
+	b1 := mk("b1", "boxB")
+	c1 := mk("c1", "boxC")
+	d1 := mk("d1", "boxD")
+	a1.AddShards(100, "col1", 0, bits(0, 1, 2, 3)) // 4 data shards, over-concentrated on boxA
+	b1.AddShards(100, "col1", 0, bits(10, 11))     // 2 parity -> b1 at SameRackCount cap
+
+	detectWithinRackImbalance(volKey{"col1", 100}, topo.nodes, buildRacks(topo.nodes), "", 0, 10, 4, rp)
+
+	moved := 0
+	for _, n := range []*Node{c1, d1} {
+		if info, ok := n.shards[volKey{"col1", 100}]; ok {
+			moved += info.shardBits.Count()
+		}
+	}
+	if moved == 0 {
+		t.Error("data shards were not moved to the viable machines boxC/boxD; the capped boxB blocked the move")
+	}
+}
+
+// TestGlobalPrefersVolumeAbsentFromDestinationMachine: the global load phase must
+// judge "volume already present" at the machine level. boxB's sibling node holds
+// vol100, so draining boxA onto boxB's empty node should move a vol200 shard first
+// (vol200 is absent from boxB) rather than piling a second vol100 copy onto boxB.
+func TestGlobalPrefersVolumeAbsentFromDestinationMachine(t *testing.T) {
+	topo := NewTopology()
+	n1 := topo.AddNode("n1", "dc1", "dc1:rack1", 0)
+	n1.SetHost("boxA")
+	n1.AddShards(100, "col1", 0, bits(0, 1, 2, 3))
+	n1.AddShards(200, "col1", 0, bits(0, 1, 2, 3))
+	n2 := topo.AddNode("n2", "dc1", "dc1:rack1", 5)
+	n2.SetHost("boxB")
+	n2.AddShards(100, "col1", 0, bits(4)) // vol100 already on boxB (sibling node)
+	n3 := topo.AddNode("n3", "dc1", "dc1:rack1", 5)
+	n3.SetHost("boxB") // empty destination node, but its machine holds vol100
+
+	moves := detectGlobalImbalance(topo.nodes, buildRacks(topo.nodes), "", 0.01, nil, nil, 0, true)
+	if len(moves) == 0 {
+		t.Fatal("expected a global move from the full node")
+	}
+	if moves[0].volumeID != 200 {
+		t.Errorf("first global move is volume %d, want 200 (vol100 already on the destination machine)", moves[0].volumeID)
+	}
+}

weed/storage/erasure_coding/ecbalancer/place.go

@@ -0,0 +1,579 @@
+package ecbalancer
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+	"github.com/seaweedfs/seaweedfs/weed/storage/super_block"
+	storagetypes "github.com/seaweedfs/seaweedfs/weed/storage/types"
+)
+
+// Constraints configures a Place call. Ratio resolves a collection's
+// (dataShards, parityShards); nil uses the standard scheme. ReplicaPlacement,
+// when non-nil, caps shards per rack (DiffRackCount = max shards/rack) and per
+// node within a rack (SameRackCount = max shards/node); both digits are direct
+// hard caps. The data-center digit (DiffDataCenterCount) is not honored:
+// the 1-byte volume ReplicaPlacement can only encode 0-2 there, too small to be a
+// meaningful per-DC EC shard cap, so EC relies on the rack/node even spread instead.
+//
+// DiskTypePolicy controls how DiskType constrains placement (Any / Prefer /
+// Require). PreferredTags drives whole-plan tag tiering: Place tries disks
+// carrying the earliest tags first and widens to all disks only if a tier cannot
+// place every shard.
+type Constraints struct {
+	DiskType         string
+	DiskTypePolicy   DiskTypePolicy
+	PreferredTags    []string
+	ReplicaPlacement *super_block.ReplicaPlacement
+	Ratio            func(collection string) (dataShards, parityShards int)
+}
+
+// DiskTypePolicy controls how Constraints.DiskType constrains placement.
+type DiskTypePolicy int
+
+const (
+	DiskTypeAny     DiskTypePolicy = iota // any disk type
+	DiskTypePrefer                        // prefer DiskType, spill to other types if needed
+	DiskTypeRequire                       // only DiskType (HardDriveType when "")
+)
+
+// diskTypeEqual compares disk types after normalization, so "" and "hdd" (both
+// HardDriveType) are equal.
+func diskTypeEqual(a, b string) bool {
+	return storagetypes.ToDiskType(a).String() == storagetypes.ToDiskType(b).String()
+}
+
+// diskHasAnyTag reports whether the disk carries any of the given tags.
+func diskHasAnyTag(d *disk, tags []string) bool {
+	for _, want := range tags {
+		for _, have := range d.tags {
+			if have == want {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// Destination is a chosen target for one shard. DataCenter and Rack are kept as
+// separate values (matching topology.DiskInfo) rather than a "dc:rack" composite,
+// so callers read them directly instead of parsing.
+type Destination struct {
+	Node       string
+	DiskID     uint32
+	DataCenter string
+	Rack       string // bare rack id within DataCenter
+}
+
+// PlaceResult holds the chosen destinations, which constraints had to be relaxed
+// (durability-first only), and whether placement spilled outside the preferred
+// disk type or tag tiers (for parity with today's logging).
+type PlaceResult struct {
+	Destinations                map[int]Destination
+	Relaxed                     []string
+	SpilledToOtherDiskType      bool
+	SpilledOutsidePreferredTags bool
+}
+
+// PlacementMode selects the strictness/relaxation policy.
+type PlacementMode int
+
+const (
+	// PlaceStrict: caps and ReplicaPlacement are hard. Place fails rather than
+	// violate them, so the caller can defer (leave the volume as-is and retry).
+	PlaceStrict PlacementMode = iota
+	// PlaceDurabilityFirst (used by both encode and repair): relax per-type caps ->
+	// data/parity anti-affinity -> ReplicaPlacement, in that order, until each shard
+	// lands, reporting what was relaxed in PlaceResult.Relaxed. The per-disk
+	// durability cap (<= parityShards per disk) is never relaxed. Fails only if no
+	// disk has free capacity. Encode places best-effort this way and rebalancing
+	// tightens the spread afterward.
+	PlaceDurabilityFirst
+)
+
+// relaxation controls which placement-quality constraints are enforced on an
+// attempt. preferring fresh nodes (repair's "avoid surviving-shard nodes") is not
+// listed: pickNodeInRack already selects the node with the fewest shards of the
+// volume, so survivors are deprioritized with built-in fallback.
+type relaxation struct {
+	caps         bool
+	antiAffinity bool
+	rp           bool
+}
+
+func (r relaxation) relaxedNames() []string {
+	var n []string
+	if !r.caps {
+		n = append(n, "caps")
+	}
+	if !r.antiAffinity {
+		n = append(n, "anti-affinity")
+	}
+	if !r.rp {
+		n = append(n, "replica-placement")
+	}
+	return n
+}
+
+var strictAttempts = []relaxation{{caps: true, antiAffinity: true, rp: true}}
+
+var durabilityAttempts = []relaxation{
+	{caps: true, antiAffinity: true, rp: true},
+	{caps: false, antiAffinity: true, rp: true},
+	{caps: false, antiAffinity: false, rp: true},
+	{caps: false, antiAffinity: false, rp: false},
+}
+
+type placedEntry struct {
+	node    *Node
+	sid     int
+	rackKey string
+}
+
+// Place assigns destinations for the `need` shard ids of volume (collection,vid),
+// reading the volume's already-placed shards from the snapshot (so encode passes
+// an empty-for-this-volume snapshot, repair passes one seeded with the surviving
+// shards).
+//
+// Tag tiering (whole-plan retry): it tries the preferred-tag tiers in order, each
+// a complete candidate set, and returns the first tier that places every shard;
+// only when it falls through to the no-tag tier does it set
+// SpilledOutsidePreferredTags. Within a tier, disk-type Prefer spills to other
+// types per shard (SpilledToOtherDiskType); Require filters strictly.
+func (t *Topology) Place(vid uint32, collection string, need []int, c Constraints, mode PlacementMode) (*PlaceResult, error) {
+	if len(need) == 0 {
+		return &PlaceResult{Destinations: map[int]Destination{}}, nil
+	}
+
+	vk := volKey{collection: collection, vid: vid}
+	dataShards, parityShards := erasure_coding.DataShardsCount, erasure_coding.ParityShardsCount
+	if c.Ratio != nil {
+		if d, p := c.Ratio(collection); d > 0 && p > 0 {
+			dataShards, parityShards = d, p
+		}
+	}
+
+	racks := buildRacks(t.nodes)
+	if len(racks) == 0 {
+		return nil, fmt.Errorf("no racks available for EC placement")
+	}
+	rackKeys := sortedKeys(racks)
+
+	// Disk-type eligibility (Require filters; Any/Prefer admit all) and the soft
+	// type preference applied in scoring under Prefer.
+	typeEligible := func(d *disk) bool {
+		if c.DiskTypePolicy == DiskTypeRequire {
+			return diskTypeEqual(d.diskType, c.DiskType)
+		}
+		return true
+	}
+	var prefer func(*disk) bool
+	if c.DiskTypePolicy == DiskTypePrefer {
+		prefer = func(d *disk) bool { return diskTypeEqual(d.diskType, c.DiskType) }
+	}
+
+	// Whole-plan retry over preferred-tag tiers; the first tier that places every
+	// shard wins. Reaching the no-tag tier means we spilled outside the tags.
+	tiers := tagTiers(c.PreferredTags)
+	var lastErr error
+	for _, tierTags := range tiers {
+		tt := tierTags
+		eligible := func(d *disk) bool {
+			return typeEligible(d) && (len(tt) == 0 || diskHasAnyTag(d, tt))
+		}
+		res, err := t.tryPlace(vk, need, dataShards, parityShards, racks, rackKeys, mode, c.ReplicaPlacement, eligible, prefer)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if len(c.PreferredTags) > 0 && len(tierTags) == 0 {
+			res.SpilledOutsidePreferredTags = true
+		}
+		return res, nil
+	}
+	return nil, lastErr
+}
+
+// tagTiers returns the eligibility tag-sets in increasing breadth, ending with an
+// empty set ("any disk"). Empty preferredTags yields a single any-disk tier.
+func tagTiers(preferredTags []string) [][]string {
+	if len(preferredTags) == 0 {
+		return [][]string{nil}
+	}
+	tiers := make([][]string, 0, len(preferredTags)+1)
+	for k := range preferredTags {
+		tiers = append(tiers, append([]string(nil), preferredTags[:k+1]...))
+	}
+	return append(tiers, nil)
+}
+
+// tryPlace runs one whole-plan placement attempt restricted to disks satisfying
+// `eligible`, with `prefer` (may be nil) ranking soft-preferred disks first. It
+// journals reservations and rolls them all back if any shard cannot be placed, so
+// a failed tier leaves the snapshot unchanged for the next attempt.
+func (t *Topology) tryPlace(vk volKey, need []int, dataShards, parityShards int, racks map[string]*rack, rackKeys []string, mode PlacementMode, rp *super_block.ReplicaPlacement, eligible func(*disk) bool, prefer func(*disk) bool) (*PlaceResult, error) {
+	result := &PlaceResult{Destinations: make(map[int]Destination, len(need))}
+
+	// Per-type shard ids per rack (even caps), total shard count per rack
+	// (DiffRackCount), and the racks bearing each type (anti-affinity) — all seeded
+	// from the volume's existing shards.
+	shardsPerRack := map[bool]map[string][]int{true: {}, false: {}}
+	rackShardCount := map[string]int{}
+	bearing := map[bool]map[string]bool{true: {}, false: {}}
+	for _, n := range t.nodes {
+		info, ok := n.shards[vk]
+		if !ok {
+			continue
+		}
+		for sid := range info.shardBits.All() {
+			s := int(sid)
+			isData := s < dataShards
+			shardsPerRack[isData][n.rack] = append(shardsPerRack[isData][n.rack], s)
+			rackShardCount[n.rack]++
+			bearing[isData][n.rack] = true
+		}
+	}
+
+	// Even per-rack caps divide by racks that actually have an eligible free disk,
+	// not all racks (the snapshot keeps every disk type/tag), so a valid tiered
+	// cluster — e.g. SSDs in only 2 of 4 racks — is not capped impossibly low.
+	numEligibleRacks := 0
+	for _, rk := range rackKeys {
+		if rackHasFreeDisk(racks[rk], eligible) {
+			numEligibleRacks++
+		}
+	}
+	if numEligibleRacks < 1 {
+		numEligibleRacks = 1
+	}
+
+	attempts := strictAttempts
+	if mode == PlaceDurabilityFirst {
+		attempts = durabilityAttempts
+	}
+
+	var journal []placedEntry
+	relaxedSeen := map[string]bool{}
+	spilledType := false
+
+	placeShard := func(sid int, isData bool) bool {
+		typeTotal := dataShards
+		if !isData {
+			typeTotal = parityShards
+		}
+		for _, rl := range attempts {
+			node, diskID, spilled, ok := chooseShardDest(vk, sid, isData, dataShards, typeTotal, numEligibleRacks, parityShards, racks, rackKeys, rp, eligible, prefer, shardsPerRack[isData], rackShardCount, bearing, rl)
+			if !ok {
+				continue
+			}
+			reserveShard(node, vk, sid, diskID)
+			node.freeSlots--
+			racks[node.rack].freeSlots--
+			shardsPerRack[isData][node.rack] = append(shardsPerRack[isData][node.rack], sid)
+			rackShardCount[node.rack]++
+			bearing[isData][node.rack] = true
+			journal = append(journal, placedEntry{node: node, sid: sid, rackKey: node.rack})
+			result.Destinations[sid] = Destination{
+				Node:       node.id,
+				DiskID:     diskID,
+				DataCenter: node.dc,
+				Rack:       strings.TrimPrefix(node.rack, node.dc+":"),
+			}
+			if spilled {
+				spilledType = true
+			}
+			for _, name := range rl.relaxedNames() {
+				relaxedSeen[name] = true
+			}
+			return true
+		}
+		return false
+	}
+
+	// Data shards first, then parity, so parity can avoid data-bearing racks.
+	for _, isData := range []bool{true, false} {
+		for _, sid := range shardsOfType(need, isData, dataShards) {
+			if placeShard(sid, isData) {
+				continue
+			}
+			for _, e := range journal {
+				releaseShard(e.node, vk, e.sid)
+				e.node.freeSlots++
+				racks[e.rackKey].freeSlots++
+			}
+			return nil, fmt.Errorf("cannot place EC shard %d of volume %d (collection %q)", sid, vk.vid, vk.collection)
+		}
+	}
+
+	result.SpilledToOtherDiskType = spilledType
+	for name := range relaxedSeen {
+		result.Relaxed = append(result.Relaxed, name)
+	}
+	sort.Strings(result.Relaxed)
+	return result, nil
+}
+
+// chooseShardDest selects a (node, disk) for one shard at the given relaxation
+// level: pick a rack (even per-type cap + ReplicaPlacement caps + two-pass
+// anti-affinity to the opposite type), then the least-loaded eligible node, then
+// the best eligible disk. The third return reports whether the disk spilled off
+// the soft-preferred type. ok=false when no rack/node/disk fits.
+func chooseShardDest(vk volKey, sid int, isData bool, dataShards, typeTotal, numEligibleRacks, maxPerDisk int, racks map[string]*rack, rackKeys []string, rp *super_block.ReplicaPlacement, eligible func(*disk) bool, prefer func(*disk) bool, shardsPerRackType map[string][]int, rackShardCount map[string]int, bearing map[bool]map[string]bool, rl relaxation) (*Node, uint32, bool, bool) {
+	maxPerRack := numEligibleRacks*typeTotal + 1 // effectively unlimited when caps are relaxed
+	if rl.caps {
+		if maxPerRack = ceilDivide(typeTotal, numEligibleRacks); maxPerRack < 1 {
+			maxPerRack = 1
+		}
+	}
+
+	var anti map[string]bool
+	if rl.antiAffinity {
+		anti = bearing[!isData] // racks already holding the opposite shard type
+	}
+
+	if !rl.rp {
+		rp = nil
+	}
+	// A rack is eligible only if it is under the per-rack shard cap (DiffRackCount),
+	// enforced only when set (and relaxed with rp).
+	withinLimit := func(r string) bool {
+		if rp == nil {
+			return true
+		}
+		if rp.DiffRackCount > 0 && rackShardCount[r] >= rp.DiffRackCount {
+			return false
+		}
+		return true
+	}
+
+	destRack, ok := pickTarget(rackKeys, shardsPerRackType, maxPerRack, anti,
+		func(r string) bool { return racks[r].freeSlots > 0 && rackHasFreeDisk(racks[r], eligible) },
+		withinLimit)
+	if !ok {
+		return nil, 0, false, false
+	}
+	node := pickNodeInRackEligible(racks[destRack], vk, rp, eligible)
+	if node == nil {
+		return nil, 0, false, false
+	}
+	diskID, ok, spilled := pickBestDiskEligible(node, vk, eligible, prefer, sid, dataShards, maxPerDisk)
+	if !ok {
+		return nil, 0, false, false
+	}
+	return node, diskID, spilled, true
+}
+
+// nodeHasFreeDisk reports whether the node has a free disk satisfying eligible.
+func nodeHasFreeDisk(n *Node, eligible func(*disk) bool) bool {
+	for _, d := range n.disks {
+		if d.freeSlots > 0 && eligible(d) {
+			return true
+		}
+	}
+	return false
+}
+
+// rackHasFreeDisk reports whether any node in the rack has a free eligible disk.
+func rackHasFreeDisk(r *rack, eligible func(*disk) bool) bool {
+	for _, n := range r.nodes {
+		if n.freeSlots > 0 && nodeHasFreeDisk(n, eligible) {
+			return true
+		}
+	}
+	return false
+}
+
+// pickNodeInRackEligible is pickNodeInRack restricted to nodes that have a free
+// eligible disk. FromActiveTopology keeps all disk types/tags in the snapshot, so
+// without this a node with free volume slots but no eligible disk could be chosen.
+//
+// Among eligible nodes it ranks by fewest shards of the volume per machine, then per
+// node, with free capacity breaking ties. The free-capacity tie-break (not sorted id)
+// keeps the lowest-id machine from winning every volume's first shard against the
+// shared encode snapshot and piling up load.
+func pickNodeInRackEligible(r *rack, vk volKey, rp *super_block.ReplicaPlacement, eligible func(*disk) bool) *Node {
+	machineShards := countShardsByHost(vk, r.nodes)
+	machineFree := freeSlotsByHost(r.nodes)
+	var best *Node
+	var bestMCount, bestMFree, bestNCount, bestNFree int
+	for _, id := range sortedNodeKeys(r.nodes) {
+		node := r.nodes[id]
+		if node.freeSlots <= 0 {
+			continue
+		}
+		if !nodeHasFreeDisk(node, eligible) {
+			continue
+		}
+		count := volumeShardCount(node, vk)
+		if rp != nil && rp.SameRackCount > 0 && count >= rp.SameRackCount {
+			continue
+		}
+		mCount, mFree := machineShards[node.host], machineFree[node.host]
+		better := false
+		switch {
+		case best == nil:
+			better = true
+		case mCount != bestMCount:
+			better = mCount < bestMCount
+		case mFree != bestMFree:
+			better = mFree > bestMFree
+		case count != bestNCount:
+			better = count < bestNCount
+		default:
+			better = node.freeSlots > bestNFree
+		}
+		if better {
+			best, bestMCount, bestMFree, bestNCount, bestNFree = node, mCount, mFree, count, node.freeSlots
+		}
+	}
+	return best
+}
+
+// pickBestDiskEligible chooses the best eligible disk on a node, ranking
+// soft-preferred disks (prefer != nil && prefer(d)) ahead of others so disk-type
+// Prefer uses the preferred type when available but spills otherwise. Returns the
+// disk id, whether one was found, and whether the chosen disk spilled off the
+// preferred type.
+func pickBestDiskEligible(node *Node, vk volKey, eligible func(*disk) bool, prefer func(*disk) bool, shardID, dataShardCount, maxPerDisk int) (uint32, bool, bool) {
+	isDataShard := dataShardCount > 0 && shardID < dataShardCount
+	info := node.shards[vk]
+	var bestDiskID uint32
+	bestScore := -1
+	bestPreferred := false
+	for _, diskID := range sortedDiskKeys(node.disks) {
+		d := node.disks[diskID]
+		if !eligible(d) || d.freeSlots <= 0 {
+			continue
+		}
+		existingShards := 0
+		hasData := false
+		hasParity := false
+		if info != nil {
+			bits := info.diskShardBits[diskID]
+			existingShards = bits.Count()
+			if dataShardCount > 0 {
+				for sid := range bits.All() {
+					if int(sid) < dataShardCount {
+						hasData = true
+					} else {
+						hasParity = true
+					}
+				}
+			}
+		}
+		// Durability: never put more than maxPerDisk (parityShards) shards of this
+		// volume on one disk, or losing that disk would lose more than EC can
+		// recover. Hard cap, enforced even under durability-first relaxation.
+		if maxPerDisk > 0 && existingShards >= maxPerDisk {
+			continue
+		}
+		score := d.shardCount*10 + existingShards*100
+		if dataShardCount > 0 {
+			if isDataShard && hasParity {
+				score += 1000
+			} else if !isDataShard && hasData {
+				score += 1000
+			}
+		}
+		preferred := prefer == nil || prefer(d)
+		if !preferred {
+			score += 100000 // strongly deprioritize spilling to a non-preferred type
+		}
+		if bestScore == -1 || score < bestScore {
+			bestScore = score
+			bestDiskID = diskID
+			bestPreferred = preferred
+		}
+	}
+	if bestScore == -1 {
+		return 0, false, false
+	}
+	return bestDiskID, true, prefer != nil && !bestPreferred
+}
+
+// clearShardAccounting removes one shard copy of a volume from the snapshot's
+// per-domain accounting (the volume's shard bits) WITHOUT crediting disk capacity.
+// It clears only the given physical disk's bit, then recomputes the node-level
+// union from the remaining disk bits, so a kept copy of the same shard on another
+// disk of the same node still counts toward caps / ReplicaPlacement / anti-affinity.
+//
+// Repair uses this to drop the duplicate/mismatched copies it plans to delete
+// before placing missing shards, so those copies do not inflate placement
+// accounting. Capacity is deliberately NOT credited: the deletes run only after
+// the rebuilt shards are distributed, so the slots are not free at plan time. This
+// is distinct from releaseShard, which credits freeSlots and clears the union.
+func clearShardAccounting(node *Node, vk volKey, shardID int, diskID uint32) {
+	info, ok := node.shards[vk]
+	if !ok {
+		return
+	}
+	sid := erasure_coding.ShardId(shardID)
+	if bits, ok := info.diskShardBits[diskID]; ok {
+		info.diskShardBits[diskID] = bits.Clear(sid)
+	}
+	var union erasure_coding.ShardBits
+	for _, b := range info.diskShardBits {
+		union |= b
+	}
+	info.shardBits = union
+}
+
+// ClearShardAccounting drops one shard copy of a volume from placement accounting
+// without crediting capacity (see clearShardAccounting). Repair calls it for each
+// copy it plans to delete before placing missing shards, so those copies do not
+// inflate caps/RP/anti-affinity. No-op for an unknown node.
+func (t *Topology) ClearShardAccounting(nodeID, collection string, vid uint32, shardID int, diskID uint32) {
+	n, ok := t.nodes[nodeID]
+	if !ok {
+		return
+	}
+	clearShardAccounting(n, volKey{collection: collection, vid: vid}, shardID, diskID)
+}
+
+// ReleaseVolumeShards removes every shard of a volume from the snapshot and
+// credits the freed disk capacity. A greenfield encode calls this so any stale
+// EC shards left by a prior failed attempt (which the encode task deletes before
+// distributing the new shards) neither occupy capacity nor skew anti-affinity /
+// per-disk caps during planning. Unlike repair's ClearShardAccounting, it credits
+// freeSlots because the deletes run before the new writes.
+func (t *Topology) ReleaseVolumeShards(collection string, vid uint32) {
+	vk := volKey{collection: collection, vid: vid}
+	for _, n := range t.nodes {
+		info, ok := n.shards[vk]
+		if !ok {
+			continue
+		}
+		// freed is the total disk-slots the volume occupies on this node (a shard may
+		// sit on more than one disk). releaseShard credits each disk's freeSlots;
+		// credit the node's freeSlots by the same total, since rack capacity is summed
+		// from node freeSlots (buildRacks) and node freeSlots gates node eligibility.
+		freed := 0
+		for _, bits := range info.diskShardBits {
+			freed += bits.Count()
+		}
+		sids := make([]int, 0, info.shardBits.Count())
+		for sid := range info.shardBits.All() {
+			sids = append(sids, int(sid))
+		}
+		for _, sid := range sids {
+			releaseShard(n, vk, sid)
+		}
+		n.freeSlots += freed
+		delete(n.shards, vk)
+	}
+}
+
+// shardsOfType returns the sorted subset of need that are data shards (id <
+// dataShards) when isData, else the parity subset.
+func shardsOfType(need []int, isData bool, dataShards int) []int {
+	var out []int
+	for _, s := range need {
+		if (s < dataShards) == isData {
+			out = append(out, s)
+		}
+	}
+	sort.Ints(out)
+	return out
+}

weed/storage/erasure_coding/ecbalancer/place_test.go

@@ -0,0 +1,502 @@
+package ecbalancer
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+	"github.com/seaweedfs/seaweedfs/weed/storage/super_block"
+)
+
+// buildPlaceTopo makes a topology of racks x nodesPerRack, each node one disk with
+// perDiskFree free EC shard slots.
+func buildPlaceTopo(racks, nodesPerRack, perDiskFree int) *Topology {
+	topo := NewTopology()
+	for r := 0; r < racks; r++ {
+		rackKey := fmt.Sprintf("dc1:rack%d", r)
+		for n := 0; n < nodesPerRack; n++ {
+			id := fmt.Sprintf("10.0.%d.%d:8080", r, n)
+			node := topo.AddNode(id, "dc1", rackKey, perDiskFree)
+			node.AddDisk(0, "", perDiskFree, 0)
+		}
+	}
+	return topo
+}
+
+func allShards() []int {
+	out := make([]int, erasure_coding.TotalShardsCount)
+	for i := range out {
+		out[i] = i
+	}
+	return out
+}
+
+// TestPlaceStrictSpreadAndCaps places a fresh 10+4 volume and checks every shard
+// lands on a distinct node and no rack exceeds the even per-type cap.
+func TestPlaceStrictSpreadAndCaps(t *testing.T) {
+	const racks = 4
+	topo := buildPlaceTopo(racks, 4, 50)
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d shards, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+
+	usedNodes := map[string]bool{}
+	dataPerRack := map[string]int{}
+	parityPerRack := map[string]int{}
+	for sid, d := range res.Destinations {
+		if usedNodes[d.Node] {
+			t.Errorf("node %s reused for shard %d (expected distinct nodes with ample capacity)", d.Node, sid)
+		}
+		usedNodes[d.Node] = true
+		if sid < erasure_coding.DataShardsCount {
+			dataPerRack[d.Rack]++
+		} else {
+			parityPerRack[d.Rack]++
+		}
+	}
+	dataCap := ceilDivide(erasure_coding.DataShardsCount, racks)
+	parityCap := ceilDivide(erasure_coding.ParityShardsCount, racks)
+	for rk, n := range dataPerRack {
+		if n > dataCap {
+			t.Errorf("rack %s holds %d data shards, cap %d", rk, n, dataCap)
+		}
+	}
+	for rk, n := range parityPerRack {
+		if n > parityCap {
+			t.Errorf("rack %s holds %d parity shards, cap %d", rk, n, parityCap)
+		}
+	}
+}
+
+// TestPlaceDistributesEvenlyAcrossManyVolumes: placing many volumes against the shared
+// encode snapshot must not pile shards onto the sorted-first machine.
+func TestPlaceDistributesEvenlyAcrossManyVolumes(t *testing.T) {
+	topo := NewTopology()
+	hosts := []string{"10.0.0.1", "10.0.0.2", "10.0.0.3", "10.0.0.4", "10.0.0.5", "10.0.0.6"}
+	for _, h := range hosts {
+		for _, port := range []string{":8080", ":8081"} {
+			n := topo.AddNode(h+port, "dc1", "dc1:rack1", 1000)
+			n.SetHost(h)
+			n.AddDisk(0, "", 1000, 0)
+		}
+	}
+
+	const volumes = 120
+	for v := 0; v < volumes; v++ {
+		if _, err := topo.Place(uint32(v), "c1", allShards(), Constraints{}, PlaceDurabilityFirst); err != nil {
+			t.Fatalf("Place volume %d: %v", v, err)
+		}
+	}
+
+	perMachine := map[string]int{}
+	for _, n := range topo.nodes {
+		for _, d := range n.disks {
+			perMachine[n.host] += d.shardCount
+		}
+	}
+	min, max := 1<<30, 0
+	for _, c := range perMachine {
+		if c < min {
+			min = c
+		}
+		if c > max {
+			max = c
+		}
+	}
+	// Even distribution is 120*14/6 = 280 shards/machine. Catch a lopsided pileup
+	// (the production symptom was the first machine at ~1.7x the rest).
+	if float64(max) > 1.25*float64(min) {
+		t.Errorf("EC shards piled unevenly across machines: min=%d max=%d %v", min, max, perMachine)
+	}
+}
+
+// TestPlaceSpreadsAcrossMachines: one rack runs two physical machines (each with
+// four volume servers). Placing a 10+4 volume must spread its shards across both
+// machines so no single machine holds more than ceil(14/2)=7, otherwise losing one
+// box would take out more shards than EC can recover even though they look spread
+// across distinct nodes.
+func TestPlaceSpreadsAcrossMachines(t *testing.T) {
+	topo := NewTopology()
+	host := map[string]string{}
+	add := func(id, h string) {
+		n := topo.AddNode(id, "dc1", "dc1:rack0", 50)
+		n.SetHost(h)
+		n.AddDisk(0, "", 50, 0)
+		host[id] = h
+	}
+	for i := 0; i < 4; i++ {
+		add(fmt.Sprintf("a%d", i), "10.0.0.1")
+		add(fmt.Sprintf("b%d", i), "10.0.0.2")
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place: %v", err)
+	}
+	perMachine := map[string]int{}
+	for _, d := range res.Destinations {
+		perMachine[host[d.Node]]++
+	}
+	if len(perMachine) < 2 {
+		t.Fatalf("shards not spread across machines: %v", perMachine)
+	}
+	maxPerMachine := ceilDivide(erasure_coding.TotalShardsCount, 2)
+	for h, c := range perMachine {
+		if c > maxPerMachine {
+			t.Errorf("machine %s holds %d shards, want <=%d (ceil(14/2))", h, c, maxPerMachine)
+		}
+	}
+}
+
+// TestPlaceStrictFailsAndRollsBack: a single tiny disk cannot hold 14 shards, so
+// strict Place fails and leaves the snapshot untouched.
+func TestPlaceStrictFailsAndRollsBack(t *testing.T) {
+	topo := buildPlaceTopo(1, 1, 2) // one node, room for 2 shards
+	node := topo.nodes["10.0.0.0:8080"]
+	freeBefore := node.freeSlots
+	diskFreeBefore := node.disks[0].freeSlots
+
+	_, err := topo.Place(1, "c1", allShards(), Constraints{}, PlaceStrict)
+	if err == nil {
+		t.Fatal("expected Place to fail on insufficient capacity")
+	}
+	if info, ok := node.shards[volKey{collection: "c1", vid: 1}]; ok && info.shardBits.Count() != 0 {
+		t.Errorf("volume shard bits left on node after failed strict Place (rollback incomplete): %b", info.shardBits)
+	}
+	if node.freeSlots != freeBefore {
+		t.Errorf("node freeSlots = %d after rollback, want %d", node.freeSlots, freeBefore)
+	}
+	if node.disks[0].freeSlots != diskFreeBefore {
+		t.Errorf("disk freeSlots = %d after rollback, want %d", node.disks[0].freeSlots, diskFreeBefore)
+	}
+}
+
+// TestPlaceDurabilityFirstRelaxesRP: a ReplicaPlacement rack limit too tight for
+// the shard count makes strict fail, while durability-first relaxes RP to place
+// everything and reports the relaxation.
+func TestPlaceDurabilityFirstRelaxesRP(t *testing.T) {
+	rp := &super_block.ReplicaPlacement{DiffRackCount: 3} // <=3 shards per rack
+	topo := buildPlaceTopo(2, 8, 50)                      // 2 racks: 2*3=6 < 14 under RP
+
+	if _, err := topo.Place(1, "c1", allShards(), Constraints{ReplicaPlacement: rp}, PlaceStrict); err == nil {
+		t.Fatal("strict Place should fail when RP rack limit cannot fit all shards")
+	}
+
+	topo = buildPlaceTopo(2, 8, 50)
+	res, err := topo.Place(1, "c1", allShards(), Constraints{ReplicaPlacement: rp}, PlaceDurabilityFirst)
+	if err != nil {
+		t.Fatalf("durability-first Place: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d shards, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+	relaxedRP := false
+	for _, r := range res.Relaxed {
+		if r == "replica-placement" {
+			relaxedRP = true
+		}
+	}
+	if !relaxedRP {
+		t.Errorf("expected replica-placement relaxation, got %v", res.Relaxed)
+	}
+}
+
+// TestPlaceSameRackCountIsDirectPerNodeCap: the 3rd ReplicaPlacement digit
+// (SameRackCount) caps shards per node directly (max == digit), matching the
+// per-rack DiffRackCount cap rather than allowing digit+1 per node.
+func TestPlaceSameRackCountIsDirectPerNodeCap(t *testing.T) {
+	rp := &super_block.ReplicaPlacement{SameRackCount: 2} // <=2 shards per node
+
+	// 5 single-node racks: 5 nodes * 2 = 10 < 14, so a strict 10+4 placement
+	// cannot satisfy the per-node cap and must fail. Under the old digit+1 reading
+	// the cap would be 3/node => 15 slots and this would have wrongly succeeded.
+	topo := buildPlaceTopo(5, 1, 50)
+	if _, err := topo.Place(1, "c1", allShards(), Constraints{ReplicaPlacement: rp}, PlaceStrict); err == nil {
+		t.Fatal("strict Place should fail: 5 nodes cannot hold 14 shards at <=2 per node")
+	}
+
+	// Durability-first relaxes the unsatisfiable per-node cap, still places every
+	// shard, and reports the relaxation so it isn't silently weakened.
+	topo = buildPlaceTopo(5, 1, 50)
+	res, err := topo.Place(1, "c1", allShards(), Constraints{ReplicaPlacement: rp}, PlaceDurabilityFirst)
+	if err != nil {
+		t.Fatalf("durability-first Place: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d shards, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+	relaxedRP := false
+	for _, r := range res.Relaxed {
+		if r == "replica-placement" {
+			relaxedRP = true
+		}
+	}
+	if !relaxedRP {
+		t.Errorf("expected replica-placement relaxation, got %v", res.Relaxed)
+	}
+}
+
+// TestPlaceDiskTypeHardFilter: with DiskType set, shards land only on disks of
+// that type, even though the snapshot also contains other-typed disks.
+func TestPlaceDiskTypeHardFilter(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 4; r++ {
+		rackKey := fmt.Sprintf("dc1:rack%d", r)
+		ssd := topo.AddNode(fmt.Sprintf("ssd-%d:8080", r), "dc1", rackKey, 50)
+		ssd.AddDisk(0, "ssd", 50, 0)
+		hdd := topo.AddNode(fmt.Sprintf("hdd-%d:8080", r), "dc1", rackKey, 50)
+		hdd.AddDisk(0, "hdd", 50, 0)
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{DiskType: "ssd", DiskTypePolicy: DiskTypeRequire}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place ssd: %v", err)
+	}
+	for sid, d := range res.Destinations {
+		node := topo.nodes[d.Node]
+		disk := node.disks[d.DiskID]
+		if disk == nil || disk.diskType != "ssd" {
+			t.Errorf("shard %d placed on non-ssd disk: node=%s diskID=%d", sid, d.Node, d.DiskID)
+		}
+	}
+}
+
+// TestPlaceDiskTypeUnavailableFails: a request for a disk type with no matching
+// disks fails rather than silently placing on the wrong tier.
+func TestPlaceDiskTypeUnavailableFails(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 4; r++ {
+		n := topo.AddNode(fmt.Sprintf("hdd-%d:8080", r), "dc1", fmt.Sprintf("dc1:rack%d", r), 50)
+		n.AddDisk(0, "hdd", 50, 0)
+	}
+	if _, err := topo.Place(1, "c1", allShards(), Constraints{DiskType: "ssd", DiskTypePolicy: DiskTypeRequire}, PlaceStrict); err == nil {
+		t.Fatal("expected Place to fail when no disks of the requested type exist")
+	}
+}
+
+// TestPlaceHDDRequestMatchesEmptyTypeDisks: a "hdd" request normalizes to
+// HardDriveType ("") and must land on the HDD disk (reported as ""), never the SSD
+// disk, even on nodes that have both.
+func TestPlaceHDDRequestMatchesEmptyTypeDisks(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 6; r++ {
+		n := topo.AddNode(fmt.Sprintf("n%d:8080", r), "dc1", fmt.Sprintf("dc1:rack%d", r), 100)
+		n.AddDisk(0, "", 50, 0)    // HDD (HardDriveType, reported as "")
+		n.AddDisk(1, "ssd", 50, 0) // SSD
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{DiskType: "hdd", DiskTypePolicy: DiskTypeRequire}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place hdd: %v", err)
+	}
+	for sid, d := range res.Destinations {
+		if d.DiskID != 0 { // disk 0 is the HDD disk on every node
+			t.Errorf("shard %d placed on disk %d (expected HDD disk 0) on node %s", sid, d.DiskID, d.Node)
+		}
+	}
+}
+
+// TestPlaceDurabilityCapRejectsSkewed: in a near-full cluster where only one disk
+// has spare room, Place must not pile more than parityShards shards onto it (losing
+// it would then lose more than EC can recover). It fails instead, so the caller
+// leaves the volume unencoded rather than minting an unrecoverable layout.
+func TestPlaceDurabilityCapRejectsSkewed(t *testing.T) {
+	topo := NewTopology()
+	// One spacious node plus four nearly-full ones, all in a single rack.
+	a := topo.AddNode("a:8080", "dc1", "dc1:rack0", 100)
+	a.AddDisk(0, "", 100, 0)
+	for i := 0; i < 4; i++ {
+		n := topo.AddNode(fmt.Sprintf("b%d:8080", i), "dc1", "dc1:rack0", 1)
+		n.AddDisk(0, "", 1, 0)
+	}
+
+	// 14 shards, parity 4: node a is capped at 4, the others hold 1 each -> at most
+	// 4+4=8 placeable without exceeding parityShards on a disk, so Place must fail.
+	// (Without the per-disk cap, a would greedily absorb 10 shards and "succeed".)
+	if _, err := topo.Place(1, "c1", allShards(), Constraints{}, PlaceDurabilityFirst); err == nil {
+		t.Fatal("expected Place to fail rather than pile >parityShards shards on one disk")
+	}
+}
+
+// TestReleaseVolumeShards: removes all of a volume's shards from the snapshot and
+// credits the freed capacity at BOTH disk and node level (rack capacity sums node
+// freeSlots), mirroring how FromActiveTopology accounts stale shards.
+func TestReleaseVolumeShards(t *testing.T) {
+	topo := NewTopology()
+	// Node total 20 = two disks of 10. Two stale shards occupy one slot each, so the
+	// snapshot would show disk0/disk1 at 9 and node at 18 (as FromActiveTopology does).
+	n := topo.AddNode("n0:8080", "dc1", "dc1:rack0", 20)
+	n.AddDisk(0, "", 10, 0)
+	n.AddDisk(1, "", 10, 0)
+	vk := volKey{collection: "c1", vid: 1}
+	n.AddShards(1, "c1", 0, erasure_coding.ShardBits(uint32(1)<<3))
+	n.AddShards(1, "c1", 1, erasure_coding.ShardBits(uint32(1)<<7))
+	n.disks[0].freeSlots = 9
+	n.disks[1].freeSlots = 9
+	n.freeSlots = 18
+
+	topo.ReleaseVolumeShards("c1", 1)
+
+	if _, ok := n.shards[vk]; ok {
+		t.Error("volume shards should be gone after ReleaseVolumeShards")
+	}
+	if n.disks[0].freeSlots != 10 || n.disks[1].freeSlots != 10 {
+		t.Errorf("disk freeSlots not restored: disk0=%d, disk1=%d (want 10, 10)", n.disks[0].freeSlots, n.disks[1].freeSlots)
+	}
+	if n.freeSlots != 20 {
+		t.Errorf("node freeSlots = %d, want 20 (must be credited at node level too)", n.freeSlots)
+	}
+}
+
+// TestClearShardAccounting: dropping one disk's copy of a shard preserves a kept
+// copy of the same shard on another disk of the same node, and credits no capacity.
+func TestClearShardAccounting(t *testing.T) {
+	topo := NewTopology()
+	n := topo.AddNode("n0:8080", "dc1", "dc1:rack0", 50)
+	n.AddDisk(0, "", 50, 0)
+	n.AddDisk(1, "", 50, 0)
+	vk := volKey{collection: "c1", vid: 1}
+	// Shard 3 lives on disk 0 (keep) and disk 1 (duplicate to delete).
+	n.AddShards(1, "c1", 0, erasure_coding.ShardBits(uint32(1)<<3))
+	n.AddShards(1, "c1", 1, erasure_coding.ShardBits(uint32(1)<<3))
+	if got := n.shards[vk].shardBits.Count(); got != 1 {
+		t.Fatalf("union count = %d, want 1", got)
+	}
+	freeBefore := n.disks[1].freeSlots
+
+	clearShardAccounting(n, vk, 3, 1)
+
+	if !n.shards[vk].shardBits.Has(erasure_coding.ShardId(3)) {
+		t.Error("kept copy of shard 3 (disk 0) lost from the node-level union")
+	}
+	if n.shards[vk].diskShardBits[1].Has(erasure_coding.ShardId(3)) {
+		t.Error("disk-1 copy of shard 3 was not cleared")
+	}
+	if n.disks[1].freeSlots != freeBefore {
+		t.Errorf("freeSlots changed %d -> %d; clearShardAccounting must not credit capacity", freeBefore, n.disks[1].freeSlots)
+	}
+}
+
+// TestPlaceDiskTypePreferSpills: DiskTypePrefer fills the preferred type first and
+// spills the remainder to other types, reporting SpilledToOtherDiskType. SSD is
+// scarce (one tiny SSD per node) so the volume must spill to HDD, but there are
+// enough disks to keep each within the parityShards durability cap.
+func TestPlaceDiskTypePreferSpills(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 8; r++ {
+		n := topo.AddNode(fmt.Sprintf("n%d:8080", r), "dc1", fmt.Sprintf("dc1:rack%d", r), 100)
+		n.AddDisk(0, "ssd", 1, 0) // tiny SSD: 1 shard
+		n.AddDisk(1, "", 50, 0)   // roomy HDD
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{DiskType: "ssd", DiskTypePolicy: DiskTypePrefer}, PlaceDurabilityFirst)
+	if err != nil {
+		t.Fatalf("Place: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+	ssd, hdd := 0, 0
+	for _, d := range res.Destinations {
+		if topo.nodes[d.Node].disks[d.DiskID].diskType == "ssd" {
+			ssd++
+		} else {
+			hdd++
+		}
+	}
+	if ssd == 0 || hdd == 0 {
+		t.Errorf("expected prefer-then-spill: some shards on SSD and some on HDD, got ssd=%d hdd=%d", ssd, hdd)
+	}
+	if !res.SpilledToOtherDiskType {
+		t.Error("expected SpilledToOtherDiskType when SSD cannot hold every shard")
+	}
+}
+
+// TestPlacePreferredTagsUseTaggedDisks: when tagged disks can hold the whole plan,
+// every shard lands on a tagged disk and no spill is reported.
+func TestPlacePreferredTagsUseTaggedDisks(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 4; r++ {
+		rackKey := fmt.Sprintf("dc1:rack%d", r)
+		fast := topo.AddNode(fmt.Sprintf("fast-%d:8080", r), "dc1", rackKey, 50)
+		fast.AddDisk(0, "", 50, 0)
+		fast.AddDiskTags(0, []string{"fast"})
+		topo.AddNode(fmt.Sprintf("slow-%d:8080", r), "dc1", rackKey, 50).AddDisk(0, "", 50, 0)
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{PreferredTags: []string{"fast"}}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place: %v", err)
+	}
+	for sid, d := range res.Destinations {
+		if !diskHasAnyTag(topo.nodes[d.Node].disks[d.DiskID], []string{"fast"}) {
+			t.Errorf("shard %d placed on an untagged disk (node %s)", sid, d.Node)
+		}
+	}
+	if res.SpilledOutsidePreferredTags {
+		t.Error("did not expect tag spill when tagged disks suffice")
+	}
+}
+
+// TestPlacePreferredTagsSpillWhenInsufficient: when the tagged tier cannot hold the
+// whole plan, Place falls back to all disks and reports SpilledOutsidePreferredTags.
+func TestPlacePreferredTagsSpillWhenInsufficient(t *testing.T) {
+	topo := NewTopology()
+	for r := 0; r < 4; r++ {
+		n := topo.AddNode(fmt.Sprintf("n-%d:8080", r), "dc1", fmt.Sprintf("dc1:rack%d", r), 50)
+		if r == 0 {
+			n.AddDisk(0, "", 5, 0) // the only tagged disk, too small for 14 shards
+			n.AddDiskTags(0, []string{"fast"})
+		} else {
+			n.AddDisk(0, "", 50, 0)
+		}
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{PreferredTags: []string{"fast"}}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+	if !res.SpilledOutsidePreferredTags {
+		t.Error("expected SpilledOutsidePreferredTags when the single fast disk cannot hold the plan")
+	}
+}
+
+// TestPlaceStrictCapsCountEligibleRacks: with DiskTypeRequire, the even per-rack
+// cap divides by racks that have a matching disk, not all racks, so SSDs in only
+// some racks still place successfully.
+func TestPlaceStrictCapsCountEligibleRacks(t *testing.T) {
+	topo := NewTopology()
+	// SSDs live in only 2 of 4 racks, with several SSD nodes per rack so 14 shards
+	// fit at <= parityShards per disk. The even per-rack cap must divide by the 2
+	// eligible racks (ceil(10/2)=5 data/rack), not all 4 (ceil(10/4)=3 -> infeasible).
+	for r := 0; r < 4; r++ {
+		rackKey := fmt.Sprintf("dc1:rack%d", r)
+		topo.AddNode(fmt.Sprintf("hdd-%d:8080", r), "dc1", rackKey, 50).AddDisk(0, "", 50, 0)
+		if r < 2 {
+			for n := 0; n < 4; n++ {
+				topo.AddNode(fmt.Sprintf("ssd-%d-%d:8080", r, n), "dc1", rackKey, 50).AddDisk(0, "ssd", 50, 0)
+			}
+		}
+	}
+
+	res, err := topo.Place(1, "c1", allShards(), Constraints{DiskType: "ssd", DiskTypePolicy: DiskTypeRequire}, PlaceStrict)
+	if err != nil {
+		t.Fatalf("Place ssd in 2/4 racks: %v", err)
+	}
+	if len(res.Destinations) != erasure_coding.TotalShardsCount {
+		t.Fatalf("placed %d, want %d", len(res.Destinations), erasure_coding.TotalShardsCount)
+	}
+	for sid, d := range res.Destinations {
+		if disk := topo.nodes[d.Node].disks[d.DiskID]; disk == nil || disk.diskType != "ssd" {
+			t.Errorf("shard %d not on an SSD disk: node=%s disk=%d", sid, d.Node, d.DiskID)
+		}
+	}
+}

weed/storage/erasure_coding/ecbalancer/shard_ratio.go

@@ -0,0 +1,24 @@
+package ecbalancer
+
+import (
+	"github.com/seaweedfs/seaweedfs/weed/pb/master_pb"
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+)
+
+// shardDataShards returns the data-shard count of the volume an EC shard belongs
+// to, used to size the shard's disk footprint. OSS uses the standard ratio for
+// every volume; custom per-volume ratios are an enterprise feature, so the
+// enterprise build overrides this to read the per-shard ratio.
+func shardDataShards(eci *master_pb.VolumeEcShardInformationMessage) int {
+	return erasure_coding.DataShardsCount
+}
+
+// VolumeShardRatio returns the RAW per-volume (dataShards, parityShards) reported
+// on an EC shard's heartbeat, with 0 meaning "not reported". Custom per-volume
+// ratios are an enterprise feature and the OSS proto has no data_shards/parity_shards
+// fields, so this returns 0, 0 and the balancer falls back to the collection ratio
+// (the standard scheme). The enterprise build overrides this to read the per-shard
+// ratio so a mixed-ratio collection is spread by each volume's own data/parity split.
+func VolumeShardRatio(eci *master_pb.VolumeEcShardInformationMessage) (dataShards, parityShards int) {
+	return 0, 0
+}

weed/storage/erasure_coding/ecbalancer/snapshot.go

@@ -0,0 +1,132 @@
+package ecbalancer
+
+import (
+	"github.com/seaweedfs/seaweedfs/weed/admin/topology"
+	"github.com/seaweedfs/seaweedfs/weed/pb"
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+	"github.com/seaweedfs/seaweedfs/weed/topology/balancer"
+)
+
+// diskTooFull reports whether a disk's physical filesystem is at/above the
+// balancing high-water mark, making it ineligible as an EC-shard target even
+// when slot math says it has room. Statfs free bytes already include EC shard
+// files. No-opinion when the disk reports no bytes (slot-only fallback).
+func diskTooFull(d *topology.DiskInfo) bool {
+	return balancer.DiskTooFullAfter(d.DiskInfo.DiskTotalBytes, d.DiskInfo.DiskFreeBytes, 0, balancer.DefaultMaxDiskUsagePercent)
+}
+
+// FromActiveTopology builds a Topology snapshot from the cluster's ActiveTopology
+// using the reservation-aware effective-capacity view that EC encode and repair
+// rely on. It collects ALL EC-eligible disks with no hard disk-type filter;
+// disk-type preference is applied later by callers (Place). Per-disk free EC shard
+// slots come from GetEffectiveAvailableEcShardSlots (shard-granular, so in-flight
+// task reservations that are not whole-volume multiples are not lost) minus the EC
+// shards already persisted on the disk. Rack keys are composite "dc:rack".
+//
+// dataShards is the target collection's data-shard count, used to size free EC
+// shard slots correctly for custom ratios (a 4+2 volume's shards are larger, so
+// fewer fit per volume slot). Pass <= 0 for the default scheme. Because of this,
+// the snapshot is ratio-specific; build one per collection ratio being placed.
+//
+// This is the encode/repair-side constructor; balance keeps its own raw-topology
+// builder (buildBalancerTopology) until the snapshot sources are reconciled.
+func FromActiveTopology(at *topology.ActiveTopology, dataShards int) *Topology {
+	topo := NewTopology()
+	if at == nil {
+		return topo
+	}
+
+	disks := at.GetDisksWithEffectiveCapacity(topology.TaskTypeErasureCoding, "", 0)
+
+	// Accumulate node-level free slots and group the node's disks together.
+	nodeFree := make(map[string]int)
+	nodeDC := make(map[string]string)
+	nodeRack := make(map[string]string)
+	nodeAddr := make(map[string]string)
+	byNode := make(map[string][]*topology.DiskInfo)
+	for _, d := range disks {
+		if d == nil || d.DiskInfo == nil {
+			continue
+		}
+		if free := perDiskFreeECSlots(at, d, dataShards); free > 0 && !diskTooFull(d) {
+			nodeFree[d.NodeID] += free
+		}
+		nodeDC[d.NodeID] = d.DataCenter
+		nodeRack[d.NodeID] = d.DataCenter + ":" + d.Rack
+		nodeAddr[d.NodeID] = d.Address
+		byNode[d.NodeID] = append(byNode[d.NodeID], d)
+	}
+
+	for nodeID, ds := range byNode {
+		node := topo.AddNode(nodeID, nodeDC[nodeID], nodeRack[nodeID], nodeFree[nodeID])
+		// Group by physical machine: derive the host from the address (NodeID may be
+		// an opaque id), falling back to the id when no address is recorded.
+		addr := nodeAddr[nodeID]
+		if addr == "" {
+			addr = nodeID
+		}
+		node.SetHost(pb.ServerAddress(addr).ToHost())
+		for _, d := range ds {
+			free := perDiskFreeECSlots(at, d, dataShards)
+			if free < 0 || diskTooFull(d) {
+				free = 0
+			}
+			node.AddDisk(d.DiskID, d.DiskType, free, ecShardCountOnDisk(d))
+			node.AddDiskTags(d.DiskID, d.DiskInfo.Tags)
+			for _, eci := range d.DiskInfo.EcShardInfos {
+				if eci.DiskId != d.DiskID {
+					continue
+				}
+				node.AddShards(eci.Id, eci.Collection, d.DiskID, erasure_coding.ShardBits(eci.EcIndexBits))
+			}
+		}
+	}
+
+	return topo
+}
+
+// perDiskFreeECSlots returns the disk's free EC shard slots for a volume with
+// dataShards data shards: the topology's shard-granular effective availability
+// (sized by the target ratio) minus the EC shards already on the disk, also
+// expressed in the target ratio's shard slots so mixed-ratio disks are charged by
+// size rather than raw count.
+func perDiskFreeECSlots(at *topology.ActiveTopology, d *topology.DiskInfo, dataShards int) int {
+	return at.GetEffectiveAvailableEcShardSlots(d.NodeID, d.DiskID, dataShards) - ecShardSlotsOnDisk(d, dataShards)
+}
+
+// ecShardCountOnDisk counts the EC shards physically on this disk (matching
+// eci.DiskId), across all volumes. Used as a per-disk load metric for scoring.
+func ecShardCountOnDisk(d *topology.DiskInfo) int {
+	count := 0
+	for _, eci := range d.DiskInfo.EcShardInfos {
+		if eci.DiskId == d.DiskID {
+			count += erasure_coding.GetShardCount(eci)
+		}
+	}
+	return count
+}
+
+// ecShardSlotsOnDisk returns the EC shards already on the disk expressed in the
+// TARGET collection's shard slots. A shard of a collection with d data shards
+// occupies ~1/d of a volume, i.e. targetDataShards/d target slots, so a 2+1 shard
+// counted against a 10+4 snapshot consumes ~5 slots, not 1.
+func ecShardSlotsOnDisk(d *topology.DiskInfo, targetDataShards int) int {
+	if targetDataShards <= 0 {
+		targetDataShards = erasure_coding.DataShardsCount
+	}
+	total := 0
+	for _, eci := range d.DiskInfo.EcShardInfos {
+		if eci.DiskId != d.DiskID {
+			continue
+		}
+		ds := shardDataShards(eci)
+		if ds <= 0 {
+			ds = erasure_coding.DataShardsCount
+		}
+		// Round up so an existing shard always consumes at least its fractional
+		// footprint; flooring lets a low-data-shard volume (targetDataShards < ds)
+		// count as zero target slots and overstate the disk's free capacity.
+		total += (erasure_coding.GetShardCount(eci)*targetDataShards + ds - 1) / ds
+	}
+	return total
+}

weed/storage/erasure_coding/ecbalancer/snapshot_test.go

@@ -0,0 +1,226 @@
+package ecbalancer
+
+import (
+	"testing"
+
+	"github.com/seaweedfs/seaweedfs/weed/admin/topology"
+	"github.com/seaweedfs/seaweedfs/weed/pb/master_pb"
+	"github.com/seaweedfs/seaweedfs/weed/storage/erasure_coding"
+)
+
+// TestFromActiveTopology verifies the encode/repair-side snapshot constructor maps
+// nodes, per-disk EC shard counts, per-volume shard bits, and free slots from an
+// ActiveTopology. Shard accounting is asserted exactly; free slots are asserted to
+// be positive (their exact value depends on effective-capacity internals).
+func TestFromActiveTopology(t *testing.T) {
+	const vid uint32 = 7
+	at := topology.NewActiveTopology(10)
+
+	// Node A holds one EC shard (id 3) of volume 7 on disk 0; node B is empty.
+	nodeA := &master_pb.DataNodeInfo{
+		Id: "10.0.0.1:8080",
+		DiskInfos: map[string]*master_pb.DiskInfo{
+			"hdd": {
+				DiskId:         0,
+				MaxVolumeCount: 100,
+				VolumeCount:    1,
+				EcShardInfos: []*master_pb.VolumeEcShardInformationMessage{{
+					Id:          vid,
+					Collection:  "c1",
+					EcIndexBits: uint32(1) << 3,
+					DiskId:      0,
+				}},
+			},
+		},
+	}
+	nodeB := &master_pb.DataNodeInfo{
+		Id: "10.0.0.2:8080",
+		DiskInfos: map[string]*master_pb.DiskInfo{
+			"hdd": {DiskId: 0, MaxVolumeCount: 100, VolumeCount: 0},
+		},
+	}
+	if err := at.UpdateTopology(&master_pb.TopologyInfo{
+		DataCenterInfos: []*master_pb.DataCenterInfo{{
+			Id: "dc1",
+			RackInfos: []*master_pb.RackInfo{{
+				Id:            "rack1",
+				DataNodeInfos: []*master_pb.DataNodeInfo{nodeA, nodeB},
+			}},
+		}},
+	}); err != nil {
+		t.Fatalf("UpdateTopology: %v", err)
+	}
+
+	topo := FromActiveTopology(at, 0)
+
+	if got := len(topo.nodes); got != 2 {
+		t.Fatalf("node count = %d, want 2", got)
+	}
+
+	a := topo.nodes["10.0.0.1:8080"]
+	if a == nil {
+		t.Fatal("node A missing from snapshot")
+	}
+	if a.rack != "dc1:rack1" {
+		t.Errorf("node A rack = %q, want dc1:rack1", a.rack)
+	}
+	diskA := a.disks[0]
+	if diskA == nil {
+		t.Fatal("node A disk 0 missing")
+	}
+	if diskA.shardCount != 1 {
+		t.Errorf("node A disk 0 shardCount = %d, want 1", diskA.shardCount)
+	}
+	vs := a.shards[volKey{collection: "c1", vid: vid}]
+	if vs == nil {
+		t.Fatal("volume 7 shards not recorded on node A")
+	}
+	if !vs.shardBits.Has(erasure_coding.ShardId(3)) {
+		t.Errorf("node A volume 7 shardBits %b missing shard 3", vs.shardBits)
+	}
+	if vs.shardBits.Count() != 1 {
+		t.Errorf("node A volume 7 shard count = %d, want 1", vs.shardBits.Count())
+	}
+
+	b := topo.nodes["10.0.0.2:8080"]
+	if b == nil {
+		t.Fatal("node B missing from snapshot")
+	}
+	if b.rack != "dc1:rack1" {
+		t.Errorf("node B rack = %q, want dc1:rack1", b.rack)
+	}
+	if diskB := b.disks[0]; diskB == nil || diskB.shardCount != 0 {
+		t.Errorf("node B disk 0 shardCount = %v, want 0", diskB)
+	}
+	if len(b.shards) != 0 {
+		t.Errorf("node B should hold no volume shards, got %d", len(b.shards))
+	}
+
+	// Free slots should be positive on both near-empty disks.
+	if a.freeSlots <= 0 || b.freeSlots <= 0 {
+		t.Errorf("free slots not positive: A=%d B=%d", a.freeSlots, b.freeSlots)
+	}
+}
+
+// A physically near-full disk must contribute zero free EC slots to the snapshot,
+// even though its slot math (MaxVolumeCount - VolumeCount) says it has room, so
+// the planner never places shards onto it. Mirrors the volume-balance #10160 gate.
+func TestFromActiveTopologySkipsPhysicallyFullDisk(t *testing.T) {
+	const gb = uint64(1) << 30
+	at := topology.NewActiveTopology(10)
+
+	// Both disks look slot-empty; only their physical byte fullness differs.
+	full := &master_pb.DataNodeInfo{
+		Id: "10.0.0.1:8080",
+		DiskInfos: map[string]*master_pb.DiskInfo{
+			"hdd": {DiskId: 0, MaxVolumeCount: 100, VolumeCount: 0, DiskTotalBytes: 1000 * gb, DiskFreeBytes: 40 * gb}, // 96% used
+		},
+	}
+	empty := &master_pb.DataNodeInfo{
+		Id: "10.0.0.2:8080",
+		DiskInfos: map[string]*master_pb.DiskInfo{
+			"hdd": {DiskId: 0, MaxVolumeCount: 100, VolumeCount: 0, DiskTotalBytes: 1000 * gb, DiskFreeBytes: 900 * gb}, // 10% used
+		},
+	}
+	if err := at.UpdateTopology(&master_pb.TopologyInfo{
+		DataCenterInfos: []*master_pb.DataCenterInfo{{
+			Id:        "dc1",
+			RackInfos: []*master_pb.RackInfo{{Id: "rack1", DataNodeInfos: []*master_pb.DataNodeInfo{full, empty}}},
+		}},
+	}); err != nil {
+		t.Fatalf("UpdateTopology: %v", err)
+	}
+
+	topo := FromActiveTopology(at, 0)
+
+	fullNode := topo.nodes["10.0.0.1:8080"]
+	if fullNode == nil {
+		t.Fatal("full node missing")
+	}
+	if fullNode.freeSlots != 0 {
+		t.Errorf("physically full node freeSlots = %d, want 0", fullNode.freeSlots)
+	}
+	if d := fullNode.disks[0]; d == nil || d.freeSlots != 0 {
+		t.Errorf("physically full disk freeSlots = %v, want 0", d)
+	}
+
+	emptyNode := topo.nodes["10.0.0.2:8080"]
+	if emptyNode == nil || emptyNode.freeSlots <= 0 {
+		t.Errorf("physically empty node should keep free slots, got %v", emptyNode)
+	}
+}
+
+// TestFromActiveTopologyGroupsByAddressHost verifies the snapshot derives a node's
+// machine from its address, not its (possibly opaque) id: two volume servers with
+// distinct ids but the same host must land on one machine so EC placement spreads
+// shards across boxes even when explicit node ids are configured.
+func TestFromActiveTopologyGroupsByAddressHost(t *testing.T) {
+	at := topology.NewActiveTopology(10)
+	mk := func(id, addr string) *master_pb.DataNodeInfo {
+		return &master_pb.DataNodeInfo{
+			Id:        id,
+			Address:   addr,
+			DiskInfos: map[string]*master_pb.DiskInfo{"hdd": {DiskId: 0, MaxVolumeCount: 100, VolumeCount: 0}},
+		}
+	}
+	// vs-a and vs-b are two servers on the same physical host; vs-c is another box.
+	nodes := []*master_pb.DataNodeInfo{
+		mk("vs-a", "10.0.0.9:8080"),
+		mk("vs-b", "10.0.0.9:8081"),
+		mk("vs-c", "10.0.0.10:8080"),
+	}
+	if err := at.UpdateTopology(&master_pb.TopologyInfo{
+		DataCenterInfos: []*master_pb.DataCenterInfo{{
+			Id:        "dc1",
+			RackInfos: []*master_pb.RackInfo{{Id: "rack1", DataNodeInfos: nodes}},
+		}},
+	}); err != nil {
+		t.Fatalf("UpdateTopology: %v", err)
+	}
+
+	topo := FromActiveTopology(at, 0)
+	if topo.nodes["vs-a"].host != topo.nodes["vs-b"].host {
+		t.Errorf("vs-a host %q != vs-b host %q; same-machine servers not grouped",
+			topo.nodes["vs-a"].host, topo.nodes["vs-b"].host)
+	}
+	if topo.nodes["vs-a"].host == topo.nodes["vs-c"].host {
+		t.Errorf("vs-a and vs-c share host %q but are different machines", topo.nodes["vs-a"].host)
+	}
+	if got := topo.nodes["vs-a"].host; got != "10.0.0.9" {
+		t.Errorf("vs-a host = %q, want 10.0.0.9", got)
+	}
+}
+
+// TestEcShardSlotsOnDiskRoundsUp covers the mixed-ratio (targetDataShards <
+// existingDataShards) conversion: an existing shard's fractional footprint must
+// round up so it is never floored to zero, which would overstate free capacity.
+// OSS always uses the standard ratio at runtime, but ecShardSlotsOnDisk takes the
+// target data-shard count as a parameter, so the fractional path is exercised
+// directly here; the enterprise build reaches it with real per-volume ratios.
+func TestEcShardSlotsOnDiskRoundsUp(t *testing.T) {
+	// A single shard (id 3) of a standard 10-data-shard volume on disk 0.
+	disk := &topology.DiskInfo{
+		DiskID: 0,
+		DiskInfo: &master_pb.DiskInfo{
+			DiskId: 0,
+			EcShardInfos: []*master_pb.VolumeEcShardInformationMessage{{
+				Id:          7,
+				Collection:  "c1",
+				EcIndexBits: uint32(1) << 3,
+				DiskId:      0,
+			}},
+		},
+	}
+
+	// Against a 2-data-shard target the shard occupies 2/10 of a slot, which must
+	// round up to 1 rather than floor to 0.
+	if got := ecShardSlotsOnDisk(disk, 2); got != 1 {
+		t.Errorf("ecShardSlotsOnDisk(target=2) = %d, want 1 (rounded up from 0.2)", got)
+	}
+
+	// Identity case: target equals the existing data-shard count, so the shard
+	// consumes exactly its whole-number footprint.
+	if got := ecShardSlotsOnDisk(disk, erasure_coding.DataShardsCount); got != 1 {
+		t.Errorf("ecShardSlotsOnDisk(target=%d) = %d, want 1", erasure_coding.DataShardsCount, got)
+	}
+}