refactor: ports ABC→Protocol, session restore logging, narrower exception handling

- Convert all port interfaces from ABC to runtime_checkable Protocol
  (structural typing per documented architecture)
- Add logging.warning for failed layer restores in session load
- Narrow except Exception to specific types in satellite table computation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: planet.jeroen

packages/core/src/humeris/ports/__init__.py

@@ -5,33 +5,30 @@
 
 Adapters implement these to handle different file formats.
 """
-from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 
-class SimulationReader(ABC):
+@runtime_checkable
+class SimulationReader(Protocol):
     """Port for reading simulation template data."""
 
-    @abstractmethod
     def read_simulation(self, path: str) -> dict[str, Any]:
         """Read and parse a simulation file."""
         ...
 
-    @abstractmethod
     def extract_template_entity(self, sim_data: dict, entity_name: str) -> dict:
         """Extract a named entity to use as a template."""
         ...
 
-    @abstractmethod
     def extract_earth_entity(self, sim_data: dict) -> dict:
         """Extract the Earth entity."""
         ...
 
 
-class SimulationWriter(ABC):
+@runtime_checkable
+class SimulationWriter(Protocol):
     """Port for writing simulation output data."""
 
-    @abstractmethod
     def write_simulation(self, sim_data: dict, path: str) -> None:
         """Write simulation data to output file."""
         ...

packages/core/src/humeris/ports/export.py

@@ -6,16 +6,16 @@
 Adapters implement this to export satellite positions in various formats
 (CSV, GeoJSON, etc.).
 """
-from abc import ABC, abstractmethod
 from datetime import datetime
+from typing import Protocol, runtime_checkable
 
 from humeris.domain.constellation import Satellite
 
 
-class SatelliteExporter(ABC):
+@runtime_checkable
+class SatelliteExporter(Protocol):
     """Port for exporting satellite data to file."""
 
-    @abstractmethod
     def export(
         self,
         satellites: list[Satellite],

packages/core/src/humeris/ports/orbital_data.py

@@ -5,29 +5,25 @@
 
 Adapters handle the actual HTTP/API calls.
 """
-from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 
-class OrbitalDataSource(ABC):
+@runtime_checkable
+class OrbitalDataSource(Protocol):
     """Port for fetching orbital element data from external sources."""
 
-    @abstractmethod
     def fetch_group(self, group_name: str) -> list[dict[str, Any]]:
         """Fetch OMM records for a named satellite group."""
         ...
 
-    @abstractmethod
     def fetch_by_name(self, name: str) -> list[dict[str, Any]]:
         """Fetch OMM records matching a satellite name."""
         ...
 
-    @abstractmethod
     def fetch_by_catnr(self, catalog_number: int) -> list[dict[str, Any]]:
         """Fetch OMM record for a NORAD catalog number."""
         ...
 
-    @abstractmethod
     def fetch_satellites(self, group: str | None = None,
                         name: str | None = None,
                         catnr: int | None = None) -> list:

packages/pro/src/humeris/adapters/viewer_server.py

@@ -1234,12 +1234,12 @@ def get_satellite_table(self, layer_id: str) -> dict[str, Any]:
                 plane = idx // sats_per_plane if sats_per_plane > 0 else 0
                 try:
                     beta_deg = compute_beta_angle(state.raan_rad, state.inclination_rad, self.epoch)
-                except Exception:
+                except (ValueError, ArithmeticError, ZeroDivisionError):
                     beta_deg = 0.0
                 try:
                     es = compute_eclipse_statistics(state, self.epoch, _DEFAULT_DURATION, _DEFAULT_STEP)
                     eclipse_pct = round(es.eclipse_fraction * 100.0, 1)
-                except Exception:
+                except (ValueError, ArithmeticError, ZeroDivisionError):
                     eclipse_pct = 0.0
                 rows.append({
                     "_sat_idx": idx,
@@ -1385,7 +1385,8 @@ def _restore_layers(self, layers_data: list[dict[str, Any]]) -> int:
                     )
                     restored_layers.append(layer_id)
                     restored += 1
-                except (KeyError, TypeError, ValueError):
+                except (KeyError, TypeError, ValueError) as e:
+                    logging.warning("Failed to restore layer %r: %s", layer_data.get("name", "?"), e)
                     restored_layers.append("")
             else:
                 restored_layers.append("")
@@ -1412,8 +1413,8 @@ def _restore_layers(self, layers_data: list[dict[str, Any]]) -> int:
                 )
                 restored_layers[idx] = gs_lid
                 restored += 1
-            except (KeyError, TypeError, ValueError):
-                pass
+            except (KeyError, TypeError, ValueError) as e:
+                logging.warning("Failed to restore ground station %r: %s", params.get("name", "?"), e)
 
         # Pass 2: Restore analysis layers using source constellation reference
         for idx, layer_data in enumerate(layers_data):
@@ -1451,8 +1452,8 @@ def _restore_layers(self, layers_data: list[dict[str, Any]]) -> int:
                     sat_names=source_sat_names,
                 )
                 restored += 1
-            except (KeyError, TypeError, ValueError, ArithmeticError):
-                pass
+            except (KeyError, TypeError, ValueError, ArithmeticError) as e:
+                logging.warning("Failed to restore analysis layer %r: %s", layer_data.get("name", "?"), e)
 
         return restored