dig_rpc_protocol/

method.rs

//! The canonical DIG-node RPC method catalogue.
//!
//! [`Method`] enumerates every JSON-RPC method the DIG node surface exposes, its
//! stable wire name, its primary [`Tier`], and whether it is reachable over the
//! mTLS peer surface. This is the single method table the OpenRPC generator,
//! both node dispatchers, and the server's allow-list all read — so the name set,
//! the tier map, and the peer allowlist can never drift from one another.
//!
//! Frame families that are shape-dispatched rather than carried in a JSON-RPC
//! `method` field — the DHT (`find_node` / `find_providers` / `add_provider` /
//! `ping`) and PEX (`pex_handshake` / `pex_snapshot` / `pex_delta` /
//! `pex_error`) wires — are documented in [`crate::frames`] and are not
//! `Method` variants.

use crate::tier::Tier;

/// Generates [`Method`] and [`Method::ALL`] from ONE variant table.
///
/// This exists so a new method cannot enter the enum without also entering
/// `ALL`: the two used to be two hand-written lists (the enum body and a
/// literal `&[Method::...]` array), and a variant added to one while
/// forgotten in the other left it invisible to every `ALL`-driven guard in
/// this module -- including the one enforcing dig_ecosystem#3261 ("no
/// `*Reward*` method may ever be peer-reachable or non-`Control`"). With one
/// source table, that omission is unwritable rather than merely testable
/// (dig_ecosystem#3317).
///
/// `name()`, `tier()`, `is_peer_reachable()` and `is_reward()` stay
/// hand-written exhaustive matches below -- they are already compiler-forced
/// (adding a variant is `E0004` until every one of them is updated), and
/// generating them too would hide the method table behind macro grammar for
/// no completeness gain.
macro_rules! method_catalogue {
    ($( $(#[$doc:meta])* $variant:ident ),+ $(,)?) => {
        /// A DIG-node RPC method.
        ///
        /// `#[non_exhaustive]` so adding a method in a minor release is additive.
        /// Convert to/from the wire name with [`Method::name`] / [`Method::from_name`].
        #[non_exhaustive]
        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
        pub enum Method {
            $( $(#[$doc])* $variant ),+
        }

        impl Method {
            /// Every method, in catalogue order. Generated by
            /// `method_catalogue!` from the same table that defines the enum, so
            /// a variant cannot exist without also being listed here.
            pub const ALL: &'static [Method] = &[ $( Method::$variant ),+ ];
        }
    };
}

method_catalogue! {
    // ---- PublicRead ----
    /// `dig.getContent` — a verified resource-window read.
    GetContent,
    /// `dig.getCapsule` — the whole `.dig` module for `(store, root)`.
    GetCapsule,
    /// `dig.getModule` — alias of [`GetCapsule`](Method::GetCapsule).
    GetModule,
    /// `dig.getManifest` — the public discovery manifest resource.
    GetManifest,
    /// `dig.getMetadata` — the plaintext metadata manifest (never encrypted).
    GetMetadata,
    /// `dig.listCapsules` — the confirmed capsule list (discovery metadata).
    ListCapsules,
    /// `dig.getProof` — the real inclusion proof + execution-proof status.
    GetProof,
    /// `dig.getProofStatus` — poll a real execution-proof job by id.
    GetProofStatus,
    /// `dig.getAnchoredRoot` — resolve a store's chain-anchored tip root.
    /// (Also peer-reachable.)
    GetAnchoredRoot,
    /// `dig.getCollection` — collection-level facts for a set of NFT launchers.
    /// (Also peer-reachable.)
    GetCollection,
    /// `dig.listCollectionItems` — a page of resolved collection items.
    /// (Also peer-reachable.)
    ListCollectionItems,
    /// `dig.health` — liveness + capability summary.
    Health,
    /// `dig.methods` — the implemented method names (agent self-describe).
    Methods,

    // ---- Peer ----
    /// `dig.getNetworkInfo` — this node's peer-network posture.
    GetNetworkInfo,
    /// `dig.getPeers` — the peers this node knows (peer exchange).
    GetPeers,
    /// `dig.announce` — accept a peer announcement.
    Announce,
    /// `dig.getAvailability` — batch presence check across stores/roots/capsules.
    GetAvailability,
    /// `dig.listInventory` — enumerate what this node serves.
    ListInventory,
    /// `dig.fetchRange` — a single verified range frame of a resource.
    FetchRange,
    /// `dig.getModuleInfo` — the whole-`.dig`-module transfer descriptor
    /// (total size + module hash + per-chunk hashes) for `(store, root)`, the
    /// handshake a peer reads before range-pulling the module blob.
    GetModuleInfo,
    /// `dig.fetchModuleRange` — a single range frame of the whole `.dig` module
    /// blob for `(store, root)` (reuses [`RangeFrame`](crate::types::RangeFrame)).
    FetchModuleRange,

    // ---- Control (loopback / in-process only) ----
    /// `dig.stage` — compile a local folder into a capsule `.dig` in-process.
    Stage,
    /// `cache.getConfig` — the local-cache config.
    CacheGetConfig,
    /// `cache.setCapBytes` — set the cache size cap.
    CacheSetCapBytes,
    /// `cache.clear` — clear the cache.
    CacheClear,
    /// `cache.listCached` — the durable module inventory.
    CacheListCached,
    /// `cache.removeCached` — remove one cached capsule.
    CacheRemoveCached,
    /// `cache.fetchAndCache` — fetch + cache one capsule.
    CacheFetchAndCache,
    /// `cache.stats` — cache telemetry: reserved cap + live usage, cached-capsule
    /// count + total on-disk bytes, session eviction + content-cache hit/miss.
    CacheStats,
    /// `control.peerStatus` — the peer-network status snapshot.
    ControlPeerStatus,
    /// `control.subscribe` — subscribe the node to a store (persisted): it
    /// actively watches + gap-fills that store.
    ControlSubscribe,
    /// `control.unsubscribe` — remove a store from the node's subscription set.
    ControlUnsubscribe,
    /// `control.listSubscriptions` — the node's persisted store subscriptions.
    ControlListSubscriptions,
    /// `control.peers.connect` — dial a peer (turn a discovered peer into a
    /// counted, RPC-reachable connected peer).
    ControlPeersConnect,
    /// `control.peers.disconnect` — drop a pooled peer by `peer_id`, closing its
    /// mTLS link (the inverse of `control.peers.connect`).
    ControlPeersDisconnect,
    /// `dig.listRewardDistributors` — the reward distributors this node funds,
    /// and the ones it has a claim to as a mirror (dig-rewards-coin SPEC §2.6).
    ListRewardDistributors,
    /// `dig.getRewardProverStatus` — the always-on reward prover loop's status
    /// for one or every distributor this node runs (dig-rewards-coin SPEC §2.3).
    GetRewardProverStatus,
    /// `dig.getRewardDistributor` — one reward distributor's chain-derived
    /// state (dig-rewards-coin SPEC §2.6).
    GetRewardDistributor,
    /// `dig.listRewardDistributorCommitments` — one distributor's per-epoch
    /// clawback commitment slots, with the recoverable amount computed per
    /// slot (dig-rewards-coin SPEC §7.4 clause 5, §7.5).
    ListRewardDistributorCommitments,
    /// `dig.getPayeeRewardClaimStatus` — this node's own claim-side posture as a
    /// **payee** (dig-rewards-coin SPEC §12.5 clause 6, §2.4).
    GetPayeeRewardClaimStatus,
    /// `rpc.discover` — the OpenRPC self-describe document.
    RpcDiscover,
}

impl Method {
    // ---- hand-written exhaustive classifiers (compiler-forced, not generated) ----

    /// The stable JSON-RPC wire name.
    pub const fn name(self) -> &'static str {
        match self {
            Method::GetContent => "dig.getContent",
            Method::GetCapsule => "dig.getCapsule",
            Method::GetModule => "dig.getModule",
            Method::GetManifest => "dig.getManifest",
            Method::GetMetadata => "dig.getMetadata",
            Method::ListCapsules => "dig.listCapsules",
            Method::GetProof => "dig.getProof",
            Method::GetProofStatus => "dig.getProofStatus",
            Method::GetAnchoredRoot => "dig.getAnchoredRoot",
            Method::GetCollection => "dig.getCollection",
            Method::ListCollectionItems => "dig.listCollectionItems",
            Method::Health => "dig.health",
            Method::Methods => "dig.methods",
            Method::GetNetworkInfo => "dig.getNetworkInfo",
            Method::GetPeers => "dig.getPeers",
            Method::Announce => "dig.announce",
            Method::GetAvailability => "dig.getAvailability",
            Method::ListInventory => "dig.listInventory",
            Method::FetchRange => "dig.fetchRange",
            Method::GetModuleInfo => "dig.getModuleInfo",
            Method::FetchModuleRange => "dig.fetchModuleRange",
            Method::Stage => "dig.stage",
            Method::CacheGetConfig => "cache.getConfig",
            Method::CacheSetCapBytes => "cache.setCapBytes",
            Method::CacheClear => "cache.clear",
            Method::CacheListCached => "cache.listCached",
            Method::CacheRemoveCached => "cache.removeCached",
            Method::CacheFetchAndCache => "cache.fetchAndCache",
            Method::CacheStats => "cache.stats",
            Method::ControlPeerStatus => "control.peerStatus",
            Method::ControlSubscribe => "control.subscribe",
            Method::ControlUnsubscribe => "control.unsubscribe",
            Method::ControlListSubscriptions => "control.listSubscriptions",
            Method::ControlPeersConnect => "control.peers.connect",
            Method::ControlPeersDisconnect => "control.peers.disconnect",
            Method::ListRewardDistributors => "dig.listRewardDistributors",
            Method::GetRewardProverStatus => "dig.getRewardProverStatus",
            Method::GetRewardDistributor => "dig.getRewardDistributor",
            Method::ListRewardDistributorCommitments => "dig.listRewardDistributorCommitments",
            Method::GetPayeeRewardClaimStatus => "dig.getPayeeRewardClaimStatus",
            Method::RpcDiscover => "rpc.discover",
        }
    }

    /// Parse a wire name into a [`Method`], or `None` for an unknown method
    /// (the caller answers `-32601`).
    pub fn from_name(name: &str) -> Option<Method> {
        Method::ALL.iter().copied().find(|m| m.name() == name)
    }

    /// The method's PRIMARY access [`Tier`].
    ///
    /// Note: a `PublicRead` method may still be peer-reachable — see
    /// [`is_peer_reachable`](Method::is_peer_reachable). The tier is the
    /// method's canonical home, the allowlist is the security boundary.
    pub const fn tier(self) -> Tier {
        match self {
            Method::GetContent
            | Method::GetCapsule
            | Method::GetModule
            | Method::GetManifest
            | Method::GetMetadata
            | Method::ListCapsules
            | Method::GetProof
            | Method::GetProofStatus
            | Method::GetAnchoredRoot
            | Method::GetCollection
            | Method::ListCollectionItems
            | Method::Health
            | Method::Methods => Tier::PublicRead,

            Method::GetNetworkInfo
            | Method::GetPeers
            | Method::Announce
            | Method::GetAvailability
            | Method::ListInventory
            | Method::FetchRange
            | Method::GetModuleInfo
            | Method::FetchModuleRange => Tier::Peer,

            Method::Stage
            | Method::CacheGetConfig
            | Method::CacheSetCapBytes
            | Method::CacheClear
            | Method::CacheListCached
            | Method::CacheRemoveCached
            | Method::CacheFetchAndCache
            | Method::CacheStats
            | Method::ControlPeerStatus
            | Method::ControlSubscribe
            | Method::ControlUnsubscribe
            | Method::ControlListSubscriptions
            | Method::ControlPeersConnect
            | Method::ControlPeersDisconnect
            | Method::ListRewardDistributors
            | Method::GetRewardProverStatus
            | Method::GetRewardDistributor
            | Method::ListRewardDistributorCommitments
            | Method::GetPayeeRewardClaimStatus
            | Method::RpcDiscover => Tier::Control,
        }
    }

    /// Whether this method is reachable over the mTLS **peer** surface.
    ///
    /// This mirrors the canonical node's `is_peer_reachable_method` byte-for-byte
    /// (digstore `dig-node` `peer.rs`). It is an ALLOWLIST: adding a method here
    /// is a deliberate security decision — it exposes the method to any remote
    /// peer (the peer verifier authenticates a `peer_id`, it does NOT authorize).
    /// Management/mutation methods (`cache.*`, `control.*`, `dig.stage`) are
    /// NEVER peer-reachable.
    pub const fn is_peer_reachable(self) -> bool {
        matches!(
            self,
            Method::GetContent
                | Method::GetNetworkInfo
                | Method::GetPeers
                | Method::Announce
                | Method::GetAvailability
                | Method::ListInventory
                | Method::FetchRange
                | Method::GetModuleInfo
                | Method::FetchModuleRange
                | Method::GetAnchoredRoot
                | Method::GetCollection
                | Method::ListCollectionItems
        )
    }

    /// Whether this method answers on the **reward** surface — distributor,
    /// prover-loop, or payee claim-side state (dig-rewards-coin SPEC §2.3, §2.6,
    /// §7.4, §7.5, §12.5).
    ///
    /// Every method for which this is `true` MUST be `Tier::Control` and MUST
    /// NOT be peer-reachable; the guard that enforces that drives itself from
    /// here.
    ///
    /// # Why an exhaustive match and not a name filter
    ///
    /// The guard previously selected its subjects with
    /// `name().contains("Reward")`, which is convention-bound: a reward method
    /// named without that substring escapes the tier assertion silently, and
    /// nothing tells the author of that method that it has. This match is
    /// compiler-bound instead — a new variant fails to compile until someone
    /// classifies it, and the answer they must give is the one the guard needs.
    /// There is deliberately no `_` arm, for exactly that reason.
    pub const fn is_reward(self) -> bool {
        match self {
            Method::ListRewardDistributors
            | Method::GetRewardProverStatus
            | Method::GetRewardDistributor
            | Method::ListRewardDistributorCommitments
            | Method::GetPayeeRewardClaimStatus => true,
            Method::GetContent
            | Method::GetCapsule
            | Method::GetModule
            | Method::GetManifest
            | Method::GetMetadata
            | Method::ListCapsules
            | Method::GetProof
            | Method::GetProofStatus
            | Method::GetAnchoredRoot
            | Method::GetCollection
            | Method::ListCollectionItems
            | Method::Health
            | Method::Methods
            | Method::GetNetworkInfo
            | Method::GetPeers
            | Method::Announce
            | Method::GetAvailability
            | Method::ListInventory
            | Method::FetchRange
            | Method::GetModuleInfo
            | Method::FetchModuleRange
            | Method::Stage
            | Method::CacheGetConfig
            | Method::CacheSetCapBytes
            | Method::CacheClear
            | Method::CacheListCached
            | Method::CacheRemoveCached
            | Method::CacheFetchAndCache
            | Method::CacheStats
            | Method::ControlPeerStatus
            | Method::ControlSubscribe
            | Method::ControlUnsubscribe
            | Method::ControlListSubscriptions
            | Method::ControlPeersConnect
            | Method::ControlPeersDisconnect
            | Method::RpcDiscover => false,
        }
    }

    /// A one-line human summary (drives the OpenRPC method `summary`).
    pub const fn summary(self) -> &'static str {
        match self {
            Method::GetContent => "Read a verified window of a resource's ciphertext.",
            Method::GetCapsule => "Fetch the whole .dig module for (store, root).",
            Method::GetModule => "Alias of dig.getCapsule.",
            Method::GetManifest => "Fetch the public discovery manifest resource.",
            Method::GetMetadata => "Fetch the plaintext metadata manifest.",
            Method::ListCapsules => "List a store's confirmed capsules.",
            Method::GetProof => "Get the real inclusion proof + execution-proof status.",
            Method::GetProofStatus => "Poll a real execution-proof job by id.",
            Method::GetAnchoredRoot => "Resolve a store's chain-anchored tip root.",
            Method::GetCollection => "Get collection-level facts for NFT launcher ids.",
            Method::ListCollectionItems => "List resolved NFT collection items (paginated).",
            Method::Health => "Liveness and capability summary.",
            Method::Methods => "List the method names this node implements.",
            Method::GetNetworkInfo => "This node's peer-network posture.",
            Method::GetPeers => "The peers this node currently knows.",
            Method::Announce => "Accept a peer announcement (peer_id + addresses).",
            Method::GetAvailability => "Batch-check whether this node holds items.",
            Method::ListInventory => "Enumerate the stores / roots this node serves.",
            Method::FetchRange => "Fetch a single verified range frame of a resource.",
            Method::GetModuleInfo => {
                "Get the whole-.dig-module transfer descriptor (size + hashes) for (store, root)."
            }
            Method::FetchModuleRange => "Fetch a single range frame of the whole .dig module blob.",
            Method::Stage => "Compile a local folder into a capsule .dig in-process.",
            Method::CacheGetConfig => "Get the local-cache configuration.",
            Method::CacheSetCapBytes => "Set the local-cache size cap.",
            Method::CacheClear => "Clear the local cache.",
            Method::CacheListCached => "List the durable cached modules.",
            Method::CacheRemoveCached => "Remove one cached capsule.",
            Method::CacheFetchAndCache => "Fetch and cache one capsule.",
            Method::CacheStats => {
                "Cache telemetry: cap + usage, entry count + bytes, eviction + hit/miss counters."
            }
            Method::ControlPeerStatus => "Snapshot the node's peer network.",
            Method::ControlSubscribe => {
                "Subscribe the node to a store (persisted watch + gap-fill)."
            }
            Method::ControlUnsubscribe => "Unsubscribe the node from a store.",
            Method::ControlListSubscriptions => "List the node's persisted store subscriptions.",
            Method::ControlPeersConnect => "Dial a peer into the connected pool.",
            Method::ControlPeersDisconnect => "Drop a pooled peer by peer_id.",
            Method::ListRewardDistributors => {
                "List the reward distributors this node funds or has a mirror claim to."
            }
            Method::GetRewardProverStatus => {
                "Get the reward prover loop's status for one or every distributor."
            }
            Method::GetRewardDistributor => "Get one reward distributor's chain-derived state.",
            Method::ListRewardDistributorCommitments => {
                "List one reward distributor's per-epoch clawback commitment slots."
            }
            Method::GetPayeeRewardClaimStatus => {
                "Report this node's own payee-side reward claim posture."
            }
            Method::RpcDiscover => "Return the OpenRPC self-describe document.",
        }
    }

    /// The method names reachable over the peer surface, in catalogue order —
    /// the exact allowlist a server hands its peer responder.
    pub fn peer_reachable_names() -> Vec<&'static str> {
        Method::ALL
            .iter()
            .copied()
            .filter(|m| m.is_peer_reachable())
            .map(Method::name)
            .collect()
    }
}

impl std::fmt::Display for Method {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.name())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashSet;

    /// **Proves:** every method name round-trips through `from_name`.
    /// **Catches:** a name typo or a variant left out of `ALL`.
    #[test]
    fn names_round_trip() {
        for m in Method::ALL {
            assert_eq!(Method::from_name(m.name()), Some(*m), "{}", m.name());
        }
        assert!(Method::from_name("dig.nope").is_none());
    }

    /// **Proves:** all wire names are unique.
    /// **Catches:** two variants accidentally sharing a name.
    #[test]
    fn names_unique() {
        let names: HashSet<&str> = Method::ALL.iter().map(|m| m.name()).collect();
        assert_eq!(names.len(), Method::ALL.len());
    }

    /// **Proves:** the peer allowlist is EXACTLY the twelve methods the canonical
    /// node exposes over mTLS — and no `cache.*`/`control.*`/`dig.stage` leaks
    /// onto the peer surface.
    /// **Catches:** a drift from digstore `is_peer_reachable_method`, or a
    /// management method accidentally allowlisted (the audit #179 auth-bypass).
    #[test]
    fn peer_allowlist_matches_canonical() {
        let mut got = Method::peer_reachable_names();
        got.sort_unstable();
        let mut want = vec![
            "dig.getContent",
            "dig.getNetworkInfo",
            "dig.getPeers",
            "dig.announce",
            "dig.getAvailability",
            "dig.listInventory",
            "dig.fetchRange",
            "dig.getModuleInfo",
            "dig.fetchModuleRange",
            "dig.getAnchoredRoot",
            "dig.getCollection",
            "dig.listCollectionItems",
        ];
        want.sort_unstable();
        assert_eq!(got, want);

        // No management/mutation method is peer-reachable.
        for m in [
            Method::Stage,
            Method::CacheGetConfig,
            Method::CacheSetCapBytes,
            Method::CacheClear,
            Method::CacheListCached,
            Method::CacheRemoveCached,
            Method::CacheFetchAndCache,
            Method::CacheStats,
            Method::ControlPeerStatus,
            Method::ControlSubscribe,
            Method::ControlUnsubscribe,
            Method::ControlListSubscriptions,
            Method::ControlPeersConnect,
            Method::ControlPeersDisconnect,
            Method::RpcDiscover,
        ] {
            assert!(
                !m.is_peer_reachable(),
                "{} must NOT be peer-reachable",
                m.name()
            );
        }
    }

    /// **Proves:** the chain-anchored public reads are PublicRead yet ALSO
    /// peer-reachable (the design-brief tier decision §5).
    #[test]
    fn anchored_reads_public_but_peer_reachable() {
        for m in [
            Method::GetAnchoredRoot,
            Method::GetCollection,
            Method::ListCollectionItems,
        ] {
            assert_eq!(m.tier(), Tier::PublicRead);
            assert!(m.is_peer_reachable());
        }
    }

    /// **Proves:** the six live-node methods the crate previously lacked are
    /// present, Control-tiered, and NEVER peer-reachable (the #1075 completeness
    /// gap: the crate must catalogue every method the dig-node dispatch serves).
    /// **Catches:** a variant dropped from the catalogue, mis-tiered, or leaked
    /// onto the peer surface.
    #[test]
    fn completed_control_methods_present_and_gated() {
        let expected = [
            (Method::CacheStats, "cache.stats"),
            (Method::ControlSubscribe, "control.subscribe"),
            (Method::ControlUnsubscribe, "control.unsubscribe"),
            (
                Method::ControlListSubscriptions,
                "control.listSubscriptions",
            ),
            (Method::ControlPeersConnect, "control.peers.connect"),
            (Method::ControlPeersDisconnect, "control.peers.disconnect"),
        ];
        for (m, name) in expected {
            assert_eq!(m.name(), name);
            assert_eq!(Method::from_name(name), Some(m));
            assert!(Method::ALL.contains(&m), "{name} missing from ALL");
            assert_eq!(m.tier(), Tier::Control, "{name} must be Control");
            assert!(!m.is_peer_reachable(), "{name} must NOT be peer-reachable");
        }
    }

    /// **Proves:** the whole-module peer-pull methods (#1576) are present,
    /// Peer-tiered, and peer-reachable — the wire surface a peer uses to pull a
    /// complete `.dig` module and reshare it.
    /// **Catches:** either method dropped from the catalogue, mis-tiered, or left
    /// off the peer allowlist (which would make peer reshare unreachable).
    #[test]
    fn module_pull_methods_present_and_peer_reachable() {
        for (m, name) in [
            (Method::GetModuleInfo, "dig.getModuleInfo"),
            (Method::FetchModuleRange, "dig.fetchModuleRange"),
        ] {
            assert_eq!(m.name(), name);
            assert_eq!(Method::from_name(name), Some(m));
            assert!(Method::ALL.contains(&m), "{name} missing from ALL");
            assert_eq!(m.tier(), Tier::Peer, "{name} must be Peer");
            assert!(m.is_peer_reachable(), "{name} must be peer-reachable");
        }
    }

    /// **Proves:** `dig.getPayeeRewardClaimStatus` is in the catalogue under its
    /// exact wire name (dig_ecosystem#3269). The tier / peer-reachability half of
    /// its contract is proven by the catalogue-wide scan below, not restated here.
    #[test]
    fn payee_reward_claim_status_present_under_its_wire_name() {
        assert_eq!(
            Method::GetPayeeRewardClaimStatus.name(),
            "dig.getPayeeRewardClaimStatus"
        );
        assert_eq!(
            Method::from_name("dig.getPayeeRewardClaimStatus"),
            Some(Method::GetPayeeRewardClaimStatus)
        );
        assert!(Method::ALL.contains(&Method::GetPayeeRewardClaimStatus));
    }

    /// **Proves:** EVERY reward method in the catalogue is Control-tiered, not
    /// peer-reachable, and absent from the peer allowlist — dig-rewards-coin
    /// SPEC §2.3/§2.6/§7.4/§7.5, §12.5.
    ///
    /// **Catches:** a mis-tier that would expose distributor / prover-loop /
    /// claim-side internals to any remote peer, *including on a reward method
    /// added after this test was written*. An earlier form named its four
    /// members explicitly, so a fifth reward method passed it by simply not
    /// being on the list (#3261: a test over an enumeration can only check the
    /// enumeration it was given); the form after that filtered on
    /// `name().contains("Reward")`, which a reward method named without that
    /// substring escapes silently.
    ///
    /// [`Method::is_reward`] is an exhaustive match, so the selection is
    /// compiler-bound: a new variant fails to compile until it is classified,
    /// and classifying it as a reward method puts it under every assertion
    /// below. There is deliberately no expected count here — a count is a second
    /// thing to forget, and nothing tells it to move.
    #[test]
    fn every_reward_method_is_control_and_not_peer_reachable() {
        let reward_methods: Vec<Method> = Method::ALL
            .iter()
            .copied()
            .filter(|m| m.is_reward())
            .collect();

        // Non-vacuous: a catalogue that lost the reward methods, or an
        // `is_reward` that stopped claiming any, must fail here rather than
        // empty the set and pass silently.
        assert!(
            !reward_methods.is_empty(),
            "no method reported is_reward() -- either the catalogue lost them or \
             the classification was inverted"
        );

        let allowlist = Method::peer_reachable_names();
        for m in reward_methods {
            let name = m.name();
            assert_eq!(
                Method::from_name(name),
                Some(m),
                "{name} does not round-trip"
            );
            assert_eq!(m.tier(), Tier::Control, "{name} must be Control");
            assert!(!m.is_peer_reachable(), "{name} must NOT be peer-reachable");
            assert!(
                !allowlist.contains(&name),
                "{name} must not appear in the peer allowlist"
            );
        }
    }

    /// **Proves:** every method whose wire name says "Reward" is classified as
    /// one.
    /// **Catches:** the one wrong answer a machine can check. The exhaustive
    /// match in [`Method::is_reward`] forces an author to answer for a new
    /// variant, but it cannot tell a wrong answer from a right one; a reward
    /// method classified `false` would drop straight out of the tier guard, and
    /// its own name is the evidence against it.
    #[test]
    fn reward_named_methods_are_classified_as_reward() {
        for m in Method::ALL {
            if m.name().contains("Reward") {
                assert!(
                    m.is_reward(),
                    "{} is named a reward method but is_reward() says otherwise",
                    m.name()
                );
            }
        }
    }

    /// **Proves:** every Control method is NOT peer-reachable (the boundary
    /// invariant).
    #[test]
    fn control_tier_never_peer_reachable() {
        for m in Method::ALL {
            if m.tier() == Tier::Control {
                assert!(
                    !m.is_peer_reachable(),
                    "{} is Control but peer-reachable",
                    m.name()
                );
            }
        }
    }

    /// **Documents:** every [`Method`] variant is named by this exhaustive
    /// match, same as the test-module's other classifiers. This is no longer
    /// the completeness guard for `Method::ALL` — `method_catalogue!`
    /// generates `ALL` directly from the variant table, so a variant missing
    /// from `ALL` is unwritable, not merely red (dig_ecosystem#3317). This
    /// match is kept because it is cheap and documents that the test module
    /// sees the same catalogue as the rest of the crate; deliberately no `_`
    /// arm, so adding a variant is still a compile error here until an author
    /// names it.
    #[test]
    fn every_variant_is_named_by_an_exhaustive_match() {
        // The identity mapping is the point: `needless_match` would have us
        // collapse this into `m`, which erases the exhaustiveness check this
        // test exists to force. Keep every arm explicit.
        #[allow(clippy::needless_match)]
        fn name_it(m: Method) -> Method {
            match m {
                Method::GetContent => Method::GetContent,
                Method::GetCapsule => Method::GetCapsule,
                Method::GetModule => Method::GetModule,
                Method::GetManifest => Method::GetManifest,
                Method::GetMetadata => Method::GetMetadata,
                Method::ListCapsules => Method::ListCapsules,
                Method::GetProof => Method::GetProof,
                Method::GetProofStatus => Method::GetProofStatus,
                Method::GetAnchoredRoot => Method::GetAnchoredRoot,
                Method::GetCollection => Method::GetCollection,
                Method::ListCollectionItems => Method::ListCollectionItems,
                Method::Health => Method::Health,
                Method::Methods => Method::Methods,
                Method::GetNetworkInfo => Method::GetNetworkInfo,
                Method::GetPeers => Method::GetPeers,
                Method::Announce => Method::Announce,
                Method::GetAvailability => Method::GetAvailability,
                Method::ListInventory => Method::ListInventory,
                Method::FetchRange => Method::FetchRange,
                Method::GetModuleInfo => Method::GetModuleInfo,
                Method::FetchModuleRange => Method::FetchModuleRange,
                Method::Stage => Method::Stage,
                Method::CacheGetConfig => Method::CacheGetConfig,
                Method::CacheSetCapBytes => Method::CacheSetCapBytes,
                Method::CacheClear => Method::CacheClear,
                Method::CacheListCached => Method::CacheListCached,
                Method::CacheRemoveCached => Method::CacheRemoveCached,
                Method::CacheFetchAndCache => Method::CacheFetchAndCache,
                Method::CacheStats => Method::CacheStats,
                Method::ControlPeerStatus => Method::ControlPeerStatus,
                Method::ControlSubscribe => Method::ControlSubscribe,
                Method::ControlUnsubscribe => Method::ControlUnsubscribe,
                Method::ControlListSubscriptions => Method::ControlListSubscriptions,
                Method::ControlPeersConnect => Method::ControlPeersConnect,
                Method::ControlPeersDisconnect => Method::ControlPeersDisconnect,
                Method::ListRewardDistributors => Method::ListRewardDistributors,
                Method::GetRewardProverStatus => Method::GetRewardProverStatus,
                Method::GetRewardDistributor => Method::GetRewardDistributor,
                Method::ListRewardDistributorCommitments => {
                    Method::ListRewardDistributorCommitments
                }
                Method::GetPayeeRewardClaimStatus => Method::GetPayeeRewardClaimStatus,
                Method::RpcDiscover => Method::RpcDiscover,
            }
        }

        for m in Method::ALL {
            assert_eq!(name_it(*m), *m);
        }
    }

    /// The number of methods `method_catalogue!` should have generated into
    /// `Method::ALL`. Bump this when you add a method -- the macro already put
    /// it in `ALL`; this is the independent oracle that would catch a broken
    /// macro body (an entry silently dropped from the table), since
    /// completeness of `ALL` itself is now structural, not this test's job.
    const CATALOGUE_LEN: usize = 41;

    /// **Proves:** `Method::ALL` has exactly [`CATALOGUE_LEN`] entries.
    /// **Catches:** a broken `method_catalogue!` body that silently drops an
    /// entry from the generated `ALL` (the compiler can't catch that -- the
    /// macro would still expand to a valid, just shorter, array). This is
    /// NOT the completeness guard for #3317: `Method::ALL` can no longer omit
    /// a variant that exists in the enum, because `method_catalogue!`
    /// generates both from the same table -- there is no second list left to
    /// forget. This test only defends against the table itself losing an
    /// entry, and forces a visible, reviewable bump on every addition.
    #[test]
    fn all_len_is_the_catalogue_count() {
        assert_eq!(
            Method::ALL.len(),
            CATALOGUE_LEN,
            "Method::ALL has {} entries, expected {CATALOGUE_LEN} -- update CATALOGUE_LEN if a \
             method was deliberately added or removed, otherwise the macro table lost an entry",
            Method::ALL.len()
        );

        // No duplicates in ALL (unchanged from the prior form of this guard).
        let all_set: HashSet<Method> = Method::ALL.iter().copied().collect();
        assert_eq!(
            all_set.len(),
            Method::ALL.len(),
            "Method::ALL contains a duplicate variant"
        );
    }
}