Skip to content

feat(mudlark): expose structural mutation counters - #900

Draft
da2ce7 wants to merge 3 commits into
torrust:developfrom
da2ce7:20260918_mudlark_counters
Draft

da2ce7 wants to merge 3 commits into
torrust:developfrom
da2ce7:20260918_mudlark_counters

Conversation

@da2ce7

@da2ce7 da2ce7 commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Release Mudlark 1.1.0 with monotonic counters for structural splits, evictions and restorations, plus a reader for the current semi-internal population. The API change is additive.

Motivation

Consumers can observe the live graph shape, but cannot distinguish accumulated structural churn from the current state: reconstructing split, eviction and restoration history from node-state deltas is expensive and unreliable, and a counter epoch that starts at construction makes interval deltas composable across operations. The semi-internal population is a current-state diagnostic in its own right and had no reader.

Change

  • Add StructuralMutationCounts with public splits, evictions and restorations totals; each saturates at u64::MAX rather than wrapping, so it never decreases during the graph's lifetime. A split is counted per child created, so a bisection adds two and a legacy promotion that recreates one missing child adds one restoration.
  • Increment the matching counter at every site that changes the node count: bootstrap_split, catalytic_split, evict_tip and handle_legacy_promotes. The audit of node_count mutation sites finds exactly these four.
  • Add GvGraph::structural_mutation_counts() and GvGraph::semi_internal_count(), the latter computed by scanning the live nodes because the transitions that create and remove a semi-internal node are spread across splitting, eviction and restoration.
  • Cover bootstrap splits, catalytic splits, eviction, legacy restoration and terminal-count behaviour with counter assertions, including a direct restoration test.
  • Document why a depth buffer wide enough to overflow the exponent saturates the headroom figure at a ceiling no budget can clear.
  • Release as Mudlark 1.1.0: the package version, the lock entry, and the dated changelog section with its comparison link.

Verification

At the head commit:

  • cargo +stable clippy --keep-going --workspace --all-targets --all-features -- -D warnings — exit 0.
  • cargo +stable test -p torrust-mudlark --all-targets --all-features — exit 0 (668 unit tests, the integration targets, 116 doctests).
  • cargo +1.90.0 check -p torrust-mudlark --all-features — exit 0.
  • cargo test -p torrust-mudlark --doc --all-features — exit 0.
  • RUSTDOCFLAGS="-D warnings" cargo doc -p torrust-mudlark --no-deps — exit 0.
  • cargo metadata --format-version 1 --locked — exit 0 and resolves torrust-mudlark 1.1.0 from the committed lockfile.
  • Fails-before witness: the base overlaid with only the three test files fails to compile on the absent type, reader and field, linking an isolated base rlib; the head passes the same tests.
  • Mutation witness: removing the eviction increment makes terminal_count_decreases_on_eviction fail with left: 0, right: 1; restoring the file reproduces its blob, mode and mtime exactly.

The public-surface diff is exactly the new struct, its three fields, the two readers and the crate-root re-export; nothing public changed or moved. The lock moves only the torrust-mudlark entry. No dependency change.

Review notes

Nightly workspace clippy on the newest nightly reports two double_must_use findings in index-cli-common, both present at the base and outside this change; stable workspace clippy is green and is the lint this workspace certifies on.

Callers need durable visibility into topology churn without reconstructing it from live graph state. Saturating split, eviction, and restoration totals make those mutations observable while preserving monotonicity.

Expose the live semi-internal population separately as a bounded scan, and exercise every node-count transition so each structural site has direct coverage.
The headroom accessor returns a conservative ceiling even when the configured depth would overflow the structural exponent. Documenting the saturation makes clear that overflow cannot turn an impossible budget into an admissible one.
Publish the additive structural-mutation counters and semi-internal reader as a minor release so callers can depend on the new observation surface.

Keep the package manifest, Cargo lock identity, dated changelog section, and release comparison link aligned.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant