decdn_common/config/

resolved.rs

//! Fully resolved configuration with concrete types.
//!
//! Most fields are non-optional. `region` remains `Option` because it has no
//! universal default; `relay_urls` is a (possibly empty) list — empty means
//! "fall back to the n0 default relays".

use std::collections::HashSet;
use std::path::PathBuf;

use alloy::primitives::Address;
use decdn_config_types::DeniedHashes;

use crate::cli::common::{LogFormat, LogLevel};

/// Resolved identity fields.
#[derive(Debug)]
pub struct ResolvedIdentity {
    /// Node data directory.
    pub data_dir: PathBuf,
    /// Region code (e.g. `"US"`).
    pub region: Option<String>,
}

/// Resolved network fields.
#[derive(Debug)]
pub struct ResolvedNetwork {
    /// QUIC bind port.
    pub bind_port: u16,
    /// iroh relay URLs for NAT traversal. Empty => use the n0 default relays;
    /// non-empty => swap in these self-hosted relays (`RelayMode::Custom`).
    /// Relay connectivity is logged after bring-up but never fatal: when no
    /// relay connects the node warns and proceeds (iroh retries in the
    /// background).
    pub relay_urls: Vec<String>,
    /// Operator-configurable address discovery (#818 scope 1). Empty
    /// ([`ResolvedDiscovery::is_empty`]) => the node keeps the n0-hosted
    /// pkarr/DNS default (`presets::N0`); otherwise the node builds on
    /// `presets::Minimal` and composes only the providers configured here.
    pub discovery: ResolvedDiscovery,
}

/// Resolved discovery providers (#818). Strings are already shape-validated at
/// resolution (`pkarr_url` a parseable URL, `dns_origin` non-empty, each peer
/// `node_id` a valid iroh `NodeId`, each `addr` a `SocketAddr`); the node wiring
/// layer parses them into iroh types — the discovery-provider seam, per
/// `adr/appendix-poc-production-seams.md`.
#[derive(Debug, Default, Clone)]
pub struct ResolvedDiscovery {
    /// pkarr relay URL to publish this node's address record to.
    pub pkarr_url: Option<String>,
    /// DNS origin domain to resolve peers from.
    pub dns_origin: Option<String>,
    /// Static peer address book, sorted by `node_id` for a deterministic build.
    pub peers: Vec<ResolvedDiscoveryPeer>,
}

impl ResolvedDiscovery {
    /// No discovery overrides configured => the node uses `presets::N0`.
    pub const fn is_empty(&self) -> bool {
        self.pkarr_url.is_none() && self.dns_origin.is_none() && self.peers.is_empty()
    }
}

/// One resolved static peer ([`ResolvedDiscovery::peers`]).
#[derive(Debug, Clone)]
pub struct ResolvedDiscoveryPeer {
    /// Peer `NodeId` (the canonical 64-char lowercase-hex form; validated at
    /// resolution).
    pub node_id: String,
    /// Peer home relay URL, if configured.
    pub relay_url: Option<String>,
    /// Peer direct socket addresses (`host:port`).
    pub addrs: Vec<String>,
}

/// Resolved blockchain fields.
#[derive(Debug)]
pub struct ResolvedBlockchain {
    /// JSON-RPC endpoint URL.
    pub rpc_url: String,
    /// Ethereum keystore file path.
    pub eth_keystore: PathBuf,
    /// Optional path to a file holding the keystore password. CLI/env-only;
    /// not surfaced via the TOML schema (passwords don't belong in config
    /// files even by reference). The runtime first consults the
    /// `DECDN_KEYSTORE_PASSWORD` env var, then this file, then prompts on
    /// stdin if connected to a TTY. Each source is chosen by presence, so a
    /// set-but-empty env var and an empty file both mean an empty password.
    pub keystore_password_file: Option<PathBuf>,
    /// `PaymentPool` contract address — the shared payment pool this node
    /// registers against for buyer and seller flows alike.
    pub payment_pool_address: String,
    /// `CapacityBond` contract address.
    pub capacity_bond_address: String,
    /// `OriginAssignment` contract address. `Some` only when the operator opts
    /// into the chain-backed origin directory; `None` => empty directory, so
    /// the `FIND_VALUE` routing fallback (ADR 022) resolves nothing.
    pub origin_assignment_address: Option<String>,
    /// Positive-hit TTL for the lazy origin directory cache, in seconds: how
    /// long a resolved, non-empty `getOrigins(namespaceId)` set is served
    /// before a re-read. Defaults to
    /// [`super::DEFAULT_ORIGIN_DIRECTORY_POSITIVE_TTL_SEC`].
    pub origin_directory_positive_ttl_sec: u64,
    /// Negative-hit TTL for the lazy origin directory cache, in seconds: how
    /// long "this namespace has no origins / does not exist" is cached.
    /// Defaults to [`super::DEFAULT_ORIGIN_DIRECTORY_NEGATIVE_TTL_SEC`].
    pub origin_directory_negative_ttl_sec: u64,
    /// Max distinct namespaces held in the lazy origin directory cache (LRU
    /// eviction). Defaults to
    /// [`super::DEFAULT_ORIGIN_DIRECTORY_CACHE_CAPACITY`].
    pub origin_directory_cache_capacity: usize,
    /// `PublisherRegistry` contract address. Independent of the origin directory
    /// (the publish CLI's `namespace create` target); not consumed by the node.
    pub publisher_registry_address: Option<String>,
    /// `SlashJudge` contract address — the EIP-712 `verifyingContract` for
    /// `slash_sig` signatures (ADR 014). Required (no default).
    pub slash_judge_address: String,
    /// Required `ContentBlacklist` contract address (ADR 011/019/031). Successful
    /// node config resolution always produces `Some`; the runtime rejects `None`.
    pub content_blacklist_address: Option<String>,
    /// Seconds between the blacklist watcher's periodic replay + re-scope pass.
    /// Defaults to [`super::DEFAULT_CONTENT_BLACKLIST_POLL_INTERVAL_SEC`]. Only
    /// used when `content_blacklist_address` is set.
    pub content_blacklist_poll_interval_sec: u64,
    /// Seconds the node may go without a successful chain read before the serve
    /// and probe paths refuse (ADR 011 § Serving while chain-stale). Defaults to
    /// [`super::DEFAULT_CHAIN_STALENESS_GRACE_SEC`]. Always evaluated; a large
    /// value opts out. Only used when `content_blacklist_address` is set.
    pub chain_staleness_grace_sec: u64,
    /// EIP-712 `chainId` for the `slash_sig` domain separator. Defaults to
    /// [`super::DEFAULT_CHAIN_ID`] (Arbitrum Sepolia) when unset.
    pub chain_id: u64,
    /// Seconds between RPC connectivity watchdog probes. `0` disables the
    /// watchdog entirely; otherwise the resolver enforces a minimum (see
    /// `MIN_RPC_WATCHDOG_INTERVAL_SEC`).
    pub rpc_watchdog_interval_sec: u64,
    /// Milliseconds between chain-event poll ticks (#1011, #1106). Two unrelated
    /// consumers read this one value:
    /// - the `MultiplexedPoller`'s `poll_interval` — the `eth_getLogs` tick
    ///   cadence shared by every chain watcher's `Route`.
    /// - alloy's pending-transaction receipt heartbeat, applied to every provider
    ///   via the node's `with_poll_interval` (`client().set_poll_interval`) and
    ///   consumed by `PendingTransactionBuilder::get_receipt` when the node awaits
    ///   a mined settlement / pool tx. This is also what overrides alloy's
    ///   localhost-detected 250 ms default.
    ///
    /// Defaults to 7000 ms (`DEFAULT_EVENT_POLL_INTERVAL_MS`); the resolver
    /// enforces a minimum (see `MIN_EVENT_POLL_INTERVAL_MS`).
    pub event_poll_interval_ms: u64,
    /// Ceiling on the block span of one chain-watcher `eth_getLogs` request
    /// (the `MultiplexedPoller`'s window). The poller starts here. When the
    /// provider rejects a range, it sets its span to half the rejected window's
    /// length, and it doubles back toward this ceiling after a streak of
    /// accepted windows. Defaults to [`super::DEFAULT_GET_LOGS_MAX_BLOCK_SPAN`];
    /// always `>= 1`.
    pub get_logs_max_block_span: u64,
    /// Seconds between authoritative `FeeRouter.getShares()` re-reads by the
    /// fee-shares watcher (ADR 041 / ADR 016 § Tunable Economics). Safety-net
    /// cadence alongside the `SharesUpdated` event subscription. Defaults to
    /// 3600s (`DEFAULT_FEE_SHARES_POLL_INTERVAL_SEC`); the resolver rejects
    /// `0`.
    pub fee_shares_poll_interval_sec: u64,
    /// Per-chunk redemption floor (base units, `µUSDC`). The seller
    /// settlement path submits an on-chain redemption transaction for a
    /// chunk of lanes only once the aggregate un-redeemed value across that
    /// chunk's lanes reaches this floor; every lane in a submitted chunk
    /// settles. Defaults to 1 USDC (`1_000_000` `µUSDC`) when unset.
    pub redeem_threshold_micro_usdc: u64,
    /// Maximum vouchers per `redeemMany` transaction (the redemption chunk size).
    /// Defaults to `300` (`DEFAULT_REDEEM_MAX_VOUCHERS_PER_TX`); the resolver
    /// rejects `0`.
    pub redeem_max_vouchers_per_tx: u64,
    /// Seconds between the redeemer self-tick sweeps (#327, #751): the
    /// low-frequency backstop that sweeps every lane and redeems the chunks
    /// that clear the redemption floor, independent of the advisory per-voucher
    /// hints. Defaults to 300s
    /// (`DEFAULT_REDEEM_INTERVAL_SECS`); the resolver rejects `0`.
    pub redeem_interval_secs: u64,
    /// Deposit (base units, `µUSDC`) the buyer path escrows when it opens a
    /// pool, and the target every top-up restores the pool balance toward.
    /// Defaults to 10 USDC (`10_000_000`). Guaranteed nonzero (the resolver
    /// rejects `0`; the pool's `openPool` reverts on a zero deposit).
    pub buyer_working_deposit_micro_usdc: u64,
    /// Whether the buyer path issues a one-time max USDC approval for the
    /// `PaymentPool` contract at startup (#744, ADR 003 § Deposit
    /// Economics). Defaults to `true`; set `false` to manage the allowance
    /// out-of-band (e.g. a tighter per-pool approval policy).
    pub buyer_max_approve: bool,
    /// The node's refundable floor `M` (base units, `µUSDC`), sized per ADR
    /// 003 § Sizing (`M = k·ρ·B·Δ`). The node stops serving a pool once its
    /// remaining on-chain balance minus `M` can no longer cover the next
    /// credit window. Defaults to 1 USDC (`1_000_000` `µUSDC`).
    pub pool_min_remaining_deposit_micro_usdc: u64,
    /// Per-signer LIVE concurrency cap `k`, in ramp-start credit windows (ADR 003
    /// § Pool solvency, per-signer floor isolation): the most live un-vouchered floor
    /// reservation any one capability signer may hold against a pool, `k · one credit
    /// window`. Lower-clamped to one window at use. Defaults to `8` — see
    /// `decdn_common::config::DEFAULT_POOL_FLOOR_SIGNER_LIVE_WINDOWS`.
    pub pool_floor_signer_live_windows: u64,
}

/// Resolved cache fields.
#[derive(Debug)]
pub struct ResolvedCache {
    /// Blob cache directory.
    pub cache_dir: PathBuf,
    /// Upper bound on the cache ceiling in megabytes. The eviction driver clamps
    /// it down each tick so the cache never grows into the last
    /// [`Self::disk_headroom_mb`] of free space on the `cache_dir` volume
    /// (#1930).
    pub cache_size_mb: u64,
    /// Free disk in megabytes the eviction driver keeps unused on the
    /// `cache_dir` volume, defended against any process (#1930). Default
    /// [`crate::config::DEFAULT_DISK_HEADROOM_MB`]; `0` opts out of the disk
    /// clamp so only [`Self::cache_size_mb`] binds.
    pub disk_headroom_mb: u64,
    /// Cap on the bytes of one blob the node holds, in megabytes. A blob from
    /// the node's own origin larger than it is refused; a pull-through serves a
    /// range at any offset of a larger blob while the bytes held for it fit.
    pub max_blob_size_mb: u64,
    /// Buyer-side ABSOLUTE per-MB rate ceiling for paid pulls (#1375), in the same
    /// per-MB units as the wire `StreamResponse.rate_per_mb`; `0` = unlimited
    /// (the default). A buyer-side ceiling: it bounds what this node, acting as a
    /// BUYER on a cache-miss pull, will accept a provider to quote. The node also
    /// always applies a probe-relative bound (a quote may not exceed the rate the
    /// chosen candidate advertised at probe), so this is the additional absolute
    /// backstop. The node never bounds its own sell rate.
    pub max_rate_per_mb: u64,
    /// Resolved ordered list of origin backends (#437, #284). Empty
    /// vec => no pull-through; cache misses return `NoOrigin`. A
    /// single-element vec is the single-origin case and is also the
    /// form produced from a `[cache.origin]` (singular) TOML table —
    /// both wire forms (singular and plural `[[cache.origins]]`)
    /// collapse here so downstream wiring sees
    /// one canonical representation. Per-variant validation (URL
    /// parse, S3 bucket/region/prefix shape) has already run at
    /// resolution time — the wiring layer can construct the concrete
    /// `Origin` impl without re-validating. Order is significant: the
    /// engine tries entries in this order on a cache miss and falls
    /// back to the next on `NotFound`, permanent error, or transient
    /// retry exhaustion.
    pub origins: Vec<ResolvedOrigin>,
    /// Operator-pinned blob hashes (#276). Hashes here are excluded from
    /// LRU eviction candidates by the cache engine. Resolved
    /// from the hex-encoded TOML form at load time, so any wrong-length
    /// or non-hex entry fails config loading rather than turning into a
    /// silent "this hash will be ignored" surprise.
    ///
    /// Held as [`decdn_config_types::PinnedHashes`] (a typed wrapper around
    /// `Arc<HashSet<Hash>>`) so the engine, runtime, and resolver
    /// share one nominal type — a future "blocklist" or similar
    /// `HashSet<Hash>`-shaped feature can't be silently swapped into
    /// the pinning slot.
    pub pinned_hashes: decdn_config_types::PinnedHashes,
    /// Origin pull-through retry policy (#285). Set once at startup;
    /// changes require a process restart.
    pub origin_retry: decdn_config_types::RetryPolicy,
    /// Per-origin circuit-breaker policy (#963). Fronts each origin's
    /// pull-through retry loop so a sustained outage fast-fails the
    /// origin's misses (no retry/backoff incurred) and the cache sheds
    /// load, then probes for recovery. Set once at startup; changes
    /// require a process restart.
    pub circuit_breaker: decdn_config_types::CircuitBreakerPolicy,
    /// `User-Agent` header sent on every HTTP origin pull-through (#435).
    /// Defaults to [`decdn_config_types::DEFAULT_USER_AGENT`] (which embeds
    /// the `decdn-config-types` crate's `CARGO_PKG_VERSION`; the
    /// `decdn-node/` prefix — not the version — is the stable contract,
    /// #578); operators can override
    /// via `cache.user_agent` to attribute CDN traffic in origin access
    /// logs or to drive origin-side rate limits and routing policy.
    pub user_agent: String,
    /// Interval between iroh-blobs GC sweeps in seconds (#518). `0`
    /// disables the periodic sweep; any positive value is forwarded to
    /// iroh-blobs' built-in GC loop. Default
    /// [`crate::config::DEFAULT_GC_INTERVAL_SEC`] when the TOML section
    /// omits the field.
    pub gc_interval_sec: u64,
    /// Interval between origin-held-index rescans in seconds (#1130). `0`
    /// disables the periodic rescan (startup + `decdn node reload` still run
    /// one). Default [`crate::config::DEFAULT_FS_RESCAN_INTERVAL_SEC`] when the
    /// TOML section omits the field.
    pub fs_rescan_interval_sec: u64,
    /// TTL in seconds for a memoised positive live-origin probe answer (#1130
    /// pt3). Default [`crate::config::DEFAULT_ORIGIN_PROBE_TTL_SEC`]. Backs the
    /// per-probe `HEAD`/`HeadObject` fallback that discovers non-pinned http/s3
    /// objects the enumeration index cannot see.
    pub origin_probe_ttl_sec: u64,
    /// Default [`crate::config::DEFAULT_ORIGIN_PROBE_NEGATIVE_TTL_SEC`]. The
    /// negative-answer TTL for the origin-probe memo — the bound on how long a
    /// stale `Absent` can hide newly-available own content.
    pub origin_probe_negative_ttl_sec: u64,
    /// Memo TTL in seconds for a `Fault` answer (#1130 pt3). Default
    /// [`crate::config::DEFAULT_ORIGIN_PROBE_FAULT_TTL_SEC`]. Bounds how long a
    /// hash that faulted is not re-probed, and is capped by
    /// `origin_probe_ttl_sec` so a recovered origin is noticed soon.
    pub origin_probe_fault_ttl_sec: u64,
    /// Per-probe live-`HEAD` ceiling in milliseconds (#1130 pt3). Default
    /// [`crate::config::DEFAULT_ORIGIN_PROBE_TIMEOUT_MS`]. Keeps a slow origin
    /// off the probe hot path.
    pub origin_probe_timeout_ms: u64,
    /// Maximum distinct hashes in the live-origin probe memo (#1130 pt3).
    /// Default [`crate::config::DEFAULT_ORIGIN_PROBE_MEMO_CAPACITY`]. Bounds
    /// memo memory under a random-hash probe flood.
    pub origin_probe_memo_capacity: u64,
    /// LRU eviction driver high-water percent of [`Self::cache_size_mb`]
    /// (#1173). Above this fraction the driver actively evicts. Validated to
    /// `[60, 95]`. Default [`crate::config::DEFAULT_EVICTION_HIGH_WATER_PCT`].
    pub eviction_high_water_pct: u64,
    /// LRU eviction driver target percent of [`Self::cache_size_mb`] (#1173).
    /// The driver evicts down to this fraction before idling. Validated to
    /// `[40, 90]` and `<= eviction_high_water_pct - 5` (structural hysteresis
    /// gap). Default [`crate::config::DEFAULT_EVICTION_TARGET_PCT`].
    pub eviction_target_pct: u64,
    /// LRU eviction driver max candidates removed per tick (#1173). Validated
    /// to `[1, 256]`. Default
    /// [`crate::config::DEFAULT_EVICTION_PER_SWEEP_BUDGET`].
    pub eviction_per_sweep_budget: u64,
    /// LRU eviction driver wakeup cadence in seconds (#1173). Validated to
    /// `[1, 60]`. Default [`crate::config::DEFAULT_EVICTION_TICK_SECS`].
    pub eviction_tick_secs: u64,
    /// Maximum number of concurrently held (eviction-exempt) blobs for the
    /// probe-triggered hold (ADR 005 §Hold budget, #318). Default
    /// [`crate::config::DEFAULT_MAX_PROBE_HOLDS`]; `0` disables
    /// `has_blob: true`.
    pub max_probe_holds: usize,
    /// Probe-hold slots reserved for the stake lane (registered node-to-node
    /// requesters) under hold-budget pressure (#757, ADR 003 §Admission and
    /// Priority). Default `0` disables the reservation (single-lane node).
    /// The runtime only builds a `StakeLanePolicy` when this is `> 0`, so the
    /// probe handler's hot path is unchanged for the default.
    pub stake_lane_reserved_holds: usize,
    /// Enable node-to-node paid cache-miss pull-through (#831). Default
    /// `false`. When `true` and the buyer pool service bootstrapped, the
    /// runtime provisions the `NodeOrigin` and the client handler triggers a
    /// pull on a miss (behind a pull-authorized client lane). `cache.*` is
    /// restart-required, so this is read once at bring-up.
    pub node_to_node_pull_through_enabled: bool,
    /// When `false`, the node serves and seeds only content its own backend
    /// holds; a foreign hash is declined like a miss. The default is
    /// role-derived: `false` (origin-only) when an origin backend is
    /// configured — an origin is not a general proxy — and `true` (relay)
    /// when no origin is configured, since a pure edge node's only function
    /// is relaying. Explicit config overrides either default. Node-local;
    /// `cache.*` is restart-required.
    pub relay_foreign_namespaces: bool,
    /// Providers probed before ranking on a node-to-node pull (#831). Default
    /// [`crate::config::DEFAULT_NODE_PULL_PROBE_FANOUT`].
    pub node_pull_probe_fanout: usize,
    /// Per-pull wall-clock timeout in seconds for a node-to-node miss fill
    /// (#831). Default [`crate::config::DEFAULT_NODE_PULL_TIMEOUT_SEC`].
    ///
    /// Bounds the OPEN stage only; the streaming stage is bounded by
    /// [`Self::node_pull_stall_window_sec`] and [`Self::node_pull_min_throughput_bps`]
    /// (#1797).
    pub node_pull_timeout_sec: u64,
    /// Throughput-floor window (seconds) on the streaming stage of an upstream pull; bytes
    /// are counted off the QUIC stream sub-frame, so it trips only when throughput falls
    /// below the floor, never on a large blob (#1797). Default
    /// [`crate::config::DEFAULT_NODE_PULL_STALL_WINDOW_SEC`]. Also the head start of each
    /// own-origin range-pull read's time budget (ADR 037).
    pub node_pull_stall_window_sec: u64,
    /// Minimum sustained upstream throughput (bytes/sec) over `node_pull_stall_window_sec`;
    /// `0` = idle detection only (#1797). Default
    /// [`crate::config::DEFAULT_NODE_PULL_MIN_THROUGHPUT_BPS`]. Also the average throughput
    /// each own-origin range-pull read must sustain after the head start; `0` leaves those
    /// reads unbounded (ADR 037).
    pub node_pull_min_throughput_bps: u64,
    /// Cache eviction policy selector (ADR 040). `"lru"` or `"tinylfu"`.
    /// Default [`crate::config::DEFAULT_EVICTION_POLICY`].
    pub eviction_policy: String,
    /// Cache admission policy selector (ADR 040). `"always"` or `"tinylfu"`.
    /// Default [`crate::config::DEFAULT_ADMISSION_POLICY`].
    pub admission_policy: String,
    /// W-TinyLFU tuning knobs (ADR 040), resolved regardless of whether either
    /// policy selector above is `"tinylfu"` — cheap to resolve and keeps this
    /// struct free of `Option`.
    pub tinylfu: ResolvedTinyLfu,
    /// Refuse-to-serve economics tuning (ADR 041): the margin policy, its
    /// discount, and per-source speculative-warming allowance.
    pub serve_economics: ResolvedServeEconomics,
}

/// Resolved W-TinyLFU tuning knobs. See [`ResolvedCache::tinylfu`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResolvedTinyLfu {
    /// Count-min sketch size in bytes. Default
    /// [`crate::config::DEFAULT_TINYLFU_SKETCH_BYTES`].
    pub sketch_bytes: usize,
    /// Prior sightings before a probation member promotes to main. Default
    /// [`crate::config::DEFAULT_TINYLFU_PROMOTION_THRESHOLD`].
    pub promotion_threshold: u32,
    /// Percent of `cache.cache_size_mb` the probation segment is capped to.
    /// Validated to `[1, 50]`. Default
    /// [`crate::config::DEFAULT_TINYLFU_PROBATION_TARGET_PCT`].
    pub probation_target_pct: u64,
    /// Reserved: half-life in seconds for aging the frequency sketch. Resolved
    /// and stored but not currently consulted by the shipped sketch (fixed
    /// sample-count reset, not wall-clock aging). Default
    /// [`crate::config::DEFAULT_TINYLFU_AGING_HALFLIFE_SEC`].
    pub aging_halflife_sec: u64,
}

/// Resolved refuse-to-serve economics tuning (ADR 041). See
/// [`ResolvedCache::serve_economics`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedServeEconomics {
    /// Refuse-to-serve policy. `"off"` or `"margin"`. Default
    /// [`crate::config::DEFAULT_SERVE_ECONOMICS_POLICY`].
    pub policy: String,
    /// Discount applied to the sell price when deciding whether a
    /// speculative pull clears its margin gate, in basis points. Validated
    /// to `[1, 10_000]` (`5000` == `0.5`). Default
    /// [`crate::config::DEFAULT_SERVE_ECONOMICS_DISCOUNT_BPS`].
    pub discount_bps: u32,
    /// Maximum number of concurrent speculative-warming sources. `>= 1`.
    /// Default [`crate::config::DEFAULT_SERVE_ECONOMICS_N_MAX`].
    pub n_max: u32,
    /// Per-source speculative-warming allowance, in payment base units.
    /// `> 0`. Default
    /// [`crate::config::DEFAULT_SERVE_ECONOMICS_WARMING_BUDGET`].
    pub warming_budget: u64,
    /// Per-source allowance refill rate, in payment base units per second.
    /// `0` disables time-based refill. Default
    /// [`crate::config::DEFAULT_SERVE_ECONOMICS_WARMING_REFILL`].
    pub warming_refill: u64,
}

/// Resolved + validated origin backend selection (#437). Mirrors
/// [`crate::config::types::OriginConfig`] but carries pre-parsed types
/// for the variants that need them (HTTP base URL, S3 endpoint URL).
///
/// The resolution layer (`crate::config::resolve_origin`) is the
/// **intended** construction path — it's the only producer the
/// runtime relies on, and the only path that runs the validators.
/// The fields on each variant are `pub` for consistency with the
/// other `Resolved*` types in this crate (see `ResolvedCache`,
/// `ResolvedBlockchain`, etc.); Rust visibility doesn't *enforce*
/// the validator-only contract, but the runtime never bypasses it.
#[derive(Debug, Clone)]
pub enum ResolvedOrigin {
    /// HTTP(S) origin. The base URL has already been parsed by
    /// [`decdn_config_types::parse_origin_url`] at resolution time, so
    /// invariants (http/https scheme, trailing-slash path, no
    /// query/fragment) are type-enforced — they cannot be reconstructed
    /// outside the parser.
    Http {
        /// Validated base URL.
        url: decdn_config_types::OriginUrl,
        /// How to handle `Content-Encoding` on the HTTP origin response
        /// (#312). Defaults to [`decdn_config_types::DecompressMode::Auto`].
        decompress: decdn_config_types::DecompressMode,
    },
    /// Local filesystem origin root. Directory-existence is validated
    /// when the runtime constructs the
    /// cache engine's filesystem origin — config resolution carries
    /// the raw path so resolution stays filesystem-free and testable
    /// without real I/O.
    Fs {
        /// Filesystem root.
        path: PathBuf,
    },
    /// S3-compatible origin. Field-shape validation (DNS-safe bucket
    /// name, region non-empty, endpoint URL scheme, prefix shape) has
    /// already run at resolution time and is encoded in the
    /// [`ResolvedS3Config`] type.
    S3(ResolvedS3Config),
}

/// Validated runtime form of an S3 origin (#437). The intended
/// construction path is `crate::config::resolve_s3_origin`, which
/// runs the validators and lifts the wire-form
/// [`crate::config::types::S3OriginConfig`] into this resolved form
/// with pre-parsed types (notably `endpoint_url: Option<OriginUrl>`).
/// `Default` is intentionally not derived. The fields are `pub` for
/// consistency with the other `Resolved*` types in this crate, so
/// in-crate construction with field-init is technically possible —
/// the runtime simply doesn't do that. Pattern of intent rather
/// than visibility-enforced invariant.
///
/// Resolved-vs-wire-form differences:
/// - `endpoint_url` is `Option<OriginUrl>` (parsed) instead of
///   `Option<String>`, so the S3 backend cannot accidentally pass
///   an un-normalized URL to the SDK and produce `SigV4` mismatches
///   between, say, `http://minio:9000` and `http://minio:9000/`.
/// - `path_style` is `bool` (collapsed from `Option<bool>`), with
///   `None` mapped to the SDK default (virtual-hosted-style = false).
/// - `prefix` is a `String` with the trailing-slash
///   auto-append already applied — the runtime never sees the raw
///   pre-normalised form.
#[derive(Debug, Clone)]
pub struct ResolvedS3Config {
    /// Bucket name. Validated DNS-safe at construction time.
    pub bucket: String,
    /// AWS region, validated non-empty at construction time.
    pub region: String,
    /// Custom endpoint URL for non-AWS S3-compatible providers (R2,
    /// B2, `MinIO`). Parsed and trailing-slash-normalized.
    pub endpoint_url: Option<decdn_config_types::OriginUrl>,
    /// Whether to use path-style addressing. `false` (the SDK
    /// default) selects virtual-hosted-style addressing.
    pub path_style: bool,
    /// Optional key prefix prepended to every fetched object.
    /// Trailing-slash-normalized so the runtime can build keys via
    /// `format!("{prefix}{shard}/{hex}")` without re-checking the
    /// trailing slash.
    pub prefix: String,
    /// Resolved credential source.
    pub credentials: Option<ResolvedS3Credentials>,
    /// How to handle `Content-Encoding` on the S3 origin response
    /// (#804). Defaults to [`decdn_config_types::DecompressMode::Auto`].
    pub decompress: decdn_config_types::DecompressMode,
}

/// Validated runtime form of S3 credentials (#437). See
/// [`ResolvedS3Config`] for the constructor invariant.
#[derive(Debug, Clone)]
pub enum ResolvedS3Credentials {
    /// Static IAM credentials.
    Static {
        /// AWS access key ID. Held in [`crate::config::secret::SecretString`]
        /// so an incidental `Debug` print or panic backtrace cannot
        /// leak it.
        access_key_id: crate::config::secret::SecretString,
        /// AWS secret access key. Same redaction discipline.
        secret_access_key: crate::config::secret::SecretString,
        /// Optional STS session token, redacted.
        session_token: Option<crate::config::secret::SecretString>,
    },
    /// Use the AWS default credential chain. `profile` overrides the
    /// default profile name for `~/.aws/credentials`.
    DefaultChain {
        /// Optional profile name override.
        profile: Option<String>,
    },
}

/// Resolved payment fields.
#[derive(Debug)]
pub struct ResolvedPayment {
    /// Rate per MB in USDC base units (6 decimals).
    pub rate_per_mb: u64,
    /// Credit-window ceiling in bytes (ADR 003 §Credit window). The per-stream
    /// window ramps toward this cap as the stream pays; floored at one chunk
    /// ([`decdn_protocol::client::CHUNK_BYTES`], the payment quantum) plus one
    /// 16 KiB chunk group, the leaf the payer verifies before it pays.
    /// See [`crate::config::DEFAULT_CREDIT_MAX`].
    pub credit_max: u64,
    /// Ramp divisor for the credit window; `0` opens the full ceiling immediately.
    pub credit_ramp_divisor: u64,
    /// Target wire-frame size for the serve path, in bytes (ADR 005
    /// §`cdn/client/v1`). See [`crate::config::DEFAULT_FRAME_TARGET_BYTES`] (1 MiB).
    /// Clamped down to the credit window's remaining room per frame.
    pub frame_target_bytes: u64,
    /// Background flush period for the lane store, in ms. See
    /// [`crate::config::DEFAULT_VOUCHER_COMMIT_INTERVAL_MS`] (5 s). Must be > 0.
    pub voucher_commit_interval_ms: u64,
}

/// Resolved observability fields.
#[derive(Debug)]
pub struct ResolvedObservability {
    /// Log verbosity level.
    pub log_level: LogLevel,
    /// Log output format.
    pub log_format: LogFormat,
    /// Prometheus metrics HTTP port.
    pub metrics_port: u16,
    /// IP address to bind the metrics HTTP server on.
    pub metrics_bind: std::net::IpAddr,
    /// Loopback admin HTTP port (`appendix-local-admin-http.md`). `None` disables the admin
    /// server entirely; `Some(port)` binds on `127.0.0.1:<port>`.
    pub admin_port: Option<u16>,
    /// OTLP gRPC collector endpoint (if set, span export is enabled). Resolution
    /// guarantees the `http://host:port` shape; see `validate_otlp_endpoint`.
    pub otlp_endpoint: Option<String>,
}

/// Resolved `cdn/dht/v1` settings (ADR 022).
///
/// Each `*_rate_per_sec == 0.0` and matching `*_burst == 0` disables that
/// layer. The resolver guarantees every rate is finite and `>= 0`, and that
/// each `*_burst > 0` whenever its rate is `> 0` (no deny-all).
///
/// `Default` returns the ADR 022 §DHT Rate Limiting defaults so test sites
/// that build a `ResolvedConfig` by hand can write `ResolvedDht::default()`
/// instead of restating the constants. The production `resolve_dht_into`
/// path threads the defaults through the resolver bag and is what
/// `decdn-common`'s integration tests cover.
#[derive(Debug, Clone)]
pub struct ResolvedDht {
    /// Token refill rate for the per-peer (`NodeId`) limiter, in requests/second.
    pub per_peer_rate_per_sec: f64,
    /// Bucket capacity for the per-peer limiter: how many requests one
    /// peer may send back to back before the refill rate binds. `0` alongside
    /// a `0.0` rate disables the layer; `0` against a nonzero rate is rejected
    /// as a deny-all. The same pairing rule holds for the two below.
    pub per_peer_burst: u32,
    /// Token refill rate for the per-source-IP limiter, in requests/second.
    pub per_ip_rate_per_sec: f64,
    /// Bucket capacity for the per-IP limiter.
    pub per_ip_burst: u32,
    /// Token refill rate for the handler-wide limiter, in requests/second. Applies
    /// across all peers and all source IPs together.
    pub global_rate_per_sec: f64,
    /// Bucket capacity for the handler-wide limiter.
    pub global_burst: u32,
    /// Hard cap on the per-IP keyed-limiter map (#645). `0` => unbounded.
    pub max_tracked_per_ip: usize,
    /// Hard cap on the per-peer (`NodeId`) keyed-limiter map (#645). `0`
    /// => unbounded.
    pub max_tracked_per_peer: usize,
}

impl Default for ResolvedDht {
    fn default() -> Self {
        Self {
            per_peer_rate_per_sec: 20.0,
            per_peer_burst: 40,
            per_ip_rate_per_sec: 100.0,
            per_ip_burst: 200,
            global_rate_per_sec: 1000.0,
            global_burst: 2000,
            max_tracked_per_ip: 4096,
            max_tracked_per_peer: 4096,
        }
    }
}

/// Resolved `cdn/probe/v1` settings (ADR 005 §Probe rate limiting).
///
/// Mirrors [`ResolvedDht`] in shape; `Default` returns the ADR 005 defaults
/// (a tighter per-peer cap than the DHT layer, since probes are
/// unauthenticated and cheaper to flood) so hand-built `ResolvedConfig` test
/// sites can write `ResolvedProbe::default()`. The production
/// `resolve_probe_into` path threads the defaults through the resolver bag.
#[derive(Debug, Clone)]
pub struct ResolvedProbe {
    /// Token refill rate for the per-peer (`NodeId`) limiter, in probes/second.
    pub per_peer_rate_per_sec: f64,
    /// Bucket capacity for the per-peer limiter: how many probes one
    /// peer may send back to back before the refill rate binds. `0` alongside
    /// a `0.0` rate disables the layer; `0` against a nonzero rate is rejected
    /// as a deny-all. The same pairing rule holds for the two below.
    pub per_peer_burst: u32,
    /// Token refill rate for the per-source-IP limiter, in probes/second.
    pub per_ip_rate_per_sec: f64,
    /// Bucket capacity for the per-IP limiter.
    pub per_ip_burst: u32,
    /// Token refill rate for the handler-wide limiter, in probes/second. Applies
    /// across all peers and all source IPs together.
    pub global_rate_per_sec: f64,
    /// Bucket capacity for the handler-wide limiter.
    pub global_burst: u32,
    /// Hard cap on the per-IP keyed-limiter map (#645). `0` => unbounded.
    pub max_tracked_per_ip: usize,
    /// Hard cap on the per-peer (`NodeId`) keyed-limiter map (#645). `0`
    /// => unbounded.
    pub max_tracked_per_peer: usize,
}

impl Default for ResolvedProbe {
    fn default() -> Self {
        Self {
            per_peer_rate_per_sec: 5.0,
            per_peer_burst: 5,
            per_ip_rate_per_sec: 50.0,
            per_ip_burst: 200,
            global_rate_per_sec: 1000.0,
            global_burst: 2000,
            max_tracked_per_ip: 4096,
            max_tracked_per_peer: 4096,
        }
    }
}

/// Resolved security / rate-limiting fields.
#[derive(Debug, Clone)]
pub struct ResolvedSecurity {
    /// Global cap on concurrent in-flight QUIC handler tasks.
    pub max_concurrent_handlers: u32,
    /// Per-source rate-limit refill (cells/second). `0.0` disables the
    /// layer.
    pub per_source_rate_per_sec: f64,
    /// Per-source rate-limit burst capacity. Ignored when
    /// `per_source_rate_per_sec == 0.0`.
    pub per_source_burst: u32,
    /// Hard cap on the number of tracked sources in the keyed limiter.
    pub max_tracked_sources: usize,
}

/// Which load-shed policy the node runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LoadShedPolicyKind {
    /// `resource-pressure` (the default): admit against the live egress,
    /// concurrency, and per-client budgets below.
    ResourcePressure,
    /// `always-admit`: never shed. The budgets below are still resolved and
    /// range-checked, but the policy discards them and refuses nothing.
    AlwaysAdmit,
}

/// Resolved load-shedding thresholds.
#[derive(Debug, Clone)]
pub struct ResolvedLoadShed {
    /// Which policy decides admission.
    pub policy: LoadShedPolicyKind,
    /// Serving egress budget in Mbps. `0` disables the egress ceiling.
    pub egress_budget_mbps: u64,
    /// Concurrency high-water mark: at or above it, the node starts shedding
    /// misses. The resolver rejects a value below
    /// [`Self::max_concurrent_serves_low`].
    pub max_concurrent_serves_high: u32,
    /// Concurrency low-water mark: at or below it, the node resumes admitting.
    /// The gap to the high mark is what stops the decision flapping.
    pub max_concurrent_serves_low: u32,
    /// Per-client concurrent-serve cap, enforced only while under pressure.
    /// `0` disables it.
    pub per_client_serve_cap: u32,
}

impl Default for ResolvedLoadShed {
    /// Reuses the `DEFAULT_LOAD_SHED_*` resolver constants so hand-built
    /// `ResolvedConfig`s in tests cannot drift from the production defaults.
    fn default() -> Self {
        Self {
            policy: LoadShedPolicyKind::ResourcePressure,
            egress_budget_mbps: super::DEFAULT_LOAD_SHED_EGRESS_BUDGET_MBPS,
            max_concurrent_serves_high: super::DEFAULT_LOAD_SHED_SERVES_HIGH,
            max_concurrent_serves_low: super::DEFAULT_LOAD_SHED_SERVES_LOW,
            per_client_serve_cap: super::DEFAULT_LOAD_SHED_PER_CLIENT_CAP,
        }
    }
}

/// Resolved download-receipt audit-log retention fields (#802).
///
/// `max_file_bytes` is always within `[MIN_RECEIPT_MAX_FILE_BYTES,
/// MAX_RECEIPT_MAX_FILE_BYTES]` and `retained_files` within
/// `[0, MAX_RECEIPT_RETAINED_FILES]` (the resolver rejects out-of-range
/// values), so the runtime can bound disk to roughly `(retained_files + 1) *
/// max_file_bytes`.
#[derive(Debug, Clone, Copy)]
pub struct ResolvedReceipts {
    /// Rotate the live receipt log once it reaches this many bytes.
    pub max_file_bytes: u64,
    /// Number of rotated backup files retained (`.1`..=`.N`). `0` keeps none.
    pub retained_files: u32,
}

impl Default for ResolvedReceipts {
    /// Reuses the `DEFAULT_RECEIPT_*` resolver constants so hand-built
    /// `ResolvedConfig`s in tests cannot drift from the production defaults.
    fn default() -> Self {
        Self {
            max_file_bytes: super::DEFAULT_RECEIPT_MAX_FILE_BYTES,
            retained_files: super::DEFAULT_RECEIPT_RETAINED_FILES,
        }
    }
}

/// Fully resolved node configuration.
///
/// Every field has a value determined by the three-layer merge:
/// CLI flag > config file > built-in default.
///
/// Required fields that have no default (`rpc_url`,
/// `payment_pool_address`, `capacity_bond_address`) cause
/// [`super::resolve_config`] to return an error if not provided.
#[derive(Debug)]
pub struct ResolvedConfig {
    /// Node key and data directory.
    pub identity: ResolvedIdentity,
    /// Listen addresses, relays, and NAT-traversal settings.
    pub network: ResolvedNetwork,
    /// Chain RPC endpoint and the contract addresses the node talks to.
    pub blockchain: ResolvedBlockchain,
    /// Blob store, origin backend, and admission/eviction policy.
    pub cache: ResolvedCache,
    /// Pricing, voucher, and settlement settings.
    pub payment: ResolvedPayment,
    /// Logging, metrics, and tracing endpoints.
    pub observability: ResolvedObservability,
    /// Connection and dispatch limits for the serving path.
    pub security: ResolvedSecurity,
    /// Overload-protection thresholds.
    pub load_shed: ResolvedLoadShed,
    /// `cdn/dht/v1` settings (ADR 022).
    pub dht: ResolvedDht,
    /// `cdn/probe/v1` settings (ADR 005).
    pub probe: ResolvedProbe,
    /// Download-receipt log settings.
    pub receipts: ResolvedReceipts,
    /// Local content denylist (ADR 011).
    pub content: ResolvedContent,
}

/// Resolved local content denylist (ADR 011 §Local Denylist).
///
/// Both sets are hot-reloadable: a takedown order with a sub-day deadline must
/// not require a restart to discharge.
#[derive(Debug, Clone, Default)]
pub struct ResolvedContent {
    /// Blob hashes refused at the delivery path. A distinct type from
    /// [`ResolvedCache::pinned_hashes`]'s `PinnedHashes` on purpose — the two
    /// are both hash sets meaning opposite things, and confusing them would pin
    /// content the operator was ordered to remove.
    pub denied_hashes: DeniedHashes,
    /// Operator addresses whose pools are refused. Unioned with the on-chain
    /// origin blacklist at the gate, so the wire refusal cannot distinguish a
    /// local entry from a governance one (ADR 011 §`StreamRequest` Response).
    pub denied_origins: HashSet<Address>,
}