mudlark: polish API surface and fix decay depth bug for 1.0.0

BREAKING CHANGES:

- Replace `GNodeInfo<C, V>` with `Node<C, V>` — `gnode_info()` now
  returns the same Surface 1 view type used by `layers()`. A new
  `#[doc(hidden)] GNodeChildren` covers the child-linkage use case.
- Demote `VNodeId` to `pub(crate)` — no public consuming method
  exists (ADR-M-032 handle test).
- Demote `v_root()` to `pub(crate)`.
- Mark `GNodeId::from_index()` and `GNodeId::index()` as
  `#[doc(hidden)]`.
- Split `Observation::scale()` (panicking default) into a separate
  `ScalableObservation<V>` sub-trait. Cross-type impls (f64→uint,
  f32→uint, f64→f32) implement both; same-type impls no longer
  carry an unusable `scale()`.
- Relax `select_plateaus` bound from `V: Proratable + Inspectable`
  to `V: Inspectable`.
- Demote `serde` from a default feature to opt-in.
- `Cell` now represents the uncovered interval (terminal or vacated
  semi-internal half), not always the full G-node range. `sample()`
  returns the narrowed interval for semi-internals.

Bug fixes:

- Fix decay factor-table index-out-of-bounds panic for f64
  coordinates where G-tree depth can exceed N (ADR-M-038). The
  factor table is now sized from the actual max depth within the
  subtree, not from `N - d_root`.
- Allow `attenuation = 0.0` in `decay()` (annihilation, §THEORY
  M-7.3) and handle `attenuation = ∞` (infinite amplification)
  without NaN from `ln(0) * 0` or `ln(∞) * 0`.
- Guard `Attenuatable::attenuate()` for f32/f64 against IEEE 754
  `0 * ∞ = NaN` — if either operand is zero, return zero.
- Fix invariant checkers and debug assertions to short-circuit
  `∞ == ∞` before computing `∞ - ∞ = NaN`.

Improvements:

- Add `Node::parent` field and `Node::is_root()` method.
- Add `debug_assert!` P2 guard in `observe()` for negative
  accumulations (ADR-M-033).
- Move `select_plateaus` from graph_query.rs to graph_plateau.rs.
- Relax `Pewei` method bounds: `layer_count()`, `node_count()`,
  `reconstruct_all()` require only `Accumulator`, not `Proratable`.
- Correct sampling cost from O(1.44 H + 1.67) to O(1.44 H).
- Mark `build_plateaus()` and `build_plateau_basis()` as
  `#[doc(hidden)]`.

Documentation:

- Rewrite ADR-M-032 with testable surface-assignment criteria and
  expanded analogy tables.
- Add ADR-M-038 (decay factor-table depth bound).
- Significantly expand docs/api.md with Cell/Node/contour-range
  semantics, cross-references, and worked examples.
- Update idea.md, architecture.md, performance.md, testing.md.

Tests:

- Add `tests/decay_infinite.rs` — infinite amplification, ADR-M-038
  regression, and annihilation edge cases (480 lines).
- Add `tests/negative_f64.rs` — P2 violation guard and downstream
  semantic breakage tests (290 lines).
- Update test count: 833 → 868 (346 unit, 415 integration,
  107 doc-tests).
- Update CHANGELOG release date to 2026-03-20.

Author: da2ce7

packages/mudlark/CHANGELOG.md

@@ -5,10 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2026-03-11
+## [1.0.0] - 2026-03-20
 
 Initial stable release. The public API surface documented in
-[docs/api.md](docs/api.md) is now covered by semver guarantees.
+[docs/api.md](docs/api.md) is covered by semver guarantees from
+1.0.0 onwards.
 
 ### Added
 
@@ -31,7 +32,7 @@ Initial stable release. The public API surface documented in
   (requires `V: Proratable + Inspectable`).
 - **Plateau selection** — `select_plateaus(lo, hi)` snapping
   arbitrary coordinates to lattice-aligned contour range endpoints
-  (requires `V: Proratable + Inspectable`).
+  (requires `V: Inspectable`).
 - **Proportional sampling** — `sample(rng)` with O(1.44 H + 1.67)
   expected cost (inherent: `V: Weighable`; via `WeightedSampler`
   trait: `V: Weighable + Inspectable`).
@@ -57,8 +58,8 @@ Initial stable release. The public API surface documented in
 - **Instrument traits** — `SpatialRead`, `SpatialWrite`,
   `TemporalDecay`, `WeightedSampler`.
 - **Built-in implementations** for `u8`–`u128`, `f32`, `f64`.
-- **Feature flags** — `dynamic-contour-tracking` (default), `serde`
-  (default), `rand` (default).
+- **Feature flags** — `dynamic-contour-tracking` (default), `rand`
+  (default), `serde` (opt-in).
 - **Serde support** — `Serialize`/`Deserialize` on all Surface 1
   snapshot types behind the `serde` feature.
 - **rand integration** — blanket `Rng` impl for `rand_core::Rng`
@@ -69,7 +70,7 @@ Initial stable release. The public API surface documented in
   builder, and RNG stubs in the `testing` module.
 - **143 Criterion benchmarks** across six families (observe, query,
   extract, lifecycle, spray, pathological).
-- **833 tests** (346 unit, 379 integration, 108 doc-tests).
+- **868 tests** (346 unit, 415 integration, 107 doc-tests).
 - **37 architecture decision records** in `adr/`.
 - **Full documentation** — `idea.md` (formal spec), `api.md`,
   `architecture.md`, `performance.md`, `testing.md`, `theory.md`.

packages/mudlark/Cargo.toml

@@ -19,7 +19,7 @@ rust-version.workspace = true
 workspace = true
 
 [features]
-default = ["dynamic-contour-tracking", "rand", "serde"]
+default = ["dynamic-contour-tracking", "rand"]
 dynamic-contour-tracking = []
 rand = ["dep:rand_core"]
 serde = ["dep:serde"]

packages/mudlark/README.md

@@ -38,8 +38,16 @@ Or add it manually to your `Cargo.toml`:
 torrust-mudlark = "1"
 ```
 
-All three default features (`dynamic-contour-tracking`, `serde`, `rand`)
-are enabled. To opt out:
+The two default features (`dynamic-contour-tracking` and `rand`) are
+enabled automatically. The `serde` feature is opt-in:
+
+```toml
+[dependencies]
+torrust-mudlark = { version = "1", features = ["serde"] }
+```
+
+Users who need a minimal build should use `default-features = false`,
+which disables both default features simultaneously:
 
 ```toml
 [dependencies]
@@ -134,7 +142,7 @@ canonical path per type.
 | `ContourRange<C, V>` | 1       | Full contour-range decomposition of a lattice-aligned interval       |
 | `ContourRangeEnergy<V>` | 1    | Energy-only result of a contour range query                          |
 | `BasisElement<C, V>`    | 1    | One element of the minimal G-node cover of a contour range           |
-| `GNodeId`, `VNodeId` | 1       | Opaque arena handles                                                 |
+| `GNodeId`            | 1       | Opaque arena handle                                                  |
 
 ### Key operations on `GvGraph`
 
@@ -148,8 +156,8 @@ canonical path per type.
 | `range_sum(range)`                | Recursive G-Tree range sum — $O(N)$ (requires `V: Proratable`)                 |
 | `contour_range(start, end)`       | Contour range decomposition — $O(N)$ (requires `V: Proratable + Inspectable`)  |
 | `contour_range_energy(start, end)` | Energy-only contour range query — $O(N)$ (requires `V: Proratable + Inspectable`) |
-| `select_plateaus(lo, hi)`          | Plateau selection — snaps arbitrary coords to lattice endpoints — $O(\log P)$ (requires `V: Proratable + Inspectable`) |
-| `sample(rng)`                     | Proportional sampling — $O(1.44\,H + 1.67)$ expected (requires `V: Weighable`) |
+| `select_plateaus(lo, hi)`          | Plateau selection — snaps arbitrary coords to lattice endpoints — $O(\log P)$ (requires `V: Inspectable`) |
+| `sample(rng)`                     | Proportional sampling — $O(1.44\,H)$ expected (requires `V: Weighable`) |
 | `extract()`                       | PEWEI extraction — $O(n)$ (requires `V: Inspectable`)                          |
 | `layers()`                        | Streaming V-Tree BFS yielding `(layer_index, Node)` — lazy, $O(V)$ BFS queue (requires `V: Inspectable`) |
 | `decay(root, attenuation, q)`     | Subband-adaptive temporal decay (requires `V: Attenuatable + Inspectable`)     |
@@ -165,7 +173,7 @@ canonical path per type.
 | `Accumulator`    | Core intensity/value type — non-negative, starting from zero. Provided for `u8`..`u128`, `f32`, `f64`                                                    |
 | `Attenuatable`   | Multiplicative decay — required by `decay()` / `TemporalDecay`                                                                                           |
 | `Weighable`      | Weight projection to `f64` — required by `sample()` / `WeightedSampler`                                                                                  |
-| `Proratable`     | Fractional subdivision — required by `range_sum()`, `contour_range()`, `contour_range_energy()`, `select_plateaus()`, and `Pewei::reconstruct()`         |
+| `Proratable`     | Fractional subdivision — required by `range_sum()`, `contour_range()`, `contour_range_energy()`, and `Pewei::reconstruct()`         |
 | `Inspectable`    | Diagnostic `f64` projection — baseline for most operations (`observe`, `plateaus`, `extract`, `layers`, `contour_range`, `from_observations`, `check_evictions`, `decay`) |
 | `Observation<V>` | Accumulation rule (blanket impl for same-type; cross-type for floats)                                                                                    |
 | `Rng`            | Minimal RNG — blanket impl for `rand_core::Rng` with `rand` feature                                                                                  |
@@ -208,7 +216,7 @@ require fallback paths for every feature they break.
 | Feature                    | Default | Effect                                                              |
 | -------------------------- | ------- | ------------------------------------------------------------------- |
 | `dynamic-contour-tracking` | yes     | Live plateau mirror; `plateaus()` returns `Cow::Borrowed` in $O(1)$ |
-| `serde`                    | yes     | `Serialize`/`Deserialize` on all Surface 1 snapshot types           |
+| `serde`                    | no      | `Serialize`/`Deserialize` on all Surface 1 snapshot types           |
 | `rand`                     | yes     | Blanket `Rng` impl for all `rand_core::Rng` types               |
 
 ## Performance
@@ -284,8 +292,8 @@ cargo clippy -p torrust-mudlark --all-targets --all-features
 cargo doc -p torrust-mudlark --all-features --no-deps
 ```
 
-833 tests across unit, integration, and doc-test suites (346 unit,
-379 integration, 108 doc-tests).
+868 tests across unit, integration, and doc-test suites (346 unit,
+415 integration, 107 doc-tests).
 See [docs/testing.md](docs/testing.md) for the full breakdown,
 feature-gated variation, and benchmark details.
 

packages/mudlark/adr/022-pewei-serialisation.md

@@ -95,22 +95,22 @@ crate stays dependency-light when the feature is disabled. `serde`
 is always available as a dev-dependency for the test harness,
 regardless of the feature flag.
 
-**Note:** The `serde` feature is enabled by default in `Cargo.toml`
-(`default = ["dynamic-contour-tracking", "rand", "serde"]`), so
-most consumers get serialisation support without opting in.
-Consumers who want a minimal dependency tree can specify
-`default-features = false`.
+**Note:** The `serde` feature is **not** enabled by default
+(`default = ["dynamic-contour-tracking", "rand"]`). Consumers who
+need serialisation support must opt in explicitly:
+`features = ["serde"]`.
 
 ## Consequences
 
-- Zero compile-time cost for consumers who disable the `serde`
-  feature (`default-features = false`).
-- Consumers using default features get `Serialize`/`Deserialize` on
-  all Surface 1 snapshot types with no additional configuration.
+- Zero compile-time cost for consumers who do not enable the `serde`
+  feature.
+- Consumers who enable the `serde` feature get
+  `Serialize`/`Deserialize` on all Surface 1 snapshot types.
 - Users who want JSON/CBOR/MessagePack output get
   `Serialize`/`Deserialize` on all Surface 1 snapshot types.
 - `Pewei<C, V>` is `Serialize` when both `C: Serialize` and
   `V: Serialize` — always true for primitive types. Custom newtypes
   must derive `Serialize` themselves.
 - The `dynamic-contour-tracking`, `rand`, and `serde` features are
-  independent and composable.
+  independent and composable. `serde` is opt-in; the other two are
+  default-on.

packages/mudlark/adr/024-decay-semantics.md

@@ -219,7 +219,8 @@ trailing rebalance — see Q2).
 | `q` in `(0.0, 1.0]`    | Selective path. Per-depth factors via precomputed table.                    |
 | `q < 0.0`              | Panic. Negative selectivity is not meaningful.                              |
 | `q > 1.0`              | Panic. At $q > 1$, coarse subbands would _grow_, violating decay semantics. |
-| `attenuation <= 0.0`   | Panic. Non-positive factors are not meaningful for multiplicative decay.    |
+| `attenuation == 0.0`   | Annihilation (§THEORY M-7.3). At $q < 1$: entire subtree zeroed. At $q = 1$: detail flush ($0^0 = 1$ preserves root, descendants zeroed). |
+| `attenuation < 0.0`    | Panic. Negative factors are not meaningful for multiplicative decay.        |
 | `attenuation.is_nan()` | Panic. NaN attenuation is a programmer error.                               |
 | `attenuation == 1.0`   | No-op. Early return.                                                        |
 | `attenuation > 1.0`    | Allowed (amplification). Documented.                                        |