fips/testing/chaos/sim/scenario.py

"""Scenario YAML loading and validation."""

from __future__ import annotations

import os
import re
from dataclasses import dataclass, field

import yaml

# Node ids are rendered nNN by the topology generator, zero-padded to two
# digits. Matching the shape here keeps a typo such as "no4" or "n4x" from
# reaching an assertion as a node that simply never appears.
_NODE_ID_RE = re.compile(r"n\d+")


@dataclass
class Range:
    """A min/max range for stochastic parameters."""

    min: float
    max: float

    def validate(self, name: str):
        if self.min > self.max:
            raise ValueError(f"{name}: min ({self.min}) > max ({self.max})")
        if self.min < 0:
            raise ValueError(f"{name}: min ({self.min}) must be >= 0")


VALID_TRANSPORTS = ("udp", "ethernet", "tcp")


@dataclass
class TopologyConfig:
    num_nodes: int = 10
    algorithm: str = "random_geometric"
    params: dict = field(default_factory=dict)
    ensure_connected: bool = True
    subnet: str = "172.20.0.0/24"
    ip_start: int = 10
    default_transport: str = "udp"
    # Optional transport mix for random topologies: {transport: weight}.
    # When set, each edge is randomly assigned a transport based on weights.
    # Only valid for non-explicit algorithms (explicit uses per-edge syntax).
    transport_mix: dict[str, float] | None = None
    # Assign derived identities in NodeAddr order so n01 holds the smallest and
    # is therefore the root every scenario diagram draws. Default on: without it
    # the root is whichever node happens to hold the smallest key, which is
    # effectively arbitrary and leaves any scenario that reasons about a
    # specific root (e.g. bloom-storm's diamond, or a baseline max_roots check)
    # describing a tree that does not form. Set false where election from an
    # arbitrary key distribution is itself the subject.
    pin_root: bool = True
    # Set by --subnet to opt out of claiming a free range. Not a scenario-file
    # key: a scenario that hardcoded its range would reintroduce the collision
    # claiming exists to remove.
    pinned_subnet: str | None = None


@dataclass
class NetemPolicy:
    delay_ms: tuple[float, float] = (0, 0)
    jitter_ms: tuple[float, float] = (0, 0)
    loss_pct: tuple[float, float] = (0, 0)
    duplicate_pct: tuple[float, float] = (0, 0)
    reorder_pct: tuple[float, float] = (0, 0)
    corrupt_pct: tuple[float, float] = (0, 0)


@dataclass
class NetemMutationConfig:
    interval_secs: Range = field(default_factory=lambda: Range(15, 30))
    fraction: float = 0.3
    policies: dict[str, NetemPolicy] = field(default_factory=dict)
    # Edges the periodic mutation must never touch, "nXX-nYY" strings. Use it
    # to pin the links a tree_parents assertion depends on so a random
    # degradation cannot flip the very comparison being asserted. Validated
    # against the topology in NetemManager — an unknown edge is a hard error.
    exclude_edges: list[str] = field(default_factory=list)


@dataclass
class LinkPolicyOverride:
    """Per-edge netem policy override.

    Edges are specified as "nXX-nYY" strings in canonical form (sorted
    alphabetically). Either ``policy`` (inline) or ``policy_name``
    (reference to a named mutation policy) must be set, not both.
    """

    edges: list[str] = field(default_factory=list)
    policy: NetemPolicy | None = None
    policy_name: str | None = None


@dataclass
class NetemConfig:
    enabled: bool = False
    default_policy: NetemPolicy = field(default_factory=NetemPolicy)
    link_policies: list[LinkPolicyOverride] = field(default_factory=list)
    mutation: NetemMutationConfig = field(default_factory=NetemMutationConfig)


@dataclass
class LinkFlapsConfig:
    enabled: bool = False
    interval_secs: Range = field(default_factory=lambda: Range(20, 60))
    max_down_links: int = 2
    down_duration_secs: Range = field(default_factory=lambda: Range(10, 30))
    protect_connectivity: bool = True


@dataclass
class TrafficConfig:
    enabled: bool = False
    max_concurrent: int = 3
    interval_secs: Range = field(default_factory=lambda: Range(10, 30))
    duration_secs: Range = field(default_factory=lambda: Range(5, 15))
    parallel_streams: int = 4


@dataclass
class NodeChurnConfig:
    enabled: bool = False
    interval_secs: Range = field(default_factory=lambda: Range(60, 180))
    max_down_nodes: int = 1
    down_duration_secs: Range = field(default_factory=lambda: Range(30, 90))
    protect_connectivity: bool = True


@dataclass
class PeerChurnConfig:
    """Peer-level topology churn via connect/disconnect commands.

    When enabled, periodically disconnects a random active link and
    connects a random unconnected node pair, causing the mesh topology
    to evolve over time.
    """

    enabled: bool = False
    interval_secs: Range = field(default_factory=lambda: Range(8, 12))
    ephemeral_fraction: float = 0.0


@dataclass
class BandwidthConfig:
    """Per-link bandwidth pacing via HTB rate limiting.

    When enabled, each link is randomly assigned a rate from the tiers list.
    # TODO: Add structured bandwidth assignment (e.g., per-node roles,
    # asymmetric uplink/downlink, tiered by topology distance, or
    # time-varying bandwidth mutations similar to netem mutation).
    """

    enabled: bool = False
    tiers_mbps: list[int] = field(default_factory=lambda: [1, 10, 100, 1000])


@dataclass
class IngressConfig:
    """Per-link ingress policing via tc ingress qdisc + policer.

    When enabled, each link gets an ingress policer that drops inbound
    packets exceeding the configured rate. Unlike egress HTB (which
    paces packets smoothly), the policer drops excess packets at the
    kernel level, creating bursty arrival patterns that can overflow
    small socket buffers and trigger SO_RXQ_OVFL kernel drops.
    """

    enabled: bool = False
    tiers_kbps: list[int] = field(default_factory=lambda: [1000])
    burst_bytes: int = 32000


@dataclass
class LinkSwapEdge:
    """One edge in a link-swap rotation.

    Edge is a canonical "nXX-nYY" string. ``policy`` names a policy
    in ``LinkSwapConfig.policies``.
    """

    edge: str = ""
    policy: str = ""


@dataclass
class LinkSwapConfig:
    """Deterministic asymmetric link-cost flapping.

    On each ``interval_secs``, the policies on every pair of edges in
    ``edges`` are swapped (cyclically rotated by one position). This
    differs from ``link_flaps`` (random link-down events) and
    ``netem.mutation`` (random per-edge policy mutation) by being a
    deterministic, periodic flip between two named netem policies on
    a fixed set of edges.

    Used to drive a downstream node to repeatedly switch parents on
    a fixed cadence — exercises the spanning-tree rebalance path
    without the noise of a random mutation walk.
    """

    enabled: bool = False
    interval_secs: float = 4.0
    policies: dict[str, NetemPolicy] = field(default_factory=dict)
    edges: list[LinkSwapEdge] = field(default_factory=list)


@dataclass
class BloomSendRateAssertion:
    """Trailing-window ceiling on per-node ``stats.bloom.sent`` delta."""

    window_secs: int = 30
    max_per_node: int = 30


@dataclass
class MinParentSwitchesAssertion:
    """Sanity guard: total parent switches across the run must be at
    least ``min_total``. Used to detect a misconfigured harness where
    the flap inducer is firing but the topology never produces a real
    parent-switch event (e.g., wrong root election).
    """

    min_total: int = 1


@dataclass
class MaxParentSwitchesAssertion:
    """Stability ceiling: fail if parent switches exceed ``max_total``.

    ``node`` scopes the count to a single node id (e.g. ``n04``) instead
    of the mesh-wide total. The distinction is not cosmetic: a criterion
    written about one node's log is a different number from the sum over
    every node, and checking the sum against a per-node threshold
    silently tests something other than what was specified.
    """

    max_total: int = 0
    node: str | None = None


@dataclass
class BaselineAssertion:
    """Floor on the mesh having formed at all.

    Deliberately weak and deliberately universal. It does not describe any
    scenario's subject; it says the nodes came up, agreed on a root, and
    took parents. Its value is that a scenario with no other assertion
    still cannot pass while the mesh is dead, which is the state twelve of
    thirteen scenarios were previously unable to distinguish from success.

    ``max_roots`` is how many distinct root values the snapshot may carry.
    One means the whole mesh agreed; a churn scenario that partitions on
    purpose needs a higher number, and setting it above one is a statement
    that partition is expected rather than an oversight.
    """

    min_nodes_reporting: int | None = None
    max_roots: int | None = None
    min_nodes_parented: int | None = None
    min_sessions: int | None = None


@dataclass
class TreeParentsAssertion:
    """Expected parent per node in the final tree snapshot.

    ``expected`` maps a node id to the node id its parent must be, e.g.
    ``{"n04": "n03"}``. Both sides are node ids rather than node
    addresses: an address is a per-run key derived from the generated
    identity, so a scenario could not name one ahead of time.

    A node absent from the snapshot fails rather than being skipped. That
    case is not hypothetical — more than half the archived runs of these
    scenarios have no entry for the node under test, and a skip would
    have reported those as satisfied.
    """

    expected: dict[str, str] = field(default_factory=dict)


@dataclass
class CongestionSignalsAssertion:
    """Floors on how many nodes observed each congestion signal.

    Each floor is the number of nodes whose final congestion snapshot
    reports a non-zero counter, not the counter's own magnitude: the
    scenario's written criteria are about *whether* a signal reached a
    class of node, and a single node with a huge count would satisfy a
    magnitude test while proving the signal never propagated.

    A floor left unset is not asserted. At least one must be set, since a
    block that asserts nothing is the failure this assertion exists to
    remove.
    """

    min_nodes_detected: int | None = None
    min_nodes_ce_forwarded: int | None = None
    min_nodes_ce_received: int | None = None


@dataclass
class MaxErrorsAssertion:
    """Ceiling on ERROR-level lines across every node's log.

    Unlike the other assertions this one is applied to every scenario
    whether or not the YAML asks for it, because it is a floor on what a
    green run means rather than a property of one scenario: without it a
    run in which every node errors on every line still exits 0.

    ``max_total`` defaults to 0, which is what the archived corpus
    supports. Across 2416 archived run directories no node log contains a
    single ERROR-level line, while the sibling WARN counter extracted by
    the same code path ranges from 0 to 1135 — so 0 is an observed value
    and not an aspiration, and the counter is known to discriminate.

    A scenario that legitimately induces errors raises the ceiling in its
    own YAML and must say at that site why the errors are expected.
    """

    max_total: int = 0


@dataclass
class AssertionsConfig:
    """Optional post-run assertions evaluated against control-socket data."""

    bloom_send_rate: BloomSendRateAssertion | None = None
    min_parent_switches: MinParentSwitchesAssertion | None = None
    max_parent_switches: MaxParentSwitchesAssertion | None = None
    max_errors: MaxErrorsAssertion | None = None
    congestion_signals: CongestionSignalsAssertion | None = None
    tree_parents: TreeParentsAssertion | None = None
    baseline: BaselineAssertion | None = None


@dataclass
class LoggingConfig:
    rust_log: str = "info"
    output_dir: str = "./sim-results"


@dataclass
class Scenario:
    name: str = "unnamed"
    seed: int = 42
    duration_secs: int = 120
    topology: TopologyConfig = field(default_factory=TopologyConfig)
    netem: NetemConfig = field(default_factory=NetemConfig)
    link_flaps: LinkFlapsConfig = field(default_factory=LinkFlapsConfig)
    traffic: TrafficConfig = field(default_factory=TrafficConfig)
    node_churn: NodeChurnConfig = field(default_factory=NodeChurnConfig)
    peer_churn: PeerChurnConfig = field(default_factory=PeerChurnConfig)
    bandwidth: BandwidthConfig = field(default_factory=BandwidthConfig)
    ingress: IngressConfig = field(default_factory=IngressConfig)
    link_swap: LinkSwapConfig = field(default_factory=LinkSwapConfig)
    assertions: AssertionsConfig = field(default_factory=AssertionsConfig)
    logging: LoggingConfig = field(default_factory=LoggingConfig)
    # Raw YAML dict appended to each generated FIPS node config.
    # Allows scenarios to override any FIPS config parameter
    # (e.g., node.tree.reeval_interval_secs).
    fips_overrides: dict = field(default_factory=dict)


# Keys each fixed-schema section understands. A key absent from these sets is a
# typo, and silently ignoring it leaves the block default-constructed while the
# YAML still looks correct — a mistyped "assertion:" disarms a scenario's only
# assertions, a mistyped "link_flap:" turns off the chaos it was meant to inject.
#
# Four mappings are deliberately NOT listed, because their keys are names the
# scenario author chooses rather than a schema: netem.mutation.policies,
# link_swap.policies, topology.transport_mix and assertions.tree_parents (whose
# keys are node ids). Two sub-trees are passed through whole and are likewise
# not checked: fips_overrides and topology.params. tree_parents is not thereby
# unchecked -- both sides of every entry are validated as node ids that exist in
# this scenario's topology, which is the check that matters for it.
#
# NOTE: adding a new assertion type means registering it in TWO places below —
# _SECTION_KEYS["assertions"] (so the block accepts its name) and _ASSERTION_KEYS
# (so its own members are checked) — or scenarios using it are rejected at load.
_TOP_KEYS = {
    "scenario", "topology", "netem", "link_flaps", "traffic", "node_churn",
    "peer_churn", "bandwidth", "ingress", "link_swap", "assertions", "logging",
    "fips_overrides",
}
_SECTION_KEYS = {
    "scenario": {"name", "seed", "duration_secs"},
    "topology": {
        "num_nodes", "algorithm", "params", "ensure_connected", "subnet",
        "ip_start", "default_transport", "transport_mix", "pin_root",
    },
    "netem": {"enabled", "default_policy", "link_policies", "mutation"},
    "netem.link_policies[]": {"edges", "policy", "policy_name"},
    "netem.mutation": {"interval_secs", "fraction", "policies", "exclude_edges"},
    "link_flaps": {
        "enabled", "interval_secs", "max_down_links", "down_duration_secs",
        "protect_connectivity",
    },
    "traffic": {
        "enabled", "max_concurrent", "interval_secs", "duration_secs",
        "parallel_streams",
    },
    "node_churn": {
        "enabled", "interval_secs", "max_down_nodes", "down_duration_secs",
        "protect_connectivity",
    },
    "peer_churn": {"enabled", "interval_secs", "ephemeral_fraction"},
    "bandwidth": {"enabled", "tiers_mbps"},
    "ingress": {"enabled", "tiers_kbps", "burst_bytes"},
    "link_swap": {"enabled", "interval_secs", "policies", "edges"},
    "link_swap.edges[]": {"edge", "policy"},
    "assertions": {
        "bloom_send_rate", "min_parent_switches", "max_parent_switches",
        "max_errors", "congestion_signals", "tree_parents", "baseline",
    },
    "logging": {"rust_log", "output_dir"},
}
_ASSERTION_KEYS = {
    "bloom_send_rate": {"window_secs", "max_per_node"},
    "min_parent_switches": {"min_total"},
    "max_parent_switches": {"max_total", "node"},
    "max_errors": {"max_total"},
    "congestion_signals": {
        "min_nodes_detected", "min_nodes_ce_forwarded", "min_nodes_ce_received",
    },
    "baseline": {
        "min_nodes_reporting", "max_roots", "min_nodes_parented", "min_sessions",
    },
}
_NETEM_POLICY_KEYS = {
    "delay_ms", "jitter_ms", "loss_pct", "duplicate_pct", "reorder_pct",
    "corrupt_pct",
}
_RANGE_KEYS = {"min", "max"}


def _reject_unknown(data, known, context: str):
    """Raise unless every key in `data` is one the loader understands."""
    if data is None:
        raise ValueError(
            f"{context}: section is present but empty; give it a body or remove it"
        )
    if not isinstance(data, dict):
        raise ValueError(f"{context}: expected a mapping, got {type(data).__name__}")
    unknown = sorted(str(k) for k in set(data) - set(known))
    if unknown:
        raise ValueError(
            f"{context}: unknown key(s): {', '.join(unknown)} "
            f"(known: {', '.join(sorted(known))})"
        )


def _parse_range(data, name: str) -> Range:
    """Parse a {min, max} dict into a Range."""
    if isinstance(data, dict):
        _reject_unknown(data, _RANGE_KEYS, name)
        return Range(min=float(data["min"]), max=float(data["max"]))
    raise ValueError(f"{name}: expected {{min, max}} dict, got {type(data).__name__}")


def _parse_netem_policy(data: dict, name: str = "netem policy") -> NetemPolicy:
    """Parse a netem policy from a dict with [min, max] lists or {min, max} dicts."""
    _reject_unknown(data, _NETEM_POLICY_KEYS, name)
    policy = NetemPolicy()
    for attr in (
        "delay_ms",
        "jitter_ms",
        "loss_pct",
        "duplicate_pct",
        "reorder_pct",
        "corrupt_pct",
    ):
        if attr in data:
            val = data[attr]
            if isinstance(val, list) and len(val) == 2:
                setattr(policy, attr, (float(val[0]), float(val[1])))
            elif isinstance(val, dict):
                setattr(policy, attr, (float(val["min"]), float(val["max"])))
            else:
                raise ValueError(f"netem policy {attr}: expected [min, max] or {{min, max}}")
    return policy


def load_scenario(path: str) -> Scenario:
    """Load and validate a scenario from a YAML file."""
    with open(path) as f:
        raw = yaml.safe_load(f)

    if raw is None:
        raise ValueError(f"{path}: file is empty")
    _reject_unknown(raw, _TOP_KEYS, "(top level)")

    s = Scenario()

    # Scenario section
    sc = raw.get("scenario", {})
    _reject_unknown(sc, _SECTION_KEYS["scenario"], "scenario")
    s.name = sc.get("name", os.path.splitext(os.path.basename(path))[0])
    s.seed = int(sc.get("seed", 42))
    s.duration_secs = int(sc.get("duration_secs", 120))

    # Topology section
    tc = raw.get("topology", {})
    _reject_unknown(tc, _SECTION_KEYS["topology"], "topology")
    s.topology.num_nodes = int(tc.get("num_nodes", 10))
    s.topology.algorithm = tc.get("algorithm", "random_geometric")
    s.topology.params = tc.get("params", {})
    s.topology.ensure_connected = tc.get("ensure_connected", True)
    s.topology.subnet = tc.get("subnet", "172.20.0.0/24")
    s.topology.ip_start = int(tc.get("ip_start", 10))
    s.topology.default_transport = tc.get("default_transport", "udp")
    if "pin_root" in tc:
        pin = tc["pin_root"]
        if not isinstance(pin, bool):
            raise ValueError(
                f"topology.pin_root must be a boolean, got {pin!r}"
            )
        s.topology.pin_root = pin
    if "transport_mix" in tc:
        mix = tc["transport_mix"]
        if not isinstance(mix, dict) or not mix:
            raise ValueError("topology.transport_mix must be a non-empty dict")
        s.topology.transport_mix = {str(k): float(v) for k, v in mix.items()}

    # Netem section
    nc = raw.get("netem", {})
    _reject_unknown(nc, _SECTION_KEYS["netem"], "netem")
    s.netem.enabled = nc.get("enabled", False)
    if "default_policy" in nc:
        s.netem.default_policy = _parse_netem_policy(
            nc["default_policy"], "netem.default_policy"
        )
    if "link_policies" in nc:
        for lp_data in nc["link_policies"]:
            _reject_unknown(
                lp_data, _SECTION_KEYS["netem.link_policies[]"], "netem.link_policies[]"
            )
            override = LinkPolicyOverride(
                edges=lp_data.get("edges", []),
            )
            if "policy" in lp_data:
                override.policy = _parse_netem_policy(
                    lp_data["policy"], "netem.link_policies[].policy"
                )
            if "policy_name" in lp_data:
                override.policy_name = lp_data["policy_name"]
            s.netem.link_policies.append(override)
    if "mutation" in nc:
        mc = nc["mutation"]
        _reject_unknown(mc, _SECTION_KEYS["netem.mutation"], "netem.mutation")
        s.netem.mutation.interval_secs = _parse_range(
            mc.get("interval_secs", {"min": 15, "max": 30}), "netem.mutation.interval_secs"
        )
        s.netem.mutation.fraction = float(mc.get("fraction", 0.3))
        s.netem.mutation.exclude_edges = list(mc.get("exclude_edges", []))
        if "policies" in mc:
            s.netem.mutation.policies = {
                name: _parse_netem_policy(pdata, f"netem.mutation.policies.{name}")
                for name, pdata in mc["policies"].items()
            }

    # Link flaps section
    lf = raw.get("link_flaps", {})
    _reject_unknown(lf, _SECTION_KEYS["link_flaps"], "link_flaps")
    s.link_flaps.enabled = lf.get("enabled", False)
    if "interval_secs" in lf:
        s.link_flaps.interval_secs = _parse_range(lf["interval_secs"], "link_flaps.interval_secs")
    s.link_flaps.max_down_links = int(lf.get("max_down_links", 2))
    if "down_duration_secs" in lf:
        s.link_flaps.down_duration_secs = _parse_range(
            lf["down_duration_secs"], "link_flaps.down_duration_secs"
        )
    s.link_flaps.protect_connectivity = lf.get("protect_connectivity", True)

    # Traffic section
    tf = raw.get("traffic", {})
    _reject_unknown(tf, _SECTION_KEYS["traffic"], "traffic")
    s.traffic.enabled = tf.get("enabled", False)
    s.traffic.max_concurrent = int(tf.get("max_concurrent", 3))
    if "interval_secs" in tf:
        s.traffic.interval_secs = _parse_range(tf["interval_secs"], "traffic.interval_secs")
    if "duration_secs" in tf:
        s.traffic.duration_secs = _parse_range(tf["duration_secs"], "traffic.duration_secs")
    s.traffic.parallel_streams = int(tf.get("parallel_streams", 4))

    # Node churn section
    nc2 = raw.get("node_churn", {})
    _reject_unknown(nc2, _SECTION_KEYS["node_churn"], "node_churn")
    s.node_churn.enabled = nc2.get("enabled", False)
    if "interval_secs" in nc2:
        s.node_churn.interval_secs = _parse_range(nc2["interval_secs"], "node_churn.interval_secs")
    s.node_churn.max_down_nodes = int(nc2.get("max_down_nodes", 1))
    if "down_duration_secs" in nc2:
        s.node_churn.down_duration_secs = _parse_range(
            nc2["down_duration_secs"], "node_churn.down_duration_secs"
        )
    s.node_churn.protect_connectivity = nc2.get("protect_connectivity", True)

    # Peer churn section
    pc = raw.get("peer_churn", {})
    _reject_unknown(pc, _SECTION_KEYS["peer_churn"], "peer_churn")
    s.peer_churn.enabled = pc.get("enabled", False)
    if "interval_secs" in pc:
        s.peer_churn.interval_secs = _parse_range(pc["interval_secs"], "peer_churn.interval_secs")
    s.peer_churn.ephemeral_fraction = float(pc.get("ephemeral_fraction", 0.0))

    # Bandwidth section
    bw = raw.get("bandwidth", {})
    _reject_unknown(bw, _SECTION_KEYS["bandwidth"], "bandwidth")
    s.bandwidth.enabled = bw.get("enabled", False)
    if "tiers_mbps" in bw:
        tiers = bw["tiers_mbps"]
        if not isinstance(tiers, list) or not tiers:
            raise ValueError("bandwidth.tiers_mbps must be a non-empty list")
        s.bandwidth.tiers_mbps = [int(t) for t in tiers]

    # Ingress section
    ig = raw.get("ingress", {})
    _reject_unknown(ig, _SECTION_KEYS["ingress"], "ingress")
    s.ingress.enabled = ig.get("enabled", False)
    if "tiers_kbps" in ig:
        tiers = ig["tiers_kbps"]
        if not isinstance(tiers, list) or not tiers:
            raise ValueError("ingress.tiers_kbps must be a non-empty list")
        s.ingress.tiers_kbps = [int(t) for t in tiers]
    s.ingress.burst_bytes = int(ig.get("burst_bytes", 32000))

    # Link swap section (deterministic asymmetric link-cost flapping).
    ls = raw.get("link_swap", {})
    _reject_unknown(ls, _SECTION_KEYS["link_swap"], "link_swap")
    s.link_swap.enabled = ls.get("enabled", False)
    if "interval_secs" in ls:
        s.link_swap.interval_secs = float(ls["interval_secs"])
    if "policies" in ls:
        s.link_swap.policies = {
            name: _parse_netem_policy(pdata, f"link_swap.policies.{name}")
            for name, pdata in ls["policies"].items()
        }
    if "edges" in ls:
        for edata in ls["edges"]:
            if not isinstance(edata, dict):
                raise ValueError("link_swap.edges entries must be dicts")
            _reject_unknown(
                edata, _SECTION_KEYS["link_swap.edges[]"], "link_swap.edges[]"
            )
            edge = str(edata.get("edge", ""))
            policy = str(edata.get("policy", ""))
            if not edge or not policy:
                raise ValueError("link_swap.edges entries require 'edge' and 'policy'")
            s.link_swap.edges.append(LinkSwapEdge(edge=edge, policy=policy))

    # Assertions section (post-run control-socket-based checks).
    asrt = raw.get("assertions", {})
    _reject_unknown(asrt, _SECTION_KEYS["assertions"], "assertions")
    if "bloom_send_rate" in asrt:
        bsr = asrt["bloom_send_rate"]
        _reject_unknown(
            bsr, _ASSERTION_KEYS["bloom_send_rate"], "assertions.bloom_send_rate"
        )
        s.assertions.bloom_send_rate = BloomSendRateAssertion(
            window_secs=int(bsr.get("window_secs", 30)),
            max_per_node=int(bsr.get("max_per_node", 30)),
        )
    if "min_parent_switches" in asrt:
        mps = asrt["min_parent_switches"]
        _reject_unknown(
            mps, _ASSERTION_KEYS["min_parent_switches"],
            "assertions.min_parent_switches",
        )
        s.assertions.min_parent_switches = MinParentSwitchesAssertion(
            min_total=int(mps.get("min_total", 1)),
        )
    if "max_parent_switches" in asrt:
        xps = asrt["max_parent_switches"]
        _reject_unknown(
            xps, _ASSERTION_KEYS["max_parent_switches"],
            "assertions.max_parent_switches",
        )
        if "max_total" not in xps:
            raise ValueError(
                "assertions.max_parent_switches: max_total is required "
                "(a defaulted ceiling would assert an arbitrary number)"
            )
        max_total = xps["max_total"]
        # bool is a subclass of int, and `max_total: yes` would coerce to 1
        # -- a ceiling low enough to change the verdict, arrived at by typo.
        if isinstance(max_total, bool) or not isinstance(max_total, int):
            raise ValueError(
                f"assertions.max_parent_switches: max_total must be a "
                f"non-negative integer, got {max_total!r}"
            )
        if max_total < 0:
            raise ValueError(
                f"assertions.max_parent_switches: max_total must be "
                f"non-negative, got {max_total}"
            )
        # Distinguish "key absent" from "key present but empty". Only the
        # first means mesh-wide. YAML renders a bare `node:` as None, and
        # treating that as absent would silently swap a per-node ceiling
        # for a mesh-wide one -- the exact conflation this assertion was
        # added to stop, and a live flake rather than a theoretical one:
        # archived runs of this scenario reach 6 mesh-wide against an n04
        # maximum of 2.
        node = None
        if "node" in xps:
            node = xps["node"]
            if not isinstance(node, str) or not node.strip():
                raise ValueError(
                    f"assertions.max_parent_switches: node must be a node id "
                    f"string such as 'n04', got {node!r}. Omit the key "
                    f"entirely for the mesh-wide total."
                )
            node = node.strip()
        s.assertions.max_parent_switches = MaxParentSwitchesAssertion(
            max_total=max_total,
            node=node,
        )
    if "max_errors" in asrt:
        mev = asrt["max_errors"]
        _reject_unknown(
            mev, _ASSERTION_KEYS["max_errors"], "assertions.max_errors",
        )
        if "max_total" not in mev:
            raise ValueError(
                "assertions.max_errors: max_total is required (the point of "
                "overriding the default ceiling is to name the new number)"
            )
        err_total = mev["max_total"]
        if isinstance(err_total, bool) or not isinstance(err_total, int):
            raise ValueError(
                f"assertions.max_errors: max_total must be a non-negative "
                f"integer, got {err_total!r}"
            )
        if err_total < 0:
            raise ValueError(
                f"assertions.max_errors: max_total must be non-negative, "
                f"got {err_total}"
            )
        s.assertions.max_errors = MaxErrorsAssertion(max_total=err_total)
    else:
        # Default-on. See MaxErrorsAssertion for why this one assertion is
        # applied without being asked for: it is the floor on what a green
        # run means, and a scenario that has to opt in is a scenario that
        # can forget to.
        s.assertions.max_errors = MaxErrorsAssertion()
    if "congestion_signals" in asrt:
        cs = asrt["congestion_signals"]
        _reject_unknown(
            cs, _ASSERTION_KEYS["congestion_signals"],
            "assertions.congestion_signals",
        )
        floors = {}
        for key in _ASSERTION_KEYS["congestion_signals"]:
            if key not in cs:
                continue
            val = cs[key]
            if isinstance(val, bool) or not isinstance(val, int):
                raise ValueError(
                    f"assertions.congestion_signals.{key}: must be a positive "
                    f"integer number of nodes, got {val!r}"
                )
            if val < 1:
                raise ValueError(
                    f"assertions.congestion_signals.{key}: must be at least 1, "
                    f"got {val}. A floor of 0 is satisfied by a mesh that "
                    f"observed nothing, which is the case this assertion exists "
                    f"to catch; omit the key instead."
                )
            floors[key] = val
        if not floors:
            raise ValueError(
                "assertions.congestion_signals: set at least one floor "
                "(min_nodes_detected, min_nodes_ce_forwarded, "
                "min_nodes_ce_received); a block with none asserts nothing"
            )
        s.assertions.congestion_signals = CongestionSignalsAssertion(**floors)
    if "tree_parents" in asrt:
        tp = asrt["tree_parents"]
        if not isinstance(tp, dict) or not tp:
            raise ValueError(
                "assertions.tree_parents: give it at least one "
                "'<node>: <expected parent>' entry; an empty block asserts "
                "nothing"
            )
        expected = {}
        for child, parent in tp.items():
            for role, val in (("node", child), ("parent", parent)):
                if not isinstance(val, str) or not _NODE_ID_RE.fullmatch(val):
                    raise ValueError(
                        f"assertions.tree_parents: {role} {val!r} is not a node "
                        f"id of the form 'n04'"
                    )
                idx = int(val[1:])
                if idx < 1 or idx > s.topology.num_nodes:
                    raise ValueError(
                        f"assertions.tree_parents: {role} '{val}' is outside "
                        f"this scenario's {s.topology.num_nodes} nodes. An "
                        f"assertion about a node that cannot exist would fail "
                        f"for the wrong reason every run."
                    )
            if child == parent:
                raise ValueError(
                    f"assertions.tree_parents: '{child}' is given itself as "
                    f"its parent. A node is its own parent only when it "
                    f"believes it is root, which is what an unconverged tree "
                    f"looks like; assert that some other way."
                )
            expected[child] = parent
        s.assertions.tree_parents = TreeParentsAssertion(expected=expected)
    if "baseline" in asrt:
        bl = asrt["baseline"]
        _reject_unknown(bl, _ASSERTION_KEYS["baseline"], "assertions.baseline")
        vals = {}
        for key in _ASSERTION_KEYS["baseline"]:
            if key not in bl:
                continue
            val = bl[key]
            if isinstance(val, bool) or not isinstance(val, int):
                raise ValueError(
                    f"assertions.baseline.{key}: must be an integer, "
                    f"got {val!r}"
                )
            floor = 1 if key == "max_roots" else 0
            if val < floor:
                raise ValueError(
                    f"assertions.baseline.{key}: must be at least {floor}, "
                    f"got {val}"
                )
            vals[key] = val
        if not vals:
            raise ValueError(
                "assertions.baseline: set at least one of "
                + ", ".join(sorted(_ASSERTION_KEYS["baseline"]))
                + "; a block with none asserts nothing"
            )
        if vals.get("min_nodes_parented", 0) > 0 or vals.get("max_roots"):
            n = s.topology.num_nodes
            if vals.get("min_nodes_parented", 0) > n - 1:
                raise ValueError(
                    f"assertions.baseline.min_nodes_parented: "
                    f"{vals['min_nodes_parented']} exceeds {n - 1}, the most a "
                    f"{n}-node mesh can reach — the root is its own parent, so "
                    f"this could never pass"
                )
        s.assertions.baseline = BaselineAssertion(**vals)

    # Logging section
    lg = raw.get("logging", {})
    _reject_unknown(lg, _SECTION_KEYS["logging"], "logging")
    s.logging.rust_log = lg.get("rust_log", "info")
    s.logging.output_dir = lg.get("output_dir", "./sim-results")

    # FIPS config overrides (raw YAML dict appended to node configs)
    s.fips_overrides = raw.get("fips_overrides", {})

    # Validation
    _validate(s)

    return s


_SUPPRESSING_LOG_LEVELS = ("off", "error", "warn")


def _validate_parent_switch_observability(s: Scenario):
    """Refuse a parent-switch assertion the log level cannot observe.

    The events these assertions count are emitted at ``info``. A scenario
    that declares one while setting ``logging.rust_log`` to ``warn`` or
    below counts zero switches: the minimum assertion then fails for the
    wrong reason, and the maximum assertion passes without observing
    anything, which is the failure mode the whole assertion effort exists
    to remove. Catch it at load rather than after the run.

    Deliberately conservative. It rejects only a default level that is
    demonstrably too coarse, and says nothing about per-target directives
    such as ``info,fips::node=debug``, which raise verbosity rather than
    lower it.
    """
    if (
        s.assertions.min_parent_switches is None
        and s.assertions.max_parent_switches is None
    ):
        return
    default_level = s.logging.rust_log.split(",")[0].strip().lower()
    if default_level in _SUPPRESSING_LOG_LEVELS:
        raise ValueError(
            f"logging.rust_log is '{s.logging.rust_log}', whose default level "
            f"'{default_level}' suppresses the info-level parent-switch events "
            f"that a parent-switch assertion counts. The assertion would see "
            f"zero switches regardless of what the tree did. Use 'info' or "
            f"more verbose, or drop the assertion."
        )


def _validate_error_observability(s: Scenario):
    """Refuse an error ceiling the log level cannot observe.

    Narrower than the parent-switch guard on purpose: ERROR lines survive
    every level except ``off``, so ``off`` is the only setting that turns
    this assertion into one that counts zero whatever the mesh did. Since
    the ceiling is applied by default, a scenario silencing its logs would
    otherwise acquire an assertion that cannot fail.
    """
    if s.assertions.max_errors is None:
        return
    default_level = s.logging.rust_log.split(",")[0].strip().lower()
    if default_level == "off":
        raise ValueError(
            "logging.rust_log is 'off', which suppresses the ERROR-level "
            "lines the max_errors assertion counts. The assertion would see "
            "zero errors regardless of what the mesh did. Raise the level, "
            "or state a deliberate override in assertions.max_errors."
        )


def _validate(s: Scenario):
    """Validate scenario constraints."""
    _validate_parent_switch_observability(s)
    _validate_error_observability(s)
    if s.topology.num_nodes < 2:
        raise ValueError("topology.num_nodes must be >= 2")
    if s.topology.num_nodes > 250:
        raise ValueError("topology.num_nodes must be <= 250 (subnet limit)")
    if s.topology.algorithm not in ("random_geometric", "erdos_renyi", "chain", "explicit"):
        raise ValueError(f"Unknown topology algorithm: {s.topology.algorithm}")
    if s.topology.default_transport not in VALID_TRANSPORTS:
        raise ValueError(
            f"topology.default_transport: '{s.topology.default_transport}' "
            f"not in {VALID_TRANSPORTS}"
        )
    if s.topology.transport_mix is not None:
        if s.topology.algorithm == "explicit":
            raise ValueError(
                "topology.transport_mix cannot be used with explicit algorithm "
                "(use per-edge transport syntax instead)"
            )
        for transport, weight in s.topology.transport_mix.items():
            if transport not in VALID_TRANSPORTS:
                raise ValueError(
                    f"topology.transport_mix: '{transport}' not in {VALID_TRANSPORTS}"
                )
            if weight <= 0:
                raise ValueError(
                    f"topology.transport_mix: weight for '{transport}' must be > 0"
                )
    if s.topology.algorithm == "explicit":
        adj = s.topology.params.get("adjacency")
        if not adj or not isinstance(adj, list):
            raise ValueError("explicit topology requires params.adjacency list")
        node_ids = set()
        for i, entry in enumerate(adj):
            if not isinstance(entry, (list, tuple)) or len(entry) not in (2, 3):
                raise ValueError(
                    f"explicit adjacency[{i}]: expected [nodeA, nodeB] or "
                    f"[nodeA, nodeB, transport], got {entry}"
                )
            node_ids.update(str(p) for p in entry[:2])
            if len(entry) == 3:
                transport = str(entry[2])
                if transport not in VALID_TRANSPORTS:
                    raise ValueError(
                        f"explicit adjacency[{i}]: transport '{transport}' "
                        f"not in {VALID_TRANSPORTS}"
                    )
        if len(node_ids) != s.topology.num_nodes:
            raise ValueError(
                f"explicit adjacency references {len(node_ids)} nodes "
                f"but num_nodes is {s.topology.num_nodes}"
            )
    if s.duration_secs < 1:
        raise ValueError("duration_secs must be >= 1")

    # Validate link_policies
    for i, lp in enumerate(s.netem.link_policies):
        if not lp.edges:
            raise ValueError(f"netem.link_policies[{i}]: edges list is empty")
        if lp.policy is not None and lp.policy_name is not None:
            raise ValueError(
                f"netem.link_policies[{i}]: specify policy or policy_name, not both"
            )
        if lp.policy is None and lp.policy_name is None:
            raise ValueError(
                f"netem.link_policies[{i}]: must specify policy or policy_name"
            )
        if lp.policy_name and lp.policy_name not in s.netem.mutation.policies:
            raise ValueError(
                f"netem.link_policies[{i}]: policy_name '{lp.policy_name}' "
                f"not found in mutation.policies"
            )

    # Validate ranges
    if s.netem.enabled and s.netem.mutation.policies:
        s.netem.mutation.interval_secs.validate("netem.mutation.interval_secs")
    if s.link_flaps.enabled:
        s.link_flaps.interval_secs.validate("link_flaps.interval_secs")
        s.link_flaps.down_duration_secs.validate("link_flaps.down_duration_secs")
    if s.traffic.enabled:
        s.traffic.interval_secs.validate("traffic.interval_secs")
        s.traffic.duration_secs.validate("traffic.duration_secs")
    if s.node_churn.enabled:
        s.node_churn.interval_secs.validate("node_churn.interval_secs")
        s.node_churn.down_duration_secs.validate("node_churn.down_duration_secs")
        if s.node_churn.max_down_nodes >= s.topology.num_nodes:
            raise ValueError("node_churn.max_down_nodes must be < topology.num_nodes")
    if s.peer_churn.enabled:
        s.peer_churn.interval_secs.validate("peer_churn.interval_secs")
        if not 0.0 <= s.peer_churn.ephemeral_fraction <= 1.0:
            raise ValueError("peer_churn.ephemeral_fraction must be between 0.0 and 1.0")
    if s.bandwidth.enabled:
        for tier in s.bandwidth.tiers_mbps:
            if tier <= 0:
                raise ValueError(f"bandwidth.tiers_mbps: all values must be > 0, got {tier}")
    if s.ingress.enabled:
        for tier in s.ingress.tiers_kbps:
            if tier <= 0:
                raise ValueError(f"ingress.tiers_kbps: all values must be > 0, got {tier}")
        if s.ingress.burst_bytes <= 0:
            raise ValueError(f"ingress.burst_bytes must be > 0, got {s.ingress.burst_bytes}")

    # Validate link_swap
    if s.link_swap.enabled:
        if s.link_swap.interval_secs <= 0:
            raise ValueError("link_swap.interval_secs must be > 0")
        if len(s.link_swap.edges) < 2:
            raise ValueError("link_swap.edges must list at least 2 edges to swap")
        if not s.link_swap.policies:
            raise ValueError("link_swap.policies must not be empty when link_swap.enabled")
        for entry in s.link_swap.edges:
            if entry.policy not in s.link_swap.policies:
                raise ValueError(
                    f"link_swap.edges: policy '{entry.policy}' not in link_swap.policies"
                )

    # Validate assertions
    if s.assertions.bloom_send_rate is not None:
        bsr = s.assertions.bloom_send_rate
        if bsr.window_secs < 1:
            raise ValueError("assertions.bloom_send_rate.window_secs must be >= 1")
        if bsr.max_per_node < 0:
            raise ValueError("assertions.bloom_send_rate.max_per_node must be >= 0")
        if bsr.window_secs > s.duration_secs:
            raise ValueError(
                "assertions.bloom_send_rate.window_secs must not exceed scenario duration"
            )