feat: add runnable :samples module (#47)

* build: scaffold :samples module (issue #37)

* feat: add runnable, verified examples to :samples (issue #37)

* ci,docs: run :samples in CI and document ./gradlew :samples:run (issue #37)

.github/workflows/test.yml

@@ -23,7 +23,7 @@ jobs:
         include:
           - name: JVM / JS / Wasm / Native + API check
             os: ubuntu-latest
-            tasks: jvmTest jsNodeTest wasmJsNodeTest nativeTest apiCheck
+            tasks: jvmTest jsNodeTest wasmJsNodeTest nativeTest apiCheck :samples:test :samples:run
           - name: iOS
             os: macos-latest
             tasks: iosSimulatorArm64Test

.gitignore

@@ -19,3 +19,6 @@ build/
 /.idea/jarRepositories.xml
 /.idea/deploymentTargetDropDown.xml
 /.idea/
+
+# Local superpowers working docs (design specs, plans) — not part of the repo
+docs/superpowers/

README.md

@@ -213,6 +213,15 @@ val bigger = root.addChild(ImmutableTreeNode("Asia")) // root is unchanged; bigg
 bigger.preOrder().forEach { println(it.value) } // pre/post/level-order, nodeCount(), height()
 ```
 
+## Examples
+
+A runnable `:samples` module bundles compile-checked, assertion-verified examples of the core API
+and the serialization, coroutines, and immutable modules. Run them with:
+
+```
+./gradlew :samples:run
+```
+
 ## Notes
 
 `TreeNode` is mutable and not thread-safe. Add your own synchronization if you share a tree across

build.gradle.kts

@@ -59,6 +59,11 @@ repositories {
     mavenCentral()
 }
 
+apiValidation {
+    // :samples is a dev-facing examples module, not a published artifact, so it has no .api dump.
+    ignoredProjects.add("samples")
+}
+
 dependencies {
     // Include this module's own docs in the aggregation — DGP v2 requires the
     // aggregating project to list itself explicitly.

docs/superpowers/specs/2026-06-07-tree-enhancements-design.md

@@ -1,77 +0,0 @@
-# Design — four additive enhancements to `tree-structure` (target 4.1.0)
-
-Date: 2026-06-07. Source issues: #34, #35, #36, #33. Integration: **four separate PRs**,
-one per issue (`Closes #NN`), matching the repo's per-issue PR convention (#32).
-
-## Shared rules (every issue)
-
-- `explicitApi()` is on everywhere → every new public declaration is `public` with KDoc.
-- New tests live in `commonTest`, use `kotlin("test")`, and mirror the existing test style
-  (`TreeNodeV4Test.kt`, `TreeNodeNavigationTest.kt`, …).
-- Add a bullet to `CHANGELOG.md` under `## [Unreleased]` → `### Added` (do **not** bump
-  `PUBLISH_VERSION`; releases are a separate manual step).
-- Regenerate the binary-compatibility baseline with `./gradlew apiDump`; verify with `apiCheck`.
-- Do not modify the core public surface in a breaking way — these are additive only.
-
-## #34 — Structural mutation helpers → **members on `TreeNode`**
-
-Members (not extensions) because they need the private `_children`/`_parent` and the cycle/parent
-validation.
-
-- Extract the existing inline validation from `addChild` into a private
-  `validateAttachable(child)` and reuse it.
-- `insertChild(index: Int, child)` — validated insert at index (bounds `0.._children.size`).
-- `removeChildAt(index: Int): TreeNode<T>` — remove and return the detached child.
-- `replaceChild(index: Int, child): TreeNode<T>` — swap, return the old (now detached) child.
-- `moveChild(child, toIndex): Boolean` — reorder an existing direct child; no re-parent/cycle
-  check needed (it is already a child); `false` if `child` is not a direct child.
-- `addChildren(vararg children)` — validated append of several (per-child `addChild` semantics).
-- `sortChildren(comparator: Comparator<TreeNode<T>>)` — stable in-place reorder.
-
-## #35 — Query algorithms → **extensions** in new `TreeNodeQueryExt.kt`
-
-Built on the public API (`ancestors()`, `parent`, `depth()`, sequences). Return `null` when the
-two nodes are unrelated (different trees).
-
-- `lowestCommonAncestor(other): TreeNode<T>?` — deepest common node; includes self/other as
-  candidates (`LCA(a, a) == a`, `LCA(a, descendantOfA) == a`).
-- `distance(other): Int?` — `depth(this) + depth(other) - 2 * depth(lca)`.
-- `pathBetween(other): List<TreeNode<T>>?` — `[this … lca … other]`.
-- `contains(value): Boolean` — value search over the subtree, including the receiver.
-
-Document complexity (parent-walk based; O(depth) for LCA/distance, O(n) for `contains`).
-
-## #36 — Customizable `prettyString()` → **extension** in new `TreeNodePrettyPrintExt.kt`
-
-- `data class TreeConnectors(branch, lastBranch, vertical, empty)` with a `companion`:
-  `Default` (current Unicode box-drawing) and `Ascii`.
-- `fun TreeNode<T>.prettyString(connectors = TreeConnectors.Default,
-  render: (value: T, depth: Int, isLast: Boolean) -> String = { v, _, _ -> v.toString() }): String`.
-- The no-arg member `prettyString()` is unchanged; member resolution wins for `node.prettyString()`,
-  so existing behaviour and output are byte-for-byte identical.
-
-## #33 — Immutable variant → **new module `:tree-structure-immutable`**
-
-Largest item; fully isolated from the other three except for `settings.gradle.kts`,
-`libs.versions.toml`, the root `build.gradle.kts` Dokka aggregation block, and `CHANGELOG.md`.
-
-- `settings.gradle.kts`: `include(":tree-structure-immutable")`.
-- New `build.gradle.kts` mirroring the serialization module's KMP target matrix; deps
-  `api(project(":"))` + `kotlinx-collections-immutable`.
-- `libs.versions.toml`: add `kotlinx-collections-immutable` (a recent stable, e.g. 0.3.8) and
-  wire it.
-- Root `build.gradle.kts`: add `dokka(project(":tree-structure-immutable"))` to the aggregation.
-- `ImmutableTreeNode<T>` backed by `persistentListOf` children; `addChild` / `removeChild` /
-  `mapValues` return a new root with unchanged subtrees structurally shared. Mirror pre/post/
-  level-order traversal helpers.
-- Its own `tree-structure-immutable/api/` baseline via `apiDump`.
-
-## Orchestration
-
-- Four git worktrees off `origin/master`, one branch each (`feat/...`), for full isolation — no
-  collisions on `TreeNode.kt`, `api/*.api`, or `CHANGELOG.md`.
-- A workflow pipelines each issue: implement (code + KDoc + tests + CHANGELOG + `apiDump`) and
-  verify locally (`jvmTest` + `apiCheck`), then an adversarial reviewer checks issue-conformance,
-  test quality, invariants, explicit API, `.api` freshness, and that it builds. Local checks are
-  JVM-only for speed; CI validates the full KMP matrix on each PR.
-- Then push each passing branch and open a PR (`Closes #NN`); remove the worktrees afterward.

samples/build.gradle.kts

@@ -0,0 +1,35 @@
+plugins {
+    // No version: the Kotlin Gradle plugin is already on the build classpath via the root
+    // project's kotlinMultiplatform plugin, so requesting a version here would clash.
+    kotlin("jvm")
+    application
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+application {
+    mainClass.set("com.github.adriankuta.samples.SamplesKt")
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(project(":"))
+    implementation(project(":tree-structure-serialization"))
+    implementation(project(":tree-structure-coroutines"))
+    implementation(project(":tree-structure-immutable"))
+    // ImmutableTreeNode.children returns a PersistentList, so consumers that touch it need
+    // kotlinx.collections.immutable on their own classpath (the module declares it as implementation).
+    implementation(libs.kotlinx.collections.immutable)
+
+    testImplementation(kotlin("test"))
+}
+
+// kotlin("test") auto-selects the JUnit 5 adapter when the test task uses the JUnit Platform.
+tasks.test {
+    useJUnitPlatform()
+}

samples/src/main/kotlin/com/github/adriankuta/samples/Samples.kt

@@ -0,0 +1,121 @@
+package com.github.adriankuta.samples
+
+import com.github.adriankuta.datastructure.tree.TreeNode
+import com.github.adriankuta.datastructure.tree.ancestors
+import com.github.adriankuta.datastructure.tree.anyNode
+import com.github.adriankuta.datastructure.tree.countNodes
+import com.github.adriankuta.datastructure.tree.deepCopy
+import com.github.adriankuta.datastructure.tree.distance
+import com.github.adriankuta.datastructure.tree.filterNodes
+import com.github.adriankuta.datastructure.tree.findNode
+import com.github.adriankuta.datastructure.tree.isLeaf
+import com.github.adriankuta.datastructure.tree.leaves
+import com.github.adriankuta.datastructure.tree.levelOrderSequence
+import com.github.adriankuta.datastructure.tree.lowestCommonAncestor
+import com.github.adriankuta.datastructure.tree.mapValues
+import com.github.adriankuta.datastructure.tree.pathBetween
+import com.github.adriankuta.datastructure.tree.preOrderSequence
+import com.github.adriankuta.datastructure.tree.structurallyEquals
+import com.github.adriankuta.datastructure.tree.tree
+import com.github.adriankuta.datastructure.tree.coroutines.asFlow
+import com.github.adriankuta.datastructure.tree.coroutines.preOrderFlow
+import com.github.adriankuta.datastructure.tree.immutable.ImmutableTreeNode
+import com.github.adriankuta.datastructure.tree.immutable.preOrder
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import com.github.adriankuta.datastructure.tree.serialization.TreeNodeDto
+import com.github.adriankuta.datastructure.tree.serialization.toDto
+import com.github.adriankuta.datastructure.tree.serialization.toTreeNode
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.decodeFromString
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+private fun sampleTree(): TreeNode<String> = tree("World") {
+    child("North America") {
+        child("USA")
+    }
+    child("Europe") {
+        child("Poland")
+        child("Germany")
+    }
+}
+
+/** Core API: DSL, pretty-print, traversal, navigation, functional, query, utilities, mutation. */
+fun coreSample(): String = buildString {
+    val root = sampleTree()
+
+    appendLine("prettyString():")
+    append(root.prettyString())
+    appendLine()
+
+    appendLine("pre-order:   " + root.preOrderSequence().map { it.value }.toList())
+    appendLine("level-order: " + root.levelOrderSequence().map { it.value }.toList())
+
+    val usa = root.findNode { it == "USA" }!!
+    val poland = root.findNode { it == "Poland" }!!
+    appendLine("usa.depth():       " + usa.depth())
+    appendLine("usa.ancestors():   " + usa.ancestors().map { it.value })
+    appendLine("root.leaves():     " + root.leaves().map { it.value })
+    appendLine("usa.isLeaf:        " + usa.isLeaf)
+
+    appendLine("anyNode == Poland: " + root.anyNode { it == "Poland" })
+    appendLine("filterNodes len>5: " + root.filterNodes { it.length > 5 }.map { it.value })
+    appendLine("countNodes 'U*':   " + root.countNodes { it.startsWith("U") })
+    appendLine("mapValues length:  " + root.mapValues { it.length }.preOrderSequence().map { it.value }.toList())
+    appendLine("deepCopy equals:   " + root.structurallyEquals(root.deepCopy()))
+
+    appendLine("lowestCommonAncestor(USA, Poland): " + usa.lowestCommonAncestor(poland)?.value)
+    appendLine("pathBetween(USA, Poland):          " + usa.pathBetween(poland)?.map { it.value })
+    appendLine("distance(USA, Poland):             " + usa.distance(poland))
+
+    appendLine("nodeCount(): " + root.nodeCount())
+    appendLine("height():    " + root.height())
+    appendLine("path(USA):   " + root.path(usa)?.map { it.value })
+
+    // Mutation on a copy; the shared sampleTree() stays untouched.
+    val mutable = root.deepCopy()
+    mutable.addChild(TreeNode("Asia"))
+    mutable.findNode { it == "Germany" }?.detach()
+    appendLine("after addChild(Asia) + detach(Germany): " + mutable.preOrderSequence().map { it.value }.toList())
+}
+
+/** Serialization satellite: TreeNode -> TreeNodeDto -> JSON -> TreeNodeDto -> TreeNode round-trip. */
+fun serializationSample(): String = buildString {
+    val root = sampleTree()
+    val json = Json.encodeToString(root.toDto())
+    appendLine("JSON: $json")
+    val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
+    appendLine("round-trips structurallyEquals: " + root.structurallyEquals(restored))
+}
+
+/** Coroutines satellite: traverse the tree as a cold Flow. */
+fun coroutinesSample(): String = buildString {
+    val root = sampleTree()
+    val preOrder = runBlocking { root.preOrderFlow().map { it.value }.toList() }
+    val levelOrder = runBlocking { root.asFlow(TreeNodeIterators.LevelOrder).map { it.value }.toList() }
+    appendLine("preOrderFlow():     $preOrder")
+    appendLine("asFlow(LevelOrder): $levelOrder")
+}
+
+/** Immutable satellite: persistent tree; every op returns a new root, leaving the original intact. */
+fun immutableSample(): String = buildString {
+    val root = ImmutableTreeNode("World").addChild(ImmutableTreeNode("Europe"))
+    val bigger = root.addChild(ImmutableTreeNode("Asia"))
+    appendLine("root.children:   " + root.children.map { it.value })
+    appendLine("bigger.children: " + bigger.children.map { it.value })
+    appendLine("root unchanged:  " + (root.children.size == 1))
+    appendLine("bigger.mapValues uppercase preOrder: " + bigger.mapValues { it.uppercase() }.preOrder().map { it.value })
+}
+
+fun main() {
+    println("== Core ==")
+    println(coreSample())
+    println("== Serialization ==")
+    println(serializationSample())
+    println("== Coroutines ==")
+    println(coroutinesSample())
+    println("== Immutable ==")
+    println(immutableSample())
+}

samples/src/test/kotlin/com/github/adriankuta/samples/SamplesTest.kt

@@ -0,0 +1,46 @@
+package com.github.adriankuta.samples
+
+import kotlin.test.Test
+import kotlin.test.assertContains
+
+class SamplesTest {
+
+    @Test
+    fun coreSampleRendersTreeAndTraversals() {
+        val out = coreSample()
+        assertContains(
+            out,
+            "World\n" +
+                "├── North America\n" +
+                "│   └── USA\n" +
+                "└── Europe\n" +
+                "    ├── Poland\n" +
+                "    └── Germany\n",
+        )
+        assertContains(out, "[World, North America, USA, Europe, Poland, Germany]")
+        assertContains(out, "[North America, World]") // usa.ancestors()
+        assertContains(out, "[USA, Poland, Germany]") // root.leaves()
+    }
+
+    @Test
+    fun serializationSampleRoundTrips() {
+        val out = serializationSample()
+        assertContains(out, "\"World\"")
+        assertContains(out, "round-trips structurallyEquals: true")
+    }
+
+    @Test
+    fun coroutinesSampleCollectsFlows() {
+        val out = coroutinesSample()
+        assertContains(out, "preOrderFlow():     [World, North America, USA, Europe, Poland, Germany]")
+        assertContains(out, "asFlow(LevelOrder): [World, North America, Europe, USA, Poland, Germany]")
+    }
+
+    @Test
+    fun immutableSampleLeavesRootUnchanged() {
+        val out = immutableSample()
+        assertContains(out, "root.children:   [Europe]")
+        assertContains(out, "bigger.children: [Europe, Asia]")
+        assertContains(out, "root unchanged:  true")
+    }
+}

settings.gradle.kts

@@ -4,3 +4,4 @@ include(":tree-structure-serialization")
 include(":tree-structure-coroutines")
 include(":tree-structure-compose")
 include(":tree-structure-immutable")
+include(":samples")

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodePropertyTest.kt

@@ -0,0 +1,455 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.random.Random
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+/**
+ * Property-based tests for traversal and structural invariants (issue #38).
+ *
+ * Instead of a handful of hand-written example trees, each property is checked against many
+ * randomly generated trees. Generation is seeded ([BASE_SEED] + iteration index), so a failing case
+ * is fully reproducible: rerun [randomTree] with the seed printed in the failure message. No
+ * external dependency is used, so these run on every Kotlin target (JVM/JS/Wasm/Native).
+ */
+class TreeNodePropertyTest {
+
+    // -----------------------------------------------------------------------------------------
+    // Traversal node-set invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun allThreeOrdersVisitTheSameSetOfNodes() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val post = tree.postOrderSequence().toList()
+        val level = tree.levelOrderSequence().toList()
+
+        assertEquals(pre.toSet(), post.toSet(), "pre vs post node set (seed=$seed)")
+        assertEquals(pre.toSet(), level.toSet(), "pre vs level node set (seed=$seed)")
+    }
+
+    @Test
+    fun allThreeOrdersHaveTheSameCardinalityAndNoDuplicates() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val post = tree.postOrderSequence().toList()
+        val level = tree.levelOrderSequence().toList()
+        val expectedSize = tree.nodeCount() + 1 // traversal includes the root; nodeCount excludes it
+
+        assertEquals(expectedSize, pre.size, "pre-order size (seed=$seed)")
+        assertEquals(expectedSize, post.size, "post-order size (seed=$seed)")
+        assertEquals(expectedSize, level.size, "level-order size (seed=$seed)")
+        assertEquals(pre.size, pre.toSet().size, "pre-order visits no node twice (seed=$seed)")
+        assertEquals(post.size, post.toSet().size, "post-order visits no node twice (seed=$seed)")
+        assertEquals(level.size, level.toSet().size, "level-order visits no node twice (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Per-order ordering invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun preOrderEmitsEverySubtreeAsAContiguousBlockAfterItsRoot() = forEachRandomTree { tree, seed ->
+        val pre = tree.preOrderSequence().toList()
+        val index = pre.indexMap()
+        for (node in pre) {
+            val start = index.getValue(node) + 1
+            val block = pre.subList(start, start + node.nodeCount())
+            assertEquals(node.descendants().toSet(), block.toSet(), "pre-order subtree of $node (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun postOrderEmitsEverySubtreeAsAContiguousBlockBeforeItsRoot() = forEachRandomTree { tree, seed ->
+        val post = tree.postOrderSequence().toList()
+        val index = post.indexMap()
+        for (node in post) {
+            val end = index.getValue(node)
+            val block = post.subList(end - node.nodeCount(), end)
+            assertEquals(node.descendants().toSet(), block.toSet(), "post-order subtree of $node (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun levelOrderVisitsNodesInNonDecreasingDepth() = forEachRandomTree { tree, seed ->
+        val depths = tree.levelOrderSequence().map { it.depth() }.toList()
+        for (i in 1 until depths.size) {
+            assertTrue(depths[i - 1] <= depths[i], "level-order depth not monotonic at $i (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun preAndLevelOrderVisitEveryParentBeforeItsChildren() = forEachRandomTree { tree, seed ->
+        for (order in listOf(tree.preOrderSequence(), tree.levelOrderSequence())) {
+            val index = order.toList().indexMap()
+            for (node in index.keys) {
+                for (child in node.children) {
+                    assertTrue(index.getValue(node) < index.getValue(child), "parent before child (seed=$seed)")
+                }
+            }
+        }
+    }
+
+    @Test
+    fun postOrderVisitsEveryChildBeforeItsParent() = forEachRandomTree { tree, seed ->
+        val index = tree.postOrderSequence().toList().indexMap()
+        for (node in index.keys) {
+            for (child in node.children) {
+                assertTrue(index.getValue(child) < index.getValue(node), "child before parent (seed=$seed)")
+            }
+        }
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // depth / height invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun depthMatchesAnIndependentBfsLevelAndEveryChildIsOneDeeper() = forEachRandomTree { tree, seed ->
+        assertEquals(0, tree.depth(), "root depth (seed=$seed)")
+        // Independent oracle: derive each node's level by walking DOWN through children (BFS), then
+        // cross-check against depth(), which walks UP through parent pointers. A bug in the parent
+        // walk cannot corrupt both derivations identically.
+        val levelByNode = HashMap<TreeNode<Int>, Int>()
+        levelByNode[tree] = 0
+        val queue = ArrayDeque<TreeNode<Int>>()
+        queue.add(tree)
+        while (queue.isNotEmpty()) {
+            val node = queue.removeFirst()
+            for (child in node.children) {
+                levelByNode[child] = levelByNode.getValue(node) + 1
+                queue.add(child)
+            }
+        }
+        for (node in tree) {
+            assertEquals(levelByNode.getValue(node), node.depth(), "depth matches BFS level (seed=$seed)")
+            for (child in node.children) {
+                assertEquals(node.depth() + 1, child.depth(), "child depth (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun heightEqualsDeepestDescendantDistanceAndLeavesHaveHeightZero() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            val expected = node.asSequence().maxOf { it.depth() } - node.depth()
+            assertEquals(expected, node.height(), "height of $node (seed=$seed)")
+            if (node.isLeaf) assertEquals(0, node.height(), "leaf height (seed=$seed)")
+        }
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // nodeCount invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun nodeCountEqualsDescendantCountForEveryNode() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            // Independent oracle: nodeCount() walks an explicit stack; the pre-order sequence is a
+            // separate traversal, so agreeing pins the count without circularity.
+            assertEquals(node.asSequence().count() - 1, node.nodeCount(), "nodeCount vs traversal (seed=$seed)")
+            // Recursive self-consistency: a node's count is the sum of (each child + its subtree).
+            assertEquals(node.children.sumOf { it.nodeCount() + 1 }, node.nodeCount(), "nodeCount recursive sum (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun nodeCountAndTraversalStayConsistentAcrossAttachAndDetach() = forEachRandomTree { tree, seed ->
+        // A second, independent tree we graft onto a random node of `tree`, then remove again.
+        val grafted = randomTree(Random(seed * 31 + 7), maxNodes = 20)
+        val host = tree.toList().random(Random(seed xor SELECT_SALT))
+
+        val countBefore = tree.nodeCount()
+        val graftSize = grafted.nodeCount() + 1 // the grafted root plus its descendants
+
+        host.addChild(grafted)
+        assertEquals(countBefore + graftSize, tree.nodeCount(), "nodeCount after addChild (seed=$seed)")
+        assertTrue(tree.toSet().containsAll(grafted.toList()), "grafted nodes now reachable (seed=$seed)")
+        assertSameNode(host, grafted.parent, "graft re-parented (seed=$seed)")
+
+        assertTrue(grafted.detach(), "detach returns true (seed=$seed)")
+        assertEquals(countBefore, tree.nodeCount(), "nodeCount restored after detach (seed=$seed)")
+        assertTrue(grafted.isRoot, "grafted is a root again (seed=$seed)")
+        assertFalse(tree.toSet().contains(grafted), "grafted no longer reachable (seed=$seed)")
+    }
+
+    @Test
+    fun removeAndReinsertKeepNodeCountAndPointersConsistent() = forEachRandomTree { tree, seed ->
+        val rnd = Random(seed xor 0x55AA_55AAL)
+        val parents = tree.toList().filter { it.children.isNotEmpty() }
+        if (parents.isEmpty()) return@forEachRandomTree // single-node tree: nothing to remove
+
+        val parent = parents.random(rnd)
+        val countBefore = tree.nodeCount()
+        val index = rnd.nextInt(parent.children.size)
+        val subtreeSize = parent.children[index].nodeCount() + 1
+
+        val removed = parent.removeChildAt(index)
+        assertTrue(removed.isRoot, "removeChildAt detaches the child (seed=$seed)")
+        assertEquals(countBefore - subtreeSize, tree.nodeCount(), "nodeCount drops by the subtree (seed=$seed)")
+        assertFalse(tree.toSet().contains(removed), "removed subtree no longer reachable (seed=$seed)")
+
+        val insertAt = rnd.nextInt(parent.children.size + 1)
+        parent.insertChild(insertAt, removed)
+        assertEquals(countBefore, tree.nodeCount(), "nodeCount restored after insertChild (seed=$seed)")
+        assertSameNode(parent, removed.parent, "re-inserted subtree is re-parented (seed=$seed)")
+        assertSameNode(removed, parent.children[insertAt], "re-inserted at the requested index (seed=$seed)")
+        for (node in tree) {
+            for (child in node.children) {
+                assertSameNode(node, child.parent, "parent pointers stay consistent (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun clearRemovesEveryDescendantAndKeepsTheNodeAttached() = forEachRandomTree { tree, seed ->
+        val node = tree.toList().random(Random(seed xor SELECT_SALT))
+        val parentBefore = node.parent
+        node.clear()
+        assertEquals(0, node.nodeCount(), "nodeCount after clear (seed=$seed)")
+        assertTrue(node.children.isEmpty(), "children empty after clear (seed=$seed)")
+        assertSameNode(parentBefore, node.parent, "node keeps its own parent after clear (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Structural / parent-pointer invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun parentAndChildPointersAreConsistentForEveryNode() = forEachRandomTree { tree, seed ->
+        assertTrue(tree.isRoot, "generated root is a root (seed=$seed)")
+        for (node in tree) {
+            assertEquals(node.parent == null, node.isRoot, "isRoot matches null parent (seed=$seed)")
+            assertSameNode(tree, node.root(), "root() returns the tree root (seed=$seed)")
+            for (child in node.children) {
+                assertSameNode(node, child.parent, "child points back to parent (seed=$seed)")
+            }
+            val parent = node.parent
+            if (parent != null) {
+                assertTrue(parent.children.any { it === node }, "node listed in its parent (seed=$seed)")
+                // Note: TreeNode is Iterable, so `list + node` would flatten the node's subtree —
+                // compare siblings against the parent's other children directly instead.
+                assertEquals(
+                    parent.children.filter { it !== node }.toSet(),
+                    node.siblings().toSet(),
+                    "siblings are exactly the parent's other children (seed=$seed)",
+                )
+                assertFalse(node.siblings().any { it === node }, "siblings exclude self (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun ancestorChainOfEveryNodeTerminatesAtTheRoot() = forEachRandomTree { tree, seed ->
+        for (node in tree) {
+            val ancestors = node.ancestors()
+            assertEquals(node.depth(), ancestors.size, "ancestor count equals depth (seed=$seed)")
+            if (ancestors.isNotEmpty()) {
+                assertSameNode(tree, ancestors.last(), "topmost ancestor is the root (seed=$seed)")
+            }
+            ancestors.forEach { assertTrue(it.depth() < node.depth(), "ancestors are shallower (seed=$seed)") }
+        }
+    }
+
+    @Test
+    fun leavesAreExactlyTheChildlessNodes() = forEachRandomTree { tree, seed ->
+        assertEquals(tree.asSequence().filter { it.isLeaf }.toSet(), tree.leaves().toSet(), "leaves (seed=$seed)")
+        assertTrue(tree.leaves().all { it.isLeaf }, "every leaf is childless (seed=$seed)")
+        assertEquals(tree.toList().size, tree.descendants().size + 1, "descendants + self (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Transform / structural-equality invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun deepCopyAndIdentityMapPreserveShapeWithFreshNodes() = forEachRandomTree { tree, seed ->
+        assertTrue(tree.structurallyEquals(tree), "structurallyEquals is reflexive (seed=$seed)")
+
+        val copy = tree.deepCopy()
+        assertTrue(copy.structurallyEquals(tree), "deepCopy is structurally equal (seed=$seed)")
+        assertEquals(tree.nodeCount(), copy.nodeCount(), "deepCopy node count (seed=$seed)")
+        assertEquals(tree.height(), copy.height(), "deepCopy height (seed=$seed)")
+        assertTrue(copy.toSet().intersect(tree.toSet()).isEmpty(), "deepCopy shares no node object (seed=$seed)")
+
+        val mapped = tree.mapValues { it }
+        assertTrue(mapped.structurallyEquals(tree), "identity mapValues preserves structure (seed=$seed)")
+        assertTrue(mapped.toSet().intersect(tree.toSet()).isEmpty(), "mapValues yields fresh nodes (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Functional / value-query invariants
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun valueQueriesAgreeWithTraversalOverUniqueValues() = forEachRandomTree { tree, seed ->
+        val values = tree.asSequence().map { it.value }.toList()
+        assertEquals(values.size, values.toSet().size, "generated values are unique (seed=$seed)")
+        assertEquals(values.size, tree.countNodes { true }, "countNodes(true) == size (seed=$seed)")
+        for (value in values) {
+            assertTrue(tree.contains(value), "contains present value $value (seed=$seed)")
+            assertNotNull(tree.findNode { it == value }, "findNode present value $value (seed=$seed)")
+        }
+        val absent = values.max() + 1 // values are unique and dense from 0, so this one is absent
+        assertFalse(tree.contains(absent), "absent value not contained (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Query algorithms (lca / distance / pathBetween)
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun lowestCommonAncestorIsTheDeepestSharedAncestor() = forEachRandomTree { tree, seed ->
+        val nodes = tree.toList()
+        val rnd = Random(seed xor 0x1234_5678L)
+        repeat(PAIRS_PER_TREE) {
+            val a = nodes.random(rnd)
+            val b = nodes.random(rnd)
+
+            val lca = a.lowestCommonAncestor(b)
+            assertNotNull(lca, "lca within one tree is non-null (seed=$seed)")
+            assertSameNode(lca, b.lowestCommonAncestor(a), "lca is symmetric (seed=$seed)")
+
+            val ancestorsAndSelfA = (listOf(a) + a.ancestors()).toSet()
+            val ancestorsAndSelfB = (listOf(b) + b.ancestors()).toSet()
+            assertTrue(lca in ancestorsAndSelfA, "lca is an ancestor-or-self of a (seed=$seed)")
+            assertTrue(lca in ancestorsAndSelfB, "lca is an ancestor-or-self of b (seed=$seed)")
+            // Common ancestors form a chain, so the deepest one is unique; it must be the lca itself.
+            val deepestShared = ancestorsAndSelfA.intersect(ancestorsAndSelfB).maxByOrNull { it.depth() }
+            assertSameNode(deepestShared, lca, "lca is the deepest shared ancestor (seed=$seed)")
+        }
+    }
+
+    @Test
+    fun distanceAndPathBetweenAreConsistent() = forEachRandomTree { tree, seed ->
+        val nodes = tree.toList()
+        val rnd = Random(seed xor 0x0F0F_0F0FL)
+        repeat(PAIRS_PER_TREE) {
+            val a = nodes.random(rnd)
+            val b = nodes.random(rnd)
+
+            val distance = a.distance(b)
+            assertNotNull(distance, "distance within one tree is non-null (seed=$seed)")
+            assertTrue(distance >= 0, "distance is non-negative (seed=$seed)")
+            assertEquals(distance, b.distance(a), "distance is symmetric (seed=$seed)")
+
+            val path = a.pathBetween(b)
+            assertNotNull(path, "path within one tree is non-null (seed=$seed)")
+            assertSameNode(a, path.first(), "path starts at a (seed=$seed)")
+            assertSameNode(b, path.last(), "path ends at b (seed=$seed)")
+            assertEquals(distance, path.size - 1, "distance == path edges (seed=$seed)")
+            assertEquals(path.size, path.toSet().size, "path has no repeated node (seed=$seed)")
+            for (i in 1 until path.size) {
+                val (p, q) = path[i - 1] to path[i]
+                assertTrue(p.parent === q || q.parent === p, "consecutive path nodes are an edge (seed=$seed)")
+            }
+        }
+    }
+
+    @Test
+    fun distanceAndPathToSelfAreTrivial() = forEachRandomTree { tree, seed ->
+        val node = tree.toList().random(Random(seed xor SELECT_SALT))
+        assertEquals(0, node.distance(node), "distance to self is 0 (seed=$seed)")
+        assertSameNode(node, node.lowestCommonAncestor(node), "lca with self is self (seed=$seed)")
+        assertEquals(listOf(node), node.pathBetween(node), "path to self is the singleton (seed=$seed)")
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // Termination and ordering on degenerate (deep / wide) trees
+    // -----------------------------------------------------------------------------------------
+
+    @Test
+    fun everyTraversalTerminatesAndIsCorrectlyOrderedOnADeepChain() {
+        val depth = 5_000
+        val root = TreeNode(0)
+        var current = root
+        for (i in 1..depth) {
+            val child = TreeNode(i)
+            current.addChild(child)
+            current = child
+        }
+
+        // On a chain pre- and level-order descend the chain; post-order returns it leaf-first. These
+        // pin the actual ordering, not merely that every order visits the same number of nodes.
+        assertContentEquals((0..depth).toList(), root.preOrderSequence().map { it.value }.toList(), "pre-order of a chain")
+        assertContentEquals((0..depth).toList(), root.levelOrderSequence().map { it.value }.toList(), "level-order of a chain")
+        assertContentEquals((depth downTo 0).toList(), root.postOrderSequence().map { it.value }.toList(), "post-order of a chain")
+        assertEquals(depth, root.height(), "height on deep chain")
+        assertEquals(depth, root.nodeCount(), "nodeCount on deep chain")
+        assertEquals(depth, current.depth(), "depth of the deepest node")
+    }
+
+    @Test
+    fun everyTraversalTerminatesAndIsCorrectlyOrderedOnAWideTree() {
+        val width = 5_000
+        val root = TreeNode(0)
+        for (i in 1..width) root.addChild(TreeNode(i))
+
+        // pre- and level-order list the root then its children in order; post-order lists the
+        // children in order then the root.
+        assertContentEquals(listOf(0) + (1..width), root.preOrderSequence().map { it.value }.toList(), "pre-order of a star")
+        assertContentEquals(listOf(0) + (1..width), root.levelOrderSequence().map { it.value }.toList(), "level-order of a star")
+        assertContentEquals((1..width).toList() + 0, root.postOrderSequence().map { it.value }.toList(), "post-order of a star")
+        assertEquals(1, root.height(), "height on wide tree")
+        assertEquals(width, root.nodeCount(), "nodeCount on wide tree")
+        assertTrue(root.children.all { it.depth() == 1 }, "every child of a wide root is at depth 1")
+    }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Random tree generation + property harness
+// ---------------------------------------------------------------------------------------------
+
+private const val ITERATIONS = 200
+private const val BASE_SEED = 0x5EEDL
+
+/** How many random node pairs each query property samples per generated tree. */
+private const val PAIRS_PER_TREE = 8
+
+/** Decorrelates node-selection RNGs from the tree-construction RNG that shares the same seed. */
+private const val SELECT_SALT = 0x2545_F491_4F6C_DD1DL
+
+/** Runs [property] against [iterations] freshly generated random trees, one per derived seed. */
+private fun forEachRandomTree(
+    iterations: Int = ITERATIONS,
+    maxNodes: Int = 80,
+    property: (tree: TreeNode<Int>, seed: Long) -> Unit,
+) {
+    for (i in 0 until iterations) {
+        val seed = BASE_SEED + i
+        property(randomTree(Random(seed), maxNodes), seed)
+    }
+}
+
+/**
+ * Builds a random tree of `1..[maxNodes]` nodes by uniform random attachment: each new node (value
+ * `1, 2, …`) is attached under a uniformly chosen existing node. This samples a broad spread of
+ * shapes — chains, bushy, and lopsided trees, plus single-node trees — without the left-heavy skew
+ * of a depth-first node budget, and is iterative so it never risks the call stack. Values are unique
+ * and dense from `0` (the root). Deterministic for a given [random], so the seed reproduces it.
+ */
+private fun randomTree(random: Random, maxNodes: Int): TreeNode<Int> {
+    val size = random.nextInt(1, maxNodes + 1)
+    val root = TreeNode(0)
+    val nodes = ArrayList<TreeNode<Int>>(size)
+    nodes.add(root)
+    for (value in 1 until size) {
+        val parent = nodes[random.nextInt(nodes.size)]
+        val child = TreeNode(value)
+        parent.addChild(child)
+        nodes.add(child)
+    }
+    return root
+}
+
+/** Maps each node to its position in this traversal. Keys compare by identity (TreeNode equality). */
+private fun List<TreeNode<Int>>.indexMap(): Map<TreeNode<Int>, Int> =
+    withIndex().associate { (i, node) -> node to i }
+
+/** Asserts two references point at the same node object (TreeNode uses identity equality). */
+private fun assertSameNode(expected: TreeNode<*>?, actual: TreeNode<*>?, message: String) {
+    assertTrue(expected === actual, "$message — expected same node as $expected but was $actual")
+}