Document bulk construction

The formula behind from_ordset/from_orddict/from_ordered_list was never
written down, so record what it computes and why.

xb5_utils:bulk_construction_params/1 counts in base 4 because bulk
construction targets nodes of 3 keys and 4 children, not the maximum 4 and 5 -
the density the README argues for under "Key density". From that:

  - BatchSize - 1 is 4^(h+1) - 1, the size of a perfect subtree of 3-key,
    4-child nodes, handed to each fully loaded child.
  - BatchOffset is (4^(h+1) - 1) / 3, at once that subtree's node count and
    the smallest S reaching this level. The two coincide only because the
    target density is exactly 3.

Confirmed against structural_stats: sizes of 4^(h+1) - 1 give exactly 3.000
keys per node over (4^(h+1) - 1) / 3 nodes, and the worst cases are the
BatchOffsets themselves, where a level is forced and the root is left an
INTERNAL1.

Document the consuming half above xb5_sets_node:from_ordset_recur/5 - the
quotient picking each node's arity, INTERNAL1 staying root-only as deletion
also requires, and the tail split. The three-quarter cap in
from_ordset_right_children_sizes/2 is recorded as tuned rather than derived,
which is what it is. xb5_trees_node and xb5_bag_node point at both places
instead of repeating them.

Comments only, no change to compiled behaviour.

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

Author: g-andrade

src/xb5_bag_node.erl

@@ -1450,6 +1450,13 @@ fold_recur(Fun, Acc, Node) ->
 %% Internal Function Definitions: from_ordered_list/2
 %% ------------------------------------------------------------------
 
+%% The bulk construction scheme is documented at
+%% xb5_utils:bulk_construction_params/1 (what BatchOffset and BatchSize mean)
+%% and above xb5_sets_node:from_ordset_recur/5 (how they pick each node's
+%% arity). What follows is that same algorithm, additionally deriving each
+%% node's offsets O1..On straight from the child sizes S1..Sn - which this
+%% scheme settles before any child is built, so they cost nothing to obtain.
+
 from_ordered_list_recur(S, L, BatchOffset, BatchSize, AtRoot) when S >= 5 ->
     ChildrenBatchOffset = BatchOffset - BatchSize,
     ChildrenBatchSize = BatchSize bsr 2,

src/xb5_sets_node.erl

@@ -1404,6 +1404,33 @@ fold_recur(Fun, Acc, Node) ->
 %% Internal Function Definitions: from_ordset/2
 %% ------------------------------------------------------------------
 
+%% Builds the tree bottom-up in one pass over an already-ordered list, taking
+%% the elements in order and never comparing them. What BatchOffset and
+%% BatchSize mean is documented at xb5_utils:bulk_construction_params/1; in
+%% short, BatchSize - 1 is the size of a perfect subtree of 3-key, 4-child
+%% nodes at this level, and BatchOffset the smallest S that reaches it.
+%%
+%% Given those, (S - BatchOffset) div BatchSize is how many children can be
+%% handed a full BatchSize - 1 elements, which settles this node's arity:
+%%
+%%     0 (at root)  INTERNAL1, 1 key    0 full children + 2 sized from the tail
+%%     0 (deeper)   INTERNAL2, 2 keys   ... treated as 1, see below
+%%     1            INTERNAL2, 2 keys   1 full child   + 2 sized from the tail
+%%     2            INTERNAL3, 3 keys   2 full         + 2
+%%     3            INTERNAL4, 4 keys   3 full         + 2
+%%
+%% A quotient of 0 only yields an INTERNAL1 at the root, which is the sole
+%% place a 1-key node may come to rest - the same invariant deletion upholds.
+%% Below the root a 0 is folded in with 1 and built as an INTERNAL2 instead,
+%% borrowing from the tail to fill it.
+%%
+%% Whatever the arity, the last two children are always sized by
+%% from_ordset_right_children_sizes/2 rather than filled: it takes the
+%% remaining elements and splits them, reserving one for the key between the
+%% two. When that remainder is long enough for both to take a full batch it
+%% gives the left one BatchSize - 1; when it is not, it caps the left at
+%% three quarters of a batch, so that what is left over does not strand the
+%% right child nearly empty. The three quarters is tuned rather than derived.
 from_ordset_recur(S, L, BatchOffset, BatchSize, AtRoot) when S >= 5 ->
     ChildrenBatchOffset = BatchOffset - BatchSize,
     ChildrenBatchSize = BatchSize bsr 2,

src/xb5_trees_node.erl

@@ -1461,6 +1461,11 @@ foldr_recur(Fun, Acc, Node) ->
 %% Internal Function Definitions: from_orddict/2
 %% ------------------------------------------------------------------
 
+%% The bulk construction scheme is documented at
+%% xb5_utils:bulk_construction_params/1 (what BatchOffset and BatchSize mean)
+%% and above xb5_sets_node:from_ordset_recur/5 (how they pick each node's
+%% arity). What follows is that same algorithm over key/value pairs.
+
 from_orddict_recur(S, L, BatchOffset, BatchSize, AtRoot) when S >= 5 ->
     ChildrenBatchOffset = BatchOffset - BatchSize,
     ChildrenBatchSize = BatchSize bsr 2,

src/xb5_utils.erl

@@ -21,6 +21,35 @@
 dialyzer_opaque_term(V) ->
     V.
 
+%% Seeds bulk construction of a tree of `S' elements from already-ordered
+%% input: xb5_sets_node:from_ordset/2, xb5_trees_node:from_orddict/2 and
+%% xb5_bag_node:from_ordered_list/2 all start here, then recurse with the
+%% pair returned.
+%%
+%% The arithmetic counts in base 4, because bulk construction aims for nodes
+%% of 3 keys and 4 children rather than the maximum 4 and 5 - the key density
+%% the README argues for under "Key density". Writing the levels out:
+%%
+%%     S range     BatchOffset   BatchSize   BatchSize - 1
+%%     < 5         1             1           0
+%%     5 .. 20     5             4           3
+%%     21 .. 84    21            16          15
+%%     85 .. 340   85            64          63
+%%     341 ..      341           256         255
+%%
+%% `BatchSize - 1' is 4^(h+1) - 1, the size of a perfect subtree of height h
+%% in which every node holds 3 keys and 4 children. It is the size handed to
+%% each fully loaded child.
+%%
+%% `BatchOffset' is (4^(h+1) - 1) / 3, which is at once the node count of that
+%% perfect subtree and the smallest `S' for which this level is chosen. The
+%% two coincide only because the target density is exactly 3.
+%%
+%% So the loop below returns the deepest level whose perfect subtree still
+%% fits inside `S'. Feeding it exactly 4^(h+1) - 1 elements yields a tree of
+%% precisely 3.000 keys per node and (4^(h+1) - 1) / 3 nodes; the worst case
+%% is `S' equal to a BatchOffset, the point at which a new level is forced and
+%% the root is left an INTERNAL1.
 -spec bulk_construction_params(non_neg_integer()) ->
     nonempty_improper_list(BatchOffset, BatchSize)
 when