You're designing a public nested builder DSL that produces an immutable tree. What design choices prevent builder/mutation leaks and partially-built nodes from escaping?

## The risk Nested builders are mutable during construction (children get appended). If that mutability leaks past construction, callers can corrupt a 'finished' tree, observe a half-built node, or hold a reference that keeps mutating. A robust public DSL designs the leaks away. ## Pattern: separate builder and result types Keep a mutable **builder** distinct from the immutable **node**: ```kotlin @DslMarker annotation class DocDsl sealed interface Node class Section(val title: String, val children: List<Node>) : Node // immutable result class Text(val value: String) : Node @DocDsl class SectionBuilder(private val title: String) { private val children = mutableListOf<Node>() // private, mutable, hidden fun text(value: String) { children += Text(value) } fun section(title: String, init: SectionBuilder.() -> Unit) { children += SectionBuilder(title).apply(init).build() } fun build(): Section = Section(title, children.toList()) // defensive copy → immutable } fun document(title: String, init: SectionBuilder.() -> Unit): Section = SectionBuilder(title).apply(init).build() ``` Key moves: - **`children` is private and mutable**; the public result exposes only `List<Node>`. - **`build()` copies** with `toList()`, so even if the builder is somehow retained, the produced `Section` can't be mutated through it. - **`section(...)` builds the child immediately** and stores the *immutable* `Section`, not the child builder. - **Builder functions return `Unit`** (or the immutable child), never the live builder — callers can't keep a handle to mutate later. ## Closing the grammar Make the node hierarchy **`sealed`** so only the intended node types exist. Combined with `@DslMarker`, the set of legal nested calls is fully constrained at compile time. ## Avoiding receiver leaks The one real escape route is a user capturing `this` inside a block (`var stash: SectionBuilder? = null; section("x") { stash = this }`). You can't fully prevent capture, but: don't return the builder, keep mutating methods on the builder only (not the result), and the builder becomes useless after `build()` since its output is already copied. Document that the builder is single-use. ## Other considerations - **Validation in build()**: enforce invariants (non-empty title, no duplicate ids) at `build()` time so an invalid tree never materializes. - **Thread-safety**: builders are not thread-safe by design; the receiver lambda runs synchronously on one thread, which is fine — don't share a builder across threads. - **Kotlinx immutable collections**: returning `kotlinx.collections.immutable.PersistentList`/`ImmutableList` documents immutability stronger than `List` (which is only read-only, not guaranteed immutable). ## Summary Hide the mutable builder, produce an immutable result via a defensive-copy `build()`, return immutable children or Unit, seal the hierarchy, mark with `@DslMarker`, and validate in `build()`. Then partially-built or mutable state can't escape the construction call.