Document the dense-label requirement of the distributed pipeline

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

Author: constantinpape

MIGRATION_GUIDE.md

@@ -500,7 +500,11 @@ per-block subgraphs/features to zarr/N5/HDF5) is intentionally left to the
 caller, since I/O and block scheduling belong in Python.
 
 The primitives assume **globally consistent labels** (a segment has the same id
-in every block — as after a stitched distributed watershed). A block owns the
+in every block — as after a stitched distributed watershed). Labels must also
+be reasonably **dense**: the global graph allocates memory proportional to the
+largest node id (`from_unique_edges(number_of_nodes, ...)` builds a dense CSR
+over ids `0 .. number_of_nodes - 1`), so sparse or very large globally unique
+id ranges need a relabeling pass before building the graph. A block owns the
 pixel-pairs whose reference pixel lies in its inner (non-halo) box, so the
 caller reads each block with a halo (≥1 on the forward faces for the region
 graph / an edge map; ≥ `max |offset|` per side for affinities) and passes the

src/bioimage_cpp/graph/distributed.py

@@ -21,7 +21,10 @@
 
 2. **Merge the graph**: :func:`merge_edges` unions the per-block edges into the
    whole-volume edge set; build the global graph with
-   :meth:`bioimage_cpp.graph.UndirectedGraph.from_unique_edges`.
+   :meth:`bioimage_cpp.graph.UndirectedGraph.from_unique_edges`. Labels must be
+   globally consistent *and* reasonably dense: the graph allocates memory
+   proportional to the largest node id, so sparse or very large globally unique
+   id ranges need a relabeling pass first.
 
 3. **Merge the features**: fold each block's partial statistics onto the global
    edges with :func:`merge_block_edge_stats` (starting from