Merge branch 'pratik/std-coro/migrate-entry-points' into pratik/std-coro/migrate-test-code

Forward-merge the entry-point migration (carrying the latest develop) into the test-code migration. Conflict resolutions in Coroutine_test.cpp and JobQueue_test.cpp: keep the postCoroTask / CoroTaskRunner form from this branch, with develop's renames (JtClient, Gate::waitFor, kN) and develop's initialization of the unprotected flag.
Merge branch 'pratik/std-coro/add-coroutine-primitives' into pratik/std-coro/migrate-entry-points
2026-07-25 08:00:22 +00:00 · 2026-07-24 20:57:01 +01:00 · 2026-07-24 20:52:28 +01:00 · 2026-07-24 20:39:41 +01:00 · 2026-07-24 17:30:20 +00:00 · 2026-07-24 15:52:45 +00:00
206 changed files with 12320 additions and 10402 deletions
--- a/.cspell.config.yaml
+++ b/.cspell.config.yaml
@@ -30,7 +30,9 @@ ignoreRegExpList:
  - ABCDEFGHIJKLMNOPQRSTUVWXYZ
  - ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
 overrides:
-  - filename: "**/*_test.cpp" # all test files
+  - filename:
+      - "**/*_test.cpp" # legacy boost.test files
+      - "src/tests/**/*.cpp" # gtest test files
    ignoreRegExpList:
      - /"[^"]*"/g # double-quoted strings
      - /'[^']*'/g # single-quoted strings
@@ -65,7 +67,6 @@ words:
  - Btrfs
  - Buildx
  - canonicality
-  - CGNAT
  - canonicalised
  - changespq
  - checkme
@@ -87,6 +88,7 @@ words:
  - coros
  - cowid
  - cpack
+  - cppcoro
  - cryptocondition
  - cryptoconditional
  - cryptoconditions
@@ -125,7 +127,6 @@ words:
  - funclets
  - Gamal
  - gantt
-  - Gantt
  - gcov
  - gcovr
  - ghead
@@ -169,14 +170,16 @@ words:
  - lseq
  - lsmf
  - ltype
+  - Mankawde
  - mathbunnyru
  - mcmodel
  - MEMORYSTATUSEX
+  - MPTAMM
+  - MPTDEX
  - Merkle
  - Metafuncton
  - misprediction
  - missingok
-  - MPTAMM
  - mptbalance
  - MPTDEX
  - mptflags
@@ -210,7 +213,6 @@ words:
  - nonxrp
  - noreplace
  - noripple
-  - nostd
  - nostdinc
  - notifempty
  - nudb
@@ -219,7 +221,7 @@ words:
  - Nyffenegger
  - onlatest
  - ostr
-  - otelc
+  - oxalica
  - pargs
  - partitioner
  - paychan
@@ -230,6 +232,7 @@ words:
  - permissioned
  - pointee
  - populator
+  - Pratik
  - preauth
  - preauthorization
  - preauthorize
@@ -248,6 +251,8 @@ words:
  - Raphson
  - rcflags
  - replayer
+  - repost
+  - reposts
  - rerandomize
  - rerandomization
  - rerandomized
@@ -292,6 +297,7 @@ words:
  - sponsees
  - SRPMS
  - sslws
+  - stackful
  - statsd
  - STATSDCOLLECTOR
  - stissue
@@ -313,7 +319,6 @@ words:
  - TMEndpointv2
  - toolchain
  - tparam
-  - traceql
  - trixie
  - tx
  - txid
@@ -321,7 +326,6 @@ words:
  - txjson
  - txn
  - txns
-  - txqueue
  - txs
  - ubsan
  - UBSAN
@@ -346,6 +350,7 @@ words:
  - unsquelch
  - unsquelched
  - unsquelching
+  - unsuffixed
  - unvalidated
  - unveto
  - unvetoed
@@ -371,5 +376,4 @@ words:
  - xrplf
  - xxhash
  - xxhasher
-  - xychart
-  - zpages
+  - CGNAT
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,10 +1,10 @@
 <!--
-This PR template helps you to write a good pull request description.
+This PR template helps you write a good pull request description.
 Please feel free to include additional useful information even beyond what is requested below.

 If your branch is on a personal fork and has a name that allows it to
 run CI build/test jobs (e.g. "ci/foo"), remember to rename it BEFORE
-opening the PR.  This avoids unnecessary redundant test runs. Renaming
+opening the PR. This avoids redundant test runs. Renaming
 the branch after opening the PR will close the PR.
 https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch
 -->
@@ -15,7 +15,7 @@ https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-
 Please include a summary of the changes.
 This may be a direct input to the release notes.
 If too broad, please consider splitting into multiple PRs.
-If a relevant task or issue, please link it here.
+If there is a relevant task or issue, please link it here.
 -->

 ### Context of Change
@@ -65,5 +65,5 @@ This section may not be needed if your change includes thoroughly commented unit

 <!--
 ## Future Tasks
-For future tasks related to PR.
+For future tasks related to this PR.
 -->
--- a/.github/scripts/levelization/README.md
+++ b/.github/scripts/levelization/README.md
@@ -40,18 +40,18 @@ listed later.
 | 04           | xrpl/protocol                       |
 | 05           | xrpl/core xrpl/resource xrpl/server |
 | 06           | xrpl/ledger xrpl/nodestore xrpl/net |
-| 07           | xrpl/shamap                         |
+| 07           | xrpl/shamap xrpl/consensus          |

 ## xrpld Modules (Application Implementation)

-| Level / Tier | Module(s)                        |
-| ------------ | -------------------------------- |
-| 05           | xrpld/conditions xrpld/consensus |
-| 06           | xrpld/core xrpld/peerfinder      |
-| 07           | xrpld/shamap xrpld/overlay       |
-| 08           | xrpld/app                        |
-| 09           | xrpld/rpc                        |
-| 10           | xrpld/perflog                    |
+| Level / Tier | Module(s)                   |
+| ------------ | --------------------------- |
+| 05           | xrpld/conditions            |
+| 06           | xrpld/core xrpld/peerfinder |
+| 07           | xrpld/shamap xrpld/overlay  |
+| 08           | xrpld/app                   |
+| 09           | xrpld/rpc                   |
+| 10           | xrpld/perflog               |

 ## Test Modules

--- a/.github/scripts/levelization/results/loops.txt
+++ b/.github/scripts/levelization/results/loops.txt
@@ -1,9 +1,6 @@
 Loop: xrpld.app xrpld.overlay
  xrpld.app > xrpld.overlay

-Loop: xrpld.app xrpld.peerfinder
-  xrpld.peerfinder ~= xrpld.app
-
 Loop: xrpld.app xrpld.rpc
  xrpld.rpc > xrpld.app

--- a/.github/scripts/levelization/results/ordering.txt
+++ b/.github/scripts/levelization/results/ordering.txt
@@ -6,6 +6,8 @@ libxrpl.conditions > xrpl.basics
 libxrpl.conditions > xrpl.conditions
 libxrpl.config > xrpl.basics
 libxrpl.config > xrpl.config
+libxrpl.consensus > xrpl.basics
+libxrpl.consensus > xrpl.consensus
 libxrpl.core > xrpl.basics
 libxrpl.core > xrpl.core
 libxrpl.core > xrpl.json
@@ -25,6 +27,9 @@ libxrpl.nodestore > xrpl.config
 libxrpl.nodestore > xrpl.json
 libxrpl.nodestore > xrpl.nodestore
 libxrpl.nodestore > xrpl.protocol
+libxrpl.peerfinder > xrpl.basics
+libxrpl.peerfinder > xrpl.peerfinder
+libxrpl.peerfinder > xrpl.protocol
 libxrpl.protocol > xrpl.basics
 libxrpl.protocol > xrpl.json
 libxrpl.protocol > xrpl.protocol
@@ -60,9 +65,9 @@ test.app > test.jtx
 test.app > test.unit_test
 test.app > xrpl.basics
 test.app > xrpl.config
+test.app > xrpl.consensus
 test.app > xrpl.core
 test.app > xrpld.app
-test.app > xrpld.consensus
 test.app > xrpld.core
 test.app > xrpld.overlay
 test.app > xrpld.rpc
@@ -83,12 +88,9 @@ test.basics > xrpl.protocol
 test.beast > xrpl.basics
 test.conditions > xrpl.basics
 test.conditions > xrpl.conditions
-test.consensus > test.csf
 test.consensus > test.jtx
-test.consensus > test.unit_test
 test.consensus > xrpl.basics
 test.consensus > xrpld.app
-test.consensus > xrpld.consensus
 test.consensus > xrpl.ledger
 test.consensus > xrpl.protocol
 test.consensus > xrpl.shamap
@@ -103,10 +105,6 @@ test.core > xrpl.json
 test.core > xrpl.protocol
 test.core > xrpl.rdb
 test.core > xrpl.server
-test.csf > xrpl.basics
-test.csf > xrpld.consensus
-test.csf > xrpl.json
-test.csf > xrpl.ledger
 test.json > test.jtx
 test.json > xrpl.json
 test.jtx > test.unit_test
@@ -146,19 +144,13 @@ test.overlay > xrpl.config
 test.overlay > xrpld.app
 test.overlay > xrpld.core
 test.overlay > xrpld.overlay
-test.overlay > xrpld.peerfinder
 test.overlay > xrpl.json
 test.overlay > xrpl.nodestore
+test.overlay > xrpl.peerfinder
 test.overlay > xrpl.protocol
 test.overlay > xrpl.resource
 test.overlay > xrpl.server
 test.overlay > xrpl.shamap
-test.peerfinder > test.beast
-test.peerfinder > test.unit_test
-test.peerfinder > xrpl.basics
-test.peerfinder > xrpld.core
-test.peerfinder > xrpld.peerfinder
-test.peerfinder > xrpl.protocol
 test.protocol > test.jtx
 test.protocol > test.unit_test
 test.protocol > xrpl.basics
@@ -192,11 +184,13 @@ test.unit_test > xrpl.basics
 test.unit_test > xrpl.protocol
 tests.libxrpl > xrpl.basics
 tests.libxrpl > xrpl.config
+tests.libxrpl > xrpl.consensus
 tests.libxrpl > xrpl.core
 tests.libxrpl > xrpl.json
 tests.libxrpl > xrpl.ledger
 tests.libxrpl > xrpl.net
 tests.libxrpl > xrpl.nodestore
+tests.libxrpl > xrpl.peerfinder
 tests.libxrpl > xrpl.protocol
 tests.libxrpl > xrpl.protocol_autogen
 tests.libxrpl > xrpl.resource
@@ -206,6 +200,10 @@ tests.libxrpl > xrpl.tx
 xrpl.conditions > xrpl.basics
 xrpl.conditions > xrpl.protocol
 xrpl.config > xrpl.basics
+xrpl.consensus > xrpl.basics
+xrpl.consensus > xrpl.json
+xrpl.consensus > xrpl.ledger
+xrpl.consensus > xrpl.protocol
 xrpl.core > xrpl.basics
 xrpl.core > xrpl.json
 xrpl.core > xrpl.protocol
@@ -220,6 +218,8 @@ xrpl.nodestore > xrpl.basics
 xrpl.nodestore > xrpl.config
 xrpl.nodestore > xrpl.json
 xrpl.nodestore > xrpl.protocol
+xrpl.peerfinder > xrpl.basics
+xrpl.peerfinder > xrpl.protocol
 xrpl.protocol > xrpl.basics
 xrpl.protocol > xrpl.json
 xrpl.protocol_autogen > xrpl.json
@@ -246,23 +246,20 @@ xrpl.tx > xrpl.protocol
 xrpld.app > test.unit_test
 xrpld.app > xrpl.basics
 xrpld.app > xrpl.config
+xrpld.app > xrpl.consensus
 xrpld.app > xrpl.core
-xrpld.app > xrpld.consensus
 xrpld.app > xrpld.core
 xrpld.app > xrpl.json
 xrpld.app > xrpl.ledger
 xrpld.app > xrpl.net
 xrpld.app > xrpl.nodestore
+xrpld.app > xrpl.peerfinder
 xrpld.app > xrpl.protocol
 xrpld.app > xrpl.rdb
 xrpld.app > xrpl.resource
 xrpld.app > xrpl.server
 xrpld.app > xrpl.shamap
 xrpld.app > xrpl.tx
-xrpld.consensus > xrpl.basics
-xrpld.consensus > xrpl.json
-xrpld.consensus > xrpl.ledger
-xrpld.consensus > xrpl.protocol
 xrpld.core > xrpl.basics
 xrpld.core > xrpl.config
 xrpld.core > xrpl.core
@@ -271,21 +268,22 @@ xrpld.core > xrpl.protocol
 xrpld.core > xrpl.rdb
 xrpld.overlay > xrpl.basics
 xrpld.overlay > xrpl.config
+xrpld.overlay > xrpl.consensus
 xrpld.overlay > xrpl.core
-xrpld.overlay > xrpld.consensus
 xrpld.overlay > xrpld.core
 xrpld.overlay > xrpld.peerfinder
 xrpld.overlay > xrpl.json
 xrpld.overlay > xrpl.ledger
+xrpld.overlay > xrpl.peerfinder
 xrpld.overlay > xrpl.protocol
 xrpld.overlay > xrpl.resource
 xrpld.overlay > xrpl.server
 xrpld.overlay > xrpl.shamap
 xrpld.overlay > xrpl.tx
 xrpld.peerfinder > xrpl.basics
-xrpld.peerfinder > xrpl.config
+xrpld.peerfinder > xrpld.app
 xrpld.peerfinder > xrpld.core
-xrpld.peerfinder > xrpl.protocol
+xrpld.peerfinder > xrpl.peerfinder
 xrpld.peerfinder > xrpl.rdb
 xrpld.perflog > xrpl.basics
 xrpld.perflog > xrpl.config
--- a/.github/scripts/strategy-matrix/linux.json
+++ b/.github/scripts/strategy-matrix/linux.json
@@ -1,5 +1,5 @@
 {
-  "image_tag": "sha-2e25435",
+  "image_tag": "sha-40cdf49",
  "configs": {
    "ubuntu": [
      {
--- a/.github/workflows/build-nix-images.yml
+++ b/.github/workflows/build-nix-images.yml
@@ -1,4 +1,4 @@
-name: Build Nix Docker images
+name: Build `nix` Docker images

 on:
  push:
@@ -8,20 +8,24 @@ on:
      - ".github/workflows/build-nix-images.yml"
      - "flake.nix"
      - "flake.lock"
+      - "rust-toolchain.toml"
      - "nix/**"
      - "!nix/docker/README.md"
      - "!nix/devshell.nix"
      - "bin/check-tools.sh"
+      - "bin/default-loader-path.sh"
      - "bin/install-sanitizer-libs.sh"
  pull_request:
    paths:
      - ".github/workflows/build-nix-images.yml"
      - "flake.nix"
      - "flake.lock"
+      - "rust-toolchain.toml"
      - "nix/**"
      - "!nix/docker/README.md"
      - "!nix/devshell.nix"
      - "bin/check-tools.sh"
+      - "bin/default-loader-path.sh"
      - "bin/install-sanitizer-libs.sh"
  workflow_dispatch:

@@ -36,7 +40,7 @@ defaults:

 jobs:
  build-merge:
-    name: Build and push nix-${{ matrix.distro.name }}
+    name: Build and push `nix-${{ matrix.distro.name }}` image
    permissions:
      contents: read
      packages: write
@@ -54,7 +58,7 @@ jobs:
            base_image: debian:bookworm
          - name: rhel
            base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@ee03d31bcc4501d7599dc1b1ecd7a34af582ad1c
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
    with:
      image_name: xrpld/nix-${{ matrix.distro.name }}
      dockerfile: nix/docker/Dockerfile
--- a/.github/workflows/build-packaging-images.yml
+++ b/.github/workflows/build-packaging-images.yml
@@ -1,4 +1,4 @@
-name: Build packaging Docker images
+name: Build `packaging` Docker images

 on:
  push:
@@ -26,7 +26,7 @@ defaults:

 jobs:
  build-merge:
-    name: Build and push packaging-${{ matrix.distro.name }}
+    name: Build and push `packaging-${{ matrix.distro.name }}` image
    permissions:
      contents: read
      packages: write
@@ -38,7 +38,7 @@ jobs:
            base_image: debian:bookworm
          - name: rhel
            base_image: registry.access.redhat.com/ubi9/ubi:latest
-    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@ee03d31bcc4501d7599dc1b1ecd7a34af582ad1c
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
    with:
      image_name: xrpld/packaging-${{ matrix.distro.name }}
      dockerfile: package/Dockerfile
--- a/.github/workflows/build-pre-commit-image.yml
+++ b/.github/workflows/build-pre-commit-image.yml
@@ -0,0 +1,38 @@
+name: Build `pre-commit` Docker image
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - ".github/workflows/build-pre-commit-image.yml"
+      - "bin/pre-commit/Dockerfile"
+      - "rust-toolchain.toml"
+  pull_request:
+    paths:
+      - ".github/workflows/build-pre-commit-image.yml"
+      - "bin/pre-commit/Dockerfile"
+      - "rust-toolchain.toml"
+  workflow_dispatch:
+
+concurrency:
+  # Read `on-trigger.yml` for the rationale behind this concurrency group name.
+  group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' && github.sha || github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-merge:
+    name: Build and push `pre-commit` image
+    permissions:
+      contents: read
+      packages: write
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@9e7e4e80af9e684c116b38369add8eea64451f32
+    with:
+      image_name: xrpld/pre-commit
+      dockerfile: bin/pre-commit/Dockerfile
+      base_image: ubuntu:26.04
+      push: ${{ github.event_name == 'push' }}
--- a/.github/workflows/check-pr-title.yml
+++ b/.github/workflows/check-pr-title.yml
@@ -20,4 +20,4 @@ on:
 jobs:
  check_title:
    if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@cba1f0891650baf1a9c88624dc2d72573be2eb81
+    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@d7c65e49225a38f6d8010eacf017bb5a98d7476c
--- a/.github/workflows/check-tools.yml
+++ b/.github/workflows/check-tools.yml
@@ -0,0 +1,114 @@
+# Verifies the committed snapshots of `bin/check-tools.sh` output for each Nix
+# environment (see nix/check-tools/). If the environment changes — a new image
+# tag, an updated flake.lock, a different tool list — without the matching
+# snapshot being regenerated and committed, this workflow fails so the drift is
+# caught in review.
+#
+# To regenerate the snapshots, see nix/check-tools/README.md.
+name: Check tools
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/check-tools.yml"
+      - ".github/scripts/strategy-matrix/linux.json"
+      - "bin/check-tools.sh"
+      - "nix/**"
+      - "flake.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+  push:
+    branches:
+      - "develop"
+    paths:
+      - ".github/workflows/check-tools.yml"
+      - ".github/scripts/strategy-matrix/linux.json"
+      - "bin/check-tools.sh"
+      - "nix/**"
+      - "flake.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # The nix-nixos image tag is pinned alongside the build matrix in linux.json,
+  # so snapshots are checked against the exact image CI builds against.
+  linux-image-tag:
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Read nix image tag
+        id: tag
+        run: echo "tag=$(jq -r .image_tag .github/scripts/strategy-matrix/linux.json)" >>"${GITHUB_OUTPUT}"
+
+  # One job for all environments; they differ only in whether the tools come
+  # from the nix-nixos container (Linux) or `nix develop` (macOS).
+  check-tools:
+    needs: linux-image-tag
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            snapshot: nix/check-tools/nix-ubuntu-amd64.txt
+            nix_develop: false
+          - runner: ubuntu-24.04-arm
+            snapshot: nix/check-tools/nix-ubuntu-arm64.txt
+            nix_develop: false
+          - runner: macos-26-apple-clang-21
+            snapshot: nix/check-tools/macos.txt
+            nix_develop: true
+    runs-on: ${{ matrix.runner }}
+    # Linux runs inside the pinned nix-nixos image; macOS runs natively and uses
+    # the flake's dev shell instead (see the run step below).
+    container: ${{ !matrix.nix_develop && format('ghcr.io/xrplf/xrpld/nix-ubuntu:{0}', needs.linux-image-tag.outputs.tag) || null }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
+        with:
+          enable_ccache: false
+
+      - name: Regenerate snapshot
+        env:
+          CHECK_TOOLS_SKIP_CLONE: "1"
+          # check-tools.sh skips some macOS tools when CI is set; the snapshots
+          # capture the full `nix develop` environment, so unset it here.
+          CI: ""
+        run: |
+          if [ "${{ matrix.nix_develop }}" = "true" ]; then
+              # `nix develop` prints the dev-shell greeting first; keep only the
+              # check-tools.sh output (from the "Detected OS:" line onward).
+              nix --extra-experimental-features "nix-command flakes" develop \
+                  -c bash bin/check-tools.sh | sed -n '/^Detected OS:/,$p' >"${{ matrix.snapshot }}"
+          else
+              bash bin/check-tools.sh >"${{ matrix.snapshot }}"
+          fi
+
+      - name: Verify snapshot is up to date
+        run: |
+          if ! git diff --exit-code -- "${{ matrix.snapshot }}"; then
+              echo "::error::${{ matrix.snapshot }} is out of date. Regenerate it (see nix/check-tools/README.md) and commit the result."
+              exit 1
+          fi
+
+      - name: Upload regenerated snapshot
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: check-tools-${{ runner.os }}-${{ runner.arch }}
+          path: ${{ matrix.snapshot }}
--- a/.github/workflows/on-pr.yml
+++ b/.github/workflows/on-pr.yml
@@ -90,6 +90,7 @@ jobs:
            .clang-tidy
            .codecov.yml
            bin/check-tools.sh
+            bin/default-loader-path.sh
            cfg/**
            cmake/**
            conan/**
--- a/.github/workflows/on-trigger.yml
+++ b/.github/workflows/on-trigger.yml
@@ -28,6 +28,7 @@ on:
      - ".clang-tidy"
      - ".codecov.yml"
      - "bin/check-tools.sh"
+      - "bin/default-loader-path.sh"
      - "cfg/**"
      - "cmake/**"
      - "conan/**"
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -14,7 +14,7 @@ on:
 jobs:
  # Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
  run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@1bde119a1ab71305ba5d3716e7a82cea1c7bdede
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@3ba08d6ddf114092891d48491fc2e26c3ba15552
    with:
      runs_on: ubuntu-latest
-      container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'
+      container: '{ "image": "ghcr.io/xrplf/xrpld/pre-commit:sha-f56b79f" }'
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -41,13 +41,13 @@ env:
 jobs:
  build:
    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-2e25435
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-40cdf49
    steps:
      - name: Checkout repository
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@ad188deb3dae79dc39816e16ddfdad1e06c6fab2
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
        with:
          enable_ccache: false

--- a/.github/workflows/reusable-build-test-config.yml
+++ b/.github/workflows/reusable-build-test-config.yml
@@ -113,7 +113,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@ad188deb3dae79dc39816e16ddfdad1e06c6fab2
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
        with:
          enable_ccache: ${{ inputs.ccache_enabled }}

@@ -223,11 +223,13 @@ jobs:
          BUILD_TYPE: ${{ inputs.build_type }}
          CMAKE_TARGET: ${{ inputs.cmake_target }}
        run: |
+          set -o pipefail
          cmake \
              --build . \
              --config "${BUILD_TYPE}" \
              --parallel "${BUILD_NPROC}" \
-              --target "${CMAKE_TARGET}"
+              --target "${CMAKE_TARGET}" \
+              2>&1 | tee "${GITHUB_WORKSPACE}/build.log"

      - name: Show ccache statistics
        if: ${{ inputs.ccache_enabled }}
@@ -322,7 +324,7 @@ jobs:
              PRELOAD=""
          fi

-          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee unittest.log
+          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"

      # Smoke-run every benchmark module with a single repetition to confirm the
      # benchmarks still build and execute. This is a correctness check, not a
@@ -341,25 +343,27 @@ jobs:
          done < <(find src/benchmarks -type f -perm -u+x -name 'xrpl.bench.*')
          exit "${rc}"

-      - name: Show test failure summary
-        if: ${{ failure() && !inputs.build_only }}
-        env:
-          WORKING_DIR: ${{ runner.os == 'Windows' && format('{0}\{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
+      - name: Show build/test failure summary
+        if: ${{ failure() }}
        run: |
-          if [ ! -d "${WORKING_DIR}" ]; then
-              echo "Working directory '${WORKING_DIR}' does not exist."
-              exit 0
-          fi
+          cd "${GITHUB_WORKSPACE}"

-          cd "${WORKING_DIR}"
-
-          if [ ! -f unittest.log ]; then
-              echo "unittest.log not found; embedded tests may not have run."
-              exit 0
-          fi
-
-          if ! grep -E "failed" unittest.log; then
-              echo "Log present but no failure lines found in unittest.log."
+          if [ -f unittest.log ]; then
+              if ! grep -E "failed" unittest.log | grep -vE "^I[0-9]|^[0-9]+> (ERR:|FTL:)"; then
+                  echo "unittest.log present but no failure lines found."
+              fi
+          elif [ -f build.log ]; then
+              # GCC/Clang emit "error:" (covers "fatal error:"); MSVC emits
+              # "error C####:", "error LNK####:", and "fatal error LNK####:".
+              # -A6 prints the lines that follow each match (source line, caret,
+              # notes, and the "N errors generated" tally) to capture the whole
+              # diagnostic block.
+              if ! grep -E -A6 "error:|error C[0-9]{4}|error LNK[0-9]{4}|fatal error" build.log; then
+                  echo "build.log present but no compile errors found."
+              fi
+          else
+              echo "unittest.log/build.log not found; something went wrong."
+              exit 1
          fi
      - name: Debug failure (Linux)
        if: ${{ failure() && runner.os == 'Linux' && !inputs.build_only }}
--- a/.github/workflows/reusable-clang-tidy.yml
+++ b/.github/workflows/reusable-clang-tidy.yml
@@ -34,7 +34,7 @@ jobs:
    needs: [determine-files]
    if: ${{ needs.determine-files.outputs.cpp_changed_files != '' || needs.determine-files.outputs.need_full_run == 'true' }}
    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-2e25435"
+    container: "ghcr.io/xrplf/xrpld/nix-debian:sha-40cdf49"
    permissions:
      contents: read
      issues: write
@@ -43,7 +43,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@ad188deb3dae79dc39816e16ddfdad1e06c6fab2
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
        with:
          enable_ccache: false

--- a/.github/workflows/reusable-package.yml
+++ b/.github/workflows/reusable-package.yml
@@ -30,7 +30,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.13"

--- a/.github/workflows/reusable-strategy-matrix.yml
+++ b/.github/workflows/reusable-strategy-matrix.yml
@@ -26,7 +26,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.13"

--- a/.github/workflows/reusable-upload-recipe.yml
+++ b/.github/workflows/reusable-upload-recipe.yml
@@ -40,7 +40,7 @@ defaults:
 jobs:
  upload:
    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-2e25435
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-40cdf49
    env:
      REMOTE_NAME: ${{ inputs.remote_name }}
      CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
--- a/.github/workflows/upload-conan-deps.yml
+++ b/.github/workflows/upload-conan-deps.yml
@@ -68,7 +68,7 @@ jobs:
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@ad188deb3dae79dc39816e16ddfdad1e06c6fab2
+        uses: XRPLF/actions/prepare-runner@e4b6449d55a61c002d7c3fdfa6c20f721ede0606
        with:
          enable_ccache: false

--- a/.gitignore
+++ b/.gitignore
@@ -81,6 +81,9 @@ DerivedData
 # Python
 __pycache__

+# Rust build artifacts.
+target/
+
 # Direnv's directory
 /.direnv

--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -55,7 +55,7 @@ repos:
        types_or: [c++, c]

  - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: dd18dad857d6133e90bbe478f4f2f22ec0030269 # frozen: v22.1.5
+    rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
    hooks:
      - id: clang-format
        args: [--style=file]
@@ -68,7 +68,7 @@ repos:
      - id: gersemi

  - repo: https://github.com/rbubley/mirrors-prettier
-    rev: 39e2973981e6d2f9b6c543b0086a2d2393abdc89 # frozen: v3.9.4
+    rev: 9337a74165b178ae2c766f60bee7252a0f06f3e8 # frozen: v3.9.5
    hooks:
      - id: prettier
        args: [--end-of-line=auto]
--- a/BoostToStdCoroutineSwitchPlan.md
+++ b/BoostToStdCoroutineSwitchPlan.md
--- a/BoostToStdCoroutineTaskList.md
+++ b/BoostToStdCoroutineTaskList.md
@@ -0,0 +1,142 @@
+# Boost.Coroutine to C++20 Migration — Task List
+
+> Parent document: [BoostToStdCoroutineSwitchPlan.md](BoostToStdCoroutineSwitchPlan.md)
+
+---
+
+## Milestone 1: New Coroutine Primitives
+
+- [ ] **1.1** Design `CoroTask<T>` class with `promise_type`
+  - Define `promise_type` with `initial_suspend`, `final_suspend`, `unhandled_exception`, `return_value`/`return_void`
+  - Implement `FinalAwaiter` for continuation support
+  - Implement move-only RAII handle wrapper
+  - Support both `CoroTask<T>` and `CoroTask<void>`
+
+- [ ] **1.2** Design and implement `JobQueueAwaiter`
+  - `await_suspend()` calls `jq_.addJob(type, name, [h]{ h.resume(); })`
+  - Handle `addJob()` failure (shutdown) — resume with error flag or throw
+  - Integrate `nSuspend_` counter increment/decrement
+
+- [ ] **1.3** Implement `LocalValues` swap in new coroutine resume path
+  - Before `handle.resume()`: save thread-local, install coroutine-local
+  - After `handle.resume()` returns: restore thread-local
+  - Ensure this works when coroutine migrates between threads
+
+- [ ] **1.4** Add `postCoroTask()` template to `JobQueue`
+  - Accept callable returning `CoroTask<void>`
+  - Schedule initial execution on JobQueue (mirror `postCoro()` behavior)
+  - Return a handle/shared_ptr for join/cancel
+
+- [ ] **1.5** Write unit tests (`src/test/core/CoroTask_test.cpp`)
+  - Test `CoroTask<void>` runs to completion
+  - Test `CoroTask<int>` returns value
+  - Test exception propagation across co_await
+  - Test coroutine destruction before completion
+  - Test `JobQueueAwaiter` schedules on correct thread
+  - Test `LocalValue` isolation across 4+ coroutines
+  - Test shutdown rejection (addJob returns false)
+  - Test `correct_order` equivalent (yield → join → post → complete)
+  - Test `incorrect_order` equivalent (post → yield → complete)
+  - Test multiple sequential co_await points
+
+- [ ] **1.6** Verify build on GCC 12+, Clang 16+
+- [ ] **1.7** Run ASAN + TSAN on new tests
+- [ ] **1.8** Run full `--unittest` suite (no regressions)
+- [ ] **1.9** Self-review and create PR #1
+
+---
+
+## Milestone 2: Entry Point Migration
+
+- [ ] **2.1** Migrate `ServerHandler::onRequest()` (`ServerHandler.cpp:287`)
+  - Replace `m_jobQueue.postCoro(jtCLIENT_RPC, ...)` with `postCoroTask()`
+  - Update lambda to return `CoroTask<void>` (add `co_return`)
+  - Update `processSession` to accept new coroutine type
+
+- [ ] **2.2** Migrate `ServerHandler::onWSMessage()` (`ServerHandler.cpp:325`)
+  - Replace `m_jobQueue.postCoro(jtCLIENT_WEBSOCKET, ...)` with `postCoroTask()`
+  - Update lambda signature
+
+- [ ] **2.3** Migrate `GRPCServer::CallData::process()` (`GRPCServer.cpp:102`)
+  - Replace `app_.getJobQueue().postCoro(JobType::jtRPC, ...)` with `postCoroTask()`
+  - Update `process(shared_ptr<Coro> coro)` overload signature
+
+- [ ] **2.4** Update `RPC::Context` (`Context.h:27`)
+  - Replace `std::shared_ptr<JobQueue::Coro> coro{}` with new coroutine wrapper type
+  - Ensure all code that accesses `context.coro` compiles
+
+- [ ] **2.5** Update `ServerHandler.h` signatures
+  - `processSession()` and `processRequest()` parameter types
+
+- [ ] **2.6** Update `GRPCServer.h` signatures
+  - `process()` method parameter types
+
+- [ ] **2.7** Run full `--unittest` suite
+- [ ] **2.8** Manual smoke test: HTTP + WS + gRPC RPC requests
+- [ ] **2.9** Run ASAN + TSAN
+- [ ] **2.10** Self-review and create PR #2
+
+---
+
+## Milestone 3: Handler Migration
+
+- [ ] **3.1** Migrate `doRipplePathFind()` (`RipplePathFind.cpp`)
+  - Replace `context.coro->yield()` with `co_await PathFindAwaiter{...}`
+  - Replace continuation lambda's `coro->post()` / `coro->resume()` with awaiter scheduling
+  - Handle shutdown case (post failure) in awaiter
+
+- [ ] **3.2** Create `PathFindAwaiter` (or use generic `JobQueueAwaiter`)
+  - Encapsulate the continuation + yield pattern from `RipplePathFind.cpp` lines 108-132
+
+- [ ] **3.3** Update `Path_test.cpp`
+  - Replace `postCoro` usage with `postCoroTask`
+  - Ensure `context.coro` usage matches new type
+
+- [ ] **3.4** Update `AMMTest.cpp`
+  - Replace `postCoro` usage with `postCoroTask`
+
+- [ ] **3.5** Rewrite `Coroutine_test.cpp` for new API
+  - `correct_order`: postCoroTask → co_await → join → resume → complete
+  - `incorrect_order`: post before yield equivalent
+  - `thread_specific_storage`: 4 coroutines with LocalValue isolation
+
+- [ ] **3.6** Update `JobQueue_test.cpp` `testPostCoro`
+  - Migrate to `postCoroTask` API
+
+- [ ] **3.7** Verify `ripple_path_find` works end-to-end with new coroutines
+- [ ] **3.8** Test shutdown-during-pathfind scenario
+- [ ] **3.9** Run full `--unittest` suite
+- [ ] **3.10** Run ASAN + TSAN
+- [ ] **3.11** Self-review and create PR #3
+
+---
+
+## Milestone 4: Cleanup & Validation
+
+- [ ] **4.1** Delete `include/xrpl/core/Coro.ipp`
+- [ ] **4.2** Remove from `JobQueue.h`:
+  - `#include <boost/coroutine2/all.hpp>`
+  - `struct Coro_create_t`
+  - `class Coro` (entire class)
+  - `postCoro()` template
+  - Comment block (lines 322-377) describing old race condition
+- [ ] **4.3** Update `cmake/deps/Boost.cmake`:
+  - Remove `coroutine` from `find_package(Boost REQUIRED COMPONENTS ...)`
+  - Remove `Boost::coroutine` from `target_link_libraries`
+- [ ] **4.4** Update `cmake/XrplInterface.cmake`:
+  - Remove `BOOST_COROUTINES2_NO_DEPRECATION_WARNING`
+- [ ] **4.5** Run memory benchmark
+  - Create N=1000 coroutines, compare RSS: before vs after
+  - Document results
+- [ ] **4.6** Run context switch benchmark
+  - 100K yield/resume cycles, compare latency: before vs after
+  - Document results
+- [ ] **4.7** Run RPC throughput benchmark
+  - Concurrent `ripple_path_find` requests, compare throughput
+  - Document results
+- [ ] **4.8** Run full `--unittest` suite
+- [ ] **4.9** Run ASAN, TSAN, UBSan
+  - Confirm `__asan_handle_no_return` warnings are gone
+- [ ] **4.10** Verify build on all supported compilers
+- [ ] **4.11** Self-review and create PR #4
+- [ ] **4.12** Document final benchmark results in PR description
--- a/4
+++ b/4
@@ -0,0 +1,4 @@
+# By default, anyone can review changes.
+
+# The CI tooling team should review changes to the CI configuration.
+/.github/ @XRPLF/ci-tooling
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -354,46 +354,6 @@ If you wish to automatically fix whatever clang-tidy finds _and_ is capable of f
 run-clang-tidy -p build -quiet -fix -allow-no-checks src tests
 ```

-## Telemetry span attribute naming
-
-OpenTelemetry span attribute keys follow these rules so they stay consistent
-across the code, the OTel collector, Tempo, Grafana dashboards, and docs. The
-constants in the `*SpanNames.h` headers are the single source of truth; every
-other layer must match them. A CI check enforces this end to end.
-
-1. Per-span unique attribute: bare field name — allowed when the field is
-   recorded by a single span/workflow, so the span name already supplies the
-   domain (e.g. `command`, `local`, `version` on `rpc.command` / `tx.process`).
-2. Shared attribute (same concept on more than one span): ONE key, reused
-   verbatim on every span that records it — the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Pick the name by the field's
-   meaning: a property of a domain object keeps that object's bare field name
-   (`ledger_hash`, `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a
-   field already qualified by a sub-kind keeps that qualifier on every emitter
-   (`proposal_trusted` on both `consensus.proposal.receive` and
-   `peer.proposal.receive`; `validation_trusted` likewise). Define it once in
-   the base `SpanNames.h` `namespace attr` block and re-export (`using`) it from
-   each domain header, so all emitters share the exact string.
-3. Collision qualifier: `<domain>_<field>` — only when a bare name would collide
-   with a DIFFERENT concept in the shared spanmetrics label space, or with the
-   OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`). This disambiguates distinct concepts
-   that share a word; it is NOT used to tag the same concept with the workflow
-   that emitted it — that is rule 2 (one shared name).
-4. Resource attribute: dotted `xrpl.<subsystem>.<field>` — reserved ONLY for
-   process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Never use the dotted `xrpl.` form for span attributes.
-5. Span names use `<subsystem>[.<component>]` (dotted). Only attribute _keys_
-   follow rules 1–4.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule above applies to xrpl-custom keys, not to OTel-standard
-conventions.
-
-Always reference the `*SpanNames.h` constants — never pass string literals as
-attribute keys or values to `setAttribute`/`addEvent`.
-
 ## Contracts and instrumentation

 We are using [Antithesis](https://antithesis.com/) for continuous fuzzing,
--- a/OpenTelemetryPlan/00-tracing-fundamentals.md
+++ b/OpenTelemetryPlan/00-tracing-fundamentals.md
@@ -1,565 +0,0 @@
-# Distributed Tracing Fundamentals
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Next**: [Architecture Analysis](./01-architecture-analysis.md)
-
---
-
-## What is Distributed Tracing?
-
-Distributed tracing is a method for tracking data objects as they flow through distributed systems. In a network like XRP Ledger, a single transaction touches multiple independent nodes—each with no shared memory or logging. Distributed tracing connects these dots.
-
-**Without tracing:** You see isolated logs on each node with no way to correlate them.
-
-**With tracing:** You see the complete journey of a transaction or an event across all nodes it touched.
-
---
-
-## Actors and Actions at a Glance
-
-### Actors
-
-| Who (Plain English)                            | Technical Term  |
-| ---------------------------------------------- | --------------- |
-| A single unit of work being tracked            | Span            |
-| The complete journey of a request              | Trace           |
-| Data that links spans across services          | Trace Context   |
-| Code that creates spans and propagates context | Instrumentation |
-| Service that receives and processes traces     | Collector       |
-| Storage and visualization system               | Backend (Tempo) |
-| Decision logic for which traces to keep        | Sampler         |
-
-### Actions
-
-| What Happens (Plain English)            | Technical Term          |
-| --------------------------------------- | ----------------------- |
-| Start tracking a new operation          | Create a Span           |
-| Connect a child operation to its parent | Set `parent_span_id`    |
-| Group all related operations together   | Share a `trace_id`      |
-| Pass tracking data between services     | Context Propagation     |
-| Decide whether to record a trace        | Sampling (Head or Tail) |
-| Send completed traces to storage        | Export (OTLP)           |
-
---
-
-## Core Concepts
-
-### 1. Trace
-
-A **trace** represents the entire journey of a request through the system. It has a unique `trace_id` that stays constant across all nodes.
-
-```
-Trace ID: abc123
-├── Node A: received transaction
-├── Node B: relayed transaction
-├── Node C: included in consensus
-└── Node D: applied to ledger
-```
-
-### 2. Span
-
-A **span** represents a single unit of work within a trace. Each span has:
-
-| Attribute        | Description                      | Example                    |
-| ---------------- | -------------------------------- | -------------------------- |
-| `trace_id`       | Identifies the trace             | `event123`                 |
-| `span_id`        | Unique identifier                | `span456`                  |
-| `parent_span_id` | Parent span (if any)             | `p_span123`                |
-| `name`           | Operation name                   | `rpc.submit`               |
-| `start_time`     | When work began (local time)     | `2024-01-15T10:30:00Z`     |
-| `end_time`       | When work completed (local time) | `2024-01-15T10:30:00.050Z` |
-| `attributes`     | Key-value metadata               | `tx_hash=ABC...`           |
-| `status`         | OK, ERROR MSG                    | `OK`                       |
-
-### 3. Trace Context
-
-**Trace context** is the data that propagates between services to link spans together. It contains:
-
- `trace_id` - The trace this span belongs to
- `span_id` - The current span (becomes parent for child spans)
- `trace_flags` - Sampling decisions
-
---
-
-## How Spans Form a Trace
-
-Spans have parent-child relationships forming a tree structure:
-
-```mermaid
-flowchart TB
-    subgraph trace["Trace: abc123"]
-        A["tx.submit<br/>span_id: 001<br/>50ms"] --> B["tx.validate<br/>span_id: 002<br/>5ms"]
-        A --> C["tx.relay<br/>span_id: 003<br/>10ms"]
-        A --> D["tx.apply<br/>span_id: 004<br/>30ms"]
-        D --> E["ledger.update<br/>span_id: 005<br/>20ms"]
-    end
-
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style D fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style E fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **tx.submit (blue, root)**: The top-level span representing the entire transaction submission; all other spans are its descendants.
- **tx.validate, tx.relay, tx.apply (green)**: Direct children of tx.submit, representing the three main stages -- validation, relay to peers, and application to the ledger.
- **ledger.update (red)**: A grandchild span nested under tx.apply, representing the actual ledger state mutation triggered by applying the transaction.
- **Arrows (parent to child)**: Each arrow indicates a parent-child span relationship where the parent's completion depends on the child finishing.
-
-The same trace visualized as a **timeline (Gantt chart)**:
-
-```
-Time →   0ms    10ms    20ms    30ms    40ms    50ms
-         ├───────────────────────────────────────────┤
-tx.submit│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         ├─────┤
-tx.valid │▓▓▓▓▓│
-         │     ├──────────┤
-tx.relay │     │▓▓▓▓▓▓▓▓▓▓│
-         │               ├────────────────────────────┤
-tx.apply │               │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-         │                         ├──────────────────┤
-ledger   │                         │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
-```
-
---
-
-## Span Relationships
-
-Spans don't always form simple parent-child trees. Distributed tracing defines several relationship types to capture different causal patterns:
-
-### 1. Parent-Child (ChildOf)
-
-The default relationship. The parent span **depends on** or **contains** the child span. The child runs within the scope of the parent.
-
-```
-tx.submit (parent)
-├── tx.validate (child)     ← parent waits for this
-├── tx.relay (child)        ← parent waits for this
-└── tx.apply (child)        ← parent waits for this
-```
-
-**When to use:** Synchronous calls, nested operations, any case where the parent's completion depends on the child.
-
-### 2. Follows-From
-
-A causal relationship where the first span **triggers** the second, but does **not wait** for it. The originator fires and moves on.
-
-```
-Time →
-
-tx.receive [=======]
-                     ↓ triggers (follows-from)
-              tx.relay   [===========]   ← runs independently
-```
-
-**When to use:** Asynchronous jobs, queued work, fire-and-forget patterns. For example, a node receives a transaction and queues it for relay — the relay span _follows from_ the receive span but the receiver doesn't wait for relaying to complete.
-
-> **OpenTracing** defined `FollowsFrom` as a first-class reference type alongside `ChildOf`.
-> **OpenTelemetry** represents this using **Span Links** with descriptive attributes instead (see below).
-
-### 3. Span Links (Cross-Trace and Non-Hierarchical)
-
-Links connect spans that are **causally related but not in a parent-child hierarchy**. Unlike parent-child, links can cross trace boundaries.
-
-```
-Trace A                          Trace B
-──────                           ──────
-batch.schedule                   batch.execute
-├─ item.enqueue (span X)    ┌──► process.item
-├─ item.enqueue (span Y) ───┤    (links to X, Y, Z)
-├─ item.enqueue (span Z)    └──►
-```
-
-**Use cases:**
-
-| Pattern              | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| **Batch processing** | A batch span links back to all individual spans that contributed to it      |
-| **Fan-in**           | An aggregation span links to the multiple producer spans it merges          |
-| **Fan-out**          | Multiple downstream spans link back to the single span that triggered them  |
-| **Async handoff**    | A deferred job links back to the request that queued it (follows-from)      |
-| **Cross-trace**      | Correlating spans across independent traces (e.g., retries, related events) |
-
-**Link structure:** Each link carries the target span's context plus optional attributes:
-
-```
-Link {
-    trace_id:   <target trace>
-    span_id:    <target span>
-    attributes: { "link.description": "triggered by batch scheduler" }
-}
-```
-
-### Relationship Summary
-
-```mermaid
-flowchart LR
-    subgraph parent_child["Parent-Child"]
-        direction TB
-        P["Parent"] --> C["Child"]
-    end
-
-    subgraph follows_from["Follows-From"]
-        direction TB
-        A["Span A"] -.->|triggers| B["Span B"]
-    end
-
-    subgraph links["Span Links"]
-        direction TB
-        X["Span X\n(Trace 1)"] -.-|link| Y["Span Y\n(Trace 2)"]
-    end
-
-    parent_child ~~~ follows_from ~~~ links
-
-    style P fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style A fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style B fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style X fill:#4a148c,stroke:#38006b,color:#ffffff
-    style Y fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-| Relationship     | Same Trace? | Dependency?                | OTel Mechanism    |
-| ---------------- | ----------- | -------------------------- | ----------------- |
-| **Parent-Child** | Yes         | Parent depends on child    | `parent_span_id`  |
-| **Follows-From** | Usually     | Causal but no dependency   | Link + attributes |
-| **Span Link**    | Either      | Correlation, no dependency | Link + attributes |
-
---
-
-## Trace ID Generation
-
-A `trace_id` is a 128-bit (16-byte) identifier that groups all spans belonging to one logical operation. How it's generated determines how easily you can find and correlate traces later.
-
-### General Approaches
-
-#### 1. Random (W3C Default)
-
-Generate a random 128-bit ID when a trace starts. Standard approach for most services.
-
-```
-trace_id = random_128_bits()
-```
-
-| Pros                        | Cons                                          |
-| --------------------------- | --------------------------------------------- |
-| Simple, standard            | No natural correlation to domain events       |
-| Guaranteed unique per trace | If propagation is lost, trace is broken       |
-| Works with all OTel tooling | "Find trace for TX abc" requires index lookup |
-
-#### 2. Deterministic (Derived from Domain Data)
-
-Compute the trace_id from a hash of a natural identifier. Every node independently derives the **same** trace_id for the same event.
-
-```
-trace_id = SHA-256(domain_identifier)[0:16]   // truncate to 128 bits
-```
-
-| Pros                                                | Cons                                                       |
-| --------------------------------------------------- | ---------------------------------------------------------- |
-| Propagation-resilient — same ID computed everywhere | Same event processed twice (retry) shares trace_id         |
-| Natural search — domain ID maps directly to trace   | Non-standard (tooling assumes random)                      |
-| No coordination needed between nodes                | 256→128 bit truncation (collision risk negligible at ~2⁶⁴) |
-
-#### 3. Hybrid (Deterministic Prefix + Random Suffix)
-
-First 8 bytes derived from domain data, last 8 bytes random.
-
-```
-trace_id = SHA-256(domain_identifier)[0:8] || random_64_bits()
-```
-
-| Pros                                        | Cons                                     |
-| ------------------------------------------- | ---------------------------------------- |
-| Prefix search: "find all traces for TX abc" | Must propagate to maintain full trace_id |
-| Unique per processing instance              | More complex generation logic            |
-| Retries get distinct trace_ids              | Partial correlation only (prefix match)  |
-
-### XRPL Workflow Analysis
-
-XRPL has a unique advantage: its core workflows produce **globally unique 256-bit hashes** that are known on every node. This makes deterministic trace_id generation practical in ways most systems can't achieve.
-
-#### Natural Identifiers by Workflow
-
-| Workflow            | Natural Identifier                | Size       | Known at Start?               | Same on All Nodes?               |
-| ------------------- | --------------------------------- | ---------- | ----------------------------- | -------------------------------- |
-| **Transaction**     | Transaction hash (`tid_`)         | 256-bit    | Yes — computed before signing | Yes — hash of canonical tx data  |
-| **Consensus round** | Previous ledger hash + ledger seq | 256+32 bit | Yes — known when round opens  | Yes — all validators agree       |
-| **Validation**      | Ledger hash being validated       | 256-bit    | Yes — from consensus result   | Yes — same closed ledger         |
-| **Ledger catch-up** | Target ledger hash                | 256-bit    | Yes — we know what to fetch   | Yes — identifies ledger globally |
-
-#### Where These Identifiers Live in Code
-
-```
-Transaction:     STTx::getTransactionID()     → uint256 tid_
-                 TMTransaction::rawTransaction → recompute hash from bytes
-
-Consensus:       ConsensusProposal::prevLedger_ → uint256 (previous ledger hash)
-                 ConsensusProposal::position_   → uint256 (TxSet hash)
-                 LedgerHeader::seq              → uint32_t (ledger sequence)
-
-Validation:      STValidation::getLedgerHash()  → uint256
-                 STValidation::getNodeID()      → NodeID (160-bit)
-
-Ledger fetch:    InboundLedger constructor      → uint256 hash, uint32_t seq
-                 TMGetLedger::ledgerHash        → bytes (uint256)
-```
-
-### Recommended Strategy: Workflow-Scoped Deterministic
-
-Each workflow type derives its trace_id from its natural domain identifier:
-
-```
-Transaction trace:   trace_id = SHA-256("tx"    || tx_hash)[0:16]
-Consensus trace:     trace_id = SHA-256("cons"  || prev_ledger_hash || ledger_seq)[0:16]
-Ledger catch-up:     trace_id = SHA-256("fetch" || target_ledger_hash)[0:16]
-```
-
-The string prefix (`"tx"`, `"cons"`, `"fetch"`) prevents collisions between workflows that might share underlying hashes.
-
-**Why this works for XRPL:**
-
-1. **Propagation-resilient** — Even if a P2P message drops trace context, every node independently computes the same trace_id from the same tx_hash or ledger_hash. Spans still correlate.
-
-2. **Zero-cost search** — "Show me the trace for transaction ABC" becomes a direct lookup: compute `SHA-256("tx" || ABC)[0:16]` and query. No secondary index needed.
-
-3. **Cross-workflow linking via Span Links** — A consensus trace links to individual transaction traces. A validation span links to the consensus trace. This connects the full picture without forcing everything into one giant trace.
-
-### Cross-Workflow Correlation
-
-Each workflow gets its own trace. Span Links tie them together:
-
-```mermaid
-flowchart TB
-    subgraph tx_trace["Transaction Trace"]
-        direction LR
-        Tn["trace_id = f(tx_hash)"]:::note --> T1["tx.receive"] --> T2["tx.validate"] --> T3["tx.relay"]
-    end
-
-    subgraph cons_trace["Consensus Trace"]
-        direction LR
-        Cn["trace_id = f(prev_ledger, seq)"]:::note --> C1["cons.open"] --> C2["cons.propose"] --> C3["cons.accept"]
-    end
-
-    subgraph val_trace["Validation"]
-        direction LR
-        Vn["spans within consensus trace"]:::note --> V1["val.create"] --> V2["val.broadcast"]
-    end
-
-    subgraph fetch_trace["Catch-Up Trace"]
-        direction LR
-        Fn["trace_id = f(ledger_hash)"]:::note --> F1["fetch.request"] --> F2["fetch.receive"] --> F3["fetch.apply"]
-    end
-
-    C1 -.-|"span link\n(tx traces)"| T3
-    C3 --> V1
-    F1 -.-|"span link\n(target ledger)"| C3
-
-    classDef note fill:none,stroke:#888,stroke-dasharray:5 5,color:#333,font-style:italic
-    style T1 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T2 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style T3 fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style C1 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C2 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style C3 fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style V1 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style V2 fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style F1 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F2 fill:#4a148c,stroke:#38006b,color:#ffffff
-    style F3 fill:#4a148c,stroke:#38006b,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **Transaction Trace (blue)**: An independent trace whose `trace_id` is deterministically derived from the transaction hash. Contains receive, validate, and relay spans.
- **Consensus Trace (green)**: An independent trace whose `trace_id` is derived from the previous ledger hash and sequence number. Covers the open, propose, and accept phases.
- **Validation (red)**: Validation spans live within the consensus trace (not a separate trace). They are created after the accept phase completes.
- **Catch-Up Trace (purple)**: An independent trace for ledger acquisition, derived from the target ledger hash. Used when a node is behind and fetching missing ledgers.
- **Dotted arrows (span links)**: Cross-trace correlations. Consensus links to transaction traces it included; catch-up links to the consensus trace that produced the target ledger.
- **Solid arrow (C3 to V1)**: A parent-child relationship -- validation spans are direct children of the consensus accept span within the same trace.
-
-**How a query flows:**
-
-```
-"Why was TX abc slow?"
-  1. Compute trace_id = SHA-256("tx" || abc)[0:16]
-  2. Find transaction trace → see it was included in consensus round N
-  3. Follow span link → consensus trace for round N
-  4. See which phase was slow (propose? accept?)
-  5. If a node was catching up, follow link → catch-up trace
-```
-
-### Trade-offs to Consider
-
-| Concern                       | Mitigation                                                                                                                    |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| **Retries get same trace_id** | Add `attempt` attribute to root span; spans have unique span_ids and timestamps                                               |
-| **256→128 bit truncation**    | Birthday-bound collision at ~2⁶⁴ operations — negligible for XRPL's throughput                                                |
-| **Non-standard generation**   | OTel spec allows any 16-byte non-zero value; tooling works on the hex string                                                  |
-| **Hash computation cost**     | SHA-256 is ~0.3μs per call; XRPL already computes these hashes for other purposes                                             |
-| **Late-binding identifiers**  | Ledger hash isn't known until after consensus — validation spans use ledger_seq as fallback, then link to the consensus trace |
-
---
-
-## Distributed Traces Across Nodes
-
-In distributed systems like xrpld, traces span **multiple independent nodes**. The trace context must be propagated in network messages:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant NodeA as Node A
-    participant NodeB as Node B
-    participant NodeC as Node C
-
-    Client->>NodeA: Submit TX<br/>(no trace context)
-
-    Note over NodeA: Creates new trace<br/>trace_id: abc123<br/>span: tx.receive
-
-    NodeA->>NodeB: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeB: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    NodeA->>NodeC: Relay TX<br/>(trace_id: abc123, parent: 001)
-
-    Note over NodeC: Creates child span<br/>span: tx.relay<br/>parent_span_id: 001
-
-    Note over NodeA,NodeC: All spans share trace_id: abc123<br/>enabling correlation across nodes
-```
-
-**Reading the diagram:**
-
- **Client**: The external entity that submits a transaction. It does not carry trace context -- the trace originates at the first node.
- **Node A**: The entry point that creates a new trace (trace_id: abc123) and the root span `tx.receive`. It relays the transaction to peers with trace context attached.
- **Node B and Node C**: Peer nodes that receive the relayed transaction along with the propagated trace context. Each creates a child span under Node A's span, preserving the same `trace_id`.
- **Arrows with trace context**: The relay messages carry `trace_id` and `parent_span_id`, allowing each downstream node to link its spans back to the originating span on Node A.
-
---
-
-## Context Propagation
-
-For traces to work across nodes, **trace context must be propagated** in messages.
-
-### What's in the Context (~26 bytes)
-
-| Field         | Size     | Description                                             |
-| ------------- | -------- | ------------------------------------------------------- |
-| `trace_id`    | 16 bytes | Identifies the entire trace (constant across all nodes) |
-| `span_id`     | 8 bytes  | The sender's current span (becomes parent on receiver)  |
-| `trace_flags` | 1 byte   | Sampling decision (bit 0 = sampled; bits 1-7 reserved)  |
-| `trace_state` | variable | Optional vendor-specific data (typically omitted)       |
-
-### How span_id Changes at Each Hop
-
-Only **one** `span_id` travels in the context - the sender's current span. Each node:
-
-1. Extracts the received `span_id` and uses it as the `parent_span_id`
-2. Creates a **new** `span_id` for its own span
-3. Sends its own `span_id` as the parent when forwarding
-
-```
-Node A                      Node B                      Node C
-──────                      ──────                      ──────
-
-Span AAA                    Span BBB                    Span CCC
-   │                           │                           │
-   ▼                           ▼                           ▼
-Context out:                Context out:                Context out:
-├─ trace_id: abc123         ├─ trace_id: abc123         ├─ trace_id: abc123
-├─ span_id: AAA ──────────► ├─ span_id: BBB ──────────► ├─ span_id: CCC ──────►
-└─ flags: 01                └─ flags: 01                └─ flags: 01
-                               │                           │
-                          parent = AAA               parent = BBB
-```
-
-The `trace_id` stays constant, but `span_id` **changes at every hop** to maintain the parent-child chain.
-
-### Propagation Formats
-
-There are two patterns:
-
-### HTTP/RPC Headers (W3C Trace Context)
-
-```
-traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
-             │  │                                │                │
-             │  │                                │                └── Flags (sampled)
-             │  │                                └── Parent span ID (16 hex)
-             │  └── Trace ID (32 hex)
-             └── Version
-```
-
-### Protocol Buffers (xrpld P2P messages)
-
-xrpld P2P messages such as `TMTransaction` carry the trace context in two added byte fields alongside the existing payload: `trace_parent` holds the W3C traceparent (`trace_id`, `span_id`, and `trace_flags`), and `trace_state` holds the optional W3C tracestate. Together they propagate the trace across the P2P boundary so a receiving node can attach its spans to the sender's span.
-
---
-
-## Sampling
-
-Not every trace needs to be recorded. **Sampling** reduces overhead:
-
-### Head Sampling (at trace start)
-
-```
-Request arrives → Random N% chance → Record or skip entire trace
-```
-
- ✅ Low overhead
- ❌ May miss interesting traces
-
-> **xrpld note**: xrpld intentionally fixes head sampling at 100% (sample
-> everything) and does not expose a configurable ratio. A per-node ratio
-> would let different nodes make divergent keep/drop decisions for the same
-> distributed trace, producing broken/partial traces. xrpld uses a
-> `ParentBased` sampler so spans with a remote parent honor the upstream
-> decision. Volume reduction is delegated to collector-side tail sampling.
-
-### Tail Sampling (after trace completes)
-
-```
-Trace completes → Collector evaluates:
-                  - Error? → KEEP
-                  - Slow? → KEEP
-                  - Normal? → Sample 10%
-```
-
- ✅ Never loses important traces
- ❌ Higher memory usage at collector
-
---
-
-## Key Benefits for xrpld
-
-| Challenge                          | How Tracing Helps                        |
-| ---------------------------------- | ---------------------------------------- |
-| "Where is my transaction?"         | Follow trace across all nodes it touched |
-| "Why was consensus slow?"          | See timing breakdown of each phase       |
-| "Which node is the bottleneck?"    | Compare span durations across nodes      |
-| "What happened during the outage?" | Correlate errors across the network      |
-
---
-
-## Glossary
-
-| Term                 | Definition                                                          |
-| -------------------- | ------------------------------------------------------------------- |
-| **Trace**            | Complete journey of a request, identified by `trace_id`             |
-| **Span**             | Single operation within a trace                                     |
-| **Parent-Child**     | Span relationship where the parent depends on the child             |
-| **Follows-From**     | Causal relationship where originator doesn't wait for the result    |
-| **Span Link**        | Non-hierarchical connection between spans, possibly across traces   |
-| **Deterministic ID** | Trace ID derived from domain data (e.g., tx_hash) instead of random |
-| **Context**          | Data propagated between services (`trace_id`, `span_id`, flags)     |
-| **Instrumentation**  | Code that creates spans and propagates context                      |
-| **Collector**        | Service that receives, processes, and exports traces                |
-| **Backend**          | Storage/visualization system (Tempo)                                |
-| **Head Sampling**    | Sampling decision at trace start                                    |
-| **Tail Sampling**    | Sampling decision after trace completes                             |
-
---
-
-_Next: [Architecture Analysis](./01-architecture-analysis.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/01-architecture-analysis.md
+++ b/OpenTelemetryPlan/01-architecture-analysis.md
@@ -1,467 +0,0 @@
-# Architecture Analysis
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Design Decisions](./02-design-decisions.md) | [Implementation Strategy](./03-implementation-strategy.md)
-
---
-
-## 1.1 Current xrpld Architecture Overview
-
-> **WS** = WebSocket | **UNL** = Unique Node List | **TxQ** = Transaction Queue | **StatsD** = Statistics Daemon
-
-The xrpld node software consists of several interconnected components that need instrumentation for distributed tracing:
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        subgraph services["Core Services"]
-            RPC["RPC Server<br/>(HTTP/WS/gRPC)"]
-            Overlay["Overlay<br/>(P2P Network)"]
-            Consensus["Consensus<br/>(RCLConsensus)"]
-            ValidatorList["ValidatorList<br/>(UNL Mgmt)"]
-        end
-
-        JobQueue["JobQueue<br/>(Thread Pool)"]
-
-        subgraph processing["Processing Layer"]
-            NetworkOPs["NetworkOPs<br/>(Tx Processing)"]
-            LedgerMaster["LedgerMaster<br/>(Ledger Mgmt)"]
-            NodeStore["NodeStore<br/>(Database)"]
-            InboundLedgers["InboundLedgers<br/>(Ledger Sync)"]
-        end
-
-        subgraph appservices["Application Services"]
-            PathFind["PathFinding<br/>(Payment Paths)"]
-            TxQ["TxQ<br/>(Fee Escalation)"]
-            LoadMgr["LoadManager<br/>(Fee/Load)"]
-        end
-
-        subgraph observability["Existing Observability"]
-            PerfLog["PerfLog<br/>(JSON)"]
-            Insight["Insight<br/>(StatsD)"]
-            Logging["Logging<br/>(Journal)"]
-        end
-
-        services --> JobQueue
-        JobQueue --> processing
-        JobQueue --> appservices
-    end
-
-    style xrpld fill:#424242,stroke:#212121,color:#ffffff
-    style services fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style processing fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style appservices fill:#6a1b9a,stroke:#4a148c,color:#ffffff
-    style observability fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **Core Services (blue)**: The entry points into xrpld -- RPC Server handles client requests, Overlay manages peer-to-peer networking, Consensus drives agreement, and ValidatorList manages trusted validators.
- **JobQueue (center)**: The asynchronous thread pool that decouples Core Services from the Processing and Application layers. All work flows through it.
- **Processing Layer (green)**: Core business logic -- NetworkOPs processes transactions, LedgerMaster manages ledger state, NodeStore handles persistence, and InboundLedgers synchronizes missing data.
- **Application Services (purple)**: Higher-level features -- PathFinding computes payment routes, TxQ manages fee-based queuing, and LoadManager tracks server load.
- **Existing Observability (orange)**: The current monitoring stack (PerfLog, Insight, Journal logging) that OpenTelemetry will complement, not replace.
- **Arrows (Services to JobQueue to layers)**: Work originates at Core Services, is enqueued onto the JobQueue, and dispatched to Processing or Application layers for execution.
-
---
-
-## 1.1.1 Actors and Actions
-
-### Actors
-
-| Who (Plain English)                       | Technical Term             |
-| ----------------------------------------- | -------------------------- |
-| Network node running XRPL software        | xrpld node                 |
-| External client submitting requests       | RPC Client                 |
-| Network neighbor sharing data             | Peer (PeerImp)             |
-| Request handler for client queries        | RPC Server (ServerHandler) |
-| Command executor for specific RPC methods | RPCHandler                 |
-| Agreement process between nodes           | Consensus (RCLConsensus)   |
-| Transaction processing coordinator        | NetworkOPs                 |
-| Background task scheduler                 | JobQueue                   |
-| Ledger state manager                      | LedgerMaster               |
-| Payment route calculator                  | PathFinding (Pathfinder)   |
-| Transaction waiting room                  | TxQ (Transaction Queue)    |
-| Fee adjustment system                     | LoadManager                |
-| Trusted validator list manager            | ValidatorList              |
-| Protocol upgrade tracker                  | AmendmentTable             |
-| Ledger state hash tree                    | SHAMap                     |
-| Persistent key-value storage              | NodeStore                  |
-
-### Actions
-
-| What Happens (Plain English)                   | Technical Term         |
-| ---------------------------------------------- | ---------------------- |
-| Client sends a request to a node               | `rpc.request`          |
-| Node executes a specific RPC command           | `rpc.command.*`        |
-| Node receives a transaction from a peer        | `tx.receive`           |
-| Node checks if a transaction is valid          | `tx.validate`          |
-| Node forwards a transaction to neighbors       | `tx.relay`             |
-| Nodes agree on which transactions to include   | `consensus.round`      |
-| Consensus progresses through phases            | `consensus.phase.*`    |
-| Node builds a new confirmed ledger             | `ledger.build`         |
-| Node fetches missing ledger data from peers    | `ledger.acquire`       |
-| Node computes payment routes                   | `pathfind.compute`     |
-| Node queues a transaction for later processing | `txq.enqueue`          |
-| Node increases fees due to high load           | `fee.escalate`         |
-| Node fetches the latest trusted validator list | `validator.list.fetch` |
-| Node votes on a protocol amendment             | `amendment.vote`       |
-| Node synchronizes state tree data              | `shamap.sync`          |
-
---
-
-## 1.2 Key Components for Instrumentation
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-| Component          | Location                                   | Purpose                  | Trace Value                      |
-| ------------------ | ------------------------------------------ | ------------------------ | -------------------------------- |
-| **Overlay**        | `src/xrpld/overlay/`                       | P2P communication        | Message propagation timing       |
-| **PeerImp**        | `src/xrpld/overlay/detail/PeerImp.cpp`     | Individual peer handling | Per-peer latency                 |
-| **RCLConsensus**   | `src/xrpld/app/consensus/RCLConsensus.cpp` | Consensus algorithm      | Round timing, phase analysis     |
-| **NetworkOPs**     | `src/xrpld/app/misc/NetworkOPs.cpp`        | Transaction processing   | Tx lifecycle tracking            |
-| **ServerHandler**  | `src/xrpld/rpc/detail/ServerHandler.cpp`   | RPC entry point          | Request latency                  |
-| **RPCHandler**     | `src/xrpld/rpc/detail/RPCHandler.cpp`      | Command execution        | Per-command timing               |
-| **JobQueue**       | `src/xrpl/core/JobQueue.h`                 | Async task execution     | Queue wait times                 |
-| **PathFinding**    | `src/xrpld/app/paths/`                     | Payment path computation | Path latency, cache hits         |
-| **TxQ**            | `src/xrpld/app/misc/TxQ.cpp`               | Transaction queue/fees   | Queue depth, eviction rates      |
-| **LoadManager**    | `src/xrpld/app/main/LoadManager.cpp`       | Fee escalation/load      | Fee levels, load factors         |
-| **InboundLedgers** | `src/xrpld/app/ledger/InboundLedgers.cpp`  | Ledger acquisition       | Sync time, peer reliability      |
-| **ValidatorList**  | `src/xrpld/app/misc/ValidatorList.cpp`     | UNL management           | List freshness, fetch failures   |
-| **AmendmentTable** | `src/xrpld/app/misc/AmendmentTable.cpp`    | Protocol amendments      | Voting status, activation events |
-| **SHAMap**         | `src/xrpld/shamap/`                        | State hash tree          | Sync speed, missing nodes        |
-
---
-
-## 1.3 Transaction Flow Diagram
-
-Transaction flow spans multiple nodes in the network. Each node creates linked spans to form a distributed trace:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant PeerA as Peer A (Receive)
-    participant PeerB as Peer B (Relay)
-    participant PeerC as Peer C (Validate)
-
-    Client->>PeerA: 1. Submit TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerA: tx.receive SPAN START
-        PeerA->>PeerA: HashRouter Deduplication
-        PeerA->>PeerA: tx.validate (child span)
-    end
-
-    PeerA->>PeerB: 2. Relay TX (with trace ctx)
-
-    rect rgb(230, 245, 255)
-        Note over PeerB: tx.receive (linked span)
-    end
-
-    PeerB->>PeerC: 3. Relay TX
-
-    rect rgb(230, 245, 255)
-        Note over PeerC: tx.receive (linked span)
-        PeerC->>PeerC: tx.process
-    end
-
-    Note over Client,PeerC: DISTRIBUTED TRACE (same trace_id: abc123)
-```
-
-**Reading the diagram:**
-
- **Client**: The external entity that submits a transaction to Peer A. It has no trace context -- the trace starts at the first node.
- **Peer A (Receive)**: The entry node that creates the root span `tx.receive`, runs HashRouter deduplication to avoid processing duplicates, and creates a child `tx.validate` span.
- **Peer A to Peer B arrow**: The relay message carries trace context (trace_id + parent span_id), enabling Peer B to create a linked span under the same trace.
- **Peer B (Relay)**: Receives the transaction and trace context, creates a `tx.receive` span linked to Peer A's trace, then relays onward.
- **Peer C (Validate)**: Final hop in this example. Creates a linked `tx.receive` span and runs `tx.process` to fully process the transaction.
- **Blue rectangles**: Highlight the span boundaries on each node, showing where instrumentation creates and closes spans.
-
-### Trace Structure
-
-```
-trace_id: abc123
-├── span: tx.receive (Peer A)
-│   ├── span: tx.validate
-│   └── span: tx.relay
-├── span: tx.receive (Peer B) [parent: Peer A]
-│   └── span: tx.relay
-└── span: tx.receive (Peer C) [parent: Peer B]
-    └── span: tx.process
-```
-
---
-
-## 1.4 Consensus Round Flow
-
-Consensus rounds are multi-phase operations that benefit significantly from tracing:
-
-```mermaid
-flowchart TB
-    subgraph round["consensus.round (root span)"]
-        attrs["Attributes:<br/>ledger_seq = 12345678<br/>consensus_mode = proposing<br/>proposers = 35"]
-
-        subgraph open["consensus.phase.open"]
-            open_desc["Duration: ~3s<br/>Waiting for transactions"]
-        end
-
-        subgraph establish["consensus.phase.establish"]
-            est_attrs["proposals_received = 28<br/>disputes_resolved = 3"]
-            est_children["├── consensus.proposal.receive (×28)<br/>├── consensus.proposal.send (×1)<br/>└── consensus.dispute.resolve (×3)"]
-        end
-
-        subgraph accept["consensus.phase.accept"]
-            acc_attrs["transactions_applied = 150<br/>ledger_hash = DEF456..."]
-            acc_children["├── ledger.build<br/>└── ledger.validate"]
-        end
-
-        attrs --> open
-        open --> establish
-        establish --> accept
-    end
-
-    style round fill:#f57f17,stroke:#e65100,color:#ffffff
-    style open fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style establish fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style accept fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **consensus.round (orange, root span)**: The top-level span encompassing the entire consensus round, with attributes like ledger sequence, mode, and proposer count.
- **consensus.phase.open (blue)**: The first phase where the node waits (~3s) to collect incoming transactions before proposing.
- **consensus.phase.establish (green)**: The negotiation phase where validators exchange proposals, resolve disputes, and converge on a transaction set. Child spans track each proposal received/sent and each dispute resolved.
- **consensus.phase.accept (pink)**: The final phase where the agreed transaction set is applied, a new ledger is built, and the ledger is validated. Child spans cover `ledger.build` and `ledger.validate`.
- **Arrows (open to establish to accept)**: The sequential flow through the three consensus phases. Each phase must complete before the next begins.
-
---
-
-## 1.5 RPC Request Flow
-
-> **WS** = WebSocket
-
-RPC requests support W3C Trace Context headers for distributed tracing across services:
-
-```mermaid
-flowchart TB
-    subgraph request["rpc.request (root span)"]
-        http["HTTP Request — POST /<br/>traceparent:<br/>00-abc123...-def456...-01"]
-
-        attrs["Attributes:<br/>http.method = POST<br/>net.peer.ip = 192.168.1.100<br/>command = submit"]
-
-        subgraph enqueue["jobqueue.enqueue"]
-            job_attr["job_type = jtCLIENT_RPC"]
-        end
-
-        subgraph command["rpc.command.submit"]
-            cmd_attrs["version = 2<br/>rpc_role = user"]
-            cmd_children["├── tx.deserialize<br/>├── tx.validate_local<br/>└── tx.submit_to_network"]
-        end
-
-        response["Response: 200 OK<br/>Duration: 45ms"]
-
-        http --> attrs
-        attrs --> enqueue
-        enqueue --> command
-        command --> response
-    end
-
-    style request fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style enqueue fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style command fill:#e65100,stroke:#bf360c,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **rpc.request (green, root span)**: The outermost span representing the full RPC request lifecycle, from HTTP receipt to response. Carries the W3C `traceparent` header for distributed tracing.
- **HTTP Request node**: Shows the incoming POST request with its `traceparent` header and extracted attributes (method, peer IP, command name).
- **jobqueue.enqueue (blue)**: The span covering the asynchronous handoff from the RPC thread to the JobQueue worker thread. The trace context is preserved across this async boundary.
- **rpc.command.submit (orange)**: The span for the actual command execution, with child spans for deserialization, local validation, and network submission.
- **Response node**: The final output with HTTP status and total duration, marking the end of the root span.
- **Arrows (top to bottom)**: The sequential processing pipeline -- receive request, extract attributes, enqueue job, execute command, return response.
-
---
-
-## 1.6 Key Trace Points
-
-> **TxQ** = Transaction Queue
-
-The following table identifies priority instrumentation points across the codebase:
-
-| Category        | Span Name              | File                   | Method                  | Priority |
-| --------------- | ---------------------- | ---------------------- | ----------------------- | -------- |
-| **Transaction** | `tx.receive`           | `PeerImp.cpp`          | `handleTransaction()`   | High     |
-| **Transaction** | `tx.validate`          | `NetworkOPs.cpp`       | `processTransaction()`  | High     |
-| **Transaction** | `tx.process`           | `NetworkOPs.cpp`       | `doTransactionSync()`   | High     |
-| **Transaction** | `tx.relay`             | `OverlayImpl.cpp`      | `relay()`               | Medium   |
-| **Consensus**   | `consensus.round`      | `RCLConsensus.cpp`     | `startRound()`          | High     |
-| **Consensus**   | `consensus.phase.*`    | `Consensus.h`          | `timerEntry()`          | High     |
-| **Consensus**   | `consensus.proposal.*` | `RCLConsensus.cpp`     | `peerProposal()`        | Medium   |
-| **RPC**         | `rpc.request`          | `ServerHandler.cpp`    | `onRequest()`           | High     |
-| **RPC**         | `rpc.command.*`        | `RPCHandler.cpp`       | `doCommand()`           | High     |
-| **Peer**        | `peer.connect`         | `OverlayImpl.cpp`      | `onHandoff()`           | Low      |
-| **Peer**        | `peer.message.*`       | `PeerImp.cpp`          | `onMessage()`           | Low      |
-| **Ledger**      | `ledger.acquire`       | `InboundLedgers.cpp`   | `acquire()`             | Medium   |
-| **Ledger**      | `ledger.build`         | `RCLConsensus.cpp`     | `buildLCL()`            | High     |
-| **PathFinding** | `pathfind.request`     | `PathRequest.cpp`      | `doUpdate()`            | High     |
-| **PathFinding** | `pathfind.compute`     | `Pathfinder.cpp`       | `findPaths()`           | High     |
-| **TxQ**         | `txq.enqueue`          | `TxQ.cpp`              | `apply()`               | High     |
-| **TxQ**         | `txq.apply`            | `TxQ.cpp`              | `processClosedLedger()` | High     |
-| **Fee**         | `fee.escalate`         | `LoadManager.cpp`      | `raiseLocalFee()`       | Medium   |
-| **Ledger**      | `ledger.replay`        | `LedgerReplayer.h`     | `replay()`              | Medium   |
-| **Ledger**      | `ledger.delta`         | `LedgerDeltaAcquire.h` | `processData()`         | Medium   |
-| **Validator**   | `validator.list.fetch` | `ValidatorList.cpp`    | `verify()`              | Medium   |
-| **Validator**   | `validator.manifest`   | `Manifest.cpp`         | `applyManifest()`       | Low      |
-| **Amendment**   | `amendment.vote`       | `AmendmentTable.cpp`   | `doVoting()`            | Low      |
-| **SHAMap**      | `shamap.sync`          | `SHAMap.cpp`           | `fetchRoot()`           | Medium   |
-
---
-
-## 1.7 Instrumentation Priority
-
-> **TxQ** = Transaction Queue
-
-```mermaid
-quadrantChart
-    title Instrumentation Priority Matrix
-    x-axis Low Complexity --> High Complexity
-    y-axis Low Value --> High Value
-    quadrant-1 Implement First
-    quadrant-2 Plan Carefully
-    quadrant-3 Quick Wins
-    quadrant-4 Consider Later
-
-    RPC Tracing: [0.2, 0.92]
-    Transaction Tracing: [0.55, 0.88]
-    Consensus Tracing: [0.78, 0.82]
-    PathFinding: [0.38, 0.75]
-    TxQ and Fees: [0.25, 0.65]
-    Ledger Sync: [0.62, 0.58]
-    Peer Message Tracing: [0.35, 0.25]
-    JobQueue Tracing: [0.2, 0.48]
-    Validator Mgmt: [0.48, 0.42]
-    Amendment Tracking: [0.15, 0.32]
-    SHAMap Operations: [0.72, 0.45]
-```
-
---
-
-## 1.8 Observable Outcomes
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List
-
-After implementing OpenTelemetry, operators and developers will gain visibility into the following:
-
-### 1.8.1 What You Will See: Traces
-
-| Trace Type                 | Description                                                                                 | Example Query in Grafana/Tempo                  |
-| -------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| **Transaction Lifecycle**  | Full journey from RPC submission through validation, relay, consensus, and ledger inclusion | `{service.name="xrpld" && tx_hash="ABC123..."}` |
-| **Cross-Node Propagation** | Transaction path across multiple xrpld nodes with timing                                    | `{relay_count > 0}`                             |
-| **Consensus Rounds**       | Complete round with all phases (open, establish, accept)                                    | `{span.name=~"consensus.round.*"}`              |
-| **RPC Request Processing** | Individual command execution with timing breakdown                                          | `{command="account_info"}`                      |
-| **Ledger Acquisition**     | Peer-to-peer ledger data requests and responses                                             | `{span.name="ledger.acquire"}`                  |
-| **PathFinding Latency**    | Path computation time and cache effectiveness for payment RPCs                              | `{span.name="pathfind.compute"}`                |
-| **TxQ Behavior**           | Queue depth, eviction patterns, fee escalation during congestion                            | `{span.name=~"txq.*"}`                          |
-| **Ledger Sync**            | Full acquisition timeline including delta and transaction fetches                           | `{span.name=~"ledger.acquire.*"}`               |
-| **Validator Health**       | UNL fetch success, manifest updates, stale list detection                                   | `{span.name=~"validator.*"}`                    |
-
-### 1.8.2 What You Will See: Metrics (Derived from Traces)
-
-| Metric                        | Description                             | Dashboard Panel             |
-| ----------------------------- | --------------------------------------- | --------------------------- |
-| **RPC Latency (p50/p95/p99)** | Response time distribution per command  | Heatmap by command          |
-| **Transaction Throughput**    | Transactions processed per second       | Time series graph           |
-| **Consensus Round Duration**  | Time to complete consensus phases       | Histogram                   |
-| **Cross-Node Latency**        | Time for transaction to reach N nodes   | Line chart with percentiles |
-| **Error Rate**                | Failed transactions/RPC calls by type   | Stacked bar chart           |
-| **PathFinding Latency**       | Path computation time per currency pair | Heatmap by currency         |
-| **TxQ Depth**                 | Queued transactions over time           | Time series with thresholds |
-| **Fee Escalation Level**      | Current fee multiplier                  | Gauge with alert thresholds |
-| **Ledger Sync Duration**      | Time to acquire missing ledgers         | Histogram                   |
-
-### 1.8.3 Concrete Dashboard Examples
-
-**Transaction Trace View (Tempo):**
-
-```
-┌────────────────────────────────────────────────────────────────────────────────┐
-│ Trace: abc123... (Transaction Submission)                    Duration: 847ms   │
-├────────────────────────────────────────────────────────────────────────────────┤
-│ ├── rpc.request [ServerHandler]                              ████░░░░░░  45ms  │
-│ │   └── rpc.command.submit [RPCHandler]                      ████░░░░░░  42ms  │
-│ │       └── tx.receive [NetworkOPs]                          ███░░░░░░░  35ms  │
-│ │           ├── tx.validate [TxQ]                            █░░░░░░░░░   8ms  │
-│ │           └── tx.relay [Overlay]                           ██░░░░░░░░  15ms  │
-│ │               ├── tx.receive [Node-B]                      █████░░░░░  52ms  │
-│ │               │   └── tx.relay [Node-B]                    ██░░░░░░░░  18ms  │
-│ │               └── tx.receive [Node-C]                      ██████░░░░  65ms  │
-│ └── consensus.round [RCLConsensus]                           ████████░░ 720ms  │
-│     ├── consensus.phase.open                                 ██░░░░░░░░ 180ms  │
-│     ├── consensus.phase.establish                            █████░░░░░ 480ms  │
-│     └── consensus.phase.accept                               █░░░░░░░░░  60ms  │
-└────────────────────────────────────────────────────────────────────────────────┘
-```
-
-**RPC Performance Dashboard Panel:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ RPC Command Latency (Last 1 Hour)                           │
-├─────────────────────────────────────────────────────────────┤
-│ Command          │ p50    │ p95    │ p99    │ Errors │ Rate │
-│──────────────────┼────────┼────────┼────────┼────────┼──────│
-│ account_info     │  12ms  │  45ms  │  89ms  │  0.1%  │ 150/s│
-│ submit           │  35ms  │ 120ms  │ 250ms  │  2.3%  │  45/s│
-│ ledger           │   8ms  │  25ms  │  55ms  │  0.0%  │  80/s│
-│ tx               │  15ms  │  50ms  │ 100ms  │  0.5%  │  60/s│
-│ server_info      │   5ms  │  12ms  │  20ms  │  0.0%  │ 200/s│
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Consensus Health Dashboard Panel:**
-
-```mermaid
---
-config:
-    xyChart:
-        width: 1200
-        height: 400
-        plotReservedSpacePercent: 50
-        chartOrientation: vertical
-    themeVariables:
-        xyChart:
-            plotColorPalette: "#3498db"
---
-xychart-beta
-    title "Consensus Round Duration (Last 24 Hours)"
-    x-axis "Time of Day (Hours)" [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24]
-    y-axis "Duration (seconds)" 1 --> 5
-    line [2.1, 2.4, 2.8, 3.2, 3.8, 4.3, 4.5, 5.0, 4.7, 4.0, 3.2, 2.6, 2.0]
-```
-
-### 1.8.4 Operator Actionable Insights
-
-| Scenario                  | What You'll See                                                              | Action                                           |
-| ------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
-| **Slow RPC**              | Span showing which phase is slow (parsing, execution, serialization)         | Optimize specific code path                      |
-| **Transaction Stuck**     | Trace stops at validation; error attribute shows reason                      | Fix transaction parameters                       |
-| **Consensus Delay**       | Phase.establish taking too long; proposer attribute shows missing validators | Investigate network connectivity                 |
-| **Memory Spike**          | Large batch of spans correlating with memory increase                        | Tune batch_size or sampling                      |
-| **Network Partition**     | Traces missing cross-node links for specific peer                            | Check peer connectivity                          |
-| **Path Computation Slow** | pathfind.compute span shows high latency; cache miss rate in attributes      | Warm the RippleLineCache, check order book depth |
-| **TxQ Full**              | txq.enqueue spans show evictions; fee.escalate spans increasing              | Monitor fee levels, alert operators              |
-| **Ledger Sync Stalled**   | ledger.acquire spans timing out; peer reliability attributes show issues     | Check peer connectivity, add trusted peers       |
-| **UNL Stale**             | validator.list.fetch spans failing; last_update attribute aging              | Verify validator site URLs, check DNS            |
-
-### 1.8.5 Developer Debugging Workflow
-
-1. **Find Transaction**: Query by `tx_hash` to get full trace
-2. **Identify Bottleneck**: Look at span durations to find slowest component
-3. **Check Attributes**: Review `validity`, `rpc_status` for errors
-4. **Correlate Logs**: Use `trace_id` to find related PerfLog entries
-5. **Compare Nodes**: Filter by `service.instance.id` to compare behavior across nodes
-
---
-
-_Next: [Design Decisions](./02-design-decisions.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/02-design-decisions.md
+++ b/OpenTelemetryPlan/02-design-decisions.md
@@ -1,568 +0,0 @@
-# Design Decisions
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Architecture Analysis](./01-architecture-analysis.md)
-
---
-
-## 2.1 OpenTelemetry Components
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 2.1.1 SDK Selection
-
-**Primary Choice**: OpenTelemetry C++ SDK (`opentelemetry-cpp`)
-
-| Component                               | Purpose                | Required                  |
-| --------------------------------------- | ---------------------- | ------------------------- |
-| `opentelemetry-cpp::api`                | Tracing API headers    | Yes                       |
-| `opentelemetry-cpp::sdk`                | SDK implementation     | Yes                       |
-| `opentelemetry-cpp::ext`                | Extensions (exporters) | Yes                       |
-| `opentelemetry-cpp::otlp_http_exporter` | OTLP/HTTP export       | Yes (shipped in Phase 1b) |
-| `opentelemetry-cpp::otlp_grpc_exporter` | OTLP/gRPC export       | Future (not yet wired up) |
-
-### 2.1.2 Instrumentation Strategy
-
-**Manual Instrumentation** (recommended):
-
-| Approach   | Pros                                                            | Cons                                                    |
-| ---------- | --------------------------------------------------------------- | ------------------------------------------------------- |
-| **Manual** | Precise control, optimized placement, xrpld-specific attributes | More development effort                                 |
-| **Auto**   | Less code, automatic coverage                                   | Less control, potential overhead, limited customization |
-
---
-
-## 2.2 Exporter Configuration
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph nodes["xrpld Nodes"]
-        node1["xrpld<br/>Node 1"]
-        node2["xrpld<br/>Node 2"]
-        node3["xrpld<br/>Node 3"]
-    end
-
-    collector["OpenTelemetry<br/>Collector<br/>(sidecar or standalone)"]
-
-    subgraph backends["Observability Backends"]
-        tempo["Tempo"]
-        elastic["Elastic<br/>APM"]
-    end
-
-    node1 -->|"OTLP/HTTP<br/>:4318"| collector
-    node2 -->|"OTLP/HTTP<br/>:4318"| collector
-    node3 -->|"OTLP/HTTP<br/>:4318"| collector
-
-    collector --> tempo
-    collector --> elastic
-
-    style nodes fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **xrpld Nodes (blue)**: The source of telemetry data. Each xrpld node exports spans via OTLP/HTTP on port 4318 (the only exporter shipped in Phase 1b).
- **OpenTelemetry Collector (red)**: The central aggregation point that receives spans from all nodes. Can run as a sidecar (per-node) or standalone (shared). Handles batching, filtering, and routing.
- **Observability Backends (green)**: The storage and visualization destinations. Tempo is the recommended backend for both development and production, and Elastic APM is an alternative. The Collector routes to one or more backends.
- **Arrows (nodes to collector to backends)**: The data pipeline -- spans flow from nodes to the Collector over HTTP, then the Collector fans out to the configured backends.
-
-### 2.2.1 OTLP/HTTP (Shipped in Phase 1b)
-
-OTLP/HTTP is the only exporter wired up in Phase 1b. It is configured via
-`OtlpHttpExporterOptions` with the collector traces endpoint
-(`http://localhost:4318/v1/traces` by default) and a JSON content type
-(binary protobuf is also available).
-
-### 2.2.2 OTLP/gRPC (Future Work — Planned Upgrade)
-
-OTLP/gRPC is planned as a future upgrade from the HTTP exporter. The gRPC
-transport offers lower per-span overhead and tighter back-pressure semantics
-than HTTP/JSON, making it attractive for production deployments once the HTTP
-path is validated in earlier phases.
-
-Required to land this upgrade:
-
-1. Add `opentelemetry-cpp::otlp_grpc_exporter` to the Conan recipe (the
-   dependency already exists but is not linked in Phase 1b builds).
-2. Extend `TelemetryConfig.cpp` to parse an `exporter` key (`otlp_http`
-   default, `otlp_grpc` opt-in) and a gRPC endpoint override.
-3. In `Telemetry::start()` branch on the parsed exporter type and construct
-   either `OtlpHttpExporterFactory::Create(httpOpts)` or
-   `OtlpGrpcExporterFactory::Create(grpcOpts)` accordingly.
-4. Update the runbook and dashboards to document the alternate port and TLS
-   settings.
-
-When wired up, the gRPC path will use `OtlpGrpcExporterOptions` configured with
-the collector endpoint (host on port 4317), TLS credentials enabled, and a CA
-certificate path.
-
-Until that work lands, `OtlpGrpcExporterOptions` is **not** used by any code
-path in Phase 1b through Phase 5.
-
---
-
-## 2.3 Span Naming Conventions
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **WS** = WebSocket
-
-### 2.3.1 Naming Schema
-
-```
-<component>.<operation>[.<sub-operation>]
-```
-
-**Examples**:
-
- `tx.receive` - Transaction received from peer
- `consensus.phase.establish` - Consensus establish phase
- `rpc.command.server_info` - server_info RPC command
-
-### 2.3.2 Complete Span Catalog
-
-| Span name                      | Description                             |
-| ------------------------------ | --------------------------------------- |
-| `tx.receive`                   | Transaction received from network       |
-| `tx.validate`                  | Transaction signature/format validation |
-| `tx.process`                   | Full transaction processing             |
-| `tx.relay`                     | Transaction relay to peers              |
-| `tx.apply`                     | Apply transaction to ledger             |
-| `consensus.round`              | Complete consensus round                |
-| `consensus.phase.open`         | Open phase - collecting transactions    |
-| `consensus.phase.establish`    | Establish phase - reaching agreement    |
-| `consensus.phase.accept`       | Accept phase - applying consensus       |
-| `consensus.proposal.receive`   | Receive peer proposal                   |
-| `consensus.proposal.send`      | Send our proposal                       |
-| `consensus.validation.receive` | Receive peer validation                 |
-| `consensus.validation.send`    | Send our validation                     |
-| `rpc.request`                  | HTTP/WebSocket request handling         |
-| `rpc.command.*`                | Specific RPC command (dynamic)          |
-| `peer.connect`                 | Peer connection establishment           |
-| `peer.disconnect`              | Peer disconnection                      |
-| `peer.message.send`            | Send protocol message                   |
-| `peer.message.receive`         | Receive protocol message                |
-| `ledger.acquire`               | Ledger acquisition from network         |
-| `ledger.build`                 | Build new ledger                        |
-| `ledger.validate`              | Ledger validation                       |
-| `ledger.close`                 | Close ledger                            |
-| `ledger.replay`                | Ledger replay executed                  |
-| `ledger.delta`                 | Delta-based ledger acquired             |
-| `pathfind.request`             | Path request initiated                  |
-| `pathfind.compute`             | Path computation executed               |
-| `txq.enqueue`                  | Transaction queued                      |
-| `txq.apply`                    | Queued transaction applied              |
-| `fee.escalate`                 | Fee escalation triggered                |
-| `validator.list.fetch`         | UNL list fetched                        |
-| `validator.manifest`           | Manifest update processed               |
-| `amendment.vote`               | Amendment voting executed               |
-| `shamap.sync`                  | State tree synchronization              |
-| `job.enqueue`                  | Job added to queue                      |
-| `job.execute`                  | Job execution                           |
-
-### 2.3.3 Attribute Naming Conventions
-
-Span **names** follow §2.3.1 (dotted `<component>.<operation>`). Span
-**attribute keys** follow the rules below. The constants in the `*SpanNames.h`
-headers are the single source of truth; the collector, Tempo, the Grafana
-dashboards, and the runbook all consume these exact keys, so every layer must
-agree with the code. A CI check enforces this end to end.
-
-1. **Per-span unique attribute** → bare field name, allowed when the field is
-   recorded by a single span/workflow so the span name already supplies the
-   domain (e.g. `command`, `version`, `local` on `rpc.command`).
-2. **Shared attribute (same concept on more than one span)** → ONE key, reused
-   verbatim on every span that records it; the span name tells the occurrences
-   apart, so no per-emitter prefix is added. Name it by the field's meaning: a
-   property of a domain object keeps that object's bare field name (`ledger_hash`,
-   `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a field already
-   qualified by a sub-kind keeps that qualifier on every emitter (`proposal_trusted`
-   on both `consensus.proposal.receive` and `peer.proposal.receive`;
-   `validation_trusted` likewise). Defined once in the base `SpanNames.h`
-   `namespace attr` block and re-exported (`using`) by each domain header.
-3. **Collision qualifier** → `<domain>_<field>`, only when a bare name would
-   collide with a DIFFERENT concept in the shared spanmetrics label space or with
-   the OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
-   `consensus_phase`, `consensus_round`, `consensus_mode`). This disambiguates
-   distinct concepts that share a word; it is NOT used to tag the same concept
-   with its emitting workflow — that is rule 2 (one shared name).
-4. **Resource attribute** → dotted `xrpl.<subsystem>.<field>`, reserved ONLY
-   for process/network identity set once at startup (`xrpl.network.id`,
-   `xrpl.network.type`). Span attributes are never dotted in the `xrpl.` form —
-   it blurs the resource/span scope boundary and parses awkwardly in TraceQL.
-5. **Span names** use `<subsystem>[.<component>]` (dotted, per §2.3.1). Only
-   attribute _keys_ follow rules 1–4.
-
-Standard OpenTelemetry semantic-convention keys keep their canonical dotted
-form (e.g. `service.*` resource attributes, `http.*` span attributes); the
-"no dotted form" rule applies to xrpl-custom keys only.
-
-The same rules are recorded in `CONTRIBUTING.md` (the permanent home, since
-`OpenTelemetryPlan/` is removed once the rollout completes). The attribute
-examples in §2.4 below follow these rules.
-
---
-
-## 2.4 Attribute Schema
-
-> **TxQ** = Transaction Queue | **UNL** = Unique Node List | **OTLP** = OpenTelemetry Protocol
-
-### 2.4.1 Resource Attributes (Set Once at Startup)
-
-Resource attributes identify the process and are set once at startup. They use
-the standard OpenTelemetry semantic conventions plus custom dotted `xrpl.*`
-keys (the dotted form is reserved for resource scope per §2.3.3).
-
-| Key                   | Type / value                                            | Description                    |
-| --------------------- | ------------------------------------------------------- | ------------------------------ |
-| `service.name`        | `"xrpld"`                                               | Standard `SERVICE_NAME`        |
-| `service.version`     | `BuildInfo::getVersionString()`                         | Standard `SERVICE_VERSION`     |
-| `service.instance.id` | node public key (base58)                                | Standard `SERVICE_INSTANCE_ID` |
-| `xrpl.network.id`     | network id (e.g. 0 for mainnet)                         | Network identifier             |
-| `xrpl.network.type`   | `"mainnet"` \| `"testnet"` \| `"devnet"` \| `"unknown"` | Network kind                   |
-| `xrpl.node.type`      | `"validator"` \| `"stock"` \| `"reporting"`             | Node role                      |
-| `xrpl.node.cluster`   | cluster name                                            | Cluster name, if clustered     |
-
-### 2.4.2 Span Attributes by Category
-
-> Span attribute keys use the underscore form from §2.3.3 (shared/qualified
-> keys are `<domain>_<field>`; per-span unique keys are bare). The dotted form
-> is reserved for the resource attributes in §2.4.1 above. This catalog lists
-> the planned attribute set by category; the exact emitted key for each
-> implemented span is defined by the `*SpanNames.h` constants, which are the
-> single source of truth where the two differ.
-
-#### Transaction Attributes
-
-| Key            | Type   | Description                           |
-| -------------- | ------ | ------------------------------------- |
-| `tx_hash`      | string | Transaction hash (hex)                |
-| `tx_type`      | string | `"Payment"`, `"OfferCreate"`, etc.    |
-| `tx_account`   | string | Source account (redacted in prod)     |
-| `tx_sequence`  | int64  | Account sequence number               |
-| `tx_fee`       | int64  | Fee in drops                          |
-| `tx_result`    | string | `"tesSUCCESS"`, `"tecPATH_DRY"`, etc. |
-| `ledger_index` | int64  | Ledger containing transaction         |
-| `relay_count`  | int64  | Peers the transaction was relayed to  |
-| `suppressed`   | bool   | `true` when HashRouter dropped a dup  |
-
-#### Consensus Attributes
-
-| Key                  | Type    | Description                         |
-| -------------------- | ------- | ----------------------------------- |
-| `consensus_round`    | int64   | Round number                        |
-| `consensus_phase`    | string  | `"open"`, `"establish"`, `"accept"` |
-| `consensus_mode`     | string  | `"proposing"`, `"observing"`, etc.  |
-| `proposers`          | int64   | Number of proposers                 |
-| `prev_ledger_prefix` | string  | Previous ledger hash prefix         |
-| `ledger_seq`         | int64   | Ledger sequence                     |
-| `tx_count`           | int64   | Transactions in consensus set       |
-| `round_time_ms`      | float64 | Round duration                      |
-
-#### RPC Attributes
-
-| Key           | Type    | Description                                                                   |
-| ------------- | ------- | ----------------------------------------------------------------------------- |
-| `command`     | string  | Command name (per-span unique on `rpc.command`)                               |
-| `version`     | int64   | API version                                                                   |
-| `rpc_role`    | string  | `"admin"` or `"user"` (qualified — `role` is generic)                         |
-| `params`      | string  | Sanitized parameters (optional)                                               |
-| `rpc_status`  | string  | Response status: `success` \| `error` (qualified — `status` is OTel-reserved) |
-| `duration_ms` | float64 | Request duration in milliseconds                                              |
-
-#### Peer & Message Attributes
-
-| Key                  | Type    | Description                |
-| -------------------- | ------- | -------------------------- |
-| `peer_id`            | string  | Peer public key (base58)   |
-| `peer_address`       | string  | IP:port                    |
-| `peer_latency_ms`    | float64 | Measured latency           |
-| `peer_cluster`       | string  | Cluster name if clustered  |
-| `message_type`       | string  | Protocol message type name |
-| `message_size_bytes` | int64   | Message size               |
-| `message_compressed` | bool    | Whether compressed         |
-
-#### Ledger & Job Attributes
-
-| Key               | Type    | Description           |
-| ----------------- | ------- | --------------------- |
-| `ledger_hash`     | string  | Ledger hash           |
-| `ledger_index`    | int64   | Ledger sequence/index |
-| `close_time`      | int64   | Close time (epoch)    |
-| `ledger_tx_count` | int64   | Transaction count     |
-| `job_type`        | string  | Job type name         |
-| `job_queue_ms`    | float64 | Time spent in queue   |
-| `job_worker`      | int64   | Worker thread ID      |
-
-#### PathFinding Attributes
-
-| Key                        | Type   | Description               |
-| -------------------------- | ------ | ------------------------- |
-| `pathfind_source_currency` | string | Source currency code      |
-| `pathfind_dest_currency`   | string | Destination currency code |
-| `pathfind_path_count`      | int64  | Number of paths found     |
-| `pathfind_cache_hit`       | bool   | RippleLineCache hit       |
-
-#### TxQ Attributes
-
-| Key                   | Type   | Description                 |
-| --------------------- | ------ | --------------------------- |
-| `txq_queue_depth`     | int64  | Current queue depth         |
-| `txq_fee_level`       | int64  | Fee level of transaction    |
-| `txq_eviction_reason` | string | Why transaction was evicted |
-
-#### Fee Attributes
-
-| Key                    | Type  | Description               |
-| ---------------------- | ----- | ------------------------- |
-| `fee_load_factor`      | int64 | Current load factor       |
-| `fee_escalation_level` | int64 | Fee escalation multiplier |
-
-#### Validator Attributes
-
-| Key                      | Type  | Description               |
-| ------------------------ | ----- | ------------------------- |
-| `validator_list_size`    | int64 | UNL size                  |
-| `validator_list_age_sec` | int64 | Seconds since last update |
-
-#### Amendment Attributes
-
-| Key                | Type   | Description                            |
-| ------------------ | ------ | -------------------------------------- |
-| `amendment_name`   | string | Amendment name                         |
-| `amendment_status` | string | `"enabled"`, `"vetoed"`, `"supported"` |
-
-#### SHAMap Attributes
-
-| Key                    | Type    | Description                                   |
-| ---------------------- | ------- | --------------------------------------------- |
-| `shamap_type`          | string  | `"transaction"`, `"state"`, `"account_state"` |
-| `shamap_missing_nodes` | int64   | Number of missing nodes during sync           |
-| `shamap_duration_ms`   | float64 | Sync duration                                 |
-
-### 2.4.3 Data Collection Summary
-
-The following table summarizes what data is collected by category:
-
-| Category        | Attributes Collected                                                                              | Purpose                      |
-| --------------- | ------------------------------------------------------------------------------------------------- | ---------------------------- |
-| **Transaction** | `tx_hash`, `tx_type`, `tx_result`, `tx_fee`, `ledger_index`                                       | Trace transaction lifecycle  |
-| **Consensus**   | `consensus_round`, `consensus_phase`, `consensus_mode`, `proposers`, `round_time_ms`              | Analyze consensus timing     |
-| **RPC**         | `command`, `version`, `rpc_status`, `duration_ms`                                                 | Monitor RPC performance      |
-| **Peer**        | `peer_id` (public key), `peer_latency_ms`, `message_type`, `message_size_bytes`                   | Network topology analysis    |
-| **Ledger**      | `ledger_hash`, `ledger_index`, `close_time`, `ledger_tx_count`                                    | Ledger progression tracking  |
-| **Job**         | `job_type`, `job_queue_ms`, `job_worker`                                                          | JobQueue performance         |
-| **PathFinding** | `pathfind_source_currency`, `pathfind_dest_currency`, `pathfind_path_count`, `pathfind_cache_hit` | Payment path analysis        |
-| **TxQ**         | `txq_queue_depth`, `txq_fee_level`, `txq_eviction_reason`                                         | Queue depth and fee tracking |
-| **Fee**         | `fee_load_factor`, `fee_escalation_level`                                                         | Fee escalation monitoring    |
-| **Validator**   | `validator_list_size`, `validator_list_age_sec`                                                   | UNL health monitoring        |
-| **Amendment**   | `amendment_name`, `amendment_status`                                                              | Protocol upgrade tracking    |
-| **SHAMap**      | `shamap_type`, `shamap_missing_nodes`, `shamap_duration_ms`                                       | State tree sync performance  |
-
-### 2.4.4 Privacy & Sensitive Data Policy
-
-> **PII** = Personally Identifiable Information
-
-OpenTelemetry instrumentation is designed to collect **operational metadata only**, never sensitive content.
-
-#### Data NOT Collected
-
-The following data is explicitly **excluded** from telemetry collection:
-
-| Excluded Data           | Reason                                    |
-| ----------------------- | ----------------------------------------- |
-| **Private Keys**        | Never exposed; not relevant to tracing    |
-| **Account Balances**    | Financial data; privacy sensitive         |
-| **Transaction Amounts** | Financial data; privacy sensitive         |
-| **Raw TX Payloads**     | May contain sensitive memo/data fields    |
-| **Personal Data**       | No PII collected                          |
-| **IP Addresses**        | Configurable; excluded by default in prod |
-
-#### Privacy Protection Mechanisms
-
-| Mechanism                     | Description                                                                                                                             |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| **Account Hashing**           | `tx_account` is hashed at collector level before storage                                                                                |
-| **Configurable Redaction**    | Sensitive fields can be excluded via `[telemetry]` config section                                                                       |
-| **Collector Tail Sampling**   | xrpld head sampling is fixed at 1.0 (every span emitted); the collector retains ~10% of non-error traces, reducing stored data exposure |
-| **Local Control**             | Node operators have full control over what gets exported                                                                                |
-| **No Raw Payloads**           | Transaction content is never recorded, only metadata (hash, type, result)                                                               |
-| **Collector-Level Filtering** | Additional redaction/hashing can be configured at OTel Collector                                                                        |
-
-#### Collector-Level Data Protection
-
-The OpenTelemetry Collector can be configured (via an `attributes` processor)
-to hash or redact sensitive attributes before export — for example, hashing
-`tx_account`, deleting `peer_address` to drop IP addresses, and deleting
-`params` to redact request parameters.
-
-#### Configuration Options for Privacy
-
-In `xrpld.cfg`, operators control data collection granularity through the
-`[telemetry]` section. Besides `enabled`, per-component toggles
-(`trace_transactions`, `trace_consensus`, `trace_rpc`, `trace_peer` — the last
-often disabled due to high volume) select which spans are emitted, and
-redaction flags (`redact_account` to hash account addresses, `redact_peer_address`
-to remove peer IP addresses) control SDK-level redaction before export.
-
-> **Note**: The `redact_account` configuration in `xrpld.cfg` controls SDK-level redaction before export, while collector-level filtering (see [Collector-Level Data Protection](#collector-level-data-protection) above) provides an additional defense-in-depth layer. Both can operate independently.
-
-> **Key Principle**: Telemetry collects **operational metadata** (timing, counts, hashes) — never **sensitive content** (keys, balances, amounts, raw payloads).
-
---
-
-## 2.5 Context Propagation Design
-
-> **WS** = WebSocket
-
-### 2.5.1 Propagation Boundaries
-
-```mermaid
-flowchart TB
-    subgraph http["HTTP/WebSocket (RPC)"]
-        w3c["W3C Trace Context Headers:<br/>traceparent:<br/>00-trace_id-span_id-flags<br/>tracestate: xrpld=..."]
-    end
-
-    subgraph protobuf["Protocol Buffers (P2P)"]
-        proto["message TraceContext {<br/>  bytes trace_id = 1;  // 16 bytes<br/>  bytes span_id = 2;   // 8 bytes<br/>  uint32 trace_flags = 3;<br/>  string trace_state = 4;<br/>}"]
-    end
-
-    subgraph jobqueue["JobQueue (Internal Async)"]
-        job["Context captured at job creation,<br/>restored at execution<br/><br/>class Job {<br/>  otel::context::Context<br/>    traceContext_;<br/>};"]
-    end
-
-    style http fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style protobuf fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style jobqueue fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **HTTP/WebSocket - RPC (blue)**: For client-facing RPC requests, trace context is propagated using the W3C `traceparent` header. This is the standard approach and works with any OTel-compatible client.
- **Protocol Buffers - P2P (green)**: For peer-to-peer messages between xrpld nodes, trace context is embedded as a protobuf `TraceContext` message carrying trace_id, span_id, flags, and optional trace_state.
- **JobQueue - Internal Async (red)**: For asynchronous work within a single node, the OTel context is captured when a job is created and restored when the job executes on a worker thread. This bridges the async gap so spans remain linked.
-
---
-
-## 2.6 Integration with Existing Observability
-
-> **OTLP** = OpenTelemetry Protocol | **WS** = WebSocket
-
-### 2.6.1 Existing Frameworks Comparison
-
-xrpld already has two observability mechanisms. OpenTelemetry complements (not replaces) them:
-
-| Aspect                | PerfLog                       | Beast Insight (StatsD)       | OpenTelemetry             |
-| --------------------- | ----------------------------- | ---------------------------- | ------------------------- |
-| **Type**              | Logging                       | Metrics                      | Distributed Tracing       |
-| **Data**              | JSON log entries              | Counters, gauges, histograms | Spans with context        |
-| **Scope**             | Single node                   | Single node                  | **Cross-node**            |
-| **Output**            | `perf.log` file               | StatsD server                | OTLP Collector            |
-| **Question answered** | "What happened on this node?" | "How many? How fast?"        | "What was the journey?"   |
-| **Correlation**       | By timestamp                  | By metric name               | By `trace_id`             |
-| **Overhead**          | Low (file I/O)                | Low (UDP packets)            | Low-Medium (configurable) |
-
-### 2.6.2 What Each Framework Does Best
-
-#### PerfLog
-
- **Purpose**: Detailed local event logging for RPC and job execution
- **Strengths**:
-  - Rich JSON output with timing data
-  - Already integrated in RPC handlers
-  - File-based, no external dependencies
- **Limitations**:
-  - Single-node only (no cross-node correlation)
-  - No parent-child relationships between events
-  - Manual log parsing required
-
-A PerfLog entry is a JSON object with fields such as `time`, `method`,
-`duration_us`, and `result`.
-
-#### Beast Insight (StatsD)
-
- **Purpose**: Real-time metrics for monitoring dashboards
- **Strengths**:
-  - Aggregated metrics (counters, gauges, histograms)
-  - Low overhead (UDP, fire-and-forget)
-  - Good for alerting thresholds
- **Limitations**:
-  - No request-level detail
-  - No causal relationships
-  - Single-node perspective
-
-In xrpld, Beast Insight is used through `increment` (counters), `gauge`
-(point-in-time values), and `timing` (durations) calls.
-
-#### OpenTelemetry (NEW)
-
- **Purpose**: Distributed request tracing across nodes
- **Strengths**:
-  - **Cross-node correlation** via `trace_id`
-  - Parent-child span relationships
-  - Rich attributes per span
-  - Industry standard (CNCF)
- **Limitations**:
-  - Requires collector infrastructure
-  - Higher complexity than logging
-
-A span is created via `startSpan` (e.g. `"tx.relay"`), annotated with
-attributes such as `tx_hash` and `peer_id`, and is automatically linked to its
-parent through the active context.
-
-### 2.6.3 When to Use Each
-
-| Scenario                                | PerfLog    | StatsD | OpenTelemetry |
-| --------------------------------------- | ---------- | ------ | ------------- |
-| "How many TXs per second?"              | ❌         | ✅     | ✅            |
-| "What's the p99 RPC latency?"           | ❌         | ✅     | ✅            |
-| "Why was this specific TX slow?"        | ⚠️ partial | ❌     | ✅            |
-| "Which node delayed consensus?"         | ❌         | ❌     | ✅            |
-| "What happened on node X at time T?"    | ✅         | ❌     | ✅            |
-| "Show me the TX journey across 5 nodes" | ❌         | ❌     | ✅            |
-
-### 2.6.4 Coexistence Strategy
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Process"]
-        perflog["PerfLog<br/>(JSON to file)"]
-        insight["Beast Insight<br/>(StatsD)"]
-        otel["OpenTelemetry<br/>(Tracing)"]
-    end
-
-    perflog --> perffile["perf.log"]
-    insight --> statsd["StatsD Server"]
-    otel --> collector["OTLP Collector"]
-
-    perffile --> grafana["Grafana<br/>(Unified UI)"]
-    statsd --> grafana
-    collector --> grafana
-
-    style xrpld fill:#212121,stroke:#0a0a0a,color:#ffffff
-    style grafana fill:#bf360c,stroke:#8c2809,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **xrpld Process (dark gray)**: The single xrpld node running all three observability frameworks side by side. Each framework operates independently with no interference.
- **PerfLog to perf.log**: PerfLog writes JSON-formatted event logs to a local file. Grafana can ingest these via Loki or a file-based datasource.
- **Beast Insight to StatsD Server**: Insight sends aggregated metrics (counters, gauges) over UDP to a StatsD server. Grafana reads from StatsD-compatible backends like Graphite or Prometheus (via StatsD exporter).
- **OpenTelemetry to OTLP Collector**: OTel exports spans over OTLP/HTTP to a Collector, which then forwards to a trace backend (Tempo). (OTLP/gRPC is future work — §2.2.2.)
- **Grafana (red, unified UI)**: All three data streams converge in Grafana, enabling operators to correlate logs, metrics, and traces in a single dashboard.
-
-### 2.6.5 Correlation with PerfLog
-
-Trace IDs can be correlated with existing PerfLog entries for comprehensive
-debugging. The design is for `RPCHandler.cpp` to start an `rpc.command.<method>`
-span alongside the existing PerfLog `rpcStart`/`rpcFinish`/`rpcError` calls,
-extract the span's `trace_id` (when valid), and eventually stamp it onto the
-PerfLog entry (a planned `setTraceId` hook) so logs and traces share a key. The
-span status is set to OK on success or to error (recording the exception) on
-failure.
-
---
-
-_Previous: [Architecture Analysis](./01-architecture-analysis.md)_ | _Next: [Implementation Strategy](./03-implementation-strategy.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/03-implementation-strategy.md
+++ b/OpenTelemetryPlan/03-implementation-strategy.md
@@ -1,488 +0,0 @@
-# Implementation Strategy
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Configuration Reference](./05-configuration-reference.md)
-
---
-
-## 3.1 Directory Structure
-
-The telemetry implementation follows xrpld's existing code organization pattern:
-
-```
-include/xrpl/
-├── telemetry/
-│   ├── Telemetry.h              # Main telemetry interface
-│   ├── TelemetryConfig.h        # Configuration structures
-│   ├── TraceContext.h           # Context propagation utilities
-│   ├── SpanGuard.h              # RAII span management
-│   └── SpanAttributes.h         # Attribute helper functions
-
-src/libxrpl/
-├── telemetry/
-│   ├── Telemetry.cpp            # Implementation
-│   ├── TelemetryConfig.cpp      # Config parsing
-│   ├── TraceContext.cpp         # Context serialization
-│   └── NullTelemetry.cpp        # No-op implementation
-
-src/xrpld/
-├── telemetry/
-│   ├── TracingInstrumentation.h # Instrumentation macros
-│   └── TracingInstrumentation.cpp
-```
-
---
-
-## 3.2 Implementation Approach
-
-<div align="center">
-
-```mermaid
-%%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 30}}}%%
-flowchart TB
-    subgraph phase1["Phase 1: Core"]
-        direction LR
-        sdk["SDK Integration"] ~~~ interface["Telemetry Interface"] ~~~ config["Configuration"]
-    end
-
-    subgraph phase2["Phase 2: RPC"]
-        direction LR
-        http["HTTP Context"] ~~~ rpc["RPC Handlers"]
-    end
-
-    subgraph phase3["Phase 3: P2P"]
-        direction LR
-        proto["Protobuf Context"] ~~~ tx["Transaction Relay"]
-    end
-
-    subgraph phase4["Phase 4: Consensus"]
-        direction LR
-        consensus["Consensus Rounds"] ~~~ proposals["Proposals"]
-    end
-
-    phase1 --> phase2 --> phase3 --> phase4
-
-    style phase1 fill:#1565c0,stroke:#0d47a1,color:#ffffff
-    style phase2 fill:#2e7d32,stroke:#1b5e20,color:#ffffff
-    style phase3 fill:#e65100,stroke:#bf360c,color:#ffffff
-    style phase4 fill:#c2185b,stroke:#880e4f,color:#ffffff
-```
-
-</div>
-
-### Key Principles
-
-1. **Minimal Intrusion**: Instrumentation should not alter existing control flow
-2. **Zero-Cost When Disabled**: Use compile-time flags and no-op implementations
-3. **Backward Compatibility**: Protocol Buffer extensions use high field numbers
-4. **Graceful Degradation**: Tracing failures must not affect node operation
-
---
-
-## 3.3 Performance Overhead Summary
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Metric        | Overhead   | Notes                                            |
-| ------------- | ---------- | ------------------------------------------------ |
-| CPU           | 1-3%       | Of per-transaction CPU cost (~200μs baseline)    |
-| Memory        | ~10 MB     | SDK statics + batch buffer + worker thread stack |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector              |
-| Latency (p99) | <2%        | With proper sampling configuration               |
-
---
-
-## 3.4 Detailed CPU Overhead Analysis
-
-### 3.4.1 Per-Operation Costs
-
-> **Note on hardware assumptions**: The costs below are based on the official OTel C++ SDK CI benchmarks
-> (969 runs on GitHub Actions 2-core shared runners). On production server hardware (3+ GHz Xeon),
-> expect costs at the **lower end** of each range (~30-50% improvement over CI hardware).
-
-| Operation             | Time (ns) | Frequency              | Impact     |
-| --------------------- | --------- | ---------------------- | ---------- |
-| Span creation         | 500-1000  | Every traced operation | Low        |
-| Span end              | 100-200   | Every traced operation | Low        |
-| SetAttribute (string) | 80-120    | 3-5 per span           | Low        |
-| SetAttribute (int)    | 40-60     | 2-3 per span           | Negligible |
-| AddEvent              | 100-200   | 0-2 per span           | Low        |
-| Context injection     | 150-250   | Per outgoing message   | Low        |
-| Context extraction    | 100-180   | Per incoming message   | Low        |
-| GetCurrent context    | 10-20     | Thread-local access    | Negligible |
-
-**Source**: Span creation based on OTel C++ SDK `BM_SpanCreation` benchmark (AlwaysOnSampler +
-SimpleSpanProcessor + InMemoryExporter), median ~1,000 ns on CI hardware. AddEvent includes
-timestamp read + string copy + vector push + mutex acquisition. Context injection/extraction
-confirmed by `BM_SpanCreationWithScope` benchmark delta (~160 ns).
-
-### 3.4.2 Transaction Processing Overhead
-
-<div align="center">
-
-```mermaid
-%%{init: {'pie': {'textPosition': 0.75}}}%%
-pie showData
-    "tx.receive (1400ns)" : 1400
-    "tx.validate (1200ns)" : 1200
-    "tx.relay (1200ns)" : 1200
-    "Context inject (200ns)" : 200
-```
-
-**Transaction Tracing Overhead (~4.0μs total)**
-
-</div>
-
-**Overhead percentage**: 4.0 μs / 200 μs (avg tx processing) = **~2.0%**
-
-> **Breakdown**: Each span (tx.receive, tx.validate, tx.relay) costs ~1,000 ns for creation plus
-> ~200-400 ns for 3-5 attribute sets. Context injection is ~200 ns (confirmed by benchmarks).
-> On production hardware, expect ~2.6 μs total (~1.3% overhead) due to faster span creation (~500-600 ns).
-
-### 3.4.3 Consensus Round Overhead
-
-| Operation              | Count | Cost (ns) | Total      |
-| ---------------------- | ----- | --------- | ---------- |
-| consensus.round span   | 1     | ~1200     | ~1.2 μs    |
-| consensus.phase spans  | 3     | ~1100     | ~3.3 μs    |
-| proposal.receive spans | ~20   | ~1100     | ~22 μs     |
-| proposal.send spans    | ~3    | ~1100     | ~3.3 μs    |
-| Context operations     | ~30   | ~200      | ~6 μs      |
-| **TOTAL**              |       |           | **~36 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for 1-2 attributes, totaling ~1,100-1,200 ns.
-> Context operations remain ~200 ns (confirmed by benchmarks). On production hardware, expect ~24 μs total.
-
-**Overhead percentage**: 36 μs / 3s (typical round) = **~0.001%** (negligible)
-
-### 3.4.4 RPC Request Overhead
-
-| Operation        | Cost (ns)    |
-| ---------------- | ------------ |
-| rpc.request span | ~1200        |
-| rpc.command span | ~1100        |
-| Context extract  | ~250         |
-| Context inject   | ~200         |
-| **TOTAL**        | **~2.75 μs** |
-
-> **Why higher**: Each span costs ~1,000 ns creation + ~100-200 ns for attributes (command name,
-> version, role). Context extract/inject costs are confirmed by OTel C++ benchmarks.
-
- Fast RPC (1ms): 2.75 μs / 1ms = **~0.275%**
- Slow RPC (100ms): 2.75 μs / 100ms = **~0.003%**
-
---
-
-## 3.5 Memory Overhead Analysis
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 3.5.1 Static Memory
-
-| Component                            | Size        | Allocated  |
-| ------------------------------------ | ----------- | ---------- |
-| TracerProvider singleton             | ~64 KB      | At startup |
-| BatchSpanProcessor (circular buffer) | ~16 KB      | At startup |
-| BatchSpanProcessor (worker thread)   | ~8 MB       | At startup |
-| OTLP/HTTP exporter (client init)     | ~64 KB      | At startup |
-| Propagator registry                  | ~8 KB       | At startup |
-| **Total static**                     | **~8.1 MB** |            |
-
-> **Why higher than earlier estimate**: The BatchSpanProcessor's circular buffer itself is only ~16 KB
-> (2049 x 8-byte `AtomicUniquePtr` entries), but it spawns a dedicated worker thread whose default
-> stack size on Linux is ~8 MB. The OTLP/HTTP exporter allocates a small client and TLS
-> initialization buffer. The worker thread stack dominates the static footprint.
-
-### 3.5.2 Dynamic Memory
-
-| Component            | Size per unit  | Max units  | Peak            |
-| -------------------- | -------------- | ---------- | --------------- |
-| Active span          | ~500-800 bytes | 1000       | ~500-800 KB     |
-| Queued span (export) | ~500 bytes     | 2048       | ~1 MB           |
-| Attribute storage    | ~80 bytes      | 5 per span | Included        |
-| Context storage      | ~64 bytes      | Per thread | ~6.4 KB         |
-| **Total dynamic**    |                |            | **~1.5-1.8 MB** |
-
-> **Why active spans are larger**: An active `Span` object includes the wrapper (~88 bytes: shared_ptr,
-> mutex, unique_ptr to Recordable) plus `SpanData` (~250 bytes: SpanContext, timestamps, name, status,
-> empty containers) plus attribute storage (~200-500 bytes for 3-5 string attributes in a `std::map`).
-> Source: `sdk/src/trace/span.h` and `sdk/include/opentelemetry/sdk/trace/span_data.h`.
-> Queued spans release the wrapper, keeping only `SpanData` + attributes (~500 bytes).
-
-### 3.5.3 Memory Growth Characteristics
-
-```mermaid
---
-config:
-    xyChart:
-        width: 700
-        height: 400
---
-xychart-beta
-    title "Memory Usage vs Span Rate (bounded by queue limit)"
-    x-axis "Spans/second" [0, 200, 400, 600, 800, 1000]
-    y-axis "Memory (MB)" 0 --> 12
-    line [8.5, 9.2, 9.6, 9.9, 10.0, 10.0]
-```
-
-**Notes**:
-
- Memory increases with span rate but **plateaus at queue capacity** (default 2048 spans)
- Batch export prevents unbounded growth
- At queue limit, oldest spans are dropped (not blocked)
- Maximum memory is bounded: ~8.3 MB static (dominated by worker thread stack) + 2048 queued spans x ~500 bytes (~1 MB) + active spans (~0.8 MB) ≈ **~10 MB ceiling**
- The worker thread stack (~8 MB) is virtual memory; actual RSS depends on stack usage (typically much less)
-
-> **Measured outcome**: A perf-iac comparison (telemetry compiled-in + enabled vs compiled-out,
-> 9 nodes — validators and client-handlers — under sustained payment load) recorded **no measurable
-> RSS increase over the telemetry-off baseline** (~15 GiB mean / ~18–19 GiB peak on both sides),
-> with no OOM, no swap, and no leak across the run. The ~10 MB ceiling above is therefore a
-> provisioning safety margin (dominated by virtual thread-stack address space), not an expected
-> resident-memory increase. Steady-state cost shows up as throughput (~3–4% at head sampling 1.0),
-> not memory.
-
-### 3.5.4 Performance Data Sources
-
-The overhead estimates in Sections 3.3-3.5 are derived from the following sources:
-
-| Source                                           | What it covers                                        | URL                                                                                                                                        |
-| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| OTel C++ SDK CI benchmarks (969 runs)            | Span creation, context activation, sampler overhead   | [Benchmark Dashboard](https://open-telemetry.github.io/opentelemetry-cpp/benchmarks/)                                                      |
-| `api/test/trace/span_benchmark.cc`               | API-level span creation (~22 ns no-op)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/api/test/trace/span_benchmark.cc)                                   |
-| `sdk/test/trace/sampler_benchmark.cc`            | SDK span creation with samplers (~1,000 ns AlwaysOn)  | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/test/trace/sampler_benchmark.cc)                                |
-| `sdk/include/.../span_data.h`                    | SpanData memory layout (~250 bytes base)              | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/span_data.h)                    |
-| `sdk/src/trace/span.h`                           | Span wrapper memory layout (~88 bytes)                | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/src/trace/span.h)                                               |
-| `sdk/include/.../batch_span_processor_options.h` | Default queue size (2048), batch size (512)           | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/trace/batch_span_processor_options.h) |
-| `sdk/include/.../circular_buffer.h`              | CircularBuffer implementation (AtomicUniquePtr array) | [Source](https://github.com/open-telemetry/opentelemetry-cpp/blob/main/sdk/include/opentelemetry/sdk/common/circular_buffer.h)             |
-| OTLP proto definition                            | Serialized span size estimation                       | [Proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto)                          |
-
---
-
-## 3.6 Network Overhead Analysis
-
-### 3.6.1 Export Bandwidth
-
-> **Bytes per span**: Estimates use ~500 bytes/span (conservative upper bound). OTLP protobuf analysis
-> shows a typical span with 3-5 string attributes serializes to ~200-300 bytes raw; with gzip
-> compression (~60-70% of raw) and batching (amortized headers), ~350 bytes/span is more realistic.
-> The table uses the conservative estimate for capacity planning.
-
-| Sampling Rate | Spans/sec | Bandwidth | Notes            |
-| ------------- | --------- | --------- | ---------------- |
-| 100%          | ~500      | ~250 KB/s | Development only |
-| 10%           | ~50       | ~25 KB/s  | Staging          |
-| 1%            | ~5        | ~2.5 KB/s | Production       |
-| Error-only    | ~1        | ~0.5 KB/s | Minimal overhead |
-
-### 3.6.2 Trace Context Propagation
-
-| Message Type           | Context Size | Messages/sec | Overhead    |
-| ---------------------- | ------------ | ------------ | ----------- |
-| TMTransaction          | 25 bytes     | ~100         | ~2.5 KB/s   |
-| TMProposeSet           | 25 bytes     | ~10          | ~250 B/s    |
-| TMValidation           | 25 bytes     | ~50          | ~1.25 KB/s  |
-| **Total P2P overhead** |              |              | **~4 KB/s** |
-
---
-
-## 3.7 Optimization Strategies
-
-### 3.7.1 Sampling Strategies
-
-#### Tail Sampling
-
-```mermaid
-flowchart TD
-    trace["New Trace"]
-
-    trace --> errors{"Is Error?"}
-    errors -->|Yes| sample["SAMPLE"]
-    errors -->|No| consensus{"Is Consensus?"}
-
-    consensus -->|Yes| sample
-    consensus -->|No| slow{"Is Slow?"}
-
-    slow -->|Yes| sample
-    slow -->|No| prob{"Random < 10%?"}
-
-    prob -->|Yes| sample
-    prob -->|No| drop["DROP"]
-
-    style sample fill:#4caf50,stroke:#388e3c,color:#fff
-    style drop fill:#f44336,stroke:#c62828,color:#fff
-```
-
-### 3.7.2 Batch Tuning Recommendations
-
-| Environment        | Batch Size | Batch Delay | Max Queue |
-| ------------------ | ---------- | ----------- | --------- |
-| Low-latency        | 128        | 1000ms      | 512       |
-| High-throughput    | 1024       | 10000ms     | 8192      |
-| Memory-constrained | 256        | 2000ms      | 512       |
-
-### 3.7.3 Conditional Instrumentation
-
-Instrumentation is gated on two levels. A compile-time feature flag (`XRPL_ENABLE_TELEMETRY`) reduces the trace macros to no-ops when telemetry is built out, so disabled builds carry zero cost. At runtime, per-component guards (e.g. `shouldTracePeer()`) skip span creation for components whose tracing is turned off, incurring no overhead beyond a single boolean check.
-
---
-
-## 3.8 Links to Detailed Documentation
-
- **[Configuration Reference](./05-configuration-reference.md)**: Configuration options and collector setup
- **[Implementation Phases](./06-implementation-phases.md)**: Detailed timeline and milestones
-
---
-
-## 3.9 Code Intrusiveness Assessment
-
-> **TxQ** = Transaction Queue
-
-This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing xrpld codebase.
-
-### 3.9.1 Files Modified Summary
-
-| Component             | Files Modified | Lines Added | Lines Changed | Architectural Impact |
-| --------------------- | -------------- | ----------- | ------------- | -------------------- |
-| **Core Telemetry**    | 11 new files   | ~980        | 0             | None (new module)    |
-| **Application Init**  | 2 files        | ~30         | ~5            | Minimal              |
-| **RPC Layer**         | 3 files        | ~80         | ~20           | Minimal              |
-| **Transaction Relay** | 4 files        | ~120        | ~40           | Low                  |
-| **Consensus**         | 3 files        | ~100        | ~30           | Low-Medium           |
-| **Protocol Buffers**  | 1 file         | ~25         | 0             | Low                  |
-| **CMake/Build**       | 3 files        | ~50         | ~10           | Minimal              |
-| **PathFinding**       | 2              | ~80         | ~5            | Minimal              |
-| **TxQ/Fee**           | 2              | ~60         | ~5            | Minimal              |
-| **Validator/Amend**   | 3              | ~40         | ~5            | Minimal              |
-| **Total**             | **~34 files**  | **~1,670**  | **~120**      | **Low**              |
-
-### 3.9.2 Detailed File Impact
-
-```mermaid
-pie title Code Changes by Component
-    "New Telemetry Module" : 800
-    "Transaction Relay" : 160
-    "Consensus" : 130
-    "RPC Layer" : 100
-    "PathFinding" : 80
-    "TxQ/Fee" : 60
-    "Validator/Amendment" : 40
-    "Application Init" : 35
-    "Protocol Buffers" : 25
-    "Build System" : 60
-```
-
-#### New Files (No Impact on Existing Code)
-
-| File                                             | Lines | Purpose                  |
-| ------------------------------------------------ | ----- | ------------------------ |
-| `include/xrpl/telemetry/Telemetry.h`             | ~160  | Main interface           |
-| `include/xrpl/telemetry/TelemetryConfig.h`       | ~80   | Configuration structures |
-| `include/xrpl/telemetry/TraceContext.h`          | ~80   | Context propagation      |
-| `include/xrpl/telemetry/SpanGuard.h`             | ~120  | RAII wrapper             |
-| `include/xrpl/telemetry/SpanAttributes.h`        | ~60   | Attribute helpers        |
-| `src/libxrpl/telemetry/Telemetry.cpp`            | ~200  | Implementation           |
-| `src/libxrpl/telemetry/TelemetryConfig.cpp`      | ~60   | Config parsing           |
-| `src/libxrpl/telemetry/TraceContext.cpp`         | ~80   | Context serialization    |
-| `src/libxrpl/telemetry/NullTelemetry.cpp`        | ~40   | No-op implementation     |
-| `src/xrpld/telemetry/TracingInstrumentation.h`   | ~60   | Macros                   |
-| `src/xrpld/telemetry/TracingInstrumentation.cpp` | ~40   | Instrumentation impl     |
-
-#### Modified Files (Existing Xrpld Code)
-
-| File                                              | Lines Added | Lines Changed | Risk Level |
-| ------------------------------------------------- | ----------- | ------------- | ---------- |
-| `src/xrpld/app/main/Application.cpp`              | ~15         | ~3            | Low        |
-| `include/xrpl/core/ServiceRegistry.h`             | ~5          | ~2            | Low        |
-| `src/xrpld/rpc/detail/ServerHandler.cpp`          | ~40         | ~10           | Low        |
-| `src/xrpld/rpc/handlers/*.cpp`                    | ~30         | ~8            | Low        |
-| `src/xrpld/overlay/detail/PeerImp.cpp`            | ~60         | ~15           | Medium     |
-| `src/xrpld/overlay/detail/OverlayImpl.cpp`        | ~30         | ~10           | Medium     |
-| `src/xrpld/app/consensus/RCLConsensus.cpp`        | ~50         | ~15           | Medium     |
-| `src/xrpld/app/consensus/RCLConsensusAdaptor.cpp` | ~40         | ~12           | Medium     |
-| `src/xrpld/core/JobQueue.cpp`                     | ~20         | ~5            | Low        |
-| `src/xrpld/app/paths/PathRequest.cpp`             | ~40         | ~3            | Low        |
-| `src/xrpld/app/paths/Pathfinder.cpp`              | ~40         | ~2            | Low        |
-| `src/xrpld/app/misc/TxQ.cpp`                      | ~40         | ~3            | Low        |
-| `src/xrpld/app/main/LoadManager.cpp`              | ~20         | ~2            | Low        |
-| `src/xrpld/app/misc/ValidatorList.cpp`            | ~20         | ~2            | Low        |
-| `src/xrpld/app/misc/AmendmentTable.cpp`           | ~10         | ~2            | Low        |
-| `src/xrpld/app/misc/Manifest.cpp`                 | ~10         | ~1            | Low        |
-| `src/xrpld/shamap/SHAMap.cpp`                     | ~20         | ~3            | Low        |
-| `src/xrpld/overlay/detail/ripple.proto`           | ~25         | 0             | Low        |
-| `CMakeLists.txt`                                  | ~40         | ~8            | Low        |
-| `cmake/FindOpenTelemetry.cmake`                   | ~50         | 0             | None (new) |
-
-### 3.9.3 Risk Assessment by Component
-
-<div align="center">
-
-**Do First** ↖ ↗ **Plan Carefully**
-
-```mermaid
-quadrantChart
-    title Code Intrusiveness Risk Matrix
-    x-axis Low Risk --> High Risk
-    y-axis Low Value --> High Value
-
-    RPC Tracing: [0.2, 0.55]
-    Transaction Relay: [0.55, 0.85]
-    Consensus Tracing: [0.75, 0.92]
-    Peer Message Tracing: [0.85, 0.35]
-    JobQueue Context: [0.3, 0.42]
-    Ledger Acquisition: [0.48, 0.65]
-    PathFinding: [0.38, 0.72]
-    TxQ and Fees: [0.25, 0.62]
-    Validator Mgmt: [0.15, 0.35]
-```
-
-**Optional** ↙ ↘ **Avoid**
-
-</div>
-
-#### Risk Level Definitions
-
-| Risk Level | Definition                                                       | Mitigation                         |
-| ---------- | ---------------------------------------------------------------- | ---------------------------------- |
-| **Low**    | Additive changes only; no modification to existing logic         | Standard code review               |
-| **Medium** | Minor modifications to existing functions; clear boundaries      | Comprehensive unit tests           |
-| **High**   | Changes to core logic or data structures; potential side effects | Integration tests + staged rollout |
-
-### 3.9.4 Architectural Impact Assessment
-
-| Aspect               | Impact  | Justification                                                                    |
-| -------------------- | ------- | -------------------------------------------------------------------------------- |
-| **Data Flow**        | Minimal | Read-only instrumentation; no modification to consensus or transaction data flow |
-| **Threading Model**  | Minimal | Context propagation uses thread-local storage (standard OTel pattern)            |
-| **Memory Model**     | Low     | Bounded queues prevent unbounded growth; RAII ensures cleanup                    |
-| **Network Protocol** | Low     | Optional fields in protobuf (high field numbers); backward compatible            |
-| **Configuration**    | None    | New config section; existing configs unaffected                                  |
-| **Build System**     | Low     | Optional CMake flag; builds work without OpenTelemetry                           |
-| **Dependencies**     | Low     | OpenTelemetry SDK is optional; null implementation when disabled                 |
-
-### 3.9.5 Backward Compatibility
-
-| Compatibility   | Status  | Notes                                                 |
-| --------------- | ------- | ----------------------------------------------------- |
-| **Config File** | ✅ Full | New `[telemetry]` section is optional                 |
-| **Protocol**    | ✅ Full | Optional protobuf fields with high field numbers      |
-| **Build**       | ✅ Full | `XRPL_ENABLE_TELEMETRY=OFF` produces identical binary |
-| **Runtime**     | ✅ Full | `enabled=0` produces zero overhead                    |
-| **API**         | ✅ Full | No changes to public RPC or P2P APIs                  |
-
-### 3.9.6 Rollback Strategy
-
-If issues are discovered after deployment:
-
-1. **Immediate**: Set `enabled=0` in config and restart (zero code change)
-2. **Quick**: Rebuild with `XRPL_ENABLE_TELEMETRY=OFF`
-3. **Complete**: Revert telemetry commits (clean separation makes this easy)
-
-### 3.9.7 Code Change Examples
-
-**Minimal RPC Instrumentation (Low Intrusiveness):** Instrumenting an RPC handler adds roughly 3-4 lines: one macro to start the span and one or two `setAttribute` calls (command name, status). The span ends automatically via RAII, so the existing control flow — process the request, send the result — is untouched.
-
-**Consensus Instrumentation (Medium Intrusiveness):** Consensus is slightly more intrusive because child spans in later phase transitions need the round's context. Beyond the span-start and attribute macros, this requires storing the active context in a new member variable (`currentRoundContext_`) at round start. The existing round logic itself remains unchanged.
-
---
-
-_Previous: [Design Decisions](./02-design-decisions.md)_ | _Next: [Configuration Reference](./05-configuration-reference.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/05-configuration-reference.md
+++ b/OpenTelemetryPlan/05-configuration-reference.md
@@ -1,265 +0,0 @@
-# Configuration Reference
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md)
-
---
-
-## 5.1 xrpld Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-### 5.1.1 Configuration File Section
-
-The authoritative `[telemetry]` example lives in `cfg/xrpld-example.cfg`. Telemetry is disabled by default (`enabled=0`); enabling it turns on distributed tracing for transaction flow, consensus, and RPC calls, with traces exported to an OpenTelemetry Collector over OTLP. Head sampling is intentionally fixed at 1.0 (sample everything) and is not configurable — per-node head-sampling would produce broken/partial distributed traces, so volume reduction is delegated to the collector's tail sampling (see Section 7.4.2). The full option reference follows.
-
-### 5.1.2 Configuration Options Summary
-
-| Option                | Type   | Default                           | Description                                          |
-| --------------------- | ------ | --------------------------------- | ---------------------------------------------------- |
-| `enabled`             | bool   | `false`                           | Enable/disable telemetry                             |
-| `endpoint`            | string | `http://localhost:4318/v1/traces` | OTLP/HTTP collector endpoint                         |
-| `use_tls`             | bool   | `false`                           | Enable TLS for exporter connection                   |
-| `tls_ca_cert`         | string | `""`                              | Path to CA certificate file                          |
-| `batch_size`          | uint   | `512`                             | Spans per export batch                               |
-| `batch_delay_ms`      | uint   | `5000`                            | Max delay before sending batch (ms)                  |
-| `max_queue_size`      | uint   | `2048`                            | Maximum queued spans                                 |
-| `trace_transactions`  | bool   | `true`                            | Enable transaction tracing                           |
-| `trace_consensus`     | bool   | `true`                            | Enable consensus tracing                             |
-| `trace_rpc`           | bool   | `true`                            | Enable RPC tracing                                   |
-| `trace_peer`          | bool   | `true`                            | Enable peer message tracing (high volume)            |
-| `trace_ledger`        | bool   | `true`                            | Enable ledger tracing                                |
-| `service_name`        | string | `"xrpld"`                         | Service name (`service.name`) for traces and metrics |
-| `service_instance_id` | string | `<node_pubkey>`                   | Instance identifier                                  |
-
-**Planned (not yet implemented)**: the following options appear in the design
-documents but are not parsed by `TelemetryConfig.cpp` in Phase 1b and later
-phases. They will be added as the corresponding subsystems are instrumented:
-
-| Option                     | Planned Phase | Purpose                                                                 |
-| -------------------------- | ------------- | ----------------------------------------------------------------------- |
-| `exporter`                 | Future        | Select between OTLP/HTTP and OTLP/gRPC                                  |
-| `trace_pathfind`           | Phase 2       | Path computation tracing toggle                                         |
-| `trace_txq`                | Phase 3       | Transaction queue tracing toggle                                        |
-| `trace_validator`          | Future        | Validator list / manifest update tracing                                |
-| `trace_amendment`          | Future        | Amendment voting tracing                                                |
-| `consensus_trace_strategy` | Phase 4       | Trace ID strategy for consensus rounds (`deterministic` \| `attribute`) |
-
---
-
-## 5.2 Configuration Parser
-
-> **TxQ** = Transaction Queue
-
-The parser `setup_Telemetry()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` reads the `[telemetry]` `Section` and populates a `Telemetry::Setup` struct, applying the defaults listed in Section 5.1.2 via `section.value_or(...)`. It derives `serviceInstanceId` from the node public key when not overridden, selects the exporter endpoint default by exporter type, and leaves the sampling ratio at its fixed 1.0 default (not read from config — see Section 7.4.2).
-
---
-
-## 5.3 Application Integration
-
-### 5.3.1 ApplicationImp Changes
-
-> **Deferred identity**: The node public key (`nodeIdentity_`) is not
-> available during `ApplicationImp`'s member initializer list — it is
-> resolved later in `setup()`. The `Telemetry` object is therefore
-> constructed with an empty `serviceInstanceId` and patched via
-> `setServiceInstanceId()` once `setup()` has called `getNodeIdentity()`.
-
-`ApplicationImp` (in `src/xrpld/app/main/Application.cpp`) owns a `std::unique_ptr<telemetry::Telemetry> telemetry_`. It is built in the member initializer list via `make_Telemetry(setup_Telemetry(...))` with an empty `serviceInstanceId`, then patched in `setup()` by calling `setServiceInstanceId()` with the Base58 node public key (unless the user supplied a custom `service_instance_id`). `start()` and `run()` forward to `telemetry_->start()` / `telemetry_->stop()`, and `getTelemetry()` returns the owned instance.
-
-### 5.3.2 ServiceRegistry Interface Addition
-
-`include/xrpl/core/ServiceRegistry.h` gains a pure-virtual `telemetry::Telemetry& getTelemetry()` (with a forward declaration of `telemetry::Telemetry`), giving every component a uniform accessor for the tracing subsystem.
-
-> **Note:** `Application` extends `ServiceRegistry`, so `getTelemetry()` is
-> available on both. Components that hold a `ServiceRegistry&` (e.g.
-> `NetworkOPsImp`) call `registry_.get().getTelemetry()`. Components that
-> still hold an `Application&` (e.g. `ServerHandler`, `PeerImp`,
-> `RCLConsensusAdaptor`) call `app_.getTelemetry()` directly.
-
---
-
-## 5.4 CMake Integration
-
-> **OTLP** = OpenTelemetry Protocol
-
-### 5.4.1 Find OpenTelemetry Module
-
-A `cmake/FindOpenTelemetry.cmake` module locates the OpenTelemetry C++ SDK. It first tries `find_package(opentelemetry-cpp CONFIG)`, aliasing the imported targets `OpenTelemetry::api`, `OpenTelemetry::sdk`, and `OpenTelemetry::otlp_grpc_exporter`, and falls back to `pkg-config` when no CMake config package is present.
-
-### 5.4.2 CMakeLists.txt Changes
-
-The top-level `CMakeLists.txt` adds an `XRPL_ENABLE_TELEMETRY` option (default `OFF`). When enabled, it runs `find_package(OpenTelemetry REQUIRED)`, defines the `XRPL_ENABLE_TELEMETRY` compile flag, and builds the `xrpl_telemetry` library from the real telemetry sources linked against the OpenTelemetry targets; when disabled, it builds the same target from a no-op `NullTelemetry.cpp` so call sites compile unchanged.
-
---
-
-## 5.5 OpenTelemetry Collector Configuration
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-The authoritative collector config lives in the repo at `docker/telemetry/otel-collector-config.yaml` (with Tempo backend config in `docker/telemetry/tempo.yaml`). The sections below summarize the development and production shapes of that pipeline.
-
-### 5.5.1 Development Configuration
-
-The development collector enables an OTLP receiver on both gRPC (`0.0.0.0:4317`) and HTTP (`0.0.0.0:4318`), a single `batch` processor (1s timeout, batch size 100), and two exporters: a `logging` exporter for console debugging and `otlp/tempo` (insecure) for trace visualization. The single `traces` pipeline wires receiver → batch → both exporters.
-
-### 5.5.2 Production Configuration
-
-The production collector adds TLS on the OTLP gRPC receiver and a richer processor chain: a `memory_limiter` (OOM guard), `batch` (5s timeout, size 512), `tail_sampling`, and an `attributes` processor that hashes sensitive fields (e.g. `tx_account`) and stamps `deployment.environment`. Tail sampling keeps all `ERROR` traces, slow consensus rounds (>5s) and slow RPC requests (>1s), and probabilistically samples the remainder at 10%. Exporters target Grafana Tempo (TLS) and Elastic APM; `health_check` and `zpages` extensions are enabled for operability.
-
---
-
-## 5.6 Docker Compose Development Environment
-
-> **OTLP** = OpenTelemetry Protocol
-
-The authoritative development stack lives in the repo at `docker/telemetry/docker-compose.yml`. It brings up four services on a shared `xrpld-telemetry` network: an `otel-collector` (otel/opentelemetry-collector-contrib) exposing OTLP gRPC `4317`, OTLP HTTP `4318`, and health check `13133`; `tempo` for trace storage/visualization; `grafana` with provisioned datasources and dashboards (anonymous admin enabled); and an optional `prometheus` for metric correlation.
-
---
-
-## 5.7 Configuration Architecture
-
-> **OTLP** = OpenTelemetry Protocol
-
-```mermaid
-flowchart TB
-    subgraph config["Configuration Sources"]
-        cfgFile["xrpld.cfg<br/>[telemetry] section"]
-        cmake["CMake<br/>XRPL_ENABLE_TELEMETRY"]
-    end
-
-    subgraph init["Initialization"]
-        parse["setup_Telemetry()"]
-        factory["make_Telemetry()"]
-    end
-
-    subgraph runtime["Runtime Components"]
-        tracer["TracerProvider"]
-        exporter["OTLP Exporter"]
-        processor["BatchProcessor"]
-    end
-
-    subgraph collector["Collector Pipeline"]
-        recv["Receivers"]
-        proc["Processors"]
-        exp["Exporters"]
-    end
-
-    cfgFile --> parse
-    cmake -->|"compile flag"| parse
-    parse --> factory
-    factory --> tracer
-    tracer --> processor
-    processor --> exporter
-    exporter -->|"OTLP"| recv
-    recv --> proc
-    proc --> exp
-
-    style config fill:#e3f2fd,stroke:#1976d2
-    style runtime fill:#e8f5e9,stroke:#388e3c
-    style collector fill:#fff3e0,stroke:#ff9800
-```
-
-**Reading the diagram:**
-
- **Configuration Sources**: `xrpld.cfg` provides runtime settings (endpoint, per-component trace toggles) while the CMake flag controls whether telemetry is compiled in at all. Head sampling is fixed at 1.0 and is not a config option; volume reduction happens via tail sampling in the collector.
- **Initialization**: `setup_Telemetry()` parses config values, then `make_Telemetry()` constructs the provider, processor, and exporter objects.
- **Runtime Components**: The `TracerProvider` creates spans, the `BatchProcessor` buffers them, and the `OTLP Exporter` serializes and sends them over the wire.
- **OTLP arrow to Collector**: Trace data leaves the xrpld process via OTLP/HTTP and enters the external Collector pipeline. (OTLP/gRPC is future work — see design decisions §2.2.2.)
- **Collector Pipeline**: `Receivers` ingest OTLP data, `Processors` apply sampling/filtering/enrichment, and `Exporters` forward traces to storage backends (Tempo, etc.).
-
---
-
-## 5.8 Grafana Integration
-
-> **APM** = Application Performance Monitoring
-
-Step-by-step instructions for integrating xrpld traces with Grafana.
-
-### 5.8.1 Data Source Configuration
-
-#### Tempo (Recommended)
-
-A Tempo datasource (`grafana/provisioning/datasources/tempo.yaml`, provisioned from `docker/telemetry/grafana/`) points at `http://tempo:3200` and enables `tracesToLogs` (linking to Loki on `service.name`/`tx_hash` and mapping `trace_id` → `traceID`), `serviceMap` against Prometheus, the node graph, and Loki search.
-
-#### Elastic APM
-
-Alternatively, an Elasticsearch datasource (`grafana/provisioning/datasources/elastic-apm.yaml`) of type `elasticsearch` points at `http://elasticsearch:9200` against the `apm-*` index, using `@timestamp` as the time field and mapping the log message/level fields.
-
-### 5.8.2 Dashboard Provisioning
-
-A dashboard provider (`grafana/provisioning/dashboards/dashboards.yaml`) loads the `xrpld` dashboard folder from disk (`/var/lib/grafana/dashboards/rippled`), polling for changes every 30s with deletion disabled.
-
-### 5.8.3 Example Dashboard: RPC Performance
-
-An example `xrpld RPC Performance` dashboard (uid `xrpld-rpc-performance`) sourced from Tempo via TraceQL provides four panels: RPC latency by command (heatmap), RPC error rate by command (timeseries), the top 10 slowest RPC commands by average duration (table), and a recent-traces table.
-
-### 5.8.4 Example Dashboard: Transaction Tracing
-
-An example `xrpld Transaction Tracing` dashboard (uid `xrpld-tx-tracing`) over Tempo provides three panels: transaction throughput (`tx.receive` rate, stat), cross-node relay count (average `span.relay_count` on `tx.relay`, timeseries), and a table of transaction validation errors (`tx.validate` with `status.code=error`).
-
-### 5.8.5 TraceQL Query Examples
-
-Common queries for xrpld traces:
-
-```
-# Find all traces for a specific transaction hash
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-
-# Find slow RPC commands (>100ms)
-{resource.service.name="xrpld" && name=~"rpc.command.*"} | duration > 100ms
-
-# Find consensus rounds taking >5 seconds
-{resource.service.name="xrpld" && name="consensus.round"} | duration > 5s
-
-# Find failed transactions with error details
-{resource.service.name="xrpld" && name="tx.validate" && status.code=error}
-
-# Find transactions relayed to many peers
-{resource.service.name="xrpld" && name="tx.relay"} | span.relay_count > 10
-
-# Compare latency across nodes
-{resource.service.name="xrpld" && name="rpc.command.account_info"} | avg(duration) by (resource.service.instance.id)
-```
-
-### 5.8.6 Correlation with PerfLog
-
-To correlate OpenTelemetry traces with existing PerfLog data:
-
-**Step 1: Configure Loki to ingest PerfLog**
-
-Configure a Promtail scrape job (`promtail-config.yaml`) that tails `/var/log/rippled/perf*.log`, parses each JSON line, and promotes `trace_id`, `ledger_seq`, and `tx_hash` to Loki labels.
-
-**Step 2: Add trace_id to PerfLog entries**
-
-Modify PerfLog so its JSON output includes a `trace_id` field whenever a valid span is active: fetch the current span from the OpenTelemetry runtime context, and if its context is valid, render the trace ID as a 32-character lowercase hex string into the log entry.
-
-**Step 3: Configure Grafana trace-to-logs link**
-
-In the Tempo datasource, set the `tracesToLogs` derived field to link to Loki on the `trace_id` and `tx_hash` tags, with `filterByTraceID: true`.
-
-### 5.8.7 Correlation with Insight/StatsD Metrics
-
-To correlate traces with existing Beast Insight metrics:
-
-**Step 1: Export Insight metrics to Prometheus**
-
-Add a Prometheus scrape job (`prometheus.yaml`) named `xrpld-statsd` targeting the StatsD exporter at `statsd-exporter:9102`.
-
-**Step 2: Add exemplars to metrics**
-
-The OpenTelemetry SDK automatically adds exemplars (trace IDs) to metrics when using the Prometheus exporter, linking metric spikes to specific traces.
-
-**Step 3: Configure Grafana metric-to-trace link**
-
-In the Prometheus datasource, set `exemplarTraceIdDestinations` to map the `trace_id` exemplar to the Tempo datasource.
-
-**Step 4: Dashboard panel with exemplars**
-
-Add a timeseries panel over Prometheus (e.g. `histogram_quantile(0.99, rate(xrpld_rpc_duration_seconds_bucket[5m]))`) with `exemplar: true` enabled.
-
-This allows clicking on metric data points to jump directly to the related trace.
-
---
-
-_Previous: [Implementation Strategy](./03-implementation-strategy.md)_ | _Next: [Implementation Phases](./06-implementation-phases.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/06-implementation-phases.md
+++ b/OpenTelemetryPlan/06-implementation-phases.md
@@ -1,575 +0,0 @@
-# Implementation Phases
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Configuration Reference](./05-configuration-reference.md) | [Observability Backends](./07-observability-backends.md)
-
---
-
-## 6.1 Phase Overview
-
-> **TxQ** = Transaction Queue
-
-```mermaid
-gantt
-    title OpenTelemetry Implementation Timeline
-    dateFormat  YYYY-MM-DD
-    axisFormat  Week %W
-
-    section Phase 1
-    Core Infrastructure        :p1, 2024-01-01, 2w
-    SDK Integration           :p1a, 2024-01-01, 4d
-    Telemetry Interface       :p1b, after p1a, 3d
-    Configuration & CMake     :p1c, after p1b, 3d
-    Unit Tests                :p1d, after p1c, 2d
-    Buffer & Integration      :p1e, after p1d, 2d
-
-    section Phase 2
-    RPC Tracing               :p2, after p1, 2w
-    HTTP Context Extraction   :p2a, after p1, 2d
-    RPC Handler Instrumentation :p2b, after p2a, 4d
-    PathFinding Instrumentation :p2f, after p2b, 2d
-    TxQ Instrumentation       :p2g, after p2f, 2d
-    WebSocket Support         :p2c, after p2g, 2d
-    Integration Tests         :p2d, after p2c, 2d
-    Buffer & Review           :p2e, after p2d, 4d
-
-    section Phase 3
-    Transaction Tracing       :p3, after p2, 2w
-    Protocol Buffer Extension :p3a, after p2, 2d
-    PeerImp Instrumentation   :p3b, after p3a, 3d
-    Fee Escalation Instrumentation :p3f, after p3b, 2d
-    Relay Context Propagation :p3c, after p3f, 3d
-    Multi-node Tests          :p3d, after p3c, 2d
-    Buffer & Review           :p3e, after p3d, 4d
-
-    section Phase 4
-    Consensus Tracing         :p4, after p3, 2w
-    Consensus Round Spans     :p4a, after p3, 3d
-    Proposal Handling         :p4b, after p4a, 3d
-    Validator List & Manifest Tracing :p4f, after p4b, 2d
-    Amendment Voting Tracing  :p4g, after p4f, 2d
-    SHAMap Sync Tracing       :p4h, after p4g, 2d
-    Validation Tests          :p4c, after p4h, 4d
-    Buffer & Review           :p4e, after p4c, 4d
-
-    section Phase 5
-    Documentation & Deploy    :p5, after p4, 1w
-```
-
---
-
-## 6.2 Phase 1: Core Infrastructure (Weeks 1-2)
-
-**Objective**: Establish foundational telemetry infrastructure
-
-### Tasks
-
-| Task | Description                                           |
-| ---- | ----------------------------------------------------- |
-| 1.1  | Add OpenTelemetry C++ SDK to Conan/CMake              |
-| 1.2  | Implement `Telemetry` interface and factory           |
-| 1.3  | Implement `SpanGuard` RAII wrapper                    |
-| 1.4  | Implement configuration parser                        |
-| 1.5  | Integrate into `ApplicationImp`                       |
-| 1.6  | Add conditional compilation (`XRPL_ENABLE_TELEMETRY`) |
-| 1.7  | Create `NullTelemetry` no-op implementation           |
-| 1.8  | Unit tests for core infrastructure                    |
-
-### Exit Criteria
-
- [ ] OpenTelemetry SDK compiles and links
- [ ] Telemetry can be enabled/disabled via config
- [ ] Basic span creation works
- [ ] No performance regression when disabled
- [ ] Unit tests passing
-
---
-
-## 6.3 Phase 2: RPC Tracing (Weeks 3-4)
-
-> **TxQ** = Transaction Queue
-
-**Objective**: Complete tracing for all RPC operations
-
-### Tasks
-
-| Task | Description                                                                |
-| ---- | -------------------------------------------------------------------------- |
-| 2.1  | Implement W3C Trace Context HTTP header extraction                         |
-| 2.2  | Instrument `ServerHandler::onRequest()`                                    |
-| 2.3  | Instrument `RPCHandler::doCommand()`                                       |
-| 2.4  | Add RPC-specific attributes                                                |
-| 2.5  | Instrument WebSocket handler                                               |
-| 2.6  | PathFinding instrumentation (`pathfind.request`, `pathfind.compute` spans) |
-| 2.7  | TxQ instrumentation (`txq.enqueue`, `txq.apply` spans)                     |
-| 2.8  | Integration tests for RPC tracing                                          |
-| 2.9  | Performance benchmarks                                                     |
-| 2.10 | Documentation                                                              |
-
-### Exit Criteria
-
- [ ] All RPC commands traced
- [ ] Trace context propagates from HTTP headers
- [ ] WebSocket and HTTP both instrumented
- [ ] <1ms overhead per RPC call
- [ ] Integration tests passing
-
---
-
-## 6.4 Phase 3: Transaction Tracing (Weeks 5-6)
-
-**Objective**: Trace transaction lifecycle across network
-
-### Tasks
-
-| Task | Description                                          |
-| ---- | ---------------------------------------------------- |
-| 3.1  | Define `TraceContext` Protocol Buffer message        |
-| 3.2  | Implement protobuf context serialization             |
-| 3.3  | Instrument `PeerImp::handleTransaction()`            |
-| 3.4  | Instrument `NetworkOPs::submitTransaction()`         |
-| 3.5  | Instrument HashRouter integration                    |
-| 3.6  | Fee escalation instrumentation (`fee.escalate` span) |
-| 3.7  | Implement relay context propagation                  |
-| 3.8  | Integration tests (multi-node)                       |
-| 3.9  | Performance benchmarks                               |
-
-### Exit Criteria
-
- [ ] Transaction traces span across nodes
- [ ] Trace context in Protocol Buffer messages
- [ ] HashRouter deduplication visible in traces
- [ ] Multi-node integration tests passing
- [ ] <5% overhead on transaction throughput
-
---
-
-## 6.5 Phase 4: Consensus Tracing (Weeks 7-8)
-
-**Objective**: Full observability into consensus rounds
-
-### Tasks
-
-| Task | Description                                    |
-| ---- | ---------------------------------------------- |
-| 4.1  | Instrument `RCLConsensusAdaptor::startRound()` |
-| 4.2  | Instrument phase transitions                   |
-| 4.3  | Instrument proposal handling                   |
-| 4.4  | Instrument validation handling                 |
-| 4.5  | Add consensus-specific attributes              |
-| 4.6  | Correlate with transaction traces              |
-| 4.7  | Validator list and manifest tracing            |
-| 4.8  | Amendment voting tracing                       |
-| 4.9  | SHAMap sync tracing                            |
-| 4.10 | Multi-validator integration tests              |
-| 4.11 | Performance validation                         |
-
-### Exit Criteria
-
- [ ] Complete consensus round traces
- [ ] Phase transitions visible
- [ ] Proposals and validations traced
- [ ] No impact on consensus timing
- [ ] Multi-validator test network validated
-
-### Implementation Status — Phase 4a Plan
-
-Phase 4a (establish-phase gap fill & cross-node correlation) will add:
-
- **Deterministic trace ID** derived from `previousLedger.id()` so all validators
-  in the same round share the same `trace_id` (switchable via
-  `consensus_trace_strategy` config: `"deterministic"` or `"attribute"`).
-  See [Configuration Reference](./05-configuration-reference.md) for full
-  configuration options.
- **Round lifecycle spans**: `consensus.round` with round-to-round span links.
- **Establish phase**: `consensus.establish`, `consensus.update_positions` (with
-  `dispute.resolve` events), `consensus.check` (with threshold tracking).
- **Mode changes**: `consensus.mode_change` spans.
- **Validation**: `consensus.validation.send` with span link to round span
-  (thread-safe cross-thread access via `roundSpanContext_` snapshot).
- **Separation of concerns**: telemetry extracted to private helpers
-  (`startRoundTracing`, `createValidationSpan`, `startEstablishTracing`,
-  `updateEstablishTracing`, `endEstablishTracing`).
-
-The `Phase4_taskList.md` spec document is introduced in the Phase 2 PR (#6424)
-and will contain the full task breakdown and implementation notes.
-
---
-
-## 6.6 Phase 5: Documentation & Deployment (Week 9)
-
-**Objective**: Production readiness
-
-### Tasks
-
-| Task | Description                   |
-| ---- | ----------------------------- |
-| 5.1  | Operator runbook              |
-| 5.2  | Grafana dashboards            |
-| 5.3  | Alert definitions             |
-| 5.4  | Collector deployment examples |
-| 5.5  | Developer documentation       |
-| 5.6  | Training materials            |
-| 5.7  | Final integration testing     |
-
---
-
-## 6.7 Risk Assessment
-
-```mermaid
-quadrantChart
-    title Risk Assessment Matrix
-    x-axis Low Impact --> High Impact
-    y-axis Low Likelihood --> High Likelihood
-    quadrant-1 Mitigate Immediately
-    quadrant-2 Plan Mitigation
-    quadrant-3 Accept Risk
-    quadrant-4 Monitor Closely
-
-    SDK Compat: [0.2, 0.18]
-    Protocol Chg: [0.75, 0.72]
-    Perf Overhead: [0.58, 0.42]
-    Context Prop: [0.4, 0.55]
-    Memory Leaks: [0.85, 0.25]
-```
-
-### Risk Details
-
-| Risk                                 | Likelihood | Impact | Mitigation                              |
-| ------------------------------------ | ---------- | ------ | --------------------------------------- |
-| Protocol changes break compatibility | Medium     | High   | Use high field numbers, optional fields |
-| Performance overhead unacceptable    | Medium     | Medium | Sampling, conditional compilation       |
-| Context propagation complexity       | Medium     | Medium | Phased rollout, extensive testing       |
-| SDK compatibility issues             | Low        | Medium | Pin SDK version, fallback to no-op      |
-| Memory leaks in long-running nodes   | Low        | High   | Memory profiling, bounded queues        |
-
---
-
-## 6.8 Success Metrics
-
-| Metric                   | Target                                                         | Measurement           |
-| ------------------------ | -------------------------------------------------------------- | --------------------- |
-| Trace coverage           | >95% of transaction code paths (independent of sampling ratio) | Sampling verification |
-| CPU overhead             | <3%                                                            | Benchmark tests       |
-| Memory overhead          | <10 MB                                                         | Memory profiling      |
-| Latency impact (p99)     | <2%                                                            | Performance tests     |
-| Trace completeness       | >99% spans with required attrs                                 | Validation script     |
-| Cross-node trace linkage | >90% of multi-hop transactions                                 | Integration tests     |
-
---
-
-## 6.9 Quick Wins and Crawl-Walk-Run Strategy
-
-> **TxQ** = Transaction Queue
-
-This section outlines a prioritized approach to maximize ROI with minimal initial investment.
-
-### 6.9.1 Crawl-Walk-Run Overview
-
-<div align="center">
-
-```mermaid
-flowchart TB
-    subgraph crawl["🐢 CRAWL (Week 1-2)"]
-        direction LR
-        c1[Core SDK Setup] ~~~ c2[RPC Tracing Only] ~~~ c3[PathFinding + TxQ Tracing] ~~~ c4[Single Node]
-    end
-
-    subgraph walk["🚶 WALK (Week 3-5)"]
-        direction LR
-        w1[Transaction Tracing] ~~~ w2[Fee Escalation Tracing] ~~~ w3[Cross-Node Context] ~~~ w4[Basic Dashboards]
-    end
-
-    subgraph run["🏃 RUN (Week 6-9)"]
-        direction LR
-        r1[Consensus Tracing] ~~~ r2[Validator, Amendment,<br/>SHAMap Tracing] ~~~ r3[Full Correlation] ~~~ r4[Production Deploy]
-    end
-
-    crawl --> walk --> run
-
-    style crawl fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style walk fill:#bf360c,stroke:#8c2809,color:#fff
-    style run fill:#0d47a1,stroke:#082f6a,color:#fff
-    style c1 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style c2 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style c3 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style c4 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style w1 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style w2 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style w3 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style w4 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style r1 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style r2 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style r3 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style r4 fill:#0d47a1,stroke:#082f6a,color:#fff
-```
-
-</div>
-
-**Reading the diagram:**
-
- **CRAWL (Weeks 1-2)**: Minimal investment -- set up the SDK, instrument RPC and PathFinding/TxQ handlers, and verify on a single node. Delivers immediate latency visibility.
- **WALK (Weeks 3-5)**: Expand to transaction lifecycle tracing, fee escalation, cross-node context propagation, and basic Grafana dashboards. This is where distributed tracing starts working.
- **RUN (Weeks 6-9)**: Full consensus instrumentation, validator/amendment/SHAMap tracing, end-to-end correlation, and production deployment with sampling and alerting.
- **Arrows (crawl → walk → run)**: Each phase builds on the prior one; you cannot skip ahead because later phases depend on infrastructure established earlier.
-
-### 6.9.2 Quick Wins (Immediate Value)
-
-| Quick Win                      | Value  | When to Deploy |
-| ------------------------------ | ------ | -------------- |
-| **RPC Command Tracing**        | High   | Week 2         |
-| **RPC Latency Histograms**     | High   | Week 2         |
-| **Error Rate Dashboard**       | Medium | Week 2         |
-| **Transaction Submit Tracing** | High   | Week 3         |
-| **Consensus Round Duration**   | Medium | Week 6         |
-
-### 6.9.3 CRAWL Phase (Weeks 1-2)
-
-**Goal**: Get basic tracing working with minimal code changes.
-
-**What You Get**:
-
- RPC request/response traces for all commands
- Latency breakdown per RPC command
- PathFinding and TxQ tracing (directly impacts RPC latency)
- Error visibility with stack traces
- Basic Grafana dashboard
-
-**Code Changes**: ~15 lines in `ServerHandler.cpp`, ~40 lines in new telemetry module
-
-**Why Start Here**:
-
- RPC is the lowest-risk, highest-visibility component
- PathFinding and TxQ are RPC-adjacent and directly affect latency
- Immediate value for debugging client issues
- No cross-node complexity
- Single file modification to existing code
-
-### 6.9.4 WALK Phase (Weeks 3-5)
-
-**Goal**: Add transaction lifecycle tracing across nodes.
-
-**What You Get**:
-
- End-to-end transaction traces from submit to relay
- Fee escalation tracing within the transaction pipeline
- Cross-node correlation (see transaction path)
- HashRouter deduplication visibility
- Relay latency metrics
-
-**Code Changes**: ~120 lines across 4 files, plus protobuf extension
-
-**Why Do This Second**:
-
- Builds on RPC tracing (transactions submitted via RPC)
- Fee escalation is integral to the transaction processing pipeline
- Moderate complexity (requires context propagation)
- High value for debugging transaction issues
-
-### 6.9.5 RUN Phase (Weeks 6-9)
-
-**Goal**: Full observability including consensus.
-
-**What You Get**:
-
- Complete consensus round visibility
- Phase transition timing
- Validator proposal tracking
- Validator list and manifest tracing
- Amendment voting tracing
- SHAMap sync tracing
- Full end-to-end traces (client → RPC → TX → consensus → ledger)
-
-**Code Changes**: ~100 lines across 3 consensus files, plus validator/amendment/SHAMap modules
-
-**Why Do This Last**:
-
- Highest complexity (consensus is critical path)
- Validator, amendment, and SHAMap components are lower priority
- Requires thorough testing
- Lower relative value (consensus issues are rarer)
-
-### 6.9.6 ROI Prioritization Matrix
-
-```mermaid
-quadrantChart
-    title Implementation ROI Matrix
-    x-axis Low Effort --> High Effort
-    y-axis Low Value --> High Value
-    quadrant-1 Quick Wins - Do First
-    quadrant-2 Major Projects - Plan Carefully
-    quadrant-3 Nice to Have - Optional
-    quadrant-4 Time Sinks - Avoid
-
-    RPC Tracing: [0.15, 0.92]
-    TX Submit Trace: [0.3, 0.78]
-    TX Relay Trace: [0.5, 0.88]
-    Consensus Trace: [0.72, 0.72]
-    Peer Msg Trace: [0.85, 0.3]
-    Ledger Acquire: [0.55, 0.52]
-```
-
---
-
-## 6.10 Definition of Done
-
-> **TxQ** = Transaction Queue | **HA** = High Availability
-
-Clear, measurable criteria for each phase.
-
-### 6.10.1 Phase 1: Core Infrastructure
-
-| Criterion       | Measurement                                                | Target                       |
-| --------------- | ---------------------------------------------------------- | ---------------------------- |
-| SDK Integration | `cmake --build` succeeds with `-DXRPL_ENABLE_TELEMETRY=ON` | ✅ Compiles                  |
-| Runtime Toggle  | `enabled=0` produces zero overhead                         | <0.1% CPU difference         |
-| Span Creation   | Unit test creates and exports span                         | Span appears in Tempo        |
-| Configuration   | All config options parsed correctly                        | Config validation tests pass |
-| Documentation   | Developer guide exists                                     | PR approved                  |
-
-**Definition of Done**: All criteria met, PR merged, no regressions in CI.
-
-### 6.10.2 Phase 2: RPC Tracing
-
-| Criterion          | Measurement                        | Target                     |
-| ------------------ | ---------------------------------- | -------------------------- |
-| Coverage           | All RPC commands instrumented      | 100% of commands           |
-| Context Extraction | traceparent header propagates      | Integration test passes    |
-| Attributes         | Command, status, duration recorded | Validation script confirms |
-| Performance        | RPC latency overhead               | <1ms p99                   |
-| Dashboard          | Grafana dashboard deployed         | Screenshot in docs         |
-
-**Definition of Done**: RPC traces visible in Tempo for all commands, dashboard shows latency distribution.
-
-### 6.10.3 Phase 3: Transaction Tracing
-
-| Criterion        | Measurement                     | Target                             |
-| ---------------- | ------------------------------- | ---------------------------------- |
-| Local Trace      | Submit → validate → TxQ traced  | Single-node test passes            |
-| Cross-Node       | Context propagates via protobuf | Multi-node test passes             |
-| Relay Visibility | relay_count attribute correct   | Spot check 100 txs                 |
-| HashRouter       | Deduplication visible in trace  | Duplicate txs show suppressed=true |
-| Performance      | TX throughput overhead          | <5% degradation                    |
-
-**Definition of Done**: Transaction traces span 3+ nodes in test network, performance within bounds.
-
-### 6.10.4 Phase 4: Consensus Tracing
-
-| Criterion            | Measurement                   | Target                    |
-| -------------------- | ----------------------------- | ------------------------- |
-| Round Tracing        | startRound creates root span  | Unit test passes          |
-| Phase Visibility     | All phases have child spans   | Integration test confirms |
-| Proposer Attribution | Proposer ID in attributes     | Spot check 50 rounds      |
-| Timing Accuracy      | Phase durations match PerfLog | <5% variance              |
-| No Consensus Impact  | Round timing unchanged        | Performance test passes   |
-
-**Definition of Done**: Consensus rounds fully traceable, no impact on consensus timing.
-
-### 6.10.5 Phase 5: Production Deployment
-
-| Criterion    | Measurement                  | Target                     |
-| ------------ | ---------------------------- | -------------------------- |
-| Collector HA | Multiple collectors deployed | No single point of failure |
-| Sampling     | Tail sampling configured     | 10% base + errors + slow   |
-| Retention    | Data retained per policy     | 7 days hot, 30 days warm   |
-| Alerting     | Alerts configured            | Error spike, high latency  |
-| Runbook      | Operator documentation       | Approved by ops team       |
-| Training     | Team trained                 | Session completed          |
-
-**Definition of Done**: Telemetry running in production, operators trained, alerts active.
-
-### 6.10.6 Success Metrics Summary
-
-| Phase   | Primary Metric         | Secondary Metric            | Deadline      |
-| ------- | ---------------------- | --------------------------- | ------------- |
-| Phase 1 | SDK compiles and runs  | Zero overhead when disabled | End of Week 2 |
-| Phase 2 | 100% RPC coverage      | <1ms latency overhead       | End of Week 4 |
-| Phase 3 | Cross-node traces work | <5% throughput impact       | End of Week 6 |
-| Phase 4 | Consensus fully traced | No consensus timing impact  | End of Week 8 |
-| Phase 5 | Production deployment  | Operators trained           | End of Week 9 |
-
---
-
-## 6.11 Recommended Implementation Order
-
-Based on ROI analysis, implement in this exact order:
-
-```mermaid
-flowchart TB
-    subgraph week1["Week 1"]
-        t1[1. OpenTelemetry SDK<br/>Conan/CMake integration]
-        t2[2. Telemetry interface<br/>SpanGuard, config]
-    end
-
-    subgraph week2["Week 2"]
-        t3[3. RPC ServerHandler<br/>instrumentation]
-        t4[4. Basic Tempo setup<br/>for testing]
-    end
-
-    subgraph week3["Week 3"]
-        t5[5. Transaction submit<br/>tracing]
-        t6[6. Grafana dashboard<br/>v1]
-    end
-
-    subgraph week4["Week 4"]
-        t7[7. Protobuf context<br/>extension]
-        t8[8. PeerImp tx.relay<br/>instrumentation]
-    end
-
-    subgraph week5["Week 5"]
-        t9[9. Multi-node<br/>integration tests]
-        t10[10. Performance<br/>benchmarks]
-    end
-
-    subgraph week6_8["Weeks 6-8"]
-        t11[11. Consensus<br/>instrumentation]
-        t12[12. Full integration<br/>testing]
-    end
-
-    subgraph week9["Week 9"]
-        t13[13. Production<br/>deployment]
-        t14[14. Documentation<br/>& training]
-    end
-
-    t1 --> t2 --> t3 --> t4
-    t4 --> t5 --> t6
-    t6 --> t7 --> t8
-    t8 --> t9 --> t10
-    t10 --> t11 --> t12
-    t12 --> t13 --> t14
-
-    style week1 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style week2 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style week3 fill:#bf360c,stroke:#8c2809,color:#fff
-    style week4 fill:#bf360c,stroke:#8c2809,color:#fff
-    style week5 fill:#bf360c,stroke:#8c2809,color:#fff
-    style week6_8 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style week9 fill:#4a148c,stroke:#2e0d57,color:#fff
-    style t1 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style t2 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style t3 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style t4 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style t5 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t6 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t7 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t8 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t9 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t10 fill:#ffe0b2,stroke:#ffcc80,color:#1e293b
-    style t11 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style t12 fill:#0d47a1,stroke:#082f6a,color:#fff
-    style t13 fill:#4a148c,stroke:#2e0d57,color:#fff
-    style t14 fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-**Reading the diagram:**
-
- **Week 1 (tasks 1-2)**: Foundation work -- integrate the OpenTelemetry SDK via Conan/CMake and build the `Telemetry` interface with `SpanGuard` and config parsing.
- **Week 2 (tasks 3-4)**: First observable output -- instrument `ServerHandler` for RPC tracing and stand up Tempo so developers can see traces immediately.
- **Weeks 3-5 (tasks 5-10)**: Transaction lifecycle -- add submit tracing, build the first Grafana dashboard, extend protobuf for cross-node context, instrument `PeerImp` relay, then validate with multi-node integration tests and performance benchmarks.
- **Weeks 6-8 (tasks 11-12)**: Consensus deep-dive -- instrument consensus rounds and phases, then run full integration testing across all instrumented paths.
- **Week 9 (tasks 13-14)**: Go-live -- deploy to production with sampling/alerting configured, and deliver documentation and operator training.
- **Arrow chain (t1 → ... → t14)**: Strict sequential dependency; each task's output is a prerequisite for the next.
-
---
-
-_Previous: [Configuration Reference](./05-configuration-reference.md)_ | _Next: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/07-observability-backends.md
+++ b/OpenTelemetryPlan/07-observability-backends.md
@@ -1,407 +0,0 @@
-# Observability Backend Recommendations
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Implementation Phases](./06-implementation-phases.md) | [Appendix](./08-appendix.md)
-
---
-
-## 7.1 Development/Testing Backends
-
-> **OTLP** = OpenTelemetry Protocol
-
-| Backend    | Pros                                | Cons                   | Use Case            |
-| ---------- | ----------------------------------- | ---------------------- | ------------------- |
-| **Tempo**  | Cost-effective, Grafana integration | Requires Grafana stack | Local dev, CI, Prod |
-| **Zipkin** | Simple, lightweight                 | Basic features         | Quick prototyping   |
-
-### Quick Start with Tempo
-
-```bash
-# Start Tempo with OTLP support
-docker run -d --name tempo \
-    -p 3200:3200 \
-    -p 4317:4317 \
-    -p 4318:4318 \
-    grafana/tempo:2.6.1
-```
-
---
-
-## 7.2 Production Backends
-
-> **APM** = Application Performance Monitoring
-
-| Backend           | Pros                                      | Cons                   | Use Case                    |
-| ----------------- | ----------------------------------------- | ---------------------- | --------------------------- |
-| **Grafana Tempo** | Cost-effective, Grafana integration       | Requires Grafana stack | Most production deployments |
-| **Elastic APM**   | Full observability stack, log correlation | Resource intensive     | Existing Elastic users      |
-| **Honeycomb**     | Excellent query, high cardinality         | SaaS cost              | Deep debugging needs        |
-| **Datadog APM**   | Full platform, easy setup                 | SaaS cost              | Enterprise with budget      |
-
-### Backend Selection Flowchart
-
-```mermaid
-flowchart TD
-    start[Select Backend] --> budget{Budget<br/>Constraints?}
-
-    budget -->|Yes| oss[Open Source]
-    budget -->|No| saas{Prefer<br/>SaaS?}
-
-    oss --> existing{Existing<br/>Stack?}
-    existing -->|Grafana| tempo[Grafana Tempo]
-    existing -->|Elastic| elastic[Elastic APM]
-    existing -->|None| tempo
-
-    saas -->|Yes| enterprise{Enterprise<br/>Support?}
-    saas -->|No| oss
-
-    enterprise -->|Yes| datadog[Datadog APM]
-    enterprise -->|No| honeycomb[Honeycomb]
-
-    tempo --> final[Configure Collector]
-    elastic --> final
-    honeycomb --> final
-    datadog --> final
-
-    style start fill:#0f172a,stroke:#020617,color:#fff
-    style budget fill:#334155,stroke:#1e293b,color:#fff
-    style oss fill:#1e293b,stroke:#0f172a,color:#fff
-    style existing fill:#334155,stroke:#1e293b,color:#fff
-    style saas fill:#334155,stroke:#1e293b,color:#fff
-    style enterprise fill:#334155,stroke:#1e293b,color:#fff
-    style final fill:#0f172a,stroke:#020617,color:#fff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style elastic fill:#bf360c,stroke:#8c2809,color:#fff
-    style honeycomb fill:#0d47a1,stroke:#082f6a,color:#fff
-    style datadog fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-**Reading the diagram:**
-
- **Budget Constraints? (Yes)**: Leads to open-source options. If you already run Grafana or Elastic, pick the matching backend; otherwise default to Grafana Tempo.
- **Budget Constraints? (No) → Prefer SaaS?**: If you want a managed service, choose between Datadog (enterprise support) and Honeycomb (developer-focused). If not, fall back to open-source.
- **Terminal nodes (Tempo / Elastic / Honeycomb / Datadog)**: Each represents a concrete backend choice, all of which feed into the same final step.
- **Configure Collector**: Regardless of backend, you always finish by configuring the OTel Collector to export to your chosen destination.
-
---
-
-## 7.3 Recommended Production Architecture
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring | **HA** = High Availability
-
-```mermaid
-flowchart TB
-    subgraph validators["Validator Nodes"]
-        v1[xrpld<br/>Validator 1]
-        v2[xrpld<br/>Validator 2]
-    end
-
-    subgraph stock["Stock Nodes"]
-        s1[xrpld<br/>Stock 1]
-        s2[xrpld<br/>Stock 2]
-    end
-
-    subgraph collector["OTel Collector Cluster"]
-        c1[Collector<br/>DC1]
-        c2[Collector<br/>DC2]
-    end
-
-    subgraph backends["Storage Backends"]
-        tempo[(Grafana<br/>Tempo)]
-        elastic[(Elastic<br/>APM)]
-        archive[(S3/GCS<br/>Archive)]
-    end
-
-    subgraph ui["Visualization"]
-        grafana[Grafana<br/>Dashboards]
-    end
-
-    v1 -->|OTLP| c1
-    v2 -->|OTLP| c1
-    s1 -->|OTLP| c2
-    s2 -->|OTLP| c2
-
-    c1 --> tempo
-    c1 --> elastic
-    c2 --> tempo
-    c2 --> archive
-
-    tempo --> grafana
-    elastic --> grafana
-
-    %% Note: simplified single-collector-per-DC topology shown for clarity
-
-    style validators fill:#b71c1c,stroke:#7f1d1d,color:#ffffff
-    style stock fill:#0d47a1,stroke:#082f6a,color:#ffffff
-    style collector fill:#bf360c,stroke:#8c2809,color:#ffffff
-    style backends fill:#1b5e20,stroke:#0d3d14,color:#ffffff
-    style ui fill:#4a148c,stroke:#2e0d57,color:#ffffff
-```
-
-**Reading the diagram:**
-
- **Validator / Stock Nodes**: All xrpld nodes emit trace data via OTLP. Validators and stock nodes are grouped separately because they may reside in different network zones.
- **Collector Cluster (DC1, DC2)**: Regional collectors receive OTLP from nodes in their datacenter, apply processing (sampling, enrichment), and fan out to multiple backends. Enrichment includes deployment-tier tagging: each collector stamps `deployment.environment` and (as a fallback) `xrpl.network.type` so one Grafana stack can filter data from many collectors by tier.
- **Storage Backends**: Tempo and Elastic provide queryable trace storage; S3/GCS Archive provides long-term cold storage for compliance or post-incident analysis.
- **Grafana Dashboards**: The single visualization layer that queries both Tempo and Elastic, giving operators a unified view of all traces.
- **Data flow direction**: Nodes → Collectors → Storage → Grafana. Each arrow represents a network hop; minimizing collector-to-backend hops reduces latency.
-
-> **Note**: Production deployments should use multiple collector instances behind a load balancer for high availability. The diagram shows a simplified single-collector topology for clarity.
-
---
-
-## 7.4 Architecture Considerations
-
-### 7.4.1 Collector Placement
-
-| Strategy      | Description          | Pros                     | Cons                    |
-| ------------- | -------------------- | ------------------------ | ----------------------- |
-| **Sidecar**   | Collector per node   | Isolation, simple config | Resource overhead       |
-| **DaemonSet** | Collector per host   | Shared resources         | Complexity              |
-| **Gateway**   | Central collector(s) | Centralized processing   | Single point of failure |
-
-**Recommendation**: Use **Gateway** pattern with regional collectors for xrpld networks:
-
- One collector cluster per datacenter/region
- Tail-based sampling at collector level
- Multiple export destinations for redundancy
-
-### 7.4.2 Sampling Strategy
-
-```mermaid
-flowchart LR
-    subgraph head["Head Sampling (Node)"]
-        hs[Node-level head sampling<br/>fixed at 100%<br/>not configurable]
-    end
-
-    subgraph tail["Tail Sampling (Collector)"]
-        ts1[Keep all errors]
-        ts2[Keep slow >5s]
-        ts3[Keep 10% rest]
-    end
-
-    head --> tail
-
-    ts1 --> final[Final Traces]
-    ts2 --> final
-    ts3 --> final
-
-    style head fill:#0d47a1,stroke:#082f6a,color:#fff
-    style tail fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style hs fill:#0d47a1,stroke:#082f6a,color:#fff
-    style ts1 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style ts2 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style ts3 fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style final fill:#bf360c,stroke:#8c2809,color:#fff
-```
-
-**Reading the diagram:**
-
- **Head Sampling (Node)**: xrpld pins head sampling at 100% (sample everything) and does not expose a configurable ratio. This is intentional: a per-node ratio would let different nodes make divergent keep/drop decisions for the same distributed trace, producing broken/partial traces. xrpld uses a `ParentBased` sampler so spans inheriting a remote parent honor the upstream decision. Volume reduction is delegated to the collector's tail sampling.
- **Tail Sampling (Collector)**: The second filter -- the collector inspects completed traces and applies rules: keep all errors, keep anything slower than 5 seconds, and keep 10% of the remainder.
- **Arrow head → tail**: All head-sampled traces flow to the collector, where tail sampling further reduces volume while preserving the most valuable data.
- **Final Traces**: The output after both sampling stages; this is what gets stored and queried. The two-stage approach balances cost with debuggability.
-
-### 7.4.3 Data Retention
-
-| Environment | Hot Storage | Warm Storage | Cold Archive |
-| ----------- | ----------- | ------------ | ------------ |
-| Development | 24 hours    | N/A          | N/A          |
-| Staging     | 7 days      | N/A          | N/A          |
-| Production  | 7 days      | 30 days      | many years   |
-
---
-
-## 7.5 Integration Checklist
-
- [ ] Choose primary backend (Tempo recommended for cost/features)
- [ ] Deploy collector cluster with high availability
- [ ] Configure tail-based sampling for error/latency traces
- [ ] Set up Grafana dashboards for trace visualization
- [ ] Configure alerts for trace anomalies
- [ ] Establish data retention policies
- [ ] Test trace correlation with logs and metrics
-
---
-
-## 7.6 Grafana Dashboard Examples
-
-Pre-built dashboards for xrpld observability.
-
-### 7.6.1 Consensus Health Dashboard
-
-A Tempo-backed dashboard (uid `xrpld-consensus-health`) with four panels, all driven by TraceQL:
-
- **Consensus Round Duration** (timeseries, ms): average `consensus.round` span duration per node instance, with yellow/red thresholds at 4s/5s.
- **Phase Duration Breakdown** (barchart): average duration of `consensus.phase.*` spans grouped by span name.
- **Proposers per Round** (stat): average of the `span.proposers` attribute on `consensus.round` spans.
- **Recent Slow Rounds (>5s)** (table): `consensus.round` spans filtered to `duration > 5s`.
-
-Each panel's TraceQL query is described inline in its bullet above.
-
-### 7.6.2 Node Overview Dashboard
-
-A Tempo-backed dashboard (uid `xrpld-node-overview`) with four panels:
-
- **Active Nodes** (stat): count of distinct `resource.service.instance.id` values seen for the `xrpld` service.
- **Total Transactions (1h)** (stat): count of `tx.receive` spans.
- **Error Rate** (gauge, percent): ratio of `status.code=error` spans to all spans, with yellow/red thresholds at 1%/5%.
- **Service Map** (nodeGraph): Tempo-generated service dependency graph.
-
-### 7.6.3 Alert Rules
-
-Grafana provisions three TraceQL-based alert rules (group `xrpld-tracing-alerts`, evaluated every 1m) against the Tempo datasource:
-
- **Consensus Round Slow** (warning, `for: 5m`): fires when average `consensus.round` duration exceeds 5s.
-
-  ```
-  {resource.service.name="xrpld" && name="consensus.round"} | avg(duration) > 5s
-  ```
-
- **RPC Error Rate Spike** (critical, `for: 2m`): fires when the error rate across `rpc.command.*` spans exceeds 5%. Error _rate_ is a ratio, so it must divide the error-span rate by the total-span rate — a single TraceQL `rate()` returns spans/second, not a percentage, and would fire on traffic volume alone. This uses span metrics emitted by the collector's `spanmetrics` connector (Prometheus datasource), not a TraceQL query:
-
-  ```
-  sum(rate(traces_spanmetrics_calls_total{service_name="xrpld", span_name=~"rpc.command.*", status_code="STATUS_CODE_ERROR"}[5m]))
-  /
-  sum(rate(traces_spanmetrics_calls_total{service_name="xrpld", span_name=~"rpc.command.*"}[5m]))
-  > 0.05
-  ```
-
- **Transaction Throughput Drop** (warning, `for: 10m`): fires when the `tx.receive` span rate falls below 10/s.
-
-  ```
-  {resource.service.name="xrpld" && name="tx.receive"} | rate() < 10
-  ```
-
-> **Note**: The Consensus Round Slow and Transaction Throughput Drop rules use TraceQL aggregates (`avg(duration)`, `rate()`), which require Tempo 2.3+ with TraceQL metrics enabled. Verify aggregate query support in your Tempo version before provisioning. The RPC Error Rate Spike rule instead queries Prometheus span metrics (collector `spanmetrics` connector), so it needs that connector enabled in the collector pipeline.
-
---
-
-## 7.7 PerfLog and Insight Correlation
-
-> **OTLP** = OpenTelemetry Protocol
-
-How to correlate OpenTelemetry traces with existing xrpld observability.
-
-### 7.7.1 Correlation Architecture
-
-```mermaid
-flowchart TB
-    subgraph xrpld["xrpld Node"]
-        otel[OpenTelemetry<br/>Spans]
-        perflog[PerfLog<br/>JSON Logs]
-        insight[Beast Insight<br/>StatsD Metrics]
-    end
-
-    subgraph collectors["Data Collection"]
-        otelc[OTel Collector]
-        promtail[Promtail/Fluentd]
-        statsd[StatsD Exporter]
-    end
-
-    subgraph storage["Storage"]
-        tempo[(Tempo)]
-        loki[(Loki)]
-        prom[(Prometheus)]
-    end
-
-    subgraph grafana["Grafana"]
-        traces[Trace View]
-        logs[Log View]
-        metrics[Metrics View]
-        corr[Correlation<br/>Panel]
-    end
-
-    otel -->|OTLP| otelc --> tempo
-    perflog -->|JSON| promtail --> loki
-    insight -->|StatsD| statsd --> prom
-
-    tempo --> traces
-    loki --> logs
-    prom --> metrics
-
-    traces --> corr
-    logs --> corr
-    metrics --> corr
-
-    style xrpld fill:#0d47a1,stroke:#082f6a,color:#fff
-    style collectors fill:#bf360c,stroke:#8c2809,color:#fff
-    style storage fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style grafana fill:#4a148c,stroke:#2e0d57,color:#fff
-    style otel fill:#0d47a1,stroke:#082f6a,color:#fff
-    style perflog fill:#0d47a1,stroke:#082f6a,color:#fff
-    style insight fill:#0d47a1,stroke:#082f6a,color:#fff
-    style otelc fill:#bf360c,stroke:#8c2809,color:#fff
-    style promtail fill:#bf360c,stroke:#8c2809,color:#fff
-    style statsd fill:#bf360c,stroke:#8c2809,color:#fff
-    style tempo fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style loki fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style prom fill:#1b5e20,stroke:#0d3d14,color:#fff
-    style traces fill:#4a148c,stroke:#2e0d57,color:#fff
-    style logs fill:#4a148c,stroke:#2e0d57,color:#fff
-    style metrics fill:#4a148c,stroke:#2e0d57,color:#fff
-    style corr fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-**Reading the diagram:**
-
- **xrpld Node (three sources)**: A single node emits three independent data streams -- OpenTelemetry spans, PerfLog JSON logs, and Beast Insight StatsD metrics.
- **Data Collection layer**: Each stream has its own collector -- OTel Collector for spans, Promtail/Fluentd for logs, and a StatsD exporter for metrics. They operate independently.
- **Storage layer (Tempo, Loki, Prometheus)**: Each data type lands in a purpose-built store optimized for its query patterns (trace search, log grep, metric aggregation).
- **Grafana Correlation Panel**: The key integration point -- Grafana queries all three stores and links them via shared fields (`trace_id`, `tx_hash`, `ledger_seq`), enabling a single-pane debugging experience.
-
-### 7.7.2 Correlation Fields
-
-| Source      | Field               | Link To       | Purpose                    |
-| ----------- | ------------------- | ------------- | -------------------------- |
-| **Trace**   | `trace_id`          | Logs          | Find log entries for trace |
-| **Trace**   | `tx_hash`           | Logs, Metrics | Find TX-related data       |
-| **Trace**   | `ledger_seq`        | Logs          | Find ledger-related logs   |
-| **PerfLog** | `trace_id` (new)    | Traces        | Jump to trace from log     |
-| **PerfLog** | `ledger_seq`        | Traces        | Find consensus trace       |
-| **Insight** | `exemplar.trace_id` | Traces        | Jump from metric spike     |
-
-### 7.7.3 Example: Debugging a Slow Transaction
-
-**Step 1: Find the trace**
-
-```
-# In Grafana Explore with Tempo
-{resource.service.name="xrpld" && span.tx_hash="ABC123..."}
-```
-
-**Step 2: Get the trace_id from the trace view**
-
-```
-Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
-```
-
-**Step 3: Find related PerfLog entries**
-
-```
-# In Grafana Explore with Loki
-{job="xrpld"} |= "4bf92f3577b34da6a3ce929d0e0e4736"
-```
-
-**Step 4: Check Insight metrics for the time window**
-
-```
-# In Grafana with Prometheus
-rate(xrpld_tx_applied_total[1m])
-  @ timestamp_from_trace
-```
-
-### 7.7.4 Unified Dashboard Example
-
-A single dashboard (uid `xrpld-unified`) that ties traces, metrics, and logs together across the Tempo, Prometheus, and Loki datasources:
-
- **Transaction Latency (Traces)** (timeseries, Tempo): `histogram_over_time(duration)` of `tx.receive` spans.
- **Transaction Rate (Metrics)** (timeseries, Prometheus): `rate(xrpld_tx_received_total[5m])` per instance, with a data link that opens the matching `tx.receive` traces in Tempo.
- **Recent Logs** (logs, Loki): `{job="xrpld"} | json`.
- **Trace Search** (table, Tempo): all `xrpld` traces, with per-row data links on `traceID` that jump to the trace in Tempo and to the correlated logs in Loki (`{job="xrpld"} |= "<traceID>"`).
-
-The cross-datasource data links are what make this a single-pane debugging view; the correlation fields they rely on are listed in section 7.7.2.
-
---
-
-_Previous: [Implementation Phases](./06-implementation-phases.md)_ | _Next: [Appendix](./08-appendix.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/08-appendix.md
+++ b/OpenTelemetryPlan/08-appendix.md
@@ -1,187 +0,0 @@
-# Appendix
-
-> **Parent Document**: [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)
-> **Related**: [Observability Backends](./07-observability-backends.md)
-
---
-
-## 8.1 Glossary
-
-> **OTLP** = OpenTelemetry Protocol | **TxQ** = Transaction Queue
-
-| Term                  | Definition                                                 |
-| --------------------- | ---------------------------------------------------------- |
-| **Span**              | A unit of work with start/end time, name, and attributes   |
-| **Trace**             | A collection of spans representing a complete request flow |
-| **Trace ID**          | 128-bit unique identifier for a trace                      |
-| **Span ID**           | 64-bit unique identifier for a span within a trace         |
-| **Context**           | Carrier for trace/span IDs across boundaries               |
-| **Propagator**        | Component that injects/extracts context                    |
-| **Sampler**           | Decides which traces to record                             |
-| **Exporter**          | Sends spans to backend                                     |
-| **Collector**         | Receives, processes, and forwards telemetry                |
-| **OTLP**              | OpenTelemetry Protocol (wire format)                       |
-| **W3C Trace Context** | Standard HTTP headers for trace propagation                |
-| **Baggage**           | Key-value pairs propagated across service boundaries       |
-| **Resource**          | Entity producing telemetry (service, host, etc.)           |
-| **Instrumentation**   | Code that creates telemetry data                           |
-
-### xrpld-Specific Terms
-
-| Term              | Definition                                                    |
-| ----------------- | ------------------------------------------------------------- |
-| **Overlay**       | P2P network layer managing peer connections                   |
-| **Consensus**     | XRP Ledger consensus algorithm (RCL)                          |
-| **Proposal**      | Validator's suggested transaction set for a ledger            |
-| **Validation**    | Validator's signature on a closed ledger                      |
-| **HashRouter**    | Component for transaction deduplication                       |
-| **JobQueue**      | Thread pool for asynchronous task execution                   |
-| **PerfLog**       | Existing performance logging system in xrpld                  |
-| **Beast Insight** | Existing metrics framework in xrpld                           |
-| **PathFinding**   | Payment path computation engine for cross-currency payments   |
-| **TxQ**           | Transaction queue managing fee-based prioritization           |
-| **LoadManager**   | Dynamic fee escalation based on network load                  |
-| **SHAMap**        | SHA-256 hash-based map (Merkle trie variant) for ledger state |
-
---
-
-## 8.2 Span Hierarchy Visualization
-
-> **TxQ** = Transaction Queue
-
-```mermaid
-flowchart TB
-    subgraph trace["Trace: Transaction Lifecycle"]
-        rpc["rpc.request<br/>(entry point)"]
-        validate["tx.validate"]
-        relay["tx.relay<br/>(parent span)"]
-
-        subgraph peers["Peer Spans"]
-            p1["peer.send<br/>Peer A"]
-            p2["peer.send<br/>Peer B"]
-            p3["peer.send<br/>Peer C"]
-        end
-
-        subgraph pathfinding["PathFinding Spans"]
-            pathfind["pathfind.request"]
-            pathcomp["pathfind.compute"]
-        end
-
-        consensus["consensus.round"]
-        apply["tx.apply"]
-
-        subgraph txqueue["TxQ Spans"]
-            txq["txq.enqueue"]
-            txqApply["txq.apply"]
-        end
-
-        feeCalc["fee.escalate"]
-    end
-
-    subgraph validators["Validator Spans"]
-        valFetch["validator.list.fetch"]
-        valManifest["validator.manifest"]
-    end
-
-    rpc --> validate
-    rpc --> pathfind
-    pathfind --> pathcomp
-    validate --> relay
-    relay --> p1
-    relay --> p2
-    relay --> p3
-    p1 -.->|"context propagation"| consensus
-    consensus --> apply
-    apply --> txq
-    txq --> txqApply
-    txq --> feeCalc
-
-    style trace fill:#0f172a,stroke:#020617,color:#fff
-    style peers fill:#1e3a8a,stroke:#172554,color:#fff
-    style pathfinding fill:#134e4a,stroke:#0f766e,color:#fff
-    style txqueue fill:#064e3b,stroke:#047857,color:#fff
-    style validators fill:#4c1d95,stroke:#6d28d9,color:#fff
-    style rpc fill:#1d4ed8,stroke:#1e40af,color:#fff
-    style validate fill:#047857,stroke:#064e3b,color:#fff
-    style relay fill:#047857,stroke:#064e3b,color:#fff
-    style p1 fill:#0e7490,stroke:#155e75,color:#fff
-    style p2 fill:#0e7490,stroke:#155e75,color:#fff
-    style p3 fill:#0e7490,stroke:#155e75,color:#fff
-    style consensus fill:#fef3c7,stroke:#fde68a,color:#1e293b
-    style apply fill:#047857,stroke:#064e3b,color:#fff
-    style pathfind fill:#0e7490,stroke:#155e75,color:#fff
-    style pathcomp fill:#0e7490,stroke:#155e75,color:#fff
-    style txq fill:#047857,stroke:#064e3b,color:#fff
-    style txqApply fill:#047857,stroke:#064e3b,color:#fff
-    style feeCalc fill:#047857,stroke:#064e3b,color:#fff
-    style valFetch fill:#6d28d9,stroke:#4c1d95,color:#fff
-    style valManifest fill:#6d28d9,stroke:#4c1d95,color:#fff
-```
-
-**Reading the diagram:**
-
- **rpc.request (blue, top)**: The entry point — every traced transaction starts as an RPC call; this root span is the parent of all downstream work.
- **tx.validate and pathfind.request (green/teal, first fork)**: The RPC request fans out into transaction validation and, for cross-currency payments, a PathFinding branch (`pathfind.request` -> `pathfind.compute`).
- **tx.relay -> Peer Spans (teal, middle)**: After validation, the transaction is relayed to peers A, B, and C in parallel; each `peer.send` is a sibling child span showing fan-out across the network.
- **context propagation (dashed arrow)**: The dotted line from `peer.send Peer A` to `consensus.round` represents the trace context crossing a node boundary — the receiving validator picks up the same `trace_id` and continues the trace.
- **consensus.round -> tx.apply -> TxQ Spans (green, lower)**: Once consensus accepts the transaction, it is applied to the ledger; the TxQ spans (`txq.enqueue`, `txq.apply`, `fee.escalate`) capture queue depth and fee escalation behavior.
- **Validator Spans (purple, detached)**: `validator.list.fetch` and `validator.manifest` are independent workflows for UNL management — they run on their own traces and are linked to consensus via Span Links, not parent-child relationships.
-
---
-
-## 8.3 References
-
-> **OTLP** = OpenTelemetry Protocol
-
-### OpenTelemetry Resources
-
-1. [OpenTelemetry C++ SDK](https://github.com/open-telemetry/opentelemetry-cpp)
-2. [OpenTelemetry Specification](https://opentelemetry.io/docs/specs/otel/)
-3. [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
-4. [OTLP Protocol Specification](https://opentelemetry.io/docs/specs/otlp/)
-
-### Standards
-
-5. [W3C Trace Context](https://www.w3.org/TR/trace-context/)
-6. [W3C Baggage](https://www.w3.org/TR/baggage/)
-7. [Protocol Buffers](https://protobuf.dev/)
-
-### xrpld Resources
-
-8. [xrpld Source Code](https://github.com/XRPLF/rippled)
-9. [XRP Ledger Documentation](https://xrpl.org/docs/)
-10. [xrpld Overlay README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/overlay/README.md)
-11. [xrpld RPC README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/rpc/README.md)
-12. [xrpld Consensus README](https://github.com/XRPLF/rippled/blob/develop/src/xrpld/app/consensus/README.md)
-
---
-
-## 8.4 Version History
-
-| Version | Date       | Author | Changes                                                        |
-| ------- | ---------- | ------ | -------------------------------------------------------------- |
-| 1.0     | 2026-02-12 | -      | Initial implementation plan                                    |
-| 1.1     | 2026-02-13 | -      | Refactored into modular documents                              |
-| 1.2     | 2026-03-24 | -      | Review fixes: accuracy corrections, cross-document consistency |
-
---
-
-## 8.5 Document Index
-
-### Plan Documents
-
-| Document                                                         | Description                                  |
-| ---------------------------------------------------------------- | -------------------------------------------- |
-| [OpenTelemetryPlan.md](./OpenTelemetryPlan.md)                   | Master overview and executive summary        |
-| [00-tracing-fundamentals.md](./00-tracing-fundamentals.md)       | Distributed tracing concepts and OTel primer |
-| [01-architecture-analysis.md](./01-architecture-analysis.md)     | xrpld architecture and trace points          |
-| [02-design-decisions.md](./02-design-decisions.md)               | SDK selection, exporters, span conventions   |
-| [03-implementation-strategy.md](./03-implementation-strategy.md) | Directory structure, performance analysis    |
-| [05-configuration-reference.md](./05-configuration-reference.md) | xrpld config, CMake, Collector configs       |
-| [06-implementation-phases.md](./06-implementation-phases.md)     | Timeline, tasks, risks, success metrics      |
-| [07-observability-backends.md](./07-observability-backends.md)   | Backend selection and architecture           |
-| [08-appendix.md](./08-appendix.md)                               | Glossary, references, version history        |
-
---
-
-_Previous: [Observability Backends](./07-observability-backends.md)_ | _Back to: [Overview](./OpenTelemetryPlan.md)_
--- a/OpenTelemetryPlan/OpenTelemetryPlan.md
+++ b/OpenTelemetryPlan/OpenTelemetryPlan.md
@@ -1,199 +0,0 @@
-# [OpenTelemetry](00-tracing-fundamentals.md) Distributed Tracing Implementation Plan for xrpld
-
-## Executive Summary
-
-> **OTLP** = OpenTelemetry Protocol
-
-This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. The plan addresses the unique challenges of a decentralized peer-to-peer system where trace context must propagate across network boundaries between independent nodes.
-
-### Key Benefits
-
- **End-to-end transaction visibility**: Track transactions from submission through consensus to ledger inclusion
- **Consensus round analysis**: Understand timing and behavior of consensus phases across validators
- **RPC performance insights**: Identify slow handlers and optimize response times
- **Network topology understanding**: Visualize message propagation patterns between peers
- **Incident debugging**: Correlate events across distributed nodes during issues
-
-### Estimated Performance Overhead
-
-| Metric        | Overhead   | Notes                                            |
-| ------------- | ---------- | ------------------------------------------------ |
-| CPU           | 1-3%       | Span creation and attribute setting              |
-| Memory        | <10 MB     | SDK statics + batch buffer + worker thread stack |
-| Network       | 10-50 KB/s | Compressed OTLP export to collector              |
-| Latency (p99) | <2%        | With proper sampling configuration               |
-
---
-
-## Document Structure
-
-This implementation plan is organized into modular documents for easier navigation:
-
-<div align="center">
-
-```mermaid
-flowchart TB
-    overview["📋 OpenTelemetryPlan.md<br/>(This Document)"]
-
-    subgraph fundamentals["Fundamentals"]
-        fund["00-tracing-fundamentals.md"]
-    end
-
-    subgraph analysis["Analysis & Design"]
-        arch["01-architecture-analysis.md"]
-        design["02-design-decisions.md"]
-    end
-
-    subgraph impl["Implementation"]
-        strategy["03-implementation-strategy.md"]
-        config["05-configuration-reference.md"]
-    end
-
-    subgraph deploy["Deployment & Planning"]
-        phases["06-implementation-phases.md"]
-        backends["07-observability-backends.md"]
-        appendix["08-appendix.md"]
-    end
-
-    overview --> fundamentals
-    overview --> analysis
-    overview --> impl
-    overview --> deploy
-
-    fund --> arch
-    arch --> design
-    design --> strategy
-    strategy --> config
-    config --> phases
-    phases --> backends
-    backends --> appendix
-
-    style overview fill:#1b5e20,stroke:#0d3d14,color:#fff,stroke-width:2px
-    style fundamentals fill:#00695c,stroke:#004d40,color:#fff
-    style fund fill:#00695c,stroke:#004d40,color:#fff
-    style analysis fill:#0d47a1,stroke:#082f6a,color:#fff
-    style impl fill:#bf360c,stroke:#8c2809,color:#fff
-    style deploy fill:#4a148c,stroke:#2e0d57,color:#fff
-    style arch fill:#0d47a1,stroke:#082f6a,color:#fff
-    style design fill:#0d47a1,stroke:#082f6a,color:#fff
-    style strategy fill:#bf360c,stroke:#8c2809,color:#fff
-    style config fill:#bf360c,stroke:#8c2809,color:#fff
-    style phases fill:#4a148c,stroke:#2e0d57,color:#fff
-    style backends fill:#4a148c,stroke:#2e0d57,color:#fff
-    style appendix fill:#4a148c,stroke:#2e0d57,color:#fff
-```
-
-</div>
-
---
-
-## Table of Contents
-
-| Section | Document                                                   | Description                                                            |
-| ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **0**   | [Tracing Fundamentals](./00-tracing-fundamentals.md)       | Distributed tracing concepts, span relationships, context propagation  |
-| **1**   | [Architecture Analysis](./01-architecture-analysis.md)     | xrpld component analysis, trace points, instrumentation priorities     |
-| **2**   | [Design Decisions](./02-design-decisions.md)               | SDK selection, exporters, span naming, attributes, context propagation |
-| **3**   | [Implementation Strategy](./03-implementation-strategy.md) | Directory structure, key principles, performance optimization          |
-| **5**   | [Configuration Reference](./05-configuration-reference.md) | xrpld config, CMake integration, Collector configurations              |
-| **6**   | [Implementation Phases](./06-implementation-phases.md)     | 5-phase timeline, tasks, risks, success metrics                        |
-| **7**   | [Observability Backends](./07-observability-backends.md)   | Backend selection guide and production architecture                    |
-| **8**   | [Appendix](./08-appendix.md)                               | Glossary, references, version history                                  |
-
---
-
-## 0. Tracing Fundamentals
-
-This document introduces distributed tracing concepts for readers unfamiliar with the domain. It covers what traces and spans are, how parent-child and follows-from relationships model causality, how context propagates across service boundaries, and how sampling controls data volume. It also maps these concepts to xrpld-specific scenarios like transaction relay and consensus.
-
-➡️ **[Read Tracing Fundamentals](./00-tracing-fundamentals.md)**
-
---
-
-## 1. Architecture Analysis
-
-> **WS** = WebSocket | **TxQ** = Transaction Queue
-
-The xrpld node consists of several key components that require instrumentation for comprehensive distributed tracing. The main areas include the RPC server (HTTP/WebSocket), Overlay P2P network, Consensus mechanism (RCLConsensus), JobQueue for async task execution, PathFinding, Transaction Queue (TxQ), fee escalation (LoadManager), ledger acquisition, validator management, and existing observability infrastructure (PerfLog, Insight/StatsD, Journal logging).
-
-Key trace points span across transaction submission via RPC, peer-to-peer message propagation, consensus round execution, ledger building, path computation, transaction queue behavior, fee escalation, and validator health. The implementation prioritizes high-value, low-risk components first: RPC handlers provide immediate value with minimal risk, while consensus tracing requires careful implementation to avoid timing impacts.
-
-➡️ **[Read full Architecture Analysis](./01-architecture-analysis.md)**
-
---
-
-## 2. Design Decisions
-
-> **OTLP** = OpenTelemetry Protocol | **CNCF** = Cloud Native Computing Foundation
-
-The OpenTelemetry C++ SDK is selected for its CNCF backing, active development, and native performance characteristics. Traces are exported via OTLP/HTTP to an OpenTelemetry Collector, which provides flexible routing and sampling. OTLP/gRPC is planned future work (see design decisions §2.2.2).
-
-Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `rpc.submit`, `tx.relay`, `consensus.round`). Context propagation uses W3C Trace Context headers for HTTP and embedded Protocol Buffer fields for P2P messages. The implementation coexists with existing PerfLog and Insight observability systems through correlation IDs.
-
-**Data Collection & Privacy**: Telemetry collects only operational metadata (timing, counts, hashes) — never sensitive content (private keys, balances, amounts, raw payloads). Privacy protection includes account hashing, configurable redaction, sampling, and collector-level filtering. Node operators retain full control over telemetry configuration.
-
-➡️ **[Read full Design Decisions](./02-design-decisions.md)**
-
---
-
-## 3. Implementation Strategy
-
-The telemetry code is organized under `include/xrpl/telemetry/` for headers and `src/libxrpl/telemetry/` for implementation. Key principles include RAII-based span management via `SpanGuard`, conditional compilation with `XRPL_ENABLE_TELEMETRY`, and minimal runtime overhead through batch processing and efficient sampling.
-
-Performance optimization strategies include head sampling fixed at 100% (intentionally not configurable, so trace keep/drop decisions stay coherent across nodes), tail-based sampling at the collector for errors and slow traces to reduce volume, batch export to reduce network overhead, and conditional instrumentation that compiles to no-ops when disabled.
-
-➡️ **[Read full Implementation Strategy](./03-implementation-strategy.md)**
-
---
-
-## 5. Configuration Reference
-
-> **OTLP** = OpenTelemetry Protocol | **APM** = Application Performance Monitoring
-
-Configuration is handled through the `[telemetry]` section in `xrpld.cfg` with options for enabling/disabling, exporter selection, endpoint configuration, and component-level filtering. Head sampling is fixed at 1.0 (not operator-configurable); volume reduction is done by tail sampling in the collector. CMake integration includes a `XRPL_ENABLE_TELEMETRY` option for compile-time control.
-
-OpenTelemetry Collector configurations are provided for development and production (with tail-based sampling, Tempo, and Elastic APM). Docker Compose examples enable quick local development environment setup.
-
-➡️ **[View full Configuration Reference](./05-configuration-reference.md)**
-
---
-
-## 6. Implementation Phases
-
-The implementation spans 9 weeks across 5 phases:
-
-| Phase | Duration  | Focus               | Key Deliverables                                    |
-| ----- | --------- | ------------------- | --------------------------------------------------- |
-| 1     | Weeks 1-2 | Core Infrastructure | SDK integration, Telemetry interface, Configuration |
-| 2     | Weeks 3-4 | RPC Tracing         | HTTP context extraction, Handler instrumentation    |
-| 3     | Weeks 5-6 | Transaction Tracing | Protocol Buffer context, Relay propagation          |
-| 4     | Weeks 7-8 | Consensus Tracing   | Round spans, Proposal/validation tracing            |
-| 5     | Week 9    | Documentation       | Runbook, Dashboards, Training                       |
-
-**Total Effort**: 47 person-days (2 developers working in parallel)
-
-➡️ **[View full Implementation Phases](./06-implementation-phases.md)**
-
---
-
-## 7. Observability Backends
-
-> **APM** = Application Performance Monitoring | **GCS** = Google Cloud Storage
-
-Grafana Tempo is recommended for all environments due to its cost-effectiveness and Grafana integration, while Elastic APM is ideal for organizations with existing Elastic infrastructure.
-
-The recommended production architecture uses a gateway collector pattern with regional collectors performing tail-based sampling, routing traces to multiple backends (Tempo for primary storage, Elastic for log correlation, S3/GCS for long-term archive).
-
-➡️ **[View Observability Backend Recommendations](./07-observability-backends.md)**
-
---
-
-## 8. Appendix
-
-The appendix contains a glossary of OpenTelemetry and xrpld-specific terms, references to external documentation and specifications, version history for this implementation plan, and a complete document index.
-
-➡️ **[View Appendix](./08-appendix.md)**
-
---
-
-_This document provides a comprehensive implementation plan for integrating OpenTelemetry distributed tracing into the xrpld XRP Ledger node software. For detailed information on any section, follow the links to the corresponding sub-documents._
--- a/bin/check-tools.sh
+++ b/bin/check-tools.sh
@@ -30,8 +30,10 @@ missing=()
 checked=0

 # check <name> [probe-command...]
-# Runs the probe (default: "<name> --version") quietly. Records <name> as
-# missing if the command is not found or exits non-zero.
+# Runs the probe (default: "<name> --version"), capturing both stdout and
+# stderr, and prints one aligned line: the status, the name, and the first
+# non-blank line of the probe output (its version). Records <name> as missing
+# if the command is not found or exits non-zero.
 check() {
    local name="$1"
    shift
@@ -40,10 +42,11 @@ check() {
        probe=("${name}" --version)
    fi

-    echo "Checking ${name}..."
    checked=$((checked + 1))
-    if "${probe[@]}" | head -n 1; then
-        printf '  [ ok ] %s\n' "${name}"
+    local output version
+    if output="$("${probe[@]}" 2>&1)"; then
+        version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
+        printf '  [ ok ] %-20s %s\n' "${name}" "${version}"
    else
        printf '  [MISS] %s\n' "${name}"
        missing+=("${name}")
@@ -85,12 +88,14 @@ if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
    check file
    check less
    check make
-    check netstat which netstat
+    # net-tools netstat reports "net-tools X.Y"; macOS ships BSD netstat with no
+    # version flag, so fall back to a presence marker there.
+    check netstat sh -c 'command -v netstat >/dev/null && { netstat --version 2>&1 | grep -m1 -oE "net-tools [0-9.]+" || echo present; }'
    check ninja
-    check perl
+    check perl perl -e 'print "$^V\n"'
    check pkg-config
    check vim
-    check zip
+    check zip bash -c 'zip --version 2>&1 | grep -m1 -oE "Zip [0-9.]+"'

    # These tools are present in our Linux CI images and in local development
    # setups, but not in the macOS CI environment. So check them everywhere
--- a/bin/default-loader-path.sh
+++ b/bin/default-loader-path.sh
--- a/bin/pre-commit/Dockerfile
+++ b/bin/pre-commit/Dockerfile
@@ -0,0 +1,55 @@
+ARG BASE_IMAGE=ubuntu:26.04
+
+FROM ${BASE_IMAGE}
+
+SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
+ENTRYPOINT ["/bin/bash"]
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+RUN <<EOF
+pkgs=()
+pkgs+=(curl)         # Required to install nix.
+pkgs+=(doxygen)      # Needed for Clio's check-doxygen-docs.sh.
+pkgs+=(git)          # Required for prepare-runner.
+pkgs+=(libatomic1)   # Required to run pre-commit provided `node`.
+pkgs+=(python3)      # Python 3 interpreter.
+pkgs+=(python3-pip)  # Package manager for Python applications.
+pkgs+=(xz-utils)     # Required to install nix
+
+apt-get update
+apt-get install -y --no-install-recommends "${pkgs[@]}"
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+EOF
+
+ARG PRE_COMMIT_VERSION=4.6.0
+RUN pip install --no-cache --break-system-packages \
+    pre-commit==${PRE_COMMIT_VERSION}
+
+RUN sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon --yes
+
+# Add nix to PATH and set NIX environment variables,
+# so nix is available in all shells including non-interactive shells (e.g., GitHub Actions).
+ENV PATH="/nix/var/nix/profiles/default/bin:${PATH}"
+ENV NIX_PROFILES="/nix/var/nix/profiles/default"
+ENV NIX_SSL_CERT_FILE="/nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt"
+
+# Verify nix installation
+RUN nix --version
+
+ENV RUSTUP_HOME="/opt/rust/rustup"
+ENV CARGO_HOME="/opt/rust/cargo"
+ENV PATH="/opt/rust/cargo/bin:${PATH}"
+
+WORKDIR /tmp
+COPY rust-toolchain.toml /tmp/rust-toolchain.toml
+RUN <<EOF
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal --default-toolchain none
+rustup toolchain install
+rustup show
+cargo fmt --version
+EOF
+
+WORKDIR /
--- a/cmake/CompilationEnv.cmake
+++ b/cmake/CompilationEnv.cmake
@@ -29,6 +29,27 @@ if(CMAKE_GENERATOR STREQUAL "Xcode")
    set(is_xcode TRUE)
 endif()

+# --------------------------------------------------------------------
+# Nix toolchain detection
+# --------------------------------------------------------------------
+# True when the C++ compiler resolves into the Nix store. CMAKE_CXX_COMPILER may
+# be referenced through a symlink outside the store (a Nix profile, a /usr/bin
+# alternative, ...), so resolve the real path before matching.
+set(is_nix_compiler FALSE)
+get_filename_component(_cxx_real "${CMAKE_CXX_COMPILER}" REALPATH)
+if(_cxx_real MATCHES "^/nix/store/")
+    set(is_nix_compiler TRUE)
+endif()
+unset(_cxx_real)
+
+# True inside the Nix CI Docker image, identified by the /nix/ci-env tree it
+# ships (see nix/docker/Dockerfile). The dev shell and bare systems don't have
+# it, so it distinguishes the CI image from other Nix-compiler environments.
+set(is_ci_image FALSE)
+if(EXISTS "/nix/ci-env/bin")
+    set(is_ci_image TRUE)
+endif()
+
 # --------------------------------------------------------------------
 # Operating system detection
 # --------------------------------------------------------------------
--- a/cmake/PatchNixBinary.cmake
+++ b/cmake/PatchNixBinary.cmake
@@ -1,26 +1,37 @@
 #[===================================================================[
   Patch executables to run in non-Nix environments.

-   The Nix-based CI image links binaries against an ELF interpreter (loader)
-   that lives in the Nix store, so the resulting binaries don't run elsewhere
-   (including once installed from the .deb package). `patch_nix_binary` adds a
-   POST_BUILD step that resets the interpreter to the system default loader and
-   drops the rpath.
+   The Nix toolchain links binaries against an ELF interpreter (loader)
+   that lives in the Nix store, so the resulting binaries don't run elsewhere.
+   `patch_nix_binary` adds a POST_BUILD step that resets the interpreter
+   to the system default loader and drops the rpath.

-   This is only active inside the Nix-based image, detected by the presence of
-   /tmp/loader-path.sh (shipped by that image, resolves the default loader). It
-   is skipped for sanitizer builds, whose runtime libraries are resolved through
-   the rpath. Everywhere else `patch_nix_binary` is a no-op.
+   This runs by default for Nix-toolchain builds (determined by whether the compiler resolves under /nix/store/).
+   Those builds are where binaries get a Nix-store loader.
+   It is opted out of by setting the XRPLD_NO_PATCH_NIX_BINARY environment variable —
+   the plain Nix dev shells set it, since their binaries link a newer glibc
+   and must not be retargeted to the system loader.
+
+   Non-Nix builds (a system compiler, already using the system loader) and sanitizer builds
+   (runtime libraries resolved through the rpath) are skipped too.
+   Everywhere else `patch_nix_binary` is a no-op.
+
+   The default loader is resolved by bin/default-loader-path.sh.
 #]===================================================================]

 include_guard(GLOBAL)

 include(CompilationEnv)

-# Provided by the Nix-based CI image; prints the system default ELF loader path.
-set(_loader_path_script "/tmp/loader-path.sh")
+# Resolves the system default ELF loader path for the current architecture.
+set(_loader_path_script "${CMAKE_SOURCE_DIR}/bin/default-loader-path.sh")

-if(is_linux AND NOT SANITIZERS_ENABLED AND EXISTS "${_loader_path_script}")
+if(
+    is_linux
+    AND NOT SANITIZERS_ENABLED
+    AND is_nix_compiler
+    AND NOT DEFINED ENV{XRPLD_NO_PATCH_NIX_BINARY}
+)
    execute_process(
        COMMAND "${_loader_path_script}"
        OUTPUT_VARIABLE DEFAULT_LOADER_PATH
--- a/cmake/XrplCompiler.cmake
+++ b/cmake/XrplCompiler.cmake
@@ -171,9 +171,8 @@ else()
    # Clang wrapper supplies those paths itself (via -nostdinc++), so at compile time the
    # flag is unused -> Clang errors under our -Werror. At link time the flag IS consumed
    # (it selects the C++ runtime), so we move it there instead of dropping it entirely.
-    get_filename_component(_cxx_real "${CMAKE_CXX_COMPILER}" REALPATH)
    if(
-        _cxx_real MATCHES "^/nix/store/"
+        is_nix_compiler
        AND is_linux
        AND is_clang
        AND CMAKE_CXX_FLAGS MATCHES "stdlib=libstdc"
--- a/cmake/XrplCore.cmake
+++ b/cmake/XrplCore.cmake
@@ -133,6 +133,12 @@ target_link_libraries(
 add_module(xrpl resource)
 target_link_libraries(xrpl.libxrpl.resource PUBLIC xrpl.libxrpl.protocol)

+add_module(xrpl peerfinder)
+target_link_libraries(
+    xrpl.libxrpl.peerfinder
+    PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.protocol
+)
+
 # Level 08
 add_module(xrpl net)
 target_link_libraries(
@@ -201,6 +207,16 @@ target_link_libraries(
 add_module(xrpl tx)
 target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)

+add_module(xrpl consensus)
+target_link_libraries(
+    xrpl.libxrpl.consensus
+    PUBLIC
+        xrpl.libxrpl.basics
+        xrpl.libxrpl.json
+        xrpl.libxrpl.protocol
+        xrpl.libxrpl.ledger
+)
+
 add_library(xrpl.libxrpl)
 set_target_properties(xrpl.libxrpl PROPERTIES OUTPUT_NAME xrpl)

@@ -220,6 +236,7 @@ target_link_modules(
    beast
    conditions
    config
+    consensus
    core
    crypto
    git
@@ -227,6 +244,7 @@ target_link_modules(
    ledger
    net
    nodestore
+    peerfinder
    protocol
    protocol_autogen
    rdb
--- a/cmake/XrplSanity.cmake
+++ b/cmake/XrplSanity.cmake
@@ -36,6 +36,19 @@ elseif(is_gcc)
    endif()
 endif()

+# A Nix compiler is only meant to be used from a managed environment: the xrpld
+# dev shell (which exports XRPL_DEVSHELL) or the CI image. Using one from a bare
+# shell usually means a leaked toolchain (picked up via PATH or a Conan profile)
+# and leads to confusing breakage, so fail early with guidance.
+if(is_nix_compiler AND NOT is_ci_image AND NOT DEFINED ENV{XRPL_DEVSHELL})
+    message(
+        FATAL_ERROR
+        "A Nix compiler (${CMAKE_CXX_COMPILER}) is being used outside the xrpld "
+        "dev shell. Enter it with `nix develop` (see docs/build/nix.md) before "
+        "configuring the build."
+    )
+endif()
+
 # check for in-source build and fail
 if("${CMAKE_CURRENT_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
    message(
--- a/conan/profiles/default
+++ b/conan/profiles/default
@@ -20,6 +20,22 @@ compiler.libcxx={{ detect_api.detect_libcxx(compiler, version, compiler_exe) }}
 {% endif %}

 [conf]
+{# The Boost recipe builds with b2, which doesn't use Conan's toolchain files. #}
+{# Instead it hand-rolls the compiler for user-config.jam, #}
+{# and its fallback probes a version-suffixed binary (e.g. `g++-15`) before plain `g++`. #}
+{# Inside the Nix shell the wrapper only provides `g++`/`gcc` (no `-15` suffix), #}
+{# so on a host that also has a system `g++-15` the probe escapes Nix #}
+{# and picks the system compiler, which is mismatched with the Nix libraries #}
+{# and breaks the build (e.g. Boost.Stacktrace link checks fail). #}
+{# Pinning the executables here short-circuits that probe so Boost (and the rest of the toolchain) #}
+{# resolve the same compiler. #}
+{# Not part of the package ID, so binaries stay shareable. #}
+{% if os != "Windows" %}
+{% set cc_exe  = {"gcc": "gcc",  "clang": "clang",   "apple-clang": "clang"}.get(compiler) %}
+{% set cxx_exe = {"gcc": "g++",  "clang": "clang++", "apple-clang": "clang++"}.get(compiler) %}
+tools.build:compiler_executables={'c':'{{ cc_exe }}','cpp':'{{ cxx_exe }}'}
+{% endif %}
+
 {# By default, Conan tries to reuse binaries built with different cppstd versions. #}
 {# We want to avoid that to improve reproduceability, so we add the cppstd version to the package ID. #}
 {# More info: https://docs.conan.io/2/reference/extensions/binary_compatibility.html #}
--- a/docs/build/nix.md
+++ b/docs/build/nix.md
@@ -38,8 +38,10 @@ The first time you run this command, it will take a few minutes to download and

 ### Platform notes

- **Linux**: `nix develop` gives you a shell with all the tooling necessary to
-  develop xrpld and with GCC 15.2 (also provided by Nix). There are no caveats.
+- **Linux**: `nix develop` gives you a shell with all the tooling necessary to develop xrpld
+  and with the same GCC/glibc toolchain that Nix builds for CI.
+  See [Choosing a different compiler](#choosing-a-different-compiler)
+  for the custom-vs-plain toolchain trade-off.
 - **macOS**: `nix develop` gives you a full environment too, with Clang (and
  every other tool, including Conan) provided by Nix. To use your system-wide
  Apple Clang instead, enter `nix develop .#apple-clang`. Conan has no binary in
@@ -63,8 +65,16 @@ The first time you run this command, it will take a few minutes to download and
 ### Choosing a different compiler

 A compiler can be chosen by providing its name with the `.#` prefix, e.g. `nix develop .#clang`.
-The `.#gcc` and `.#clang` shells provide the same GCC and Clang versions used in CI
-(pinned in [`nix/packages.nix`](../../nix/packages.nix)).
+
+On Linux, `.#gcc` and `.#clang` provide the exact toolchain CI uses:
+the compiler (pinned in [`nix/packages.nix`](../../nix/packages.nix))
+rebuilt against the pinned custom glibc (see [`nix/compilers.nix`](../../nix/compilers.nix)).
+Building that toolchain the first time is slow unless it is fetched from a Nix binary cache.
+If you don't need the custom glibc, the Linux-only `.#gcc-plain` and `.#clang-plain`
+give you the stock nixpkgs compilers of the same versions.
+On macOS there is no custom glibc, so `.#gcc` and `.#clang` are already the plain nixpkgs toolchain,
+and the `-plain` variants do not exist.
+
 Use `nix flake show` to see all the available development shells.

 Use `nix develop .#no-compiler` to use the compiler from your system.
@@ -72,14 +82,18 @@ Use `nix develop .#no-compiler` to use the compiler from your system.
 ### Example Usage

 ```bash
-# Use GCC (same version as CI)
+# Use GCC — same toolchain as CI (custom glibc on Linux)
 nix develop .#gcc

-# Use Clang (same version as CI)
+# Use Clang — same toolchain as CI (custom glibc on Linux)
 nix develop .#clang

 # Use default for your platform
 nix develop
+
+# Stock nixpkgs GCC/Clang, Linux only — skips the custom-glibc build, but does not match CI
+nix develop .#gcc-plain
+nix develop .#clang-plain
 ```

 ### Using a different shell
@@ -110,6 +124,10 @@ nix develop -c "$SHELL"

 Once inside the Nix development shell, follow the standard [build instructions](../../BUILD.md#steps). The Nix shell provides all necessary tools (CMake, Ninja, Conan, etc.).

+Coverage builds (`-Dcoverage=ON`) work in the `gcc` shell (and `gcc-plain` on Linux):
+each ships a `gcov` matching its compiler, since Nix's cc-wrapper does not expose one.
+The `clang` shells do not include `llvm-cov`, so use a `gcc` shell for coverage.
+
 ## Automatic Activation with direnv

 [direnv](https://direnv.net/) or [nix-direnv](https://github.com/nix-community/nix-direnv) can automatically activate the Nix development shell when you enter the repository directory.
@@ -136,6 +154,14 @@ conan install .. --output-folder . --build '*' --settings build_type=Release

 To update `flake.lock` to the latest revision use `nix flake update` command.

+## Tooling snapshots
+
+The tool versions in each Nix environment are recorded in
+[`nix/check-tools/`](../../nix/check-tools) and verified by CI. If you change the
+environment (bump the CI image tag, update `flake.lock`, or edit the tool list in
+`bin/check-tools.sh`), CI fails until you regenerate and commit the affected
+snapshot — see [`nix/check-tools/README.md`](../../nix/check-tools/README.md).
+
 ## Troubleshooting

 See [Troubleshooting Nix problems](./nix_troubleshooting.md) for common issues,
--- a/flake.lock
+++ b/flake.lock
@@ -36,7 +36,28 @@
    "root": {
      "inputs": {
        "nixpkgs": "nixpkgs",
-        "nixpkgs-custom-glibc": "nixpkgs-custom-glibc"
+        "nixpkgs-custom-glibc": "nixpkgs-custom-glibc",
+        "rust-overlay": "rust-overlay"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1784611586,
+        "narHash": "sha256-OfqgY+0hp/zseZB7uyH0U8kIDPS4scZZCyAurEplvG0=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "14f58845249f3552a89b07772626b8d3c632fa86",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
      }
    }
  },
--- a/flake.nix
+++ b/flake.nix
@@ -10,12 +10,25 @@
      url = "github:NixOS/nixpkgs/9cd98386a38891d1074fc18036b842dc4416f562";
      flake = false;
    };
+    # Pinned Rust toolchains, delivered from the Nix store. Lets the Nix CI
+    # image and dev shell honour the single `rust-toolchain.toml` pin (shared
+    # with the rustup-based non-Nix runners) while staying hermetic — the
+    # toolchain lands in the image's Nix closure and is locked by flake.lock.
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
  };

  outputs =
-    { nixpkgs, nixpkgs-custom-glibc, ... }:
+    {
+      nixpkgs,
+      nixpkgs-custom-glibc,
+      rust-overlay,
+      ...
+    }:
    let
-      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-custom-glibc; };
+      forEachSystem = import ./nix/utils.nix { inherit nixpkgs nixpkgs-custom-glibc rust-overlay; };
    in
    {
      devShells = forEachSystem (import ./nix/devshell.nix);
--- a/include/xrpl/beast/container/detail/aged_unordered_container.h
+++ b/include/xrpl/beast/container/detail/aged_unordered_container.h
@@ -5,6 +5,7 @@
 #include <xrpl/beast/container/detail/aged_associative_container.h>
 #include <xrpl/beast/container/detail/aged_container_iterator.h>
 #include <xrpl/beast/container/detail/empty_base_optimization.h>
+#include <xrpl/beast/utility/instrumentation.h>

 #include <boost/intrusive/list.hpp>
 #include <boost/intrusive/unordered_set.hpp>
--- a/src/xrpld/app/consensus/RCLCensorshipDetector.h
+++ b/src/xrpld/app/consensus/RCLCensorshipDetector.h
@@ -10,7 +10,7 @@
 namespace xrpl {

 template <class TxID, class Sequence>
-class RCLCensorshipDetector
+class CensorshipDetector
 {
 public:
    struct TxIDSeq
@@ -49,7 +49,7 @@ private:
    TxIDSeqVec tracker_;

 public:
-    RCLCensorshipDetector() = default;
+    CensorshipDetector() = default;

    /**
     * Add transactions being proposed for the current consensus round.
--- a/include/xrpl/consensus/Consensus.h
+++ b/include/xrpl/consensus/Consensus.h
@@ -1,15 +1,14 @@
 #pragma once

-#include <xrpld/consensus/ConsensusParms.h>
-#include <xrpld/consensus/ConsensusProposal.h>
-#include <xrpld/consensus/ConsensusTypes.h>
-
 #include <xrpl/basics/Log.h>
 #include <xrpl/basics/UnorderedContainers.h>
 #include <xrpl/basics/chrono.h>
 #include <xrpl/beast/clock/abstract_clock.h>
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/consensus/ConsensusParms.h>
+#include <xrpl/consensus/ConsensusProposal.h>
+#include <xrpl/consensus/ConsensusTypes.h>
 #include <xrpl/json/json_value.h>
 #include <xrpl/json/json_writer.h>
 #include <xrpl/ledger/LedgerTiming.h>
--- a/include/xrpl/consensus/ConsensusParms.h
+++ b/include/xrpl/consensus/ConsensusParms.h
--- a/include/xrpl/consensus/ConsensusProposal.h
+++ b/include/xrpl/consensus/ConsensusProposal.h
--- a/include/xrpl/consensus/ConsensusTypes.h
+++ b/include/xrpl/consensus/ConsensusTypes.h
@@ -1,11 +1,10 @@
 #pragma once

-#include <xrpld/consensus/ConsensusProposal.h>
-#include <xrpld/consensus/DisputedTx.h>
-
 #include <xrpl/basics/UnorderedContainers.h>
 #include <xrpl/basics/chrono.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/consensus/ConsensusProposal.h>
+#include <xrpl/consensus/DisputedTx.h>

 #include <chrono>
 #include <cstddef>
--- a/include/xrpl/consensus/DisputedTx.h
+++ b/include/xrpl/consensus/DisputedTx.h
@@ -1,9 +1,8 @@
 #pragma once

-#include <xrpld/consensus/ConsensusParms.h>
-
 #include <xrpl/basics/Log.h>
 #include <xrpl/beast/utility/Journal.h>
+#include <xrpl/consensus/ConsensusParms.h>
 #include <xrpl/json/json_value.h>
 #include <xrpl/json/json_writer.h>

--- a/include/xrpl/consensus/LedgerTrie.h
+++ b/include/xrpl/consensus/LedgerTrie.h
--- a/include/xrpl/consensus/README.md
+++ b/include/xrpl/consensus/README.md
--- a/include/xrpl/consensus/Validations.h
+++ b/include/xrpl/consensus/Validations.h
@@ -1,7 +1,5 @@
 #pragma once

-#include <xrpld/consensus/LedgerTrie.h>
-
 #include <xrpl/basics/Log.h>
 #include <xrpl/basics/UnorderedContainers.h>
 #include <xrpl/basics/chrono.h>
@@ -11,6 +9,7 @@
 #include <xrpl/beast/hash/uhash.h>
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/consensus/LedgerTrie.h>
 #include <xrpl/json/json_value.h>

 #include <algorithm>
--- a/include/xrpl/core/CoroTask.h
+++ b/include/xrpl/core/CoroTask.h
@@ -0,0 +1,699 @@
+#pragma once
+
+#include <xrpl/beast/utility/instrumentation.h>
+
+#include <coroutine>
+#include <exception>
+#include <type_traits>
+#include <utility>
+#include <variant>
+
+namespace xrpl {
+
+template <typename T = void>
+class CoroTask;
+
+/**
+ * CoroTask<void> -- coroutine return type for void-returning coroutines.
+ *
+ * Class / Dependency Diagram
+ * ==========================
+ *
+ *   CoroTask<void>
+ *   +-----------------------------------------------+
+ *   | - handle_ : Handle (coroutine_handle<promise>) |
+ *   +-----------------------------------------------+
+ *   | + handle(), done()                             |
+ *   | + await_ready/suspend/resume  (Awaiter iface)  |
+ *   +-----------------------------------------------+
+ *            |  owns
+ *            v
+ *   promise_type
+ *   +-----------------------------------------------+
+ *   | - exception_    : std::exception_ptr           |
+ *   | - continuation_ : std::coroutine_handle<>      |
+ *   +-----------------------------------------------+
+ *   | + get_return_object() -> CoroTask              |
+ *   | + initial_suspend()   -> suspend_always (lazy) |
+ *   | + final_suspend()     -> FinalAwaiter          |
+ *   | + return_void()                                |
+ *   | + unhandled_exception()                        |
+ *   +-----------------------------------------------+
+ *            |  returns at final_suspend
+ *            v
+ *   FinalAwaiter
+ *   +-----------------------------------------------+
+ *   | await_suspend(h):                              |
+ *   |   if continuation_ set -> symmetric transfer   |
+ *   |   else                 -> noop_coroutine        |
+ *   +-----------------------------------------------+
+ *
+ * Design Notes
+ * ------------
+ * - Lazy start: initial_suspend returns suspend_always, so the coroutine
+ *   body does not execute until the handle is explicitly resumed.
+ * - Symmetric transfer: await_suspend returns a coroutine_handle instead
+ *   of void/bool, allowing the scheduler to jump directly to the next
+ *   coroutine without growing the call stack.
+ * - Continuation chaining: when one CoroTask is co_await-ed inside
+ *   another, the caller's handle is stored as continuation_ so
+ *   FinalAwaiter can resume it when this task finishes.
+ * - Move-only: the handle is exclusively owned; copy is deleted.
+ *
+ * Usage Examples
+ * ==============
+ *
+ * 1. Basic void coroutine (the most common case in rippled):
+ *
+ *      CoroTask<void> doWork(std::shared_ptr<CoroTaskRunner> runner) {
+ *          // do something
+ *          co_await runner->suspend();   // yield control
+ *          // resumed later via runner->post() or runner->resume()
+ *          co_return;
+ *      }
+ *
+ * 2. co_await-ing one CoroTask<void> from another (chaining):
+ *
+ *      CoroTask<void> inner() {
+ *          // ...
+ *          co_return;
+ *      }
+ *      CoroTask<void> outer() {
+ *          co_await inner();   // continuation_ links outer -> inner
+ *          co_return;          // FinalAwaiter resumes outer
+ *      }
+ *
+ * 3. Exceptions propagate through co_await:
+ *
+ *      CoroTask<void> failing() {
+ *          throw std::runtime_error("oops");
+ *          co_return;
+ *      }
+ *      CoroTask<void> caller() {
+ *          try { co_await failing(); }
+ *          catch (std::runtime_error const&) { // caught here }
+ *      }
+ *
+ * Caveats / Pitfalls
+ * ==================
+ *
+ * BUG-RISK: Dangling references in coroutine parameters.
+ *   Coroutine parameters are copied into the frame, but references
+ *   are NOT -- they are stored as-is. If the referent goes out of scope
+ *   before the coroutine finishes, you get use-after-free.
+ *
+ *      // BROKEN -- local dies before coroutine runs:
+ *      CoroTask<void> bad(int& ref) { co_return; }
+ *      void launch() {
+ *          int local = 42;
+ *          auto task = bad(local);  // frame stores &local
+ *      }  // local destroyed; frame holds dangling ref
+ *
+ *      // FIX -- pass by value, or ensure lifetime via shared_ptr.
+ *
+ * BUG-RISK: GCC 14 corrupts reference captures in coroutine lambdas.
+ *   When a lambda that returns CoroTask captures by reference ([&]),
+ *   GCC 14 may generate a corrupted coroutine frame. Always capture
+ *   by explicit pointer-to-value instead:
+ *
+ *      // BROKEN on GCC 14:
+ *      jq.postCoroTask(t, n, [&](auto) -> CoroTask<void> { ... });
+ *
+ *      // FIX -- capture pointers explicitly:
+ *      jq.postCoroTask(t, n, [ptr = &val](auto) -> CoroTask<void> { ... });
+ *
+ * BUG-RISK: Resuming a destroyed or completed CoroTask.
+ *   Calling handle().resume() after the coroutine has already run to
+ *   completion (done() == true) is undefined behavior. The CoroTaskRunner
+ *   guards against this with an XRPL_ASSERT, but standalone usage of
+ *   CoroTask must check done() before resuming.
+ *
+ * BUG-RISK: Moving a CoroTask that is being awaited.
+ *   If task A is co_await-ed by task B (so A.continuation_ == B), moving
+ *   or destroying A will invalidate the continuation link. Never move
+ *   or reassign a CoroTask while it is mid-execution or being awaited.
+ *
+ * LIMITATION: CoroTask is fire-and-forget for the top-level owner.
+ *   There is no built-in notification when the coroutine finishes.
+ *   The caller must use external synchronization (e.g. CoroTaskRunner::join
+ *   or a gate/condition_variable) to know when it is done.
+ *
+ * LIMITATION: No cancellation token.
+ *   There is no way to cancel a suspended CoroTask from outside. The
+ *   coroutine body must cooperatively check a flag (e.g. jq_.isStopping())
+ *   after each co_await and co_return early if needed.
+ *
+ * LIMITATION: Stackless -- cannot suspend from nested non-coroutine calls.
+ *   If a coroutine calls a regular function that wants to "yield", it
+ *   cannot. Only the immediate coroutine body can use co_await.
+ *   This is acceptable for rippled because all yield() sites are shallow.
+ */
+template <>
+class CoroTask<void>
+{
+public:
+    struct promise_type;
+    using Handle = std::coroutine_handle<promise_type>;
+
+    /**
+     * Coroutine promise. Compiler uses this to manage coroutine state.
+     * Stores the exception (if any) and the continuation handle for
+     * symmetric transfer back to the awaiting coroutine.
+     */
+    struct promise_type
+    {
+        // Captured exception from the coroutine body, rethrown in
+        // await_resume() when this task is co_await-ed by a caller.
+        std::exception_ptr exception_;
+
+        // Handle to the coroutine that is co_await-ing this task.
+        // Set by await_suspend(). FinalAwaiter uses it for symmetric
+        // transfer back to the caller. Null if this is a top-level task.
+        std::coroutine_handle<> continuation_;
+
+        /**
+         * Create the CoroTask return object.
+         * Called by the compiler at coroutine creation.
+         */
+        CoroTask
+        get_return_object()
+        {
+            return CoroTask{Handle::from_promise(*this)};
+        }
+
+        /**
+         * Lazy start. The coroutine body does not execute until the
+         * handle is explicitly resumed (e.g. by CoroTaskRunner::resume).
+         */
+        std::suspend_always
+        initial_suspend() noexcept
+        {
+            return {};
+        }
+
+        /**
+         * Awaiter returned by final_suspend(). Uses symmetric transfer:
+         * if a continuation exists, transfers control directly to it
+         * (tail-call, no stack growth). Otherwise returns noop_coroutine
+         * so the coroutine frame stays alive for the owner to destroy.
+         */
+        struct FinalAwaiter
+        {
+            /**
+             * Always false. We need await_suspend to run for
+             * symmetric transfer.
+             */
+            bool
+            await_ready() noexcept
+            {
+                return false;
+            }
+
+            /**
+             * Symmetric transfer: returns the continuation handle so
+             * the compiler emits a tail-call instead of a nested resume.
+             * If no continuation is set, returns noop_coroutine to
+             * suspend at final_suspend without destroying the frame.
+             *
+             * @param h Handle to this completing coroutine
+             *
+             * @return Continuation handle, or noop_coroutine
+             */
+            std::coroutine_handle<>
+            await_suspend(Handle h) noexcept
+            {
+                if (auto cont = h.promise().continuation_)
+                    return cont;
+                return std::noop_coroutine();
+            }
+
+            void
+            await_resume() noexcept
+            {
+            }
+        };
+
+        /**
+         * Returns FinalAwaiter for symmetric transfer at coroutine end.
+         */
+        FinalAwaiter
+        final_suspend() noexcept
+        {
+            return {};
+        }
+
+        /**
+         * Called by the compiler for `co_return;` (void coroutine).
+         */
+        void
+        return_void()
+        {
+        }
+
+        /**
+         * Called by the compiler when an exception escapes the coroutine
+         * body. Captures it for later rethrowing in await_resume().
+         */
+        void
+        unhandled_exception()
+        {
+            exception_ = std::current_exception();
+        }
+    };
+
+    /**
+     * Default constructor. Creates an empty (null handle) task.
+     */
+    CoroTask() = default;
+
+    /**
+     * Takes ownership of a compiler-generated coroutine handle.
+     *
+     * @param h Coroutine handle to own
+     */
+    explicit CoroTask(Handle h) : handle_(h)
+    {
+    }
+
+    /**
+     * Destroys the coroutine frame if this task owns one.
+     */
+    ~CoroTask()
+    {
+        if (handle_)
+            handle_.destroy();
+    }
+
+    /**
+     * Move constructor. Transfers handle ownership, leaves other empty.
+     */
+    CoroTask(CoroTask&& other) noexcept : handle_(std::exchange(other.handle_, {}))
+    {
+    }
+
+    /**
+     * Move assignment. Destroys current frame (if any), takes other's.
+     */
+    CoroTask&
+    operator=(CoroTask&& other) noexcept
+    {
+        if (this != &other)
+        {
+            if (handle_)
+                handle_.destroy();
+            handle_ = std::exchange(other.handle_, {});
+        }
+        return *this;
+    }
+
+    CoroTask(CoroTask const&) = delete;
+    CoroTask&
+    operator=(CoroTask const&) = delete;
+
+    /**
+     * @return The underlying coroutine_handle
+     */
+    Handle
+    handle() const
+    {
+        return handle_;
+    }
+
+    /**
+     * @return true if the coroutine has run to completion (or thrown)
+     */
+    bool
+    done() const
+    {
+        return handle_ && handle_.done();
+    }
+
+    // -- Awaiter interface: allows `co_await someCoroTask;` --
+
+    /**
+     * Always false. This task is lazy, so co_await always suspends
+     * the caller to set up the continuation link.
+     */
+    bool
+    await_ready() const noexcept
+    {
+        return false;
+    }
+
+    /**
+     * Stores the caller's handle as our continuation, then returns
+     * our handle for symmetric transfer (caller suspends, we resume).
+     *
+     * @param caller Handle of the coroutine doing co_await on us
+     *
+     * @return Our handle for symmetric transfer
+     */
+    std::coroutine_handle<>
+    await_suspend(std::coroutine_handle<> caller) noexcept
+    {
+        XRPL_ASSERT(handle_, "xrpl::CoroTask<void>::await_suspend : handle is valid");
+        handle_.promise().continuation_ = caller;
+        return handle_;  // Symmetric transfer
+    }
+
+    /**
+     * Called in the awaiting coroutine's context after this task
+     * completes. Rethrows any exception captured by
+     * unhandled_exception().
+     */
+    void
+    await_resume()
+    {
+        XRPL_ASSERT(handle_, "xrpl::CoroTask<void>::await_resume : handle is valid");
+        if (auto& ep = handle_.promise().exception_)
+            std::rethrow_exception(ep);
+    }
+
+private:
+    // Exclusively-owned coroutine handle. Null after move or default
+    // construction. Destroyed in the destructor.
+    Handle handle_;
+};
+
+/**
+ * CoroTask<T> -- coroutine return type for value-returning coroutines.
+ *
+ * Class / Dependency Diagram
+ * ==========================
+ *
+ *   CoroTask<T>
+ *   +-----------------------------------------------+
+ *   | - handle_ : Handle (coroutine_handle<promise>) |
+ *   +-----------------------------------------------+
+ *   | + handle(), done()                             |
+ *   | + await_ready/suspend/resume  (Awaiter iface)  |
+ *   +-----------------------------------------------+
+ *            |  owns
+ *            v
+ *   promise_type
+ *   +-----------------------------------------------+
+ *   | - result_       : variant<monostate, T,        |
+ *   |                           exception_ptr>       |
+ *   | - continuation_ : std::coroutine_handle<>      |
+ *   +-----------------------------------------------+
+ *   | + get_return_object() -> CoroTask              |
+ *   | + initial_suspend()   -> suspend_always (lazy) |
+ *   | + final_suspend()     -> FinalAwaiter          |
+ *   | + return_value(T)     -> stores in result_[1]  |
+ *   | + unhandled_exception -> stores in result_[2]  |
+ *   +-----------------------------------------------+
+ *            |  returns at final_suspend
+ *            v
+ *   FinalAwaiter  (same symmetric-transfer pattern as CoroTask<void>)
+ *
+ * Value Extraction
+ * ----------------
+ * await_resume() inspects the variant:
+ *   - index 2 (exception_ptr) -> rethrow
+ *   - index 1 (T)             -> return value via move
+ *
+ * Usage Examples
+ * ==============
+ *
+ * 1. Simple value return:
+ *
+ *      CoroTask<int> computeAnswer() { co_return 42; }
+ *
+ *      CoroTask<void> caller() {
+ *          int v = co_await computeAnswer();  // v == 42
+ *      }
+ *
+ * 2. Chaining value-returning coroutines:
+ *
+ *      CoroTask<int> add(int a, int b) { co_return a + b; }
+ *      CoroTask<int> doubleSum(int a, int b) {
+ *          int s = co_await add(a, b);
+ *          co_return s * 2;
+ *      }
+ *
+ * 3. Exception propagation from inner to outer:
+ *
+ *      CoroTask<int> failing() {
+ *          throw std::runtime_error("bad");
+ *          co_return 0;  // never reached
+ *      }
+ *      CoroTask<void> caller() {
+ *          try {
+ *              int v = co_await failing();  // throws here
+ *          } catch (std::runtime_error const& e) {
+ *              // e.what() == "bad"
+ *          }
+ *      }
+ *
+ * Caveats / Pitfalls (in addition to CoroTask<void> caveats above)
+ * ================================================================
+ *
+ * BUG-RISK: await_resume() moves the value out of the variant.
+ *   Calling co_await on the same CoroTask<T> instance twice is undefined
+ *   behavior -- the second call will see a moved-from T. CoroTask is
+ *   single-shot: one co_return, one co_await.
+ *
+ * BUG-RISK: T must be move-constructible.
+ *   return_value(T) takes by value and moves into the variant.
+ *   Types that are not movable cannot be used as T.
+ *
+ * LIMITATION: No co_yield support.
+ *   CoroTask<T> only supports a single co_return. It does not implement
+ *   yield_value(), so using co_yield inside a CoroTask<T> coroutine is a
+ *   compile error. For streaming values, a different return type
+ *   (e.g. Generator<T>) would be needed.
+ *
+ * LIMITATION: Result is only accessible via co_await.
+ *   There is no .get() or .result() method. The value can only be
+ *   extracted by co_await-ing the CoroTask<T> from inside another
+ *   coroutine. For extracting results in non-coroutine code, pass a
+ *   pointer to the caller and write through it (as the tests do).
+ */
+template <typename T>
+class CoroTask
+{
+    static_assert(
+        std::is_move_constructible_v<T>,
+        "CoroTask<T> requires T to be move-constructible");
+
+public:
+    struct promise_type;
+    using Handle = std::coroutine_handle<promise_type>;
+
+    /**
+     * Coroutine promise for value-returning coroutines.
+     * Stores the result as a variant: monostate (not yet set),
+     * T (co_return value), or exception_ptr (unhandled exception).
+     */
+    struct promise_type
+    {
+        // Tri-state result:
+        //   index 0 (monostate) -- coroutine has not yet completed
+        //   index 1 (T)         -- co_return value stored here
+        //   index 2 (exception) -- unhandled exception captured here
+        std::variant<std::monostate, T, std::exception_ptr> result_;
+
+        // Handle to the coroutine co_await-ing this task. Used by
+        // FinalAwaiter for symmetric transfer. Null for top-level tasks.
+        std::coroutine_handle<> continuation_;
+
+        /**
+         * Create the CoroTask return object.
+         * Called by the compiler at coroutine creation.
+         */
+        CoroTask
+        get_return_object()
+        {
+            return CoroTask{Handle::from_promise(*this)};
+        }
+
+        /**
+         * Lazy start. Coroutine body does not run until explicitly resumed.
+         */
+        std::suspend_always
+        initial_suspend() noexcept
+        {
+            return {};
+        }
+
+        /**
+         * Symmetric-transfer awaiter at coroutine completion.
+         * Same pattern as CoroTask<void>::FinalAwaiter.
+         */
+        struct FinalAwaiter
+        {
+            bool
+            await_ready() noexcept
+            {
+                return false;
+            }
+
+            /**
+             * Returns continuation for symmetric transfer, or
+             * noop_coroutine if this is a top-level task.
+             *
+             * @param h Handle to this completing coroutine
+             *
+             * @return Continuation handle, or noop_coroutine
+             */
+            std::coroutine_handle<>
+            await_suspend(Handle h) noexcept
+            {
+                if (auto cont = h.promise().continuation_)
+                    return cont;
+                return std::noop_coroutine();
+            }
+
+            void
+            await_resume() noexcept
+            {
+            }
+        };
+
+        FinalAwaiter
+        final_suspend() noexcept
+        {
+            return {};
+        }
+
+        /**
+         * Called by the compiler for `co_return value;`.
+         * Moves the value into result_ at index 1.
+         *
+         * @param value The value to store
+         */
+        void
+        return_value(T value)
+        {
+            result_.template emplace<1>(std::move(value));
+        }
+
+        /**
+         * Captures unhandled exceptions at index 2 of result_.
+         * Rethrown later in await_resume().
+         */
+        void
+        unhandled_exception()
+        {
+            result_.template emplace<2>(std::current_exception());
+        }
+    };
+
+    /**
+     * Default constructor. Creates an empty (null handle) task.
+     */
+    CoroTask() = default;
+
+    /**
+     * Takes ownership of a compiler-generated coroutine handle.
+     *
+     * @param h Coroutine handle to own
+     */
+    explicit CoroTask(Handle h) : handle_(h)
+    {
+    }
+
+    /**
+     * Destroys the coroutine frame if this task owns one.
+     */
+    ~CoroTask()
+    {
+        if (handle_)
+            handle_.destroy();
+    }
+
+    /**
+     * Move constructor. Transfers handle ownership, leaves other empty.
+     */
+    CoroTask(CoroTask&& other) noexcept : handle_(std::exchange(other.handle_, {}))
+    {
+    }
+
+    /**
+     * Move assignment. Destroys current frame (if any), takes other's.
+     */
+    CoroTask&
+    operator=(CoroTask&& other) noexcept
+    {
+        if (this != &other)
+        {
+            if (handle_)
+                handle_.destroy();
+            handle_ = std::exchange(other.handle_, {});
+        }
+        return *this;
+    }
+
+    CoroTask(CoroTask const&) = delete;
+    CoroTask&
+    operator=(CoroTask const&) = delete;
+
+    /**
+     * @return The underlying coroutine_handle
+     */
+    Handle
+    handle() const
+    {
+        return handle_;
+    }
+
+    /**
+     * @return true if the coroutine has run to completion (or thrown)
+     */
+    bool
+    done() const
+    {
+        return handle_ && handle_.done();
+    }
+
+    // -- Awaiter interface: allows `T val = co_await someCoroTask;` --
+
+    /**
+     * Always false. co_await always suspends to set up continuation.
+     */
+    bool
+    await_ready() const noexcept
+    {
+        return false;
+    }
+
+    /**
+     * Stores caller as continuation, returns our handle for
+     * symmetric transfer.
+     *
+     * @param caller Handle of the coroutine doing co_await on us
+     *
+     * @return Our handle for symmetric transfer
+     */
+    std::coroutine_handle<>
+    await_suspend(std::coroutine_handle<> caller) noexcept
+    {
+        XRPL_ASSERT(handle_, "xrpl::CoroTask<T>::await_suspend : handle is valid");
+        handle_.promise().continuation_ = caller;
+        return handle_;
+    }
+
+    /**
+     * Extracts the result: rethrows if exception, otherwise moves
+     * the T value out of the variant. Single-shot: calling twice
+     * on the same task is undefined (moved-from T).
+     *
+     * @return The co_return-ed value
+     */
+    T
+    await_resume()
+    {
+        XRPL_ASSERT(handle_, "xrpl::CoroTask<T>::await_resume : handle is valid");
+        auto& result = handle_.promise().result_;
+        if (auto* ep = std::get_if<2>(&result))
+            std::rethrow_exception(*ep);
+        return std::get<1>(std::move(result));
+    }
+
+private:
+    // Exclusively-owned coroutine handle. Null after move or default
+    // construction. Destroyed in the destructor.
+    Handle handle_;
+};
+
+}  // namespace xrpl
--- a/include/xrpl/core/CoroTaskRunner.ipp
+++ b/include/xrpl/core/CoroTaskRunner.ipp
@@ -0,0 +1,395 @@
+#pragma once
+
+/**
+ * @file CoroTaskRunner.ipp
+ *
+ * CoroTaskRunner inline implementation.
+ *
+ * This file contains the business logic for managing C++20 coroutines
+ * on the JobQueue. It is included at the bottom of JobQueue.h.
+ *
+ * Data Flow: suspend / post / resume cycle
+ * =========================================
+ *
+ *         coroutine body                 CoroTaskRunner              JobQueue
+ *         --------------                 --------------              --------
+ *              |
+ *    co_await runner->suspend()
+ *              |
+ *              +--- await_suspend ------> onSuspend()
+ *              |                            ++nSuspend_ ------------> nSuspend_
+ *              |                          [coroutine is now suspended]
+ *              |
+ *              .    (externally or by yieldAndPost())
+ *              .
+ *              +--- (caller calls) -----> post()
+ *              |                            ++runCount_
+ *              |                            addJob(resume) ----------> job enqueued
+ *              |                                                        |
+ *              |                                                      [worker picks up]
+ *              |                                                        |
+ *              +--- <----- resume() <-----------------------------------+
+ *              |             --nSuspend_ ------> nSuspend_
+ *              |             swap in LocalValues (lvs_)
+ *              |             task_.handle().resume()
+ *              |                |
+ *              |    [coroutine body continues here]
+ *              |                |
+ *              |             swap out LocalValues
+ *              |             --runCount_
+ *              |             cv_.notify_all()
+ *              v
+ *
+ * Thread Safety
+ * =============
+ * - mutex_     : guards task_.handle().resume() so that post()-before-suspend
+ *                races cannot resume the coroutine while it is still running.
+ *                (See the race condition discussion in JobQueue.h)
+ * - mutexRun_ : guards runCount_ counter; used by join() to wait until
+ *                all in-flight resume operations complete.
+ * - jq_.mutex_: guards nSuspend_ increments/decrements.
+ *
+ * Common Mistakes When Modifying This File
+ * =========================================
+ *
+ * 1. Changing lock ordering.
+ *    resume() acquires locks sequentially (never held simultaneously):
+ *    jq_.mutex_ (released immediately), then mutex_ (held across resume),
+ *    then mutexRun_ (released after decrement). post() acquires only
+ *    mutexRun_. Any new code path must follow the same order.
+ *
+ * 2. Removing the shared_from_this() capture in post().
+ *    The lambda passed to addJob captures [this, sp = shared_from_this()].
+ *    If you remove sp, 'this' can be destroyed before the job runs,
+ *    causing use-after-free. The sp capture is load-bearing.
+ *
+ * 3. Forgetting to decrement nSuspend_ on a new code path.
+ *    Every ++nSuspend_ must have a matching --nSuspend_. If you add a new
+ *    suspension path (e.g. a new awaiter) and forget to decrement on resume
+ *    or on failure, JobQueue::stop() will hang.
+ *
+ * 4. Calling task_.handle().resume() without holding mutex_.
+ *    This allows a race where the coroutine runs on two threads
+ *    simultaneously. Always hold mutex_ around resume().
+ *
+ * 5. Swapping LocalValues outside of the mutex_ critical section.
+ *    The swap-in and swap-out of LocalValues must bracket the resume()
+ *    call. If you move the swap-out before the lock_guard(mutex_) is
+ *    released, you break LocalValue isolation for any code that runs
+ *    after the coroutine suspends but before the lock is dropped.
+ */
+
+namespace xrpl {
+
+/**
+ * Construct a CoroTaskRunner. Sets runCount_ to 0; does not
+ * create the coroutine. Call init() afterwards.
+ *
+ * @param jq   The JobQueue this coroutine will run on
+ * @param type Job type for scheduling priority
+ * @param name Human-readable name for logging
+ */
+inline JobQueue::CoroTaskRunner::CoroTaskRunner(
+    CreateT,
+    JobQueue& jq,
+    JobType type,
+    std::string const& name)
+    : jq_(jq), type_(type), name_(name), runCount_(0)
+{
+}
+
+/**
+ * Initialize with a coroutine-returning callable.
+ * Stores the callable on the heap (FuncStore) so it outlives the
+ * coroutine frame. Coroutine frames store a reference to the
+ * callable's implicit object parameter (the lambda). If the callable
+ * is a temporary, that reference dangles after the caller returns.
+ * Keeping the callable alive here ensures the coroutine's captures
+ * remain valid.
+ *
+ * @param f Callable: CoroTask<void>(shared_ptr<CoroTaskRunner>)
+ */
+template <class F>
+void
+JobQueue::CoroTaskRunner::init(F&& f)
+{
+    using Fn = std::decay_t<F>;
+    auto store = std::make_unique<FuncStore<Fn>>(std::forward<F>(f));
+    task_ = store->func(shared_from_this());
+    storedFunc_ = std::move(store);
+}
+
+/**
+ * Destructor. Waits for any in-flight resume() to complete, then
+ * asserts (debug) that the coroutine has finished or
+ * expectEarlyExit() was called.
+ *
+ * The join() call is necessary because with async dispatch the
+ * coroutine runs on a worker thread. The gate signal (which wakes
+ * the test thread) can arrive before resume() has set finished_.
+ * join() synchronizes via mutexRun_, establishing a happens-before
+ * edge: finished_ = true -> unlock(mutexRun_) in resume() ->
+ * lock(mutexRun_) in join() -> read finished_.
+ */
+inline JobQueue::CoroTaskRunner::~CoroTaskRunner()
+{
+#ifndef NDEBUG
+    join();
+    XRPL_ASSERT(finished_, "xrpl::JobQueue::CoroTaskRunner::~CoroTaskRunner : is finished");
+#endif
+}
+
+/**
+ * Increment the JobQueue's suspended-coroutine count (nSuspend_).
+ */
+inline void
+JobQueue::CoroTaskRunner::onSuspend()
+{
+    std::lock_guard lock(jq_.mutex_);
+    ++jq_.nSuspend_;
+}
+
+/**
+ * Decrement nSuspend_ without resuming.
+ */
+inline void
+JobQueue::CoroTaskRunner::onUndoSuspend()
+{
+    std::lock_guard lock(jq_.mutex_);
+    --jq_.nSuspend_;
+}
+
+/**
+ * Return a SuspendAwaiter whose await_suspend() increments nSuspend_
+ * before the coroutine actually suspends. The caller must later call
+ * post() or resume() to continue execution.
+ *
+ * @return Awaiter for use with `co_await runner->suspend()`
+ */
+inline auto
+JobQueue::CoroTaskRunner::suspend()
+{
+    /**
+     * Custom awaiter for suspend(). Always suspends (await_ready
+     * returns false) and increments nSuspend_ in await_suspend().
+     */
+    struct SuspendAwaiter
+    {
+        CoroTaskRunner& runner_;  // The runner that owns this coroutine.
+
+        /**
+         * Always returns false so the coroutine suspends.
+         */
+        bool
+        await_ready() const noexcept
+        {
+            return false;
+        }
+
+        /**
+         * Called when the coroutine suspends. Increments nSuspend_
+         * so the JobQueue knows a coroutine is waiting.
+         */
+        void
+        await_suspend(std::coroutine_handle<>) const
+        {
+            runner_.onSuspend();
+        }
+
+        void
+        await_resume() const noexcept
+        {
+        }
+    };
+    return SuspendAwaiter{*this};
+}
+
+/**
+ * Suspend and immediately repost on the JobQueue. Equivalent to
+ * `co_await JobQueueAwaiter{runner}` but uses an inline struct
+ * to work around a GCC-12 codegen bug (see declaration in JobQueue.h).
+ *
+ * If the JobQueue is stopping (post fails), the suspend count is
+ * undone and the coroutine continues immediately via symmetric
+ * transfer back to its own handle.
+ *
+ * @return An inline YieldPostAwaiter
+ */
+inline auto
+JobQueue::CoroTaskRunner::yieldAndPost()
+{
+    struct YieldPostAwaiter
+    {
+        CoroTaskRunner& runner_;
+
+        bool
+        await_ready() const noexcept
+        {
+            return false;
+        }
+
+        /**
+         * Returns a coroutine_handle<> (symmetric transfer) rather than
+         * void + h.resume(). Two reasons:
+         *
+         *  1. h.resume() runs the coroutine nested inside this frame. A
+         *     coroutine that yields in a loop against a stopping JobQueue
+         *     fails post() every iteration, so the stack grows without
+         *     bound. Symmetric transfer is a tail call and does not nest.
+         *
+         *  2. After h.resume() returns, the coroutine may have completed
+         *     and destroyed its frame -- the frame this awaiter lives in.
+         *     Returning from await_suspend would then touch freed memory.
+         *
+         * A bool return would also avoid nesting, but GCC-12 miscompiles
+         * bool-returning await_suspend (see JobQueueAwaiter.h).
+         *
+         * @return noop_coroutine() to stay suspended (job posted);
+         *         the caller's handle to continue now (JQ stopping)
+         */
+        std::coroutine_handle<>
+        await_suspend(std::coroutine_handle<> h)
+        {
+            runner_.onSuspend();
+            if (!runner_.post())
+            {
+                runner_.onUndoSuspend();
+                return h;
+            }
+            return std::noop_coroutine();
+        }
+
+        void
+        await_resume() const noexcept
+        {
+        }
+    };
+    return YieldPostAwaiter{*this};
+}
+
+/**
+ * Schedule coroutine resumption as a job on the JobQueue.
+ * A shared_ptr capture (sp) prevents this CoroTaskRunner from being
+ * destroyed while the job is queued but not yet executed.
+ *
+ * @return false if the JobQueue rejected the job (shutting down)
+ */
+inline bool
+JobQueue::CoroTaskRunner::post()
+{
+    {
+        std::lock_guard lk(mutexRun_);
+        ++runCount_;
+    }
+
+    // sp prevents 'this' from being destroyed while the job is pending
+    if (jq_.addJob(type_, name_, [this, sp = shared_from_this()]() { resume(); }))
+    {
+        return true;
+    }
+
+    // The coroutine will not run. Undo the runCount_ increment.
+    std::lock_guard lk(mutexRun_);
+    --runCount_;
+    cv_.notify_all();
+    return false;
+}
+
+/**
+ * Resume the coroutine on the current thread.
+ *
+ * Steps:
+ *   1. Decrement nSuspend_ (under jq_.mutex_)
+ *   2. Swap in this coroutine's LocalValues for thread-local isolation
+ *   3. Resume the coroutine handle (under mutex_)
+ *   4. Swap out LocalValues, restoring the thread's previous state
+ *   5. Decrement runCount_ and notify join() waiters
+ *
+ * @pre post() must have been called before resume(). Direct calls
+ *      without a prior post() will corrupt runCount_ and break join().
+ * Note: runCount_ is NOT incremented here — post() already did that.
+ * This ensures join() stays blocked for the entire post->resume lifetime.
+ */
+inline void
+JobQueue::CoroTaskRunner::resume()
+{
+    {
+        std::lock_guard lock(jq_.mutex_);
+        --jq_.nSuspend_;
+    }
+    auto saved = detail::getLocalValues().release();
+    detail::getLocalValues().reset(&lvs_);
+    std::lock_guard lock(mutex_);
+    XRPL_ASSERT(
+        task_.handle() && !task_.done(),
+        "xrpl::JobQueue::CoroTaskRunner::resume : task handle is valid and not done");
+    task_.handle().resume();
+    detail::getLocalValues().release();
+    detail::getLocalValues().reset(saved);
+    if (task_.done())
+    {
+        finished_ = true;
+        // Break the shared_ptr cycle: frame -> shared_ptr<runner> -> this.
+        // Use std::move (not task_ = {}) so task_.handle_ is null BEFORE the
+        // frame is destroyed. operator= would destroy the frame while handle_
+        // still holds the old value -- a re-entrancy hazard on GCC-12 if
+        // frame destruction triggers runner cleanup.
+        [[maybe_unused]] auto completed = std::move(task_);
+    }
+    std::lock_guard lk(mutexRun_);
+    --runCount_;
+    cv_.notify_all();
+}
+
+/**
+ * @return true if the coroutine has not yet run to completion
+ */
+inline bool
+JobQueue::CoroTaskRunner::runnable() const
+{
+    // After normal completion, task_ is reset to break the shared_ptr cycle
+    // (handle_ becomes null). A null handle means the coroutine is done.
+    return task_.handle() && !task_.done();
+}
+
+/**
+ * Handle early termination when the coroutine never ran (e.g. JobQueue
+ * is stopping). Decrements nSuspend_ and destroys the coroutine frame
+ * to break the shared_ptr cycle: frame -> lambda -> runner -> frame.
+ */
+inline void
+JobQueue::CoroTaskRunner::expectEarlyExit()
+{
+    if (!finished_)
+    {
+        std::lock_guard lock(jq_.mutex_);
+        --jq_.nSuspend_;
+        finished_ = true;
+    }
+    // Break the shared_ptr cycle: frame -> shared_ptr<runner> -> this.
+    // The coroutine is at initial_suspend and never ran user code, so
+    // destroying it is safe. Use std::move (not task_ = {}) so
+    // task_.handle_ is null before the frame is destroyed.
+    {
+        [[maybe_unused]] auto completed = std::move(task_);
+    }
+    storedFunc_.reset();
+}
+
+/**
+ * Block until all pending/active resume operations complete.
+ * Uses cv_ + mutexRun_ to wait until runCount_ reaches 0 or
+ * finished_ becomes true. The finished_ check handles the case
+ * where resume() is called directly (without post()), which
+ * decrements runCount_ below zero. In that scenario runCount_
+ * never returns to 0, but finished_ becoming true guarantees
+ * the coroutine is done and no more resumes will occur.
+ */
+inline void
+JobQueue::CoroTaskRunner::join()
+{
+    std::unique_lock<std::mutex> lk(mutexRun_);
+    cv_.wait(lk, [this]() { return runCount_ == 0 || finished_; });
+}
+
+}  // namespace xrpl
--- a/include/xrpl/core/JobQueue.h
+++ b/include/xrpl/core/JobQueue.h
@@ -2,6 +2,7 @@

 #include <xrpl/basics/LocalValue.h>
 #include <xrpl/core/ClosureCounter.h>
+#include <xrpl/core/CoroTask.h>
 #include <xrpl/core/JobTypeData.h>
 #include <xrpl/core/detail/Workers.h>
 #include <xrpl/json/json_value.h>
@@ -24,6 +25,7 @@
 #include <atomic>
 #include <chrono>
 #include <condition_variable>
+#include <coroutine>
 #include <cstdint>
 #include <functional>
 #include <map>
@@ -152,6 +154,420 @@ public:
        join();
    };

+    /**
+     * C++20 coroutine lifecycle manager. Replaces Coro for new code.
+     *
+     *  Class / Inheritance / Dependency Diagram
+     *  =========================================
+     *
+     *  std::enable_shared_from_this<CoroTaskRunner>
+     *            ^
+     *            | (public inheritance)
+     *            |
+     *  CoroTaskRunner
+     *  +---------------------------------------------------+
+     *  | - lvs_         : detail::LocalValues               |
+     *  | - jq_          : JobQueue&                         |
+     *  | - type_        : JobType                           |
+     *  | - name_        : std::string                       |
+     *  | - runCount_    : int         (in-flight resumes)    |
+     *  | - mutex_       : std::mutex      (coroutine guard) |
+     *  | - mutexRun_    : std::mutex      (join guard)      |
+     *  | - cv_          : condition_variable                 |
+     *  | - task_        : CoroTask<void>                    |
+     *  | - storedFunc_  : unique_ptr<FuncBase> (type-erased)|
+     *  +---------------------------------------------------+
+     *  | + init(F&&)         : set up coroutine callable    |
+     *  | + onSuspend()       : ++jq_.nSuspend_              |
+     *  | + onUndoSuspend()   : --jq_.nSuspend_              |
+     *  | + suspend()         : returns SuspendAwaiter       |
+     *  | + post()            : schedule resume on JobQueue  |
+     *  | + resume()          : resume coroutine on caller   |
+     *  | + runnable()        : !task_.done()                |
+     *  | + expectEarlyExit() : teardown for failed post     |
+     *  | + join()            : block until not running       |
+     *  +---------------------------------------------------+
+     *          |                          |
+     *          | owns                     | references
+     *          v                          v
+     *    CoroTask<void>             JobQueue
+     *    (coroutine frame)          (thread pool + nSuspend_)
+     *
+     *    FuncBase / FuncStore<F>    (type-erased heap storage
+     *                                for the coroutine lambda)
+     *
+     *  Coroutine Lifecycle (Control Flow)
+     *  ===================================
+     *
+     *  Caller thread              JobQueue worker thread
+     *  -------------              ----------------------
+     *  postCoroTask(f)
+     *    |
+     *    +-- reserve a jobCounter_ slot (reject if JQ shutting down)
+     *    +-- ++nSuspend_  (lazy start counts as suspended)
+     *    +-- make_shared<CoroTaskRunner>
+     *    +-- init(f)
+     *    |     +-- store lambda on heap (FuncStore)
+     *    |     +-- task_ = f(shared_from_this())
+     *    |           [coroutine created, suspended at initial_suspend]
+     *    +-- post()
+     *    |     +-- ++runCount_
+     *    |     +-- addJob(type_, [resume]{})
+     *    |                                    resume()
+     *    |                                      |
+     *    |                                      +-- --nSuspend_
+     *    |                                      +-- swap in LocalValues
+     *    |                                      +-- task_.handle().resume()
+     *    |                                      |     [coroutine body runs]
+     *    |                                      |     ...
+     *    |                                      |     co_await suspend()
+     *    |                                      |       +-- ++nSuspend_
+     *    |                                      |       [coroutine suspends]
+     *    |                                      +-- swap out LocalValues
+     *    |                                      +-- --runCount_
+     *    |                                      +-- cv_.notify_all()
+     *    |
+     *  post()  <-- called externally or by yieldAndPost()
+     *    +-- ++runCount_
+     *    +-- addJob(type_, [resume]{})
+     *                                         resume()
+     *                                           |
+     *                                           +-- [coroutine body continues]
+     *                                           +-- co_return
+     *                                           +-- --runCount_
+     *                                           +-- cv_.notify_all()
+     *  join()
+     *    +-- cv_.wait([]{runCount_ == 0})
+     *    +-- [done]
+     *
+     *  Usage Examples
+     *  ==============
+     *
+     *  1. Fire-and-forget coroutine (most common pattern):
+     *
+     *      jq.postCoroTask(JtClient, "MyWork",
+     *          [](auto runner) -> CoroTask<void> {
+     *              doSomeWork();
+     *              co_await runner->suspend();  // yield to other jobs
+     *              doMoreWork();
+     *              co_return;
+     *          });
+     *
+     *  2. Manually controlling suspend / resume (external trigger):
+     *
+     *      auto runner = jq.postCoroTask(JtClient, "ExtTrigger",
+     *          [&result](auto runner) -> CoroTask<void> {
+     *              startAsyncOperation(callback);
+     *              co_await runner->suspend();
+     *              // callback called runner->post() to get here
+     *              result = collectResult();
+     *              co_return;
+     *          });
+     *      // ... later, from the callback:
+     *      runner->post();   // reschedule the coroutine on the JobQueue
+     *
+     *  3. Using yieldAndPost() for automatic suspend + repost:
+     *
+     *      jq.postCoroTask(JtClient, "AutoRepost",
+     *          [](auto runner) -> CoroTask<void> {
+     *              step1();
+     *              co_await runner->yieldAndPost();  // yield + auto-repost
+     *              step2();
+     *              co_await runner->yieldAndPost();
+     *              step3();
+     *              co_return;
+     *          });
+     *
+     *  4. Checking shutdown after co_await (cooperative cancellation):
+     *
+     *      jq.postCoroTask(JtClient, "Cancellable",
+     *          [&jq](auto runner) -> CoroTask<void> {
+     *              while (moreWork()) {
+     *                  co_await runner->yieldAndPost();
+     *                  if (jq.isStopping())
+     *                      co_return;  // bail out cleanly
+     *                  processNextItem();
+     *              }
+     *              co_return;
+     *          });
+     *
+     *  Caveats / Pitfalls
+     *  ==================
+     *
+     *  BUG-RISK: Calling suspend() without a matching post()/resume().
+     *    After co_await runner->suspend(), the coroutine is parked and
+     *    nSuspend_ is incremented.  If nothing ever calls post() or
+     *    resume(), the coroutine is leaked and JobQueue::stop() will
+     *    hang forever waiting for nSuspend_ to reach zero.
+     *
+     *  BUG-RISK: Calling post() on an already-running coroutine.
+     *    post() schedules a resume() job.  If the coroutine has not
+     *    actually suspended yet (no co_await executed), the resume job
+     *    will try to call handle().resume() while the coroutine is still
+     *    running on another thread.  This is UB.  The mutex_ prevents
+     *    data corruption but the logic is wrong — always co_await
+     *    suspend() before calling post().  (The test incorrect_order()
+     *    shows this works only because mutex_ serializes the calls.)
+     *
+     *  BUG-RISK: Dropping the shared_ptr<CoroTaskRunner> before join().
+     *    The CoroTaskRunner destructor asserts that finished_ is true
+     *    (the coroutine completed). If you let the last shared_ptr die
+     *    while the coroutine is still running or suspended, you get an
+     *    assertion failure in debug and UB in release.  Always call
+     *    join() or expectEarlyExit() first.
+     *
+     *  BUG-RISK: Lambda captures outliving the coroutine frame.
+     *    The lambda passed to postCoroTask is heap-allocated (FuncStore)
+     *    to prevent dangling.  But objects captured by pointer still need
+     *    their own lifetime management.  If you capture a raw pointer to
+     *    a stack variable, and the stack frame exits before the coroutine
+     *    finishes, the pointer dangles.  Use shared_ptr or ensure the
+     *    pointed-to object outlives the coroutine.
+     *
+     *  BUG-RISK: Forgetting co_return in a void coroutine.
+     *    If the coroutine body falls off the end without co_return,
+     *    the compiler may silently treat it as co_return (per standard),
+     *    but some compilers warn.  Always write explicit co_return.
+     *
+     *  LIMITATION: CoroTaskRunner only supports CoroTask<void>.
+     *    The task_ member is CoroTask<void>.  To return values from
+     *    the top-level coroutine, write through a captured pointer
+     *    (as the tests demonstrate), or co_await inner CoroTask<T>
+     *    coroutines that return values.
+     *
+     *  LIMITATION: One coroutine per CoroTaskRunner.
+     *    init() must be called exactly once.  You cannot reuse a
+     *    CoroTaskRunner to run a second coroutine.  Create a new one
+     *    via postCoroTask() instead.
+     *
+     *  LIMITATION: No timeout on join().
+     *    join() blocks indefinitely.  If the coroutine is suspended
+     *    and never posted, join() will deadlock.  Use timed waits
+     *    on the gate pattern (condition_variable + wait_for) in tests.
+     */
+    class CoroTaskRunner : public std::enable_shared_from_this<CoroTaskRunner>
+    {
+    private:
+        // Per-coroutine thread-local storage. Swapped in before resume()
+        // and swapped out after, so each coroutine sees its own LocalValue
+        // state regardless of which worker thread executes it.
+        detail::LocalValues lvs_;
+
+        // Back-reference to the owning JobQueue. Used to post jobs,
+        // increment/decrement nSuspend_, and acquire jq_.mutex_.
+        JobQueue& jq_;
+
+        // Job type passed to addJob() when posting this coroutine.
+        JobType type_;
+
+        // Human-readable name for this coroutine job (for logging).
+        std::string name_;
+
+        // Number of in-flight resume operations (pending + active).
+        // Incremented by post(), decremented when resume() finishes.
+        // Guarded by mutexRun_. join() blocks until this reaches 0.
+        //
+        // A counter (not a bool) is needed because post() can be called
+        // from within the coroutine body (e.g. via yieldAndPost()),
+        // enqueuing a second resume while the first is still running.
+        // A bool would be clobbered: R2.post() sets true, then R1's
+        // cleanup sets false — losing the fact that R2 is still pending.
+        int runCount_;
+
+        // Serializes all coroutine resume() calls, preventing concurrent
+        // execution of the coroutine body on multiple threads. Handles the
+        // race where post() enqueues a resume before the coroutine has
+        // actually suspended (post-before-suspend pattern).
+        std::mutex mutex_;
+
+        // Guards runCount_. Used with cv_ for join() to wait
+        // until all pending/active resume operations complete.
+        std::mutex mutexRun_;
+
+        // Notified when runCount_ reaches zero, allowing
+        // join() waiters to wake up.
+        std::condition_variable cv_;
+
+        // The coroutine handle wrapper. Owns the coroutine frame.
+        // Set by init(). Reset to empty in resume() upon coroutine
+        // completion (to break the shared_ptr cycle) or in
+        // expectEarlyExit() on early termination.
+        CoroTask<void> task_;
+
+        /**
+         * Type-erased base for heap-stored callables.
+         * Prevents the coroutine lambda from being destroyed before
+         * the coroutine frame is done with it.
+         *
+         * @see FuncStore
+         */
+        struct FuncBase
+        {
+            virtual ~FuncBase() = default;
+        };
+
+        /**
+         * Concrete type-erased storage for a callable of type F.
+         * The coroutine frame stores a reference to the lambda's implicit
+         * object parameter. If the lambda is a temporary, that reference
+         * dangles after the call returns. FuncStore keeps it alive on
+         * the heap for the lifetime of the CoroTaskRunner.
+         */
+        template <class F>
+        struct FuncStore : FuncBase
+        {
+            F func;  // The stored callable (coroutine lambda).
+            explicit FuncStore(F&& f) : func(std::move(f))
+            {
+            }
+        };
+
+        // Heap-allocated callable storage. Set by init(), ensures the
+        // lambda outlives the coroutine frame that references it.
+        std::unique_ptr<FuncBase> storedFunc_;
+
+        // True once the coroutine has completed or expectEarlyExit() was
+        // called. Asserted in the destructor (debug) to catch leaked
+        // runners. Available in all builds to guard expectEarlyExit()
+        // against double-decrementing nSuspend_.
+        bool finished_ = false;
+
+    public:
+        /**
+         * Tag type for private construction. Prevents external code
+         * from constructing CoroTaskRunner directly. Use postCoroTask().
+         */
+        struct CreateT
+        {
+            explicit CreateT() = default;
+        };
+
+        /**
+         * Construct a CoroTaskRunner. Private by convention (CreateT tag).
+         *
+         * @param jq   The JobQueue this coroutine will run on
+         * @param type Job type for scheduling priority
+         * @param name Human-readable name for logging
+         */
+        CoroTaskRunner(CreateT, JobQueue&, JobType, std::string const&);
+
+        CoroTaskRunner(CoroTaskRunner const&) = delete;
+        CoroTaskRunner&
+        operator=(CoroTaskRunner const&) = delete;
+
+        /**
+         * Destructor. Asserts (debug) that the coroutine has finished
+         * or expectEarlyExit() was called.
+         */
+        ~CoroTaskRunner();
+
+        /**
+         * Initialize with a coroutine-returning callable.
+         * Must be called exactly once, after the object is managed by
+         * shared_ptr (because init uses shared_from_this internally).
+         * This is handled automatically by postCoroTask().
+         *
+         * @param f Callable: CoroTask<void>(shared_ptr<CoroTaskRunner>)
+         */
+        template <class F>
+        void
+        init(F&& f);
+
+        /**
+         * Increment the JobQueue's suspended-coroutine count (nSuspend_).
+         * Called when the coroutine is about to suspend. Every call
+         * must be balanced by a corresponding decrement (via resume()
+         * or onUndoSuspend()), or JobQueue::stop() will hang.
+         */
+        void
+        onSuspend();
+
+        /**
+         * Decrement nSuspend_ without resuming.
+         * Used to undo onSuspend() when a scheduled post() fails
+         * (e.g. JobQueue is stopping).
+         */
+        void
+        onUndoSuspend();
+
+        /**
+         * Suspend the coroutine.
+         * The awaiter's await_suspend() increments nSuspend_ before the
+         * coroutine actually suspends. The caller must later call post()
+         * or resume() to continue execution.
+         *
+         * @return An awaiter for use with `co_await runner->suspend()`
+         */
+        auto
+        suspend();
+
+        /**
+         * Suspend the coroutine and immediately repost it on the
+         * JobQueue. Combines suspend() + post() atomically inside
+         * await_suspend, so there is no window where an external
+         * event could race between the two.
+         *
+         * Equivalent to JobQueueAwaiter but defined as an inline
+         * awaiter returned from a member function. This avoids a
+         * GCC-12 coroutine codegen bug where an external awaiter
+         * struct (JobQueueAwaiter) used at multiple co_await points
+         * corrupts the coroutine state machine's resume index,
+         * causing the coroutine to hang on the third resumption.
+         *
+         * @return An awaiter for use with `co_await runner->yieldAndPost()`
+         */
+        auto
+        yieldAndPost();
+
+        /**
+         * Schedule coroutine resumption as a job on the JobQueue.
+         * Captures shared_from_this() to prevent this runner from being
+         * destroyed while the job is queued.
+         *
+         * @return true if the job was accepted; false if the JobQueue
+         *         is stopping (caller must handle cleanup)
+         */
+        bool
+        post();
+
+        /**
+         * Resume the coroutine on the current thread.
+         * Decrements nSuspend_, swaps in LocalValues, resumes the
+         * coroutine handle, swaps out LocalValues, and notifies join()
+         * waiters. Lock ordering (sequential, non-overlapping):
+         * jq_.mutex_ -> mutex_ -> mutexRun_.
+         *
+         * @pre post() must have been called before resume(). Direct
+         *      calls without a prior post() will corrupt runCount_
+         *      and break join().
+         */
+        void
+        resume();
+
+        /**
+         * @return true if the coroutine has not yet run to completion
+         */
+        bool
+        runnable() const;
+
+        /**
+         * Handle early termination when the coroutine never ran.
+         * Decrements nSuspend_ and destroys the coroutine frame to
+         * break the shared_ptr cycle (frame -> lambda -> runner -> frame).
+         * Called by postCoroTask() when post() fails.
+         */
+        void
+        expectEarlyExit();
+
+        /**
+         * Block until all pending/active resume operations complete.
+         * Uses cv_ + mutexRun_ to wait until runCount_ reaches 0.
+         * Warning: deadlocks if the coroutine is suspended and never posted.
+         */
+        void
+        join();
+    };
+
    using JobFunction = std::function<void()>;

    JobQueue(
@@ -197,6 +613,20 @@ public:
    std::shared_ptr<Coro>
    postCoro(JobType t, std::string const& name, F&& f);

+    /**
+     * Creates a C++20 coroutine and adds a job to the queue to run it.
+     *
+     * @param t The type of job.
+     * @param name Name of the job.
+     * @param f Callable with signature
+     * CoroTask<void>(std::shared_ptr<CoroTaskRunner>).
+     *
+     * @return shared_ptr to posted CoroTaskRunner. nullptr if not successful.
+     */
+    template <class F>
+    std::shared_ptr<CoroTaskRunner>
+    postCoroTask(JobType t, std::string const& name, F&& f);
+
    /**
     * Jobs waiting at this priority.
     */
@@ -419,7 +849,8 @@ private:

 }  // namespace xrpl

-#include <xrpl/core/Coro.ipp>  // IWYU pragma: keep
+#include <xrpl/core/Coro.ipp>            // IWYU pragma: keep
+#include <xrpl/core/CoroTaskRunner.ipp>  // IWYU pragma: keep

 namespace xrpl {

@@ -442,4 +873,82 @@ JobQueue::postCoro(JobType t, std::string const& name, F&& f)
    return coro;
 }

+// postCoroTask — entry point for launching a C++20 coroutine on the JobQueue.
+//
+// Control Flow
+// ============
+//
+//   postCoroTask(t, name, f)
+//     |
+//     +-- 1. Reserve a jobCounter_ slot — reject if JQ shutting down
+//     |
+//     +-- 2. ++nSuspend_   (mirrors Boost Coro ctor's implicit yield)
+//     |        The coroutine is "suspended" from the JobQueue's perspective
+//     |        even though it hasn't run yet — this keeps the JQ shutdown
+//     |        logic correct (it waits for nSuspend_ to reach 0).
+//     |
+//     +-- 3. Create CoroTaskRunner (shared_ptr, ref-counted)
+//     |
+//     +-- 4. runner->init(f)
+//     |        +-- Heap-allocate the lambda (FuncStore) to prevent
+//     |        |   dangling captures in the coroutine frame
+//     |        +-- task_ = f(shared_from_this())
+//     |              [coroutine created but NOT started — lazy initial_suspend]
+//     |
+//     +-- 5. runner->post()
+//     |        +-- addJob(type_, [resume]{})   → resume on worker thread
+//     |        +-- failure (JQ stopping):
+//     |              +-- runner->expectEarlyExit()
+//     |              |     --nSuspend_, destroy coroutine frame
+//     |              +-- return nullptr
+//     |
+//     +-- 6. Release the jobCounter_ slot (on return)
+//
+// Why reserve a jobCounter_ slot?
+// ===============================
+// JobQueue::stop() joins jobCounter_ before it acquires mutex_ and asserts
+// nSuspend_ == 0.  Without a reservation, stop() could run to completion in
+// the window between the ++nSuspend_ in step 2 and the balancing post() or
+// expectEarlyExit() in step 5, tripping that assert.  Holding a slot blocks
+// stop()'s join() for the whole function, closing the window.  wrap() also
+// returns nullopt once the counter is joined, so it doubles as the shutdown
+// check — a plain stopping_ read cannot do this, because the read and the
+// ++nSuspend_ are not a single atomic step.
+//
+// Why async post() instead of synchronous resume()?
+// ==================================================
+// The initial dispatch MUST use async post() so the coroutine body runs on
+// a JobQueue worker thread, not the caller's thread.  resume() swaps the
+// caller's thread-local LocalValues with the coroutine's private copy.
+// If the coroutine mutates LocalValues (e.g. thread_specific_storage test),
+// those mutations bleed back into the caller's thread-local state after the
+// swap-out, corrupting subsequent tests that share the same thread pool.
+// Async post() avoids this by running the coroutine on a worker thread whose
+// LocalValues are managed by the thread pool, not by the caller.
+//
+template <class F>
+std::shared_ptr<JobQueue::CoroTaskRunner>
+JobQueue::postCoroTask(JobType t, std::string const& name, F&& f)
+{
+    // Held until this function returns. Null once jobCounter_ is joined,
+    // which is how a shutting-down JobQueue rejects new coroutines.
+    auto const shutdownGuard = jobCounter_.wrap([]() {});
+    if (!shutdownGuard)
+        return nullptr;
+
+    {
+        std::lock_guard lock(mutex_);
+        ++nSuspend_;
+    }
+
+    auto runner = std::make_shared<CoroTaskRunner>(CoroTaskRunner::CreateT{}, *this, t, name);
+    runner->init(std::forward<F>(f));
+    if (!runner->post())
+    {
+        runner->expectEarlyExit();
+        runner.reset();
+    }
+    return runner;
+}
+
 }  // namespace xrpl
--- a/include/xrpl/core/JobQueueAwaiter.h
+++ b/include/xrpl/core/JobQueueAwaiter.h
@@ -0,0 +1,206 @@
+#pragma once
+
+#include <xrpl/core/JobQueue.h>
+
+#include <coroutine>
+#include <memory>
+
+namespace xrpl {
+
+/**
+ * Awaiter that suspends and immediately reschedules on the JobQueue.
+ * Equivalent to calling yield() followed by post() in the old Coro API.
+ *
+ * Usage:
+ *     co_await JobQueueAwaiter{runner};
+ *
+ * What it waits for: The coroutine is re-queued as a job and resumes
+ * when a worker thread picks it up.
+ *
+ * Which thread resumes: A JobQueue worker thread.
+ *
+ * What await_resume() returns: void.
+ *
+ * Dependency Diagram
+ * ==================
+ *
+ *   JobQueueAwaiter
+ *   +----------------------------------------------+
+ *   | + runner : shared_ptr<CoroTaskRunner>         |
+ *   +----------------------------------------------+
+ *   | + await_ready()   -> false (always suspend)   |
+ *   | + await_suspend() -> bool (suspend or cancel) |
+ *   | + await_resume()  -> void                     |
+ *   +----------------------------------------------+
+ *          |                         |
+ *          | uses                    | uses
+ *          v                         v
+ *   CoroTaskRunner              JobQueue
+ *   .onSuspend()                (via runner->post() -> addJob)
+ *   .onUndoSuspend()
+ *   .post()
+ *
+ * Control Flow (await_suspend)
+ * ============================
+ *
+ *   co_await JobQueueAwaiter{runner}
+ *     |
+ *     +-- await_ready() -> false
+ *     +-- await_suspend(handle)
+ *           |
+ *           +-- runner->onSuspend()     // ++nSuspend_
+ *           +-- runner->post()          // addJob to JobQueue
+ *           |     |
+ *           |     +-- success? return noop_coroutine()
+ *           |     |     // coroutine stays suspended;
+ *           |     |     // worker thread will call resume()
+ *           |     +-- failure? (JQ stopping)
+ *           |           +-- runner->onUndoSuspend()  // --nSuspend_
+ *           |           +-- return handle  // symmetric transfer back
+ *           |                              // coroutine continues immediately
+ *           |                              // so it can clean up and co_return
+ *
+ * DEPRECATED — prefer `co_await runner->yieldAndPost()`
+ * =====================================================
+ *
+ * GCC-12 has a coroutine codegen bug where using this external awaiter
+ * struct at multiple co_await points in the same coroutine corrupts the
+ * state machine's resume index. After the second co_await, the third
+ * resumption enters handle().resume() but never reaches await_resume()
+ * or any subsequent user code — the coroutine hangs indefinitely.
+ *
+ * The fix is `co_await runner->yieldAndPost()`, which defines the
+ * awaiter as an inline struct inside a CoroTaskRunner member function.
+ * GCC-12 handles inline awaiters correctly at multiple co_await points.
+ *
+ * This struct is retained for single-use scenarios and documentation
+ * purposes. For any code that may use co_await in a loop or at
+ * multiple points, always use `runner->yieldAndPost()`.
+ *
+ * Usage Examples
+ * ==============
+ *
+ * 1. Yield and auto-repost (preferred — works on all compilers):
+ *
+ *     CoroTask<void> handler(auto runner) {
+ *         doPartA();
+ *         co_await runner->yieldAndPost();   // yield + repost
+ *         doPartB();                         // runs on a worker thread
+ *         co_return;
+ *     }
+ *
+ * 2. Multiple yield points in a loop:
+ *
+ *     CoroTask<void> batchProcessor(auto runner) {
+ *         for (auto& item : items) {
+ *             process(item);
+ *             co_await runner->yieldAndPost();  // let other jobs run
+ *         }
+ *         co_return;
+ *     }
+ *
+ * 3. Graceful shutdown — checking after resume:
+ *
+ *     CoroTask<void> longTask(auto runner, JobQueue& jq) {
+ *         while (hasWork()) {
+ *             co_await runner->yieldAndPost();
+ *             // If JQ is stopping, await_suspend resumes the coroutine
+ *             // immediately without re-queuing. Always check
+ *             // isStopping() to decide whether to proceed:
+ *             if (jq.isStopping())
+ *                 co_return;
+ *             doNextChunk();
+ *         }
+ *         co_return;
+ *     }
+ *
+ * Caveats / Pitfalls
+ * ==================
+ *
+ * BUG-RISK: Using a stale or null runner.
+ *   The runner shared_ptr must be valid and point to the CoroTaskRunner
+ *   that owns the coroutine currently executing. Passing a runner from
+ *   a different coroutine, or a default-constructed shared_ptr, is UB.
+ *
+ * BUG-RISK: Assuming resume happens on the same thread.
+ *   After co_await, the coroutine resumes on whatever worker thread
+ *   picks up the job. Do not rely on thread-local state unless it is
+ *   managed through LocalValue (which CoroTaskRunner automatically
+ *   swaps in/out).
+ *
+ * BUG-RISK: Ignoring the shutdown path.
+ *   When the JobQueue is stopping, post() fails and await_suspend()
+ *   resumes the coroutine immediately (symmetric transfer back to h).
+ *   The coroutine body continues on the same thread. If your code
+ *   after co_await assumes it was re-queued and is running on a worker
+ *   thread, that assumption breaks during shutdown. Always handle the
+ *   "JQ is stopping" case, either by checking jq.isStopping() or by
+ *   letting the coroutine fall through to co_return naturally.
+ *
+ * DIFFERENCE from runner->suspend() + runner->post():
+ *   Both JobQueueAwaiter and yieldAndPost() combine suspend + post
+ *   in one atomic operation. With the manual suspend()/post() pattern,
+ *   there is a window between the two calls where an external event
+ *   could race. The atomic awaiters remove that window — onSuspend()
+ *   and post() happen within the same await_suspend() call while the
+ *   coroutine is guaranteed to be suspended. Use yieldAndPost() unless
+ *   you need an external party to decide *when* to call post().
+ */
+struct JobQueueAwaiter
+{
+    // The CoroTaskRunner that owns the currently executing coroutine.
+    std::shared_ptr<JobQueue::CoroTaskRunner> runner;
+
+    /**
+     * Always returns false so the coroutine suspends.
+     */
+    bool
+    await_ready() const noexcept
+    {
+        return false;
+    }
+
+    /**
+     * Increment nSuspend (equivalent to yield()) and schedule resume
+     * on the JobQueue (equivalent to post()). If the JobQueue is
+     * stopping, undoes the suspend count and transfers back to the
+     * coroutine so it can clean up and co_return.
+     *
+     * Returns a coroutine_handle<> (symmetric transfer) instead of
+     * bool to work around a GCC-12 codegen bug where bool-returning
+     * await_suspend leaves the coroutine in an invalid state —
+     * neither properly suspended nor resumed — causing a hang.
+     *
+     * WARNING: GCC-12 has an additional codegen bug where using this
+     * external awaiter struct at multiple co_await points in the same
+     * coroutine corrupts the state machine's resume index, causing the
+     * coroutine to hang on the third resumption. Prefer
+     * `co_await runner->yieldAndPost()` which uses an inline awaiter
+     * that GCC-12 handles correctly.
+     *
+     * @return noop_coroutine() to stay suspended (job posted);
+     *         the caller's handle to resume immediately (JQ stopping)
+     */
+    std::coroutine_handle<>
+    await_suspend(std::coroutine_handle<> h)
+    {
+        XRPL_ASSERT(runner, "xrpl::JobQueueAwaiter::await_suspend : runner is valid");
+        runner->onSuspend();
+        if (!runner->post())
+        {
+            // JobQueue is stopping. Undo the suspend count and
+            // transfer back to the coroutine so it can clean up
+            // and co_return.
+            runner->onUndoSuspend();
+            return h;
+        }
+        return std::noop_coroutine();
+    }
+
+    void
+    await_resume() const noexcept
+    {
+    }
+};
+
+}  // namespace xrpl
--- a/include/xrpl/peerfinder/Config.h
+++ b/include/xrpl/peerfinder/Config.h
@@ -0,0 +1,163 @@
+#pragma once
+
+#include <xrpl/beast/utility/PropertyStream.h>
+#include <xrpl/peerfinder/detail/Tuning.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace xrpl::PeerFinder {
+
+struct PeerLimitConfig
+{
+    std::optional<std::size_t> maxPeers;
+    std::optional<std::size_t> inPeers;
+    std::optional<std::size_t> outPeers;
+};
+
+/**
+ * PeerFinder configuration settings.
+ */
+struct Config
+{
+    /**
+     * The largest number of public peer slots to allow.
+     * This includes both inbound and outbound, but does not include
+     * fixed peers.
+     */
+    std::size_t maxPeers{Tuning::kDefaultMaxPeers};
+
+    /**
+     * The number of automatic outbound connections to maintain.
+     * Outbound connections are only maintained if autoConnect
+     * is `true`.
+     */
+    std::size_t outPeers = calcOutPeers();  // Note: relies on `maxPeers` being initialized
+
+    /**
+     * The number of automatic inbound connections to maintain.
+     * Inbound connections are only maintained if wantIncoming
+     * is `true`.
+     */
+    std::size_t inPeers{0};
+
+    /**
+     * `true` if we want our IP address kept private.
+     */
+    bool peerPrivate = true;
+
+    /**
+     * `true` if we want to accept incoming connections.
+     */
+    bool wantIncoming{true};
+
+    /**
+     * `true` if we want to establish connections automatically
+     */
+    bool autoConnect{true};
+
+    /**
+     * The listening port number.
+     */
+    std::uint16_t listeningPort{0};
+
+    /**
+     * The set of features we advertise.
+     */
+    std::string features;
+
+    /**
+     * Limit how many incoming connections we allow per IP
+     */
+    int ipLimit{0};
+
+    /**
+     * `true` if we want to verify endpoints in TMEndpoints messages
+     */
+    bool verifyEndpoints = true;
+
+    //--------------------------------------------------------------------------
+
+    /**
+     * Returns a suitable value for outPeers according to the rules.
+     */
+    [[nodiscard]] std::size_t
+    calcOutPeers() const;
+
+    /**
+     * Adjusts the values so they follow the business rules.
+     */
+    void
+    applyTuning();
+
+    /**
+     * Write the configuration into a property stream
+     */
+    void
+    onWrite(beast::PropertyStream::Map& map) const;
+
+    /**
+     * Make PeerFinder::Config from peer limit and server mode parameters.
+     */
+    static Config
+    makeConfig(
+        bool peerPrivate,
+        bool standalone,
+        PeerLimitConfig const& limits,
+        std::uint16_t port,
+        bool validationPublicKey,
+        int ipLimit,
+        bool verifyEndpoints);
+
+    /**
+     * Compares two configurations for equality field by field.
+     */
+    friend bool
+    operator==(Config const& lhs, Config const& rhs) = default;
+};
+
+//------------------------------------------------------------------------------
+
+/**
+ * Possible results from activating a slot.
+ */
+enum class Result { InboundDisabled, DuplicatePeer, IpLimitExceeded, Full, Success };
+
+/**
+ * @brief Converts a `Result` enum value to its string representation.
+ *
+ * This function provides a human-readable string for a given `Result` enum,
+ * which is useful for logging, debugging, or displaying status messages.
+ *
+ * @param result The `Result` enum value to convert.
+ * @return A `std::string_view` representing the enum value. Returns "unknown"
+ * if the enum value is not explicitly handled.
+ *
+ * @note This function returns a `std::string_view` for performance.
+ * A `std::string` would need to allocate memory on the heap and copy the
+ * string literal into it every time the function is called.
+ */
+inline std::string_view
+to_string(Result result) noexcept
+{
+    switch (result)
+    {
+        case Result::InboundDisabled:
+            return "inbound disabled";
+        case Result::DuplicatePeer:
+            return "peer already connected";
+        case Result::IpLimitExceeded:
+            return "ip limit exceeded";
+        case Result::Full:
+            return "slots full";
+        case Result::Success:
+            return "success";
+    }
+
+    return "unknown";
+}
+
+}  // namespace xrpl::PeerFinder
--- a/include/xrpl/peerfinder/PeerfinderManager.h
+++ b/include/xrpl/peerfinder/PeerfinderManager.h
@@ -0,0 +1,179 @@
+#pragma once
+
+#include <xrpl/beast/net/IPEndpoint.h>
+#include <xrpl/beast/utility/PropertyStream.h>
+#include <xrpl/peerfinder/Config.h>
+#include <xrpl/peerfinder/Slot.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/protocol/PublicKey.h>
+
+#include <boost/asio/ip/tcp.hpp>
+
+#include <memory>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace xrpl::PeerFinder {
+
+/**
+ * Maintains a set of IP addresses used for getting into the network.
+ */
+class Manager : public beast::PropertyStream::Source
+{
+protected:
+    Manager() noexcept;
+
+public:
+    /**
+     * Destroy the object.
+     * Any pending source fetch operations are aborted.
+     * There may be some listener calls made before the
+     * destructor returns.
+     */
+    ~Manager() override = default;
+
+    /**
+     * Set the configuration for the manager.
+     * The new settings will be applied asynchronously.
+     * Thread safety:
+     *     Can be called from any threads at any time.
+     */
+    virtual void
+    setConfig(Config const& config) = 0;
+
+    /**
+     * Transition to the started state, synchronously.
+     */
+    virtual void
+    start() = 0;
+
+    /**
+     * Transition to the stopped state, synchronously.
+     */
+    virtual void
+    stop() = 0;
+
+    /**
+     * Returns the configuration for the manager.
+     */
+    virtual Config
+    config() = 0;
+
+    /**
+     * Add a peer that should always be connected.
+     * This is useful for maintaining a private cluster of peers.
+     * The string is the name as specified in the configuration
+     * file, along with the set of corresponding IP addresses.
+     */
+    virtual void
+    addFixedPeer(std::string_view name, std::vector<beast::IP::Endpoint> const& addresses) = 0;
+
+    /**
+     * Add a set of strings as fallback IP::Endpoint sources.
+     * @param name A label used for diagnostics.
+     */
+    virtual void
+    addFallbackStrings(std::string const& name, std::vector<std::string> const& strings) = 0;
+
+    /**
+     * Add a URL as a fallback location to obtain IP::Endpoint sources.
+     * @param name A label used for diagnostics.
+     */
+    /* VFALCO NOTE Unimplemented
+    virtual void addFallbackURL (std::string const& name,
+        std::string const& url) = 0;
+    */
+
+    //--------------------------------------------------------------------------
+
+    /**
+     * Create a new inbound slot with the specified remote endpoint.
+     * If nullptr is returned, then the slot could not be assigned.
+     * Usually this is because of a detected self-connection.
+     */
+    virtual std::pair<std::shared_ptr<Slot>, Result>
+    newInboundSlot(
+        beast::IP::Endpoint const& localEndpoint,
+        beast::IP::Endpoint const& remoteEndpoint) = 0;
+
+    /**
+     * Create a new outbound slot with the specified remote endpoint.
+     * If nullptr is returned, then the slot could not be assigned.
+     * Usually this is because of a duplicate connection.
+     */
+    virtual std::pair<std::shared_ptr<Slot>, Result>
+    newOutboundSlot(beast::IP::Endpoint const& remoteEndpoint) = 0;
+
+    /**
+     * Called when mtENDPOINTS is received.
+     */
+    virtual void
+    onEndpoints(std::shared_ptr<Slot> const& slot, Endpoints const& endpoints) = 0;
+
+    /**
+     * Called when the slot is closed.
+     * This always happens when the socket is closed, unless the socket
+     * was canceled.
+     */
+    virtual void
+    onClosed(std::shared_ptr<Slot> const& slot) = 0;
+
+    /**
+     * Called when an outbound connection is deemed to have failed
+     */
+    virtual void
+    onFailure(std::shared_ptr<Slot> const& slot) = 0;
+
+    /**
+     * Called when we received redirect IPs from a busy peer.
+     */
+    virtual void
+    onRedirects(
+        boost::asio::ip::tcp::endpoint const& remoteAddress,
+        std::vector<boost::asio::ip::tcp::endpoint> const& eps) = 0;
+
+    //--------------------------------------------------------------------------
+
+    /**
+     * Called when an outbound connection attempt succeeds.
+     * The local endpoint must be valid. If the caller receives an error
+     * when retrieving the local endpoint from the socket, it should
+     * proceed as if the connection attempt failed by calling on_closed
+     * instead of on_connected.
+     * @return `true` if the connection should be kept
+     */
+    virtual bool
+    onConnected(std::shared_ptr<Slot> const& slot, beast::IP::Endpoint const& localEndpoint) = 0;
+
+    /**
+     * Request an active slot type.
+     */
+    virtual Result
+    activate(std::shared_ptr<Slot> const& slot, PublicKey const& key, bool reserved) = 0;
+
+    /**
+     * Returns a set of endpoints suitable for redirection.
+     */
+    virtual std::vector<Endpoint>
+    redirect(std::shared_ptr<Slot> const& slot) = 0;
+
+    /**
+     * Return a set of addresses we should connect to.
+     */
+    virtual std::vector<beast::IP::Endpoint>
+    autoconnect() = 0;
+
+    virtual std::vector<std::pair<std::shared_ptr<Slot>, std::vector<Endpoint>>>
+    buildEndpointsForPeers() = 0;
+
+    /**
+     * Perform periodic activity.
+     * This should be called once per second.
+     */
+    virtual void
+    oncePerSecond() = 0;
+};
+
+}  // namespace xrpl::PeerFinder
--- a/include/xrpl/peerfinder/Slot.h
+++ b/include/xrpl/peerfinder/Slot.h
--- a/include/xrpl/peerfinder/Types.h
+++ b/include/xrpl/peerfinder/Types.h
@@ -0,0 +1,46 @@
+#pragma once
+
+#include <xrpl/beast/clock/abstract_clock.h>
+#include <xrpl/beast/net/IPEndpoint.h>
+#include <xrpl/peerfinder/detail/Tuning.h>
+
+#include <chrono>
+#include <cstdint>
+#include <vector>
+
+namespace xrpl::PeerFinder {
+
+using clock_type = beast::AbstractClock<std::chrono::steady_clock>;
+
+/**
+ * Represents a set of addresses.
+ */
+using IPAddresses = std::vector<beast::IP::Endpoint>;
+
+//------------------------------------------------------------------------------
+
+/**
+ * Describes a connectable peer address along with some metadata.
+ */
+struct Endpoint
+{
+    Endpoint() = default;
+
+    Endpoint(beast::IP::Endpoint ep, std::uint32_t hops);
+
+    std::uint32_t hops = 0;
+    beast::IP::Endpoint address;
+};
+
+inline bool
+operator<(Endpoint const& lhs, Endpoint const& rhs)
+{
+    return lhs.address < rhs.address;
+}
+
+/**
+ * A set of Endpoint used for connecting.
+ */
+using Endpoints = std::vector<Endpoint>;
+
+}  // namespace xrpl::PeerFinder
--- a/include/xrpl/peerfinder/detail/Bootcache.h
+++ b/include/xrpl/peerfinder/detail/Bootcache.h
@@ -1,11 +1,11 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/detail/Store.h>
-
 #include <xrpl/beast/net/IPEndpoint.h>
 #include <xrpl/beast/utility/Journal.h>
 #include <xrpl/beast/utility/PropertyStream.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/Store.h>
+#include <xrpl/peerfinder/detail/Tuning.h>

 #include <boost/bimap.hpp>
 #include <boost/bimap/multiset_of.hpp>
--- a/include/xrpl/peerfinder/detail/Checker.h
+++ b/include/xrpl/peerfinder/detail/Checker.h
--- a/include/xrpl/peerfinder/detail/Counts.h
+++ b/include/xrpl/peerfinder/detail/Counts.h
@@ -1,11 +1,10 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/Slot.h>
-#include <xrpld/peerfinder/detail/Tuning.h>
-
 #include <xrpl/beast/utility/PropertyStream.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/peerfinder/Config.h>
+#include <xrpl/peerfinder/Slot.h>
+#include <xrpl/peerfinder/detail/Tuning.h>

 #include <cstddef>
 #include <sstream>
--- a/include/xrpl/peerfinder/detail/Fixed.h
+++ b/include/xrpl/peerfinder/detail/Fixed.h
@@ -1,7 +1,7 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/detail/Tuning.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/Tuning.h>

 #include <algorithm>
 #include <chrono>
--- a/include/xrpl/peerfinder/detail/Handouts.h
+++ b/include/xrpl/peerfinder/detail/Handouts.h
@@ -1,12 +1,11 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/detail/SlotImp.h>
-#include <xrpld/peerfinder/detail/Tuning.h>
-
 #include <xrpl/beast/container/aged_set.h>
 #include <xrpl/beast/net/IPAddress.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/SlotImp.h>
+#include <xrpl/peerfinder/detail/Tuning.h>

 #include <algorithm>
 #include <cstddef>
--- a/include/xrpl/peerfinder/detail/Livecache.h
+++ b/include/xrpl/peerfinder/detail/Livecache.h
@@ -1,9 +1,5 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/detail/Tuning.h>
-#include <xrpld/peerfinder/detail/iosformat.h>
-
 #include <xrpl/basics/Log.h>
 #include <xrpl/basics/random.h>
 #include <xrpl/beast/container/aged_map.h>
@@ -12,6 +8,8 @@
 #include <xrpl/beast/utility/PropertyStream.h>
 #include <xrpl/beast/utility/instrumentation.h>
 #include <xrpl/beast/utility/maybe_const.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/Tuning.h>

 #include <boost/intrusive/list.hpp>
 #include <boost/iterator/transform_iterator.hpp>
@@ -22,6 +20,8 @@
 #include <cstddef>
 #include <cstdint>
 #include <functional>
+#include <iomanip>
+#include <ios>
 #include <iterator>
 #include <memory>
 #include <sstream>
@@ -411,7 +411,7 @@ Livecache<Allocator>::expire()
    }
    if (n > 0)
    {
-        JLOG(journal_.debug()) << beast::Leftw(18) << "Livecache expired " << n
+        JLOG(journal_.debug()) << std::left << std::setw(18) << "Livecache expired " << n
                               << ((n > 1) ? " entries" : " entry");
    }
 }
@@ -434,7 +434,7 @@ Livecache<Allocator>::insert(Endpoint const& ep)
    if (result.second)
    {
        hops.insert(e);
-        JLOG(journal_.debug()) << beast::Leftw(18) << "Livecache insert " << ep.address
+        JLOG(journal_.debug()) << std::left << std::setw(18) << "Livecache insert " << ep.address
                               << " at hops " << ep.hops;
        return;
    }
@@ -442,7 +442,7 @@ Livecache<Allocator>::insert(Endpoint const& ep)
    {
        // Drop duplicates at higher hops
        std::size_t const excess(ep.hops - e.endpoint.hops);
-        JLOG(journal_.trace()) << beast::Leftw(18) << "Livecache drop " << ep.address
+        JLOG(journal_.trace()) << std::left << std::setw(18) << "Livecache drop " << ep.address
                               << " at hops +" << excess;
        return;
    }
@@ -453,12 +453,12 @@ Livecache<Allocator>::insert(Endpoint const& ep)
    if (ep.hops < e.endpoint.hops)
    {
        hops.reinsert(e, ep.hops);
-        JLOG(journal_.debug()) << beast::Leftw(18) << "Livecache update " << ep.address
+        JLOG(journal_.debug()) << std::left << std::setw(18) << "Livecache update " << ep.address
                               << " at hops " << ep.hops;
    }
    else
    {
-        JLOG(journal_.trace()) << beast::Leftw(18) << "Livecache refresh " << ep.address
+        JLOG(journal_.trace()) << std::left << std::setw(18) << "Livecache refresh " << ep.address
                               << " at hops " << ep.hops;
    }
 }
--- a/include/xrpl/peerfinder/detail/Logic.h
+++ b/include/xrpl/peerfinder/detail/Logic.h
@@ -1,17 +1,5 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/Slot.h>
-#include <xrpld/peerfinder/detail/Bootcache.h>
-#include <xrpld/peerfinder/detail/Counts.h>
-#include <xrpld/peerfinder/detail/Fixed.h>
-#include <xrpld/peerfinder/detail/Handouts.h>
-#include <xrpld/peerfinder/detail/Livecache.h>
-#include <xrpld/peerfinder/detail/SlotImp.h>
-#include <xrpld/peerfinder/detail/Source.h>
-#include <xrpld/peerfinder/detail/Store.h>
-#include <xrpld/peerfinder/detail/iosformat.h>
-
 #include <xrpl/basics/Log.h>
 #include <xrpl/basics/contract.h>
 #include <xrpl/basics/random.h>
@@ -22,18 +10,34 @@
 #include <xrpl/beast/utility/PropertyStream.h>
 #include <xrpl/beast/utility/WrappedSink.h>
 #include <xrpl/beast/utility/instrumentation.h>
+#include <xrpl/peerfinder/Config.h>
+#include <xrpl/peerfinder/Slot.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/Bootcache.h>
+#include <xrpl/peerfinder/detail/Counts.h>
+#include <xrpl/peerfinder/detail/Fixed.h>
+#include <xrpl/peerfinder/detail/Handouts.h>
+#include <xrpl/peerfinder/detail/Livecache.h>
+#include <xrpl/peerfinder/detail/SlotImp.h>
+#include <xrpl/peerfinder/detail/Source.h>
+#include <xrpl/peerfinder/detail/Store.h>
 #include <xrpl/protocol/PublicKey.h>

+#include <boost/asio/error.hpp>
+
 #include <algorithm>
 #include <cstddef>
 #include <cstdint>
 #include <functional>
+#include <iomanip>
+#include <ios>
 #include <map>
 #include <memory>
 #include <mutex>
 #include <optional>
 #include <set>
 #include <stdexcept>
+#include <string>
 #include <string_view>
 #include <tuple>
 #include <utility>
@@ -197,8 +201,8 @@ public:

            if (result.second)
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Logic add fixed '" << name << "' at " << remoteAddress;
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Logic add fixed '" << name
+                                      << "' at " << remoteAddress;
                return;
            }
        }
@@ -221,7 +225,7 @@ public:
        if (iter == slots.end())
        {
            // The slot disconnected before we finished the check
-            JLOG(journal.debug()) << beast::Leftw(18) << "Logic tested " << checkedAddress
+            JLOG(journal.debug()) << std::left << std::setw(18) << "Logic tested " << checkedAddress
                                  << " but the connection was closed";
            return;
        }
@@ -255,7 +259,7 @@ public:
        beast::IP::Endpoint const& localEndpoint,
        beast::IP::Endpoint const& remoteEndpoint)
    {
-        JLOG(journal.debug()) << beast::Leftw(18) << "Logic accept" << remoteEndpoint
+        JLOG(journal.debug()) << std::left << std::setw(18) << "Logic accept" << remoteEndpoint
                              << " on local " << localEndpoint;

        std::scoped_lock const _(lock);
@@ -266,7 +270,7 @@ public:
            auto const count = connectedAddresses.count(remoteEndpoint.address());
            if (count + 1 > config_.ipLimit)
            {
-                JLOG(journal.debug()) << beast::Leftw(18) << "Logic dropping inbound "
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Logic dropping inbound "
                                      << remoteEndpoint << " because of ip limits.";
                return {SlotImp::ptr(), Result::IpLimitExceeded};
            }
@@ -275,8 +279,8 @@ public:
        // Check for duplicate connection
        if (slots.contains(remoteEndpoint))
        {
-            JLOG(journal.debug()) << beast::Leftw(18) << "Logic dropping " << remoteEndpoint
-                                  << " as duplicate incoming";
+            JLOG(journal.debug()) << std::left << std::setw(18) << "Logic dropping "
+                                  << remoteEndpoint << " as duplicate incoming";
            return {SlotImp::ptr(), Result::DuplicatePeer};
        }

@@ -304,15 +308,15 @@ public:
    std::pair<SlotImp::ptr, Result>
    newOutboundSlot(beast::IP::Endpoint const& remoteEndpoint)
    {
-        JLOG(journal.debug()) << beast::Leftw(18) << "Logic connect " << remoteEndpoint;
+        JLOG(journal.debug()) << std::left << std::setw(18) << "Logic connect " << remoteEndpoint;

        std::scoped_lock const _(lock);

        // Check for duplicate connection
        if (slots.contains(remoteEndpoint))
        {
-            JLOG(journal.debug()) << beast::Leftw(18) << "Logic dropping " << remoteEndpoint
-                                  << " as duplicate connect";
+            JLOG(journal.debug()) << std::left << std::setw(18) << "Logic dropping "
+                                  << remoteEndpoint << " as duplicate connect";
            return {SlotImp::ptr(), Result::DuplicatePeer};
        }

@@ -506,15 +510,15 @@ public:

            if (!h.list().empty())
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Logic connect " << h.list().size() << " fixed";
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Logic connect "
+                                      << h.list().size() << " fixed";
                return h.list();
            }

            if (counts_.attempts() > 0)
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Logic waiting on " << counts_.attempts() << " attempts";
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Logic waiting on "
+                                      << counts_.attempts() << " attempts";
                return none;
            }
        }
@@ -535,14 +539,14 @@ public:
            if (!h.list().empty())
            {
                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Logic connect " << h.list().size() << " live "
+                    << std::left << std::setw(18) << "Logic connect " << h.list().size() << " live "
                    << ((h.list().size() > 1) ? "endpoints" : "endpoint");
                return h.list();
            }
            if (counts_.attempts() > 0)
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Logic waiting on " << counts_.attempts() << " attempts";
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Logic waiting on "
+                                      << counts_.attempts() << " attempts";
                return none;
            }
        }
@@ -568,8 +572,9 @@ public:

        if (!h.list().empty())
        {
-            JLOG(journal.debug()) << beast::Leftw(18) << "Logic connect " << h.list().size()
-                                  << " boot " << ((h.list().size() > 1) ? "addresses" : "address");
+            JLOG(journal.debug()) << std::left << std::setw(18) << "Logic connect "
+                                  << h.list().size() << " boot "
+                                  << ((h.list().size() > 1) ? "addresses" : "address");
            return h.list();
        }

@@ -689,8 +694,8 @@ public:
            // Enforce hop limit
            if (ep.hops > Tuning::kMaxHops)
            {
-                JLOG(journal.debug()) << beast::Leftw(18) << "Endpoints drop " << ep.address
-                                      << " for excess hops " << ep.hops;
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Endpoints drop "
+                                      << ep.address << " for excess hops " << ep.hops;
                iter = list.erase(iter);
                continue;
            }
@@ -706,18 +711,18 @@ public:
                }
                else
                {
-                    JLOG(journal.debug())
-                        << beast::Leftw(18) << "Endpoints drop " << ep.address << " for extra self";
+                    JLOG(journal.debug()) << std::left << std::setw(18) << "Endpoints drop "
+                                          << ep.address << " for extra self";
                    iter = list.erase(iter);
                    continue;
                }
            }

            // Discard invalid addresses
-            if (config_.verifyEndpoints && !isValidAddress(ep.address))
+            if (!isValidAddress(ep.address))
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Endpoints drop " << ep.address << " as invalid";
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Endpoints drop "
+                                      << ep.address << " as invalid";
                iter = list.erase(iter);
                continue;
            }
@@ -727,8 +732,8 @@ public:
                    return ep.address == other.address;
                }))
            {
-                JLOG(journal.debug())
-                    << beast::Leftw(18) << "Endpoints drop " << ep.address << " as duplicate";
+                JLOG(journal.debug()) << std::left << std::setw(18) << "Endpoints drop "
+                                      << ep.address << " as duplicate";
                iter = list.erase(iter);
                continue;
            }
@@ -1074,13 +1079,13 @@ public:
        if (!results.error)
        {
            int const count(addBootcacheAddresses(results.addresses));
-            JLOG(journal.info()) << beast::Leftw(18) << "Logic added " << count << " new "
+            JLOG(journal.info()) << std::left << std::setw(18) << "Logic added " << count << " new "
                                 << ((count == 1) ? "address" : "addresses") << " from "
                                 << source->name();
        }
        else
        {
-            JLOG(journal.error()) << beast::Leftw(18) << "Logic failed "
+            JLOG(journal.error()) << std::left << std::setw(18) << "Logic failed "
                                  << "'" << source->name() << "' fetch, "
                                  << results.error.message();
        }
@@ -1098,8 +1103,6 @@ public:
    {
        if (isUnspecified(address))
            return false;
-        if (isLoopback(address))
-            return false;
        if (!isPublic(address))
            return false;
        if (address.port() == 0)
@@ -1221,8 +1224,8 @@ Logic<Checker>::onRedirects(
        bootcache.insert(beast::IPAddressConversion::fromAsio(*first));
    if (n > 0)
    {
-        JLOG(journal.trace()) << beast::Leftw(18) << "Logic add " << n << " redirect IPs from "
-                              << remoteAddress;
+        JLOG(journal.trace()) << std::left << std::setw(18) << "Logic add " << n
+                              << " redirect IPs from " << remoteAddress;
    }
 }

--- a/include/xrpl/peerfinder/detail/SlotImp.h
+++ b/include/xrpl/peerfinder/detail/SlotImp.h
@@ -1,10 +1,9 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-#include <xrpld/peerfinder/Slot.h>
-
 #include <xrpl/beast/container/aged_unordered_map.h>
 #include <xrpl/beast/net/IPEndpoint.h>
+#include <xrpl/peerfinder/Slot.h>
+#include <xrpl/peerfinder/Types.h>
 #include <xrpl/protocol/PublicKey.h>

 #include <atomic>
@@ -172,7 +171,7 @@ private:
    std::optional<beast::IP::Endpoint> localEndpoint_;
    std::optional<PublicKey> publicKey_;

-    static constexpr std::int32_t kUnknownPort = -1;
+    static std::int32_t constexpr kUnknownPort = -1;
    std::atomic<std::int32_t> listeningPort_;

 public:
--- a/include/xrpl/peerfinder/detail/Source.h
+++ b/include/xrpl/peerfinder/detail/Source.h
@@ -1,8 +1,7 @@
 #pragma once

-#include <xrpld/peerfinder/PeerfinderManager.h>
-
 #include <xrpl/beast/utility/Journal.h>
+#include <xrpl/peerfinder/Types.h>

 #include <boost/system/error_code.hpp>

--- a/include/xrpl/peerfinder/detail/SourceStrings.h
+++ b/include/xrpl/peerfinder/detail/SourceStrings.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <xrpld/peerfinder/detail/Source.h>
+#include <xrpl/peerfinder/detail/Source.h>

 #include <memory>
 #include <string>
--- a/include/xrpl/peerfinder/detail/Store.h
+++ b/include/xrpl/peerfinder/detail/Store.h
--- a/include/xrpl/peerfinder/detail/Tuning.h
+++ b/include/xrpl/peerfinder/detail/Tuning.h
--- a/include/xrpl/peerfinder/make_Manager.h
+++ b/include/xrpl/peerfinder/make_Manager.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <xrpl/beast/insight/Collector.h>
+#include <xrpl/beast/utility/Journal.h>
+#include <xrpl/peerfinder/PeerfinderManager.h>
+#include <xrpl/peerfinder/Types.h>
+#include <xrpl/peerfinder/detail/Store.h>
+
+#include <boost/asio/io_context.hpp>
+
+#include <memory>
+
+namespace xrpl::PeerFinder {
+
+/**
+ * @brief Create a new Manager.
+ *
+ * @param ioContext The io_context used to schedule asynchronous work.
+ * @param clock The clock used for timekeeping.
+ * @param journal The journal used for logging.
+ * @param store The persistence backend for the bootstrap cache. The caller
+ *     retains ownership and must keep it alive (and opened) for the lifetime of
+ *     the returned Manager. This lets consumers supply their own Store
+ *     implementation (e.g. the SQLite-backed StoreSqdb in xrpld).
+ * @param collector The collector used to report metrics.
+ * @return The newly created Manager.
+ */
+std::unique_ptr<Manager>
+makeManager(
+    boost::asio::io_context& ioContext,
+    clock_type& clock,
+    beast::Journal journal,
+    Store& store,
+    beast::insight::Collector::ptr const& collector);
+
+}  // namespace xrpl::PeerFinder
--- a/include/xrpl/protocol/detail/features.macro
+++ b/include/xrpl/protocol/detail/features.macro
@@ -15,6 +15,7 @@
 // Add new amendments to the top of this list.
 // Keep it sorted in reverse chronological order.

+XRPL_FIX    (Cleanup3_4_0,                Supported::Yes, VoteBehavior::DefaultNo)
 XRPL_FEATURE(Sponsor,                     Supported::Yes, VoteBehavior::DefaultNo)
 XRPL_FEATURE(BatchV1_1,                   Supported::Yes, VoteBehavior::DefaultNo)
 XRPL_FEATURE(LendingProtocolV1_1,         Supported::No,  VoteBehavior::DefaultNo)
--- a/include/xrpl/tx/invariants/PermissionedDEXInvariant.h
+++ b/include/xrpl/tx/invariants/PermissionedDEXInvariant.h
@@ -17,7 +17,8 @@ class ValidPermissionedDEX
    bool regularOffers_ = false;     // post-fixCleanup3_2_0: excludes deleted offers
    bool badHybridsOld_ = false;     // pre-fixCleanup3_1_3: missing field/domain or size > 1
    bool badHybrids_ = false;        // post-fixCleanup3_1_3: also catches size == 0 (size != 1)
-    hash_set<uint256> domains_;
+    hash_set<uint256> domainsOld_;   // pre-fixCleanup3_4_0: also flags deleted domains
+    hash_set<uint256> domains_;      // post-fixCleanup3_4_0: excludes deleted domains

 public:
    void
--- a/nix/check-tools/README.md
+++ b/nix/check-tools/README.md
@@ -0,0 +1,49 @@
+# check-tools snapshots
+
+These files capture the output of [`bin/check-tools.sh`](../../bin/check-tools.sh)
+— the versions of the development tooling — in each Nix environment:
+
+| File                  | Environment                         |
+| --------------------- | ----------------------------------- |
+| `nix-nixos-amd64.txt` | `nix-nixos` CI image, `linux/amd64` |
+| `nix-nixos-arm64.txt` | `nix-nixos` CI image, `linux/arm64` |
+| `macos.txt`           | macOS, inside `nix develop`         |
+
+The [`check-tools`](../../.github/workflows/check-tools.yml) workflow regenerates
+each snapshot in its environment and fails if it differs from the committed file.
+So if you change the environment (bump the image tag in
+[`linux.json`](../../.github/scripts/strategy-matrix/linux.json), update
+`flake.lock`, change the tool list in `check-tools.sh`, …) you must regenerate
+and commit the affected snapshots.
+
+Each snapshot is `check-tools.sh` stdout with the git-clone connectivity check
+skipped (`CHECK_TOOLS_SKIP_CLONE=1`), so it contains only deterministic version
+data. On macOS the dev-shell greeting that `nix develop` prints first is dropped
+with `sed -n '/^Detected OS:/,$p'`.
+
+## Regenerating
+
+The two Linux snapshots come from the `nix-nixos` image (Docker or a compatible
+runtime such as Apple `container`). The image tag is pinned in `linux.json`:
+
+```bash
+img="ghcr.io/xrplf/xrpld/nix-nixos:$(jq -r .image_tag .github/scripts/strategy-matrix/linux.json)"
+
+for arch in amd64 arm64; do
+    container run --rm -i -e CHECK_TOOLS_SKIP_CLONE=1 -a "${arch}" --entrypoint bash "${img}" -s \
+        <bin/check-tools.sh >"nix/check-tools/nix-nixos-${arch}.txt"
+done
+```
+
+(With Docker, replace `container run … -a "${arch}"` with
+`docker run … --platform "linux/${arch}"`.)
+
+The macOS snapshot is generated locally. `CI=` is unset so `check-tools.sh`
+checks the full dev-shell tool set (it otherwise skips some tools when `CI` is
+set):
+
+```bash
+CI= nix develop -c bash -c 'CHECK_TOOLS_SKIP_CLONE=1 bash bin/check-tools.sh' |
+    sed -n '/^Detected OS:/,$p' \
+        >nix/check-tools/macos.txt
+```
--- a/nix/check-tools/macos.txt
+++ b/nix/check-tools/macos.txt
@@ -0,0 +1,47 @@
+Detected OS: macos (Darwin arm64)
+
+Core build tools:
+  [ ok ] cmake                cmake version 4.1.2
+  [ ok ] conan                Conan version 2.28.1
+  [ ok ] git                  git version 2.54.0
+  [ ok ] python3              Python 3.13.13
+
+Development tooling:
+  [ ok ] ccache               ccache version 4.13.6
+  [ ok ] clang                clang version 22.1.7
+  [ ok ] clang++              clang version 22.1.7
+  [ ok ] ClangBuildAnalyzer   ClangBuildAnalyzer 1.6.0
+  [ ok ] curl                 curl 8.20.0 (aarch64-apple-darwin25.3.0) libcurl/8.20.0 OpenSSL/3.6.2 zlib/1.3.2 libssh2/1.11.1 nghttp2/1.69.0 mit-krb5/1.22.1
+  [ ok ] file                 file-5.47
+  [ ok ] less                 less 692 (PCRE2 regular expressions)
+  [ ok ] make                 GNU Make 4.4.1
+  [ ok ] netstat              present
+  [ ok ] ninja                1.13.2
+  [ ok ] perl                 v5.42.0
+  [ ok ] pkg-config           0.29.2
+  [ ok ] vim                  VIM - Vi IMproved 9.2 (2026 Feb 14, compiled Jan 01 1980 00:00:00)
+  [ ok ] zip                  Zip 3.0
+  [ ok ] clang-format         clang-format version 22.1.7
+  [ ok ] dot                  dot - graphviz version 12.2.1 (0)
+  [ ok ] doxygen              1.16.1
+  [ ok ] gcovr                gcovr 8.4
+  [ ok ] gh                   gh version 2.94.0 (nixpkgs)
+  [ ok ] git-cliff            git-cliff 2.13.1
+  [ ok ] git-lfs              git-lfs/3.7.1 (3.7.1; darwin arm64; go 1.26.3)
+  [ ok ] gpg                  gpg (GnuPG) 2.4.9
+  [ ok ] pre-commit           pre-commit 4.5.1
+  [ ok ] run-clang-tidy       usage: run-clang-tidy [-h] [-allow-enabling-alpha-checkers]
+
+Rust toolchain:
+  [ ok ] cargo                cargo 1.95.0 (f2d3ce0bd 2026-03-21)
+  [ ok ] cargo-audit          cargo-audit-audit 0.22.1
+  [ ok ] cargo-llvm-cov       cargo-llvm-cov 0.8.5
+  [ ok ] cargo-nextest        cargo-nextest 0.9.137
+  [ ok ] clippy               clippy 0.1.95 (59807616e1 2026-04-14)
+  [ ok ] rust-analyzer        rust-analyzer 1.95.0 (59807616 2026-04-14)
+  [ ok ] rustc                rustc 1.95.0 (59807616e 2026-04-14)
+  [ ok ] rustfmt              rustfmt 1.9.0-stable (59807616e1 2026-04-14)
+
+Skipping git-over-HTTPS check (CHECK_TOOLS_SKIP_CLONE is set).
+
+All 36 checked tools are present and runnable.
--- a/nix/check-tools/nix-ubuntu-amd64.txt
+++ b/nix/check-tools/nix-ubuntu-amd64.txt
@@ -0,0 +1,55 @@
+Detected OS: linux (Linux x86_64)
+
+Core build tools:
+  [ ok ] cmake                cmake version 4.1.2
+  [ ok ] conan                Conan version 2.28.1
+  [ ok ] git                  git version 2.54.0
+  [ ok ] python3              Python 3.13.13
+
+Development tooling:
+  [ ok ] ccache               ccache version 4.13.6
+  [ ok ] clang                clang version 22.1.7
+  [ ok ] clang++              clang version 22.1.7
+  [ ok ] ClangBuildAnalyzer   ClangBuildAnalyzer 1.6.0
+  [ ok ] curl                 curl 8.20.0 (x86_64-pc-linux-gnu) libcurl/8.20.0 OpenSSL/3.6.2 zlib/1.3.2 libssh2/1.11.1 nghttp2/1.69.0 mit-krb5/1.22.1
+  [ ok ] file                 file-5.47
+  [ ok ] less                 less 692 (PCRE2 regular expressions)
+  [ ok ] make                 GNU Make 4.4.1
+  [ ok ] netstat              net-tools 2.10
+  [ ok ] ninja                1.13.2
+  [ ok ] perl                 v5.42.0
+  [ ok ] pkg-config           0.29.2
+  [ ok ] vim                  VIM - Vi IMproved 9.2 (2026 Feb 14, compiled Jan 01 1980 00:00:00)
+  [ ok ] zip                  Zip 3.0
+  [ ok ] clang-format         clang-format version 22.1.7
+  [ ok ] dot                  dot - graphviz version 12.2.1 (0)
+  [ ok ] doxygen              1.16.1
+  [ ok ] gcovr                gcovr 8.4
+  [ ok ] gh                   gh version 2.94.0 (nixpkgs)
+  [ ok ] git-cliff            git-cliff 2.13.1
+  [ ok ] git-lfs              git-lfs/3.7.1 (3.7.1; linux amd64; go 1.26.3)
+  [ ok ] gpg                  gpg (GnuPG) 2.4.9
+  [ ok ] pre-commit           pre-commit 4.5.1
+  [ ok ] run-clang-tidy       usage: run-clang-tidy [-h] [-allow-enabling-alpha-checkers]
+
+Rust toolchain:
+  [ ok ] cargo                cargo 1.95.0 (f2d3ce0bd 2026-03-21)
+  [ ok ] cargo-audit          cargo-audit-audit 0.22.1
+  [ ok ] cargo-llvm-cov       cargo-llvm-cov 0.8.5
+  [ ok ] cargo-nextest        cargo-nextest 0.9.137
+  [ ok ] clippy               clippy 0.1.95 (59807616e1 2026-04-14)
+  [ ok ] rust-analyzer        rust-analyzer 1.95.0 (5980761 2026-04-14)
+  [ ok ] rustc                rustc 1.95.0 (59807616e 2026-04-14)
+  [ ok ] rustfmt              rustfmt 1.9.0-stable (59807616e1 2026-04-14)
+
+GCC toolchain:
+  [ ok ] gcc                  gcc (GCC) 15.2.0
+  [ ok ] g++                  g++ (GCC) 15.2.0
+  [ ok ] gcov                 gcov (GCC) 15.2.0
+
+Mold:
+  [ ok ] mold                 mold 2.41.0 (compatible with GNU ld)
+
+Skipping git-over-HTTPS check (CHECK_TOOLS_SKIP_CLONE is set).
+
+All 40 checked tools are present and runnable.
--- a/nix/check-tools/nix-ubuntu-arm64.txt
+++ b/nix/check-tools/nix-ubuntu-arm64.txt
@@ -0,0 +1,55 @@
+Detected OS: linux (Linux aarch64)
+
+Core build tools:
+  [ ok ] cmake                cmake version 4.1.2
+  [ ok ] conan                Conan version 2.28.1
+  [ ok ] git                  git version 2.54.0
+  [ ok ] python3              Python 3.13.13
+
+Development tooling:
+  [ ok ] ccache               ccache version 4.13.6
+  [ ok ] clang                clang version 22.1.7
+  [ ok ] clang++              clang version 22.1.7
+  [ ok ] ClangBuildAnalyzer   ClangBuildAnalyzer 1.6.0
+  [ ok ] curl                 curl 8.20.0 (aarch64-unknown-linux-gnu) libcurl/8.20.0 OpenSSL/3.6.2 zlib/1.3.2 libssh2/1.11.1 nghttp2/1.69.0 mit-krb5/1.22.1
+  [ ok ] file                 file-5.47
+  [ ok ] less                 less 692 (PCRE2 regular expressions)
+  [ ok ] make                 GNU Make 4.4.1
+  [ ok ] netstat              net-tools 2.10
+  [ ok ] ninja                1.13.2
+  [ ok ] perl                 v5.42.0
+  [ ok ] pkg-config           0.29.2
+  [ ok ] vim                  VIM - Vi IMproved 9.2 (2026 Feb 14, compiled Jan 01 1980 00:00:00)
+  [ ok ] zip                  Zip 3.0
+  [ ok ] clang-format         clang-format version 22.1.7
+  [ ok ] dot                  dot - graphviz version 12.2.1 (0)
+  [ ok ] doxygen              1.16.1
+  [ ok ] gcovr                gcovr 8.4
+  [ ok ] gh                   gh version 2.94.0 (nixpkgs)
+  [ ok ] git-cliff            git-cliff 2.13.1
+  [ ok ] git-lfs              git-lfs/3.7.1 (3.7.1; linux arm64; go 1.26.3)
+  [ ok ] gpg                  gpg (GnuPG) 2.4.9
+  [ ok ] pre-commit           pre-commit 4.5.1
+  [ ok ] run-clang-tidy       usage: run-clang-tidy [-h] [-allow-enabling-alpha-checkers]
+
+Rust toolchain:
+  [ ok ] cargo                cargo 1.95.0 (f2d3ce0bd 2026-03-21)
+  [ ok ] cargo-audit          cargo-audit-audit 0.22.1
+  [ ok ] cargo-llvm-cov       cargo-llvm-cov 0.8.5
+  [ ok ] cargo-nextest        cargo-nextest 0.9.137
+  [ ok ] clippy               clippy 0.1.95 (59807616e1 2026-04-14)
+  [ ok ] rust-analyzer        rust-analyzer 1.95.0 (5980761 2026-04-14)
+  [ ok ] rustc                rustc 1.95.0 (59807616e 2026-04-14)
+  [ ok ] rustfmt              rustfmt 1.9.0-stable (59807616e1 2026-04-14)
+
+GCC toolchain:
+  [ ok ] gcc                  gcc (GCC) 15.2.0
+  [ ok ] g++                  g++ (GCC) 15.2.0
+  [ ok ] gcov                 gcov (GCC) 15.2.0
+
+Mold:
+  [ ok ] mold                 mold 2.41.0 (compatible with GNU ld)
+
+Skipping git-over-HTTPS check (CHECK_TOOLS_SKIP_CLONE is set).
+
+All 40 checked tools are present and runnable.
--- a/nix/ci-env.nix
+++ b/nix/ci-env.nix
@@ -6,106 +6,18 @@
 let
  inherit (import ./packages.nix { inherit pkgs; })
    commonPackages
-    gccPackage
-    llvmPackages
+    gccVersion
    llvmVersion
+    mkVersionedToolLinks
    ;

-  # Underlying compiler toolchains to wrap (versions pinned in packages.nix).
-  customGccPackage = gccPackage;
-  customLlvmPackages = llvmPackages;
-
-  # binutils wrapped to emit binaries that reference the custom glibc
-  # (dynamic linker path, library search path, RPATH).
-  customBinutils = pkgs.wrapBintoolsWith {
-    bintools = pkgs.binutils-unwrapped;
-    libc = customGlibc;
-  };
-
-  # Rebuild gcc (specifically libstdc++ / libgcc_s) against the custom
-  # glibc. The override swaps gcc.cc's bootstrap stdenv for one that uses
-  # the existing gcc binary but links against the custom glibc, so the
-  # resulting compiler ships runtime libraries that only reference symbols
-  # available in that glibc.
-  customGccCc = customGccPackage.cc.override {
-    stdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv (
-      pkgs.wrapCCWith {
-        cc = customGccPackage.cc;
-        libc = customGlibc;
-        bintools = customBinutils;
-      }
-    );
-  };
-
-  # cc-wrapper around the rebuilt compiler, pointing at the custom glibc
-  # headers and libraries. This is what we actually expose to users.
-  customGcc = pkgs.wrapCCWith {
-    cc = customGccCc;
-    libc = customGlibc;
-    bintools = customBinutils;
-  };
-
-  # gcov ships in gcc's `cc` output, but the cc-wrapper doesn't expose it.
-  # Surface the gcov from our rebuilt gcc (linked against the custom glibc, so
-  # it runs under the loader installed in the image) and matching the exact
-  # compiler version, so gcovr can produce coverage reports in the CI env.
-  customGcov = pkgs.runCommand "gcov-custom-for-ci-env" { } ''
-    mkdir -p "$out/bin"
-    ln -s "${customGccCc}/bin/gcov" "$out/bin/gcov"
-  '';
-
-  # stdenv built around the rebuilt gcc / custom glibc. Used to rebuild
-  # compiler-rt below so its sanitizer runtimes see the custom glibc
-  # headers.
-  customStdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv customGcc;
-
-  # Rebuild compiler-rt against the custom glibc so the sanitizer runtimes
-  # don't use glibc symbols (or sysconf constants like _SC_SIGSTKSZ) that
-  # only exist in newer glibc versions. scudo is dropped because its CMake
-  # includes CheckAtomic with -nostdinc++ in CMAKE_REQUIRED_FLAGS, which
-  # makes std::atomic unfindable in our stdenv; we don't use scudo (only
-  # asan/ubsan/tsan etc.).
-  customCompilerRt =
-    (customLlvmPackages.compiler-rt.override {
-      stdenv = customStdenv;
-    }).overrideAttrs
-      (old: {
-        postPatch = (old.postPatch or "") + ''
-          substituteInPlace lib/CMakeLists.txt \
-            --replace-quiet 'add_subdirectory(scudo/standalone)' \
-                            '# scudo/standalone disabled in xrpld ci-env'
-        '';
-      });
-
-  # cc-wrapper around clang, pointing at the custom glibc headers and
-  # libraries. Reuses the rebuilt gcc for libstdc++ / libgcc_s so that
-  # C++ binaries produced by clang also only reference symbols available
-  # in the custom glibc. compiler-rt is wired into a resource-root so
-  # sanitizer runtimes (libclang_rt.*.a) are found at link time; this
-  # mirrors what nixpkgs does internally when building llvmPackages.clang.
-  customClang = pkgs.wrapCCWith {
-    cc = customLlvmPackages.clang-unwrapped;
-    libc = customGlibc;
-    bintools = customBinutils;
-    gccForLibs = customGccCc;
-    extraPackages = [ customCompilerRt ];
-    extraBuildCommands = ''
-      rsrc="$out/resource-root"
-      mkdir "$rsrc"
-      ln -s "${customLlvmPackages.clang-unwrapped.lib}/lib/clang/${toString llvmVersion}/include" "$rsrc/include"
-      ln -s "${customCompilerRt.out}/lib" "$rsrc/lib"
-      ln -s "${customCompilerRt.out}/share" "$rsrc/share" || true
-      echo "-resource-dir=$rsrc" >> $out/nix-support/cc-cflags
-      # compiler-rt ships the sanitizer/profile/xray interface headers (e.g.
-      # <sanitizer/lsan_interface.h>) in its `dev` output. In a normal Nix
-      # build these reach the include path because compiler-rt is propagated
-      # via depsTargetTargetPropagated and stdenv's setup hooks add its
-      # dev/include. The CI image runs clang outside a Nix stdenv (binaries
-      # on PATH, no setup hooks), so that never happens; add the headers
-      # explicitly. gcc ships its own copy, which is why this is clang-only.
-      echo "-isystem ${customCompilerRt.dev}/include" >> $out/nix-support/cc-cflags
-    '';
-  };
+  # Custom-glibc toolchain, shared with the Linux dev shell (see compilers.nix).
+  inherit (import ./compilers.nix { inherit pkgs customGlibc; })
+    customGcc
+    customClang
+    customBinutils
+    customGcov
+    ;

  # Strip the generic cc/c++/cpp symlinks from the clang wrapper so it can
  # coexist with the gcc wrapper in buildEnv. gcc remains the default
@@ -127,6 +39,25 @@ in
      customGcov
      customClangForCiEnv
      customBinutils
+      (mkVersionedToolLinks {
+        name = "gcc";
+        package = customGcc;
+        version = gccVersion;
+        tools = [
+          "gcc"
+          "g++"
+          "cpp"
+        ];
+      })
+      (mkVersionedToolLinks {
+        name = "clang";
+        package = customClang;
+        version = llvmVersion;
+        tools = [
+          "clang"
+          "clang++"
+        ];
+      })
      # CA certificate bundle so HTTPS clients (git, curl, conan) can verify
      # TLS connections without ca-certificates being installed in the system.
      pkgs.cacert
--- a/nix/compilers.nix
+++ b/nix/compilers.nix
@@ -0,0 +1,117 @@
+# Custom-glibc compiler toolchain shared by the CI environment (ci-env.nix) and
+# the Linux dev shell (devshell.nix): gcc / clang / binutils rebuilt to target
+# the pinned custom glibc. Linux only — the pinned glibc snapshot does not build
+# on darwin, so callers must not evaluate this on macOS.
+{
+  pkgs,
+  customGlibc,
+}:
+let
+  inherit (import ./packages.nix { inherit pkgs; })
+    gccPackage
+    llvmPackages
+    llvmVersion
+    mkGcov
+    ;
+
+  # binutils wrapped to emit binaries that reference the custom glibc
+  # (dynamic linker path, library search path, RPATH).
+  customBinutils = pkgs.wrapBintoolsWith {
+    bintools = pkgs.binutils-unwrapped;
+    libc = customGlibc;
+  };
+
+  # Rebuild gcc (specifically libstdc++ / libgcc_s) against the custom
+  # glibc. The override swaps gcc.cc's bootstrap stdenv for one that uses
+  # the existing gcc binary but links against the custom glibc, so the
+  # resulting compiler ships runtime libraries that only reference symbols
+  # available in that glibc.
+  customGccCc = gccPackage.cc.override {
+    stdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv (
+      pkgs.wrapCCWith {
+        cc = gccPackage.cc;
+        libc = customGlibc;
+        bintools = customBinutils;
+      }
+    );
+  };
+
+  # cc-wrapper around the rebuilt compiler, pointing at the custom glibc
+  # headers and libraries. This is what we actually expose to users.
+  customGcc = pkgs.wrapCCWith {
+    cc = customGccCc;
+    libc = customGlibc;
+    bintools = customBinutils;
+  };
+
+  # gcov matching the rebuilt gcc (linked against the custom glibc), so gcovr
+  # can produce coverage reports both in CI and in the dev shell.
+  customGcov = mkGcov {
+    name = "custom";
+    cc = customGccCc;
+  };
+
+  # stdenv built around the rebuilt gcc / custom glibc. Exported as the dev
+  # shell's gcc stdenv, and used below to rebuild compiler-rt so its sanitizer
+  # runtimes see the custom glibc headers.
+  customStdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv customGcc;
+
+  # Rebuild compiler-rt against the custom glibc so the sanitizer runtimes
+  # don't use glibc symbols (or sysconf constants like _SC_SIGSTKSZ) that
+  # only exist in newer glibc versions. scudo is dropped because its CMake
+  # includes CheckAtomic with -nostdinc++ in CMAKE_REQUIRED_FLAGS, which
+  # makes std::atomic unfindable in our stdenv; we don't use scudo (only
+  # asan/ubsan/tsan etc.).
+  customCompilerRt =
+    (llvmPackages.compiler-rt.override {
+      stdenv = customStdenv;
+    }).overrideAttrs
+      (old: {
+        postPatch = (old.postPatch or "") + ''
+          substituteInPlace lib/CMakeLists.txt \
+            --replace-quiet 'add_subdirectory(scudo/standalone)' \
+                            '# scudo/standalone disabled in xrpld ci-env'
+        '';
+      });
+
+  # cc-wrapper around clang, pointing at the custom glibc headers and
+  # libraries. Reuses the rebuilt gcc for libstdc++ / libgcc_s so that
+  # C++ binaries produced by clang also only reference symbols available
+  # in the custom glibc. compiler-rt is wired into a resource-root so
+  # sanitizer runtimes (libclang_rt.*.a) are found at link time; this
+  # mirrors what nixpkgs does internally when building llvmPackages.clang.
+  customClang = pkgs.wrapCCWith {
+    cc = llvmPackages.clang-unwrapped;
+    libc = customGlibc;
+    bintools = customBinutils;
+    gccForLibs = customGccCc;
+    extraPackages = [ customCompilerRt ];
+    extraBuildCommands = ''
+      rsrc="$out/resource-root"
+      mkdir "$rsrc"
+      ln -s "${llvmPackages.clang-unwrapped.lib}/lib/clang/${toString llvmVersion}/include" "$rsrc/include"
+      ln -s "${customCompilerRt.out}/lib" "$rsrc/lib"
+      ln -s "${customCompilerRt.out}/share" "$rsrc/share" || true
+      echo "-resource-dir=$rsrc" >> $out/nix-support/cc-cflags
+      # compiler-rt ships the sanitizer/profile/xray interface headers (e.g.
+      # <sanitizer/lsan_interface.h>) in its `dev` output. In a normal Nix
+      # build these reach the include path because compiler-rt is propagated
+      # via depsTargetTargetPropagated and stdenv's setup hooks add its
+      # dev/include. The CI image runs clang outside a Nix stdenv (binaries
+      # on PATH, no setup hooks), so that never happens; add the headers
+      # explicitly. gcc ships its own copy, which is why this is clang-only.
+      echo "-isystem ${customCompilerRt.dev}/include" >> $out/nix-support/cc-cflags
+    '';
+  };
+in
+{
+  inherit
+    customGcc
+    customClang
+    customBinutils
+    customStdenv
+    customGcov
+    ;
+
+  customClangStdenv = pkgs.stdenvAdapters.overrideCC pkgs.stdenv customClang;
+}
--- a/nix/devshell.nix
+++ b/nix/devshell.nix
@@ -1,23 +1,69 @@
-{ pkgs, ... }:
+{ pkgs, customGlibc, ... }:
 let
  inherit (import ./packages.nix { inherit pkgs; })
    commonPackages
+    gccPackage
    gccVersion
+    llvmVersion
    llvmPackages
+    mkVersionedToolLinks
+    mkGcov
    ;

-  # Plain nixpkgs stdenvs — no custom glibc, unlike ci-env.nix.
-  gccStdenv = pkgs."gcc${toString gccVersion}Stdenv";
-  clangStdenv = llvmPackages.stdenv;
+  # Plain nixpkgs stdenvs — no custom glibc.
+  plainGccStdenv = pkgs."gcc${toString gccVersion}Stdenv";
+  plainClangStdenv = llvmPackages.stdenv;
+
+  # Custom-glibc stdenvs, matching the CI environment (see compilers.nix). The
+  # pinned glibc snapshot only builds on Linux, so on darwin these fall back to
+  # the plain stdenvs; the `if isLinux` guard keeps `customGlibc` from being
+  # forced (and erroring) on macOS.
+  customCompilers = import ./compilers.nix { inherit pkgs customGlibc; };
+  customGccStdenv = if pkgs.stdenv.isLinux then customCompilers.customStdenv else plainGccStdenv;
+  customClangStdenv =
+    if pkgs.stdenv.isLinux then customCompilers.customClangStdenv else plainClangStdenv;
+
+  # gcov matching each gcc shell, so `-Dcoverage=ON` builds work in the shell.
+  plainGcov = mkGcov {
+    name = "plain";
+    cc = gccPackage.cc;
+  };
+  customGccGcov = if pkgs.stdenv.isLinux then customCompilers.customGcov else plainGcov;
+
+  # Shown when entering a *-plain shell. These exist only on Linux (see below),
+  # where the stock toolchain diverges from CI.
+  plainWarningHook = ''
+    echo "⚠️  WARNING: this is the stock nixpkgs toolchain and does not match CI's glibc. Prefer 'nix develop .#gcc' / '.#clang' unless you need to skip the custom-glibc build."
+  '';
+
+  # Tools to expose under version-suffixed names (see mkVersionedToolLinks).
+  gccVersionedTools = [
+    "gcc"
+    "g++"
+    "cpp"
+  ];
+  clangVersionedTools = [
+    "clang"
+    "clang++"
+  ];

  # compilerName is the command used to print the version, or null for none.
  makeShell =
    {
+      shellName,
      stdenv,
      compilerName,
+      version ? null,
+      versionedTools ? [ ],
+      extraPackages ? [ ],
+      warningHook ? "",
+      # Opt out of PatchNixBinary.cmake retargeting binaries to the system
+      # loader. The plain toolchain links a newer glibc, so it must not be
+      # patched; the custom toolchain patches by default.
+      noPatchNixBinary ? false,
    }:
    let
-      compilerVersion =
+      compilerVersionHook =
        if compilerName == null then
          ''echo "No compiler specified - using system compiler"''
        else
@@ -25,33 +71,81 @@ let
            echo "Compiler: "
            ${compilerName} --version
          '';
+      versionedLinks = pkgs.lib.optional (version != null) (mkVersionedToolLinks {
+        name = compilerName;
+        package = stdenv.cc;
+        inherit version;
+        tools = versionedTools;
+      });
    in
-    (pkgs.mkShell.override { inherit stdenv; }) {
-      packages = commonPackages;
-      shellHook = ''
-        echo "Welcome to xrpld development shell";
-        ${compilerVersion}
-      '';
-    };
+    (pkgs.mkShell.override { inherit stdenv; }) (
+      {
+        packages = commonPackages ++ versionedLinks ++ extraPackages;
+        # Marks a managed dev shell, so the build (XrplSanity.cmake) can tell an
+        # intentional Nix toolchain from one leaked into a bare shell.
+        XRPL_DEVSHELL = shellName;
+        shellHook = ''
+          echo "Welcome to xrpld development shell";
+          ${compilerVersionHook}
+          ${warningHook}
+        '';
+      }
+      // pkgs.lib.optionalAttrs noPatchNixBinary { XRPLD_NO_PATCH_NIX_BINARY = "1"; }
+    );
 in
 rec {
  # macOS: Nix Clang. Linux: Nix GCC.
  default = if pkgs.stdenv.isDarwin then clang else gcc;

+  # gcc/clang use the custom-glibc toolchain, matching CI. On darwin there is no
+  # custom glibc, so they fall back to the plain nixpkgs toolchain.
  gcc = makeShell {
-    stdenv = gccStdenv;
+    shellName = "gcc";
+    stdenv = customGccStdenv;
    compilerName = "gcc";
+    version = gccVersion;
+    versionedTools = gccVersionedTools;
+    extraPackages = [ customGccGcov ];
  };

  clang = makeShell {
-    stdenv = clangStdenv;
+    shellName = "clang";
+    stdenv = customClangStdenv;
    compilerName = "clang";
+    version = llvmVersion;
+    versionedTools = clangVersionedTools;
  };

  # Nix provides no compiler; use the one from your system (e.g. Apple Clang).
  no-compiler = makeShell {
+    shellName = "no-compiler";
    stdenv = pkgs.stdenvNoCC;
    compilerName = null;
  };
  apple-clang = no-compiler;
 }
+# The *-plain shells (stock nixpkgs toolchain) exist only on Linux: on darwin
+# gcc/clang are already plain, so these would be redundant and are omitted, which
+# makes `nix develop .#gcc-plain` fail there rather than silently aliasing gcc.
+// pkgs.lib.optionalAttrs pkgs.stdenv.isLinux {
+  gcc-plain = makeShell {
+    shellName = "gcc-plain";
+    stdenv = plainGccStdenv;
+    compilerName = "gcc";
+    version = gccVersion;
+    versionedTools = gccVersionedTools;
+    extraPackages = [ plainGcov ];
+    warningHook = plainWarningHook;
+    noPatchNixBinary = true;
+  };
+
+  clang-plain = makeShell {
+    shellName = "clang-plain";
+    stdenv = plainClangStdenv;
+    compilerName = "clang";
+    version = llvmVersion;
+    versionedTools = clangVersionedTools;
+    warningHook = plainWarningHook;
+    noPatchNixBinary = true;
+  };
+}
--- a/nix/docker/Dockerfile
+++ b/nix/docker/Dockerfile
@@ -8,10 +8,12 @@ RUN mkdir -p ~/.config/nix && \

 # Copy our source and setup our working dir.
 COPY nix/ci-env.nix /tmp/build/nix/ci-env.nix
+COPY nix/compilers.nix /tmp/build/nix/compilers.nix
 COPY nix/packages.nix /tmp/build/nix/packages.nix
 COPY nix/utils.nix /tmp/build/nix/utils.nix
 COPY flake.nix /tmp/build/
 COPY flake.lock /tmp/build/
+COPY rust-toolchain.toml /tmp/build/
 WORKDIR /tmp/build

 FROM builder-source AS builder
@@ -56,7 +58,7 @@ ENV GIT_SSL_CAINFO="/nix/ci-env/etc/ssl/certs/ca-bundle.crt"
 # Externally-built dynamically-linked ELF binaries hard-code the loader path
 # (e.g. /lib64/ld-linux-x86-64.so.2) in their PT_INTERP header. Install it
 # from the Nix store when the base image doesn't already provide one.
-COPY nix/docker/loader-path.sh /tmp/loader-path.sh
+COPY bin/default-loader-path.sh /tmp/loader-path.sh

 RUN <<EOF
 target="$(/tmp/loader-path.sh)"
--- a/nix/docker/README.md
+++ b/nix/docker/README.md
@@ -47,7 +47,9 @@ work without `ca-certificates` being installed in the base image.
     [`test_files/cpp/sources/`](./test_files/cpp/sources) with both `g++` and
     `clang++`, and sanitizers, and
   - compiles the Rust test programs in
-     [`test_files/rust/sources/`](./test_files/rust/sources) with `rustc`.
+     [`test_files/rust/sources/`](./test_files/rust/sources) with `rustc`, and
+     builds the [`test_files/rust/proc_macro/`](./test_files/rust/proc_macro)
+     workspace with `cargo` to exercise proc-macro dylib loading.
 3. **`tester`** — Start again from a clean `BASE_IMAGE` (no Nix toolchain),
   install only the sanitizer runtime libraries
   ([`install-sanitizer-libs.sh`](./install-sanitizer-libs.sh)), and run the
@@ -73,23 +75,27 @@ toolchain being present at runtime. Two pieces make that work:

 - **An expected dynamic linker in the image.**
  Binaries built in Nix environments reference a dynamic linker from Nix store paths, which won't be present in the base image. However,
-  [`loader-path.sh`](./loader-path.sh) reports the expected loader path for the
-  current architecture, so we can patch the binaries to use the correct loader.
+  [`bin/default-loader-path.sh`](../../bin/default-loader-path.sh) reports the
+  expected loader path for the current architecture, so we can patch the binaries
+  to use the correct loader.

-The build then verifies all of this end to end: the C++ test programs in
-`test_files/cpp/sources/` (a regular binary plus ASan/TSan/UBSan variants) and
-the Rust test programs in `test_files/rust/sources/` (a hello binary plus panic
-and overflow-check variants) are compiled in `final`, their `PT_INTERP` is
-patched to the target loader, and they are run in the clean `tester` stage to
-confirm each emits the expected diagnostic on a stock base image.
+The build then verifies all of this end to end, and the C++ and Rust programs
+go through the same pipeline: each is compiled in `final`, has its `PT_INTERP`
+patched to the target loader, and is then run in the clean `tester` stage to
+confirm it emits the expected diagnostic on a stock base image. The C++ programs
+are in `test_files/cpp/sources/` (a regular binary plus ASan/TSan/UBSan
+variants); the Rust programs are in `test_files/rust/sources/` (a hello binary
+plus panic and overflow-check variants), plus the `test_files/rust/proc_macro/`
+workspace — a crate whose compilation additionally loads a proc-macro dylib, and
+whose resulting binary is patched and run like the others.

 ## Files

-| File                                                                    | Purpose                                                                       |
-| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`./Dockerfile`](./Dockerfile)                                          | Multi-stage build described above.                                            |
-| [`./loader-path.sh`](./loader-path.sh)                                  | Print the dynamic-linker (`PT_INTERP`) path for the current architecture.     |
-| [`./test_files/cpp/`](./test_files/cpp)                                 | C++ sanitizer smoke test: sources + compile/run scripts.                      |
-| [`./test_files/rust/`](./test_files/rust)                               | Rust rustc smoke test: sources + compile/run scripts.                         |
-| [`/bin/check-tools.sh`](../../bin/check-tools.sh)                       | Verify every expected tools are present and runnable.                         |
-| [`/bin/install-sanitizer-libs.sh`](../../bin/install-sanitizer-libs.sh) | Install `libasan`/`libtsan`/`libubsan` runtimes on the supported base images. |
+| File                                                                    | Purpose                                                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [`./Dockerfile`](./Dockerfile)                                          | Multi-stage build described above.                                                   |
+| [`./test_files/cpp/`](./test_files/cpp)                                 | C++ sanitizer smoke test: sources + compile/run scripts.                             |
+| [`./test_files/rust/`](./test_files/rust)                               | Rust smoke test: rustc sources + a cargo proc-macro workspace + compile/run scripts. |
+| [`/bin/check-tools.sh`](../../bin/check-tools.sh)                       | Verify every expected tools are present and runnable.                                |
+| [`/bin/default-loader-path.sh`](../../bin/default-loader-path.sh)       | Print the dynamic-linker (`PT_INTERP`) path for the current architecture.            |
+| [`/bin/install-sanitizer-libs.sh`](../../bin/install-sanitizer-libs.sh) | Install `libasan`/`libtsan`/`libubsan` runtimes on the supported base images.        |
--- a/nix/docker/test_files/rust/compile-sources.sh
+++ b/nix/docker/test_files/rust/compile-sources.sh
@@ -40,6 +40,29 @@ compile hello
 compile panic
 compile overflow "-C overflow-checks=on"

+function compile_proc_macro() {
+    local proj="${src_dir}/../proc_macro"
+
+    echo "=== Building proc-macro workspace (cargo) ==="
+    cargo build --manifest-path "${proj}/Cargo.toml" --offline
+
+    local built="${proj}/target/debug/test_macro"
+    if [ ! -f "${built}" ]; then
+        echo "ERROR: built test_macro binary not found at ${built}" >&2
+        exit 1
+    fi
+
+    local binary="${dst_dir}/proc_macro"
+    cp "${built}" "${binary}"
+
+    echo "=== Patching ${binary} to use ${loader} as PT_INTERP ==="
+    patchelf --set-interpreter "${loader}" --remove-rpath "${binary}"
+
+    rm -rf "${proj}/target"
+}
+
+compile_proc_macro
+
 echo "=== All binaries compiled ==="

 ls -la "${dst_dir}"
--- a/nix/docker/test_files/rust/proc_macro/Cargo.lock
+++ b/nix/docker/test_files/rust/proc_macro/Cargo.lock
@@ -0,0 +1,14 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "echo_macro"
+version = "0.0.0"
+
+[[package]]
+name = "test_macro"
+version = "0.0.0"
+dependencies = [
+ "echo_macro",
+]
--- a/nix/docker/test_files/rust/proc_macro/Cargo.toml
+++ b/nix/docker/test_files/rust/proc_macro/Cargo.toml
@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["echo_macro", "test_macro"]
--- a/nix/docker/test_files/rust/proc_macro/echo_macro/Cargo.toml
+++ b/nix/docker/test_files/rust/proc_macro/echo_macro/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "echo_macro"
+version = "0.0.0"
+edition = "2024"
+publish = false
+
+[lib]
+proc-macro = true
--- a/nix/docker/test_files/rust/proc_macro/echo_macro/src/lib.rs
+++ b/nix/docker/test_files/rust/proc_macro/echo_macro/src/lib.rs
@@ -0,0 +1,6 @@
+use proc_macro::TokenStream;
+
+#[proc_macro]
+pub fn define_echo(item: TokenStream) -> TokenStream {
+    format!("fn echo() -> u32 {{ {item} }}").parse().unwrap()
+}
--- a/nix/docker/test_files/rust/proc_macro/test_macro/Cargo.toml
+++ b/nix/docker/test_files/rust/proc_macro/test_macro/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "test_macro"
+version = "0.0.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+echo_macro = { path = "../echo_macro" }
--- a/nix/docker/test_files/rust/proc_macro/test_macro/src/main.rs
+++ b/nix/docker/test_files/rust/proc_macro/test_macro/src/main.rs
@@ -0,0 +1,9 @@
+use echo_macro::define_echo;
+
+define_echo!(42);
+
+fn main() {
+    let a = echo();
+    println!("proc-macro answer = {a}");
+    assert_eq!(a, 42, "proc-macro expansion produced the wrong value");
+}
--- a/nix/docker/test_files/rust/run-binaries.sh
+++ b/nix/docker/test_files/rust/run-binaries.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # Run pre-compiled Rust binaries and confirm each emits its expected diagnostic.
 # Binaries must already exist in <bins_dir> as <name> for name in
-# {hello,panic,overflow}.
+# {hello,panic,overflow,proc_macro}.

 set -eo pipefail

@@ -54,12 +54,13 @@ declare -A expect=(
    [hello]="Hello from main thread"
    [panic]="explicit panic from test"
    [overflow]="attempt to add with overflow"
+    [proc_macro]="proc-macro answer = 42"
 )

-for name in hello panic overflow; do
+for name in hello panic overflow proc_macro; do
    binary="${bins_dir}/${name}"

-    if [ "${name}" = "hello" ]; then
+    if [ "${name}" = "hello" ] || [ "${name}" = "proc_macro" ]; then
        expected_rc=0
    else
        expected_rc=nonzero
--- a/nix/packages.nix
+++ b/nix/packages.nix
@@ -15,6 +15,82 @@ let
  runClangTidy = pkgs.writeShellScriptBin "run-clang-tidy" ''
    exec ${pkgs.python3}/bin/python3 ${llvmPackages.clang-unwrapped}/bin/run-clang-tidy "$@"
  '';
+
+  # rust-overlay's toolchain propagates the *default* stdenv.cc onto the PATH (so
+  # cargo has a linker). That default may be different from the clang we pin here,
+  # so it shadows our clang and the build can silently use a different compiler
+  # version. Drop that cc from every propagation channel instead of pinning a
+  # replacement: the toolchain then carries no compiler and cargo just uses the
+  # active shell's stdenv cc. Must cover all channels — rust-overlay uses both
+  # propagatedBuildInputs and depsHostHostPropagated.
+  rustToolchainBase = pkgs.rust-bin.fromRustupToolchainFile ../rust-toolchain.toml;
+  rustToolchain =
+    let
+      defaultCc = pkgs.stdenv.cc; # default compiler from nixpkgs stdenv
+      withoutDefaultCc = builtins.filter (dep: (dep.outPath or "") != defaultCc.outPath);
+    in
+    rustToolchainBase.overrideAttrs (old: {
+      propagatedBuildInputs = withoutDefaultCc (old.propagatedBuildInputs or [ ]);
+      depsHostHostPropagated = withoutDefaultCc (old.depsHostHostPropagated or [ ]);
+    });
+
+  # Nix wraps its toolchain so that binaries are exposed only under unsuffixed
+  # names (gcc, g++, clang-tidy, ...). Several tools probe for a
+  # version-suffixed name first and fall back to a system binary on the PATH
+  # when Nix doesn't provide it:
+  #   - Conan's Boost recipe looks up `g++-<major>` before plain `g++`.
+  #   - bin/pre-commit/clang_tidy_check.py looks up `run-clang-tidy-<v>` and
+  #     `clang-apply-replacements-<v>` before the unsuffixed names.
+  # On a host that also has the matching system binary (e.g. Ubuntu's
+  # `/usr/bin/g++-15` or `clang-tidy-22`) the probe escapes Nix and mixes a
+  # system tool into the Nix environment. Generate version-suffixed symlinks
+  # next to a package's tools so those probes resolve to the Nix ones.
+  #
+  # Compiler links must point at whichever compiler is active in a given
+  # environment (the plain stdenv compiler in the dev shell, the custom-glibc
+  # wrappers in ci-env.nix), so those callers pass their own `package`; the
+  # clang tooling is environment-independent and is linked in commonPackages.
+  mkVersionedToolLinks =
+    {
+      name,
+      package,
+      version,
+      tools,
+    }:
+    pkgs.linkFarm "${name}-${toString version}-versioned-links" (
+      map (tool: {
+        name = "bin/${tool}-${toString version}";
+        path = "${package}/bin/${tool}";
+      }) tools
+    );
+
+  # The cc-wrapper doesn't re-export gcov, but coverage tooling (gcovr) needs a
+  # gcov that exactly matches the compiler. Surface it from a gcc `cc` output.
+  mkGcov =
+    { name, cc }:
+    pkgs.linkFarm "gcov-${name}" [
+      {
+        name = "bin/gcov";
+        path = "${cc}/bin/gcov";
+      }
+    ];
+
+  clangToolLinks = mkVersionedToolLinks {
+    name = "clang-tools";
+    package = clangTools;
+    version = llvmVersion;
+    tools = [
+      "clang-tidy"
+      "clang-apply-replacements"
+      "clang-format"
+    ];
+  };
+  runClangTidyLink = mkVersionedToolLinks {
+    name = "run-clang-tidy";
+    package = runClangTidy;
+    version = llvmVersion;
+    tools = [ "run-clang-tidy" ];
+  };
 in
 {
  inherit
@@ -22,9 +98,13 @@ in
    llvmVersion
    gccPackage
    llvmPackages
+    mkVersionedToolLinks
+    mkGcov
    ;

  commonPackages = with pkgs; [
+    clangToolLinks
+    runClangTidyLink
    ccache
    clangbuildanalyzer
    clangTools
@@ -63,14 +143,10 @@ in
    vim
    zip
    # Rust packages
-    cargo
    cargo-audit
    cargo-llvm-cov
    cargo-nextest
-    clippy
    corrosion
-    rust-analyzer
-    rustc
-    rustfmt
+    rustToolchain
  ];
 }
--- a/nix/utils.nix
+++ b/nix/utils.nix
@@ -1,4 +1,8 @@
-{ nixpkgs, nixpkgs-custom-glibc }:
+{
+  nixpkgs,
+  nixpkgs-custom-glibc,
+  rust-overlay,
+}:
 function:
 nixpkgs.lib.genAttrs
  [
@@ -10,7 +14,12 @@ nixpkgs.lib.genAttrs
  (
    system:
    function {
-      pkgs = import nixpkgs { inherit system; };
+      # rust-overlay adds `pkgs.rust-bin`, from which we build the pinned Rust
+      # toolchain (see packages.nix). Consumed by both the CI image and dev shell.
+      pkgs = import nixpkgs {
+        inherit system;
+        overlays = [ (import rust-overlay) ];
+      };
      # glibc 2.31 — matches the system libc on Ubuntu 20.04 LTS. Sourced
      # from the nixpkgs snapshot pinned via the `nixpkgs-custom-glibc`
      # flake input, so the build uses the compiler from that snapshot
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Pratik Mankawde	91004209e9	Merge branch 'pratik/std-coro/migrate-entry-points' into pratik/std-coro/migrate-test-code Forward-merge the entry-point migration (carrying the latest develop) into the test-code migration. Conflict resolutions in Coroutine_test.cpp and JobQueue_test.cpp: keep the postCoroTask / CoroTaskRunner form from this branch, with develop's renames (JtClient, Gate::waitFor, kN) and develop's initialization of the unprotected flag.	2026-07-24 20:57:01 +01:00
Pratik Mankawde	4c18dd867c	Merge branch 'pratik/std-coro/add-coroutine-primitives' into pratik/std-coro/migrate-entry-points Forward-merge the updated coroutine primitives (which themselves carry the latest develop) into the entry-point migration. Conflict resolutions: - .cspell.config.yaml: keep develop's dotfile name, merge word lists. - Context.h: drop the coro member; infoSub gets a default initializer. - Application.cpp, ServerHandler.cpp, TestHelpers.cpp, Path_test.cpp, PathMPT_test.cpp: adopt develop's designated-initializer JsonContext and renamed identifiers (JtClient, kApiVersionIfUnspecified, kMaxSrcCur, Gate). - GRPCServer: process(coro) becomes processRequest(), posted with postCoroTask. - RipplePathFind.cpp: follow develop's move to handlers/orderbook/ and PathRequestManager; the completion state shared with the path-finding continuation is now heap-allocated so it outlives an early return. - AMMTest.cpp: develop moved find_paths_request into TestHelpers.cpp, so the local copy is dropped and the migration applied there instead.	2026-07-24 20:52:28 +01:00
Pratik Mankawde	fb6ece56f2	Merge remote-tracking branch 'origin/develop' into pratik/std-coro/add-coroutine-primitives Resolves the develop rename of cspell.config.yaml and the JobQueue.h conflicts, and aligns the new coroutine primitives with develop naming (CreateT, mutex_/mutexRun_, JtClient, forceMultiThread, beast::unit_test::Suite). Also addresses two review findings: - postCoroTask now holds a jobCounter_ reservation for the whole function. JobQueue::stop() joins jobCounter_ before asserting nSuspend_ == 0, so the reservation closes the window between the ++nSuspend_ and the balancing post()/expectEarlyExit(), and doubles as the shutdown check. - YieldPostAwaiter::await_suspend returns a coroutine_handle<> (symmetric transfer) instead of resuming inline. This keeps a yield loop against a stopping JobQueue from growing the stack without bound and avoids touching a frame that resume() may have already destroyed.	2026-07-24 20:39:41 +01:00
Sergey Kuznetsov	fecfc0cf3f	chore: Fix clang version in devshell (#7860 ) Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com>	2026-07-24 17:30:20 +00:00
Ayaz Salikhov	ea0a6904f0	chore: Verify tooling version for Nix-managed environments (#7862 )	2026-07-24 15:52:45 +00:00
Ayaz Salikhov	29d74142ae	build: Patсh binary in local Linux nix environment (#7859 ) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-07-24 14:59:24 +00:00
Kassaking7	9afa1cf4d1	fix: Update PermissionedDEX invariant domain tracking for valid offer replacement (#7387 ) Co-authored-by: Bart <bthomee@users.noreply.github.com>	2026-07-23 21:40:21 +00:00
Ed Hennis	7908aec2ec	feat: Check default fields are not default when serializing (#6267 ) Co-authored-by: Vito <5780819+Tapanito@users.noreply.github.com> Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com> Co-authored-by: Bart <bthomee@users.noreply.github.com>	2026-07-23 21:39:11 +00:00
Marek Foss	4c0180b3db	test: Migrate csf and xrpld-consensus Beast non-JTx tests to GTest (#7046 ) Co-authored-by: Alex Kremer <akremer@ripple.com>	2026-07-23 21:38:21 +00:00
Marek Foss	4acccfeda8	test: Modularize Peerfinder component and migrate Peerfinder tests from Beast to GTest and GMock (#7054 ) Co-authored-by: Alex Kremer <akremer@ripple.com>	2026-07-23 21:00:06 +00:00
Ed Hennis	b89d75a2d5	test: Add an RAII class to manage the env.parseFailureExpected flag (#7669 )	2026-07-23 20:57:00 +00:00
Ayaz Salikhov	40cdf49d15	build: Use custom libc in a devshell by default (#7852 )	2026-07-23 19:05:24 +00:00
Mayukha Vadari	38c54c3f36	feat: Add fixCleanup3_4_0 amendment (no functionality yet) (#7854 )	2026-07-23 18:50:59 +00:00
Sergey Kuznetsov	95e1ffea6e	ci: Add llvm-tools-preview to rust toolchain (#7853 )	2026-07-23 16:49:44 +00:00
Sergey Kuznetsov	74cfb3586a	ci: Update CI image (#7850 )	2026-07-23 11:21:49 +00:00
Ayaz Salikhov	0072ced94c	ci: Update XRPLF/actions (#7849 )	2026-07-23 10:22:18 +00:00
Mayukha Vadari	12ed506565	chore: Clean up grammar in PR template (#7846 )	2026-07-22 18:50:10 +00:00
Ayaz Salikhov	3122de86bf	build: Create versioned compiler/tooling symlinks in nix environments (#7844 )	2026-07-22 17:04:02 +00:00
Sergey Kuznetsov	7edf39e622	ci: Use rust-overlay to bring Rust into nix (#7837 )	2026-07-22 14:00:17 +00:00
dependabot[bot]	ba01b05f33	ci: [DEPENDABOT] bump actions/setup-python from 6.3.0 to 7.0.0 (#7830 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-07-21 16:04:45 +00:00
Sergey Kuznetsov	c414e1877d	ci: Update pre-commit image (#7838 )	2026-07-21 15:37:47 +00:00
Sergey Kuznetsov	f56b79f00d	ci: Add cargo to pre-commit image (#7835 )	2026-07-21 13:39:37 +00:00
Ayaz Salikhov	4918f3bb20	chore: Add doxygen in pre-commit image (#7836 )	2026-07-21 13:38:26 +00:00
Mayukha Vadari	ee0a3dfad7	ci: Improve test debuggability (#7619 ) Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com>	2026-07-21 13:14:40 +00:00
Bart	042c9660cd	chore: Add CODEOWNERS for CI-related changes (#7832 ) Co-authored-by: Bart <11445373+bthomee@users.noreply.github.com>	2026-07-20 21:06:24 +00:00
Ayaz Salikhov	60b49f3fe0	ci: Use in-house image for pre-commit (#7610 )	2026-07-20 19:11:09 +00:00
Ayaz Salikhov	4c869ee16c	ci: Build separate pre-commit docker image (#7831 )	2026-07-20 17:40:38 +00:00
Ayaz Salikhov	b2f45813e0	chore: Workaround boost compiler resolution inside Nix environment (#7826 )	2026-07-20 14:04:08 +00:00
Pratik Mankawde	42cced50fb	feat: Migrate coroutine tests from Boost.Coroutine to C++20 coroutines Migrate Coroutine_test and JobQueue_test from Boost.Coroutine to C++20 std::coroutine using CoroTask/CoroTaskRunner: - Coroutine_test: Replace Coro-based coroutine tests with CoroTask equivalents using co_await runner->yieldAndPost(). - JobQueue_test: Replace Coro suspend/resume patterns with CoroTask equivalents, use pointer-by-value captures in coroutine lambdas to avoid dangling reference issues.	2026-03-25 15:48:17 +00:00
Pratik Mankawde	0e815aa1ac	feat: Migrate production entry points from Boost.Coroutine to C++20 coroutines Migrate all production coroutine entry points from Boost.Coroutine to C++20 std::coroutine using the CoroTask/CoroTaskRunner primitives: - RipplePathFind: Replace Coro suspend/resume with co_await pattern, add cv timeout for graceful shutdown. - ServerHandler: Replace Coro-based processRequest with CoroTask, simplify coroutine lifecycle management. - GRPCServer: Replace Coro with CoroTask for streaming RPC handlers. - Remove Coro usage from Context.h aggregate initialization. - Add exception handling in coroutine bodies to prevent unhandled exceptions from escaping the coroutine frame.	2026-03-25 15:48:10 +00:00
Pratik Mankawde	21149a81e3	feat: Add C++20 coroutine primitives: CoroTask, CoroTaskRunner, JobQueueAwaiter Add C++20 std::coroutine based task primitives for the JobQueue: - CoroTask<T>: A coroutine return type with RAII ownership semantics and symmetric transfer for efficient resumption. - CoroTaskRunner: Manages coroutine lifecycle on the JobQueue with suspend/resume tracking, LocalValue preservation, and graceful shutdown support. - JobQueueAwaiter: External awaiter combining yield+post atomically. - yieldAndPost(): Inline awaiter workaround for GCC-12 codegen bug where external awaiters at multiple co_await points corrupt the coroutine state machine resume index. - CoroTask_test: Comprehensive test suite covering task lifecycle, suspend/resume, shutdown, and value-returning coroutines. - BoostToStdCoroutineSwitchPlan.md: Migration plan documentation.	2026-03-25 15:46:44 +00:00
Pratik Mankawde	b78202a99a	docs: Add Boost to C++20 coroutine migration plan Comprehensive migration plan documenting the switch from Boost.Coroutine2 to C++20 standard coroutines in rippled, including research analysis, implementation phases, risk assessment, and testing strategy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-25 15:44:19 +00:00