feat(array): let callers choose a nested builder's chunk threshold [builders-child-stack]

[robert3005]

Rationale for this change

Stacked on #8964 — review that one first.

ChildBuilder copies appended arrays shorter than 64 values instead of giving each one a chunk. That default is right for the callers it was written for: nested builders routinely append the elements of a single list, and a chunk per list would produce a ChunkedArray with more chunks than values.

It is wrong for a caller whose appended arrays are already chunks whose identity is the point. The motivating one is ChunkedArray's canonicalization, which today hand-rolls swizzle_list_chunks and friends precisely to reuse each chunk's children without copying.

The argument for the knob is compatibility rather than measured performance. Canonicalizing a ChunkedArray currently preserves every chunk boundary in the children, at any chunk size; letting the default threshold apply would silently coalesce chunks under 64 rows into a copy. Passing 0 reproduces today's behaviour exactly, which is what a refactor should do. Whether sub-64-row chunks are common enough at canonicalization time for that to matter is unmeasured — I instrumented the threshold across eleven crates' test suites and every production-shaped append (7232 and 8192 rows, file scan batches) chunked under either setting; the only sub-64 chunks observed came from tests.

What changes are included in this PR?

ArrayBuilder::set_min_chunk_len, defaulting to a no-op so builders without array children ignore it. StructBuilder, ListBuilder, ListViewBuilder, FixedSizeListBuilder and ExtensionBuilder forward it to their ChildBuilders, which hold the threshold as a field instead of reading the const.

Two semantics worth stating, both documented on the trait method:

• The threshold is read when an array is appended, so it only affects subsequent appends — no "call this before anything else" ordering trap.
• It applies transitively. A ChildBuilder's scalar builder is itself a nested builder with children of its own, so it gets the setting too.

Three tests: a threshold of zero keeps every chunk boundary at the ChildBuilder level and through the public builder_with_capacity, and the transitive case is checked with a list-typed child short enough to be materialized whose elements would otherwise have earned a chunk.

What APIs are changed? Are there any user-facing changes?

One new ArrayBuilder trait method with a default implementation, so external implementors are unaffected. No behaviour change for anyone who does not call it: DEFAULT_MIN_CHUNK_LEN is the previous constant.

Checks

• cargo test -p vortex-array — 3167 lib tests
• cargo +nightly fmt --all, cargo clippy -p vortex-array --all-targets --all-features

---

Generated by Claude Code

Stacked PR Chain: builders-child-stack

PR	Title	Merges Into
#9046	perf(array): stop flattening appended list views in ListViewBuilder [builders-child-stack]	N/A
#8964	feat(array): builders no longer canonicalize their children [builders-child-stack]	#9046
#8965	feat(array): let callers choose a nested builder's chunk threshold [builders-child-stack]	#8964
#8966	perf(array): accumulate nested builder validity without a null buffer [builders-child-stack]	#8965
#8967	refactor(array): canonicalize chunked structs and FSLs through the builder [builders-child-stack]	#8966

---

Generated by Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 1841 untouched benchmarks
⏩ 55 skipped benchmarks¹

---

_{Comparing claude/builders-min-chunk-len-9ze0t6 (20dd597) with claude/builders-canonical-children-9ze0t6 (c78ed3c)}

Footnotes

1. 55 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[robert3005]

Superseded: MIN_CHUNK_LEN is deleted in #8964, which now keeps every appended array as a chunk however short it is. With no threshold left there is nothing for set_min_chunk_len to configure, and #8967 no longer needs to call it.

The looping callers that motivated the threshold — the sparse fill loops and ListBuilder::extend_from_listview — are converted to bulk appends in #9064 instead, so nothing depends on this any more.