Promote gateway real-internet mode & service_mirrors to experimental

### Motivation
- The gateway nftables policies and mirrored-mode operator output are now wired, so `gateway_portal.real_internet.mode` and `gateway_portal.real_internet.service_mirrors` should be represented as `experimental` rather than `unsupported` in the feature-state registry and docs.
- Tests and CLI validation must reflect that mirrored mode validates with a warning instead of failing alpha validation, while truly unsupported flags remain CI-failing.

### Description
- Update feature-state registry in `netengine/spec/feature_state.py` to mark `gateway_portal.real_internet.mode` and `gateway_portal.real_internet.service_mirrors` as `experimental` and add explanatory caveats.
- Update documentation rows in `docs/spec-alpha-support.md` and `docs/support-matrix.md` to document the promoted experimental state and caveats about remaining real-host integration and DNS aliasing.
- Adjust CLI/tests in `tests/test_cli.py` so a spec with `gateway_portal.real_internet.mode: mirrored` validates successfully with `--explain` (shows a warning) and change the JSON CI-failure test to target `upstream_resolver_enabled` which remains `unsupported`.
- Adjust spec parsing test in `tests/test_spec_parsing.py` to assert the loader logs an experimental warning for mirrored gateway mode instead of raising `SpecLoadError`.

### Testing
- Ran `poetry run pytest tests/test_spec_parsing.py tests/test_cli.py tests/test_gateway_portal.py tests/test_feature_states.py` and those targeted tests passed.
- Ran the full suite with `poetry run pytest`; the full run completed but showed 2 unrelated integration failures (`TestFullMVPLifecycle.test_full_mvp_lifecycle` returned `401` for reload and `TestHealthRoute.test_health_does_not_leak_last_error_detail` exposed `last_error`) that pre-existed this change.
- No new regressions observed in gateway rule generation or unit tests covering gateway portal behavior.

Author: aidankhogg

docs/netengines-spec-v1.yaml

@@ -447,11 +447,13 @@ gateway_portal:
     # custom    — explicit rule list (use when presets don't fit)
 
     # Required if mode: mirrored
+    # Alpha: in_world_service must be an IPv4 address because gateway rules
+    # render nftables ip daddr allowlists; DNS aliasing for names is planned.
     # service_mirrors:
     #   - real_hostname: s3.amazonaws.com
-    #     in_world_service: storage.platform.internal
+    #     in_world_service: 10.0.0.11
     #   - real_hostname: github.com
-    #     in_world_service: gitea.acme.internal
+    #     in_world_service: 10.0.1.20
 
     # Required if mode: custom
     # rules: []

docs/spec-alpha-support.md

@@ -27,7 +27,7 @@ Feature states:
 | `pki.ocsp_enabled` | `experimental` | `false` | `netengine.handlers.pki_handler`, `netengine.handlers.phase_pki` | step-ca OCSP config is injected and the responder URL is published in Phase 3 output; responder lifecycle/verification is hardened in CI e2e. |
 | `pki.rotation_policy` | `experimental` | `{enabled: true, default_interval_hours: 24, default_warning_days: 30, cert_type_overrides: {}}` | `netengine.handlers.phase_pki`, `netengine.workers.pki_cert_rotation_worker`, `netengine.api.routes` | Wired from the spec into worker registration and live-reloaded from runtime state; policy shape and cert-type semantics may change during alpha. |
 | `gateway_portal.real_internet.mode` | `experimental` | `isolated` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Isolated, shadowed, mirrored, and exposed nftables policies are wired; real-host integration remains alpha. |
-| `gateway_portal.real_internet.service_mirrors` | `experimental` | `[]` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Mirrored-mode allowlists and operator output are wired; automatic DNS aliasing for real hostnames remains alpha. |
+| `gateway_portal.real_internet.service_mirrors` | `experimental` | `[]` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Mirrored-mode allowlists and operator output are wired; `in_world_service` must be an IPv4 address until automatic DNS aliasing for real hostnames lands. |
 | `gateway_portal.real_internet.upstream_resolver_enabled` | `unsupported` | `false` | `netengine.spec.loader` | Upstream resolver forwarding is not implemented. |
 | `gateway_portal.cross_world.mode` | `unsupported` | `none` | `netengine.spec.loader` | Cross-world federation is not implemented. |
 | `gateway_portal.cross_world.peers` | `unsupported` | `[]` | `netengine.spec.loader` | Cross-world peer provisioning is not implemented. |

docs/support-matrix.md

@@ -27,7 +27,7 @@ Feature states:
 | `pki.ocsp_enabled` | `unsupported` | `false` | `netengine.handlers.pki_handler`, `netengine.handlers.phase_pki` | Handler code can inject OCSP-related step-ca config and report a URL, but responder deployment/verification is incomplete and active use is unsupported in alpha validation. |
 | `pki.rotation_policy` | `experimental` | `{enabled: true, default_interval_hours: 24, default_warning_days: 30, cert_type_overrides: {}}` | `netengine.handlers.phase_pki`, `netengine.workers.pki_cert_rotation_worker`, `netengine.api.routes` | Wired from the spec into worker registration and live-reloaded from runtime state; policy shape and cert-type semantics may change during alpha. |
 | `gateway_portal.real_internet.mode` | `experimental` | `isolated` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Isolated, shadowed, mirrored, and exposed nftables policies are wired; real-host integration remains alpha. |
-| `gateway_portal.real_internet.service_mirrors` | `experimental` | `[]` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Mirrored-mode allowlists and operator output are wired; automatic DNS aliasing for real hostnames remains alpha. |
+| `gateway_portal.real_internet.service_mirrors` | `experimental` | `[]` | `netengine.handlers.gateway_handler`, `netengine.handlers.gateway_portal_handler`, `netengine.spec.loader` | Mirrored-mode allowlists and operator output are wired; `in_world_service` must be an IPv4 address until automatic DNS aliasing for real hostnames lands. |
 | `gateway_portal.real_internet.upstream_resolver_enabled` | `unsupported` | `false` | `netengine.spec.loader` | Upstream resolver forwarding is not implemented. |
 | `gateway_portal.cross_world.mode` | `unsupported` | `none` | `netengine.spec.loader` | Cross-world federation is not implemented. |
 | `gateway_portal.cross_world.peers` | `unsupported` | `[]` | `netengine.spec.loader` | Cross-world peer provisioning is not implemented. |

netengine/spec/loader.py

@@ -11,6 +11,7 @@
 
 from netengine.config.loader import ConfigLoader
 from netengine.spec.models import SUPPORTED_SPEC_SCHEMA_VERSIONS, NetEngineSpec
+from netengine.spec.types import GatewayRealInternetMode
 
 logger = logging.getLogger(__name__)
 
@@ -155,6 +156,32 @@ def _cross_validate(spec: NetEngineSpec) -> None:
             if net_a.overlaps(net_b):
                 errors.append(f"subnet overlap: {name_a} ({net_a}) overlaps {name_b} ({net_b})")
 
+    # 5. Mirrored real-internet mode needs explicit IP allowlist targets.
+    # The alpha gateway implementation renders nftables `ip daddr` rules from
+    # service_mirrors, so hostnames would generate invalid nftables policy until
+    # DNS aliasing/resolution is implemented.
+    real_internet = spec.gateway_portal.real_internet
+    if real_internet.mode == GatewayRealInternetMode.MIRRORED:
+        if not real_internet.service_mirrors:
+            errors.append(
+                "gateway_portal.real_internet.service_mirrors: "
+                "at least one service mirror is required when mode is 'mirrored'"
+            )
+    elif real_internet.service_mirrors:
+        errors.append(
+            "gateway_portal.real_internet.service_mirrors: "
+            "service mirrors require real_internet.mode: 'mirrored'"
+        )
+
+    for idx, mirror in enumerate(real_internet.service_mirrors):
+        try:
+            ipaddress.IPv4Address(mirror.in_world_service)
+        except ValueError:
+            errors.append(
+                f"gateway_portal.real_internet.service_mirrors[{idx}].in_world_service: "
+                "must be an IPv4 address for alpha mirrored gateway nftables rules"
+            )
+
     if errors:
         raise SpecLoadError(
             "Spec cross-validation failed:\n" + "\n".join(f"  - {e}" for e in errors)

tests/test_cli.py

@@ -435,7 +435,13 @@ def test_validate_valid_spec_exits_zero() -> None:
 
 def test_validate_experimental_gateway_mode_exits_zero_with_explanation(tmp_path: Path) -> None:
     """Mirrored gateway mode is wired but remains experimental during alpha."""
-    spec_file = _write_cli_validate_spec(tmp_path, gateway_portal__real_internet__mode="mirrored")
+    spec_file = _write_cli_validate_spec(
+        tmp_path,
+        gateway_portal__real_internet__mode="mirrored",
+        gateway_portal__real_internet__service_mirrors=[
+            {"real_hostname": "github.com", "in_world_service": "10.0.1.20"}
+        ],
+    )
 
     result = CliRunner().invoke(cli_main.cli, ["validate", str(spec_file), "--explain"])
 

tests/test_spec_parsing.py

@@ -184,18 +184,76 @@ def test_experimental_gateway_mode_logs_warning_not_raises(self, tmp_path, caplo
         import logging
 
         spec_file = self._write_spec(
-            tmp_path, {"gateway_portal": {"real_internet": {"mode": "mirrored"}}}
+            tmp_path,
+            {
+                "gateway_portal": {
+                    "real_internet": {
+                        "mode": "mirrored",
+                        "service_mirrors": [
+                            {"real_hostname": "github.com", "in_world_service": "10.0.1.20"}
+                        ],
+                    }
+                }
+            },
         )
 
         with caplog.at_level(logging.WARNING, logger="netengine.spec.loader"):
             spec = load_spec(spec_file)
 
         assert spec.gateway_portal.real_internet.mode.value == "mirrored"
+        assert spec.gateway_portal.real_internet.service_mirrors[0].in_world_service == "10.0.1.20"
         assert any(
             "gateway_portal.real_internet.mode is experimental in alpha" in r.message
             for r in caplog.records
         )
 
+    def test_mirrored_gateway_requires_service_mirrors(self, tmp_path) -> None:
+        spec_file = self._write_spec(
+            tmp_path, {"gateway_portal": {"real_internet": {"mode": "mirrored"}}}
+        )
+
+        with pytest.raises(SpecLoadError, match="at least one service mirror is required"):
+            load_spec(spec_file)
+
+    def test_service_mirrors_require_mirrored_gateway_mode(self, tmp_path) -> None:
+        spec_file = self._write_spec(
+            tmp_path,
+            {
+                "gateway_portal": {
+                    "real_internet": {
+                        "service_mirrors": [
+                            {"real_hostname": "github.com", "in_world_service": "10.0.1.20"}
+                        ]
+                    }
+                }
+            },
+        )
+
+        with pytest.raises(SpecLoadError, match="service mirrors require"):
+            load_spec(spec_file)
+
+    def test_service_mirror_targets_must_be_ipv4_for_alpha_nftables(self, tmp_path) -> None:
+        spec_file = self._write_spec(
+            tmp_path,
+            {
+                "gateway_portal": {
+                    "real_internet": {
+                        "mode": "mirrored",
+                        "service_mirrors": [
+                            {
+                                "real_hostname": "github.com",
+                                "in_world_service": "gitea.acme.internal",
+                            }
+                        ],
+                    }
+                }
+            },
+        )
+
+        with pytest.raises(SpecLoadError, match="must be an IPv4 address"):
+            load_spec(spec_file)
+
+
     def test_experimental_profile_field_logs_warning_not_raises(self, tmp_path, caplog) -> None:
         import logging