testprotocols 0.1.0__py3-none-any.whl

testprotocols/device_lifecycle.py

@@ -0,0 +1,49 @@
+"""Device lifecycle template.
+
+Defines the abstract contract for controlling a CPE device through its
+boot lifecycle, including boot detection, factory reset, and finalization.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DeviceLifecycle(Protocol):
+    """Abstract contract for device lifecycle and boot management operations."""
+
+    def verify_cpe_is_booting(self) -> None:
+        """Verify that the CPE device has entered the boot process."""
+        ...
+
+    def wait_for_boot(self, timeout_s: int | None = None) -> None:
+        """Block until the device has completed booting.
+
+        Implementations verify completion via a signal that
+        unambiguously postdates the most recent ``reset()`` — for
+        example, comparing an ACS-side ``last_boot_time`` against a
+        timestamp captured before the reset was issued. Raises
+        ``TimeoutError`` if completion is not observed within
+        *timeout_s*; when *timeout_s* is ``None`` the implementation
+        applies its own default deadline.
+        """
+        ...
+
+    def factory_reset(self, method: str | None = None) -> bool:
+        """Perform a factory reset using the given method. Return True on success."""
+        ...
+
+    def reset(self, method: str | None = None) -> None:
+        """Perform a reset (soft or hard) using the given method.
+
+        The implementation is expected to capture an internal baseline
+        (e.g. a wall-clock timestamp) so the matching ``wait_for_boot()``
+        call can confirm the device's post-reset boot is fresh, not a
+        stale signal from before the reset was issued.
+        """
+        ...
+
+    def finalize_boot(self) -> bool:
+        """Finalize the boot sequence and return True if the device is ready."""
+        ...

testprotocols/device_management.py

@@ -0,0 +1,50 @@
+"""Device management template.
+
+Defines the abstract contract for querying runtime health and operational
+state of a managed device, including uptime, memory, processes, and logs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DeviceManagement(Protocol):
+    """Abstract contract for device management and health monitoring operations."""
+
+    def get_seconds_uptime(self) -> float:
+        """Return the device uptime in seconds."""
+        ...
+
+    def is_online(self) -> bool:
+        """Return True if the device is reachable and operational."""
+        ...
+
+    def get_load_avg(self) -> float:
+        """Return the current 1-minute load average of the device."""
+        ...
+
+    def get_memory_utilization(self) -> dict[str, int]:
+        """Return memory utilization in bytes, keyed by metric name."""
+        ...
+
+    def get_running_processes(self, ps_options: str = "-A") -> list[Any]:
+        """Return the list of running processes using the given ps options."""
+        ...
+
+    def get_board_logs(self, timeout: int = 300) -> str:
+        """Return the board system log as a string, waiting up to *timeout* seconds."""
+        ...
+
+    def read_event_logs(self) -> list[dict[str, Any]]:
+        """Return structured event log entries from the device."""
+        ...
+
+    def get_boottime_log(self) -> list[str]:
+        """Return the boot-time log as a list of log lines."""
+        ...
+
+    def get_file_content(self, fname: str, timeout: int = 30) -> str:
+        """Return the content of the named file from the device filesystem."""
+        ...

testprotocols/devices/__init__.py

@@ -0,0 +1,46 @@
+"""Device archetype registry — maps inventory device_type strings to Protocols."""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+
+_registry: dict[str, DeviceTypeSpec] = {}
+
+
+@dataclass(frozen=True)
+class DeviceTypeSpec:
+    """Registration record: inventory string -> @runtime_checkable Protocol class."""
+
+    name: str
+    protocol: type
+
+
+def register_device_type(name: str, protocol: type) -> DeviceTypeSpec:
+    """Register *protocol* as the contract for inventory devices typed *name*.
+
+    Returns the spec; also stored in the module-level registry so
+    ``get_device_type(name)`` can look it up by inventory string.
+    """
+    spec = DeviceTypeSpec(name=name, protocol=protocol)
+    _registry[name] = spec
+    return spec
+
+
+def get_device_type(name: str) -> DeviceTypeSpec | None:
+    """Return the spec for inventory *name*, or None if not registered."""
+    return _registry.get(name)
+
+
+def all_device_types() -> dict[str, DeviceTypeSpec]:
+    """Return a copy of the full registry."""
+    return dict(_registry)
+
+
+# Auto-import all archetype modules to trigger registration as a side effect.
+# ``importlib.import_module`` avoids the unused-import / out-of-order-import
+# friction that direct ``from … import …`` statements would create here, and
+# keeps the import section at the top of the file as PEP 8 prefers.
+for _mod in ("client", "cpe", "infra", "sdwan", "switch", "traffic", "voice", "wan"):
+    importlib.import_module(f"testprotocols.devices.{_mod}")
+del _mod

testprotocols/devices/base.py

@@ -0,0 +1,40 @@
+"""Universal base Protocol shared by every device archetype."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class BaseDeviceProtocol(Protocol):
+    """Universal identity surface every test-device archetype carries.
+
+    Substrate- and framework-neutral: any concrete driver that exposes a
+    ``device_name`` and a ``device_type`` satisfies this — palco's
+    ``PalcoDevice`` (where both are ``@property``), a hypothetical
+    boardfarm ``BoardfarmDevice``, a pyATS ``Device`` wrapper, a
+    pure-Python simulator. Archetype Protocols in
+    ``testprotocols.devices.*`` inherit from this so consumers
+    (operations, step defs) can read identity for log / assertion
+    messages without reaching into framework-specific base classes.
+
+    Deliberately scoped to the universal pair — name + type. Anything a
+    specific framework wants to expose (palco's ``config`` /
+    ``get_interactive_consoles``, boardfarm's lifecycle hooks, etc.) is
+    the framework's own concern. Frameworks declare a connector Protocol
+    on their side that extends this base; testbed plugins compose
+    archetype + framework-connector into a combined Protocol where step
+    defs need both.
+    """
+
+    # Read-only identity. Declared as properties (not settable variables) so that
+    # implementers exposing them as ``@property`` (VitroDevice, palco's
+    # PalcoDevice) statically satisfy the Protocol — a settable-variable member
+    # would reject a read-only property. A plain ``device_name: str`` attribute
+    # also satisfies a read-only-property member, so this is the more permissive,
+    # correct declaration for read-only identity.
+    @property
+    def device_name(self) -> str: ...
+
+    @property
+    def device_type(self) -> str: ...

testprotocols/devices/client.py

@@ -0,0 +1,133 @@
+"""Client device archetypes — wired LAN, wireless LAN, and QoE measurement endpoints."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.arp_client import ArpClient
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.dhcp_client import DhcpClient
+from testprotocols.dns_client import DnsClient
+from testprotocols.file_transfer import FileTransfer
+from testprotocols.http_client import HttpClient
+from testprotocols.http_server import HttpServer
+from testprotocols.ip_interface import IpInterface
+from testprotocols.ip_routing import IpRouting
+from testprotocols.iperf_client import IperfClient
+from testprotocols.iperf_server import IperfServer
+from testprotocols.multicast_client import MulticastClient
+from testprotocols.network_endpoint import NetworkEndpoint
+from testprotocols.network_probe import NetworkProbe
+from testprotocols.nmap_scanner import NmapScanner
+from testprotocols.ntp_client import NtpClient
+from testprotocols.packet_filter import PacketFilter
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.qoe_browser import QoeBrowser
+from testprotocols.syslog_config import SyslogConfig
+from testprotocols.upnp_client import UpnpClient
+from testprotocols.vlan_client import VlanClient
+from testprotocols.wifi_client import WifiClient
+
+
+@runtime_checkable
+class LanClientDevice(BaseDeviceProtocol, Protocol):
+    """Wired LAN client archetype — a host on the customer LAN segment.
+
+    Used as a traffic source/sink and protocol endpoint for testing CPE/router
+    behaviour from the subscriber side. Provides L3 (IP, routing, DHCP), the
+    common application-layer clients (HTTP/DNS/iperf/UPnP/multicast/NTP/file
+    transfer), packet capture, network scanning, host packet-filtering, and
+    L2 helpers (ARP, VLAN tagging).
+    """
+
+    ip_interface: IpInterface
+    ip_routing: IpRouting
+    dhcp_client: DhcpClient
+    http_client: HttpClient
+    http_server: HttpServer
+    dns_client: DnsClient
+    iperf_client: IperfClient
+    iperf_server: IperfServer
+    pcap: PcapCapture
+    upnp_client: UpnpClient
+    multicast_client: MulticastClient
+    ntp_client: NtpClient
+    nmap_scanner: NmapScanner
+    file_transfer: FileTransfer
+    packet_filter: PacketFilter
+    arp_client: ArpClient
+    vlan_client: VlanClient
+    network_probe: NetworkProbe
+    data_plane_endpoint: NetworkEndpoint
+
+
+@runtime_checkable
+class WlanClientDevice(BaseDeviceProtocol, Protocol):
+    """Wireless LAN client archetype — a Wi-Fi station for over-the-air testing.
+
+    Used to drive Wi-Fi association, roaming, and traffic scenarios against a
+    CPE / access point. Provides Wi-Fi client capabilities plus the L3 / app
+    surface needed to exercise data-plane behaviour once associated.
+    """
+
+    wifi_client: WifiClient
+    ip_interface: IpInterface
+    ip_routing: IpRouting
+    dhcp_client: DhcpClient
+    http_client: HttpClient
+    iperf_client: IperfClient
+    iperf_server: IperfServer
+    pcap: PcapCapture
+    upnp_client: UpnpClient
+    multicast_client: MulticastClient
+    ntp_client: NtpClient
+    nmap_scanner: NmapScanner
+    file_transfer: FileTransfer
+
+
+@runtime_checkable
+class QoeClientDevice(BaseDeviceProtocol, Protocol):
+    """QoE (Quality of Experience) client archetype — browser-driven measurement endpoint.
+
+    Minimal client used to drive web-based QoE workloads (page load, video
+    streaming) against test servers and through CPE/SD-WAN under test.
+    """
+
+    qoe_browser: QoeBrowser
+    ip_interface: IpInterface
+    dhcp_client: DhcpClient
+    syslog: SyslogConfig
+    """Where this host forwards its syslog stream (management-plane telemetry).
+
+    Testbed-driven: the driver auto-applies the configured collector at
+    configure time; a testbed with no collector simply leaves it unset.
+    ``QoeMeasurementClientDevice`` inherits this attribute.
+    """
+
+
+@runtime_checkable
+class QoeMeasurementClientDevice(QoeClientDevice, Protocol):
+    """QoE measurement client — a QoeClientDevice that is also a LAN-side
+    throughput source/sink, reachability prober, and capture point.
+
+    One host that drives browser QoE workloads AND acts as an iperf source/sink,
+    runs protocol-parameterised reachability probes (icmp / tcp / udp, with a
+    responder so the connectionless "blocked vs no-service" case is observable),
+    and captures traffic on the test segment. A strict superset of
+    ``QoeClientDevice`` (qoe_browser + ip_interface + dhcp_client) — so any
+    consumer typed against ``QoeClientDevice`` also accepts this device — for
+    testbeds (e.g. a mobile LAN-side measurement VM) that fold all those roles
+    into one host rather than separate browser / iperf-generator devices.
+    """
+
+    iperf_client: IperfClient
+    iperf_server: IperfServer
+    network_probe: NetworkProbe
+    pcap: PcapCapture
+
+
+register_device_type("linux_lan_client", LanClientDevice)
+register_device_type("linux_wlan_client", WlanClientDevice)
+register_device_type("linux_qoe_client", QoeClientDevice)
+register_device_type("linux_qoe_measurement_client", QoeMeasurementClientDevice)

testprotocols/devices/cpe.py

@@ -0,0 +1,66 @@
+"""CPE (Customer Premises Equipment) device archetype."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.conntrack import Conntrack
+from testprotocols.device_lifecycle import DeviceLifecycle
+from testprotocols.device_management import DeviceManagement
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.firewall import Firewall
+from testprotocols.firewall_zones import FirewallZones
+from testprotocols.hw_console import HwConsole
+from testprotocols.ip_interface import IpInterface
+from testprotocols.ip_routing import IpRouting
+from testprotocols.nat import Nat
+from testprotocols.network_endpoint import NetworkEndpoint
+from testprotocols.network_probe import NetworkProbe
+from testprotocols.ntp_client import NtpClient
+from testprotocols.tr069_client import Tr069Client
+from testprotocols.wifi_bss import WifiBss
+from testprotocols.wifi_onboarding import WifiOnboarding
+from testprotocols.wifi_radio import WifiRadio
+from testprotocols.wifi_rf import WifiRf
+from testprotocols.wifi_stations import WifiStations
+from testprotocols.wifi_transitions import WifiTransitions
+
+
+@runtime_checkable
+class CpeDevice(BaseDeviceProtocol, Protocol):
+    """CPE device archetype — black-box surface for residential / SMB gateways.
+
+    Aggregates the capability protocols any conforming CPE driver must provide:
+    TR-069 management, lifecycle, hardware console, the full Wi-Fi stack
+    (radio / BSS / stations / RF / transitions / onboarding), L3 (IP, routing,
+    NAT), the gateway-tier firewall (rule administration + port forwarding,
+    plus zone-based policy via firewall_zones), and NTP.
+
+    Plugin-local extensions (richer levels, additional capabilities) can
+    derive their own Protocol from this one.
+    """
+
+    tr069_client: Tr069Client
+    device_management: DeviceManagement
+    device_lifecycle: DeviceLifecycle
+    hw_console: HwConsole
+    wifi_radio: WifiRadio
+    wifi_bss: WifiBss
+    wifi_stations: WifiStations
+    wifi_rf: WifiRf
+    wifi_transitions: WifiTransitions
+    wifi_onboarding: WifiOnboarding
+    ip_interface: IpInterface
+    ip_routing: IpRouting
+    firewall: Firewall
+    nat: Nat
+    conntrack: Conntrack
+    firewall_zones: FirewallZones
+    ntp_client: NtpClient
+    network_probe: NetworkProbe
+    wan_endpoint: NetworkEndpoint
+    lan_endpoint: NetworkEndpoint
+
+
+register_device_type("linux_cpe", CpeDevice)

testprotocols/devices/infra.py

@@ -0,0 +1,62 @@
+"""Infrastructure device archetypes — ACS, provisioner, TFTP server."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.dhcp_server import DhcpServer
+from testprotocols.file_transfer import FileTransfer
+from testprotocols.packet_filter import PacketFilter
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.tftp_server import TftpServer
+from testprotocols.tr069_server import Tr069Server
+
+
+@runtime_checkable
+class AcsDevice(BaseDeviceProtocol, Protocol):
+    """ACS (Auto-Configuration Server) archetype — TR-069 server-side counterpart to CPE.
+
+    Provides the TR-069 server protocol surface (CWMP plus ACS-side inventory
+    and per-CPE connection status). Includes packet capture / filter and file
+    transfer for diagnostic workflows. Drivers may implement the server
+    surface over any transport (CWMP NBI, REST, GUI scrape); the choice is a
+    driver-internal concern.
+    """
+
+    tr069_server: Tr069Server
+    pcap: PcapCapture
+    file_transfer: FileTransfer
+    packet_filter: PacketFilter
+
+
+@runtime_checkable
+class ProvisionerDevice(BaseDeviceProtocol, Protocol):
+    """Provisioner archetype — DHCP-driven device provisioning service.
+
+    Hands out IP leases (with vendor-specific options) to CPEs and clients on
+    the test network. Includes packet capture / filter and file transfer for
+    inspecting provisioning exchanges.
+    """
+
+    dhcp_server: DhcpServer
+    pcap: PcapCapture
+    file_transfer: FileTransfer
+    packet_filter: PacketFilter
+
+
+@runtime_checkable
+class TftpDevice(BaseDeviceProtocol, Protocol):
+    """TFTP server archetype — file source for firmware downloads / config fetches.
+
+    Minimal archetype used as a source for TR-069 ``Download`` operations and
+    similar boot-time fetch flows.
+    """
+
+    tftp_server: TftpServer
+
+
+register_device_type("linux_acs", AcsDevice)
+register_device_type("linux_provisioner", ProvisionerDevice)
+register_device_type("linux_tftp", TftpDevice)

testprotocols/devices/sdwan.py

@@ -0,0 +1,97 @@
+"""SD-WAN device archetypes."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.appliance_nat import ApplianceNat
+from testprotocols.appliance_uplinks import ApplianceUplinks
+from testprotocols.appliance_vlans import ApplianceVlans
+from testprotocols.bgp import Bgp
+from testprotocols.content_filtering import ContentFiltering
+from testprotocols.conntrack import Conntrack
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.ip_interface import IpInterface
+from testprotocols.l3_firewall import L3Firewall
+from testprotocols.l7_firewall import L7Firewall
+from testprotocols.nat import Nat
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.router import Router
+from testprotocols.sdwan_policy_manager import SdwanPolicyManager
+from testprotocols.site_to_site_vpn import SiteToSiteVpn
+from testprotocols.static_routes import StaticRoutes
+from testprotocols.syslog_config import SyslogConfig
+from testprotocols.threat_prevention import ThreatPrevention
+from testprotocols.traffic_shaping import TrafficShaping
+from testprotocols.wan_link_admin import WanLinkAdmin
+
+
+@runtime_checkable
+class SdwanRouterDevice(BaseDeviceProtocol, Protocol):
+    """SD-WAN router archetype — branch / edge router with policy-based path selection.
+
+    Combines a generic routing read surface, WAN link administration (forced
+    link up/down — a host-substrate lever this Linux twin *can* exercise),
+    SD-WAN policy management (path / app steering), IP interface management,
+    packet capture, NAT, and connection tracking — the full set of L3 levers
+    a test needs to exercise SD-WAN behaviour end to end. Traffic impairment (netem) is on the
+    TrafficControllerDevice archetype — a separate device sitting between the
+    router and its WAN peers — not on the router itself; see
+    SPLITS.md for the rationale.
+    """
+
+    routing: Router
+    wan_admin: WanLinkAdmin
+    static_routes: StaticRoutes
+    bgp: Bgp
+    sdwan_policy: SdwanPolicyManager
+    ip_interface: IpInterface
+    pcap: PcapCapture
+    nat: Nat
+    conntrack: Conntrack
+
+
+register_device_type("linux_sdwan_router", SdwanRouterDevice)
+
+
+@runtime_checkable
+class SdwanApplianceDevice(BaseDeviceProtocol, Protocol):
+    """Managed SD-WAN **appliance** archetype — vendor-neutral.
+
+    The capability surface a cloud-/controller-managed SD-WAN appliance exposes
+    through its management API — satisfiable by any vendor's driver. Distinct
+    from ``SdwanRouterDevice`` (the Linux digital twin, ``linux_sdwan_router``):
+    an appliance is driven by an API, not a shell, so the host substrate
+    capabilities — ``conntrack``, ``pcap``, ``ip_interface``, and the iptables
+    ``nat`` — are deliberately **not** here; they remain on the twin. Packet
+    capture is the TrafficControllerDevice's job (see SPLITS.md), not the
+    appliance's.
+
+    Firewall is split by layer (``l3_firewall`` / ``l7_firewall``) and content
+    filtering is its own surface; NAT here is the appliance's 1:1 / 1:Many /
+    port-forwarding (``appliance_nat``), not the host iptables primitives.
+    Site-to-site VPN overlay participation — role, hubs, advertised subnets,
+    peer status — is the ``vpn`` surface; the overlay's firewall rules stay on
+    ``l3_firewall``. Forced link-down (``wan_admin``) is likewise absent: an
+    API-managed appliance cannot admin-down its own uplink, so ``routing`` here
+    is the read-only surface and link administration stays on the twin.
+    """
+
+    routing: Router
+    static_routes: StaticRoutes
+    bgp: Bgp
+    sdwan_policy: SdwanPolicyManager
+    vpn: SiteToSiteVpn
+    traffic_shaping: TrafficShaping
+    l3_firewall: L3Firewall
+    l7_firewall: L7Firewall
+    content_filtering: ContentFiltering
+    appliance_nat: ApplianceNat
+    security: ThreatPrevention
+    uplinks: ApplianceUplinks
+    lan: ApplianceVlans
+    syslog: SyslogConfig
+
+
+register_device_type("sdwan_appliance", SdwanApplianceDevice)

testprotocols/devices/switch.py

@@ -0,0 +1,115 @@
+"""Managed switch device archetypes — vendor-neutral.
+
+``L2Switch`` is the managed access switch: the capability surface an
+API/controller-managed switch exposes, satisfiable by any vendor's driver.
+Host-substrate levers (conntrack, pcap, ip_interface, nat, packet_filter,
+firewall_zones, wan_admin) are deliberately absent — a switch is not a Linux
+host. See docs/architecture/l2-switch-protocol-design.md.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.bgp import Bgp
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.discovery import Discovery
+from testprotocols.first_hop_security import FirstHopSecurity
+from testprotocols.gateway_redundancy import GatewayRedundancy
+from testprotocols.interface_dhcp import InterfaceDhcp
+from testprotocols.link_aggregation import LinkAggregation
+from testprotocols.mac_table import MacTable
+from testprotocols.ntp_config import NtpConfig
+from testprotocols.ospf import Ospf
+from testprotocols.port_poe import PortPoe
+from testprotocols.port_security import PortSecurity
+from testprotocols.port_status import PortStatus
+from testprotocols.radius_client import RadiusClient
+from testprotocols.routed_interfaces import RoutedInterfaces
+from testprotocols.routing_read import RoutingRead
+from testprotocols.spanning_tree import SpanningTree
+from testprotocols.static_routes import StaticRoutes
+from testprotocols.storm_control import StormControl
+from testprotocols.switch_acl import SwitchAcl
+from testprotocols.switch_ports import SwitchPorts
+from testprotocols.switch_qos import SwitchQos
+from testprotocols.switch_vlans import SwitchVlans
+from testprotocols.syslog_config import SyslogConfig
+
+
+@runtime_checkable
+class L2Switch(BaseDeviceProtocol, Protocol):
+    """Managed access switch archetype — vendor-neutral.
+
+    Composes the shared L2 capability layer. ``radius`` and ``syslog`` are reused
+    as-is; ``first_hop_security`` and ``ntp`` are net-new baseline capabilities.
+    The sibling ``L3Switch`` (separate doc) composes this set plus an L3 layer as
+    a strict superset.
+    Host-substrate levers (conntrack, pcap, ip_interface, nat, packet_filter,
+    firewall_zones, wan_admin) are deliberately absent — a switch is API/controller-managed,
+    not a Linux host.
+    """
+
+    switch_ports: SwitchPorts
+    switch_vlans: SwitchVlans
+    spanning_tree: SpanningTree
+    link_aggregation: LinkAggregation
+    port_poe: PortPoe
+    port_security: PortSecurity
+    radius: RadiusClient
+    first_hop_security: FirstHopSecurity
+    storm_control: StormControl
+    switch_acl: SwitchAcl
+    discovery: Discovery
+    mac_table: MacTable
+    port_status: PortStatus
+    switch_qos: SwitchQos
+    syslog: SyslogConfig
+    ntp: NtpConfig
+
+
+register_device_type("managed_switch_l2", L2Switch)
+
+
+@runtime_checkable
+class L3Switch(L2Switch, Protocol):
+    """Managed distribution switch — strict superset of L2Switch plus an L3 layer.
+
+    Inherits the full L2 capability layer via Protocol inheritance and adds
+    routed interfaces, static routes, RIB read, OSPF, per-interface DHCP, and
+    gateway redundancy. Scope is the default VRF (multi-VRF deferred, GAPS.md).
+    BGP is on the L3SwitchRouted tier (it fails the L3 majority bar).
+    Host-substrate levers (conntrack, pcap, ip_interface, nat, packet_filter,
+    firewall_zones, wan_admin) are deliberately absent — same exclusion as
+    ``L2Switch``. The WAN-edge uplink-admin surface (``wan_admin`` / full
+    ``Router`` write layer) is also excluded: an API-managed switch cannot
+    admin-down its own uplinks, so the RIB surface here is the read-only
+    ``routing_read`` / ``RouteEntry`` view, not the router's write surface.
+    """
+
+    routed_interfaces: RoutedInterfaces
+    static_routes: StaticRoutes
+    routing_read: RoutingRead
+    ospf: Ospf
+    interface_dhcp: InterfaceDhcp
+    gateway_redundancy: GatewayRedundancy
+
+
+register_device_type("managed_switch_l3", L3Switch)
+
+
+@runtime_checkable
+class L3SwitchRouted(L3Switch, Protocol):
+    """L3Switch plus BGP — the routed-distribution tier.
+
+    BGP is absent on the cloud design-target and fails the L3 majority bar, so it
+    is a separate tier rather than a mandatory L3Switch attribute. A driver for a
+    BGP-capable switch satisfies this; the registration isinstance-gate flags a
+    missing bgp at startup.
+    """
+
+    bgp: Bgp
+
+
+register_device_type("managed_switch_l3_routed", L3SwitchRouted)