From 6d2952c3c3527865fce1bbe6ce00572b04a1edb6 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:03:34 +0000
Subject: [PATCH 1/6] serialize: Add missing `<span>` header

Including the missing `<span>` header in `serialize.h` allows IWYU to
correctly evaluate its redundancy elsewhere.
---
 src/index/base.cpp             | 1 -
 src/index/blockfilterindex.cpp | 1 -
 src/index/coinstatsindex.cpp   | 1 -
 src/index/txindex.cpp          | 1 -
 src/index/txospenderindex.cpp  | 1 -
 src/kernel/coinstats.cpp       | 1 -
 src/node/utxo_snapshot.cpp     | 1 -
 src/primitives/block.cpp       | 1 -
 src/serialize.h                | 1 +
 src/zmq/zmqpublishnotifier.cpp | 1 -
 10 files changed, 1 insertion(+), 9 deletions(-)

diff --git a/src/index/base.cpp b/src/index/base.cpp
index fba2f4f6c10..851b3cda2dd 100644
--- a/src/index/base.cpp
+++ b/src/index/base.cpp
@@ -35,7 +35,6 @@
 #include <cstdint>
 #include <memory>
 #include <optional>
-#include <span>
 #include <stdexcept>
 #include <string>
 #include <thread>
diff --git a/src/index/blockfilterindex.cpp b/src/index/blockfilterindex.cpp
index 67fa1fab318..e63aa4a332c 100644
--- a/src/index/blockfilterindex.cpp
+++ b/src/index/blockfilterindex.cpp
@@ -28,7 +28,6 @@
 #include <exception>
 #include <map>
 #include <optional>
-#include <span>
 #include <stdexcept>
 #include <string>
 #include <tuple>
diff --git a/src/index/coinstatsindex.cpp b/src/index/coinstatsindex.cpp
index 319ffcadc63..80a6d8dfd2b 100644
--- a/src/index/coinstatsindex.cpp
+++ b/src/index/coinstatsindex.cpp
@@ -30,7 +30,6 @@
 
 #include <compare>
 #include <limits>
-#include <span>
 #include <string>
 #include <utility>
 #include <vector>
diff --git a/src/index/txindex.cpp b/src/index/txindex.cpp
index d0e88021325..4b0c82877ab 100644
--- a/src/index/txindex.cpp
+++ b/src/index/txindex.cpp
@@ -24,7 +24,6 @@
 #include <cstdint>
 #include <cstdio>
 #include <exception>
-#include <span>
 #include <string>
 #include <utility>
 #include <vector>
diff --git a/src/index/txospenderindex.cpp b/src/index/txospenderindex.cpp
index d451bb1e0a4..f0d559a958f 100644
--- a/src/index/txospenderindex.cpp
+++ b/src/index/txospenderindex.cpp
@@ -26,7 +26,6 @@
 #include <cstdio>
 #include <exception>
 #include <ios>
-#include <span>
 #include <string>
 #include <utility>
 #include <vector>
diff --git a/src/kernel/coinstats.cpp b/src/kernel/coinstats.cpp
index 49b51d64f30..4e30a876229 100644
--- a/src/kernel/coinstats.cpp
+++ b/src/kernel/coinstats.cpp
@@ -22,7 +22,6 @@
 
 #include <map>
 #include <memory>
-#include <span>
 #include <utility>
 #include <version>
 
diff --git a/src/node/utxo_snapshot.cpp b/src/node/utxo_snapshot.cpp
index e5997b7b65b..4b61a76c6eb 100644
--- a/src/node/utxo_snapshot.cpp
+++ b/src/node/utxo_snapshot.cpp
@@ -15,7 +15,6 @@
 #include <cassert>
 #include <cstdio>
 #include <optional>
-#include <span>
 #include <string>
 
 namespace node {
diff --git a/src/primitives/block.cpp b/src/primitives/block.cpp
index dfeed29575c..0e81b74d375 100644
--- a/src/primitives/block.cpp
+++ b/src/primitives/block.cpp
@@ -9,7 +9,6 @@
 #include <tinyformat.h>
 
 #include <memory>
-#include <span>
 #include <sstream>
 
 uint256 CBlockHeader::GetHash() const
diff --git a/src/serialize.h b/src/serialize.h
index 9c18c72734b..4c33311c1c9 100644
--- a/src/serialize.h
+++ b/src/serialize.h
@@ -22,6 +22,7 @@
 #include <map>
 #include <memory>
 #include <set>
+#include <span>
 #include <string>
 #include <utility>
 #include <vector>
diff --git a/src/zmq/zmqpublishnotifier.cpp b/src/zmq/zmqpublishnotifier.cpp
index 56cdea05e3a..61b65a1317a 100644
--- a/src/zmq/zmqpublishnotifier.cpp
+++ b/src/zmq/zmqpublishnotifier.cpp
@@ -24,7 +24,6 @@
 #include <cstring>
 #include <map>
 #include <optional>
-#include <span>
 #include <string>
 #include <utility>
 #include <vector>

From 179abb387f4c4196b6ea8914dd703e4d3f52187d Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Fri, 20 Mar 2026 15:37:44 +0000
Subject: [PATCH 2/6] refactor: Move `StdMutex` to its own header

This makes `threadsafety.h` agnostic to the actual implementation.
---
 src/logging.h       |  2 +-
 src/threadsafety.h  | 24 ------------------------
 src/util/stdmutex.h | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+), 25 deletions(-)
 create mode 100644 src/util/stdmutex.h

diff --git a/src/logging.h b/src/logging.h
index e21495015b6..803bdac1c42 100644
--- a/src/logging.h
+++ b/src/logging.h
@@ -8,9 +8,9 @@
 
 #include <crypto/siphash.h>
 #include <logging/categories.h> // IWYU pragma: export
-#include <threadsafety.h>
 #include <util/fs.h>
 #include <util/log.h> // IWYU pragma: export
+#include <util/stdmutex.h>
 #include <util/string.h>
 #include <util/time.h>
 
diff --git a/src/threadsafety.h b/src/threadsafety.h
index b79d4c76458..35f3b813273 100644
--- a/src/threadsafety.h
+++ b/src/threadsafety.h
@@ -6,8 +6,6 @@
 #ifndef BITCOIN_THREADSAFETY_H
 #define BITCOIN_THREADSAFETY_H
 
-#include <mutex>
-
 #ifdef __clang__
 // TL;DR Add GUARDED_BY(mutex) to member variables. The others are
 // rarely necessary. Ex: int nFoo GUARDED_BY(cs_foo);
@@ -54,26 +52,4 @@
 #define ASSERT_EXCLUSIVE_LOCK(...)
 #endif // __GNUC__
 
-// StdMutex provides an annotated version of std::mutex for us,
-// and should only be used when sync.h Mutex/LOCK/etc are not usable.
-class LOCKABLE StdMutex : public std::mutex
-{
-public:
-#ifdef __clang__
-    //! For negative capabilities in the Clang Thread Safety Analysis.
-    //! A negative requirement uses the EXCLUSIVE_LOCKS_REQUIRED attribute, in conjunction
-    //! with the ! operator, to indicate that a mutex should not be held.
-    const StdMutex& operator!() const { return *this; }
-#endif // __clang__
-};
-
-// StdLockGuard provides an annotated version of std::lock_guard for us,
-// and should only be used when sync.h Mutex/LOCK/etc are not usable.
-class SCOPED_LOCKABLE StdLockGuard : public std::lock_guard<StdMutex>
-{
-public:
-    explicit StdLockGuard(StdMutex& cs) EXCLUSIVE_LOCK_FUNCTION(cs) : std::lock_guard<StdMutex>(cs) {}
-    ~StdLockGuard() UNLOCK_FUNCTION() = default;
-};
-
 #endif // BITCOIN_THREADSAFETY_H
diff --git a/src/util/stdmutex.h b/src/util/stdmutex.h
new file mode 100644
index 00000000000..4c3c0cec5ed
--- /dev/null
+++ b/src/util/stdmutex.h
@@ -0,0 +1,35 @@
+// Copyright (c) 2009-2010 Satoshi Nakamoto
+// Copyright (c) 2009-present The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_UTIL_STDMUTEX_H
+#define BITCOIN_UTIL_STDMUTEX_H
+
+#include <threadsafety.h> // IWYU pragma: export
+
+#include <mutex>
+
+// StdMutex provides an annotated version of std::mutex for us,
+// and should only be used when sync.h Mutex/LOCK/etc are not usable.
+class LOCKABLE StdMutex : public std::mutex
+{
+public:
+#ifdef __clang__
+    //! For negative capabilities in the Clang Thread Safety Analysis.
+    //! A negative requirement uses the EXCLUSIVE_LOCKS_REQUIRED attribute, in conjunction
+    //! with the ! operator, to indicate that a mutex should not be held.
+    const StdMutex& operator!() const { return *this; }
+#endif // __clang__
+};
+
+// StdLockGuard provides an annotated version of std::lock_guard for us,
+// and should only be used when sync.h Mutex/LOCK/etc are not usable.
+class SCOPED_LOCKABLE StdLockGuard : public std::lock_guard<StdMutex>
+{
+public:
+    explicit StdLockGuard(StdMutex& cs) EXCLUSIVE_LOCK_FUNCTION(cs) : std::lock_guard<StdMutex>(cs) {}
+    ~StdLockGuard() UNLOCK_FUNCTION() = default;
+};
+
+#endif // BITCOIN_UTIL_STDMUTEX_H

From 48bfcfedec01b66263d37e6c785b7079161ded6d Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:03:51 +0000
Subject: [PATCH 3/6] iwyu, doc: Document `IWYU pragma: export` for
 `<threadsafety.h>`

---
 src/index/base.h                         | 2 +-
 src/net_processing.h                     | 1 -
 src/node/chainstate.cpp                  | 1 -
 src/node/kernel_notifications.h          | 1 -
 src/policy/fees/block_policy_estimator.h | 1 -
 src/policy/rbf.h                         | 2 +-
 src/private_broadcast.h                  | 1 -
 src/rpc/blockchain.h                     | 1 -
 src/scheduler.h                          | 1 -
 src/sync.h                               | 2 ++
 src/test/fuzz/util/net.h                 | 2 +-
 src/util/stdmutex.h                      | 2 ++
 src/util/threadinterrupt.h               | 1 -
 13 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/index/base.h b/src/index/base.h
index d8fd8566933..63f60be0349 100644
--- a/src/index/base.h
+++ b/src/index/base.h
@@ -9,7 +9,7 @@
 #include <dbwrapper.h>
 #include <interfaces/chain.h>
 #include <kernel/cs_main.h>
-#include <threadsafety.h>
+#include <sync.h>
 #include <uint256.h>
 #include <util/fs.h>
 #include <util/threadinterrupt.h>
diff --git a/src/net_processing.h b/src/net_processing.h
index 6339852327b..d2050d8f3d7 100644
--- a/src/net_processing.h
+++ b/src/net_processing.h
@@ -11,7 +11,6 @@
 #include <node/txorphanage.h>
 #include <private_broadcast.h>
 #include <protocol.h>
-#include <threadsafety.h>
 #include <uint256.h>
 #include <util/expected.h>
 #include <validationinterface.h>
diff --git a/src/node/chainstate.cpp b/src/node/chainstate.cpp
index ff3de298227..0738c00aef8 100644
--- a/src/node/chainstate.cpp
+++ b/src/node/chainstate.cpp
@@ -11,7 +11,6 @@
 #include <kernel/caches.h>
 #include <node/blockstorage.h>
 #include <sync.h>
-#include <threadsafety.h>
 #include <tinyformat.h>
 #include <txdb.h>
 #include <uint256.h>
diff --git a/src/node/kernel_notifications.h b/src/node/kernel_notifications.h
index b90248bf0ab..b152e7a476a 100644
--- a/src/node/kernel_notifications.h
+++ b/src/node/kernel_notifications.h
@@ -8,7 +8,6 @@
 #include <kernel/notifications_interface.h>
 
 #include <sync.h>
-#include <threadsafety.h>
 #include <uint256.h>
 
 #include <atomic>
diff --git a/src/policy/fees/block_policy_estimator.h b/src/policy/fees/block_policy_estimator.h
index 026bf1eb842..f015bd5b683 100644
--- a/src/policy/fees/block_policy_estimator.h
+++ b/src/policy/fees/block_policy_estimator.h
@@ -9,7 +9,6 @@
 #include <policy/feerate.h>
 #include <random.h>
 #include <sync.h>
-#include <threadsafety.h>
 #include <uint256.h>
 #include <util/fs.h>
 #include <validationinterface.h>
diff --git a/src/policy/rbf.h b/src/policy/rbf.h
index ad8a2dbfa3b..0ba646ca8d1 100644
--- a/src/policy/rbf.h
+++ b/src/policy/rbf.h
@@ -7,7 +7,7 @@
 
 #include <consensus/amount.h>
 #include <primitives/transaction.h>
-#include <threadsafety.h>
+#include <sync.h>
 #include <txmempool.h>
 #include <util/feefrac.h>
 
diff --git a/src/private_broadcast.h b/src/private_broadcast.h
index 286344248d9..fec61907dd3 100644
--- a/src/private_broadcast.h
+++ b/src/private_broadcast.h
@@ -9,7 +9,6 @@
 #include <primitives/transaction.h>
 #include <primitives/transaction_identifier.h>
 #include <sync.h>
-#include <threadsafety.h>
 #include <util/time.h>
 
 #include <optional>
diff --git a/src/rpc/blockchain.h b/src/rpc/blockchain.h
index efb06ac2d29..53f6a804f99 100644
--- a/src/rpc/blockchain.h
+++ b/src/rpc/blockchain.h
@@ -9,7 +9,6 @@
 #include <core_io.h>
 #include <streams.h>
 #include <sync.h>
-#include <threadsafety.h>
 #include <util/fs.h>
 #include <validation.h>
 
diff --git a/src/scheduler.h b/src/scheduler.h
index 79b8afd2ada..5d4affb0ab8 100644
--- a/src/scheduler.h
+++ b/src/scheduler.h
@@ -7,7 +7,6 @@
 
 #include <attributes.h>
 #include <sync.h>
-#include <threadsafety.h>
 #include <util/task_runner.h>
 
 #include <chrono>
diff --git a/src/sync.h b/src/sync.h
index 00fdaae942b..123184d44f6 100644
--- a/src/sync.h
+++ b/src/sync.h
@@ -6,6 +6,8 @@
 #ifndef BITCOIN_SYNC_H
 #define BITCOIN_SYNC_H
 
+// This header declares threading primitives compatible with Clang
+// Thread Safety Analysis and provides appropriate annotation macros.
 #include <threadsafety.h> // IWYU pragma: export
 #include <util/macros.h>
 
diff --git a/src/test/fuzz/util/net.h b/src/test/fuzz/util/net.h
index 862153ab26f..36393811624 100644
--- a/src/test/fuzz/util/net.h
+++ b/src/test/fuzz/util/net.h
@@ -13,10 +13,10 @@
 #include <node/connection_types.h>
 #include <node/eviction.h>
 #include <protocol.h>
+#include <sync.h>
 #include <test/fuzz/FuzzedDataProvider.h>
 #include <test/fuzz/util.h>
 #include <test/util/net.h>
-#include <threadsafety.h>
 #include <util/asmap.h>
 #include <util/sock.h>
 
diff --git a/src/util/stdmutex.h b/src/util/stdmutex.h
index 4c3c0cec5ed..7a3e3039546 100644
--- a/src/util/stdmutex.h
+++ b/src/util/stdmutex.h
@@ -6,6 +6,8 @@
 #ifndef BITCOIN_UTIL_STDMUTEX_H
 #define BITCOIN_UTIL_STDMUTEX_H
 
+// This header declares threading primitives compatible with Clang
+// Thread Safety Analysis and provides appropriate annotation macros.
 #include <threadsafety.h> // IWYU pragma: export
 
 #include <mutex>
diff --git a/src/util/threadinterrupt.h b/src/util/threadinterrupt.h
index 84ced9277aa..9cac330e3d2 100644
--- a/src/util/threadinterrupt.h
+++ b/src/util/threadinterrupt.h
@@ -6,7 +6,6 @@
 #define BITCOIN_UTIL_THREADINTERRUPT_H
 
 #include <sync.h>
-#include <threadsafety.h>
 
 #include <atomic>
 #include <chrono>

From 015bea05e6a067696601fa83b1e9d80360064e24 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:03:59 +0000
Subject: [PATCH 4/6] iwyu, doc: Document `IWYU pragma: export` for `<chrono>`

---
 src/kernel/mempool_entry.h   | 2 +-
 src/kernel/mempool_options.h | 2 +-
 src/util/time.h              | 1 +
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/kernel/mempool_entry.h b/src/kernel/mempool_entry.h
index dd0c23a2cde..29ca1fd0e28 100644
--- a/src/kernel/mempool_entry.h
+++ b/src/kernel/mempool_entry.h
@@ -13,8 +13,8 @@
 #include <primitives/transaction.h>
 #include <txgraph.h>
 #include <util/overflow.h>
+#include <util/time.h>
 
-#include <chrono>
 #include <cstddef>
 #include <cstdint>
 #include <functional>
diff --git a/src/kernel/mempool_options.h b/src/kernel/mempool_options.h
index a18d565c65c..392c837fbbf 100644
--- a/src/kernel/mempool_options.h
+++ b/src/kernel/mempool_options.h
@@ -8,8 +8,8 @@
 
 #include <policy/feerate.h>
 #include <policy/policy.h>
+#include <util/time.h>
 
-#include <chrono>
 #include <cstdint>
 #include <optional>
 
diff --git a/src/util/time.h b/src/util/time.h
index 967ea780aaf..30d363bb612 100644
--- a/src/util/time.h
+++ b/src/util/time.h
@@ -6,6 +6,7 @@
 #ifndef BITCOIN_UTIL_TIME_H
 #define BITCOIN_UTIL_TIME_H
 
+// The `util/time.h` header is designed to be a drop-in replacement for `chrono`.
 #include <chrono> // IWYU pragma: export
 #include <cstdint>
 #include <optional>

From cfa3b10d50d3d71be7fc718c2a21e4a5909c590b Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:04:13 +0000
Subject: [PATCH 5/6] iwyu, doc: Document `IWYU pragma: export` for
 `<logging/categories.h>`

---
 src/util/log.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/util/log.h b/src/util/log.h
index aae23f0df1e..1bec49f2298 100644
--- a/src/util/log.h
+++ b/src/util/log.h
@@ -5,6 +5,8 @@
 #ifndef BITCOIN_UTIL_LOG_H
 #define BITCOIN_UTIL_LOG_H
 
+// This header works in tandem with `logging/categories.h`
+// to expose the complete logging interface.
 #include <logging/categories.h> // IWYU pragma: export
 #include <tinyformat.h>
 #include <util/check.h>

From 0fe6fccec279f9799dfb84c36cf9033eedcc2c32 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Fri, 13 Mar 2026 12:54:18 +0000
Subject: [PATCH 6/6] doc: Document rationale for using `IWYU pragma: export`

---
 doc/developer-notes.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index d8ce01c8118..399fcbd094d 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -542,6 +542,13 @@ to a function that accepts a `std::string` parameter. An implicit conversion occ
 Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers
 and undermines the specific purpose of IWYU.
 
+The acceptable cases for using `IWYU pragma: export` are:
+1. Facade headers. For example, see [`compat/compat.h`](/src/compat/compat.h).
+2. Drop-in replacement headers. For example, see [`util/time.h`](/src/util/time.h).
+3. Presenting a complete interface across multiple headers.
+
+A comment explaining the rationale is required for every use of `IWYU pragma: export`.
+
 ### Performance profiling with perf
 
 Profiling is a good way to get a precise idea of where time is being spent in