dwara_core/snapshot/

mod.rs

//! Config compile pipeline: validate -> compile -> publish (feature analysis
//! section 9.2).
//!
//! The pipeline is split into a pure half and an effectful half:
//!
//! - [`validate`] checks semantic integrity that the schema deliberately
//!   deferred (reference resolution, duplicate names, port conflicts,
//!   credential well-formedness). It returns ALL issues, never fail-fast.
//! - [`compile`] turns a validated [`Gateway`] into a [`Compiled`] value:
//!   compiled route structures plus a content hash. This is where schema-valid
//!   config can still fail (invalid regex, conflicting route templates).
//! - [`ConfigState::compile_and_publish`] stamps a monotonic generation id and
//!   atomically installs the result behind an `ArcSwap`. Rollback semantics
//!   are "atomic not-publish": on ANY validation or compile failure the swap
//!   never happens and the currently-published snapshot remains untouched.
//!
//! Route matching model (v1):
//!
//! - `exact` routes are mounted in a `matchit` radix router; path parameters
//!   like `/users/{id}` are supported by the router itself.
//! - `regex` routes are compiled into a shared `regex::RegexSet`; the first
//!   matching pattern (declaration order) wins.
//! - `prefix` routes are kept in an ordered list and matched by
//!   longest-prefix at lookup time. `matchit` is exact-template matching, so
//!   prefix semantics are modeled explicitly rather than by mounting a
//!   trailing catch-all; that keeps parameter capture out of prefix routes.
//! - Lookup precedence: exact, then regex, then longest prefix.
//!
//! Content hash: a fast non-cryptographic `DefaultHasher` (SipHash-1-3) over
//! the normalized YAML serialization of the gateway. Its purpose is change
//! detection / generation identity, NOT cryptographic integrity; it is not
//! suitable for adversarial settings. The same hashing step backs a public
//! per-entity variant ([`entity_content_hash`]) so tooling can compare
//! single entities the way the gateway compares whole generations.

use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};
use std::str::FromStr as _;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};

use arc_swap::ArcSwap;

use crate::config::{
    gateway_to_yaml, Credential, Gateway, ListenerProtocol, PathMatchKind, PathRewrite, Route,
    RouteAction, TlsMode, TranslationKind, ZeroRttPolicy,
};

/// One semantic-validation finding. Operators get every issue at once, not a
/// fail-fast first error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationIssue {
    /// Entity kind, e.g. `route`, `service`, `listener`.
    pub entity: String,
    /// Name of the offending entity.
    pub name: String,
    /// Field (or near-field locator) the issue concerns.
    pub field: String,
    pub message: String,
}

impl std::fmt::Display for ValidationIssue {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{} '{}.{}': {}",
            self.entity, self.name, self.field, self.message
        )
    }
}

/// Error produced by the compile pipeline. Validation failures carry every
/// issue; compile failures name the route and pattern at fault.
#[derive(Debug)]
pub enum CompileError {
    Validation(Vec<ValidationIssue>),
    InvalidRegex {
        route: String,
        pattern: String,
        message: String,
    },
    RouteConflict {
        route: String,
        pattern: String,
        message: String,
    },
    Internal(String),
}

impl std::fmt::Display for CompileError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CompileError::Validation(issues) => {
                write!(f, "config validation failed ({} issues)", issues.len())?;
                for i in issues {
                    write!(f, "\n  - {i}")?;
                }
                Ok(())
            }
            CompileError::InvalidRegex {
                route,
                pattern,
                message,
            } => write!(f, "route '{route}': invalid regex '{pattern}': {message}"),
            CompileError::RouteConflict {
                route,
                pattern,
                message,
            } => write!(
                f,
                "route '{route}': conflicting path template '{pattern}': {message}"
            ),
            CompileError::Internal(m) => write!(f, "internal compile error: {m}"),
        }
    }
}

impl std::error::Error for CompileError {}

fn issue(entity: &str, name: &str, field: &str, message: impl Into<String>) -> ValidationIssue {
    ValidationIssue {
        entity: entity.to_string(),
        name: name.to_string(),
        field: field.to_string(),
        message: message.into(),
    }
}

/// DW-103: human-readable name for an [`UpstreamProtocol`] (used in L4
/// SNI-routing validation messages).
fn upstream_protocol_name(p: crate::config::UpstreamProtocol) -> &'static str {
    match p {
        crate::config::UpstreamProtocol::Http1 => "http1",
        crate::config::UpstreamProtocol::Http2 => "http2",
        crate::config::UpstreamProtocol::H2c => "h2c",
        crate::config::UpstreamProtocol::Https => "https",
        crate::config::UpstreamProtocol::H3 => "h3",
    }
}

/// Compile-time check for a `trusted_ca_file` (#121): the file must
/// exist, be readable, and PARSE to at least one PEM certificate NOW, or
/// the config generation is rejected naming the field. A missing,
/// unreadable, or certificate-free trust bundle would otherwise publish
/// fine and fail every TLS dial to the affected upstream at request time
/// — and, the sharp case, DISABLE a JWT provider at authenticator build,
/// after which Bearer tokens pass through UNVERIFIED. Closing that torn
/// state here, at validation, is the whole point of the PEM dimension:
/// the runtime fail-closed paths (empty root store / provider disabled,
/// security/tls.rs and authn.rs) remain as a microsecond-race backstop
/// for a bundle that breaks between validate and build. PEM parsing uses
/// rustls-pki-types directly — an EXTERNAL crate, so this module's
/// position in the facade's `crate::` dependency order is untouched —
/// while anchor USABILITY (a parseable certificate the root store
/// rejects) stays enforced where the rustls root store lives, at
/// registry build.
/// Check that a file path is readable (DW-035): used for OAuth2 mTLS
/// client cert/key files. Unlike `check_trusted_ca_file`, this does NOT
/// parse the file contents — the OAuth2 client builder does that at
/// build time and logs a disabling error on a parse failure (the
/// upstream still proxies, just without the OAuth2 Bearer token).
fn check_file_readable(
    entity: &str,
    name: &str,
    field: &str,
    path: &str,
    issues: &mut Vec<ValidationIssue>,
) {
    if !std::path::Path::new(path).is_file() {
        issues.push(issue(
            entity,
            name,
            field,
            format!("{field} '{path}' is not a readable file"),
        ));
    }
}

fn check_trusted_ca_file(
    entity: &str,
    name: &str,
    field: &str,
    path: &str,
    issues: &mut Vec<ValidationIssue>,
) {
    use rustls_pki_types::pem::PemObject;

    if let Err(e) = std::fs::File::open(path) {
        issues.push(issue(
            entity,
            name,
            field,
            format!("{field} '{path}' is not a readable file: {e}"),
        ));
        return;
    }
    // Non-PEM text between blocks is skipped (real bundles carry
    // comments), so `Ok([])` means the file holds no CERTIFICATE
    // sections at all; an Err is a read failure (e.g. a directory:
    // File::open succeeds on Unix, the read does not) or a malformed
    // PEM block.
    let parsed = rustls_pki_types::CertificateDer::pem_file_iter(path).and_then(|iter| {
        iter.collect::<Result<Vec<rustls_pki_types::CertificateDer<'static>>, _>>()
    });
    match parsed {
        Ok(certs) if !certs.is_empty() => {}
        Ok(_) => issues.push(issue(
            entity,
            name,
            field,
            format!(
                "{field} '{path}' holds no usable CA certificates \
                 (the PEM bundle must list at least one CERTIFICATE)"
            ),
        )),
        Err(e) => issues.push(issue(
            entity,
            name,
            field,
            format!(
                "{field} '{path}' could not be parsed as a PEM \
                 certificate bundle: {e}"
            ),
        )),
    }
}

/// Validate one `authorization` block (#123: shared by every attachment
/// level — route, service, listener, consumer, and gateway/global). The
/// checks are identical at every level: consumer/group references must
/// resolve against the configured consumers, every IP ACL entry must
/// parse as an IP/CIDR (the trusted-proxies parser), a block carrying NO
/// rules at all is rejected (always an authoring mistake — omit the
/// block), and a `/0` entry in the ALLOW list is rejected (allow-all
/// filters nothing; the intended shape is `default: allow`; `/0` in the
/// DENY list is meaningful — deny-all — and accepted).
fn validate_authz(
    entity: &str,
    name: &str,
    authz: &crate::config::Authz,
    consumers: &std::collections::BTreeSet<&str>,
    consumer_groups: &std::collections::BTreeSet<&str>,
    issues: &mut Vec<ValidationIssue>,
) {
    let field_prefix = "authorization".to_string();
    let empty = authz.allowed_consumers.is_empty()
        && authz.denied_consumers.is_empty()
        && authz.allowed_groups.is_empty()
        && authz.denied_groups.is_empty()
        && authz.required_scopes.is_empty()
        && authz.required_claims.is_empty()
        && authz.ip_acl.is_none()
        && authz.geoip.is_none();
    if empty {
        issues.push(issue(
            entity,
            name,
            "authorization",
            "carries no rules (no consumers, groups, scopes, claims, ip_acl, \
             or geoip) and is always a mistake: omit the authorization block \
             entirely",
        ));
    }
    for (side, entries) in [
        ("allowed_consumers", &authz.allowed_consumers),
        ("denied_consumers", &authz.denied_consumers),
    ] {
        for entry in entries.iter() {
            if !consumers.contains(entry.as_str()) {
                issues.push(issue(
                    entity,
                    name,
                    &format!("{field_prefix}.{side}"),
                    format!("references unknown consumer '{entry}'"),
                ));
            }
        }
    }
    for (side, entries) in [
        ("allowed_groups", &authz.allowed_groups),
        ("denied_groups", &authz.denied_groups),
    ] {
        for group in entries.iter() {
            if !consumer_groups.contains(group.as_str()) {
                issues.push(issue(
                    entity,
                    name,
                    &format!("{field_prefix}.{side}"),
                    format!("references group '{group}' that no consumer is a member of"),
                ));
            }
        }
    }
    if let Some(acl) = &authz.ip_acl {
        for (side, entries) in [("ip_acl.allow", &acl.allow), ("ip_acl.deny", &acl.deny)] {
            for (i, entry) in entries.iter().enumerate() {
                if crate::config::net::parse_ip_or_cidr(entry).is_none() {
                    issues.push(issue(
                        entity,
                        name,
                        &format!("{field_prefix}.{side}[{i}]"),
                        format!(
                            "'{entry}' is not an IP address or CIDR (e.g. 10.0.0.0/8 \
                             or 2001:db8::/32)"
                        ),
                    ));
                } else if side == "ip_acl.allow"
                    && crate::config::net::parse_ip_or_cidr(entry)
                        .is_some_and(|(_, prefix)| prefix == 0)
                {
                    issues.push(issue(
                        entity,
                        name,
                        &format!("{field_prefix}.{side}[{i}]"),
                        format!(
                            "'{entry}' allows every address and filters nothing; \
                             use 'default: allow' instead of an allow-all entry"
                        ),
                    ));
                }
            }
        }
    }
}

/// Validate one `cors` block (DW-027). The origin list must be a
/// non-empty closed set of well-formed `http(s)` origins (or `*`);
/// wildcard origins/headers cannot combine with credentials (Fetch spec:
/// `*` is not a valid allow-origin/allow-headers value on a credentialed
/// response); methods must be valid HTTP tokens; header lists must hold
/// valid header names (or `*` for `allowed_headers` only).
fn validate_cors(name: &str, cors: &crate::config::Cors, issues: &mut Vec<ValidationIssue>) {
    if cors.allowed_origins.is_empty() {
        issues.push(issue(
            "route",
            name,
            "cors.allowed_origins",
            "allowed_origins is empty: a cors block with no origins filters nothing \
             and is always a mistake; omit the cors block to disable CORS",
        ));
    }
    let wildcard = cors.allowed_origins.iter().any(|o| o == "*");
    if wildcard && cors.allow_credentials {
        issues.push(issue(
            "route",
            name,
            "cors.allowed_origins",
            "'*' cannot be combined with allow_credentials (the Fetch spec forbids \
             wildcard credentialed responses); list explicit origins instead",
        ));
    }
    for (i, origin) in cors.allowed_origins.iter().enumerate() {
        if origin == "*" {
            continue;
        }
        // Normalize exactly like the runtime matcher: lowercase scheme
        // and host, default port dropped. Anything the matcher would not
        // itself accept is an authoring error caught here.
        if crate::config::normalize_origin(origin).is_none() {
            issues.push(issue(
                "route",
                name,
                &format!("cors.allowed_origins[{i}]"),
                format!(
                    "'{origin}' is not a well-formed origin (expected scheme://host[:port] \
                     with an http or https scheme and no path, e.g. https://api.example.com, \
                     or the single entry '*')"
                ),
            ));
        }
    }
    if wildcard && cors.allowed_origins.len() > 1 {
        issues.push(issue(
            "route",
            name,
            "cors.allowed_origins",
            "'*' cannot be combined with other origins ('*' already matches everything)",
        ));
    }
    for (i, m) in cors.allowed_methods.iter().enumerate() {
        if hyper::Method::from_bytes(m.as_bytes()).is_err() {
            issues.push(issue(
                "route",
                name,
                &format!("cors.allowed_methods[{i}]"),
                format!("'{m}' is not a valid HTTP method token"),
            ));
        }
    }
    let header_lists = [
        ("cors.allowed_headers", &cors.allowed_headers, true),
        ("cors.expose_headers", &cors.expose_headers, false),
    ];
    for (field, list, allows_wildcard) in header_lists {
        for (i, h) in list.iter().enumerate() {
            if h == "*" {
                if !allows_wildcard {
                    issues.push(issue(
                        "route",
                        name,
                        &format!("{field}[{i}]"),
                        "'*' is only valid in allowed_headers (expose_headers must name \
                         the headers to expose)",
                    ));
                } else if cors.allow_credentials {
                    issues.push(issue(
                        "route",
                        name,
                        &format!("{field}[{i}]"),
                        "'*' cannot be combined with allow_credentials (the Fetch spec \
                         forbids wildcard allow-headers on credentialed preflights); \
                         list explicit header names instead",
                    ));
                }
                continue;
            }
            if hyper::header::HeaderName::from_bytes(h.as_bytes()).is_err() {
                issues.push(issue(
                    "route",
                    name,
                    &format!("{field}[{i}]"),
                    format!("'{h}' is not a valid HTTP header name"),
                ));
            }
        }
    }
}

/// Validate one `compression` block (DW-027): non-empty duplicate-free
/// algorithm list, level within 0-22 (per-algorithm clamping happens at
/// encode time), and non-empty content-type prefixes.
fn validate_compression(
    name: &str,
    compression: &crate::config::Compression,
    issues: &mut Vec<ValidationIssue>,
) {
    if compression.algorithms.is_empty() {
        issues.push(issue(
            "route",
            name,
            "compression.algorithms",
            "algorithms is empty: a compression block with no algorithms compresses \
             nothing and is always a mistake; omit the compression block to disable it",
        ));
    }
    let mut seen = std::collections::BTreeSet::new();
    for (i, a) in compression.algorithms.iter().enumerate() {
        if !seen.insert(a) {
            issues.push(issue(
                "route",
                name,
                &format!("compression.algorithms[{i}]"),
                format!("algorithm '{a:?}' is listed more than once"),
            ));
        }
    }
    if let Some(level) = compression.level {
        if level > 22 {
            issues.push(issue(
                "route",
                name,
                "compression.level",
                format!(
                    "level {level} is out of range: 0-22 (clamped per algorithm: \
                         gzip 0-9, brotli 0-11, zstd 0-22)"
                ),
            ));
        }
    }
    for (field, entries) in [
        ("compression.content_types", &compression.content_types),
        (
            "compression.excluded_content_types",
            &compression.excluded_content_types,
        ),
    ] {
        for (i, entry) in entries.iter().enumerate() {
            let t = entry.trim().to_lowercase();
            if t.is_empty() || t.contains(char::is_whitespace) {
                issues.push(issue(
                    "route",
                    name,
                    &format!("{field}[{i}]"),
                    format!(
                        "'{entry}' is not a content-type prefix (expected a non-empty \
                         token like 'text/' or 'application/json')"
                    ),
                ));
            }
        }
    }
}

/// Validate one `request_limits` block (DW-027): at least one limit set,
/// every set limit >= 1.
fn validate_request_limits(
    name: &str,
    limits: &crate::config::RequestLimits,
    issues: &mut Vec<ValidationIssue>,
) {
    if limits.max_body_bytes.is_none()
        && limits.max_header_count.is_none()
        && limits.max_header_bytes.is_none()
    {
        issues.push(issue(
            "route",
            name,
            "limits",
            "carries no limits (no max_body_bytes, max_header_count, or max_header_bytes) \
             and is always a mistake: omit the limits block entirely",
        ));
    }
    if let Some(0) = limits.max_body_bytes {
        issues.push(issue(
            "route",
            name,
            "limits.max_body_bytes",
            "max_body_bytes must be > 0 (0 would reject every request with a body)",
        ));
    }
    if let Some(0) = limits.max_header_count {
        issues.push(issue(
            "route",
            name,
            "limits.max_header_count",
            "max_header_count must be > 0",
        ));
    }
    if let Some(0) = limits.max_header_bytes {
        issues.push(issue(
            "route",
            name,
            "limits.max_header_bytes",
            "max_header_bytes must be > 0",
        ));
    }
}

/// Validate one `deprecation` block (DW-048): a block with no dates has
/// no effect (omit it); dates must be IMF-fixdate HTTP-dates (the only
/// form RFC 9110 generators may send — see `config::versioning`); a
/// sunset already in the past advertises a removal that already happened
/// (rejected: remove the route or extend the date — this also stops a
/// long-lived deployment from silently re-publishing a stale sunset;
/// a rejected hot reload keeps the running generation, so the operator
/// must fix the date to publish ANY new config carrying it, which is the
/// fail-closed intent); sunset must not precede since; and `uri`
/// documents the `Deprecation` header, so it requires `since`. The
/// past-sunset check reads the wall clock: it is a compile-time policy
/// gate, not a per-request one.
fn validate_deprecation(
    name: &str,
    dep: &crate::config::Deprecation,
    issues: &mut Vec<ValidationIssue>,
) {
    let since = dep
        .since
        .as_deref()
        .and_then(crate::config::versioning::parse_http_date);
    let sunset = dep
        .sunset
        .as_deref()
        .and_then(crate::config::versioning::parse_http_date);
    // The no-dates check reads the RAW fields: a garbage `since` with no
    // `sunset` is a date-format error, not an empty block (reporting it
    // as both would be noise).
    if dep.since.is_none() && dep.sunset.is_none() {
        issues.push(issue(
            "route",
            name,
            "deprecation",
            "carries no dates (no since or sunset) and emits nothing: omit the \
             deprecation block entirely",
        ));
    }
    for (field, value) in [
        ("deprecation.since", &dep.since),
        ("deprecation.sunset", &dep.sunset),
    ] {
        if let Some(v) = value {
            if crate::config::versioning::parse_http_date(v).is_none() {
                issues.push(issue(
                    "route",
                    name,
                    field,
                    format!(
                        "'{v}' is not a valid HTTP-date: use the IMF-fixdate form \
                         (e.g. 'Sun, 06 Nov 1994 08:49:37 GMT')"
                    ),
                ));
            }
        }
    }
    if let Some(s) = since {
        if s.unix_seconds() < 0 {
            issues.push(issue(
                "route",
                name,
                "deprecation.since",
                "since must be 1970 or later (the RFC 9745 Deprecation header renders it \
                 as a Unix-time structured date)",
            ));
        }
    }
    if let Some(s) = sunset {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs() as i64)
            .unwrap_or(0);
        if s.unix_seconds() < now {
            issues.push(issue(
                "route",
                name,
                "deprecation.sunset",
                format!(
                    "sunset date '{}' is in the past: the route should be removed or the \
                     date extended, not advertise a removal that already happened",
                    dep.sunset.as_deref().unwrap_or_default()
                ),
            ));
        }
        if let Some(since_date) = since {
            if s.unix_seconds() < since_date.unix_seconds() {
                issues.push(issue(
                    "route",
                    name,
                    "deprecation.sunset",
                    "sunset is before since (the route would be removed before it is \
                     deprecated)",
                ));
            }
        }
    }
    if let Some(uri) = &dep.uri {
        if since.is_none() {
            issues.push(issue(
                "route",
                name,
                "deprecation.uri",
                "uri requires since: the Link rel=\"deprecation\" it emits documents the \
                 Deprecation header, which only since produces",
            ));
        }
        // The Link header is built as `<uri>; rel="deprecation"` — the
        // URI must parse AND carry no byte that breaks out of the angle
        // brackets or the quoted param.
        let parseable = match uri.parse::<hyper::Uri>() {
            Ok(u) => matches!(u.scheme_str(), Some("http") | Some("https")) && u.host().is_some(),
            Err(_) => false,
        };
        if !parseable || uri.bytes().any(|b| matches!(b, b'<' | b'>' | b'"')) {
            issues.push(issue(
                "route",
                name,
                "deprecation.uri",
                format!(
                    "'{uri}' must be an absolute http(s) URL with no '<', '>', or '\"' \
                         (it is emitted inside a Link header)"
                ),
            ));
        }
    }
}

/// Validate one `maintenance` block (DW-041): `retry_after_secs` 0 would
/// invite an immediate retry stampede against the route the operator just
/// took down (the whole point of the header is "come back later"), and an
/// empty `message` is indistinguishable from an absent one (omit it for
/// the default text).
fn validate_maintenance(
    name: &str,
    maintenance: &crate::config::Maintenance,
    issues: &mut Vec<ValidationIssue>,
) {
    if maintenance.retry_after_secs == Some(0) {
        issues.push(issue(
            "route",
            name,
            "maintenance.retry_after_secs",
            "retry_after_secs must be > 0 (0 tells clients to retry immediately against a \
             route that is down; omit the field for the 60s default)",
        ));
    }
    if maintenance
        .message
        .as_deref()
        .is_some_and(|m| m.trim().is_empty())
    {
        issues.push(issue(
            "route",
            name,
            "maintenance.message",
            "message is empty: omit the field for the default 'route under maintenance' text",
        ));
    }
}

/// Validate one `transforms` block (DW-028): no empty containers (a
/// transforms block that transforms nothing is an authoring mistake),
/// representable header names and values, no framing/hop-by-hop header
/// names (the body pipeline owns framing; `deny`-listing them here is
/// the request-smuggling guard — see `config::transforms`), sane
/// query-component bytes, and JSON pointers that parse (the shared
/// grammar in `config::transforms`, the same agreement validation
/// holds with every other runtime grammar).
fn validate_transforms(
    name: &str,
    transforms: &crate::config::transforms::Transforms,
    issues: &mut Vec<ValidationIssue>,
) {
    if transforms.request.is_none() && transforms.response.is_none() {
        issues.push(issue(
            "route",
            name,
            "transforms",
            "carries neither request nor response (nothing to transform) and is always a \
             mistake: omit the transforms block entirely",
        ));
    }
    if let Some(req) = &transforms.request {
        if req.headers.is_none() && req.query.is_none() && req.body.is_none() {
            issues.push(issue(
                "route",
                name,
                "transforms.request",
                "carries no headers, query, or body block and is always a mistake: omit it",
            ));
        }
        if let Some(headers) = &req.headers {
            validate_header_ops(name, "transforms.request.headers", headers, true, issues);
        }
        if let Some(query) = &req.query {
            validate_query_ops(name, "transforms.request.query", query, issues);
        }
        if let Some(body) = &req.body {
            validate_json_body(name, "transforms.request.body", &body.json, issues);
        }
    }
    if let Some(resp) = &transforms.response {
        if resp.headers.is_none() && resp.body.is_none() {
            issues.push(issue(
                "route",
                name,
                "transforms.response",
                "carries no headers or body block and is always a mistake: omit it",
            ));
        }
        if let Some(headers) = &resp.headers {
            validate_header_ops(name, "transforms.response.headers", headers, false, issues);
        }
        if let Some(body) = &resp.body {
            validate_json_body(name, "transforms.response.body", &body.json, issues);
        }
    }
}

/// Validate one header-ops block. `request_side` selects the forbidden
/// set: the request side forbids `host` (the gateway names the origin
/// it dials) and the framing pair; the response side forbids the
/// framing pair plus `content-encoding` (only the compression pipeline
/// may manage it — an op that stripped it without decoding would
/// corrupt the body, and one that added it would misdescribe bytes it
/// did not encode).
fn validate_header_ops(
    route: &str,
    field: &str,
    ops: &crate::config::transforms::HeaderOps,
    request_side: bool,
    issues: &mut Vec<ValidationIssue>,
) {
    use crate::config::transforms as t;
    if ops.set.is_empty() && ops.add.is_empty() && ops.remove.is_empty() && ops.rename.is_empty() {
        issues.push(issue(
            "route",
            route,
            field,
            "carries no set, add, remove, or rename entries and is always a mistake: omit it",
        ));
    }
    let names: Vec<(&str, String)> = ops
        .set
        .keys()
        .map(|k| ("set", k.clone()))
        .chain(ops.add.keys().map(|k| ("add", k.clone())))
        .chain(ops.remove.iter().map(|k| ("remove", k.clone())))
        .chain(ops.rename.keys().map(|k| ("rename", k.clone())))
        .chain(ops.rename.values().map(|k| ("rename (to)", k.clone())))
        .collect();
    for (op, header) in &names {
        if hyper::header::HeaderName::from_bytes(header.as_bytes()).is_err() {
            issues.push(issue(
                "route",
                route,
                field,
                format!("'{header}' ({op}) is not a valid HTTP header name"),
            ));
            continue;
        }
        let forbidden = if request_side {
            t::is_forbidden_request_header(header)
        } else {
            t::is_forbidden_response_header(header)
        };
        if forbidden {
            issues.push(issue(
                "route",
                route,
                field,
                format!(
                    "'{header}' ({op}) is a framing/hop-by-hop header the gateway's body \
                     pipeline owns: transforms may not touch it (request smuggling and \
                     body-corruption guard)"
                ),
            ));
        }
    }
    for (op, value) in ops
        .set
        .values()
        .map(|v| ("set", v))
        .chain(ops.add.values().map(|v| ("add", v)))
    {
        if hyper::header::HeaderValue::from_str(value).is_err() {
            issues.push(issue(
                "route",
                route,
                field,
                format!(
                    "the '{op}' value '{value}' is not representable in an HTTP header \
                     (control characters and non-visible bytes are rejected)"
                ),
            ));
        }
    }
    for (from, to) in &ops.rename {
        if from == to {
            issues.push(issue(
                "route",
                route,
                field,
                format!("rename '{from}' -> '{to}' is a no-op: rename to a different name"),
            ));
        }
    }
}

/// Validate one query-ops block (DW-028): names and values must be
/// plain ASCII without the query structural bytes (`&` separates
/// pairs, `=` separates key from value, `#` would start a fragment).
/// Everything else the runtime percent-encodes on emit.
fn validate_query_ops(
    route: &str,
    field: &str,
    ops: &crate::config::transforms::QueryOps,
    issues: &mut Vec<ValidationIssue>,
) {
    if ops.set.is_empty() && ops.add.is_empty() && ops.remove.is_empty() && ops.rename.is_empty() {
        issues.push(issue(
            "route",
            route,
            field,
            "carries no set, add, remove, or rename entries and is always a mistake: omit it",
        ));
    }
    let check = |kind: &str, key: &str, value: Option<&str>, issues: &mut Vec<ValidationIssue>| {
        let bad_name = key.is_empty()
            || key.bytes().any(|b| {
                !b.is_ascii() || b.is_ascii_control() || matches!(b, b'&' | b'=' | b'#' | b' ')
            });
        if bad_name {
            issues.push(issue(
                "route",
                route,
                field,
                format!(
                    "the {kind} name '{key}' is not a plain query name (non-empty ASCII, no \
                     '&', '=', '#', or spaces)"
                ),
            ));
        }
        if let Some(v) = value {
            if v.bytes()
                .any(|b| !b.is_ascii() || b.is_ascii_control() || matches!(b, b'&' | b'#'))
            {
                issues.push(issue(
                    "route",
                    route,
                    field,
                    format!(
                        "the {kind} value '{v}' is not representable in a query string \
                         (ASCII without '&' or '#')"
                    ),
                ));
            }
        }
    };
    for (k, v) in &ops.set {
        check("set", k, Some(v), issues);
    }
    for (k, v) in &ops.add {
        check("add", k, Some(v), issues);
    }
    for k in &ops.remove {
        check("remove", k, None, issues);
    }
    for (from, to) in &ops.rename {
        check("rename", from, None, issues);
        check("rename (to)", to, None, issues);
        if from == to {
            issues.push(issue(
                "route",
                route,
                field,
                format!("rename '{from}' -> '{to}' is a no-op: rename to a different key"),
            ));
        }
    }
}

/// Validate one JSON body transform (DW-028): non-empty ops, a positive
/// cap, pointers that parse (the shared `config::transforms` grammar),
/// and no `remove` of the whole document.
fn validate_json_body(
    route: &str,
    field: &str,
    json: &crate::config::transforms::JsonBodyTransform,
    issues: &mut Vec<ValidationIssue>,
) {
    use crate::config::transforms as t;
    if json.ops.is_empty() {
        issues.push(issue(
            "route",
            route,
            &format!("{field}.json.ops"),
            "ops is empty: a body transform that transforms nothing is always a mistake \
             (and still pays the content-type gate); omit the body block",
        ));
    }
    if json.max_bytes == 0 {
        issues.push(issue(
            "route",
            route,
            &format!("{field}.json.max_bytes"),
            "max_bytes must be > 0 (0 would fail every body against the transform cap)",
        ));
    }
    for (i, op) in json.ops.iter().enumerate() {
        let path = match op {
            t::JsonOp::Set { path, .. } => path,
            t::JsonOp::Remove { path } => path,
        };
        match t::JsonPointer::parse(path) {
            None => issues.push(issue(
                "route",
                route,
                &format!("{field}.json.ops[{i}].path"),
                format!(
                    "'{path}' is not an RFC 6901 JSON pointer (start with '/', use ~0 and ~1 \
                     for '~' and '/', e.g. /items/0/id; '' addresses the whole document)"
                ),
            )),
            Some(pointer) => {
                if matches!(op, t::JsonOp::Remove { .. }) && pointer.is_root() {
                    issues.push(issue(
                        "route",
                        route,
                        &format!("{field}.json.ops[{i}].path"),
                        "remove at the root pointer ('') would delete the whole document — \
                         there is no 'no body' state to forward; use set at the root to \
                         replace it",
                    ));
                }
            }
        }
    }
}

/// Validate one `security_headers` block (DW-028): at least one header
/// opted in, HSTS directives that compose (0 is the RFC 6797 deletion
/// signal this policy cannot express; the subdomains/preload
/// directives are meaningless without a max-age, and the preload list
/// requires includeSubDomains), and a CSP that is non-empty and
/// representable in an HTTP header (the runtime's silent-skip backstop
/// must stay unreachable).
fn validate_security_headers(
    name: &str,
    sh: &crate::config::transforms::SecurityHeaders,
    issues: &mut Vec<ValidationIssue>,
) {
    if sh.hsts_max_age_secs.is_none()
        && !sh.nosniff
        && sh.content_security_policy.is_none()
        && sh.frame_options.is_none()
    {
        issues.push(issue(
            "route",
            name,
            "security_headers",
            "carries no policy (no HSTS, nosniff, CSP, or frame_options) and is always a \
             mistake: omit the security_headers block to disable injection",
        ));
    }
    if sh.hsts_max_age_secs == Some(0) {
        issues.push(issue(
            "route",
            name,
            "security_headers.hsts_max_age_secs",
            "hsts_max_age_secs must be > 0 (max-age=0 is the RFC 6797 deletion signal — \
             delete the field to stop emitting HSTS on this route)",
        ));
    }
    if sh.hsts_max_age_secs.is_none() && (sh.hsts_include_subdomains || sh.hsts_preload) {
        issues.push(issue(
            "route",
            name,
            "security_headers.hsts_include_subdomains",
            "include_subdomains/preload require hsts_max_age_secs: the directives only \
             exist inside a Strict-Transport-Security header, which a max-age starts",
        ));
    }
    if sh.hsts_preload && !sh.hsts_include_subdomains {
        issues.push(issue(
            "route",
            name,
            "security_headers.hsts_preload",
            "preload requires include_subdomains (the HSTS preload list rejects entries \
             without it; emitting a header the list would refuse is an authoring mistake)",
        ));
    }
    if sh
        .content_security_policy
        .as_deref()
        .is_some_and(|p| p.trim().is_empty())
    {
        issues.push(issue(
            "route",
            name,
            "security_headers.content_security_policy",
            "content_security_policy is empty: omit the field to stop emitting CSP on \
             this route",
        ));
    }
    if let Some(csp) = sh.content_security_policy.as_deref() {
        // The runtime stamps the policy inside a representable-only skip
        // (`if let Ok(v) = HeaderValue::from_str(..)`); validation keeps
        // that skip unreachable, so a publishable config can never carry
        // a CSP the edge would silently not emit. The realistic trap is a
        // YAML block scalar's trailing newline.
        if !csp.trim().is_empty() && hyper::header::HeaderValue::from_str(csp).is_err() {
            issues.push(issue(
                "route",
                name,
                "security_headers.content_security_policy",
                "content_security_policy is not representable in an HTTP header (control \
                 characters are rejected — including the trailing newline a YAML block \
                 scalar adds)",
            ));
        }
    }
}

/// DW-106: maximum allowed linear memory for a nano-service module.
const NANO_SERVICE_MAX_MEMORY: usize = 67_108_864; // 64 MiB

/// DW-106: maximum allowed execution timeout for a nano-service module.
const NANO_SERVICE_MAX_TIMEOUT_MS: u64 = 5_000;

/// Validate a nano-service route action (DW-106): the module file must
/// exist and be readable, `memory_limit` must be > 0 and <= 64 MiB, and
/// `execution_timeout_ms` must be > 0 and <= 5000ms. (The nano-service
/// runtime dispatch is compiled into every build; no cargo feature.)
fn validate_nano_service(
    name: &str,
    nano: &crate::config::NanoServiceAction,
    issues: &mut Vec<ValidationIssue>,
) {
    if nano.module.trim().is_empty() {
        issues.push(issue(
            "route",
            name,
            "action.module",
            "nano_service module path must be non-empty",
        ));
    } else if !std::path::Path::new(&nano.module).exists() {
        issues.push(issue(
            "route",
            name,
            "action.module",
            format!(
                "nano_service module file '{}' does not exist (checked at config publish time)",
                nano.module
            ),
        ));
    }
    if nano.memory_limit == 0 {
        issues.push(issue(
            "route",
            name,
            "action.memory_limit",
            "nano_service memory_limit must be > 0 (omit for the default 1 MiB)",
        ));
    } else if nano.memory_limit > NANO_SERVICE_MAX_MEMORY {
        issues.push(issue(
            "route",
            name,
            "action.memory_limit",
            format!(
                "nano_service memory_limit ({}) exceeds the maximum {} (64 MiB)",
                nano.memory_limit, NANO_SERVICE_MAX_MEMORY
            ),
        ));
    }
    if nano.execution_timeout_ms == 0 {
        issues.push(issue(
            "route",
            name,
            "action.execution_timeout_ms",
            "nano_service execution_timeout_ms must be > 0 (omit for the default 100ms)",
        ));
    } else if nano.execution_timeout_ms > NANO_SERVICE_MAX_TIMEOUT_MS {
        issues.push(issue(
            "route",
            name,
            "action.execution_timeout_ms",
            format!(
                "nano_service execution_timeout_ms ({}) exceeds the maximum {}ms",
                nano.execution_timeout_ms, NANO_SERVICE_MAX_TIMEOUT_MS
            ),
        ));
    }
}

/// Validate one `cache` block (DW-037): bounded ttl/stale window/body
/// cap, and a vary list whose entries are real header names, dedupli-
/// cated, and not one of the names the variance model forbids; the
/// DW-038 coalescing wait bound (the grammar lives in `config::cache`,
/// the same validate/compile split as every other route block).
fn validate_route_cache(
    name: &str,
    cache: &crate::config::cache::RouteCache,
    issues: &mut Vec<ValidationIssue>,
) {
    use crate::config::cache::{
        forbidden_vary_reason, MAX_CACHE_MAX_BODY_BYTES, MAX_CACHE_STALE_SECS, MAX_CACHE_TTL_SECS,
        MAX_CACHE_VARY_HEADERS, MAX_COALESCE_WAIT_MS,
    };
    if cache.ttl_secs == 0 {
        issues.push(issue(
            "route",
            name,
            "cache.ttl_secs",
            "ttl_secs must be >= 1 (a zero lifetime would expire every entry immediately; \
             omit the cache block to disable caching)",
        ));
    } else if cache.ttl_secs > MAX_CACHE_TTL_SECS {
        issues.push(issue(
            "route",
            name,
            "cache.ttl_secs",
            format!(
                "ttl_secs must be <= {MAX_CACHE_TTL_SECS} (24 h; longer freshness belongs to a \
                 CDN in front of the gateway)"
            ),
        ));
    }
    if let Some(swr) = cache.stale_while_revalidate_secs {
        if swr > MAX_CACHE_STALE_SECS {
            issues.push(issue(
                "route",
                name,
                "cache.stale_while_revalidate_secs",
                format!(
                    "stale_while_revalidate_secs must be <= {MAX_CACHE_STALE_SECS} (24 h, \
                     symmetric with the ttl bound)"
                ),
            ));
        }
    }
    if cache.max_body_bytes == 0 {
        issues.push(issue(
            "route",
            name,
            "cache.max_body_bytes",
            "max_body_bytes must be >= 1 (0 would store nothing; omit the cache block to \
             disable caching)",
        ));
    } else if cache.max_body_bytes > MAX_CACHE_MAX_BODY_BYTES {
        issues.push(issue(
            "route",
            name,
            "cache.max_body_bytes",
            format!(
                "max_body_bytes must be <= {MAX_CACHE_MAX_BODY_BYTES} (16 MiB; larger bodies \
                 stream through unstored)"
            ),
        ));
    }
    if cache.vary.len() > MAX_CACHE_VARY_HEADERS {
        issues.push(issue(
            "route",
            name,
            "cache.vary",
            format!(
                "at most {MAX_CACHE_VARY_HEADERS} vary headers per route (each multiplies the \
                 entry key space)"
            ),
        ));
    }
    let mut seen: Vec<String> = Vec::new();
    for (i, raw) in cache.vary.iter().enumerate() {
        let trimmed = raw.trim();
        let lowered = trimmed.to_ascii_lowercase();
        let field = format!("cache.vary[{i}]");
        if lowered.is_empty()
            || lowered != trimmed
            || lowered.starts_with('-')
            || lowered.ends_with('-')
            || !lowered
                .bytes()
                .all(|b| b.is_ascii_lowercase() || b == b'-' || b.is_ascii_digit())
        {
            issues.push(issue(
                "route",
                name,
                &field,
                format!("'{raw}' is not a header name (use the trimmed lowercase form)"),
            ));
            continue;
        }
        if let Some(reason) = forbidden_vary_reason(&lowered) {
            issues.push(issue(
                "route",
                name,
                &field,
                format!("'{lowered}' cannot vary: {reason}"),
            ));
            continue;
        }
        if seen.contains(&lowered) {
            issues.push(issue(
                "route",
                name,
                &field,
                format!("duplicate vary header '{lowered}' (deduplicate the list)"),
            ));
        }
        seen.push(lowered);
    }
    // DW-038: the coalescing follower wait bound. 0 would time every
    // follower out before the leader could possibly answer (a wait is
    // the only reason the block exists); a minute-plus wait just parks
    // clients behind a leader the route's own timeouts already bound.
    if let Some(coalescing) = &cache.coalescing {
        if coalescing.wait_ms == 0 {
            issues.push(issue(
                "route",
                name,
                "cache.coalescing.wait_ms",
                "wait_ms must be >= 1 (0 would fail every follower open before the leader \
                 answers; omit the coalescing block to disable coalescing)",
            ));
        } else if coalescing.wait_ms > MAX_COALESCE_WAIT_MS {
            issues.push(issue(
                "route",
                name,
                "cache.coalescing.wait_ms",
                format!(
                    "wait_ms must be <= {MAX_COALESCE_WAIT_MS} (60 s; a follower parked longer \
                     is a stuck request from the client's point of view)"
                ),
            ));
        }
    }
}

/// Validate one `masking` block (DW-029): a positive cap, at least one
/// pointer somewhere (a masking policy that masks nothing is an
/// authoring mistake), pointers that parse and are not the root, and
/// group names that resolve against some config consumer's membership
/// — a typo'd group name silently never masks, which is fail-OPEN, the
/// exact posture this policy forbids (same check, and same store-only
/// caveat, as authorization group rules).
fn validate_masking(
    name: &str,
    masking: &crate::config::transforms::Masking,
    consumer_groups: &std::collections::BTreeSet<&str>,
    issues: &mut Vec<ValidationIssue>,
) {
    use crate::config::transforms as t;
    if masking.fields.is_empty() && masking.groups.is_empty() {
        issues.push(issue(
            "route",
            name,
            "masking",
            "carries no fields and no groups (nothing to mask) and is always a mistake: \
             omit the masking block to disable masking on this route",
        ));
    }
    if masking.max_bytes == 0 {
        issues.push(issue(
            "route",
            name,
            "masking.max_bytes",
            "max_bytes must be > 0 (0 would fail every response against the masking cap)",
        ));
    }
    let check_pointer =
        |field: String, path: &str, issues: &mut Vec<ValidationIssue>| match t::JsonPointer::parse(
            path,
        ) {
            None => issues.push(issue(
                "route",
                name,
                &field,
                format!(
                    "'{path}' is not an RFC 6901 JSON pointer (start with '/', use ~0 and ~1 for \
                 '~' and '/', e.g. /items/0/id)"
                ),
            )),
            Some(pointer) => {
                if pointer.is_root() {
                    issues.push(issue(
                    "route",
                    name,
                    &field,
                    "the root pointer ('') would replace the whole document with the sentinel — \
                     a body the route cannot usefully serve; mask fields, not the document",
                ));
                }
            }
        };
    for (i, path) in masking.fields.iter().enumerate() {
        check_pointer(format!("masking.fields[{i}]"), path, issues);
    }
    for (group, paths) in &masking.groups {
        if group.trim().is_empty() {
            issues.push(issue(
                "route",
                name,
                "masking.groups",
                format!("group key '{group}' is empty: group names are non-empty strings"),
            ));
        }
        if !consumer_groups.contains(group.as_str()) {
            issues.push(issue(
                "route",
                name,
                "masking.groups",
                format!(
                    "group '{group}' matches no configured consumer's groups membership — a \
                     typo here silently never masks (fail-open); grant a consumer the group \
                     or fix the name (store-managed consumers carry groups the config cannot \
                     see, the known caveat of this check)"
                ),
            ));
        }
        if paths.is_empty() {
            issues.push(issue(
                "route",
                name,
                "masking.groups",
                format!(
                    "group '{group}' carries no pointers and is always a mistake: omit \
                         the entry (the route floor still applies to the group's consumers)"
                ),
            ));
        }
        for (i, path) in paths.iter().enumerate() {
            check_pointer(format!("masking.groups.{group}[{i}]"), path, issues);
        }
    }
}

/// Validate the `gateway.analytics` block (DW-043): the database path
/// must be non-empty (it is opened at startup — an empty string would
/// silently create a throwaway temp database), `flush_ms` bounded
/// (a sub-100 ms flush tick is timer churn; past 60 s the writer's
/// latency is the rollup grace's problem, not a useful knob),
/// retention monotone (a coarser table may not expire before a finer
/// one — the cascade would be recomputing from deleted history), and
/// dimensions name-valid (`[a-z0-9_]{1,32}` — the name is the rollup
/// table's `dim` key), header-representable, unique, and at most 16
/// (every dimension multiplies rollup cardinality).
fn validate_analytics(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(a) = &gateway.analytics else { return };
    if a.path.trim().is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "analytics.path",
            "analytics.path is empty: the database path must name a real file \
             (an empty path would open a throwaway temp database, losing every \
             record)",
        ));
    }
    if let Some(flush) = a.flush_ms {
        if !(100..=60_000).contains(&flush) {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.flush_ms",
                format!(
                    "flush_ms {flush} is out of range: must be 100..=60000 \
                     (below 100 is timer churn; above 60000 adds nothing the \
                     rollup grace does not already cover)"
                ),
            ));
        }
    }
    // REL-10 (#221): sampled degradation validation.
    if let Some(d) = &a.sampled_degradation {
        if !(0.0..=1.0).contains(&d.high_watermark) || d.high_watermark <= 0.0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.sampled_degradation.high_watermark",
                "high_watermark must be in (0.0, 1.0]",
            ));
        }
        if !(0.0..=1.0).contains(&d.low_watermark) {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.sampled_degradation.low_watermark",
                "low_watermark must be in [0.0, 1.0)",
            ));
        }
        if d.low_watermark >= d.high_watermark {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.sampled_degradation.low_watermark",
                "low_watermark must be < high_watermark",
            ));
        }
        if !(0.0..=1.0).contains(&d.keep_rate) || d.keep_rate <= 0.0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.sampled_degradation.keep_rate",
                "keep_rate must be in (0.0, 1.0]",
            ));
        }
    }
    if let Some(r) = &a.retention {
        let e = r.effective();
        let names = ["raw_ms", "m1_ms", "m5_ms", "h1_ms", "d1_ms"];
        for i in 0..5 {
            let v = e[i];
            let cap: i64 = match i {
                0 => 7 * 86_400_000,     // raw: a week
                1 => 30 * 86_400_000,    // 1m: a month
                2 => 90 * 86_400_000,    // 5m: a quarter
                3 => 365 * 86_400_000,   // 1h: a year
                _ => 3_650 * 86_400_000, // 1d: a decade
            };
            if v > cap {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("analytics.retention.{}", names[i]),
                    format!(
                        "{} {} ms exceeds the cap {} ms (bounded disk is the \
                         point of the store)",
                        names[i], v, cap
                    ),
                ));
            }
        }
        for w in 0..4 {
            if e[w + 1] < e[w] {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("analytics.retention.{}", names[w + 1]),
                    format!(
                        "{} {} ms is shorter than {} {} ms: a coarser \
                         rollup may not expire before the finer table it \
                         cascades from",
                        names[w + 1],
                        e[w + 1],
                        names[w],
                        e[w]
                    ),
                ));
            }
        }
    }
    let mut seen = std::collections::BTreeSet::new();
    for (i, dim) in a.dimensions.iter().enumerate() {
        let field = format!("analytics.dimensions[{i}]");
        let name_ok = !dim.name.is_empty()
            && dim.name.len() <= 32
            && dim
                .name
                .bytes()
                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_');
        if !name_ok {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.name"),
                format!(
                    "dimension name '{}' is invalid: lowercase [a-z0-9_], \
                     1..=32 bytes (it is the rollup dimension key)",
                    dim.name
                ),
            ));
        }
        // Source-specific field validation (DW-093): each source
        // requires its own field, and the field must be well-formed.
        match dim.effective_source() {
            crate::config::DimensionSource::Header => {
                if let Some(header) = &dim.header {
                    if let Err(e) = hyper::header::HeaderName::try_from(header.as_str()) {
                        issues.push(issue(
                            "gateway",
                            "(root)",
                            &format!("{field}.header"),
                            format!("header name '{header}' is not representable: {e}"),
                        ));
                    }
                } else {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("{field}.header"),
                        "source 'header' (or absent source) requires the \
                         'header' field",
                    ));
                }
            }
            crate::config::DimensionSource::Claim => {
                if let Some(claim) = &dim.claim {
                    if claim.is_empty()
                        || !claim.bytes().all(|b| b.is_ascii_graphic())
                        || claim.len() > 128
                    {
                        issues.push(issue(
                            "gateway",
                            "(root)",
                            &format!("{field}.claim"),
                            format!(
                                "claim name '{}' is invalid: non-empty \
                                 printable ASCII, at most 128 bytes",
                                claim
                            ),
                        ));
                    }
                } else {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("{field}.claim"),
                        "source 'claim' requires the 'claim' field",
                    ));
                }
            }
            crate::config::DimensionSource::BodyPath => {
                if let Some(path) = &dim.body_path {
                    if crate::config::transforms::JsonPointer::parse(path).is_none() {
                        issues.push(issue(
                            "gateway",
                            "(root)",
                            &format!("{field}.body_path"),
                            format!(
                                "body_path '{}' is not a valid RFC 6901 JSON \
                                 pointer (must start with '/' or be empty for \
                                 the whole document)",
                                path
                            ),
                        ));
                    }
                } else {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("{field}.body_path"),
                        "source 'body_path' requires the 'body_path' field",
                    ));
                }
            }
        }
        if !seen.insert(dim.name.to_ascii_lowercase()) {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.name"),
                format!(
                    "duplicate dimension name '{}' (each name is one rollup key)",
                    dim.name
                ),
            ));
        }
    }
    if a.dimensions.len() > 16 {
        issues.push(issue(
            "gateway",
            "(root)",
            "analytics.dimensions",
            format!(
                "{} dimensions declared; at most 16 (each multiplies rollup \
                 cardinality)",
                a.dimensions.len()
            ),
        ));
    }
    if let Some(exports) = &a.exports {
        if exports.directory.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.exports.directory",
                "analytics.exports.directory is empty: exports need a real \
                 directory to write their files into",
            ));
        }
        let mut seen_formats = std::collections::BTreeSet::new();
        for (i, f) in exports.formats.iter().enumerate() {
            if !seen_formats.insert(f) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("analytics.exports.formats[{i}]"),
                    format!(
                        "duplicate export format '{f:?}': each format writes \
                         exactly one file per window",
                    ),
                ));
            }
        }
    }
    // DW-092: live sketches freshness target bounds.
    if let Some(ls) = &a.live_sketches {
        if ls.enabled && !(100..=5000).contains(&ls.freshness_target_ms) {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.live_sketches.freshness_target_ms",
                format!(
                    "freshness_target_ms {} is out of range: must be 100..=5000 \
                     (below 100 is timer churn; above 5000 is no longer 'live')",
                    ls.freshness_target_ms
                ),
            ));
        }
    }
    // DW-092: insights baseline_windows must be > 0 when either feature
    // is enabled.
    if let Some(ins) = &a.insights {
        if (ins.forecast || ins.anomaly_baseline) && ins.baseline_windows == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics.insights.baseline_windows",
                "baseline_windows must be > 0 when forecast or anomaly_baseline \
                 is enabled (the ring buffer must hold at least one window)",
            ));
        }
    }
}

/// Validate GeoIP rules (DW-050): every `authorization.geoip`
/// predicate anywhere in the config (gateway/listener/service/route/
/// consumer — the five Authz attachment points) needs a
/// `gateway.geoip` database (an unevaluable gate is an authoring
/// error, never a silent pass), and country entries must be two ASCII
/// letters.
fn validate_geoip(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    fn check(a: Option<&crate::config::Authz>, where_: &str, issues: &mut Vec<ValidationIssue>) {
        let Some(rules) = a.and_then(|a| a.geoip.as_ref()) else {
            return;
        };
        for c in rules
            .allowed_countries
            .iter()
            .chain(&rules.denied_countries)
        {
            if c.len() != 2 || !c.chars().all(|ch| ch.is_ascii_alphabetic()) {
                issues.push(issue(
                    "gateway",
                    where_,
                    "authorization.geoip.countries",
                    format!("country code '{c}' is not two ASCII letters (ISO 3166-1 alpha-2)"),
                ));
            }
        }
    }
    let has_rules = |a: Option<&crate::config::Authz>| a.is_some_and(|a| a.geoip.is_some());
    let any = gateway
        .authorization
        .as_ref()
        .is_some_and(|a| has_rules(Some(a)))
        || gateway
            .listeners
            .iter()
            .any(|l| has_rules(l.authorization.as_ref()))
        || gateway
            .services
            .iter()
            .any(|s| has_rules(s.authorization.as_ref()))
        || gateway
            .routes
            .iter()
            .any(|r| has_rules(r.authorization.as_ref()))
        || gateway
            .consumers
            .iter()
            .any(|c| has_rules(c.authorization.as_ref()));
    match &gateway.geoip {
        None if any => issues.push(issue(
            "gateway",
            "(root)",
            "geoip",
            "authorization.geoip rules require a gateway.geoip database block \
             (without one the gate cannot be evaluated)",
        )),
        Some(g) if g.path.trim().is_empty() => issues.push(issue(
            "gateway",
            "(root)",
            "geoip.path",
            "geoip.path is empty: name a real .mmdb file or remove the block",
        )),
        _ => {}
    }
    check(gateway.authorization.as_ref(), "(root)", issues);
    for l in &gateway.listeners {
        check(
            l.authorization.as_ref(),
            &format!("listeners[{}]", l.name),
            issues,
        );
    }
    for s in &gateway.services {
        check(
            s.authorization.as_ref(),
            &format!("services[{}]", s.name),
            issues,
        );
    }
    for r in &gateway.routes {
        check(
            r.authorization.as_ref(),
            &format!("routes[{}]", r.name),
            issues,
        );
    }
    for c in &gateway.consumers {
        check(
            c.authorization.as_ref(),
            &format!("consumers[{}]", c.name),
            issues,
        );
    }
}

/// Validate consumer request budgets (DW-033): a `quotas` block must
/// set at least one budget, and every set budget must be > 0 (a 0
/// budget would deny the consumer's first request; "no budget" is the
/// omitted field). Quota enforcement additionally needs the state
/// store at RUNTIME (`DWARA_STATE_DB`), which config validation
/// deliberately cannot see — without one the block is inert and the
/// dataplane warns (see `state::quotas`).
fn validate_quotas(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    for c in &gateway.consumers {
        let Some(q) = &c.quotas else {
            continue;
        };
        let field = format!("consumers[{}].quotas", c.name);
        if q.daily_requests.is_none() && q.monthly_requests.is_none() {
            issues.push(issue(
                "consumer",
                &c.name,
                &field,
                "sets no budget: at least one of daily_requests or monthly_requests \
                 must be present (omit the quotas block entirely for no budgets)",
            ));
        }
        for (name, value) in [
            ("daily_requests", q.daily_requests),
            ("monthly_requests", q.monthly_requests),
        ] {
            if value == Some(0) {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    &format!("{field}.{name}"),
                    format!(
                        "{name} must be > 0 (a zero budget denies the consumer's \
                             first request; no budget is the omitted field)"
                    ),
                ));
            }
        }
    }
}

/// Validate the `gateway.plugins` list (DW-055 / DW-119): each plugin
/// must set exactly one of `wasm` or `native` (mutually exclusive), and
/// must declare a non-empty `phases` list. Duplicate plugin names are
/// flagged. Route references to unknown names are rejected (see the
/// route validation pass). A `wasm` plugin's file existence and
/// compilability are checked by the WASM lifecycle manager at LOAD
/// time (DW-157: a broken .wasm is marked crashed there and routes
/// referencing it answer 500 fail-closed), not here — the file may not
/// be present in the validation environment.
fn validate_plugins(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let mut seen = std::collections::BTreeSet::new();
    for p in &gateway.plugins {
        if !seen.insert(p.name.as_str()) {
            issues.push(issue("plugin", &p.name, "name", "duplicate plugin name"));
        }
        let has_wasm = p.wasm.is_some();
        let has_native = p.native.is_some();
        let has_source = p.source.is_some();
        // SCALE-12 (#192): source is a remote variant of wasm. A plugin
        // with `source` is a WASM plugin whose artifact is downloaded
        // from the registry; `wasm` is the optional local cache path.
        let has_wasm_or_source = has_wasm || has_source;
        if !has_wasm_or_source && !has_native {
            issues.push(issue(
                "plugin",
                &p.name,
                "wasm",
                "plugin must set exactly one of `wasm`, `source`, or `native` (all are absent)",
            ));
        }
        if has_wasm_or_source && has_native {
            issues.push(issue(
                "plugin",
                &p.name,
                "native",
                "plugin must set exactly one of `wasm`/`source` or `native` (both are set)",
            ));
        }
        if has_wasm && has_source {
            issues.push(issue(
                "plugin",
                &p.name,
                "source",
                "plugin must not set both `wasm` and `source` (use `source` with optional `cache_path`)",
            ));
        }
        if p.phases.is_empty() {
            issues.push(issue(
                "plugin",
                &p.name,
                "phases",
                "phases must be a non-empty subset of request_headers, \
                 request_body, response_headers, response_body",
            ));
        }
        // SCALE-12 (#192)/DW-165: validate remote source config. The
        // resolver (wasm::source) re-checks all of this defensively;
        // validation gives the operator the earliest, field-named view.
        if let Some(src) = &p.source {
            let digest_ok =
                src.digest.len() == 64 && src.digest.bytes().all(|b| b.is_ascii_hexdigit());
            if !digest_ok {
                let detail = if src.digest.len() != 64 {
                    format!("got {} chars, expected 64", src.digest.len())
                } else {
                    "contains non-hex characters".to_string()
                };
                issues.push(issue(
                    "plugin",
                    &p.name,
                    "source.digest",
                    format!("source digest must be a hex-encoded SHA-256 string ({detail})"),
                ));
            }
            if src.url.starts_with("oci://") {
                issues.push(issue(
                    "plugin",
                    &p.name,
                    "source.url",
                    "oci:// plugin sources are not supported in this version; publish \
                     the artifact over https:// or pre-fetch it with `dwara-cli plugin \
                     install` and reference the local file with `wasm`",
                ));
            } else if !src.url.starts_with("https://") {
                issues.push(issue(
                    "plugin",
                    &p.name,
                    "source.url",
                    "source url must use the https:// scheme (oci:// is not supported \
                     in this version)",
                ));
            }
            if let Some(pk) = &src.public_key {
                if pk.len() != 64 || !pk.bytes().all(|b| b.is_ascii_hexdigit()) {
                    issues.push(issue(
                        "plugin",
                        &p.name,
                        "source.public_key",
                        "source.public_key must be a 32-byte Ed25519 key hex-encoded \
                         (64 chars)",
                    ));
                }
            }
            if let Some(sig) = &src.signature {
                if sig.len() != 128 || !sig.bytes().all(|b| b.is_ascii_hexdigit()) {
                    issues.push(issue(
                        "plugin",
                        &p.name,
                        "source.signature",
                        "source.signature must be a 64-byte Ed25519 signature \
                         hex-encoded (128 chars)",
                    ));
                }
            }
            if src.signature.is_some() && src.public_key.is_none() {
                // Still required per-plugin: registry-pinned keys alone
                // do not identify which key signed THIS plugin unless
                // the operator pins them via plugin_registry.
                let registry_keys = gateway
                    .plugin_registry
                    .as_ref()
                    .map(|r| !r.public_keys.is_empty())
                    .unwrap_or(false);
                if !registry_keys {
                    issues.push(issue(
                        "plugin",
                        &p.name,
                        "source.public_key",
                        "source.public_key is required when source.signature is set \
                         (or pin keys via plugin_registry.public_keys)",
                    ));
                }
            }
            if src.public_key.is_some() && src.signature.is_none() {
                // Review finding: a key without a signature used to be
                // silently ignored (nothing would be verified with it);
                // that is a config mistake — reject it.
                issues.push(issue(
                    "plugin",
                    &p.name,
                    "source.signature",
                    "source.signature is required when source.public_key is set \
                     (a key without a signature verifies nothing — sign the \
                     artifact or remove the key)",
                ));
            }
            if let Some(cp) = &src.cache_path {
                // Review finding (containment): cache_path is
                // operator-chosen and the resolver creates directories
                // and writes artifact bytes there — it must stay inside
                // the cache dir. The rule lives on
                // PluginSourceConfig (shared with the resolver's
                // defensive re-check).
                if let Some(reason) = crate::config::PluginSourceConfig::cache_path_violation(cp) {
                    issues.push(issue(
                        "plugin",
                        &p.name,
                        "source.cache_path",
                        format!(
                            "source.cache_path '{cp}' is not usable ({reason}); it must \
                             be a relative path under plugin_registry.cache_dir with no \
                             parent segments"
                        ),
                    ));
                }
            }
        }
    }
    // SCALE-12 (#192): validate plugin registry config.
    if let Some(reg) = &gateway.plugin_registry {
        for pk in &reg.public_keys {
            if pk.len() != 64 {
                issues.push(issue(
                    "plugin_registry",
                    "gateway",
                    "public_keys",
                    "each public key must be a 32-byte Ed25519 key hex-encoded (64 chars)",
                ));
            }
        }
    }
}

/// SCALE-12 (#191): validate a filter-chain config block. The `order`
/// override, if present, must be a permutation of the default phase
/// set (no duplicates, no unknown phases, all phases present).
fn validate_filter_chain(
    fc: &crate::config::FilterChainConfig,
    entity: &str,
    name: &str,
    issues: &mut Vec<ValidationIssue>,
) {
    if let Some(order) = &fc.order {
        let default = crate::config::FilterPhase::DEFAULT_ORDER;
        if order.len() != default.len() {
            issues.push(issue(
                entity,
                name,
                "filter_chain.order",
                format!(
                    "order must contain exactly {} phases, got {}",
                    default.len(),
                    order.len()
                ),
            ));
        } else {
            let mut seen = std::collections::BTreeSet::new();
            for phase in order {
                if !seen.insert(*phase) {
                    issues.push(issue(
                        entity,
                        name,
                        "filter_chain.order",
                        format!("duplicate phase '{}' in filter_chain.order", phase.as_str()),
                    ));
                }
            }
            // Check all default phases are present.
            for dp in &default {
                if !order.contains(dp) {
                    issues.push(issue(
                        entity,
                        name,
                        "filter_chain.order",
                        format!("filter_chain.order is missing phase '{}'", dp.as_str()),
                    ));
                }
            }
        }
    }
    // dry_run: check for duplicates.
    let mut seen = std::collections::BTreeSet::new();
    for phase in &fc.dry_run {
        if !seen.insert(*phase) {
            issues.push(issue(
                entity,
                name,
                "filter_chain.dry_run",
                format!(
                    "duplicate phase '{}' in filter_chain.dry_run",
                    phase.as_str()
                ),
            ));
        }
    }
}

/// Validate the `gateway.license` block (DW-032): the grace-period days
/// must be in 0..=30, and the file path must be non-empty. The signature
/// and expiry checks are NOT validation concerns — they run at startup
/// in dwara-bin (where a missing or invalid file can exit 1), not in the
/// compile pipeline (a license file's validity is a runtime property
/// that can change between reloads without a config-schema change).
fn validate_license(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(lic) = &gateway.license else {
        return;
    };
    if lic.file.trim().is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "license.file",
            "license.file must be a non-empty filesystem path",
        ));
    }
    if lic.grace_period_days > crate::config::limits::MAX_LICENSE_GRACE_PERIOD_DAYS {
        issues.push(issue(
            "gateway",
            "(root)",
            "license.grace_period_days",
            format!(
                "license.grace_period_days {} is out of range: must be 0..={}",
                lic.grace_period_days,
                crate::config::limits::MAX_LICENSE_GRACE_PERIOD_DAYS,
            ),
        ));
    }
}

/// Validate the `gateway.redis_rate_limiter` block (DW-031): the URL
/// must be non-empty, the connection timeout must be in
/// 100..=30 000 ms, and the key TTL must be in 1..=604 800 s. The
/// license check (does the license grant `redis_rate_limiter`?) is NOT
/// a validation concern — it runs at startup in dwara-bin (where a
/// missing claim can log a warning and fall back to the local
/// limiter), not in the compile pipeline (a license's validity is a
/// runtime property that can change between reloads without a
/// config-schema change).
fn validate_redis_rate_limiter(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(rl) = &gateway.redis_rate_limiter else {
        return;
    };
    if rl.url.trim().is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_rate_limiter.url",
            "redis_rate_limiter.url must be a non-empty Redis URL",
        ));
    }
    let timeout = rl.connection_timeout_ms;
    if !(crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS
        ..=crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS)
        .contains(&timeout)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_rate_limiter.connection_timeout_ms",
            format!(
                "redis_rate_limiter.connection_timeout_ms {} is out of range: must be {}..={}",
                timeout,
                crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS,
                crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS,
            ),
        ));
    }
    let ttl = rl.key_ttl_s;
    if !(crate::config::limits::MIN_REDIS_KEY_TTL_S..=crate::config::limits::MAX_REDIS_KEY_TTL_S)
        .contains(&ttl)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_rate_limiter.key_ttl_s",
            format!(
                "redis_rate_limiter.key_ttl_s {} is out of range: must be {}..={}",
                ttl,
                crate::config::limits::MIN_REDIS_KEY_TTL_S,
                crate::config::limits::MAX_REDIS_KEY_TTL_S,
            ),
        ));
    }
    if rl.key_prefix.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_rate_limiter.key_prefix",
            "redis_rate_limiter.key_prefix must be a non-empty string",
        ));
    }
    validate_redis_ha("redis_rate_limiter", &rl.ha, issues);
}

/// Validate the `ha` block shared by all Redis-backed config sections
/// (SCALE-11, #248). Checks:
/// - `topology = sentinel` requires `master_name` and at least one
///   node URL.
/// - `topology = cluster` requires at least one node URL (or the
///   parent `url` must be non-empty).
/// - `request_timeout_ms` must be 0 or in 50..=30 000.
fn validate_redis_ha(
    prefix: &str,
    ha: &crate::config::RedisHaConfig,
    issues: &mut Vec<ValidationIssue>,
) {
    use crate::config::RedisTopology;
    match ha.topology {
        RedisTopology::Single => {}
        RedisTopology::Sentinel => {
            if ha.master_name.is_none()
                || ha
                    .master_name
                    .as_deref()
                    .map(|s| s.trim().is_empty())
                    .unwrap_or(true)
            {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("{prefix}.ha.master_name"),
                    format!("{prefix}.ha.master_name is required when topology = sentinel"),
                ));
            }
            if ha.nodes.is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("{prefix}.ha.nodes"),
                    format!("{prefix}.ha.nodes must list at least one Sentinel URL when topology = sentinel"),
                ));
            }
        }
        RedisTopology::Cluster => {
            if ha.nodes.is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("{prefix}.ha.nodes"),
                    format!("{prefix}.ha.nodes must list at least one cluster node URL when topology = cluster"),
                ));
            }
        }
    }
    let timeout = ha.request_timeout_ms;
    if timeout != 0 && !(50..=30_000).contains(&timeout) {
        issues.push(issue(
            "gateway",
            "(root)",
            &format!("{prefix}.ha.request_timeout_ms"),
            format!(
                "{prefix}.ha.request_timeout_ms {timeout} is out of range: must be 0 or 50..=30000"
            ),
        ));
    }
}

/// Validate the `gateway.redis_quotas` block (DW-155): the URL must be
/// non-empty, the connection timeout must be in 100..=30 000 ms, and
/// the key prefix must be non-empty. The license check (does the
/// license grant `redis_quotas`?) is NOT a validation concern — it
/// runs at startup in dwara-bin (where a missing claim can log a
/// warning and fall back to the local SQLite checker), not in the
/// compile pipeline.
fn validate_redis_quotas(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(rq) = &gateway.redis_quotas else {
        return;
    };
    if rq.url.trim().is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_quotas.url",
            "redis_quotas.url must be a non-empty Redis URL",
        ));
    }
    let timeout = rq.connection_timeout_ms;
    if !(crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS
        ..=crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS)
        .contains(&timeout)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_quotas.connection_timeout_ms",
            format!(
                "redis_quotas.connection_timeout_ms {} is out of range: must be {}..={}",
                timeout,
                crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS,
                crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS,
            ),
        ));
    }
    if rq.key_prefix.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_quotas.key_prefix",
            "redis_quotas.key_prefix must be a non-empty string",
        ));
    }
    validate_redis_ha("redis_quotas", &rq.ha, issues);
}

/// Validate the `gateway.redis_cache` block (SCALE-04, #183): the URL
/// must be non-empty, the connection timeout must be in 100..=30 000 ms,
/// and the key prefix must be non-empty. The license check (does the
/// license grant `redis_cache`?) is NOT a validation concern — it runs
/// at startup in dwara-bin (where a missing claim logs a warning and
/// falls back to the local moka cache), not in the compile pipeline.
fn validate_redis_cache(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(rc) = &gateway.redis_cache else {
        return;
    };
    if rc.url.trim().is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_cache.url",
            "redis_cache.url must be a non-empty Redis URL",
        ));
    }
    let timeout = rc.connection_timeout_ms;
    if !(crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS
        ..=crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS)
        .contains(&timeout)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_cache.connection_timeout_ms",
            format!(
                "redis_cache.connection_timeout_ms {} is out of range: must be {}..={}",
                timeout,
                crate::config::limits::MIN_REDIS_CONNECTION_TIMEOUT_MS,
                crate::config::limits::MAX_REDIS_CONNECTION_TIMEOUT_MS,
            ),
        ));
    }
    if rc.key_prefix.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "redis_cache.key_prefix",
            "redis_cache.key_prefix must be a non-empty string",
        ));
    }
    validate_redis_ha("redis_cache", &rc.ha, issues);
}

/// Validate the `gateway.config_convergence` block (DW-054): the
/// backend must be `"redis"` (the only v1 backend; etcd/Consul are
/// deferred behind the trait), `redis_url` must be present and
/// non-empty when `backend = "redis"`, the poll and drift-check
/// intervals must be in range, and the key prefix must be non-empty.
/// The license check (does the license grant `config_convergence`?)
/// is NOT a validation concern -- it runs at startup in dwara-bin
/// (where a missing claim logs a warning and falls back to local-only
/// mode), not in the compile pipeline (a license's validity is a
/// runtime property that can change between reloads without a
/// config-schema change).
fn validate_config_convergence(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(cc) = &gateway.config_convergence else {
        return;
    };
    if cc.backend != "redis" {
        issues.push(issue(
            "gateway",
            "(root)",
            "config_convergence.backend",
            format!(
                "config_convergence.backend '{}' is not supported: v1 ships only 'redis' \
                 (etcd/Consul are deferred behind the ConfigConvergenceBackend trait)",
                cc.backend,
            ),
        ));
    }
    if cc.backend == "redis" {
        match &cc.redis_url {
            None => issues.push(issue(
                "gateway",
                "(root)",
                "config_convergence.redis_url",
                "config_convergence.redis_url is required when backend = 'redis'",
            )),
            Some(url) if url.trim().is_empty() => issues.push(issue(
                "gateway",
                "(root)",
                "config_convergence.redis_url",
                "config_convergence.redis_url must be a non-empty Redis URL",
            )),
            _ => {}
        }
    }
    let poll = cc.poll_interval_ms;
    if !(crate::config::limits::MIN_CONFIG_CONVERGENCE_POLL_MS
        ..=crate::config::limits::MAX_CONFIG_CONVERGENCE_POLL_MS)
        .contains(&poll)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "config_convergence.poll_interval_ms",
            format!(
                "config_convergence.poll_interval_ms {} is out of range: must be {}..={}",
                poll,
                crate::config::limits::MIN_CONFIG_CONVERGENCE_POLL_MS,
                crate::config::limits::MAX_CONFIG_CONVERGENCE_POLL_MS,
            ),
        ));
    }
    let drift = cc.drift_check_interval_ms;
    if !(crate::config::limits::MIN_CONFIG_CONVERGENCE_DRIFT_CHECK_MS
        ..=crate::config::limits::MAX_CONFIG_CONVERGENCE_DRIFT_CHECK_MS)
        .contains(&drift)
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "config_convergence.drift_check_interval_ms",
            format!(
                "config_convergence.drift_check_interval_ms {} is out of range: must be {}..={}",
                drift,
                crate::config::limits::MIN_CONFIG_CONVERGENCE_DRIFT_CHECK_MS,
                crate::config::limits::MAX_CONFIG_CONVERGENCE_DRIFT_CHECK_MS,
            ),
        ));
    }
    if cc.key_prefix.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "config_convergence.key_prefix",
            "config_convergence.key_prefix must be a non-empty string",
        ));
    }
}

/// Validate the `gateway.fleet` block (DW-098): the stale timeout
/// must be in range, upgrade order entries must have non-empty names
/// and non-empty label selectors, and label selectors must not
/// overlap (an edge would match two waves, making the order
/// ambiguous).
fn validate_fleet(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(fleet) = &gateway.fleet else {
        return;
    };
    if !fleet.enabled {
        return;
    }
    let stale = fleet.stale_timeout_secs;
    if !(5..=3600).contains(&stale) {
        issues.push(issue(
            "gateway",
            "(root)",
            "fleet.stale_timeout_secs",
            format!("fleet.stale_timeout_secs {stale} is out of range: must be 5..=3600"),
        ));
    }
    if let Some(cv) = &fleet.controller_version {
        if cv.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "fleet.controller_version",
                "fleet.controller_version must be a non-empty semver string when present",
            ));
        }
    }
    if let Some(upgrade) = &fleet.upgrade {
        let mut seen_names = std::collections::HashSet::new();
        for (i, entry) in upgrade.order.iter().enumerate() {
            if entry.name.is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("fleet.upgrade.order[{i}].name"),
                    "upgrade order entry name must be a non-empty string",
                ));
            }
            if !seen_names.insert(entry.name.as_str()) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("fleet.upgrade.order[{i}].name"),
                    format!(
                        "upgrade order entry name '{}' is duplicated (each wave must have a \
                         unique name)",
                        entry.name
                    ),
                ));
            }
            if entry.labels.is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("fleet.upgrade.order[{i}].labels"),
                    "upgrade order entry labels must be a non-empty label selector",
                ));
            }
        }
        // Check for overlapping label selectors (an edge matching two
        // waves makes the order ambiguous).
        for (i, a) in upgrade.order.iter().enumerate() {
            for (j, b) in upgrade.order.iter().enumerate().skip(i + 1) {
                if labels_overlap(&a.labels, &b.labels) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("fleet.upgrade.order[{i}].labels"),
                        format!(
                            "upgrade order entries '{}' (index {i}) and '{}' (index {j}) have \
                             overlapping label selectors (an edge would match both, making the \
                             order ambiguous)",
                            a.name, b.name
                        ),
                    ));
                }
            }
        }
    }
}

/// Whether two label selectors overlap (one is a subset of the other).
/// Two selectors overlap when every label in the smaller set is
/// present in the larger set with the same value.
fn labels_overlap(
    a: &std::collections::HashMap<String, String>,
    b: &std::collections::HashMap<String, String>,
) -> bool {
    let (smaller, larger) = if a.len() <= b.len() { (a, b) } else { (b, a) };
    smaller.iter().all(|(k, v)| larger.get(k) == Some(v))
}

/// Validate the `gateway.mesh` block (DW-107): service mesh mode
/// (sidecar + SPIFFE/SPIRE mTLS identity). When the `mesh` cargo
/// feature is off, the block is accepted but a warning issue is
/// emitted (the block is inert -- no sidecar listeners or SPIFFE
/// client are wired). Ent-only: when the `ent` feature is off, a
/// warning is emitted (mesh is an enterprise feature). SPIFFE:
/// `trust_domain` and `workload_api_socket` must be non-empty, and
/// `svid_refresh_interval_secs` must be > 0. Sidecar: `inbound_port`
/// and `outbound_port` must be > 0 and different, and `redirect_mode`
/// must be `iptables` or `tproxy`.
fn validate_mesh(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(mesh) = &gateway.mesh else {
        return;
    };

    // Feature gate: warn that the block is inert without the `mesh`
    // cargo feature (mirrors the a2a ent-gated warning pattern).

    // Ent gate: warn when mesh is configured without the `ent` feature
    // (mesh is an enterprise feature; mirrors the FIPS/credential-pool
    // ent-gate pattern). The block still parses and the mesh-feature
    // scaffold compiles, but license-gated enforcement requires `ent`.
    #[cfg(not(feature = "ent"))]
    {
        issues.push(issue(
            "gateway",
            "(root)",
            "mesh",
            "the mesh block is configured but the `ent` cargo feature is \
             not compiled in: service mesh mode is an enterprise feature \
             (DW-107). Build with --features ent (combined with --features \
             mesh) for license-gated enforcement.",
        ));
    }

    if !mesh.enabled {
        return;
    }

    // Sidecar validation.
    if let Some(sidecar) = &mesh.sidecar {
        if sidecar.inbound_port == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.sidecar.inbound_port",
                "inbound_port must be > 0",
            ));
        }
        if sidecar.outbound_port == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.sidecar.outbound_port",
                "outbound_port must be > 0",
            ));
        }
        if sidecar.inbound_port == sidecar.outbound_port && sidecar.inbound_port != 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.sidecar.inbound_port",
                format!(
                    "inbound_port ({}) and outbound_port ({}) must be different \
                     (the sidecar binds separate listeners for inbound and outbound \
                     traffic)",
                    sidecar.inbound_port, sidecar.outbound_port
                ),
            ));
        }
        if sidecar.redirect_mode != "iptables" && sidecar.redirect_mode != "tproxy" {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.sidecar.redirect_mode",
                format!(
                    "redirect_mode '{}' is not a supported redirect mode: must be \
                     'iptables' or 'tproxy'",
                    sidecar.redirect_mode
                ),
            ));
        }
    }

    // SPIFFE validation.
    if let Some(spiffe) = &mesh.spiffe {
        if spiffe.trust_domain.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.spiffe.trust_domain",
                "trust_domain must be non-empty (it forms the SPIFFE ID prefix \
                 spiffe://<trust-domain>/...)",
            ));
        }
        if spiffe.workload_api_socket.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.spiffe.workload_api_socket",
                "workload_api_socket must be non-empty (the SPIRE Workload API \
                 Unix socket path)",
            ));
        }
        if spiffe.svid_refresh_interval_secs == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "mesh.spiffe.svid_refresh_interval_secs",
                "svid_refresh_interval_secs must be > 0 (omit for the default 300s)",
            ));
        }
    }
}

/// Validate the `gateway.oidc_providers` list (DW-034): each issuer must
/// be an absolute `http(s)://` URL, the introspection cache TTL must be
/// in `1..=3600`, the `consumer` reference (when set) must name a known
/// consumer, the `trusted_ca_file` (when set) must be a readable PEM
/// bundle and only applies to an `https://` issuer, and provider names
/// must be unique. Endpoint overrides (`introspection_endpoint`,
/// `revocation_endpoint`) are checked for URL shape when present.
fn validate_oidc_providers(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    // Duplicate provider names (inline: check_dups is a local closure in
    // the calling validate function, not a free function).
    {
        let mut seen = std::collections::BTreeSet::new();
        for p in &gateway.oidc_providers {
            if !seen.insert(p.name.as_str()) {
                issues.push(issue("oidc_provider", &p.name, "name", "duplicate name"));
            }
        }
    }
    for p in &gateway.oidc_providers {
        match p.issuer.parse::<hyper::Uri>() {
            Ok(uri) => {
                if !matches!(uri.scheme_str(), Some("http") | Some("https")) || uri.host().is_none()
                {
                    issues.push(issue(
                        "oidc_provider",
                        &p.name,
                        "issuer",
                        format!("'{}' must be an absolute http(s) URL", p.issuer),
                    ));
                }
            }
            Err(_) => issues.push(issue(
                "oidc_provider",
                &p.name,
                "issuer",
                format!("'{}' is not a valid URL", p.issuer),
            )),
        }
        let ttl = p.introspection_cache_ttl_s;
        if !(crate::config::limits::MIN_OIDC_INTROSPECTION_CACHE_TTL_S
            ..=crate::config::limits::MAX_OIDC_INTROSPECTION_CACHE_TTL_S)
            .contains(&ttl)
        {
            issues.push(issue(
                "oidc_provider",
                &p.name,
                "introspection_cache_ttl_s",
                format!(
                    "introspection_cache_ttl_s {} is out of range: must be {}..={}",
                    ttl,
                    crate::config::limits::MIN_OIDC_INTROSPECTION_CACHE_TTL_S,
                    crate::config::limits::MAX_OIDC_INTROSPECTION_CACHE_TTL_S,
                ),
            ));
        }
        if let Some(consumer) = &p.consumer {
            if !gateway.consumers.iter().any(|c| &c.name == consumer) {
                issues.push(issue(
                    "oidc_provider",
                    &p.name,
                    "consumer",
                    format!("references unknown consumer '{consumer}'"),
                ));
            }
        }
        // trusted_ca_file: same rules as JwtProvider (#121) — only
        // meaningful for an https issuer, and must be a readable PEM
        // bundle when it does apply.
        if let Some(ca) = &p.trusted_ca_file {
            if let Ok(uri) = p.issuer.parse::<hyper::Uri>() {
                if uri
                    .scheme_str()
                    .is_some_and(|s| s.eq_ignore_ascii_case("https"))
                {
                    check_trusted_ca_file("oidc_provider", &p.name, "trusted_ca_file", ca, issues);
                } else {
                    issues.push(issue(
                        "oidc_provider",
                        &p.name,
                        "trusted_ca_file",
                        "trusted_ca_file only applies to an https issuer (no TLS is \
                         negotiated toward an http endpoint)",
                    ));
                }
            }
        }
        // Endpoint overrides: when present, must be absolute http(s) URLs.
        if let Some(ep) = &p.introspection_endpoint {
            validate_delivery_url(
                &format!("oidc_provider[{}].introspection_endpoint", p.name),
                ep,
                issues,
            );
        }
        if let Some(ep) = &p.revocation_endpoint {
            validate_delivery_url(
                &format!("oidc_provider[{}].revocation_endpoint", p.name),
                ep,
                issues,
            );
        }
    }
}

/// Validate the `gateway.webhooks` list (DW-044): every URL must be an
/// absolute http(s) URL, every `events` entry must name an emitted kind
/// (unknown spellings are rejected; `quota_near_limit` IS emitted since
/// DW-033), header names/values must be
/// representable (with `${...}` references resolved NOW, the DW-045
/// compile-time contract — an unresolvable reference fails the
/// generation closed, and the issue names the reference, never the
/// value), the retry knobs must be in bounds, and a duplicate URL is
/// rejected (two identical targets would double-deliver every event).
fn validate_webhooks(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let mut seen_urls = std::collections::BTreeSet::new();
    for (i, hook) in gateway.webhooks.iter().enumerate() {
        let field = format!("webhooks[{i}]");
        validate_delivery_url(&format!("{field}.url"), &hook.url, issues);
        if !seen_urls.insert(hook.url.trim().to_string()) {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.url"),
                format!(
                    "duplicate webhook url '{}' (an event would be delivered \
                     twice; merge their events lists instead)",
                    hook.url
                ),
            ));
        }
        if hook.events.is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.events"),
                "events is empty: a webhook subscribing to nothing never fires \
                 and is always a mistake; omit the entry",
            ));
        }
        for (j, kind) in hook.events.iter().enumerate() {
            if crate::events::EventKind::from_config(kind).is_none() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("{field}.events[{j}]"),
                    format!(
                        "unknown event kind '{kind}' (emitted kinds: {})",
                        crate::events::EventKind::ALL
                            .iter()
                            .map(|k| k.as_str())
                            .collect::<Vec<_>>()
                            .join(", ")
                    ),
                ));
            }
        }
        validate_delivery_headers(&field, &hook.headers, issues);
        if hook.timeout_ms == 0 || hook.timeout_ms > crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.timeout_ms"),
                format!(
                    "timeout_ms must be in 1..={} (one total budget per delivery, \
                     shared by every retry attempt)",
                    crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS
                ),
            ));
        }
        if hook.max_attempts == 0 || hook.max_attempts > crate::config::limits::MAX_WEBHOOK_ATTEMPTS
        {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.max_attempts"),
                format!(
                    "max_attempts must be in 1..={} (total attempts per delivery)",
                    crate::config::limits::MAX_WEBHOOK_ATTEMPTS
                ),
            ));
        }
        if hook.backoff_base_ms == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.backoff_base_ms"),
                "backoff_base_ms must be > 0",
            ));
        }
        if hook.backoff_cap_ms < hook.backoff_base_ms {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.backoff_cap_ms"),
                "backoff_cap_ms must be >= backoff_base_ms",
            ));
        }
    }
}

/// The URL shape shared by every outbound HTTP delivery surface
/// (DW-044 webhooks and the DW-121 record-stream sink): absolute
/// http(s) with a host.
fn validate_delivery_url(field: &str, url: &str, issues: &mut Vec<ValidationIssue>) {
    match url.parse::<hyper::Uri>() {
        Ok(uri) => {
            if !matches!(uri.scheme_str(), Some("http") | Some("https")) || uri.host().is_none() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    field,
                    format!(
                        "'{url}' must be an absolute http(s) URL with a host \
                         (e.g. https://hooks.example.com/alerts)"
                    ),
                ));
            }
        }
        Err(_) => issues.push(issue(
            "gateway",
            "(root)",
            field,
            format!("'{url}' is not a valid URL"),
        )),
    }
}

/// The header grammar shared by every outbound HTTP delivery surface:
/// names must be valid HTTP header names, and values (with `${...}`
/// references resolved NOW, the DW-045 compile-time contract — an
/// unresolvable reference fails the generation closed) must be
/// representable as a single header value. Issues name the header and
/// the reason, never the resolved value.
fn validate_delivery_headers(
    field: &str,
    headers: &std::collections::BTreeMap<String, String>,
    issues: &mut Vec<ValidationIssue>,
) {
    for (name, value) in headers {
        if hyper::header::HeaderName::from_bytes(name.as_bytes()).is_err() {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.headers"),
                format!("header name '{name}' is not a valid HTTP header name"),
            ));
            continue;
        }
        let problem = match crate::config::credentials::resolve_configured_secret(value) {
            Ok(resolved) => {
                if hyper::header::HeaderValue::from_str(&resolved).is_err() {
                    Some(
                        "the header value (after secret-reference resolution) \
                         contains characters that cannot appear in an HTTP \
                         header value"
                            .to_string(),
                    )
                } else {
                    None
                }
            }
            Err(message) => Some(message),
        };
        if let Some(message) = problem {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("{field}.headers"),
                format!("header '{name}': {message}"),
            ));
        }
    }
}

/// Validate the `gateway.analytics_stream` block (DW-121): the sink's
/// URL and headers through the shared outbound-delivery grammar
/// (alert webhooks and the record stream must not drift), the shared
/// retry-knob bounds, and the pipeline knobs — `buffer` (a boot-time
/// memory bound), `flush_ms` (batch latency), and `batch_max` (the
/// per-delivery record count).
fn validate_analytics_stream(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(cfg) = gateway.analytics_stream.as_ref() else {
        return;
    };
    match &cfg.sink {
        crate::config::AnalyticsStreamSink::Webhook(wh) => {
            validate_delivery_url("analytics_stream.sink.webhook.url", &wh.url, issues);
            validate_delivery_headers("analytics_stream.sink.webhook", &wh.headers, issues);
            if wh.timeout_ms == 0 || wh.timeout_ms > crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.webhook.timeout_ms",
                    format!(
                        "timeout_ms must be in 1..={} (one total budget per batch \
                         delivery, shared by every retry attempt — the shared \
                         webhook engine's bound)",
                        crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS
                    ),
                ));
            }
            if wh.max_attempts == 0 || wh.max_attempts > crate::config::limits::MAX_WEBHOOK_ATTEMPTS
            {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.webhook.max_attempts",
                    format!(
                        "max_attempts must be in 1..={} (total attempts per batch \
                         delivery)",
                        crate::config::limits::MAX_WEBHOOK_ATTEMPTS
                    ),
                ));
            }
            if wh.backoff_base_ms == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.webhook.backoff_base_ms",
                    "backoff_base_ms must be > 0",
                ));
            }
            if wh.backoff_cap_ms < wh.backoff_base_ms {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.webhook.backoff_cap_ms",
                    "backoff_cap_ms must be >= backoff_base_ms",
                ));
            }
        }
        crate::config::AnalyticsStreamSink::Kafka(k) => {
            validate_delivery_url(
                "analytics_stream.sink.kafka.rest_proxy_url",
                &k.rest_proxy_url,
                issues,
            );
            validate_delivery_headers("analytics_stream.sink.kafka", &k.headers, issues);
            if k.timeout_ms == 0 || k.timeout_ms > crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.kafka.timeout_ms",
                    format!(
                        "timeout_ms must be in 1..={} (one total budget per batch \
                         delivery, shared by every retry attempt — the shared \
                         webhook engine's bound)",
                        crate::config::limits::MAX_WEBHOOK_TIMEOUT_MS
                    ),
                ));
            }
            if k.max_attempts == 0 || k.max_attempts > crate::config::limits::MAX_WEBHOOK_ATTEMPTS {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.kafka.max_attempts",
                    format!(
                        "max_attempts must be in 1..={} (total attempts per batch \
                         delivery)",
                        crate::config::limits::MAX_WEBHOOK_ATTEMPTS
                    ),
                ));
            }
            if k.backoff_base_ms == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.kafka.backoff_base_ms",
                    "backoff_base_ms must be > 0",
                ));
            }
            if k.backoff_cap_ms < k.backoff_base_ms {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "analytics_stream.sink.kafka.backoff_cap_ms",
                    "backoff_cap_ms must be >= backoff_base_ms",
                ));
            }
        }
    }
    if let Some(buffer) = cfg.buffer {
        if !(crate::config::limits::MIN_STREAM_BUFFER..=crate::config::limits::MAX_STREAM_BUFFER)
            .contains(&buffer)
        {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics_stream.buffer",
                format!(
                    "buffer must be in {}..={} (the queue's whole memory story; \
                     a full queue drops and counts, it never blocks)",
                    crate::config::limits::MIN_STREAM_BUFFER,
                    crate::config::limits::MAX_STREAM_BUFFER,
                ),
            ));
        }
    }
    if let Some(flush) = cfg.flush_ms {
        if !(crate::config::limits::MIN_STREAM_FLUSH_MS
            ..=crate::config::limits::MAX_STREAM_FLUSH_MS)
            .contains(&flush)
        {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics_stream.flush_ms",
                format!(
                    "flush_ms must be in {}..={} (maximum batch latency)",
                    crate::config::limits::MIN_STREAM_FLUSH_MS,
                    crate::config::limits::MAX_STREAM_FLUSH_MS,
                ),
            ));
        }
    }
    if let Some(batch) = cfg.batch_max {
        if batch == 0 || batch > crate::config::limits::MAX_STREAM_BATCH_RECORDS {
            issues.push(issue(
                "gateway",
                "(root)",
                "analytics_stream.batch_max",
                format!(
                    "batch_max must be in 1..={} (records per flushed batch — \
                     also the largest single delivery)",
                    crate::config::limits::MAX_STREAM_BATCH_RECORDS,
                ),
            ));
        }
    }
}

/// Whether a string is a valid RFC 6265 cookie-name (the RFC 2616
/// `token` grammar: alphanumerics and `!#$%&'*+-.^_`|~` — no
/// separators, spaces, or controls). DW-040's sticky cookie names ride
/// `Set-Cookie` headers serialized by hand-adjacent code paths, so the
/// name must be provably header-safe.
fn is_cookie_name(name: &str) -> bool {
    !name.is_empty()
        && name.bytes().all(|b| {
            b.is_ascii_alphanumeric()
                || matches!(
                    b,
                    b'!' | b'#'
                        | b'$'
                        | b'%'
                        | b'&'
                        | b'\''
                        | b'*'
                        | b'+'
                        | b'-'
                        | b'.'
                        | b'^'
                        | b'_'
                        | b'`'
                        | b'|'
                        | b'~'
                )
        })
}

/// DW-091: validate one canary analysis rule. Error-rate thresholds
/// must be in [0.0, 1.0] (a fraction); latency thresholds must be > 0
/// (a 0-ms threshold would trigger on every request).
fn validate_canary_rule(
    service: &str,
    field: &str,
    rule: &crate::config::CanaryRule,
    issues: &mut Vec<ValidationIssue>,
) {
    match rule.metric {
        crate::config::CanaryMetric::ErrorRate => {
            if rule.threshold < 0.0 || rule.threshold > 1.0 {
                issues.push(issue(
                    "service",
                    service,
                    &format!("{field}.threshold"),
                    "error_rate threshold must be in [0.0, 1.0] (a fraction)",
                ));
            }
        }
        crate::config::CanaryMetric::LatencyP99
        | crate::config::CanaryMetric::LatencyP95
        | crate::config::CanaryMetric::LatencyP50 => {
            if rule.threshold <= 0.0 {
                issues.push(issue(
                    "service",
                    service,
                    &format!("{field}.threshold"),
                    "latency threshold must be > 0 (milliseconds)",
                ));
            }
        }
    }
}

/// DW-091: validate one canary analysis rule for an AI model alias.
/// Same bounds as [`validate_canary_rule`] but uses the `gateway`
/// scope and the alias in the field path.
fn validate_ai_canary_rule(
    alias: &str,
    field: &str,
    rule: &crate::config::CanaryRule,
    issues: &mut Vec<ValidationIssue>,
) {
    match rule.metric {
        crate::config::CanaryMetric::ErrorRate => {
            if rule.threshold < 0.0 || rule.threshold > 1.0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].{field}.threshold"),
                    "error_rate threshold must be in [0.0, 1.0] (a fraction)",
                ));
            }
        }
        crate::config::CanaryMetric::LatencyP99
        | crate::config::CanaryMetric::LatencyP95
        | crate::config::CanaryMetric::LatencyP50 => {
            if rule.threshold <= 0.0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].{field}.threshold"),
                    "latency threshold must be > 0 (milliseconds)",
                ));
            }
        }
    }
}

/// Check semantic integrity of a parsed [`Gateway`]. An empty Vec means valid.
/// Validate the `ai:` block (DW-075): provider names unique and
/// non-empty, provider `upstream` references resolve, auth headers are
/// valid and their values RESOLVE (the DW-045 compile-time contract —
/// an unresolvable reference fails the generation closed), and model
/// aliases reference known providers with non-empty provider model
/// ids. Issues name the offending field; never a resolved value.
fn validate_ai(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    let Some(ai) = &gateway.ai else { return };
    if ai.providers.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "ai.providers",
            "the ai block is present but declares no providers: it could never \
             serve a model (remove the block, or declare at least one provider)",
        ));
    }
    if ai.models.is_empty() {
        issues.push(issue(
            "gateway",
            "(root)",
            "ai.models",
            "the ai block is present but declares no models: no client model \
             could ever resolve (remove the block, or map at least one alias)",
        ));
    }
    let mut names = std::collections::BTreeSet::new();
    for p in &ai.providers {
        if p.name.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "ai.providers[].name",
                "provider name must be non-empty",
            ));
            continue;
        }
        if !names.insert(p.name.as_str()) {
            issues.push(issue(
                "gateway",
                &p.name,
                "ai.providers[].name",
                "duplicate ai provider name",
            ));
        }
        if !gateway.upstreams.iter().any(|u| u.name == p.upstream) {
            issues.push(issue(
                "gateway",
                &p.name,
                "ai.providers[].upstream",
                format!(
                    "references unknown upstream '{}' (the provider's transport \
                     is a standard upstreams entry)",
                    p.upstream
                ),
            ));
        }
        if let Some(path) = &p.path {
            if path.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].path",
                    "provider path override must be non-empty (remove the \
                     field to use the adapter's default path)",
                ));
            } else if !path.starts_with('/') {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].path",
                    format!(
                        "provider path override '{path}' must start with '/' \
                         (it is a request path, not a full URL)"
                    ),
                ));
            }
        }
        if let Some(auth) = &p.auth {
            if hyper::header::HeaderName::from_bytes(auth.header.as_bytes()).is_err() {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].auth.header",
                    format!("'{}' is not a valid HTTP header name", auth.header),
                ));
            }
            // DW-45 compile-time contract: the value must resolve AND
            // be representable as a header value. Issues name the
            // provider and reason, never the value.
            let problem = match crate::config::credentials::resolve_configured_secret(&auth.value) {
                Ok(resolved) => {
                    if hyper::header::HeaderValue::from_str(&resolved).is_err() {
                        Some(
                            "the auth value (after secret-reference resolution) \
                             contains characters that cannot appear in an HTTP \
                             header value"
                                .to_string(),
                        )
                    } else {
                        None
                    }
                }
                Err(message) => Some(message),
            };
            if let Some(message) = problem {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].auth.value",
                    format!("provider auth: {message}"),
                ));
            }
        }
        // DW-080: credential pool validation.
        if let Some(pool) = &p.credential_pool {
            // Ent-only: reject when the ent feature is off.
            #[cfg(not(feature = "ent"))]
            {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].credential_pool",
                    "credential pools require the enterprise edition (build with \
                 --features ent)",
                ));
            }
            // auth and credential_pool are mutually exclusive.
            if p.auth.is_some() {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].credential_pool",
                    "credential_pool and auth are mutually exclusive; use one or \
                     the other",
                ));
            }
            // At least 2 entries required.
            if pool.credentials.len() < 2 {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].credential_pool.credentials",
                    "credential pool requires at least 2 entries (a single-entry \
                     pool is equivalent to auth)",
                ));
            }
            // Each entry: validate header name + resolve value.
            for (i, cred) in pool.credentials.iter().enumerate() {
                if hyper::header::HeaderName::from_bytes(cred.header.as_bytes()).is_err() {
                    issues.push(issue(
                        "gateway",
                        &p.name,
                        &format!("ai.providers[].credential_pool.credentials[{i}].header"),
                        format!("'{}' is not a valid HTTP header name", cred.header),
                    ));
                }
                let problem =
                    match crate::config::credentials::resolve_configured_secret(&cred.value) {
                        Ok(resolved) => {
                            if hyper::header::HeaderValue::from_str(&resolved).is_err() {
                                Some(
                                    "the credential value (after secret-reference \
                                 resolution) contains characters that cannot appear \
                                 in an HTTP header value"
                                        .to_string(),
                                )
                            } else {
                                None
                            }
                        }
                        Err(message) => Some(message),
                    };
                if let Some(message) = problem {
                    issues.push(issue(
                        "gateway",
                        &p.name,
                        &format!("ai.providers[].credential_pool.credentials[{i}].value"),
                        format!("credential pool entry {i}: {message}"),
                    ));
                }
            }
            // Quarantine window bounds.
            if pool.quarantine_secs == 0 {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].credential_pool.quarantine_secs",
                    "quarantine_secs must be greater than 0",
                ));
            }
            if pool.quarantine_secs > 600 {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "ai.providers[].credential_pool.quarantine_secs",
                    "quarantine_secs must not exceed 600 (10 minutes)",
                ));
            }
        }
    }
    for (alias, m) in &ai.models {
        if alias.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                "ai.models",
                "model alias must be non-empty",
            ));
        }
        if !names.contains(m.provider.as_str()) {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}].provider"),
                format!("references unknown ai provider '{}'", m.provider),
            ));
        }
        if m.provider_model.trim().is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}].provider_model"),
                "provider_model must be non-empty",
            ));
        }
        // DW-076: failover and canary are mutually exclusive per alias
        // (the config docs explain why: failover retries a canary
        // request onto the stable version and silently undoes the
        // experiment). DW-085: a routing policy is mutually exclusive
        // with both — a policy alias composes over OTHER aliases'
        // routing plans, so it has no provider/model pair of its own.
        if !m.failover.is_empty() && !m.canary.is_empty() {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}]"),
                "an alias cannot declare both failover and canary: \
                 failover is an availability chain for one logical model, \
                 a canary split deliberately serves several versions — \
                 combine them on separate aliases",
            ));
        }
        if m.routing_policy.is_some() && (!m.failover.is_empty() || !m.canary.is_empty()) {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}]"),
                "an alias cannot declare a routing_policy together with \
                 failover or canary: a policy alias composes over other \
                 aliases' routing plans and has no provider/model pair of \
                 its own — combine them on separate aliases",
            ));
        }
        // DW-086: ab_test is mutually exclusive with failover, canary,
        // and routing_policy (an experiment alias composes over OTHER
        // aliases' routing plans, same as a policy alias).
        if m.ab_test.is_some()
            && (!m.failover.is_empty() || !m.canary.is_empty() || m.routing_policy.is_some())
        {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}]"),
                "an alias cannot declare an ab_test together with \
                 failover, canary, or routing_policy: an experiment alias \
                 composes over other aliases' routing plans and has no \
                 provider/model pair of its own — combine them on separate \
                 aliases",
            ));
        }
        // DW-086: the referenced A/B test must exist in
        // ai.experiments.ab_tests.
        if let Some(test_name) = &m.ab_test {
            let exists = ai
                .experiments
                .as_ref()
                .map(|e| e.ab_tests.contains_key(test_name))
                .unwrap_or(false);
            if !exists {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].ab_test"),
                    format!(
                        "references unknown A/B test '{}' (not in \
                         ai.experiments.ab_tests — a typo, or the test was \
                         removed, or ai.experiments is not configured)",
                        test_name
                    ),
                ));
            }
        }
        // DW-085: the referenced routing policy must exist.
        if let Some(policy_name) = &m.routing_policy {
            if !ai.routing_policies.contains_key(policy_name) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].routing_policy"),
                    format!(
                        "references unknown routing policy '{}' (not in \
                         ai.routing_policies — a typo, or the policy was \
                         removed)",
                        policy_name
                    ),
                ));
            }
        }
        // DW-076: the failover chain. Bounded to 4 alternates (the
        // chain is walked synchronously — every extra candidate adds a
        // full provider round-trip to the request's worst-case
        // latency, the same reasoning that bounds splits). Entries
        // must resolve, and the chain must not repeat a provider/model
        // pair (a duplicate would re-send to a target that just failed
        // — the provider's upstream breaker owns same-target retries).
        if m.failover.len() > 4 {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}].failover"),
                format!(
                    "failover accepts at most 4 alternates ({} given): the \
                     chain is walked synchronously, so every extra candidate \
                     adds a full provider round-trip to the request's \
                     worst-case latency",
                    m.failover.len()
                ),
            ));
        }
        let mut chain = vec![(m.provider.as_str(), m.provider_model.as_str())];
        for (i, f) in m.failover.iter().enumerate() {
            if !names.contains(f.provider.as_str()) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].failover[{i}].provider"),
                    format!("references unknown ai provider '{}'", f.provider),
                ));
            }
            if f.provider_model.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].failover[{i}].provider_model"),
                    "provider_model must be non-empty",
                ));
            }
            if chain.contains(&(f.provider.as_str(), f.provider_model.as_str())) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].failover[{i}]"),
                    format!(
                        "duplicates the provider/model pair ('{}' / '{}') already \
                         earlier in the chain — the upstream breaker owns \
                         same-target retries",
                        f.provider, f.provider_model
                    ),
                ));
            } else {
                chain.push((f.provider.as_str(), f.provider_model.as_str()));
            }
        }
        // DW-076: the canary split. Bounded to 2..=8 versions (the
        // DW-040 split bound: the pick scans linearly, and every
        // version is a metrics label — an unbounded list is a series
        // explosion; one version is not a split, it is the whole
        // model). Version names unique and non-empty, weights >= 1,
        // providers resolve.
        if !m.canary.is_empty() && !(2..=8).contains(&m.canary.len()) {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("ai.models[{alias}].canary"),
                format!(
                    "a canary split needs 2..=8 versions ({} given): one \
                     version is the whole model (no split), and every version \
                     is a metrics label — the bound keeps the pick cheap and \
                     the series count sane",
                    m.canary.len()
                ),
            ));
        }
        let mut versions = std::collections::BTreeSet::new();
        for (i, v) in m.canary.iter().enumerate() {
            if v.version.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary[{i}].version"),
                    "version name must be non-empty",
                ));
            }
            if !versions.insert(v.version.as_str()) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary[{i}].version"),
                    format!("duplicate version name '{}'", v.version),
                ));
            }
            if v.weight == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary[{i}].weight"),
                    "weight must be >= 1 (park a version by removing the \
                     entry, not by zeroing it)",
                ));
            }
            if !names.contains(v.provider.as_str()) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary[{i}].provider"),
                    format!("references unknown ai provider '{}'", v.provider),
                ));
            }
            if v.provider_model.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary[{i}].provider_model"),
                    "provider_model must be non-empty",
                ));
            }
        }
        // DW-091: canary_analysis validation on AI model aliases.
        // Only valid on a 2-version canary (baseline + canary);
        // the controller compares exactly two sides. Same bounds as
        // service-level canary_analysis.
        if let Some(analysis) = &m.canary_analysis {
            if m.canary.len() != 2 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary_analysis"),
                    "canary_analysis requires exactly 2 canary versions (baseline + canary): \
                     the controller compares two sides",
                ));
            }
            if analysis.window_seconds == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary_analysis.window_seconds"),
                    "window_seconds must be >= 1",
                ));
            }
            if analysis.step == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary_analysis.step"),
                    "step must be >= 1 (a 0-step never adjusts)",
                ));
            }
            if analysis.min_requests == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary_analysis.min_requests"),
                    "min_requests must be >= 1",
                ));
            }
            if analysis.cooldown_seconds == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.models[{alias}].canary_analysis.cooldown_seconds"),
                    "cooldown_seconds must be >= 1",
                ));
            }
            validate_ai_canary_rule(alias, "canary_analysis.promote", &analysis.promote, issues);
            validate_ai_canary_rule(
                alias,
                "canary_analysis.rollback",
                &analysis.rollback,
                issues,
            );
        }
    }
    // DW-084: governance team_allowlists must reference model aliases
    // that exist in the `models` map. A typo in an allowlist that
    // names a non-existent alias is an authoring error — the runtime
    // would block every call to it (the alias never matches), so
    // validation names it at publish time instead.
    if let Some(gov) = &ai.governance {
        let known: std::collections::BTreeSet<&str> =
            ai.models.keys().map(|s| s.as_str()).collect();
        for (policy, allowlist) in &gov.team_allowlists {
            // The policy itself must exist (a typo'd policy name would
            // silently bind nobody — an allowlist that governs nothing).
            if !gateway.policies.iter().any(|p| &p.name == policy) {
                issues.push(issue(
                    "gateway",
                    policy,
                    "ai.governance.team_allowlists",
                    format!(
                        "references unknown policy '{}' (the allowlist would \
                         govern nobody — a typo, or the policy was removed)",
                        policy
                    ),
                ));
            }
            for (i, alias) in allowlist.iter().enumerate() {
                if !known.contains(alias.as_str()) {
                    issues.push(issue(
                        "gateway",
                        policy,
                        &format!("ai.governance.team_allowlists[{policy}][{i}]"),
                        format!(
                            "references unknown model alias '{}' (not in \
                             ai.models — a typo, or the alias was renamed)",
                            alias
                        ),
                    ));
                }
            }
        }
    }
    // DW-081: prompt/response logging validation. The sample rate
    // must be 0.0..=1.0, retention must be > 0 when enabled, and
    // custom redaction patterns must be valid regexes (compiled at
    // validation time — invalid regex fails at publish).
    if let Some(logging) = &ai.logging {
        if !(0.0..=1.0).contains(&logging.sample_rate) {
            issues.push(issue(
                "gateway",
                "(root)",
                "ai.logging.sample_rate",
                format!(
                    "sample_rate must be between 0.0 and 1.0 (got {})",
                    logging.sample_rate
                ),
            ));
        }
        if logging.enabled && logging.retention_secs == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "ai.logging.retention_secs",
                "retention_secs must be > 0 when logging is enabled \
                 (0 would retain records forever — omit the field for \
                 the 7-day default, or set a positive value)",
            ));
        }
        for (i, pat) in logging.redaction.patterns.iter().enumerate() {
            if regex::Regex::new(pat).is_err() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.logging.redaction.patterns[{i}]"),
                    format!(
                        "'{}' is not a valid regex pattern (the custom \
                         redaction pattern must compile)",
                        pat
                    ),
                ));
            }
        }
    }
    // DW-082: guardrails validation. Rule names must be unique, regex
    // patterns must compile, and JSON schemas (for schema-kind rules)
    // must be valid. Policy references must name existing policies
    // (a typo'd policy name would silently bind nobody).
    if let Some(guardrails) = &ai.guardrails {
        let mut rule_names = std::collections::BTreeSet::new();
        for (i, rule) in guardrails.rules.iter().enumerate() {
            if rule.name.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.guardrails.rules[{i}].name"),
                    "guardrail rule name must be non-empty",
                ));
            } else if !rule_names.insert(rule.name.as_str()) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    &format!("ai.guardrails.rules[{i}].name"),
                    format!("duplicate guardrail rule name '{}'", rule.name),
                ));
            }
            // Validate regex patterns compile.
            for (j, pat) in rule.patterns.iter().enumerate() {
                if regex::Regex::new(pat).is_err() {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("ai.guardrails.rules[{i}].patterns[{j}]"),
                        format!(
                            "'{}' is not a valid regex pattern (the guardrail \
                             pattern must compile)",
                            pat
                        ),
                    ));
                }
            }
            // Validate schema-kind rules have a schema.
            if rule.kind == crate::config::ai::AiGuardrailKind::Schema && rule.schema.is_none() {
                issues.push(issue(
                    "gateway",
                    &rule.name,
                    &format!("ai.guardrails.rules[{i}].schema"),
                    "a schema-kind guardrail rule must declare a JSON schema \
                     (the `schema` field is required for kind: schema)",
                ));
            }
            // Validate schema is valid JSON (it is already parsed by
            // serde, so this is always true — but check it is an
            // object or bool, the valid JSON Schema root shapes).
            if let Some(schema) = &rule.schema {
                if !schema.is_object() && !schema.is_boolean() {
                    issues.push(issue(
                        "gateway",
                        &rule.name,
                        &format!("ai.guardrails.rules[{i}].schema"),
                        "a JSON schema must be an object or a boolean \
                         (the root schema shape)",
                    ));
                }
            }
            // Validate policy references exist.
            for (j, policy) in rule.policies.iter().enumerate() {
                if !gateway.policies.iter().any(|p| &p.name == policy) {
                    issues.push(issue(
                        "gateway",
                        &rule.name,
                        &format!("ai.guardrails.rules[{i}].policies[{j}]"),
                        format!(
                            "references unknown policy '{}' (the rule would \
                             apply to nobody — a typo, or the policy was removed)",
                            policy
                        ),
                    ));
                }
            }
            // Redact action is prompt-phase only (a redact at the
            // response phase is a no-op — warn, not reject, since it
            // is a benign misconfiguration).
            if rule.action == crate::config::ai::AiGuardrailAction::Redact
                && !matches!(
                    rule.phase,
                    crate::config::ai::AiGuardrailPhase::Prompt
                        | crate::config::ai::AiGuardrailPhase::Both
                )
            {
                // This is not a hard error — a redact at the response
                // phase is treated as a log by the engine. But name
                // it so the operator notices.
                issues.push(issue(
                    "gateway",
                    &rule.name,
                    &format!("ai.guardrails.rules[{i}].action"),
                    "redact action is only effective at the prompt phase; \
                     at the response phase it is treated as log (dry-run)",
                ));
            }
        }
    }
    // DW-083: semantic cache validation. When enabled, the embedding
    // URL/model/dim must be valid, the threshold in [0.0, 1.0], and
    // the TTL/max-entries/timeout positive. A disabled block is
    // accepted without further checks (it is inert).
    if let Some(sem_cache) = &ai.semantic_cache {
        if sem_cache.enabled {
            if sem_cache.embedding_url.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.embedding_url",
                    "the semantic cache embedding_url must be non-empty when \
                     enabled (the OpenAI-compatible /v1/embeddings endpoint)",
                ));
            } else if !sem_cache.embedding_url.starts_with("http://")
                && !sem_cache.embedding_url.starts_with("https://")
            {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.embedding_url",
                    "the semantic cache embedding_url must be an http or https \
                     URL",
                ));
            }
            if sem_cache.embedding_model.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.embedding_model",
                    "the semantic cache embedding_model must be non-empty when \
                     enabled (the model name passed to the embedding service)",
                ));
            }
            if sem_cache.embedding_dim == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.embedding_dim",
                    "the semantic cache embedding_dim must be > 0 (it must \
                     match the embedding service's vector dimension)",
                ));
            }
            if !(0.0..=1.0).contains(&sem_cache.threshold) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.threshold",
                    format!(
                        "the semantic cache threshold must be in [0.0, 1.0] \
                         (got {})",
                        sem_cache.threshold
                    ),
                ));
            }
            if sem_cache.ttl_secs == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.ttl_secs",
                    "the semantic cache ttl_secs must be > 0",
                ));
            }
            if sem_cache.max_entries == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.max_entries",
                    "the semantic cache max_entries must be > 0",
                ));
            }
            if sem_cache.embedding_timeout_ms == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.semantic_cache.embedding_timeout_ms",
                    "the semantic cache embedding_timeout_ms must be > 0",
                ));
            }
        }
    }
    // DW-085: routing policies validation. The referenced model
    // aliases must exist (a typo would route to nothing), the
    // classifier URL/model valid for FallbackChain, the threshold in
    // [0.0, 1.0] and timeout > 0, and candidates non-empty with
    // cost/latency in 1-10 for LatencyCost. Policy aliases (those
    // with `routing_policy` set) cannot be referenced by other
    // policies (no nested policies — a policy composes over plain
    // chain/canary aliases only).
    let policy_aliases: std::collections::BTreeSet<&str> = ai
        .models
        .iter()
        .filter(|(_, m)| m.routing_policy.is_some())
        .map(|(alias, _)| alias.as_str())
        .collect();
    for (policy_name, policy) in &ai.routing_policies {
        match policy {
            crate::config::ai::AiRoutingPolicy::FallbackChain(p) => {
                if !ai.models.contains_key(&p.cheap) {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].cheap",
                        format!(
                            "references unknown model alias '{}' (not in \
                             ai.models — a typo, or the alias was renamed)",
                            p.cheap
                        ),
                    ));
                } else if policy_aliases.contains(p.cheap.as_str()) {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].cheap",
                        format!(
                            "references alias '{}' which is itself a policy \
                             alias (nested policies are not allowed — a policy \
                             composes over plain chain/canary aliases only)",
                            p.cheap
                        ),
                    ));
                }
                if !ai.models.contains_key(&p.escalate_to) {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].escalate_to",
                        format!(
                            "references unknown model alias '{}' (not in \
                             ai.models — a typo, or the alias was renamed)",
                            p.escalate_to
                        ),
                    ));
                } else if policy_aliases.contains(p.escalate_to.as_str()) {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].escalate_to",
                        format!(
                            "references alias '{}' which is itself a policy \
                             alias (nested policies are not allowed — a policy \
                             composes over plain chain/canary aliases only)",
                            p.escalate_to
                        ),
                    ));
                }
                if p.classifier_url.trim().is_empty() {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].classifier_url",
                        "the classifier_url must be non-empty (the external \
                         complexity-classifier service endpoint)",
                    ));
                } else if !p.classifier_url.starts_with("http://")
                    && !p.classifier_url.starts_with("https://")
                {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].classifier_url",
                        "the classifier_url must be an http or https URL",
                    ));
                }
                if p.classifier_model.trim().is_empty() {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].classifier_model",
                        "the classifier_model must be non-empty (the model \
                         name passed to the classifier service)",
                    ));
                }
                if !(0.0..=1.0).contains(&p.threshold) {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].threshold",
                        format!("the threshold must be in [0.0, 1.0] (got {})", p.threshold),
                    ));
                }
                if p.timeout_ms == 0 {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[fallback_chain].timeout_ms",
                        "the timeout_ms must be > 0",
                    ));
                }
            }
            crate::config::ai::AiRoutingPolicy::LatencyCost(p) => {
                if p.candidates.is_empty() {
                    issues.push(issue(
                        "gateway",
                        policy_name,
                        "ai.routing_policies[latency_cost].candidates",
                        "a latency_cost policy must declare at least one \
                         candidate (an empty list would route to nothing)",
                    ));
                }
                for (i, c) in p.candidates.iter().enumerate() {
                    if !ai.models.contains_key(&c.model) {
                        issues.push(issue(
                            "gateway",
                            policy_name,
                            &format!("ai.routing_policies[latency_cost].candidates[{i}].model"),
                            format!(
                                "references unknown model alias '{}' (not in \
                                 ai.models — a typo, or the alias was renamed)",
                                c.model
                            ),
                        ));
                    } else if policy_aliases.contains(c.model.as_str()) {
                        issues.push(issue(
                            "gateway",
                            policy_name,
                            &format!("ai.routing_policies[latency_cost].candidates[{i}].model"),
                            format!(
                                "references alias '{}' which is itself a policy \
                                 alias (nested policies are not allowed — a \
                                 policy composes over plain chain/canary aliases \
                                 only)",
                                c.model
                            ),
                        ));
                    }
                    if !(1..=10).contains(&c.cost) {
                        issues.push(issue(
                            "gateway",
                            policy_name,
                            &format!("ai.routing_policies[latency_cost].candidates[{i}].cost"),
                            format!("the cost score must be in 1..=10 (got {})", c.cost),
                        ));
                    }
                    if !(1..=10).contains(&c.latency) {
                        issues.push(issue(
                            "gateway",
                            policy_name,
                            &format!("ai.routing_policies[latency_cost].candidates[{i}].latency"),
                            format!("the latency score must be in 1..=10 (got {})", c.latency),
                        ));
                    }
                }
            }
        }
    }

    // DW-086: experiments validation. A/B test variants must reference
    // existing plain (non-policy, non-experiment) model aliases; prompt
    // references must resolve to existing prompt versions; evals must
    // reference existing model aliases and valid prompt versions.
    // Experiment aliases (those with `ab_test` set) cannot be
    // referenced by other experiments (no nested experiments — an
    // experiment composes over plain chain/canary aliases only).
    let experiment_aliases: std::collections::BTreeSet<&str> = ai
        .models
        .iter()
        .filter(|(_, m)| m.ab_test.is_some())
        .map(|(alias, _)| alias.as_str())
        .collect();
    if let Some(experiments) = &ai.experiments {
        // Validate A/B tests.
        for (test_name, test) in &experiments.ab_tests {
            if test.variants.len() < 2 {
                issues.push(issue(
                    "gateway",
                    test_name,
                    &format!("ai.experiments.ab_tests[{test_name}].variants"),
                    "an A/B test must have at least 2 variants (got \
                     fewer)",
                ));
            }
            for (i, variant) in test.variants.iter().enumerate() {
                if !ai.models.contains_key(&variant.model) {
                    issues.push(issue(
                        "gateway",
                        test_name,
                        &format!("ai.experiments.ab_tests[{test_name}].variants[{i}].model"),
                        format!(
                            "references unknown model alias '{}' (not in \
                             ai.models — a typo, or the alias was renamed)",
                            variant.model
                        ),
                    ));
                } else if policy_aliases.contains(variant.model.as_str())
                    || experiment_aliases.contains(variant.model.as_str())
                {
                    issues.push(issue(
                        "gateway",
                        test_name,
                        &format!("ai.experiments.ab_tests[{test_name}].variants[{i}].model"),
                        format!(
                            "references alias '{}' which is itself a policy \
                             or experiment alias (nested policies/experiments \
                             are not allowed — an experiment composes over \
                             plain chain/canary aliases only)",
                            variant.model
                        ),
                    ));
                }
                if variant.weight == 0 {
                    issues.push(issue(
                        "gateway",
                        test_name,
                        &format!("ai.experiments.ab_tests[{test_name}].variants[{i}].weight"),
                        "a variant weight must be >= 1 (got 0)",
                    ));
                }
                // Validate prompt reference if present.
                if let Some(prompt_ref) = &variant.prompt {
                    if let Some((prompt_name, version_name)) = prompt_ref.split_once('/') {
                        let prompt_exists = experiments
                            .prompts
                            .get(prompt_name)
                            .is_some_and(|p| p.versions.contains_key(version_name));
                        if !prompt_exists {
                            issues.push(issue(
                                "gateway",
                                test_name,
                                &format!(
                                    "ai.experiments.ab_tests[{test_name}].variants[{i}].prompt"
                                ),
                                format!(
                                    "references unknown prompt version '{}' \
                                     (not in ai.experiments.prompts — a typo, \
                                     or the prompt/version was removed)",
                                    prompt_ref
                                ),
                            ));
                        }
                    } else {
                        issues.push(issue(
                            "gateway",
                            test_name,
                            &format!("ai.experiments.ab_tests[{test_name}].variants[{i}].prompt"),
                            format!(
                                "prompt reference '{}' must be in the form \
                                 'prompt_name/version_name'",
                                prompt_ref
                            ),
                        ));
                    }
                }
            }
        }
        // Validate prompts: active version must exist.
        for (prompt_name, prompt) in &experiments.prompts {
            if !prompt.versions.contains_key(&prompt.active) {
                issues.push(issue(
                    "gateway",
                    prompt_name,
                    &format!("ai.experiments.prompts[{prompt_name}].active"),
                    format!(
                        "references unknown version '{}' (not in \
                         ai.experiments.prompts[{prompt_name}].versions — \
                         a typo, or the version was removed)",
                        prompt.active
                    ),
                ));
            }
            if prompt.versions.is_empty() {
                issues.push(issue(
                    "gateway",
                    prompt_name,
                    &format!("ai.experiments.prompts[{prompt_name}].versions"),
                    "a prompt must have at least one version",
                ));
            }
        }
        // Validate evals: prompt reference must resolve, golden set
        // non-empty. The model alias is specified at eval run time by
        // the admin endpoint (the eval config does not bind to a
        // specific model — the same eval can run against any model).
        for (eval_name, eval) in &experiments.evals {
            if let Some(prompt_ref) = &eval.prompt {
                if let Some((prompt_name, version_name)) = prompt_ref.split_once('/') {
                    let prompt_exists = experiments
                        .prompts
                        .get(prompt_name)
                        .is_some_and(|p| p.versions.contains_key(version_name));
                    if !prompt_exists {
                        issues.push(issue(
                            "gateway",
                            eval_name,
                            &format!("ai.experiments.evals[{eval_name}].prompt"),
                            format!(
                                "references unknown prompt version '{}' \
                                 (not in ai.experiments.prompts)",
                                prompt_ref
                            ),
                        ));
                    }
                } else {
                    issues.push(issue(
                        "gateway",
                        eval_name,
                        &format!("ai.experiments.evals[{eval_name}].prompt"),
                        format!(
                            "prompt reference '{}' must be in the form \
                             'prompt_name/version_name'",
                            prompt_ref
                        ),
                    ));
                }
            }
            if eval.golden_set.is_empty() {
                issues.push(issue(
                    "gateway",
                    eval_name,
                    &format!("ai.experiments.evals[{eval_name}].golden_set"),
                    "an eval must have at least one golden-set case",
                ));
            }
            for (i, case) in eval.golden_set.iter().enumerate() {
                if case.input.is_empty() {
                    issues.push(issue(
                        "gateway",
                        eval_name,
                        &format!("ai.experiments.evals[{eval_name}].golden_set[{i}].input"),
                        "an eval case input must be non-empty",
                    ));
                }
                if case.expected.is_empty() {
                    issues.push(issue(
                        "gateway",
                        eval_name,
                        &format!("ai.experiments.evals[{eval_name}].golden_set[{i}].expected"),
                        "an eval case expected value must be non-empty",
                    ));
                }
                if let Some(scorer) = &case.scorer {
                    if scorer != "exact_match" && scorer != "contains" && scorer != "regex" {
                        issues.push(issue(
                            "gateway",
                            eval_name,
                            &format!(
                                "ai.experiments.evals[{eval_name}].golden_set[{i}].scorer"
                            ),
                            format!(
                                "unknown scorer '{}' (must be one of: exact_match, contains, regex)",
                                scorer
                            ),
                        ));
                    }
                    if scorer == "regex" {
                        if let Err(e) = regex::Regex::new(&case.expected) {
                            issues.push(issue(
                                "gateway",
                                eval_name,
                                &format!(
                                    "ai.experiments.evals[{eval_name}].golden_set[{i}].expected"
                                ),
                                format!("invalid regex pattern for regex scorer: {e}",),
                            ));
                        }
                    }
                }
            }
        }
    }

    // DW-087: MCP gateway validation. Tool names are non-empty (the
    // BTreeMap key enforces uniqueness; empty keys are impossible via
    // serde but trim-empty descriptions are caught here). Each tool's
    // `upstream` must reference a known upstream. The `path` (if
    // present) must start with `/`. Session TTL and max_concurrent
    // must be positive.
    if let Some(mcp) = &ai.mcp {
        let upstream_names: std::collections::BTreeSet<&str> =
            gateway.upstreams.iter().map(|u| u.name.as_str()).collect();
        for (name, tool) in &mcp.tools {
            if name.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.mcp.tools",
                    "tool name must be non-empty",
                ));
            }
            if tool.description.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    name,
                    "ai.mcp.tools.description",
                    "tool description must be non-empty",
                ));
            }
            if !upstream_names.contains(tool.upstream.as_str()) {
                issues.push(issue(
                    "gateway",
                    name,
                    "ai.mcp.tools.upstream",
                    format!(
                        "references unknown upstream '{}' (not in \
                         upstreams[] — a typo, or the upstream was renamed)",
                        tool.upstream
                    ),
                ));
            }
            if let Some(path) = &tool.path {
                if !path.starts_with('/') {
                    issues.push(issue(
                        "gateway",
                        name,
                        "ai.mcp.tools.path",
                        "the path must start with '/' (it is appended to the upstream endpoint)",
                    ));
                }
            }
            if let Some(method) = &tool.method {
                let m = method.to_ascii_uppercase();
                if !matches!(m.as_str(), "GET" | "POST" | "PUT" | "PATCH" | "DELETE") {
                    issues.push(issue(
                        "gateway",
                        name,
                        "ai.mcp.tools.method",
                        format!(
                            "unknown HTTP method '{}' (must be GET, POST, PUT, PATCH, or DELETE)",
                            method
                        ),
                    ));
                }
            }
            if !tool.input_schema.is_object() {
                issues.push(issue(
                    "gateway",
                    name,
                    "ai.mcp.tools.input_schema",
                    "input_schema must be a JSON object (a JSON Schema for the tool's arguments)",
                ));
            }
            if let Some(timeout) = tool.timeout_ms {
                if timeout == 0 {
                    issues.push(issue(
                        "gateway",
                        name,
                        "ai.mcp.tools.timeout_ms",
                        "timeout_ms must be > 0 (omit for the default 30s)",
                    ));
                }
            }
        }
        if let Some(sessions) = &mcp.sessions {
            if let Some(ttl) = sessions.ttl_secs {
                if ttl == 0 {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "ai.mcp.sessions.ttl_secs",
                        "ttl_secs must be > 0 (omit for the default 3600s)",
                    ));
                }
            }
            if let Some(max) = sessions.max_concurrent {
                if max == 0 {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "ai.mcp.sessions.max_concurrent",
                        "max_concurrent must be > 0 (omit for the default 1000)",
                    ));
                }
            }
        }
        if let Some(path) = &mcp.path {
            if !path.starts_with('/') {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.mcp.path",
                    "the path must start with '/' (it is a reserved HTTP path)",
                ));
            }
        }
    }

    // DW-114: A2A (agent-to-agent) validation. Agent names are
    // non-empty and unique, each agent's `upstream` references a
    // known upstream, the `url` is an http/https URL, and the inline
    // card (when present) is a JSON object. Session TTL and
    // max_concurrent must be positive. When the `a2a` cargo feature
    // is off, the block is accepted but a warning issue is emitted
    // (the block is inert -- no A2A providers are wired).
    if let Some(a2a) = &ai.a2a {
        // Feature gate: warn that the block is inert without the
        // `a2a` cargo feature (mirrors the ent-gated credential pool
        // warning pattern).
        let upstream_names: std::collections::BTreeSet<&str> =
            gateway.upstreams.iter().map(|u| u.name.as_str()).collect();
        let mut agent_names = std::collections::BTreeSet::new();
        for agent in &a2a.agents {
            if agent.name.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "ai.a2a.agents[].name",
                    "agent name must be non-empty",
                ));
            } else if !agent_names.insert(agent.name.as_str()) {
                issues.push(issue(
                    "gateway",
                    &agent.name,
                    "ai.a2a.agents[].name",
                    "duplicate a2a agent name",
                ));
            }
            if agent.url.trim().is_empty() {
                issues.push(issue(
                    "gateway",
                    &agent.name,
                    "ai.a2a.agents[].url",
                    "agent url must be non-empty",
                ));
            } else if !agent.url.starts_with("http://") && !agent.url.starts_with("https://") {
                issues.push(issue(
                    "gateway",
                    &agent.name,
                    "ai.a2a.agents[].url",
                    "the agent url must be an http or https URL",
                ));
            }
            if !upstream_names.contains(agent.upstream.as_str()) {
                issues.push(issue(
                    "gateway",
                    &agent.name,
                    "ai.a2a.agents[].upstream",
                    format!(
                        "references unknown upstream '{}' (not in \
                         upstreams[] -- a typo, or the upstream was renamed)",
                        agent.upstream
                    ),
                ));
            }
            if let Some(card) = &agent.card {
                if let Some(inline) = &card.inline {
                    if !inline.is_object() {
                        issues.push(issue(
                            "gateway",
                            &agent.name,
                            "ai.a2a.agents[].card.inline",
                            "the inline agent card must be a JSON object",
                        ));
                    }
                }
                if card.path.is_none() && card.inline.is_none() {
                    issues.push(issue(
                        "gateway",
                        &agent.name,
                        "ai.a2a.agents[].card",
                        "agent card has neither inline nor path set (set one)",
                    ));
                }
            }
        }
        if let Some(sessions) = &a2a.sessions {
            if let Some(ttl) = sessions.ttl_secs {
                if ttl == 0 {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "ai.a2a.sessions.ttl_secs",
                        "ttl_secs must be > 0 (omit for the default 3600s)",
                    ));
                }
            }
            if let Some(max) = sessions.max_concurrent {
                if max == 0 {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "ai.a2a.sessions.max_concurrent",
                        "max_concurrent must be > 0 (omit for the default 1000)",
                    ));
                }
            }
        }
    }
}

pub fn validate(gateway: &Gateway) -> Vec<ValidationIssue> {
    let mut issues = Vec::new();

    // Trusted proxies: each entry must be an IP address or CIDR (parsed by
    // the dataplane's trusted-proxy matcher; rejected here at compile time).
    for (i, entry) in gateway.trusted_proxies.iter().enumerate() {
        if crate::config::net::parse_ip_or_cidr(entry).is_none() {
            issues.push(issue(
                "gateway",
                "(root)",
                &format!("trusted_proxies[{i}]"),
                format!("'{entry}' is not an IP address or CIDR (e.g. 10.0.0.0/8 or ::1/128)"),
            ));
        }
    }

    if gateway.max_concurrent_requests == Some(0) {
        issues.push(issue(
            "gateway",
            "(root)",
            "max_concurrent_requests",
            "max_concurrent_requests must be > 0 (unlimited is expressed by \
             omitting the field, so an explicit 0 is rejected as ambiguous)",
        ));
    }

    // SEC-08 (#212): Global WAF validation. When enabled, each CRS
    // rule must have a valid regex pattern, a valid phase (1 or 2),
    // a valid severity (1-4), and valid target names. The paranoia
    // level must be 1-4, and the anomaly threshold must be > 0.
    if let Some(waf) = &gateway.waf {
        if waf.enabled {
            if !(1..=4).contains(&waf.paranoia_level) {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "waf.paranoia_level",
                    format!(
                        "paranoia_level {} is out of range: must be 1-4",
                        waf.paranoia_level
                    ),
                ));
            }
            if waf.anomaly_threshold == 0 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "waf.anomaly_threshold",
                    "anomaly_threshold must be > 0 (use dry_run for audit-only mode)",
                ));
            }
            if waf.max_body_inspect_bytes > 1_048_576 {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "waf.max_body_inspect_bytes",
                    format!(
                        "max_body_inspect_bytes {} is out of range: must be 0 \
                         (no body inspection) or 1..=1048576 (1 MiB)",
                        waf.max_body_inspect_bytes
                    ),
                ));
            }
            for (i, rule) in waf.rules.iter().enumerate() {
                if !(1..=4).contains(&rule.severity) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("waf.rules[{i}].severity"),
                        format!(
                            "rule {} severity {} is out of range: must be 1-4",
                            rule.id, rule.severity
                        ),
                    ));
                }
                if !(1..=2).contains(&rule.phase) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("waf.rules[{i}].phase"),
                        format!(
                            "rule {} phase {} is out of range: must be 1 (request headers) or 2 (request body)",
                            rule.id, rule.phase
                        ),
                    ));
                }
                if regex::Regex::new(&rule.pattern).is_err() {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("waf.rules[{i}].pattern"),
                        format!("rule {} has an invalid regex pattern", rule.id),
                    ));
                }
                for (j, target) in rule.targets.iter().enumerate() {
                    if !matches!(
                        target.as_str(),
                        "path" | "query" | "header" | "headers" | "body"
                    ) {
                        issues.push(issue(
                            "gateway",
                            "(root)",
                            &format!("waf.rules[{i}].targets[{j}]"),
                            format!(
                                "rule {} has unknown target '{}': must be path, query, header, headers, or body",
                                rule.id, target
                            ),
                        ));
                    }
                }
                for (j, t) in rule.transformations.iter().enumerate() {
                    if !matches!(
                        t.as_str(),
                        "lowercase"
                            | "url_decode"
                            | "html_entity_decode"
                            | "compress_whitespace"
                            | "remove_whitespace"
                            | "url_decode_uni"
                    ) {
                        issues.push(issue(
                            "gateway",
                            "(root)",
                            &format!("waf.rules[{i}].transformations[{j}]"),
                            format!("rule {} has unknown transformation '{}'", rule.id, t),
                        ));
                    }
                }
            }
        }
    }

    // Load-shed monitor mode (DW-041) is only meaningful with a cap: an
    // uncapped gateway never sheds, so the flag would be a silent no-op
    // that reads as monitoring coverage. Rejected rather than ignored so
    // the config cannot imply a guarantee it does not provide.
    if gateway.load_shed_dry_run && gateway.max_concurrent_requests.is_none() {
        issues.push(issue(
            "gateway",
            "(root)",
            "load_shed_dry_run",
            "load_shed_dry_run requires max_concurrent_requests: an uncapped gateway \
             never sheds, so the flag would be a silent no-op (set a cap, or omit \
             the flag)",
        ));
    }

    // Admission queues (DW-053): an enabled queue requires a cap (the
    // queue waits for a PERMIT from the cap's semaphore — no cap means
    // no permits to wait for, so the queue would be a silent no-op).
    // Bounds: max_queue_size 1..=10000, queue_timeout_ms 1..=10000.
    if let Some(aq) = &gateway.admission_queue {
        if aq.enabled && gateway.max_concurrent_requests.is_none() {
            issues.push(issue(
                "gateway",
                "(root)",
                "admission_queue.enabled",
                "admission_queue.enabled requires max_concurrent_requests: the queue \
                 waits for a cap permit, so an uncapped gateway has nothing to queue \
                 for (set a cap, or omit the block)",
            ));
        }
        if aq.max_queue_size == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "admission_queue.max_queue_size",
                "admission_queue.max_queue_size must be > 0 (range 1..=10000)",
            ));
        }
        if aq.max_queue_size > 10000 {
            issues.push(issue(
                "gateway",
                "(root)",
                "admission_queue.max_queue_size",
                format!(
                    "admission_queue.max_queue_size {} is out of range: must be \
                     1..=10000",
                    aq.max_queue_size
                ),
            ));
        }
        if aq.queue_timeout_ms == 0 {
            issues.push(issue(
                "gateway",
                "(root)",
                "admission_queue.queue_timeout_ms",
                "admission_queue.queue_timeout_ms must be > 0 (range 1..=10000)",
            ));
        }
        if aq.queue_timeout_ms > 10000 {
            issues.push(issue(
                "gateway",
                "(root)",
                "admission_queue.queue_timeout_ms",
                format!(
                    "admission_queue.queue_timeout_ms {} is out of range: must be \
                     1..=10000",
                    aq.queue_timeout_ms
                ),
            ));
        }
    }

    // HMAC signing policy bounds (DW-036): a zero-second window rejects
    // every signed request with any clock drift at all, and an unbounded
    // one pins nonce-cache memory for the process lifetime (nonces are
    // remembered for twice the window).
    if let Some(hmac) = &gateway.hmac_auth {
        let skew = hmac.max_clock_skew_secs;
        if !(1..=3600).contains(&skew) {
            issues.push(issue(
                "gateway",
                "(root)",
                "hmac_auth.max_clock_skew_secs",
                format!(
                    "max_clock_skew_secs {skew} is out of range: must be 1..=3600 seconds \
                     (0 rejects every signer with any clock drift; a larger window pins \
                     replay-nonce memory for its whole duration)"
                ),
            ));
        }
    }

    // DW-044: alert/event webhook targets.
    validate_webhooks(gateway, &mut issues);
    // DW-121: the access-record stream.
    validate_analytics_stream(gateway, &mut issues);

    // DW-043: the embedded analytics store block.
    validate_analytics(gateway, &mut issues);

    // DW-050: geo rules need a database; countries must be alpha-2.
    validate_geoip(gateway, &mut issues);

    // DW-033: consumer request budgets.
    validate_quotas(gateway, &mut issues);

    // DW-032: enterprise license block (grace-period bounds; the
    // signature/expiry check is NOT validation — it runs at startup in
    // dwara-bin, where a missing/invalid file can exit 1).
    validate_license(gateway, &mut issues);

    // DW-031: Redis rate limiter config (URL non-empty, timeout/TTL
    // bounds; the license claim check is NOT validation — it runs at
    // startup in dwara-bin, where a missing claim logs a warning and
    // falls back to the local limiter).
    validate_redis_rate_limiter(gateway, &mut issues);

    // DW-155: Redis quotas config (URL non-empty, timeout bounds; the
    // license claim check is NOT validation — it runs at startup in
    // dwara-bin, where a missing claim logs a warning and falls back to
    // the local SQLite checker).
    validate_redis_quotas(gateway, &mut issues);

    // SCALE-04 (#183): Redis response cache config (URL non-empty,
    // timeout bounds, key prefix non-empty; the license claim check is
    // NOT validation — it runs at startup in dwara-bin, where a missing
    // claim logs a warning and falls back to the local moka cache).
    validate_redis_cache(gateway, &mut issues);

    // DW-054: config convergence (backend type, redis_url presence,
    // interval bounds; the license claim check is NOT validation — it
    // runs at startup in dwara-bin, where a missing claim logs a
    // warning and falls back to local-only mode).
    validate_config_convergence(gateway, &mut issues);
    validate_fleet(gateway, &mut issues);

    // DW-107: service mesh mode (sidecar + SPIFFE/SPIRE mTLS
    // identity). Feature-gate warning (inert without `mesh`), ent-gate
    // warning (enterprise feature), SPIFFE field checks, and sidecar
    // port/redirect-mode checks.
    validate_mesh(gateway, &mut issues);

    // DW-034: OIDC providers (issuer URL shape, introspection cache TTL
    // bounds, consumer references, trusted_ca_file readability).
    validate_oidc_providers(gateway, &mut issues);

    // DW-075: the AI provider-adapter block (provider upstream refs,
    // auth resolvability, model alias refs).
    validate_ai(gateway, &mut issues);

    // DW-111: FIPS 140-3 mode primitive restrictions. When FIPS mode is
    // active (Enterprise `ent` build + license claim), reject
    // non-approved primitives at config
    // validation: Ed25519 certificates (not on the FIPS-validated list
    // for aws-lc-rs) and Argon2 credential hashing (not FIPS-approved).
    // When FIPS mode is not active, the check is inert (no issues
    // produced).
    validate_fips(gateway, &mut issues);

    // DW-105: post-quantum TLS validation. PQ hybrid key exchange is
    // compiled into every build (the feature-off warning is vestigial
    // and never fires). When `pq: true` and FIPS mode is active,
    // reject (ML-KEM is not on the FIPS-validated list). When `pq: true`
    // is on a passthrough listener or an http1 upstream, reject (no TLS
    // is terminated/negotiated).
    validate_pq(gateway, &mut issues);

    // Zero-route guard (#129, maintainer decision): a route-less config is
    // schema-valid, and a truncated/torn write (truncate-then-save) lands
    // exactly here — publishing it would drop all routing mid-run. Rejected
    // unless the operator explicitly opted in for a deliberate admin-only
    // shape. Applies to cold start and hot reload alike (compile runs both).
    if gateway.routes.is_empty() && !gateway.allow_empty_routes {
        issues.push(issue(
            "gateway",
            "(root)",
            "routes",
            "routes is empty: publishing an empty route set drops all routing \
             (every request would 404), and a truncated or torn config write \
             is schema-valid here — set allow_empty_routes: true if this \
             route-less shape is deliberate",
        ));
    }

    // DW-078: AI token budgets on policies — set fields must be positive,
    // and at least one window must be configured (a budget block that
    // bounds nothing is an authoring error).
    for p in &gateway.policies {
        if let Some(tb) = &p.token_budget {
            if tb.tokens_per_min.is_none() && tb.cost_per_day_micros.is_none() {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "token_budget",
                    "a token_budget must set tokens_per_min and/or cost_per_day_micros \
                 (an empty budget bounds nothing)",
                ));
            }
            if tb.tokens_per_min == Some(0) {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "token_budget.tokens_per_min",
                    "tokens_per_min must be > 0 (omit the field for no token window)",
                ));
            }
            if tb.cost_per_day_micros == Some(0) {
                issues.push(issue(
                    "gateway",
                    &p.name,
                    "token_budget.cost_per_day_micros",
                    "cost_per_day_micros must be > 0 (omit the field for no cost window)",
                ));
            }
        }
    }

    // Duplicate names within each entity kind.
    let mut check_dups = |kind: &str, field: &str, names: Vec<&str>| {
        let mut seen = std::collections::BTreeSet::new();
        for name in names {
            if !seen.insert(name) {
                issues.push(issue(kind, name, field, "duplicate name"));
            }
        }
    };
    check_dups(
        "listener",
        "name",
        gateway.listeners.iter().map(|l| l.name.as_str()).collect(),
    );
    check_dups(
        "route",
        "name",
        gateway.routes.iter().map(|r| r.name.as_str()).collect(),
    );
    check_dups(
        "service",
        "name",
        gateway.services.iter().map(|s| s.name.as_str()).collect(),
    );
    check_dups(
        "upstream",
        "name",
        gateway.upstreams.iter().map(|u| u.name.as_str()).collect(),
    );
    check_dups(
        "consumer",
        "name",
        gateway.consumers.iter().map(|c| c.name.as_str()).collect(),
    );
    check_dups(
        "policy",
        "name",
        gateway.policies.iter().map(|p| p.name.as_str()).collect(),
    );
    check_dups(
        "jwt_provider",
        "name",
        gateway
            .jwt_providers
            .iter()
            .map(|p| p.name.as_str())
            .collect(),
    );

    // DW-055/DW-119: plugin definitions -- exactly one of wasm/native,
    // non-empty phases, duplicate names.
    validate_plugins(gateway, &mut issues);

    // SCALE-12 (#191): global filter-chain ordering and dry-run.
    if let Some(fc) = &gateway.filter_chain {
        validate_filter_chain(fc, "gateway", "filter_chain", &mut issues);
    }

    // SCALE-12 (#191): per-route filter-chain overrides.
    for route in &gateway.routes {
        if let Some(fc) = &route.filter_chain {
            validate_filter_chain(fc, "route", &route.name, &mut issues);
        }
    }

    // JWT providers (DW-019): url shape, algorithm allowlist, refresh
    // cadence, and consumer references are compile-time checked — a
    // gateway must not boot (or reload) into an unverifiable provider.
    for p in &gateway.jwt_providers {
        match p.jwks_url.parse::<hyper::Uri>() {
            Ok(uri) => {
                if !matches!(uri.scheme_str(), Some("http") | Some("https")) || uri.host().is_none()
                {
                    issues.push(issue(
                        "jwt_provider",
                        &p.name,
                        "jwks_url",
                        format!("'{}' must be an absolute http(s) URL", p.jwks_url),
                    ));
                }
            }
            Err(_) => issues.push(issue(
                "jwt_provider",
                &p.name,
                "jwks_url",
                format!("'{}' is not a valid URL", p.jwks_url),
            )),
        }
        if p.algorithms.is_empty() {
            issues.push(issue(
                "jwt_provider",
                &p.name,
                "algorithms",
                "at least one algorithm must be allowed",
            ));
        }
        for a in &p.algorithms {
            let upper = a.to_ascii_uppercase();
            if matches!(upper.as_str(), "HS256" | "HS384" | "HS512" | "NONE") {
                issues.push(issue(
                    "jwt_provider",
                    &p.name,
                    "algorithms",
                    format!(
                        "algorithm '{a}' is not allowed: only asymmetric verification \
                         (RS*/ES*/PS*/EdDSA) is supported"
                    ),
                ));
            } else if jsonwebtoken::Algorithm::from_str(&upper).is_err() {
                issues.push(issue(
                    "jwt_provider",
                    &p.name,
                    "algorithms",
                    format!("unknown algorithm '{a}'"),
                ));
            }
        }
        if p.refresh_secs == 0 {
            issues.push(issue(
                "jwt_provider",
                &p.name,
                "refresh_secs",
                "refresh_secs must be > 0",
            ));
        }
        // DW-046: the retired-key grace is a bounded safety window —
        // past a week it is no longer bridging a rotation, it is
        // keeping a retired key alive on purpose.
        if let Some(grace) = p.retired_key_grace_secs {
            if grace > 604_800 {
                issues.push(issue(
                    "jwt_provider",
                    &p.name,
                    "retired_key_grace_secs",
                    format!(
                        "retired_key_grace_secs {grace} exceeds the 604800 cap \
                         (7 days): a longer window would keep a retired issuer \
                         key verifying indefinitely"
                    ),
                ));
            }
        }
        if let Some(consumer) = &p.consumer {
            if !gateway.consumers.iter().any(|c| &c.name == consumer) {
                issues.push(issue(
                    "jwt_provider",
                    &p.name,
                    "consumer",
                    format!("references unknown consumer '{consumer}'"),
                ));
            }
        }
        // trusted_ca_file (#121): the JWKS fetcher's TLS trust override
        // for private-CA issuers. It only applies to an `https://`
        // jwks_url — no TLS is negotiated toward an `http://` endpoint,
        // so there is nothing to verify and the field is an authoring
        // mistake. When it does apply, the bundle must be on disk and
        // readable at compile time (see check_trusted_ca_file).
        if let Some(ca) = &p.trusted_ca_file {
            // An unparseable URL already produced its own jwks_url issue
            // above; piling a CA complaint on a broken URL is noise.
            if let Ok(uri) = p.jwks_url.parse::<hyper::Uri>() {
                if uri
                    .scheme_str()
                    .is_some_and(|s| s.eq_ignore_ascii_case("https"))
                {
                    check_trusted_ca_file(
                        "jwt_provider",
                        &p.name,
                        "trusted_ca_file",
                        ca,
                        &mut issues,
                    );
                } else {
                    issues.push(issue(
                        "jwt_provider",
                        &p.name,
                        "trusted_ca_file",
                        "trusted_ca_file only applies to an https jwks_url (no TLS is \
                         negotiated toward an http endpoint)",
                    ));
                }
            }
        }
    }

    // Admin block (DW-022): when configured, the bind must parse as a
    // socket address and the mTLS material must be present and non-empty.
    // A client CA is REQUIRED (mTLS-only, decision 6): an admin block
    // without one is rejected here rather than serving no-auth TLS.
    if let Some(admin) = &gateway.admin {
        if admin.bind.trim().is_empty() {
            issues.push(issue(
                "admin",
                "(root)",
                "bind",
                "admin bind is empty (default 127.0.0.1:2019)",
            ));
        } else if admin.bind.parse::<std::net::SocketAddr>().is_err() {
            issues.push(issue(
                "admin",
                "(root)",
                "bind",
                format!(
                    "admin bind '{}' is not a valid address:port (e.g. 127.0.0.1:2019)",
                    admin.bind
                ),
            ));
        }
        let t = &admin.tls;
        for (field, value) in [
            ("tls.cert_file", &t.cert_file),
            ("tls.key_file", &t.key_file),
            ("tls.client_ca_file", &t.client_ca_file),
        ] {
            if value.trim().is_empty() {
                issues.push(issue(
                    "admin",
                    "(root)",
                    field,
                    format!("{field} is required (mTLS-only admin: server cert, key, and client CA must all be set)"),
                ));
            }
        }
    }

    // Listener sanity and bind conflicts.
    let mut binds = std::collections::BTreeSet::new();
    for l in &gateway.listeners {
        if l.port == 0 {
            issues.push(issue(
                "listener",
                &l.name,
                "port",
                "port 0 is not a valid gateway listen port (only meaningful as an ephemeral test bind)",
            ));
        }
        if l.address.trim().is_empty() {
            issues.push(issue("listener", &l.name, "address", "address is empty"));
        }
        match l.protocol {
            ListenerProtocol::Https => {
                match &l.tls {
                    None => issues.push(issue(
                        "listener",
                        &l.name,
                        "tls",
                        "protocol https requires a tls block",
                    )),
                    Some(t) => match t.mode {
                        TlsMode::Terminate => {
                            let has_pair = t.cert_file.is_some() || t.key_file.is_some();
                            if t.certificates.is_empty() || has_pair {
                                if t.cert_file.as_deref().unwrap_or("").trim().is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        "tls.cert_file",
                                        "tls mode terminate requires a non-empty cert_file",
                                    ));
                                }
                                if t.key_file.as_deref().unwrap_or("").trim().is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        "tls.key_file",
                                        "tls mode terminate requires a non-empty key_file",
                                    ));
                                }
                            }
                            if !t.sni_routes.is_empty() {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.sni_routes",
                                    "sni_routes only apply to tls mode passthrough",
                                ));
                            }
                            // #124: a client-CA bundle turns the terminate
                            // listener into one that verifies client
                            // certificates (optional at the TLS layer, matched
                            // against mtls credentials at authn). The same
                            // compile-time PEM check as trusted_ca_file: a
                            // broken bundle would otherwise surface as a
                            // listener-build failure at startup.
                            if let Some(ca) = &t.client_ca_file {
                                check_trusted_ca_file(
                                    "listener",
                                    &l.name,
                                    "tls.client_ca_file",
                                    ca,
                                    &mut issues,
                                );
                            }
                            let mut seen_names = std::collections::BTreeSet::new();
                            for (i, c) in t.certificates.iter().enumerate() {
                                if c.server_names.is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        &format!("tls.certificates[{i}].server_names"),
                                        "certificate entry lists no server_names",
                                    ));
                                }
                                for n in &c.server_names {
                                    if n.trim().is_empty() {
                                        issues.push(issue(
                                            "listener",
                                            &l.name,
                                            &format!("tls.certificates[{i}].server_names"),
                                            "server name is empty",
                                        ));
                                    } else if !seen_names.insert(n.to_ascii_lowercase()) {
                                        issues.push(issue(
                                            "listener",
                                            &l.name,
                                            &format!("tls.certificates[{i}].server_names"),
                                            format!("duplicate server name '{n}'"),
                                        ));
                                    }
                                }
                                if c.cert_file.trim().is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        &format!("tls.certificates[{i}].cert_file"),
                                        "certificate entry requires a non-empty cert_file",
                                    ));
                                }
                                if c.key_file.trim().is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        &format!("tls.certificates[{i}].key_file"),
                                        "certificate entry requires a non-empty key_file",
                                    ));
                                }
                            }
                            // SEC-02: ACME validation. Terminate mode
                            // only (passthrough does not terminate TLS).
                            if let Some(acme) = &t.acme {
                                if acme.domains.is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        "tls.acme.domains",
                                        "acme domains list must not be empty",
                                    ));
                                }
                                if !acme.staging && acme.contact.is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        "tls.acme.contact",
                                        "acme contact email is required for production issuance \
                                         (Let's Encrypt requires at least one contact email)",
                                    ));
                                }
                            }
                        }
                        TlsMode::Passthrough => {
                            if t.cert_file.is_some() || t.key_file.is_some() {
                                issues.push(issue(
                                "listener",
                                &l.name,
                                "tls",
                                "tls mode passthrough ignores cert_file/key_file; remove them or use mode terminate",
                            ));
                            }
                            // DW-030: PROXY acceptance needs the HTTP pipeline
                            // that consumes the client address (ACL, rate
                            // keys, XFF); a passthrough listener splices raw
                            // bytes and would silently ignore the knob.
                            if l.proxy_protocol {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "proxy_protocol",
                                    "proxy_protocol cannot be combined with tls mode passthrough: \
                                 passthrough splices raw bytes and never runs the pipeline that \
                                 consumes the PROXY client address (use protocol http, or https \
                                 with mode terminate)",
                                ));
                            }
                            if !t.certificates.is_empty() {
                                issues.push(issue(
                                "listener",
                                &l.name,
                                "tls.certificates",
                                "tls mode passthrough does not terminate TLS; certificates do not apply",
                            ));
                            }
                            if t.client_ca_file.is_some() {
                                issues.push(issue(
                                "listener",
                                &l.name,
                                "tls.client_ca_file",
                                "tls mode passthrough does not terminate TLS; client certificates \
                                 cannot be verified (use mode terminate)",
                            ));
                            }
                            if t.acme.is_some() {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.acme",
                                    "tls mode passthrough does not terminate TLS; acme certificate \
                                     automation does not apply (use mode terminate)",
                                ));
                            }
                            let mut seen_names = std::collections::BTreeSet::new();
                            for (i, r) in t.sni_routes.iter().enumerate() {
                                if r.server_names.is_empty() {
                                    issues.push(issue(
                                        "listener",
                                        &l.name,
                                        &format!("tls.sni_routes[{i}].server_names"),
                                        "sni route lists no server_names",
                                    ));
                                }
                                for n in &r.server_names {
                                    if n.trim().is_empty() {
                                        issues.push(issue(
                                            "listener",
                                            &l.name,
                                            &format!("tls.sni_routes[{i}].server_names"),
                                            "server name is empty",
                                        ));
                                    } else if !seen_names.insert(n.to_ascii_lowercase()) {
                                        issues.push(issue(
                                            "listener",
                                            &l.name,
                                            &format!("tls.sni_routes[{i}].server_names"),
                                            format!("duplicate server name '{n}'"),
                                        ));
                                    }
                                }
                            }
                        }
                    },
                } // close match &l.tls
                  // DW-088: zero_rtt is an H3-only policy; on H1/H2
                  // listeners it has no effect (TLS 1.3 early data over
                  // TCP is not exposed here). Reject it to avoid silent
                  // misconfiguration.
                if let Some(t) = &l.tls {
                    if t.zero_rtt != ZeroRttPolicy::Reject {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "tls.zero_rtt",
                            "zero_rtt only applies to protocol h3 listeners (TLS 1.3 early data over QUIC); remove it or use protocol h3",
                        ));
                    }
                }
                // DW-088: alt_svc on https listeners advertises the H3
                // port. Validate non-empty (same as http).
                if let Some(alt_svc) = &l.alt_svc {
                    if alt_svc.trim().is_empty() {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "alt_svc",
                            "alt_svc is set but empty; provide a valid alt-svc value or remove the field",
                        ));
                    }
                }
            }
            ListenerProtocol::Http => {
                if l.tls.is_some() {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "tls",
                        "protocol http must not carry a tls block (use protocol https for TLS)",
                    ));
                }
                // DW-088: alt_svc is meaningful on H1/H2 listeners (they
                // advertise the H3 port to clients). An H3 listener
                // advertising itself is a no-op.
                if let Some(alt_svc) = &l.alt_svc {
                    if alt_svc.trim().is_empty() {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "alt_svc",
                            "alt_svc is set but empty; provide a valid alt-svc value or remove the field",
                        ));
                    }
                }
            }
            ListenerProtocol::H3 => {
                // DW-088: HTTP/3 (QUIC) ingress. The QUIC stack is
                // always linked in the OSS default build.
                match &l.tls {
                    None => issues.push(issue(
                        "listener",
                        &l.name,
                        "tls",
                        "protocol h3 requires a tls block with cert_file and key_file (QUIC uses TLS 1.3)",
                    )),
                    Some(t) => {
                        if t.mode == TlsMode::Passthrough {
                            issues.push(issue(
                                "listener",
                                &l.name,
                                "tls.mode",
                                "protocol h3 does not support tls mode passthrough (QUIC terminates TLS in the handshake)",
                            ));
                        } else {
                            // Terminate mode: require cert/key (same as
                            // https terminate, but H3 has no SNI routes).
                            if t.cert_file.as_deref().unwrap_or("").trim().is_empty()
                                && t.certificates.is_empty()
                            {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.cert_file",
                                    "protocol h3 requires a non-empty cert_file or certificates (QUIC handshake needs a server certificate)",
                                ));
                            }
                            if t.key_file.as_deref().unwrap_or("").trim().is_empty()
                                && t.certificates.is_empty()
                            {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.key_file",
                                    "protocol h3 requires a non-empty key_file or certificates (QUIC handshake needs a private key)",
                                ));
                            }
                            if !t.sni_routes.is_empty() {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.sni_routes",
                                    "sni_routes only apply to tls mode passthrough (H3 uses SNI for cert selection, not routing)",
                                ));
                            }
                        }
                        // zero_rtt is only meaningful on H3 listeners.
                        // On H1/H2 listeners it is rejected below.
                    }
                }
                // H3 listeners must not advertise alt_svc (they ARE the
                // alt-svc target; advertising themselves is a no-op).
                if l.alt_svc.is_some() {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "alt_svc",
                        "alt_svc must not be set on an h3 listener (the h3 listener is the alt-svc target, not the advertiser)",
                    ));
                }
                // PROXY protocol on H3 is not supported (QUIC has no
                // pre-handshake byte stream to read a PROXY header from).
                if l.proxy_protocol {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "proxy_protocol",
                        "proxy_protocol is not supported on h3 listeners (QUIC has no pre-handshake byte stream)",
                    ));
                }
            }
            ListenerProtocol::Tcp | ListenerProtocol::Udp => {
                // DW-103: L4 TCP/UDP proxying. The L4 dispatcher is
                // always linked in the OSS default build.
                // The `l4` block is required on tcp/udp listeners.
                let l4_cfg = match &l.l4 {
                    None => {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "l4",
                            format!(
                                "protocol {} requires an l4 block (upstream + optional \
                                 sni_routing + idle_timeout_s)",
                                if l.protocol == ListenerProtocol::Tcp {
                                    "tcp"
                                } else {
                                    "udp"
                                }
                            ),
                        ));
                        continue;
                    }
                    Some(cfg) => cfg,
                };
                // sni_routing is TCP-only (UDP has no byte-stream
                // handshake to peek).
                if l4_cfg.sni_routing && l.protocol == ListenerProtocol::Udp {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "l4.sni_routing",
                        "sni_routing is not supported on udp listeners (UDP has no \
                         byte-stream handshake to peek; use protocol tcp for SNI-routed \
                         L4 proxying)",
                    ));
                }
                // idle_timeout_s bounds check (at most 1 hour).
                if let Some(timeout) = l4_cfg.idle_timeout_s {
                    if timeout > 3600 {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "l4.idle_timeout_s",
                            "idle_timeout_s must be at most 3600 (1 hour)",
                        ));
                    }
                }
                // The upstream (when present) must reference a known
                // upstream. When sni_routing is true the upstream is
                // optional (the fallback for no-SNI/unmatched); when
                // false it is required.
                if !l4_cfg.sni_routing && l4_cfg.upstream.is_none() {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "l4.upstream",
                        "l4.upstream is required when sni_routing is false (every \
                         connection goes to the configured upstream)",
                    ));
                }
                // The upstreams set is built below this loop; defer the
                // upstream-exists check to the post-loop block (the
                // same pattern as sni_routes upstream checks).
                // SNI routing requires the listener to carry a tls
                // block with sni_routes (the same routing table
                // passthrough uses).
                if l4_cfg.sni_routing {
                    match &l.tls {
                        None => {
                            issues.push(issue(
                                "listener",
                                &l.name,
                                "tls",
                                "l4.sni_routing requires a tls block with sni_routes \
                                 (the SNI routing table, same as tls passthrough)",
                            ));
                        }
                        Some(t) => {
                            if t.sni_routes.is_empty() {
                                issues.push(issue(
                                    "listener",
                                    &l.name,
                                    "tls.sni_routes",
                                    "l4.sni_routing requires at least one tls.sni_routes \
                                     entry (the SNI routing table is empty)",
                                ));
                            }
                        }
                    }
                } else if l.tls.is_some() {
                    // A tls block without sni_routing is only meaningful
                    // for sni_routes; warn (not reject -- the tls block
                    // is additive and could carry future L4-relevant
                    // config).
                    if l.tls
                        .as_ref()
                        .map(|t| t.sni_routes.is_empty())
                        .unwrap_or(true)
                    {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "tls",
                            "tls block on an l4 listener without sni_routing has no \
                             effect (remove it or set l4.sni_routing: true)",
                        ));
                    }
                }
                // alt_svc / zero_rtt are HTTP-transport concepts;
                // reject them on L4 listeners.
                if l.alt_svc.is_some() {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "alt_svc",
                        "alt_svc must not be set on an l4 listener (L4 proxying has no \
                         HTTP response to advertise on)",
                    ));
                }
                if let Some(t) = &l.tls {
                    if t.zero_rtt != ZeroRttPolicy::Reject {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "tls.zero_rtt",
                            "zero_rtt only applies to protocol h3 listeners (TLS 1.3 \
                             early data over QUIC); remove it",
                        ));
                    }
                }
            }
        }
        if !binds.insert((l.address.as_str(), l.port)) {
            issues.push(issue(
                "listener",
                &l.name,
                "port",
                format!(
                    "address {}:{} already bound by another listener",
                    l.address, l.port
                ),
            ));
        }
    }

    let services: std::collections::BTreeSet<&str> =
        gateway.services.iter().map(|s| s.name.as_str()).collect();
    let upstreams: std::collections::BTreeSet<&str> =
        gateway.upstreams.iter().map(|u| u.name.as_str()).collect();
    let policies: std::collections::BTreeSet<&str> =
        gateway.policies.iter().map(|p| p.name.as_str()).collect();
    let consumers: std::collections::BTreeSet<&str> =
        gateway.consumers.iter().map(|c| c.name.as_str()).collect();
    let consumer_groups: std::collections::BTreeSet<&str> = gateway
        .consumers
        .iter()
        .flat_map(|c| c.groups.iter().map(String::as_str))
        .collect();
    // DW-055/DW-119: plugin names for route reference validation.
    let plugin_names: std::collections::BTreeSet<&str> =
        gateway.plugins.iter().map(|p| p.name.as_str()).collect();

    for l in &gateway.listeners {
        // Listener policy attachment (#123): same resolution rule as
        // route/service/consumer refs. Runs for EVERY listener (the
        // tls-scoped checks below skip tls-less listeners early).
        for p in &l.policies {
            if !policies.contains(p.as_str()) {
                issues.push(issue(
                    "listener",
                    &l.name,
                    "policies",
                    format!("references unknown policy '{p}'"),
                ));
            }
        }
        // Listener authorization (#123): shared shape checks with every
        // other attachment level.
        if let Some(authz) = &l.authorization {
            validate_authz(
                "listener",
                &l.name,
                authz,
                &consumers,
                &consumer_groups,
                &mut issues,
            );
        }
        let Some(tls) = &l.tls else { continue };
        for (i, r) in tls.sni_routes.iter().enumerate() {
            if !upstreams.contains(r.upstream.as_str()) {
                issues.push(issue(
                    "listener",
                    &l.name,
                    &format!("tls.sni_routes[{i}].upstream"),
                    format!("references unknown upstream '{}'", r.upstream),
                ));
            }
        }
    }

    // DW-103: L4 listener upstream reference checks (deferred to here
    // because the `upstreams` set is built after the listener loop).
    for l in &gateway.listeners {
        if !matches!(l.protocol, ListenerProtocol::Tcp | ListenerProtocol::Udp) {
            continue;
        }
        let Some(l4_cfg) = &l.l4 else { continue };
        // The l4.upstream (when present) must reference a known upstream.
        if let Some(name) = &l4_cfg.upstream {
            if !upstreams.contains(name.as_str()) {
                issues.push(issue(
                    "listener",
                    &l.name,
                    "l4.upstream",
                    format!("references unknown upstream '{name}'"),
                ));
            }
        }
        // SNI routing: each tls.sni_routes[].upstream must reference a
        // known upstream (already checked above for ALL listeners with
        // tls.sni_routes, so no duplicate check here). Additionally,
        // SNI routing requires the referenced upstreams to have TLS
        // endpoints (the SNI is a TLS ClientHello field; the upstream
        // must terminate or pass through TLS). Check that the upstream
        // protocol is a TLS-bearing one (https, http2, h3).
        if l4_cfg.sni_routing {
            if let Some(tls) = &l.tls {
                for r in &tls.sni_routes {
                    if let Some(upstream) = gateway.upstreams.iter().find(|u| u.name == r.upstream)
                    {
                        if !matches!(
                            upstream.protocol,
                            crate::config::UpstreamProtocol::Https
                                | crate::config::UpstreamProtocol::Http2
                                | crate::config::UpstreamProtocol::H3
                        ) {
                            issues.push(issue(
                                "listener",
                                &l.name,
                                "tls.sni_routes.upstream",
                                format!(
                                    "sni_routing upstream '{}' must use a TLS protocol \
                                     (https, http2, or h3); '{}' cannot receive a \
                                     TLS-routed L4 splice",
                                    r.upstream,
                                    upstream_protocol_name(upstream.protocol)
                                ),
                            ));
                        }
                    }
                }
            }
        }
    }

    // Gateway-level (global) policy attachment (#123): named
    // `global_policies` because `policies` at this level is the registry.
    for p in &gateway.global_policies {
        if !policies.contains(p.as_str()) {
            issues.push(issue(
                "gateway",
                "(root)",
                "global_policies",
                format!("references unknown policy '{p}'"),
            ));
        }
    }
    // Gateway-level (global) authorization (#123).
    if let Some(authz) = &gateway.authorization {
        validate_authz(
            "gateway",
            "(root)",
            authz,
            &consumers,
            &consumer_groups,
            &mut issues,
        );
    }

    for s in &gateway.services {
        // DW-040: a service dispatches through exactly one of
        // `upstream` (single target) or `split` (weighted targets) —
        // both set is ambiguous routing, neither is a service that
        // can serve nothing.
        match (&s.upstream, &s.split) {
            (Some(_), Some(_)) => issues.push(issue(
                "service",
                &s.name,
                "upstream",
                "upstream and split are both set: a service dispatches through exactly one \
                 (upstream = single target; split = weighted canary/blue-green)",
            )),
            (None, None) => issues.push(issue(
                "service",
                &s.name,
                "upstream",
                "neither upstream nor split is set: set upstream (single target) or split \
                 (weighted targets)",
            )),
            _ => {}
        }
        if let Some(upstream) = &s.upstream {
            if !upstreams.contains(upstream.as_str()) {
                issues.push(issue(
                    "service",
                    &s.name,
                    "upstream",
                    format!("references unknown upstream '{upstream}'"),
                ));
            }
        }
        // DW-040 split validation: existing upstreams, sane bounds, no
        // duplicates, and a positive total (individual zeros are the
        // parked side of a blue-green pair; an all-zero split routes
        // nowhere).
        if let Some(split) = &s.split {
            if split.targets.len() < 2 || split.targets.len() > 8 {
                issues.push(issue(
                    "service",
                    &s.name,
                    "split.targets",
                    format!(
                        "a split needs 2..=8 targets ({} given): one target is what \
                         services[].upstream expresses",
                        split.targets.len()
                    ),
                ));
            }
            let mut seen = std::collections::BTreeSet::new();
            let mut total: u64 = 0;
            for (i, t) in split.targets.iter().enumerate() {
                if !upstreams.contains(t.upstream.as_str()) {
                    issues.push(issue(
                        "service",
                        &s.name,
                        &format!("split.targets[{i}].upstream"),
                        format!("references unknown upstream '{}'", t.upstream),
                    ));
                }
                if !seen.insert(t.upstream.clone()) {
                    issues.push(issue(
                        "service",
                        &s.name,
                        &format!("split.targets[{i}].upstream"),
                        format!(
                            "duplicate upstream '{}' in the split (weights merge by intent; \
                             name it once)",
                            t.upstream
                        ),
                    ));
                }
                total += u64::from(t.weight);
            }
            if total == 0 {
                issues.push(issue(
                    "service",
                    &s.name,
                    "split.targets",
                    "every weight is 0: a split must serve some traffic (a parked \
                     blue-green side is weight 0, the other side is not)",
                ));
            }
            if total > 100_000 {
                issues.push(issue(
                    "service",
                    &s.name,
                    "split.targets",
                    format!("weights sum to {total}; keep the total at or under 100000"),
                ));
            }
            // DW-091: canary_analysis validation. Only valid on a
            // 2-target split (baseline + canary); the controller
            // compares exactly two sides. Bounds: window >= 1s,
            // step >= 1, min_requests >= 1, cooldown >= 1s, and
            // thresholds in [0.0, 1.0] for error_rate or > 0 for
            // latency.
            if let Some(analysis) = &split.canary_analysis {
                if split.targets.len() != 2 {
                    issues.push(issue(
                        "service",
                        &s.name,
                        "split.canary_analysis",
                        "canary_analysis requires exactly 2 targets (baseline + canary): \
                         the controller compares two sides",
                    ));
                }
                if analysis.window_seconds == 0 {
                    issues.push(issue(
                        "service",
                        &s.name,
                        "split.canary_analysis.window_seconds",
                        "window_seconds must be >= 1",
                    ));
                }
                if analysis.step == 0 {
                    issues.push(issue(
                        "service",
                        &s.name,
                        "split.canary_analysis.step",
                        "step must be >= 1 (a 0-step never adjusts)",
                    ));
                }
                if analysis.min_requests == 0 {
                    issues.push(issue(
                        "service",
                        &s.name,
                        "split.canary_analysis.min_requests",
                        "min_requests must be >= 1",
                    ));
                }
                if analysis.cooldown_seconds == 0 {
                    issues.push(issue(
                        "service",
                        &s.name,
                        "split.canary_analysis.cooldown_seconds",
                        "cooldown_seconds must be >= 1",
                    ));
                }
                validate_canary_rule(
                    &s.name,
                    "split.canary_analysis.promote",
                    &analysis.promote,
                    &mut issues,
                );
                validate_canary_rule(
                    &s.name,
                    "split.canary_analysis.rollback",
                    &analysis.rollback,
                    &mut issues,
                );
            }
        }
        // DW-040 sticky validation: a usable cookie-name token and a
        // bounded lifetime.
        if let Some(sticky) = &s.sticky {
            if !is_cookie_name(&sticky.cookie) {
                issues.push(issue(
                    "service",
                    &s.name,
                    "sticky.cookie",
                    format!(
                        "'{}' is not a valid cookie name (RFC 6265 token: no \
                         separators, spaces, or non-token characters)",
                        sticky.cookie
                    ),
                ));
            }
            if sticky.ttl_s == 0 || sticky.ttl_s > 2_592_000 {
                issues.push(issue(
                    "service",
                    &s.name,
                    "sticky.ttl_s",
                    "ttl_s must be in 1..=2592000 (30 days)",
                ));
            }
        }
        for p in &s.policies {
            if !policies.contains(p.as_str()) {
                issues.push(issue(
                    "service",
                    &s.name,
                    "policies",
                    format!("references unknown policy '{p}'"),
                ));
            }
        }
        // Service authorization (#123): shared shape checks with every
        // other attachment level.
        if let Some(authz) = &s.authorization {
            validate_authz(
                "service",
                &s.name,
                authz,
                &consumers,
                &consumer_groups,
                &mut issues,
            );
        }
    }

    for r in &gateway.routes {
        if let Some(p) = r.priority {
            if p > 10 {
                issues.push(issue(
                    "route",
                    &r.name,
                    "priority",
                    format!("priority {p} is out of range: must be 0 (lowest) to 10 (highest)"),
                ));
            }
        }
        if !services.contains(r.service.as_str()) {
            issues.push(issue(
                "route",
                &r.name,
                "service",
                format!("references unknown service '{}'", r.service),
            ));
        }
        for p in &r.policies {
            if !policies.contains(p.as_str()) {
                issues.push(issue(
                    "route",
                    &r.name,
                    "policies",
                    format!("references unknown policy '{p}'"),
                ));
            }
        }
        // DW-055/DW-119: route plugin references must name a plugin
        // defined in the top-level `plugins` list, and each name at
        // most once (DW-157: the request-path chain executes every
        // reference, so a duplicate would run the plugin twice).
        let mut route_plugins = std::collections::BTreeSet::new();
        for p in &r.plugins {
            if !route_plugins.insert(p.as_str()) {
                issues.push(issue(
                    "route",
                    &r.name,
                    "plugins",
                    format!("references plugin '{p}' more than once"),
                ));
            }
            if !plugin_names.contains(p.as_str()) {
                issues.push(issue(
                    "route",
                    &r.name,
                    "plugins",
                    format!("references unknown plugin '{p}'"),
                ));
            }
        }
        // Route authorization (DW-020): shared shape checks with every
        // other attachment level (see validate_authz).
        if let Some(authz) = &r.authorization {
            validate_authz(
                "route",
                &r.name,
                authz,
                &consumers,
                &consumer_groups,
                &mut issues,
            );
        }
        // Route-scoped edge policies (DW-027): CORS, response
        // compression, request limits.
        if let Some(cors) = &r.cors {
            validate_cors(&r.name, cors, &mut issues);
        }
        if let Some(compression) = &r.compression {
            validate_compression(&r.name, compression, &mut issues);
        }
        if let Some(limits) = &r.limits {
            validate_request_limits(&r.name, limits, &mut issues);
        }
        if let Some(dep) = &r.deprecation {
            validate_deprecation(&r.name, dep, &mut issues);
        }
        if let Some(maintenance) = &r.maintenance {
            validate_maintenance(&r.name, maintenance, &mut issues);
        }
        // Route-scoped transforms + security headers (DW-028).
        if let Some(transforms) = &r.transforms {
            validate_transforms(&r.name, transforms, &mut issues);
        }
        if let Some(sh) = &r.security_headers {
            validate_security_headers(&r.name, sh, &mut issues);
        }
        // Response field masking (DW-029).
        if let Some(masking) = &r.masking {
            validate_masking(&r.name, masking, &consumer_groups, &mut issues);
        }
        // Response caching (DW-037).
        if let Some(cache) = &r.cache {
            validate_route_cache(&r.name, cache, &mut issues);
        }
        // Per-route method allowlist (DW-030): every entry must be a
        // valid HTTP method token (the same grammar cors.allowed_methods
        // checks) and the list must not repeat an entry case-insensitively
        // — a duplicate would only ever be an authoring artifact, and the
        // 405's Allow header echoes the list verbatim.
        {
            let mut seen_methods = std::collections::BTreeSet::new();
            for (i, m) in r.methods.iter().enumerate() {
                if m.trim().is_empty() {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("methods[{i}]"),
                        "method is empty or only whitespace",
                    ));
                } else if hyper::Method::from_bytes(m.as_bytes()).is_err() {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("methods[{i}]"),
                        format!("'{m}' is not a valid HTTP method token"),
                    ));
                } else if !seen_methods.insert(m.to_ascii_lowercase()) {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("methods[{i}]"),
                        format!("duplicate method '{m}' (matching is case-insensitive)"),
                    ));
                }
            }
        }
        // Per-route SLO objectives (DW-052): targets must be achievable
        // percentages, a latency target without a threshold can never
        // evaluate, and a threshold without a target would silently use
        // the default (it does — the error is only for the impossible
        // combination).
        if let Some(slo) = &r.slo {
            if !(0.0..=100.0).contains(&slo.availability) || slo.availability <= 0.0 {
                issues.push(issue(
                    "route",
                    &r.name,
                    "slo.availability",
                    format!(
                        "availability {} is out of range: a percentage in (0, 100] \
                         (100 = every request must be non-5xx)",
                        slo.availability
                    ),
                ));
            }
            if let Some(ms) = slo.latency_ms {
                if !(1.0..=600_000.0).contains(&ms) {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "slo.latency_ms",
                        format!(
                            "latency_ms {ms} is out of range: 1..=600000 (the \
                             whole-request budget; nothing sensible is faster \
                             than 1 ms or slower than the 10-minute class of \
                             timeouts)"
                        ),
                    ));
                }
            }
            if let Some(t) = slo.latency_target {
                if !(0.0..=100.0).contains(&t) || t <= 0.0 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "slo.latency_target",
                        format!(
                            "latency_target {t} is out of range: a percentage in \
                             (0, 100]"
                        ),
                    ));
                }
            }
            if slo.latency_target.is_some() && slo.latency_ms.is_none() {
                issues.push(issue(
                    "route",
                    &r.name,
                    "slo.latency_target",
                    "latency_target without latency_ms: the objective has no \
                     threshold to measure against",
                ));
            }
        }
        // Media-type criterion (DW-048): the shared grammar in
        // config::versioning is the whole check — a value that is not a
        // bare type/subtype can never match and is an authoring error.
        if let Some(accept) = &r.r#match.accept {
            if crate::config::versioning::normalize_media_type(accept).is_none() {
                issues.push(issue(
                    "route",
                    &r.name,
                    "match.accept",
                    format!(
                        "'{accept}' is not a bare media type: use type/subtype like \
                         'application/vnd.acme.v2+json' (parameters and wildcards are not \
                         supported; wildcards never match a versioned route)"
                    ),
                ));
            }
        }
        // WebSocket policy (DW-039): origins must be comparable header
        // values (the gate is an exact string match, so an entry that
        // could never appear in an Origin header is an authoring
        // error), and the frame allowance lives under the same ceiling
        // as every other rate-shaped knob.
        if let Some(ws) = &r.websocket {
            for (i, origin) in ws.origins.iter().enumerate() {
                if origin.is_empty() {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("websocket.origins[{i}]"),
                        "origin is empty: an allowlist entry must name an origin \
                         (e.g. https://app.example.com, or the literal null)",
                    ));
                } else if origin.len() > 256 || !origin.bytes().all(|b| (0x20..0x7f).contains(&b)) {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("websocket.origins[{i}]"),
                        "origin must be printable ASCII at most 256 bytes",
                    ));
                }
            }
            if let Some(rate) = ws.max_frames_per_sec {
                if rate == 0 || rate > crate::config::limits::MAX_WEBSOCKET_FRAMES_PER_SEC {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "websocket.max_frames_per_sec",
                        format!(
                            "max_frames_per_sec must be in 1..={} (sustained data \
                             frames per second, one-second burst)",
                            crate::config::limits::MAX_WEBSOCKET_FRAMES_PER_SEC
                        ),
                    ));
                }
            }
            // DP-05 (#253): idle timeout 1s..=86400s, frame size 1..=16MiB.
            if let Some(idle) = ws.idle_timeout_s {
                if idle == 0 || idle > 86400 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "websocket.idle_timeout_s",
                        "idle_timeout_s must be in 1..=86400 (seconds, 1s to 24h)",
                    ));
                }
            }
            if let Some(sz) = ws.max_frame_size_bytes {
                if sz == 0 || sz > 16_777_216 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "websocket.max_frame_size_bytes",
                        "max_frame_size_bytes must be in 1..=16777216 (1 byte to 16 MiB)",
                    ));
                }
            }
        }
        // WAF-lite (DW-051): when enabled, the filter list must be
        // either absent (defaults to all three) or a non-empty list of
        // known category names, the body inspection cap must be 0 or
        // within 1..=1048576, and every custom pattern must compile as
        // a valid regex (an invalid regex is an authoring error that
        // would panic at request time if it reached the runtime).
        if let Some(waf) = &r.waf {
            if waf.enabled {
                for (i, f) in waf.filters.iter().enumerate() {
                    if !matches!(f.as_str(), "sqli" | "xss" | "path_traversal") {
                        issues.push(issue(
                            "route",
                            &r.name,
                            &format!("waf.filters[{i}]"),
                            format!(
                                "unknown filter category '{f}': must be one of \
                                 sqli, xss, path_traversal (or omit the list for \
                                 all three)"
                            ),
                        ));
                    }
                }
            }
            if waf.max_body_inspect_bytes > 1_048_576 {
                issues.push(issue(
                    "route",
                    &r.name,
                    "waf.max_body_inspect_bytes",
                    format!(
                        "max_body_inspect_bytes {} is out of range: must be 0 \
                         (no body inspection) or 1..=1048576 (1 MiB)",
                        waf.max_body_inspect_bytes
                    ),
                ));
            }
            for (i, pat) in waf.custom_patterns.iter().enumerate() {
                if regex::Regex::new(pat).is_err() {
                    issues.push(issue(
                        "route",
                        &r.name,
                        &format!("waf.custom_patterns[{i}]"),
                        format!("invalid regex pattern: '{pat}'"),
                    ));
                }
            }
        }
        // GraphQL awareness (DW-099): when a route has a `graphql`
        // block, validate that depth_limit and complexity_limit are
        // > 0 (a 0 limit would reject every query or none, neither
        // is a useful configuration), and that persisted-query
        // hashes are non-empty strings. The block is compiled into
        // every build (no cargo feature), so
        // validation runs unconditionally -- the schema is always
        // present.
        if let Some(graphql) = &r.graphql {
            if graphql.enabled {
                if graphql.depth_limit == 0 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "graphql.depth_limit",
                        "depth_limit must be > 0 when graphql is enabled",
                    ));
                }
                if graphql.complexity_limit == 0 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "graphql.complexity_limit",
                        "complexity_limit must be > 0 when graphql is enabled",
                    ));
                }
                if graphql.complexity_coefficient == 0 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "graphql.complexity_coefficient",
                        "complexity_coefficient must be > 0 (use 1 for \
                         uniform cost; 0 would make every query free)",
                    ));
                }
            }
            if let Some(pq) = &graphql.persisted_queries {
                if pq.enabled {
                    for (hash, query) in &pq.store {
                        if hash.trim().is_empty() {
                            issues.push(issue(
                                "route",
                                &r.name,
                                "graphql.persisted_queries.store",
                                "persisted query hash must be a non-empty \
                                 string",
                            ));
                        }
                        if query.trim().is_empty() {
                            issues.push(issue(
                                "route",
                                &r.name,
                                "graphql.persisted_queries.store",
                                "persisted query text must be a non-empty \
                                 string",
                            ));
                        }
                    }
                }
            }
        }
        // gRPC-Web framing + JSON-to-gRPC transcoding (DW-101): when a
        // route has a `grpc_web` block with `enabled: true`, validate
        // the transcoding sub-block. When transcoding is enabled, at
        // least one descriptor must be present and every descriptor
        // file must exist and be readable at validation time (a missing
        // or unreadable descriptor would otherwise publish fine and
        // fail every transcoded request at runtime). The config schema
        // is always present (the block parses and validates in every
        // build; no cargo feature), so validation runs
        // unconditionally; descriptor files are checked only when the
        // block is enabled so a staged-but-inert config does not fail.
        if let Some(grpc_web) = &r.grpc_web {
            if grpc_web.enabled {
                if let Some(tc) = &grpc_web.transcoding {
                    if tc.enabled {
                        if tc.descriptors.is_empty() {
                            issues.push(issue(
                                "route",
                                &r.name,
                                "grpc_web.transcoding.descriptors",
                                "transcoding is enabled but no descriptors \
                                 are listed: at least one descriptor is \
                                 required",
                            ));
                        }
                        for (i, desc) in tc.descriptors.iter().enumerate() {
                            check_file_readable(
                                "route",
                                &r.name,
                                &format!("grpc_web.transcoding.descriptors[{i}].file"),
                                &desc.file,
                                &mut issues,
                            );
                        }
                    }
                }
            }
        }
        // Protocol translation (DW-100): when a route has a
        // `translation` block, validate that the referenced kind has
        // the required sub-block. A `rest_to_graphql` or
        // `graphql_to_rest` kind requires a `graphql` block with a
        // `query_template` (the reverse direction only unwraps the
        // response envelope, so the template is required only for
        // `rest_to_graphql`). A `rest_to_soap` or `soap_to_rest` kind
        // requires a `soap` block with an `operation` name, and
        // `rest_to_soap` additionally requires a `namespace`. The
        // config schema is always present (the block parses and
        // validates in every build; no cargo feature), so validation
        // runs unconditionally; the runtime translation is scaffolded
        // (not yet dispatched from the request path).
        if let Some(translation) = &r.translation {
            match translation.kind {
                TranslationKind::RestToGraphql => match &translation.graphql {
                    None => {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "translation.graphql",
                            "kind rest_to_graphql requires a graphql block",
                        ));
                    }
                    Some(graphql) => {
                        if graphql.query_template.trim().is_empty() {
                            issues.push(issue(
                                "route",
                                &r.name,
                                "translation.graphql.query_template",
                                "rest_to_graphql requires a query_template",
                            ));
                        }
                    }
                },
                TranslationKind::GraphqlToRest => {
                    if translation.graphql.is_none() {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "translation.graphql",
                            "kind graphql_to_rest requires a graphql block",
                        ));
                    }
                }
                TranslationKind::RestToSoap | TranslationKind::SoapToRest => {
                    match &translation.soap {
                        None => {
                            issues.push(issue(
                                "route",
                                &r.name,
                                "translation.soap",
                                "kind requires a soap block",
                            ));
                        }
                        Some(soap) => {
                            if soap.operation.trim().is_empty() {
                                issues.push(issue(
                                    "route",
                                    &r.name,
                                    "translation.soap.operation",
                                    "soap translation requires an operation name",
                                ));
                            }
                            if translation.kind == TranslationKind::RestToSoap
                                && soap.namespace.trim().is_empty()
                            {
                                issues.push(issue(
                                    "route",
                                    &r.name,
                                    "translation.soap.namespace",
                                    "rest_to_soap requires a namespace",
                                ));
                            }
                        }
                    }
                }
            }
        }
        let m = &r.r#match.path;
        for (field, entries) in [
            ("match.query", &r.r#match.query),
            ("match.cookies", &r.r#match.cookies),
        ] {
            for e in entries.iter() {
                if e.name.trim().is_empty() {
                    issues.push(issue("route", &r.name, field, "matcher name is empty"));
                }
                if let Some(v) = &e.value {
                    if v.is_empty() {
                        issues.push(issue(
                            "route",
                            &r.name,
                            field,
                            format!("matcher '{}' carries an empty value; omit value for presence-only matching", e.name),
                        ));
                    }
                }
            }
        }
        if !m.value.starts_with('/') {
            issues.push(issue(
                "route",
                &r.name,
                "match.path.value",
                format!("path pattern '{}' must start with '/'", m.value),
            ));
        }
        if m.kind == PathMatchKind::Prefix && m.value.trim_end_matches('/').is_empty() {
            issues.push(issue(
                "route",
                &r.name,
                "match.path.value",
                format!(
                    "prefix '{}' would match every path (it trims to the empty string); \
                     use a regex route or an explicit catch-all route instead",
                    m.value
                ),
            ));
        }
        match r.action {
            RouteAction::Redirect {
                status,
                ref scheme,
                ref host,
                path: ref redirect_path,
            } => {
                if !(300..=399).contains(&status) {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "action.status",
                        format!("redirect status {status} is not a 3xx redirect"),
                    ));
                }
                // Location is built into a HeaderValue at request time; a
                // hostile config must fail HERE, not panic the dataplane.
                if let Some(s) = scheme {
                    if !s.eq_ignore_ascii_case("http") && !s.eq_ignore_ascii_case("https") {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.scheme",
                            format!("redirect scheme '{s}' must be http or https"),
                        ));
                    }
                }
                if let Some(h) = host {
                    if h.is_empty() || !h.bytes().all(|b| (0x21..=0x7e).contains(&b)) {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.host",
                            format!(
                                "redirect host '{h}' contains whitespace or control \
                                 characters and cannot form a Location header"
                            ),
                        ));
                    }
                }
                if let Some(p) = redirect_path {
                    if !p.is_empty() && !p.starts_with('/') {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.path",
                            format!("redirect path '{p}' must start with '/' or be empty"),
                        ));
                    }
                    if !p.bytes().all(|b| (0x20..=0x7e).contains(&b)) {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.path",
                            format!(
                                "redirect path '{p}' contains control characters and \
                                 cannot form a Location header"
                            ),
                        ));
                    }
                }
            }
            RouteAction::Respond {
                status,
                ref headers,
                ..
            } => {
                if !(100..=599).contains(&status) {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "action.status",
                        format!("respond status {status} is not a valid HTTP status"),
                    ));
                }
                for (name, value) in headers {
                    if hyper::header::HeaderName::from_bytes(name.as_bytes()).is_err() {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.headers",
                            format!("respond header name '{name}' is not a valid HTTP header name"),
                        ));
                    }
                    if hyper::header::HeaderValue::from_str(value.as_str()).is_err() {
                        issues.push(issue(
                            "route",
                            &r.name,
                            "action.headers",
                            format!(
                                "respond header value for '{name}' contains characters that \
                                 cannot appear in an HTTP header value"
                            ),
                        ));
                    }
                }
            }
            RouteAction::Proxy { rewrite: None } => {}
            RouteAction::Proxy {
                rewrite: Some(ref rw),
            } => validate_rewrite(&r.name, rw, &mut issues),
            RouteAction::Mock { ref mock } => validate_mock(&r.name, mock, &mut issues),
            RouteAction::Ai { .. } => {
                // The action needs the gateway-level alias table; a
                // route declaring `ai` without one answers 500s for
                // every request and is an authoring error caught here.
                if gateway.ai.is_none() {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "action.type",
                        "an ai action requires a gateway-level ai block \
                         (ai.providers + ai.models define what it can serve)",
                    ));
                }
            }
            RouteAction::NanoService { ref nano } => {
                validate_nano_service(&r.name, nano, &mut issues);
            }
        }
        // Request validation (DW-047): the JSON schema must be
        // well-formed (known type names, non-negative bounds). An
        // invalid schema is an authoring error that would surface at
        // request time otherwise.
        if let Some(rv) = &r.request_validation {
            validate_json_schema(
                &r.name,
                "request_validation.body_schema",
                &rv.body_schema,
                &mut issues,
            );
        }
        // DW-062: mirror validation.
        if let Some(m) = &r.mirror {
            if m.percentage > 100 {
                issues.push(issue(
                    "route",
                    &r.name,
                    "mirror.percentage",
                    "percentage must be in [0, 100]",
                ));
            }
            if m.upstream.trim().is_empty() {
                issues.push(issue(
                    "route",
                    &r.name,
                    "mirror.upstream",
                    "mirror upstream name must not be empty",
                ));
            } else if !gateway.upstreams.iter().any(|u| u.name == m.upstream) {
                issues.push(issue(
                    "route",
                    &r.name,
                    "mirror.upstream",
                    format!("mirror upstream '{}' not found in upstreams", m.upstream),
                ));
            }
        }
        // DW-062: fault injection validation.
        if let Some(fi) = &r.fault_injection {
            if let Some(a) = &fi.abort {
                if a.percentage > 100 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "fault_injection.abort.percentage",
                        "percentage must be in [0, 100]",
                    ));
                }
                if a.status < crate::config::limits::MIN_FAULT_ABORT_STATUS
                    || a.status > crate::config::limits::MAX_FAULT_ABORT_STATUS
                {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "fault_injection.abort.status",
                        format!(
                            "status must be in [{}, {}]",
                            crate::config::limits::MIN_FAULT_ABORT_STATUS,
                            crate::config::limits::MAX_FAULT_ABORT_STATUS
                        ),
                    ));
                }
            }
            if let Some(d) = &fi.delay {
                if d.percentage > 100 {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "fault_injection.delay.percentage",
                        "percentage must be in [0, 100]",
                    ));
                }
                if d.fixed_ms == 0 || d.fixed_ms > crate::config::limits::MAX_FAULT_DELAY_MS {
                    issues.push(issue(
                        "route",
                        &r.name,
                        "fault_injection.delay.fixed_ms",
                        format!(
                            "fixed_ms must be in [1, {}]",
                            crate::config::limits::MAX_FAULT_DELAY_MS
                        ),
                    ));
                }
            }
            // An empty fault_injection block (no abort, no delay) is an
            // authoring mistake — reject it.
            if fi.abort.is_none() && fi.delay.is_none() {
                issues.push(issue(
                    "route",
                    &r.name,
                    "fault_injection",
                    "fault_injection block must have at least one of abort or delay",
                ));
            }
        }
        // SEC-05: OIDC browser login validation. The provider must
        // exist in gateway.oidc_providers; the redirect_uri must be a
        // non-empty path starting with `/`.
        if let Some(oidc_login) = &r.oidc_login {
            if oidc_login.provider.is_empty() {
                issues.push(issue(
                    "route",
                    &r.name,
                    "oidc_login.provider",
                    "oidc_login provider must not be empty",
                ));
            } else if !gateway
                .oidc_providers
                .iter()
                .any(|p| p.name == oidc_login.provider)
            {
                issues.push(issue(
                    "route",
                    &r.name,
                    "oidc_login.provider",
                    format!(
                        "oidc_login provider '{}' not found in gateway.oidc_providers",
                        oidc_login.provider
                    ),
                ));
            }
            if !oidc_login.redirect_uri.starts_with('/') {
                issues.push(issue(
                    "route",
                    &r.name,
                    "oidc_login.redirect_uri",
                    "oidc_login redirect_uri must be a path starting with '/'",
                ));
            }
            if oidc_login.session_ttl_s == 0 {
                issues.push(issue(
                    "route",
                    &r.name,
                    "oidc_login.session_ttl_s",
                    "oidc_login session_ttl_s must be > 0",
                ));
            }
        }
    }

    for u in &gateway.upstreams {
        // DW-042: when dns_discovery is present, endpoints may be empty
        // (the gateway resolves them from DNS). The static-endpoints
        // guard only applies to upstreams without dynamic discovery.
        if u.endpoints.is_empty() && u.dns_discovery.is_none() {
            issues.push(issue(
                "upstream",
                &u.name,
                "endpoints",
                "upstream has no endpoints",
            ));
        }
        // DW-042: validate the dns_discovery block.
        if let Some(dns) = &u.dns_discovery {
            if dns.hostname.trim().is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "dns_discovery.hostname",
                    "dns_discovery hostname is empty",
                ));
            }
            if dns.record_type != "A" && dns.record_type != "SRV" {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "dns_discovery.record_type",
                    "dns_discovery record_type must be \"A\" or \"SRV\"",
                ));
            }
            if dns.refresh_interval_s < crate::config::limits::MIN_DNS_DISCOVERY_REFRESH_S
                || dns.refresh_interval_s > crate::config::limits::MAX_DNS_DISCOVERY_REFRESH_S
            {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "dns_discovery.refresh_interval_s",
                    format!(
                        "dns_discovery refresh_interval_s must be in {}..={}",
                        crate::config::limits::MIN_DNS_DISCOVERY_REFRESH_S,
                        crate::config::limits::MAX_DNS_DISCOVERY_REFRESH_S
                    ),
                ));
            }
        }
        // trusted_ca_file (#121): the connector's TLS trust override for
        // private-CA upstreams. It only applies to the TLS protocols —
        // no TLS is negotiated toward an `http1` upstream, so there is
        // nothing to verify and the field is an authoring mistake (the
        // same reading as a listener's "protocol http must not carry a
        // tls block"). When it does apply, the bundle must be on disk
        // and readable at compile time.
        if let Some(ca) = &u.trusted_ca_file {
            let tls = matches!(
                u.protocol,
                crate::config::UpstreamProtocol::Https | crate::config::UpstreamProtocol::Http2
            );
            if tls {
                check_trusted_ca_file("upstream", &u.name, "trusted_ca_file", ca, &mut issues);
            } else {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "trusted_ca_file",
                    "trusted_ca_file only applies to TLS upstreams (protocol https or http2); no \
                     TLS is negotiated toward an http1 upstream",
                ));
            }
        }
        // REL-08 (#219): use_system_roots is the OS-native trust store
        // alternative to the webpki default. It only applies to the TLS
        // protocols, and is mutually exclusive with trusted_ca_file
        // (both select a trust set; setting both is an authoring
        // mistake — the operator must pick one).
        if u.use_system_roots {
            let tls = matches!(
                u.protocol,
                crate::config::UpstreamProtocol::Https | crate::config::UpstreamProtocol::Http2
            );
            if !tls {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "use_system_roots",
                    "use_system_roots only applies to TLS upstreams (protocol https or http2); no \
                     TLS is negotiated toward an http1 upstream",
                ));
            }
            if u.trusted_ca_file.is_some() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "use_system_roots",
                    "use_system_roots and trusted_ca_file are mutually exclusive; pick one trust \
                     source per upstream",
                ));
            }
        }
        // SEC-04 / DW-109: cert_pinning validation. The block is always
        // accepted by the parser (additive-only); validation enforces:
        // (1) only on TLS upstreams, (2) non-empty pin list, (3) each
        // pin is 64 lowercase hex chars. (Compiled into every build;
        // no cargo feature.)
        if let Some(cp) = &u.cert_pinning {
            let tls = matches!(
                u.protocol,
                crate::config::UpstreamProtocol::Https | crate::config::UpstreamProtocol::Http2
            );
            if !tls {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "cert_pinning",
                    "cert_pinning only applies to TLS upstreams (protocol https or http2); no \
                     TLS is negotiated toward an http1 upstream",
                ));
            }
            if cp.pins.is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "cert_pinning.pins",
                    "cert_pinning pins list must not be empty (a pin-less pinning block is an \
                     authoring mistake, not 'pin nothing')",
                ));
            }
            for (i, pin) in cp.pins.iter().enumerate() {
                let h = &pin.spki_sha256;
                if h.len() != 64
                    || !h
                        .chars()
                        .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
                {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        &format!("cert_pinning.pins[{i}].spki_sha256"),
                        "spki_sha256 must be 64 lowercase hex chars (SHA-256)",
                    ));
                }
            }
        }
        // SEC-03: upstream mTLS client cert validation. The block is
        // always accepted by the parser (additive-only); validation
        // enforces: (1) only on TLS upstreams, (2) cert/key files exist
        // and are readable at compile time.
        if let Some(mtls) = &u.mtls {
            let tls = matches!(
                u.protocol,
                crate::config::UpstreamProtocol::Https | crate::config::UpstreamProtocol::Http2
            );
            if !tls {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "mtls",
                    "mtls only applies to TLS upstreams (protocol https or http2); no \
                     TLS is negotiated toward an http1 upstream",
                ));
            } else {
                // Check that the cert and key files are readable.
                if let Err(e) = std::fs::read_to_string(&mtls.client_cert_file) {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "mtls.client_cert_file",
                        format!(
                            "client_cert_file '{}' cannot be read: {e}",
                            mtls.client_cert_file
                        ),
                    ));
                }
                if let Err(e) = std::fs::read_to_string(&mtls.client_key_file) {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "mtls.client_key_file",
                        format!(
                            "client_key_file '{}' cannot be read: {e}",
                            mtls.client_key_file
                        ),
                    ));
                }
            }
        }
        let mut seen_targets = std::collections::BTreeSet::new();
        let mut total_vnodes: u64 = 0;
        for (i, e) in u.endpoints.iter().enumerate() {
            if e.address.trim().is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    &format!("endpoints[{i}].address"),
                    "endpoint address is empty",
                ));
            }
            if e.weight == 0 {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    &format!("endpoints[{i}].weight"),
                    "endpoint weight must be > 0",
                ));
            }
            // Duplicate address:port corrupts shared balancer state (both
            // entries carry to the same live counter; guards would
            // double-decrement). Reject at validation time. The target is
            // compared TRIMMED, exactly like the empty-address check
            // above: " 127.0.0.1" and "127.0.0.1" are the same endpoint
            // (#128, DW-011 review).
            if !seen_targets.insert((e.address.trim(), e.port)) {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    &format!("endpoints[{i}].address"),
                    format!(
                        "duplicate endpoint {}/{}: address:port must be unique within an upstream",
                        e.address.trim(),
                        e.port
                    ),
                ));
            }
            total_vnodes += crate::config::limits::KETAMA_VNODES * e.weight.max(1) as u64;
        }
        if u.load_balancer == crate::config::LoadBalancer::IpHash
            && total_vnodes > crate::config::limits::MAX_RING_VNODES
        {
            issues.push(issue(
                "upstream",
                &u.name,
                "endpoints.weight",
                format!(
                    "ip_hash ring too large: total vnodes (160 * sum of weights) must be at most {}",
                    crate::config::limits::MAX_RING_VNODES
                ),
            ));
        }
        // DP-07 (#236): hash_on is only meaningful for consistent-hash
        // load balancers (ip_hash and maglev). A hash_on block on a
        // non-hash algorithm is an authoring mistake.
        if let Some(hash_on) = &u.hash_on {
            if !matches!(
                u.load_balancer,
                crate::config::LoadBalancer::IpHash | crate::config::LoadBalancer::Maglev
            ) {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "hash_on",
                    format!(
                        "hash_on only applies to ip_hash or maglev load balancers; \
                         '{}' does not use a hash key",
                        match u.load_balancer {
                            crate::config::LoadBalancer::RoundRobin => "round_robin",
                            crate::config::LoadBalancer::LeastRequests => "least_requests",
                            crate::config::LoadBalancer::Random => "random",
                            crate::config::LoadBalancer::PeakEwma => "peak_ewma",
                            _ => "this",
                        }
                    ),
                ));
            }
            // Validate cookie/header names are non-empty.
            match hash_on {
                crate::config::HashOn::Cookie { cookie } => {
                    if cookie.trim().is_empty() {
                        issues.push(issue(
                            "upstream",
                            &u.name,
                            "hash_on.cookie",
                            "hash_on cookie name must be a non-empty string",
                        ));
                    }
                }
                crate::config::HashOn::Header { header } => {
                    if header.trim().is_empty() {
                        issues.push(issue(
                            "upstream",
                            &u.name,
                            "hash_on.header",
                            "hash_on header name must be a non-empty string",
                        ));
                    }
                }
                _ => {}
            }
        }
        if u.connection_cap == Some(0) {
            issues.push(issue(
                "upstream",
                &u.name,
                "connection_cap",
                "connection_cap must be > 0",
            ));
        }
        if u.max_pending == Some(0) {
            issues.push(issue(
                "upstream",
                &u.name,
                "max_pending",
                "max_pending must be > 0 (unbounded is expressed by omitting \
                 the field, so an explicit 0 is rejected as ambiguous)",
            ));
        }
        if let Some(b) = &u.breaker {
            for (field, v) in [
                (
                    "breaker.consecutive_failures",
                    u64::from(b.consecutive_failures),
                ),
                ("breaker.error_volume", u64::from(b.error_volume)),
                ("breaker.open_ms", b.open_ms),
                ("breaker.half_open_probes", u64::from(b.half_open_probes)),
            ] {
                if v == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        field,
                        "circuit breaker value must be > 0",
                    ));
                }
            }
            if !b.error_ratio.is_finite() || b.error_ratio <= 0.0 || b.error_ratio > 1.0 {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "breaker.error_ratio",
                    format!("error_ratio must be in (0, 1]; got {}", b.error_ratio),
                ));
            }
        }
        if u.slow_start_ms
            .is_some_and(|ms| ms > crate::config::limits::MAX_SLOW_START_MS)
        {
            issues.push(issue(
                "upstream",
                &u.name,
                "slow_start_ms",
                "slow_start_ms must be at most 10 minutes (600000)",
            ));
        }
        if let Some(h) = &u.health {
            // Every knob must be positive; the ratio additionally must be a
            // real fraction (0, 1]. NaN/inf compare false everywhere and
            // would silently disable ejection, so reject them explicitly.
            for (field, v) in [
                ("health.window_ms", h.window_ms),
                ("health.eject_ms", h.eject_ms),
            ] {
                if v == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        field,
                        "passive health value must be > 0",
                    ));
                }
            }
            for (field, v) in [
                ("health.consecutive_failures", h.consecutive_failures),
                ("health.failure_min_volume", h.failure_min_volume),
                ("health.half_open_probes", h.half_open_probes),
            ] {
                if v == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        field,
                        "passive health value must be > 0",
                    ));
                }
            }
            if !h.failure_ratio.is_finite() || h.failure_ratio <= 0.0 || h.failure_ratio > 1.0 {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "health.failure_ratio",
                    format!("failure_ratio must be in (0, 1]; got {}", h.failure_ratio),
                ));
            }
        }
        if let Some(a) = &u.active_health {
            // Active probes report into the passive ejection machinery, so
            // the passive block (which owns eject/half-open windows) is a
            // hard requirement.
            if u.health.is_none() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "active_health",
                    "active health requires the passive `health` block (probe results report \
                     into the same ejection machinery)",
                ));
            }
            for (field, v) in [
                ("active_health.interval_ms", a.interval_ms),
                ("active_health.timeout_ms", a.timeout_ms),
            ] {
                if v == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        field,
                        "active health value must be > 0",
                    ));
                }
            }
            // jitter_ms == 0 is legal: it disables jitter entirely.
            for (field, v) in [
                ("active_health.success_threshold", a.success_threshold),
                ("active_health.failure_threshold", a.failure_threshold),
            ] {
                if v == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        field,
                        "active health threshold must be > 0",
                    ));
                }
            }
            if a.timeout_ms > a.interval_ms {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "active_health.timeout_ms",
                    "timeout_ms must be <= interval_ms (an overlapping probe would pile up)",
                ));
            }
            if a.jitter_ms > a.interval_ms {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "active_health.jitter_ms",
                    "jitter_ms must be <= interval_ms",
                ));
            }
            if a.kind == crate::config::ProbeKind::Http
                && (!a.path.starts_with('/') || a.path.bytes().any(|b| b.is_ascii_control()))
            {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "active_health.path",
                    format!(
                        "probe path '{}' must start with '/' and contain no control characters",
                        a.path
                    ),
                ));
            }
        }
        if let Some(t) = &u.timeouts {
            for (field, v) in [
                ("connect_ms", t.connect_ms),
                ("read_ms", t.read_ms),
                ("write_ms", t.write_ms),
            ] {
                if v == Some(0) {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        &format!("timeouts.{field}"),
                        "timeout must be > 0 milliseconds",
                    ));
                }
            }
            // DW-030: 0 is LEGAL here (it disables happy-eyeballs racing
            // instead of unbounding it — the house zero-disables pattern);
            // only the upper bound applies.
            if t.happy_eyeballs_ms
                .is_some_and(|ms| ms > crate::config::limits::MAX_HAPPY_EYEBALLS_MS)
            {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "timeouts.happy_eyeballs_ms",
                    format!(
                        "happy_eyeballs_ms must be at most {} (0 disables racing)",
                        crate::config::limits::MAX_HAPPY_EYEBALLS_MS
                    ),
                ));
            }
        }
        // DP-03: hyper connection-pool and HTTP/2 tuning bounds. Every
        // field is optional; a present value must be within bounds. The
        // h2-only knobs are accepted on any protocol (the runtime ignores
        // them for non-h2 upstreams), so validation only checks bounds —
        // protocol gating is a runtime concern, not an authoring error.
        if let Some(p) = &u.pool {
            if let Some(ms) = p.pool_idle_timeout_ms {
                if ms == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.pool_idle_timeout_ms",
                        "pool_idle_timeout_ms must be > 0 (omit the field for the hyper default)",
                    ));
                } else if ms > crate::config::limits::MAX_POOL_IDLE_TIMEOUT_MS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.pool_idle_timeout_ms",
                        format!(
                            "pool_idle_timeout_ms must be at most {}",
                            crate::config::limits::MAX_POOL_IDLE_TIMEOUT_MS
                        ),
                    ));
                }
            }
            if let Some(n) = p.pool_max_idle_per_host {
                if n > crate::config::limits::MAX_POOL_MAX_IDLE_PER_HOST {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.pool_max_idle_per_host",
                        format!(
                            "pool_max_idle_per_host must be at most {}",
                            crate::config::limits::MAX_POOL_MAX_IDLE_PER_HOST
                        ),
                    ));
                }
            }
            if let Some(ms) = p.http2_keep_alive_interval_ms {
                if ms == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.http2_keep_alive_interval_ms",
                        "http2_keep_alive_interval_ms must be > 0 (omit the field to disable PINGs)",
                    ));
                } else if ms > crate::config::limits::MAX_HTTP2_KEEP_ALIVE_INTERVAL_MS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.http2_keep_alive_interval_ms",
                        format!(
                            "http2_keep_alive_interval_ms must be at most {}",
                            crate::config::limits::MAX_HTTP2_KEEP_ALIVE_INTERVAL_MS
                        ),
                    ));
                }
            }
            if let Some(ms) = p.http2_keep_alive_timeout_ms {
                if ms == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.http2_keep_alive_timeout_ms",
                        "http2_keep_alive_timeout_ms must be > 0 (omit the field for the hyper default)",
                    ));
                } else if ms > crate::config::limits::MAX_HTTP2_KEEP_ALIVE_TIMEOUT_MS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.http2_keep_alive_timeout_ms",
                        format!(
                            "http2_keep_alive_timeout_ms must be at most {}",
                            crate::config::limits::MAX_HTTP2_KEEP_ALIVE_TIMEOUT_MS
                        ),
                    ));
                }
            }
            if let Some(n) = p.max_concurrent_streams {
                if n == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.max_concurrent_streams",
                        "max_concurrent_streams must be > 0 (omit the field for the hyper default)",
                    ));
                } else if n > crate::config::limits::MAX_POOL_MAX_CONCURRENT_STREAMS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.max_concurrent_streams",
                        format!(
                            "max_concurrent_streams must be at most {}",
                            crate::config::limits::MAX_POOL_MAX_CONCURRENT_STREAMS
                        ),
                    ));
                }
            }
            // SCALE-10 (#189): pre-warm, per-endpoint cap, max-age.
            if let Some(n) = p.pre_warm {
                if n > 64 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.pre_warm",
                        "pre_warm must be at most 64 per endpoint",
                    ));
                }
            }
            if let Some(n) = p.per_endpoint_cap {
                if n == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.per_endpoint_cap",
                        "per_endpoint_cap must be > 0 (omit the field for no per-endpoint cap)",
                    ));
                } else if n > 1024 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.per_endpoint_cap",
                        "per_endpoint_cap must be at most 1024",
                    ));
                }
            }
            if let Some(ms) = p.max_connection_age_ms {
                if ms == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.max_connection_age_ms",
                        "max_connection_age_ms must be > 0 (omit the field for no max-age)",
                    ));
                } else if ms > crate::config::limits::MAX_POOL_IDLE_TIMEOUT_MS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "pool.max_connection_age_ms",
                        format!(
                            "max_connection_age_ms must be at most {}",
                            crate::config::limits::MAX_POOL_IDLE_TIMEOUT_MS
                        ),
                    ));
                }
            }
        }
        if let Some(r) = &u.retries {
            if r.attempts > crate::config::limits::MAX_RETRY_ATTEMPTS {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "retries.attempts",
                    format!(
                        "retries.attempts must be at most {} (retries beyond the first attempt)",
                        crate::config::limits::MAX_RETRY_ATTEMPTS
                    ),
                ));
            }
            if r.backoff_base_ms == 0 {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "retries.backoff_base_ms",
                    "backoff_base_ms must be > 0",
                ));
            }
            if r.backoff_cap_ms < r.backoff_base_ms {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "retries.backoff_cap_ms",
                    "backoff_cap_ms must be >= backoff_base_ms",
                ));
            }
            if r.budget_percent == 0 || r.budget_percent > 100 {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "retries.budget_percent",
                    "budget_percent must be in (0, 100]",
                ));
            }
            // REL-01: cross-attempt total retry deadline (wall-clock cap
            // including backoff). 0 is rejected (omit the field for
            // unbounded); a present value must be within the bound.
            if let Some(td) = r.total_deadline_ms {
                if td == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "retries.total_deadline_ms",
                        "total_deadline_ms must be > 0 (omit the field for unbounded)",
                    ));
                } else if td > crate::config::limits::MAX_RETRY_TOTAL_DEADLINE_MS {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "retries.total_deadline_ms",
                        format!(
                            "total_deadline_ms must be at most {}",
                            crate::config::limits::MAX_RETRY_TOTAL_DEADLINE_MS
                        ),
                    ));
                }
            }
            for (i, status) in r.retry_statuses.iter().enumerate() {
                if !(400..=599).contains(status) {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        &format!("retries.retry_statuses[{i}]"),
                        format!("retry status {status} is not a 4xx/5xx status"),
                    ));
                }
            }
            // DW-063: hedge validation.
            if let Some(h) = &r.hedge {
                if h.hedge_after_ms < crate::config::limits::MIN_HEDGE_AFTER_MS
                    || h.hedge_after_ms > crate::config::limits::MAX_HEDGE_AFTER_MS
                {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "retries.hedge.hedge_after_ms",
                        format!(
                            "hedge_after_ms must be in [{}, {}]",
                            crate::config::limits::MIN_HEDGE_AFTER_MS,
                            crate::config::limits::MAX_HEDGE_AFTER_MS
                        ),
                    ));
                }
                if h.hedge_max == 0 || h.hedge_max > crate::config::limits::MAX_HEDGE_COPIES {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "retries.hedge.hedge_max",
                        format!(
                            "hedge_max must be in [1, {}]",
                            crate::config::limits::MAX_HEDGE_COPIES
                        ),
                    ));
                }
                // Hedging requires a replayable body.
                if r.buffer_max_bytes == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "retries.hedge",
                        "hedging requires retries.buffer_max_bytes > 0 (the body must be \
                         replayable to send a hedge copy)",
                    ));
                }
            }
        }
        // DW-035: OAuth2 client-credentials validation.
        if let Some(o) = &u.oauth2_client_credentials {
            // token_endpoint must be an absolute http(s) URL.
            match o.token_endpoint.parse::<hyper::Uri>() {
                Ok(uri) => {
                    if !matches!(uri.scheme_str(), Some("http") | Some("https"))
                        || uri.host().is_none()
                    {
                        issues.push(issue(
                            "upstream",
                            &u.name,
                            "oauth2_client_credentials.token_endpoint",
                            format!("'{}' must be an absolute http(s) URL", o.token_endpoint),
                        ));
                    }
                }
                Err(_) => issues.push(issue(
                    "upstream",
                    &u.name,
                    "oauth2_client_credentials.token_endpoint",
                    format!("'{}' is not a valid URL", o.token_endpoint),
                )),
            }
            if o.client_id.is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "oauth2_client_credentials.client_id",
                    "client_id must not be empty",
                ));
            }
            if o.client_secret.is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "oauth2_client_credentials.client_secret",
                    "client_secret must not be empty",
                ));
            }
            if let Some(ttl) = o.token_cache_ttl_s {
                if ttl == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "oauth2_client_credentials.token_cache_ttl_s",
                        "token_cache_ttl_s must be > 0",
                    ));
                }
            }
            // mTLS cert/key files must exist and be readable at compile
            // time (the same check as trusted_ca_file). A missing file
            // disables the upstream's OAuth2 at build instead of failing
            // every request.
            if let Some(m) = &o.mtls {
                check_file_readable(
                    "upstream",
                    &u.name,
                    "oauth2_client_credentials.mtls.client_cert",
                    &m.client_cert,
                    &mut issues,
                );
                check_file_readable(
                    "upstream",
                    &u.name,
                    "oauth2_client_credentials.mtls.client_key",
                    &m.client_key,
                    &mut issues,
                );
            }
        }
        // DW-090: Peak-EWMA load-balancer tuning validation.
        if let Some(pe) = &u.peak_ewma {
            if let Some(decay) = pe.decay_ms {
                if decay == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "peak_ewma.decay_ms",
                        "peak_ewma.decay_ms must be > 0 (the EWMA decay window)",
                    ));
                }
            }
            if let Some(rtt) = pe.default_rtt_ms {
                if rtt == 0 {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "peak_ewma.default_rtt_ms",
                        "peak_ewma.default_rtt_ms must be > 0 (the initial cost estimate)",
                    ));
                }
            }
        }
        // DW-094 (Ent): locality-aware routing and data residency
        // validation.
        if let Some(loc) = &u.locality {
            // Data residency: allowed_regions must be non-empty when
            // enforce_data_residency is true.
            if loc.enforce_data_residency && loc.allowed_regions.is_empty() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "locality.allowed_regions",
                    "locality.allowed_regions must be non-empty when \
                     enforce_data_residency is true",
                ));
            }
            // Region/zone fields on endpoints must be non-empty strings.
            for (i, ep) in u.endpoints.iter().enumerate() {
                if let Some(r) = &ep.region {
                    if r.is_empty() {
                        issues.push(issue(
                            "upstream",
                            &u.name,
                            &format!("endpoints[{i}].region"),
                            "endpoint region must be a non-empty string",
                        ));
                    }
                }
                if let Some(z) = &ep.zone {
                    if z.is_empty() {
                        issues.push(issue(
                            "upstream",
                            &u.name,
                            &format!("endpoints[{i}].zone"),
                            "endpoint zone must be a non-empty string",
                        ));
                    }
                }
            }
            // When data residency is enforced, at least one endpoint
            // must satisfy the allowed_regions constraint (or have no
            // region — locality-agnostic endpoints are always allowed).
            if loc.enforce_data_residency {
                let has_satisfiable = u.endpoints.iter().any(|ep| {
                    ep.region
                        .as_ref()
                        .is_none_or(|r| loc.allowed_regions.contains(r))
                });
                if !has_satisfiable {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "locality.allowed_regions",
                        "no endpoint satisfies the allowed_regions constraint \
                         (every endpoint has a region not in the allowed list)",
                    ));
                }
            }
            // denied_regions must not overlap with allowed_regions.
            for d in &loc.denied_regions {
                if loc.allowed_regions.contains(d) {
                    issues.push(issue(
                        "upstream",
                        &u.name,
                        "locality.denied_regions",
                        format!(
                            "region '{}' appears in both allowed_regions and \
                             denied_regions (contradictory)",
                            d
                        ),
                    ));
                }
            }
        }
    }

    // DW-035: mTLS consumer mapping validation.
    if let Some(m) = &gateway.mtls_consumer_mapping {
        if m.enabled {
            let consumer_names: std::collections::BTreeSet<&str> =
                gateway.consumers.iter().map(|c| c.name.as_str()).collect();
            for (i, entry) in m.consumers.iter().enumerate() {
                // Fingerprint grammar: 64 hex digits with optional colon
                // separators (lowercase or uppercase; normalized at build).
                let stripped = entry.fingerprint.replace(':', "");
                if stripped.len() != 64 || !stripped.bytes().all(|b| b.is_ascii_hexdigit()) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("mtls_consumer_mapping.consumers[{i}].fingerprint"),
                        format!(
                            "fingerprint '{}' must be 64 hex digits with optional ':' separators \
                             (SHA-256 of the certificate DER)",
                            entry.fingerprint
                        ),
                    ));
                }
                if !consumer_names.contains(entry.consumer.as_str()) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        &format!("mtls_consumer_mapping.consumers[{i}].consumer"),
                        format!(
                            "consumer '{}' is not defined in the consumers list",
                            entry.consumer
                        ),
                    ));
                }
            }
            for (cn, consumer) in &m.subject_cn_mapping {
                if cn.is_empty() {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "mtls_consumer_mapping.subject_cn_mapping",
                        "subject CN key must not be empty",
                    ));
                }
                if !consumer_names.contains(consumer.as_str()) {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "mtls_consumer_mapping.subject_cn_mapping",
                        format!("consumer '{consumer}' is not defined in the consumers list"),
                    ));
                }
            }
        }
    }

    // DW-035: mTLS forward headers validation.
    if let Some(f) = &gateway.mtls_forward_headers {
        if f.enabled {
            // Prefix must be a valid HTTP token (it becomes header
            // names like `<prefix>-Fingerprint`).
            let prefix = f.prefix.as_str();
            if prefix.is_empty() {
                issues.push(issue(
                    "gateway",
                    "(root)",
                    "mtls_forward_headers.prefix",
                    "prefix must not be empty",
                ));
            }
            // Check that the derived header names are valid.
            for suffix in &["Fingerprint", "Subject-CN", "Issuer-CN", "Not-After"] {
                let name = format!("{prefix}-{suffix}");
                if hyper::header::HeaderName::from_bytes(name.as_bytes()).is_err() {
                    issues.push(issue(
                        "gateway",
                        "(root)",
                        "mtls_forward_headers.prefix",
                        format!("'{name}' is not a valid HTTP header name"),
                    ));
                }
            }
        }
    }

    // DW-036: hmac key ids are the SELECTOR a signed request presents;
    // a duplicate would make consumer resolution ambiguous. First
    // declarant wins the map, later ones get the issue.
    let mut hmac_key_ids: std::collections::HashMap<&str, &str> = std::collections::HashMap::new();
    for c in &gateway.consumers {
        // The consumer name is injected upstream as the X-Consumer-Name
        // header value; non-visible-ASCII names cannot be represented in a
        // header and would silently break the identity injection (DW-019
        // review). Reject at compile time instead.
        if c.name.is_empty() || !c.name.bytes().all(|b| (0x21..=0x7e).contains(&b)) {
            issues.push(issue(
                "consumer",
                &c.name,
                "name",
                "consumer name must be non-empty visible ASCII (0x21-0x7E): it is injected \
                 upstream as the X-Consumer-Name header value",
            ));
        }
        if let Some(p) = c.priority {
            if p > 10 {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    "priority",
                    format!("priority {p} is out of range: must be 0 (lowest) to 10 (highest)"),
                ));
            }
        }
        for (i, cred) in c.credentials.iter().enumerate() {
            let field = format!("credentials[{i}]");
            // DW-036: cross-consumer key-id uniqueness (see the map's
            // declaration note above).
            if let Credential::Hmac { key_id, .. } = cred {
                match hmac_key_ids.get_key_value(key_id.as_str()) {
                    Some((_, other_consumer)) => {
                        issues.push(issue(
                            "consumer",
                            &c.name,
                            &field,
                            format!(
                                "hmac key_id '{key_id}' is already declared by consumer \
                                 '{other_consumer}' (key ids select the credential a signed \
                                 request presents; they must be unique)"
                            ),
                        ));
                    }
                    None => {
                        hmac_key_ids.insert(key_id.as_str(), c.name.as_str());
                    }
                }
            }
            let problem = match cred {
                Credential::ApiKey { key } if key.is_empty() => {
                    Some("api key is empty".to_string())
                }
                // DW-045: an api key may be a ${...} reference. Resolve it
                // NOW (config-compile time) so an unresolvable secret fails
                // the generation closed — the same contract as
                // trusted_ca_file. Reference-shaped but malformed values
                // fail equally: treating a typo'd reference as a literal
                // key would silently install garbage bytes as the key.
                // Messages name the reference, never a resolved value.
                Credential::ApiKey { key } => {
                    match crate::config::credentials::parse_secret_reference(key) {
                        None => None,
                        Some(Ok(reference)) => reference.resolve().err(),
                        Some(Err(malformed)) => Some(malformed),
                    }
                }
                // DW-036: an hmac signing credential. The key id is the
                // PRESENTED selector (a header value), so it must be
                // representable: non-empty visible ASCII, bounded length.
                // The secret follows the same reference contract as api
                // keys (resolve at compile time, fail closed naming the
                // reference). Duplicate key ids across ALL consumers are
                // rejected inside the loop below (an ambiguous selector
                // cannot pick a consumer deterministically).
                Credential::Hmac { key_id, secret } => {
                    if key_id.is_empty() {
                        Some("hmac key_id is empty".to_string())
                    } else if !key_id.bytes().all(|b| (0x21..=0x7e).contains(&b)) {
                        Some(
                            "hmac key_id must be visible ASCII (0x21-0x7E): it is presented \
                             as the X-Dwara-Key-Id header value"
                                .to_string(),
                        )
                    } else if key_id.len() > 128 {
                        Some("hmac key_id is longer than 128 bytes".to_string())
                    } else if secret.is_empty() {
                        Some("hmac secret is empty".to_string())
                    } else {
                        match crate::config::credentials::parse_secret_reference(secret) {
                            None => None,
                            Some(Ok(reference)) => reference.resolve().err(),
                            Some(Err(malformed)) => Some(malformed),
                        }
                    }
                }
                Credential::Jwt { issuer, .. } if issuer.is_empty() => {
                    Some("jwt issuer is empty".to_string())
                }
                // #124: an mtls credential matches a verified client
                // certificate by subject CN or by fingerprint — exactly
                // one of the two must carry a non-empty value. Both-set
                // is rejected because only the subject would ever be
                // matched (the fingerprint would sit inert).
                Credential::Mtls {
                    subject,
                    fingerprint,
                } => {
                    let s = subject.as_deref().unwrap_or("");
                    let f = fingerprint.as_deref().unwrap_or("");
                    if s.is_empty() && f.is_empty() {
                        Some(
                            "mtls credential must set subject or fingerprint (both are empty)"
                                .to_string(),
                        )
                    } else if subject.is_some() && s.is_empty() {
                        Some("mtls subject is empty".to_string())
                    } else if fingerprint.is_some() && f.is_empty() {
                        Some("mtls fingerprint is empty".to_string())
                    } else if subject.is_some() && fingerprint.is_some() {
                        Some(
                            "mtls credential must set subject or fingerprint, not both \
                             (both are set; only the subject would be matched)"
                                .to_string(),
                        )
                    } else {
                        None
                    }
                }
                _ => None,
            };
            if let Some(m) = problem {
                issues.push(issue("consumer", &c.name, &field, m));
            }
        }
        for p in &c.policies {
            if !policies.contains(p.as_str()) {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    "policies",
                    format!("references unknown policy '{p}'"),
                ));
            }
        }
        // Consumer authorization (#123): shared shape checks with every
        // other attachment level.
        if let Some(authz) = &c.authorization {
            validate_authz(
                "consumer",
                &c.name,
                authz,
                &consumers,
                &consumer_groups,
                &mut issues,
            );
        }
        // DW-113: tool_allowlist entries must reference configured MCP
        // tools. When no `ai.mcp` block is configured, a non-empty
        // allowlist is an error (the tools do not exist).
        if !c.tool_allowlist.is_empty() {
            let mcp_tools: Option<std::collections::BTreeSet<&str>> = gateway
                .ai
                .as_ref()
                .and_then(|ai| ai.mcp.as_ref())
                .map(|mcp| mcp.tools.keys().map(|s| s.as_str()).collect());
            match mcp_tools {
                None => {
                    issues.push(issue(
                        "consumer",
                        &c.name,
                        "tool_allowlist",
                        "tool_allowlist is non-empty but no ai.mcp block is configured \
                         (the tools do not exist)",
                    ));
                }
                Some(tool_names) => {
                    for tool in &c.tool_allowlist {
                        if !tool_names.contains(tool.as_str()) {
                            issues.push(issue(
                                "consumer",
                                &c.name,
                                "tool_allowlist",
                                format!(
                                    "tool_allowlist references unknown tool '{tool}' \
                                     (not in ai.mcp.tools)"
                                ),
                            ));
                        }
                    }
                }
            }
        }
        // DW-113: per-consumer token_budget — same shape checks as a
        // policy's token_budget (at least one window, positive values).
        if let Some(tb) = &c.token_budget {
            if tb.tokens_per_min.is_none() && tb.cost_per_day_micros.is_none() {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    "token_budget",
                    "a token_budget must set tokens_per_min and/or cost_per_day_micros \
                     (an empty budget bounds nothing)",
                ));
            }
            if tb.tokens_per_min == Some(0) {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    "token_budget.tokens_per_min",
                    "tokens_per_min must be > 0 (omit the field for no token window)",
                ));
            }
            if tb.cost_per_day_micros == Some(0) {
                issues.push(issue(
                    "consumer",
                    &c.name,
                    "token_budget.cost_per_day_micros",
                    "cost_per_day_micros must be > 0 (omit the field for no cost window)",
                ));
            }
        }
    }

    for p in &gateway.policies {
        if let Some(rl) = &p.rate_limit {
            if rl.requests == 0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "rate_limit.requests",
                    "rate limit requests must be > 0 (0 would block every request)",
                ));
            }
            if rl.window_seconds == 0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "rate_limit.window_seconds",
                    "rate limit window_seconds must be > 0 (0 is a nonsensical window)",
                ));
            }
        }
        for (i, rule) in p.rate_limits.iter().enumerate() {
            let field = format!("rate_limits[{i}]");
            if rule.selector.is_empty() {
                issues.push(issue(
                    "policy",
                    &p.name,
                    &format!("{field}.selector"),
                    "rate limit selector must name at least one key component",
                ));
            }
            let rp = &rule.requests_per;
            if rp.per_second.is_none() && rp.minute.is_none() && rp.hour.is_none() {
                issues.push(issue(
                    "policy",
                    &p.name,
                    &format!("{field}.requests_per"),
                    "rate limit rule must set at least one window (s, minute, hour)",
                ));
            }
            for (window, value) in [
                ("s", rp.per_second),
                ("minute", rp.minute),
                ("hour", rp.hour),
            ] {
                if value == Some(0) {
                    issues.push(issue(
                        "policy",
                        &p.name,
                        &format!("{field}.requests_per.{window}"),
                        "rate limit window rate must be > 0 (0 would block every request)",
                    ));
                }
            }
            if rule.burst == Some(0) {
                issues.push(issue(
                    "policy",
                    &p.name,
                    &format!("{field}.burst"),
                    "rate limit burst must be >= 1 when present (omit for the default)",
                ));
            }
        }
        // DW-090: anomaly scoring policy validation.
        if let Some(an) = &p.anomaly {
            if an.enabled && an.signals.is_empty() {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "anomaly.signals",
                    "anomaly scoring is enabled but no signals are configured (at least \
                     one signal is required)",
                ));
            }
            if !an.threshold.is_finite() || an.threshold <= 0.0 || an.threshold > 1.0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "anomaly.threshold",
                    format!("anomaly.threshold must be in (0, 1]; got {}", an.threshold),
                ));
            }
            if an.max_body_inspect_bytes == 0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "anomaly.max_body_inspect_bytes",
                    "anomaly.max_body_inspect_bytes must be > 0 (the body_size signal \
                     cap; use a large value to effectively disable the cap)",
                ));
            }
        }
        // DW-089: adaptive rate-limit tuning validation.
        if let Some(ad) = &p.adaptive {
            if ad.ewma_window_secs == 0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.ewma_window_secs",
                    "adaptive.ewma_window_secs must be > 0 (0 is a nonsensical decay window)",
                ));
            }
            if !ad.min_factor.is_finite() || ad.min_factor <= 0.0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.min_factor",
                    format!(
                        "adaptive.min_factor must be > 0 (never 0); got {}",
                        ad.min_factor
                    ),
                ));
            }
            if !ad.max_factor.is_finite() || ad.max_factor <= 0.0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.max_factor",
                    format!(
                        "adaptive.max_factor must be > 0 (never unbounded); got {}",
                        ad.max_factor
                    ),
                ));
            }
            if ad.min_factor.is_finite()
                && ad.max_factor.is_finite()
                && ad.min_factor > 0.0
                && ad.max_factor > 0.0
                && ad.min_factor > ad.max_factor
            {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.min_factor",
                    format!(
                        "adaptive.min_factor ({}) must be <= adaptive.max_factor ({})",
                        ad.min_factor, ad.max_factor
                    ),
                ));
            }
            if !ad.error_threshold.is_finite()
                || ad.error_threshold <= 0.0
                || ad.error_threshold > 1.0
            {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.error_threshold",
                    format!(
                        "adaptive.error_threshold must be in (0, 1]; got {}",
                        ad.error_threshold
                    ),
                ));
            }
            if ad.latency_threshold_ms == 0 {
                issues.push(issue(
                    "policy",
                    &p.name,
                    "adaptive.latency_threshold_ms",
                    "adaptive.latency_threshold_ms must be > 0 (0 would mark every \
                     response as slow)",
                ));
            }
        }
    }

    issues
}

/// DW-111: FIPS 140-3 mode primitive restrictions. When the `fips` cargo
/// feature is ON, reject non-approved primitives at config validation:
///
/// - Ed25519 certificates: the leaf certificate's SubjectPublicKeyInfo
///   algorithm must not be Ed25519 (not on the FIPS-validated list for
///   aws-lc-rs). The check walks the certificate DER the same way the
///   SPKI extractor in `security::tls` does (no X.509 parser dependency).
/// - Argon2 credential hashing: a config-declared credential whose
///   stored-hash format prefix is `argon2id` (or `argon2`) is rejected.
///   Config-declared credentials use sha256/hmac-sha256 (the fast path);
///   argon2 is store-managed only, but a config that declares an argon2
///   hash directly is rejected here so the gateway never boots in FIPS
///   mode with a non-approved hash.
///
/// When the `fips` feature is OFF, this function is inert (no issues
/// produced). The check is conservative: a certificate that cannot be
/// parsed is skipped (the TLS build path will reject an unparseable cert
/// on its own); only a parseable cert whose SPKI algorithm is Ed25519 is
/// flagged.
fn validate_fips(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    if !crate::security::fips::FipsMode::current().is_enabled() {
        return;
    }
    {
        use crate::security::fips;

        // Ed25519 certificate check: walk every terminate-mode listener's
        // certificate files and check the leaf certificate's SPKI algorithm.
        // The DER walk is the same substrate as `spki_of_leaf` in
        // `security::tls` (no X.509 parser dependency). A certificate that
        // cannot be read or parsed is skipped here — the TLS build path
        // rejects unparseable certs on its own, and piling a FIPS issue on
        // a broken file is noise.
        for l in &gateway.listeners {
            if l.protocol != ListenerProtocol::Https {
                continue;
            }
            let Some(tls) = &l.tls else { continue };
            if tls.mode != TlsMode::Terminate {
                continue;
            }
            // Collect all cert file paths from the terminate block.
            let mut cert_paths: Vec<&str> = Vec::new();
            if let Some(cf) = &tls.cert_file {
                cert_paths.push(cf.as_str());
            }
            for c in &tls.certificates {
                cert_paths.push(c.cert_file.as_str());
            }
            for cf in &cert_paths {
                if let Some(algo) = spki_algorithm_of_cert_file(cf) {
                    if fips::is_signature_disallowed(&algo) {
                        issues.push(issue(
                            "listener",
                            &l.name,
                            "tls.cert_file",
                            format!(
                                "FIPS mode rejects certificate '{cf}': the leaf certificate's \
                                 signature algorithm '{algo}' is not on the FIPS-approved \
                                 allowlist (Ed25519 is not FIPS-validated in aws-lc-rs; use \
                                 RSA-PSS or ECDSA P-256/P-384 certificates instead)"
                            ),
                        ));
                    }
                }
            }
        }

        // Admin block: check the admin mTLS server certificate too.
        if let Some(admin) = &gateway.admin {
            if let Some(algo) = spki_algorithm_of_cert_file(&admin.tls.cert_file) {
                if fips::is_signature_disallowed(&algo) {
                    issues.push(issue(
                        "admin",
                        "(root)",
                        "tls.cert_file",
                        format!(
                            "FIPS mode rejects admin certificate '{}': the leaf certificate's \
                             signature algorithm '{}' is not on the FIPS-approved allowlist \
                             (Ed25519 is not FIPS-validated in aws-lc-rs; use RSA-PSS or \
                             ECDSA P-256/P-384 certificates instead)",
                            admin.tls.cert_file, algo
                        ),
                    ));
                }
            }
        }

        // Argon2 credential hashing check: config-declared credentials
        // use sha256/hmac-sha256 (the fast path). A config that declares
        // an argon2 hash directly is rejected. In practice config
        // credentials are ApiKey/Hmac/Jwt/Mtls (no stored-hash field),
        // but the check is here for completeness and to catch any future
        // config field that carries a stored hash.
        for c in &gateway.consumers {
            for (i, cred) in c.credentials.iter().enumerate() {
                let field = format!("credentials[{i}]");
                // The ApiKey key value is the raw secret, not a stored hash,
                // so it is not checked here. Argon2 appears only in
                // store-managed credential records (the state store), not
                // in config. This check is a no-op for config-declared
                // credentials today, but documents the FIPS restriction
                // for any future config field that carries a stored hash.
                let _ = cred;
                let _ = &field;
            }
        }
    }
}

/// DW-105: post-quantum TLS validation. Enforces three rules:
///
/// 1. **Feature-off warning**: vestigial. PQ hybrid key exchange is
///    compiled into every build (`PqMode::current()` is always
///    `Enabled`), so this warning never fires; the branch remains for
///    the day the kx group is conditionally absent.
/// 2. **FIPS incompatibility**: when `pq: true` is configured AND FIPS
///    mode is active (Enterprise `ent` build), REJECT with an
///    error issue. ML-KEM is not on the FIPS-validated list for
///    aws-lc-rs, so the two must not combine unless both
///    algorithms are on a validated list.
/// 3. **Protocol relevance**: `pq: true` on a passthrough listener (no
///    TLS termination) or an `http1` upstream (no TLS negotiation) is
///    rejected — the kx group list is irrelevant when no TLS is
///    terminated/negotiated.
fn validate_pq(gateway: &Gateway, issues: &mut Vec<ValidationIssue>) {
    use crate::config::{TlsMode, UpstreamProtocol};
    use crate::security::pq::PqMode;

    let pq_feature = PqMode::current();
    let fips_active = crate::security::fips::FipsMode::current().is_enabled();

    // Listeners: check pq: true on each listener's TLS block.
    for l in &gateway.listeners {
        if let Some(tls) = &l.tls {
            if tls.pq {
                // Rule 3: passthrough listeners do not terminate TLS, so
                // the kx group list is irrelevant.
                if tls.mode == TlsMode::Passthrough {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "tls.pq",
                        "pq: true is only meaningful in tls.mode terminate (passthrough does \
                         not terminate TLS, so the kx group list is irrelevant)",
                    ));
                    continue;
                }
                // Rule 2: FIPS incompatibility.
                if fips_active {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "tls.pq",
                        "pq: true is incompatible with FIPS mode: ML-KEM is not on the \
                         FIPS-validated list for aws-lc-rs (the two features must not combine \
                         unless both algorithms are on a validated list)",
                    ));
                    continue;
                }
                // Rule 1: feature-off warning.
                if !pq_feature.is_enabled() {
                    issues.push(issue(
                        "listener",
                        &l.name,
                        "tls.pq",
                        "pq: true is configured but the `pq` cargo feature is OFF — PQ hybrid \
                         key exchange is inert (no kx group is prepended). Build with \
                         --features pq to enable post-quantum TLS",
                    ));
                }
            }
        }
    }

    // Upstreams: check pq: true on each upstream.
    for u in &gateway.upstreams {
        if u.pq {
            // Rule 3: http1/h2c upstreams do not negotiate TLS.
            if matches!(u.protocol, UpstreamProtocol::Http1 | UpstreamProtocol::H2c) {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "pq",
                    "pq: true is only meaningful for https or http2 upstreams (http1 and h2c do \
                     not negotiate TLS, so the kx group list is irrelevant)",
                ));
                continue;
            }
            // Rule 2: FIPS incompatibility.
            if fips_active {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "pq",
                    "pq: true is incompatible with FIPS mode: ML-KEM is not on the \
                     FIPS-validated list for aws-lc-rs (the two features must not combine \
                     unless both algorithms are on a validated list)",
                ));
                continue;
            }
            // Rule 1: feature-off warning.
            if !pq_feature.is_enabled() {
                issues.push(issue(
                    "upstream",
                    &u.name,
                    "pq",
                    "pq: true is configured but the `pq` cargo feature is OFF — PQ hybrid \
                     key exchange is inert (no kx group is prepended). Build with \
                     --features pq to enable post-quantum TLS",
                ));
            }
        }
    }
}

/// DW-111: Extract the SubjectPublicKeyInfo algorithm OID from a
/// certificate file's leaf certificate. Returns the algorithm name
/// ("ed25519", "rsa", "ecdsa") or None when the file cannot be read or
/// the SPKI algorithm cannot be determined. Uses the same DER-walk
/// substrate as `security::tls::spki_of_leaf` (no X.509 parser
/// dependency).
fn spki_algorithm_of_cert_file(path: &str) -> Option<String> {
    use rustls_pki_types::pem::PemObject;

    let certs = rustls_pki_types::CertificateDer::pem_file_iter(path)
        .ok()?
        .collect::<Result<Vec<_>, _>>()
        .ok()?;
    let leaf = certs.first()?;
    spki_algorithm_of_leaf(leaf)
}

/// DW-111: Walk the leaf certificate's DER to the SubjectPublicKeyInfo
/// algorithm OID and map it to a name. Returns "ed25519" for Ed25519,
/// "rsa" for RSA, "ecdsa" for ECDSA P-256/P-384, or None on any
/// structural shortcoming.
fn spki_algorithm_of_leaf(cert: &rustls_pki_types::CertificateDer<'_>) -> Option<String> {
    // Certificate SEQUENCE -> TBSCertificate SEQUENCE.
    let (tag, cert_content, _) = der_elem_local(cert.as_ref())?;
    if tag != 0x30 {
        return None;
    }
    let (tag, tbs, _) = der_elem_local(cert_content)?;
    if tag != 0x30 {
        return None;
    }
    let mut rest = tbs;
    // Optional [0] EXPLICIT version comes before the serial INTEGER.
    if let Some((tag, _, tail)) = der_elem_local(rest) {
        if tag & 0xc0 == 0x80 {
            rest = tail;
        }
    }
    // serialNumber, signature, issuer, validity, subject, then SPKI.
    for _ in 0..5 {
        let (_, _, tail) = der_elem_local(rest)?;
        rest = tail;
    }
    // SPKI: SEQUENCE { algorithm SEQUENCE { OID, params }, subjectPublicKey BIT STRING }
    let (tag, spki_content, _) = der_elem_local(rest)?;
    if tag != 0x30 {
        return None;
    }
    // algorithm SEQUENCE
    let (tag, algo_content, _) = der_elem_local(spki_content)?;
    if tag != 0x30 {
        return None;
    }
    // OID
    let (oid_tag, oid, _) = der_elem_local(algo_content)?;
    if oid_tag != 0x06 {
        return None;
    }
    // Map the algorithm OID to a name.
    // 1.2.840.10045.4.3 = id-ecPublicKey (ECDSA) — but the SPKI algorithm
    // OID for ECDSA keys is 1.2.840.10045.2.1 (id-ecPublicKey). The
    // SIGNATURE algorithm OIDs are different. Here we check the SPKI
    // algorithm OID, which identifies the KEY type.
    //
    // RSA: 1.2.840.113549.1.1.1 (rsaEncryption)
    // EC: 1.2.840.10045.2.1 (id-ecPublicKey)
    // Ed25519: 1.3.101.112 (id-Ed25519)
    if oid == [0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01] {
        // id-ecPublicKey — could be P-256, P-384, or Ed25519 (but Ed25519
        // has its own OID). This is ECDSA.
        Some("ecdsa".to_string())
    } else if oid == [0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01] {
        // rsaEncryption
        Some("rsa".to_string())
    } else if oid == [0x2b, 0x65, 0x70] {
        // id-Ed25519 (1.3.101.112)
        Some("ed25519".to_string())
    } else {
        // Unknown algorithm OID — return the raw bytes as hex for the
        // caller to decide. The FIPS check treats unknown algorithms as
        // allowed (conservative: only known non-approved primitives are
        // denied).
        Some(format!("unknown:{}", hex_oid(oid)))
    }
}

/// DW-111: Encode an OID's content bytes as lowercase hex (for the
/// "unknown" algorithm fallback).
fn hex_oid(bytes: &[u8]) -> String {
    const TABLE: &[u8; 16] = b"0123456789abcdef";
    let mut out = String::with_capacity(bytes.len() * 2);
    for b in bytes {
        out.push(TABLE[usize::from(*b >> 4)] as char);
        out.push(TABLE[usize::from(*b & 0x0f)] as char);
    }
    out
}

/// DW-111: Local copy of the DER element walker (the same logic as
/// `security::tls::der_elem`, duplicated here because `der_elem` is
/// private to that module and `snapshot` must not import `security`
/// internals — the dependency direction is `snapshot <- security`, not
/// the reverse).
fn der_elem_local(buf: &[u8]) -> Option<(u8, &[u8], &[u8])> {
    let tag = *buf.first()?;
    let mut i = 1usize;
    let first = *buf.get(i)?;
    let len = if first < 0x80 {
        i += 1;
        first as usize
    } else {
        let n = (first & 0x7f) as usize;
        if n == 0 || n > 8 {
            return None;
        }
        i += 1;
        let mut l = 0usize;
        for &b in buf.get(i..i + n)? {
            l = (l << 8) | b as usize;
        }
        i += n;
        l
    };
    let end = len.checked_add(i).filter(|end| *end <= buf.len())?;
    Some((tag, &buf[i..end], &buf[end..]))
}

/// Validate a proxy-action path rewrite (shape only; regex COMPILATION is
/// checked in [`compile`], like the regex path-match kind).
fn validate_rewrite(route: &str, rw: &PathRewrite, issues: &mut Vec<ValidationIssue>) {
    match rw {
        PathRewrite::StripPrefix {} => {}
        PathRewrite::ReplacePrefix {
            prefix,
            replacement,
        } => {
            if !prefix.starts_with('/') {
                issues.push(issue(
                    "route",
                    route,
                    "action.rewrite.prefix",
                    format!("replace_prefix prefix '{prefix}' must start with '/'"),
                ));
            }
            if !replacement.is_empty() && !replacement.starts_with('/') {
                issues.push(issue(
                    "route",
                    route,
                    "action.rewrite.replacement",
                    format!(
                        "replace_prefix replacement '{replacement}' must start with '/' or be \
                         empty (empty turns the prefix into the root path)"
                    ),
                ));
            }
        }
        PathRewrite::Regex {
            pattern,
            substitution,
        } => {
            if pattern.is_empty() {
                issues.push(issue(
                    "route",
                    route,
                    "action.rewrite.pattern",
                    "rewrite regex pattern is empty",
                ));
            }
            if substitution.is_empty() {
                issues.push(issue(
                    "route",
                    route,
                    "action.rewrite.substitution",
                    "rewrite substitution is empty (use replace_prefix or strip_prefix to \
                     remove path material)",
                ));
            } else {
                // The substitution must expand to an absolute path or be a
                // pure capture expansion: reject anything that starts with
                // a literal (a relative result cannot be reparsed as a
                // request URI, and the dataplane would silently forward the
                // ORIGINAL path). Whitespace, '?', and '#' would corrupt
                // the path/query split; control characters never belong.
                if !substitution.starts_with(['/', '$', '{']) {
                    issues.push(issue(
                        "route",
                        route,
                        "action.rewrite.substitution",
                        format!(
                            "rewrite substitution '{substitution}' must start with '/' (or a \
                             capture reference like '$1' / '${{name}}') so it expands to an \
                             absolute path"
                        ),
                    ));
                }
                if substitution
                    .chars()
                    .any(|c| c.is_whitespace() || c == '?' || c == '#' || c.is_control())
                {
                    issues.push(issue(
                        "route",
                        route,
                        "action.rewrite.substitution",
                        format!(
                            "rewrite substitution '{substitution}' must not contain \
                             whitespace, '?', '#', or control characters"
                        ),
                    ));
                }
            }
        }
    }
}

/// Validate a mock action (DW-047): status in 100..=599, delay_ms in
/// 0..=30000, exactly one of body/body_file (or neither), body_file
/// exists and is readable, and header names/values are buildable.
fn validate_mock(route: &str, mock: &crate::config::MockAction, issues: &mut Vec<ValidationIssue>) {
    if !(100..=599).contains(&mock.status) {
        issues.push(issue(
            "route",
            route,
            "action.mock.status",
            format!(
                "mock status {} is not a valid HTTP status (100..=599)",
                mock.status
            ),
        ));
    }
    if let Some(delay) = mock.delay_ms {
        if delay > 30000 {
            issues.push(issue(
                "route",
                route,
                "action.mock.delay_ms",
                format!("mock delay_ms {delay} is out of range: must be 0..=30000"),
            ));
        }
    }
    if mock.body.is_some() && mock.body_file.is_some() {
        issues.push(issue(
            "route",
            route,
            "action.mock",
            "mock action sets both 'body' and 'body_file'; set at most one \
             (use body for an inline string, body_file for a fixture file)",
        ));
    }
    for (name, value) in &mock.headers {
        if hyper::header::HeaderName::from_bytes(name.as_bytes()).is_err() {
            issues.push(issue(
                "route",
                route,
                "action.mock.headers",
                format!("mock header name '{name}' is not a valid HTTP header name"),
            ));
        }
        if hyper::header::HeaderValue::from_str(value.as_str()).is_err() {
            issues.push(issue(
                "route",
                route,
                "action.mock.headers",
                format!(
                    "mock header value for '{name}' contains characters that \
                     cannot appear in an HTTP header value"
                ),
            ));
        }
    }
    if let Some(path) = &mock.body_file {
        if path.trim().is_empty() {
            issues.push(issue(
                "route",
                route,
                "action.mock.body_file",
                "mock body_file path is empty",
            ));
        } else if std::fs::read(path).is_err() {
            issues.push(issue(
                "route",
                route,
                "action.mock.body_file",
                format!("mock body_file '{path}' is not a readable file"),
            ));
        }
    }
}

/// Validate a JSON schema (DW-047): type names must be known, numeric
/// bounds non-negative, and the schema recursively well-formed. Unknown
/// keywords are ignored (forward compatibility).
fn validate_json_schema(
    route: &str,
    field: &str,
    schema: &crate::config::BodySchema,
    issues: &mut Vec<ValidationIssue>,
) {
    if let Some(t) = &schema.r#type {
        if !matches!(
            t.as_str(),
            "object" | "array" | "string" | "number" | "integer" | "boolean" | "null"
        ) {
            issues.push(issue(
                "route",
                route,
                field,
                format!("json schema type '{t}' is not a known JSON type"),
            ));
        }
    }
    if let Some(min) = schema.min_length {
        if min > u64::MAX / 4 {
            // Guard against absurd values; the practical cap is the
            // route's body limit, enforced at request time.
        }
    }
    for (name, child) in &schema.properties {
        validate_json_schema(route, &format!("{field}.properties[{name}]"), child, issues);
    }
    if let Some(items) = &schema.items {
        validate_json_schema(route, &format!("{field}.items"), items, issues);
    }
    if let Some(ap) = &schema.additional_properties {
        if let crate::config::AdditionalProperties::Schema(s) = ap.as_ref() {
            validate_json_schema(route, &format!("{field}.additionalProperties"), s, issues);
        }
    }
}

/// Compiled route structures for one snapshot. Path-only lookup (v1); host,
/// method, header, query, and cookie matching are applied by the dataplane
/// after path resolution (see `proxy::route_applies`).
///
/// # Route precedence (canonical spec, DW-010)
///
/// A request path resolves to AT MOST ONE route, chosen across three
/// path-match kinds in a fixed order:
///
/// 1. **Exact** — `matchit` radix templates (`type: exact`). Within this
///    kind, `matchit`'s specificity rules apply: static segments beat
///    parameters (`/users/active` before `/users/{id}`). Templates that
///    would conflict are rejected at compile time
///    ([`CompileError::RouteConflict`]), so there is no ambiguity here.
/// 2. **Regex** — a shared `RegexSet` over all `type: regex` routes. When
///    several patterns match, the FIRST-DECLARED route in config order
///    wins (`RegexSet` returns matches in insertion order and lookup takes
///    the first).
/// 3. **Prefix** — byte-prefix matching (no segment boundary: `/v1` also
///    matches `/v1anything`). The LONGEST matching prefix wins; equal-length
///    ties go to the FIRST-DECLARED route (strict `>` comparison keeps the
///    earlier entry).
///
/// Cross-kind precedence is therefore: exact beats regex beats prefix,
/// regardless of declaration order and regardless of how "specific" a
/// regex or prefix looks. A shorter exact template beats a longer regex.
/// The prefix stored is the configured value with trailing `/` trimmed,
/// so `/v1/` and `/v1` are the same prefix and equal-length ties are
/// possible (first declared wins).
///
/// Non-path criteria (host, method, headers, query, cookies) are applied
/// AFTER this resolution; a criteria miss does NOT fall through to the
/// next candidate — the request is unmatched (404 in v1).
///
/// PERF-03 (#205): prefix lookup uses a radix trie (`PrefixTrie`) for
/// O(k) longest-prefix-match where k is the path length, instead of the
/// O(n) linear scan over all prefix routes.
///
/// PERF-03 (#205): A radix trie for longest-prefix matching. Each
/// node stores the route indices whose prefix ends at this node
/// (empty for internal nodes) and children keyed by the next byte.
/// Lookup traverses the trie following the path bytes, recording the
/// last node carrying indices — that is the longest prefix match.
///
/// O(k) lookup where k is the path length, replacing the previous
/// O(n) linear scan over all prefix routes.
#[derive(Debug, Default)]
struct PrefixTrie {
    /// Route indices of prefixes ending at this node, in declaration
    /// order. Empty means this node is internal (no prefix ends here,
    /// but longer prefixes pass through it). More than one entry means
    /// duplicate configured prefixes — each is a distinct fall-through
    /// candidate for `find_candidates` (DP-06), while `longest_match`
    /// takes the first entry (first-declared wins).
    route_idxs: Vec<usize>,
    /// Child nodes keyed by the next byte of the prefix.
    children: std::collections::HashMap<u8, Box<PrefixTrie>>,
}

impl PrefixTrie {
    fn new() -> Self {
        Self::default()
    }

    /// Insert a prefix and its route index. Every route declared with
    /// this exact prefix is kept, in declaration order: the candidate
    /// fall-through walks all of them (the first-declared-wins tie rule
    /// for `find_full` is applied by `longest_match` reading the first
    /// entry).
    fn insert(&mut self, prefix: &str, idx: usize) {
        let mut node = self;
        for &byte in prefix.as_bytes() {
            node = node
                .children
                .entry(byte)
                .or_insert_with(|| Box::new(PrefixTrie::new()));
        }
        node.route_idxs.push(idx);
    }

    /// Longest-prefix-match: traverse the trie following the path
    /// bytes, recording the last node with a route index. Returns
    /// the route index of the longest matching prefix, or `None`.
    fn longest_match(&self, path: &str) -> Option<usize> {
        let mut node = self;
        let mut best = node.route_idxs.first().copied();
        for &byte in path.as_bytes() {
            match node.children.get(&byte) {
                Some(child) => {
                    node = child;
                    if let Some(&idx) = node.route_idxs.first() {
                        best = Some(idx);
                    }
                }
                None => break,
            }
        }
        best
    }

    /// Every prefix match along the path, ONE SLICE PER MATCHED NODE,
    /// in increasing-depth (= increasing prefix length) order. The
    /// root is included first (an empty configured prefix — `/`
    /// trimmed — matches every path), so a caller wanting longest-first
    /// reverses the NODE order while keeping each node's slice in
    /// declaration order: the flat Vec cannot simply be reversed, or
    /// duplicate configured prefixes at one node would flip their
    /// fall-through order.
    fn collect_matches(&self, path: &str) -> Vec<&[usize]> {
        let mut node = self;
        let mut out = Vec::new();
        if !node.route_idxs.is_empty() {
            out.push(&node.route_idxs[..]);
        }
        for &byte in path.as_bytes() {
            match node.children.get(&byte) {
                Some(child) => {
                    node = child;
                    if !node.route_idxs.is_empty() {
                        out.push(&node.route_idxs[..]);
                    }
                }
                None => break,
            }
        }
        out
    }
}

#[derive(Debug)]
pub struct RouteTable {
    exact: matchit::Router<usize>,
    /// (prefix, route index) for prefix-kind routes; longest prefix wins.
    /// Kept for backward compatibility and Debug; the trie is the
    /// primary lookup structure (PERF-03, #205).
    #[allow(dead_code)]
    prefixes: Vec<(String, usize)>,
    /// PERF-03 (#205): radix trie for O(k) longest-prefix-match.
    prefix_trie: PrefixTrie,
    regex_set: regex::RegexSet,
    /// Route index per RegexSet member, in insertion order.
    regex_indices: Vec<usize>,
    /// Specificity score per RegexSet member (DP-06, #254): higher =
    /// more specific. When multiple regexes match, the most specific
    /// one wins instead of the first declared. Scored by literal
    /// character count in the pattern.
    regex_scores: Vec<u32>,
    /// Compiled `path_rewrite.regex` pattern per route index (None where
    /// the action carries no regex rewrite). Validation guarantees these
    /// compiled at config-compile time, never at request time.
    rewrite_regexes: Vec<Option<regex::Regex>>,
    /// Precompiled `path_rewrite.regex.substitution` per route index
    /// (PERF-04, #206): the `$1`/`${name}` syntax is parsed into
    /// literal segments and capture references ONCE at compile time so
    /// the request path never re-parses the substitution string. `None`
    /// where the route carries no regex rewrite.
    rewrite_substitutions: Vec<Option<CompiledSubstitution>>,
    /// Precompiled CORS origin matcher per route index (DW-027): `None`
    /// where the route carries no `cors` block, mirroring
    /// `Route::cors` exactly so the proxy's config read and matcher
    /// lookup stay in lockstep.
    cors_origins: Vec<Option<crate::config::CompiledCorsOrigins>>,
    /// Precompiled compression content-type filter per route index
    /// (DW-027), mirroring `Route::compression` the same way.
    compression_types: Vec<Option<crate::config::CompiledContentTypeFilter>>,
    /// Precompiled deprecation header values per route index (DW-048),
    /// mirroring `Route::deprecation` the same way: HTTP-dates are
    /// parsed once here, never per response.
    deprecations: Vec<Option<crate::config::CompiledDeprecation>>,
    /// Normalized `match.accept` media type per route index (DW-048),
    /// mirroring `Route::r#match.accept` exactly (`None` = no
    /// criterion). Normalizing here — trim + lowercase via the shared
    /// `config::versioning` grammar — keeps the raw config string out
    /// of the request path, so a padded or mixed-case spelling matches
    /// exactly like its canonical form. Validation guarantees every
    /// configured value normalizes; a `None` for a configured one is
    /// the same unreachable-skip contract as the compilations above
    /// (`compile` has already run validation by then).
    accept_media_types: Vec<Option<String>>,
    /// Precompiled request JSON body transforms per route index
    /// (DW-028), mirroring `routes[idx].transforms.request.body.json`
    /// exactly: pointers parsed once here, never per request. Header
    /// and query ops carry no parseable grammar (names are checked by
    /// validation and applied verbatim), so they deliberately have no
    /// compiled form — only the JSON pointers need precompute.
    request_body_ops: Vec<Option<crate::config::transforms::CompiledJsonTransform>>,
    /// Precompiled response JSON body transforms per route index
    /// (DW-028), same mirroring as `request_body_ops`.
    response_body_ops: Vec<Option<crate::config::transforms::CompiledJsonTransform>>,
    /// Precompiled response field masking policies per route index
    /// (DW-029), mirroring `routes[idx].masking`: pointers parsed once
    /// here; the per-request union with the consumer's groups is
    /// resolved at apply time (group membership is per-request state).
    masking: Vec<Option<crate::config::transforms::CompiledMasking>>,
    /// Precompiled response-cache policies per route index (DW-037),
    /// mirroring `routes[idx].cache` with the policy-derived vary folds
    /// (`match.accept` -> `Accept`, `cors` -> `Origin`) resolved once.
    caches: Vec<Option<std::sync::Arc<crate::config::cache::CompiledRouteCache>>>,
    /// Preloaded mock response bodies per route index (DW-047): the
    /// bytes of a mock action's `body_file`, read once at compile time
    /// so the request path never touches the filesystem. `None` where
    /// the route carries no mock action or uses an inline `body`.
    mock_bodies: Vec<Option<bytes::Bytes>>,
    /// Effective security headers per route index (SEC-09, #213): the
    /// route's own `security_headers` block when present, else the
    /// gateway-level `default_security_headers` when the route has
    /// not opted out, else `None`. Computed once at compile time so
    /// the request path never re-merges.
    effective_security_headers: Vec<Option<crate::config::transforms::SecurityHeaders>>,
}

impl RouteTable {
    fn empty() -> Self {
        RouteTable {
            exact: matchit::Router::new(),
            prefixes: Vec::new(),
            prefix_trie: PrefixTrie::new(),
            regex_set: regex::RegexSet::empty(),
            regex_indices: Vec::new(),
            regex_scores: Vec::new(),
            rewrite_regexes: Vec::new(),
            rewrite_substitutions: Vec::new(),
            cors_origins: Vec::new(),
            compression_types: Vec::new(),
            deprecations: Vec::new(),
            accept_media_types: Vec::new(),
            request_body_ops: Vec::new(),
            response_body_ops: Vec::new(),
            masking: Vec::new(),
            caches: Vec::new(),
            mock_bodies: Vec::new(),
            effective_security_headers: Vec::new(),
        }
    }

    /// Resolve a request path to a route index. Precedence: exact template,
    /// then most-specific regex match, then longest prefix. `None` means no
    /// route.
    pub fn find(&self, path: &str) -> Option<usize> {
        self.find_full(path).map(|(idx, _)| idx)
    }

    /// Like [`RouteTable::find`] but also returns the path parameters
    /// captured by an exact-template match (`{name}` segments), as
    /// (name, value) pairs in template order. Regex- and prefix-kind
    /// routes return an empty parameter list.
    pub fn find_full(&self, path: &str) -> Option<(usize, Vec<(String, String)>)> {
        if let Ok(m) = self.exact.at(path) {
            let params = m
                .params
                .iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect();
            return Some((*m.value, params));
        }
        // DP-06 (#254): when multiple regexes match, choose the most
        // specific one (highest score), not the first declared. Ties
        // break by declaration order (stable sort).
        let matches = self.regex_set.matches(path);
        let mut best: Option<(u32, usize)> = None; // (score, regex_set_index)
        for i in matches.iter() {
            let score = self.regex_scores[i];
            if best.is_none_or(|(s, _)| score > s) {
                best = Some((score, i));
            }
        }
        if let Some((_, i)) = best {
            return Some((self.regex_indices[i], Vec::new()));
        }
        // PERF-03 (#205): O(k) trie lookup replaces O(n) linear scan.
        if let Some(idx) = self.prefix_trie.longest_match(path) {
            return Some((idx, Vec::new()));
        }
        None
    }

    /// Yield all candidate route indices for a path in precedence order
    /// (DP-06, #254): exact, then regex matches by specificity (highest
    /// first), then prefix matches by longest prefix. Each candidate
    /// also carries its path parameters (populated only for exact
    /// matches). The caller is expected to test non-path criteria
    /// (`route_applies`) on each candidate and stop at the first that
    /// fully matches -- this is the "fall-through" behavior.
    pub fn find_candidates(&self, path: &str) -> Vec<(usize, Vec<(String, String)>)> {
        let mut candidates = Vec::new();

        // 1. Exact match (at most one).
        if let Ok(m) = self.exact.at(path) {
            let params = m
                .params
                .iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect();
            candidates.push((*m.value, params));
        }

        // 2. Regex matches, most specific first.
        let matches = self.regex_set.matches(path);
        let mut regex_matches: Vec<(u32, usize)> = Vec::new();
        for i in matches.iter() {
            regex_matches.push((self.regex_scores[i], i));
        }
        // Sort by score descending; stable sort preserves declaration
        // order for ties. PERF: skipped entirely for the 0/1-match cases
        // (the overwhelming majority — sorting one element is a no-op).
        if regex_matches.len() > 1 {
            regex_matches.sort_by(|a, b| b.0.cmp(&a.0));
        }
        for (_, i) in regex_matches {
            candidates.push((self.regex_indices[i], Vec::new()));
        }

        // 3. Prefix matches, longest first. PERF-03 (#205): the trie
        // walk visits only nodes along the path — O(k) in the path
        // length — replacing the O(n) scan-and-sort over every
        // configured prefix. The walk yields matched nodes in
        // increasing-depth order; reversing the node order gives
        // longest-first while each node's slice stays in declaration
        // order (duplicate configured prefixes fall through in
        // declaration order, matching the old stable sort's output).
        for idxs in self.prefix_trie.collect_matches(path).iter().rev() {
            for &idx in *idxs {
                candidates.push((idx, Vec::new()));
            }
        }

        candidates
    }

    /// The compiled rewrite regex for `idx`, if the route's proxy action
    /// carries a `path_rewrite.regex`.
    pub fn rewrite_regex(&self, idx: usize) -> Option<&regex::Regex> {
        self.rewrite_regexes.get(idx).and_then(|r| r.as_ref())
    }

    /// The precompiled substitution template for `idx` (PERF-04, #206),
    /// if the route's proxy action carries a `path_rewrite.regex`.
    pub fn rewrite_substitution(&self, idx: usize) -> Option<&CompiledSubstitution> {
        self.rewrite_substitutions.get(idx).and_then(|s| s.as_ref())
    }

    /// The precompiled CORS origin matcher for route `idx` (`None`: the
    /// route carries no `cors` block — exactly mirroring
    /// `gateway().routes[idx].cors`).
    pub fn cors_origins(&self, idx: usize) -> Option<&crate::config::CompiledCorsOrigins> {
        self.cors_origins.get(idx).and_then(|o| o.as_ref())
    }

    /// The precompiled compression content-type filter for route `idx`
    /// (`None`: the route carries no `compression` block — exactly
    /// mirroring `gateway().routes[idx].compression`).
    pub fn compression_types(
        &self,
        idx: usize,
    ) -> Option<&crate::config::CompiledContentTypeFilter> {
        self.compression_types.get(idx).and_then(|t| t.as_ref())
    }

    /// The precompiled deprecation header values for route `idx` (`None`:
    /// the route carries no `deprecation` block — exactly mirroring
    /// `gateway().routes[idx].deprecation`).
    pub fn deprecation(&self, idx: usize) -> Option<&crate::config::CompiledDeprecation> {
        self.deprecations.get(idx).and_then(|d| d.as_ref())
    }

    /// The normalized `match.accept` media type for route `idx` (`None`:
    /// the route carries no accept criterion — exactly mirroring
    /// `gateway().routes[idx].r#match.accept`). This is the comparison
    /// key the proxy's Accept criterion must use, never the raw config
    /// string.
    pub fn accept_media_type(&self, idx: usize) -> Option<&str> {
        self.accept_media_types.get(idx).and_then(|a| a.as_deref())
    }

    /// The precompiled REQUEST JSON body transform for route `idx`
    /// (`None`: the route transforms no request bodies — exactly
    /// mirroring `gateway().routes[idx].transforms.request.body`).
    pub fn request_body_ops(
        &self,
        idx: usize,
    ) -> Option<&crate::config::transforms::CompiledJsonTransform> {
        self.request_body_ops.get(idx).and_then(|t| t.as_ref())
    }

    /// The precompiled RESPONSE JSON body transform for route `idx`
    /// (`None`: the route transforms no response bodies — exactly
    /// mirroring `gateway().routes[idx].transforms.response.body`).
    pub fn response_body_ops(
        &self,
        idx: usize,
    ) -> Option<&crate::config::transforms::CompiledJsonTransform> {
        self.response_body_ops.get(idx).and_then(|t| t.as_ref())
    }

    /// The precompiled response field masking policy for route `idx`
    /// (`None`: the route masks nothing — exactly mirroring
    /// `gateway().routes[idx].masking`).
    pub fn masking(&self, idx: usize) -> Option<&crate::config::transforms::CompiledMasking> {
        self.masking.get(idx).and_then(|m| m.as_ref())
    }

    /// The precompiled response-cache policy for route `idx` (`None`:
    /// the route's responses are never cached — exactly mirroring
    /// `gateway().routes[idx].cache`, with the policy-derived vary
    /// folds already resolved).
    pub fn cache(
        &self,
        idx: usize,
    ) -> Option<&std::sync::Arc<crate::config::cache::CompiledRouteCache>> {
        self.caches.get(idx).and_then(|c| c.as_ref())
    }

    /// The preloaded mock response body for route `idx` (DW-047,
    /// `None`: the route carries no mock `body_file` — exactly
    /// mirroring `gateway().routes[idx].action.mock.body_file`).
    pub fn mock_body(&self, idx: usize) -> Option<&bytes::Bytes> {
        self.mock_bodies.get(idx).and_then(|b| b.as_ref())
    }

    /// The effective security headers for a route (SEC-09, #213): the
    /// route's own `security_headers` block when present, else the
    /// gateway-level `default_security_headers` when the route has
    /// not opted out, else `None`.
    pub fn effective_security_headers(
        &self,
        idx: usize,
    ) -> Option<&crate::config::transforms::SecurityHeaders> {
        self.effective_security_headers
            .get(idx)
            .and_then(|sh| sh.as_ref())
    }
}

/// A precompiled `path_rewrite.regex.substitution` (PERF-04, #206).
///
/// The `$1` / `${name}` substitution syntax is parsed ONCE at snapshot
/// compile time into a list of segments — literal text or a named/numeric
/// reference — so the per-request rewrite path never re-parses the
/// substitution string. Each segment is expanded against the regex
/// captures (and the route's `{param}` template captures) in a single
/// pass with a pre-sized `String`.
#[derive(Debug, Clone)]
pub struct CompiledSubstitution {
    segments: Vec<SubstSegment>,
    /// The precomputed output capacity: sum of all literal segment
    /// lengths, so the result `String` is allocated once at the right
    /// size (capture expansions add to it, but the literal baseline is
    /// the dominant cost for most templates).
    capacity: usize,
}

/// One segment of a compiled substitution template.
#[derive(Debug, Clone)]
enum SubstSegment {
    /// Literal text copied verbatim.
    Literal(String),
    /// A numeric capture-group reference (`$1`, `${1}`).
    Numeric(usize),
    /// A named reference (`$name`, `${name}`): resolved against the
    /// regex's named capture groups first, then the route's `{param}`
    /// template captures.
    Named(String),
}

impl CompiledSubstitution {
    /// Parse a `$1` / `${name}` substitution string into segments.
    /// Mirrors the grammar of `expand_substitution` in
    /// `dataplane/proxy.rs` exactly: `$` followed by digits, an
    /// identifier, or `{...}`; a lone `$` (end of string or followed
    /// by a non-identifier char) is kept literally.
    pub fn compile(substitution: &str) -> Self {
        let mut segments = Vec::new();
        let mut capacity = 0;
        let mut rest = substitution;
        let mut literal = String::new();

        while let Some(dollar) = rest.find('$') {
            literal.push_str(&rest[..dollar]);
            let after = &rest[dollar + 1..];
            if after.is_empty() {
                literal.push('$');
                rest = after;
                break;
            }
            if let Some(braced) = after.strip_prefix('{') {
                match braced.find('}') {
                    Some(end) => {
                        if !literal.is_empty() {
                            capacity += literal.len();
                            segments.push(SubstSegment::Literal(std::mem::take(&mut literal)));
                        }
                        let name = &braced[..end];
                        if let Ok(i) = name.parse::<usize>() {
                            segments.push(SubstSegment::Numeric(i));
                        } else {
                            segments.push(SubstSegment::Named(name.to_string()));
                        }
                        rest = &braced[end + 1..];
                    }
                    None => {
                        literal.push('$');
                        rest = after;
                    }
                }
            } else {
                let end = after
                    .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
                    .unwrap_or(after.len());
                if end == 0 {
                    literal.push('$');
                    rest = after;
                } else {
                    if !literal.is_empty() {
                        capacity += literal.len();
                        segments.push(SubstSegment::Literal(std::mem::take(&mut literal)));
                    }
                    let name = &after[..end];
                    if let Ok(i) = name.parse::<usize>() {
                        segments.push(SubstSegment::Numeric(i));
                    } else {
                        segments.push(SubstSegment::Named(name.to_string()));
                    }
                    rest = &after[end..];
                }
            }
        }
        literal.push_str(rest);
        if !literal.is_empty() {
            capacity += literal.len();
            segments.push(SubstSegment::Literal(literal));
        }

        CompiledSubstitution { segments, capacity }
    }

    /// Expand against regex captures and route `{param}` captures.
    /// The result `String` is pre-sized to the compiled literal
    /// capacity, so the common case (a template with mostly literal
    /// text and a few short capture refs) allocates exactly once.
    pub fn expand(&self, caps: &regex::Captures<'_>, params: &[(String, String)]) -> String {
        let mut out = String::with_capacity(self.capacity);
        for seg in &self.segments {
            match seg {
                SubstSegment::Literal(s) => out.push_str(s),
                SubstSegment::Numeric(i) => {
                    if let Some(m) = caps.get(*i) {
                        out.push_str(m.as_str());
                    }
                }
                SubstSegment::Named(name) => {
                    if let Some(m) = caps.name(name) {
                        out.push_str(m.as_str());
                    } else if let Some((_, v)) = params.iter().find(|(n, _)| n == name) {
                        out.push_str(v);
                    }
                }
            }
        }
        out
    }

    /// The precomputed literal capacity (PERF-04, #206): the sum of
    /// all literal segment lengths, so a caller building a larger
    /// string around the expansion can pre-size its own output.
    pub fn capacity(&self) -> usize {
        self.capacity
    }
}

/// Output of the pure compile step: everything a [`Snapshot`] needs except
/// its generation id, which is assigned at publish time.
#[derive(Debug)]
pub struct Compiled {
    gateway: Arc<Gateway>,
    routes: Arc<RouteTable>,
    content_hash: u64,
    /// USA-12 (#233): the developer portal, built at compile time when
    /// `lifecycle.portal.enabled` is true. `None` when the portal is
    /// disabled or no lifecycle config is present.
    portal: Option<crate::lifecycle::DevPortal>,
}

impl Compiled {
    pub fn gateway(&self) -> &Gateway {
        &self.gateway
    }

    pub fn route_table(&self) -> &RouteTable {
        &self.routes
    }

    pub fn content_hash(&self) -> u64 {
        self.content_hash
    }

    /// USA-12 (#233): the developer portal, when built.
    pub fn portal(&self) -> Option<&crate::lifecycle::DevPortal> {
        self.portal.as_ref()
    }
}

/// Immutable, fully compiled configuration generation, cheap to share.
#[derive(Debug)]
pub struct Snapshot {
    generation: u64,
    content_hash: u64,
    gateway: Arc<Gateway>,
    routes: Arc<RouteTable>,
    /// USA-12 (#233): the developer portal, when built.
    portal: Option<crate::lifecycle::DevPortal>,
}

impl Snapshot {
    /// The empty generation-0 snapshot a cold gateway serves before any
    /// config has been published.
    pub fn empty() -> Self {
        Snapshot {
            generation: 0,
            content_hash: 0,
            gateway: Arc::new(Gateway {
                version: 1,
                trusted_proxies: vec![],
                listeners: Vec::new(),
                routes: Vec::new(),
                services: Vec::new(),
                upstreams: Vec::new(),
                consumers: Vec::new(),
                policies: Vec::new(),
                global_policies: Vec::new(),
                authorization: None,
                default_security_headers: None,
                waf: None,
                max_concurrent_requests: None,
                load_shed_dry_run: false,
                jwt_providers: Vec::new(),
                admin: None,
                allow_empty_routes: false,
                hmac_auth: None,
                webhooks: Vec::new(),
                analytics: None,
                analytics_stream: None,
                geoip: None,
                admission_queue: None,
                mtls_consumer_mapping: None,
                mtls_forward_headers: None,
                license: None,
                oidc_providers: Vec::new(),
                redis_rate_limiter: None,
                redis_quotas: None,
                redis_cache: None,
                config_convergence: None,
                plugins: Vec::new(),
                filter_chain: None,
                plugin_registry: None,
                ai: None,
                fleet: None,
                mesh: None,
                lifecycle: None,
                ssrf_filter: None,
            }),
            routes: Arc::new(RouteTable::empty()),
            portal: None,
        }
    }

    pub fn generation(&self) -> u64 {
        self.generation
    }

    /// Build a generation-0 snapshot from a [`Compiled`] value (DW-102:
    /// replay and other offline tools that need a snapshot without
    /// publishing through [`ConfigState`]). The generation id is 0
    /// (replay does not need a real generation id; it only reads the
    /// compiled route table and gateway).
    pub fn from_compiled(compiled: Compiled) -> Self {
        Snapshot {
            generation: 0,
            content_hash: compiled.content_hash,
            gateway: compiled.gateway,
            routes: compiled.routes,
            portal: compiled.portal,
        }
    }

    pub fn content_hash(&self) -> u64 {
        self.content_hash
    }

    pub fn gateway(&self) -> &Gateway {
        &self.gateway
    }

    pub fn route_table(&self) -> &RouteTable {
        &self.routes
    }

    /// USA-12 (#233): the developer portal, when built.
    pub fn portal(&self) -> Option<&crate::lifecycle::DevPortal> {
        self.portal.as_ref()
    }

    /// Convenience: resolve a path to the matching route, if any.
    pub fn match_route(&self, path: &str) -> Option<&Route> {
        self.routes.find(path).map(|i| &self.gateway.routes[i])
    }
}

/// Identity of a successfully published snapshot, for logs/metrics.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SnapshotInfo {
    pub generation: u64,
    /// Per-process change-detection token over the normalized config.
    /// NOT stable across Rust versions (SipHash internals may change) and
    /// NOT a content digest; never persist it, compare it across
    /// processes/versions, or treat it as cryptographic integrity.
    pub content_hash: u64,
    pub route_count: usize,
}

/// The single hashing step behind both the whole-gateway content hash
/// in [`compile`] and the per-entity [`entity_content_hash`]: a
/// `DefaultHasher` (SipHash-1-3) over a normalized YAML serialization.
fn normalized_hash(yaml: &str) -> u64 {
    let mut hasher = DefaultHasher::new();
    yaml.hash(&mut hasher);
    hasher.finish()
}

/// Per-entity content hash: the entity's normalized YAML serialization
/// (stable field order, defaulted-empty fields omitted — the same
/// normalization `gateway_to_yaml` applies to a whole [`Gateway`])
/// through the same `DefaultHasher` as the snapshot content hash. Two
/// entities of one kind hash equal exactly when their normalized
/// serializations are equal, so source key order and omitted defaults
/// do not affect the result. Same caveats as
/// [`SnapshotInfo::content_hash`]: a per-process change-detection
/// token, not stable across Rust versions, not a content digest.
pub fn entity_content_hash<T: serde::Serialize>(entity: &T) -> Result<u64, String> {
    let yaml =
        serde_yaml_ng::to_string(entity).map_err(|e| format!("normalization failed: {e}"))?;
    Ok(normalized_hash(&yaml))
}

/// Compute a specificity score for a regex pattern (DP-06, #254).
///
/// The score is the count of literal (non-meta) characters in the
/// pattern. A pattern like `/x/[0-9]+` scores higher than `/x/`
/// because it has more literal characters and is therefore more
/// specific. This is a simple heuristic that avoids pulling in a
/// regex AST crate; it is sufficient for the common case of
/// distinguishing broad vs. narrow path patterns.
///
/// Meta characters counted as non-literal: `\`, `.`, `*`, `+`, `?`,
/// `(`, `)`, `[`, `]`, `{`, `}`, `|`, `^`, `$`. Escaped characters
/// (`\.`) count the escaped char as literal but the backslash as
/// non-literal, which is the right relative ordering.
fn regex_specificity_score(pattern: &str) -> u32 {
    pattern
        .chars()
        .filter(|c| {
            !matches!(
                c,
                '\\' | '.' | '*' | '+' | '?' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '^' | '$'
            )
        })
        .count() as u32
}

/// Pure compile: validated [`Gateway`] -> [`Compiled`]. Fails with
/// [`CompileError::Validation`] on semantic issues, or with
/// [`CompileError::InvalidRegex`] / [`CompileError::RouteConflict`] when
/// schema-valid config still cannot compile.
pub fn compile(gateway: &Gateway) -> Result<Compiled, CompileError> {
    let issues = validate(gateway);
    if !issues.is_empty() {
        return Err(CompileError::Validation(issues));
    }

    let mut exact = matchit::Router::new();
    let mut prefixes = Vec::new();
    let mut prefix_trie = PrefixTrie::new();
    let mut regex_patterns = Vec::new();
    let mut regex_indices = Vec::new();
    let mut regex_scores = Vec::new();
    let mut rewrite_regexes: Vec<Option<regex::Regex>> = vec![None; gateway.routes.len()];
    let mut rewrite_substitutions: Vec<Option<CompiledSubstitution>> =
        vec![None; gateway.routes.len()];

    for (idx, route) in gateway.routes.iter().enumerate() {
        let path = &route.r#match.path;
        match path.kind {
            PathMatchKind::Exact => {
                exact
                    .insert(&path.value, idx)
                    .map_err(|e| CompileError::RouteConflict {
                        route: route.name.clone(),
                        pattern: path.value.clone(),
                        message: e.to_string(),
                    })?;
            }
            PathMatchKind::Prefix => {
                let prefix = path.value.trim_end_matches('/').to_string();
                // PERF-03 (#205): insert into the trie for O(k) lookup.
                // Duplicate prefixes each keep their own entry in the
                // node (declaration order) so the candidate fall-through
                // (find_candidates) offers all of them; `find_full`'s
                // first-declared-wins tie rule reads the node's first
                // entry. The Vec mirrors the trie for Debug output only.
                prefix_trie.insert(&prefix, idx);
                prefixes.push((prefix, idx));
            }
            PathMatchKind::Regex => {
                regex::Regex::new(&path.value).map_err(|e| CompileError::InvalidRegex {
                    route: route.name.clone(),
                    pattern: path.value.clone(),
                    message: e.to_string(),
                })?;
                // DP-06 (#254): score the regex pattern for specificity.
                // Higher score = more literal characters = more specific.
                // When multiple regexes match a path, the most specific
                // one wins instead of the first declared.
                regex_scores.push(regex_specificity_score(&path.value));
                regex_patterns.push(path.value.clone());
                regex_indices.push(idx);
            }
        }
        if let RouteAction::Proxy {
            rewrite:
                Some(PathRewrite::Regex {
                    pattern,
                    substitution,
                }),
        } = &route.action
        {
            let compiled = regex::Regex::new(pattern).map_err(|e| CompileError::InvalidRegex {
                route: route.name.clone(),
                pattern: pattern.clone(),
                message: e.to_string(),
            })?;
            rewrite_regexes[idx] = Some(compiled);
            rewrite_substitutions[idx] = Some(CompiledSubstitution::compile(substitution));
        }
    }

    let regex_set =
        regex::RegexSet::new(regex_patterns).map_err(|e| CompileError::Internal(e.to_string()))?;

    let yaml = gateway_to_yaml(gateway)
        .map_err(|e| CompileError::Internal(format!("normalization failed: {e}")))?;
    let content_hash = normalized_hash(&yaml);

    // DW-027 edge-policy matching state, precompiled per route index in
    // lockstep with `Route::cors` / `Route::compression` (built from the
    // same route list, so lookups mirror the config the proxy reads):
    // normalized CORS origins and lowercased content-type prefixes are
    // computed once here instead of on every request.
    let cors_origins = gateway
        .routes
        .iter()
        .map(|r| {
            r.cors
                .as_ref()
                .map(crate::config::CompiledCorsOrigins::compile)
        })
        .collect();
    let compression_types = gateway
        .routes
        .iter()
        .map(|r| {
            r.compression
                .as_ref()
                .map(crate::config::CompiledContentTypeFilter::compile)
        })
        .collect();
    // DW-048: the deprecation header values, parsed from their config
    // HTTP-dates once here (validation guarantees they parse; the
    // filter_map fallback documents the same unreachable-skip contract
    // as the CORS/compression compilations above).
    let deprecations = gateway
        .routes
        .iter()
        .map(|r| {
            r.deprecation
                .as_ref()
                .map(crate::config::CompiledDeprecation::compile)
        })
        .collect();
    // DW-048: the accept criterion's comparison key, normalized once
    // here instead of on every request — validation guarantees every
    // configured value normalizes, so the None fallback is unreachable
    // (the same skip contract as the compilations above). Without this
    // the raw config string reached the hot path, and a padded
    // `match.accept` published cleanly only to 404 every request.
    let accept_media_types = gateway
        .routes
        .iter()
        .map(|r| {
            r.r#match
                .accept
                .as_deref()
                .and_then(crate::config::versioning::normalize_media_type)
        })
        .collect();
    // DW-028: the JSON body transforms' pointers, parsed once here
    // (validation guarantees they parse; the same unreachable-skip
    // contract as the compilations above). Header and query ops have
    // no parseable grammar and deliberately ride the config value.
    let request_body_ops = gateway
        .routes
        .iter()
        .map(|r| {
            r.transforms
                .as_ref()
                .and_then(|t| t.request.as_ref())
                .and_then(|req| req.body.as_ref())
                .map(|b| crate::config::transforms::CompiledJsonTransform::compile(&b.json))
        })
        .collect();
    let response_body_ops = gateway
        .routes
        .iter()
        .map(|r| {
            r.transforms
                .as_ref()
                .and_then(|t| t.response.as_ref())
                .and_then(|resp| resp.body.as_ref())
                .map(|b| crate::config::transforms::CompiledJsonTransform::compile(&b.json))
        })
        .collect();
    // DW-029: masking pointers, parsed once here (validation guarantees
    // they parse; the same unreachable-skip contract). Group membership
    // varies per request, so the union resolves at apply time.
    let masking = gateway
        .routes
        .iter()
        .map(|r| {
            r.masking
                .as_ref()
                .map(crate::config::transforms::CompiledMasking::compile)
        })
        .collect();
    // DW-037: compiled cache policies, including the policy-derived
    // vary folds (`match.accept` -> Accept, `cors` -> Origin) resolved
    // once here so the request path never re-derives the vary set.
    let caches = gateway
        .routes
        .iter()
        .map(|r| {
            r.cache.as_ref().map(|c| {
                std::sync::Arc::new(crate::config::cache::CompiledRouteCache::compile(
                    c,
                    r.r#match.accept.is_some(),
                    r.cors.is_some(),
                ))
            })
        })
        .collect();
    // DW-047: preload mock `body_file` bytes once here so the request
    // path never touches the filesystem. Validation has already checked
    // the file exists and is readable; a read failure here is a
    // generation tear (the file was removed between validate and
    // compile) and surfaces as a compile error naming the route.
    let mock_bodies = gateway
        .routes
        .iter()
        .map(|r| match &r.action {
            RouteAction::Mock { mock } => mock
                .body_file
                .as_ref()
                .and_then(|path| std::fs::read(path).ok().map(bytes::Bytes::from)),
            _ => None,
        })
        .collect();

    // SEC-09 (#213): compute the effective security headers per route
    // — the route's own block when present, else the gateway-level
    // default when the route has not opted out, else None. Computed
    // once here so the request path never re-merges.
    let effective_security_headers = gateway
        .routes
        .iter()
        .map(|r| {
            if let Some(sh) = &r.security_headers {
                Some(sh.clone())
            } else if !r.security_headers_opt_out {
                gateway.default_security_headers.clone()
            } else {
                None
            }
        })
        .collect();

    // USA-12 (#233): build the developer portal at compile time when
    // `lifecycle.portal.enabled` is true. The portal is a read-only
    // static HTML page aggregating the configured OpenAPI specs.
    let portal = gateway
        .lifecycle
        .as_ref()
        .and_then(|l| l.portal.as_ref())
        .filter(|p| p.enabled)
        .map(crate::lifecycle::DevPortal::build);

    Ok(Compiled {
        gateway: Arc::new(gateway.clone()),
        portal,
        routes: Arc::new(RouteTable {
            exact,
            prefixes,
            prefix_trie,
            regex_set,
            regex_indices,
            regex_scores,
            rewrite_regexes,
            rewrite_substitutions,
            cors_origins,
            compression_types,
            deprecations,
            accept_media_types,
            request_body_ops,
            response_body_ops,
            masking,
            caches,
            mock_bodies,
            effective_security_headers,
        }),
        content_hash,
    })
}

/// Holds the currently published [`Snapshot`] behind an `ArcSwap` and owns
/// the monotonic generation counter. Shared across the dataplane (read) and
/// the config source / hot reload (write, DW-006). May carry the process's
/// [`crate::events::EventBus`] (DW-044): every publish outcome emits one event
/// (`config_published` / `config_rejected`) onto it, which is why the bus
/// sits in a domain BELOW this one.
pub struct ConfigState {
    snapshot: ArcSwap<Snapshot>,
    generation: AtomicU64,
    /// Serializes publish attempts so generation ids stay gap-free and
    /// monotonic under concurrent writers.
    publish_lock: Mutex<()>,
    /// The event bus publish outcomes emit onto (DW-044). Attached at
    /// construction ([`ConfigState::with_event_bus`]) or by the dataplane
    /// ([`ConfigState::attach_event_bus`], first attach wins). Interior
    /// mutability because the bus is created before/independently of the
    /// state in some wiring orders (the binary creates both up front; a
    /// bare `ConfigState::new` gets one when a `DataPlane` is built from
    /// it, so config events are never silently missing in a live
    /// gateway).
    events: std::sync::RwLock<Option<Arc<crate::events::EventBus>>>,
}

impl Default for ConfigState {
    fn default() -> Self {
        ConfigState {
            snapshot: ArcSwap::from_pointee(Snapshot::empty()),
            generation: AtomicU64::new(0),
            publish_lock: Mutex::new(()),
            events: std::sync::RwLock::new(None),
        }
    }
}

impl ConfigState {
    pub fn new() -> Self {
        Self::default()
    }

    /// New state with its event bus attached from the start (DW-044):
    /// the binary's wiring, so the very first (startup) publish already
    /// emits onto the bus the deliverer will drain.
    pub fn with_event_bus(bus: Arc<crate::events::EventBus>) -> Self {
        let state = Self::default();
        state.attach_event_bus(bus);
        state
    }

    /// Attach the event bus if none is attached yet (first attach wins;
    /// a live bus is never swapped underneath an emitter). Idempotent.
    pub fn attach_event_bus(&self, bus: Arc<crate::events::EventBus>) {
        let mut slot = self.events.write().expect("event bus slot poisoned");
        if slot.is_none() {
            *slot = Some(bus);
        }
    }

    /// The attached event bus, if any (the dataplane adopts/creates it).
    pub fn event_bus(&self) -> Option<Arc<crate::events::EventBus>> {
        self.events.read().expect("event bus slot poisoned").clone()
    }

    /// The emitter for publish outcomes (a no-op handle when no bus is
    /// attached — `None` at the call site keeps emission optional in
    /// unwired constructions).
    fn event_emitter(&self) -> Option<crate::events::Emitter> {
        self.event_bus().map(|bus| bus.emitter())
    }

    /// Currently published snapshot (load is lock-free).
    pub fn snapshot(&self) -> Arc<Snapshot> {
        self.snapshot.load_full()
    }

    /// Validate, compile, and atomically publish. On ANY failure the
    /// currently-published snapshot is untouched (rollback = not-published);
    /// the generation counter is only advanced on success.
    ///
    /// DW-044: emits `config_published` (generation, content hash, route
    /// count) on success and `config_rejected` (issue count, plus the
    /// generation still running) on failure — every publish path (cold
    /// start, hot reload, admin POST) funnels through here, so one
    /// emission site covers them all. Emission is the bus's bounded
    /// non-blocking hand-off; a full queue drops and counts.
    pub fn compile_and_publish(&self, gateway: &Gateway) -> Result<SnapshotInfo, CompileError> {
        let _guard = self.publish_lock.lock().unwrap_or_else(|p| p.into_inner());
        let emitter = self.event_emitter();
        let compiled = match compile(gateway) {
            Ok(compiled) => compiled,
            Err(err) => {
                if let Some(emitter) = &emitter {
                    let issue_count = match &err {
                        CompileError::Validation(issues) => issues.len(),
                        // A compile-stage failure (regex, route conflict)
                        // is one named problem; its Display carries it.
                        _ => 1,
                    };
                    emitter.emit(
                        crate::events::EventKind::ConfigRejected,
                        crate::events::EventPayload {
                            issue_count: Some(issue_count),
                            generation: Some(self.snapshot.load().generation),
                            ..crate::events::EventPayload::default()
                        },
                    );
                }
                return Err(err);
            }
        };
        let generation = self.generation.fetch_add(1, Ordering::SeqCst) + 1;
        let snapshot = Snapshot {
            generation,
            content_hash: compiled.content_hash,
            gateway: compiled.gateway,
            routes: compiled.routes,
            portal: compiled.portal,
        };
        let info = SnapshotInfo {
            generation,
            content_hash: snapshot.content_hash,
            route_count: snapshot.gateway.routes.len(),
        };
        self.snapshot.store(Arc::new(snapshot));
        if let Some(emitter) = &emitter {
            emitter.emit(
                crate::events::EventKind::ConfigPublished,
                crate::events::EventPayload {
                    generation: Some(info.generation),
                    content_hash: Some(info.content_hash),
                    route_count: Some(info.route_count),
                    ..crate::events::EventPayload::default()
                },
            );
        }
        Ok(info)
    }
}