wip: take over #3900 [Ixt1Hwre]

Author: rjpower

lib/iris/src/iris/cluster/platform/base.py

@@ -440,49 +440,79 @@ def resolve_image(self, image: str, zone: str | None = None) -> str:
         """
         ...
 
-    def discover_controller(self, controller_config: config_pb2.ControllerVmConfig) -> str:
-        """Discover controller address from platform-specific mechanism.
+    def debug_report(self) -> None:
+        """Log diagnostic info about the controller after a failure.
 
-        Returns 'host:port' string. Each platform resolves this differently:
-        - GCP: queries VMs by controller label
-        - Manual: uses static host from config
-        - Local: returns configured address or localhost
+        Override to inspect platform-specific state (e.g. pod termination
+        reason, previous container logs). Default is a no-op.
         """
         ...
 
-    def start_controller(self, config: config_pb2.IrisClusterConfig) -> str:
-        """Start or discover existing controller. Returns address (host:port).
+    def shutdown(self) -> None:
+        """Release platform-owned resources (threads, connections, caches).
 
-        Each remote platform implements its own controller lifecycle:
-        - GCP: creates GCE VM, SSHes in, bootstraps container
-        - Manual: SSHes to configured host, bootstraps container
-        - CoreWeave: kubectl apply ConfigMap + NodePool + Deployment + Service
+        Distinct from terminate() on handles -- shutdown() doesn't destroy
+        cloud resources. It cleans up the Platform object itself.
 
-        Local mode uses LocalCluster directly and does not go through Platform.
+        In LOCAL mode this stops worker threads managed by ThreadContainer.
+        For GCP/Manual this is typically a no-op.
         """
         ...
 
-    def restart_controller(self, config: config_pb2.IrisClusterConfig) -> str:
-        """Restart controller in-place without destroying underlying compute.
+    def resolve_image(self, image: str, zone: str | None = None) -> str:
+        """Resolve a container image reference for this platform's registry.
 
-        Re-runs the bootstrap script on the existing VM/pod to pull the latest
-        image and restart the container. Falls back to stop+start semantics on
-        platforms where in-place restart isn't meaningful (e.g. CoreWeave).
+        On GCP, rewrites ``ghcr.io/`` images to the Artifact Registry remote
+        repo for the given zone's continent.  Other platforms return the image
+        unchanged.
+
+        Args:
+            image: Container image tag (e.g. ``ghcr.io/org/img:v1``).
+            zone: Cloud zone used to select the regional mirror.  Required on
+                GCP when the image starts with ``ghcr.io/``.
+
+        Returns:
+            Resolved image tag ready for ``docker pull``.
         """
         ...
 
-    def stop_controller(self, config: config_pb2.IrisClusterConfig) -> None:
-        """Stop the controller.
 
-        Each remote platform tears down its own controller resources:
-        - GCP: terminates GCE VM
-        - Manual: terminates bootstrap on host
-        - CoreWeave: kubectl delete Deployment + Service + NodePool
+# ============================================================================
+# Controller Lifecycle Protocol
+# ============================================================================
+
+
+class ControllerLifecycle(Protocol):
+    """Controller lifecycle operations, separated from infrastructure provisioning.
+
+    Handles discovery, start, restart, stop, and bulk teardown of the controller
+    process. Each platform provides its own implementation:
+    - GCP/Manual: VM-based lifecycle via vm_lifecycle.py
+    - CoreWeave: K8s Deployment/Service lifecycle via kubectl
+    """
+
+    def discover_controller(self, controller_config: config_pb2.ControllerVmConfig) -> str:
+        """Discover controller address from platform-specific mechanism.
 
-        Local mode uses LocalCluster.close() directly and does not go through Platform.
+        Returns 'host:port' string. Each platform resolves this differently:
+        - GCP: queries VMs by controller label
+        - Manual: uses static host from config
+        - CoreWeave: returns K8s Service DNS name
         """
         ...
 
+    def start_controller(self, config: config_pb2.IrisClusterConfig) -> str:
+        """Start or discover existing controller. Returns address (host:port)."""
+        ...
+
+    def restart_controller(self, config: config_pb2.IrisClusterConfig) -> str:
+        """Restart controller in-place without destroying underlying compute."""
+        ...
+
+    def stop_controller(self, config: config_pb2.IrisClusterConfig) -> None:
+        """Stop the controller and clean up its resources."""
+        ...
+
     def stop_all(
         self,
         config: config_pb2.IrisClusterConfig,
@@ -493,11 +523,6 @@ def stop_all(
 
         When dry_run=True, discovers resources but does not terminate them.
         Returns list of resource names that were (or would be) terminated.
-
-        Each platform implements its own teardown strategy:
-        - GCP/Manual: list_all_slices + terminate each + stop_controller (parallel)
-        - CoreWeave: kubectl delete NodePools + controller resources
-        - Local: terminate slices + stop controller
         """
         ...