autumn-web 0.9.0

//! Per-deploy capacity contract — the `capacity.lock` artifact (issue #1733).
//!
//! A capacity contract is a committed, versioned statement of what one build
//! sustains on one host class: *"on this hardware, this binary sustains N
//! req/s at P99 ≤ M ms; beyond that it admission-controls rather than
//! degrades."* It is produced by `autumn calibrate`, committed next to
//! `autumn.toml`, re-checked in CI by `autumn calibrate --check`, and — the
//! part that makes it a contract rather than a report — read back by the
//! runtime to source the bounded-concurrency admission limit that
//! [`LoadShedLayer`](crate::middleware::LoadShedLayer) enforces (ADR-0009).
//!
//! This module owns the artifact *model* only: the types, their canonical
//! TOML form, and the two questions the runtime asks of a contract ("is this
//! contract about a host like mine?" and "what admission limit does it
//! license?"). Measuring an envelope lives in the CLI (`autumn calibrate`);
//! enforcing one lives in `router::build_load_shed_layer`.
//!
//! # Canonical form
//!
//! [`CapacityContract::to_toml`] canonicalizes before rendering — routes
//! sorted by `(path, method)`, pools sorted and deduplicated — so a
//! re-calibration that measured the same graph produces a byte-identical
//! route section and the git diff shows only the numbers that actually moved.
//!
//! # What a contract does *not* claim
//!
//! The per-route shape is the **provable subset** of a route's resource
//! usage: it is derived at macro-expansion time from the handler's declared
//! extractors, so a pool reached through an application-held
//! [`State`](axum::extract::State) value is invisible to it and the route
//! reads as [`ResourceShape::ComputeBound`]. The shape narrows *why* an
//! envelope moved; the envelope itself is measured, not inferred.

use std::path::Path;

use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};

use crate::config::normalize_profile_name;

/// Schema version of the `capacity.lock` document.
///
/// A contract declaring a *higher* version is rejected rather than
/// best-effort parsed: an older binary silently ignoring a field a newer
/// calibration relied on would enforce an envelope nobody proved.
pub const CONTRACT_VERSION: u32 = 1;

/// Conventional file name of the committed contract.
pub const CONTRACT_FILE_NAME: &str = "capacity.lock";

/// Header written above a generated contract, so the artifact explains itself
/// where a reader meets it.
const CONTRACT_HEADER: &str = "\
# Autumn capacity contract (issue #1733) — generated by `autumn calibrate`.
#
# Committed on purpose: `autumn calibrate --check` gates rebuilds against it in
# CI, and the runtime can source its load-shedding admission limit from it
# (`[server] capacity_contract`). Re-generate it with `autumn calibrate`
# rather than editing it by hand — the numbers below are measured, and a
# hand-edited envelope is a guarantee nobody proved.
";

/// Errors raised while reading, validating, or writing a capacity contract.
#[derive(Debug, thiserror::Error)]
pub enum CapacityError {
    /// The contract file could not be read.
    #[error("failed to read capacity contract '{path}': {source}")]
    Io {
        /// Path that was attempted.
        path: String,
        /// Underlying I/O failure.
        #[source]
        source: std::io::Error,
    },
    /// The document is not a well-formed capacity contract.
    #[error("capacity contract is not valid TOML: {0}")]
    Parse(#[from] toml::de::Error),
    /// The contract could not be rendered back to TOML.
    #[error("failed to serialize capacity contract: {0}")]
    Serialize(#[from] toml::ser::Error),
    /// The contract was written by a newer autumn than this build understands.
    #[error(
        "capacity contract declares schema version {found}, but this build understands \
         up to {supported}; re-run `autumn calibrate` with a matching autumn version"
    )]
    UnsupportedVersion {
        /// Version read from the document.
        found: u32,
        /// Highest version this build understands ([`CONTRACT_VERSION`]).
        supported: u32,
    },
}

/// The resource character of one route, derived statically from its handler's
/// declared extractors.
///
/// Ordered by how much a route's cost is dominated by waiting on something
/// outside the process: a route holding a database connection for the length
/// of the request constrains concurrency very differently from one that only
/// renders a template.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ResourceShape {
    /// Touches a database pool: its concurrency is bounded by pool checkout,
    /// not by CPU.
    DbBound,
    /// Touches a non-database external resource. In this slice that means the
    /// mail transport, the event bus, the presence store, or notifications —
    /// the extractors the derivation can actually prove.
    IoBound,
    /// Touches no pool this build can prove. The default, and the honest
    /// reading of a handler whose signature declares no resource extractor.
    #[default]
    ComputeBound,
}

impl ResourceShape {
    /// Stable lowercase tag used in the serialized contract.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::DbBound => "db-bound",
            Self::IoBound => "io-bound",
            Self::ComputeBound => "compute-bound",
        }
    }

    /// Classify a route from the set of pools its handler declares.
    ///
    /// A database pool dominates: a handler that touches both the database
    /// and a cache is bounded by the database.
    #[must_use]
    pub fn from_pools<S: AsRef<str>>(pools: &[S]) -> Self {
        if pools.iter().any(|p| p.as_ref() == POOL_DB) {
            Self::DbBound
        } else if pools.is_empty() {
            Self::ComputeBound
        } else {
            Self::IoBound
        }
    }
}

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

impl std::str::FromStr for ResourceShape {
    type Err = ();

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "db-bound" => Ok(Self::DbBound),
            "io-bound" => Ok(Self::IoBound),
            "compute-bound" => Ok(Self::ComputeBound),
            _ => Err(()),
        }
    }
}

impl Serialize for ResourceShape {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for ResourceShape {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        // An unknown tag from a forward-compatible writer degrades to the
        // conservative default rather than failing the whole document: the
        // shape annotates a diff, it never licenses an admission limit.
        Ok(s.parse().unwrap_or_default())
    }
}

/// Pool tag for a database connection pool.
///
/// The one tag with semantics beyond documentation: it is what makes a route
/// [`ResourceShape::DbBound`], because holding a pooled connection for the
/// length of a request bounds concurrency in a way nothing else here does.
pub const POOL_DB: &str = "db";
/// Every pool tag the derivation can emit, sorted.
///
/// The vocabulary is *produced* by `autumn-macros`, which cannot depend on this
/// crate and so repeats the literals. This list is the reader's reference and
/// the anchor for the round-trip test below — a macro-side rename that is not
/// mirrored here shows up as a route whose pool tag is not in this set.
pub const POOL_TAGS: &[&str] = &[POOL_DB, "events", "mail", "notifications", "presence"];

/// One route's statically derived resource shape.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RouteShape {
    /// HTTP method (`GET`, `POST`, …).
    pub method: String,
    /// Mounted path template (e.g. `/api/posts/{id}`).
    pub path: String,
    /// Handler function name, for diagnostics. Deliberately **not** part of
    /// [`route_graph_digest`]: renaming a handler does not change what the
    /// route costs.
    pub handler: String,
    /// Derived resource character.
    pub shape: ResourceShape,
    /// Pools the handler's declared extractors prove it touches, sorted and
    /// deduplicated.
    #[serde(default)]
    pub pools: Vec<String>,
}

/// The host class a contract was measured on.
///
/// Recorded so a contract is never compared against — or enforced on — a
/// machine it says nothing about. Comparing a laptop's envelope to a CI
/// runner's is the fastest way to turn a capacity gate into a flake.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct HostProfile {
    /// Target OS (`std::env::consts::OS`).
    pub os: String,
    /// Target architecture (`std::env::consts::ARCH`).
    pub arch: String,
    /// Logical CPUs visible to the process.
    pub logical_cpus: usize,
    /// Total system memory in MiB, when the platform exposes it. Recorded for
    /// the reader; deliberately **not** part of [`HostProfile::matches`],
    /// because it is unavailable on some platforms and varies with
    /// container accounting.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub total_memory_mb: Option<u64>,
}

impl HostProfile {
    /// Placeholder used on the code paths that resolve an admission limit
    /// *without* consulting a contract, where no host comparison happens.
    /// Never written to a contract.
    const EMPTY: Self = Self {
        os: String::new(),
        arch: String::new(),
        logical_cpus: 0,
        total_memory_mb: None,
    };

    /// Read the current host's profile.
    #[must_use]
    pub fn detect() -> Self {
        Self {
            os: std::env::consts::OS.to_owned(),
            arch: std::env::consts::ARCH.to_owned(),
            logical_cpus: std::thread::available_parallelism().map_or(1, std::num::NonZero::get),
            total_memory_mb: detect_total_memory_mb(),
        }
    }

    /// Whether `other` is the same host *class* as `self`.
    ///
    /// Same OS, same architecture, same logical CPU count. Memory is
    /// informational only (see [`Self::total_memory_mb`]).
    #[must_use]
    pub fn matches(&self, other: &Self) -> bool {
        self.os == other.os && self.arch == other.arch && self.logical_cpus == other.logical_cpus
    }

    /// One-line rendering for diagnostics, e.g. `linux/x86_64 8 vCPU`.
    #[must_use]
    pub fn summary(&self) -> String {
        format!("{}/{} {} vCPU", self.os, self.arch, self.logical_cpus)
    }
}

/// Total system memory in MiB, or `None` when the platform does not expose it
/// without a dependency.
fn detect_total_memory_mb() -> Option<u64> {
    #[cfg(target_os = "linux")]
    {
        let meminfo = std::fs::read_to_string("/proc/meminfo").ok()?;
        let kb: u64 = meminfo
            .lines()
            .find_map(|line| line.strip_prefix("MemTotal:"))?
            .split_whitespace()
            .next()?
            .parse()
            .ok()?;
        Some(kb / 1024)
    }
    #[cfg(not(target_os = "linux"))]
    {
        None
    }
}

/// Where a contract came from.
///
/// Recorded for the human reading a diff; **never** compared by
/// `autumn calibrate --check`, so a no-op rebuild can never fail the gate on
/// a changed timestamp.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Provenance {
    /// Version of autumn that ran the calibration.
    pub autumn_version: String,
    /// RFC 3339 timestamp of the calibration run.
    pub calibrated_at: String,
    /// Commit the calibrated binary was built from, when discoverable.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit: Option<String>,
    /// Whether the working tree had uncommitted changes at calibration time.
    /// A contract measured from a dirty tree describes a build nobody else
    /// can reproduce.
    #[serde(default)]
    pub git_dirty: bool,
    /// Digest of the route graph the envelope was measured against — see
    /// [`route_graph_digest`].
    pub route_graph_digest: String,
}

/// The calibration parameters that produced an envelope.
///
/// Recorded because an envelope only means something next to the workload that
/// produced it. `autumn calibrate --check` replays these rather than its own
/// defaults: comparing a contract measured with `--concurrency 1,8,64
/// --rung-ms 5000` against a rebuild measured with the default ladder would be
/// comparing two different experiments, which is a false regression (or a
/// false pass) waiting to happen.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Calibration {
    /// Autumn profile the app was booted under (`prod` by default, matching
    /// the deploy path).
    ///
    /// Profile overlays and smart defaults change middleware, backends and
    /// pool sizing, so a contract measured under `dev` would govern a
    /// materially different production binary.
    #[serde(default = "default_calibration_profile")]
    pub profile: String,
    /// Cargo features the calibrated binary was built with, verbatim.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub features: Vec<String>,
    /// Whether the binary was built with `--all-features`.
    #[serde(default, skip_serializing_if = "is_false_flag")]
    pub all_features: bool,
    /// Whether the binary was built with `--no-default-features`.
    #[serde(default, skip_serializing_if = "is_false_flag")]
    pub no_default_features: bool,
    /// Paths the ladder drove, when they were named explicitly rather than
    /// discovered.
    ///
    /// Replayed by `--check`: a contract measured against an explicitly named
    /// (often deliberately expensive) route would otherwise be gated against a
    /// rediscovered, cheaper mix — certifying a rebuild on a workload that
    /// never produced the committed envelope. Empty means "discover them",
    /// which is itself stable for an unchanged route graph.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub targets: Vec<String>,
    /// Seed for the request profile.
    pub seed: u64,
    /// Concurrency ladder walked, ascending.
    pub concurrency: Vec<usize>,
    /// Milliseconds each rung was held for.
    pub rung_ms: u64,
    /// How many times each rung was measured, with the median taken.
    ///
    /// A single sample per rung makes the gate hostage to whatever else the
    /// machine was doing during that one window; repeating and taking the
    /// median is what the sibling dev-loop benchmarks do, and it is the
    /// difference between a gate that flags regressions and one that flags
    /// noisy neighbours.
    #[serde(default = "default_runs")]
    pub runs: u32,
    /// Milliseconds of discarded warmup before the ladder.
    pub warmup_ms: u64,
}

/// `skip_serializing_if` helper for the build-selection booleans.
#[allow(clippy::trivially_copy_pass_by_ref)]
const fn is_false_flag(flag: &bool) -> bool {
    !*flag
}

/// Serde default for [`Calibration::runs`].
const fn default_runs() -> u32 {
    DEFAULT_RUNS
}

/// Serde default for [`Calibration::profile`].
fn default_calibration_profile() -> String {
    DEFAULT_PROFILE.to_owned()
}

impl Default for Calibration {
    /// The shipped defaults, used when a contract predates this section.
    fn default() -> Self {
        Self {
            profile: default_calibration_profile(),
            features: Vec::new(),
            all_features: false,
            no_default_features: false,
            targets: Vec::new(),
            seed: DEFAULT_SEED,
            concurrency: DEFAULT_LADDER.to_vec(),
            rung_ms: DEFAULT_RUNG_MS,
            runs: DEFAULT_RUNS,
            warmup_ms: DEFAULT_WARMUP_MS,
        }
    }
}

/// Profile a calibration runs under unless told otherwise.
///
/// `prod` rather than the ambient default: `autumn deploy` pins the deployment
/// profile, so calibrating under `dev` would measure a configuration nobody
/// ships.
pub const DEFAULT_PROFILE: &str = "prod";

/// Default seed for the request profile.
///
/// Lives here, not in the CLI, so the `#[serde(default)]` fallback for a
/// contract written before the calibration section existed matches what that
/// contract was actually measured with.
pub const DEFAULT_SEED: u64 = 1733;
/// Default concurrency ladder.
pub const DEFAULT_LADDER: &[usize] = &[1, 2, 4, 8, 16, 32, 64];
/// Default milliseconds held per rung.
pub const DEFAULT_RUNG_MS: u64 = 2000;
/// Default milliseconds of discarded warmup.
pub const DEFAULT_WARMUP_MS: u64 = 1000;
/// Default number of measurements per rung; the median is recorded.
pub const DEFAULT_RUNS: u32 = 3;

/// The proven envelope: what the build sustains, and what it will admit.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Envelope {
    /// Sustained throughput at the saturation knee, in requests per second.
    pub sustained_rps: f64,
    /// P99 request latency at that knee, in milliseconds.
    pub p99_latency_ms: f64,
    /// Offered concurrency at the knee — the point past which more
    /// concurrency bought throughput no longer worth its latency.
    pub saturation_concurrency: usize,
    /// Admission limit the contract licenses: the in-flight ceiling the
    /// runtime enforces so the binary sheds at its proven edge instead of
    /// degrading past it.
    pub admission_limit: usize,
}

/// A committed, versioned capacity contract.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CapacityContract {
    /// Schema version — see [`CONTRACT_VERSION`].
    pub version: u32,
    /// Where the contract came from.
    pub provenance: Provenance,
    /// Host class the envelope was measured on.
    pub host: HostProfile,
    /// The proven envelope.
    pub envelope: Envelope,
    /// The workload that produced [`Self::envelope`], replayed verbatim by
    /// `autumn calibrate --check`. Defaulted when absent so a contract written
    /// before this field was recorded still loads.
    #[serde(default)]
    pub calibration: Calibration,
    /// Statically derived per-route resource shape.
    #[serde(default, rename = "routes")]
    pub routes: Vec<RouteShape>,
}

/// Minimal probe used to read the schema version before committing to the
/// full document shape.
#[derive(Deserialize)]
struct VersionProbe {
    version: u32,
}

impl CapacityContract {
    /// Parse a contract from its TOML form.
    ///
    /// # Errors
    ///
    /// [`CapacityError::Parse`] when the document is not a well-formed
    /// contract, or [`CapacityError::UnsupportedVersion`] when it was written
    /// by a newer autumn.
    pub fn parse(toml_src: &str) -> Result<Self, CapacityError> {
        let probe: VersionProbe = toml::from_str(toml_src)?;
        if probe.version > CONTRACT_VERSION {
            return Err(CapacityError::UnsupportedVersion {
                found: probe.version,
                supported: CONTRACT_VERSION,
            });
        }
        Ok(toml::from_str(toml_src)?)
    }

    /// Read and parse a contract from disk.
    ///
    /// # Errors
    ///
    /// [`CapacityError::Io`] when the file cannot be read, plus any error
    /// [`Self::parse`] raises.
    pub fn load(path: impl AsRef<Path>) -> Result<Self, CapacityError> {
        let path = path.as_ref();
        let src = std::fs::read_to_string(path).map_err(|source| CapacityError::Io {
            path: path.display().to_string(),
            source,
        })?;
        Self::parse(&src)
    }

    /// Render the contract in its canonical TOML form, with the explanatory
    /// header.
    ///
    /// Canonicalizes first (see [`Self::canonicalize`]) so re-calibrating an
    /// unchanged route graph produces a byte-identical route section.
    ///
    /// # Errors
    ///
    /// [`CapacityError::Serialize`] when the document cannot be rendered.
    pub fn to_toml(&self) -> Result<String, CapacityError> {
        let mut canonical = self.clone();
        canonical.canonicalize();
        let body = toml::to_string_pretty(&canonical)?;
        Ok(format!("{CONTRACT_HEADER}{body}"))
    }

    /// Put the contract in canonical order: routes sorted by `(path, method)`,
    /// each route's pools sorted and deduplicated.
    pub fn canonicalize(&mut self) {
        for route in &mut self.routes {
            route.pools.sort_unstable();
            route.pools.dedup();
        }
        self.routes
            .sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.method.cmp(&b.method)));
    }

    /// The admission limit this contract licenses on `host`, if any.
    ///
    /// `None` — meaning "no contract-derived limit, leave admission control
    /// as configured" — when the contract describes a different host class,
    /// or when it records a limit of `0`. That second guard matters: `0`
    /// reaching [`LoadShedLayer`](crate::middleware::LoadShedLayer) as a
    /// ceiling would be read as *shed everything*, so a contract that failed
    /// to measure a limit must never be able to wedge a deploy shut.
    #[must_use]
    pub fn admission_limit_for_host(&self, host: &HostProfile) -> Option<usize> {
        if !self.host.matches(host) {
            return None;
        }
        (self.envelope.admission_limit > 0).then_some(self.envelope.admission_limit)
    }

    /// Whether the contract was calibrated under the `running` profile.
    ///
    /// Both names go through [`normalize_profile_name`], so `production` and
    /// `PROD` compare equal. An unnamed running profile cannot be compared,
    /// so it counts as a match. A blank contract profile never matches a named one.
    #[must_use]
    pub(crate) fn calibrated_under(&self, running: Option<&str>) -> bool {
        let Some(running) = running.and_then(normalize_profile_name) else {
            return true;
        };
        normalize_profile_name(&self.calibration.profile).is_some_and(|own| own == running)
    }
}

/// Resolve the ceiling from an app's `[server]` settings.
///
/// Thin wrapper over [`resolve_admission_limit`] that does the cheap checks
/// first and only reads the running host's profile when a contract is actually
/// going to be consulted — `build_router` runs this on every boot (and on
/// every `TestApp`), and there is no reason to stat `/proc` for an app that
/// configured no contract. An empty path is treated as "no contract", so
/// clearing `AUTUMN_SERVER__CAPACITY_CONTRACT` to the empty string disables
/// contract sourcing rather than reporting a missing file.
#[must_use]
pub fn resolve_configured_admission_limit(
    explicit: Option<usize>,
    contract_path: Option<&str>,
) -> AdmissionLimit {
    resolve_configured_admission_limit_with_default(explicit, contract_path, None)
}

/// [`resolve_configured_admission_limit`] with a profile default ceiling
/// (#3057). It does not check the calibrated profile. For that, use
/// [`resolve_configured_admission_limit_for_profile`].
#[must_use]
pub fn resolve_configured_admission_limit_with_default(
    explicit: Option<usize>,
    contract_path: Option<&str>,
    profile_default: Option<usize>,
) -> AdmissionLimit {
    resolve_configured_admission_limit_for_profile(explicit, contract_path, profile_default, None)
}

/// [`resolve_configured_admission_limit_with_default`] that also checks the
/// contract was calibrated under `running_profile` (#2418).
#[must_use]
pub fn resolve_configured_admission_limit_for_profile(
    explicit: Option<usize>,
    contract_path: Option<&str>,
    profile_default: Option<usize>,
    running_profile: Option<&str>,
) -> AdmissionLimit {
    let path = contract_path.filter(|p| !p.is_empty());
    if explicit.is_some() || path.is_none() {
        return resolve_admission_limit_for_profile(
            explicit,
            None,
            &HostProfile::EMPTY,
            profile_default,
            running_profile,
        );
    }
    resolve_admission_limit_for_profile(
        explicit,
        path.map(Path::new),
        &HostProfile::detect(),
        profile_default,
        running_profile,
    )
}

/// Digest of a route graph's *capacity-relevant* shape.
///
/// Covers method, path, derived shape, and pools — deliberately not handler
/// names, so renaming a handler does not read as a capacity change. Order
/// independent: the same graph digests identically however it was collected.
#[must_use]
pub fn route_graph_digest(routes: &[RouteShape]) -> String {
    let mut lines: Vec<String> = routes
        .iter()
        .map(|route| {
            let mut pools = route.pools.clone();
            pools.sort_unstable();
            pools.dedup();
            format!(
                "{} {} {} {}",
                route.method,
                route.path,
                route.shape.as_str(),
                pools.join(",")
            )
        })
        .collect();
    lines.sort_unstable();

    let mut hasher = Sha256::new();
    for line in &lines {
        hasher.update(line.as_bytes());
        hasher.update(b"\n");
    }
    format!("sha256:{:x}", hasher.finalize())
}

/// Where a load-shedding admission ceiling came from.
///
/// Surfaced rather than collapsed to an `Option<usize>` so boot logs can say
/// *which* source won, and so a reviewer reading
/// `router::build_load_shed_layer` can see the precedence at a glance.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AdmissionLimit {
    /// An explicit `[server] max_concurrent_requests`. Always wins: an
    /// operator who set a number by hand outranks a committed artifact.
    Configured(usize),
    /// Derived from the committed capacity contract — the binary admitting
    /// against its own proven envelope.
    Contract(usize),
    /// The profile's default ceiling, used when nothing above applies or the
    /// contract cannot be used. Only `prod` supplies one (#3057).
    ProfileDefault(usize),
    /// No ceiling: load shedding stays off, exactly as it is today when
    /// nothing is configured.
    Unlimited,
}

impl AdmissionLimit {
    /// The ceiling to enforce, or `None` to leave shedding disabled.
    #[must_use]
    pub const fn limit(self) -> Option<usize> {
        match self {
            Self::Configured(n) | Self::Contract(n) | Self::ProfileDefault(n) => Some(n),
            Self::Unlimited => None,
        }
    }

    /// Short tag naming the source, for boot diagnostics.
    #[must_use]
    pub const fn source(self) -> &'static str {
        match self {
            Self::Configured(_) => "server.max_concurrent_requests",
            Self::Contract(_) => "capacity contract",
            Self::ProfileDefault(_) => "profile default",
            Self::Unlimited => "unset",
        }
    }
}

/// Resolve the admission ceiling the load-shed layer should enforce.
///
/// Precedence, and why:
///
/// 1. **`explicit`** (`[server] max_concurrent_requests`) always wins, including
///    an explicit `0` — today's spelling of "shedding off". An operator who
///    turned admission control off by hand must not have it switched back on
///    by a file they committed months ago.
/// 2. Otherwise the **contract** at `contract_path`, but only when it was
///    measured on this host class and records a non-zero limit.
/// 3. Otherwise **unlimited**, preserving today's default.
///
/// Every failure along the contract path — missing file, malformed document,
/// newer schema, foreign host class — degrades to [`AdmissionLimit::Unlimited`]
/// with a warning, never to a ceiling. Failing *closed* here would mean a
/// typo'd path or a stale lockfile sheds every request on the way up, turning
/// a capacity feature into an outage.
#[must_use]
pub fn resolve_admission_limit(
    explicit: Option<usize>,
    contract_path: Option<&Path>,
    host: &HostProfile,
) -> AdmissionLimit {
    resolve_admission_limit_with_default(explicit, contract_path, host, None)
}

/// [`resolve_admission_limit`] with a profile default ceiling (#3057).
///
/// The precedence is explicit, then contract, then `profile_default`. When the
/// contract cannot be used, the result is `profile_default`, not unlimited.
/// A `None` or `0` default gives [`AdmissionLimit::Unlimited`].
#[must_use]
pub fn resolve_admission_limit_with_default(
    explicit: Option<usize>,
    contract_path: Option<&Path>,
    host: &HostProfile,
    profile_default: Option<usize>,
) -> AdmissionLimit {
    resolve_admission_limit_for_profile(explicit, contract_path, host, profile_default, None)
}

/// [`resolve_admission_limit_with_default`] that also checks the profile (#2418).
///
/// If the contract was calibrated under a different profile than
/// `running_profile`, it gives no limit. The function then returns the
/// fallback, as it does for a host mismatch. `None` skips the check.
#[must_use]
pub fn resolve_admission_limit_for_profile(
    explicit: Option<usize>,
    contract_path: Option<&Path>,
    host: &HostProfile,
    profile_default: Option<usize>,
    running_profile: Option<&str>,
) -> AdmissionLimit {
    let fallback = profile_default
        .filter(|n| *n > 0)
        .map_or(AdmissionLimit::Unlimited, AdmissionLimit::ProfileDefault);
    if let Some(configured) = explicit {
        return if configured > 0 {
            AdmissionLimit::Configured(configured)
        } else {
            AdmissionLimit::Unlimited
        };
    }

    let Some(path) = contract_path else {
        return fallback;
    };

    let contract = match CapacityContract::load(path) {
        Ok(contract) => contract,
        Err(error) => {
            tracing::warn!(
                path = %path.display(),
                %error,
                fallback = fallback.source(),
                "capacity contract could not be read; using the fallback admission limit"
            );
            return fallback;
        }
    };

    if !contract.calibrated_under(running_profile) {
        tracing::warn!(
            path = %path.display(),
            contract_profile = %contract.calibration.profile,
            running_profile = running_profile.unwrap_or_default(),
            fallback = fallback.source(),
            "capacity contract was calibrated under another profile, so \
             the fallback admission limit applies"
        );
        return fallback;
    }

    if let Some(limit) = contract.admission_limit_for_host(host) {
        AdmissionLimit::Contract(limit)
    } else {
        tracing::warn!(
            path = %path.display(),
            contract_host = %contract.host.summary(),
            running_host = %host.summary(),
            admission_limit = contract.envelope.admission_limit,
            fallback = fallback.source(),
            "capacity contract licenses no admission limit here (different host \
             class, or no limit recorded); using the fallback admission limit"
        );
        fallback
    }
}

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

    fn sample_routes() -> Vec<RouteShape> {
        vec![
            RouteShape {
                method: "GET".to_owned(),
                path: "/posts".to_owned(),
                handler: "posts::index".to_owned(),
                shape: ResourceShape::DbBound,
                pools: vec!["db".to_owned()],
            },
            RouteShape {
                method: "GET".to_owned(),
                path: "/about".to_owned(),
                handler: "pages::about".to_owned(),
                shape: ResourceShape::ComputeBound,
                pools: Vec::new(),
            },
        ]
    }

    fn sample_contract() -> CapacityContract {
        let routes = sample_routes();
        CapacityContract {
            version: CONTRACT_VERSION,
            provenance: Provenance {
                autumn_version: "0.7.0".to_owned(),
                calibrated_at: "2026-09-01T12:00:00Z".to_owned(),
                git_commit: Some("abc1234".to_owned()),
                git_dirty: false,
                route_graph_digest: route_graph_digest(&routes),
            },
            host: HostProfile {
                os: "linux".to_owned(),
                arch: "x86_64".to_owned(),
                logical_cpus: 8,
                total_memory_mb: Some(16384),
            },
            envelope: Envelope {
                sustained_rps: 4210.5,
                p99_latency_ms: 18.42,
                saturation_concurrency: 64,
                admission_limit: 64,
            },
            calibration: Calibration::default(),
            routes,
        }
    }

    #[test]
    fn contract_round_trips_through_toml() {
        let contract = sample_contract();
        let rendered = contract.to_toml().expect("contract should serialize");
        let parsed = CapacityContract::parse(&rendered).expect("contract should parse back");

        assert_eq!(parsed.version, CONTRACT_VERSION);
        assert_eq!(parsed.host.logical_cpus, 8);
        assert_eq!(parsed.envelope.admission_limit, 64);
        assert!((parsed.envelope.sustained_rps - 4210.5).abs() < 1e-9);
        assert_eq!(parsed.routes.len(), 2);
        // The workload travels with the envelope: `--check` replays it rather
        // than its own defaults.
        assert_eq!(parsed.calibration, Calibration::default());
        assert!(
            parsed.calibration.targets.is_empty(),
            "an unset target list round-trips as 'discover them'"
        );
        assert_eq!(parsed.calibration.concurrency, DEFAULT_LADDER.to_vec());
    }

    #[test]
    fn explicitly_named_targets_survive_the_round_trip() {
        // `--check` replays these: a contract measured against a deliberately
        // expensive named route must not be gated against a rediscovered,
        // cheaper mix.
        let mut contract = sample_contract();
        contract.calibration.targets = vec!["/search".to_owned(), "/report".to_owned()];
        let rendered = contract.to_toml().expect("serialize");
        let parsed = CapacityContract::parse(&rendered).expect("parse");

        assert_eq!(
            parsed.calibration.targets,
            vec!["/search".to_owned(), "/report".to_owned()]
        );
    }

    #[test]
    fn to_toml_sorts_routes_for_stable_diffs() {
        let mut contract = sample_contract();
        contract.routes.reverse();
        let rendered = contract.to_toml().expect("contract should serialize");
        let parsed = CapacityContract::parse(&rendered).expect("contract should parse back");

        let paths: Vec<&str> = parsed.routes.iter().map(|r| r.path.as_str()).collect();
        assert_eq!(paths, ["/about", "/posts"]);
    }

    #[test]
    fn parse_rejects_a_newer_contract_version() {
        let mut contract = sample_contract();
        contract.version = CONTRACT_VERSION + 1;
        let rendered = toml::to_string_pretty(&contract).expect("raw serialize");

        let err = CapacityContract::parse(&rendered).expect_err("newer version must be rejected");
        assert!(
            matches!(err, CapacityError::UnsupportedVersion { .. }),
            "expected UnsupportedVersion, got {err}"
        );
    }

    #[test]
    fn parse_reports_malformed_toml() {
        let err = CapacityContract::parse("this is not = = toml").expect_err("must reject garbage");
        assert!(matches!(err, CapacityError::Parse(_)), "got {err}");
    }

    #[test]
    fn host_profiles_match_on_os_arch_and_cpu_count() {
        let a = HostProfile {
            os: "linux".to_owned(),
            arch: "x86_64".to_owned(),
            logical_cpus: 8,
            total_memory_mb: Some(16384),
        };
        // Memory is recorded but never gated on: it is unavailable on some
        // platforms and would make the comparison flaky.
        let b = HostProfile {
            total_memory_mb: None,
            ..a.clone()
        };
        assert!(a.matches(&b));

        let fewer_cpus = HostProfile {
            logical_cpus: 4,
            ..a.clone()
        };
        assert!(!a.matches(&fewer_cpus));

        let other_arch = HostProfile {
            arch: "aarch64".to_owned(),
            ..a.clone()
        };
        assert!(!a.matches(&other_arch));
    }

    #[test]
    fn admission_limit_is_offered_only_on_a_matching_host() {
        let contract = sample_contract();
        assert_eq!(
            contract.admission_limit_for_host(&contract.host.clone()),
            Some(64)
        );

        let other = HostProfile {
            logical_cpus: 2,
            ..contract.host.clone()
        };
        assert_eq!(contract.admission_limit_for_host(&other), None);
    }

    #[test]
    fn a_zero_admission_limit_is_never_enforced() {
        // A contract that recorded `0` must never be read as "shed every
        // request" — it degrades to "no contract-derived limit".
        let mut contract = sample_contract();
        contract.envelope.admission_limit = 0;
        assert_eq!(
            contract.admission_limit_for_host(&contract.host.clone()),
            None
        );
    }

    #[test]
    fn every_pool_tag_classifies_and_the_database_tag_dominates() {
        // `autumn-macros` cannot depend on this crate, so it repeats these
        // literals. Pin the vocabulary here: a macro-side rename that is not
        // mirrored shows up as a tag this set does not contain.
        assert!(POOL_TAGS.contains(&POOL_DB));
        let mut sorted = POOL_TAGS.to_vec();
        sorted.sort_unstable();
        assert_eq!(sorted, POOL_TAGS, "POOL_TAGS must stay sorted");

        for tag in POOL_TAGS {
            let shape = ResourceShape::from_pools(&[*tag]);
            let expected = if *tag == POOL_DB {
                ResourceShape::DbBound
            } else {
                ResourceShape::IoBound
            };
            assert_eq!(shape, expected, "tag {tag} classified wrongly");
        }

        // A handler touching both is bounded by the database.
        assert_eq!(
            ResourceShape::from_pools(&["mail", POOL_DB]),
            ResourceShape::DbBound
        );
    }

    #[test]
    fn resource_shape_serializes_as_a_stable_tag() {
        assert_eq!(ResourceShape::DbBound.as_str(), "db-bound");
        assert_eq!(ResourceShape::IoBound.as_str(), "io-bound");
        assert_eq!(ResourceShape::ComputeBound.as_str(), "compute-bound");
        assert_eq!(
            "db-bound".parse::<ResourceShape>().expect("parses"),
            ResourceShape::DbBound
        );
    }

    #[test]
    fn route_graph_digest_ignores_ordering_but_tracks_shape() {
        let routes = sample_routes();
        let mut reordered = routes.clone();
        reordered.reverse();
        assert_eq!(route_graph_digest(&routes), route_graph_digest(&reordered));

        let mut changed = routes.clone();
        changed[0].shape = ResourceShape::ComputeBound;
        assert_ne!(route_graph_digest(&routes), route_graph_digest(&changed));
    }

    // ── runtime admission sourcing (#1733 AC-4) ─────────────────────────

    use std::io::Write as _;

    /// Write `contract` to a temp dir and return the dir (kept alive by the
    /// caller) plus the contract path.
    fn write_contract(contract: &CapacityContract) -> (tempfile::TempDir, std::path::PathBuf) {
        let dir = tempfile::tempdir().expect("temp dir");
        let path = dir.path().join(CONTRACT_FILE_NAME);
        let mut file = std::fs::File::create(&path).expect("create contract");
        file.write_all(contract.to_toml().expect("serialize").as_bytes())
            .expect("write contract");
        (dir, path)
    }

    #[test]
    fn an_explicit_ceiling_wins_over_the_contract() {
        let mut contract = sample_contract();
        contract.host = HostProfile::detect();
        let (_dir, path) = write_contract(&contract);

        let resolved = resolve_admission_limit(Some(16), Some(&path), &HostProfile::detect());
        assert_eq!(resolved, AdmissionLimit::Configured(16));
        assert_eq!(resolved.limit(), Some(16));
    }

    #[test]
    fn an_explicit_zero_disables_shedding_and_never_consults_the_contract() {
        // `max_concurrent_requests = 0` is today's spelling of "shedding off".
        // A committed contract must not quietly switch it back on.
        let mut contract = sample_contract();
        contract.host = HostProfile::detect();
        let (_dir, path) = write_contract(&contract);

        let resolved = resolve_admission_limit(Some(0), Some(&path), &HostProfile::detect());
        assert_eq!(resolved, AdmissionLimit::Unlimited);
        assert_eq!(resolved.limit(), None);
    }

    #[test]
    fn the_contract_supplies_the_limit_when_no_ceiling_is_configured() {
        let mut contract = sample_contract();
        contract.host = HostProfile::detect();
        let (_dir, path) = write_contract(&contract);

        let resolved = resolve_admission_limit(None, Some(&path), &HostProfile::detect());
        assert_eq!(resolved, AdmissionLimit::Contract(64));
    }

    #[test]
    fn a_contract_measured_on_another_host_class_is_not_enforced() {
        // Throttling a 64-core production box to a 2-core laptop's proven
        // envelope would be a self-inflicted outage.
        let mut contract = sample_contract();
        contract.host = HostProfile {
            logical_cpus: HostProfile::detect().logical_cpus.saturating_add(7),
            ..HostProfile::detect()
        };
        let (_dir, path) = write_contract(&contract);

        assert_eq!(
            resolve_admission_limit(None, Some(&path), &HostProfile::detect()),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn an_unreadable_or_malformed_contract_leaves_admission_unlimited() {
        // Failing *closed* here would mean a typo'd path sheds every request.
        let missing = std::path::Path::new("/nonexistent/capacity.lock");
        assert_eq!(
            resolve_admission_limit(None, Some(missing), &HostProfile::detect()),
            AdmissionLimit::Unlimited
        );

        let dir = tempfile::tempdir().expect("temp dir");
        let path = dir.path().join(CONTRACT_FILE_NAME);
        std::fs::write(&path, "not = = a contract").expect("write garbage");
        assert_eq!(
            resolve_admission_limit(None, Some(&path), &HostProfile::detect()),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn no_contract_configured_leaves_todays_behaviour_untouched() {
        assert_eq!(
            resolve_admission_limit(None, None, &HostProfile::detect()),
            AdmissionLimit::Unlimited
        );
        assert_eq!(
            resolve_admission_limit(Some(32), None, &HostProfile::detect()),
            AdmissionLimit::Configured(32)
        );
    }

    // ── profile default ceiling (#3057) ─────────────────────────────────

    #[test]
    fn the_profile_default_applies_when_nothing_else_is_set() {
        let resolved =
            resolve_admission_limit_with_default(None, None, &HostProfile::detect(), Some(320));
        assert_eq!(resolved, AdmissionLimit::ProfileDefault(320));
        assert_eq!(resolved.limit(), Some(320));
        assert_eq!(resolved.source(), "profile default");
    }

    #[test]
    fn explicit_settings_win_over_the_profile_default() {
        let host = HostProfile::detect();
        assert_eq!(
            resolve_admission_limit_with_default(Some(16), None, &host, Some(320)),
            AdmissionLimit::Configured(16)
        );
        // An explicit `0` still turns shedding off.
        assert_eq!(
            resolve_admission_limit_with_default(Some(0), None, &host, Some(320)),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn the_contract_wins_over_the_profile_default() {
        let mut contract = sample_contract();
        contract.host = HostProfile::detect();
        let (_dir, path) = write_contract(&contract);
        assert_eq!(
            resolve_admission_limit_with_default(
                None,
                Some(&path),
                &HostProfile::detect(),
                Some(320)
            ),
            AdmissionLimit::Contract(64)
        );
    }

    #[test]
    fn contract_failures_fall_back_to_the_profile_default() {
        let host = HostProfile::detect();
        let missing = std::path::Path::new("/nonexistent/capacity.lock");
        assert_eq!(
            resolve_admission_limit_with_default(None, Some(missing), &host, Some(320)),
            AdmissionLimit::ProfileDefault(320)
        );

        let mut contract = sample_contract();
        contract.host = HostProfile {
            logical_cpus: host.logical_cpus.saturating_add(7),
            ..host.clone()
        };
        let (_dir, path) = write_contract(&contract);
        assert_eq!(
            resolve_admission_limit_with_default(None, Some(&path), &host, Some(320)),
            AdmissionLimit::ProfileDefault(320)
        );
    }

    #[test]
    fn a_zero_profile_default_never_sheds_everything() {
        assert_eq!(
            resolve_admission_limit_with_default(None, None, &HostProfile::detect(), Some(0)),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn the_configured_wrapper_threads_the_profile_default() {
        assert_eq!(
            resolve_configured_admission_limit_with_default(None, None, Some(320)),
            AdmissionLimit::ProfileDefault(320)
        );
        assert_eq!(
            resolve_configured_admission_limit_with_default(None, Some(""), Some(320)),
            AdmissionLimit::ProfileDefault(320)
        );
        assert_eq!(
            resolve_configured_admission_limit_with_default(Some(0), None, Some(320)),
            AdmissionLimit::Unlimited
        );
    }

    // ── calibrated profile (#2418) ──────────────────────────────────────

    fn local_contract_under(profile: &str) -> (tempfile::TempDir, std::path::PathBuf) {
        let mut contract = sample_contract();
        contract.host = HostProfile::detect();
        contract.calibration.profile = profile.to_owned();
        write_contract(&contract)
    }

    #[test]
    fn a_contract_calibrated_under_another_profile_fails_open() {
        let (_dir, path) = local_contract_under("staging");
        let host = HostProfile::detect();
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, Some(320), Some("prod")),
            AdmissionLimit::ProfileDefault(320)
        );
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, None, Some("prod")),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn a_contract_calibrated_under_the_running_profile_is_enforced() {
        let (_dir, path) = local_contract_under("prod");
        let host = HostProfile::detect();
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, Some(320), Some("prod")),
            AdmissionLimit::Contract(64)
        );
    }

    #[test]
    fn profile_aliases_and_case_compare_equal() {
        let (_dir, path) = local_contract_under("production");
        let host = HostProfile::detect();
        for running in ["prod", "PROD", " production "] {
            assert_eq!(
                resolve_admission_limit_for_profile(None, Some(&path), &host, None, Some(running)),
                AdmissionLimit::Contract(64),
                "{running}"
            );
        }
    }

    #[test]
    fn custom_profile_names_must_match_exactly() {
        let (_dir, path) = local_contract_under("staging");
        let host = HostProfile::detect();
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, None, Some("staging")),
            AdmissionLimit::Contract(64)
        );
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, None, Some("Staging")),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn a_blank_calibrated_profile_matches_no_named_profile() {
        let (_dir, path) = local_contract_under("  ");
        let host = HostProfile::detect();
        assert_eq!(
            resolve_admission_limit_for_profile(None, Some(&path), &host, None, Some("prod")),
            AdmissionLimit::Unlimited
        );
    }

    #[test]
    fn an_unknown_runtime_profile_skips_the_profile_check() {
        let (_dir, path) = local_contract_under("staging");
        let host = HostProfile::detect();
        for running in [None, Some(""), Some("  ")] {
            assert_eq!(
                resolve_admission_limit_for_profile(None, Some(&path), &host, None, running),
                AdmissionLimit::Contract(64),
                "{running:?}"
            );
        }
    }

    #[test]
    fn the_configured_wrapper_checks_the_profile() {
        let (_dir, path) = local_contract_under("staging");
        let path = path.to_str().expect("utf-8 path");
        assert_eq!(
            resolve_configured_admission_limit_for_profile(
                None,
                Some(path),
                Some(320),
                Some("prod")
            ),
            AdmissionLimit::ProfileDefault(320)
        );
        assert_eq!(
            resolve_configured_admission_limit_for_profile(
                None,
                Some(path),
                Some(320),
                Some("staging")
            ),
            AdmissionLimit::Contract(64)
        );
    }
}