diff --git a/crates/types/src/codec/mod.rs b/crates/types/src/codec/mod.rs
index 6487896..1cffc90 100644
--- a/crates/types/src/codec/mod.rs
+++ b/crates/types/src/codec/mod.rs
@@ -26,6 +26,11 @@ pub use malachitebft_codec::{Codec, HasEncodedLen};
 /// - `$ty`: The message type to encode/decode
 /// - `$version_ty`: The version enum type
 /// - `$version_val`: The specific version value to use
+///
+/// Must stay above the `pub mod` declarations at the bottom of this file:
+/// `network` reaches this macro through textual scope, not through a path, so
+/// moving the module declarations above it — or moving this below them —
+/// breaks all 8 invocation sites with `cannot find macro`.
 macro_rules! impl_versioned_codec {
     ($codec_ty:ty, $ty:ty, $version_ty:ty, $version_val:expr) => {
         impl malachitebft_codec::Codec<$ty> for $codec_ty {
@@ -75,6 +80,9 @@ macro_rules! impl_versioned_codec {
 /// This is only for persisted data formats that predate version bytes, such as
 /// the WAL. Networked types are already versioned and should use
 /// `impl_versioned_codec!` instead.
+///
+/// Same ordering constraint as `impl_versioned_codec!`: `wal` reaches this
+/// through textual scope, so it must stay above the `pub mod` declarations.
 macro_rules! impl_versioned_codec_with_legacy_fallback {
     ($codec_ty:ty, $ty:ty, $version_ty:ty, $version_val:expr) => {
         impl malachitebft_codec::Codec<$ty> for $codec_ty {