Make tree file reading and writing faster and safer

benchmark/Project.toml

@@ -1,7 +1,9 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MultiScaleTreeGraph = "dd4a991b-8a45-4075-bede-262ee62d5583"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [sources]
-MultiScaleTreeGraph = {path = ".."}
+MultiScaleTreeGraph = {path = ".."}

benchmark/README.md

@@ -8,6 +8,36 @@ Run the benchmark suite locally:
 julia --project=benchmark benchmark/benchmarks.jl
 ```
 
+Run the byte-parity, allocation, and timing gates for the streaming MTG writer:
+
+```bash
+julia --project=benchmark benchmark/write_mtg_streaming.jl
+```
+
+Run the focused correctness gate for A1 row-local mutation and topology fixtures:
+
+```bash
+julia --project=benchmark benchmark/test/runtests.jl
+```
+
+The `a1_row_mutation_topology` benchmark group uses deterministic fixtures with
+32, 256, and 1,024 leaf rows plus one root. It measures cold explicit-ID
+construction, one hot explicit-ID append, and `write_mtg` for dense and sparse
+attributes. Row-local `pop!`, `empty!`, and sparse-toggle workloads are registered
+only when a public behavior probe confirms that the loaded MultiScaleTreeGraph
+revision supports row-local absence. Historical schema-wide revisions keep their
+semantic oracle but are not used as a timing baseline for those different
+operations.
+
+The `automatic_id` subgroup exercises repeated ID-less node construction. For
+columnar MTGs, the next ID comes from the store's cached maximum instead of a
+full-tree search. The subgroup keeps the cost of automatic ID allocation visible
+separately from explicit-ID construction.
+
+The writer gate exercises 40 features at 1,000 and 10,000 nodes. It compares the
+streaming path with the compatibility materialization path, measures seven alternating
+samples after warmup, and checks linear scaling.
+
 Workloads currently covered:
 
 - tiered datasets: `small` (~10k nodes), `medium` (~100k), `large` (~300k)

benchmark/benchmarks.jl

@@ -3,6 +3,9 @@ using MultiScaleTreeGraph
 using Random
 using Tables
 
+include("test-row-mutation-topology-benchmark.jl")
+using .A1RowMutationTopologyBenchmarks: build_a1_benchmark_suite!
+
 const SUITE = BenchmarkGroup()
 
 const SIZE_TIERS = (
@@ -325,6 +328,7 @@ SUITE[suite_name] = BenchmarkGroup()
 build_tier!(SUITE[suite_name], "small", SIZE_TIERS.small)
 build_tier!(SUITE[suite_name], "medium", SIZE_TIERS.medium)
 build_tier!(SUITE[suite_name], "large", SIZE_TIERS.large)
+build_a1_benchmark_suite!(SUITE[suite_name])
 
 # Keep the largest tier focused on critical hot paths.
 delete!(SUITE[suite_name]["large"], "api_surface_small_only")