fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/foundation_adoption_host.py

@@ -0,0 +1,157 @@
+"""Bind a verified Foundation adoption to managed-host kit preparation."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.deployment_kit import DeploymentKit
+from fdai_deployment_cli.foundation_adoption_evidence import (
+    validate_foundation_adoption_receipt,
+)
+from fdai_deployment_cli.private_output import read_private_bytes
+from fdai_deployment_cli.contracts import load_json_object
+from fdai_deployment_cli.target import compute_target_binding
+
+_COMMIT = re.compile(r"[0-9a-f]{40}")
+_GUID = re.compile(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}")
+
+
+@dataclass(frozen=True, slots=True)
+class FoundationHostAdoption:
+    """Current application source and optional no-effect adoption evidence."""
+
+    source_commit: str
+    digest: str
+    receipt: dict[str, Any] | None
+
+    def require_kit(self, kit: DeploymentKit) -> None:
+        """Require one verified kit to match the selected application revision."""
+
+        if kit.source_commit != self.source_commit:
+            raise ValueError("Foundation and deployment kit source revisions differ")
+        if self.receipt is not None and (
+            self.receipt.get("kit_manifest_digest") != kit.verification.manifest_digest
+            or self.receipt.get("runtime_release_digest") != kit.runtime.digest
+        ):
+            raise ValueError("Foundation adoption differs from the verified deployment kit")
+
+    def require_context(self, context: dict[str, Any]) -> None:
+        """Require retained host preparation to preserve the exact adoption."""
+
+        if (
+            context.get("source_commit") != self.source_commit
+            or context.get("foundation_adoption_digest", "") != self.digest
+            or (
+                self.receipt is not None
+                and (
+                    context.get("kit_manifest_digest") != self.receipt.get("kit_manifest_digest")
+                    or context.get("runtime_release_digest")
+                    != self.receipt.get("runtime_release_digest")
+                )
+            )
+        ):
+            raise ValueError("standalone host retained Foundation adoption differs")
+
+
+@dataclass(frozen=True, slots=True)
+class FoundationHostContext:
+    """Verified target, runner identity, and optional adoption."""
+
+    subscription_id: str
+    tenant_id: str
+    target_binding: str
+    client_id: str
+    principal_id: str
+    adoption: FoundationHostAdoption
+
+    def login(
+        self,
+        operation: Callable[[str, str, str, str, Path], None],
+        work_dir: Path,
+    ) -> None:
+        """Run the existing managed-identity login with verified target fields."""
+
+        operation(
+            self.subscription_id,
+            self.tenant_id,
+            self.client_id,
+            self.principal_id,
+            work_dir,
+        )
+
+
+def load_foundation_host_context(
+    path: Path | None,
+    *,
+    handoff: dict[str, Any],
+    runner: dict[str, Any],
+) -> FoundationHostContext:
+    """Load the target and adoption fields needed by managed-host preparation."""
+
+    subscription_id = _guid(handoff, "subscription_id")
+    tenant_id = _guid(handoff, "tenant_id")
+    target_binding = compute_target_binding(
+        tenant_id=tenant_id,
+        subscription_id=subscription_id,
+    )
+    return FoundationHostContext(
+        subscription_id=subscription_id,
+        tenant_id=tenant_id,
+        target_binding=target_binding,
+        client_id=_guid(runner, "client_id"),
+        principal_id=_guid(runner, "principal_id"),
+        adoption=load_foundation_host_adoption(
+            path,
+            handoff=handoff,
+            target_binding=target_binding,
+        ),
+    )
+
+
+def load_foundation_host_adoption(
+    path: Path | None,
+    *,
+    handoff: dict[str, Any],
+    target_binding: str,
+) -> FoundationHostAdoption:
+    """Load optional adoption evidence while preserving the original handoff."""
+
+    foundation_source_commit = handoff.get("source_commit")
+    if (
+        not isinstance(foundation_source_commit, str)
+        or _COMMIT.fullmatch(foundation_source_commit) is None
+    ):
+        raise ValueError("Foundation handoff source revision is invalid")
+    if path is None:
+        return FoundationHostAdoption(
+            source_commit=foundation_source_commit,
+            digest="",
+            receipt=None,
+        )
+    raw = read_private_bytes(path, max_bytes=65_536)
+    receipt = load_json_object(raw, label="Foundation adoption")
+    application_source_commit = str(receipt.get("application_source_commit", ""))
+    digest = validate_foundation_adoption_receipt(
+        receipt,
+        handoff=handoff,
+        target_binding=target_binding,
+        application_source_commit=application_source_commit,
+        kit_manifest_digest=str(receipt.get("kit_manifest_digest", "")),
+        runtime_release_digest=str(receipt.get("runtime_release_digest", "")),
+    )
+    return FoundationHostAdoption(
+        source_commit=application_source_commit,
+        digest=digest,
+        receipt=receipt,
+    )
+
+
+def _guid(value: dict[str, Any], field: str) -> str:
+    item = value.get(field)
+    if not isinstance(item, str) or _GUID.fullmatch(item) is None:
+        raise ValueError(f"{field} is not a canonical GUID")
+    return item

fdai_deployment_cli/foundation_adoption_transport.py

@@ -0,0 +1,51 @@
+"""Transfer Foundation context and optional adoption evidence to the managed host."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+class PrivateTransport(Protocol):
+    """Minimum managed-host file transport used by Foundation staging."""
+
+    def copy_to(self, source: Path, destination: str, *, timeout: int) -> None:
+        """Copy one validated private file."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class FoundationTransport:
+    """Remote Foundation input paths and optional host CLI arguments."""
+
+    handoff: str
+    entra: str | None
+    adoption_arguments: tuple[str, ...]
+
+
+def stage_foundation_context(
+    tunnel: PrivateTransport,
+    handoff_path: Path,
+    remote_handoff: str,
+    entra_path: Path | None,
+    remote_entra: str | None,
+    remote_root: str,
+) -> FoundationTransport:
+    """Copy exact handoff inputs and return optional adoption arguments."""
+
+    tunnel.copy_to(handoff_path, remote_handoff, timeout=120)
+    if (entra_path is None) != (remote_entra is None):
+        raise ValueError("Entra transport inputs must be selected together")
+    if entra_path is not None and remote_entra is not None:
+        tunnel.copy_to(entra_path, remote_entra, timeout=120)
+    adoption = handoff_path.parent.parent / "foundation-adoption-receipt.json"
+    if not adoption.exists() and not adoption.is_symlink():
+        return FoundationTransport(remote_handoff, remote_entra, ())
+    remote_adoption = f"{remote_root}/foundation-adoption.json"
+    tunnel.copy_to(adoption, remote_adoption, timeout=120)
+    return FoundationTransport(
+        remote_handoff,
+        remote_entra,
+        ("--foundation-adoption", remote_adoption),
+    )

fdai_deployment_cli/foundation_failure.py

@@ -0,0 +1,72 @@
+"""Describe a failed Foundation attempt without accepting it as handoff or authority."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, NoReturn
+
+from fdai_deployment_cli.private_output import read_private_bytes
+
+_GENERIC = "standalone Foundation orchestration failed; inspect retained status before recovery"
+_IMAGE_INCOMPLETE = (
+    "standalone Foundation orchestration failed at Runner image exact apply (08/15).\n"
+    "Image creation or independent verification is incomplete.\n"
+    "Preserve the work directory and its state, plans, and apply claims. "
+    "A retained claim permits verification only; recovery needs a separately reviewed exact "
+    "plan and new approval."
+)
+
+
+def foundation_failure_summary(
+    path: Path, *, previous: int, source_commit: str, run_binding: str
+) -> str:
+    """Return fixed guidance only for a current, context-matched failed child attempt.
+
+    Call only after the child has exited unsuccessfully. This bounded private read never accepts
+    a success record, returns operational state, prints payload values, or changes execution.
+    Missing, malformed, stale, unreadable, or unrecognized evidence retains the generic failure.
+    """
+    try:
+        value = json.loads(
+            read_private_bytes(path, max_bytes=1_048_576).decode("utf-8"),
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_constant,
+        )
+    except (OSError, ValueError, RecursionError):
+        return _GENERIC
+    if not isinstance(value, dict):
+        return _GENERIC
+    attempt, sequence = value.get("attempt"), value.get("sequence")
+    if (
+        value.get("schema_version") != "fdai.genesis-orchestration-status.v2"
+        or type(attempt) is not int
+        or attempt != previous + 1
+        or type(sequence) is not int
+        or sequence < 1
+        or value.get("source_commit") != source_commit
+        or value.get("target_binding") != run_binding
+        or value.get("mode") != "apply"
+        or value.get("state") not in ("blocked", "failed")
+        or value.get("route") != "private-runner"
+    ):
+        return _GENERIC
+    if (
+        value.get("current_stage") == "runner-image-apply"
+        and value.get("reason_code") == "runner_image_apply_or_verification_failed"
+    ):
+        return _IMAGE_INCOMPLETE
+    return _GENERIC
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate Foundation diagnostic key")
+        result[key] = value
+    return result
+
+
+def _reject_constant(_value: str) -> NoReturn:
+    raise ValueError("nonfinite Foundation diagnostic value")

fdai_deployment_cli/foundation_image.py

@@ -0,0 +1,168 @@
+"""Read-only validation for the exact managed image consumed by Foundation."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+
+from fdai_deployment_cli.contracts import canonical_digest
+
+RunCommand = Callable[..., subprocess.CompletedProcess[str]]
+
+
+def verify_foundation_runner_image(
+    variables: dict[str, object], *, expected_region: str, run: RunCommand = subprocess.run
+) -> str:
+    """Verify exact image provenance through ARM and return a content-free observation digest.
+
+    This read grants no image, Foundation, apply, or readiness authority. Provider output is
+    never returned or included in an error.
+    """
+
+    mode = variables.get("runner_bootstrap_mode", "offline")
+    image_id = variables.get("runner_source_image_id")
+    marketplace_version = variables.get("runner_marketplace_image_version", "")
+    source_commit = variables.get("runner_image_source_commit", variables.get("source_commit"))
+    toolchain_digest = variables.get("runner_image_toolchain_digest")
+    if mode == "online":
+        return _verify_marketplace_image(
+            version=marketplace_version,
+            toolchain_digest=toolchain_digest,
+            expected_region=expected_region,
+            run=run,
+        )
+    if (
+        not isinstance(image_id, str)
+        or not image_id
+        or not isinstance(source_commit, str)
+        or not source_commit
+        or not isinstance(toolchain_digest, str)
+        or not toolchain_digest
+    ):
+        raise ValueError("Foundation runner image provenance input is incomplete")
+    completed = run(
+        [
+            "az",
+            "resource",
+            "show",
+            "--ids",
+            image_id,
+            "--query",
+            "{id:id,type:type,location:location,provisioningState:properties.provisioningState,managedOsType:properties.storageProfile.osDisk.osType,galleryOsType:properties.storageProfile.osDiskImage.operatingSystem,tags:tags}",
+            "--output",
+            "json",
+            "--only-show-errors",
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=60,
+    )
+    if completed.returncode != 0:
+        raise ValueError("Foundation runner image is unavailable")
+    try:
+        observed = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise ValueError("Foundation runner image observation is invalid") from exc
+    if not isinstance(observed, dict):
+        raise TypeError("Foundation runner image observation is invalid")
+    tags = observed.get("tags")
+    image_type = str(observed.get("type", "")).casefold()
+    os_type = observed.get("managedOsType") or observed.get("galleryOsType")
+    if (
+        str(observed.get("id", "")).casefold() != image_id.casefold()
+        or image_type
+        not in {
+            "microsoft.compute/images",
+            "microsoft.compute/galleries/images/versions",
+        }
+        or str(observed.get("location", "")).casefold() != expected_region.casefold()
+        or observed.get("provisioningState") != "Succeeded"
+        or str(os_type).casefold() != "linux"
+        or not isinstance(tags, dict)
+        or tags.get("fdai:source-commit") != source_commit
+        or tags.get("fdai:toolchain-digest") != toolchain_digest
+    ):
+        raise ValueError("Foundation runner image provenance does not match the reviewed input")
+    return canonical_digest(
+        {
+            "schema_version": "fdai.foundation-runner-image-observation.v1",
+            "image_id_digest": canonical_digest(image_id.casefold()),
+            "image_type": image_type,
+            "location": expected_region,
+            "provisioning_state": "Succeeded",
+            "os_type": "Linux",
+            "source_commit": source_commit,
+            "toolchain_digest": toolchain_digest,
+        }
+    )
+
+
+def _verify_marketplace_image(
+    *,
+    version: object,
+    toolchain_digest: object,
+    expected_region: str,
+    run: RunCommand,
+) -> str:
+    if (
+        not isinstance(version, str)
+        or not version
+        or not isinstance(toolchain_digest, str)
+        or not toolchain_digest
+    ):
+        raise ValueError("Foundation Marketplace image input is incomplete")
+    urn = f"Canonical:ubuntu-24_04-lts:server:{version}"
+    completed = run(
+        [
+            "az",
+            "vm",
+            "image",
+            "show",
+            "--location",
+            expected_region,
+            "--urn",
+            urn,
+            "--query",
+            (
+                "{version:name,location:location,"
+                "osType:osDiskImage.operatingSystem,"
+                "hyperVGeneration:hyperVGeneration}"
+            ),
+            "--output",
+            "json",
+            "--only-show-errors",
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=60,
+    )
+    if completed.returncode != 0:
+        raise ValueError("Foundation Marketplace image is unavailable")
+    try:
+        observed = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise ValueError("Foundation Marketplace image observation is invalid") from exc
+    if (
+        not isinstance(observed, dict)
+        or observed.get("version") != version
+        or str(observed.get("location", "")).casefold() != expected_region.casefold()
+        or observed.get("osType") != "Linux"
+        or observed.get("hyperVGeneration") != "V2"
+    ):
+        raise ValueError("Foundation Marketplace image does not match the reviewed input")
+    return canonical_digest(
+        {
+            "schema_version": "fdai.foundation-marketplace-image-observation.v1",
+            "publisher": "Canonical",
+            "offer": "ubuntu-24_04-lts",
+            "sku": "server",
+            "version": version,
+            "region": expected_region,
+            "os_type": "Linux",
+            "hyper_v_generation": "V2",
+            "toolchain_digest": toolchain_digest,
+        }
+    )

fdai_deployment_cli/foundation_input.py

@@ -0,0 +1,235 @@
+"""Secret-free inputs for planning the ARM-only genesis foundation."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from pathlib import Path
+
+from fdai_deployment_cli.plan_input import PlanInputContext, read_plan_input, write_plan_input
+from fdai_deployment_cli.target import compute_target_binding
+
+_STRINGS = {
+    "workload": r"[a-z][a-z0-9]{1,11}",
+    "region_short": r"[a-z][a-z0-9]{1,7}",
+    "state_storage_account_name": r"[a-z0-9]{3,24}",
+    "runner_ssh_public_key": r"ssh-(?:ed25519|rsa) [A-Za-z0-9+/]+={0,2}",
+    "source_commit": r"[0-9a-f]{40}",
+    "run_digest": r"[0-9a-f]{64}",
+    "foundation_context_digest": r"[0-9a-f]{64}",
+    "runner_image_toolchain_digest": r"[0-9a-f]{64}",
+}
+_NETWORKS = ("ops_address_space", "runner_subnet_prefix", "pe_subnet_prefix")
+_RUNNER_IMAGE_NETWORKS = (
+    "build_address_space",
+    "build_subnet_prefix",
+    "firewall_subnet_prefix",
+    "firewall_management_subnet_prefix",
+)
+_OPTIONAL_STRINGS = {
+    "application_workload": r"[a-z][a-z0-9]{1,11}",
+    "runner_image_source_commit": r"[0-9a-f]{40}",
+    "runner_image_verified_source_commit": r"[0-9a-f]{40}",
+    "runner_image_run_digest": r"[0-9a-f]{64}",
+    "runner_image_receipt_digest": r"[0-9a-f]{64}",
+}
+_REQUIRED = (
+    frozenset(_STRINGS)
+    | frozenset(_NETWORKS)
+    | {
+        "tenant_id",
+        "subscription_id",
+        "target_binding",
+        "region",
+        "runner_source_image_id",
+    }
+)
+_OPTIONAL = frozenset(
+    {
+        "state_retention_days",
+        "operations_public_ip_tags",
+        "runner_vm_size",
+        "runner_admin_username",
+        "runner_parallelism",
+        "enable_public_egress",
+        "enable_bastion",
+        "bastion_subnet_prefix",
+        "execution_transport",
+        "runner_bootstrap_mode",
+        "runner_marketplace_image_version",
+        *_OPTIONAL_STRINGS,
+        *_RUNNER_IMAGE_NETWORKS,
+    }
+)
+_UUID = r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}"
+_SEGMENT = r"[A-Za-z0-9._()-]+"
+_IMAGE = re.compile(
+    rf"/subscriptions/{_UUID}/resourceGroups/{_SEGMENT}/providers/Microsoft\.Compute/"
+    rf"(?:images/{_SEGMENT}|galleries/{_SEGMENT}/images/{_SEGMENT}/versions/[0-9]+\.[0-9]+\.[0-9]+)",
+    re.IGNORECASE,
+)
+
+
+def snapshot_foundation_input(
+    source: Path,
+    destination: Path,
+    *,
+    expected_target_binding: str,
+    expected_region: str,
+    expected_environment: str,
+    preserve_runner_image_networks: bool = False,
+) -> PlanInputContext:
+    """Snapshot only reviewed foundation inputs; never accept credentials.
+
+    This validates a dry-run input, not image trust, network policy, source
+    eligibility, approval, or existing-resource adoption. The protected executor
+    must independently bind those before applying a separately sealed plan.
+    """
+
+    values = read_plan_input(source)
+    if not _REQUIRED <= values.keys() or values.keys() - (_REQUIRED | _OPTIONAL):
+        raise ValueError("foundation plan input fields do not match the secret-free schema")
+    tenant = values["tenant_id"]
+    subscription = values["subscription_id"]
+    if (
+        not isinstance(tenant, str)
+        or not isinstance(subscription, str)
+        or not tenant
+        or not subscription
+    ):
+        raise ValueError("foundation plan target values MUST be strings")
+    binding = compute_target_binding(tenant_id=tenant, subscription_id=subscription)
+    if values["target_binding"] != binding or binding != expected_target_binding:
+        raise ValueError("foundation plan target binding does not match the profile")
+    if values["region"] != expected_region:
+        raise ValueError("foundation plan region does not match the profile")
+    if expected_environment not in {"dev", "staging", "prod"}:
+        raise ValueError("foundation plan environment is unsupported")
+    for name, pattern in _STRINGS.items():
+        value = values[name]
+        if not isinstance(value, str) or re.fullmatch(pattern, value) is None:
+            raise ValueError(f"foundation plan {name} is invalid")
+    for name, pattern in _OPTIONAL_STRINGS.items():
+        value = values.get(name)
+        if value is not None and (
+            not isinstance(value, str) or re.fullmatch(pattern, value) is None
+        ):
+            raise ValueError(f"foundation plan {name} is invalid")
+    image = values["runner_source_image_id"]
+    marketplace_version = values.get("runner_marketplace_image_version", "")
+    mode = values.get("runner_bootstrap_mode", "offline")
+    if mode not in {"online", "offline"}:
+        raise ValueError("foundation plan runner bootstrap mode is invalid")
+    if mode == "online":
+        if (
+            image != ""
+            or not isinstance(marketplace_version, str)
+            or re.fullmatch(r"[0-9]+(?:\.[0-9]+)+", marketplace_version) is None
+        ):
+            raise ValueError("online foundation requires an exact Marketplace image version")
+    elif not isinstance(image, str) or _IMAGE.fullmatch(image) is None or marketplace_version != "":
+        raise ValueError("offline foundation requires an exact managed image or gallery version")
+    _validate_networks(values)
+    _validate_runner_image_networks(values)
+    if values.get("operations_public_ip_tags", {}) not in (
+        {},
+        {"FirstPartyUsage": "/Unprivileged"},
+    ):
+        raise ValueError("foundation plan operations public IP policy tags are unsupported")
+    retention = values.get("state_retention_days", 30)
+    if type(retention) is not int or not 1 <= retention <= 365:
+        raise ValueError("foundation plan retention MUST be an integer from 1 through 365")
+    size = values.get("runner_vm_size", "Standard_D8ds_v5")
+    if not isinstance(size, str) or re.fullmatch(r"Standard_[A-Za-z0-9_]{1,64}", size) is None:
+        raise ValueError("foundation plan runner size is invalid")
+    username = values.get("runner_admin_username", "fdairunner")
+    if not isinstance(username, str) or re.fullmatch(r"[a-z_][a-z0-9_-]{0,30}", username) is None:
+        raise ValueError("foundation plan runner username is invalid")
+    parallelism = values.get("runner_parallelism", 1)
+    if type(parallelism) is not int or not 1 <= parallelism <= 5:
+        raise ValueError("foundation plan runner parallelism MUST be an integer from 1 through 5")
+    if values.get("execution_transport", "manual") != "manual":
+        raise ValueError("foundation plan execution transport must be manual")
+    if type(values.get("enable_public_egress", False)) is not bool:
+        raise ValueError("foundation plan public egress selection MUST be boolean")
+    enable_bastion = values.get("enable_bastion", False)
+    if type(enable_bastion) is not bool:
+        raise ValueError("foundation plan Bastion selection MUST be boolean")
+    _validate_bastion_network(values, enabled=enable_bastion)
+    excluded = {"target_binding"}
+    if not preserve_runner_image_networks:
+        excluded.update(_RUNNER_IMAGE_NETWORKS)
+    terraform_values = {key: value for key, value in values.items() if key not in excluded}
+    terraform_values.setdefault("runner_bootstrap_mode", "offline")
+    terraform_values.setdefault("runner_marketplace_image_version", "")
+    terraform_values["env"] = expected_environment
+    write_plan_input(destination, terraform_values)
+    return PlanInputContext(subscription_id=subscription, tenant_id=tenant)
+
+
+def _validate_networks(values: dict[str, object]) -> None:
+    networks: list[ipaddress.IPv4Network] = []
+    for name in _NETWORKS:
+        value = values[name]
+        if not isinstance(value, str) or "/" not in value:
+            raise ValueError("foundation network prefixes MUST be IPv4 CIDRs")
+        try:
+            network = ipaddress.IPv4Network(value)
+        except ValueError:
+            raise ValueError("foundation network prefixes MUST be canonical IPv4 CIDRs") from None
+        networks.append(network)
+    hub, runner, endpoint = networks
+    if not runner.subnet_of(hub) or not endpoint.subnet_of(hub) or runner.overlaps(endpoint):
+        raise ValueError("foundation subnets MUST be disjoint and contained in the ops network")
+
+
+def _validate_bastion_network(values: dict[str, object], *, enabled: bool) -> None:
+    value = values.get("bastion_subnet_prefix")
+    if not enabled:
+        if value is not None:
+            raise ValueError("foundation Bastion subnet requires Bastion to be enabled")
+        return
+    if not isinstance(value, str) or "/" not in value:
+        raise ValueError("foundation Bastion requires an IPv4 /26-or-larger subnet")
+    try:
+        bastion = ipaddress.IPv4Network(value)
+        hub = ipaddress.IPv4Network(str(values["ops_address_space"]))
+        runner = ipaddress.IPv4Network(str(values["runner_subnet_prefix"]))
+        endpoint = ipaddress.IPv4Network(str(values["pe_subnet_prefix"]))
+    except ValueError:
+        raise ValueError("foundation Bastion subnet MUST be a canonical IPv4 CIDR") from None
+    if (
+        bastion.prefixlen > 26
+        or not bastion.subnet_of(hub)
+        or bastion.overlaps(runner)
+        or bastion.overlaps(endpoint)
+    ):
+        raise ValueError("foundation Bastion subnet MUST be disjoint, contained, and at least /26")
+
+
+def _validate_runner_image_networks(values: dict[str, object]) -> None:
+    present = set(_RUNNER_IMAGE_NETWORKS) & values.keys()
+    if not present:
+        return
+    if present != set(_RUNNER_IMAGE_NETWORKS):
+        raise ValueError("runner image network fields MUST be supplied together")
+    try:
+        build, builder, firewall, firewall_management = (
+            ipaddress.IPv4Network(str(values[name])) for name in _RUNNER_IMAGE_NETWORKS
+        )
+        ops = ipaddress.IPv4Network(str(values["ops_address_space"]))
+    except ValueError:
+        raise ValueError("runner image network prefixes MUST be canonical IPv4 CIDRs") from None
+    if (
+        not build.is_private
+        or build.overlaps(ops)
+        or not all(subnet.subnet_of(build) for subnet in (builder, firewall, firewall_management))
+        or builder.overlaps(firewall)
+        or builder.overlaps(firewall_management)
+        or firewall.overlaps(firewall_management)
+        or firewall.prefixlen > 26
+        or firewall_management.prefixlen > 26
+    ):
+        raise ValueError(
+            "runner image subnets MUST be private, disjoint, contained, and policy compatible"
+        )