mudlark: introduce generational GNodeId handle (ADR-M-040)

The G-node arena reuses slots via a free list. A handle obtained
before an eviction could silently bind to a new, unrelated node
after the slot is reallocated (ABA problem). This is not
hypothetical — the sentinel stores handles across observation
cycles where evict-then-split sequences can recycle slots.

Introduce a two-tier handle design:

- GNodeId (pub, 8 bytes): slot index + generation counter.
  Used on all public API surfaces. Consuming methods
  (decay, gnode_info, is_ancestor_of) validate the generation
  and panic on mismatch.

- GSlotPointer (pub(crate), 4 bytes): generation-free handle
  for internal tree walks where no interleaving eviction can
  occur. Renamed from the former GNodeId.

- VSlotPointer (pub(crate), 4 bytes): renamed from VNodeId
  for consistency with the new naming convention.

Arena changes:
- alloc() returns (index, generation) tuple
- dealloc() increments the per-slot generation counter
- New generation() accessor for handle validation

The generation Vec is cold data — touched only on alloc/dealloc,
never on hot read/write paths. Internal hot paths continue to use
4-byte GSlotPointer; the 8-byte GNodeId exists only at the API
boundary.

Author: da2ce7

packages/mudlark/README.md

@@ -536,7 +536,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`               | 1       | Opaque arena handle                                                  |
+| `GNodeId`                    | 1       | Opaque generational arena handle (ADR-M-040)                         |
 
 ### Key operations on `GvGraph`
 

packages/mudlark/adr/001-node-storage.md

@@ -40,8 +40,8 @@ and invalidation safety.
 
 **Option B — Generational `Vec` arenas**, refined with:
 
-- **`NonZeroU32` niche-optimized handles** — `Option<GNodeId>` and
-  `Option<VNodeId>` are exactly 4 bytes (no discriminant overhead).
+- **`NonZeroU32` niche-optimized handles** — `Option<GSlotPointer>` and
+  `Option<VSlotPointer>` are exactly 4 bytes (no discriminant overhead).
 - **Separate `Vec<u64>` bitset** for occupancy tracking instead of
   per-slot generation counters, keeping node structs cache-line sized.
 - **`debug_assert!`** on occupancy for stale-handle detection — catches
@@ -74,11 +74,11 @@ occupancy, compiles to bare array access in release.
 ```rust
 use std::num::NonZeroU32;
 
-struct GNodeId(NonZeroU32);   // 4 bytes, Option = 4 bytes
-struct VNodeId(NonZeroU32);   // 4 bytes, Option = 4 bytes
+struct GSlotPointer(NonZeroU32);   // 4 bytes, Option = 4 bytes
+struct VSlotPointer(NonZeroU32);   // 4 bytes, Option = 4 bytes
 ```
 
-Type-safe: `GNodeId` cannot index the V-node arena (compile error).
+Type-safe: `GSlotPointer` cannot index the V-node arena (compile error).
 Opaque outside the crate — `from_index()` and `index()` are
 currently `pub` (§API M-4.4 notes this as potential future
 tightening).

packages/mudlark/adr/002-vtree-node-enum.md

@@ -15,7 +15,7 @@ module — `VNode<V>`, `VKind<V>`, `PackedChildren<V>`)
 **Related ADRs:**
 
 - [ADR-M-001](001-node-storage.md): arena topology — determines that
-  `VNode<V>` lives in a single `Arena<VNode<V>>` with `VNodeId`
+  `VNode<V>` lives in a single `Arena<VNode<V>>` with `VSlotPointer`
   handles
 - [ADR-M-013](013-eviction-eligibility.md): eviction eligibility uses
   `is_evictable` on entries and `has_evictable` on structural nodes
@@ -37,7 +37,7 @@ pattern-matching ergonomics, arena design, and traversal code.
 
 1. **Separate types + trait:** `VEntry<V>` and `VStructural<V>` in
    separate arenas, unified by a `VNode` trait. Requires two arena
-   pools and a `VNodeId` enum to distinguish which pool to index.
+   pools and a `VSlotPointer` enum to distinguish which pool to index.
 
 2. **Single enum:** `VNode<V>` with a `VKind<V>` enum. One arena,
    one handle type. Pattern match on `node.kind` at each use site.
@@ -49,14 +49,14 @@ pattern-matching ergonomics, arena design, and traversal code.
 ```rust
 struct VNode<V> {                  // 64 bytes for V = u64 — one cache line
     intensity: V,                  //  8 bytes: sum for structural, own for entry
-    parent: Option<VNodeId>,       //  4 bytes
+    parent: Option<VSlotPointer>,       //  4 bytes
     cached_depth: AtomicU32,       //  4 bytes: padding gap (ADR-M-029)
     kind: VKind<V>,                // 48 bytes
 }
 
 enum VKind<V> {
     Entry {
-        gnode: GNodeId,            // backing G-node (V-I4)
+        gnode: GSlotPointer,            // backing G-node (V-I4)
         is_exposed: bool,          // on contour? (V-I6)
         is_evictable: bool,        // zero G-children? (V-I6b)
     },
@@ -103,7 +103,7 @@ Two booleans on `VKind::Entry`, each serving a distinct purpose:
 ```rust
 struct PackedChildren<V> {         // 40 bytes for V = u64
     intensities: [V; 3],          // 24 bytes — hot: one scan per sampling step
-    ids: [Option<VNodeId>; 3],    // 12 bytes — cold: read only after winner chosen
+    ids: [Option<VSlotPointer>; 3],    // 12 bytes — cold: read only after winner chosen
     len: u8,                      //  1 byte  — 2 or 3
 }
 ```
@@ -119,7 +119,7 @@ visits the parent), so maintenance cost is zero.
 
 ## Consequences
 
-- One arena (`Arena<VNode<V>>`) and one handle type (`VNodeId`) for
+- One arena (`Arena<VNode<V>>`) and one handle type (`VSlotPointer`) for
   all V-Tree nodes. Simpler than two pools + enum handle.
 - Pattern matching on `node.kind` is ergonomic and exhaustive —
   the compiler enforces that both variants are handled.

packages/mudlark/adr/003-violation-tracking.md

@@ -25,7 +25,7 @@ entry's intensity grows past its max uncle. The rebalance loop
 
 ## Decision
 
-**Eager tracking with a `Vec<VNodeId>` work queue.**
+**Eager tracking with a `Vec<VSlotPointer>` work queue.**
 
 ### Rationale
 
@@ -34,7 +34,7 @@ during sum propagation. The uncle check reads the grandparent's
 `PackedChildren` — which is in the same cache line, already loaded.
 The violation check is **free in cache terms**.
 
-Pushing a `VNodeId` onto a `Vec` is a single write. Scanning the
+Pushing a `VSlotPointer` onto a `Vec` is a single write. Scanning the
 entire V-Tree to find the same violations would re-read nodes
 already in hand.
 
@@ -49,7 +49,7 @@ struct GvGraph<C, V, const N: u32> {
 
     /// Work queue — scoped to one mutation batch (observe, evict, decay).
     /// Built during propagation, drained by rebalance(), empty on return.
-    violations: Vec<VNodeId>,
+    violations: Vec<VSlotPointer>,
 }
 ```
 
@@ -303,7 +303,7 @@ The implementation includes a safety-net iteration limit proportional
 to arena size (`20 × node_count`, floor 10 000). In debug builds
 the limit panics; in release builds it breaks out with an error log.
 
-`rebalance()` returns `Vec<GNodeId>` — the G-nodes created by
+`rebalance()` returns `Vec<GSlotPointer>` — the G-nodes created by
 legacy promotions (§IDEA M-11.6) during the drain, so the caller can handle
 plateau and depth-control bookkeeping.
 

packages/mudlark/adr/006-generic-parameters.md

@@ -495,7 +495,7 @@ over `O: Observation<V>`. See [ADR-M-024](024-decay-semantics.md) for
 the full design rationale.
 
 ```rust
-pub fn decay(&mut self, root: GNodeId, attenuation: f64, q: f64);
+pub fn decay(&mut self, root: GSlotPointer, attenuation: f64, q: f64);
 ```
 
 The original design made `decay` generic over `O: Observation<V>`.

packages/mudlark/adr/007-thread-safety.md

@@ -56,10 +56,10 @@ Rust auto-derives `Send + Sync` for the entire struct.
 | ------------------- | --------------------------------------- | ----------------------------- |
 | `gnodes`            | `Arena<GNode<C, V>>`                    | `Send + Sync` when `C, V` are |
 | `vnodes`            | `Arena<VNode<V>>`                       | `Send + Sync` when `V` is ¹   |
-| `g_root`            | `GNodeId` (`NonZeroU32`)                | `Copy + Send + Sync`          |
-| `v_root`            | `Option<VNodeId>` (`NonZeroU32` niche)  | `Copy + Send + Sync`          |
+| `g_root`            | `GSlotPointer` (`NonZeroU32`)                | `Copy + Send + Sync`          |
+| `v_root`            | `Option<VSlotPointer>` (`NonZeroU32` niche)  | `Copy + Send + Sync`          |
 | `config`            | `Config<V>`                             | `Send + Sync` when `V` is     |
-| `violations`        | `Vec<VNodeId>`                          | `Send + Sync`                 |
+| `violations`        | `Vec<VSlotPointer>`                          | `Send + Sync`                 |
 | `node_count`        | `u32`                                   | `Send + Sync`                 |
 | `terminal_count`    | `u32`                                   | `Send + Sync`                 |
 | `live_depth_evict`  | `u32`                                   | `Send + Sync`                 |
@@ -68,7 +68,7 @@ Rust auto-derives `Send + Sync` for the entire struct.
 | `headroom`          | `usize`                                 | `Send + Sync`                 |
 | `soft_limit`        | `Option<usize>`                         | `Send + Sync`                 |
 | `plateaus`†         | `BTreeMap<BasisEdge<C>, Plateau<C, V>>` | `Send + Sync` when `C, V` are |
-| `pending_p_i4`†     | `Vec<(GNodeId, BasisEdge<C>)>`          | `Send + Sync` when `C` is     |
+| `pending_p_i4`†     | `Vec<(GSlotPointer, BasisEdge<C>)>`          | `Send + Sync` when `C` is     |
 | `plateau_basis`†    | `PlateauBasis<C>` ²                     | `Send + Sync` when `C` is     |
 | `plateaus_dirty`†   | `bool`                                  | `Send + Sync`                 |
 
@@ -79,7 +79,7 @@ Rust auto-derives `Send + Sync` for the entire struct.
 auto-trait depends only on `V`.
 
 ² `PlateauBasis<C>` is backed by a `BTreeMap<BasisEdge<C>,
-HashSet<GNodeId>>` (forward map) and a `HashMap<GNodeId,
+HashSet<GSlotPointer>>` (forward map) and a `HashMap<GSlotPointer,
 BasisEdge<C>>` (back map). All three collections are `Send + Sync`
 when their element types are — satisfied when `C: Send + Sync`.
 

packages/mudlark/adr/008-span-type.md

@@ -85,7 +85,7 @@ What should borrowed view types look like?
 
 | Option | Design                                                                                        | Notes                                                                                                                                     |
 | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| A      | `Cell<'a, C, V>` borrows `&'a GvGraph` + `GNodeId` — deref to fields lazily                   | Zero-copy, minimal struct (pointer + handle). But every field access goes through a pointer chase.                                        |
+| A      | `Cell<'a, C, V>` borrows `&'a GvGraph` + `GSlotPointer` — deref to fields lazily                   | Zero-copy, minimal struct (pointer + handle). But every field access goes through a pointer chase.                                        |
 | B      | `Cell<'a, C, V>` contains `start: C, end: C, intensity: V, depth: u32` — snapshot at creation | Copied on construction. Self-contained. No borrow escape hazards. Can outlive the graph if `'a` is removed (but then it's just a `Span`). |
 | C      | `Cell<'a, C, V> = &'a Span<C, V>` — `Cell` is a type alias for a reference                    | Simplest. No new struct. But can't add Cell-specific methods without a newtype.                                                           |
 | D      | `Cell<'a, C, V>` borrows individual fields: `start: &'a C, end: &'a C, intensity: &'a V`      | Fine-grained borrows. Unusual in Rust — typically borrow-of-struct patterns use a single reference.                                       |
@@ -98,7 +98,7 @@ What should borrowed view types look like?
 - `Cell` should support `cell.to_span() -> Span<C, V>` for ownership
   transfer regardless of option chosen.
 - `Node` (an internal G-Tree node) could follow the same pattern as
-  Cell, adding `children: (GNodeId, GNodeId)` for traversal. Or it
+  Cell, adding `children: (GSlotPointer, GSlotPointer)` for traversal. Or it
   can be deferred — most API surfaces only expose terminal cells.
 - If `Cell` is just a `Span` with a lifetime, Option C is simplest
   and avoids type proliferation.

packages/mudlark/adr/009-trait-decomposition.md

@@ -61,7 +61,7 @@ pub trait SpatialWrite: SpatialRead {
 /// Temporal decay: subband-adaptive attenuation.
 /// Requires `Self::Accum: Attenuatable`.
 pub trait TemporalDecay: SpatialRead {
-    fn decay(&mut self, root: GNodeId, attenuation: f64, q: f64);
+    fn decay(&mut self, root: GSlotPointer, attenuation: f64, q: f64);
 }
 
 /// Weighted random sampling over entries by intensity.

packages/mudlark/adr/012-g-sum-recomputation.md

@@ -90,7 +90,7 @@ requires subtraction internally — reduces to Option A or B.
 ```rust
 pub fn recompute_g_sums<C: Coordinate, V: Accumulator>(
     gnodes: &mut Arena<GNode<C, V>>,
-    start: GNodeId,
+    start: GSlotPointer,
 ) {
     let mut current = Some(start);
     while let Some(id) = current {

packages/mudlark/adr/015-eviction-scan-design.md

@@ -518,7 +518,7 @@ Option A).
 
 ```rust
 fn check_evictions(&mut self) -> u32 {
-    // Phase 1: collect eligible entry VNodeIds
+    // Phase 1: collect eligible entry VSlotPointers
     let candidates = evict::scan_for_candidates(self);
 
     // Phase 2: evict each candidate
@@ -565,7 +565,7 @@ if soft_limit_exceeded {
 
 ### Recommendation: Two-phase collect-then-evict with single trailing rebalance
 
-Phase 1 (scan) collects candidates into a `Vec<VNodeId>`. Phase 2
+Phase 1 (scan) collects candidates into a `Vec<VSlotPointer>`. Phase 2
 evicts each with re-verification. Violations accumulate during
 phase 2. Phase 3 is a single `rebalance()` call to drain all
 violations. This avoids mutating the tree during traversal, avoids