refactor: Screen wasm modules with a wasmi ModuleInspector instead of a pre-scan

fix: Check unexported oversized memories and tables during admission screening
fix: Change check_sig gas cost back to 35000 (#8597 )
2026-10-22 19:47:17 +00:00 · 2026-10-16 11:01:24 -04:00 · 2026-10-15 21:26:55 -04:00 · 2026-10-15 12:09:55 -04:00 · 2026-10-15 16:49:25 +01:00 · 2026-10-14 18:34:33 -04:00
2416 changed files with 277765 additions and 102477 deletions
@@ -1,171 +1,117 @@
 ---
 Checks: "-*,
-  bugprone-argument-comment,
-  bugprone-assert-side-effect,
-  bugprone-bad-signal-to-kill-thread,
-  bugprone-bool-pointer-implicit-conversion,
-  bugprone-casting-through-void,
-  bugprone-capturing-this-in-member-variable,
-  bugprone-chained-comparison,
-  bugprone-compare-pointer-to-member-virtual-function,
-  bugprone-copy-constructor-init,
-  bugprone-crtp-constructor-accessibility,
-  bugprone-dangling-handle,
-  bugprone-dynamic-static-initializers,
-  bugprone-empty-catch,
-  bugprone-fold-init-type,
-  bugprone-forward-declaration-namespace,
-  bugprone-inaccurate-erase,
-  bugprone-inc-dec-in-conditions,
-  bugprone-incorrect-enable-if,
-  bugprone-incorrect-roundings,
-  bugprone-infinite-loop,
-  bugprone-integer-division,
-  bugprone-lambda-function-name,
-  bugprone-macro-parentheses,
-  bugprone-macro-repeated-side-effects,
-  bugprone-misplaced-operator-in-strlen-in-alloc,
-  bugprone-misplaced-pointer-arithmetic-in-alloc,
-  bugprone-misplaced-widening-cast,
-  bugprone-misleading-setter-of-reference,
-  bugprone-move-forwarding-reference,
-  bugprone-multi-level-implicit-pointer-conversion,
-  bugprone-multiple-new-in-one-expression,
-  bugprone-multiple-statement-macro,
-  bugprone-no-escape,
-  bugprone-non-zero-enum-to-bool-conversion,
-  bugprone-optional-value-conversion,
-  bugprone-parent-virtual-call,
-  bugprone-pointer-arithmetic-on-polymorphic-object,
-  bugprone-posix-return,
-  bugprone-redundant-branch-condition,
-  bugprone-reserved-identifier,
-  bugprone-return-const-ref-from-parameter,
-  bugprone-shared-ptr-array-mismatch,
-  bugprone-signal-handler,
-  bugprone-signed-char-misuse,
-  bugprone-sizeof-container,
-  bugprone-sizeof-expression,
-  bugprone-spuriously-wake-up-functions,
-  bugprone-standalone-empty,
-  bugprone-string-constructor,
-  bugprone-string-integer-assignment,
-  bugprone-string-literal-with-embedded-nul,
-  bugprone-stringview-nullptr,
-  bugprone-suspicious-enum-usage,
-  bugprone-suspicious-include,
-  bugprone-suspicious-memory-comparison,
-  bugprone-suspicious-memset-usage,
-  bugprone-suspicious-missing-comma,
-  bugprone-suspicious-realloc-usage,
-  bugprone-suspicious-semicolon,
-  bugprone-suspicious-string-compare,
-  bugprone-suspicious-stringview-data-usage,
-  bugprone-swapped-arguments,
-  bugprone-switch-missing-default-case,
-  bugprone-terminating-continue,
-  bugprone-throw-keyword-missing,
-  bugprone-too-small-loop-variable,
-  bugprone-unchecked-optional-access,
-  bugprone-undefined-memory-manipulation,
-  bugprone-undelegated-constructor,
-  bugprone-unhandled-exception-at-new,
-  bugprone-unhandled-self-assignment,
-  bugprone-unique-ptr-array-mismatch,
-  bugprone-unsafe-functions,
-  bugprone-use-after-move,
-  bugprone-unused-raii,
-  bugprone-unused-return-value,
-  bugprone-unused-local-non-trivial-variable,
-  bugprone-virtual-near-miss,
-  cppcoreguidelines-init-variables,
-  cppcoreguidelines-misleading-capture-default-by-value,
-  cppcoreguidelines-no-suspend-with-lock,
-  cppcoreguidelines-pro-type-member-init,
-  cppcoreguidelines-pro-type-static-cast-downcast,
-  cppcoreguidelines-rvalue-reference-param-not-moved,
-  cppcoreguidelines-use-default-member-init,
-  cppcoreguidelines-use-enum-class,
-  cppcoreguidelines-virtual-class-destructor,
-  hicpp-ignored-remove-result,
-  misc-const-correctness,
-  misc-definitions-in-headers,
-  misc-header-include-cycle,
-  misc-include-cleaner,
-  misc-misplaced-const,
-  misc-redundant-expression,
-  misc-static-assert,
-  misc-throw-by-value-catch-by-reference,
-  misc-unused-alias-decls,
-  misc-unused-using-decls,
-  modernize-concat-nested-namespaces,
-  modernize-make-shared,
-  modernize-make-unique,
-  modernize-pass-by-value,
-  modernize-type-traits,
-  modernize-use-designated-initializers,
-  modernize-use-emplace,
-  modernize-use-equals-default,
-  modernize-use-equals-delete,
-  modernize-use-nodiscard,
-  modernize-use-override,
-  modernize-use-ranges,
-  modernize-use-scoped-lock,
-  modernize-use-starts-ends-with,
-  modernize-use-std-numbers,
-  modernize-use-using,
-  modernize-deprecated-headers,
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-exception-escape,
+  -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-narrowing-conversions,
+  -bugprone-signed-bitwise,
+  -bugprone-std-exception-baseclass,
+  -bugprone-throwing-static-initialization,
+  -bugprone-unhandled-code-paths,
+
+  cppcoreguidelines-*,
+  -cppcoreguidelines-avoid-c-arrays,
+  -cppcoreguidelines-avoid-const-or-ref-data-members,
+  -cppcoreguidelines-avoid-do-while,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-avoid-non-const-global-variables,
+  -cppcoreguidelines-c-copy-assignment-signature,
+  -cppcoreguidelines-explicit-constructor,
+  -cppcoreguidelines-interfaces-global-init,
+  -cppcoreguidelines-macro-usage,
+  -cppcoreguidelines-missing-std-forward,
+  -cppcoreguidelines-narrowing-conversions,
+  -cppcoreguidelines-noexcept-move-operations,
+  -cppcoreguidelines-non-private-member-variables-in-classes,
+  -cppcoreguidelines-owning-memory,
+  -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
+  -cppcoreguidelines-pro-bounds-constant-array-index,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-pro-type-reinterpret-cast,
+  -cppcoreguidelines-pro-type-union-access,
+  -cppcoreguidelines-special-member-functions,
+
  llvm-namespace-comment,
-  performance-faster-string-find,
-  performance-for-range-copy,
-  performance-implicit-conversion-in-loop,
-  performance-inefficient-vector-operation,
-  performance-move-const-arg,
-  performance-move-constructor-init,
-  performance-no-automatic-move,
-  performance-trivially-destructible,
-  readability-ambiguous-smartptr-reset-call,
-  readability-avoid-nested-conditional-operator,
-  readability-avoid-return-with-void-value,
-  readability-braces-around-statements,
-  readability-const-return-type,
-  readability-container-contains,
-  readability-container-size-empty,
-  readability-convert-member-functions-to-static,
-  readability-duplicate-include,
-  readability-else-after-return,
-  readability-enum-initial-value,
-  readability-identifier-naming,
-  readability-implicit-bool-conversion,
-  readability-make-member-function-const,
-  readability-math-missing-parentheses,
-  readability-misleading-indentation,
-  readability-non-const-parameter,
-  readability-redundant-casting,
-  readability-redundant-declaration,
-  readability-redundant-inline-specifier,
-  readability-redundant-member-init,
-  readability-redundant-string-init,
-  readability-reference-to-constructed-temporary,
-  readability-simplify-boolean-expr,
-  readability-static-definition-in-anonymous-namespace,
-  readability-suspicious-call-argument,
-  readability-use-std-min-max
+
+  misc-*,
+  -misc-explicit-constructor,
+  -misc-multiple-inheritance,
+  -misc-no-recursion,
+  -misc-non-private-member-variables-in-classes,
+  -misc-override-with-different-visibility,
+  -misc-unused-parameters,
+  -misc-use-anonymous-namespace,
+  -misc-use-internal-linkage,
+
+  modernize-*,
+  -modernize-avoid-c-arrays,
+  -modernize-avoid-c-style-cast,
+  -modernize-return-braced-init-list,
+  -modernize-use-integer-sign-comparison,
+  -modernize-use-string-view,
+  -modernize-use-structured-binding,
+  -modernize-use-trailing-return-type,
+
+  performance-*,
+  -performance-avoid-endl,
+  -performance-enum-size,
+  -performance-noexcept-move-constructor,
+  -performance-unnecessary-copy-initialization,
+  -performance-unnecessary-value-param,
+  -performance-use-std-move,
+
+  readability-*,
+  -readability-avoid-const-params-in-decls,
+  -readability-container-data-pointer,
+  -readability-function-cognitive-complexity,
+  -readability-identifier-length,
+  -readability-inconsistent-declaration-parameter-name,
+  -readability-isolate-declaration,
+  -readability-magic-numbers,
+  -readability-named-parameter,
+  -readability-qualified-auto,
+  -readability-redundant-access-specifiers,
+  -readability-redundant-nested-if,
+  -readability-redundant-qualified-alias,
+  -readability-static-accessed-through-instance,
+  -readability-trivial-switch,
+  -readability-uppercase-literal-suffix
  "
 # ---
-# readability-inconsistent-declaration-parameter-name, # in this codebase this check will break a lot of arg names
-# readability-static-accessed-through-instance,        # this check is probably unnecessary. it makes the code less readable
+# bugprone-narrowing-conversions,                      # This will break a lot of code but we should enable it in the future because it can eliminate a lot of bugs
+# misc-override-with-different-visibility,             # Will be addressed in a future PR, but for now it generates too many warnings
+# readability-inconsistent-declaration-parameter-name, # In this codebase this check will break a lot of arg names
+# readability-static-accessed-through-instance,        # this check is probably unnecessary. It makes the code less readable
 # ---
+
+FormatStyle: file
+
 CheckOptions:
+  bugprone-unsafe-functions.ReportMoreUnsafeFunctions: true
+  bugprone-unused-return-value.CheckedReturnTypes: ::std::error_code;::std::error_condition;::std::errc
+
+  misc-include-cleaner.IgnoreHeaders: ".*/(detail|impl)/.*;.*fwd\\.h(pp)?;time.h;stdlib.h;sqlite3.h;netinet/in\\.h;sys/resource\\.h;sys/sysinfo\\.h;linux/sysinfo\\.h;__chrono/.*;bits/.*;_abort\\.h;boost/.*;openssl/obj_mac\\.h"
+
  readability-braces-around-statements.ShortStatementLines: 2
  readability-identifier-naming.MacroDefinitionCase: UPPER_CASE
+  readability-identifier-naming.NamespaceCase: lower_case
+  readability-identifier-naming.InlineNamespaceCase: lower_case
  readability-identifier-naming.ClassCase: CamelCase
  readability-identifier-naming.StructCase: CamelCase
  readability-identifier-naming.UnionCase: CamelCase
+  readability-identifier-naming.TypeAliasCase: CamelCase
+  readability-identifier-naming.TypedefCase: CamelCase
+  # Member type names mandated by std/Boost concepts. Subtrees that need more
+  # than these carry their own .clang-tidy (include/xrpl/{beast,basics,protocol,
+  # peerfinder}, src/test/beast); one-off cases use an inline NOLINT.
+  readability-identifier-naming.TypeAliasIgnoredRegexp: "^(const_iterator|const_reference|difference_type|duration|iterator|iterator_category|key_type|mapped_type|period|pointer|reference|rep|result_type|size_type|time_point|value_type)$"
+  readability-identifier-naming.TypedefIgnoredRegexp: "^(const_iterator|const_reference|difference_type|duration|iterator|iterator_category|key_type|mapped_type|period|pointer|reference|rep|result_type|size_type|time_point|value_type)$"
  readability-identifier-naming.EnumCase: CamelCase
  readability-identifier-naming.EnumConstantCase: CamelCase
  readability-identifier-naming.ScopedEnumConstantCase: CamelCase
-  readability-identifier-naming.GlobalConstantCase: UPPER_CASE
+  readability-identifier-naming.GlobalConstantCase: CamelCase
  readability-identifier-naming.GlobalConstantPrefix: "k"
  readability-identifier-naming.GlobalVariableCase: CamelCase
  readability-identifier-naming.GlobalVariablePrefix: "g"
@@ -173,27 +119,26 @@ CheckOptions:
  readability-identifier-naming.ConstexprMethodCase: camelBack
  readability-identifier-naming.ClassMethodCase: camelBack
  readability-identifier-naming.ClassMemberCase: camelBack
-  readability-identifier-naming.ClassConstantCase: UPPER_CASE
+  readability-identifier-naming.ClassConstantCase: CamelCase
  readability-identifier-naming.ClassConstantPrefix: "k"
-  readability-identifier-naming.StaticConstantCase: UPPER_CASE
+  readability-identifier-naming.StaticConstantCase: CamelCase
  readability-identifier-naming.StaticConstantPrefix: "k"
-  readability-identifier-naming.StaticVariableCase: UPPER_CASE
-  readability-identifier-naming.StaticVariablePrefix: "k"
-  readability-identifier-naming.ConstexprVariableCase: UPPER_CASE
-  readability-identifier-naming.ConstexprVariablePrefix: "k"
+  readability-identifier-naming.StaticVariableCase: camelBack
+  readability-identifier-naming.ConstexprVariableCase: camelBack
  readability-identifier-naming.LocalConstantCase: camelBack
  readability-identifier-naming.LocalVariableCase: camelBack
  readability-identifier-naming.TemplateParameterCase: CamelCase
  readability-identifier-naming.ParameterCase: camelBack
  readability-identifier-naming.FunctionCase: camelBack
  readability-identifier-naming.MemberCase: camelBack
+  readability-identifier-naming.PrivateMemberCase: camelBack
  readability-identifier-naming.PrivateMemberSuffix: _
+  readability-identifier-naming.ProtectedMemberCase: camelBack
  readability-identifier-naming.ProtectedMemberSuffix: _
+  readability-identifier-naming.PublicMemberCase: camelBack
  readability-identifier-naming.PublicMemberSuffix: ""
  readability-identifier-naming.GlobalFunctionIgnoredRegexp: "^(to_string|hash_append|tuple_hash)$"
-  bugprone-unsafe-functions.ReportMoreUnsafeFunctions: true
-  bugprone-unused-return-value.CheckedReturnTypes: ::std::error_code;::std::error_condition;::std::errc
-  misc-include-cleaner.IgnoreHeaders: ".*/(detail|impl)/.*;.*fwd\\.h(pp)?;time.h;stdlib.h;sqlite3.h;netinet/in\\.h;sys/resource\\.h;sys/sysinfo\\.h;linux/sysinfo\\.h;__chrono/.*;bits/.*;_abort\\.h;boost/uuid/uuid_hash.hpp;boost/beast/core/flat_buffer\\.hpp;boost/beast/http/field\\.hpp;boost/beast/http/dynamic_body\\.hpp;boost/beast/http/message\\.hpp;boost/beast/http/read\\.hpp;boost/beast/http/write\\.hpp;openssl/obj_mac\\.h"
-HeaderFilterRegex: '^.*/(test|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
-ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$'
+
+HeaderFilterRegex: '^.*/(tests?|xrpl|xrpld)/.*\.(h|hpp|ipp)$'
+ExcludeHeaderFilterRegex: '^.*/protocol_autogen/.*\.(h|hpp)$|^.*\.pb\.h$'
 WarningsAsErrors: "*"
@@ -1,10 +1,32 @@
 codecov:
  require_ci_to_pass: true
+  # The C++ and Rust uploads land minutes apart; without this gate Codecov
+  # publishes a near-zero total from whichever one arrives first.
+  notify:
+    after_n_builds: 2
+    wait_for_ci: true

 comment:
  behavior: default
  layout: reach,diff,flags,tree,reach
-  show_carryforward_flags: false
+  show_carryforward_flags: true
+  after_n_builds: 2
+
+# C++ and Rust coverage upload from independent workflows under the `cpp` and
+# `rust` flags; carryforward keeps one language's total when only the other reran.
+flag_management:
+  default_rules:
+    carryforward: true
+  individual_flags:
+    - name: cpp
+      carryforward: true
+      paths:
+        - include/
+        - src/
+    - name: rust
+      carryforward: true
+      paths:
+        - crates/

 coverage:
  range: "70..85"
@@ -7,6 +7,7 @@ ignorePaths:
  - cmake/**
  - LICENSE.md
  - .clang-tidy
+  - nix/check-tools/*.txt # generated, and full of Nix store hashes
 language: en
 allowCompoundWords: true # TODO (#6334)
 ignoreRandomStrings: true
@@ -30,15 +31,15 @@ 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
      - /`[^`]*`/g # backtick strings
 suggestWords:
-  - xprl->xrpl
-  - xprld->xrpld # cspell: disable-line not sure what this problem is....
-  - unsynched->unsynced # cspell: disable-line not sure what this problem is....
+  - unsynched->unsynced
  - synched->synced
  - synch->sync
 words:
@@ -50,6 +51,7 @@ words:
  - AMMXRP
  - amt
  - amts
+  - archs
  - asnode
  - asynchrony
  - attestation
@@ -59,11 +61,17 @@ words:
  - autobridging
  - bimap
  - bindir
+  - blindings
  - bookdir
  - Bougalis
+  - bthomee
  - Britto
  - Btrfs
+  - Buildx
  - canonicality
+  - cdylib
+  - canonicalised
+  - cctools
  - changespq
  - checkme
  - choco
@@ -71,6 +79,8 @@ words:
  - citardauq
  - clawback
  - clawbacks
+  - clippy
+  - cmaketoolchain
  - coeffs
  - coldwallet
  - compr
@@ -81,6 +91,7 @@ words:
  - coro
  - coros
  - cowid
+  - cpack
  - cryptocondition
  - cryptoconditional
  - cryptoconditions
@@ -91,18 +102,27 @@ words:
  - daria
  - dcmake
  - dearmor
+  - decryptor
+  - dedented
  - deleteme
  - demultiplexer
  - deserializaton
+  - desugars
  - desync
  - desynced
  - determ
+  - disablerepo
  - distro
  - doxyfile
+  - dsymutil
  - dxrpl
+  - elgamal
  - enabled
+  - enablerepo
  - endmacro
+  - envrc
  - exceptioned
+  - EXPECT_STREQ
  - Falco
  - fcontext
  - finalizers
@@ -110,23 +130,31 @@ words:
  - fmtdur
  - fsanitize
  - funclets
+  - Gamal
  - gcov
  - gcovr
  - ghead
+  - gmock
  - Gnutella
+  - godexsoft
  - gpgcheck
  - gpgkey
+  - Hinnant
  - hotwallet
  - hwaddress
  - hwrap
  - ifndef
+  - impls
  - inequation
+  - initialiser
+  - Injectivity
  - insuf
  - insuff
  - invasively
  - iou
  - ious
  - isrdc
+  - isystem
  - itype
  - jemalloc
  - jlog
@@ -148,16 +176,20 @@ words:
  - llection
  - LOCALGOOD
  - logwstream
+  - Lombrozo
+  - lresolv
  - lseq
  - lsmf
  - ltype
+  - mathbunnyru
+  - maxima
  - mcmodel
  - MEMORYSTATUSEX
  - MPTAMM
  - MPTDEX
  - Merkle
-  - Metafuncton
  - misprediction
+  - missingok
  - mptbalance
  - MPTDEX
  - mptflags
@@ -170,6 +202,7 @@ words:
  - mptokenissuance
  - mptokens
  - mpts
+  - mpt
  - mtgox
  - multisig
  - multisign
@@ -183,22 +216,30 @@ words:
  - nftokens
  - nftpage
  - nikb
+  - Nikolaos
  - nixfmt
  - nixos
  - nixpkgs
  - NOLINT
  - NOLINTNEXTLINE
  - nonxrp
+  - noreplace
  - noripple
+  - nostdinc
+  - notifempty
  - nudb
  - nullptr
  - nunl
  - Nyffenegger
+  - onlatest
  - ostr
+  - otool
+  - oxalica
  - pargs
  - partitioner
  - paychan
  - paychans
+  - Pedersen
  - permdex
  - perminute
  - permissioned
@@ -209,6 +250,7 @@ words:
  - preauthorize
  - preauthorizes
  - preclaim
+  - preun
  - protobuf
  - protos
  - ptrs
@@ -216,10 +258,22 @@ words:
  - pyenv
  - pyparsing
  - qalloc
+  - qbsprofile
+  - qself
  - queuable
  - Raphson
+  - rcflags
+  - reencrypted
  - replayer
+  - repodata
+  - repomd
+  - rerandomize
+  - rerandomization
+  - rerandomized
+  - rerandomizes
  - rerere
+  - retargeted
+  - retargets
  - retriable
  - RIPD
  - ripdtop
@@ -232,9 +286,13 @@ words:
  - rocksdb
  - Rohrs
  - roundings
+  - rustc
+  - rustfmt
+  - rustup
  - sahyadri
  - Satoshi
  - scons
+  - Schnorr
  - secp
  - sendq
  - seqit
@@ -243,17 +301,24 @@ words:
  - sfields
  - shamap
  - shamapitem
+  - shfmt
+  - shlibs
  - sidechain
  - SIGGOOD
  - sle
  - sles
  - soci
  - socidb
+  - Sonatype
+  - sponsee
+  - sponsees
+  - SRPMS
  - sslws
  - statsd
  - STATSDCOLLECTOR
  - stissue
  - stnum
+  - stnumber
  - stobj
  - stobject
  - stpath
@@ -262,12 +327,16 @@ words:
  - stvar
  - stvector
  - stxchainattestations
+  - summands
  - superpeer
  - superpeers
+  - Swatinem
  - takergets
  - takerpays
  - ters
  - TMEndpointv2
+  - toolchain
+  - tparam
  - trixie
  - tx
  - txid
@@ -276,8 +345,9 @@ words:
  - txn
  - txns
  - txs
-  - UBSAN
  - ubsan
+  - UBSAN
+  - ufdio
  - umant
  - unacquired
  - unambiguity
@@ -285,17 +355,21 @@ words:
  - unauthorizing
  - unergonomic
  - unfetched
+  - unfindable
  - unflatten
  - unfund
  - unimpair
+  - unmetered
  - unroutable
  - unscalable
  - unserviced
  - unshareable
  - unshares
+  - unsponsored
  - unsquelch
  - unsquelched
  - unsquelching
+  - unsuffixed
  - unvalidated
  - unveto
  - unvetoed
@@ -306,6 +380,8 @@ words:
  - vfalco
  - vinnie
  - wasmi
+  - wasmparser
+  - Werror
  - wextra
  - wptr
  - writeme
@@ -313,12 +389,18 @@ words:
  - wthread
  - xbridge
  - xchain
+  - xcrun
+  - xfloat
  - ximinez
-  - EXPECT_STREQ
  - XMACRO
+  - xored
+  - xrp
  - xrpkuwait
  - xrpl
  - xrpld
  - xrplf
  - xxhash
  - xxhasher
+  - zstdio
+  - CGNAT
+  - ungated
@@ -0,0 +1,14 @@
+watch_file nix/*.nix
+
+# Pinned Rust toolchain, read by nix/packages.nix via fromRustupToolchainFile.
+watch_file rust-toolchain.toml
+
+# The dev shell derivation includes all of conan/ (see nix/devshell.nix), so any
+# change in there has to invalidate direnv's cached environment.
+watch_dir conan
+
+use flake
+
+# Optional, untracked local overrides. To use a different shell, put e.g.
+# `use flake .#formal-verification` in .envrc.local.
+source_env_if_exists .envrc.local
@@ -11,7 +11,7 @@ endfunction()
 function(create_symbolic_link target link)
 endfunction()

-function(xrpl_add_test name)
+function(xrpl_add_benchmark name)
 endfunction()

 macro(exclude_from_default target_)
@@ -51,6 +51,12 @@ endfunction()
 function(add_module parent name)
 endfunction()

+function(verify_target_headers target headers_dir)
+endfunction()
+
+function(_verify_add_headers target dir)
+endfunction()
+
 function(setup_protocol_autogen)
 endfunction()

@@ -99,3 +105,78 @@ function(verbose_find_path variable name)
        ${ARGN}
    )
 endfunction()
+
+function(patch_nix_binary target)
+endfunction()
+
+function(rpcspec_generate_instantiations)
+    set(options)
+    set(oneValueArgs OUT_VAR VALUE_TYPE VIEW_HEADER INCLUDE_DIR)
+    set(multiValueArgs HANDLERS)
+    cmake_parse_arguments(
+        THIS_FUNCTION_PREFIX
+        "${options}"
+        "${oneValueArgs}"
+        "${multiValueArgs}"
+        ${ARGN}
+    )
+endfunction()
+
+function(corrosion_import_crate)
+    set(options
+        ALL_FEATURES
+        NO_DEFAULT_FEATURES
+        NO_STD
+        NO_LINKER_OVERRIDE
+        NO_USES_TERMINAL
+        LOCKED
+        FROZEN
+    )
+    set(oneValueArgs MANIFEST_PATH PROFILE IMPORTED_CRATES)
+    set(multiValueArgs
+        CRATE_TYPES
+        CRATES
+        FEATURES
+        FLAGS
+        OVERRIDE_CRATE_TYPE
+    )
+    cmake_parse_arguments(
+        THIS_FUNCTION_PREFIX
+        "${options}"
+        "${oneValueArgs}"
+        "${multiValueArgs}"
+        ${ARGN}
+    )
+endfunction()
+
+function(corrosion_set_env_vars target_name env_var)
+endfunction()
+
+function(corrosion_add_cxxbridge cxx_target)
+    set(options)
+    set(oneValueArgs CRATE)
+    set(multiValueArgs FILES)
+    cmake_parse_arguments(
+        THIS_FUNCTION_PREFIX
+        "${options}"
+        "${oneValueArgs}"
+        "${multiValueArgs}"
+        ${ARGN}
+    )
+endfunction()
+
+function(_unlink_libgcc_s crate)
+endfunction()
+
+function(add_xrpl_crate name)
+    set(options)
+    set(oneValueArgs CRATE)
+    set(multiValueArgs FILES)
+    cmake_parse_arguments(
+        THIS_FUNCTION_PREFIX
+        "${options}"
+        "${oneValueArgs}"
+        "${multiValueArgs}"
+        ${ARGN}
+    )
+endfunction()
@@ -5,6 +5,18 @@
 # This file is sorted in reverse chronological order, with the most recent commits at the top.
 # The commits listed here are ignored by git blame, which is useful for formatting-only commits that would otherwise obscure the history of changes to a file.

+# chore: CamelCase for typedef/using in `clang-tidy` (#8177)
+97a1824537d20d82d25bf151a37a7a4532ebf085
+# chore: Rename CamelCase namespaces to snake_case (#7933)
+06488c1318d96f56d0536251bee08ac85fa7fdd3
+# style: Unify style for all Doxygen comments (#7776)
+73b6852a122854140336e6e6bc30a3a4b41aa5fd
+# style: More clang-tidy identifier renaming (#7290)
+a830ab10efed8d3e59ef2fc15d66efdf9c6bb0d8
+# refactor: Rename static constants (#7120)
+5b6e8b6f93b19c1e3f6a3467a25639031d9d9a53
+# chore: More fixes for bad renames (#7092)
+7afdd71a54d562b32a50b29a5aa00bb997dc9053
 # refactor: Enable clang-tidy `readability-identifier-naming` check (#6571)
 8995564ed6b9e453e144bb663303072a3c1ba305
 # refactor: Enable remaining clang-tidy `cppcoreguidelines` checks (#6538)
@@ -15,9 +15,9 @@ inputs:
    required: false
    default: "false"
  log_verbosity:
-    description: "The logging verbosity."
+    description: 'The logging verbosity ("quiet", "verbose"), or empty to use the Conan defaults.'
    required: false
-    default: "verbose"
+    default: ""
  sanitizers:
    description: "The sanitizers to enable."
    required: false
@@ -35,14 +35,30 @@ runs:
        LOG_VERBOSITY: ${{ inputs.log_verbosity }}
        SANITIZERS: ${{ inputs.sanitizers }}
      run: |
-        echo 'Installing dependencies.'
+        # By default, leave the verbosity unset, so CMake configure output is
+        # shown, but compile commands and Boost's b2 debug output (~85k lines
+        # when "verbose") are not.
+        VERBOSITY_ARGS=()
+        if [[ -n "${LOG_VERBOSITY}" ]]; then
+            VERBOSITY_ARGS=(
+                --conf:all tools.build:verbosity="${LOG_VERBOSITY}"
+                --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}"
+            )
+        fi
        conan install \
-          --profile ci \
-          --build="${BUILD_OPTION}" \
-          --options:host='&:tests=True' \
-          --options:host='&:xrpld=True' \
-          --settings:all build_type="${BUILD_TYPE}" \
-          --conf:all tools.build:jobs=${BUILD_NPROC} \
-          --conf:all tools.build:verbosity="${LOG_VERBOSITY}" \
-          --conf:all tools.compilation:verbosity="${LOG_VERBOSITY}" \
-          .
+            --profile:all ci \
+            --build="${BUILD_OPTION}" \
+            --options:host='&:tests=True' \
+            --options:host='&:xrpld=True' \
+            --settings:all build_type="${BUILD_TYPE}" \
+            --conf:all tools.build:jobs=${BUILD_NPROC} \
+            "${VERBOSITY_ARGS[@]}" \
+            --format=json \
+            . >"${RUNNER_TEMP}/conan-graph.json"
+
+    # Tools that run during the build may only load glibc from the Nix store,
+    # as their package ID survives a GCC runtime update.
+    - name: Check build-context packages for Nix store dependencies (Linux)
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      run: ./bin/nix/check-build-context-runtime.sh "${RUNNER_TEMP}/conan-graph.json"
@@ -0,0 +1,39 @@
+name: Use cargo artifacts cache
+description: >
+  Cache the cargo build artifacts with rust-cache. Never caches ~/.cargo/bin:
+  when saving the cache, rust-cache deletes all binaries that were already
+  present there, which on persistent self-hosted runners wipes the tools
+  installed by prepare-runner. Harmless on ephemeral runners, but kept
+  consistent everywhere.
+
+inputs:
+  workspaces:
+    description: "Workspaces to cache, as 'workspace -> target' lines."
+    required: false
+    default: crates
+  key:
+    description: "Additional part of the cache key."
+    required: false
+    default: ""
+  cache-directories:
+    description: "Additional non-workspace directories to cache."
+    required: false
+    default: ""
+  save-if:
+    description: >
+      Condition for saving the cache after the job. Defaults to save only from develop branch
+    required: false
+    default: ${{ github.ref == 'refs/heads/develop' }}
+
+runs:
+  using: composite
+
+  steps:
+    - name: Use cargo artifacts cache
+      uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      with:
+        cache-bin: "false"
+        cache-directories: ${{ inputs.cache-directories }}
+        key: ${{ inputs.key }}
+        save-if: ${{ inputs.save-if }}
+        workspaces: ${{ inputs.workspaces }}
@@ -1,44 +0,0 @@
-name: Generate build version number
-description: "Generate build version number."
-
-outputs:
-  version:
-    description: "The generated build version number."
-    value: ${{ steps.version.outputs.version }}
-
-runs:
-  using: composite
-  steps:
-    # When a tag is pushed, the version is used as-is.
-    - name: Generate version for tag event
-      if: ${{ startsWith(github.ref, 'refs/tags/') }}
-      shell: bash
-      env:
-        VERSION: ${{ github.ref_name }}
-      run: echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
-
-    # When a tag is not pushed, then the version (e.g. 1.2.3-b0) is extracted
-    # from the BuildInfo.cpp file and the shortened commit hash appended to it.
-    # We use a plus sign instead of a hyphen because Conan recipe versions do
-    # not support two hyphens.
-    - name: Generate version for non-tag event
-      if: ${{ !startsWith(github.ref, 'refs/tags/') }}
-      shell: bash
-      run: |
-        echo 'Extracting version from BuildInfo.cpp.'
-        VERSION="$(cat src/libxrpl/protocol/BuildInfo.cpp | grep "versionString =" | awk -F '"' '{print $2}')"
-        if [[ -z "${VERSION}" ]]; then
-          echo 'Unable to extract version from BuildInfo.cpp.'
-          exit 1
-        fi
-
-        echo 'Appending shortened commit hash to version.'
-        SHA='${{ github.sha }}'
-        VERSION="${VERSION}+${SHA:0:7}"
-
-        echo "VERSION=${VERSION}" >> "${GITHUB_ENV}"
-
-    - name: Output version
-      id: version
-      shell: bash
-      run: echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
@@ -0,0 +1,39 @@
+name: Release info
+description: "Derive the version, release channel and package release number for this build."
+
+outputs:
+  version:
+    description: "The build version number."
+    value: ${{ steps.version.outputs.version }}
+  channel:
+    description: "The release channel this build belongs to."
+    value: ${{ steps.release_info.outputs.channel }}
+  pkg_release:
+    description: "The package release number: 1 for a tag, <run number>.<commit date>git<short commit hash> otherwise."
+    value: ${{ steps.release_info.outputs.pkg_release }}
+
+runs:
+  using: composite
+  steps:
+    # A tag names its own version. Anything else is a development build named by
+    # its commit hash, matching what cmake/XrplVersion.cmake derives: the head of
+    # a pull request rather than the merge commit GitHub creates for it.
+    - name: Determine version
+      id: version
+      shell: bash
+      env:
+        IS_TAG: ${{ startsWith(github.ref, 'refs/tags/') }}
+        REF_NAME: ${{ github.ref_name }}
+        SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+      run: |
+        if [[ "${IS_TAG}" == "true" ]]; then
+            version="${REF_NAME}"
+        else
+            version="0.0.0-dev+${SHA:0:7}"
+        fi
+
+        echo "version=${version}" | tee -a "${GITHUB_OUTPUT}"
+
+    - name: Determine release channel and package release
+      id: release_info
+      uses: XRPLF/actions/release-info@a9f2eeca6fb3980ba3a84cf68566f1c69ad30674
@@ -0,0 +1,34 @@
+name: Set compiler environment
+description: "Set CC and CXX environment variables for the given compiler."
+
+inputs:
+  compiler:
+    description: 'The compiler to use ("gcc" or "clang").'
+    required: true
+
+runs:
+  using: composite
+
+  steps:
+    - name: Set CC and CXX for gcc
+      if: ${{ inputs.compiler == 'gcc' }}
+      shell: bash
+      run: |
+        echo "CC=gcc" >>"${GITHUB_ENV}"
+        echo "CXX=g++" >>"${GITHUB_ENV}"
+
+    - name: Set CC and CXX for clang
+      if: ${{ inputs.compiler == 'clang' }}
+      shell: bash
+      run: |
+        echo "CC=clang" >>"${GITHUB_ENV}"
+        echo "CXX=clang++" >>"${GITHUB_ENV}"
+
+    - name: Fail on unknown compiler
+      if: ${{ inputs.compiler != 'gcc' && inputs.compiler != 'clang' }}
+      shell: bash
+      env:
+        COMPILER: ${{ inputs.compiler }}
+      run: |
+        echo "Unknown compiler: $COMPILER" >&2
+        exit 1
@@ -9,38 +9,41 @@ inputs:
  remote_url:
    description: "The URL of the Conan endpoint to use."
    required: false
-    default: https://conan.ripplex.io
+    default: https://conan.xrplf.org/repository/conan/

 runs:
  using: composite

  steps:
-    - name: Set up Conan configuration
+    - name: Apply custom configuration to global.conf
      shell: bash
      run: |
-        echo 'Installing configuration.'
        cat conan/global.conf ${{ runner.os == 'Linux' && '>>' || '>' }} $(conan config home)/global.conf

-        echo 'Conan configuration:'
-        conan config show '*'
-
-    - name: Set up Conan profile
+    - name: Show global configuration
+      shell: bash
+      run: |
+        conan config show '*'
+
+    - name: Install profiles
      shell: bash
      run: |
-        echo 'Installing profile.'
        conan config install conan/profiles/ -tf $(conan config home)/profiles/

-        echo 'Conan profile:'
+    - name: Show CI profile
+      shell: bash
+      run: |
        conan profile show --profile ci

-    - name: Set up Conan remote
+    - name: Add a remote
      shell: bash
      env:
        REMOTE_NAME: ${{ inputs.remote_name }}
        REMOTE_URL: ${{ inputs.remote_url }}
      run: |
-        echo "Adding Conan remote '${REMOTE_NAME}' at '${REMOTE_URL}'."
        conan remote add --index 0 --force "${REMOTE_NAME}" "${REMOTE_URL}"

-        echo 'Listing Conan remotes.'
+    - name: List remotes
+      shell: bash
+      run: |
        conan remote list
@@ -0,0 +1,70 @@
+name: Setup Nix environment
+description: "Build the flake's CI environment and put its tools on PATH."
+
+# The environment from nix/ci-env.nix, the same one the Linux CI images bake in
+# (see nix/docker). Exported onto PATH rather than entered with `nix develop`:
+# the composite actions below run plain `bash` and would escape a dev shell.
+
+runs:
+  using: composite
+
+  steps:
+    - name: Build the CI environment
+      id: build
+      shell: bash
+      env:
+        # --out-link doubles as a GC root for the length of the job.
+        OUT_LINK: ${{ runner.temp }}/xrpld-ci-env
+      run: |
+        # --extra-experimental-features: flakes may not be on in the runner's nix.conf.
+        nix --extra-experimental-features "nix-command flakes" \
+            build .#default --out-link "${OUT_LINK}" --print-build-logs
+        echo "path=$(readlink -f "${OUT_LINK}")" >>"${GITHUB_OUTPUT}"
+
+    - name: Export the environment
+      shell: bash
+      env:
+        ENV_PATH: ${{ steps.build.outputs.path }}
+      run: |
+        echo "${ENV_PATH}/bin" >>"${GITHUB_PATH}"
+
+        # Already KEY=VALUE per line. See `darwinEnv` in nix/ci-env.nix.
+        ENV_FILE="${ENV_PATH}/share/xrpld-ci-env/env"
+        if [ -f "${ENV_FILE}" ]; then
+            cat "${ENV_FILE}" >>"${GITHUB_ENV}"
+        fi
+
+        # XrplSanity.cmake otherwise rejects a Nix compiler as one that leaked.
+        echo "XRPL_DEVSHELL=ci-env" >>"${GITHUB_ENV}"
+
+        # Unlike the Linux nix images, macOS needs no SSL_CERT_FILE: it has its
+        # own trust store, and pinning would break TLS to hosts relying on it.
+
+        # In RUNNER_TEMP, which the runner empties per job, like the `.conan2`
+        # prepare-runner hands the system toolchain - but under its own name:
+        # that Conan is a different version, and the two would migrate each
+        # other's cache.
+        echo "CONAN_HOME=${RUNNER_TEMP}/.conan2-nix" >>"${GITHUB_ENV}"
+
+    # Config, profiles and remote, exactly as the dev shell sets them up on
+    # entry; the `setup-conan` action is skipped for this toolchain.
+    - name: Setup Conan
+      shell: bash
+      run: ./conan/init.sh
+
+    # `Check tools` runs later but swallows failures; a bad export would just
+    # build with the system toolchain.
+    - name: Verify the toolchain resolves into the Nix store
+      shell: bash
+      run: |
+        for tool in clang clang++ cmake ninja conan; do
+            path="$(command -v "${tool}" || true)"
+            echo "${tool} -> ${path:-<not found>}"
+            case "${path}" in
+                /nix/store/*) ;;
+                *)
+                    echo "::error::${tool} does not resolve into the Nix store"
+                    exit 1
+                    ;;
+            esac
+        done
@@ -1,7 +1,13 @@
 version: 2
 updates:
  - package-ecosystem: github-actions
-    directory: /
+    directories:
+      - /
+      - .github/actions/build-deps/
+      - .github/actions/cargo-cache/
+      - .github/actions/release-info/
+      - .github/actions/set-compiler-env/
+      - .github/actions/setup-conan/
    schedule:
      interval: weekly
      day: monday
@@ -10,36 +16,23 @@ updates:
    commit-message:
      prefix: "ci: [DEPENDABOT] "
    target-branch: develop
+    groups:
+      github-actions:
+        patterns:
+          - "*"

-  - package-ecosystem: github-actions
-    directory: .github/actions/build-deps/
+  - package-ecosystem: cargo
+    directory: /crates
    schedule:
      interval: weekly
      day: monday
      time: "04:00"
      timezone: Etc/GMT
    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/generate-version/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/setup-conan/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
+      prefix: "chore: [DEPENDABOT] "
    target-branch: develop
+    open-pull-requests-limit: 10
+    groups:
+      rust-dependencies:
+        patterns:
+          - "*"
@@ -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,10 +15,10 @@ 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
+## Context of Change

 <!--
 Please include the context of a change.
@@ -29,7 +29,7 @@ If a refactor, how is this better than the previous implementation?
 If there is a spec or design document for this feature, please link it here.
 -->

-### API Impact
+## API Impact

 <!--
 Please check [x] relevant options, delete irrelevant ones.
@@ -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.
 -->
@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+
+"""
+Format embedded shell snippets using the shfmt hook configured in
+.pre-commit-config.yaml.
+
+Two shapes are recognised:
+
+* YAML workflow/action files: literal block-scalar runs (`run: |`) and
+  single-line runs (`run: some command`). A single-line run is upgraded to
+  a `run: |` block scalar if shfmt's output spans multiple lines.
+
+* Markdown files: ``` ```bash ``` fenced code blocks.
+
+Any block that shfmt cannot parse is skipped with a warning on stderr, so
+the file is left untouched and surrounding blocks still get formatted.
+
+For each occurrence the body is dedented, written to a temp .sh file,
+formatted via `pre-commit run shfmt --files <temp>` (falling back to
+`prek`), then re-indented and written back in place.
+
+When invoked without arguments, every .yml/.yaml under .github/ plus every
+.md file in the repo is scanned. When invoked with file arguments (the
+pre-commit case), only those files are processed.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Union
+
+REPO = Path(__file__).resolve().parents[2]
+
+_HOOK_RUNNER = next((cmd for cmd in ("pre-commit", "prek") if shutil.which(cmd)), None)
+if _HOOK_RUNNER is None:
+    sys.exit("error: neither `pre-commit` nor `prek` found on PATH")
+
+RUN_BLOCK_RE = re.compile(r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]*\|[+-]?[ \t]*$")
+RUN_INLINE_RE = re.compile(
+    r"^(?P<prefix>[ \t]*(?:- )?)run:[ \t]+" r"(?P<value>(?!\|[+-]?[ \t]*$)\S.*?)[ \t]*$"
+)
+MD_BASH_OPEN_RE = re.compile(r"^(?P<indent>[ ]{0,3})`{3}bash[ \t]*$")
+MD_FENCE_CLOSE_RE = re.compile(r"^[ ]{0,3}`{3,}[ \t]*$")
+
+
+@dataclass(frozen=True)
+class BlockRun:
+    """A `run: |` block scalar; `body_start:body_end` slices into `lines`."""
+
+    body_start: int
+    body_end: int
+    body_indent: int
+
+
+@dataclass(frozen=True)
+class InlineRun:
+    """A single-line `run: value` at `line_idx`."""
+
+    line_idx: int
+    prefix: str
+    value: str
+
+
+@dataclass(frozen=True)
+class MdBashBlock:
+    """A markdown ``` ```bash ``` fenced code block.
+
+    `body_start:body_end` slices into the file's lines; `open_line_idx`
+    points at the opening fence line.
+    """
+
+    open_line_idx: int
+    body_start: int
+    body_end: int
+    body_indent: int
+
+
+RunItem = Union[BlockRun, InlineRun]
+
+
+def _scan_block_body(
+    lines: list[str], body_start: int, run_col: int
+) -> tuple[int | None, int]:
+    """Locate the body of a `run: |` block scalar starting at `body_start`.
+
+    Returns `(body_indent, scan_end)`. `scan_end` is the line index where the
+    outer scanner should resume. `body_indent` is `None` when no body is
+    present (the scalar is empty, or the next non-blank line has indent
+    `<= run_col`).
+    """
+    body_indent: int | None = None
+    scan_end = len(lines)
+    for idx in range(body_start, len(lines)):
+        line = lines[idx]
+        if line.strip() == "":
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if body_indent is None:
+            if indent > run_col:
+                body_indent = indent
+            else:
+                scan_end = idx
+                break
+        elif indent < body_indent:
+            scan_end = idx
+            break
+    if body_indent is not None:
+        while scan_end > body_start and lines[scan_end - 1].strip() == "":
+            scan_end -= 1
+        if scan_end <= body_start:
+            body_indent = None
+    return body_indent, scan_end
+
+
+def find_run_blocks(lines: list[str]) -> list[RunItem]:
+    """Return run items in document order."""
+    items: list[RunItem] = []
+    line_idx = 0
+    while line_idx < len(lines):
+        line = lines[line_idx]
+        if block_match := RUN_BLOCK_RE.match(line):
+            run_col = len(block_match.group("prefix"))
+            body_start = line_idx + 1
+            body_indent, scan_end = _scan_block_body(lines, body_start, run_col)
+            if body_indent is not None:
+                items.append(
+                    BlockRun(
+                        body_start=body_start,
+                        body_end=scan_end,
+                        body_indent=body_indent,
+                    )
+                )
+            line_idx = scan_end
+            continue
+        if inline_match := RUN_INLINE_RE.match(line):
+            items.append(
+                InlineRun(
+                    line_idx=line_idx,
+                    prefix=inline_match.group("prefix"),
+                    value=inline_match.group("value"),
+                )
+            )
+        line_idx += 1
+    return items
+
+
+def find_md_bash_blocks(lines: list[str]) -> list[MdBashBlock]:
+    """Return ``` ```bash ``` fenced code blocks in document order."""
+    blocks: list[MdBashBlock] = []
+    line_idx = 0
+    while line_idx < len(lines):
+        open_match = MD_BASH_OPEN_RE.match(lines[line_idx])
+        if not open_match:
+            line_idx += 1
+            continue
+        body_start = line_idx + 1
+        close_idx = next(
+            (
+                j
+                for j in range(body_start, len(lines))
+                if MD_FENCE_CLOSE_RE.match(lines[j])
+            ),
+            None,
+        )
+        if close_idx is None:
+            line_idx = body_start
+            continue
+        body = lines[body_start:close_idx]
+        non_blank = [b for b in body if b.strip()]
+        body_indent = (
+            min(len(b) - len(b.lstrip(" ")) for b in non_blank)
+            if non_blank
+            else len(open_match.group("indent"))
+        )
+        blocks.append(
+            MdBashBlock(
+                open_line_idx=line_idx,
+                body_start=body_start,
+                body_end=close_idx,
+                body_indent=body_indent,
+            )
+        )
+        line_idx = close_idx + 1
+    return blocks
+
+
+def dedent(lines: list[str], n: int) -> list[str]:
+    pad = " " * n
+    return [
+        (
+            ""
+            if line.strip() == ""
+            else (line[n:] if line.startswith(pad) else line.lstrip(" "))
+        )
+        for line in lines
+    ]
+
+
+def reindent(lines: list[str], n: int) -> list[str]:
+    pad = " " * n
+    return [pad + line if line else "" for line in lines]
+
+
+_SHFMT_ERR_RE = re.compile(r"\.sh:\d+:\d+:\s")
+_GHA_EXPR_RE = re.compile(r"\$\{\{.*?\}\}", re.DOTALL)
+_GHA_PLACEHOLDER_RE = re.compile(r"__GHA_EXPR_(\d+)__")
+
+
+def _encode_gha_exprs(text: str) -> tuple[str, list[str]]:
+    """Replace `${{ ... }}` expressions with bash-safe placeholder identifiers."""
+    exprs: list[str] = []
+
+    def repl(match: re.Match[str]) -> str:
+        exprs.append(match.group(0))
+        return f"__GHA_EXPR_{len(exprs) - 1}__"
+
+    return _GHA_EXPR_RE.sub(repl, text), exprs
+
+
+def _decode_gha_exprs(text: str, exprs: list[str]) -> str:
+    """Restore `${{ ... }}` expressions from placeholder identifiers."""
+    return _GHA_PLACEHOLDER_RE.sub(lambda m: exprs[int(m.group(1))], text)
+
+
+def shfmt_via_hook(tmp_path: Path) -> tuple[bool, str]:
+    # `${{ ... }}` is not valid shell, so swap it for a placeholder identifier
+    # that shfmt can parse, then restore it after formatting.
+    encoded, exprs = _encode_gha_exprs(tmp_path.read_text())
+    if exprs:
+        tmp_path.write_text(encoded)
+    res = subprocess.run(
+        [_HOOK_RUNNER, "run", "shfmt", "--files", str(tmp_path)],
+        cwd=REPO,
+        capture_output=True,
+        text=True,
+    )
+    output = res.stdout + res.stderr
+    # shfmt emits parse errors as "<path>:<line>:<col>: <message>".
+    parse_err = bool(_SHFMT_ERR_RE.search(output))
+    # A non-zero exit that is neither a parse error nor pre-commit's "I had
+    # to modify files" signal means the hook itself failed to run (missing
+    # binary, install failure, bad config, ...). Surface that loudly rather
+    # than silently treating it as a no-op.
+    if (
+        res.returncode != 0
+        and not parse_err
+        and "files were modified by this hook" not in output
+    ):
+        sys.exit(
+            f"error: `{_HOOK_RUNNER} run shfmt` failed with exit {res.returncode}:\n{output}"
+        )
+    if exprs and not parse_err:
+        tmp_path.write_text(_decode_gha_exprs(tmp_path.read_text(), exprs))
+    return not parse_err, output
+
+
+def _skip(path: Path, where: int, kind: str, output: str) -> None:
+    print(
+        f"  shfmt could not parse {kind} at {path}:{where + 1} — skipped",
+        file=sys.stderr,
+    )
+    print(f"    {output.strip()}", file=sys.stderr)
+
+
+def process_yaml_file(path: Path, tmp_path: Path) -> int:
+    text = path.read_text()
+    had_nl = text.endswith("\n")
+    lines = text.split("\n")
+    if had_nl:
+        lines = lines[:-1]
+    items = find_run_blocks(lines)
+    if not items:
+        return 0
+    changed = 0
+    # Process in reverse so earlier indices remain valid as we splice.
+    for item in reversed(items):
+        if isinstance(item, BlockRun):
+            body = lines[item.body_start : item.body_end]
+            tmp_path.write_text("\n".join(dedent(body, item.body_indent)) + "\n")
+            ok, output = shfmt_via_hook(tmp_path)
+            if not ok:
+                _skip(path, item.body_start, "block", output)
+                continue
+            formatted = tmp_path.read_text().rstrip("\n")
+            new_body = reindent(formatted.split("\n"), item.body_indent)
+            if new_body != body:
+                lines[item.body_start : item.body_end] = new_body
+                changed += 1
+        else:
+            tmp_path.write_text(item.value + "\n")
+            ok, output = shfmt_via_hook(tmp_path)
+            if not ok:
+                _skip(path, item.line_idx, "inline run", output)
+                continue
+            formatted = tmp_path.read_text().rstrip("\n")
+            if formatted == item.value:
+                continue
+            formatted_lines = formatted.split("\n")
+            if len(formatted_lines) == 1:
+                lines[item.line_idx] = f"{item.prefix}run: {formatted}"
+            else:
+                body_indent = len(item.prefix) + 2
+                lines[item.line_idx : item.line_idx + 1] = [
+                    f"{item.prefix}run: |",
+                    *reindent(formatted_lines, body_indent),
+                ]
+            changed += 1
+    new_text = "\n".join(lines) + ("\n" if had_nl else "")
+    if new_text != text:
+        path.write_text(new_text)
+    return changed
+
+
+def process_md_file(path: Path, tmp_path: Path) -> int:
+    text = path.read_text()
+    had_nl = text.endswith("\n")
+    lines = text.split("\n")
+    if had_nl:
+        lines = lines[:-1]
+    blocks = find_md_bash_blocks(lines)
+    if not blocks:
+        return 0
+    changed = 0
+    for block in reversed(blocks):
+        body = lines[block.body_start : block.body_end]
+        tmp_path.write_text("\n".join(dedent(body, block.body_indent)) + "\n")
+        ok, output = shfmt_via_hook(tmp_path)
+        if not ok:
+            _skip(path, block.open_line_idx, "```bash block", output)
+            continue
+        formatted = tmp_path.read_text().rstrip("\n")
+        formatted_lines = formatted.split("\n") if formatted else []
+        new_body = reindent(formatted_lines, block.body_indent)
+        if new_body != body:
+            lines[block.body_start : block.body_end] = new_body
+            changed += 1
+    new_text = "\n".join(lines) + ("\n" if had_nl else "")
+    if new_text != text:
+        path.write_text(new_text)
+    return changed
+
+
+def process_file(path: Path, tmp_path: Path) -> int:
+    if path.suffix in (".yml", ".yaml"):
+        return process_yaml_file(path, tmp_path)
+    if path.suffix == ".md":
+        return process_md_file(path, tmp_path)
+    return 0
+
+
+def gather_files(argv: list[str]) -> list[Path]:
+    """Return YAML workflow/action files and markdown files that we should
+    process — either the paths in `argv` or, when `argv` is empty, every
+    such file in the repo (skipping `external/`)."""
+    if argv:
+        candidates: list[Path] = [
+            (REPO / a).resolve() if not Path(a).is_absolute() else Path(a) for a in argv
+        ]
+    else:
+        gh = REPO / ".github"
+        candidates = [
+            *gh.rglob("*.yml"),
+            *gh.rglob("*.yaml"),
+            *(
+                p
+                for p in REPO.rglob("*.md")
+                if "external" not in p.relative_to(REPO).parts
+            ),
+        ]
+    return sorted(
+        p
+        for p in candidates
+        if p.exists()
+        and (
+            (p.suffix in (".yml", ".yaml") and ".github" in p.parts)
+            or p.suffix == ".md"
+        )
+    )
+
+
+def main(argv: list[str]) -> int:
+    files = gather_files(argv)
+    if not files:
+        return 0
+    with tempfile.TemporaryDirectory(prefix="format-inline-bash-") as tmpdir:
+        tmp_path = Path(tmpdir) / "shfmt.sh"
+        total = 0
+        for f in files:
+            n = process_file(f, tmp_path)
+            if n:
+                print(f"{f.relative_to(REPO)}: reformatted {n} block(s)")
+                total += n
+        return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -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

@@ -1,15 +1,6 @@
-Loop: test.jtx test.toplevel
-  test.toplevel > test.jtx
-
-Loop: test.jtx test.unit_test
-  test.unit_test ~= test.jtx
-
 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

@@ -1,6 +1,16 @@
+benchmarks.libxrpl > xrpl.basics
+benchmarks.libxrpl > xrpl.config
+benchmarks.libxrpl > xrpl.nodestore
+benchmarks.libxrpl > xrpl.protocol
+benchmarks.libxrpl > xrpl.protocol_autogen
+benchmarks.libxrpl > xrpl.tx
 libxrpl.basics > xrpl.basics
 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
@@ -12,18 +22,22 @@ libxrpl.ledger > xrpl.json
 libxrpl.ledger > xrpl.ledger
 libxrpl.ledger > xrpl.nodestore
 libxrpl.ledger > xrpl.protocol
-libxrpl.ledger > xrpl.server
 libxrpl.ledger > xrpl.shamap
 libxrpl.net > xrpl.basics
 libxrpl.net > xrpl.net
 libxrpl.nodestore > xrpl.basics
+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
 libxrpl.rdb > xrpl.basics
+libxrpl.rdb > xrpl.config
 libxrpl.rdb > xrpl.core
 libxrpl.rdb > xrpl.rdb
 libxrpl.resource > xrpl.basics
@@ -31,6 +45,7 @@ libxrpl.resource > xrpl.json
 libxrpl.resource > xrpl.protocol
 libxrpl.resource > xrpl.resource
 libxrpl.server > xrpl.basics
+libxrpl.server > xrpl.config
 libxrpl.server > xrpl.core
 libxrpl.server > xrpl.json
 libxrpl.server > xrpl.protocol
@@ -52,9 +67,10 @@ libxrpl.tx > xrpl.tx
 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
@@ -67,22 +83,16 @@ test.app > xrpl.server
 test.app > xrpl.shamap
 test.app > xrpl.tx
 test.basics > test.jtx
-test.basics > test.unit_test
 test.basics > xrpl.basics
 test.basics > xrpl.core
-test.basics > xrpld.rpc
 test.basics > xrpl.json
 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.toplevel
-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
@@ -90,23 +100,22 @@ test.consensus > xrpl.tx
 test.core > test.jtx
 test.core > test.unit_test
 test.core > xrpl.basics
+test.core > xrpl.config
 test.core > xrpl.core
 test.core > xrpld.core
 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.csf > xrpl.protocol
 test.json > test.jtx
 test.json > xrpl.json
+test.jtx > test.unit_test
 test.jtx > xrpl.basics
+test.jtx > xrpl.config
 test.jtx > xrpl.core
 test.jtx > xrpld.app
 test.jtx > xrpld.core
+test.jtx > xrpld.overlay
 test.jtx > xrpld.rpc
 test.jtx > xrpl.json
 test.jtx > xrpl.ledger
@@ -124,41 +133,33 @@ test.ledger > xrpl.json
 test.ledger > xrpl.ledger
 test.ledger > xrpl.protocol
 test.nodestore > test.jtx
-test.nodestore > test.unit_test
 test.nodestore > xrpl.basics
 test.nodestore > xrpld.core
 test.nodestore > xrpl.nodestore
-test.nodestore > xrpl.protocol
 test.nodestore > xrpl.rdb
 test.overlay > test.jtx
 test.overlay > test.unit_test
 test.overlay > xrpl.basics
+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
+test.protocol > xrpld.core
 test.protocol > xrpl.json
 test.protocol > xrpl.protocol
-test.resource > test.unit_test
-test.resource > xrpl.basics
-test.resource > xrpl.resource
 test.rpc > test.jtx
 test.rpc > xrpl.basics
+test.rpc > xrpl.config
 test.rpc > xrpl.core
 test.rpc > xrpld.app
 test.rpc > xrpld.core
@@ -173,44 +174,55 @@ test.rpc > xrpl.tx
 test.server > test.jtx
 test.server > test.unit_test
 test.server > xrpl.basics
+test.server > xrpl.config
 test.server > xrpld.app
 test.server > xrpld.core
 test.server > xrpl.json
 test.server > xrpl.protocol
 test.server > xrpl.server
-test.shamap > test.unit_test
-test.shamap > xrpl.basics
-test.shamap > xrpl.nodestore
-test.shamap > xrpl.protocol
-test.shamap > xrpl.shamap
-test.toplevel > test.csf
-test.toplevel > xrpl.json
 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
 tests.libxrpl > xrpl.server
 tests.libxrpl > xrpl.shamap
 tests.libxrpl > xrpl.tx
+tests.xrpld > xrpld.rpc
+tests.xrpld > xrpl.json
+tests.xrpld > xrpl.protocol
 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
 xrpl.json > xrpl.basics
 xrpl.ledger > xrpl.basics
+xrpl.ledger > xrpl.json
+xrpl.ledger > xrpl.nodestore
 xrpl.ledger > xrpl.protocol
-xrpl.ledger > xrpl.server
 xrpl.ledger > xrpl.shamap
 xrpl.net > xrpl.basics
 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
@@ -227,7 +239,6 @@ xrpl.server > xrpl.json
 xrpl.server > xrpl.protocol
 xrpl.server > xrpl.rdb
 xrpl.server > xrpl.resource
-xrpl.server > xrpl.shamap
 xrpl.shamap > xrpl.basics
 xrpl.shamap > xrpl.nodestore
 xrpl.shamap > xrpl.protocol
@@ -237,50 +248,56 @@ xrpl.tx > xrpl.ledger
 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
 xrpld.core > xrpl.net
 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 > 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
 xrpld.perflog > xrpl.core
-xrpld.perflog > xrpld.rpc
+xrpld.perflog > xrpld.app
 xrpld.perflog > xrpl.json
+xrpld.perflog > xrpl.nodestore
 xrpld.perflog > xrpl.protocol
+xrpld.perflog > xrpl.server
 xrpld.rpc > xrpl.basics
+xrpld.rpc > xrpl.config
 xrpld.rpc > xrpl.core
 xrpld.rpc > xrpld.core
 xrpld.rpc > xrpl.json
@@ -295,5 +312,6 @@ xrpld.rpc > xrpl.shamap
 xrpld.rpc > xrpl.tx
 xrpld.shamap > xrpl.basics
 xrpld.shamap > xrpld.core
+xrpld.shamap > xrpl.nodestore
 xrpld.shamap > xrpl.protocol
 xrpld.shamap > xrpl.shamap
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+# Exit the script as soon as an error occurs.
+set -euo pipefail
+
+# This script fails if <head> merges a release back into <base>,
+# but also adds commits that aren't on a release or staging branch, see RELEASING.md.
+# Merge commits are allowed.
+# Usage: .github/scripts/releasing/check-merge-back-commits.sh <base> <head>
+
+if [ "$#" -ne 2 ]; then
+    echo "Usage: $0 <base> <head>"
+    exit 1
+fi
+
+BASE=$1
+HEAD=$2
+
+SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
+# shellcheck source=.github/scripts/releasing/common.sh
+source "${SCRIPT_DIR}/common.sh"
+load_release_branches
+
+# A PR is a merge-back if some of its commits are on a release or staging branch.
+PR_COUNT=$(git rev-list --no-merges --count "${BASE}..${HEAD}")
+NEW_COUNT=$(git rev-list --no-merges --count "${BASE}..${HEAD}" --not "${BRANCHES[@]}")
+if ((NEW_COUNT == PR_COUNT)); then
+    echo "This PR doesn't merge a release back."
+    exit 0
+fi
+if ((NEW_COUNT == 0)); then
+    echo "This merge-back adds no commits of its own."
+    exit 0
+fi
+
+echo "This PR merges a release back, but also adds commits that aren't on a release or staging branch:"
+git log --no-merges --format='  %h %s' "${BASE}..${HEAD}" --not "${BRANCHES[@]}"
+echo
+echo "Make these changes in a separate PR, see RELEASING.md."
+exit 1
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Exit the script as soon as an error occurs.
+set -euo pipefail
+
+# This script fails if the commits in <base>..<head> copy commits from a release or staging branch
+# (e.g. by rebasing or cherry-picking them) instead of merging that branch, see RELEASING.md.
+# Commits are compared by patch-id,
+# and only against release and staging commits that <head> does not already contain.
+# Usage: .github/scripts/releasing/check-no-copied-release-commits.sh <base> <head>
+
+if [ "$#" -ne 2 ]; then
+    echo "Usage: $0 <base> <head>"
+    exit 1
+fi
+
+BASE=$1
+HEAD=$2
+
+patch_ids() {
+    git log --no-merges --patch --no-color --no-ext-diff "$@" | git patch-id --stable | sort
+}
+
+SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
+# shellcheck source=.github/scripts/releasing/common.sh
+source "${SCRIPT_DIR}/common.sh"
+load_release_branches
+
+# Each line is "<patch-id> <commit>".
+RELEASE_PATCHES=$(patch_ids "${BRANCHES[@]}" --not "${HEAD}")
+PR_PATCHES=$(patch_ids "${BASE}..${HEAD}")
+
+# Each line is "<patch-id> <release commit> <PR commit>".
+COPIES=$(join <(echo "${RELEASE_PATCHES}") <(echo "${PR_PATCHES}"))
+if [ -z "${COPIES}" ]; then
+    echo "No copied release commits found."
+    exit 0
+fi
+
+echo "These commits copy release commits instead of merging them:"
+while read -r _ RELEASE_COMMIT PR_COMMIT; do
+    echo "  $(git log -1 --format='%h %s' "${PR_COMMIT}") (copies ${RELEASE_COMMIT:0:10})"
+done <<<"${COPIES}"
+echo
+echo "Merge the release tag (or branch) instead, see RELEASING.md."
+exit 1
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+# Exit the script as soon as an error occurs.
+set -euo pipefail
+
+# This script fails if <head> contains release or staging commits that <base> does not,
+# i.e. if <head> merges a release back into <base>.
+# Used in the merge queue, which squashes PRs and would drop the merge commit, see RELEASING.md.
+# Usage: .github/scripts/releasing/check-no-merge-back.sh <base> <head>
+
+if [ "$#" -ne 2 ]; then
+    echo "Usage: $0 <base> <head>"
+    exit 1
+fi
+
+BASE=$1
+HEAD=$2
+
+SCRIPT_DIR=$(dirname "${BASH_SOURCE[0]}")
+# shellcheck source=.github/scripts/releasing/common.sh
+source "${SCRIPT_DIR}/common.sh"
+load_release_branches
+
+RELEASE_COMMITS=$(git rev-list "${BRANCHES[@]}" --not "${BASE}")
+HEAD_COMMITS=$(git rev-list "${BASE}..${HEAD}")
+# The release commits in <head>, newest first.
+MERGED=$(grep -xF -f <(echo "${RELEASE_COMMITS}") <<<"${HEAD_COMMITS}" || true)
+if [ -z "${MERGED}" ]; then
+    echo "No release commits are merged back."
+    exit 0
+fi
+
+echo "This PR merges $(wc -l <<<"${MERGED}" | tr -d ' ') release commits back, e.g.:"
+head -5 <<<"${MERGED}" | xargs git log --no-walk --format='  %h %s'
+echo
+echo "Merge-backs must not go through the merge queue, which squashes them."
+echo "Fast-forward develop to the PR branch instead, see RELEASING.md."
+exit 1
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Exit the script as soon as an error occurs.
+set -euo pipefail
+
+# This script fails if a final release (a tag like 3.4.0) on a release branch
+# is not merged back into <develop> within a few days, see RELEASING.md.
+# Usage: .github/scripts/releasing/check-releases-merged.sh <develop>
+
+if [ "$#" -ne 1 ]; then
+    echo "Usage: $0 <develop>"
+    exit 1
+fi
+
+DEVELOP=$1
+GRACE_DAYS=3
+
+mapfile -t MERGED_ARGS < <(git for-each-ref --format='--merged=%(refname)' 'refs/remotes/*/release/*')
+if [ "${#MERGED_ARGS[@]}" -eq 0 ]; then
+    echo "Error: No release branches found."
+    exit 1
+fi
+
+# Tags on a release branch that <develop> does not contain.
+TAGS=$(git for-each-ref --format='%(refname:short) %(creatordate:unix)' \
+    "${MERGED_ARGS[@]}" --no-merged="${DEVELOP}" 'refs/tags/[0-9]*')
+
+MISSING=0
+while read -r TAG CREATED; do
+    if ! [[ "${TAG}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        continue
+    fi
+    if (($(date +%s) - CREATED < GRACE_DAYS * 86400)); then
+        echo "${TAG}: not merged yet, still within the ${GRACE_DAYS}-day grace period."
+    else
+        echo "${TAG}: not merged into develop."
+        MISSING=1
+    fi
+done <<<"${TAGS}"
+
+if [ "${MISSING}" -ne 0 ]; then
+    echo
+    echo "Merge the missing releases back into develop, see RELEASING.md."
+    exit 1
+fi
+echo "No releases past the grace period are missing from develop."
@@ -0,0 +1,12 @@
+# shellcheck shell=bash
+
+# Helpers shared by the release checks in this directory, see RELEASING.md.
+
+# Sets BRANCHES to all release and staging branches, and fails if there are none.
+load_release_branches() {
+    mapfile -t BRANCHES < <(git for-each-ref --format='%(refname)' 'refs/remotes/*/release/*' 'refs/remotes/*/staging/*')
+    if [ "${#BRANCHES[@]}" -eq 0 ]; then
+        echo "Error: No release or staging branches found."
+        exit 1
+    fi
+}
@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -49,7 +49,7 @@ ${SED_COMMAND} -i -E 's@ripple/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' BUILD.md
 ${SED_COMMAND} -i -E 's@xrpld \(`xrpld`\)@xrpld@g' BUILD.md
 ${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' CONTRIBUTING.md
-${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/build/install.md
+${SED_COMMAND} -i -E 's@XRPLF/xrpld@XRPLF/rippled@g' docs/install.md

 popd
 echo "Processing complete."
@@ -8,12 +8,12 @@ set -e
 SED_COMMAND=sed
 HEAD_COMMAND=head
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
    SED_COMMAND=gsed
-    if ! command -v ghead &> /dev/null; then
+    if ! command -v ghead &>/dev/null; then
        echo "Error: ghead is not installed. Please install it using 'brew install coreutils'."
        exit 1
    fi
@@ -43,9 +43,6 @@ pushd "${DIRECTORY}"
 # Rename the files.
 find cmake -type f -name 'Rippled*.cmake' -exec bash -c 'mv "${1}" "${1/Rippled/Xrpl}"' - {} \;
 find cmake -type f -name 'Ripple*.cmake' -exec bash -c 'mv "${1}" "${1/Ripple/Xrpl}"' - {} \;
-if [ -e cmake/xrpl_add_test.cmake ]; then
-    mv cmake/xrpl_add_test.cmake cmake/XrplAddTest.cmake
-fi
 if [ -e include/xrpl/proto/ripple.proto ]; then
    mv include/xrpl/proto/ripple.proto include/xrpl/proto/xrpl.proto
 fi
@@ -60,7 +57,6 @@ find cmake -type f -name '*.cmake' | while read -r FILE; do
 done
 ${SED_COMMAND} -i -E 's/Rippled?/Xrpl/g' CMakeLists.txt
 ${SED_COMMAND} -i 's/ripple/xrpl/g' CMakeLists.txt
-${SED_COMMAND} -i 's/include(xrpl_add_test)/include(XrplAddTest)/' src/tests/libxrpl/CMakeLists.txt
 ${SED_COMMAND} -i 's/ripple.pb.h/xrpl.pb.h/' include/xrpl/protocol/messages.h
 ${SED_COMMAND} -i 's/ripple.pb.h/xrpl.pb.h/' BUILD.md
 ${SED_COMMAND} -i 's/ripple.pb.h/xrpl.pb.h/' BUILD.md
@@ -74,10 +70,10 @@ if grep -q '"xrpld"' cmake/XrplCore.cmake; then
    # The script has been rerun, so just restore the name of the binary.
    ${SED_COMMAND} -i 's/"xrpld"/"rippled"/' cmake/XrplCore.cmake
 elif ! grep -q '"rippled"' cmake/XrplCore.cmake; then
-    ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake > cmake.tmp
-    echo '  # For the time being, we will keep the name of the binary as it was.' >> cmake.tmp
-    echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >> cmake.tmp
-    tail -1 cmake/XrplCore.cmake >> cmake.tmp
+    ${HEAD_COMMAND} -n -1 cmake/XrplCore.cmake >cmake.tmp
+    echo '  # For the time being, we will keep the name of the binary as it was.' >>cmake.tmp
+    echo '  set_target_properties(xrpld PROPERTIES OUTPUT_NAME "rippled")' >>cmake.tmp
+    tail -1 cmake/XrplCore.cmake >>cmake.tmp
    mv cmake.tmp cmake/XrplCore.cmake
 fi

@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -62,7 +62,7 @@ ${SED_COMMAND} -i 's@ripple/@xrpld/@g' src/test/core/Config_test.cpp
 ${SED_COMMAND} -i 's/Rippled/File/g' src/test/core/Config_test.cpp

 # Restore the old config file name in the code that maintains support for now.
-${SED_COMMAND} -i 's/kCONFIG_LEGACY_NAME = "xrpld.cfg"/kCONFIG_LEGACY_NAME = "rippled.cfg"/g' src/xrpld/core/detail/Config.cpp
+${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/g' src/xrpld/core/Config.h

 # Restore an URL.
 ${SED_COMMAND} -i 's/connect-your-xrpld-to-the-xrp-test-net.html/connect-your-rippled-to-the-xrp-test-net.html/g' cfg/xrpld-example.cfg
@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -62,37 +62,37 @@ done
 # restoring the verbiage that is already present in LICENSE.md. Ensure that if
 # the script is run multiple times, duplicate notices are not added.
 if ! grep -q 'Raw Material Software' include/xrpl/beast/core/CurrentThreadName.h; then
-    echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" > include/xrpl/beast/core/CurrentThreadName.h
+    echo -e "// Portions of this file are from JUCE (http://www.juce.com).\n// Copyright (c) 2013 - Raw Material Software Ltd.\n// Please visit http://www.juce.com\n\n$(cat include/xrpl/beast/core/CurrentThreadName.h)" >include/xrpl/beast/core/CurrentThreadName.h
 fi
 if ! grep -q 'Dev Null' src/test/app/NetworkID_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" > src/test/app/NetworkID_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/NetworkID_test.cpp)" >src/test/app/NetworkID_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/app/tx/apply_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" > src/test/app/tx/apply_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/app/tx/apply_test.cpp)" >src/test/app/tx/apply_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ManifestRPC_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" > src/test/rpc/ManifestRPC_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ManifestRPC_test.cpp)" >src/test/rpc/ManifestRPC_test.cpp
 fi
 if ! grep -q 'Dev Null' src/test/rpc/ValidatorInfo_test.cpp; then
-    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" > src/test/rpc/ValidatorInfo_test.cpp
+    echo -e "// Copyright (c) 2020 Dev Null Productions\n\n$(cat src/test/rpc/ValidatorInfo_test.cpp)" >src/test/rpc/ValidatorInfo_test.cpp
 fi
 if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/server_info/Manifest.cpp; then
-    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/server_info/Manifest.cpp)" > src/xrpld/rpc/handlers/server_info/Manifest.cpp
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/server_info/Manifest.cpp)" >src/xrpld/rpc/handlers/server_info/Manifest.cpp
 fi
 if ! grep -q 'Dev Null' src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp; then
-    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp)" > src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
+    echo -e "// Copyright (c) 2019 Dev Null Productions\n\n$(cat src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp)" >src/xrpld/rpc/handlers/admin/status/ValidatorInfo.cpp
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/SlabAllocator.h; then
-    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" > include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/SlabAllocator.h)" >include/xrpl/basics/SlabAllocator.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/spinlock.h; then
-    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/spinlock.h)" > include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2022, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/spinlock.h)" >include/xrpl/basics/spinlock.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Bougalis' include/xrpl/basics/tagged_integer.h; then
-    echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/tagged_integer.h)" > include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
+    echo -e "// Copyright (c) 2014, Nikolaos D. Bougalis <[email protected]>\n\n$(cat include/xrpl/basics/tagged_integer.h)" >include/xrpl/basics/tagged_integer.h # cspell: ignore Nikolaos Bougalis nikb
 fi
 if ! grep -q 'Ritchford' include/xrpl/beast/utility/Zero.h; then
-    echo -e "// Copyright (c) 2014, Tom Ritchford <[email protected]>\n\n$(cat include/xrpl/beast/utility/Zero.h)" > include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
+    echo -e "// Copyright (c) 2014, Tom Ritchford <[email protected]>\n\n$(cat include/xrpl/beast/utility/Zero.h)" >include/xrpl/beast/utility/Zero.h # cspell: ignore Ritchford
 fi

 # Restore newlines and tabs in string literals in the affected file.
@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -77,8 +77,8 @@ ${SED_COMMAND} -i 's/Ripple integrators/XRPL developers/' README.md
 ${SED_COMMAND} -i 's/sanitizer-configuration-for-rippled/sanitizer-configuration-for-xrpld/' docs/build/sanitizers.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/levelization/README.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' .github/scripts/strategy-matrix/generate.py
-${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/build/install.md
-${SED_COMMAND} -i '[email protected]/XRPLF/[email protected]/XRPLF/rippled@g' docs/build/install.md
+${SED_COMMAND} -i 's@/rippled@/xrpld@g' docs/install.md
+${SED_COMMAND} -i '[email protected]/XRPLF/[email protected]/XRPLF/rippled@g' docs/install.md
 ${SED_COMMAND} -i 's/rippled/xrpld/g' docs/Doxyfile
 ${SED_COMMAND} -i 's/ripple_basics/basics/' include/xrpl/basics/CountedObject.h
 ${SED_COMMAND} -i 's/<ripple/<xrpl/' include/xrpl/protocol/AccountID.h
@@ -90,7 +90,7 @@ ${SED_COMMAND} -i 's/www.ripple.com/www.xrpl.org/g' src/test/protocol/Seed_test.
 # Restore specific changes.
 ${SED_COMMAND} -i 's@b5efcc/src/xrpld@b5efcc/src/ripple@' include/xrpl/protocol/README.md
 ${SED_COMMAND} -i 's/dbPrefix_ = "xrpldb"/dbPrefix_ = "rippledb"/' src/xrpld/app/misc/SHAMapStoreImp.h # cspell: disable-line
-${SED_COMMAND} -i 's/kCONFIG_LEGACY_NAME = "xrpld.cfg"/kCONFIG_LEGACY_NAME = "rippled.cfg"/' src/xrpld/core/detail/Config.cpp
+${SED_COMMAND} -i 's/kConfigLegacyName = "xrpld.cfg"/kConfigLegacyName = "rippled.cfg"/' src/xrpld/core/Config.h

 popd
 echo "Renaming complete."
@@ -6,7 +6,7 @@ set -e
 # On MacOS, ensure that GNU sed is installed and available as `gsed`.
 SED_COMMAND=sed
 if [[ "${OSTYPE}" == 'darwin'* ]]; then
-    if ! command -v gsed &> /dev/null; then
+    if ! command -v gsed &>/dev/null; then
        echo "Error: gsed is not installed. Please install it using 'brew install gnu-sed'."
        exit 1
    fi
@@ -46,9 +46,6 @@ for DIRECTORY in "${DIRECTORIES[@]}"; do
    done
 done

-# Special case for NuDBFactory that has ripple twice in the test suite name.
-${SED_COMMAND} -i -E 's/(BEAST_DEFINE_TESTSUITE.+)ripple(.+)/\1xrpl\2/g' src/test/nodestore/NuDBFactory_test.cpp
-
 DIRECTORY=$1
 find "${DIRECTORY}" -type f -name "*.md" | while read -r FILE; do
    echo "Processing file: ${FILE}"
@@ -1,350 +1,401 @@
 #!/usr/bin/env python3
 import argparse
+import dataclasses
 import itertools
 import json
-from dataclasses import dataclass
 from pathlib import Path

 THIS_DIR = Path(__file__).parent.resolve()

+_BASE_CMAKE_ARGS = [
+    "-Dtests=ON",
+    "-Dwerr=ON",
+    "-Dxrpld=ON",
+    "-Dwextra=ON",
+]

-@dataclass
-class Config:
-    architecture: list[dict]
-    os: list[dict]
-    build_type: list[str]
-    cmake_args: list[str]
+# The package formats a config can be packaged as, each with its own
+# install-test job in reusable-package.yml.
+PACKAGE_TYPES = ("deb", "rpm")
+
+# The package name a variant suffixes, as build_pkg.py's BASE_NAME spells it:
+# the two have to agree, or the artifact globs miss what was built.
+BASE_NAME = "xrpld"
+
+# Maps sanitizer names (as used in cmake) to short config-name suffixes.
+_SANITIZER_SUFFIX: dict[str, str] = {
+    "address": "asan",
+    "undefinedbehavior": "ubsan",
+    "thread": "tsan",
+}


-"""
-Generate a strategy matrix for GitHub Actions CI.
-
-On each PR commit we will build a selection of Debian, RHEL, Ubuntu, MacOS, and
-Windows configurations, while upon merge into the develop or release branches,
-we will build all configurations, and test most of them.
-
-We will further set additional CMake arguments as follows:
- All builds will have the `tests`, `werr`, and `xrpld` options.
- All builds will have the `wextra` option except for GCC 12 and Clang 16.
- All release builds will have the `assert` option.
- Certain Debian Bookworm configurations will change the reference fee, enable
-  codecov, and enable voidstar in PRs.
-"""
+def config_name(
+    distro: str,
+    compiler: str,
+    build_type: str,
+    arch: str,
+    suffix: str = "",
+    sanitizer: str = "",
+) -> str:
+    """Name a config. Its artifacts are named after it, so packaging reuses this."""
+    parts = [s for s in [suffix, _SANITIZER_SUFFIX.get(sanitizer, "")] if s]
+    return "-".join([f"{distro}-{compiler}-{build_type.lower()}-{arch}", *parts])


-def generate_strategy_matrix(all: bool, config: Config) -> list:
-    configurations = []
-    for architecture, os, build_type, cmake_args in itertools.product(
-        config.architecture, config.os, config.build_type, config.cmake_args
-    ):
-        # The default CMake target is 'all' for Linux and MacOS and 'install'
-        # for Windows, but it can get overridden for certain configurations.
-        cmake_target = "install" if os["distro_name"] == "windows" else "all"
+def get_cmake_args(build_type: str, extra_args: str) -> str:
+    """Get the full list of CMake arguments for a config."""
+    args = _BASE_CMAKE_ARGS.copy()
+    if extra_args:
+        args.extend(extra_args.split())
+    return " ".join(args)

-        # We build and test all configurations by default, except for Windows in
-        # Debug, because it is too slow, as well as when code coverage is
-        # enabled as that mode already runs the tests.
-        build_only = False
-        if os["distro_name"] == "windows" and build_type == "Debug":
-            build_only = True

-        # Only generate a subset of configurations in PRs.
-        if not all:
-            # Debian:
-            # - Bookworm using GCC 13: Debug on linux/amd64, set the reference
-            #   fee to 500 and enable code coverage (which will be done below).
-            # - Bookworm using GCC 15: Debug on linux/amd64, enable Address and
-            #   UB sanitizers (which will be done below).
-            # - Bookworm using Clang 16: Debug on linux/amd64, enable voidstar.
-            # - Bookworm using Clang 17: Release on linux/amd64, set the
-            #   reference fee to 1000.
-            # - Bookworm using Clang 20: Debug on linux/amd64, enable Address
-            #   and UB sanitizers (which will be done below).
-            if os["distro_name"] == "debian":
-                skip = True
-                if os["distro_version"] == "bookworm":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-13"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-DUNIT_TEST_REFERENCE_FEE=500 {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-15"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-16"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-Dvoidstar=ON {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-17"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        cmake_args = f"-DUNIT_TEST_REFERENCE_FEE=1000 {cmake_args}"
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-20"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                if skip:
-                    continue
+# ---------------------------------------------------------------------------
+# Input types — shapes of the JSON config files
+# ---------------------------------------------------------------------------

-            # RHEL:
-            # - 9 using GCC 12: Debug on linux/amd64.
-            # - 10 using Clang: Release on linux/amd64.
-            if os["distro_name"] == "rhel":
-                skip = True
-                if os["distro_version"] == "9":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                elif os["distro_version"] == "10":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-any"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                if skip:
-                    continue

-            # Ubuntu:
-            # - Jammy using GCC 12: Debug on linux/arm64.
-            # - Noble using GCC 14: Release on linux/amd64.
-            # - Noble using Clang 18: Debug on linux/amd64.
-            # - Noble using Clang 19: Release on linux/arm64.
-            if os["distro_name"] == "ubuntu":
-                skip = True
-                if os["distro_version"] == "jammy":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/arm64"
-                    ):
-                        skip = False
-                elif os["distro_version"] == "noble":
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-14"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-18"
-                        and build_type == "Debug"
-                        and architecture["platform"] == "linux/amd64"
-                    ):
-                        skip = False
-                    if (
-                        f"{os['compiler_name']}-{os['compiler_version']}" == "clang-19"
-                        and build_type == "Release"
-                        and architecture["platform"] == "linux/arm64"
-                    ):
-                        skip = False
-                if skip:
-                    continue
+# Every config must declare 'minimal'. Minimal configs form the reduced matrix
+# built for pull requests by default; the full matrix adds the rest.
+#
+# Configs may also opt into 'benchmark' to smoke-run the benchmarks, or carry a
+# 'package' map to be packaged as well. Note that either applies to every entry
+# a config expands into, so only set them on configs that expand to a single
+# combination.

-            # MacOS:
-            # - Debug on macos/arm64.
-            if os["distro_name"] == "macos" and not (
-                build_type == "Debug" and architecture["platform"] == "macos/arm64"
-            ):
-                continue

-            # Windows:
-            # - Release on windows/amd64.
-            if os["distro_name"] == "windows" and not (
-                build_type == "Release" and architecture["platform"] == "windows/amd64"
-            ):
-                continue
+@dataclasses.dataclass
+class PackageConfig:
+    """The 'package' map of a config whose binaries are also packaged."""

-        # Additional CMake arguments.
-        cmake_args = f"{cmake_args} -Dtests=ON -Dwerr=ON -Dxrpld=ON"
-        if not f"{os['compiler_name']}-{os['compiler_version']}" in [
-            "gcc-12",
-            "clang-16",
-        ]:
-            cmake_args = f"{cmake_args} -Dwextra=ON"
-        if build_type == "Release":
-            cmake_args = f"{cmake_args} -Dassert=ON"
+    type: str  # has to match what the image provides
+    # The packaging container image: a vanilla distro image, not the nix image
+    # the config itself builds in.
+    image: str
+    # A flavour of the package, named xrpld-<variant>, for a config whose
+    # binaries are not the plain release build. A variant needs no counterpart
+    # in the other format.
+    variant: str = ""

-        # We skip all RHEL on arm64 due to a build failure that needs further
-        # investigation.
-        if os["distro_name"] == "rhel" and architecture["platform"] == "linux/arm64":
-            continue
-
-        # We skip all clang 20+ on arm64 due to Boost build error.
-        if (
-            f"{os['compiler_name']}-{os['compiler_version']}"
-            in ["clang-20", "clang-21"]
-            and architecture["platform"] == "linux/arm64"
-        ):
-            continue
-
-        # Enable code coverage for Debian Bookworm using GCC 13 in Debug on
-        # linux/amd64.
-        if (
-            f"{os['distro_name']}-{os['distro_version']}" == "debian-bookworm"
-            and f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-13"
-            and build_type == "Debug"
-            and architecture["platform"] == "linux/amd64"
-        ):
-            cmake_args = f"{cmake_args} -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
-
-        # Enable unity build for Ubuntu Jammy using GCC 12 in Debug on
-        # linux/amd64.
-        if (
-            f"{os['distro_name']}-{os['distro_version']}" == "ubuntu-jammy"
-            and f"{os['compiler_name']}-{os['compiler_version']}" == "gcc-12"
-            and build_type == "Debug"
-            and architecture["platform"] == "linux/amd64"
-        ):
-            cmake_args = f"{cmake_args} -Dunity=ON"
-
-        # Generate a unique name for the configuration, e.g. macos-arm64-debug
-        # or debian-bookworm-gcc-12-amd64-release.
-        config_name = os["distro_name"]
-        if (n := os["distro_version"]) != "":
-            config_name += f"-{n}"
-        if (n := os["compiler_name"]) != "":
-            config_name += f"-{n}"
-        if (n := os["compiler_version"]) != "":
-            config_name += f"-{n}"
-        config_name += (
-            f"-{architecture['platform'][architecture['platform'].find('/')+1:]}"
+    def __post_init__(self) -> None:
+        assert self.type in PACKAGE_TYPES, (
+            f"unsupported package type {self.type!r}: "
+            f"use one of {', '.join(PACKAGE_TYPES)}."
        )
-        config_name += f"-{build_type.lower()}"
-        if "-Dcoverage=ON" in cmake_args:
-            config_name += "-coverage"
-        if "-Dunity=ON" in cmake_args:
-            config_name += "-unity"

-        # Add the configuration to the list, with the most unique fields first,
-        # so that they are easier to identify in the GitHub Actions UI, as long
-        # names get truncated.
-        # Add Address and UB sanitizers as separate configurations for specific
-        # bookworm distros. Thread sanitizer is currently disabled (see below).
-        # GCC-Asan xrpld-embedded tests are failing because of https://github.com/google/sanitizers/issues/856
-        if os[
-            "distro_version"
-        ] == "bookworm" and f"{os['compiler_name']}-{os['compiler_version']}" in [
-            "gcc-15",
-            "clang-20",
-        ]:
-            # Add ASAN configuration.
-            configurations.append(
-                {
-                    "config_name": config_name + "-asan",
-                    "cmake_args": cmake_args,
-                    "cmake_target": cmake_target,
-                    "build_only": build_only,
-                    "build_type": build_type,
-                    "os": os,
-                    "architecture": architecture,
-                    "sanitizers": "address",
-                }
-            )
-            # Add UBSAN configuration.
-            configurations.append(
-                {
-                    "config_name": config_name + "-ubsan",
-                    "cmake_args": cmake_args,
-                    "cmake_target": cmake_target,
-                    "build_only": build_only,
-                    "build_type": build_type,
-                    "os": os,
-                    "architecture": architecture,
-                    "sanitizers": "undefinedbehavior",
-                }
-            )
-            # TSAN is deactivated due to seg faults with latest compilers.
-            activate_tsan = False
-            if activate_tsan:
-                configurations.append(
-                    {
-                        "config_name": config_name + "-tsan-ubsan",
-                        "cmake_args": cmake_args,
-                        "cmake_target": cmake_target,
-                        "build_only": build_only,
-                        "build_type": build_type,
-                        "os": os,
-                        "architecture": architecture,
-                        "sanitizers": "thread,undefinedbehavior",
-                    }
+
+@dataclasses.dataclass
+class LinuxConfig:
+    """One entry in a linux.json 'configs' array."""
+
+    compiler: list[str]
+    build_type: list[str]
+    arch: list[str]
+    minimal: bool
+    benchmark: bool = False  # if true, smoke-run the benchmarks after testing
+    sanitizers: list[str] = dataclasses.field(default_factory=list)
+    suffix: str = ""
+    extra_cmake_args: str = ""
+    package: PackageConfig | None = None  # set to also package this config
+
+    def __post_init__(self) -> None:
+        if isinstance(self.package, dict):
+            self.package = PackageConfig(**self.package)
+
+
+@dataclasses.dataclass
+class LinuxFile:
+    """Shape of linux.json."""
+
+    image_tag: str
+    configs: dict[str, list[LinuxConfig]]  # distro → configs
+
+    @classmethod
+    def load(cls, path: Path) -> "LinuxFile":
+        data = json.loads(path.read_text())
+        return cls(
+            image_tag=data["image_tag"],
+            configs={
+                distro: [LinuxConfig(**c) for c in cfgs]
+                for distro, cfgs in data["configs"].items()
+            },
+        )
+
+
+@dataclasses.dataclass
+class PlatformConfig:
+    """One entry in macos.json's or windows.json's 'configs' array."""
+
+    build_type: list[str]
+    minimal: bool
+    build_only: bool = False  # if true, skip tests (e.g. macos/Windows Debug)
+    benchmark: bool = False  # if true, smoke-run the benchmarks after testing
+    extra_cmake_args: str = ""
+    # "" is the runner's system compiler, "nix" the flake's CI environment.
+    # macOS only: Linux always builds in a Nix image, Windows has no Nix.
+    toolchain: str = ""
+
+    def __post_init__(self) -> None:
+        if isinstance(self.build_type, str):
+            self.build_type = [self.build_type]
+
+
+@dataclasses.dataclass
+class PlatformFile:
+    """Shape of macos.json and windows.json."""
+
+    platform: str  # e.g. "macos/arm64" or "windows/amd64"
+    runner: list[str]  # GitHub Actions runner labels
+    configs: list[PlatformConfig]
+
+    @classmethod
+    def load(cls, path: Path) -> "PlatformFile":
+        data = json.loads(path.read_text())
+        return cls(
+            platform=data["platform"],
+            runner=data["runner"],
+            configs=[PlatformConfig(**c) for c in data["configs"]],
+        )
+
+
+# ---------------------------------------------------------------------------
+# Output types — shapes of the generated GitHub Actions matrix entries
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class Architecture:
+    platform: str
+    runner: list[str]
+
+
+@dataclasses.dataclass
+class MatrixEntry:
+    """One entry in the generated build/test strategy matrix."""
+
+    config_name: str
+    cmake_args: str
+    cmake_target: str
+    build_only: bool
+    benchmark: bool
+    build_type: str
+    architecture: Architecture
+    sanitizers: str
+    image: str = ""  # container image; empty for macOS/Windows (runs natively)
+    compiler: str = ""  # compiler name ("gcc" or "clang"); empty for macOS/Windows
+    toolchain: str = ""  # "nix" for the flake's CI environment; see PlatformConfig
+
+
+@dataclasses.dataclass
+class PackagingEntry:
+    """One entry in the generated packaging strategy matrix."""
+
+    xrpld_artifact_name: str
+    validator_keys_artifact_name: str
+    image: str
+    package_type: str  # "deb" or "rpm"; drives the format-specific steps
+    package_variant: str  # passed to build_pkg.py --variant; empty for xrpld
+    package_name: str  # the name it builds under, which the artifact globs use
+
+
+# ---------------------------------------------------------------------------
+# Matrix expansion
+# ---------------------------------------------------------------------------
+
+_ARCHS: dict[str, Architecture] = {
+    "amd64": Architecture(
+        platform="linux/amd64", runner=["self-hosted", "Linux", "X64", "heavy"]
+    ),
+    "arm64": Architecture(
+        platform="linux/arm64",
+        runner=["self-hosted", "Linux", "ARM64", "heavy-arm64"],
+    ),
+}
+
+
+def expand_linux_matrix(linux: LinuxFile, minimal: bool) -> list[MatrixEntry]:
+    """Expand a LinuxFile into a flat list of matrix entries.
+
+    Each config entry is expanded over the cross-product of its
+    compiler, build_type, sanitizers, and architecture lists. When 'minimal' is
+    true, only configs flagged as minimal are included.
+    """
+    entries: list[MatrixEntry] = []
+
+    for distro, configs in linux.configs.items():
+        for cfg in configs:
+            if minimal and not cfg.minimal:
+                continue
+            # An empty sanitizers list means "one entry with no sanitizer".
+            effective_sanitizers = cfg.sanitizers or [""]
+            effective_archs = {arch: _ARCHS[arch] for arch in cfg.arch}
+
+            for compiler, build_type, sanitizer, (arch, arch_info) in itertools.product(
+                cfg.compiler,
+                cfg.build_type,
+                effective_sanitizers,
+                effective_archs.items(),
+            ):
+                name = config_name(
+                    distro, compiler, build_type, arch, cfg.suffix, sanitizer
+                )
+                entries.append(
+                    MatrixEntry(
+                        config_name=name,
+                        image=f"ghcr.io/xrplf/xrpld/nix-{distro}:{linux.image_tag}",
+                        cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
+                        cmake_target="all",
+                        build_only=False,
+                        benchmark=cfg.benchmark,
+                        build_type=build_type,
+                        architecture=arch_info,
+                        sanitizers=sanitizer,
+                        compiler=compiler,
+                    )
+                )
+
+    return entries
+
+
+def expand_linux_packaging(linux: LinuxFile) -> list[PackagingEntry]:
+    """Generate the packaging matrix from the configs that carry a 'package' map.
+
+    Packaging consumes the binaries that config's build job uploaded, so the
+    artifact names come from the same config name, and a packaged config is one
+    that passes -Dvalidator_keys=ON.
+
+    Packaging itself runs in vanilla distro images (debian:trixie, almalinux:10)
+    instead of the nix-based build images, because deb/rpm tooling (debhelper,
+    rpm-build) is taken from the distro's archive rather than from nixpkgs.
+    """
+    entries = []
+    for distro, configs in linux.configs.items():
+        for cfg in configs:
+            if cfg.package is None:
+                continue
+            for compiler, build_type, arch in itertools.product(
+                cfg.compiler, cfg.build_type, cfg.arch
+            ):
+                # The packaging workflow hardcodes an amd64 runner.
+                assert arch == "amd64", f"cannot package {distro} on {arch}"
+                name = config_name(distro, compiler, build_type, arch, cfg.suffix)
+                entries.append(
+                    PackagingEntry(
+                        xrpld_artifact_name=f"xrpld-{name}",
+                        validator_keys_artifact_name=f"validator-keys-{name}",
+                        image=cfg.package.image,
+                        package_type=cfg.package.type,
+                        package_variant=cfg.package.variant,
+                        package_name=(
+                            f"{BASE_NAME}-{cfg.package.variant}"
+                            if cfg.package.variant
+                            else BASE_NAME
+                        ),
+                    )
+                )
+
+    return entries
+
+
+def package_names_by_type(entries: list[PackagingEntry]) -> dict[str, list[str]]:
+    """The names of the packages in 'entries', keyed by format.
+
+    Derived from the packaging matrix rather than listed again, so the packages
+    the install-test jobs look for are the packages that were built.
+    """
+    return {
+        package_type: sorted(
+            {e.package_name for e in entries if e.package_type == package_type}
+        )
+        for package_type in PACKAGE_TYPES
+    }
+
+
+def expand_platform_matrix(pf: PlatformFile, minimal: bool) -> list[MatrixEntry]:
+    """Expand a PlatformFile (macOS or Windows) into matrix entries.
+
+    When 'minimal' is true, only configs flagged as minimal are included.
+    """
+    platform_name, arch = pf.platform.split("/")
+    is_windows = platform_name == "windows"
+
+    entries: list[MatrixEntry] = []
+    for cfg in pf.configs:
+        if minimal and not cfg.minimal:
+            continue
+        for build_type in cfg.build_type:
+            name = f"{platform_name}-{arch}-{build_type.lower()}"
+            if cfg.toolchain:
+                name += f"-{cfg.toolchain}"
+            entries.append(
+                MatrixEntry(
+                    config_name=name,
+                    cmake_args=get_cmake_args(build_type, cfg.extra_cmake_args),
+                    cmake_target="install" if is_windows else "all",
+                    build_only=cfg.build_only,
+                    benchmark=cfg.benchmark,
+                    build_type=build_type,
+                    architecture=Architecture(platform=pf.platform, runner=pf.runner),
+                    sanitizers="",
+                    toolchain=cfg.toolchain,
                )
-        else:
-            configurations.append(
-                {
-                    "config_name": config_name,
-                    "cmake_args": cmake_args,
-                    "cmake_target": cmake_target,
-                    "build_only": build_only,
-                    "build_type": build_type,
-                    "os": os,
-                    "architecture": architecture,
-                    "sanitizers": "",
-                }
            )
-
-    return configurations
+    return entries


-def read_config(file: Path) -> Config:
-    config = json.loads(file.read_text())
-    if (
-        config["architecture"] is None
-        or config["os"] is None
-        or config["build_type"] is None
-        or config["cmake_args"] is None
-    ):
-        raise Exception("Invalid configuration file.")
-
-    return Config(**config)
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------


 if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument(
-        "-a",
-        "--all",
-        help="Set to generate all configurations (generally used when merging a PR) or leave unset to generate a subset of configurations (generally used when committing to a PR).",
-        action="store_true",
+    parser = argparse.ArgumentParser(
+        description="Generate a CI strategy matrix for all platforms or a specific one."
    )
    parser.add_argument(
        "-c",
        "--config",
-        help="Path to the JSON file containing the strategy matrix configurations.",
-        required=False,
-        type=Path,
+        help="Platform to generate for ('linux', 'macos', or 'windows'). Defaults to all platforms.",
+        choices=["linux", "macos", "windows"],
+        default=None,
+    )
+    parser.add_argument(
+        "-p",
+        "--packaging",
+        help="Emit the Linux packaging matrix instead of the build/test matrix.",
+        action="store_true",
+    )
+    parser.add_argument(
+        "-m",
+        "--minimal",
+        help="Emit only the minimal matrix (the configs flagged 'minimal'), "
+        "used for pull requests by default. If omitted, the full matrix is "
+        "emitted.",
+        action="store_true",
    )
    args = parser.parse_args()

-    matrix = []
-    if args.config is None or args.config == "":
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "linux.json")
-        )
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "macos.json")
-        )
-        matrix += generate_strategy_matrix(
-            args.all, read_config(THIS_DIR / "windows.json")
-        )
-    else:
-        matrix += generate_strategy_matrix(args.all, read_config(args.config))
+    matrix: list[MatrixEntry] | list[PackagingEntry] = []

-    # Generate the strategy matrix.
-    print(f"matrix={json.dumps({'include': matrix})}")
+    if args.packaging:
+        matrix = expand_linux_packaging(LinuxFile.load(THIS_DIR / "linux.json"))
+        # One list per format, so each install-test job installs the packages its
+        # own format produced.
+        for package_type, names in package_names_by_type(matrix).items():
+            print(f"{package_type}_package_names={json.dumps(names)}")
+    else:
+        if args.config in ("linux", None):
+            matrix += expand_linux_matrix(
+                LinuxFile.load(THIS_DIR / "linux.json"), args.minimal
+            )
+        if args.config in ("macos", None):
+            matrix += expand_platform_matrix(
+                PlatformFile.load(THIS_DIR / "macos.json"), args.minimal
+            )
+        if args.config in ("windows", None):
+            matrix += expand_platform_matrix(
+                PlatformFile.load(THIS_DIR / "windows.json"), args.minimal
+            )
+
+    print(f"matrix={json.dumps({'include': [dataclasses.asdict(e) for e in matrix]})}")
@@ -1,212 +1,109 @@
 {
-  "architecture": [
-    {
-      "platform": "linux/amd64",
-      "runner": ["self-hosted", "Linux", "X64", "heavy"]
-    },
-    {
-      "platform": "linux/arm64",
-      "runner": ["self-hosted", "Linux", "ARM64", "heavy-arm64"]
-    }
-  ],
-  "os": [
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "gcc",
-      "compiler_version": "15",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "16",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "17",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "18",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "19",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "bookworm",
-      "compiler_name": "clang",
-      "compiler_version": "20",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "gcc",
-      "compiler_version": "15",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "clang",
-      "compiler_version": "20",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "debian",
-      "distro_version": "trixie",
-      "compiler_name": "clang",
-      "compiler_version": "21",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "8",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "8",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "9",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "10",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "rhel",
-      "distro_version": "10",
-      "compiler_name": "clang",
-      "compiler_version": "any",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "jammy",
-      "compiler_name": "gcc",
-      "compiler_version": "12",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "gcc",
-      "compiler_version": "13",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "gcc",
-      "compiler_version": "14",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "16",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "17",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "18",
-      "image_sha": "ab4d1f0"
-    },
-    {
-      "distro_name": "ubuntu",
-      "distro_version": "noble",
-      "compiler_name": "clang",
-      "compiler_version": "19",
-      "image_sha": "ab4d1f0"
-    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": [""]
+  "image_tag": "sha-3d526d4",
+  "configs": {
+    "ubuntu": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Debug"],
+        "arch": ["amd64"],
+        "minimal": true,
+        "suffix": "coverage",
+        "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=500 -Dcoverage=ON -Dcoverage_format=xml -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_C_FLAGS=-O0 -DCMAKE_CXX_FLAGS=-O0"
+      },
+      {
+        "compiler": ["clang"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": true,
+        "benchmark": true
+      },
+
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false
+      },
+      {
+        "compiler": ["gcc", "clang"],
+        "build_type": ["Debug", "Release"],
+        "arch": ["arm64"],
+        "minimal": false
+      },
+
+      {
+        "compiler": ["gcc", "clang"],
+        "build_type": ["Debug", "Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "sanitizers": ["address", "undefinedbehavior"]
+      },
+
+      {
+        "compiler": ["clang"],
+        "build_type": ["Debug"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "suffix": "voidstar",
+        "extra_cmake_args": "-Dvoidstar=ON"
+      },
+      {
+        "compiler": ["clang"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "suffix": "reffee",
+        "extra_cmake_args": "-DUNIT_TEST_REFERENCE_FEE=1000"
+      },
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Debug"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "suffix": "unity",
+        "extra_cmake_args": "-Dunity=ON"
+      }
+    ],
+
+    "debian": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "extra_cmake_args": "-Dvalidator_keys=ON",
+        "package": {
+          "type": "deb",
+          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-e6055dd"
+        }
+      },
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "suffix": "assert",
+        "extra_cmake_args": "-Dvalidator_keys=ON -Dassert=ON",
+        "package": {
+          "type": "deb",
+          "image": "ghcr.io/xrplf/xrpld/packaging-debian:sha-e6055dd",
+          "variant": "assert"
+        }
+      }
+    ],
+
+    "rhel": [
+      {
+        "compiler": ["gcc"],
+        "build_type": ["Release"],
+        "arch": ["amd64"],
+        "minimal": false,
+        "extra_cmake_args": "-Dvalidator_keys=ON",
+        "package": {
+          "type": "rpm",
+          "image": "ghcr.io/xrplf/xrpld/packaging-rhel:sha-e6055dd"
+        }
+      }
+    ]
+  }
 }
@@ -1,19 +1,30 @@
 {
-  "architecture": [
+  "platform": "macos/arm64",
+  "runner": ["self-hosted", "macOS", "ARM64", "macos-26-apple-clang-21"],
+  "configs": [
    {
-      "platform": "macos/arm64",
-      "runner": ["self-hosted", "macOS", "ARM64", "mac-runner-m1"]
-    }
-  ],
-  "os": [
+      "build_type": "Release",
+      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
+      "minimal": true
+    },
    {
-      "distro_name": "macos",
-      "distro_version": "",
-      "compiler_name": "",
-      "compiler_version": "",
-      "image_sha": ""
+      "build_type": "Debug",
+      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
+      "build_only": true,
+      "minimal": false
+    },
+    {
+      "build_type": "Release",
+      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
+      "toolchain": "nix",
+      "minimal": false
+    },
+    {
+      "build_type": "Debug",
+      "extra_cmake_args": "-DCMAKE_POLICY_VERSION_MINIMUM=3.5",
+      "toolchain": "nix",
+      "build_only": true,
+      "minimal": false
    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": ["-DCMAKE_POLICY_VERSION_MINIMUM=3.5"]
+  ]
 }
@@ -1,19 +1,12 @@
 {
-  "architecture": [
+  "platform": "windows/amd64",
+  "runner": ["self-hosted", "Windows", "dev-box-windows-2026"],
+  "configs": [
+    { "build_type": "Release", "minimal": true },
    {
-      "platform": "windows/amd64",
-      "runner": ["self-hosted", "Windows", "devbox"]
+      "build_type": "Debug",
+      "build_only": true,
+      "minimal": false
    }
-  ],
-  "os": [
-    {
-      "distro_name": "windows",
-      "distro_version": "",
-      "compiler_name": "",
-      "compiler_version": "",
-      "image_sha": ""
-    }
-  ],
-  "build_type": ["Debug", "Release"],
-  "cmake_args": [""]
+  ]
 }
@@ -0,0 +1,65 @@
+name: Build `nix` Docker images
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "rust-toolchain.toml"
+      - "nix/**"
+      - "!nix/docker/README.md"
+      - "!nix/devshell.nix"
+      - "!nix/check-tools/**"
+      - "bin/nix/default-loader-path.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"
+      - "!nix/check-tools/**"
+      - "bin/check-tools.sh"
+      - "bin/nix/default-loader-path.sh"
+      - "bin/install/sanitizer-libs.sh"
+  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 `nix-${{ matrix.distro.name }}` image
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # The base images are the oldest supported version of each distro
+        # that we want to build images for.
+        distro:
+          - name: nixos
+            base_image: nixos/nix:latest
+          - name: ubuntu
+            base_image: ubuntu:20.04
+          - name: debian
+            base_image: debian:bookworm
+          - name: rhel
+            base_image: registry.access.redhat.com/ubi9/ubi:latest
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@696384b292577293292daed06af0306d1b83bd7d
+    with:
+      image_name: xrpld/nix-${{ matrix.distro.name }}
+      dockerfile: nix/docker/Dockerfile
+      base_image: ${{ matrix.distro.base_image }}
+      push: ${{ github.event_name == 'push' }}
@@ -0,0 +1,48 @@
+name: Build `packaging` Docker images
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - "bin/install/packaging-tools.sh"
+      - "package/images/packaging/**"
+  pull_request:
+    paths:
+      - ".github/workflows/build-packaging-images.yml"
+      - "bin/install/packaging-tools.sh"
+      - "package/images/packaging/**"
+  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 `packaging-${{ matrix.distro.name }}` image
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        # Newest of each distro: these images only wrap pre-built binaries, so
+        # they set no floor for consumers. build_pkg.py pins the RPM dist tag.
+        distro:
+          - name: debian
+            base_image: debian:trixie
+          # AlmaLinux rather than UBI, which does not ship rpm-sign.
+          - name: rhel
+            base_image: almalinux:10
+    uses: XRPLF/actions/.github/workflows/build-multiarch-image.yml@696384b292577293292daed06af0306d1b83bd7d
+    with:
+      image_name: xrpld/packaging-${{ matrix.distro.name }}
+      dockerfile: package/images/packaging/Dockerfile
+      base_image: ${{ matrix.distro.base_image }}
+      push: ${{ github.event_name == 'push' }}
@@ -0,0 +1,37 @@
+name: Build `pre-commit` Docker image
+
+on:
+  push:
+    branches:
+      - develop
+    paths:
+      - "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@696384b292577293292daed06af0306d1b83bd7d
+    with:
+      image_name: xrpld/pre-commit
+      dockerfile: bin/pre-commit/Dockerfile
+      base_image: ubuntu:26.04
+      push: ${{ github.event_name == 'push' }}
@@ -0,0 +1,80 @@
+name: Cargo audit
+
+on:
+  schedule:
+    # 06:32 UTC every Monday.
+    - cron: "32 6 * * 1"
+  push:
+    branches:
+      - "develop"
+      - "release/*"
+    paths:
+      - "crates/**/Cargo.toml"
+      - "crates/Cargo.lock"
+      - ".github/workflows/cargo-audit.yml"
+  pull_request:
+    paths:
+      - "crates/**/Cargo.toml"
+      - "crates/Cargo.lock"
+      - ".github/workflows/cargo-audit.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+    working-directory: crates
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    permissions:
+      contents: read
+      # Needed to open an issue on scheduled failures.
+      issues: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Run cargo audit
+        id: audit
+        continue-on-error: true
+        run: |
+          set -o pipefail
+          cargo audit | tee /tmp/cargo-audit.txt
+
+      - name: Prepare issue body
+        if: ${{ steps.audit.outcome != 'success' && github.event_name == 'schedule' }}
+        run: |
+          {
+              echo "## \`cargo audit\` found advisories"
+              echo
+              echo '```'
+              cat /tmp/cargo-audit.txt
+              echo '```'
+              echo
+              echo "---"
+              echo "*This issue was automatically created by the cargo-audit workflow.*"
+          } >/tmp/cargo-audit-issue.md
+
+      - name: Create issue
+        if: ${{ steps.audit.outcome != 'success' && github.event_name == 'schedule' }}
+        uses: XRPLF/actions/create-issue@b489c21d53928f7dab4874912fec40e4f6c9e85e
+        with:
+          title: "cargo audit found vulnerabilities"
+          body_file: /tmp/cargo-audit-issue.md
+          labels: "Bug,Security"
+
+      - name: Fail if advisories were found
+        if: ${{ steps.audit.outcome != 'success' }}
+        run: |
+          echo "cargo audit found advisories!"
+          cat /tmp/cargo-audit.txt
+          exit 1
@@ -5,8 +5,16 @@ on:
    types:
      - checks_requested
  pull_request:
-    types: [opened, edited, reopened, synchronize, ready_for_review]
-    branches: [develop]
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+    branches:
+      - develop
+      - "release/*"
+      - "staging/*"

 jobs:
  check_description:
@@ -14,17 +22,17 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Write PR body to file
        env:
          PR_BODY: ${{ github.event.pull_request.body }}
        if: ${{ github.event_name == 'pull_request' }}
-        run: printenv PR_BODY > pr_body.md
+        run: printenv PR_BODY >pr_body.md

      - name: Check PR description differs from template
        if: ${{ github.event_name == 'pull_request' }}
-        run: >
-          python .github/scripts/check-pr-description.py
-          --template-file .github/pull_request_template.md
-          --pr-body-file pr_body.md
+        run: |
+          python .github/scripts/check-pr-description.py \
+              --template-file .github/pull_request_template.md \
+              --pr-body-file pr_body.md
@@ -5,10 +5,18 @@ on:
    types:
      - checks_requested
  pull_request:
-    types: [opened, edited, reopened, synchronize, ready_for_review]
-    branches: [develop]
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+    branches:
+      - develop
+      - "release/*"
+      - "staging/*"

 jobs:
  check_title:
    if: ${{ github.event.pull_request.draft != true }}
-    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@a5d8dd35be543365e90a11358447130c8763871d
+    uses: XRPLF/actions/.github/workflows/check-pr-title.yml@d7c65e49225a38f6d8010eacf017bb5a98d7476c
@@ -0,0 +1,60 @@
+# This workflow checks that every final release on a release branch
+# has been merged back into develop, see RELEASING.md.
+name: Check releases merged
+
+on:
+  schedule:
+    # 06:47 UTC every Monday.
+    - cron: "47 6 * * 1"
+  push:
+    branches:
+      - "develop"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  OUTPUT_FILE: /tmp/releases-merged.txt
+  ISSUE_FILE: /tmp/releases-merged-issue.md
+
+jobs:
+  releases-merged:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Needed to open an issue on scheduled failures.
+      issues: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # The check needs the full history of develop, the release branches and tags.
+          fetch-depth: 0
+
+      - name: Check releases are merged into develop
+        run: |
+          set -o pipefail
+          .github/scripts/releasing/check-releases-merged.sh origin/develop | tee "${OUTPUT_FILE}"
+
+      - name: Prepare issue body
+        if: ${{ failure() && github.event_name == 'schedule' && github.repository == 'XRPLF/rippled' }}
+        run: |
+          {
+              echo '```'
+              cat "${OUTPUT_FILE}"
+              echo '```'
+          } >"${ISSUE_FILE}"
+
+      - name: Create issue
+        if: ${{ failure() && github.event_name == 'schedule' && github.repository == 'XRPLF/rippled' }}
+        uses: XRPLF/actions/create-issue@b489c21d53928f7dab4874912fec40e4f6c9e85e
+        with:
+          title: "Releases not merged back into develop"
+          body_file: ${{ env.ISSUE_FILE }}
+          labels: "Bug"
@@ -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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - 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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
+        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@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: check-tools-${{ runner.os }}-${{ runner.arch }}
+          path: ${{ matrix.snapshot }}
@@ -14,10 +14,11 @@ permissions:

 jobs:
  main:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'IgnoreConflicts') }}
    runs-on: ubuntu-latest
    steps:
      - name: Check if PRs are dirty
-        uses: eps1lon/actions-label-merge-conflict@1df065ebe6e3310545d4f4c4e862e43bdca146f0 # v3.0.3
+        uses: eps1lon/actions-label-merge-conflict@0273be72a0bbd58fcd71d0d6c02c209b50d1e5e1 # v3.1.0
        with:
          dirtyLabel: "PR: has conflicts"
          repoToken: "${{ secrets.GITHUB_TOKEN }}"
@@ -1,7 +1,11 @@
-# This workflow runs all workflows to check, build and test the project on
-# various Linux flavors, as well as on MacOS and Windows, on every push to a
-# user branch. However, it will not run if the pull request is a draft unless it
-# has the 'DraftRunCI' label. For commits to PRs that target a release branch,
+# This workflow runs workflows to check, build and test the project
+# on every meaningful change on pull_request.
+# However, it will not run if the PR is a draft
+# unless it has the 'DraftRunCI' or 'Full CI build' label.
+#
+# By default a PR builds only a minimal matrix.
+# The full matrix runs once the PR is labeled "Ready to merge" or "Full CI build".
+# For commits to PRs that target a release branch,
 # it also uploads the libxrpl recipe to the Conan remote.
 name: PR

@@ -15,8 +19,16 @@ on:
      - reopened
      - synchronize
      - ready_for_review
+      # Trigger on label changes so toggling "Ready to merge" or "Full CI build"
+      # switches between the minimal and full matrix without needing a new push.
+      - labeled
+      - unlabeled

 concurrency:
+  # A single per-ref group with cancel-in-progress means any newer run (a push
+  # or a label change) supersedes the in-progress one for that ref. Keeping
+  # exactly one authoritative run per ref ensures a fast do-nothing run can never
+  # mask a real build's checks.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

@@ -25,15 +37,22 @@ defaults:
    shell: bash

 jobs:
-  # This job determines whether the rest of the workflow should run. It runs
-  # when the PR is not a draft (which should also cover merge-group) or
-  # has the 'DraftRunCI' label.
+  # This job determines whether the rest of the workflow should run at all,
+  # based on the current set of labels: it runs when the PR is not a draft
+  # (which should also cover merge-group) or has the 'DraftRunCI' or
+  # 'Full CI build' label. Whether a build then happens, and whether it is the
+  # minimal or full matrix, is decided further below and in the strategy matrix.
  should-run:
-    if: ${{ !github.event.pull_request.draft || contains(github.event.pull_request.labels.*.name, 'DraftRunCI') }}
+    if: >-
+      ${{
+        !github.event.pull_request.draft
+        || contains(github.event.pull_request.labels.*.name, 'DraftRunCI')
+        || contains(github.event.pull_request.labels.*.name, 'Full CI build')
+      }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Determine changed files
        # This step checks whether any files have changed that should
        # cause the next jobs to run. We do it this way rather than
@@ -58,22 +77,28 @@ jobs:

            # Keep the paths below in sync with those in `on-trigger.yml`.
            .github/actions/build-deps/**
-            .github/actions/build-test/**
-            .github/actions/generate-version/**
+            .github/actions/release-info/**
            .github/actions/setup-conan/**
+            .github/actions/setup-nix-env/**
            .github/scripts/strategy-matrix/**
-            .github/workflows/reusable-build.yml
            .github/workflows/reusable-build-test-config.yml
            .github/workflows/reusable-build-test.yml
+            .github/workflows/reusable-check-autogen.yml
            .github/workflows/reusable-clang-tidy.yml
-            .github/workflows/reusable-clang-tidy-files.yml
+            .github/workflows/reusable-package-test-install.yml
+            .github/workflows/reusable-package.yml
+            .github/workflows/reusable-rust.yml
            .github/workflows/reusable-strategy-matrix.yml
            .github/workflows/reusable-test.yml
            .github/workflows/reusable-upload-recipe.yml
            .clang-tidy
            .codecov.yml
+            bin/check-tools.sh
+            bin/nix/**
+            cfg/**
            cmake/**
            conan/**
+            crates/**
            external/**
            include/**
            src/**
@@ -81,25 +106,39 @@ jobs:
            CMakeLists.txt
            conanfile.py
            conan.lock
+            flake.lock
+            flake.nix
+            nix/**
+            LICENSE.md
+            package/**
+            README.md
+
      - name: Check whether to run
        # This step determines whether the rest of the workflow should
        # run. The rest of the workflow will run if this job runs AND at
        # least one of:
        # * Any of the files checked in the `changes` step were modified
        # * The PR is NOT a draft and is labeled "Ready to merge"
+        # * The PR is labeled "Full CI build" (draft or not)
        # * The workflow is running from the merge queue
        id: go
        env:
          FILES: ${{ steps.changes.outputs.any_changed }}
          DRAFT: ${{ github.event.pull_request.draft }}
          READY: ${{ contains(github.event.pull_request.labels.*.name, 'Ready to merge') }}
+          FULL: ${{ contains(github.event.pull_request.labels.*.name, 'Full CI build') }}
          MERGE: ${{ github.event_name == 'merge_group' }}
        run: |
-          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FILES == 'true' || env.MERGE == 'true' }}" >> "${GITHUB_OUTPUT}"
+          echo "go=${{ (env.DRAFT != 'true' && env.READY == 'true') || env.FULL == 'true' || env.FILES == 'true' || env.MERGE == 'true' }}" >>"${GITHUB_OUTPUT}"
          cat "${GITHUB_OUTPUT}"
    outputs:
      go: ${{ steps.go.outputs.go == 'true' }}

+  check-autogen:
+    needs: should-run
+    if: ${{ needs.should-run.outputs.go == 'true' }}
+    uses: ./.github/workflows/reusable-check-autogen.yml
+
  check-levelization:
    needs: should-run
    if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -110,6 +149,48 @@ jobs:
    if: ${{ needs.should-run.outputs.go == 'true' }}
    uses: ./.github/workflows/reusable-check-rename.yml

+  # Runs regardless of the changed files.
+  # PRs into staging branches are skipped, since fixes may be cherry-picked between release lines.
+  check-release-commits:
+    needs: should-run
+    if: ${{ github.event.pull_request.base.ref == 'develop' || github.event.merge_group.base_ref == 'refs/heads/develop' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # The check needs the full history of the release and staging branches.
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Check for copied release commits
+        if: ${{ github.event_name == 'pull_request' }}
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: .github/scripts/releasing/check-no-copied-release-commits.sh "${BASE}" "${HEAD}"
+      # Runs even if the previous check fails, so that both problems are reported at once.
+      - name: Check merge-back has no new commits
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: .github/scripts/releasing/check-merge-back-commits.sh "${BASE}" "${HEAD}"
+      # The queue squashes PRs, so check the PR's own branch, named in the queue branch.
+      - name: Check the merge queue doesn't merge a release back
+        if: ${{ github.event_name == 'merge_group' }}
+        env:
+          BASE: ${{ github.event.merge_group.base_sha }}
+          HEAD_REF: ${{ github.event.merge_group.head_ref }}
+        run: |
+          if ! [[ "${HEAD_REF}" =~ /pr-([0-9]+)-[0-9a-f]+$ ]]; then
+              echo "Error: Can't find the PR number in '${HEAD_REF}'."
+              exit 1
+          fi
+          git fetch --no-tags origin "refs/pull/${BASH_REMATCH[1]}/head"
+          .github/scripts/releasing/check-no-merge-back.sh "${BASE}" FETCH_HEAD
+
  clang-tidy:
    needs: should-run
    if: ${{ needs.should-run.outputs.go == 'true' }}
@@ -118,7 +199,6 @@ jobs:
      issues: write
      contents: read
    with:
-      check_only_changed: true
      create_issue_on_failure: false

  build-test:
@@ -137,6 +217,27 @@ jobs:
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

+  rust:
+    needs: should-run
+    if: ${{ needs.should-run.outputs.go == 'true' }}
+    uses: ./.github/workflows/reusable-rust.yml
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  package:
+    needs: [should-run, build-test]
+    # Packaging consumes the debian/rhel release binaries, which are only built
+    # by the full matrix. Skip it for pull requests that ran only the minimal
+    # matrix (i.e. not yet labeled "Ready to merge" or "Full CI build").
+    if: ${{ needs.should-run.outputs.go == 'true' && (github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'Ready to merge') || contains(github.event.pull_request.labels.*.name, 'Full CI build')) }}
+    uses: ./.github/workflows/reusable-package.yml
+    with:
+      # A pull request builds packages to prove they still build, and publishes
+      # nothing. Stated rather than left to the input's default, so that changing
+      # that default cannot start publishing from pull requests. No secrets are
+      # passed either, which is the second reason a publish here cannot succeed.
+      publish: false
+
  upload-recipe:
    needs:
      - should-run
@@ -145,8 +246,8 @@ jobs:
    if: ${{ github.repository == 'XRPLF/rippled' && needs.should-run.outputs.go == 'true' && github.event_name == 'pull_request' && startsWith(github.event.pull_request.base.ref, 'release') }}
    uses: ./.github/workflows/reusable-upload-recipe.yml
    secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
+      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}

  notify-clio:
    needs: upload-recipe
@@ -160,20 +261,24 @@ jobs:
          PR_URL: ${{ github.event.pull_request.html_url }}
        run: |
          gh api --method POST -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
-          /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
-          -F "client_payload[ref]=${{ needs.upload-recipe.outputs.recipe_ref }}" \
-          -F "client_payload[pr_url]=${PR_URL}"
+              /repos/xrplf/clio/dispatches -f "event_type=check_libxrpl" \
+              -F "client_payload[ref]=${{ needs.upload-recipe.outputs.recipe_ref }}" \
+              -F "client_payload[pr_url]=${PR_URL}"

  passed:
    if: failure() || cancelled()
    needs:
+      - check-autogen
      - check-levelization
      - check-rename
+      - check-release-commits
      - clang-tidy
      - build-test
+      - rust
+      - package
      - upload-recipe
      - notify-clio
    runs-on: ubuntu-latest
    steps:
      - name: Fail
-        run: false
+        run: exit 1
@@ -1,5 +1,12 @@
-# This workflow uploads the libxrpl recipe to the Conan remote when a versioned
-# tag is pushed.
+# When a versioned tag is pushed, this workflow:
+#
+#   - builds and tests the release binaries
+#   - uploads the libxrpl recipe to the Conan remote
+#   - builds the DEB and RPM packages
+#   - publishes those packages to the XRPLF package repositories
+#
+# Nothing is published unless the build passes, which is also where CMake
+# rejects a tag that is not a valid version, e.g. 3.2.01.
 name: Tag

 on:
@@ -18,7 +25,36 @@ defaults:
 jobs:
  upload-recipe:
    if: ${{ github.repository == 'XRPLF/rippled' }}
+    needs: build-test
    uses: ./.github/workflows/reusable-upload-recipe.yml
    secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
+      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
+
+  build-test:
+    if: ${{ github.repository_owner == 'XRPLF' }}
+    uses: ./.github/workflows/reusable-build-test.yml
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [linux]
+    with:
+      ccache_enabled: false
+      os: ${{ matrix.os }}
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  package:
+    if: ${{ github.repository_owner == 'XRPLF' }}
+    needs: build-test
+    uses: ./.github/workflows/reusable-package.yml
+    with:
+      publish: true
+    secrets:
+      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
+      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}
+      dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
+      antithesis_docker_host: ${{ secrets.ANTITHESIS_DOCKER_HOST }}
+      antithesis_docker_path: ${{ secrets.ANTITHESIS_DOCKER_PATH }}
+      antithesis_docker_credentials: ${{ secrets.ANTITHESIS_DOCKER_CREDENTIALS }}
@@ -15,22 +15,28 @@ on:

      # Keep the paths below in sync with those in `on-pr.yml`.
      - ".github/actions/build-deps/**"
-      - ".github/actions/build-test/**"
-      - ".github/actions/generate-version/**"
+      - ".github/actions/release-info/**"
      - ".github/actions/setup-conan/**"
+      - ".github/actions/setup-nix-env/**"
      - ".github/scripts/strategy-matrix/**"
-      - ".github/workflows/reusable-build.yml"
      - ".github/workflows/reusable-build-test-config.yml"
      - ".github/workflows/reusable-build-test.yml"
+      - ".github/workflows/reusable-check-autogen.yml"
      - ".github/workflows/reusable-clang-tidy.yml"
-      - ".github/workflows/reusable-clang-tidy-files.yml"
+      - ".github/workflows/reusable-package-test-install.yml"
+      - ".github/workflows/reusable-package.yml"
+      - ".github/workflows/reusable-rust.yml"
      - ".github/workflows/reusable-strategy-matrix.yml"
      - ".github/workflows/reusable-test.yml"
      - ".github/workflows/reusable-upload-recipe.yml"
      - ".clang-tidy"
      - ".codecov.yml"
+      - "bin/check-tools.sh"
+      - "bin/nix/**"
+      - "cfg/**"
      - "cmake/**"
      - "conan/**"
+      - "crates/**"
      - "external/**"
      - "include/**"
      - "src/**"
@@ -38,6 +44,12 @@ on:
      - "CMakeLists.txt"
      - "conanfile.py"
      - "conan.lock"
+      - "flake.lock"
+      - "flake.nix"
+      - "nix/**"
+      - "LICENSE.md"
+      - "package/**"
+      - "README.md"

  # Run at 06:32 UTC on every day of the week from Monday through Friday. This
  # will force all dependencies to be rebuilt, which is useful to verify that
@@ -63,13 +75,15 @@ defaults:
    shell: bash

 jobs:
+  check-autogen:
+    uses: ./.github/workflows/reusable-check-autogen.yml
+
  clang-tidy:
    uses: ./.github/workflows/reusable-clang-tidy.yml
    permissions:
      issues: write
      contents: read
    with:
-      check_only_changed: false
      create_issue_on_failure: ${{ github.event_name == 'schedule' }}

  build-test:
@@ -86,7 +100,11 @@ jobs:
      # not identical to a regular compilation.
      ccache_enabled: ${{ github.repository_owner == 'XRPLF' && !startsWith(github.ref, 'refs/heads/release') }}
      os: ${{ matrix.os }}
-      strategy_matrix: ${{ github.event_name == 'schedule' && 'all' || 'minimal' }}
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  rust:
+    uses: ./.github/workflows/reusable-rust.yml
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

@@ -96,5 +114,21 @@ jobs:
    if: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
    uses: ./.github/workflows/reusable-upload-recipe.yml
    secrets:
-      remote_username: ${{ secrets.CONAN_REMOTE_USERNAME }}
-      remote_password: ${{ secrets.CONAN_REMOTE_PASSWORD }}
+      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
+
+  package:
+    needs: build-test
+    uses: ./.github/workflows/reusable-package.yml
+    with:
+      # Packages are built on every trigger; only develop pushes in XRPLF/rippled
+      # publish them, matching upload-recipe above.
+      publish: ${{ github.repository == 'XRPLF/rippled' && github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
+    secrets:
+      remote_username: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+      remote_password: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
+      signing_key: ${{ secrets.NEXUS_PACKAGES_PRIVATE_KEY }}
+      dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
+      antithesis_docker_host: ${{ secrets.ANTITHESIS_DOCKER_HOST }}
+      antithesis_docker_path: ${{ secrets.ANTITHESIS_DOCKER_PATH }}
+      antithesis_docker_credentials: ${{ secrets.ANTITHESIS_DOCKER_CREDENTIALS }}
@@ -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@5e942d61bf32f7557a7c159cfac4712a687b3e3a
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@d7f2acb47d9662e1e2f8b1f5feffa6d21cc3290a
    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-70b8fd3" }'
@@ -41,13 +41,13 @@ env:
 jobs:
  build:
    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/ci/tools-rippled-documentation:sha-a8c7be1
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
        with:
          enable_ccache: false

@@ -57,19 +57,11 @@ jobs:
        with:
          subtract: ${{ env.NPROC_SUBTRACT }}

-      - name: Check configuration
-        run: |
-          echo 'Checking path.'
-          echo ${PATH} | tr ':' '\n'
+      - name: Print build environment
+        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574

-          echo 'Checking environment variables.'
-          env | sort
-
-          echo 'Checking CMake version.'
-          cmake --version
-
-          echo 'Checking Doxygen version.'
-          doxygen --version
+      - name: Check Doxygen version
+        run: doxygen --version

      - name: Build documentation
        env:
@@ -99,4 +91,4 @@ jobs:
    steps:
      - name: Deploy to GitHub Pages
        id: deploy
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
@@ -3,6 +3,12 @@ name: Build and test configuration
 on:
  workflow_call:
    inputs:
+      benchmark:
+        description: "Whether to smoke-run the benchmarks after testing."
+        required: false
+        type: boolean
+        default: false
+
      build_only:
        description: 'Whether to only build or to build and test the code ("true", "false").'
        required: true
@@ -57,6 +63,18 @@ on:
        type: string
        default: ""

+      compiler:
+        description: 'The compiler to use ("gcc" or "clang"). Leave empty for macOS/Windows (uses system default).'
+        required: false
+        type: string
+        default: ""
+
+      toolchain:
+        description: 'Where the toolchain comes from ("nix" to build the flake CI environment on the runner, empty for the system one). macOS only: Linux always builds in a Nix image, and Nix has no Windows support.'
+        required: false
+        type: string
+        default: ""
+
    secrets:
      CODECOV_TOKEN:
        description: "The Codecov token to use for uploading coverage reports."
@@ -76,7 +94,7 @@ jobs:
    name: ${{ inputs.config_name }}
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    container: ${{ inputs.image != '' && inputs.image || null }}
-    timeout-minutes: ${{ inputs.sanitizers != '' && 360 || 60 }}
+    timeout-minutes: ${{ inputs.sanitizers != '' && 360 || 180 }}
    env:
      # Use a namespace to keep the objects separate for each configuration.
      CCACHE_NAMESPACE: ${{ inputs.config_name }}
@@ -94,26 +112,40 @@ jobs:
      # header files are copied into separate directories by CMake, which will
      # otherwise result in cache misses.
      CCACHE_SLOPPINESS: include_file_ctime,include_file_mtime
-      # Determine if coverage and voidstar should be enabled.
+      # Determine if coverage, voidstar and validator-keys should be enabled.
      COVERAGE_ENABLED: ${{ contains(inputs.cmake_args, '-Dcoverage=ON') }}
      VOIDSTAR_ENABLED: ${{ contains(inputs.cmake_args, '-Dvoidstar=ON') }}
+      VALIDATOR_KEYS_ENABLED: ${{ contains(inputs.cmake_args, '-Dvalidator_keys=ON') }}
      SANITIZERS_ENABLED: ${{ inputs.sanitizers != '' }}
+      # The binaries reusable-package.yml consumes. A private repository skips
+      # them except on a tag push, which is what produces its release packages.
+      PACKAGING_ARTIFACTS_ENABLED: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
    steps:
      - name: Cleanup workspace (macOS and Windows)
        if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
        uses: XRPLF/actions/cleanup-workspace@c7d9ce5ebb03c752a354889ecd870cadfc2b1cd4

      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
        with:
          enable_ccache: ${{ inputs.ccache_enabled }}

+      # Before any step that uses a build tool, composite actions included.
+      - name: Setup Nix environment
+        if: ${{ inputs.toolchain == 'nix' }}
+        uses: ./.github/actions/setup-nix-env
+
      - name: Set ccache log file
        if: ${{ inputs.ccache_enabled && runner.debug == '1' }}
-        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >> "${GITHUB_ENV}"
+        run: echo "CCACHE_LOGFILE=${{ runner.temp }}/ccache.log" >>"${GITHUB_ENV}"
+
+      - name: Check tools
+        env:
+          CHECK_TOOLS_SKIP_CLONE: "1"
+        run: ./bin/check-tools.sh || true

      - name: Print build environment
        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
@@ -124,7 +156,27 @@ jobs:
        with:
          subtract: ${{ inputs.nproc_subtract }}

+      - name: Set compiler environment (Linux)
+        if: ${{ runner.os == 'Linux' }}
+        uses: ./.github/actions/set-compiler-env
+        with:
+          compiler: ${{ inputs.compiler }}
+
+      - name: Use cargo artifacts cache
+        uses: ./.github/actions/cargo-cache
+        with:
+          cache-directories: ${{ env.BUILD_DIR }}/corrosion
+          key: ${{ inputs.config_name }}
+          # two workspaces here because build artifacts are located in 2 places:
+          # - crates/target when cargo is called directly
+          # - build/cargo when cargo is called by cmake
+          workspaces: |
+            crates
+            crates -> ${{ runner.os == 'Windows' && format('../{0}/x64/{1}/cargo', env.BUILD_DIR, inputs.build_type) || format('../{0}/cargo', env.BUILD_DIR) }}
+
+      # `setup-nix-env` already did this for the Nix toolchain.
      - name: Setup Conan
+        if: ${{ inputs.toolchain != 'nix' }}
        env:
          SANITIZERS: ${{ inputs.sanitizers }}
        uses: ./.github/actions/setup-conan
@@ -134,50 +186,54 @@ jobs:
        with:
          build_nproc: ${{ steps.nproc.outputs.nproc }}
          build_type: ${{ inputs.build_type }}
-          # Set the verbosity to "quiet" for Windows to avoid an excessive
-          # amount of logs. For other OSes, the "verbose" logs are more useful.
-          log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
          sanitizers: ${{ inputs.sanitizers }}

      - name: Configure CMake
        working-directory: ${{ env.BUILD_DIR }}
        env:
          BUILD_TYPE: ${{ inputs.build_type }}
-          SANITIZERS: ${{ inputs.sanitizers }}
          CMAKE_ARGS: ${{ inputs.cmake_args }}
+          # GitHub creates a merge commit for a PR
+          # https://www.kenmuse.com/blog/the-many-shas-of-a-github-pull-request/
+          #
+          # We:
+          # - explicitly provide branch name
+          # - use `github.event.pull_request.head.sha` to get the SHA of last commit in the PR branch
+          #
+          # This way it works both for PRs and pushes to branches.
+          GITHUB_BRANCH_NAME: "${{ github.head_ref || github.ref_name }}"
+          GITHUB_HEAD_SHA: "${{ github.event.pull_request.head.sha || github.sha }}"
+          #
+          # If tag is being pushed, we use that version.
+          FORCE_XRPLD_VERSION: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
        run: |
          cmake \
-            -G '${{ runner.os == 'Windows' && 'Visual Studio 17 2022' || 'Ninja' }}' \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-            ${CMAKE_ARGS} \
-            ..
+              -G '${{ runner.os == 'Windows' && 'Visual Studio 18 2026' || 'Ninja' }}' \
+              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+              -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
+              ${CMAKE_ARGS} \
+              ..

-      - name: Check protocol autogen files are up-to-date
-        working-directory: ${{ env.BUILD_DIR }}
+      # Export the sanitizer options before any instrumented binary runs. The
+      # build step below invokes instrumented dependency tools (protoc, grpc),
+      # so setting UBSAN_OPTIONS here lets the UBSan suppression list silence
+      # their diagnostics too, not just at test time.
+      # GITHUB_WORKSPACE (not the github.workspace context) is used so the path
+      # resolves correctly inside the container job.
+      - name: Set sanitizer options
+        if: ${{ !inputs.build_only && env.SANITIZERS_ENABLED == 'true' }}
        env:
-          MESSAGE: |
-
-            The generated protocol wrapper classes are out of date.
-
-            This typically happens when the macro files or generator scripts
-            have changed but the generated files were not regenerated.
-
-            To fix this:
-              1. Run: cmake --build . --target setup_code_gen
-              2. Run: cmake --build . --target code_gen
-              3. Commit and push the regenerated files
+          CONFIG_NAME: ${{ inputs.config_name }}
        run: |
-          set -e
-          cmake --build . --target setup_code_gen
-          cmake --build . --target code_gen
-          DIFF=$(git -C .. status --porcelain -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen)
-          if [ -n "${DIFF}" ]; then
-            echo "::error::Generated protocol files are out of date"
-            git -C .. diff -- include/xrpl/protocol_autogen src/tests/libxrpl/protocol_autogen
-            echo "${MESSAGE}"
-            exit 1
+          SUPP="${GITHUB_WORKSPACE}/sanitizers/suppressions"
+          ASAN_OPTS="include=${SUPP}/runtime-asan-options.txt:suppressions=${SUPP}/asan.supp"
+          if [[ "${CONFIG_NAME}" == *gcc* ]]; then
+              ASAN_OPTS="${ASAN_OPTS}:alloc_dealloc_mismatch=0"
          fi
+          echo "ASAN_OPTIONS=${ASAN_OPTS}" >>${GITHUB_ENV}
+          echo "TSAN_OPTIONS=include=${SUPP}/runtime-tsan-options.txt:suppressions=${SUPP}/tsan.supp" >>${GITHUB_ENV}
+          echo "UBSAN_OPTIONS=include=${SUPP}/runtime-ubsan-options.txt:suppressions=${SUPP}/ubsan.supp" >>${GITHUB_ENV}
+          echo "LSAN_OPTIONS=include=${SUPP}/runtime-lsan-options.txt:suppressions=${SUPP}/lsan.supp" >>${GITHUB_ENV}

      - name: Build the binary
        working-directory: ${{ env.BUILD_DIR }}
@@ -186,40 +242,86 @@ 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}"
+              --build . \
+              --config "${BUILD_TYPE}" \
+              --parallel "${BUILD_NPROC}" \
+              --target "${CMAKE_TARGET}" \
+              2>&1 | tee "${GITHUB_WORKSPACE}/build.log"
+
+      # Nothing may reference the store, so whole trees are checked - the Conan
+      # cache included, since what it holds is what gets uploaded and reused.
+      - name: Check the build output for Nix store references (Nix toolchain)
+        if: ${{ inputs.toolchain == 'nix' }}
+        run: ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}"
+
+      - name: Check the Conan cache for Nix store references (Nix toolchain)
+        if: ${{ inputs.toolchain == 'nix' }}
+        run: ./bin/nix/check-nix-store-refs.sh "${CONAN_HOME}"
+
+      # Only what PatchNixBinary.cmake retargets: the toolchain in the Linux
+      # images always references the store. Same condition it uses.
+      - name: Check for Nix store references (Linux)
+        if: ${{ runner.os == 'Linux' && env.SANITIZERS_ENABLED == 'false' }}
+        run: |
+          ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpld"
+          ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpl_tests"
+          ./bin/nix/check-nix-store-refs.sh "${BUILD_DIR}/xrpld_tests"

      - name: Show ccache statistics
        if: ${{ inputs.ccache_enabled }}
        run: |
          ccache --show-stats -vv
          if [ '${{ runner.debug }}' = '1' ]; then
-            cat "${CCACHE_LOGFILE}"
-            curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
+              cat "${CCACHE_LOGFILE}"
+              curl ${CCACHE_REMOTE_STORAGE%|*}/status || true
          fi

      - name: Upload the binary (Linux)
-        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && runner.os == 'Linux' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: xrpld-${{ inputs.config_name }}
          path: ${{ env.BUILD_DIR }}/xrpld
          retention-days: 3
          if-no-files-found: error

+      - name: Run the validator-keys tests
+        if: ${{ env.VALIDATOR_KEYS_ENABLED == 'true' }}
+        working-directory: ${{ env.BUILD_DIR }}
+        run: ./validator-keys --unittest
+
+      - name: Upload the validator-keys binary
+        if: ${{ env.PACKAGING_ARTIFACTS_ENABLED == 'true' && env.VALIDATOR_KEYS_ENABLED == 'true' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: validator-keys-${{ inputs.config_name }}
+          path: |
+            ${{ env.BUILD_DIR }}/validator-keys
+            ${{ env.BUILD_DIR }}/validator-keys-LICENSE
+          retention-days: 3
+          if-no-files-found: error
+
+      - name: Upload the test binary (Linux)
+        if: ${{ github.event.repository.visibility == 'public' && runner.os == 'Linux' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: xrpl_tests-${{ inputs.config_name }}
+          path: ${{ env.BUILD_DIR }}/xrpl_tests
+          retention-days: 3
+          if-no-files-found: error
+
      - name: Export server definitions
        if: ${{ runner.os != 'Windows' && !inputs.build_only && env.VOIDSTAR_ENABLED != 'true' }}
        working-directory: ${{ env.BUILD_DIR }}
        run: |
          set -o pipefail
-          ./xrpld --definitions | python3 -m json.tool > server_definitions.json
+          ./xrpld --definitions | python3 -m json.tool >server_definitions.json

      - name: Upload server definitions
-        if: ${{ github.event.repository.visibility == 'public' && inputs.config_name == 'debian-bookworm-gcc-13-amd64-release' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: ${{ github.event.repository.visibility == 'public' && inputs.config_name == 'ubuntu-gcc-debug-amd64-coverage' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: server-definitions
          path: ${{ env.BUILD_DIR }}/server_definitions.json
@@ -232,10 +334,10 @@ jobs:
        run: |
          ldd ./xrpld
          if [ "$(ldd ./xrpld | grep -E '(libstdc\+\+|libgcc)' | wc -l)" -eq 0 ]; then
-            echo 'The binary is statically linked.'
+              echo 'The binary is statically linked.'
          else
-            echo 'The binary is dynamically linked.'
-            exit 1
+              echo 'The binary is dynamically linked.'
+              exit 1
          fi

      - name: Verify presence of instrumentation (Linux)
@@ -244,32 +346,12 @@ jobs:
        run: |
          ./xrpld --version | grep libvoidstar

-      - name: Set sanitizer options
-        if: ${{ !inputs.build_only && env.SANITIZERS_ENABLED == 'true' }}
-        env:
-          CONFIG_NAME: ${{ inputs.config_name }}
-        run: |
-          ASAN_OPTS="include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-asan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/asan.supp"
-          if [[ "${CONFIG_NAME}" == *gcc* ]]; then
-            ASAN_OPTS="${ASAN_OPTS}:alloc_dealloc_mismatch=0"
-          fi
-          echo "ASAN_OPTIONS=${ASAN_OPTS}" >> ${GITHUB_ENV}
-          echo "TSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-tsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/tsan.supp" >> ${GITHUB_ENV}
-          echo "UBSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/ubsan.supp" >> ${GITHUB_ENV}
-          echo "LSAN_OPTIONS=include=${GITHUB_WORKSPACE}/sanitizers/suppressions/runtime-lsan-options.txt:suppressions=${GITHUB_WORKSPACE}/sanitizers/suppressions/lsan.supp" >> ${GITHUB_ENV}
-
      - name: Run the separate tests
        if: ${{ !inputs.build_only }}
-        working-directory: ${{ env.BUILD_DIR }}
-        # Windows locks some of the build files while running tests, and parallel jobs can collide
-        env:
-          BUILD_TYPE: ${{ inputs.build_type }}
-          PARALLELISM: ${{ runner.os == 'Windows' && '1' || steps.nproc.outputs.nproc }}
+        working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
        run: |
-          ctest \
-            --output-on-failure \
-            -C "${BUILD_TYPE}" \
-            -j "${PARALLELISM}"
+          ./xrpl_tests
+          ./xrpld_tests

      - name: Run the embedded tests
        if: ${{ !inputs.build_only }}
@@ -279,20 +361,76 @@ jobs:
        run: |
          set -o pipefail
          # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness
-          [ "$COVERAGE_ENABLED" = "true" ] && BUILD_NPROC=$(( BUILD_NPROC - 2 ))
-          ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee unittest.log
+          [ "$COVERAGE_ENABLED" = "true" ] && BUILD_NPROC=$((BUILD_NPROC - 2))

-      - name: Show test failure summary
-        if: ${{ failure() && !inputs.build_only }}
-        working-directory: ${{ runner.os == 'Windows' && format('{0}/{1}', env.BUILD_DIR, inputs.build_type) || env.BUILD_DIR }}
-        run: |
-          if [ ! -f unittest.log ]; then
-            echo "unittest.log not found; embedded tests may not have run."
-            exit 0
+          # The resolver/preload workaround is only correct for the ASan build:
+          # a regular build doesn't hit the __dn_expand interceptor bug, and must
+          # NOT have libasan injected. So only preload when xrpld is ASan-built.
+          #
+          # libresolv hosts getaddrinfo's resolver helpers (dn_expand, res_*). Under ASan
+          # these are intercepted via dlsym(RTLD_NEXT, ...), which yields a NULL pointer
+          # and crashes DNS resolution if libresolv isn't loaded. Linking it guarantees
+          # the symbols are present; it's a harmless no-op on glibc >= 2.34 (merged into
+          # libc) and is what the compiler driver already does for sanitizer builds.
+          #   https://github.com/llvm/llvm-project/issues/59007
+          #   https://github.com/google/sanitizers/issues/1592
+          if ldd ./xrpld | grep -q libasan; then
+              PRELOAD="$(gcc -print-file-name=libasan.so):/usr/lib/x86_64-linux-gnu/libresolv.so.2"
+          else
+              PRELOAD=""
          fi

-          if ! grep -E "failed" unittest.log; then
-            echo "Log present but no failure lines found in unittest.log."
+          LD_PRELOAD="$PRELOAD" ./xrpld --unittest --unittest-jobs "${BUILD_NPROC}" 2>&1 | tee "${GITHUB_WORKSPACE}/unittest.log"
+
+      - name: Run Rust tests
+        if: ${{ !inputs.build_only }}
+        working-directory: crates
+        # `xrpl-wasm-vm-ffi` is left out on Windows: its tests link as an executable, and
+        # MSVC - unlike the Unix linkers - will not dead-strip the never-called cxx wrappers
+        # whose C++ shims only the CMake build defines. The other runners cover these tests.
+        run: cargo nextest run --workspace --all-features --locked --no-tests=warn ${{ runner.os == 'Windows' && '--exclude xrpl-wasm-vm-ffi' || '' }}
+
+      # Smoke-run every benchmark module with a single repetition to confirm the
+      # benchmarks still build and execute. This is a correctness check, not a
+      # performance measurement, so there is nothing to gain from repeating it
+      # across configurations: it is opted into by a single config in the
+      # strategy matrix (see the 'benchmark' flag in the JSON files), which
+      # keeps it off instrumented builds (sanitizers/coverage/voidstar), where
+      # it would be slow and meaningless, off Debug builds, where it is much
+      # slower, and off Windows, where the `install` target does not build them.
+      - name: Run the benchmarks
+        if: ${{ inputs.benchmark }}
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          rc=0
+          while IFS= read -r bench; do
+              echo "::group::${bench}"
+              "./${bench}" --benchmark_repetitions=1 || rc=1
+              echo "::endgroup::"
+          done < <(find src/benchmarks -type f -perm -u+x -name 'xrpl.bench.*')
+          exit "${rc}"
+
+      - name: Show build/test failure summary
+        if: ${{ failure() }}
+        run: |
+          cd "${GITHUB_WORKSPACE}"
+
+          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 }}
@@ -310,19 +448,20 @@ jobs:
          BUILD_TYPE: ${{ inputs.build_type }}
        run: |
          cmake \
-            --build . \
-            --config "${BUILD_TYPE}" \
-            --parallel "${BUILD_NPROC}" \
-            --target coverage
+              --build . \
+              --config "${BUILD_TYPE}" \
+              --parallel "${BUILD_NPROC}" \
+              --target coverage

      - name: Upload coverage report
-        if: ${{ github.repository == 'XRPLF/rippled' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        if: ${{ github.repository_owner == 'XRPLF' && !inputs.build_only && env.COVERAGE_ENABLED == 'true' }}
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
        with:
          disable_search: true
          disable_telem: true
          fail_ci_if_error: true
          files: ${{ env.BUILD_DIR }}/coverage.xml
+          flags: cpp
          plugins: noop
          token: ${{ secrets.CODECOV_TOKEN }}
          verbose: true
@@ -19,13 +19,6 @@ on:
        required: true
        type: string

-      strategy_matrix:
-        # TODO: Support additional strategies, e.g. "ubuntu" for generating all Ubuntu configurations.
-        description: 'The strategy matrix to use for generating the configurations ("minimal", "all").'
-        required: false
-        type: string
-        default: "minimal"
-
    secrets:
      CODECOV_TOKEN:
        description: "The Codecov token to use for uploading coverage reports."
@@ -37,7 +30,6 @@ jobs:
    uses: ./.github/workflows/reusable-strategy-matrix.yml
    with:
      os: ${{ inputs.os }}
-      strategy_matrix: ${{ inputs.strategy_matrix }}

  # Build and test the binary for each configuration.
  build-test-config:
@@ -47,16 +39,18 @@ jobs:
    strategy:
      fail-fast: ${{ github.event_name == 'merge_group' }}
      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-      max-parallel: 10
    with:
+      benchmark: ${{ matrix.benchmark }}
      build_only: ${{ matrix.build_only }}
      build_type: ${{ matrix.build_type }}
      ccache_enabled: ${{ inputs.ccache_enabled }}
      cmake_args: ${{ matrix.cmake_args }}
      cmake_target: ${{ matrix.cmake_target }}
      runs_on: ${{ toJSON(matrix.architecture.runner) }}
-      image: ${{ contains(matrix.architecture.platform, 'linux') && format('ghcr.io/xrplf/ci/{0}-{1}:{2}-{3}-sha-{4}', matrix.os.distro_name, matrix.os.distro_version, matrix.os.compiler_name, matrix.os.compiler_version, matrix.os.image_sha) || '' }}
+      image: ${{ matrix.image || '' }}
      config_name: ${{ matrix.config_name }}
      sanitizers: ${{ matrix.sanitizers }}
+      compiler: ${{ matrix.compiler || '' }}
+      toolchain: ${{ matrix.toolchain || '' }}
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
@@ -0,0 +1,76 @@
+# This workflow checks that the generated protocol wrapper classes are
+# up-to-date with the macro files and generator scripts they are produced from,
+# see more info in include/xrpl/protocol_autogen/README.md.
+name: Check autogen
+
+# This workflow can only be triggered by other workflows.
+on: workflow_call
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-autogen
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  BUILD_DIR: build/codegen
+
+jobs:
+  autogen:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      # Code generation is pure Python, so the standalone project below offers
+      # the same targets as the main build without needing its dependencies or
+      # a compiler, which keeps this job down to a few seconds.
+      - name: Configure CMake
+        run: cmake -S cmake/codegen -B "${BUILD_DIR}"
+
+      - name: Install code generation dependencies
+        run: cmake --build "${BUILD_DIR}" --target setup_code_gen
+
+      - name: Generate code
+        run: cmake --build "${BUILD_DIR}" --target code_gen
+
+      - name: Check for differences
+        env:
+          MESSAGE: |
+
+            The generated protocol wrapper classes are out of date.
+
+            This typically happens when the macro files or generator scripts
+            have changed but the generated files were not regenerated.
+
+            Run the following from the repository root, then commit and push
+            the regenerated files. This needs neither the dependencies nor a
+            compiler. See include/xrpl/protocol_autogen/README.md for more info.
+
+              cmake -S cmake/codegen -B build/codegen
+              cmake --build build/codegen --target setup_code_gen
+              cmake --build build/codegen --target code_gen
+
+            In an already configured build directory, the 'setup_code_gen' and
+            'code_gen' targets do the same thing.
+        run: |
+          # Record untracked files in the index without staging their contents,
+          # so that classes generated for a newly added transaction or ledger
+          # entry type show up in the diff below rather than silently as an
+          # empty one.
+          git add --intent-to-add .
+          DIFF=$(git status --porcelain)
+          if [ -n "${DIFF}" ]; then
+              # Print the differences to give the contributor a hint about what to
+              # expect when running code generation on their own machine.
+              git diff
+              echo "${MESSAGE}"
+              exit 1
+          fi
@@ -18,7 +18,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Check levelization
        run: python .github/scripts/levelization/generate.py
      - name: Check for differences
@@ -38,9 +38,9 @@ jobs:
        run: |
          DIFF=$(git status --porcelain)
          if [ -n "${DIFF}" ]; then
-            # Print the differences to give the contributor a hint about what to
-            # expect when running levelization on their own machine.
-            git diff
-            echo "${MESSAGE}"
-            exit 1
+              # Print the differences to give the contributor a hint about what to
+              # expect when running levelization on their own machine.
+              git diff
+              echo "${MESSAGE}"
+              exit 1
          fi
@@ -18,7 +18,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Check definitions
        run: .github/scripts/rename/definitions.sh .
      - name: Check copyright notices
@@ -48,9 +48,9 @@ jobs:
        run: |
          DIFF=$(git status --porcelain)
          if [ -n "${DIFF}" ]; then
-            # Print the differences to give the contributor a hint about what to
-            # expect when running the renaming scripts on their own machine.
-            git diff
-            echo "${MESSAGE}"
-            exit 1
+              # Print the differences to give the contributor a hint about what to
+              # expect when running the renaming scripts on their own machine.
+              git diff
+              echo "${MESSAGE}"
+              exit 1
          fi
@@ -1,175 +0,0 @@
-name: Run clang-tidy on files
-
-on:
-  workflow_call:
-    inputs:
-      files:
-        description: "List of files to check (empty means check all files)"
-        type: string
-        default: ""
-      create_issue_on_failure:
-        description: "Whether to create an issue if the check failed"
-        type: boolean
-        default: false
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  # Conan installs the generators in the build/generators directory, see the
-  # layout() method in conanfile.py. We then run CMake from the build directory.
-  BUILD_DIR: build
-  BUILD_TYPE: Debug # Debug so that ASSERTS and such participate in clang-tidy check
-
-jobs:
-  run-clang-tidy:
-    name: Run clang tidy
-    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
-    container: "ghcr.io/xrplf/ci/debian-trixie:clang-21-sha-53033a2"
-    permissions:
-      issues: write
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
-        with:
-          enable_ccache: false
-
-      - name: Print build environment
-        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
-
-      - name: Get number of processors
-        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
-        id: nproc
-
-      - name: Setup Conan
-        uses: ./.github/actions/setup-conan
-
-      - name: Build dependencies
-        uses: ./.github/actions/build-deps
-        with:
-          build_nproc: ${{ steps.nproc.outputs.nproc }}
-          build_type: ${{ env.BUILD_TYPE }}
-          log_verbosity: verbose
-
-      - name: Configure CMake
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          cmake \
-            -G 'Ninja' \
-            -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
-            -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
-            -Dtests=ON \
-            -Dwerr=ON \
-            -Dxrpld=ON \
-            ..
-
-      # clang-tidy needs headers generated from proto files
-      - name: Build libxrpl.libpb
-        working-directory: ${{ env.BUILD_DIR }}
-        run: |
-          ninja -j ${{ steps.nproc.outputs.nproc }} xrpl.libpb
-
-      - name: Run clang tidy
-        id: run_clang_tidy
-        continue-on-error: true
-        env:
-          TARGETS: ${{ inputs.files != '' && inputs.files || 'src tests' }}
-        run: |
-          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "${BUILD_DIR}" -quiet -fix -allow-no-checks ${TARGETS} 2>&1 | tee clang-tidy-output.txt
-
-      - name: Upload clang-tidy output
-        if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: clang-tidy-results
-          path: clang-tidy-output.txt
-          retention-days: 30
-
-      - name: Generate git diff
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          git diff | tee clang-tidy-git-diff.txt
-
-      - name: Upload clang-tidy diff output
-        if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: clang-tidy-git-diff
-          path: clang-tidy-git-diff.txt
-          retention-days: 30
-
-      - name: Create an issue
-        if: ${{ steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure }}
-        id: create_issue
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          # Prepare issue body with clang-tidy output
-          cat > issue.md <<EOF
-          ## Clang-tidy Check Failed
-
-          **Workflow:** ${{ github.workflow }}
-          **Run ID:** ${{ github.run_id }}
-          **Commit:** ${{ github.sha }}
-          **Branch/Ref:** ${{ github.ref }}
-          **Triggered by:** ${{ github.actor }}
-
-          ### Clang-tidy Output:
-          \`\`\`
-          EOF
-
-          # Append clang-tidy output (filter for errors and warnings)
-          if [ -f clang-tidy-output.txt ]; then
-            # Extract lines containing 'error:', 'warning:', or 'note:'
-            grep -E '(error:|warning:|note:)' clang-tidy-output.txt > filtered-output.txt || true
-
-            # If filtered output is empty, use original (might be a different error format)
-            if [ ! -s filtered-output.txt ]; then
-              cp clang-tidy-output.txt filtered-output.txt
-            fi
-
-            # Truncate if too large
-            head -c 60000 filtered-output.txt >> issue.md
-            if [ "$(wc -c < filtered-output.txt)" -gt 60000 ]; then
-              echo "" >> issue.md
-              echo "... (output truncated, see artifacts for full output)" >> issue.md
-            fi
-
-            rm filtered-output.txt
-          else
-            echo "No output file found" >> issue.md
-          fi
-
-          cat >> issue.md <<EOF
-          \`\`\`
-
-          **Workflow run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-          ---
-          *This issue was automatically created by the clang-tidy workflow.*
-          EOF
-
-          # Create the issue
-          gh issue create \
-            --label "Bug,Clang-tidy" \
-            --title "Clang-tidy check failed" \
-            --body-file ./issue.md \
-            > create_issue.log
-
-          created_issue="$(sed 's|.*/||' create_issue.log)"
-          echo "created_issue=$created_issue" >> $GITHUB_OUTPUT
-          echo "Created issue #$created_issue"
-
-          rm -f create_issue.log issue.md clang-tidy-output.txt
-
-      - name: Fail the workflow if clang-tidy failed
-        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        run: |
-          echo "Clang-tidy check failed!"
-          exit 1
@@ -1,12 +1,8 @@
-name: Clang-tidy check
+name: Run clang-tidy on files

 on:
  workflow_call:
    inputs:
-      check_only_changed:
-        description: "Check only changed files in PR. If false, checks all files in the repository."
-        type: boolean
-        default: false
      create_issue_on_failure:
        description: "Whether to create an issue if the check failed"
        type: boolean
@@ -16,40 +12,187 @@ defaults:
  run:
    shell: bash

+env:
+  BUILD_DIR: build
+  BUILD_TYPE: Debug # Debug so that ASSERTS and such participate in clang-tidy check
+
+  OUTPUT_FILE: /tmp/clang-tidy-output.txt
+  FILTERED_OUTPUT_FILE: /tmp/clang-tidy-filtered-output.txt
+  DIFF_FILE: /tmp/clang-tidy-git-diff.txt
+  ISSUE_FILE: /tmp/clang-tidy-issue.md
+
+  COMPILER: clang
+
 jobs:
  determine-files:
-    name: Determine files to check
-    if: ${{ inputs.check_only_changed }}
-    runs-on: ubuntu-latest
-    outputs:
-      clang_tidy_config_changed: ${{ steps.changed_clang_tidy.outputs.any_changed }}
-      any_cpp_changed: ${{ steps.changed_files.outputs.any_changed }}
-      all_changed_files: ${{ steps.changed_files.outputs.all_changed_files }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get changed C++ files
-        id: changed_files
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            **/*.cpp
-            **/*.h
-            **/*.ipp
-          separator: " "
-
-      - name: Get changed clang-tidy configuration
-        id: changed_clang_tidy
-        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
-        with:
-          files: |
-            .clang-tidy
+    permissions:
+      contents: read
+    uses: XRPLF/actions/.github/workflows/determine-tidy-files.yml@70145243b905dc3e040a61d39c00e178cfb96f71

  run-clang-tidy:
+    name: Run clang tidy
    needs: [determine-files]
-    if: ${{ always() && !cancelled() && (!inputs.check_only_changed || needs.determine-files.outputs.any_cpp_changed == 'true' || needs.determine-files.outputs.clang_tidy_config_changed == 'true') }}
-    uses: ./.github/workflows/reusable-clang-tidy-files.yml
-    with:
-      files: ${{ (needs.determine-files.outputs.clang_tidy_config_changed != 'true' && inputs.check_only_changed) && needs.determine-files.outputs.all_changed_files || '' }}
-      create_issue_on_failure: ${{ inputs.create_issue_on_failure }}
+    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-3d526d4"
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
+        with:
+          enable_ccache: false
+
+      - name: Print build environment
+        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574
+
+      - name: Get number of processors
+        uses: XRPLF/actions/get-nproc@cf0433aa74563aead044a1e395610c96d65a37cf
+        id: nproc
+
+      - name: Set compiler environment
+        uses: ./.github/actions/set-compiler-env
+        with:
+          compiler: ${{ env.COMPILER }}
+
+      - name: Use cargo artifacts cache
+        uses: ./.github/actions/cargo-cache
+        with:
+          cache-directories: ${{ env.BUILD_DIR }}/corrosion
+          workspaces: crates -> ../${{ env.BUILD_DIR }}/cargo
+
+      - name: Setup Conan
+        uses: ./.github/actions/setup-conan
+
+      - name: Build dependencies
+        uses: ./.github/actions/build-deps
+        with:
+          build_nproc: ${{ steps.nproc.outputs.nproc }}
+          build_type: ${{ env.BUILD_TYPE }}
+
+      - name: Configure CMake
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          cmake \
+              -G 'Ninja' \
+              -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+              -DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
+              -Dtests=ON \
+              -Dwerr=ON \
+              -Dxrpld=ON \
+              -Dverify_headers=ON \
+              ..
+
+      - name: Build clang-tidy prerequisites
+        working-directory: ${{ env.BUILD_DIR }}
+        run: |
+          ninja -j ${{ steps.nproc.outputs.nproc }} tidy_prerequisites
+
+      - name: Run clang tidy
+        id: run_clang_tidy
+        continue-on-error: true
+        env:
+          TARGETS: ${{ needs.determine-files.outputs.need_full_run != 'true' && needs.determine-files.outputs.cpp_changed_files || 'include src tests' }}
+        run: |
+          set -o pipefail
+          run-clang-tidy -j ${{ steps.nproc.outputs.nproc }} -p "${BUILD_DIR}" -quiet -fix -format -allow-no-checks ${TARGETS} 2>&1 | tee "${OUTPUT_FILE}"
+
+      - name: Print filtered clang-tidy errors
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          bin/filter-clang-tidy.py "${OUTPUT_FILE}"
+
+      - name: Upload clang-tidy output
+        if: ${{ github.event.repository.visibility == 'public' && steps.run_clang_tidy.outcome != 'success' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          path: ${{ env.OUTPUT_FILE }}
+          archive: false
+          retention-days: 30
+
+      - name: Check for changes
+        id: files_changed
+        continue-on-error: true
+        run: |
+          git diff --exit-code
+
+      - name: Fix style
+        if: ${{ steps.files_changed.outcome != 'success' }}
+        run: |
+          pre-commit run --all-files || true
+
+      - name: Generate git diff
+        if: ${{ steps.files_changed.outcome != 'success' }}
+        run: |
+          git diff | tee "${DIFF_FILE}"
+
+      - name: Upload clang-tidy diff output
+        if: ${{ github.event.repository.visibility == 'public' && steps.files_changed.outcome != 'success' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          path: ${{ env.DIFF_FILE }}
+          archive: false
+          retention-days: 30
+
+      - name: Write issue header
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          cat >"${ISSUE_FILE}" <<EOF
+          ## Clang-tidy Check Failed
+
+          ### Clang-tidy Output:
+          \`\`\`
+          EOF
+
+      - name: Append filtered clang-tidy output to issue body
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          if [ -f "${OUTPUT_FILE}" ]; then
+              # Filter to the unique errors with their source context.
+              bin/filter-clang-tidy.py "${OUTPUT_FILE}" >"${FILTERED_OUTPUT_FILE}" || true
+
+              # If filtered output is empty, use original (might be a different error format)
+              if [ ! -s "${FILTERED_OUTPUT_FILE}" ]; then
+                  cp "${OUTPUT_FILE}" "${FILTERED_OUTPUT_FILE}"
+              fi
+
+              # Truncate if too large
+              head -c 60000 "${FILTERED_OUTPUT_FILE}" >>"${ISSUE_FILE}"
+              if [ "$(wc -c <"${FILTERED_OUTPUT_FILE}")" -gt 60000 ]; then
+                  echo "" >>"${ISSUE_FILE}"
+                  echo "... (output truncated, see artifacts for full output)" >>"${ISSUE_FILE}"
+              fi
+
+              rm "${FILTERED_OUTPUT_FILE}"
+          else
+              echo "No output file found" >>"${ISSUE_FILE}"
+          fi
+
+      - name: Append issue footer
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          cat >>"${ISSUE_FILE}" <<EOF
+          \`\`\`
+
+          ---
+          *This issue was automatically created by the clang-tidy workflow.*
+          EOF
+
+      - name: Create issue
+        if: ${{ steps.run_clang_tidy.outcome != 'success' && inputs.create_issue_on_failure }}
+        uses: XRPLF/actions/create-issue@b489c21d53928f7dab4874912fec40e4f6c9e85e
+        with:
+          title: "Clang-tidy check failed"
+          body_file: ${{ env.ISSUE_FILE }}
+          labels: "Bug,Clang-tidy"
+          assignees: "godexsoft,mathbunnyru"
+
+      - name: Fail if clang-tidy found issues
+        if: ${{ steps.run_clang_tidy.outcome != 'success' }}
+        run: |
+          echo "Clang-tidy check failed!"
+          exit 1
@@ -0,0 +1,120 @@
+# Install one package format on every distro family it targets, one job per
+# package name and image, and run the binaries there. Called once per format by
+# reusable-package.yml, which owns the names and the image lists.
+name: Install packages
+
+on:
+  workflow_call:
+    inputs:
+      package_type:
+        description: 'The package format to install ("deb" or "rpm").'
+        required: true
+        type: string
+      package_names:
+        description: "JSON array of package names built for this format."
+        required: true
+        type: string
+      images:
+        description: "JSON array of container images to install in."
+        required: true
+        type: string
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  PACKAGE_DIR: packages
+
+jobs:
+  install:
+    strategy:
+      fail-fast: false
+      matrix:
+        package_name: ${{ fromJson(inputs.package_names) }}
+        image: ${{ fromJson(inputs.images) }}
+    name: "${{ matrix.package_name }} on ${{ matrix.image }}"
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    timeout-minutes: 5
+
+    steps:
+      # Every package lands in one directory; the step below picks its own,
+      # which keeps this independent of the artifact names.
+      - name: Download package artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "*-pkg"
+          merge-multiple: true
+          path: ${{ env.PACKAGE_DIR }}
+
+      - name: Find the package
+        id: find
+        env:
+          PACKAGE_NAME: ${{ matrix.package_name }}
+          PACKAGE_TYPE: ${{ inputs.package_type }}
+        run: |
+          # The version follows the name, separated by '_' in a DEB and '-' in an
+          # RPM. Requiring a digit after it is what keeps 'xrpld' from picking up
+          # another package, such as 'xrpld-assert'.
+          pattern="${PACKAGE_NAME}[_-][0-9]*.${PACKAGE_TYPE}"
+          package="$(find "${PACKAGE_DIR}" -type f -name "${pattern}" -print -quit)"
+          test -n "${package}" || {
+              echo "no ${pattern} found in ${PACKAGE_DIR}" >&2
+              exit 1
+          }
+          echo "package=${package}" >>"${GITHUB_OUTPUT}"
+
+      # Debian 11 went end-of-life on 2026-08-31
+      # (https://www.debian.org/News/2026/20260831) and its packages are
+      # already partly gone from deb.debian.org, so switch to the
+      # snapshot.debian.org entries the image ships commented out in its
+      # sources.list: they are pinned to the snapshot the image was built
+      # from, so they serve every version it needs and never go away.
+      # Snapshots keep their original, long-passed Valid-Until, hence the
+      # disabled check; the retries absorb snapshot.debian.org's throttling.
+      - name: Switch Debian 11 to snapshot.debian.org
+        if: ${{ matrix.image == 'debian:11' }}
+        run: |
+          sed -i 's|^deb |# deb |; s|^# deb http://snapshot|deb http://snapshot|' /etc/apt/sources.list
+          printf '%s\n' \
+              'Acquire::Check-Valid-Until "false";' \
+              'Acquire::Retries "3";' \
+              >/etc/apt/apt.conf.d/99snapshot
+
+      - name: Install the DEB
+        if: ${{ inputs.package_type == 'deb' }}
+        env:
+          DEBIAN_FRONTEND: noninteractive
+          PACKAGE: ${{ steps.find.outputs.package }}
+        run: |
+          # Stock Debian and Ubuntu images carry no package lists, so apt has
+          # nothing to resolve the systemd dependency from until it fetches them.
+          apt-get update -qq
+          apt-get install -y "./${PACKAGE}"
+
+      - name: Install the RPM
+        if: ${{ inputs.package_type == 'rpm' }}
+        env:
+          PACKAGE: ${{ steps.find.outputs.package }}
+        run: dnf install -y "./${PACKAGE}"
+
+      - name: Run xrpld
+        run: xrpld --version
+
+      - name: Run validator-keys
+        run: validator-keys --version
+
+      - name: Run rippled, the legacy compatibility symlink
+        run: rippled --version
+
+      - name: Check the service account
+        run: id xrpld
+
+      - name: Check the state directory
+        run: test -d /var/lib/xrpld
+
+      - name: Check the log directory
+        run: test -d /var/log/xrpld
@@ -0,0 +1,348 @@
+# Build, verify and publish Linux packages from the pre-built xrpld and
+# validator-keys artifacts, in these stages:
+#
+#   - 'package' builds and signs one format per config that carries a "package"
+#     map in linux.json; that map names the container image and the format
+#   - 'test-install-deb' and 'test-install-rpm' call
+#     reusable-package-test-install.yml to install what was built on a range of
+#     distros and run the binaries there, so a package that cannot be installed
+#     never reaches Nexus
+#   - 'publish' uploads with the image's publish_pkg.py, doing a --dry-run
+#     unless 'publish: true'
+#   - 'docker' builds an Ubuntu image from the tested DEB, and one with the
+#     voidstar binary for Antithesis, pushing them to Docker Hub and to the
+#     Antithesis registry only with 'publish: true'
+#
+# Only linux/amd64 is supported; the runner is hardcoded in the jobs below.
+name: Package
+
+on:
+  workflow_call:
+    inputs:
+      publish:
+        description: "Whether to publish the packages after building them."
+        required: false
+        type: boolean
+        default: false
+      nexus_url:
+        description: "The base URL of the Nexus instance hosting the deb and rpm repositories."
+        required: false
+        type: string
+        default: https://packages-upload.xrplf.org
+
+    secrets:
+      remote_username:
+        description: "The username of a Nexus account with write access to the repositories."
+        required: false
+      remote_password:
+        description: "The password or token for that Nexus account."
+        required: false
+      signing_key:
+        description: "Armoured PGP private key used to sign the RPMs."
+        required: false
+      dockerhub_token:
+        description: "A Docker Hub organization access token for xrplf, with push access to xrplf/xrpld."
+        required: false
+      antithesis_docker_host:
+        description: "The host of the Antithesis container registry, e.g. us-central1-docker.pkg.dev."
+        required: false
+      antithesis_docker_path:
+        description: "The repository path in that registry, the image name excluded."
+        required: false
+      antithesis_docker_credentials:
+        description: "The JSON key of a service account with push access to that repository."
+        required: false
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  BUILD_DIR: build
+  PACKAGE_DIR: packages
+
+jobs:
+  generate-matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+      deb_package_names: ${{ steps.generate.outputs.deb_package_names }}
+      rpm_package_names: ${{ steps.generate.outputs.rpm_package_names }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Generate packaging matrix
+        id: generate
+        working-directory: .github/scripts/strategy-matrix
+        run: ./generate.py --packaging >>"${GITHUB_OUTPUT}"
+
+  package:
+    needs: [generate-matrix]
+    if: ${{ github.event.repository.visibility == 'public' || startsWith(github.ref, 'refs/tags/') }}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
+    name: "${{ matrix.xrpld_artifact_name }}"
+    permissions:
+      contents: read
+    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
+    container: ${{ matrix.image }}
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
+        with:
+          enable_ccache: false
+
+      - name: Download pre-built xrpld binary
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: ${{ matrix.xrpld_artifact_name }}
+          path: ${{ env.BUILD_DIR }}
+
+      - name: Download pre-built validator-keys binary
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: ${{ matrix.validator_keys_artifact_name }}
+          path: ${{ env.BUILD_DIR }}
+
+      - name: Make binaries executable
+        run: chmod +x "${BUILD_DIR}/xrpld" "${BUILD_DIR}/validator-keys"
+
+      - name: Determine release info
+        id: release_info
+        uses: ./.github/actions/release-info
+
+      - name: Build package
+        env:
+          PACKAGE_TYPE: ${{ matrix.package_type }}
+          PACKAGE_VARIANT: ${{ matrix.package_variant }}
+          PKG_RELEASE: ${{ steps.release_info.outputs.pkg_release }}
+          CHANNEL: ${{ steps.release_info.outputs.channel }}
+        run: |
+          ./package/build_pkg.py \
+              --package-type "${PACKAGE_TYPE}" \
+              --build-dir "${BUILD_DIR}" \
+              --pkg-release "${PKG_RELEASE}" \
+              --variant "${PACKAGE_VARIANT}" \
+              --channel "${CHANNEL}"
+
+      # Before the upload, so the artifact, the tested package and the published
+      # package are the same bytes.
+      - name: Sign RPM
+        if: ${{ inputs.publish && matrix.package_type == 'rpm' }}
+        env:
+          PKG_SIGNING_KEY: ${{ secrets.signing_key }}
+        run: ./package/sign_rpm.py --package-dir "${BUILD_DIR}"
+
+      # Split from the debug symbols, which are an order of magnitude larger, so
+      # that test-install downloads only what it installs. In the globs below the
+      # version follows the name, separated by '_' in a DEB and '-' in an RPM. A
+      # version starts with a digit and a longer name does not, so that one digit
+      # is what tells 'xrpld-3.4.1-...' from 'xrpld-assert-3.4.1-...'.
+      - name: Upload package artifact
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: ${{ matrix.xrpld_artifact_name }}-pkg
+          path: |
+            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}_[0-9]*.deb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-[0-9]*.rpm
+          if-no-files-found: error
+
+      - name: Upload debug symbol artifact
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: ${{ matrix.xrpld_artifact_name }}-pkg-debug
+          path: |
+            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.deb
+            ${{ env.BUILD_DIR }}/debbuild/${{ matrix.package_name }}-dbgsym_[0-9]*.ddeb
+            ${{ env.BUILD_DIR }}/rpmbuild/RPMS/**/${{ matrix.package_name }}-debuginfo-[0-9]*.rpm
+          if-no-files-found: error
+
+  # One call per format, so a variant packaged for one format is installed for
+  # that format alone. The images are every distro family that format targets,
+  # oldest release first, so both ends of the dependency range the packages
+  # declare are exercised.
+  test-install-deb:
+    needs: [generate-matrix, package]
+    name: install deb
+    uses: ./.github/workflows/reusable-package-test-install.yml
+    with:
+      package_type: deb
+      package_names: ${{ needs.generate-matrix.outputs.deb_package_names }}
+      images: |
+        [
+          "debian:11",
+          "debian:12",
+          "debian:13",
+          "ubuntu:20.04",
+          "ubuntu:22.04",
+          "ubuntu:24.04",
+          "ubuntu:26.04"
+        ]
+
+  test-install-rpm:
+    needs: [generate-matrix, package]
+    name: install rpm
+    uses: ./.github/workflows/reusable-package-test-install.yml
+    with:
+      package_type: rpm
+      package_names: ${{ needs.generate-matrix.outputs.rpm_package_names }}
+      images: |
+        [
+          "almalinux:9",
+          "almalinux:10",
+          "rockylinux/rockylinux:9",
+          "rockylinux/rockylinux:10",
+          "registry.access.redhat.com/ubi9/ubi",
+          "registry.access.redhat.com/ubi10/ubi"
+        ]
+
+  publish:
+    needs: [generate-matrix, package, test-install-deb, test-install-rpm]
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
+    name: "publish ${{ matrix.xrpld_artifact_name }}${{ !inputs.publish && ' (dry run)' || '' }}"
+    permissions:
+      contents: read
+    runs-on: ["self-hosted", "Linux", "X64", "heavy"]
+    container: ${{ matrix.image }}
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
+        with:
+          enable_ccache: false
+
+      # Both artifacts, so the debug symbols are published alongside the package.
+      - name: Download package artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: ${{ matrix.xrpld_artifact_name }}-pkg*
+          merge-multiple: true
+          path: ${{ env.PACKAGE_DIR }}
+
+      - name: Determine release info
+        id: release_info
+        uses: ./.github/actions/release-info
+
+      - name: Publish package
+        env:
+          CHANNEL: ${{ steps.release_info.outputs.channel }}
+          DRY_RUN_OPTION: ${{ !inputs.publish && '--dry-run' || '' }}
+          NEXUS_URL: ${{ inputs.nexus_url }}
+          NEXUS_USERNAME: ${{ inputs.publish && secrets.remote_username || '' }}
+          NEXUS_PASSWORD: ${{ inputs.publish && secrets.remote_password || '' }}
+        run: |
+          publish_pkg.py \
+              --channel "${CHANNEL}" \
+              --package-dir "${PACKAGE_DIR}" \
+              --nexus-url "${NEXUS_URL}" \
+              ${DRY_RUN_OPTION}
+
+  docker:
+    needs: [test-install-deb, test-install-rpm]
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [xrpld, voidstar]
+    name: "docker ${{ matrix.target }}${{ !inputs.publish && ' (dry run)' || '' }}"
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      CONTEXT: image-context
+      IMAGE: ${{ matrix.target == 'voidstar' && 'xrpld-voidstar' || 'xrplf/xrpld' }}:${{ github.ref_type == 'tag' && github.ref_name || 'develop' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Determine release info
+        id: release_info
+        uses: ./.github/actions/release-info
+
+      # Docker Hub is public, so it only gets builds whose packages are public:
+      # those of a public codebase, and stable releases.
+      # The Antithesis registry is private, so it gets every build.
+      - name: Decide whether to push
+        env:
+          PUSH: ${{ inputs.publish && (matrix.target == 'voidstar' || github.event.repository.visibility == 'public' || steps.release_info.outputs.channel == 'stable') }}
+        run: echo "PUSH=${PUSH}" | tee -a "${GITHUB_ENV}"
+
+      - name: Download package artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "*-pkg"
+          merge-multiple: true
+          path: ${{ env.PACKAGE_DIR }}
+
+      - name: Download voidstar binary
+        if: ${{ matrix.target == 'voidstar' }}
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: xrpld-ubuntu-clang-debug-amd64-voidstar
+          path: ${{ env.CONTEXT }}
+
+      - name: Build image
+        env:
+          TARGET: ${{ matrix.target }}
+        run: |
+          mkdir -p "${CONTEXT}"
+          find "${PACKAGE_DIR}" -type f -name 'xrpld_[0-9]*.deb' -exec cp {} "${CONTEXT}/" \;
+          docker build --pull --file package/images/xrpld/Dockerfile --target "${TARGET}" --tag "${IMAGE}" "${CONTEXT}"
+
+      - name: Start the server
+        run: |
+          container="$(docker run --detach "${IMAGE}" --standalone --silent --conf /etc/xrpld/xrpld.cfg)"
+          trap 'docker rm --force "${container}" >/dev/null' EXIT
+
+          for _ in $(seq 30); do
+              output="$(docker exec "${container}" xrpld --conf /etc/xrpld/xrpld.cfg server_info || true)"
+              if [[ "${output}" == *'"status" : "success"'* ]]; then
+                  exit 0
+              fi
+              sleep 2
+          done
+
+          docker logs "${container}"
+          exit 1
+
+      - name: Log in to Docker Hub
+        if: ${{ env.PUSH == 'true' && matrix.target == 'xrpld' }}
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          username: xrplf
+          password: ${{ secrets.dockerhub_token }}
+
+      - name: Log in to the Antithesis registry
+        if: ${{ env.PUSH == 'true' && matrix.target == 'voidstar' }}
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ${{ secrets.antithesis_docker_host }}
+          username: _json_key
+          password: ${{ secrets.antithesis_docker_credentials }}
+
+      - name: Push image
+        if: ${{ env.PUSH == 'true' }}
+        env:
+          REGISTRY: ${{ matrix.target == 'voidstar' && format('{0}/{1}/', secrets.antithesis_docker_host, secrets.antithesis_docker_path) || '' }}
+        run: |
+          docker tag "${IMAGE}" "${REGISTRY}${IMAGE}"
+          docker push "${REGISTRY}${IMAGE}"
@@ -0,0 +1,84 @@
+# Clippy, coverage and documentation for the Rust crates in crates/. Each runs
+# as an independent job on a GitHub-hosted runner, but inside the same container
+# image used to build the crates in the C++/Corrosion path, so the toolchain
+# (and therefore the lints and the cargo cache) matches what production builds
+# use. Coverage is the exception: it needs the nightly rustc that honours
+# #[coverage(off)], which the image carries alongside the pinned stable.
+#
+# Rust unit tests are deliberately NOT run here. They run as part of the C++
+# build (reusable-build-test-config.yml), which already compiles the crates on a
+# self-hosted runner, so there is no need to provision a toolchain again.
+name: Rust
+
+on:
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        description: "The Codecov token to use for uploading coverage reports."
+        required: true
+
+defaults:
+  run:
+    shell: bash
+    working-directory: crates
+
+permissions:
+  contents: read
+
+jobs:
+  clippy:
+    runs-on: ubuntu-latest
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Use cargo artifacts cache
+        uses: ./.github/actions/cargo-cache
+
+      - name: Run clippy
+        run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
+
+  coverage:
+    runs-on: ubuntu-latest
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Use the nightly Rust toolchain
+        run: rust-nightly path >>"${GITHUB_PATH}"
+
+      - name: Use cargo artifacts cache
+        uses: ./.github/actions/cargo-cache
+
+      - name: Generate coverage report
+        run: cargo llvm-cov nextest --workspace --all-features --locked --no-tests=warn --lcov --output-path lcov.info
+
+      - name: Upload coverage report
+        if: ${{ github.repository == 'XRPLF/rippled' }}
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          disable_search: true
+          disable_telem: true
+          fail_ci_if_error: true
+          files: crates/lcov.info
+          flags: rust
+          plugins: noop
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
+
+  doc:
+    runs-on: ubuntu-latest
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Use cargo artifacts cache
+        uses: ./.github/actions/cargo-cache
+
+      - name: Build documentation
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+        run: cargo doc --workspace --no-deps --all-features --locked
@@ -4,15 +4,9 @@ on:
  workflow_call:
    inputs:
      os:
-        description: 'The operating system to use for the build ("linux", "macos", "windows").'
+        description: 'The operating system to use for the build ("linux", "macos", "windows", or empty for all).'
        required: false
        type: string
-      strategy_matrix:
-        # TODO: Support additional strategies, e.g. "ubuntu" for generating all Ubuntu configurations.
-        description: 'The strategy matrix to use for generating the configurations ("minimal", "all").'
-        required: false
-        type: string
-        default: "minimal"
    outputs:
      matrix:
        description: "The generated strategy matrix."
@@ -29,17 +23,20 @@ jobs:
      matrix: ${{ steps.generate.outputs.matrix }}
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

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

      - name: Generate strategy matrix
        working-directory: .github/scripts/strategy-matrix
        id: generate
        env:
-          GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}.json', inputs.os) || '' }}
-          GENERATE_OPTION: ${{ inputs.strategy_matrix == 'all' && '--all' || '' }}
-        run: ./generate.py ${GENERATE_OPTION} ${GENERATE_CONFIG} >> "${GITHUB_OUTPUT}"
+          GENERATE_CONFIG: ${{ inputs.os != '' && format('--config={0}', inputs.os) || '' }}
+          # Run only the minimal matrix for pull requests that are not yet
+          # labeled "Ready to merge" or "Full CI build". Any other event (merge
+          # queue, push, schedule, manual dispatch) runs the full matrix.
+          GENERATE_MINIMAL: ${{ (github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'Ready to merge') && !contains(github.event.pull_request.labels.*.name, 'Full CI build')) && '--minimal' || '' }}
+        run: ./generate.py ${GENERATE_CONFIG} ${GENERATE_MINIMAL} >>"${GITHUB_OUTPUT}"
@@ -14,7 +14,7 @@ on:
        description: "The URL of the Conan endpoint to use."
        required: false
        type: string
-        default: https://conan.ripplex.io
+        default: https://conan.xrplf.org/repository/conan/

    secrets:
      remote_username:
@@ -40,14 +40,23 @@ defaults:
 jobs:
  upload:
    runs-on: ubuntu-latest
-    container: ghcr.io/xrplf/ci/ubuntu-noble:gcc-13-sha-5dd7158
+    container: ghcr.io/xrplf/xrpld/nix-ubuntu:sha-3d526d4
+    env:
+      REMOTE_NAME: ${{ inputs.remote_name }}
+      CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.remote_username }}
+      CONAN_PASSWORD_XRPLF: ${{ secrets.remote_password }}
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

-      - name: Generate build version number
-        id: version
-        uses: ./.github/actions/generate-version
+      - name: Prepare runner
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
+        with:
+          enable_ccache: false
+
+      - name: Determine release info
+        id: release_info
+        uses: ./.github/actions/release-info

      - name: Set up Conan
        uses: ./.github/actions/setup-conan
@@ -56,48 +65,20 @@ jobs:
          remote_url: ${{ inputs.remote_url }}

      - name: Log into Conan remote
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-          REMOTE_USERNAME: ${{ secrets.remote_username }}
-          REMOTE_PASSWORD: ${{ secrets.remote_password }}
-        run: conan remote login "${REMOTE_NAME}" "${REMOTE_USERNAME}" --password "${REMOTE_PASSWORD}"
+        run: conan remote login "${REMOTE_NAME}" "${CONAN_LOGIN_USERNAME_XRPLF}" --password "${CONAN_PASSWORD_XRPLF}"

      - name: Upload Conan recipe (version)
        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
+          VERSION: ${{ steps.release_info.outputs.version }}
        run: |
-          conan export . --version=${{ steps.version.outputs.version }}
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/${{ steps.version.outputs.version }}
+          conan export . --version="${VERSION}"
+          conan upload --confirm --check --remote="${REMOTE_NAME}" "xrpl/${VERSION}"

-      # When this workflow is triggered by a push event, it will always be when merging into the
-      # 'develop' branch, see on-trigger.yml.
      - name: Upload Conan recipe (develop)
-        if: ${{ github.event_name == 'push' }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
+        if: ${{ github.ref == 'refs/heads/develop' }}
        run: |
          conan export . --version=develop
          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/develop

-      # When this workflow is triggered by a pull request event, it will always be when merging into
-      # one of the 'release' branches, see on-pr.yml.
-      - name: Upload Conan recipe (rc)
-        if: ${{ github.event_name == 'pull_request' }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=rc
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/rc
-
-      # When this workflow is triggered by a push event, it will always be when tagging a final
-      # release, see on-tag.yml.
-      - name: Upload Conan recipe (release)
-        if: ${{ startsWith(github.ref, 'refs/tags/') }}
-        env:
-          REMOTE_NAME: ${{ inputs.remote_name }}
-        run: |
-          conan export . --version=release
-          conan upload --confirm --check --remote="${REMOTE_NAME}" xrpl/release
-
    outputs:
-      ref: xrpl/${{ steps.version.outputs.version }}
+      ref: xrpl/${{ steps.release_info.outputs.version }}
@@ -30,10 +30,11 @@ on:
      - ".github/scripts/strategy-matrix/**"
      - conanfile.py
      - conan.lock
+      - conan/profiles/**

 env:
  CONAN_REMOTE_NAME: xrplf
-  CONAN_REMOTE_URL: https://conan.ripplex.io
+  CONAN_REMOTE_URL: https://conan.xrplf.org/repository/conan/
  NPROC_SUBTRACT: 2

 concurrency:
@@ -48,8 +49,6 @@ jobs:
  # Generate the strategy matrix to be used by the following job.
  generate-matrix:
    uses: ./.github/workflows/reusable-strategy-matrix.yml
-    with:
-      strategy_matrix: ${{ github.event_name == 'pull_request' && 'minimal' || 'all' }}

  # Build and upload the dependencies for each configuration.
  run-upload-conan-deps:
@@ -58,22 +57,26 @@ jobs:
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.generate-matrix.outputs.matrix) }}
-      max-parallel: 10
    runs-on: ${{ matrix.architecture.runner }}
-    container: ${{ contains(matrix.architecture.platform, 'linux') && format('ghcr.io/xrplf/ci/{0}-{1}:{2}-{3}-sha-{4}', matrix.os.distro_name, matrix.os.distro_version, matrix.os.compiler_name, matrix.os.compiler_version, matrix.os.image_sha) || null }}
+    container: ${{ matrix.image || null }}
    steps:
      - name: Cleanup workspace (macOS and Windows)
        if: ${{ runner.os == 'macOS' || runner.os == 'Windows' }}
        uses: XRPLF/actions/cleanup-workspace@c7d9ce5ebb03c752a354889ecd870cadfc2b1cd4

      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Prepare runner
-        uses: XRPLF/actions/prepare-runner@90f11ee655d1687824fb8793db770477d52afbab
+        uses: XRPLF/actions/prepare-runner@8e98d61f011fd2a67f3fde5f0f075662c099a527
        with:
          enable_ccache: false

+      # Before any step that uses a build tool, composite actions included.
+      - name: Setup Nix environment
+        if: ${{ matrix.toolchain == 'nix' }}
+        uses: ./.github/actions/setup-nix-env
+
      - name: Print build environment
        uses: XRPLF/actions/print-build-env@59dec886e4afb05a1724443af08baccbc045b574

@@ -83,7 +86,15 @@ jobs:
        with:
          subtract: ${{ env.NPROC_SUBTRACT }}

+      - name: Set compiler environment (Linux)
+        if: ${{ runner.os == 'Linux' }}
+        uses: ./.github/actions/set-compiler-env
+        with:
+          compiler: ${{ matrix.compiler }}
+
+      # `setup-nix-env` already did this for the Nix toolchain.
      - name: Setup Conan
+        if: ${{ matrix.toolchain != 'nix' }}
        env:
          SANITIZERS: ${{ matrix.sanitizers }}
        uses: ./.github/actions/setup-conan
@@ -97,17 +108,20 @@ jobs:
          build_nproc: ${{ steps.nproc.outputs.nproc }}
          build_type: ${{ matrix.build_type }}
          force_build: ${{ github.event_name == 'schedule' || github.event.inputs.force_source_build == 'true' }}
-          # Set the verbosity to "quiet" for Windows to avoid an excessive
-          # amount of logs. For other OSes, the "verbose" logs are more useful.
-          log_verbosity: ${{ runner.os == 'Windows' && 'quiet' || 'verbose' }}
          sanitizers: ${{ matrix.sanitizers }}

+      - name: Check the Conan cache for Nix store references (Nix toolchain)
+        if: ${{ matrix.toolchain == 'nix' }}
+        run: ./bin/nix/check-nix-store-refs.sh "${CONAN_HOME}"
+
      - name: Log into Conan remote
        if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
-        run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.CONAN_REMOTE_USERNAME }}" --password "${{ secrets.CONAN_REMOTE_PASSWORD }}"
+        run: conan remote login "${CONAN_REMOTE_NAME}" "${{ secrets.NEXUS_REMOTE_USERNAME }}" --password "${{ secrets.NEXUS_REMOTE_PASSWORD }}"

      - name: Upload Conan packages
        if: ${{ github.repository == 'XRPLF/rippled' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
        env:
          FORCE_OPTION: ${{ github.event.inputs.force_upload == 'true' && '--force' || '' }}
+          CONAN_LOGIN_USERNAME_XRPLF: ${{ secrets.NEXUS_REMOTE_USERNAME }}
+          CONAN_PASSWORD_XRPLF: ${{ secrets.NEXUS_REMOTE_PASSWORD }}
        run: conan upload "*" --remote="${CONAN_REMOTE_NAME}" --confirm ${FORCE_OPTION}
@@ -72,17 +72,31 @@ DerivedData
 /.zed/

 # AI tools.
+# Shared/committable AI agent config (AGENTS.md, CLAUDE.md, GEMINI.md, .claude/settings.json,
+# tool-specific rules files, etc.) should be checked in — see CONTRIBUTING.md. Only the
+# personal/local variants below are ignored.
 /.agent
 /.agents
 /.augment
-/.claude
-/CLAUDE.md
+/.claude/settings.local.json
+AGENTS.override.md
+CLAUDE.local.md
+GEMINI.local.md

 # Python
 __pycache__

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

+# Direnv's local, per-developer overrides
+/.envrc.local
+
 # clangd cache
 /.cache
+
+# Rust build directory
+crates/target
@@ -15,6 +15,7 @@ repos:
    hooks:
      - id: check-added-large-files
        args: [--maxkb=400, --enforce-all]
+      - id: check-executables-have-shebangs
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-merge-conflict
@@ -27,58 +28,127 @@ repos:
        entry: ./bin/pre-commit/clang_tidy_check.py
        language: python
        types_or: [c++, c]
-        exclude: ^include/xrpl/protocol_autogen
-        pass_filenames: false # script determines the staged files itself
+        # .ipp fragments are included by their owning header rather than compiled
+        # as standalone translation units, so they have no compile_commands.json
+        # entry to lint (verify_headers checks them transitively).
+        exclude: '^include/xrpl/protocol_autogen|\.ipp$'
+        # run-clang-tidy --fix may edit headers included by files it is not run on,
+        # so pre-commit must not split the files across parallel hook invocations.
+        # The script determines the staged files itself and lets run-clang-tidy
+        # handle parallelism internally.
+        pass_filenames: false
      - id: fix-include-style
        name: fix include style
        entry: ./bin/pre-commit/fix_include_style.py
        language: python
        types_or: [c++, c]
        exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/
+      - id: fix-pragma-once
+        name: fix missing '#pragma once' declarations in header files
+        language: python
+        entry: ./bin/pre-commit/fix_pragma_once.py
+        files: \.(h|hpp)$
+      - id: check-doxygen-style
+        name: check Doxygen comment style
+        entry: ./bin/pre-commit/check_doxygen_style.py
+        language: python
+        types_or: [c++, c]
+      - id: fix-gtest-names
+        name: "fix gtest names: CamelCase suite, snake_case test case"
+        entry: ./bin/pre-commit/fix_gtest_names.py
+        language: python
+        types_or: [c++, c]

  - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: cd481d7b0bfb5c7b3090c21846317f9a8262e891 # frozen: v22.1.0
+    rev: a9a8a861f30ed207ead7d5a3b7e8032283ba5da7 # frozen: v23.1.2
    hooks:
      - id: clang-format
        args: [--style=file]
-        "types_or": [c++, c, proto]
+        types_or: [c++, c, proto]
        exclude: ^include/xrpl/protocol_autogen/(transactions|ledger_entries)/

-  - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.26.0
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt --manifest-path crates/Cargo.toml --all
+        language: system
+        types: [rust]
+        pass_filenames: false # rustfmt formats the whole workspace
+      - id: check-coverage-attrs
+        name: check Rust coverage attributes
+        entry: ./bin/pre-commit/check_rust_coverage_attrs.py
+        language: python
+        files: ^crates/.*\.rs$
+
+  - repo: https://github.com/BlankSpruce/gersemi-pre-commit
+    rev: 28010ddd6016e1a0f7bd232acb6536ef996ae897 # frozen: 0.29.2
    hooks:
      - id: gersemi
+        args: [-i, --warnings-as-errors]

  - repo: https://github.com/rbubley/mirrors-prettier
-    rev: c2bc67fe8f8f549cc489e00ba8b45aa18ee713b1 # frozen: v3.8.1
+    rev: ef4a397f916211b4a39ccf9d3d9cbb6562157251 # frozen: v3.9.9
    hooks:
      - id: prettier
        args: [--end-of-line=auto]

+  # Scoped to package/: the rest of the repo's Python has pre-existing findings,
+  # so widening these is its own change.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: f12be1ebaa5351c1fc76472de98db2c3446c8253 # frozen: v0.16.10
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        files: ^package/.*\.py$
+
  - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: ea488cebbfd88a5f50b8bd95d5c829d0bb76feb8 # frozen: 26.1.0
+    rev: 96ae3e5802f3fe2d551e703e18f0a367d1a81ac2 # frozen: 26.10.0
    hooks:
      - id: black

-  - repo: https://github.com/openstack/bashate
-    rev: 5798d24d571676fc407e81df574c1ef57b520f23 # frozen: 2.1.1
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: 2834ec6639549dd6796205c8f011dedcd587288b # frozen: v2.4.0
    hooks:
-      - id: bashate
-        args: ["--ignore=E006"]
+      - id: mypy
+        args: [--strict]
+        files: ^package/.*\.py$
+
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: 479be5958357ba5ab65ce47172117348516860e9 # frozen: v3.14.1-1
+    hooks:
+      - id: shfmt
+        args: [--write, --indent=4, --case-indent=true]
+
+  - repo: local
+    hooks:
+      - id: format-inline-bash-workflows
+        name: "format `run:` blocks in workflows/actions"
+        entry: ./.github/scripts/format-inline-bash.py
+        language: python
+        files: ^\.github/(workflows|actions)/.*\.ya?ml$
+      - id: format-inline-bash-markdown
+        name: "format ```bash blocks in markdown"
+        entry: ./.github/scripts/format-inline-bash.py
+        language: python
+        files: \.md$

  - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: a42085ade523f591dca134379a595e7859986445 # frozen: v9.7.0
+    rev: f5c5d72342f35643988a9ffa0705c05bd3ff8383 # frozen: v10.3.0
    hooks:
-      - id: cspell # Spell check changed files
-        exclude: (.config/cspell.config.yaml|^include/xrpl/protocol_autogen/(transactions|ledger_entries)/)
-      - id: cspell # Spell check the commit message
+      - id: cspell
+        name: check changed files spelling
+        exclude: |
+          (?x)^(
+              \.cspell\.config\.yaml|
+              include/xrpl/protocol_autogen/(transactions|ledger_entries)/.*
+          )$
+      - id: cspell
        name: check commit message spelling
        args:
          - --no-must-find-files
          - --no-progress
          - --no-summary
-          - --files
-          - .git/COMMIT_EDITMSG
        stages: [commit-msg]

  - repo: local
@@ -0,0 +1,42 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (Claude Code, and other AGENTS.md-compatible tools) when working with code in this repository.
+
+## Build
+
+Required on Linux/macOS: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
+
+```bash
+nix develop
+```
+
+For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For the manual build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
+
+Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).
+
+## Testing
+
+Unit tests are a custom framework built into the `xrpld` binary itself (not Boost.Test/GTest/Catch); see [CONTRIBUTING.md](./CONTRIBUTING.md#unit-tests) for the basic invocation. Notes not covered there:
+
+- A suite's `--unittest` name is built from the arguments to its `BEAST_DEFINE_TESTSUITE`/`BEAST_DEFINE_TESTSUITE_PRIO` macro (usually at the bottom of the test file), in reverse order and joined with `.`: `BEAST_DEFINE_TESTSUITE(Credentials, app, xrpl)` → `xrpl.app.Credentials`.
+- `--unittest-arg` does nothing — don't use it.
+- Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
+- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
+
+## Lint/Format
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup and [CONTRIBUTING.md](./CONTRIBUTING.md#clang-tidy) for `clang-tidy` (opt-in, needs local `clang-tidy` and generated headers).
+
+## Code Style
+
+New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages).
+
+## Architecture
+
+Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
+
+- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`. Any change to transaction-processing behavior must be gated behind an Amendment.
+- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
+- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
+- `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
+- `crates/` — a Rust workspace holding the WebAssembly engine that runs Smart Escrow contracts, bridged into C++ via `cxxbridge`/the `cxx` crate; see [crates/README.md](./crates/README.md) for more details.
@@ -22,14 +22,67 @@ API version 2 is available in `xrpld` version 2.0.0 and later. See [API-VERSION-

 This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-RPC requests, it is currently the default API version used when no `api_version` is specified.

-## Unreleased
+## XRP Ledger server version 3.5.0

-This section contains changes targeting a future version.
+Version 3.5.0 is not yet released.

-### Additions
+### Additions in 3.5.0
+
+- `subscribe`, `unsubscribe`: Added an optional `mpt_issuances` request field, an array of MPT issuance IDs (hex strings). Subscribers receive the same `transaction` message as the `transactions` stream for each validated transaction whose metadata affects a subscribed issuance. MPT issuance subscriptions count toward the per-connection subscription limit. An empty array, a non-array value, or an invalid ID returns `invalidParams`. ([#5671](https://github.com/XRPLF/rippled/pull/5671))
+- `ledger_entry`: Add full support for checks, NFT offers, payment channels, and signer lists. ([#6319](https://github.com/XRPLF/rippled/pull/6319))
+
+### Bugfixes in 3.5.0
+
+- `channel_authorize`: The `channel_id` field now returns an `invalidParams` error if the value is not a string. [#7582](https://github.com/XRPLF/rippled/pull/7582)
+- `channel_verify`: The `channel_id` and `signature` fields now return an `invalidParams` error if the value is not a string. [#7582](https://github.com/XRPLF/rippled/pull/7582)
+
+### Bugfixes in 3.5.0
+
+- `feature`: The admin-only `vetoed` field now returns `invalidParams` unless its value is a boolean. [#7583](https://github.com/XRPLF/rippled/pull/7583)
+
+## XRP Ledger server version 3.4.0
+
+Version 3.4.0 is not yet released. These changes are available in the 3.4.0 beta releases.
+
+### Additions in 3.4.0
+
+- `ledger`: `nftoken_id`, `nftoken_ids`, and `offer_id` are now included in transaction metadata when transactions are expanded (`expand`, or admin-only `full`), matching the `tx`, `account_tx`, and `subscribe` (`transactions` stream) responses. ([#5706](https://github.com/XRPLF/rippled/pull/5706))
+
+### Bugfixes in 3.4.0
+
+- `sign`, `sign_for`, `submit`: `signature_target` now returns `invalidParams` unless it names `CounterpartySignature` or `SponsorSignature`. It previously accepted any inner object field, such as `Book` or `NFToken`, and signed into it.
+- `sign`, `sign_for`, `submit`, `submit_multisigned`: With `fixCleanup3_4_0` enabled, a signature in `CounterpartySignature` or `SponsorSignature` covers a different prefix than the transaction's own signature, so a signature can no longer be moved from one of those roles into another. Clients that build these signatures themselves must use the new prefixes: `CPT` and `CPM` (single- and multi-signing) for `CounterpartySignature`, and `SPN` and `SPM` for `SponsorSignature`.
+- `get_aggregate_price`: Duplicate entries in the `oracles` request array are now ignored. [#6586](https://github.com/XRPLF/rippled/pull/6586)
+- `vault_info`: Errors now identify what the request got wrong instead of reporting every failure as the unregistered token `malformedRequest`, and the `error`, `error_code` and `error_message` fields now agree with each other. An invalid `vault_id` or `seq` returns `invalidParams`, an invalid `owner` returns `actMalformed`, and a request that mixes `vault_id` with `owner`/`seq` or supplies neither returns `invalidParams` with a message naming the accepted combinations. [#8015](https://github.com/XRPLF/rippled/pull/8015)
+- `vault_info`: A well-formed all-zero `vault_id` now returns `entryNotFound` instead of being rejected as malformed, and `entryNotFound` responses now include `error_code` and `error_message`. Clients that request `ripplerpc` 3.0 or above therefore receive HTTP 400 with that error rather than HTTP 200. [#8015](https://github.com/XRPLF/rippled/pull/8015)
+- `vault_info`: `vault_id` and `owner` must now be strings, matching how `ledger_entry` reads the same fields. An object or an array in either field previously produced an internal error, and a number was silently converted to its decimal text; `vault_id` now returns `invalidParams` and `owner` returns `actMalformed`. [#8015](https://github.com/XRPLF/rippled/pull/8015)
+- `gateway_balances`: The `account` and `ident` fields now return an `invalidParams` error if the value is not a string, instead of an `internal` error. [#7655](https://github.com/XRPLF/rippled/pull/7655)
+- `account_lines`: The `peer` field now returns an error if the value is not a string. [#7728](https://github.com/XRPLF/rippled/pull/7728)
+- `ledger`: `delivered_amount` is now included in the metadata of successful `AccountDelete` transactions when transactions are expanded (`expand`, or admin-only `full`). Previously it was only added for `Payment` and `CheckCash`, which made `ledger` inconsistent with `tx` and `account_tx`. [#5706](https://github.com/XRPLF/rippled/pull/5706)
+- `noripple_check`: The `transactions` field is no longer included in error responses; it is still returned (possibly as an empty array) whenever `transactions` is `true` and the request succeeds. A malformed `account` is now rejected before the ledger is looked up, so that error response no longer carries the `ledger_hash`, `ledger_index`, and `validated` fields ([#6303](https://github.com/XRPLF/rippled/pull/6303)).
+- `transaction_entry`: An object or an array in `tx_hash` now returns `malformedRequest`, like any other value that is not a hex hash, instead of an `internal` error.
+
+## XRP Ledger server version 3.3.0
+
+[Version 3.3.0](https://github.com/XRPLF/rippled/releases/tag/3.3.0) was released on Aug 6, 2026.
+
+### Additions in 3.3.0
+
+- `account_tx`: Added an optional `delegate` request object to filter delegated transactions. The object requires `delegate_filter`, which must be either `actor` for transactions owned by the requested account but signed by another account, or `authorizer` for transactions signed by the requested account on behalf of another account. The optional `counter_party` account narrows the results to a specific signer/delegate for `actor` or a specific owner/delegator for `authorizer`. Malformed `delegate`, `delegate_filter`, and `counter_party` values return standard invalid field errors, and invalid account IDs return `actMalformed`. When paginating delegate-filtered queries, a marker from a delegate-filtered query includes a `delegate` flag and is only valid for follow-up requests that also supply `delegate` (mixing marker conventions returns `invalidParams`). Because filtering is applied after the ledger scan, a page may contain fewer results than `limit` (possibly zero) while still returning a marker, so callers must continue until no marker is present. ([#6126](https://github.com/XRPLF/rippled/pull/6126))
+
+## XRP Ledger server version 3.2.1
+
+[Version 3.2.1](https://github.com/XRPLF/rippled/releases/tag/3.2.1) was released on Aug 1, 2026.
+
+This release contains bug fixes only and no API changes.
+
+## XRP Ledger server version 3.2.0
+
+[Version 3.2.0](https://github.com/XRPLF/rippled/releases/tag/3.2.0) was released on Jun 16, 2026.
+
+### Additions in 3.2.0

 - `ledger_entry`, `account_objects`: The `Delegate` ledger entry now includes an optional `DestinationNode` field, which stores the index into the authorized account's owner directory. This field is present on entries created after bidirectional directory tracking was introduced and may appear in RPC responses for those entries. ([#6681](https://github.com/XRPLF/rippled/pull/6681))
-
 - `server_definitions`: Added the following new sections to the response ([#6321](https://github.com/XRPLF/rippled/pull/6321)):
  - `TRANSACTION_FORMATS`: Describes the fields and their optionality for each transaction type, including common fields shared across all transactions.
  - `LEDGER_ENTRY_FORMATS`: Describes the fields and their optionality for each ledger entry type, including common fields shared across all ledger entries.
@@ -37,7 +90,7 @@ This section contains changes targeting a future version.
  - `LEDGER_ENTRY_FLAGS`: Maps ledger entry type names to their flags and flag values.
  - `ACCOUNT_SET_FLAGS`: Maps AccountSet flag names (asf flags) to their numeric values.

-### Bugfixes
+### Bugfixes in 3.2.0

 - Peer Crawler: The `port` field in `overlay.active[]` now consistently returns an integer instead of a string for outbound peers. [#6318](https://github.com/XRPLF/rippled/pull/6318)
 - `ping`: The `ip` field is no longer returned as an empty string for proxied connections without a forwarded-for header. It is now omitted, consistent with the behavior for identified connections. [#6730](https://github.com/XRPLF/rippled/pull/6730)
@@ -51,6 +104,24 @@ This section contains changes targeting a future version.
 - `subscribe`: The `taker` field in the `books` array now returns `actMalformed` instead of `badIssuer` if the value is not a valid account. [#6529](https://github.com/XRPLF/rippled/pull/6529)
 - Fixed a bug in `Forwarded` HTTP header parsing where the extracted IP address could be incorrect when no comma or semicolon delimiter follows the address. This could cause the server to misidentify a client's IP address when operating behind a reverse proxy. [#6529](https://github.com/XRPLF/rippled/pull/6529)

+## XRP Ledger server version 3.1.3
+
+[Version 3.1.3](https://github.com/XRPLF/rippled/releases/tag/3.1.3) was released on May 8, 2026.
+
+This release contains bug fixes only and no API changes.
+
+## XRP Ledger server version 3.1.2
+
+[Version 3.1.2](https://github.com/XRPLF/rippled/releases/tag/3.1.2) was released on Mar 12, 2026.
+
+This release contains bug fixes only and no API changes.
+
+## XRP Ledger server version 3.1.1
+
+[Version 3.1.1](https://github.com/XRPLF/rippled/releases/tag/3.1.1) was released on Feb 23, 2026.
+
+This release contains bug fixes only and no API changes.
+
 ## XRP Ledger server version 3.1.0

 [Version 3.1.0](https://github.com/XRPLF/rippled/releases/tag/3.1.0) was released on Jan 27, 2026.
@@ -1,26 +1,38 @@
-| :warning: **WARNING** :warning:                                                                                                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md). |
+| :warning: **WARNING** :warning:                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, Rust, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md).<br><br>These instructions also assume a basic familiarity with Conan and CMake. If you are unfamiliar with Conan, you can read our [crash course](./docs/build/conan.md) or the official [Getting Started][conan-getting-started] walkthrough. |

-> These instructions also assume a basic familiarity with Conan and CMake.
-> If you are unfamiliar with Conan, you can read our
-> [crash course](./docs/build/conan.md) or the official [Getting Started][3]
-> walkthrough.
+## Minimum Requirements

-## Branches
+For the hardware needed to run a node, see
+[System Requirements](https://xrpl.org/system-requirements.html).

-For a stable release, choose the `master` branch or one of the [tagged
-releases](https://github.com/XRPLF/rippled/releases).
+For the software needed to build xrpld, see the
+[environment setup guide](./docs/build/environment.md).

-```bash
-git checkout master
-```
+## Operating Systems

-For the latest release candidate, choose the `release` branch.
+### Linux

-```bash
-git checkout release
-```
+The Ubuntu Linux distribution has received the highest level of quality
+assurance, testing, and support. We also support Red Hat and use Debian
+internally.
+Our Linux CI tooling is distro-independent and uses a Nix-based environment, so it should be possible to build on other Linux distributions as well, although we have not tested them.
+
+### macOS
+
+Many `xrpld` engineers use macOS for development.
+The minimum supported version is macOS 15 (Sequoia).
+CI testing is done in macOS 26 (Tahoe), but the build defaults `CMAKE_OSX_DEPLOYMENT_TARGET` to 15.
+
+### Windows
+
+Windows is used by some engineers for development only, and is not recommended
+for production use.
+
+## Steps
+
+### Branches

 For the latest set of untested features, or to contribute, choose the `develop`
 branch.
@@ -29,303 +41,41 @@ branch.
 git checkout develop
 ```

-## Minimum Requirements
+For a release or release candidate, check out its [tag](https://github.com/XRPLF/rippled/releases), e.g.:

-See [System Requirements](https://xrpl.org/system-requirements.html).
+```bash
+git checkout 3.4.0
+```

-Building xrpld generally requires git, Python, Conan, CMake, and a C++
-compiler. Some guidance on setting up such a [C++ development environment can be
-found here](./docs/build/environment.md).
+See [RELEASING.md](./RELEASING.md) for how branches and releases are organized.

- [Python 3.11](https://www.python.org/downloads/), or higher
- [Conan 2.17](https://conan.io/downloads.html)[^1], or higher
- [CMake 3.22](https://cmake.org/download/), or higher
-
-[^1]:
-    It is possible to build with Conan 1.60+, but the instructions are
-    significantly different, which is why we are not recommending it.
-
-`xrpld` is written in the C++20 dialect and includes the `<concepts>` header.
-The [minimum compiler versions][2] required are:
-
-| Compiler    | Version   |
-| ----------- | --------- |
-| GCC         | 12        |
-| Clang       | 16        |
-| Apple Clang | 16        |
-| MSVC        | 19.44[^3] |
-
-### Linux
-
-The Ubuntu Linux distribution has received the highest level of quality
-assurance, testing, and support. We also support Red Hat and use Debian
-internally.
-
-Here are [sample instructions for setting up a C++ development environment on
-Linux](./docs/build/environment.md#linux).
-
-### Mac
-
-Many xrpld engineers use macOS for development.
-
-Here are [sample instructions for setting up a C++ development environment on
-macOS](./docs/build/environment.md#macos).
-
-### Windows
-
-Windows is used by some engineers for development only.
-
-[^3]: Windows is not recommended for production use.
-
-## Steps
+A build reports `0.0.0-dev` with its short commit hash as build metadata, e.g.
+`0.0.0-dev+0123abc`. Only builds of a release, from a tag in CI or a versioned
+Conan reference, report a release version. To use another version, set the
+`FORCE_XRPLD_VERSION` environment variable when running CMake, e.g.
+`FORCE_XRPLD_VERSION=3.4.0`.

 ### Set Up Conan

-After you have a [C++ development environment](./docs/build/environment.md) ready with Git, Python,
-Conan, CMake, and a C++ compiler, you may need to set up your Conan profile.
-
-These instructions assume a basic familiarity with Conan and CMake. If you are
-unfamiliar with Conan, then please read [this crash course](./docs/build/conan.md) or the official
-[Getting Started][3] walkthrough.
-
-#### Conan lockfile
-
-To achieve reproducible dependencies, we use a [Conan lockfile](https://docs.conan.io/2/tutorial/versioning/lockfiles.html),
-which has to be updated every time dependencies change.
-
-Please see the [instructions on how to regenerate the lockfile](conan/lockfile/README.md).
-
-#### Default profile
-
-We recommend that you import the provided `conan/profiles/default` profile:
+Once your [development environment](./docs/build/environment.md) is ready, set
+Conan up for this repository:

 ```bash
-conan config install conan/profiles/ -tf $(conan config home)/profiles/
+./conan/init.sh
 ```

-You can check your Conan profile by running:
+That installs our [`global.conf`](./conan/global.conf), our Conan
+[profiles](./conan/profiles), and the `xrplf` remote that hosts some of our
+dependencies. It honours `CONAN_HOME` and never deletes an existing Conan home,
+so it is safe to re-run — it only overwrites the files it manages.

-```bash
-conan profile show
-```
+> [!TIP]
+> In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is
+> already done for you: the script runs on entry.

-#### Custom profile
-
-If the default profile does not work for you and you do not yet have a Conan
-profile, you can create one by running:
-
-```bash
-conan profile detect
-```
-
-You may need to make changes to the profile to suit your environment. You can
-refer to the provided `conan/profiles/default` profile for inspiration, and you
-may also need to apply the required [tweaks](#conan-profile-tweaks) to this
-default profile.
-
-### Patched recipes
-
-Occasionally, we need patched recipes or recipes not present in Conan Center.
-We maintain a fork of the Conan Center Index
-[here](https://github.com/XRPLF/conan-center-index/) containing the modified and newly added recipes.
-
-To ensure our patched recipes are used, you must add our Conan remote at a
-higher index than the default Conan Center remote, so it is consulted first. You
-can do this by running:
-
-```bash
-conan remote add --index 0 xrplf https://conan.ripplex.io
-```
-
-Alternatively, you can pull our recipes from the repository and export them locally:
-
-```bash
-# Define which recipes to export.
-recipes=('abseil' 'ed25519' 'grpc' 'm4' 'mpt-crypto' 'openssl' 'secp256k1' 'snappy' 'soci' 'wasm-xrplf' 'wasmi')
-
-# Selectively check out the recipes from our CCI fork.
-cd external
-mkdir -p conan-center-index
-cd conan-center-index
-git init
-git remote add origin git@github.com:XRPLF/conan-center-index.git
-git sparse-checkout init
-for recipe in "${recipes[@]}"; do
-  echo "Checking out recipe '${recipe}'..."
-  git sparse-checkout add recipes/${recipe}
-done
-git fetch origin master
-git checkout master
-
-./export_all.sh
-cd ../../
-```
-
-In the case we switch to a newer version of a dependency that still requires a
-patch or add a new dependency, it will be necessary for you to pull in the changes and re-export the
-updated dependencies with the newer version. However, if we switch to a newer
-version that no longer requires a patch, no action is required on your part, as
-the new recipe will be automatically pulled from the official Conan Center.
-
-> [!NOTE]
-> You might need to add `--lockfile=""` to your `conan install` command
-> to avoid automatic use of the existing `conan.lock` file when you run
-> `conan export` manually on your machine
->
-> This is not recommended though, as you might end up using different revisions of recipes.
-
-### Conan profile tweaks
-
-#### Missing compiler version
-
-If you see an error similar to the following after running `conan profile show`:
-
-```bash
-ERROR: Invalid setting '17' is not a valid 'settings.compiler.version' value.
-Possible values are ['5.0', '5.1', '6.0', '6.1', '7.0', '7.3', '8.0', '8.1',
-'9.0', '9.1', '10.0', '11.0', '12.0', '13', '13.0', '13.1', '14', '14.0', '15',
-'15.0', '16', '16.0']
-Read "http://docs.conan.io/2/knowledge/faq.html#error-invalid-setting"
-```
-
-you need to add your compiler to the list of compiler versions in
-`$(conan config home)/settings_user.yml`, by adding the required version number(s)
-to the `version` array specific for your compiler. For example:
-
-```yaml
-compiler:
-  apple-clang:
-    version: ["17.0"]
-```
-
-#### Multiple compilers
-
-If you have multiple compilers installed, make sure to select the one to use in
-your default Conan configuration **before** running `conan profile detect`, by
-setting the `CC` and `CXX` environment variables.
-
-For example, if you are running MacOS and have [homebrew
-LLVM@18](https://formulae.brew.sh/formula/llvm@18), and want to use it as a
-compiler in the new Conan profile:
-
-```bash
-export CC=$(brew --prefix llvm@18)/bin/clang
-export CXX=$(brew --prefix llvm@18)/bin/clang++
-conan profile detect
-```
-
-You should also explicitly set the path to the compiler in the profile file,
-which helps to avoid errors when `CC` and/or `CXX` are set and disagree with the
-selected Conan profile. For example:
-
-```text
-[conf]
-tools.build:compiler_executables={'c':'/usr/bin/gcc','cpp':'/usr/bin/g++'}
-```
-
-#### Multiple profiles
-
-You can manage multiple Conan profiles in the directory
-`$(conan config home)/profiles`, for example renaming `default` to a different
-name and then creating a new `default` profile for a different compiler.
-
-#### Select language
-
-The default profile created by Conan will typically select different C++ dialect
-than C++20 used by this project. You should set `20` in the profile line
-starting with `compiler.cppstd=`. For example:
-
-```bash
-sed -i.bak -e 's|^compiler\.cppstd=.*$|compiler.cppstd=20|' $(conan config home)/profiles/default
-```
-
-#### Select standard library in Linux
-
-**Linux** developers will commonly have a default Conan [profile][] that
-compiles with GCC and links with libstdc++. If you are linking with libstdc++
-(see profile setting `compiler.libcxx`), then you will need to choose the
-`libstdc++11` ABI:
-
-```bash
-sed -i.bak -e 's|^compiler\.libcxx=.*$|compiler.libcxx=libstdc++11|' $(conan config home)/profiles/default
-```
-
-#### Select architecture and runtime in Windows
-
-**Windows** developers may need to use the x64 native build tools. An easy way
-to do that is to run the shortcut "x64 Native Tools Command Prompt" for the
-version of Visual Studio that you have installed.
-
-Windows developers must also build `xrpld` and its dependencies for the x64
-architecture:
-
-```bash
-sed -i.bak -e 's|^arch=.*$|arch=x86_64|' $(conan config home)/profiles/default
-```
-
-**Windows** developers also must select static runtime:
-
-```bash
-sed -i.bak -e 's|^compiler\.runtime=.*$|compiler.runtime=static|' $(conan config home)/profiles/default
-```
-
-#### Clang workaround for grpc
-
-If your compiler is clang, version 19 or later, or apple-clang, version 17 or
-later, you may encounter a compilation error while building the `grpc`
-dependency:
-
-```text
-In file included from .../lib/promise/try_seq.h:26:
-.../lib/promise/detail/basic_seq.h:499:38: error: a template argument list is expected after a name prefixed by the template keyword [-Wmissing-template-arg-list-after-template-kw]
-  499 |                     Traits::template CallSeqFactory(f_, *cur_, std::move(arg)));
-      |                                      ^
-```
-
-The workaround for this error is to add two lines to profile:
-
-```text
-[conf]
-tools.build:cxxflags=['-Wno-missing-template-arg-list-after-template-kw']
-```
-
-#### Workaround for gcc 12
-
-If your compiler is gcc, version 12, and you have enabled `werr` option, you may
-encounter a compilation error such as:
-
-```text
-/usr/include/c++/12/bits/char_traits.h:435:56: error: 'void* __builtin_memcpy(void*, const void*, long unsigned int)' accessing 9223372036854775810 or more bytes at offsets [2, 9223372036854775807] and 1 may overlap up to 9223372036854775813 bytes at offset -3 [-Werror=restrict]
-  435 |         return static_cast<char_type*>(__builtin_memcpy(__s1, __s2, __n));
-      |                                        ~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~
-cc1plus: all warnings being treated as errors
-```
-
-The workaround for this error is to add two lines to your profile:
-
-```text
-[conf]
-tools.build:cxxflags=['-Wno-restrict']
-```
-
-#### Workaround for clang 16
-
-If your compiler is clang, version 16, you may encounter compilation error such
-as:
-
-```text
-In file included from .../boost/beast/websocket/stream.hpp:2857:
-.../boost/beast/websocket/impl/read.hpp:695:17: error: call to 'async_teardown' is ambiguous
-                async_teardown(impl.role, impl.stream(),
-                ^~~~~~~~~~~~~~
-```
-
-The workaround for this error is to add two lines to your profile:
-
-```text
-[conf]
-tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS']
-```
+You can inspect the resulting profile with `conan profile show`. If it is not
+suitable for your environment, create a custom profile and pass it to Conan — see
+[Advanced Conan configuration](./docs/build/advanced_conan.md).

 ### Set Up Ccache

@@ -333,14 +83,7 @@ To speed up repeated compilations, we recommend that you install
 [ccache](https://ccache.dev), a tool that wraps your compiler so that it can
 cache build objects locally.

-#### Linux
-
-You can install it using the package manager, e.g. `sudo apt install ccache`
-(Ubuntu) or `sudo dnf install ccache` (RHEL).
-
-#### macOS
-
-You can install it using Homebrew, i.e. `brew install ccache`.
+On Linux and macOS, `ccache` is included in the [Nix development shell](./docs/build/nix.md).

 #### Windows

@@ -427,16 +170,19 @@ install ccache --version 4.11.3 --allow-downgrade`.
   Single-config generators:

   ```
-   cmake --build .
+   cmake --build . --parallel N
   ```

   Multi-config generators:

   ```
-   cmake --build . --config Release
-   cmake --build . --config Debug
+   cmake --build . --config Release --parallel N
+   cmake --build . --config Debug --parallel N
   ```

+   Replace the `--parallel` parameter N with the desired number of parallel jobs. A common starting point is half of the number of available CPU
+   cores.
+
 5. Test xrpld.

   Single-config generators:
@@ -472,7 +218,17 @@ cmake --build . --target setup_code_gen  # create venv and install dependencies
 cmake --build . --target code_gen        # regenerate code
 ```

-The regenerated files should be committed alongside your changes.
+The same targets are also available as a standalone project, which does not
+need the dependencies to be configured first:
+
+```
+cmake -S cmake/codegen -B build/codegen
+cmake --build build/codegen --target setup_code_gen
+cmake --build build/codegen --target code_gen
+```
+
+The regenerated files should be committed alongside your changes. CI verifies
+that they are up-to-date.

 ## Coverage report

@@ -484,10 +240,14 @@ which is only enabled when the `coverage` option is set, e.g. with
 Prerequisites for the coverage report:

 - [gcovr tool][gcovr] (can be installed e.g. with [pip][python-pip])
- `gcov` for GCC (installed with the compiler by default) or
- `llvm-cov` for Clang (installed with the compiler by default)
+- `gcov` for GCC or `llvm-cov` for Clang, usually installed with the compiler
 - `Debug` build type

+> [!NOTE]
+> Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell):
+> its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`,
+> or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler.
+
 A coverage report is created when the following steps are completed, in order:

 1. `xrpld` binary built with instrumentation data, enabled by the `coverage`
@@ -530,35 +290,71 @@ stored inside the build directory, as either of:
 ## Sanitizers

 To build dependencies and xrpld with sanitizer instrumentation, set the
-`SANITIZERS` environment variable (only once before running conan and cmake) and use the `sanitizers` profile in conan:
+`SANITIZERS` environment variable when running `conan install` and use the `sanitizers` profile:

 ```bash
 export SANITIZERS=address,undefinedbehavior

 conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug
-
-cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Debug -Dxrpld=ON -Dtests=ON ..
 ```

+You can then build and test as usual, with the generated `xrpld` binary containing the sanitizer instrumentation. When you run it, it will report any sanitizer errors it detects in the console output.
+
 See [Sanitizers docs](./docs/build/sanitizers.md) for more details.

 ## Options

-| Option     | Default Value | Description                                                    |
-| ---------- | ------------- | -------------------------------------------------------------- |
-| `assert`   | OFF           | Enable assertions.                                             |
-| `coverage` | OFF           | Prepare the coverage report.                                   |
-| `tests`    | OFF           | Build tests.                                                   |
-| `unity`    | OFF           | Configure a unity build.                                       |
-| `xrpld`    | OFF           | Build the xrpld application, and not just the libxrpl library. |
-| `werr`     | OFF           | Treat compilation warnings as errors                           |
-| `wextra`   | OFF           | Enable additional compilation warnings                         |
+| Option           | Default Value | Description                                                                   |
+| ---------------- | ------------- | ----------------------------------------------------------------------------- |
+| `assert`         | OFF           | Force enabling assertions.                                                    |
+| `coverage`       | OFF           | Prepare the coverage report.                                                  |
+| `tests`          | OFF           | Build tests.                                                                  |
+| `unity`          | OFF           | Configure a unity build.                                                      |
+| `verify_headers` | ON            | Make the `verify-headers` target available to compile each header on its own. |
+| `xrpld`          | OFF           | Build the xrpld application, and not just the libxrpl library.                |
+| `werr`           | OFF           | Treat compilation warnings as errors                                          |
+| `wextra`         | OFF           | Enable additional compilation warnings                                        |

-[Unity builds][5] may be faster for the first build (at the cost of much more
+[Unity builds][unity-build] may be faster for the first build (at the cost of much more
 memory) since they concatenate sources into fewer translation units. Non-unity
 builds may be faster for incremental builds, and can be helpful for detecting
 `#include` omissions.

+### Rust crates
+
+The build compiles the Rust workspace in `crates/` and generates the cxxbridge
+bindings the C++ side includes, so it needs a Rust toolchain (`cargo`, `rustc`)
+at the channel pinned in [`rust-toolchain.toml`](./rust-toolchain.toml). The
+[Nix development shell](./docs/build/nix.md) provides one; otherwise install it
+as described in [Rust](./docs/build/environment.md#rust).
+
+The crates also have their own Rust unit tests. Those are run with `cargo` and
+need only the Rust toolchain, independently of CMake (CI runs them with
+`cargo nextest`):
+
+```bash
+cargo test --manifest-path crates/Cargo.toml --workspace
+```
+
+### Verifying headers
+
+The regular build only compiles `.cpp` files, so a header is only ever checked
+through whatever translation unit happens to include it. A header that forgets
+an `#include` is not caught as long as every `.cpp` that uses it includes its
+missing dependency first. The `verify_headers` option (ON by default) adds a
+`verify-headers` target that compiles every header on its own, which fails if a
+header is not self-contained:
+
+```bash
+cmake --build . --target verify-headers
+```
+
+The per-header objects are excluded from the `all` target, so a normal build
+never compiles them; they are built only through `verify-headers`. The generated
+translation units do appear in `compile_commands.json`, so clang-tidy (and
+clangd and IDEs) can lint each header on its own. Pass `-Dverify_headers=OFF` to
+omit them entirely.
+
 ## Troubleshooting

 ### Conan
@@ -580,14 +376,18 @@ After any updates or changes to dependencies, you may need to do the following:
   conan remove '*'
   ```

-3. Re-run [conan export](#patched-recipes) if needed.
-4. [Regenerate lockfile](#conan-lockfile).
+3. Re-run [conan export](./docs/build/advanced_conan.md#patched-recipes) if needed.
+4. [Regenerate lockfile](./docs/build/advanced_conan.md#conan-lockfile).
 5. Re-run [conan install](#build-and-test).

+If you are using the Nix development shell, whether prebuilt Conan binaries apply
+depends on your platform — see
+[Prebuilt packages](./docs/build/nix.md#prebuilt-packages).
+
 #### ERROR: Package not resolved

 If you're seeing an error like `ERROR: Package 'snappy/1.1.10' not resolved: Unable to find 'snappy/1.1.10#968fef506ff261592ec30c574d4a7809%1756234314.246' in remotes.`,
-please add `xrplf` remote or re-run `conan export` for [patched recipes](#patched-recipes).
+please [set Conan up](#set-up-conan) so the `xrplf` remote is configured, or re-run `conan export` for [patched recipes](./docs/build/advanced_conan.md#patched-recipes).

 ### `protobuf/port_def.inc` file not found

@@ -607,28 +407,8 @@ For example, if you want to build Debug:
 1. For conan install, pass `--settings build_type=Debug`
 2. For cmake, pass `-DCMAKE_BUILD_TYPE=Debug`

-## Add a Dependency
-
-If you want to experiment with a new package, follow these steps:
-
-1. Search for the package on [Conan Center](https://conan.io/center/).
-2. Modify [`conanfile.py`](./conanfile.py):
-   - Add a version of the package to the `requires` property.
-   - Change any default options for the package by adding them to the
-     `default_options` property (with syntax `'$package:$option': $value`).
-3. Modify [`CMakeLists.txt`](./CMakeLists.txt):
-   - Add a call to `find_package($package REQUIRED)`.
-   - Link a library from the package to the target `xrpl_libs`
-     (search for the existing call to `target_link_libraries(xrpl_libs INTERFACE ...)`).
-4. Start coding! Don't forget to include whatever headers you need from the package.
-
-[1]: https://github.com/conan-io/conan-center-index/issues/13168
-[2]: https://en.cppreference.com/w/cpp/compiler_support/20
-[3]: https://docs.conan.io/en/latest/getting_started.html
-[5]: https://en.wikipedia.org/wiki/Unity_build
-[6]: https://github.com/boostorg/beast/issues/2648
-[7]: https://github.com/boostorg/beast/issues/2661
+[conan-getting-started]: https://docs.conan.io/en/latest/getting_started.html
+[unity-build]: https://en.wikipedia.org/wiki/Unity_build
 [gcovr]: https://gcovr.com/en/stable/getting-started.html
 [python-pip]: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/
 [build_type]: https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html
-[profile]: https://docs.conan.io/en/latest/reference/profiles.html
@@ -0,0 +1 @@
+AGENTS.md
@@ -13,9 +13,26 @@ if(DEFINED CMAKE_MODULE_PATH)
 endif()
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

+# Must be set before project() because project() consumes it when configuring the compiler and SDK.
+# A user-provided -DCMAKE_OSX_DEPLOYMENT_TARGET still takes precedence.
+#
+# CMAKE_SYSTEM_NAME can't be used before project(), so CMAKE_HOST_SYSTEM_NAME is used instead.
+#
+# When CMAKE_OSX_DEPLOYMENT_TARGET is bumped to >=26.0, FastFloat dependency won't be needed anymore
+if(
+    CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin"
+    AND NOT DEFINED CMAKE_OSX_DEPLOYMENT_TARGET
+)
+    set(CMAKE_OSX_DEPLOYMENT_TARGET
+        "15.0"
+        CACHE STRING
+        "Minimum macOS deployment version"
+    )
+endif()
+
 project(xrpl)
 set(CMAKE_CXX_EXTENSIONS OFF)
-set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

@@ -57,8 +74,9 @@ if(target)
    )
 endif()

+include(PatchNixBinary)
+
 include(XrplSanity)
-include(XrplVersion)
 include(XrplSettings)
 # this check has to remain in the top-level cmake because of the early return statement
 if(packages_only)
@@ -85,21 +103,26 @@ include(deps/Boost)
 add_subdirectory(external/antithesis-sdk)
 find_package(date REQUIRED)
 find_package(ed25519 REQUIRED)
+find_package(FastFloat REQUIRED)
 find_package(gRPC REQUIRED)
 find_package(LibArchive REQUIRED)
 find_package(lz4 REQUIRED)
+find_package(mpt-crypto REQUIRED)
 find_package(nudb REQUIRED)
 find_package(OpenSSL REQUIRED)
 find_package(secp256k1 REQUIRED)
 find_package(SOCI REQUIRED)
 find_package(SQLite3 REQUIRED)
 find_package(xxHash REQUIRED)
+find_package(xrpl-rpc-spec REQUIRED)

 target_link_libraries(
    xrpl_libs
    INTERFACE
        ed25519::ed25519
+        FastFloat::fast_float
        lz4::lz4
+        mpt-crypto::mpt-crypto
        OpenSSL::Crypto
        OpenSSL::SSL
        secp256k1::secp256k1
@@ -127,16 +150,31 @@ else()
 endif()
 target_link_libraries(xrpl_libs INTERFACE ${nudb})

+if(benchmark)
+    find_package(benchmark REQUIRED)
+endif()
+
 if(coverage)
    include(XrplCov)
 endif()

+add_custom_target(tidy_prerequisites)
+
+add_subdirectory(crates)
 include(XrplCore)
 include(XrplProtocolAutogen)
 include(XrplInstall)
 include(XrplValidatorKeys)
+# Must come after XrplValidatorKeys: the 'package' target depends on the
+# validator-keys target existing.
+include(XrplPackaging)

 if(tests)
    include(CTest)
    add_subdirectory(src/tests/libxrpl)
+    add_subdirectory(src/tests/xrpld)
+endif()
+
+if(benchmark)
+    add_subdirectory(src/benchmarks/libxrpl)
 endif()
@@ -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
@@ -14,9 +14,13 @@ The following branches exist in the main project repository:

 - `develop`: The latest set of unreleased features, and the most common
  starting point for contributions.
- `release`: The latest beta release or release candidate.
- `master`: The latest stable release.
- `gh-pages`: The documentation for this project, built by Doxygen.
+- `staging/*` (e.g. `staging/3.4.x`): Staging branches, one per release line,
+  where fixes for that line are developed.
+- `release/*` (e.g. `release/3.4.x`): Release branches, one per release line,
+  holding the latest public release candidate or release for that line.
+  Releases are published as [tagged releases](https://github.com/XRPLF/rippled/releases).
+
+See [RELEASING.md](./RELEASING.md) for how these branches are used.

 The tip of each branch must be signed. In order for GitHub to sign a
 squashed commit that it builds from your pull request, GitHub must know
@@ -59,6 +63,17 @@ to an existing XLS. Neither change will be released (in an amendment's
 case, marked as `Supported::yes`) until the corresponding XLS's status
 is `Final`.

+## AI coding agents
+
+[`AGENTS.md`](./AGENTS.md) (and its `CLAUDE.md` symlink, for Claude Code) holds shared, checked-in guidance for AI coding agents working in this repository — build/test/lint commands and architecture notes. Additional `AGENTS.md` files may exist in subdirectories to give agents context specific to that part of the codebase; whenever you add one, also add a `CLAUDE.md` symlink pointing to it (`ln -s AGENTS.md CLAUDE.md`) so Claude Code picks it up too.
+
+If you want to give an agent personal instructions that shouldn't be shared with other contributors (e.g. your own workflow preferences), those are gitignored, not checked in:
+
+- `CLAUDE.local.md` — read by Claude Code alongside `CLAUDE.md`.
+- `AGENTS.override.md` — read by AGENTS.md-compatible tools that support a personal override file layered on top of `AGENTS.md`.
+
+Likewise, `.claude/settings.local.json` is for personal, untracked Claude Code settings, while `.claude/settings.json` is shared.
+
 ## Before making a pull request

 (Or marking a draft pull request as ready.)
@@ -82,9 +97,12 @@ If you create new source files, they must be organized as follows:
  under `include/xrpl`, and source (`.cpp`) files must go under
  `src/libxrpl`.
 - All other non-test files must go under `src/xrpld`.
- All test source files must go under `src/test`.
+- New test source files should use `gtest` and go under `src/tests`, unless that isn't possible, in which case they should use our legacy test framework and go under `src/test`.
+- All benchmark source files must go under `src/benchmarks`.

-The source must be formatted according to the style guide below.
+The source must be formatted according to the style guide below. The easiest
+way to satisfy this is to install the [`pre-commit`](#pre-commit-hooks) hooks,
+which format and lint your changes automatically on every commit.

 Header includes must be [levelized](.github/scripts/levelization).

@@ -130,11 +148,9 @@ tl;dr
 ## Pull requests

 In general, pull requests use `develop` as the base branch.
-The exceptions are

- Fixes and improvements to a release candidate use `release` as the
-  base.
- Hotfixes use `master` as the base.
+The exceptions are fixes for an existing release line,
+which use that line's staging branch (e.g. `staging/3.4.x`) as the base.

 If your changes are not quite ready, but you want to make it easily available
 for preliminary examination or review, you can create a "Draft" pull request.
@@ -214,13 +230,63 @@ This is a non-exhaustive list of recommended style guidelines. These are
 not always strictly enforced and serve as a way to keep the codebase
 coherent rather than a set of _thou shalt not_ commandments.

+## Pre-commit hooks
+
+We use the [`pre-commit`](https://pre-commit.com/) framework to run the
+formatting and linting tools that keep the codebase consistent. `pre-commit`
+runs each tool configured in
+[`.pre-commit-config.yaml`](./.pre-commit-config.yaml) in its own isolated
+environment, so you don't need to install most of the individual tools
+yourself. The version of each hook sourced from an external repository
+(`clang-format`, `gersemi`, etc.) is pinned in that file, so running the hooks
+locally uses exactly the same versions as CI. A few `local` hooks — most notably
+`clang-tidy` and `cargo fmt` — run tools from your own environment; see
+[Installing clang-tidy](#installing-clang-tidy) and
+[Rust](./docs/build/environment.md#rust) for how to get those.
+
+To get started, install `pre-commit` and enable the git hook scripts:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+Once installed, the hooks run automatically on your staged files every time you
+`git commit`. You can also run them on demand:
+
+```bash
+# Run all hooks against only the staged files
+pre-commit run
+
+# Run all hooks against every file in the repository
+pre-commit run --all-files
+
+# Run a single hook (e.g. clang-format) against all files
+pre-commit run clang-format --all-files
+```
+
+The hooks configured in this repository include, among others:
+
+- `clang-format` — C++/proto formatting (see [Formatting](#formatting))
+- `clang-tidy` — C++ static analysis (see [Clang-tidy](#clang-tidy)); opt in with `TIDY=1`
+- `fix-include-style`, `fix-pragma-once`, `check-doxygen-style` — C++ hygiene
+- `gersemi` — CMake formatting
+- `cargo fmt` — Rust formatting for the crates in `crates/`
+- `prettier`, `black`, `shfmt` — formatting for JavaScript/JSON/Markdown, Python, and shell
+- `cspell` — spell checking
+
+The same hooks run in CI on every pull request, so running them locally before
+you push helps you avoid CI failures.
+
 ## Formatting

-All code must conform to `clang-format` version 21,
-according to the settings in [`.clang-format`](./.clang-format),
-unless the result would be unreasonably difficult to read or maintain.
-To demarcate lines that should be left as-is, surround them with comments like
-this:
+All code must conform to `clang-format`, according to the settings in
+[`.clang-format`](./.clang-format), unless the result would be unreasonably
+difficult to read or maintain. The `clang-format` version is pinned in
+[`.pre-commit-config.yaml`](./.pre-commit-config.yaml), so the
+[`pre-commit`](#pre-commit-hooks) hook always formats with the same version as
+CI. To demarcate lines that should be left as-is, surround them with comments
+like this:

 ```
 // clang-format off
@@ -228,9 +294,21 @@ this:
 // clang-format on
 ```

-You can format individual files in place by running `clang-format -i <file>...`
+The easiest way to format your changes is to let the `pre-commit` hook run
+automatically on commit, or to run it manually:
+
+```bash
+pre-commit run clang-format --all-files
+```
+
+You can also format individual files in place by running `clang-format -i <file>...`
 from any directory within this project.

+> [!NOTE]
+> This uses whatever `clang-format` version is installed locally, which may
+> differ from the pinned version used by `pre-commit` and CI, so the results
+> can vary.
+
 There is a Continuous Integration job that runs clang-format on pull requests. If the code doesn't comply, a patch file that corrects auto-fixable formatting issues is generated.

 To download the patch file:
@@ -241,13 +319,6 @@ To download the patch file:
 4. Download the zip file and extract it to your local git repository. Run `git apply [patch-file-name]`.
 5. Commit and push.

-You can install a pre-commit hook to automatically run `clang-format` before every commit:
-
-```
-pip3 install pre-commit
-pre-commit install
-```
-
 ## Clang-tidy

 All code must pass `clang-tidy` checks according to the settings in [`.clang-tidy`](./.clang-tidy).
@@ -261,15 +332,19 @@ This ensures that configuration changes don't introduce new warnings across the

 ### Installing clang-tidy

-See the [environment setup guide](./docs/build/environment.md#clang-tidy) for platform-specific installation instructions.
+See the [environment setup guide](./docs/build/environment.md#clang-tidy) for how to get clang-tidy.

 ### Running clang-tidy locally

-Before running clang-tidy, you must build the project to generate required files (particularly protobuf headers). Refer to [`BUILD.md`](./BUILD.md) for build instructions.
+Before running clang-tidy, you must generate the files it depends on (protobuf headers and the cxxbridge headers from the Rust crates). Configure the project as described in [`BUILD.md`](./BUILD.md), then build the `tidy_prerequisites` target, which generates all of them:
+
+```bash
+cmake --build build --target tidy_prerequisites
+```

 #### Via pre-commit (recommended)

-If you have already installed the pre-commit hooks (see above), you can run clang-tidy on your staged files using:
+If you have already installed the [`pre-commit`](#pre-commit-hooks) hooks, you can run clang-tidy on your staged files using:

 ```
 TIDY=1 pre-commit run clang-tidy
@@ -294,12 +369,14 @@ run-clang-tidy -p build -allow-no-checks src tests
 ```

 This will check all source files in the `src`, `include` and `tests` directories using the compile commands from your `build` directory.
-If you wish to automatically fix whatever clang-tidy finds _and_ is capable of fixing, add `-fix` to the above command:
+If you wish to automatically fix whatever clang-tidy finds _and_ is capable of fixing, add `-fix -format` to the above command:

 ```
-run-clang-tidy -p build -quiet -fix -allow-no-checks src tests
+run-clang-tidy -p build -quiet -fix -format -allow-no-checks src tests
 ```

+`-format` reformats the fixed code with [`.clang-format`](./.clang-format); without it the fixes are inserted in LLVM style and the `clang-format` hook rewrites them afterwards.
+
 ## Contracts and instrumentation

 We are using [Antithesis](https://antithesis.com/) for continuous fuzzing,
@@ -406,8 +483,12 @@ exists, then no other unit test will be executed, apart from `TestSuiteName`.
    elsewhere in the codebase.
 12. Use clear and self-explanatory names for functions, variables,
    structs and classes.
-13. Use TitleCase for classes, structs and filenames, camelCase for
-    function and variable names, lower case for namespaces and folders.
+13. Use TitleCase for classes, structs, type aliases and filenames,
+    camelCase for function and variable names, lower case for namespaces and
+    folders. The exception is a type alias that generic code looks up by name
+    (`value_type`, `iterator`, `result_type`, and the rest of the standard
+    container, hash and clock members), which keeps its snake_case spelling;
+    `.clang-tidy` lists the names that are allowed.
 14. Provide as many comments as you feel that a competent programmer
    would need to understand what your code does.

@@ -514,15 +595,16 @@ the suggested commit message, or modify it as needed.

 #### Slightly more complicated pull requests

-Some pull requests need to be pushed to `develop` as more than one
-commit. A PR author may _request_ to merge as separate commits. They
+Some pull requests need to be pushed to their base branch (usually `develop`)
+as more than one commit.
+A PR author may _request_ to merge as separate commits. They
 must _justify_ why separate commits are needed, and _specify_ how they
 would like the commits to be merged. If you disagree with the author,
 discuss it with them directly.

 If the process is reasonable, follow it. The simplest option is to do a
-fast forward only merge (`--ff-only`) on the command line and push to
-`develop`.
+fast forward only merge (`--ff-only`) on the command line
+and push to the base branch.

 Some examples of when separate commits are worthwhile are:

@@ -535,9 +617,10 @@ Some examples of when separate commits are worthwhile are:

 Either way, check that:

- The commits are based on the current tip of `develop`.
- The commits are clean: No merge commits (except when reverse
-  merging), no "[FOLD]" or "fixup!" messages.
+- The commits are based on the current tip of the base branch.
+- The commits are clean:
+  No merge commits (except when merging a release, see [RELEASING.md](./RELEASING.md)),
+  no "[FOLD]" or "fixup!" messages.
 - All commits are signed. If the commits are not signed by the author, use
  `git commit --amend -S` to sign them yourself.
 - At least one (but preferably all) of the commits has the PR number
@@ -549,578 +632,8 @@ use them!**

 ### Releases

-All releases, including release candidates and betas, are handled
-differently from typical PRs. Most importantly, never use
-the Github UI to merge a release.
-
-Xrpld uses a linear workflow model that can be summarized as:
-
-1. In between releases, developers work against the `develop` branch.
-2. Periodically, a maintainer will build and tag a beta version from
-   `develop`, which is pushed to `release`.
-   - Betas are usually released every two to three weeks, though that
-     schedule can vary depending on progress, availability, and other
-     factors.
-3. When the changes in `develop` are considered stable and mature enough
-   to be ready to release, a release candidate (RC) is built and tagged
-   from `develop`, and merged to `release`.
-   - Further development for that release (primarily fixes) then
-     continues against `release`, while other development continues on
-     `develop`. Effectively, `release` is forked from `develop`. Changes
-     to `release` must be reverse merged to `develop`.
-4. When the candidate has passed testing and is ready for release, the
-   final release is merged to `master`.
-5. If any issues are found post-release, a hotfix / point release may be
-   created, which is merged to `master`, and then reverse merged to
-   `develop`.
-
-#### Betas, and the first release candidate
-
-##### Preparing the `develop` branch
-
-1. Optimally, the `develop` branch will be ready to go, with all
-   relevant PRs already merged.
-2. If there are any PRs pending, merge them **BEFORE** preparing the beta.
-   1. If only one or two PRs need to be merged, merge those PRs [as
-      normal](#when-and-how-to-merge-pull-requests), updating the second
-      one, and waiting for CI to finish in between.
-   2. If there are several pending PRs, do not use the Github UI,
-      because the delays waiting for CI in between each merge will be
-      unnecessarily onerous. (Incidentally, this process can also be
-      used to merge if the Github UI has issues.) Merge each PR branch
-      directly to a `release-next` on your local machine and create a single
-      PR, then push your branch to `develop`.
-      1. Squash the changes from each PR, one commit each (unless more
-         are needed), being sure to sign each commit and update the
-         commit message to include the PR number. You may be able to use
-         a fast-forward merge for the first PR.
-      2. Push your branch.
-      3. Continue to [Making the release](#making-the-release) to update
-         the version number, etc.
-
-      The workflow may look something like:
-
-```
-git fetch --multiple upstreams user1 user2 user3 [...]
-git checkout -B release-next --no-track upstream/develop
-
-# Only do an ff-only merge if pr-branch1 is either already
-# squashed, or needs to be merged with separate commits,
-# and has no merge commits.
-# Use -S on the ff-only merge if pr-branch1 isn't signed.
-git merge [-S] --ff-only user1/pr-branch1
-
-git merge --squash user2/pr-branch2
-git commit -S # Use the commit message provided on the PR
-
-git merge --squash user3/pr-branch3
-git commit -S # Use the commit message provided on the PR
-
-[...]
-
-# Make sure the commits look right
-git log --show-signature "upstream/develop..HEAD"
-
-git push --set-upstream origin
-
-# Continue to "Making the release" to update the version number, so
-# everything can be done in one PR.
-```
-
-You can also use the [squash-branches] script.
-
-You may also need to manually close the open PRs after the changes are
-merged to `develop`. Be sure to include the commit ID.
-
-##### Making the release
-
-This includes, betas, and the first release candidate (RC).
-
-1. If you didn't create one [preparing the `develop`
-   branch](#preparing-the-develop-branch), Ensure there is no old
-   `release-next` branch hanging around. Then make a `release-next`
-   branch that only changes the version number. e.g.
-
-```
-git fetch upstreams
-
-git checkout --no-track -B release-next upstream/develop
-
-v="A.B.C-bD"
-build=$( find -name BuildInfo.cpp )
-sed 's/\(^.*versionString =\).*$/\1 "'${v}'"/' ${build} > version.cpp && mv -vi version.cpp ${build}
-
-git diff
-
-git add ${build}
-
-git commit -S -m "Set version to ${v}"
-
-# You could use your "origin" repo, but some CI tests work better on upstream.
-git push upstream-push
-git fetch upstreams
-git branch --set-upstream-to=upstream/release-next
-```
-
-You can also use the [update-version] script. 2. Create a Pull Request for `release-next` with **`develop`** as
-the base branch.
-
-1.  Use the title "[TRIVIAL] Set version to X.X.X-bX".
-2.  Instead of the default description template, use the following:
-
-```
-## High Level Overview of Change
-
-This PR only changes the version number. It will be merged as
-soon as Github CI actions successfully complete.
-```
-
-3. Wait for CI to successfully complete, and get someone to approve
-   the PR. (It is safe to ignore known CI issues.)
-4. Push the updated `develop` branch using your `release-next`
-   branch. **Do not use the Github UI. It's important to preserve
-   commit IDs.**
-
-```
-git push upstream-push release-next:develop
-```
-
-5. In the unlikely event that the push fails because someone has merged
-   something else in the meantime, rebase your branch onto the updated
-   `develop` branch, push again, and go back to step 3.
-6. Ensure that your PR against `develop` is closed. Github should do it
-   automatically.
-7. Once this is done, forward progress on `develop` can continue
-   (other PRs may be merged).
-8. Now create a Pull Request for `release-next` with **`release`** as
-   the base branch. Instead of the default template, reuse and update
-   the message from the previous release. Include the following verbiage
-   somewhere in the description:
-
-```
-The base branch is `release`. [All releases (including
-betas)](https://github.com/XRPLF/rippled/blob/develop/CONTRIBUTING.md#before-you-start)
-go in `release`. This PR branch will be pushed directly to `release` (not
-squashed or rebased, and not using the GitHub UI).
-```
-
-7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
-   offline, but at least one approval will be needed on the PR.
-   - If issues are discovered during testing, simply abandon the
-     release. It's easy to start a new release, it should be easy to
-     abandon one. **DO NOT REUSE THE VERSION NUMBER.** e.g. If you
-     abandon 2.4.0-b1, the next attempt will be 2.4.0-b2.
-8. Once everything is ready to go, push to `release`.
-
-```
-git fetch upstreams
-
-# Just to be safe, do a dry run first:
-git push --dry-run upstream-push release-next:release
-
-# If everything looks right, push the branch
-git push upstream-push release-next:release
-
-# Check that all of the branches are updated
-git fetch upstreams
-git log -1 --oneline
-# The output should look like:
-# 0123456789 (HEAD -> upstream/release-next, upstream/release,
-#            upstream/develop) Set version to 2.4.0-b1
-# Note that upstream/develop may not be on this commit, but
-# upstream/release must be.
-# Other branches, including some from upstream-push, may also be
-# present.
-```
-
-9. Tag the release, too.
-
-```
-git tag <version number>
-git push upstream-push <version number>
-```
-
-10. Delete the `release-next` branch on the repo. Use the Github UI or:
-
-```
-git push --delete upstream-push release-next
-```
-
-11. Finally [create a new release on
-    Github](https://github.com/XRPLF/rippled/releases).
-
-#### Release candidates after the first
-
-Once the first release candidate is [merged into
-release](#making-the-release), then `release` and `develop` _are allowed
-to diverge_.
-
-If a bug or issue is discovered in a version that has a release
-candidate being tested, any fix and new version will need to be applied
-against `release`, then reverse-merged to `develop`. This helps keep git
-history as linear as possible.
-
-A `release-next` branch will be created from `release`, and any further
-work for that release must be based on `release-next`. Specifically,
-PRs must use `release-next` as the base, and those PRs will be merged
-directly to `release-next` when approved. Changes should be restricted
-to bug fixes, but other changes may be necessary from time to time.
-
-1. Open any PRs for the pending release using `release-next` as the base,
-   so they can be merged directly in to it. Unlike `develop`, though,
-   `release-next` can be thrown away and recreated if necessary.
-2. Once a new release candidate is ready, create a version commit as in
-   step 1 [above](#making-the-release) on `release-next`. You can use
-   the [update-version] script for this, too.
-3. Jump to step 8 ("Now create a Pull Request for `release-next` with
-   **`release`** as the base") from the process
-   [above](#making-the-release) to merge `release-next` into `release`.
-
-##### Follow up: reverse merge
-
-Once the RC is merged and tagged, it needs to be reverse merged into
-`develop` as soon as possible.
-
-1. Create a branch, based on `upstream/develop`.
-   The branch name is not important, but could include "mergeNNNrcN".
-   E.g. For release A.B.C-rcD, use `mergeABCrcD`.
-
-```
-git fetch upstreams
-
-git checkout --no-track -b mergeABCrcD upstream/develop
-```
-
-2. Merge `release` into your branch.
-
-```
-# I like the "--edit --log --verbose" parameters, but they are
-# not required.
-git merge upstream/release
-```
-
-3. `BuildInfo.cpp` will have a conflict with the version number.
-   Resolve it with the version from `develop` - the higher version.
-4. Push your branch to your repo (or `upstream` if you have permission),
-   and open a normal PR against `develop`. The "High level overview" can
-   simply indicate that this is a merge of the RC. The "Context" should
-   summarize the changes from the RC. Include the following text
-   prominently:
-
-```
-This PR must be merged manually using a push. Do not use the Github UI.
-```
-
-5. Depending on the complexity of the changes, and/or merge conflicts,
-   the PR may need a thorough review, or just a sign-off that the
-   merge was done correctly.
-6. If `develop` is updated before this PR is merged, do not merge
-   `develop` back into your branch. Instead rebase preserving merges,
-   or do the merge again. (See also the `rerere` git config setting.)
-
-```
-git rebase --rebase-merges upstream/develop
-# OR
-git reset --hard upstream/develop
-git merge upstream/release
-```
-
-7. When the PR is ready, push it to `develop`.
-
-```
-git fetch upstreams
-
-# Make sure the commits look right
-git log --show-signature "upstream/develop^..HEAD"
-
-git push upstream-push mergeABCrcD:develop
-
-git fetch upstreams
-```
-
-Development on `develop` can proceed as normal.
-
-#### Final releases
-
-A final release is any release that is not a beta or RC, such as 2.2.0.
-
-Only code that has already been tested and vetted across all three
-platforms should be included in a final release. Most of the time, that
-means that the commit immediately preceding the commit setting the
-version number will be an RC. Occasionally, there may be last-minute bug
-fixes included as well. If so, those bug fixes must have been tested
-internally as if they were RCs (at minimum, ensuring unit tests pass,
-and the app starts, syncs, and stops cleanly across all three
-platforms.)
-
-_If in doubt, make an RC first._
-
-The process for building a final release is very similar to [the process
-for building a beta](#making-the-release), except the code will be
-moving from `release` to `master` instead of from `develop` to
-`release`, and both branches will be pushed at the same time.
-
-1. Ensure there is no old `master-next` branch hanging around.
-   Then make a `master-next` branch that only changes the version
-   number. As above, or using the
-   [update-version] script.
-2. Create a Pull Request for `master-next` with **`master`** as
-   the base branch. Instead of the default template, reuse and update
-   the message from the previous final release. Include the following verbiage
-   somewhere in the description:
-
-```
-The base branch is `master`. This PR branch will be pushed directly to
-`release` and `master` (not squashed or rebased, and not using the
-GitHub UI).
-```
-
-7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
-   offline, but at least one approval will be needed on the PR.
-   - If issues are discovered during testing, close the PR, delete
-     `master-next`, and move development back to `release`, [issuing
-     more RCs as necessary](#release-candidates-after-the-first)
-8. Once everything is ready to go, push to `release` and `master`.
-
-```
-git fetch upstreams
-
-# Just to be safe, do dry runs first:
-git push --dry-run upstream-push master-next:release
-git push --dry-run upstream-push master-next:master
-
-# If everything looks right, push the branch
-git push upstream-push master-next:release
-git push upstream-push master-next:master
-
-# Check that all of the branches are updated
-git fetch upstreams
-git log -1 --oneline
-# The output should look like:
-# 0123456789 (HEAD -> upstream/master-next, upstream/master,
-#            upstream/release) Set version to A.B.0
-# Note that both upstream/release and upstream/master must be on this
-# commit.
-# Other branches, including some from upstream-push, may also be
-# present.
-```
-
-9. Tag the release, too.
-
-```
-git tag <version number>
-git push upstream-push <version number>
-```
-
-10. Delete the `master-next` branch on the repo. Use the Github UI or:
-
-```
-git push --delete upstream-push master-next
-```
-
-11. [Create a new release on
-    Github](https://github.com/XRPLF/rippled/releases). Be sure that
-    "Set as the latest release" is checked.
-12. Open a PR to update the [API-CHANGELOG](API-CHANGELOG.md) and `API-VERSION-[n].md` with the changes for this release (if any are missing).
-13. Finally, [reverse merge the release into `develop`](#follow-up-reverse-merge).
-
-#### Special cases: point releases, hotfixes, etc.
-
-On occasion, a bug or issue is discovered in a version that already
-had a final release. Most of the time, development will have started
-on the next version, and will usually have changes in `develop`
-and often in `release`.
-
-Because git history is kept as linear as possible, any fix and new
-version will need to be applied against `master`.
-
-The process for building a hotfix release is very similar to [the
-process for building release candidates after the
-first](#release-candidates-after-the-first) and [for building a final
-release](#final-releases), except the changes will be done against
-`master` instead of `release`.
-
-If there is only a single issue for the hotfix, the work can be done in
-any branch. When it's ready to merge, jump to step 3 using your branch
-instead of `master-next`.
-
-1. Create a `master-next` branch from `master`.
-
-```
-git checkout --no-track -b master-next upstream/master
-git push upstream-push
-git fetch upstreams
-```
-
-2. Open any PRs for the pending hotfix using `master-next` as the base,
-   so they can be merged directly in to it. Unlike `develop`, though,
-   `master-next` can be thrown away and recreated if necessary.
-3. Once the hotfix is ready, create a version commit using the same
-   steps as above, or use the
-   [update-version] script.
-4. Create a Pull Request for `master-next` with **`master`** as
-   the base branch. Instead of the default template, reuse and update
-   the message from the previous final release. Include the following verbiage
-   somewhere in the description:
-
-```
-The base branch is `master`. This PR branch will be pushed directly to
-`master` (not squashed or rebased, and not using the GitHub UI).
-```
-
-7. Sign-offs for the three platforms (Linux, Mac, Windows) usually occur
-   offline, but at least one approval will be needed on the PR.
-   - If issues are discovered during testing, update `master-next` as
-     needed, but ensure that the changes are properly squashed, and the
-     version setting commit remains last
-8. Once everything is ready to go, push to `master` **only**.
-
-```
-git fetch upstreams
-
-# Just to be safe, do a dry run first:
-git push --dry-run upstream-push master-next:master
-
-# If everything looks right, push the branch
-git push upstream-push master-next:master
-
-# Check that all of the branches are updated
-git fetch upstreams
-git log -1 --oneline
-# The output should look like:
-# 0123456789 (HEAD -> upstream/master-next, upstream/master) Set version
-#            to 2.4.1
-# Note that upstream/master must be on this commit. upstream/release and
-# upstream/develop should not.
-# Other branches, including some from upstream-push, may also be
-# present.
-```
-
-9. Tag the release, too.
-
-```
-git tag <version number>
-git push upstream-push <version number>
-```
-
-9. Delete the `master-next` branch on the repo.
-
-```
-git push --delete upstream-push master-next
-```
-
-10. [Create a new release on
-    Github](https://github.com/XRPLF/rippled/releases). Be sure that
-    "Set as the latest release" is checked.
-
-Once the hotfix is released, it needs to be reverse merged into
-`develop` as soon as possible. It may also need to be merged into
-`release` if a release candidate is under development.
-
-1. Create a branch in your own repo, based on `upstream/develop`.
-   The branch name is not important, but could include "mergeNNN".
-   E.g. For release 2.2.3, use `merge223`.
-
-```
-git fetch upstreams
-
-git checkout --no-track -b merge223 upstream/develop
-```
-
-2. Merge master into your branch.
-
-```
-# I like the "--edit --log --verbose" parameters, but they are
-# not required.
-git merge upstream/master
-```
-
-3. `BuildInfo.cpp` will have a conflict with the version number.
-   Resolve it with the version from `develop` - the higher version.
-4. Push your branch to your repo, and open a normal PR against
-   `develop`. The "High level overview" can simply indicate that this
-   is a merge of the hotfix version. The "Context" should summarize
-   the changes from the hotfix. Include the following text
-   prominently:
-
-```
-This PR must be merged manually using a --ff-only merge. Do not use the Github UI.
-```
-
-5. Depending on the complexity of the hotfix, and/or merge conflicts,
-   the PR may need a thorough review, or just a sign-off that the
-   merge was done correctly.
-6. If `develop` is updated before this PR is merged, do not merge
-   `develop` back into your branch. Instead rebase preserving merges,
-   or do the merge again. (See also the `rerere` git config setting.)
-
-```
-git rebase --rebase-merges upstream/develop
-# OR
-git reset --hard upstream/develop
-git merge upstream/master
-```
-
-7. When the PR is ready, push it to `develop`.
-
-```
-git fetch upstreams
-
-# Make sure the commits look right
-git log --show-signature "upstream/develop..HEAD"
-
-git push upstream-push HEAD:develop
-```
-
-Development on `develop` can proceed as normal. It is recommended to
-create a beta (or RC) immediately to ensure that everything worked as
-expected.
-
-##### An even rarer scenario: A hotfix on an old release
-
-Historically, once a final release is tagged and packages are released,
-versions older than the latest final release are no longer supported.
-However, there is a possibility that a very high severity bug may occur
-in a non-amendment blocked version that is still being run by
-a significant fraction of users, which would necessitate a hotfix / point
-release to that version as well as any later versions.
-
-This scenario would follow the same basic procedure as above,
-except that _none_ of `develop`, `release`, or `master`
-would be touched during the release process.
-
-In this example, consider if version 2.1.1 needed to be patched.
-
-1. Create two branches in the main (`upstream`) repo.
-
-```
-git fetch upstreams
-
-# Create a base branch off the tag
-git checkout --no-track -b master-2.1.2 2.1.1
-git push upstream-push
-
-# Create a working branch
-git checkout --no-track -b master212-next master-2.1.2
-git push upstream-push
-
-git fetch upstreams
-```
-
-2. Work continues as above, except using `master-2.1.2`as
-   the base branch for any merging, packaging, etc.
-3. After the release is tagged and packages are built, you could
-   potentially delete both branches, e.g. `master-2.1.2` and
-   `master212-next`. However, it may be useful to keep `master-2.1.2`
-   around indefinitely for reference.
-4. Assuming that a hotfix is also released for the latest
-   version in parallel with this one, or if the issue is
-   already fixed in the latest version, do no do any
-   reverse merges. However, if it is not, it probably makes
-   sense to reverse merge `master-2.1.2` into `master`,
-   release a hotfix for _that_ version, then reverse merge
-   from `master` to `develop`. (Please don't do this unless absolutely
-   necessary.)
+Releases, release branches, and merging releases back into `develop`
+are described in [RELEASING.md](./RELEASING.md).

 [contrib]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
 [squash]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits
@@ -1128,5 +641,3 @@ git fetch upstreams
 [xrpld]: https://github.com/XRPLF/rippled
 [signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification
 [setup-upstreams]: ./bin/git/setup-upstreams.sh
-[squash-branches]: ./bin/git/squash-branches.sh
-[update-version]: ./bin/git/update-version.sh
@@ -54,6 +54,7 @@ Here are some good places to start learning the source code:
 | `./docs`   | Source documentation files and doxygen config. |
 | `./cfg`    | Example configuration files.                   |
 | `./src`    | Source code.                                   |
+| `./crates` | Rust source code.                              |

 Some of the directories under `src` are external repositories included using
 git-subtree. See those directories' README files for more details.
@@ -0,0 +1,152 @@
+# Branching and Release Management
+
+This document describes how we branch, release, and merge releases back into `develop`.
+It does not define version naming
+(e.g., what constitutes a major-minor, patch, or beta release).
+
+Examples use `X.Y` for a release line:
+`X` and `Y` are placeholders, while the trailing `x` is literal,
+e.g., `release/X.Y.x` is `release/3.4.x` for the `3.4` line.
+
+## Branches
+
+| Branch          | Purpose                                                                                   |
+| :-------------- | :---------------------------------------------------------------------------------------- |
+| `develop`       | Main development branch. Betas and the first RC of a major-minor release are tagged here. |
+| `staging/X.Y.x` | Where fixes for the `X.Y` line are developed and RCs are prepared.                        |
+| `release/X.Y.x` | The last public RC or release of the `X.Y` line.                                          |
+
+A release line is named `X.Y.x`
+because one branch serves every patch release of that line (`X.Y.0`, `X.Y.1`, `X.Y.2`, ...).
+The `/` groups branches hierarchically,
+so tools can filter them and protection rules can target `release/*` and `staging/*`.
+
+## Principles
+
+- **Releases are merged back into `develop`, never cherry-picked or rebased onto it.**
+  Cherry-picked and rebased commits get new hashes,
+  so Git can't tell that `develop` already has them.
+  Future merges then replay them and produce artificial conflicts,
+  and it's hard to verify that every fix actually reached `develop`.
+  Merging keeps a single history:
+  Git knows exactly which release commits `develop` contains,
+  and no fix is left behind.
+- **Branches only move forward.**
+  `develop`, `staging/X.Y.x`, and `release/X.Y.x` are never rewritten.
+- **Cherry-picking only goes from `develop` to a staging branch**,
+  for fixes that must get into a release after the code freeze
+  (see [Emergency Fixes From `develop`](#emergency-fixes-from-develop)).
+- **Security fixes are prepared privately and published with the release that contains them**,
+  so vulnerabilities are not disclosed prematurely.
+
+## Release Lifecycle
+
+This diagram shows a major-minor release and its first patch release.
+The staging and release branches are drawn as one line.
+
+```text
+develop                            staging/X.Y.x & release/X.Y.x
+   │
+   ├── Tag: X.Y.0-b1
+   ├── Tag: X.Y.0-bN
+   ├── Tag: X.Y.0-rc1 ───────────────┐ (branches created)
+   │                                 │
+   │  (development continues)        ├── Fixes
+   │                                 ├── Tag: X.Y.0-rcN
+   │                                 ├── Tag: X.Y.0 (final)
+   ◀──── (merge) ────────────────────┤
+   │                                 ├── Fixes
+   │                                 ├── Tag: X.Y.1-rcN
+   │                                 ├── Tag: X.Y.1 (final)
+   ◀──── (merge) ────────────────────┤
+   │
+   ▼
+```
+
+### Betas, First RC & Branching
+
+> [!NOTE]
+> This phase applies only to a new major-minor release (e.g., `X.Y.0`).
+> Patch releases work on the existing branches of the line.
+
+1. **Betas:** All beta versions (e.g., `X.Y.0-b1`) are built and tagged directly on `develop`.
+2. **First RC:** We release the first RC (`X.Y.0-rc1`)
+   once everything that should be included in the release has been merged.
+3. **Branches:** `staging/X.Y.x` and `release/X.Y.x` are created from `develop`
+   at the commit tagged `X.Y.0-rc1`.
+   The first RC also kicks off the QE process.
+4. **Code freeze:** No new features or unrelated changes are pulled from `develop`
+   into `staging/X.Y.x` or `release/X.Y.x`.
+   Only critical stabilization fixes go into the line.
+5. **No large changes on `develop`:** Until `X.Y.0` is [merged back](#merging-back-into-develop),
+   large changes (e.g., big refactors, moving or renaming many files, mass reformatting)
+   are not merged into `develop`,
+   so that fixes on the line and the merge back don't run into conflicts.
+
+### Release Candidates
+
+1. Fixes are developed against `staging/X.Y.x`.
+2. When ready, a new RC is created on `staging/X.Y.x`,
+   and `release/X.Y.x` is fast-forwarded to it.
+
+RCs that contain unpublished security fixes are not published,
+and don't touch the public branches.
+
+RCs are not merged back into `develop`:
+`X.Y.0-rc1` is tagged on `develop` itself,
+and all later changes reach `develop` with the [final release](#final-release).
+
+### Final Release
+
+Security fixes become public as soon as they reach the public repo,
+so these steps happen only once the release is ready to be published,
+one right after the other.
+
+1. Unpublished security fixes, if any, are merged into `staging/X.Y.x`.
+2. `release/X.Y.x` is fast-forwarded to `staging/X.Y.x`,
+   and the release is tagged on it.
+3. The release is immediately [merged back into `develop`](#merging-back-into-develop).
+   For a major-minor release, this lifts the freeze on large changes in `develop`.
+
+### Merging Back Into `develop`
+
+The merge back is a regular PR into `develop`
+whose branch contains a real merge commit of the release tag:
+
+1. Create a branch from `develop`, run `git merge --no-ff <tag>`, and resolve any conflicts.
+2. Once the PR is approved, `develop` is fast-forwarded to the PR branch,
+   so the merge commit lands as it is.
+   Never squash or rebase it.
+   Never add it to the merge queue either: the queue squashes PRs, which would drop the merge commit.
+3. If `develop` moves while the PR is open, redo the merge on top of the new `develop`.
+
+After the merge, `git log develop..<tag>` must be empty.
+
+## Special Cases
+
+### Emergency Fixes From `develop`
+
+If a commit was merged to `develop`
+and needs to be included in a release after the code freeze:
+
+1. Create a PR that cherry-picks the commit onto `staging/X.Y.x`.
+2. Leave `develop` as it is, with no reverts.
+3. Follow the [release candidates](#release-candidates) process as usual.
+
+When the release is later merged back into `develop`,
+both sides already contain the same change,
+so the merge usually resolves it cleanly or with a trivial conflict.
+From Git's perspective, the cherry-picked commit then becomes part of `develop` too.
+
+### Several Supported Lines
+
+When a fix must ship in more than one supported line (e.g., `X.Y` and `X.(Y+1)`),
+the lines are merged upwards rather than cherry-picked between:
+
+1. The fix goes into the oldest line first.
+2. After that line's release,
+   its `release/X.Y.x` is merged into the staging branch of the next newer line,
+   and so on up to the newest line.
+3. The newest line is merged back into `develop` as usual.
+
+This way every newer line, and eventually `develop`, contains the history of the older lines.
@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+#
+# check-tools.sh — verify the xrpld development tooling is present and runnable.
+#
+# Works on Linux, macOS, and Windows (Git Bash / MSYS). For every expected tool
+# it runs a version probe, collecting anything that is missing or fails to run,
+# and prints a summary at the end (exiting non-zero if anything is missing).
+#
+# The tool set is platform-aware:
+#   - Linux:   the full Nix CI environment (see nix/packages.nix, nix/ci-env.nix),
+#              with GCC, Clang and the sanitizer/coverage tooling. This script is
+#              run during the Nix Docker image build (nix/docker/Dockerfile), so
+#              the Linux list is kept in sync with that environment.
+#   - macOS:   the same tooling, minus GCC/g++/gcov/mold
+#   - Windows: the core build tools only (CMake, Conan, Git, Python).
+#              MSVC is expected to be provided separately and is not checked here.
+#
+# Some tools (clang-format, clang-tidy, doxygen, gcovr, gh, git-cliff, gpg,
+# pre-commit, run-clang-tidy) are present in our Linux CI images and in local
+# development setups, but not in the macOS CI environment. They are checked
+# everywhere except when running in CI on macOS.
+#
+# Tools that Nix also exposes under a version-suffixed name
+# (`clang-tidy-<v>`, `g++-<v>`, ...) are probed under both names:
+# a suffixed name can break while the plain one still works
+# (see mkVersionedToolLinks in nix/packages.nix).
+# The suffix is the major version of the plain `clang` / `gcc` on PATH.
+#
+# Tools scoped to a single dev shell rather than to commonPackages are checked
+# only in that shell, keyed off XRPL_DEVSHELL.
+#
+# Environment variables:
+#   CI                      if set, skip the tools above when on macOS.
+#   CHECK_TOOLS_SKIP_CLONE  if set, skip the git-over-HTTPS connectivity check.
+#   XRPL_DEVSHELL           active dev shell; selects shell-specific tools.
+
+set -uo pipefail
+
+# major_version <compiler>
+# Major version of a compiler on PATH, or "unknown" when it isn't there.
+major_version() {
+    local version
+    version="$("$1" -dumpversion 2>/dev/null)" || version=""
+    version="${version%%.*}"
+    printf '%s' "${version:-unknown}"
+}
+
+llvm_version="$(major_version clang)"
+
+missing=()
+checked=0
+
+# tool_path <name>
+# Fully resolved path of a tool, so the snapshots record which derivation
+# provides it. Prints nothing when it isn't on PATH.
+tool_path() {
+    local path
+    path="$(command -v "$1" 2>/dev/null)" || return 0
+    readlink -f "${path}" 2>/dev/null || printf '%s' "${path}"
+}
+
+# check <name> [probe-command...]
+# Runs the probe (default: "<name> --version"), capturing both stdout and
+# stderr, and prints three lines: the status and name, the first non-blank line
+# of the probe output (its version, or the error when it failed), and the tool's
+# resolved path. Records <name> as missing if it is not found or exits non-zero.
+check() {
+    local name="$1"
+    shift
+    local -a probe=("$@")
+    if [ "${#probe[@]}" -eq 0 ]; then
+        probe=("${name}" --version)
+    fi
+
+    checked=$((checked + 1))
+    local output version path
+    path="$(tool_path "${name}")"
+    if output="$("${probe[@]}" 2>&1)"; then
+        printf '  ✅ %s\n' "${name}"
+    else
+        printf '  ❌ %s\n' "${name}"
+        missing+=("${name}")
+    fi
+    version="$(printf '%s\n' "${output}" | grep -m1 '[^[:space:]]' || true)"
+    printf '     %s\n' "${version:-(no output)}"
+    printf '     %s\n' "${path:-(not found)}"
+}
+
+case "$(uname -s)" in
+    Linux*) os=linux ;;
+    Darwin*) os=macos ;;
+    MINGW* | MSYS* | CYGWIN*) os=windows ;;
+    *)
+        echo "Unknown OS: $(uname -s)" >&2
+        exit 1
+        ;;
+esac
+
+echo "Detected OS: ${os} ($(uname -s) $(uname -m))"
+echo
+echo "Core build tools:"
+check cmake
+check conan
+check git
+if [ "${os}" = "windows" ]; then
+    check python python --version
+else
+    check python3
+fi
+
+# The full development toolchain. Available from Nix on Linux and macOS; on
+# Windows these are typically not installed, so they are skipped.
+if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
+    echo
+    echo "Development tooling:"
+    check ccache
+    check clang
+    check "clang-${llvm_version}"
+    check clang++
+    check "clang++-${llvm_version}"
+    check ClangBuildAnalyzer
+    check curl
+    check file
+    check jq
+    check less
+    check make
+    # 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 perl -e 'print "$^V\n"'
+    check pkg-config
+    check vim
+    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
+    # except when running in CI on macOS.
+    if [ "${os}" = "linux" ] || [ -z "${CI:-}" ]; then
+        check clang-apply-replacements
+        check "clang-apply-replacements-${llvm_version}"
+        check clang-format
+        check "clang-format-${llvm_version}"
+        # clang-tidy leads --version with the LLVM banner, not the version.
+        tidy_probe="--version | grep -m1 -oE 'LLVM version [0-9.]+'"
+        check clang-tidy sh -c "clang-tidy ${tidy_probe}"
+        check "clang-tidy-${llvm_version}" sh -c "clang-tidy-${llvm_version} ${tidy_probe}"
+        check dot
+        check doxygen
+        check gcovr
+        check gh
+        check git-cliff
+        check git-lfs
+        check gpg
+        # pre-commit, or its alternative implementation prek
+        check pre-commit sh -c 'pre-commit --version || prek --version'
+        check run-clang-tidy run-clang-tidy --help
+        check "run-clang-tidy-${llvm_version}" "run-clang-tidy-${llvm_version}" --help
+    fi
+fi
+
+# Rust toolchain. Part of the Nix commonPackages, so available on both Linux
+# and macOS. The cargo plugins are invoked through cargo (`cargo <sub>`), which
+# resolves the matching `cargo-<sub>` binary on PATH; `--version` is offline and
+# does not need a Cargo project.
+if [ "${os}" = "linux" ] || [ "${os}" = "macos" ]; then
+    echo
+    echo "Rust toolchain:"
+    check cargo
+    check cargo-audit cargo audit --version
+    check cargo-llvm-cov cargo llvm-cov --version
+    check cargo-nextest cargo nextest --version
+    check clippy-driver
+    check rust-analyzer
+    check rust-nightly rust-nightly run rustc --version
+    check rustc
+    check rustfmt
+fi
+
+# Lean4 is in the formal-verification shell only, not in commonPackages.
+if [ "${XRPL_DEVSHELL:-}" = "formal-verification" ]; then
+    echo
+    echo "Formal verification toolchain:"
+    check lean
+    check lake
+fi
+
+# GCC is the default compiler on Linux. macOS uses the system Apple Clang
+# instead, so GCC/g++/gcov are not expected there.
+if [ "${os}" = "linux" ]; then
+    echo
+    echo "GCC toolchain:"
+    gcc_version="$(major_version gcc)"
+    check gcc
+    check "gcc-${gcc_version}"
+    check g++
+    check "g++-${gcc_version}"
+    check cpp
+    check "cpp-${gcc_version}"
+    check gcov
+
+    echo
+    echo "Mold:"
+    check mold
+fi
+
+if [ "${os}" = "windows" ]; then
+    echo
+    echo "Note: on Windows the C++ compiler is MSVC, which is provided"
+    echo "      separately (e.g. via Visual Studio) and is not checked here."
+fi
+
+# A simple test to verify that git can clone a repository over HTTPS
+# (i.e. the CA bundle is wired up). Clone to a temp dir and clean up.
+if [ -n "${CHECK_TOOLS_SKIP_CLONE:-}" ]; then
+    echo
+    echo "Skipping git-over-HTTPS check (CHECK_TOOLS_SKIP_CLONE is set)."
+else
+    echo
+    echo "Connectivity check:"
+    checked=$((checked + 1))
+    tmp_clone="$(mktemp -d)"
+    if git clone --depth 1 https://github.com/XRPLF/actions.git "${tmp_clone}/actions" >/dev/null 2>&1; then
+        printf '  ✅ git clone over HTTPS\n'
+    else
+        printf '  ❌ git clone over HTTPS\n'
+        missing+=("git-https-clone")
+    fi
+    rm -rf "${tmp_clone}"
+fi
+
+echo
+if [ "${#missing[@]}" -eq 0 ]; then
+    echo "✅ All ${checked} checked tools are present and runnable."
+else
+    echo "❌ Missing or non-functional tools (${#missing[@]} of ${checked}):" >&2
+    for tool in "${missing[@]}"; do
+        echo "  - ${tool}" >&2
+    done
+    exit 1
+fi
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+
+"""
+Reduce run-clang-tidy output to its unique errors.
+
+It does two things:
+
+  1. Filters the raw output down to diagnostics and their source-context lines
+     (the indented "  103 | ..." / "      | ^" lines clang-tidy prints),
+     matching the "path:line:col: error:" diagnostic shape.
+
+  2. Deduplicates. The same diagnostic in a header is reported once per
+     translation unit that includes it, so identical error blocks are collapsed
+     to their first occurrence.
+
+An "error block" is an "error:" line together with the indented context lines
+and any "note:" lines that follow it (up to the next "error:" line). Blocks are
+compared as a whole, so an error stays attached to its own context, and
+first-occurrence order is preserved.
+
+The deduplicated output goes to stdout; a summary of unique error counts per
+check is printed to stderr.
+
+Usage:
+  bin/filter-clang-tidy.py [INPUT_FILE]            # read from file, or
+  run-clang-tidy ... | bin/filter-clang-tidy.py    # read from stdin
+"""
+
+import re
+import sys
+from collections import Counter
+
+# A clang-tidy diagnostic line looks like "path:line:col: error: msg [check]".
+# Matching on that shape (rather than a loose "error" substring) avoids treating
+# progress lines whose paths contain "error" as diagnostics, e.g.
+#   [284/850][0.7s] /nix/.../clang-tidy ... src/.../error.cpp
+DIAG_RE = re.compile(r":\d+:\d+: (?:error|warning|note):")
+ERROR_RE = re.compile(r":\d+:\d+: error:")
+CHECK_RE = re.compile(r" error: .*\[([^\],]+)")
+
+
+def filter_and_dedup(lines: list[str]) -> list[str]:
+    """Keep diagnostics with their context, then drop duplicate error blocks."""
+    blocks: list[str] = []
+    seen: set[str] = set()
+    current: list[str] = []
+
+    def flush() -> None:
+        if not current:
+            return
+        block = "".join(current)
+        if block not in seen:
+            seen.add(block)
+            blocks.append(block)
+
+    for line in lines:
+        # Keep only diagnostics and their indented source-context lines; drop
+        # progress/status output and blank lines.
+        if not (DIAG_RE.search(line) or line[:1] in (" ", "\t")):
+            continue
+        # An "error:" line starts a new block; its context and any following
+        # "note:" lines (and their context) belong to it.
+        if ERROR_RE.search(line):
+            flush()
+            current = []
+        current.append(line)
+    flush()
+
+    return blocks
+
+
+def summarize(blocks: list[str]) -> Counter[str]:
+    """Count unique errors per check name (e.g. "bugprone-branch-clone")."""
+    counts: Counter[str] = Counter()
+    for block in blocks:
+        # The error line is the first line of the block.
+        match = CHECK_RE.search(block.splitlines()[0])
+        if match:
+            counts[match.group(1)] += 1
+    return counts
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] != "-":
+        with open(sys.argv[1], encoding="utf-8") as f:
+            lines = f.readlines()
+    else:
+        lines = sys.stdin.readlines()
+
+    blocks = filter_and_dedup(lines)
+    # Blank line between blocks so distinct errors are easy to tell apart.
+    sys.stdout.write("\n".join(blocks))
+
+    print("\nUnique errors per check:", file=sys.stderr)
+    for check, count in summarize(blocks).most_common():
+        print(f"{count:>4} {check}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -1,8 +1,8 @@
 #!/bin/bash

 if [[ $# -ne 1 || "$1" == "--help" || "$1" == "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
+    name=$(basename $0)
+    cat <<-USAGE
    Usage: $name <username>

    Where <username> is the Github username of the upstream repo. e.g. XRPLF
@@ -14,7 +14,7 @@ fi
 shift
 user="$1"
 # Get the origin URL. Expect it be an SSH-style URL
-origin=$( git remote get-url origin )
+origin=$(git remote get-url origin)
 if [[ "${origin}" == "" ]]; then
    echo Invalid origin remote >&2
    exit 1
@@ -22,11 +22,11 @@ fi
 # echo "Origin: ${origin}"
 # Parse the origin
 ifs_orig="${IFS}"
-IFS=':' read remote originpath <<< "${origin}"
+IFS=':' read remote originpath <<<"${origin}"
 # echo "Remote: ${remote}, Originpath: ${originpath}"
-IFS='@' read sshuser server <<< "${remote}"
+IFS='@' read sshuser server <<<"${remote}"
 # echo "SSHUser: ${sshuser}, Server: ${server}"
-IFS='/' read originuser repo <<< "${originpath}"
+IFS='/' read originuser repo <<<"${originpath}"
 # echo "Originuser: ${originuser}, Repo: ${repo}"
 if [[ "${sshuser}" == "" || "${server}" == "" || "${originuser}" == "" || "${repo}" == "" ]]; then
    echo "Can't parse origin URL: ${origin}" >&2
@@ -35,9 +35,9 @@ fi
 upstream="https://${server}/${user}/${repo}"
 upstreampush="${remote}:${user}/${repo}"
 upstreamgroup="upstream upstream-push"
-current=$( git remote get-url upstream 2>/dev/null )
-currentpush=$( git remote get-url upstream-push 2>/dev/null )
-currentgroup=$( git config remotes.upstreams )
+current=$(git remote get-url upstream 2>/dev/null)
+currentpush=$(git remote get-url upstream-push 2>/dev/null)
+currentgroup=$(git config remotes.upstreams)
 if [[ "${current}" == "${upstream}" ]]; then
    echo "Upstream already set up correctly. Skip"
 elif [[ -n "${current}" && "${current}" != "${upstream}" && "${current}" != "${upstreampush}" ]]; then
@@ -45,9 +45,9 @@ elif [[ -n "${current}" && "${current}" != "${upstream}" && "${current}" != "${u
 else
    if [[ "${current}" == "${upstreampush}" ]]; then
        echo "Upstream set to dangerous push URL. Update."
-        _run git remote rename upstream upstream-push || \
-        _run git remote remove upstream
-        currentpush=$( git remote get-url upstream-push 2>/dev/null )
+        _run git remote rename upstream upstream-push ||
+            _run git remote remove upstream
+        currentpush=$(git remote get-url upstream-push 2>/dev/null)
    fi
    _run git remote add upstream "${upstream}"
 fi
@@ -1,8 +1,8 @@
 #!/bin/bash

 if [[ $# -lt 3 || "$1" == "--help" || "$1" = "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
+    name=$(basename $0)
+    cat <<-USAGE
    Usage: $name workbranch base/branch user/branch [user/branch [...]]

    * workbranch will be created locally from base/branch
@@ -16,7 +16,7 @@ fi
 work="$1"
 shift

-branches=( $( echo "${@}" | sed "s/:/\//" ) )
+branches=($(echo "${@}" | sed "s/:/\//"))
 base="${branches[0]}"
 unset branches[0]

@@ -24,10 +24,10 @@ set -e

 users=()
 for b in "${branches[@]}"; do
-    users+=( $( echo $b | cut -d/ -f1 ) )
+    users+=($(echo $b | cut -d/ -f1))
 done

-users=( $( printf '%s\n' "${users[@]}" | sort -u ) )
+users=($(printf '%s\n' "${users[@]}" | sort -u))

 git fetch --multiple upstreams "${users[@]}"
 git checkout -B "$work" --no-track "$base"
@@ -40,7 +40,7 @@ done
 # Make sure the commits look right
 git log --show-signature "$base..HEAD"

-parts=( $( echo $base | sed "s/\// /" ) )
+parts=($(echo $base | sed "s/\// /"))
 repo="${parts[0]}"
 b="${parts[1]}"
 push=$repo
@@ -50,7 +50,7 @@ fi
 if [[ "$repo" == "upstream" ]]; then
    repo="upstreams"
 fi
-cat << PUSH
+cat <<PUSH

 -------------------------------------------------------------------
 This script will not push. Verify everything is correct, then push
@@ -1,56 +0,0 @@
-#!/bin/bash
-
-if [[ $# -ne 3 || "$1" == "--help" || "$1" = "-h" ]]; then
-    name=$( basename $0 )
-    cat <<- USAGE
-    Usage: $name workbranch base/branch version
-
-    * workbranch will be created locally from base/branch. If it exists,
-        it will be reused, so make sure you don't overwrite any work.
-    * base/branch may be specified as user:branch to allow easy copying
-        from Github PRs.
-USAGE
-    exit 0
-fi
-
-work="$1"
-shift
-
-base=$( echo "$1" | sed "s/:/\//" )
-shift
-
-version=$1
-shift
-
-set -e
-
-git fetch upstreams
-
-git checkout -B "${work}" --no-track "${base}"
-
-push=$( git rev-parse --abbrev-ref --symbolic-full-name '@{push}' \
-    2>/dev/null ) || true
-if [[ "${push}" != "" ]]; then
-    echo "Warning: ${push} may already exist."
-fi
-
-build=$( find -name BuildInfo.cpp )
-sed 's/\(^.*versionString =\).*$/\1 "'${version}'"/' ${build} > version.cpp && \
-diff "${build}" version.cpp && exit 1 || \
-mv -vi version.cpp ${build}
-
-git diff
-
-git add ${build}
-
-git commit -S -m "Set version to ${version}"
-
-git log --oneline --first-parent ${base}^..
-
-cat << PUSH
-
-------------------------------------------------------------------
-This script will not push. Verify everything is correct, then push
-to your repo, and create a PR as described in CONTRIBUTING.md.
-------------------------------------------------------------------
-PUSH
@@ -0,0 +1,86 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if [ ! -f /etc/os-release ]; then
+    echo "ERROR: /etc/os-release not found; cannot detect OS" >&2
+    exit 1
+fi
+
+# shellcheck source=/dev/null
+. /etc/os-release
+
+echo "Detected OS: ${ID} ${VERSION_ID:-}"
+
+case "${ID}" in
+    ubuntu | debian | rhel | centos | rocky | almalinux)
+        echo "Supported OS detected: ${ID}"
+        ;;
+    *)
+        echo "ERROR: unsupported OS '${ID}'. Supported: debian, ubuntu, rhel-family" >&2
+        exit 1
+        ;;
+esac
+
+# Packaging runs in a vanilla distro image, so the tooling comes from the distro's
+# archive rather than from nixpkgs:
+#
+#   - debhelper and dpkg-dev build the DEB, and lintian checks it
+#   - binutils gives debian/rules the readelf its glibc-floor check runs; it
+#     already arrives via dpkg-dev, but that tool is called directly
+#   - rpm-build builds the RPM, with systemd-rpm-macros and redhat-rpm-config
+#     supplying the systemd and find-debuginfo macros the spec uses
+#   - rpm-sign and gnupg2 sign the built RPM
+#   - python3 runs the packaging scripts
+#   - git gives build_pkg.py the commit timestamp it stamps files with
+#   - ca-certificates lets git and the packaging scripts verify TLS
+function install() {
+    case "${ID}" in
+        debian | ubuntu)
+            apt-get update -y
+            apt-get install -y --no-install-recommends \
+                binutils \
+                ca-certificates \
+                debhelper \
+                debhelper-compat \
+                dpkg-dev \
+                git \
+                lintian \
+                python3
+            ;;
+
+        rhel | centos | rocky | almalinux)
+            dnf install -y --setopt=install_weak_deps=False \
+                git \
+                gnupg2 \
+                python3 \
+                redhat-rpm-config \
+                rpm-build \
+                rpm-sign \
+                systemd-rpm-macros
+            ;;
+    esac
+}
+
+function postinstall() {
+    # Don't clear cache in non-CI environments
+    if [ -z "${CI:-}" ]; then
+        echo "Not running in CI environment; skipping cache cleanup"
+        return
+    fi
+
+    case "${ID}" in
+        debian | ubuntu)
+            apt-get clean
+            rm -rf /var/lib/apt/lists/*
+            ;;
+
+        rhel | centos | rocky | almalinux)
+            dnf clean -y all
+            rm -rf /var/cache/dnf/*
+            ;;
+    esac
+}
+
+install
+postinstall
@@ -0,0 +1,113 @@
+#!/bin/bash
+# Install sanitizer runtime libraries required to run binaries compiled with:
+#   -fsanitize=address   → libasan.so.8
+#   -fsanitize=thread    → libtsan.so.2
+#   -fsanitize=undefined → libubsan.so.1
+#
+# The exact SONAMEs required depend on the compiler toolchain used to build the
+# test binaries (see nix/ci-env.nix). If the toolchain is bumped and SONAMEs
+# change, update the list below (or detect them from the binaries).
+#
+# Supported base images:
+#   debian:bookworm
+#   ubuntu:20.04
+#   rhel:9
+#   nixos/nix        — tests are skipped; this script is not called
+
+set -euo pipefail
+
+if [ ! -f /etc/os-release ]; then
+    echo "ERROR: /etc/os-release not found; cannot detect OS" >&2
+    exit 1
+fi
+
+# shellcheck source=/dev/null
+. /etc/os-release
+
+echo "Detected OS: ${ID} ${VERSION_ID:-}"
+
+case "${ID}" in
+    ubuntu | debian | rhel | centos | rocky | almalinux)
+        echo "Supported OS detected: ${ID}"
+        ;;
+    *)
+        echo "ERROR: unsupported OS '${ID}'. Supported: debian, ubuntu, rhel-family" >&2
+        exit 1
+        ;;
+esac
+
+function preinstall() {
+    case "${ID}" in
+        ubuntu)
+            apt-get update -y
+            apt-get install -y --no-install-recommends \
+                gnupg \
+                software-properties-common
+            add-apt-repository -y ppa:ubuntu-toolchain-r/test
+            ;;
+    esac
+}
+
+function install() {
+    case "${ID}" in
+        debian | ubuntu)
+            apt-get update -y
+            apt-get install -y --no-install-recommends \
+                libasan8 \
+                libtsan2 \
+                libubsan1
+            ;;
+
+        rhel | centos | rocky | almalinux)
+            dnf install -y \
+                libasan8 \
+                libtsan2 \
+                libubsan
+            ;;
+    esac
+}
+
+function postinstall() {
+    # Don't clear cache in non-CI environments
+    if [ -z "${CI:-}" ]; then
+        echo "Not running in CI environment; skipping cache cleanup"
+        return
+    fi
+
+    case "${ID}" in
+        debian | ubuntu)
+            apt-get clean
+            rm -rf /var/lib/apt/lists/*
+            ;;
+
+        rhel | centos | rocky | almalinux)
+            dnf clean -y all
+            rm -rf /var/cache/dnf/*
+            ;;
+    esac
+}
+
+function verify() {
+    # Verify that every expected library is now resolvable by the dynamic linker.
+    missing=0
+    for lib in libasan.so.8 libtsan.so.2 libubsan.so.1; do
+        if ldconfig -p | grep -q "${lib}"; then
+            echo "OK: ${lib} found"
+        else
+            echo "ERROR: ${lib} not found after installation" >&2
+            missing=$((missing + 1))
+        fi
+    done
+
+    if [ "${missing}" -ne 0 ]; then
+        echo "ERROR: ${missing} library/libraries missing" >&2
+        exit 1
+    fi
+}
+
+preinstall
+install
+postinstall
+verify
+
+echo "All sanitizer runtime libraries installed successfully."
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Fail if a binary of a build-context Conan package loads anything from the Nix
+# store other than glibc, or cannot resolve a library at all.
+#
+# Only binaries linked by the Nix toolchain are checked, i.e. those recording a
+# store path as their interpreter or RUNPATH. Prebuilt upstream binaries (such
+# as the ones the cmake package ships) use the system loader instead.
+#
+# Build-context packages provide the tools that run during the build (protoc,
+# grpc_cpp_plugin, ...). Their package ID does not change when a Nix toolchain
+# update moves the GCC runtime to a new store path, so a cached binary has to
+# get by with the pinned glibc alone. See docs/build/nix.md.
+#
+# Usage: bin/nix/check-build-context-runtime.sh <graph.json>
+#   <graph.json> is the output of `conan install --format=json`.
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+    echo "usage: $0 <graph.json>" >&2
+    exit 2
+fi
+
+if [ "$(uname -s)" != "Linux" ]; then
+    echo "$0: Linux only" >&2
+    exit 2
+fi
+
+folders="$(jq -r '.graph.nodes[] | select(.context == "build" and .package_folder) | .package_folder' "$1" | sort -u)"
+
+checked=0
+failed=0
+
+while IFS= read -r file; do
+    case "$(file -b "${file}")" in
+        ELF*) ;;
+        *) continue ;;
+    esac
+    [[ "$(readelf -ldW "${file}")" == */nix/store/* ]] || continue
+    checked=$((checked + 1))
+
+    # `ldd` lists the interpreter and every library as the loader resolves them.
+    if deps="$(ldd "${file}" 2>&1)"; then
+        bad="$(printf '%s\n' "${deps}" |
+            grep -E 'not found|/nix/store/' |
+            grep -vE '/nix/store/[^/]+-glibc-[^/]+/' || true)"
+    else
+        case "${deps}" in
+            *"not a dynamic executable"*) continue ;;
+        esac
+        bad="${deps}"
+    fi
+    if [ -n "${bad}" ]; then
+        failed=$((failed + 1))
+        echo "::error file=${file}::loads a library from the Nix store other than glibc"
+        echo "${file}"
+        echo "${bad}" | sed 's/^/    /'
+    fi
+done < <(
+    # shellcheck disable=SC2086 # one folder per line, no spaces in Conan paths
+    [ -z "${folders}" ] || find ${folders} -type f \( -perm -u+x -o -name '*.so*' \)
+)
+
+echo "Build-context packages: checked ${checked} binaries, ${failed} failed."
+[ "${failed}" -eq 0 ]
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Fail if a binary under <path> records a /nix/store path it resolves at run
+# time. See docs/build/nix.md#prebuilt-packages for why that matters.
+#
+# <path> is a file or a directory. macOS: nothing may reference the store, so
+# point it at whole trees. Linux: the toolchain always writes the store into
+# PT_INTERP and RUNPATH, so only at what cmake/PatchNixBinary.cmake retargets.
+#
+# Only Mach-O / ELF is inspected. Static archives hold store paths in debug info
+# alone; the scripts in a Conan cache are all git hook samples and autotools
+# scratch, 36 false positives to 0 real.
+#
+# Usage: bin/nix/check-nix-store-refs.sh <path>
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+    echo "usage: $0 <path>" >&2
+    exit 2
+fi
+
+if [ ! -e "$1" ]; then
+    echo "$0: no such path: $1" >&2
+    exit 2
+fi
+
+case "$(uname -s)" in
+    Darwin)
+        format=Mach-O
+        recorded_paths=macho_recorded_paths
+        tool=otool
+        ;;
+    Linux)
+        format=ELF
+        recorded_paths=elf_recorded_paths
+        tool=readelf
+        ;;
+    *)
+        echo "Unsupported OS - skipping the Nix store reference check."
+        exit 0
+        ;;
+esac
+
+# `pipefail` would catch this too, but only as a bare nonzero exit.
+if ! command -v "${tool}" >/dev/null; then
+    echo "$0: ${tool} not found; cannot inspect binaries" >&2
+    exit 2
+fi
+
+# Both list what the file records. `ldd` would answer what this machine resolves
+# now, which is wrong both ways: store paths for a correctly patched binary,
+# silence for a store RUNPATH that resolves nowhere.
+
+# `name` covers LC_ID_DYLIB and LC_LOAD*_DYLIB, `path` covers LC_RPATH.
+macho_recorded_paths() {
+    otool -l "$1" | sed -nE 's#^ *(name|path) ([^ ]*).*#\2#p'
+}
+
+# RPATH and RUNPATH are colon-separated.
+elf_recorded_paths() {
+    readelf -ldW "$1" |
+        sed -nE \
+            -e 's#.*program interpreter: ([^]]*)\].*#\1#p' \
+            -e 's#.*\((RPATH|RUNPATH|NEEDED)\).*\[([^]]*)\].*#\2#p' |
+        tr ':' '\n'
+}
+
+checked=0
+skipped=0
+leaked=0
+
+while IFS= read -r file; do
+    case "$(file -b "${file}" 2>/dev/null)" in
+        *"${format}"*) ;;
+        *)
+            skipped=$((skipped + 1))
+            continue
+            ;;
+    esac
+    checked=$((checked + 1))
+
+    # Filter after extracting, or a search path starting elsewhere ($ORIGIN)
+    # hides the rest. `sed` not `grep`: grep calls "no matches" a failure, and
+    # the `|| true` that would need masks a broken pipeline too.
+    refs="$("${recorded_paths}" "${file}" | sed -n '\#^/nix/store/#p' | sort -u)"
+    if [ -n "${refs}" ]; then
+        leaked=$((leaked + 1))
+        echo "::error file=${file}::references the Nix store at run time"
+        echo "${file}"
+        echo "${refs}" | sed 's/^/    /'
+    fi
+done < <(find "$1" -type f \( -perm -u+x -o -name '*.dylib' -o -name '*.so*' \))
+
+echo "$1: checked ${checked}, skipped ${skipped}, ${leaked} with Nix store references."
+
+if [ "${leaked}" -ne 0 ]; then
+    cat >&2 <<'EOF'
+
+Fixes, in order of preference:
+  - A Conan package built before this check existed: drop it
+    (`conan remove '<name>/*'`) and rebuild.
+  - A binary that should have been retargeted to the system loader: check that
+    cmake/PatchNixBinary.cmake ran for it.
+  - Link the macOS system library instead of the Nix one - see
+    libresolvSystemStub in nix/darwin.nix.
+  - No system library exists (libstdc++): link it statically.
+  - None of the above: pin the toolchain into the package ID, following
+    `user.package:libc_version` in conan/profiles/ci.
+EOF
+    exit 1
+fi
@@ -0,0 +1,12 @@
+#!/bin/bash
+
+case "$(uname -m)" in
+    x86_64) LOADER=/lib64/ld-linux-x86-64.so.2 ;;
+    aarch64) LOADER=/lib/ld-linux-aarch64.so.1 ;;
+    *)
+        echo "Unsupported arch: $(uname -m)" >&2
+        exit 1
+        ;;
+esac
+
+echo "${LOADER}"
@@ -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.2
+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 /
@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""
+Check C++ Doxygen comment style.
+
+Enforces the house convention for documentation comments:
+
+  * Use ``/** ... */`` blocks, not ``///``, ``//!`` or ``/*! ... */``; a plain
+    ``/* ... */`` that contains Doxygen commands is a doc comment missing its
+    second star. Trailing member-after comments use ``///<`` (not ``//!<``,
+    ``/*!< ... */`` or ``/**< ... */`` -- the block forms get reflowed and
+    mis-attached by clang-format on packed enum values, the line form does not).
+  * ``/**`` sits alone on its line; the closing ``*/`` sits alone on its line.
+  * Every content line is prefixed with `` * `` (no bare-indented continuation).
+  * The first content line is flush (not over-indented).
+  * Doxygen commands use the ``@cmd`` form, not ``\\cmd``.
+  * Use ``@return`` / ``@throws`` rather than prose ``Returns:`` / ``Throws:``.
+  * A plain ``//`` comment carrying a block-level ``@command`` (``@param``,
+    ``@return``, ``@see``, ...) is documentation and must be a ``/** ... */``
+    block (Doxygen ignores ``//``).
+  * Use canonical command spellings: ``@return`` (not ``@returns``),
+    ``@throws`` (not ``@throw``), ``@see`` (not ``@sa``).
+  * Order block tags ``@tparam`` -> ``@param`` -> ``@return``. (Whether
+    ``@param`` order matches the signature is not checked here -- too fragile to
+    parse; Doxygen's WARN_IF_DOC_ERROR covers name mismatches.)
+  * One-liners are expanded to three lines, EXCEPT bare markers ``@{`` / ``@}``
+    / ``@cond [label]`` / ``@endcond`` / ``@file [name]`` which stay on one line.
+
+Left intentionally alone (recognized, valid Doxygen that is not this style's
+concern):
+
+  * ``///<`` trailing "member-after" comments (the house form).
+  * Divider lines made only of slashes (``//////////``).
+  * Plain ``/* ... */`` (non-Doxygen) comments.
+
+Usage:
+    check_doxygen_style.py [FILE ...]      # explicit files
+    check_doxygen_style.py                 # default: src/ and include/ trees
+
+Exit status is non-zero if any violation is found.
+"""
+
+import argparse
+import re
+import sys
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class Category(Enum):
+    """A kind of style violation: a printed ``label`` and its ``description``.
+
+    The description is the default message; a few categories whose wording
+    depends on the offending text (see ``Finding.detail``) override it.
+    """
+
+    def __init__(self, label: str, description: str) -> None:
+        self.label = label
+        self.description = description
+
+    BACKSLASH_COMMAND = ("backslash-command", "use the @cmd form, not \\cmd")
+    WRONG_COMMAND = ("wrong-command", "use the canonical command spelling")
+    TRIPLE_SLASH = ("triple-slash", "use a /** ... */ block instead of ///")
+    QT_MEMBER = ("qt-member", "use ///< instead of //!<")
+    QT_LINE = ("qt-line", "use a /** ... */ block instead of //!")
+    BLOCK_MEMBER = ("block-member", "use ///< instead of /**<")
+    QT_BLOCK_MEMBER = ("qt-block-member", "use ///< instead of /*!<")
+    DOC_IN_LINE_COMMENT = (
+        "doc-in-line-comment",
+        "use a /** ... */ block for documentation, not //",
+    )
+    QT_COMMENT = ("qt-comment", "use /** instead of /*!")
+    SINGLE_LINE_BLOCK = (
+        "single-line-block",
+        "expand one-line /** ... */ to a multi-line block "
+        "(markers @{ @} @cond @endcond @file may stay)",
+    )
+    TEXT_ON_OPENER = ("text-on-opener", "move text off the /** opener line")
+    BARE_CONTINUATION = ("bare-continuation", 'prefix continuation lines with " * "')
+    OVER_INDENTED = ("over-indented", "first content line is over-indented")
+    OVER_INDENTED_TAG = (
+        "over-indented-tag",
+        'Doxygen tag over-indented; use a single space after "*"',
+    )
+    COMBINED_MARKER = (
+        "combined-marker",
+        "scope marker @{ / @} should be its own single-line /** @{ */ block",
+    )
+    PROSE_LABEL = ("prose-label", "use a Doxygen tag instead of a prose label")
+    CONTENT_ON_CLOSER = ("content-on-closer", "move content off the closing */ line")
+    PLAIN_BLOCK_DOC = (
+        "plain-block-doc",
+        "documentation comment must open with /** not /*",
+    )
+    TAG_ORDER = (
+        "tag-order",
+        "block tags out of order; expected @tparam, then @param, then @return",
+    )
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single style violation at a 1-based line number.
+
+    ``detail`` overrides the category's default description when the message
+    depends on the offending text (e.g. which command was misspelled).
+    """
+
+    line: int
+    category: Category
+    detail: str | None = None
+
+    @property
+    def message(self) -> str:
+        return self.detail if self.detail is not None else self.category.description
+
+
+DEFAULT_ROOTS = ("src", "include")
+EXTS = {".h", ".hpp", ".cpp", ".ipp", ".cxx", ".cc"}
+
+# Every Doxygen command we recognize when written with a backslash (\cmd).
+_ALL_COMMANDS = (
+    "brief|param|tparam|return|returns|retval|note|warning|pre|post|see|sa|ref|"
+    "throw|throws|exception|deprecated|details|code|endcode|verbatim|endverbatim|"
+    "li|arg|c|internal|since|todo|attention|remark|remarks|ingroup|defgroup"
+)
+# Block-level tags whose over-indentation we flag inside a block body.
+_BLOCK_TAGS = (
+    "param|tparam|returns?|retval|brief|throws?|note|warning|"
+    "pre|post|see|sa|details|deprecated"
+)
+# Tags that, appearing anywhere in a comment, mark it as documentation.
+_ANY_DOC_TAGS = (
+    "param|tparam|returns?|retval|brief|throws?|note|warning|pre|post|see|sa"
+)
+# Tags that make a plain // comment a mis-styled doc comment.
+_LINE_DOC_TAGS = "brief|param|tparam|returns?|retval|throws?|note|see|pre|post"
+
+# \cmd that should be @cmd.
+RE_BACKSLASH_CMD = re.compile(r"\\(" + _ALL_COMMANDS + r")\b")
+# Bare markers that may legitimately stay on a single line.
+RE_MARKER = re.compile(r"^@(\{|\}|cond(\s.*)?|endcond|file(\s.*)?)$")
+# Prose section labels that should be Doxygen tags.
+RE_PROSE_LABEL = re.compile(r"^\*\s(Returns|Throws|Exceptions):\s*$")
+# An over-indented block tag: "*" followed by 2+ spaces then the tag.
+RE_OVERINDENTED_TAG = re.compile(r"^\*\s{2,}@(" + _BLOCK_TAGS + r")\b")
+# Any documentation tag (used to spot a doc comment hiding in a plain /* */).
+RE_ANY_DOC_TAG = re.compile(r"@(" + _ANY_DOC_TAGS + r")\b")
+# A documentation tag inside a // comment.
+RE_LINE_DOC_TAG = re.compile(r"@(" + _LINE_DOC_TAGS + r")\b")
+# Order-relevant tags, for the @tparam -> @param -> @return ordering check.
+RE_ORDER_TAG = re.compile(r"^\*\s*@(param|tparam|returns?|retval)\b")
+# First content line indented by 2+ spaces after the "*".
+RE_FIRST_OVERINDENT = re.compile(r"^\s*\*\s{2,}\S")
+# A scope marker @{ / @} sharing a comment with other text.
+RE_COMBINED_MARKER = re.compile(r"^\*\s*@[{}]\s*$")
+
+# Non-canonical command spellings -> the house spelling (bare command names).
+# Used both to flag a wrong @form and to suggest the right @form for a \wrong.
+CANONICAL_COMMAND = {"returns": "return", "throw": "throws", "sa": "see"}
+WRONG_SPELLINGS = [
+    (re.compile(rf"@{wrong}\b"), f"@{right}")
+    for wrong, right in CANONICAL_COMMAND.items()
+]
+
+# Order block tags should appear in; a body out of this order is a violation.
+EXPECTED_TAG_ORDER = ("tparam", "param", "return")
+
+
+def is_doxy_open(stripped: str) -> bool:
+    """True for a line-start Doxygen block opener we should normalize."""
+    if stripped.startswith("/*!"):  # Qt-style Doxygen
+        return not stripped.startswith("/*!<")  # member-after, leave inline
+    return (
+        stripped.startswith("/**")
+        and not stripped.startswith("/***")
+        and not stripped.startswith("/**/")
+        and not stripped.startswith("/**<")
+    )
+
+
+def _flag_commands(raw_line: str, stripped: str, index: int) -> list[Finding]:
+    """Flag \\cmd and misspelled @cmd on a comment line (opener, body, or closer)."""
+    if not stripped.startswith(("*", "//", "/*")):
+        return []
+    findings: list[Finding] = []
+    backslash = RE_BACKSLASH_CMD.search(raw_line)
+    if backslash:
+        command = backslash.group(1)
+        canonical = CANONICAL_COMMAND.get(command, command)
+        findings.append(
+            Finding(
+                index + 1,
+                Category.BACKSLASH_COMMAND,
+                f"use @{canonical} instead of \\{command}",
+            )
+        )
+    for pattern, replacement in WRONG_SPELLINGS:
+        wrong = pattern.search(raw_line)
+        if wrong:
+            findings.append(
+                Finding(
+                    index + 1,
+                    Category.WRONG_COMMAND,
+                    f"use {replacement} instead of {wrong.group(0)}",
+                )
+            )
+    return findings
+
+
+def _flag_line_comment(raw_line: str, stripped: str, index: int) -> Finding | None:
+    """Return the finding for a single-line comment form (///, //!, /**<, ...), else None."""
+    if stripped.startswith("///") and not stripped.startswith(("////", "///<")):
+        return Finding(index + 1, Category.TRIPLE_SLASH)
+    if "//!<" in raw_line:
+        return Finding(index + 1, Category.QT_MEMBER)
+    if stripped.startswith("//!"):
+        return Finding(index + 1, Category.QT_LINE)
+    if "/**<" in raw_line:
+        return Finding(index + 1, Category.BLOCK_MEMBER)
+    if "/*!<" in raw_line:
+        return Finding(index + 1, Category.QT_BLOCK_MEMBER)
+    if stripped.startswith("//") and RE_LINE_DOC_TAG.search(stripped):
+        return Finding(index + 1, Category.DOC_IN_LINE_COMMENT)
+    return None
+
+
+def _flag_single_line_block(stripped: str, line_no: int, is_qt: bool) -> list[Finding]:
+    """Findings for a whole /** ... */ or /*! ... */ block on one line."""
+    inner = re.sub(r"^/\*[*!]", "", stripped)
+    inner = re.sub(r"\*/\s*$", "", inner).strip()
+    findings: list[Finding] = []
+    if is_qt:
+        findings.append(Finding(line_no, Category.QT_COMMENT))
+    if inner and not RE_MARKER.match(inner):
+        findings.append(Finding(line_no, Category.SINGLE_LINE_BLOCK))
+    return findings
+
+
+def _canonical_order_tag(body: str) -> str | None:
+    """The order-relevant tag (tparam/param/return) a body line opens with, if any."""
+    match = RE_ORDER_TAG.match(body)
+    if match is None:
+        return None
+    command = match.group(1)
+    return "return" if command in ("return", "returns", "retval") else command
+
+
+def _flag_body_line(
+    body_line: str, line_no: int, is_first_content: bool
+) -> list[Finding]:
+    """Findings for one interior line of a multi-line block."""
+    body = body_line.strip()
+    findings: list[Finding] = []
+    if body and not body.startswith("*"):
+        findings.append(Finding(line_no, Category.BARE_CONTINUATION))
+    if body.startswith("*"):
+        if is_first_content and RE_FIRST_OVERINDENT.match(body_line):
+            findings.append(Finding(line_no, Category.OVER_INDENTED))
+        if RE_OVERINDENTED_TAG.match(body):
+            findings.append(Finding(line_no, Category.OVER_INDENTED_TAG))
+        if RE_COMBINED_MARKER.match(body):
+            findings.append(Finding(line_no, Category.COMBINED_MARKER))
+        label = RE_PROSE_LABEL.match(body)
+        if label:
+            suggested_tag = "@return" if label.group(1) == "Returns" else "@throws"
+            findings.append(
+                Finding(
+                    line_no,
+                    Category.PROSE_LABEL,
+                    f'use {suggested_tag} instead of prose "{label.group(1)}:"',
+                )
+            )
+    return findings
+
+
+def _flag_closer(closer_line: str, line_no: int) -> list[Finding]:
+    """Findings for content sharing the closing */ line."""
+    before = closer_line[: closer_line.index("*/")].strip()
+    if before and before != "*":
+        return [Finding(line_no, Category.CONTENT_ON_CLOSER)]
+    return []
+
+
+def _flag_tag_order(first_tag_line: dict[str, int]) -> list[Finding]:
+    """One finding if the present block tags are not in EXPECTED_TAG_ORDER."""
+    tag_lines = [
+        first_tag_line[tag] for tag in EXPECTED_TAG_ORDER if tag in first_tag_line
+    ]
+    if tag_lines != sorted(tag_lines):
+        return [Finding(min(tag_lines), Category.TAG_ORDER)]
+    return []
+
+
+def _flag_doxy_block(lines: list[str], start: int) -> tuple[int, list[Finding]]:
+    """Handle a /** or /*! block opening at ``start``; return (next index, findings)."""
+    raw_line = lines[start]
+    stripped = raw_line.lstrip()
+    open_pos = raw_line.index("/*")
+    is_qt = stripped.startswith("/*!")
+
+    # A whole block on one line: /** ... */.
+    if "*/" in raw_line[open_pos + 2 :]:
+        return start + 1, _flag_single_line_block(stripped, start + 1, is_qt)
+
+    # Multi-line block: opener, then scan the body to the closer.
+    findings: list[Finding] = []
+    if is_qt:
+        findings.append(Finding(start + 1, Category.QT_COMMENT))
+    if raw_line[open_pos + 3 :].strip():
+        findings.append(Finding(start + 1, Category.TEXT_ON_OPENER))
+
+    line_count = len(lines)
+    cursor = start + 1
+    is_first_content = True
+    first_tag_line: dict[str, int] = {}  # canonical tag -> 1-based first line
+    while cursor < line_count and "*/" not in lines[cursor]:
+        body_line = lines[cursor]
+        body = body_line.strip()
+        findings.extend(_flag_commands(body_line, body, cursor))
+        tag = _canonical_order_tag(body)
+        if tag is not None:
+            first_tag_line.setdefault(tag, cursor + 1)
+        findings.extend(_flag_body_line(body_line, cursor + 1, is_first_content))
+        if body.startswith("*"):
+            is_first_content = False
+        cursor += 1
+
+    if cursor < line_count:
+        closer_line = lines[cursor]
+        findings.extend(_flag_commands(closer_line, closer_line.strip(), cursor))
+        findings.extend(_flag_closer(closer_line, cursor + 1))
+    findings.extend(_flag_tag_order(first_tag_line))
+
+    return cursor + 1, findings
+
+
+def _flag_plain_block(lines: list[str], start: int) -> tuple[int, list[Finding]]:
+    """Handle a line-start plain /* ... */ block; return (next index, findings).
+
+    Only flagged when it hides a documentation command (a missing second star).
+    """
+    line_count = len(lines)
+    cursor = start
+    while cursor < line_count and "*/" not in lines[cursor]:
+        cursor += 1
+    findings: list[Finding] = []
+    # The opener (start) is command-checked by check_file; check the rest here.
+    for i in range(start + 1, min(cursor + 1, line_count)):
+        findings.extend(_flag_commands(lines[i], lines[i].strip(), i))
+    block_text = "\n".join(
+        lines[start : cursor + 1] if cursor < line_count else lines[start:]
+    )
+    if RE_ANY_DOC_TAG.search(block_text):
+        findings.append(Finding(start + 1, Category.PLAIN_BLOCK_DOC))
+    next_index = cursor + 1 if cursor < line_count else line_count
+    return next_index, findings
+
+
+def check_source(text: str) -> list[Finding]:
+    """Return all style violations found in the given source text."""
+    lines = text.split("\n")
+    findings: list[Finding] = []
+    line_count = len(lines)
+    index = 0
+    in_plain_block = False  # inside a mid-line, non-Doxygen /* ... */
+    while index < line_count:
+        raw_line = lines[index]
+        stripped = raw_line.lstrip()
+
+        # Skip the interior of a plain block opened on an earlier line.
+        if in_plain_block:
+            in_plain_block = "*/" not in raw_line
+            index += 1
+            continue
+
+        findings.extend(_flag_commands(raw_line, stripped, index))
+
+        line_finding = _flag_line_comment(raw_line, stripped, index)
+        if line_finding is not None:
+            findings.append(line_finding)
+            index += 1
+        elif is_doxy_open(stripped):
+            index, block_findings = _flag_doxy_block(lines, index)
+            findings.extend(block_findings)
+        elif stripped.startswith("/*"):
+            index, block_findings = _flag_plain_block(lines, index)
+            findings.extend(block_findings)
+        else:
+            # A /* that opens mid-line without closing starts a plain block.
+            if "/*" in raw_line and not stripped.startswith("//"):
+                if "*/" not in raw_line[raw_line.index("/*") + 2 :]:
+                    in_plain_block = True
+            index += 1
+    return findings
+
+
+def check_file(path: Path) -> list[Finding]:
+    """Return all style violations found in one file."""
+    return check_source(path.read_text(encoding="utf-8"))
+
+
+def iter_files(paths: Iterable[str]) -> Iterator[Path]:
+    """Yield every C++ source file among the given files and directories."""
+    for raw_path in paths:
+        path = Path(raw_path)
+        if path.is_dir():
+            for candidate in path.rglob("*"):
+                if candidate.is_file() and candidate.suffix in EXTS:
+                    yield candidate
+        elif path.suffix in EXTS:
+            yield path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check Doxygen comment style.")
+    parser.add_argument(
+        "files", nargs="*", help="files or directories (default: src/ include/)"
+    )
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="only print the summary count"
+    )
+    args = parser.parse_args()
+    roots = args.files or [root for root in DEFAULT_ROOTS if Path(root).is_dir()]
+
+    total = 0
+    for path in sorted(set(iter_files(roots)), key=str):
+        for finding in check_file(path):
+            total += 1
+            if not args.quiet:
+                print(
+                    f"{path}:{finding.line}: {finding.category.label}: {finding.message}"
+                )
+    print(f"\n{total} doxygen-style violation(s)", file=sys.stderr)
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Check that Rust unit tests stay out of the coverage report.
+
+cargo-llvm-cov instruments the test code along with everything else, so a test
+module that is not excluded counts its own body as covered and inflates the
+reported number. Excluding it takes two attributes:
+
+  * every `#[cfg(test)]` module carries
+    `#[cfg_attr(coverage_nightly, coverage(off))]`;
+  * every crate root (lib.rs, main.rs) carries
+    `#![cfg_attr(coverage_nightly, feature(coverage_attribute))]`, which the
+    attribute above needs in order to compile.
+
+Both are inert outside the coverage job: cargo-llvm-cov defines
+`coverage_nightly` only when it runs on a nightly toolchain.
+
+The crate-root gate is checked even in a crate that has no tests yet, because
+that is what lets the first test module added later carry the attribute without
+a build failure. Missing it is a hard error, so it cannot go unnoticed; a
+missing `coverage(off)` fails open, which is why this check exists.
+
+Matching is on exact attribute text, which works because `cargo fmt` runs over
+the whole workspace in the hook ahead of this one: rustfmt puts every attribute
+on its own line and normalizes what is inside it, turning `#[cfg( test )]`
+and `#[cfg(test,)]` alike into `#[cfg(test)]`. So there is nothing here that
+parses Rust. The price is that a cfg this file does not spell out literally --
+`all(test, ...)`, `any(test, ...)`, `not(test)` -- is reported rather than
+classified, on the grounds that guessing at coverage semantics is how a check
+like this ends up quietly wrong.
+
+Usage: ./bin/pre-commit/check_rust_coverage_attrs.py <file1> <file2> ...
+
+Exit status is non-zero if any violation is found.
+"""
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+CRATE_ROOTS = {"lib.rs", "main.rs"}
+
+FEATURE_ATTR = "#![cfg_attr(coverage_nightly, feature(coverage_attribute))]"
+COVERAGE_OFF_ATTR = "#[cfg_attr(coverage_nightly, coverage(off))]"
+CFG_TEST_ATTR = "#[cfg(test)]"
+
+# Any other cfg that mentions `test`. String literals are blanked before this
+# runs, so `feature = "test"` does not read as the `test` cfg.
+RE_CFG_MENTIONS_TEST = re.compile(r"^#\[cfg\(.*\btest\b.*\)\]$")
+RE_STRING = re.compile(r'"(?:[^"\\]|\\.)*"')
+RE_MOD = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?mod\s+([A-Za-z_]\w*)")
+
+
+@dataclass(frozen=True)
+class Finding:
+    line: int
+    label: str
+    message: str
+
+
+def _check_module(attrs: list[str], line: int, name: str) -> list[Finding]:
+    """Findings for one module, given the attributes attached to it."""
+    if COVERAGE_OFF_ATTR in attrs:
+        return []  # excluded from coverage; which cfg gates it does not matter
+    if CFG_TEST_ATTR in attrs:
+        return [
+            Finding(
+                line,
+                "missing-coverage-off",
+                f"`mod {name}` is #[cfg(test)] but not excluded from coverage; "
+                f"add {COVERAGE_OFF_ATTR}",
+            )
+        ]
+    unclassified = [
+        attr for attr in attrs if RE_CFG_MENTIONS_TEST.match(RE_STRING.sub('""', attr))
+    ]
+    if unclassified:
+        return [
+            Finding(
+                line,
+                "unclassified-cfg",
+                f"`mod {name}` is gated on {unclassified[0]}, which this check "
+                f"cannot tell apart from a module that ships in the library; "
+                f"add {COVERAGE_OFF_ATTR} if it is test-only, or teach this "
+                f"check the cfg if it is not",
+            )
+        ]
+    return []
+
+
+def _check_test_modules(lines: list[str]) -> list[Finding]:
+    """Findings for every test module that is not excluded from coverage."""
+    findings: list[Finding] = []
+    attrs: list[str] = []
+    attrs_line = 0
+    for number, raw in enumerate(lines, start=1):
+        stripped = raw.strip()
+        # Blank lines and comments are allowed between an attribute and its item.
+        if not stripped or stripped.startswith("//"):
+            continue
+        if stripped.startswith("#["):
+            if not attrs:
+                attrs_line = number
+            attrs.append(stripped)
+            continue
+        module = RE_MOD.match(stripped)
+        if module is not None and attrs:
+            findings += _check_module(attrs, attrs_line, module.group(1))
+        attrs = []
+    return findings
+
+
+def _check_crate_root(name: str, lines: list[str]) -> list[Finding]:
+    """A finding if a crate root is missing the coverage_attribute feature gate."""
+    if name not in CRATE_ROOTS:
+        return []
+    if any(line.strip() == FEATURE_ATTR for line in lines):
+        return []
+    return [
+        Finding(
+            1,
+            "missing-feature-gate",
+            f"crate root is missing {FEATURE_ATTR}",
+        )
+    ]
+
+
+def check_source(name: str, text: str) -> list[Finding]:
+    """Findings for one file's contents; `name` is its base name (lib.rs, ...)."""
+    lines = text.splitlines()
+    return _check_crate_root(name, lines) + _check_test_modules(lines)
+
+
+def check_file(path: Path) -> list[Finding]:
+    return check_source(path.name, path.read_text(encoding="utf-8"))
+
+
+def main() -> int:
+    total = 0
+    for path in (Path(name) for name in sys.argv[1:]):
+        for finding in check_file(path):
+            total += 1
+            print(f"{path}:{finding.line}: {finding.label}: {finding.message}")
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -1,24 +1,57 @@
 #!/usr/bin/env python3
-"""Pre-commit hook that runs clang-tidy on changed files using run-clang-tidy."""
+"""Pre-commit hook that runs clang-tidy on staged files using run-clang-tidy.
+
+The script determines the staged files itself (see `pass_filenames: false` in
+.pre-commit-config.yaml) so run-clang-tidy is run once and handles parallelism
+internally: pre-commit would otherwise split the files across parallel hook
+invocations that race when fixes edit a shared header.
+
+Fixes are collected with `-export-fixes` and applied by clang-apply-replacements
+in a separate step rather than with run-clang-tidy's `-fix`. The `add_module`
+build isolates each module's headers behind a per-module symlink directory
+(build/modules/<module>/...), so a header reachable from several translation
+units is referenced through different paths that all resolve to the same source
+file. clang-apply-replacements deduplicates identical replacements by their
+literal path, so those paths must be canonicalised to the real source path
+first; otherwise the same fix is applied once per path and corrupts the header.
+"""

 from __future__ import annotations

-import json
 import os
 import re
 import shutil
 import subprocess
 import sys
-from collections import defaultdict
+import tempfile
 from pathlib import Path

-HEADER_EXTENSIONS = {".h", ".hpp", ".ipp"}
-SOURCE_EXTENSIONS = {".cpp"}
-INCLUDE_RE = re.compile(r"^\s*#\s*include\s*[<\"]([^>\"]+)[>\"]")
+# Extensions run-clang-tidy can analyse: `.cpp` translation units and, thanks to
+# the `verify_headers` build option, `.h`/`.hpp` headers (each has its own
+# compile_commands.json entry). `.ipp` fragments have no entry and are skipped.
+TIDY_EXTENSIONS = {".cpp", ".h", ".hpp"}
+
+# A single-quoted `FilePath:` entry in an -export-fixes YAML file, allowing the
+# `- ` marker that precedes it inside a `Replacements:` sequence. clang-tidy
+# emits paths single-quoted and doubles any embedded quote per YAML rules.
+FILEPATH_RE = re.compile(r"^(\s*(?:-\s+)?FilePath:\s*)'((?:[^']|'')*)'\s*$")


-def find_run_clang_tidy() -> str | None:
-    for candidate in ("run-clang-tidy-21", "run-clang-tidy"):
+def clang_tidy_major() -> str | None:
+    """Major version of the `clang-tidy` on PATH, which run-clang-tidy invokes."""
+    if not (clang_tidy := shutil.which("clang-tidy")):
+        return None
+    output = subprocess.run(
+        [clang_tidy, "--version"], capture_output=True, text=True
+    ).stdout
+    m = re.search(r"LLVM version (\d+)", output)
+    return m.group(1) if m else None
+
+
+def find_tool(name: str, version: str | None) -> str | None:
+    """Prefer `<name>-<version>`, so a host tool of another version can't win."""
+    candidates = ([f"{name}-{version}"] if version else []) + [name]
+    for candidate in candidates:
        if path := shutil.which(candidate):
            return path
    return None
@@ -32,152 +65,71 @@ def find_build_dir(repo_root: Path) -> Path | None:
    return None


-def build_include_graph(build_dir: Path, repo_root: Path) -> tuple[dict, set]:
+def staged_files(repo_root: Path) -> list[Path]:
+    """Return absolute paths of staged, lint-able C/C++ files.
+
+    `--diff-filter=d` excludes deletions so we never lint a removed file.
    """
-    Scan all files reachable from compile_commands.json and build an inverted include graph.
-
-    Returns:
-        inverted: header_path -> set of files that include it
-        source_files: set of all TU paths from compile_commands.json
-    """
-    with open(build_dir / "compile_commands.json") as f:
-        db = json.load(f)
-
-    source_files = {Path(e["file"]).resolve() for e in db}
-    include_roots = [repo_root / "include", repo_root / "src"]
-    inverted: dict[Path, set[Path]] = defaultdict(set)
-
-    to_scan: set[Path] = set(source_files)
-    scanned: set[Path] = set()
-
-    while to_scan:
-        file = to_scan.pop()
-        if file in scanned or not file.exists():
-            continue
-        scanned.add(file)
-
-        content = file.read_text()
-
-        for line in content.splitlines():
-            m = INCLUDE_RE.match(line)
-            if not m:
-                continue
-            for root in include_roots:
-                candidate = (root / m.group(1)).resolve()
-                if candidate.exists():
-                    inverted[candidate].add(file)
-                    if candidate not in scanned:
-                        to_scan.add(candidate)
-                    break
-
-    return inverted, source_files
-
-
-def find_tus_for_headers(
-    headers: list[Path],
-    inverted: dict[Path, set[Path]],
-    source_files: set[Path],
-) -> set[Path]:
-    """
-    For each header, pick one TU that transitively includes it.
-    Prefers a TU whose stem matches the header's stem, otherwise picks the first found.
-    """
-    result: set[Path] = set()
-
-    for header in headers:
-        preferred: Path | None = None
-        visited: set[Path] = {header}
-        stack: list[Path] = [header]
-
-        while stack:
-            h = stack.pop()
-            for inc in inverted.get(h, ()):
-                if inc in source_files:
-                    if inc.stem == header.stem:
-                        preferred = inc
-                        break
-                    if preferred is None:
-                        preferred = inc
-                if inc not in visited:
-                    visited.add(inc)
-                    stack.append(inc)
-            if preferred is not None and preferred.stem == header.stem:
-                break
-
-        if preferred is not None:
-            result.add(preferred)
-
-    return result
-
-
-def resolve_files(
-    input_files: list[str], build_dir: Path, repo_root: Path
-) -> list[str]:
-    """
-    Split input into source files and headers. Source files are passed through;
-    headers are resolved to the TUs that transitively include them.
-    """
-    sources: list[Path] = []
-    headers: list[Path] = []
-
-    for f in input_files:
-        p = Path(f).resolve()
-        if p.suffix in SOURCE_EXTENSIONS:
-            sources.append(p)
-        elif p.suffix in HEADER_EXTENSIONS:
-            headers.append(p)
-
-    if not headers:
-        return [str(p) for p in sources]
-
-    print(
-        f"Resolving {len(headers)} header(s) to compilation units...", file=sys.stderr
-    )
-    inverted, source_files = build_include_graph(build_dir, repo_root)
-    tus = find_tus_for_headers(headers, inverted, source_files)
-
-    if not tus:
-        print(
-            "Warning: no compilation units found that include the modified headers; "
-            "skipping clang-tidy for headers.",
-            file=sys.stderr,
-        )
-
-    return sorted({str(p) for p in (*sources, *tus)})
-
-
-def staged_files(repo_root: Path) -> list[str]:
-    result = subprocess.run(
-        ["git", "diff", "--staged", "--name-only", "--diff-filter=d"],
-        capture_output=True,
+    output = subprocess.check_output(
+        ["git", "diff", "--staged", "--name-only", "--diff-filter=d", "--"]
+        + [f"*{ext}" for ext in TIDY_EXTENSIONS],
        text=True,
        cwd=repo_root,
    )
-    if result.returncode != 0:
-        print(
-            "clang-tidy check failed: 'git diff --staged' command failed.",
-            file=sys.stderr,
-        )
-        if result.stderr:
-            print(result.stderr, file=sys.stderr)
-        sys.exit(result.returncode or 1)
-    return [str(repo_root / p) for p in result.stdout.splitlines() if p]
+    return [repo_root / rel for rel in output.splitlines() if rel]
+
+
+def canonicalize_fix_paths(fixes_dir: Path) -> None:
+    """Rewrite every `FilePath` in the exported fixes to its real source path.
+
+    A header included through a module's isolation symlink is recorded under that
+    symlink's path; collapsing all paths to the same real file lets
+    clang-apply-replacements recognise the per-translation-unit duplicates and
+    apply each fix once.
+    """
+    for yaml in fixes_dir.glob("*.yaml"):
+        lines = []
+        for line in yaml.read_text().splitlines():
+            if m := FILEPATH_RE.match(line):
+                path = m.group(2).replace("''", "'")
+                real = os.path.realpath(path).replace("'", "''")
+                line = f"{m.group(1)}'{real}'"
+            lines.append(line)
+        yaml.write_text("\n".join(lines) + "\n")


 def main():
    if not os.environ.get("TIDY"):
        return 0

-    repo_root = Path(__file__).parent.parent
+    repo_root = Path(
+        subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=Path(__file__).parent,
+            text=True,
+        ).strip()
+    )
+
    files = staged_files(repo_root)
    if not files:
        return 0

-    run_clang_tidy = find_run_clang_tidy()
-    if not run_clang_tidy:
+    version = clang_tidy_major()
+    run_clang_tidy = find_tool("run-clang-tidy", version)
+    clang_apply_replacements = find_tool("clang-apply-replacements", version)
+    missing = [
+        name
+        for name, path in (
+            ("run-clang-tidy", run_clang_tidy),
+            ("clang-apply-replacements", clang_apply_replacements),
+        )
+        if not path
+    ]
+    if missing:
+        tried = f" (tried the '-{version}' suffix too)" if version else ""
        print(
-            "clang-tidy check failed: TIDY is enabled but neither "
-            "'run-clang-tidy-21' nor 'run-clang-tidy' was found in PATH.",
+            f"clang-tidy check failed: TIDY is enabled but {' and '.join(missing)} "
+            f"was not found in PATH{tried}.",
            file=sys.stderr,
        )
        return 1
@@ -191,15 +143,27 @@ def main():
        )
        return 1

-    tidy_files = resolve_files(files, build_dir, repo_root)
-    if not tidy_files:
-        return 0
+    with tempfile.TemporaryDirectory() as fixes_dir:
+        result = subprocess.run(
+            [
+                run_clang_tidy,
+                "-quiet",
+                "-p",
+                build_dir,
+                "-export-fixes",
+                fixes_dir,
+                "-allow-no-checks",
+            ]
+            + files
+        )
+        canonicalize_fix_paths(Path(fixes_dir))
+        # `FormatStyle` in .clang-tidy does not reach this path,
+        # so ask for the repository style here.
+        applied = subprocess.run(
+            [clang_apply_replacements, "--format", "--style=file", fixes_dir]
+        )

-    result = subprocess.run(
-        [run_clang_tidy, "-quiet", "-p", str(build_dir), "-fix", "-allow-no-checks"]
-        + tidy_files
-    )
-    return result.returncode
+    return result.returncode or applied.returncode


 if __name__ == "__main__":
@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+
+"""
+Rewrites gtest names to the required style in this project: the suite name is
+CamelCase, the test-case name is snake_case.
+
+    TEST(SuiteName, test_case_name)
+
+The gtest `DISABLED_` prefix is kept verbatim on either name.
+
+Both conversions fold acronyms the way a reader expects:
+`SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`, not
+`set_and_reset_account_txn_i_d`.
+
+The first argument of `TEST_F`, `TEST_P`, `TYPED_TEST` and `TYPED_TEST_P` is a
+fixture class rather than a free identifier, so rewriting it here would leave
+the class it names behind. Those are reported for a human to rename (clang-tidy
+checks the class declaration itself, via readability-identifier-naming).
+
+Usage: ./bin/pre-commit/fix_gtest_names.py <file1> <file2> ...
+"""
+
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+# A test-case definition, `MACRO(SuiteOrFixture, TestName)`, anchored at the
+# start of a line so that commented-out definitions and project macros that
+# merely look similar (`TEST_EXPECT(...)`) are left alone. The `\s*` between
+# arguments allows for a definition clang-format wrapped over several lines.
+PATTERN = re.compile(
+    r"(?P<head>^[ \t]*(?P<macro>TYPED_TEST_P|TYPED_TEST|TEST_F|TEST_P|TEST)\s*\(\s*)"
+    r"(?P<suite>\w+)(?P<mid>\s*,\s*)(?P<name>\w+)(?P<tail>\s*\))",
+    re.MULTILINE,
+)
+
+# The macros whose first argument names a fixture class, not a free identifier.
+FIXTURE_MACROS = ("TEST_F", "TEST_P", "TYPED_TEST", "TYPED_TEST_P")
+
+DISABLED = "DISABLED_"
+
+ACRONYM_BOUNDARY = re.compile(r"([A-Z]+)([A-Z][a-z])")
+WORD_BOUNDARY = re.compile(r"([a-z\d])([A-Z])")
+
+
+def _split_disabled(name: str) -> tuple[str, str]:
+    """Splits off gtest's `DISABLED_` prefix, which is kept verbatim."""
+    if name.startswith(DISABLED):
+        return DISABLED, name[len(DISABLED) :]
+    return "", name
+
+
+def snake_case(name: str) -> str:
+    """Returns the name in snake_case, leaving acronyms whole.
+
+    `SetAndResetAccountTxnID` -> `set_and_reset_account_txn_id`,
+    `parseStatRSSkB` -> `parse_stat_rs_sk_b`.
+    """
+    prefix, core = _split_disabled(name)
+    core = ACRONYM_BOUNDARY.sub(r"\1_\2", core)
+    return prefix + WORD_BOUNDARY.sub(r"\1_\2", core).lower()
+
+
+def camel_case(name: str) -> str:
+    """Returns the name in CamelCase, capitalizing each underscored word.
+
+    Only the letters that have to change are touched, so acronyms survive: a
+    conversion that went via snake_case would turn `SHAMapTest` into
+    `ShaMapTest`, whereas here it is already CamelCase and stays put.
+    `json_value` -> `JsonValue`, `parseStatRSSkB` -> `ParseStatRSSkB`.
+    """
+    prefix, core = _split_disabled(name)
+    return prefix + "".join(w[:1].upper() + w[1:] for w in core.split("_") if w)
+
+
+def _corrected(match: re.Match) -> tuple[str, str]:
+    """Returns the suite and test-case names this definition should end up with."""
+    suite = match["suite"]
+    return (
+        suite if match["macro"] in FIXTURE_MACROS else camel_case(suite),
+        snake_case(match["name"]),
+    )
+
+
+def fix_source(text: str) -> tuple[str, list[str]]:
+    """Returns the corrected text and one `line: message` report per bad name."""
+    # gtest joins the suite and test names into one class name, so two test
+    # cases whose joined names agree cannot coexist: `TEST(a, b_c)` and
+    # `TEST(a_b, c)` both define `a_b_c_Test`. A rename that would introduce
+    # such a clash is reported for a human instead of applied.
+    joined = Counter("_".join(_corrected(m)) for m in PATTERN.finditer(text))
+    reports = []
+
+    def rewrite(match: re.Match) -> str:
+        suite, name = match["suite"], match["name"]
+        new_suite, new_name = _corrected(match)
+        line = text.count("\n", 0, match.start()) + 1
+
+        if match["macro"] in FIXTURE_MACROS and camel_case(suite) != suite:
+            reports.append(
+                f"{line}: fixture '{suite}' is not CamelCase: rename the class "
+                f"to '{camel_case(suite)}' by hand"
+            )
+        if (new_suite, new_name) == (suite, name):
+            return match[0]
+        if joined[f"{new_suite}_{new_name}"] > 1:
+            reports.append(
+                f"{line}: cannot rename '{suite}, {name}' to '{new_suite}, "
+                f"{new_name}': another test case already generates that name"
+            )
+            return match[0]
+        if new_suite != suite:
+            reports.append(f"{line}: renamed suite '{suite}' to '{new_suite}'")
+        if new_name != name:
+            reports.append(f"{line}: renamed test case '{name}' to '{new_name}'")
+        return match["head"] + new_suite + match["mid"] + new_name + match["tail"]
+
+    return PATTERN.sub(rewrite, text), reports
+
+
+def fix_names(path: Path) -> bool:
+    """Corrects one file's gtest names, reporting each on stdout."""
+    original = path.read_text(encoding="utf-8")
+    fixed, reports = fix_source(original)
+    for report in reports:
+        print(f"{path}:{report}")
+    if fixed != original:
+        path.write_text(fixed, encoding="utf-8")
+    return not reports
+
+
+def main() -> int:
+    files = [Path(f) for f in sys.argv[1:]]
+    success = True
+
+    for path in files:
+        success &= fix_names(path)
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+
+"""
+Adds "#pragma once" to the top of header files that don't already have it.
+
+Usage: ./bin/pre-commit/fix_pragma_once.py <file1> <file2> ...
+"""
+
+import sys
+from pathlib import Path
+
+PRAGMA_ONCE = "#pragma once\n\n"
+
+
+def fix_pragma_once(path: Path) -> bool:
+    original = path.read_text(encoding="utf-8")
+    if PRAGMA_ONCE not in original:
+        path.write_text(PRAGMA_ONCE + original, encoding="utf-8")
+        return False
+    return True
+
+
+def main() -> int:
+    files = [Path(f) for f in sys.argv[1:]]
+    success = True
+
+    for path in files:
+        success &= fix_pragma_once(path)
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""
+Tests for check_doxygen_style.py.
+
+Run directly (no test framework needed):
+    ./bin/pre-commit/test_check_doxygen_style.py
+or under pytest:
+    pytest bin/pre-commit/test_check_doxygen_style.py
+"""
+
+import sys
+import textwrap
+
+from check_doxygen_style import Finding, check_source
+
+
+def findings_for(text: str) -> list[Finding]:
+    """Return the style violations for the given source text.
+
+    The text is dedented and its leading newline stripped, so fixtures can be
+    written as indented triple-quoted here-docs while keeping honest 1-based
+    line numbers.
+    """
+    text = textwrap.dedent(text).lstrip("\n")
+    return check_source(text)
+
+
+def labels_for(text: str) -> list[str]:
+    return [f.category.label for f in findings_for(text)]
+
+
+def messages_for(text: str) -> list[str]:
+    return [f.message for f in findings_for(text)]
+
+
+# --- well-formed input produces nothing -------------------------------------
+
+
+def test_clean_block_ok() -> None:
+    code = """
+    /**
+     * Brief.
+     *
+     * @tparam T a type
+     * @param x the x
+     * @return the result
+     */
+    """
+    assert findings_for(code) == []
+
+
+def test_blank_lines_inside_block_ok() -> None:
+    code = """
+    /**
+     * a
+     *
+     * b
+     */
+    """
+    assert findings_for(code) == []
+
+
+def test_member_and_divider_allowed() -> None:
+    assert findings_for("int x;  ///< ok member\n") == []
+    assert findings_for("//////////\n") == []
+    assert findings_for("//// text\n") == []
+
+
+# --- line-comment forms ------------------------------------------------------
+
+
+def test_triple_slash() -> None:
+    code = "/// doc\n"
+    assert labels_for(code) == ["triple-slash"]
+
+
+def test_qt_line() -> None:
+    code = "//! doc\n"
+    assert labels_for(code) == ["qt-line"]
+
+
+def test_qt_member() -> None:
+    code = "int x;  //!< doc\n"
+    assert labels_for(code) == ["qt-member"]
+
+
+def test_block_member() -> None:
+    code = "int x;  /**< doc */\n"
+    assert labels_for(code) == ["block-member"]
+
+
+def test_qt_block_member() -> None:
+    code = "int x;  /*!< doc */\n"
+    assert labels_for(code) == ["qt-block-member"]
+
+
+def test_doc_in_line_comment() -> None:
+    code = "// @param x\n"
+    assert labels_for(code) == ["doc-in-line-comment"]
+
+
+# --- block forms -------------------------------------------------------------
+
+
+def test_qt_comment() -> None:
+    code = """
+    /*!
+     * brief
+     */
+    """
+    assert labels_for(code) == ["qt-comment"]
+
+
+def test_qt_comment_single_line() -> None:
+    # /*! ... */ on one line -> qt-comment (plus single-line-block)
+    code = "/*! brief */\n"
+    assert labels_for(code) == ["qt-comment", "single-line-block"]
+
+
+def test_single_line_block() -> None:
+    code = "/** brief */\n"
+    assert labels_for(code) == ["single-line-block"]
+
+
+def test_single_line_markers_allowed() -> None:
+    for marker in ("@{", "@}", "@cond LABEL", "@endcond", "@file foo.h"):
+        code = f"/** {marker} */\n"
+        assert findings_for(code) == [], marker
+
+
+def test_text_on_opener() -> None:
+    code = """
+    /** text here
+     * more
+     */
+    """
+    assert labels_for(code) == ["text-on-opener"]
+
+
+def test_bare_continuation() -> None:
+    code = """
+    /**
+     * a
+       bare line
+     */
+    """
+    assert labels_for(code) == ["bare-continuation"]
+
+
+def test_over_indented_first_line() -> None:
+    code = """
+    /**
+     *   over
+     */
+    """
+    assert labels_for(code) == ["over-indented"]
+
+
+def test_over_indented_tag() -> None:
+    # a flush first line consumes "first content", isolating the tag check
+    code = """
+    /**
+     * brief
+     *   @param x
+     */
+    """
+    assert labels_for(code) == ["over-indented-tag"]
+
+
+def test_combined_marker() -> None:
+    code = """
+    /**
+     * @{
+     */
+    """
+    assert labels_for(code) == ["combined-marker"]
+
+
+def test_prose_label() -> None:
+    for word in ("Returns", "Throws", "Exceptions"):
+        code = f"""
+        /**
+         * {word}:
+         */
+        """
+        assert labels_for(code) == ["prose-label"], word
+
+
+def test_content_on_closer() -> None:
+    code = """
+    /**
+     * a
+     * b */
+    """
+    assert labels_for(code) == ["content-on-closer"]
+
+
+def test_plain_block_doc() -> None:
+    assert labels_for("/* @param x */\n") == ["plain-block-doc"]
+    assert findings_for("/* just an ordinary note */\n") == []
+
+
+def test_tag_order() -> None:
+    out_of_order = """
+    /**
+     * @param x
+     * @tparam T
+     */
+    """
+    assert labels_for(out_of_order) == ["tag-order"]
+
+    correct = """
+    /**
+     * @tparam T
+     * @param x
+     * @return r
+     */
+    """
+    assert findings_for(correct) == []
+
+    single = """
+    /**
+     * @param x
+     */
+    """
+    assert findings_for(single) == []  # single tag: never out of order
+
+
+# --- command spelling (must work on body/closer lines, not just the opener) --
+
+
+def test_backslash_command_on_body_line() -> None:
+    code = r"""
+    /**
+     * \brief x
+     */
+    """
+    assert labels_for(code) == ["backslash-command"]
+
+
+def test_backslash_command_suggests_canonical_spelling() -> None:
+    # a backslash + non-canonical spelling is fixed in one pass, not two:
+    # \sa -> @see (not @sa), \returns -> @return (not @returns)
+    sa = r"""
+    /**
+     * \sa other
+     */
+    """
+    assert messages_for(sa) == [r"use @see instead of \sa"]
+
+    returns = r"""
+    /**
+     * \returns x
+     */
+    """
+    assert messages_for(returns) == [r"use @return instead of \returns"]
+
+
+def test_wrong_command_on_body_line() -> None:
+    code = """
+    /**
+     * @returns x
+     */
+    """
+    assert labels_for(code) == ["wrong-command"]
+
+
+def test_body_line_commands_regression() -> None:
+    # regression: these live on body lines of a multi-line block
+    code = r"""
+    /**
+     * @returns bad
+     * @throw ex
+     * @sa other
+     * \param y
+     */
+    """
+    assert labels_for(code) == [
+        "wrong-command",
+        "wrong-command",
+        "wrong-command",
+        "backslash-command",
+    ]
+
+
+def test_command_on_closer_line() -> None:
+    code = """
+    /**
+     * a
+     * @sa b */
+    """
+    assert labels_for(code) == ["wrong-command", "content-on-closer"]
+
+
+def test_no_double_count_across_opener_body_closer() -> None:
+    code = """
+    /** @returns opener
+     * @throw body
+     * @sa closer */
+    """
+    assert labels_for(code).count("wrong-command") == 3
+
+
+def test_code_with_word_allowed() -> None:
+    # @code{.cpp} is valid Doxygen and must not be flagged
+    code = """
+    /**
+     * @code{.cpp}
+     * int x;
+     * @endcode
+     */
+    """
+    assert findings_for(code) == []
+
+
+# --- rendered message text ---------------------------------------------------
+
+
+def test_message_uses_category_description() -> None:
+    # a static category renders its default description
+    code = "/// doc\n"
+    assert messages_for(code) == ["use a /** ... */ block instead of ///"]
+
+
+def test_message_detail_overrides() -> None:
+    # dynamic categories render the offending text via Finding.detail
+    backslash = r"""
+    /**
+     * \param y
+     */
+    """
+    assert messages_for(backslash) == [r"use @param instead of \param"]
+
+    wrong = """
+    /**
+     * @returns x
+     */
+    """
+    assert messages_for(wrong) == ["use @return instead of @returns"]
+
+    prose = """
+    /**
+     * Throws:
+     */
+    """
+    assert messages_for(prose) == ['use @throws instead of prose "Throws:"']
+
+
+# --- robustness --------------------------------------------------------------
+
+
+def test_empty_file_no_crash() -> None:
+    assert findings_for("") == []
+
+
+def test_mid_line_plain_block_skipped() -> None:
+    # a /* opened mid-line (after code) and spanning lines is skipped, so its
+    # comment-like contents are not analyzed
+    code = """
+    int x = 0;  /* note: @returns is not a real tag here
+     * @param also not real
+     */
+    int y = 0;
+    """
+    assert findings_for(code) == []
+
+
+def test_unclosed_block_scanned_to_eof() -> None:
+    # an unterminated /** block is still scanned to EOF (no crash, body checked)
+    code = """
+    /**
+     * @returns x
+    """
+    assert labels_for(code) == ["wrong-command"]
+
+
+def test_banner_and_empty_comment_not_flagged() -> None:
+    code = """
+    /***
+     * banner
+     ***/
+    """
+    assert findings_for(code) == []
+    assert findings_for("/**/\n") == []
+
+
+def main() -> int:
+    tests = sorted(
+        (name, fn)
+        for name, fn in globals().items()
+        if name.startswith("test_") and callable(fn)
+    )
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"PASS {name}")
+        except AssertionError as exc:
+            failed += 1
+            print(f"FAIL {name}: {exc!r}")
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+Tests for fix_gtest_names.py.
+
+Run directly (no test framework needed):
+    ./bin/pre-commit/test_fix_gtest_names.py
+or under pytest:
+    pytest bin/pre-commit/test_fix_gtest_names.py
+"""
+
+import sys
+import textwrap
+
+from fix_gtest_names import camel_case, fix_source, snake_case
+
+
+def dedent(text: str) -> str:
+    """Removes a fixture's common indentation and its leading newline.
+
+    Lets fixtures be written as indented triple-quoted here-docs while keeping
+    honest 1-based line numbers.
+    """
+    return textwrap.dedent(text).lstrip("\n")
+
+
+def fixed(text: str) -> str:
+    return fix_source(dedent(text))[0]
+
+
+def reports(text: str) -> list[str]:
+    return fix_source(dedent(text))[1]
+
+
+# --- conversion --------------------------------------------------------------
+
+
+def test_snake_case_conversion() -> None:
+    assert snake_case("BadInputs") == "bad_inputs"
+    assert snake_case("mulDiv") == "mul_div"
+    assert snake_case("already_snake") == "already_snake"
+    assert snake_case("base64") == "base64"
+
+
+def test_snake_case_keeps_acronyms_whole() -> None:
+    assert snake_case("SetAndResetAccountTxnID") == "set_and_reset_account_txn_id"
+    assert snake_case("XRPToIOU") == "xrp_to_iou"
+    assert snake_case("STAmountMath") == "st_amount_math"
+
+
+def test_camel_case_conversion() -> None:
+    assert camel_case("json_value") == "JsonValue"
+    assert camel_case("mulDiv") == "MulDiv"
+    assert camel_case("scope") == "Scope"
+    assert camel_case("base64") == "Base64"
+
+
+def test_camel_case_leaves_acronyms_alone() -> None:
+    # A snake_case round-trip would give `ShaMapTest` / `ParseStatmRsSkB` here.
+    assert camel_case("SHAMapTest") == "SHAMapTest"
+    assert camel_case("parseStatmRSSkB") == "ParseStatmRSSkB"
+    assert camel_case("XRPAmount") == "XRPAmount"
+    assert camel_case("CSPRNG") == "CSPRNG"
+
+
+def test_disabled_prefix_preserved() -> None:
+    assert snake_case("DISABLED_FooBar") == "DISABLED_foo_bar"
+    assert snake_case("DISABLED_foo_bar") == "DISABLED_foo_bar"
+    assert snake_case("DISABLED_") == "DISABLED_"
+    assert camel_case("DISABLED_foo_bar") == "DISABLED_FooBar"
+    assert camel_case("DISABLED_") == "DISABLED_"
+
+
+# --- what counts as a test definition ---------------------------------------
+
+
+def test_all_macros_recognized() -> None:
+    code = """
+    TEST(Suite, oneName)
+    TEST_F(Fixture, twoName)
+    TEST_P(Fixture, threeName)
+    TYPED_TEST(Fixture, fourName)
+    TYPED_TEST_P(Fixture, fiveName)
+    """
+    assert fixed(code) == dedent("""
+        TEST(Suite, one_name)
+        TEST_F(Fixture, two_name)
+        TEST_P(Fixture, three_name)
+        TYPED_TEST(Fixture, four_name)
+        TYPED_TEST_P(Fixture, five_name)
+        """)
+
+
+def test_conforming_definitions_untouched() -> None:
+    code = """
+    TEST(AccountSet, bad_inputs)
+    TEST_F(MutexMakeTest, default_constructor)
+    TEST(SHAMap, DISABLED_slow_path)
+    """
+    assert reports(code) == []
+    assert fixed(code) == dedent(code)
+
+
+def test_lookalikes_ignored() -> None:
+    code = """
+    // TEST(Suite, notATest)
+    TEST_EXPECT(someCall())
+    TEST_EXPECTS(amount == value, amount.getText())
+    INSTANTIATE_TEST_SUITE_P(Prefix, Fixture, testValues());
+    auto x = TEST(Suite, notATest);
+    TYPED_TEST_SUITE(Fixture, MyTypes);
+    """
+    assert reports(code) == []
+    assert fixed(code) == dedent(code)
+
+
+def test_indented_and_wrapped_definitions() -> None:
+    code = """
+    namespace ripple {
+        TEST(Suite, indentedName)
+    }
+    TEST_F(
+        SomeVeryLongFixtureName,
+        wrappedName)
+    """
+    assert fixed(code) == dedent("""
+        namespace ripple {
+            TEST(Suite, indented_name)
+        }
+        TEST_F(
+            SomeVeryLongFixtureName,
+            wrapped_name)
+        """)
+
+
+# --- rewriting --------------------------------------------------------------
+
+
+def test_only_the_two_names_are_rewritten() -> None:
+    code = """
+    TEST(mulDiv, mulDiv)
+    {
+        auto const mulDiv = 1;  // mulDiv stays
+    }
+    """
+    assert fixed(code) == dedent("""
+        TEST(MulDiv, mul_div)
+        {
+            auto const mulDiv = 1;  // mulDiv stays
+        }
+        """)
+
+
+def test_suite_name_camel_cased() -> None:
+    code = """
+    TEST(json_value, limits)
+    TEST(scope, ScopeExit)
+    """
+    assert reports(code) == [
+        "1: renamed suite 'json_value' to 'JsonValue'",
+        "2: renamed suite 'scope' to 'Scope'",
+        "2: renamed test case 'ScopeExit' to 'scope_exit'",
+    ]
+    assert fixed(code) == dedent("""
+        TEST(JsonValue, limits)
+        TEST(Scope, scope_exit)
+        """)
+
+
+def test_fixture_reported_but_not_renamed() -> None:
+    # The first argument names a class, so only a human (or clang-tidy) can
+    # rename it; the test-case name is still fixed.
+    code = """
+    TEST_F(my_fixture, someTest)
+    """
+    assert reports(code) == [
+        "1: fixture 'my_fixture' is not CamelCase: rename the class to "
+        "'MyFixture' by hand",
+        "1: renamed test case 'someTest' to 'some_test'",
+    ]
+    assert fixed(code) == dedent("""
+        TEST_F(my_fixture, some_test)
+        """)
+
+
+def test_reports_carry_line_numbers() -> None:
+    code = """
+    #include <foo.h>
+
+    TEST(Suite, firstName)
+
+    TEST(Suite, secondName)
+    """
+    assert reports(code) == [
+        "3: renamed test case 'firstName' to 'first_name'",
+        "5: renamed test case 'secondName' to 'second_name'",
+    ]
+
+
+# --- collisions -------------------------------------------------------------
+
+
+def test_collision_reported_and_not_applied() -> None:
+    # Both would define `Suite_mul_div_Test`.
+    code = """
+    TEST(Suite, mulDiv)
+    TEST(Suite, mul_div)
+    """
+    assert reports(code) == [
+        "1: cannot rename 'Suite, mulDiv' to 'Suite, mul_div': another test "
+        "case already generates that name"
+    ]
+    assert fixed(code) == dedent(code)
+
+
+def test_collision_between_converging_suites() -> None:
+    # Both suites camel-case to `SuiteA`, so both would define
+    # `SuiteA_one_test_Test`.
+    code = """
+    TEST(SuiteA, oneTest)
+    TEST(Suite_a, one_test)
+    """
+    assert [r.split(":")[1].strip() for r in reports(code)] == [
+        "cannot rename 'SuiteA, oneTest' to 'SuiteA, one_test'",
+        "cannot rename 'Suite_a, one_test' to 'SuiteA, one_test'",
+    ]
+    assert fixed(code) == dedent(code)
+
+
+def test_same_name_in_different_suites_is_not_a_collision() -> None:
+    code = """
+    TEST(SuiteOne, mulDiv)
+    TEST(SuiteTwo, mulDiv)
+    """
+    assert fixed(code) == dedent("""
+        TEST(SuiteOne, mul_div)
+        TEST(SuiteTwo, mul_div)
+        """)
+
+
+def main() -> int:
+    tests = sorted(
+        (name, fn)
+        for name, fn in globals().items()
+        if name.startswith("test_") and callable(fn)
+    )
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"PASS {name}")
+        except AssertionError as exc:
+            failed += 1
+            print(f"FAIL {name}: {exc!r}")
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -28,7 +28,7 @@
 #    https://vl.ripple.com
 #    https://unl.xrplf.org
 #    http://127.0.0.1:8000
-#    file:///etc/opt/xrpld/vl.txt
+#    file:///etc/xrpld/vl.txt
 #
 # [validator_list_keys]
 #
@@ -488,6 +488,17 @@
 #   Must be a number between 100 and 1000, defaults to 250
 #
 #
+# [max_subscriptions_per_connection]
+#
+#   Maximum number of account, real-time account, and account-history
+#   subscriptions a single client connection may hold at once. Bounds the
+#   per-connection state torn down when the connection disconnects. Book
+#   subscriptions are tracked separately and are not counted here.
+#
+#   Defaults to 100000 if not set; large enough for legitimate power users
+#   such as block explorers.
+#
+#
 # [overlay]
 #
 #   Controls settings related to the peer to peer overlay.
@@ -527,6 +538,56 @@
 #
 #       The current default (which is subject to change) is 300 seconds.
 #
+#   verify_endpoints = <0 | 1>
+#
+#       If set to 0, the server will skip validation of endpoint
+#       addresses received in TMEndpoints peer protocol messages,
+#       allowing addresses that are not publicly routable or have a
+#       port of 0. The default is 1 (verification enabled).
+#
+#       WARNING: Disabling this option is a security risk and should
+#       only be used for local testing and debugging. Do not disable
+#       on mainnet.
+#
+#   max_untrusted_count = <number>
+#
+#       The number of manifests the server keeps for validators it does not
+#       list, and the number it sends and processes in a single peer protocol
+#       message. Once the server holds this many, a manifest for a new
+#       unlisted validator is rejected, so peer gossip cannot grow the cache
+#       without end.
+#
+#       This option can take any value between 50 and 1000, inclusive. If
+#       the option is not present the server uses its built-in value.
+#
+#       The current default (which is subject to change) is 300.
+#
+#   max_trusted_count = <number>
+#
+#       The number of manifests for listed validators to allow for when
+#       sizing peer protocol messages. Manifests for listed validators are
+#       never dropped, whether sending or receiving, because doing so would
+#       delay a validator key change reaching this server. Set this above the
+#       number of validators the server lists.
+#
+#       Together the two counts above set the largest manifest message the
+#       server accepts: bigger messages are discarded without reading them,
+#       and without penalising the sender. Raising either means the server
+#       accepts and sends bigger messages than a peer using the defaults, and
+#       those peers will discard what this server sends. Lowering either below
+#       what peers send makes this server discard their manifest messages,
+#       which it does without recording anything.
+#
+#       This option can take any value between 50 and 1000, inclusive. If
+#       the option is not present the server uses its built-in value.
+#
+#       The current default (which is subject to change) is 300.
+#
+#       NOTE: These two options (max_untrusted_count and max_trusted_count)
+#       are transitional. They exist to bound manifest-message size and cache
+#       growth during the network upgrade. They may be removed in a future
+#       release once the fleet has upgraded, and should not be relied upon as
+#       stable configuration.
 #
 # [transaction_queue] EXPERIMENTAL
 #
@@ -942,6 +1003,21 @@
 #
 #   Optional keys for NuDB and RocksDB:
 #
+#       cache_size          Size of cache for database records. Default is 16384.
+#                           Setting this value to 0 will use the default value.
+#
+#       cache_age           Length of time in minutes to keep database records
+#                           cached. Default is 5 minutes. Setting this value to
+#                           0 will use the default value.
+#
+#                           Note: if cache_size or cache_age is not specified,
+#                           default values will be used for the unspecified
+#                           parameter.
+#
+#                           Note: the cache will not be created if online_delete
+#                           is specified, because the rotating NodeStore does
+#                           not use this cache).
+#
 #       fast_load           Boolean. If set, load the last persisted ledger
 #                           from disk upon process start before syncing to
 #                           the network. This is likely to improve performance
@@ -1018,8 +1094,8 @@
 #                           Default is 100.
 #
 #       back_off_milliseconds
-#                           Number of milliseconds to wait between
-#                           online_delete batches to allow other functions
+#                           Number of milliseconds to wait between online_delete
+#                           SQL deletion batches to allow other functions
 #                           to catch up.
 #                           Default is 100.
 #
@@ -1033,10 +1109,22 @@
 #                           The online delete process checks periodically
 #                           that xrpld is still in sync with the network,
 #                           and that the validated ledger is less than
-#                           'age_threshold_seconds' old. If not, then continue
+#                           'age_threshold_seconds' old, and that all
+#                           recent ledgers are available. If not, then continue
 #                           sleeping for this number of seconds and
 #                           checking until healthy.
-#                           Default is 5.
+#                           Default is 2.
+#
+#       max_waiting_ledgers
+#                           The maximum number of ledgers that may be validated
+#                           while online deletion is waiting for the node to get
+#                           fully synced with the rest of the network. If more than
+#                           this number of ledgers are validated while waiting, then
+#                           online deletion gives up on the current ledger and tries
+#                           again later. Note this only affects situations that cause
+#                           rotation to wait, such as going out of sync, or missing
+#                           ledgers. Forward progress is not penalized. Minimum is 64.
+#                           Default is the online_delete value.
 #
 #   Notes:
 #       The 'node_db' entry configures the primary, persistent storage.
@@ -1258,7 +1346,7 @@
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
-#           account_reserve = 10000000   # 10 XRP
+#           account_reserve = 1000000   # 1 XRP
 #
 #   owner_reserve = <drops>
 #
@@ -1270,8 +1358,41 @@
 #       default. Don't change this without understanding the consequences.
 #
 #       Example:
-#           owner_reserve = 2000000      # 2 XRP
+#           owner_reserve = 200000      # 0.2 XRP
 #
+#   gas_limit = <gas>
+#
+#       The gas limit is the maximum amount of gas that can be
+#       consumed by a single transaction. The gas limit is used to prevent
+#       transactions from consuming too many resources.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           gas_limit = 1000000      # 1 million gas
+#
+#   bytecode_size_limit = <bytes>
+#
+#       The bytecode size limit is the maximum size of a WASM extension in
+#       bytes. The size limit is used to prevent extensions from consuming
+#       too many resources.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           bytecode_size_limit = 100000      # 100 kb
+#
+#   gas_price = <micro-drops>
+#
+#       The gas price is the conversion between WASM gas and its price in drops.
+#
+#       If this parameter is unspecified, xrpld will use an internal
+#       default. Don't change this without understanding the consequences.
+#
+#       Example:
+#           gas_price = 1000000      # 1 drop per gas
 #-------------------------------------------------------------------------------
 #
 # 9. Misc Settings
@@ -1455,10 +1576,7 @@ admin = 127.0.0.1
 protocol = http

 [port_peer]
-# Many servers still use the legacy port of 51235, so for backward-compatibility
-# we maintain that port number here. However, for new servers we recommend
-# changing this to the default port of 2459.
-port = 51235
+port = 2459
 ip = 0.0.0.0
 # alternatively, to accept connections on IPv4 + IPv6, use:
 #ip = ::
@@ -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
 # --------------------------------------------------------------------
@@ -56,3 +77,16 @@ elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64|ARM64")
 else()
    message(FATAL_ERROR "Unknown architecture: ${CMAKE_SYSTEM_PROCESSOR}")
 endif()
+
+# --------------------------------------------------------------------
+# Sanitizers
+# --------------------------------------------------------------------
+# SANITIZERS is injected by the Conan toolchain when a sanitizer build is
+# requested (see conan/profiles/sanitizers). The flags are applied to the
+# 'common' target in XrplSanitizers; this flag lets other modules know a
+# sanitizer build is active without depending on that module.
+if(DEFINED SANITIZERS)
+    set(SANITIZERS_ENABLED TRUE)
+else()
+    set(SANITIZERS_ENABLED FALSE)
+endif()
@@ -1,28 +0,0 @@
-include_guard()
-
-set(GIT_BUILD_BRANCH "")
-set(GIT_COMMIT_HASH "")
-
-find_package(Git)
-if(NOT Git_FOUND)
-    message(WARNING "Git not found. Git branch and commit hash will be empty.")
-    return()
-endif()
-
-set(GIT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/.git)
-
-execute_process(
-    COMMAND
-        ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse --abbrev-ref HEAD
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    OUTPUT_VARIABLE GIT_BUILD_BRANCH
-)
-
-execute_process(
-    COMMAND ${GIT_EXECUTABLE} --git-dir=${GIT_DIRECTORY} rev-parse HEAD
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    OUTPUT_VARIABLE GIT_COMMIT_HASH
-)
-
-message(STATUS "Git branch: ${GIT_BUILD_BRANCH}")
-message(STATUS "Git commit hash: ${GIT_COMMIT_HASH}")
@@ -0,0 +1,90 @@
+#[===================================================================[
+   Patch executables to run in non-Nix environments.
+
+   The Nix toolchain 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` resets
+   the interpreter to the system default loader and drops the rpath, once the
+   binary has been linked.
+
+   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/nix/default-loader-path.sh.
+#]===================================================================]
+
+include_guard(GLOBAL)
+
+include(CompilationEnv)
+
+# Resolves the system default ELF loader path for the current architecture.
+set(_loader_path_script "${CMAKE_SOURCE_DIR}/bin/nix/default-loader-path.sh")
+
+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
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        COMMAND_ERROR_IS_FATAL ANY
+    )
+    find_program(PATCHELF_COMMAND patchelf REQUIRED)
+    set(PATCH_NIX_BINARIES TRUE)
+    message(
+        STATUS
+        "Binaries will be patched to use loader '${DEFAULT_LOADER_PATH}'"
+    )
+else()
+    set(PATCH_NIX_BINARIES FALSE)
+endif()
+
+function(patch_nix_binary target)
+    if(NOT PATCH_NIX_BINARIES)
+        return()
+    endif()
+
+    set(patch_command
+        "${PATCHELF_COMMAND}"
+        --set-interpreter
+        "${DEFAULT_LOADER_PATH}"
+        --remove-rpath
+        "$<TARGET_FILE:${target}>"
+    )
+    set(comment "Patching ${target}: set default loader, remove rpath")
+
+    # POST_BUILD is the cheap way to do this: it runs only when the binary is
+    # relinked. It is also only available in the directory that defined the
+    # target, so for a target from elsewhere (e.g. a FetchContent subproject)
+    # fall back to a custom target that runs after the binary is linked. That
+    # one runs on every build, which is harmless because patchelf is idempotent.
+    get_target_property(target_source_dir ${target} SOURCE_DIR)
+    if("${target_source_dir}" STREQUAL "${CMAKE_CURRENT_SOURCE_DIR}")
+        add_custom_command(
+            TARGET ${target}
+            POST_BUILD
+            COMMAND ${patch_command}
+            COMMENT "${comment}"
+            VERBATIM
+        )
+    else()
+        add_custom_target(
+            ${target}-patch-nix
+            ALL
+            COMMAND ${patch_command}
+            COMMENT "${comment}"
+            VERBATIM
+        )
+        add_dependencies(${target}-patch-nix ${target})
+    endif()
+endfunction()
@@ -0,0 +1,46 @@
+include_guard()
+
+include(isolate_headers)
+
+# Define a benchmark executable for the module `name`.
+#
+# This follows the same general pattern as other build helpers in this repo
+# (e.g. `add_module`): create a target and isolate headers, but here the target
+# is a benchmark executable and no `add_test(...)` is registered.
+#
+# `isolate_headers` exposes only `${CMAKE_CURRENT_SOURCE_DIR}/${name}` on the
+# include path, rooted at `src`, so a benchmark's own headers are reached as
+# `<benchmarks/.../${name}/...>` and nothing else in the tree leaks in.
+function(xrpl_add_benchmark name)
+    set(target ${PROJECT_NAME}.bench.${name})
+
+    file(
+        GLOB_RECURSE sources
+        CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}/*.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}.cpp"
+    )
+    add_executable(${target} ${ARGN} ${sources})
+
+    # Benchmark sources register cases through Google Benchmark's static
+    # registrars (anonymous-namespace lambdas). Merging several such files into
+    # one unity translation unit collides those internal-linkage entities, so
+    # keep benchmarks out of the unity build - mirroring xrpl.libpb in
+    # XrplCore.cmake. Each file compiles fine on its own.
+    set_target_properties(${target} PROPERTIES UNITY_BUILD OFF)
+
+    # Land next to `xrpl_tests` in the build root rather than buried under
+    # `src/benchmarks/libxrpl/`. A benchmark is something a person runs by hand,
+    # repeatedly, and comparing two of them should not mean typing two long paths.
+    set_target_properties(
+        ${target}
+        PROPERTIES RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
+    )
+
+    isolate_headers(
+        ${target}
+        "${CMAKE_SOURCE_DIR}/src"
+        "${CMAKE_CURRENT_SOURCE_DIR}/${name}"
+        PRIVATE
+    )
+endfunction()
@@ -1,22 +0,0 @@
-include(isolate_headers)
-
-function(xrpl_add_test name)
-    set(target ${PROJECT_NAME}.test.${name})
-
-    file(
-        GLOB_RECURSE sources
-        CONFIGURE_DEPENDS
-        "${CMAKE_CURRENT_SOURCE_DIR}/${name}/*.cpp"
-        "${CMAKE_CURRENT_SOURCE_DIR}/${name}.cpp"
-    )
-    add_executable(${target} ${ARGN} ${sources})
-
-    isolate_headers(
-        ${target}
-        "${CMAKE_SOURCE_DIR}"
-        "${CMAKE_SOURCE_DIR}/tests/${name}"
-        PRIVATE
-    )
-
-    add_test(NAME ${target} COMMAND ${target})
-endfunction()
@@ -120,7 +120,10 @@ if(MSVC)
            _SILENCE_ALL_CXX17_DEPRECATION_WARNINGS
            $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CONFIG:Debug>>:_CRTDBG_MAP_ALLOC>
    )
-    target_link_libraries(common INTERFACE -errorreport:none -machine:X64)
+    target_link_libraries(
+        common
+        INTERFACE -errorreport:none -machine:X64 -ignore:4099
+    )
 else()
    target_compile_options(
        common
@@ -145,13 +148,47 @@ else()
        INTERFACE
            -rdynamic
            $<$<BOOL:${is_linux}>:-Wl,-z,relro,-z,now,--build-id>
-            # link to static libc/c++ iff: * static option set and * NOT APPLE (AppleClang does not support static
-            # libc/c++) and * NOT SANITIZERS (sanitizers typically don't work with static libc/c++)
-            $<$<AND:$<BOOL:${static}>,$<NOT:$<BOOL:${APPLE}>>,$<NOT:$<BOOL:${SANITIZERS_ENABLED}>>>:
+            # link to static libc/c++ if:
+            # * static option set and
+            # * NOT APPLE (AppleClang does not support static libc/c++)
+            $<$<AND:$<BOOL:${static}>,$<NOT:$<BOOL:${APPLE}>>>:
            -static-libstdc++
            -static-libgcc
            >
    )
+
+    # On aarch64, libatomic is required for atomic operations. It is not needed on x86_64.
+    # Linking it statically on Linux
+    if(is_arm64 AND is_linux)
+        target_link_options(
+            common
+            INTERFACE -Wl,--push-state -Wl,-Bstatic -latomic -Wl,--pop-state
+        )
+    endif()
+
+    # Keep -stdlib=libstdc++ off the compile commands, but preserve it for linking.
+    #
+    # Conan turns `compiler.libcxx=libstdc++` into `-stdlib=libstdc++` and puts it in
+    # CMAKE_CXX_FLAGS, which CMake passes to BOTH compile and link steps. On a normal Clang
+    # the compile step consumes it while choosing the C++ stdlib include paths. The Nixpkgs
+    # 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.
+    if(
+        is_nix_compiler
+        AND is_linux
+        AND is_clang
+        AND CMAKE_CXX_FLAGS MATCHES "stdlib=libstdc"
+    )
+        string(
+            REPLACE "-stdlib=libstdc++"
+            ""
+            CMAKE_CXX_FLAGS
+            "${CMAKE_CXX_FLAGS}"
+        )
+        string(STRIP "${CMAKE_CXX_FLAGS}" CMAKE_CXX_FLAGS)
+        add_link_options($<$<LINK_LANGUAGE:CXX>:-stdlib=libstdc++>)
+    endif()
 endif()

 # Antithesis instrumentation will only be built and deployed using machines running Linux.
@@ -232,10 +269,50 @@ elseif(use_lld)
    )
    if("${LD_VERSION}" MATCHES "LLD")
        target_link_libraries(common INTERFACE -fuse-ld=lld)
+        # remembered for the linker flag probe below
+        set(fuse_ld_flag "-fuse-ld=lld")
    endif()
    unset(LD_VERSION)
 endif()

+# Linker warnings are errors where we control the toolchain and the dependencies: CI and the Nix dev shell.
+# On non-Nix macOS we suppress the deployment target warning: an old Conan profile may not pin os.version.
+# Only the new Apple linker understands the flag, so probe the actual linker (lld may be selected above).
+if(is_macos OR is_linux)
+    if(is_ci OR is_nix_compiler)
+        if(is_macos)
+            set(fatal_warnings_flag "-Wl,-fatal_warnings")
+        else()
+            set(fatal_warnings_flag "-Wl,--fatal-warnings")
+        endif()
+        message(
+            STATUS
+            "Treating all linker warnings as errors (${fatal_warnings_flag})"
+        )
+        target_link_options(common INTERFACE "${fatal_warnings_flag}")
+        unset(fatal_warnings_flag)
+    elseif(is_macos)
+        set(silence_flag "-Wl,-deployment_target_mismatches,suppress")
+        set(probe_flags ${fuse_ld_flag} "${silence_flag}")
+        include(CheckLinkerFlag)
+        check_linker_flag(
+            CXX
+            "${probe_flags}"
+            have_deployment_target_mismatches
+        )
+        if(have_deployment_target_mismatches)
+            message(
+                STATUS
+                "Silencing macOS deployment target mismatch warnings (${silence_flag})"
+            )
+            target_link_options(common INTERFACE "${silence_flag}")
+        endif()
+        unset(probe_flags)
+        unset(silence_flag)
+    endif()
+endif()
+unset(fuse_ld_flag)
+
 if(assert)
    foreach(var_ CMAKE_C_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELEASE)
        string(REGEX REPLACE "[-/]DNDEBUG" "" ${var_} "${${var_}}")