mudlark: close mutation-testing gaps; rewrite README with doc-tested examples

A cargo-mutants run produced ~305 surviving mutants, revealing
systematic blind spots in value-correctness, boundary-precision,
and type-coverage testing.  ADR-M-039 documents the analysis and
classifies survivors into seven mutant classes; this commit closes
the gaps it identified.

Test count: 868 → 1 311 (+443 tests across all three surfaces).

New crate-level test modules:
  - config_validation: rejects invalid Config combinations
  - decompose_basis: value-exact basis-element assertions
  - invariant_self: checker self-consistency (kills class-1 mutants)

New integration tests:
  - pedagogy: 10-step narrative walkthrough of the worked example
    from §IDEA M-16 — bootstrap split, catalytic split, skip-
    promote, uncle shield, PEWEI extraction, proportional sampling,
    subtree decay, and post-decay rebalancing.  Every assertion
    maps to a spec claim; every step prints a teaching narrative.
  - pedagogy_advanced: 18-step companion covering the read surface
    — construction alternatives (from_observations, Extend, Clone),
    gnode_info / is_ancestor_of introspection, range_sum pro-ration
    subtleties, full contour-range query pipeline (endpoint lattice,
    basis consolidation, energy-field algebraic identity,
    energy-only variant, invalid-endpoint rejection), plateau
    selection with outward snap, progressive PEWEI reconstruction
    with truncation, and budget-limited eviction under a tight
    budget=10 ceiling.
  - eviction_diagnostic: step-by-step diagnostic replay (replaces
    eviction_debug)
  - eviction_plateau: plateau integrity through eviction cycles
    (replaces eviction_p_i2)

Both pedagogy tests use `harness = false` (custom main) so the
steps execute in sequence on a shared graph, printing a continuous
narrative that can be read alongside the formal spec.

Removed (superseded):
  - eviction_debug → eviction_diagnostic
  - eviction_p_i2 → eviction_plateau

Every existing test file receives a doc-header index table per the
new AGENTS.md "Test Doc-Headers" convention, plus targeted new tests
to kill mutation-testing survivors.

README rewrite:
  - New "Choose GvGraph" section (when to use, when not to)
  - Quick Start rebuilt around a minimal N=3 graph with five
    canonical observations; each section is a runnable doc-test
    (compiled via `include_str!` in lib.rs)
  - New sections: adaptive splitting with ASCII contour diagrams,
    entropy-adaptive sampling, targeted subtree decay, advanced
    usage (checkpoint/fork, gnode_info, contour-range decomposition,
    progressive PEWEI reconstruction, budget-constrained operation)
  - "Limitations" section (1D only, f64 cost, single-writer, no
    signed accumulators)
  - Performance table softened to "typical latencies" with caveat
    that absolute numbers vary by hardware
  - Cross-reference conventions reformatted as a tag→document table
  - License section updated for the new LINKING-EXCEPTION

LINKING-EXCEPTION:
  AGPL-3.0-only linking exception (v1.0) permitting unmodified use
  through Surfaces 1 and 2 without copyleft obligations on the
  consumer's code.  Surface 3 (pub(crate) / #[doc(hidden)]) remains
  fully AGPL.  Explicitly notes the Legacy Exception does not apply
  to this package.

Other changes:
  - Cell / api.md docs expanded: sample() can land on internal
    G-nodes whose V-entry carries frozen pre-split intensity
    (ADR-M-019, §IDEA M-6.5)
  - GNode::Internal doc-comment expanded with the same detail
  - Config<V> derives PartialEq (needed by config_validation and
    the pedagogy test's README_CONFIG == worked_example_config guard)
  - Testing presets: no_split_config, f64_no_split_config,
    decay_config, contour_range_config, plan_multi_plateau
  - Testing runners: run_diagnostic, run_diagnostic_budgeted
    (step-by-step invariant-checking replay with full diagnostic
    dump on first violation)
  - ADR tables reformatted for consistent column alignment
  - AGENTS.md: "Test Doc-Headers" convention added, table and
    prose refinements
  - CHANGELOG date corrected to 2026-03-21; test counts updated
  - rand 0.10 added to dev-dependencies
  - updated `project-words.txt`

Author: da2ce7

Cargo.lock

@@ -5,7 +5,7 @@ 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-20
+## [1.0.0] - 2026-03-21
 
 Initial stable release. The public API surface documented in
 [docs/api.md](docs/api.md) is covered by semver guarantees from
@@ -70,8 +70,8 @@ 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).
-- **868 tests** (346 unit, 415 integration, 107 doc-tests).
-- **37 architecture decision records** in `adr/`.
+- **1315 tests** (651 unit, 543 integration, 121 doc-tests).
+- **38 architecture decision records** in `adr/`.
 - **Full documentation** — `idea.md` (formal spec), `api.md`,
   `architecture.md`, `performance.md`, `testing.md`, `theory.md`.
 

packages/mudlark/CHANGELOG.md

@@ -31,11 +31,15 @@ tracing = "0"
 
 [dev-dependencies]
 criterion = { version = "0", features = ["html_reports"] }
+rand = "0.10"
 rand_core = { version = "0.10" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 tracing-subscriber = { version = "0", features = ["env-filter"] }
 
+[package.metadata.cargo-machete]
+ignored = ["rand"]
+
 [[bench]]
 harness = false
 name = "observe"
@@ -59,3 +63,11 @@ name = "spray"
 [[bench]]
 harness = false
 name = "pathological"
+
+[[test]]
+harness = false
+name = "pedagogy"
+
+[[test]]
+harness = false
+name = "pedagogy_advanced"

packages/mudlark/Cargo.toml

@@ -0,0 +1,38 @@
+TORRUST-MUDLARK LINKING EXCEPTION
+Version 1.0, 2026
+
+As a special exception, the copyright holders of the torrust-mudlark
+library give you permission to combine this library with independent
+crates to produce a combined work, and to distribute and make available
+the resulting combined work under terms of your choice, provided that:
+
+  (a) you interact with the library solely through its documented
+      public API — Surfaces 1 (Prints) and 2 (Film) as specified in
+      docs/api.md of the library's source distribution; and
+
+  (b) you do not modify the library's source code; and
+
+  (c) you include a copy of, or a URI pointing to, this exception
+      notice and the GNU Affero General Public License alongside the
+      combined work.
+
+This exception applies to the obligations imposed by Sections 5, 6,
+and 13 of the GNU Affero General Public License version 3: neither
+distributing the combined work, nor making it available for interaction
+over a computer network, requires you to offer or provide the
+Corresponding Source of your independent crates under the AGPL, so
+long as the conditions above are met.
+
+Any code that reaches into Surface 3 (Emulsion) — the library's
+pub(crate) and #[doc(hidden)] internal machinery as defined in
+docs/api.md §6 — or that copies, adapts, or links against internal
+modules directly, is not covered by this exception and remains
+subject to the full terms of the AGPL.
+
+If you modify the library, you may extend this exception to your
+modified version, but you are not obligated to do so. If you do not
+wish to extend it, delete this exception statement from your version.
+
+Note: The Torrust project's Legacy Exception (five-year MIT-0 sunset)
+does not apply to this package. torrust-mudlark is licensed under
+AGPL-3.0-only with this Linking Exception only.