dig_rpc_protocol/

types.rs

//! Request/response wire types for every DIG-node RPC method.
//!
//! Each type is `serde`-derived and models a method's params or result
//! field-for-field with the canonical implementation (the digstore `dig-node`
//! crate). Fields that appear only in one profile or only on the first window of
//! a paged stream are `Option` and doc-flagged.
//!
//! Hex-encoded identifiers (`store_id`, `root`, `retrieval_key`, `peer_id`) are
//! carried as `String` on the wire — lower-case 64-hex — because the interface
//! crate does no crypto and imposes no byte-array dependency. Callers validate
//! length/charset at their boundary.
//!
//! # Two content profiles, one chunk type
//!
//! [`ContentChunk`] models both the node profile (`dig.getContent` on the local
//! dig-node) and the network profile (`rpc.dig.net`). The network-profile-only
//! fields — [`total_length`](ContentChunk::total_length),
//! [`length`](ContentChunk::length), [`program_hash`](ContentChunk::program_hash),
//! [`offset`](ContentChunk::offset) — are `Option` so one type serves both
//! surfaces with no silent split.

use serde::{Deserialize, Serialize};

/// A lower-case 64-hex identifier on the wire (e.g. a `store_id`, `root`,
/// `retrieval_key`, or `peer_id`). A type alias for documentation; validation is
/// the boundary's job.
pub type HexId = String;

// ===========================================================================
// Shared value objects
// ===========================================================================

/// A peer's dialable network endpoint.
///
/// IPv6-first per the ecosystem networking rule: an address list orders
/// global-unicast IPv6 ahead of IPv4 fallback, and a wildcard bind
/// (`[::]`/`0.0.0.0`) is never advertised.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeerAddress {
    /// The host — an IPv6 or IPv4 literal (never a wildcard).
    pub host: String,
    /// The TCP port.
    pub port: u16,
    /// How the address was discovered: `direct`, `reflexive`, `mapped`, or
    /// `relay`.
    pub kind: String,
}

/// A content provider: a holder's stable `peer_id` plus its candidate addresses.
///
/// The address list is byte-compatible with [`dig.getPeers`](crate::method::Method::GetPeers)
/// and the DHT provider shape.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct Provider {
    /// The holder's stable `peer_id` = `SHA-256(TLS SPKI DER)`, 64-hex.
    pub peer_id: HexId,
    /// The holder's candidate addresses (IPv6-first).
    pub addresses: Vec<PeerAddress>,
}

/// The content item a redirect points at: `store_id` [+ `root` [+
/// `retrieval_key`]], each lower-case 64-hex — the exact item to re-request.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ContentRef {
    /// The store launcher id (always present).
    pub store_id: HexId,
    /// The generation root (present for capsule/resource granularity).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub root: Option<HexId>,
    /// The resource retrieval key (present for resource granularity).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub retrieval_key: Option<HexId>,
}

/// The `error.data.redirect` payload of a
/// [`ContentRedirect`](crate::error::ErrorCode::ContentRedirect) (`-32008`).
///
/// The node does not hold the content but located peers that do; the caller
/// re-requests against one of `providers`, echoing `redirect_depth` in its
/// params so the hop budget stays bounded (stop at `max_redirects`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RedirectInfo {
    /// The content the caller should re-request.
    pub content: ContentRef,
    /// The holders (peer_id + candidate addresses) to re-request against.
    pub providers: Vec<Provider>,
    /// The hop count the caller must echo on its re-request.
    pub redirect_depth: u64,
    /// The redirect budget — stop redirecting when `redirect_depth` reaches this.
    pub max_redirects: u64,
}

// ===========================================================================
// dig.getContent  (PUBLIC-READ, also peer-reachable)
// ===========================================================================

/// Params for [`dig.getContent`](crate::method::Method::GetContent) — a verified
/// resource-window read.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetContentParams {
    /// The CHIP-0035 singleton launcher id (64-hex).
    pub store_id: HexId,
    /// `SHA-256(urn)` — the only URN-derived value sent to a node (64-hex).
    pub retrieval_key: HexId,
    /// The generation root (64-hex). Empty / `"latest"` / absent ⇒ resolve the
    /// chain tip.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub root: Option<HexId>,
    /// The window start offset (default 0).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub offset: Option<u64>,
    /// Retrieval mode: `"speed"` (default) or `"privacy"` (onion — target).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub mode: Option<String>,
    /// The redirect budget already consumed (echoed from a `-32008` redirect).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub redirect_depth: Option<u64>,
}

/// One window of a resource's ciphertext — the chunk wire object.
///
/// Serves BOTH the node profile (`dig.getContent` on the local dig-node) and the
/// network profile (`rpc.dig.net`). Node-profile responses omit the
/// network-profile-only fields; the doc on each field says which profile
/// populates it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ContentChunk {
    /// This window's bytes, base64. Both profiles.
    pub ciphertext: String,
    /// The resolved generation root (64-hex). Both profiles.
    pub root: HexId,
    /// Whether this window ends the resource. Both profiles.
    pub complete: bool,
    /// The next offset; present iff not complete. Both profiles.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub next_offset: Option<u64>,
    /// Whole-resource merkle proof, base64. First window only (`offset == 0`).
    /// Both profiles.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub inclusion_proof: Option<String>,
    /// Per-chunk ciphertext lengths of the full resource. First window only;
    /// empty ⇒ single chunk. Both profiles.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub chunk_lens: Option<Vec<u64>>,
    /// Where the window was served from: `"local"` (this device's cache) or
    /// `"remote"` (freshly fetched). **Node profile only** — additive tag the
    /// in-process node sets; absent on the network profile.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub source: Option<String>,
    /// The full resource ciphertext length (pre-windowing). **Network profile
    /// only.**
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub total_length: Option<u64>,
    /// This window's byte length. **Network profile only** (the node profile's
    /// length is implicit in `ciphertext`).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub length: Option<u64>,
    /// The window start offset (echoed). **Network profile only.**
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub offset: Option<u64>,
    /// `SHA-256(.dig bytes)` — the on-chain program identity (64-hex).
    /// **Network profile only.**
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub program_hash: Option<HexId>,
}

// ===========================================================================
// dig.getAnchoredRoot  (PUBLIC-READ, also peer-reachable)
// ===========================================================================

/// Params for [`dig.getAnchoredRoot`](crate::method::Method::GetAnchoredRoot).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetAnchoredRootParams {
    /// The store launcher id (64-hex).
    pub store_id: HexId,
}

/// Result for [`dig.getAnchoredRoot`](crate::method::Method::GetAnchoredRoot) —
/// the store's current chain-anchored tip root.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AnchoredRoot {
    /// The store launcher id (echoed, 64-hex).
    pub store_id: HexId,
    /// The chain-anchored tip root (64-hex).
    pub root: HexId,
}

// ===========================================================================
// dig.getCollection / dig.listCollectionItems  (PUBLIC-READ, also peer)
// ===========================================================================

/// Params for [`dig.getCollection`](crate::method::Method::GetCollection).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetCollectionParams {
    /// The NFT launcher ids to resolve. Capped at 10,000 (over-cap ⇒ `-32602`).
    pub launcher_ids: Vec<HexId>,
    /// The optional collection creator DID (64-hex).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub did: Option<HexId>,
}

/// Result for [`dig.getCollection`](crate::method::Method::GetCollection) —
/// collection-level facts computed from DIG's own coinset data.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct Collection {
    /// The resolved creator DID (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub did: Option<HexId>,
    /// The DID declared by the caller / metadata (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub declared_did: Option<HexId>,
    /// The number of launcher ids requested.
    pub item_count: u64,
    /// How many resolved to live NFTs.
    pub resolved_count: u64,
    /// The uniform royalty in basis points, if resolvable.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub royalty_basis_points: Option<u64>,
}

/// Params for
/// [`dig.listCollectionItems`](crate::method::Method::ListCollectionItems).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ListCollectionItemsParams {
    /// The NFT launcher ids. Capped at 10,000 (over-cap ⇒ `-32602`).
    pub launcher_ids: Vec<HexId>,
    /// Page start (default 0).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub offset: Option<u64>,
    /// Page size (default 50, capped at 200).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub limit: Option<u64>,
}

/// CHIP-0007 NFT metadata for one collection item.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct NftMetadata {
    /// Edition ordinal, if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub edition_number: Option<u64>,
    /// Edition total, if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub edition_total: Option<u64>,
    /// Data URIs.
    #[serde(default)]
    pub data_uris: Vec<String>,
    /// `SHA-256` of the data (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub data_hash: Option<HexId>,
    /// Metadata URIs.
    #[serde(default)]
    pub metadata_uris: Vec<String>,
    /// `SHA-256` of the metadata document (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub metadata_hash: Option<HexId>,
    /// License URIs.
    #[serde(default)]
    pub license_uris: Vec<String>,
    /// `SHA-256` of the license (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub license_hash: Option<HexId>,
}

/// One resolved collection item — its current on-chain owner, royalty, and
/// CHIP-0007 metadata.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CollectionItem {
    /// The NFT launcher id (64-hex).
    pub launcher_id: HexId,
    /// The current coin id (64-hex).
    pub coin_id: HexId,
    /// The current owner DID (64-hex), if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub owner_did: Option<HexId>,
    /// The royalty puzzle hash (64-hex).
    pub royalty_puzzle_hash: HexId,
    /// The royalty in basis points.
    pub royalty_basis_points: u64,
    /// The current owner puzzle hash (64-hex).
    pub owner_puzzle_hash: HexId,
    /// The CHIP-0007 metadata, if resolvable.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub metadata: Option<NftMetadata>,
}

/// Result for
/// [`dig.listCollectionItems`](crate::method::Method::ListCollectionItems) — a
/// page of resolved items.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CollectionItemsPage {
    /// This page's items.
    pub items: Vec<CollectionItem>,
    /// The page start (echoed).
    pub offset: u64,
    /// The page size (echoed).
    pub limit: u64,
    /// The total item count across the whole (capped) launcher set.
    pub total: u64,
    /// The next page's offset, or `null` when exhausted.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub next_offset: Option<u64>,
}

// ===========================================================================
// dig.getNetworkInfo  (PEER)
// ===========================================================================

/// The node's relay reservation posture.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RelayStatus {
    /// The relay endpoint URL (e.g. `wss://relay.dig.net:443`).
    pub url: String,
    /// Whether a relay reservation is currently held.
    pub reserved: bool,
}

/// Result for [`dig.getNetworkInfo`](crate::method::Method::GetNetworkInfo) —
/// this node's own peer-network posture.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct NetworkInfo {
    /// This node's stable `peer_id` = `SHA-256(TLS SPKI DER)` (64-hex), or
    /// `null` when no identity is configured.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub peer_id: Option<HexId>,
    /// The DIG network id (e.g. `DIG_MAINNET`).
    pub network_id: String,
    /// The first advertised (dialable) candidate address, `host:port`.
    pub listen_addr: String,
    /// The STUN-discovered reflexive address, if known.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub reflexive_addr: Option<String>,
    /// All advertised candidate addresses (IPv6-first).
    pub candidate_addresses: Vec<String>,
    /// Reachability posture: `"direct"` or `"relayed"`.
    pub reachability: String,
    /// The relay reservation posture.
    pub relay: RelayStatus,
}

// ===========================================================================
// dig.getPeers  (PEER)
// ===========================================================================

/// Result for [`dig.getPeers`](crate::method::Method::GetPeers) — the peers this
/// node currently knows (peer exchange over RPC).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeersList {
    /// The known peers (peer_id + candidate addresses).
    pub peers: Vec<Provider>,
}

// ===========================================================================
// dig.announce  (PEER)
// ===========================================================================

/// Params for [`dig.announce`](crate::method::Method::Announce).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AnnounceParams {
    /// The announcing peer's `peer_id` (64-hex).
    pub peer_id: HexId,
    /// The announcing peer's candidate addresses.
    pub addresses: Vec<PeerAddress>,
}

/// Result for [`dig.announce`](crate::method::Method::Announce).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AnnounceAck {
    /// Whether the announcement was accepted.
    pub accepted: bool,
    /// How many peers this node now knows.
    pub known_peers: u64,
}

// ===========================================================================
// dig.getAvailability  (PEER)
// ===========================================================================

/// One availability query item. Granularity is inferred from which fields are
/// present: `store_id` only ⇒ which roots are held; `+root` ⇒ a capsule; `+root
/// +retrieval_key` ⇒ a resource.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AvailabilityQuery {
    /// The store launcher id (64-hex, required).
    pub store_id: HexId,
    /// The generation root (64-hex), for capsule/resource granularity.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub root: Option<HexId>,
    /// The resource retrieval key (64-hex), for resource granularity.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub retrieval_key: Option<HexId>,
}

/// Params for [`dig.getAvailability`](crate::method::Method::GetAvailability).
///
/// # Construction
///
/// Like [`FetchRangeParams`], this type is `#[non_exhaustive]`: build it with
/// [`new`](Self::new) plus the `with_*` setters rather than a struct literal, so a
/// future additive field is a PATCH for every consumer instead of a semver cascade.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct GetAvailabilityParams {
    /// The items to check. Capped at 512 per batch (past-cap items are dropped).
    pub items: Vec<AvailabilityQuery>,
    /// The hop budget already consumed by this ask. Absent means zero — read it
    /// through [`hops_consumed`](Self::hops_consumed), never directly.
    ///
    /// # What it means for an availability ask
    ///
    /// An availability answer is not only *this* node's holdings: on a miss it may
    /// name the holders it located, in
    /// [`AvailabilityAnswer::providers`](AvailabilityAnswer::providers) — the same
    /// enrichment a [`RedirectInfo`] carries. A responder that cannot answer from
    /// what it holds MAY ask its own peers, so one caller's question can walk
    /// several hops, and each hop is a node spending someone else's bandwidth.
    /// This field is what bounds that walk.
    ///
    /// It is the SAME budget, counted the SAME way, as
    /// [`RedirectInfo::redirect_depth`] and as the `redirect_depth` that
    /// [`GetContentParams`] and [`FetchRangeParams`] already echo: the number of
    /// hops ALREADY CONSUMED when this ask arrives, counting UP from zero — never a
    /// remaining allowance counting down. A responder that asks onward sends
    /// `hops_consumed() + 1` (saturating at the type maximum), and MUST NOT ask
    /// onward when that would reach the budget it advertises as
    /// [`RedirectInfo::max_redirects`].
    ///
    /// Absent reads as a fresh, unhopped ask, so a client written before this field
    /// existed is served unchanged.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub redirect_depth: Option<u64>,
    /// The wall-clock TIME this ask may still spend, in milliseconds. Absent means
    /// unbudgeted — read it through [`budget_ms`](Self::budget_ms), never directly.
    ///
    /// # Why this is its OWN field and not the hop budget
    ///
    /// [`redirect_depth`](Self::redirect_depth) counts hops UP from zero toward a
    /// ceiling; this counts milliseconds DOWN toward zero. The two move in opposite
    /// directions along different axes, so one integer cannot carry both, and folding
    /// them together would make "one more hop" and "more time" the same request.
    ///
    /// # The contract a relaying responder MUST honour
    ///
    /// A responder that asks its own peers onward MUST pass a value it has decremented
    /// by the time it has itself already spent, and it MUST NOT grant a child less time
    /// than the work it asks that child to do. Concretely: a parent that asks `n`
    /// children SEQUENTIALLY must divide the remaining budget between them, and a
    /// parent with less time left than one round trip needs MUST answer
    /// [`ContentMissInconclusive`](crate::error::ErrorCode::ContentMissInconclusive)
    /// rather than ask onward and then time out.
    ///
    /// This exists because the alternative is measurable: a FIXED per-ask bound with
    /// sequential asks and a fan-out greater than one guarantees the second hop times
    /// out, and a responder that reads that timeout as a miss reports a CONFIDENT
    /// not-found for content it never looked for.
    ///
    /// Absent reads as unbudgeted, so a client written before this field existed is
    /// served exactly as it was.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub budget_ms: Option<u64>,
    /// An opaque identity for this ask, for cross-path dedup. Absent means the caller
    /// opted out of dedup — read it through [`ask_id`](Self::ask_id).
    ///
    /// # What it is for
    ///
    /// A recursive ask walks a graph, not a tree. Two disjoint paths can arrive at the
    /// same responder, and without a shared identity that responder cannot tell a
    /// re-walk from a fresh question — so a diamond in the peer graph does not
    /// terminate. A responder that has already seen an `ask_id` MUST answer from what
    /// it already knows instead of asking onward again.
    ///
    /// # What it is NOT
    ///
    /// It is **not** the JSON-RPC `id`. That field correlates one request with one
    /// response on one connection; it is chosen per-connection, is commonly a small
    /// constant, and says nothing about whether two arrivals are the same ask. An
    /// implementation that reused the JSON-RPC `id` for dedup would either collide
    /// every unrelated ask together or dedup nothing at all.
    ///
    /// # Requirements
    ///
    /// 32 lowercase hex characters: **16 unpredictable random bytes**, freshly drawn
    /// by the ORIGINATOR and copied verbatim by every relaying hop. It MUST be
    /// unpredictable, because a value an attacker can guess lets that attacker
    /// pre-poison a responder dedup memo and suppress an ask that has not happened
    /// yet. A responder MUST NOT derive anything from its value beyond EQUALITY — it
    /// carries no structure, no origin, no timestamp and no ordering.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ask_id: Option<String>,
}

impl GetAvailabilityParams {
    /// An availability batch for `items`, asked at hop zero.
    pub fn new(items: Vec<AvailabilityQuery>) -> Self {
        GetAvailabilityParams {
            items,
            redirect_depth: None,
            budget_ms: None,
            ask_id: None,
        }
    }

    /// Echo the hop budget already consumed — from a `-32008` redirect, or from the
    /// ask this one is being made on behalf of. See
    /// [`redirect_depth`](Self::redirect_depth).
    pub fn with_redirect_depth(mut self, redirect_depth: u64) -> Self {
        self.redirect_depth = Some(redirect_depth);
        self
    }

    /// The hops already consumed by this ask.
    ///
    /// The single home for the "absent means zero" rule. A responder that reached for
    /// `redirect_depth.is_some()` instead would read every pre-0.8 client's ask as
    /// budget-free and forward it without bound — the amplification the budget exists
    /// to stop.
    pub fn hops_consumed(&self) -> u64 {
        self.redirect_depth.unwrap_or(0)
    }

    /// Set the remaining time budget for this ask. See [`budget_ms`](Self::budget_ms).
    pub fn with_budget_ms(mut self, budget_ms: u64) -> Self {
        self.budget_ms = Some(budget_ms);
        self
    }

    /// The time this ask may still spend, or `None` when the caller sent no budget.
    ///
    /// Deliberately NOT collapsed to a number, unlike
    /// [`hops_consumed`](Self::hops_consumed): there is no safe scalar default. Zero
    /// would refuse every older caller ask outright, and any positive default would
    /// silently impose one node idea of patience on another node question. A responder
    /// that receives `None` applies its OWN policy and passes on what it granted.
    pub fn budget_ms(&self) -> Option<u64> {
        self.budget_ms
    }

    /// Set the cross-path dedup identity. See [`ask_id`](Self::ask_id).
    pub fn with_ask_id(mut self, ask_id: impl Into<String>) -> Self {
        self.ask_id = Some(ask_id.into());
        self
    }

    /// The dedup identity, or `None` when the caller opted out of dedup.
    pub fn ask_id(&self) -> Option<&str> {
        self.ask_id.as_deref()
    }
}

/// One availability answer. Only the fields relevant to the query's granularity
/// are populated.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AvailabilityAnswer {
    /// Whether this node holds the queried item.
    pub available: bool,
    /// The roots held (store-granularity queries only).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub roots: Option<Vec<HexId>>,
    /// The full resource ciphertext length (resource-granularity only).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub total_length: Option<u64>,
    /// The chunk count (resource-granularity only).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub chunk_count: Option<u64>,
    /// Whether the whole item is held (root/resource-granularity only).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub complete: Option<bool>,
    /// Providers that hold the item — present on a miss when holders were
    /// located (enriched answer).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub providers: Option<Vec<Provider>>,
    /// Whether this responder actually ESTABLISHED that nobody holds the item.
    ///
    /// Only meaningful beside `available: false`; on a hit the item is held and there
    /// is nothing to establish.
    ///
    /// # Absent is a THIRD state, not `false`
    ///
    /// - `Some(true)` — the responder looked, reached everything it meant to reach,
    ///   and asserts absence. A client MAY stop searching.
    /// - `Some(false)` — the responder looked and could NOT establish absence: a hop
    ///   timed out, was unreachable, or refused uninformatively. A client MUST keep
    ///   looking. This is the in-band form of
    ///   [`ContentMissInconclusive`](crate::error::ErrorCode::ContentMissInconclusive),
    ///   for a batch where only SOME items were inconclusive and the call itself
    ///   therefore succeeded.
    /// - `None` — the responder predates this field and makes NO claim either way.
    ///   It is NOT `Some(false)`: `Some(false)` is a responder telling you its search
    ///   was incomplete, while `None` is a responder that cannot describe its search at
    ///   all. Conflating them lets an older server every miss be read as a positive
    ///   report of incompleteness; conflating it the other way (`unwrap_or(true)`)
    ///   turns an unknown into an assertion of absence. Read it through
    ///   [`absence_established_or_unknown`](AvailabilityAnswer::absence_established_or_unknown),
    ///   which keeps the three states distinct.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub absence_established: Option<bool>,
}

impl AvailabilityAnswer {
    /// Whether absence was established, as a THREE-state answer: `Some(true)`
    /// asserted, `Some(false)` explicitly not established, `None` unknown because the
    /// responder predates the field.
    ///
    /// A pass-through, and that is the point — it is the named home for the rule that
    /// there is no safe collapse to `bool`. A client that wants to stop searching MUST
    /// require `Some(true)`.
    pub fn absence_established_or_unknown(&self) -> Option<bool> {
        self.absence_established
    }
}

/// Result for [`dig.getAvailability`](crate::method::Method::GetAvailability) —
/// one answer per query item, in order.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct AvailabilityBatch {
    /// The per-item answers (index-aligned to the query items served).
    pub items: Vec<AvailabilityAnswer>,
}

// ===========================================================================
// dig.listInventory  (PEER)
// ===========================================================================

/// Params for [`dig.listInventory`](crate::method::Method::ListInventory).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ListInventoryParams {
    /// The store to list roots for (64-hex). Absent ⇒ list all stores served.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub store_id: Option<HexId>,
    /// The maximum number of entries to return.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub limit: Option<u64>,
}

/// Result for [`dig.listInventory`](crate::method::Method::ListInventory).
///
/// With a `store_id` the node returns the roots it holds for that store; without
/// one it returns the stores it serves. `#[serde(untagged)]` keeps the wire flat
/// (`{"roots": …}` or `{"stores": …}`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum Inventory {
    /// The roots held for a specific store.
    ForStore {
        /// The store launcher id (echoed, 64-hex).
        store_id: HexId,
        /// The roots this node holds for the store.
        roots: Vec<HexId>,
    },
    /// The stores this node serves (no `store_id` given).
    AllStores {
        /// The store launcher ids served.
        stores: Vec<HexId>,
    },
}

// ===========================================================================
// dig.fetchRange  (PEER)
// ===========================================================================

/// Params for [`dig.fetchRange`](crate::method::Method::FetchRange) — a single
/// range frame of a resource this node holds.
///
/// # Construction
///
/// Like [`RangeFrame`], this type is `#[non_exhaustive]`: build it with
/// [`resource`](Self::resource) plus the `with_*` setters rather than a struct
/// literal, so a future additive field is a PATCH for every consumer instead of a
/// semver cascade.
///
/// # Cross-repo contract
///
/// [`skip_layout`](Self::skip_layout) is byte-identical to
/// `dig_nat::mux::RangeRequest::skip_layout`, pinned in
/// `tests/nat_wire_mirror.rs`. The two enclosing types deliberately differ in every
/// other respect — dig-nat's `RangeRequest` is a length-prefixed stream preamble,
/// this is a JSON-RPC params object with a `redirect_depth` dig-nat has no notion
/// of — so the byte-identical contract here is the FIELD, not the object.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct FetchRangeParams {
    /// The store launcher id (64-hex, required).
    pub store_id: HexId,
    /// The generation root (64-hex, required for a resource fetch).
    pub root: HexId,
    /// `SHA-256(urn)` (64-hex, required for a resource fetch).
    pub retrieval_key: HexId,
    /// The range start (default 0).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub offset: Option<u64>,
    /// The range length in bytes (> 0; clamped to the window cap).
    pub length: u64,
    /// Whole-capsule mode (default false). Capsule range fetch is not yet
    /// served; a `true` here yields `-32004`.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub capsule: Option<bool>,
    /// The redirect budget already consumed (echoed from a `-32008` redirect).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub redirect_depth: Option<u64>,
    /// Suppress the resource-scaling layout metadata (`chunk_lens` +
    /// `inclusion_proof`) on this stream's frames, because the client already holds
    /// the commitment for this `root`.
    ///
    /// A client that has already read the layout once — a resumed download, a second
    /// range of the same resource, a parallel fetch from another holder — does not
    /// need it again, and re-sending it costs a whole paged prologue PER STREAM: a
    /// 1,048,576-chunk layout is roughly 7.3 MB, which a 64-way parallel plan would
    /// otherwise pay 64 times over. Suppressing it is the difference between a
    /// bounded and an unbounded cost on the read path.
    ///
    /// Absent or `false` preserves the pre-0.6.0 behaviour, so an older holder that
    /// ignores this field is never broken by it — it simply sends metadata the client
    /// discards. Read the rule through
    /// [`suppresses_layout`](Self::suppresses_layout) rather than re-deriving it.
    ///
    /// The fixed-size identity fields ([`root`](RangeFrame::root),
    /// [`total_length`](RangeFrame::total_length),
    /// [`chunk_count`](RangeFrame::chunk_count),
    /// [`chunk_index`](RangeFrame::chunk_index)) are NOT suppressed: they are what
    /// detects a wrong-generation holder on arrival, and a client that stopped
    /// receiving them would lose that check on exactly the streams it fetches most.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub skip_layout: Option<bool>,
}

impl FetchRangeParams {
    /// A range request for one content resource: `length` bytes of
    /// `retrieval_key`'s ciphertext at the generation `root`.
    pub fn resource(
        store_id: impl Into<HexId>,
        root: impl Into<HexId>,
        retrieval_key: impl Into<HexId>,
        length: u64,
    ) -> Self {
        FetchRangeParams {
            store_id: store_id.into(),
            root: root.into(),
            retrieval_key: retrieval_key.into(),
            offset: None,
            length,
            capsule: None,
            redirect_depth: None,
            skip_layout: None,
        }
    }

    /// Start the range at `offset` rather than at 0.
    pub fn with_offset(mut self, offset: u64) -> Self {
        self.offset = Some(offset);
        self
    }

    /// Request whole-capsule mode. Capsule range fetch is not yet served — a `true`
    /// here yields
    /// [`ResourceUnavailable`](crate::error::ErrorCode::ResourceUnavailable).
    pub fn with_capsule(mut self, capsule: bool) -> Self {
        self.capsule = Some(capsule);
        self
    }

    /// Echo the redirect budget already consumed, from a `-32008` redirect.
    pub fn with_redirect_depth(mut self, redirect_depth: u64) -> Self {
        self.redirect_depth = Some(redirect_depth);
        self
    }

    /// Ask the holder to omit the resource-scaling layout metadata, because this
    /// client already holds the commitment for this `root`. See
    /// [`skip_layout`](Self::skip_layout).
    pub fn with_skip_layout(mut self, skip_layout: bool) -> Self {
        self.skip_layout = Some(skip_layout);
        self
    }

    /// Whether this request suppresses the resource-scaling layout metadata.
    ///
    /// The single home for the "absent or `false` means SEND the layout" rule. A
    /// serve path that reached for `skip_layout.is_some()` instead would suppress the
    /// layout for a client that had explicitly asked for it — unrecoverable for that
    /// client, since the layout is a decrypt input it cannot obtain any other way on
    /// that stream.
    pub fn suppresses_layout(&self) -> bool {
        self.skip_layout.unwrap_or(false)
    }
}

/// One range frame of a resource: a byte window, plus the per-resource
/// verification metadata that makes the window independently checkable.
///
/// The metadata splits in two by whether it scales with the resource, and the
/// split decides which frames carry it:
///
/// - **The identity set — [`root`](Self::root),
///   [`total_length`](Self::total_length), [`chunk_count`](Self::chunk_count),
///   plus [`chunk_index`](Self::chunk_index) when the window begins on a chunk
///   boundary — rides EVERY frame.** It is fixed-size, so carrying it everywhere
///   costs a bounded number of bytes, and it is what lets a client fetching in
///   parallel from many holders reject a wrong-generation or wrong-layout source
///   the moment a frame arrives, rather than after paying for the whole resource
///   in bandwidth.
/// - **The resource-scaling set — [`chunk_lens`](Self::chunk_lens) and
///   [`inclusion_proof`](Self::inclusion_proof) — rides the first frame, or a
///   paged prologue, once per range stream.** Repeating it per frame would cost
///   proportionally to the resource against a frame budget with no slack; a layout
///   too large to state on one frame is paged instead, each page stamped with the
///   [`chunk_lens_offset`](Self::chunk_lens_offset) it begins at.
///
/// The window is exactly the span the caller requested — never widened.
///
/// # Construction
///
/// This type is [`#[non_exhaustive]`](https://doc.rust-lang.org/reference/attributes/type_system.html):
/// build it with [`data`](Self::data) and the `with_*` setters rather than a struct
/// literal. That is deliberate — the wire form grows as the protocol does, and
/// routing construction through named setters means a future additive field is a
/// PATCH release for every consumer instead of another semver cascade. It also
/// makes the two frame shapes different call chains rather than one call with a
/// pile of `None`s, so a continuation frame cannot accidentally claim a layout it
/// is not stating.
///
/// # Cross-repo contract
///
/// The wire form is **byte-identical** to `dig_nat::mux::RangeFrame`, the
/// streaming implementation of this frame (`SYSTEM.md` → "Canonical DIG-node RPC
/// interface"). Field names, encodings, and the population rule above are pinned
/// against dig-nat's actual output in `tests/nat_wire_mirror.rs`; a change to any
/// of them lands in both crates in the same unit of work or not at all.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct RangeFrame {
    /// The window start offset (echoed).
    pub offset: u64,
    /// This window's byte length.
    pub length: u64,
    /// This window's ciphertext, base64.
    pub bytes: String,
    /// Whether this frame ends the resource.
    pub complete: bool,
    /// The full resource ciphertext length. Part of the fixed-size **identity
    /// set**, so it rides EVERY frame.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub total_length: Option<u64>,
    /// Per-chunk ciphertext lengths of the full resource, in order — the layout a
    /// reader needs before it can decrypt (per-chunk AEAD needs the WHOLE array,
    /// and a reader rejects an array whose sum differs from
    /// [`total_length`](Self::total_length)).
    ///
    /// Resource-scaling, so it rides the first frame or a **paged prologue**, once
    /// per range stream — never repeated on continuation frames. When paged, this
    /// is one page of the array and
    /// [`chunk_lens_offset`](Self::chunk_lens_offset) states the entry it begins
    /// at.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub chunk_lens: Option<Vec<u64>>,
    /// This frame's first chunk index — the pre-existing alias of
    /// [`first_chunk_index`](Self::first_chunk_index), carrying the same value, and
    /// the name dig-nat emits.
    ///
    /// Part of the **identity set**: it rides every frame whose window begins on a
    /// chunk boundary, and is OMITTED (rather than guessed) on a mid-chunk window.
    /// Being fixed-size, it is settable on its own — see
    /// [`with_chunk_index`](Self::with_chunk_index) — precisely so a continuation
    /// frame can state it without dragging along the once-per-stream
    /// [`inclusion_proof`](Self::inclusion_proof).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub chunk_index: Option<u64>,
    /// Whole-resource merkle proof against [`root`](Self::root), base64, relayed
    /// verbatim.
    ///
    /// Resource-scaling, so it rides the first frame or the paged prologue, once
    /// per range stream. A holder MUST NOT repeat it per frame: it is bounded at
    /// 4,096 base64 bytes, which against the frame budget leaves no slack for the
    /// payload the frame exists to carry.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub inclusion_proof: Option<String>,
    /// The chain-anchored root (64-hex) this frame's resource verified against.
    /// Part of the fixed-size **identity set**, so it rides EVERY frame.
    ///
    /// NOT A TRUST ANCHOR BY ITSELF. The client resolves the resource's root from
    /// the URN (chain-anchored) and PINS it before fetching; a peer-declared value
    /// never replaces that pinned root. What this field provides is a
    /// generation-CONSISTENCY check: a frame declaring a root other than the pinned
    /// one is REJECTED and attributed to the offending peer (NC-9 fail-closed). So
    /// a declared root can only ever cause rejection — it can never move the pinned
    /// root, and never makes an unverified frame acceptable.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub root: Option<HexId>,
    /// **RESERVED — not currently derivable; a server MUST NOT emit it.**
    ///
    /// Per-chunk merkle inclusion proofs for the chunks a frame covers. No such
    /// proof exists in the current store format: the generation root's merkle
    /// leaves are per-RESOURCE (a leaf is the SHA-256 of a resource's WHOLE
    /// ciphertext), so a single chunk has no leaf to prove. A client MUST NOT
    /// require this field, and per-range verification instead uses the
    /// whole-resource [`inclusion_proof`](Self::inclusion_proof) together with the
    /// per-frame [`root`](Self::root)/[`chunk_lens`](Self::chunk_lens) metadata.
    ///
    /// Making it derivable requires a per-resource chunk-level commitment in the
    /// store format first (tracked as `dig_ecosystem#1601`). The field is kept in
    /// the wire type, unused, so populating it later is additive (§5.1); each entry
    /// would be an opaque base64 proof blob, since this pure level-00 wire type
    /// MUST NOT depend on the merkle primitive.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub range_proof: Option<Vec<String>>,
    /// The chunk index of the first chunk in this frame (0-based, into the
    /// resource's chunk sequence described by [`chunk_lens`](Self::chunk_lens)).
    ///
    /// Present only when the frame's window begins EXACTLY on a chunk boundary; a
    /// mid-chunk window omits it rather than assert an index the caller's own
    /// alignment check would contradict. The served window is exactly the requested
    /// span — a server MUST NOT widen a range to a chunk boundary — so a frame is
    /// chunk-aligned only when the caller asked for an aligned span.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub first_chunk_index: Option<u64>,
    /// The resource's TOTAL chunk count — how many entries the fully reassembled
    /// [`chunk_lens`](Self::chunk_lens) array has.
    ///
    /// Fixed-size, so it belongs to the **identity set** and rides EVERY frame.
    /// Together with [`root`](Self::root) and
    /// [`total_length`](Self::total_length) it is what lets a reader detect a
    /// wrong-generation or wrong-layout holder on the first frame it receives. It is
    /// also how a reader sizes the array it is paging in, and therefore how it knows
    /// a **paged prologue** is complete: the prologue ends when the reader holds
    /// `chunk_count` entries, which no single page can tell it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chunk_count: Option<u64>,
    /// The index into the resource's [`chunk_lens`](Self::chunk_lens) array at which
    /// THIS frame's page begins — how a **paged prologue** is located and
    /// reassembled.
    ///
    /// A resource whose layout exceeds the per-frame entry cap cannot state it on
    /// one frame, so the sender pages it: successive frames each carry up to that
    /// many entries, stamped with the offset they start at. A reader places each page
    /// at its offset and holds the whole array once it has
    /// [`chunk_count`](Self::chunk_count) entries.
    ///
    /// Absent means "this frame's `chunk_lens`, if any, begins at entry 0" — the
    /// single-frame layout, which is the shape every pre-0.6.0 producer emits. So an
    /// older frame decodes with exactly its original meaning (§5.1).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chunk_lens_offset: Option<u64>,
}

impl RangeFrame {
    /// A **data frame**: `length` bytes of base64 ciphertext at `offset`, carrying
    /// no metadata — the bare shape every continuation frame starts from.
    ///
    /// `length` is stated rather than derived because [`bytes`](Self::bytes) is
    /// already base64 on this type, and recovering the raw window length from it
    /// would need a base64 codec this pure level-00 wire crate deliberately does not
    /// depend on. A serve path passes the length it served.
    pub fn data(offset: u64, length: u64, bytes: impl Into<String>) -> Self {
        RangeFrame {
            offset,
            length,
            bytes: bytes.into(),
            complete: false,
            total_length: None,
            chunk_lens: None,
            chunk_index: None,
            inclusion_proof: None,
            root: None,
            range_proof: None,
            first_chunk_index: None,
            chunk_count: None,
            chunk_lens_offset: None,
        }
    }

    /// Mark this as the final frame of the range.
    pub fn with_complete(mut self, complete: bool) -> Self {
        self.complete = complete;
        self
    }

    /// The fixed-size **identity set** every frame of a range carries: the
    /// generation `root` (64-hex) the range is served from, the resource's
    /// ciphertext `total_length`, and its `chunk_count`.
    ///
    /// These three are what let a reader reject a wrong-generation or wrong-layout
    /// holder the moment a frame arrives — which the resource-scaling metadata never
    /// could, since it arrives once. Call this on every frame.
    pub fn with_identity(
        mut self,
        root: impl Into<HexId>,
        total_length: u64,
        chunk_count: u64,
    ) -> Self {
        self.root = Some(root.into());
        self.total_length = Some(total_length);
        self.chunk_count = Some(chunk_count);
        self
    }

    /// State [`chunk_index`](Self::chunk_index) — the chunk this frame's window
    /// begins on — for a chunk-aligned window.
    ///
    /// Separate from [`with_inclusion_proof`](Self::with_inclusion_proof) on purpose:
    /// the index is fixed-size identity metadata that rides every aligned frame,
    /// while the proof is once-per-stream, so binding them together would force a
    /// producer to either repeat a proof it MUST NOT repeat or bypass this API. Omit
    /// the call entirely for a mid-chunk window.
    pub fn with_chunk_index(mut self, chunk_index: u64) -> Self {
        self.chunk_index = Some(chunk_index);
        self
    }

    /// Additionally state [`first_chunk_index`](Self::first_chunk_index), this
    /// crate's v0.4.0 alias of [`chunk_index`](Self::chunk_index).
    ///
    /// Both names carry the same value. dig-nat emits only `chunk_index`, so
    /// [`with_chunk_index`](Self::with_chunk_index) alone is the interoperable
    /// choice; a producer serving readers that expect the newer name states both.
    pub fn with_first_chunk_index(mut self, first_chunk_index: u64) -> Self {
        self.first_chunk_index = Some(first_chunk_index);
        self
    }

    /// One page of the resource's `chunk_lens` array, beginning at entry
    /// `chunk_lens_offset`.
    ///
    /// Call it once with offset `0` for a layout that fits a single frame, or once
    /// per page of a **paged prologue**. A page is only ever useful as part of a
    /// complete set: `chunk_lens` is a decrypt input, and a reader needs all
    /// [`chunk_count`](Self::chunk_count) entries before it can decrypt anything.
    pub fn with_chunk_lens_page(mut self, chunk_lens_offset: u64, chunk_lens: Vec<u64>) -> Self {
        self.chunk_lens_offset = Some(chunk_lens_offset);
        self.chunk_lens = Some(chunk_lens);
        self
    }

    /// The whole-resource merkle inclusion proof against
    /// [`root`](Self::root) (base64, relayed verbatim).
    ///
    /// Resource-scaling: state it on the first frame or the prologue, once per range
    /// stream, never per frame.
    pub fn with_inclusion_proof(mut self, inclusion_proof: impl Into<String>) -> Self {
        self.inclusion_proof = Some(inclusion_proof.into());
        self
    }

    /// State the **RESERVED** [`range_proof`](Self::range_proof) field.
    ///
    /// A server MUST NOT emit it — no per-chunk proof is derivable from the current
    /// store format (see the field's own documentation). The setter exists so the
    /// shape stays constructible for the conformance vectors that pin it, and so no
    /// field of this `#[non_exhaustive]` type is unreachable; it is not a serve-path
    /// call.
    pub fn with_range_proof(mut self, range_proof: Vec<String>) -> Self {
        self.range_proof = Some(range_proof);
        self
    }
}

// ===========================================================================
// dig.getModuleInfo / dig.fetchModuleRange  (PEER — whole-module pull, #1576)
// ===========================================================================

/// Params for [`dig.getModuleInfo`](crate::method::Method::GetModuleInfo) — the
/// handshake a peer reads before range-pulling a whole `.dig` module for
/// `(store, root)`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetModuleInfoParams {
    /// The store launcher id (64-hex, required).
    pub store_id: HexId,
    /// The generation root whose `.dig` module is being pulled (64-hex, required).
    pub root: HexId,
}

/// Result for [`dig.getModuleInfo`](crate::method::Method::GetModuleInfo) — the
/// transfer descriptor of a whole `.dig` module.
///
/// The whole-module blob is content-addressed + immutable (the `.dig` container
/// is byte-identical by construction). [`module_hash`](Self::module_hash) is the
/// content id of the assembled blob; a puller verifies each pulled range against
/// [`chunk_hashes`](Self::chunk_hashes) (per-peer attribution on a multi-source
/// pull) and the fully-assembled blob against `module_hash`, THEN verifies the
/// assembled module against its chain-anchored root before admitting + resharing
/// (NC-9 verified-content-not-safe-content).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ModuleInfo {
    /// The total byte length of the whole `.dig` module blob.
    pub total_size: u64,
    /// The content id of the fully-assembled module blob (64-hex `SHA-256` of the
    /// module bytes). The puller checks the assembled blob against this.
    pub module_hash: HexId,
    /// Per-chunk content hashes (64-hex each) in ascending chunk order, covering
    /// the blob in [`total_size`](Self::total_size)-spanning fixed-size chunks
    /// (the trailing chunk may be short). A puller checks each pulled
    /// [`RangeFrame`] against the covering entries for per-source attribution on a
    /// multi-source pull (a tampered range fails closed before assembly).
    pub chunk_hashes: Vec<HexId>,
    /// Per-chunk byte lengths (in the same order as [`chunk_hashes`](Self::chunk_hashes)).
    /// MUST have the same length as `chunk_hashes` and MUST sum to `total_size`.
    /// A puller uses these to map a fetched byte range to the covering chunk hash(es).
    pub chunk_lens: Vec<u64>,
}

/// Params for [`dig.fetchModuleRange`](crate::method::Method::FetchModuleRange) —
/// a single range frame of the whole `.dig` module blob for `(store, root)`.
///
/// The response reuses [`RangeFrame`]: [`bytes`](RangeFrame::bytes) carries the
/// window of the module blob (base64), [`total_length`](RangeFrame::total_length)
/// echoes the whole-module size on the first frame, and
/// [`complete`](RangeFrame::complete) ends the stream.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct FetchModuleRangeParams {
    /// The store launcher id (64-hex, required).
    pub store_id: HexId,
    /// The generation root whose `.dig` module is being pulled (64-hex, required).
    pub root: HexId,
    /// The range start into the module blob (default 0).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub offset: Option<u64>,
    /// The range length in bytes (> 0; clamped to the window cap).
    pub length: u64,
}

// ===========================================================================
// dig.stage  (CONTROL — loopback / in-process only)
// ===========================================================================

/// Params for [`dig.stage`](crate::method::Method::Stage) — compile a local
/// folder into a capsule `.dig` module in-process.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct StageParams {
    /// The absolute path to the folder to compile.
    pub dir: String,
    /// The target store launcher id (64-hex). Absent ⇒ an ephemeral,
    /// content-derived id (a preview).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub store_id: Option<HexId>,
    /// The store salt (64-hex). Present ⇒ a private store.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub salt: Option<HexId>,
    /// Optional DIGHub-style manifest metadata to embed.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub metadata: Option<serde_json::Value>,
}

/// Result for [`dig.stage`](crate::method::Method::Stage) — the compiled capsule.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct StageResult {
    /// The canonical capsule identity, `storeId:rootHash`.
    pub capsule: String,
    /// The store launcher id (64-hex).
    pub store_id: HexId,
    /// The compiled generation root (64-hex).
    pub root: HexId,
    /// The filesystem path to the compiled `.dig` module.
    pub module_path: String,
    /// The module size in bytes.
    pub size: u64,
    /// The `chia://storeId:rootHash/` content address.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub content_address: Option<String>,
    /// The relative paths compiled into the capsule.
    #[serde(default)]
    pub files: Vec<String>,
    /// Whether this is an ephemeral preview (not advancing a real store).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub ephemeral: Option<bool>,
}

// ===========================================================================
// cache.*  (CONTROL — loopback / in-process only)
// ===========================================================================

/// Result for [`cache.getConfig`](crate::method::Method::CacheGetConfig).
///
/// The canonical field name for the cache path is `cache_dir` everywhere (the
/// shell's historical `dir` is unified onto this name).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CacheConfig {
    /// The on-disk cache size cap in bytes (floored at 64 MiB).
    pub cap_bytes: u64,
    /// The bytes currently used.
    pub used_bytes: u64,
    /// The effective resolved cache directory.
    pub cache_dir: String,
    /// Whether that directory is the canonical shared location (vs a
    /// process-private fallback).
    pub shared: bool,
}

/// Params for [`cache.setCapBytes`](crate::method::Method::CacheSetCapBytes).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct SetCapBytesParams {
    /// The requested cap in bytes (floored at 64 MiB by the node).
    pub cap_bytes: u64,
}

/// Result for [`cache.setCapBytes`](crate::method::Method::CacheSetCapBytes).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct SetCapBytesResult {
    /// The effective cap after flooring.
    pub cap_bytes: u64,
}

/// One durable cached-module entry.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CachedCapsule {
    /// The canonical capsule identity, `storeId:rootHash`.
    pub capsule: String,
    /// The store launcher id (64-hex).
    pub store_id: HexId,
    /// The generation root (64-hex).
    pub root: HexId,
    /// The module size in bytes.
    pub size_bytes: u64,
    /// When the module was last used (unix ms).
    pub last_used_unix_ms: u64,
}

/// Result for [`cache.listCached`](crate::method::Method::CacheListCached).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CachedList {
    /// The cached capsules.
    pub cached: Vec<CachedCapsule>,
}

/// Params for a capsule-keyed cache op
/// ([`cache.removeCached`](crate::method::Method::CacheRemoveCached),
/// [`cache.fetchAndCache`](crate::method::Method::CacheFetchAndCache)).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CapsuleKey {
    /// The store launcher id (64-hex).
    pub store_id: HexId,
    /// The generation root (64-hex).
    pub root: HexId,
}

/// Result for [`cache.removeCached`](crate::method::Method::CacheRemoveCached).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RemoveCachedResult {
    /// Whether an entry was removed.
    pub removed: bool,
}

/// Result for [`cache.fetchAndCache`](crate::method::Method::CacheFetchAndCache).
///
/// A failed fetch is reported in-band (`status = "failed"` + `message`) so the
/// caller can show it without treating it as a transport error.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct FetchAndCacheResult {
    /// `"cached"`, `"already_cached"`, or `"failed"`.
    pub status: String,
    /// The fetched module size in bytes (on success).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub size_bytes: Option<u64>,
    /// The served generation root (64-hex, on success).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub served_root: Option<HexId>,
    /// The failure message (on `status = "failed"`).
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub message: Option<String>,
}

// ===========================================================================
// control.peerStatus  (CONTROL — loopback / in-process only)
// ===========================================================================

/// Result for [`control.peerStatus`](crate::method::Method::ControlPeerStatus) —
/// a snapshot of the node's L7 peer network. Always safe to call; reports
/// `running: false` on the FFI path.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeerStatusSnapshot {
    /// Whether a peer network is currently active.
    pub running: bool,
    /// This node's `peer_id` (64-hex), if a peer network is running.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub peer_id: Option<HexId>,
    /// The DIG network id.
    pub network_id: String,
    /// The relay reservation posture.
    pub relay: RelayStatus,
    /// The number of currently connected peers.
    pub connected_peers: u64,
    /// The last peer-network error, if any.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub last_error: Option<String>,
}

// ===========================================================================
// cache.stats  (CONTROL — loopback / in-process only)
// ===========================================================================

/// The decoded-content cache hit/miss counters carried in
/// [`CacheStats`](CacheStats::content_cache).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ContentCacheCounters {
    /// Session decoded-content cache hits.
    pub hits: u64,
    /// Session decoded-content cache misses.
    pub misses: u64,
}

/// Result for [`cache.stats`](crate::method::Method::CacheStats) — cache
/// telemetry beside [`cache.getConfig`](crate::method::Method::CacheGetConfig):
/// the reserved cap + live usage, the cached-capsule count + total on-disk
/// bytes, and the session eviction + content-cache counters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct CacheStats {
    /// The on-disk cache size cap in bytes.
    pub cap_bytes: u64,
    /// The bytes currently used on disk.
    pub used_bytes: u64,
    /// The number of durable cached capsules.
    pub entry_count: u64,
    /// The total on-disk bytes across the cached capsules.
    pub total_bytes: u64,
    /// Capsules evicted this session.
    pub evicted_count: u64,
    /// Bytes evicted this session.
    pub evicted_bytes: u64,
    /// The decoded-content cache hit/miss counters.
    pub content_cache: ContentCacheCounters,
}

// ===========================================================================
// control.subscribe / control.unsubscribe / control.listSubscriptions
// (CONTROL — loopback / in-process only)
// ===========================================================================

/// Params for [`control.subscribe`](crate::method::Method::ControlSubscribe) and
/// [`control.unsubscribe`](crate::method::Method::ControlUnsubscribe).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct SubscribeParams {
    /// The store launcher id to (un)subscribe (64-hex).
    pub store_id: HexId,
}

/// Result for [`control.subscribe`](crate::method::Method::ControlSubscribe).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct SubscribeResult {
    /// Always `true` — the store is subscribed after this call.
    pub subscribed: bool,
    /// Whether this call ADDED the subscription (`false` ⇒ already subscribed).
    pub added: bool,
    /// The canonical persisted store id (trimmed + lower-cased, 64-hex).
    pub store_id: HexId,
}

/// Result for [`control.unsubscribe`](crate::method::Method::ControlUnsubscribe).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct UnsubscribeResult {
    /// Always `false` — the store is not subscribed after this call.
    pub subscribed: bool,
    /// Whether this call REMOVED a subscription (`false` ⇒ was not subscribed).
    pub removed: bool,
    /// The canonical persisted store id (trimmed + lower-cased, 64-hex).
    pub store_id: HexId,
}

/// Result for
/// [`control.listSubscriptions`](crate::method::Method::ControlListSubscriptions).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct SubscriptionsList {
    /// The persisted subscribed store ids (64-hex each).
    pub subscriptions: Vec<HexId>,
    /// The subscription count (`subscriptions.len()`).
    pub count: u64,
}

// ===========================================================================
// control.peers.connect / control.peers.disconnect
// (CONTROL — loopback / in-process only)
// ===========================================================================

/// Params for [`control.peers.connect`](crate::method::Method::ControlPeersConnect)
/// and [`control.peers.disconnect`](crate::method::Method::ControlPeersDisconnect).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeerConnectParams {
    /// The peer to dial/drop — a dialable address, or a known peer's `peer_id`
    /// (64-hex) to resolve an already-connected peer.
    pub peer: String,
}

/// Result for
/// [`control.peers.connect`](crate::method::Method::ControlPeersConnect).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeerConnectResult {
    /// Always `true` on success — the peer is a counted, connected pool member.
    pub connected: bool,
    /// The connected peer's stable `peer_id` (64-hex).
    pub peer_id: HexId,
}

/// Result for
/// [`control.peers.disconnect`](crate::method::Method::ControlPeersDisconnect).
///
/// Idempotent: disconnecting a peer that is not connected succeeds as a no-op.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PeerDisconnectResult {
    /// Always `true` — the peer is not in the pool after this call.
    pub disconnected: bool,
    /// The dropped peer's `peer_id` (trimmed + lower-cased, 64-hex).
    pub peer_id: HexId,
}

// ===========================================================================
// dig.listRewardDistributors / dig.getRewardProverStatus / dig.getRewardDistributor
// (CONTROL — loopback / in-process only; dig-rewards-coin SPEC.md §2.3 / §2.6)
// ===========================================================================

/// The always-on reward prover loop's state — SPEC §2.3, the closed set.
///
/// `#[non_exhaustive]`-equivalent by convention rather than attribute (the SPEC
/// pins this to an exact nine-member set; a variant needs a SPEC amendment, not
/// a semver-additive appendix). Deserialization is fail-closed: no
/// `#[serde(other)]` catch-all and no `Default` impl, so an unknown wire string
/// (a newer node, a typo) is a hard parse error rather than a silently-coerced
/// state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum ProverState {
    /// No distributor assigned; the loop is parked.
    Idle,
    /// A cycle is in progress.
    Running,
    /// The local capsule/store copy this cycle needs is missing.
    LocalCopyMissing,
    /// The chain source (full node / peer) is unreachable this cycle.
    ChainSourceUnavailable,
    /// The distributor is unfunded — no reserve to pay a cycle out of.
    Unfunded,
    /// The fee budget for entry-set writes is exhausted for this cycle.
    FeeBudgetExhausted,
    /// The entry set is at capacity; no further entries can be added.
    EntrySetFull,
    /// Paused by an operator action.
    Paused,
    /// Stopped; the loop will not run again without an explicit restart.
    Stopped,
}

/// The reward prover loop's running counters — SPEC §2.3.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ProverCounters {
    /// Distinct mirrors observed across all cycles.
    pub mirrors_seen: u64,
    /// Ranged capsule challenges issued.
    pub challenges_issued: u64,
    /// Challenges that passed verification.
    pub challenges_passed: u64,
    /// Challenges that failed verification.
    pub challenges_failed: u64,
    /// Entry-set entries added.
    pub entries_added: u64,
    /// Entry-set entries removed.
    pub entries_removed: u64,
    /// The current entry-set size.
    pub entry_count: u64,
    /// The distributor's reserve, in base units.
    pub reserve_base_units: u64,
    /// Total paid out over the loop's lifetime, in base units.
    pub total_paid_out_base_units: u64,
}

/// One distributor's prover-loop status — SPEC §2.3 / §2.4.
///
/// # No health boolean, no pre-computed staleness
///
/// This type carries no `healthy`/`ok`/`up`/`running`/`stale` field and no
/// `seconds_since_last_run`. SPEC §2.4: a wedged loop cannot report its own
/// wedging — a boolean the writer sets on every successful cycle reads `true`
/// forever after exactly the failure it exists to reveal, because the write
/// that would flip it never runs. The reader derives staleness itself from
/// [`last_cycle_completed_at`](Self::last_cycle_completed_at) /
/// [`next_cycle_due_at`](Self::next_cycle_due_at) against
/// [`observed_at`](Self::observed_at) and its own clock. Contrast
/// [`GetRewardDistributorResult::entry_set_stale`], which IS a boolean — it is
/// permitted there because it is computed from the singleton's on-chain spend
/// history by the responder at read time, not self-reported by the writer this
/// type describes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RewardProverStatus {
    /// The distributor singleton's launcher id (64-hex).
    pub launcher_id: HexId,
    /// The backing store's launcher id (64-hex).
    pub store_id: HexId,
    /// The store's current generation root (64-hex).
    pub root: HexId,
    /// The loop's current state.
    pub prover_state: ProverState,
    /// Unix seconds the loop entered `prover_state`.
    pub prover_state_since: u64,
    /// Unix seconds the current/most recent cycle started, if any has run.
    pub last_cycle_started_at: Option<u64>,
    /// Unix seconds the most recent cycle completed, if any has completed.
    pub last_cycle_completed_at: Option<u64>,
    /// Unix seconds the next cycle is scheduled, if the loop is scheduling one.
    pub next_cycle_due_at: Option<u64>,
    /// Unix seconds of the most recent entry-set write, if any.
    pub last_entry_write_at: Option<u64>,
    /// Consecutive cycle failures (resets to 0 on a completed cycle).
    pub consecutive_cycle_failures: u32,
    /// Entry writes queued but not yet committed.
    pub pending_entry_writes: u32,
    /// Unix seconds this status was assembled (the reader's staleness anchor).
    pub observed_at: u64,
    /// The loop's running counters.
    pub counters: ProverCounters,
}

/// Params for
/// [`dig.getRewardProverStatus`](crate::method::Method::GetRewardProverStatus).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetRewardProverStatusParams {
    /// Restrict to one distributor's launcher id (64-hex). Absent ⇒ every
    /// distributor this node runs a prover loop for.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub launcher_id: Option<HexId>,
}

/// Result for
/// [`dig.getRewardProverStatus`](crate::method::Method::GetRewardProverStatus).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetRewardProverStatusResult {
    /// One entry per prover loop this node runs, in no particular order — or
    /// the statement that the prover registry was never consulted.
    ///
    /// This is a [`Half`] for the same reason as
    /// [`ListRewardDistributorsResult`]'s two halves: a bare empty vector cannot
    /// tell an operator "this node runs no prover loops" apart from "I could not
    /// read the registry", and on a reward surface the second reads as the first
    /// while meaning the opposite. It describes the responder's own consultation
    /// of its prover registry, never a chain fact about any one distributor.
    pub statuses: Half<RewardProverStatus>,
}

/// A minimal distributor reference — SPEC §2.6.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RewardDistributorRef {
    /// The distributor singleton's launcher id (64-hex).
    pub launcher_id: HexId,
    /// The backing store's launcher id (64-hex).
    pub store_id: HexId,
    /// The store's current generation root (64-hex).
    pub root: HexId,
}

/// One collection a responder either consulted — and can therefore answer for —
/// or did not: dig-rewards-coin SPEC §12.5 clause 6.
///
/// # Why the items live INSIDE the variant
///
/// Clause 6: "the absence MUST be surfaced, not swallowed", and it "MUST be
/// dated by an `observed_at` and MUST NOT be presented as a bare zero". A bare
/// `claimable: []` cannot tell an operator apart "I looked and I hold no mirror
/// claims" from "nothing looked" — a funder-only responder emitting the empty
/// vector reads as the former while meaning the latter.
///
/// An observation carried *beside* its collection would leave
/// `{"outcome": "not_consulted", "items": [seven things]}` expressible, forbidden
/// only by prose. Folding the items into
/// [`Consulted`](Self::Consulted) makes that contradiction unconstructible in
/// Rust and unparseable on the wire: the arm that says nothing looked has no
/// field to put items in, and the arm that carries items has already said it
/// looked. A partially consulted half, if this crate ever needs one, is a third
/// arm rather than a new convention layered over the same two fields.
///
/// # What it deliberately cannot say
///
/// It describes the **responder's own consultation of the collection**, never a
/// chain fact about any one member. Clause 7 forbids a consumer reconstructing
/// "never admitted" from "evicted after settlement", and there is no arm, reason
/// code or per-member record here that could carry that split: after a
/// `Consulted` read, a distributor the peer was never admitted to and one it was
/// evicted from are both simply absent from `items`, exactly as before.
///
/// This does **not** discharge clause 6's *per-member* dated absence, which
/// needs a field this wire does not yet carry. What it closes is the
/// per-collection consultation record.
///
/// # Relation to `absence_established`
///
/// [`AvailabilityAnswer::absence_established`] is this crate's earlier, weaker
/// expression of the same idea: a marker *beside* the data, so "absence not
/// established, and here are seven items" stays representable and is forbidden
/// only by prose. `Half` is the intended direction for new shapes.
/// `AvailabilityAnswer` keeps its form because it has shipped consumers; it is
/// not a second pattern to copy.
///
/// # Fail-closed
///
/// Matching [`ProverState`]: internally tagged on `outcome`, no
/// `#[serde(other)]`, no `Default`, no `skip_serializing_if`, and `observed_at`
/// required in **every** arm. An unknown or missing outcome, or a missing date,
/// is a hard parse error rather than a silently coerced "consulted".
///
/// ```
/// use dig_rpc_protocol::types::Half;
///
/// let looked: Half<u32> = Half::Consulted { observed_at: 1_700, items: vec![] };
/// let did_not: Half<u32> = Half::NotConsulted { observed_at: 1_700 };
/// assert_eq!(looked.items(), Some(&[][..]));
/// assert_eq!(did_not.items(), None);
/// assert_eq!(did_not.observed_at(), 1_700);
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "outcome", rename_all = "snake_case", deny_unknown_fields)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum Half<T> {
    /// The collection WAS consulted, and `items` is its complete answer as of
    /// `observed_at` (Unix seconds). An empty `items` here means "none", and the
    /// reader derives staleness itself from `observed_at`.
    Consulted {
        /// Unix seconds the collection was read.
        observed_at: u64,
        /// The complete answer as of `observed_at`; empty means "none".
        items: Vec<T>,
    },
    /// The collection was NOT consulted as of `observed_at` (Unix seconds):
    /// nothing looked, so there is no answer here to read as "none".
    NotConsulted {
        /// Unix seconds this answer was assembled without consulting the
        /// collection.
        observed_at: u64,
    },
}

impl<T> Half<T> {
    /// The Unix seconds this half was observed — present in both arms, so a
    /// reader always has a staleness anchor.
    pub fn observed_at(&self) -> u64 {
        match self {
            Half::Consulted { observed_at, .. } | Half::NotConsulted { observed_at } => {
                *observed_at
            }
        }
    }

    /// The consulted answer, or `None` when nothing looked.
    ///
    /// `Some(&[])` means "consulted, and there are none"; `None` means "not
    /// consulted" — the distinction a bare `Vec` cannot make.
    pub fn items(&self) -> Option<&[T]> {
        match self {
            Half::Consulted { items, .. } => Some(items),
            Half::NotConsulted { .. } => None,
        }
    }
}

/// Result for
/// [`dig.listRewardDistributors`](crate::method::Method::ListRewardDistributors)
/// — SPEC §2.6: "the distributors this node funds, and the distributors this
/// node has a claim to as a mirror".
///
/// # No `Default`, by design
///
/// `Default` is not derived here and MUST NOT be re-added. A default could only
/// be the empty, consulted-looking answer — the exact ambiguity [`Half`] exists
/// to remove (SPEC §12.5 clause 6). Every producer must state, per half, whether
/// it consulted that half.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ListRewardDistributorsResult {
    /// Distributors this node funds (the reserve is this node's), or the
    /// statement that the funded half was never consulted.
    ///
    /// A responder whose funded set is unconfigured, unreadable, or failed to
    /// read must say so here rather than emit an empty list, which would read as
    /// "this node funds nothing" — a claim about the operator's own money.
    pub funded: Half<RewardDistributorRef>,
    /// Distributors this node has a claim to as a mirror but does not fund, or
    /// the statement that the claimable half was never consulted.
    pub claimable: Half<RewardDistributorRef>,
}

/// Params for
/// [`dig.getRewardDistributor`](crate::method::Method::GetRewardDistributor).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetRewardDistributorParams {
    /// The distributor singleton's launcher id (64-hex, required).
    pub launcher_id: HexId,
}

/// Result for
/// [`dig.getRewardDistributor`](crate::method::Method::GetRewardDistributor) —
/// SPEC §2.6, third method: chain-derived distributor state only, never the
/// local prover loop's own state (see [`RewardProverStatus`] for that).
///
/// # `entry_set_stale` lives HERE, never on `RewardProverStatus`
///
/// This is the one boolean in the reward-distributor surface, and it belongs
/// here specifically: per SPEC §12.4 it is computed by the responder from the
/// distributor singleton's on-chain spend history at read time, not
/// self-reported by a possibly-wedged writer. Copying it onto
/// [`RewardProverStatus`] would reintroduce exactly the self-reported-health
/// failure that type's doc comment forbids — see that type for the full
/// argument.
///
/// # The chain-view anchor (`chain_peak_height` / `chain_peak_timestamp`) — SPEC §4.5
///
/// `observed_at` dates when THIS REPLY was assembled — a wall clock, and
/// nothing else. `entry_set_stale` above is computed on a different clock
/// entirely: the distributor singleton's on-chain peak. A stalled chain
/// source freezes that peak while the wall clock keeps advancing, which
/// freezes `entry_set_stale` at `false` under a freshly stamped
/// `observed_at` — the optimistic-staleness defect this field pair exists to
/// close (dig_ecosystem#3262). `chain_peak_height` and `chain_peak_timestamp`
/// expose the clock `entry_set_stale` was actually computed against, so a
/// reader can check the two are self-consistent:
///
/// ```text
/// entry_set_stale == (reserve_base_units > 0
///     && chain_peak_timestamp - last_entry_write_at.unwrap_or(0) >= 172_800)
/// ```
///
/// **What this check is, and is not.** Every value on the right-hand side —
/// `chain_peak_timestamp` included — comes from the SAME response and the
/// SAME responder as `entry_set_stale` itself. Re-deriving the formula from
/// the responder's own numbers catches an INTERNALLY INCONSISTENT responder
/// only; it is not evidence against a lying, wedged, or compromised one,
/// which can report any self-consistent triple it likes and pass this check
/// every time. What the anchor genuinely fixes is narrower, and real: an
/// HONEST but chain-stalled responder can no longer freeze `entry_set_stale`
/// at `false` under a freshly stamped `observed_at`, because its own stalled
/// chain clock now travels on the wire beside it — the defect
/// dig_ecosystem#3262 was filed for, and it is closed. Real protection
/// against a dishonest responder requires comparing `chain_peak_height`
/// against a chain view the consumer obtained INDEPENDENTLY of this
/// response — see [`Self::chain_peak_height`]. SPEC §4.5.
///
/// Both fields are **required**, never `Option`, never `0`. A responder that
/// cannot obtain the chain peak (dig-rewards-coin's `read_distributor`
/// refuses without one) MUST answer a JSON-RPC error, not a result with a
/// missing or zeroed anchor — there is no result arm for "I could not look".
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct GetRewardDistributorResult {
    /// The distributor singleton's launcher id (64-hex).
    pub launcher_id: HexId,
    /// The backing store's launcher id (64-hex).
    pub store_id: HexId,
    /// The store's current generation root (64-hex).
    pub root: HexId,
    /// The payout epoch length, in seconds.
    pub epoch_seconds: u64,
    /// Unix seconds the first epoch started.
    pub first_epoch_start: u64,
    /// The reserve threshold, in base units, that triggers a payout.
    pub payout_threshold: u64,
    /// The distributor's fee, in basis points.
    pub fee_bps: u16,
    /// The share of a clawed-back commitment the committer recovers, in basis
    /// points — SPEC §7.5. `withdrawal_share_bps = 9000` means a clawback
    /// returns 90% of the committed value; the remaining 10% is forfeited to
    /// the reserve as a deterrent against the funder (SPEC §7.5 clause 1: it
    /// is priced correctly and is **not** compensation to induced mirrors).
    /// Curried at launch and immutable, same as [`Self::fee_bps`] beside it.
    pub withdrawal_share_bps: u16,
    /// The current reserve, in base units.
    pub reserve_base_units: u64,
    /// The current entry-set size.
    pub entry_count: u64,
    /// The current epoch index (`0`-based from `first_epoch_start`).
    pub current_distributor_epoch: u64,
    /// Unix seconds of the most recent entry-set write on chain, if any.
    /// `None` together with a non-zero `reserve_base_units` **implies
    /// stale**: an entry set that has never been written is maximally
    /// stale, not unknown, and a consumer MUST NOT render it as blank or
    /// "unknown" (SPEC §2.4 cl. 1 — silence is not an acceptable
    /// representation of "not distributing").
    pub last_entry_write_at: Option<u64>,
    /// `true` when the entry set has not changed in
    /// `STALE_ENTRY_SET_SECONDS = 172_800` (48 h) **while the reserve is
    /// non-zero** — SPEC §12.4. A drained distributor with a frozen entry set
    /// is not stale, it is [`Unfunded`](crate::types::ProverState::Unfunded);
    /// the non-zero-reserve conjunct exists to keep the two states distinct.
    /// The responder computes this at read time from the singleton's own
    /// on-chain spend history — it is not self-reported, so a wedged prover
    /// cannot fake it. See the type doc for why this boolean is safe here and
    /// forbidden on [`RewardProverStatus`].
    pub entry_set_stale: bool,
    /// Unix seconds this result was assembled — a WALL clock. Says nothing
    /// about chain freshness; read `chain_peak_timestamp` for that (see the
    /// type doc's "chain-view anchor" section).
    pub observed_at: u64,
    /// The distributor singleton's chain peak height at read time
    /// (`ChainObservation::peak_height`, widened losslessly from `u32`).
    /// Required — a responder with no chain peak in hand errors instead of
    /// answering. This is the field that carries REAL protection against a
    /// dishonest responder: compare it against a chain view the consumer
    /// obtained independently, not against anything else in this response.
    /// See the type doc's trust-boundary section. SPEC §4.5.
    pub chain_peak_height: u64,
    /// `block_timestamp(chain_peak_height)` — the CHAIN clock, never the wall
    /// clock, and the exact clock [`Self::entry_set_stale`] is computed
    /// against. Required, never `0`: a responder with no chain peak errors
    /// instead of answering. Self-consistency against `entry_set_stale` only
    /// catches an internally inconsistent responder — see the type doc's
    /// trust-boundary section. SPEC §4.5.
    pub chain_peak_timestamp: u64,
}

/// Params for
/// [`dig.listRewardDistributorCommitments`](crate::method::Method::ListRewardDistributorCommitments).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ListRewardDistributorCommitmentsParams {
    /// The distributor singleton's launcher id (64-hex, required).
    pub launcher_id: HexId,
}

/// One clawback commitment slot for a distributor epoch — SPEC §7.4 clause 5.
///
/// # `recoverable_base_units` is NOT `rewards_base_units`
///
/// Committed is not recoverable: SPEC §7.4 clause 4 / §7.5 return only
/// `withdrawal_share_bps / 10000` of the committed value on clawback (the
/// remainder is forfeited to the reserve — see
/// [`GetRewardDistributorResult::withdrawal_share_bps`]). Reporting only
/// `rewards_base_units` and letting a caller label it "recoverable" would
/// overstate every clawback by the forfeit fraction — exactly the
/// one-balance-figure money-honesty failure SPEC §7.4 clause 5 forbids,
/// relocated from a single total into a single per-slot figure. So the
/// **responder** must compute `recoverable_base_units` itself, with integer
/// arithmetic in the order `rewards_base_units * withdrawal_share_bps /
/// 10_000` — multiply then divide, no floats, truncated (never rounded up:
/// rounding up would promise money the chain will not return). This type
/// does not enforce that computation — see below.
///
/// Only the holder of the key for `clawback_puzzle_hash` may claw this slot
/// back — not an operator role, not the manager singleton, and not the
/// launcher (SPEC §7.4 clause 3). This field is the proof of entitlement; a
/// reader must not mistake it for a display label.
///
/// This type does not enforce any of the above: `recoverable_base_units` is
/// a bare `pub u64` with no constructor or validation. The **responder**
/// must compute it in the order described; nothing here checks that it did.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct RewardDistributorCommitment {
    /// The epoch this commitment slot funds.
    pub epoch_start: u64,
    /// The chain's `clawback_ph` (SPEC / `chia-sdk-types`
    /// `RewardDistributorCommitmentSlotValue`): the puzzle hash whose key
    /// holder alone may claw this slot back.
    pub clawback_puzzle_hash: HexId,
    /// The committed amount, in base units.
    pub rewards_base_units: u64,
    /// The amount actually recoverable on clawback, in base units —
    /// `rewards_base_units * withdrawal_share_bps / 10_000`, integer
    /// arithmetic, truncated down. See the type doc for why this must never
    /// be derived by a caller from `rewards_base_units` alone.
    ///
    /// This is share arithmetic only. It is **NOT an eligibility claim**: it
    /// says what fraction of the slot would return, not that the caller may
    /// claw it back. Entitlement is key-holding against
    /// `clawback_puzzle_hash` and nothing else (SPEC §7.4 cl. 3).
    pub recoverable_base_units: u64,
}

/// Result for
/// [`dig.listRewardDistributorCommitments`](crate::method::Method::ListRewardDistributorCommitments)
/// — SPEC §7.4 clause 5: per-epoch commitment slots, never a single balance
/// figure.
///
/// # The chain-view anchor — SPEC §4.5
///
/// `commitments` is read off the distributor singleton's on-chain slots, so
/// it carries the same chain-view anchor as [`GetRewardDistributorResult`]
/// and for the same reason: `observed_at` is the wall clock of reply
/// assembly, `chain_peak_height` / `chain_peak_timestamp` are the chain's own
/// clock at read time. See that type's doc for the full argument and the
/// refusal rule (both anchor fields required, never `Option`, never `0`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct ListRewardDistributorCommitmentsResult {
    /// The distributor singleton's launcher id (64-hex).
    pub launcher_id: HexId,
    /// The curried launch constant, echoed so a caller's row math (dividing
    /// `recoverable_base_units` by `rewards_base_units`) is auditable against
    /// the value that actually governs it. A responder MUST use this echoed
    /// value — never a compiled-in constant — when computing each row's
    /// `recoverable_base_units`, because the share is a launch-curried,
    /// per-distributor value that differs across distributors. A conforming
    /// responder MUST NOT emit a value above `10_000`.
    pub withdrawal_share_bps: u16,
    /// The payout epoch length, in seconds — a launch-curried, immutable
    /// distributor constant, echoed here so a caller can compute an epoch's
    /// end (`epoch_start + epoch_seconds`) or place a commitment on a
    /// calendar without a second `dig.getRewardDistributor` call. This is
    /// per-distributor and defaulted, not a fixed 7-day value, so it must
    /// not be hardcoded.
    pub epoch_seconds: u64,
    /// One entry per commitment slot. Empty is legitimate: a distributor
    /// funded only via `AddIncentives` has no clawback-eligible slots at all
    /// — an irrevocable donation, not an error.
    pub commitments: Vec<RewardDistributorCommitment>,
    /// Unix seconds this result was assembled — a WALL clock. Says nothing
    /// about chain freshness; read `chain_peak_timestamp` for that.
    pub observed_at: u64,
    /// The distributor singleton's chain peak height at read time. Required
    /// — see [`GetRewardDistributorResult::chain_peak_height`]. SPEC §4.5.
    pub chain_peak_height: u64,
    /// `block_timestamp(chain_peak_height)` — the chain clock. Required, never
    /// `0` — see [`GetRewardDistributorResult::chain_peak_timestamp`]. SPEC
    /// §4.5.
    pub chain_peak_timestamp: u64,
}

// ===========================================================================
// dig.getPayeeRewardClaimStatus
// (CONTROL — loopback / in-process only; dig-rewards-coin SPEC §12.5 clause 6,
//  §2.4)
// ===========================================================================

/// The subject of a **payee-side** status answer.
///
/// One variant on purpose, and named for that one variant on purpose. A payee's
/// claim-side posture and a funder's distributor-side posture are different
/// answers with different money behind them, and this crate keeps them in
/// different types rather than in two arms of one enum — so a payee-shaped
/// result structurally cannot be built carrying a funder's subject, whatever a
/// responder gets wrong. A funder answer, if this crate ever grows one, gets its
/// own type and its own literal.
///
/// The name carries that rule. A `RewardSubject` invites a `Funder` arm, and the
/// moment it has one the type guarantees nothing; `PayeeSubject` cannot absorb a
/// funder arm without a rename obviously wrong at the call site, which is the
/// point.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum PayeeSubject {
    /// The node answering is speaking as a **payee** — a mirror with a claim,
    /// not the party that funded the reserve.
    #[serde(rename = "payee")]
    Payee,
}

/// What a node can say about its own claim log: it read the log and has a count,
/// or it did not read the log and has no count to give.
///
/// # Why the count is inside the variant
///
/// The count and the fact that anything was counted cannot be separated, for the
/// same reason [`Half`]'s items live inside `Consulted`. A node whose claim log
/// is missing, unreadable, or failed to read has nothing to report, and a
/// `claims_submitted_count: 0` beside a freshly stamped `observed_at` is worse
/// than an undated zero: the date actively reassures the reader that something
/// looked at the log just now and found nothing, which is dig-rewards-coin SPEC
/// §12.5 clause 6's "reassuring zero" reproduced inside the type added to remove
/// it. There is no arm here that can carry a count without having read the log.
///
/// This is a sibling of [`Half`] rather than an instance of it: `Half` answers
/// for a *collection* and carries `items`, and forcing a scalar tally through it
/// would mean either a vacuous `Vec` or a wire key that names the wrong thing.
/// The vocabulary — `outcome`, two arms, `observed_at` in both — is deliberately
/// identical, so a reader who has learned one has learned the other.
///
/// `observed_at` dates the **consultation**, not the assembly of the answer:
/// in [`Consulted`](Self::Consulted) it is when the log was read, and in
/// [`NotConsulted`](Self::NotConsulted) it is when the responder established
/// that it could not read it. Fail-closed like [`Half`]: internally tagged, no
/// `#[serde(other)]`, no `Default`, no `skip_serializing_if`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "outcome", rename_all = "snake_case", deny_unknown_fields)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum ClaimLogObservation {
    /// The claim log WAS read as of `observed_at` (Unix seconds), and
    /// `claims_submitted_count` is what it held.
    Consulted {
        /// Unix seconds the claim log was read.
        observed_at: u64,
        /// How many claim submissions this node has made as a payee. A count of
        /// attempts, not of money: it says nothing about how much was settled,
        /// and a reader MUST NOT treat it as an amount or as a success count.
        claims_submitted_count: u64,
    },
    /// The claim log was NOT read as of `observed_at` (Unix seconds) — missing,
    /// unreadable, or the read failed. There is deliberately no count here.
    NotConsulted {
        /// Unix seconds the responder established it could not read the log.
        observed_at: u64,
    },
}

/// The claim loop's own condition, as the loop last reported it — a closed
/// set of seven members (SPEC §4.4.3). `ClaimLoopState` mirrors the producer's
/// enumeration one-to-one, payloads included: a wire type with fewer states
/// than the loop can be in is a new instance of the defect this method exists
/// to remove, a type that cannot say something went wrong.
///
/// The tag key is `kind`, not `state` — the field holding this type is already
/// named `state`, and `"state": { "state": … }` would put two meanings under
/// one key in adjacent positions.
///
/// [`ClaimableButNotClaiming`](Self::ClaimableButNotClaiming) is the state a
/// conforming producer reports **whenever claims exist that the loop did not
/// make and no cycle-wide fault is live** — the anti-silence signal this
/// method exists to carry. It is never folded into
/// [`Nominal`](Self::Nominal) for lack of anywhere else to go, and a
/// cycle-wide fault is never folded into it either.
///
/// The five payload-less members ([`Idle`](Self::Idle),
/// [`ChainSourceUnavailable`](Self::ChainSourceUnavailable),
/// [`PersistedStateCorrupt`](Self::PersistedStateCorrupt),
/// [`CadenceNotElapsed`](Self::CadenceNotElapsed), [`Nominal`](Self::Nominal))
/// serialise as exactly `{ "kind": … }`. serde does not apply
/// `deny_unknown_fields` to the payload-less members of an internally tagged
/// enum, so `{ "kind": "idle", "claimable": 5 }` parses as `Idle` with the
/// stray key silently dropped (SPEC §4.4.1's one stated vacuity) — a
/// conforming producer never emits the stray key, and a consumer MUST NOT
/// read any key but `kind` from a payload-less state. The property this type
/// does enforce is the one that carries weight: the counts a reader acts on
/// live on [`ClaimLoopObservation::Consulted`], where unknown and missing
/// keys ARE rejected.
///
/// Not `#[non_exhaustive]`, on purpose: a wildcard arm in a consumer is
/// `#[serde(other)]` relocated to the render path, deciding at compile time
/// that a state nobody has heard of renders as something bland. A new member
/// is a SPEC amendment and a breaking release for every consumer.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum ClaimLoopState {
    /// No cycle has been attempted yet.
    Idle,
    /// The chain seam reported itself unavailable; no cycle ran. The true
    /// state, not a silent no-op.
    ChainSourceUnavailable,
    /// The loop's persisted claim state was unreadable, unparsable, over its
    /// own budget or future-dated; the loop treats its spend window as
    /// exhausted and submits nothing this cycle. A refusal made visible, not
    /// a freeze that reads as [`Nominal`](Self::Nominal).
    PersistedStateCorrupt,
    /// The claim cadence has not elapsed since the last completed cycle: a
    /// deliberate skip, named as its own condition rather than left as the
    /// absence of one.
    CadenceNotElapsed,
    /// A chain call this cycle failed with a real error, distinct from "no
    /// chain at all".
    Faulted {
        /// Consecutive cycles, including the current one, on which the loop
        /// has observed a cycle-wide fault. From a conforming producer this
        /// is at least 1; the type does not reject `0`.
        cycles: u64,
    },
    /// Fewer distributors were claimed against this cycle than should have
    /// been, and no fault is live. **The anti-silence signal**: the loop is
    /// running and paying nobody, or not everybody. This is the state
    /// reported whenever claims exist and none are being made.
    ClaimableButNotClaiming {
        /// This cycle's distributors that should have been claimed against.
        /// A count of distributors, never an amount, and at least
        /// [`ClaimLoopObservation::Consulted`]'s own
        /// `distributors_claimable` — the producer folds in refusals it
        /// never counted as claimable.
        claimable: u64,
        /// This cycle's distributors actually claimed against. From a
        /// conforming producer, strictly less than `claimable`; the type
        /// does not reject the contrary.
        submitted: u64,
    },
    /// A cycle completed and none of the above is true.
    Nominal,
}

/// What a node can say about its own claim loop: it read the loop's last
/// reported condition and has counts and a state, or it did not read the loop
/// and has nothing to give.
///
/// A sibling of [`ClaimLogObservation`], same vocabulary: `outcome`, two
/// arms, `observed_at` in both. `observed_at` dates the **consultation** —
/// in [`Consulted`](Self::Consulted) it is when the loop last wrote the
/// status this arm reports, stamped by the loop in the cycle that produced
/// these numbers or, before any cycle, when the loop published its initial
/// `idle`; a responder MUST NOT stamp it with the clock of the RPC handler
/// that read the status. Re-dating the snapshot at read time manufactures
/// freshness for a number nobody produced just now, and only an
/// `observed_at` that stops advancing tells a reader a stuck loop's last
/// `nominal` is its last word rather than its current one.
///
/// In [`NotConsulted`](Self::NotConsulted) it is when the responder
/// established the loop's status could not be read: the loop is not
/// constructed (claiming disabled or not started) or its status was
/// unreadable — not "the chain is unreachable" (that is a
/// [`ClaimLoopState`]) and not "no distributors" (that is a count).
///
/// Fail-closed like [`ClaimLogObservation`]: internally tagged, no
/// `#[serde(other)]`, no `Default`, no `skip_serializing_if`,
/// `deny_unknown_fields` on the whole enum — a count or a verdict cannot
/// ride an arm that says nothing was read.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "outcome", rename_all = "snake_case", deny_unknown_fields)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub enum ClaimLoopObservation {
    /// The claim loop's status WAS read as of `observed_at` (Unix seconds).
    Consulted {
        /// Unix seconds the claim loop last wrote the status this arm
        /// reports.
        observed_at: u64,
        /// How many reward distributors this node's claim loop has
        /// discovered as candidates it might hold an entry in. A count of
        /// distributors, never an amount.
        distributors_known: u64,
        /// How many of those the loop judged claimable in the cycle dated by
        /// `observed_at`. A count of distributors, never an amount, and a
        /// per-cycle reading, not a lifetime total.
        distributors_claimable: u64,
        /// The loop's condition in the cycle dated by `observed_at`.
        state: ClaimLoopState,
    },
    /// The claim loop's status was NOT read as of `observed_at` (Unix
    /// seconds) — the loop is not constructed or its status was unreadable.
    /// There is deliberately no count and no state here.
    NotConsulted {
        /// Unix seconds the responder established it could not read the
        /// loop's status.
        observed_at: u64,
    },
}

/// Result for
/// [`dig.getPayeeRewardClaimStatus`](crate::method::Method::GetPayeeRewardClaimStatus)
/// — the claim-side posture of the node answering, as a payee.
///
/// # The subject is on the wire, not inferred from the endpoint
///
/// [`subject`](Self::subject) is required and is the literal `"payee"`. It is
/// not redundant with the method name: this epic shipped a defect in which a
/// **funder's** distributor-wide total was rendered to a **payee** as that
/// operator's own earnings, overstating by up to 250x, and it passed security
/// review and a full green CI because no test asserted *whose* money the number
/// was. A renderer that reads `subject` off the payload cannot make that
/// substitution silently; one that infers the subject from which endpoint it
/// thinks it called can.
///
/// # No monetary amount, at all
///
/// There is deliberately no amount field here — not optional, not nullable,
/// absent. A payload that carries no amount has nothing a UI can misrender as
/// earnings, and that absence is the whole defence; an `Option<u64>` would not
/// be, because the misrendering path is a present number attributed to the wrong
/// party. A payee that wants its own settled history reads its own past
/// `InitiatePayout` spends, which are on chain and are evidence (SPEC §12.5
/// clause 7). The payout puzzle hash is likewise absent and MUST NOT be added:
/// it is the payee's payment identity, and nothing here needs it.
///
/// # No `#[serde(default)]`, no `skip_serializing_if`
///
/// Every field is required on the wire in both directions. A defaulting field is
/// a field a producer can omit and a consumer will invent — which for
/// [`subject`](Self::subject) would restore exactly the inferred-subject hazard
/// above, and for [`claim_log`](Self::claim_log) would manufacture a
/// consultation nobody performed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct PayeeClaimStatus {
    /// Always [`PayeeSubject::Payee`]; serialises as the literal
    /// `"subject": "payee"`.
    pub subject: PayeeSubject,
    /// This node's claim log: read, with the count it held, or not read at all.
    ///
    /// The count lives inside the observation so it cannot be separated from the
    /// fact that something read the log. The reader derives staleness itself
    /// from the observation's `observed_at` and its own clock (SPEC §2.4); no
    /// staleness is pre-computed here.
    pub claim_log: ClaimLogObservation,
    /// This node's claim loop: read, with its counts and last-reported
    /// state, or not read at all (new in 0.13.0, SPEC §4.4).
    ///
    /// New in 0.13.0. `deny_unknown_fields` on this struct means a 0.12.0
    /// payload — which has no `claim_loop` key — fails to parse rather than
    /// silently answering with a missing field: version skew fails loudly in
    /// both directions.
    pub claim_loop: ClaimLoopObservation,
}

// ===========================================================================
// dig.health / dig.methods / rpc.discover  (discovery)
// ===========================================================================

/// Result for [`dig.health`](crate::method::Method::Health) — liveness + a
/// capability summary.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct Health {
    /// Liveness — `"ok"` when the node can serve.
    pub status: String,
    /// The node's software version.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub version: Option<String>,
    /// The DIG network id the node serves.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub network_id: Option<String>,
    /// The method names this node implements (its profile).
    #[serde(default)]
    pub methods: Vec<String>,
}

/// Result for [`dig.methods`](crate::method::Method::Methods) — the method names
/// this node implements (agent self-describe).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "schema-export", derive(schemars::JsonSchema))]
pub struct Methods {
    /// The implemented method names.
    pub methods: Vec<String>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    /// The JSON object keys of `value`, sorted — so a key-set assertion reads as
    /// one line and fails naming the field that appeared or vanished.
    fn sorted_keys(value: &serde_json::Value) -> Vec<&str> {
        let mut keys: Vec<&str> = value
            .as_object()
            .expect("expected a JSON object")
            .keys()
            .map(String::as_str)
            .collect();
        keys.sort_unstable();
        keys
    }

    /// **Proves:** `ContentChunk` round-trips a node-profile window (no
    /// network-profile fields) without inventing keys.
    /// **Catches:** a missing `skip_serializing_if` that would leak `null`
    /// network-profile fields onto the node profile.
    #[test]
    fn content_chunk_node_profile_is_lean() {
        let c = ContentChunk {
            ciphertext: "AAA=".into(),
            root: "ab".repeat(32),
            complete: false,
            next_offset: Some(3_145_728),
            inclusion_proof: Some("cHJvb2Y=".into()),
            chunk_lens: Some(vec![10, 20]),
            source: Some("local".into()),
            total_length: None,
            length: None,
            offset: None,
            program_hash: None,
        };
        let v = serde_json::to_value(&c).unwrap();
        assert_eq!(v["source"], "local");
        assert!(
            v.get("total_length").is_none(),
            "node profile must omit total_length"
        );
        assert!(v.get("program_hash").is_none());
        assert_eq!(serde_json::from_value::<ContentChunk>(v).unwrap(), c);
    }

    /// **Proves:** the network-profile fields serialize when present.
    #[test]
    fn content_chunk_network_profile_carries_extras() {
        let c = ContentChunk {
            ciphertext: "AAA=".into(),
            root: "cd".repeat(32),
            complete: true,
            next_offset: None,
            inclusion_proof: None,
            chunk_lens: None,
            source: None,
            total_length: Some(100),
            length: Some(100),
            offset: Some(0),
            program_hash: Some("ef".repeat(32)),
        };
        let v = serde_json::to_value(&c).unwrap();
        assert_eq!(v["total_length"], 100);
        assert_eq!(v["length"], 100);
        assert!(v.get("source").is_none());
    }

    /// **Proves:** the untagged `Inventory` picks `ForStore` vs `AllStores` by
    /// shape.
    /// **Catches:** a lost `#[serde(untagged)]` that would tag the variant.
    #[test]
    fn inventory_untagged_by_shape() {
        let for_store = Inventory::ForStore {
            store_id: "ab".repeat(32),
            roots: vec!["cd".repeat(32)],
        };
        let s = serde_json::to_string(&for_store).unwrap();
        assert!(s.contains("\"roots\""));
        assert!(!s.contains("ForStore"));
        assert_eq!(serde_json::from_str::<Inventory>(&s).unwrap(), for_store);

        let all = Inventory::AllStores {
            stores: vec!["ef".repeat(32)],
        };
        let s = serde_json::to_string(&all).unwrap();
        assert!(s.contains("\"stores\""));
        assert_eq!(serde_json::from_str::<Inventory>(&s).unwrap(), all);
    }

    /// **Proves:** `RedirectInfo` serializes the full redirect payload the
    /// `-32008` envelope carries.
    #[test]
    fn redirect_info_shape() {
        let r = RedirectInfo {
            content: ContentRef {
                store_id: "ab".repeat(32),
                root: Some("cd".repeat(32)),
                retrieval_key: Some("ef".repeat(32)),
            },
            providers: vec![Provider {
                peer_id: "12".repeat(32),
                addresses: vec![PeerAddress {
                    host: "::1".into(),
                    port: 9444,
                    kind: "direct".into(),
                }],
            }],
            redirect_depth: 1,
            max_redirects: 4,
        };
        let v = serde_json::to_value(&r).unwrap();
        assert_eq!(v["redirect_depth"], 1);
        assert_eq!(v["max_redirects"], 4);
        assert_eq!(v["providers"][0]["addresses"][0]["host"], "::1");
        assert_eq!(serde_json::from_value::<RedirectInfo>(v).unwrap(), r);
    }

    /// **Proves:** `cache.stats` models the live dig-node result field-for-field
    /// (the nested `content_cache{hits,misses}` object included).
    /// **Catches:** a drift from the node's `cache.stats` wire shape (#1075).
    #[test]
    fn cache_stats_wire_shape() {
        let s = CacheStats {
            cap_bytes: 1 << 30,
            used_bytes: 2048,
            entry_count: 3,
            total_bytes: 2048,
            evicted_count: 1,
            evicted_bytes: 512,
            content_cache: ContentCacheCounters { hits: 7, misses: 2 },
        };
        let v = serde_json::to_value(s).unwrap();
        assert_eq!(v["cap_bytes"], 1 << 30);
        assert_eq!(v["entry_count"], 3);
        assert_eq!(v["content_cache"]["hits"], 7);
        assert_eq!(v["content_cache"]["misses"], 2);
        assert_eq!(serde_json::from_value::<CacheStats>(v).unwrap(), s);
    }

    /// **Proves:** the subscription-management results carry the exact
    /// `{subscribed, added|removed, store_id}` / `{subscriptions, count}` shapes
    /// the live node returns.
    #[test]
    fn subscription_result_shapes() {
        let sub = SubscribeResult {
            subscribed: true,
            added: true,
            store_id: "ab".repeat(32),
        };
        let v = serde_json::to_value(&sub).unwrap();
        assert_eq!(v["subscribed"], true);
        assert_eq!(v["added"], true);
        assert_eq!(serde_json::from_value::<SubscribeResult>(v).unwrap(), sub);

        let unsub = UnsubscribeResult {
            subscribed: false,
            removed: true,
            store_id: "cd".repeat(32),
        };
        let v = serde_json::to_value(&unsub).unwrap();
        assert_eq!(v["subscribed"], false);
        assert_eq!(v["removed"], true);
        assert_eq!(
            serde_json::from_value::<UnsubscribeResult>(v).unwrap(),
            unsub
        );

        let list = SubscriptionsList {
            subscriptions: vec!["ef".repeat(32)],
            count: 1,
        };
        let v = serde_json::to_value(&list).unwrap();
        assert_eq!(v["count"], 1);
        assert_eq!(
            serde_json::from_value::<SubscriptionsList>(v).unwrap(),
            list
        );
    }

    /// **Proves:** `ModuleInfo` carries `chunk_lens` covering every chunk, and
    /// round-trips with unknown future fields.
    /// **Catches:** a missing `chunk_lens` field that would leave a puller unable
    /// to map a fetched byte range to its covering chunk hash.
    /// **Invariants enforced by docs:** `chunk_lens` must have the same length as
    /// `chunk_hashes` and must sum to `total_size`.
    #[test]
    fn module_info_chunk_lens_shape() {
        let info = ModuleInfo {
            total_size: 1024,
            module_hash: "ab".repeat(32),
            chunk_hashes: vec!["cd".repeat(32), "ef".repeat(32)],
            chunk_lens: vec![512, 512],
        };
        let v = serde_json::to_value(&info).unwrap();
        assert_eq!(v["total_size"], 1024);
        assert_eq!(v["chunk_hashes"].as_array().unwrap().len(), 2);
        assert_eq!(v["chunk_lens"].as_array().unwrap().len(), 2);
        assert_eq!(v["chunk_lens"][0], 512);
        assert_eq!(v["chunk_lens"][1], 512);
        assert_eq!(serde_json::from_value::<ModuleInfo>(v).unwrap(), info);
    }

    /// **Proves:** `ModuleInfo` deserialization REJECTS missing `chunk_lens` field.
    /// This is a REQUIRED field (not optional) — omitting it from the wire is a
    /// protocol violation and must fail-closed.
    #[test]
    fn module_info_rejects_missing_chunk_lens() {
        let json_str = r#"{"total_size": 2048, "module_hash": "1122334455667788990011223344556677889900112233445566778899001122", "chunk_hashes": []}"#;
        let result: Result<ModuleInfo, _> = serde_json::from_str(json_str);
        assert!(
            result.is_err(),
            "ModuleInfo must reject JSON missing the required chunk_lens field"
        );
        let err = result.unwrap_err();
        assert!(
            err.to_string().contains("chunk_lens"),
            "error message should mention chunk_lens: {}",
            err
        );
    }

    /// **Proves:** the peer connect/disconnect params + results round-trip and
    /// match the node's `{connected|disconnected, peer_id}` shapes.
    #[test]
    fn peer_connect_disconnect_shapes() {
        let p = PeerConnectParams {
            peer: "12".repeat(32),
        };
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(serde_json::from_value::<PeerConnectParams>(v).unwrap(), p);

        let c = PeerConnectResult {
            connected: true,
            peer_id: "12".repeat(32),
        };
        let v = serde_json::to_value(&c).unwrap();
        assert_eq!(v["connected"], true);
        assert_eq!(serde_json::from_value::<PeerConnectResult>(v).unwrap(), c);

        let d = PeerDisconnectResult {
            disconnected: true,
            peer_id: "34".repeat(32),
        };
        let v = serde_json::to_value(&d).unwrap();
        assert_eq!(v["disconnected"], true);
        assert_eq!(
            serde_json::from_value::<PeerDisconnectResult>(v).unwrap(),
            d
        );
    }

    /// **Proves:** `cache.getConfig` uses the canonical `cache_dir` field name.
    /// **Catches:** a regression to the shell's historical `dir` name.
    #[test]
    fn cache_config_field_name_is_cache_dir() {
        let c = CacheConfig {
            cap_bytes: 1 << 30,
            used_bytes: 0,
            cache_dir: "/var/cache/dig".into(),
            shared: true,
        };
        let v = serde_json::to_value(&c).unwrap();
        assert!(v.get("cache_dir").is_some());
        assert!(v.get("dir").is_none(), "must not use the legacy `dir` name");
    }

    /// **Proves:** an OLDER client's `dig.getAvailability` params — written
    /// before the hop budget existed — still deserialize, and read as a fresh,
    /// unhopped ask.
    /// **Catches:** a `redirect_depth` declared as a required `u64`, which
    /// rejects exactly these params with `missing field redirect_depth` and would
    /// make every pre-0.8 caller's ask a parse error at the peer boundary.
    /// **Guarded by:** the field's `Option` TYPE. `serde`'s derive already reads a
    /// missing `Option` field as `None`, so the `#[serde(default)]` beside it is
    /// parity with the sibling params types rather than the live guard — removing
    /// it alone leaves this test green (mutant-tested). Do not cite the attribute
    /// as the thing that keeps older clients working.
    #[test]
    fn get_availability_params_accepts_an_older_clients_params() {
        let older = json!({
            "items": [ { "store_id": "ab".repeat(32) } ]
        });
        let p: GetAvailabilityParams = serde_json::from_value(older).unwrap();
        assert_eq!(p.items.len(), 1);
        assert_eq!(p.redirect_depth, None, "an absent budget stays absent");
        assert_eq!(p.hops_consumed(), 0, "absent means zero hops consumed");
    }

    /// **Proves:** a hop-zero ask serializes to exactly the pre-0.8 bytes — the
    /// `redirect_depth` key is absent, not `null`.
    /// **Catches:** a bare `#[serde(default)]` without `skip_serializing_if`,
    /// which would add `"redirect_depth": null` to every existing caller's
    /// frame and change the wire for callers that never opted in.
    #[test]
    fn get_availability_params_omits_an_absent_hop_budget() {
        let p = GetAvailabilityParams::new(vec![AvailabilityQuery {
            store_id: "ab".repeat(32),
            root: None,
            retrieval_key: None,
        }]);
        let v = serde_json::to_value(&p).unwrap();
        let keys: Vec<&String> = v.as_object().unwrap().keys().collect();
        assert_eq!(keys, vec!["items"], "hop-zero params carry only `items`");
    }

    /// **Proves:** a hopped ask round-trips its budget under the `redirect_depth`
    /// key, and reads back through `hops_consumed`.
    #[test]
    fn get_availability_params_round_trips_the_hop_budget() {
        let p = GetAvailabilityParams::new(vec![AvailabilityQuery {
            store_id: "cd".repeat(32),
            root: Some("ef".repeat(32)),
            retrieval_key: None,
        }])
        .with_redirect_depth(2);
        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["redirect_depth"], 2);
        assert_eq!(p.hops_consumed(), 2);
        assert_eq!(
            serde_json::from_value::<GetAvailabilityParams>(v).unwrap(),
            p
        );
    }

    /// **Proves:** an older client params object — written before ANY of the
    /// recursive-ask fields existed — still deserializes, and every new field reads
    /// as its documented absent value.
    /// **Catches:** any of the three declared as required, which would turn every
    /// pre-0.9 caller ask into `missing field` at the peer boundary.
    #[test]
    fn get_availability_params_accepts_a_client_older_than_the_recursive_ask() {
        let older = json!({ "items": [ { "store_id": "ab".repeat(32) } ] });
        let p: GetAvailabilityParams = serde_json::from_value(older).unwrap();

        assert_eq!(p.budget_ms(), None, "absent budget_ms means unbudgeted");
        assert_eq!(p.ask_id(), None, "absent ask_id means dedup opted out");
        assert_eq!(p.hops_consumed(), 0);
    }

    /// **Proves:** a params object carrying no recursive-ask fields serializes to
    /// exactly the pre-0.9 bytes — the three new keys are ABSENT, not `null`.
    /// **Catches:** a bare `#[serde(default)]` without `skip_serializing_if`, which
    /// would add `"budget_ms": null` and `"ask_id": null` to the frame of every
    /// caller that never opted in.
    #[test]
    fn get_availability_params_omits_absent_recursive_ask_fields() {
        let p = GetAvailabilityParams::new(vec![AvailabilityQuery {
            store_id: "ab".repeat(32),
            root: None,
            retrieval_key: None,
        }]);
        let v = serde_json::to_value(&p).unwrap();
        let keys: Vec<&String> = v.as_object().unwrap().keys().collect();
        assert_eq!(keys, vec!["items"], "a plain ask carries only `items`");
    }

    /// **Proves:** the time budget and the hop budget are two INDEPENDENT fields
    /// under two distinct keys, each round-tripping its own value.
    /// **Catches:** the shape defect this addition exists to prevent — folding the
    /// time budget into `redirect_depth`. The fixture sets them to DIFFERENT values
    /// (2 hops, 9000 ms) precisely so a single backing integer cannot satisfy both
    /// assertions; equal values would pass under either shape.
    #[test]
    fn the_time_budget_is_a_separate_field_from_the_hop_budget() {
        let p = GetAvailabilityParams::new(vec![AvailabilityQuery {
            store_id: "cd".repeat(32),
            root: None,
            retrieval_key: None,
        }])
        .with_redirect_depth(2)
        .with_budget_ms(9_000);

        let v = serde_json::to_value(&p).unwrap();
        assert_eq!(v["redirect_depth"], 2, "hops counted UP from zero");
        assert_eq!(v["budget_ms"], 9_000, "milliseconds counted DOWN to zero");
        assert_eq!(p.hops_consumed(), 2);
        assert_eq!(p.budget_ms(), Some(9_000));
        assert_eq!(
            serde_json::from_value::<GetAvailabilityParams>(v).unwrap(),
            p
        );
    }

    /// **Proves:** a zero time budget survives the wire as `Some(0)` and is NOT
    /// erased into `None`.
    /// **Catches:** a `skip_serializing_if` written over the VALUE rather than the
    /// Option (`is_zero`-style), which would make "you have no time left, do not ask
    /// onward" indistinguishable from "unbudgeted, use your own policy" — exactly
    /// inverting the field on the one hop where it matters most.
    #[test]
    fn a_zero_time_budget_is_not_the_same_as_an_absent_one() {
        let exhausted = GetAvailabilityParams::new(vec![]).with_budget_ms(0);
        let v = serde_json::to_value(&exhausted).unwrap();

        assert_eq!(v["budget_ms"], 0, "an exhausted budget stays on the wire");
        assert_eq!(
            serde_json::from_value::<GetAvailabilityParams>(v)
                .unwrap()
                .budget_ms(),
            Some(0)
        );
        assert_eq!(
            GetAvailabilityParams::new(vec![]).budget_ms(),
            None,
            "unbudgeted is a different state from budget zero"
        );
    }

    /// **Proves:** `ask_id` round-trips verbatim under its own key, and is NOT the
    /// JSON-RPC `id`.
    /// **Catches:** an implementation that reuses the envelope correlator for dedup.
    /// The fixture puts a hardcoded `"id": 1` — the exact value dig-node was sending
    /// — beside a real 16-byte ask id in one envelope, so a reader that took the
    /// correlator would see `1` and disagree with both assertions.
    #[test]
    fn the_ask_id_is_not_the_jsonrpc_correlator() {
        const ASK_ID: &str = "3f9c1a04b7e25d68f0a1c3b5d7e9f012";
        assert_eq!(ASK_ID.len(), 32, "16 random bytes as lowercase hex");

        let envelope = json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "dig.getAvailability",
            "params": {
                "items": [ { "store_id": "ab".repeat(32) } ],
                "ask_id": ASK_ID,
            }
        });

        let p: GetAvailabilityParams = serde_json::from_value(envelope["params"].clone()).unwrap();
        assert_eq!(p.ask_id(), Some(ASK_ID));
        assert_ne!(
            p.ask_id(),
            Some("1"),
            "the dedup identity must not be read from the envelope `id`"
        );
        assert_eq!(envelope["id"], 1, "the correlator is untouched beside it");
    }

    /// **Proves:** `absence_established` distinguishes THREE states on the wire —
    /// asserted, explicitly-not-established, and unknown-because-older-server — and
    /// that the unknown state serializes as an ABSENT key rather than `false`.
    /// **Catches:** the collapse this field exists to prevent. The fixture carries
    /// all three answers in ONE batch, so a `bool` with `#[serde(default)]` (which
    /// would read the old server answer as `false`) makes the second and third
    /// answers compare EQUAL and the test fails; a fixture with only one answer
    /// could not see that.
    #[test]
    fn absence_established_keeps_absent_distinct_from_false() {
        let asserted = AvailabilityAnswer {
            available: false,
            absence_established: Some(true),
            ..Default::default()
        };
        let inconclusive = AvailabilityAnswer {
            available: false,
            absence_established: Some(false),
            ..Default::default()
        };
        let older_server = AvailabilityAnswer {
            available: false,
            ..Default::default()
        };

        assert_ne!(
            inconclusive, older_server,
            "an explicit `false` is a claim; an absent field is not"
        );
        assert_eq!(asserted.absence_established_or_unknown(), Some(true));
        assert_eq!(inconclusive.absence_established_or_unknown(), Some(false));
        assert_eq!(
            older_server.absence_established_or_unknown(),
            None,
            "an older server makes no claim either way"
        );

        let batch = serde_json::to_value(AvailabilityBatch {
            items: vec![asserted, inconclusive, older_server],
        })
        .unwrap();
        assert_eq!(batch["items"][0]["absence_established"], true);
        assert_eq!(batch["items"][1]["absence_established"], false);
        assert!(
            batch["items"][2].get("absence_established").is_none(),
            "the unknown state is an absent key, never `false` and never `null`"
        );
    }

    /// **Proves:** an OLDER client can still read a NEWER answer — the added field
    /// does not break the shipped shape (§5.1).
    #[test]
    fn an_answer_carrying_the_new_field_still_parses_as_the_shipped_shape() {
        let newer = json!({
            "items": [ { "available": false, "absence_established": true } ]
        });
        let b: AvailabilityBatch = serde_json::from_value(newer).unwrap();
        assert_eq!(b.items.len(), 1);
        assert!(!b.items[0].available);
        assert_eq!(b.items[0].absence_established_or_unknown(), Some(true));
    }

    /// **Proves:** the hop budget an availability ask carries is the SAME field,
    /// with the same key, type and value, that a `-32008` redirect hands back and
    /// that `dig.getContent` / `dig.fetchRange` already echo — one field, one
    /// interpretation, counted UP toward `max_redirects`.
    /// **Catches:** a second reading of the budget in this crate (a remaining
    /// allowance counting DOWN, a differently-named key, a differently-typed
    /// value) — the byte-drift the shipped redirect contract exists to prevent.
    #[test]
    fn availability_hop_budget_mirrors_the_redirect_budget() {
        let handed_back = RedirectInfo {
            content: ContentRef {
                store_id: "ab".repeat(32),
                root: None,
                retrieval_key: None,
            },
            providers: vec![],
            redirect_depth: 3,
            max_redirects: 4,
        };
        let echoed = handed_back.redirect_depth;

        let availability = serde_json::to_value(
            GetAvailabilityParams::new(vec![AvailabilityQuery {
                store_id: "ab".repeat(32),
                root: None,
                retrieval_key: None,
            }])
            .with_redirect_depth(echoed),
        )
        .unwrap();
        let content = serde_json::to_value(GetContentParams {
            store_id: "ab".repeat(32),
            retrieval_key: "cd".repeat(32),
            root: None,
            offset: None,
            mode: None,
            redirect_depth: Some(echoed),
        })
        .unwrap();
        let range = serde_json::to_value(
            FetchRangeParams::resource("ab".repeat(32), "cd".repeat(32), "ef".repeat(32), 1)
                .with_redirect_depth(echoed),
        )
        .unwrap();

        for (method, params) in [
            ("dig.getAvailability", &availability),
            ("dig.getContent", &content),
            ("dig.fetchRange", &range),
        ] {
            assert_eq!(
                params["redirect_depth"], 3,
                "{method} must carry the echoed depth under `redirect_depth`"
            );
        }
        assert!(
            handed_back.redirect_depth < handed_back.max_redirects,
            "the budget counts UP toward `max_redirects`"
        );
    }

    /// **Proves:** a NEWER client's params — carrying a field this build does not
    /// know — still deserialize, so a hop-bearing ask is never refused outright by
    /// an older responder that simply ignores the budget.
    /// **Catches:** a `#[serde(deny_unknown_fields)]` added to the params type,
    /// which would turn every forward-compatible extension into a hard parse
    /// failure at the peer boundary.
    #[test]
    fn get_availability_params_tolerates_an_unknown_field() {
        let newer = json!({
            "items": [ { "store_id": "ab".repeat(32) } ],
            "redirect_depth": 1,
            "a_field_this_build_does_not_know": true
        });
        let p: GetAvailabilityParams = serde_json::from_value(newer).unwrap();
        assert_eq!(p.hops_consumed(), 1);
    }

    // -----------------------------------------------------------------
    // dig.listRewardDistributors / dig.getRewardProverStatus /
    // dig.getRewardDistributor  (#3250, dig-rewards-coin SPEC §2.3/§2.6)
    // -----------------------------------------------------------------

    fn sample_prover_status() -> RewardProverStatus {
        RewardProverStatus {
            launcher_id: "ab".repeat(32),
            store_id: "cd".repeat(32),
            root: "ef".repeat(32),
            prover_state: ProverState::Running,
            prover_state_since: 1_000,
            last_cycle_started_at: Some(1_050),
            last_cycle_completed_at: None,
            next_cycle_due_at: Some(1_600),
            last_entry_write_at: Some(900),
            consecutive_cycle_failures: 0,
            pending_entry_writes: 2,
            observed_at: 1_700,
            counters: ProverCounters {
                mirrors_seen: 3,
                challenges_issued: 10,
                challenges_passed: 9,
                challenges_failed: 1,
                entries_added: 5,
                entries_removed: 1,
                entry_count: 4,
                reserve_base_units: 12_345,
                total_paid_out_base_units: 6_789,
            },
        }
    }

    /// **Proves:** `RewardProverStatus` round-trips through serde.
    #[test]
    fn reward_prover_status_round_trips() {
        let status = sample_prover_status();
        let json = serde_json::to_string(&status).unwrap();
        let back: RewardProverStatus = serde_json::from_str(&json).unwrap();
        assert_eq!(status, back);
    }

    /// **Proves:** `RewardProverStatus`'s JSON key set is EXACTLY the SPEC §2.3
    /// field list, and contains NEITHER a health boolean NOR a pre-computed
    /// staleness field — SPEC §2.4: a wedged loop cannot report its own
    /// wedging, so a boolean the writer sets reads true forever after the
    /// failure it exists to reveal.
    /// **Catches:** a `healthy`/`ok`/`up`/`running`/`stale`/
    /// `seconds_since_last_run`/`is_healthy` field reintroduced onto the
    /// self-reported prover record.
    #[test]
    fn reward_prover_status_has_no_health_boolean_and_exact_keys() {
        let value = serde_json::to_value(sample_prover_status()).unwrap();
        let obj = value.as_object().unwrap();
        let mut got: Vec<&str> = obj.keys().map(String::as_str).collect();
        got.sort_unstable();

        let mut want = vec![
            "launcher_id",
            "store_id",
            "root",
            "prover_state",
            "prover_state_since",
            "last_cycle_started_at",
            "next_cycle_due_at",
            "last_entry_write_at",
            "consecutive_cycle_failures",
            "pending_entry_writes",
            "observed_at",
            "counters",
        ];
        // `last_cycle_completed_at` is `None` in the fixture and this type has
        // no `skip_serializing_if`, so it still serializes as `null` — include it.
        want.push("last_cycle_completed_at");
        want.sort_unstable();
        assert_eq!(got, want);

        // Recurse into `counters` too — a smuggled health flag could hide one
        // level down, and a substring check on the serialized string would
        // miss it (and would also be actively wrong: `ProverState::Running`
        // legitimately serializes the *value* `"running"`, so a
        // `!s.contains("running")` assertion fails on honest input while
        // still passing a smuggled `isRunning` key).
        let counters_keys: Vec<&str> = value["counters"]
            .as_object()
            .unwrap()
            .keys()
            .map(String::as_str)
            .collect();
        let mut all_keys = got.clone();
        all_keys.extend(counters_keys);

        for forbidden in [
            "healthy",
            "ok",
            "up",
            "running",
            "isRunning",
            "stale",
            "isStale",
            "staleness",
            "secondsSinceLastRun",
            "uptime",
            "alive",
            "live",
            "lastRunSecondsAgo",
        ] {
            assert!(
                !all_keys.contains(&forbidden),
                "RewardProverStatus (incl. counters) must not carry `{forbidden}` (SPEC §2.4)"
            );
        }

        // Also assert directly against the Rust field list, independent of the
        // JSON round-trip, so a `#[serde(rename)]` cannot hide a violation.
        got.retain(|k| *k != "prover_state"); // enum-typed; checked separately below.
    }

    /// **Proves:** `ProverState` deserializes each of the nine named SPEC §2.3
    /// variants and REJECTS an unknown string — fail-closed: no
    /// `#[serde(other)]`, no `Default`.
    #[test]
    fn prover_state_covers_the_closed_set_and_rejects_unknown() {
        let known = [
            ("idle", ProverState::Idle),
            ("running", ProverState::Running),
            ("localCopyMissing", ProverState::LocalCopyMissing),
            (
                "chainSourceUnavailable",
                ProverState::ChainSourceUnavailable,
            ),
            ("unfunded", ProverState::Unfunded),
            ("feeBudgetExhausted", ProverState::FeeBudgetExhausted),
            ("entrySetFull", ProverState::EntrySetFull),
            ("paused", ProverState::Paused),
            ("stopped", ProverState::Stopped),
        ];
        assert_eq!(known.len(), 9, "the SPEC §2.3 set has exactly nine members");
        for (wire, variant) in known {
            let got: ProverState = serde_json::from_value(json!(wire)).unwrap();
            assert_eq!(got, variant, "{wire}");
            assert_eq!(serde_json::to_value(variant).unwrap(), json!(wire));
        }

        let err = serde_json::from_value::<ProverState>(json!("somethingElse"));
        assert!(
            err.is_err(),
            "an unknown ProverState string must be rejected"
        );
    }

    /// **Proves:** `GetRewardProverStatusParams` / `GetRewardProverStatusResult`
    /// round-trip, and the statuses half is a `Half`.
    #[test]
    fn get_reward_prover_status_types_round_trip() {
        let params = GetRewardProverStatusParams {
            launcher_id: Some("ab".repeat(32)),
        };
        let back: GetRewardProverStatusParams =
            serde_json::from_str(&serde_json::to_string(&params).unwrap()).unwrap();
        assert_eq!(params, back);

        let result = GetRewardProverStatusResult {
            statuses: Half::Consulted {
                observed_at: 1_700,
                items: vec![sample_prover_status()],
            },
        };
        let back: GetRewardProverStatusResult =
            serde_json::from_str(&serde_json::to_string(&result).unwrap()).unwrap();
        assert_eq!(result, back);
    }

    /// **Proves:** "this node runs no prover loops" and "this node could not
    /// read its prover registry" are DIFFERENT wire payloads, each dated.
    /// **Catches:** `GetRewardProverStatusResult.statuses` reverting to a bare
    /// `Vec`, where an unreadable registry renders as a confident "none" on a
    /// reward surface.
    #[test]
    fn unconsulted_prover_registry_is_distinguishable_from_an_empty_one() {
        let not_consulted = GetRewardProverStatusResult {
            statuses: Half::NotConsulted { observed_at: 1_700 },
        };
        let consulted_and_empty = GetRewardProverStatusResult {
            statuses: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
        };

        let a = serde_json::to_value(&not_consulted).unwrap();
        let b = serde_json::to_value(&consulted_and_empty).unwrap();
        assert_ne!(
            a, b,
            "an unread prover registry must not serialise as an empty one"
        );
        assert_eq!(a["statuses"]["outcome"], "not_consulted");
        assert_eq!(a["statuses"]["observed_at"], 1_700);
        assert_eq!(b["statuses"]["outcome"], "consulted");
        assert_eq!(b["statuses"]["observed_at"], 1_700);

        let back: GetRewardProverStatusResult = serde_json::from_value(a).unwrap();
        assert_eq!(back, not_consulted);
        let back: GetRewardProverStatusResult = serde_json::from_value(b).unwrap();
        assert_eq!(back, consulted_and_empty);
    }

    /// **Proves:** `ListRewardDistributorsResult` round-trips and its JSON keys
    /// are exactly `funded` / `claimable`, each a `Half` object carrying its own
    /// `outcome`, `observed_at` and `items` (SPEC §2.6, §12.5 clause 6).
    #[test]
    fn list_reward_distributors_result_round_trips_with_exact_keys() {
        let result = ListRewardDistributorsResult {
            funded: Half::Consulted {
                observed_at: 1_700,
                items: vec![RewardDistributorRef {
                    launcher_id: "11".repeat(32),
                    store_id: "22".repeat(32),
                    root: "33".repeat(32),
                }],
            },
            claimable: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
        };
        let value = serde_json::to_value(&result).unwrap();
        assert_eq!(sorted_keys(&value), vec!["claimable", "funded"]);
        assert_eq!(
            sorted_keys(&value["funded"]),
            vec!["items", "observed_at", "outcome"],
            "a half must carry its items INSIDE the tagged observation"
        );

        let back: ListRewardDistributorsResult = serde_json::from_value(value).unwrap();
        assert_eq!(result, back);
    }

    /// **Proves:** "the mirror-claim half was not consulted" and "it was
    /// consulted and is empty" are DIFFERENT wire payloads — the whole point of
    /// SPEC §12.5 clause 6. Both carry an `observed_at`, so neither is a bare,
    /// undated zero.
    /// **Catches:** the dated absence collapsing back into a plain empty vector,
    /// which is how a funder-only answer came to read as "you have no mirror
    /// claims".
    #[test]
    fn unconsulted_claimable_half_is_distinguishable_from_an_empty_one() {
        let not_consulted = ListRewardDistributorsResult {
            funded: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
            claimable: Half::NotConsulted { observed_at: 1_700 },
        };
        let consulted_and_empty = ListRewardDistributorsResult {
            claimable: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
            ..not_consulted.clone()
        };

        let a = serde_json::to_value(&not_consulted).unwrap();
        let b = serde_json::to_value(&consulted_and_empty).unwrap();
        assert_ne!(
            a, b,
            "an unconsulted half must not serialise as an empty one"
        );
        assert_eq!(a["claimable"]["outcome"], "not_consulted");
        assert_eq!(a["claimable"]["observed_at"], 1_700);
        assert_eq!(b["claimable"]["outcome"], "consulted");

        let back: ListRewardDistributorsResult = serde_json::from_value(a).unwrap();
        assert_eq!(back, not_consulted);
    }

    /// **Proves:** "this node's funded half was not consulted" and "it was
    /// consulted and is empty" are DIFFERENT wire payloads, each dated, exactly
    /// as for the mirror-claim half (SPEC §12.5 clause 6).
    /// **Catches:** a node that cannot read its own funder registry -- not
    /// configured, persisted state corrupt, or the read failed -- reporting an
    /// empty funded list, which states that the operator funds nothing.
    #[test]
    fn unconsulted_funded_half_is_distinguishable_from_an_empty_one() {
        let not_consulted = ListRewardDistributorsResult {
            funded: Half::NotConsulted { observed_at: 1_700 },
            claimable: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
        };
        let consulted_and_empty = ListRewardDistributorsResult {
            funded: Half::Consulted {
                observed_at: 1_700,
                items: vec![],
            },
            ..not_consulted.clone()
        };

        let a = serde_json::to_value(&not_consulted).unwrap();
        let b = serde_json::to_value(&consulted_and_empty).unwrap();
        assert_ne!(
            a, b,
            "an unconsulted funded half must not serialise as an empty one"
        );
        assert_eq!(a["funded"]["outcome"], "not_consulted");
        assert_eq!(a["funded"]["observed_at"], 1_700);
        assert_eq!(b["funded"]["outcome"], "consulted");
        assert_eq!(b["funded"]["observed_at"], 1_700);

        let back: ListRewardDistributorsResult = serde_json::from_value(a).unwrap();
        assert_eq!(back, not_consulted);
        let back: ListRewardDistributorsResult = serde_json::from_value(b).unwrap();
        assert_eq!(back, consulted_and_empty);
    }

    /// **Proves:** "nothing looked, and here are the results" is UNREPRESENTABLE
    /// — in Rust, because [`Half::NotConsulted`] has no `items` field at all; and
    /// on the wire, because the arm denies unknown fields, so a producer that
    /// emits both is a parse ERROR rather than having its items silently dropped.
    /// **Catches:** the observation drifting back out beside the collection,
    /// where only prose forbids the contradiction (dig_ecosystem#3269
    /// Condition 1).
    #[test]
    fn not_consulted_carrying_items_does_not_parse() {
        let contradiction = serde_json::json!({
            "outcome": "not_consulted",
            "observed_at": 1_700,
            "items": [{"launcher_id": "11".repeat(32),
                       "store_id": "22".repeat(32),
                       "root": "33".repeat(32)}],
        });
        assert!(
            serde_json::from_value::<Half<RewardDistributorRef>>(contradiction).is_err(),
            "\"not consulted, and here are the items\" must not parse"
        );
    }

    /// **Proves:** `Half` is fail-closed — an unknown outcome, or one missing its
    /// `observed_at`, is a parse ERROR, never a silently coerced "consulted" (the
    /// `ProverState` discipline, SPEC §12.5 clause 6's ban on an undated absence).
    #[test]
    fn half_rejects_unknown_and_undated_outcomes() {
        let unknown = serde_json::json!({"outcome": "maybe", "observed_at": 1, "items": []});
        assert!(serde_json::from_value::<Half<RewardDistributorRef>>(unknown).is_err());

        let undated = serde_json::json!({"outcome": "not_consulted"});
        assert!(serde_json::from_value::<Half<RewardDistributorRef>>(undated).is_err());

        let undated_consulted = serde_json::json!({"outcome": "consulted", "items": []});
        assert!(serde_json::from_value::<Half<RewardDistributorRef>>(undated_consulted).is_err());

        // A half that says it looked owes an answer, even an empty one.
        let itemless = serde_json::json!({"outcome": "consulted", "observed_at": 1});
        assert!(serde_json::from_value::<Half<RewardDistributorRef>>(itemless).is_err());
    }

    /// **Proves:** [`Half::items`] distinguishes "consulted, none" (`Some(&[])`)
    /// from "not consulted" (`None`), and [`Half::observed_at`] answers in both
    /// arms — so a consumer never has to re-match to get a staleness anchor.
    #[test]
    fn half_accessors_keep_the_distinction() {
        let consulted: Half<RewardDistributorRef> = Half::Consulted {
            observed_at: 1_700,
            items: vec![],
        };
        let not_consulted: Half<RewardDistributorRef> = Half::NotConsulted { observed_at: 1_701 };
        assert_eq!(consulted.items().map(<[_]>::len), Some(0));
        assert!(not_consulted.items().is_none());
        assert_eq!(consulted.observed_at(), 1_700);
        assert_eq!(not_consulted.observed_at(), 1_701);
    }

    /// A `ListRewardDistributorsResult` body with every key present, so a test
    /// can delete exactly one and assert the deletion is what broke it.
    fn full_list_reward_distributors_body() -> serde_json::Value {
        serde_json::json!({
            "funded": {"outcome": "consulted", "observed_at": 1_700, "items": []},
            "claimable": {"outcome": "consulted", "observed_at": 1_700, "items": []},
        })
    }

    /// **Proves:** omitting `funded` -- or `claimable` -- is a PARSE ERROR, not a
    /// default, while the same body with both keys present parses. Neither half
    /// may be silently assumed consulted.
    /// **Catches:** `#[serde(default)]` (or a re-derived `Default`) being added
    /// as a compatibility convenience, which would make every legacy payload
    /// parse as "both halves consulted" -- the undated bare zero SPEC §12.5
    /// clause 6 forbids.
    #[test]
    fn omitting_either_half_is_a_parse_error() {
        serde_json::from_value::<ListRewardDistributorsResult>(full_list_reward_distributors_body())
            .expect("the complete body must parse, or the omission assertions prove nothing");

        for omitted in ["funded", "claimable"] {
            let mut body = full_list_reward_distributors_body();
            body.as_object_mut().unwrap().remove(omitted).unwrap();
            assert!(
                serde_json::from_value::<ListRewardDistributorsResult>(body).is_err(),
                "omitting {omitted} must fail to parse, never default to consulted"
            );
        }
    }

    /// **Proves:** `PayeeClaimStatus` carries the literal `"subject": "payee"`
    /// and a claim-log observation — and NO monetary field and no payout puzzle
    /// hash (dig_ecosystem#3269).
    /// **Catches:** an amount or a payment identity creeping back onto the payee
    /// payload, which is the shape that let a funder's total render as one
    /// operator's personal earnings.
    #[test]
    fn payee_claim_status_names_its_subject_and_carries_no_money() {
        let status = PayeeClaimStatus {
            subject: PayeeSubject::Payee,
            claim_log: ClaimLogObservation::Consulted {
                observed_at: 1_700,
                claims_submitted_count: 3,
            },
            claim_loop: ClaimLoopObservation::Consulted {
                observed_at: 1_690,
                distributors_known: 4,
                distributors_claimable: 2,
                state: ClaimLoopState::ClaimableButNotClaiming {
                    claimable: 2,
                    submitted: 0,
                },
            },
        };
        let value = serde_json::to_value(status).unwrap();
        assert_eq!(value["subject"], "payee");
        assert_eq!(
            sorted_keys(&value),
            vec!["claim_log", "claim_loop", "subject"],
            "PayeeClaimStatus gained a field -- if it names money or a payee's \
             payment identity, it must not ship"
        );
        assert_eq!(
            sorted_keys(&value["claim_log"]),
            vec!["claims_submitted_count", "observed_at", "outcome"],
            "the claim log gained a field -- the same money rule applies inside it"
        );
        assert_eq!(
            sorted_keys(&value["claim_loop"]),
            vec![
                "distributors_claimable",
                "distributors_known",
                "observed_at",
                "outcome",
                "state",
            ],
            "the claim loop's consulted arm gained a field -- the same money rule \
             applies inside it"
        );

        let back: PayeeClaimStatus = serde_json::from_value(value).unwrap();
        assert_eq!(status, back);
    }

    /// **Proves:** every field of `PayeeClaimStatus` is REQUIRED on the wire —
    /// nothing defaults, so a producer cannot omit the subject and have a
    /// consumer invent it.
    #[test]
    fn payee_claim_status_fields_do_not_default() {
        let full = || {
            serde_json::json!({
                "subject": "payee",
                "claim_log": {
                    "outcome": "consulted",
                    "observed_at": 1_700,
                    "claims_submitted_count": 3,
                },
                "claim_loop": {
                    "outcome": "consulted",
                    "observed_at": 1_690,
                    "distributors_known": 4,
                    "distributors_claimable": 2,
                    "state": { "kind": "nominal" },
                },
            })
        };
        serde_json::from_value::<PayeeClaimStatus>(full())
            .expect("the complete body must parse, or the omission assertions prove nothing");

        for missing in ["subject", "claim_log", "claim_loop"] {
            let mut value = full();
            value.as_object_mut().unwrap().remove(missing).unwrap();
            assert!(
                serde_json::from_value::<PayeeClaimStatus>(value).is_err(),
                "{missing} must be required"
            );
        }

        let wrong_subject = serde_json::json!({
            "subject": "funder",
            "claim_log": {
                "outcome": "consulted",
                "observed_at": 1_700,
                "claims_submitted_count": 3,
            },
            "claim_loop": {
                "outcome": "consulted",
                "observed_at": 1_690,
                "distributors_known": 4,
                "distributors_claimable": 2,
                "state": { "kind": "nominal" },
            },
        });
        assert!(
            serde_json::from_value::<PayeeClaimStatus>(wrong_subject).is_err(),
            "only the literal \"payee\" subject may parse into PayeeClaimStatus"
        );
    }

    /// **Proves:** a node that never read its claim log cannot emit a count at
    /// all — there is no field for one in `not_consulted`, and a payload that
    /// carries one anyway is a parse ERROR. "Consulted and zero" and "never
    /// looked" are different, dated payloads.
    /// **Catches:** dig_ecosystem#3269 Condition 3 — a freshly dated
    /// `claims_submitted_count: 0` emitted by a node whose log was unreadable,
    /// which is SPEC §12.5 clause 6's reassuring zero with a timestamp on it.
    #[test]
    fn an_unread_claim_log_cannot_report_a_count() {
        let unread = PayeeClaimStatus {
            subject: PayeeSubject::Payee,
            claim_log: ClaimLogObservation::NotConsulted { observed_at: 1_700 },
            claim_loop: ClaimLoopObservation::NotConsulted { observed_at: 1_700 },
        };
        let read_and_zero = PayeeClaimStatus {
            subject: PayeeSubject::Payee,
            claim_log: ClaimLogObservation::Consulted {
                observed_at: 1_700,
                claims_submitted_count: 0,
            },
            claim_loop: ClaimLoopObservation::NotConsulted { observed_at: 1_700 },
        };

        let a = serde_json::to_value(unread).unwrap();
        let b = serde_json::to_value(read_and_zero).unwrap();
        assert_ne!(a, b, "an unread claim log must not serialise as a zero one");
        assert_eq!(a["claim_log"]["outcome"], "not_consulted");
        assert_eq!(a["claim_log"]["observed_at"], 1_700);
        assert!(
            a["claim_log"].get("claims_submitted_count").is_none(),
            "an unread log has no count to give"
        );
        assert_eq!(b["claim_log"]["claims_submitted_count"], 0);

        let contradiction = serde_json::json!({
            "outcome": "not_consulted",
            "observed_at": 1_700,
            "claims_submitted_count": 0,
        });
        assert!(
            serde_json::from_value::<ClaimLogObservation>(contradiction).is_err(),
            "\"never looked, and the count is zero\" must not parse"
        );

        let undated = serde_json::json!({"outcome": "not_consulted"});
        assert!(serde_json::from_value::<ClaimLogObservation>(undated).is_err());

        let countless = serde_json::json!({"outcome": "consulted", "observed_at": 1_700});
        assert!(
            serde_json::from_value::<ClaimLogObservation>(countless).is_err(),
            "a log that says it was read owes a count"
        );
    }

    /// A `PayeeClaimStatus` carrying a fully populated `claim_loop` for use as
    /// a base by the new-test fixtures below.
    fn claim_loop_fixture() -> serde_json::Value {
        serde_json::json!({
            "subject": "payee",
            "claim_log": {
                "outcome": "not_consulted",
                "observed_at": 1_700,
            },
            "claim_loop": {
                "outcome": "consulted",
                "observed_at": 1_690,
                "distributors_known": 4,
                "distributors_claimable": 2,
                "state": { "kind": "nominal" },
            },
        })
    }

    /// **Proves:** every one of the seven `ClaimLoopState` kinds round-trips
    /// through `PayeeClaimStatus` with exactly the keys SPEC §4.4.1 lists for
    /// its arm -- no more, no fewer. The two distributor counts parse from their
    /// correctly-named JSON keys: swapping `distributors_known` and
    /// `distributors_claimable` on the wire changes the parsed values.
    #[test]
    fn every_claim_loop_state_kind_round_trips_with_exact_keys() {
        let cases: Vec<(serde_json::Value, Vec<&str>)> = vec![
            (serde_json::json!({"kind": "idle"}), vec!["kind"]),
            (
                serde_json::json!({"kind": "chain_source_unavailable"}),
                vec!["kind"],
            ),
            (
                serde_json::json!({"kind": "persisted_state_corrupt"}),
                vec!["kind"],
            ),
            (
                serde_json::json!({"kind": "cadence_not_elapsed"}),
                vec!["kind"],
            ),
            (serde_json::json!({"kind": "nominal"}), vec!["kind"]),
            (
                serde_json::json!({"kind": "faulted", "cycles": 3}),
                vec!["cycles", "kind"],
            ),
            (
                serde_json::json!({
                    "kind": "claimable_but_not_claiming",
                    "claimable": 2,
                    "submitted": 0,
                }),
                vec!["claimable", "kind", "submitted"],
            ),
        ];

        // Pin the wire names to their field bindings: a transposition on the
        // wire would silently invert the counts.
        let parsed: PayeeClaimStatus = serde_json::from_value(claim_loop_fixture()).unwrap();
        assert!(
            matches!(
                parsed.claim_loop,
                ClaimLoopObservation::Consulted { distributors_known: 4, distributors_claimable: 2, .. }
            ),
            "distributors_known must parse from the `distributors_known` key and \
             distributors_claimable from `distributors_claimable`; a swap must not parse into the same value"
        );

        for (state, expected_keys) in cases {
            let mut body = claim_loop_fixture();
            body["claim_loop"]["state"] = state.clone();
            assert_eq!(
                sorted_keys(&state),
                expected_keys,
                "state {state:?} does not carry its SPEC section 4.4.1 key set"
            );
            let parsed: PayeeClaimStatus = serde_json::from_value(body).unwrap_or_else(|e| {
                panic!("state {state:?} must round-trip, got {e}");
            });
            let back = serde_json::to_value(parsed).unwrap();
            assert_eq!(
                sorted_keys(&back["claim_loop"]["state"]),
                expected_keys,
                "state {state:?} changed shape across a round trip"
            );
        }
    }

    /// **Proves:** every one of `claim_loop.consulted`'s five keys is
    /// REQUIRED -- removing any one is a parse error, never a default.
    #[test]
    fn claim_loop_consulted_fields_do_not_default() {
        for missing in [
            "outcome",
            "observed_at",
            "distributors_known",
            "distributors_claimable",
            "state",
        ] {
            let mut body = claim_loop_fixture();
            body["claim_loop"].as_object_mut().unwrap().remove(missing);
            assert!(
                serde_json::from_value::<PayeeClaimStatus>(body).is_err(),
                "claim_loop.consulted must require {missing}"
            );
        }
    }

    /// **Proves:** a `ClaimLoopState` payload is rejected for an unknown
    /// `kind`, for a bare-string `state`, for `faulted` missing `cycles`, for
    /// `claimable_but_not_claiming` missing `submitted`, and for an unknown
    /// key riding beside a `faulted` payload.
    #[test]
    fn claim_loop_state_rejects_malformed_and_unknown_payloads() {
        let reject = |state: serde_json::Value, why: &str| {
            let mut body = claim_loop_fixture();
            body["claim_loop"]["state"] = state;
            assert!(
                serde_json::from_value::<PayeeClaimStatus>(body).is_err(),
                "{why}"
            );
        };

        reject(
            serde_json::json!({"kind": "not_a_real_state"}),
            "an unknown kind must not parse, never coerce to idle",
        );
        reject(
            serde_json::json!("idle"),
            "state must always be an object, never a bare string",
        );
        reject(
            serde_json::json!({"kind": "faulted"}),
            "faulted without cycles must not parse",
        );
        reject(
            serde_json::json!({"kind": "claimable_but_not_claiming", "claimable": 2}),
            "claimable_but_not_claiming without submitted must not parse",
        );
        reject(
            serde_json::json!({"kind": "faulted", "cycles": 3, "extra": 1}),
            "an unknown key beside a faulted payload must not parse",
        );
    }

    /// **Proves:** `claim_loop.not_consulted` carries no count and no state --
    /// a count or a verdict cannot ride an arm that says nothing was read.
    #[test]
    fn claim_loop_not_consulted_rejects_every_count_and_state_key() {
        let base_not_consulted = || {
            serde_json::json!({
                "outcome": "not_consulted",
                "observed_at": 1_700,
            })
        };

        for (key, value) in [
            ("distributors_known", serde_json::json!(0)),
            ("distributors_claimable", serde_json::json!(0)),
            ("state", serde_json::json!({"kind": "idle"})),
        ] {
            let mut claim_loop = base_not_consulted();
            claim_loop
                .as_object_mut()
                .unwrap()
                .insert(key.to_string(), value);
            let mut body = claim_loop_fixture();
            body["claim_loop"] = claim_loop;
            assert!(
                serde_json::from_value::<PayeeClaimStatus>(body).is_err(),
                "not_consulted must reject a stray {key}"
            );
        }
    }

    /// **Proves:** the anti-silence rule (SPEC section 4.4.4) actually holds
    /// on the wire -- a consumer reading ONLY `claim_loop.state.kind` from
    /// the serialised JSON can tell "running, not paying everybody" apart
    /// from "nothing to do", without touching the Rust enum. Each distributor
    /// count rides under its own wire key: swapping `distributors_known`
    /// and `distributors_claimable` field names changes the JSON values.
    /// **Catches:** a producer that folds `claimable_but_not_claiming` into
    /// `nominal` or `idle`, which is the exact silence this method exists to
    /// remove.
    #[test]
    fn claimable_but_not_claiming_is_distinguishable_from_idle_by_json_alone() {
        let running_and_shortfalling = PayeeClaimStatus {
            subject: PayeeSubject::Payee,
            claim_log: ClaimLogObservation::NotConsulted { observed_at: 1_700 },
            claim_loop: ClaimLoopObservation::Consulted {
                observed_at: 1_690,
                distributors_known: 4,
                distributors_claimable: 2,
                state: ClaimLoopState::ClaimableButNotClaiming {
                    claimable: 2,
                    submitted: 0,
                },
            },
        };
        let nothing_to_do = PayeeClaimStatus {
            subject: PayeeSubject::Payee,
            claim_log: ClaimLogObservation::NotConsulted { observed_at: 1_700 },
            claim_loop: ClaimLoopObservation::Consulted {
                observed_at: 1_690,
                distributors_known: 0,
                distributors_claimable: 0,
                state: ClaimLoopState::Idle,
            },
        };

        let a = serde_json::to_value(running_and_shortfalling).unwrap();
        let b = serde_json::to_value(nothing_to_do).unwrap();

        // The two counts an operator compares must each ride under its OWN
        // key: a transposition on the wire would invert "known" and
        // "claimable" and every other assertion here would still pass.
        assert_eq!(a["claim_loop"]["distributors_known"], 4);
        assert_eq!(a["claim_loop"]["distributors_claimable"], 2);

        let a_kind = a["claim_loop"]["state"]["kind"].as_str().unwrap();
        let b_kind = b["claim_loop"]["state"]["kind"].as_str().unwrap();

        assert_ne!(
            a_kind, b_kind,
            "a loop that is running and shortfalling must not read the same as one \
             with nothing to do, from the JSON alone"
        );
        assert_eq!(a_kind, "claimable_but_not_claiming");
    }

    /// **Proves:** an unknown top-level key on `PayeeClaimStatus` is a parse
    /// error, per `deny_unknown_fields` (new in 0.13.0).
    #[test]
    fn payee_claim_status_rejects_an_unknown_top_level_key() {
        let mut body = claim_loop_fixture();
        body.as_object_mut()
            .unwrap()
            .insert("amount".to_string(), serde_json::json!(5));
        assert!(
            serde_json::from_value::<PayeeClaimStatus>(body).is_err(),
            "an unknown top-level key must not parse"
        );
    }

    /// **Proves:** `GetRewardDistributorResult` round-trips, and `entry_set_stale`
    /// IS present on this chain-derived type (contrast `RewardProverStatus`,
    /// which must never carry it — SPEC §12.4 vs §2.4).
    #[test]
    fn get_reward_distributor_result_round_trips_and_carries_entry_set_stale() {
        let params = GetRewardDistributorParams {
            launcher_id: "ab".repeat(32),
        };
        let back: GetRewardDistributorParams =
            serde_json::from_str(&serde_json::to_string(&params).unwrap()).unwrap();
        assert_eq!(params, back);

        let result = GetRewardDistributorResult {
            launcher_id: "ab".repeat(32),
            store_id: "cd".repeat(32),
            root: "ef".repeat(32),
            epoch_seconds: 86_400,
            first_epoch_start: 1_000,
            payout_threshold: 500_000,
            fee_bps: 250,
            withdrawal_share_bps: 9_000,
            reserve_base_units: 1_000_000,
            entry_count: 42,
            current_distributor_epoch: 7,
            last_entry_write_at: Some(1_650),
            entry_set_stale: true,
            observed_at: 1_700,
            chain_peak_height: 12_345,
            chain_peak_timestamp: 1_690,
        };
        let value = serde_json::to_value(&result).unwrap();
        assert_eq!(value["entry_set_stale"], true);
        let back: GetRewardDistributorResult = serde_json::from_value(value).unwrap();
        assert_eq!(result, back);
    }

    /// **Proves:** `entry_set_stale` is placed on exactly one of the two
    /// reward-distributor result types — present on the chain-derived
    /// `GetRewardDistributorResult`, absent from the self-reported
    /// `RewardProverStatus` — SPEC §12.4 vs §2.4.
    /// **Catches:** the staleness boolean migrating (or being copy-pasted)
    /// onto the self-reported type, which would let a wedged prover fake
    /// liveness by simply never flipping it.
    #[test]
    fn entry_set_stale_is_placed_on_the_chain_derived_result_only() {
        let prover_status = serde_json::to_value(sample_prover_status()).unwrap();
        assert!(
            !prover_status
                .as_object()
                .unwrap()
                .contains_key("entry_set_stale"),
            "RewardProverStatus must never carry entry_set_stale (SPEC §2.4)"
        );

        let distributor_result = GetRewardDistributorResult {
            launcher_id: "ab".repeat(32),
            store_id: "cd".repeat(32),
            root: "ef".repeat(32),
            epoch_seconds: 86_400,
            first_epoch_start: 1_000,
            payout_threshold: 500_000,
            fee_bps: 250,
            withdrawal_share_bps: 9_000,
            reserve_base_units: 1_000_000,
            entry_count: 42,
            current_distributor_epoch: 7,
            last_entry_write_at: None,
            entry_set_stale: false,
            observed_at: 1_700,
            chain_peak_height: 12_345,
            chain_peak_timestamp: 1_690,
        };
        let value = serde_json::to_value(&distributor_result).unwrap();
        assert!(
            value.as_object().unwrap().contains_key("entry_set_stale"),
            "GetRewardDistributorResult must carry entry_set_stale (SPEC §12.4)"
        );
    }

    /// **Proves:** `GetRewardProverStatusParams` with an absent `launcher_id`
    /// deserializes from an empty JSON object to `None` — the field is
    /// genuinely optional on the wire, not merely optional in Rust.
    #[test]
    fn get_reward_prover_status_params_absent_launcher_id_is_none() {
        let parsed: GetRewardProverStatusParams = serde_json::from_value(json!({})).unwrap();
        assert_eq!(parsed.launcher_id, None);

        // And the round trip the other way: `Some` serializes the key back out.
        let with_id = GetRewardProverStatusParams {
            launcher_id: Some("ab".repeat(32)),
        };
        let value = serde_json::to_value(&with_id).unwrap();
        assert_eq!(value["launcher_id"], json!("ab".repeat(32)));
    }

    /// **Proves:** `ListRewardDistributorCommitmentsResult` round-trips,
    /// including the legitimate EMPTY `commitments` case (a distributor
    /// funded only via `AddIncentives` has no clawback slots at all — an
    /// irrevocable donation, not an error) — SPEC §7.4 clause 5.
    #[test]
    fn list_reward_distributor_commitments_round_trips_with_empty_commitments() {
        let params = ListRewardDistributorCommitmentsParams {
            launcher_id: "ab".repeat(32),
        };
        let back: ListRewardDistributorCommitmentsParams =
            serde_json::from_str(&serde_json::to_string(&params).unwrap()).unwrap();
        assert_eq!(params, back);

        let result = ListRewardDistributorCommitmentsResult {
            launcher_id: "ab".repeat(32),
            withdrawal_share_bps: 9_000,
            epoch_seconds: 86_400,
            commitments: vec![],
            observed_at: 1_700,
            chain_peak_height: 12_345,
            chain_peak_timestamp: 1_690,
        };
        let back: ListRewardDistributorCommitmentsResult =
            serde_json::from_str(&serde_json::to_string(&result).unwrap()).unwrap();
        assert_eq!(result, back);
        assert_eq!(back.epoch_seconds, 86_400);
    }

    /// A full `GetRewardDistributorResult` body, as JSON, with the chain-view
    /// anchor fields included. Kept as one JSON literal (not a struct literal)
    /// so this helper compiles whether or not `chain_peak_height` /
    /// `chain_peak_timestamp` exist on the struct yet — the RED phase for
    /// ticket #3262 depends on that.
    fn get_reward_distributor_result_body_with_anchor() -> serde_json::Value {
        json!({
            "launcher_id": "ab".repeat(32),
            "store_id": "cd".repeat(32),
            "root": "ef".repeat(32),
            "epoch_seconds": 86_400,
            "first_epoch_start": 1_000,
            "payout_threshold": 500_000,
            "fee_bps": 250,
            "withdrawal_share_bps": 9_000,
            "reserve_base_units": 1_000_000,
            "entry_count": 42,
            "current_distributor_epoch": 7,
            "last_entry_write_at": 1_650,
            "entry_set_stale": true,
            "observed_at": 1_700,
            "chain_peak_height": 12_345,
            "chain_peak_timestamp": 1_690,
        })
    }

    /// **Proves:** a `GetRewardDistributorResult` body without
    /// `chain_peak_height` / `chain_peak_timestamp` is a parse ERROR (the
    /// pre-0.14.0, 0.12.0-shaped wire body must not parse once the anchor is
    /// required), and the same body WITH both keys round-trips carrying
    /// exactly the expected key set — SPEC §4.5, dig_ecosystem#3262.
    /// **Catches:** `#[serde(default)]` / `Option` on either field, which
    /// would let the missing-key body parse silently.
    #[test]
    fn get_reward_distributor_result_refuses_a_body_without_its_chain_anchor() {
        let mut body = get_reward_distributor_result_body_with_anchor();
        body.as_object_mut()
            .unwrap()
            .remove("chain_peak_height")
            .unwrap();
        body.as_object_mut()
            .unwrap()
            .remove("chain_peak_timestamp")
            .unwrap();
        assert!(
            serde_json::from_value::<GetRewardDistributorResult>(body).is_err(),
            "a GetRewardDistributorResult body missing the chain-view anchor \
             must not parse -- SPEC §4.5 requires both fields"
        );

        let full_body = get_reward_distributor_result_body_with_anchor();
        let parsed: GetRewardDistributorResult =
            serde_json::from_value(full_body).expect("a body carrying both anchor keys must parse");
        let value = serde_json::to_value(&parsed).unwrap();
        assert_eq!(
            sorted_keys(&value),
            vec![
                "chain_peak_height",
                "chain_peak_timestamp",
                "current_distributor_epoch",
                "entry_count",
                "entry_set_stale",
                "epoch_seconds",
                "fee_bps",
                "first_epoch_start",
                "last_entry_write_at",
                "launcher_id",
                "observed_at",
                "payout_threshold",
                "reserve_base_units",
                "root",
                "store_id",
                "withdrawal_share_bps",
            ],
            "GetRewardDistributorResult must carry exactly these keys, including \
             the chain-view anchor"
        );
    }

    /// A full `ListRewardDistributorCommitmentsResult` body, as JSON, with the
    /// chain-view anchor fields included. See
    /// [`get_reward_distributor_result_body_with_anchor`] for why this is JSON
    /// rather than a struct literal.
    fn list_reward_distributor_commitments_result_body_with_anchor() -> serde_json::Value {
        json!({
            "launcher_id": "ab".repeat(32),
            "withdrawal_share_bps": 9_000,
            "epoch_seconds": 86_400,
            "commitments": [],
            "observed_at": 1_700,
            "chain_peak_height": 12_345,
            "chain_peak_timestamp": 1_690,
        })
    }

    /// **Proves:** a `ListRewardDistributorCommitmentsResult` body without
    /// `chain_peak_height` / `chain_peak_timestamp` is a parse ERROR, and the
    /// same body WITH both keys round-trips carrying exactly the expected key
    /// set — SPEC §4.5, dig_ecosystem#3262 (sibling of the
    /// `GetRewardDistributorResult` test above).
    #[test]
    fn list_reward_distributor_commitments_result_refuses_a_body_without_its_chain_anchor() {
        let mut body = list_reward_distributor_commitments_result_body_with_anchor();
        body.as_object_mut()
            .unwrap()
            .remove("chain_peak_height")
            .unwrap();
        body.as_object_mut()
            .unwrap()
            .remove("chain_peak_timestamp")
            .unwrap();
        assert!(
            serde_json::from_value::<ListRewardDistributorCommitmentsResult>(body).is_err(),
            "a ListRewardDistributorCommitmentsResult body missing the chain-view \
             anchor must not parse -- SPEC §4.5 requires both fields"
        );

        let full_body = list_reward_distributor_commitments_result_body_with_anchor();
        let parsed: ListRewardDistributorCommitmentsResult =
            serde_json::from_value(full_body).expect("a body carrying both anchor keys must parse");
        let value = serde_json::to_value(&parsed).unwrap();
        assert_eq!(
            sorted_keys(&value),
            vec![
                "chain_peak_height",
                "chain_peak_timestamp",
                "commitments",
                "epoch_seconds",
                "launcher_id",
                "observed_at",
                "withdrawal_share_bps",
            ],
            "ListRewardDistributorCommitmentsResult must carry exactly these keys, \
             including the chain-view anchor"
        );
    }

    /// **Proves:** `observed_at` (wall clock of reply assembly) and
    /// `chain_peak_timestamp` (chain clock `entry_set_stale` is computed
    /// against) are DISTINCT fields that can hold different values — the
    /// whole point of the anchor is that one can be fresh while the other is
    /// stale (dig_ecosystem#3262).
    /// **Catches:** collapsing the two into one field, or deriving one from
    /// the other at serialization time.
    #[test]
    fn chain_peak_timestamp_and_observed_at_are_distinct_fields() {
        let mut body = get_reward_distributor_result_body_with_anchor();
        body["observed_at"] = json!(2_600u64);
        body["chain_peak_timestamp"] = json!(1_700u64);
        let parsed: GetRewardDistributorResult =
            serde_json::from_value(body).expect("full body must parse");
        let value = serde_json::to_value(&parsed).unwrap();
        assert_eq!(value["observed_at"], json!(2_600u64));
        assert_eq!(value["chain_peak_timestamp"], json!(1_700u64));
        assert_ne!(
            value["observed_at"], value["chain_peak_timestamp"],
            "observed_at (wall clock) and chain_peak_timestamp (chain clock) \
             must be able to disagree -- a stalled chain source freezes the \
             latter while the former keeps advancing"
        );
    }

    /// **Proves:** `recoverable_base_units` is `rewards_base_units *
    /// withdrawal_share_bps / 10_000`, computed with integer arithmetic
    /// (multiply then divide) that TRUNCATES rather than rounds up — SPEC
    /// §7.4 clause 4 / §7.5.
    /// **Catches:** a rounded-up recoverable amount, which would promise
    /// money the chain will not return on clawback.
    #[test]
    fn commitment_recoverable_amount_truncates_and_never_exceeds_committed() {
        let withdrawal_share_bps: u64 = 9_000;

        // Evenly divisible: 1_000 * 9000 / 10000 = 900.
        let even = RewardDistributorCommitment {
            epoch_start: 10,
            clawback_puzzle_hash: "aa".repeat(32),
            rewards_base_units: 1_000,
            recoverable_base_units: 1_000 * withdrawal_share_bps / 10_000,
        };
        assert_eq!(even.recoverable_base_units, 900);

        // Not evenly divisible: 1_001 * 9000 / 10000 = 900.9 -> 900, not 901.
        let odd = RewardDistributorCommitment {
            epoch_start: 11,
            clawback_puzzle_hash: "bb".repeat(32),
            rewards_base_units: 1_001,
            recoverable_base_units: 1_001 * withdrawal_share_bps / 10_000,
        };
        assert_eq!(
            odd.recoverable_base_units, 900,
            "a non-evenly-divisible amount must truncate down, never round up"
        );

        for commitment in [even, odd] {
            assert!(
                commitment.recoverable_base_units <= commitment.rewards_base_units,
                "recoverable_base_units must never exceed rewards_base_units"
            );
        }
    }
}